@everystack/server 0.3.5 → 0.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "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/cli": "0.3.31",
-    "@everystack/auth": "0.3.1"
+    "@everystack/auth": "0.4.0",
+    "@everystack/cli": "0.4.5"
   },
   "scripts": {
     "test": "jest",

package/src/cdn/index.ts

@@ -38,6 +38,7 @@ export {
 export {
   stripSstDeadCode,
   applyWafExclusions,
+  applyWafRateLimit429,
   WAF_JSON_API_OVERRIDES,
 } from './transforms';
 

package/src/cdn/transforms.ts

@@ -155,3 +155,60 @@ export function applyWafExclusions(
     return rule;
   });
 }
+
+/**
+ * Rewrite rate-based-rule block actions to answer 429 + Retry-After instead
+ * of WAF's default 403.
+ *
+ * Google is explicit that the status code matters for SEO ("Don't use 403s
+ * or 404s for rate limiting"): every 4xx except 429 signals the content no
+ * longer exists and deindexes the URL over time, while 429/503 mean "back
+ * off and retry" — crawling slows almost immediately and Google retries for
+ * ~2 days before dropping anything. A per-IP rate rule clears within
+ * minutes of the burst ending, so a legitimate crawler never sees multi-day
+ * 429s. Getting this wrong turns a load shield into a deindexing engine.
+ *
+ * Only rules with a rateBasedStatement AND a block action are touched;
+ * managed rule groups (overrideAction) and count-mode rules pass through.
+ *
+ * @param rules  Resolved WAF rules array from Pulumi.
+ * @param retryAfterSeconds  Retry-After header value. Default 120.
+ *
+ * @example
+ * ```ts
+ * // In sst.config.ts — composes with applyWafExclusions in one transform.
+ * // MUST be registered BEFORE `new sst.aws.Router` (a $transform only
+ * // applies to resources created after it, and the Router creates the WebAcl).
+ * import { applyWafExclusions, applyWafRateLimit429 } from '@everystack/server/cdn';
+ *
+ * $transform(aws.wafv2.WebAcl, (args: any) => {
+ *   if (!args.rules) return;
+ *   args.rules = $resolve(args.rules).apply(
+ *     (rules) => applyWafRateLimit429(applyWafExclusions(rules)),
+ *   );
+ * });
+ * ```
+ */
+export function applyWafRateLimit429(
+  rules: any[],
+  retryAfterSeconds = 120,
+): any[] {
+  return rules.map((rule: any) => {
+    if (!rule.statement?.rateBasedStatement || !rule.action?.block) return rule;
+    return {
+      ...rule,
+      action: {
+        ...rule.action,
+        block: {
+          ...rule.action.block,
+          customResponse: {
+            responseCode: 429,
+            responseHeaders: [
+              { name: 'Retry-After', value: String(retryAfterSeconds) },
+            ],
+          },
+        },
+      },
+    };
+  });
+}

package/src/db-doctor.ts

@@ -67,8 +67,40 @@ export interface DoctorProbe {
    * `functions` teeth read this: for each schema that owns a `writtenBy: 'functions'` table
    * (passed as `functionSchemas`), the package's SECDEF functions must exist and each must
    * pin its search_path. Absent on an older probe (the check is then skipped).
+   *
+   * B4 also reads it globally: an unpinned SECDEF ANYWHERE is the runtime echo of the
+   * compile gate (defineFunction refuses to compile one) — warn-level outside the
+   * functions-teeth schemas, which keep their fail.
    */
   secdefFunctions?: SecdefFn[];
+  /**
+   * Functions PUBLIC can EXECUTE — PostgreSQL's silent-open default (a NULL proacl MEANS
+   * EXECUTE to PUBLIC; the query expands acldefault to see it). The declared derived layer
+   * revokes it unconditionally; anything here was created outside it or hand-granted back.
+   * Absent on an older probe (the check is then skipped). B4.
+   */
+  publicExecutableFunctions?: PublicExecutableFn[];
+  /**
+   * Views/matviews NO app role can read (no non-owner ACL entries) — superuser-only
+   * relations, the runtime echo of the derived read-gap gate. Declared-dark descriptors
+   * (`private: true`) also land here by design; the warn names both resolutions. Absent on
+   * an older probe (the check is then skipped). B4.
+   */
+  darkRelations?: DarkRelation[];
+}
+
+/** A function PUBLIC can EXECUTE, and whether it runs as its owner (the dangerous half). */
+export interface PublicExecutableFn {
+  schema: string;
+  name: string;
+  secdef: boolean;
+}
+
+/** A view ('v') or matview ('m') with no grants to any non-owner role. */
+export interface DarkRelation {
+  schema: string;
+  name: string;
+  kind: string;
 }
 
 /** A SECURITY DEFINER function and whether its `search_path` is pinned. */
