@homeflare/alchemy 0.37.4 → 0.37.6

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

@@ -0,0 +1,128 @@
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { judgeAuthRoleRename } from './auth-role-identity.ts';
+import { deleteAuthRole, readAuthRole, writeAuthRole } from './auth-role-wire.ts';
+import { run, runFailure, withFake } from './fake-bao.ts';
+
+const PROPS = {
+  name: 'host-cert',
+  tokenPolicies: ['host-cert'],
+  tokenTtl: '15m',
+  tokenMaxTtl: '1h',
+  secretIdTtl: '2160h',
+};
+const DATA = {
+  bind_secret_id: true,
+  secret_id_num_uses: 0,
+  secret_id_ttl: 7776000,
+  token_max_ttl: 3600,
+  token_policies: ['host-cert'],
+  token_ttl: 900,
+};
+
+test('metadata SDK POST preserves omission/false/zero and never sends credential IDs', async () => {
+  await withFake(
+    () => ({ status: 204 }),
+    async (bao) => {
+      const env = { BAO_ADDR: bao.address, BAO_NAMESPACE: 'fixture', BAO_TOKEN: 'fake-token' };
+      await run(env, writeAuthRole(PROPS));
+      await run(env, writeAuthRole({ ...PROPS, bindSecretId: false, secretIdNumUses: 0 }));
+      expect(bao.seen.map(({ method }) => method)).toEqual(['POST', 'POST']);
+      const [first, second] = bao.seen;
+      if (first === undefined || second === undefined) throw new Error('expected both SDK writes');
+      expect(first.path).toBe('/v1/auth/approle/role/host-cert');
+      expect(first.headers.get('x-vault-request')).toBe('true');
+      expect(first.headers.get('x-vault-namespace')).toBe('fixture');
+      expect(JSON.parse(first.body)).toEqual({
+        token_policies: ['host-cert'],
+        token_ttl: 900,
+        token_max_ttl: 3600,
+        secret_id_ttl: 7776000,
+      });
+      expect(JSON.parse(second.body)).toEqual({
+        ...JSON.parse(first.body),
+        bind_secret_id: false,
+        secret_id_num_uses: 0,
+      });
+    },
+  );
+});
+
+for (const [status, tag] of [
+  [401, 'Unauthorized'],
+  [403, 'Forbidden'],
+  [500, 'InternalServerError'],
+] as const) {
+  test(`metadata SDK ${status} propagates for every verb and collision reads without retry`, async () => {
+    await withFake(
+      () => ({ status, json: { errors: ['refused'] } }),
+      async (bao) => {
+        const env = { BAO_ADDR: bao.address };
+        for (const op of [
+          Effect.asVoid(readAuthRole('host-cert')),
+          Effect.asVoid(writeAuthRole(PROPS)),
+          Effect.asVoid(deleteAuthRole('host-cert')),
+          Effect.asVoid(judgeAuthRoleRename({ name: 'old' }, { name: 'new' }, undefined)),
+        ])
+          expect(await runFailure(env, op)).toMatchObject({ _tag: tag });
+        expect(bao.seen.map(({ method }) => method)).toEqual(['GET', 'POST', 'DELETE', 'GET']);
+      },
+    );
+  });
+}
+
+test('typed missing read is absence and missing delete is success', async () => {
+  await withFake(
+    () => ({ status: 404, json: { errors: [] } }),
+    async (bao) => {
+      const env = { BAO_ADDR: bao.address };
+      expect(await run(env, readAuthRole('gone'))).toBeUndefined();
+      await run(env, deleteAuthRole('gone'));
+      expect(bao.seen).toHaveLength(2);
+    },
+  );
+});
+
+test('a malformed 200 never supplies role defaults or becomes absence', async () => {
+  for (const data of [
+    null,
+    {},
+    { ...DATA, token_policies: 'host-cert' },
+    { ...DATA, bind_secret_id: 'true' },
+    { ...DATA, token_ttl: -1 },
+  ]) {
+    await withFake(
+      () => ({ status: 200, json: { data } }),
+      async (bao) => {
+        expect(
+          String(await runFailure({ BAO_ADDR: bao.address }, readAuthRole('host-cert'))),
+        ).toContain('incomplete role metadata');
+      },
+    );
+  }
+});
+
+test('unmanaged nullable vendor fields do not prevent a valid metadata read', async () => {
+  await withFake(
+    () => ({ status: 200, json: { data: { ...DATA, secret_id_bound_cidrs: null } } }),
+    async (bao) => {
+      expect(await run({ BAO_ADDR: bao.address }, readAuthRole('host-cert'))).toMatchObject(DATA);
+    },
+  );
+});
+
+test('invalid TTL conversion refuses before any SDK exchange', async () => {
+  await withFake(
+    () => ({ status: 204 }),
+    async (bao) => {
+      for (const tokenTtl of ['invalid', '999999999999999999999999999h']) {
+        expect(
+          String(
+            await runFailure({ BAO_ADDR: bao.address }, writeAuthRole({ ...PROPS, tokenTtl })),
+          ),
+        ).toContain('invalid role TTL');
+      }
+      expect(bao.seen).toEqual([]);
+    },
+  );
+});

