@homeflare/alchemy 0.1.0

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

@@ -0,0 +1,231 @@
+/**
+ * The roles.yaml expansion — surfaces × accounts × zones into concrete roles — ported from
+ * cfroles.py `expand` and cfhf.py `policy_for`, with permission groups still by NAME.
+ *
+ * ★ PURE, AND NAMES STAY NAMES. The Python resolved names to IDs in the same pass
+ *   (apply-roles.py:144-150), with a Cloudflare credential in hand. Agents may not hold that
+ *   credential, so resolution is a separate step behind one interface
+ *   (cloudflare-permission-groups.ts) and nothing here knows where IDs come from.
+ *
+ * ⛔ THE NAMING AND THE ZONE RULES ARE CONTRACTS WITH EVERY CONSUMER. apply-consumers.py grants
+ *   `creds/<slug(zone)>-*` by zone (apply-consumers.py:117-120) and agents mint by role name, so a
+ *   role a port renames is a role nothing can mint. Each rule cites the line it came from, and
+ *   cloudflare/parity.ts proves the whole expansion against production.
+ */
+import { accountResource, bucketResource, zoneResource } from './cloudflare-group-scope.ts';
+import type { AccountSpec, RoleTemplate, RolesConfig } from './cloudflare-roles-config.ts';
+
+/** A zone as the expansion needs it — what cfhf.py load_account listed (cfhf.py:134-146). */
+export interface CloudflareZone {
+  readonly name: string;
+  readonly id: string;
+  /** From the `type=internal` listing. ⚠️ Shares its NAME with the public zone, never its id. */
+  readonly internal: boolean;
+}
+
+/**
+ * One policy entry, groups by name.
+ *
+ * ★ `groupOrder` CARRIES A PYTHON RULE THAT ONLY EXISTS AFTER RESOLUTION. cfhf.py:180 sorts the
+ *   account entry's group IDS — not its names — so that order cannot be computed here, only
+ *   promised. A `declared` entry keeps roles.yaml order, exactly as cfhf.py:175 emitted it.
+ */
+export interface DeclaredPolicy {
+  readonly effect: 'allow';
+  readonly resource: string;
+  readonly groups: readonly string[];
+  readonly groupOrder: 'declared' | 'by-id';
+  /**
+   * The scope these NAMES resolve at, when it is not this entry's own resource namespace —
+   * roles.yaml `groups_scope:`, already a GROUP_SCOPES value. Undefined on every entry that does
+   * not say otherwise, which is 639 of the estate's 643 group references.
+   *
+   * ⛔ IT MOVES THE LOOKUP, NEVER THE RESOURCE. The entry still binds the groups to the resource
+   *   above; only the id chosen for each name changes. That is the shape Cloudflare calls "all
+   *   zones from an account" — the ACCOUNT resource carrying ZONE-scoped groups
+   *   (house/nix/homeflare-config/scripts/cf-mint-analytics-tokens.py:155-158, beside a working
+   *   token). Without this field the resource is the only witness, and it says `account`.
+   */
+  readonly scope?: string;
+}
+
+/** What apply-roles.py wrote to the KV catalog for one role (apply-roles.py:58-62). */
+export interface CatalogView {
+  readonly description: string;
+  readonly zone: string | null;
+  readonly ttl: string;
+  readonly maxTtl: string;
+  readonly permissions: readonly string[];
+}
+
+export interface ExpandedRole {
+  readonly account: string;
+  readonly accountId: string;
+  readonly mount: string;
+  readonly surface: string;
+  readonly name: string;
+  /** Exactly what apply-roles.py:160-161 wrote — the zone suffix included. */
+  readonly description: string;
+  readonly ttl: string;
+  readonly maxTtl: string;
+  readonly policies: readonly DeclaredPolicy[];
+  readonly catalog: CatalogView;
+}
+
+/** cfroles.py:18-20 — `example.com` → `homeflare-dev`. */
+export const slug = (name: string) =>
+  name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+/**
+ * cfroles.py:23-38. ⛔ THE `-internal` SUFFIX IS WHAT KEEPS TWO ZONES OF ONE NAME APART. Slugging
+ *   both example.com zones alike would leave two roles fighting for one name, and whichever
+ *   wrote last would silently own it.
+ */
+export const zoneSlug = (zone: CloudflareZone) =>
+  `${slug(zone.name)}${zone.internal ? '-internal' : ''}`;
+
+/** cfroles.py:46-47 — one mount, and so one parent token, per (account, surface). */
+export const mountName = (account: string, surface: string) => `cloudflare-${account}-${surface}`;
+
+/**
+ * cfhf.py:151-181. ⛔ ONE ENTRY PER SCOPE, NEVER MERGED: Cloudflare gates a permission at one
+ *   scope only, so a zone role that also needs account groups gets a SECOND entry on the account
+ *   resource. ⚠️ `if account_group_ids:` — an empty list emits no second entry (cfhf.py:176).
+ */
+const policiesFor = (
+  tpl: RoleTemplate,
+  accountId: string,
+  zone: CloudflareZone | null,
+  accountGroups: readonly string[],
+): DeclaredPolicy[] => {
+  /**
+   * ⛔ A BUCKET NARROWS THE ACCOUNT RESOURCE; IT NEVER NARROWS A ZONE. A zone role scoped to an R2
+   *   bucket is not a narrower grant, it is an incoherent one — the groups a zone role carries are
+   *   gated at the zone and would be refused against a bucket resource. Refusing here is the only
+   *   place that can tell the difference; roles.yaml cannot express the contradiction as a type.
+   */
+  if (tpl.bucket !== undefined && zone !== null) {
+    throw new Error(`${tpl.name}: a zone role cannot be scoped to R2 bucket ${tpl.bucket}`);
+  }
+  const accountScoped =
+    tpl.bucket === undefined
+      ? accountResource(accountId)
+      : bucketResource(accountId, tpl.bucketJurisdiction, tpl.bucket);
+  const resource = zone === null ? accountScoped : zoneResource(zone.id);
+  const first: DeclaredPolicy = {
+    effect: 'allow',
+    groupOrder: 'declared',
+    groups: tpl.groups,
+    resource,
+    /**
+     * ⚠️ `groups_scope:` GOVERNS `groups:` AND NOTHING ELSE. The second entry below exists because
+     *   `account_groups` are account-scoped BY CONSTRUCTION (cfhf.py:176-180) — overriding its
+     *   scope from the same key would make one word mean two things in one template.
+     * ★ OMITTED, NOT SET TO THE DEFAULT, WHEN THE yaml IS SILENT: an always-present field would
+     *   rewrite the stored props of all 594 declared roles to say what the resource already said.
+     */
+    ...(tpl.groupsScope === undefined ? {} : { scope: tpl.groupsScope }),
+  };
+  if (accountGroups.length === 0) return [first];
+  const second: DeclaredPolicy = {
+    effect: 'allow',
+    groupOrder: 'by-id',
+    groups: accountGroups,
+    resource: accountResource(accountId),
+  };
+  return [first, second];
+};
+
+const build = (
+  account: AccountSpec,
+  surface: string,
+  tpl: RoleTemplate,
+  zone: CloudflareZone | null,
+  accountGroups: readonly string[],
+): ExpandedRole => ({
+  account: account.key,
+  accountId: account.id,
+  catalog: {
+    description: tpl.desc,
+    maxTtl: tpl.maxTtl,
+    // apply-roles.py:61 — groups then account_groups, names, in file order.
+    permissions: [...tpl.groups, ...accountGroups],
+    ttl: tpl.ttl,
+    zone: zone === null ? null : zone.name,
+  },
+  /**
+   * apply-roles.py:160-161. ⚠️ THE ZONE NAME, NOT ITS SLUG, so a public zone and its internal
+   *   twin describe alike, and an empty `desc` still gains the suffix after a leading space.
+   */
+  description: zone === null ? tpl.desc : `${tpl.desc} (zone: ${zone.name})`,
+  maxTtl: tpl.maxTtl,
+  mount: mountName(account.key, surface),
+  // cfroles.py:84 for zone roles, :98 for account roles.
+  name: zone === null ? tpl.name : `${zoneSlug(zone)}-${tpl.name}`,
+  policies: policiesFor(tpl, account.id, zone, accountGroups),
+  surface,
+  ttl: tpl.ttl,
+});
+
+/** cfroles.py:50-104 for one account, in the Python's order: per surface, zone roles first. */
+export const expandAccount = (
+  config: RolesConfig,
+  account: AccountSpec,
+  zones: readonly CloudflareZone[],
+): ExpandedRole[] => {
+  const roles: ExpandedRole[] = [];
+  for (const surface of account.surfaces) {
+    const spec = config.surfaces[surface];
+    if (spec === undefined) throw new Error(`surface ${surface} is not defined`);
+    for (const tpl of spec.zoneRoles) {
+      const only = tpl.zones;
+      /**
+       * ⛔ INTERNAL ZONES ARE OPT-IN PER TEMPLATE AND THE DEFAULT IS NO (cfroles.py:68-74). Only the
+       *   word `internal` in zone_types matters; `full` and `secondary` are never checked, so a
+       *   public zone of any type expands.
+       */
+      const internalOk = tpl.zoneTypes.includes('internal');
+      for (const zone of zones) {
+        if (account.zones !== 'all' && !account.zones.includes(zone.name)) continue; // :76
+        if (only !== undefined && only.length > 0 && !only.includes(zone.name)) continue; // :78
+        if (zone.internal && !internalOk) continue; // :80
+        roles.push(build(account, surface, tpl, zone, tpl.accountGroups));
+      }
+    }
+    // cfroles.py:96-103 — `account_groups` is [] on an account role, whatever the yaml says.
+    for (const tpl of spec.accountRoles) roles.push(build(account, surface, tpl, null, []));
+  }
+  return roles;
+};
+
+/**
+ * Every account's roles, grouped by mount.
+ *
+ * ⛔ A DUPLICATE ROLE ON ONE MOUNT IS AN ERROR HERE. apply-roles.py wrote both and the last write
+ *   won in silence (apply-roles.py:157-162); declared, they are two resources fighting over one
+ *   object. ⚠️ A MISSING ZONE INVENTORY IS AN ERROR TOO — an empty one is not, because an account
+ *   with no zones is real, and the Python expanded it to account roles only.
+ */
+export const expandAll = (
+  config: RolesConfig,
+  zonesByAccount: Readonly<Record<string, readonly CloudflareZone[]>>,
+): ReadonlyMap<string, readonly ExpandedRole[]> => {
+  const byMount = new Map<string, ExpandedRole[]>();
+  const seen = new Set<string>();
+  for (const account of config.accounts) {
+    const zones = zonesByAccount[account.key];
+    if (zones === undefined) throw new Error(`no zone inventory for account ${account.key}`);
+    for (const role of expandAccount(config, account, zones)) {
+      const key = `${role.mount}/roles/${role.name}`;
+      if (seen.has(key)) throw new Error(`roles.yaml expands ${key} twice`);
+      seen.add(key);
+      const mount = byMount.get(role.mount) ?? [];
+      mount.push(role);
+      byMount.set(role.mount, mount);
+    }
+  }
+  return byMount;
+};

