@everystack/server 0.4.30 → 0.4.32

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,23 +178,50 @@ 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[] };
+  /**
+   * The PUBLIC-on-schema-`public` posture, and what (if anything) was done about it. Always present
+   * once convergence has run — `publicCanCreate: false` is the already-clean answer, and the CLI
+   * says nothing about it. Same non-fatal contract as ENACT: never throws, never aborts.
+   */
+  publicSchemaPosture?: PublicSchemaPosture;
   error?: string;
 }
 
+/** The result of the PUBLIC-on-`public` posture step. See `convergePublicSchemaPosture`. */
+export interface PublicSchemaPosture {
+  /** Does the PUBLIC pseudo-role hold CREATE on schema `public`? (The pre-PG15 default.) */
+  publicCanCreate: boolean;
+  /** Was the REVOKE applied AND verified? Only ever true when `publicCanCreate` was true. */
+  revoked: boolean;
+  /** Why it was not applied — the missing `--confirm`, a connection that cannot, a server refusal. */
+  refusals: string[];
+}
+
 const ALNUM = /^[A-Za-z0-9]+$/;
 
 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 +231,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 +251,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 +356,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 +398,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' | 'publicSchemaPosture'>> {
+  const out: Pick<ProvisionResult, 'ownerEnactment' | 'ownerAdoption' | 'readerGrants' | 'publicSchemaPosture'> = {};
   if (!deps.query) return out;
   const operator = payload.adminRole ?? 'migrator';
 
@@ -334,11 +420,184 @@ 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)}`] };
+    }
+  }
+
+  // The PUBLIC-on-`public` posture — LAST, and UNCONDITIONAL. It is a property of the DATABASE, not
+  // of what the Models declare, so it must not hide behind the declared-ownership guards above: the
+  // brownfield app with nothing declared is precisely the one most likely to carry the pre-PG15
+  // grant. One catalog read on a converged database, one statement when the operator has confirmed.
+  try {
+    out.publicSchemaPosture = await convergePublicSchemaPosture(deps, !!payload.confirm);
+  } catch (err: any) {
+    out.publicSchemaPosture = { publicCanCreate: false, revoked: false, refusals: [
+      `the schema "public" posture check 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';
 
