@homeflare/alchemy 0.1.0

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

@@ -0,0 +1,41 @@
+/**
+ * The OpenBao calls Bao.CloudflareRole and the live-roles bootstrap make — read, write and delete
+ * of `<mount>/roles/<name>`. Split out so each can be tested against fake-bao.
+ */
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { baoDelete, baoRead, baoWrite } from './bao-http.ts';
+import type { BaoError } from './bao-status.ts';
+import { type LiveCloudflareRole, liveRoleOf, rolePath } from './cloudflare-role-form.ts';
+
+/**
+ * The live role, or undefined when the engine answers 404.
+ *
+ * ⚠️ A MISSING MOUNT AND A MISSING ROLE BOTH READ AS UNDEFINED — both are a 404 from OpenBao, the
+ *   first as "no handler for route". That is proxmox-role.ts's ⚠️ in full: the WRITE is what tells
+ *   them apart, and it lets OpenBao's own `errors` through. A 403 or 503 is never absence
+ *   (bao-status.ts).
+ */
+export const readCloudflareRole = (
+  mount: string,
+  name: string,
+): Effect.Effect<LiveCloudflareRole | undefined, BaoError, HttpClient.HttpClient> =>
+  Effect.map(baoRead(rolePath(mount, name)), (data) =>
+    data === undefined ? undefined : liveRoleOf(data),
+  );
+
+/** ★ `PUT`, which is what `bao write` sent (bao-http.ts). A 404 here fails — see readCloudflareRole. */
+export const writeCloudflareRole = (
+  mount: string,
+  name: string,
+  body: Readonly<Record<string, string>>,
+) => baoWrite('PUT', rolePath(mount, name), body);
+
+/**
+ * Idempotent as Alchemy requires — already gone (404) is success, a refusal is not.
+ *
+ * ⚠️ THE ENGINE'S DELETE IS ONE STORAGE DELETE (path_roles.go:214-216). Tokens the role already
+ *   minted are leases, and they live to their own expiry.
+ */
+export const deleteCloudflareRole = (mount: string, name: string) =>
+  baoDelete(rolePath(mount, name));

package/src/openbao/cloudflare-role.ts

