@homeflare/alchemy 0.1.0

package/src/openbao/cloudflare-policy.ts

@@ -0,0 +1,180 @@
+/**
+ * A Cloudflare policy document as the engine stores it — resolution from names, parsing from a
+ * read, and the one comparison every Bao.CloudflareRole plan rests on.
+ *
+ * MEASURED from the engine source (house/platform/secrets/vault/plugin/cloudflare/path_roles.go)
+ * and the 2026-09-14 snapshot of all 586 live roles:
+ *   • `policies` is a STRING field holding a JSON array (path_roles.go:67-72). Each entry is
+ *     `{effect, resources: map[string]string, permission_groups: [{id}]}` (:25-33).
+ *   • A read hands back `json.Marshal` of the stored slice (:199-207): no whitespace, entry and
+ *     group order preserved (Go slices), resource keys sorted (Go maps). Every snapshot role has
+ *     exactly that shape.
+ */
+import { GROUP_SCOPES, groupKey, scopeOfResource } from './cloudflare-group-scope.ts';
+import type { DeclaredPolicy } from './cloudflare-roles-expand.ts';
+
+export interface WirePolicy {
+  readonly effect: string;
+  readonly resources: Readonly<Record<string, string>>;
+  readonly groupIds: readonly string[];
+}
+
+/** A declared entry with its IDs, still carrying how its group order is to be compared. */
+export interface ResolvedPolicy extends WirePolicy {
+  readonly groupOrder: DeclaredPolicy['groupOrder'];
+}
+
+/**
+ * One name at every scope — what a source that cannot see scopes can honestly offer.
+ *
+ * ⚠️ IT IS A WIDENING, AND IT IS THE ASYMMETRY BETWEEN THE TWO SOURCES. The live-roles bootstrap
+ *   and cloudflare-permission-groups-solve.ts recover `name → id` from roles that carry ids and no
+ *   scopes, so they cannot tell the seven two-id names apart; the id they learned is offered for
+ *   whatever scope an entry asks. The engine source keys by (name, scope) and never does this.
+ */
+export const atEveryScope = (byName: ReadonlyMap<string, string>): ReadonlyMap<string, string> =>
+  new Map(
+    [...byName].flatMap(([name, id]) =>
+      Object.values(GROUP_SCOPES).map((scope) => [groupKey(name, scope), id] as const),
+    ),
+  );
+
+/**
+ * Declared names to IDs, or the names `ids` lacks.
+ *
+ * ⛔ AN ENTRY LOOKS ITS GROUPS UP AT ITS OWN SCOPE (`groupKey`), not by name: a zone entry and an
+ *   account entry of the same role can name one group and mean two different ids.
+ * ★ THE ACCOUNT ENTRY IS SORTED BY ID, EXACTLY AS cfhf.py:180 DID. ⚠️ Plain `sort()`, never
+ *   `localeCompare`: Python's `sorted()` on str is codepoint order, and JavaScript's default sort
+ *   is UTF-16 code-unit order, which agree on the lowercase hex these IDs are made of.
+ */
+export const resolvePolicies = (
+  declared: readonly DeclaredPolicy[],
+  ids: ReadonlyMap<string, string>,
+): { readonly policies: ResolvedPolicy[]; readonly missing: string[] } => {
+  const missing = new Set<string>();
+  const policies = declared.map((policy) => {
+    /**
+     * ⛔ THE ENTRY'S OWN WORD BEATS ITS RESOURCE. `scope` is roles.yaml `groups_scope:` reaching
+     *   here unchanged; `scopeOfResource` is the default for the 639 of 643 references that say
+     *   nothing. The four that do are `logs`/`logs-read` on both security mounts — ACCOUNT roles
+     *   whose live entry carries the ZONE-scoped `Logs` ids, which is how Cloudflare writes "all
+     *   zones from an account" (cf-mint-analytics-tokens.py:155-158).
+     */
+    const scope = policy.scope ?? scopeOfResource(policy.resource);
+    const groupIds = policy.groups.flatMap((name) => {
+      const id = ids.get(groupKey(name, scope));
+      if (id === undefined) missing.add(name);
+      return id === undefined ? [] : [id];
+    });
+    return {
+      effect: policy.effect,
+      groupIds: policy.groupOrder === 'by-id' ? [...groupIds].sort() : groupIds,
+      groupOrder: policy.groupOrder,
+      resources: { [policy.resource]: '*' },
+    };
+  });
+  return { missing: [...missing].sort(), policies };
+};
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const stringMap = (value: unknown): Readonly<Record<string, string>> | undefined => {
+  if (!isRecord(value)) return undefined;
+  const out: Record<string, string> = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (typeof item !== 'string') return undefined;
+    out[key] = item;
+  }
+  return out;
+};
+
+const entryOf = (entry: unknown): WirePolicy | undefined => {
+  if (!isRecord(entry) || typeof entry['effect'] !== 'string') return undefined;
+  const resources = stringMap(entry['resources']);
+  const groups = entry['permission_groups'];
+  if (resources === undefined || !Array.isArray(groups)) return undefined;
+  const groupIds = groups.flatMap((group) =>
+    isRecord(group) && typeof group['id'] === 'string' ? [group['id']] : [],
+  );
+  return groupIds.length === groups.length
+    ? { effect: entry['effect'], groupIds, resources }
+    : undefined;
+};
+
+/**
+ * The live `policies` string parsed, or undefined when it is not a policy document.
+ *
+ * ⚠️ UNDEFINED IS NOT ABSENCE. It means the role exists and its policies could not be read, which
+ *   compares unequal to every declaration — so it plans `update`, and reconcile's re-read refuses
+ *   to call a write that still reads back like that a success.
+ */
+export const parseLivePolicies = (raw: unknown): WirePolicy[] | undefined => {
+  if (typeof raw !== 'string') return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  if (!Array.isArray(parsed)) return undefined;
+  const policies = parsed.map(entryOf);
+  return policies.every((policy): policy is WirePolicy => policy !== undefined)
+    ? policies
+    : undefined;
+};
+
+/**
+ * The `policies` field for a write — the array cfhf.py:174-180 built, serialized.
+ *
+ * ⚠️ NOT BYTE-IDENTICAL TO WHAT PYTHON SENT, AND IT NEED NOT BE. `json.dumps` put a space after
+ *   every `:` and `,`; this emits none. The engine unmarshals the string into structs
+ *   (path_roles.go:161-166) and stores those, never the text, so the stored role and the read
+ *   that diff compares are the same either way.
+ */
+export const policiesJson = (policies: readonly WirePolicy[]) =>
+  JSON.stringify(
+    policies.map((policy) => ({
+      effect: policy.effect,
+      resources: policy.resources,
+      permission_groups: policy.groupIds.map((id) => ({ id })),
+    })),
+  );
+
+const sameList = (a: readonly string[], b: readonly string[]) =>
+  a.length === b.length && a.every((item, i) => item === b[i]);
+
+const sameResources = (
+  a: Readonly<Record<string, string>>,
+  b: Readonly<Record<string, string>>,
+) => {
+  const keys = Object.keys(a);
+  return keys.length === Object.keys(b).length && keys.every((key) => a[key] === b[key]);
+};
+
+/**
+ * ⛔ THE POLICY EQUALITY.
+ *
+ *   • Entry count and entry ORDER must match: cfhf.py always wrote the scope entry first and the
+ *     account entry second (cfhf.py:174-180).
+ *   • Within an entry: effect, the resource map, and the group IDs — IN ORDER for a `declared`
+ *     entry, because cfhf.py:175 kept yaml order; AS A SORTED LIST for a `by-id` entry, because
+ *     cfhf.py:180 sorted it, so its order never carried meaning.
+ *
+ * ⚠️ NOT ORDER-INSENSITIVE EVERYWHERE, ON PURPOSE. Cloudflare treats a group list as a set, so a
+ *   reordered `declared` entry mints an identical token — and still plans `update` here. The
+ *   Python would have rewritten it as well, and an adoption that is noop only up to reordering
+ *   would not prove the port exact.
+ */
+export const samePolicies = (want: readonly ResolvedPolicy[], have: readonly WirePolicy[]) =>
+  want.length === have.length &&
+  want.every((w, i) => {
+    const h = have[i];
+    if (h === undefined || w.effect !== h.effect || !sameResources(w.resources, h.resources)) {
+      return false;
+    }
+    return w.groupOrder === 'by-id'
+      ? sameList([...w.groupIds].sort(), [...h.groupIds].sort())
+      : sameList(w.groupIds, h.groupIds);
+  });

