@homeflare/alchemy 0.4.1 → 0.6.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));

package/src/openbao/auth-method-form.ts

@@ -18,6 +18,13 @@ export interface BaoAuthMethodProps {
   defaultLeaseTtl?: string;
   /** Max lease TTL, e.g. `8760h`. */
   maxLeaseTtl?: string;
+  /**
+   * The path this method lives at NOW, when `path` is where it should move to — `sys/remount`
+   * from `auth/<remountFrom>`, keeping every role. Without it a changed `path` fails the plan
+   * (mount-move.ts). ⚠️ Every token issued through the method is revoked by the move, and login
+   * URLs, policies and MFA enforcements by accessor are not rewritten (the accessor is kept).
+   */
+  remountFrom?: string;
 }
 
 export interface BaoAuthMethodAttributes {

package/src/openbao/auth-method-reconcile.ts

@@ -0,0 +1,74 @@
+/**
+ * Bao.AuthMethod's read and reconcile as plain effects — split from auth-method.ts so the move runs
+ * against a fake server. Same shape as mount-reconcile.ts; the one difference that matters is the
+ * `auth/` prefix sys/remount needs (vault/logical_system.go:1295-1310 refuses to move an auth mount
+ * to a non-auth path, and `token/` cannot move at all).
+ */
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import {
+  type BaoAuthMethodAttributes,
+  type BaoAuthMethodProps,
+  attributesOf,
+  authPath,
+  matches,
+  wantsTune,
+} from './auth-method-form.ts';
+import { enableAuthMethod, readAuthMethodData, tuneAuthMethod } from './auth-method-wire.ts';
+import type { BaoError } from './bao-status.ts';
+import { type MoveTarget, performMove, planMove } from './mount-move.ts';
+import type { RemountError, RemountOptions } from './remount-wire.ts';
+
+export const readMethod = (
+  props: BaoAuthMethodProps,
+): Effect.Effect<BaoAuthMethodAttributes | undefined, BaoError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const live = yield* readAuthMethodData(props.path);
+    if (live === undefined) return undefined;
+    return attributesOf(props, live);
+  });
+
+const moveTarget = (props: BaoAuthMethodProps): MoveTarget => ({
+  family: 'Bao.AuthMethod',
+  path: props.path,
+  read: (path) => readMethod({ ...props, path }),
+  type: props.type,
+  wire: (path) => `auth/${authPath(path)}`,
+});
+
+/** Converge one auth method. `stated` is the path in Alchemy's state, if any. */
+export const reconcileAuthMethod = (
+  news: BaoAuthMethodProps,
+  stated: string | undefined,
+  options?: RemountOptions,
+): Effect.Effect<BaoAuthMethodAttributes, BaoError | RemountError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const move = planMove('Bao.AuthMethod', stated, news.path, news.remountFrom);
+    if (move.kind === 'refuse') return yield* Effect.die(new Error(move.message));
+    if (move.kind === 'move') yield* performMove(moveTarget(news), move.from, options);
+
+    let live = yield* readMethod(news);
+    if (live === undefined) {
+      yield* enableAuthMethod(news);
+      if (wantsTune(news)) yield* tuneAuthMethod(news);
+    } else if (!matches(live, news)) {
+      if (live.type !== news.type) {
+        return yield* Effect.die(
+          new Error(
+            `Bao.AuthMethod ${authPath(news.path)}: live type ${live.type} != ${news.type}. ` +
+              'Auth method type is immutable — replace manually.',
+          ),
+        );
+      }
+      yield* tuneAuthMethod(news);
+    }
+    live = yield* readMethod(news);
+    if (live === undefined) {
+      return yield* Effect.die(
+        new Error(
+          `Bao.AuthMethod ${authPath(news.path)}: write returned no error but the method is still absent.`,
+        ),
+      );
+    }
+    return live;
+  });

package/src/openbao/auth-method.ts

@@ -7,6 +7,12 @@
  * ★ `defaultRemovalPolicy: 'retain'` — disabling a method destroys every role under it
  *   and revokes tokens minted through those roles. Opt in with
  *   `.pipe(RemovalPolicy.destroy())`.
