@homeflare/alchemy 0.4.1 → 0.5.0

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

package/src/openbao/plugin.ts

@@ -0,0 +1,100 @@
+/**
+ * An OpenBao plugin catalog entry — `sys/plugins/catalog/<type>/<name>`: which binary in
+ * plugin_directory, at which SHA-256, may run as a plugin of that name. METADATA ONLY.
+ *
+ * ⛔ IT REGISTERS; IT DOES NOT DELIVER. The binary must already sit in plugin_directory. Copying it
+ *   there is a host step.
+ *   ⚠️ A MISSING FILE FAILS THE WRITE; A WRONG SHA-256 DOES NOT. setInternal (plugin_catalog.go
+ *     :1150-1230) resolves the path first, which fails loudly, but the run that would notice a
+ *     checksum mismatch is only the version probe, and that is best-effort: it logs a warning and
+ *     stores the entry anyway. The mismatch then surfaces when a mount first starts the plugin.
+ * ⛔ NO `env` PROP, AND THERE MUST NEVER BE ONE — see registerBody in plugin-form.ts. Alchemy keeps
+ *   props and attributes UNENCRYPTED in its state store (policy.ts has the reasoning).
+ * ⚠️ A NEW SHA-256 DOES NOT RESTART A RUNNING PLUGIN. setInternal writes the catalog entry and
+ *   reloads nothing, so mounts keep the old process until `sys/plugins/reload/backend` or a
+ *   restart. Reloading is an operator step, not this resource.
+ *
+ * ★ `defaultRemovalPolicy: 'retain'`. Deregistering does not check whether a mount still runs the
+ *   plugin (the ⛔ on deregisterPlugin in plugin-wire.ts), so a destroy would break that mount at its
+ *   next start. Retain also means a version bump — a REPLACE, below — leaves the old version
+ *   registered for mounts pinned to it; prune it by hand once nothing uses it.
+ */
+import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { type BaoPluginAttributes, type BaoPluginProps, matches, resolve } from './plugin-form.ts';
+import { readEntry, reconcilePlugin } from './plugin-reconcile.ts';
+import { deregisterPlugin } from './plugin-wire.ts';
+
+export type { BaoPluginAttributes, BaoPluginProps, BaoPluginType } from './plugin-form.ts';
+
+export interface BaoPlugin extends Resource<
+  'Bao.Plugin',
+  BaoPluginProps,
+  BaoPluginAttributes,
+  never,
+  HttpClient.HttpClient
+> {}
+
+export const BaoPlugin = Resource<BaoPlugin>('Bao.Plugin', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const BaoPluginProvider = () =>
+  Provider.effect(
+    BaoPlugin,
+    Effect.succeed(
+      BaoPlugin.Provider.of({
+        /**
+         * ⛔ THE CATALOG IS NOT A LIST OF THINGS THIS OWNS. It answers every builtin plugin and
+         *   every hand registration. Returning them would invite Alchemy to adopt — and then
+         *   deregister — plugins it never registered.
+         */
+        list: () => Effect.succeed([]),
+
+        read: Effect.fn(function* ({ olds }) {
+          const found = yield* readEntry(resolve(olds));
+          return found?.attributes;
+        }),
+
+        /** ⛔ IT COMPARES THE LIVE ENTRY, NOT THE STORED DIGEST — a hand re-register is drift. */
+        diff: Effect.fn(function* ({ news, output }) {
+          if (output === undefined || !isResolved(news)) return undefined;
+          const form = resolve(news);
+          /**
+           * ⛔ NAME, TYPE AND VERSION ARE THE CATALOG KEY, so changing one is a different entry,
+           *   not an edit. Writing the new key would leave the old registration in place under a
+           *   state record that no longer names it.
+           */
+          if (
+            output.name !== form.name ||
+            output.type !== form.type ||
+            output.version !== form.version
+          ) {
+            return { action: 'replace' } as const;
+          }
+          const found = yield* readEntry(form);
+          if (found === undefined) return { action: 'update' } as const;
+          return matches(found.attributes, form)
+            ? ({ action: 'noop' } as const)
+            : ({ action: 'update' } as const);
+        }),
+
+        /** The refusals — declarative, builtin, self-reported version — live in plugin-reconcile.ts. */
+        reconcile: Effect.fn(function* ({ news }) {
+          return yield* reconcilePlugin(news);
+        }),
+
+        /**
+         * ⛔ READ THE ⛔ ON deregisterPlugin FIRST: nothing checks that a mount still runs this.
+         *   Idempotent as Alchemy requires — already gone is success on the server.
+         */
+        delete: Effect.fn(function* ({ output }) {
+          yield* deregisterPlugin(output.type, output.name, output.version);
+          return undefined;
+        }),
+      }),
+    ),
+  );

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

@@ -0,0 +1,105 @@
+/**
+ * Bao.SshRole's two shapes — a user-cert role and a host-cert role — through writeBody and back
+ * through attributesOf, the round trip every plan rests on.
+ *
+ * ★ `cert_type` IS NOT A ROLE FIELD. It is a SIGN parameter, default `user` (openbao v2.6.2
+ *   builtin/logical/ssh/path_sign.go:50-54); a host-cert role is `allow_host_certificates` plus the
+ *   domain fields, and the host asks for `cert_type=host` when it signs. path_roles.go has no such
+ *   field, so nothing here sends one.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  type BaoSshRoleProps,
+  attributesOf,
+  matches,
+  resolve,
+  writeBody,
+} from './ssh-role-form.ts';
+
+const USER: BaoSshRoleProps = {
+  allowUserCertificates: true,
+  allowedUsers: ['ops', 'deploy'],
+  defaultExtensions: { 'permit-pty': '', 'permit-agent-forwarding': '' },
+  maxTtl: '16h',
+  name: 'operator',
+  ttl: '16h',
+};
+
+const HOST: BaoSshRoleProps = {
+  allowHostCertificates: true,
+  allowSubdomains: true,
+  allowedDomains: ['example.test', 'lab.example.test'],
+  allowedUsers: [],
+  maxTtl: '8760h',
+  mount: 'ssh-host/',
+  name: 'host',
+  ttl: '8760h',
+};
+
+describe('ssh role writeBody', () => {
+  it('sends the maps as JSON objects, never as JSON strings (sdk TypeMap refuses a string)', () => {
+    const body = writeBody(resolve(USER));
+    assert.deepEqual(body['default_extensions'], {
+      'permit-agent-forwarding': '',
+      'permit-pty': '',
+    });
+    assert.deepEqual(body['default_critical_options'], {});
+    assert.equal(typeof body['default_extensions'], 'object');
+  });
+
+  it('writes a user-cert role with key_type ca, sorted principals and a stated TTL', () => {
+    const body = writeBody(resolve(USER));
+    assert.equal(body['key_type'], 'ca');
+    assert.equal(body['allowed_users'], 'deploy,ops');
+    assert.equal(body['allow_user_certificates'], 'true');
+    assert.equal(body['allow_host_certificates'], 'false');
+    assert.equal(body['ttl'], '16h');
+    assert.equal('cert_type' in body, false);
+  });
+
+  it('writes a host-cert role with domains and subdomains on its own mount', () => {
+    const form = resolve(HOST);
+    const body = writeBody(form);
+    assert.equal(form.mount, 'ssh-host');
+    assert.equal(body['allow_host_certificates'], 'true');
+    assert.equal(body['allow_user_certificates'], 'false');
+    assert.equal(body['allowed_domains'], 'example.test,lab.example.test');
+    assert.equal(body['allow_subdomains'], 'true');
+    assert.equal(body['allowed_users'], '');
+  });
+});
+
+describe('ssh role round trip', () => {
+  it('matches the role OpenBao reads back — seconds, objects, comma strings', () => {
+    const live = {
+      allow_host_certificates: false,
+      allow_user_certificates: true,
+      allowed_users: 'ops,deploy',
+      default_critical_options: {},
+      default_extensions: { 'permit-agent-forwarding': '', 'permit-pty': '' },
+      key_type: 'ca',
+      max_ttl: 57600,
+      ttl: 57600,
+    };
+    const form = resolve(USER);
+    assert.equal(matches(attributesOf(form, live), form), true);
+    assert.equal(matches(attributesOf(form, { ...live, ttl: 14400 }), form), false);
+  });
+
+  it('matches a host role read back', () => {
+    const live = {
+      allow_host_certificates: true,
+      allow_subdomains: true,
+      allowed_domains: 'lab.example.test,example.test',
+      allowed_users: '',
+      default_critical_options: {},
+      default_extensions: {},
+      key_type: 'ca',
+      max_ttl: 31536000,
+      ttl: 31536000,
+    };
+    const form = resolve(HOST);
+    assert.equal(matches(attributesOf(form, live), form), true);
+  });
+});