@homeflare/alchemy 0.1.0

package/src/forgejo/team-member.ts

@@ -0,0 +1,97 @@
+/**
+ * `Forgejo.TeamMember` — one user in one organization team.
+ *
+ * ★ WHY IT EXISTS: forgejo-provision, the service account the Forgejo engine mints as, belongs to the
+ *   HomeFlare Owners team — Tim, 2026-09-14. Membership is what its tokens can reach; the role's
+ *   scopes only cap it (house/openbao/src/forgejo-bootstrap.ts).
+ *
+ * ★ READ OFF THE LIVE 16.0.3 SWAGGER (127.0.0.1:3000/swagger.v1.json, 2026-09-14): GET, PUT and
+ *   DELETE `/teams/{id}/members/{username}` answer 200, 204 and 204, and 404 when absent. The team
+ *   is addressed by numeric id, so it is found by name first — the same seam as org-team.ts.
+ *
+ * ⚠️ EXISTENCE IS THE WHOLE OBJECT. Nothing about a membership can be updated, so `matches` is
+ *   always true; a different team or user is a different resource id in alchemy.run.ts.
+ *
+ * ⚠️ THE TEAM ITSELF IS ONLY LOCATED HERE, NEVER MANAGED. A missing team fails the plan by name
+ *   instead of folding into "absent", because a PUT can add a member but cannot create a team.
+ *
+ * ⛔ TOKEN NEEDS `write:organization` TO ADD OR REMOVE, and an identity allowed to manage the team.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { ForgejoError, forgejo } from './client.ts';
+import { type ForgejoRequirements, forgejoHandlers } from './resource.ts';
+
+export interface TeamMemberProps {
+  org: string;
+  /** Team name as Forgejo shows it, e.g. `Owners`. */
+  team: string;
+  username: string;
+}
+
+export interface TeamMemberAttributes {
+  org: string;
+  team: string;
+  teamId: number;
+  username: string;
+}
+
+export interface ForgejoTeamMember extends Resource<
+  'Forgejo.TeamMember',
+  TeamMemberProps,
+  TeamMemberAttributes,
+  never,
+  ForgejoRequirements
+> {}
+
+export const ForgejoTeamMember = Resource<ForgejoTeamMember>('Forgejo.TeamMember');
+
+/** Where `locate` leaves the team id on the live row, for `attributes` and `wirePath`. */
+const TEAM_ID = '__team_id';
+
+const teamIdOf = (props: TeamMemberProps) =>
+  Effect.gen(function* () {
+    const path = `orgs/${props.org}/teams?limit=200`;
+    const rows = yield* forgejo<Record<string, unknown>[]>('GET', path);
+    const id = (Array.isArray(rows) ? rows : []).find((row) => row['name'] === props.team)?.['id'];
+    if (typeof id !== 'number') {
+      return yield* Effect.fail(
+        new ForgejoError(0, 'GET', path, `no team named ${props.team} in org ${props.org}`),
+      );
+    }
+    return id;
+  });
+
+const memberPath = (id: number, props: TeamMemberProps) =>
+  `teams/${String(id)}/members/${props.username}`;
+
+const handlers = forgejoHandlers<TeamMemberProps, TeamMemberAttributes>({
+  attributes: (live, props) => {
+    const id = live[TEAM_ID];
+    const login = live['login'];
+    if (typeof id !== 'number' || typeof login !== 'string') return undefined;
+    if (login.toLowerCase() !== props.username.toLowerCase()) return undefined;
+    return { org: props.org, team: props.team, teamId: id, username: props.username };
+  },
+  collection: (props) => `orgs/${props.org}/teams`,
+  createForm: () => ({}),
+  locate: (props) =>
+    Effect.gen(function* () {
+      const id = yield* teamIdOf(props);
+      const user = yield* forgejo<Record<string, unknown>>('GET', memberPath(id, props));
+      return user === undefined ? undefined : { ...user, [TEAM_ID]: id };
+    }),
+  matches: () => true,
+  path: (props) => `orgs/${props.org}/teams/${props.team}/members/${props.username}`,
+  upsert: (props, before) =>
+    before !== undefined
+      ? Effect.void
+      : Effect.flatMap(teamIdOf(props), (id) =>
+          Effect.asVoid(forgejo('PUT', memberPath(id, props))),
+        ),
+  wirePath: (props, live) => memberPath(Number(live[TEAM_ID]), props),
+});
+
+export const ForgejoTeamMemberProvider = () =>
+  Provider.effect(ForgejoTeamMember, Effect.succeed(ForgejoTeamMember.Provider.of(handlers)));

