@homeflare/alchemy 0.43.0 → 0.45.0

package/src/postgres/role-attrs.ts

@@ -0,0 +1,137 @@
+/**
+ * `Postgres.Role` props and attributes, and the plan-time checks that run before any statement.
+ *
+ * ⛔ EVERY ASSERTED PROP TRACES TO A REAL `CREATE ROLE` / `ALTER ROLE` OPTION AND A REAL CATALOG
+ *   COLUMN. `role-provenance.test.ts` parses the committed fixtures (`create_role.sgml`,
+ *   `alter_role.sgml`, `pg_authid.h`, `pg_auth_members.h`) and fails if that mapping breaks.
+ * ⛔ NO PASSWORD VALUE AS A PROP (S25). `password` is declared as
+ *   `{ fromEnv: 'PG_SEAT_WIDGET_PASSWORD' }`, never a string. The name lives in state; the value
+ *   is resolved from the deploying process's environment at reconcile time, wrapped in
+ *   `Redacted`, and quoted into the one statement that needs it.
+ * ★ UNLIKE `Postgres.Database`, THIS FAMILY IS ALTER-CAPABLE: `LOGIN`/`NOLOGIN`,
+ *   `INHERIT`/`NOINHERIT`, `CONNECTION LIMIT` and `VALID UNTIL` all have a safe atomic
+ *   `ALTER ROLE` form (`alter_role.sgml`'s first synopsis variant), so a drifted live row is
+ *   brought back to the declaration instead of refused.
+ */
+import type { FromEnv } from '../secrets/write-only.ts';
+
+/** Re-exported for tests that operate on identifier byte length. */
+export { POSTGRES_NAME_MAX_BYTES, nameByteRefusal, utf8ByteLength } from './database-attrs.ts';
+
+/**
+ * A declared `validUntil` must carry its own UTC designator (`Z`) or numeric offset (`+02:00`).
+ *
+ * ⛔ WHY A ZONE-FREE TIMESTAMP IS REFUSED AT PLAN. PostgreSQL reads `VALID UNTIL '2027-01-01'`
+ *   as midnight in the SESSION's time zone; the deploying process parses the same string as UTC
+ *   (ECMAScript's rule for date-only forms). The instants differ, so the value read back would
+ *   never equal the declaration, and every plan would issue the same `ALTER ROLE … VALID UNTIL`
+ *   forever — the exact silent loop this family refuses elsewhere. A string ECMAScript cannot
+ *   parse at all reaches the same refusal; PostgreSQL would reject it too, only later and as an
+ *   unclassified statement error.
+ */
+const VALID_UNTIL_OFFSET = /(?:Z|[+-]\d{2}:\d{2})$/;
+
+export const validUntilRefusal = (
+  value: string,
+): { readonly reason: 'unparseable' | 'zone-free' } | undefined => {
+  // A zone suffix is not a timestamp. `2027-13-01T00:00:00Z` and `not-a-dateZ` match the
+  // offset and `Date.parse` to NaN; accepting them sends a VALID UNTIL PostgreSQL rejects, or
+  // one that never compares equal on read-back, so every later reconcile re-issues the ALTER.
+  if (Number.isNaN(Date.parse(value))) return { reason: 'unparseable' };
+  if (VALID_UNTIL_OFFSET.test(value)) return undefined;
+  return { reason: 'zone-free' };
+};
+
+/** Whether a declared `validUntil` and the live serialised value name the same instant. Both
+ * sides are plan-checked parseable, so `NaN` cannot reach here. */
+export const sameValidUntil = (declared: string, live: string | null): boolean =>
+  live !== null && Date.parse(declared) === Date.parse(live);
+
+/**
+ * Declared properties of one role.
+ *
+ * `login` and `inherit` are required: the resource configures a LOGIN or NOLOGIN role with
+ * INHERIT explicit, per the seat-wiring spec's group-role-per-seat shape (`NOLOGIN`, member of
+ * `hf_agent`, owning its own schema). An undeclared boolean would silently adopt whatever the
+ * live row already says — the opposite of idempotent.
+ */
+export interface PostgresRoleProps {
+  /** At most 63 UTF-8 bytes — refused at plan/reconcile if larger (`PostgresRoleNameRefused`). */
+  readonly name: string;
+  /** `LOGIN` or `NOLOGIN` — maps to `pg_roles.rolcanlogin`. */
+  readonly login: boolean;
+  /** `CONNECTION LIMIT n`, `-1` for unlimited — maps to `pg_roles.rolconnlimit`. */
+  readonly connectionLimit: number;
+  /** `INHERIT` or `NOINHERIT` — maps to `pg_roles.rolinherit`; false also clears per-grant
+   * INHERIT on declared memberships (PG 16+ uses the role flag only to default new grants). */
+  readonly inherit: boolean;
+  /**
+   * `VALID UNTIL 'timestamp'` — maps to `pg_roles.rolvaliduntil`. ISO 8601 without a timezone is
+   * accepted by PostgreSQL's `timestamptz` input (it is interpreted in the client's time zone);
+   * an ISO 8601 string carrying `Z` is unambiguous, so the docs recommend declaring it. Omitted
+   * means "leave the live value alone" — the resource never clears an expiry it did not declare.
+   */
+  readonly validUntil?: string;
+  /**
+   * The roles this role is a member of (`GRANT parent TO this`). Backed by `pg_auth_members`.
+   * Compared when declared; omitted leaves live memberships untouched. Empty array means
+   * "ensure none".
+   */
+  readonly memberOf?: readonly string[];
+  /**
+   * `PASSWORD '...'` by the NAME of the environment variable holding it. Omitted means "leave
+   * the live password alone" (and `NOLOGIN` group roles need none). Required once, before the
+   * first create that declares it, and on every later write while the variable is set — a value
+   * the environment stopped providing is never guessed.
+   */
+  readonly password?: FromEnv;
+}
+
+/** Live attributes, read back after every reconcile. `passwordValue` is NEVER stored (S25). */
+export interface PostgresRoleAttributes {
+  readonly name: string;
+  readonly oid: number;
+  readonly login: boolean;
+  readonly connectionLimit: number;
+  readonly inherit: boolean;
+  /** ISO 8601 (`...Z`), server-side serialised; `null` when the live row has no expiry. */
+  readonly validUntil: string | null;
+  /**
+   * Catalog flags this family never declares. A create lands on the server default (all false).
+   * An adopt or alter that finds any of them true is refused — they are not inherited, so a
+   * member who `SET ROLE`s to this role would exercise them. Absent on a seeded test row means
+   * false, the default a `CREATE ROLE` without the option lands on.
+   */
+  readonly superuser?: boolean;
+  readonly createrole?: boolean;
+  readonly createdb?: boolean;
+  readonly replication?: boolean;
+  readonly bypassrls?: boolean;
+  /**
+   * Parent role names, sorted. Empty array when the role is a member of nothing. Null means
+   * "memberships were not declared on this resource", so the field is not asserted.
+   */
+  readonly memberOf: readonly string[] | null;
+  /**
+   * The membership rows behind `memberOf`, including `admin_option`, `set_option` and
+   * `inherit_option`. Present
+   * on a catalog read; stripped before attributes are stored (`storedAttributes`), because the
+   * engine's diff receives stored attributes and would never see them there. The provider's
+   * diff reads these rows live. `grantor` is the role that made the grant
+   * (`pg_auth_members.grantor`). Null is a defensive inconsistent-catalog case, not an ordinary
+   * DROP ROLE outcome; such a row cannot be named in `REVOKE … GRANTED BY`.
+   */
+  readonly memberships?: readonly {
+    readonly parent: string;
+    readonly grantor: string | null;
+    readonly admin: boolean;
+    readonly set: boolean;
+    readonly inherit: boolean;
+  }[];
+  /**
+   * A seal of the last password value written, or `''` if none was ever written (`seal()` from
+   * `secrets/write-only.ts`). Lets a later reconcile notice a rotated environment variable
+   * without the state store holding anything a reader could replay.
+   */
+  readonly passwordSeal: string;
+}

