@homeflare/alchemy 0.43.0 → 0.45.0

package/src/postgres/role-membership-sql.ts

@@ -0,0 +1,223 @@
+/**
+ * Membership statements and the catalog read behind them, split out of `role-sql.ts`
+ * (file cap). One file so `diff`, reconcile and the fake agree on the exact texts.
+ *
+ * ★ ONE PARENT PER STATEMENT. `pg_auth_members` keys a membership on three columns —
+ *   (parent, member, grantor) — so more than one row can exist for one parent name:
+ *   another grantor's `ADMIN`-option grant rides beside the safe one. A multi-role
+ *   `GRANT`/`REVOKE` list would make a partially-failed write harder to attribute.
+ * ★ SEAT GRANTS SAY `SET FALSE`. Upstream `GRANT` defaults `SET` to TRUE (`grant.sgml` at
+ *   REL_18_6), and `SET ROLE` to the parent is how `SUPERUSER` / `CREATEROLE` / `CREATEDB`
+ *   are exercised (`user-manag.sgml`). A safe seat membership is `ADMIN FALSE, SET FALSE`.
+ * ⛔ REVOKE BY GRANTOR. A plain `REVOKE parent FROM member` only touches rows the session's
+ *   own grantor made; Postgres 18 warns and leaves another grantor's rows standing
+ *   (`revoke.sgml`). Every revoke here names `GRANTED BY`. A mismatched grantor can still
+ *   produce only a warning; the catalog re-read below catches surviving unsafe rows.
+ */
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+import * as Effect from 'effect/Effect';
+import type { PgExecutor } from './database-sql.ts';
+import { quoteIdent, roleExists } from './database-sql.ts';
+import { PostgresRoleMembershipUnrepaired, PostgresRoleParentMissing } from './role-errors.ts';
+import type { PostgresRoleAttributes, PostgresRoleProps } from './role-attrs.ts';
+
+/** One `pg_auth_members` row as this family reads it: the parent name, the grantor who made
+ * the grant, and the three options a name-only compare would hide. `admin` true is `WITH ADMIN`;
+ * `inherit` true inherits the parent's privileges even when the member is NOINHERIT;
+ * `set` true (the `GRANT` default) lets the member `SET ROLE` to the parent. `grantor` is null
+ * only in an inconsistent catalog or a synthetic test row, not after an ordinary DROP ROLE:
+ * PostgreSQL tracks grantor dependencies. Keep the null guard as a defensive refusal. */
+export interface MembershipRow {
+  readonly parent: string;
+  readonly grantor: string | null;
+  readonly admin: boolean;
+  readonly set: boolean;
+  readonly inherit: boolean;
+}
+
+const MEMBERSHIP_SQL = `SELECT parent.rolname AS parent,
+    grantor.rolname AS grantor,
+    m.admin_option AS admin,
+    m.set_option AS set,
+    m.inherit_option AS inherit
+  FROM pg_auth_members m
+  JOIN pg_roles member ON member.oid = m.member
+  JOIN pg_roles parent ON parent.oid = m.roleid
+  LEFT JOIN pg_roles grantor ON grantor.oid = m.grantor
+  WHERE member.rolname = $1
+  ORDER BY parent.rolname, grantor.rolname NULLS FIRST`;
+
+export const selectRoleMemberships = (
+  pg: PgExecutor,
+  name: string,
+): Effect.Effect<readonly MembershipRow[], SqlError> =>
+  Effect.map(pg.unsafe<MembershipRow>(MEMBERSHIP_SQL, [name]), (rows) => rows);
+
+/** Seat grants say `SET FALSE`. Upstream `GRANT` defaults `SET` to TRUE, and `SET ROLE` to the
+ * parent is how `SUPERUSER` / `CREATEROLE` / `CREATEDB` are exercised (`user-manag.sgml`). */
+export const buildGrantMembershipSql = (member: string, parent: string): string =>
+  `GRANT ${quoteIdent(parent)} TO ${quoteIdent(member)} WITH SET FALSE`;
+
+/** ⛔ Do not repair with GRANT … ADMIN FALSE: measured in PR 336, that left grants made
+ * by the member standing after stripping its ADMIN. PG 16+ tracks dependent role grants:
+ * https://www.postgresql.org/docs/16/sql-grant.html#SQL-GRANT-DESCRIPTION-ROLES
+ * https://www.postgresql.org/docs/16/sql-revoke.html
+ * Measured 2026-10-02 on PG 17.11: REVOKE ADMIN OPTION … RESTRICT refuses dependents;
+ * without dependents, ADMIN/SET revocation keeps membership and its INHERIT bit intact.
+ * INHERIT revocation explicitly clears that bit for a declared NOINHERIT role.
+ * GRANTED BY targets the observed row, including a different grantor's row. */
+export const buildRepairMembershipSql = (
+  member: string,
+  parent: string,
+  grantor: string,
+  option: 'ADMIN' | 'SET' | 'INHERIT',
+): string =>
+  `REVOKE ${option} OPTION FOR ${quoteIdent(parent)} FROM ${quoteIdent(member)} GRANTED BY ${quoteIdent(grantor)} RESTRICT`;
+
+/** Remove one grantor's row for one parent. Naming the grantor is what makes the revoke
+ * bind: a plain `REVOKE` skips rows other grantors made (`revoke.sgml`). */
+export const buildRevokeGrantorMembershipSql = (
+  member: string,
+  parent: string,
+  grantor: string,
+): string =>
+  `REVOKE ${quoteIdent(parent)} FROM ${quoteIdent(member)} GRANTED BY ${quoteIdent(grantor)}`;
+
+/** ADMIN/SET are always unsafe; per-grant INHERIT is unsafe for declared NOINHERIT.
+ * PG 16–18 GRANT docs: the role attribute only defaults NEW membership grants. */
+export const unsafeMemberships = (
+  live: Omit<PostgresRoleAttributes, 'passwordSeal'>,
+  /** The DECLARED inherit flag (never the live one): a declared NOINHERIT role must see live
+   *  per-grant INHERIT rows as unsafe even when the live role flag says INHERIT. */
+  inherit: boolean,
+): ReadonlySet<string> =>
+  new Set(
+    (live.memberships ?? [])
+      .filter((row) => row.admin || row.set || (row.inherit && !inherit))
+      .map((row) => row.parent),
+  );
+
+/** Membership drift: sorted set difference between declared and live. Duplicates in the
+ * declaration collapse to one; `undefined` means "not asserted" — nothing to grant or revoke.
+ * A parent already granted `WITH ADMIN`, or with `SET` still at the upstream default TRUE, is
+ * a grant again: the name matches, but the options do not, so reconcile repairs in place. */
+export const membershipDrift = (
+  declared: readonly string[] | undefined,
+  live: readonly string[],
+  unsafe: ReadonlySet<string> = new Set(),
+): { readonly grants: readonly string[]; readonly revokes: readonly string[] } => {
+  if (declared === undefined) return { grants: [], revokes: [] };
+  const wanted = [...new Set(declared)].sort();
+  const current = [...new Set(live)].sort();
+  return {
+    grants: wanted.filter((parent) => !current.includes(parent) || unsafe.has(parent)),
+    revokes: [
+      ...current.filter((parent) => !wanted.includes(parent)),
+      ...wanted.filter((parent) => current.includes(parent) && unsafe.has(parent)),
+    ],
+  };
+};
+
+/** Refuse before any membership write when a declared parent is not in `pg_roles`. `GRANT` of a
+ * missing role is `42704` (`user.c@REL_18_6`), and on a create that error arrives only after
+ * `CREATE ROLE` has committed. */
+export const assertParentsExist = (
+  pg: PgExecutor,
+  role: string,
+  parents: readonly string[] | undefined,
+): Effect.Effect<void, PostgresRoleParentMissing | SqlError> =>
+  Effect.gen(function* () {
+    if (parents === undefined) return;
+    for (const parent of [...new Set(parents)].sort()) {
+      if (!(yield* roleExists(pg, parent))) {
+        return yield* Effect.fail(new PostgresRoleParentMissing({ role, parent }));
+      }
+    }
+  });
+
+/** Make live memberships equal the declaration, preserving wanted memberships in place.
+ * The previous full-options GRANT updated only its own grantor's row, then revoked other
+ * unsafe rows; it could silently strip ADMIN despite dependent grants (PR 336 round 2).
+ * Now each unsafe option is revoked by its observed grantor with RESTRICT. Unwanted rows
+ * commit first, so a blocked ADMIN repair cannot restore unwanted access (PR 349 review).
+ * Each retained row's options share a transaction, attributing a dependency/permission
+ * refusal to that parent and grantor. No CASCADE and no replacement grantor row.
+ * Unnameable grantors are defensive catalog-corruption cases, left to the typed backstop. */
+export const syncMemberships = (
+  pg: PgExecutor,
+  props: PostgresRoleProps,
+  rows: readonly MembershipRow[],
+): Effect.Effect<
+  readonly string[],
+  SqlError | PostgresRoleMembershipUnrepaired | PostgresRoleParentMissing
+> =>
+  Effect.gen(function* () {
+    if (props.memberOf === undefined) {
+      return [...new Set(rows.map((row) => row.parent))].sort();
+    }
+    yield* assertParentsExist(pg, props.name, props.memberOf);
+    const wanted = [...new Set(props.memberOf)].sort();
+    const revokes: string[] = [];
+    for (const row of rows) {
+      if (!wanted.includes(row.parent) && row.grantor !== null) {
+        revokes.push(buildRevokeGrantorMembershipSql(props.name, row.parent, row.grantor));
+      }
+    }
+    if (revokes.length > 0) yield* pg.transaction(revokes);
+    for (const row of rows) {
+      if (row.grantor === null || !wanted.includes(row.parent)) continue;
+      const statements: string[] = [];
+      for (const option of ['ADMIN', 'SET', 'INHERIT'] as const) {
+        const unsafe =
+          option === 'ADMIN'
+            ? row.admin
+            : option === 'SET'
+              ? row.set
+              : row.inherit && !props.inherit;
+        if (unsafe) {
+          statements.push(buildRepairMembershipSql(props.name, row.parent, row.grantor, option));
+        }
+      }
+      if (statements.length > 0)
+        yield* pg.transaction(statements).pipe(
+          Effect.catchTag('SqlError', (error) => {
+            // Both installed socket and psql transports preserve raw SQLSTATE here.
+            // Class 2B is UnknownError, class 42 is SqlSyntaxError; never match messages.
+            const cause = error.reason.cause;
+            const code =
+              typeof cause === 'object' && cause !== null
+                ? (cause as { code?: unknown }).code
+                : undefined;
+            return Effect.fail(
+              code === '2BP01' || code === '42501'
+                ? new PostgresRoleMembershipUnrepaired({
+                    role: props.name,
+                    parent: row.parent,
+                    grantor: row.grantor,
+                    declared: true,
+                  })
+                : error,
+            );
+          }),
+        );
+    }
+    // Absent-but-wanted parents get a fresh seat grant. Existing rows keep their grantor.
+    const grants = wanted
+      .filter((p) => !rows.some((row) => row.parent === p))
+      .map((parent) => buildGrantMembershipSql(props.name, parent));
+    if (grants.length > 0) yield* pg.transaction(grants);
+    // Backstop: anything not wanted or still unsafe fails typed.
+    for (const row of yield* selectRoleMemberships(pg, props.name)) {
+      if (!wanted.includes(row.parent) || row.admin || row.set || (row.inherit && !props.inherit)) {
+        return yield* Effect.fail(
+          new PostgresRoleMembershipUnrepaired({
+            role: props.name,
+            parent: row.parent,
+            grantor: row.grantor,
+            declared: wanted.includes(row.parent),
+          }),
+        );
+      }
+    }
+    return wanted;
+  });