package/src/openbao/auth-role-wire.ts

@@ -0,0 +1,89 @@
+/**
+ * AppRole METADATA through the named SDK operations (OpenBao 2.6.2 generated schema).
+ * ★ pathRoleRead returns nil for absence; logical.RespondErrorCommon turns that read into
+ * 404. pathRoleDelete returns nil for an already absent role (204). Reasoned from v2.6.2
+ * builtin/credential/approle/path_role.go:1758-1904 and sdk/logical/response_util.go:21-26.
+ * ⛔ No role-id, secret-id or login request belongs in this configuration lifecycle.
+ */
+import {
+  type AppRoleReadRoleResponse,
+  type AppRoleWriteRoleRequest,
+  appRoleDeleteRole,
+  appRoleReadRole,
+  appRoleWriteRole,
+} from '@distilled.cloud/openbao/approle';
+import * as Effect from 'effect/Effect';
+import { type BaoAuthRoleProps, readPath } from './auth-role-form.ts';
+import { BaoError } from './bao-status.ts';
+import { runBao, runBaoRead, runBaoWrite } from './distilled.ts';
+import { parseDuration } from './mount-form.ts';
+
+const identity = (name: string) => ({ approle_mount_path: 'approle', role_name: name });
+const seconds = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+
+/**
+ * The vendor always returns these managed fields (pathRoleRead + tokenutil.PopulateTokenData).
+ * Generated response fields are optional, so a proxy's 200 {} must not supply default values.
+ * Ignore unmanaged fields: secret_id_bound_cidrs can legitimately be null in the vendor response.
+ */
+const completeRole = (live: AppRoleReadRoleResponse): boolean =>
+  live !== null &&
+  typeof live === 'object' &&
+  typeof live.bind_secret_id === 'boolean' &&
+  seconds(live.secret_id_num_uses) &&
+  seconds(live.secret_id_ttl) &&
+  seconds(live.token_ttl) &&
+  seconds(live.token_max_ttl) &&
+  Array.isArray(live.token_policies) &&
+  live.token_policies.every((policy) => typeof policy === 'string');
+
+export const readAuthRole = (name: string) =>
+  runBaoRead(appRoleReadRole(identity(name))).pipe(
+    Effect.flatMap((live) =>
+      completeRole(live)
+        ? Effect.succeed(live)
+        : Effect.fail(new BaoError(200, 'GET', readPath(name), ['incomplete role metadata'])),
+    ),
+    Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
+  );
+
+export const authRoleExists = (name: string) =>
+  readAuthRole(name).pipe(Effect.map((live) => live !== undefined));
+
+export const authRoleRequest = (props: BaoAuthRoleProps) =>
+  Effect.gen(function* () {
+    const tokenTtl = parseDuration(props.tokenTtl);
+    const tokenMaxTtl = parseDuration(props.tokenMaxTtl);
+    const secretIdTtl = parseDuration(props.secretIdTtl);
+    if (!seconds(tokenTtl) || !seconds(tokenMaxTtl) || !seconds(secretIdTtl)) {
+      return yield* Effect.fail(
+        new BaoError(0, 'POST', readPath(props.name), ['invalid role TTL duration']),
+      );
+    }
+    // ★ The former CLI-style body used strings for every k=v. The SDK schema uses seconds,
+    // booleans and arrays; omitted knobs stay omitted on update.
+    // pathRoleCreateUpdate preserves absent bind_secret_id/secret_id_num_uses on existing roles.
+    const request: AppRoleWriteRoleRequest = {
+      ...identity(props.name),
+      token_policies: [...props.tokenPolicies],
+      token_ttl: tokenTtl,
+      token_max_ttl: tokenMaxTtl,
+      secret_id_ttl: secretIdTtl,
+      ...(props.bindSecretId === undefined ? {} : { bind_secret_id: props.bindSecretId }),
+      ...(props.secretIdNumUses === undefined ? {} : { secret_id_num_uses: props.secretIdNumUses }),
+    };
+    return request;
+  });
+
+/**
+ * ★ A FULL-REPLACE WRITE, like the policy write: every managed field travels in the request
+ * every time (only genuinely omitted knobs stay omitted), so a transport failure is safe to
+ * retry through `runBaoWrite` — the replay sends the identical desired state.
+ */
+export const writeAuthRole = (props: BaoAuthRoleProps) =>
+  authRoleRequest(props).pipe(Effect.flatMap((request) => runBaoWrite(appRoleWriteRole(request))));
+
+/** Other typed SDK failures, including denied deletes, propagate unchanged. */
+export const deleteAuthRole = (name: string) =>
+  runBao(appRoleDeleteRole(identity(name))).pipe(Effect.catchTag('NotFound', () => Effect.void));

