@baruk/core 0.3.0 → 0.4.2

package/src/db/migrations/0040_communication_unknown_outcome.sql

@@ -0,0 +1,99 @@
+-- 0040 — Desfecho desconhecido, marca de chamada externa e trilha durável
+--
+-- A 0039 fechou a janela do envio duplo sob concorrência: a reserva é tomada
+-- ANTES do efeito externo, numa instrução atômica. O que ela NÃO fechou, e a
+-- segunda certificação independente apontou, é o que acontece quando o titular
+-- da reserva morre.
+--
+-- A reserva tem prazo (10 min) porque processo morre, e uma etapa calada para
+-- sempre é pior que uma duplicata rara. Mas a retomada por prazo vencido era
+-- CEGA: o motor não tinha como distinguir
+--
+--   (a) o titular morreu ANTES de chamar o provider — nada saiu, reenviar é certo;
+--   (b) o titular morreu DEPOIS de chamar o provider — pode ter saído, reenviar duplica.
+--
+-- Os dois chegavam com a mesma cara, e o motor reenviava nos dois. Essa migration
+-- dá ao banco o que falta para separá-los, e um estado para o caso em que a
+-- separação não basta.
+
+-- ── A marca da chamada externa ──────────────────────────────────────────────
+--
+-- Gravada IMEDIATAMENTE antes de falar com o provider, em transação própria e
+-- commitada. Precisa sobreviver à morte do processo que a escreveu — se vivesse
+-- na transação de quem chama, ficaria invisível justamente no caso que ela
+-- existe para cobrir, porque o processo que morre é o que nunca commita.
+--
+-- Erra para o lado seguro por construção: quem morre ENTRE a marca e a chamada
+-- é classificado como "pode ter enviado" sem ter enviado. Isso cala uma
+-- mensagem; a alternativa manda duas.
+ALTER TABLE communication_dispatch
+  ADD COLUMN IF NOT EXISTS provider_attempts integer NOT NULL DEFAULT 0;
+
+-- Instante da PRIMEIRA chamada externa desta chave. A janela de idempotência do
+-- provider conta a partir dela, não da tentativa atual: uma chave que o provider
+-- já esqueceu não protege mais nada, e reenviar depois disso é uma mensagem nova.
+ALTER TABLE communication_dispatch
+  ADD COLUMN IF NOT EXISTS provider_first_attempt_at timestamptz;
+
+-- Última chamada externa. Diagnóstico operacional — responde "há quanto tempo
+-- esta reserva está pendurada depois de já ter falado com o provider".
+ALTER TABLE communication_dispatch
+  ADD COLUMN IF NOT EXISTS provider_last_attempt_at timestamptz;
+
+-- ── O estado que faltava ────────────────────────────────────────────────────
+--
+-- `unknown_outcome`: alguém chamou o provider e ninguém sabe o que aconteceu.
+--
+-- Não é falha (pode ter dado certo) e não é sucesso (pode não ter saído). Os
+-- quatro estados anteriores obrigavam a mentir: `failed_retryable` devolveria a
+-- chave e a próxima rodada duplicaria; `sent` afirmaria uma entrega que ninguém
+-- viu.
+--
+-- A chave fica travada aqui de propósito. Destravar sozinha é escolher, no
+-- escuro, entre calar um aviso e cobrar duas vezes — e essa escolha é de quem
+-- consegue olhar o painel do provider, não do cron.
+ALTER TABLE communication_dispatch
+  DROP CONSTRAINT IF EXISTS communication_dispatch_status_check;
+
+ALTER TABLE communication_dispatch
+  ADD CONSTRAINT communication_dispatch_status_check
+  CHECK (status IN ('in_flight', 'sent', 'failed_retryable', 'failed_permanent', 'unknown_outcome'));
+
+-- Reservas paradas em desfecho desconhecido, para a fila de quem investiga.
+-- Parcial porque a expectativa é que sejam raras: um índice cheio sobre um
+-- estado excepcional é um índice que só custa.
+CREATE INDEX IF NOT EXISTS communication_dispatch_unknown_idx
+  ON communication_dispatch (tenant_id, updated_at DESC)
+  WHERE status = 'unknown_outcome';
+
+-- ── Trilha durável ──────────────────────────────────────────────────────────
+--
+-- `recipient_ref` passa a viver na reserva porque a trilha do CICLO DE VIDA do
+-- disparo (`dispatch_claimed`, `dispatch_sent`, `dispatch_failed`) passou a ser
+-- escrita na mesma transação da reserva, e não mais na transação de negócio de
+-- quem chamou.
+--
+-- O defeito que isso corrige é concreto. A reserva commita em transação própria
+-- e curta (precisa ficar visível a outros workers antes do fim do ciclo); a
+-- trilha vivia na transação longa da régua. Um rollback da régua DEPOIS de a
+-- mensagem sair produzia:
+--
+--     communication_dispatch.status = 'sent'      (sobreviveu — a mensagem saiu)
+--     communication_event.dispatch_sent           (sumiu — a narrativa foi desfeita)
+--
+-- Um disparo enviado sem nenhuma linha explicando que foi enviado. Escrevendo as
+-- duas coisas juntas, elas caem ou sobrevivem juntas. Não é outbox nem
+-- dual-write com compensação: é uma escrita só.
+--
+-- Referência LÓGICA (id do cliente), como no resto do motor. NUNCA telefone,
+-- NUNCA e-mail: a reserva é consultada por quem opera, e uma reserva que carrega
+-- contato transforma toda consulta operacional numa exportação de PII.
+ALTER TABLE communication_dispatch
+  ADD COLUMN IF NOT EXISTS recipient_ref text;
+
+COMMENT ON COLUMN communication_dispatch.provider_attempts IS
+  'Quantas vezes o provider foi chamado por esta chave. Marcado ANTES da chamada, em transação própria.';
+COMMENT ON COLUMN communication_dispatch.provider_first_attempt_at IS
+  'Primeira chamada externa. A janela de idempotência do provider conta a partir daqui.';
+COMMENT ON COLUMN communication_dispatch.recipient_ref IS
+  'Referência lógica do destinatário, para a trilha durável. Nunca telefone, nunca e-mail.';

