@everystack/server 0.3.6 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -144,7 +144,7 @@
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
     "@everystack/auth": "0.4.0",
-    "@everystack/cli": "0.4.3"
+    "@everystack/cli": "0.4.5"
   },
   "scripts": {
     "test": "jest",

package/src/db.ts

@@ -262,3 +262,75 @@ export function getAdminSql(): ReturnType<typeof postgres> {
   if (adminSqlClient) return adminSqlClient;
   return getSql();
 }
+
+/**
+ * Resolve the read-replica database URL, if configured.
+ *
+ * The third credential slot: DATABASE_URL (api), ADMIN_DATABASE_URL (operator),
+ * READ_DATABASE_URL (replica). Point it at a physical read replica's endpoint
+ * with the SAME least-privilege role as DATABASE_URL — same credential,
+ * different host. Returns null when no replica is configured.
+ */
+export function getReadDatabaseUrl(): string | null {
+  // SST Secret — PascalCase (Resource.ReadDatabaseUrl.value)
+  const pascal = tryResource(() => (Resource as any).ReadDatabaseUrl?.value as string);
+  if (pascal) return pascal;
+  // SST Secret — raw env name (Resource.READ_DATABASE_URL.value)
+  const raw = tryResource(() => (Resource as any).READ_DATABASE_URL?.value as string);
+  if (raw) return raw;
+  // process.env fallback
+  if (process.env.READ_DATABASE_URL) return process.env.READ_DATABASE_URL;
+  return null;
+}
+
+// Lazy singleton read-replica connection (separate from the API connection)
+let readDbInstance: ReturnType<typeof drizzle> | null = null;
+let readSqlClient: ReturnType<typeof postgres> | null = null;
+
+/**
+ * Read-replica database connection for anonymous read traffic.
+ *
+ * Connects with READ_DATABASE_URL when configured. When it isn't, returns the
+ * primary connection (createDb) with NO warning — unlike the admin split this
+ * is a scaling knob, not a security boundary: absent is normal, not a
+ * misconfiguration. Apps without a replica keep working with zero config.
+ *
+ * `withRole` works unchanged against a hot standby: SET LOCAL ROLE and
+ * set_config(…, true) are permitted in read-only transactions, and physical
+ * replication carries roles, GRANTs, and RLS policies with the catalog. A
+ * write through this connection fails loudly on a real replica ("cannot
+ * execute … in a read-only transaction") — a routing bug can never silently
+ * diverge. See docs/plans/read-replica-routing.md.
+ */
+export function createReadDb<T extends Record<string, unknown>>(
+  schema: T,
+  options?: { maxConnections?: number }
+): {
+  db: ReturnType<typeof drizzle>;
+  schema: T;
+} {
+  if (readDbInstance) return { db: readDbInstance, schema };
+
+  const url = getReadDatabaseUrl();
+  if (!url) return createDb(schema, options);
+
+  readSqlClient = postgres(url, {
+    max: options?.maxConnections ?? 1,
+    idle_timeout: 60,
+    connect_timeout: 5,
+    max_lifetime: 60 * 5,
+    ssl: 'require',
+  });
+  readDbInstance = drizzle(readSqlClient, { schema });
+  return { db: readDbInstance, schema };
+}
+
+/**
+ * Raw postgres.js client for the read-replica connection.
+ * Must be called after createReadDb(). Falls back to the API client when no
+ * replica is configured (same fallback as createReadDb).
+ */
+export function getReadSql(): ReturnType<typeof postgres> {
+  if (readSqlClient) return readSqlClient;
+  return getSql();
+}

package/src/plugin.ts

@@ -731,46 +731,55 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       );
     };
 
-    // --- db:provision — create the role chain + set the login password ---
+    // --- db:provision — BOTH sides of the credential split, in the safe order ---
     // Runs as the operator and creates ONLY roles (no database, no tables, no schema), so
     // it is safe on an existing database: an app that brings its own DATABASE_URL can run
     // this to adopt the least-privilege split without re-provisioning anything. The
     // auto-provisioning construct invokes it at deploy time with a generated password.
