Primeros pasos

Introducción

Librería para trabajar con certificados CSD y eFirma (FIEL) del SAT en Node.js y navegadores.

@nodecfdi/credentials es una librería diseñada para trabajar de manera sencilla con los archivos de CSD (Certificado de Sello Digital) y eFirma (antes FIEL) emitidos por el Servicio de Administración Tributaria (SAT) en México.

Con esta librería no es necesario convertir previamente los archivos .cer y .key mediante OpenSSL: puedes utilizarlos exactamente como los entrega el SAT, además de soportar formatos PEM y archivos .pfx (PKCS#12).

Esta librería está inspirada en phpcfdi/credentials para PHP y forma parte del ecosistema de paquetes de NodeCfdi.

¿Qué son el CSD y la eFirma (FIEL)?

  • CSD (Certificado de Sello Digital): Se utiliza específicamente para firmar Comprobantes Fiscales Digitales por Internet (CFDI).
  • eFirma (FIEL / Firma Electrónica Avanzada): Se utiliza para firmar electrónicamente documentos o solicitudes (por ejemplo, autenticarse ante servicios web del SAT o XML-DSig) y tiene validez legal para personas físicas y morales.

Características principales

  • Lectura directa de formatos del SAT: Acepta certificados X.509 en formatos DER (.cer), PEM o DER en Base64, y llaves privadas en PKCS#8 DER (.key), PKCS#8 PEM o PKCS#5 PEM (cifradas o sin cifrar).
  • Firma y verificación criptográfica: Firma cadenas con sha256 (por defecto), sha1, sha384, sha512 o md5, y verifica firmas contra el certificado o la llave pública.
  • Extracción de metadatos fiscales: Obtén fácilmente el RFC, razón social (legalName), sucursal (branchName), número de serie, vigencia (validFrom, validTo, validOn), tipo de certificado (CSD o FIEL) y emisor en formato RFC 4514.
  • Soporte PFX (PKCS#12): Lee archivos .pfx / .p12 para obtener un objeto Credential o exporta un certificado y llave privada a formato PFX.
  • Cambio de contraseña: Recifra o elimina la contraseña de una llave privada en memoria con changePassPhrase().
  • Multiplataforma + CLI: Las clases principales funcionan tanto en Node.js como en navegadores modernos, e incluye la herramienta de línea de comandos nc-credentials.

Requisitos de versión

Entorno / DependenciaVersión requerida
Node.js^22.13.0 || ^24 || ^26 (ESM)
NavegadoresNavegadores modernos (defaults, not IE 11)
Peer Dependencyluxon ^3.7.2

Siguientes pasos

Continúa con la guía de Instalación para agregar @nodecfdi/credentials a tu proyecto.