@homeflare/alchemy 0.5.0 → 0.6.0

package/src/openbao/pki-role.ts

@@ -44,12 +44,13 @@ import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import type * as HttpClient from 'effect/unstable/http/HttpClient';
 import { baoDelete, baoRead, baoWrite } from './bao-http.ts';
-import { mountPath, parseDuration } from './mount-form.ts';
+import { mountPath } from './mount-form.ts';
 import {
   type BaoPkiRoleAttributes,
   type BaoPkiRoleProps,
   attributesOf,
   matches,
+  problems,
   rolePath,
   writeBody,
 } from './pki-role-form.ts';
@@ -75,12 +76,6 @@ const readRole = (props: BaoPkiRoleProps) =>
     return attributesOf(props, live);
   });
 
-/** Duration props `bao write` must never see — reconcile turns these into a refusal. */
-const badDurations = (props: BaoPkiRoleProps) =>
-  [['ttl', props.ttl] as const, ['maxTtl', props.maxTtl] as const].filter(
-    ([, text]) => parseDuration(text) === undefined,
-  );
-
 export const BaoPkiRoleProvider = () =>
   Provider.effect(
     BaoPkiRole,
@@ -111,18 +106,20 @@ export const BaoPkiRoleProvider = () =>
            * ⚠️ A ROLE IS IDENTIFIED BY MOUNT **AND** NAME. Moving a declaration to another
            *   engine is a different object under a different CA, never an in-place edit —
            *   `replace`, so Alchemy creates the new one and retires the old.
+           * ⛔ A RENAME WAS NOT CAUGHT UNTIL 2026-09-21 (REPLACE.md): only the mount was compared,
+           *   so a new `name` read nothing at the new path, planned `update`, wrote the new role,
+           *   and left the old one issuing certificates under no state record at all.
            */
-          if (mountPath(news.mount ?? 'pki') !== output.mount)
+          if (mountPath(news.mount ?? 'pki') !== output.mount || news.name !== output.name)
             return { action: 'replace' } as const;
           /**
            * ⚠️ A DECLARATION reconcile WOULD REFUSE MUST NEVER PLAN AS noop. An empty
            *   allowedDomains, or a duration OpenBao cannot parse, can compare equal to a
            *   live role already in that state — and a noop there hides the refusal behind a
            *   clean plan until the next deploy. Route it to reconcile, which says why.
+           *   (The full list is `problems` in pki-role-form.ts.)
            */
-          if (news.allowedDomains.length === 0 || badDurations(news).length > 0) {
-            return { action: 'update' } as const;
-          }
+          if (problems(news).length > 0) return { action: 'update' } as const;
           const live = yield* readRole(news);
           if (live === undefined) return { action: 'update' } as const;
           return matches(live, news)
@@ -136,24 +133,12 @@ export const BaoPkiRoleProvider = () =>
            * ⛔ AN EMPTY allowedDomains IS A REFUSAL, NOT AN EMPTY ROLE. `allow_any_name` is
            *   false on every live role, so a role with no allowed domains can issue NOTHING —
            *   and an unresolved or mistyped prop reads exactly like an author who meant it.
-           *   policy.ts refuses an empty fragment directory for the same reason.
+           *   policy.ts refuses an empty fragment directory for the same reason. The other
+           *   refusals — an unparseable duration, noStore with generateLease — are in `problems`.
            */
-          if (news.allowedDomains.length === 0) {
-            return yield* Effect.die(
-              new Error(
-                `Bao.PkiRole ${path}: allowedDomains is empty. With allow_any_name false ` +
-                  'that role can issue no certificate at all.',
-              ),
-            );
-          }
-          const bad = badDurations(news);
+          const bad = problems(news);
           if (bad.length > 0) {
-            return yield* Effect.die(
-              new Error(
-                `Bao.PkiRole ${path}: ${bad.map(([k, v]) => `${k}=${v}`).join(', ')} ` +
-                  'is not a duration OpenBao parses (expect 30m, 720h, 8760h or 0).',
-              ),
-            );
+            return yield* Effect.die(new Error(`Bao.PkiRole ${path}: ${bad.join(' ')}`));
           }
           const live = yield* readRole(news);
           if (live === undefined || !matches(live, news)) {

package/src/openbao/remount-wire.test.ts

@@ -0,0 +1,87 @@
+/**
+ * sys/remount and its status loop against a fake. The shapes pinned here are the CLI's own
+ * (api/sys_mounts.go:95-191): POST `{from, to}`, then poll until `success` or `failure`.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import * as Effect from 'effect/Effect';
+import { type Reply, type Seen, run, withFake } from './fake-bao.ts';
+import { RemountError, remountAndWait } from './remount-wire.ts';
+
+const STARTED = { json: { data: { migration_id: 'm-1' }, warnings: ['queued'] }, status: 200 };
+const status = (value: string): Reply => ({
+  json: {
+    data: {
+      migration_id: 'm-1',
+      migration_info: { source_mount: 'kv/', status: value, target_mount: 'kv-moved/' },
+    },
+  },
+  status: 200,
+});
+const FORGOTTEN: Reply = { json: { errors: [] }, status: 404 };
+
+/** Answer the start, then each status read from `statuses` in order (the last one repeats). */
+const script = (...statuses: Reply[]) => {
+  let polls = 0;
+  return (seen: Seen): Reply => {
+    if (seen.path === '/v1/sys/remount') return STARTED;
+    const reply = statuses[Math.min(polls, statuses.length - 1)] ?? FORGOTTEN;
+    polls += 1;
+    return reply;
+  };
+};
+
+const FAST = { attempts: 3, intervalMillis: 1 };
+const moved = (confirm = Effect.succeed(true)) => remountAndWait('kv', 'kv-moved', confirm, FAST);
+
+describe('remountAndWait', () => {
+  it('posts from/to and polls until success', async () => {
+    await withFake(script(status('in-progress'), status('success')), async (bao) => {
+      await run({ BAO_ADDR: bao.address }, moved());
+      assert.deepEqual(
+        bao.seen.map((seen) => [seen.method, seen.path, seen.body]),
+        [
+          ['POST', '/v1/sys/remount', JSON.stringify({ from: 'kv', to: 'kv-moved' })],
+          ['GET', '/v1/sys/remount/status/m-1', ''],
+          ['GET', '/v1/sys/remount/status/m-1', ''],
+        ],
+      );
+    });
+  });
+
+  it('fails a migration OpenBao reports failed, naming the id', async () => {
+    await withFake(script(status('failure')), async (bao) => {
+      await assert.rejects(run({ BAO_ADDR: bao.address }, moved()), (error: unknown) => {
+        assert.ok(error instanceof RemountError);
+        assert.match(error.message, /migration m-1\) FAILED/);
+        return true;
+      });
+    });
+  });
+
+  it('settles a forgotten migration from the mount tables, both ways', async () => {
+    await withFake(script(FORGOTTEN), async (bao) => {
+      await run({ BAO_ADDR: bao.address }, moved(Effect.succeed(true)));
+    });
+    await withFake(script(FORGOTTEN), async (bao) => {
+      await assert.rejects(
+        run({ BAO_ADDR: bao.address }, moved(Effect.succeed(false))),
+        /no longer knows the migration/,
+      );
+    });
+  });
+
+  it('gives up after the bounded number of status reads', async () => {
+    await withFake(script(status('in-progress')), async (bao) => {
+      await assert.rejects(run({ BAO_ADDR: bao.address }, moved()), /still in progress after 3/);
+      assert.equal(bao.seen.length, 4);
+    });
+  });
+
+  it('fails a start that names no migration id', async () => {
+    const answer = () => ({ json: { data: {} }, status: 200 });
+    await withFake(answer, async (bao) => {
+      await assert.rejects(run({ BAO_ADDR: bao.address }, moved()), /no migration_id/);
+    });
+  });
+});

package/src/openbao/remount-wire.ts

@@ -0,0 +1,112 @@
+/**
+ * `sys/remount` — move a secrets engine or auth method to a new path WITH its data — and the status
+ * polling it needs, because the move finishes after the call returns.
+ *
+ * ★ READ FROM openbao v2.6.2, NOT RECALLED:
+ *   · api/sys_mounts.go:95-191 — the CLI's `bao secrets move` POSTs `{from, to}` to sys/remount,
+ *     takes `data.migration_id`, then GETs sys/remount/status/<id> once a second until
+ *     `migration_info.status` is `success` or `failure`. This is that loop, bounded.
+ *   · vault/logical_system.go:1257-1357 — the handler validates, records the migration and
+ *     answers AT ONCE; a goroutine does the move. So a 200 means "queued", never "moved".
+ *   · vault/mount.go:630-735 — the mount keeps its UUID, and storage lives under the UUID, so every
+ *     secret stays. ⛔ BUT EVERY LEASE UNDER THE SOURCE IS REVOKED (`RevokePrefix`, :684): a move of
+ *     a dynamic-secrets mount kills every credential it has issued. KV has no leases.
+ *   · vault/logical_system.go:67-69 — `remount` is a sudo path. The status path is not.
+ * ⚠️ THE STATUS TRACKER IS IN MEMORY (vault/mount.go:2303-2336, a sync.Map on the active node). A
+ *   restart or leader change mid-move loses it, and the status read then answers 404. That is not a
+ *   failure and not a success; `confirm` settles it from the mount tables, or the call fails.
+ * ⛔ POLICIES ARE NOT REWRITTEN. Every ACL path naming the old mount keeps naming it.
+ */
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { baoCall, baoRead } from './bao-http.ts';
+import type { BaoError } from './bao-status.ts';
+
+/** A move OpenBao reported failed, or one this could not confirm. Never carries a token. */
+export class RemountError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RemountError';
+  }
+}
+
+export interface RemountOptions {
+  /** Milliseconds between status reads. Default 1000 — the CLI's own pace. */
+  readonly intervalMillis?: number;
+  /** Status reads before giving up. Default 120, so about two minutes. */
+  readonly attempts?: number;
+}
+
+const record = (value: unknown): Record<string, unknown> | undefined =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+
+/** POST sys/remount and return the migration id. `from`/`to` are full paths (`auth/x` for auth). */
+export const startRemount = (
+  from: string,
+  to: string,
+): Effect.Effect<string, BaoError | RemountError, HttpClient.HttpClient> =>
+  Effect.flatMap(baoCall('write', 'POST', 'sys/remount', { from, to }), (body) => {
+    const id = record(body?.['data'])?.['migration_id'];
+    return typeof id === 'string' && id !== ''
+      ? Effect.succeed(id)
+      : Effect.fail(new RemountError(`sys/remount ${from} -> ${to} answered no migration_id.`));
+  });
+
+/** `in-progress`, `success`, `failure` — or undefined when the server no longer knows the id. */
+export const remountStatus = (
+  id: string,
+): Effect.Effect<string | undefined, BaoError, HttpClient.HttpClient> =>
+  Effect.map(baoRead(`sys/remount/status/${encodeURIComponent(id)}`), (data) => {
+    if (data === undefined) return undefined;
+    const status = record(data['migration_info'])?.['status'];
+    return typeof status === 'string' ? status : 'unknown';
+  });
+
+/**
+ * Move `from` to `to` and wait until OpenBao says it is done.
+ *
+ * @param confirm answers "does the mount table show the move finished?" — asked only when the
+ *   status tracker has forgotten the id. True is success; false fails.
+ */
+export const remountAndWait = (
+  from: string,
+  to: string,
+  confirm: Effect.Effect<boolean, BaoError, HttpClient.HttpClient>,
+  options: RemountOptions = {},
+): Effect.Effect<void, BaoError | RemountError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const interval = options.intervalMillis ?? 1000;
+    const attempts = Math.max(1, options.attempts ?? 120);
+    const id = yield* startRemount(from, to);
+    const named = `sys/remount ${from} -> ${to} (migration ${id})`;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+      const status = yield* remountStatus(id);
+      if (status === 'success') return;
+      if (status === 'failure') {
+        return yield* Effect.fail(
+          new RemountError(
+            `${named} FAILED. The server log carries the reason, tagged with that migration_id. ` +
+              'Read sys/mounts (or sys/auth) before retrying: the source may be tainted.',
+          ),
+        );
+      }
+      if (status === undefined) {
+        if (yield* confirm) return;
+        return yield* Effect.fail(
+          new RemountError(
+            `${named}: the server no longer knows the migration (its tracker is in memory, lost ` +
+              'on a restart or leader change), and the mount table does not show the move done.',
+          ),
+        );
+      }
+      if (attempt < attempts) yield* Effect.sleep(interval);
+    }
+    return yield* Effect.fail(
+      new RemountError(
+        `${named} is still in progress after ${String(attempts)} status reads. Do not re-run ` +
+          `until sys/remount/status/${id} settles.`,
+      ),
+    );
+  });

