@everystack/cli 0.3.21 → 0.3.23

package/README.md

@@ -220,7 +220,9 @@ everystack db:reconcile                 # deploy the derived layer (functions/vi
 everystack db:fingerprint               # content-address the live base schema vs the Models — MATCH/MISMATCH
 everystack db:sync                      # make the database match your checkout — state + compute, one verb (dev DBs)
 everystack db:diff                      # the state edge between two declared states — no DB, CI-pure; reverse = computed rollback
-everystack db:plan | db:apply           # mint a reviewable plan against a target, apply it fingerprint-verified at both ends
+everystack db:plan | db:apply           # mint a reviewable plan against a target, apply it fingerprint-verified at both ends + the fast-forward rule (checkout must descend from the commit declaring the target's state); destructive plans: --confirm + snapshot + approver set when declared
+everystack db:check                     # the CI gate per PR: merged declared state composes + artifacts match regeneration (+ ephemeral from-scratch build w/ a scratch PG)
+everystack db:approvers                 # declare who can DESTROY: the stage's destructive-approver set (SSM, STS-verified at apply)
 
 # Security
 everystack db:doctor                    # is the DB least-privilege + RLS-subject?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.21",
+  "version": "0.3.23",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -78,7 +78,7 @@
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "@everystack/model": "0.3.5"
+    "@everystack/model": "0.3.6"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.1.0",
@@ -93,7 +93,8 @@
     "expo-updates": "55.0.21",
     "postgres": "3.4.9",
     "react": "19.2.0",