+ *
+ * ★ REPLACE SEMANTICS (audited 2026-09-21, see REPLACE.md): `type` changed → plans `replace`, whose
+ *   create half dies on the still-occupied path before any write, so the apply fails and nothing is
+ *   disabled (auth-method-reconcile.ts); `path` changed → FAILS unless `remountFrom` names the old
+ *   path (then an in-place move). It used to plan `update` and enable an empty method at the new
+ *   path, exactly as Bao.Mount did.
  */
 import { Resource } from 'alchemy';
 import { isResolved } from 'alchemy/Diff';
@@ -16,17 +22,11 @@ import type * as HttpClient from 'effect/unstable/http/HttpClient';
 import {
   type BaoAuthMethodAttributes,
   type BaoAuthMethodProps,
-  attributesOf,
-  authPath,
   matches,
-  wantsTune,
 } from './auth-method-form.ts';
-import {
-  disableAuthMethod,
-  enableAuthMethod,
-  readAuthMethodData,
-  tuneAuthMethod,
-} from './auth-method-wire.ts';
+import { readMethod, reconcileAuthMethod } from './auth-method-reconcile.ts';
+import { disableAuthMethod } from './auth-method-wire.ts';
+import { planMove } from './mount-move.ts';
 
 export type { BaoAuthMethodAttributes, BaoAuthMethodProps };
 
@@ -42,13 +42,6 @@ export const BaoAuthMethod = Resource<BaoAuthMethod>('Bao.AuthMethod', {
   defaultRemovalPolicy: 'retain',
 });
 
