@homeflare/alchemy 0.4.1 → 0.5.0

package/src/openbao/approle-login.test.ts

@@ -0,0 +1,200 @@
+/**
+ * appRoleLogin / revokeSelf against a fake, through the PROMISE wrappers a plain script calls — so
+ * the fetch client, the env override and the error type are all exercised, not just the Effect.
+ *
+ * ⛔ Every call passes an explicit `env`; nothing here reads the shell's BAO_ADDR or BAO_TOKEN.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { inspect } from 'node:util';
+import { BaoLoginError, appRoleLogin, revokeSelf } from './approle-login.ts';
+import { withFake } from './fake-bao.ts';
+
+const ROLE = 'role-id-fixture';
+const SECRET = 'fixturefixture';
+const AUTH = {
+  auth: {
+    accessor: 'accessor-fixture',
+    client_token: 'token-fixture',
+    lease_duration: 900,
+    policies: ['default', 'host-cert'],
+  },
+};
+
+const failure = async (pending: Promise<unknown>) => {
+  const error = await pending.then(
+    () => assert.fail('expected a rejection'),
+    (caught: unknown) => caught,
+  );
+  assert.ok(error instanceof BaoLoginError, 'rejects with BaoLoginError itself');
+  return error;
+};
+
+describe('appRoleLogin', () => {
+  it('logs in with no token header, whatever the environment holds', async () => {
+    await withFake(
+      () => ({ json: AUTH, status: 200 }),
+      async (bao) => {
+        const env = {
+          BAO_ADDR: bao.address,
+          BAO_NAMESPACE: 'example-ns',
+          BAO_TOKEN: 'operator-token',
+          VAULT_TOKEN: 'legacy-token',
+        };
+        const login = await appRoleLogin({ env, roleId: ROLE, secretId: SECRET });
+        const [seen] = bao.seen;
+        assert.equal(seen?.method, 'PUT');
+        assert.equal(seen?.path, '/v1/auth/approle/login');
+        assert.equal(seen?.body, JSON.stringify({ role_id: ROLE, secret_id: SECRET }));
+        assert.equal(seen?.headers.get('x-vault-token'), null);
+        assert.equal(seen?.headers.get('x-vault-namespace'), 'example-ns');
+        assert.equal(login.clientToken, 'token-fixture');
+        assert.equal(login.accessor, 'accessor-fixture');
+        assert.deepEqual(login.policies, ['default', 'host-cert']);
+        assert.equal(login.leaseDurationSeconds, 900);
+      },
+    );
+  });
+
+  /**
+   * ⚠️ THE PRINTS ARE THE POINT. The first version passed JSON and Object.keys checks and still
+   *   printed the token in full under bun's console.log (approle-login-result.ts has the measure).
+   */
+  it('keeps the token out of every print, JSON, spread and clone', async () => {
+    await withFake(
+      () => ({ json: AUTH, status: 200 }),
+      async (bao) => {
+        const env = { BAO_ADDR: bao.address };
+        const login = await appRoleLogin({ env, roleId: ROLE, secretId: SECRET });
+        const renderings = [
+          Bun.inspect(login),
+          inspect(login),
+          inspect(login, { showHidden: true }),
+          JSON.stringify(login),
+          JSON.stringify({ ...login }),
+          JSON.stringify(structuredClone(login)),
+        ];
+        for (const text of renderings) assert.ok(!text.includes('token-fixture'), text);
+        assert.equal(Object.keys(login).includes('clientToken'), false);
+        assert.equal(login.accessor, 'accessor-fixture');
+      },
+    );
+  });
+
+  it('logs in on a named mount', async () => {
+    await withFake(
+      () => ({ json: AUTH, status: 200 }),
+      async (bao) => {
+        const env = { BAO_ADDR: bao.address };
+        await appRoleLogin({ env, mount: '/approle-hosts/', roleId: ROLE, secretId: SECRET });
+        assert.equal(bao.seen[0]?.path, '/v1/auth/approle-hosts/login');
+      },
+    );
+  });
+
+  it('refuses empty, missing and padded inputs without sending anything', async () => {
+    await withFake(
+      () => ({ json: AUTH, status: 200 }),
+      async (bao) => {
+        const env = { BAO_ADDR: bao.address };
+        const cases = [
+          { roleId: '', secretId: SECRET },
+          { roleId: ROLE, secretId: `${SECRET}\n` },
+          { roleId: ROLE, secretId: undefined as unknown as string },
+          { mount: '/', roleId: ROLE, secretId: SECRET },
+          // ⛔ The URL parser would resolve these onto another path; nothing may be sent.
+          { mount: '../../sys/tools', roleId: ROLE, secretId: SECRET },
+          { mount: 'approle?x=', roleId: ROLE, secretId: SECRET },
+        ];
+        for (const input of cases) {
+          const error = await failure(appRoleLogin({ env, ...input }));
+          assert.equal(error.reason, 'input');
+          assert.ok(!error.message.includes(SECRET));
+        }
+        assert.equal(bao.seen.length, 0);
+      },
+    );
+  });
+
+  it('redacts a secret_id OpenBao echoes back (approle path_login.go:291)', async () => {
+    const echoed = { errors: [`invalid secret_id "${SECRET}"`] };
+    await withFake(
+      () => ({ json: echoed, status: 400 }),
+      async (bao) => {
+        const env = { BAO_ADDR: bao.address };
+        const error = await failure(appRoleLogin({ env, roleId: ROLE, secretId: SECRET }));
+        assert.equal(error.reason, 'refused');
+        assert.equal(error.status, 400);
+        assert.deepEqual(error.errors, ['invalid secret_id "[redacted]"']);
+        assert.ok(!error.message.includes(SECRET));
+      },
+    );
+  });
+
+  it('describes a non-JSON error page by size, never by content', async () => {
+    const page = `<html>502 upstream said ${SECRET}</html>`;
+    await withFake(
+      () => ({ status: 502, text: page }),
+      async (bao) => {
+        const env = { BAO_ADDR: bao.address };
+        const error = await failure(appRoleLogin({ env, roleId: ROLE, secretId: SECRET }));
+        assert.equal(error.status, 502);
+        assert.match(error.message, /not an OpenBao error body/);
+        assert.ok(!error.message.includes('upstream'));
+      },
+    );
+  });
+
+  it('names a 2xx without a usable login — not JSON, no auth block, unfinished MFA', async () => {
+    const replies = [
+      { json: { data: {} }, status: 200 },
+      {
+        json: { auth: { client_token: '', mfa_requirement: { mfa_request_id: 'x' } } },
+        status: 200,
+      },
+      // ⚠️ Some other web server at BAO_ADDR: a yes that is not a login, never `refused 200`.
+      { status: 200, text: '<html>welcome</html>' },
+    ];
+    const expected = [/no auth block/, /requires MFA/, /response 200: a success body/];
+    for (const [index, reply] of replies.entries()) {
+      await withFake(
+        () => reply,
+        async (bao) => {
+          const env = { BAO_ADDR: bao.address };
+          const error = await failure(appRoleLogin({ env, roleId: ROLE, secretId: SECRET }));
+          assert.equal(error.reason, 'response');
+          assert.match(error.message, expected[index] ?? /never/);
+        },
+      );
+    }
+  });
+});
+
+describe('revokeSelf', () => {
+  it('revokes the token it was given, not the environment one', async () => {
+    await withFake(
+      () => ({ status: 204 }),
+      async (bao) => {
+        await revokeSelf('token-fixture', { BAO_ADDR: bao.address, BAO_TOKEN: 'operator-token' });
+        const [seen] = bao.seen;
+        assert.equal(seen?.method, 'PUT');
+        assert.equal(seen?.path, '/v1/auth/token/revoke-self');
+        assert.equal(seen?.headers.get('x-vault-token'), 'token-fixture');
+      },
+    );
+  });
+
+  it('refuses an empty token and redacts a refused one', async () => {
+    await withFake(
+      () => ({ json: { errors: ['permission denied for token-fixture'] }, status: 403 }),
+      async (bao) => {
+        const env = { BAO_ADDR: bao.address };
+        assert.equal((await failure(revokeSelf('', env))).reason, 'input');
+        assert.equal(bao.seen.length, 0);
+        const refused = await failure(revokeSelf('token-fixture', env));
+        assert.equal(refused.reason, 'refused');
+        assert.ok(!refused.message.includes('token-fixture'));
+      },
+    );
+  });
+});