package/src/db/migrations/0041_channel_binding_routing.sql

@@ -0,0 +1,146 @@
+-- 0041 — Vínculo de canal por tenant e roteamento reverso de webhook
+--
+-- O que muda de premissa. Até aqui, a configuração de canal do escritório vivia
+-- em `tenant.settings.channels` (jsonb) e o webhook trazia o tenant no PATH da
+-- URL. Isso é coerente com uma topologia em que cada tenant tem o próprio Meta
+-- App e o próprio webhook — e incoerente com a topologia que o motor vai
+-- operar, em que existe UM App do motor e N contas de clientes.
+--
+-- Sob um App único, a URL de callback e o verify token pertencem ao APP. A Meta
+-- entrega os eventos de todas as contas assinadas no mesmo endereço e não tem
+-- como saber o nosso `tenantId`. O tenant precisa sair do PAYLOAD, pelo
+-- `phone_number_id` — e isso exige um caminho de leitura que vai da conta do
+-- provider para o tenant, exatamente o inverso do que existe hoje.
+--
+-- Nada aqui apaga o caminho anterior: `tenant.settings.channels` continua
+-- válido e continua sendo lido. Esta migração acrescenta o registro canônico e
+-- o índice de roteamento.
+
+-- ── Vínculo de canal ────────────────────────────────────────────────────────
+--
+-- Uma linha por (tenant, produto, marca, canal). É o que `resolveIdentity` já
+-- pressupõe: o motor pergunta "qual a conta DESTE contexto neste canal" e
+-- espera no máximo uma resposta.
+--
+-- `credential_ref` é referência LÓGICA — o nome da credencial no Vault Engine
+-- (`0012_vault.sql`), nunca o valor. O ciclo de vida do segredo (vencimento,
+-- rotação, remoção) já é do Vault e não é duplicado aqui: duas fontes para
+-- "quando este token expira" divergem no dia em que uma é atualizada e a outra
+-- não.
+CREATE TABLE IF NOT EXISTS channel_binding (
+  id            uuid PRIMARY KEY,
+  tenant_id     uuid NOT NULL REFERENCES tenant(id),
+  -- Produto e marca fazem parte da identidade do vínculo porque fazem parte do
+  -- `CommunicationContext`. Um tenant que consome dois produtos do ecossistema
+  -- tem duas conversas distintas com o cliente dele.
+  product       text NOT NULL,
+  brand         text NOT NULL,
+  -- Só canais de TELEFONE. E-mail não tem conta de provider por tenant no
+  -- desenho atual (o fallback de plataforma existe e é declaradamente
+  -- email-only), e criar a linha para ele daria a impressão de que tem.
+  channel       text NOT NULL CHECK (channel IN ('whatsapp', 'sms')),
+  provider      text NOT NULL CHECK (provider IN ('meta_whatsapp')),
+  -- Identidade visível ao destinatário (E.164). Não é segredo — aparece na tela
+  -- e na trilha.
+  sender_id     text NOT NULL,
+  display_name  text,
+  -- Nome da credencial no Vault. Jamais o segredo.
+  credential_ref text NOT NULL,
+  -- `pending_validation` existe porque uma conta cadastrada e não verificada
+  -- parece pronta na tela e é recusada pelo provider. O operador merece ver a
+  -- diferença antes da primeira cobrança, não depois.
+  status        text NOT NULL DEFAULT 'not_configured'
+                  CHECK (status IN ('not_configured','pending_validation','active','paused','error')),
+  -- Revogação do VÍNCULO — distinta da revogação da credencial, que é do Vault.
+  -- Um tenant pode retirar o acesso do motor à conta dele sem que o segredo
+  -- deixe de existir.
+  revoked_at    timestamptz,
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  updated_at    timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT channel_binding_tenant_id_uq UNIQUE (tenant_id, id)
+);
+
+-- Um vínculo vivo por contexto e canal. Sem isto, duas linhas concorrentes
+-- fariam `resolveIdentity` escolher uma — e escolher errado significa enviar
+-- pela conta errada.
+CREATE UNIQUE INDEX IF NOT EXISTS channel_binding_context_uq
+  ON channel_binding (tenant_id, product, brand, channel)
+  WHERE revoked_at IS NULL;
+
+ALTER TABLE channel_binding ENABLE ROW LEVEL SECURITY;
+ALTER TABLE channel_binding FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY channel_binding_tenant_isolation ON channel_binding
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- ── Índice de roteamento ────────────────────────────────────────────────────
+--
+-- Por que uma tabela separada, e não colunas em `channel_binding`.
+--
+-- A pergunta do webhook é "de quem é este `phone_number_id`?", feita ANTES de
+-- existir contexto de tenant — não há como setar `app.current_tenant` para
+-- descobrir qual é o tenant. Sob a RLS FORCE de `channel_binding`, essa
+-- consulta não enxergaria linha nenhuma.
+--
+-- E há um segundo motivo, mais duro: a unicidade global. Se o par
+-- (provider, conta) morasse numa tabela com RLS por tenant, um índice único
+-- `(tenant_id, ...)` deixaria DOIS tenants reivindicarem o mesmo número, e
+-- nenhum guard de aplicação pegaria isso — sob RLS, o guard do tenant A não
+-- enxerga a linha do tenant B para comparar. A chave primária abaixo é global
+-- de propósito: é o banco, e não o código, que garante que um número pertence a
+-- no máximo um tenant.
+--
+-- O que esta tabela contém: identificadores emitidos pelo provider (que o
+-- próprio provider manda em texto claro em todo webhook) e o dono. Nenhuma
+-- credencial, nenhum dado de cliente, nenhuma PII.
+CREATE TABLE IF NOT EXISTS channel_route (
+  provider              text NOT NULL CHECK (provider IN ('meta_whatsapp')),
+  -- O identificador de ROTEAMENTO. Na Meta, `phone_number_id`.
+  provider_account_ref  text NOT NULL,
+  -- O agrupador (WABA). Conferência de coerência, nunca segunda chave.
+  provider_parent_ref   text,
+  tenant_id             uuid NOT NULL,
+  binding_id            uuid NOT NULL,
+  created_at            timestamptz NOT NULL DEFAULT now(),
+  updated_at            timestamptz NOT NULL DEFAULT now(),
+  -- GLOBAL, não por tenant. Ver o comentário acima.
+  PRIMARY KEY (provider, provider_account_ref),
+  -- A FK composta amarra a rota ao vínculo do MESMO tenant. Não há como
+  -- registrar uma rota apontando para o vínculo de outro escritório.
+  FOREIGN KEY (tenant_id, binding_id)
+    REFERENCES channel_binding (tenant_id, id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS channel_route_tenant_idx ON channel_route (tenant_id);
+
+ALTER TABLE channel_route ENABLE ROW LEVEL SECURITY;
+ALTER TABLE channel_route FORCE ROW LEVEL SECURITY;
+
+-- LEITURA: aberta apenas quando NÃO há tenant na sessão — que é o único momento
+-- em que o roteador precisa consultar, e o único em que ele pode. Dentro de um
+-- contexto de tenant, um escritório continua vendo só as próprias rotas.
+--
+-- O ramo aberto é uma decisão consciente e é o preço da topologia de App único.
+-- O que ele expõe a um código que rode sem GUC é o mapa
+-- (número do provider → tenant) — sem segredo, sem PII, sem conteúdo. O que ele
+-- NÃO abre é escrita: veja a política seguinte.
+CREATE POLICY channel_route_read ON channel_route FOR SELECT
+  USING (
+    NULLIF(current_setting('app.current_tenant', true), '') IS NULL
+    OR tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid
+  );
+
+-- ESCRITA: sempre fechada. Registrar ou remover rota exige estar dentro do
+-- tenant dono. Sem isto, o mesmo ramo aberto da leitura permitiria a qualquer
+-- código sem contexto reivindicar o número de um escritório.
+CREATE POLICY channel_route_write ON channel_route FOR ALL
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+COMMENT ON TABLE channel_binding IS
+  'Conta de canal de um tenant. credential_ref é o NOME no Vault, nunca o valor.';
+COMMENT ON TABLE channel_route IS
+  'Índice de roteamento de webhook. Chave primária GLOBAL: um phone_number_id pertence a no máximo um tenant.';
+COMMENT ON COLUMN channel_route.provider_parent_ref IS
+  'WABA. Conferência de coerência; nunca decide sozinho de quem é o evento.';

package/src/db/migrations/0042_channel_route_read_isolation.sql

@@ -0,0 +1,165 @@
+-- 0042 — Fecha a leitura de `channel_route` e move o roteamento para um caminho
+--        de sistema explícito.
+--
+-- POR QUE UMA MIGRATION NOVA, E NÃO UMA CORREÇÃO NA 0041.
+--
+-- O runner (`db/migrate.ts`) guarda o checksum de cada arquivo aplicado e
+-- recusa a subida quando ele muda: "Migration já aplicada foi modificada —
+-- migrations são imutáveis, crie uma nova". Editar a 0041 faria o caminho de
+-- UPGRADE (banco que já a aplicou) abortar antes de qualquer correção chegar,
+-- e só o caminho FRESH veria a versão nova. Um defeito de segurança que se
+-- corrige apenas em banco recriado não está corrigido.
+--
+-- O QUE A 0041 DEIXOU ABERTO.
+--
+-- A política de leitura dela era:
+--
+--     current_tenant IS NULL  OR  tenant_id = current_tenant
+--
+-- O primeiro ramo transformava a AUSÊNCIA de contexto em autorização. Isso
+-- inverte a regra da casa: sem contexto, não se lê tabela de tenant. E a
+-- ausência de contexto não é um estado raro — é o estado de qualquer código
+-- que esqueceu de abrir `withContext`, de qualquer script, de qualquer job.
+-- O ramo entregava o mapa (conta do provider → tenant) a todos eles, e a
+-- listagem inteira: `SELECT * FROM channel_route` sem GUC devolvia o portfólio
+-- de clientes do motor.
+--
+-- A necessidade que justificava o ramo continua real: o webhook do App único
+-- precisa descobrir o tenant ANTES de poder abrir contexto dele. O que muda é
+-- que essa necessidade passa a ser atendida por um caminho nomeado, com
+-- assinatura fixa e resposta de no máximo uma linha, em vez de por um buraco na
+-- política que qualquer consulta atravessa.
+
+-- ── 1 · Leitura fecha ───────────────────────────────────────────────────────
+--
+-- Sem GUC, `NULLIF(...)::uuid` é NULL, e `tenant_id = NULL` é NULL — que a RLS
+-- trata como falso. Fail-closed sem ramo especial.
+DROP POLICY IF EXISTS channel_route_read ON channel_route;
+
+CREATE POLICY channel_route_read ON channel_route FOR SELECT
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- ── 2 · O caminho de sistema, explícito ─────────────────────────────────────
+--
+-- `channel_route_resolve` é a ÚNICA forma de perguntar "de quem é esta conta"
+-- sem contexto de tenant, e ela responde só isso:
+--
+--   - exige a chave exata (provider + conta). Não existe consulta por prefixo,
+--     por tenant, por faixa, nem sem argumento: não há como enumerar o mapa.
+--   - devolve no máximo UMA linha, e só as colunas de roteamento.
+--   - `SECURITY DEFINER` com `search_path` fixo — sem isso, um schema no
+--     caminho de busca do chamador poderia sombrear `channel_route` e a função
+--     leria a tabela de outra pessoa com o privilégio do dono.
+--   - `STABLE`, nunca `VOLATILE`: não escreve.
+--
+-- O privilégio de execução é concedido nominalmente ao papel de aplicação. O
+-- `REVOKE ... FROM PUBLIC` é obrigatório porque o Postgres concede EXECUTE a
+-- PUBLIC por padrão em toda função criada — sem ele, "estritamente limitada"
+-- seria só o nome.
+CREATE OR REPLACE FUNCTION channel_route_resolve(
+  p_provider    text,
+  p_account_ref text
+)
+RETURNS TABLE (
+  provider             text,
+  provider_account_ref text,
+  provider_parent_ref  text,
+  tenant_id            uuid,
+  binding_id           uuid
+)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = pg_catalog, public
+AS $fn$
+  SELECT r.provider, r.provider_account_ref, r.provider_parent_ref,
+         r.tenant_id, r.binding_id
+    FROM public.channel_route r
+   WHERE r.provider            = p_provider
+     AND r.provider_account_ref = p_account_ref
+   LIMIT 1
+$fn$;
+
+REVOKE ALL ON FUNCTION channel_route_resolve(text, text) FROM PUBLIC;
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT FROM pg_roles WHERE rolname = 'baruk_app') THEN
+    EXECUTE 'GRANT EXECUTE ON FUNCTION channel_route_resolve(text, text) TO baruk_app';
+  END IF;
+END $$;
+
+-- ── 3 · Por que a função consegue ler o que o chamador não consegue ─────────
+--
+-- `channel_route` tem FORCE ROW LEVEL SECURITY, e FORCE aplica as políticas
+-- TAMBÉM ao dono da tabela. Sem uma política que o autorize, a função
+-- `SECURITY DEFINER` — que roda com a identidade do dono — leria zero linhas, e
+-- o roteamento morreria em silêncio.
+--
+-- A autorização é dada nominalmente ao papel que é dono do schema (o mesmo que
+-- roda migrations), e é de LEITURA APENAS. A escrita continua sujeita à
+-- política por tenant inclusive para ele: `channel_route_write` não foi
+-- afetada, e nenhuma política nova concede INSERT/UPDATE/DELETE.
+--
+-- O nome do papel varia por ambiente (`baruk_test` local, outro em produção),
+-- então ele é descoberto — não escrito à mão.
+DO $$
+DECLARE
+  owner_role text;
+BEGIN
+  SELECT tableowner INTO owner_role
+    FROM pg_tables
+   WHERE schemaname = 'public' AND tablename = 'channel_route';
+
+  IF owner_role IS NULL THEN
+    RAISE EXCEPTION 'channel_route sem dono identificável — abortando';
+  END IF;
+
+  EXECUTE format('DROP POLICY IF EXISTS channel_route_system_resolver ON channel_route');
+  EXECUTE format(
+    'CREATE POLICY channel_route_system_resolver ON channel_route FOR SELECT TO %I USING (true)',
+    owner_role
+  );
+END $$;
+
+COMMENT ON FUNCTION channel_route_resolve(text, text) IS
+  'Resolução de webhook fora de contexto de tenant. Chave exata, uma linha, sem enumeração.';
+
+-- ── 4 · A credencial de canal de telefone tem de ser do COFRE ───────────────
+--
+-- `isAcceptableForNewBinding` já dizia isto em TypeScript, e nenhum caminho de
+-- escrita a chamava. A 0042 corrige o caminho (ver `registerChannelBinding`) e
+-- repete a regra aqui, porque um guard de aplicação cobre a função que o
+-- invoca — não cobre um `UPDATE` cru, uma importação, um script de correção de
+-- dados nem a próxima função de escrita que alguém escrever.
+--
+-- Um `credential_ref` que não começa por `vault://` num canal de telefone
+-- significa um token de ambiente, e um token de ambiente é COMPARTILHADO: o
+-- bloqueio que a Meta aplicar a um escritório cai sobre todos os outros.
+--
+-- `NOT VALID` de propósito, e é exatamente a compatibilidade legada do §10.
+-- Ele NÃO afrouxa a regra para escritas: todo INSERT e todo UPDATE passam pela
+-- verificação, inclusive um UPDATE numa linha antiga. O que ele dispensa é a
+-- varredura das linhas que já existem — que hoje são zero (a tabela nasceu na
+-- 0041, que nunca foi mesclada), e que num ambiente onde não fossem
+-- continuariam legíveis e utilizáveis até serem tocadas.
+--
+-- Plano de remoção do `NOT VALID`: quando o inventário de `channel_binding`
+-- confirmar zero linhas com referência de ambiente, uma migration futura roda
+-- `VALIDATE CONSTRAINT` e a exceção deixa de existir.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT FROM pg_constraint WHERE conname = 'channel_binding_phone_credential_ref_chk'
+  ) THEN
+    ALTER TABLE channel_binding
+      ADD CONSTRAINT channel_binding_phone_credential_ref_chk
+      CHECK (
+        channel NOT IN ('whatsapp', 'sms')
+        OR credential_ref LIKE 'vault://%'
+      ) NOT VALID;
+  END IF;
+END $$;
+
+COMMENT ON CONSTRAINT channel_binding_phone_credential_ref_chk ON channel_binding IS
+  'Canal de telefone exige credencial do cofre. NOT VALID cobre linhas legadas; escritas são verificadas.';