-const readMethod = (props: BaoAuthMethodProps) =>
-  Effect.gen(function* () {
-    const live = yield* readAuthMethodData(props.path);
-    if (live === undefined) return undefined;
-    return attributesOf(props, live);
-  });
-
 export const BaoAuthMethodProvider = () =>
   Provider.effect(
     BaoAuthMethod,
@@ -67,6 +60,14 @@ export const BaoAuthMethodProvider = () =>
 
         diff: Effect.fn(function* ({ news, output }) {
           if (output === undefined || !isResolved(news)) return undefined;
+          /**
+           * ⛔ A CHANGED PATH FAILS HERE unless `remountFrom` names the old one — the same trap
+           *   Bao.Mount had: reading the new path finds nothing, plans `update`, and enables an
+           *   EMPTY method beside the retained one, with every role left behind (mount-move.ts).
+           */
+          const move = planMove('Bao.AuthMethod', output.path, news.path, news.remountFrom);
+          if (move.kind === 'refuse') return yield* Effect.die(new Error(move.message));
+          if (move.kind === 'move') return { action: 'update' } as const;
           const live = yield* readMethod(news);
           if (live === undefined) return { action: 'update' } as const;
           /**
@@ -79,31 +80,9 @@ export const BaoAuthMethodProvider = () =>
           return { action: 'update' } as const;
         }),
 
-        reconcile: Effect.fn(function* ({ news }) {
-          let live = yield* readMethod(news);
-          if (live === undefined) {
-            yield* enableAuthMethod(news);
-            if (wantsTune(news)) yield* tuneAuthMethod(news);
-          } else if (!matches(live, news)) {
-            if (live.type !== news.type) {
-              return yield* Effect.die(
-                new Error(
-                  `Bao.AuthMethod ${authPath(news.path)}: live type ${live.type} != ${news.type}. ` +
-                    'Auth method type is immutable — replace manually.',
-                ),
-              );
-            }
-            yield* tuneAuthMethod(news);
-          }
-          live = yield* readMethod(news);
-          if (live === undefined) {
-            return yield* Effect.die(
-              new Error(
-                `Bao.AuthMethod ${authPath(news.path)}: write returned no error but the method is still absent.`,
-              ),
-            );
-          }
-          return live;
+        /** The body, and the move, live in auth-method-reconcile.ts. */
+        reconcile: Effect.fn(function* ({ news, output }) {
+          return yield* reconcileAuthMethod(news, output?.path);
         }),
 
         /**

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

@@ -0,0 +1,57 @@
+/**
+ * Bao.AuthRole's secret_id TTL at the 90-day length the per-host AppRoles use.
+ *
+ * ★ `2160h` IS WHAT GOES ON THE WIRE, AND OPENBAO ACCEPTS IT. MEASURED 2026-09-21 with a Go probe of
+ *   sdk v2.6.2 framework.FieldData.Validate on the approle role fields (path_role.go:166-167,
+ *   TypeDurationSecond): `secret_id_ttl: "2160h"` validates and parses to 7776000 seconds. A role
+ *   read hands back that integer, which attributesOf renders as `90d` — the same role.
+ * And what the diff calls a rename (a `replace`): only a change the server would not fold away.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  type BaoAuthRoleProps,
+  attributesOf,
+  isRename,
+  matches,
+  writeBody,
+} from './auth-role-form.ts';
+
+const PROPS: BaoAuthRoleProps = {
+  bindSecretId: true,
+  name: 'host-cert',
+  secretIdNumUses: 0,
+  secretIdTtl: '2160h',
+  tokenMaxTtl: '1h',
+  tokenPolicies: ['host-cert', 'default'],
+  tokenTtl: '15m',
+};
+
+describe('auth role secret_id TTL', () => {
+  it('writes 2160h as given', () => {
+    assert.equal(writeBody(PROPS)['secret_id_ttl'], '2160h');
+  });
+
+  it('reads 7776000 seconds back as the same role', () => {
+    const live = {
+      bind_secret_id: true,
+      secret_id_num_uses: 0,
+      secret_id_ttl: 7776000,
+      token_max_ttl: 3600,
+      token_policies: ['default', 'host-cert'],
+      token_ttl: 900,
+    };
+    const attributes = attributesOf(PROPS, live);
+    assert.equal(attributes.secretIdTtl, '90d');
+    assert.equal(matches(attributes, PROPS), true);
+    assert.equal(matches(attributesOf(PROPS, { ...live, secret_id_ttl: 0 }), PROPS), false);
+  });
+});
+
+describe('auth role rename', () => {
+  it('is a rename only when the lower-cased names differ, as the server stores them', () => {
+    assert.equal(isRename('pve-node--node-a', 'pve-node--node-b'), true);
+    assert.equal(isRename('Host-Cert', 'host-cert'), false);
+    assert.equal(isRename('host-cert', 'host-cert'), false);
+  });
+});

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

@@ -89,6 +89,17 @@ export const writeBody = (props: BaoAuthRoleProps): Record<string, string> => {
   return body;
 };
 
+/**
+ * Whether a changed `name` names a DIFFERENT role — the diff's `replace` question.
+ *
+ * ⚠️ CASE-INSENSITIVELY, BECAUSE THE SERVER IS. AppRole stores `role/<lowercased name>` (openbao
+ *   v2.6.2 builtin/credential/approle/path_role.go:1485, and roleEntry reads the same key, :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.
+ */
+export const isRename = (from: string, to: string): boolean =>
+  from.toLowerCase() !== to.toLowerCase();
+
 const samePolicies = (want: readonly string[], have: readonly string[]) =>
   want.length === have.length && want.every((policy, index) => policy === have[index]);
 

package/src/openbao/auth-role.ts

@@ -17,6 +17,7 @@ import {
   type BaoAuthRoleAttributes,
   type BaoAuthRoleProps,
   attributesOf,
+  isRename,
   matches,
   readPath,
   writeBody,
@@ -66,6 +67,17 @@ export const BaoAuthRoleProvider = () =>
          */
         diff: Effect.fn(function* ({ news, output }) {
           if (output === undefined || !isResolved(news)) return undefined;
+          /**
+           * ⛔ A RENAMED ROLE IS A NEW ROLE — NEW role_id, NEW secret_ids — SO IT IS A `replace`.
+           *   Until 2026-09-21 a new `name` read nothing, planned `update` and wrote the new role,
+           *   leaving the old one live under no state record: its secret_ids kept logging in for
+           *   their whole TTL, and no plan would ever mention it again (REPLACE.md).
+           * ⚠️ UNDER THE DEFAULT `retain` THE OLD ROLE STILL STAYS LIVE — retain keeps the old
+           *   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.
+           */
+          // ⚠️ Case-insensitively, because the server is — the ⚠️ on isRename in auth-role-form.ts.
+          if (isRename(output.name, news.name)) return { action: 'replace' } as const;
           const live = yield* readRole(news);
           if (live === undefined) return { action: 'update' } as const;
           if (matches(live, news)) return { action: 'noop' } as const;