package/src/openbao/digest.ts

@@ -0,0 +1,26 @@
+/**
+ * The digest every Bao.* family persists instead of a value — moved here from the retired
+ * bao-shell.ts, unchanged, when the package stopped shelling out to `bao`.
+ */
+
+/** ⚠️ Bun's hasher, not node:crypto — this runs under `bun --bun alchemy`. */
+/**
+ * The only form a policy body may be hashed or compared in.
+ *
+ * ⛔ OPENBAO STRIPS THE TRAILING NEWLINE AND THAT ALONE WAS A FOREVER-DIFF. MEASURED on the live
+ *   server: the assembler emits each fragment followed by a newline, so `homeflare-llm` goes in as
+ *   41 lines and `bao policy read` hands back 40 — identical text, one `\n` apart, two different
+ *   digests. Every plan therefore reported `update`, every deploy rewrote the same policy, and the
+ *   stack could never settle. It was invisible until the stack planned for the first time today.
+ *   ★ THE HTTP API HANDS BACK THE SAME STRIPPED TEXT. `bao policy read` printed `data.policy` of
+ *     `GET /v1/sys/policies/acl/<name>` (openbao v2.6.2 api/sys_policy.go:60-81), which is what
+ *     policy-wire.ts now reads directly — so the canonicalisation is still load-bearing.
+ *
+ * ⚠️ `trimEnd` ONLY. Leading and interior whitespace are part of the HCL and must not be touched —
+ *   a policy that differs by an indent really is a different document, and quietly folding that
+ *   away would hide an edit rather than a formatting artifact.
+ */
+export const canonical = (text: string) => text.trimEnd();
+
+export const sha256 = (text: string) =>
+  new Bun.CryptoHasher('sha256').update(canonical(text)).digest('hex');