package/src/openbao/auth-role.ts

@@ -23,10 +23,10 @@ import {
   attributesOf,
   matches,
   readPath,
-  writeBody,
 } from './auth-role-form.ts';
-import { baoDelete, baoRead, baoWrite } from './bao-http.ts';
-import { foldName, guardRename, judgeRename, nameIdentity } from './rename-identity.ts';
+import { authRoleIdentity, judgeAuthRoleRename } from './auth-role-identity.ts';
+import { deleteAuthRole, readAuthRole, writeAuthRole } from './auth-role-wire.ts';
+import { guardRename } from './rename-identity.ts';
 
 export type { BaoAuthRoleAttributes, BaoAuthRoleProps };
 
@@ -48,13 +48,13 @@ export const BaoAuthRole = Resource<BaoAuthRole>('Bao.AuthRole', {
  *   :1537), so `Host` → `host` is the SAME role: a `replace` there would write it, then — under
  *   `destroy` — delete the old generation, which is that same role.
  */
-const IDENTITY = nameIdentity<BaoAuthRoleAttributes>('Bao.AuthRole', readPath, foldName);
+const IDENTITY = authRoleIdentity;
 
 const readRole = (props: BaoAuthRoleProps) =>
   Effect.gen(function* () {
-    const live = yield* baoRead(readPath(props.name));
+    const live = yield* readAuthRole(props.name);
     if (live === undefined) return undefined;
-    return attributesOf(props, live);
+    return attributesOf(props, { ...live });
   });
 
 export const BaoAuthRoleProvider = () =>
@@ -92,7 +92,7 @@ export const BaoAuthRoleProvider = () =>
            *   generation of a replace (Apply.ts:2164-2173). For per-host roles (host-approles.ts),
            *   opt into `RemovalPolicy.destroy()` or destroy the old role's accessors by hand.
            */
-          const move = yield* judgeRename(IDENTITY, olds, news, output);
+          const move = yield* judgeAuthRoleRename(olds, news, output);
           // ★ No attributes: an unfinished generation, proven ours or not by provingResumes.
           if (output === undefined) return undefined;
           if (move !== undefined) return { action: 'replace' } as const;
@@ -111,7 +111,7 @@ export const BaoAuthRoleProvider = () =>
           if (live !== undefined)
             yield* refuseTakeover({ fqn, instanceId, output }, `Bao.AuthRole ${path}`);
           if (live === undefined || !matches(live, news)) {
-            yield* baoWrite('PUT', readPath(news.name), writeBody(news));
+            yield* writeAuthRole(news);
           }
           const after = yield* readRole(news);
           if (after === undefined) {
@@ -136,7 +136,7 @@ export const BaoAuthRoleProvider = () =>
          *   because every host logging in with the role is locked out at the delete.
          */
         delete: Effect.fn(function* ({ output }) {
-          yield* baoDelete(readPath(output.name));
+          yield* deleteAuthRole(output.name);
           return undefined;
         }),
       }),

