@homeflare/alchemy 0.1.0

package/src/openbao/cloudflare-permission-groups-solve.test.ts

@@ -0,0 +1,171 @@
+/**
+ * The bootstrap solver — ⚠️ temporary, like the code it tests. Resolvable by single-group pairs and
+ * by elimination; ambiguous in both directions; unresolved when nothing isolates a name;
+ * contradicted when an entry declares a known name without its id; and never a pair inferred from
+ * position. Unknown names at lookup time are in cloudflare-permission-groups.test.ts, because that
+ * is where a lookup happens.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  type Observation,
+  describeProblems,
+  observationsOf,
+  solveGroups,
+} from './cloudflare-permission-groups-solve.ts';
+import type { WirePolicy } from './cloudflare-policy.ts';
+import type { ExpandedRole } from './cloudflare-roles-expand.ts';
+
+const obs = (where: string, names: string[], ids: string[]): Observation => ({ ids, names, where });
+
+describe('solveGroups', () => {
+  it('pairs single-group entries, then eliminates known pairs until nothing changes', () => {
+    const solved = solveGroups([
+      // Out of order on purpose: the chain below needs two passes to settle.
+      obs('platform/union', ['Email Routing', 'Queues Write'], ['id-queues', 'id-email']),
+      obs(
+        'platform/create[0]',
+        ['DNS Write', 'Email Routing', 'DNS Read'],
+        ['id-email', 'id-read', 'id-write'],
+      ),
+      obs('dns/read', ['DNS Read'], ['id-read']),
+      obs('dns/edit', ['DNS Write'], ['id-write']),
+    ]);
+    assert.deepEqual(Object.fromEntries(solved.groups), {
+      'DNS Read': 'id-read',
+      'DNS Write': 'id-write',
+      'Email Routing': 'id-email',
+      'Queues Write': 'id-queues',
+    });
+    assert.deepEqual([solved.ambiguous, solved.unresolved, solved.contradicted], [[], [], []]);
+  });
+
+  // ⛔ The Python kept yaml order in a declared entry, and it would have paired these correctly.
+  //    A hand-edited role would pair them wrongly with the same confidence, so position is never used.
+  it('never pairs by position', () => {
+    const solved = solveGroups([
+      obs('platform/run', ['AI Gateway Read', 'AI Gateway Run'], ['a', 'b']),
+    ]);
+    assert.equal(solved.groups.size, 0);
+    assert.deepEqual(solved.unresolved, ['AI Gateway Read', 'AI Gateway Run']);
+  });
+
+  it('reports a name bound to two ids as ambiguous and keeps it out of the map', () => {
+    const solved = solveGroups([
+      obs('dns/a-dns-read', ['DNS Read'], ['id-read']),
+      obs('dns/b-dns-read', ['DNS Read'], ['id-write']),
+    ]);
+    assert.equal(solved.groups.has('DNS Read'), false);
+    assert.deepEqual(solved.ambiguous, [
+      { bound: ['id-read', 'id-write'], kind: 'name', value: 'DNS Read' },
+    ]);
+    assert.match(describeProblems(solved)[0] ?? '', /^ambiguous: name "DNS Read" is bound to ids/);
+  });
+
+  it('reports an id bound to two names as ambiguous', () => {
+    const solved = solveGroups([
+      obs('dns/edit', ['DNS Write'], ['id-1']),
+      obs('dns/also-edit', ['Zone DNS Write'], ['id-1']),
+    ]);
+    assert.equal(solved.groups.size, 0);
+    assert.deepEqual(solved.ambiguous, [
+      { bound: ['DNS Write', 'Zone DNS Write'], kind: 'id', value: 'id-1' },
+    ]);
+  });
+
+  // ⚠️ A contradicting single-group role must surface even when its name was already learned.
+  it('records a contradicting single-group entry wherever it sits', () => {
+    const solved = solveGroups([
+      obs('dns/x', ['DNS Read'], ['id-read']),
+      obs('dns/union', ['DNS Read', 'Cache Purge'], ['id-read', 'id-purge']),
+      obs('dns/hand-edited', ['DNS Read'], ['id-other']),
+    ]);
+    assert.equal(solved.ambiguous.length, 1);
+    assert.equal(solved.groups.has('DNS Read'), false);
+  });
+
+  it('binds nothing from an entry that contradicts what is known, and reports it', () => {
+    const solved = solveGroups([
+      obs('dns/read', ['A'], ['a']),
+      obs('platform/drifted', ['A', 'B'], ['x', 'y']),
+    ]);
+    assert.deepEqual(solved.unresolved, ['B']);
+    assert.deepEqual(solved.contradicted, [{ id: 'a', name: 'A', where: 'platform/drifted' }]);
+  });
+
+  // ⛔ THE BUG THIS CHECK EXISTS FOR. `workers-deploy` is the only single-group witness of its
+  //    group on an account. Edited by hand, it teaches the map the edited id, and without this every
+  //    union role carrying the real id would plan an update TO the edited one.
+  it('reports every entry that contradicts a hand-edited sole witness', () => {
+    const solved = solveGroups([
+      obs('platform/workers-deploy', ['Scripts Write'], ['id-edited']),
+      obs('platform/containers', ['Containers Write'], ['id-containers']),
+      obs(
+        'platform/workers-deploy-containers',
+        ['Scripts Write', 'Containers Write'],
+        ['id-containers', 'id-scripts'],
+      ),
+    ]);
+    assert.deepEqual(solved.contradicted, [
+      { id: 'id-edited', name: 'Scripts Write', where: 'platform/workers-deploy-containers' },
+    ]);
+    assert.match(
+      describeProblems(solved).at(-1) ?? '',
+      /^contradicted: platform\/workers-deploy-containers declares "Scripts Write" but lacks its id id-edited$/,
+    );
+  });
+
+  it('skips an entry whose name and id counts differ, without calling it a contradiction', () => {
+    const solved = solveGroups([
+      obs('dns/read', ['A'], ['a']),
+      obs('dns/short', ['A', 'B'], ['a']),
+    ]);
+    assert.deepEqual([solved.unresolved, solved.contradicted], [['B'], []]);
+    assert.match(describeProblems(solved)[0] ?? '', /^unresolved: no live role isolates "B"/);
+  });
+});
+
+const ZONE = 'com.cloudflare.api.account.zone.z1';
+const ACCOUNT = 'com.cloudflare.api.account.acct';
+
+const declaredRole: ExpandedRole = {
+  account: 'acme',
+  accountId: 'acct',
+  catalog: { description: '', maxTtl: '1h', permissions: [], ttl: '5m', zone: 'example.com' },
+  description: ' (zone: example.com)',
+  maxTtl: '1h',
+  mount: 'cloudflare-acme-platform',
+  name: 'example-com-create',
+  policies: [
+    { effect: 'allow', groupOrder: 'declared', groups: ['Routes'], resource: ZONE },
+    { effect: 'allow', groupOrder: 'by-id', groups: ['Scripts', 'Queues'], resource: ACCOUNT },
+  ],
+  surface: 'platform',
+  ttl: '5m',
+};
+
+describe('observationsOf', () => {
+  it('pairs declared and live entries by resource, whatever order live stored them in', () => {
+    const live = new Map<string, readonly WirePolicy[]>([
+      [
+        'cloudflare-acme-platform/example-com-create',
+        [
+          { effect: 'allow', groupIds: ['q', 's'], resources: { [ACCOUNT]: '*' } },
+          { effect: 'allow', groupIds: ['r'], resources: { [ZONE]: '*' } },
+        ],
+      ],
+    ]);
+    assert.deepEqual(observationsOf([declaredRole], live), [
+      { ids: ['r'], names: ['Routes'], where: 'cloudflare-acme-platform/example-com-create[0]' },
+      {
+        ids: ['q', 's'],
+        names: ['Scripts', 'Queues'],
+        where: 'cloudflare-acme-platform/example-com-create[1]',
+      },
+    ]);
+  });
+
+  it('observes nothing for a role that is not live', () => {
+    assert.deepEqual(observationsOf([declaredRole], new Map()), []);
+  });
+});

package/src/openbao/cloudflare-permission-groups-solve.ts

@@ -0,0 +1,197 @@
+/**
+ * ⚠️ TEMPORARY — DELETE WITH `permissionGroupsFromLiveRoles` (cloudflare-permission-groups.ts) ONCE
+ *   `GET <mount>/permission-groups` IS DEPLOYED ON THE CLOUDFLARE ENGINE.
+ *
+ * The pure half of the bootstrap: recover permission-group name → ID from roles whose names are
+ * declared (roles.yaml) and whose IDs are live (the engine).
+ *
+ * ★ WHY IT EXISTS AT ALL. apply-roles.py resolved names with
+ *   `GET /accounts/<id>/tokens/permission_groups` (cfhf.py:147-148) under a Cloudflare parent
+ *   credential, which agents may not use. The engine is gaining an endpoint that answers under its
+ *   own credential; until it ships, the only other witness is the roles apply-roles.py already
+ *   wrote, each pairing a list of names with a list of IDs.
+ *
+ * ⛔ NEVER A GUESS.
+ *   1. Every entry with exactly one name and one ID binds that pair.
+ *   2. Then, until nothing changes: an entry left with exactly ONE name and ONE ID not yet known
+ *      binds those two.
+ *   3. Once settled, every entry is checked against the map: one that declares a known name without
+ *      carrying that name's ID CONTRADICTS it.
+ *   POSITIONS ARE NEVER USED, even where the Python kept yaml order — a hand-edited role would
+ *   otherwise teach the map a wrong pair in silence. A name bound to two IDs, or an ID bound to two
+ *   names, is AMBIGUOUS; a name nothing isolates is UNRESOLVED; and a contradiction is exactly
+ *   that. Each is an error for the whole account, not a best effort.
+ *
+ * ⛔ THE CONTRADICTION CHECK IS THE ONE THAT BITES, AND IT WAS FOUND BY A TEST, NOT BY DESIGN. When a
+ *   name has ONE single-group witness and that role was edited by hand, step 1 learns the edited ID,
+ *   and the multi-group roles carrying the real one merely fail to eliminate. Unchecked, diff would
+ *   then plan every one of those roles as an update TO THE EDITED ID — a hand edit propagated by the
+ *   tool meant to catch it. Which side is wrong is unknowable here; only Cloudflare knows.
+ * ⚠️ THE PRICE: SOURCE (b) CANNOT PLAN A GROUP ADDED TO, OR SWAPPED IN, AN EXISTING ROLE. That edit
+ *   looks exactly like the hand edit above — declared names disagreeing with live IDs — so it fails
+ *   the account. New roles and removed groups still plan. (b) is for ADOPTION; changes wait for (a).
+ *
+ * ⛔ IT KEYS BY NAME AND THE ENGINE SOURCE KEYS BY (NAME, SCOPE) — DELIBERATELY UNCHANGED, 2026-09-15.
+ *   A live role is a list of ids with no scopes, so a name is all this can key on; seven names the
+ *   engine lists TWICE (once account-scoped, once zone-scoped) are one entry here, holding whichever
+ *   id the estate happens to carry. cloudflare-policy.ts `atEveryScope` is where that map is widened
+ *   to the scoped key the resolver now uses, and it is the honest shape of this blind spot: this file
+ *   is the OFFLINE PARITY PROOF against a production export, and rewriting it to a key it cannot
+ *   observe would make it agree with the engine by construction instead of by measurement.
+ *
+ * ⚠️ WHAT IT CANNOT CATCH. The names come from roles.yaml itself, so a group misnamed CONSISTENTLY
+ *   — every use of `DNS Read` spelled `DNS Reed` — pairs the wrong name with the right ID and
+ *   resolves cleanly, where Cloudflare would have refused it. cloudflare/parity.ts cross-checks the
+ *   catalog documents apply-roles.py wrote, which hold names that DID resolve against Cloudflare at
+ *   the last apply, for exactly that reason. The engine endpoint has no such blind spot.
+ */
+import type { WirePolicy } from './cloudflare-policy.ts';
+import type { ExpandedRole } from './cloudflare-roles-expand.ts';
+
+export interface Observation {
+  /** `<mount>/<role>[<entry>]`, for messages. */
+  readonly where: string;
+  readonly names: readonly string[];
+  readonly ids: readonly string[];
+}
+
+export interface Conflict {
+  /** `name` bound to several IDs, or `id` bound to several names. */
+  readonly kind: 'id' | 'name';
+  readonly value: string;
+  readonly bound: readonly string[];
+}
+
+/** An entry declaring `name`, whose ID the map knows as `id`, without carrying `id`. */
+export interface Contradiction {
+  readonly where: string;
+  readonly name: string;
+  readonly id: string;
+}
+
+export interface Solved {
+  readonly groups: ReadonlyMap<string, string>;
+  readonly ambiguous: readonly Conflict[];
+  readonly unresolved: readonly string[];
+  readonly contradicted: readonly Contradiction[];
+}
+
+/**
+ * One observation per declared entry whose resource matches exactly one live entry of that role.
+ *
+ * ★ PAIRED BY RESOURCE, NOT BY POSITION. A zone role's account groups sit on the account resource
+ *   and nowhere else, whatever order the entries were stored in. An entry that shares its resource
+ *   with a sibling, or finds no single live match, observes nothing — the diff reports it instead.
+ */
+export const observationsOf = (
+  declared: readonly ExpandedRole[],
+  live: ReadonlyMap<string, readonly WirePolicy[]>,
+): Observation[] =>
+  declared.flatMap((role) => {
+    const entries = live.get(`${role.mount}/${role.name}`);
+    if (entries === undefined) return [];
+    return role.policies.flatMap((policy, i) => {
+      const twins = role.policies.filter((other) => other.resource === policy.resource);
+      const matching = entries.filter(
+        (entry) => Object.keys(entry.resources).length === 1 && policy.resource in entry.resources,
+      );
+      const [only] = matching;
+      if (twins.length !== 1 || matching.length !== 1 || only === undefined) return [];
+      return [
+        {
+          ids: only.groupIds,
+          names: policy.groups,
+          where: `${role.mount}/${role.name}[${String(i)}]`,
+        },
+      ];
+    });
+  });
+
+const unique = (items: readonly string[]) => [...new Set(items)];
+
+export const solveGroups = (observations: readonly Observation[]): Solved => {
+  const idsOf = new Map<string, Set<string>>();
+  const namesOf = new Map<string, Set<string>>();
+  const bind = (name: string, id: string) => {
+    const ids = idsOf.get(name) ?? new Set<string>();
+    const fresh = !ids.has(id);
+    idsOf.set(name, ids.add(id));
+    namesOf.set(id, (namesOf.get(id) ?? new Set<string>()).add(name));
+    return fresh;
+  };
+  /** Known only while the name has one ID and that ID has only this name. */
+  const known = (name: string) => {
+    const ids = idsOf.get(name);
+    const [id] = ids ?? [];
+    return ids?.size === 1 && id !== undefined && namesOf.get(id)?.size === 1 ? id : undefined;
+  };
+
+  const shaped = observations.map((o) => ({ ids: unique(o.ids), names: unique(o.names) }));
+  // 1. Every single-group entry binds, unconditionally — so a contradicting one is RECORDED as a
+  //    conflict rather than skipped because its name happened to be learned first.
+  for (const { ids, names } of shaped) {
+    const [name] = names;
+    const [id] = ids;
+    if (names.length === 1 && ids.length === 1 && name !== undefined && id !== undefined) {
+      bind(name, id);
+    }
+  }
+  // 2. Elimination. ⚠️ A count mismatch proves nothing about which name is which ID, so it is skipped.
+  for (let changed = true; changed;) {
+    changed = false;
+    for (const { ids, names } of shaped) {
+      if (names.length !== ids.length) continue;
+      const knownIds = new Set(names.map(known));
+      const openNames = names.filter((name) => known(name) === undefined);
+      const openIds = ids.filter((id) => !knownIds.has(id));
+      const [name] = openNames;
+      const [id] = openIds;
+      if (
+        openNames.length === 1 &&
+        openIds.length === 1 &&
+        name !== undefined &&
+        id !== undefined
+      ) {
+        changed = bind(name, id) || changed;
+      }
+    }
+  }
+  // 3. Contradictions — including entries step 2 skipped for a count mismatch.
+  const contradicted: Contradiction[] = [];
+  for (const o of observations) {
+    for (const name of unique(o.names)) {
+      const id = known(name);
+      if (id !== undefined && !o.ids.includes(id)) contradicted.push({ id, name, where: o.where });
+    }
+  }
+
+  const groups = new Map<string, string>();
+  const ambiguous: Conflict[] = [];
+  const unresolved: string[] = [];
+  for (const name of unique(observations.flatMap((o) => o.names)).sort()) {
+    const ids = idsOf.get(name);
+    const id = known(name);
+    if (ids === undefined) unresolved.push(name);
+    else if (ids.size > 1) ambiguous.push({ bound: [...ids].sort(), kind: 'name', value: name });
+    else if (id !== undefined) groups.set(name, id);
+  }
+  for (const [id, names] of [...namesOf].sort(([a], [b]) => (a < b ? -1 : 1))) {
+    if (names.size > 1) ambiguous.push({ bound: [...names].sort(), kind: 'id', value: id });
+  }
+  return { ambiguous, contradicted, groups, unresolved };
+};
+
+/** Every conflict, unresolved name and contradiction, one line each. */
+export const describeProblems = (solved: Solved): string[] => [
+  ...solved.ambiguous.map((c) =>
+    c.kind === 'name'
+      ? `ambiguous: name ${JSON.stringify(c.value)} is bound to ids ${c.bound.join(', ')}`
+      : `ambiguous: id ${c.value} is bound to names ${c.bound.map((n) => JSON.stringify(n)).join(', ')}`,
+  ),
+  ...solved.unresolved.map(
+    (name) => `unresolved: no live role isolates ${JSON.stringify(name)} to one id`,
+  ),
+  ...solved.contradicted.map(
+    (c) => `contradicted: ${c.where} declares ${JSON.stringify(c.name)} but lacks its id ${c.id}`,
+  ),
+];