package/src/openbao/cloudflare-role-form.test.ts

@@ -0,0 +1,177 @@
+/**
+ * The equality Bao.CloudflareRole's diff and reconcile rest on: TTLs as seconds, description
+ * exactly, and policies with order significant in a declared entry and insignificant in the
+ * account entry the Python sorted. Plus the write body and the refusals.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { atEveryScope, resolvePolicies } from './cloudflare-policy.ts';
+import {
+  type BaoCloudflareRoleProps,
+  attributesOf,
+  differences,
+  liveRoleOf,
+  refusalOf,
+  writeBody,
+} from './cloudflare-role-form.ts';
+
+const ZONE = 'com.cloudflare.api.account.zone.z1';
+const ACCOUNT = 'com.cloudflare.api.account.acct';
+
+const PROPS: BaoCloudflareRoleProps = {
+  description: 'Deploy with a route. (zone: example.com)',
+  maxTtl: '2h',
+  mount: 'cloudflare-acme-platform',
+  name: 'example-com-workers-deploy-full',
+  policies: [
+    {
+      effect: 'allow',
+      groupOrder: 'declared',
+      groups: ['Routes Write', 'DNS Write'],
+      resource: ZONE,
+    },
+    {
+      effect: 'allow',
+      groupOrder: 'by-id',
+      groups: ['Scripts Write', 'Containers Write'],
+      resource: ACCOUNT,
+    },
+  ],
+  ttl: '30m',
+};
+
+const IDS = new Map([
+  ['Containers Write', 'c'],
+  ['DNS Write', 'd'],
+  ['Routes Write', 'r'],
+  ['Scripts Write', 's'],
+]);
+
+const { policies: RESOLVED } = resolvePolicies(PROPS.policies, atEveryScope(IDS));
+
+/** A policies string in the engine's own marshalled shape. */
+const wire = (entries: [string, string[]][]) =>
+  JSON.stringify(
+    entries.map(([resource, ids]) => ({
+      effect: 'allow',
+      resources: { [resource]: '*' },
+      permission_groups: ids.map((id) => ({ id })),
+    })),
+  );
+
+const live = (overrides: Record<string, unknown> = {}) =>
+  liveRoleOf({
+    description: PROPS.description,
+    max_ttl: 7200,
+    name: PROPS.name,
+    policies: wire([
+      [ZONE, ['r', 'd']],
+      [ACCOUNT, ['c', 's']],
+    ]),
+    ttl: 1800,
+    ...overrides,
+  });
+
+const fields = (role = live(), props: BaoCloudflareRoleProps = PROPS) =>
+  differences(props, RESOLVED, role).map((d) => d.field);
+
+describe('differences', () => {
+  it('is empty when live matches, TTL text compared to engine seconds', () => {
+    assert.deepEqual(fields(), []);
+  });
+
+  it('reads the account entry as a sorted set, because the Python sorted it', () => {
+    const reordered = wire([
+      [ZONE, ['r', 'd']],
+      [ACCOUNT, ['s', 'c']],
+    ]);
+    assert.deepEqual(fields(live({ policies: reordered })), []);
+  });
+
+  it('keeps group order significant in a declared entry', () => {
+    const reordered = wire([
+      [ZONE, ['d', 'r']],
+      [ACCOUNT, ['c', 's']],
+    ]);
+    assert.deepEqual(fields(live({ policies: reordered })), ['policies']);
+  });
+
+  // The drift role's shape on 2026-09-14: the same entries, account first.
+  it('keeps entry order significant', () => {
+    const swapped = wire([
+      [ACCOUNT, ['c', 's']],
+      [ZONE, ['r', 'd']],
+    ]);
+    assert.deepEqual(fields(live({ policies: swapped })), ['policies']);
+  });
+
+  it('catches a different resource, a missing group and an extra entry', () => {
+    for (const policies of [
+      wire([
+        [`${ZONE}x`, ['r', 'd']],
+        [ACCOUNT, ['c', 's']],
+      ]),
+      wire([
+        [ZONE, ['r', 'd']],
+        [ACCOUNT, ['c']],
+      ]),
+      wire([
+        [ZONE, ['r', 'd']],
+        [ACCOUNT, ['c', 's']],
+        [ACCOUNT, ['c']],
+      ]),
+    ]) {
+      assert.deepEqual(fields(live({ policies })), ['policies'], policies);
+    }
+  });
+
+  it('names description, ttl and max_ttl separately', () => {
+    const drifted = live({ description: 'widened by hand', max_ttl: 3600, ttl: 600 });
+    assert.deepEqual(fields(drifted), ['description', 'ttl', 'max_ttl']);
+  });
+
+  it('treats live policies that are not a policy document as different', () => {
+    assert.deepEqual(fields(live({ policies: 'not json' })), ['policies']);
+    assert.deepEqual(fields(live({ policies: '[{"effect":"allow"}]' })), ['policies']);
+  });
+
+  it('never equals an unparseable declared ttl, and reconcile refuses it', () => {
+    const props = { ...PROPS, ttl: '1h30m' };
+    assert.deepEqual(fields(live(), props), ['ttl']);
+    assert.match(refusalOf(props) ?? '', /unparseable duration ttl=1h30m/);
+  });
+});
+
+describe('writeBody', () => {
+  it('sends the four fields apply-roles.py sent, policies in the engine shape with sorted account IDs', () => {
+    const body = writeBody(PROPS, RESOLVED);
+    assert.deepEqual(Object.keys(body).sort(), ['description', 'max_ttl', 'policies', 'ttl']);
+    assert.deepEqual([body.ttl, body.max_ttl, body.description], ['30m', '2h', PROPS.description]);
+    assert.equal(
+      body.policies,
+      wire([
+        [ZONE, ['r', 'd']],
+        [ACCOUNT, ['c', 's']],
+      ]),
+    );
+  });
+});
+
+describe('refusalOf and attributesOf', () => {
+  it('refuses no policies and a policy with no groups', () => {
+    assert.equal(refusalOf(PROPS), undefined);
+    assert.equal(refusalOf({ ...PROPS, policies: [] }), 'no policy entries');
+    const empty = [
+      { effect: 'allow' as const, groupOrder: 'declared' as const, groups: [], resource: ZONE },
+    ];
+    assert.equal(refusalOf({ ...PROPS, policies: empty }), 'a policy with no groups');
+  });
+
+  it('builds attributes from live only, with a stable digest', () => {
+    const attrs = attributesOf(PROPS, live({ description: 'live says this' }));
+    assert.equal(attrs.description, 'live says this');
+    assert.deepEqual([attrs.ttl, attrs.maxTtl, attrs.mount], [1800, 7200, PROPS.mount]);
+    assert.equal(attrs.digest, attributesOf(PROPS, live({ description: 'live says this' })).digest);
+    assert.notEqual(attrs.digest, attributesOf(PROPS, live()).digest);
+  });
+});

