@everystack/cli 0.2.37 → 0.3.0

package/src/cli/commands/security.ts

@@ -0,0 +1,185 @@
+/**
+ * `everystack security:audit` — the gate behind the two-surface security model.
+ *
+ * Goes RED (non-zero exit) on any data-returning SECURITY DEFINER function or any
+ * public view that exposes a non-public column, so CI fails before the leak ships.
+ * Two instruments over one classifier:
+ *
+ *   everystack security:audit                 static scan of migration SQL (pre-merge)
+ *   everystack security:audit --stage <name>  live catalog scan of a deployed stage
+ *
+ * See docs/security.md ("Auditing the surface") and docs/plans/nothing-skips-rls.md.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  audit,
+  parseFunctionsFromSql,
+  parseViewsAndGrantsFromSql,
+  type Waivers,
+  type AuditReport,
+  type FunctionDescriptor,
+  type ViewDescriptor,
+} from '../security-audit.js';
+import {
+  FUNCTIONS_SQL,
+  RELATIONS_SQL,
+  catalogFunctionToDescriptor,
+  catalogRelationToDescriptor,
+} from '../security-catalog.js';
+import { resolveConfig, opsFunction } from '../config.js';
+import { invokeAction } from '../aws.js';
+import { step, success, fail, info, warn } from '../output.js';
+
+const MIGRATION_DIRS = ['drizzle', 'db/migrations', 'migrations', 'db/drizzle'];
+const WAIVER_FILES = ['security-audit.json', '.security-audit.json'];
+
+export async function securityAuditCommand(flags: Record<string, string>): Promise<void> {
+  const waivers = await loadWaivers(flags.config);
+
+  const useCatalog = flags.catalog === 'true' || typeof flags.stage === 'string';
+
+  let report: AuditReport;
+  try {
+    report = useCatalog
+      ? await runCatalogAudit(flags, waivers)
+      : await runStaticAudit(flags, waivers);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  printReport(report, useCatalog ? 'catalog' : 'static');
+  process.exit(report.red > 0 ? 1 : 0);
+}
+
+// ---------------------------------------------------------------------------
+// Static instrument — parse migration SQL, no database.
+// ---------------------------------------------------------------------------
+
+async function runStaticAudit(flags: Record<string, string>, waivers: Waivers): Promise<AuditReport> {
+  const dir = await resolveMigrationDir(flags.dir);
+  step(`Scanning migration SQL in ${dir} ...`);
+
+  const entries = (await fs.readdir(dir)).filter((f) => f.endsWith('.sql')).sort();
+  if (entries.length === 0) {
+    throw new Error(`No .sql files found in ${dir}. Pass --dir <path> to point at your migrations.`);
+  }
+
+  let sql = '';
+  for (const entry of entries) {
+    sql += '\n' + (await fs.readFile(path.join(dir, entry), 'utf8'));
+  }
+
+  const functions = parseFunctionsFromSql(sql);
+  const views = parseViewsAndGrantsFromSql(sql);
+  info(`Found ${functions.length} function(s), ${views.length} view(s) across ${entries.length} migration file(s).`);
+  return audit(functions, views, waivers);
+}
+
+async function resolveMigrationDir(flag?: string): Promise<string> {
+  if (flag) {
+    const abs = path.resolve(flag);
+    await fs.access(abs);
+    return abs;
+  }
+  for (const candidate of MIGRATION_DIRS) {
+    const abs = path.resolve(candidate);
+    try {
+      const stat = await fs.stat(abs);
+      if (stat.isDirectory()) return abs;
+    } catch {
+      // try next
+    }
+  }
+  throw new Error(`No migration directory found (looked for ${MIGRATION_DIRS.join(', ')}). Pass --dir <path>.`);
+}
+
+// ---------------------------------------------------------------------------
+// Catalog instrument — introspect the live database via the ops Lambda.
+// ---------------------------------------------------------------------------
+
+async function runCatalogAudit(flags: Record<string, string>, waivers: Waivers): Promise<AuditReport> {
+  step('Resolving deployed config...');
+  const config = await resolveConfig(flags.stage);
+  info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+
+  step('Introspecting database catalog (functions + relations)...');
+  const fnRows = await catalogQuery(config.region, opsFunction(config), FUNCTIONS_SQL);
+  const relRows = await catalogQuery(config.region, opsFunction(config), RELATIONS_SQL);
+
+  const functions: FunctionDescriptor[] = fnRows.map(catalogFunctionToDescriptor);
+  const views: ViewDescriptor[] = relRows.map(catalogRelationToDescriptor);
+  info(`Catalog: ${functions.length} function(s), ${views.length} relation(s).`);
+  return audit(functions, views, waivers);
+}
+
+async function catalogQuery(region: string, fn: string, sql: string): Promise<any[]> {
+  const result: any = await invokeAction(region, fn, 'db:query', { sql });
+  if (result?.error) throw new Error(`Catalog query failed: ${result.error}`);
+  return result?.rows ?? [];
+}
+
+// ---------------------------------------------------------------------------
+// Waivers + reporting.
+// ---------------------------------------------------------------------------
+
+async function loadWaivers(flag?: string): Promise<Waivers> {
+  const candidates = flag ? [flag] : WAIVER_FILES;
+  for (const candidate of candidates) {
+    const abs = path.resolve(candidate);
+    try {
+      const raw = await fs.readFile(abs, 'utf8');
+      const parsed = JSON.parse(raw);
+      info(`Loaded waivers from ${candidate}.`);
+      return { secdef: parsed.secdef ?? {}, publicColumns: parsed.publicColumns ?? {} };
+    } catch (err: any) {
+      if (err.code !== 'ENOENT') throw new Error(`Could not read waiver config ${candidate}: ${err.message}`);
+    }
+  }
+  return {};
+}
+
+function printReport(report: AuditReport, instrument: 'static' | 'catalog'): void {
+  const reds = [
+    ...report.functions.filter((f) => f.severity === 'red'),
+    ...report.views.filter((v) => v.severity === 'red'),
+  ];
+  const warns = [
+    ...report.functions.filter((f) => f.severity === 'warn'),
+    ...report.views.filter((v) => v.severity === 'warn'),
+  ];
+  const waived = report.functions.filter((f) => f.waived);
+
+  if (reds.length > 0) {
+    console.log('');
+    info('RED — must fix or waive with justification:');
+    for (const f of reds) {
+      fail(`${f.key}`);
+      for (const r of f.reasons) info(`    ${r}`);
+    }
+  }
+
+  if (warns.length > 0) {
+    console.log('');
+    info('WARN — review (does not fail the build):');
+    for (const f of warns) {
+      warn(`${f.key}`);
+      for (const r of f.reasons) info(`    ${r}`);
+    }
+  }
+
+  if (waived.length > 0) {
+    console.log('');
+    info(`Waived (${waived.length}): ${waived.map((f) => f.key).join(', ')}`);
+  }
+
+  console.log('');
+  const summary = `security:audit (${instrument}) — ${report.red} red, ${report.warn} warn`;
+  if (report.red > 0) {
+    fail(summary);
+  } else {
+    success(summary);
+  }
+}

package/src/cli/config.ts

@@ -24,6 +24,10 @@ export interface CliConfig {
   mediaBucket?: string;
   kvsArn?: string;
   distributionId?: string;
+  /** RDS DB instance identifier (for db:snapshot). Absent when the DB isn't RDS or in dev mode. */
+  databaseInstanceId?: string;
+  /** Private S3 bucket holding logical backups (for db:backup:download presign). */
+  backupsBucket?: string;
 }
 
 /** Operator invoke target — dedicated ops function when deployed, else the API function. */
