@homeflare/alchemy 0.4.1 → 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/plugin-form.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Bao.Plugin's form: what a declaration may say, the body it registers with, and the equality a
+ * plan's `noop` rests on. The shapes are the v2.6.2 handler's (plugin-form.ts cites the lines).
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  type BaoPluginProps,
+  attributesOf,
+  matches,
+  problems,
+  registerBody,
+  resolve,
+  versionedPath,
+} from './plugin-form.ts';
+
+const SUM = '0123456789abcdef'.repeat(4);
+const UNVERSIONED: BaoPluginProps = {
+  command: 'openbao-plugin-secrets-cloudflare',
+  name: 'openbao-plugin-secrets-cloudflare',
+  sha256: SUM.toUpperCase(),
+  type: 'secret',
+};
+const PROPS: BaoPluginProps = { ...UNVERSIONED, version: 'v0.1.2' };
+
+describe('plugin form', () => {
+  it('resolves the defaults the register call stores, and lower-cases the sum', () => {
+    const form = resolve(UNVERSIONED);
+    assert.equal(form.sha256, SUM);
+    assert.deepEqual(form.args, []);
+    assert.equal(form.version, '');
+    assert.deepEqual(problems(resolve(PROPS)), []);
+  });
+
+  it('refuses what the server would reject or store differently', () => {
+    const bad = (patch: Partial<BaoPluginProps>) => problems(resolve({ ...PROPS, ...patch }));
+    for (const name of ['a/b', '..x', '', 'has space']) assert.equal(bad({ name }).length, 1);
+    assert.equal(bad({ sha256: 'abc' }).length, 1);
+    for (const command of ['plugin --flag', 'sub/plugin', '/abs/plugin', '../plugin', './plugin']) {
+      assert.equal(bad({ command }).length, 1, command);
+    }
+    // ⚠️ Accepted by the server but stored canonicalised, so they would never read back equal.
+    for (const version of ['1.2.0', 'v1.2', 'v01.2.0']) assert.equal(bad({ version }).length, 1);
+    assert.ok(bad({ version: 'v1.2.0+builtin' }).length > 0);
+    assert.deepEqual(bad({ version: 'v1.2.0-rc.1' }), []);
+  });
+
+  it('reads and deletes one version, and registers at the unversioned path', () => {
+    assert.equal(
+      versionedPath('secret', 'x', 'v1.0.0+meta'),
+      'sys/plugins/catalog/secret/x?version=v1.0.0%2Bmeta',
+    );
+    assert.equal(versionedPath('auth', 'x', ''), 'sys/plugins/catalog/auth/x');
+  });
+
+  it('registers with the RegisterPluginInput fields and never env or a numeric type', () => {
+    assert.deepEqual(registerBody(resolve(PROPS)), {
+      command: PROPS.command,
+      sha256: SUM,
+      version: 'v0.1.2',
+    });
+    const withArgs = registerBody(resolve({ ...UNVERSIONED, args: ['--b', '--a'] }));
+    assert.deepEqual(withArgs, { args: ['--b', '--a'], command: PROPS.command, sha256: SUM });
+    assert.equal('env' in withArgs || 'type' in withArgs, false);
+  });
+
+  it('matches the live entry by value, args in order, and never a builtin', () => {
+    const form = resolve({ ...PROPS, args: ['--a', '--b'] });
+    const live = {
+      args: ['--a', '--b'],
+      builtin: false,
+      command: PROPS.command,
+      declarative: false,
+      name: PROPS.name,
+      oci: false,
+      sha256: SUM,
+      version: 'v0.1.2',
+    };
+    assert.equal(matches(attributesOf(form, live), form), true);
+    assert.equal(matches(attributesOf(form, { ...live, args: ['--b', '--a'] }), form), false);
+    assert.equal(matches(attributesOf(form, { ...live, sha256: 'f'.repeat(64) }), form), false);
+    assert.equal(matches(attributesOf(form, { ...live, builtin: true }), form), false);
+    const bare = resolve(UNVERSIONED);
+    assert.deepEqual(attributesOf(bare, { ...live, args: null, version: '' }).args, []);
+  });
+});