package/src/postgres/role-diff.ts

@@ -0,0 +1,93 @@
+/**
+ * Plan diff for `Postgres.Role`.
+ *
+ * ⛔ THE ENGINE PASSES STORED ATTRIBUTES, NOT A CATALOG READ. `Plan.ts` (alchemy beta.79,
+ *   the `provider.diff` call that sets `output: oldState.attr`) hands `diff` whatever reconcile
+ *   last stored. `storedAttributes` strips `memberships`, so a name-matched `memberOf` looks
+ *   idle even when the live row is `WITH ADMIN` or still at the `SET TRUE` default. The provider
+ *   reads the role and passes it as `observation`. Offline tests omit `observation` and compare
+ *   the stored parent names only.
+ */
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Effect from 'effect/Effect';
+import type { Environment } from '../secrets/write-only.ts';
+import type { PostgresRoleAttributes, PostgresRoleProps } from './role-attrs.ts';
+import {
+  PostgresRoleIdentityRefused,
+  type PostgresRoleNameRefused,
+  type PostgresRolePasswordNonAsciiRefused,
+  PostgresRoleRenameRefused,
+  type PostgresRoleValidUntilRefused,
+} from './role-errors.ts';
+import { membershipDrift, unsafeMemberships } from './role-membership-sql.ts';
+import { assertPasswordAscii, passwordMatchesSeal, resolvePassword } from './role-secrets.ts';
+import { privilegedFlags, scalarDrift } from './role-sql.ts';
+import { refuseAtPlan } from './role.ts';
+
+/** A catalog read the provider performed for this diff. `found: undefined` means the name is
+ * absent. Omitting the argument means no catalog read (the offline comparison). */
+export interface RoleObservation {
+  readonly found: Omit<PostgresRoleAttributes, 'passwordSeal'> | undefined;
+}
+
+/**
+ * `news` against stored `output`, plus a live row when the provider has one. A rename is a
+ * plan-time refusal; so are an over-long name and an unusable `validUntil`. An oid that is not
+ * the stored one is refused — the name was recreated out of band. Every other change answers
+ * `update`. `delete` is a real drop here, so `diff` never answers `replace`.
+ */
+export const diffPostgresRole = (
+  news: Input<PostgresRoleProps>,
+  output: PostgresRoleAttributes | undefined,
+  env: Environment = process.env,
+  observation?: RoleObservation,
+): Effect.Effect<
+  { readonly action: 'update' } | { readonly action: 'noop' } | undefined,
+  | PostgresRoleRenameRefused
+  | PostgresRoleNameRefused
+  | PostgresRoleValidUntilRefused
+  | PostgresRoleIdentityRefused
+  | PostgresRolePasswordNonAsciiRefused
+> =>
+  Effect.gen(function* () {
+    if (output === undefined || !isResolved(news)) return undefined;
+    if (news.name !== output.name) {
+      return yield* Effect.fail(
+        new PostgresRoleRenameRefused({ from: output.name, to: news.name }),
+      );
+    }
+    yield* refuseAtPlan(news);
+    const live = observation?.found;
+    if (live !== undefined && live.oid !== output.oid) {
+      return yield* Effect.fail(
+        new PostgresRoleIdentityRefused({
+          role: output.name,
+          storedOid: output.oid,
+          liveOid: live.oid,
+        }),
+      );
+    }
+    const compared = live ?? output;
+    const scalars = scalarDrift(news, compared);
+    // Option rows live only on the catalog read. Stored `memberships` is stripped before it
+    // reaches the engine, so it is not consulted here.
+    const membership = membershipDrift(
+      news.memberOf,
+      compared.memberOf ?? [],
+      live === undefined ? new Set() : unsafeMemberships(live, news.inherit),
+    );
+    const resolved = resolvePassword(news, env);
+    yield* assertPasswordAscii(news.name, resolved);
+    const passwordStale =
+      resolved.value !== undefined && !passwordMatchesSeal(resolved.value, output.passwordSeal);
+    const absent = observation !== undefined && live === undefined;
+    const changed =
+      absent ||
+      privilegedFlags(compared).length > 0 ||
+      scalars.length > 0 ||
+      membership.grants.length > 0 ||
+      membership.revokes.length > 0 ||
+      passwordStale;
+    return changed ? ({ action: 'update' } as const) : ({ action: 'noop' } as const);
+  });