@@ -44,6 +48,8 @@ interface SstOutputs {
   mediaBucket?: string;
   kvsArn?: string;
   distributionId?: string;
+  databaseInstanceId?: string;
+  backupsBucket?: string;
 }
 
 export async function resolveConfig(stage?: string): Promise<CliConfig> {
@@ -115,5 +121,7 @@ export async function resolveConfig(stage?: string): Promise<CliConfig> {
     mediaBucket: outputs.mediaBucket,
     kvsArn: outputs.kvsArn,
     distributionId: outputs.distributionId,
+    databaseInstanceId: outputs.databaseInstanceId,
+    backupsBucket: outputs.backupsBucket,
   };
 }

package/src/cli/index.ts

@@ -3,10 +3,16 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { updateCommand } from './commands/update.js';
+import { deployCommand } from './commands/deploy.js';
 import { certsCommand } from './commands/certs.js';
 import { channelsCommand } from './commands/channels.js';
 import { branchesCommand } from './commands/branches.js';
-import { dbMigrateCommand, dbSeedCommand, dbResetCommand, dbPsqlCommand } from './commands/db.js';
+import { dbMigrateCommand, dbSeedCommand, dbResetCommand, dbPsqlCommand, dbDoctorCommand, dbProvisionCommand } from './commands/db.js';
+import { dbAuthzPullCommand, dbAuthzDiffCommand, dbAuthzTestCommand, dbAuthzOwnerCommand, dbAuthzReportCommand } from './commands/db-authz.js';
+import { dbGenerateCommand } from './commands/db-generate.js';
+import { dbPullCommand } from './commands/db-pull.js';
+import { dbSnapshotCommand, dbSnapshotsCommand } from './commands/db-snapshot.js';
+import { dbBackupProbeCommand, dbBackupCommand, dbBackupsCommand, dbRestoreCommand, dbBackupDownloadCommand } from './commands/db-backup.js';
 import { consoleCommand } from './commands/console.js';
 import { cachePurgeCommand } from './commands/cache.js';
 import { statusCommand } from './commands/status.js';