@@ -143,6 +175,59 @@ WHERE p.prosecdef
 ORDER BY n.nspname, p.proname
 `.trim();
 
+/**
+ * Functions PUBLIC can EXECUTE. The trap this exists for: a NULL `proacl` is not "no
+ * grants" — it is PostgreSQL's BUILT-IN DEFAULT, which includes EXECUTE to PUBLIC, so the
+ * query expands `acldefault('f', proowner)` before exploding. Trigger-returning functions
+ * are excluded (not directly callable — PUBLIC EXECUTE on them is inert), as are
+ * extension-owned functions (not ours to judge) and system schemas. `secdef` marks the
+ * dangerous half: PUBLIC-callable code that runs as its OWNER.
+ */
+export const PUBLIC_EXECUTABLE_FUNCTIONS_SQL = `
+SELECT
+  n.nspname AS schema,
+  p.proname AS name,
+  p.prosecdef AS secdef
+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
+WHERE p.prokind IN ('f', 'p')
+  AND a.grantee = 0
+  AND a.privilege_type = 'EXECUTE'
+  AND p.prorettype <> 'trigger'::regtype
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_depend dep WHERE dep.objid = p.oid AND dep.deptype = 'e'
+  )
+GROUP BY n.nspname, p.proname, p.prosecdef
+ORDER BY n.nspname, p.proname
+`.trim();
+
+/**
+ * Views/matviews with no ACL entry for any non-owner role — readable by the superuser
+ * and nobody else. The runtime echo of the derived read-gap gate: on a modeled project
+ * this is either an object created outside the read model or a declared-dark descriptor.
+ */
+export const DARK_RELATIONS_SQL = `
+SELECT
+  n.nspname AS schema,
+  c.relname AS name,
+  c.relkind AS kind
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE c.relkind IN ('v', 'm')
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+  AND NOT EXISTS (
+    SELECT 1 FROM aclexplode(c.relacl) a WHERE a.grantee <> c.relowner
+  )
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_depend dep WHERE dep.objid = c.oid AND dep.deptype = 'e'
+  )
+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';
@@ -385,6 +470,75 @@ export function buildDoctorReport(probe: DoctorProbe, options: DoctorReportOptio
     }
   }
 
