@baruk/core 0.3.0 → 0.4.2

package/dist/communication/stores/routing.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Persistência do vínculo de canal e do índice de roteamento
+ * (migrações 0041 e 0042).
+ *
+ * Duas leituras, com fronteiras deliberadamente diferentes:
+ *
+ * - `createPostgresChannelBindingStore` responde "qual a conta DESTE tenant
+ *   neste canal", dentro do contexto do tenant, sob RLS.
+ * - `createPostgresChannelRouteStore` responde "de quem é esta conta do
+ *   provider", FORA de contexto de tenant, porque no momento em que o webhook
+ *   chega ainda não se sabe qual é o tenant.
+ *
+ * A segunda é a única leitura do motor que roda sem `app.current_tenant` — e
+ * ela não lê a tabela. Passa por `channel_route_resolve`, uma função de sistema
+ * que exige a chave exata e devolve no máximo uma linha. A tabela em si voltou
+ * a ser fechada por tenant na 0042: sem GUC, `SELECT * FROM channel_route`
+ * devolve zero linhas.
+ */
+import type { Tx } from '../../db/client.js';
+import type { ChannelAccount, ChannelAccountStore } from '../identity.js';
+import type { ChannelRoute, ChannelRouteStore, RoutedProvider } from '../routing.js';
+/**
+ * Índice de roteamento — primeiro tempo da resolução.
+ *
+ * Devolve o MÍNIMO: quem é o dono. Produto e marca ficam de fora porque vivem
+ * em `channel_binding`, que é fechada por RLS e portanto ilegível neste momento
+ * — ainda não há tenant na sessão. Denormalizá-los aqui resolveria a consulta e
+ * colocaria "que produto este escritório assina" atrás da mesma função que
+ * responde sem contexto de tenant, o que é informação comercial em lugar
+ * errado.
+ *
+ * O segundo tempo é `completeRoute`, já dentro de `withContext`.
+ */
+export declare function createPostgresChannelRouteStore(tx: Tx): ChannelRouteStore;
+/**
+ * Completa a rota com produto e marca, JÁ dentro do contexto do tenant.
+ *
+ * Separado de propósito: a primeira consulta responde "de quem é", a segunda
+ * responde "o que é" — e a segunda roda sob a RLS de `channel_binding`, que é
+ * fechada.
+ *
+ * Três gates, e o terceiro estava faltando na primeira entrega. A revogação era
+ * conferida (`revoked_at IS NULL`) e o STATUS não — de modo que um vínculo
+ * `paused`, `error`, `pending_validation` ou `not_configured`, que ninguém
+ * revogou, continuava roteando. É a assimetria clássica: o caminho de saída
+ * consultava o status (`identity.ts` só envia por conta `active`) e o de
+ * entrada não, e uma conta pausada por suspeita de abuso seguia recebendo.
+ */
+export declare function completeRoute(tx: Tx, route: ChannelRoute): Promise<ChannelRoute | null>;
+/**
+ * Contas de canal a partir de `channel_binding`.
+ *
+ * Substitui, para os canais de telefone, a leitura de `tenant.settings.channels`
+ * — que continua existindo e continua servindo o e-mail e a configuração
+ * herdada. Não há fallback de um para o outro dentro desta função: quem compõe
+ * o runtime decide a ordem, e a decisão fica visível na composição em vez de
+ * escondida num `??`.
+ */
+export declare function createPostgresChannelBindingStore(tx: Tx): ChannelAccountStore;
+export interface RegisterBindingInput {
+    id: string;
+    tenantId: string;
+    product: string;
+    brand: string;
+    channel: 'whatsapp' | 'sms';
+    provider: RoutedProvider;
+    senderId: string;
+    displayName?: string | null;
+    /** NOME da credencial no Vault. Nunca o valor. */
+    credentialRef: string;
+    status?: ChannelAccount['status'];
+    /** `phone_number_id`. Registrá-lo é o que torna o vínculo roteável. */
+    providerAccountRef?: string | null;
+    /** WABA. */
+    providerParentRef?: string | null;
+}
+/**
+ * Registra ou atualiza um vínculo e sua rota. **Roda dentro do contexto do
+ * tenant** — as duas políticas de escrita exigem isso.
+ *
+ * O `INSERT` da rota falha por violação de chave primária quando outro tenant já
+ * reivindicou a mesma conta do provider. Isso é o comportamento desejado e é a
+ * razão de a chave ser global: o erro vem do banco, não de um `SELECT` prévio
+ * que a RLS teria feito voltar vazio.
+ *
+ * ── O guard de credencial ───────────────────────────────────────────────────
+ *
+ * `isAcceptableForNewBinding` existia e **não era chamado por ninguém**. Uma
+ * regra que só um teste unitário exercita não é enforcement: é documentação com
+ * sintaxe de TypeScript. O caminho real de criação aceitava, sem reclamar,
+ * `credentialRef: 'WHATSAPP_ACCESS_TOKEN'` — o token global que a fase inteira
+ * existe para eliminar.
+ *
+ * A checagem vem ANTES de qualquer escrita, e cobre criação e atualização pelo
+ * mesmo ponto porque este `INSERT ... ON CONFLICT DO UPDATE` É os dois. O banco
+ * repete a regra em `channel_binding_phone_credential_ref_chk` (migração 0042),
+ * para o caso de alguém alcançar a tabela por outro caminho: um `UPDATE` cru,
+ * uma importação, um script de migração de dados.
+ */
+export declare function registerChannelBinding(tx: Tx, input: RegisterBindingInput): Promise<void>;
+/**
+ * A conta do provider já pertence a outro vínculo.
+ *
+ * Erro de negócio, não de infraestrutura: dois escritórios não podem reivindicar
+ * o mesmo número. A mensagem não carrega o tenant dono — quem está tentando
+ * registrar não tem por que descobrir de quem é.
+ */
+export declare class ChannelRouteConflictError extends Error {
+    readonly code = "channel_route_conflict";
+    constructor(provider: string, providerAccountRef: string);
+}
+/**
+ * A referência de credencial não é aceitável para este canal.
+ *
+ * O canal de telefone exige `vault://` — uma referência ao cofre do TENANT.
+ * Aceitar um nome de variável de ambiente significaria, na prática, que dois
+ * escritórios compartilham o mesmo token de WhatsApp: o bloqueio que um tomar
+ * cai sobre o outro, e a conversa de um aparece na conta do outro.
+ *
+ * A mensagem carrega o canal e **não** carrega a referência recusada. Quem
+ * cadastrou já sabe o que digitou; a mensagem viaja para log e para tela de
+ * erro, e uma referência colada ali é meio caminho para o valor aparecer junto
+ * na próxima vez que alguém "melhorar o diagnóstico".
+ */
+export declare class CredentialRefNotAcceptableError extends Error {
+    readonly code = "credential_ref_not_acceptable";
+    readonly channel: string;
+    constructor(channel: string, _ref: string);
+}
+export interface ClaimChannelAccountInput extends Omit<RegisterBindingInput, 'id'> {
+    /** Sugerido quando não houver vínculo vivo para o contexto. */
+    id: string;
+}
+export interface ClaimedChannelAccount {
+    bindingId: string;
+    /** `true` quando reaproveitou o vínculo que já existia para o contexto. */
+    reused: boolean;
+    /** Rotas de contas ANTIGAS que deixaram de apontar para este vínculo. */
+    releasedRoutes: number;
+}
+/**
+ * Registra a conta de canal do contexto — criando o vínculo ou **substituindo o
+ * que já existe**.
+ *
+ * ## Por que `registerChannelBinding` sozinho não serve ao onboarding
+ *
+ * `channel_binding_context_uq` (0041) garante **um** vínculo vivo por
+ * (tenant, produto, marca, canal) — é o que faz `resolveIdentity` nunca ter de
+ * escolher entre dois. `registerChannelBinding` resolve conflito por `id`, e o
+ * `id` de um onboarding novo é novo: reconectar o WhatsApp de um escritório que
+ * já tinha um caía direto na violação do índice de contexto, como erro 500.
+ *
+ * Isso não é caso de laboratório. É o caminho de: trocar de número, refazer o
+ * signup depois de revogar o acesso, migrar a WABA de portfólio. O primeiro
+ * onboarding funcionava e o segundo derrubava a rota.
+ *
+ * ## As rotas órfãs, que são o risco silencioso
+ *
+ * Trocar o número deixaria a rota do número ANTIGO apontando para este mesmo
+ * vínculo — e o webhook do número que o escritório não usa mais continuaria
+ * sendo aceito e aplicado na trilha dele. Pior: aquele número fica preso a este
+ * tenant pela chave global de `channel_route`, e o escritório que o receber
+ * depois não consegue reivindicá-lo.
+ *
+ * Por isso a limpeza é parte da mesma operação, e não um passo que quem chama
+ * precisa lembrar de fazer.
+ */
+export declare function claimChannelAccount(tx: Tx, input: ClaimChannelAccountInput): Promise<ClaimedChannelAccount>;
+//# sourceMappingURL=routing.d.ts.map

