@baruk/core 0.4.2 → 0.5.0

package/dist/fiscal/contracts/nfse-adn-contract.js

@@ -0,0 +1,386 @@
+/**
+ * O contrato oficial da NFS-e Nacional — ADN — como artefato versionado.
+ *
+ * ## Por que um módulo, e não comentários espalhados
+ *
+ * Até a Fase 2 o que sabíamos do ADN estava disperso em comentários de
+ * `nfse-adn.ts` e `adn-transport.ts`, misturado com o que apenas SUPÚNHAMOS. Um
+ * leitor não tinha como separar "o manual diz" de "assumimos por simetria com a
+ * NF-e" — e a segunda categoria é exatamente a que produz um parser que devolve
+ * lote vazio com sucesso aparente.
+ *
+ * Aqui cada afirmação carrega a fonte que a sustenta e, quando não há fonte, diz
+ * que não há. `evidence: 'official'` significa que existe um documento oficial
+ * publicado, com versão, data e sha256 registrados abaixo; `evidence:
+ * 'unverified'` significa que a afirmação é a melhor leitura disponível e NÃO
+ * foi conferida contra o serviço.
+ *
+ * A distinção não é documental: ela é executável. Um perfil de envelope com
+ * `verified: false` fecha o transporte real (`adn-transport.ts`), e é por isso
+ * que a Fase 3 termina com o motor pronto e parado em vez de pronto e chutando.
+ *
+ * ## O que foi medido nesta onda, e como
+ *
+ * Todo host do ADN — `adn.nfse.gov.br` e `adn.producaorestrita.nfse.gov.br` —
+ * exige TLS mútuo com certificado ICP-Brasil para TODOS os seus módulos,
+ * documentação inclusive. Medido em 2026-09-08 percorrendo as dezesseis URLs de
+ * Swagger publicadas em gov.br (oito módulos × dois ambientes): o handshake
+ * completa, o servidor envia `CertificateRequest` — 170 CAs aceitas em produção
+ * restrita, 5 em produção — e então encerra a conexão sem UM byte de HTTP.
+ * Não há caminho público para ler o envelope de resposta.
+ *
+ * Por isso o envelope permanece `unverified`, e por isso a Fase 3 não é a
+ * primeira conexão real: é a transformação do que ESTÁ publicado num contrato
+ * executável que se recusa a adivinhar o que não está.
+ */
+/**
+ * A versão do contrato que este código implementa.
+ *
+ * Vai gravada em `fiscal_sync_run.contract_version`. O motivo é operacional e
+ * concreto: quando o governo alterar o leiaute — e ele já alterou duas vezes
+ * entre dez/2025 e fev/2026 —, a pergunta "qual parser processou este lote?"
+ * precisa ter resposta no dado, não na arqueologia do `git log`.
+ */
+export const NFSE_ADN_CONTRACT_VERSION = 'nfse-adn:v1';
+/**
+ * As fontes primárias. Somente gov.br / Portal Nacional NFS-e.
+ *
+ * Blog, fórum, artigo de fornecedor e repositório de terceiro ficaram de fora
+ * por decisão de fase, e não por desdém: nenhum deles é responsável pelo
+ * protocolo, e um deles CONTRADIZ o manual quanto ao papel do certificado.
+ * Pista serve para saber onde procurar; certificação, não.
+ */
+export const NFSE_ADN_OFFICIAL_SOURCES = Object.freeze([
+    Object.freeze({
+        id: 'manual-contribuintes-adn',
+        title: 'Manual dos Contribuintes — Sistema Nacional NFS-e — Guia para utilização das API´s do ADN',
+        url: 'https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual/manual-contribuintes-apis-adn-sistema-nacional-nfse.pdf',
+        version: '1.0',
+        publishedAt: '2026-02-12',
+        sha256: '9ffc97d8b1be4c80a440b3569b0027df61265b9e75ef69437f21f9481a9a1d6d',
+        retrievedAt: '2026-09-08',
+        scope: 'Métodos do ADN para o contribuinte: GET /DFe/{NSU} e GET /NFSe/{ChaveAcesso}/Eventos; escopo por CNPJ Raiz do certificado.',
+    }),
+    Object.freeze({
+        id: 'manual-municipios-adn',
+        title: 'Manual dos Municípios Conveniados ao Sistema Nacional NFS-e — Guia para utilização das API´s do ADN',
+        url: 'https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual/manual-municipios-apis-adn-sistema-nacional-nfs-e-v1-2-out21025.pdf',
+        version: '1.0',
+        publishedAt: '2025-03-17',
+        sha256: '1e1463e68aa56dbd94e77c3597059b173b8c0a60b1234b3e8424cdcba033b067',
+        retrievedAt: '2026-09-08',
+        scope: 'Semântica dos quatro NSU, ordem crescente, teto de 50 por lote, ultNSU/maxNSU, espera de uma hora, e os três desfechos possíveis da distribuição.',
+    }),
+    Object.freeze({
+        id: 'anexo-iv-adn',
+        title: 'ANEXO_IV — ADN — SNNFSe (regras de negócio e códigos de erro do ADN)',
+        url: 'https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual/anexo_iv-adn-snnfse-v1-00-20251216.xlsx',
+        version: '1.00',
+        publishedAt: '2025-12-16',
+        sha256: 'fa778d0b6e58d62d90d72225b0495805108a4f4983ac77076044a21d8036302f',
+        retrievedAt: '2026-09-08',
+        scope: 'Códigos E1xxx (certificado, mensagem, área de dados) e E2xxx (distribuição), incluindo os do contribuinte: E2215, E2230, E2240, E2241.',
+    }),
+    Object.freeze({
+        id: 'esquemas-xsd-v1-01',
+        title: 'NFSe-ESQUEMAS_XSD-v1.01-20260209',
+        url: 'https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual/nfse-esquemas_xsd-v1-01-20260209.zip',
+        version: '1.01',
+        publishedAt: '2026-02-09',
+        sha256: 'e7935cbd9470527c6cc32984c1b2263e614183bf0139ce2733eaaed2de9a8072',
+        retrievedAt: '2026-09-08',
+        scope: 'Leiaute do CONTEÚDO: NFSe_v1.01, evento_v1.01, tiposComplexos, tiposEventos, tiposSimples. É a fonte do parser de documento e do mapa de eventos.',
+    }),
+]);
+/**
+ * ═══ A distinção que a Fase 3 existe para tornar precisa ═══════════════════
+ *
+ * `payloadShapeVerified` — o CONTEÚDO (o XML da NFS-e e do evento). Conferido
+ * contra o XSD oficial v1.01, cujo hash está acima. É `true`.
+ *
+ * `envelopeShapeVerified` — o ENVELOPE de transporte que embrulha esse conteúdo
+ * na resposta HTTP do ADN. NÃO existe em nenhum artefato alcançável sem
+ * certificado ICP-Brasil: o Swagger é servido pelo próprio host que exige TLS
+ * mútuo. É `false`.
+ *
+ * Uma constante só para os dois esconderia justamente a diferença que importa.
+ * O antigo `ADN_RESPONSE_SHAPE_VERIFIED` era essa constante única, e ela dizia
+ * `false` por causa do envelope — deixando o leitor concluir que também não
+ * sabíamos ler o documento, o que era falso e desnecessariamente pessimista.
+ */
+export const NFSE_ADN_PAYLOAD_SHAPE_VERIFIED = true;
+export const NFSE_ADN_ENVELOPE_SHAPE_VERIFIED = false;
+/**
+ * mTLS é exigência do PROTOCOLO neste endpoint — medido e documentado.
+ *
+ * Duas evidências independentes, e nenhuma delas é dedução:
+ *
+ *   1. O manual do contribuinte (v1.0, §1.1) fala do "CNPJ do certificado
+ *      utilizado para ESTABELECER A CONEXÃO" e valida o CNPJ Raiz entre o
+ *      parâmetro informado e esse certificado. Certificado que estabelece a
+ *      conexão é certificado de cliente em TLS.
+ *   2. As dezesseis URLs oficiais de Swagger do ADN, nos dois ambientes, não
+ *      devolvem um byte de HTTP sem certificado de cliente (medido 2026-09-08).
+ *
+ * O escopo desta afirmação é o HOST do ADN, e para nada além dele. A NFS-e
+ * nacional tem outros serviços — emissão pela Sefin, sistemas municipais
+ * próprios, Emissor Público Web com login gov.br — e generalizar um endpoint
+ * para todo o ecossistema seria o mesmo erro de método que a Fase 1 cometeu ao
+ * adivinhar código de evento por prefixo.
+ */
+export const NFSE_ADN_MTLS_REQUIREMENT = 'required';
+/**
+ * A1 continua REFUTADO como exigência de protocolo.
+ *
+ * O que as fontes oficiais exigem do certificado é: raiz ICP-Brasil (E1208),
+ * `KeyUsage` com Autenticação Cliente (E1200), extensão de CNPJ no `OtherName`
+ * OID 2.16.76.1.3.3 (E1209), cadeia e LCR válidas (E1205/E1206/E1207). Nada
+ * disso distingue A1 de A3 — um A3 em token satisfaz os cinco.
+ *
+ * A1 é PREFERÊNCIA DE AUTOMAÇÃO nossa: um worker sem pessoa presente não digita
+ * PIN de token. Registrar isso como preferência, e não como obrigação legal, é o
+ * que impede o produto de exigir do cliente um certificado que a norma não pede.
+ */
+export const NFSE_ADN_A1_REQUIREMENT = 'refuted';
+export const NFSE_ADN_A1_RATIONALE = 'server_side_automation_preference';
+/** Hosts oficiais, por ambiente. Nunca substituíveis um pelo outro. */
+export const NFSE_ADN_HOSTS = Object.freeze({
+    /** Produção RESTRITA: responde como o real sobre documento SEM valor fiscal. */
+    homologation: 'adn.producaorestrita.nfse.gov.br',
+    production: 'adn.nfse.gov.br',
+});
+/**
+ * Limites. Os oficiais vêm da norma; os defensivos são nossos e dizem que são.
+ *
+ * A separação existe porque um limite oficial ultrapassado é violação de norma —
+ * e o CNPJ bloqueado é o do CLIENTE —, enquanto um limite defensivo ultrapassado
+ * é só a nossa proteção agindo. Confundi-los faria alguém "afrouxar o limite"
+ * numa madrugada sem saber qual dos dois estava afrouxando.
+ */
+export const NFSE_ADN_LIMITS = Object.freeze({
+    /** Manual dos Municípios §1.4.2.b: "Quantidade máxima de documentos no lote: 50". */
+    maxDocumentsPerBatch: { value: 50, evidence: 'official' },
+    /**
+     * Manual dos Municípios §1.4.2.b: espera mínima de UMA HORA depois de receber
+     * a indicação de que não há mais documentos.
+     *
+     * Isto corrige o comentário da Fase 1, que dizia que a NFS-e "não publica a
+     * regra de uma hora que a NF-e publica" e que adotávamos 3600s por simetria.
+     * Ela publica. A regra é dela, não emprestada.
+     */
+    exhaustedWaitSeconds: { value: 3600, evidence: 'official' },
+    /**
+     * Teto de bytes da resposta HTTP. DEFENSIVO — a norma não fixa um.
+     *
+     * 16 MiB acomoda com folga 50 documentos comprimidos (uma NFS-e tem alguns KB)
+     * e impede que um servidor comprometido, um proxy hostil ou um defeito do lado
+     * de lá transformem uma sincronização em consumo ilimitado de memória.
+     */
+    maxResponseBytes: { value: 16 * 1024 * 1024, evidence: 'unverified' },
+    /**
+     * Teto de bytes DESCOMPACTADOS por documento. DEFENSIVO.
+     *
+     * É o mesmo 8 MiB que `decodeFiscalXml` já impõe ao XML. Repeti-lo aqui não é
+     * duplicação: sem ele, uma bomba de descompressão estoura a memória ANTES de
+     * o leitor de XML ter a chance de recusar o tamanho.
+     */
+    maxDecompressedBytesPerDocument: {
+        value: 8 * 1024 * 1024,
+        evidence: 'unverified',
+    },
+    /**
+     * Teto de bytes descompactados do lote inteiro. DEFENSIVO.
+     *
+     * 50 × 8 MiB seriam 400 MiB — o produto dos dois tetos anteriores não é um
+     * teto útil. 64 MiB é generoso para o caso real e finito para o hostil.
+     */
+    maxDecompressedBytesPerBatch: {
+        value: 64 * 1024 * 1024,
+        evidence: 'unverified',
+    },
+    /** Teto de espera de uma requisição. DEFENSIVO — ver `FiscalTransportRequest`. */
+    requestTimeoutMs: { value: 30_000, evidence: 'unverified' },
+});
+/**
+ * As quatro séries de NSU do ADN — Manual dos Municípios §1.3.4.
+ *
+ * Confundi-las é o erro caro: cada uma numera um conjunto diferente de fatos, e
+ * usar o cursor de uma para consultar outra pularia documentos em silêncio.
+ * A nossa é a QUARTA, e apenas ela.
+ */
+export const NFSE_ADN_NSU_SERIES = Object.freeze({
+    general: 'NSU Geral do ADN (por DF-e) — controle interno do ADN; NÃO é distribuição.',
+    municipalReception: 'NSU de Recepção/Backup (por Código de Município) — do município emissor.',
+    municipalDistribution: 'NSU de Distribuição (por Código de Município) — do município interessado.',
+    actorDistribution: 'NSU de Distribuição para os atores da NFS-e (por CPF/CNPJ) — Prestador, Tomador e Intermediário. É ESTA que o Office consome.',
+});
+/** A série que este adapter consome. Explícito para que nunca seja "a outra". */
+export const NFSE_ADN_NSU_SERIES_IN_USE = 'actorDistribution';
+/**
+ * A matriz de contrato. Nada aqui é inferido em silêncio.
+ *
+ * Onde a fonte oficial não diz, o campo diz "não publicado" e o item entra em
+ * `unverified`. Um campo preenchido com a melhor suposição e sem marca seria
+ * indistinguível de um campo conferido — e essa indistinção é precisamente o
+ * defeito que a Fase 3 fecha.
+ */
+export const NFSE_ADN_OPERATIONS = Object.freeze([
+    Object.freeze({
+        id: 'dfe-distribution',
+        method: 'GET',
+        path: '/DFe/{NSU}',
+        environments: ['homologation', 'production'],
+        authentication: 'TLS mútuo com certificado ICP-Brasil de pessoa jurídica; o certificado estabelece a conexão e identifica o solicitante.',
+        identityScope: 'CNPJ Raiz do certificado. O manual v1.0 acrescentou um parâmetro para consultar CNPJ diferente do certificado, validando a RAIZ entre os dois — o que autoriza filial da MESMA raiz, e nada além dela.',
+        requestFormat: 'Sem corpo. O NSU de continuação vai no caminho; `0` é o começo disponível.',
+        responseFormat: 'JSON (Manual dos Municípios §1.3.2: "As mensagens de comunicação com a API utilizarão o padrão JSON"), transportando DF-e cujo leiaute é XML assinado.',
+        cursorSemantics: 'Até 50 DF-e a partir do último NSU informado, em ordem CRESCENTE de NSU. O NSU é gerado por ordem cronológica de RECEPÇÃO pelo ADN, não de emissão. Documentos compartilhados pelo próprio solicitante não são distribuídos a ele.',
+        emptySemantics: 'Três desfechos publicados: rejeição com motivo; "nenhum documento localizado"; documento localizado. Para o contribuinte, "nenhum documento" é o código E2215 (a partir do NSU) ou E2230 (NSU pontual). Esgotamento é ultNSU === maxNSU, e obriga espera de 1h.',
+        errorShape: 'Códigos E1xxx/E2xxx do ANEXO_IV. O envelope JSON que os carrega NÃO está publicado fora do Swagger protegido por mTLS.',
+        rateLimitSemantics: 'Espera mínima de 1 hora após a indicação de esgotamento. A norma não publica cabeçalho de limite nem código HTTP de excesso para este endpoint.',
+        sourceId: 'manual-contribuintes-adn',
+        implemented: true,
+        unverified: Object.freeze([
+            'nomes e capitalização dos campos do envelope JSON',
+            'status HTTP associado a cada um dos três desfechos',
+            'codificação do conteúdo do documento (gzip+base64 é a forma usada pelo docZip da NF-e, não confirmada aqui)',
+            'nome do parâmetro de CNPJ de consulta acrescentado na v1.0',
+        ]),
+    }),
+    Object.freeze({
+        id: 'nfse-events-by-key',
+        method: 'GET',
+        path: '/NFSe/{ChaveAcesso}/Eventos',
+        environments: ['homologation', 'production'],
+        authentication: 'TLS mútuo com certificado ICP-Brasil, idem.',
+        identityScope: 'A chave precisa referenciar o contribuinte solicitante; caso contrário E2241.',
+        requestFormat: 'Sem corpo. Chave de acesso de 53 posições no caminho.',
+        responseFormat: 'JSON com os eventos vinculados à chave; conteúdo XML por evento.',
+        cursorSemantics: 'Não tem cursor: é consulta pontual por chave.',
+        emptySemantics: 'E2240 — chave não localizada. E2241 — chave não referencia o solicitante.',
+        errorShape: 'Idem, códigos E2xxx do ANEXO_IV.',
+        rateLimitSemantics: 'Não publicada para esta operação.',
+        sourceId: 'manual-contribuintes-adn',
+        // Deliberadamente NÃO implementada nesta fase. O motor recebe os eventos
+        // pela própria distribuição por NSU — a série de atores distribui os eventos
+        // junto com os documentos (ANEXO_IV, aba de geração de NSU). Uma segunda
+        // porta para o mesmo fato só acrescentaria consumo contra o ambiente
+        // nacional sem trazer informação nova.
+        implemented: false,
+        unverified: Object.freeze(['envelope JSON', 'status HTTP por desfecho']),
+    }),
+]);
+export const NFSE_ADN_OFFICIAL_CODES = Object.freeze(Object.fromEntries([
+    // ── Distribuição para os ATORES (o nosso caminho) ────────────────────
+    [
+        'E2215',
+        'Não existem DF-e para o contribuinte a partir do NSU informado',
+        'no_documents',
+        null,
+    ],
+    ['E2230', 'Não existe DF-e para o contribuinte com o NSU informado', 'no_documents', null],
+    ['E2240', 'Chave de acesso não localizada', 'no_documents', null],
+    [
+        'E2241',
+        'Chave de acesso não referencia o contribuinte solicitante',
+        'error',
+        'not_allowed',
+    ],
+    // ── Certificado de transmissão ───────────────────────────────────────
+    ['E1200', 'Certificado de transmissão inválido', 'error', 'auth'],
+    ['E1203', 'Certificado de transmissão expirado', 'error', 'auth'],
+    ['E1205', 'Erro na cadeia de certificação', 'error', 'auth'],
+    ['E1206', 'Erro de acesso à LCR', 'error', 'auth'],
+    ['E1207', 'Certificado de transmissão revogado', 'error', 'auth'],
+    ['E1208', 'Certificado não tem raiz ICP-Brasil', 'error', 'auth'],
+    ['E1209', 'Certificado de transmissão sem CNPJ', 'error', 'auth'],
+    ['E2000', 'Erro no certificado de transmissão', 'error', 'auth'],
+    // ── Autorização e cadastro ───────────────────────────────────────────
+    [
+        'E1262',
+        'CNPJ não autorizado a compartilhar DF-e pelo município conveniado',
+        'error',
+        'not_allowed',
+    ],
+    ['E2001', 'CNPJ não cadastrado para nenhum município conveniado', 'error', 'not_allowed'],
+    ['E2301', 'CNPJ não cadastrado', 'error', 'not_allowed'],
+    // ── Serviço ──────────────────────────────────────────────────────────
+    ['E1217', 'Serviço paralisado para manutenção', 'error', 'transient'],
+    // ── Mensagem e área de dados ─────────────────────────────────────────
+    ['E1219', 'Número de documentos maior que o limite', 'error', 'invalid'],
+    ['E1225', 'Falha na decodificação da base64 da área de dados', 'error', 'invalid'],
+    ['E1226', 'Estrutura descompactada mal formada', 'error', 'invalid'],
+    ['E1228', 'Prefixo de namespace não permitido', 'error', 'invalid'],
+    ['E1229', 'XML fora de UTF-8', 'error', 'invalid'],
+    ['E1235', 'Falha no esquema XML do DF-e', 'error', 'invalid'],
+    ['E1242', 'Tipo de DF-e não tratado pelo Sistema Nacional NFS-e', 'error', 'invalid'],
+    ['E1245', 'Certificado da assinatura do lote sem CNPJ', 'error', 'invalid'],
+    ['E1246', 'Certificado da assinatura do lote — erro na cadeia', 'error', 'invalid'],
+    ['E1250', 'Assinatura difere do calculado', 'error', 'invalid'],
+].map(([code, meaning, outcome, errorClass]) => [
+    code,
+    Object.freeze({ code, meaning, outcome, errorClass }),
+])));
+/**
+ * O perfil OFICIAL — a melhor leitura disponível, e declaradamente não conferida.
+ *
+ * Os nomes vêm da descrição pública da API e da simetria com o `docZip` da
+ * NF-e. Estão aqui para que exista UM lugar onde corrigi-los no dia em que
+ * alguém vir a resposta — e para que o `verified: false` mantenha o transporte
+ * real fechado até esse dia.
+ */
+export const ADN_OFFICIAL_ENVELOPE_PROFILE = Object.freeze({
+    id: 'nfse-adn:v1/official',
+    contractVersion: NFSE_ADN_CONTRACT_VERSION,
+    verified: NFSE_ADN_ENVELOPE_SHAPE_VERIFIED,
+    environments: Object.freeze(['homologation', 'production']),
+    batchField: 'LoteDFe',
+    itemNsuField: 'NSU',
+    itemContentField: 'ArquivoXml',
+    lastNsuField: 'UltimoNSU',
+    maxNsuField: 'MaximoNSU',
+    codeField: 'Codigo',
+    contentEncoding: 'gzip+base64',
+});
+/**
+ * O perfil SINTÉTICO — conferido, porque somos nós quem o define.
+ *
+ * Não há circularidade: ele não afirma nada sobre o ADN. Ele descreve o servidor
+ * de mentira que a suíte levanta, e `verified: true` aqui significa apenas "o
+ * parser e o servidor sintético concordam", que é uma afirmação verificável e
+ * verificada. `environments: ['synthetic']` impede que ele seja usado como
+ * atalho para abrir o transporte real.
+ */
+export const ADN_SYNTHETIC_ENVELOPE_PROFILE = Object.freeze({
+    id: 'nfse-adn:v1/synthetic',
+    contractVersion: NFSE_ADN_CONTRACT_VERSION,
+    verified: true,
+    environments: Object.freeze(['synthetic']),
+    batchField: 'LoteDFe',
+    itemNsuField: 'NSU',
+    itemContentField: 'ArquivoXml',
+    lastNsuField: 'UltimoNSU',
+    maxNsuField: 'MaximoNSU',
+    codeField: 'Codigo',
+    contentEncoding: 'gzip+base64',
+});
+/**
+ * O transporte real está ligado?
+ *
+ * Constante, e não variável de ambiente, por decisão de fase: uma variável de
+ * ambiente é ligável sem revisão, e a primeira conexão fiscal real do produto
+ * não deve poder acontecer por causa de uma linha num painel. Quando o portão
+ * humano da Fase 4 for aberto, isto vira um commit — revisável, revertível, e
+ * com o nome de quem o abriu.
+ */
+export const ADN_REAL_TRANSPORT_ENABLED = false;
+/** Motivos pelos quais o transporte real está fechado, para tela e trilha. */
+export function adnRealTransportBlockers(profile = ADN_OFFICIAL_ENVELOPE_PROFILE) {
+    const razoes = [];
+    if (!ADN_REAL_TRANSPORT_ENABLED)
+        razoes.push('ADN_REAL_TRANSPORT_DISABLED');
+    if (!profile.verified)
+        razoes.push('ADN_ENVELOPE_UNVERIFIED');
+    return Object.freeze(razoes);
+}
+//# sourceMappingURL=nfse-adn-contract.js.map

