@everystack/server 0.4.36 → 0.4.38

package/src/plugin.ts

@@ -37,6 +37,7 @@ import {
 } from './index';
 import { splitSqlStatements, stripSqlComments } from './sql-lex';
 import { DEFAULT_STRIP_QUERY_PARAMS, stripQueryParams } from './strip-query-params';
+import { htmlCacheControl } from './cache-control';
 
 // --- Plugin Types ---
 
@@ -172,6 +173,17 @@ export function createPluginLambdaHandler(
       contributions.push(await plugin(ctx));
     }
 
+    // An OWN `__proto__` key (parsed JSON, a computed key) cannot be an action: Object.assign would
+    // run the `__proto__` setter on the map instead of adding it, and the spread below would define
+    // it as an own key. Refuse it at init rather than drop or dispatch it.
+    const refuseProtoKey = (source: string, actions: Record<string, ActionHandler> | undefined) => {
+      if (actions && Object.hasOwn(actions, '__proto__')) {
+        throw new Error(`[everystack/server] ${source} action name "__proto__" is not allowed`);
+      }
+    };
+    for (const contribution of contributions) refuseProtoKey('plugin', contribution.actions);
+    refuseProtoKey('app', options.actions);
+
     // Collect actions (app-level takes precedence on collision)
     const pluginActions: Record<string, ActionHandler> = {};
     for (const contribution of contributions) {
@@ -305,7 +317,7 @@ export function createPluginLambdaHandler(
             // GETs are version-keyed and can cache long at the edge.
             const isHtml = String(result.headers['content-type'] || '').includes('text/html');
             result.headers['cache-control'] = isHtml
-              ? (options.cache?.html ?? 'public, max-age=0, s-maxage=60')
+              ? htmlCacheControl(path, options.cache)
               : (options.cache?.public ?? 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5');
           }
         } else {
@@ -1092,6 +1104,11 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
         (payload || {}) as Parameters<typeof runProvision>[0],
         {
           execute: async (statement) => opsDb.execute(sql.raw(statement)),
+          // Reads for the lifecycle role's existence and member report.
+          query: async (statement) => {
+            const res: any = await opsDb.execute(sql.raw(statement));
+            return Array.isArray(res) ? res : (res?.rows ?? []);
+          },
           connection,
           // Additive-only: an already-live login role keeps its password (never reset on re-provision).
           roleHasLogin: async (role) => {

package/src/provision.ts

@@ -20,7 +20,7 @@
  * without a database; plugin.ts wires the real deps.
  */
 
-import { generateRoleChainSQL, generateAdminRoleSQL, generateSearchPathSQL, generateRotationPairSQL, generateReaderRoleSQL } from './role-chain';
+import { generateRoleChainSQL, generateAdminRoleSQL, generateSearchPathSQL, generateRotationPairSQL, generateReaderRoleSQL, generateLifecycleRoleSQL, LIFECYCLE_ROLE } from './role-chain';
 import {
   pgVersionRefusal,
   ownerFactsSql,
@@ -107,6 +107,12 @@ export interface ProvisionPayload {
   searchPath?: string[];
   /** Create A/B rotation pairs for credential rotation without downtime. */
   rotationPairs?: boolean;
+  /**
+   * The Models declare a `lifecycle: true` model, so provision the reserved role it compiles to
+   * (everystack_lifecycle): NOLOGIN NOINHERIT NOBYPASSRLS, no grants, no members. Derived from the
+   * Models barrel by the CLI. Absent or false (an older CLI) = no role is created, as before.
+   */
+  lifecycleRole?: boolean;
 }
 
 /**
@@ -148,6 +154,20 @@ export interface ProvisionDeps {
    * not-existing (the role is being created now, so its password IS set).
    */
   roleHasLogin?: (role: string) => Promise<boolean>;
+  /**
+   * The lifecycle role's name. A TEST seam only: the role is cluster-level and a dev cluster may
+   * already hold the real one. No caller sets it; absent = everystack_lifecycle.
+   */
+  lifecycleRoleName?: string;
+}
+
+/** One direct member of the lifecycle role, with the options its membership carries. */
+export interface LifecycleRoleMember {
+  role: string;
+  admin: boolean;
+  inherit: boolean;
+  /** Can SET ROLE to it (always true before PostgreSQL 16, which has no per-grant SET option). */
+  set: boolean;
 }
 
 export interface ProvisionResult {
@@ -202,6 +222,23 @@ export interface ProvisionResult {
    * says nothing about it. Same non-fatal contract as ENACT: never throws, never aborts.
    */
   publicSchemaPosture?: PublicSchemaPosture;
+  /**
+   * The reserved lifecycle role. Absent when the payload did not ask for it. `created` = false means
+   * it existed and its attributes were re-asserted. `members` are its direct members, reported and
+   * never revoked: a member can SET ROLE to it, and that passes the lifecycle guard. Null when this
+   * caller cannot read (no `query` dep).
+   */
+  lifecycleRole?: {
+    role: string;
+    created: boolean | null;
+    members: LifecycleRoleMember[] | null;
+    /**
+     * Elevated attributes an existing role carries that provision does not strip (CREATEROLE,
+     * CREATEDB, REPLICATION), for the CLI to name. SUPERUSER is never here: it is refused.
+     * Null when this caller cannot read.
+     */
+    attributes: string[] | null;
+  };
   error?: string;
 }
 
@@ -238,8 +275,11 @@ export async function runProvision(
   let roleSql: string;
   let adminSql: string | null = null;
   let readerSql: string | null = null;
+  let lifecycleSql: string | null = null;
+  const lifecycleRole = deps.lifecycleRoleName ?? LIFECYCLE_ROLE;
   try {
     roleSql = generateRoleChainSQL({ loginRole, appRoles });
+    if (payload.lifecycleRole === true) lifecycleSql = generateLifecycleRoleSQL(lifecycleRole);
     if (adminPassword) adminSql = generateAdminRoleSQL({ adminRole });
     if (readerPassword) readerSql = generateReaderRoleSQL({ readerRole });
   } catch (err: any) {
@@ -256,6 +296,30 @@ export async function runProvision(
   const adminExisted = !!adminPassword && !!deps.roleHasLogin && (await deps.roleHasLogin(admin));
   const readerExisted = !!readerPassword && !!deps.roleHasLogin && (await deps.roleHasLogin(reader));
 
+  // The lifecycle role's live state, read BEFORE any DDL so a refusal leaves nothing half-done.
+  let lifecycleLive: { existed: boolean; attributes: string[] } | null = null;
+  if (lifecycleSql && deps.query) {
+    const [row] = await deps.query(
+      `SELECT rolsuper, rolcreaterole, rolcreatedb, rolreplication FROM pg_roles WHERE rolname = '${lifecycleRole}'`,
+    );
+    const on = (v: unknown): boolean => v === true || v === 't' || v === 'true';
+    if (row && on(row.rolsuper)) {
+      // Not fixed by the ALTER: PostgreSQL 16 refuses NOSUPERUSER from a non-superuser, and a
+      // superuser owning SECURITY DEFINER functions makes every one of them run as a superuser.
+      throw new Error(
+        `the lifecycle role '${lifecycleRole}' exists with SUPERUSER — refused before any change. ` +
+        `As a superuser run: ALTER ROLE ${lifecycleRole} NOSUPERUSER; (or drop the role and re-run db:provision).`,
+      );
+    }
+    lifecycleLive = {
+      existed: !!row,
+      attributes: row
+        ? ([['CREATEROLE', row.rolcreaterole], ['CREATEDB', row.rolcreatedb], ['REPLICATION', row.rolreplication]] as const)
+          .filter(([, v]) => on(v)).map(([name]) => name)
+        : [],
+    };
+  }
+
   await deps.execute(roleSql);
 
   const result: ProvisionResult = {
@@ -265,6 +329,18 @@ export async function runProvision(
     passwordSet: false,
   };
 
+  // The reserved lifecycle role — a NOLOGIN role with no password, so it sits with the role chain,
+  // ahead of every password and well clear of the password-to-secret window.
+  if (lifecycleSql) {
+    await deps.execute(lifecycleSql);
+    result.lifecycleRole = {
+      role: lifecycleRole,
+      created: lifecycleLive ? !lifecycleLive.existed : null,
+      members: deps.query ? await lifecycleRoleMembers(lifecycleRole, deps.query) : null,
+      attributes: lifecycleLive ? lifecycleLive.attributes : null,
+    };
+  }
+
   // The role-default search_path (search-path-ownership): set it on the login role now that it
   // exists. The right layer — a clean connection secret, bare refs resolved for every direct
   // connection, and it persists through the API's SET ROLE. No-op for an all-public app.
@@ -387,6 +463,26 @@ export async function runProvision(
   return result;
 }
 
+/**
+ * The direct members of the lifecycle role, from pg_auth_members. `to_jsonb(m)` reads the
+ * PostgreSQL 16 per-grant options without naming columns an older server lacks; before 16 every
+ * membership could SET ROLE and INHERIT followed the member, so a missing option reads that way.
+ */
+async function lifecycleRoleMembers(role: string, query: (sql: string) => Promise<any[]>): Promise<LifecycleRoleMember[]> {
+  const rows = await query(
+    `SELECT r.rolname AS member, m.admin_option AS admin,
+            COALESCE((to_jsonb(m) ->> 'inherit_option')::boolean, r.rolinherit) AS inherit,
+            COALESCE((to_jsonb(m) ->> 'set_option')::boolean, true) AS set
+       FROM pg_auth_members m
+       JOIN pg_roles g ON g.oid = m.roleid
+       JOIN pg_roles r ON r.oid = m.member
+      WHERE g.rolname = '${role}'
+      ORDER BY r.rolname`,
+  );
+  const truthy = (v: unknown): boolean => v === true || v === 't' || v === 'true';
+  return rows.map((r) => ({ role: String(r.member), admin: truthy(r.admin), inherit: truthy(r.inherit), set: truthy(r.set) }));
+}
+
 /**
  * Converge declared ownership — ENACT (Gap 1) then ADOPT (Gap 2) — as a step SEPARATE from and
  * AFTER credential provisioning + the secret-store write (see runProvision's closing note). By the

package/src/purge-graph.ts

@@ -0,0 +1,91 @@
+/** Refuse physical removal when live foreign keys exceed the declared lifecycle graph. */
+import { sql } from 'drizzle-orm';
+import type { ModelDescriptor, Relation } from '@everystack/model';
+import type { SessionTx } from './db-session';
+
+interface ForeignKey {
+  parent_schema: string;
+  parent_table: string;
+  child_schema: string;
+  child_table: string;
+  parent_columns: string[];
+  child_columns: string[];
+  action: string;
+  child_lifecycle: boolean;
+}
+const label = (m: ModelDescriptor): string => `${m.schema}.${m.table}`;
+const parentOf = (f: ForeignKey): string => `${f.parent_schema}.${f.parent_table}`;
+const childOf = (f: ForeignKey): string => `${f.child_schema}.${f.child_table}`;
+const snake = (name: string): string => name.replace(/[A-Z]/g, c => '_' + c.toLowerCase());
+const expectedAction = (rel: Relation, liveLifecycle: boolean): string => rel.dependent === 'nullify' ? 'n'
+  : rel.dependent === 'cascade' && !liveLifecycle && !rel.target().lifecycle ? 'c' : 'r';
+
+function matches(fk: ForeignKey, parent: ModelDescriptor, rel: Relation): boolean {
+  return rel.kind === 'hasMany' && Boolean(rel.dependent)
+    && parentOf(fk) === label(parent) && childOf(fk) === label(rel.target())
+    && fk.child_columns.length === 1 && fk.child_columns[0] === snake(rel.column)
+    && fk.parent_columns.length === 1 && fk.parent_columns[0] === snake(rel.references ?? parent.primaryKey[0]);
+}
+
+/** Catalog read only. A refusal has no hook, DELETE or receipt, even for eligible rows. */
+export async function unsupportedPurgeGraphs(exec: SessionTx, models: ModelDescriptor[]): Promise<Map<string, string>> {
+  const raw: unknown = await exec.execute(sql`
+    SELECT pn.nspname AS parent_schema, p.relname AS parent_table,
+      cn.nspname AS child_schema, c.relname AS child_table, f.confdeltype AS action,
+      ARRAY(SELECT a.attname FROM unnest(f.confkey) WITH ORDINALITY k(num,pos)
+        JOIN pg_catalog.pg_attribute a ON a.attrelid=p.oid AND a.attnum=k.num ORDER BY k.pos) AS parent_columns,
+      ARRAY(SELECT a.attname FROM unnest(f.conkey) WITH ORDINALITY k(num,pos)
+        JOIN pg_catalog.pg_attribute a ON a.attrelid=c.oid AND a.attnum=k.num ORDER BY k.pos) AS child_columns,
+      EXISTS (SELECT 1 FROM pg_catalog.pg_trigger t
+        JOIN pg_catalog.pg_proc fn ON fn.oid=t.tgfoid
+        JOIN pg_catalog.pg_roles r ON r.oid=fn.proowner
+        WHERE t.tgrelid=c.oid AND NOT t.tgisinternal
+          AND (t.tgtype & 2)=2 AND (t.tgtype & 8)=8
+          AND r.rolname='everystack_lifecycle') AS child_lifecycle
+    FROM pg_catalog.pg_constraint f
+      JOIN pg_catalog.pg_class p ON p.oid=f.confrelid
+      JOIN pg_catalog.pg_namespace pn ON pn.oid=p.relnamespace
+      JOIN pg_catalog.pg_class c ON c.oid=f.conrelid
+      JOIN pg_catalog.pg_namespace cn ON cn.oid=c.relnamespace
+    WHERE f.contype='f'`);
+  const fks = (Array.isArray(raw) ? raw : (raw as { rows: ForeignKey[] }).rows) as ForeignKey[];
+  const byParent = new Map<string, ForeignKey[]>();
+  for (const fk of fks) byParent.set(parentOf(fk), [...(byParent.get(parentOf(fk)) ?? []), fk]);
+  const declared = new Map(models.map(m => [label(m), m]));
+  const badActions = new Map<string, string>();
+  for (const model of models) {
+    const root = label(model);
+    for (const rel of Object.values(model.relations)) {
+      if (rel.kind !== 'hasMany' || !rel.dependent) continue;
+      const edges = (byParent.get(root) ?? []).filter(fk => matches(fk, model, rel));
+      if (!edges.length || edges.some(fk => fk.action !== expectedAction(rel, fk.child_lifecycle))) {
+        badActions.set(root, `unsupported graph: ${label(rel.target())} foreign key disagrees with declared ${rel.dependent}`);
+      }
+    }
+  }
+  const refused = new Map<string, string>();
+  for (const model of models.filter(m => m.lifecycle)) {
+    const root = label(model);
+    const visited = new Set<string>();
+    const walk = (parent: string): string | undefined => {
+      const mismatch = badActions.get(parent);
+      if (mismatch) return mismatch;
+      if (visited.has(parent)) return;
+      visited.add(parent);
+      for (const fk of byParent.get(parent) ?? []) {
+        const child = childOf(fk);
+        const descriptor = declared.get(parent);
+        const rel = descriptor && Object.values(descriptor.relations).find(r => matches(fk, descriptor, r));
+        if (fk.child_lifecycle && (!rel || fk.action !== expectedAction(rel, fk.child_lifecycle))) {
+          return `unsupported graph: path ${root} reaches undeclared lifecycle edge ${parent} -> ${child}`;
+        }
+        if (!['c', 'n', 'd'].includes(fk.action)) continue;
+        const deeper = walk(child);
+        if (deeper) return deeper;
+      }
+    };
+    const reason = walk(root);
+    if (reason) refused.set(root, reason);
+  }
+  return refused;
+}

package/src/purge-log.ts

@@ -0,0 +1,63 @@
+/**
+ * The purge ledger contains keys and outcomes, never row payloads. Run this ensure
+ * as the table owner before purging. Only the lifecycle role may append receipts.
+ * Mutation guards also refuse a writer with direct privileges. The trusted owner
+ * can still disable these triggers; this is not a boundary against that owner.
+ */
+export const ENSURE_PURGE_LOG_SQL: string[] = [
+  'CREATE SCHEMA IF NOT EXISTS everystack',
+  `CREATE TABLE IF NOT EXISTS everystack.purge_log (
+    run_id uuid NOT NULL,
+    "table" text NOT NULL,
+    "key" text NOT NULL,
+    deleted_batch uuid,
+    deleted_at timestamptz NOT NULL,
+    purged_at timestamptz NOT NULL,
+    actor text,
+    outcome text NOT NULL CHECK (outcome IN ('purged', 'skipped', 'failed')),
+    hook text NOT NULL CHECK (hook IN ('ran', 'none', 'failed')),
+    detail text
+  )`,
+  'CREATE INDEX IF NOT EXISTS purge_log_key_time ON everystack.purge_log ("table", "key", purged_at)',
+  // Typed key comparisons still need an index that bounds the recent receipt window.
+  'CREATE INDEX IF NOT EXISTS purge_log_table_time ON everystack.purge_log ("table", purged_at)',
+  `CREATE OR REPLACE FUNCTION everystack.purge_log_refuse_mutation() RETURNS trigger
+    LANGUAGE plpgsql SET search_path = pg_catalog AS $guard$
+    BEGIN
+      RAISE EXCEPTION 'everystack.purge_log is append-only' USING ERRCODE = '42501';
+    END
+    $guard$`,
+  `CREATE OR REPLACE TRIGGER purge_log_no_mutation BEFORE UPDATE OR DELETE ON everystack.purge_log
+    FOR EACH ROW EXECUTE FUNCTION everystack.purge_log_refuse_mutation()`,
+  `CREATE OR REPLACE TRIGGER purge_log_no_truncate BEFORE TRUNCATE ON everystack.purge_log
+    FOR EACH STATEMENT EXECUTE FUNCTION everystack.purge_log_refuse_mutation()`,
+  // PUBLIC function defaults would become reachable after the new schema USAGE grant.
+  'REVOKE EXECUTE ON ALL FUNCTIONS IN SCHEMA everystack FROM PUBLIC',
+  'REVOKE ALL PRIVILEGES ON TABLE everystack.purge_log FROM PUBLIC',
+  `DO $acl$
+    DECLARE r record;
+    BEGIN
+      FOR r IN
+        SELECT DISTINCT roles.rolname
+        FROM (
+          SELECT acl.grantee
+          FROM pg_catalog.pg_class c CROSS JOIN LATERAL pg_catalog.aclexplode(c.relacl) acl
+          WHERE c.oid = 'everystack.purge_log'::regclass
+          UNION
+          SELECT acl.grantee
+          FROM pg_catalog.pg_attribute a CROSS JOIN LATERAL pg_catalog.aclexplode(a.attacl) acl
+          WHERE a.attrelid = 'everystack.purge_log'::regclass AND a.attnum > 0 AND NOT a.attisdropped
+        ) grants JOIN pg_catalog.pg_roles roles ON roles.oid = grants.grantee
+        WHERE grants.grantee <> 0 AND roles.oid <> (
+          SELECT c.relowner FROM pg_catalog.pg_class c WHERE c.oid = 'everystack.purge_log'::regclass
+        )
+      LOOP
+        EXECUTE pg_catalog.format('REVOKE ALL PRIVILEGES ON TABLE everystack.purge_log FROM %I', r.rolname);
+        EXECUTE pg_catalog.format('REVOKE ALL PRIVILEGES (run_id, "table", "key", deleted_batch, deleted_at, purged_at, actor, outcome, hook, detail) ON TABLE everystack.purge_log FROM %I', r.rolname);
+      END LOOP;
+    END
+    $acl$`,
+  'REVOKE ALL PRIVILEGES (run_id, "table", "key", deleted_batch, deleted_at, purged_at, actor, outcome, hook, detail) ON TABLE everystack.purge_log FROM PUBLIC',
+  'GRANT USAGE ON SCHEMA everystack TO everystack_lifecycle',
+  'GRANT INSERT ON TABLE everystack.purge_log TO everystack_lifecycle',
+];