@everystack/cli 0.4.36 → 0.4.39

package/bin/everystack.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * The `everystack` entry point.
+ *
+ * This package ships TypeScript source deliberately — every `exports` target is a
+ * `./src/*.ts` file — so the CLI needs a TypeScript loader at runtime. It used to get one
+ * from `#!/usr/bin/env tsx` on `src/cli/index.ts`, which cannot work once the package is
+ * installed: `env` searches the CONSUMER's PATH, and tsx is a dependency of
+ * @everystack/cli, so under pnpm's isolated layout it lives in this package's own
+ * node_modules and is never on that PATH. `everystack --help` died with
+ * "env: tsx: No such file or directory"; only `pnpm exec everystack` worked, because that
+ * puts the local .bin on PATH first.
+ *
+ * So: boot under plain `node` — always present, it is what runs npm — and find tsx by
+ * MODULE RESOLUTION from this file rather than by PATH lookup.
+ *
+ * The loader is installed by re-executing node with `--import`, not by calling tsx's
+ * register() in-process. register() followed by `import()` of the TypeScript entry makes
+ * the entry load through a require(esm) path and Node rejects it with
+ * ERR_REQUIRE_CYCLE_MODULE. `--import` installs the hooks before any module graph exists,
+ * which is the only ordering that works. The extra process is the price of shipping
+ * source, and it is paid once per invocation.
+ */
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+
+let tsx;
+try {
+  tsx = pathToFileURL(require.resolve('tsx')).href;
+} catch {
+  console.error('everystack: could not resolve the "tsx" TypeScript loader from this package.');
+  console.error('This usually means a partial install — try reinstalling @everystack/cli.');
+  process.exit(1);
+}
+
+const entry = fileURLToPath(new URL('../src/cli/index.ts', import.meta.url));
+
+const result = spawnSync(process.execPath, ['--import', tsx, entry, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+});
+
+// Re-raise a signal death as a signal death so `everystack … &` + Ctrl-C behaves, and
+// otherwise pass the child's exit code through unchanged — the CLI's non-zero exits are
+// load-bearing (db:check, db:authz:diff and friends are CI gates).
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+} else {
+  process.exit(result.status ?? 1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.36",
+  "version": "0.4.39",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -17,6 +17,7 @@
     "access": "public"
   },
   "files": [
+    "bin",
     "src",
     "README.md"
   ],
@@ -91,7 +92,7 @@
     }
   },
   "bin": {
-    "everystack": "./src/cli/index.ts"
+    "everystack": "./bin/everystack.mjs"
   },
   "dependencies": {
     "@aws-sdk/client-cloudfront": "3.1053.0",
@@ -108,10 +109,10 @@
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "@everystack/model": "0.4.5"
+    "@everystack/model": "0.4.6"
   },
   "peerDependencies": {
-    "@everystack/server": ">=0.1.0",
+    "@everystack/server": ">=0.4.0",
     "@aws-sdk/client-cloudwatch": "3.1053.0",
     "@aws-sdk/client-rds": "3.1053.0",
     "@aws-sdk/s3-request-presigner": "3.1053.0",

package/src/cli/authz-compile.ts

@@ -210,6 +210,34 @@ function compileColumnGrants(abilities: readonly Ability[]): Record<string, Reco
   return Object.keys(out).length ? out : undefined;
 }
 
+/**
+ * Unwrap a `sql` fragment into predicate text.
+ *
+ * `where` / `sql` / `check` are typed `unknown` because the model package brands its
+ * fragments (`RawSql`) rather than accepting bare strings — a predicate must be written
+ * deliberately, never assembled by accident. Anything else THROWS: these conditions were
+ * declared and documented long before they were compiled, so a model could carry a
+ * `sql:` predicate that silently did nothing. Failing loudly is the fix; a predicate that
+ * evaporates is an authorization hole wearing the costume of a working rule.
+ */
+function rawPredicate(value: unknown, where: string): string | null {
+  if (value == null) return null;
+  const text = (value as { sql?: unknown }).sql;
+  if (typeof text !== 'string' || !text.trim()) {
+    throw new Error(
+      `${where}: expected a sql\`…\` fragment (import { sql } from '@everystack/model'), got ${typeof value}. A bare string is rejected on purpose — an RLS predicate is authored, never stringly assembled.`,
+    );
+  }
+  return `(${text.trim()})`;
+}
+
+/** AND-compose predicates, dropping the vacuous ones. A condition only ever NARROWS. */
+function andPredicates(...parts: (string | null)[]): string | null {
+  const real = parts.filter((p): p is string => Boolean(p) && p !== '(true)' && p !== 'true');
+  if (real.length === 0) return null;
+  return real.length === 1 ? real[0] : `(${real.join(' AND ')})`;
+}
+
 // ---------------------------------------------------------------------------
 // Compile.
 // ---------------------------------------------------------------------------
