@everystack/cli 0.4.40 → 0.4.43

package/src/cli/authz-redteam.ts

@@ -40,7 +40,7 @@ export interface ProbeResult {
 }
 
 export interface RedTeamFinding {
-  severity: 'hole' | 'broken' | 'unprobed' | 'inconclusive' | 'inherited';
+  severity: 'hole' | 'broken' | 'unprobed' | 'inconclusive' | 'inherited' | 'elevated';
   role: string;
   table: string;
   command: ProbeCommand;
@@ -244,6 +244,9 @@ export interface InheritedGrant {
   table: string;   // schema-qualified
   command: ProbeCommand;
   via: string;     // the ancestor role(s) supplying it
+  /** True when an ancestor is SUPERUSER or BYPASSRLS — the role bypasses RLS entirely,
+   *  which makes every probe result for it vacuous. Drives the severity split. */
+  elevated: boolean;
 }
 
 /**
@@ -273,7 +276,8 @@ WITH RECURSIVE anc AS (
 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
+       string_agg(DISTINCT ar.rolname, ', ' ORDER BY ar.rolname) AS via,
+       bool_or(ar.rolsuper OR ar.rolbypassrls) AS elevated
 FROM pg_class c
 CROSS JOIN (VALUES ('SELECT'),('INSERT'),('UPDATE'),('DELETE')) AS p(priv)
 JOIN pg_roles r ON r.rolname = ANY(${pgArrayLiteral(roles)})
@@ -296,6 +300,10 @@ export function toInheritedGrant(row: any): InheritedGrant {
     table: String(row.table),
     command: String(row.command).toUpperCase() as ProbeCommand,
     via: String(row.via),
+    // An ancestor that is SUPERUSER or BYPASSRLS makes every probe result for this role
+    // vacuous — default-deny cannot be falsified and RLS assertions are void. That is a
+    // different finding from inheriting an ordinary role's grants, and it is graded so.
+    elevated: row.elevated === true || row.elevated === 't' || row.elevated === 'true',
   };
 }
 
@@ -329,8 +337,8 @@ export function evaluateRedTeam(
   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 }>();
+  const inheritedBy = new Map(inherited.map((g) => [`${g.role}\u0000${g.table}\u0000${g.command}`, g]));
+  const inheritedRoles = new Map<string, { via: string; count: number; elevated: boolean }>();
 
   for (const r of results) {
     const table = tablesByName.get(r.table);
@@ -347,12 +355,12 @@ export function evaluateRedTeam(
       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) {
-      const via = inheritedBy.get(`${r.role}${r.table}${r.command}`);
+      const via = inheritedBy.get(`${r.role}\u0000${r.table}\u0000${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 });
+        if (seen) { seen.count += 1; seen.elevated ||= via.elevated; }
+        else inheritedRoles.set(r.role, { via: via.via, count: 1, elevated: via.elevated });
       } 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)` });
@@ -366,9 +374,23 @@ export function evaluateRedTeam(
   // 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` });
+  for (const [role, { via, count, elevated }] of inheritedRoles) {
+    // The severity axis is WHAT the ancestor is, not that inheritance happened.
+    //
+    // An ordinary ancestor's grants are finite, enumerable, and still RLS-subject: the
+    // database enforces declared ∪ inherited, which is a completeness note.
+    //
+    // A SUPERUSER/BYPASSRLS ancestor is categorically different. The role bypasses every
+    // policy, its effective access is unbounded, and every probe result for it is vacuous —
+    // this tool cannot vouch for the role at all. Reporting that at the same level as
+    // "could not SET ROLE into this role" is what let an adopter read the run as clean.
+    if (elevated) {
+      findings.push({ severity: 'elevated', role, table: '', command: 'SELECT',
+        detail: `${role} inherits ${via}, which is SUPERUSER or BYPASSRLS — it bypasses every RLS policy and holds privileges no ACL lists (${count} seen here). Every probe result for ${role} is vacuous: this run cannot vouch for it` });
+    } else {
+      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;
 }

package/src/cli/commands/db-apply.ts

@@ -31,6 +31,11 @@ import { planHash, PLAN_VERSION, type EdgePlan } from '../edge-plan.js';
 import { verifyDescent, type DescentVerdict, type LiveState } from '../git-descent.js';
 import { checkDestructiveAuthority, readApproverParam, resolveCallerIdentity, type AuthorityVerdict } from '../apply-authority.js';
 import { resolveModelsPath } from '../models-path.js';
+import { loadModels } from './db-generate.js';
+import { loadDeclaredDerived } from '../declared-derived.js';
+import { compileTableContract } from '../authz-compile.js';
+import { governedRoleSet, ungovernedGrants } from '../authz-reconcile.js';
+import { readBaselineFile, checkAgainstBaseline, baselineRefusal } from '../authz-baseline.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
 import { resolveConfig, opsFunction } from '../config.js';
 import { invokeAction, lambdaQueryRunner } from '../aws.js';
@@ -341,6 +346,19 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
       actor: process.env.USER ?? null,
       gitRef: currentGitRef() ?? plan.gitRef,
       ...(verifyAuthority ? { verifyAuthority } : {}),
+      // Re-verified here, not just at mint: a plan is an artifact with a lifetime, and a
+      // foreign role granted between minting and applying would otherwise ride through.
+      verifyAuthzBaseline: async ({ contract }) => {
+        const stageName = flags.stage || 'local';
+        const models = await loadModels(resolveModelsPath(flags.models));
+        const governedRoles = (await loadDeclaredDerived(flags.models))?.governedRoles ?? [];
+        const declaredAuthz = { tables: models.map((m) => compileTableContract(m, {})), functions: [] };
+        const exemptions = ungovernedGrants(contract, governedRoleSet(declaredAuthz, governedRoles));
+        const violations = checkAgainstBaseline(await readBaselineFile(), stageName, exemptions);
+        return violations.length === 0
+          ? { ok: true as const }
+          : { ok: false as const, reason: baselineRefusal(stageName, violations) };
+      },
       ...(forceDescent === undefined ? {
         verifyDescent: async (live: LiveState & { fingerprint: string }) => {
           step('Descent: searching git for the commit that declares the target\'s state...');

package/src/cli/commands/db-authz.ts

@@ -252,12 +252,20 @@ export async function dbAuthzTestCommand(flags: Record<string, string>): Promise
   const unprobed = findings.filter((f) => f.severity === 'unprobed');
   const inconclusive = findings.filter((f) => f.severity === 'inconclusive');
   const inheritedFindings = findings.filter((f) => f.severity === 'inherited');
+  // An ancestor that is SUPERUSER/BYPASSRLS makes every probe for that role vacuous. It is
+  // NOT an enforcement hole — the database enforces exactly what the grants say — so it does
+  // not fail the gate, which would go red on the many legitimate elevated migration roles
+  // and teach adopters to stop running it. But it is warn-grade, and it must qualify the
+  // success line: people read the checkmark and stop, which is exactly how the first adopter
+  // came away thinking a real finding had been dismissed.
+  const elevatedFindings = findings.filter((f) => f.severity === 'elevated');
   const gaps = gapRows.map(toGrantGap);
 
   console.log('');
   for (const f of holes) fail(`[HOLE]   ${f.detail}`);
   for (const f of broken) warn(`[BROKEN] ${f.detail}`);
   for (const g of gaps) fail(`[GRANT-GAP] ${g.secdef} calls ${g.helper} but its owner cannot EXECUTE it (42501 in prod once ownership is normalized)`);
+  for (const f of elevatedFindings) warn(`[ELEVATED] ${f.detail}`);
   for (const f of inheritedFindings) info(`[inherited] ${f.detail}`);
   if (inconclusive.length) {
     // Never a pass and never a failure — a probe that proved nothing, said out loud so it
@@ -273,7 +281,15 @@ export async function dbAuthzTestCommand(flags: Record<string, string>): Promise
   console.log('');
 
   if (holes.length === 0 && broken.length === 0 && gaps.length === 0) {
-    success(`db:authz:test — ${venueLabel} enforces the contract (${contract.tables.length} tables probed, default-deny holds, SECDEF grants complete)`);
+    // "default-deny holds" is a FALSE UNIVERSAL when a role bypasses RLS. Any claim this run
+    // could not verify for a role is excluded from the claim in the sentence that makes it,
+    // so a reader who sees only the green line still learns one role is outside it.
+    const exempt = elevatedFindings.map((f) => f.role).sort();
+    const scope = exempt.length
+      ? `${contract.tables.length} tables probed; default-deny holds EXCEPT for ${exempt.join(', ')} — `
+        + `${exempt.length === 1 ? 'that role bypasses RLS by inheritance and this run cannot vouch for it' : 'those roles bypass RLS by inheritance and this run cannot vouch for them'}`
+      : `${contract.tables.length} tables probed, default-deny holds, SECDEF grants complete`;
+    success(`db:authz:test — ${venueLabel} enforces the contract (${scope})`);
     process.exit(0);
   }
   fail(`db:authz:test — ${holes.length} enforcement hole(s), ${broken.length} broken grant(s), ${gaps.length} SECDEF grant gap(s). ${venueLabel} does not enforce the contract.`);

package/src/cli/commands/db-check.ts

@@ -29,6 +29,7 @@
  */
 
 import fs from 'node:fs/promises';
+import path from 'node:path';
 import type { ModelDescriptor, DerivedDescriptor } from '@everystack/model';
 import { compileDeclaredState } from '../declared-diff.js';
 import { compileMigration } from '../migration-compile.js';
@@ -41,6 +42,7 @@ import { loadDeclaredDerived, retiredSqlDirAnywhere, retiredSqlDirFlagRefusal, t
 import type { SequenceDescriptor } from '@everystack/model';
 import type { SourceObject } from '../derived-source.js';
 import { findReadAuthzGaps } from '../authz-lint.js';
+import { parseBaseline, renderBaseline, BASELINE_FILE } from '../authz-baseline.js';
 import { findDerivedReadGaps, findSecdefExecuteGaps, findMatviewSnapshotWarnings } from '../derived-lint.js';
 import { step, success, fail, info, warn } from '../output.js';
 
@@ -82,6 +84,9 @@ export interface StaticCheckInput {
    *  stream reads `export const models`; when the two disagree, the state layer builds a
    *  different database than the modules declare — the split-brain gate below names it. */
   moduleModels?: ModelDescriptor[] | null;
+  /** Raw `db/authz-baseline.json`, or null when there is none. The ARTIFACT half of the
+   *  ungoverned-grantee gate — see the check below for what it deliberately does not do. */
+  baselineSource?: string | null;
 }
 
 export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
@@ -155,6 +160,37 @@ export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
     }
   }
 
