Uso

Credential (Credencial)

Combina un certificado y su llave privada para consultar datos fiscales, firmar y verificar firmas.

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.

Si el certificado no pertenece a la llave privada proporcionada, el constructor de 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://):

node-credential.ts
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:

memory-credential.ts
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:

instance-credential.ts
import { Certificate, Credential, PrivateKey } from '@nodecfdi/credentials';

const certificate = new Certificate(cerContents);
const privateKey = new PrivateKey(keyContents, '12345678a');

const credential = new Credential(certificate, privateKey);
También puedes crear un objeto 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:

credential-info.ts
// 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.

sign-and-verify.ts
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'
custom-algorithm.ts
const signatureSha1 = credential.sign('texto a firmar', 'sha1');
const validSha1 = credential.verify('texto a firmar', signatureSha1, 'sha1');