@homeflare/alchemy 0.5.0 → 0.6.0

package/src/openbao/mfa.test.ts

@@ -0,0 +1,200 @@
+/**
+ * Login MFA against a fake: a TOTP method found by name in THIS namespace only, and an enforcement
+ * whose mount paths resolve to accessors and whose lists always go over as arrays. Ids and names are
+ * placeholders.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { type Reply, type Seen, run, withFake } from './fake-bao.ts';
+import { planEnforcement, reconcileEnforcement } from './mfa-enforcement.ts';
+import { planTotp, reconcileTotp } from './mfa-totp.ts';
+import { renameProblem } from './mfa-totp-form.ts';
+
+const ENV = (address: string) => ({ BAO_ADDR: address, BAO_NAMESPACE: 'team-a' });
+const TOTP = { issuer: 'vault-example', name: 'admin-totp' };
+const METHOD_ID = '00000000-0000-4000-8000-00000000000a';
+const stored = (namespacePath: string, extra: Record<string, unknown> = {}) => ({
+  algorithm: 'SHA1',
+  digits: 6,
+  id: METHOD_ID,
+  issuer: 'vault-example',
+  key_size: 20,
+  max_validation_attempts: 5,
+  name: 'admin-totp',
+  namespace_path: namespacePath,
+  period: 30,
+  qr_size: 200,
+  skew: 1,
+  type: 'totp',
+  ...extra,
+});
+const listing = (...entries: Record<string, unknown>[]): Reply =>
+  entries.length === 0
+    ? { json: { errors: [] }, status: 404 }
+    : {
+        json: {
+          data: {
+            key_info: Object.fromEntries(entries.map((e, i) => [`id-${String(i)}`, e])),
+            keys: [],
+          },
+        },
+        status: 200,
+      };
+
+/** Listing replies in order (the last repeats); every write answers 200. */
+const totpFake = (...lists: Reply[]) => {
+  let reads = 0;
+  return (seen: Seen): Reply => {
+    if (seen.method !== 'GET') return { json: { data: { method_id: METHOD_ID } }, status: 200 };
+    const reply = lists[Math.min(reads, lists.length - 1)] ?? listing();
+    reads += 1;
+    return reply;
+  };
+};
+const writes = (seen: Seen[]) => seen.filter((each) => each.method !== 'GET');
+
+describe('Bao.MfaTotpMethod', () => {
+  it('upserts by method_name when absent, and returns the id it read back', async () => {
+    await withFake(totpFake(listing(), listing(stored('team-a/'))), async (bao) => {
+      const attributes = await run(ENV(bao.address), reconcileTotp(TOTP));
+      assert.equal(attributes.methodId, 'id-0');
+      const [write] = writes(bao.seen);
+      assert.equal(write?.path, '/v1/identity/mfa/method/totp');
+      const body = JSON.parse(write?.body ?? '{}') as Record<string, unknown>;
+      assert.equal(body['method_name'], 'admin-totp');
+      assert.equal(body['method_id'], undefined);
+      assert.equal(body['period'], '30s');
+    });
+  });
+
+  it('plans noop and writes nothing when this namespace already has it', async () => {
+    await withFake(totpFake(listing(stored('team-a/'))), async (bao) => {
+      assert.equal(await run(ENV(bao.address), planTotp(TOTP)), 'noop');
+      await run(ENV(bao.address), reconcileTotp(TOTP));
+      assert.equal(writes(bao.seen).length, 0);
+    });
+  });
+
+  it("ignores a same-named method in a parent namespace — it is not this namespace's", async () => {
+    await withFake(
+      totpFake(listing(stored('')), listing(stored(''), stored('team-a/'))),
+      async (bao) => {
+        await run(ENV(bao.address), reconcileTotp(TOTP));
+        assert.equal(writes(bao.seen).length, 1);
+      },
+    );
+  });
+
+  it('refuses a rename at plan time — a new id would strand every enrolled secret', () => {
+    assert.equal(renameProblem('admin-totp', 'admin-totp'), undefined);
+    assert.match(renameProblem('admin-totp', 'admin-otp') ?? '', /strand every enrolled secret/);
+  });
+
+  it('refuses a name another method type holds here — a TOTP write would convert it', async () => {
+    await withFake(totpFake(listing(stored('team-a/', { type: 'duo' }))), async (bao) => {
+      await assert.rejects(run(ENV(bao.address), reconcileTotp(TOTP)), /belongs to a duo method/);
+      assert.equal(writes(bao.seen).length, 0);
+      // ★ The GLOBAL listing — the per-type one cannot see a Duo method at all.
+      assert.equal(bao.seen[0]?.path, '/v1/identity/mfa/method?list=true');
+    });
+  });
+
+  it('plans update on drift, and refuses a bad declaration before any call', async () => {
+    await withFake(totpFake(listing(stored('team-a/', { digits: 8 }))), async (bao) => {
+      assert.equal(await run(ENV(bao.address), planTotp(TOTP)), 'update');
+    });
+    await withFake(totpFake(listing()), async (bao) => {
+      await assert.rejects(
+        run(ENV(bao.address), reconcileTotp({ ...TOTP, issuer: '' })),
+        /issuer is empty/,
+      );
+      assert.equal(bao.seen.length, 0);
+    });
+  });
+});
+
+const AUTH_TABLE: Reply = {
+  json: {
+    data: {
+      'oidc/': { accessor: 'auth_oidc_1', type: 'oidc' },
+      'token/': { accessor: 'auth_token_1', type: 'token' },
+    },
+  },
+  status: 200,
+};
+const ENFORCE = { authMethodPaths: ['oidc'], mfaMethodIds: [METHOD_ID], name: 'admin-mfa' };
+const enforcementLive = (accessors: string[]) => ({
+  json: {
+    data: {
+      auth_method_accessors: accessors,
+      auth_method_types: [],
+      id: 'enf-1',
+      identity_entity_ids: [],
+      identity_group_ids: [],
+      mfa_method_ids: [METHOD_ID],
+      name: 'admin-mfa',
+      namespace_path: 'team-a/',
+    },
+  },
+  status: 200,
+});
+
+/** sys/auth answers the table; the enforcement answers `states` in order; writes answer 204. */
+const enforcementFake = (...states: Reply[]) => {
+  let reads = 0;
+  return (seen: Seen): Reply => {
+    if (seen.path === '/v1/sys/auth') return AUTH_TABLE;
+    if (seen.method !== 'GET') return { status: 204 };
+    const reply = states[Math.min(reads, states.length - 1)] ?? {
+      json: { errors: [] },
+      status: 404,
+    };
+    reads += 1;
+    return reply;
+  };
+};
+
+describe('Bao.MfaLoginEnforcement', () => {
+  it('resolves mount paths to accessors and sends every list as an array', async () => {
+    const absent = { json: { errors: [] }, status: 404 };
+    await withFake(enforcementFake(absent, enforcementLive(['auth_oidc_1'])), async (bao) => {
+      const attributes = await run(ENV(bao.address), reconcileEnforcement(ENFORCE));
+      assert.equal(attributes.enforcementId, 'enf-1');
+      const [write] = writes(bao.seen);
+      assert.equal(write?.path, '/v1/identity/mfa/login-enforcement/admin-mfa');
+      assert.deepEqual(JSON.parse(write?.body ?? '{}'), {
+        auth_method_accessors: ['auth_oidc_1'],
+        auth_method_types: [],
+        identity_entity_ids: [],
+        identity_group_ids: [],
+        mfa_method_ids: [METHOD_ID],
+      });
+    });
+  });
+
+  it('plans update when live carries a target the declaration does not', async () => {
+    await withFake(
+      enforcementFake(enforcementLive(['auth_oidc_1', 'auth_token_1'])),
+      async (bao) => {
+        assert.equal(await run(ENV(bao.address), planEnforcement(ENFORCE)), 'update');
+      },
+    );
+    await withFake(enforcementFake(enforcementLive(['auth_oidc_1'])), async (bao) => {
+      assert.equal(await run(ENV(bao.address), planEnforcement(ENFORCE)), 'noop');
+    });
+  });
+
+  it('refuses a path with no mount, and an enforcement with no target, before writing', async () => {
+    await withFake(enforcementFake(), async (bao) => {
+      await assert.rejects(
+        run(ENV(bao.address), reconcileEnforcement({ ...ENFORCE, authMethodPaths: ['jwt-admin'] })),
+        /no auth mount at jwt-admin/,
+      );
+      await assert.rejects(
+        run(ENV(bao.address), reconcileEnforcement({ ...ENFORCE, authMethodPaths: [] })),
+        /enforces NOTHING/,
+      );
+      assert.equal(writes(bao.seen).length, 0);
+    });
+  });
+});

