@homeflare/alchemy 0.5.0 → 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/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

@@ -5,10 +5,17 @@
  *   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, matches, writeBody } from './auth-role-form.ts';
+import {
+  type BaoAuthRoleProps,
+  attributesOf,
+  isRename,
+  matches,
+  writeBody,
+} from './auth-role-form.ts';
 
 const PROPS: BaoAuthRoleProps = {
   bindSecretId: true,
@@ -40,3 +47,11 @@ describe('auth role secret_id TTL', () => {
     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;