@homeflare/alchemy 0.7.0 → 0.8.0

package/src/launchd/sudo-runner.test.ts

@@ -0,0 +1,126 @@
+/**
+ * sudoRunner over the fake host (fake-sudo.ts): which calls reach sudo, in what exact argv, what
+ * is logged, and what is refused before sudo is ever asked. No real sudo runs anywhere.
+ * File writes and removes are in sudo-runner-files.test.ts.
+ */
+import { describe, expect, test } from 'bun:test';
+import { OPERATOR, PREFIXES, fakeSudoHost } from './fake-sudo.ts';
+import { LAUNCHCTL } from './launchctl.ts';
+import { RM, SUDO } from './sudo-allowlist.ts';
+import { SudoRefusedError, makeSudoRunner, sudoRunner } from './sudo-runner.ts';
+
+const PLIST = '/Library/LaunchDaemons/com.example.a.plist';
+const plistBytes = new TextEncoder().encode('<key>Label</key><string>com.example.a</string>');
+
+describe('what it claims', () => {
+  test('privileged, as the operator: it elevates calls, it is not root', () => {
+    const { runner } = fakeSudoHost();
+    expect(runner.privileged).toBe(true);
+    expect(runner.effectiveUid()).toBe(OPERATOR);
+  });
+
+  test('prefixes are required and checked when it is built', () => {
+    expect(() => sudoRunner({ prefixes: [] })).toThrow('no prefixes');
+    expect(() => sudoRunner({ prefixes: ['/'] })).toThrow('every path');
+  });
+});
+
+describe('exec', () => {
+  test('a system bootstrap runs as `sudo -n --`, logged once, argv only', async () => {
+    const host = fakeSudoHost();
+    host.fake.files.set(PLIST, { bytes: plistBytes, gid: 0, kind: 'file', mode: 0o644, uid: 0 });
+    const result = await host.runner.exec([LAUNCHCTL, 'bootstrap', 'system', PLIST]);
+    expect(result.exitCode).toBe(0);
+    expect(host.sudoCalls).toEqual([[SUDO, '-n', '--', LAUNCHCTL, 'bootstrap', 'system', PLIST]]);
+    expect(host.logs).toEqual([
+      `homeflare/launchd sudo -n ${JSON.stringify([LAUNCHCTL, 'bootstrap', 'system', PLIST])}`,
+    ]);
+  });
+
+  test('bootstrap of a plist that is not a plain file is refused before sudo', async () => {
+    const host = fakeSudoHost();
+    const missing = host.runner.exec([LAUNCHCTL, 'bootstrap', 'system', PLIST]);
+    // ★ The host checks throw the same class as the allowlist: nothing ran as root.
+    await expect(missing).rejects.toBeInstanceOf(SudoRefusedError);
+    await expect(missing).rejects.toThrow('is missing, not a file');
+    host.fake.files.set(PLIST, { bytes: plistBytes, gid: 0, kind: 'symlink', mode: 0o755, uid: 0 });
+    await expect(host.runner.exec([LAUNCHCTL, 'bootstrap', 'system', PLIST])).rejects.toThrow(
+      'is a symlink',
+    );
+    expect(host.sudoCalls).toEqual([]);
+    expect(host.logs).toEqual([]);
+  });
+
+  test('reads stay unelevated: no sudo, no log line', async () => {
+    const host = fakeSudoHost();
+    const result = await host.runner.exec([LAUNCHCTL, 'print', 'system/com.example.a']);
+    expect(result.exitCode).toBe(113);
+    await host.runner.exec([LAUNCHCTL, 'print-disabled', 'system']);
+    expect(host.sudoCalls).toEqual([]);
+    expect(host.logs).toEqual([]);
+  });
+
+  test.each([
+    ['a bare-domain bootout', [LAUNCHCTL, 'bootout', 'system']],
+    ["another user's gui domain", [LAUNCHCTL, 'bootout', 'gui/502/com.example.a']],
+    ['a sudo argv', [SUDO, '-n', RM, '-rf', '/']],
+  ])('%s is refused before sudo is asked', async (_name, argv) => {
+    const host = fakeSudoHost();
+    await expect(host.runner.exec(argv)).rejects.toBeInstanceOf(SudoRefusedError);
+    expect(host.sudoCalls).toEqual([]);
+    expect(host.logs).toEqual([]);
+  });
+
+  test('a password-required sudo fails at once, saying what to do', async () => {
+    const host = fakeSudoHost();
+    host.state.sudo = 'password';
+    const run = host.runner.exec([LAUNCHCTL, 'bootout', 'system/com.example.a']);
+    await expect(run).rejects.toBeInstanceOf(SudoRefusedError);
+    await expect(run).rejects.toThrow('a password is required');
+    await expect(run).rejects.toThrow('sudo -v');
+    expect(host.sudoCalls).toHaveLength(1);
+  });
+
+  test.each(['denied', 'not-in-sudoers', 'not-on-host'] as const)(
+    'a sudoers refusal (%s) is named as one',
+    async (refusal) => {
+      const host = fakeSudoHost();
+      host.state.sudo = refusal;
+      const run = host.runner.exec([LAUNCHCTL, 'bootout', 'system/com.example.a']);
+      await expect(run).rejects.toBeInstanceOf(SudoRefusedError);
+      await expect(run).rejects.toThrow('sudoers does not let');
+    },
+  );
+
+  test("launchctl's own failure comes back as a result, for the provider to judge", async () => {
+    const host = fakeSudoHost();
+    const result = await host.runner.exec([LAUNCHCTL, 'bootout', 'system/com.example.a']);
+    expect(result.exitCode).toBe(3);
+    expect(host.sudoCalls).toHaveLength(1);
+  });
+
+  test('a launchctl error that says "not allowed" is still launchctl\'s, not sudo\'s', async () => {
+    const host = fakeSudoHost();
+    host.fake.files.set(PLIST, { bytes: plistBytes, gid: 0, kind: 'file', mode: 0o644, uid: 0 });
+    // ⚠️ Exit 1 like sudo's own failures; only sudo's message forms may turn it into a refusal.
+    host.fake.state.bootstrapFailure = {
+      exitCode: 1,
+      stderr: 'Bootstrap failed: 1: service is not allowed to execute in this domain',
+      stdout: '',
+    };
+    const result = await host.runner.exec([LAUNCHCTL, 'bootstrap', 'system', PLIST]);
+    expect(result.exitCode).toBe(1);
+  });
+});
+
+test('makeSudoRunner validates prefixes too', () => {
+  const { fake } = fakeSudoHost();
+  const deps = {
+    base: fake.runner,
+    groups: async () => [],
+    log: () => undefined,
+    stage: async () => ({ dispose: async () => undefined, path: '' }),
+  };
+  expect(() => makeSudoRunner([], deps)).toThrow('no prefixes');
+  expect(() => makeSudoRunner(PREFIXES, deps)).not.toThrow();
+});

