Actualizar desde v3.2.0
Esta guía detalla todos los cambios introducidos después de la versión 3.2.0 y cómo actualizar tu código paso a paso.
Resumen de cambios principales
- Unificación de clases en
@nodecfdi/credentials: Todas las clases principales (Credential,Certificate,PrivateKey,PublicKey,PfxReader,PfxExporter,PemExtractor,SerialNumber) ahora se importan directamente desde la raíz@nodecfdi/credentialstanto en Node.js como en navegadores. - Eliminación de
@nodecfdi/credentials/browser: La subruta./browserfue eliminada; reemplázala por@nodecfdi/credentials. - Nuevas funciones de sistema de archivos en
@nodecfdi/credentials/node: Se eliminaron las subclases basadas en mixins (ts-mixer) a favor de funciones puras y explícitas (openCredentialFiles,openCertificateFile,openPrivateKeyFile,openPublicKeyFile,readPfxFile,exportPfxToFile,localFileOpen). - Paquete ESM puro y requisitos de entorno:
- Empaquetado como ESM (
"type": "module"contsdown). - Requiere Node.js
^22.13.0 || ^24 || ^26. - Requiere
luxon^3.7.2como peer dependency.
- Empaquetado como ESM (
- Nuevo ejecutable CLI (
nc-credentials): Incluye comandos de terminaldata(info),sign,verifyypfx export. - Nuevo bundle IIFE para navegador (
dist/index.iife.js): Expone la variable globalncfdiCredentialspara su uso directo mediante<script>en el navegador. - Mejoras criptográficas y de codificación UTF-8: Migración a
node-forge^1.4.3, decodificación automática de atributos UTF-8 ensubjecteissuerde certificados X.509 y caché en memoria de llaves RSA parseadas.
1. Migración de importaciones del navegador (/browser)
Si antes importabas desde @nodecfdi/credentials/browser, cambia la ruta directamente a @nodecfdi/credentials. Las clases y sus métodos en memoria son idénticos:
import { Certificate, Credential, PrivateKey } from '@nodecfdi/credentials/browser';
import { Certificate, Credential, PrivateKey } from '@nodecfdi/credentials';
2. Migración de lectura y escritura de archivos en Node.js (/node)
En v3.2.0, @nodecfdi/credentials/node exportaba subclases con métodos estáticos como Credential.openFiles(...) o Certificate.openFile(...). En la nueva versión, @nodecfdi/credentials/node exporta funciones dedicadas que devuelven las clases estándar de @nodecfdi/credentials.
Tabla de equivalencias para Node.js
Antes (v3.2.0 desde @nodecfdi/credentials/node) | Ahora (desde @nodecfdi/credentials/node) |
|---|---|
Credential.openFiles(cerFile, keyFile, pass) | openCredentialFiles(cerFile, keyFile, pass) |
Certificate.openFile(cerFile) | openCertificateFile(cerFile) |
PrivateKey.openFile(keyFile, pass) | openPrivateKeyFile(keyFile, pass) |
PublicKey.openFile(pubFile) | openPublicKeyFile(pubFile) |
PfxReader.createCredentialFromFile(pfxFile, pass) | readPfxFile(pfxFile, pass) |
new PfxExporter(cred).exportToFile(pfxFile, pass, alg) | exportPfxToFile(cred, pfxFile, pass, alg) |
Certificate.localFileOpen(file) | localFileOpen(file) |
Ejemplo comparativo en Node.js
import {
Certificate,
Credential,
PfxExporter,
PfxReader,
PrivateKey,
PublicKey,
} from '@nodecfdi/credentials/node';
const credential = Credential.openFiles('cert.cer', 'key.key', '12345678a');
const certificate = Certificate.openFile('cert.cer');
const privateKey = PrivateKey.openFile('key.key', '12345678a');
const publicKey = PublicKey.openFile('pubkey.pem');
const pfxCredential = PfxReader.createCredentialFromFile('archivo.pfx', '12345678a');
const exporter = new PfxExporter(credential);
exporter.exportToFile('salida.pfx', '12345678a', 'aes128');
import {
exportPfxToFile,
openCertificateFile,
openCredentialFiles,
openPrivateKeyFile,
openPublicKeyFile,
readPfxFile,
} from '@nodecfdi/credentials/node';
const credential = openCredentialFiles('cert.cer', 'key.key', '12345678a');
const certificate = openCertificateFile('cert.cer');
const privateKey = openPrivateKeyFile('key.key', '12345678a');
const publicKey = openPublicKeyFile('pubkey.pem');
const pfxCredential = readPfxFile('archivo.pfx', '12345678a');
exportPfxToFile(credential, 'salida.pfx', '12345678a', 'aes128');
Credential.create(cerContents, keyContents, pass) o new Certificate(contents), ahora solo necesitas importar Credential o Certificate desde @nodecfdi/credentials.3. Exportaciones internas eliminadas de la raíz
En v3.2.0, la raíz @nodecfdi/credentials reexportaba utilidades internas (isHexadecimal, isNumber, isScalar, KeyType, KeyTypeEnum, SatType, SatTypeEnum). Estas utilidades eran de uso interno y ya no se exportan desde la raíz:
- Para verificar el tipo de certificado SAT, usa
credential.isCsd(),credential.isFiel(),certificate.satType().isCsd()ocertificate.satType().isFiel(). - Para verificar el tipo de llave (
PrivateKeyoPublicKey), usakey.type.isRSA()okey.isType('RSA').
4. Nuevas funcionalidades disponibles
- CLI
nc-credentials: Ahora puedes inspeccionar certificados, firmar, verificar y exportar a PFX desde la terminal. Consulta la Introducción al CLI. - Decodificación UTF-8 en certificados: Los nombres o razones sociales con caracteres especiales (como
Ño acentos codificados en UTF-8 dentro del certificado X.509) se decodifican automáticamente al instanciarCertificate. - Algoritmo opcional en
PfxExporter:exporter.export(passPhrase, algorithm?)yexportPfxToFile(credential, file, passPhrase, algorithm?)ahora permiten omitir el parámetroalgorithmo especificar'aes128','aes192','aes256'o'3des'.