+    // With adminPassword, also creates the operator login (migrator) and VERIFIES its
+    // real connectivity BEFORE the authenticator password is set — the ordering that
+    // keeps a BYO-database app from sawing off its own ops plane (see provision.ts).
     actions['db:provision'] = async (payload, _ctx) => {
-      const { authPassword, loginRole, appRoles } = (payload || {}) as {
-        authPassword?: string;
-        loginRole?: string;
-        appRoles?: string[];
-      };
       const { sql } = await import('drizzle-orm');
-      const { generateRoleChainSQL } = await import('./role-chain');
+      const { runProvision } = await import('./provision');
 
-      let roleSql: string;
-      try {
-        roleSql = generateRoleChainSQL({ loginRole, appRoles });
-      } catch (err: any) {
-        return { error: err?.message || String(err) };
-      }
-      await opsDb.execute(sql.raw(roleSql));
-
-      const role = loginRole ?? 'authenticator';
-      let passwordSet = false;
-      if (authPassword) {
-        // Generated via RandomPassword(special:false) — alphanumeric. Reject anything
-        // else so nothing untrusted is interpolated into the ALTER ROLE literal.
-        if (!/^[A-Za-z0-9]+$/.test(authPassword)) {
-          return { error: 'authPassword must be alphanumeric (generate via RandomPassword special:false or hex)' };
+      // Same host/port/database resolution as db:psql — the verification URL must
+      // point at the database this connection is actually provisioning.
+      let connection: { host: string; port?: number | string; database: string } | null = null;
+      if (options.connectionInfo) {
+        const info = await options.connectionInfo();
+        if (info?.host && info?.database) {
+          connection = { host: info.host, port: info.port, database: info.database };
+        }
+      } else {
+        try {
+          const { Resource } = await import('sst');
+          const db = (Resource as any).Database;
+          if (db?.host) connection = { host: db.host, port: db.port, database: db.database };
+        } catch {
+          // No linked component and no callback — the admin login lands unverified.
         }
-        await opsDb.execute(sql.raw(`ALTER ROLE ${role} WITH LOGIN PASSWORD '${authPassword}';`));
-        passwordSet = true;
       }
 
-      return {
-        provisioned: true,
-        loginRole: role,
-        appRoles: appRoles ?? ['anon', 'authenticated', 'admin'],
-        passwordSet,
-      };
+      return await runProvision(
+        (payload || {}) as Parameters<typeof runProvision>[0],
+        {
+          execute: async (statement) => opsDb.execute(sql.raw(statement)),
+          connection,
+          connectProbe: async (url) => {
+            const { default: postgres } = await import('postgres');
+            // 'prefer' handles both TLS-required RDS and plain local Postgres.
+            const probe = postgres(url, { max: 1, connect_timeout: 5, ssl: 'prefer' });
+            try {
+              await probe`SELECT 1`;
+              await probe.unsafe('CREATE TEMP TABLE _everystack_provision_probe (x int)');
+              await probe.unsafe('DROP TABLE _everystack_provision_probe');
+            } finally {
+              await probe.end({ timeout: 1 });
+            }
+          },
+        },
+      );
     };
 
     // --- db:backup:probe — is the pg_dump layer attached, and does it match the server? ---

package/src/provision.ts

@@ -0,0 +1,129 @@
+/**
+ * runProvision — the db:provision orchestration: both sides of the credential split,
+ * in the only safe order.
+ *
+ * The split has two logins: the least-privilege `authenticator` the API connects as
+ * (DATABASE_URL), and the operator `migrator` that owns migrations/DDL
+ * (ADMIN_DATABASE_URL). Provisioning only the first half strands the operator path on
+ * the linked Postgres master — and for a BYO-database app (no linked component) the
+ * operator fallback bottoms out in DATABASE_URL itself, so rewriting it to the
+ * authenticator saws off the branch provision sits on: the next ops invoke (including
+ * the re-run that would fix it) dies "permission denied".
+ *
+ * Hence the ordering contract, pinned by __tests__/provision.test.ts:
+ *   1. role chain (NOLOGIN tiers + authenticator role, no password)
+ *   2. admin role + admin password
+ *   3. VERIFY the admin login with a real connection
+ *   4. only then the authenticator password — a failed verification aborts the swap.
+ *
+ * Dependency-injected (execute / connection / connectProbe) so the ordering is testable
+ * without a database; plugin.ts wires the real deps.
+ */
+
+import { generateRoleChainSQL, generateAdminRoleSQL } from './role-chain';
+
+export interface ProvisionPayload {
+  /** Password for the least-privilege API login. Alphanumeric only. */
+  authPassword?: string;
+  /** Password for the operator login. Alphanumeric only. Absent = today's half-split. */
+  adminPassword?: string;
+  loginRole?: string;
+  adminRole?: string;
+  appRoles?: string[];
+}
+
+export interface ProvisionDeps {
+  /** Run one SQL string on the (privileged) provisioning connection. */
+  execute: (sql: string) => Promise<unknown>;
+  /** host/port/database for the verification URL; null when unresolvable. */
+  connection?: { host: string; port?: number | string; database: string } | null;
+  /** Real login attempt as the admin role — resolves on success, throws on failure. */
+  connectProbe?: (url: string) => Promise<void>;
+}
+
+export interface ProvisionResult {
+  provisioned?: boolean;
+  loginRole?: string;
+  adminRole?: string;
+  appRoles?: string[];
+  passwordSet?: boolean;
+  adminPasswordSet?: boolean;
+  /** true = login proven; null = no way to probe (unverified); absent = no admin requested. */
+  adminVerified?: boolean | null;
+  error?: string;
+}
+
+const ALNUM = /^[A-Za-z0-9]+$/;
+
+export async function runProvision(
+  payload: ProvisionPayload,
+  deps: ProvisionDeps,
+): Promise<ProvisionResult> {
+  const { authPassword, adminPassword, loginRole, adminRole, appRoles } = payload;
+
+  // Passwords are generated (RandomPassword special:false / hex) — reject anything else
+  // BEFORE any DDL runs, so nothing untrusted is interpolated into an ALTER ROLE literal.
+  if (authPassword && !ALNUM.test(authPassword)) {
+    return { error: 'authPassword must be alphanumeric (generate via RandomPassword special:false or hex)' };
+  }
+  if (adminPassword && !ALNUM.test(adminPassword)) {
+    return { error: 'adminPassword must be alphanumeric (generate via RandomPassword special:false or hex)' };
+  }
+
+  let roleSql: string;
+  let adminSql: string | null = null;
+  try {
+    roleSql = generateRoleChainSQL({ loginRole, appRoles });
+    if (adminPassword) adminSql = generateAdminRoleSQL({ adminRole });
+  } catch (err: any) {
+    return { error: err?.message || String(err) };
+  }
+
+  await deps.execute(roleSql);
+
+  const login = loginRole ?? 'authenticator';
+  const result: ProvisionResult = {
+    provisioned: true,
+    loginRole: login,
+    appRoles: appRoles ?? ['anon', 'authenticated', 'admin'],
+    passwordSet: false,
+  };
+
+  // Admin side FIRST — created and verified before the authenticator swap can happen.
+  if (adminPassword && adminSql) {
+    const admin = adminRole ?? 'migrator';
+    await deps.execute(adminSql);
+    await deps.execute(`ALTER ROLE ${admin} WITH LOGIN PASSWORD '${adminPassword}';`);
+    result.adminRole = admin;
+    result.adminPasswordSet = true;
+
+    if (deps.connection && deps.connectProbe) {
+      const { host, port, database } = deps.connection;
+      const url = `postgresql://${admin}:${adminPassword}@${host}:${port ?? 5432}/${database}`;
+      try {
+        await deps.connectProbe(url);
+        result.adminVerified = true;
+      } catch (err: any) {
+        // The whole point of the ordering: a broken admin login must abort the swap,
+        // or a BYO-database app loses its only privileged path.
+        return {
+          error:
+            `admin login verification failed for role '${admin}': ${err?.message || String(err)} — ` +
+            'the authenticator password was NOT set and DATABASE_URL must not be rewritten.',
+          adminRole: admin,
+          adminVerified: false,
+        };
+      }
+    } else {
+      result.adminVerified = null; // no way to probe — caller should verify via db:doctor
+    }
+  }
+
+  // Authenticator LAST — only reached when the admin side (if requested) held up.
+  if (authPassword) {
+    await deps.execute(`ALTER ROLE ${login} WITH LOGIN PASSWORD '${authPassword}';`);
+    result.passwordSet = true;
+  }
+
+  return result;
+}

package/src/role-chain.ts

@@ -73,3 +73,35 @@ export function generateRoleChainSQL(options: RoleChainOptions = {}): string {
 
   return lines.join('\n') + '\n';
 }
+
+export interface AdminRoleOptions {
+  /**
+   * The LOGIN role operator tasks (migrate/seed/DDL/console) connect as — the OTHER half
+   * of the credential split, so the master credential stops being the working credential.
+   * INHERIT (unlike the authenticator): its power comes from owner-role membership, and it
+   * must hold it ambiently to run DDL over owner-created objects. Default 'migrator'.
+   */
+  adminRole?: string;
+}
+
+/**
+ * Generate idempotent DDL for the operator (admin) login role. Membership is granted BOTH
+ * ways with the CURRENT user (the master/owner running the provision): owner → admin gives
+ * the admin ownership rights over every owner-created object (no REASSIGN OWNED), and
+ * admin → owner keeps the owner able to manage objects the admin creates later. The grants
+ * are guarded so a RE-provision running AS the admin role (post-split, the ops connection
+ * is this role) never attempts the self-grant Postgres hard-errors on. Does NOT set a
+ * password — that's `db:provision`'s job, from a deploy-generated value.
+ */
+export function generateAdminRoleSQL(options: AdminRoleOptions = {}): string {
+  const adminRole = options.adminRole ?? 'migrator';
+  assertIdent(adminRole, 'adminRole');
+
+  const lines: string[] = [
+    `DO $$ BEGIN IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = '${adminRole}') THEN CREATE ROLE ${adminRole} LOGIN INHERIT NOBYPASSRLS; END IF; END $$;`,
+    `ALTER ROLE ${adminRole} WITH LOGIN INHERIT NOBYPASSRLS;`,
+    `DO $$ BEGIN IF current_user <> '${adminRole}' THEN EXECUTE format('GRANT %I TO ${adminRole}', current_user); EXECUTE format('GRANT ${adminRole} TO %I', current_user); END IF; END $$;`,
+  ];
+
+  return lines.join('\n') + '\n';
+}