@baruk/core 0.4.2 → 0.5.0

package/dist/cjs/fiscal/contracts/nfse-adn-envelope.js

@@ -0,0 +1,220 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdnContractMismatchError = void 0;
+exports.readAdnEnvelope = readAdnEnvelope;
+const node_zlib_1 = require("node:zlib");
+const provider_js_1 = require("../ingestion/provider.js");
+const nfse_adn_contract_js_1 = require("./nfse-adn-contract.js");
+/**
+ * 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.
+ */
+class AdnContractMismatchError extends provider_js_1.FiscalProviderError {
+    reason;
+    profileId;
+    constructor(reason, profileId) {
+        super('invalid', `resposta do ADN não corresponde ao perfil ${profileId} (${reason})`, 'PROTOCOL_CONTRACT_MISMATCH');
+        this.reason = reason;
+        this.profileId = profileId;
+        this.name = 'AdnContractMismatchError';
+    }
+}
+exports.AdnContractMismatchError = AdnContractMismatchError;
+/** Base64 canônico. `Buffer.from(x,'base64')` ignora lixo em silêncio — este não. */
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+/** Assinatura do gzip (RFC 1952 §2.3.1): `1f 8b`. Dois bytes, sem ambiguidade. */
+const GZIP_MAGIC = [0x1f, 0x8b];
+/**
+ * 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.
+ */
+function readAdnEnvelope(body, options) {
+    const { profile, fromNsu } = options;
+    const maxBytes = options.maxResponseBytes ?? nfse_adn_contract_js_1.NFSE_ADN_LIMITS.maxResponseBytes.value;
+    const maxDoc = options.maxDecompressedBytesPerDocument ??
+        nfse_adn_contract_js_1.NFSE_ADN_LIMITS.maxDecompressedBytesPerDocument.value;
+    const maxLote = options.maxDecompressedBytesPerBatch ?? nfse_adn_contract_js_1.NFSE_ADN_LIMITS.maxDecompressedBytesPerBatch.value;
+    const maxItens = options.maxDocumentsPerBatch ?? nfse_adn_contract_js_1.NFSE_ADN_LIMITS.maxDocumentsPerBatch.value;
+    // A anotação de tipo explícita não é decoração: sem ela o TypeScript não
+    // propaga o `never` de uma arrow function, e todo `if (...) recusa(...)`
+    // deixaria de estreitar o tipo depois — obrigando a um `return` ou a um `!`
+    // em cada ponto, que é exatamente onde um dia alguém erra.
+    const recusa = (r) => {
+        throw new AdnContractMismatchError(r, profile.id);
+    };
+    if (body.byteLength > maxBytes)
+        recusa('RESPONSE_TOO_LARGE');
+    if (body.byteLength === 0)
+        recusa('BODY_EMPTY');
+    const texto = Buffer.from(body).toString('utf8').trim();
+    // Página de erro de proxy, portal de captura, HTML de WAF. Todos começam com
+    // `<`, e todos seriam "JSON inválido" — um diagnóstico que manda a pessoa
+    // olhar o lugar errado. Nomear o caso aponta para a rede, não para o parser.
+    if (texto.startsWith('<'))
+        recusa('MARKUP_INSTEAD_OF_JSON');
+    let json;
+    try {
+        json = JSON.parse(texto);
+    }
+    catch {
+        recusa('NOT_JSON');
+    }
+    if (json === null || typeof json !== 'object' || Array.isArray(json))
+        recusa('NOT_OBJECT');
+    const raiz = json;
+    // ── Rejeição RECONHECIDA ────────────────────────────────────────────────
+    //
+    // Antes de exigir o lote: uma rejeição legítima do ADN não traz lote nenhum,
+    // e cobrá-lo dela transformaria "seu cliente não teve nota" em "o contrato
+    // quebrou" — o alarme mais caro que este produto poderia dar.
+    const codigo = leiaCodigo(raiz[profile.codeField]);
+    if (codigo) {
+        const oficial = nfse_adn_contract_js_1.NFSE_ADN_OFFICIAL_CODES[codigo];
+        if (oficial?.outcome === 'no_documents') {
+            return {
+                documents: [],
+                // A posição de quem não achou nada é a de onde partiu. Ver o comentário
+                // de `fromNsu` acima: `null` aqui faria a próxima execução recomeçar.
+                lastNsu: fromNsu,
+                maxNsu: null,
+                // Esgotado: o Manual dos Municípios §1.4.2.b manda esperar uma hora
+                // "caso receba a indicação que não existem mais documentos".
+                exhausted: true,
+                providerStatus: codigo,
+            };
+        }
+        if (oficial) {
+            throw new provider_js_1.FiscalProviderError(oficial.errorClass ?? 'unknown', `ADN recusou: ${oficial.meaning}`, codigo);
+        }
+        // Código do ADN que não está no nosso mapa. NÃO é lote vazio, e NÃO é
+        // `invalid`: o governo pode ter acrescentado um código sem mudar o
+        // envelope. `unknown` é tratado como transitório com teto pelo motor —
+        // errar para "tente de novo com espera" custa latência; errar para "está
+        // tudo bem, zero documentos" custa uma fiscalização.
+        throw new provider_js_1.FiscalProviderError('unknown', 'ADN devolveu código não catalogado', codigo);
+    }
+    // ── Lote ────────────────────────────────────────────────────────────────
+    if (!(profile.batchField in raiz))
+        recusa('BATCH_FIELD_MISSING');
+    const lote = raiz[profile.batchField];
+    if (!Array.isArray(lote))
+        recusa('BATCH_NOT_ARRAY');
+    const itens = lote;
+    // O teto de 50 é oficial. Um lote maior significa que estamos falando com
+    // algo que não é o ADN — ou que o contrato mudou. Nos dois casos, parar.
+    if (itens.length > maxItens)
+        recusa('BATCH_OVER_OFFICIAL_LIMIT');
+    const documents = [];
+    let descompactadoNoLote = 0;
+    for (const item of itens) {
+        if (item === null || typeof item !== 'object' || Array.isArray(item))
+            recusa('ITEM_NOT_OBJECT');
+        const linha = item;
+        const nsu = leiaNsu(linha[profile.itemNsuField]);
+        if (nsu === null)
+            recusa('ITEM_NSU_INVALID');
+        const conteudo = linha[profile.itemContentField];
+        if (typeof conteudo !== 'string' || conteudo.length === 0)
+            recusa('ITEM_CONTENT_MISSING');
+        if (!BASE64.test(conteudo))
+            recusa('ITEM_CONTENT_NOT_BASE64');
+        const bytes = Buffer.from(conteudo, 'base64');
+        let raw;
+        if (profile.contentEncoding === 'gzip+base64') {
+            // A verificação da assinatura vem ANTES da descompressão, e substitui o
+            // `try/catch` que virava fallback. Sem ela, "não é gzip" e "é gzip
+            // corrompido" chegam pelo mesmo caminho — e o antigo `catch` respondia
+            // aos dois tratando os bytes como XML.
+            if (bytes.length < 2 || bytes[0] !== GZIP_MAGIC[0] || bytes[1] !== GZIP_MAGIC[1]) {
+                recusa('ITEM_CONTENT_NOT_GZIP');
+            }
+            try {
+                // `maxOutputLength` é a defesa contra bomba de descompressão: o zlib
+                // aborta ao ultrapassar, em vez de alocar até o processo morrer.
+                raw = new Uint8Array((0, node_zlib_1.gunzipSync)(bytes, { maxOutputLength: maxDoc }));
+            }
+            catch (err) {
+                // O zlib distingue os dois casos, e a distinção importa: "grande demais"
+                // é possivelmente hostil e "corrompido" é possivelmente rede.
+                const code = err?.code;
+                if (code === 'ERR_BUFFER_TOO_LARGE')
+                    recusa('ITEM_CONTENT_TOO_LARGE');
+                recusa('ITEM_CONTENT_DECOMPRESSION_FAILED');
+            }
+        }
+        else {
+            if (bytes.length > maxDoc)
+                recusa('ITEM_CONTENT_TOO_LARGE');
+            raw = new Uint8Array(bytes);
+        }
+        descompactadoNoLote += raw.byteLength;
+        // O teto do LOTE existe porque o produto dos tetos individuais não é um
+        // teto: 50 documentos de 8 MiB seriam 400 MiB perfeitamente "válidos".
+        if (descompactadoNoLote > maxLote)
+            recusa('BATCH_DECOMPRESSED_TOO_LARGE');
+        documents.push({ nsu, raw, mimeType: 'application/xml' });
+    }
+    const ultimo = leiaPosicao(raiz, profile.lastNsuField, recusa);
+    const maximo = leiaPosicao(raiz, profile.maxNsuField, recusa);
+    // Sem `ultNSU` declarado, a posição é a do último item — e, se nem item houve,
+    // é de onde partimos. Jamais `null`: ver o comentário de `fromNsu`.
+    const lastNsu = ultimo ?? documents.at(-1)?.nsu ?? fromNsu;
+    return {
+        documents,
+        lastNsu,
+        maxNsu: maximo,
+        // Esgotado é o servidor DECLARANDO que a posição alcançou o máximo
+        // (Manual dos Municípios §1.4.2.b: "Se o NSU informado (ultNSU) for igual ao
+        // maior NSU do Ambiente Nacional (maxNSU), então não existem mais
+        // documentos"). Nunca por lote vazio: um lote vazio no meio da faixa não
+        // autoriza a espera de uma hora, e tratá-lo assim atrasaria o cliente à toa.
+        exhausted: lastNsu !== null && maximo !== null && lastNsu === maximo,
+        providerStatus: null,
+    };
+}
+/**
+ * NSU como o contrato o define: dígitos, sem sinal, sem separador.
+ *
+ * Número JSON é aceito e normalizado para texto — o ADN pode enviá-lo como
+ * número, e recusá-lo seria rigor sem propósito. O que não é aceito é qualquer
+ * coisa que não seja uma posição: `null`, negativo, decimal, texto com letra.
+ * Um NSU que não é posição não pode governar cursor.
+ */
+function leiaNsu(v) {
+    if (typeof v === 'number') {
+        return Number.isSafeInteger(v) && v >= 0 ? String(v) : null;
+    }
+    if (typeof v === 'string' && /^\d{1,20}$/.test(v))
+        return v;
+    return null;
+}
+/** `ultNSU`/`maxNSU`: ausente é legítimo; presente e inválido, não. */
+function leiaPosicao(raiz, campo, recusa) {
+    if (!(campo in raiz))
+        return null;
+    const bruto = raiz[campo];
+    if (bruto === null || bruto === undefined)
+        return null;
+    const nsu = leiaNsu(bruto);
+    // Presente e ilegível é diferente de ausente: o primeiro é contrato quebrado,
+    // o segundo é campo opcional. Tratá-los igual perderia a quebra.
+    if (nsu === null)
+        recusa('NSU_POSITION_INVALID');
+    return nsu;
+}
+/** O código do ADN, quando a resposta é uma rejeição. `E` seguido de dígitos. */
+function leiaCodigo(v) {
+    if (typeof v !== 'string')
+        return null;
+    const t = v.trim().toUpperCase();
+    return /^E\d{4}$/.test(t) ? t : null;
+}
+//# sourceMappingURL=nfse-adn-envelope.js.map