@@ -0,0 +1,189 @@
+/**
+ * A role on one of the six Cloudflare secrets-engine mounts — what one consumer may mint: the
+ * Cloudflare policy its tokens carry and the lease bounds they get. METADATA ONLY.
+ *
+ * ★ THE PORT OF apply-roles.py's WRITE. roles.yaml expands to these (cloudflare-roles-expand.ts),
+ *   and what used to be `bao write <mount>/roles/<name> ttl= max_ttl= description= policies=` is
+ *   reconcile below. The props name permission groups; CloudflarePermissionGroups turns them into
+ *   IDs at diff and reconcile time.
+ *
+ * ⛔ NO SECRET IN PROPS OR ATTRIBUTES — see cloudflare-role-form.ts. ⛔ AND ISSUANCE IS NOT THIS
+ *   RESOURCE: `<mount>/creds/<name>` returns a LIVE Cloudflare token, and a token declared as a
+ *   resource would outlive its lease in Alchemy's unencrypted state (proxmox-role.ts has the four
+ *   places it would land). This declares the door; minting is a runtime call.
+ *
+ * ★ `defaultRemovalPolicy: 'retain'` — deleting a role breaks every consumer that mints from it,
+ *   and apply-roles.py never deleted one either: an unexplained role was reported UNTRACKED and
+ *   left alone (apply-roles.py:190-196). Opt in with `.pipe(RemovalPolicy.destroy())`.
+ */
+import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { groupKey, scopeOfResource } from './cloudflare-group-scope.ts';
+import { CloudflarePermissionGroups, type GroupRef } from './cloudflare-permission-groups.ts';
+import { resolvePolicies } from './cloudflare-policy.ts';
+import {
+  type BaoCloudflareRoleAttributes,
+  type BaoCloudflareRoleProps,
+  attributesOf,
+  differences,
+  refusalOf,
+  rolePath,
+  writeBody,
+} from './cloudflare-role-form.ts';
+import {
+  deleteCloudflareRole,
+  readCloudflareRole,
+  writeCloudflareRole,
+} from './cloudflare-role-wire.ts';
+
+export type { BaoCloudflareRoleAttributes, BaoCloudflareRoleProps };
+
+/**
+ * ⚠️ CloudflarePermissionGroups IS NOT A REQUIREMENT OF THE RESOURCE. The provider takes it once, when
+ *   it is built (`yield* CloudflarePermissionGroups` below), and alchemy.run.ts supplies it to the
+ *   provider layer with `Layer.provide`. Listing it here as well made it a requirement of the STACK
+ *   body, which Alchemy only lets name its own provider and stack services — tsc refused the wiring.
+ */
+export interface BaoCloudflareRole extends Resource<
+  'Bao.CloudflareRole',
+  BaoCloudflareRoleProps,
+  BaoCloudflareRoleAttributes,
+  never,
+  HttpClient.HttpClient
+> {}
+
+export const BaoCloudflareRole = Resource<BaoCloudflareRole>('Bao.CloudflareRole', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const BaoCloudflareRoleProvider = () =>
+  Provider.effect(
+    BaoCloudflareRole,
+    Effect.gen(function* () {
+      const groups = yield* CloudflarePermissionGroups;
+
+      /**
+       * The declaration with IDs. ⛔ A name that does not resolve fails here — never a guess.
+       *
+       * ⛔ ONE REF PER (NAME, SCOPE), NOT PER NAME. The entry's resource is what says which scope
+       *   its groups are gated at, so a role whose zone entry and account entry name one group asks
+       *   for both ids; deduplicating by name alone would ask for one and use it for both.
+       */
+      const resolved = (props: BaoCloudflareRoleProps) =>
+        Effect.gen(function* () {
+          const refs = new Map<string, GroupRef>();
+          for (const policy of props.policies) {
+            /** ⛔ THE SAME PREFERENCE resolvePolicies MAKES — ask for the id the entry will use. */
+            const scope = policy.scope ?? scopeOfResource(policy.resource);
+            for (const name of policy.groups) refs.set(groupKey(name, scope), { name, scope });
+          }
+          const ids = yield* groups.resolve(props.mount, [...refs.values()]);
+          const { missing, policies } = resolvePolicies(props.policies, ids);
+          if (missing.length > 0) {
+            return yield* Effect.die(
+              new Error(
+                `Bao.CloudflareRole ${rolePath(props.mount, props.name)}: groups ` +
+                  `${missing.join(', ')} came back unresolved from a lookup that reported success.`,
+              ),
+            );
+          }
+          return policies;
+        });
+
+      return BaoCloudflareRole.Provider.of({
+        /**
+         * ⛔ `<mount>/roles` IS NOT A LIST OF THINGS THIS OWNS. MEASURED 2026-09-14: 586 live roles,
+         *   585 of which roles.yaml declares — and the 586th, cloudflare-<account>-platform/
+         *   alchemy-os-create, is exactly the role nobody has decided about. Returning it would
+         *   invite Alchemy to adopt, then delete, a role that may be someone's live credential.
+         */
+        list: () => Effect.succeed([]),
+
+        read: Effect.fn(function* ({ olds }) {
+          const live = yield* readCloudflareRole(olds.mount, olds.name);
+          return live === undefined ? undefined : attributesOf(olds, live);
+        }),
+
+        /**
+         * ⛔ IT COMPARES THE LIVE ROLE, NOT THE STORED DIGEST. A policy widened by hand in the
+         *   OpenBao UI changes what every future token can do while the digest in Postgres still
+         *   says everything is fine.
+         *
+         * ⚠️ NO `replace`, EVEN FOR A NAME OR MOUNT CHANGE. A different path is a different object,
+         *   so diff reads the new path, finds it absent and plans `update`; reconcile creates it and
+         *   the old role is left live, retained and unmanaged — the same outcome apply-roles.py's
+         *   UNTRACKED report had. declareCloudflareRoles puts mount and name in the resource id, so
+         *   a rename there is a new resource anyway.
+         */
+        diff: Effect.fn(function* ({ news, output }) {
+          if (output === undefined || !isResolved(news)) return undefined;
+          /**
+           * ⚠️ A DECLARATION reconcile WOULD REFUSE MUST NEVER PLAN AS noop — route it to reconcile,
+           *   which says why (pki-role.ts has the same guard).
+           */
+          if (refusalOf(news) !== undefined) return { action: 'update' } as const;
+          const policies = yield* resolved(news);
+          const live = yield* readCloudflareRole(news.mount, news.name);
+          if (live === undefined) return { action: 'update' } as const;
+          return differences(news, policies, live).length === 0
+            ? ({ action: 'noop' } as const)
+            : ({ action: 'update' } as const);
+        }),
+
+        reconcile: Effect.fn(function* ({ news }) {
+          const path = rolePath(news.mount, news.name);
+          const refusal = refusalOf(news);
+          if (refusal !== undefined) {
+            return yield* Effect.die(new Error(`Bao.CloudflareRole ${path}: ${refusal}.`));
+          }
+          const policies = yield* resolved(news);
+          const live = yield* readCloudflareRole(news.mount, news.name);
+          /**
+           * ⛔ ADOPTING A ROLE THAT ALREADY MATCHES MUST NOT REWRITE IT. Alchemy's `adopted` action
+           *   routes through reconcile (policy.ts has the Apply.ts reading), so without this guard
+           *   the first deploy would PUT all 585 roles — byte-identical in the happy case, and a
+           *   silent rewrite of live grants the moment the port disagreed with production.
+           */
+          if (live === undefined || differences(news, policies, live).length > 0) {
+            yield* writeCloudflareRole(news.mount, news.name, writeBody(news, policies));
+          }
+          const after = yield* readCloudflareRole(news.mount, news.name);
+          if (after === undefined) {
+            return yield* Effect.die(
+              new Error(`Bao.CloudflareRole ${path}: the write succeeded but the role is absent.`),
+            );
+          }
+          /**
+           * ⛔ THE WRITE IS NOT TRUSTED, IT IS RE-READ. The engine re-marshals `policies` from structs
+           *   (path_roles.go:199-207), so a document it stored differently from what was sent — a
+           *   dropped group, a merged resource — shows up here as a named field, not as a green
+           *   deploy followed by a 403 at mint time.
+           */
+          const left = differences(news, policies, after);
+          if (left.length > 0) {
+            return yield* Effect.die(
+              new Error(
+                `Bao.CloudflareRole ${path}: wrote cleanly but reads back different in ` +
+                  `${left.map((d) => d.field).join(', ')}. Inspect the role before retrying.`,
+              ),
+            );
+          }
+          return attributesOf(news, after);
+        }),
+
+        /**
+         * ⛔ DELETING A ROLE DOES NOT REVOKE THE TOKENS IT MINTED. They are leases on Cloudflare API
+         *   tokens and live to their own expiry, so this is an availability change for every
+         *   consumer of `creds/<name>`, never a containment action — to contain a leak, revoke the
+         *   lease. Idempotent: already gone is success (bao-status.ts).
+         */
+        delete: Effect.fn(function* ({ output }) {
+          yield* deleteCloudflareRole(output.mount, output.name);
+          return undefined;
+        }),
+      });
+    }),
+  );

package/src/openbao/cloudflare-roles-config.ts

@@ -0,0 +1,230 @@
+/**
+ * roles.yaml, parsed and checked — the input half of the Cloudflare role expansion. The expansion
+ * itself is cloudflare-roles-expand.ts.
+ *
+ * ★ BUN's OWN PARSER, NO DEPENDENCY. `Bun.YAML.parse` ships in Bun 1.4 — MEASURED on 1.4.0:
+ *   `typeof Bun.YAML` is `object` with `parse` and `stringify`, typed in bun-types 1.4.2
+ *   (bun.d.ts:1479). The Python read the same file with PyYAML's `safe_load` (cfroles.py:41-43).
+ * ⚠️ THEY ARE DIFFERENT PARSERS, SO THE SHAPE IS CHECKED, NOT TRUSTED. The file leans on flow
+ *   mappings (`- { name: dns-edit, groups: [DNS Write] }`), and a bare `5m` must stay a string.
+ *   MEASURED against roles.yaml: both parsers give `ttl` as the string `5m`, and both keep
+ *   `'Access: Apps and Policies Write'` as one name. parity.ts against the live snapshot is the
+ *   end-to-end proof; a field of the wrong type fails loudly here instead of expanding to nonsense.
+ *
+ * ⛔ A MISSING FIELD IS AN ERROR, NEVER A DEFAULT — except exactly where the Python defaulted:
+ *   `desc` to '' (cfroles.py:86, :100), an account's `zones` to "all" (:57), `surfaces`,
+ *   `zone_roles` and `account_roles` to empty (:59, :62, :96), `zone_types` to empty (:74) and
+ *   `account_groups` to empty (:90). Everywhere else the Python raised KeyError, and so does this.
+ *
+ * ⚠️ `consumers:` IS NOT READ HERE. It belongs to apply-consumers.py, and declaring it is the next
+ *   phase — see the report that came with this file.
+ */
+import { GROUP_SCOPES, groupScopeNamed } from './cloudflare-group-scope.ts';
+
+/** One `zone_roles` or `account_roles` entry. */
+export interface RoleTemplate {
+  readonly name: string;
+  readonly groups: readonly string[];
+  /** Duration text exactly as written (`5m`), which is what apply-roles.py sent. */
+  readonly ttl: string;
+  readonly maxTtl: string;
+  readonly desc: string;
+  /** `zones:` narrowing. Undefined or empty narrows nothing — `if only and …` (cfroles.py:78). */
+  readonly zones: readonly string[] | undefined;
+  readonly zoneTypes: readonly string[];
+  /** Account-scoped groups on a ZONE role. Ignored on account roles, as cfroles.py:101 ignores it. */
+  readonly accountGroups: readonly string[];
+  /**
+   * One R2 bucket NAME, narrowing an account role's resource to that bucket alone.
+   *
+   * ⛔ BUCKET IS THE FINEST GRAIN R2 HAS — A PREFIX CANNOT BE SCOPED. So one repository per
+   *   instance in its own bucket is the only least-privilege shape for a backup credential, and
+   *   this field is what expresses it. Undefined leaves the role account-wide, which is what every
+   *   role declared before 2026-09-15 is.
+   * ⚠️ IT ONLY MEANS ANYTHING WITH THE `Bucket Item` GROUPS. `Workers R2 Storage Write` is gated at
+   *   the ACCOUNT scope, so pairing it with a bucket resource is a token Cloudflare will mint and
+   *   that will then be refused on every call. roles.yaml says which pair goes with which.
+   */
+  readonly bucket: string | undefined;
+  /**
+   * The bucket's jurisdiction, which is part of its resource id and not cosmetic — a bucket
+   * created in `default` is a different resource from the same name under `eu`. Defaults to
+   * `default`, which is what every bucket in this estate is (measured: `r2_bucket_get` reports
+   * `jurisdiction default` on all 34).
+   */
+  readonly bucketJurisdiction: string;
+  /**
+   * roles.yaml `groups_scope:` — the scope this template's `groups:` NAMES resolve at, as a
+   * GROUP_SCOPES value. Undefined means the entry's own resource namespace, which is every
+   * template written before 2026-09-15.
+   *
+   * ⛔ IT SAYS WHICH ID, NOT WHICH RESOURCE. `groups_scope: zone` on an ACCOUNT role keeps the
+   *   account resource and takes the zone-scoped id of each name — Cloudflare's "all zones from
+   *   this account" (cf-mint-analytics-tokens.py:155-158). It is meaningful only for the seven
+   *   names the engine lists at two scopes; anywhere else the name has one id and answers alike.
+   */
+  readonly groupsScope: string | undefined;
+}
+
+export interface SurfaceSpec {
+  readonly zoneRoles: readonly RoleTemplate[];
+  readonly accountRoles: readonly RoleTemplate[];
+}
+
+export interface AccountSpec {
+  /** The key under `accounts:` — the `<account>` in `cloudflare-<account>-<surface>`. */
+  readonly key: string;
+  readonly id: string;
+  readonly zones: 'all' | readonly string[];
+  readonly surfaces: readonly string[];
+}
+
+export interface RolesConfig {
+  readonly namespace: string;
+  readonly surfaces: Readonly<Record<string, SurfaceSpec>>;
+  /** In file order, which is the order apply-roles.py walked them (apply-roles.py:111). */
+  readonly accounts: readonly AccountSpec[];
+}
+
+export class RolesConfigError extends Error {
+  constructor(where: string, problem: string) {
+    super(`roles.yaml ${where}: ${problem}`);
+    this.name = 'RolesConfigError';
+  }
+}
+
+type Raw = Readonly<Record<string, unknown>>;
+
+const isRaw = (value: unknown): value is Raw =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const record = (value: unknown, where: string): Raw => {
+  if (!isRaw(value)) throw new RolesConfigError(where, 'expected a mapping');
+  return value;
+};
+
+const text = (raw: Raw, key: string, where: string): string => {
+  const value = raw[key];
+  if (typeof value === 'string') return value;
+  /**
+   * ⚠️ STRICTER THAN THE PYTHON FOR A NUMBER. `ttl: 300` would have reached `bao write` as `300`
+   *   and been read as seconds. Every duration in roles.yaml is unit-suffixed, and the comparison
+   *   in cloudflare-role-form.ts only parses unit-suffixed text, so a bare number is refused here
+   *   rather than planning an update that can never settle.
+   */
+  throw new RolesConfigError(`${where}.${key}`, `expected a string, got ${JSON.stringify(value)}`);
+};
+
+const texts = (raw: Raw, key: string, where: string): readonly string[] | undefined => {
+  const value = raw[key];
+  if (value === undefined || value === null) return undefined;
+  if (Array.isArray(value) && value.every((item): item is string => typeof item === 'string')) {
+    return value;
+  }
+  throw new RolesConfigError(`${where}.${key}`, 'expected a list of strings');
+};
+
+const entries = (raw: Raw, key: string, where: string): readonly unknown[] => {
+  const value = raw[key];
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) throw new RolesConfigError(`${where}.${key}`, 'expected a list');
+  return value;
+};
+
+const template = (value: unknown, where: string): RoleTemplate => {
+  const raw = record(value, where);
+  const groups = texts(raw, 'groups', where);
+  if (groups === undefined) throw new RolesConfigError(`${where}.groups`, 'is required');
+  /**
+   * ⚠️ `bucket` IS OPTIONAL BUT NEVER EMPTY. `bucket: ''` would expand to the resource
+   *   `…r2.bucket.<acct>_default_`, which is not a bucket and not the account either — a policy
+   *   that names nothing. A missing key means account-wide; a present one must name a bucket.
+   */
+  const bucket = raw['bucket'] === undefined ? undefined : text(raw, 'bucket', where);
+  if (bucket !== undefined && bucket.length === 0) {
+    throw new RolesConfigError(`${where}.bucket`, 'is empty; omit it to stay account-wide');
+  }
+  /**
+   * ⛔ AN UNKNOWN WORD IS AN ERROR, NEVER A PASS-THROUGH. A scope roles.yaml invents matches no
+   *   group at all, so accepting it would turn a typo into "unknown group X at scope zonee" at
+   *   deploy time — a failure naming the group rather than the line that is wrong.
+   */
+  const groupsScope =
+    raw['groups_scope'] === undefined
+      ? undefined
+      : groupScopeNamed(text(raw, 'groups_scope', where));
+  if (raw['groups_scope'] !== undefined && groupsScope === undefined) {
+    throw new RolesConfigError(
+      `${where}.groups_scope`,
+      `expected one of ${Object.keys(GROUP_SCOPES).join(', ')}`,
+    );
+  }
+  return {
+    accountGroups: texts(raw, 'account_groups', where) ?? [],
+    bucket,
+    bucketJurisdiction:
+      raw['bucket_jurisdiction'] === undefined
+        ? 'default'
+        : text(raw, 'bucket_jurisdiction', where),
+    desc: raw['desc'] === undefined ? '' : text(raw, 'desc', where),
+    groups,
+    groupsScope,
+    maxTtl: text(raw, 'max_ttl', where),
+    name: text(raw, 'name', where),
+    ttl: text(raw, 'ttl', where),
+    zoneTypes: texts(raw, 'zone_types', where) ?? [],
+    zones: texts(raw, 'zones', where),
+  };
+};
+
+const surface = (name: string, value: unknown): SurfaceSpec => {
+  const where = `surfaces.${name}`;
+  const raw = record(value, where);
+  return {
+    accountRoles: entries(raw, 'account_roles', where).map((item, i) =>
+      template(item, `${where}.account_roles[${String(i)}]`),
+    ),
+    zoneRoles: entries(raw, 'zone_roles', where).map((item, i) =>
+      template(item, `${where}.zone_roles[${String(i)}]`),
+    ),
+  };
+};
+
+const account = (
+  key: string,
+  value: unknown,
+  surfaces: Readonly<Record<string, SurfaceSpec>>,
+): AccountSpec => {
+  const where = `accounts.${key}`;
+  const raw = record(value, where);
+  const names = texts(raw, 'surfaces', where) ?? [];
+  for (const name of names) {
+    /** ⚠️ cfroles.py:60 would raise KeyError at expansion; this says which account named it. */
+    if (surfaces[name] === undefined) {
+      throw new RolesConfigError(
+        `${where}.surfaces`,
+        `names ${name}, which surfaces: never defines`,
+      );
+    }
+  }
+  const zones =
+    raw['zones'] === undefined || raw['zones'] === 'all' ? 'all' : texts(raw, 'zones', where);
+  return { id: text(raw, 'id', where), key, surfaces: names, zones: zones ?? 'all' };
+};
+
+/** Parse and check roles.yaml. Throws RolesConfigError naming the first bad field. */
+export const parseRolesConfig = (yaml: string): RolesConfig => {
+  const root = record(Bun.YAML.parse(yaml), '(document)');
+  const surfaces: Record<string, SurfaceSpec> = {};
+  for (const [name, spec] of Object.entries(record(root['surfaces'], 'surfaces'))) {
+    surfaces[name] = surface(name, spec);
+  }
+  const accounts = Object.entries(record(root['accounts'], 'accounts')).map(([key, value]) =>
+    account(key, value, surfaces),
+  );
+  return {
+    accounts,
+    namespace: text(record(root['defaults'], 'defaults'), 'namespace', 'defaults'),
+    surfaces,
+  };
+};

