@homeflare/alchemy 0.1.0

package/src/openbao/bao-http-gate.test.ts

@@ -0,0 +1,88 @@
+/**
+ * The in-flight cap on OpenBao exchanges (`BaoGate` in bao-http.ts), counted where the listener that
+ * died on 2026-09-14 counted it: on the server. The fake holds every request for a few milliseconds
+ * and records the most it ever held at once.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import * as Effect from 'effect/Effect';
+import * as Semaphore from 'effect/Semaphore';
+import { BaoGate, MAX_IN_FLIGHT, baoRead } from './bao-http.ts';
+import { type Reply, run, runFailure, withFake } from './fake-bao.ts';
+
+/** A fake that holds each request `holdMs`, answering `reply`, and remembers its peak overlap. */
+const holding = (reply: (path: string) => Reply, holdMs = 15) => {
+  const counts = { inFlight: 0, peak: 0 };
+  const answer = async (seen: { path: string }) => {
+    counts.inFlight += 1;
+    counts.peak = Math.max(counts.peak, counts.inFlight);
+    await Bun.sleep(holdMs);
+    counts.inFlight -= 1;
+    return reply(seen.path);
+  };
+  return { answer, counts };
+};
+
+const OK: Reply = { json: { data: {} }, status: 200 };
+
+const burst = (address: string, calls: number, gate?: Semaphore.Semaphore) =>
+  Promise.all(
+    Array.from({ length: calls }, (_, index) => {
+      const read = baoRead(`kv/burst/${String(index)}`);
+      return run(
+        { BAO_ADDR: address },
+        gate === undefined ? read : read.pipe(Effect.provideService(BaoGate, gate)),
+      );
+    }),
+  );
+
+describe('BaoGate', () => {
+  it('never lets more than the gate through at once, and still answers every call', async () => {
+    const fake = holding(() => OK);
+    await withFake(fake.answer, async (bao) => {
+      const results = await burst(bao.address, 40, Semaphore.makeUnsafe(4));
+      assert.equal(results.length, 40);
+      assert.equal(bao.seen.length, 40);
+      // ★ EQUAL, NOT AT-MOST: 4 proves the calls really overlapped, so the cap was what held them.
+      assert.equal(fake.counts.peak, 4);
+    });
+  });
+
+  it('caps an unprovided burst at MAX_IN_FLIGHT — the gate every provider shares', async () => {
+    const fake = holding(() => OK);
+    await withFake(fake.answer, async (bao) => {
+      await burst(bao.address, MAX_IN_FLIGHT * 3);
+      assert.equal(fake.counts.peak, MAX_IN_FLIGHT);
+    });
+  });
+
+  // ★ THE SENSITIVITY CHECK: the same burst through a wide gate overlaps far past 4, so the tests
+  //   above would fail if the permit were dropped from baoCall.
+  it('lets the burst overlap when the gate is wide, so the cap above is doing the holding', async () => {
+    const fake = holding(() => OK);
+    await withFake(fake.answer, async (bao) => {
+      await burst(bao.address, 40, Semaphore.makeUnsafe(1000));
+      assert.ok(fake.counts.peak > 4, `peak was ${String(fake.counts.peak)}`);
+    });
+  });
+
+  it('gives a permit back when OpenBao refuses the call', async () => {
+    const denied: Reply = { json: { errors: ['permission denied'] }, status: 403 };
+    const fake = holding((path) => (path.includes('/refused/') ? denied : OK), 2);
+    await withFake(fake.answer, async (bao) => {
+      const gate = Semaphore.makeUnsafe(2);
+      const env = { BAO_ADDR: bao.address };
+      const gated = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+        effect.pipe(Effect.provideService(BaoGate, gate));
+      await Promise.all(
+        Array.from({ length: 10 }, (_, index) =>
+          runFailure(env, gated(baoRead(`kv/refused/${String(index)}`))),
+        ),
+      );
+      // ⛔ A LEAKED PERMIT HANGS HERE rather than failing, so the race turns a hang into a failure.
+      const after = run(env, gated(baoRead('kv/after')));
+      const hung = Bun.sleep(2000).then(() => 'hung' as const);
+      assert.notEqual(await Promise.race([after, hung]), 'hung');
+    });
+  });
+});

