@everystack/cli 0.2.37 → 0.3.0

package/src/cli/authz-owner-probe.ts

@@ -0,0 +1,200 @@
+/**
+ * The owner-aware red-team — proving RLS actually isolates one user from another.
+ *
+ * `authz-redteam.ts` probes (role × table × command): it `SET ROLE`s and asks "does the
+ * role hold the privilege?", treating an RLS-filtered row as "privilege present" — it is
+ * deliberately identity-blind. That leaves the highest-value class unverified: can user A
+ * read or mutate user B's row? RLS owner policies turn on the JWT identity
+ * (`request.jwt.claims ->> 'sub'`), not the role, so two `authenticated` users look
+ * identical to the grant probe. This module fills that gap.
+ *
+ * For each owner-scoped table it DISCOVERS two distinct owner values from the live data
+ * (as the privileged connection, before assuming a role), then assumes role `authenticated`
+ * and sets `request.jwt.claims` to the first identity and checks three things:
+ *   - read-own   — the owner's own rows ARE visible (the anti-vacuous twin: a deny that
+ *                  also hides the owner's rows is a policy bug, not a pass).
+ *   - read-other — the other identity's rows are NOT visible (an IDOR read leak).
+ *   - write-other— an UPDATE touching the other identity's rows affects ZERO rows (an IDOR
+ *                  write leak). Rolled back by the runner; nothing persists.
+ * A table with fewer than two distinct owners records `unprobed` (can't test isolation with
+ * one identity) — surfaced, never a false pass. Discovery casts the owner to text, so the
+ * same probe works for a uuid, bigint, or text owner column.
+ *
+ * The builder and evaluator are pure; the SQL runs through the `db:authz:probe` action, which
+ * executes it in a transaction it always rolls back.
+ */
+
+/** One owner-scoped table to probe. Identity values are discovered from the data at run time. */
+export interface OwnerProbe {
+  /** Schema-qualified table, e.g. `public.notes`. */
+  table: string;
+  /** The SQL column holding the owner id (e.g. `author_id`). */
+  ownerColumn: string;
+  /** JWT claim carrying the owner id. Default `sub`. */
+  claim?: string;
+  /** App role to assume. Default `authenticated`. */
+  role?: string;
+}
+
+export type OwnerCheck = 'discover' | 'read-own' | 'read-other' | 'write-other';
+/** `visible`/`hidden` = rows seen-or-affected / none; `error` = the attempt raised; `unprobed` = <2 owners. */
+export type OwnerOutcome = 'visible' | 'hidden' | 'error' | 'unprobed';
+
+export interface OwnerProbeResult {
+  table: string;
+  check: OwnerCheck;
+  outcome: OwnerOutcome;
+  /** Rows seen (read) / affected (write); for `discover`, the number of distinct owners found. */
+  rows: number;
+}
+
+export interface OwnerFinding {
+  severity: 'read-leak' | 'write-leak' | 'vacuous' | 'unprobed';
+  table: string;
+  detail: string;
+}
+
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** A SQL single-quoted literal, doubling embedded quotes. */
+function sqlLiteral(value: string): string {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+
+/**
+ * Build the server-side owner probe. Returns SQL that populates
+ * `_authz_owner_probe(tbl, check, outcome, rows)` for every probe, then a trailing SELECT.
+ * The caller (the `db:authz:probe` action) runs both in one transaction it always rolls back.
+ * Schema/table/column identifiers are split and `%I`-quoted in PL/pgSQL; discovered identity
+ * values live in PL/pgSQL variables (never concatenated into SQL), so there is no injection
+ * surface from the data. Only the column/claim/role idents are inlined, and they are validated.
+ */
+export function buildOwnerProbeSql(probes: OwnerProbe[]): string {
+  const blocks = probes.map((p) => {
+    const role = p.role ?? 'authenticated';
+    const claim = p.claim ?? 'sub';
+    if (!IDENT.test(role)) throw new Error(`Invalid role: ${JSON.stringify(role)}`);
+    if (!IDENT.test(p.ownerColumn)) throw new Error(`Invalid owner column: ${JSON.stringify(p.ownerColumn)}`);
+    if (!IDENT.test(claim)) throw new Error(`Invalid claim: ${JSON.stringify(claim)}`);
+
+    const tbl = sqlLiteral(p.table);
+    const col = sqlLiteral(p.ownerColumn);
+    const roleLit = sqlLiteral(role);
+    const claimLit = sqlLiteral(claim);
+
+    return `
+  -- ${p.table} (owner ${p.ownerColumn})
+  v_schema := split_part(${tbl}, '.', 1);
+  v_table  := split_part(${tbl}, '.', 2);
+  v_write_err := false;
+  EXECUTE format(
+    'SELECT array_agg(v) FROM (SELECT DISTINCT %I::text AS v FROM %I.%I WHERE %I IS NOT NULL ORDER BY v LIMIT 2) s',
+    ${col}, v_schema, v_table, ${col}
+  ) INTO v_owners;
+
+  IF v_owners IS NULL OR array_length(v_owners, 1) < 2 THEN
+    INSERT INTO _authz_owner_probe VALUES (${tbl}, 'discover', 'unprobed', COALESCE(array_length(v_owners, 1), 0));
+  ELSE
+    v_owner := v_owners[1];
+    v_intruder := v_owners[2];
+
+    EXECUTE format('SET LOCAL ROLE %I', ${roleLit});
+    PERFORM set_config('request.jwt.claims', jsonb_build_object(${claimLit}, v_owner, 'role', ${roleLit})::text, true);
+
+    EXECUTE format('SELECT count(*) FROM %I.%I WHERE %I = %L', v_schema, v_table, ${col}, v_owner) INTO v_own;
+    EXECUTE format('SELECT count(*) FROM %I.%I WHERE %I = %L', v_schema, v_table, ${col}, v_intruder) INTO v_other;
+    BEGIN
+      EXECUTE format('UPDATE %I.%I SET %I = %I WHERE %I = %L', v_schema, v_table, ${col}, ${col}, ${col}, v_intruder);
+      GET DIAGNOSTICS v_write = ROW_COUNT;
+    EXCEPTION WHEN OTHERS THEN
+      v_write := 0; v_write_err := true;
+    END;
+
+    RESET ROLE;
+    PERFORM set_config('request.jwt.claims', '', true);
+
+    INSERT INTO _authz_owner_probe VALUES
+      (${tbl}, 'read-own',    CASE WHEN v_own   > 0 THEN 'visible' ELSE 'hidden' END, v_own),
+      (${tbl}, 'read-other',  CASE WHEN v_other > 0 THEN 'visible' ELSE 'hidden' END, v_other),
+      (${tbl}, 'write-other', CASE WHEN v_write_err THEN 'error' WHEN v_write > 0 THEN 'visible' ELSE 'hidden' END, v_write);
+  END IF;`;
+  });
+
+  return `
+DROP TABLE IF EXISTS _authz_owner_probe;
+CREATE TEMP TABLE _authz_owner_probe(tbl text, "check" text, outcome text, rows int) ON COMMIT DROP;
+DO $owner$
+DECLARE
+  v_schema    text;
+  v_table     text;
+  v_owners    text[];
+  v_owner     text;
+  v_intruder  text;
+  v_own       bigint;
+  v_other     bigint;
+  v_write     bigint;
+  v_write_err boolean;
+BEGIN
+${blocks.join('\n')}
+END
+$owner$;
+`.trim();
+}
+
+/** Read the probe outcomes (same transaction as buildOwnerProbeSql; the runner rolls back). */
+export const OWNER_PROBE_SELECT_SQL =
+  'SELECT tbl AS table, "check", outcome, rows FROM _authz_owner_probe ORDER BY tbl, "check"';
+
+/** Map a probe-result row to a typed OwnerProbeResult. */
+export function toOwnerProbeResult(row: any): OwnerProbeResult {
+  return {
+    table: String(row.table),
+    check: String(row.check) as OwnerCheck,
+    outcome: String(row.outcome) as OwnerOutcome,
+    rows: Number(row.rows ?? 0),
+  };
+}
+
+/**
+ * Turn probe outcomes into findings. Each is a behavioural authorization failure:
+ *   - read-leak  — as the owner, the other identity's rows were visible (read-other = visible).
+ *   - write-leak — as the owner, an UPDATE touched the other identity's rows (write-other visible).
+ *   - vacuous    — the owner could NOT see their own rows (read-own = hidden): the policy denies
+ *                  the owner too, so the read-other deny proves nothing — the faithfulness guard.
+ *   - unprobed   — fewer than two distinct owners in the table; isolation can't be tested (a
+ *                  warning, not a verdict — seed a second owner's row, or accept the gap).
+ * A correctly-isolated table with two owners produces zero findings.
+ */
+export function evaluateOwnerProbe(results: OwnerProbeResult[]): OwnerFinding[] {
+  const findings: OwnerFinding[] = [];
+  const byTable = new Map<string, Map<OwnerCheck, OwnerProbeResult>>();
+  for (const r of results) {
+    (byTable.get(r.table) ?? byTable.set(r.table, new Map()).get(r.table)!).set(r.check, r);
+  }
+
+  for (const [table, checks] of byTable) {
+    if (checks.get('discover')?.outcome === 'unprobed') {
+      findings.push({ severity: 'unprobed', table,
+        detail: `fewer than two distinct owners in ${table} — cannot test reader/writer isolation; seed a second owner's row to cover it` });
+      continue;
+    }
+    const own = checks.get('read-own');
+    const other = checks.get('read-other');
+    const write = checks.get('write-other');
+
+    if (own && own.outcome !== 'visible') {
+      findings.push({ severity: 'vacuous', table,
+        detail: `owner could not see their own rows in ${table} — the policy denies the owner too, or the probe identity is wrong; the isolation checks prove nothing until this is fixed` });
+      continue; // the other checks are meaningless while the owner can't see own rows
+    }
+    if (other && other.outcome === 'visible') {
+      findings.push({ severity: 'read-leak', table,
+        detail: `as the owner, ${other.rows} of another user's row(s) in ${table} were visible — RLS does not isolate readers (IDOR read)` });
+    }
+    if (write && write.outcome === 'visible') {
+      findings.push({ severity: 'write-leak', table,
+        detail: `as the owner, an UPDATE affected ${write.rows} of another user's row(s) in ${table} — RLS does not isolate writers (IDOR write)` });
+    }
+  }
+  return findings;
+}

package/src/cli/authz-reconcile.ts

@@ -0,0 +1,127 @@
+/**
+ * Reconcile — the authz diff turned back into SQL (the "correct" to the contract
+ * suite's "validate"). `diffContracts` detects drift as prose findings;
+ * `emitReconcileSql` emits the idempotent DDL that makes the live database match
+ * the declared contract.
+ *
+ * It works off the structured contracts, not DriftFinding (whose `detail` is
+ * prose — "USING changed" can't be turned into SQL). Declared is the target
+ * (compiled from the Model); live is the current database; the output transforms
+ * live -> declared.
+ *
+ * Authz-only by construction: it emits CREATE/DROP POLICY, GRANT/REVOKE, and
+ * ALTER TABLE ... ROW LEVEL SECURITY — never anything that touches table data. A
+ * policy/grant change loses no rows and is idempotently replaceable, which is why
+ * this layer reconciles without a migration file (unlike the data layer).
+ */
+
+import type { AuthzContract, TableContract, PolicyContract } from './authz-contract.js';
+import { quoteQualified } from './pg-ident.js';
+
+/** True when `s`'s outer parens already wrap the whole expression (redundant to add more). */
+function isWrapped(s: string): boolean {
+  if (!s.startsWith('(') || !s.endsWith(')')) return false;
+  let depth = 0;
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === '(') depth++;
+    else if (s[i] === ')') {
+      depth--;
+      if (depth === 0 && i < s.length - 1) return false;
+    }
+  }
+  return depth === 0;
+}
+
+/** A USING/WITH CHECK clause expression, parenthesized exactly once. */
+function clause(expr: string): string {
+  return isWrapped(expr) ? expr : `(${expr})`;
+}
+
+/** A CREATE POLICY statement from a policy descriptor. */
+function policyCreateSql(table: string, p: PolicyContract): string {
+  const parts = [`CREATE POLICY ${p.name} ON ${table}`];
+  if (!p.permissive) parts.push('AS RESTRICTIVE');
+  parts.push(`FOR ${p.command}`);
+  parts.push(`TO ${p.roles.join(', ')}`);
+  if (p.using != null) parts.push(`USING ${clause(p.using)}`);
+  if (p.check != null) parts.push(`WITH CHECK ${clause(p.check)}`);
+  return `${parts.join(' ')};`;
+}
+
+function policyDropSql(table: string, name: string): string {
+  return `DROP POLICY IF EXISTS ${name} ON ${table};`;
+}
+
+/** Two policies are the same authorization when every diffed field matches. */
+function policiesEqual(a: PolicyContract, b: PolicyContract): boolean {
+  return a.command === b.command
+    && a.permissive === b.permissive
+    && a.roles.join(',') === b.roles.join(',')
+    && (a.using ?? '') === (b.using ?? '')
+    && (a.check ?? '') === (b.check ?? '');
+}
+
+function tableMap(c: AuthzContract): Map<string, TableContract> {
+  return new Map(c.tables.map((t) => [t.table, t]));
+}
+
+/**
+ * Emit the ordered SQL that transforms the live database into the declared
+ * contract. Empty when they already match (the reconcile no-op). Order per table:
+ * enable RLS, drop removed/changed policies, create added/changed policies, then
+ * revoke/grant — so a replaced policy never briefly co-exists with its old form
+ * and policies exist before grants reference the table.
+ */
+export function emitReconcileSql(declared: AuthzContract, live: AuthzContract): string[] {
+  const sql: string[] = [];
+  const lTables = tableMap(live);
+
+  for (const d of declared.tables) {
+    const l = lTables.get(d.table);
+    // The contract keys on the bare `<schema>.<table>` (so the diff matches both producers);
+    // the EMITTED SQL must quote it, or a reserved table name (`public.user`) is a syntax error.
+    const table = quoteQualified(d.table);
+    reconcileRls(table, d, l, sql);
+    reconcilePolicies(table, d, l, sql);
+    reconcileGrants(table, d, l, sql);
+  }
+
+  return sql;
+}
+
+function reconcileRls(table: string, d: TableContract, l: TableContract | undefined, out: string[]): void {
+  if (d.rls.enabled && !l?.rls.enabled) out.push(`ALTER TABLE ${table} ENABLE ROW LEVEL SECURITY;`);
+  if (d.rls.forced && !l?.rls.forced) out.push(`ALTER TABLE ${table} FORCE ROW LEVEL SECURITY;`);
+  if (!d.rls.enabled && l?.rls.enabled) out.push(`ALTER TABLE ${table} DISABLE ROW LEVEL SECURITY;`);
+  if (!d.rls.forced && l?.rls.forced) out.push(`ALTER TABLE ${table} NO FORCE ROW LEVEL SECURITY;`);
+}
+
+function reconcilePolicies(table: string, d: TableContract, l: TableContract | undefined, out: string[]): void {
+  const dMap = new Map(d.policies.map((p) => [p.name, p]));
+  const lMap = new Map((l?.policies ?? []).map((p) => [p.name, p]));
+
+  // Drops first: policies removed, or changed (dropped then recreated below).
+  for (const [name, lp] of lMap) {
+    const dp = dMap.get(name);
+    if (!dp || !policiesEqual(dp, lp)) out.push(policyDropSql(table, name));
+  }
+  // Creates: policies added, or changed (recreated to the declared form).
+  for (const [name, dp] of dMap) {
+    const lp = lMap.get(name);
+    if (!lp || !policiesEqual(dp, lp)) out.push(policyCreateSql(table, dp));
+  }
+}
+
+function reconcileGrants(table: string, d: TableContract, l: TableContract | undefined, out: string[]): void {
+  const grantees = new Set([...Object.keys(d.grants), ...Object.keys(l?.grants ?? {})]);
+  for (const grantee of [...grantees].sort()) {
+    const declared = new Set(d.grants[grantee] ?? []);
+    const live = new Set(l?.grants?.[grantee] ?? []);
+    const target = grantee.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : grantee;
+
+    const toRevoke = [...live].filter((p) => !declared.has(p)).sort();
+    const toGrant = [...declared].filter((p) => !live.has(p)).sort();
+    if (toRevoke.length) out.push(`REVOKE ${toRevoke.join(', ')} ON ${table} FROM ${target};`);
+    if (toGrant.length) out.push(`GRANT ${toGrant.join(', ')} ON ${table} TO ${target};`);
+  }
+}