package/src/postgres/role-errors.ts

@@ -0,0 +1,206 @@
+/**
+ * `Postgres.Role` failures as typed tags (S21).
+ *
+ * ⛔ NEVER MATCH DRIVER MESSAGE TEXT. Most errors are raised from a fact the
+ *   provider already checked (a byte count, a live catalog row, a missing environment variable,
+ *   a vanished create). Membership repair also maps raw SQLSTATE 2BP01/42501 to a typed
+ *   refusal naming the observed parent and grantor. A `DROP ROLE` that the
+ *   server refuses (the role still owns objects, `2BP01 dependent_objects_still_exist`) surfaces
+ *   as the `SqlError` the client raised, unclassified by this family.
+ */
+import * as Data from 'effect/Data';
+
+/**
+ * A role name would be silently truncated by the server (`NAMEDATALEN` 64, so 63 UTF-8 bytes is
+ * the last one that survives whole) — refused at plan, before any statement runs.
+ *
+ * ⚠️ Same hazard as `PostgresDatabaseNameRefused`: `truncate_identifier` clips at 63 bytes and
+ * emits only a NOTICE. A create would succeed against the truncated name; the next plan would
+ * look for the original name and find nothing, looping forever.
+ */
+export class PostgresRoleNameRefused extends Data.TaggedError('PostgresRoleNameRefused')<{
+  readonly name: string;
+  readonly byteLength: number;
+  readonly limit: number;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Role "${this.name}": ${String(this.byteLength)} UTF-8 bytes, over the ` +
+      `${String(this.limit)}-byte limit (NAMEDATALEN 64, minus the terminator). PostgreSQL would ` +
+      'accept the CREATE and silently truncate the name with only a NOTICE, so this plan refuses ' +
+      'it instead of creating a role no later read will ever find again.'
+    );
+  }
+}
+
+/** A logical id's `name` changed. A role's name is its identity; this resource never replaces via
+ * `DROP` then `CREATE` — role memberships, grants and owned objects would be lost, and the
+ * seat-wiring shape depends on the group-role name staying stable. `ALTER ROLE … RENAME TO`
+ * exists in PostgreSQL; this family does not drive it, so a rename is refused at plan and the
+ * new name is declared as its own logical id. */
+export class PostgresRoleRenameRefused extends Data.TaggedError('PostgresRoleRenameRefused')<{
+  readonly from: string;
+  readonly to: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Role: the declared name changed from "${this.from}" to "${this.to}". A ` +
+      'rename is refused at plan — this provider never replaces a role (that is DROP then ' +
+      'CREATE, which loses memberships, grants and ownerships). Declare a new logical id for ' +
+      'the new name, and remove the old one once its objects have moved.'
+    );
+  }
+}
+
+/** The password prop names an environment variable that is unset or empty at reconcile time, on a
+ * write that must send one (a create that declares it, or any reconcile while the variable is
+ * set). Never a guess: a group role left with a stale or empty password is exactly the
+ * unauthenticated path the refusal exists to prevent. */
+export class PostgresRolePasswordEnvUnsetError extends Data.TaggedError(
+  'PostgresRolePasswordEnvUnsetError',
+)<{
+  readonly role: string;
+  readonly variable: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Role "${this.role}": password.fromEnv "${this.variable}" is unset or empty ` +
+      'in the deploying process, but this write requires a password this stack has not sealed.'
+    );
+  }
+}
+
+/** A live role carries a catalog flag this family never declares (`rolsuper`, `rolcreaterole`,
+ * `rolcreatedb`, `rolreplication`, `rolbypassrls`). Those are not inherited: a member who
+ * `SET ROLE`s to the parent exercises them. Refused before any write, adopt included. */
+export class PostgresRolePrivilegedRefused extends Data.TaggedError(
+  'PostgresRolePrivilegedRefused',
+)<{
+  readonly role: string;
+  readonly flags: readonly string[];
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Role "${this.role}": the live role has ${this.flags.join(', ')} set. This ` +
+      'family never declares those attributes (a create lands on the server default, all off), ' +
+      'and they are not inherited — a member who SET ROLEs to this role would exercise them. ' +
+      'Clear the flag on the cluster before this stack adopts the role.'
+    );
+  }
+}
+
+/** The declared `validUntil` is not a timestamp this family can compare: ECMAScript cannot parse
+ * it at all, or it names no time zone. Refused at plan, before any statement — see
+ * `role-attrs.ts#validUntilRefusal` for the churn loop this prevents. */
+export class PostgresRoleValidUntilRefused extends Data.TaggedError(
+  'PostgresRoleValidUntilRefused',
+)<{
+  readonly role: string;
+  readonly value: string;
+  readonly reason: 'unparseable' | 'zone-free';
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Role "${this.role}": validUntil "${this.value}" is ${this.reason === 'unparseable' ? 'not a timestamp this kit can parse' : 'missing its UTC designator or numeric offset'}. ` +
+      'Declare an explicit-zone ISO 8601 value such as "2027-01-01T00:00:00Z" — PostgreSQL would ' +
+      'read a zone-free value in the session time zone while the plan compares UTC, and the two ' +
+      'would never agree.'
+    );
+  }
+}
+
+/** `CREATE ROLE` raised no error, but the immediate re-read still finds nothing (S10/S20).
+ * Measured to have no real trigger in a correctly speaking client; still a typed failure the
+ * caller can see and retry, never a defect that crashes the engine. */
+export class PostgresRoleCreateVanished extends Data.TaggedError('PostgresRoleCreateVanished')<{
+  readonly role: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Role "${this.role}": CREATE ROLE raised no error, but the role is still ` +
+      'absent on the immediate re-read. Re-plan — this is not a state this provider expects to reach.'
+    );
+  }
+}
+
+/** An option repair was refused, or a catalog row survived outside the declaration. A null grantor is a
+ * defensive corruption/test case: PostgreSQL tracks grantor dependencies, so ordinary
+ * DROP ROLE does not leave a dangling grantor. Refuse instead of claiming convergence. */
+export class PostgresRoleMembershipUnrepaired extends Data.TaggedError(
+  'PostgresRoleMembershipUnrepaired',
+)<{
+  readonly role: string;
+  readonly parent: string;
+  readonly grantor: string | null;
+  readonly declared: boolean;
+}> {
+  override get message(): string {
+    const who =
+      this.grantor === null
+        ? 'an unresolvable grantor (inconsistent catalog)'
+        : `grantor "${this.grantor}"`;
+    return (
+      `Postgres.Role "${this.role}": membership of "${this.parent}" ` +
+      `(${this.declared ? 'declared, options unsafe' : 'not declared'}) could not be repaired ` +
+      `under ${who}. The server refused the repair or the catalog re-read still found the row ` +
+      'outside the declaration. pg_auth_members keys a membership on (parent, member, grantor). ' +
+      'Check dependent grants, executor permissions and grantor identity before re-planning.'
+    );
+  }
+}
+
+/** A declared `memberOf` parent is not in `pg_roles`. Checked before any statement of a create,
+ * so a missing parent never leaves a committed LOGIN role behind a `42704` (`undefined_object`,
+ * `user.c@REL_18_6`) from `GRANT`. */
+export class PostgresRoleParentMissing extends Data.TaggedError('PostgresRoleParentMissing')<{
+  readonly role: string;
+  readonly parent: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Role "${this.role}": memberOf parent "${this.parent}" does not exist. ` +
+      'Nothing was written — declare that role first (or drop it from memberOf). A GRANT of a ' +
+      'missing role fails only after CREATE ROLE has committed, and the next plan then needs ' +
+      '--adopt to finish the orphan.'
+    );
+  }
+}
+
+/** The live role's oid is not the one this stack stored. A drop and recreate out of band reuses
+ * the name and would otherwise plan as ours: noop while the seal still matches, and a destroy
+ * would `DROP` a role this stack never created. */
+export class PostgresRoleIdentityRefused extends Data.TaggedError('PostgresRoleIdentityRefused')<{
+  readonly role: string;
+  readonly storedOid: number;
+  readonly liveOid: number;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Role "${this.role}": the live oid is ${String(this.liveOid)}, but state recorded ` +
+      `${String(this.storedOid)}. The name was dropped and recreated outside this stack. Nothing ` +
+      'was altered and the live role was not dropped — remove the stale state, or adopt the new ' +
+      'role under a new logical id once you mean to own it.'
+    );
+  }
+}
+
+/** Never carry the rejected password in this error: errors reach logs and traces. */
+export class PostgresRolePasswordNonAsciiRefused extends Data.TaggedError(
+  'PostgresRolePasswordNonAsciiRefused',
+)<{ readonly role: string }> {
+  override get message(): string {
+    return `Postgres.Role "${this.role}": password must be ASCII; this provider does not implement PostgreSQL SASLprep normalization. Nothing was written.`;
+  }
+}
+
+export type PostgresRoleError =
+  | PostgresRolePasswordNonAsciiRefused
+  | PostgresRoleNameRefused
+  | PostgresRoleRenameRefused
+  | PostgresRoleValidUntilRefused
+  | PostgresRolePasswordEnvUnsetError
+  | PostgresRolePrivilegedRefused
+  | PostgresRoleCreateVanished
+  | PostgresRoleMembershipUnrepaired
+  | PostgresRoleParentMissing
+  | PostgresRoleIdentityRefused;

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

