@homeflare/alchemy 0.43.0 → 0.45.0

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

@@ -0,0 +1,200 @@
+/**
+ * Provenance: every `PostgresRoleProps` field traces to a real `CREATE ROLE` synopsis option AND
+ * a real `pg_authid`/`pg_auth_members` column, every synopsis option this family does NOT expose
+ * is named with a reason, and the `ALTER ROLE` synopsis backs every field the family alters (plus
+ * the "memberships move via GRANT and REVOKE" note the membership statements lean on). All four
+ * fixtures are parsed, not eyeballed — deleting a fixture line, or adding a prop with no mapping,
+ * fails this file (S38, the house's provenance rule).
+ */
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const FIXTURES = join(import.meta.dir, 'fixtures');
+const createRole = readFileSync(join(FIXTURES, 'pg-REL_18_6-create_role.sgml.txt'), 'utf8');
+const alterRole = readFileSync(join(FIXTURES, 'pg-REL_18_6-alter_role.sgml.txt'), 'utf8');
+const authid = readFileSync(join(FIXTURES, 'pg-REL_18_6-pg_authid.h.txt'), 'utf8');
+const authMembers = readFileSync(join(FIXTURES, 'pg-REL_18_6-pg_auth_members.h.txt'), 'utf8');
+
+const CREATE_ROLE_BLOB = 'cee23b1ea6b4dcf2d9d356d07a582e64808c2912';
+const ALTER_ROLE_BLOB = '7b0a04bc4637c7c08246e597a9acf4466b467fa2';
+const AUTHID_BLOB = 'b2f3e9d01eec972a3392e7037c9679ac644ddc7b';
+const AUTH_MEMBERS_BLOB = '387316e44f07982264482f01f2298f4f85ffbafb';
+
+/** Each alternative of a "where <option> can be:" list, normalised to its leading keyword
+ * sequence, keeping the optional `[ ENCRYPTED ]` prefix and multi-word forms such as
+ * `CONNECTION LIMIT` / `VALID UNTIL` intact. */
+const optionTokens = (region: string): readonly string[] => {
+  const found: string[] = [];
+  for (const line of region.split('\n')) {
+    for (const raw of line.split('|')) {
+      const m = /^(\[ ENCRYPTED \] )?([A-Z]+(?: [A-Z]+)*)/.exec(raw.trim());
+      if (m !== null) found.push(`${m[1] ?? ''}${m[2] as string}`.trim());
+    }
+  }
+  return [...new Set(found)];
+};
+
+/** A `CATALOG` struct's column names, from the tab-indicated `type name;` lines. */
+const structColumns = (fixture: string): readonly string[] => {
+  const re = /^\t[A-Za-z_][A-Za-z0-9_]*\s+(\w+)(?:\[\d+\])?\b/;
+  return fixture
+    .split('\n')
+    .map((line) => re.exec(line)?.[1])
+    .filter((name): name is string => name !== undefined);
+};
+
+/** The create synopsis's option list: from the first `can be:</phrase>` to `</synopsis>`. */
+const createOptionsRegion = (): string => {
+  const start = createRole.indexOf('can be:</phrase>');
+  return createRole.slice(start, createRole.indexOf('</synopsis>', start));
+};
+
+/** The first ALTER variant's option list: from the first `can be:</phrase>` to `RENAME TO`. */
+const alterOptionsRegion = (): string => {
+  const start = alterRole.indexOf('can be:</phrase>');
+  return alterRole.slice(start, alterRole.indexOf('RENAME TO', start));
+};
+
+/** Every asserted prop except `name`, which is the mandatory `CREATE ROLE <name>` token, checked
+ * separately below. A boolean prop claims both its affirmative and its negative option. */
+const PROP_MAPPING: Readonly<
+  Record<string, { readonly option: string; readonly also?: string; readonly column: string }>
+> = {
+  login: { option: 'LOGIN', also: 'NOLOGIN', column: 'rolcanlogin' },
+  inherit: { option: 'INHERIT', also: 'NOINHERIT', column: 'rolinherit' },
+  connectionLimit: { option: 'CONNECTION LIMIT', column: 'rolconnlimit' },
+  validUntil: { option: 'VALID UNTIL', column: 'rolvaliduntil' },
+  // The value is never a prop (S25): the prop names the environment variable, and the value
+  // travels only in the dedicated `ALTER ROLE … WITH PASSWORD` statement.
+  password: { option: '[ ENCRYPTED ] PASSWORD', column: 'rolpassword' },
+};
+
+/** Every synopsis option this family does NOT declare as a prop, and why. */
+const EXCLUDED: Readonly<Record<string, string>> = {
+  SUPERUSER:
+    'left at the server default (NOSUPERUSER) on CREATE; an adopt or alter that finds rolsuper true is PostgresRolePrivilegedRefused — the flag is not inherited, SET ROLE exercises it',
+  NOSUPERUSER:
+    'the server default for CREATE ROLE; never declared, so the default is what a create lands on',
+  CREATEDB:
+    "left at the server default (NOCREATEDB); database creation is Postgres.Database's job, not a role prop",
+  NOCREATEDB: 'the server default for CREATE ROLE; never declared',
+  CREATEROLE:
+    'left at the server default (NOCREATEROLE) on CREATE; an adopt or alter that finds rolcreaterole true is refused — a CREATEROLE role can manage other roles',
+  NOCREATEROLE: 'the server default for CREATE ROLE; never declared',
+  REPLICATION:
+    'left at the server default (NOREPLICATION); replication is a cluster-operator concern, never a seat role',
+  NOREPLICATION: 'the server default for CREATE ROLE; never declared',
+  BYPASSRLS:
+    'left at the server default (NOBYPASSRLS) on CREATE; an adopt or alter that finds rolbypassrls true is refused',
+  NOBYPASSRLS: 'the server default for CREATE ROLE; never declared',
+  'PASSWORD NULL':
+    'clears the password; this family never clears one — a password is either declared by reference or left alone',
+  'IN ROLE':
+    'the create-time membership shorthand; this family writes memberships with one explicit GRANT per parent instead, so the re-read stays authoritative',
+  ROLE: 'grants the listed roles membership in the NEW role — the inverse of memberOf; membership is declared in one direction only',
+  ADMIN:
+    'grants membership with ADMIN OPTION; a live admin_option is revoked by grantor with RESTRICT, preserving membership and refusing dependent grants, and the seat GRANT says SET FALSE',
+  SYSID:
+    'ignored by the server since PostgreSQL 8.1 (the docs keep it only for compatibility); this family never assigns oids',
+};
+
+describe('postgres role provenance', () => {
+  test('fixture headers name the measured blob shas', () => {
+    expect(createRole).toContain(CREATE_ROLE_BLOB);
+    expect(createRole).toContain('doc/src/sgml/ref/create_role.sgml');
+    expect(alterRole).toContain(ALTER_ROLE_BLOB);
+    expect(alterRole).toContain('doc/src/sgml/ref/alter_role.sgml');
+    expect(authid).toContain(AUTHID_BLOB);
+    expect(authid).toContain('src/include/catalog/pg_authid.h');
+    expect(authMembers).toContain(AUTH_MEMBERS_BLOB);
+    expect(authMembers).toContain('src/include/catalog/pg_auth_members.h');
+  });
+
+  test('the name token is documented and backed by rolname', () => {
+    expect(createRole).toContain('CREATE ROLE <replaceable class="parameter">name</replaceable>');
+    expect(structColumns(authid)).toContain('rolname');
+  });
+
+  test('every declared prop maps to a real synopsis option (affirmative and negative)', () => {
+    const options = optionTokens(createOptionsRegion());
+    for (const [prop, { option, also }] of Object.entries(PROP_MAPPING)) {
+      expect(options, `prop "${prop}" claims synopsis option "${option}"`).toContain(option);
+      if (also !== undefined) {
+        expect(options, `prop "${prop}" claims negative option "${also}"`).toContain(also);
+      }
+    }
+  });
+
+  test('every declared prop maps to a real pg_authid column', () => {
+    const columns = structColumns(authid);
+    for (const [prop, { column }] of Object.entries(PROP_MAPPING)) {
+      expect(columns, `prop "${prop}" claims column "${column}"`).toContain(column);
+    }
+  });
+
+  test('memberOf is backed by the pg_auth_members catalog columns the membership read joins on', () => {
+    const columns = structColumns(authMembers);
+    expect(columns).toContain('roleid');
+    expect(columns).toContain('member');
+  });
+
+  test('every synopsis option is either a declared prop or a documented exclusion', () => {
+    const declared = new Set(
+      Object.values(PROP_MAPPING).flatMap((m) => [
+        m.option,
+        ...(m.also !== undefined ? [m.also] : []),
+      ]),
+    );
+    for (const option of optionTokens(createOptionsRegion())) {
+      const accounted = declared.has(option) || option in EXCLUDED;
+      expect(accounted, `synopsis option "${option}" is neither a prop nor in EXCLUDED`).toBe(true);
+    }
+  });
+
+  test('no excluded option is silently also a declared prop', () => {
+    const declared = new Set(
+      Object.values(PROP_MAPPING).flatMap((m) => [
+        m.option,
+        ...(m.also !== undefined ? [m.also] : []),
+      ]),
+    );
+    for (const option of Object.keys(EXCLUDED)) {
+      expect(declared.has(option), `"${option}" is both excluded and declared`).toBe(false);
+    }
+  });
+
+  test('every excluded option actually exists in the synopsis (no stale entries)', () => {
+    const options = new Set(optionTokens(createOptionsRegion()));
+    for (const option of Object.keys(EXCLUDED)) {
+      expect(
+        options.has(option),
+        `EXCLUDED names "${option}", which the synopsis no longer has`,
+      ).toBe(true);
+    }
+  });
+
+  test('ALTER ROLE backs every field this family alters', () => {
+    const alterOptions = optionTokens(alterOptionsRegion());
+    for (const option of Object.values(PROP_MAPPING).map((m) => m.option)) {
+      expect(alterOptions, `ALTER ROLE cannot set "${option}"`).toContain(option);
+    }
+  });
+
+  test('ALTER ROLE offers no membership or oid options, which is why memberships move via GRANT/REVOKE', () => {
+    const alterOptions = new Set(optionTokens(alterOptionsRegion()));
+    for (const option of ['IN ROLE', 'ROLE', 'ADMIN', 'SYSID']) {
+      expect(alterOptions.has(option), `ALTER ROLE unexpectedly offers "${option}"`).toBe(false);
+    }
+  });
+
+  test('the fixture carries the memberships sentence the one-parent GRANT/REVOKE design leans on', () => {
+    const stripped = alterRole.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ');
+    expect(stripped).toMatch(/no options[^;]*memberships/);
+    expect(stripped).toMatch(/use GRANT.{0,20}REVOKE/);
+  });
+
+  test('RENAME TO exists in the synopsis — the rename refusal is a choice, not an unknowing gap', () => {
+    expect(alterRole).toContain('RENAME TO');
+  });
+});

