# @nodecfdi/credentials

> Librería para usar eFirma (fiel) y CSD (sellos) para el SAT

Latest version **4.0.0** (published 2026-11-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install @nodecfdi/credentials
pnpm add @nodecfdi/credentials
yarn add @nodecfdi/credentials
bun add @nodecfdi/credentials
```

Provides the command `nc-credentials`.

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2026-11-19 |
| First published | 2021-06-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | ^22.13.0 \|\| ^24 \|\| ^26 |
| Dependencies | 3 |
| Unpacked size | 827.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 17 |
| Author | Fernando Isidro <luffynando@gmail.com> |
| Maintainers | luffynando, celli33 |
| Keywords | certificate, sat, csd, fiel, signing, firmar, factura, rfc, efirma, sellos, pfx |

## Links

- npm: https://www.npmjs.com/package/@nodecfdi/credentials
- Repository: https://github.com/nodecfdi/credentials
- Issues: https://github.com/nodecfdi/credentials/issues
- npm.io page: https://npm.io/package/@nodecfdi/credentials

## Dependencies (3)

- [node-forge](https://npm.io/package/node-forge.md) ^1.4.3
- [@types/node-forge](https://npm.io/package/@types/node-forge.md) ^1.3.14
- [@nodecfdi/base-converter](https://npm.io/package/@nodecfdi/base-converter.md) ^3.0.1

## Recent versions

- 4.0.0 (latest) — 2026-11-19
- 3.2.0 — 2024-10-06
- 3.1.1 — 2024-09-11
- 3.1.0 — 2024-08-14
- 3.0.0 — 2024-08-13
- 2.0.3 — 2023-07-13
- 2.0.2 — 2023-07-13
- 2.0.1 — 2023-07-11
- 2.0.0 — 2023-06-30
- 1.3.0 — 2022-07-08
- 1.2.2 — 2022-03-14
- 1.2.1 — 2022-03-10
- 1.2.0 — 2022-02-19
- 1.1.0 — 2022-02-18
- 1.0.1 — 2021-08-06
- … 1 more at https://npm.io/package/@nodecfdi/credentials/versions

## README

# `@nodecfdi/credentials`

[![Source Code][badge-source]][source]
[![Npm Node Version Support][badge-node-version]][node-version]
[![Discord][badge-discord]][discord]
[![Latest Version][badge-release]][release]
[![Software License][badge-license]][license]
[![Build Status][badge-build]][build]
[![Reliability][badge-reliability]][reliability]
[![Maintainability][badge-maintainability]][maintainability]
[![Code Coverage][badge-coverage]][coverage]
[![Violations][badge-violations]][violations]
[![Total Downloads][badge-downloads]][downloads]

> Library to use eFirma (fiel) and CSD (sellos) from SAT

:us: The documentation of this project is in spanish as this is the natural language for intended audience.

:mexico: La documentación del proyecto está en español porque ese es el lenguaje principal de los usuarios.

## Acerca de `@nodecfdi/credentials`

Esta librería ha sido creada para poder trabajar con los archivos CSD y FIEL del SAT. De esta forma, se simplifica el
proceso de firmar, verificar firma y obtener datos particulares del archivo de certificado así como de la llave pública.

- El CSD (Certificado de Sello Digital) es utilizado para firmar Comprobantes Fiscales Digitales.

- La FIEL (o eFirma) es utilizada para firmar electrónicamente documentos (generalmente usando XML-SEC) y está
  reconocida por el gobierno mexicano como una manera de firma legal de una persona física o moral.

Con esta librería no es necesario convertir los archivos generados por el SAT a otro formato, se pueden utilizar tal y
como el SAT los entrega.

Esta librería ha sido inspirada por la versión para php https://github.com/phpcfdi/credentials

## Inicio rápido

Instala el paquete junto con su dependencia par `luxon`:

```bash
# pnpm
pnpm add @nodecfdi/credentials luxon

# npm
npm install @nodecfdi/credentials luxon

# yarn
yarn add @nodecfdi/credentials luxon

# bun
bun add @nodecfdi/credentials luxon
```

Abre un certificado (`.cer`) y llave privada (`.key`) directamente como los entrega el SAT para consultar datos, firmar y verificar:

```ts
import { Buffer } from 'node:buffer';
import { openCredentialFiles } from '@nodecfdi/credentials/node';

// En Node.js puedes abrir archivos locales directamente
const credential = openCredentialFiles(
  'ruta/al/certificado.cer',
  'ruta/a/la/llave_privada.key',
  'contraseña-de-la-llave',
);

console.log(credential.rfc()); // AAA010101AAA
console.log(credential.legalName()); // ACCEM SERVICIOS EMPRESARIALES SC
console.log(credential.isCsd()); // true (o credential.isFiel())

// Firmar una cadena original (devuelve firma en cadena binaria)
const cadenaOriginal = '||4.0|A|1|2026-01-01T12:00:00|...||';
const signatureBinary = credential.sign(cadenaOriginal);
const selloBase64 = Buffer.from(signatureBinary, 'binary').toString('base64');

// Verificar la firma con el certificado
const isValid = credential.verify(cadenaOriginal, signatureBinary);
console.log(isValid); // true
```

En navegadores o cuando ya tienes el contenido en memoria, utiliza `Credential.create(certContents, keyContents, passPhrase)` importado desde `@nodecfdi/credentials`.

## Uso por línea de comandos (CLI)

Al instalar el paquete se incluye el ejecutable `nc-credentials` (o puedes ejecutarlo con `npx nc-credentials`):

```bash
# Obtener datos de un certificado (RFC, razón social, serie, vigencia, etc.)
nc-credentials data --cer certificate.cer
nc-credentials data --cer certificate.cer --json
nc-credentials data --cer certificate.cer --field rfc
nc-credentials data --cer certificate.cer --field legal-name

# Firmar texto o archivo
nc-credentials sign --cer certificate.cer --key private_key.key --password-file password.txt --data "cadena original"
nc-credentials sign --key private_key.key --password-file password.txt --file documento.txt --output firma.b64

# Verificar una firma
nc-credentials verify --cer certificate.cer --data "cadena original" --signature "<firma-base64>"
nc-credentials verify --cer certificate.cer --file documento.txt --signature-file firma.b64

# Exportar a archivo PFX (PKCS#12)
nc-credentials pfx export --cer certificate.cer --key private_key.key --password-file password.txt --output archivo.pfx
```

Ejecuta `nc-credentials --help` o `nc-credentials <comando> --help` para ver todas las opciones disponibles (incluyendo soporte para `--pfx`, `stdin`, `--encoding` y `NODECFDI_PASSWORD`).

Notas de seguridad y validación:

- Prefiere `--password-file` o la variable `NODECFDI_PASSWORD` en lugar de `--password`, que expone la contraseña en la lista de procesos (el CLI emite una advertencia).
- Las opciones desconocidas, repetidas, vacías, argumentos sobrantes o valores no permitidos detienen la ejecución indicando el valor inesperado.
- Los archivos de salida (`--output`) se crean con permisos `0600` y no se sobrescriben salvo que uses `--force`.
- Los datos se firman byte a byte (texto en UTF-8); `--encoding binary` requiere `--output` al firmar y `--signature-file` al verificar.
- Códigos de salida: `0` éxito, `1` error de ejecución o firma inválida, `2` argumentos inválidos.

## Documentación

La documentación está disponible en el sitio web [NodeCfdi](https://nodecfdi.com/packages/credentials/getting-started)

## Soporte

Puedes obtener soporte abriendo un ticket en Github.

## Compatibilidad

Esta librería se mantendrá compatible con al menos la versión con
[soporte activo de Node](https://nodejs.org/es/about/releases/) más reciente.

También utilizamos [Versionado Semántico 2.0.0](https://semver.org/lang/es/) por lo que puedes usar esta librería sin temor a romper tu aplicación.

## Contribuciones

Las contribuciones con bienvenidas. Por favor lee [CONTRIBUTING][] para más detalles y recuerda revisar el archivo [CHANGELOG][].

## Copyright and License

The `@nodecfdi/credentials` library is copyright © [NodeCfdi](https://github.com/nodecfdi) and licensed for use under the MIT License (MIT). Please see [LICENSE][] for more information.

[contributing]: https://github.com/nodecfdi/.github/blob/main/docs/CONTRIBUTING.md
[changelog]: https://github.com/nodecfdi/credentials/blob/main/CHANGELOG.md
[source]: https://github.com/nodecfdi/credentials
[node-version]: https://www.npmjs.com/package/@nodecfdi/credentials
[discord]: https://discord.gg/AsqX8fkW2k
[release]: https://www.npmjs.com/package/@nodecfdi/credentials
[license]: https://github.com/nodecfdi/credentials/blob/main/LICENSE
[build]: https://github.com/nodecfdi/credentials/actions/workflows/build.yml?query=branch:main
[reliability]: https://sonarcloud.io/component_measures?id=nodecfdi_credentials&metric=Reliability
[maintainability]: https://sonarcloud.io/component_measures?id=nodecfdi_credentials&metric=Maintainability
[coverage]: https://sonarcloud.io/component_measures?id=nodecfdi_credentials&metric=Coverage
[violations]: https://sonarcloud.io/project/issues?id=nodecfdi_credentials&resolved=false
[downloads]: https://www.npmjs.com/package/@nodecfdi/credentials
[badge-source]: https://img.shields.io/badge/source-nodecfdi/credentials-blue.svg?logo=github
[badge-node-version]: https://img.shields.io/node/v/@nodecfdi/credentials.svg?logo=nodedotjs
[badge-discord]: https://img.shields.io/discord/459860554090283019?logo=discord
[badge-release]: https://img.shields.io/npm/v/@nodecfdi/credentials.svg?logo=npm
[badge-license]: https://img.shields.io/github/license/nodecfdi/credentials.svg?logo=open-source-initiative
[badge-build]: https://img.shields.io/github/actions/workflow/status/nodecfdi/credentials/build.yml?branch=main&logo=github-actions
[badge-reliability]: https://sonarcloud.io/api/project_badges/measure?project=nodecfdi_credentials&metric=reliability_rating
[badge-maintainability]: https://sonarcloud.io/api/project_badges/measure?project=nodecfdi_credentials&metric=sqale_rating
[badge-coverage]: https://img.shields.io/sonar/coverage/nodecfdi_credentials/main?logo=sonarcloud&server=https%3A%2F%2Fsonarcloud.io
[badge-violations]: https://img.shields.io/sonar/violations/nodecfdi_credentials/main?format=long&logo=sonarcloud&server=https%3A%2F%2Fsonarcloud.io
[badge-downloads]: https://img.shields.io/npm/dm/@nodecfdi/credentials.svg?logo=npm

---
_Source: https://npm.io/package/@nodecfdi/credentials · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