@@ -14,6 +20,7 @@ import { diagCommand } from './commands/diag.js';
 import { analyzeSSRCommand } from './commands/analyze.js';
 import { logsErrorsCommand, logsTailCommand, logsQueryCommand } from './commands/logs.js';
 import { secretsCommand } from './commands/secrets.js';
+import { securityAuditCommand } from './commands/security.js';
 import { fail } from './output.js';
 
 const args = process.argv.slice(2);
@@ -90,6 +97,9 @@ async function main() {
     case 'update':
       await updateCommand(flags);
       break;
+    case 'deploy':
+      await deployCommand(flags);
+      break;
     case 'certs:generate':
       await certsCommand('generate', flags);
       break;
@@ -114,6 +124,56 @@ async function main() {
     case 'db:psql':
       await dbPsqlCommand(flags);
       break;
+    case 'db:doctor':
+      await dbDoctorCommand(flags);
+      break;
+    case 'db:provision':
+      await dbProvisionCommand(flags);
+      break;
+    case 'db:snapshot':
+      await dbSnapshotCommand(flags);
+      break;
+    case 'db:snapshots':
+      await dbSnapshotsCommand(flags);
+      break;
+    case 'db:backup:probe':
+      await dbBackupProbeCommand(flags);
+      break;
+    case 'db:backup':
+      await dbBackupCommand(flags);
+      break;
+    case 'db:backups':
+      await dbBackupsCommand(flags);
+      break;
+    case 'db:restore':
+      await dbRestoreCommand(flags);
+      break;
+    case 'db:backup:download': {
+      const backupId = args[1] && !args[1].startsWith('--') ? args[1] : undefined;
+      await dbBackupDownloadCommand(flags, backupId);
+      break;
+    }
+    case 'db:generate':
+      await dbGenerateCommand(flags);
+      break;
+    case 'db:pull':
+      await dbPullCommand(flags);
+      break;
+    case 'db:authz:pull':
+      await dbAuthzPullCommand(flags);
+      break;
+    case 'db:authz:diff':
+      await dbAuthzDiffCommand(flags);
+      break;
+    case 'db:authz:test':
+      await dbAuthzTestCommand(flags);
+      break;
+    case 'db:authz:owner':
+      await dbAuthzOwnerCommand(flags);
+      break;
+    case 'db:authz:report':
+      await dbAuthzReportCommand(flags);
+      break;
     case 'console':
       await consoleCommand(flags);
       break;
@@ -143,6 +203,9 @@ async function main() {
     case 'logs:query':
       await logsQueryCommand(flags);
       break;
+    case 'security:audit':
+      await securityAuditCommand(flags);
+      break;
     case 'secrets': {
       // secrets <subcommand> [positional...] [--flags]
       // Extract positional args: everything after subcommand that isn't a flag or flag value
@@ -171,14 +234,34 @@ function printHelp() {
 everystack - CLI for Expo apps on everystack
 
 Usage:
+  everystack deploy            [--stage <name>]  Deploy infrastructure (wraps sst deploy — no need to know SST)
   everystack update            --branch <name> --message <msg> [--platform ios|android|web|all] [--stage <name>] [--skip-export]
   everystack update            --channel <name> --message <msg> [--platform ios|android|web|all] [--stage <name>] [--skip-export]
   everystack db:migrate        [--stage <name>]  Run database migrations on deployed Lambda
   everystack db:seed           [--stage <name>]  Seed database on deployed Lambda (dev only)
   everystack db:reset          [--stage <name>]  Drop all schemas + re-run migrations (dev only)
-  everystack db:psql           [--stage <name>] -c <command>  Execute SQL query via Lambda (private RDS)
+  everystack db:psql           --stage <name>  Interactive ADMIN psql (IAM-gated; resolves the admin URL in-process)
+  everystack db:psql           [--stage <name>] -c <command>  Run one query via Lambda (works for private RDS)
+  everystack db:doctor         [--stage <name>]  Check the DB is least-privilege + RLS-subject (api vs operator connection)
+  everystack db:provision      [--stage <name>]  Create the least-privilege role chain on an EXISTING database (idempotent; creates no DB)
+  everystack db:snapshot       [--stage <name>] [--instance <id>]  Take a physical RDS snapshot (instant DR point; RDS only — use db:backup for portable logical backups)
+  everystack db:snapshots      [--stage <name>] [--instance <id>]  List manual RDS snapshots for the instance
+  everystack db:backup:probe   [--stage <name>]  Verify the pg_dump layer is attached + version-compatible with the server
+  everystack db:backup         [--stage <name>]  Logical pg_dump of the DB → private S3 backups bucket (prints the backup id)
+  everystack db:backups        [--stage <name>]  List logical backups (id, size, created)
+  everystack db:restore        --from <id> [--stage <name>] --confirm  Restore a backup INTO the stage's DB (DESTRUCTIVE)
+  everystack db:backup:download <id> [--stage <name>]  Presigned URL to download a backup's dump (valid 1h)
+  everystack db:generate       [--stage <name>] [--name <label>] [--models models/index.ts] [--allow-drops]  Diff models vs the live DB → write the next migration (never touches the DB; DROPs held back unless --allow-drops)
+  everystack db:pull           [--stage <name>] [--schema public] [--out <file>]  Introspect the live DB → render field() Models (the brownfield on-ramp; stdout unless --out)
+  everystack db:authz:pull     [--stage <name>] [--dir authz]  Introspect live authz (rls/grants/policies/secdef) → reviewable contract files
+  everystack db:authz:diff     [--stage <name>] [--dir authz]  Validate the live DB against the committed contract (non-zero exit on drift)
+  everystack db:authz:test     [--stage <name>] [--dir authz]  Red-team enforcement: SET ROLE + attempt per role/table/command (non-zero exit on a hole)
+  everystack db:authz:owner    [--stage <name>] [--models models/index.ts]  Red-team owner isolation: two JWT identities per owner-scoped table — catches IDOR (non-zero exit on a leak)
+  everystack db:authz:report   [--dir authz]  Render the committed contract as a human-readable authorization review (no DB)
   everystack console           --stage <name> [--sandbox]  Interactive REPL on deployed Lambda
   everystack status            [--stage <name>] [--hours <n>]  Platform health: CDN, Lambda, rollup summary
+  everystack security:audit    [--dir <path>] [--config <file>]  Static scan of migration SQL (pre-merge gate)
+  everystack security:audit    --stage <name> [--config <file>]  Live catalog scan of a deployed stage (post-deploy)
   everystack certs:generate    [--output ./certs]
   everystack certs:configure   [--input ./certs] [--keyid main]
   everystack cache:purge       [--stage <name>]                  Bust all cached content (global epoch)

package/src/cli/migration-compile.ts

@@ -0,0 +1,69 @@
+/**
+ * The one generator — compose the Model into a single ordered migration.
+ *
+ * This is the unified-migration thesis made concrete: a set of Models compiles to
+ * ONE ordered list of SQL statements covering *both* layers, in dependency order:
+ *
+ *   1. CREATE TABLE …            (data — fields → DDL + CHECK)
+ *   2. ALTER TABLE … FOREIGN KEY (data — references, after every table exists)
+ *   3. ENABLE/FORCE RLS · policies · grants   (authz — abilities, after the
+ *                                              columns they reference exist)
+ *
+ * It is not two pipelines: the authz statements reference columns the DDL just
+ * created, so they live in the same ordered migration. This composes the four
+ * compilers already built — compileCreateTable + foreignKeySql (data) and
+ * compileTableContract + emitReconcileSql (authz) — with no new SQL emission.
+ *
+ * This is the greenfield form (empty database → the whole schema). The brownfield
+ * form diffs against an introspected snapshot instead of the empty baseline; that
+ * lands with whole-DB introspection. The emission is identical either way.
+ */
+
+import type { ModelDescriptor } from '@everystack/model';
+import type { AuthzContract, TableContract } from './authz-contract.js';
+import { compileCreateTable, compileEnums, foreignKeySql, modelConstraintSpecs, type CompileTableOptions } from './schema-compile.js';
+import { compileTableContract } from './authz-compile.js';
+import { emitReconcileSql } from './authz-reconcile.js';
+import { emitSchemaSql, type SchemaChange } from './schema-diff.js';
+
+/** The empty (not-yet-created) authz state for a table — the greenfield baseline. */
+function emptyTable(table: string): TableContract {
+  return { table, rls: { enabled: false, forced: false }, grants: {}, policies: [] };
+}
+
+/**
+ * Compile a set of Models into one ordered migration (greenfield: empty DB → full
+ * schema). Tables, then foreign keys, then authz — the order a fresh database must
+ * apply them in.
+ */
+export function compileMigration(models: ModelDescriptor[], opts: CompileTableOptions = {}): string[] {
+  const sql: string[] = [];
+
+  // 0. Enum types — `CREATE TYPE … AS ENUM`, before any table/column references them.
+  const enumCreates: SchemaChange[] = compileEnums(models).map((e) => ({ kind: 'createType', name: e.name, values: e.values }));
+  sql.push(...emitSchemaSql(enumCreates));
+
+  // 1. Tables (with columns, CHECKs, single/composite PK, uniques).
+  for (const model of models) sql.push(compileCreateTable(model, opts));
+
+  // 2. Foreign keys — after every table exists.
+  for (const model of models) sql.push(...foreignKeySql(model));
+
+  // 2b. Standalone indexes — after the columns they cover exist.
+  const indexCreates: SchemaChange[] = [];
+  for (const model of models) {
+    for (const ix of modelConstraintSpecs(model).indexes) {
+      indexCreates.push({ kind: 'createIndex', table: `"${model.table}"`, name: ix.name, columns: ix.columns, unique: ix.unique, ...(ix.where ? { where: ix.where } : {}) });
+    }
+  }
+  sql.push(...emitSchemaSql(indexCreates));
+
+  // 3. Authz — RLS + policies + grants, after the columns they reference. Reuse
+  //    the reconcile emitter against the empty baseline: every policy/grant is a
+  //    pure creation, in the same dependency-correct order reconcile already uses.
+  const desired: AuthzContract = { tables: models.map((m) => compileTableContract(m)), functions: [] };
+  const baseline: AuthzContract = { tables: models.map((m) => emptyTable(`public.${m.table}`)), functions: [] };
+  sql.push(...emitReconcileSql(desired, baseline));
+
+  return sql;
+}

package/src/cli/migration-generate.ts

@@ -0,0 +1,175 @@
+/**
+ * `db:generate`'s pure core — Models + live snapshot → a migration file.
+ *
+ * The brownfield generator, composed from the pieces already built and proven:
+ *
+ *   compileTableSchema + compileRenames (the desired side, from the Models)
+ *     → diffSchema (vs the introspected `current`)
+ *     → emitSchemaSql (the ALTER/CREATE/RENAME DDL)
+ *
+ * A whole *new* table renders through the greenfield `compileCreateTable` (byte-identical
+ * to what the app ships) rather than the IR renderer; its foreign keys still arrive as the
+ * diff's `addConstraint` changes, so they land after every table exists.
+ *
+ * Everything here is pure and deterministic — the clock (`when`) is injected, never read —
+ * so the command shell (commands/db-generate.ts) is a thin layer of IO over it.
+ */
+
+import type { ModelDescriptor } from '@everystack/model';
+import type { SchemaSnapshot } from './schema-introspect.js';
+import type { AuthzContract } from './authz-contract.js';
+import { compileTableSchema, compileRenames, compileCreateTable, compileEnums } from './schema-compile.js';
+import { compileTableContract } from './authz-compile.js';
+import { emitReconcileSql } from './authz-reconcile.js';
+import { diffSchema, emitSchemaSql, type SchemaChange } from './schema-diff.js';
+
+export interface GenerateOptions {
+  /** The Postgres schema the Models live in. Default: `public`. */
+  schema?: string;
+  /**
+   * Emit real `DROP COLUMN`/`DROP CONSTRAINT`/`DROP TABLE` for things present in the
+   * database but absent from the Models. Default `false` — those are held back as
+   * commented notices (see {@link HELD_DROP_PREFIX}), so a partial or lossy Model set
+   * never silently loses data. Destruction needs intent, the same rule renames are built on.
+   */
+  allowDrops?: boolean;
+  /**
+   * The live authorization contract (`introspectContract`). When provided, the migration
+   * carries the authz layer too — the Models' `abilities` compiled to RLS/policies/grants,
+   * diffed against this live state, appended after the data phase as one ordered file (the
+   * unified-migration thesis: declare once, generate both layers). Omitted → data-only, the
+   * backward-compatible default. Authz drops (`DROP POLICY`/`REVOKE`) are data-safe, so they
+   * are emitted regardless of `allowDrops` — `allowDrops` gates only data destruction.
+   */
+  liveAuthz?: AuthzContract;
+}
+
+/** The comment prefix a held-back destructive change carries (the command greps it to count them). */
+export const HELD_DROP_PREFIX = '-- DROP held back';
+
+/**
+ * A destructive change that removes data or an integrity guard with no re-creation —
+ * the set held back unless `allowDrops`. A constraint *replace* (a `dropConstraint`
+ * paired with an `addConstraint` of the same name) is NOT a removal: it loses no data
+ * and its add depends on the drop, so it is kept intact.
+ */
+function isRemoval(change: SchemaChange, replacedConstraints: Set<string>): boolean {
+  if (change.kind === 'dropColumn' || change.kind === 'dropTable' || change.kind === 'dropType' || change.kind === 'dropIndex') return true;
+  if (change.kind === 'dropConstraint') return !replacedConstraints.has(`${change.table}::${change.name}`);
+  return false;
+}
+
+/** Comment out a destructive statement, showing the exact DDL to run by hand or with `--allow-drops`. */
+function holdDrop(sql: string): string {
+  return `${HELD_DROP_PREFIX} (destructive — re-run db:generate with --allow-drops to emit it, or run it by hand):\n-- ${sql}`;
+}
+
+/**
+ * Tables present in the live database that no model declares. `db:generate` leaves these
+ * untouched — they belong to another concern (auth, jobs, observability all ship their own
+ * migrations), and dropping a table must be deliberate, never a side effect of a missing
+ * model. The command reports the count so the omission is visible, not silent.
+ */
+export function unmodeledTables(models: ModelDescriptor[], current: SchemaSnapshot, opts: GenerateOptions = {}): string[] {
+  const schema = opts.schema ?? 'public';
+  const declared = new Set(models.map((m) => `${schema}.${m.table}`));
+  return current.tables.map((t) => t.table).filter((t) => !declared.has(t)).sort();
+}
+
+/**
+ * Compile the Models into the ordered SQL that evolves `current` to match them. Empty when
+ * the database already matches (the no-op generate).
+ *
+ * Scoped to the tables the models DECLARE: the diff never sees a table no model owns, so it
+ * cannot propose dropping one. db:generate manages your declared schema; everything else in
+ * the database (auth, jobs, observability) is left to its own migrations.
+ */
+export function generateMigrationSql(models: ModelDescriptor[], current: SchemaSnapshot, opts: GenerateOptions = {}): string[] {
+  const schema = opts.schema ?? 'public';
+  const desiredEnums = compileEnums(models);
+  const desired: SchemaSnapshot = { tables: models.map((m) => compileTableSchema(m, { schema })), enums: desiredEnums };
+  const declaredTables = new Set(desired.tables.map((t) => t.table));
+  const declaredEnums = new Set(desiredEnums.map((e) => e.name));
+  // Scope both tables and enums to what the Models declare — an undeclared table OR enum
+  // (auth, jobs, observability ship their own) is invisible to the diff, so it is never dropped.
+  const scopedCurrent: SchemaSnapshot = {
+    tables: current.tables.filter((t) => declaredTables.has(t.table)),
+    enums: (current.enums ?? []).filter((e) => declaredEnums.has(e.name)),
+  };
+  const renames = compileRenames(models, { schema });
+  const changes = diffSchema(desired, scopedCurrent, renames);
+
+  const modelByTable = new Map(models.map((m) => [`${schema}.${m.table}`, m]));
+  const emitted = emitSchemaSql(changes, {
+    createTable: (change) => {
+      const model = modelByTable.get(change.table);
+      if (!model) throw new Error(`db:generate: no model found for new table ${change.table}`);
+      return compileCreateTable(model);
+    },
+  });
+
+  // Non-destructive by default: a column/constraint/table in the database but absent
+  // from the Models would otherwise become a DROP — silent data loss for a partial or
+  // lossy Model set. Hold removals back as comments unless `allowDrops`. emitSchemaSql
+  // returns one statement per change, index-aligned, so the gate stays a pure
+  // post-pass — `diffSchema`/`emitSchemaSql` remain honest (they always emit the DROP).
+  let dataPhase = emitted;
+  if (!opts.allowDrops) {
+    const replacedConstraints = new Set(
+      changes
+        .filter((c): c is Extract<SchemaChange, { kind: 'addConstraint' }> => c.kind === 'addConstraint')
+        .map((c) => `${c.table}::${c.constraint.name}`),
+    );
+    dataPhase = emitted.map((sql, i) => (isRemoval(changes[i], replacedConstraints) ? holdDrop(sql) : sql));
+  }
+
+  // Authz phase — appended after the data phase so a policy/grant references columns the
+  // data DDL just created. Emitted only when the live contract is supplied; the Models'
+  // `abilities` compile to the same contract shape introspection reads, so the two diff.
+  // Authz changes are data-safe (no row touches), so they are never held by `allowDrops`.
+  const authzPhase = opts.liveAuthz
+    ? emitReconcileSql({ tables: models.map((m) => compileTableContract(m, { schema })), functions: [] }, opts.liveAuthz)
+    : [];
+
+  return [...dataPhase, ...authzPhase];
+}
+
+/** The marker drizzle migration files put between statements. */
+const BREAKPOINT = '\n--> statement-breakpoint\n';
+
+/** Join statements into a drizzle-compatible migration file body (trailing newline). */
+export function formatMigrationFile(statements: string[]): string {
+  return statements.join(BREAKPOINT) + '\n';
+}
+
+export interface JournalEntry {
+  idx: number;
+  version: string;
+  when: number;
+  tag: string;
+  breakpoints: boolean;
+}
+
+export interface Journal {
+  version: string;
+  dialect: string;
+  entries: JournalEntry[];
+}
+
+/** Sanitize a migration name into the snake_case the `NNNN_<tag>.sql` convention uses. */
+function sanitizeName(name: string): string {
+  return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'generated';
+}
+
+/**
+ * Plan the next migration file: its tag, filename, and the journal with the new entry
+ * appended. Pure — `when` is passed in (the command stamps it with the clock), so the same
+ * inputs always produce the same plan. The next index is one past the highest existing
+ * `idx`, matching how the runner and drizzle order migrations.
+ */
+export function planMigrationFile(journal: Journal, name: string, when: number): { tag: string; filename: string; journal: Journal } {
+  const idx = journal.entries.reduce((max, e) => Math.max(max, e.idx + 1), 0);
+  const tag = `${String(idx).padStart(4, '0')}_${sanitizeName(name)}`;
+  const entry: JournalEntry = { idx, version: journal.version || '7', when, tag, breakpoints: true };
+  return { tag, filename: `${tag}.sql`, journal: { ...journal, entries: [...journal.entries, entry] } };
+}

package/src/cli/model-api.ts

@@ -0,0 +1,35 @@
+/**
+ * `@everystack/cli/model` — the programmatic surface of the v3 Model generator and red-team.
+ *
+ * Everything the CLI commands do (`db:generate`, `db:pull`, `db:authz:*`) is pure logic over a
+ * `QueryRunner`; this barrel exposes it so a consumer can generate and VERIFY their schema in
+ * their own tests/CI without shelling out to the CLI. The reference app dogfoods exactly this
+ * surface — its real Models are round-tripped through `compileMigration` / `generateMigrationSql`
+ * and red-teamed with the owner probe, against a real Postgres, proving the generator on a real app.
+ *
+ * The two entry shapes:
+ *   - GENERATE: `compileMigration(models)` (greenfield) or `generateMigrationSql(models, snapshot,
+ *     { liveAuthz })` (brownfield, both layers) → ordered SQL.
+ *   - VERIFY: `introspectSchema(run)` / `introspectContract(run, …)` → diff against the Models, and
+ *     `buildOwnerProbeSql` / `evaluateOwnerProbe` for behavioural owner-isolation checks.
+ */
+
+// --- data layer: compile, introspect, diff, render -------------------------
+export * from './schema-compile.js';
+export * from './schema-introspect.js';
+export * from './schema-diff.js';
+export * from './model-render.js';
+export * from './migration-compile.js';
+export * from './migration-generate.js';
+
+// --- authz layer: contract compile/introspect/diff/reconcile ---------------
+export * from './authz-compile.js';
+export * from './authz-contract.js';
+export * from './authz-reconcile.js';
+
+// --- red-team: grant enforcement + owner isolation -------------------------
+export * from './authz-redteam.js';
+export * from './authz-owner-probe.js';
+
+// --- the SECDEF function catalog the contract introspection needs -----------
+export { FUNCTIONS_SQL, catalogFunctionToDescriptor } from './security-catalog.js';