package/src/postgres/role-password-ascii.test.ts

@@ -0,0 +1,53 @@
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { makeFakeSql } from './fake-sql.ts';
+import { diffPostgresRole } from './role-diff.ts';
+import { reconcileWithClient } from './role.ts';
+import { seal } from '../secrets/write-only.ts';
+import type { PostgresRoleAttributes } from './role-attrs.ts';
+
+const props = {
+  name: 'ascii-seat',
+  login: true,
+  inherit: true,
+  connectionLimit: -1,
+  password: { fromEnv: 'TEST_PASSWORD' },
+};
+const live: PostgresRoleAttributes = {
+  ...props,
+  oid: 42,
+  validUntil: null,
+  memberOf: [],
+  passwordSeal: '',
+};
+
+// Synthetic values cover SASLprep mapping, normalization and invalid Unicode; never credentials.
+test.each(['soft\u00adhyphen', 'caf\u00e9', '\u2168', '\ud800'])(
+  'non-ASCII case %# refuses create, adopt, sealed reconcile and diff without exposing input',
+  async (password) => {
+    const env = { TEST_PASSWORD: password };
+    const passwordSeal = seal({ password }, 'test-salt');
+    for (const exists of [false, true]) {
+      const fake = makeFakeSql({ roleRows: exists ? [live] : [] });
+      for (const previous of ['', passwordSeal]) {
+        const error = await Effect.runPromise(
+          reconcileWithClient(fake, props, env, previous).pipe(
+            Effect.catchTag('PostgresRolePasswordNonAsciiRefused', Effect.succeed),
+          ),
+        );
+        expect(error).toMatchObject({
+          _tag: 'PostgresRolePasswordNonAsciiRefused',
+          role: props.name,
+        });
+        expect(JSON.stringify(error)).not.toContain(password);
+        expect(fake.statements).toEqual([]);
+      }
+    }
+    const error = await Effect.runPromise(
+      diffPostgresRole(props, { ...live, passwordSeal }, env).pipe(
+        Effect.catchTag('PostgresRolePasswordNonAsciiRefused', Effect.succeed),
+      ),
+    );
+    expect(error).toHaveProperty('_tag', 'PostgresRolePasswordNonAsciiRefused');
+  },
+);