package/src/forgejo/values.test.ts

@@ -0,0 +1,48 @@
+/**
+ * Wire coercions for Forgejo resources — each case is a trap values.ts documents.
+ *
+ * ⚠️ `@homeflare/forgejo` had no tests; `bun test` exited 1 on "No tests found" and blocked verify.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  hookConfigPublic,
+  orgSecretEnvKey,
+  recordEqual,
+  stringArray,
+  stringRecord,
+} from './values.ts';
+
+describe('stringArray', () => {
+  it('sorts for stable comparison', () => {
+    assert.deepEqual(stringArray(['push', 'create']), ['create', 'push']);
+  });
+});
+
+describe('recordEqual', () => {
+  it('ignores key order', () => {
+    assert.equal(recordEqual({ a: '1', b: '2' }, { b: '2', a: '1' }), true);
+    assert.equal(recordEqual({ a: '1' }, { a: '2' }), false);
+  });
+});
+
+describe('hookConfigPublic', () => {
+  it('drops secret from config', () => {
+    assert.deepEqual(hookConfigPublic({ secret: 'x', url: 'https://example.test' }), {
+      url: 'https://example.test',
+    });
+  });
+});
+
+describe('orgSecretEnvKey', () => {
+  it('normalizes org and name into an env key', () => {
+    assert.equal(orgSecretEnvKey('homeflare', 'ci-token'), 'FORGEJO_ORG_SECRET_HOMEFLARE_CI_TOKEN');
+  });
+});
+
+describe('stringRecord', () => {
+  it('returns empty for non-objects', () => {
+    assert.deepEqual(stringRecord(null), {});
+    assert.deepEqual(stringRecord(['x']), {});
+  });
+});

package/src/forgejo/values.ts

@@ -0,0 +1,61 @@
+/**
+ * Wire coercions shared across Forgejo resources.
+ *
+ * ★ GITEA/ FORGEJO JSON USES snake_case ON THE WIRE and camelCase in props — each resource
+ *   translates at the form boundary; these helpers only normalise values for comparison.
+ */
+
+export const text = (value: unknown, fallback = '') =>
+  typeof value === 'string' ? value : fallback;
+
+/** Forgejo returns label colours without `#`; declarations may include it. */
+export const color = (value: unknown) => text(value).replace(/^#/, '').toLowerCase();
+
+export const bool = (value: unknown, fallback = false) =>
+  value === undefined || value === null ? fallback : value === true || value === 1 || value === '1';
+
+export const int = (value: unknown, fallback = 0) => {
+  if (typeof value === 'number' && Number.isFinite(value)) return Math.trunc(value);
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number.parseInt(value, 10);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return fallback;
+};
+
+/** Wire arrays compared in sorted order — Gitea reshuffles nothing but callers should not depend on order. */
+export const stringArray = (value: unknown) =>
+  Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === 'string').toSorted()
+    : [];
+
+export const stringRecord = (value: unknown): Record<string, string> => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return {};
+  const out: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (typeof entry === 'string') out[key] = entry;
+  }
+  return out;
+};
+
+export const recordEqual = (left: Record<string, string>, right: Record<string, string>) => {
+  const leftKeys = Object.keys(left).toSorted();
+  const rightKeys = Object.keys(right).toSorted();
+  if (leftKeys.length !== rightKeys.length) return false;
+  return leftKeys.every((key, index) => rightKeys[index] === key && left[key] === right[key]);
+};
+
+/** Hook `config` without `secret` — the value must never land in Alchemy attributes. */
+export const hookConfigPublic = (value: unknown) => {
+  const config = stringRecord(value);
+  const { secret: _secret, ...rest } = config;
+  return rest;
+};
+
+/** Env key for a write-only org actions secret — value read at PUT time only, never stored. */
+export const orgSecretEnvKey = (org: string, name: string) =>
+  `FORGEJO_ORG_SECRET_${org}_${name}`.replace(/[^A-Za-z0-9_]/g, '_').toUpperCase();
+
+/** Env key for a write-only repo webhook HMAC secret — omitted from attributes and props. */
+export const hookSecretEnvKey = (owner: string, repo: string, name: string) =>
+  `FORGEJO_HOOK_SECRET_${owner}_${repo}_${name}`.replace(/[^A-Za-z0-9_]/g, '_').toUpperCase();

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @homeflare/alchemy — custom Alchemy providers for systems the vendor has none for.
+ *
+ * ⛔ IMPORT A SUBPATH, NOT THIS FILE. Each system carries its own peers and its own
+ *   client; a root barrel would pull Proxmox into a stack that only wanted Forgejo.
+ *
+ *     import { R2BucketLock } from '@homeflare/alchemy/cloudflare';
+ *     import { BranchProtection } from '@homeflare/alchemy/forgejo';
+ *     import { BaoMount } from '@homeflare/alchemy/openbao';
+ *     import { TalosCluster } from '@homeflare/alchemy/talos';
+ *     import { ProxmoxAcl } from '@homeflare/alchemy/proxmox';
+ *
+ * ★ WHY THESE EXIST AT ALL. When Alchemy has no resource for something, the alternative
+ *   is a runbook step a human runs once — and a plan can never show a missing runbook
+ *   step. A custom provider makes the drift visible in `plan` like everything else.
+ */
+
+export {};

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