+  // B4 — the derived layer's runtime echoes (read-model-everywhere). Each check echoes a
+  // compile/check gate on the LIVE database: the gates cover what the models declare;
+  // these cover what actually exists, however it got there.
+
+  // PUBLIC-executable functions: fail when any runs as its owner (SECDEF — PUBLIC-callable
+  // privileged code), warn otherwise (invoker functions still run with the caller's
+  // rights, but PUBLIC EXECUTE is never a decision someone reviewed).
+  if (probe.publicExecutableFunctions) {
+    const offenders = probe.publicExecutableFunctions;
+    if (offenders.length > 0) {
+      const label = (f: PublicExecutableFn): string => `${f.schema}.${f.name}${f.secdef ? ' (SECURITY DEFINER)' : ''}`;
+      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.`,
+      });
+    } else {
+      checks.push({
+        name: 'Functions are not PUBLIC-executable',
+        status: 'pass',
+        detail: 'no function is executable by PUBLIC',
+      });
+    }
+  }
+
+  // Dark relations: readable by the superuser and nobody else — either created outside
+  // the read model, or declared dark on purpose. Warn, because only the author knows.
+  if (probe.darkRelations) {
+    if (probe.darkRelations.length > 0) {
+      checks.push({
+        name: 'Derived relations are readable or declared dark',
+        status: 'warn',
+        detail: `no app role can read: ${probe.darkRelations.map((r) => `${r.schema}.${r.name}`).join(', ')} — superuser-only relation(s)`,
+        remediation: `Declare can('read') on the descriptor (the compiler emits the GRANT), or private: true if it is intentionally dark — either way the decision lands in source.`,
+      });
+    } else {
+      checks.push({
+        name: 'Derived relations are readable or declared dark',
+        status: 'pass',
+        detail: 'every view/matview is granted to at least one role',
+      });
+    }
+  }
+
+  // The global SECDEF-pin echo: the compile gate refuses to DECLARE an unpinned SECDEF;
+  // this catches the ones that exist anyway (hand-created, pre-descriptor). The
+  // functions-teeth schemas keep their fail above — excluded here, never double-reported.
+  if (probe.secdefFunctions) {
+    const teeth = new Set(options.functionSchemas ?? []);
+    const unpinned = probe.secdefFunctions.filter((f) => !f.hasSearchPath && !teeth.has(f.schema));
+    if (unpinned.length > 0) {
+      checks.push({
+        name: 'Every SECURITY DEFINER function pins search_path',
+        status: 'warn',
+        detail: `unpinned SECDEF function(s) — owner-privilege hijack vector: ${unpinned.map((f) => `${f.schema}.${f.name}`).join(', ')}`,
+        remediation: unpinned.map((f) => `ALTER FUNCTION ${f.schema}.${f.name} SET search_path = pg_catalog;`).join('  ')
+          + ` Better: declare it with defineFunction({ security: 'definer', searchPath: [...] }) — the compiler refuses an unpinned one.`,
+      });
+    } else {
+      checks.push({
+        name: 'Every SECURITY DEFINER function pins search_path',
+        status: 'pass',
+        detail: `all ${probe.secdefFunctions.length} SECURITY DEFINER function(s) pin their search_path`,
+      });
+    }
+  }
+
   return {
     api,
     admin,
@@ -393,6 +547,24 @@ export function buildDoctorReport(probe: DoctorProbe, options: DoctorReportOptio
   };
 }
 
+/** Map a PUBLIC_EXECUTABLE_FUNCTIONS_SQL row to PublicExecutableFn. */
+export function rowToPublicExecutableFn(row: any): PublicExecutableFn {
+  return {
+    schema: String(row.schema),
+    name: String(row.name),
+    secdef: pgBool(row.secdef),
+  };
+}
+
+/** Map a DARK_RELATIONS_SQL row to DarkRelation. */
+export function rowToDarkRelation(row: any): DarkRelation {
+  return {
+    schema: String(row.schema),
+    name: String(row.name),
+    kind: String(row.kind),
+  };
+}
+
 /** Map a SECDEF_FUNCTIONS_SQL row to SecdefFn. */
 export function rowToSecdefFn(row: any): SecdefFn {
   return {

package/src/plugin.ts

@@ -186,6 +186,18 @@ export function createPluginLambdaHandler(
   ): Promise<APIGatewayProxyStructuredResultV2 | unknown> => {
     // Direct CLI invoke via Lambda Invoke — IAM is the auth layer.
     if ('_action' in event && typeof event._action === 'string') {
+      // Built-in health probe — `everystack deploy` invokes it right after a deploy so a bundle
+      // that can't initialize is caught at deploy time, not at the next db verb. Handled before
+      // the action lookup (it must answer even when initialization itself is the failure) and
+      // reserved: an app action named `_health` is never reached.
+      if (event._action === '_health') {
+        try {
+          const { actions } = await ensureInitialized();
+          return { ok: true, mode: httpEnabled ? 'http' : 'ops', actions: Object.keys(actions).sort() };
+        } catch (error) {
+          return { ok: false, error: String(error) };
+        }
+      }
       const { ctx, actions } = await ensureInitialized();
       const actionName = event._action;
       const actionHandler = actions[actionName];
@@ -505,7 +517,14 @@ export interface DbPluginOptions {
  * Contributes: migrate, seed, db:reset, db:psql, db:query, console.
  *
  * Usage:
- *   dbPlugin({ migrationsFolder: join(__dirname, '..', 'drizzle'), seed: runSeed })
+ *   dbPlugin({
+ *     migrationsFolder: join(__dirname, '..', 'drizzle'),
+ *     // Load the seed module LAZILY. Seed scripts are often also runnable directly
+ *     // (`node db/seed.ts`) and may connect or process.exit at import time — a static
+ *     // `import { runSeed }` runs that at Lambda INIT and crashes the ops plane before
+ *     // any handler exists. The dynamic import defers it to the moment db:seed runs.
+ *     seed: async (db, schema) => (await import('../db/seed.js')).runSeed(db, schema),
+ *   })
  */
 export function dbPlugin(options: DbPluginOptions): Plugin {
   return async (ctx: PluginContext): Promise<PluginContribution> => {
@@ -662,7 +681,9 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       const { sql } = await import('drizzle-orm');
       const {
         buildDoctorReport, rowToConnInfo, rowToForceRls, rowToAppGranted, rowToSecdefFn,
+        rowToPublicExecutableFn, rowToDarkRelation,
         CONN_SQL, FORCE_RLS_SQL, appGrantsRlsSql, SECDEF_FUNCTIONS_SQL,
+        PUBLIC_EXECUTABLE_FUNCTIONS_SQL, DARK_RELATIONS_SQL,
       } = await import('./db-doctor');
       const rowsOf = (result: any): any[] => (Array.isArray(result) ? result : result?.rows || []);
 
@@ -686,6 +707,10 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       // SECDEF functions (schema, name, search_path pinned?) — the `functions` teeth read these
       // to assert every SECDEF function in a functions-written schema pins its search_path.
       const secdefFunctions = rowsOf(await opsDb.execute(sql.raw(SECDEF_FUNCTIONS_SQL))).map(rowToSecdefFn);
+      // B4 — the derived layer's runtime echoes: PUBLIC-executable functions (NULL proacl
+      // included via acldefault) and superuser-only views/matviews.
+      const publicExecutableFunctions = rowsOf(await opsDb.execute(sql.raw(PUBLIC_EXECUTABLE_FUNCTIONS_SQL))).map(rowToPublicExecutableFn);
+      const darkRelations = rowsOf(await opsDb.execute(sql.raw(DARK_RELATIONS_SQL))).map(rowToDarkRelation);
 
       // Ambient-access probe: can the api connection read an RLS table WITHOUT SET ROLE?
       let apiAmbientRead: { table: string; accessible: boolean } | undefined;
@@ -701,51 +726,60 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       }
 
       return buildDoctorReport(
-        { api, admin, forceRls, appGrantedRls, apiAmbientRead, secdefFunctions },
+        { api, admin, forceRls, appGrantedRls, apiAmbientRead, secdefFunctions, publicExecutableFunctions, darkRelations },
         { forceRlsCarveouts: options.forceRlsCarveouts, functionSchemas: options.functionSchemas },
       );
     };
 
-    // --- 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';
+}