@homeflare/alchemy 0.4.1 → 0.6.0

package/src/openbao/README.md

@@ -0,0 +1,181 @@
+# `@homeflare/alchemy/openbao`
+
+Vault objects as Alchemy resources: `BaoMount`, `BaoAuthMethod`, `BaoPolicy`, `BaoAuthRole`,
+`BaoJwtRole`, `BaoKubernetesRole`, `BaoJwtAuthConfig`, `BaoMfaTotpMethod`,
+`BaoMfaLoginEnforcement`, `BaoPkiRole`, `BaoSshRole`, `BaoCloudflareRole`, `BaoProxmoxRole` and
+`BaoPlugin`. It also has three plain helpers: `assertBaoIdentity`, `hostAppRoles` and
+`appRoleLogin`.
+
+Every call resolves `BAO_ADDR`, `BAO_AGENT_ADDR`, `BAO_NAMESPACE` and `BAO_TOKEN` (or their
+`VAULT_*` twins) the same way the `bao` CLI does. A stack provides each `Bao*Provider()` it uses,
+plus `FetchHttpClient.layer`.
+
+- ⛔ **Metadata only.** Alchemy stores props and attributes unencrypted, so you cannot declare a
+  secret, a CA key, a plugin `env` or an OIDC client secret.
+- Every family defaults to `retain` on destroy. For what a rename does, read
+  [REPLACE.md](./REPLACE.md) before you change any resource's path or name.
+
+## assertBaoIdentity: call it first
+
+```ts
+import { assertBaoIdentityEffect } from '@homeflare/alchemy/openbao';
+
+export const guarded = Effect.gen(function* () {
+  yield* assertBaoIdentityEffect({ clusterName: 'vault-example', namespace: 'team-a' });
+  // …every Bao.* resource after this
+});
+```
+
+- It reads the unauthenticated `sys/health` with no token and no namespace header, because
+  health is root-only. It refuses a sealed vault, the wrong `cluster_name`, a `BAO_NAMESPACE`
+  that is not the expected one, and a namespace the cluster does not have.
+- ⚠️ It fails with a `BaoIdentityError` whose message starts with `REFUSING:`. The `reason` is
+  `input`, `mismatch`, `unconfirmed` or `unreachable`. `assertBaoIdentity` is the Promise form.
+- ⚠️ It catches a mis-set address, not an impostor. Any server can repeat a `cluster_name`;
+  TLS is what proves which server answered.
+
+## BaoMount / BaoAuthMethod: moving a path
+
+```ts
+export const kv = Effect.gen(function* () {
+  yield* BaoMount('kv', { path: 'secrets', remountFrom: 'kv', type: 'kv', version: 2 });
+});
+```
+
+- ⛔ If `path` changes, the plan now fails unless `remountFrom` names the old path. Before this, a
+  path change enabled an empty mount at the new path.
+- With `remountFrom`, the provider moves the mount with `sys/remount` and polls until the move is
+  done, so the data stays. ⛔ The move revokes every lease under the old path, and it does not
+  rewrite policies that name that path. The deploying token needs `sudo` on `sys/remount`.
+
+## hostAppRoles: one AppRole per host
+
+```ts
+export const hostRoles = Effect.gen(function* () {
+  const roles = hostAppRoles({
+    classes: {
+      'pve-node': {
+        policies: ['pve-node'],
+        secretIdTtl: '2160h',
+        tokenMaxTtl: '1h',
+        tokenTtl: '15m',
+      },
+    },
+    hosts: [{ class: 'pve-node', name: 'node-a' }],
+  });
+  for (const props of roles) yield* BaoAuthRole(props.name, props); // `pve-node--node-a`
+});
+```
+
+- A role is named `<class>--<host>`. Class and host names may contain only lowercase letters,
+  digits and single hyphens.
+- It refuses `secretIdTtl` 0 (a secret_id that never expires), empty policies, `root`, unknown
+  classes and duplicate hosts.
+- ⚠️ Renaming a host or class makes a new role. Under `retain` the old one stays live and keeps
+  admitting its secret_ids (REPLACE.md).
+
+## BaoJwtRole / BaoKubernetesRole / BaoJwtAuthConfig
+
+```ts
+export const machines = Effect.gen(function* () {
+  const issuer = 'https://issuer.example.com';
+  yield* BaoJwtAuthConfig('gh', {
+    boundIssuer: issuer,
+    mount: 'jwt-github',
+    oidcDiscoveryUrl: issuer,
+  });
+  yield* BaoJwtRole('ci', {
+    boundAudiences: ['https://example.com/org'],
+    boundClaims: { ref: 'refs/heads/main' },
+    mount: 'jwt-github',
+    name: 'ci-app',
+    roleType: 'jwt',
+    tokenPolicies: ['ci-app'],
+    tokenTtl: '10m',
+    userClaim: 'repository',
+  });
+  yield* BaoKubernetesRole('pod', {
+    aliasNameSource: 'serviceaccount_name',
+    boundServiceAccountNames: ['litellm'],
+    boundServiceAccountNamespaces: ['ai'],
+    name: 'ai-litellm',
+    tokenPolicies: ['ai-litellm'],
+  });
+});
+```
+
+- ⛔ `roleType` is required. OpenBao's default is `oidc`, even when it rewrites a `jwt` role.
+- ⛔ `aliasNameSource` is required too. Changing it on a live role moves every pod to a new entity.
+- Every managed field is sent on every write, so a value someone set by hand cannot sit
+  unnoticed behind a green plan. `verbose_oidc_logging` and `oidc_disable_confirmation` are
+  always sent as `false`.
+- ⛔ `BaoJwtAuthConfig` has no OIDC client secret, and it refuses a mount whose live config has
+  an `oidc_client_id`: its full-replace write would erase that secret, which the read never
+  returns. It has no delete endpoint, so its delete writes nothing.
+
+## Login MFA: BaoMfaTotpMethod + BaoMfaLoginEnforcement
+
+```ts
+export const adminMfa = Effect.gen(function* () {
+  const totp = yield* BaoMfaTotpMethod('admin-totp', {
+    issuer: 'vault-example',
+    name: 'admin-totp',
+  });
+  yield* BaoMfaLoginEnforcement('admin-mfa', {
+    authMethodPaths: ['oidc-admin'],
+    mfaMethodIds: [totp.methodId],
+    name: 'admin-mfa',
+  });
+});
+```
+
+- ⛔ **Enrol before you enforce.** An entity with no TOTP secret fails every login the
+  enforcement matches. Enrol admins with `admin-generate`, never through Alchemy.
+- ⚠️ An enforcement matches mounts, identity groups or entities. It never matches a role. Target
+  mounts by path; `authMethodTypes: ['jwt']` also catches machine JWT mounts.
+- ⛔ Renaming a TOTP method fails the plan, because it would strand every enrolled secret.
+  Deleting an enforcement is refused: in OpenBao 2.6.2 a delete comes back after a restart
+  (openbao/openbao#4030).
+
+## appRoleLogin / revokeSelf (for scripts)
+
+```ts
+const login = await appRoleLogin({ roleId, secretId }); // mount defaults to `approle`
+try {
+  use(login.clientToken, login.accessor, login.policies, login.leaseDurationSeconds);
+} finally {
+  await revokeSelf(login.clientToken);
+}
+```
+
+- ⛔ The login never sends `BAO_TOKEN`, and a `BaoLoginError` never contains the credential.
+  OpenBao can echo a secret_id back in an error, so every error string is redacted.
+- ⚠️ `clientToken` is a getter over a private field. `console.log(login)` prints `[Getter]` at
+  most under Bun and nothing under Node. JSON, a spread and `structuredClone` carry no token.
+- ⚠️ A value with leading or trailing whitespace is refused, not trimmed. Note that
+  `Bun.file().text()` keeps a file's trailing newline.
+- The error's `reason` is `input`, `refused`, `unreachable` or `response`. Pass `env` to use
+  something other than `process.env`. `appRoleLoginEffect` and `revokeSelfEffect` are the same
+  calls as Effects.
+
+## BaoPlugin
+
+```ts
+export const plugins = Effect.gen(function* () {
+  yield* BaoPlugin('plugin-example', {
+    name: 'openbao-plugin-secrets-example',
+    type: 'secret', // 'secret' | 'auth' | 'database'
+    command: 'openbao-plugin-secrets-example', // a bare file name in plugin_directory
+    sha256: '<hex sha256 of that file>',
+    version: 'v0.1.2', // canonical semver
+  });
+});
+```
+
+- ⛔ It registers a binary that is already in `plugin_directory`. It does not copy the binary.
+- ⚠️ **If the binary reports its own version, declare exactly that version.** OpenBao refuses any
+  other version ("plugin version mismatch"). It files an unversioned registration under the
+  reported version, and reconcile then refuses because the read-back finds nothing.
+- ⚠️ A new `sha256` does not restart running mounts. Reload them with
+  `sys/plugins/reload/backend`.
+- The deploying token needs `sudo` on `sys/plugins/catalog/*`.

package/src/openbao/REPLACE.md

@@ -0,0 +1,87 @@
+# Replace semantics: the `Bao.*` providers
+
+Audited 2026-09-21, against `alchemy@2.0.0-beta.79` and OpenBao v2.6.2 source. Every kit
+provider must answer `replace` correctly (vault consolidation plan, "Replace freely").
+
+## What Alchemy does with each answer
+
+- **`update`**: `reconcile` runs against the same resource. Only safe when the object's identity
+  (its path) is unchanged.
+- **`replace`**: create-first by default. The new generation is created, dependents are updated in
+  the same graph, then the old generation is deleted (`Apply.ts`, delete-first comment near :1180).
+- **`deleteFirst: true`**: tears the old one down first. It is only for identities that cannot
+  coexist, such as a unique physical name. No `Bao.*` provider uses it. A rename is a new API
+  path, which never collides with the old one. ⚠️ A mount or auth method whose `type` changes
+  keeps its path, so the two generations DO collide. It deliberately stays create-first, and the
+  create fails (see the table).
+- **`retain`**, the default for every `Bao.*` family, **keeps the old generation of a replace**
+  (`Apply.ts:2164-2173`, "Retaining replaced resource"). ⚠️ So under the default, a replaced role
+  **stays live** and still admits logins. Opt into `RemovalPolicy.destroy()` where that matters
+  (per-host AppRoles), or remove it by hand.
+
+## The bug class this audit found
+
+⛔ **A changed identity planned `update`.** `diff` read the NEW path, found nothing, answered
+`update`, and `reconcile` created the object at the new path. The old object stayed live with no
+state record, so no later plan would mention it. For a mount this meant an **empty** new mount
+beside the retained one that held every secret. For an AppRole it meant the old role's secret_ids
+kept working for their whole TTL.
+
+## Touched in this batch
+
+| Resource                  | Identity change | Answer now                                                                                                                               | Other changes                                                                               |
+| ------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `Bao.Mount`               | `path`          | ⛔ **fails the plan**, unless `remountFrom` names the old path. Then it is an in-place `update` that moves the mount with `sys/remount`. | `type` → `replace` that **fails at apply** (below). Description and TTLs → `update` (tune). |
+| `Bao.AuthMethod`          | `path`          | Same as `Bao.Mount` (`auth/` prefix). The accessor survives the move.                                                                    | `type` → `replace` that **fails at apply** (below)                                          |
+| `Bao.AuthRole`            | `name`          | `replace`. Before 2026-09-21 it was `update`, and the old role was orphaned.                                                             | `update`                                                                                    |
+| `Bao.PkiRole`             | `mount`, `name` | `replace`. Before, only a `mount` change was caught; a `name` change orphaned the old role.                                              | `update` (full-replace write)                                                               |
+| `Bao.JwtRole`             | `mount`, `name` | `replace`                                                                                                                                | `update` (merge write; every managed field is sent)                                         |
+| `Bao.KubernetesRole`      | `mount`, `name` | `replace`                                                                                                                                | `update`                                                                                    |
+| `Bao.JwtAuthConfig`       | `mount`         | `replace`. The old delete is a no-op because there is no delete endpoint.                                                                | `update` (full-replace write)                                                               |
+| `Bao.MfaTotpMethod`       | `name`          | ⛔ **fails the plan**: a new id would strand every enrolled secret                                                                       | `update` (the upsert keeps the id)                                                          |
+| `Bao.MfaLoginEnforcement` | `name`          | `replace`. Its delete is **refused** (openbao#4030)                                                                                      | `update`                                                                                    |
+
+`hostAppRoles` makes no resources, but its names are identities: renaming a host or a class
+renames the role. With the logical id taken from the role name, as the README does, the old id
+leaves the stack: that is an orphan delete, not a `replace`. With a stable logical id,
+`Bao.AuthRole` plans a `replace`. Under the default `retain`, both leave the old role live.
+
+## Why the moves fail instead of replacing
+
+- **Mount and auth path.** A `replace` would create an empty mount. Deleting the old one would
+  destroy every secret, and with the default `retain` the data would be stranded. `sys/remount`
+  is the only move that keeps the data: the mount keeps its UUID, and storage lives under the
+  UUID (`vault/mount.go:630-735`). ⛔ It **revokes every lease** under the old path
+  (`RevokePrefix`, :684), and it rewrites no policy that names the old path.
+- **TOTP method name.** Every enrolled secret is keyed by the method id
+  (`entity.MFASecrets[id]`). The safe rename adds a second method, lists both on the enforcement
+  (any one passing is enough), enrols everyone, then drops the old method.
+
+## Why a type change fails instead of replacing
+
+The plan says `replace`, but the new generation reads the same path, finds the old type there,
+and its reconcile dies with "type is immutable" before any write. So the deploy fails, and
+nothing is disabled under either removal policy. Change a type by hand. ⛔ `deleteFirst` would
+make it succeed, but under `destroy` it disables the mount first, and a mistyped `type` would
+take every secret with it. (Corrected 2026-09-21: the first audit listed this as a clean
+`replace`.)
+
+## The plan's three exceptions, mapped
+
+1. **`retain` resources orphan the old generation on a replace.** That applies to all of the
+   above. A mount is never replaced for a rename. It is moved (`remountFrom`), which works like
+   adopting it at the new path.
+2. **Referents outside the graph.** These do not follow a replace: host credential files (a new
+   AppRole means a new role_id), login URLs and CLI `-path` flags naming an auth mount or role,
+   policies naming a mount path, and third-party OIDC clients holding a redirect URI. Rotate or
+   move them in the same PR.
+3. **Unique names need `deleteFirst`.** Only a mount's `type` change keeps its unique path, and
+   it fails on purpose instead (above).
+
+## Audited, not touched in this batch (open)
+
+- ⚠️ `Bao.Policy`, `Bao.CloudflareRole` and `Bao.ProxmoxRole` still compare only the live object
+  at the declared `name` (and `mount`). A rename plans `update` and orphans the old object, which
+  is the same bug class as above. `Bao.ProxmoxRole` deliberately never answers `replace` for a
+  `mint_user` change (its own comment), and that choice is sound. The rename case is separate.
+- `Bao.SshRole` and `Bao.Plugin` already answer `replace` on an identity change.

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