package/src/openbao/mount-form.ts

@@ -1,7 +1,8 @@
 import { sha256 } from './digest.ts';
+import { trimTrailingSlashes } from './mount-path.ts';
 
 /** Mount path without a trailing slash — props and `sys/mounts/<path>` use this shape. */
-export const mountPath = (path: string) => path.replace(/\/+$/, '');
+export const mountPath = (path: string) => trimTrailingSlashes(path);
 
 const DURATION = /^(\d+)([smhd])$/;
 
@@ -46,6 +47,13 @@ export interface BaoMountProps {
   maxLeaseTtl?: string;
   /** KV only — sent as `options.version` on enable, as `-version=2` was. Immutable after create. */
   version?: 1 | 2;
+  /**
+   * The path this mount lives at NOW, when `path` is where it should move to. Moves it with
+   * `sys/remount`, keeping every secret. Without it, a changed `path` fails the plan — see
+   * mount-move.ts. ⛔ Every lease under the old path is revoked, and policies are not rewritten.
+   * Harmless to leave declared after the move: once state holds `path`, it is ignored.
+   */
+  remountFrom?: string;
 }
 
 export interface BaoMountAttributes {

package/src/openbao/mount-move.test.ts

@@ -0,0 +1,164 @@
+/**
+ * A changed mount path: refused without `remountFrom`, moved with it — for secrets engines and for
+ * auth methods. The fake keeps a live mount table, so the move is judged by what it leaves behind.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { reconcileAuthMethod } from './auth-method-reconcile.ts';
+import { type Reply, type Seen, run, withFake } from './fake-bao.ts';
+import { planMove } from './mount-move.ts';
+import { reconcileMount } from './mount-reconcile.ts';
+
+describe('planMove', () => {
+  it('stays when the path is unchanged, whatever remountFrom says', () => {
+    assert.deepEqual(planMove('Bao.Mount', 'kv', 'kv/', undefined), { kind: 'stay' });
+    assert.deepEqual(planMove('Bao.Mount', 'kv', 'kv', 'old'), { kind: 'stay' });
+    assert.deepEqual(planMove('Bao.Mount', undefined, 'kv', undefined), { kind: 'stay' });
+  });
+
+  it('refuses a changed path with no remountFrom, and names the fix', () => {
+    const move = planMove('Bao.Mount', 'kv', 'kv2', undefined);
+    assert.equal(move.kind, 'refuse');
+    assert.match(move.kind === 'refuse' ? move.message : '', /EMPTY mount.*remountFrom: 'kv'/s);
+  });
+
+  it('refuses a remountFrom that is not the path in state', () => {
+    assert.equal(planMove('Bao.Mount', 'kv', 'kv2', 'other').kind, 'refuse');
+  });
+
+  it('moves when remountFrom names the stated path, or on a first reconcile', () => {
+    assert.deepEqual(planMove('Bao.Mount', 'kv/', 'kv2', 'kv/'), { from: 'kv', kind: 'move' });
+    assert.deepEqual(planMove('Bao.Mount', undefined, 'kv2', 'kv'), { from: 'kv', kind: 'move' });
+  });
+});
+
+/** A fake with a live table under `prefix` (`sys/mounts` or `sys/auth`) that sys/remount edits. */
+const liveTable = (prefix: string, initial: Record<string, string>) => {
+  const table = new Map(Object.entries(initial).map(([path, type]) => [`${path}/`, type]));
+  const entry = (type: string) => ({ config: { default_lease_ttl: 0, max_lease_ttl: 0 }, type });
+  const answer = (seen: Seen): Reply => {
+    const path = seen.path.replace(/^\/v1\//, '');
+    if (path === 'sys/remount' && seen.method === 'POST') {
+      const { from, to } = JSON.parse(seen.body) as { from: string; to: string };
+      const key = `${from.replace(/^auth\//, '')}/`;
+      const type = table.get(key);
+      if (type === undefined) return { json: { errors: ['no matching mount'] }, status: 400 };
+      table.delete(key);
+      table.set(`${to.replace(/^auth\//, '')}/`, type);
+      return { json: { data: { migration_id: 'm-1' } }, status: 200 };
+    }
+    if (path.startsWith('sys/remount/status/')) {
+      return { json: { data: { migration_info: { status: 'success' } } }, status: 200 };
+    }
+    if (path === prefix) {
+      return { json: { data: Object.fromEntries(table) }, status: 200 };
+    }
+    const mount = path.slice(prefix.length + 1).replace(/\/tune$/, '');
+    if (seen.method === 'POST') {
+      if (!path.endsWith('/tune')) table.set(`${mount}/`, 'enabled-by-test');
+      return { status: 204 };
+    }
+    const type = table.get(`${mount}/`);
+    return type === undefined
+      ? { json: { errors: [`No secret engine mount at ${mount}/`] }, status: 400 }
+      : { json: { data: entry(type) }, status: 200 };
+  };
+  return { answer, table };
+};
+
+const posts = (seen: Seen[]) =>
+  seen.filter((each) => each.method === 'POST').map((each) => each.path);
+
+describe('reconcileMount', () => {
+  it('moves kv to its new path with sys/remount, and enables nothing', async () => {
+    const live = liveTable('sys/mounts', { kv: 'kv' });
+    await withFake(live.answer, async (bao) => {
+      const props = { path: 'kv-moved', remountFrom: 'kv', type: 'kv' };
+      const attributes = await run({ BAO_ADDR: bao.address }, reconcileMount(props, 'kv'));
+      assert.equal(attributes.path, 'kv-moved');
+      assert.deepEqual(posts(bao.seen), ['/v1/sys/remount']);
+      assert.deepEqual([...live.table.keys()], ['kv-moved/']);
+    });
+  });
+
+  it('refuses a changed path with no remountFrom before any write', async () => {
+    const live = liveTable('sys/mounts', { kv: 'kv' });
+    await withFake(live.answer, async (bao) => {
+      await assert.rejects(
+        run({ BAO_ADDR: bao.address }, reconcileMount({ path: 'kv-moved', type: 'kv' }, 'kv')),
+        /EMPTY mount/,
+      );
+      assert.deepEqual(posts(bao.seen), []);
+    });
+  });
+
+  it('converges when the move already happened (an interrupted apply re-running)', async () => {
+    const live = liveTable('sys/mounts', { 'kv-moved': 'kv' });
+    await withFake(live.answer, async (bao) => {
+      const props = { path: 'kv-moved', remountFrom: 'kv', type: 'kv' };
+      await run({ BAO_ADDR: bao.address }, reconcileMount(props, 'kv'));
+      assert.deepEqual(posts(bao.seen), []);
+    });
+  });
+
+  it('refuses when neither path exists, rather than enabling an empty mount', async () => {
+    const live = liveTable('sys/mounts', {});
+    await withFake(live.answer, async (bao) => {
+      const props = { path: 'kv-moved', remountFrom: 'kv', type: 'kv' };
+      await assert.rejects(
+        run({ BAO_ADDR: bao.address }, reconcileMount(props, undefined)),
+        /empty mount where data was expected/,
+      );
+      assert.deepEqual(posts(bao.seen), []);
+    });
+  });
+
+  it('refuses when both paths exist, or the source is another type', async () => {
+    const both = liveTable('sys/mounts', { kv: 'kv', 'kv-moved': 'kv' });
+    await withFake(both.answer, async (bao) => {
+      const props = { path: 'kv-moved', remountFrom: 'kv', type: 'kv' };
+      await assert.rejects(run({ BAO_ADDR: bao.address }, reconcileMount(props, 'kv')), /both/);
+    });
+    const typed = liveTable('sys/mounts', { kv: 'pki' });
+    await withFake(typed.answer, async (bao) => {
+      const props = { path: 'kv-moved', remountFrom: 'kv', type: 'kv' };
+      await assert.rejects(run({ BAO_ADDR: bao.address }, reconcileMount(props, 'kv')), /type/);
+    });
+  });
+});
+
+describe('a type change (REPLACE.md)', () => {
+  it("fails the replacement's create on the occupied path, before any write", async () => {
+    const live = liveTable('sys/mounts', { kv: 'kv' });
+    await withFake(live.answer, async (bao) => {
+      // ★ A replacement's new generation reconciles with no state: `stated` is undefined.
+      const replacement = reconcileMount({ path: 'kv', type: 'pki' }, undefined);
+      await assert.rejects(run({ BAO_ADDR: bao.address }, replacement), /immutable/);
+      assert.deepEqual(posts(bao.seen), []);
+      assert.deepEqual([...live.table.entries()], [['kv/', 'kv']]);
+    });
+  });
+});
+
+describe('reconcileAuthMethod', () => {
+  it('moves an auth method through sys/remount with the auth/ prefix', async () => {
+    const live = liveTable('sys/auth', { jwt: 'jwt' });
+    await withFake(live.answer, async (bao) => {
+      const props = { path: 'jwt-humans', remountFrom: 'jwt', type: 'jwt' };
+      await run({ BAO_ADDR: bao.address }, reconcileAuthMethod(props, 'jwt'));
+      const start = bao.seen.find((seen) => seen.path === '/v1/sys/remount');
+      assert.equal(start?.body, JSON.stringify({ from: 'auth/jwt', to: 'auth/jwt-humans' }));
+      assert.deepEqual([...live.table.keys()], ['jwt-humans/']);
+    });
+  });
+
+  it('refuses a changed auth path with no remountFrom', async () => {
+    const live = liveTable('sys/auth', { jwt: 'jwt' });
+    await withFake(live.answer, async (bao) => {
+      await assert.rejects(
+        run({ BAO_ADDR: bao.address }, reconcileAuthMethod({ path: 'jwt2', type: 'jwt' }, 'jwt')),
+        /Bao\.AuthMethod: path changed/,
+      );
+    });
+  });
+});

package/src/openbao/mount-move.ts

@@ -0,0 +1,113 @@
+/**
+ * What a changed path means for Bao.Mount and Bao.AuthMethod — and the move, when one is declared.
+ *
+ * ⛔ A CHANGED PATH USED TO PLAN `update` AND ENABLE AN EMPTY MOUNT AT THE NEW PATH. diff read the
+ *   new path, found nothing, answered `update`, and reconcile ran `enable` there: a fresh, empty
+ *   `kv2/` beside the retained `kv/` that still held every secret, with Alchemy's state now naming
+ *   only the empty one. Nothing failed, so nothing said so (site-config plan, Guards).
+ * ★ NOW A CHANGED PATH FAILS AT PLAN TIME, unless the declaration says where it came from:
+ *   `remountFrom: '<old path>'` moves the mount with `sys/remount` (remount-wire.ts), which keeps
+ *   every secret. A genuinely new, empty mount is a new resource id, never an edited path.
+ * ★ THE MOVE IS DECIDED BY LIVE STATE, SO A RE-RUN CONVERGES. Source present and target absent is
+ *   a move; target present and source absent is a move that already happened; both present, or
+ *   neither, is a refusal — "neither" in particular is exactly the empty-mount failure above.
+ */
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import type { BaoError } from './bao-status.ts';
+import { mountPath } from './mount-form.ts';
+import { type RemountError, type RemountOptions, remountAndWait } from './remount-wire.ts';
+
+export type Move =
+  | { readonly kind: 'stay' }
+  | { readonly kind: 'move'; readonly from: string }
+  | { readonly kind: 'refuse'; readonly message: string };
+
+/**
+ * @param family  `Bao.Mount` or `Bao.AuthMethod`, for the message.
+ * @param stated  the path Alchemy's state holds, or undefined on a first reconcile.
+ * @param path    the declared path.
+ * @param remountFrom the declared source, if any.
+ */
+export const planMove = (
+  family: string,
+  stated: string | undefined,
+  path: string,
+  remountFrom: string | undefined,
+): Move => {
+  const to = mountPath(path);
+  const from = remountFrom === undefined ? undefined : mountPath(remountFrom);
+  if (stated === undefined) {
+    return from === undefined || from === to ? { kind: 'stay' } : { kind: 'move', from };
+  }
+  const was = mountPath(stated);
+  if (was === to) return { kind: 'stay' };
+  if (from === undefined) {
+    return {
+      kind: 'refuse',
+      message:
+        `${family}: path changed from ${was} to ${to}. That would enable an EMPTY mount at ${to} ` +
+        `and strand everything under ${was}. To move it with its data, declare ` +
+        `\`remountFrom: '${was}'\` (leases under it are revoked; policies are not rewritten). ` +
+        'For a new, empty mount, give it a new resource id instead.',
+    };
+  }
+  if (from !== was) {
+    return {
+      kind: 'refuse',
+      message: `${family}: remountFrom is ${from}, but the mount in state is ${was}.`,
+    };
+  }
+  return { kind: 'move', from };
+};
+
+export interface MoveTarget {
+  readonly family: string;
+  /** Declared path, bare. */
+  readonly path: string;
+  readonly type: string;
+  /** Read one path's live entry — undefined when absent. */
+  readonly read: (
+    path: string,
+  ) => Effect.Effect<{ readonly type: string } | undefined, BaoError, HttpClient.HttpClient>;
+  /** The path as sys/remount takes it: the bare path for secrets, `auth/<path>` for auth. */
+  readonly wire: (path: string) => string;
+}
+
+const refuse = (message: string) => Effect.die(new Error(message));
+
+/** Perform a planned move, deciding by live state. Returns once the target is in place. */
+export const performMove = (
+  target: MoveTarget,
+  from: string,
+  options?: RemountOptions,
+): Effect.Effect<void, BaoError | RemountError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const to = mountPath(target.path);
+    const source = yield* target.read(from);
+    const landed = yield* target.read(to);
+    if (source !== undefined && landed !== undefined) {
+      return yield* refuse(
+        `${target.family}: both ${from} and ${to} exist, so remountFrom cannot move one onto the ` +
+          'other. Decide which holds the data, and retire the other by hand.',
+      );
+    }
+    if (source === undefined && landed === undefined) {
+      return yield* refuse(
+        `${target.family}: remountFrom ${from} names no mount, and ${to} does not exist either. ` +
+          'Refusing to enable an empty mount where data was expected.',
+      );
+    }
+    if (source === undefined) return; // ★ Already moved — an interrupted apply re-running.
+    if (source.type !== target.type) {
+      return yield* refuse(
+        `${target.family}: ${from} is type ${source.type}, not ${target.type}. A remount keeps the ` +
+          'type; fix the declaration first.',
+      );
+    }
+    const confirm = Effect.map(
+      Effect.all([target.read(from), target.read(to)]),
+      ([gone, there]) => gone === undefined && there !== undefined,
+    );
+    yield* remountAndWait(target.wire(from), target.wire(to), confirm, options);
+  });

