CLI

Introducción al CLI

Utiliza la herramienta de línea de comandos nc-credentials para inspeccionar, firmar, verificar y exportar certificados.

Al instalar @nodecfdi/credentials se incluye el ejecutable nc-credentials, que te permite trabajar con archivos CSD, eFirma (FIEL) y PFX directamente desde la terminal o en scripts de automatización sin escribir código JavaScript.

Ejecución

Puedes invocarlo mediante npx, pnpm dlx o directamente si el paquete está instalado en tu proyecto o de forma global:

nc-credentials --help
nc-credentials --version

Resumen de comandos

ComandoDescripción
data (alias info)Extrae información de un certificado (.cer, .pem) o archivo .pfx (en texto, JSON o un campo individual).
signFirma texto, un archivo o stdin usando una llave privada (.key, .pem) o archivo .pfx.
verifyVerifica una firma contra un certificado, llave pública o archivo .pfx.
pfx exportEmpaqueta y exporta un certificado y llave privada a un archivo .pfx (PKCS#12).

Consulta los detalles y opciones de cada comando en la página Comandos del CLI.

Manejo seguro de contraseñas

El CLI ofrece tres mecanismos para proporcionar contraseñas de llaves privadas o archivos PFX (en orden de recomendación):

  1. Archivo de contraseña (--password-file / --pfx-password-file): Lee la contraseña desde un archivo (eliminando saltos de línea finales \r o \n).
  2. Variables de entorno (NODECFDI_PASSWORD / NODECFDI_PFX_PASSWORD): Define la contraseña en el entorno sin exponerla en los argumentos del comando.
  3. Argumento directo (-p, --password / --pfx-password): Pasa la contraseña en la línea de comandos.
El uso de --password o --pfx-password expone la contraseña en la lista de procesos del sistema operativo y en el historial del shell. Cuando los utilizas, el CLI emite una advertencia en stderr recomendando usar --password-file o NODECFDI_PASSWORD.

Seguridad en archivos de salida y validación

  • Permisos restringidos (0600): Todos los archivos creados mediante --output (tanto firmas como archivos .pfx) se escriben con permisos 0600 (lectura y escritura únicamente para el propietario).
  • Protección contra sobrescritura: Por defecto, --output falla si el archivo destino ya existe. Usa la bandera --force cuando desees permitir que se sobrescriba.
  • Validación estricta de argumentos: Cualquier opción desconocida, repetida, vacía, argumento posicional sobrante o combinación inválida detiene inmediatamente la ejecución antes de realizar operaciones criptográficas.

Códigos de salida

CódigoSignificado
0Ejecución exitosa (o firma válida en verify).
1Error durante la ejecución (archivo no encontrado, contraseña incorrecta) o firma inválida en verify.
2Error de validación en los argumentos u opciones de la línea de comandos.