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
| Comando | Descripción |
|---|---|
data (alias info) | Extrae información de un certificado (.cer, .pem) o archivo .pfx (en texto, JSON o un campo individual). |
sign | Firma texto, un archivo o stdin usando una llave privada (.key, .pem) o archivo .pfx. |
verify | Verifica una firma contra un certificado, llave pública o archivo .pfx. |
pfx export | Empaqueta 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):
- Archivo de contraseña (
--password-file/--pfx-password-file): Lee la contraseña desde un archivo (eliminando saltos de línea finales\ro\n). - Variables de entorno (
NODECFDI_PASSWORD/NODECFDI_PFX_PASSWORD): Define la contraseña en el entorno sin exponerla en los argumentos del comando. - 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 permisos0600(lectura y escritura únicamente para el propietario). - Protección contra sobrescritura: Por defecto,
--outputfalla si el archivo destino ya existe. Usa la bandera--forcecuando 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ódigo | Significado |
|---|---|
0 | Ejecución exitosa (o firma válida en verify). |
1 | Error durante la ejecución (archivo no encontrado, contraseña incorrecta) o firma inválida en verify. |
2 | Error de validación en los argumentos u opciones de la línea de comandos. |
