@everystack/server 0.4.29 → 0.4.31

package/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to `@everystack/server` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.31] - 2026-09-16
+
+### Added
+
+- a real SELECT-only role for db:query's read connection
+- version-guard the Model-derived wire payloads (provision, converge-ownership, reconcile)
+- automate the version-drift check — a manual note is not a gate
+
+### Fixed
+
+- one shipped descent step for both lanes, bound end to end by the real CLI; trees materialize inside the project
+- the compile-failure detail keeps the cause; the monorepo test skips loudly; the stash filter sits on the refuse-closed side
+- owner-adoption fast-follows — identity guard, self-grant revoke, ENACT transaction
+- roll the session back after a failed grant transaction
+- the reader's TABLES and SEQUENCES defaults converge independently
+- 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
+- rds_superuser membership is not superuser — probe grant capability honestly
+- 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
+
+### Changed
+
+- use drizzle's tx.rollback() instead of a hand-rolled sentinel Symbol
+
+### Documentation
+
+- note the accepted narrowing db:query's read-only transaction introduces
+
+## [0.4.30] - 2026-09-04
+
+### Fixed
+
+- ADOPT resolves its master from ADMIN_DATABASE_URL on a BYO/external RDS
+
 ## [0.4.29] - 2026-09-04
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.4.29",
+  "version": "0.4.31",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -187,8 +187,8 @@
     "sst": "4.13.1",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/cli": "0.4.71",
