@everystack/cli 0.4.44 → 0.4.46

package/src/cli/authz-contract.ts

@@ -22,7 +22,8 @@
  */
 
 import { parsePgArray } from './security-catalog.js';
-import { withCanonicalSearchPath } from './search-path.js';
+import { INTROSPECTION_SESSION, type SessionRunner } from './session.js';
+import { matchPolicies, roleSetEqual } from './authz-identity.js';
 
 // ---------------------------------------------------------------------------
 // The contract format — the frozen, reviewable, version-controlled shape.
@@ -100,6 +101,119 @@ 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);
+}
+
+/** The four row-level commands a policy can govern. `FOR ALL` fans out across them. */
+export const POLICY_COMMANDS = ['DELETE', 'INSERT', 'SELECT', 'UPDATE'];
+
+/** Every command a policy governs — `ALL` fans out, so a live `FOR ALL` is compared per command. */
+export function policyCommands(p: PolicyContract): string[] {
+  return p.command === 'ALL' ? [...POLICY_COMMANDS] : [p.command];
+}
+
+/**
+ * Is this policy DEAD — does it authorize nothing at all?
+ *
+ * PostgreSQL checks the GRANT before the policy, so a policy governing a privilege none of
+ * its roles holds is inert: it cannot admit a single row today, and removing it takes away
+ * access that was never there. A PUBLIC policy applies to every grantee, so it is dead only
+ * when NO grantee holds the privilege.
+ *
+ * ONE definition, four callers — the classifier (what class is this statement?), the
+ * reconciler (should I drop it?), the canonical form (is it part of the state?), and db:pull
+ * (what do I tell the adopter?). They were drifting apart, which is this milestone's recurring
+ * bug: two surfaces answering the same question differently. Note the deadness is a property
+ * of the CONTRACT, not the policy — it is recomputed against live grants every time, so a
+ * policy RESURRECTS the moment a grant makes it effective.
+ */
+export function isPolicyDead(t: TableContract, p: PolicyContract): boolean {
+  const roles = p.roles.includes('public') || p.roles.includes('PUBLIC')
+    ? Object.keys(t.grants)
+    : p.roles;
+  if (!roles.length) return true;
+  // `holdsPrivilege`, not the table-level one: a column-scoped grant is real access, so a
+  // policy governing it is doing live work. See the two-predicate note above.
+  return !policyCommands(p).some((cmd) => roles.some((r) => holdsPrivilege(t, r, cmd)));
+}
+
+/** Does this policy name PostgreSQL's PUBLIC pseudo-role — the open set of every role? */
+export function isPublicPolicy(p: PolicyContract): boolean {
+  return p.roles.some((r) => r.toUpperCase() === 'PUBLIC');
+}
+
+/**
+ * A policy's RULE, with the roles and the NAME deliberately absent — what it authorizes, not
+ * whom it names or what it is called. The same normalization the canonical form hashes by, so
+ * "these two policies say the same thing" has one answer.
+ */
+export function policyRuleKey(p: PolicyContract): string {
+  return JSON.stringify([p.command, p.permissive, p.using ?? '', effectivePolicyCheck(p) ?? '']);
+}
+
+/**
+ * Is this policy SUBSUMED — does an identical rule already reach every role it names?
+ *
+ * PERMISSIVE policies OR together, and a policy TO PUBLIC applies to every role there is. So a
+ * role-scoped policy whose rule is character-for-character a PUBLIC policy's rule contributes
+ * nothing: every session it would admit is already admitted. Dropping it changes no access,
+ * which is why it is churn rather than a change — a brownfield database often carries both,
+ * one from the framework and one from a migration written years earlier.
+ *
+ * Two guards, and they are the whole safety of this:
+ *
+ *  - **RESTRICTIVE policies are never subsumed.** They AND rather than OR, so a restrictive
+ *    policy is the thing NARROWING access; removing it would widen. Only permissive policies
+ *    can be redundant, and only a permissive PUBLIC policy can make them so.
+ *  - **The rule must match exactly**, including the effective WITH CHECK. A PUBLIC policy with
+ *    a laxer predicate does not subsume a stricter role-scoped one — under OR the lax rule
+ *    already wins, but the two are not the same state, and hashing them equal would report
+ *    MATCH while the reconciler still had work.
+ */
+export function isPolicySubsumed(t: TableContract, p: PolicyContract): boolean {
+  if (!p.permissive || isPublicPolicy(p)) return false;
+  const key = policyRuleKey(p);
+  // No self-exclusion by NAME: `p` is asked about against BOTH the live and the declared
+  // contract (subsumed before and after), and the compiler routinely picks the same policy
+  // name the brownfield database already uses — so a name guard here would silently exclude
+  // the very PUBLIC policy doing the covering. It is not needed: `p` is non-PUBLIC by the
+  // line above and every candidate is PUBLIC, so `p` can never match itself.
+  return t.policies.some((o) => o.permissive && isPublicPolicy(o) && policyRuleKey(o) === key);
+}
+
 /** 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;
@@ -479,27 +593,23 @@ export function assembleContract(rows: ContractRows): AuthzContract {
 
 /** Run every introspection query through one runner and assemble the contract. */
 export async function introspectContract(
-  run: QueryRunner,
+  session: SessionRunner,
   mapFunctionRow: (row: any) => { schema: string; name: string; securityDefiner: boolean; hasSearchPath: boolean },
   functionsSql: string,
 ): Promise<AuthzContract> {
-  // Policy USING/WITH CHECK expressions deparse relative to the search_path — pin the
-  // canonical baseline so an ambient non-default path never reads as false authz drift.
-  return withCanonicalSearchPath(run, async () => {
-    const [rls, policies, grants, columnGrants, fnRows] = await Promise.all([
-      run(RLS_SQL),
-      run(POLICIES_SQL),
-      run(GRANTS_SQL),
-      run(COLUMN_GRANTS_SQL),
-      run(functionsSql),
-    ]);
-    return assembleContract({
-      rls: rls as RlsRow[],
-      policies: policies as PolicyRow[],
-      grants: grants as GrantRow[],
-      columnGrants: columnGrants as ColumnGrantRow[],
-      functions: (fnRows as any[]).map(mapFunctionRow),
-    });
+  // ONE session: the five queries describe one moment under one pinned search_path.
+  // Policy USING / WITH CHECK expressions deparse relative to that path, so a read spread
+  // across connections can report authz drift that does not exist.
+  const [rls, policies, grants, columnGrants, fnRows] = await session(
+    [RLS_SQL, POLICIES_SQL, GRANTS_SQL, COLUMN_GRANTS_SQL, functionsSql],
+    INTROSPECTION_SESSION,
+  );
+  return assembleContract({
+    rls: rls as RlsRow[],
+    policies: policies as PolicyRow[],
+    grants: grants as GrantRow[],
+    columnGrants: columnGrants as ColumnGrantRow[],
+    functions: (fnRows as any[]).map(mapFunctionRow),
   });
 }
 
@@ -509,6 +619,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 +656,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 +687,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 +716,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 +753,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)` });
   }
 }