@fayz-ai/db 0.10.0 → 0.12.0

package/migrations/030_effect_idempotency.sql

@@ -0,0 +1,159 @@
+-- ============================================================================
+-- 030_effect_idempotency.sql — the run row IS the claim.
+--
+-- 029 drew the line the request plane needs: a QUOTE is not a run (no fetched,
+-- no written, no cursor, and an `anon` shopper with no tenant-scoped write path
+-- to file one with), while the EFFECTS a quote leads to — capture the payment,
+-- buy the label — are ordinary rows of plg_sync_runs.
+--
+-- What 029 could not express is the half of an effect that the sync plane never
+-- needed: nobody double-clicks a cron. A gateway that re-delivers its webhook,
+-- and a buyer who clicks "pagar" twice, both arrive as a second call to capture
+-- the same order for the same amount. The sync plane's answer — "the run is
+-- filed after the work" — leaves exactly the window in which the second call
+-- charges again.
+--
+-- So the claim and the run become one statement. `plg_claim_effect` inserts the
+-- run row with the buyer-derived key and lets the unique index decide the race:
+-- the caller that inserted owns the effect, the caller that conflicted is handed
+-- the FIRST run's id and told not to call the provider. Two connectors need this
+-- (AppMax capture, Melhor Envio label), which is why it is here and not in
+-- either of them.
+--
+-- WHY A COLUMN AND NOT A TABLE. A second table would have to be kept in
+-- agreement with plg_sync_runs about which effects happened — two sources of
+-- truth for one fact, and the failure mode is a claim with no run behind it (or
+-- the reverse) that nobody notices until a customer is charged twice. The claim
+-- and the record of the effect are the same row on purpose.
+--
+-- The column is NULLABLE and the index PARTIAL: an ordinary sync run carries no
+-- key and is completely unaffected. Nothing about the sync plane changes here.
+-- ============================================================================
+
+ALTER TABLE public.plg_sync_runs
+  ADD COLUMN IF NOT EXISTS idempotency_key text;
+
+-- Scoped to (tenant, connector) rather than to the connection: an order is
+-- captured once per gateway for a tenant, whichever instance of that gateway
+-- answered. Including tenant_id is not decoration — a key is derived from an
+-- order id, and two tenants of one pool must never be able to make each other's
+-- capture look like a duplicate that was already done.
+CREATE UNIQUE INDEX IF NOT EXISTS uq_plg_sync_runs_effect_key
+  ON public.plg_sync_runs (tenant_id, connector_id, idempotency_key)
+  WHERE idempotency_key IS NOT NULL;
+
+COMMENT ON COLUMN public.plg_sync_runs.idempotency_key IS
+  'Buyer-derived key for an effect on the request plane (capture, label). NULL '
+  'for every sync run and for every quote — a quote is not a run at all. Unique '
+  'per (tenant, connector) so a re-delivered webhook claims the first run '
+  'instead of performing the effect a second time.';
+
+-- ── Claim ───────────────────────────────────────────────────────────────────
+-- Returns (run_id, claimed). `claimed = false` means the key already ran: hand
+-- back the first run and DO NOT call the provider.
+--
+-- The tenant is resolved from the connection row and never taken from the
+-- caller — the same discipline plugbank_import_movements follows, and the reason
+-- a compromised data-plane call cannot file an effect against a tenant it does
+-- not hold a connection for.
+CREATE OR REPLACE FUNCTION public.plg_claim_effect(
+  p_connection_id   uuid,
+  p_idempotency_key text,
+  p_direction       text,
+  p_trigger_kind    text,
+  p_stream          text DEFAULT NULL
+)
+RETURNS TABLE (run_id uuid, claimed boolean)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $fn$
+DECLARE
+  v_tenant_id    uuid;
+  v_connector_id text;
+  v_id           uuid;
+BEGIN
+  IF p_idempotency_key IS NULL OR btrim(p_idempotency_key) = '' THEN
+    -- An effect nobody can name twice is an effect that runs twice. There is no
+    -- "just this once" path, because that path is the one a retry takes.
+    RAISE EXCEPTION 'plg_claim_effect requires an idempotency key';
+  END IF;
+
+  SELECT c.tenant_id, c.connector_id INTO v_tenant_id, v_connector_id
+    FROM public.plg_connections c
+   WHERE c.id = p_connection_id;
+
+  IF v_tenant_id IS NULL THEN
+    RAISE EXCEPTION 'plg_claim_effect: no connection %', p_connection_id;
+  END IF;
+
+  INSERT INTO public.plg_sync_runs
+    (tenant_id, connection_id, connector_id, direction, trigger_kind, status, stream, idempotency_key)
+  VALUES
+    (v_tenant_id, p_connection_id, v_connector_id, p_direction, p_trigger_kind, 'running', p_stream, p_idempotency_key)
+  ON CONFLICT (tenant_id, connector_id, idempotency_key) WHERE idempotency_key IS NOT NULL
+  DO NOTHING
+  RETURNING id INTO v_id;
+
+  IF v_id IS NOT NULL THEN
+    RETURN QUERY SELECT v_id, true;
+    RETURN;
+  END IF;
+
+  SELECT r.id INTO v_id
+    FROM public.plg_sync_runs r
+   WHERE r.tenant_id = v_tenant_id
+     AND r.connector_id = v_connector_id
+     AND r.idempotency_key = p_idempotency_key;
+
+  RETURN QUERY SELECT v_id, false;
+END;
+$fn$;
+
+-- ── Settle ─────────────────────────────────────────────────────────────────
+-- Closes the run the claim opened. `finished_at IS NULL` in the WHERE is the
+-- guard that matters: a replayed webhook cannot rewrite an effect that already
+-- has a verdict, so "captured" never becomes "error" because the gateway
+-- re-sent an old event.
+CREATE OR REPLACE FUNCTION public.plg_settle_effect(
+  p_run_id uuid,
+  p_status text,
+  p_stats  jsonb DEFAULT '{}'::jsonb,
+  p_error  text  DEFAULT NULL
+)
+RETURNS boolean
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $fn$
+DECLARE
+  v_rows integer;
+BEGIN
+  UPDATE public.plg_sync_runs
+     SET status      = p_status,
+         stats       = COALESCE(p_stats, '{}'::jsonb),
+         error       = p_error,
+         finished_at = now()
+   WHERE id = p_run_id
+     AND finished_at IS NULL;
+  GET DIAGNOSTICS v_rows = ROW_COUNT;
+  RETURN v_rows > 0;
+END;
+$fn$;
+
+-- Server-side only, exactly like the runs table itself: 029 grants
+-- `authenticated` SELECT and nothing else, and a SECURITY DEFINER function that
+-- inserts runs would hand back the INSERT that grant deliberately withholds.
+-- The shopper is `anon` and reaches neither.
+REVOKE ALL ON FUNCTION public.plg_claim_effect(uuid, text, text, text, text) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.plg_claim_effect(uuid, text, text, text, text) FROM anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.plg_claim_effect(uuid, text, text, text, text) TO service_role;
+
+REVOKE ALL ON FUNCTION public.plg_settle_effect(uuid, text, jsonb, text) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.plg_settle_effect(uuid, text, jsonb, text) FROM anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.plg_settle_effect(uuid, text, jsonb, text) TO service_role;
+
+COMMENT ON FUNCTION public.plg_claim_effect(uuid, text, text, text, text) IS
+  'Claim an effect on the request plane. The run row is the claim: the caller '
+  'that inserts owns it, the caller that conflicts gets the first run back with '
+  'claimed=false and must not call the provider. Quotes never come here.';

