@homeflare/alchemy 0.39.0 → 0.41.0

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

@@ -0,0 +1,119 @@
+/**
+ * The observe -> ensure -> sync loop `Ceph.AuthEntity`'s reconcile runs (mon-transport doc,
+ * `Ceph.AuthEntity`). Split from auth-entity.ts so the loop itself — the part a fake-runner test
+ * actually exercises — is a plain function, the same split ceph-pool.ts and ssh-role.ts use.
+ *
+ * ⛔ NEVER ADOPTS. A live entity found present while this stack holds no attributes for it is
+ *   refused outright, `--adopt` included — the generic `refuseTakeover` (../ownership/adopt.ts)
+ *   is deliberately NOT used here, because it honours `--adopt` and this family's own design says
+ *   plainly: "Existing auth entities are recorded as observed inventory only — never adopted:
+ *   adopting one would mean reading and fingerprinting its key, and a key is only ever handled for
+ *   an entity this stack owns."
+ * ⛔ THE OBSERVE STEP READS `auth get`'S UNFILTERED STDOUT ON EVERY RECONCILE (decision 65,
+ *   2026-09-26, amending the design after LAND finding 5 — no node-side filter narrows it first).
+ *   The key that stdout carries is dropped in the same breath: `parseAuthGet` has no `key` field in
+ *   its return type at all, so there is no variable here ever holding it past that call. Only `auth
+ *   get-or-create`, run once on the create branch, yields a `key` value, and it goes straight to
+ *   OpenBao — never assigned to a variable this function returns, logs, or puts in the attributes
+ *   it hands back — `attributesOf` takes a fingerprint, never a key.
+ * ★ CAPS DRIFT NEVER RE-MINTS THE KEY. `auth caps` changes only what an entity may do; the returned
+ *   attributes reuse `output.fingerprint` unchanged.
+ * ⛔ A MOVED IDENTITY IS REFUSED HERE TOO, BELT AND SUSPENDERS WITH `planCephAuthEntity`'s
+ *   `replace`. `isResolved(news)` in auth-entity.ts's `diff` can defer to the engine's own
+ *   `update` fallback while any prop is still an Output (rename.ts's own header documents this
+ *   exact Alchemy behaviour for every other family this pattern protects) — a case in which
+ *   `planCephAuthEntity` never even runs. Reached with `output` naming a different entity/mount
+ *   than `props`, this refuses before any ssh call, the same shape of guard `guardRename`
+ *   (openbao/rename-identity.ts) runs first in every `Bao.*` reconcile.
+ */
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { baoWrite } from '../openbao/bao-http.ts';
+import { sha256 } from '../openbao/digest.ts';
+import { authCapsArgv, authGetArgv, authGetOrCreateArgv } from './ceph-argv.ts';
+import { parseAuthGet, parseAuthGetOrCreate } from './ceph-auth-parse.ts';
+import {
+  type CephAuthEntityAttributes,
+  type CephAuthEntityProps,
+  attributesOf,
+  capsEqual,
+  cephDataPath,
+  identityMoved,
+} from './ceph-auth-form.ts';
+import { type CephTransportOptions, assertFreshQuorum, runCephCommand } from './ceph-transport.ts';
+
+export type CephAuthDeps = Pick<CephTransportOptions, 'dial' | 'log'>;
+
+const asError = (cause: unknown): Error =>
+  cause instanceof Error ? cause : new Error(String(cause));
+
+const runCeph = (transport: CephTransportOptions, argv: readonly string[]) =>
+  Effect.tryPromise({ catch: asError, try: () => runCephCommand(transport, argv) });
+
+const syncQuorum = (transport: CephTransportOptions) =>
+  Effect.tryPromise({ catch: asError, try: () => assertFreshQuorum(transport) });
+
+const neverAdopted = (entity: string): Error =>
+  new Error(
+    `Ceph.AuthEntity ${entity}: already exists on the mon cluster and this stack holds no state ` +
+      'for it. This family is never adopted — not even under --adopt — because taking it over ' +
+      'would mean fingerprinting a key this stack did not mint. Remove it by hand first, or bring ' +
+      'it under management through the coordinator’s own read-only inventory process.',
+  );
+
+const movedIdentity = (from: string, to: string): Error =>
+  new Error(
+    `Ceph.AuthEntity: planned as an update, but its identity moved from ${from} to ${to}. ` +
+      `Acting on ${to} now, with ${from}'s attributes, could re-cap an entity this generation ` +
+      'never minted. Nothing was sent to any mon. Run the deploy again: once entity/mount fully ' +
+      'resolve at plan time this plans as a replace instead.',
+  );
+
+export const reconcileCephAuthEntity = (
+  props: CephAuthEntityProps,
+  output: CephAuthEntityAttributes | undefined,
+  deps: CephAuthDeps,
+): Effect.Effect<CephAuthEntityAttributes, Error, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    if (identityMoved(props, output))
+      return yield* Effect.fail(movedIdentity(output?.entity ?? '', props.entity));
+
+    const transport: CephTransportOptions = { nodes: props.nodes, ...deps };
+
+    const observed = yield* runCeph(transport, authGetArgv(props.entity)).pipe(
+      Effect.map((result) => parseAuthGet(result, props.entity)),
+    );
+
+    if (observed.kind === 'absent') {
+      // ⛔ THE VAULT WRITE IS CHECKED BEFORE ANYTHING IS MINTED. LAND red team (2026-09-26),
+      //   CONFIRMED: minting first and writing second means a write refused by policy (the likely
+      //   first-deploy shape — the `data/ceph/*` write grant landing after this stack's first
+      //   run) strands a key that only ever existed in memory. The next reconcile's `auth get`
+      //   then finds the entity present, `output` is still undefined, and `neverAdopted` refuses
+      //   it — permanently, since `auth del` is refused too (D3). A placeholder write proves the
+      //   path is writable first; nothing has touched the mon if it fails, so a retry starts
+      //   clean. ⚠️ KV-v2 keeps this placeholder as a version in the secret's history (no version
+      //   is ever skipped) — harmless, since it never carries anything key-shaped, but visible to
+      //   `bao kv get -version=N` until the mount's `max_versions` rolls it off.
+      yield* baoWrite('POST', cephDataPath(props.mount, props.entity), {
+        data: { pending: true },
+      });
+      const result = yield* runCeph(transport, authGetOrCreateArgv(props.entity, props.caps));
+      const created = parseAuthGetOrCreate(result, props.entity);
+      // ⛔ THE ONE PLACE THE KEY CROSSES INTO A BAO CALL — as the HTTP request body's JSON, never
+      //   argv, never a temp file. `created.key` is not referenced again after this.
+      yield* baoWrite('POST', cephDataPath(props.mount, props.entity), {
+        data: { caps: created.caps, key: created.key },
+      });
+      yield* syncQuorum(transport);
+      return attributesOf(props, sha256(created.key), result.node);
+    }
+
+    if (output === undefined) return yield* Effect.fail(neverAdopted(props.entity));
+
+    if (capsEqual(observed.caps, props.caps)) return output;
+
+    const result = yield* runCeph(transport, authCapsArgv(props.entity, props.caps));
+    yield* syncQuorum(transport);
+    return attributesOf(props, output.fingerprint, result.node);
+  });

