@baruk/core 0.3.1 → 0.5.0

package/dist/fiscal/credentials/material.d.ts

@@ -0,0 +1,81 @@
+import type { Tx } from '../../db/client.js';
+import type { Keyring } from '../../vault/crypto.js';
+import type { ClientTlsMaterial } from '../transport/types.js';
+import type { FiscalCredentialKind } from '../eligibility.js';
+import { type FiscalSecretAuthorization } from '../sync/secret-boundary.js';
+/**
+ * O material de TLS mútuo, do cofre para a memória — e para lugar nenhum mais.
+ *
+ * ## As três coisas que este módulo recusa a fazer
+ *
+ * **Não escreve no disco.** Um PKCS#12 em `/tmp` precisa de permissão restrita,
+ * de limpeza garantida em todo caminho de saída (inclusive `SIGKILL`) e de
+ * alguém que lembre das duas coisas no dia do incidente. O `https.Agent` do Node
+ * aceita `Buffer`, então o arquivo temporário nunca é necessário — e "nunca
+ * necessário" é a única forma segura de "nunca esquecido".
+ *
+ * **Não passa por variável de ambiente.** Env var vaza em `env`, em dump de
+ * processo, em painel de provedor e em log de boot. Este ecossistema já perdeu
+ * `DATABASE_URL` inteiro por um `env | grep` bem-intencionado.
+ *
+ * **Não aparece em log, erro ou trilha.** O único campo desta estrutura que
+ * pode ser impresso é `fingerprintSha256`, e é por isso que ele existe: ele
+ * responde "qual certificado foi apresentado?" sem revelar nada dele.
+ *
+ * ## O envelope
+ *
+ * `vault_credential` guarda UM texto cifrado. Para certificado, esse texto é um
+ * JSON com formato declarado — e não o base64 solto, que obrigaria quem lê a
+ * adivinhar se recebeu PKCS#12 ou PEM:
+ *
+ *   {"format":"pkcs12","material":"<base64 do .pfx>","passphrase":"..."}
+ *   {"format":"pem","cert":"<base64 do PEM>","key":"<base64 do PEM>"}
+ *
+ * O `format` é obrigatório. Um envelope sem ele é recusado em vez de tentado
+ * como PKCS#12: adivinhar formato de material criptográfico produz um erro de
+ * OpenSSL seis camadas adiante, indistinguível de senha errada.
+ */
+/** O que deu errado ao buscar o material. Classe, nunca o texto do sistema. */
+export type TlsMaterialFailure = 'no_credential' | 'vault_unavailable' | 'envelope_unreadable' | 'unsupported_format';
+export type TlsMaterialResult = {
+    status: 'ok';
+    material: ClientTlsMaterial;
+} | {
+    status: 'unavailable';
+    reason: TlsMaterialFailure;
+};
+/**
+ * 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.
+ */
+export declare function buildTlsMaterial(raw: string): TlsMaterialResult;
+/**
+ * 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.
+ */
+export declare function loadFiscalTlsMaterial(tx: Tx, keyring: Keyring, tenantId: string, input: {
+    clientId: string;
+    kind?: FiscalCredentialKind;
+    authorization: FiscalSecretAuthorization;
+}): Promise<TlsMaterialResult>;
+//# sourceMappingURL=material.d.ts.map

package/dist/fiscal/credentials/material.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"material.d.ts","sourceRoot":"","sources":["../../../src/fiscal/credentials/material.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAErD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,+EAA+E;AAC/E,MAAM,MAAM,kBAAkB,GAC5B,eAAe,GAAG,mBAAmB,GAAG,qBAAqB,GAAG,oBAAoB,CAAC;AAEvF,MAAM,MAAM,iBAAiB,GACzB;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,iBAAiB,CAAA;CAAE,GAC7C;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAe1D;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAsC/D;AAwCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE;IACL,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B,aAAa,EAAE,yBAAyB,CAAC;CAC1C,GACA,OAAO,CAAC,iBAAiB,CAAC,CA6D5B"}

package/dist/fiscal/credentials/material.js

