@fayz-ai/db 0.10.0 → 0.12.0

package/migrations/026_audit_trail.sql

@@ -0,0 +1,73 @@
+-- ============================================================================
+-- 026_audit_trail.sql — audit_logs vira leitura, não só depósito.
+--
+-- A tabela existe desde o 001_core e hoje recebe linhas de um lugar só: os RPCs
+-- do agente (`agent_forms_upsert_template` e irmãos). Tudo que uma PESSOA faz
+-- pela tela — criar cliente, corrigir um telefone, excluir um serviço — não
+-- deixava rastro nenhum. O resultado é que "quem mudou isso, e quando" não tinha
+-- resposta em lugar nenhum do produto.
+--
+-- Esta migração NÃO põe gatilho de auditoria em tabela nenhuma. A escrita passa
+-- a sair do único ponto por onde todo cadastro do app já passa — o store de CRUD
+-- (packages/admin/src/stores/createCrudStore.ts), que hoje já emite os eventos
+-- de domínio de created/updated/deleted. Um gatilho por tabela pegaria também as
+-- escritas fora do app, mas custaria uma migração a cada cadastro novo, e
+-- "auditoria funciona pra qualquer cadastro" viraria "funciona nos cadastros de
+-- que alguém lembrou". No chokepoint, um cadastro novo já nasce auditado.
+--
+-- Aqui só fica o que é do banco: a permissão para gravar, quem gravou, e os
+-- índices que fazem essa tabela ser lida sem varredura.
+-- ============================================================================
+
+-- ── Quem gravou ─────────────────────────────────────────────────────────────
+-- Mesma escolha do 025: por gatilho, e não `DEFAULT auth.uid()` na coluna,
+-- para o service_role (edge function, backfill) poder gravar um autor explícito
+-- sem que "escrever NULL de propósito" e "não escrever nada" virem a mesma coisa.
+CREATE OR REPLACE FUNCTION public.handle_audit_actor()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $fn$
+BEGIN
+  NEW.user_id := COALESCE(NEW.user_id, auth.uid());
+  RETURN NEW;
+END;
+$fn$;
+
+REVOKE ALL ON FUNCTION public.handle_audit_actor() FROM public;
+REVOKE ALL ON FUNCTION public.handle_audit_actor() FROM anon;
+
+DROP TRIGGER IF EXISTS audit_logs_actor ON public.audit_logs;
+CREATE TRIGGER audit_logs_actor BEFORE INSERT ON public.audit_logs
+  FOR EACH ROW EXECUTE FUNCTION public.handle_audit_actor();
+
+-- ── Permissão de escrita ────────────────────────────────────────────────────
+-- A política de INSERT estava em `WITH CHECK (true)`: qualquer usuário
+-- autenticado podia gravar uma linha de auditoria em QUALQUER tenant do pool —
+-- inclusive forjando ação em nome de outro. Numa tabela cujo propósito é ser
+-- prova do que aconteceu, isso é o defeito mais caro possível.
+--
+-- `user_id` fica de fora da checagem de propósito: o gatilho acima o preenche
+-- DEPOIS que a política roda, e o RPC do agente grava em nome do ator que o
+-- broker injetou.
+DROP POLICY IF EXISTS "audit_insert" ON public.audit_logs;
+CREATE POLICY "audit_insert" ON public.audit_logs
+  FOR INSERT TO authenticated
+  WITH CHECK (tenant_id IN (SELECT public.user_tenant_ids()));
+
+-- Auditoria não se corrige e não se apaga pela aplicação. Sem política de
+-- UPDATE/DELETE para `authenticated`, a RLS nega — que é o comportamento certo:
+-- um registro de auditoria editável não prova nada. Correção e expurgo por
+-- retenção são trabalho de service_role.
+
+-- ── Leitura ─────────────────────────────────────────────────────────────────
+-- A linha do tempo de uma ficha pergunta sempre a mesma coisa: "os eventos
+-- DESTE registro, do mais novo para o mais velho". Sem este índice é varredura
+-- na tabela inteira do tenant a cada abertura de ficha.
+CREATE INDEX IF NOT EXISTS idx_audit_logs_entity
+  ON public.audit_logs (tenant_id, entity_type, entity_id, created_at DESC);
+
+-- E o feed geral ("o que andou acontecendo"), que ordena só por data.
+CREATE INDEX IF NOT EXISTS idx_audit_logs_recent
+  ON public.audit_logs (tenant_id, created_at DESC);