package/src/ceph/ceph-config-options.test.ts

@@ -0,0 +1,44 @@
+/**
+ * Structural guard on the named config-option list itself (mon-transport doc acceptance test #3):
+ * the list contains none of the lockout classes, and it starts empty (D-C1).
+ */
+import { describe, expect, test } from 'bun:test';
+import { NAMED_CONFIG_OPTIONS, isLockoutConfigOption } from './ceph-config-options.ts';
+
+describe('NAMED_CONFIG_OPTIONS', () => {
+  test('starts empty', () => {
+    expect(NAMED_CONFIG_OPTIONS.size).toBe(0);
+  });
+
+  test('contains none of the lockout classes, whatever gets added later', () => {
+    const bad = [...NAMED_CONFIG_OPTIONS].filter((name) => isLockoutConfigOption(name));
+    expect(bad).toEqual([]);
+  });
+});
+
+describe('isLockoutConfigOption', () => {
+  test.each([
+    'mon_host',
+    'public_network',
+    'cluster_network',
+    'public_addr',
+    'cluster_addr',
+    'auth_cluster_required',
+    'auth_service_required',
+    'auth_client_required',
+    'keyring',
+    'mgr_keyring',
+    'keyring_path',
+    'key',
+    'mon_data_key',
+  ])('flags %s', (name) => {
+    expect(isLockoutConfigOption(name)).toBe(true);
+  });
+
+  test.each(['mon_allow_pool_delete', 'osd_pool_default_size', 'mon_max_pg_per_osd'])(
+    'does not flag an ordinary tuning option like %s',
+    (name) => {
+      expect(isLockoutConfigOption(name)).toBe(false);
+    },
+  );
+});

