Credential (Credencial)
La clase Credential encapsula el par formado por un objeto Certificate y su PrivateKey. Al construirse, valida automáticamente que la llave privada corresponda matemáticamente al certificado.
Credential lanzará un error: Error: Certificate does not belong to private key.Creación de una credencial
Existen tres maneras principales de crear una instancia de Credential:
1. Desde archivos locales (Node.js)
Si trabajas en Node.js, la función openCredentialFiles de @nodecfdi/credentials/node lee los archivos .cer y .key directamente desde el disco (acepta rutas normales o con esquema file://):
import { openCredentialFiles } from '@nodecfdi/credentials/node';
const credential = openCredentialFiles(
'/ruta/al/CSD01_AAA010101AAA.cer',
'/ruta/al/CSD01_AAA010101AAA.key',
'12345678a',
);
2. Desde contenidos en memoria (Credential.create)
Cuando ya tienes el contenido de los archivos como cadenas (ya sea en formato PEM, Base64 o cadena binaria DER, tanto en Node.js como en el navegador), usa el método estático Credential.create:
import { readFileSync } from 'node:fs';
import { Credential } from '@nodecfdi/credentials';
const cerContents = readFileSync('/ruta/al/certificado.cer', 'binary');
const keyContents = readFileSync('/ruta/a/la/llave.key', 'binary');
const credential = Credential.create(cerContents, keyContents, '12345678a');
3. A partir de instancias existentes (new Credential)
Si ya instanciaste Certificate y PrivateKey por separado, pásalos al constructor:
import { Certificate, Credential, PrivateKey } from '@nodecfdi/credentials';
const certificate = new Certificate(cerContents);
const privateKey = new PrivateKey(keyContents, '12345678a');
const credential = new Credential(certificate, privateKey);
Credential a partir de un archivo .pfx utilizando readPfxFile o PfxReader. Consulta la sección Archivos PFX.Métodos de acceso y datos fiscales
Credential expone atajos directos a la información más utilizada del certificado, además de permitirte acceder a las instancias subyacentes:
// Instancias subyacentes
const certificate = credential.certificate(); // Certificate
const privateKey = credential.privateKey(); // PrivateKey
// Datos del contribuyente
console.log(credential.rfc()); // "AAA010101AAA"
console.log(credential.legalName()); // "ACCEM SERVICIOS EMPRESARIALES SC"
// Tipo de certificado SAT
console.log(credential.isCsd()); // true si es Certificado de Sello Digital
console.log(credential.isFiel()); // true si es eFirma / FIEL
Firmar y verificar datos
El método sign(data, algorithm?) firma una cadena de texto utilizando la llave privada y el algoritmo especificado ('sha256' por defecto). Devuelve la firma como cadena binaria (binary string).
El método verify(data, signature, algorithm?) comprueba que la firma binaria corresponda a los datos originales utilizando la llave pública del certificado.
import { Buffer } from 'node:buffer';
const sourceString = '||4.0|A|1|2026-01-01T12:00:00|99|100.00|MXN|116.00|I|01|PUE|06300|...||';
// 1. Firmar (por defecto usa 'sha256')
const signatureBinary = credential.sign(sourceString);
// Para incluir el sello en un CFDI XML, conviértelo a Base64:
const selloBase64 = Buffer.from(signatureBinary, 'binary').toString('base64');
console.log('Sello Base64:', selloBase64);
// 2. Verificar la firma (recibe la firma en cadena binaria)
const isValid = credential.verify(sourceString, signatureBinary);
console.log('¿Firma válida?:', isValid); // true
Algoritmos soportados
Tanto sign como verify aceptan como segundo/tercer parámetro cualquiera de los algoritmos definidos en el tipo Algorithm:
'sha256'(valor por defecto, utilizado en CFDI 3.3 y 4.0)'sha1'(utilizado en algunos servicios del SAT y XML-DSig legacy)'sha384''sha512''md5'
const signatureSha1 = credential.sign('texto a firmar', 'sha1');
const validSha1 = credential.verify('texto a firmar', signatureSha1, 'sha1');