package/src/openbao/cloudflare-role-form.ts

@@ -0,0 +1,183 @@
+/**
+ * Props, attributes and field comparison for Bao.CloudflareRole — the resource is
+ * cloudflare-role.ts, the policy document rules are cloudflare-policy.ts.
+ *
+ * MEASURED from the engine (house/platform/secrets/vault/plugin/cloudflare/path_roles.go) and the
+ * 2026-09-14 snapshot of all 586 live roles:
+ *   • A role is name, description, policies, ttl and max_ttl AND NOTHING ELSE (path_roles.go:14-20
+ *     stores those; :204-210 returns them). Every snapshot read carries exactly those five keys, so
+ *     `differences` below covers the whole server-side object — no unmanaged field can drift
+ *     behind a green plan.
+ *   • ttl and max_ttl are TypeDurationSecond (:73-80) and read back as integer seconds.
+ *   • ⚠️ A WRITE MERGES, IT DOES NOT REPLACE (:117-146). The handler loads the stored role and
+ *     overwrites only the fields present — the opposite of the proxmox engine, where an omitted
+ *     field is zeroed. writeBody sends all four anyway, so a write always lands the whole
+ *     declaration and can never leave an old description behind a new policy.
+ *
+ * ⛔ NO SECRET IN PROPS OR ATTRIBUTES, AND THERE IS NONE TO LEAK. A role is permission-group IDs, a
+ *   zone or account resource, a sentence and two TTLs. The parent token lives at `<mount>/config`
+ *   and a minted token at `<mount>/creds/<name>`; nothing in this family reads either path. Keep
+ *   it that way — Alchemy persists attributes unencrypted (see policy.ts).
+ */
+import {
+  type ResolvedPolicy,
+  type WirePolicy,
+  parseLivePolicies,
+  policiesJson,
+  samePolicies,
+} from './cloudflare-policy.ts';
+import type { DeclaredPolicy } from './cloudflare-roles-expand.ts';
+import { sha256 } from './digest.ts';
+import { mountPath, parseDuration } from './mount-form.ts';
+
+export interface BaoCloudflareRoleProps {
+  /** Mount of the Cloudflare secrets engine, e.g. `cloudflare-<account>-dns`. */
+  mount: string;
+  /** Role name. ⛔ Consumers mint by it — see cloudflare-roles-expand.ts before changing one. */
+  name: string;
+  /** The description as written: a zone role's carries its ` (zone: <name>)` suffix. */
+  description: string;
+  /** Default lease TTL, e.g. `5m`. */
+  ttl: string;
+  /** Maximum lease TTL, e.g. `1h`. */
+  maxTtl: string;
+  /**
+   * Policy entries, groups by NAME. The provider resolves them through CloudflarePermissionGroups
+   * at diff and reconcile time; an ID is never a prop, so a plan can never persist a guessed one.
+   */
+  policies: DeclaredPolicy[];
+}
+
+export interface BaoCloudflareRoleAttributes {
+  mount: string;
+  name: string;
+  description: string;
+  /** Live ttl in seconds, as the engine stores it. */
+  ttl: number;
+  /** Live max_ttl in seconds. */
+  maxTtl: number;
+  /** Live `policies` JSON — group IDs and a resource, never a credential. */
+  policies: string;
+  /** SHA-256 of the fields above — safe to persist; see policy.ts. */
+  digest: string;
+}
+
+/** One live role, as a read returns it. */
+export interface LiveCloudflareRole {
+  readonly name: string;
+  readonly description: string;
+  readonly ttl: number | undefined;
+  readonly maxTtl: number | undefined;
+  readonly policiesText: string;
+  /** Undefined when `policies` is not a policy document — see parseLivePolicies. */
+  readonly policies: readonly WirePolicy[] | undefined;
+}
+
+export interface RoleDifference {
+  readonly field: 'description' | 'max_ttl' | 'policies' | 'ttl';
+  readonly want: string;
+  readonly have: string;
+}
+
+/** `cloudflare-<account>-dns/roles/homeflare-dev-dns-read` — read, write and delete use it. */
+export const rolePath = (mount: string, name: string) => `${mountPath(mount)}/roles/${name}`;
+
+const seconds = (value: unknown) =>
+  typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+
+/** A read's `data`, shaped. Lenient on purpose: a malformed field compares unequal, loudly. */
+export const liveRoleOf = (data: Readonly<Record<string, unknown>>): LiveCloudflareRole => ({
+  description: typeof data['description'] === 'string' ? data['description'] : '',
+  maxTtl: seconds(data['max_ttl']),
+  name: typeof data['name'] === 'string' ? data['name'] : '',
+  policies: parseLivePolicies(data['policies']),
+  policiesText: typeof data['policies'] === 'string' ? data['policies'] : '',
+  ttl: seconds(data['ttl']),
+});
+
+/**
+ * ⚠️ Every value is taken from `live`, the prop only standing in for a missing `name` — the same
+ *   split the sibling families use, so a read never launders the declaration back as "current".
+ */
+export const attributesOf = (
+  props: Pick<BaoCloudflareRoleProps, 'mount' | 'name'>,
+  live: LiveCloudflareRole,
+): BaoCloudflareRoleAttributes => {
+  const attrs = {
+    description: live.description,
+    maxTtl: live.maxTtl ?? 0,
+    mount: mountPath(props.mount),
+    name: live.name || props.name,
+    policies: live.policiesText,
+    ttl: live.ttl ?? 0,
+  };
+  return { ...attrs, digest: sha256(JSON.stringify(attrs)) };
+};
+
+/**
+ * Why reconcile must refuse this declaration, or undefined.
+ *
+ * ⛔ AN UNPARSEABLE TTL IS A REFUSAL, NOT A ZERO: it can never equal the live seconds, so it would
+ *   plan `update` forever. ⛔ AN EMPTY POLICY LIST OR AN ENTRY WITH NO GROUPS IS A REFUSAL TOO — the
+ *   engine rejects both (path_roles.go:147-149, :175-180), and saying so before the write names the
+ *   declaration instead of quoting the server.
+ */
+export const refusalOf = (props: BaoCloudflareRoleProps): string | undefined => {
+  const bad = [
+    ...(parseDuration(props.ttl) === undefined ? [`ttl=${props.ttl}`] : []),
+    ...(parseDuration(props.maxTtl) === undefined ? [`maxTtl=${props.maxTtl}`] : []),
+  ];
+  if (bad.length > 0) return `unparseable duration ${bad.join(', ')} (use 30s / 5m / 1h / 1d)`;
+  if (props.policies.length === 0) return 'no policy entries';
+  if (props.policies.some((policy) => policy.groups.length === 0)) return 'a policy with no groups';
+  return undefined;
+};
+
+/**
+ * The body for `PUT <mount>/roles/<name>` — the four `k=v` pairs apply-roles.py:157-162 sent.
+ *
+ * ★ THE TTLs GO AS THE DECLARED TEXT (`5m`), which is what `bao write ttl=5m` put in the JSON body,
+ *   and TypeDurationSecond parses it server-side. `policies` is a string because the field is a
+ *   string (path_roles.go:67-68), not because the engine wants the whole body stringly-typed.
+ */
+export const writeBody = (props: BaoCloudflareRoleProps, policies: readonly WirePolicy[]) => ({
+  description: props.description,
+  max_ttl: props.maxTtl,
+  policies: policiesJson(policies),
+  ttl: props.ttl,
+});
+
+const sameTtl = (want: string, have: number | undefined) => {
+  const wantSeconds = parseDuration(want);
+  return wantSeconds !== undefined && wantSeconds === have;
+};
+
+/**
+ * Every field where live differs from the resolved declaration. Empty means noop.
+ *
+ * ⛔ apply-roles.py --verify COMPARED NONE OF THESE. It lists `<mount>/roles` and reports names
+ *   only: MISSING when roles.yaml has a role the vault lacks, UNTRACKED for the reverse
+ *   (apply-roles.py:136-141, :167-173, :179-185). It never read a role. So this equality is new: the
+ *   four fields --apply WRITES (apply-roles.py:157-162), compared the way the engine reads them back
+ *   — durations as seconds, description exactly, policies by the rules in samePolicies.
+ */
+export const differences = (
+  props: Pick<BaoCloudflareRoleProps, 'description' | 'maxTtl' | 'ttl'>,
+  policies: readonly ResolvedPolicy[],
+  live: LiveCloudflareRole,
+): RoleDifference[] => {
+  const out: RoleDifference[] = [];
+  if (props.description !== live.description) {
+    out.push({ field: 'description', have: live.description, want: props.description });
+  }
+  if (!sameTtl(props.ttl, live.ttl)) {
+    out.push({ field: 'ttl', have: String(live.ttl), want: props.ttl });
+  }
+  if (!sameTtl(props.maxTtl, live.maxTtl)) {
+    out.push({ field: 'max_ttl', have: String(live.maxTtl), want: props.maxTtl });
+  }
+  if (live.policies === undefined || !samePolicies(policies, live.policies)) {
+    out.push({ field: 'policies', have: live.policiesText, want: policiesJson(policies) });
+  }
+  return out;
+};