package/src/db/migrations/0043_workload_identity.sql

@@ -0,0 +1,105 @@
+-- 0043 — Identidade e autorização de workload NÃO-HUMANO.
+--
+-- Por que uma tabela nova, e não `user`/`user_role`.
+--
+-- O RBAC existente resolve autorização de PESSOA: `user` → `membership` →
+-- `user_role` → `role_permission` → `permission`. Reaproveitá-lo para um cron
+-- exigiria criar uma linha em `"user"` — e `login()` (auth/service.ts) não
+-- filtra `user_type`. Um principal de automação virando linha de `"user"`
+-- ganharia, de graça, a superfície de login interativo: bastaria o fluxo de
+-- convite/reset alcançar aquele e-mail para que um humano obtivesse uma sessão
+-- HTTP carregando `vault.credential.decrypt`. Além disso, o menor papel de
+-- sistema que carrega essa permissão é `accountant`, que carrega junto
+-- `client.write`, `billing.write` e mais trinta — raio de dano incompatível
+-- com "este processo lê UMA credencial de canal".
+--
+-- O que estas duas tabelas fazem é o mínimo: separar IDENTIDADE (global, como
+-- `"user"`) de AUTORIZAÇÃO (tenant-scoped, como `user_role`), mantendo o
+-- vocabulário de permissão no catálogo já existente (FK para `permission.key`)
+-- e acrescentando os dois escopos que o RBAC de pessoa não tem — PROPÓSITO e
+-- RECURSO. Sem eles, autorizar um workload a decifrar "alguma coisa" no tenant
+-- A o autorizaria a decifrar TUDO do tenant A, e um `credentialRef` vindo de
+-- input viraria confused deputy.
+--
+-- A trava que importa não está aqui, e sim nos privilégios: `baruk_app` recebe
+-- apenas SELECT nestas duas tabelas (ver `db/migrate.ts` §3 e o bloco final
+-- deste arquivo). O processo que CONSOME a autorização não consegue ESCREVÊ-LA.
+-- Autoridade escrita pelo controlado não é autoridade.
+
+-- ── service_principal (identidade global de workload — espelha `"user"`) ─────
+CREATE TABLE service_principal (
+  id                uuid PRIMARY KEY,
+  -- Slug estável, é o que a raiz de composição apresenta ('collection-cron').
+  key               text NOT NULL,
+  display_name      text NOT NULL,
+  status            text NOT NULL DEFAULT 'active'
+                      CHECK (status IN ('active', 'disabled')),
+  -- scrypt, mesmo formato de `user_credential.password_hash`. NUNCA o segredo.
+  -- O segredo em claro vive só no ambiente do deploy que roda aquele workload.
+  secret_hash       text NOT NULL,
+  secret_rotated_at timestamptz,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  updated_at        timestamptz NOT NULL DEFAULT now(),
+  disabled_at       timestamptz,
+  deleted_at        timestamptz
+);
+CREATE UNIQUE INDEX service_principal_key_uq
+  ON service_principal (lower(key)) WHERE deleted_at IS NULL;
+
+-- ── service_principal_grant (autorização tenant-scoped — espelha `user_role`) ─
+-- Uma linha = "o principal P pode exercer a permissão K, no tenant T, para o
+-- propósito R, sobre ESTE recurso". As quatro dimensões são conjuntivas.
+CREATE TABLE service_principal_grant (
+  id             uuid PRIMARY KEY,
+  tenant_id      uuid NOT NULL REFERENCES tenant(id),
+  principal_id   uuid NOT NULL REFERENCES service_principal(id),
+  -- FK para o catálogo: a permissão de workload usa o MESMO vocabulário do
+  -- RBAC de pessoa. Uma permissão inventada não entra.
+  permission_key text NOT NULL REFERENCES permission(key),
+  -- Propósito declarado. Mesmo vocabulário fechado de `SecretAccessReason`.
+  purpose        text NOT NULL
+                   CHECK (purpose IN ('channel_dispatch', 'onboarding_seal', 'health_probe')),
+  -- Escopo de recurso. `exact` = um nome de credencial; `prefix` = um namespace
+  -- ('whatsapp/'). O comprimento mínimo existe para que `prefix = ''` — que
+  -- alcançaria tudo — não seja representável.
+  resource_kind  text NOT NULL CHECK (resource_kind IN ('exact', 'prefix')),
+  resource_value text NOT NULL CHECK (length(btrim(resource_value)) >= 3),
+  -- Quem concedeu. Humano do tenant, ou NULL quando a concessão nasce do
+  -- provisionamento com a credencial de migração. Nunca o próprio principal.
+  granted_by     uuid REFERENCES "user"(id),
+  granted_reason text,
+  created_at     timestamptz NOT NULL DEFAULT now(),
+  -- Validade temporal opcional. NULL = vigente até revogação — deliberado: uma
+  -- concessão do cron de cobrança que vence sozinha vira parada de produção
+  -- silenciosa. A validade CURTA e obrigatória vive na sessão em memória
+  -- (`WorkloadIdentity.expiresAt`), onde expirar não custa disponibilidade.
+  expires_at     timestamptz,
+  revoked_at     timestamptz,
+  deleted_at     timestamptz
+);
+CREATE UNIQUE INDEX service_principal_grant_uq
+  ON service_principal_grant (tenant_id, principal_id, permission_key, purpose,
+                              resource_kind, lower(resource_value))
+  WHERE deleted_at IS NULL AND revoked_at IS NULL;
+CREATE INDEX service_principal_grant_lookup_idx
+  ON service_principal_grant (tenant_id, principal_id, permission_key);
+
+ALTER TABLE service_principal_grant ENABLE ROW LEVEL SECURITY;
+ALTER TABLE service_principal_grant FORCE ROW LEVEL SECURITY;
+CREATE POLICY service_principal_grant_tenant_isolation ON service_principal_grant
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- ── Privilégios: o app LÊ, nunca escreve ────────────────────────────────────
+-- Repetido em `db/migrate.ts` §3 porque o bloco de grants roda DEPOIS das
+-- migrations e concede INSERT/UPDATE/DELETE em ALL TABLES. Aqui o estado já
+-- nasce certo; lá ele sobrevive ao re-grant.
+DO $$
+BEGIN
+  IF EXISTS (SELECT FROM pg_roles WHERE rolname = 'baruk_app') THEN
+    EXECUTE 'GRANT SELECT ON service_principal TO baruk_app';
+    EXECUTE 'GRANT SELECT ON service_principal_grant TO baruk_app';
+    EXECUTE 'REVOKE INSERT, UPDATE, DELETE ON service_principal FROM baruk_app';
+    EXECUTE 'REVOKE INSERT, UPDATE, DELETE ON service_principal_grant FROM baruk_app';
+  END IF;
+END $$;