package/src/ceph/ceph-config-options.ts

@@ -0,0 +1,36 @@
+/**
+ * The named Ceph config-option list — the only options `ceph config get/set/rm` may ever touch
+ * through the mon-command transport (ceph-argv.ts's `configProblem`). Design:
+ * docs/plans/2026-09-26-ceph-config-options.md, D-C1.
+ *
+ * ⛔ THE LIST STARTS EMPTY, AND EACH ADDITION IS ITS OWN REVIEWED PR LINE. Nothing in K-A4 adds to
+ *   it — `CephConfigOption` (K-D) is a separate, later family; this file exists now only so the
+ *   transport's allowlist has something to bound `config` against from day one, per the accepted
+ *   design ("config get/set for the named option list which starts EMPTY").
+ * ⛔ NEVER ADD ONE OF THE LOCKOUT CLASSES BELOW. `mon_host`, `public_network`, `cluster_network`,
+ *   `public_addr`, `cluster_addr`, every `auth_*_required` and every `key`/`keyring`-bearing
+ *   option re-address the mons or de-authenticate the whole cluster — cutting every VM disk — and
+ *   `isLockoutConfigOption` is a structural guard a test runs against this file's own list, not a
+ *   suggestion for the reviewer of the next PR line.
+ * ⛔ NEVER ADD A SECRET-VALUED OPTION. mgr module options can hold passwords (REASONED — no live
+ *   cluster to measure this against yet); a secret-bearing setting belongs in a vault-backed flow,
+ *   never a `ceph config set` argv, which lands in the runner's log and the node's sudo journal.
+ */
+
+/** Starts empty. Add one reviewed option name per PR line, never a batch. */
+export const NAMED_CONFIG_OPTIONS: ReadonlySet<string> = new Set([]);
+
+const LOCKOUT_EXACT: ReadonlySet<string> = new Set([
+  'mon_host',
+  'public_network',
+  'cluster_network',
+  'public_addr',
+  'cluster_addr',
+]);
+
+/** `auth_*_required` (cephx enforcement) and anything key/keyring-shaped, either side of `_`. */
+const LOCKOUT_PATTERN = /^auth_\w*_required$|(^|_)key(ring)?($|_)/;
+
+/** Whether `name` is a class this transport must never read a value for, adopt, or write. */
+export const isLockoutConfigOption = (name: string): boolean =>
+  LOCKOUT_EXACT.has(name) || LOCKOUT_PATTERN.test(name);

package/src/ceph/ceph-key-leak-assert.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared by the two test files that prove `Ceph.AuthEntity` never leaks a minted key through a
+ * parse-error message: ceph-auth-parse.test.ts (direct parser calls) and
+ * ceph-auth-reconcile-secrecy.test.ts (through the full reconcile loop). Split out so the leak
+ * check and the malformed-stdout fixtures are identical in both places — the property being
+ * proved (decision 65) is the same one, and two hand-copied versions are exactly the kind of thing
+ * that quietly drifts apart.
+ *
+ * ⛔ TEST-ONLY. Nothing in `src/` imports this outside a `.test.ts` file.
+ * ★ NO HYPHEN IN THE SENTINEL. LAND red team (2026-09-26), CONFIRMED: a JSON lexer's "unexpected
+ *   identifier" error for a bare (unquoted) token stops at the first character outside
+ *   `[A-Za-z0-9_$]`, so a hyphenated sentinel (`sentinel-ceph-key-...`) truncates to its first
+ *   word — `.not.toContain(SENTINEL)` on the FULL string then never fires even when that first
+ *   word leaked. Cephx keys are base64 (`[A-Za-z0-9+/=]`, no hyphen), so this sentinel is shaped
+ *   the same way, and every check here compares 8-character slices, not full-string containment.
+ */
+
+/** A cephx-shaped sentinel: looks like a real minted key, no hyphen anywhere to truncate on. */
+export const KEY_SHAPED_SENTINEL = 'AQDsentinelKEYsentinelKEY0123456789abcd==';
+
+/** True if any 8-character window of `key` shows up anywhere in `message`. */
+export const leaksSliceOf = (message: string, key: string = KEY_SHAPED_SENTINEL): boolean => {
+  for (let start = 0; start + 8 <= key.length; start += 1) {
+    if (message.includes(key.slice(start, start + 8))) return true;
+  }
+  return false;
+};
+
+/** `auth get`/`auth get-or-create` stdout with the key left as a bare (unquoted) JSON token. */
+export const unquotedKeyStdout = (entity: string, key: string = KEY_SHAPED_SENTINEL): string =>
+  `[{"entity":"${entity}","key":${key}}]`;
+
+/** The same shape with a trailing comma after the entry — a different malformed-JSON path. */
+export const trailingCommaKeyStdout = (entity: string, key: string = KEY_SHAPED_SENTINEL): string =>
+  `[{"entity":"${entity}","key":"${key}"},]`;

