@everystack/server 0.2.21 → 0.2.24

package/README.md

@@ -365,4 +365,8 @@ Part of [everystack](https://github.com/scalable-technology/everystack) — a se
 
 ## License
 
-MIT
+[AGPL-3.0-only](https://www.gnu.org/licenses/agpl-3.0.html) © Scalable Technology, Inc.
+
+A commercial license is available for organizations that cannot or do not wish to
+comply with the AGPL-3.0 terms. For commercial licensing, contact
+licensing@scalable.technology.

package/jest-preset.js

@@ -0,0 +1,63 @@
+/**
+ * Drop-in jest config for a consumer's server-boundary test project (the one
+ * that imports `@everystack/server/testing`).
+ *
+ *   // jest.config.js
+ *   module.exports = { preset: '@everystack/server' };
+ *
+ * Note the value is the package name, NOT '@everystack/server/jest-preset':
+ * jest appends `/jest-preset.js` to the preset string itself, so it resolves
+ * this file as `@everystack/server/jest-preset.js`.
+ *
+ * Why a preset is needed
+ * ----------------------
+ * @everystack packages ship TypeScript source, and their subpaths (like
+ * `@everystack/server/testing`) are reachable only through the package
+ * `exports` map. Two things have to be true for a consumer to import them:
+ *
+ *  1. TypeScript must read the `exports` map. Only `node16`/`nodenext`/`bundler`
+ *     resolution does. ts-jest under `module: commonjs` silently falls back to
+ *     classic `node` resolution, which ignores `exports` → TS2307. NodeNext is
+ *     the one mode that reads `exports` AND emits CommonJS for jest. Its hybrid
+ *     module kind makes ts-jest warn TS151002; we silence only that one code
+ *     (NOT via `isolatedModules: true`, which would switch ts-jest to
+ *     transpile-only and drop type-checking entirely).
+ *
+ *  2. jest must TRANSFORM the shipped `.ts` source. Source in `node_modules` is
+ *     ignored by default, so the `transformIgnorePatterns` allowlist below opts
+ *     `@everystack/*` back in. (Inside this monorepo the pnpm symlink escapes
+ *     `node_modules` and hides this requirement — real installs need it.)
+ *
+ * Requires `ts-jest` and `typescript` in the consuming project (already present
+ * for any TS jest setup).
+ */
+module.exports = {
+  testEnvironment: 'node',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        tsconfig: {
+          module: 'NodeNext',
+          moduleResolution: 'NodeNext',
+          target: 'ES2022',
+          jsx: 'react-jsx',
+          esModuleInterop: true,
+          skipLibCheck: true,
+          types: ['jest', 'node'],
+        },
+        // 151002: "hybrid module kind needs isolatedModules" — expected under
+        // NodeNext; suppressing it keeps full type-checking on (real type errors
+        // in the consumer's tests still fail the suite).
+        diagnostics: { ignoreCodes: [151002] },
+      },
+    ],
+  },
+  // @everystack packages ship source, not built dist — transform them.
+  transformIgnorePatterns: ['/node_modules/(?!@everystack/)'],
+  // NodeNext consumers may write `.js` on relative ESM specifiers; map to source.
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+};

package/package.json

@@ -1,14 +1,25 @@
 {
   "name": "@everystack/server",
-  "version": "0.2.21",
+  "version": "0.2.24",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
+  "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scalable-technology/everystack.git",
+    "directory": "packages/server"
+  },
+  "homepage": "https://github.com/scalable-technology/everystack#readme",
+  "bugs": {
+    "url": "https://github.com/scalable-technology/everystack/issues"
+  },
   "publishConfig": {
     "access": "public"
   },
   "files": [
     "src",
     "stubs",
+    "jest-preset.js",
     "README.md"
   ],
   "exports": {
@@ -44,6 +55,8 @@
       "types": "./src/testing/index.ts",
       "default": "./src/testing/index.ts"
     },
+    "./jest-preset": "./jest-preset.js",
+    "./jest-preset.js": "./jest-preset.js",
     "./plugin": {
       "types": "./src/plugin.ts",
       "default": "./src/plugin.ts"
@@ -61,11 +74,6 @@
       "default": "./src/media.ts"
     }
   },
