@homeflare/alchemy 0.39.0 → 0.41.0

package/src/ceph/ceph-argv.test.ts

@@ -0,0 +1,226 @@
+/**
+ * The ceph allowlist, as pure argv checks — no ssh, no fake dial. Every acceptance is a shape
+ * ceph-argv.ts's own builders actually produce; every refusal is a shape that would do real damage
+ * (a printed key, a cut mon, a de-authenticated cluster) if it ever reached `sudo -n ceph`.
+ */
+import { describe, expect, test } from 'bun:test';
+import {
+  CEPH_BIN,
+  authCapsArgv,
+  authGetArgv,
+  authGetOrCreateArgv,
+  boundedEntityProblem,
+  cephCommandProblem,
+  configValueProblem,
+  quorumStatusArgv,
+} from './ceph-argv.ts';
+
+const ENTITY = 'client.k8s-rbd';
+const CAPS = {
+  mgr: 'profile rbd pool=k8s-rbd',
+  mon: 'profile rbd',
+  osd: 'profile rbd pool=k8s-rbd',
+};
+
+describe('the allowed shapes, byte-for-byte', () => {
+  test('auth get', () => {
+    expect(cephCommandProblem(authGetArgv(ENTITY))).toBeUndefined();
+    expect(authGetArgv(ENTITY)).toEqual([CEPH_BIN, 'auth', 'get', ENTITY, '-f', 'json']);
+  });
+
+  test('auth get-or-create', () => {
+    expect(cephCommandProblem(authGetOrCreateArgv(ENTITY, CAPS))).toBeUndefined();
+    expect(authGetOrCreateArgv(ENTITY, CAPS)).toEqual([
+      CEPH_BIN,
+      'auth',
+      'get-or-create',
+      ENTITY,
+      'mon',
+      CAPS.mon,
+      'osd',
+      CAPS.osd,
+      'mgr',
+      CAPS.mgr,
+      '-f',
+      'json',
+    ]);
+  });
+
+  test('auth caps', () => {
+    expect(cephCommandProblem(authCapsArgv(ENTITY, CAPS))).toBeUndefined();
+  });
+
+  test('quorum_status', () => {
+    expect(cephCommandProblem(quorumStatusArgv())).toBeUndefined();
+    expect(quorumStatusArgv()).toEqual([CEPH_BIN, 'quorum_status', '-f', 'json']);
+  });
+});
+
+describe('the entity prefix', () => {
+  test('accepts a bounded client.k8s- name', () => {
+    expect(boundedEntityProblem('client.k8s-rbd')).toBeUndefined();
+    expect(boundedEntityProblem('client.k8s-cephfs')).toBeUndefined();
+  });
+
+  test.each([
+    ['the cluster admin keyring', 'client.admin'],
+    ['a mon keyring', 'mon.a'],
+    ['an osd keyring', 'osd.0'],
+    ['an mgr keyring', 'mgr.a'],
+    ['the PVE storage client', 'client.pve-storage'],
+    ['a bare client prefix', 'client.k8s-'],
+    ['no client prefix at all', 'k8s-rbd'],
+  ])('refuses %s', (_name, entity) => {
+    expect(boundedEntityProblem(entity)).toBeString();
+    expect(cephCommandProblem(authGetArgv(entity))).toBeString();
+  });
+});
+
+describe('shell metacharacters never reach the allowlist as data', () => {
+  test.each([
+    ['in the entity', authGetArgv('client.k8s-rbd; rm -rf /')],
+    ['in a cap, backtick', authGetOrCreateArgv(ENTITY, { ...CAPS, osd: 'profile rbd `id`' })],
+    ['in a cap, command substitution', authCapsArgv(ENTITY, { ...CAPS, mon: '$(whoami)' })],
+    ['in a cap, a pipe', authCapsArgv(ENTITY, { ...CAPS, mgr: 'profile rbd | cat /etc/passwd' })],
+    [
+      'in a cap, a semicolon',
+      authCapsArgv(ENTITY, { ...CAPS, mon: 'profile rbd; ceph auth del client.admin' }),
+    ],
+  ])('refuses %s', (_name, argv) => {
+    expect(cephCommandProblem(argv)).toBeString();
+  });
+});
+
+describe('K-A4 finding 3: caps are the design’s literal shape, not a general grammar', () => {
+  test.each([
+    ['plain rwx, no profile at all', 'osd', 'allow rwx'],
+    ['a non-rbd profile', 'osd', 'profile osd'],
+    ['bootstrap-osd', 'osd', 'profile bootstrap-osd'],
+    ['a comma-chained extra grant', 'osd', 'profile rbd pool=k8s-rbd, allow rwx'],
+    ['osd rbd with no pool — every pool, VM disks included', 'osd', 'profile rbd'],
+    ['mgr rbd with no pool', 'mgr', 'profile rbd'],
+    ['mon widened past the plain profile', 'mon', 'profile rbd pool=k8s-rbd'],
+  ])('refuses %s (%s cap %j)', (_name, daemon, value) => {
+    const caps = { ...CAPS, [daemon]: value };
+    expect(cephCommandProblem(authGetOrCreateArgv(ENTITY, caps))).toBeString();
+    expect(cephCommandProblem(authCapsArgv(ENTITY, caps))).toBeString();
+  });
+
+  test('the design’s own three caps are still accepted', () => {
+    expect(cephCommandProblem(authGetOrCreateArgv(ENTITY, CAPS))).toBeUndefined();
+  });
+});
+
+describe('the never-allowed auth verbs', () => {
+  test('auth ls is refused, naming the reason', () => {
+    const problem = cephCommandProblem([CEPH_BIN, 'auth', 'ls', '-f', 'json']);
+    expect(problem).toContain('prints every key');
+  });
+
+  test('auth del is refused, naming lockout safety, for any entity', () => {
+    for (const entity of [ENTITY, 'client.admin', 'mon.a']) {
+      const problem = cephCommandProblem([CEPH_BIN, 'auth', 'del', entity, '-f', 'json']);
+      expect(problem).toContain('never auto-delete');
+    }
+  });
+});
+
+describe('shape mismatches', () => {
+  test.each([
+    ['bare ceph, no group', [CEPH_BIN]],
+    ['an unknown group', [CEPH_BIN, 'status', '-f', 'json']],
+    ['auth get with an extra operand', [CEPH_BIN, 'auth', 'get', ENTITY, 'extra', '-f', 'json']],
+    ['auth get with an unexpected flag', [CEPH_BIN, 'auth', 'get', ENTITY, '--yes', '-f', 'json']],
+    [
+      'auth get-or-create missing a daemon',
+      [CEPH_BIN, 'auth', 'get-or-create', ENTITY, 'mon', CAPS.mon, '-f', 'json'],
+    ],
+    [
+      'auth caps with daemons out of order',
+      [
+        CEPH_BIN,
+        'auth',
+        'caps',
+        ENTITY,
+        'osd',
+        CAPS.osd,
+        'mon',
+        CAPS.mon,
+        'mgr',
+        CAPS.mgr,
+        '-f',
+        'json',
+      ],
+    ],
+    ['missing the -f json suffix', [CEPH_BIN, 'auth', 'get', ENTITY]],
+    ['-f without json', [CEPH_BIN, 'auth', 'get', ENTITY, '-f', 'plain']],
+    ['a relative ceph, not absolute', ['ceph', 'auth', 'get', ENTITY, '-f', 'json']],
+    ['quorum_status with an operand', [CEPH_BIN, 'quorum_status', ENTITY, '-f', 'json']],
+  ])('refuses %s', (_name, argv) => {
+    expect(cephCommandProblem(argv)).toBeString();
+  });
+});
+
+describe('config: the named list starts empty, so every shape is refused today', () => {
+  test.each([
+    ['get', [CEPH_BIN, 'config', 'get', 'global', 'mon_allow_pool_delete', '-f', 'json']],
+    ['set', [CEPH_BIN, 'config', 'set', 'global', 'mon_allow_pool_delete', 'true', '-f', 'json']],
+    ['rm', [CEPH_BIN, 'config', 'rm', 'global', 'mon_allow_pool_delete', '-f', 'json']],
+  ])('config %s is refused: not on the named list', (_verb, argv) => {
+    const problem = cephCommandProblem(argv);
+    expect(problem).toContain('named option list');
+  });
+
+  test('a lockout-class name is refused even if someone tried to add it', () => {
+    const problem = cephCommandProblem([
+      CEPH_BIN,
+      'config',
+      'get',
+      'mon',
+      'mon_host',
+      '-f',
+      'json',
+    ]);
+    expect(problem).toContain('lockout-class');
+  });
+
+  test('an unbounded `who` is refused', () => {
+    const problem = cephCommandProblem([
+      CEPH_BIN,
+      'config',
+      'get',
+      'literally anything',
+      'x',
+      '-f',
+      'json',
+    ]);
+    expect(problem).toBeString();
+  });
+
+  test('a config value with a shell metacharacter is refused', () => {
+    const argv = [CEPH_BIN, 'config', 'set', 'global', 'x', 'true; rm -rf /', '-f', 'json'];
+    expect(cephCommandProblem(argv)).toBeString();
+  });
+});
+
+describe('K-A4 finding 4: configValueProblem never accepts a flag-shaped value', () => {
+  test.each([
+    ['a short flag', '-n'],
+    ['a file-overwrite flag glued to its argument', '-o/etc/ceph/ceph.conf'],
+    ['a long flag with =', '--admin-daemon=/var/run/ceph/ceph-mon.a.asok'],
+    ['another long flag', '--conf=/tmp/x'],
+    ['the empty string', ''],
+    ['a bare dash', '-'],
+  ])('refuses %s (%j)', (_name, value) => {
+    expect(configValueProblem(value)).toBeString();
+  });
+
+  test('a negative integer is still a plain value, not a flag', () => {
+    expect(configValueProblem('-42')).toBeUndefined();
+  });
+
+  test('an ordinary value is accepted', () => {
+    expect(configValueProblem('true')).toBeUndefined();
+    expect(configValueProblem('3600')).toBeUndefined();
+  });
+});