package/src/ceph/ceph-no-output-logging.test.ts

@@ -0,0 +1,52 @@
+/**
+ * The design doc's own Risks section (docs/plans/2026-09-26-ceph-mon-transport.md) says this
+ * family "gets a structural test over its own source (no output-logging)". LAND red team
+ * (2026-09-26): no such test existed — the fake-runner tests proved the key never reaches a log
+ * line for the SHAPES they happened to exercise, but nothing proved a future call site could not
+ * add a new one that does. This is that test, the same grep-gate shape
+ * `talos/secrets-gate.test.ts` runs for PEM/bootstrap-token material.
+ *
+ * ★ A POSITIVE CONTROL WOULD DEFEAT THE PURPOSE HERE, same as secrets-gate.test.ts: there is no
+ *   "real" case where a hit should be found, so this only has a negative case.
+ * ⚠️ THIS IS A TEXT SCAN, NOT A TYPE CHECKER. It cannot prove no code path ever COULD log output —
+ *   only that today's source doesn't. ceph-transport.ts's own header comment carries the actual
+ *   invariant ("ONLY ARGV IS EVER LOGGED"); this test is the regression guard for it.
+ */
+import { describe, expect, test } from 'bun:test';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const CEPH_DIR = import.meta.dir;
+
+/** This family's own production source — never a test file, never the fake dial's test double. */
+const productionFiles = () =>
+  readdirSync(CEPH_DIR)
+    .filter(
+      (name) => name.endsWith('.ts') && !name.includes('.test.') && name !== 'fake-ceph-dial.ts',
+    )
+    .map((name) => join(CEPH_DIR, name));
+
+describe('no output-logging — structural test over this family’s own source', () => {
+  test('no console.* call anywhere — logging goes only through the injected `log` sink', () => {
+    for (const file of productionFiles()) {
+      const text = readFileSync(file, 'utf8');
+      expect(text).not.toMatch(/\bconsole\.\w+\(/);
+    }
+  });
+
+  test('every call to the injected `log` sink logs the attempted argv line only, never stdout/stderr/a key', () => {
+    let sawACall = false;
+    for (const file of productionFiles()) {
+      for (const line of readFileSync(file, 'utf8').split('\n')) {
+        if (!/\blog\(/.test(line)) continue;
+        sawACall = true;
+        expect(line).not.toMatch(/\.stdout\b/);
+        expect(line).not.toMatch(/\.stderr\b/);
+        expect(line).not.toMatch(/\bkey\b/i);
+      }
+    }
+    // ⛔ A GUARD AGAINST THE GUARD GOING QUIET. If this ever finds zero call sites (the log call
+    //   renamed, the file moved), the two checks above would trivially pass having proven nothing.
+    expect(sawACall).toBe(true);
+  });
+});

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

@@ -0,0 +1,125 @@
+/**
+ * The mon-command transport against `fakeCephDial` — no ssh, no spawned process. Mon-transport doc
+ * acceptance tests #1 ("no ssh at all" for a refused shape) and #2 (try-in-order, transport
+ * failure never reads as absent, quorum re-checked on a fresh connection after a write).
+ */
+import { describe, expect, test } from 'bun:test';
+import { authGetArgv, quorumStatusArgv } from './ceph-argv.ts';
+import { assertFreshQuorum, runCephCommand } from './ceph-transport.ts';
+import { fakeCephDial, fakeCephOk } from './fake-ceph-dial.ts';
+
+const ENTITY = 'client.k8s-rbd';
+const MON_A = 'mon-a.example.test';
+const MON_B = 'mon-b.example.test';
+const MON_C = 'mon-c.example.test';
+
+describe('runCephCommand', () => {
+  test('a refused shape never dials — no mon is ever contacted', async () => {
+    const fake = fakeCephDial({});
+    await expect(
+      runCephCommand({ dial: fake.dial, log: () => {}, nodes: [MON_A] }, [
+        '/usr/bin/ceph',
+        'auth',
+        'del',
+        ENTITY,
+        '-f',
+        'json',
+      ]),
+    ).rejects.toThrow(/never auto-delete/);
+    expect(fake.seen).toEqual([]);
+  });
+
+  test('refuses when no mon nodes are declared, without dialing', async () => {
+    const fake = fakeCephDial({});
+    await expect(
+      runCephCommand({ dial: fake.dial, log: () => {}, nodes: [] }, authGetArgv(ENTITY)),
+    ).rejects.toThrow(/no mon nodes/);
+    expect(fake.seen).toEqual([]);
+  });
+
+  test('tries the next mon on a transport failure, in order, and returns the first that answers', async () => {
+    const fake = fakeCephDial({
+      [MON_B]: [{ kind: 'result', result: { exitCode: 0, stderr: '', stdout: '[]' } }],
+    });
+    const result = await runCephCommand(
+      { dial: fake.dial, log: () => {}, nodes: [MON_A, MON_B, MON_C] },
+      authGetArgv(ENTITY),
+    );
+    expect(result.node).toBe(MON_B);
+    expect(fake.seen.map((call) => call.node)).toEqual([MON_A, MON_B]);
+  });
+
+  test('every mon failing at the transport layer propagates as an error, never as absent', async () => {
+    const fake = fakeCephDial({});
+    const attempt = runCephCommand(
+      { dial: fake.dial, log: () => {}, nodes: [MON_A, MON_B] },
+      authGetArgv(ENTITY),
+    );
+    await expect(attempt).rejects.toThrow(/every mon node failed \(never treated as absent\)/);
+    expect(fake.seen.map((call) => call.node)).toEqual([MON_A, MON_B]);
+  });
+
+  test('a mon that actually answers, even with a nonzero exit, is not retried on another node', async () => {
+    const fake = fakeCephDial({
+      [MON_A]: [
+        { kind: 'result', result: { exitCode: 2, stderr: 'Error ENOENT: not found', stdout: '' } },
+      ],
+    });
+    const result = await runCephCommand(
+      { dial: fake.dial, log: () => {}, nodes: [MON_A, MON_B] },
+      authGetArgv(ENTITY),
+    );
+    expect(result.node).toBe(MON_A);
+    expect(result.exitCode).toBe(2);
+    expect(fake.seen.map((call) => call.node)).toEqual([MON_A]);
+  });
+
+  test('the log line carries the argv, never any result — including a successful stdout', async () => {
+    const lines: string[] = [];
+    const fake = fakeCephDial({
+      [MON_A]: [
+        fakeCephOk('[{"entity":"client.k8s-rbd","key":"fake-key-not-a-secret","caps":{}}]'),
+      ],
+    });
+    await runCephCommand(
+      { dial: fake.dial, log: (line) => lines.push(line), nodes: [MON_A] },
+      authGetArgv(ENTITY),
+    );
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toContain(JSON.stringify(authGetArgv(ENTITY)));
+    expect(lines.join('\n')).not.toContain('fake-key-not-a-secret');
+  });
+});
+
+describe('assertFreshQuorum', () => {
+  test('passes on a healthy quorum', async () => {
+    const fake = fakeCephDial({ [MON_A]: [fakeCephOk('{"quorum":[0,1,2]}')] });
+    await expect(
+      assertFreshQuorum({ dial: fake.dial, log: () => {}, nodes: [MON_A] }),
+    ).resolves.toBeUndefined();
+    expect(fake.seen).toEqual([{ argv: quorumStatusArgv(), node: MON_A }]);
+  });
+
+  test('fails closed on an empty quorum array', async () => {
+    const fake = fakeCephDial({ [MON_A]: [fakeCephOk('{"quorum":[]}')] });
+    await expect(
+      assertFreshQuorum({ dial: fake.dial, log: () => {}, nodes: [MON_A] }),
+    ).rejects.toThrow(/degraded/);
+  });
+
+  test('fails closed on unparseable output — never calls a guess "healthy"', async () => {
+    const fake = fakeCephDial({ [MON_A]: [fakeCephOk('not json')] });
+    await expect(
+      assertFreshQuorum({ dial: fake.dial, log: () => {}, nodes: [MON_A] }),
+    ).rejects.toThrow(/degraded/);
+  });
+
+  test('a nonzero exit from quorum_status itself fails, reporting stderr only', async () => {
+    const fake = fakeCephDial({
+      [MON_A]: [{ kind: 'result', result: { exitCode: 1, stderr: 'mon down', stdout: '' } }],
+    });
+    await expect(
+      assertFreshQuorum({ dial: fake.dial, log: () => {}, nodes: [MON_A] }),
+    ).rejects.toThrow(/mon down/);
+  });
+});

package/src/ceph/ceph-transport.ts

@@ -0,0 +1,117 @@
+/**
+ * The Ceph mon-command transport (K-A4, T-A): ssh to one of the TB4 mon nodes, `sudo -n
+ * /usr/bin/ceph …`, tried in node order. Every call is checked against ceph-argv.ts's allowlist
+ * BEFORE anything dials — a refused shape never opens a connection, never mind runs a command.
+ *
+ * ★ BUILT ON THE SAME WIRE FORMAT sshSudoRunner USES, NOT A SECOND ONE. `runRemote` (the framed
+ *   script + nonce marker `../linux/ssh-command.ts` and `../linux/ssh-runner.ts` already ship and
+ *   test) is reused directly: same fail-closed behaviour on a dropped connection, same
+ *   `BatchMode=yes`, same host-key verification left to the operator's own ssh config.
+ * ⛔ THE DIAL IS AN INJECTED SEAM, NOT child_process MOCKED. `CephDial` is the same idea as
+ *   `HostRunner` (../launchd/runner.ts): production code gets `sshCephDial`, tests hand a fake
+ *   function directly (fake-ceph-dial.ts) — no ssh binary, no spawned process, ever, in a test.
+ * ⛔ A TRANSPORT FAILURE (no mon reachable) IS NEVER "ABSENT". Only a mon that actually ran the
+ *   command and answered gets to say whether an entity exists; every node failing to connect
+ *   propagates as an Error, so a down anchor can never read as "recreate it".
+ * ⛔ ONLY ARGV IS EVER LOGGED. `log` is called with the shape being attempted, never with a
+ *   result's stdout or stderr — `auth get`/`auth get-or-create`'s stdout carries the entity's key.
+ */
+import { randomBytes } from 'node:crypto';
+import { quoteArgv } from '../linux/ssh-command.ts';
+import { runRemote } from '../linux/ssh-runner.ts';
+import { SUDO, SudoRefusedError } from '../linux/sudo-allowlist.ts';
+import { cephCommandProblem, quorumStatusArgv } from './ceph-argv.ts';
+import { parseQuorumStatus } from './ceph-auth-parse.ts';
+
+export type CephExecResult = {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+};
+
+/** One attempt against one mon: run `argv` (already sudo-wrapped by the caller) and report. */
+export type CephDial = (node: string, argv: readonly string[]) => Promise<CephExecResult>;
+
+const CONNECT_TIMEOUT_SEC = 10;
+const EXEC_TIMEOUT_MS = 30_000;
+
+/** ★ A fresh nonce per attempt — this dial never reuses a connection or a marker across calls. */
+export const sshCephDial: CephDial = async (node, argv) => {
+  const nonce = randomBytes(8).toString('hex');
+  const script = `${SUDO} -n -- ${quoteArgv(argv)}`;
+  return runRemote(
+    { connectTimeoutSec: CONNECT_TIMEOUT_SEC, execTimeoutMs: EXEC_TIMEOUT_MS, host: node },
+    nonce,
+    script,
+  );
+};
+
+export type CephTransportOptions = {
+  /** TB4 mon ssh destinations, tried in this order. Required; at least one. */
+  readonly nodes: readonly string[];
+  readonly dial?: CephDial;
+  /** One line per attempted argv, before it dials. @default a line on stderr */
+  readonly log?: (line: string) => void;
+};
+
+const defaultLog = (line: string) => process.stderr.write(`${line}\n`);
+
+/**
+ * Run one allowed ceph shape against the first mon that answers.
+ *
+ * ⛔ THE ALLOWLIST CHECK HAPPENS BEFORE THE FIRST NODE IS EVEN TRIED — a refused argv dials no
+ *   ssh at all, so a bug that builds a bad shape cannot leak so much as a connection attempt.
+ */
+export const runCephCommand = async (
+  options: CephTransportOptions,
+  argv: readonly string[],
+): Promise<CephExecResult & { readonly node: string }> => {
+  const problem = cephCommandProblem(argv);
+  if (problem !== undefined) {
+    throw new SudoRefusedError(`ceph transport refused ${JSON.stringify(argv)}: ${problem}`);
+  }
+  if (options.nodes.length === 0) throw new Error('ceph transport: no mon nodes were declared');
+  const dial = options.dial ?? sshCephDial;
+  const log = options.log ?? defaultLog;
+  const attempts: { readonly node: string; readonly message: string }[] = [];
+  for (const node of options.nodes) {
+    log(`homeflare/ceph sudo -n ${JSON.stringify(argv)} @ ${node}`);
+    try {
+      const result = await dial(node, argv);
+      return { ...result, node };
+    } catch (cause) {
+      attempts.push({ message: cause instanceof Error ? cause.message : String(cause), node });
+    }
+  }
+  // ⛔ NEVER "ABSENT". Every mon this call knew about failed at the transport layer; that is a
+  //   down anchor (or a network problem), not proof the entity does not exist.
+  const detail = attempts.map((a) => `${a.node}: ${a.message}`).join('; ');
+  throw new Error(`ceph transport: every mon node failed (never treated as absent) — ${detail}`);
+};
+
+/**
+ * ★ LOCKOUT SAFETY, THE UFW-ESTABLISHED PATTERN: after every write, re-check quorum on a FRESH
+ *   connection (a new dial, never the one the write used) and fail the row if it degraded. Never
+ *   auto-repair, never continue — the caller's write is reported as failed even though it may
+ *   itself have succeeded, because a write that broke quorum is not a success this transport will
+ *   call one.
+ * ⚠️ THE SHAPE OF `quorum_status -f json` IS REASONED FROM PUBLIC CEPH DOCS, NOT MEASURED against
+ *   this estate's Ceph release — there is no mon yet. An unparseable or missing `quorum` array
+ *   fails closed as "degraded", never as "healthy"; see ceph-auth-parse.ts.
+ */
+export const assertFreshQuorum = async (options: CephTransportOptions): Promise<void> => {
+  const result = await runCephCommand(options, quorumStatusArgv());
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `ceph quorum_status failed after a write (mon ${result.node}): ` +
+        `${result.stderr.trim().slice(0, 300)}`,
+    );
+  }
+  const quorum = parseQuorumStatus(result.stdout);
+  if (!quorum.healthy) {
+    throw new Error(
+      `ceph quorum degraded after a write (mon ${result.node}): ${quorum.reason} — the write is ` +
+        'reported as failed even if it landed; nothing here auto-repairs a quorum problem.',
+    );
+  }
+};

