@homeflare/alchemy 0.5.0 → 0.6.0

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

@@ -0,0 +1,161 @@
+/**
+ * The `token_*` fields every auth role shares — read once here for Bao.JwtRole and
+ * Bao.KubernetesRole, so the two cannot disagree about what a token TTL is.
+ *
+ * ★ READ FROM openbao v2.6.2 sdk/helper/tokenutil/tokenutil.go:
+ *   · TokenFields (:80-170) — `token_policies`, `token_bound_cidrs` are comma-string slices;
+ *     `token_ttl`, `token_max_ttl`, `token_explicit_max_ttl`, `token_period` are duration-seconds;
+ *     `token_no_default_policy` bool; `token_num_uses` int; `token_type` a string.
+ *   · ParseTokenFields (:176-262) — EVERY field is `GetOk`: an omitted field KEEPS its stored value.
+ *     So an update is a merge, and the only way to clear a stale value is to send the default.
+ *     That is why every field below is sent on every write, resolved to its default.
+ *   · PopulateTokenData (:265-284) — the read answers seconds for durations, `[]` for empty lists,
+ *     and `token_type` as a word (sdk/logical/token.go: `default`, `service`, `batch`).
+ * ⛔ NO SECRET HERE: policy names, CIDRs, TTLs.
+ */
+import { parseDuration, ttlSeconds } from './mount-form.ts';
+
+export type BaoTokenType = 'batch' | 'default' | 'service';
+
+export interface BaoTokenProps {
+  /** Policies on tokens this role issues. Names only. */
+  tokenPolicies: readonly string[];
+  /** Token TTL (`15m`). Default `0` — the mount's default. */
+  tokenTtl?: string;
+  /** Token max TTL (`1h`). Default `0` — the mount's max. */
+  tokenMaxTtl?: string;
+  /** Hard ceiling that renewal cannot pass. Default `0` (none). */
+  tokenExplicitMaxTtl?: string;
+  /** Periodic tokens renew forever within this period. Default `0` (not periodic). */
+  tokenPeriod?: string;
+  /** Leave the `default` policy off. Default false. */
+  tokenNoDefaultPolicy?: boolean;
+  /** CIDRs a token may be USED from. Default none. */
+  tokenBoundCidrs?: readonly string[];
+  /** Uses before the token dies; `0` is unlimited. Default 0. */
+  tokenNumUses?: number;
+  /** Default `default` — the mount decides, which means service tokens unless it says otherwise. */
+  tokenType?: BaoTokenType;
+}
+
+/** The token fields as seconds and sorted sets — both sides of a diff are built by `tokenForm`. */
+export interface BaoTokenForm {
+  tokenBoundCidrs: readonly string[];
+  tokenExplicitMaxTtlSeconds: number;
+  tokenMaxTtlSeconds: number;
+  tokenNoDefaultPolicy: boolean;
+  tokenNumUses: number;
+  tokenPeriodSeconds: number;
+  tokenPolicies: readonly string[];
+  tokenTtlSeconds: number;
+  tokenType: string;
+}
+
+const sortedSet = (values: readonly string[]) => [...new Set(values)].sort();
+
+/**
+ * ⚠️ A HOST CIDR READS BACK BARE. token_bound_cidrs is stored as sockaddr values, and a `/32` (or
+ *   `/128`) host address renders without its mask. REASONED from go-sockaddr's String(), not
+ *   measured — so the mask is dropped on BOTH sides, which can only hide a spelling difference.
+ */
+const cidr = (value: string) => value.trim().replace(/\/(32|128)$/, '');
+
+const strings = (value: unknown): readonly string[] =>
+  Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
+
+const seconds = (text: string | undefined) => parseDuration(text ?? '0') ?? -1;
+
+/**
+ * The token fields of an already-normalised form, in one fixed key order — what a role family's own
+ * canonical literal spreads, so its digest cannot depend on how the object was assembled.
+ */
+export const tokenFields = (input: BaoTokenForm): BaoTokenForm => ({
+  tokenBoundCidrs: input.tokenBoundCidrs,
+  tokenExplicitMaxTtlSeconds: input.tokenExplicitMaxTtlSeconds,
+  tokenMaxTtlSeconds: input.tokenMaxTtlSeconds,
+  tokenNoDefaultPolicy: input.tokenNoDefaultPolicy,
+  tokenNumUses: input.tokenNumUses,
+  tokenPeriodSeconds: input.tokenPeriodSeconds,
+  tokenPolicies: input.tokenPolicies,
+  tokenTtlSeconds: input.tokenTtlSeconds,
+  tokenType: input.tokenType,
+});
+
+/** The key order is fixed here, once, for both sides. */
+const tokenForm = (input: BaoTokenForm): BaoTokenForm => ({
+  tokenBoundCidrs: sortedSet(input.tokenBoundCidrs.map(cidr)),
+  tokenExplicitMaxTtlSeconds: input.tokenExplicitMaxTtlSeconds,
+  tokenMaxTtlSeconds: input.tokenMaxTtlSeconds,
+  tokenNoDefaultPolicy: input.tokenNoDefaultPolicy,
+  tokenNumUses: input.tokenNumUses,
+  tokenPeriodSeconds: input.tokenPeriodSeconds,
+  tokenPolicies: sortedSet(input.tokenPolicies),
+  tokenTtlSeconds: input.tokenTtlSeconds,
+  tokenType: input.tokenType,
+});
+
+export const tokenFormOfProps = (props: BaoTokenProps): BaoTokenForm =>
+  tokenForm({
+    tokenBoundCidrs: props.tokenBoundCidrs ?? [],
+    tokenExplicitMaxTtlSeconds: seconds(props.tokenExplicitMaxTtl),
+    tokenMaxTtlSeconds: seconds(props.tokenMaxTtl),
+    tokenNoDefaultPolicy: props.tokenNoDefaultPolicy ?? false,
+    tokenNumUses: props.tokenNumUses ?? 0,
+    tokenPeriodSeconds: seconds(props.tokenPeriod),
+    tokenPolicies: props.tokenPolicies,
+    tokenTtlSeconds: seconds(props.tokenTtl),
+    tokenType: props.tokenType ?? 'default',
+  });
+
+export const tokenFormOfLive = (live: Record<string, unknown>): BaoTokenForm =>
+  tokenForm({
+    tokenBoundCidrs: strings(live['token_bound_cidrs']),
+    tokenExplicitMaxTtlSeconds: ttlSeconds(live['token_explicit_max_ttl']) ?? -1,
+    tokenMaxTtlSeconds: ttlSeconds(live['token_max_ttl']) ?? -1,
+    tokenNoDefaultPolicy: live['token_no_default_policy'] === true,
+    tokenNumUses: typeof live['token_num_uses'] === 'number' ? live['token_num_uses'] : -1,
+    tokenPeriodSeconds: ttlSeconds(live['token_period']) ?? -1,
+    tokenPolicies: strings(live['token_policies']),
+    tokenTtlSeconds: ttlSeconds(live['token_ttl']) ?? -1,
+    tokenType: typeof live['token_type'] === 'string' ? live['token_type'] : '',
+  });
+
+/**
+ * The token half of a role write — every field, defaults included (the merge ⚠️ above). Durations
+ * go over as the author's own strings; lists as JSON arrays, which a comma-string-slice accepts.
+ */
+export const tokenBody = (props: BaoTokenProps): Record<string, unknown> => ({
+  token_bound_cidrs: [...(props.tokenBoundCidrs ?? [])],
+  token_explicit_max_ttl: props.tokenExplicitMaxTtl ?? '0',
+  token_max_ttl: props.tokenMaxTtl ?? '0',
+  token_no_default_policy: props.tokenNoDefaultPolicy ?? false,
+  token_num_uses: props.tokenNumUses ?? 0,
+  token_period: props.tokenPeriod ?? '0',
+  token_policies: [...props.tokenPolicies],
+  token_ttl: props.tokenTtl ?? '0',
+  token_type: props.tokenType ?? 'default',
+});
+
+/** Refusals the token half can know without a server. */
+export const tokenProblems = (props: BaoTokenProps): readonly string[] => {
+  const found: string[] = [];
+  const durations = {
+    tokenExplicitMaxTtl: props.tokenExplicitMaxTtl,
+    tokenMaxTtl: props.tokenMaxTtl,
+    tokenPeriod: props.tokenPeriod,
+    tokenTtl: props.tokenTtl,
+  };
+  for (const [field, text] of Object.entries(durations)) {
+    if (seconds(text) < 0) found.push(`${field}=${text ?? ''} is not a duration (0 or <n>s|m|h|d)`);
+  }
+  const ttl = seconds(props.tokenTtl);
+  const max = seconds(props.tokenMaxTtl);
+  if (ttl > 0 && max > 0 && ttl > max) found.push('tokenTtl is longer than tokenMaxTtl');
+  if (
+    props.tokenType === 'batch' &&
+    (seconds(props.tokenPeriod) > 0 || (props.tokenNumUses ?? 0) > 0)
+  ) {
+    found.push('a batch token cannot be periodic or use-limited (tokenutil.go:234-241)');
+  }
+  return found;
+};

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