package/src/openbao/bao-http-unix.test.ts

@@ -0,0 +1,70 @@
+/**
+ * The unix-socket path, against a fake agent listener on Bun.serve's `unix` option.
+ *
+ * ★ An OpenBao Agent `listener "unix"` serves the API on a socket; BAO_ADDR / BAO_AGENT_ADDR name
+ *   it as `unix:///path`. These prove the request really leaves over the socket — through the real
+ *   FetchHttpClient layer, with no TCP server to fall back on.
+ */
+import assert from 'node:assert/strict';
+import { rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, it } from 'node:test';
+import { baoDelete, baoRead } from './bao-http.ts';
+import { fakeBao, run, withFake } from './fake-bao.ts';
+
+const socketPath = (label: string) => {
+  const path = join(tmpdir(), `fake-bao-${label}-${String(process.pid)}.sock`);
+  rmSync(path, { force: true });
+  return path;
+};
+
+describe('a unix:// address', () => {
+  it('reads over the socket, in agent mode, with the namespace', async () => {
+    const path = socketPath('read');
+    await withFake(
+      () => ({ json: { data: { type: 'kv' } }, status: 200 }),
+      async (agent) => {
+        const env = { BAO_ADDR: agent.address, BAO_NAMESPACE: 'homeflare' };
+        assert.deepEqual(await run(env, baoRead('sys/mounts/kv')), { type: 'kv' });
+        assert.equal(agent.seen[0]?.path, '/v1/sys/mounts/kv');
+        assert.equal(agent.seen[0]?.headers.get('x-vault-namespace'), 'homeflare');
+        assert.equal(agent.seen[0]?.headers.has('x-vault-token'), false);
+      },
+      path,
+    );
+    rmSync(path, { force: true });
+  });
+
+  it('classifies over the socket the same way: 404 read absent, 404 delete success', async () => {
+    const path = socketPath('absent');
+    await withFake(
+      () => ({ json: { errors: [] }, status: 404 }),
+      async (agent) => {
+        const env = { BAO_ADDR: agent.address };
+        assert.equal(await run(env, baoRead('pki/roles/zz')), undefined);
+        await run(env, baoDelete('pki/roles/zz'));
+        assert.equal(agent.seen.length, 2);
+      },
+      path,
+    );
+    rmSync(path, { force: true });
+  });
+
+  // ★ api/client.go:761-762 — BAO_AGENT_ADDR wins. BAO_ADDR here points at a server that is gone,
+  //   so the call only succeeds if it went to the agent socket.
+  it('prefers a BAO_AGENT_ADDR socket over BAO_ADDR', async () => {
+    const gone = fakeBao(() => ({ status: 200 }));
+    gone.stop();
+    const path = socketPath('agent');
+    await withFake(
+      () => ({ json: { data: { ok: true } }, status: 200 }),
+      async (agent) => {
+        const env = { BAO_ADDR: gone.address, BAO_AGENT_ADDR: agent.address };
+        assert.deepEqual(await run(env, baoRead('kv/config')), { ok: true });
+      },
+      path,
+    );
+    rmSync(path, { force: true });
+  });
+});

package/src/openbao/bao-http.test.ts