-    "react-native": "0.83.6"
+    "react-native": "0.83.6",
+    "@aws-sdk/client-sts": "3.1053.0"
   },
   "peerDependenciesMeta": {
     "postgres": {
@@ -131,6 +132,9 @@
     },
     "@aws-sdk/s3-request-presigner": {
       "optional": true
+    },
+    "@aws-sdk/client-sts": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -148,7 +152,8 @@
     "drizzle-orm": "0.41.0",
     "jest": "29.7.0",
     "react": "19.2.0",
-    "ts-jest": "29.4.9"
+    "ts-jest": "29.4.9",
+    "@aws-sdk/client-sts": "3.1053.0"
   },
   "scripts": {
     "test": "jest",

package/src/cli/apply-authority.ts

@@ -0,0 +1,150 @@
+/**
+ * apply-authority — destructive applies are role-gated to a declared
+ * approver set, enforced against the caller's REAL identity (brick 9 of the
+ * migration-authority design, decisions 11 + 12).
+ *
+ * "CTO drops tables; everyone else creates functions and views." The
+ * approver set lives STAGE-SIDE — an SSM parameter in the stage's namespace,
+ * admin-writable only — never in the repo, where a checkout edit would
+ * defeat it (a repo-declared list is a convention wearing a gate's clothes).
+ * The chokepoint resolves the caller's real identity via STS — the same
+ * pattern as the `db:psql` break-glass, where the IAM read IS the gate.
+ *
+ * The gate engages on DECLARATION: a stage that never declared approvers
+ * keeps the ceremony (explicit confirmation + snapshot, always) but is not
+ * identity-gated — the migration-friendly posture, stated honestly. A
+ * declared-but-EMPTY set means "no one": destructive applies are disabled
+ * on that stage until the set says otherwise.
+ *
+ * The refusal is the two-person flow's handoff: it names who CAN approve,
+ * and `plan_ref` already pins the exact reviewed artifact — a dev mints the
+ * destructive plan, an approver applies that same file.
+ *
+ * The decision core is pure; the AWS edge (SSM + STS) is thin and injected
+ * by the command shell.
+ */
+
+/** The SSM parameter holding the approver set — a JSON array of entries. */
+export function approverParamName(appName: string, stage: string): string {
+  return `/everystack/${appName}/${stage}/db-approvers`;
+}
+
+/**
+ * Does an approver entry match a caller ARN? Exact ARN match, or a match on
+ * any path segment after the first slash — so the set can hold plain names:
+ * `ty` matches `arn:aws:iam::123:user/ty` and the session name in
+ * `arn:aws:sts::123:assumed-role/Admin/ty`. Segment (not suffix) matching:
+ * `ty` never matches `user/notty`.
+ */
+export function approverMatches(entry: string, identityArn: string): boolean {
+  if (entry === identityArn) return true;
+  const segments = identityArn.split('/').slice(1);
+  return segments.includes(entry);
+}
+
+export interface AuthorityInputs {
+  /** The declared approver set; null = the stage never declared one. */
+  approvers: string[] | null;
+  /** The caller's resolved identity (STS ARN); null = unresolvable. */
+  identity: string | null;
+}
+
+export type AuthorityVerdict =
+  | { ok: true; reason: 'approved' | 'undeclared' }
+  | { ok: false; reason: string };
+
+/** The pure decision core for a DESTRUCTIVE apply. Non-destructive plans never reach it. */
+export function checkDestructiveAuthority({ approvers, identity }: AuthorityInputs): AuthorityVerdict {
+  if (approvers === null) return { ok: true, reason: 'undeclared' };
+  if (approvers.length === 0) {
+    return {
+      ok: false,
+      reason:
+        'the declared approver set is EMPTY — destructive applies are disabled on this stage. ' +
+        'Declare approvers with `everystack db:approvers --set <arn-or-name,...>` (admin-writable parameter).',
+    };
+  }
+  if (identity === null) {
+    return {
+      ok: false,
+      reason:
+        'this stage declares a destructive-approver set, so the apply must be identity-verified — ' +
+        'and your AWS identity could not be resolved (credentials?). Fix the credentials or hand the plan to an approver.',
+    };
+  }
+  if (approvers.some((entry) => approverMatches(entry, identity))) {
+    return { ok: true, reason: 'approved' };
+  }
+  return {
+    ok: false,
+    reason:
+      `you are ${identity}, and the declared approvers are: ${approvers.join(', ')}. ` +
+      'Hand the plan file to an approver — they review and apply the exact same artifact (its plan_ref pins it).',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The thin AWS edge (lazy imports, injected by the command shell).
+// ---------------------------------------------------------------------------
+
+/** Read the approver set from SSM. Null when the parameter does not exist. */
+export async function readApproverParam(region: string, appName: string, stage: string): Promise<string[] | null> {
+  const { SSMClient, GetParameterCommand } = await import('@aws-sdk/client-ssm');
+  const client = new SSMClient({ region });
+  try {
+    const result = await client.send(new GetParameterCommand({ Name: approverParamName(appName, stage) }));
+    return parseApproverValue(result.Parameter?.Value ?? '');
+  } catch (err: any) {
+    if (err?.name === 'ParameterNotFound') return null;
+    throw err;
+  }
+}
+
+/** The stored form is a JSON array; a bare comma-separated string is accepted on read. */
+export function parseApproverValue(value: string): string[] {
+  const trimmed = value.trim();
+  if (trimmed === '') return [];
+  if (trimmed.startsWith('[')) {
+    const parsed = JSON.parse(trimmed);
+    if (!Array.isArray(parsed) || parsed.some((e) => typeof e !== 'string')) {
+      throw new Error('db-approvers parameter must be a JSON array of strings');
+    }
+    return parsed.map((e: string) => e.trim()).filter(Boolean);
+  }
+  return trimmed.split(',').map((e) => e.trim()).filter(Boolean);
+}
+
+/** Declare (or replace) the approver set. Stored as a JSON array. */
+export async function writeApproverParam(region: string, appName: string, stage: string, approvers: string[]): Promise<void> {
+  const { SSMClient, PutParameterCommand } = await import('@aws-sdk/client-ssm');
+  const client = new SSMClient({ region });
+  await client.send(new PutParameterCommand({
+    Name: approverParamName(appName, stage),
+    Value: JSON.stringify(approvers),
+    Type: 'String',
+    Overwrite: true,
+  }));
+}
+
+/** Remove the declaration entirely — the stage returns to the undeclared (ceremony-only) posture. */
+export async function removeApproverParam(region: string, appName: string, stage: string): Promise<void> {
+  const { SSMClient, DeleteParameterCommand } = await import('@aws-sdk/client-ssm');
+  const client = new SSMClient({ region });
+  try {
+    await client.send(new DeleteParameterCommand({ Name: approverParamName(appName, stage) }));
+  } catch (err: any) {
+    if (err?.name !== 'ParameterNotFound') throw err;
+  }
+}
+
+/** The caller's real identity — the STS ARN. Null when credentials can't answer. */
+export async function resolveCallerIdentity(region: string): Promise<string | null> {
+  const { STSClient, GetCallerIdentityCommand } = await import('@aws-sdk/client-sts');
+  const client = new STSClient({ region });
+  try {
+    const result = await client.send(new GetCallerIdentityCommand({}));
+    return result.Arn ?? null;
+  } catch {
+    return null;
+  }
+}

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

@@ -22,15 +22,20 @@
  */
 
 import fs from 'node:fs/promises';
-import { introspectContract, type QueryRunner } from '../authz-contract.js';
-import { introspectSchema } from '../schema-introspect.js';
+import { introspectContract, type QueryRunner, type AuthzContract } from '../authz-contract.js';
+import { introspectSchema, type SchemaSnapshot } from '../schema-introspect.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { fingerprintLive } from '../schema-fingerprint.js';
 import { applyGeneratedStatements, currentGitRef } from '../state-apply.js';
-import { renderSchemaLogFingerprintUpdate } from '../derived-apply.js';
+import { ENSURE_RECONCILER_SQL, renderSchemaLogInsert, renderSchemaLogFingerprintUpdate } from '../derived-apply.js';
 import { checkPlanPrecondition, planHash, PLAN_VERSION, type EdgePlan } from '../edge-plan.js';
+import { verifyDescent, type LiveState } from '../git-descent.js';
+import { checkDestructiveAuthority, readApproverParam, resolveCallerIdentity } from '../apply-authority.js';
+import { resolveModelsPath } from '../models-path.js';
 import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
-import { step, success, fail, info } from '../output.js';
+import { resolveConfig, opsFunction } from '../config.js';
+import { invokeAction } from '../aws.js';
+import { step, success, fail, info, warn } from '../output.js';
 
 // ---------------------------------------------------------------------------
 // The testable core.
@@ -40,17 +45,75 @@ export interface ApplyPlanOptions {
   actor?: string | null;
   /** Defaults to the plan's own gitRef (the intent that minted it). */
   gitRef?: string | null;
+  /**
+   * The fast-forward rule (brick 7): called with the target's live state
+   * after the concurrency lock passes, BEFORE anything executes. Return
+   * `ok: false` to refuse — the checkout does not descend from the commit
+   * declaring the target's state. Omitted = no descent enforcement (tests,
+   * or an explicit, confirmed, snapshotted force).
+   */
+  verifyDescent?: (live: {
+    snapshot: SchemaSnapshot;
+    contract: AuthzContract;
+    fingerprint: string;
+  }) => Promise<{ ok: true } | { ok: false; reason: string }>;
+  /**
+   * Destructive authority (brick 9, decisions 11+12): called only when the
+   * plan is destructive, after the lock and descent checks pass. Return
+   * `ok: false` to refuse — the caller is not in the stage's declared
+   * approver set. Omitted = no authority gate (non-staged targets keep the
+   * ceremony the command shell enforces).
+   */
+  verifyAuthority?: () => Promise<{ ok: true } | { ok: false; reason: string }>;
+  /**
+   * Runs after every verification passes and BEFORE the edge executes, only
+   * for destructive plans — the auto-snapshot seam ("losing data should be
+   * hard": confirmed, approved, snapshotted, in that order). A throw here
+   * aborts the apply with nothing executed.
+   */
+  beforeDestructive?: () => Promise<void>;
   /** Injectable clock for tests. */
   now?: () => number;
 }
 
 export interface ApplyPlanResult {
-  status: 'applied' | 'already-applied' | 'refused' | 'verify-failed';
+  status: 'applied' | 'already-applied' | 'refused' | 'descent-refused' | 'authority-refused' | 'verify-failed';
   liveFingerprint: string;
   reason?: string;
   logId?: number;
 }
 
+/**
+ * Decision 7, made whole: every database records every refusal, not just
+ * every apply. Best-effort by construction — a memoir INSERT that cannot be
+ * written must never mask the refusal itself (a target that rejects the
+ * bookkeeping write would have failed the apply's ENSURE identically).
+ */
+async function recordRefusal(
+  runner: QueryRunner,
+  plan: EdgePlan,
+  liveFingerprint: string,
+  gate: string,
+  reason: string,
+  options: ApplyPlanOptions,
+): Promise<void> {
+  try {
+    await runner(ENSURE_RECONCILER_SQL.join(';\n'));
+    await runner(renderSchemaLogInsert({
+      kind: 'state refusal',
+      outcome: 'refused',
+      actor: options.actor ?? null,
+      gitRef: options.gitRef ?? plan.gitRef,
+      planRef: planHash(plan),
+      fromFingerprint: liveFingerprint,
+      toFingerprint: plan.toFingerprint,
+      sql: `-- REFUSED (${gate}): ${reason}\n${plan.statements.join('\n;\n')}`,
+    }));
+  } catch {
+    // Swallowed deliberately — see the docblock.
+  }
+}
+
 /** Verify → apply → verify. Pure orchestration over an injected QueryRunner. */
 export async function executeApplyPlan(
   runner: QueryRunner,
@@ -66,9 +129,30 @@ export async function executeApplyPlan(
   }
   const pre = checkPlanPrecondition(plan, live);
   if (!pre.ok) {
+    await recordRefusal(runner, plan, live, 'concurrency lock', pre.reason, options);
     return { status: 'refused', liveFingerprint: live, reason: pre.reason };
   }
 
+  if (options.verifyDescent) {
+    const descent = await options.verifyDescent({ snapshot: before, contract: beforeAuthz, fingerprint: live });
+    if (!descent.ok) {
+      await recordRefusal(runner, plan, live, 'fast-forward rule', descent.reason, options);
+      return { status: 'descent-refused', liveFingerprint: live, reason: descent.reason };
+    }
+  }
+
+  if (plan.destructive > 0 && options.verifyAuthority) {
+    const authority = await options.verifyAuthority();
+    if (!authority.ok) {
+      await recordRefusal(runner, plan, live, 'destructive authority', authority.reason, options);
+      return { status: 'authority-refused', liveFingerprint: live, reason: authority.reason };
+    }
+  }
+
+  if (plan.destructive > 0 && options.beforeDestructive) {
+    await options.beforeDestructive();
+  }
+
   const result = await applyGeneratedStatements(runner, plan.statements, {
     actor: options.actor,
     gitRef: options.gitRef ?? plan.gitRef,
@@ -134,15 +218,101 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
     process.exit(1);
   }
 
+  // The fast-forward rule's force ceremony (design decision 9): explicit
+  // (--force-descent), snapshotted (its value NAMES the snapshot you took),
+  // and confirmed (--confirm). All three or no bypass.
+  const forceDescent = flags['force-descent'];
+  if (forceDescent !== undefined) {
+    if (forceDescent === 'true') {
+      fail('--force-descent needs the snapshot you took as its value: --force-descent <snapshot-ref> (take one first: db:snapshot or db:backup).');
+      process.exit(1);
+    }
+    if (flags.confirm !== 'true') {
+      fail('--force-descent bypasses the fast-forward rule — confirm explicitly with --confirm.');
+      process.exit(1);
+    }
+  }
+
+  // Losing data should be hard (decision 11): a destructive plan applies
+  // only confirmed (--confirm, always), snapshotted (automatic with --stage,
+  // named over a bare connection), and — when the stage declares an approver
+  // set — identity-approved (decision 12).
+  const isDestructive = plan.destructive > 0;
+  let verifyAuthority: (() => Promise<{ ok: true } | { ok: false; reason: string }>) | undefined;
+  let beforeDestructive: (() => Promise<void>) | undefined;
+  if (isDestructive) {
+    const shape = `${plan.classification.drops} drop(s), ${plan.classification.narrowings} narrowing type change(s)`;
+    if (flags.confirm !== 'true') {
+      fail(`This plan is DESTRUCTIVE — ${plan.destructive} statement(s) lose data (${shape}). Explicit confirmation is required, always: re-run with --confirm.`);
+      process.exit(1);
+    }
+    if (flags.stage) {
+      const config = await resolveConfig(flags.stage);
+      const { parseAppName } = await import('../discover.js');
+      const appName = await parseAppName();
+      verifyAuthority = async () => {
+        step(`Destructive authority: checking the approver set for stage ${flags.stage}...`);
+        const approvers = await readApproverParam(config.region, appName, flags.stage);
+        const identity = approvers === null ? null : await resolveCallerIdentity(config.region);
+        const verdict = checkDestructiveAuthority({ approvers, identity });
+        if (!verdict.ok) return verdict;
+        if (verdict.reason === 'approved') {
+          info(`authority: ${identity} is a declared approver.`);
+        } else {
+          warn('authority: no approver set declared for this stage — proceeding on ceremony alone. Declare one: everystack db:approvers --set <arn-or-name,...> --stage ' + flags.stage);
+        }
+        return { ok: true };
+      };
+      beforeDestructive = async () => {
+        step('Destructive apply — taking a snapshot first (db:backup)...');
+        const result: any = await invokeAction(config.region, opsFunction(config), 'db:backup', { stage: flags.stage });
+        if (result?.error) {
+          throw new Error(`auto-snapshot failed, so the destructive plan was NOT applied: ${result.error}`);
+        }
+        info(`snapshot on record: ${result?.id ?? 'backup complete'} — restore with db:restore --from ${result?.id ?? '<id>'} --confirm.`);
+      };
+    } else if (!flags['snapshot-ref']) {
+      fail(`This plan is DESTRUCTIVE (${shape}) and the target is a bare connection — the apply cannot take the snapshot itself. Take one (db:snapshot / db:backup / pg_dump) and name it: --snapshot-ref <ref>. Or pass --stage and the apply snapshots automatically, with the stage's approver set enforced.`);
+      process.exit(1);
+    } else {
+      warn(`DESTRUCTIVE apply over a bare connection — approver gating unavailable (no --stage), proceeding on ceremony: --confirm + snapshot ${flags['snapshot-ref']}.`);
+    }
+  }
+
   step(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
   const { runner, end } = await createUrlRunner(dbSource.url);
 
   try {
     info(`plan ${planHash(plan).slice(0, 12)}: ${plan.fromFingerprint.slice(0, 12)} → ${plan.toFingerprint.slice(0, 12)} (${plan.executable} statement(s)${plan.destructive ? `, ${plan.destructive} destructive` : ''})`);
+    if (forceDescent !== undefined) {
+      warn(`DESCENT FORCED — the fast-forward rule is bypassed for this apply. Snapshot on record: ${forceDescent}.`);
+    }
     step('Verifying the target is where the plan started...');
     const result = await executeApplyPlan(runner, plan, {
       actor: process.env.USER ?? null,
       gitRef: currentGitRef() ?? plan.gitRef,
+      ...(verifyAuthority ? { verifyAuthority } : {}),
+      ...(beforeDestructive ? { beforeDestructive } : {}),
+      ...(forceDescent === undefined ? {
+        verifyDescent: async (live: LiveState & { fingerprint: string }) => {
+          step('Descent: searching git for the commit that declares the target\'s state...');
+          const verdict = await verifyDescent(resolveModelsPath(flags.models), live, {});
+          switch (verdict.status) {
+            case 'ok':
+              info(`descent: ${verdict.commit.slice(0, 12)} declares the target's state and is an ancestor of HEAD — fast-forward.`);
+              return { ok: true };
+            case 'fresh-target':
+              info('descent: fresh target (no tables) — nothing to protect, bootstrapping.');
+              return { ok: true };
+            case 'no-git':
+              warn('descent: not a git checkout — the fast-forward rule cannot be verified here.');
+              return { ok: true };
+            case 'diverged':
+            case 'drift':
+              return { ok: false, reason: verdict.reason };
+          }
+        },
+      } : {}),
     });
 
     switch (result.status) {
@@ -153,6 +323,14 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
         fail(`REFUSED: ${result.reason}`);
         process.exit(1);
         break;
+      case 'descent-refused':
+        fail(`REFUSED (fast-forward rule): ${result.reason}`);
+        process.exit(1);
+        break;
+      case 'authority-refused':
+        fail(`REFUSED (destructive authority): ${result.reason}`);
+        process.exit(1);
+        break;
       case 'verify-failed':
         fail(`Verify FAILED: ${result.reason}`);
         process.exit(1);

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

@@ -0,0 +1,71 @@
+/**
+ * `everystack db:approvers` — declare who can destroy (brick 9, decision 12).
+ *
+ *   db:approvers --stage <name>                      # show the declared set
+ *   db:approvers --stage <name> --set "cto,arn:..."  # declare / replace
+ *   db:approvers --stage <name> --set ''             # declare EMPTY: destructive applies disabled
+ *   db:approvers --stage <name> --remove             # undeclare: back to ceremony-only
+ *
+ * The set lives stage-side (an SSM parameter in the stage's namespace) so a
+ * checkout edit can't reach it; lock it down further with IAM by denying
+ * `ssm:PutParameter` on `/everystack/<app>/<stage>/db-approvers` to
+ * non-admins — the same posture as the rest of the stage's parameters.
+ * Entries are exact ARNs or bare names matched against the caller's ARN
+ * path segments (`ty` matches `user/ty` and an assumed-role session `ty`).
+ */
+
+import { resolveConfig } from '../config.js';
+import {
+  approverParamName,
+  parseApproverValue,
+  readApproverParam,
+  writeApproverParam,
+  removeApproverParam,
+} from '../apply-authority.js';
+import { step, success, fail, info, warn } from '../output.js';
+
+export async function dbApproversCommand(flags: Record<string, string>): Promise<void> {
+  if (!flags.stage) {
+    fail('db:approvers needs --stage <name> — the approver set is per-stage configuration.');
+    process.exit(1);
+  }
+
+  step('Resolving deployed config...');
+  const config = await resolveConfig(flags.stage);
+  const { parseAppName } = await import('../discover.js');
+  const appName = await parseAppName();
+  const paramName = approverParamName(appName, flags.stage);
+
+  if (flags.remove === 'true') {
+    await removeApproverParam(config.region, appName, flags.stage);
+    success(`Removed ${paramName} — the stage is back to the undeclared posture (destructive applies gated by ceremony only).`);
+    return;
+  }
+
+  if (flags.set !== undefined) {
+    if (flags.set === 'true') {
+      fail("--set needs a value: a comma-separated list of ARNs or names (--set '' declares an EMPTY set, disabling destructive applies).");
+      process.exit(1);
+    }
+    const approvers = parseApproverValue(flags.set);
+    await writeApproverParam(config.region, appName, flags.stage, approvers);
+    if (approvers.length === 0) {
+      warn(`Declared an EMPTY approver set at ${paramName} — destructive applies are now DISABLED on ${flags.stage}.`);
+    } else {
+      success(`Declared ${approvers.length} approver(s) at ${paramName}: ${approvers.join(', ')}`);
+      info('Destructive db:apply runs against this stage now require one of these identities (STS-verified).');
+    }
+    return;
+  }
+
+  const approvers = await readApproverParam(config.region, appName, flags.stage);
+  if (approvers === null) {
+    info(`No approver set declared (${paramName} absent) — destructive applies are gated by ceremony only (--confirm + snapshot).`);
+    info("Declare one: everystack db:approvers --set 'cto,arn:aws:iam::…:user/…' --stage " + flags.stage);
+  } else if (approvers.length === 0) {
+    warn(`The approver set is declared EMPTY — destructive applies are DISABLED on ${flags.stage}.`);
+  } else {
+    info(`Destructive-approver set for ${flags.stage} (${approvers.length}):`);
+    for (const a of approvers) info(`  - ${a}`);
+  }
+}