package/src/launchd/sudo-runner.ts

@@ -0,0 +1,235 @@
+/**
+ * sudoRunner(): the kit's one elevating HostRunner. The deploy runs as the operator, and only the
+ * calls that need root go through `sudo -n`, in the exact shapes sudo-allowlist.ts names:
+ *
+ * - `launchctl bootstrap | bootout | kickstart` in the system domain;
+ * - a file under a prefix the stack declared: staged in a private temp file as the operator, then
+ *   `sudo -n install -S -m <mode> [-o <uid>] [-g <gid>] <staged> <path>`; removed with
+ *   `sudo -n rm -f -- <path>`.
+ *
+ * Everything else (reads, lookups, the operator's own files and gui domain) goes to localRunner().
+ *
+ * ★ DECIDED 2026-09-21. A host stack deploys as the operator rather than as root, so a provider bug
+ *   or a wrong declaration can do no more than this list. It is an explicit opt-in,
+ *   `launchdProviders(sudoRunner({ prefixes }))`, and nothing ever falls back to it: localRunner()
+ *   stays the default and never elevates.
+ * ⛔ `sudo -n`, NEVER A PROMPT. A deploy that stops mid-apply to ask for a password is the failure
+ *   "no silent sudo" exists to prevent. With -n, sudo fails at once, and that failure becomes an
+ *   error saying what to do.
+ * ⛔ EVERY PRIVILEGED ARGV IS LOGGED BEFORE IT RUNS, and it is only ever an argv: a file's bytes
+ *   travel through the staged file, never through argv, so a log line cannot carry content.
+ * ★ `install -S`: install(1) on macOS 27.2 (read 2026-09-21) always writes a temp file in the
+ *   target directory and renames it, so the file is never torn, and -S adds the fsync that
+ *   localRunner's `handle.sync()` does.
+ * ⚠️ REASONED, NOT MEASURED: sudo's failure text. The kit never runs sudo. The strings below follow
+ *   sudoers(5) for sudo 1.9.17p2 on macOS 27.2 ("a password is required": -n was given but a
+ *   password was needed) and sudo(8) (sudo exits 1 when it fails itself).
+ */
+import { type LocalRunnerOptions, errnoCode, localRunner } from './local-runner.ts';
+import type { ExecResult, HostRunner } from './runner.ts';
+import {
+  INSTALL,
+  RM,
+  SUDO,
+  SudoRefusedError,
+  checkPrefixes,
+  octalMode,
+  prefixOf,
+  privilegedProblem,
+  routeExec,
+} from './sudo-allowlist.ts';
+import { assertPlainPath, assertReadableBack, operatorGroups } from './sudo-guard.ts';
+import { type Staged, stageFile } from './sudo-stage.ts';
+
+export { SudoRefusedError };
+
+export type SudoRunnerOptions = LocalRunnerOptions & {
+  /**
+   * The directories root may install into and remove from: `/Library/LaunchDaemons` for system
+   * jobs (bootstrap and bootout are refused without it), plus wherever the stack's root-owned
+   * HostFiles live. ⛔ Required: absolute, normalised, never `/`; and at every privileged call a
+   * real directory that root owns and only root may write (sudo-guard.ts). Outside every prefix a
+   * file is written as the deploying user, or refused when that needs root.
+   */
+  readonly prefixes: readonly string[];
+  /** Receives one line per privileged argv, before it runs. @default a line on stderr */
+  readonly log?: (line: string) => void;
+};
+
+/** What a sudo runner is built from. ★ Split out so the tests swap the host, never the logic. */
+export type SudoDeps = {
+  /** Runs everything, including `sudo` itself. localRunner() for the real one. */
+  readonly base: HostRunner;
+  readonly stage: (bytes: Uint8Array) => Promise<Staged>;
+  /** The deploying user's groups, for the read-back check; `undefined` when unknown. */
+  readonly groups: () => Promise<readonly number[] | undefined>;
+  readonly log: (line: string) => void;
+};
+
+/**
+ * ⚠️ ANCHORED TO sudo'S OWN MESSAGE FORMS (`sudo: …` lines, `Sorry, user …`), so a launchctl or
+ *   install error that happens to say "not allowed" is never reported as "the command did not run".
+ *   The refusals are the three a sudoers denial prints: the command not allowed, the user not in
+ *   sudoers, and the user not allowed on this host (`<user> is not allowed to run sudo on <host>.`).
+ *   REASONED from sudo 1.9's sudoers plugin, like the rest (header).
+ */
+const PASSWORD =
+  /^sudo: (?:a password is required|a terminal is required|sorry, you must have a tty)/m;
+const NOT_ALLOWED =
+  /^(?:Sorry, user \S+ (?:is not allowed to execute|may not run sudo)|\S+ is not (?:in the sudoers file|allowed to run sudo on ))/m;
+
+/** ★ An EACCES outside every prefix is almost always a directory the stack forgot to declare. */
+const undeclared =
+  (path: string, prefixes: readonly string[]) =>
+  (cause: unknown): never => {
+    const code = errnoCode(cause);
+    if (code !== 'EACCES' && code !== 'EPERM') throw cause;
+    throw new Error(
+      `sudoRunner ${path}: ${code} as the deploying user, and the path is under no declared prefix ` +
+        `(${prefixes.join(', ')}). If root owns its directory, declare that directory as a prefix.`,
+      { cause },
+    );
+  };
+
+export const makeSudoRunner = (prefixList: readonly string[], deps: SudoDeps): HostRunner => {
+  const prefixes = checkPrefixes(prefixList);
+  const { base } = deps;
+
+  /**
+   * ⛔ THE ONE PLACE `sudo` IS SPAWNED: allowlist, then any host check (`before`), then the log
+   *   line, then `sudo -n -- argv`.
+   */
+  const elevate = async (
+    argv: readonly string[],
+    { before, staged }: { before?: () => Promise<unknown>; staged?: string } = {},
+  ): Promise<ExecResult> => {
+    const shown = JSON.stringify(argv);
+    const problem = privilegedProblem(argv, {
+      prefixes,
+      ...(staged === undefined ? {} : { staged }),
+    });
+    if (problem !== undefined)
+      throw new SudoRefusedError(`sudoRunner refused ${shown}: ${problem}`);
+    await before?.();
+    deps.log(`homeflare/launchd sudo -n ${shown}`);
+    const result = await base.exec([SUDO, '-n', '--', ...argv]);
+    if (result.exitCode !== 1) return result;
+    if (PASSWORD.test(result.stderr)) {
+      throw new SudoRefusedError(
+        `sudo -n ${shown}: a password is required, and this runner never prompts. Run \`sudo -v\` ` +
+          'in the deploying terminal just before the deploy, or grant exactly these commands ' +
+          'NOPASSWD (docs/launchd-sudo.md). The command did not run.',
+      );
+    }
+    if (NOT_ALLOWED.test(result.stderr)) {
+      throw new SudoRefusedError(
+        `sudo -n ${shown}: sudoers does not let the deploying user run this. The command did not run.`,
+      );
+    }
+    return result;
+  };
+
+  /** A privileged file operation: anything but exit 0 is an error. ⚠️ stderr names paths only. */
+  const mustSucceed = async (argv: readonly string[], staged?: string): Promise<void> => {
+    const result = await elevate(argv, staged === undefined ? {} : { staged });
+    if (result.exitCode !== 0) {
+      const stderr = result.stderr.trim().slice(0, 300);
+      throw new Error(`sudo -n ${JSON.stringify(argv)} -> ${String(result.exitCode)}: ${stderr}`);
+    }
+  };
+
+  return {
+    effectiveUid: () => base.effectiveUid(),
+    exec: async (argv) => {
+      const route = routeExec(argv, base.effectiveUid());
+      if ('refuse' in route) throw new SudoRefusedError(`sudoRunner: ${route.refuse}`);
+      if (route.as === 'operator') return base.exec(argv);
+      // ⛔ bootstrap makes root read the plist: it must be a plain file exactly where argv says.
+      //   The allowlist has already put it under a prefix by the time `before` runs.
+      const plist = argv[1] === 'bootstrap' ? argv[3] : undefined;
+      const prefix = plist === undefined ? undefined : prefixOf(plist, prefixes);
+      return elevate(argv, {
+        before: async () => {
+          if (plist !== undefined && prefix !== undefined) {
+            await assertPlainPath(base, prefix, plist, 'file');
+          }
+        },
+      });
+    },
+    lookupGroup: (nameOrId) => base.lookupGroup(nameOrId),
+    lookupUser: (nameOrId) => base.lookupUser(nameOrId),
+    // ★ True, so the providers let a system-domain job through to this runner (canActAsRoot).
+    privileged: true,
+    readFile: (path) => base.readFile(path),
+    removeFile: async (path) => {
+      const prefix = prefixOf(path, prefixes);
+      if (prefix === undefined) return base.removeFile(path).catch(undeclared(path, prefixes));
+      /**
+       * ★ Nothing there is success without a privileged call, so an idempotent delete logs nothing.
+       * ⚠️ lstat the path FIRST: a directory on the way that is already gone means nothing is there
+       *   (HostRunner.removeFile is idempotent, and localRunner treats ENOENT/ENOTDIR so), where the
+       *   guard alone would refuse it as a missing directory.
+       */
+      if ((await base.stat(path)) === undefined) return;
+      await assertPlainPath(base, prefix, path, 'file');
+      await mustSucceed([RM, '-f', '--', path]);
+    },
+    sleep: (ms) => base.sleep(ms),
+    stat: (path) => base.stat(path),
+    writeFileAtomic: async (path, bytes, options) => {
+      const prefix = prefixOf(path, prefixes);
+      const operator = base.effectiveUid();
+      if (prefix === undefined) {
+        if (options.uid !== undefined && options.uid !== operator && operator !== 0) {
+          throw new SudoRefusedError(
+            `sudoRunner ${path}: owner ${String(options.uid)} needs root, and the path is under no ` +
+              `declared prefix (${prefixes.join(', ')}). Declare its directory, or deploy as root. ` +
+              'Nothing was written.',
+          );
+        }
+        return base.writeFileAtomic(path, bytes, options).catch(undeclared(path, prefixes));
+      }
+      const mode = octalMode(options.mode);
+      if (mode === undefined)
+        throw new SudoRefusedError(`sudoRunner ${path}: mode must be 0–0o7777`);
+      await assertPlainPath(base, prefix, path, 'file-or-absent');
+      await assertReadableBack(base, path, options, await deps.groups());
+      const staged = await deps.stage(bytes);
+      try {
+        await mustSucceed(
+          [
+            INSTALL,
+            '-S',
+            '-m',
+            mode,
+            ...(options.uid === undefined ? [] : ['-o', String(options.uid)]),
+            ...(options.gid === undefined ? [] : ['-g', String(options.gid)]),
+            staged.path,
+            path,
+          ],
+          staged.path,
+        );
+      } finally {
+        await staged.dispose();
+      }
+    },
+  };
+};
+
+/**
+ * The real sudo runner: localRunner() for everything, `/usr/bin/sudo -n` for the allowlist.
+ * Pass it explicitly: `launchdProviders(sudoRunner({ prefixes: ['/Library/LaunchDaemons'] }))`.
+ */
+export const sudoRunner = (options: SudoRunnerOptions): HostRunner => {
+  const base = localRunner(options);
+  return makeSudoRunner(options.prefixes, {
+    base,
+    groups: () => operatorGroups(base),
+    log:
+      options.log ??
+      ((line) => {
+        process.stderr.write(`${line}\n`);
+      }),
+    stage: stageFile,
+  });
+};