package/src/openbao/fake-bao.ts

@@ -0,0 +1,84 @@
+/**
+ * A fake OpenBao for the tests beside it — `Bun.serve` on an ephemeral 127.0.0.1 port, or on a unix
+ * socket the way an agent listener can be.
+ *
+ * ⛔ TEST-ONLY, AND NEVER A REAL VAULT. No provider imports this file, it forwards nowhere, and every
+ *   helper below runs with an EXPLICIT environment rather than `process.env`, so a BAO_ADDR or
+ *   BAO_TOKEN in the shell running the tests can never be read or contacted.
+ */
+import * as Effect from 'effect/Effect';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import type { BaoEnvironment } from './bao-address.ts';
+import { BaoEnv } from './bao-http.ts';
+
+/** One request the fake received. */
+export type Seen = {
+  readonly method: string;
+  readonly path: string;
+  readonly headers: Headers;
+  readonly body: string;
+};
+
+/** What the fake answers: a status and a JSON value, or raw text for a body that is not JSON. */
+export type Reply = { readonly status: number; readonly json?: unknown; readonly text?: string };
+
+export type Fake = { readonly address: string; readonly seen: Seen[]; stop(): void };
+
+/** ★ An answer may be async, so a test can HOLD requests open and count how many overlap. */
+type Answer = (seen: Seen) => Reply | Promise<Reply>;
+
+export const fakeBao = (answer: Answer, unix?: string): Fake => {
+  const seen: Seen[] = [];
+  const fetch = async (request: Request) => {
+    const url = new URL(request.url);
+    const entry = {
+      body: await request.text(),
+      headers: request.headers,
+      method: request.method,
+      path: `${url.pathname}${url.search}`,
+    };
+    seen.push(entry);
+    const reply = await answer(entry);
+    const text = reply.text ?? (reply.json === undefined ? null : JSON.stringify(reply.json));
+    return new Response(reply.status === 204 ? null : text, {
+      headers: { 'content-type': 'application/json' },
+      status: reply.status,
+    });
+  };
+  if (unix !== undefined) {
+    const server = Bun.serve({ fetch, unix });
+    return { address: `unix://${unix}`, seen, stop: () => void server.stop(true) };
+  }
+  const server = Bun.serve({ fetch, hostname: '127.0.0.1', port: 0 });
+  return { address: server.url.origin, seen, stop: () => void server.stop(true) };
+};
+
+/** Run `body` against a fresh fake, and stop it whatever happens. */
+export const withFake = async (
+  answer: Answer,
+  body: (bao: Fake) => Promise<void>,
+  unix?: string,
+) => {
+  const bao = fakeBao(answer, unix);
+  try {
+    await body(bao);
+  } finally {
+    bao.stop();
+  }
+};
+
+const provided = <A, E>(env: BaoEnvironment, effect: Effect.Effect<A, E, HttpClient.HttpClient>) =>
+  effect.pipe(Effect.provideService(BaoEnv, env), Effect.provide(FetchHttpClient.layer));
+
+/** The effect's success, through the real FetchHttpClient, under `env` only. */
+export const run = <A, E>(
+  env: BaoEnvironment,
+  effect: Effect.Effect<A, E, HttpClient.HttpClient>,
+) => Effect.runPromise(provided(env, effect));
+
+/** The effect's failure — rejects if it succeeded. */
+export const runFailure = <A, E>(
+  env: BaoEnvironment,
+  effect: Effect.Effect<A, E, HttpClient.HttpClient>,
+) => Effect.runPromise(provided(env, Effect.flip(effect)));

