@nodecfdi/credentials
Library to use eFirma (fiel) and CSD (sellos) from SAT
The documentation of this project is in spanish as this is the natural language for intended audience.
La documentación del proyecto está en español porque ese es el lenguaje principal de los usuarios.
Acerca de @nodecfdi/credentials
Esta librería ha sido creada para poder trabajar con los archivos CSD y FIEL del SAT. De esta forma, se simplifica el proceso de firmar, verificar firma y obtener datos particulares del archivo de certificado así como de la llave pública.
El CSD (Certificado de Sello Digital) es utilizado para firmar Comprobantes Fiscales Digitales.
La FIEL (o eFirma) es utilizada para firmar electrónicamente documentos (generalmente usando XML-SEC) y está reconocida por el gobierno mexicano como una manera de firma legal de una persona física o moral.
Con esta librería no es necesario convertir los archivos generados por el SAT a otro formato, se pueden utilizar tal y como el SAT los entrega.
Esta librería ha sido inspirada por la versión para php https://github.com/phpcfdi/credentials
Inicio rápido
Instala el paquete junto con su dependencia par luxon:
# pnpm
pnpm add @nodecfdi/credentials luxon
# npm
npm install @nodecfdi/credentials luxon
# yarn
yarn add @nodecfdi/credentials luxon
# bun
bun add @nodecfdi/credentials luxon
Abre un certificado (.cer) y llave privada (.key) directamente como los entrega el SAT para consultar datos, firmar y verificar:
import { Buffer } from 'node:buffer';
import { openCredentialFiles } from '@nodecfdi/credentials/node';
// En Node.js puedes abrir archivos locales directamente
const credential = openCredentialFiles(
'ruta/al/certificado.cer',
'ruta/a/la/llave_privada.key',
'contraseña-de-la-llave',
);
console.log(credential.rfc()); // AAA010101AAA
console.log(credential.legalName()); // ACCEM SERVICIOS EMPRESARIALES SC
console.log(credential.isCsd()); // true (o credential.isFiel())
// Firmar una cadena original (devuelve firma en cadena binaria)
const cadenaOriginal = '||4.0|A|1|2026-01-01T12:00:00|...||';
const signatureBinary = credential.sign(cadenaOriginal);
const selloBase64 = Buffer.from(signatureBinary, 'binary').toString('base64');
// Verificar la firma con el certificado
const isValid = credential.verify(cadenaOriginal, signatureBinary);
console.log(isValid); // true
En navegadores o cuando ya tienes el contenido en memoria, utiliza Credential.create(certContents, keyContents, passPhrase) importado desde @nodecfdi/credentials.
Uso por línea de comandos (CLI)
Al instalar el paquete se incluye el ejecutable nc-credentials (o puedes ejecutarlo con npx nc-credentials):
# Obtener datos de un certificado (RFC, razón social, serie, vigencia, etc.)
nc-credentials data --cer certificate.cer
nc-credentials data --cer certificate.cer --json
nc-credentials data --cer certificate.cer --field rfc
nc-credentials data --cer certificate.cer --field legal-name
# Firmar texto o archivo
nc-credentials sign --cer certificate.cer --key private_key.key --password-file password.txt --data "cadena original"
nc-credentials sign --key private_key.key --password-file password.txt --file documento.txt --output firma.b64
# Verificar una firma
nc-credentials verify --cer certificate.cer --data "cadena original" --signature "<firma-base64>"
nc-credentials verify --cer certificate.cer --file documento.txt --signature-file firma.b64
# Exportar a archivo PFX (PKCS#12)
nc-credentials pfx export --cer certificate.cer --key private_key.key --password-file password.txt --output archivo.pfx
Ejecuta nc-credentials --help o nc-credentials <comando> --help para ver todas las opciones disponibles (incluyendo soporte para --pfx, stdin, --encoding y NODECFDI_PASSWORD).
Notas de seguridad y validación:
- Prefiere
--password-fileo la variableNODECFDI_PASSWORDen lugar de--password, que expone la contraseña en la lista de procesos (el CLI emite una advertencia). - Las opciones desconocidas, repetidas, vacías, argumentos sobrantes o valores no permitidos detienen la ejecución indicando el valor inesperado.
- Los archivos de salida (
--output) se crean con permisos0600y no se sobrescriben salvo que uses--force. - Los datos se firman byte a byte (texto en UTF-8);
--encoding binaryrequiere--outputal firmar y--signature-fileal verificar. - Códigos de salida:
0éxito,1error de ejecución o firma inválida,2argumentos inválidos.
Documentación
La documentación está disponible en el sitio web NodeCfdi
Soporte
Puedes obtener soporte abriendo un ticket en Github.
Compatibilidad
Esta librería se mantendrá compatible con al menos la versión con soporte activo de Node más reciente.
También utilizamos Versionado Semántico 2.0.0 por lo que puedes usar esta librería sin temor a romper tu aplicación.
Contribuciones
Las contribuciones con bienvenidas. Por favor lee CONTRIBUTING para más detalles y recuerda revisar el archivo CHANGELOG.
Copyright and License
The @nodecfdi/credentials library is copyright NodeCfdi and licensed for use under the MIT License (MIT). Please see LICENSE for more information.