@@ -0,0 +1,112 @@
+import { sha256 } from './digest.ts';
+import { parseDuration, ttlSeconds } from './mount-form.ts';
+
+export interface BaoAuthRoleProps {
+  /** AppRole name, as `auth/approle/role/{name}` takes it. */
+  name: string;
+  /** Policies bound to tokens minted through this role. Names only — never a secret. */
+  tokenPolicies: readonly string[];
+  /** Token TTL, e.g. `15m`. */
+  tokenTtl: string;
+  /** Token max TTL, e.g. `1h`. */
+  tokenMaxTtl: string;
+  /** Secret ID TTL — `0` means non-expiring, as reconcile.sh and apply-consumers.py set. */
+  secretIdTtl: string;
+  /** Whether login requires a secret_id. Defaults to true when omitted on write. */
+  bindSecretId?: boolean;
+  /** `0` means unlimited uses — the shape reconcile.sh writes for headless roles. */
+  secretIdNumUses?: number;
+}
+
+export interface BaoAuthRoleAttributes {
+  name: string;
+  tokenPolicies: readonly string[];
+  tokenTtl: string;
+  tokenMaxTtl: string;
+  secretIdTtl: string;
+  bindSecretId: boolean;
+  secretIdNumUses: number;
+  /** SHA-256 of the managed fields — safe to persist; see policy.ts. */
+  digest: string;
+}
+
+const policiesOf = (live: Record<string, unknown>): readonly string[] => {
+  const raw = live['token_policies'];
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .filter((entry): entry is string => typeof entry === 'string')
+    .slice()
+    .sort();
+};
+
+const bool = (value: unknown, fallback: boolean) => (typeof value === 'boolean' ? value : fallback);
+
+const int = (value: unknown, fallback: number) =>
+  typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+
+const ttlText = (seconds: number | undefined, fallback = '') => {
+  if (seconds === undefined) return fallback;
+  if (seconds % 86400 === 0) return `${String(seconds / 86400)}d`;
+  if (seconds % 3600 === 0) return `${String(seconds / 3600)}h`;
+  if (seconds % 60 === 0) return `${String(seconds / 60)}m`;
+  return `${String(seconds)}s`;
+};
+
+export const attributesOf = (
+  props: BaoAuthRoleProps,
+  live: Record<string, unknown>,
+): BaoAuthRoleAttributes => {
+  const attrs = {
+    name: props.name,
+    tokenPolicies: policiesOf(live),
+    tokenTtl: ttlText(ttlSeconds(live['token_ttl'])),
+    tokenMaxTtl: ttlText(ttlSeconds(live['token_max_ttl'])),
+    secretIdTtl: ttlText(ttlSeconds(live['secret_id_ttl']), '0'),
+    bindSecretId: bool(live['bind_secret_id'], true),
+    secretIdNumUses: int(live['secret_id_num_uses'], 0),
+  };
+  return { ...attrs, digest: sha256(JSON.stringify(attrs)) };
+};
+
+export const readPath = (name: string) => `auth/approle/role/${name}`;
+
+/**
+ * The body for `PUT auth/approle/role/<name>`.
+ *
+ * ★ ALL STRINGS, EXACTLY THE `k=v` PAIRS `bao write` USED TO SEND — see `baoWrite` in bao-http.ts.
+ */
+export const writeBody = (props: BaoAuthRoleProps): Record<string, string> => {
+  const body: Record<string, string> = {
+    token_policies: props.tokenPolicies.join(','),
+    token_ttl: props.tokenTtl,
+    token_max_ttl: props.tokenMaxTtl,
+    secret_id_ttl: props.secretIdTtl,
+  };
+  if (props.bindSecretId !== undefined) body['bind_secret_id'] = String(props.bindSecretId);
+  if (props.secretIdNumUses !== undefined) {
+    body['secret_id_num_uses'] = String(props.secretIdNumUses);
+  }
+  return body;
+};
+
+const samePolicies = (want: readonly string[], have: readonly string[]) =>
+  want.length === have.length && want.every((policy, index) => policy === have[index]);
+
+const sameTtl = (want: string, have: string) => {
+  const wantSeconds = parseDuration(want);
+  const haveSeconds = ttlSeconds(have);
+  return wantSeconds !== undefined && wantSeconds === haveSeconds;
+};
+
+/** True when live already matches the declaration on every managed field. */
+export const matches = (attributes: BaoAuthRoleAttributes, props: BaoAuthRoleProps) => {
+  const wantPolicies = props.tokenPolicies.slice().sort();
+  return (
+    samePolicies(wantPolicies, attributes.tokenPolicies) &&
+    sameTtl(props.tokenTtl, attributes.tokenTtl) &&
+    sameTtl(props.tokenMaxTtl, attributes.tokenMaxTtl) &&
+    sameTtl(props.secretIdTtl, attributes.secretIdTtl) &&
+    (props.bindSecretId === undefined || attributes.bindSecretId === props.bindSecretId) &&
+    (props.secretIdNumUses === undefined || attributes.secretIdNumUses === props.secretIdNumUses)
+  );
+};

