@everystack/cli 0.2.39 → 0.2.40

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;
+}

package/src/cli/authz-render.ts

@@ -0,0 +1,248 @@
+/**
+ * The human-readable view of the Authorization Contract.
+ *
+ * The JSON contract is machine-grade — correct for diff/test/probe, but a CTO cannot
+ * scan `(author_id = (((current_setting('request.jwt.claims'::text, true))::jsonb ->>
+ * 'sub'::text))::uuid)` and confirm it means "owns the row". This renders the same
+ * contract as a role x action matrix with the predicates translated to plain English,
+ * so a human can read it and confirm or deny the rules match intent.
+ *
+ * `humanizePredicate` recognises the handful of shapes that make up ~all real policies
+ * (owner check, soft-delete guard, boolean, simple comparisons) — the same
+ * classification the v3 reverse-compiler (db:pull -> can()) needs, so it is not
+ * throwaway. Anything it does not recognise is shown verbatim, never hidden.
+ */
+
+import type { AuthzContract, TableContract, PolicyContract } from './authz-contract.js';
+import { hasPrivilege } from './authz-redteam.js';
+
+/** True when the expression resolves to the signed-in user's id (any of the forms). */
+function isCurrentUserExpr(s: string): boolean {
+  return /current_setting\([^)]*jwt\.claims/i.test(s)
+    || /auth\.uid\(\)/i.test(s)
+    || /auth\.jwt\(\)\s*->>\s*'sub'/i.test(s);
+}
+
+/** Strip one layer of redundant outer parentheses, repeatedly. */
+function unwrap(s: string): string {
+  let t = s.trim();
+  while (t.startsWith('(') && t.endsWith(')') && balanced(t.slice(1, -1))) {
+    t = t.slice(1, -1).trim();
+  }
+  return t;
+}
+
+/** True when every '(' in s closes before the end — i.e. the outer parens were redundant. */
+function balanced(s: string): boolean {
+  let depth = 0;
+  for (const ch of s) {
+    if (ch === '(') depth++;
+    else if (ch === ')') { if (--depth < 0) return false; }
+  }
+  return depth === 0;
+}
+
+/** Split on a top-level keyword (OR / AND), respecting parentheses. */
+function splitTop(s: string, keyword: 'OR' | 'AND'): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let last = 0;
+  const re = new RegExp(`\\b${keyword}\\b`, 'gi');
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === '(') depth++;
+    else if (s[i] === ')') depth--;
+    else if (depth === 0) {
+      re.lastIndex = i;
+      const m = re.exec(s);
+      if (m && m.index === i) {
+        parts.push(s.slice(last, i));
+        i += m[0].length - 1;
+        last = i + 1;
+      }
+    }
+  }
+  parts.push(s.slice(last));
+  return parts.map((p) => p.trim()).filter(Boolean);
+}
+
+/** One comparison/atom -> a phrase. Falls back to the raw SQL in backticks. */
+function ownerOf(col: string): string {
+  return `owner (\`${col.replace(/"/g, '')}\`)`;
+}
+
+function humanizeAtom(atom: string): string {
+  const a = unwrap(atom);
+  if (/^true$/i.test(a)) return 'any row';
+  if (/^false$/i.test(a)) return 'no row';
+
+  // <col> IN ( SELECT ... FROM <parent> WHERE ... <current user> ... ) — parent-visibility
+  // inheritance: you may touch this row when you own the parent it links to.
+  let m = a.match(/^([\w".]+)\s+IN\s*\(\s*SELECT[\s\S]*?\bFROM\s+([\w".]+)/i);
+  if (m && isCurrentUserExpr(a)) {
+    return `owner of linked \`${m[2].replace(/"/g, '')}\` (via \`${m[1].replace(/"/g, '')}\`)`;
+  }
+
+  // <col> = <current-user-id-expr>  (in either order) -> ownership. Anchored on the
+  // column and the start of the identity expression, so the trailing cast/paren noise
+  // (`::uuid`, `))`) never matters.
+  if (isCurrentUserExpr(a)) {
+    m = a.match(/^\(*\s*([\w".]+)\s*=\s*\(*\s*(?:current_setting|auth\.)/i);
+    if (m) return ownerOf(m[1]);
+    m = a.match(/=\s*([\w".]+)\s*\)*$/);
+    if (m) return ownerOf(m[1]);
+    // A subquery / EXISTS keyed on the current user that we can't reduce cleanly — be
+    // honest that it depends on the user via related data, and point at the JSON.
+    if (/\bselect\b|\bexists\b/i.test(a)) return 'depends on the signed-in user (via a subquery — see JSON)';
+    return 'the current user';
+  }
+
+  // a bare boolean column used as a predicate (e.g. `active`) means "<col> is true"
+  if (/^[\w".]+$/.test(a)) return `\`${a.replace(/"/g, '')}\` is true`;
+
+  // soft-delete / null guards
+  m = a.match(/^([\w".]+)\s+IS\s+NULL$/i);
+  if (m) return /delet/i.test(m[1]) ? 'not deleted' : `\`${m[1].replace(/"/g, '')}\` is empty`;
+  m = a.match(/^([\w".]+)\s+IS\s+NOT\s+NULL$/i);
+  if (m) return `\`${m[1].replace(/"/g, '')}\` is set`;
+
+  // simple equality / membership against a literal
+  m = a.match(/^([\w".]+)\s*=\s*('[^']*'|\w+)$/i);
+  if (m) return `\`${m[1].replace(/"/g, '')}\` = ${m[2]}`;
+  m = a.match(/^([\w".]+)\s+IN\s+(\(.+\))$/i);
+  if (m) return `\`${m[1].replace(/"/g, '')}\` in ${m[2]}`;
+
+  return `\`${a}\``;
+}
+
+/**
+ * Translate an RLS predicate to a plain-English phrase. null/empty -> "any row".
+ * Handles OR / AND combinations of the recognised atoms; unknown atoms are shown raw.
+ */
+export function humanizePredicate(sql: string | null): string {
+  if (!sql || !sql.trim()) return 'any row';
+  const expr = unwrap(sql);
+
+  const ors = splitTop(expr, 'OR');
+  if (ors.length > 1) return ors.map(renderConj).join(' OR ');
+  return renderConj(expr);
+}
+
+function renderConj(s: string): string {
+  const ands = splitTop(s, 'AND');
+  if (ands.length > 1) return ands.map(humanizeAtom).join(' AND ');
+  return humanizeAtom(s);
+}
+
+// ---------------------------------------------------------------------------
+// The matrix renderer.
+// ---------------------------------------------------------------------------
+
+const ACTIONS: { label: string; command: string; clause: 'using' | 'check' }[] = [
+  { label: 'Read', command: 'SELECT', clause: 'using' },
+  { label: 'Create', command: 'INSERT', clause: 'check' },
+  { label: 'Update', command: 'UPDATE', clause: 'using' },
+  { label: 'Delete', command: 'DELETE', clause: 'using' },
+];
+const COMMAND_PRIVILEGE: Record<string, string> = { SELECT: 'SELECT', INSERT: 'INSERT', UPDATE: 'UPDATE', DELETE: 'DELETE' };
+
+/** Roles to show as rows: the table's grantees (and column-grantees), minus PUBLIC. */
+function tableRoles(t: TableContract): string[] {
+  const roles = new Set<string>();
+  Object.keys(t.grants).forEach((g) => g.toUpperCase() !== 'PUBLIC' && roles.add(g));
+  Object.keys(t.columnGrants ?? {}).forEach((g) => g.toUpperCase() !== 'PUBLIC' && roles.add(g));
+  return [...roles].sort();
+}
+
+function policiesFor(t: TableContract, role: string, command: string): { permissive: PolicyContract[]; restrictive: PolicyContract[] } {
+  const applies = (p: PolicyContract) =>
+    (p.command === command || p.command === 'ALL') &&
+    (p.roles.includes(role) || p.roles.includes('public'));
+  return {
+    permissive: t.policies.filter((p) => applies(p) && p.permissive),
+    restrictive: t.policies.filter((p) => applies(p) && !p.permissive),
+  };
+}
+
+/** One matrix cell for (table, role, action). */
+export function renderCell(t: TableContract, role: string, action: typeof ACTIONS[number]): string {
+  const priv = COMMAND_PRIVILEGE[action.command];
+  if (!hasPrivilege(t, role, priv)) return '—';
+  if (!t.rls.enabled) return '✓ all';
+
+  const { permissive, restrictive } = policiesFor(t, role, action.command);
+  if (permissive.length === 0) return '⚠ no policy';
+
+  const conds = permissive.map((p) => humanizePredicate(p[action.clause]));
+  let cell = conds.some((c) => c === 'any row') ? '✓ all' : `✓ ${[...new Set(conds)].join(' OR ')}`;
+  if (restrictive.length) {
+    cell += ` (only if ${restrictive.map((p) => humanizePredicate(p[action.clause])).join(' AND ')})`;
+  }
+  // Column-restricted read/write: note the columns when access is column-scoped only.
+  const cols = t.columnGrants?.[role]?.[priv];
+  if (cols?.length && !(t.grants[role] ?? []).includes(priv)) {
+    cell += ` — cols: ${cols.join(', ')}`;
+  }
+  return cell;
+}
+
+/** Render the whole contract as a human-readable Markdown review document. */
+export function renderContractMarkdown(contract: AuthzContract): string {
+  const policyCount = contract.tables.reduce((n, t) => n + t.policies.length, 0);
+  const lines: string[] = [];
+
+  lines.push('# Authorization Review');
+  lines.push('');
+  lines.push('> The human-readable view of `authz/*.contract.json`. Read it to confirm the rules');
+  lines.push('> match intent — the JSON is the machine-checked source, this is generated from it.');
+  lines.push('> Regenerate with `everystack db:authz:report`; never hand-edit.');
+  lines.push('');
+  lines.push(`_${contract.tables.length} tables · ${policyCount} policies · ${contract.functions.length} SECURITY DEFINER functions._`);
+  lines.push('');
+  lines.push('**Legend:**');
+  lines.push('');
+  lines.push('- **✓** — allowed, followed by the condition a row must satisfy');
+  lines.push('- **—** — not granted');
+  lines.push('- **⚠ no policy** — the privilege is granted but no RLS policy matches, so no rows are returned (usually a mistake)');
+  lines.push('- **owner (`col`)** — the row\'s `col` equals the signed-in user');
+  lines.push('- **owner of linked `t` (via `col`)** — you may act when you own the `t` row that `col` points to');
+  lines.push('');
+
+  for (const t of contract.tables) {
+    const posture = t.rls.enabled ? (t.rls.forced ? 'enforced (forced)' : 'enabled (not forced)') : '**OFF — no row security**';
+    lines.push(`## ${t.table}`);
+    lines.push(`RLS: ${posture}`);
+    lines.push('');
+    const roles = tableRoles(t);
+    if (roles.length === 0) {
+      lines.push('_No roles granted any access._');
+      lines.push('');
+      continue;
+    }
+    lines.push(`| Role | ${ACTIONS.map((a) => a.label).join(' | ')} |`);
+    lines.push(`|---|${ACTIONS.map(() => '---').join('|')}|`);
+    for (const role of roles) {
+      lines.push(`| \`${role}\` | ${ACTIONS.map((a) => renderCell(t, role, a)).join(' | ')} |`);
+    }
+    lines.push('');
+  }
+
+  if (contract.functions.length) {
+    lines.push('## SECURITY DEFINER functions');
+    lines.push('');
+    lines.push('These run with their owner\'s privileges, **above row security** — their own bodies enforce access. Review each one deliberately. A missing `search_path` is a hijack vector; an owner that bypasses RLS (superuser / BYPASSRLS) makes the function run above RLS as that role — the maximum blast radius. `db:migrate` often leaves functions superuser-owned; normalize ownership to a non-superuser operator.');
+    lines.push('');
+    const elevated = contract.functions.filter((f) => f.ownerBypassesRls);
+    if (elevated.length) {
+      lines.push(`> **⚠ ${elevated.length} function(s) are owned by a role that bypasses RLS** — they run above row security regardless of \`search_path\`. Normalize their ownership.`);
+      lines.push('');
+    }
+    for (const f of contract.functions) {
+      const sp = f.hasSearchPath ? 'search_path pinned ✓' : '**search_path NOT pinned ⚠**';
+      const own = f.ownerBypassesRls ? ' · **owner bypasses RLS ⚠**' : '';
+      lines.push(`- \`${f.name}\` — ${sp}${own}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}