package/dist/communication/stores/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../../src/communication/stores/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,oBAAoB,CAAC;AAG7C,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AASrF;;;;;;;;;;;GAWG;AACH,wBAAgB,+BAA+B,CAAC,EAAE,EAAE,EAAE,GAAG,iBAAiB,CAqCzE;AAaD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAa7F;AAuBD;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAAC,EAAE,EAAE,EAAE,GAAG,mBAAmB,CAyC7E;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,UAAU,GAAG,KAAK,CAAC;IAC5B,QAAQ,EAAE,cAAc,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,kDAAkD;IAClD,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IAClC,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,YAAY;IACZ,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,sBAAsB,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4C/F;AAED;;;;;;GAMG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,4BAA4B;gBAC7B,QAAQ,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM;CAIzD;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,QAAQ,CAAC,IAAI,mCAAmC;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBACb,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAK1C;AAED,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CAAC,oBAAoB,EAAE,IAAI,CAAC;IAChF,+DAA+D;IAC/D,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,MAAM,EAAE,OAAO,CAAC;IAChB,yEAAyE;IACzE,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,EAAE,EACN,KAAK,EAAE,wBAAwB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAgChC"}

package/dist/communication/stores/routing.js

@@ -0,0 +1,324 @@
+/**
+ * Persistência do vínculo de canal e do índice de roteamento
+ * (migrações 0041 e 0042).
+ *
+ * Duas leituras, com fronteiras deliberadamente diferentes:
+ *
+ * - `createPostgresChannelBindingStore` responde "qual a conta DESTE tenant
+ *   neste canal", dentro do contexto do tenant, sob RLS.
+ * - `createPostgresChannelRouteStore` responde "de quem é esta conta do
+ *   provider", FORA de contexto de tenant, porque no momento em que o webhook
+ *   chega ainda não se sabe qual é o tenant.
+ *
+ * A segunda é a única leitura do motor que roda sem `app.current_tenant` — e
+ * ela não lê a tabela. Passa por `channel_route_resolve`, uma função de sistema
+ * que exige a chave exata e devolve no máximo uma linha. A tabela em si voltou
+ * a ser fechada por tenant na 0042: sem GUC, `SELECT * FROM channel_route`
+ * devolve zero linhas.
+ */
+import { isAcceptableForNewBinding } from '../credentials.js';
+/**
+ * Índice de roteamento — primeiro tempo da resolução.
+ *
+ * Devolve o MÍNIMO: quem é o dono. Produto e marca ficam de fora porque vivem
+ * em `channel_binding`, que é fechada por RLS e portanto ilegível neste momento
+ * — ainda não há tenant na sessão. Denormalizá-los aqui resolveria a consulta e
+ * colocaria "que produto este escritório assina" atrás da mesma função que
+ * responde sem contexto de tenant, o que é informação comercial em lugar
+ * errado.
+ *
+ * O segundo tempo é `completeRoute`, já dentro de `withContext`.
+ */
+export function createPostgresChannelRouteStore(tx) {
+    return {
+        async findByProviderAccount(provider, providerAccountRef) {
+            // `channel_route_resolve` (migração 0042), e não um `SELECT` na tabela.
+            //
+            // A 0041 abria a política de leitura quando não havia tenant na sessão,
+            // e essa abertura era o que fazia este `SELECT` funcionar. O preço era
+            // que QUALQUER consulta sem contexto — um script, um job, um caminho que
+            // esqueceu de abrir `withContext` — enxergava o mapa inteiro de
+            // (conta do provider → tenant) e podia listá-lo.
+            //
+            // A função de sistema entrega a mesma resposta sem o mesmo preço: exige a
+            // chave exata, devolve no máximo uma linha e não tem forma de ser
+            // chamada "sem argumento". A política da tabela voltou a ser fechada, e
+            // ninguém lê `channel_route` fora do próprio tenant.
+            const rows = await tx `
+        SELECT provider, provider_account_ref, provider_parent_ref, tenant_id, binding_id
+          FROM channel_route_resolve(${provider}, ${providerAccountRef})
+      `;
+            const row = rows[0];
+            if (!row)
+                return null;
+            return {
+                provider,
+                providerAccountRef: row.provider_account_ref,
+                ...(row.provider_parent_ref ? { providerParentRef: row.provider_parent_ref } : {}),
+                tenantId: row.tenant_id,
+                // Preenchidos por `completeRoute`, dentro do contexto do tenant.
+                product: '',
+                brand: '',
+                bindingId: row.binding_id,
+            };
+        },
+    };
+}
+/**
+ * O único estado de vínculo que autoriza tráfego.
+ *
+ * Lista de PERMISSÃO, e não de bloqueio. Uma lista de bloqueio
+ * (`status !== 'paused'`) autoriza por omissão: o dia em que a coluna ganhar
+ * `suspended`, `blocked` ou `migrating`, o estado novo nasce liberado e ninguém
+ * repara. Aqui um estado que ninguém escreveu aqui não passa, inclusive um
+ * valor que a aplicação não reconhece.
+ */
+const ROUTABLE_STATUSES = new Set(['active']);
+/**
+ * Completa a rota com produto e marca, JÁ dentro do contexto do tenant.
+ *
+ * Separado de propósito: a primeira consulta responde "de quem é", a segunda
+ * responde "o que é" — e a segunda roda sob a RLS de `channel_binding`, que é
+ * fechada.
+ *
+ * Três gates, e o terceiro estava faltando na primeira entrega. A revogação era
+ * conferida (`revoked_at IS NULL`) e o STATUS não — de modo que um vínculo
+ * `paused`, `error`, `pending_validation` ou `not_configured`, que ninguém
+ * revogou, continuava roteando. É a assimetria clássica: o caminho de saída
+ * consultava o status (`identity.ts` só envia por conta `active`) e o de
+ * entrada não, e uma conta pausada por suspeita de abuso seguia recebendo.
+ */
+export async function completeRoute(tx, route) {
+    const rows = await tx `
+    SELECT product, brand, status
+      FROM channel_binding
+     WHERE id = ${route.bindingId}
+       AND tenant_id = ${route.tenantId}
+       AND revoked_at IS NULL
+     LIMIT 1
+  `;
+    const row = rows[0];
+    if (!row)
+        return null;
+    if (!ROUTABLE_STATUSES.has(row.status))
+        return null;
+    return { ...route, product: row.product, brand: row.brand };
+}
+const STATUSES = new Set([
+    'not_configured',
+    'pending_validation',
+    'active',
+    'paused',
+    'error',
+]);
+/**
+ * Contas de canal a partir de `channel_binding`.
+ *
+ * Substitui, para os canais de telefone, a leitura de `tenant.settings.channels`
+ * — que continua existindo e continua servindo o e-mail e a configuração
+ * herdada. Não há fallback de um para o outro dentro desta função: quem compõe
+ * o runtime decide a ordem, e a decisão fica visível na composição em vez de
+ * escondida num `??`.
+ */
+export function createPostgresChannelBindingStore(tx) {
+    return {
+        async find(ctx, channel) {
+            const rows = await tx `
+        SELECT b.id, b.product, b.brand, b.channel, b.sender_id, b.display_name,
+               b.credential_ref, b.status,
+               r.provider_account_ref, r.provider_parent_ref
+          FROM channel_binding b
+          LEFT JOIN channel_route r
+            ON r.tenant_id = b.tenant_id AND r.binding_id = b.id
+         WHERE b.tenant_id = ${ctx.tenantId}
+           AND b.product   = ${ctx.product}
+           AND b.brand     = ${ctx.brand}
+           AND b.channel   = ${channel}
+           AND b.revoked_at IS NULL
+         LIMIT 1
+      `;
+            const row = rows[0];
+            if (!row)
+                return null;
+            const meta = {};
+            if (row.provider_account_ref)
+                meta.phoneNumberId = row.provider_account_ref;
+            if (row.provider_parent_ref)
+                meta.wabaId = row.provider_parent_ref;
+            return {
+                channel,
+                tenantId: ctx.tenantId,
+                product: row.product,
+                brand: row.brand,
+                senderId: row.sender_id,
+                ...(row.display_name ? { displayName: row.display_name } : {}),
+                credentialRef: row.credential_ref,
+                // Estado desconhecido nunca vira `active`: configuração que ninguém
+                // reconhece não autoriza envio.
+                status: STATUSES.has(row.status)
+                    ? row.status
+                    : 'not_configured',
+                ...(Object.keys(meta).length > 0 ? { meta } : {}),
+            };
+        },
+    };
+}
+/**
+ * Registra ou atualiza um vínculo e sua rota. **Roda dentro do contexto do
+ * tenant** — as duas políticas de escrita exigem isso.
+ *
+ * O `INSERT` da rota falha por violação de chave primária quando outro tenant já
+ * reivindicou a mesma conta do provider. Isso é o comportamento desejado e é a
+ * razão de a chave ser global: o erro vem do banco, não de um `SELECT` prévio
+ * que a RLS teria feito voltar vazio.
+ *
+ * ── O guard de credencial ───────────────────────────────────────────────────
+ *
+ * `isAcceptableForNewBinding` existia e **não era chamado por ninguém**. Uma
+ * regra que só um teste unitário exercita não é enforcement: é documentação com
+ * sintaxe de TypeScript. O caminho real de criação aceitava, sem reclamar,
+ * `credentialRef: 'WHATSAPP_ACCESS_TOKEN'` — o token global que a fase inteira
+ * existe para eliminar.
+ *
+ * A checagem vem ANTES de qualquer escrita, e cobre criação e atualização pelo
+ * mesmo ponto porque este `INSERT ... ON CONFLICT DO UPDATE` É os dois. O banco
+ * repete a regra em `channel_binding_phone_credential_ref_chk` (migração 0042),
+ * para o caso de alguém alcançar a tabela por outro caminho: um `UPDATE` cru,
+ * uma importação, um script de migração de dados.
+ */
+export async function registerChannelBinding(tx, input) {
+    if (!isAcceptableForNewBinding(input.channel, input.credentialRef)) {
+        throw new CredentialRefNotAcceptableError(input.channel, input.credentialRef);
+    }
+    await tx `
+    INSERT INTO channel_binding
+      (id, tenant_id, product, brand, channel, provider, sender_id, display_name,
+       credential_ref, status)
+    VALUES
+      (${input.id}, ${input.tenantId}, ${input.product}, ${input.brand}, ${input.channel},
+       ${input.provider}, ${input.senderId}, ${input.displayName ?? null},
+       ${input.credentialRef}, ${input.status ?? 'not_configured'})
+    ON CONFLICT (id) DO UPDATE SET
+      sender_id      = EXCLUDED.sender_id,
+      display_name   = EXCLUDED.display_name,
+      credential_ref = EXCLUDED.credential_ref,
+      status         = EXCLUDED.status,
+      updated_at     = now()
+  `;
+    if (!input.providerAccountRef)
+        return;
+    const claimed = await tx `
+    INSERT INTO channel_route
+      (provider, provider_account_ref, provider_parent_ref, tenant_id, binding_id)
+    VALUES
+      (${input.provider}, ${input.providerAccountRef}, ${input.providerParentRef ?? null},
+       ${input.tenantId}, ${input.id})
+    ON CONFLICT (provider, provider_account_ref) DO UPDATE SET
+      provider_parent_ref = EXCLUDED.provider_parent_ref,
+      updated_at          = now()
+      WHERE channel_route.tenant_id  = EXCLUDED.tenant_id
+        AND channel_route.binding_id = EXCLUDED.binding_id
+    RETURNING provider_account_ref
+  `;
+    // Zero linhas com `ON CONFLICT DO UPDATE` significa que o conflito existe e o
+    // `WHERE` recusou — ou seja, a conta já pertence a OUTRO vínculo. Deixar
+    // passar em silêncio é o pior desfecho possível: o registro pareceria ter
+    // funcionado e os webhooks continuariam indo para o dono anterior.
+    if (claimed.count === 0) {
+        throw new ChannelRouteConflictError(input.provider, input.providerAccountRef);
+    }
+}
+/**
+ * A conta do provider já pertence a outro vínculo.
+ *
+ * Erro de negócio, não de infraestrutura: dois escritórios não podem reivindicar
+ * o mesmo número. A mensagem não carrega o tenant dono — quem está tentando
+ * registrar não tem por que descobrir de quem é.
+ */
+export class ChannelRouteConflictError extends Error {
+    code = 'channel_route_conflict';
+    constructor(provider, providerAccountRef) {
+        super(`conta ${provider}/${providerAccountRef} já vinculada a outro registro`);
+        this.name = 'ChannelRouteConflictError';
+    }
+}
+/**
+ * A referência de credencial não é aceitável para este canal.
+ *
+ * O canal de telefone exige `vault://` — uma referência ao cofre do TENANT.
+ * Aceitar um nome de variável de ambiente significaria, na prática, que dois
+ * escritórios compartilham o mesmo token de WhatsApp: o bloqueio que um tomar
+ * cai sobre o outro, e a conversa de um aparece na conta do outro.
+ *
+ * A mensagem carrega o canal e **não** carrega a referência recusada. Quem
+ * cadastrou já sabe o que digitou; a mensagem viaja para log e para tela de
+ * erro, e uma referência colada ali é meio caminho para o valor aparecer junto
+ * na próxima vez que alguém "melhorar o diagnóstico".
+ */
+export class CredentialRefNotAcceptableError extends Error {
+    code = 'credential_ref_not_acceptable';
+    channel;
+    constructor(channel, _ref) {
+        super(`canal ${channel} exige referência de cofre (vault://) — referência recusada`);
+        this.name = 'CredentialRefNotAcceptableError';
+        this.channel = channel;
+    }
+}
+/**
+ * Registra a conta de canal do contexto — criando o vínculo ou **substituindo o
+ * que já existe**.
+ *
+ * ## Por que `registerChannelBinding` sozinho não serve ao onboarding
+ *
+ * `channel_binding_context_uq` (0041) garante **um** vínculo vivo por
+ * (tenant, produto, marca, canal) — é o que faz `resolveIdentity` nunca ter de
+ * escolher entre dois. `registerChannelBinding` resolve conflito por `id`, e o
+ * `id` de um onboarding novo é novo: reconectar o WhatsApp de um escritório que
+ * já tinha um caía direto na violação do índice de contexto, como erro 500.
+ *
+ * Isso não é caso de laboratório. É o caminho de: trocar de número, refazer o
+ * signup depois de revogar o acesso, migrar a WABA de portfólio. O primeiro
+ * onboarding funcionava e o segundo derrubava a rota.
+ *
+ * ## As rotas órfãs, que são o risco silencioso
+ *
+ * Trocar o número deixaria a rota do número ANTIGO apontando para este mesmo
+ * vínculo — e o webhook do número que o escritório não usa mais continuaria
+ * sendo aceito e aplicado na trilha dele. Pior: aquele número fica preso a este
+ * tenant pela chave global de `channel_route`, e o escritório que o receber
+ * depois não consegue reivindicá-lo.
+ *
+ * Por isso a limpeza é parte da mesma operação, e não um passo que quem chama
+ * precisa lembrar de fazer.
+ */
+export async function claimChannelAccount(tx, input) {
+    const existing = await tx `
+    SELECT id FROM channel_binding
+     WHERE tenant_id = ${input.tenantId}
+       AND product   = ${input.product}
+       AND brand     = ${input.brand}
+       AND channel   = ${input.channel}
+       AND revoked_at IS NULL
+     LIMIT 1
+  `;
+    const bindingId = existing[0]?.id ?? input.id;
+    await registerChannelBinding(tx, { ...input, id: bindingId });
+    // Só depois de a rota nova estar reivindicada. Apagar antes deixaria o
+    // vínculo sem rota nenhuma se o `INSERT` seguinte falhasse por conflito — e o
+    // canal do escritório pararia de receber callbacks por causa da tentativa
+    // frustrada de outro.
+    const released = input.providerAccountRef
+        ? await tx `
+        DELETE FROM channel_route
+         WHERE tenant_id = ${input.tenantId}
+           AND binding_id = ${bindingId}
+           AND provider_account_ref <> ${input.providerAccountRef}
+      `
+        : { count: 0 };
+    return {
+        bindingId,
+        reused: Boolean(existing[0]),
+        releasedRoutes: released.count,
+    };
+}
+//# sourceMappingURL=routing.js.map