package/src/postgres/role-provider.ts

@@ -0,0 +1,105 @@
+/**
+ * `Postgres.Role`'s five lifecycle handlers, wired to `withPg` for anything that touches a
+ * client, and the one Layer a consuming stack provides. Split from `role.ts` so the file stays
+ * under the house cap: `role.ts` holds reconcile, `role-diff.ts` the plan diff; this file holds
+ * only the engine wiring.
+ */
+import * as Provider from 'alchemy/Provider';
+import { isResolved } from 'alchemy/Diff';
+import * as Effect from 'effect/Effect';
+import { ownedRead } from '../ownership/probe.ts';
+import { noteUnfinished } from '../ownership/resume.ts';
+import { refuseTakeover } from '../ownership/adopt.ts';
+import { PostgresRole } from './role.ts';
+import { readRole, reconcileWithClient, refuseAtPlan } from './role.ts';
+import { diffPostgresRole } from './role-diff.ts';
+import { PostgresRoleIdentityRefused } from './role-errors.ts';
+import { buildDropRoleSql, declarationMatches, storedAttributes } from './role-sql.ts';
+import { withPg } from './connection.ts';
+
+export const postgresRoleHandlers = PostgresRole.Provider.of({
+  // ⚠️ EMPTY, NOT A LIVE SWEEP: `pg_roles` lists every role on the cluster, most of which nothing
+  //   declared — the same reasoning `Postgres.Database`'s `list` documents.
+  list: () => Effect.succeed([]),
+  nuke: { skip: true },
+
+  read: ({ fqn, instanceId, olds, output }) =>
+    Effect.gen(function* () {
+      const name = output?.name ?? olds.name;
+      const live = yield* withPg((pg) => readRole(pg, name));
+      if (live === undefined) return undefined;
+      // A recycled name is not the role state recorded. Failing (rather than `Unowned`) matters
+      // because drift strips `Unowned` and would then reconcile the foreign role.
+      if (output !== undefined && live.oid !== output.oid) {
+        return yield* Effect.fail(
+          new PostgresRoleIdentityRefused({
+            role: name,
+            storedOid: output.oid,
+            liveOid: live.oid,
+          }),
+        );
+      }
+      const passwordSeal = output?.passwordSeal ?? '';
+      // Read and reconcile must expose the same shape to Alchemy's drift comparison.
+      const found = { ...storedAttributes(live), passwordSeal };
+      return yield* ownedRead(
+        { fqn, instanceId, output },
+        found,
+        Effect.succeed(declarationMatches(olds, live)),
+      );
+    }),
+
+  diff: ({ news, output, instanceId }) =>
+    Effect.gen(function* () {
+      // A `creating` row has no attributes. Mark it unfinished so `--adopt` can resume it
+      // (ownership/resume.ts); the engine treats `undefined` as "defer".
+      if (output === undefined) return yield* noteUnfinished(instanceId);
+      if (!isResolved(news)) return undefined;
+      const found = yield* withPg((pg) => readRole(pg, output.name));
+      return yield* diffPostgresRole(news, output, process.env, { found });
+    }),
+
+  reconcile: ({ fqn, instanceId, news, output }) =>
+    Effect.gen(function* () {
+      yield* refuseAtPlan(news);
+      return yield* withPg((pg) =>
+        Effect.gen(function* () {
+          // Alchemy skips the plan probe while a prop is still an Output, and a role can
+          // appear between plan and apply. A live role with no state is a takeover: refuse
+          // before any ALTER, PASSWORD or REVOKE, unless `--adopt` speaks for this apply.
+          const observed = yield* readRole(pg, news.name);
+          if (observed !== undefined && output === undefined) {
+            yield* refuseTakeover({ fqn, instanceId, output }, 'Postgres.Role');
+          }
+          return yield* reconcileWithClient(
+            pg,
+            news,
+            process.env,
+            output?.passwordSeal,
+            output?.oid,
+          );
+        }),
+      );
+    }),
+
+  delete: ({ output }) =>
+    withPg((pg) =>
+      Effect.gen(function* () {
+        if (output === undefined) return;
+        const live = yield* readRole(pg, output.name);
+        if (live === undefined) return;
+        if (live.oid !== output.oid) {
+          return yield* Effect.fail(
+            new PostgresRoleIdentityRefused({
+              role: output.name,
+              storedOid: output.oid,
+              liveOid: live.oid,
+            }),
+          );
+        }
+        yield* pg.unsafe(buildDropRoleSql(output.name)).pipe(Effect.asVoid);
+      }),
+    ),
+});
+
+export const PostgresRoleProvider = () => Provider.succeed(PostgresRole, postgresRoleHandlers);

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