package/src/openbao/plugin-form.ts

@@ -0,0 +1,164 @@
+/**
+ * The form half of Bao.Plugin: props, the paths, the register body, and the equality that decides
+ * whether a plan says `noop`. Split from plugin.ts the way mount-form.ts is.
+ *
+ * ★ THE CATALOG API, READ FROM openbao v2.6.2 — the docs AND the server, because they disagree:
+ *   · docs/api/system/plugins-catalog.mdx — `POST sys/plugins/catalog/:type/:name` registers with
+ *     `sha256`, `command`, `args`, `env`, `version`, `oci`; `GET` and `DELETE` take `?version=`, which
+ *     is REQUIRED to read a plugin registered with one. All three need `sudo`.
+ *   · vault/logical_system.go:515-576 handlePluginCatalogRead — answers `name`, `args`, `command`
+ *     (relative to plugin_directory), `sha256`, `builtin`, `version`, `oci`, `declarative`. ⚠️ The
+ *     docs' sample shows sha256 as BASE64; the server writes `hex.EncodeToString` (:561). Hex wins.
+ *   · vault/logical_system.go:441-513 handlePluginCatalogUpdate, and :615-628 getVersion — the
+ *     version is canonicalised to `"v" + semver.String()` before it is stored.
+ */
+import { sha256 as digestOf } from './digest.ts';
+
+export type BaoPluginType = 'auth' | 'database' | 'secret';
+
+export interface BaoPluginProps {
+  /** Catalog name — what a mount's `type` names, e.g. `openbao-plugin-secrets-cloudflare`. */
+  name: string;
+  /** Catalog type. `secret` for a secrets engine, `auth` for an auth method. */
+  type: BaoPluginType;
+  /** Hex SHA-256 of the binary already sitting in plugin_directory. Case is normalised. */
+  sha256: string;
+  /** The binary's file name inside plugin_directory — a bare name, no path, no arguments. */
+  command: string;
+  /**
+   * Canonical semver with its `v`, e.g. `v0.1.2`. ⚠️ When the binary reports its own version,
+   * declare EXACTLY that one: any other is refused at write ("plugin version mismatch",
+   * plugin_catalog.go setInternal), and none at all is filed under the reported one — see the ⚠️
+   * on SELF_REPORTED in plugin-reconcile.ts.
+   */
+  version?: string;
+  /** Arguments, in order. ⛔ Never a secret: they land in Alchemy state and in every catalog read. */
+  args?: readonly string[];
+}
+
+/** ⛔ NO SECRET HERE — names, a hash, a file name, arguments and a digest. */
+export interface BaoPluginAttributes {
+  name: string;
+  type: BaoPluginType;
+  /** The canonical version the catalog stored, `''` when unversioned. Delete needs it. */
+  version: string;
+  sha256: string;
+  command: string;
+  args: readonly string[];
+  /** True when the catalog answered with OpenBao's own builtin rather than a registration. */
+  builtin: boolean;
+  /** SHA-256 of the managed fields — safe to persist; see policy.ts. */
+  digest: string;
+}
+
+/** Every prop resolved to what the register call will store. */
+export type BaoPluginForm = Required<BaoPluginProps>;
+
+export const resolve = (props: BaoPluginProps): BaoPluginForm => ({
+  args: props.args ?? [],
+  command: props.command,
+  name: props.name,
+  sha256: props.sha256.toLowerCase(),
+  type: props.type,
+  version: props.version ?? '',
+});
+
+/**
+ * ⛔ THE VERSION MUST ALREADY BE CANONICAL, OR THE PLAN NEVER GOES GREEN. The server stores
+ *   `"v" + semver.String()` (getVersion, :615-628), so `1.2.0`, `v1.2` and `v01.2.0` are all
+ *   written as `v1.2.0`, read back as `v1.2.0`, and compared unequal to the declaration forever.
+ *   Refusing anything but the canonical spelling is cheaper than reimplementing go-version.
+ */
+const CANONICAL_VERSION =
+  /^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$/;
+
+/** Everything wrong with the declaration, or `[]`. Checked before any request. */
+export const problems = (form: BaoPluginForm): readonly string[] => {
+  const found: string[] = [];
+  // ⚠️ The route is `(?P<name>.+)` (logical_system_paths.go:1697), so a `/` would nest the storage
+  //   key; the server refuses `..` in a name (plugin_catalog.go Set).
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(form.name) || form.name.includes('..')) {
+    found.push(`name ${JSON.stringify(form.name)} is not a plain catalog name`);
+  }
+  if (!/^[0-9a-f]{64}$/.test(form.sha256)) found.push('sha256 is not 64 hex characters');
+  /**
+   * ⛔ A BARE FILE NAME. The server splits `command` on spaces and keeps the rest as args
+   *   (handlePluginCatalogUpdate :487-495), and refuses a binary whose directory is not
+   *   plugin_directory itself (plugin_catalog.go setInternal, `symAbs != c.directory`) — so a
+   *   path or an argument here either fails the write or reads back as something else.
+   */
+  if (!/^[A-Za-z0-9][A-Za-z0-9._+-]*$/.test(form.command) || form.command.includes('..')) {
+    found.push(`command ${JSON.stringify(form.command)} is not a bare file name`);
+  }
+  if (form.version !== '' && !CANONICAL_VERSION.test(form.version)) {
+    found.push(`version ${JSON.stringify(form.version)} is not canonical semver like v1.2.0`);
+  }
+  // ⚠️ `+builtin` metadata is reserved; the server refuses it (handlePluginCatalogUpdate :462-464).
+  if (/\+builtin/.test(form.version)) found.push('version metadata `builtin` is reserved');
+  return found;
+};
+
+/** `?version=` only when there is one — an unversioned plugin is read without it. */
+const versionQuery = (version: string) =>
+  version === '' ? '' : `?version=${encodeURIComponent(version)}`;
+
+/** `sys/plugins/catalog/<type>/<name>` — register addresses the plugin here. */
+export const catalogPath = (type: BaoPluginType, name: string): string =>
+  `sys/plugins/catalog/${type}/${name}`;
+
+/** Read and delete address one VERSION of the plugin. */
+export const versionedPath = (type: BaoPluginType, name: string, version: string): string =>
+  `${catalogPath(type, name)}${versionQuery(version)}`;
+
+/**
+ * The register body — the fields RegisterPluginInput sends (api v2.6.0 sys_plugins.go:186-204),
+ * which is what `bao plugin register` sends.
+ *
+ * ★ `type` IS LEFT OUT OF THE BODY ON PURPOSE. The Go client puts it there as a NUMBER (PluginType
+ *   has no MarshalJSON), and the route's `type` capture is what the handler reads. The path says it.
+ * ⛔ NO `env`, EVER. The catalog read never returns env (handlePluginCatalogRead's data map has no
+ *   such key), so a declared env could not be diffed, and what env exists to carry into a plugin
+ *   process is exactly what must not sit in Alchemy's unencrypted state. ⚠️ The register call is a
+ *   FULL REPLACE (setInternal builds a fresh entry), so an env someone set by hand is dropped by
+ *   the next write — which only happens when a managed field has drifted.
+ */
+export const registerBody = (form: BaoPluginForm): Record<string, unknown> => ({
+  command: form.command,
+  sha256: form.sha256,
+  ...(form.args.length > 0 ? { args: form.args } : {}),
+  ...(form.version === '' ? {} : { version: form.version }),
+});
+
+const text = (value: unknown) => (typeof value === 'string' ? value : '');
+
+/** ⚠️ `args` is a Go slice, so an entry stored without any can read back `null` — the same as `[]`. */
+const list = (value: unknown): readonly string[] =>
+  Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
+
+export const attributesOf = (
+  form: BaoPluginForm,
+  live: Record<string, unknown>,
+): BaoPluginAttributes => {
+  const attrs = {
+    name: form.name,
+    type: form.type,
+    version: text(live['version']),
+    sha256: text(live['sha256']).toLowerCase(),
+    command: text(live['command']),
+    args: list(live['args']),
+    builtin: live['builtin'] === true,
+  };
+  return { ...attrs, digest: digestOf(JSON.stringify(attrs)) };
+};
+
+/** ⚠️ ORDER MATTERS for args — they are an argv, not a set. */
+const sameArgs = (want: readonly string[], have: readonly string[]) =>
+  want.length === have.length && want.every((entry, index) => entry === have[index]);
+
+/** True when the catalog already holds exactly this registration. A builtin never matches. */
+export const matches = (attributes: BaoPluginAttributes, form: BaoPluginForm): boolean =>
+  !attributes.builtin &&
+  attributes.version === form.version &&
+  attributes.sha256 === form.sha256 &&
+  attributes.command === form.command &&
+  sameArgs(form.args, attributes.args);