@@ -0,0 +1,131 @@
+/**
+ * assertBaoIdentity against a fake. The parts worth pinning: health goes out with NO token and NO
+ * namespace header (root-only API), a mismatch refuses before anything else is asked, and a
+ * missing namespace is a refusal rather than a quiet fall-through to root.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  BaoIdentityError,
+  HEALTH_PATH,
+  NAMESPACE_PROBE_PATH,
+  assertBaoIdentity,
+  assertBaoIdentityEffect,
+} from './bao-identity.ts';
+import { type Reply, type Seen, run, runFailure, withFake } from './fake-bao.ts';
+
+const HEALTHY = {
+  cluster_id: '00000000-0000-4000-8000-000000000001',
+  cluster_name: 'vault-example',
+  initialized: true,
+  sealed: false,
+  standby: false,
+  version: '2.6.2',
+};
+
+const routes =
+  (health: Reply, probe: Reply = { json: { data: { auth: {}, secret: {} } }, status: 200 }) =>
+  (seen: Seen) =>
+    seen.path.startsWith('/v1/sys/health') ? health : probe;
+
+const EXPECT = { clusterName: 'vault-example', namespace: 'team-a' };
+const envOf = (address: string) => ({
+  BAO_ADDR: address,
+  BAO_NAMESPACE: 'team-a',
+  BAO_TOKEN: 'placeholder-token',
+});
+
+const failureOf = async (promise: Promise<unknown>) => {
+  const error = await promise;
+  assert.ok(error instanceof BaoIdentityError);
+  assert.match(error.message, /^REFUSING: /);
+  return error;
+};
+
+describe('assertBaoIdentity', () => {
+  it('passes a matching vault, sending no token anywhere and no namespace to health', async () => {
+    await withFake(routes({ json: HEALTHY, status: 200 }), async (bao) => {
+      const identity = await run(envOf(bao.address), assertBaoIdentityEffect(EXPECT));
+      assert.equal(identity.clusterName, 'vault-example');
+      assert.equal(identity.namespace, 'team-a');
+      assert.equal(identity.version, '2.6.2');
+      const [health, probe] = bao.seen;
+      assert.equal(health?.path, `/v1/${HEALTH_PATH}`);
+      assert.equal(health?.headers.get('x-vault-namespace'), null);
+      assert.equal(probe?.path, `/v1/${NAMESPACE_PROBE_PATH}`);
+      assert.equal(probe?.headers.get('x-vault-namespace'), 'team-a');
+      for (const seen of bao.seen) assert.equal(seen.headers.get('x-vault-token'), null);
+    });
+  });
+
+  it('refuses the wrong cluster and asks nothing more', async () => {
+    const other = { ...HEALTHY, cluster_name: 'vault-other' };
+    await withFake(routes({ json: other, status: 200 }), async (bao) => {
+      const error = await failureOf(
+        runFailure(envOf(bao.address), assertBaoIdentityEffect(EXPECT)),
+      );
+      assert.equal(error.reason, 'mismatch');
+      assert.match(error.message, /vault-other/);
+      assert.equal(bao.seen.length, 1);
+    });
+  });
+
+  it('refuses a sealed vault as unconfirmed, because sealed hides cluster_name', async () => {
+    const sealed = { initialized: true, sealed: true, standby: true, version: '2.6.2' };
+    await withFake(routes({ json: sealed, status: 200 }), async (bao) => {
+      const error = await failureOf(
+        runFailure(envOf(bao.address), assertBaoIdentityEffect(EXPECT)),
+      );
+      assert.equal(error.reason, 'unconfirmed');
+    });
+  });
+
+  it('refuses a BAO_NAMESPACE that is not the expected one without calling out', async () => {
+    await withFake(routes({ json: HEALTHY, status: 200 }), async (bao) => {
+      const env = { ...envOf(bao.address), BAO_NAMESPACE: '' };
+      const error = await failureOf(runFailure(env, assertBaoIdentityEffect(EXPECT)));
+      assert.equal(error.reason, 'mismatch');
+      assert.match(error.message, /`root`/);
+      assert.equal(bao.seen.length, 0);
+    });
+  });
+
+  it('refuses when the namespace does not exist on that cluster', async () => {
+    const missing = { json: { errors: ['namespace not found'] }, status: 404 };
+    await withFake(routes({ json: HEALTHY, status: 200 }, missing), async (bao) => {
+      const error = await failureOf(
+        runFailure(envOf(bao.address), assertBaoIdentityEffect(EXPECT)),
+      );
+      assert.equal(error.reason, 'mismatch');
+      assert.match(error.message, /no namespace `team-a`/);
+    });
+  });
+
+  it('skips the probe for the root namespace, however it is spelled', async () => {
+    await withFake(routes({ json: HEALTHY, status: 200 }), async (bao) => {
+      const env = { BAO_ADDR: bao.address, BAO_NAMESPACE: 'root' };
+      await run(env, assertBaoIdentityEffect({ clusterName: 'vault-example', namespace: '/' }));
+      assert.equal(bao.seen.length, 1);
+    });
+  });
+
+  it('refuses a 200 that is not an OpenBao health body', async () => {
+    await withFake(routes({ json: { ok: true }, status: 200 }), async (bao) => {
+      const error = await failureOf(
+        runFailure(envOf(bao.address), assertBaoIdentityEffect(EXPECT)),
+      );
+      assert.equal(error.reason, 'unconfirmed');
+    });
+  });
+
+  it('rejects the Promise form with the BaoIdentityError itself', async () => {
+    const other = { ...HEALTHY, cluster_name: 'vault-other' };
+    await withFake(routes({ json: other, status: 200 }), async (bao) => {
+      const error = await assertBaoIdentity({ ...EXPECT, env: envOf(bao.address) }).then(
+        () => undefined,
+        (rejection: unknown) => rejection,
+      );
+      await failureOf(Promise.resolve(error));
+    });
+  });
+});

package/src/openbao/bao-identity.ts

@@ -0,0 +1,188 @@
+/**
+ * Refuse to plan against the wrong vault: assert the `cluster_name` and namespace a stack expects
+ * BEFORE any Bao.* resource reads or writes.
+ *
+ * ⛔ WHY IT EXISTS. A `BAO_ADDR` left exported for one vault (or a `BAO_AGENT_ADDR`, which wins)
+ *   would otherwise apply a stack written for another vault to it, and every family here would
+ *   plan CREATEs against the wrong server with a clean conscience (the estate's site-config plan,
+ *   "Identity checks on every live plan").
+ *   A missing `BAO_NAMESPACE` does the same thing one level down: the stack lands in root.
+ *
+ * ★ `sys/health`, UNAUTHENTICATED, WITH NO TOKEN AND NO NAMESPACE HEADER. READ FROM openbao v2.6.2:
+ *   · http/sys_health.go:143-165 — `cluster_name` and `cluster_id` are filled ONLY while unsealed,
+ *     and the body is top-level JSON, not wrapped in `data`.
+ *   · http/handler.go:108-124, :405-411 — `health` is a root-only API: a request carrying
+ *     `X-Vault-Namespace` is answered 400 "operation unavailable in namespaces". So the header is
+ *     stripped for this one call, whatever BAO_NAMESPACE says.
+ *   · The query asks for 200 when sealed, uninitialised or standby (`sealedcode`, `uninitcode`,
+ *     `standbyok`, :78-110), so the body is always there to read and the refusal can say WHICH.
+ *   ⛔ NO TOKEN IS SENT. Until this check passes, the server has not even claimed to be ours, and a
+ *     token sent to the wrong server is a token handed over.
+ * ⚠️ IT CATCHES A MISTARGET, NOT AN IMPOSTOR (review 2026-09-21). `cluster_name` is answered to
+ *   anyone, unauthenticated, so a hostile server can echo the expected one; passing proves the
+ *   address is configured right, never who answers. TLS to a trusted certificate is what
+ *   authenticates the server — keep an https BAO_ADDR on anything that is not loopback or a socket.
+ * ★ THE NAMESPACE IS CHECKED TWICE. Locally first: the namespace every later call will send (the
+ *   same bao-address.ts resolution) must BE the expected one. Then remotely: unauthenticated
+ *   `sys/internal/ui/mounts` with that namespace header answers 200 when the namespace exists and
+ *   404 "namespace not found" when it does not (vault/request_handling.go:607-612; the path is in
+ *   the system backend's Unauthenticated list, vault/logical_system.go:95). Only the status is read.
+ *   REASONED FROM SOURCE, not measured against a live server.
+ * ⚠️ IT PROVES THE CLUSTER, NOT THE NODE. A standby answers with the cluster's name, which is the
+ *   point: a standby forwards to the same vault.
+ */
+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, resolveAddress } from './bao-address.ts';
+import { BaoEnv, baoCall } from './bao-http.ts';
+import { canonicalNamespace, envNamespace, namespaceLabel } from './bao-namespace.ts';
+import type { BaoError } from './bao-status.ts';
+
+/** `input` a blank expectation · `mismatch` the wrong vault · `unconfirmed` could not tell · `unreachable` no answer. */
+export type BaoIdentityFailure = 'input' | 'mismatch' | 'unconfirmed' | 'unreachable';
+
+/** ⛔ Every message starts `REFUSING:`, and none carries a token — only the address and names. */
+export class BaoIdentityError extends Error {
+  constructor(
+    readonly reason: BaoIdentityFailure,
+    detail: string,
+  ) {
+    super(`REFUSING: ${detail}`);
+    this.name = 'BaoIdentityError';
+  }
+}
+
+export interface BaoIdentityExpected {
+  /** The vault's `cluster_name` (server config `cluster_name`, or the one generated at init). */
+  readonly clusterName: string;
+  /** The namespace the stack targets: `team-a`, or `''` / `root` for the root namespace. */
+  readonly namespace: string;
+}
+
+/** What the vault said about itself once every check passed. */
+export interface BaoIdentity {
+  /** The resolved address, without any token. */
+  readonly address: string;
+  readonly clusterName: string;
+  readonly clusterId: string;
+  readonly version: string;
+  /** Canonical: `''` is root. */
+  readonly namespace: string;
+}
+
+export const HEALTH_PATH = 'sys/health?standbyok=true&sealedcode=200&uninitcode=200';
+export const NAMESPACE_PROBE_PATH = 'sys/internal/ui/mounts';
+
+const addressOf = (env: BaoEnvironment) => {
+  const address = resolveAddress(env);
+  return address.socket === undefined ? address.base : `unix://${address.socket}`;
+};
+
+const unreachable =
+  (address: string, what: string) =>
+  (error: BaoError): BaoIdentityError =>
+    new BaoIdentityError('unreachable', `${address} did not answer ${what}: ${error.message}`);
+
+const text = (value: unknown) => (typeof value === 'string' ? value : '');
+
+/** Read a health body into the one question asked of it. Pure, for the tests. */
+export const checkHealth = (
+  address: string,
+  expectedCluster: string,
+  body: Record<string, unknown> | undefined,
+): { readonly clusterId: string; readonly version: string } | BaoIdentityError => {
+  if (body === undefined || typeof body['sealed'] !== 'boolean') {
+    return new BaoIdentityError(
+      'unconfirmed',
+      `${address} answered sys/health, but not as OpenBao.`,
+    );
+  }
+  if (body['initialized'] === false) {
+    return new BaoIdentityError('unconfirmed', `${address} is not initialised.`);
+  }
+  if (body['sealed'] === true) {
+    return new BaoIdentityError(
+      'unconfirmed',
+      `${address} is sealed, and a sealed vault does not report its cluster_name.`,
+    );
+  }
+  const clusterName = text(body['cluster_name']);
+  if (clusterName !== expectedCluster) {
+    return new BaoIdentityError(
+      'mismatch',
+      `${address} answers as cluster \`${clusterName || '(none)'}\`, but this stack expects ` +
+        `\`${expectedCluster}\`. Check BAO_ADDR and BAO_AGENT_ADDR (the agent address wins).`,
+    );
+  }
+  return { clusterId: text(body['cluster_id']), version: text(body['version']) };
+};
+
+/**
+ * The check, as an Effect under BaoEnv (process.env unless provided). Fails with BaoIdentityError
+ * and nothing else.
+ */
+export const assertBaoIdentityEffect = (
+  expected: BaoIdentityExpected,
+): Effect.Effect<BaoIdentity, BaoIdentityError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const env = yield* BaoEnv;
+    const address = addressOf(env);
+    const clusterName = expected.clusterName.trim();
+    if (clusterName === '') {
+      return yield* Effect.fail(
+        new BaoIdentityError('input', 'clusterName is empty, so there is nothing to compare.'),
+      );
+    }
+    const namespace = canonicalNamespace(expected.namespace);
+    const sent = envNamespace(env);
+    if (sent !== namespace) {
+      return yield* Effect.fail(
+        new BaoIdentityError(
+          'mismatch',
+          `BAO_NAMESPACE resolves to \`${namespaceLabel(sent)}\`, but this stack expects ` +
+            `\`${namespaceLabel(namespace)}\`.`,
+        ),
+      );
+    }
+
+    const anonymous = { ...env, BAO_NAMESPACE: '', BAO_TOKEN: '' };
+    const body = yield* baoCall('read', 'GET', HEALTH_PATH).pipe(
+      Effect.provideService(BaoEnv, anonymous),
+      Effect.mapError(unreachable(address, 'sys/health')),
+    );
+    const health = checkHealth(address, clusterName, body);
+    if (health instanceof BaoIdentityError) return yield* Effect.fail(health);
+
+    if (namespace !== '') {
+      const scoped = { ...env, BAO_NAMESPACE: namespace, BAO_TOKEN: '' };
+      const probe = yield* baoCall('read', 'GET', NAMESPACE_PROBE_PATH).pipe(
+        Effect.provideService(BaoEnv, scoped),
+        Effect.mapError(unreachable(address, `the namespace probe for \`${namespace}\``)),
+      );
+      if (probe === undefined) {
+        return yield* Effect.fail(
+          new BaoIdentityError(
+            'mismatch',
+            `cluster \`${clusterName}\` at ${address} has no namespace \`${namespace}\`.`,
+          ),
+        );
+      }
+    }
+    return { address, clusterName, namespace, ...health };
+  });
+
+/**
+ * `assertBaoIdentityEffect` for a plain script. `env` defaults to `process.env`, read at call time.
+ * ★ Rejects with the BaoIdentityError itself (Effect.runPromise, as in approle-login.ts).
+ *
+ *     await assertBaoIdentity({ clusterName: 'vault-example', namespace: 'team-a' });
+ */
+export const assertBaoIdentity = (
+  input: BaoIdentityExpected & { readonly env?: BaoEnvironment },
+): Promise<BaoIdentity> => {
+  const effect = assertBaoIdentityEffect(input);
+  const scoped =
+    input.env === undefined ? effect : Effect.provideService(effect, BaoEnv, input.env);
+  return Effect.runPromise(scoped.pipe(Effect.provide(FetchHttpClient.layer)));
+};