package/src/postgres/role-password-transports.test.ts

@@ -0,0 +1,123 @@
+/** Capture the actual Effect SQL spans and psql stdin, not just the builder's output. */
+import { expect, test } from 'bun:test';
+import * as PgClient from '@effect/sql-pg/PgClient';
+import * as Effect from 'effect/Effect';
+import * as Stream from 'effect/Stream';
+import * as Tracer from 'effect/Tracer';
+import * as Statement from 'effect/unstable/sql/Statement';
+import type { Connection } from 'effect/unstable/sql/SqlConnection';
+import type { PgExecutor } from './database-sql.ts';
+import { makeFakeSql } from './fake-sql.ts';
+import { type PsqlRunner, makePsqlExecutor } from './psql-executor.ts';
+import { reconcileWithClient } from './role.ts';
+
+const props = {
+  name: 'transport-seat',
+  login: true,
+  inherit: true,
+  connectionLimit: -1,
+  password: { fromEnv: 'TEST_PASSWORD' },
+};
+// Synthetic test input, deliberately recognizable if it escapes into captured telemetry.
+const password = 'kit336-plaintext-canary:must-never-reach-transport!';
+const env = { TEST_PASSWORD: password };
+const live = { ...props, oid: 42, validUntil: null, memberOf: [], passwordSeal: '' };
+
+test('SQL tracer captures only a verifier on create, rotate and failed ALTER', async () => {
+  for (const exists of [false, true]) {
+    for (const fail of [false, true]) {
+      const fake = makeFakeSql({
+        roleRows: exists ? [live] : [],
+        ...(fail ? { failNext: 'ALTER ROLE' } : {}),
+      });
+      const spans: Tracer.Span[] = [];
+      const tracer = Tracer.make({
+        span: (options) => {
+          const span = Tracer.nativeTracer.span(options);
+          spans.push(span);
+          return span;
+        },
+      });
+      const execute: Connection['execute'] = (sql, params) => fake.unsafe(sql, params);
+      const connection: Connection = {
+        execute,
+        executeUnprepared: execute,
+        executeRaw: (sql, params) => fake.unsafe(sql, params),
+        executeValues: () => Effect.succeed([]),
+        executeValuesUnprepared: () => Effect.succeed([]),
+        executeStream: () => Stream.empty,
+      };
+      // Use the installed SQL Statement and PG compiler: db.query.text is set by Effect,
+      // while only the connection beneath it is fake. A hand-written span would prove nothing.
+      const sql = Statement.make(
+        Effect.succeed(connection),
+        PgClient.makeCompiler(),
+        [],
+        undefined,
+      );
+      const pg: PgExecutor = {
+        unsafe: (text, params) => sql.unsafe(text, params),
+        transaction: (texts) =>
+          Effect.gen(function* () {
+            for (const text of texts) yield* sql.unsafe(text);
+          }),
+      };
+      const result = await Effect.runPromise(
+        Effect.exit(reconcileWithClient(pg, props, env, exists ? 'stale-seal' : '')).pipe(
+          Effect.provideService(Tracer.Tracer, tracer),
+        ),
+      );
+      expect(result._tag).toBe(fail ? 'Failure' : 'Success');
+      const attributes = spans.map((span) => Object.fromEntries(span.attributes));
+      const passwordQueries = attributes
+        .map((a) => a['db.query.text'])
+        .filter((text): text is string => typeof text === 'string' && text.includes('PASSWORD'));
+      expect(passwordQueries).toHaveLength(1);
+      expect(passwordQueries[0]).toContain("PASSWORD E'SCRAM-SHA-256$");
+      expect(JSON.stringify({ attributes, result })).not.toContain(password);
+    }
+  }
+});
+
+test('psql runner receives only a verifier; echoed failure and state hold no plain value', async () => {
+  for (const exists of [false, true]) {
+    for (const fail of [false, true]) {
+      const calls: Parameters<PsqlRunner>[0][] = [];
+      let created = exists;
+      const run: PsqlRunner = (call) => {
+        calls.push(call);
+        if (call.stdin.includes('PASSWORD') && fail) {
+          return Promise.resolve({
+            code: 3,
+            stdout: '',
+            stderr: `ERROR:  42501: refused\nSTATEMENT: ${call.stdin}`,
+          });
+        }
+        if (call.stdin.startsWith('BEGIN')) created = true;
+        return Promise.resolve({
+          code: 0,
+          stderr: '',
+          stdout: call.stdin.includes('FROM pg_roles r')
+            ? JSON.stringify(created ? [live] : [])
+            : '[]',
+        });
+      };
+      const result = await Effect.runPromise(
+        Effect.exit(
+          reconcileWithClient(
+            makePsqlExecutor(run, { database: 'postgres', username: 'postgres' }),
+            props,
+            env,
+            exists ? 'stale-seal' : '',
+          ),
+        ),
+      );
+      expect(result._tag).toBe(fail ? 'Failure' : 'Success');
+      const writes = calls.filter((call) => call.stdin.includes('PASSWORD'));
+      expect(writes).toHaveLength(1);
+      expect(writes[0]?.stdin).toContain("PASSWORD E'SCRAM-SHA-256$");
+      expect(JSON.stringify({ calls, result })).not.toContain(password);
+      expect(JSON.stringify(result)).not.toContain('SCRAM-SHA-256$');
+    }
+  }
+});