package/dist/fiscal/contracts/nfse-adn-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nfse-adn-contract.js","sourceRoot":"","sources":["../../../src/fiscal/contracts/nfse-adn-contract.ts"],"names":[],"mappings":"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"}

package/dist/fiscal/contracts/nfse-adn-endpoint.d.ts

@@ -0,0 +1,13 @@
+import { FiscalProviderError, type FiscalEnvironmentTag } from '../ingestion/provider.js';
+export declare class AdnEndpointNotAllowedError extends FiscalProviderError {
+    readonly detail: string;
+    constructor(detail: string);
+}
+/**
+ * Resolve e AUTORIZA a base do ADN para um ambiente.
+ *
+ * Devolve sempre uma URL sem barra final, para que a composição de caminho em
+ * `adnDfeUrl` seja uma concatenação e não uma decisão.
+ */
+export declare function resolveAdnBaseUrl(environment: FiscalEnvironmentTag, baseUrl?: string | null): string;
+//# sourceMappingURL=nfse-adn-endpoint.d.ts.map

package/dist/fiscal/contracts/nfse-adn-endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nfse-adn-endpoint.d.ts","sourceRoot":"","sources":["../../../src/fiscal/contracts/nfse-adn-endpoint.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,KAAK,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAmC1F,qBAAa,0BAA2B,SAAQ,mBAAmB;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAQpC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,oBAAoB,EACjC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,GACtB,MAAM,CAkCR"}