package/src/openbao/bao-namespace.ts

@@ -0,0 +1,32 @@
+/**
+ * Namespace spellings, made comparable. `homeflare`, `/homeflare/` and `homeflare/` are one
+ * namespace to OpenBao, and `root` (or nothing) is the root namespace.
+ *
+ * ★ READ FROM openbao v2.6.2: namespace.Canonicalize trims the leading slash and appends a trailing
+ *   one, and ResolveNamespaceFromRequest (vault/namespace_store.go:1573-1598) re-routes a header
+ *   that is literally `root/` to the root namespace. A namespace's own `namespace_path` in an API
+ *   answer is that canonical form: `''` for root, `a/b/` below it (vault/login_mfa.go
+ *   mfaConfigToMap and mfaLoginEnforcementConfigToMap).
+ */
+import { type BaoEnvironment, resolveAddress } from './bao-address.ts';
+import { trimSlashes } from './mount-path.ts';
+
+/** The bare name: no leading or trailing slash, and `''` for the root namespace. */
+export const canonicalNamespace = (namespace: string | undefined): string => {
+  const bare = trimSlashes((namespace ?? '').trim());
+  return bare === 'root' ? '' : bare;
+};
+
+/** OpenBao's `namespace_path` rendering of the same namespace: `''` or `a/b/`. */
+export const namespacePath = (namespace: string | undefined): string => {
+  const bare = canonicalNamespace(namespace);
+  return bare === '' ? '' : `${bare}/`;
+};
+
+/** The namespace every call under `env` targets, canonical. */
+export const envNamespace = (env: BaoEnvironment): string =>
+  canonicalNamespace(resolveAddress(env).namespace);
+
+/** How a namespace reads in a message: `root` rather than an empty pair of backticks. */
+export const namespaceLabel = (namespace: string): string =>
+  namespace === '' ? 'root' : namespace;

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