@@ -0,0 +1,60 @@
+/**
+ * The create must not survive a missing parent, and a synthetic inconsistent-catalog membership with no grantor
+ * must fail typed rather than look repaired.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { makeFakeSql } from './fake-sql.ts';
+import { PostgresRoleMembershipUnrepaired, PostgresRoleParentMissing } from './role-errors.ts';
+import type { PostgresRoleAttributes, PostgresRoleProps } from './role-attrs.ts';
+import { reconcileWithClient } from './role.ts';
+
+const fails = <A, E>(eff: Effect.Effect<A, E>): Promise<E> => Effect.runPromise(Effect.flip(eff));
+
+const props: PostgresRoleProps = {
+  name: 'seat-observability',
+  login: true,
+  connectionLimit: 10,
+  inherit: true,
+  memberOf: ['hf_agent'],
+};
+
+const live = (): PostgresRoleAttributes => ({
+  name: 'seat-observability',
+  oid: 20000,
+  login: true,
+  connectionLimit: 10,
+  inherit: true,
+  validUntil: null,
+  memberOf: ['hf_agent'],
+  passwordSeal: '',
+});
+
+describe('missing parent and inconsistent grantor', () => {
+  test('a missing parent fails typed and issues no CREATE', async () => {
+    const fake = makeFakeSql();
+    const error = await fails(reconcileWithClient(fake, props));
+    expect(error).toBeInstanceOf(PostgresRoleParentMissing);
+    expect((error as PostgresRoleParentMissing).parent).toBe('hf_agent');
+    expect(fake.statements.some((s) => s.text.startsWith('CREATE'))).toBe(false);
+    expect(fake.roleRows.has('seat-observability')).toBe(false);
+  });
+
+  test('a GRANT failure inside the create transaction rolls the CREATE back', async () => {
+    const fake = makeFakeSql({ roles: ['hf_agent'], failNext: 'GRANT' });
+    const error = await fails(reconcileWithClient(fake, props));
+    expect(error).not.toBeInstanceOf(PostgresRoleParentMissing);
+    expect(fake.roleRows.has('seat-observability')).toBe(false);
+    expect(fake.statements.some((s) => s.text.startsWith('CREATE ROLE'))).toBe(true);
+  });
+
+  test('a synthetic unresolvable grantor fails typed (not an ordinary DROP ROLE outcome)', async () => {
+    const fake = makeFakeSql({ roleRows: [live()], roles: ['hf_agent'] });
+    fake.memberships.add('seat-observability\0hf_agent\0');
+    fake.membershipOptions.set('seat-observability\0hf_agent\0', { admin: true, set: true });
+    const error = await fails(reconcileWithClient(fake, props));
+    expect(error).toBeInstanceOf(PostgresRoleMembershipUnrepaired);
+    expect((error as PostgresRoleMembershipUnrepaired).grantor).toBeNull();
+    expect(fake.memberships.has('seat-observability\0hf_agent\0')).toBe(true);
+  });
+});