@everystack/cli 0.4.81 → 0.4.83

package/CHANGELOG.md

@@ -4,6 +4,47 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.83] - 2026-09-16
+
+### Added
+
+- db:pull --derived-out takes a directory, split by kind and schema
+- a real SELECT-only role for db:query's read connection
+- version-guard the Model-derived wire payloads (provision, converge-ownership, reconcile)
+- two symbols and plain words — the default output for db:plan/db:apply/db:check
+- db:apply does the whole job — the plan, then the functions and views
+
+### Fixed
+
+- derive USAGE only on serial sequences (least privilege) (#11)
+- close the closing-gate findings on --derived-out <dir>
+- owner-adoption fast-follows — identity guard, self-grant revoke, ENACT transaction
+- mirror the reader fields in ServerProvision, and pin that no credential prints
+- an E-string prefix only counts when it stands alone
+- throw a private sentinel instead of calling tx.rollback() — closes a console-sandbox swallow/neutralize hole
+- the shape-pin also covers enum value domains, not just field names
+- symmetric v-prefix in the mismatch message, restore db:provision's --direct detail
+- ADD CONSTRAINT/PRIMARY KEY are not additive — they can fail against existing data
+- the lease covers the catch-up, the receipt marks a strip, the preflight never exits mid-chain
+- the catch-up's refusal mode belongs to the caller, and the failure line says why
+- the catch-up failure names two subjects, quotes its cause once, and nobody inherits 'exit'
+- db:apply refuses a malformed plan `statements` instead of throwing
+- what a statement IS gets read once, and a comment can neither hide a revoke nor invent a drop
+- the declared side rides on the plan, so a strip reads the same before and after
+- one statement, one bucket — the summary's two halves read the same declared side
+- the plan's optional grantee set is refused at load, not dereferenced after the write
+
+### Documentation
+
+- the workflow is three commands — db:plan, db:apply, db:check
+
+## [0.4.82] - 2026-09-08
+
+### Fixed
+
+- four compiler-hardening throws close the A22/F-A10/F-A12 tail
+- column-path check disclosure parity closes the F1 gap
+
 ## [0.4.81] - 2026-09-08
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.81",
+  "version": "0.4.83",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -48,6 +48,11 @@
       "types": "./src/cli/db-source.ts",
       "default": "./src/cli/db-source.ts"
     },