@@ -0,0 +1,225 @@
+/**
+ * Every plan-time refusal and offline comparison, checked without a client: name-byte precision
+ * (the truncation trap `Postgres.Database` refuses), the rename refusal, a full sweep proving
+ * `diff` answers `update` and never `replace`, per-field and membership drift semantics,
+ * quoting, and the write-only password shape (S25). Zone-free and unparseable `validUntil`
+ * live in `role-valid-until.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import * as Effect from 'effect/Effect';
+import * as Redacted from 'effect/Redacted';
+import { POSTGRES_NAME_MAX_BYTES } from './database-attrs.ts';
+import { refuseAtPlan } from './role.ts';
+import { diffPostgresRole } from './role-diff.ts';
+import { resolvePassword } from './role-secrets.ts';
+import { seal } from '../secrets/write-only.ts';
+import { PostgresRoleNameRefused, PostgresRoleRenameRefused } from './role-errors.ts';
+import type { PostgresRoleAttributes, PostgresRoleProps } from './role-attrs.ts';
+import {
+  buildAlterRoleSql,
+  buildCreateRoleSql,
+  buildDropRoleSql,
+  buildSetPasswordSql,
+  scalarDrift,
+} from './role-sql.ts';
+import {
+  buildGrantMembershipSql,
+  buildRevokeGrantorMembershipSql,
+  membershipDrift,
+} from './role-membership-sql.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 base: PostgresRoleProps = {
+  name: 'seat-observability',
+  login: false,
+  connectionLimit: 10,
+  inherit: true,
+};
+
+const output: PostgresRoleAttributes = {
+  name: 'seat-observability',
+  oid: 20000,
+  login: false,
+  connectionLimit: 10,
+  inherit: true,
+  validUntil: null,
+  memberOf: [],
+  passwordSeal: '',
+};
+
+describe('name byte length', () => {
+  test('a 63-byte ASCII name passes the plan check', async () => {
+    await run(refuseAtPlan({ ...base, name: 'a'.repeat(63) }));
+  });
+
+  test('a 64-byte ASCII name is refused with the typed tag naming the measurement', async () => {
+    const error = await fails(refuseAtPlan({ ...base, name: 'a'.repeat(64) }));
+    expect(error).toBeInstanceOf(PostgresRoleNameRefused);
+    expect((error as PostgresRoleNameRefused).byteLength).toBe(64);
+    expect((error as PostgresRoleNameRefused).limit).toBe(POSTGRES_NAME_MAX_BYTES);
+  });
+
+  test('a 64-byte multibyte name is refused though .length is 32', async () => {
+    // U+00E9 ("é") is 2 UTF-8 bytes; 32 of them is 64 bytes — over the 63-byte limit.
+    const error = await fails(refuseAtPlan({ ...base, name: 'é'.repeat(32) }));
+    expect(error).toBeInstanceOf(PostgresRoleNameRefused);
+  });
+});
+
+describe('diff', () => {
+  test('a rename is refused at plan, before reconcile ever runs', async () => {
+    const error = await fails(diffPostgresRole({ ...base, name: 'seat-logs' }, output));
+    expect(error).toBeInstanceOf(PostgresRoleRenameRefused);
+  });
+
+  test('an unchanged declaration answers noop, and no output answers undefined (nothing to diff)', async () => {
+    expect(await run(diffPostgresRole(base, output))).toEqual({ action: 'noop' });
+    expect(await run(diffPostgresRole(base, undefined))).toBeUndefined();
+  });
+
+  test('a change in any single prop answers update, and NEVER replace \u2014 swept across every prop', async () => {
+    const variants: ReadonlyArray<
+      readonly [Partial<PostgresRoleProps>, Partial<PostgresRoleAttributes>]
+    > = [
+      [{ login: true }, {}],
+      [{ inherit: false }, {}],
+      [{ connectionLimit: 5 }, {}],
+      [{ validUntil: '2027-01-01T00:00:00Z' }, {}],
+      [{ memberOf: ['hf_agent'] }, {}],
+      [{ memberOf: [] }, { memberOf: ['hf_agent'] }],
+      [{ memberOf: ['hf_agent', 'seat-owners'] }, { memberOf: ['hf_agent'] }],
+    ];
+    for (const [variant, live] of variants) {
+      const result = await run(diffPostgresRole({ ...base, ...variant }, { ...output, ...live }));
+      expect(result?.action, `variant ${JSON.stringify(variant)}`).toBe('update');
+      expect(result).not.toEqual({ action: 'replace' });
+    }
+  });
+
+  test('a rotated password answers update even with no other drift; a matching or unreadable one does not', async () => {
+    const declared = { ...base, password: { fromEnv: 'PG_SEAT_ROLE_PASSWORD' } as const };
+    const stale = seal({ password: 'old' }, 'fixed-salt');
+    const matched = seal({ password: 'current' }, 'fixed-salt');
+    const held = { PG_SEAT_ROLE_PASSWORD: 'current' };
+    // A value the seal does not match — rotated, or an adopted role's empty seal — answers update.
+    expect(await run(diffPostgresRole(declared, { ...output, passwordSeal: stale }, held))).toEqual(
+      { action: 'update' },
+    );
+    expect(await run(diffPostgresRole(declared, output, held))).toEqual({ action: 'update' });
+    // Still matching: noop. The variable unset here: never stale — a plan that cannot read the
+    // secret never churns it.
+    expect(
+      await run(diffPostgresRole(declared, { ...output, passwordSeal: matched }, held)),
+    ).toEqual({ action: 'noop' });
+    expect(await run(diffPostgresRole(declared, { ...output, passwordSeal: stale }, {}))).toEqual({
+      action: 'noop',
+    });
+  });
+});
+
+describe('scalarDrift', () => {
+  test('lists one change per drifted field, in the family\u2019s compared order', () => {
+    expect(
+      scalarDrift(
+        {
+          ...base,
+          login: true,
+          inherit: false,
+          connectionLimit: 5,
+          validUntil: '2027-01-01T00:00:00Z',
+        },
+        { ...output, login: false, inherit: true, connectionLimit: 10 },
+      ),
+    ).toEqual([
+      { prop: 'login', value: true },
+      { prop: 'inherit', value: false },
+      { prop: 'connectionLimit', value: 5 },
+      { prop: 'validUntil', value: '2027-01-01T00:00:00Z' },
+    ]);
+  });
+
+  test('is empty when the live row matches, including the milliseconds case', () => {
+    expect(scalarDrift(base, output)).toEqual([]);
+    expect(
+      scalarDrift(
+        { ...base, validUntil: '2027-01-01T00:00:00Z' },
+        {
+          ...output,
+          validUntil: '2027-01-01T00:00:00.000Z',
+        },
+      ),
+    ).toEqual([]);
+  });
+});
+
+describe('membershipDrift', () => {
+  test('undefined asserts nothing; duplicates collapse; grants and revokes are sorted set differences', () => {
+    expect(membershipDrift(undefined, ['hf_agent'])).toEqual({ grants: [], revokes: [] });
+    expect(membershipDrift(['hf_agent', 'hf_agent', 'seat-b'], [])).toEqual({
+      grants: ['hf_agent', 'seat-b'],
+      revokes: [],
+    });
+    expect(membershipDrift(['hf_agent'], ['hf_agent', 'seat-b', 'seat-a'])).toEqual({
+      grants: [],
+      revokes: ['seat-a', 'seat-b'],
+    });
+  });
+});
+
+describe('quoting', () => {
+  test('a hostile role name is doubled in every statement that quotes it', () => {
+    expect(buildCreateRoleSql({ ...base, name: 'a"b' })).toBe(
+      'CREATE ROLE "a""b" WITH NOLOGIN INHERIT CONNECTION LIMIT 10',
+    );
+    expect(buildAlterRoleSql('a"b', { prop: 'connectionLimit', value: 3 })).toBe(
+      'ALTER ROLE "a""b" WITH CONNECTION LIMIT 3',
+    );
+    expect(buildGrantMembershipSql('m"1', 'p"2')).toBe('GRANT "p""2" TO "m""1" WITH SET FALSE');
+    expect(buildRevokeGrantorMembershipSql('m"1', 'p"2', 'g"3')).toBe(
+      'REVOKE "p""2" FROM "m""1" GRANTED BY "g""3"',
+    );
+    expect(buildDropRoleSql('a"b')).toBe('DROP ROLE IF EXISTS "a""b"');
+  });
+
+  test('the value buildSetPasswordSql carries is single-quote escaped exactly once', () => {
+    // In production that value is a SCRAM verifier (`role-scram.ts`), which the base64 alphabet
+    // keeps free of `'`; the quoting property still holds for any string handed to the builder.
+    expect(buildSetPasswordSql('seat-observability', "O'Brien; DROP")).toBe(
+      "ALTER ROLE \"seat-observability\" WITH PASSWORD E'O''Brien; DROP'",
+    );
+  });
+});
+
+describe('write-only password shape (S25)', () => {
+  const props = { ...base, password: { fromEnv: 'PG_SEAT_ROLE_PASSWORD' } };
+
+  test('resolvePassword holds the value as Redacted, which never prints or serialises it', () => {
+    const { variable, value } = resolvePassword(props, { PG_SEAT_ROLE_PASSWORD: 's3cret-value' });
+    expect(variable).toBe('PG_SEAT_ROLE_PASSWORD');
+    expect(String(value)).toBe('<redacted>');
+    expect(JSON.stringify({ value })).not.toContain('s3cret-value');
+    expect(Redacted.isRedacted(value)).toBe(true);
+    if (Redacted.isRedacted(value)) {
+      expect(Redacted.value(value)).toBe('s3cret-value');
+    }
+  });
+
+  test('resolvePassword answers no value when the variable is unset or empty', () => {
+    expect(resolvePassword(props, {}).value).toBeUndefined();
+    expect(resolvePassword(props, { PG_SEAT_ROLE_PASSWORD: '' }).value).toBeUndefined();
+    expect(resolvePassword(base, { PG_SEAT_ROLE_PASSWORD: 's3cret-value' })).toEqual({
+      variable: undefined,
+      value: undefined,
+    });
+  });
+});
+
+describe('removal policy', () => {
+  test('defaultRemovalPolicy is retain (checked in source, declared alongside PostgresRole)', () => {
+    const source = readFileSync(new URL('./role.ts', import.meta.url), 'utf8');
+    expect(source).toContain("defaultRemovalPolicy: 'retain'");
+  });
+});

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

@@ -0,0 +1,38 @@
+/**
+ * The SCRAM-SHA-256 verifier `role-scram.ts` builds — the only password form this family ever
+ * sends. The golden vector below was computed OUTSIDE node (`hashlib`/`hmac` from the Python 3
+ * standard library, 2026-09-30) so the test is a cross-implementation check, not the function
+ * re-deriving its own math.
+ */
+import { describe, expect, test } from 'bun:test';
+import { scramSha256Verifier } from './role-scram.ts';
+
+// A placeholder, never a credential; the salt is fixed so the vector is deterministic.
+const GOLDEN_SALT = Buffer.from('a1b2c3d4e5f60718293a4b5c6d7e8f90', 'hex');
+const PLACEHOLDER = 'placeholder-password';
+const GOLDEN =
+  'SCRAM-SHA-256$4096:obLD1OX2BxgpOktcbX6PkA==$' +
+  'wP+XMQxcTjqewigDeRTAJB703b2ekDF1fCBumhTm4N8=:' +
+  'Bcc+TZOxqllgMPNn8IX0u/TJpvlRhwqPJaNQ2VLm1F4=';
+
+describe('scramSha256Verifier', () => {
+  test('matches a verifier computed by an independent implementation', () => {
+    expect(scramSha256Verifier(PLACEHOLDER, GOLDEN_SALT)).toBe(GOLDEN);
+  });
+
+  test('fresh salt per call, standard base64 parts at PostgreSQL defaults', () => {
+    const shape =
+      /^SCRAM-SHA-256\$4096:[A-Za-z0-9+/]{22}==\$[A-Za-z0-9+/]{43}=:[A-Za-z0-9+/]{43}=$/;
+    const a = scramSha256Verifier(PLACEHOLDER);
+    const b = scramSha256Verifier(PLACEHOLDER);
+    expect(a).not.toBe(b);
+    expect(a).toMatch(shape);
+    expect(b).toMatch(shape);
+  });
+
+  test('a different password gives a different verifier for the same salt', () => {
+    expect(scramSha256Verifier(PLACEHOLDER, GOLDEN_SALT)).not.toBe(
+      scramSha256Verifier('placeholder-password-two', GOLDEN_SALT),
+    );
+  });
+});

