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,sha512omd5, 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 (CSDoFIEL) y emisor en formato RFC 4514. - Soporte PFX (PKCS#12): Lee archivos
.pfx/.p12para obtener un objetoCredentialo 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 / Dependencia | Versión requerida |
|---|---|
| Node.js | ^22.13.0 || ^24 || ^26 (ESM) |
| Navegadores | Navegadores modernos (defaults, not IE 11) |
| Peer Dependency | luxon ^3.7.2 |
Siguientes pasos
Continúa con la guía de Instalación para agregar @nodecfdi/credentials a tu proyecto.
