@homeflare/alchemy 0.39.0 → 0.40.0

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,
+});

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

@@ -0,0 +1,155 @@
+/**
+ * Parsing against fixture stdout — REASONED shapes (ceph-auth-parse.ts's header), so these fixtures
+ * are this PR's stand-in for a live cluster, not a measurement.
+ */
+import { describe, expect, test } from 'bun:test';
+import { leaksSliceOf, trailingCommaKeyStdout, unquotedKeyStdout } from './ceph-key-leak-assert.ts';
+import { parseAuthGet, parseAuthGetOrCreate, parseQuorumStatus } from './ceph-auth-parse.ts';
+
+const ENTITY = 'client.k8s-rbd';
+const CAPS = {
+  mgr: 'profile rbd pool=k8s-rbd',
+  mon: 'profile rbd',
+  osd: 'profile rbd pool=k8s-rbd',
+};
+const KEYRING_JSON = JSON.stringify([
+  { caps: CAPS, entity: ENTITY, key: 'fake-ceph-key-not-a-real-secret' },
+]);
+
+describe('parseAuthGet', () => {
+  test('present: returns caps only — the parsed value has no key field at all', () => {
+    const observed = parseAuthGet({ exitCode: 0, stderr: '', stdout: KEYRING_JSON }, ENTITY);
+    expect(observed).toEqual({ caps: CAPS, kind: 'present' });
+    expect(Object.keys(observed)).not.toContain('key');
+  });
+
+  test('absent: ENOENT in stderr, never mistaken for an error', () => {
+    const observed = parseAuthGet(
+      { exitCode: 2, stderr: 'Error ENOENT: failed to find client.k8s-rbd in keyring', stdout: '' },
+      ENTITY,
+    );
+    expect(observed).toEqual({ kind: 'absent' });
+  });
+
+  test('a nonzero exit without ENOENT propagates as an error, never as absent', () => {
+    expect(() =>
+      parseAuthGet({ exitCode: 1, stderr: 'Error EACCES: permission denied', stdout: '' }, ENTITY),
+    ).toThrow(/EACCES/);
+  });
+
+  test('unparseable stdout is an error, never absent', () => {
+    expect(() => parseAuthGet({ exitCode: 0, stderr: '', stdout: 'not json' }, ENTITY)).toThrow();
+  });
+
+  test('a JSON array with no matching entity is an error', () => {
+    const other = JSON.stringify([{ caps: CAPS, entity: 'client.k8s-other', key: 'x' }]);
+    expect(() => parseAuthGet({ exitCode: 0, stderr: '', stdout: other }, ENTITY)).toThrow(
+      /no matching entry/,
+    );
+  });
+
+  test('an entry missing a caps field is an error', () => {
+    const bad = JSON.stringify([{ entity: ENTITY, key: 'x' }]);
+    expect(() => parseAuthGet({ exitCode: 0, stderr: '', stdout: bad }, ENTITY)).toThrow();
+  });
+
+  // Decision 65 (LAND finding 5): `auth get` is read unfiltered on every reconcile, so every
+  // failure path below feeds it a key-shaped sentinel and proves no 8-character SLICE of it ever
+  // reaches the thrown error — not just the whole string. LAND red team (2026-09-26), CONFIRMED:
+  // a hyphenated sentinel and a whole-string `.not.toContain` check both missed a real leak where
+  // `JSON.parse`'s own error message quoted a prefix of an unquoted or comma-adjacent key
+  // (ceph-key-leak-assert.ts has the measured detail).
+  test('a malformed present entry never lets even a slice of the key it carried leak', () => {
+    const bad = JSON.stringify([{ entity: ENTITY, key: 'sentinel-ceph-key-must-never-leak' }]); // no caps
+    let caught: unknown;
+    try {
+      parseAuthGet({ exitCode: 0, stderr: '', stdout: bad }, ENTITY);
+    } catch (cause) {
+      caught = cause;
+    }
+    expect(caught).toBeInstanceOf(Error);
+    expect(leaksSliceOf(String(caught), 'sentinel-ceph-key-must-never-leak')).toBe(false);
+  });
+
+  test('a nonzero exit never echoes stdout, even a slice of a key it somehow carried', () => {
+    const stdout = unquotedKeyStdout(ENTITY);
+    let caught: unknown;
+    try {
+      parseAuthGet({ exitCode: 13, stderr: 'Error EPERM: refused', stdout }, ENTITY);
+    } catch (cause) {
+      caught = cause;
+    }
+    expect(String(caught)).toContain('EPERM');
+    expect(leaksSliceOf(String(caught))).toBe(false);
+  });
+
+  for (const [shape, stdout] of [
+    ['a bare (unquoted) key token', unquotedKeyStdout(ENTITY)],
+    ['a trailing comma after the entry', trailingCommaKeyStdout(ENTITY)],
+  ] as const) {
+    test(`unparseable stdout via ${shape} never leaks a slice of the key, from parseAuthGet`, () => {
+      let caught: unknown;
+      try {
+        parseAuthGet({ exitCode: 0, stderr: '', stdout }, ENTITY);
+      } catch (cause) {
+        caught = cause;
+      }
+      expect(caught).toBeInstanceOf(Error);
+      expect(leaksSliceOf(String(caught))).toBe(false);
+    });
+
+    test(`unparseable stdout via ${shape} never leaks a slice of the key, from parseAuthGetOrCreate`, () => {
+      let caught: unknown;
+      try {
+        parseAuthGetOrCreate({ exitCode: 0, stderr: '', stdout }, ENTITY);
+      } catch (cause) {
+        caught = cause;
+      }
+      expect(caught).toBeInstanceOf(Error);
+      expect(leaksSliceOf(String(caught))).toBe(false);
+    });
+  }
+});
+
+describe('parseAuthGetOrCreate', () => {
+  test('returns caps and the key, on success', () => {
+    const created = parseAuthGetOrCreate({ exitCode: 0, stderr: '', stdout: KEYRING_JSON }, ENTITY);
+    expect(created).toEqual({ caps: CAPS, key: 'fake-ceph-key-not-a-real-secret' });
+  });
+
+  test('never reads a nonzero exit as absent — always an error', () => {
+    expect(() =>
+      parseAuthGetOrCreate(
+        { exitCode: 22, stderr: 'Error EINVAL: caps do not match', stdout: '' },
+        ENTITY,
+      ),
+    ).toThrow(/EINVAL/);
+  });
+});
+
+describe('parseQuorumStatus', () => {
+  test('healthy: a non-empty quorum array', () => {
+    expect(parseQuorumStatus('{"quorum":[0,1,2],"quorum_names":["a","b","c"]}')).toEqual({
+      healthy: true,
+    });
+  });
+
+  test('degraded: an empty quorum array', () => {
+    expect(parseQuorumStatus('{"quorum":[]}')).toEqual({
+      healthy: false,
+      reason: 'no non-empty `quorum` array in the quorum_status output',
+    });
+  });
+
+  test('degraded: no quorum field at all', () => {
+    expect(parseQuorumStatus('{"election_epoch":5}').healthy).toBe(false);
+  });
+
+  test('degraded: not even a JSON object', () => {
+    expect(parseQuorumStatus('[1,2,3]').healthy).toBe(false);
+  });
+
+  test('degraded, never thrown: unparseable JSON fails closed instead of crashing the caller', () => {
+    expect(parseQuorumStatus('not json').healthy).toBe(false);
+  });
+});

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

