@baruk/core 0.3.1 → 0.5.0

package/src/db/migrations/0045_role_write_scope.sql

@@ -0,0 +1,122 @@
+-- 0045 — fechar a escrita de papel de SISTEMA a partir de contexto de tenant.
+--
+-- ── O defeito ───────────────────────────────────────────────────────────────
+--
+-- `role_visibility` e `role_permission_visibility` nasceram na 0006 assim:
+--
+--   USING      (tenant_id IS NULL OR tenant_id = current_tenant)
+--   WITH CHECK (tenant_id IS NULL OR tenant_id = current_tenant)
+--
+-- O ramo `IS NULL` no USING é necessário e correto: todo tenant precisa LER os
+-- papéis de sistema, senão ninguém autentica. No WITH CHECK ele autoriza a
+-- ESCRITA de linhas com `tenant_id NULL` — que é justamente a marca do papel
+-- global, visível a todos os escritórios.
+--
+-- Reproduzido em 2026-09-05, com o papel de runtime e uma GUC de tenant comum:
+--
+--   1. INSERT de `role` com `tenant_id NULL`         → PASSAVA
+--   2. UPDATE promovendo papel do tenant a global    → PASSAVA
+--   3. INSERT em `role_permission` anexando
+--      `vault.credential.decrypt` ao papel de sistema
+--      `readonly`                                     → PASSAVA
+--
+-- O terceiro é escalada cross-tenant real: `readonly` é semeado em TODO tenant,
+-- e uma permissão anexada a ele alcança todos os escritórios de uma vez.
+--
+-- A 0026 já tinha acertado este padrão em `recurring_item_type` e
+-- `document_category` — `WITH CHECK` sem o ramo `IS NULL`. As duas policies de
+-- 0006 nunca foram alinhadas.
+--
+-- ── A correção, e por que ela vai além de alinhar o WITH CHECK ──────────────
+--
+-- Alinhar o WITH CHECK fecha os vetores 1 e 3, mas deixa a barreira num único
+-- lugar. O levantamento mostrou algo que permite fechar na raiz: **nenhuma rota
+-- da API cria ou altera papel**. O único escritor de `role` em todo o produto é
+-- `ensureRbacCatalog`, e ele roda sempre com a conexão do OWNER — no seed, na
+-- migração e nos testes.
+--
+-- Então o papel de runtime não precisa de escrita nenhuma aqui. Revogá-la torna
+-- "o tenant não forja papel" uma propriedade do PRIVILÉGIO, não só da política —
+-- duas barreiras independentes, e a de fora não depende de nenhuma GUC estar
+-- certa. É o mesmo desenho que a 0043 aplicou a `service_principal`: quem
+-- consome a autorização não consegue escrevê-la.
+--
+-- ── O que isto NÃO faz ──────────────────────────────────────────────────────
+--
+-- Não remove o suporte a papel por escritório: `role.tenant_id` continua lá, e a
+-- policy continua permitindo escrita tenant-scoped para quem tiver privilégio. O
+-- dia em que existir uma rota de papéis customizados, ela entra pelo caminho de
+-- provisionamento (owner) ou por um GRANT explícito e revisado — não pela porta
+-- que estava aberta por acidente.
+
+-- ── 1 · WITH CHECK sem o ramo IS NULL ──────────────────────────────────────
+--
+-- USING preservado: ler papel de sistema é requisito de autenticação.
+
+DROP POLICY IF EXISTS role_visibility ON role;
+CREATE POLICY role_visibility ON role
+  USING (tenant_id IS NULL OR tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+DROP POLICY IF EXISTS role_permission_visibility ON role_permission;
+CREATE POLICY role_permission_visibility ON role_permission
+  USING (tenant_id IS NULL OR tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- ── 2 · O provisionamento continua funcionando ─────────────────────────────
+--
+-- `role` e `role_permission` têm FORCE ROW LEVEL SECURITY, e FORCE vale também
+-- para o dono da tabela. Sem uma política que o autorize, `ensureRbacCatalog`
+-- — que roda com o owner e SEM tenant no contexto — passaria a falhar, e o
+-- produto não subiria em banco novo.
+--
+-- A autorização é nominal ao papel dono do schema (o mesmo que roda migrations),
+-- resolvido em tempo de migração para funcionar em qualquer ambiente. Mesmo
+-- padrão da 0042.
+
+DO $$
+DECLARE
+  owner_role text;
+BEGIN
+  SELECT tableowner INTO owner_role
+    FROM pg_tables WHERE schemaname = 'public' AND tablename = 'role';
+  IF owner_role IS NULL THEN
+    RAISE EXCEPTION 'role sem dono identificável — abortando';
+  END IF;
+
+  EXECUTE 'DROP POLICY IF EXISTS role_system_provisioning ON role';
+  EXECUTE format(
+    'CREATE POLICY role_system_provisioning ON role FOR ALL TO %I USING (true) WITH CHECK (true)',
+    owner_role
+  );
+
+  EXECUTE 'DROP POLICY IF EXISTS role_permission_system_provisioning ON role_permission';
+  EXECUTE format(
+    'CREATE POLICY role_permission_system_provisioning ON role_permission FOR ALL TO %I USING (true) WITH CHECK (true)',
+    owner_role
+  );
+END $$;
+
+-- ── 3 · A segunda barreira: privilégio ─────────────────────────────────────
+--
+-- O runtime lê o catálogo de papéis a cada autenticação e nunca o escreve.
+-- Revogar a escrita fecha os quatro vetores mesmo que uma política futura seja
+-- afrouxada por engano.
+--
+-- Este REVOKE precisa ser repetido em `migrate.ts`, no mesmo bloco que trata
+-- `audit_log` e `service_principal`: o GRANT da allowlist é amplo por
+-- construção e devolveria estes privilégios no deploy seguinte. Foi exatamente
+-- o defeito que a Fase 3 encontrou ao separar GRANT e hardening.
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT FROM pg_roles WHERE rolname = 'baruk_app') THEN
+    EXECUTE 'REVOKE INSERT, UPDATE, DELETE ON role FROM baruk_app';
+    EXECUTE 'REVOKE INSERT, UPDATE, DELETE ON role_permission FROM baruk_app';
+  END IF;
+END $$;
+
+COMMENT ON POLICY role_visibility ON role IS
+  'Leitura: papéis de sistema + os do tenant. Escrita: SOMENTE do tenant — o ramo IS NULL no WITH CHECK permitia forjar papel global (P0-A, Fase 4).';
+COMMENT ON POLICY role_system_provisioning ON role IS
+  'Provisionamento do catálogo de sistema pelo papel dono do schema. FORCE RLS vale para o dono, e ensureRbacCatalog roda sem tenant no contexto.';

package/src/db/migrations/0046_pilot_activation_model.sql

@@ -0,0 +1,184 @@
+-- 0046 — o modelo de dados que falta para ativar um cliente real.
+--
+-- A Fase 5 começou mapeando, contra o schema, exatamente quais dados um
+-- escritório precisa para ativar um cliente. Quatro ausências apareceram, e
+-- todas bloqueiam algo concreto do piloto:
+--
+--  1. **Não há onde guardar município e UF.** Três obrigações do catálogo são
+--     estaduais ou municipais e têm prazo que varia por localidade. Sem UF e
+--     município no cliente, marcar essas obrigações como "depende da localidade"
+--     é honesto mas inútil: não há o dado com que decidir.
+--
+--  2. **Não há responsável pelo cliente.** `recurring_instance` e
+--     `service_request` têm `responsible_user_id`; o cliente não tem. Então a
+--     carteira não pode ser dividida entre as pessoas do escritório — só as
+--     tarefas podem, uma a uma, depois de criadas.
+--
+--  3. **A importação não deixa rastro reversível.** `commitImport` cria
+--     clientes e devolve uma contagem. Não há como responder "quais linhas
+--     entraram naquela importação" nem desfazer uma importação inteira.
+--
+--  4. **A validação humana do catálogo não tem onde ser gravada.** O catálogo
+--     fiscal foi semeado tecnicamente e não foi conferido contra os serviços que
+--     a SC presta. Marcar "conferido" é por escritório, não global — o mesmo
+--     template de sistema pode ser válido para um escritório e não se aplicar a
+--     outro. Por isso é tabela própria, e não coluna em `recurring_item_type`:
+--     aquela linha é COMPARTILHADA entre todos os tenants, e uma coluna nela
+--     faria um escritório carimbar a validação do outro.
+--
+-- Nada aqui liga cobrança, obrigação ou envio. É só onde o dado passa a caber.
+
+-- ── 1 · Localidade e responsável do cliente ────────────────────────────────
+--
+-- Os campos de endereço são deliberadamente poucos: os que o produto usa hoje.
+-- `state_uf` tem CHECK de duas maiúsculas porque é ele que vai selecionar regra
+-- estadual — um "Goias" digitado no lugar de "GO" faria a regra não casar em
+-- silêncio, e silêncio é o modo de falha que esta fase existe para eliminar.
+
+ALTER TABLE client ADD COLUMN IF NOT EXISTS address_line text;
+ALTER TABLE client ADD COLUMN IF NOT EXISTS municipality text;
+ALTER TABLE client ADD COLUMN IF NOT EXISTS state_uf text;
+ALTER TABLE client ADD COLUMN IF NOT EXISTS postal_code text;
+ALTER TABLE client ADD COLUMN IF NOT EXISTS notes text;
+ALTER TABLE client ADD COLUMN IF NOT EXISTS responsible_user_id uuid REFERENCES "user"(id);
+ALTER TABLE client ADD COLUMN IF NOT EXISTS contract_started_on date;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT FROM pg_constraint WHERE conname = 'client_state_uf_format'
+  ) THEN
+    ALTER TABLE client ADD CONSTRAINT client_state_uf_format
+      CHECK (state_uf IS NULL OR state_uf ~ '^[A-Z]{2}$');
+  END IF;
+END $$;
+
+CREATE INDEX IF NOT EXISTS client_responsible_idx
+  ON client (tenant_id, responsible_user_id) WHERE deleted_at IS NULL;
+CREATE INDEX IF NOT EXISTS client_locality_idx
+  ON client (tenant_id, state_uf, municipality) WHERE deleted_at IS NULL;
+
+COMMENT ON COLUMN client.state_uf IS
+  'UF em duas maiúsculas. Seleciona regra estadual de vencimento; formato livre faria a regra não casar em silêncio.';
+COMMENT ON COLUMN client.responsible_user_id IS
+  'Responsável pela carteira deste cliente. Toda troca passa por audit_log — ver assignClientResponsible.';
+
+-- ── 2 · Lote de importação ─────────────────────────────────────────────────
+--
+-- Existe para duas perguntas que hoje não têm resposta: "o que entrou naquela
+-- importação?" e "como desfaço?". O desfazer é lógico (soft-delete dos clientes
+-- do lote que ninguém tocou desde então), nunca físico: apagar linha real é
+-- proibido, e um cliente que já ganhou honorário ou obrigação não é mais "só uma
+-- linha importada".
+--
+-- `source_digest` é o sha256 do CSV. É ele que amarra plano e commit: o commit
+-- recusa aplicar um conteúdo diferente do que foi previsto, em vez de reparsear
+-- e produzir um resultado que ninguém viu.
+
+CREATE TABLE IF NOT EXISTS client_import_batch (
+  id             uuid PRIMARY KEY,
+  tenant_id      uuid NOT NULL REFERENCES tenant(id),
+  source_digest  text NOT NULL,
+  source_name    text,
+  row_total      int  NOT NULL DEFAULT 0,
+  created_count  int  NOT NULL DEFAULT 0,
+  skipped_count  int  NOT NULL DEFAULT 0,
+  error_count    int  NOT NULL DEFAULT 0,
+  status         text NOT NULL DEFAULT 'applied'
+                   CHECK (status IN ('applied', 'rolled_back')),
+  created_by     uuid REFERENCES "user"(id),
+  created_at     timestamptz NOT NULL DEFAULT now(),
+  rolled_back_at timestamptz,
+  rolled_back_by uuid REFERENCES "user"(id),
+  CONSTRAINT client_import_batch_tenant_id_uq UNIQUE (tenant_id, id),
+  CHECK ((status <> 'rolled_back') OR rolled_back_at IS NOT NULL)
+);
+CREATE INDEX IF NOT EXISTS client_import_batch_tenant_idx
+  ON client_import_batch (tenant_id, created_at DESC);
+
+ALTER TABLE client ADD COLUMN IF NOT EXISTS import_batch_id uuid;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT FROM pg_constraint WHERE conname = 'client_import_batch_fk') THEN
+    ALTER TABLE client ADD CONSTRAINT client_import_batch_fk
+      FOREIGN KEY (tenant_id, import_batch_id)
+      REFERENCES client_import_batch (tenant_id, id);
+  END IF;
+END $$;
+
+CREATE INDEX IF NOT EXISTS client_import_batch_idx
+  ON client (tenant_id, import_batch_id) WHERE import_batch_id IS NOT NULL;
+
+ALTER TABLE client_import_batch ENABLE ROW LEVEL SECURITY;
+ALTER TABLE client_import_batch FORCE ROW LEVEL SECURITY;
+CREATE POLICY client_import_batch_tenant_isolation ON client_import_batch
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- ── 3 · Validação humana do catálogo, por escritório ───────────────────────
+--
+-- Um item do catálogo, para um escritório, está em um de quatro estados. O
+-- padrão é `pending_validation` e ele é o ponto inteiro: enquanto ninguém
+-- conferiu, o produto deve DIZER que ninguém conferiu, em vez de deixar o seed
+-- passar por verdade operacional.
+--
+-- `depends_on_locality` marca os itens cujo prazo muda por UF ou município. Não
+-- é um prazo inventado — é a ausência de prazo, declarada.
+
+CREATE TABLE IF NOT EXISTS recurring_item_type_validation (
+  id             uuid PRIMARY KEY,
+  tenant_id      uuid NOT NULL REFERENCES tenant(id),
+  item_type_id   uuid NOT NULL REFERENCES recurring_item_type(id),
+  status         text NOT NULL DEFAULT 'pending_validation'
+                   CHECK (status IN ('validated', 'pending_validation', 'not_applicable', 'disabled')),
+  depends_on_locality boolean NOT NULL DEFAULT false,
+  note           text,
+  validated_by   uuid REFERENCES "user"(id),
+  validated_at   timestamptz,
+  created_at     timestamptz NOT NULL DEFAULT now(),
+  updated_at     timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT recurring_item_type_validation_tenant_id_uq UNIQUE (tenant_id, id),
+  CHECK ((status <> 'validated') OR validated_at IS NOT NULL)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS recurring_item_type_validation_uq
+  ON recurring_item_type_validation (tenant_id, item_type_id);
+
+ALTER TABLE recurring_item_type_validation ENABLE ROW LEVEL SECURITY;
+ALTER TABLE recurring_item_type_validation FORCE ROW LEVEL SECURITY;
+CREATE POLICY recurring_item_type_validation_tenant_isolation ON recurring_item_type_validation
+  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 recurring_item_type_validation IS
+  'Conferência humana do catálogo, POR ESCRITÓRIO. Tabela própria porque recurring_item_type com tenant_id NULL é linha compartilhada: coluna nela faria um escritório carimbar a validação do outro.';
+
+-- ── 4 · O serviço contratado ganha responsável e vínculo com obrigação ─────
+--
+-- `fee_agreement` já era a entidade de serviço contratado: tem descrição, valor,
+-- periodicidade, vencimento, início, fim e status, e um cliente pode ter
+-- vários. Não se cria entidade nova para o que já existe. Faltavam duas coisas.
+--
+-- O vínculo é tabela de ligação porque a relação é N-para-N de verdade: um
+-- serviço de folha cobre eSocial, FGTS e a própria folha; e a mesma obrigação
+-- pode estar coberta por mais de um contrato ao longo do tempo.
+
+ALTER TABLE fee_agreement ADD COLUMN IF NOT EXISTS responsible_user_id uuid REFERENCES "user"(id);
+
+CREATE TABLE IF NOT EXISTS fee_agreement_obligation (
+  id                uuid PRIMARY KEY,
+  tenant_id         uuid NOT NULL REFERENCES tenant(id),
+  fee_agreement_id  uuid NOT NULL,
+  item_type_id      uuid NOT NULL REFERENCES recurring_item_type(id),
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT fee_agreement_obligation_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, fee_agreement_id) REFERENCES fee_agreement (tenant_id, id)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS fee_agreement_obligation_uq
+  ON fee_agreement_obligation (tenant_id, fee_agreement_id, item_type_id);
+
+ALTER TABLE fee_agreement_obligation ENABLE ROW LEVEL SECURITY;
+ALTER TABLE fee_agreement_obligation FORCE ROW LEVEL SECURITY;
+CREATE POLICY fee_agreement_obligation_tenant_isolation ON fee_agreement_obligation
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);