package/src/openbao/role-reconcile.test.ts

@@ -0,0 +1,104 @@
+/**
+ * The shared role loop against a fake, through Bao.JwtAuthConfig — the family where `wouldErase`
+ * matters most: a live OIDC client must never be written over, because the write would erase a
+ * secret the read never shows.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { type Reply, type Seen, run, withFake } from './fake-bao.ts';
+import { jwtConfigSpec } from './jwt-config.ts';
+import { problems } from './jwt-config-form.ts';
+import { planRole, reconcileRole } from './role-reconcile.ts';
+
+const PROPS = {
+  boundIssuer: 'https://token.actions.example.com',
+  mount: 'jwt-github',
+  oidcDiscoveryUrl: 'https://token.actions.example.com',
+};
+
+const STORED = {
+  bound_issuer: 'https://token.actions.example.com',
+  default_role: '',
+  jwks_ca_pem: '',
+  jwks_url: '',
+  jwt_supported_algs: [],
+  jwt_validation_pubkeys: [],
+  namespace_in_state: true,
+  oidc_client_id: '',
+  oidc_discovery_ca_pem: '',
+  oidc_discovery_url: 'https://token.actions.example.com',
+  oidc_response_mode: '',
+  oidc_response_types: [],
+  override_allowed_server_names: null,
+  provider_config: {},
+  status: 'valid',
+};
+
+/** Reads answer from `reads` in order (the last repeats); writes answer 204. */
+const script = (...reads: Reply[]) => {
+  let count = 0;
+  return (seen: Seen): Reply => {
+    if (seen.method !== 'GET') return { status: 204 };
+    const reply = reads[Math.min(count, reads.length - 1)] ?? { status: 500 };
+    count += 1;
+    return reply;
+  };
+};
+const ABSENT: Reply = { json: { errors: [] }, status: 404 };
+const found = (data: Record<string, unknown>): Reply => ({ json: { data }, status: 200 });
+const writes = (seen: Seen[]) => seen.filter((each) => each.method !== 'GET');
+
+describe('role loop (Bao.JwtAuthConfig)', () => {
+  it('writes an absent config once, as PUT, and returns what it read back', async () => {
+    await withFake(script(ABSENT, found(STORED)), async (bao) => {
+      const attributes = await run({ BAO_ADDR: bao.address }, reconcileRole(jwtConfigSpec(PROPS)));
+      assert.equal(attributes.mount, 'jwt-github');
+      const [write] = writes(bao.seen);
+      assert.equal(write?.method, 'PUT');
+      assert.equal(write?.path, '/v1/auth/jwt-github/config');
+      assert.ok(!(write?.body ?? '').includes('oidc_client_secret'));
+    });
+  });
+
+  it('writes nothing and plans noop when live already matches', async () => {
+    await withFake(script(found(STORED)), async (bao) => {
+      assert.equal(await run({ BAO_ADDR: bao.address }, planRole(jwtConfigSpec(PROPS))), 'noop');
+      await run({ BAO_ADDR: bao.address }, reconcileRole(jwtConfigSpec(PROPS)));
+      assert.equal(writes(bao.seen).length, 0);
+    });
+  });
+
+  it('refuses to write over a live OIDC client, naming what would be erased', async () => {
+    const oidc = found({
+      ...STORED,
+      bound_issuer: 'https://old.example.com',
+      oidc_client_id: 'client-a',
+    });
+    await withFake(script(oidc), async (bao) => {
+      await assert.rejects(
+        run({ BAO_ADDR: bao.address }, reconcileRole(jwtConfigSpec(PROPS))),
+        /oidc_client_id \(and its unreadable secret\)/,
+      );
+      assert.equal(writes(bao.seen).length, 0);
+    });
+  });
+
+  it('refuses a write that reads back different', async () => {
+    const other = found({ ...STORED, bound_issuer: 'https://elsewhere.example.com' });
+    await withFake(script(ABSENT, other), async (bao) => {
+      await assert.rejects(
+        run({ BAO_ADDR: bao.address }, reconcileRole(jwtConfigSpec(PROPS))),
+        /read back different/,
+      );
+    });
+  });
+
+  it('plans update, never noop, for a declaration it would refuse', async () => {
+    const bad = { ...PROPS, jwksUrl: 'https://keys.example.com' };
+    assert.match(problems(bad).join(), /exactly one/);
+    await withFake(script(found(STORED)), async (bao) => {
+      assert.equal(await run({ BAO_ADDR: bao.address }, planRole(jwtConfigSpec(bad))), 'update');
+      assert.equal(bao.seen.length, 0);
+    });
+  });
+});

