npm.io
4.0.0 • Published 19h agoCLI

@nodecfdi/credentials

Licence
MIT
Version
4.0.0
Deps
3
Size
828 kB
Vulns
0
Weekly
0
Stars
17

@nodecfdi/credentials

Source Code Npm Node Version Support Discord Latest Version Software License Build Status Reliability Maintainability Code Coverage Violations Total Downloads

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-file o la variable NODECFDI_PASSWORD en 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 permisos 0600 y no se sobrescriben salvo que uses --force.
  • Los datos se firman byte a byte (texto en UTF-8); --encoding binary requiere --output al firmar y --signature-file al verificar.
  • Códigos de salida: 0 éxito, 1 error de ejecución o firma inválida, 2 argumentos 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.

The @nodecfdi/credentials library is copyright NodeCfdi and licensed for use under the MIT License (MIT). Please see LICENSE for more information.

Keywords