@everystack/cli 0.4.43 → 0.4.45

package/src/cli/authz-compile.ts

@@ -66,7 +66,11 @@ function claimExpr(claim: string): string {
  *   uuid: (author_id = (((current_setting('request.jwt.claims'::text, true))::jsonb ->> 'sub'::text))::uuid)
  *   text: (user_id   =  ((current_setting('request.jwt.claims'::text, true))::jsonb ->> 'sub'::text))
  */
-function ownerPredicate(sqlColumn: string, type: string, claim: string): string {
+function ownerPredicate(sqlColumn: string, type: string, claim: string, expr: string | null = null): string {
+  // A declared `ownerExpr` is the accessor the database already has (`auth.user_id()`),
+  // emitted verbatim and uncast: the function returns the owner column's type, and a cast
+  // the deparser would not print is a DROP + CREATE on every owner policy in the schema.
+  if (expr) return `(${sqlColumn} = ${expr})`;
   const ce = claimExpr(claim);
   if (type === 'text') return `(${sqlColumn} = ${ce})`;
   return `(${sqlColumn} = (${ce})::${castForType(type)})`;
@@ -89,7 +93,7 @@ function softDeleteGuard(sqlColumn: string): string {
  *     WHERE (uploads.user_id = ((current_setting('request.jwt.claims'::text, true))::jsonb ->> 'sub'::text))))
  */
 function viaPredicate(v: ViaRef): string {
-  const parentOwner = ownerPredicate(`${v.parentTable}.${v.parentOwner.sqlColumn}`, v.parentOwner.type, v.parentOwner.claim);
+  const parentOwner = ownerPredicate(`${v.parentTable}.${v.parentOwner.sqlColumn}`, v.parentOwner.type, v.parentOwner.claim, v.parentOwner.expr);
   return `(${v.fkColumn} IN ( SELECT ${v.parentTable}.${v.parentPk}\n   FROM ${v.parentTable}\n  WHERE ${parentOwner}))`;
 }
 
@@ -103,6 +107,8 @@ interface OwnerRef {
   type: string;
   /** JWT claim holding the owner id. */
   claim: string;
+  /** A declared accessor for the caller's id (`auth.user_id()`), or null for the inline claim. */
+  expr: string | null;
 }
 
 /**
@@ -135,6 +141,7 @@ function resolveOwner(model: ModelDescriptor): OwnerRef | null {
     sqlColumn: toSnakeCase(fieldKey),
     type: model.fields[fieldKey]?.spec.type ?? 'uuid',
     claim: ownerAbility.condition.userField ?? 'sub',
+    expr: rawExpr(ownerAbility.condition.ownerExpr, `${model.table}: can({ ownerExpr })`),
   };
 }
 
@@ -201,6 +208,31 @@ function isColumnRead(a: Ability): boolean {
   return a.action === 'read' && Boolean(a.condition.owner) && Boolean(a.condition.columns?.length);
 }
 
+/**
+ * `can(…, { role: 'public' })` names PostgreSQL's PUBLIC pseudo-role, and the two catalogs
+ * that describe it spell it differently — both correctly:
+ *
+ *   - `pg_policies.roles` renders it as the literal `{public}` (lowercase)
+ *   - `aclexplode()` yields grantee OID 0, which GRANTS_SQL renders as `'PUBLIC'`
+ *
+ * So the compiler speaks each catalog's spelling on its own axis. Saying `public` on both
+ * made the grant set-difference see `public` and `PUBLIC` as two grantees and emit a REVOKE
+ * and a GRANT that cancel out — on every run, converging never.
+ *
+ * The fold is COMPILE-TIME ONLY, applied to the author's declared role. Nothing folds at
+ * comparison time: `CREATE ROLE "Public"` is a legal, distinct role, and a case-insensitive
+ * compare against a live grantee would silently conflate it with the pseudo-role. (The cost
+ * of that choice: a real role named `Public` cannot be named by `role:`, because a model
+ * string carries no way to say "quoted identifier".)
+ */
+const isPseudoPublic = (role: string): boolean => role.toLowerCase() === 'public';
+
+/** The grant-side spelling of a declared role — what `aclexplode` would report. */
+const granteeKey = (role: string): string => (isPseudoPublic(role) ? 'PUBLIC' : role);
+
+/** The policy-side spelling of a declared role — what `pg_policies` would report. */
+const policyRole = (role: string): string => (isPseudoPublic(role) ? 'public' : role);
+
 /**
  * Column grants from the column-scoped read abilities: the read role (`authenticated`, since
  * the ability is owner-scoped, not role-gated) gets `SELECT (cols)`. Field keys are snake_cased
@@ -212,7 +244,7 @@ function compileColumnGrants(abilities: readonly Ability[]): Record<string, Reco
   const out: Record<string, Record<string, string[]>> = {};
   for (const a of abilities) {
     if (!isColumnRead(a)) continue;
-    const role = a.condition.role ?? 'authenticated';
+    const role = granteeKey(a.condition.role ?? 'authenticated');
     const cols = [...a.condition.columns!].map(toSnakeCase).sort();
     (out[role] ??= {}).SELECT = cols;
   }
@@ -244,6 +276,23 @@ function rawPredicate(value: unknown, where: string): string | null {
   return parenthesizeOnce(text.trim());
 }
 
+/**
+ * Unwrap a sql fragment to its text, UNparenthesized — for an expression that is not a
+ * predicate. `ownerExpr` is the right-hand side of `<col> = …`; parenthesizing it would
+ * emit `(user_id = (auth.user_id()))`, which is not what the deparser prints, and the
+ * whole point of declaring it is to match the live text exactly.
+ */
+function rawExpr(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 — the expression that decides who owns a row 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');
@@ -270,7 +319,7 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
   // parent subquery. Both drive the same owner-gated policies (select/insert/
   // update/delete_own); only the predicate text differs.
   const rowPred = owner
-    ? ownerPredicate(owner.sqlColumn, owner.type, owner.claim)
+    ? ownerPredicate(owner.sqlColumn, owner.type, owner.claim, owner.expr)
     : via
       ? viaPredicate(via)
       : null;
@@ -298,6 +347,33 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
     }
     return null;
   };
+  /**
+   * The predicate on the PUBLIC read — a read ability with neither a role nor a row scope.
+   *
+   * Read separately from {@link ownerReadPred} because the two are different BRANCHES of
+   * the same authenticated policy. Taking both from one ordered lookup made the anon
+   * policy depend on the order the abilities happened to be declared in: put the owner
+   * read first and `anon` inherited the owner branch's guard as its whole public rule.
+   */
+  const publicReadPred = (): string | null => {
+    for (const a of model.abilities) {
+      if (a.action !== 'read' || a.condition.role || rowScoped(a)) continue;
+      const p = rawPredicate(a.condition.sql ?? a.condition.where, `${table}: can('read')`);
+      if (p) return p;
+    }
+    return null;
+  };
+
+  /** The predicate the OWNER read narrows ITSELF by — `can('read', { owner, sql })`. */
+  const ownerReadPred = (): string | null => {
+    for (const a of model.abilities) {
+      if (a.action !== 'read' || !rowScoped(a) || isColumnRead(a)) continue;
+      const p = rawPredicate(a.condition.sql ?? a.condition.where, `${table}: can('read', { owner })`);
+      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) {
@@ -334,18 +410,37 @@ 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 readPred = predFor('read');
+    const readPred = publicReadPred();
     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:
-    // owners also see their own deleted rows). It must never REPLACE it — an owner
-    // 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
-      ? andPredicates(`(${sdGuard} OR ${rowPred})`, readPred)!
-      : anonUsing;
+    let authedUsing: string;
+    if (hasOwnerRead && rowPred && anonUsing !== 'true') {
+      // PUBLIC **OR** MINE. Two read abilities on one model — a public read and an
+      // owner read — are two branches of one authenticated policy, not a contest the
+      // public one wins. They used to be exactly that contest: `hasPublicRead` took
+      // the branch and the owner read was computed and discarded, so a signed-in
+      // author could not see their own non-public rows. On a real brownfield schema
+      // that hid ~13k legacy `pending` rows from the people who wrote them.
+      //
+      // The owner branch escapes the public predicate (that is the whole point) and
+      // carries its OWN guard — `can('read', { owner: 'userId', sql: … })` — so the
+      // author says what "mine" means without loosening what "public" means.
+      const ownBranch = andPredicates(rowPred, ownerReadPred())!;
+      authedUsing = `(${anonUsing} OR ${ownBranch})`;
+    } else {
+      // The owner predicate may only ever WIDEN a public read (the soft-delete OR:
+      // owners also see their own deleted rows). It must never REPLACE it — an owner
+      // 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` — and an
+      // unfiltered public read already contains every row an owner could add, which
+      // is why `anonUsing === 'true'` skips the disjunction rather than emitting a
+      // branch that can never change the answer.
+      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
@@ -366,7 +461,8 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
   // discarded. That is the same failure `rawPredicate` throws over, one level up: a predicate
   // that evaporates is an authorization hole wearing the costume of a working rule.
   for (const a of abilities.filter(isRoleRead)) {
-    const role = a.condition.role!;
+    // The policy-side spelling, so `role: 'PUBLIC'` still matches what pg_policies reports.
+    const role = policyRole(a.condition.role!);
     const name = `${t}_select_${role}`;
     const where = `${table}: can('read', { role: '${role}' })`;
     if (policies.some((p) => p.name === name)) {
@@ -408,7 +504,7 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
     // write on the owner connection and bypass RLS -> ENABLE-not-FORCE (on RDS the
     // owner is not a superuser, so a FORCEd table would block the owner's own writes).
     rls: { enabled: true, forced: model.writtenBy === 'app' },
-    grants: compileGrants(abilities),
+    grants: compileGrants(abilities, model.privileges),
     ...(compileColumnGrants(abilities) ? { columnGrants: compileColumnGrants(abilities) } : {}),
     policies,
   };
@@ -447,10 +543,19 @@ function verbsFor(action: Ability['action']): string[] {
  * table grants nothing, an owner-only table grants no anon SELECT, an admin-managed
  * table grants admin CRUD only. Deterministic: roles and privilege lists sorted,
  * so the output is byte-comparable with an introspected contract.
+ *
+ * `privileges` is the model's beyond-CRUD key — REFERENCES/TRIGGER/TRUNCATE, the table
+ * privileges `can()` has no verb for. They are UNIONED in, never subtracted: an admin that
+ * `can('manage')` and holds TRUNCATE keeps both. Without it, `manage` meant exactly CRUD and
+ * every live REFERENCES/TRIGGER/TRUNCATE read as drift, so the first plan against an existing
+ * schema revoked all three on every table — our spelling, not their schema.
  */
-function compileGrants(abilities: readonly Ability[]): Record<string, string[]> {
+function compileGrants(
+  abilities: readonly Ability[],
+  privileges: Record<string, readonly string[]> = {},
+): Record<string, string[]> {
   const grants: Record<string, Set<string>> = {};
-  const add = (role: string, verbs: string[]): void => {
+  const add = (role: string, verbs: readonly string[]): void => {
     const set = (grants[role] ??= new Set<string>());
     for (const v of verbs) set.add(v);
   };
@@ -461,13 +566,18 @@ function compileGrants(abilities: readonly Ability[]): Record<string, string[]>
     if (isColumnRead(a)) continue;
     const verbs = verbsFor(a.action);
     if (a.condition.role) {
-      add(a.condition.role, verbs);
+      add(granteeKey(a.condition.role), verbs);
     } else {
       add('authenticated', verbs);
       // A public read (no role, not owner/via-scoped) is anon-visible.
       if (a.action === 'read' && !a.condition.owner && !a.condition.via) add('anon', ['SELECT']);
     }
   }
+  // The role is spelled on the GRANT axis, so `privileges: { public: [...] }` reaches the
+  // same grantee `aclexplode` reports as `PUBLIC` — the fold the ability path already does.
+  for (const [role, privs] of Object.entries(privileges)) {
+    if (privs.length) add(granteeKey(role), privs);
+  }
   const out: Record<string, string[]> = {};
   for (const role of Object.keys(grants).sort()) out[role] = [...grants[role]].sort();
   return out;

package/src/cli/authz-contract.ts

@@ -23,6 +23,7 @@
 
 import { parsePgArray } from './security-catalog.js';
 import { withCanonicalSearchPath } from './search-path.js';
+import { matchPolicies, roleSetEqual } from './authz-identity.js';
 
 // ---------------------------------------------------------------------------
 // The contract format — the frozen, reviewable, version-controlled shape.
@@ -100,6 +101,42 @@ export function effectivePolicyCheck(p: PolicyContract): string | null {
   return p.check;
 }
 
+/**
+ * Does a role hold a privilege at the TABLE level? — the question "may we emit an ability?"
+ *
+ * `can('update')` compiles to a policy PLUS a table-wide `GRANT UPDATE`. So a role that holds
+ * UPDATE only on three columns does NOT satisfy this: rendering the ability would widen a
+ * column grant into a whole-table one. PUBLIC counts, in both catalog spellings, because a
+ * grant to PUBLIC really is held by every role.
+ */
+export function holdsTablePrivilege(t: TableContract, role: string, privilege: string): boolean {
+  const direct = t.grants[role] ?? [];
+  const pub = t.grants.PUBLIC ?? t.grants.public ?? [];
+  return direct.includes(privilege) || pub.includes(privilege);
+}
+
+/**
+ * Does a role hold a privilege AT ALL? — the question "does this policy authorize anything?"
+ *
+ * The same question one layer wider: a COLUMN-scoped grant counts. `GRANT UPDATE (body) ON t
+ * TO authenticated` really does let that role update, so a policy governing UPDATE is doing
+ * live work even though the role holds no table-level UPDATE.
+ *
+ * TWO PREDICATES ON PURPOSE, and they answer different questions — that is why they are here
+ * together rather than one being written twice. `db:pull` used the narrow one to answer the
+ * wide question and told adopters a live, column-granted UPDATE policy was "dead code today,
+ * declaring it would ADD a privilege the database does not give". Both halves were false, and
+ * it was printed beside the model they were about to trust. Use {@link holdsTablePrivilege} to
+ * decide what to EMIT; use this to decide what is DEAD.
+ */
+export function holdsPrivilege(t: TableContract, role: string, privilege: string): boolean {
+  if (holdsTablePrivilege(t, role, privilege)) return true;
+  const cols = t.columnGrants ?? {};
+  return Boolean(cols[role]?.[privilege]?.length)
+    || Boolean(cols.PUBLIC?.[privilege]?.length)
+    || Boolean(cols.public?.[privilege]?.length);
+}
+
 /** True when `s`'s outer parens already wrap the whole expression (redundant to add more). */
 export function isWrappedExpression(s: string): boolean {
   if (!s.startsWith('(') || !s.endsWith(')')) return false;
@@ -509,6 +546,24 @@ export async function introspectContract(
 
 export type DriftSeverity = 'drift';
 
+/** A live policy kept under its own name because it already carries the declared rule. */
+export interface PolicyAdoption {
+  /** Schema-qualified table. */
+  subject: string;
+  /** The policy name(s) the model would have created. */
+  declared: string[];
+  /** The name the database uses, and keeps. */
+  live: string;
+  /** Why it was accepted, in plain words. */
+  reason: string;
+}
+
+/** Drift, plus the adoptions that are deliberately NOT drift. */
+export interface ContractComparison {
+  findings: DriftFinding[];
+  adoptions: PolicyAdoption[];
+}
+
 export interface DriftFinding {
   /** Schema-qualified table, or `fn:<name>` for a function finding. */
   subject: string;
@@ -528,7 +583,20 @@ function tableMap(c: AuthzContract): Map<string, TableContract> {
  * Returns every discrepancy; an empty list means the live DB matches the declaration.
  */
 export function diffContracts(declared: AuthzContract, live: AuthzContract): DriftFinding[] {
+  return compareContracts(declared, live).findings;
+}
+
+/**
+ * The full comparison: drift AND the name divergences accepted by rule.
+ *
+ * `diffContracts` returns only the findings, because every caller treats a finding as drift
+ * and exits non-zero. An adoption is the opposite of drift, so it cannot travel in that list —
+ * but it must still be SHOWN, or the mapping between the model's name and the database's name
+ * becomes tribal knowledge.
+ */
+export function compareContracts(declared: AuthzContract, live: AuthzContract): ContractComparison {
   const findings: DriftFinding[] = [];
+  const adoptions: PolicyAdoption[] = [];
   const dTables = tableMap(declared);
   const lTables = tableMap(live);
 
@@ -546,7 +614,7 @@ export function diffContracts(declared: AuthzContract, live: AuthzContract): Dri
     }
     diffGrants(name, d, l, findings);
     diffColumnGrants(name, d, l, findings);
-    diffPolicies(name, d, l, findings);
+    diffPolicies(name, d, l, findings, adoptions);
   }
   for (const name of lTables.keys()) {
     if (!dTables.has(name)) {
@@ -575,7 +643,7 @@ export function diffContracts(declared: AuthzContract, live: AuthzContract): Dri
     }
   }
 
-  return findings;
+  return { findings, adoptions };
 }
 
 function diffGrants(table: string, d: TableContract, l: TableContract, out: DriftFinding[]): void {
@@ -612,31 +680,58 @@ function diffColumnGrants(table: string, d: TableContract, l: TableContract, out
   }
 }
 
-function diffPolicies(table: string, d: TableContract, l: TableContract, out: DriftFinding[]): void {
-  const dPol = new Map(d.policies.map((p) => [p.name, p]));
-  const lPol = new Map(l.policies.map((p) => [p.name, p]));
-  for (const [name, dp] of dPol) {
-    const lp = lPol.get(name);
-    if (!lp) {
-      out.push({ subject: table, kind: 'policy', detail: `policy "${name}" declared but missing from the live database` });
-      continue;
-    }
+/**
+ * Diff policies through the SHARED matcher — the same equivalence `emitReconcileSql` and the
+ * fingerprint use. A rule-identical live policy under a different name is not drift: the
+ * database already authorizes exactly what the model declares.
+ *
+ * Adoptions travel on their own channel, not as findings. A finding means drift and drift
+ * means exit 1, while an adoption is agreement. It is never SILENT though — once a live policy
+ * keeps its own name, the name the model shows and the name a human greps for have diverged,
+ * and that mapping has to stay machine-derived and visible.
+ */
+function diffPolicies(
+  table: string,
+  d: TableContract,
+  l: TableContract,
+  out: DriftFinding[],
+  adoptions: PolicyAdoption[],
+): void {
+  const m = matchPolicies(d.policies, l.policies);
+
+  for (const a of m.adopted) {
+    adoptions.push({ subject: table, declared: [a.declared], live: a.live, reason: 'same rule, different name' });
+  }
+  for (const g of m.adoptedGroups) {
+    adoptions.push({ subject: table, declared: g.declared, live: g.live, reason: 'one live policy covers the declared per-role group' });
+  }
+
+  // A name on BOTH sides whose rule moved is a CHANGE, not a remove-and-add. Saying which
+  // field moved is the difference between a finding an operator can act on and one they have
+  // to go read the catalog to understand.
+  const createdByName = new Map(m.toCreate.map((p) => [p.name, p]));
+  const changed = new Set<string>();
+  for (const name of m.toDrop) {
+    const dp = createdByName.get(name);
+    if (!dp) continue;
+    const lp = l.policies.find((p) => p.name === name)!;
+    changed.add(name);
     const changes: string[] = [];
-    if (dp.command !== lp.command) changes.push(`command ${dp.command}→${lp.command}`);
-    if (dp.permissive !== lp.permissive) changes.push(`permissive ${dp.permissive}→${lp.permissive}`);
-    if (dp.roles.join(',') !== lp.roles.join(',')) changes.push(`roles [${dp.roles}]→[${lp.roles}]`);
-    if ((dp.using ?? '') !== (lp.using ?? '')) changes.push(`USING changed`);
-    // Compared through the server's own defaulting rule, so this agrees with
-    // emitReconcileSql — otherwise db:check reports drift the plan does not carry.
-    if ((effectivePolicyCheck(dp) ?? '') !== (effectivePolicyCheck(lp) ?? '')) changes.push(`WITH CHECK changed`);
-    if (changes.length) {
-      out.push({ subject: table, kind: 'policy', detail: `policy "${name}": ${changes.join(', ')}` });
-    }
+    if (dp.command !== lp.command) changes.push(`command ${dp.command}\u2192${lp.command}`);
+    if (dp.permissive !== lp.permissive) changes.push(`permissive ${dp.permissive}\u2192${lp.permissive}`);
+    if (!roleSetEqual(dp.roles, lp.roles)) changes.push(`roles [${dp.roles}]\u2192[${lp.roles}]`);
+    if ((dp.using ?? '') !== (lp.using ?? '')) changes.push('USING changed');
+    if ((effectivePolicyCheck(dp) ?? '') !== (effectivePolicyCheck(lp) ?? '')) changes.push('WITH CHECK changed');
+    out.push({ subject: table, kind: 'policy', detail: `policy "${name}": ${changes.join(', ')}` });
   }
-  for (const name of lPol.keys()) {
-    if (!dPol.has(name)) {
-      out.push({ subject: table, kind: 'policy', detail: `policy "${name}" exists live but is not declared (undeclared policy)` });
-    }
+
+  for (const p of m.toCreate) {
+    if (changed.has(p.name)) continue;
+    out.push({ subject: table, kind: 'policy', detail: `policy "${p.name}" declared but missing from the live database` });
+  }
+  for (const name of m.toDrop) {
+    if (changed.has(name)) continue;
+    out.push({ subject: table, kind: 'policy', detail: `policy "${name}" exists live but is not declared (undeclared policy)` });
   }
 }