package/src/openbao/role-reconcile.ts

@@ -0,0 +1,84 @@
+/**
+ * The read / plan / reconcile loop the newer role families share (Bao.JwtRole, Bao.KubernetesRole,
+ * Bao.JwtAuthConfig): one path, one body, one comparison. Each family supplies its own form; this
+ * owns the order of operations, which is where the estate's providers have gone wrong before.
+ *
+ * ★ THE ORDER, AND WHY EACH STEP IS THERE:
+ *   1. Refuse a declaration the family knows is wrong, before any call (`problems`).
+ *   2. Read live. Write only when it differs — an identical write is still an audit line.
+ *   3. Before writing over a live object, refuse if the write would silently destroy something
+ *      this resource does not model (`wouldErase`, the ssh-role.ts pattern).
+ *   4. Re-read, and refuse unless live now MATCHES. A 2xx is not proof: the server can accept a
+ *      field and store something else (pki-role.ts has the history).
+ * ⛔ A DECLARATION reconcile WOULD REFUSE NEVER PLANS `noop` — `planRole` routes it to `update`,
+ *   so the refusal is seen at the next deploy instead of hiding behind a clean plan.
+ */
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { baoRead, baoWrite } from './bao-http.ts';
+import type { BaoError } from './bao-status.ts';
+
+export interface RoleSpec<A> {
+  /** `Bao.JwtRole` etc., for messages. */
+  readonly family: string;
+  /** The API path, e.g. `auth/jwt/role/humans`. */
+  readonly path: string;
+  readonly problems: readonly string[];
+  readonly attributesOf: (live: Record<string, unknown>) => A;
+  readonly matches: (attributes: A) => boolean;
+  readonly body: Readonly<Record<string, unknown>>;
+  /** Live fields a write would reset that the declaration does not model. */
+  readonly wouldErase?: (live: Record<string, unknown>) => readonly string[];
+}
+
+type Found<A> = { readonly attributes: A; readonly live: Record<string, unknown> };
+
+export const readRoleAt = <A>(
+  spec: RoleSpec<A>,
+): Effect.Effect<Found<A> | undefined, BaoError, HttpClient.HttpClient> =>
+  Effect.map(baoRead(spec.path), (live) =>
+    live === undefined ? undefined : { attributes: spec.attributesOf(live), live },
+  );
+
+/** `update` or `noop` — the part of a diff after the identity checks. */
+export const planRole = <A>(
+  spec: RoleSpec<A>,
+): Effect.Effect<'noop' | 'update', BaoError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    if (spec.problems.length > 0) return 'update';
+    const found = yield* readRoleAt(spec);
+    return found !== undefined && spec.matches(found.attributes) ? 'noop' : 'update';
+  });
+
+const refuse = (spec: { readonly family: string; readonly path: string }, message: string) =>
+  Effect.die(new Error(`${spec.family} ${spec.path}: ${message}`));
+
+export const reconcileRole = <A>(
+  spec: RoleSpec<A>,
+): Effect.Effect<A, BaoError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    if (spec.problems.length > 0) return yield* refuse(spec, spec.problems.join('; '));
+    const found = yield* readRoleAt(spec);
+    if (found === undefined || !spec.matches(found.attributes)) {
+      const lost = found === undefined ? [] : (spec.wouldErase?.(found.live) ?? []);
+      if (lost.length > 0) {
+        return yield* refuse(
+          spec,
+          `live carries ${lost.join(', ')}, which this resource does not declare and the write ` +
+            'would reset. Fold it into the declaration, or clear it by hand first.',
+        );
+      }
+      // ★ PUT, as `bao write` sends (api/logical.go); http/logical.go maps PUT and POST alike.
+      yield* baoWrite('PUT', spec.path, spec.body);
+    }
+    const after = yield* readRoleAt(spec);
+    if (after === undefined) return yield* refuse(spec, 'write reported success but it is absent.');
+    if (!spec.matches(after.attributes)) {
+      return yield* refuse(
+        spec,
+        'wrote cleanly but read back different — OpenBao stored something other than what was ' +
+          'declared. Read it by hand before retrying.',
+      );
+    }
+    return after.attributes;
+  });