package/src/openbao/forgejo-bootstrap-parse.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  readCreateOutput,
+  runningForgejoBinary,
+  usernamesFrom,
+} from './forgejo-bootstrap-parse.ts';
+
+const NIX = '/nix/store/2wagmmlb09s2r0gv839iwmdvrc18kg8h-forgejo-16.0.3/bin/forgejo';
+
+describe('runningForgejoBinary', () => {
+  test('finds the web process the daemon runs, as ps prints it', () => {
+    const ps = [
+      'COMMAND',
+      '/usr/sbin/cfprefsd agent',
+      `${NIX} web --work-path /opt/homeflare/forgejo`,
+      `${NIX} admin user list --work-path /opt/homeflare/forgejo`,
+    ].join('\n');
+    expect(runningForgejoBinary(ps)).toBe(NIX);
+  });
+
+  test('ignores a forgejo that is not serving, and one off PATH', () => {
+    expect(runningForgejoBinary(`${NIX} admin user list`)).toBeUndefined();
+    expect(runningForgejoBinary('/opt/homebrew/bin/forgejo web')).toBeUndefined();
+    expect(runningForgejoBinary('')).toBeUndefined();
+  });
+});
+
+describe('usernamesFrom', () => {
+  test('reads the Username column of the measured table', () => {
+    const table = [
+      'ID   Username            Email                                   IsActive IsAdmin 2FA',
+      '1    tim                 tim@example.invalid                     true     true    false',
+      '7    forgejo-provision   forgejo-provision@noreply.example        true     false   false',
+      '',
+    ].join('\n');
+    expect(usernamesFrom(table)).toEqual(['tim', 'forgejo-provision']);
+  });
+
+  test('refuses a table it does not recognise rather than reporting nobody', () => {
+    expect(() => usernamesFrom('something else entirely')).toThrow(/unexpected header/);
+    expect(() => usernamesFrom('')).toThrow(/unexpected header/);
+  });
+});
+
+describe('readCreateOutput', () => {
+  const user = 'forgejo-provision';
+
+  test('captures the password and keeps it out of the lines it echoes', () => {
+    const stdout = [
+      "generated random password is 'aB3dE5gH7jK9'",
+      "New user 'forgejo-provision' has been successfully created!",
+      '',
+    ].join('\n');
+    const out = readCreateOutput(stdout, user);
+    expect(out.password).toBe('aB3dE5gH7jK9');
+    expect(out.created).toBe(true);
+    expect(out.rest.join('\n')).not.toContain('aB3dE5gH7jK9');
+  });
+
+  test('keeps a quote inside the password instead of truncating at it', () => {
+    const out = readCreateOutput("generated random password is 'ab'c\"d e'", user);
+    expect(out.password).toBe('ab\'c"d e');
+  });
+
+  test('reports not created when the success line names someone else or is missing', () => {
+    expect(readCreateOutput("New user 'tim' has been successfully created!", user).created).toBe(
+      false,
+    );
+    const noPassword = readCreateOutput(
+      "New user 'forgejo-provision' has been successfully created!",
+      user,
+    );
+    expect(noPassword.created).toBe(true);
+    expect(noPassword.password).toBeUndefined();
+  });
+});