package/src/openbao/cloudflare-role-wire.test.ts

@@ -0,0 +1,132 @@
+/**
+ * Bao.CloudflareRole's calls against a fake that behaves like the Cloudflare engine where it matters:
+ * a write parses the duration text into seconds and re-marshals `policies` (path_roles.go:117-146,
+ * :199-210), a role never written is a 404, and a delete answers 204 whether or not it existed.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { BaoError } from './bao-status.ts';
+import { atEveryScope, resolvePolicies } from './cloudflare-policy.ts';
+import { type BaoCloudflareRoleProps, differences, writeBody } from './cloudflare-role-form.ts';
+import {
+  deleteCloudflareRole,
+  readCloudflareRole,
+  writeCloudflareRole,
+} from './cloudflare-role-wire.ts';
+import { type Reply, type Seen, run, runFailure, withFake } from './fake-bao.ts';
+import { parseDuration } from './mount-form.ts';
+
+const PROPS: BaoCloudflareRoleProps = {
+  description: 'Read DNS records on one zone. (zone: example.com)',
+  maxTtl: '1h',
+  mount: 'cloudflare-acme-dns',
+  name: 'example-com-dns-read',
+  policies: [
+    {
+      effect: 'allow',
+      groupOrder: 'declared',
+      groups: ['DNS Read'],
+      resource: 'com.cloudflare.api.account.zone.z1',
+    },
+  ],
+  ttl: '5m',
+};
+
+const PATH = '/v1/cloudflare-acme-dns/roles/example-com-dns-read';
+
+/** The engine's role store, reduced to what these calls can observe. */
+const roleStore = () => {
+  const roles = new Map<string, Record<string, unknown>>();
+  return (seen: Seen): Reply => {
+    if (seen.method === 'PUT') {
+      const body = JSON.parse(seen.body) as Record<string, string>;
+      roles.set(seen.path, {
+        description: body['description'],
+        max_ttl: parseDuration(body['max_ttl'] ?? ''),
+        name: seen.path.split('/').at(-1),
+        // ★ Re-marshalled, as json.Marshal of the stored structs would be.
+        policies: JSON.stringify(JSON.parse(body['policies'] ?? 'null')),
+        ttl: parseDuration(body['ttl'] ?? ''),
+      });
+      return { status: 204 };
+    }
+    if (seen.method === 'DELETE') {
+      roles.delete(seen.path);
+      return { status: 204 };
+    }
+    const role = roles.get(seen.path);
+    return role === undefined
+      ? { json: { errors: [] }, status: 404 }
+      : { json: { data: role }, status: 200 };
+  };
+};
+
+describe('Cloudflare role wire', () => {
+  it('reads a role that was never written as absent', async () => {
+    await withFake(roleStore(), async (bao) => {
+      const env = { BAO_ADDR: bao.address };
+      assert.equal(await run(env, readCloudflareRole(PROPS.mount, PROPS.name)), undefined);
+      assert.deepEqual([bao.seen[0]?.method, bao.seen[0]?.path], ['GET', PATH]);
+    });
+  });
+
+  it('writes the four fields and reads them back with no difference', async () => {
+    await withFake(roleStore(), async (bao) => {
+      const env = { BAO_ADDR: bao.address };
+      const { policies } = resolvePolicies(
+        PROPS.policies,
+        atEveryScope(new Map([['DNS Read', 'id-read']])),
+      );
+      await run(env, writeCloudflareRole(PROPS.mount, PROPS.name, writeBody(PROPS, policies)));
+      const put = bao.seen[0];
+      assert.deepEqual([put?.method, put?.path], ['PUT', PATH]);
+      assert.equal(put?.headers.get('content-type'), 'application/json');
+      assert.deepEqual(JSON.parse(put?.body ?? ''), {
+        description: PROPS.description,
+        max_ttl: '1h',
+        policies:
+          '[{"effect":"allow","resources":{"com.cloudflare.api.account.zone.z1":"*"},' +
+          '"permission_groups":[{"id":"id-read"}]}]',
+        ttl: '5m',
+      });
+      const live = await run(env, readCloudflareRole(PROPS.mount, PROPS.name));
+      assert.ok(live);
+      assert.deepEqual([live.ttl, live.maxTtl], [300, 3600]);
+      assert.deepEqual(differences(PROPS, policies, live), []);
+    });
+  });
+
+  it('fails a refused read (403) instead of calling the role absent', async () => {
+    await withFake(
+      () => ({ json: { errors: ['permission denied'] }, status: 403 }),
+      async (bao) => {
+        const error = await runFailure({ BAO_ADDR: bao.address }, readCloudflareRole('m', 'r'));
+        assert.ok(error instanceof BaoError);
+        assert.equal(error.status, 403);
+      },
+    );
+  });
+
+  it('fails a write to a mount that is not there (404), carrying OpenBao errors', async () => {
+    const errors = ['no handler for route "cloudflare-nope/roles/r". route entry not found.'];
+    await withFake(
+      () => ({ json: { errors }, status: 404 }),
+      async (bao) => {
+        const write = writeCloudflareRole('cloudflare-nope', 'r', { ttl: '5m' });
+        const error = await runFailure({ BAO_ADDR: bao.address }, write);
+        assert.ok(error instanceof BaoError);
+        assert.deepEqual(error.errors, errors);
+      },
+    );
+  });
+
+  it('deletes idempotently: a role already gone is success', async () => {
+    await withFake(
+      () => ({ json: { errors: [] }, status: 404 }),
+      async (bao) => {
+        await run({ BAO_ADDR: bao.address }, deleteCloudflareRole(PROPS.mount, PROPS.name));
+        assert.deepEqual([bao.seen[0]?.method, bao.seen[0]?.path], ['DELETE', PATH]);
+      },
+    );
+  });
+});