@homeflare/alchemy 0.4.1 → 0.6.0

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/remount-wire.test.ts

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

package/src/openbao/remount-wire.ts

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

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

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

package/src/openbao/role-reconcile.ts

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

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

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

@@ -13,6 +13,7 @@
  */
 import { sha256 } from './digest.ts';
 import { parseDuration, ttlSeconds } from './mount-form.ts';
+import { sshMountOf as mountOf } from './mount-path.ts';
 
 export interface BaoSshRoleProps {
   /** Role name, as `<mount>/roles/{name}` takes it. */
@@ -76,8 +77,7 @@ export interface BaoSshRoleAttributes extends Omit<BaoSshRoleForm, 'maxTtl' | 't
   digest: string;
 }
 
-/** Mount path without a trailing slash; `ssh` when the caller did not say. */
-export const mountOf = (mount: string | undefined) => (mount ?? 'ssh').replace(/\/+$/, '');
+export { mountOf };
 
 export const readPath = (mount: string | undefined, name: string) =>
   `${mountOf(mount)}/roles/${name}`;
@@ -159,26 +159,28 @@ export const attributesOf = (
 };
 
 /**
- * ⛔ THE MAPS CROSS THE WIRE AS A JSON STRING, AND THAT IS THE CORRECT SHAPE. MEASURED with
- *   `bao write -output-curl-string` against the live v2.6.2 (no write was sent): the CLI
- *   puts every `k=v` value in the body as a string, so `default_extensions` leaves as
- *   `"{\"permit-pty\":\"\"}"` and never as an object. OpenBao's own OpenAPI types that field
- *   `object`/`format: map` — a `framework` TypeMap, which JSON-decodes a string value.
- *   ⚠️ THAT DECODE IS REASONED, NOT MEASURED: writing to the live engine was out of bounds,
- *   so the round trip was never executed. If a first deploy lands a role whose
- *   default_extensions came out EMPTY, this is the line that was wrong, and the fix is to
- *   send the map as a JSON object in writeBody rather than as this string — the HTTP body
- *   can now carry either.
+ * ⛔ THE MAPS CROSS THE WIRE AS JSON OBJECTS. A JSON STRING IS REJECTED, SO EVERY WRITE FAILED.
+ *   History: `bao write -output-curl-string` showed the CLI sending `k=v` values as strings,
+ *   so this once sent `"{\"permit-pty\":\"\"}"` on the reasoning that a `framework` TypeMap
+ *   JSON-decodes a string. ⚠️ IT DOES NOT. MEASURED 2026-09-21 against sdk v2.6.2 itself (a Go
+ *   probe of framework.FieldData.Validate, no server): TypeMap is `mapstructure.WeakDecode`
+ *   (framework/field_data.go:271-276), which refuses a string with "expected type
+ *   'map[string]interface {}', got unconvertible type 'string'" — and framework/backend.go:
+ *   281-285 answers that with a 400 before the handler runs. `"{}"` fails the same way, so every
+ *   Bao.SshRole write, not only those with extensions, would have been refused. It went unseen
+ *   because the adopted roles already matched and no write was ever sent. The same probe
+ *   accepted the object form and every other field of writeBody as sent.
  */
-const mapValue = (map: Readonly<Record<string, string>>) => JSON.stringify(extMap(map));
+const mapValue = (map: Readonly<Record<string, string>>) => extMap(map);
 
 /**
  * ⛔ EVERY MANAGED FIELD IS SENT ON EVERY WRITE, INCLUDING THE FALSE ONES. The role write is
  *   a full replace (see ssh-role.ts), so an omitted field is not "left alone" — it is reset.
- *   Sending the resolved form makes the body and the declaration the same statement. All
- *   strings, exactly the `k=v` pairs `bao write` sent, for `PUT <mount>/roles/<name>`.
+ *   Sending the resolved form makes the body and the declaration the same statement. Strings,
+ *   exactly the `k=v` pairs `bao write` sent, for `PUT <mount>/roles/<name>` — except the two
+ *   maps, which must be objects (the ⛔ on mapValue).
  */
-export const writeBody = (form: BaoSshRoleForm): Record<string, string> => ({
+export const writeBody = (form: BaoSshRoleForm): Record<string, unknown> => ({
   key_type: 'ca',
   allowed_users: form.allowedUsers.join(','),
   default_user: form.defaultUser,