+  // The adoption baseline, ARTIFACT ONLY.
+  //
+  // This check cannot see the threat and must not pretend to. The foreign grantees it
+  // exists to catch live in a real database; db:check's ephemeral compose builds a scratch
+  // database that by construction has none of them. So what runs offline is: does the
+  // artifact parse, and does it regenerate byte-identically (a hand-edit that does not
+  // match the recorded observation shape is a fail). The gate that actually defends the
+  // database is on the LIVE path — db:plan refuses to mint and db:apply re-verifies.
+  if (input.baselineSource != null) {
+    try {
+      const parsed = parseBaseline(input.baselineSource);
+      if (renderBaseline(parsed) !== input.baselineSource) {
+        findings.push({
+          level: 'fail',
+          area: 'authz',
+          message: `${BASELINE_FILE} is not in generated form — re-run \`db:pull --abilities live --stage <name>\` and commit the result. (A hand-edited baseline is how a foreign role gets admitted without the observation that justifies it.)`,
+        });
+      } else {
+        const stages = Object.keys(parsed.stages).sort();
+        const total = stages.reduce((n, st) => n + Object.keys(parsed.stages[st].grantees).length, 0);
+        findings.push({
+          level: 'ok',
+          area: 'authz',
+          message: `${BASELINE_FILE} is in generated form — ${total} adopted foreign grantee(s) across ${stages.length} stage(s): ${stages.join(', ')} (the live gate runs at db:plan/db:apply, not here)`,
+        });
+      }
+    } catch (err: any) {
+      findings.push({ level: 'fail', area: 'authz', message: err.message });
+    }
+  }
+
   // The derived layer failing to COMPILE (reachability, cycles, undeclared trigger
   // functions) is a hard fail — CI cannot shrug at a compile error.
   if (input.derivedError) {
@@ -295,10 +331,19 @@ export async function dbCheckCommand(flags: Record<string, string>): Promise<voi
     derivedError = err.message;
   }
 