package/dist/fiscal/contracts/nfse-adn-endpoint.js

@@ -0,0 +1,103 @@
+import { URL } from 'node:url';
+import { FiscalProviderError } from '../ingestion/provider.js';
+import { NFSE_ADN_HOSTS } from './nfse-adn-contract.js';
+/**
+ * Para onde o worker fiscal PODE abrir socket — e a resposta é uma lista curta.
+ *
+ * ## O risco concreto, e não teórico
+ *
+ * O transporte do ADN aceitava `baseUrl` livre. Ela existe por um motivo
+ * legítimo: o servidor sintético da suíte precisa entrar no lugar do host
+ * oficial. Mas nada impedia que esse mesmo campo chegasse de configuração de
+ * tenant, de uma coluna de cadastro de provedor ou de um parâmetro de rota — e
+ * então o worker fiscal, que roda dentro da rede com o certificado do cliente
+ * carregado, vira um proxy HTTP de destino escolhido por terceiro.
+ *
+ * O dano não é abstrato: o alvo natural de um SSRF em nuvem é o metadata do
+ * provedor, e o corpo da resposta seria devolvido ao chamador pelo caminho de
+ * ingestão. Pior: o certificado ICP-Brasil do CONTRIBUINTE seria apresentado ao
+ * destino escolhido pelo atacante.
+ *
+ * ## Por que allowlist, e por que tão estreita
+ *
+ * Uma denylist ("não pode ser IP interno") erra por construção: DNS rebinding,
+ * redirecionamento, IPv6 mapeado, notação decimal de IP. A allowlist responde à
+ * pergunta certa — "quais são os destinos legítimos?" — e a resposta oficial tem
+ * exatamente dois nomes.
+ *
+ * Para o ambiente sintético o destino permitido é o loopback, e só ele. Um
+ * servidor de teste que precise sair da máquina é um teste que precisa de outro
+ * desenho, não de um portão mais frouxo.
+ */
+/** Onde o ambiente sintético pode falar. Nada além da própria máquina. */
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+export class AdnEndpointNotAllowedError extends FiscalProviderError {
+    detail;
+    constructor(detail) {
+        super('not_allowed', `destino recusado pela allowlist do ADN: ${detail}`, 'ENDPOINT_NOT_ALLOWED');
+        this.detail = detail;
+        this.name = 'AdnEndpointNotAllowedError';
+    }
+}
+/**
+ * Resolve e AUTORIZA a base do ADN para um ambiente.
+ *
+ * Devolve sempre uma URL sem barra final, para que a composição de caminho em
+ * `adnDfeUrl` seja uma concatenação e não uma decisão.
+ */
+export function resolveAdnBaseUrl(environment, baseUrl) {
+    if (environment === 'synthetic') {
+        if (!baseUrl) {
+            // Sem base explícita, o default apontaria para o host oficial — e um teste
+            // que "esqueceu" de configurar o servidor de mentira falaria com o governo.
+            throw new FiscalProviderError('invalid', 'ambiente sintético exige baseUrl explícita', 'SYNTHETIC_BASE_URL_REQUIRED');
+        }
+        const u = parseOrRefuse(baseUrl);
+        if (!LOOPBACK.has(u.hostname)) {
+            throw new AdnEndpointNotAllowedError('sintético só fala com loopback');
+        }
+        return semBarraFinal(u);
+    }
+    const oficial = NFSE_ADN_HOSTS[environment === 'production' ? 'production' : 'homologation'];
+    if (!baseUrl)
+        return `https://${oficial}`;
+    const u = parseOrRefuse(baseUrl);
+    // Comparação por igualdade do hostname, e nunca `includes`/`endsWith`: um
+    // `endsWith('nfse.gov.br')` aceitaria `adn.nfse.gov.br.exemplo.com`, que é o
+    // truque mais antigo do gênero.
+    if (u.hostname !== oficial) {
+        throw new AdnEndpointNotAllowedError('host fora da lista oficial do ambiente');
+    }
+    // Porta não padrão contra o host oficial não é um cenário legítimo: seria um
+    // desvio para um serviço diferente no mesmo nome.
+    if (u.port !== '' && u.port !== '443') {
+        throw new AdnEndpointNotAllowedError('porta não padrão contra host oficial');
+    }
+    return semBarraFinal(u);
+}
+function parseOrRefuse(raw) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new AdnEndpointNotAllowedError('URL ilegível');
+    }
+    // `http:` aqui não é degradação de conforto: é o certificado do CLIENTE
+    // viajando em claro contra a Receita.
+    if (u.protocol !== 'https:')
+        throw new AdnEndpointNotAllowedError('esquema não é https');
+    // Credencial embutida na URL vaza em log, em `err.stack` e em trilha. O
+    // caminho legítimo para credencial neste motor é o material de TLS.
+    if (u.username !== '' || u.password !== '') {
+        throw new AdnEndpointNotAllowedError('URL com credencial embutida');
+    }
+    if (u.search !== '' || u.hash !== '') {
+        throw new AdnEndpointNotAllowedError('base com query ou fragmento');
+    }
+    return u;
+}
+function semBarraFinal(u) {
+    return `${u.origin}${u.pathname}`.replace(/\/+$/, '');
+}
+//# sourceMappingURL=nfse-adn-endpoint.js.map