package/migrations/027_domain_events.sql

@@ -0,0 +1,266 @@
+-- ============================================================================
+-- 027_domain_events.sql — the facts the browser never sees.
+--
+-- Domain events have exactly one emitter today: the CRUD store running in the
+-- browser (packages/admin/src/stores/createCrudStore.ts). It only knows about
+-- writes that pass through it. An edge function's upsert, a CSV import, a
+-- webhook handler, a hand-run SQL fix — none of them produce a fact, and those
+-- are precisely the writes an integration makes. So "notify me when a booking
+-- is created" quietly stops being true the moment bookings start arriving from
+-- outside the app, which is the whole point of having integrations.
+--
+-- This puts the emit seam where every write ends up no matter who made it:
+-- `plg_emit_event` records one fact, `plg_attach_event_source` hangs a generic
+-- trigger on a table. It lives in the core db package and not in
+-- plugin-automations because `emitsFrom` is a manifest field ANY plugin may
+-- declare — the ledger must not depend on an optional plugin being installed.
+--
+-- The ledger table is therefore (re)created here with the SAME shape as
+-- plugins/plugin-automations/migrations/0002_event_log.sql: a pool that already
+-- ran 0002 sees a no-op, a pool without that plugin gets the table.
+--
+-- Nothing is attached to a real table here. Declaring `emitsFrom` in a manifest
+-- is how a plugin opts in, and that wiring is a later milestone.
+-- ============================================================================
+
+-- ── The ledger ──────────────────────────────────────────────────────────────
+-- One row per FACT, not per message sent: the same paid order may drive an
+-- e-mail, a webhook and the audit trail, and only a row tied to the fact can
+-- answer "did the trigger fire at all?" without asking every consumer.
+-- Byte-for-byte the shape of 0002 — divergence here would mean two different
+-- tables answering to one name across the pool fleet.
+CREATE TABLE IF NOT EXISTS public.plg_event_log (
+  id           uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id    uuid NOT NULL,
+  event_key    text NOT NULL,
+  status       text NOT NULL DEFAULT 'recorded'
+               CHECK (status IN ('recorded', 'sent', 'skipped', 'failed')),
+  payload      jsonb NOT NULL DEFAULT '{}'::jsonb,
+  result       jsonb,
+  error        text,
+  actor_id     uuid,
+  subject_type text,
+  subject_id   text,
+  occurred_at  timestamptz NOT NULL DEFAULT now(),
+  created_at   timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS plg_event_log_lookup_idx
+  ON public.plg_event_log (tenant_id, event_key, occurred_at DESC);
+
+CREATE INDEX IF NOT EXISTS plg_event_log_subject_idx
+  ON public.plg_event_log (tenant_id, subject_type, subject_id, occurred_at DESC);
+
+ALTER TABLE public.plg_event_log ENABLE ROW LEVEL SECURITY;
+
+DROP POLICY IF EXISTS plg_event_log_member_read ON public.plg_event_log;
+CREATE POLICY plg_event_log_member_read ON public.plg_event_log
+  FOR SELECT TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+
+DROP POLICY IF EXISTS plg_event_log_member_insert ON public.plg_event_log;
+CREATE POLICY plg_event_log_member_insert ON public.plg_event_log
+  FOR INSERT TO authenticated
+  WITH CHECK (tenant_id IN (SELECT public.user_tenant_ids()));
+
+-- No UPDATE/DELETE policy, same as 0002: a history the application can rewrite
+-- is not a history. Marking 'sent'/'failed' is the dispatcher's job, server-side.
+
+-- ── Dedupe key ──────────────────────────────────────────────────────────────
+-- The SDK emitter mints its own uuid per event (packages/sdk/src/events.ts) so a
+-- retried batch counts as duplicates instead of re-running automations. That id
+-- belongs to the emitter's namespace, not to this table: `id` is the ledger's
+-- own identity, is NOT NULL and is already filled on every legacy row, so it
+-- cannot express "this caller had no dedupe key". A nullable column plus a
+-- partial unique index can — emitters that dedupe get it, the trigger below and
+-- anything else that has no natural id simply pass NULL.
+ALTER TABLE public.plg_event_log ADD COLUMN IF NOT EXISTS event_id uuid;
+
+CREATE UNIQUE INDEX IF NOT EXISTS plg_event_log_event_id_key
+  ON public.plg_event_log (event_id) WHERE event_id IS NOT NULL;
+
+-- ── plg_emit_event ──────────────────────────────────────────────────────────
+CREATE OR REPLACE FUNCTION public.plg_emit_event(
+  p_key          text,
+  p_payload      jsonb DEFAULT '{}'::jsonb,
+  p_subject_type text DEFAULT NULL,
+  p_subject_id   text DEFAULT NULL,
+  p_tenant_id    uuid DEFAULT NULL,
+  p_event_id     uuid DEFAULT NULL
+)
+RETURNS uuid
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $fn$
+DECLARE
+  v_tenants uuid[];
+  v_tenant  uuid := p_tenant_id;
+  v_id      uuid;
+BEGIN
+  IF p_key IS NULL OR p_key = '' THEN
+    RAISE EXCEPTION 'plg_emit_event: p_key is required'
+      USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+
+  SELECT array_agg(t) INTO v_tenants FROM public.user_tenant_ids() AS t;
+
+  IF v_tenant IS NULL THEN
+    -- A fact filed under the wrong tenant is worse than a fact not filed: it is
+    -- readable by people it does not belong to and it triggers their automations.
+    -- With more than one membership and no explicit tenant there is no answer,
+    -- only a guess, so refuse.
+    IF v_tenants IS NULL OR array_length(v_tenants, 1) <> 1 THEN
+      RAISE EXCEPTION 'plg_emit_event: cannot resolve tenant for % — pass p_tenant_id', p_key
+        USING ERRCODE = 'invalid_parameter_value';
+    END IF;
+    v_tenant := v_tenants[1];
+  END IF;
+
+  -- SECURITY DEFINER runs as the owner and therefore bypasses the INSERT policy
+  -- above, so the membership check it would have made has to happen here — the
+  -- same defect 026 fixed on audit_logs. No auth.uid() means service_role or a
+  -- migration, i.e. the server, which legitimately writes for any tenant.
+  IF auth.uid() IS NOT NULL AND NOT (v_tenant = ANY (COALESCE(v_tenants, '{}'::uuid[]))) THEN
+    RAISE EXCEPTION 'plg_emit_event: caller is not a member of tenant %', v_tenant
+      USING ERRCODE = 'insufficient_privilege';
+  END IF;
+
+  BEGIN
+    INSERT INTO public.plg_event_log
+      (tenant_id, event_key, payload, actor_id, subject_type, subject_id, event_id)
+    VALUES
+      (v_tenant, p_key, COALESCE(p_payload, '{}'::jsonb), auth.uid(),
+       p_subject_type, p_subject_id, p_event_id)
+    ON CONFLICT (event_id) WHERE event_id IS NOT NULL DO NOTHING
+    RETURNING id INTO v_id;
+  EXCEPTION WHEN OTHERS THEN
+    -- The write that caused the fact already succeeded. Losing the ledger row is
+    -- bad; taking the customer's saved booking down with it is worse.
+    RAISE WARNING '[plg_emit_event] % not recorded: %', p_key, SQLERRM;
+    RETURN NULL;
+  END;
+
+  RETURN v_id; -- NULL when p_event_id was already recorded.
+END;
+$fn$;
+
+REVOKE ALL ON FUNCTION public.plg_emit_event(text, jsonb, text, text, uuid, uuid) FROM public;
+REVOKE ALL ON FUNCTION public.plg_emit_event(text, jsonb, text, text, uuid, uuid) FROM anon;
+GRANT EXECUTE ON FUNCTION public.plg_emit_event(text, jsonb, text, text, uuid, uuid)
+  TO authenticated, service_role;
+
+-- ── The generic row trigger ─────────────────────────────────────────────────
+-- The payload carries id, display name and entity key — never the row. The whole
+-- row would put CPF, phone and address inside every webhook by default, and
+-- "send everything" is not a decision to make on behalf of whoever installed an
+-- integration; whoever needs the rest fetches it by id. Same envelope the
+-- browser store emits (see the note in core/src/entity/events.ts), plus
+-- `source`, which is how you tell a trigger fact from a store fact when a table
+-- is written by both.
+CREATE OR REPLACE FUNCTION public.plg_emit_row_event()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $fn$
+DECLARE
+  v_row    jsonb;
+  v_action text;
+BEGIN
+  IF TG_OP = 'DELETE' THEN
+    v_row := to_jsonb(OLD);
+    v_action := 'deleted';
+  ELSIF TG_OP = 'UPDATE' THEN
+    -- A touch that changed nothing is not a fact. Without this, any bulk
+    -- re-save floods the ledger with "updated" and buries the real ones.
+    IF OLD IS NOT DISTINCT FROM NEW THEN
+      RETURN NULL;
+    END IF;
+    v_row := to_jsonb(NEW);
+    v_action := 'updated';
+  ELSE
+    v_row := to_jsonb(NEW);
+    v_action := 'created';
+  END IF;
+
+  BEGIN
+    PERFORM public.plg_emit_event(
+      format('registry.%s.%s', TG_ARGV[0], v_action),
+      jsonb_build_object(
+        'record_id', v_row->>'id',
+        -- Mirrors displayName() in createCrudStore: an event without a readable
+        -- name reads as "record" in the timeline.
+        'record_name', COALESCE(v_row->>'name', v_row->>'title', v_row->>'full_name', v_row->>'id'),
+        'entity_key', TG_ARGV[0],
+        'source', 'database'
+      ),
+      TG_ARGV[0],
+      v_row->>'id',
+      NULLIF(v_row->>'tenant_id', '')::uuid,
+      NULL
+    );
+  EXCEPTION WHEN OTHERS THEN
+    -- AFTER trigger or not, an exception here would roll the row's write back.
+    -- Observability must never be able to reject a customer's data.
+    RAISE WARNING '[plg_emit_row_event] % on %: %', v_action, TG_TABLE_NAME, SQLERRM;
+  END;
+
+  RETURN NULL;
+END;
+$fn$;
+
+REVOKE ALL ON FUNCTION public.plg_emit_row_event() FROM public;
+REVOKE ALL ON FUNCTION public.plg_emit_row_event() FROM anon;
+
+-- ── plg_attach_event_source ─────────────────────────────────────────────────
+-- Implements PluginEventSource (core/src/types/plugins.ts): table, entityKey,
+-- actions. Not granted to `authenticated`: it is SECURITY DEFINER and takes an
+-- arbitrary regclass, so an exposed version would let any signed-in user put a
+-- trigger on any table in the pool.
+CREATE OR REPLACE FUNCTION public.plg_attach_event_source(
+  p_table      regclass,
+  p_entity_key text,
+  p_actions    text[] DEFAULT ARRAY['created', 'updated', 'deleted']
+)
+RETURNS void
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $fn$
+DECLARE
+  v_actions text[] := COALESCE(NULLIF(p_actions, '{}'::text[]), ARRAY['created', 'updated', 'deleted']);
+  v_action  text;
+  v_ops     text[] := '{}';
+  v_trigger text;
+BEGIN
+  IF p_entity_key IS NULL OR p_entity_key = '' THEN
+    RAISE EXCEPTION 'plg_attach_event_source: p_entity_key is required'
+      USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+
+  FOREACH v_action IN ARRAY v_actions LOOP
+    CASE v_action
+      WHEN 'created' THEN v_ops := array_append(v_ops, 'INSERT');
+      WHEN 'updated' THEN v_ops := array_append(v_ops, 'UPDATE');
+      WHEN 'deleted' THEN v_ops := array_append(v_ops, 'DELETE');
+      ELSE RAISE EXCEPTION 'plg_attach_event_source: unknown action %', v_action
+        USING ERRCODE = 'invalid_parameter_value';
+    END CASE;
+  END LOOP;
+
+  -- Derived from the table and not from the entity key: one table gets one
+  -- trigger, so re-attaching replaces instead of stacking a second emitter.
+  v_trigger := left(replace(replace(p_table::text, '.', '_'), '"', ''), 48) || '_emit_events';
+
+  EXECUTE format('DROP TRIGGER IF EXISTS %I ON %s', v_trigger, p_table::text);
+  EXECUTE format(
+    'CREATE TRIGGER %I AFTER %s ON %s FOR EACH ROW EXECUTE FUNCTION public.plg_emit_row_event(%L)',
+    v_trigger, array_to_string(v_ops, ' OR '), p_table::text, p_entity_key
+  );
+END;
+$fn$;
+
+REVOKE ALL ON FUNCTION public.plg_attach_event_source(regclass, text, text[]) FROM public;
+REVOKE ALL ON FUNCTION public.plg_attach_event_source(regclass, text, text[]) FROM anon;
+GRANT EXECUTE ON FUNCTION public.plg_attach_event_source(regclass, text, text[]) TO service_role;

package/migrations/028_tenant_scoped_token.sql

@@ -0,0 +1,127 @@
+-- ============================================================================
+-- 028_tenant_scoped_token.sql — a connector's reach comes from its token.
+--
+-- THE EXPOSURE. A pool is ONE Supabase project serving N tenants:
+-- cluster-salon-br-01 (gphxclpkbtbucoqclbco) carries beauty-saas,
+-- espaco-renova-rio and several real clinics in the same `public` schema. Every
+-- plugin edge function builds its client with SUPABASE_SERVICE_ROLE_KEY, and
+-- service_role bypasses RLS by definition — so a connector installed by ONE
+-- clinic can read EVERY clinic in the cluster. No line of that code is wrong;
+-- the credential simply has no tenant in it.
+--
+-- THE SEAM. `public.user_tenant_ids()` is the single function every RLS policy
+-- in the product resolves through (~260 call sites in the SQL tree: db, shop,
+-- courses, plugins). Teach it to honour a `tenant_id` claim and a token becomes a
+-- tenant boundary — no policy is edited, no table is touched.
+--
+-- THIS IS HALF THE FEATURE. Nothing mints such a token yet: minting lives in
+-- the platform repo (../fayz), not here. Until it does, no request carries the
+-- claim, the claim branch is never taken, and the edge functions keep using
+-- service_role — which is exactly why this file is safe to apply now. No edge
+-- function in this repo is changed to expect a token that cannot be issued.
+-- ============================================================================
+
+-- ── public.user_tenant_ids() ────────────────────────────────────────────────
+-- Signature, return type and volatility are unchanged (SETOF uuid, STABLE,
+-- SECURITY DEFINER), so every inherited policy keeps compiling and planning as
+-- it did. Only the body grows a branch.
+--
+-- WHERE THE CLAIM LIVES: top-level `tenant_id`, not `app_metadata.tenant_id`.
+-- The repo reads top-level claims and only top-level ones today (022
+-- `auth.jwt() ->> 'email'`; shop 0019/0023 `->> 'role'`), and GoTrue never puts
+-- a top-level `tenant_id` on a session token — only a JWT we signed ourselves
+-- can carry one. `app_metadata` would instead ride along on every session of
+-- every user whose metadata was ever stamped, silently putting real people on
+-- the narrowing branch and cutting a two-tenant user down to one. Supabase's
+-- own guidance rules out `user_metadata` outright: the user can write it.
+CREATE OR REPLACE FUNCTION public.user_tenant_ids()
+RETURNS SETOF uuid
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+  WITH claim AS (
+    -- PRESENCE of the key and USABILITY of its value are separate questions.
+    -- A token that carries `tenant_id` has expressed intent to be narrowed; if
+    -- the value then fails to parse, the answer is no tenant, never the full
+    -- session handed back. Only an absent key falls through.
+    SELECT coalesce(jsonb_exists(auth.jwt(), 'tenant_id'), false) AS present,
+           auth.jwt() ->> 'tenant_id'                             AS raw
+  ),
+  scoped AS (
+    -- Shape-checked instead of cast blindly: an RLS policy is not a place to
+    -- raise, so a junk value must resolve to no rows rather than an error.
+    SELECT raw::uuid AS tenant_id
+      FROM claim
+     WHERE raw ~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+  )
+  -- No claim at all → the pre-028 behaviour, unchanged. A token with neither a
+  -- claim nor auth.uid() therefore matches no member row and resolves to
+  -- nothing, which is the fail-closed answer.
+  SELECT tm.tenant_id
+    FROM public.tenant_members tm
+   WHERE tm.user_id = auth.uid()
+     AND NOT (SELECT present FROM claim)
+  UNION
+  -- Precedence: the claim NARROWS, it never widens. A signed-in session is the
+  -- stronger authority, so when auth.uid() is present the claim is intersected
+  -- with real membership rather than trusted — a token bearing someone else's
+  -- tenant reaches nothing. Only a session-less token (the connector) is scoped
+  -- by the claim alone, and that token can only exist if we signed it.
+  SELECT s.tenant_id
+    FROM scoped s
+   WHERE auth.uid() IS NULL
+      OR EXISTS (
+           SELECT 1 FROM public.tenant_members tm
+            WHERE tm.user_id = auth.uid() AND tm.tenant_id = s.tenant_id
+         );
+$$;
+
+-- ── The connector role ──────────────────────────────────────────────────────
+-- What a connector may do becomes a property of the role its token lands in.
+-- `fayz_connector` is NOT a service_role understudy: RLS applies to it in full,
+-- and with the claim above that means exactly one tenant. Named for the `fayz_`
+-- prefix the tree already uses for platform-owned objects (fayz_projects,
+-- fayz_migration_ledger, fayz_global_search).
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'fayz_connector') THEN
+    CREATE ROLE fayz_connector NOLOGIN NOINHERIT;
+  END IF;
+END $$;
+
+-- PostgREST SET ROLEs into the role named by the token's `role` claim, which it
+-- can only do if the authenticator it connects as is a member. Guarded because
+-- a bare Postgres (the migration bench) has no authenticator role.
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'authenticator') THEN
+    EXECUTE 'GRANT fayz_connector TO authenticator';
+  END IF;
+END $$;
+
+GRANT USAGE ON SCHEMA public TO fayz_connector;
+
+-- NO DIRECT TABLE ACCESS, now and for tables added later. 008 grants tables to
+-- authenticated/service_role only, so this is already true by omission — stated
+-- explicitly because a silence is not a decision, and because a future blanket
+-- grant would otherwise reach this role too. A connector reads through declared
+-- functions or it does not read.
+REVOKE ALL ON ALL TABLES IN SCHEMA public FROM fayz_connector;
+ALTER DEFAULT PRIVILEGES IN SCHEMA public REVOKE ALL ON TABLES FROM fayz_connector;
+
+-- The RPC surface is opt-in per function, written next to the function that
+-- opens it (`GRANT EXECUTE ON FUNCTION ... TO fayz_connector`), the way
+-- 015/018/022/024 grant themselves. This one is granted here because it is how
+-- a connector answers "which tenant am I?", and it can only ever return the
+-- caller's own scope.
+--
+-- What is NOT done here, deliberately: PUBLIC keeps its default EXECUTE on this
+-- function. RLS policy expressions run as the QUERYING role, so revoking it
+-- would turn anon's storefront catalogue reads into "permission denied for
+-- function user_tenant_ids" instead of zero rows — 009 revoked anon's explicit
+-- grant and anon still works today precisely because PUBLIC's carries it. The
+-- same default means fayz_connector can reach public functions it was never
+-- granted; that is a pre-existing repo-wide condition this file neither creates
+-- nor widens, and its ceiling is RLS plus the claim above.
+GRANT EXECUTE ON FUNCTION public.user_tenant_ids()
+  TO authenticated, service_role, fayz_connector;