package/src/openbao/plugin-reconcile.ts

@@ -0,0 +1,92 @@
+/**
+ * Bao.Plugin's read and reconcile, as plain effects — split from plugin.ts so the refusals below can
+ * be run against a fake server rather than only reasoned about.
+ */
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import type { BaoError } from './bao-status.ts';
+import {
+  type BaoPluginAttributes,
+  type BaoPluginForm,
+  type BaoPluginProps,
+  attributesOf,
+  matches,
+  problems,
+  resolve,
+  versionedPath,
+} from './plugin-form.ts';
+import { readPluginData, registerPlugin } from './plugin-wire.ts';
+
+type Entry = { readonly attributes: BaoPluginAttributes; readonly live: Record<string, unknown> };
+
+/** Live entry, plus the raw body — reconcile needs the raw half for `oci` and `declarative`. */
+export const readEntry = (
+  form: BaoPluginForm,
+): Effect.Effect<Entry | undefined, BaoError, HttpClient.HttpClient> =>
+  Effect.map(readPluginData(form), (live) =>
+    live === undefined ? undefined : { attributes: attributesOf(form, live), live },
+  );
+
+const refuse = (form: BaoPluginForm, message: string) =>
+  Effect.die(
+    new Error(`Bao.Plugin ${versionedPath(form.type, form.name, form.version)}: ${message}`),
+  );
+
+/**
+ * ⚠️ AN UNVERSIONED REGISTRATION OF A BINARY THAT REPORTS ITS OWN VERSION IS FILED UNDER THAT
+ *   VERSION. setInternal (plugin_catalog.go:1222-1228) takes the self-reported version when the
+ *   request names none, and the storage key carries it — so the unversioned read that follows finds
+ *   nothing, or finds an OLDER genuinely-unversioned entry. The Cloudflare engine reports one
+ *   (`framework.Backend.RunningVersion`). REASONED FROM SOURCE, not measured against a server.
+ * ⚠️ THE WRITE HAS ALREADY LANDED when this fires, so the catalog holds a registration no state
+ *   record names. Declaring the reported version adopts it on the next deploy (same sha256 and
+ *   command, so reconcile matches and writes nothing); declaring a DIFFERENT version is refused by
+ *   the server itself (setInternal :1219-1221, "plugin version mismatch").
+ */
+const SELF_REPORTED =
+  'the write succeeded but the read-back does not match. If the binary reports its own version, ' +
+  'OpenBao filed the registration under it (plugin_catalog.go setInternal) — declare `version` ' +
+  'as exactly the version the binary reports; that adopts the entry this write just made.';
+
+/** Register when the live entry differs, then prove it by reading back. Dies on a refusal. */
+export const reconcilePlugin = (
+  props: BaoPluginProps,
+): Effect.Effect<BaoPluginAttributes, BaoError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const form = resolve(props);
+    const bad = problems(form);
+    if (bad.length > 0) return yield* refuse(form, bad.join('; '));
+
+    const found = yield* readEntry(form);
+    if (found !== undefined && !matches(found.attributes, form)) {
+      /**
+       * ⛔ A DECLARATIVE OR OCI ENTRY BELONGS TO THE SERVER'S CONFIG FILE (`plugin` stanzas with
+       *   plugin_auto_register), which re-registers it on every plugin reload. An API write turns
+       *   it non-declarative, and the next reload then REFUSES the config entry: "conflicts with
+       *   existing non-declarative plugin" (plugin_catalog.go:333-336).
+       */
+      if (found.live['declarative'] === true || found.live['oci'] === true) {
+        return yield* refuse(
+          form,
+          'the live entry is declarative/OCI; manage it in server config.',
+        );
+      }
+      /**
+       * ⛔ AN UNVERSIONED WRITE OVER A BUILTIN SHADOWS IT FOR EVERY MOUNT OF THAT TYPE. The catalog
+       *   answered with OpenBao's own builtin (`builtin: true`), and get() returns an external entry
+       *   before it ever looks at builtins (plugin_catalog.go:982-1036). Register a versioned plugin
+       *   instead, which leaves the builtin where it is.
+       */
+      if (found.attributes.builtin) {
+        return yield* refuse(form, 'this name is a builtin; an unversioned write would shadow it.');
+      }
+    }
+    if (found === undefined || !matches(found.attributes, form)) yield* registerPlugin(form);
+
+    // ⚠️ RE-READ AND COMPARE, never echo the declaration — see SELF_REPORTED above.
+    const after = yield* readEntry(form);
+    if (after === undefined || !matches(after.attributes, form)) {
+      return yield* refuse(form, SELF_REPORTED);
+    }
+    return after.attributes;
+  });

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

