@homeflare/alchemy 0.5.0 → 0.7.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,163 @@
+# Replace semantics: the `Bao.*` providers
+
+Audited 2026-09-21, against `alchemy@2.0.0-beta.79` and OpenBao v2.6.2 source, in two batches.
+Every kit provider must answer `replace` correctly (vault consolidation plan, "Replace freely").
+
+★ **Measured, not only read.** `fake-stack.ts` runs beta.79's own `Plan.make` and `apply` over an
+in-memory state store against the fake engines in `fake-engines.ts`. `policy-rename.test.ts`,
+`role-rename.test.ts` and `rename-occupied.test.ts` deploy, rename, and deploy again, then check
+the plan and every call that reached the fake.
+
+## 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).
+  ★ That delete gets the **old** generation's attributes (`output: old.attr`), so a provider that
+  deletes by `output` deletes the old path. Measured: `PUT` of the new path, then `DELETE` of the
+  old one.
+- **No answer** (`undefined`, which every diff returns while `news` holds a pending Output): the
+  engine plans `update` if any prop changed (`Plan.ts`, `havePropsChanged`). ⚠️ That is the bug
+  class below whenever the identity changed too.
+- **`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.
+
+🔴 Reproduced through the engine on 2026-09-21 for `Bao.Policy` under `RemovalPolicy.destroy()`:
+deploy `app-old`, redeclare it as `app-new`, deploy. The plan said `update`, and both policies
+stayed live. `destroy` could not help, because nothing recorded the old one.
+
+## Answers, by resource
+
+| 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`                                                                                    |
+| `Bao.Policy`              | `name`          | `replace` (batch 3A). Compared as OpenBao keys it, trimmed and lowercased, so `Admin` → `admin` is the same policy: `noop`. ⛔ **Fails the plan** onto a name that exists (below). | `update` (fragments digest)                                                                 |
+| `Bao.CloudflareRole`      | `mount`, `name` | `replace` (batch 3A). Exact; a trailing `/` on the mount is the same path. ⛔ **Fails the plan** onto a role that exists (below).                                                  | `update`                                                                                    |
+| `Bao.ProxmoxRole`         | `mount`, `name` | `replace` (batch 3A). ⛔ **Fails the plan** onto a role that exists, or if the rename also changes `mintUser` unless `allowMintUserChange` names the old one.                      | `update`. A `mintUser` change at the same path is refused at apply, never replaced.         |
+
+`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.
+
+## When the new identity is not known at plan
+
+- **Only another prop is pending** (say `fragments` is an Output of an upstream that is also
+  changing). `Bao.Policy`, `Bao.CloudflareRole` and `Bao.ProxmoxRole` judge the identity props
+  before `isResolved(news)` (`rename.ts`), so the rename still plans `replace`. Measured.
+- **The identity itself is pending.** Then the diff defers: it never answers `replace` on an
+  unknown identity, because under `destroy` a replace onto the same path deletes what it just
+  wrote. The engine plans `update`, and reconcile, seeing the old attributes name another
+  object, **refuses before any write**. The row is left `updating`, with the new props and the
+  old attributes. The next deploy sees both names and plans `replace`. Measured, for all three.
+- `Bao.ProxmoxRole` defers the same way while `mintUser` or `allowMintUserChange` is pending on a
+  rename, because the re-scope guard cannot be checked. Measured for `allowMintUserChange`.
+
+## A move onto an object that already exists fails the plan
+
+⛔ All three read the new path at plan (`judgeMove`, `rename.ts`) and refuse the move if anything
+is there. 🔴 Measured before the guard: two policies that swapped names under
+`RemovalPolicy.destroy()` both planned `replace`. Each new generation wrote over the other's live
+policy, and each old generation's delete then removed the name the other had just written. The
+deploy was green, and both policies were gone, every grant revoked. Measured the same way:
+
+- a shift (`a → b` while `b → c`) deleted `b`, and a move onto the name of a resource leaving the
+  stack deleted the name it moved onto;
+- reverting a move whose new generation failed. The old generation still holds the name, and its
+  delete runs after the revert rewrites it. So the diff compares against the props of an
+  unfinished create or replacement when there are no attributes yet. Declaring the new name again
+  finishes the move instead.
+
+⚠️ The diff cannot see the removal policy, so this refuses under `retain` too, where a swap would
+have been harmless. So would a move back onto a retained old generation. Move in two deploys
+through a name nothing holds, or remove the target by hand first. A change of policy-name case, or
+a trailing `/` on a mount, is the same object, so it is not a move and is never refused.
+
+## What `retain` means for these three
+
+Under the default `retain` the old generation is kept, and the apply says so ("Replaced resource
+retained."). It is live and unmanaged from then on:
+
+- **`Bao.Policy`**: the old policy keeps every grant, for every token, role and group that still
+  names it. Under `destroy` they lose those grants at the delete. ⚠️ Only a role that takes the
+  policy's `name` Output follows the rename in the same graph. A role that names the policy as a
+  literal string (`tokenPolicies: ['deploy']`) keeps the old name, so change it in the same PR.
+- **`Bao.CloudflareRole`**: the old role still mints, for any token whose ACL reaches its
+  `creds/<name>`. Under `destroy` every consumer still minting from the old path fails. Tokens
+  already minted are leases and live to their own expiry either way.
+- **`Bao.ProxmoxRole`**: the same, and the old role keeps minting under its old `mint_user`. The
+  plugin's delete leaves outstanding leases revocable (its own
+  `TestDeletingARoleLeavesItsOutstandingLeasesRevocable`).
+
+★ A stack that puts `mount` and `name` in the logical id, as homeflare-openbao's
+`declareCloudflareRoles` does, never reaches the `replace`: the old id leaves the stack as an
+orphan delete, which `retain` also keeps live.
+
+⚠️ A NEW declaration (a new logical id) of a name that already exists still takes that object over
+and rewrites it: these families' `read` never answers `Unowned`, so Alchemy adopts it.
+
+## 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).
+
+## Open
+
+- ⚠️ **Nine families still check the identity after `isResolved(news)`**: `Bao.AuthRole`,
+  `Bao.PkiRole`, `Bao.JwtRole`, `Bao.KubernetesRole`, `Bao.JwtAuthConfig`, `Bao.MfaTotpMethod`,
+  `Bao.MfaLoginEnforcement`, `Bao.SshRole` and `Bao.Plugin`. A rename that lands in the same
+  deploy as any pending Output plans `update`, and none of their reconciles has the moved-update
+  guard. For `Bao.MfaTotpMethod` that writes a second method and strands every enrolment. The
+  helpers in `rename.ts` close it the same way. (`Bao.Mount` and `Bao.AuthMethod` are safe: their
+  reconcile re-plans the move from the stated path.)

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;