@homeflare/alchemy 0.4.0 → 0.5.0

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

@@ -0,0 +1,64 @@
+/**
+ * The pure decisions behind appRoleLogin: which failure a status is, which mounts may be spliced
+ * into a URL, and what redaction removes. No server — approle-login.test.ts drives the fake.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { failureOf, loginPath, mountProblem, redact } from './approle-login-form.ts';
+
+describe('failureOf', () => {
+  it('reads 0 as unreachable, 2xx as a bad response, anything else as refused', () => {
+    assert.equal(failureOf(0), 'unreachable');
+    assert.equal(failureOf(200), 'response');
+    assert.equal(failureOf(204), 'response');
+    assert.equal(failureOf(400), 'refused');
+    assert.equal(failureOf(503), 'refused');
+  });
+});
+
+describe('mountProblem', () => {
+  it('accepts plain and nested mounts, trimming outer slashes', () => {
+    for (const mount of [undefined, 'approle', '/approle-hosts/', 'team/approle']) {
+      assert.equal(mountProblem(mount), undefined, String(mount));
+    }
+    assert.equal(loginPath('/team/approle/'), 'auth/team/approle/login');
+  });
+
+  it('refuses anything the URL parser would move or cut short', () => {
+    for (const mount of ['', '/', '..', 'a/../b', './a', 'a//b', 'a?b', 'a#b', 'a%2e', 'a b']) {
+      assert.notEqual(mountProblem(mount), undefined, mount);
+    }
+  });
+
+  it('trims long runs of slashes in linear time (no polynomial regex on caller input)', () => {
+    const run = '/'.repeat(200_000);
+    const started = performance.now();
+    assert.equal(loginPath(`${run}approle${run}`), 'auth/approle/login');
+    assert.notEqual(mountProblem(`${run}a${run}x`), undefined);
+    assert.ok(performance.now() - started < 1_000, 'slash trimming took over a second');
+  });
+});
+
+describe('redact', () => {
+  it('removes the raw value wherever it appears', () => {
+    assert.deepEqual(redact(['x secret-1 y secret-1'], ['secret-1']), [
+      'x [redacted] y [redacted]',
+    ]);
+  });
+
+  it('removes the %q form OpenBao echoes (path_login.go:291), escapes and all', () => {
+    const secret = 'a"b\\c';
+    const echoed = `invalid secret_id "a\\"b\\\\c"`;
+    assert.deepEqual(redact([echoed], [secret]), ['invalid secret_id "[redacted]"']);
+  });
+
+  it('redacts the longer value first, so a shorter one cannot split it', () => {
+    const [text] = redact(['role abc and secret abcdef'], ['abc', 'abcdef']);
+    assert.equal(text, 'role [redacted] and secret [redacted]');
+    assert.ok(!text?.includes('def'));
+  });
+
+  it('ignores an empty value rather than redacting every gap', () => {
+    assert.deepEqual(redact(['kept'], ['']), ['kept']);
+  });
+});

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

@@ -0,0 +1,153 @@
+/**
+ * The pure half of an AppRole login's INPUT and FAILURE: what counts as a usable input, and how a
+ * failure is described without the credential in it. Split from approle-login.ts so each decision
+ * is testable without a server; what a success hands back is approle-login-result.ts.
+ *
+ * ★ READ FROM openbao v2.6.2, NOT RECALLED:
+ *   · docs/api/auth/approle.mdx "Login with AppRole" — `role_id` and `secret_id` in, an `auth` block
+ *     out.
+ *   · api/auth/approle/approle.go:145-146 — the official Go helper writes `auth/<mount>/login`, and
+ *     the mount is `approle` unless the caller says otherwise. (api/*.go cited here diffed identical
+ *     between v2.6.0 and v2.6.2.)
+ */
+import { trimSlashes } from './mount-path.ts';
+
+/** Why a login or a revoke failed. */
+export type BaoLoginFailure =
+  /** Refused before any request was sent: an empty or padded value, or a mount that is not a path. */
+  | 'input'
+  /** OpenBao (or something at BAO_ADDR) answered with a non-2xx status. */
+  | 'refused'
+  /** No answer at all — transport, timeout, or an address nothing listens on. */
+  | 'unreachable'
+  /** A 2xx that is not a usable answer: not JSON, no auth block, or MFA still required. */
+  | 'response';
+
+/**
+ * The failure a transport-level BaoError stands for.
+ *
+ * ⚠️ A 2xx CAN FAIL TOO, AND IT IS NOT A REFUSAL. bao-status.ts settle fails a success whose body is
+ *   not a JSON object — the shape of a BAO_ADDR that points at some other web server. The first
+ *   version mapped every non-zero status to `refused`, so that read as `refused 200`: a server that
+ *   said yes, reported as one that said no.
+ */
+export const failureOf = (status: number): BaoLoginFailure =>
+  status === 0 ? 'unreachable' : status >= 200 && status < 300 ? 'response' : 'refused';
+
+/**
+ * A failed login or revoke.
+ *
+ * ⛔ IT NEVER CARRIES A CREDENTIAL. It is built from the operation name, a status and a list of
+ *   strings that have been through `redact` — never from the request, a header, or a `cause`, for
+ *   the reason bao-status.ts gives for BaoError.
+ */
+export class BaoLoginError extends Error {
+  constructor(
+    readonly reason: BaoLoginFailure,
+    /** The HTTP status, or 0 when none applies (input, unreachable, an unusable auth block). */
+    readonly status: number,
+    readonly errors: readonly string[],
+    operation: string,
+  ) {
+    const code = status === 0 ? reason : `${reason} ${String(status)}`;
+    super(`${operation}: ${code}: ${errors.join('; ') || '(no errors given)'}`);
+    this.name = 'BaoLoginError';
+  }
+}
+
+/**
+ * Why a value cannot be sent, or undefined when it can.
+ *
+ * ⚠️ PADDING IS REFUSED, NOT TRIMMED. `await Bun.file(path).text()` keeps a secret_id file's trailing
+ *   newline, and OpenBao answers that with "invalid role or secret ID" — the same words it uses for
+ *   a revoked or expired credential, so the real cause is invisible from the error. Trimming quietly
+ *   would send a different value from the one the caller holds; refusing names the problem.
+ * ⚠️ `unknown`, NOT `string`: a plain script passes `process.env.X`, which is `undefined` when unset.
+ */
+export const refusal = (label: string, value: unknown): string | undefined => {
+  if (typeof value !== 'string' || value === '') return `${label} is empty`;
+  if (value.trim() === '') return `${label} is only whitespace`;
+  if (value.trim() !== value) {
+    return `${label} has leading or trailing whitespace (a file read keeps its newline; trim it)`;
+  }
+  return undefined;
+};
+
+/** The auth mount without slashes; `approle` when the caller did not say. */
+export const loginMount = (mount: string | undefined): string => trimSlashes(mount ?? 'approle');
+
+/**
+ * Why `mount` cannot name an auth mount, or undefined when it can.
+ *
+ * ⛔ THE MOUNT IS SPLICED INTO A URL, AND THE URL PARSER RESOLVES `..` AND ENDS THE PATH AT `?` OR
+ *   `#`. `new URL('…/v1/auth/../sys/x/login')` is `…/v1/sys/x/login` — the role_id and secret_id
+ *   would be sent to a path the caller never named. Refused rather than escaped, like padding.
+ */
+export const mountProblem = (mount: string | undefined): string | undefined => {
+  const path = loginMount(mount);
+  if (path === '') return 'mount is empty';
+  const segments = path.split('/');
+  if (
+    /[\s?#%\\]/.test(path) ||
+    segments.some((part) => part === '' || part === '.' || part === '..')
+  ) {
+    return `mount ${JSON.stringify(path)} is not a plain mount path`;
+  }
+  return undefined;
+};
+
+/** `auth/<mount>/login` — what api/auth/approle/approle.go:145 writes. */
+export const loginPath = (mount: string | undefined): string => `auth/${loginMount(mount)}/login`;
+
+/** strconv.Quote's single-letter escapes, by code point. */
+const GO_ESCAPES: Readonly<Record<number, string>> = {
+  7: 'a',
+  8: 'b',
+  9: 't',
+  10: 'n',
+  11: 'v',
+  12: 'f',
+  13: 'r',
+};
+
+/**
+ * `value` as it appears between the quotes of Go's `%q` (strconv.Quote) — ASCII escapes only.
+ * ⚠️ Non-ASCII passes through as-is, which is what strconv.Quote does for PRINTABLE runes; a
+ *   non-printable non-ASCII rune in a secret would escape differently and is not covered.
+ */
+const goQuoted = (value: string): string =>
+  [...value]
+    .map((char) => {
+      const code = char.codePointAt(0) ?? 0;
+      const named = GO_ESCAPES[code];
+      if (char === '"' || char === '\\') return `\\${char}`;
+      if (named !== undefined) return `\\${named}`;
+      if (code < 0x20 || code === 0x7f) return `\\x${code.toString(16).padStart(2, '0')}`;
+      return char;
+    })
+    .join('');
+
+/**
+ * Every string in `errors` with each credential replaced by `[redacted]`.
+ *
+ * ⛔ OPENBAO CAN ECHO THE SECRET_ID BACK, SO THIS IS NOT DEFENCE IN DEPTH — IT IS THE DEFENCE.
+ *   openbao v2.6.2 builtin/credential/approle/path_login.go:291 answers a limited-use secret_id
+ *   whose storage entry vanished between two reads with `invalid secret_id "<the secret_id>"`.
+ *   BaoError keeps OpenBao's `errors` verbatim (that is its job), so every string that leaves the
+ *   login or revoke passes through here first.
+ * ⚠️ THAT ECHO IS `%q`, SO THE RAW VALUE IS NOT ENOUGH. A custom secret_id holding `"` or `\` comes
+ *   back escaped (`\"`, `\\`) and would slip past a raw match; the Go-quoted form is redacted too.
+ * ⚠️ LONGEST FIRST. Were one value a substring of another, redacting the shorter first would break
+ *   the longer one's match and leave the rest of it in the message.
+ */
+export const redact = (
+  errors: readonly string[],
+  secrets: readonly string[],
+): readonly string[] => {
+  const forms = [...new Set(secrets.flatMap((secret) => [secret, goQuoted(secret)]))]
+    .filter((form) => form !== '')
+    .sort((a, b) => b.length - a.length);
+  return errors.map((entry) =>
+    forms.reduce((text, form) => text.split(form).join('[redacted]'), entry),
+  );
+};

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

@@ -0,0 +1,96 @@
+/**
+ * What a successful AppRole login hands back, and how it is read out of a 2xx body. Split from
+ * approle-login-form.ts, which decides what goes IN; this decides what comes OUT and how the token
+ * stays out of every log line that prints the result.
+ *
+ * ★ READ FROM openbao v2.6.2 api/secret.go:304-318 SecretAuth — `client_token`, `accessor`,
+ *   `policies`, `lease_duration` and `mfa_requirement`. (api/*.go cited here diffed identical
+ *   between v2.6.0 and v2.6.2.)
+ */
+
+/** What a successful login hands back. */
+export interface AppRoleLogin {
+  /**
+   * The token. ⛔ A GETTER OVER A PRIVATE FIELD, NEVER AN OWN PROPERTY — see LoginResult below.
+   * `console.log(login)` prints `clientToken: [Getter]` at most, and `JSON.stringify(login)`,
+   * `{ ...login }` and `structuredClone(login)` carry no token at all. Read it by name.
+   */
+  readonly clientToken: string;
+  /** The token's accessor — safe to log, and what revoke-accessor and audit lines name. */
+  readonly accessor: string;
+  /** Every policy on the token: the role's token_policies plus identity policies. */
+  readonly policies: readonly string[];
+  /** The token TTL in seconds, from the role's `token_ttl`. */
+  readonly leaseDurationSeconds: number;
+}
+
+/**
+ * ⛔ A PRIVATE FIELD BEHIND A PROTOTYPE GETTER, BECAUSE A NON-ENUMERABLE PROPERTY DID NOT HIDE THE
+ *   TOKEN UNDER BUN. MEASURED 2026-09-21 on bun 1.4.0: `console.log` of an object whose token was a
+ *   non-enumerable OWN property printed `clientToken: "<the token>"` in full — node's util.inspect
+ *   hid it, bun's formatter did not — and this helper exists for Bun scripts. The first version
+ *   shipped exactly that shape, with a test that checked JSON and Object.keys but never a print.
+ *   This shape prints `clientToken: [Getter]` under bun's console.log and Bun.inspect, and nothing
+ *   at all under node's default inspect.
+ * ⚠️ `util.inspect(login, { getters: true })` DOES evaluate the getter. That is an explicit request
+ *   for the value, not an accident of logging the result.
+ */
+class LoginResult implements AppRoleLogin {
+  readonly #token: string;
+  readonly accessor: string;
+  readonly policies: readonly string[];
+  readonly leaseDurationSeconds: number;
+
+  constructor(token: string, accessor: string, policies: readonly string[], lease: number) {
+    this.#token = token;
+    this.accessor = accessor;
+    this.policies = Object.freeze([...policies]);
+    this.leaseDurationSeconds = lease;
+    Object.freeze(this);
+  }
+
+  get clientToken(): string {
+    return this.#token;
+  }
+}
+
+const strings = (value: unknown): readonly string[] =>
+  Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
+
+/**
+ * The login in a 2xx body, or the reason there is none.
+ *
+ * ⚠️ AN EMPTY `client_token` WITH A `mfa_requirement` IS AN UNFINISHED LOGIN, NOT A BROKEN ONE. The
+ *   auth block carries that field for a login that still owes an MFA step (api/secret.go:317). A
+ *   script cannot complete that step, so it is named rather than reported as a missing field.
+ *   REASONED FROM THE CLIENT TYPE — no MFA-enforced login was run.
+ * ⛔ THE BODY IS NEVER QUOTED. It holds the token on success and is not OpenBao's on a wrong address.
+ */
+export const loginOf = (
+  body: Record<string, unknown> | undefined,
+): { readonly login: AppRoleLogin } | { readonly problem: string } => {
+  const auth = body?.['auth'];
+  if (typeof auth !== 'object' || auth === null || Array.isArray(auth)) {
+    return { problem: 'the answer carried no auth block' };
+  }
+  const fields = auth as Record<string, unknown>;
+  const token = fields['client_token'];
+  if (typeof token !== 'string' || token === '') {
+    const mfa = fields['mfa_requirement'];
+    return {
+      problem:
+        mfa !== undefined && mfa !== null
+          ? 'the login requires MFA, which this helper does not complete'
+          : 'the auth block carried no client_token',
+    };
+  }
+  const lease = fields['lease_duration'];
+  return {
+    login: new LoginResult(
+      token,
+      typeof fields['accessor'] === 'string' ? fields['accessor'] : '',
+      strings(fields['policies']),
+      typeof lease === 'number' && Number.isFinite(lease) ? lease : 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));