@@ -0,0 +1,161 @@
+/**
+ * The HTTP client against a fake OpenBao on Bun.serve: status classification end to end, the
+ * namespace header, the token header present with BAO_TOKEN and ABSENT in agent mode, and the
+ * token kept out of every error and every span.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import * as Effect from 'effect/Effect';
+import * as Headers from 'effect/unstable/http/Headers';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientResponse from 'effect/unstable/http/HttpClientResponse';
+import { BaoEnv, baoDelete, baoRead, baoWrite } from './bao-http.ts';
+import { BaoError } from './bao-status.ts';
+import { fakeBao, run, runFailure, withFake } from './fake-bao.ts';
+
+const TOKEN = 'hvs.FAKE-sentinel-never-a-real-token';
+const NONE = { errors: [] };
+
+const keepsTokenOut = (error: unknown) => {
+  assert.ok(error instanceof BaoError);
+  assert.ok(!error.message.includes(TOKEN), 'token in message');
+  assert.ok(!JSON.stringify(error).includes(TOKEN), 'token in JSON');
+  assert.ok(!Bun.inspect(error).includes(TOKEN), 'token in inspect');
+  return error;
+};
+
+describe('baoRead', () => {
+  it('returns data, sending the token, the namespace and X-Vault-Request', async () => {
+    const reply = { json: { data: { mint_user: 'hf-read@pve', ttl: 3600 } }, status: 200 };
+    await withFake(
+      () => reply,
+      async (bao) => {
+        const env = { BAO_ADDR: bao.address, BAO_NAMESPACE: 'homeflare', BAO_TOKEN: TOKEN };
+        const data = await run(env, baoRead('proxmox-tb4/roles/read'));
+        assert.deepEqual(data, { mint_user: 'hf-read@pve', ttl: 3600 });
+        const [seen] = bao.seen;
+        assert.equal(seen?.method, 'GET');
+        assert.equal(seen?.path, '/v1/proxmox-tb4/roles/read');
+        assert.equal(seen?.headers.get('x-vault-namespace'), 'homeflare');
+        assert.equal(seen?.headers.get('x-vault-token'), TOKEN);
+        assert.equal(seen?.headers.get('x-vault-request'), 'true');
+      },
+    );
+  });
+
+  // ★ AGENT MODE: the listener injects its auto-auth token only into a request that carries none.
+  it('sends no token header at all when BAO_TOKEN is unset', async () => {
+    await withFake(
+      () => ({ json: { data: {} }, status: 200 }),
+      async (bao) => {
+        await run({ BAO_ADDR: bao.address }, baoRead('kv/config'));
+        assert.equal(bao.seen[0]?.headers.has('x-vault-token'), false);
+        assert.equal(bao.seen[0]?.headers.has('x-vault-namespace'), false);
+      },
+    );
+  });
+
+  it('reads a 404 as absent', async () => {
+    await withFake(
+      () => ({ json: NONE, status: 404 }),
+      async (bao) => {
+        assert.equal(await run({ BAO_ADDR: bao.address }, baoRead('pki/roles/zz')), undefined);
+      },
+    );
+  });
+
+  it('fails a 403 with OpenBao errors and without the token', async () => {
+    const denied = {
+      json: { errors: ['1 error occurred:\n\t* permission denied\n\n'] },
+      status: 403,
+    };
+    await withFake(
+      () => denied,
+      async (bao) => {
+        const env = { BAO_ADDR: bao.address, BAO_TOKEN: TOKEN };
+        const error = keepsTokenOut(await runFailure(env, baoRead('sys/policies/acl/x')));
+        assert.equal(error.status, 403);
+        assert.deepEqual(error.errors, denied.json.errors);
+      },
+    );
+  });
+
+  it('fails a sealed server (503)', async () => {
+    await withFake(
+      () => ({ json: { errors: ['Vault is sealed'] }, status: 503 }),
+      async (bao) => {
+        const env = { BAO_ADDR: bao.address, BAO_TOKEN: TOKEN };
+        assert.equal(keepsTokenOut(await runFailure(env, baoRead('kv/config'))).status, 503);
+      },
+    );
+  });
+
+  it('fails a server that is not listening, as no response', async () => {
+    const gone = fakeBao(() => ({ status: 200 }));
+    gone.stop();
+    const env = { BAO_ADDR: gone.address, BAO_TOKEN: TOKEN };
+    const error = keepsTokenOut(await runFailure(env, baoRead('kv/config')));
+    assert.equal(error.status, 0);
+    assert.match(error.message, /-> no response: /);
+  });
+
+  // ⛔ Effect writes request headers onto the client span; the token must be a redacted name.
+  it('adds x-vault-token to the header names Effect redacts', async () => {
+    let names: ReadonlyArray<RegExp | string> = [];
+    const recording = HttpClient.make((request, _url, _signal, fiber) => {
+      names = fiber.getRef(Headers.CurrentRedactedNames);
+      const response = new Response('{"data":{}}', { status: 200 });
+      return Effect.succeed(HttpClientResponse.fromWeb(request, response));
+    });
+    await Effect.runPromise(
+      baoRead('kv/config').pipe(
+        Effect.provideService(BaoEnv, { BAO_ADDR: 'http://fake.invalid', BAO_TOKEN: TOKEN }),
+        Effect.provideService(HttpClient.HttpClient, recording),
+      ),
+    );
+    assert.ok(names.includes('x-vault-token'));
+    assert.ok(names.includes('authorization'), 'the defaults are kept');
+  });
+});
+
+describe('baoDelete', () => {
+  it('succeeds on a 404 — already gone — and on a 204', async () => {
+    for (const reply of [{ json: NONE, status: 404 }, { status: 204 }]) {
+      await withFake(
+        () => reply,
+        async (bao) => {
+          await run({ BAO_ADDR: bao.address }, baoDelete('ssh/roles/zz'));
+          assert.equal(bao.seen[0]?.method, 'DELETE');
+        },
+      );
+    }
+  });
+
+  it('fails a refused delete (403) and a sealed one (503)', async () => {
+    for (const status of [403, 503]) {
+      await withFake(
+        () => ({ json: { errors: ['nope'] }, status }),
+        async (bao) => {
+          const error = await runFailure({ BAO_ADDR: bao.address }, baoDelete('ssh/roles/zz'));
+          assert.equal(keepsTokenOut(error).status, status);
+        },
+      );
+    }
+  });
+});
+
+describe('baoWrite', () => {
+  it('sends the body as JSON with its content type, and fails a 404', async () => {
+    await withFake(
+      (seen) => (seen.path === '/v1/ok/roles/x' ? { status: 204 } : { json: NONE, status: 404 }),
+      async (bao) => {
+        const env = { BAO_ADDR: bao.address };
+        await run(env, baoWrite('PUT', 'ok/roles/x', { ttl: '3600' }));
+        assert.equal(bao.seen[0]?.headers.get('content-type'), 'application/json');
+        assert.deepEqual(JSON.parse(bao.seen[0]?.body ?? ''), { ttl: '3600' });
+        const error = await runFailure(env, baoWrite('PUT', 'nope/roles/x', { ttl: '1' }));
+        assert.equal(keepsTokenOut(error).status, 404);
+      },
+    );
+  });
+});

package/src/openbao/bao-http.ts

@@ -0,0 +1,185 @@
+/**
+ * One call to OpenBao's HTTP API through Effect's `HttpClient` — the transport every Bao.* family
+ * uses since it stopped shelling out to `bao`.
+ *
+ * ★ `HttpClient`, THE SAME PATTERN house/proxmox and house/forgejo USE AGAINST THEIR APIs, decided
+ *   2026-09-14. It buys a typed error channel, interruption when a plan is cancelled, the runtime's
+ *   tracing, and a client a test can point at a fake server — and it needs no Alchemy session, so
+ *   every call here works from all four operations. (`CommandExecutor.run` was tried on Bao.Policy
+ *   first and blocked read/diff: Alchemy passes a session to reconcile/delete but NOT to read/diff,
+ *   Provider.ts:258-289. The ChildProcessSpawner that fixed that is gone with the CLI.)
+ * ⚠️ THE STACK MUST PROVIDE `FetchHttpClient.layer`. alchemy.run.ts does, the way
+ *   house/proxmox/alchemy.run.ts does.
+ */
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as Semaphore from 'effect/Semaphore';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import * as Headers from 'effect/unstable/http/Headers';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
+import { type BaoEnvironment, headersFor, resolveAddress } from './bao-address.ts';
+import { BaoError, type BaoIntent, settle } from './bao-status.ts';
+
+/**
+ * The environment a call resolves BAO_ADDR, BAO_NAMESPACE and BAO_TOKEN from — `process.env`,
+ * read at call time, unless a test provides another.
+ */
+export const BaoEnv = Context.Reference<BaoEnvironment>('homeflare/openbao/BaoEnv', {
+  defaultValue: () => process.env,
+});
+
+/**
+ * ⛔ AT MOST EIGHT EXCHANGES WITH OPENBAO AT ONCE — ACROSS EVERY Bao.* FAMILY, IN ONE PROCESS.
+ *
+ * 🔴 MEASURED 2026-09-14 10:41: A DEPLOY OF THIS STACK TOOK OPENBAO's API OFF THE MINI. Alchemy fans
+ *   resources out with a hard-coded `concurrency: "unbounded"` (alchemy Plan.ts:476, Apply.ts:259,
+ *   :263, :303 — no option reaches it), and 555 Bao.CloudflareRole resources each read, diff,
+ *   reconcile and read back: well over a thousand requests at one loopback listener within seconds.
+ *   OpenBao logged
+ *     HTTP server (listening on 127.0.0.1:8200) exited with error: set tcp
+ *     127.0.0.1:8200->127.0.0.1:57974: setsockopt: invalid argument
+ *   and KEPT RUNNING with 8200 closed. launchd saw a live process and restarted nothing. Everything
+ *   on the mini that talks to 127.0.0.1:8200 was cut off, starting with the agent's templates, until
+ *   a manual restart.
+ * ★ THE LISTENER DYING IS A GO-ON-DARWIN FAILURE, NOT OURS TO FIX. Traefik lost its entrypoints the
+ *   same way on darwin/arm64 (traefik issue 8841). The BURST is ours. The adoption deploy an hour
+ *   earlier made the same calls and survived, so a cap narrows a race; it does not prove it closed.
+ * ★ A SEMAPHORE, NOT `HttpClient.withRateLimiter`. That limits requests per window and needs a
+ *   RateLimiter service. The failure is simultaneous connections, and only a cap on in-flight
+ *   exchanges bounds those whatever each one's latency.
+ * ⚠️ A Context.Reference SO A TEST CAN PROVIDE ITS OWN GATE. The default is built ONCE and cached on
+ *   the reference (effect Context.ts:1582-1588), so every call in the process shares one gate.
+ * ⚠️ EIGHT IS A CHOICE, NOT A MEASUREMENT OF WHAT THE LISTENER TOLERATES. Nothing here can find that
+ *   number without re-running the failure against production.
+ */
+export const MAX_IN_FLIGHT = 8;
+
+export const BaoGate = Context.Reference<Semaphore.Semaphore>('homeflare/openbao/BaoGate', {
+  defaultValue: () => Semaphore.makeUnsafe(MAX_IN_FLIGHT),
+});
+
+/**
+ * ⚠️ THE CLI's DEFAULT CLIENT TIMEOUT (openbao v2.6.2 api/client.go:324). A hung agent or a server
+ *   that accepts and never answers would otherwise hang the plan with no line saying why.
+ */
+const TIMEOUT = '60 seconds';
+
+/**
+ * ⛔ EFFECT RECORDS EVERY REQUEST HEADER ON THE CLIENT SPAN and redacts only the names in
+ *   `Headers.CurrentRedactedNames` — by default authorization, cookie, set-cookie and x-api-key
+ *   (effect Headers.ts:753-762; HttpClient.ts:842-849, with `TracerHeaderFilter` defaulting to
+ *   true). `X-Vault-Token` is not on that list, so under any tracer the token would be exported as
+ *   a span attribute. It is added for every call made here.
+ */
+const redactingToken = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+  Effect.gen(function* () {
+    const names = yield* Headers.CurrentRedactedNames;
+    return yield* Effect.provideService(effect, Headers.CurrentRedactedNames, [
+      ...names,
+      'x-vault-token',
+    ]);
+  });
+
+/**
+ * Route the exchange over a unix socket when the address is one.
+ *
+ * ★ BUN's `fetch` TAKES A `unix` OPTION (bun-types globals.d.ts BunFetchRequestInit.unix), AND
+ *   `FetchHttpClient.RequestInit` IS EFFECT'S DOCUMENTED WAY TO PASS FETCH OPTIONS. The fetch client
+ *   spreads that service into every call (effect FetchHttpClient.ts:59-72), reading it from the
+ *   CALLING fiber's context — and `layerMergedContext` merges the caller's context over the layer's
+ *   (HttpClient.ts:2065-2076), so providing it around one call routes that call alone. Any defaults
+ *   already provided are kept.
+ * ⛔ IT ONLY WORKS ON BUN, SO ANYWHERE ELSE IT REFUSES. Node's fetch ignores `unix` and would send
+ *   the request to http://localhost:80 — a silent wrong server, which is the one outcome this
+ *   package exists to prevent. It also assumes the provided `HttpClient` is the fetch one.
+ */
+const overSocket =
+  (socket: string | undefined, method: string, path: string) =>
+  <A, R>(effect: Effect.Effect<A, BaoError, R>): Effect.Effect<A, BaoError, R> => {
+    if (socket === undefined) return effect;
+    if (typeof Bun === 'undefined') {
+      return Effect.fail(
+        new BaoError(0, method, path, ['a unix:// address needs Bun fetch; this is not Bun']),
+      );
+    }
+    return Effect.flatMap(Effect.serviceOption(FetchHttpClient.RequestInit), (defaults) => {
+      const init: BunFetchRequestInit = { ...Option.getOrElse(defaults, () => ({})), unix: socket };
+      return Effect.provideService(effect, FetchHttpClient.RequestInit, init);
+    });
+  };
+
+/** One exchange, classified. The body is the parsed JSON object, or undefined for absent / 204. */
+export const baoCall = (
+  intent: BaoIntent,
+  method: 'DELETE' | 'GET' | 'POST' | 'PUT',
+  path: string,
+  body?: Readonly<Record<string, unknown>>,
+) =>
+  Effect.gen(function* () {
+    const env = yield* BaoEnv;
+    const address = resolveAddress(env);
+    const client = yield* HttpClient.HttpClient;
+    // ⚠️ The content type goes on `bodyText`, never in the header map: `bodyText` overwrites it.
+    //   house/proxmox/src/client.ts has the scar.
+    const request = HttpClientRequest.make(method)(`${address.base}/v1/${path}`).pipe(
+      HttpClientRequest.setHeaders(headersFor(address, env)),
+      body === undefined
+        ? (self) => self
+        : HttpClientRequest.bodyText(JSON.stringify(body), 'application/json'),
+    );
+    // ★ Status first, body read exactly once, as text — an error body is not reliably JSON.
+    const exchange = client.execute(request).pipe(
+      Effect.flatMap((response) =>
+        Effect.map(response.text, (text) => ({ status: response.status, text })),
+      ),
+      Effect.timeout(TIMEOUT),
+      // ⛔ `.message` ONLY: the HttpClientError message is the reason, method and URL. The error
+      //   object itself holds the request, whose headers hold the token.
+      Effect.mapError((cause) => new BaoError(0, method, path, [cause.message])),
+    );
+    // ★ THE PERMIT WRAPS THE TIMEOUT, NOT THE REVERSE: a call queued behind the gate is not yet
+    //   talking to OpenBao, so its wait must not count against the 60 seconds.
+    const gate = yield* BaoGate;
+    const { status, text } = yield* exchange.pipe(
+      overSocket(address.socket, method, path),
+      redactingToken,
+      Semaphore.withPermits(gate, 1),
+    );
+    const outcome = settle(intent, method, path, status, text);
+    return 'error' in outcome ? yield* Effect.fail(outcome.error) : outcome.body;
+  });
+
+/**
+ * The `data` of a read, or undefined when OpenBao says the object is ABSENT (404).
+ *
+ * ★ `bao read -format=json` printed this same response body; the old helper took `data` when it was
+ *   an object and the whole body otherwise, and so does this.
+ */
+export const baoRead = (path: string) =>
+  Effect.map(baoCall('read', 'GET', path), (body) => {
+    if (body === undefined) return undefined;
+    const data = body['data'];
+    return typeof data === 'object' && data !== null
+      ? (data as Record<string, unknown>)
+      : (body as Record<string, unknown>);
+  });
+
+/**
+ * A write whose SUCCESS MATTERS. Any non-2xx fails, 404 included.
+ *
+ * ★ `PUT` IS WHAT `bao write` SENT (openbao v2.6.2 api/logical.go Write); `sys/mounts` enable and
+ *   tune are `POST` in the same client (api/sys_mounts.go:57, :201).
+ * ⚠️ 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.
+ */
+export const baoWrite = (
+  method: 'POST' | 'PUT',
+  path: string,
+  body: Readonly<Record<string, unknown>>,
+) => Effect.asVoid(baoCall('write', method, path, body));
+
+/** A delete: idempotent — already gone (404) is success — and refused (403, 5xx) is a failure. */
+export const baoDelete = (path: string) => Effect.asVoid(baoCall('delete', 'DELETE', path));