package/dist/fiscal/contracts/nfse-adn-endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nfse-adn-endpoint.js","sourceRoot":"","sources":["../../../src/fiscal/contracts/nfse-adn-endpoint.ts"],"names":[],"mappings":"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"}

package/dist/fiscal/contracts/nfse-adn-envelope.d.ts

@@ -0,0 +1,77 @@
+import { FiscalProviderError, type FiscalFetchResult } from '../ingestion/provider.js';
+import { type AdnEnvelopeProfile } from './nfse-adn-contract.js';
+/**
+ * O leitor de envelope do ADN — estrito por construção.
+ *
+ * ## A propriedade que este arquivo inteiro existe para garantir
+ *
+ *   RESPOSTA NÃO RECONHECIDA ≠ SUCESSO COM ZERO DOCUMENTOS
+ *
+ * São indistinguíveis para o cursor e opostos para o negócio. "Zero documentos"
+ * é o dia normal de um cliente que não emitiu nem recebeu nota; "não reconheci"
+ * é um defeito que precisa parar tudo. A versão anterior deste leitor podia
+ * confundi-los de três maneiras, e todas as três estão fechadas aqui:
+ *
+ *   1. `LoteDFe ?? loteDFe` — se o nome real fosse um terceiro, o `??`
+ *      devolveria `undefined` e o parser lançaria; mas um envelope que POSSUÍSSE
+ *      `LoteDFe: []` por outro motivo passaria como lote vazio legítimo. Agora
+ *      os nomes vêm do PERFIL, um só conjunto, e o que não bate não é lido.
+ *   2. `gunzipSync(...)` com `catch { raw = compactado }` — conteúdo que não é
+ *      gzip virava "conteúdo não compactado" em silêncio. Um base64 de HTML de
+ *      página de erro de proxy passaria por aqui como documento fiscal, e só
+ *      falharia lá adiante, sem dizer que o problema era o transporte.
+ *   3. Ausência de teto de descompressão — 200 bytes de gzip hostil viram
+ *      gigabytes na memória do worker.
+ *
+ * ## O terceiro estado, que não é erro nem sucesso genérico
+ *
+ * O ADN representa "não há documentos" como uma REJEIÇÃO com código (E2215 a
+ * partir de um NSU, E2230 para NSU pontual — ANEXO_IV, aba
+ * `ADN-RN_DISTRIB_MUN_CONTRIB`). No vocabulário dele é rejeição; no nosso é o
+ * dia normal. Tratá-lo como erro encheria a caixa de intervenções de escritórios
+ * cujos clientes simplesmente não tiveram nota na semana.
+ *
+ * Ele é reconhecido, nomeado, e devolvido como lote vazio COM o código na
+ * trilha — o que o mantém distinguível de um envelope que mudou, que lança.
+ */
+/** As formas de não reconhecer uma resposta. Códigos estáveis para a trilha. */
+export type AdnMismatchReason = 'BODY_EMPTY' | 'NOT_JSON' | 'MARKUP_INSTEAD_OF_JSON' | 'NOT_OBJECT' | 'BATCH_FIELD_MISSING' | 'BATCH_NOT_ARRAY' | 'BATCH_OVER_OFFICIAL_LIMIT' | 'ITEM_NOT_OBJECT' | 'ITEM_NSU_INVALID' | 'ITEM_CONTENT_MISSING' | 'ITEM_CONTENT_NOT_BASE64' | 'ITEM_CONTENT_NOT_GZIP' | 'ITEM_CONTENT_DECOMPRESSION_FAILED' | 'ITEM_CONTENT_TOO_LARGE' | 'BATCH_DECOMPRESSED_TOO_LARGE' | 'NSU_POSITION_INVALID' | 'RESPONSE_TOO_LARGE';
+/**
+ * A resposta não corresponde ao contrato declarado.
+ *
+ * Classe `invalid` porque retentar não resolve: o formato não muda entre
+ * tentativas. `providerCode` é SEMPRE `PROTOCOL_CONTRACT_MISMATCH` — um código
+ * único é o que permite ao painel perguntar "o contrato quebrou?" com uma
+ * comparação de igualdade. O detalhe fica em `reason`, que é enumerado e não
+ * carrega um byte do corpo recebido: um corpo hostil não escreve na nossa trilha.
+ */
+export declare class AdnContractMismatchError extends FiscalProviderError {
+    readonly reason: AdnMismatchReason;
+    readonly profileId: string;
+    constructor(reason: AdnMismatchReason, profileId: string);
+}
+export interface AdnEnvelopeReadOptions {
+    readonly profile: AdnEnvelopeProfile;
+    /**
+     * O cursor com que a consulta foi feita.
+     *
+     * Necessário porque um desfecho "não há documentos" NÃO pode devolver
+     * `lastNsu: null`: o pipeline gravaria `null` como posição alcançada e a
+     * próxima execução recomeçaria do zero, reprocessando tudo. A posição de quem
+     * não achou nada é a de onde ele partiu.
+     */
+    readonly fromNsu: string | null;
+    readonly maxResponseBytes?: number;
+    readonly maxDecompressedBytesPerDocument?: number;
+    readonly maxDecompressedBytesPerBatch?: number;
+    readonly maxDocumentsPerBatch?: number;
+}
+/**
+ * Lê o envelope. Devolve lote (possivelmente vazio e RECONHECIDO), ou lança.
+ *
+ * Nunca devolve `documents: []` para uma resposta que não entendeu. Essa é a
+ * invariante, e o teste de mutação da Fase 3 a exercita reintroduzindo o
+ * comportamento antigo e exigindo que a suíte fique vermelha.
+ */
+export declare function readAdnEnvelope(body: Uint8Array, options: AdnEnvelopeReadOptions): FiscalFetchResult;
+//# sourceMappingURL=nfse-adn-envelope.d.ts.map