package/dist/cjs/fiscal/contracts/nfse-adn-envelope.js.map

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

package/dist/cjs/fiscal/coverage/model.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unknownCoverage = unknownCoverage;
+exports.resolveFiscalCoverage = resolveFiscalCoverage;
+exports.coverageForClient = coverageForClient;
+exports.listFiscalCoverage = listFiscalCoverage;
+exports.assumesUniversalNfseCoverage = assumesUniversalNfseCoverage;
+const repository_js_1 = require("../repository.js");
+/** A resposta quando nem a linha padrão existe. Desconhecida, nunca coberta. */
+function unknownCoverage(documentType, scope, code) {
+    return {
+        id: 'unknown',
+        documentType,
+        jurisdictionScope: scope,
+        jurisdictionCode: code,
+        provider: 'desconhecido',
+        coverageStatus: 'UNKNOWN',
+        automationMethod: null,
+        credentialRequirement: 'unknown',
+        environments: [],
+        fallbackType: 'manual_upload',
+        lastVerifiedAt: null,
+        sourceReference: null,
+        notes: 'Nenhuma linha de cobertura para esta combinação. Ninguém mediu.',
+    };
+}
+const map = (r) => ({
+    id: r.id,
+    documentType: r.document_type,
+    jurisdictionScope: r.jurisdiction_scope,
+    jurisdictionCode: r.jurisdiction_code,
+    provider: r.provider,
+    coverageStatus: r.coverage_status,
+    automationMethod: r.automation_method,
+    credentialRequirement: r.credential_requirement,
+    environments: r.environments ?? [],
+    fallbackType: r.fallback_type,
+    lastVerifiedAt: r.last_verified_at ? r.last_verified_at.toISOString().slice(0, 10) : null,
+    sourceReference: r.source_reference,
+    notes: r.notes,
+});
+const COLUMNS = `id, document_type, jurisdiction_scope, jurisdiction_code, provider,
+                 coverage_status, automation_method, credential_requirement, environments,
+                 fallback_type, last_verified_at, source_reference, notes`;
+/**
+ * Resolve a cobertura de uma pergunta específica.
+ *
+ * Duas etapas, e a segunda NUNCA sobe de escopo: a linha exata do código, e
+ * depois a linha padrão do MESMO escopo. Não há terceira etapa.
+ */
+async function resolveFiscalCoverage(tx, input) {
+    const code = input.jurisdictionCode ?? null;
+    if (code) {
+        const exact = await tx `
+      SELECT ${tx.unsafe(COLUMNS)} FROM fiscal_coverage
+       WHERE document_type = ${input.documentType}
+         AND jurisdiction_scope = ${input.jurisdictionScope}
+         AND jurisdiction_code = ${code}
+       LIMIT 1
+    `;
+        if (exact[0])
+            return map(exact[0]);
+    }
+    const fallback = await tx `
+    SELECT ${tx.unsafe(COLUMNS)} FROM fiscal_coverage
+     WHERE document_type = ${input.documentType}
+       AND jurisdiction_scope = ${input.jurisdictionScope}
+       AND jurisdiction_code IS NULL
+     LIMIT 1
+  `;
+    if (fallback[0])
+        return { ...map(fallback[0]), jurisdictionCode: code };
+    return unknownCoverage(input.documentType, input.jurisdictionScope, code);
+}
+/**
+ * A cobertura que vale para um CLIENTE — a pergunta que a tela realmente faz.
+ *
+ * NFS-e é municipal por natureza: quem recolhe ISS é a prefeitura. Por isso a
+ * pergunta pelo cliente vai ao escopo municipal, e é ali que ela encontra
+ * `UNKNOWN` enquanto ninguém tiver medido a adesão daquele município. NF-e e
+ * CT-e são de distribuição nacional, e a pergunta é nacional.
+ */
+async function coverageForClient(tx, input) {
+    const jurisdiction = await (0, repository_js_1.loadClientJurisdiction)(tx, input.clientId);
+    if (input.documentType === 'nfse') {
+        const coverage = await resolveFiscalCoverage(tx, {
+            documentType: 'nfse',
+            jurisdictionScope: 'municipal',
+            jurisdictionCode: jurisdiction.cityIbge,
+        });
+        // Sem o IBGE do cliente não dá para nem PERGUNTAR pelo município certo. É um
+        // dado que falta, e dizer isso é diferente de dizer que não há cobertura.
+        return { ...coverage, jurisdictionKnown: jurisdiction.cityIbge !== null };
+    }
+    const coverage = await resolveFiscalCoverage(tx, {
+        documentType: input.documentType,
+        jurisdictionScope: 'national',
+        jurisdictionCode: null,
+    });
+    return { ...coverage, jurisdictionKnown: true };
+}
+/** O catálogo inteiro, para a tela de cobertura. */
+async function listFiscalCoverage(tx) {
+    const rows = await tx `
+    SELECT ${tx.unsafe(COLUMNS)} FROM fiscal_coverage
+     ORDER BY document_type, jurisdiction_scope, jurisdiction_code NULLS FIRST
+  `;
+    return rows.map(map);
+}
+/**
+ * Existe alguma afirmação de cobertura NACIONAL para NFS-e municipal?
+ *
+ * A pergunta parece estranha e é o oráculo de `UNIVERSAL_NFSE_COVERAGE_ASSUMED`:
+ * o modelo passa se, e somente se, uma pergunta municipal sem medição não
+ * devolver "coberto". Um teste que só verificasse a linha nacional passaria com
+ * o defeito presente.
+ */
+async function assumesUniversalNfseCoverage(tx) {
+    const resolved = await resolveFiscalCoverage(tx, {
+        documentType: 'nfse',
+        jurisdictionScope: 'municipal',
+        // Um IBGE que ninguém mediu. É o caso da esmagadora maioria dos 5.570.
+        jurisdictionCode: '9999999',
+    });
+    return resolved.coverageStatus !== 'UNKNOWN';
+}
+//# sourceMappingURL=model.js.map

