@homeflare/alchemy 0.5.0 → 0.7.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-role-wire.test.ts

@@ -1,7 +1,8 @@
 /**
- * Bao.CloudflareRole's calls against a fake that behaves like the Cloudflare engine where it matters:
- * a write parses the duration text into seconds and re-marshals `policies` (path_roles.go:117-146,
- * :199-210), a role never written is a 404, and a delete answers 204 whether or not it existed.
+ * Bao.CloudflareRole's calls against a fake that behaves like the Cloudflare engine where it matters
+ * (fake-engines.ts): a write parses the duration text into seconds and re-marshals `policies`
+ * (path_roles.go:117-146, :199-210), a role never written is a 404, and a delete answers 204
+ * whether or not it existed.
  */
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
@@ -13,8 +14,8 @@ import {
   readCloudflareRole,
   writeCloudflareRole,
 } from './cloudflare-role-wire.ts';
-import { type Reply, type Seen, run, runFailure, withFake } from './fake-bao.ts';
-import { parseDuration } from './mount-form.ts';
+import { run, runFailure, withFake } from './fake-bao.ts';
+import { cloudflareRoles } from './fake-engines.ts';
 
 const PROPS: BaoCloudflareRoleProps = {
   description: 'Read DNS records on one zone. (zone: example.com)',
@@ -34,36 +35,9 @@ const PROPS: BaoCloudflareRoleProps = {
 
 const PATH = '/v1/cloudflare-acme-dns/roles/example-com-dns-read';
 
-/** The engine's role store, reduced to what these calls can observe. */
-const roleStore = () => {
-  const roles = new Map<string, Record<string, unknown>>();
-  return (seen: Seen): Reply => {
-    if (seen.method === 'PUT') {
-      const body = JSON.parse(seen.body) as Record<string, string>;
-      roles.set(seen.path, {
-        description: body['description'],
-        max_ttl: parseDuration(body['max_ttl'] ?? ''),
-        name: seen.path.split('/').at(-1),
-        // ★ Re-marshalled, as json.Marshal of the stored structs would be.
-        policies: JSON.stringify(JSON.parse(body['policies'] ?? 'null')),
-        ttl: parseDuration(body['ttl'] ?? ''),
-      });
-      return { status: 204 };
-    }
-    if (seen.method === 'DELETE') {
-      roles.delete(seen.path);
-      return { status: 204 };
-    }
-    const role = roles.get(seen.path);
-    return role === undefined
-      ? { json: { errors: [] }, status: 404 }
-      : { json: { data: role }, status: 200 };
-  };
-};
-
 describe('Cloudflare role wire', () => {
   it('reads a role that was never written as absent', async () => {
-    await withFake(roleStore(), async (bao) => {
+    await withFake(cloudflareRoles(), async (bao) => {
       const env = { BAO_ADDR: bao.address };
       assert.equal(await run(env, readCloudflareRole(PROPS.mount, PROPS.name)), undefined);
       assert.deepEqual([bao.seen[0]?.method, bao.seen[0]?.path], ['GET', PATH]);
@@ -71,7 +45,7 @@ describe('Cloudflare role wire', () => {
   });
 
   it('writes the four fields and reads them back with no difference', async () => {
-    await withFake(roleStore(), async (bao) => {
+    await withFake(cloudflareRoles(), async (bao) => {
       const env = { BAO_ADDR: bao.address };
       const { policies } = resolvePolicies(
         PROPS.policies,

package/src/openbao/cloudflare-role.ts

@@ -38,6 +38,13 @@ import {
   readCloudflareRole,
   writeCloudflareRole,
 } from './cloudflare-role-wire.ts';
+import {
+  declaredRolePath,
+  isMoved,
+  judgeMove,
+  refuseMovedUpdate,
+  triedRolePath,
+} from './rename.ts';
 
 export type { BaoCloudflareRoleAttributes, BaoCloudflareRoleProps };
 
@@ -112,14 +119,24 @@ export const BaoCloudflareRoleProvider = () =>
          *   OpenBao UI changes what every future token can do while the digest in Postgres still
          *   says everything is fine.
          *
-         * ⚠️ NO `replace`, EVEN FOR A NAME OR MOUNT CHANGE. A different path is a different object,
-         *   so diff reads the new path, finds it absent and plans `update`; reconcile creates it and
-         *   the old role is left live, retained and unmanaged — the same outcome apply-roles.py's
-         *   UNTRACKED report had. declareCloudflareRoles puts mount and name in the resource id, so
-         *   a rename there is a new resource anyway.
+         * ⛔ A NEW `mount` OR `name` IS A `replace`, DECIDED BEFORE ANY OTHER READ (rename.ts). Until
+         *   2026-09-21 this read the new path, found it absent and planned `update`: reconcile wrote
+         *   the new role and the old one stayed live and mintable under no state record. ⛔ A move
+         *   onto a role that already exists fails the plan (`judgeMove`).
+         * ⚠️ UNDER THE DEFAULT `retain` THE OLD ROLE STILL MINTS for any token whose policy reaches its
+         *   `creds/<name>`. Under `destroy` every consumer still minting from the old path fails at
+         *   the delete, so move them in the same PR (REPLACE.md).
+         * ★ A STACK THAT PUTS mount AND name IN THE LOGICAL ID never reaches this branch
+         *   (homeflare-openbao's declareCloudflareRoles does). There a rename is a new logical id,
+         *   and the old id leaves the stack as an orphan delete, which `retain` keeps live.
          */
-        diff: Effect.fn(function* ({ news, output }) {
-          if (output === undefined || !isResolved(news)) return undefined;
+        diff: Effect.fn(function* ({ news, olds, output }) {
+          const tried = triedRolePath(output, olds, rolePath);
+          const declared = declaredRolePath(news, rolePath);
+          const move = yield* judgeMove('Bao.CloudflareRole', tried, declared, (path) => path);
+          if (output === undefined) return undefined;
+          if (move !== undefined) return { action: 'replace' } as const;
+          if (!isResolved(news)) return undefined;
           /**
            * ⚠️ A DECLARATION reconcile WOULD REFUSE MUST NEVER PLAN AS noop — route it to reconcile,
            *   which says why (pki-role.ts has the same guard).
@@ -133,8 +150,13 @@ export const BaoCloudflareRoleProvider = () =>
             : ({ action: 'update' } as const);
         }),
 
-        reconcile: Effect.fn(function* ({ news }) {
+        reconcile: Effect.fn(function* ({ news, output }) {
           const path = rolePath(news.mount, news.name);
+          // ⛔ An `update` across a move the diff could not see — refused before any write.
+          const before = output === undefined ? path : rolePath(output.mount, output.name);
+          if (isMoved(before, path) === true) {
+            return yield* refuseMovedUpdate('Bao.CloudflareRole', before, path);
+          }
           const refusal = refusalOf(news);
           if (refusal !== undefined) {
             return yield* Effect.die(new Error(`Bao.CloudflareRole ${path}: ${refusal}.`));

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