package/dist/fiscal/contracts/nfse-adn-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nfse-adn-envelope.d.ts","sourceRoot":"","sources":["../../../src/fiscal/contracts/nfse-adn-envelope.ts"],"names":[],"mappings":"AACA,OAAO,EACL,mBAAmB,EACnB,KAAK,iBAAiB,EAEvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB,YAAY,GACZ,UAAU,GACV,wBAAwB,GACxB,YAAY,GACZ,qBAAqB,GACrB,iBAAiB,GACjB,2BAA2B,GAC3B,iBAAiB,GACjB,kBAAkB,GAClB,sBAAsB,GACtB,yBAAyB,GACzB,uBAAuB,GACvB,mCAAmC,GACnC,wBAAwB,GACxB,8BAA8B,GAC9B,sBAAsB,GACtB,oBAAoB,CAAC;AAEzB;;;;;;;;GAQG;AACH,qBAAa,wBAAyB,SAAQ,mBAAmB;IAE7D,QAAQ,CAAC,MAAM,EAAE,iBAAiB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM;gBADjB,MAAM,EAAE,iBAAiB,EACzB,SAAS,EAAE,MAAM;CAS7B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,+BAA+B,CAAC,EAAE,MAAM,CAAC;IAClD,QAAQ,CAAC,4BAA4B,CAAC,EAAE,MAAM,CAAC;IAC/C,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;AAOD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,sBAAsB,GAC9B,iBAAiB,CAoJnB"}