package/dist/communication/stores/routing.js.map

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

package/dist/communication/stores/secrets.d.ts

@@ -0,0 +1,89 @@
+/**
+ * `TenantSecretStore` sobre o Vault Engine — agora atrás de autorização real.
+ *
+ * `credentials.ts` já declarava a interface e já dizia por que o valor teria
+ * de vir do cofre (migração 0012), mas nenhum arquivo do repositório a
+ * implementava: `createChannelCredentialResolver` só era chamado em teste, e
+ * os três call sites de produção (`collection-cron.ts`, `routes/collections.ts`)
+ * seguiam presos a `environmentCredentialResolver()`. Uma referência
+ * `vault://...` resolvia para `undefined` em produção — não por bug, por
+ * ausência: o fio entre o cofre e o motor nunca foi ligado.
+ *
+ * Este módulo é esse fio. Não é um segundo cofre — reaproveita
+ * `vault/repository.ts` inteiro (RLS FORCE, AAD por tenant, envelope
+ * AES-256-GCM) e acrescenta só o que o motor precisava e o Vault não tinha:
+ * ler por NOME em vez de `id` (`revealSecretByName`).
+ *
+ * **O que mudou no lote C1A.1.** A primeira versão aceitava um
+ * `SecretAccessGrant` montado pelo CHAMADOR: `principal` e `reason` eram
+ * strings, e qualquer módulo interno podia declará-las e pedir decifração.
+ * Isso registrava quem disse ser — não provava quem era. Agora o store exige
+ * uma `WorkloadIdentity` autenticada (`rbac/workload.ts`), e cada `reveal()`
+ * consulta o banco, DENTRO da mesma transação, para saber se aquele principal
+ * tem `vault.credential.decrypt` NAQUELE tenant, para AQUELE propósito e sobre
+ * AQUELE nome de credencial. O grant deixou de ser declaração e virou linha em
+ * tabela que o papel da aplicação não consegue escrever.
+ *
+ * O `SecretAccessGrant` permanece — como REGISTRO DE AUDITORIA derivado da
+ * decisão, não como entrada. É o que vai para o `audit_log`.
+ */
+import type { Db } from '../../db/client.js';
+import { type WorkloadIdentity, type WorkloadPurpose } from '../../rbac/workload.js';
+import type { Keyring } from '../../vault/crypto.js';
+import type { TenantSecretStore } from '../credentials.js';
+/**
+ * Por que este workload pode pedir decifração. Vocabulário fechado, o mesmo do
+ * CHECK de `service_principal_grant.purpose` — o propósito não é um rótulo de
+ * log, é uma das quatro dimensões que a autorização exige casar.
+ */
+export type SecretAccessReason = WorkloadPurpose;
+/** A permissão do catálogo RBAC exigida para decifrar. Uma só, específica. */
+export declare const VAULT_DECRYPT_PERMISSION = "vault.credential.decrypt";
+/**
+ * Registro de auditoria de um acesso a segredo.
+ *
+ * **Não é mais um parâmetro.** É produzido AQUI, a partir da identidade
+ * autenticada e da decisão do banco, e existe para a trilha. Um chamador não
+ * consegue mais fabricá-lo para se autorizar — no máximo consegue ler o que
+ * ficou registrado.
+ */
+export interface SecretAccessGrant {
+    reason: SecretAccessReason;
+    /** `principalKey` autenticado — nunca uma string escolhida pelo chamador. */
+    principal: string;
+    principalId: string;
+    /** Id da linha de `service_principal_grant` que autorizou. `null` quando negado. */
+    grantId: string | null;
+    issuedAt: Date;
+    expiresAt: Date;
+}
+export interface TenantSecretStoreOptions {
+    /** Propósito desta composição. Precisa casar com um grant no banco. */
+    purpose: SecretAccessReason;
+    /** Correlação com a execução (job/request). Vai para a trilha; nunca é segredo. */
+    correlationId?: string;
+}
+/**
+ * `TenantSecretStore` sobre o Vault Engine.
+ *
+ * `reveal(tenantId, name)` recebe `tenantId` POR CHAMADA — o store é
+ * construído uma vez, no processo, e serve qualquer tenant que o motor
+ * resolver depois. É o mesmo desenho de `createChannelCredentialResolver`:
+ * quem sabe o tenant é o CHAMADOR, nunca o store. Mas saber o tenant não
+ * autoriza: cada chamada é decidida contra os grants DAQUELE tenant.
+ *
+ * Deny-by-default em toda borda:
+ *  - identidade não emitida por `authenticateWorkload` → lança na CONSTRUÇÃO
+ *  - `tenantId`/`name` vazios          → nega sem tocar o banco
+ *  - sessão expirada                   → nega, audita `denied`
+ *  - principal revogado/desabilitado   → nega, audita `denied`
+ *  - sem grant casando tenant+permissão+propósito+recurso → nega, audita `denied`
+ *  - nome inexistente/revogado/de outro tenant → nega (RLS filtra a linha)
+ *  - vencida (`expires_at`)            → nega, NUNCA decifra
+ *  - erro de infraestrutura            → propaga (não é "ausência"; é falha)
+ *
+ * Toda chamada que chega ao banco grava uma linha em `audit_log` —
+ * sucesso, ausência ou negação. O reveal nunca é silencioso.
+ */
+export declare function createPostgresTenantSecretStore(db: Db, keyring: Keyring, identity: WorkloadIdentity, options: TenantSecretStoreOptions): TenantSecretStore;
+//# sourceMappingURL=secrets.d.ts.map

package/dist/communication/stores/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../../src/communication/stores/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,KAAK,EAAE,EAAE,EAAM,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAEjD,8EAA8E;AAC9E,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AAEnE;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,IAAI,CAAC;IACf,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,uEAAuE;IACvE,OAAO,EAAE,kBAAkB,CAAC;IAC5B,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,+BAA+B,CAC7C,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,wBAAwB,GAChC,iBAAiB,CA2EnB"}