@homeflare/alchemy 0.4.0 → 0.5.0

package/src/openbao/auth-role-form.test.ts

@@ -0,0 +1,42 @@
+/**
+ * Bao.AuthRole's secret_id TTL at the 90-day length the per-host AppRoles use.
+ *
+ * ★ `2160h` IS WHAT GOES ON THE WIRE, AND OPENBAO ACCEPTS IT. MEASURED 2026-09-21 with a Go probe of
+ *   sdk v2.6.2 framework.FieldData.Validate on the approle role fields (path_role.go:166-167,
+ *   TypeDurationSecond): `secret_id_ttl: "2160h"` validates and parses to 7776000 seconds. A role
+ *   read hands back that integer, which attributesOf renders as `90d` — the same role.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { type BaoAuthRoleProps, attributesOf, matches, writeBody } from './auth-role-form.ts';
+
+const PROPS: BaoAuthRoleProps = {
+  bindSecretId: true,
+  name: 'host-cert',
+  secretIdNumUses: 0,
+  secretIdTtl: '2160h',
+  tokenMaxTtl: '1h',
+  tokenPolicies: ['host-cert', 'default'],
+  tokenTtl: '15m',
+};
+
+describe('auth role secret_id TTL', () => {
+  it('writes 2160h as given', () => {
+    assert.equal(writeBody(PROPS)['secret_id_ttl'], '2160h');
+  });
+
+  it('reads 7776000 seconds back as the same role', () => {
+    const live = {
+      bind_secret_id: true,
+      secret_id_num_uses: 0,
+      secret_id_ttl: 7776000,
+      token_max_ttl: 3600,
+      token_policies: ['default', 'host-cert'],
+      token_ttl: 900,
+    };
+    const attributes = attributesOf(PROPS, live);
+    assert.equal(attributes.secretIdTtl, '90d');
+    assert.equal(matches(attributes, PROPS), true);
+    assert.equal(matches(attributesOf(PROPS, { ...live, secret_id_ttl: 0 }), PROPS), false);
+  });
+});

package/src/openbao/bao-http.ts

@@ -190,6 +190,8 @@ export const baoRead = (path: string) =>
  * ⚠️ ROLE BODIES STAY ALL-STRING ON PURPOSE. `bao write k=v` put every value in the JSON body as a
  *   string — MEASURED with `-output-curl-string`, see ssh-role-form.ts — and the form files still
  *   build exactly that body, so the server parses the same request it was always sent.
+ *   ⛔ EXCEPT A MAP FIELD: sdk v2.6.2 refuses a string for a TypeMap with a 400, so Bao.SshRole
+ *   sends its two maps as objects (the ⛔ on mapValue in ssh-role-form.ts, measured 2026-09-21).
  */
 export const baoWrite = (
   method: 'POST' | 'PUT',

package/src/openbao/index.ts

@@ -7,7 +7,18 @@
  *   every helper as API and make the next refactor a breaking change.
  * ★ Anything unlisted is still reachable by path if you genuinely need it — that is a
  *   deliberate, visible act rather than an accident of barrelling.
+ * ★ THE APPROLE LOGIN IS HERE FOR SCRIPTS, NOT STACKS (approle-login.ts). A wrapper that logs in
+ *   and revokes on exit needs it, and giving it the families' own transport is what keeps a script
+ *   and a stack from disagreeing about which server BAO_ADDR means.
  */
+export type { AppRoleLogin, AppRoleLoginInput, BaoLoginFailure } from './approle-login.ts';
+export {
+  BaoLoginError,
+  appRoleLogin,
+  appRoleLoginEffect,
+  revokeSelf,
+  revokeSelfEffect,
+} from './approle-login.ts';
 export { BaoAuthMethod, BaoAuthMethodProvider } from './auth-method.ts';
 export { BaoAuthRole, BaoAuthRoleProvider } from './auth-role.ts';
 export { BaoCloudflareRole, BaoCloudflareRoleProvider } from './cloudflare-role.ts';
@@ -22,6 +33,8 @@ export type { RolesConfig, SurfaceSpec } from './cloudflare-roles-config.ts';
 export { parseRolesConfig } from './cloudflare-roles-config.ts';
 export { BaoMount, BaoMountProvider } from './mount.ts';
 export { BaoPkiRole, BaoPkiRoleProvider } from './pki-role.ts';
+export type { BaoPluginProps, BaoPluginType } from './plugin.ts';
+export { BaoPlugin, BaoPluginProvider } from './plugin.ts';
 export { BaoPolicy, BaoPolicyProvider } from './policy.ts';
 export { BaoProxmoxRole, BaoProxmoxRoleProvider } from './proxmox-role.ts';
 export { BaoSshRole, BaoSshRoleProvider } from './ssh-role.ts';

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

@@ -0,0 +1,23 @@
+/**
+ * Slash trimming stays linear on caller input (CodeQL js/polynomial-redos).
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { trimSlashes, trimTrailingSlashes } from './mount-path.ts';
+
+describe('mount-path', () => {
+  it('trims outer slashes and keeps inner ones', () => {
+    assert.equal(trimSlashes('/team/approle/'), 'team/approle');
+    assert.equal(trimSlashes('///'), '');
+    assert.equal(trimTrailingSlashes('/ssh-host//'), '/ssh-host');
+    assert.equal(trimTrailingSlashes('ssh'), 'ssh');
+  });
+
+  it('handles a long run of slashes before other text in linear time', () => {
+    const run = '/'.repeat(200_000);
+    const started = performance.now();
+    assert.equal(trimTrailingSlashes(`${run}x`), `${run}x`);
+    assert.equal(trimSlashes(`${run}x${run}`), 'x');
+    assert.ok(performance.now() - started < 1_000, 'slash trimming took over a second');
+  });
+});

package/src/openbao/mount-path.ts

@@ -0,0 +1,25 @@
+/**
+ * Slash trimming for caller-supplied mount paths.
+ *
+ * ★ 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.
+ */
+
+/** `text` without trailing `/`. */
+export const trimTrailingSlashes = (text: string): string => {
+  let end = text.length;
+  while (end > 0 && text[end - 1] === '/') end -= 1;
+  return text.slice(0, end);
+};
+
+/** `text` without leading or trailing `/`. */
+export const trimSlashes = (text: string): string => {
+  let start = 0;
+  while (start < text.length && text[start] === '/') start += 1;
+  return trimTrailingSlashes(text.slice(start));
+};
+
+/** 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-wire.test.ts

@@ -93,6 +93,19 @@ describe('enable, tune, disable', () => {
     );
   });
 
+  it('enables an ssh engine at any path — type is a free string, sent as given', async () => {
+    await withFake(
+      () => ({ status: 204 }),
+      async (bao) => {
+        await run({ BAO_ADDR: bao.address }, enableMount({ path: 'ssh-host/', type: 'ssh' }));
+        assert.deepEqual(
+          bao.seen.map((seen) => [seen.method, seen.path, seen.body]),
+          [['POST', '/v1/sys/mounts/ssh-host', JSON.stringify({ type: 'ssh' })]],
+        );
+      },
+    );
+  });
+
   it('fails a refused enable with OpenBao errors', async () => {
     await withFake(
       () => ({ json: { errors: ['path is already in use at kv/'] }, status: 400 }),

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);
+    });
+  });
+});