@@ -238,6 +266,26 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
   // A "row-scoped" condition is either a direct owner or a transitive via.
   const rowScoped = (a: Ability): boolean => Boolean(a.condition.owner || a.condition.via);
 
+  // Author-supplied predicates, per action. `manage` carries no predicate of its own —
+  // it is the admin bypass — so only the specific verbs are consulted.
+  const predFor = (action: Ability['action']): string | null => {
+    for (const a of model.abilities) {
+      if (a.action !== action) continue;
+      const p = rawPredicate(a.condition.sql ?? a.condition.where, `${table}: can('${action}')`);
+      if (p) return p;
+    }
+    return null;
+  };
+  /** The WRITE half, when the author declared one distinct from the read half. */
+  const checkFor = (action: Ability['action']): string | null => {
+    for (const a of model.abilities) {
+      if (a.action !== action) continue;
+      const p = rawPredicate(a.condition.check, `${table}: can('${action}', { check })`);
+      if (p) return p;
+    }
+    return null;
+  };
+
   const abilities = model.abilities;
   const hasAdminManage = abilities.some((a) => a.action === 'manage' && a.condition.role === 'admin');
   const hasPublicRead = abilities.some((a) => a.action === 'read' && !a.condition.role && !rowScoped(a));
@@ -264,7 +312,8 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
   if (hasPublicRead) {
     // public read on a soft-delete table — split per role; authenticated owners
     // also see their own (soft-deleted) rows, hence the OR'd owner check.
-    const anonUsing = sdGuard ?? 'true';
+    const readPred = predFor('read');
+    const anonUsing = andPredicates(sdGuard, readPred) ?? 'true';
     policy(`${t}_select_anon`, 'SELECT', ['anon'], anonUsing, null);
 
     // The owner predicate may only ever WIDEN a public read (the soft-delete OR:
@@ -272,12 +321,14 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
     // condition on a WRITE ability used to narrow the authenticated SELECT to
     // own-rows-only, so anon saw the whole table and a signed-in user lost it.
     // Without a soft-delete guard, `true OR owner` is just `true`.
-    const authedUsing = sdGuard && rowPred ? `(${sdGuard} OR ${rowPred})` : anonUsing;
+    const authedUsing = sdGuard && rowPred
+      ? andPredicates(`(${sdGuard} OR ${rowPred})`, readPred)!
+      : anonUsing;
     policy(`${t}_select_authenticated`, 'SELECT', ['authenticated'], authedUsing, null);
   } else if (hasOwnerRead && rowPred) {
     // owner-scoped read — no anon visibility; you see only the rows you own
     // (directly, or transitively through a `via:` parent).
-    policy(`${t}_select_own`, 'SELECT', ['authenticated'], rowPred, null);
+    policy(`${t}_select_own`, 'SELECT', ['authenticated'], andPredicates(rowPred, predFor('read'))!, null);
   } else if (hasColumnRead && rowPred) {
     // column-scoped self read — `authenticated` reads only its OWN row, and only the
     // granted columns (the GRANT scopes fields; this policy scopes rows). Named
@@ -287,10 +338,23 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
 
   // owner-gated writes. INSERT checks ownership (you can only create rows you own);
   // UPDATE gates + checks; DELETE gates. `rowPred` is the direct-owner or `via:` predicate.
-  if (rowPred) {
-    if (canCreate) policy(`${t}_insert_own`, 'INSERT', ['authenticated'], null, rowPred);
-    if (hasUpdateOwner) policy(`${t}_update_own`, 'UPDATE', ['authenticated'], rowPred, rowPred);
-    if (hasDeleteOwner) policy(`${t}_delete_own`, 'DELETE', ['authenticated'], rowPred, null);
+  //
+  // A declared `check` is the WITH CHECK half; without one the read half governs both
+  // (Postgres' own default). The two differ when a row may be written into a shape its
+  // author could not have selected by — the direction that matters is a check WEAKER than
+  // the using, which lets an owner move their own row past whatever the using guarded.
+  const createPred = andPredicates(rowPred, predFor('create'));
+  const updatePred = andPredicates(rowPred, predFor('update'));
+  const deletePred = andPredicates(rowPred, predFor('delete'));
+
+  if (canCreate && createPred) {
+    policy(`${t}_insert_own`, 'INSERT', ['authenticated'], null, checkFor('create') ?? createPred);
+  }
+  if ((hasUpdateOwner || predFor('update')) && updatePred) {
+    policy(`${t}_update_own`, 'UPDATE', ['authenticated'], updatePred, checkFor('update') ?? updatePred);
+  }
+  if ((hasDeleteOwner || predFor('delete')) && deletePred) {
+    policy(`${t}_delete_own`, 'DELETE', ['authenticated'], deletePred, null);
   }
 
   policies.sort((a, b) => a.name.localeCompare(b.name));

package/src/cli/authz-derive.ts

@@ -0,0 +1,210 @@
+/**
+ * authz-derive — live authorization → declared `can()` abilities. The brownfield on-ramp's
+ * missing half.
+ *
+ * `db:pull` already renders fields, indexes and relations from a live database, but left
+ * authz as commented scaffolding: every adopter hand-transcribed rules that were sitting in
+ * the catalog, which is the single highest-risk manual step in a migration and the one
+ * place a human introduces drift.
+ *
+ * The rule that governs every decision here:
+ *
+ *   **policy presence ≠ effective privilege.**
+ *
+ * Postgres checks the GRANT before it checks the policy. A table can carry a perfectly
+ * good UPDATE policy and still be un-updatable, because no role was ever granted UPDATE —
+ * the policy is dead code. Rendering that policy as `can('update', { owner })` would
+ * compile to a policy PLUS a table-wide `GRANT UPDATE`, manufacturing a privilege the
+ * database does not currently give. On a real schema that path was a moderation bypass:
+ * the live USING carried a state guard the WITH CHECK did not, so handing out the grant
+ * would have let owners publish their own drafts.
+ *
+ * So an ability is emitted only where the grant and the policy AGREE. Everything else
+ * becomes a comment that names what was found and why it was not rendered — the same
+ * honesty the view-skip message already practices. A false ability is worse than a
+ * comment: the comment costs a human five minutes, the ability costs them a privilege.
+ */
+
+import type { TableContract, PolicyContract } from './authz-contract.js';
+
+/** One rendered decision: either an ability line, or a comment explaining the omission. */
+export interface DerivedAbilities {
+  /** `can(...)` lines, ready to sit inside `abilities: [ ... ]`. */
+  abilities: string[];
+  /** `//` comment lines naming what could not be rendered, and why. */
+  notes: string[];
+  /**
+   * Roles holding grants that the model vocabulary has no name for (anything outside
+   * anon/authenticated/admin) — an operator or reporting role, typically.
+   *
+   * Returned rather than written into `notes` because it is usually the SAME role on every
+   * table: a migrator or ops account granted across the schema. Repeating that fact once
+   * per model buries the per-table findings that are actually specific. The caller states
+   * it once, for the whole pull.
+   */
+  unmappedRoles: string[];
+}
+
+const DML: Record<string, 'read' | 'create' | 'update' | 'delete'> = {
+  SELECT: 'read',
+  INSERT: 'create',
+  UPDATE: 'update',
+  DELETE: 'delete',
+};
+
+/** The roles the compiler itself emits policies for; anything else is app-specific. */
+const KNOWN_ROLES = new Set(['anon', 'authenticated', 'admin']);
+
+/**
+ * The deparsed owner predicate the compiler produces, in both its casts:
+ *   (col = (((current_setting('request.jwt.claims'::text, true))::jsonb ->> 'sub'::text)))
+ * Recognising it turns a predicate back into `{ owner: 'col' }` — the structured shape —
+ * instead of an opaque `sql:` fragment. Anything unrecognised stays verbatim rather than
+ * being guessed at.
+ */
+const OWNER_RE =
+  /^\(?([a-z_][a-z0-9_]*)\s*=\s*\(*\(current_setting\('request\.jwt\.claims'::text,\s*true\)\)::jsonb\s*->>\s*'([a-z_]+)'::text\)*(?:::[a-z]+)?\)?$/i;
+
+/** Does this predicate say "the row is mine"? Returns the column and the claim if so. */
+export function parseOwnerPredicate(pred: string | null): { column: string; claim: string } | null {
+  if (!pred) return null;
+  const m = OWNER_RE.exec(pred.trim());
+  return m ? { column: m[1], claim: m[2] } : null;
+}
+
+/** Is a privilege EFFECTIVE for a role — i.e. actually granted, not merely policed? */
+function granted(contract: TableContract, role: string, privilege: string): boolean {
+  const direct = contract.grants[role] ?? [];
+  const publicGrant = contract.grants.PUBLIC ?? contract.grants.public ?? [];
+  return direct.includes(privilege) || publicGrant.includes(privilege);
+}
+
+/** The policies that apply to a role for a command (an `ALL` policy covers every command). */
+function policiesFor(contract: TableContract, role: string, command: string): PolicyContract[] {
+  return contract.policies.filter(
+    (p) => (p.command === command || p.command === 'ALL') && (p.roles.includes(role) || p.roles.includes('public')),
+  );
+}
+
+/** A sql`…` fragment literal, or null when the predicate is vacuous. */
+function sqlFragment(pred: string | null): string | null {
+  if (!pred) return null;
+  const t = pred.trim();
+  if (t === 'true' || t === '(true)') return null;
+  return `sql\`${t.replace(/`/g, '\\`')}\``;
+}
+
+/**
+ * Derive the ability stanza for ONE table from its live contract.
+ *
+ * Deliberately conservative. Every branch that cannot prove what it would emit falls
+ * through to `notes` rather than guessing — the caller renders those as comments beside
+ * the model, so the human sees the real rule and decides.
+ */
+export function deriveAbilities(contract: TableContract): DerivedAbilities {
+  const abilities: string[] = [];
+  const notes: string[] = [];
+  const table = contract.table;
+
+  // --- the admin bypass: one role holding every privilege ------------------------------
+  const adminAll = ['SELECT', 'INSERT', 'UPDATE', 'DELETE'].every((p) => granted(contract, 'admin', p));
+  if (adminAll) abilities.push(`can('manage', { role: 'admin' })`);
+
+  // --- dead policies: policed but never granted ----------------------------------------
+  // The trap. Rendering one of these would ADD a privilege that does not exist today.
+  for (const p of contract.policies) {
+    const commands = p.command === 'ALL' ? ['SELECT', 'INSERT', 'UPDATE', 'DELETE'] : [p.command];
+    for (const cmd of commands) {
+      const priv = cmd;
+      const live = p.roles.filter((r) => r !== 'public' && r !== 'admin' && !granted(contract, r, priv));
+      if (live.length && p.roles.some((r) => r !== 'admin')) {
+        notes.push(
+          `policy "${p.name}" (${cmd}) applies to ${live.join(', ')} but no ${priv} grant exists —`,
+        );
+        notes.push(
+          `  it is dead code today. Declaring it would ADD a privilege the database does not give.`,
+        );
+      }
+    }
+  }
+
+  // --- reads ---------------------------------------------------------------------------
+  const anonRead = granted(contract, 'anon', 'SELECT');
+  const authedRead = granted(contract, 'authenticated', 'SELECT');
+
+  if (anonRead) {
+    // Public read. If the live policy narrows it (a soft-delete guard, a published flag),
+    // carry that predicate — a public read with a filter is still a public read.
+    const pol = policiesFor(contract, 'anon', 'SELECT')[0];
+    const frag = sqlFragment(pol?.using ?? null);
+    abilities.push(frag ? `can('read', { sql: ${frag} })` : `can('read')`);
+  } else if (authedRead) {
+    const pol = policiesFor(contract, 'authenticated', 'SELECT')[0];
+    const owner = parseOwnerPredicate(pol?.using ?? null);
+    if (owner) {
+      const claim = owner.claim === 'sub' ? '' : `, userField: '${owner.claim}'`;
+      abilities.push(`can('read', { owner: '${owner.column}'${claim} })`);
+    } else {
+      const frag = sqlFragment(pol?.using ?? null);
+      abilities.push(frag ? `can('read', { role: 'authenticated', sql: ${frag} })` : `can('read', { role: 'authenticated' })`);
+    }
+  }
+
+  // --- writes --------------------------------------------------------------------------
+  for (const [command, action] of Object.entries(DML)) {
+    if (action === 'read') continue;
+    if (!granted(contract, 'authenticated', command)) continue;
+
+    const pol = policiesFor(contract, 'authenticated', command).find((p) => p.command !== 'ALL')
+      ?? policiesFor(contract, 'authenticated', command)[0];
+    const using = pol?.using ?? null;
+    const check = pol?.check ?? null;
+    const owner = parseOwnerPredicate(using) ?? parseOwnerPredicate(check);
+
+    const parts: string[] = [];
+    if (owner) {
+      parts.push(`owner: '${owner.column}'`);
+      if (owner.claim !== 'sub') parts.push(`userField: '${owner.claim}'`);
+    }
+    // A predicate beyond the owner gate (a state guard, a tenant filter) rides as `sql`.
+    const usingFrag = owner && parseOwnerPredicate(using) ? null : sqlFragment(using);
+    if (usingFrag) parts.push(`sql: ${usingFrag}`);
+    // The WRITE half, only when it genuinely differs. Postgres defaults it to USING, and
+    // emitting it unconditionally would be noise that also defeats the round-trip diff.
+    if (check && check !== using) {
+      const checkFrag = sqlFragment(check);
+      if (checkFrag) parts.push(`check: ${checkFrag}`);
+    }
+
+    if (!parts.length && !pol) {
+      // Granted with no policy at all. Under RLS that is a table nobody can actually
+      // reach; without RLS it is a wide-open privilege. Either way, say so.
+      notes.push(`${command} is granted to authenticated with no policy — ${contract.rls.enabled ? 'RLS is on, so no row qualifies' : 'RLS is OFF: this is unrestricted'}.`);
+      continue;
+    }
+    abilities.push(`can('${action}'${parts.length ? `, { ${parts.join(', ')} }` : ''})`);
+  }
+
+  // --- roles the compiler has no vocabulary for ----------------------------------------
+  const unmappedRoles = Object.keys(contract.grants).filter(
+    (r) => !KNOWN_ROLES.has(r) && r !== 'PUBLIC' && r !== 'public',
+  );
+
+  if (!abilities.length && !notes.length && !unmappedRoles.length) {
+    notes.push(`no grants found — this table is internal (nothing reaches it through the data API).`);
+  }
+
+  return { abilities, notes, unmappedRoles };
+}
+
+/** Render one table's derived stanza as the lines that sit inside a model literal. */
+export function renderDerivedAbilities(d: DerivedAbilities): string {
+  const out: string[] = [];
+  for (const n of d.notes) out.push(`  // ${n}`);
+  if (d.abilities.length) {
+    out.push(`  abilities: [${d.abilities.join(', ')}],`);
+  } else {
+    out.push(`  private: true,   // no effective privilege found — not part of the data API`);
+  }
+  return out.join('\n');
+}