package/src/db/migrations/0044_channel_onboarding_session.sql

@@ -0,0 +1,96 @@
+-- 0044 — Sessão de onboarding de canal (Embedded Signup da Meta)
+--
+-- O que esta tabela existe para impedir.
+--
+-- O Embedded Signup devolve, NO NAVEGADOR do operador, um `code` trocável por
+-- um token de negócio do cliente. Quem recebe esse `code` no servidor precisa
+-- responder três perguntas antes de trocá-lo:
+--
+--   1. este `code` veio de um fluxo que ESTE tenant iniciou? (CSRF)
+--   2. é a PRIMEIRA vez que ele chega? (replay)
+--   3. o fluxo começou há pouco? (janela)
+--
+-- Nenhuma delas é respondível pelo `code` sozinho: ele é opaco e a Meta não o
+-- amarra a nada nosso. A resposta é um `state` que nós emitimos, guardamos e
+-- consumimos uma única vez — o mesmo mecanismo do OAuth clássico, e pela mesma
+-- razão.
+--
+-- ── Por que o HASH, e não o state ───────────────────────────────────────────
+--
+-- O `state` em claro vive no navegador e volta pela requisição. Guardá-lo em
+-- claro faria desta tabela uma lista de tokens de sessão de onboarding válidos:
+-- qualquer leitura dela (um dump, um log de query, um SELECT de suporte)
+-- entregaria a chave que autoriza a conclusão do fluxo de um escritório. O
+-- hash responde "é este?" sem responder "qual é".
+--
+-- ── Por que o índice é GLOBAL ───────────────────────────────────────────────
+--
+-- A conclusão do fluxo roda no contexto do tenant autenticado, e o `state` é
+-- procurado dentro dele — um state de outro escritório simplesmente não é
+-- encontrado. O índice único global existe para a outra direção: garantir que o
+-- mesmo hash não possa ser emitido duas vezes, nem por tenants distintos, o que
+-- tornaria "consumido uma vez" uma afirmação sobre uma linha e não sobre o
+-- valor.
+
+CREATE TABLE IF NOT EXISTS channel_onboarding_session (
+  id            uuid PRIMARY KEY,
+  tenant_id     uuid NOT NULL REFERENCES tenant(id),
+  -- Produto e marca fazem parte da identidade do vínculo que este fluxo vai
+  -- criar (ver 0041). Guardá-los aqui é o que permite concluir o fluxo sem
+  -- reperguntá-los a quem chama — e portanto sem aceitar que a requisição de
+  -- conclusão os escolha.
+  product       text NOT NULL,
+  brand         text NOT NULL,
+  channel       text NOT NULL CHECK (channel IN ('whatsapp')),
+  provider      text NOT NULL CHECK (provider IN ('meta_whatsapp')),
+  -- sha256 hex do state. NUNCA o state.
+  state_hash    text NOT NULL CHECK (state_hash ~ '^[0-9a-f]{64}$'),
+  -- `pending` → `consumed` (sucesso) | `failed` (troca recusada) | `expired`.
+  -- `failed` é terminal de propósito: um `code` cuja troca falhou não deve ser
+  -- retentado com o mesmo state, porque a falha pode ter sido a Meta já o ter
+  -- consumido — e a segunda tentativa não distingue "erro nosso" de "alguém
+  -- chegou antes".
+  status        text NOT NULL DEFAULT 'pending'
+                  CHECK (status IN ('pending', 'consumed', 'failed', 'expired')),
+  -- Quem abriu o fluxo. Humano, sempre: não existe caminho de máquina para
+  -- iniciar onboarding de canal.
+  created_by    uuid REFERENCES "user"(id),
+  expires_at    timestamptz NOT NULL,
+  consumed_at   timestamptz,
+  -- Classe do erro, nunca a mensagem do provider. A mensagem da Meta pode
+  -- carregar identificadores do negócio do cliente.
+  failure_code  text,
+  -- Identificadores devolvidos pelo fluxo, gravados DEPOIS do sucesso. Não são
+  -- segredo — a Meta os manda em texto claro em todo webhook.
+  waba_ref      text,
+  phone_ref     text,
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  updated_at    timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT channel_onboarding_session_tenant_id_uq UNIQUE (tenant_id, id)
+);
+
+-- Global. Ver o bloco de comentário acima.
+CREATE UNIQUE INDEX IF NOT EXISTS channel_onboarding_session_state_uq
+  ON channel_onboarding_session (state_hash);
+
+-- Listagem do que está aberto, por tenant — é o que a tela consulta.
+CREATE INDEX IF NOT EXISTS channel_onboarding_session_pending_idx
+  ON channel_onboarding_session (tenant_id, channel, created_at DESC)
+  WHERE status = 'pending';
+
+ALTER TABLE channel_onboarding_session ENABLE ROW LEVEL SECURITY;
+ALTER TABLE channel_onboarding_session FORCE ROW LEVEL SECURITY;
+
+-- FORCE porque a política precisa valer inclusive para o dono da tabela — o
+-- papel que roda migration. É a armadilha da 0035/0036, e ela não se repete
+-- aqui.
+CREATE POLICY channel_onboarding_session_tenant_isolation ON channel_onboarding_session
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+COMMENT ON TABLE channel_onboarding_session IS
+  'Sessão de Embedded Signup. Guarda o HASH do state, nunca o state. Consumo é único.';
+COMMENT ON COLUMN channel_onboarding_session.state_hash IS
+  'sha256 hex do state emitido. O valor em claro só existe no navegador do operador.';
+COMMENT ON COLUMN channel_onboarding_session.failure_code IS
+  'Classe do erro. Nunca a mensagem do provider — ela carrega identificadores do negócio do cliente.';