@baruk/core 0.4.2 → 0.6.0

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

@@ -0,0 +1,119 @@
+import type { Tx } from '../../db/client.js';
+import type { Keyring } from '../../vault/crypto.js';
+import { type IdentityMatch } from './inspect.js';
+/**
+ * O caminho de entrada do certificado digital — o único.
+ *
+ * ## O que esta frente entrega, e por que ela existe
+ *
+ * Até aqui o produto sabia USAR um certificado (`material.ts`) e sabia dizer se
+ * ele estava pronto (`readiness.ts`). O que não existia era como ele ENTRA:
+ * `POST /v1/compliance/certificates` aceitava um `vaultCredentialId` já
+ * existente, e nada no produto criava esse ponteiro. Na prática, a única forma
+ * de cadastrar um A1 era alguém colar o base64 do `.pfx` — e a senha — na tela
+ * genérica do cofre, ou digitá-los num terminal.
+ *
+ * Uma senha de certificado digitada num terminal é uma senha no histórico do
+ * shell, no scrollback e, se o comando falhar, na mensagem de erro. O objetivo
+ * declarado desta fase é que ela nunca precise sair do navegador.
+ *
+ * ## Três recusas que acontecem ANTES de qualquer escrita
+ *
+ * **Senha que não abre.** Sem isso, o cadastro fica `active` e o defeito só
+ * aparece no dia em que o worker apresentar o material à Receita.
+ *
+ * **Certificado vencido.** Guardar material vencido é assumir o risco de
+ * custodiar uma chave privada sem nenhum uso possível em troca.
+ *
+ * **Certificado de outra empresa.** É o caso que a arquitetura precisa impedir
+ * em silêncio total: cliente A com o certificado da empresa B consulta a Receita
+ * em nome de quem não autorizou. Aqui ele exige assinatura — nome e motivo —, e
+ * a 0060 repete a exigência como CHECK, para o caminho que ainda não foi escrito.
+ *
+ * ## O que NUNCA sai daqui
+ *
+ * Nenhum retorno desta função carrega material nem senha. O que volta é
+ * metadata: sujeito, emissor, validade, impressão digital e estado. É essa
+ * estrutura que a tela mostra, e é por isso que ela não tem como mostrar mais.
+ */
+export type CertificateRejection = 'wrong_password' | 'malformed_material' | 'unsupported_material' | 'inspection_failed' | 'expired' | 'identity_mismatch' | 'client_not_found';
+/** Metadata segura para tela, trilha e resposta de API. Nunca há material aqui. */
+export interface FiscalCertificateSummary {
+    id: string;
+    clientId: string;
+    certType: 'A1' | 'A3';
+    status: string;
+    subjectCommonName: string | null;
+    issuerCommonName: string | null;
+    serialTail: string | null;
+    /** sha256 do certificado apresentado, truncado — identifica sem revelar. */
+    fingerprint: string;
+    certificateDocument: string | null;
+    identityMatch: IdentityMatch;
+    identityOverrideReason: string | null;
+    issuedAt: string | null;
+    expiresOn: string;
+    uploadedAt: string | null;
+    /** Já exercido contra o ambiente oficial? Preenchido por execução, nunca aqui. */
+    verifiedAt: string | null;
+    /** `true` quando esta chamada substituiu material que já existia. */
+    replaced: boolean;
+}
+export type CertificateOnboardingResult = {
+    status: 'stored';
+    certificate: FiscalCertificateSummary;
+} | {
+    status: 'rejected';
+    reason: CertificateRejection;
+    identityMatch?: IdentityMatch;
+};
+export interface CertificateOnboardingInput {
+    clientId: string;
+    certType?: 'A1' | 'A3';
+    /** O `.pfx`/`.p12` em bytes. Nunca um caminho de arquivo: não há arquivo. */
+    material: Buffer;
+    passphrase?: string;
+    actorId: string;
+    /**
+     * A assinatura humana que destrava um titular divergente. Sem ela, divergência
+     * é recusa — e é assim que "cliente A + certificado B" deixa de ser possível
+     * por distração.
+     */
+    identityOverrideReason?: string;
+}
+/**
+ * Nome determinístico da credencial no cofre.
+ *
+ * Determinístico porque a substituição precisa ENCONTRAR o que já existe: o
+ * índice único do cofre é `(tenant, cliente, lower(nome))`, e um nome novo a
+ * cada upload deixaria uma trilha de chaves privadas órfãs, todas ainda
+ * decifráveis, nenhuma referenciada.
+ */
+export declare function fiscalCertificateCredentialName(clientId: string, certType: 'A1' | 'A3'): string;
+export declare function onboardFiscalCertificate(tx: Tx, keyring: Keyring, tenantId: string, input: CertificateOnboardingInput): Promise<CertificateOnboardingResult>;
+/** Os certificados de um cliente, só metadata. É o que a tela lê. */
+export declare function listFiscalCertificates(tx: Tx, clientId: string): Promise<FiscalCertificateSummary[]>;
+/**
+ * Revoga o uso do certificado DENTRO deste produto.
+ *
+ * Não toca a ICP-Brasil, e é por isso que a função se chama assim. Revogar de
+ * verdade um certificado é um ato junto à Autoridade Certificadora que o emitiu;
+ * apagar a linha daqui apenas garante que este produto pare de apresentá-lo. A
+ * tela repete a distinção, porque um operador que acredite ter revogado o
+ * certificado do cliente não vai à AC — e o certificado segue válido no mundo.
+ *
+ * O material sai do cofre no mesmo movimento (`deleted_at`), de modo que a
+ * revogação não deixa chave privada decifrável para trás.
+ */
+export declare function revokeFiscalCertificate(tx: Tx, clientId: string, certificateId: string): Promise<{
+    revoked: boolean;
+}>;
+/**
+ * Impressão digital do material recebido, antes de qualquer decisão.
+ *
+ * Serve à trilha do upload recusado: registrar "tentaram subir algo" sem
+ * registrar o quê. É o mesmo cálculo de `material.ts`, e é seguro por
+ * construção — um hash não volta a ser um certificado.
+ */
+export declare function materialFingerprint(material: Buffer): string;
+//# sourceMappingURL=onboarding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.d.ts","sourceRoot":"","sources":["../../../src/fiscal/credentials/onboarding.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAErD,OAAO,EAAgC,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,MAAM,MAAM,oBAAoB,GAC5B,gBAAgB,GAChB,oBAAoB,GACpB,sBAAsB,GACtB,mBAAmB,GACnB,SAAS,GACT,mBAAmB,GACnB,kBAAkB,CAAC;AAEvB,mFAAmF;AACnF,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,aAAa,EAAE,aAAa,CAAC;IAC7B,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,kFAAkF;IAClF,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,2BAA2B,GACnC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,WAAW,EAAE,wBAAwB,CAAA;CAAE,GAC3D;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAC;IAAC,aAAa,CAAC,EAAE,aAAa,CAAA;CAAE,CAAC;AAExF,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAOD;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAE/F;AAED,wBAAsB,wBAAwB,CAC5C,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,2BAA2B,CAAC,CA0HtC;AAiHD,qEAAqE;AACrE,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,EAAE,EACN,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,wBAAwB,EAAE,CAAC,CAQrC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,EAAE,EACN,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAgB/B;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D"}