package/dist/cjs/fiscal/coverage/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../../src/fiscal/coverage/model.ts"],"names":[],"mappings":";;AA2DA,0CAoBC;AA4CD,sDA+BC;AAUD,8CAuBC;AAGD,gDAMC;AAUD,oEAQC;AApND,oDAA0D;AAwD1D,gFAAgF;AAChF,SAAgB,eAAe,CAC7B,YAAgC,EAChC,KAAoB,EACpB,IAAmB;IAEnB,OAAO;QACL,EAAE,EAAE,SAAS;QACb,YAAY;QACZ,iBAAiB,EAAE,KAAK;QACxB,gBAAgB,EAAE,IAAI;QACtB,QAAQ,EAAE,cAAc;QACxB,cAAc,EAAE,SAAS;QACzB,gBAAgB,EAAE,IAAI;QACtB,qBAAqB,EAAE,SAAS;QAChC,YAAY,EAAE,EAAE;QAChB,YAAY,EAAE,eAAe;QAC7B,cAAc,EAAE,IAAI;QACpB,eAAe,EAAE,IAAI;QACrB,KAAK,EAAE,iEAAiE;KACzE,CAAC;AACJ,CAAC;AAkBD,MAAM,GAAG,GAAG,CAAC,CAAM,EAAkB,EAAE,CAAC,CAAC;IACvC,EAAE,EAAE,CAAC,CAAC,EAAE;IACR,YAAY,EAAE,CAAC,CAAC,aAAa;IAC7B,iBAAiB,EAAE,CAAC,CAAC,kBAAkB;IACvC,gBAAgB,EAAE,CAAC,CAAC,iBAAiB;IACrC,QAAQ,EAAE,CAAC,CAAC,QAAQ;IACpB,cAAc,EAAE,CAAC,CAAC,eAAe;IACjC,gBAAgB,EAAE,CAAC,CAAC,iBAAiB;IACrC,qBAAqB,EAAE,CAAC,CAAC,sBAAsB;IAC/C,YAAY,EAAE,CAAC,CAAC,YAAY,IAAI,EAAE;IAClC,YAAY,EAAE,CAAC,CAAC,aAAa;IAC7B,cAAc,EAAE,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI;IACzF,eAAe,EAAE,CAAC,CAAC,gBAAgB;IACnC,KAAK,EAAE,CAAC,CAAC,KAAK;CACf,CAAC,CAAC;AAEH,MAAM,OAAO,GAAG;;0EAE0D,CAAC;AAE3E;;;;;GAKG;AACI,KAAK,UAAU,qBAAqB,CACzC,EAAM,EACN,KAIC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,gBAAgB,IAAI,IAAI,CAAC;IAE5C,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,KAAK,GAAG,MAAM,EAAE,CAAO;eAClB,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC;+BACF,KAAK,CAAC,YAAY;oCACb,KAAK,CAAC,iBAAiB;mCACxB,IAAI;;KAElC,CAAC;QACF,IAAI,KAAK,CAAC,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAO;aACrB,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC;6BACF,KAAK,CAAC,YAAY;kCACb,KAAK,CAAC,iBAAiB;;;GAGtD,CAAC;IACF,IAAI,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC;IAExE,OAAO,eAAe,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,iBAAiB,EAAE,IAAI,CAAC,CAAC;AAC5E,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,iBAAiB,CACrC,EAAM,EACN,KAA6D;IAE7D,MAAM,YAAY,GAAG,MAAM,IAAA,sCAAsB,EAAC,EAAE,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAEtE,IAAI,KAAK,CAAC,YAAY,KAAK,MAAM,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,MAAM,qBAAqB,CAAC,EAAE,EAAE;YAC/C,YAAY,EAAE,MAAM;YACpB,iBAAiB,EAAE,WAAW;YAC9B,gBAAgB,EAAE,YAAY,CAAC,QAAQ;SACxC,CAAC,CAAC;QACH,6EAA6E;QAC7E,0EAA0E;QAC1E,OAAO,EAAE,GAAG,QAAQ,EAAE,iBAAiB,EAAE,YAAY,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;IAC5E,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,qBAAqB,CAAC,EAAE,EAAE;QAC/C,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,iBAAiB,EAAE,UAAU;QAC7B,gBAAgB,EAAE,IAAI;KACvB,CAAC,CAAC;IACH,OAAO,EAAE,GAAG,QAAQ,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC;AAClD,CAAC;AAED,oDAAoD;AAC7C,KAAK,UAAU,kBAAkB,CAAC,EAAM;IAC7C,MAAM,IAAI,GAAG,MAAM,EAAE,CAAO;aACjB,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC;;GAE5B,CAAC;IACF,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,4BAA4B,CAAC,EAAM;IACvD,MAAM,QAAQ,GAAG,MAAM,qBAAqB,CAAC,EAAE,EAAE;QAC/C,YAAY,EAAE,MAAM;QACpB,iBAAiB,EAAE,WAAW;QAC9B,uEAAuE;QACvE,gBAAgB,EAAE,SAAS;KAC5B,CAAC,CAAC;IACH,OAAO,QAAQ,CAAC,cAAc,KAAK,SAAS,CAAC;AAC/C,CAAC"}