+    "./wire": {
+      "source": "./src/wire.ts",
+      "types": "./src/wire.ts",
+      "default": "./src/wire.ts"
+    },
     "./reconcile": {
       "source": "./src/reconcile.ts",
       "types": "./src/reconcile.ts",
@@ -120,10 +125,12 @@
     "@aws-sdk/client-rds": "3.1053.0",
     "@aws-sdk/client-s3": "3.1053.0",
     "@aws-sdk/client-ssm": "3.1053.0",
+    "@aws-sdk/credential-provider-node": "3.972.44",
     "@aws-sdk/lib-storage": "3.1053.0",
     "@aws-sdk/client-sts": "3.1053.0",
     "@aws-sdk/signature-v4a": "3.1048.0",
     "glob": "13.0.6",
+    "minimatch": "10.2.5",
     "node-forge": "1.4.0",
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
@@ -174,6 +181,7 @@
     "jest": "29.7.0",
     "react": "19.2.0",
     "ts-jest": "29.4.9",
+    "zod": "3.25.67",
     "@everystack/server": "0.4.30"
   },
   "scripts": {

package/src/cli/authz-compile.ts

@@ -133,16 +133,48 @@ function resolveSchema(model: ModelDescriptor, opts: CompileOptions): string {
   return model.schema ?? opts.schema ?? 'public';
 }
 
-/** Resolve the owner column (SQL name + type + claim) from the first owner ability. */
+/**
+ * The identity of a row scope — owner column, claim, and accessor — as one string, so two
+ * owner abilities can be compared for agreement. A model may declare `owner` on several
+ * abilities (a read and each write); they MUST all name the same scope, because the compiler
+ * folds them into ONE `rowPred`. It used to take the first silently, so a second ability with
+ * a different `owner:` compiled a policy scoped to a column nobody meant (A22).
+ */
+function ownerScopeKey(a: Ability): string {
+  const expr = (a.condition.ownerExpr as { sql?: unknown } | undefined)?.sql;
+  return `${a.condition.owner}\u0000${a.condition.userField ?? 'sub'}\u0000${typeof expr === 'string' ? expr : ''}`;
+}
+
+/**
+ * Resolve the owner column (SQL name + type + claim) from the owner abilities.
+ *
+ * Every ability that declares `owner:` must agree on the SAME column, userField and ownerExpr —
+ * the compiler has one `rowPred` per model, so disagreeing owners cannot both be honored. Taking
+ * the first silently meant a `can('read', { owner: 'authorId' })` beside a
+ * `can('update', { owner: 'editorId' })` scoped every write to `author_id` with no error (A22).
+ * A repeat of the SAME owner is fine — that is the normal shape (one owner, many verbs).
+ */
 function resolveOwner(model: ModelDescriptor): OwnerRef | null {
-  const ownerAbility = model.abilities.find((a) => a.condition.owner);
-  if (!ownerAbility) return null;
-  const fieldKey = ownerAbility.condition.owner!;
+  const ownerAbilities = model.abilities.filter((a) => a.condition.owner);
+  if (!ownerAbilities.length) return null;
+  const first = ownerAbilities[0];
+  const firstKey = ownerScopeKey(first);
+  const clash = ownerAbilities.find((a) => ownerScopeKey(a) !== firstKey);
+  if (clash) {
+    throw new Error(
+      `${model.table}: two owner abilities declare DIFFERENT row scopes — `
+      + `can('${first.action}', { owner: '${first.condition.owner}'${first.condition.userField ? `, userField: '${first.condition.userField}'` : ''} }) `
+      + `vs can('${clash.action}', { owner: '${clash.condition.owner}'${clash.condition.userField ? `, userField: '${clash.condition.userField}'` : ''} }). `
+      + `A model has ONE owner row scope; every owner ability must name the same owner, userField and ownerExpr. `
+      + `Declare the owner once and reuse it across the verbs.`,
+    );
+  }
+  const fieldKey = first.condition.owner!;
   return {
     sqlColumn: toSnakeCase(fieldKey),
     type: model.fields[fieldKey]?.spec.type ?? 'uuid',
-    claim: ownerAbility.condition.userField ?? 'sub',
-    expr: rawExpr(ownerAbility.condition.ownerExpr, `${model.table}: can({ ownerExpr })`),
+    claim: first.condition.userField ?? 'sub',
+    expr: rawExpr(first.condition.ownerExpr, `${model.table}: can({ ownerExpr })`),
   };
 }
 
@@ -167,6 +199,19 @@ interface ViaRef {
 function resolveVia(model: ModelDescriptor): ViaRef | null {
   const viaAbility = model.abilities.find((a) => a.condition.via);
   if (!viaAbility) return null;
+  // A model scopes its rows EITHER directly (`owner:`) OR transitively (`via:`) — never both.
+  // The compiler keeps one `rowPred`, and with both declared `owner` won and `via` vanished
+  // silently (A22). Two definitions of "mine" on one model is a declaration bug, not a merge.
+  const ownerAbility = model.abilities.find((a) => a.condition.owner);
+  if (ownerAbility) {
+    throw new Error(
+      `${model.table}: a model declares BOTH an owner row scope and a via: row scope — `
+      + `can('${ownerAbility.action}', { owner: '${ownerAbility.condition.owner}' }) `
+      + `and can('${viaAbility.action}', { via: '${viaAbility.condition.via}' }). `
+      + `They are two definitions of which rows are the caller's, and the compiler can honor only one. `
+      + `Use a single row scope — a direct owner OR a transitive via — for the whole model.`,
+    );
+  }
   const fieldKey = viaAbility.condition.via!;
   const ref = model.fields[fieldKey]?.spec.references;
   if (!ref) {
@@ -263,6 +308,7 @@ function rawPredicate(value: unknown, where: string): string | null {
       `${where}: expected a sql\`…\` fragment (import { sql } from '@everystack/model'), got ${typeof value}. A bare string is rejected on purpose — an RLS predicate is authored, never stringly assembled.`,
     );
   }
+  assertBalancedParens(text.trim(), where);
   // Parenthesized exactly once. A pulled predicate arrives already fully parenthesized
   // (that is how pg_get_expr deparses it), and wrapping it again made the compiled policy
   // differ from the live one by a single layer of parens — enough for the reconciler to
@@ -284,9 +330,69 @@ function rawExpr(value: unknown, where: string): string | null {
       `${where}: expected a sql\`…\` fragment (import { sql } from '@everystack/model'), got ${typeof value}. A bare string is rejected on purpose — the expression that decides who owns a row is authored, never stringly assembled.`,
     );
   }
+  assertBalancedParens(text.trim(), where);
   return text.trim();
 }
 
+/**
+ * Refuse a fragment whose parentheses do not balance WITHIN it (quote-aware).
+ *
+ * A compiled predicate is assembled by templates — `andPredicates` joins terms with ` AND ` and
+ * `ownerPredicate` writes `(col = …)`. A fragment that closes a paren it never opened, or opens
+ * one it never closes, RE-ASSOCIATES against the terms around it: `sql\`true) OR (true\`` ANDed
+ * beside an owner gate becomes `(owner AND (true) OR (true))`, and AND binds tighter than OR, so
+ * the whole policy collapses to `USING (true)` — the owner term defeated (F-A10). pg_get_expr
+ * always deparses balanced predicates, so a pulled fragment is never rejected here; only a
+ * hand-authored fragment with a stray paren is, and that is the one this catches.
+ *
+ * Quote-aware because a paren INSIDE a string literal (`status = ')'`) or a quoted identifier
+ * is data, not structure — counting it would false-reject a fragment that composes cleanly.
+ * Dollar-quoted strings ($tag$…$tag$) are skipped whole for the same reason.
+ */
+function assertBalancedParens(text: string, where: string): void {
+  const fail = (): never => {
+    throw new Error(
+      `${where}: the predicate has unbalanced parentheses. A fragment whose parens do not close `
+      + `within it re-associates against the terms it is composed beside — `
+      + `sql\`true) OR (true\` ANDed next to an owner gate becomes USING (true), defeating the gate. `
+      + `Parenthesize the fragment so every '(' it opens closes inside it.`,
+    );
+  };
+  let depth = 0;
+  let i = 0;
+  const n = text.length;
+  while (i < n) {
+    const c = text[i];
+    // A single-quoted string or double-quoted identifier — parens inside are literal text.
+    if (c === "'" || c === '"') {
+      const q = c;
+      i++;
+      while (i < n) {
+        if (text[i] === q) {
+          if (text[i + 1] === q) { i += 2; continue; } // '' / "" — an escaped quote, stay in
+          i++;
+          break;
+        }
+        i++;
+      }
+      continue;
+    }
+    // A dollar-quoted string ($tag$ … $tag$) — skip it whole, any paren inside is data.
+    if (c === '$') {
+      const m = /^\$[A-Za-z0-9_]*\$/.exec(text.slice(i));
+      if (m) {
+        const close = text.indexOf(m[0], i + m[0].length);
+        i = close === -1 ? n : close + m[0].length;
+        continue;
+      }
+    }
+    if (c === '(') depth++;
+    else if (c === ')') { if (--depth < 0) fail(); }
+    i++;
+  }
+  if (depth !== 0) fail();
+}
+
 /** AND-compose predicates, dropping the vacuous ones. A condition only ever NARROWS. */
 function andPredicates(...parts: (string | null)[]): string | null {
   const real = parts.filter((p): p is string => Boolean(p) && p !== '(true)' && p !== 'true');
@@ -586,6 +692,20 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
     }
   }
 