@@ -0,0 +1,164 @@
+import { createHash } from 'node:crypto';
+import { revealSecret } from '../../vault/repository.js';
+import { FiscalSecretBoundaryError, assertFiscalSecretAccess, } from '../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.
+ */
+export 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 = 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.
+ */
+export async function loadFiscalTlsMaterial(tx, keyring, tenantId, input) {
+    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 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 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/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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"}

package/dist/fiscal/credentials/readiness.d.ts

@@ -0,0 +1,92 @@
+import type { Tx } from '../../db/client.js';
+import type { FiscalCredentialKind, FiscalEnvironment } from '../eligibility.js';
+/**
+ * A prontidão OPERACIONAL da credencial de um cliente.
+ *
+ * ## Por que não bastava o que a Fase 1 já respondia
+ *
+ * `readCredentialReadiness` (eligibility.ts) responde à pergunta do PORTÃO:
+ * "posso deixar este cliente entrar na automação?". Devolve cinco valores e é
+ * suficiente para isso.
+ *
+ * O worker precisa de outra coisa: quando o portão fecha, ele tem de decidir o
+ * que fazer com o fechamento — retentar amanhã, abrir tarefa para uma pessoa, ou
+ * nem uma coisa nem outra. `configured_not_verified` e `expired` reprovam
+ * igualmente no portão e pedem ações opostas depois dele.
+ *
+ * ## Cadastrado não é autorizado — e a separação é um campo, não um comentário
+ *
+ * Existe um erro caro que este módulo existe para tornar indizível: tratar
+ * "o cliente cadastrou um A1 válido" como "estamos autorizados a consultar o
+ * ambiente nacional em nome dele". São fatos independentes.
+ *
+ *   material               o certificado existe, abre, e não venceu.
+ *   providerAuthorization  aquele ambiente JÁ ACEITOU esse material alguma vez.
+ *
+ * O segundo não se deduz do primeiro. Um A1 impecável cujo titular não outorgou
+ * procuração é recusado pelo servidor — e o primeiro campo continua `READY`. Por
+ * isso a autorização sai de FATO OBSERVADO (um `fiscal_sync_run` bem-sucedido
+ * naquele ambiente), e nunca de inferência sobre o cadastro.
+ */
+/**
+ * Estados operacionais.
+ *
+ *   `NOT_CONFIGURED`   não há credencial. Ninguém prometeu nada.
+ *   `READY`            existe, abre, não venceu, e já foi exercida.
+ *   `EXPIRED`          venceu. Só a renovação resolve.
+ *   `INVALID`          revogada, ou o ponteiro para o cofre não resolve.
+ *   `ACCESS_DENIED`    o material serve; o ambiente recusou o TITULAR.
+ *   `REQUIRES_REVIEW`  cadastrada e nunca exercida — ou de um tipo que um cron
+ *                      não consegue usar (A3 vive em token com PIN presencial).
+ */
+export type FiscalCredentialState = 'NOT_CONFIGURED' | 'READY' | 'EXPIRED' | 'INVALID' | 'ACCESS_DENIED' | 'REQUIRES_REVIEW';
+export interface FiscalCredentialReadiness {
+    state: FiscalCredentialState;
+    kind: FiscalCredentialKind | null;
+    /** Só `READY` autoriza o worker a tentar. Nenhum outro estado, por motivo nenhum. */
+    usableByWorker: boolean;
+    /**
+     * `true` quando um retry futuro pode mudar o desfecho sem intervenção humana.
+     * `EXPIRED`, `INVALID` e `ACCESS_DENIED` são `false` — e é isso que decide se
+     * o caso vira linha na fila de pessoas ou só espera.
+     */
+    selfHealing: boolean;
+    expiresOn: string | null;
+    verifiedAt: string | null;
+    /** sha256 truncado do material, quando registrado. Seguro para tela e trilha. */
+    fingerprint: string | null;
+    /**
+     * O ambiente já aceitou esta credencial? Sai de execução observada, jamais do
+     * cadastro. `unknown` é o estado inicial e honesto de todo cliente novo.
+     */
+    providerAuthorization: 'unknown' | 'established';
+    /** Classe e contexto. NUNCA a resposta do provedor. */
+    detail: string;
+}
+/**
+ * Lê a prontidão operacional.
+ *
+ * Roda dentro de `withContext` com o tenant: `digital_certificate` tem RLS FORCE
+ * e é a GUC que decide de quem são as linhas lidas.
+ *
+ * Tolera a ausência da tabela (`42P01`) porque `digital_certificate` pertence à
+ * VERTICAL contábil: um tenant sem ela instalada não tem credencial nenhuma, e
+ * a leitura correta disso é `NOT_CONFIGURED` — não uma exceção que derruba o
+ * worker no meio da carteira.
+ */
+export declare function readFiscalCredentialReadiness(tx: Tx, input: {
+    clientId: string;
+    environment: FiscalEnvironment;
+    source: string;
+    kind?: FiscalCredentialKind;
+}): Promise<FiscalCredentialReadiness>;
+/**
+ * O motivo de intervenção que este estado pede — ou `null` quando não pede.
+ *
+ * Aqui mora a regra de B2.36 que evita a fila ilegível: `REQUIRES_REVIEW` e
+ * `NOT_CONFIGURED` NÃO abrem tarefa. Não configurar automação é uma escolha
+ * legítima do escritório, e transformá-la em pendência encheria a fila de
+ * clientes que ninguém pediu para automatizar.
+ */
+export declare function interventionKindFor(state: FiscalCredentialState): 'certificate_expired' | 'certificate_invalid' | 'auth_required' | null;
+//# sourceMappingURL=readiness.d.ts.map

package/dist/fiscal/credentials/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../../../src/fiscal/credentials/readiness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,qBAAqB,GAC/B,gBAAgB,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,eAAe,GAAG,iBAAiB,CAAC;AAE3F,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,qBAAqB,CAAC;IAC7B,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAClC,qFAAqF;IACrF,cAAc,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,iFAAiF;IACjF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;OAGG;IACH,qBAAqB,EAAE,SAAS,GAAG,aAAa,CAAC;IACjD,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;CAChB;AAoBD;;;;;;;;;;GAUG;AACH,wBAAsB,6BAA6B,CACjD,EAAE,EAAE,EAAE,EACN,KAAK,EAAE;IACL,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,oBAAoB,CAAC;CAC7B,GACA,OAAO,CAAC,yBAAyB,CAAC,CAuHpC;AAWD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,qBAAqB,GAC3B,qBAAqB,GAAG,qBAAqB,GAAG,eAAe,GAAG,IAAI,CAWxE"}

package/dist/fiscal/credentials/readiness.js

@@ -0,0 +1,159 @@
+/**
+ * Classes de erro de verificação que significam "o titular foi recusado".
+ *
+ * Guardadas em `digital_certificate.last_verification_error` como CLASSE — a
+ * coluna existe desde a 1004 justamente para não guardar a mensagem.
+ */
+const DENIED_CLASSES = new Set(['auth', 'not_allowed', 'access_denied', 'permission_denied']);
+/**
+ * Lê a prontidão operacional.
+ *
+ * Roda dentro de `withContext` com o tenant: `digital_certificate` tem RLS FORCE
+ * e é a GUC que decide de quem são as linhas lidas.
+ *
+ * Tolera a ausência da tabela (`42P01`) porque `digital_certificate` pertence à
+ * VERTICAL contábil: um tenant sem ela instalada não tem credencial nenhuma, e
+ * a leitura correta disso é `NOT_CONFIGURED` — não uma exceção que derruba o
+ * worker no meio da carteira.
+ */
+export async function readFiscalCredentialReadiness(tx, input) {
+    const kind = input.kind ?? 'certificate_a1';
+    const base = {
+        kind,
+        usableByWorker: false,
+        selfHealing: false,
+        expiresOn: null,
+        verifiedAt: null,
+        fingerprint: null,
+        providerAuthorization: 'unknown',
+    };
+    if (kind === 'municipal_portal') {
+        // Login de portal municipal não é certificado ICP-Brasil e ainda não tem
+        // onde morar. Um cron também não digita captcha. Negado até existir.
+        return {
+            ...base,
+            state: 'NOT_CONFIGURED',
+            detail: 'portal municipal não tem credencial automatizável neste produto',
+        };
+    }
+    let rows;
+    try {
+        rows = await tx `
+      SELECT id, cert_type, status, expires_at, verified_at,
+             last_verification_error, vault_credential_id
+        FROM digital_certificate
+       WHERE client_id = ${input.clientId}
+         AND cert_type = ${kind === 'certificate_a3' ? 'A3' : 'A1'}
+         AND deleted_at IS NULL
+       ORDER BY expires_at DESC
+       LIMIT 1
+    `;
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === '42P01' || code === '42703') {
+            return { ...base, state: 'NOT_CONFIGURED', detail: 'vertical contábil não aplicada' };
+        }
+        throw err;
+    }
+    const cert = rows[0];
+    if (!cert) {
+        return { ...base, state: 'NOT_CONFIGURED', detail: 'nenhum certificado cadastrado' };
+    }
+    const expiresOn = cert.expires_at ? isoDate(cert.expires_at) : null;
+    const verifiedAt = cert.verified_at?.toISOString() ?? null;
+    const withDates = { ...base, expiresOn, verifiedAt };
+    if (cert.status === 'revoked') {
+        return { ...withDates, state: 'INVALID', detail: 'certificado revogado' };
+    }
+    // Vencimento é fato do calendário, não do registro: um certificado marcado
+    // `active` cuja data passou está vencido mesmo que ninguém tenha corrido para
+    // atualizar a linha.
+    if (cert.expires_at && cert.expires_at < todayUtc()) {
+        return { ...withDates, state: 'EXPIRED', detail: `vencido em ${expiresOn}` };
+    }
+    if (cert.status === 'expired') {
+        return { ...withDates, state: 'EXPIRED', detail: 'marcado como vencido' };
+    }
+    if (cert.last_verification_error && DENIED_CLASSES.has(cert.last_verification_error)) {
+        return {
+            ...withDates,
+            state: 'ACCESS_DENIED',
+            detail: `último acesso recusado (${cert.last_verification_error})`,
+        };
+    }
+    if (kind === 'certificate_a3') {
+        // A3 vive em token ou cartão com PIN digitado por uma pessoa. Ele EXISTE, e
+        // dizer "não tem certificado" seria falso; o que ele não é, é automatizável.
+        return {
+            ...withDates,
+            state: 'REQUIRES_REVIEW',
+            detail: 'A3 exige PIN presencial e não é automatizável por cron',
+        };
+    }
+    if (!cert.vault_credential_id) {
+        // Cadastro sem material é uma promessa sem lastro: a tela diria "tem
+        // certificado" e o worker não teria o que apresentar no handshake.
+        return {
+            ...withDates,
+            state: 'INVALID',
+            detail: 'certificado cadastrado sem material no cofre',
+        };
+    }
+    if (!cert.verified_at) {
+        return {
+            ...withDates,
+            state: 'REQUIRES_REVIEW',
+            detail: 'cadastrado e nunca exercido contra o ambiente oficial',
+        };
+    }
+    // A autorização do provedor sai de execução OBSERVADA. Um `SELECT` sobre a
+    // trilha, e não uma dedução a partir do cadastro.
+    const [ok] = await tx `
+    SELECT count(*)::int AS n
+      FROM fiscal_sync_run
+     WHERE client_id = ${input.clientId}
+       AND source = ${input.source}
+       AND environment = ${input.environment}
+       AND outcome IN ('completed', 'no_documents')
+  `;
+    const established = (ok?.n ?? 0) > 0;
+    return {
+        ...withDates,
+        state: 'READY',
+        usableByWorker: true,
+        selfHealing: true,
+        providerAuthorization: established ? 'established' : 'unknown',
+        detail: established
+            ? 'pronta; o ambiente já aceitou esta credencial'
+            : 'pronta; o ambiente ainda não aceitou esta credencial nenhuma vez',
+    };
+}
+function todayUtc() {
+    const now = new Date();
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+}
+function isoDate(d) {
+    return d.toISOString().slice(0, 10);
+}
+/**
+ * O motivo de intervenção que este estado pede — ou `null` quando não pede.
+ *
+ * Aqui mora a regra de B2.36 que evita a fila ilegível: `REQUIRES_REVIEW` e
+ * `NOT_CONFIGURED` NÃO abrem tarefa. Não configurar automação é uma escolha
+ * legítima do escritório, e transformá-la em pendência encheria a fila de
+ * clientes que ninguém pediu para automatizar.
+ */
+export function interventionKindFor(state) {
+    switch (state) {
+        case 'EXPIRED':
+            return 'certificate_expired';
+        case 'INVALID':
+            return 'certificate_invalid';
+        case 'ACCESS_DENIED':
+            return 'auth_required';
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=readiness.js.map

package/dist/fiscal/credentials/readiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.js","sourceRoot":"","sources":["../../../src/fiscal/credentials/readiness.ts"],"names":[],"mappings":"AAgFA;;;;;GAKG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,aAAa,EAAE,eAAe,EAAE,mBAAmB,CAAC,CAAC,CAAC;AAE9F;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,EAAM,EACN,KAKC;IAED,MAAM,IAAI,GAAyB,KAAK,CAAC,IAAI,IAAI,gBAAgB,CAAC;IAElE,MAAM,IAAI,GAAG;QACX,IAAI;QACJ,cAAc,EAAE,KAAK;QACrB,WAAW,EAAE,KAAK;QAClB,SAAS,EAAE,IAAI;QACf,UAAU,EAAE,IAAI;QAChB,WAAW,EAAE,IAAI;QACjB,qBAAqB,EAAE,SAAkB;KAC1C,CAAC;IAEF,IAAI,IAAI,KAAK,kBAAkB,EAAE,CAAC;QAChC,yEAAyE;QACzE,qEAAqE;QACrE,OAAO;YACL,GAAG,IAAI;YACP,KAAK,EAAE,gBAAgB;YACvB,MAAM,EAAE,iEAAiE;SAC1E,CAAC;IACJ,CAAC;IAED,IAAI,IAAe,CAAC;IACpB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,EAAE,CAAW;;;;2BAIH,KAAK,CAAC,QAAQ;2BACd,IAAI,KAAK,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;;;;KAI7D,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAI,GAAgC,EAAE,IAAI,CAAC;QACrD,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;YACzC,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,gCAAgC,EAAE,CAAC;QACxF,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACrB,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,+BAA+B,EAAE,CAAC;IACvF,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACpE,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,IAAI,IAAI,CAAC;IAC3D,MAAM,SAAS,GAAG,EAAE,GAAG,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;IAErD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,EAAE,GAAG,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;IAC5E,CAAC;IACD,2EAA2E;IAC3E,8EAA8E;IAC9E,qBAAqB;IACrB,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,GAAG,QAAQ,EAAE,EAAE,CAAC;QACpD,OAAO,EAAE,GAAG,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,SAAS,EAAE,EAAE,CAAC;IAC/E,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,EAAE,GAAG,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;IAC5E,CAAC;IACD,IAAI,IAAI,CAAC,uBAAuB,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,uBAAuB,CAAC,EAAE,CAAC;QACrF,OAAO;YACL,GAAG,SAAS;YACZ,KAAK,EAAE,eAAe;YACtB,MAAM,EAAE,2BAA2B,IAAI,CAAC,uBAAuB,GAAG;SACnE,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,KAAK,gBAAgB,EAAE,CAAC;QAC9B,4EAA4E;QAC5E,6EAA6E;QAC7E,OAAO;YACL,GAAG,SAAS;YACZ,KAAK,EAAE,iBAAiB;YACxB,MAAM,EAAE,wDAAwD;SACjE,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC9B,qEAAqE;QACrE,mEAAmE;QACnE,OAAO;YACL,GAAG,SAAS;YACZ,KAAK,EAAE,SAAS;YAChB,MAAM,EAAE,8CAA8C;SACvD,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QACtB,OAAO;YACL,GAAG,SAAS;YACZ,KAAK,EAAE,iBAAiB;YACxB,MAAM,EAAE,uDAAuD;SAChE,CAAC;IACJ,CAAC;IAED,2EAA2E;IAC3E,kDAAkD;IAClD,MAAM,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAiB;;;yBAGf,KAAK,CAAC,QAAQ;sBACjB,KAAK,CAAC,MAAM;2BACP,KAAK,CAAC,WAAW;;GAEzC,CAAC;IACF,MAAM,WAAW,GAAG,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IAErC,OAAO;QACL,GAAG,SAAS;QACZ,KAAK,EAAE,OAAO;QACd,cAAc,EAAE,IAAI;QACpB,WAAW,EAAE,IAAI;QACjB,qBAAqB,EAAE,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS;QAC9D,MAAM,EAAE,WAAW;YACjB,CAAC,CAAC,+CAA+C;YACjD,CAAC,CAAC,kEAAkE;KACvE,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ;IACf,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,EAAE,GAAG,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;AACvF,CAAC;AAED,SAAS,OAAO,CAAC,CAAO;IACtB,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAA4B;IAE5B,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,SAAS;YACZ,OAAO,qBAAqB,CAAC;QAC/B,KAAK,SAAS;YACZ,OAAO,qBAAqB,CAAC;QAC/B,KAAK,eAAe;YAClB,OAAO,eAAe,CAAC;QACzB;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC"}

package/dist/fiscal/eligibility.d.ts

@@ -0,0 +1,106 @@
+import type { Tx } from '../db/client.js';
+/**
+ * Quem entra em automação fiscal — e, sobretudo, quem NÃO entra.
+ *
+ * ## O caso que dá nome a tudo
+ *
+ * Um job de ingestão fiscal escrito da forma óbvia selecionaria
+ * `WHERE deleted_at IS NULL`. No tenant da SC isso alcança hoje dois cadastros
+ * que foram criados em teste do próprio sistema — e alcançaria a carteira real
+ * inteira no dia seguinte a uma importação, sem que ninguém tivesse dito que
+ * aqueles clientes deviam ser acompanhados.
+ *
+ * Documento fiscal não é e-mail. Uma consulta indevida ao DF-e usa o
+ * certificado do CLIENTE contra a Receita, e o `cStat 656` que ela pode render
+ * bloqueia o CNPJ dele — não o nosso. O custo do falso positivo recai sobre um
+ * terceiro que não pediu nada.
+ *
+ * ## Quatro camadas, porque quatro coisas diferentes podem faltar
+ *
+ *   escritório  → ligou automação fiscal? em qual ambiente? (`tenant_fiscal_automation`)
+ *   cliente     → está inscrito, para ESTE tipo de documento? (`client_fiscal_enrollment`)
+ *   credencial  → existe insumo, e alguém o EXERCEU? (`digital_certificate`)
+ *   operação    → o ambiente pedido é real, e o piloto foi declarado? (0047)
+ *
+ * Nenhuma delas tem default permissivo. A ausência de linha nas três tabelas
+ * significa negado, e é isso que faz a migration 0055 não precisar de backfill
+ * nenhum para deixar todo mundo fora: ela cria as tabelas vazias, e vazio já é
+ * a barreira. É a mesma decisão da 0047 — omissão nunca vira autorização,
+ * porque omissão é o estado natural de quem acabou de entrar.
+ *
+ * ## Ambiente é parte da pergunta, não um detalhe
+ *
+ * `synthetic` e `production` não se substituem. Um escritório em `synthetic`
+ * NUNCA fica elegível para um job real, e um escritório em `production` NUNCA
+ * fica elegível para um job sintético. Não há fallback entre eles em nenhuma
+ * direção: fallback é exatamente como documento de homologação entra em
+ * carteira real, e como credencial real acaba exercida por um ensaio.
+ */
+/**
+ * Os três ambientes, e nenhum substitui outro.
+ *
+ * `homologation` é a produção restrita oficial — do ADN
+ * (`adn.producaorestrita.nfse.gov.br`) ou da SEFAZ. Ela não é laboratório: é o
+ * servidor de verdade, respondendo como o real, sobre documento sem valor
+ * fiscal. Colapsá-la em `production` faria alguém abrir a elegibilidade para
+ * ensaiar e, sem perceber, autorizar o ambiente real.
+ */
+export type FiscalEnvironment = 'synthetic' | 'homologation' | 'production';
+export type FiscalDocumentType = 'nfe' | 'nfse' | 'cte' | 'nfce';
+/** Prontidão da credencial. `no_credential` é a AUSÊNCIA de linha, não um valor. */
+export type CredentialReadiness = 'no_credential' | 'configured_not_verified' | 'verified' | 'expired' | 'revoked';
+/**
+ * Tipos de credencial fiscal.
+ *
+ * `certificate_a3` existe no vocabulário porque `digital_certificate` já o
+ * aceita — mas A3 vive em token ou cartão com PIN presencial, e por isso NÃO é
+ * automatizável por um cron. Nomeá-lo permite ao produto dizer "este cliente
+ * tem certificado, e ele não serve para automação" em vez de dizer que não tem.
+ */
+export type FiscalCredentialKind = 'certificate_a1' | 'certificate_a3' | 'municipal_portal';
+export type FiscalDenialReason = 'tenant_automation_disabled' | 'environment_mismatch' | 'real_operation_not_declared' | 'client_not_found' | 'client_inactive' | 'client_not_enrolled' | 'credential_not_ready';
+export interface FiscalEligibility {
+    eligible: boolean;
+    /** Vazio quando elegível. Todos os motivos, não só o primeiro. */
+    reasons: readonly FiscalDenialReason[];
+    environment: FiscalEnvironment | null;
+    credential: CredentialReadiness;
+    detail: string;
+}
+export interface TenantFiscalAutomation {
+    mode: 'disabled' | FiscalEnvironment;
+    enabledAt: string | null;
+    enabledBy: string | null;
+}
+/** Lê o modo do escritório. Ausência de linha é `disabled` — nunca "herda". */
+export declare function getTenantFiscalAutomation(tx: Tx): Promise<TenantFiscalAutomation>;
+/**
+ * Este cliente pode entrar em automação fiscal, neste ambiente, para este tipo?
+ *
+ * Devolve TODOS os motivos de recusa, e não só o primeiro: quem for habilitar
+ * um cliente precisa saber tudo o que falta de uma vez, e não descobrir a
+ * próxima pendência a cada tentativa.
+ *
+ * Precisa rodar dentro de `withContext` com o tenant: as três tabelas têm RLS
+ * FORCE, e é a GUC que decide de quem são as linhas lidas.
+ */
+export declare function evaluateFiscalEligibility(tx: Tx, input: {
+    clientId: string;
+    documentType: FiscalDocumentType;
+    environment: FiscalEnvironment;
+    /** Tipo de credencial exigido pelo documento. */
+    credentialKind?: FiscalCredentialKind;
+}): Promise<FiscalEligibility>;
+/**
+ * Os clientes elegíveis do tenant corrente.
+ *
+ * É esta função — e não uma consulta escrita à mão dentro do worker — que um
+ * job fiscal futuro deve usar para montar o lote. A regra vale porque o caminho
+ * óbvio (`SELECT id FROM client WHERE deleted_at IS NULL`) é justamente o
+ * defeito: ele existe, é fácil de escrever, e não pergunta nada do que importa.
+ */
+export declare function listFiscalEligibleClients(tx: Tx, input: {
+    documentType: FiscalDocumentType;
+    environment: FiscalEnvironment;
+}): Promise<string[]>;
+//# sourceMappingURL=eligibility.d.ts.map

package/dist/fiscal/eligibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eligibility.d.ts","sourceRoot":"","sources":["../../src/fiscal/eligibility.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,cAAc,GAAG,YAAY,CAAC;AAC5E,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAEjE,oFAAoF;AACpF,MAAM,MAAM,mBAAmB,GAC7B,eAAe,GAAG,yBAAyB,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAEnF;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;AAE5F,MAAM,MAAM,kBAAkB,GAC1B,4BAA4B,GAC5B,sBAAsB,GACtB,6BAA6B,GAC7B,kBAAkB,GAClB,iBAAiB,GACjB,qBAAqB,GACrB,sBAAsB,CAAC;AAE3B,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,kEAAkE;IAClE,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACvC,WAAW,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACtC,UAAU,EAAE,mBAAmB,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,UAAU,GAAG,iBAAiB,CAAC;IACrC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,+EAA+E;AAC/E,wBAAsB,yBAAyB,CAAC,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAWvF;AAED;;;;;;;;;GASG;AACH,wBAAsB,yBAAyB,CAC7C,EAAE,EAAE,EAAE,EACN,KAAK,EAAE;IACL,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,kBAAkB,CAAC;IACjC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,iDAAiD;IACjD,cAAc,CAAC,EAAE,oBAAoB,CAAC;CACvC,GACA,OAAO,CAAC,iBAAiB,CAAC,CAyD5B;AA6ED;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,EAAE,EAAE,EAAE,EACN,KAAK,EAAE;IAAE,YAAY,EAAE,kBAAkB,CAAC;IAAC,WAAW,EAAE,iBAAiB,CAAA;CAAE,GAC1E,OAAO,CAAC,MAAM,EAAE,CAAC,CA4BnB"}