package/src/postgres/role-scram.ts

@@ -0,0 +1,40 @@
+/**
+ * SCRAM-SHA-256 password verifier, built client-side the way `psql \password` and `createuser -w`
+ * do (`createuser.c@REL_18_6` → `pg_format scram verifier`). Postgres stores the verifier as-is in
+ * `pg_authid.rolpassword` and never recovers the password from it.
+ *
+ * ⛔ THE PLAIN PASSWORD NEVER ENTERS A STATEMENT. Before this file, `ALTER ROLE … PASSWORD` carried
+ *   the plain value as a literal, so it landed in the Effect SQL span attribute `db.query.text`,
+ *   in `pg_stat_statements` (`track_utility=on` records utility statements), and in the server log
+ *   of any failed `ALTER`. The verifier is the one form Postgres accepts that is not the secret:
+ *   `PASSWORD 'SCRAM-SHA-256$4096:<salt>$<StoredKey>:<ServerKey>'` (`create_role.sgml`: a string
+ *   already in SCRAM verifier format is stored as given).
+ * ★ WIRE FORMAT AND MATH (`scram_protocols` / RFC 5802 / `auth-scram.c`): salt 16 bytes,
+ *   iterations 4096 (both Postgres defaults), standard base64. SaltedPassword = PBKDF2-HMAC-SHA-256
+ *   (password, salt, 4096, 32 bytes); ClientKey = HMAC(SaltedPassword, "Client Key"); StoredKey =
+ *   SHA-256(ClientKey); ServerKey = HMAC(SaltedPassword, "Server Key").
+ */
+import { createHash, createHmac, pbkdf2Sync, randomBytes } from 'node:crypto';
+
+const ITERATIONS = 4096;
+const SALT_BYTES = 16;
+const KEY_BYTES = 32;
+
+const hmac = (key: Buffer, label: string): Buffer =>
+  createHmac('sha256', key).update(label, 'utf8').digest();
+
+const b64 = (value: Buffer): string => value.toString('base64');
+
+/**
+ * `SCRAM-SHA-256$4096:<salt>$<StoredKey>:<ServerKey>` for one password. The salt is fresh per
+ * call (same as `psql \password`); tests pass one to make the output deterministic.
+ * Callers first run `assertPasswordAscii`: raw non-ASCII may differ from PostgreSQL's
+ * SASLprep bytes (https://www.postgresql.org/docs/16/sasl-authentication.html).
+ */
+export const scramSha256Verifier = (password: string, salt?: Buffer): string => {
+  const bytes = salt ?? randomBytes(SALT_BYTES);
+  const saltedPassword = pbkdf2Sync(password, bytes, ITERATIONS, KEY_BYTES, 'sha256');
+  const storedKey = createHash('sha256').update(hmac(saltedPassword, 'Client Key')).digest();
+  const serverKey = hmac(saltedPassword, 'Server Key');
+  return `SCRAM-SHA-256$${ITERATIONS}:${b64(bytes)}$${b64(storedKey)}:${b64(serverKey)}`;
+};