package/migrations/029_connections.sql

@@ -0,0 +1,186 @@
+-- ============================================================================
+-- 029_connections.sql — one shape for every connector.
+--
+-- Four connectors exist today and each brought its own pair of tables
+-- (plg_marketing_ranklayer_integrations, bank_integrations, calendar_integrations,
+-- + a *_sync_log each). They are the same table under four names: tenant, on/off,
+-- settings, last sync. At 100 connectors that is 200 tables nobody can audit.
+--
+-- Two tables replace the pair. They live in packages/db and not in a plugin
+-- because a connector must be able to ship with a ConnectorDefinition and no SQL
+-- at all — a table that only exists when some plugin happens to be installed
+-- cannot be that.
+--
+-- The two levels the shape encodes, and they do not flatten (FAY-1376 item 1):
+--   connection = ONE account at the provider (one grant of credentials)
+--   stream     = one resource inside it (a calendar, a bank account)
+-- Two Google accounts are two connections; two calendars are two streams of one
+-- connection. `instance_key` is what separates the first case; `cursors` is
+-- keyed by the second.
+--
+-- SUPERSEDES nothing yet (still true 2026-08-12): the live pool's connections
+-- all sit on bespoke tables and this table is EMPTY there. The bespoke tables
+-- die one ticket each — bank_integrations (FAY-1360), the RankLayer leftovers
+-- (FAY-1391), and plg_calendar_integrations LAST (FAY-1359): it holds a real
+-- clinic's OAuth refresh token, whose destination is the platform's encrypted
+-- ConnectorConnection store (FAY-1388), never a column here. Adding a token
+-- column to this table instead would put every provider's token for every
+-- tenant of a shared pool in one place: strictly worse than today's dispersion.
+-- ============================================================================
+
+-- ── The connection ──────────────────────────────────────────────────────────
+-- No credential column, by construction — a connector cannot store a secret here
+-- because there is nowhere to put one; convention failed three times already.
+CREATE TABLE IF NOT EXISTS public.plg_connections (
+  id                   uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id            uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  connector_id         text NOT NULL,
+  instance_key         text NOT NULL DEFAULT '',   -- bank account, Bling company, gateway instance
+  display_name         text,
+  active               boolean NOT NULL DEFAULT true,    -- the tenant's switch
+  status               text NOT NULL DEFAULT 'pending'   -- health, observed server-side
+                         CHECK (status IN ('pending', 'connected', 'error', 'revoked')),
+  status_detail        text,
+  settings             jsonb NOT NULL DEFAULT '{}'::jsonb,  -- declared keys only; never a credential
+  provider_account_key text,
+  cursors              jsonb NOT NULL DEFAULT '{}'::jsonb,  -- {stream: cursor}
+  last_sync_at         timestamptz,
+  created_at           timestamptz NOT NULL DEFAULT now(),
+  updated_at           timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (tenant_id, connector_id, instance_key)
+);
+
+-- Webhook routing: the provider announces an account, not a tenant. Partial so
+-- the connectors that never learn an account key (api-key ones) are unaffected.
+CREATE UNIQUE INDEX IF NOT EXISTS uq_plg_connections_account_key
+  ON public.plg_connections (connector_id, provider_account_key)
+  WHERE provider_account_key IS NOT NULL;
+
+COMMENT ON TABLE public.plg_connections IS
+  'One tenant''s connection to one account at one provider. Has NO credential '
+  'column by construction: secrets belong to the platform credential store, '
+  'never to a row a connector''s own browser code can write.';
+
+-- ── The run ────────────────────────────────────────────────────────────────
+-- One row per execution of the SYNC plane. An invocation of the `request` plane
+-- (a shipping quote, a checkout session) is NOT a run: it would be the largest
+-- table in the pool within weeks, it is issued for an `anon` buyer with no
+-- tenant-scoped write path, and it has no fetched/written/cursor to record.
+CREATE TABLE IF NOT EXISTS public.plg_sync_runs (
+  id             uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id      uuid NOT NULL,
+  connection_id  uuid NOT NULL REFERENCES public.plg_connections(id) ON DELETE CASCADE,
+  connector_id   text NOT NULL,
+  direction      text NOT NULL CHECK (direction IN ('inbound', 'outbound')),
+  -- `trigger_kind`, never `trigger`: the reserved word already cost the banking
+  -- plugin one migration.
+  trigger_kind   text NOT NULL CHECK (trigger_kind IN ('on-write', 'scheduled', 'manual', 'webhook')),
+  status         text NOT NULL CHECK (status IN ('running', 'success', 'partial', 'error')),
+  stream         text,
+  fetched        integer NOT NULL DEFAULT 0,
+  written        integer NOT NULL DEFAULT 0,
+  stats          jsonb NOT NULL DEFAULT '{}'::jsonb,  -- duplicates, discovered, period_from/to
+  cursor         text,
+  correlation_id uuid,
+  error          text,
+  started_at     timestamptz NOT NULL DEFAULT now(),
+  finished_at    timestamptz
+);
+
+CREATE INDEX IF NOT EXISTS idx_plg_sync_runs_read
+  ON public.plg_sync_runs (connection_id, started_at DESC);
+
+-- ── RLS and the default-privilege trap ─────────────────────────────────────
+-- 011 closed `anon` on every table in the schema and for future ones. It did
+-- NOT close `authenticated`, which is still born with the full set on any new
+-- public table. Here that would be every tenant reading every tenant's
+-- provider_account_key — the bank-account instance key of every clinic in the
+-- pool. So both tables are stripped first and granted back only what they need.
+REVOKE ALL ON public.plg_connections FROM anon, authenticated;
+REVOKE ALL ON public.plg_sync_runs   FROM anon, authenticated;
+
+ALTER TABLE public.plg_connections ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.plg_sync_runs   ENABLE ROW LEVEL SECURITY;
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON public.plg_connections TO authenticated;
+
+-- SELECT only. A history the application can write is not a history: any member
+-- could otherwise forge "sync succeeded" on a shared audit table. Runs are
+-- written server-side (service_role), the same rule plg_event_log follows.
+GRANT SELECT ON public.plg_sync_runs TO authenticated;
+
+DROP POLICY IF EXISTS plg_connections_member_read ON public.plg_connections;
+CREATE POLICY plg_connections_member_read ON public.plg_connections
+  FOR SELECT TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+
+DROP POLICY IF EXISTS plg_connections_member_insert ON public.plg_connections;
+CREATE POLICY plg_connections_member_insert ON public.plg_connections
+  FOR INSERT TO authenticated
+  WITH CHECK (tenant_id IN (SELECT public.user_tenant_ids()));
+
+DROP POLICY IF EXISTS plg_connections_member_update ON public.plg_connections;
+CREATE POLICY plg_connections_member_update ON public.plg_connections
+  FOR UPDATE TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()))
+  WITH CHECK (tenant_id IN (SELECT public.user_tenant_ids()));
+
+DROP POLICY IF EXISTS plg_connections_member_delete ON public.plg_connections;
+CREATE POLICY plg_connections_member_delete ON public.plg_connections
+  FOR DELETE TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+
+DROP POLICY IF EXISTS plg_sync_runs_member_read ON public.plg_sync_runs;
+CREATE POLICY plg_sync_runs_member_read ON public.plg_sync_runs
+  FOR SELECT TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+
+-- No INSERT/UPDATE/DELETE policy on plg_sync_runs, deliberately: the missing
+-- grant above and the missing policy here have to agree, or the next person to
+-- "fix the grant" reopens it.
+
+-- ── Retention ──────────────────────────────────────────────────────────────
+-- Append-only, N tenants per pool, a scheduled pull every 10 minutes. Every
+-- reader wants the last 20 rows; the table wants millions. The prune ships with
+-- the table and not in a later ticket, because by the time it is a ticket the
+-- pool already has the rows.
+--
+-- A run is deleted only when it is BOTH outside the newest N of its connection
+-- AND older than the window. Either test alone is wrong: newest-N alone erases
+-- the morning while someone is debugging it, and age alone empties the panel of
+-- a connector that syncs once a quarter.
+CREATE OR REPLACE FUNCTION public.plg_prune_sync_runs(
+  p_keep_per_connection integer DEFAULT 50,
+  p_keep_days           integer DEFAULT 30
+)
+RETURNS integer
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $fn$
+DECLARE
+  v_rows integer;
+BEGIN
+  WITH ranked AS (
+    SELECT id,
+           row_number() OVER (PARTITION BY connection_id ORDER BY started_at DESC) AS rn
+      FROM public.plg_sync_runs
+  )
+  DELETE FROM public.plg_sync_runs r
+   USING ranked
+   WHERE r.id = ranked.id
+     AND ranked.rn > GREATEST(p_keep_per_connection, 1)
+     AND r.started_at < now() - make_interval(days => GREATEST(p_keep_days, 0));
+  GET DIAGNOSTICS v_rows = ROW_COUNT;
+  RETURN v_rows;
+END;
+$fn$;
+
+REVOKE ALL ON FUNCTION public.plg_prune_sync_runs(integer, integer) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.plg_prune_sync_runs(integer, integer) FROM anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.plg_prune_sync_runs(integer, integer) TO service_role;
+
+COMMENT ON FUNCTION public.plg_prune_sync_runs(integer, integer) IS
+  'Retention for plg_sync_runs: deletes runs that are both outside the newest N '
+  'of their connection and older than the window. No pool runs pg_cron, so the '
+  'caller is the sync ingress — it prunes the connection it just wrote.';