+  // The baseline artifact, read raw so the check can compare it against its own
+  // regeneration. Absent is not a failure here — an app with no foreign grantees has
+  // nothing to adopt; the LIVE gate is what refuses an unadopted one.
+  let baselineSource: string | null = null;
+  try {
+    baselineSource = await fs.readFile(path.resolve(process.cwd(), BASELINE_FILE), 'utf8');
+  } catch { /* no baseline — see above */ }
+
   const findings = runStaticChecks({
     modelsPath, models, modelsError, artifactPath, artifactSource, sqlDirRetired,
     sequences: declaredDb?.sequences, derived: declaredDb?.derived, derivedError,
     moduleModels: declaredDb?.models ?? null,
+    baselineSource,
   });
   for (const f of findings) {
     (f.level === 'fail' || f.level === 'warn' ? warn : info)(`${MARK[f.level]} ${f.area}: ${f.message}`);

package/src/cli/commands/db-generate.ts

@@ -27,7 +27,9 @@ import { introspectSchema } from '../schema-introspect.js';
 import { compileDrizzleSource } from '../schema-source.js';
 import { compileModuleMigration } from '../migration-compile.js';
 import { generateMigrationSql, unmodeledTables, formatMigrationFile, planMigrationFile, resolveSchemaOut, HELD_DROP_PREFIX, type Journal } from '../migration-generate.js';
-import { introspectContract, type QueryRunner } from '../authz-contract.js';
+import { introspectContract, type QueryRunner, type AuthzContract } from '../authz-contract.js';
+import { compileTableContract } from '../authz-compile.js';
+import { governedRoleSet, ungovernedGrants, renderGrantExemptions } from '../authz-reconcile.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
 import { resolveModelsPath } from '../models-path.js';
@@ -86,7 +88,7 @@ async function loadModules(modelsPath: string): Promise<Module[]> {
   }
   if (Array.isArray(mod.modules)) return mod.modules;
   const models = mod.models ?? mod.default;
-  if (Array.isArray(models)) return [{ models, extensions: [], sequences: [], derived: [], functions: [] }];
+  if (Array.isArray(models)) return [{ models, extensions: [], sequences: [], derived: [], governedRoles: [], functions: [] }];
   throw new Error(`${modelsPath} must export a \`modules\` (or \`models\`) array.`);
 }
 