package/dist/cjs/fiscal/coverage/requests.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assessRequestCoverage = assessRequestCoverage;
+exports.listRequestCoverage = listRequestCoverage;
+/**
+ * Classifica a cobertura da solicitação de uma competência.
+ *
+ * `FULLY_COVERED_BY_AUTOMATION` exige as DUAS condições, e não uma:
+ * cobertura oficial declarada para a jurisdição E documentos de entrada e saída
+ * presentes. Com só uma delas, o máximo é `PARTIALLY_COVERED` — porque só uma
+ * delas é, literalmente, cobertura parcial.
+ */
+async function assessRequestCoverage(tx, input) {
+    const documentType = input.documentType ?? 'nfse';
+    const [doc] = await tx `
+    SELECT count(*)::int                                   AS total,
+           coalesce(array_agg(DISTINCT direction), '{}')   AS direcoes
+      FROM fiscal_document
+     WHERE client_id = ${input.clientId}
+       AND competence_label = ${input.competenceLabel}
+       AND source <> 'manual'
+  `;
+    const [cov] = await tx `
+    SELECT fc.coverage_status
+      FROM client c
+      LEFT JOIN fiscal_coverage fc
+        ON fc.document_type = ${documentType}
+       AND fc.jurisdiction_scope = ${documentType === 'nfse' ? 'municipal' : 'national'}
+       AND (fc.jurisdiction_code = c.municipality_ibge_code OR fc.jurisdiction_code IS NULL)
+     WHERE c.id = ${input.clientId}
+     ORDER BY fc.jurisdiction_code NULLS LAST
+     LIMIT 1
+  `;
+    const coverageStatus = cov?.coverage_status ?? 'UNKNOWN';
+    const total = doc?.total ?? 0;
+    const direcoes = doc?.direcoes ?? [];
+    const oficial = coverageStatus === 'SUPPORTED_OFFICIAL' || coverageStatus === 'SUPPORTED_PROVIDER';
+    const temEntradaESaida = direcoes.includes('received') && direcoes.includes('issued');
+    const level = total === 0
+        ? 'NOT_COVERED'
+        : oficial && temEntradaESaida
+            ? 'FULLY_COVERED_BY_AUTOMATION'
+            : 'PARTIALLY_COVERED';
+    return {
+        clientId: input.clientId,
+        competenceLabel: input.competenceLabel,
+        level,
+        automaticDocuments: total,
+        directions: direcoes,
+        coverageStatus,
+        autoClosed: false,
+        detail: level === 'NOT_COVERED'
+            ? 'Nenhum documento coletado automaticamente nesta competência.'
+            : level === 'FULLY_COVERED_BY_AUTOMATION'
+                ? `${total} documentos coletados, com entrada e saída, em jurisdição com cobertura oficial.`
+                : oficial
+                    ? `${total} documentos coletados, mas falta ${direcoes.includes('issued') ? 'documento de entrada' : 'documento de saída'}.`
+                    : `${total} documentos coletados, porém a cobertura desta jurisdição é ${coverageStatus}.`,
+    };
+}
+/**
+ * As solicitações de "Documentos fiscais do mês" com sua classificação.
+ *
+ * Leitura pura. Nenhuma linha de `recurring_instance` é tocada — e um teste
+ * confere isso comparando o `updated_at` das solicitações antes e depois, porque
+ * "eu não escrevi nada" é uma afirmação que precisa de oráculo.
+ */
+async function listRequestCoverage(tx, input = {}) {
+    const limit = Math.min(Math.max(input.limit ?? 100, 1), 500);
+    const rows = await tx `
+    SELECT ri.id AS request_id, ri.client_id, c.display_name AS client_name,
+           ri.status, ri.due_date, comp.label AS competence_label
+      FROM recurring_instance ri
+      JOIN recurring_item_type rit ON rit.id = ri.item_type_id
+      JOIN competence comp ON comp.id = ri.competence_id
+      JOIN client c ON c.id = ri.client_id
+     WHERE rit.key = 'docs_fiscais_mes'
+       AND ri.deleted_at IS NULL
+       AND ${input.competenceLabel ? tx `comp.label = ${input.competenceLabel}` : tx `true`}
+     ORDER BY comp.label DESC, c.display_name
+     LIMIT ${limit}
+  `;
+    const out = [];
+    for (const r of rows) {
+        const assessment = await assessRequestCoverage(tx, {
+            clientId: r.client_id,
+            competenceLabel: r.competence_label,
+        });
+        out.push({
+            ...assessment,
+            requestId: r.request_id,
+            clientName: r.client_name,
+            status: r.status,
+            dueDate: r.due_date ? r.due_date.toISOString().slice(0, 10) : null,
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=requests.js.map

package/dist/cjs/fiscal/coverage/requests.js.map

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

package/dist/cjs/fiscal/credentials/material.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTlsMaterial = buildTlsMaterial;
+exports.loadFiscalTlsMaterial = loadFiscalTlsMaterial;
+const node_crypto_1 = require("node:crypto");
+const repository_js_1 = require("../../vault/repository.js");
+const secret_boundary_js_1 = require("../sync/secret-boundary.js");
+/**
+ * Constrói o material a partir do envelope decifrado.
+ *
+ * Separado da leitura do banco de propósito: é esta função que o teste
+ * exercita com um PKCS#12 sintético, sem precisar de cofre nem de tenant.
+ */
+function buildTlsMaterial(raw) {
+    let envelope;
+    try {
+        envelope = JSON.parse(raw);
+    }
+    catch {
+        // Sem `err.message`: um JSON malformado costuma vir citado inteiro na
+        // exceção, e o "JSON malformado" aqui é um certificado.
+        return { status: 'unavailable', reason: 'envelope_unreadable' };
+    }
+    if (!envelope || typeof envelope !== 'object' || !('format' in envelope)) {
+        return { status: 'unavailable', reason: 'envelope_unreadable' };
+    }
+    try {
+        if (envelope.format === 'pkcs12') {
+            if (typeof envelope.material !== 'string' || envelope.material === '') {
+                return { status: 'unavailable', reason: 'envelope_unreadable' };
+            }
+            const pfx = Buffer.from(envelope.material, 'base64');
+            if (pfx.byteLength === 0)
+                return { status: 'unavailable', reason: 'envelope_unreadable' };
+            return { status: 'ok', material: sealed({ pfx, passphrase: envelope.passphrase }) };
+        }
+        if (envelope.format === 'pem') {
+            if (typeof envelope.cert !== 'string' || typeof envelope.key !== 'string') {
+                return { status: 'unavailable', reason: 'envelope_unreadable' };
+            }
+            const cert = Buffer.from(envelope.cert, 'base64');
+            const key = Buffer.from(envelope.key, 'base64');
+            const ca = (envelope.ca ?? []).map((c) => Buffer.from(c, 'base64'));
+            if (cert.byteLength === 0 || key.byteLength === 0) {
+                return { status: 'unavailable', reason: 'envelope_unreadable' };
+            }
+            return { status: 'ok', material: sealed({ cert, key, ca }) };
+        }
+    }
+    catch {
+        return { status: 'unavailable', reason: 'envelope_unreadable' };
+    }
+    return { status: 'unavailable', reason: 'unsupported_format' };
+}
+/**
+ * Embrulha os buffers com a impressão digital e com o descarte.
+ *
+ * A impressão é do material APRESENTADO (o `.pfx` ou o `cert`), nunca da chave
+ * privada: identificar qual certificado foi usado não deve exigir tocar no
+ * segredo, nem sequer para calcular um hash.
+ */
+function sealed(parts) {
+    const identity = parts.pfx ?? parts.cert ?? Buffer.alloc(0);
+    const fingerprintSha256 = (0, node_crypto_1.createHash)('sha256').update(identity).digest('hex');
+    let disposed = false;
+    return {
+        ...(parts.pfx ? { pfx: parts.pfx } : {}),
+        ...(parts.passphrase ? { passphrase: parts.passphrase } : {}),
+        ...(parts.cert ? { cert: parts.cert } : {}),
+        ...(parts.key ? { key: parts.key } : {}),
+        ...(parts.ca && parts.ca.length > 0 ? { ca: parts.ca } : {}),
+        fingerprintSha256,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            // Zerar não é cerimônia: o Buffer sobrevive no heap até o GC passar, e um
+            // heap dump de produção é um arquivo que alguém abre e guarda.
+            parts.pfx?.fill(0);
+            parts.cert?.fill(0);
+            parts.key?.fill(0);
+            for (const c of parts.ca ?? [])
+                c.fill(0);
+        },
+    };
+}
+/**
+ * Busca o material do certificado de um cliente.
+ *
+ * O ponteiro vem de `digital_certificate.vault_credential_id` — o MESMO domínio
+ * que a prontidão lê, e não uma segunda tabela de credencial fiscal. Duas
+ * origens para o mesmo fato divergiriam na primeira atualização de uma só.
+ *
+ * NUNCA lança por ausência: um cliente sem certificado é estado normal, e uma
+ * exceção aqui derrubaria o worker no meio da carteira por causa do primeiro
+ * cliente não configurado.
+ *
+ * ## O `authorization` não é decoração
+ *
+ * Esta é a única porta do produto para material de certificado, e ela agora
+ * EXIGE o passe que o orquestrador emite depois do último portão. Um chamador
+ * que tente abrir o cofre antes disso — para "só conferir se o certificado
+ * abre", que é sempre como começa — recebe `FiscalSecretBoundaryError` em vez de
+ * uma chave privada. Ver `sync/secret-boundary.ts`.
+ *
+ * A checagem lança ANTES do primeiro `SELECT`: nem a existência do ponteiro é
+ * revelada a quem não passou pelos portões.
+ */
+async function loadFiscalTlsMaterial(tx, keyring, tenantId, input) {
+    (0, secret_boundary_js_1.assertFiscalSecretAccess)(input.authorization, 'loadFiscalTlsMaterial');
+    /*
+     * O passe é AUTÊNTICO — mas para quem?
+     *
+     * `assertFiscalSecretAccess` responde "esta autorização saiu dos portões", e
+     * não "esta autorização é DESTE cliente". A diferença abre um caso que a RLS
+     * não fecha: dentro do MESMO escritório, um passe emitido para o cliente X
+     * abriria o certificado do cliente Y, porque a política de tenant considera as
+     * duas linhas visíveis. É o `WHERE client_id = ...` abaixo que escolhe a
+     * linha, e ele obedece ao parâmetro, não ao passe.
+     *
+     * Hoje o orquestrador emite e usa o passe no mesmo par (tenant, cliente), de
+     * modo que o caso não ocorre. Mas é exatamente esse tipo de invariante — "quem
+     * chama sempre passa os mesmos valores" — que um refactor quebra em silêncio,
+     * e o módulo inteiro da fronteira existe porque convenção não é portão.
+     *
+     * A checagem é de ESCOPO, e vem antes de qualquer consulta: um passe fora do
+     * seu escopo não chega nem a saber se existe certificado do outro lado.
+     */
+    if (input.authorization.tenantId !== tenantId ||
+        input.authorization.clientId !== input.clientId) {
+        throw new secret_boundary_js_1.FiscalSecretBoundaryError('loadFiscalTlsMaterial:scope');
+    }
+    const certType = input.kind === 'certificate_a3' ? 'A3' : 'A1';
+    let rows;
+    try {
+        rows = await tx `
+      SELECT vault_credential_id
+        FROM digital_certificate
+       WHERE client_id = ${input.clientId}
+         AND cert_type = ${certType}
+         AND deleted_at IS NULL
+       ORDER BY expires_at DESC
+       LIMIT 1
+    `;
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === '42P01' || code === '42703') {
+            return { status: 'unavailable', reason: 'no_credential' };
+        }
+        throw err;
+    }
+    const pointer = rows[0]?.vault_credential_id;
+    if (!pointer)
+        return { status: 'unavailable', reason: 'no_credential' };
+    let secret;
+    try {
+        ({ secret } = await (0, repository_js_1.revealSecret)(tx, keyring, tenantId, pointer));
+    }
+    catch {
+        // Ponteiro pendurado, chave de cifra ausente, linha invisível sob RLS: os
+        // três colapsam em "não deu para abrir", e diferenciá-los aqui vazaria a
+        // existência de um registro que a RLS já respondeu como ausente.
+        return { status: 'unavailable', reason: 'vault_unavailable' };
+    }
+    return buildTlsMaterial(secret);
+}
+//# sourceMappingURL=material.js.map

package/dist/cjs/fiscal/credentials/material.js.map

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