-  "scripts": {
-    "test": "jest",
-    "build": "tsc --build",
-    "lint": "tsc --noEmit"
-  },
   "peerDependencies": {
     "esbuild": ">=0.20.0",
     "@aws-sdk/client-cloudfront-keyvaluestore": ">=3.1053.0",
@@ -115,8 +123,6 @@
   "devDependencies": {
     "@aws-sdk/client-cloudfront-keyvaluestore": "3.1053.0",
     "@aws-sdk/signature-v4a": "3.1063.0",
-    "@everystack/auth": "workspace:*",
-    "@everystack/cli": "workspace:*",
     "@types/aws-lambda": "8.10.161",
     "@types/jest": "29.5.14",
     "@types/node": "22.19.18",
@@ -126,6 +132,13 @@
     "postgres": "3.4.9",
     "sst": "4.13.1",
     "ts-jest": "29.4.9",
-    "typescript": "5.9.3"
+    "typescript": "5.9.3",
+    "@everystack/auth": "0.2.6",
+    "@everystack/cli": "0.2.39"
+  },
+  "scripts": {
+    "test": "jest",
+    "build": "tsc --build",
+    "lint": "tsc --noEmit"
   }
-}
+}

package/src/db-doctor.ts

@@ -0,0 +1,229 @@
+/**
+ * db:doctor — "is my database actually secure?" in one command.
+ *
+ * The credential split is invisible until something tells you which role each Lambda
+ * really connects as. This is that instrument: it probes the api connection (createDb)
+ * and the admin connection (createAdminDb) from inside the VPC and reports, green/red,
+ * whether the api path is least-privilege and RLS-subject. It catches the exact traps
+ * that bit us by hand — an unwired DATABASE_URL secret (api still connects as the
+ * master), a missing FORCE ROW LEVEL SECURITY, a BYPASSRLS role on the api path.
+ *
+ * Pairs with `security:audit` (the SECDEF surface). This module is the pure classifier;
+ * the dbPlugin `db:doctor` action gathers the probe and the CLI prints the report.
+ *
+ * See docs/plans/secure-by-default-database.md.
+ */
+
+export interface ConnInfo {
+  /** current_user the connection runs as. */
+  role: string;
+  isSuperuser: boolean;
+  bypassRls: boolean;
+}
+
+export interface ForceRlsRow {
+  schema: string;
+  table: string;
+  /** RLS enabled on the table. */
+  enabled: boolean;
+  /** FORCE ROW LEVEL SECURITY (applies even to the owner). */
+  forced: boolean;
+}
+
+export interface DoctorProbe {
+  /** The api credential's connection facts (createDb / DATABASE_URL). */
+  api: ConnInfo;
+  /** The operator connection's facts (createAdminDb / ADMIN_DATABASE_URL). */
+  admin: ConnInfo;
+  /** Tables with RLS enabled, and whether it's FORCEd. Gathered as admin. */
+  forceRls: ForceRlsRow[];
+  /**
+   * Result of a bare `SELECT` on an RLS table as the api connection, WITHOUT setting a
+   * role. A least-privilege role (NOINHERIT, no grants of its own) must fail closed here;
+   * a role that returns rows carries ambient privileges (e.g. INHERIT + membership in a
+   * `USING(true)` role like the master). Absent when there is no RLS table to probe.
+   */
+  apiAmbientRead?: { table: string; accessible: boolean };
+}
+
+export type CheckStatus = 'pass' | 'fail' | 'warn';
+
+export interface Check {
+  name: string;
+  status: CheckStatus;
+  detail: string;
+  /** When the check fails, concrete guidance on how to fix it (shown by the CLI). */
+  remediation?: string;
+}
+
+export interface DoctorReport {
+  api: ConnInfo;
+  admin: ConnInfo;
+  checks: Check[];
+  /** True when no check failed (warnings are allowed). */
+  ok: boolean;
+}
+
+/** SQL run as a single connection to read its own security facts. */
+export const CONN_SQL = `
+SELECT
+  current_user AS role,
+  current_setting('is_superuser') = 'on' AS is_superuser,
+  COALESCE((SELECT rolbypassrls FROM pg_roles WHERE rolname = current_user), false) AS bypass_rls
+`.trim();
+
+/** SQL run as admin: every table with RLS enabled, and whether it is FORCEd. */
+export const FORCE_RLS_SQL = `
+SELECT
+  n.nspname AS schema,
+  c.relname AS "table",
+  c.relrowsecurity AS enabled,
+  c.relforcerowsecurity AS forced
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE c.relkind = 'r'
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+  AND c.relrowsecurity
+ORDER BY n.nspname, c.relname
+`.trim();
+
+/** Coerce a Postgres boolean (true | 't' | 'true' | 1) to a JS boolean. */
+export function pgBool(v: unknown): boolean {
+  return v === true || v === 't' || v === 'true' || v === 1 || v === '1';
+}
+
+/** Options for the report builder. */
+export interface DoctorReportOptions {
+  /**
+   * App-owned tables that are intentionally ENABLE-not-FORCE: an operational table whose
+   * owner (e.g. the worker, or a SECURITY DEFINER function) must read/write it, where FORCE
+   * would block the owner. These are added to the framework default (`auth.users`) and not
+   * flagged by the FORCE check. Example: `['ops.runs']` (the jobs queue the worker writes).
+   */
+  forceRlsCarveouts?: string[];
+}
+
+/** Build the green/red report from a gathered probe. Pure. */
+export function buildDoctorReport(probe: DoctorProbe, options: DoctorReportOptions = {}): DoctorReport {
+  const checks: Check[] = [];
+  const { api, admin } = probe;
+
+  // The headline check — does the api path actually run as a distinct least-privilege
+  // role, or is it the operator/master? Same role on both = the split isn't active
+  // (the classic unwired-secret trap: the api still connects as the master).
+  if (api.role === admin.role) {
+    checks.push({
+      name: 'API connection is least-privilege',
+      status: 'fail',
+      detail: `the api and operator connections both run as "${api.role}" — the credential split is not active (DATABASE_URL likely unwired; the API is using the operator/master credential)`,
+      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. '
+        + 'New apps get all of this automatically from the `everystack.Postgres` construct.',
+    });
+  } else {
+    checks.push({
+      name: 'API connection is least-privilege',
+      status: 'pass',
+      detail: `api runs as "${api.role}", operator as "${admin.role}"`,
+    });
+  }
+
+  checks.push({
+    name: 'API role is not a superuser',
+    status: api.isSuperuser ? 'fail' : 'pass',
+    detail: api.isSuperuser ? `"${api.role}" is a superuser — it bypasses RLS entirely` : `"${api.role}" is not a superuser`,
+  });
+
+  checks.push({
+    name: 'API role has no BYPASSRLS',
+    status: api.bypassRls ? 'fail' : 'pass',
+    detail: api.bypassRls ? `"${api.role}" has the BYPASSRLS attribute — every policy is skipped` : `"${api.role}" is subject to RLS`,
+  });
+
+  // The definitive least-privilege test: can the api connection read an RLS table with no
+  // SET ROLE? A role can pass "not superuser / no bypassrls / FORCE on" and still see every
+  // row through INHERITed membership in a USING(true) role (the master's leak path). Only a
+  // bare read proves it fails closed.
+  if (probe.apiAmbientRead) {
+    const { table, accessible } = probe.apiAmbientRead;
+    checks.push({
+      name: 'API connection fails closed (no ambient table access)',
+      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`,
+      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,
+    });
+  }
+
+  // FORCE coverage — RLS enabled but not FORCEd means the owner silently bypasses it.
+  //
+  // Carve-out: a credential table whose SECURITY DEFINER auth functions (verify the
+  // password, create the user) run as the table owner and MUST read/write it. FORCE would
+  // subject the owner to RLS and break sign_in/sign_up — and on managed Postgres (e.g. RDS)
+  // the owner is not a superuser, so it can't bypass FORCE either. Such a table is correctly
+  // ENABLE-but-not-FORCE: the API/SSR roles are non-owners and are still gated by its
+  // policies regardless of FORCE. `auth.users` (the @everystack/auth credential table) is
+  // the framework's one such table.
+  // auth.users is the framework's own credential carve-out (always); apps add operational
+  // tables whose owner must write them (e.g. ops.runs, the worker-written jobs queue).
+  const FORCE_RLS_CARVEOUTS = new Set(['auth.users', ...(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}`));
+  const unforced = allUnforced.filter((r) => !FORCE_RLS_CARVEOUTS.has(`${r.schema}.${r.table}`));
+  const carveNote = carved.length > 0
+    ? ` (${carved.map((r) => `${r.schema}.${r.table}`).join(', ')} intentionally ENABLE-not-FORCE: owner-written table(s) whose owner — a SECURITY DEFINER function or the worker — must bypass)`
+    : '';
+  if (probe.forceRls.length === 0) {
+    checks.push({
+      name: 'FORCE ROW LEVEL SECURITY on RLS tables',
+      status: 'warn',
+      detail: 'no tables have RLS enabled yet (nothing to force)',
+    });
+  } else if (unforced.length > 0) {
+    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('  '),
+    });
+  } else {
+    checks.push({
+      name: 'FORCE ROW LEVEL SECURITY on RLS tables',
+      status: 'pass',
+      detail: `all ${probe.forceRls.length - carved.length} protected RLS table(s) are FORCEd${carveNote}`,
+    });
+  }
+
+  return {
+    api,
+    admin,
+    checks,
+    ok: !checks.some((c) => c.status === 'fail'),
+  };
+}
+
+/** Map a CONN_SQL row to ConnInfo (tolerant of pg driver boolean encodings). */
+export function rowToConnInfo(row: any): ConnInfo {
+  return {
+    role: String(row.role),
+    isSuperuser: pgBool(row.is_superuser),
+    bypassRls: pgBool(row.bypass_rls),
+  };
+}
+
+/** Map a FORCE_RLS_SQL row to ForceRlsRow. */
+export function rowToForceRls(row: any): ForceRlsRow {
+  return {
+    schema: String(row.schema),
+    table: String(row.table),
+    enabled: pgBool(row.enabled),
+    forced: pgBool(row.forced),
+  };
+}