package/src/openbao/mount-path.test.ts

@@ -3,7 +3,7 @@
  */
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
-import { trimSlashes, trimTrailingSlashes } from './mount-path.ts';
+import { trimRuns, trimSlashes, trimTrailingSlashes } from './mount-path.ts';
 
 describe('mount-path', () => {
   it('trims outer slashes and keeps inner ones', () => {
@@ -21,3 +21,13 @@ describe('mount-path', () => {
     assert.ok(performance.now() - started < 1_000, 'slash trimming took over a second');
   });
 });
+
+describe('trimRuns', () => {
+  it('trims any single character and stays linear on long runs', () => {
+    assert.equal(trimRuns('--a-b--', '-'), 'a-b');
+    const run = '-'.repeat(200_000);
+    const started = performance.now();
+    assert.equal(trimRuns(`${run}x${run}y`, '-'), `x${run}y`);
+    assert.ok(performance.now() - started < 1_000, 'trimming took over a second');
+  });
+});

package/src/openbao/mount-path.ts

@@ -1,25 +1,31 @@
 /**
- * Slash trimming for caller-supplied mount paths.
+ * Trimming runs of one character from caller-supplied paths and names.
  *
- * ★ LOOPS, NOT `/^\/+|\/+$/g` OR `/\/+$/`. A trailing `\/+$` backtracks polynomially on a long run
- *   of `/` followed by anything else (CodeQL js/polynomial-redos), and mount paths are caller input.
- *   Both loops are linear in the input length.
+ * ★ LOOPS, NOT `/^\/+|\/+$/g`, `/\/+$/` OR `/^-+|-+$/g`. A trailing `x+$` backtracks polynomially
+ *   on a long run of `x` followed by anything else (CodeQL js/polynomial-redos), and mount paths,
+ *   namespaces and slugs are caller input. Every loop here is linear in the input length.
  */
 
-/** `text` without trailing `/`. */
-export const trimTrailingSlashes = (text: string): string => {
+/** `text` without a trailing run of `char` (one UTF-16 unit). */
+export const trimTrailing = (text: string, char: string): string => {
   let end = text.length;
-  while (end > 0 && text[end - 1] === '/') end -= 1;
+  while (end > 0 && text[end - 1] === char) end -= 1;
   return text.slice(0, end);
 };
 
-/** `text` without leading or trailing `/`. */
-export const trimSlashes = (text: string): string => {
+/** `text` without a leading or trailing run of `char` (one UTF-16 unit). */
+export const trimRuns = (text: string, char: string): string => {
   let start = 0;
-  while (start < text.length && text[start] === '/') start += 1;
-  return trimTrailingSlashes(text.slice(start));
+  while (start < text.length && text[start] === char) start += 1;
+  return trimTrailing(text.slice(start), char);
 };
 
+/** `text` without trailing `/`. */
+export const trimTrailingSlashes = (text: string): string => trimTrailing(text, '/');
+
+/** `text` without leading or trailing `/`. */
+export const trimSlashes = (text: string): string => trimRuns(text, '/');
+
 /** SSH mount path without a trailing slash; `ssh` when the caller did not say. */
 export const sshMountOf = (mount: string | undefined): string =>
   trimTrailingSlashes(mount ?? 'ssh');

package/src/openbao/mount-reconcile.ts

@@ -0,0 +1,75 @@
+/**
+ * Bao.Mount's read and reconcile as plain effects — split from mount.ts so the move (and its
+ * refusals) run against a fake server, not only in a reviewer's head.
+ */
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import type { BaoError } from './bao-status.ts';
+import {
+  type BaoMountAttributes,
+  type BaoMountProps,
+  attributesOf,
+  matches,
+  mountPath,
+  wantsTune,
+} from './mount-form.ts';
+import { type MoveTarget, performMove, planMove } from './mount-move.ts';
+import { enableMount, readMountData, tuneMount } from './mount-wire.ts';
+import type { RemountError, RemountOptions } from './remount-wire.ts';
+
+export const readMount = (
+  props: BaoMountProps,
+): Effect.Effect<BaoMountAttributes | undefined, BaoError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const live = yield* readMountData(props.path);
+    if (live === undefined) return undefined;
+    return attributesOf(props, live);
+  });
+
+const moveTarget = (props: BaoMountProps): MoveTarget => ({
+  family: 'Bao.Mount',
+  path: props.path,
+  read: (path) => readMount({ ...props, path }),
+  type: props.type,
+  wire: mountPath,
+});
+
+/**
+ * Converge one mount. `stated` is the path in Alchemy's state (undefined on a first reconcile).
+ * Dies on a refusal; fails with OpenBao's own error on a refused call.
+ */
+export const reconcileMount = (
+  news: BaoMountProps,
+  stated: string | undefined,
+  options?: RemountOptions,
+): Effect.Effect<BaoMountAttributes, BaoError | RemountError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const move = planMove('Bao.Mount', stated, news.path, news.remountFrom);
+    if (move.kind === 'refuse') return yield* Effect.die(new Error(move.message));
+    if (move.kind === 'move') yield* performMove(moveTarget(news), move.from, options);
+
+    let live = yield* readMount(news);
+    if (live === undefined) {
+      yield* enableMount(news);
+      if (wantsTune(news)) yield* tuneMount(news);
+    } else if (!matches(live, news)) {
+      if (live.type !== news.type) {
+        return yield* Effect.die(
+          new Error(
+            `Bao.Mount ${mountPath(news.path)}: live type ${live.type} != ${news.type}. ` +
+              'Secrets engine type is immutable — replace manually.',
+          ),
+        );
+      }
+      yield* tuneMount(news);
+    }
+    live = yield* readMount(news);
+    if (live === undefined) {
+      return yield* Effect.die(
+        new Error(
+          `Bao.Mount ${mountPath(news.path)}: write returned no error but the mount is still absent.`,
+        ),
+      );
+    }
+    return live;
+  });