package/src/db/migrations/0047_recipient_clearance.sql

@@ -0,0 +1,89 @@
+-- 0047 — liberação do destinatário para comunicação externa.
+--
+-- ── O que foi medido em produção ────────────────────────────────────────────
+--
+-- Em 2026-09-05, às 12:00, o cron de cobrança enviou 5 e-mails no tenant `sc`.
+-- Hoje isso é inofensivo: o único cliente com e-mail cadastrado é o do próprio
+-- titular, e os recebíveis são sintéticos.
+--
+-- O problema aparece no dia seguinte à importação da carteira real. A régua
+-- percorre todo cliente com e-mail e recebível vencido, e **nada no caminho
+-- pergunta se alguém conferiu aquele endereço**. Trezentos clientes importados
+-- de manhã recebem cobrança automática à tarde, sobre dados que ninguém
+-- validou. Foi exatamente assim que 81 e-mails saíram sobre a carteira de QA.
+--
+-- ── Por que não é consentimento ─────────────────────────────────────────────
+--
+-- O motor já tem consentimento, e ele está certo do jeito que está: a política
+-- do produto trata `unknown` como permitido no e-mail porque cobrança
+-- transacional se apoia na relação contratual. Mudar isso travaria a cobrança
+-- de toda carteira legada que nunca teve o campo preenchido — o próprio código
+-- do consentimento avisa disso.
+--
+-- São perguntas diferentes:
+--
+--   consentimento → "esta pessoa aceita ser contatada?"   (vontade do DESTINATÁRIO)
+--   liberação     → "alguém daqui conferiu este endereço?" (conferência do REMETENTE)
+--
+-- Elas se separam exatamente no caso que importa: o cliente recém-importado tem
+-- relação contratual e nenhuma conferência.
+--
+-- ── Por que a ausência bloqueia ─────────────────────────────────────────────
+--
+-- O padrão é NÃO liberado, e não existe configuração que inverta isso. Um
+-- default "libera se ninguém disse nada" transformaria a omissão em
+-- autorização — e omissão é o estado natural de todo cliente que acabou de
+-- entrar. O cliente não some da operação: ele aparece com pulo nomeado
+-- (`recipient_not_confirmed`) na trilha e contado no painel.
+
+ALTER TABLE client ADD COLUMN IF NOT EXISTS communication_cleared_at timestamptz;
+ALTER TABLE client ADD COLUMN IF NOT EXISTS communication_cleared_by uuid REFERENCES "user"(id);
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT FROM pg_constraint WHERE conname = 'client_clearance_coherent') THEN
+    -- Data e autor andam juntos: uma liberação sem autor não responde "quem
+    -- conferiu?", que é a única pergunta que ela existe para responder.
+    ALTER TABLE client ADD CONSTRAINT client_clearance_coherent
+      CHECK ((communication_cleared_at IS NULL) = (communication_cleared_by IS NULL));
+  END IF;
+END $$;
+
+CREATE INDEX IF NOT EXISTS client_clearance_idx
+  ON client (tenant_id, communication_cleared_at) WHERE deleted_at IS NULL;
+
+COMMENT ON COLUMN client.communication_cleared_at IS
+  'Quando alguém do escritório conferiu o contato e liberou este cliente para comunicação externa. NULL = não liberado, e a régua pula com motivo nomeado.';
+
+-- ── Marco de início do piloto real ──────────────────────────────────────────
+--
+-- Os registros hoje no tenant `sc` são de desenvolvimento, QA, homologação e
+-- demonstração — inclusive os do App Review da Meta. Nenhum é carteira real.
+--
+-- Sem um marco explícito, daqui a três meses ninguém distingue "cliente de
+-- teste de agosto" de "cliente real de setembro", e todo indicador do painel
+-- passa a misturar os dois. A tabela existe para que a fronteira seja um FATO
+-- gravado, com autor e data, e não uma lembrança.
+
+CREATE TABLE IF NOT EXISTS tenant_pilot_milestone (
+  id           uuid PRIMARY KEY,
+  tenant_id    uuid NOT NULL REFERENCES tenant(id),
+  milestone    text NOT NULL CHECK (milestone IN ('real_pilot_start')),
+  occurred_at  timestamptz NOT NULL DEFAULT now(),
+  declared_by  uuid REFERENCES "user"(id),
+  note         text,
+  CONSTRAINT tenant_pilot_milestone_tenant_id_uq UNIQUE (tenant_id, id)
+);
+
+-- Um marco por tenant: "quando começou de verdade" não admite duas respostas.
+CREATE UNIQUE INDEX IF NOT EXISTS tenant_pilot_milestone_uq
+  ON tenant_pilot_milestone (tenant_id, milestone);
+
+ALTER TABLE tenant_pilot_milestone ENABLE ROW LEVEL SECURITY;
+ALTER TABLE tenant_pilot_milestone FORCE ROW LEVEL SECURITY;
+CREATE POLICY tenant_pilot_milestone_tenant_isolation ON tenant_pilot_milestone
+  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 tenant_pilot_milestone IS
+  'Fronteira gravada entre dado pré-produtivo (QA, demo, Meta App Review) e carteira real. Sem ela, os indicadores do painel misturam os dois e ninguém consegue separar depois.';

package/src/db/migrations/0048_item_type_note.sql

@@ -0,0 +1,16 @@
+-- 0048 — a observação do catálogo passa a chegar a quem confere.
+--
+-- `FiscalCatalogEntry.note` existe na vertical desde a Fase 3, com o comentário
+-- "Aparece na UI para o operador saber o que ajustar". Ela nunca apareceu:
+-- não havia coluna, o seed não a escrevia, e a tela não tinha o que mostrar.
+--
+-- Nove das dezessete entradas têm nota, e são exatamente as que o escritório
+-- precisa ler para decidir — as de esfera estadual e municipal, cujo prazo
+-- muda por localidade, e as que dependem do segmento atendido. A conferência
+-- humana do catálogo é o bloqueio desta fase, e ela estava sendo pedida sem a
+-- informação que a torna possível.
+
+ALTER TABLE recurring_item_type ADD COLUMN IF NOT EXISTS note text;
+
+COMMENT ON COLUMN recurring_item_type.note IS
+  'Observação para quem confere: o que este item exige de decisão local (UF, município, segmento). Não é regra — é o que o operador precisa saber para decidir.';