package/src/openbao/bao-status.test.ts

@@ -0,0 +1,114 @@
+/**
+ * The classification every read and every delete in this package rests on.
+ *
+ * ⛔ BOTH DIRECTIONS ARE PINNED, BECAUSE EACH HAS ALREADY BEEN WRONG ONCE. Every non-zero exit used
+ *   to read as "absent" — a bad token planned 33 updates against a vault that was fine — and one
+ *   command's absence wording was assumed for another's, so a policy that did not exist yet could
+ *   not be created. These replace bao-shell.test.ts's stderr cases with the status codes those
+ *   stderr lines were rendering: a missing role (404), a refused policy read under the agent lane
+ *   (403 — `Code: 403 … permission denied`, measured 2026-09-14), a missing policy under the admin
+ *   lane (404), and a server that is not listening (no response at all, bao-http.test.ts).
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { BaoError, settle } from './bao-status.ts';
+
+const ROLE = 'pki/roles/does-not-exist-zzz';
+const POLICY = 'sys/policies/acl/zz-new-policy';
+const NONE = JSON.stringify({ errors: [] });
+const DENIED = JSON.stringify({ errors: ['1 error occurred:\n\t* permission denied\n\n'] });
+const SEALED = JSON.stringify({ errors: ['Vault is sealed'] });
+
+const errorOf = (outcome: ReturnType<typeof settle>) => {
+  assert.ok('error' in outcome, 'expected a failure');
+  return outcome.error;
+};
+
+describe('settle', () => {
+  it('passes a JSON body through on success', () => {
+    assert.deepEqual(settle('read', 'GET', ROLE, 200, '{"data":{"ttl":3600}}'), {
+      body: { data: { ttl: 3600 } },
+    });
+  });
+
+  it('reads an OpenBao 404 as absent on a read', () => {
+    assert.deepEqual(settle('read', 'GET', ROLE, 404, NONE), { body: undefined });
+  });
+
+  // ⛔ THE BUG SHAPE b3c18a33e FIXED. A policy that does not exist yet is the same 404 as any other
+  //    absent object — there is no second wording left to get wrong.
+  it('reads a policy that does not exist yet as absent', () => {
+    assert.deepEqual(settle('read', 'GET', POLICY, 404, NONE), { body: undefined });
+  });
+
+  it('treats a 404 as success on a delete, because a delete must be idempotent', () => {
+    assert.deepEqual(settle('delete', 'DELETE', POLICY, 404, NONE), { body: undefined });
+  });
+
+  it('accepts a 204 with no body on a write and on a delete', () => {
+    assert.deepEqual(settle('write', 'PUT', POLICY, 204, ''), { body: undefined });
+    assert.deepEqual(settle('delete', 'DELETE', POLICY, 204, ''), { body: undefined });
+  });
+
+  it('fails a 404 on a write, carrying OpenBao errors', () => {
+    const errors = ['no handler for route "nope/roles/x". route entry not found.'];
+    const error = errorOf(settle('write', 'PUT', 'nope/roles/x', 404, JSON.stringify({ errors })));
+    assert.deepEqual(error.errors, errors);
+  });
+
+  // ⛔ AND DENIAL IS NEVER ABSENCE, on a read or on a delete.
+  it('fails a refused read and a refused delete (403)', () => {
+    assert.equal(errorOf(settle('read', 'GET', POLICY, 403, DENIED)).status, 403);
+    assert.equal(errorOf(settle('delete', 'DELETE', POLICY, 403, DENIED)).status, 403);
+  });
+
+  it('fails a sealed server (503) on every intent', () => {
+    for (const intent of ['read', 'write', 'delete'] as const) {
+      assert.equal(errorOf(settle(intent, 'GET', ROLE, 503, SEALED)).status, 503);
+    }
+  });
+
+  it('fails a 400 and a 500', () => {
+    assert.equal(errorOf(settle('read', 'GET', ROLE, 400, NONE)).status, 400);
+    assert.equal(errorOf(settle('read', 'GET', ROLE, 500, NONE)).status, 500);
+  });
+
+  // ⚠️ A BAO_ADDR pointed at the wrong server must not plan CREATE for everything.
+  it('does not read a 404 that is not an OpenBao body as absent', () => {
+    const error = errorOf(settle('read', 'GET', ROLE, 404, '<html>Not Found</html>'));
+    assert.match(error.message, /not an OpenBao error body/);
+    assert.ok('error' in settle('delete', 'DELETE', ROLE, 404, '<html>Not Found</html>'));
+  });
+
+  it('fails a successful read that has no body', () => {
+    assert.equal(errorOf(settle('read', 'GET', ROLE, 200, '')).status, 200);
+  });
+
+  // ⛔ A success body can hold a credential, so a malformed one is described and never quoted.
+  it('fails an unparseable success body without quoting it', () => {
+    const error = errorOf(settle('read', 'GET', 'pbs-tb4/creds/read', 200, 'secret=abc123 {'));
+    assert.ok(!error.message.includes('abc123'));
+  });
+
+  // ⛔ A JSON gateway's error shape is not OpenBao's, even on a 404 (grok, 2026-09-14).
+  it('does not read a 404 whose errors are objects as absent, on a read or a delete', () => {
+    const gateway = JSON.stringify({ errors: [{ code: 1000, message: 'Not Found' }] });
+    const error = errorOf(settle('read', 'GET', ROLE, 404, gateway));
+    assert.match(error.message, /not an OpenBao error body/);
+    assert.ok('error' in settle('delete', 'DELETE', ROLE, 404, gateway));
+  });
+
+  // ⛔ An error page that echoes the request back must not carry the token into the message.
+  it('describes a foreign error body without quoting it', () => {
+    const echo = '<pre>X-Vault-Token: hvs.sentinel-not-a-token</pre>';
+    const error = errorOf(settle('read', 'GET', ROLE, 502, echo));
+    assert.ok(!error.message.includes('hvs.sentinel'));
+  });
+
+  it('names the method and path, and carries the errors array', () => {
+    const error = errorOf(settle('read', 'GET', POLICY, 403, DENIED));
+    assert.ok(error instanceof BaoError);
+    assert.match(error.message, /^OpenBao GET \/v1\/sys\/policies\/acl\/zz-new-policy -> 403: /);
+    assert.deepEqual(error.errors, ['1 error occurred:\n\t* permission denied\n\n']);
+  });
+});