package/src/postgres/role-password.test.ts

@@ -0,0 +1,158 @@
+/**
+ * The write-only password lifecycle (S25) against `fake-sql.ts`'s recording fake: the
+ * declaration is the NAME of an environment variable, the value exists only in memory and on
+ * the wire of the one dedicated `ALTER ROLE … PASSWORD` statement, and what state remembers is
+ * a scrypt seal. Create, adopt, rotate and the never-guessed refusals.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import type { PgExecutor } from './database-sql.ts';
+import { seal, sealMatches } from '../secrets/write-only.ts';
+import { makeFakeSql } from './fake-sql.ts';
+import { PostgresRoleCreateVanished, PostgresRolePasswordEnvUnsetError } from './role-errors.ts';
+import type { PostgresRoleAttributes, PostgresRoleProps } from './role-attrs.ts';
+import { reconcileWithClient } from './role.ts';
+
+const run = <A, E>(eff: Effect.Effect<A, E>): Promise<A> => Effect.runPromise(eff);
+const fails = <A, E>(eff: Effect.Effect<A, E>): Promise<E> => Effect.runPromise(Effect.flip(eff));
+
+const baseProps: PostgresRoleProps = {
+  name: 'seat-observability',
+  login: false,
+  connectionLimit: 10,
+  inherit: true,
+};
+
+const liveRole = (over: Partial<PostgresRoleAttributes> = {}): PostgresRoleAttributes => ({
+  name: 'seat-observability',
+  oid: 20000,
+  login: false,
+  connectionLimit: 10,
+  inherit: true,
+  validUntil: null,
+  memberOf: [],
+  passwordSeal: '',
+  ...over,
+});
+
+const startingWith = (fake: ReturnType<typeof makeFakeSql>, prefix: string) =>
+  fake.statements.filter((s) => s.text.startsWith(prefix));
+
+const withPassword = {
+  ...baseProps,
+  password: { fromEnv: 'PG_SEAT_ROLE_PASSWORD' },
+};
+
+describe('password: create', () => {
+  test('travels in a dedicated ALTER, never in the CREATE, and only its seal lands in state', async () => {
+    const fake = makeFakeSql();
+    const attrs = await run(
+      reconcileWithClient(fake, withPassword, { PG_SEAT_ROLE_PASSWORD: 's3cret-value' }),
+    );
+    expect(startingWith(fake, 'CREATE ROLE')[0]?.text.includes('PASSWORD')).toBe(false);
+    // The statement carries the SCRAM-SHA-256 verifier, never the plain value: this is the text
+    // that reaches the span attribute `db.query.text` on the socket transport and the inlined
+    // stdin on the runner transport, so both are covered by one assertion over the shared text.
+    const sent = startingWith(fake, 'ALTER ROLE').map((s) => s.text);
+    expect(sent).toHaveLength(1);
+    expect(sent[0]).toMatch(/^ALTER ROLE "seat-observability" WITH PASSWORD E'SCRAM-SHA-256\$/);
+    expect(JSON.stringify(fake.statements)).not.toContain('s3cret-value');
+    expect(JSON.stringify(attrs)).not.toContain('s3cret-value');
+    // The seal stays a seal of the plain value — only the wire form changed.
+    expect(sealMatches(attrs.passwordSeal, { password: 's3cret-value' })).toBe(true);
+  });
+
+  test('a missing environment value refuses before any statement — never a guess', async () => {
+    const fake = makeFakeSql();
+    const error = await fails(reconcileWithClient(fake, withPassword, {}));
+    expect(error).toBeInstanceOf(PostgresRolePasswordEnvUnsetError);
+    expect((error as PostgresRolePasswordEnvUnsetError).variable).toBe('PG_SEAT_ROLE_PASSWORD');
+    // The reconcile reads first (one SELECT); the refusal lands before any write statement.
+    expect(startingWith(fake, 'CREATE').length).toBe(0);
+    expect(startingWith(fake, 'ALTER').length).toBe(0);
+  });
+});
+
+describe('password: live role', () => {
+  test('a rotated environment value rewrites the password under a fresh seal', async () => {
+    const oldSeal = seal({ password: 'old' }, 'fixed-salt');
+    const fake = makeFakeSql({ roleRows: [liveRole()] });
+    const attrs = await run(
+      reconcileWithClient(fake, withPassword, { PG_SEAT_ROLE_PASSWORD: 'new' }, oldSeal),
+    );
+    const sent = startingWith(fake, 'ALTER ROLE').map((s) => s.text);
+    expect(sent).toHaveLength(1);
+    expect(sent[0]).toMatch(/^ALTER ROLE "seat-observability" WITH PASSWORD E'SCRAM-SHA-256\$/);
+    expect(JSON.stringify(fake.statements)).not.toContain('new');
+    expect(sealMatches(attrs.passwordSeal, { password: 'new' })).toBe(true);
+    expect(sealMatches(attrs.passwordSeal, { password: 'old' })).toBe(false);
+  });
+
+  test('an unchanged environment value sends no password statement and keeps the seal bit-identical', async () => {
+    const oldSeal = seal({ password: 'old' }, 'fixed-salt');
+    const fake = makeFakeSql({ roleRows: [liveRole()] });
+    const attrs = await run(
+      reconcileWithClient(fake, withPassword, { PG_SEAT_ROLE_PASSWORD: 'old' }, oldSeal),
+    );
+    expect(fake.statements.some((s) => s.text.startsWith('ALTER'))).toBe(false);
+    expect(attrs.passwordSeal).toBe(oldSeal);
+  });
+
+  test('an adopted role (empty seal) gets the password written on the first reconcile that holds it', async () => {
+    const fake = makeFakeSql({ roleRows: [liveRole()] });
+    const attrs = await run(
+      reconcileWithClient(fake, withPassword, { PG_SEAT_ROLE_PASSWORD: 'first' }),
+    );
+    expect(startingWith(fake, 'ALTER ROLE').length).toBe(1);
+    expect(sealMatches(attrs.passwordSeal, { password: 'first' })).toBe(true);
+  });
+
+  test('an environment that went empty on a live role never churns the stored password', async () => {
+    const oldSeal = seal({ password: 'old' }, 'fixed-salt');
+    const fake = makeFakeSql({ roleRows: [liveRole()] });
+    const attrs = await run(
+      reconcileWithClient(fake, withPassword, { PG_SEAT_ROLE_PASSWORD: '' }, oldSeal),
+    );
+    expect(fake.statements.some((s) => s.text.startsWith('ALTER'))).toBe(false);
+    expect(attrs.passwordSeal).toBe(oldSeal);
+  });
+
+  test('a declared password whose seal is still empty refuses an unset variable on the update path', async () => {
+    // CREATE ROLE committed, then ALTER ROLE … PASSWORD failed or the process died before state
+    // was saved. The next run sees the role and an empty seal. Reporting success would leave a
+    // LOGIN role this stack has never sealed.
+    const fake = makeFakeSql({ roleRows: [liveRole({ login: true })] });
+    const error = await fails(
+      reconcileWithClient(fake, { ...withPassword, login: true }, { PG_SEAT_ROLE_PASSWORD: '' }),
+    );
+    expect(error).toBeInstanceOf(PostgresRolePasswordEnvUnsetError);
+    expect(fake.statements.some((s) => s.text.startsWith('ALTER'))).toBe(false);
+  });
+});
+
+describe('password: no new write statements on the no-op path', () => {
+  test('a create with no password declared never mentions PASSWORD at all', async () => {
+    const fake = makeFakeSql();
+    await run(reconcileWithClient(fake, baseProps));
+    expect(fake.statements.some((s) => s.text.includes('PASSWORD'))).toBe(false);
+  });
+
+  test('a vanished create on a password-carrying reconcile fails typed, with the password statement issued first', async () => {
+    // The blank executor answers every read with `[]` (absent), so the reconcile takes the
+    // create path: CREATE, then the dedicated password ALTER, then a re-read that finds nothing.
+    // The typed `PostgresRoleCreateVanished` surfaces that — the value stayed on the wire, and
+    // the failure is never a secret leak.
+    const unsafe = <A extends object>(_sql?: string) => Effect.succeed([] as ReadonlyArray<A>);
+    const blankPg: PgExecutor = {
+      unsafe,
+      transaction: (statements) =>
+        Effect.gen(function* () {
+          for (const sql of statements) yield* unsafe(sql).pipe(Effect.asVoid);
+        }),
+    };
+    const error = await fails(
+      reconcileWithClient(blankPg, withPassword, { PG_SEAT_ROLE_PASSWORD: 'v' }),
+    );
+    expect(error).toBeInstanceOf(PostgresRoleCreateVanished);
+  });
+});

package/src/postgres/role-privilege.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Adopt and alter of a role that already carries privileges this family never declares.
+ *
+ * The review of PR 336: `--adopt` of a SUPERUSER (or CREATEROLE / CREATEDB / REPLICATION /
+ * BYPASSRLS) role planned green and left the flag set, and a membership already granted
+ * `WITH ADMIN` matched by name so it was never revoked. `GRANT` also omitted `SET`, which
+ * upstream defaults to TRUE — a member can `SET ROLE` to the parent.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { makeFakeSql } from './fake-sql.ts';
+import { PostgresRolePrivilegedRefused } from './role-errors.ts';
+import type { PostgresRoleAttributes, PostgresRoleProps } from './role-attrs.ts';
+import { diffPostgresRole } from './role-diff.ts';
+import { reconcileWithClient } from './role.ts';
+
+const run = <A, E>(eff: Effect.Effect<A, E>): Promise<A> => Effect.runPromise(eff);
+const fails = <A, E>(eff: Effect.Effect<A, E>): Promise<E> => Effect.runPromise(Effect.flip(eff));
+
+const baseProps: PostgresRoleProps = {
+  name: 'seat-widget',
+  login: false,
+  connectionLimit: -1,
+  inherit: true,
+  memberOf: ['hf_agent'],
+};
+
+const liveRole = (over: Partial<PostgresRoleAttributes> = {}): PostgresRoleAttributes => ({
+  name: 'seat-widget',
+  oid: 20000,
+  login: false,
+  connectionLimit: -1,
+  inherit: true,
+  validUntil: null,
+  memberOf: ['hf_agent'],
+  passwordSeal: '',
+  superuser: false,
+  createrole: false,
+  createdb: false,
+  replication: false,
+  bypassrls: false,
+  ...over,
+});
+
+describe('adopted privilege flags', () => {
+  test('a live SUPERUSER is refused before any write', async () => {
+    const fake = makeFakeSql({ roleRows: [liveRole({ superuser: true })] });
+    const error = await fails(reconcileWithClient(fake, baseProps));
+    expect(error).toBeInstanceOf(PostgresRolePrivilegedRefused);
+    expect(
+      fake.statements.some((s) => s.text.startsWith('ALTER') || s.text.startsWith('GRANT')),
+    ).toBe(false);
+  });
+
+  test('a membership granted WITH ADMIN by this session is repaired in place', async () => {
+    const fake = makeFakeSql({ roleRows: [liveRole()], roles: ['hf_agent'] });
+    fake.memberships.add('seat-widget\0hf_agent\0postgres');
+    fake.membershipOptions.set('seat-widget\0hf_agent\0postgres', { admin: true, set: true });
+    await run(reconcileWithClient(fake, baseProps));
+    const texts = fake.statements.map((s) => s.text);
+    // Option revocation keeps the membership, while RESTRICT protects dependent grants.
+    expect(texts).toContain(
+      'REVOKE ADMIN OPTION FOR "hf_agent" FROM "seat-widget" GRANTED BY "postgres" RESTRICT',
+    );
+    expect(texts).toContain(
+      'REVOKE SET OPTION FOR "hf_agent" FROM "seat-widget" GRANTED BY "postgres" RESTRICT',
+    );
+    expect(texts.some((text) => text.startsWith('GRANT'))).toBe(false);
+    expect(fake.memberships.has('seat-widget\0hf_agent\0postgres')).toBe(true);
+    expect(fake.membershipOptions.has('seat-widget\0hf_agent\0postgres')).toBe(false);
+  });
+
+  test("another grantor's options are revoked while its membership remains", async () => {
+    const fake = makeFakeSql({ roleRows: [liveRole()], roles: ['hf_agent'] });
+    fake.memberships.add('seat-widget\0hf_agent\0other');
+    fake.membershipOptions.set('seat-widget\0hf_agent\0other', { admin: true, set: true });
+    await run(reconcileWithClient(fake, baseProps));
+    const texts = fake.statements.map((s) => s.text);
+    expect(texts).toContain(
+      'REVOKE ADMIN OPTION FOR "hf_agent" FROM "seat-widget" GRANTED BY "other" RESTRICT',
+    );
+    expect(texts).toContain(
+      'REVOKE SET OPTION FOR "hf_agent" FROM "seat-widget" GRANTED BY "other" RESTRICT',
+    );
+    expect(fake.memberships.has('seat-widget\0hf_agent\0other')).toBe(true);
+    expect(fake.memberships.has('seat-widget\0hf_agent\0postgres')).toBe(false);
+    expect(fake.membershipOptions.has('seat-widget\0hf_agent\0other')).toBe(false);
+  });
+});
+
+test.each(['superuser', 'createrole', 'createdb', 'replication', 'bypassrls'] as const)(
+  'live %s plans update and reconcile refuses before writing',
+  async (flag) => {
+    const live = liveRole({ [flag]: true });
+    expect(await run(diffPostgresRole(baseProps, liveRole(), {}, { found: live }))).toEqual({
+      action: 'update',
+    });
+    const fake = makeFakeSql({ roleRows: [live] });
+    const refused = await run(
+      reconcileWithClient(fake, baseProps, {}).pipe(
+        Effect.catchTag('PostgresRolePrivilegedRefused', (error) => Effect.succeed(error.flags)),
+      ),
+    );
+    expect(refused).toContain(flag.toUpperCase());
+    expect(fake.statements.every((s) => s.text.trimStart().startsWith('SELECT'))).toBe(true);
+  },
+);