@@ -0,0 +1,146 @@
+/**
+ * Bao.Plugin's calls and reconcile against a fake. The parts worth pinning are the ones the source
+ * read turned up: a missing entry is a real 404, a builtin answers at an unversioned name, a
+ * declarative entry belongs to config, and a self-versioning binary is filed under its own version.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { BaoError } from './bao-status.ts';
+import { type Reply, type Seen, run, runFailure, withFake } from './fake-bao.ts';
+import { type BaoPluginProps, resolve } from './plugin-form.ts';
+import { reconcilePlugin } from './plugin-reconcile.ts';
+import { deregisterPlugin, readPluginData, registerPlugin } from './plugin-wire.ts';
+
+const SUM = '0123456789abcdef'.repeat(4);
+const UNVERSIONED: BaoPluginProps = {
+  command: 'openbao-plugin-secrets-cloudflare',
+  name: 'openbao-plugin-secrets-cloudflare',
+  sha256: SUM,
+  type: 'secret',
+};
+const PROPS: BaoPluginProps = { ...UNVERSIONED, version: 'v0.1.2' };
+const FORM = resolve(PROPS);
+const PATH = '/v1/sys/plugins/catalog/secret/openbao-plugin-secrets-cloudflare';
+const ENTRY = {
+  args: [],
+  builtin: false,
+  command: PROPS.command,
+  declarative: false,
+  name: PROPS.name,
+  oci: false,
+  sha256: SUM,
+  version: 'v0.1.2',
+};
+const ABSENT = { json: { errors: [] }, status: 404 };
+const found = (data: Record<string, unknown>) => ({ json: { data }, status: 200 });
+
+/** A catalog that answers reads with `before` until a PUT lands, and with `after` from then on. */
+const catalog = (before: Reply, after: Reply = found(ENTRY)) => {
+  let registered = false;
+  return (seen: Seen) => {
+    if (seen.method === 'PUT') {
+      registered = true;
+      return { status: 204 };
+    }
+    return registered ? after : before;
+  };
+};
+
+const writes = (seen: Seen[]) => seen.filter((entry) => entry.method !== 'GET');
+
+describe('plugin wire', () => {
+  it('reads a missing entry as absent, and a refused read as an error', async () => {
+    await withFake(
+      () => ABSENT,
+      async (bao) => {
+        assert.equal(await run({ BAO_ADDR: bao.address }, readPluginData(FORM)), undefined);
+        assert.equal(bao.seen[0]?.path, `${PATH}?version=v0.1.2`);
+      },
+    );
+    await withFake(
+      () => ({ json: { errors: ['permission denied'] }, status: 403 }),
+      async (bao) => {
+        const error = await runFailure({ BAO_ADDR: bao.address }, readPluginData(FORM));
+        assert.ok(error instanceof BaoError && error.status === 403);
+      },
+    );
+  });
+
+  it('registers and deregisters at the paths `bao plugin` uses', async () => {
+    await withFake(
+      () => ({ status: 204 }),
+      async (bao) => {
+        const env = { BAO_ADDR: bao.address };
+        await run(env, registerPlugin(FORM));
+        await run(env, deregisterPlugin('secret', PROPS.name, 'v0.1.2'));
+        assert.deepEqual(
+          bao.seen.map((seen) => [seen.method, seen.path, seen.body]),
+          [
+            [
+              'PUT',
+              PATH,
+              JSON.stringify({ command: PROPS.command, sha256: SUM, version: 'v0.1.2' }),
+            ],
+            ['DELETE', `${PATH}?version=v0.1.2`, ''],
+          ],
+        );
+      },
+    );
+  });
+});
+
+describe('reconcilePlugin', () => {
+  it('registers a missing plugin and returns what it read back', async () => {
+    await withFake(catalog(ABSENT), async (bao) => {
+      const attributes = await run({ BAO_ADDR: bao.address }, reconcilePlugin(PROPS));
+      assert.equal(attributes.version, 'v0.1.2');
+      assert.equal(writes(bao.seen).length, 1);
+    });
+  });
+
+  it('writes nothing when the live entry already matches', async () => {
+    await withFake(catalog(found(ENTRY)), async (bao) => {
+      await run({ BAO_ADDR: bao.address }, reconcilePlugin(PROPS));
+      assert.equal(writes(bao.seen).length, 0);
+    });
+  });
+
+  it('refuses to overwrite a declarative entry or shadow a builtin', async () => {
+    const cases = [
+      { live: found({ ...ENTRY, declarative: true, sha256: 'f'.repeat(64) }), props: PROPS },
+      {
+        live: found({ builtin: true, command: '', name: 'kv', sha256: '', version: 'v2.6.2' }),
+        props: { ...UNVERSIONED, name: 'kv' },
+      },
+    ];
+    for (const [index, { live, props }] of cases.entries()) {
+      await withFake(catalog(live), async (bao) => {
+        await assert.rejects(
+          run({ BAO_ADDR: bao.address }, reconcilePlugin(props)),
+          index === 0 ? /declarative/ : /builtin/,
+        );
+        assert.equal(writes(bao.seen).length, 0);
+      });
+    }
+  });
+
+  it('names the self-reported version when an unversioned write reads back as nothing', async () => {
+    await withFake(catalog(ABSENT, ABSENT), async (bao) => {
+      await assert.rejects(
+        run({ BAO_ADDR: bao.address }, reconcilePlugin(UNVERSIONED)),
+        /declare `version`/,
+      );
+      assert.equal(writes(bao.seen).length, 1);
+    });
+  });
+
+  it('refuses a bad declaration before sending anything', async () => {
+    await withFake(catalog(ABSENT), async (bao) => {
+      await assert.rejects(
+        run({ BAO_ADDR: bao.address }, reconcilePlugin({ ...PROPS, version: '0.1.2' })),
+        /canonical semver/,
+      );
+      assert.equal(bao.seen.length, 0);
+    });
+  });
+});