package/src/cli/authz-redteam.ts

@@ -0,0 +1,251 @@
+/**
+ * The Authorization Contract red-team — proving *enforcement*, not just declaration.
+ *
+ * db:authz:diff proves the live ACL matches the committed contract (static text). This
+ * proves the database actually *behaves* that way: for each (role, table, command) it
+ * SET ROLEs into the app role and attempts the operation, then asks "was it allowed?".
+ * That catches enforcement holes static inspection cannot — privilege escalation via
+ * role inheritance, a BYPASSRLS attribute, or a `USING(true)` policy quietly defeating
+ * intent. The worst finding is a role that can do *more* than the contract declares.
+ *
+ * Execution model (built into the `db:authz:probe` ops action): one server-side DO
+ * block loops every (role, table, command); each probe runs inside its own savepoint
+ * (SET LOCAL ROLE -> attempt -> classify SQLSTATE -> rollback to savepoint -> RESET
+ * ROLE) and writes its outcome to a temp table the surrounding transaction then
+ * discards. Nothing persists; one round trip. The builder and evaluator here are pure.
+ */
+
+import type { AuthzContract, TableContract } from './authz-contract.js';
+
+export type ProbeCommand = 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE';
+export const PROBE_COMMANDS: ProbeCommand[] = ['SELECT', 'INSERT', 'UPDATE', 'DELETE'];
+
+/** SELECT/INSERT/UPDATE/DELETE map to the privilege a grant must carry to allow them. */
+const COMMAND_PRIVILEGE: Record<ProbeCommand, string> = {
+  SELECT: 'SELECT', INSERT: 'INSERT', UPDATE: 'UPDATE', DELETE: 'DELETE',
+};
+
+export type ProbeOutcome =
+  | 'allowed'           // the privilege is present (RLS may still filter rows)
+  | 'denied-privilege'  // no grant: "permission denied for table"
+  | 'denied-rls'        // grant present, RLS blocked the row: privilege IS present
+  | 'no-impersonate';   // the probing role could not SET ROLE into this role
+
+export interface ProbeResult {
+  role: string;
+  table: string;        // schema-qualified
+  command: ProbeCommand;
+  outcome: ProbeOutcome;
+}
+
+export interface RedTeamFinding {
+  severity: 'hole' | 'broken' | 'unprobed';
+  role: string;
+  table: string;
+  command: ProbeCommand;
+  detail: string;
+}
+
+/**
+ * Does a role hold a privilege on a table — by table grant, by a column-scoped grant
+ * (for SELECT/INSERT/UPDATE), or via a PUBLIC grant (which applies to every role)? The
+ * privilege-isolated probe (`SELECT 1`, `UPDATE ... WHERE false`) needs the privilege on
+ * *any* column, so a column grant confers it — matching what the database enforces, and
+ * the reason a table-grant-only check produced false "holes" on `auth.users`.
+ */
+export function hasPrivilege(table: TableContract, role: string, privilege: string): boolean {
+  const tableGrant = (g: string) => (table.grants[g] ?? []).includes(privilege);
+  const columnGrant = (g: string) => (table.columnGrants?.[g]?.[privilege]?.length ?? 0) > 0;
+  return tableGrant(role) || columnGrant(role) || tableGrant('PUBLIC') || columnGrant('PUBLIC');
+}
+
+/** Roles to probe: every grantee named in the contract (minus PUBLIC) plus anon — so a
+ *  role that should have NO access is still actively tested for default-deny. */
+export function probeRoles(contract: AuthzContract): string[] {
+  const roles = new Set<string>(['anon']);
+  const add = (g: string) => { if (g.toUpperCase() !== 'PUBLIC') roles.add(g); };
+  for (const t of contract.tables) {
+    Object.keys(t.grants).forEach(add);
+    Object.keys(t.columnGrants ?? {}).forEach(add);
+  }
+  return [...roles].sort();
+}
+
+/** A Postgres string-array literal: `ARRAY['a','b']` with each element escaped. */
+function pgArrayLiteral(values: string[]): string {
+  const escaped = values.map((v) => `'${v.replace(/'/g, "''")}'`);
+  return `ARRAY[${escaped.join(', ')}]::text[]`;
+}
+
+/**
+ * Build the server-side probe. Returns SQL that populates `_authz_probe(role, tbl,
+ * command, outcome)` and a trailing SELECT of it. The caller runs both inside one
+ * transaction it always rolls back. Probe statements are privilege-isolated:
+ *   SELECT 1 FROM t WHERE false      — SELECT privilege, reads no rows
+ *   INSERT INTO t DEFAULT VALUES     — INSERT privilege (rolled back; NOT NULL = allowed)
+ *   UPDATE t SET col = col WHERE false — UPDATE privilege, touches no rows
+ *   DELETE FROM t WHERE false        — DELETE privilege, touches no rows
+ * "permission denied" -> denied-privilege; "row-level security" -> denied-rls; any
+ * other error (constraint, etc.) means the privilege passed -> allowed.
+ */
+export function buildProbeSql(roles: string[], tables: string[]): string {
+  return `
+DROP TABLE IF EXISTS _authz_probe;
+CREATE TEMP TABLE _authz_probe(role text, tbl text, command text, outcome text) ON COMMIT DROP;
+DO $probe$
+DECLARE
+  v_role text;
+  v_tbl  text;
+  v_cmd  text;
+  v_col  text;
+  v_stmt text;
+  v_outcome text;
+BEGIN
+  FOREACH v_role IN ARRAY ${pgArrayLiteral(roles)} LOOP
+    FOREACH v_tbl IN ARRAY ${pgArrayLiteral(tables)} LOOP
+      FOREACH v_cmd IN ARRAY ${pgArrayLiteral(PROBE_COMMANDS)} LOOP
+        v_stmt := CASE v_cmd
+          WHEN 'SELECT' THEN format('SELECT 1 FROM %I.%I WHERE false', split_part(v_tbl,'.',1), split_part(v_tbl,'.',2))
+          WHEN 'INSERT' THEN format('INSERT INTO %I.%I DEFAULT VALUES', split_part(v_tbl,'.',1), split_part(v_tbl,'.',2))
+          WHEN 'DELETE' THEN format('DELETE FROM %I.%I WHERE false', split_part(v_tbl,'.',1), split_part(v_tbl,'.',2))
+          WHEN 'UPDATE' THEN NULL
+        END;
+        IF v_cmd = 'UPDATE' THEN
+          SELECT quote_ident(attname) INTO v_col FROM pg_attribute
+            WHERE attrelid = format('%I.%I', split_part(v_tbl,'.',1), split_part(v_tbl,'.',2))::regclass
+              AND attnum > 0 AND NOT attisdropped ORDER BY attnum LIMIT 1;
+          v_stmt := format('UPDATE %I.%I SET %s = %s WHERE false', split_part(v_tbl,'.',1), split_part(v_tbl,'.',2), v_col, v_col);
+        END IF;
+
+        BEGIN
+          EXECUTE format('SET LOCAL ROLE %I', v_role);
+          BEGIN
+            EXECUTE v_stmt;
+            v_outcome := 'allowed';
+          EXCEPTION
+            WHEN insufficient_privilege THEN
+              v_outcome := CASE WHEN SQLERRM ILIKE '%row-level security%' THEN 'denied-rls' ELSE 'denied-privilege' END;
+            WHEN OTHERS THEN
+              v_outcome := 'allowed';  -- privilege passed; failed on data/constraint
+          END;
+          RESET ROLE;
+        EXCEPTION WHEN insufficient_privilege THEN
+          v_outcome := 'no-impersonate';  -- the SET ROLE itself was refused
+          RESET ROLE;
+        END;
+
+        INSERT INTO _authz_probe VALUES (v_role, v_tbl, v_cmd, v_outcome);
+      END LOOP;
+    END LOOP;
+  END LOOP;
+END
+$probe$;
+`.trim();
+}
+
+/**
+ * Read the probe outcomes. Runs in the same transaction as `buildProbeSql` (the temp
+ * table is `ON COMMIT DROP`), which the caller always rolls back so nothing persists.
+ */
+export const PROBE_SELECT_SQL =
+  'SELECT role, tbl AS table, command, outcome FROM _authz_probe ORDER BY tbl, role, command';
+
+// ---------------------------------------------------------------------------
+// Grant-completeness — the SECDEF-helper EXECUTE gap.
+// ---------------------------------------------------------------------------
+
+/**
+ * Find SECURITY DEFINER functions whose owner cannot EXECUTE a helper their body calls.
+ *
+ * A SECDEF function runs as its owner; calling a helper needs the owner to hold EXECUTE
+ * on it. While every function is superuser-owned (db:migrate's default) the owner can
+ * execute everything, so the gaps are invisible — local tests pass. Normalize ownership
+ * to a non-superuser operator and the same call fails in production with 42501. This
+ * query surfaces those gaps from the catalog so they never reach prod unnoticed.
+ *
+ * Helper references are extracted from the function body by regex (schema-qualified
+ * `schema.fn(` calls); the join to pg_proc keeps only real functions, and
+ * has_function_privilege resolves ownership/PUBLIC/inheritance. Read-only — runs through
+ * the db:query action. A normalized, least-privilege database returns zero rows.
+ */
+export const GRANT_COMPLETENESS_SQL = `
+WITH secdef AS (
+  SELECT p.oid, p.proowner, n.nspname || '.' || p.proname AS name, p.prosrc
+  FROM pg_proc p
+  JOIN pg_namespace n ON n.oid = p.pronamespace
+  WHERE p.prosecdef
+    AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+    AND n.nspname NOT LIKE 'pg_%'
+    AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.objid = p.oid AND d.deptype = 'e')
+)
+SELECT DISTINCT s.name AS secdef, ref.helper AS helper
+FROM secdef s
+CROSS JOIN LATERAL (
+  SELECT DISTINCT lower(m[1]) AS helper
+  FROM regexp_matches(s.prosrc, '([a-zA-Z_][a-zA-Z0-9_]*\\.[a-zA-Z_][a-zA-Z0-9_]*)\\s*\\(', 'g') AS m
+) ref
+JOIN pg_proc hp ON true
+JOIN pg_namespace hn ON hn.oid = hp.pronamespace
+WHERE lower(hn.nspname || '.' || hp.proname) = ref.helper
+  AND hp.oid <> s.oid
+  AND hn.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND NOT has_function_privilege(s.proowner, hp.oid, 'EXECUTE')
+ORDER BY secdef, helper;
+`.trim();
+
+export interface GrantGap {
+  /** The SECDEF function whose owner is missing a grant. */
+  secdef: string;
+  /** The helper it calls but its owner cannot EXECUTE. */
+  helper: string;
+}
+
+export function toGrantGap(row: any): GrantGap {
+  return { secdef: String(row.secdef), helper: String(row.helper) };
+}
+
+/** Map a probe result row (from the SELECT) into a typed ProbeResult. */
+export function toProbeResult(row: any): ProbeResult {
+  return {
+    role: String(row.role),
+    table: String(row.table),
+    command: String(row.command).toUpperCase() as ProbeCommand,
+    outcome: String(row.outcome) as ProbeOutcome,
+  };
+}
+
+/**
+ * Compare the live probe matrix against the contract's grants. A finding is a
+ * *disagreement* between declared authority and enforced behaviour:
+ *   - `hole`   — the role was ALLOWED something the contract does not grant. The
+ *                dangerous one: enforced access exceeds the declaration.
+ *   - `broken` — the contract grants it but the role was DENIED by privilege. The
+ *                declaration is a dead letter; the feature is silently off.
+ *   - `unprobed` — the probing connection could not SET ROLE into the role (a warning,
+ *                not a verdict — grant the probe role membership to cover it).
+ * denied-rls counts as the privilege being present (RLS filtering rows is the policy's
+ * job, exercised behaviourally by the RPC layer, not a grant-level finding).
+ */
+export function evaluateRedTeam(contract: AuthzContract, results: ProbeResult[]): RedTeamFinding[] {
+  const tablesByName = new Map(contract.tables.map((t) => [t.table, t]));
+  const findings: RedTeamFinding[] = [];
+
+  for (const r of results) {
+    const table = tablesByName.get(r.table);
+    if (!table) continue; // a table not in the contract (e.g. ignored schema)
+    const granted = hasPrivilege(table, r.role, COMMAND_PRIVILEGE[r.command]);
+    const allowed = r.outcome === 'allowed' || r.outcome === 'denied-rls';
+
+    if (r.outcome === 'no-impersonate') {
+      findings.push({ severity: 'unprobed', role: r.role, table: r.table, command: r.command,
+        detail: `could not SET ROLE into ${r.role} — grant the probe connection membership to cover it` });
+    } else if (allowed && !granted) {
+      findings.push({ severity: 'hole', role: r.role, table: r.table, command: r.command,
+        detail: `${r.role} can ${r.command} ${r.table} but the contract grants no such privilege (enforcement exceeds declaration)` });
+    } else if (!allowed && granted) {
+      findings.push({ severity: 'broken', role: r.role, table: r.table, command: r.command,
+        detail: `contract grants ${r.role} ${r.command} on ${r.table} but the database denied it (declared but not enforced)` });
+    }
+  }
+  return findings;
+}