package/dist/fiscal/credentials/onboarding.js

@@ -0,0 +1,259 @@
+import { createHash } from 'node:crypto';
+import { uuidv7 } from '@baruk/shared';
+import { encryptSecret } from '../../vault/crypto.js';
+import { inspectPkcs12, matchIdentity } from './inspect.js';
+/** Impressão digital truncada. 16 hex identificam sem virar um segundo identificador. */
+function shortFingerprint(full) {
+    return full.slice(0, 16);
+}
+/**
+ * Nome determinístico da credencial no cofre.
+ *
+ * Determinístico porque a substituição precisa ENCONTRAR o que já existe: o
+ * índice único do cofre é `(tenant, cliente, lower(nome))`, e um nome novo a
+ * cada upload deixaria uma trilha de chaves privadas órfãs, todas ainda
+ * decifráveis, nenhuma referenciada.
+ */
+export function fiscalCertificateCredentialName(clientId, certType) {
+    return `fiscal:certificate:${certType}:${clientId}`;
+}
+export async function onboardFiscalCertificate(tx, keyring, tenantId, input) {
+    const certType = input.certType ?? 'A1';
+    const clients = await tx `
+    SELECT id, document_number FROM client
+     WHERE id = ${input.clientId} AND deleted_at IS NULL
+  `;
+    const client = clients[0];
+    if (!client)
+        return { status: 'rejected', reason: 'client_not_found' };
+    const inspection = await inspectPkcs12(input.material, input.passphrase);
+    if (inspection.status === 'failed') {
+        return { status: 'rejected', reason: inspection.reason };
+    }
+    const facts = inspection.facts;
+    if (facts.expired)
+        return { status: 'rejected', reason: 'expired' };
+    const identity = matchIdentity(facts.document, client.document_number);
+    if (identity === 'mismatch' && !input.identityOverrideReason) {
+        return { status: 'rejected', reason: 'identity_mismatch', identityMatch: identity };
+    }
+    // O envelope é o MESMO que `material.ts` sabe abrir. Um segundo formato aqui
+    // significaria que o certificado que entra não é o que o transporte usa.
+    const envelope = JSON.stringify({
+        format: 'pkcs12',
+        material: input.material.toString('base64'),
+        ...(input.passphrase ? { passphrase: input.passphrase } : {}),
+    });
+    const credentialName = fiscalCertificateCredentialName(input.clientId, certType);
+    const credentialId = await upsertWriteOnlyCredential(tx, keyring, tenantId, {
+        name: credentialName,
+        clientId: input.clientId,
+        secret: envelope,
+        expiresAt: facts.validTo,
+        actorId: input.actorId,
+        metadata: {
+            // Metadata do cofre é lida por telas e por trilha: só o que é público no
+            // certificado entra aqui.
+            fingerprint: shortFingerprint(facts.fingerprintSha256),
+            certType,
+            subject: facts.subjectCommonName,
+        },
+    });
+    const expiresOn = facts.validTo.slice(0, 10);
+    const issuedAt = facts.validFrom.slice(0, 10);
+    const holderName = facts.subjectCommonName ?? 'Titular não identificado no certificado';
+    const existing = await tx `
+    SELECT id FROM digital_certificate
+     WHERE client_id = ${input.clientId} AND cert_type = ${certType} AND deleted_at IS NULL
+     ORDER BY created_at DESC LIMIT 1
+  `;
+    const override = identity === 'mismatch' ? (input.identityOverrideReason ?? null) : null;
+    const overrideBy = override ? input.actorId : null;
+    let rows;
+    if (existing[0]) {
+        rows = await tx `
+      UPDATE digital_certificate SET
+        holder_name = ${holderName},
+        holder_document = ${facts.document ?? client.document_number},
+        issued_at = ${issuedAt},
+        expires_at = ${expiresOn},
+        vault_credential_id = ${credentialId},
+        status = 'active',
+        fingerprint_sha256 = ${facts.fingerprintSha256},
+        subject_common_name = ${facts.subjectCommonName},
+        issuer_common_name = ${facts.issuerCommonName},
+        serial_tail = ${facts.serialTail},
+        certificate_document = ${facts.document},
+        identity_match = ${identity},
+        identity_override_by = ${overrideBy},
+        identity_override_reason = ${override},
+        uploaded_by = ${input.actorId},
+        uploaded_at = now(),
+        -- O material acabou de ser aberto pela inspeção — o mesmo OpenSSL do
+        -- handshake real. Isso é a validação LOCAL, e ela é fato deste instante:
+        -- senha correta, chave casando com o certificado, titular e datas
+        -- conferidos. Ver 1006.
+        local_validated_at = now(),
+        -- Material novo é uma afirmação nova: o que o ambiente oficial aceitou
+        -- foi o certificado ANTERIOR, e herdar a verificação diria que o novo
+        -- já funcionou. Ver 1004.
+        verified_at = NULL,
+        verified_by = NULL,
+        remote_verification_provider = NULL,
+        remote_verification_last_attempt_at = NULL,
+        last_verification_error = NULL,
+        updated_at = now()
+      WHERE id = ${existing[0].id}
+      RETURNING ${tx.unsafe(CERTIFICATE_COLUMNS)}
+    `;
+    }
+    else {
+        rows = await tx `
+      INSERT INTO digital_certificate (
+        id, tenant_id, client_id, cert_type, holder_name, holder_document,
+        issued_at, expires_at, vault_credential_id, status,
+        fingerprint_sha256, subject_common_name, issuer_common_name, serial_tail,
+        certificate_document, identity_match, identity_override_by, identity_override_reason,
+        uploaded_by, uploaded_at, local_validated_at
+      ) VALUES (
+        ${uuidv7()}, current_setting('app.current_tenant')::uuid, ${input.clientId},
+        ${certType}, ${holderName}, ${facts.document ?? client.document_number},
+        ${issuedAt}, ${expiresOn}, ${credentialId}, 'active',
+        ${facts.fingerprintSha256}, ${facts.subjectCommonName}, ${facts.issuerCommonName},
+        ${facts.serialTail}, ${facts.document}, ${identity}, ${overrideBy}, ${override},
+        -- As duas datas coincidem aqui, e é correto: o material só chega a
+        -- esta linha porque a inspeção passou.
+        ${input.actorId}, now(), now()
+      )
+      RETURNING ${tx.unsafe(CERTIFICATE_COLUMNS)}
+    `;
+    }
+    return {
+        status: 'stored',
+        certificate: mapCertificate(rows[0], { replaced: Boolean(existing[0]) }),
+    };
+}
+/**
+ * Grava (ou rotaciona) o segredo no cofre com `exposure = 'write_only'`.
+ *
+ * Não reutiliza `createCredential`/`rotateSecret` de `vault/repository.ts` por
+ * um motivo específico: aqueles não conhecem `exposure`, e um certificado
+ * gravado por eles nasceria `revealable` — a 0060 recusaria o INSERT, o que
+ * está correto, mas a mensagem de erro seria uma violação de CHECK em vez de
+ * uma decisão explícita. Aqui a classe do segredo é dita na escrita.
+ */
+async function upsertWriteOnlyCredential(tx, keyring, tenantId, input) {
+    const enc = encryptSecret(keyring, tenantId, input.secret);
+    const existing = await tx `
+    SELECT id FROM vault_credential
+     WHERE client_id = ${input.clientId}
+       AND lower(name) = lower(${input.name})
+       AND deleted_at IS NULL
+     LIMIT 1
+  `;
+    if (existing[0]) {
+        await tx `
+      UPDATE vault_credential SET
+        ciphertext = ${enc.ciphertext}, iv = ${enc.iv}, auth_tag = ${enc.authTag},
+        key_version = ${enc.keyVersion}, rotated_at = now(), updated_at = now(),
+        updated_by = ${input.actorId}, version = version + 1,
+        expires_at = ${input.expiresAt},
+        metadata = ${tx.json(input.metadata)},
+        exposure = 'write_only'
+      WHERE id = ${existing[0].id}
+    `;
+        return existing[0].id;
+    }
+    const rows = await tx `
+    INSERT INTO vault_credential (
+      id, tenant_id, client_id, name, category, provider,
+      ciphertext, iv, auth_tag, key_version, metadata, expires_at, created_by, exposure
+    ) VALUES (
+      ${uuidv7()}, current_setting('app.current_tenant')::uuid, ${input.clientId},
+      ${input.name}, 'certificate', 'icp_brasil',
+      ${enc.ciphertext}, ${enc.iv}, ${enc.authTag}, ${enc.keyVersion},
+      ${tx.json(input.metadata)}, ${input.expiresAt}, ${input.actorId}, 'write_only'
+    )
+    RETURNING id
+  `;
+    return rows[0].id;
+}
+const CERTIFICATE_COLUMNS = `
+  id, client_id, cert_type, status, subject_common_name, issuer_common_name,
+  serial_tail, fingerprint_sha256, certificate_document, identity_match,
+  identity_override_reason, issued_at, expires_at, uploaded_at, verified_at,
+  local_validated_at, remote_verification_provider
+`;
+function mapCertificate(r, extra) {
+    return {
+        id: r.id,
+        clientId: r.client_id,
+        certType: r.cert_type === 'A3' ? 'A3' : 'A1',
+        status: r.status,
+        subjectCommonName: r.subject_common_name,
+        issuerCommonName: r.issuer_common_name,
+        serialTail: r.serial_tail,
+        fingerprint: shortFingerprint(r.fingerprint_sha256 ?? ''),
+        certificateDocument: r.certificate_document,
+        identityMatch: r.identity_match ?? 'indeterminate',
+        identityOverrideReason: r.identity_override_reason,
+        issuedAt: r.issued_at ? isoDate(r.issued_at) : null,
+        expiresOn: isoDate(r.expires_at),
+        uploadedAt: r.uploaded_at?.toISOString() ?? null,
+        verifiedAt: r.verified_at?.toISOString() ?? null,
+        replaced: extra.replaced,
+    };
+}
+function isoDate(d) {
+    return d.toISOString().slice(0, 10);
+}
+/** Os certificados de um cliente, só metadata. É o que a tela lê. */
+export async function listFiscalCertificates(tx, clientId) {
+    const rows = await tx `
+    SELECT ${tx.unsafe(CERTIFICATE_COLUMNS)}
+      FROM digital_certificate
+     WHERE client_id = ${clientId} AND deleted_at IS NULL
+     ORDER BY expires_at DESC
+  `;
+    return rows.map((r) => mapCertificate(r, { replaced: false }));
+}
+/**
+ * Revoga o uso do certificado DENTRO deste produto.
+ *
+ * Não toca a ICP-Brasil, e é por isso que a função se chama assim. Revogar de
+ * verdade um certificado é um ato junto à Autoridade Certificadora que o emitiu;
+ * apagar a linha daqui apenas garante que este produto pare de apresentá-lo. A
+ * tela repete a distinção, porque um operador que acredite ter revogado o
+ * certificado do cliente não vai à AC — e o certificado segue válido no mundo.
+ *
+ * O material sai do cofre no mesmo movimento (`deleted_at`), de modo que a
+ * revogação não deixa chave privada decifrável para trás.
+ */
+export async function revokeFiscalCertificate(tx, clientId, certificateId) {
+    const rows = await tx `
+    UPDATE digital_certificate SET status = 'revoked', deleted_at = now(), updated_at = now()
+     WHERE id = ${certificateId} AND client_id = ${clientId} AND deleted_at IS NULL
+    RETURNING vault_credential_id
+  `;
+    if (rows.length === 0)
+        return { revoked: false };
+    const pointer = rows[0]?.vault_credential_id;
+    if (pointer) {
+        await tx `
+      UPDATE vault_credential SET deleted_at = now()
+       WHERE id = ${pointer} AND deleted_at IS NULL
+    `;
+    }
+    return { revoked: true };
+}
+/**
+ * Impressão digital do material recebido, antes de qualquer decisão.
+ *
+ * Serve à trilha do upload recusado: registrar "tentaram subir algo" sem
+ * registrar o quê. É o mesmo cálculo de `material.ts`, e é seguro por
+ * construção — um hash não volta a ser um certificado.
+ */
+export function materialFingerprint(material) {
+    return shortFingerprint(createHash('sha256').update(material).digest('hex'));
+}
+//# sourceMappingURL=onboarding.js.map

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

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

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

