@everystack/cli 0.2.39 → 0.3.3

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

@@ -0,0 +1,300 @@
+/**
+ * `everystack db:authz:pull` / `db:authz:diff` — the Authorization Contract commands.
+ *
+ *   db:authz:pull --stage <name>   introspect the live authz → write authz/*.contract.json
+ *   db:authz:diff --stage <name>   validate the live DB against the committed contract
+ *
+ * The contract is the brownfield slice of the Model (docs/plans/v3-authz-contract.md):
+ * authorization that lived only in scattered migrations becomes a reviewable file you
+ * can diff a deployed database against. `pull` is the export + on-ramp; `diff` is the
+ * audit and the CI gate (non-zero exit on any drift).
+ *
+ * Both introspect through the ops Lambda `db:query` action (read-only SQL), the same
+ * path security:audit uses. The core (introspect/assemble/diff) is backend-agnostic and
+ * pure; only the runner here is AWS-bound.
+ */
+
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { ModelDescriptor } from '@everystack/model';
+import {
+  introspectContract,
+  diffContracts,
+  type QueryRunner,
+  type AuthzContract,
+} from '../authz-contract.js';
+import {
+  buildProbeSql,
+  PROBE_SELECT_SQL,
+  probeRoles,
+  toProbeResult,
+  evaluateRedTeam,
+  GRANT_COMPLETENESS_SQL,
+  toGrantGap,
+} from '../authz-redteam.js';
+import {
+  buildOwnerProbeSql,
+  OWNER_PROBE_SELECT_SQL,
+  toOwnerProbeResult,
+  evaluateOwnerProbe,
+  type OwnerProbe,
+} from '../authz-owner-probe.js';
+import { modelOwner } from '../authz-compile.js';
+import { writeContract, loadContract } from '../authz-contract-io.js';
+import { renderContractMarkdown } from '../authz-render.js';
+import { FUNCTIONS_SQL, catalogFunctionToDescriptor } 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 DEFAULT_DIR = 'authz';
+
+/** Map a FUNCTIONS_SQL row to the minimal shape the contract records. */
+const mapFunctionRow = (row: any) => {
+  const d = catalogFunctionToDescriptor(row);
+  return {
+    schema: d.schema, name: d.name, securityDefiner: d.securityDefiner, hasSearchPath: d.hasSearchPath,
+    owner: d.owner, ownerBypassesRls: d.ownerBypassesRls,
+  };
+};
+
+/** A QueryRunner backed by the ops Lambda `db:query` action (read-only). */
+function lambdaRunner(region: string, fn: string): QueryRunner {
+  return async (sql: string) => {
+    const result: any = await invokeAction(region, fn, 'db:query', { sql });
+    if (result?.error) throw new Error(`Introspection query failed: ${result.error}`);
+    return result?.rows ?? [];
+  };
+}
+
+async function introspectStage(flags: Record<string, string>): Promise<AuthzContract> {
+  step('Resolving deployed config...');
+  const config = await resolveConfig(flags.stage);
+  info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+  step('Introspecting authorization (rls + grants + policies + secdef)...');
+  const runner = lambdaRunner(config.region, opsFunction(config));
+  return introspectContract(runner, mapFunctionRow, FUNCTIONS_SQL);
+}
+
+export async function dbAuthzPullCommand(flags: Record<string, string>): Promise<void> {
+  const dir = path.resolve(flags.dir || flags.out || DEFAULT_DIR);
+  let contract: AuthzContract;
+  try {
+    contract = await introspectStage(flags);
+  } catch (err: any) {
+    fail(err.message);
+    info('Ensure your IAM user/role has lambda:InvokeFunction permission.');
+    process.exit(1);
+  }
+
+  const files = await writeContract(dir, contract);
+  const policies = contract.tables.reduce((n, t) => n + t.policies.length, 0);
+  console.log('');
+  success(`Wrote ${files.length} file(s) to ${dir}`);
+  info(`${contract.tables.length} table(s), ${policies} policy(ies), ${contract.functions.length} SECDEF function(s).`);
+  console.log('');
+  warn('pull OVERWROTE the committed contract with the live state — `git diff` IS your drift report.');
+  warn('Do not run `db:authz:diff` to find drift right after a pull: it compares the live DB to what');
+  warn('you just wrote, so it is always clean. Review `git diff`, then commit only if the change is intended.');
+  info('Note: column exposure (hidden/protected) is handler-layer and not part of the DB pull.');
+  process.exit(0);
+}
+
+export async function dbAuthzDiffCommand(flags: Record<string, string>): Promise<void> {
+  const dir = path.resolve(flags.dir || flags.out || DEFAULT_DIR);
+
+  let declared: AuthzContract;
+  let live: AuthzContract;
+  try {
+    declared = await loadContract(dir);
+    live = await introspectStage(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  if (declared.tables.length === 0 && declared.functions.length === 0) {
+    fail(`No committed contract found in ${dir}. Run \`everystack db:authz:pull --stage <name>\` first.`);
+    process.exit(1);
+  }
+
+  const findings = diffContracts(declared, live);
+  console.log('');
+  if (findings.length === 0) {
+    success(`db:authz:diff — live database matches the declared contract (${declared.tables.length} tables)`);
+    process.exit(0);
+  }
+
+  fail(`db:authz:diff — ${findings.length} drift finding(s): the live database does NOT match the declared contract`);
+  console.log('');
+  for (const f of findings) {
+    warn(`[${f.kind}] ${f.subject} — ${f.detail}`);
+  }
+  console.log('');
+  info('Either the live DB drifted (reconcile it) or the change is intended (re-pull + commit the contract delta).');
+  process.exit(1);
+}
+
+export async function dbAuthzReportCommand(flags: Record<string, string>): Promise<void> {
+  const dir = path.resolve(flags.dir || flags.out || DEFAULT_DIR);
+  let contract: AuthzContract;
+  try {
+    contract = await loadContract(dir);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  if (contract.tables.length === 0) {
+    fail(`No committed contract found in ${dir}. Run \`everystack db:authz:pull --stage <name>\` first.`);
+    process.exit(1);
+  }
+  // Render from the committed contract — no database needed. Print to stdout so it can
+  // be piped or redirected; `pull` writes the same content to authz/AUTHORIZATION.md.
+  console.log(renderContractMarkdown(contract));
+  process.exit(0);
+}
+
+export async function dbAuthzTestCommand(flags: Record<string, string>): Promise<void> {
+  const dir = path.resolve(flags.dir || flags.out || DEFAULT_DIR);
+
+  let contract: AuthzContract;
+  try {
+    contract = await loadContract(dir);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  if (contract.tables.length === 0) {
+    fail(`No committed contract found in ${dir}. Run \`everystack db:authz:pull --stage <name>\` first.`);
+    process.exit(1);
+  }
+
+  let rows: any[];
+  let gapRows: any[];
+  try {
+    step('Resolving deployed config...');
+    const config = await resolveConfig(flags.stage);
+    const fn = opsFunction(config);
+    info(`Region: ${config.region}, Function: ${fn}`);
+    step('Red-teaming enforcement (SET ROLE + attempt per role/table/command, rolled back)...');
+    const setup = buildProbeSql(probeRoles(contract), contract.tables.map((t) => t.table));
+    const result: any = await invokeAction(config.region, fn, 'db:authz:probe', { setup, read: PROBE_SELECT_SQL });
+    if (result?.error) throw new Error(result.error);
+    rows = result?.rows ?? [];
+    step('Checking SECDEF grant-completeness (owner can EXECUTE every helper it calls)...');
+    const gc: any = await invokeAction(config.region, fn, 'db:query', { sql: GRANT_COMPLETENESS_SQL });
+    if (gc?.error) throw new Error(gc.error);
+    gapRows = gc?.rows ?? [];
+  } catch (err: any) {
+    fail(`db:authz:test failed: ${err.message}`);
+    info('Ensure the stage is deployed with @everystack/server >= the version that adds db:authz:probe.');
+    process.exit(1);
+  }
+
+  const findings = evaluateRedTeam(contract, rows.map(toProbeResult));
+  const holes = findings.filter((f) => f.severity === 'hole');
+  const broken = findings.filter((f) => f.severity === 'broken');
+  const unprobed = findings.filter((f) => f.severity === 'unprobed');
+  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)`);
+  if (unprobed.length) {
+    const roles = [...new Set(unprobed.map((f) => f.role))].join(', ');
+    info(`[unprobed] could not SET ROLE into: ${roles} — grant the operator membership to cover them.`);
+  }
+  console.log('');
+
+  if (holes.length === 0 && broken.length === 0 && gaps.length === 0) {
+    success(`db:authz:test — enforcement matches the contract (${contract.tables.length} tables probed, default-deny holds, SECDEF grants complete)`);
+    process.exit(0);
+  }
+  fail(`db:authz:test — ${holes.length} enforcement hole(s), ${broken.length} broken grant(s), ${gaps.length} SECDEF grant gap(s). The database does not enforce the contract.`);
+  process.exit(1);
+}
+
+/** Import the app's Model barrel and return its `models` array (runs under tsx, so TS imports work). */
+async function loadModels(modelsPath: string): Promise<ModelDescriptor[]> {
+  const abs = path.resolve(modelsPath);
+  let mod: any;
+  try {
+    mod = await import(pathToFileURL(abs).href);
+  } catch (err: any) {
+    throw new Error(`Could not load models from ${modelsPath}: ${err.message}`);
+  }
+  const models = mod.models ?? mod.default;
+  if (!Array.isArray(models)) throw new Error(`${modelsPath} must export a \`models\` array (got ${typeof models}).`);
+  return models;
+}
+
+/**
+ * `db:authz:owner` — the owner-aware red-team. Where `db:authz:test` proves grants (can a ROLE
+ * do a command), this proves ISOLATION: can one user read or mutate another user's row? It is
+ * Model-driven — every `can({ owner })` names the owner column — and discovers two real
+ * identities from the data, so it needs no fixtures. For each owner-scoped table it checks that
+ * the owner sees their own rows (the anti-vacuous twin), the other identity's rows stay hidden,
+ * and an UPDATE can't touch them. Reuses the self-reverting `db:authz:probe` runner. Non-zero
+ * exit on any leak or vacuous policy; an `unprobed` table (one identity) is a warning, not a fail.
+ */
+export async function dbAuthzOwnerCommand(flags: Record<string, string>): Promise<void> {
+  const modelsPath = flags.models || 'models/index.ts';
+  const schema = flags.schema || 'public';
+
+  let probes: OwnerProbe[];
+  let publicReadTables = new Set<string>();
+  let rows: any[];
+  try {
+    step(`Loading models from ${modelsPath}...`);
+    const models = await loadModels(modelsPath);
+    const ownerModels = models
+      .map((m) => ({ m, owner: modelOwner(m, { schema }) }))
+      .filter((x): x is { m: (typeof models)[number]; owner: NonNullable<typeof x.owner> } => x.owner !== null);
+    // A table with a public read (`can('read')`, no owner/role/via) is intentionally not
+    // reader-isolated — flag it so the probe reports its cross-owner reads as expected, not IDOR.
+    const isPublicRead = (m: (typeof models)[number]): boolean =>
+      m.abilities.some((a) => a.action === 'read' && !a.condition.role && !a.condition.owner && !a.condition.via);
+    publicReadTables = new Set(ownerModels.filter(({ m }) => isPublicRead(m)).map(({ owner }) => owner.table));
+    probes = ownerModels.map(({ owner }) => ({ table: owner.table, ownerColumn: owner.ownerColumn, claim: owner.claim }));
+    info(`${probes.length} owner-scoped model(s).`);
+    if (probes.length === 0) {
+      success('db:authz:owner — no owner-scoped models (no `can({ owner })`); nothing to probe.');
+      process.exit(0);
+    }
+    step('Resolving deployed config...');
+    const config = await resolveConfig(flags.stage);
+    const fn = opsFunction(config);
+    info(`Region: ${config.region}, Function: ${fn}`);
+    step('Red-teaming owner isolation (two JWT identities per table, rolled back)...');
+    const result: any = await invokeAction(config.region, fn, 'db:authz:probe', {
+      setup: buildOwnerProbeSql(probes), read: OWNER_PROBE_SELECT_SQL,
+    });
+    if (result?.error) throw new Error(result.error);
+    rows = result?.rows ?? [];
+  } catch (err: any) {
+    fail(`db:authz:owner failed: ${err.message}`);
+    info('Ensure the stage is deployed with @everystack/server >= the version that adds db:authz:probe.');
+    process.exit(1);
+  }
+
+  const findings = evaluateOwnerProbe(rows.map(toOwnerProbeResult), publicReadTables);
+  const leaks = findings.filter((f) => f.severity === 'read-leak' || f.severity === 'write-leak');
+  const vacuous = findings.filter((f) => f.severity === 'vacuous');
+  const unprobed = findings.filter((f) => f.severity === 'unprobed');
+  const publicReads = findings.filter((f) => f.severity === 'public-read');
+
+  console.log('');
+  for (const f of leaks) fail(`[LEAK]    ${f.detail}`);
+  for (const f of vacuous) fail(`[VACUOUS] ${f.detail}`);
+  for (const f of publicReads) info(`[public]   ${f.detail}`);
+  for (const f of unprobed) info(`[unprobed] ${f.detail}`);
+  console.log('');
+
+  if (leaks.length === 0 && vacuous.length === 0) {
+    success(`db:authz:owner — owner isolation holds (${probes.length} table(s) probed${unprobed.length ? `, ${unprobed.length} unprobed` : ''}).`);
+    process.exit(0);
+  }
+  fail(`db:authz:owner — ${leaks.length} IDOR leak(s), ${vacuous.length} vacuous policy(ies). One user can reach another's rows.`);
+  process.exit(1);
+}

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

@@ -0,0 +1,218 @@
+/**
+ * db:backup family — logical pg_dump/pg_restore backups (the postgres-native, DB-agnostic path).
+ *
+ * These run server-side in the ops Lambda (the DB is private), so the CLI is a thin invokeAction
+ * wrapper. db:backup:probe is the deploy-verification for the pg_dump layer (B1); the
+ * dump/list/restore/download commands land in B2/B3. See docs/plans/db-backup-restore.md.
+ */
+
+import { resolveConfig, opsFunction, type CliConfig } from '../config.js';
+import { invokeAction, presignGet } from '../aws.js';
+import { parseBackupRef, keyForId, crossStageGuard, restoreTargetGuard } from '../backup.js';
+import { step, success, fail, info, warn } from '../output.js';
+
+function fmtBytes(n?: number): string {
+  if (n == null) return '-';
+  if (n < 1024) return `${n} B`;
+  const u = ['KB', 'MB', 'GB', 'TB'];
+  let v = n / 1024, i = 0;
+  while (v >= 1024 && i < u.length - 1) { v /= 1024; i++; }
+  return `${v.toFixed(1)} ${u[i]}`;
+}
+
+/**
+ * db:backup:probe — confirm the pg_dump layer is attached to the ops function AND that its major
+ * version can dump the live server (pg_dump >= server major; there is no bypass flag). This is how
+ * we prove B1 after a deploy before trusting db:backup.
+ */
+export async function dbBackupProbeCommand(flags: Record<string, string>): Promise<void> {
+  step('Resolving deployed config...');
+  let config: CliConfig;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+  step('Probing pg_dump layer + server version...');
+
+  let result: any;
+  try {
+    result = await invokeAction(config.region, opsFunction(config), 'db:backup:probe', {});
+  } catch (err: any) {
+    fail(`Probe failed: ${err.message}`);
+    process.exit(1);
+  }
+
+  if (result?.error) {
+    fail(result.error);
+    info('Build + publish the layer with scripts/build-pgdump-layer.sh, export PGDUMP_LAYER_ARN, then redeploy.');
+    process.exit(1);
+  }
+
+  info(`pg_dump:  ${result.pgDump} (major ${result.pgDumpMajor})`);
+  info(`server:   ${result.serverVersionNum} (major ${result.serverMajor})`);
+  if (result.compatible) {
+    success('Compatible — pg_dump can back up and restore this server. db:backup is ready.');
+  } else {
+    warn('INCOMPATIBLE — pg_dump is older than the server major; it will refuse to dump (no bypass exists).');
+    warn('Rebuild the layer with a pg_dump >= the server major.');
+    process.exit(1);
+  }
+}
+
+/** db:backup — pg_dump the stage's DB to S3 (runs in the ops Lambda). Prints the new backup id. */
+export async function dbBackupCommand(flags: Record<string, string>): Promise<void> {
+  step('Resolving deployed config...');
+  let config: CliConfig;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+  step('Running pg_dump → S3 (this may take a while for large databases)...');
+
+  let result: any;
+  try {
+    result = await invokeAction(config.region, opsFunction(config), 'db:backup', { stage: flags.stage });
+  } catch (err: any) {
+    fail(`Backup failed: ${err.message}`);
+    process.exit(1);
+  }
+  if (result?.error) {
+    fail(`Backup failed: ${result.error}`);
+    process.exit(1);
+  }
+  success(`Backup ${result.id} (${fmtBytes(result.bytes)}). Restore with: everystack db:restore --from ${result.id} --confirm`);
+}
+
+/** db:backups — list a stage's logical backups. */
+export async function dbBackupsCommand(flags: Record<string, string>): Promise<void> {
+  step('Resolving deployed config...');
+  let config: CliConfig;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  step('Listing backups...');
+  let result: any;
+  try {
+    result = await invokeAction(config.region, opsFunction(config), 'db:backups', { stage: flags.stage });
+  } catch (err: any) {
+    fail(`List failed: ${err.message}`);
+    process.exit(1);
+  }
+  if (result?.error) {
+    fail(`List failed: ${result.error}`);
+    process.exit(1);
+  }
+  const backups: any[] = result.backups ?? [];
+  if (backups.length === 0) {
+    info('No backups. Create one with `everystack db:backup`.');
+    return;
+  }
+  for (const b of backups) {
+    info(`${b.id}  ${fmtBytes(b.bytes).padEnd(9)}  ${b.lastModified ?? ''}`);
+  }
+  success(`${backups.length} backup${backups.length === 1 ? '' : 's'}.`);
+}
+
+/**
+ * db:restore — pg_restore a backup INTO a stage's existing DB. Destructive (drops + replaces), so
+ * it requires --confirm; restoring production-tier data downward or into a production target raises
+ * a louder warning (the S0 guards). The id encodes the source stage.
+ */
+export async function dbRestoreCommand(flags: Record<string, string>): Promise<void> {
+  const id = flags.from;
+  if (!id) {
+    fail('db:restore requires --from <backup-id> (see `everystack db:backups`).');
+    process.exit(1);
+  }
+  const ref = parseBackupRef(id);
+  if (!ref || !keyForId(id)) {
+    fail(`Malformed backup id: ${id}`);
+    process.exit(1);
+  }
+  const fromStage = ref.stage;
+  const toStage = flags.stage ?? fromStage;
+
+  // Destructive — always require --confirm. Production-tier source/target escalate the warning.
+  if (!flags.confirm) {
+    warn(`Restore is DESTRUCTIVE — it drops and replaces ${toStage}'s database with backup ${id}.`);
+    for (const g of [crossStageGuard(fromStage, toStage), restoreTargetGuard(toStage)]) {
+      if (g.requiresConfirm && g.warning) warn(g.warning);
+    }
+    info('Re-run with --confirm to proceed.');
+    process.exit(1);
+  }
+
+  step('Resolving deployed config...');
+  let config: CliConfig;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+  step(`Restoring ${id} into ${toStage} (pg_restore)...`);
+  let result: any;
+  try {
+    result = await invokeAction(config.region, opsFunction(config), 'db:restore', { id, confirm: true, stage: flags.stage });
+  } catch (err: any) {
+    fail(`Restore failed: ${err.message}`);
+    process.exit(1);
+  }
+  if (result?.error) {
+    fail(`Restore failed: ${result.error}`);
+    process.exit(1);
+  }
+  success(`Restored ${id} into ${toStage}.`);
+}
+
+/** db:backup:download — print (or save) a presigned URL to a backup's dump for local download. */
+export async function dbBackupDownloadCommand(flags: Record<string, string>, id?: string): Promise<void> {
+  const backupId = id ?? flags.from;
+  if (!backupId) {
+    fail('db:backup:download requires a backup id (e.g. `everystack db:backup:download dev/20260628T120000Z-ab12cd`).');
+    process.exit(1);
+  }
+  const key = keyForId(backupId);
+  if (!key) {
+    fail(`Malformed backup id: ${backupId}`);
+    process.exit(1);
+  }
+
+  step('Resolving deployed config...');
+  let config: CliConfig;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  if (!config.backupsBucket) {
+    fail('No backupsBucket in the deployed config. Add `backupsBucket: backups.name` to sst.config outputs and redeploy.');
+    process.exit(1);
+  }
+
+  let url: string;
+  try {
+    url = await presignGet(config.region, config.backupsBucket, key, 3600);
+  } catch (err: any) {
+    fail(`Presign failed: ${err.message}`);
+    process.exit(1);
+  }
+  info('Presigned URL (valid 1 hour) — the dump is custom-format gzip; restore with pg_restore or `everystack db:restore`:');
+  // The URL itself is the command output — print it raw so it can be piped/copied.
+  console.log(url);
+}