package/src/openbao/plugin-wire.ts

@@ -0,0 +1,65 @@
+/**
+ * The OpenBao calls Bao.Plugin makes — read one catalog entry, register, deregister. Split from
+ * plugin.ts so the calls can be pinned against a fake server, the way mount-wire.ts is.
+ *
+ * ★ ENDPOINTS, READ FROM openbao v2.6.2 api/sys_plugins.go (the client `bao plugin` uses) and the
+ *   handlers in vault/logical_system.go:
+ *     read        GET    sys/plugins/catalog/<type>/<name>[?version=]  (GetPlugin, :159-183)
+ *     register    PUT    sys/plugins/catalog/<type>/<name>             (RegisterPlugin, :212-228)
+ *     deregister  DELETE sys/plugins/catalog/<type>/<name>[?version=]  (DeregisterPlugin, :249-261)
+ *   (api/sys_plugins.go diffed identical between v2.6.0 and v2.6.2.)
+ * ⚠️ ALL THREE NEED `sudo` ON THE PATH, not just the verb (docs/api/system/plugins-catalog.mdx). A
+ *   token without it reads as 403, which is an error here, never "absent".
+ */
+import type * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { baoDelete, baoRead, baoWrite } from './bao-http.ts';
+import type { BaoError } from './bao-status.ts';
+import {
+  type BaoPluginForm,
+  type BaoPluginType,
+  catalogPath,
+  registerBody,
+  versionedPath,
+} from './plugin-form.ts';
+
+/**
+ * One catalog entry, or undefined when the catalog has none at that name, type and version.
+ *
+ * ★ UNLIKE A MOUNT, A MISSING PLUGIN REALLY IS A 404. handlePluginCatalogRead returns `nil, nil` when
+ *   the catalog lookup finds nothing (vault/logical_system.go:545-547), and RespondErrorCommon turns
+ *   a nil READ response into 404 (sdk v2.6.2 logical/response_util.go:23-26). No second question is
+ *   needed, unlike the mount-table check in mount-wire.ts.
+ * ⚠️ A BUILTIN ANSWERS TOO. With no external registration at an unversioned name, the catalog falls
+ *   through to OpenBao's own builtin of that name and type (plugin_catalog.go get, :1016-1036), which
+ *   reads back with `builtin: true` — present, but not a registration. plugin.ts decides what that
+ *   means.
+ */
+export const readPluginData = (
+  form: BaoPluginForm,
+): Effect.Effect<Record<string, unknown> | undefined, BaoError, HttpClient.HttpClient> =>
+  baoRead(versionedPath(form.type, form.name, form.version));
+
+export const registerPlugin = (
+  form: BaoPluginForm,
+): Effect.Effect<void, BaoError, HttpClient.HttpClient> =>
+  baoWrite('PUT', catalogPath(form.type, form.name), registerBody(form));
+
+/**
+ * ★ IDEMPOTENT ON THE SERVER. deleteInternal deletes the storage key whether or not it exists
+ *   (plugin_catalog.go:1272-1284) and the handler answers with no body, so a retried delete succeeds.
+ *   ⚠️ BUT A MISSING TYPED KEY FALLS BACK TO THE BARE NAME. When `<type>/<name>[/<version>]` is not
+ *     in storage, the same function deletes the key `<name>` instead — where registrations made
+ *     before plugin types existed live, whatever their type. A fresh 2.x vault has none; one
+ *     migrated from an old Vault may. REASONED FROM SOURCE, not run.
+ * ⛔ AND THAT IS THE DANGER: NOTHING CHECKS WHETHER A MOUNT STILL USES THE PLUGIN. The same function
+ *   has no mount lookup at all, so deregistering the plugin a live mount runs succeeds. The running
+ *   process is not killed by it; the mount breaks the next time OpenBao has to START the plugin — a
+ *   reload, a restart, an unseal — long after the plan that did it. REASONED FROM SOURCE, not run.
+ */
+export const deregisterPlugin = (
+  type: BaoPluginType,
+  name: string,
+  version: string,
+): Effect.Effect<void, BaoError, HttpClient.HttpClient> =>
+  baoDelete(versionedPath(type, name, version));