@@ -0,0 +1,119 @@
+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.
+ *   `LOCAL_VALID`      o material abre, a chave casa, o titular confere e as
+ *                      datas estão na janela — e NENHUM ambiente oficial o
+ *                      aceitou ainda. É o estado em que todo certificado novo
+ *                      nasce, e o único que o primeiro contato admite.
+ *   `REQUIRES_REVIEW`  cadastrada e sem validação local registrada — ou de um
+ *                      tipo que um cron não consegue usar (A3 vive em token com
+ *                      PIN presencial).
+ */
+export type FiscalCredentialState = 'NOT_CONFIGURED' | 'READY' | 'LOCAL_VALID' | '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;
+    /**
+     * O material passou na verificação LOCAL: abriu com a senha, a chave casa com
+     * o certificado, o titular confere e as datas estão na janela.
+     *
+     * Independente de `usableByWorker` de propósito. Foi a fusão dos dois que
+     * produziu o impasse: exigir aceite remoto para executar, quando só executar
+     * produz o aceite.
+     */
+    localValid: boolean;
+    /**
+     * Esta credencial pode ser usada num PRIMEIRO CONTATO — a execução única,
+     * manual e autorizada que existe justamente para obter o aceite remoto.
+     *
+     * `true` exatamente quando o material é válido localmente e nenhum ambiente o
+     * aceitou ainda. Um cron jamais consulta este campo: ele existe para o
+     * executor de primeiro contato, e o banco recusa autorização de primeiro
+     * contato disparada por agendador.
+     */
+    eligibleForFirstContact: 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;
+    /** Quando o ambiente OFICIAL aceitou. Nunca sai do cadastro. */
+    verifiedAt: string | null;
+    /** Quando o material passou na verificação local. */
+    localValidatedAt: 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;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,qBAAqB,GAC7B,gBAAgB,GAChB,OAAO,GACP,aAAa,GACb,SAAS,GACT,SAAS,GACT,eAAe,GACf,iBAAiB,CAAC;AAEtB,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,qBAAqB,CAAC;IAC7B,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAClC,qFAAqF;IACrF,cAAc,EAAE,OAAO,CAAC;IACxB;;;;;;;OAOG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;;;;OAQG;IACH,uBAAuB,EAAE,OAAO,CAAC;IACjC;;;;OAIG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gEAAgE;IAChE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,qDAAqD;IACrD,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,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;AAsBD;;;;;;;;;;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,CAkJpC;AAWD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,qBAAqB,GAC3B,qBAAqB,GAAG,qBAAqB,GAAG,eAAe,GAAG,IAAI,CAWxE"}