@everystack/server 0.4.15 → 0.4.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.4.15",
+  "version": "0.4.17",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -163,8 +163,8 @@
     "sst": "4.13.1",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/auth": "0.4.0",
-    "@everystack/cli": "0.4.35"
+    "@everystack/cli": "0.4.47",
+    "@everystack/auth": "0.4.1"
   },
   "scripts": {
     "test": "jest",

package/src/db-doctor.ts

@@ -94,6 +94,14 @@ export interface PublicExecutableFn {
   schema: string;
   name: string;
   secdef: boolean;
+  /**
+   * True when some RLS policy expression names this function. Such a function is evaluated as
+   * the QUERYING role, so a bare `REVOKE ... FROM PUBLIC` with no grant-back breaks every policy
+   * that calls it — `auth.uid()` being the canonical case. Measured from pg_policy rather than
+   * guessed from a name list, so it stays right for an app whose policies call its own helpers.
+   * Absent on an older probe (treated as unknown, never as false).
+   */
+  policyReferenced?: boolean;
 }
 
 /** A view ('v') or matview ('m') with no grants to any non-owner role. */
@@ -187,7 +195,14 @@ export const PUBLIC_EXECUTABLE_FUNCTIONS_SQL = `
 SELECT
   n.nspname AS schema,
   p.proname AS name,
-  p.prosecdef AS secdef
+  p.prosecdef AS secdef,
+  EXISTS (
+    SELECT 1
+    FROM pg_policy pol
+    WHERE COALESCE(pg_get_expr(pol.polqual, pol.polrelid), '')
+          || ' ' || COALESCE(pg_get_expr(pol.polwithcheck, pol.polrelid), '')
+          ~ ('\\m' || n.nspname || '\\.' || p.proname || '\\M')
+  ) AS policy_referenced
 FROM pg_proc p
 JOIN pg_namespace n ON n.oid = p.pronamespace
 CROSS JOIN LATERAL aclexplode(COALESCE(p.proacl, acldefault('f', p.proowner))) a
@@ -411,6 +426,17 @@ export function buildDoctorReport(probe: DoctorProbe, options: DoctorReportOptio
   // (deriveForceRlsCarveouts): auth.users and the six other auth.* tables (functions),
   // ops.runs and dist.blobs (worker), the notification tables. No hand-list, no framework
   // default that could drift from — or fall short of — the modeled set.
+  //
+  // ABSENT IS NOT EMPTY. `forceRlsCarveouts` comes from the app's models via its dbPlugin. A
+  // deploy that never passes it is not a deploy with no owner-written tables — it is a deploy
+  // whose declarations we cannot see. Collapsing the two with `?? []` made db:doctor red-flag
+  // seven owner-written auth tables and print `FORCE ROW LEVEL SECURITY` for each, unqualified.
+  // Running that paste breaks the auth paths: FORCE applies RLS to the OWNER, which is exactly
+  // the SECURITY DEFINER function that has to write those tables. The check has to say what it
+  // could not see rather than assert a fix it cannot justify. (Consumer report 2026-08-04: they
+  // read the remediation, recognised the trap themselves, and refused to run it. The next
+  // operator will not.)
+  const carveoutsDeclared = options.forceRlsCarveouts !== undefined;
   const FORCE_RLS_CARVEOUTS = new Set(options.forceRlsCarveouts ?? []);
   const allUnforced = probe.forceRls.filter((r) => r.enabled && !r.forced);
   const carved = allUnforced.filter((r) => FORCE_RLS_CARVEOUTS.has(`${r.schema}.${r.table}`));
@@ -425,11 +451,23 @@ export function buildDoctorReport(probe: DoctorProbe, options: DoctorReportOptio
       detail: 'no tables have RLS enabled yet (nothing to force)',
     });
   } else if (unforced.length > 0) {
+    const names = unforced.map((r) => `${r.schema}.${r.table}`).join(', ');
+    const fix = unforced.map((r) => `ALTER TABLE ${r.schema}.${r.table} FORCE ROW LEVEL SECURITY;`).join('  ');
+    // The STATUS stays 'fail' whether or not the carveouts were declared. An unforced RLS table
+    // is a real finding, and an app with genuinely nothing to carve out passes no carveouts —
+    // indistinguishable from one that never wired them, so downgrading on absence would weaken
+    // the check for everyone to spare the misconfigured. What changes is the REMEDIATION, which
+    // is where the actual harm was: a flat list of FORCE statements that breaks owner-mediated
+    // writes if any of these tables is one.
     checks.push({
       name: 'FORCE ROW LEVEL SECURITY on RLS tables',
       status: 'fail',
-      detail: `RLS enabled but not FORCEd (owner bypasses policies): ${unforced.map((r) => `${r.schema}.${r.table}`).join(', ')}`,
-      remediation: unforced.map((r) => `ALTER TABLE ${r.schema}.${r.table} FORCE ROW LEVEL SECURITY;`).join('  '),
+      detail: carveoutsDeclared
+        ? `RLS enabled but not FORCEd (owner bypasses policies): ${names}`
+        : `RLS enabled but not FORCEd: ${names}. NOTE: this deploy's dbPlugin passes no forceRlsCarveouts, so db:doctor cannot tell an unprotected table from one deliberately ENABLE-not-FORCE because SECURITY DEFINER functions or a worker own its writes.`,
+      remediation: carveoutsDeclared
+        ? fix
+        : `Do NOT paste this blind — FORCE applies RLS to the table OWNER, so forcing a table whose writes are owner-mediated breaks those writes, both before and after the mediating functions exist. First pass forceRlsCarveouts (and functionSchemas) from your models into dbPlugin and re-run: the answer may be that nothing is wrong. Then, for the tables that remain and are NOT owner-written: ${fix}`,
     });
   } else {
     checks.push({
@@ -486,12 +524,34 @@ export function buildDoctorReport(probe: DoctorProbe, options: DoctorReportOptio
     const offenders = probe.publicExecutableFunctions;
     if (offenders.length > 0) {
       const label = (f: PublicExecutableFn): string => `${f.schema}.${f.name}${f.secdef ? ' (SECURITY DEFINER)' : ''}`;
+      // SPLIT BY WHO CALLS IT, because one remediation is not safe for both groups.
+      //
+      // A function named in an RLS policy expression is evaluated as the QUERYING role. Revoking
+      // PUBLIC without granting the request roles back breaks every policy that calls it — the
+      // canonical case being `auth.uid()`. This used to print one flat REVOKE list covering
+      // SECDEF internals and policy helpers together, and a consumer who pasted it would have
+      // taken their own policies down. They spotted the trap and refused to run it; the next
+      // operator will not. `policyReferenced` is MEASURED from pg_policy, not guessed from a
+      // name list, so it stays correct for an app whose policies call its own helpers.
+      const policyFns = offenders.filter((f) => f.policyReferenced === true);
+      const plainFns = offenders.filter((f) => f.policyReferenced !== true);
+      const revoke = (f: PublicExecutableFn): string => `REVOKE ALL ON FUNCTION ${f.schema}.${f.name} FROM PUBLIC;`;
+      const parts: string[] = [];
+      if (plainFns.length > 0) {
+        parts.push(
+          `${plainFns.map(revoke).join('  ')} Then grant the intended callers — or declare the function with defineFunction + can('execute', { role }) so the compiler emits both. (A SECURITY DEFINER internal called only from other SECDEF functions needs NO grant back: those run as the owner.)`,
+        );
+      }
+      if (policyFns.length > 0) {
+        parts.push(
+          `CAUTION — ${policyFns.map((f) => `${f.schema}.${f.name}`).join(', ')} ${policyFns.length === 1 ? 'is' : 'are'} referenced by an RLS POLICY and evaluated as the querying role. Revoking alone will break every policy that calls ${policyFns.length === 1 ? 'it' : 'them'}. Revoke AND grant the request roles back in the same change: ${policyFns.map((f) => `${revoke(f)} GRANT EXECUTE ON FUNCTION ${f.schema}.${f.name} TO anon, authenticated, admin;`).join('  ')}`,
+        );
+      }
       checks.push({
         name: 'Functions are not PUBLIC-executable',
         status: offenders.some((f) => f.secdef) ? 'fail' : 'warn',
         detail: `PUBLIC can EXECUTE (PostgreSQL's silent-open default — a NULL proacl grants it): ${offenders.map(label).join(', ')}`,
-        remediation: offenders.map((f) => `REVOKE ALL ON FUNCTION ${f.schema}.${f.name} FROM PUBLIC;`).join('  ')
-          + ` Then grant the intended callers — or declare the function with defineFunction + can('execute', { role }) so the compiler emits both.`,
+        remediation: parts.join('  '),
       });
     } else {
       checks.push({
@@ -638,6 +698,7 @@ export function rowToPublicExecutableFn(row: any): PublicExecutableFn {
     schema: String(row.schema),
     name: String(row.name),
     secdef: pgBool(row.secdef),
+    ...(row.policy_referenced === undefined ? {} : { policyReferenced: pgBool(row.policy_referenced) }),
   };
 }
 

package/src/db-session.ts

@@ -0,0 +1,252 @@
+/**
+ * db:session — N statements, ONE connection, ONE transaction, N result sets.
+ *
+ * The problem it exists to solve: the ops Lambda holds one database connection per
+ * container and containers are ambient. `db:query` is one statement per invoke, so a
+ * caller that needs several statements to describe ONE moment (a catalog
+ * introspection, say) gets them answered by several containers on several
+ * connections. Any session state one statement sets is invisible to the next, and
+ * the assembled answer can be a collage of two renderings of one database. That is
+ * not a tuning problem; it is the absence of a session.
+ *
+ * So the session is the primitive. The caller sends its statements together, the
+ * Lambda runs them on one connection inside one transaction, and sends the result
+ * sets back in input order. The SQL stays in the caller (no version skew between a
+ * deployed server and the CLI that asks it questions), and the policy — read-only,
+ * isolation level, search_path — is the caller's too. This module hardcodes none of it.
+ *
+ * Three properties are load bearing:
+ *
+ * - **`searchPath` emits `SET LOCAL`, never a bare `SET`.** A bare `SET` on a pooled,
+ *   persistent connection outlives its command and pins whichever connection answered.
+ *   `SET LOCAL` reverts with the transaction, so reversion is structural rather than a
+ *   compensating statement that may not run. The pin consumes NO result slot — the
+ *   caller indexes results by statement, and a hidden extra slot would shift every one.
+ * - **Per-statement `allowFailure`** wraps a statement in a savepoint, so "this catalog
+ *   table may not exist yet" (`derived_provenance`, `backfill_log`, `schema_log`) costs
+ *   the one slot rather than the whole transaction. Same semantics as psql's
+ *   `ON_ERROR_ROLLBACK`. A statement NOT flagged is fatal: it aborts the transaction and
+ *   the whole session fails, because a partial answer to a consistency question is worse
+ *   than no answer. The savepoint is taken through the DRIVER's nested transaction, not
+ *   by issuing `SAVEPOINT` as SQL: postgres.js records any query error inside a
+ *   transaction scope and re-throws it after the callback returns, so a hand-rolled
+ *   `ROLLBACK TO SAVEPOINT` recovers the database and still loses the session. Only a
+ *   nested scope gets its own error bookkeeping. (Proven on a live PostgreSQL — the
+ *   hand-rolled version passed against a fake and failed against the driver.)
+ * - **The response is gzipped and size-checked.** Lambda's invoke response limit is 6 MB
+ *   and catalog JSON compresses 10-20x, so gzip alone carries any real schema. When it
+ *   does not, this HARD ERRORS with the size — it never truncates, and it never returns
+ *   a partial read that a fingerprint would silently be computed from.
+ */
+
+import { gzipSync } from 'node:zlib';
+
+/** One statement in a session. A bare string is shorthand for `{ sql, allowFailure: false }`. */
+export interface DbSessionStatement {
+  sql: string;
+  /** Survive a failure of THIS statement (savepoint), leaving the other slots intact. */
+  allowFailure?: boolean;
+}
+
+export interface DbSessionPayload {
+  statements?: Array<DbSessionStatement | string>;
+  /** `SET TRANSACTION READ ONLY` — the caller's policy, never assumed here. */
+  readOnly?: boolean;
+  /** Transaction isolation level, e.g. 'repeatable read' for a single-snapshot read. */
+  isolation?: string;
+  /** Pinned via `SET LOCAL search_path`; consumes no result slot. */
+  searchPath?: string;
+}
+
+/** A statement that failed under `allowFailure`. Occupies its slot; carries the cause. */
+export interface DbSessionStatementError {
+  everystackSessionError: true;
+  message: string;
+}
+
+/** One slot: the statement's rows, or the marker for an allowed failure. */
+export type DbSessionResult = any[] | DbSessionStatementError;
+
+/**
+ * Compressed-response ceiling. Lambda's synchronous invoke response limit is 6 MB;
+ * this leaves headroom for the JSON envelope and base64 expansion of the gzip payload.
+ */
+export const SESSION_MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+
+/** The isolation levels PostgreSQL accepts. Anything else is refused, never coerced. */
+const ISOLATION_LEVELS = new Set([
+  'read uncommitted',
+  'read committed',
+  'repeatable read',
+  'serializable',
+]);
+
+/** A bare SQL identifier — the only shape a search_path element may take. */
+const PLAIN_IDENT = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+
+/**
+ * Build the `SET LOCAL search_path` statement for a caller-supplied path.
+ *
+ * The path arrives as a string over an IAM-gated invoke and is interpolated into SQL,
+ * so it is validated as a comma-separated list of plain identifiers and rejected
+ * otherwise. `$user` is deliberately NOT accepted: this pin exists to make deparsed
+ * expressions canonical, and a role-dependent element would make the capture depend on
+ * who read it.
+ */
+export function buildSearchPathSql(searchPath: string): string {
+  const parts = searchPath.split(',').map((p) => p.trim()).filter((p) => p.length > 0);
+  if (parts.length === 0) {
+    throw new Error('searchPath must name at least one schema');
+  }
+  for (const part of parts) {
+    if (!PLAIN_IDENT.test(part)) {
+      throw new Error(
+        `searchPath element ${JSON.stringify(part)} is not a plain identifier — db:session pins only bare schema names`,
+      );
+    }
+  }
+  return `SET LOCAL search_path = ${parts.map((p) => `"${p}"`).join(', ')}`;
+}
+
+/** Normalize the payload's statements, or explain what is wrong with them. */
+export function normalizeStatements(
+  statements: Array<DbSessionStatement | string> | undefined,
+): DbSessionStatement[] {
+  if (!Array.isArray(statements) || statements.length === 0) {
+    throw new Error('db:session requires a non-empty { statements } array');
+  }
+  return statements.map((s, i) => {
+    const stmt = typeof s === 'string' ? { sql: s } : s;
+    if (!stmt || typeof stmt.sql !== 'string' || stmt.sql.trim() === '') {
+      throw new Error(`db:session statement ${i} has no sql`);
+    }
+    return { sql: stmt.sql, allowFailure: stmt.allowFailure === true };
+  });
+}
+
+/** The refusal when the compressed result set will not fit in an invoke response. */
+export function oversizeResponseError(bytes: number, statements: number): string {
+  const mb = (bytes / (1024 * 1024)).toFixed(1);
+  const capMb = (SESSION_MAX_RESPONSE_BYTES / (1024 * 1024)).toFixed(0);
+  return [
+    `db:session response too large: ${mb} MB compressed from ${statements} statements exceeds the ${capMb} MB invoke-response ceiling.`,
+    'Nothing was truncated and nothing partial was returned — a partial read is not a state anything may be computed from.',
+    'Split the read into more sessions, or narrow it (fewer schemas, fewer statements).',
+  ].join(' ');
+}
+
+/**
+ * The transaction handle: statements, plus a NESTED transaction — which drizzle maps to
+ * the driver's savepoint, the only mechanism that survives a failed statement.
+ */
+export interface SessionTx {
+  execute: (query: any) => Promise<any>;
+  transaction: <T>(fn: (sp: SessionTx) => Promise<T>) => Promise<T>;
+}
+
+/** The minimal database surface this needs: drizzle's `transaction`, nothing more. */
+export interface SessionCapableDb {
+  transaction: <T>(
+    fn: (tx: SessionTx) => Promise<T>,
+    config?: { isolationLevel?: any; accessMode?: any },
+  ) => Promise<T>;
+}
+
+const rowsOf = (result: any): any[] =>
+  Array.isArray(result) ? result : result?.rows ?? [];
+
+/**
+ * Run N statements as ONE session and return the result sets, in input order.
+ *
+ * The core, shared by the `db:session` action (which gzips this) and by the in-Lambda
+ * verbs that need a consistent multi-statement read on the operator connection —
+ * `db:apply`'s fingerprint endpoints and `db:reconcile`'s catalog read. One
+ * implementation, so the wire path and the in-process path cannot mean different things
+ * by "one session".
+ */
+export async function runSessionStatements(
+  db: SessionCapableDb,
+  statements: Array<DbSessionStatement | string> | undefined,
+  opts: Omit<DbSessionPayload, 'statements'> | undefined,
+  raw: (query: string) => any,
+): Promise<DbSessionResult[]> {
+  const stmts = normalizeStatements(statements);
+  const searchPathSql =
+    opts?.searchPath !== undefined ? buildSearchPathSql(String(opts.searchPath)) : undefined;
+
+  let isolationLevel: string | undefined;
+  if (opts?.isolation !== undefined) {
+    const level = String(opts.isolation).toLowerCase().trim();
+    if (!ISOLATION_LEVELS.has(level)) {
+      throw new Error(
+        `db:session isolation ${JSON.stringify(opts.isolation)} is not a PostgreSQL isolation level`,
+      );
+    }
+    isolationLevel = level;
+  }
+
+  // An EMPTY config is not the same as no config: drizzle treats any object as a request
+  // to configure the transaction and emits a chunk-less `SET TRANSACTION`, which is a
+  // syntax error. Declare nothing by passing nothing.
+  const txConfig = {
+    ...(isolationLevel ? { isolationLevel } : {}),
+    ...(opts?.readOnly ? { accessMode: 'read only' } : {}),
+  };
+  const hasConfig = Object.keys(txConfig).length > 0;
+
+  const results: DbSessionResult[] = [];
+  await db.transaction(
+    async (tx) => {
+      // The pin runs FIRST and its result is discarded — callers index by statement.
+      if (searchPathSql) await tx.execute(raw(searchPathSql));
+
+      for (const stmt of stmts) {
+        if (!stmt.allowFailure) {
+          // Fatal by default: a failure here aborts the transaction and the session.
+          results.push(rowsOf(await tx.execute(raw(stmt.sql))));
+          continue;
+        }
+        try {
+          // A nested transaction IS the savepoint, taken by the driver so its own error
+          // bookkeeping is scoped to it. Rolling back by hand would recover the database
+          // and still lose the session.
+          results.push(
+            await tx.transaction(async (sp) => rowsOf(await sp.execute(raw(stmt.sql)))),
+          );
+        } catch (err: any) {
+          results.push({
+            everystackSessionError: true,
+            message: err?.message || String(err),
+          });
+        }
+      }
+    },
+    hasConfig ? txConfig : undefined,
+  );
+  return results;
+}
+
+/**
+ * Run a session and return the gzipped result sets (or a typed error object).
+ *
+ * The return value is the action's response verbatim: `{ gzip }` on success,
+ * `{ error }` on any refusal or unrecovered failure. Never both.
+ */
+export async function runDbSession(
+  db: SessionCapableDb,
+  payload: DbSessionPayload | undefined,
+  raw: (query: string) => any,
+): Promise<{ gzip: string } | { error: string }> {
+  let results: DbSessionResult[];
+  try {
+    results = await runSessionStatements(db, payload?.statements, payload, raw);
+  } catch (err: any) {
+    return { error: err?.message || String(err) };
+  }
+
+  const gzip = gzipSync(Buffer.from(JSON.stringify(results), 'utf8')).toString('base64');
+  if (gzip.length > SESSION_MAX_RESPONSE_BYTES) {
+    return { error: oversizeResponseError(gzip.length, results.length) };
+  }
+  return { gzip };
+}

package/src/plugin.ts

@@ -706,6 +706,29 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       return { rows };
     };
 
+    // A SessionRunner over THIS container's operator connection, for the in-Lambda verbs
+    // (db:apply's fingerprint endpoints, db:reconcile's catalog read). Same core the
+    // db:session action serves over the wire, so both mean the same thing by "one session".
+    const sessionOverOpsDb = (sql: { raw: (q: string) => any }) =>
+      async (statements: any, opts?: any) => {
+        const { runSessionStatements } = await import('./db-session');
+        return runSessionStatements(opsDb as any, statements, opts, (q: string) => sql.raw(q));
+      };
+
+    // --- db:session — N statements, ONE connection, ONE transaction ---
+    // The primitive that makes a multi-statement remote read describe ONE moment.
+    // `db:query` is one statement per invoke, so a five-query introspection can be
+    // answered by five containers holding five connections, and any session state one
+    // statement sets is invisible to the next. This runs the caller's statements
+    // together on the single ops connection inside one transaction and returns the
+    // result sets in input order, gzipped. Policy (read-only, isolation, search_path)
+    // is the caller's; the SQL is the caller's. See db-session.ts.
+    actions['db:session'] = async (payload, _ctx) => {
+      const { sql } = await import('drizzle-orm');
+      const { runDbSession } = await import('./db-session');
+      return runDbSession(opsDb as any, payload as any, (query: string) => sql.raw(query));
+    };
+
     // --- db:doctor — "is my database actually secure?" ---
     // Probes the api connection (createDb / DATABASE_URL) and the operator connection
     // (opsDb / ADMIN_DATABASE_URL) from inside the VPC and reports whether the api path
@@ -852,6 +875,11 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
         const result: any = await opsDb.execute(sql.raw(query));
         return Array.isArray(result) ? result : result?.rows ?? [];
       };
+      // The fingerprint endpoints this apply gates on are multi-statement reads, so they
+      // run as ONE session on this container's operator connection. Server-side that was
+      // always one connection; saying so in the type is what stops a future caller from
+      // quietly reintroducing a per-statement read.
+      const session = sessionOverOpsDb(sql);
 
       const destructive = Number(plan.destructive) > 0;
       const snapStage = stage ?? ctx.environment ?? 'default';
@@ -860,7 +888,7 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       const SNAPSHOT_FRESHNESS_MS = 60 * 60_000;
       let snapshotId: string | undefined;
       try {
-        const result = await executeApplyPlan(runner, plan, {
+        const result = await executeApplyPlan(runner, session, plan, {
           actor: actor ?? null,
           gitRef: gitRef ?? null,
           // Descent/authority are decided by the CLI (checkout + caller identity)
@@ -930,7 +958,7 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
           const result: any = await opsDb.execute(sql.raw(query));
           return Array.isArray(result) ? result : result?.rows ?? [];
         };
-        const run = await executeReconcile(runner, {
+        const run = await executeReconcile(runner, sessionOverOpsDb(sql), {
           declared: p.declared,
           renamedTables: p.renamedTables,
           apply: p.apply,