package/src/db.ts

@@ -26,11 +26,12 @@ function tryResource<T>(fn: () => T): T | undefined {
 }
 
 export function getDatabaseUrl(): string {
-  // SST Postgres component (Resource.Database)
-  const db = tryResource(() => Resource.Database);
-  if (db?.host) {
-    return `postgresql://${db.username}:${db.password}@${db.host}:${db.port}/${db.database}`;
-  }
+  // An EXPLICIT DATABASE_URL wins over the component-derived master. This is what
+  // lets the API connection be a least-privilege role (`authenticator`) while the SST
+  // Postgres component still exists to back the owner/ops credential. If the master
+  // resolved first, setting DATABASE_URL to a least-privilege role would be silently
+  // ignored. See docs/plans/credential-split-rls-everywhere.md.
+
   // SST Secret — PascalCase (Resource.DatabaseUrl.value)
   const pascal = tryResource(() => (Resource as any).DatabaseUrl?.value as string);
   if (pascal) return pascal;
@@ -39,9 +40,28 @@ export function getDatabaseUrl(): string {
   if (raw) return raw;
   // process.env fallback
   if (process.env.DATABASE_URL) return process.env.DATABASE_URL;
+  // Fallback: the SST Postgres component's master credential. Single-credential apps
+  // (no explicit DATABASE_URL) keep working; this is the privileged owner, so the
+  // createAdminDb fallback warning applies until the credentials are split.
+  const master = getMasterDatabaseUrl();
+  if (master) return master;
   throw new Error('DATABASE_URL not set — link an sst.aws.Postgres or sst.Secret, or set process.env.DATABASE_URL');
 }
 
+/**
+ * The SST Postgres component's master credential URL (the privileged owner), or null when no
+ * Postgres component is linked. This is the owner credential operator tasks fall back to when
+ * no dedicated ADMIN_DATABASE_URL is provisioned — kept separate from getDatabaseUrl() so the
+ * operator path never accidentally resolves the least-privilege DATABASE_URL secret.
+ */
+export function getMasterDatabaseUrl(): string | null {
+  const db = tryResource(() => Resource.Database);
+  if (db?.host) {
+    return `postgresql://${db.username}:${db.password}@${db.host}:${db.port}/${db.database}`;
+  }
+  return null;
+}
+
 /**
  * Resolve the operator (privileged) database URL, if configured.
  *
@@ -117,6 +137,69 @@ export function getSql(): ReturnType<typeof postgres> {
   return sqlClient;
 }
 
+// ---------------------------------------------------------------------------
+// withRole — the access primitive (RLS on every path)
+// ---------------------------------------------------------------------------
+
+/**
+ * The postgres.js transaction handle is callable as a tagged template, but its type
+ * (`TransactionSql` via `Omit<Sql, …>`) drops the call signature. Type callbacks
+ * against the plain callable `Sql` handle instead.
+ */
+export type RoleSql = ReturnType<typeof postgres>;
+
+// Postgres identifier rule — the only value ever interpolated into SET ROLE. Roles
+// come from server code, never user input, but validate defensively against injection.
+const ROLE_NAME = /^[a-z_][a-z0-9_]*$/;
+
+/**
+ * Run `fn` inside a transaction with the effective Postgres role and JWT claims set
+ * for its duration. This is THE access primitive on a least-privilege connection: RLS
+ * policies and column grants evaluate against `role`, and SQL functions read `auth.*`
+ * from the claims. A path that never calls this runs as the grant-less login role and
+ * **fails closed** — nothing here bypasses RLS.
+ *
+ *   role    one of your application roles (e.g. anon | authenticated | service) —
+ *           validated against the Postgres identifier rule, never user input.
+ *   claims  the `request.jwt.claims` payload; defaults to `{ role }` for roleless paths.
+ *
+ * `SET LOCAL` / `set_config(…, true)` are transaction-scoped, so they reset when the
+ * pooled connection returns — roles never leak between requests.
+ */
+export async function withRole<T>(
+  sql: ReturnType<typeof postgres>,
+  role: string,
+  claims: Record<string, unknown> | null,
+  fn: (tx: RoleSql) => Promise<T>,
+): Promise<T> {
+  if (!ROLE_NAME.test(role)) {
+    throw new Error(`Invalid role name: ${role}`);
+  }
+  const claimsJson = JSON.stringify(claims ?? { role });
+  return sql.begin(async (tx: any) => {
+    await tx.unsafe(`SET LOCAL ROLE ${role}`);
+    await tx.unsafe(`SELECT set_config('request.jwt.claims', $1, true)`, [claimsJson]);
+    return fn(tx as unknown as RoleSql);
+  }) as Promise<T>;
+}
+
+/**
+ * Effective role + claims for a request, derived from the verified JWT (or anon).
+ *
+ * Returns only `anon`/`authenticated` — the roles that may come from a token. The
+ * privileged `service` role is NEVER returned here; server code sets it explicitly via
+ * `withRole(sql, 'service', …)` after its own authorization check, so a forged or
+ * absent JWT can never reach it.
+ */
+export function roleFor(user?: Record<string, unknown> | null): {
+  role: 'anon' | 'authenticated';
+  claims: Record<string, unknown>;
+} {
+  return user
+    ? { role: 'authenticated', claims: user }
+    : { role: 'anon', claims: { role: 'anon' } };
+}
+
 // Lazy singleton operator DB connection (separate from the API connection)
 let adminDbInstance: ReturnType<typeof drizzle> | null = null;
 let adminSqlClient: ReturnType<typeof postgres> | null = null;
@@ -139,16 +222,23 @@ export function createAdminDb<T extends Record<string, unknown>>(
 } {
   if (adminDbInstance) return { db: adminDbInstance, schema };
 
-  const adminUrl = getAdminDatabaseUrl();
+  // Resolve the operator credential: an explicit ADMIN_DATABASE_URL, else the Postgres master
+  // (the privileged owner). NOT getDatabaseUrl()/createDb — post-split that resolves the
+  // least-privilege DATABASE_URL (authenticator), which cannot run operator tasks (migrate/
+  // seed/DDL) and fails "permission denied".
+  let adminUrl = getAdminDatabaseUrl();
   if (!adminUrl) {
-    if (!adminFallbackWarned) {
+    adminUrl = getMasterDatabaseUrl();
+    if (adminUrl && !adminFallbackWarned) {
       adminFallbackWarned = true;
       console.warn(
-        '[everystack/db] ADMIN_DATABASE_URL not set — operator tasks are using the '
-        + 'API connection (DATABASE_URL). If that role has BYPASSRLS, your RLS policies '
-        + 'are not enforced. Split the credentials: docs/plans/admin-database-url.md'
+        '[everystack/db] ADMIN_DATABASE_URL not set — operator tasks use the Postgres master '
+        + 'credential. Provision a dedicated ops owner role for full credential separation.'
       );
     }
+  }
+  if (!adminUrl) {
+    // No Postgres component at all (e.g. local dev with no DB linked) — last resort.
     return createDb(schema, options);
   }
 

package/src/plugin.ts

@@ -457,10 +457,17 @@ export interface DbPluginOptions {
   connectionInfo?: () => Promise<Record<string, string>>;
   /** Enable console action (default: true) */
   allowConsole?: boolean;
-  /** Read replica URL for db:query (default: process.env.READ_DATABASE_URL) */
+  /** Optional read-replica URL for db:query. When unset, db:query runs on the operator
+   *  connection. (No env fallback — pass it explicitly if you have a replica.) */
   readDatabaseUrl?: string;
   /** pgSettings callback for console auth context — applied via SET LOCAL when user is present */
   pgSettings?: (user: Record<string, unknown> | null) => Record<string, string>;
+  /**
+   * App-owned tables that are intentionally ENABLE-not-FORCE row-level security, so db:doctor
+   * does not flag them. The framework always carves out `auth.users`; add operational tables
+   * whose owner must write them, e.g. `['ops.runs']` (the worker-written jobs queue).
+   */
+  forceRlsCarveouts?: string[];
   /** Console auth helper config — column names for login/asUser (defaults to everystack conventions) */
   consoleAuth?: {
     usersTable?: string;
@@ -561,8 +568,8 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       try {
         const { sql } = await import('drizzle-orm');
         let queryDb = opsDb;
-        const readUrl = options.readDatabaseUrl ?? process.env.READ_DATABASE_URL;
-        if (readUrl && readUrl !== process.env.DATABASE_URL) {
+        const readUrl = options.readDatabaseUrl;
+        if (readUrl) {
           const { drizzle } = await import('drizzle-orm/postgres-js');
           const postgres = (await import('postgres')).default;
           queryDb = drizzle(postgres(readUrl, { max: 1, idle_timeout: 20, connect_timeout: 10 }));
@@ -575,6 +582,94 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       }
     };
 
+    // --- 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
+    // is a distinct least-privilege, RLS-subject role. Catches the unwired-secret trap
+    // (api still on the master), BYPASSRLS, and un-FORCEd RLS. See db-doctor.ts.
+    actions['db:doctor'] = async (_payload, ctx) => {
+      const { sql } = await import('drizzle-orm');
+      const {
+        buildDoctorReport, rowToConnInfo, rowToForceRls, CONN_SQL, FORCE_RLS_SQL,
+      } = await import('./db-doctor');
+      const rowsOf = (result: any): any[] => (Array.isArray(result) ? result : result?.rows || []);
+
+      const quoteIdent = (s: string) => '"' + String(s).replace(/"/g, '""') + '"';
+
+      let apiDb: any;
+      let api;
+      try {
+        const { createDb } = await import('./db');
+        apiDb = createDb(ctx.schema).db;
+        api = rowToConnInfo(rowsOf(await apiDb.execute(sql.raw(CONN_SQL)))[0]);
+      } catch (err: any) {
+        return { error: `api connection probe failed (DATABASE_URL): ${err?.message || String(err)}` };
+      }
+
+      const admin = rowToConnInfo(rowsOf(await opsDb.execute(sql.raw(CONN_SQL)))[0]);
+      const forceRls = rowsOf(await opsDb.execute(sql.raw(FORCE_RLS_SQL))).map(rowToForceRls);
+
+      // Ambient-access probe: can the api connection read an RLS table WITHOUT SET ROLE?
+      let apiAmbientRead: { table: string; accessible: boolean } | undefined;
+      if (forceRls.length > 0) {
+        const t = forceRls[0];
+        const ref = `${t.schema}.${t.table}`;
+        try {
+          await apiDb.execute(sql.raw(`SELECT 1 FROM ${quoteIdent(t.schema)}.${quoteIdent(t.table)} LIMIT 1`));
+          apiAmbientRead = { table: ref, accessible: true };
+        } catch {
+          apiAmbientRead = { table: ref, accessible: false };
+        }
+      }
+
+      return buildDoctorReport(
+        { api, admin, forceRls, apiAmbientRead },
+        { forceRlsCarveouts: options.forceRlsCarveouts },
+      );
+    };
+
+    // --- db:provision — create the role chain + set the login password ---
+    // 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.
+    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');
+
+      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)' };
+        }
+        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,
+      };
+    };
+
     // --- console ---
     if (options.allowConsole !== false) {
       actions['console:meta'] = async (_payload, ctx) => {