package/src/openbao/forgejo-bootstrap-parse.ts

@@ -0,0 +1,90 @@
+/**
+ * Reading what the Forgejo CLI prints, for the forgejo-provision bootstrap (forgejo-bootstrap.ts).
+ *
+ * ★ PURE, SO THE ONE PART THAT TOUCHES THE PASSWORD IS TESTED WITHOUT ONE. Every format below was
+ *   read off the running 16.0.3 daemon or its source on 2026-09-14, not assumed.
+ */
+
+/** Where the mini's Forgejo keeps its state (hosts/macmini/modules/forgejo.nix:235, app.ini:14). */
+export const FORGEJO_WORK_PATH = '/opt/homeflare/forgejo';
+/** The file the launchd runner renders at every start (forgejo.nix:78). Readable by tim, who runs Forgejo. */
+export const FORGEJO_CONFIG = `${FORGEJO_WORK_PATH}/custom/conf/app.ini`;
+
+/**
+ * The binary of the RUNNING server, so the CLI writes the same schema as the daemon serving it.
+ *
+ * ★ MEASURED: `ps -axo command` shows
+ *   `/nix/store/<hash>-forgejo-16.0.3/bin/forgejo web --work-path /opt/homeflare/forgejo`. A
+ *   `forgejo` found on PATH could be a different version from the one holding the database.
+ */
+export const runningForgejoBinary = (psCommands: string): string | undefined => {
+  for (const line of psCommands.split('\n')) {
+    const [binary, subcommand] = line.trim().split(/\s+/);
+    if (
+      subcommand === 'web' &&
+      binary !== undefined &&
+      /^\/nix\/store\/[^/]+-forgejo-[\d.]+\/bin\/forgejo$/.test(binary)
+    ) {
+      return binary;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * Usernames from `forgejo admin user list`: a tabwriter table whose header is
+ * `ID Username Email IsActive IsAdmin 2FA` (measured, six columns).
+ *
+ * ⛔ AN UNEXPECTED HEADER THROWS. Parsing a changed table as "no such user" would let the bootstrap
+ *   create over an account it failed to see.
+ */
+export const usernamesFrom = (table: string): string[] => {
+  const rows = table
+    .split('\n')
+    .map((row) => row.trim())
+    .filter((row) => row !== '');
+  const header = rows[0]?.split(/\s+/) ?? [];
+  if (header[0] !== 'ID' || header[1] !== 'Username') {
+    throw new Error(
+      `forgejo admin user list printed an unexpected header: ${rows[0] ?? '(nothing)'}`,
+    );
+  }
+  return rows.slice(1).map((row) => row.split(/\s+/)[1] ?? '');
+};
+
+/** What `admin user create --random-password` printed on stdout. */
+export type CreateOutput = {
+  readonly created: boolean;
+  /** ⛔ Never logged, never returned past the one OpenBao write. */
+  readonly password: string | undefined;
+  /** Every other non-empty stdout line, safe to echo. */
+  readonly rest: readonly string[];
+};
+
+/**
+ * ★ THE TWO LINES, FROM forgejo v16.0 cmd/admin_user_create.go:
+ *     generated random password is '%s'
+ *     New user '%s' has been successfully created!
+ * ⚠️ THE PATTERN IS GREEDY TO THE LAST QUOTE ON PURPOSE. Forgejo's generator can draw a `'` when
+ *   PASSWORD_COMPLEXITY includes `spec`, and a lazy match would silently store a truncated password
+ *   that no mint could ever use. The generator never draws a newline, so one line is one password.
+ */
+export const readCreateOutput = (stdout: string, username: string): CreateOutput => {
+  let password: string | undefined;
+  let created = false;
+  const rest: string[] = [];
+  for (const line of stdout.split('\n')) {
+    const generated = /^generated random password is '(.*)'$/.exec(line);
+    if (generated !== null) {
+      password = generated[1];
+      continue;
+    }
+    if (line === `New user '${username}' has been successfully created!`) created = true;
+    if (line.trim() !== '') rest.push(line);
+  }
+  return { created, password, rest };
+};
+
+/** The last few lines of a CLI's stderr, for a failure message. Forgejo prints no secret there. */
+export const tailOf = (text: string, lines = 5): string =>
+  text.trim().split('\n').slice(-lines).join(' | ') || '(no output)';