package/migrations/031_sync_run_message.sql

@@ -0,0 +1,39 @@
+-- ============================================================================
+-- 031_sync_run_message.sql — the one thing the generic shape split in two.
+--
+-- Four connectors brought a bespoke sync log and every one of them had a single
+-- `message`/`error` column carrying whatever the run had to say. 029 kept only
+-- the failure half (`error`), on the reasonable-sounding theory that a
+-- successful run says everything in `fetched`/`written`.
+--
+-- It does not. "Importado do extrato de 01/08 a 12/08, 3 duplicados ignorados"
+-- is a successful run with something to say, and RankLayer's panel had to
+-- reconstruct it as `run.error ?? run.stats.message` — an ad-hoc key inside a
+-- free-form jsonb, which is precisely the convention the generic tables exist
+-- to stop the sixth connector from reinventing.
+--
+-- So: one nullable text column, and the rule that goes with it —
+--   error   is what went WRONG. Null on a successful run, always.
+--   message is what the run has to SAY. Set on any status, including 'error',
+--           where it is the human sentence next to the machine one.
+--
+-- Additive and idempotent: every pool has already applied 029, and `fayz db
+-- apply` re-runs a file whose checksum moved, so this must be safe twice.
+-- ============================================================================
+
+ALTER TABLE public.plg_sync_runs
+  ADD COLUMN IF NOT EXISTS message text;
+
+COMMENT ON COLUMN public.plg_sync_runs.message IS
+  'What the run has to say, on any status. `error` stays reserved for what went '
+  'wrong, so a successful run with something to report no longer has to smuggle '
+  'it through stats.';
+
+-- No grant statement here, deliberately, and the omission is load-bearing.
+--
+-- A defensive `REVOKE INSERT, UPDATE, DELETE … FROM authenticated` looks like
+-- belt and braces. It is the opposite: 029 is the file that owns the write ban,
+-- and re-asserting it here means the bench's negative control (which deletes
+-- 029's REVOKE and demands that C3 go red) passes with the ban gone. A second
+-- REVOKE does not add a guarantee, it hides the loss of the first one.
+-- The property is asserted instead — connections.regression.sql C10c.