package/src/ceph/fake-ceph-dial.ts

@@ -0,0 +1,55 @@
+/**
+ * A fake `CephDial` for the tests beside it — no ssh, no spawned process, ever. The same idea as
+ * `../linux/fake-sudo.ts` and `../openbao/fake-bao.ts`: production code is handed the real
+ * implementation, a test hands this instead, and neither one's internals change to make room for
+ * the other.
+ *
+ * ⛔ TEST-ONLY. Nothing in `src/` imports this outside a `.test.ts` file.
+ */
+import type { CephDial, CephExecResult } from './ceph-transport.ts';
+
+/** One call this fake received. */
+export type SeenCephCall = { readonly node: string; readonly argv: readonly string[] };
+
+/** What a scripted node answers: a result, or a thrown transport failure. */
+export type CephAnswer =
+  | { readonly kind: 'result'; readonly result: CephExecResult }
+  | { readonly kind: 'transport-error'; readonly message: string };
+
+export type FakeCephDial = {
+  readonly dial: CephDial;
+  readonly seen: SeenCephCall[];
+};
+
+const ok = (stdout: string, exitCode = 0, stderr = ''): CephAnswer => ({
+  kind: 'result',
+  result: { exitCode, stderr, stdout },
+});
+
+/**
+ * `script` maps a node to the fixed sequence of answers it gives, one per call that reaches it —
+ * the last entry repeats once exhausted. A node with no entry always transport-fails, which is
+ * exactly "an unreachable mon" without a special case.
+ */
+export const fakeCephDial = (
+  script: Readonly<Record<string, readonly CephAnswer[]>>,
+): FakeCephDial => {
+  const seen: SeenCephCall[] = [];
+  const counts = new Map<string, number>();
+  const dial: CephDial = async (node, argv) => {
+    seen.push({ argv, node });
+    const answers = script[node];
+    if (answers === undefined || answers.length === 0) {
+      throw new Error(`fakeCephDial: ${node} is not reachable (no script entry)`);
+    }
+    const at = counts.get(node) ?? 0;
+    counts.set(node, at + 1);
+    const answer = answers[Math.min(at, answers.length - 1)];
+    if (answer === undefined) throw new Error(`fakeCephDial: ${node} has no answer`);
+    if (answer.kind === 'transport-error') throw new Error(answer.message);
+    return answer.result;
+  };
+  return { dial, seen };
+};
+
+export { ok as fakeCephOk };

