@everystack/server 0.4.29 → 0.4.31

package/src/provision.ts

@@ -20,15 +20,22 @@
  * without a database; plugin.ts wires the real deps.
  */
 
-import { generateRoleChainSQL, generateAdminRoleSQL, generateSearchPathSQL, generateRotationPairSQL } from './role-chain';
+import { generateRoleChainSQL, generateAdminRoleSQL, generateSearchPathSQL, generateRotationPairSQL, generateReaderRoleSQL } from './role-chain';
 import {
   pgVersionRefusal,
   ownerFactsSql,
   granterCapabilitySql,
   planOwnerEnactment,
+  readerGrantFactsSql,
+  readerGrantCapabilitySql,
+  planReaderGrants,
+  unitRefusal,
+  type EnactmentPlan,
   type DeclaredOwner,
   type OwnerFactRow,
   type GranterCapabilityRow,
+  type ReaderGrantFactRow,
+  type ReaderGranterCapabilityRow,
 } from './owner-enactment';
 import {
   adopteeProbeSql,
@@ -41,13 +48,34 @@ import {
   type AdoptionFinding,
 } from './owner-adoption';
 
+/**
+ * The db:provision payload.
+ *
+ * Its Model-derived fields — `searchPath`, `declaredOwners`, `declaredObjects` — are computed by
+ * the CLI from the Models barrel, so the payload is a VERSIONED wire contract when it arrives over
+ * the `_action` wire. That version (`modelContract`, checked against `MODEL_WIRE_CONTRACT`) is
+ * enforced at the action boundary in plugin.ts, BEFORE any connection is resolved — see
+ * `model-wire.ts`. It is deliberately not modelled here: by the time this core runs, the payload
+ * has already been proven to speak this server's shape, and this file's job is the credential
+ * ordering, not the handshake. `@everystack/model/wire` holds the canonical declarations of
+ * `DeclaredOwner` and `Adoptee`; the local ones below are pinned equal to them by
+ * `__tests__/model-wire-shape.test.ts`.
+ */
 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;
+  /**
+   * Password for the SELECT-only reader login — the third credential, the one `db:query` connects
+   * as. Alphanumeric only. ABSENT = no reader role is created at all, byte-identical to today (a
+   * db:query with no reader keeps running on the operator connection; see plugin.ts).
+   */
+  readerPassword?: string;
   loginRole?: string;
   adminRole?: string;
+  /** The SELECT-only login. Default 'reader'. */
+  readerRole?: string;
   appRoles?: string[];
   /**
    * Declared owners to ENACT (brownfield ownership convergence, Gap 1). Each (owner, schema) the
@@ -129,6 +157,10 @@ export interface ProvisionResult {
   appRoles?: string[];
   passwordSet?: boolean;
   adminPasswordSet?: boolean;
+  /** The SELECT-only login that was created/adopted. Absent = no reader was requested. */
+  readerRole?: string;
+  /** false = the reader already existed as a live login and was NOT re-passworded (additive-only). */
+  readerPasswordSet?: boolean;
   /** true = login proven; null = no way to probe (unverified); absent = no admin requested. */
   adminVerified?: boolean | null;
   rotationPairsCreated?: boolean;
@@ -146,13 +178,24 @@ export interface ProvisionResult {
    * change) for the CLI to print; `findings` are the pre-adopt semantic audit; `refusals` block the
    * whole phase (a pre-flight obstacle, a missing master, or a required --confirm that was absent).
    * Like ENACT, refusals never abort credential provisioning and never throw.
+   *
+   * `warnings` is the SUCCEEDED-BUT half: the reassignment is committed, and something after it did
+   * not go cleanly (today: a self-granted membership that would not revoke). Never a refusal — a
+   * refusal says nothing was applied, and here everything was.
    */
   ownerAdoption?: {
     reassigned: number;
     manifest: Array<{ identity: string; kind: string; secdef: boolean; from: string; to: string }>;
     findings: AdoptionFinding[];
     refusals: string[];
+    warnings?: string[];
   };
+  /**
+   * The result of the reader's read grants (SELECT/USAGE/default privileges over the declared
+   * schemas). Absent when no reader was declared. Same contract as ENACT: refusals never abort
+   * anything and never throw — a reader that cannot read is loud, recoverable, and reported.
+   */
+  readerGrants?: { granted: number; refusals: string[] };
   error?: string;
 }
 