-    "@everystack/auth": "0.4.4"
+    "@everystack/cli": "0.4.85",
+    "@everystack/auth": "0.4.5"
   },
   "scripts": {
     "test": "jest",

package/src/db.ts

@@ -1,4 +1,3 @@
-/// <reference path="./sst-env.d.ts" />
 /**
  * @everystack/server/db — Database and secret helpers.
  *
@@ -150,6 +149,26 @@ export function getOperatorDatabaseUrl(): { url: string; source: 'admin' | 'mast
   return null;
 }
 
+/**
+ * The connection ADOPT (ownership reassignment) runs on: the linked SST Postgres master when one is
+ * present, else the `ADMIN_DATABASE_URL` operator secret.
+ *
+ * A brownfield / external-RDS app — the exact `db:pull --abilities live` audience — has NO linked
+ * `sst.aws.Postgres` component. It wires the database as secrets, and its `ADMIN_DATABASE_URL` is a
+ * privileged operator (commonly BYPASSRLS and a member of `postgres`, i.e. master-capable) that the
+ * ops Lambda already carries. Resolving ADOPT's master ONLY through the component dead-ended those
+ * apps on the missing component. This falls back to the admin secret so ADOPT has a connection to
+ * try. Whether that connection can ACTUALLY reassign is NOT decided here — ADOPT's live
+ * `master_can_act` probe decides it: a least-privilege admin resolves but the probe then refuses
+ * precisely (naming the grant to run), while a master-capable admin proceeds.
+ *
+ * `master` (linked component) is preferred because its presence guarantees master capability; the
+ * admin fallback is probe-gated. Never the least-privilege `DATABASE_URL`.
+ */
+export function getAdoptMasterUrl(): string | null {
+  return getMasterDatabaseUrl() ?? getAdminDatabaseUrl();
+}
+
 export function getJwtSecret(): Uint8Array {
   // PascalCase Secret (SST_RESOURCE_JwtSecret → { value })
   const pascal = sstLink('JwtSecret')?.value as string | undefined;
@@ -322,9 +341,29 @@ let adminFallbackWarned = false;
  * fallback — which is why the guard that refuses a privileged app credential must not treat
  * local dev as a violation. See
  * plan:the-operator-credential-is-the-ops-channel-only-doctrine-doc.
+ *
+ * ONE PHYSICAL CONNECTION, ALWAYS. This connection is pinned to `max: 1` and a caller's
+ * `maxConnections` is deliberately ignored on this path — two guarantees rest on there being
+ * exactly one backend behind it:
+ *
+ *   1. `db:query`'s `pg_advisory_unlock_all()` cleanup (plugin.ts) must run on the SAME backend
+ *      that took the lock. A session advisory lock survives ROLLBACK, so with a pool the
+ *      release can land on a different connection and the lock is held until the container dies.
+ *   2. Session state a statement leaves behind — `SET search_path`, a temp table, a prepared
+ *      statement — must not surface in an unrelated later call. With one connection "the last
+ *      call rolled back" is the whole story; with a pool it is a per-connection lottery.
+ *
+ * Pooling buys the ops channel nothing either way: its actions (migrate, seed, console,
+ * db:query) run one at a time.
  */
 export function createAdminDb<T extends Record<string, unknown>>(
   schema: T,
+  /**
+   * Accepted for signature parity with `createDb`. `maxConnections` is IGNORED for the operator
+   * connection — see the "ONE PHYSICAL CONNECTION" note above. It still reaches `createDb` on
+   * the no-operator-credential fallback below, which is the API connection, a different
+   * connection kind with its own rules.
+   */
   options?: { maxConnections?: number }
 ): {
   db: ReturnType<typeof drizzle>;
@@ -352,7 +391,9 @@ export function createAdminDb<T extends Record<string, unknown>>(
     return createDb(schema, options);
   }
 
-  adminSqlClient = postgres(adminUrl, connectionOptions(adminUrl, options?.maxConnections));
+  // Pinned to 1, not `options?.maxConnections` — the advisory-lock cleanup and the
+  // no-session-leak guarantee both require a single physical connection. See the docblock.
+  adminSqlClient = postgres(adminUrl, connectionOptions(adminUrl, 1));
   adminDbInstance = drizzle(adminSqlClient, { schema });
   return { db: adminDbInstance, schema };
 }

package/src/model-wire.ts

@@ -0,0 +1,94 @@
+/**
+ * The Model-derived WIRE-CONTRACT gate — the server half.
+ *
+ * `db:provision`, `db:converge-ownership` and `db:reconcile` take payloads the CLI computes FROM
+ * the Models barrel: owner assignments (`declaredOwners` / `declaredObjects`) and derived-object
+ * descriptors (`declared`). The operator's `@everystack/cli` and the one bundled into this Lambda
+ * are separate installs on independent release trains, so those shapes can drift between the two
+ * — a field renamed, retyped, or given new required meaning rides through silently and lands as
+ * wrong ownership or a wrong derived object on a real database.
+ *
+ * So each of those payloads carries `modelContract`, and this refuses anything but EXACT equality
+ * with the MODEL_WIRE_CONTRACT the bundled CLI states. Same shape of check `db:apply` has run
+ * against `APPLY_CONTRACT_VERSION` since M1, and deliberately a SEPARATE number: apply versions a
+ * persisted plan artifact, this versions an ephemeral wire payload.
+ *
+ * Two rules this file exists to make unmissable:
+ *
+ *   MISSING IS A REFUSAL, never a default. A caller that does not send `modelContract` is on a
+ *   version that predates the field, which IS the skew being guarded. Defaulting it to "probably
+ *   fine" would reintroduce exactly the silent path the guard removes.
+ *
+ *   THE REFUSAL IS PRE-DISPATCH. Callers run this before resolving a connection, before any
+ *   master client is opened, and before any DDL — so a skewed payload never reaches the database
+ *   at all. `__tests__/model-wire-actions.test.ts` proves that with a mocked operator connection
+ *   that must never be called.
+ *
+ * The CLI's own half of the handshake — reading `_health` and refusing to dispatch to a stage
+ * that advertises a different number, or none at all — lives in
+ * `packages/cli/src/cli/model-wire-lane.ts`. Neither half closes the hole alone: this one cannot
+ * see a stage deployed BEFORE the guard existed (it has no code to refuse with), and that one is
+ * a client claim, which a server must never trust.
+ */
+
+/**
+ * Null when the payload speaks this server's Model-derived wire contract; otherwise the refusal
+ * to return to the caller verbatim.
+ *
+ * `verb` is the action name, so the operator reads which edge refused.
+ */
+export function modelWireRefusal(
+  verb: string,
+  declared: unknown,
+  enforced: number,
+): string | null {
+  if (typeof declared === 'number' && declared === enforced) return null;
+
+  // Three genuinely different situations, so three leads rather than one template with holes in
+  // it. Two formatting rules earn their keep here, both learned the hard way:
+  //
+  //   ABSENT gets its own sentence. Splicing nothing into "declares v…" rendered the literal
+  //   "declares v(none)", which reads as a broken template exactly where an operator has to trust
+  //   what the message says.
+  //
+  //   Every VERSION NUMBER renders as `v<n>`, on both sides. The first fix for the above put the
+  //   prefix on the enforced side only, giving "declares model-wire contract 5 … enforces v1" —
+  //   two numbers in one sentence, formatted two ways, inviting the reader to wonder whether they
+  //   mean the same kind of thing. They do.
+  //
+  // A non-numeric claim gets neither: `v"1"` would be worse than saying plainly that it is
+  // malformed, and a client sending one has a bug distinct from being out of date.
+  const lead =
+    declared === undefined || declared === null
+      ? `this ${verb} payload declares NO model-wire contract — the everystack CLI that sent it `
+        + `predates the handshake — and this stage's ops Lambda enforces v${enforced}.`
+      : typeof declared === 'number'
+        ? `this ${verb} payload declares model-wire contract v${declared}, and this stage's ops `
+          + `Lambda enforces v${enforced}.`
+        : `this ${verb} payload declares a malformed model-wire contract `
+          + `(${JSON.stringify(declared)}); this stage's ops Lambda enforces v${enforced}.`;
+
+  // An older CLI is the overwhelmingly likely cause: a CURRENT CLI catches the skew at the
+  // `_health` handshake and never dispatches, so a payload that gets here at all came from one
+  // that does not run that preflight. Hence the remedy leads with upgrading the CLI — the same
+  // reasoning db:apply's refusal spells out.
+  return (
+    `${lead} The CLI that computed this Model-derived payload and the one deployed with this `
+    + `stage do not agree on its shape. Upgrade the CLI to match (or, if the stage was rolled `
+    + `back, redeploy it); nothing was applied.`
+  );
+}
+
+/**
+ * The refusal for a server that cannot even STATE its contract, because `@everystack/cli/wire`
+ * would not load. Fail closed: a stage that cannot name the shape it understands must never
+ * accept a Model-derived payload on the strength of the caller's word for it.
+ */
+export function modelWireUnavailableRefusal(verb: string, cause: unknown): string {
+  return (
+    `${verb} cannot verify the Model-derived wire contract — this stage's ops Lambda failed to `
+    + `load @everystack/cli/wire (${String(cause)}), so it cannot state which payload shape it `
+    + `understands. Refusing rather than guessing. Redeploy the stage with a matching `
+    + `@everystack/cli; nothing was applied.`
+  );
+}

package/src/owner-adoption.ts

@@ -188,6 +188,59 @@ export interface AdopteeProbe {
 }
 
 const OWNER_IDENT = /^[a-z_][a-z0-9_]*$/;
+
+/** One unquoted identifier component — a schema, an object name, a type word. */
+const IDENT_PART = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A double-quoted component. The catalog spells exactly two kinds this way: `"char"` and a
+ *  mixed-case custom type. Nothing that could carry SQL is allowed inside. */
+const QUOTED_PART = /^"[A-Za-z0-9_ ]+"$/;
+const isPart = (s: string): boolean => IDENT_PART.test(s) || QUOTED_PART.test(s);
+
+/** `schema.name` — exactly two components, each a bare or quoted identifier. */
+function isQualifiedName(s: string): boolean {
+  const parts = s.split('.');
+  return parts.length === 2 && parts.every(isPart);
+}
+
+/**
+ * One argument type in the catalog's `format_type` spelling: a single word (`integer`), several
+ * (`character varying`, `timestamp with time zone`), a schema-qualified custom type
+ * (`api.my_enum`), a quoted one (`"char"`), each with any number of trailing `[]` dimensions.
+ */
+function isArgType(s: string): boolean {
+  let t = s;
+  while (t.endsWith('[]')) t = t.slice(0, -2);
+  if (!t) return false;
+  const words = t.split(' ');
+  if (words.some((w) => w === '')) return false; // leading, trailing or doubled space
+  if (words.length > 1) return words.every((w) => IDENT_PART.test(w));
+  return t.includes('.') ? isQualifiedName(t) : isPart(t);
+}
+
+/**
+ * Is `identity` shaped like an identity everystack spells — `schema.name` for a view/matview,
+ * `schema.name(argtype, …)` for a function?
+ *
+ * DEFENCE IN DEPTH (BF5). `identity` is interpolated RAW into `ALTER … OWNER TO` below. Today it
+ * cannot be anything else: the list is barrel-sourced (the Models export, not user input) and
+ * resolution-gated (`to_regprocedure`/`to_regclass` return NULL for a bogus identity, and only a
+ * probe that EXISTS reaches the ALTER). But a raw interpolation deserves its own gate, and
+ * OWNER_IDENT cannot be that gate — a bare role name has no dots, parens, commas or spaces, and an
+ * identity legitimately has all four. So the interpolation gets a validator shaped for what it
+ * actually carries, and everything else is refused by name.
+ */
+export function isValidObjectIdentity(identity: string): boolean {
+  const open = identity.indexOf('(');
+  if (open === -1) return isQualifiedName(identity);
+  if (!identity.endsWith(')')) return false;
+  if (!isQualifiedName(identity.slice(0, open))) return false;
+  const args = identity.slice(open + 1, -1);
+  if (args.includes('(') || args.includes(')')) return false;
+  if (args === '') return true; // `api.report()` — a function of no arguments
+  // The catalog joins argument types with `, `; tolerate the separating space, nothing else.
+  return args.split(',').every((a) => isArgType(a.startsWith(' ') ? a.slice(1) : a));
+}
+
 const KEYWORD: Record<Adoptee['kind'], string> = {
   function: 'FUNCTION', view: 'VIEW', 'materialized view': 'MATERIALIZED VIEW',
 };
@@ -245,6 +298,13 @@ export interface AdoptionPlan {
   reassigned: Adoptee[];
   /** Precise pre-flight refusals — nothing is applied if this is non-empty (all or nothing). */
   refusals: string[];
+  /**
+   * The declared owners the master self-granted `SET` on, BY NAME. That membership exists only to
+   * make the ALTERs legal, so the caller revokes each one once the transaction has committed —
+   * otherwise it accumulates on the master across ADOPT runs. Named, not spelled as SQL, because
+   * only the caller knows when the commit happened.
+   */
+  selfGrantedOwners: string[];
 }
 
 /**
@@ -257,13 +317,17 @@ export interface AdoptionPlan {
 export function planAdoptionReassignment(adoptees: Adoptee[], probes: AdopteeProbe[]): AdoptionPlan {
   const byId = new Map(probes.map((p) => [p.identity, p]));
   const alters: string[] = [];
-  const selfGrants = new Set<string>(); // one per declared owner the master must self-grant SET on
-  const plan: AdoptionPlan = { statements: [], reassigned: [], refusals: [] };
+  const selfGranted = new Set<string>(); // one per declared owner the master must self-grant SET on
+  const plan: AdoptionPlan = { statements: [], reassigned: [], refusals: [], selfGrantedOwners: [] };
 
   for (const a of adoptees) {
     const p = byId.get(a.identity);
     if (!p || !p.exists) continue; // not in the DB — reconcile creates it owned correctly, nothing to adopt
     if (p.liveOwner === a.declaredOwner) continue; // already correct
+    if (!isValidObjectIdentity(a.identity)) {
+      plan.refusals.push(`${JSON.stringify(a.identity)}: not a valid qualified object identity (expected schema.name, or schema.name(argtype, ...) for a function) — refusing to interpolate it into ALTER ${KEYWORD[a.kind]} ... OWNER TO.`);
+      continue;
+    }
     if (p.isExtensionMember) {
       plan.refusals.push(`${a.identity}: owned by an extension — never reassigned (its OID binds to the extension).`);
       continue;
@@ -292,7 +356,7 @@ export function planAdoptionReassignment(adoptees: Adoptee[], probes: AdopteePro
       // it self-grants SET inside the transaction; otherwise it is a precise refusal naming THIS
       // conjunct (not the current-owner one), with the fix.
       if (p.masterAdminOfDeclared) {
-        selfGrants.add(`GRANT ${a.declaredOwner} TO CURRENT_USER WITH SET TRUE, INHERIT FALSE`);
+        selfGranted.add(a.declaredOwner);
       } else {
         plan.refusals.push(`${a.identity}: the master cannot SET ROLE to the declared owner '${a.declaredOwner}' and lacks ADMIN OPTION on it to grant itself. As a role with admin on '${a.declaredOwner}':  GRANT ${a.declaredOwner} TO <master> WITH SET TRUE;  then re-run.`);
         continue;
@@ -302,6 +366,13 @@ export function planAdoptionReassignment(adoptees: Adoptee[], probes: AdopteePro
     plan.reassigned.push({ ...a, currentOwner: p.liveOwner });
   }
   // Self-grants first (they make the SET conjunct true), then the reassignments — one transaction.
-  plan.statements = [...selfGrants, ...alters];
+  // A role membership granted inside a transaction is visible to the commands that follow it there,
+  // which is exactly why the ALTERs can use it; the matching REVOKE therefore belongs strictly
+  // AFTER the commit, and is the caller's job (see selfGrantedOwners).
+  plan.selfGrantedOwners = [...selfGranted];
+  plan.statements = [
+    ...plan.selfGrantedOwners.map((o) => `GRANT ${o} TO CURRENT_USER WITH SET TRUE, INHERIT FALSE`),
+    ...alters,
+  ];
   return plan;
 }