package/migrations/032_connection_secrets.sql

@@ -0,0 +1,227 @@
+-- ============================================================================
+-- 032_connection_secrets.sql — the credential holder 029 promised and nobody built.
+--
+-- 029 wrote, on the table itself: "secrets belong to the platform credential
+-- store, never to a row a connector's own browser code can write." That was the
+-- right call and it left a hole, because the platform credential store does not
+-- exist (FAY-1381). The consequence is not theoretical:
+--
+--   * Bling declares authKind 'oauth' and its Connect button is disabled,
+--     because there is nowhere to put the refresh token the consent returns.
+--   * AppMax and Melhor Envio declare an api-key field, the hub routes it to
+--     ConnectorCredentialSink, and no app installs a sink — so the honest
+--     outcome is "cannot save", which is where they are now.
+--   * google-calendar still cannot migrate off its bespoke table for exactly
+--     this reason; 029 said so in its own header.
+--
+-- Three connectors, one missing thing. This file is that thing, scoped to the
+-- pool rather than the platform: Supabase Vault is installed here
+-- (`supabase_vault`, encrypted at rest, keyed outside the table), so the pool
+-- CAN hold a tenant credential safely today. When the platform broker ships,
+-- the data plane keeps calling the same three functions and the storage moves
+-- underneath — which is the point of putting the functions in front of it.
+--
+-- ── Why a table of ids and not a column on plg_connections ──────────────────
+-- Because 029's argument still holds in full. A credential column is a column
+-- some later `select *` returns, some later RLS policy exposes, and some later
+-- connector writes from the browser. Nothing here changes that: plg_connections
+-- keeps no credential, and the bench's C1 keeps proving it.
+--
+-- What this table holds is a POINTER — `(connection, key) → vault secret id`.
+-- The secret itself lives in vault.secrets, encrypted, reachable only through a
+-- SECURITY DEFINER function that no client role may execute.
+--
+-- ── Why the mapping table at all, when the vault name is deterministic ──────
+-- `plg:<connection_id>:<key>` could be recomputed instead of stored. The table
+-- earns its place three times over: ON DELETE CASCADE means disconnecting a
+-- connection takes its credentials with it without anyone remembering to; the
+-- keys of a connection can be enumerated without granting a single privilege on
+-- the vault schema; and the drop path deletes what it actually stored rather
+-- than what it guesses the name should have been.
+--
+-- ── Why the table is granted to nobody ──────────────────────────────────────
+-- It holds ids, not secrets. It is still shut to `anon` and `authenticated`,
+-- because an id is a handle, and the whole design rests on the handle being
+-- unreachable from the browser. A tenant that can read the handle is one
+-- "GRANT SELECT ON vault.decrypted_secrets TO authenticated for debugging"
+-- away from reading the credential — and that grant is a one-liner somebody
+-- will be tempted by at 2am. Take the handle away and the temptation has
+-- nothing to act on.
+--
+-- Idempotent, because `fayz db apply` re-runs a file whose checksum moved.
+-- ============================================================================
+
+-- ── The pointer ─────────────────────────────────────────────────────────────
+-- One row per (connection, key). `key` is the connector's own field name —
+-- 'access_token' / 'refresh_token' for an OAuth connector, the declared field
+-- key ('apiKey', 'token') for an api-key one. Deliberately free text: the set
+-- of keys belongs to the ConnectorDefinition, and a CHECK here would mean every
+-- new connector needs a migration.
+CREATE TABLE IF NOT EXISTS public.plg_connection_secrets (
+  connection_id   uuid NOT NULL REFERENCES public.plg_connections(id) ON DELETE CASCADE,
+  key             text NOT NULL,
+  vault_secret_id uuid NOT NULL,
+  created_at      timestamptz NOT NULL DEFAULT now(),
+  updated_at      timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (connection_id, key)
+);
+
+COMMENT ON TABLE public.plg_connection_secrets IS
+  'Pointer table: (connection, key) -> vault secret id. Holds NO secret value '
+  'and is granted to NO client role. The three plg_*_connection_secret(s) '
+  'functions are the only way in or out, and only service_role may call them.';
+
+-- ── Grants: none, and the RLS has to agree ─────────────────────────────────
+-- 011 shut `anon` out of every new table in this schema and left `authenticated`
+-- born with the full set — the same trap 029 documented. Both are stripped, and
+-- nothing is granted back. RLS is enabled with NO policy, which for a
+-- non-owner role means deny-all; the REVOKE and the empty policy set have to
+-- agree, or the next person to "fix the grant" reopens it silently.
+REVOKE ALL ON public.plg_connection_secrets FROM PUBLIC;
+REVOKE ALL ON public.plg_connection_secrets FROM anon, authenticated;
+
+ALTER TABLE public.plg_connection_secrets ENABLE ROW LEVEL SECURITY;
+
+-- ── Store ───────────────────────────────────────────────────────────────────
+-- Upsert semantics, and they are load-bearing: Bling's refresh token is
+-- replaced on every renewal, and a store that appended would leave the pool
+-- holding a growing pile of dead credentials — each one still decryptable.
+-- One connection+key is one vault secret, forever.
+--
+-- The vault name is derived, never supplied, so a caller cannot aim this at
+-- another connection's secret or at an unrelated vault entry.
+CREATE OR REPLACE FUNCTION public.plg_store_connection_secret(
+  p_connection_id uuid,
+  p_key           text,
+  p_secret        text
+)
+RETURNS uuid
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $fn$
+DECLARE
+  v_name  text;
+  v_id    uuid;
+BEGIN
+  IF p_connection_id IS NULL OR coalesce(p_key, '') = '' THEN
+    RAISE EXCEPTION 'connection id and key are required';
+  END IF;
+  -- The key becomes part of a vault name; keep it to an identifier so it cannot
+  -- carry a colon and collide with another connection's namespace.
+  IF p_key !~ '^[a-zA-Z0-9_.-]{1,64}$' THEN
+    RAISE EXCEPTION 'invalid secret key';
+  END IF;
+  IF p_secret IS NULL OR length(p_secret) = 0 THEN
+    RAISE EXCEPTION 'refusing to store an empty secret';
+  END IF;
+
+  v_name := 'plg:' || p_connection_id::text || ':' || p_key;
+
+  SELECT vault_secret_id INTO v_id
+    FROM public.plg_connection_secrets
+   WHERE connection_id = p_connection_id AND key = p_key;
+
+  -- A vault entry may outlive its pointer (a manual DELETE, a half-applied
+  -- earlier run). Adopt it rather than create a second one under a name the
+  -- vault's unique index would reject anyway.
+  IF v_id IS NULL THEN
+    SELECT id INTO v_id FROM vault.secrets WHERE name = v_name;
+  END IF;
+
+  IF v_id IS NULL THEN
+    v_id := vault.create_secret(p_secret, v_name, 'fayz connector credential');
+  ELSE
+    PERFORM vault.update_secret(v_id, p_secret);
+  END IF;
+
+  INSERT INTO public.plg_connection_secrets (connection_id, key, vault_secret_id)
+  VALUES (p_connection_id, p_key, v_id)
+  ON CONFLICT (connection_id, key)
+  DO UPDATE SET vault_secret_id = EXCLUDED.vault_secret_id, updated_at = now();
+
+  RETURN v_id;
+END;
+$fn$;
+
+-- ── Read ────────────────────────────────────────────────────────────────────
+-- What the data plane calls at run time, and the only decrypt path that exists.
+-- Returns NULL rather than raising when there is nothing stored: "not connected"
+-- is an ordinary answer for a connector, not an exception.
+CREATE OR REPLACE FUNCTION public.plg_read_connection_secret(
+  p_connection_id uuid,
+  p_key           text
+)
+RETURNS text
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $fn$
+DECLARE
+  v_secret text;
+BEGIN
+  SELECT d.decrypted_secret INTO v_secret
+    FROM public.plg_connection_secrets s
+    JOIN vault.decrypted_secrets d ON d.id = s.vault_secret_id
+   WHERE s.connection_id = p_connection_id AND s.key = p_key;
+  RETURN v_secret;
+END;
+$fn$;
+
+-- ── Drop ────────────────────────────────────────────────────────────────────
+-- Disconnect. 029's C9g rule stands — a disconnect FREEZES the mirror and keeps
+-- the connection row and its history — but the credential is exactly the thing
+-- that must not survive it, so this deletes the vault entries as well as the
+-- pointers. Returns the count so the caller can log a real number.
+--
+-- The CASCADE on the table only removes pointers when the whole connection is
+-- deleted; the vault rows would be orphaned. That is why this function exists
+-- rather than a `DELETE FROM plg_connection_secrets`.
+CREATE OR REPLACE FUNCTION public.plg_drop_connection_secrets(p_connection_id uuid)
+RETURNS integer
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $fn$
+DECLARE
+  v_ids  uuid[];
+  v_rows integer;
+BEGIN
+  SELECT array_agg(vault_secret_id) INTO v_ids
+    FROM public.plg_connection_secrets WHERE connection_id = p_connection_id;
+
+  DELETE FROM public.plg_connection_secrets WHERE connection_id = p_connection_id;
+  GET DIAGNOSTICS v_rows = ROW_COUNT;
+
+  IF v_ids IS NOT NULL THEN
+    DELETE FROM vault.secrets WHERE id = ANY (v_ids);
+  END IF;
+
+  RETURN v_rows;
+END;
+$fn$;
+
+-- ── The grant discipline, three times ──────────────────────────────────────
+-- PUBLIC first: EXECUTE on a new function is granted to PUBLIC by default, and
+-- revoking from anon/authenticated alone leaves it reachable through that.
+REVOKE ALL ON FUNCTION public.plg_store_connection_secret(uuid, text, text) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.plg_store_connection_secret(uuid, text, text) FROM anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.plg_store_connection_secret(uuid, text, text) TO service_role;
+
+REVOKE ALL ON FUNCTION public.plg_read_connection_secret(uuid, text) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.plg_read_connection_secret(uuid, text) FROM anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.plg_read_connection_secret(uuid, text) TO service_role;
+
+REVOKE ALL ON FUNCTION public.plg_drop_connection_secrets(uuid) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.plg_drop_connection_secrets(uuid) FROM anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.plg_drop_connection_secrets(uuid) TO service_role;
+
+COMMENT ON FUNCTION public.plg_store_connection_secret(uuid, text, text) IS
+  'Place or replace one credential for a connection. Vault name is derived from '
+  'the connection id and key, so a refresh replaces rather than accumulates. '
+  'service_role only.';
+COMMENT ON FUNCTION public.plg_read_connection_secret(uuid, text) IS
+  'The only decrypt path. Called by the data plane at run time. service_role only.';
+COMMENT ON FUNCTION public.plg_drop_connection_secrets(uuid) IS
+  'Disconnect: removes the pointers AND the vault entries behind them. '
+  'service_role only.';