package/src/ceph/ceph-argv.ts

@@ -0,0 +1,189 @@
+/**
+ * The client-side argv allowlist for the Ceph mon-command transport (K-A4) — an allowlist of
+ * SHAPES, not of subcommands, the same discipline `../linux/sudo-allowlist.ts` uses for the file
+ * family. Pure: no I/O, so every shape is tested without ssh (ceph-argv.test.ts).
+ *
+ * Design: docs/plans/2026-09-26-ceph-mon-transport.md ("Transport options", T-A) and
+ * docs/plans/2026-09-26-ceph-config-options.md (the named option list this file bounds `config`
+ * to). Both are REASONED against public Ceph docs, not measured on this estate's cluster — no
+ * mon exists yet for a live check, which is exactly why every shape here is bounded as tightly as
+ * the design allows rather than merely "shaped like a ceph command".
+ *
+ * ⛔ `auth ls` IS NEVER ALLOWED. It prints every key on the cluster, and the estate's own
+ *   2026-09-25 lesson is that an exclusion filter is how a token leaks — allowlist extraction
+ *   only, never "everything except". A caller that wants an inventory uses the committed
+ *   read-only script this design defers to, never this transport.
+ * ⛔ `auth del` IS NEVER ALLOWED, PERIOD — not behind a flag, not for any entity. The lockout-safety
+ *   rule is "never auto-delete" (D3): a wrong delete here de-authenticates whatever the entity's
+ *   caps still let VM disks depend on, and it does not ask twice.
+ * ⛔ THE ENTITY OPERAND IS BOUNDED TO THE `client.k8s-` PREFIX. `client.admin`, `mon.*`, `osd.*`,
+ *   `mgr.*` and the PVE storage client are the keyrings the cluster and every VM disk run on;
+ *   nothing this allowlist accepts can name one.
+ * ⛔ EVERY CHECK RUNS AGAINST THE FINAL ARGV — `/usr/bin/ceph`, the real subcommand, and the
+ *   trailing `-f json` the transport always appends — never a pre-transform version, so what is
+ *   validated is exactly what reaches `sudo -n`.
+ */
+import { configProblem } from './ceph-argv-config.ts';
+
+export { configValueProblem } from './ceph-argv-config.ts';
+
+/** ★ Absolute, so neither sudo nor `ceph` is looked up on the operator's PATH. */
+export const CEPH_BIN = '/usr/bin/ceph';
+
+/** Every entity this transport may ever touch starts with this. */
+export const ENTITY_PREFIX = 'client.k8s-';
+
+/** ⚠️ Bounded length too — a cap operand this long is not a plausible pool-scoped rbd profile. */
+const ENTITY = /^client\.k8s-[a-z0-9][a-z0-9-]{0,61}$/;
+
+/** `undefined` when `entity` is a name this transport may ever create, get or re-cap. */
+export const boundedEntityProblem = (entity: string): string | undefined =>
+  ENTITY.test(entity)
+    ? undefined
+    : `entity must match \`${ENTITY_PREFIX}<name>\` (lowercase, digits, hyphens), got ${JSON.stringify(entity)}`;
+
+/**
+ * ⛔ THE DESIGN'S OWN CAPS, LITERALLY — NOT A GENERAL "LOOKS LIKE A CAP STRING" GRAMMAR. LAND red
+ *   team (2026-09-26), CONFIRMED: an earlier, wider pattern here (any of `[A-Za-z0-9 _.=,-]`, no
+ *   per-daemon shape) also matched `allow rwx`, bare `profile osd` / `profile bootstrap-osd`,
+ *   comma-chained grants (`profile rbd pool=k8s-rbd, allow rwx`), and — the sharpest one — an osd
+ *   `profile rbd` with NO pool, which grants rbd access to every pool on the cluster, the VM-disk
+ *   pool included. The design (2026-09-26-ceph-mon-transport.md, "Props") only ever declares
+ *   `mon: 'profile rbd'` and `osd`/`mgr: 'profile rbd pool=<name>'`; these are that shape, exactly,
+ *   pool name bounded the same way an entity name is.
+ */
+const MON_CAP = /^profile rbd$/;
+const POOL_SCOPED_CAP = /^profile rbd pool=[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+
+const DAEMONS = ['mon', 'osd', 'mgr'] as const;
+
+/** `undefined` when `value` is `daemon`'s one allowed cap shape (the design's own caps map). */
+const capProblem = (
+  daemon: (typeof DAEMONS)[number],
+  value: string | undefined,
+): string | undefined => {
+  if (value === undefined) return `${daemon} cap is missing`;
+  const shape = daemon === 'mon' ? MON_CAP : POOL_SCOPED_CAP;
+  return shape.test(value)
+    ? undefined
+    : `${daemon} cap ${JSON.stringify(value)} is not the design's plain pool-scoped rbd profile`;
+};
+
+/** `auth get <entity>`: the read `Ceph.AuthEntity` uses to observe caps, never the key. */
+const authGetProblem = (ops: readonly string[]): string | undefined => {
+  const [entity, ...extra] = ops;
+  if (entity === undefined || extra.length !== 0) return 'auth get takes exactly `<entity>`';
+  return boundedEntityProblem(entity);
+};
+
+/**
+ * `auth get-or-create <entity> mon <cap> osd <cap> mgr <cap>` and `auth caps` (same operand
+ * shape). ★ FIXED ORDER, EXACTLY THREE PAIRS — the design's own caps map is always
+ *   `{mon, osd, mgr}`; a variable-length daemon list is more allowlist than this family needs,
+ *   and less allowlist is less to get wrong.
+ */
+const capsTripleProblem = (ops: readonly string[]): string | undefined => {
+  const [entity, ...pairs] = ops;
+  if (entity === undefined)
+    return `takes exactly \`<entity> ${DAEMONS.map((d) => `${d} <cap>`).join(' ')}\``;
+  const entityProblem = boundedEntityProblem(entity);
+  if (entityProblem !== undefined) return entityProblem;
+  if (pairs.length !== DAEMONS.length * 2) {
+    return `takes exactly \`<entity> ${DAEMONS.map((d) => `${d} <cap>`).join(' ')}\``;
+  }
+  for (const [index, daemon] of DAEMONS.entries()) {
+    const key = pairs[index * 2];
+    const value = pairs[index * 2 + 1];
+    if (key !== daemon)
+      return `expected \`${daemon}\` in position ${String(index + 1)}, got ${JSON.stringify(key)}`;
+    const problem = capProblem(daemon, value);
+    if (problem !== undefined) return problem;
+  }
+  return undefined;
+};
+
+const authProblem = (rest: readonly string[]): string | undefined => {
+  const [verb, ...ops] = rest;
+  if (verb === 'ls') {
+    return (
+      'auth ls prints every key on the cluster; use the committed read-only inventory ' +
+      'script instead, never this transport'
+    );
+  }
+  if (verb === 'del')
+    return 'auth del is refused entirely — lockout safety, never auto-delete (D3)';
+  if (verb === 'get') return authGetProblem(ops);
+  if (verb === 'get-or-create') return capsTripleProblem(ops);
+  if (verb === 'caps') return capsTripleProblem(ops);
+  return `ceph auth ${String(verb)} is not on the allowlist`;
+};
+
+/** Every call this allowlist accepts ends in this — the transport appends it, never the caller. */
+const JSON_FORMAT = ['-f', 'json'] as const;
+
+const withJsonSuffix = (
+  rest: readonly string[],
+  check: (ops: readonly string[]) => string | undefined,
+): string | undefined => {
+  const suffix = rest.slice(-2);
+  if (suffix[0] !== JSON_FORMAT[0] || suffix[1] !== JSON_FORMAT[1]) {
+    return 'every ceph call in this allowlist ends `-f json`';
+  }
+  return check(rest.slice(0, -2));
+};
+
+/**
+ * `undefined` when `argv` is exactly an allowed ceph shape (the FULL argv `sudo -n` would run,
+ * `/usr/bin/ceph` included), else the reason it is not.
+ */
+export const cephCommandProblem = (argv: readonly string[]): string | undefined => {
+  const [bin, group, ...rest] = argv;
+  if (bin !== CEPH_BIN) return `${JSON.stringify(bin)} is not the allowlisted ceph binary`;
+  if (group === 'quorum_status') {
+    return rest.length === 2 && rest[0] === JSON_FORMAT[0] && rest[1] === JSON_FORMAT[1]
+      ? undefined
+      : 'quorum_status takes exactly `-f json`';
+  }
+  if (group === 'auth') return withJsonSuffix(rest, authProblem);
+  if (group === 'config') return withJsonSuffix(rest, configProblem);
+  return `ceph ${String(group)} is not on the allowlist`;
+};
+
+/** The exact argv for each allowed shape, so callers never hand-assemble one that could drift. */
+export const authGetArgv = (entity: string): readonly string[] => [
+  CEPH_BIN,
+  'auth',
+  'get',
+  entity,
+  ...JSON_FORMAT,
+];
+
+export const authGetOrCreateArgv = (
+  entity: string,
+  caps: Readonly<Record<(typeof DAEMONS)[number], string>>,
+): readonly string[] => [
+  CEPH_BIN,
+  'auth',
+  'get-or-create',
+  entity,
+  ...DAEMONS.flatMap((daemon) => [daemon, caps[daemon]]),
+  ...JSON_FORMAT,
+];
+
+export const authCapsArgv = (
+  entity: string,
+  caps: Readonly<Record<(typeof DAEMONS)[number], string>>,
+): readonly string[] => [
+  CEPH_BIN,
+  'auth',
+  'caps',
+  entity,
+  ...DAEMONS.flatMap((daemon) => [daemon, caps[daemon]]),
+  ...JSON_FORMAT,
+];
+
+export const quorumStatusArgv = (): readonly string[] => [
+  CEPH_BIN,
+  'quorum_status',
+  ...JSON_FORMAT,
+];

package/src/ceph/ceph-auth-form.test.ts

@@ -0,0 +1,103 @@
+/**
+ * The pure props/state comparison `diff` runs — no ssh, no fake dial, nothing async. Mon-transport
+ * doc: "a plan never elevates"; this is the whole of what a plan may ever decide for this family.
+ */
+import { describe, expect, test } from 'bun:test';
+import {
+  type CephAuthEntityAttributes,
+  attributesOf,
+  capsEqual,
+  cephCliPath,
+  cephDataPath,
+  identityMoved,
+  planCephAuthEntity,
+} from './ceph-auth-form.ts';
+
+const CAPS = {
+  mgr: 'profile rbd pool=k8s-rbd',
+  mon: 'profile rbd',
+  osd: 'profile rbd pool=k8s-rbd',
+};
+const OTHER = { ...CAPS, osd: 'profile rbd pool=other' };
+const OUTPUT: CephAuthEntityAttributes = {
+  baoPath: 'talos-c1/ceph/client.k8s-rbd',
+  caps: CAPS,
+  entity: 'client.k8s-rbd',
+  fingerprint: 'deadbeef',
+  node: 'mon-a.example.test',
+};
+const PROPS = {
+  caps: CAPS,
+  entity: 'client.k8s-rbd',
+  mount: 'talos-c1',
+  nodes: ['mon-a.example.test'],
+};
+
+describe('planCephAuthEntity', () => {
+  test('a brand-new row (no output) leaves the decision to reconcile', () => {
+    expect(planCephAuthEntity(PROPS, undefined)).toBeUndefined();
+  });
+
+  test('caps unchanged plans noop', () => {
+    expect(planCephAuthEntity(PROPS, OUTPUT)).toEqual({ action: 'noop' });
+  });
+
+  test('caps changed plans update', () => {
+    expect(planCephAuthEntity({ ...PROPS, caps: OTHER }, OUTPUT)).toEqual({ action: 'update' });
+  });
+
+  test('K-A4 finding 1: an entity edited in place plans replace, not update, even with caps changed too', () => {
+    expect(
+      planCephAuthEntity({ ...PROPS, caps: OTHER, entity: 'client.k8s-other' }, OUTPUT),
+    ).toEqual({ action: 'replace' });
+  });
+
+  test('a mount change alone is the same identity move', () => {
+    expect(planCephAuthEntity({ ...PROPS, mount: 'talos-c2' }, OUTPUT)).toEqual({
+      action: 'replace',
+    });
+  });
+});
+
+describe('identityMoved', () => {
+  test('undefined output is never a move — a brand-new row', () => {
+    expect(identityMoved(PROPS, undefined)).toBe(false);
+  });
+
+  test('the same entity and mount is not a move', () => {
+    expect(identityMoved(PROPS, OUTPUT)).toBe(false);
+  });
+
+  test('a different entity, or a different mount, is a move', () => {
+    expect(identityMoved({ ...PROPS, entity: 'client.k8s-other' }, OUTPUT)).toBe(true);
+    expect(identityMoved({ ...PROPS, mount: 'talos-c2' }, OUTPUT)).toBe(true);
+  });
+});
+
+describe('capsEqual', () => {
+  test('true for the same three fields, false if any one differs', () => {
+    expect(capsEqual(CAPS, { ...CAPS })).toBe(true);
+    expect(capsEqual(CAPS, { ...CAPS, mon: 'profile rbd pool=other' })).toBe(false);
+    expect(capsEqual(CAPS, { ...CAPS, osd: 'profile rbd pool=other' })).toBe(false);
+    expect(capsEqual(CAPS, { ...CAPS, mgr: 'profile rbd pool=other' })).toBe(false);
+  });
+});
+
+describe('bao paths', () => {
+  test('the CLI-style path has no `data/` segment; the HTTP path does', () => {
+    expect(cephCliPath('talos-c1', 'client.k8s-rbd')).toBe('talos-c1/ceph/client.k8s-rbd');
+    expect(cephDataPath('talos-c1', 'client.k8s-rbd')).toBe('talos-c1/data/ceph/client.k8s-rbd');
+  });
+
+  test('a trailing slash on the mount is trimmed', () => {
+    expect(cephCliPath('talos-c1/', 'client.k8s-rbd')).toBe('talos-c1/ceph/client.k8s-rbd');
+  });
+});
+
+describe('attributesOf', () => {
+  test('carries the fingerprint given, never anything shaped like a key', () => {
+    const attrs = attributesOf(PROPS, 'deadbeef', 'mon-a.example.test');
+    expect(attrs).toEqual(OUTPUT);
+    expect(Object.keys(attrs)).not.toContain('key');
+  });
+});

package/src/ceph/ceph-auth-form.ts

@@ -0,0 +1,107 @@
+/**
+ * `Ceph.AuthEntity`'s props/attributes shapes, the OpenBao paths it writes to, and the pure plan
+ * function `diff` uses. Design: docs/plans/2026-09-26-ceph-mon-transport.md, "`Ceph.AuthEntity`
+ * (K-A4)".
+ *
+ * ⛔ `entity` AND `mount` ARE IDENTITY — WHICH MEANS A CHANGE TO EITHER IS `replace`, NEVER
+ *   `update`. The original header here argued a different entity/mount is simply a different
+ *   resource id in the consuming stack, so this family would never need `replace`. That assumed
+ *   the id and the identity move together; nothing enforces that they do — a declaration can keep
+ *   its Alchemy id and edit `entity` or `mount` in place. LAND red team (2026-09-26), CONFIRMED:
+ *   with `output` still naming the OLD entity, comparing caps alone answered `update`, and
+ *   reconcile then ran `auth get`/`auth caps` against the NEW entity — a foreign or unrelated
+ *   live entity — because `output !== undefined` skipped the "never adopted" refusal (which only
+ *   fires when state is absent). `identityMoved` below is the guard, mirroring the
+ *   `rename-identity.ts` pattern `Bao.SshRole` and its siblings use for the same shape of bug —
+ *   except this family cannot ask `judgeMove`'s occupancy question at plan time (that would ssh),
+ *   so there is no `replace`-onto-an-occupied-identity refusal here; reconcile's own
+ *   `neverAdopted` check is what catches a moved identity landing on a live foreign entity,
+ *   because a `replace`'s new generation always reconciles with `output: undefined`.
+ */
+import { trimTrailingSlashes } from '../openbao/mount-path.ts';
+import type { CephCaps } from './ceph-auth-parse.ts';
+
+export type { CephCaps };
+
+export type CephAuthEntityProps = {
+  /** `client.k8s-<name>` — bounded by ceph-argv.ts's allowlist, checked on every transport call. */
+  readonly entity: string;
+  readonly caps: CephCaps;
+  /** TB4 mon ssh destinations, tried in this order (D1). At least one. */
+  readonly nodes: readonly string[];
+  /** OpenBao KV-v2 mount holding Talos/Ceph material, e.g. `talos-c1` (D2). */
+  readonly mount: string;
+};
+
+export type CephAuthEntityAttributes = {
+  readonly entity: string;
+  readonly caps: CephCaps;
+  /** `sha256(key)`, hex — never the key itself. */
+  readonly fingerprint: string;
+  /** CLI-style path (`<mount>/ceph/<entity>`) — safe to persist and log; the key is not here. */
+  readonly baoPath: string;
+  /** Which mon actually answered the write that produced this row. Never key material. */
+  readonly node: string;
+};
+
+export const capsEqual = (a: CephCaps, b: CephCaps): boolean =>
+  a.mon === b.mon && a.osd === b.osd && a.mgr === b.mgr;
+
+/** The CLI-style path an operator's `bao kv get` would use — what `baoPath` records. */
+export const cephCliPath = (mount: string, entity: string): string =>
+  `${trimTrailingSlashes(mount)}/ceph/${entity}`;
+
+/**
+ * The raw KV-v2 HTTP API path `../openbao/bao-http.ts`'s `baoRead`/`baoWrite` take — the CLI path
+ * with `data/` inserted, the same segment `bao kv get`/`bao kv put` insert themselves
+ * (`../talos/credentials.ts`'s header has the shipped-default bug this convention avoids: never
+ * include `data/` in the CLI-style path itself, only here).
+ */
+export const cephDataPath = (mount: string, entity: string): string =>
+  `${trimTrailingSlashes(mount)}/data/ceph/${entity}`;
+
+export type CephAuthEntityPlan = { readonly action: 'noop' | 'update' | 'replace' };
+
+/**
+ * Whether `output` (if any) names a different entity/mount than `news` declares — the one
+ * question both `planCephAuthEntity` and `reconcileCephAuthEntity`'s guard ask, so the comparison
+ * lives in exactly one place (rename-identity.ts's own header: "one description of which object,
+ * not twelve copies of the check").
+ */
+export const identityMoved = (
+  news: Pick<CephAuthEntityProps, 'entity' | 'mount'>,
+  output: CephAuthEntityAttributes | undefined,
+): boolean =>
+  output !== undefined &&
+  (output.entity !== news.entity || output.baoPath !== cephCliPath(news.mount, news.entity));
+
+/**
+ * ⛔ STATE ONLY, NO SSH — the design's own rule for this family ("a plan never elevates"; diff and
+ *   verify compare props against state, never the live cluster). `output === undefined` returns
+ *   `undefined`: a brand-new row plans as a create the same way every other family in this kit
+ *   does, and reconcile is where the actual ssh work — and the key material — ever appears.
+ *   A moved identity plans `replace` before caps are even considered: `defaultRemovalPolicy:
+ *   'retain'` means the old generation is simply left alone (Apply.ts skips its delete under
+ *   retain), and the new generation reconciles with `output: undefined`, which is exactly the
+ *   "never adopted" path if the new identity already has a live entity.
+ */
+export const planCephAuthEntity = (
+  news: CephAuthEntityProps,
+  output: CephAuthEntityAttributes | undefined,
+): CephAuthEntityPlan | undefined => {
+  if (output === undefined) return undefined;
+  if (identityMoved(news, output)) return { action: 'replace' };
+  return capsEqual(news.caps, output.caps) ? { action: 'noop' } : { action: 'update' };
+};
+
+export const attributesOf = (
+  props: Pick<CephAuthEntityProps, 'caps' | 'entity' | 'mount'>,
+  fingerprint: string,
+  node: string,
+): CephAuthEntityAttributes => ({
+  baoPath: cephCliPath(props.mount, props.entity),
+  caps: props.caps,
+  entity: props.entity,
+  fingerprint,
+  node,
+});