package/src/cli/authz-redteam.ts

@@ -29,7 +29,8 @@ 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
+  | 'no-impersonate'    // the probing role could not SET ROLE into this role
+  | 'inconclusive';     // the statement failed BEFORE the privilege check — proves nothing
 
 export interface ProbeResult {
   role: string;
@@ -39,7 +40,7 @@ export interface ProbeResult {
 }
 
 export interface RedTeamFinding {
-  severity: 'hole' | 'broken' | 'unprobed';
+  severity: 'hole' | 'broken' | 'unprobed' | 'inconclusive' | 'inherited';
   role: string;
   table: string;
   command: ProbeCommand;
@@ -85,8 +86,15 @@ function pgArrayLiteral(values: string[]): string {
  *   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.
+ * "permission denied" -> denied-privilege; "row-level security" -> denied-rls.
+ *
+ * Any OTHER error needs care, and getting this wrong is how the tool cries wolf. A
+ * constraint or NOT NULL violation happens AFTER the permission check, so it proves the
+ * privilege was present -> allowed. But a statement rejected at parse/analysis time never
+ * reached the permission check at all and proves NOTHING -> inconclusive. Classifying the
+ * second kind as `allowed` is what reported `anon` as able to UPDATE a table it cannot
+ * touch: the probe's `SET pk = pk` hit 428C9 ("can only be updated to DEFAULT") on an
+ * identity PK, and a non-grant then read as "enforcement exceeds declaration".
  */
 export function buildProbeSql(roles: string[], tables: string[]): string {
   return `
@@ -111,9 +119,20 @@ BEGIN
           WHEN 'UPDATE' THEN NULL
         END;
         IF v_cmd = 'UPDATE' THEN
+          -- Prefer a column the statement can actually SET. An identity or generated
+          -- column rejects "SET col = col" at analysis time (428C9), before the permission
+          -- check — which makes the probe prove nothing. Fall back to the first column
+          -- only when every column is generated; that run reports inconclusive.
           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;
+              AND attnum > 0 AND NOT attisdropped
+              AND attidentity = '' AND attgenerated = ''
+            ORDER BY attnum LIMIT 1;
+          IF v_col IS NULL 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;
+          END IF;
           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;
 
@@ -126,7 +145,21 @@ BEGIN
             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
+              -- Did this error happen BEFORE the permission check, or after it?
+              -- Before (parse/analysis): the probe proves nothing about the privilege.
+              -- After (data/constraint): the privilege was present.
+              v_outcome := CASE
+                WHEN SQLSTATE IN (
+                  '428C9',  -- generated_always: identity/generated column (the probe's own SET pk = pk)
+                  '42703',  -- undefined_column
+                  '42P01',  -- undefined_table
+                  '42601',  -- syntax_error
+                  '42P10',  -- invalid_column_reference
+                  '42804',  -- datatype_mismatch
+                  '0A000'   -- feature_not_supported (e.g. writable-view restrictions)
+                ) THEN 'inconclusive'
+                ELSE 'allowed'
+              END;
           END;
           RESET ROLE;
         EXCEPTION WHEN insufficient_privilege THEN
@@ -205,6 +238,67 @@ export function toGrantGap(row: any): GrantGap {
 }
 
 /** Map a probe result row (from the SELECT) into a typed ProbeResult. */
+/** A privilege a role holds only by MEMBERSHIP in another role, not by a direct grant. */
+export interface InheritedGrant {
+  role: string;
+  table: string;   // schema-qualified
+  command: ProbeCommand;
+  via: string;     // the ancestor role(s) supplying it
+}
+
+/**
+ * Why does a role hold a privilege the contract never granted it?
+ *
+ * The contract's grants come from the table ACL, which records DIRECT grants. Effective
+ * privilege also flows through role membership (`GRANT parent TO child` with INHERIT), and
+ * the probe measures the effective answer. The gap is real but reads as noise: on a real
+ * brownfield schema a migrator role that inherits `postgres` reported 20 undeclared
+ * privileges — 5 tables × 4 commands — when the whole story is one line about the role.
+ *
+ * This attributes each such privilege to the ancestor that supplies it, so the finding can
+ * be stated once per role instead of once per table × command.
+ */
+export function buildInheritedPrivilegeSql(roles: string[], tables: string[]): string {
+  return `
+WITH RECURSIVE anc AS (
+  SELECT am.member AS member, am.roleid AS ancestor
+  FROM pg_auth_members am
+  JOIN pg_roles child ON child.oid = am.member AND child.rolinherit
+  UNION
+  SELECT a.member, am2.roleid
+  FROM anc a
+  JOIN pg_auth_members am2 ON am2.member = a.ancestor
+  JOIN pg_roles mid ON mid.oid = a.ancestor AND mid.rolinherit
+)
+SELECT r.rolname AS role,
+       (c.relnamespace::regnamespace::text || '.' || c.relname) AS "table",
+       p.priv AS command,
+       string_agg(DISTINCT ar.rolname, ', ' ORDER BY ar.rolname) AS via
+FROM pg_class c
+CROSS JOIN (VALUES ('SELECT'),('INSERT'),('UPDATE'),('DELETE')) AS p(priv)
+JOIN pg_roles r ON r.rolname = ANY(${pgArrayLiteral(roles)})
+JOIN anc ON anc.member = r.oid
+JOIN pg_roles ar ON ar.oid = anc.ancestor
+WHERE (c.relnamespace::regnamespace::text || '.' || c.relname) = ANY(${pgArrayLiteral(tables)})
+  AND has_table_privilege(r.oid, c.oid, p.priv)
+  AND has_table_privilege(ar.oid, c.oid, p.priv)
+  AND NOT EXISTS (
+    SELECT 1 FROM aclexplode(c.relacl) a
+    WHERE a.privilege_type = p.priv AND a.grantee IN (r.oid, 0)
+  )
+GROUP BY 1, 2, 3
+`;
+}
+
+export function toInheritedGrant(row: any): InheritedGrant {
+  return {
+    role: String(row.role),
+    table: String(row.table),
+    command: String(row.command).toUpperCase() as ProbeCommand,
+    via: String(row.via),
+  };
+}
+
 export function toProbeResult(row: any): ProbeResult {
   return {
     role: String(row.role),
@@ -226,9 +320,17 @@ export function toProbeResult(row: any): ProbeResult {
  * 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[] {
+export function evaluateRedTeam(
+  contract: AuthzContract,
+  results: ProbeResult[],
+  inherited: InheritedGrant[] = [],
+): RedTeamFinding[] {
   const tablesByName = new Map(contract.tables.map((t) => [t.table, t]));
   const findings: RedTeamFinding[] = [];
+  // Privileges explained by role membership rather than a direct grant. Keyed so the
+  // per-result lookup is exact; reported once per role, not once per table × command.
+  const inheritedBy = new Map(inherited.map((g) => [`${g.role}${g.table}${g.command}`, g]));
+  const inheritedRoles = new Map<string, { via: string; count: number }>();
 
   for (const r of results) {
     const table = tablesByName.get(r.table);
@@ -239,13 +341,34 @@ export function evaluateRedTeam(contract: AuthzContract, results: ProbeResult[])
     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 (r.outcome === 'inconclusive') {
+      // The statement never reached the permission check, so this proves nothing either
+      // way. Reported so it is visible, never counted as a pass or a hole.
+      findings.push({ severity: 'inconclusive', role: r.role, table: r.table, command: r.command,
+        detail: `${r.command} on ${r.table} failed before the privilege check — this probe proves nothing about ${r.role}` });
     } 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)` });
+      const via = inheritedBy.get(`${r.role}${r.table}${r.command}`);
+      if (via) {
+        // Real, but it is one fact about a role, not N facts about N tables.
+        const seen = inheritedRoles.get(r.role);
+        if (seen) seen.count += 1;
+        else inheritedRoles.set(r.role, { via: via.via, count: 1 });
+      } else {
+        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)` });
     }
   }
+
+  // One line per inheriting role. The membership IS the finding — a role that reaches
+  // tables through `GRANT parent TO child` is worth stating out loud once, and worth not
+  // stating N times.
+  for (const [role, { via, count }] of inheritedRoles) {
+    findings.push({ severity: 'inherited', role, table: '', command: 'SELECT',
+      detail: `${role} holds ${count} undeclared privilege(s) INHERITED via membership in ${via} — not a direct grant, so the contract cannot see them. Intentional for a migrator/owner role; a finding if it is an application role` });
+  }
   return findings;
 }