package/src/openbao/approle-login.ts

@@ -0,0 +1,156 @@
+/**
+ * AppRole login and self-revoke for a plain Bun script — the one part of the openbao subpath that is
+ * not a Resource.
+ *
+ * ★ WHY IT LIVES HERE. Wrapper scripts log in with a per-host AppRole and revoke the token on exit.
+ *   Each one hand-rolling a `fetch` is how two of them end up disagreeing about BAO_ADDR versus
+ *   BAO_AGENT_ADDR, or dropping the namespace header. This rides the transport every Bao.* family
+ *   already uses: bao-address.ts resolution (BAO_ADDR, BAO_AGENT_ADDR, BAO_NAMESPACE, the VAULT_*
+ *   twins, unix sockets), bao-http.ts's in-flight gate, timeout, transport retry and token
+ *   redaction on spans, and bao-status.ts's status-first classification of the answer.
+ * ★ ONE IMPLEMENTATION, TWO SHAPES. `appRoleLoginEffect` and `revokeSelfEffect` are the
+ *   implementation; `appRoleLogin` and `revokeSelf` run them on the fetch client for a caller with
+ *   no Effect runtime. Both fail with BaoLoginError and nothing else.
+ *
+ * ⚠️ SHARING A secret_id ACROSS HOSTS THROUGH A CACHING PROXY SHARES THE TOKEN. Two hosts sending
+ *   the same AppRole login through a caching OpenBao Proxy get the SAME cached token back, so two
+ *   hosts become one identity in every audit line (recorded as a trap in the 2026-09-21 vault
+ *   consolidation plan; not re-measured here). Give each host its own secret_id.
+ */
+import * as Effect from 'effect/Effect';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import type { BaoEnvironment } from './bao-address.ts';
+import { BaoEnv, baoCall } from './bao-http.ts';
+import type { BaoError } from './bao-status.ts';
+import {
+  BaoLoginError,
+  failureOf,
+  loginPath,
+  mountProblem,
+  redact,
+  refusal,
+} from './approle-login-form.ts';
+import { type AppRoleLogin, loginOf } from './approle-login-result.ts';
+
+export type { BaoLoginFailure } from './approle-login-form.ts';
+export type { AppRoleLogin } from './approle-login-result.ts';
+export { BaoLoginError };
+
+export interface AppRoleLoginInput {
+  /** The role_id. Not a secret on its own, but half of one — it is redacted from errors too. */
+  readonly roleId: string;
+  /** ⛔ The secret_id. Never logged, never in an error — see `redact`. */
+  readonly secretId: string;
+  /** The AppRole auth mount, e.g. `approle` (the default) — no `.`/`..` segments, `?` or `#`. */
+  readonly mount?: string;
+}
+
+const LOGIN = 'OpenBao AppRole login';
+const REVOKE = 'OpenBao revoke-self';
+
+const failed =
+  (operation: string, secrets: readonly string[]) =>
+  (error: BaoError): BaoLoginError =>
+    new BaoLoginError(
+      failureOf(error.status),
+      error.status,
+      redact(error.errors, secrets),
+      operation,
+    );
+
+/**
+ * Log in with a role_id and secret_id, under BaoEnv (process.env unless a caller provides one).
+ *
+ * ⛔ THE LOGIN SENDS NO TOKEN, WHATEVER THE ENVIRONMENT HOLDS. BAO_TOKEN is overridden with a
+ *   PRESENT-BUT-EMPTY value for this one call, which bao-address.ts readBaoVariable treats as
+ *   winning over VAULT_TOKEN, so headersFor omits X-Vault-Token entirely. A script that already
+ *   had an operator token exported must not send it along with a machine login.
+ * ⚠️ A DROPPED TRANSPORT IS RETRIED TWICE (bao-http.ts retryTransport, status 0 only). If the first
+ *   request reached OpenBao and only the answer was lost, the retry is a second login: one extra
+ *   token that lives until its TTL, and — for a secret_id with `secret_id_num_uses` — one extra use.
+ *   A single-use secret_id can therefore come back "invalid" on a flaky path.
+ * ★ `PUT`, THE METHOD api/logical.go:325 WriteWithContext SENDS, which is what the official Go helper
+ *   calls (api/auth/approle/approle.go:146). The docs show POST; both are the update operation.
+ */
+export const appRoleLoginEffect = (
+  input: AppRoleLoginInput,
+): Effect.Effect<AppRoleLogin, BaoLoginError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const problems = [
+      refusal('roleId', input.roleId),
+      refusal('secretId', input.secretId),
+      mountProblem(input.mount),
+    ].filter((problem): problem is string => problem !== undefined);
+    if (problems.length > 0)
+      return yield* Effect.fail(new BaoLoginError('input', 0, problems, LOGIN));
+    const env = yield* BaoEnv;
+    const body = yield* baoCall('write', 'PUT', loginPath(input.mount), {
+      role_id: input.roleId,
+      secret_id: input.secretId,
+    }).pipe(
+      Effect.provideService(BaoEnv, { ...env, BAO_TOKEN: '' }),
+      Effect.mapError(failed(LOGIN, [input.roleId, input.secretId])),
+    );
+    const read = loginOf(body);
+    if ('problem' in read) {
+      return yield* Effect.fail(new BaoLoginError('response', 0, [read.problem], LOGIN));
+    }
+    return read.login;
+  });
+
+/**
+ * Revoke `token` itself — what a wrapper runs on exit, so a login does not outlive its job.
+ *
+ * ★ `PUT auth/token/revoke-self`, READ FROM openbao v2.6.2 api/auth_token.go:318-330: the token
+ *   revoked is the one in X-Vault-Token, and the body is empty. `token` rides in that header for
+ *   this call only (BAO_TOKEN is overridden), whatever the environment holds.
+ * ⚠️ AN ALREADY-REVOKED OR EXPIRED TOKEN IS A FAILURE, NOT A NO-OP. OpenBao refuses a token it no
+ *   longer knows (permission denied — not measured here), and a refusal from the wrong server looks
+ *   the same; "I could not tell" stays an error. A wrapper that only wants best-effort cleanup on
+ *   exit can catch BaoLoginError with reason `refused`.
+ * ⚠️ NEVER THROUGH AN AGENT OR PROXY IN `use_auto_auth_token = "force"` MODE. Force overwrites the
+ *   request's token with the agent's own (bao-address.ts headersFor cites apiproxy.mdx), so this
+ *   would revoke the AGENT's token. The estate's LAN proxy runs with no auto-auth at all.
+ */
+export const revokeSelfEffect = (
+  token: string,
+): Effect.Effect<void, BaoLoginError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const problem = refusal('token', token);
+    if (problem !== undefined) {
+      return yield* Effect.fail(new BaoLoginError('input', 0, [problem], REVOKE));
+    }
+    const env = yield* BaoEnv;
+    yield* baoCall('write', 'PUT', 'auth/token/revoke-self').pipe(
+      Effect.provideService(BaoEnv, { ...env, BAO_TOKEN: token }),
+      Effect.mapError(failed(REVOKE, [token])),
+    );
+  });
+
+/**
+ * ★ `Effect.runPromise` REJECTS WITH THE FAILURE ITSELF on this Effect line (measured on
+ *   effect 4.0.0-rc.115: the rejection is `instanceof` the failed class), so a script catches
+ *   BaoLoginError directly.
+ */
+const runWith = <A>(
+  env: BaoEnvironment | undefined,
+  effect: Effect.Effect<A, BaoLoginError, HttpClient.HttpClient>,
+): Promise<A> => {
+  const scoped = env === undefined ? effect : Effect.provideService(effect, BaoEnv, env);
+  return Effect.runPromise(scoped.pipe(Effect.provide(FetchHttpClient.layer)));
+};
+
+/**
+ * `appRoleLoginEffect` for a plain script. `env` defaults to `process.env`, read at call time.
+ *
+ *     const login = await appRoleLogin({ roleId, secretId });
+ *     try { … login.clientToken … } finally { await revokeSelf(login.clientToken); }
+ */
+export const appRoleLogin = (
+  input: AppRoleLoginInput & { readonly env?: BaoEnvironment },
+): Promise<AppRoleLogin> => runWith(input.env, appRoleLoginEffect(input));
+
+/** `revokeSelfEffect` for a plain script. `env` defaults to `process.env`, read at call time. */
+export const revokeSelf = (token: string, env?: BaoEnvironment): Promise<void> =>
+  runWith(env, revokeSelfEffect(token));

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