@everystack/server 0.3.7 → 0.4.1

package/package.json

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

package/src/db-doctor.ts

@@ -324,8 +324,13 @@ export function buildDoctorReport(probe: DoctorProbe, options: DoctorReportOptio
       remediation:
         'Run `everystack db:provision --stage <stage>` — it creates the least-privilege role chain on this '
         + 'database (idempotent, creates no database) AND writes the DATABASE_URL secret for you, without ever '
-        + 'printing the credential. Then in sst.config.ts declare `new sst.Secret("DatabaseUrl")`, link it to the '
-        + 'API function, and drop the raw Postgres component from the API link (keep it on ops/worker); redeploy. '
+        + 'printing the credential. PRECONDITION before flipping the API: the handler must escalate per request '
+        + '(pgSettings + SET ROLE / withRole) — the authenticator holds no privileges of its own (NOINHERIT), so a '
+        + 'handler that never escalates cannot even see the schema and every endpoint fails "relation does not exist". '
+        + 'Then flip in TWO deploys: (1) declare `new sst.Secret("DatabaseUrl")` and link it to the API function while '
+        + 'KEEPING the raw Postgres component linked (an explicit DatabaseUrl already outranks it, and the component is '
+        + 'your instant rollback — unlink the secret to revert); verify with real requests and `everystack db:doctor`; '
+        + '(2) then drop the raw Postgres component from the API link (keep it on ops/worker) and redeploy. '
         + 'New apps get all of this automatically from the `everystack.Postgres` construct.',
     });
   } else {
@@ -359,7 +364,7 @@ export function buildDoctorReport(probe: DoctorProbe, options: DoctorReportOptio
       status: accessible ? 'fail' : 'pass',
       detail: accessible
         ? `the api connection read "${table}" without setting a role — it carries ambient privileges (likely INHERIT + membership in a USING(true) role). A least-privilege role has no grants of its own and must SET ROLE first.`
-        : `the api connection cannot read "${table}" without SET ROLE — correct fail-closed behavior`,
+        : `the api connection cannot read "${table}" without SET ROLE — correct fail-closed behavior. NOTE the runtime requirement this creates: the handler MUST escalate per request (pgSettings + SET ROLE / withRole); a handler that never escalates fails every endpoint with "relation ... does not exist".`,
       remediation: accessible
         ? `Connect the API as a NOINHERIT role with no table grants of its own (e.g. \`authenticator\`), so memberships only apply via SET ROLE: \`ALTER ROLE <api_role> NOINHERIT;\` and revoke any direct table grants. The handler/SSR then escalate per-request via withRole().`
         : undefined,

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/role-chain.ts

@@ -85,13 +85,18 @@ export interface AdminRoleOptions {
 }
 
 /**
- * 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.
+ * Generate idempotent DDL for the operator (admin) login role. Membership is granted ONE
+ * way — owner → admin — giving the admin ownership rights over every owner-created object
+ * (no REASSIGN OWNED). Never the reverse: Postgres forbids circular role membership, and
+ * the 0.4.0 reciprocal grant broke the SECOND stage on a shared RDS instance (roles are
+ * INSTANCE-level; the first stage's `migrator ∈ owner` membership made the reciprocal a
+ * cycle — 'role "migrator" is a member of role "postgres"').
+ *
+ * Adoption over creation: the grant is skipped when the membership already exists (a
+ * prior stage or a manual setup made it) and when granting would FORM a cycle (the owner
+ * is already a member of the admin role in some prior topology). A re-provision running
+ * AS the admin role (post-split, the ops connection is this role) skips the self-grant
+ * Postgres hard-errors on. Does NOT set a password — that's `db:provision`'s job.
  */
 export function generateAdminRoleSQL(options: AdminRoleOptions = {}): string {
   const adminRole = options.adminRole ?? 'migrator';
@@ -100,7 +105,7 @@ export function generateAdminRoleSQL(options: AdminRoleOptions = {}): string {
   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 $$;`,
+    `DO $$ BEGIN IF current_user <> '${adminRole}' AND NOT pg_has_role('${adminRole}', current_user, 'MEMBER') AND NOT pg_has_role(current_user, '${adminRole}', 'MEMBER') THEN EXECUTE format('GRANT %I TO ${adminRole}', current_user); END IF; END $$;`,
   ];
 
   return lines.join('\n') + '\n';