package/src/ceph/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Ceph providers for Alchemy — the mon-command transport and `Ceph.AuthEntity` (K-A4).
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, DELIBERATELY SMALLER THAN THE DIRECTORY — see
+ *   `../openbao/index.ts`'s header for why. The allowlist internals (ceph-argv.ts), the parsing
+ *   (ceph-auth-parse.ts) and the reconcile loop (ceph-auth-reconcile.ts) are exported by path for
+ *   a future `CephConfigOption` (K-D) or a test to reach directly, not published here.
+ */
+export type { CephAuthEntityAttributes, CephAuthEntityProps, CephCaps } from './auth-entity.ts';
+export { CephAuthEntity, CephAuthEntityProvider } from './auth-entity.ts';
+export type { CephDial, CephExecResult, CephTransportOptions } from './ceph-transport.ts';
+export { assertFreshQuorum, runCephCommand, sshCephDial } from './ceph-transport.ts';

package/src/index.ts

@@ -10,6 +10,7 @@
  *     import { BaoMount } from '@homeflare/alchemy/openbao';
  *     import { TalosCluster } from '@homeflare/alchemy/talos';
  *     import { ProxmoxAcl } from '@homeflare/alchemy/proxmox';
+ *     import { CephAuthEntity } from '@homeflare/alchemy/ceph';
  *     import { LaunchdJob } from '@homeflare/alchemy/launchd';
  *     import { ReleaseBinary } from '@homeflare/alchemy/release';
  *     import { CaddyConfig } from '@homeflare/alchemy/caddy';