@@ -14,6 +14,7 @@
  */
 import { accountResource, bucketResource, zoneResource } from './cloudflare-group-scope.ts';
 import type { AccountSpec, RoleTemplate, RolesConfig } from './cloudflare-roles-config.ts';
+import { trimRuns } from './mount-path.ts';
 
 /** A zone as the expansion needs it — what cfhf.py load_account listed (cfhf.py:134-146). */
 export interface CloudflareZone {
@@ -73,11 +74,7 @@ export interface ExpandedRole {
 }
 
 /** cfroles.py:18-20 — `example.com` → `homeflare-dev`. */
-export const slug = (name: string) =>
-  name
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
+export const slug = (name: string) => trimRuns(name.toLowerCase().replace(/[^a-z0-9]+/g, '-'), '-');
 
 /**
  * cfroles.py:23-38. ⛔ THE `-internal` SUFFIX IS WHAT KEEPS TWO ZONES OF ONE NAME APART. Slugging

package/src/openbao/host-approles.test.ts

@@ -0,0 +1,121 @@
+/**
+ * hostAppRoles: one role per host, named `<class>--<host>`, and never a secret_id that does not
+ * expire. The hosts and classes here are placeholders, not the estate's.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  HOST_ROLE_SEPARATOR,
+  type HostRoleClass,
+  hostAppRoles,
+  hostRoleName,
+} from './host-approles.ts';
+import { parseDuration } from './mount-form.ts';
+
+const INFRA: HostRoleClass = {
+  policies: ['host-cert', 'pve-node', 'host-cert'],
+  secretIdTtl: '2160h',
+  tokenMaxTtl: '1h',
+  tokenTtl: '15m',
+};
+const SIGNER: HostRoleClass = {
+  policies: ['ssh-signer'],
+  secretIdTtl: '90d',
+  tokenMaxTtl: '30m',
+  tokenTtl: '10m',
+};
+const INPUT = {
+  classes: { 'operator-signer': SIGNER, 'pve-node': INFRA },
+  hosts: [
+    { class: 'pve-node', name: 'node-b' },
+    { class: 'pve-node', name: 'node-a' },
+    { class: 'operator-signer', name: 'workstation-1' },
+  ],
+};
+
+describe('hostAppRoles', () => {
+  it('makes one role per host, named <class>--<host>, sorted', () => {
+    const roles = hostAppRoles(INPUT);
+    assert.deepEqual(
+      roles.map((role) => role.name),
+      ['operator-signer--workstation-1', 'pve-node--node-a', 'pve-node--node-b'],
+    );
+    assert.equal(hostRoleName('pve-node', 'node-a'), 'pve-node--node-a');
+  });
+
+  it('gives every role an expiring secret_id — none has secret_id_ttl 0', () => {
+    for (const role of hostAppRoles(INPUT)) {
+      const seconds = parseDuration(role.secretIdTtl);
+      assert.ok(
+        seconds !== undefined && seconds > 0,
+        `${role.name} secret_id_ttl ${role.secretIdTtl}`,
+      );
+      assert.equal(role.bindSecretId, true);
+    }
+  });
+
+  it("carries the class's policies, de-duplicated, and its TTLs", () => {
+    const role = hostAppRoles(INPUT).find((each) => each.name === 'pve-node--node-a');
+    assert.deepEqual(role?.tokenPolicies, ['host-cert', 'pve-node']);
+    assert.equal(role?.tokenTtl, '15m');
+    assert.equal(role?.secretIdNumUses, 0);
+  });
+
+  it('splits every name back into exactly one class and host', () => {
+    for (const role of hostAppRoles(INPUT)) {
+      assert.equal(role.name.split(HOST_ROLE_SEPARATOR).length, 2, role.name);
+    }
+  });
+
+  it('refuses a secret_id that never expires, or does not parse', () => {
+    for (const secretIdTtl of ['0', '0s', 'forever']) {
+      assert.throws(
+        () =>
+          hostAppRoles({
+            ...INPUT,
+            classes: { ...INPUT.classes, 'pve-node': { ...INFRA, secretIdTtl } },
+          }),
+        /must be a duration above zero/,
+      );
+    }
+  });
+
+  it('refuses unknown classes, duplicate hosts and names that would blur the separator', () => {
+    const bad = [
+      { class: 'nope', name: 'node-c' },
+      { class: 'pve-node', name: 'node-a' },
+      { class: 'pve-node', name: 'node-a' },
+      { class: 'pve-node', name: 'node--x' },
+      { class: 'pve-node', name: 'Node-Y' },
+    ];
+    assert.throws(
+      () => hostAppRoles({ ...INPUT, hosts: bad }),
+      (error: unknown) => {
+        assert.ok(error instanceof Error);
+        assert.match(error.message, /unknown class `nope`/);
+        assert.match(error.message, /`node-a` is listed twice/);
+        assert.match(error.message, /`node--x` is not lowercase/);
+        assert.match(error.message, /`Node-Y` is not lowercase/);
+        return true;
+      },
+    );
+  });
+
+  it('refuses a class with no policies, with root, or with ttl above max', () => {
+    const classes = {
+      empty: { ...INFRA, policies: [] },
+      rooted: { ...INFRA, policies: ['root'] },
+      upside: { ...INFRA, tokenMaxTtl: '5m', tokenTtl: '1h' },
+    };
+    assert.throws(
+      () => hostAppRoles({ classes, hosts: [] }),
+      (error: unknown) => {
+        assert.ok(error instanceof Error);
+        assert.match(error.message, /`empty` has no policies/);
+        assert.match(error.message, /`rooted` grants `root`/);
+        assert.match(error.message, /`upside` tokenTtl is longer/);
+        return true;
+      },
+    );
+  });
+});