package/src/postgres/role-secrets.ts

@@ -0,0 +1,61 @@
+/**
+ * The `Postgres.Role` password: resolution from the environment and the seal arithmetic that
+ * lets state answer "did this value already go out?" without storing it (S25).
+ *
+ * ⛔ THE PASSWORD IS A REFERENCE, NEVER A VALUE. It is declared as
+ *   `{ fromEnv: 'PG_SEAT_WIDGET_PASSWORD' }`; the NAME lands in state, the value is resolved
+ *   from the deploying process's environment at reconcile/diff time, held as `Redacted`, and
+ *   quoted into the one `ALTER ROLE … PASSWORD` statement that needs it.
+ * ★ What state remembers is a `scrypt:<salt>:<digest>` seal ({@link sealPassword}), so a
+ *   reconcile sends the password only when the environment value differs from the one last
+ *   written — a plan never re-sends a secret that already matches, and never stores one.
+ */
+import * as Redacted from 'effect/Redacted';
+import * as Effect from 'effect/Effect';
+import { PostgresRolePasswordNonAsciiRefused } from './role-errors.ts';
+import { type Environment, resolveAll, seal, sealMatches } from '../secrets/write-only.ts';
+import type { PostgresRoleProps } from './role-attrs.ts';
+
+/** What the environment holds for the declared password. `value` is `undefined` when no
+ * password is declared, or when the variable is unset or empty (a renderer that failed writes
+ * `NAME=`; `resolveAll` treats empty as missing). ⛔ Reads the environment at CALL time. */
+export interface ResolvedPassword {
+  readonly variable: string | undefined;
+  readonly value: Redacted.Redacted<string> | undefined;
+}
+
+/** ⛔ PostgreSQL applies SASLprep before SCRAM, with a raw-byte fallback for prohibited input:
+ * https://www.postgresql.org/docs/16/sasl-authentication.html#SASL-SCRAM-SHA-256
+ * Non-ASCII can normalize to different bytes (e.g. soft hyphen disappears). Refuse before
+ * any write, even with a matching old seal, until we have a vendor-compatible normalizer.
+ * ASCII is unchanged, including prohibited ASCII controls via PostgreSQL's fallback. */
+export const assertPasswordAscii = (
+  role: string,
+  resolved: ResolvedPassword,
+): Effect.Effect<void, PostgresRolePasswordNonAsciiRefused> =>
+  resolved.value !== undefined && /[\u0080-\uffff]/.test(Redacted.value(resolved.value))
+    ? Effect.fail(new PostgresRolePasswordNonAsciiRefused({ role }))
+    : Effect.void;
+
+export const resolvePassword = (
+  props: PostgresRoleProps,
+  env: Environment = process.env,
+): ResolvedPassword => {
+  if (props.password === undefined) return { variable: undefined, value: undefined };
+  const { values } = resolveAll({ password: props.password }, env);
+  const raw = values['password'];
+  return {
+    variable: props.password.fromEnv,
+    value: raw === undefined ? undefined : Redacted.make(raw),
+  };
+};
+
+/** `seal({ password })` of the resolved value — the one thing state remembers about it. */
+export const sealPassword = (value: Redacted.Redacted<string>): string =>
+  seal({ password: Redacted.value(value) });
+
+/** Whether the seal was made from the resolved value. Malformed/empty seals answer false, so an
+ * adopted role (seal `''`) or one written outside this stack gets the password written on the
+ * first reconcile that holds the variable — the declaration is authoritative. */
+export const passwordMatchesSeal = (value: Redacted.Redacted<string>, sealed: string): boolean =>
+  sealMatches(sealed, { password: Redacted.value(value) });