@@ -162,7 +205,7 @@ export async function runProvision(
   payload: ProvisionPayload,
   deps: ProvisionDeps,
 ): Promise<ProvisionResult> {
-  const { authPassword, adminPassword, loginRole, adminRole, appRoles, searchPath } = payload;
+  const { authPassword, adminPassword, readerPassword, loginRole, adminRole, readerRole, appRoles, searchPath } = 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.
@@ -172,12 +215,17 @@ export async function runProvision(
   if (adminPassword && !ALNUM.test(adminPassword)) {
     return { error: 'adminPassword must be alphanumeric (generate via RandomPassword special:false or hex)' };
   }
+  if (readerPassword && !ALNUM.test(readerPassword)) {
+    return { error: 'readerPassword must be alphanumeric (generate via RandomPassword special:false or hex)' };
+  }
 
   let roleSql: string;
   let adminSql: string | null = null;
+  let readerSql: string | null = null;
   try {
     roleSql = generateRoleChainSQL({ loginRole, appRoles });
     if (adminPassword) adminSql = generateAdminRoleSQL({ adminRole });
+    if (readerPassword) readerSql = generateReaderRoleSQL({ readerRole });
   } catch (err: any) {
     return { error: err?.message || String(err) };
   }
@@ -187,8 +235,10 @@ export async function runProvision(
   // we must not reset (additive-only); one created now gets its password set.
   const login = loginRole ?? 'authenticator';
   const admin = adminRole ?? 'migrator';
+  const reader = readerRole ?? 'reader';
   const authExisted = !!authPassword && !!deps.roleHasLogin && (await deps.roleHasLogin(login));
   const adminExisted = !!adminPassword && !!deps.roleHasLogin && (await deps.roleHasLogin(admin));
+  const readerExisted = !!readerPassword && !!deps.roleHasLogin && (await deps.roleHasLogin(reader));
 
   await deps.execute(roleSql);
 
@@ -290,6 +340,26 @@ export async function runProvision(
     result.passwordSet = true;
   }
 
+  // The SELECT-only reader LAST — it is the one login nothing else depends on, so it can never
+  // disturb the ordering contract above. Role + password only; its GRANTs are made by
+  // convergeOwnership, AFTER the CLI has written the secret: `GRANT ... ON ALL TABLES` takes an
+  // ACCESS EXCLUSIVE lock on every table it touches, and a step that can stall behind a long reader
+  // must never sit between the autocommitted `ALTER ROLE … PASSWORD` and the secret-store write
+  // (the lockout this file's ordering exists to prevent — see the closing note below).
+  if (readerPassword && readerSql) {
+    await deps.execute(readerSql);
+    result.readerRole = reader;
+    const readerSearchPathSql = searchPath ? generateSearchPathSQL(reader, searchPath) : null;
+    if (readerSearchPathSql) await deps.execute(readerSearchPathSql);
+    if (readerExisted) {
+      // Additive-only, same rule as the other two logins: never rewrite a live password.
+      result.readerPasswordSet = false;
+    } else {
+      await deps.execute(`ALTER ROLE ${reader} WITH LOGIN PASSWORD '${readerPassword}';`);
+      result.readerPasswordSet = true;
+    }
+  }
+
   // Ownership convergence (ENACT + ADOPT) is DELIBERATELY NOT here. It is the one part of the
   // provisioning flow that can wait on a lock (ADOPT's transaction) or outlive the Lambda clock,
   // and it sits AFTER the credential swap — so running it inside runProvision would put a
@@ -312,10 +382,10 @@ export async function runProvision(
  * (empty result) when nothing is declared or the caller cannot read (no `query` dep — an older CLI).
  */
 export async function convergeOwnership(
-  payload: Pick<ProvisionPayload, 'declaredOwners' | 'declaredObjects' | 'confirm' | 'adminRole'>,
+  payload: Pick<ProvisionPayload, 'declaredOwners' | 'declaredObjects' | 'confirm' | 'adminRole' | 'readerRole' | 'searchPath'>,
   deps: ProvisionDeps,
-): Promise<Pick<ProvisionResult, 'ownerEnactment' | 'ownerAdoption'>> {
-  const out: Pick<ProvisionResult, 'ownerEnactment' | 'ownerAdoption'> = {};
+): Promise<Pick<ProvisionResult, 'ownerEnactment' | 'ownerAdoption' | 'readerGrants'>> {
+  const out: Pick<ProvisionResult, 'ownerEnactment' | 'ownerAdoption' | 'readerGrants'> = {};
   if (!deps.query) return out;
   const operator = payload.adminRole ?? 'migrator';
 
@@ -334,11 +404,52 @@ export async function convergeOwnership(
       out.ownerAdoption = { reassigned: 0, manifest: [], findings: [], refusals: [`owner adoption failed (the transaction rolled back; credentials are untouched): ${err?.message ?? String(err)}`] };
     }
   }
+
+  // The reader's read grants — LAST, and here rather than in runProvision for the same reason ADOPT
+  // is here: `GRANT ... ON ALL TABLES` locks every table it touches, so it must never sit between
+  // the password swap and the secret write. A refusal (or a stall killed by the Lambda clock) leaves
+  // a reader that cannot read — loud, recoverable by a re-run, and stranding no credential.
+  if (payload.readerRole) {
+    try {
+      out.readerGrants = await grantReaderAccess(payload.readerRole, payload, operator, deps);
+    } catch (err: any) {
+      out.readerGrants = { granted: 0, refusals: [`reader grants failed (credentials are already saved; nothing is stranded): ${err?.message ?? String(err)}`] };
+    }
+  }
   return out;
 }
 
 const truthy = (v: unknown): boolean => v === true || v === 't' || v === 'true';
 
+/**
+ * Run `statements` as ONE transaction on `execute`, and leave the SESSION usable whatever happens.
+ *
+ * A statement that fails inside a multi-statement `BEGIN; … COMMIT;` string does NOT end the
+ * transaction: PostgreSQL leaves the session in an ABORTED transaction, where every later statement
+ * on that same connection fails with "current transaction is aborted, commands ignored until end of
+ * transaction block" — until something sends ROLLBACK. Both callers run on connections the caller
+ * opens once and keeps: the ops action holds ONE master connection across ENACT and then ADOPT, so
+ * an un-rolled-back ENACT failure would take ADOPT — a separate phase, on unrelated objects — down
+ * with it, reporting a stale abort instead of running its own probe.
+ *
+ * So a throw is followed by a best-effort ROLLBACK on the SAME connection, and the ORIGINAL error is
+ * rethrown unchanged. The rollback is a repair attempt, not a result: it is wrapped in its own
+ * try/catch so a failed rollback (a dead connection) can never mask or replace the failure that
+ * caused it — the caller must still see WHY the transaction failed.
+ */
+async function runTransaction(execute: (sql: string) => Promise<unknown>, statements: string[]): Promise<void> {
+  try {
+    await execute(`BEGIN;\n${statements.map((s) => `${s};`).join('\n')}\nCOMMIT;`);
+  } catch (err) {
+    try {
+      await execute('ROLLBACK;');
+    } catch {
+      // Best-effort only. The transaction's own error is the one that matters.
+    }
+    throw err;
+  }
+}
+
 function toFacts(rows: any[]): OwnerFactRow[] {
   return rows.map((r) => ({
     owner: String(r.owner),
@@ -380,9 +491,117 @@ async function enactOwners(
   const masterCaps = deps.master ? toCaps(await deps.master.query(granterCapabilitySql(owners))) : null;
 
   const plan = planOwnerEnactment(operator, facts, operatorCaps, masterCaps);
-  for (const stmt of plan.asOperator) await deps.execute(`${stmt};`);
-  for (const stmt of plan.asMaster) await deps.master!.execute(`${stmt};`);
-  return { enacted: plan.asOperator.length + plan.asMaster.length, refusals: plan.refusals };
+  // One transaction per OWNER (per connection) — not one per connection for the whole run. See
+  // applyUnits for why the grain moved; each set is still idempotent (a GRANT already in place is a
+  // no-op), so a rolled-back unit is simply re-run, and `runTransaction` is what keeps a failed one
+  // from aborting the session for whatever the caller runs on it next.
+  return applyUnits(plan, deps, runTransaction, (n) => ({ enacted: n.applied, refusals: n.refusals }));
+}
+
+/** Autocommit, statement by statement — the reader grants' runner. See applyUnits. */
+async function runSequentially(execute: (sql: string) => Promise<unknown>, statements: string[]): Promise<void> {
+  for (const s of statements) await execute(`${s};`);
+}
+
+/**
+ * Apply a routed plan ONE UNIT AT A TIME — a unit being one declared owner, or one of the reader's
+ * grant kinds for one schema, on one connection. Never the whole run as a single batch.
+ *
+ * THE GRAIN IS THE FIX. The subjects are independent of each other and every statement is
+ * idempotent, so batching them across subjects bought nothing and cost this: one owner whose GRANT
+ * the server rejected rolled back a co-batched, perfectly grantable owner, and the refusal named
+ * only the failure — not the casualty. Because the plan is rebuilt from the catalog on every run,
+ * the same batch then failed the same way on every later db:provision, and that owner never
+ * converged, silently. ADOPT stays all-or-nothing for the opposite reason: a half-adopted schema is
+ * residue db:reconcile chokes on. These grants have no such coupling.
+ *
+ * A unit that throws becomes a precise refusal naming its subject and carrying the runnable fix
+ * (`unitRefusal`); the run continues with the next unit. `run` is the unit's runner: ENACT wraps a
+ * unit in ONE transaction (`runTransaction`, which also leaves the shared session usable after a
+ * failure); the reader's grants stay autocommit, one statement at a time, because `GRANT ... ON ALL
+ * TABLES` takes an ACCESS EXCLUSIVE lock on every relation it touches and a transaction would hold
+ * those locks across the whole unit for no atomicity anyone needs.
+ */
+async function applyUnits<T>(
+  plan: EnactmentPlan,
+  deps: ProvisionDeps,
+  run: (execute: (sql: string) => Promise<unknown>, statements: string[]) => Promise<void>,
+  shape: (n: { applied: number; refusals: string[] }) => T,
+): Promise<T> {
+  const refusals = [...plan.refusals];
+  let applied = 0;
+  for (const unit of plan.units) {
+    const execute = unit.connection === 'master'
+      ? (s: string) => deps.master!.execute(s)
+      : (s: string) => deps.execute(s);
+    try {
+      await run(execute, unit.statements);
+      applied += unit.statements.length;
+    } catch (err: any) {
+      refusals.push(unitRefusal(unit, err?.message ?? String(err)));
+    }
+  }
+  return shape({ applied, refusals });
+}
+
+function toReaderFacts(rows: any[]): ReaderGrantFactRow[] {
+  return rows.map((r) => ({
+    schema: String(r.schema),
+    creator: String(r.creator ?? ''),
+    schemaExists: truthy(r.schema_exists),
+    creatorExists: truthy(r.creator_exists),
+    usageMissing: truthy(r.usage_missing),
+    selectMissing: truthy(r.select_missing),
+    // Two facts, never one — see ReaderGrantFactRow: either default-privilege kind can already be
+    // in place without the other, and folding them together starves the missing one forever.
+    tablesDefaultsMissing: truthy(r.tables_defaults_missing),
+    sequencesDefaultsMissing: truthy(r.sequences_defaults_missing),
+  }));
+}
+
+function toReaderCaps(rows: any[]): ReaderGranterCapabilityRow[] {
+  return rows.map((r) => ({
+    schema: String(r.schema),
+    creator: String(r.creator ?? ''),
+    canGrantUsage: truthy(r.can_grant_usage),
+    canGrantSelect: truthy(r.can_grant_select),
+    canSetDefaults: truthy(r.can_set_defaults),
+  }));
+}
+
+/**
+ * Probe (operator + master), route, and apply the SELECT-only reader's read grants over the app's
+ * declared schemas.
+ *
+ * The schemas are the app's declared set (the same ordered list the role-default search_path uses),
+ * falling back to `public` for an all-public app — the reader is scoped to what the app declares,
+ * never granted database-wide. The CREATING roles are the operator plus every declared object owner,
+ * because `ALTER DEFAULT PRIVILEGES` is recorded per creating role: covering only the operator would
+ * leave a later table created by a declared owner invisible to the reader.
+ *
+ * Idempotent by construction (the facts probe reports only what is missing), so a converged database
+ * runs zero statements and takes zero locks.
+ */
+async function grantReaderAccess(
+  reader: string,
+  payload: Pick<ProvisionPayload, 'declaredOwners' | 'searchPath'>,
+  operator: string,
+  deps: ProvisionDeps,
+): Promise<{ granted: number; refusals: string[] }> {
+  const query = deps.query!;
+  const schemas = payload.searchPath?.length ? payload.searchPath : ['public'];
+  const creators = [...new Set([operator, ...(payload.declaredOwners ?? []).map((o) => o.owner)])];
+
+  const facts = toReaderFacts(await query(readerGrantFactsSql(reader, schemas, creators)));
+  const operatorCaps = toReaderCaps(await query(readerGrantCapabilitySql(schemas, creators)));
+  const masterCaps = deps.master ? toReaderCaps(await deps.master.query(readerGrantCapabilitySql(schemas, creators))) : null;
+
+  const plan = planReaderGrants(reader, facts, operatorCaps, masterCaps);
+  // Unit by unit, exactly like ENACT: a schema whose relations a DBA owns — the grant the honest
+  // capability probe now refuses up front, and which can still fail on the server for a reason no
+  // probe sees — must not cost the reader its grants in every OTHER schema. Autocommit within the
+  // unit, unchanged: the locks these statements take are too heavy to hold across a transaction.
+  return applyUnits(plan, deps, runSequentially, (n) => ({ granted: n.applied, refusals: n.refusals }));
 }
 
 function toProbes(rows: any[]): AdopteeProbe[] {
@@ -418,13 +637,15 @@ async function adoptOwners(
   const vRefusal = pgVersionRefusal(Number(vRow?.v ?? 0));
   if (vRefusal) return { ...EMPTY_ADOPTION, refusals: [vRefusal] };
 
-  // ADOPT cannot run as the least-privilege operator (it would need INHERIT membership in the
-  // current owner `postgres`, which is the master). No master → a precise refusal, never an attempt.
+  // ADOPT reassigns on a master-capable connection (the linked SST Postgres master, else the
+  // ADMIN_DATABASE_URL operator secret — see getAdoptMasterUrl). A connection is present unless the
+  // app configures NEITHER. Its actual capability is probed below; this refusal is only the
+  // no-connection-at-all case.
   if (!deps.master) {
     return { ...EMPTY_ADOPTION, refusals: [
-      'ADOPT requires the master connection — the least-privilege operator cannot reassign a ' +
-      'postgres-owned object. Link an sst.aws.Postgres component (the master fallback), or run the ' +
-      'ALTER … OWNER TO statements as the master by hand.',
+      'ADOPT has no master-capable connection to reassign through. Provide an ADMIN_DATABASE_URL ' +
+      'secret for the stage (a privileged operator that owns/administers the objects), or link an ' +
+      'sst.aws.Postgres component. The least-privilege DATABASE_URL cannot reassign a postgres-owned object.',
     ] };
   }
 
@@ -464,9 +685,37 @@ async function adoptOwners(
 
   // One transaction: per-statement lock_timeout, all-or-nothing. `statements` may include SET
   // self-grants ahead of the ALTERs, so the count of reassignments is plan.reassigned, not statements.
-  const body = plan.statements.map((s) => `${s};`).join('\n');
-  await deps.master.execute(`BEGIN;\nSET LOCAL lock_timeout = '5000ms';\n${body}\nCOMMIT;`);
-  return { reassigned: plan.reassigned.length, manifest, findings, refusals: [] };
+  // The lock_timeout is DESIGNED to fire under contention, which makes the rollback runTransaction
+  // does on failure load-bearing here: this connection is the caller's, and it keeps using it.
+  const master = deps.master;
+  await runTransaction((s) => master.execute(s), [`SET LOCAL lock_timeout = '5000ms'`, ...plan.statements]);
+
+  // The self-granted SET was scaffolding: it exists so the ALTERs above are legal, and it must not
+  // outlive them, or every ADOPT run leaves another membership on the master. It cannot be revoked
+  // INSIDE the transaction (the ALTERs still need it there), so it is revoked strictly after the
+  // COMMIT, each as its own statement.
+  //
+  // GRANTED BY CURRENT_USER makes the revoke surgical: PG16 keys a membership on
+  // (role, member, grantor), so the master's own self-grant is a DIFFERENT row from the durable
+  // ADMIN grant somebody else made it — and that durable one is what lets the NEXT run self-grant.
+  // Naming the grantor takes back exactly what this run gave.
+  //
+  // Non-fatal by construction: the reassignment is already committed, so a failed revoke is a
+  // warning with the hand-fix, never a refusal and never a throw.
+  const warnings: string[] = [];
+  for (const owner of plan.selfGrantedOwners) {
+    const revoke = `REVOKE ${owner} FROM CURRENT_USER GRANTED BY CURRENT_USER;`;
+    try {
+      await deps.master.execute(revoke);
+    } catch (err: any) {
+      warnings.push(
+        `ADOPT self-granted SET on '${owner}' to reassign, and could not revoke it afterwards ` +
+        `(${err?.message ?? String(err)}). The reassignment IS committed — this leaves the master ` +
+        `holding a SET-only membership in '${owner}'. Revoke it by hand on the master:  ${revoke}`,
+      );
+    }
+  }
+  return { reassigned: plan.reassigned.length, manifest, findings, refusals: [], ...(warnings.length ? { warnings } : {}) };
 }
 
 /** Read superuser / bypassrls for a set of roles, on the master. */

package/src/role-chain.ts

@@ -125,6 +125,120 @@ export function generateRotationPairSQL(
   return lines.join('\n') + '\n';
 }
 
+export interface ReaderRoleOptions {
+  /**
+   * The LOGIN role read-only inspection (`db:query`, and anything else that only reads) connects
+   * as — the THIRD credential in the split. Default 'reader'.
+   */
+  readerRole?: string;
+}
+
+/**
+ * Generate idempotent DDL for the SELECT-only login role.
+ *
+ * WHY it exists: `db:query` (the read-only lane behind `db:psql -c`, `db:pull`, `db:doctor`,
+ * `security:audit`) runs its statement on the OPERATOR connection when no reader is configured.
+ * The read-only TRANSACTION stops the statement from writing, but the operator is still a role
+ * that COULD write — and a read-only transaction does not fence a function that opens its own
+ * connection (`dblink_exec`, `pg_background`), so on a database where those extensions exist the
+ * operator's write privilege is reachable from a "read-only" query. The fix is not a longer
+ * keyword blocklist; it is a role that HAS no write privilege to reach.
+ *
+ * The posture, and why each attribute:
+ *   - LOGIN        — it is a connection identity, not a tier reached by SET ROLE.
+ *   - NOINHERIT    — it never ambiently gains another role's privileges. Same posture as the
+ *                    authenticator.
+ *   - NOBYPASSRLS  — it reads through row-level security like any other client. A reader that
+ *                    bypassed RLS would turn an inspection tool into a data-exfiltration path.
+ *   - NO membership in the app-role chain (anon/authenticated/admin) and none in the owner
+ *                    roles — so there is no SET ROLE that reaches write privilege. Its access is
+ *                    exactly its own direct grants (generateReaderGrantSQL), nothing more.
+ *
+ * Idempotent, like the rest of this file: `IF NOT EXISTS`-guarded creation, then the attributes
+ * are re-asserted so a role created some other way is brought into compliance. Does NOT set a
+ * password — that is `db:provision`'s job, from a deploy-generated value.
+ */
+export function generateReaderRoleSQL(options: ReaderRoleOptions = {}): string {
+  const readerRole = options.readerRole ?? 'reader';
+  assertIdent(readerRole, 'readerRole');
+
+  return [
+    `DO $$ BEGIN IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = '${readerRole}') THEN CREATE ROLE ${readerRole} LOGIN NOINHERIT NOBYPASSRLS; END IF; END $$;`,
+    `ALTER ROLE ${readerRole} WITH LOGIN NOINHERIT NOBYPASSRLS;`,
+  ].join('\n') + '\n';
+}
+
+export interface ReaderGrantOptions {
+  /** The SELECT-only login the grants are made TO. Default 'reader'. */
+  readerRole?: string;
+  /** The app's declared schemas, ordered and deduped (declaredSearchPath). */
+  schemas: string[];
+  /**
+   * The roles that CREATE objects in those schemas — the operator (`migrator`) and any declared
+   * object owner. `ALTER DEFAULT PRIVILEGES` is recorded per creating role, so a default privilege
+   * set for the wrong role silently covers nothing.
+   */
+  creators: string[];
+}
+
+/** The reader's grants for ONE schema, grouped by the privilege the GRANTING connection needs. */
+export interface ReaderSchemaGrants {
+  schema: string;
+  /** GRANT USAGE ON SCHEMA — the granter must own the schema or hold USAGE WITH GRANT OPTION. */
+  usage: string;
+  /** GRANT SELECT on what exists today — the granter needs SELECT WITH GRANT OPTION on each relation. */
+  select: string[];
+  /**
+   * ALTER DEFAULT PRIVILEGES, per creating role — the granter must be a member of that role.
+   *
+   * The two object kinds are NAMED fields rather than one statement list, because the router gates
+   * them independently: PostgreSQL records them as separate `pg_default_acl` rows, so a database
+   * can hold one and lack the other (see ReaderGrantFactRow in owner-enactment.ts).
+   */
+  defaults: Array<{ creator: string; tables: string; sequences: string }>;
+}
+
+/**
+ * Generate the reader's read grants, scoped to the app's declared schemas.
+ *
+ * WHY these exact statements:
+ *   - `GRANT USAGE ON SCHEMA` is mandatory: without schema USAGE no object inside it is reachable,
+ *     whatever table grants exist. It confers no ability to create or write.
+ *   - `GRANT SELECT ON ALL TABLES` covers tables, views, matviews and foreign tables — everything
+ *     `db:query` reads.
+ *   - `GRANT SELECT ON ALL SEQUENCES` — SELECT, deliberately NOT USAGE. USAGE on a sequence permits
+ *     `nextval()`, which MUTATES it; SELECT reads `last_value` and nothing else. This is the one
+ *     place where the read-only-looking keyword is the wrong one.
+ *   - `ALTER DEFAULT PRIVILEGES ... FOR ROLE <creator>` so a table created by the next migration is
+ *     readable without a re-provision. Default privileges attach to the role that CREATES the
+ *     object, hence one statement per creating role rather than a bare `IN SCHEMA` (which would
+ *     silently cover only the role that happened to run the grant).
+ *
+ * Nothing here grants INSERT/UPDATE/DELETE/TRUNCATE/REFERENCES/TRIGGER, CREATE, or role membership.
+ * Returns statements WITHOUT trailing semicolons — the router (planReaderGrants) decides which
+ * connection runs each, and the caller terminates them.
+ */
+export function generateReaderGrantSQL(options: ReaderGrantOptions): ReaderSchemaGrants[] {
+  const readerRole = options.readerRole ?? 'reader';
+  assertIdent(readerRole, 'readerRole');
+  options.schemas.forEach((s) => assertIdent(s, 'schema'));
+  options.creators.forEach((c) => assertIdent(c, 'creator'));
+
+  return options.schemas.map((schema) => ({
+    schema,
+    usage: `GRANT USAGE ON SCHEMA ${schema} TO ${readerRole}`,
+    select: [
+      `GRANT SELECT ON ALL TABLES IN SCHEMA ${schema} TO ${readerRole}`,
+      `GRANT SELECT ON ALL SEQUENCES IN SCHEMA ${schema} TO ${readerRole}`,
+    ],
+    defaults: options.creators.map((creator) => ({
+      creator,
+      tables: `ALTER DEFAULT PRIVILEGES FOR ROLE ${creator} IN SCHEMA ${schema} GRANT SELECT ON TABLES TO ${readerRole}`,
+      sequences: `ALTER DEFAULT PRIVILEGES FOR ROLE ${creator} IN SCHEMA ${schema} GRANT SELECT ON SEQUENCES TO ${readerRole}`,
+    })),
+  }));
+}
+
 export interface AdminRoleOptions {
   /**
    * The LOGIN role operator tasks (migrate/seed/DDL/console) connect as — the OTHER half