+  // The `privileges` map's KEYS are grantees too, emitted unquoted into GRANT just like a
+  // `role:` (see compileGrants). The role-name guard above only saw ability roles, so a
+  // fold/split grantee here — `privileges: { AUTHENTICATED: [...] }` — slid straight through and
+  // GRANTed a beyond-CRUD privilege to the wrong role. Same refusal, same exemption for PUBLIC.
+  for (const role of Object.keys(model.privileges ?? {})) {
+    if (!isPseudoPublic(role) && !/^[a-z_][a-z0-9_]*$/.test(role)) {
+      throw new Error(
+        `${table}: privileges['${role}'] — a grantee is emitted unquoted, so it must be a bare `
+        + `lowercase identifier ([a-z_][a-z0-9_]*). '${role}' would be case-folded or split by Postgres and the grant `
+        + `would land on a different role. Use the exact lowercase role name (or 'public').`,
+      );
+    }
+  }
+
   const WRITE_VERBS = [
     { action: 'create' as const, word: 'insert', command: 'INSERT' as PolicyCommand },
     { action: 'update' as const, word: 'update', command: 'UPDATE' as PolicyCommand },

package/src/cli/authz-contract.ts

@@ -385,9 +385,11 @@ export interface SequenceGrantContract {
   /**
    * The owning column is `GENERATED … AS IDENTITY`, not `serial` — and that changes who needs
    * what. A serial column's value comes from a DEFAULT `nextval(...)` evaluated with the
-   * CALLER's privileges, so an INSERTing role must hold USAGE/SELECT/UPDATE on the sequence or
-   * every insert fails `permission denied for sequence`. An identity column's value is supplied
-   * by the system as part of the column definition; no caller privilege is consulted at all.
+   * CALLER's privileges, so an INSERTing role must hold USAGE on the sequence (all `nextval`
+   * needs) or every insert fails `permission denied for sequence`. `SELECT`/`UPDATE` are NOT
+   * required for an INSERT — they are administrative (see SEQUENCE_PRIVILEGES_FOR_INSERT). An
+   * identity column's value is supplied by the system as part of the column definition; no
+   * caller privilege is consulted at all.
    *
    * Measured, not assumed: a role with INSERT on the table and NOTHING on the sequence inserts
    * successfully into an identity table and fails on a serial one. So the A6 inheritance rule

package/src/cli/authz-derive.ts

@@ -364,15 +364,24 @@ function renderColumnAbility(
   grantee: string,
   columns: readonly string[],
   policy: PolicyContract,
+  notes: string[],
 ): string | null {
   const using = policy.using ?? null;
   const owner = parseOwnerPredicate(using);
   const parts: string[] = [];
   const role = policyRoleForGrantee(grantee);
 
-  // Owner-only uses the model's authenticated default. Every other grantee must be named so
-  // the compiler emits the policy TO the live role, rather than a role-less public ability.
-  if (!owner || role !== 'authenticated') parts.push(`role: '${role}'`);
+  // A distinct WITH CHECK on a column UPDATE must ride as `check:`, and the compiler REFUSES a
+  // role-less column ability that carries any row predicate (F-A12: a column ability has nowhere
+  // row-level to put one). So a differing check forces the NAMED-role spelling — `role:
+  // 'authenticated'` — which routes to the compiler's named-role column path: that path ANDs the
+  // owner back into BOTH halves and honors the check, where the role-less shape would throw.
+  const distinctCheck = action === 'update' && policy.check != null && policy.check !== using;
+
+  // Owner-only uses the model's authenticated default. Every other grantee must be named so the
+  // compiler emits the policy TO the live role, not a role-less public ability — and a differing
+  // check names it too, to escape the F-A12 refusal above.
+  if (!owner || role !== 'authenticated' || distinctCheck) parts.push(`role: '${role}'`);
   if (owner) {
     parts.push(`owner: '${modelFieldKey(owner.column)}'`);
     if (owner.claim !== 'sub') parts.push(`userField: '${owner.claim}'`);
@@ -382,10 +391,26 @@ function renderColumnAbility(
     if (fragment) parts.push(`sql: ${fragment}`);
   }
 
-  if (action === 'update' && policy.check && policy.check !== using) {
-    const fragment = sqlFragment(policy.check);
+  if (distinctCheck) {
+    // Emit only the guard BEYOND the owner gate. The live WITH CHECK restates the owner term
+    // (the compiler's named-role column path ANDs it back in), so carrying the whole predicate
+    // would double the owner on recompile and churn the plan. Strip it exactly as the row-level
+    // write path does; a check with no owner conjunct rides whole (guard === the check).
+    const split = owner ? splitOwnerPredicate(policy.check) : null;
+    const guard = split ? split.guard : policy.check;
+    const fragment = sqlFragment(guard);
     if (!fragment) return null;
     parts.push(`check: ${fragment}`);
+    // Disclosure parity with the row-level write path. When USING is a PURE owner predicate but
+    // the live WITH CHECK does NOT restate the owner, the compiler ANDs the owner back into the
+    // rendered check — TIGHTENING it (the F-A11 "wider write half" the model cannot express). Say
+    // so, rather than let an unexplained conjunct surface in the next db:plan, which an operator
+    // might "fix" back toward the wider live shape by hand — the exact spelling the compiler refuses.
+    if (split && split.owner == null) {
+      notes.push(`policy "${policy.name}" (UPDATE) has a WITH CHECK that does not restate the owner gate in its USING —`);
+      notes.push(`  it is wider than a column owner ability can express, so the rendered model TIGHTENS it to the owner. Live WITH CHECK:`);
+      notes.push(`    ${policy.check}`);
+    }
   }
   parts.push(`columns: [${columns.map((column) => `'${modelFieldKey(column)}'`).join(', ')}]`);
   return `can('${action}', { ${parts.join(', ')} })`;
@@ -739,7 +764,7 @@ export function deriveAbilities(
       if (!cols.length) continue;
       const action = priv === 'SELECT' ? 'read' : priv === 'UPDATE' ? 'update' : null;
       const policy = action ? columnPolicyFor(contract, grantee, priv) : null;
-      const ability = action && policy ? renderColumnAbility(action, grantee, cols, policy) : null;
+      const ability = action && policy ? renderColumnAbility(action, grantee, cols, policy, notes) : null;
       if (ability) {
         abilities.push(ability);
         renderedColumnRoles.add(grantee);

package/src/cli/authz-reconcile.ts

@@ -277,20 +277,23 @@ function tableMap(c: AuthzContract): Map<string, TableContract> {
  * Measured on a consumer's database: every INSERT into a serial-PK table failed
  * `permission denied for sequence`, and two of their 563 tests were exactly that.
  *
- * The rule is INSERT on the table → USAGE + SELECT + UPDATE on its sequence, and all three
- * matter. USAGE alone permits `nextval`, but `setval` needs UPDATE and reading `last_value`
- * needs SELECT, so the common `rU` shape breaks the moment anything reseeds the counter.
+ * The rule is INSERT on the table → USAGE on its sequence, and ONLY USAGE. A serial column's
+ * value comes from a DEFAULT `nextval(...)`; USAGE is exactly the privilege `nextval` (and
+ * `currval`) requires. `setval` (reseed the counter) needs UPDATE and reading `last_value`
+ * directly needs SELECT — but neither is part of an INSERT. They are administrative operations,
+ * so an INSERT-holder must not inherit them.
  *
- * Signed off after measurement, not assumed: the consumer checked every role against every
- * serial/identity sequence and found zero cases of INSERT-without-sequence-USAGE and zero of
- * USAGE-without-UPDATE, so this under-grants nobody. Their one divergence — `authenticated`
- * holding USAGE on all 27 sequences while able to INSERT into none — was a vestigial 2023
- * blanket grant they are revoking, so their database converges to this rule rather than the
- * reverse. The pull ADVISORY names that shape wherever it appears.
+ * Least privilege, corrected after a regression: an earlier form derived SELECT + UPDATE + USAGE
+ * and handed every INSERT-holder `setval` control of a surrogate key. It widened a consumer's
+ * governed prod migrator by 28 UPDATE grants nobody asked for — governance ADDED privileges the
+ * role had worked fine without. The fix returns to the minimum INSERT needs: USAGE. A role that
+ * genuinely reseeds a counter is administrative and is either ungoverned (the reconciler leaves
+ * it alone) or must declare the grant deliberately; it is never inferred from INSERT.
  *
- * Derived, never declared: there is no `sequence:` key in the model and nobody wants one.
+ * Derived, never declared: there is no `sequence:` key in the model. Declaring sequence UPDATE
+ * for a governed role is a deliberately deferred feature — added when a real need names it.
  */
-export const SEQUENCE_PRIVILEGES_FOR_INSERT = ['SELECT', 'UPDATE', 'USAGE'] as const;
+export const SEQUENCE_PRIVILEGES_FOR_INSERT = ['USAGE'] as const;
 
 export function inheritedSequenceGrants(table: TableContract): Record<string, string[]> {
   const out: Record<string, string[]> = {};
@@ -332,10 +335,10 @@ function reconcileSequenceGrants(
     // NOTHING on the sequence inserts fine into an identity table and fails on a serial one.
     //
     // Applying the rule here was a real WIDENING, caught by the round-trip oracle the day
-    // identity columns became declarable: the rebuild handed an INSERTing role SELECT + UPDATE
-    // + USAGE — direct `setval` control of a surrogate key — that the original database never
-    // granted and never needed. Nothing is revoked either: a grant somebody made deliberately
-    // is not ours to remove, and no declaration says it should not be there.
+    // identity columns became declarable: the rebuild handed an INSERTing role USAGE on the
+    // identity sequence that the original database never granted and never needed. Nothing is
+    // revoked either: a grant somebody made deliberately is not ours to remove, and no
+    // declaration says it should not be there.
     if (seq.identity) continue;
     const target = quoteQualified(seq.sequence);
     const grantees = new Set([...Object.keys(declared), ...Object.keys(seq.grants)]);

package/src/cli/aws.ts

@@ -290,7 +290,23 @@ export async function resolveFunctionName(
  * credential-free introspection path. Every deployed-stage read verb
  * (db:plan, db:apply --stage's descent probe, …) shares it: catalog SQL runs
  * inside AWS on the operator connection, and the row set comes back over IAM.
- * `db:query` refuses writes, so this can only read.
+ *
+ * WHAT MAKES THIS READ-ONLY: not this file, and no longer a keyword blocklist in the
+ * action. `db:query` runs its single statement inside an explicit PostgreSQL `READ ONLY`
+ * transaction that always rolls back, so the ENGINE refuses a write — after parsing,
+ * where no leading comment, quoted identifier, writable CTE, `SELECT ... INTO`,
+ * `EXPLAIN ANALYZE <write>`, `COPY`, `MERGE`, `CALL` or `DO` block reaches. (A red team
+ * against a real PostgreSQL 16 defeated the blocklist that stood here before; see the
+ * comment on the `db:query` action in `@everystack/server`'s plugin.ts.)
+ *
+ * WHAT IT DOES NOT COVER: a read-only transaction stops DATA writes, not every effect.
+ * Still reachable by anyone who may invoke this action — `CLUSTER`, `REINDEX`,
+ * `LOCK TABLE ... ACCESS EXCLUSIVE`, `pg_sleep`, `NOTIFY`, and session advisory locks:
+ * availability and side-channel effects, not data change. An out-of-transaction escape
+ * exists via `dblink_exec` / `pg_background` IF those extensions are installed AND
+ * executable by the operator role. Closing those needs a real SELECT-only role wired in
+ * as the query connection (`readDatabaseUrl`) — a separate, already-filed follow-up, and
+ * an infrastructure decision rather than a code change here.
  */
 export function lambdaQueryRunner(
   region: string,