@@ -129,6 +131,26 @@ async function dbGenerateInit(modelsPath: string, migrationsDir: string, schemaO
 }
 
 /** Read the journal if present (null = no history yet). */
+/**
+ * Name every live grantee the declared authz does not govern, with its exact privileges.
+ *
+ * The reconciler EXEMPTS these from revocation — a migrator, ETL account or BI reader the
+ * model vocabulary cannot express would otherwise have its access destroyed by a plan
+ * nobody read (32 such revokes on the first brownfield schema this was measured against).
+ * The exemption is only defensible if it is never silent, so this prints on every generate,
+ * dry run or not, and names roles and privileges exactly rather than counting them.
+ */
+function reportGrantExemptions(liveAuthz: AuthzContract | undefined, models: ModelDescriptor[], governedRoles: string[]): void {
+  if (!liveAuthz) return; // no live side — nothing can be ungoverned
+  const declared: AuthzContract = { tables: models.map((m) => compileTableContract(m, {})), functions: [] };
+  const exemptions = ungovernedGrants(liveAuthz, governedRoleSet(declared, governedRoles));
+  if (exemptions.length === 0) return;
+  const roles = new Set(exemptions.map((e) => e.grantee));
+  warn(`${roles.size} role(s) hold privileges this schema does not govern — left UNTOUCHED, never revoked:`);
+  for (const line of renderGrantExemptions(exemptions)) info(`  ${line}`);
+  info(`Bring them under the reconciler with defineModule({ governedRoles: [...] }), or leave them exempt — either way they are listed here every run.`);
+}
+
 async function readJournal(migrationsDir: string): Promise<Journal | null> {
   try {
     return JSON.parse(await fs.readFile(path.join(migrationsDir, 'meta', '_journal.json'), 'utf8'));
@@ -226,11 +248,15 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
 
   // One ordered migration carries both layers: data DDL first, then the authz reconcile
   // (RLS/policies/grants) the Models' abilities declare, diffed against the live contract.
-  const statements = generateMigrationSql(models, current, { allowDrops, liveAuthz, sequences: declaredDb?.sequences });
+  const statements = generateMigrationSql(models, current, { allowDrops, liveAuthz, sequences: declaredDb?.sequences, governedRoles: declaredDb?.governedRoles });
   const unmodeled = unmodeledTables(models, current);
   if (unmodeled.length) {
     info(`${unmodeled.length} table(s) in the database are not declared by any model — left untouched (db:generate manages only declared tables).`);
   }
+  // Exemptions are enumerated on EVERY generate, dry run or not. The reconciler leaves an
+  // ungoverned grantee's privileges alone rather than revoking them; that is only
+  // defensible because the artifact says exactly whose access it chose not to govern.
+  reportGrantExemptions(liveAuthz, models, declaredDb?.governedRoles ?? []);
   console.log('');
   if (statements.length === 0) {
     success(`db:generate — the live database already matches the models. ${dryRun ? 'Nothing to preview.' : 'No migration written.'}`);

package/src/cli/commands/db-plan.ts

@@ -19,6 +19,7 @@
  */
 
 import fs from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
 import type { ModelDescriptor } from '@everystack/model';
 import { introspectContract, type QueryRunner } from '../authz-contract.js';
 import { introspectSchema } from '../schema-introspect.js';
@@ -33,11 +34,32 @@ import { resolveModelsPath } from '../models-path.js';
 import { resolveConfig, opsFunction } from '../config.js';
 import { lambdaQueryRunner } from '../aws.js';
 import { loadModels } from './db-generate.js';
+import { loadDeclaredDerived } from '../declared-derived.js';
+import { governedRoleSet, ungovernedGrants } from '../authz-reconcile.js';
+import { readBaselineFile, checkAgainstBaseline, baselineRefusal } from '../authz-baseline.js';
+import { compileTableContract } from '../authz-compile.js';
 import { reportPipelineLastRun } from './pipeline-run.js';
 import { step, success, fail, info, warn } from '../output.js';
 
 const DEFAULT_OUT = 'db.plan.json';
 
+/**
+ * True when git would ignore `file` — false when it would happily commit it, and ALSO false
+ * outside a repo or when git is unavailable, because the warning is only ever advice and a
+ * missing git must not turn a plan mint into a failure.
+ *
+ * `check-ignore` exits 0 for ignored, 1 for not-ignored, 128 for "not a repo".
+ */
+function isGitIgnored(file: string): boolean {
+  try {
+    const r = spawnSync('git', ['check-ignore', '-q', file], { stdio: 'ignore' });
+    if (r.error || r.status === 128) return true; // no repo / no git — nothing to warn about
+    return r.status === 0;
+  } catch {
+    return true;
+  }
+}
+
 export async function dbPlanCommand(flags: Record<string, string>): Promise<void> {
   let dbSource: DbSource;
   try {
@@ -73,6 +95,29 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
     step('Asking the target its fingerprint (introspecting state + authz)...');
     const snapshot = await introspectSchema(runner);
     const contract = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+    // The modules' widened governed-role set. A barrel that exports only `models` has none,
+    // which is the greenfield default: govern exactly what the models name.
+    let declaredGovernedRoles: string[] = [];
+    try {
+      declaredGovernedRoles = (await loadDeclaredDerived(flags.models))?.governedRoles ?? [];
+    } catch {
+      // The barrel's own compose errors surface on the paths that need the derived layer;
+      // a plan must not fail to mint because a module could not be read for this one field.
+    }
+
+    // THE GATE. The reconciler leaves an ungoverned grantee alone rather than revoking it,
+    // so the only thing standing between a brownfield exemption and a permanent silent hole
+    // is this: a foreign grantee must be in the stage's adoption baseline, and must not have
+    // grown since. An absent baseline is an EMPTY one, so greenfield gets the strong
+    // property with no flag to remember — a new foreign role refuses on day one.
+    const stageName = flags.stage || 'local';
+    const declaredAuthz = { tables: models.map((m) => compileTableContract(m, {})), functions: [] };
+    const exemptions = ungovernedGrants(contract, governedRoleSet(declaredAuthz, declaredGovernedRoles));
+    const violations = checkAgainstBaseline(await readBaselineFile(), stageName, exemptions);
+    if (violations.length > 0) {
+      fail(baselineRefusal(stageName, violations));
+      process.exit(1);
+    }
 
     let plan;
     try {
@@ -80,6 +125,9 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
         allowDrops: flags['allow-drops'] === 'true',
         gitRef: currentGitRef(),
         actor: process.env.USER ?? null,
+        // Without this the MINTED PLAN carries a REVOKE for every live grantee the models
+        // do not name — which is the artifact an operator actually applies.
+        governedRoles: declaredGovernedRoles,
       });
     } catch (err: any) {
       fail(`Mint refused: ${err.message}`);
@@ -131,6 +179,12 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
     if (out !== '-') {
       success(`Wrote ${out} — review it, then \`everystack db:apply --plan ${out}\`.`);
       warn('Plans are ephemeral release artifacts — attach to the run, do NOT commit.');
+      // "Do NOT commit" is advice; git is what enforces it. The default lands in the app
+      // root, so an adopter following the happy path gets an untracked, unignored artifact
+      // sitting next to their source with only a log line between it and a `git add .`.
+      if (!isGitIgnored(out)) {
+        warn(`${out} is NOT gitignored — add it, or the next \`git add .\` commits the plan: echo '${out}' >> .gitignore`);
+      }
     }
   } finally {
     await end?.();

package/src/cli/commands/db-pull.ts

@@ -30,6 +30,9 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { introspectSchema, MATVIEW_COLUMNS_SQL, matviewColumnsByIdentity, type ColumnRow, type ColumnSchema } from '../schema-introspect.js';
+import { fingerprintLive } from '../schema-fingerprint.js';
+import { ungovernedGrants, ALWAYS_GOVERNED, type GrantExemption } from '../authz-reconcile.js';
+import { buildStageBaseline, mergeBaseline, readBaselineFile, writeBaselineFile, BASELINE_FILE } from '../authz-baseline.js';
 import { introspectDerived, type DerivedCatalog } from '../derived-introspect.js';
 import { introspectContract, type TableContract } from '../authz-contract.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
@@ -126,6 +129,9 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
 
   let current;
   let liveAuthz: Map<string, TableContract> | undefined;
+  /** Adoption observation — the foreign grantees present, and what the claim is true OF. */
+  let pulledExemptions: GrantExemption[] = [];
+  let pulledFingerprint = '';
   let derivedCatalog: DerivedCatalog | undefined;
   let matviewColumns: Map<string, ColumnSchema[]> | undefined;
   let candidatesByIdentity: Map<string, string[]> | undefined;
@@ -167,6 +173,17 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
         note(`Grants exist for ${[...unmapped].sort().join(', ')} — not rendered: abilities name the roles the model knows (anon/authenticated/admin).`);
         detail(`These are left exactly as they are in the database. Add can(..., { role }) only if you want the models to own them.`);
       }
+      // ADOPTION: record the foreign grantees that were already here, per stage. The
+      // reconciler exempts them from revocation, so this artifact is what stops that
+      // exemption becoming permanent and silent — anything NEW, or anything that has since
+      // grown, refuses at db:plan. It lands as a reviewable diff, with writes flagged,
+      // because nothing mechanical can tell a legitimate BI role from an attacker's on day
+      // one; the defence is forcing the look and making it recur.
+      // The governed set at ADOPTION is the fixed vocabulary alone: the models being
+      // rendered here can only name anon/authenticated/admin, so every other grantee is
+      // foreign by construction — the same set `unmapped` just reported, with privileges.
+      pulledExemptions = ungovernedGrants(contract, new Set(ALWAYS_GOVERNED));
+      pulledFingerprint = fingerprintLive(current, contract).hash;
     }
     // --matviews-as-tables: the flip needs real fields — one extra catalog read for the
     // matview columns the derived layer (definition-only) doesn't carry.
@@ -299,5 +316,28 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
   } else {
     note(`Stamped '${abilities}' abilities into every model — review the generated stanzas; they are code, not defaults.`);
   }
+
+  // The adoption baseline. Only under --abilities live (it is an OBSERVATION of the live
+  // grants, so there is nothing to record without having read them) and only for a named
+  // stage, because the gate is per-stage: a production entry must not excuse the same role
+  // in dev. Written even when EMPTY — an empty baseline for a stage is a real, reviewed
+  // claim ("this stage had no foreign grantees"), and it is what makes a later arrival fail.
+  if (abilities === 'live') {
+    const stageName = flags.stage;
+    if (!stageName) {
+      note(`No --stage, so ${BASELINE_FILE} was not written. The foreign grantees above are recorded per stage; re-run with --stage <name> to adopt them, or db:plan will refuse until you do.`);
+    } else {
+      const entry = buildStageBaseline(pulledExemptions, { observedAt: new Date().toISOString(), fingerprint: pulledFingerprint });
+      const merged = mergeBaseline(await readBaselineFile(), stageName, entry);
+      const written = await writeBaselineFile(merged);
+      const names = Object.keys(entry.grantees);
+      const writers = names.filter((n) => entry.grantees[n].write);
+      ok(`Wrote ${path.relative(process.cwd(), written)} — ${names.length} foreign grantee(s) recorded for stage '${stageName}'.`);
+      if (writers.length) {
+        caution(`${writers.length} of them hold WRITE privileges: ${writers.join(', ')}. Review the diff before committing — this is the moment those roles get looked at.`);
+      }
+      note(`Committing this file ADOPTS those roles. Anything not in it — or anything that grows beyond it — refuses at db:plan.`);
+    }
+  }
   process.exit(0);
 }