package/src/openbao/bao-http.ts

@@ -11,6 +11,7 @@
  * ⚠️ THE STACK MUST PROVIDE `FetchHttpClient.layer`. alchemy.run.ts does, the way
  *   <estate>/proxmox/alchemy.run.ts does.
  */
+import * as Cause from 'effect/Cause';
 import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
 import * as Option from 'effect/Option';
@@ -65,7 +66,7 @@ export const BaoGate = Context.Reference<Semaphore.Semaphore>('homeflare/openbao
  * ⚠️ 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';
+export const BAO_TIMEOUT = '60 seconds';
 
 /**
  * Mesh in front of a remote OpenBao drops connections under Alchemy's unbounded
@@ -73,11 +74,12 @@ const TIMEOUT = '60 seconds';
  * 2026-09-16 against bao.example.internal: a 585-role plan died mid-diff with
  * `no response: (no errors given)` while the vault stayed unsealed.
  */
-const retryTransport = <A, R>(effect: Effect.Effect<A, BaoError, R>) =>
+export const retryTransport = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
   Effect.retry(effect, {
     schedule: Schedule.spaced('750 millis'),
     times: 2,
-    while: (error: BaoError) => error.status === 0,
+    while: (error) =>
+      (error instanceof BaoError && error.status === 0) || Cause.isTimeoutError(error),
   });
 
 /**
@@ -87,7 +89,7 @@ const retryTransport = <A, R>(effect: Effect.Effect<A, BaoError, R>) =>
  *   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>) =>
+export 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, [
@@ -109,9 +111,9 @@ const redactingToken = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
  *   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 =
+export const overSocket =
   (socket: string | undefined, method: string, path: string) =>
-  <A, R>(effect: Effect.Effect<A, BaoError, R>): Effect.Effect<A, BaoError, R> => {
+  <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E | BaoError, R> => {
     if (socket === undefined) return effect;
     if (typeof Bun === 'undefined') {
       return Effect.fail(
@@ -148,7 +150,7 @@ export const baoCall = (
       Effect.flatMap((response) =>
         Effect.map(response.text, (text) => ({ status: response.status, text })),
       ),
-      Effect.timeout(TIMEOUT),
+      Effect.timeout(BAO_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])),

package/src/openbao/distilled-retry.test.ts

@@ -0,0 +1,164 @@
+import { expect, test } from 'bun:test';
+import { policiesReadAclPolicy } from '@distilled.cloud/openbao/policies';
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import { HttpClientError, TransportError } from 'effect/unstable/http/HttpClientError';
+import * as HttpClientResponse from 'effect/unstable/http/HttpClientResponse';
+import { readAuthRole, writeAuthRole } from './auth-role-wire.ts';
+import { BaoEnv } from './bao-http.ts';
+import { BaoError } from './bao-status.ts';
+import { runBaoRead } from './distilled.ts';
+import { deletePolicy, readPolicy, writePolicy } from './policy-wire.ts';
+
+const ROLE_PROPS = {
+  name: 'test',
+  tokenPolicies: ['default'],
+  tokenTtl: '15m',
+  tokenMaxTtl: '1h',
+  secretIdTtl: '2160h',
+};
+
+const TOKEN = 'fixture-retry-token';
+const POLICY = { policy: 'path "test" {}' };
+const ROLE = {
+  bind_secret_id: true,
+  secret_id_num_uses: 0,
+  secret_id_ttl: 0,
+  token_max_ttl: 3600,
+  token_policies: ['default'],
+  token_ttl: 900,
+};
+
+const runWith = <A, E>(
+  effect: Effect.Effect<A, E, HttpClient.HttpClient>,
+  client: HttpClient.HttpClient,
+) =>
+  Effect.runPromise(
+    effect.pipe(
+      Effect.provideService(BaoEnv, { BAO_ADDR: 'http://fake.invalid', BAO_TOKEN: TOKEN }),
+      Effect.provideService(HttpClient.HttpClient, client),
+    ),
+  );
+
+for (const [name, read, data] of [
+  ['Policy', Effect.asVoid(readPolicy('test')), POLICY],
+  ['AppRole', Effect.asVoid(readAuthRole('test')), ROLE],
+] as const) {
+  test(`${name} retries a dropped read and then returns the live object`, async () => {
+    let attempts = 0;
+    const client = HttpClient.make((request) => {
+      attempts++;
+      expect(request.method).toBe('GET');
+      return attempts === 1
+        ? Effect.fail(new HttpClientError({ reason: new TransportError({ request }) }))
+        : Effect.succeed(HttpClientResponse.fromWeb(request, Response.json({ data })));
+    });
+    await runWith(read, client);
+    expect(attempts).toBe(2);
+  });
+}
+
+test('read transport retries stop after three attempts without exposing the token', async () => {
+  let attempts = 0;
+  const client = HttpClient.make((request) => {
+    attempts++;
+    return Effect.fail(new HttpClientError({ reason: new TransportError({ request }) }));
+  });
+  const error = await runWith(Effect.flip(readPolicy('test')), client);
+  expect(attempts).toBe(3);
+  expect(error).toBeInstanceOf(BaoError);
+  expect(JSON.stringify(error)).not.toContain(TOKEN);
+});
+
+/**
+ * A FULL-REPLACE write sends the complete desired state on every attempt, so — unlike a
+ * create or a non-idempotent call — it is safe to replay after a transport-level failure.
+ * `runBaoWrite` restores the bounded retry `baoCall()` gave every call before the distilled
+ * SDK path landed with `Retry.none`.
+ */
+for (const [name, write] of [
+  ['Policy', writePolicy('test', 'path "test" {}')],
+  ['AppRole', writeAuthRole(ROLE_PROPS)],
+] as const) {
+  test(`${name} write retries a dropped transport attempt and then succeeds`, async () => {
+    let attempts = 0;
+    const client = HttpClient.make((request) => {
+      attempts++;
+      expect(request.method).toBe('POST');
+      return attempts === 1
+        ? Effect.fail(new HttpClientError({ reason: new TransportError({ request }) }))
+        : Effect.succeed(HttpClientResponse.fromWeb(request, new Response(null, { status: 204 })));
+    });
+    await runWith(write, client);
+    expect(attempts).toBe(2);
+  });
+
+  test(`${name} write transport retries stop after three attempts without exposing the token`, async () => {
+    let attempts = 0;
+    const client = HttpClient.make((request) => {
+      attempts++;
+      return Effect.fail(new HttpClientError({ reason: new TransportError({ request }) }));
+    });
+    const error = await runWith(Effect.flip(write), client);
+    expect(attempts).toBe(3);
+    expect(error).toBeInstanceOf(BaoError);
+    expect(JSON.stringify(error)).not.toContain(TOKEN);
+  });
+}
+
+test('a read timeout has a fresh bound on its next attempt', async () => {
+  let attempts = 0;
+  const client = HttpClient.make((request) => {
+    attempts++;
+    return attempts === 1
+      ? Effect.never
+      : Effect.succeed(HttpClientResponse.fromWeb(request, Response.json({ data: POLICY })));
+  });
+  await runWith(runBaoRead(policiesReadAclPolicy({ name: 'test' }), '20 millis'), client);
+  expect(attempts).toBe(2);
+});
+
+/**
+ * Delete stays single-attempt: it is idempotent (a policy or role already gone is success,
+ * per policy-wire.ts / auth-role-wire.ts), but it is not a full-replace write, and this suite
+ * scopes the restored retry to the writes that carry the complete desired state on the wire.
+ */
+test('an uncertain delete is never replayed', async () => {
+  let attempts = 0;
+  const client = HttpClient.make((request) => {
+    attempts++;
+    return Effect.fail(new HttpClientError({ reason: new TransportError({ request }) }));
+  });
+  const error = await runWith(Effect.flip(deletePolicy('test')), client);
+  expect(error).toBeInstanceOf(BaoError);
+  expect(attempts).toBe(1);
+});
+
+test('typed denied reads are returned immediately without transport retries', async () => {
+  let attempts = 0;
+  const client = HttpClient.make((request) => {
+    attempts++;
+    return Effect.succeed(
+      HttpClientResponse.fromWeb(
+        request,
+        Response.json({ errors: ['permission denied'] }, { status: 403 }),
+      ),
+    );
+  });
+  const error = await runWith(Effect.flip(readPolicy('test')), client);
+  expect(error).toMatchObject({ _tag: 'Forbidden' });
+  expect(attempts).toBe(1);
+});
+
+test('SDK normalization accepts an address that already carries the API prefix', async () => {
+  let observed = '';
+  const client = HttpClient.make((request) => {
+    observed = request.url;
+    return Effect.succeed(HttpClientResponse.fromWeb(request, Response.json({ data: POLICY })));
+  });
+  await runWith(
+    readPolicy('test').pipe(Effect.provideService(BaoEnv, { BAO_ADDR: 'http://fake.invalid/v1/' })),
+    client,
+  );
+  expect(observed).toBe('http://fake.invalid/v1/sys/policies/acl/test');
+});

package/src/openbao/distilled.test.ts

@@ -0,0 +1,146 @@
+import { expect, test } from 'bun:test';
+import { rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { policiesReadAclPolicy, policiesWriteAclPolicy } from '@distilled.cloud/openbao/policies';
+import * as Effect from 'effect/Effect';
+import * as Semaphore from 'effect/Semaphore';
+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, BaoGate, MAX_IN_FLIGHT, baoRead } from './bao-http.ts';
+import { runBao } from './distilled.ts';
+import { fakeBao, run, runFailure, withFake } from './fake-bao.ts';
+import { BaoError } from './bao-status.ts';
+import { readPolicy } from './policy-wire.ts';
+
+const OK = { json: { data: { policy: 'path "test" {}' } }, status: 200 };
+
+test('SDK calls resolve BAO/VAULT values per call, retaining empty BAO precedence', async () => {
+  await withFake(
+    () => OK,
+    async (bao) => {
+      const env = {
+        VAULT_ADDR: bao.address,
+        VAULT_NAMESPACE: 'tenant',
+        VAULT_TOKEN: 'first',
+        BAO_TOKEN: '',
+      };
+      const read = readPolicy('test');
+      await run(env, read);
+      env.BAO_TOKEN = 'rotated';
+      await run(env, read);
+      expect(bao.seen[0]?.headers.has('x-vault-token')).toBe(false);
+      expect(bao.seen[1]?.headers.get('x-vault-token')).toBe('rotated');
+      expect(bao.seen[1]?.headers.get('x-vault-namespace')).toBe('tenant');
+      expect(bao.seen[1]?.headers.get('x-vault-request')).toBe('true');
+    },
+  );
+});
+
+test('SDK calls use the agent unix socket ahead of a direct address, without a token header', async () => {
+  const socket = join(tmpdir(), `distilled-bao-${process.pid}.sock`);
+  rmSync(socket, { force: true });
+  try {
+    await withFake(
+      () => OK,
+      async (bao) => {
+        await run(
+          { BAO_ADDR: 'http://wrong.invalid', BAO_AGENT_ADDR: bao.address },
+          readPolicy('test'),
+        );
+        expect(bao.seen[0]?.path).toBe('/v1/sys/policies/acl/test');
+        expect(bao.seen[0]?.headers.has('x-vault-token')).toBe(false);
+        expect(bao.seen[0]?.headers.has('x-vault-namespace')).toBe(false);
+      },
+      socket,
+    );
+  } finally {
+    rmSync(socket, { force: true });
+  }
+});
+
+test('legacy and SDK calls share the same eight in-flight permits', async () => {
+  let active = 0;
+  let peak = 0;
+  await withFake(
+    async () => {
+      active++;
+      peak = Math.max(peak, active);
+      await Bun.sleep(15);
+      active--;
+      return OK;
+    },
+    async (bao) => {
+      await run(
+        { BAO_ADDR: bao.address },
+        Effect.all(
+          Array.from({ length: 32 }, (_, i) =>
+            i % 2 === 0 ? Effect.asVoid(readPolicy(`p${i}`)) : Effect.asVoid(baoRead(`p${i}`)),
+          ),
+          { concurrency: 'unbounded' },
+        ),
+      );
+      expect(peak).toBe(MAX_IN_FLIGHT);
+      expect(bao.seen).toHaveLength(32);
+    },
+  );
+});
+
+test('a sent write is bounded, not retried, and releases its permit', async () => {
+  await withFake(
+    async ({ method }) => {
+      if (method === 'POST') {
+        await Bun.sleep(120);
+        return { status: 204 };
+      }
+      return OK;
+    },
+    async (bao) => {
+      const gate = Semaphore.makeUnsafe(1);
+      const write = runBao(
+        policiesWriteAclPolicy({ name: 'test', policy: 'path "test" {}' }),
+        '30 millis',
+      );
+      const error = await runFailure(
+        { BAO_ADDR: bao.address },
+        write.pipe(Effect.provideService(BaoGate, gate)),
+      );
+      expect(error).toMatchObject({ _tag: 'TimeoutError' });
+      await run(
+        { BAO_ADDR: bao.address },
+        readPolicy('test').pipe(Effect.provideService(BaoGate, gate)),
+      );
+      expect(bao.seen.filter(({ method }) => method === 'POST')).toHaveLength(1);
+    },
+  );
+});
+
+test('the SDK keeps x-vault-token in Effect trace redaction alongside default names', async () => {
+  let names: ReadonlyArray<RegExp | string> = [];
+  const client = HttpClient.make((request, _url, _signal, fiber) => {
+    names = fiber.getRef(Headers.CurrentRedactedNames);
+    return Effect.succeed(HttpClientResponse.fromWeb(request, Response.json(OK.json)));
+  });
+  await Effect.runPromise(
+    runBao(policiesReadAclPolicy({ name: 'test' })).pipe(
+      Effect.provideService(BaoEnv, {
+        BAO_ADDR: 'http://fake.invalid',
+        BAO_TOKEN: 'never-log-this',
+      }),
+      Effect.provideService(HttpClient.HttpClient, client),
+    ),
+  );
+  expect(names).toContain('x-vault-token');
+  expect(names).toContain('authorization');
+});
+
+test('transport failures cannot serialize the request token after the fiber context unwinds', async () => {
+  const gone = fakeBao(() => OK);
+  gone.stop();
+  const token = 'fixture-private-bao-token';
+  const error = await runFailure({ BAO_ADDR: gone.address, BAO_TOKEN: token }, readPolicy('test'));
+  expect(error).toBeInstanceOf(BaoError);
+  expect(JSON.stringify(error)).not.toContain(token);
+  expect(String(error)).not.toContain(token);
+});