@brasil-fiscal/core

Infraestrutura compartilhada para documentos fiscais eletronicos brasileiros. Certificado digital, assinatura XML, transporte mTLS, helpers e constantes — tudo que NFe, CTe e MDFe tem em comum.

Para que serve?

Este pacote eh a base dos projetos @brasil-fiscal/*. Ele contem a logica que eh identica entre NFe, CTe e MDFe:

• Carregar certificado digital A1 (.pfx/.p12)
• Assinar XML com XMLDSig (RSA-SHA1)
• Comunicar com a SEFAZ via HTTPS com mTLS
• Canonicalizacao C14N de XML
• Gerar chave de acesso (44 digitos)
• Validar CNPJ e CPF
• Codigos IBGE das UFs
• Classes de erro base

Voce provavelmente nao precisa instalar este pacote diretamente. Ele eh uma dependencia dos pacotes de documento fiscal:

Instalacao

Se voce esta construindo um pacote que depende do core:

npm install @brasil-fiscal/core

API

Certificado Digital

import { A1CertificateProvider } from '@brasil-fiscal/core';

const provider = new A1CertificateProvider(pfxBuffer, 'senha');
const cert = await provider.load();
// cert.privateKey, cert.certPem, cert.pfx, cert.password, cert.notAfter

Assinatura XML

import { DefaultXmlSigner } from '@brasil-fiscal/core';

const signer = new DefaultXmlSigner();
const xmlAssinado = signer.sign(xml, certificateData);

O signer detecta automaticamente o tipo de documento (infNFe, infCte, infMDFe, infEvento, infInut) e assina corretamente.

Transporte mTLS

import { NodeHttpSefazTransport } from '@brasil-fiscal/core';

const transport = new NodeHttpSefazTransport({ timeout: 30000 });
const response = await transport.send({
  url: 'https://nfe.sefaz.mt.gov.br/...',
  soapAction: '...',
  xml: envelopeXml,
  pfx: cert.pfx,
  password: cert.password
});

Helpers XML

import { tag, tagGroup, formatDate, escapeXml, padLeft } from '@brasil-fiscal/core';

tag('CNPJ', '12345678000195');           // <CNPJ>12345678000195</CNPJ>
tag('xNome', undefined);                  // '' (omite tags vazias)
tagGroup('emit', tag('CNPJ', '123'));     // <emit><CNPJ>123</CNPJ></emit>
formatDate(new Date(), '-03:00');         // '2024-04-28T10:00:00-03:00'

SOAP

import { extractSoapBody, extractTag } from '@brasil-fiscal/core';

const body = extractSoapBody(soapResponseXml);  // conteudo dentro de <soap:Body>
const cStat = extractTag(body, 'cStat');         // conteudo de <cStat>

Chave de Acesso

import { generateAccessKey, generateNumericCode } from '@brasil-fiscal/core';

const chave = generateAccessKey({
  uf: '51',
  dataEmissao: new Date(),
  cnpj: '12345678000195',
  modelo: '55',     // 55=NFe, 57=CTe, 58=MDFe, 65=NFCe
  serie: 1,
  numero: 1,
  tipoEmissao: 1,
  codigoNumerico: generateNumericCode()
});
// 44 digitos com digito verificador

Validacao de Documentos

import { isValidCnpj, isValidCpf, formatCnpj, formatCpf } from '@brasil-fiscal/core';

isValidCnpj('11222333000181');  // true
isValidCpf('52998224725');      // true
formatCnpj('11222333000181');   // '11.222.333/0001-81'
formatCpf('52998224725');       // '529.982.247-25'

Constantes

import { UF_CODES } from '@brasil-fiscal/core';

UF_CODES['MT'];  // '51'
UF_CODES['SP'];  // '35'

Erros

import { DFeError, CertificateError, SefazRejectError } from '@brasil-fiscal/core';

// DFeError — erro base de todos os documentos fiscais
// CertificateError — falha no certificado digital
// SefazRejectError — SEFAZ rejeitou o documento (cStat + xMotivo)
// SchemaValidationError — XML invalido contra XSD

Contratos (Interfaces)

O core define contratos que podem ser implementados por qualquer pacote:

Criando um provider customizado

import type { CertificateProvider, CertificateData } from '@brasil-fiscal/core';

export class MyCertificateProvider implements CertificateProvider {
  async load(): Promise<CertificateData> {
    // Sua logica (vault, HSM, banco de dados, etc.)
    return { pfx, password, notAfter, privateKey, certPem };
  }
}

Arquitetura

src/
  contracts/        Interfaces (CertificateProvider, SefazTransport, XmlSigner, SchemaValidator)
  infra/
    certificate/    A1CertificateProvider (carrega .pfx/.p12 via openssl)
    xml/            DefaultXmlSigner, canonicalize (C14N), xml-helper (tag, escapeXml)
    transport/      NodeHttpSefazTransport (mTLS), soap-helper (extractSoapBody)
  shared/
    errors/         DFeError, CertificateError, SefazRejectError, SchemaValidationError
    helpers/        CNPJ, CPF, mod11, access-key
    constants/      UF_CODES (codigos IBGE)

Principios

• Zero dependencias em runtime — apenas node:crypto, node:https, node:child_process
• Contratos primeiro — toda integracao externa eh uma interface
• Falhar rapido — erros claros com classes tipadas
• DI manual — sem containers, providers injetados via construtores

Requisitos

• Node.js >= 18
• OpenSSL instalado (para carregar certificados A1)

Desenvolvimento

git clone https://github.com/brasil-fiscal/core.git
cd core
npm install
npm run build
npm test

Contribuindo

Contribuicoes sao bem-vindas! Veja CONTRIBUTING.md.

Code Style

• TypeScript strict mode, return types explicitos
• Single quotes, semicolons, sem trailing commas, 100 chars por linha
• Path alias: @core/* mapeia para src/*
• Interfaces sem prefixo I (CertificateProvider, nao ICertificateProvider)

Ecossistema @brasil-fiscal

Licenca

MIT