package/src/openbao/cloudflare-roles-expand-bucket.test.ts

@@ -0,0 +1,134 @@
+/**
+ * R2 BUCKET-scoped roles: the third resource form, beside `zoneResource` and `accountResource`.
+ *
+ * ★ ITS OWN FILE, AND ITS OWN INLINE YAML, FOR TWO REASONS. The shared fixture
+ *   (cloudflare-roles.fixture.yaml) is a miniature of the REAL roles.yaml and every assertion in
+ *   cloudflare-roles-expand.test.ts counts its roles by name — adding two there moves four
+ *   unrelated expectations for no gain. And a bucket role needs no zones at all, so the smallest
+ *   thing that can prove it is three lines of yaml rather than a 64-line fixture.
+ * ⚠️ THE SPLIT IS ALSO THE CAP. The shared file is 229 lines against a 250 cap; these cases were
+ *   written there first and pushed it to 302. AGENTS.md rule 5 says extract, never compress —
+ *   the comments are the expensive part.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { bucketResource } from './cloudflare-group-scope.ts';
+import { RolesConfigError, parseRolesConfig } from './cloudflare-roles-config.ts';
+import { type CloudflareZone, type ExpandedRole, expandAll } from './cloudflare-roles-expand.ts';
+
+/**
+ * ⚠️ ONE ZONE, AND IT EXISTS ONLY SO `expandAll` HAS AN INVENTORY. An account with no zone
+ *   inventory is an ERROR there (a missing inventory is not the same as an empty one), so a bucket
+ *   role — which is an account role and touches no zone — still needs this to be present.
+ */
+const ZONES: Record<string, readonly CloudflareZone[]> = {
+  acme: [{ id: 'zone-com', internal: false, name: 'example.com' }],
+};
+
+const yaml = (roles: string) => `
+defaults: { namespace: homeflare }
+surfaces:
+  platform:
+${roles}
+accounts:
+  acme: { id: acct-acme, zones: all, surfaces: [platform] }
+`;
+
+const ACCOUNT_ROLES = yaml(`    account_roles:
+      - {
+          name: r2-backup-demo,
+          groups: [Workers R2 Storage Bucket Item Write, Workers R2 Storage Bucket Item Read],
+          bucket: demo-pg-bucket,
+          ttl: 12h,
+          max_ttl: 12h,
+          desc: 'Write one bucket and nothing else.',
+        }
+      - { name: r2-backup-eu, groups: [Workers R2 Storage Bucket Item Read],
+          bucket: demo-eu-bucket, bucket_jurisdiction: eu, ttl: 12h, max_ttl: 12h, desc: 'EU.' }
+      - { name: workers-deploy, groups: [Workers Scripts Write], ttl: 30m, max_ttl: 2h, desc: 'W.' }
+`);
+
+const expanded = expandAll(parseRolesConfig(ACCOUNT_ROLES), ZONES);
+
+const role = (name: string): ExpandedRole => {
+  const found = expanded.get('cloudflare-acme-platform')?.find((r) => r.name === name);
+  assert.ok(found, `${name} was not expanded`);
+  return found;
+};
+
+describe('R2 bucket-scoped roles', () => {
+  /**
+   * ⛔ THE UNDERSCORES ARE THE ASSERTION, not the prefix. `com.cloudflare.edge.r2.bucket.` then
+   *   `<accountId>_<jurisdiction>_<bucket>` as ONE dotted segment is what Cloudflare's R2 token
+   *   documentation specifies. A dot where an underscore belongs still mints a token; that token
+   *   matches no bucket and is refused on first use, which is indistinguishable at the call site
+   *   from a missing permission group. This is the only place that difference is ever checked.
+   */
+  it('scopes the policy to one bucket, in the edge.r2 namespace', () => {
+    assert.deepEqual(role('r2-backup-demo').policies, [
+      {
+        effect: 'allow',
+        groupOrder: 'declared',
+        groups: ['Workers R2 Storage Bucket Item Write', 'Workers R2 Storage Bucket Item Read'],
+        resource: 'com.cloudflare.edge.r2.bucket.acct-acme_default_demo-pg-bucket',
+      },
+    ]);
+  });
+
+  /** ⚠️ THE DEFAULT IS UNCHANGED: every role declared before 2026-09-15 stays account-wide. */
+  it('leaves a role with no bucket on the account resource', () => {
+    assert.equal(
+      role('workers-deploy').policies[0]?.resource,
+      'com.cloudflare.api.account.acct-acme',
+    );
+  });
+
+  /**
+   * ⛔ THE JURISDICTION IS PART OF THE IDENTITY, NOT DECORATION. A bucket of the same name under
+   *   `eu` is a DIFFERENT resource, so defaulting it silently would hand out a token for a bucket
+   *   that does not exist. Every bucket in this estate is `default` (measured on all 34), which is
+   *   exactly why the non-default path needs a test rather than a comment.
+   */
+  it('puts the jurisdiction in the middle segment', () => {
+    assert.equal(
+      role('r2-backup-eu').policies[0]?.resource,
+      'com.cloudflare.edge.r2.bucket.acct-acme_eu_demo-eu-bucket',
+    );
+    assert.equal(bucketResource('a', 'default', 'b'), 'com.cloudflare.edge.r2.bucket.a_default_b');
+  });
+
+  /**
+   * ⚠️ THE KV CATALOG SHAPE IS DELIBERATELY UNCHANGED. cloudflare-parity-catalog.ts proves the TS
+   *   catalog against what apply-roles.py published, so a new field here would read as drift on
+   *   every one of 555 roles. The bucket is stated in `desc` and shown by `--plan` instead.
+   */
+  it('does not move the catalog shape', () => {
+    assert.deepEqual(role('r2-backup-demo').catalog, {
+      description: 'Write one bucket and nothing else.',
+      maxTtl: '12h',
+      permissions: ['Workers R2 Storage Bucket Item Write', 'Workers R2 Storage Bucket Item Read'],
+      ttl: '12h',
+      zone: null,
+    });
+  });
+
+  /**
+   * ⛔ A ZONE ROLE SCOPED TO A BUCKET IS INCOHERENT, NOT NARROW. The groups a zone role carries are
+   *   gated at the zone; against a bucket resource every one of them is refused. roles.yaml cannot
+   *   express the contradiction as a type, so the expansion is the only place it can be caught.
+   */
+  it('refuses a zone role that names a bucket', () => {
+    const bad = yaml(`    zone_roles:
+      - { name: nope, groups: [DNS Read], bucket: b, ttl: 5m, max_ttl: 1h, desc: '' }
+`);
+    assert.throws(() => expandAll(parseRolesConfig(bad), ZONES), /zone role cannot be scoped/);
+  });
+
+  /** ⛔ `bucket: ''` would expand to `…_default_` — neither a bucket nor the account. */
+  it('refuses an empty bucket rather than defaulting it', () => {
+    const bad = yaml(`    account_roles:
+      - { name: nope, groups: [DNS Read], bucket: '', ttl: 5m, max_ttl: 1h, desc: '' }
+`);
+    assert.throws(() => parseRolesConfig(bad), RolesConfigError);
+  });
+});