package/src/cli/commands/db-sync.ts

@@ -75,6 +75,9 @@ export interface SyncOptions {
   declared?: SourceObject[];
   /** Standalone sequences the modules declare (state — created before tables, fingerprinted). */
   sequences?: SequenceDescriptor[];
+  /** Roles the modules govern beyond the ones the models name — a grantee outside the set
+   *  is exempted from revocation and enumerated instead (authz-reconcile's governedRoleSet). */
+  governedRoles?: string[];
   /** Pending table renames — trigger provenance migrates instead of drop+create. */
   renamedTables?: Record<string, string>;
   /** Injectable clock for tests. */
@@ -118,6 +121,7 @@ export async function executeSync(
   const liveAuthz = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
   const statements = generateMigrationSql(models, current, {
     allowDrops: options.allowDrops, liveAuthz, sequences: options.sequences,
+    governedRoles: options.governedRoles,
   });
   hooks.onStatePlan?.(statements, classifyGeneratedStatements(statements));
 

package/src/cli/declared-derived.ts

@@ -12,6 +12,7 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 import { pathToFileURL } from 'node:url';
 import type { Module, ModelDescriptor, SequenceDescriptor, DerivedDescriptor } from '@everystack/model';
+import { moduleGovernedRoles } from '@everystack/model';
 import { compileDerived } from './derived-compile.js';
 import { compileTableRenames, compileTableMoves } from './schema-compile.js';
 import type { SourceObject } from './derived-source.js';
@@ -30,6 +31,9 @@ export interface DeclaredDerived {
   /** The models the modules compose — db:check's split-brain gate compares these against
    *  the barrel's `export const models` (the array every verb's state stream reads). */
   models: ModelDescriptor[];
+  /** Roles the modules declare as governed beyond the ones the models name. A live grantee
+   *  outside the governed set is exempted from reconciliation and ENUMERATED instead. */
+  governedRoles: string[];
 }
 
 /**
@@ -64,7 +68,7 @@ export async function loadModulesFrom(modelsPath: string): Promise<Module[]> {
     const models = mod.models ?? mod.default;
     if (Array.isArray(models)) {
       assertNoHoles(modelsPath, 'models', models);
-      return [{ models, extensions: [], sequences: [], derived: [], functions: [] }];
+      return [{ models, extensions: [], sequences: [], derived: [], governedRoles: [], functions: [] }];
     }
     throw new Error(`${modelsPath} must export a \`modules\` (or \`models\`) array.`);
   } catch (err) {
@@ -173,6 +177,7 @@ export function composeDeclaredDerived(modules: Module[], modelsPath: string): D
       // ... SET SCHEMA alike, so the trigger-provenance migration is identical — feed both.
       renamedTables: { ...compileTableRenames(models, {}), ...compileTableMoves(models, {}) },
       models,
+      governedRoles: moduleGovernedRoles(modules),
     };
   } catch (err) {
     throw asModelComposeError(modelsPath, err);