package/src/launchd/fake-runner.ts

@@ -156,6 +156,8 @@ export const fakeRunner = (options: FakeOptions = {}) => {
     lookupUser: async (nameOrId) =>
       options.users?.[nameOrId] ??
       Object.values(options.users ?? {}).find((user) => String(user.uid) === nameOrId),
+    // ★ This fake models launchd, which only ever exists on a Mac — fixed, not an option.
+    platform: 'darwin',
     privileged,
     readFile: async (path) => files.get(path)?.bytes,
     removeFile: async (path) => {

package/src/launchd/index.ts

@@ -24,7 +24,14 @@ export { PlistError, renderPlist } from './plist.ts';
 export type { PortClaim } from './port-claims.ts';
 export { PortRefused, claimPorts, portClaimProblems } from './port-claims.ts';
 export { launchdProviders } from './providers.ts';
-export type { ExecResult, FileStat, HostRunner, HostUser, WriteOptions } from './runner.ts';
+export type {
+  ExecResult,
+  FileStat,
+  HostPlatform,
+  HostRunner,
+  HostUser,
+  WriteOptions,
+} from './runner.ts';
 export { HostRunnerService, canActAsRoot, hostRunnerLayer } from './runner.ts';
 export type { SudoRunnerOptions } from './sudo-runner.ts';
 export { SudoRefusedError, sudoRunner } from './sudo-runner.ts';