Actualización

Actualizar desde v3.2.0

Guía de migración paso a paso desde @nodecfdi/credentials v3.2.0 hacia la nueva versión con soporte CLI y funciones de Node.js.

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

  1. 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/credentials tanto en Node.js como en navegadores.
  2. Eliminación de @nodecfdi/credentials/browser: La subruta ./browser fue eliminada; reemplázala por @nodecfdi/credentials.
  3. 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).
  4. Paquete ESM puro y requisitos de entorno:
    • Empaquetado como ESM ("type": "module" con tsdown).
    • Requiere Node.js ^22.13.0 || ^24 || ^26.
    • Requiere luxon ^3.7.2 como peer dependency.
  5. Nuevo ejecutable CLI (nc-credentials): Incluye comandos de terminal data (info), sign, verify y pfx export.
  6. Nuevo bundle IIFE para navegador (dist/index.iife.js): Expone la variable global ncfdiCredentials para su uso directo mediante <script> en el navegador.
  7. 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 en subject e issuer de 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';

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');
Si en Node.js ya tienes los contenidos en memoria y usabas 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() o certificate.satType().isFiel().
  • Para verificar el tipo de llave (PrivateKey o PublicKey), usa key.type.isRSA() o key.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 instanciar Certificate.
  • Algoritmo opcional en PfxExporter: exporter.export(passPhrase, algorithm?) y exportPfxToFile(credential, file, passPhrase, algorithm?) ahora permiten omitir el parámetro algorithm o especificar 'aes128', 'aes192', 'aes256' o '3des'.