package/src/launchd/sudo-stage.ts

@@ -0,0 +1,28 @@
+/**
+ * Where sudo-runner.ts puts a file's bytes before `install` copies them into place as root.
+ *
+ * ★ WHY STAGE AT ALL. The deploying user cannot write inside a root-owned directory, and the bytes
+ *   must not travel through argv (they would reach the log and `ps`). So they are written, as the
+ *   deploying user, to a private file, and `install` copies that one file.
+ * ⛔ A 0700 DIRECTORY, A 0600 FILE, O_EXCL: between the write and the install, nobody but the
+ *   deploying user and root can read the bytes or swap the file.
+ */
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/** A file staged for `install`, and how to remove it again. */
+export type Staged = { readonly path: string; readonly dispose: () => Promise<void> };
+
+export const stageFile = async (bytes: Uint8Array): Promise<Staged> => {
+  const dir = await mkdtemp(join(tmpdir(), 'hf-sudo-'));
+  const dispose = () => rm(dir, { force: true, recursive: true });
+  try {
+    const path = join(dir, 'staged');
+    await writeFile(path, bytes, { flag: 'wx', mode: 0o600 });
+    return { dispose, path };
+  } catch (cause) {
+    await dispose();
+    throw cause;
+  }
+};

package/src/openbao/README.md