@@ -0,0 +1,121 @@
+/**
+ * Parsing for the three ceph `-f json` shapes `Ceph.AuthEntity` reads: `auth get`, `auth
+ * get-or-create` and `quorum_status`. Pure: no I/O, tested with fixture stdout
+ * (ceph-auth-parse.test.ts) — there is no live mon to capture real output from yet, so every shape
+ * below is REASONED from public Ceph documentation, not measured, and an unexpected shape is
+ * always an error, never a guess.
+ *
+ * ⛔ `parseAuthGet`'S RETURN TYPE HAS NO `key` FIELD. Decision 65 (2026-09-26, LAND finding 5)
+ *   amended the design to let the observe step read `auth get`'s unfiltered stdout on every
+ *   reconcile, not only on create — but the key it carries is dropped in the same breath:
+ *   `parseKeyringEntry` reads it into a local binding and `parseAuthGet` never puts it in the
+ *   object it returns. Not a convention, a type: there is no field here to forget to strip.
+ * ⛔ `parseQuorumStatus` FAILS CLOSED. A JSON parse error, a missing `quorum` array or an empty one
+ *   all answer `{ healthy: false }`; nothing here ever calls an unparseable answer healthy.
+ */
+
+export type CephCaps = { readonly mon: string; readonly osd: string; readonly mgr: string };
+
+export type CephExecOutcome = {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+const parseCaps = (value: unknown, entity: string): CephCaps => {
+  if (!isRecord(value)) throw new Error(`ceph auth: ${entity}'s entry has no caps object`);
+  const { mon, osd, mgr } = value;
+  if (typeof mon !== 'string' || typeof osd !== 'string' || typeof mgr !== 'string') {
+    throw new Error(`ceph auth: ${entity}'s caps are missing a mon, osd or mgr string`);
+  }
+  return { mgr, mon, osd };
+};
+
+/**
+ * REASONED shape (public `ceph auth get -f json` / `auth get-or-create -f json` docs): a JSON
+ * array with one object per entity, `{entity, key, caps: {mon, osd, mgr}}`.
+ */
+const parseKeyringEntry = (
+  stdout: string,
+  entity: string,
+): { readonly caps: CephCaps; readonly key: string } => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    // ⛔ NEVER INTERPOLATE THE CATCH VALUE. LAND red team (2026-09-26), CONFIRMED: both Bun's and
+    //   Node's `JSON.parse` errors quote a slice of the offending input — a bare (unquoted) or
+    //   comma-adjacent key in this stdout put a slice of a real cephx key straight into this
+    //   thrown error (measured: median 32/40 chars of a 1000-key sample). `stdout` carries the
+    //   key on every reconcile since decision 65, so this message names only what failed, never
+    //   any part of what it was reading.
+    throw new Error(`ceph auth ${entity}: stdout did not parse as JSON`);
+  }
+  const row = Array.isArray(parsed)
+    ? parsed.find((entry) => isRecord(entry) && entry['entity'] === entity)
+    : undefined;
+  if (!isRecord(row)) throw new Error(`ceph auth ${entity}: no matching entry in the JSON output`);
+  const { key } = row;
+  if (typeof key !== 'string' || key.trim() === '') {
+    throw new Error(`ceph auth ${entity}: the entry has no key field`);
+  }
+  return { caps: parseCaps(row['caps'], entity), key };
+};
+
+export type CephAuthObserved =
+  | { readonly kind: 'present'; readonly caps: CephCaps }
+  | { readonly kind: 'absent' };
+
+/**
+ * ⚠️ ABSENCE IS RECOGNISED ONLY BY `ENOENT` IN STDERR (REASONED from `ceph auth get`'s documented
+ *   error text). Any other nonzero exit — a permission problem, a malformed entity ceph itself
+ *   refused, a mon mid-election — propagates as an error, never as "absent": the transient-read
+ *   test every family in this kit carries.
+ */
+export const parseAuthGet = (result: CephExecOutcome, entity: string): CephAuthObserved => {
+  if (result.exitCode !== 0) {
+    if (result.stderr.includes('ENOENT')) return { kind: 'absent' };
+    throw new Error(`ceph auth get ${entity} failed: ${result.stderr.trim().slice(0, 300)}`);
+  }
+  const { caps } = parseKeyringEntry(result.stdout, entity);
+  return { caps, kind: 'present' };
+};
+
+/**
+ * ⚠️ `get-or-create` NEVER READS AS ABSENT — REASONED: it either creates, returns the existing
+ *   entity unchanged, or fails outright (e.g. an existing entity with different caps). A nonzero
+ *   exit here is always an error.
+ */
+export const parseAuthGetOrCreate = (
+  result: CephExecOutcome,
+  entity: string,
+): { readonly caps: CephCaps; readonly key: string } => {
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `ceph auth get-or-create ${entity} failed: ${result.stderr.trim().slice(0, 300)}`,
+    );
+  }
+  return parseKeyringEntry(result.stdout, entity);
+};
+
+export type CephQuorum =
+  | { readonly healthy: true }
+  | { readonly healthy: false; readonly reason: string };
+
+/** REASONED shape (public `ceph quorum_status -f json` docs): an object with a `quorum` array. */
+export const parseQuorumStatus = (stdout: string): CephQuorum => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch (cause) {
+    return { healthy: false, reason: `stdout did not parse as JSON (${String(cause)})` };
+  }
+  if (!isRecord(parsed)) return { healthy: false, reason: 'stdout was not a JSON object' };
+  const quorum = parsed['quorum'];
+  return Array.isArray(quorum) && quorum.length > 0
+    ? { healthy: true }
+    : { healthy: false, reason: 'no non-empty `quorum` array in the quorum_status output' };
+};