+/** The one statement this step ever sends. Also the fix SQL every refusal below hands back. */
+export const REVOKE_PUBLIC_CREATE_SQL = 'REVOKE CREATE ON SCHEMA public FROM PUBLIC';
+
+/**
+ * The posture probe: does the PUBLIC pseudo-role hold CREATE on schema `public`, and can THIS
+ * connection take it away?
+ *
+ * `public_can_create` reads the ACL directly rather than asking `has_schema_privilege('public', …)`.
+ * Both answer correctly on a live server (measured, PG16), but the ACL read is the idiom the rest of
+ * this file already uses (`toFacts`/`toCaps` over `aclexplode`) and it is unambiguous: grantee 0 IS
+ * the PUBLIC pseudo-role, whereas the literal `'public'` in `has_schema_privilege` is a special-cased
+ * NAME that resolves to no row in `pg_roles`. A NULL `nspacl` (owner-only defaults, and what a
+ * hand-recreated `public` schema carries on every version) explodes to zero rows — correctly, no grant.
+ *
+ * This is deliberately NOT `server_version_num`. PG15 removed the grant as a DEFAULT; it says nothing
+ * about the database in front of us. A PG16 database restored from a pre-15 dump still carries it, and
+ * an operator can re-add it on any version with one legal statement. The catalog is the only truth.
+ *
+ * `can_revoke` is the capability half, and it is load-bearing for a reason PostgreSQL makes easy to
+ * miss: a REVOKE run by a role that does not administer the schema DOES NOT FAIL. It emits
+ * `WARNING: no privileges could be revoked for "public"` and returns success with the grant still in
+ * place. `pg_has_role(current_user, nspowner, 'USAGE')` is true for the schema's owner, for a member
+ * of it, and for a superuser — exactly the set that can actually revoke.
+ */
+export const PUBLIC_SCHEMA_POSTURE_SQL = `SELECT
+  EXISTS (
+    SELECT 1 FROM pg_namespace n, aclexplode(n.nspacl) a
+    WHERE n.nspname = 'public' AND a.grantee = 0 AND a.privilege_type = 'CREATE'
+  ) AS public_can_create,
+  EXISTS (
+    SELECT 1 FROM pg_namespace n
+    WHERE n.nspname = 'public' AND pg_has_role(current_user, n.nspowner, 'USAGE')
+  ) AS can_revoke`;
+
+/**
+ * Converge the PUBLIC-on-schema-`public` posture — detect always, act only under `confirm`.
+ *
+ * THE GAP. Before PG15, `CREATE ON SCHEMA public` was granted to the PUBLIC pseudo-role by default.
+ * PG15 removed that default. Where it is still in place, every login this file provisions —
+ * authenticator, migrator, reader — can create objects in `public` through an ambient grant none of
+ * them was given, whatever its own privileges say. A schema anyone can write is also a search_path
+ * hijack surface: plant a shadow object there and a privileged session resolving through `public`
+ * runs it (the same chain `security-audit` reds on).
+ *
+ * WHY THIS IS GATED, when db:build revokes the same grant unconditionally. db:build refuses a
+ * non-empty target, so there is nothing in `public` to strand and no app to surprise. db:provision
+ * has no such guarantee: it runs against a LIVE, often long-running database, and some legacy apps
+ * genuinely create objects in `public` at runtime. Taking that away silently, mid-deploy, is a
+ * behaviour change no one asked for. So this reports by default and acts only when the operator has
+ * seen the report and re-run with `--confirm` — the same shape ADOPT uses for its runtime-changing
+ * reassignments.
+ *
+ * ROUTED like ENACT's grants: the operator's own connection when it administers `public`, the master
+ * when it does not, and a refusal carrying the runnable SQL when neither can. VERIFIED after the
+ * fact, because — see PUBLIC_SCHEMA_POSTURE_SQL — an under-privileged REVOKE reports success while
+ * changing nothing, so "the statement ran" would have printed `revoked` over a wide-open database.
+ *
+ * Non-fatal by construction: it never throws. It runs strictly after the credential is in the secret
+ * store, so anything it fails to do is recoverable by a re-run and strands nothing.
+ */
+export async function convergePublicSchemaPosture(
+  deps: ProvisionDeps,
+  confirm: boolean,
+): Promise<PublicSchemaPosture> {
+  const query = deps.query;
+  if (!query) return { publicCanCreate: false, revoked: false, refusals: [] };
+
+  const [row] = await query(PUBLIC_SCHEMA_POSTURE_SQL);
+  if (!truthy(row?.public_can_create)) return { publicCanCreate: false, revoked: false, refusals: [] };
+
+  if (!confirm) {
+    return { publicCanCreate: true, revoked: false, refusals: [
+      'the PUBLIC pseudo-role holds CREATE on schema "public" — the pre-PG15 default, which PG15 ' +
+      'removed. Every login this provision created can place objects there through that ambient ' +
+      'grant, and a writable schema on a search path is a hijack surface for every privileged ' +
+      'session resolving through it. Taking it away can break an app that creates objects in ' +
+      '"public" at runtime, so it is NOT done silently: review, then re-run with --confirm. ' +
+      `The statement it would send:  ${REVOKE_PUBLIC_CREATE_SQL};`,
+    ] };
+  }
+
+  // Route to a connection that can actually revoke. The operator usually does not own `public`
+  // (postgres or pg_database_owner does), so the master is the normal venue.
+  let execute: ((sql: string) => Promise<unknown>) | null = null;
+  if (truthy(row?.can_revoke)) {
+    execute = deps.execute;
+  } else if (deps.master) {
+    const [masterRow] = await deps.master.query(PUBLIC_SCHEMA_POSTURE_SQL);
+    if (truthy(masterRow?.can_revoke)) execute = (s: string) => deps.master!.execute(s);
+  }
+  if (!execute) {
+    return { publicCanCreate: true, revoked: false, refusals: [
+      'cannot revoke PUBLIC\'s CREATE on schema "public": neither the operator connection nor the ' +
+      'master is the owner of schema "public" (nor a member of its owner). PostgreSQL would accept ' +
+      'the statement from them and change NOTHING — it warns "no privileges could be revoked" and ' +
+      `returns success. Run it as the schema's owner:  ${REVOKE_PUBLIC_CREATE_SQL};`,
+    ] };
+  }
+
+  try {
+    await execute(`${REVOKE_PUBLIC_CREATE_SQL};`);
+  } catch (err: any) {
+    return { publicCanCreate: true, revoked: false, refusals: [
+      `revoking PUBLIC's CREATE on schema "public" failed: ${err?.message ?? String(err)}. ` +
+      `Nothing else is affected — credentials are already saved. Fix:  ${REVOKE_PUBLIC_CREATE_SQL};`,
+    ] };
+  }
+
+  // VERIFY. The statement completing is not evidence (see above), so re-read the catalog.
+  const [after] = await query(PUBLIC_SCHEMA_POSTURE_SQL);
+  if (truthy(after?.public_can_create)) {
+    return { publicCanCreate: true, revoked: false, refusals: [
+      'the REVOKE was accepted but PUBLIC still holds CREATE on schema "public". PostgreSQL does ' +
+      'not error when a role that does not administer the schema revokes — it warns and changes ' +
+      `nothing. Run it as the schema's owner:  ${REVOKE_PUBLIC_CREATE_SQL};`,
+    ] };
+  }
+  return { publicCanCreate: true, revoked: true, refusals: [] };
+}
+
+/**
+ * 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 +639,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[] {
@@ -466,9 +833,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