@@ -14,6 +14,11 @@ plus `FetchHttpClient.layer`.
   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.
+- ⛔ A rename or move onto a name or path that already exists fails the plan, before anything is
+  written (every family but the mounts, whose moves are below). Move through a free name, in two
+  deploys, or remove the target first.
+- ⚠️ A NEW logical id for a live name adopts it, and under `destroy` the old id's delete then
+  removes it. Change a logical id with Alchemy's `renamedFrom` (REPLACE.md).
 
 ## assertBaoIdentity: call it first
 
@@ -70,9 +75,10 @@ export const hostRoles = Effect.gen(function* () {
 - 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.
+  classes and a host listed twice in one class. A host in several classes gets one role per class.
 - ⚠️ Renaming a host or class makes a new role. Under `retain` the old one stays live and keeps
-  admitting its secret_ids (REPLACE.md).
+  admitting its secret_ids (REPLACE.md). Under `destroy` its secret_ids go, but tokens it already
+  issued run to their TTL: deleting a role revokes no token.
 
 ## BaoJwtRole / BaoKubernetesRole / BaoJwtAuthConfig
 

package/src/openbao/REPLACE.md

@@ -4,9 +4,10 @@ Audited 2026-09-21, against `alchemy@2.0.0-beta.79` and OpenBao v2.6.2 source, i
 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.
+in-memory state store against the fake engines in `fake-engines.ts` and `fake-engines-roles.ts`.
+`policy-rename.test.ts`, `role-rename.test.ts`, `rename-occupied.test.ts`,
+`rename-families.test.ts`, `rename-identity.test.ts` and `rename-adoption.test.ts` deploy, rename,
+and deploy again, then check the plan and every call that reached the fake.
 
 ## What Alchemy does with each answer
 
@@ -44,46 +45,60 @@ 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.         |
+⛔ Every family below except `Bao.Mount` and `Bao.AuthMethod` judges its identity **before**
+`isResolved(news)`, and **fails the plan** on a move onto an object that already exists
+(`rename-identity.ts`, below). Names compare as the server keys them: exact, except where a row
+says folded.
+
+| 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` (folded)           | `replace`. Before 2026-09-21 it was `update`, and the old role was orphaned. Its delete clears the secret_ids; issued tokens run to their TTL (below).                | `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` (folded)  | `replace`. The name is folded: the server reads it lowercased (TypeLowerCaseString).                                                                                  | `update` (merge write; every managed field is sent)                                         |
+| `Bao.KubernetesRole`      | `mount`, `name` (folded)  | `replace`. The name is folded, as the server stores it.                                                                                                               | `update`                                                                                    |
+| `Bao.JwtAuthConfig`       | `mount`                   | `replace`. The old delete is a no-op because there is no delete endpoint. A move onto a mount with a config fails the plan too: it would rewrite that mount's logins. | `update` (full-replace write)                                                               |
+| `Bao.MfaTotpMethod`       | `name`                    | ⛔ **fails the plan**: a new id would strand every enrolled secret. Reconcile refuses it too, when the name was an Output.                                            | `update` (the upsert keeps the id)                                                          |
+| `Bao.MfaLoginEnforcement` | `name`                    | `replace`. Its delete is **refused** (openbao#4030)                                                                                                                   | `update`                                                                                    |
+| `Bao.SshRole`             | `mount`, `name`           | `replace`                                                                                                                                                             | `update` (full-replace write)                                                               |
+| `Bao.Plugin`              | `type`, `name`, `version` | `replace`: a version bump is a new catalog entry, and `retain` keeps the old version registered.                                                                      | `update` (full-replace register)                                                            |
+| `Bao.Policy`              | `name`                    | `replace` (batch 3A). Compared as OpenBao keys it, trimmed and lowercased, so `Admin` → `admin` is the same policy: `noop`.                                           | `update` (fragments digest)                                                                 |
+| `Bao.CloudflareRole`      | `mount`, `name`           | `replace` (batch 3A). Exact; a trailing `/` on the mount is the same path.                                                                                            | `update`                                                                                    |
+| `Bao.ProxmoxRole`         | `mount`, `name`           | `replace` (batch 3A). ⛔ **Fails the plan** 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.
+`Bao.AuthRole` plans a `replace`. Under the default `retain`, both leave the old role live. A
+host may sit in several classes: it gets one role per class, and only the same host twice in one
+class is refused.
 
 ## 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.
+  changing). Every family judges the identity props before `isResolved(news)`
+  (`rename-identity.ts`), so the rename still plans `replace`. Measured for all twelve. Before
+  2026-09-21 the nine batch-2 families planned `update` here and orphaned the old object.
 - **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.
+  old attributes. The next deploy sees both names and plans `replace`. Measured for all twelve.
+  `Bao.MfaTotpMethod` refuses there with its rename refusal, and its next plan fails the same way.
 - `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
+⛔ Every family in the table reads the new path at plan (`judgeMove`, `rename.ts`) and refuses 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:
+deploy was green, and both policies were gone, every grant revoked. The same swap deleted both
+objects for `Bao.AuthRole`, `Bao.PkiRole`, `Bao.JwtRole`, `Bao.KubernetesRole`, `Bao.SshRole` and
+`Bao.Plugin`. `Bao.JwtAuthConfig` (no delete) and `Bao.MfaLoginEnforcement` (delete refused) lost
+nothing, but each new generation silently rewrote the other's live object. 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;
@@ -94,10 +109,12 @@ deploy was green, and both policies were gone, every grant revoked. Measured the
 
 ⚠️ 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.
+through a name nothing holds, or remove the target by hand first. For `Bao.Plugin` that includes a
+version bump onto a version already registered by hand. A change of case the server folds (policy,
+AppRole, JWT and Kubernetes role names), or a trailing `/` on a mount, is the same object, so it is
+not a move and is never refused (`rename-identity.test.ts`).
 
-## What `retain` means for these three
+## What `retain` means for batch 3A and AppRole
 
 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:
@@ -112,13 +129,27 @@ retained."). It is live and unmanaged from then on:
 - **`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`).
+- **`Bao.AuthRole`**: the old role keeps admitting its secret_ids. Under `destroy` the delete
+  removes every secret_id and the role_id, so no new login succeeds, but it revokes no token:
+  tokens already issued live to their TTL and only fail to renew (openbao v2.6.2 approle
+  `pathRoleDelete`, path_role.go:1858-1902; `pathLoginRenew`, path_login.go:414-438). Revoke by
+  accessor to contain one.
 
 ★ 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.
+## A new declaration of a live name: the swap the guard cannot see
+
+⚠️ A NEW logical id whose name already exists takes that object over and rewrites it: these
+families' `read` never answers `Unowned`, so Alchemy silently adopts it. Nothing moved, so
+`judgeMove` never runs. 🔴 Measured (`rename-adoption.test.ts`): under `destroy` the old owner's
+delete then runs after the adoption wrote, and removes the object the new id now claims, in a
+green deploy. It happened when a logical id changed with the name kept, to each of the nine
+batch-2 families whose delete runs (a TOTP method and its enrolments included), and when a new
+`Bao.AuthRole` took a name another one moved off in the same deploy. Change a logical id with
+Alchemy's `renamedFrom('<old id>')`, which migrates the state row and plans an `update`. Take a
+freed name in the deploy after the move.
 
 ## Why the moves fail instead of replacing
 
@@ -152,12 +183,9 @@ take every secret with it. (Corrected 2026-09-21: the first audit listed this as
 3. **Unique names need `deleteFirst`.** Only a mount's `type` change keeps its unique path, and
    it fails on purpose instead (above).
 
-## Open
+## Closed
 
-- ⚠️ **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.)
+- ✅ **Nine families checked the identity after `isResolved(news)`** and never read the target
+  (closed 2026-09-21 by `rename-identity.ts`, measured in `rename-families.test.ts`).
+  `Bao.Mount` and `Bao.AuthMethod` never needed it: their reconcile re-plans the move from the
+  stated path.

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

@@ -5,17 +5,11 @@
  *   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.
+ * (What the diff calls a rename is pinned in rename-families.test.ts, `foldName`.)
  */
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
-import {
-  type BaoAuthRoleProps,
-  attributesOf,
-  isRename,
-  matches,
-  writeBody,
-} from './auth-role-form.ts';
+import { type BaoAuthRoleProps, attributesOf, matches, writeBody } from './auth-role-form.ts';
 
 const PROPS: BaoAuthRoleProps = {
   bindSecretId: true,
@@ -47,11 +41,3 @@ 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,17 +89,6 @@ 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]);