package/src/openbao/auth-role.ts

@@ -0,0 +1,101 @@
+/**
+ * An OpenBao AppRole auth role — token_policies, TTLs and bind flags. METADATA ONLY.
+ *
+ * ⛔ NO SECRET IN PROPS OR ATTRIBUTES — see policy.ts for why. `role_id` and `secret_id`
+ *   are credential issuance, not configuration, and are OUT OF SCOPE. This declares the
+ *   role shape an approle login inherits — policy names and TTL strings only.
+ *
+ * ★ `defaultRemovalPolicy: 'retain'` — deleting a role revokes every token bound to it.
+ *   Opt in with `.pipe(RemovalPolicy.destroy())`; see resource.ts in house/proxmox.
+ */
+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 {
+  type BaoAuthRoleAttributes,
+  type BaoAuthRoleProps,
+  attributesOf,
+  matches,
+  readPath,
+  writeBody,
+} from './auth-role-form.ts';
+import { baoDelete, baoRead, baoWrite } from './bao-http.ts';
+
+export type { BaoAuthRoleAttributes, BaoAuthRoleProps };
+
+export interface BaoAuthRole extends Resource<
+  'Bao.AuthRole',
+  BaoAuthRoleProps,
+  BaoAuthRoleAttributes,
+  never,
+  HttpClient.HttpClient
+> {}
+
+export const BaoAuthRole = Resource<BaoAuthRole>('Bao.AuthRole', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const readRole = (props: BaoAuthRoleProps) =>
+  Effect.gen(function* () {
+    const live = yield* baoRead(readPath(props.name));
+    if (live === undefined) return undefined;
+    return attributesOf(props, live);
+  });
+
+export const BaoAuthRoleProvider = () =>
+  Provider.effect(
+    BaoAuthRole,
+    Effect.succeed(
+      BaoAuthRole.Provider.of({
+        /**
+         * ⛔ `bao list auth/approle/role` IS NOT A LIST OF THINGS THIS OWNS. Every role
+         *   in the namespace answers, including break-glass and bootstrap ones. Returning
+         *   them would invite Alchemy to adopt — and then delete — roles it never created.
+         */
+        list: () => Effect.succeed([]),
+
+        read: Effect.fn(function* ({ olds }) {
+          return yield* readRole(olds);
+        }),
+
+        /**
+         * ⛔ IT COMPARES THE LIVE ROLE, NOT THE STORED DIGEST. A role edited in the OpenBao
+         *   UI is exactly the drift the check-* gates exist to catch.
+         */
+        diff: Effect.fn(function* ({ news, output }) {
+          if (output === undefined || !isResolved(news)) return undefined;
+          const live = yield* readRole(news);
+          if (live === undefined) return { action: 'update' } as const;
+          if (matches(live, news)) return { action: 'noop' } as const;
+          return { action: 'update' } as const;
+        }),
+
+        reconcile: Effect.fn(function* ({ news }) {
+          const live = yield* readRole(news);
+          if (live === undefined || !matches(live, news)) {
+            yield* baoWrite('PUT', readPath(news.name), writeBody(news));
+          }
+          const after = yield* readRole(news);
+          if (after === undefined) {
+            return yield* Effect.die(
+              new Error(
+                `Bao.AuthRole ${news.name}: write returned no error but the role is still absent.`,
+              ),
+            );
+          }
+          return after;
+        }),
+
+        /**
+         * ⛔ DELETING A ROLE REVOKES EVERY TOKEN BOUND TO IT. Idempotent as Alchemy requires
+         *   — already gone is success — but retain is the default for a reason.
+         */
+        delete: Effect.fn(function* ({ output }) {
+          yield* baoDelete(readPath(output.name));
+          return undefined;
+        }),
+      }),
+    ),
+  );

package/src/openbao/bao-address.test.ts

@@ -0,0 +1,89 @@
+/**
+ * The environment contract, pinned to what openbao v2.6.2's CLI client does — see the citations in
+ * bao-address.ts. Pure: nothing here opens a connection.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { DEFAULT_ADDRESS, headersFor, resolveAddress } from './bao-address.ts';
+
+const TOKEN = 'hvs.FAKE-sentinel-never-a-real-token';
+
+describe('resolveAddress', () => {
+  it("falls back to the CLI's default address when nothing is set", () => {
+    assert.deepEqual(resolveAddress({}), {
+      base: DEFAULT_ADDRESS,
+      namespace: undefined,
+      socket: undefined,
+    });
+  });
+
+  it('strips a trailing slash and keeps a path prefix', () => {
+    assert.equal(
+      resolveAddress({ BAO_ADDR: 'https://bao.example:8200/' }).base,
+      'https://bao.example:8200',
+    );
+    assert.equal(
+      resolveAddress({ BAO_ADDR: 'https://edge.example/bao/' }).base,
+      'https://edge.example/bao',
+    );
+  });
+
+  it('lets BAO_AGENT_ADDR win over BAO_ADDR', () => {
+    const env = {
+      BAO_ADDR: 'https://server.example:8200',
+      BAO_AGENT_ADDR: 'http://127.0.0.1:8100',
+    };
+    assert.equal(resolveAddress(env).base, 'http://127.0.0.1:8100');
+  });
+
+  it('falls back to VAULT_ADDR, but a present-and-empty BAO_ADDR still wins', () => {
+    assert.equal(
+      resolveAddress({ VAULT_ADDR: 'https://vault.example' }).base,
+      'https://vault.example',
+    );
+    assert.equal(
+      resolveAddress({ BAO_ADDR: '', VAULT_ADDR: 'https://vault.example' }).base,
+      DEFAULT_ADDRESS,
+    );
+  });
+
+  it('turns unix:///path into plain HTTP to localhost over that socket', () => {
+    assert.deepEqual(resolveAddress({ BAO_ADDR: 'unix:///run/openbao/agent.sock' }), {
+      base: 'http://localhost',
+      namespace: undefined,
+      socket: '/run/openbao/agent.sock',
+    });
+  });
+
+  it('carries a namespace only when it is non-empty', () => {
+    assert.equal(resolveAddress({ BAO_NAMESPACE: 'homeflare' }).namespace, 'homeflare');
+    assert.equal(resolveAddress({ BAO_NAMESPACE: '' }).namespace, undefined);
+  });
+});
+
+describe('headersFor', () => {
+  it('sends the token and the namespace when both are set', () => {
+    const env = { BAO_NAMESPACE: 'homeflare', BAO_TOKEN: TOKEN };
+    assert.deepEqual(headersFor(resolveAddress(env), env), {
+      'X-Vault-Namespace': 'homeflare',
+      'X-Vault-Request': 'true',
+      'X-Vault-Token': TOKEN,
+    });
+  });
+
+  // ★ AGENT MODE. The agent substitutes its auto-auth token only when the request carries none.
+  it('sends NO token header when BAO_TOKEN is unset or empty', () => {
+    for (const env of [{}, { BAO_TOKEN: '' }]) {
+      assert.deepEqual(headersFor(resolveAddress(env), env), { 'X-Vault-Request': 'true' });
+    }
+  });
+
+  it('falls back to VAULT_TOKEN, as the CLI does', () => {
+    const env = { VAULT_TOKEN: TOKEN };
+    assert.equal(headersFor(resolveAddress(env), env)['X-Vault-Token'], TOKEN);
+  });
+
+  it('keeps the token out of the resolved address', () => {
+    assert.ok(!JSON.stringify(resolveAddress({ BAO_TOKEN: TOKEN })).includes(TOKEN));
+  });
+});

package/src/openbao/bao-address.ts

@@ -0,0 +1,97 @@
+/**
+ * Where an OpenBao call goes and which headers it carries — resolved from the environment the way
+ * the `bao` CLI resolves it, so the provider and `bao kv get` can never disagree about which server
+ * or namespace this machine is talking to.
+ *
+ * ★ READ FROM openbao v2.6.2, NOT RECALLED:
+ *   · api/client.go:34-66 — BAO_ADDR, BAO_AGENT_ADDR, BAO_NAMESPACE, BAO_TOKEN, and the header
+ *     names `X-Vault-Namespace` and `X-Vault-Token`.
+ *   · api/client.go:370 — the default address, `https://127.0.0.1:8200`.
+ *   · api/client.go:503-507, 617-618, 761-762 — BAO_AGENT_ADDR, when set, WINS over BAO_ADDR.
+ *   · api/env.go:22-34 — every BAO_* falls back to its VAULT_* twin, but a BAO_* that is present
+ *     and EMPTY still wins over the VAULT_* one.
+ *   · api/client.go:776-785 — the token and namespace are applied only when non-empty, and every
+ *     request carries `X-Vault-Request: true`.
+ *   · api/client.go:1349-1354 — the request path is joined onto the address's own path.
+ *
+ * ⛔ WHAT THE CLI DOES AND THIS DELIBERATELY DOES NOT: with BAO_TOKEN unset, `bao` falls back to its
+ *   token helper (a token file in $HOME). This never reads that file. No BAO_TOKEN means AGENT
+ *   MODE — see `headersFor`.
+ * ⚠️ NOT CARRIED OVER: BAO_CACERT / BAO_SKIP_VERIFY / client certificates, SRV lookup, and the CLI's
+ *   retries on 5xx. An https address needs a certificate the runtime already trusts; a TLS failure
+ *   fails the call loudly rather than being skipped.
+ */
+
+export type BaoEnvironment = Readonly<Record<string, string | undefined>>;
+
+export type BaoAddress = {
+  /** Scheme, host and any path prefix, no trailing slash. `http://localhost` for a socket. */
+  readonly base: string;
+  /** The socket path when the address is `unix:///path`, otherwise undefined. */
+  readonly socket: string | undefined;
+  /** The namespace to send, when there is one. */
+  readonly namespace: string | undefined;
+};
+
+export const DEFAULT_ADDRESS = 'https://127.0.0.1:8200';
+
+const UNIX = 'unix://';
+
+/** api/env.go ReadBaoVariable: present (even empty) BAO_* wins, else the VAULT_* twin. */
+export const readBaoVariable = (env: BaoEnvironment, name: `BAO_${string}`): string =>
+  env[name] ?? env[`VAULT_${name.slice('BAO_'.length)}`] ?? '';
+
+/**
+ * The address and namespace for this environment. Carries no token, so it is safe to log.
+ *
+ * ★ UNIX SOCKETS, BECAUSE AN AGENT LISTENER CAN BE ONE. OpenBao Agent's `listener "unix"` serves
+ *   the same API on a socket (website/content/docs/agent-and-proxy/agent/index.mdx:382-384), and the
+ *   agent advertises such a listener as `unix://<path>` (command/agent.go:565-566). The CLI handles
+ *   that address by dialling the socket and speaking plain HTTP to host `localhost`
+ *   (api/client.go:654-667); `base` and `socket` are exactly those two halves.
+ */
+export const resolveAddress = (env: BaoEnvironment): BaoAddress => {
+  const agent = readBaoVariable(env, 'BAO_AGENT_ADDR');
+  const direct = readBaoVariable(env, 'BAO_ADDR');
+  const raw = agent !== '' ? agent : direct !== '' ? direct : DEFAULT_ADDRESS;
+  const namespace = readBaoVariable(env, 'BAO_NAMESPACE');
+  const socket = raw.startsWith(UNIX) ? raw.slice(UNIX.length) : undefined;
+  return {
+    base: socket === undefined ? raw.replace(/\/+$/, '') : 'http://localhost',
+    namespace: namespace === '' ? undefined : namespace,
+    socket,
+  };
+};
+
+/**
+ * The headers one call sends.
+ *
+ * ★ AGENT MODE IS "NO TOKEN HEADER AT ALL", AND THAT IS THE AGENT'S OWN CONTRACT. Read in openbao
+ *   v2.6.2 command/agentproxyshared/cache/handler.go:29-38: the proxy handler takes the request's
+ *   `X-Vault-Token`, and only when it is EMPTY and an auto-auth sink exists does it substitute the
+ *   agent's own token. command/agent.go:517-541 creates that sink exactly when
+ *   `api_proxy { use_auto_auth_token = true }` is set; command/agent/config/config.go:288-292 and
+ *   635-637 map the older `cache { use_auto_auth_token }` onto the same setting; and
+ *   command/proxy.go:495-518 wires OpenBao Proxy identically. The docs say the same in words
+ *   (website/content/docs/agent-and-proxy/agent/apiproxy.mdx:57-62): a request without a token is
+ *   forwarded with the auto-auth token, a request that bears one keeps its own, and `"force"`
+ *   overwrites it.
+ *   ⛔ SO AN EMPTY `X-Vault-Token: ` WOULD BE WRONG IN BOTH DIRECTIONS: harmless to the agent,
+ *     which reads empty as absent, but an explicit unauthenticated request to a server. The header
+ *     is omitted, never blanked.
+ * ★ THE NAMESPACE RIDES THROUGH THE AGENT UNTOUCHED. The proxy clones its client and replaces that
+ *   client's headers with the incoming request's (cache/api_proxy.go:50-54 and :78), so the
+ *   `X-Vault-Namespace` sent here is the one OpenBao sees.
+ * ⚠️ `X-Vault-Request: true` IS NOT DECORATION. An agent listener with `require_request_header`
+ *   refuses any request without it (command/agent.go:544-548); the CLI always sends it.
+ *
+ * ⛔ THE RETURN VALUE HOLDS THE TOKEN. Hand it to the request and nowhere else: never to an error,
+ *   a log line, an attribute, or a span — bao-http.ts adds the header to the redacted names.
+ */
+export const headersFor = (address: BaoAddress, env: BaoEnvironment): Record<string, string> => {
+  const headers: Record<string, string> = { 'X-Vault-Request': 'true' };
+  if (address.namespace !== undefined) headers['X-Vault-Namespace'] = address.namespace;
+  const token = readBaoVariable(env, 'BAO_TOKEN');
+  if (token !== '') headers['X-Vault-Token'] = token;
+  return headers;
+};