@homeflare/alchemy 0.54.0 → 0.56.0

package/dist/proxmox/scoped-api.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `pveScoped`: the agent helper for Ceph and container operations over the PVE API when SSH to a
+ * node is not available (2026-10-14, "PVE API path").
+ *
+ * ★ EVERY CALL MINTS A SCOPED TIER, NEVER `provision`. A call names its tier (`ceph-ops` or
+ *   `ct-config`); `scopedTarget` pins BOTH of the target's roles to that tier (credentials.ts's
+ *   "set both roles or neither"), so no read or write in it can fall back to the estate-wide tier.
+ *   In the estate those tiers are `proxmox-tb4/creds/{ceph-ops,ct-config}` → hf-ceph-ops@pve
+ *   (HFCephOps on `/`) and hf-ct-config@pve (HFCTConfig on `/vms`); the PVE ACL is the boundary.
+ * ★ A CLOSED SET OF OPERATIONS. Each builder returns a fixed method + path, with every path
+ *   segment validated, and `ctSetConfig` accepts only the keys HFCTConfig can change anyway.
+ *   No free-form path, so an agent cannot turn this into a general PVE client.
+ * ⛔ The minted secret never leaves `mint`/`pve()` (mint.ts's ⛔). Results are PVE's `data`.
+ * ⛔ Not a substitute for Alchemy: a change that should persist (a declared CT's cores, a Ceph
+ *   flag that a stack owns) still lands as a reviewed PR. This is the break-glass read/act path.
+ */
+import type * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/http/HttpClient';
+import type { PveCredentialDenied } from './credential-errors.ts';
+import { type PveForm } from './client.ts';
+import type { PveRole, PveTarget } from './credentials.ts';
+export type ScopedTier = 'ceph-ops' | 'ct-config';
+export type ScopedCall = {
+    readonly tier: ScopedTier;
+    readonly role: PveRole;
+    readonly method: 'GET' | 'POST' | 'PUT';
+    readonly path: string;
+    readonly form?: PveForm;
+};
+/** The target with BOTH roles pinned to `tier`: nothing here can mint `read`/`provision`. */
+export declare const scopedTarget: (target: PveTarget, tier: ScopedTier) => PveTarget;
+/** Flags an operator sets around maintenance. `pause`, `full` and friends are deliberately absent. */
+export declare const CEPH_FLAGS: readonly ['noout', 'norebalance', 'norecover', 'nobackfill', 'noscrub', 'nodeep-scrub'];
+export type CephFlag = (typeof CEPH_FLAGS)[number];
+/** The CT config keys `ctSetConfig` may write: exactly what HFCTConfig's VM.Config.* privs cover. */
+export declare const CT_CONFIG_KEYS: readonly ['cores', 'cpulimit', 'memory', 'swap', 'onboot', 'description', 'tags'];
+export type CtConfigPatch = Partial<Record<(typeof CT_CONFIG_KEYS)[number], string | number | boolean>>;
+export declare const scopedCalls: {
+    readonly cephStatus: () => ScopedCall;
+    readonly cephFlags: () => ScopedCall;
+    readonly cephSetFlag: (flag: CephFlag, on: boolean) => ScopedCall;
+    readonly cephOsd: (n: string, id: number, to: 'in' | 'out') => ScopedCall;
+    readonly ctConfig: (n: string, id: number) => ScopedCall;
+    readonly ctSetConfig: (n: string, id: number, patch: CtConfigPatch) => ScopedCall;
+    readonly ctPower: (n: string, id: number, action: 'start' | 'shutdown' | 'reboot') => ScopedCall;
+};
+/** Run one scoped call: mint its tier (only), call PVE, return `data`. */
+export declare const pveScoped: <T = unknown>(target: PveTarget, call: ScopedCall) => Effect.Effect<T | undefined, Error | PveCredentialDenied, HttpClient.HttpClient>;
+//# sourceMappingURL=scoped-api.d.ts.map

package/dist/proxmox/scoped-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoped-api.d.ts","sourceRoot":"","sources":["../../src/proxmox/scoped-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,KAAK,UAAU,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,KAAK,OAAO,EAAO,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE3D,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,WAAW,CAAC;AAElD,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,6FAA6F;AAC7F,eAAO,MAAM,YAAY,WAAY,SAAS,QAAQ,UAAU,KAAG,SAGjE,CAAC;AAgBH,sGAAsG;AACtG,eAAO,MAAM,UAAU,YACrB,OAAO,EACP,aAAa,EACb,WAAW,EACX,YAAY,EACZ,SAAS,EACT,cAAc,CACN,CAAC;AACX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,qGAAqG;AACrG,eAAO,MAAM,cAAc,YACzB,OAAO,EACP,UAAU,EACV,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,aAAa,EACb,MAAM,CACE,CAAC;AACX,MAAM,MAAM,aAAa,GAAG,OAAO,CACjC,MAAM,CAAC,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CACnE,CAAC;AAEF,eAAO,MAAM,WAAW;aACtB,UAAU,QAAM,UAAU;aAM1B,SAAS,QAAM,UAAU;aAMzB,WAAW,SAAS,QAAQ,MAAM,OAAO,KAAG,UAAU;aAUtD,OAAO,MAAM,MAAM,MAAM,MAAM,MAAM,IAAI,GAAG,KAAK,KAAG,UAAU;aAS9D,QAAQ,MAAM,MAAM,MAAM,MAAM,KAAG,UAAU;aAM7C,WAAW,MAAM,MAAM,MAAM,MAAM,SAAS,aAAa,KAAG,UAAU;aAgBtE,OAAO,MAAM,MAAM,MAAM,MAAM,UAAU,OAAO,GAAG,UAAU,GAAG,QAAQ,KAAG,UAAU;CAS7E,CAAC;AAEX,0EAA0E;AAC1E,eAAO,MAAM,SAAS,GAAI,CAAC,GAAG,OAAO,UAC3B,SAAS,QACX,UAAU,KACf,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,EAAE,KAAK,GAAG,mBAAmB,EAAE,UAAU,CAAC,UAAU,CACK,CAAC"}

package/docs/linux-sudo-review-2026-09-23.md

@@ -0,0 +1,27 @@
+# The 2026-09-23 adversarial review of the linux sudo runner
+
+Extracted from [linux-sudo.md](./linux-sudo.md) to keep that doc under the 200-line
+cap. The findings it records are live rules of the runner, not history.
+
+🔴 **Adversarial review, 2026-09-23, two rounds — everything found is fixed
+and tested.** Round 1: a directory this runner elevates was checked for
+SHAPE only, never mode or owner. `mkdir -m 0777` and `chown <non-root uid>`
+both passed untouched, so a stack could declare `HostDirectory({ path:
+'/etc/systemd/system/x.service.d', mode: 0o777 })`, drop an `ExecStart=`
+override into it, and this runner's own next `daemon-reload` + `restart`
+would run it as root. Fixed: a directory this runner elevates is now always
+root-owned and never setuid/setgid or group/other-writable, unconditionally
+— a directory's OWNER always has write access through the owner bits alone,
+so no mode restriction alone could make a non-root-owned directory safe
+here. The same round tightened the shared `modeProblem` check
+(`../launchd/sudo-guard.ts`, used by both platforms): it exempted a file
+merely because its `uid` was non-root, missing that `{uid: 501, gid: 0,
+mode: 0o2775}` — setgid to root's own group — reaches the same escalation
+through the group instead. Round 2 found the round-1 `modeProblem` fix was
+itself incomplete (an OMITTED `gid`, not just an explicit `0`, defaults to
+root's own group under `install` — see the section above), the masked-unit
+and FragmentPath-scope gaps documented above, `install`'s own numeric-id
+ambiguity (also above), and a swallowed cleanup-`rm` failure (now included
+in the thrown error, with the leftover path named). All covered by tests:
+`sudo-allowlist.test.ts`, `sudo-lifecycle.test.ts`, `sudo-runner.test.ts`,
+`../launchd/sudo-modes.test.ts`.

package/docs/linux-sudo.md

@@ -60,18 +60,19 @@ staging directory is removed either way.
 
 Each is `/usr/bin/sudo -n -- <argv>`, every program by absolute path.
 
-| when                                 | argv                                                                                |
-| ------------------------------------ | ----------------------------------------------------------------------------------- |
-| a file under a prefix — stage→temp   | `/usr/bin/install -m <0644> -T -- <staged> <temp>`                                  |
-| its owner, if not root:root          | `/usr/bin/chown +<uid>[:+<gid>] -- <temp>` — numeric, `+`-forced, bound to `<temp>` |
-| a file under a prefix — temp→dest    | `/usr/bin/mv -f -T -- <temp> <dest>`                                                |
-| a file under a prefix is removed     | `/usr/bin/rm -f -- <path>`                                                          |
-| a directory under a prefix is made   | `/usr/bin/mkdir -m <octal> -- <path>` — never setuid/setgid or group/other-write    |
-| its mode is fixed                    | `/usr/bin/chmod <octal> -- <path>` — same restriction                               |
-| its owner is fixed                   | `/usr/bin/chown <owner> -- <path>` — **root only**: `+0`, `:+0` or `+0:+0`          |
-| it is removed                        | `/usr/bin/rmdir -- <path>`                                                          |
-| after any unit-file write/removal    | `/usr/bin/systemctl daemon-reload`                                                  |
-| a unit is enabled/disabled/started/… | `/usr/bin/systemctl <verb> -- <unit>`                                               |
+| when                                 | argv                                                                                          |
+| ------------------------------------ | --------------------------------------------------------------------------------------------- |
+| a file under a prefix — stage→temp   | `/usr/bin/install -m <0644> -T -- <staged> <temp>`                                            |
+| its owner, if not root:root          | `/usr/bin/chown +<uid>[:+<gid>] -- <temp>` — numeric, `+`-forced, bound to `<temp>`           |
+| a file under a prefix — temp→dest    | `/usr/bin/mv -f -T -- <temp> <dest>`                                                          |
+| a file under a prefix is removed     | `/usr/bin/rm -f -- <path>`                                                                    |
+| a directory under a prefix is made   | `/usr/bin/mkdir -m <octal> -- <path>` — never setuid/setgid or group/other-write              |
+| its mode is fixed                    | `/usr/bin/chmod <octal> -- <path>` — same restriction                                         |
+| its owner is fixed                   | `/usr/bin/chown <owner> -- <path>` — **root only**: `+0`, `:+0` or `+0:+0`                    |
+| it is removed                        | `/usr/bin/rmdir -- <path>`                                                                    |
+| after any unit-file write/removal    | `/usr/bin/systemctl daemon-reload`                                                            |
+| a unit is enabled/disabled/started/… | `/usr/bin/systemctl <verb> -- <unit>`                                                         |
+| a `privilegedReads` file is read     | `/usr/bin/base64 -- <path>` — exact listed path, root-owned regular file, or the read refuses |
 
 `enable`/`disable`/`start`/`stop`/`restart` elevate only when the unit is not
 **masked** (`LoadState`, read alongside `FragmentPath` in the same call —
@@ -103,7 +104,7 @@ know that syntax exists.
 
 ## What stays as the operator
 
-- Every read: `stat`, `readFile`, user/group lookups, `systemctl show`.
+- Every read: `stat`, `readFile`, user/group lookups, `systemctl show` — with one exact exception: a file on the runner's `privilegedReads` list is read with `sudo -n base64` (the plan-diff read a declared root-owned file needs; see the table above). Every other path, and every `checkWrite` host probe (`id -G`, `ls`, `stat`), stays the operator's own.
 - `checkWrite` — the plan-time half of a write, run at every plan so a
   refusal surfaces before any resource is applied, never at the write.
 - Files and directories outside every prefix (a foreign owner there is a
@@ -111,10 +112,11 @@ know that syntax exists.
 - `ls -ldn` and `mktemp -d` — the guard's chain read and the write's own
   staging, both unprivileged (`src/linux/sudo-listing.ts`, `sudo-stage.ts`).
 
-★ **So a plan never calls sudo**, and construction never does either:
-`sshSudoRunner()` runs one combined, read-only `test -x` for the nine
-absolute programs above, so a missing coreutils package or a systemd-free
-container fails with a clear message at construction — never a sudo probe.
+★ **So a plan calls sudo for exactly one thing** — reading a `privilegedReads`
+file — and construction never does: `sshSudoRunner()` runs one combined,
+read-only `test -x` for the nine absolute programs above, so a missing
+coreutils package or a systemd-free container fails with a clear message at
+construction — never a sudo probe.
 
 ## The host guard
 
@@ -144,31 +146,17 @@ prefix-sibling (`/usr/local/bin-x` is not under `/usr/local/bin`), or a
 `chown` by name, a bare digit, or any non-root id; `systemctl mask`/`--user`;
 a masked unit, any verb; `enable`/`start`/`restart` on a unit with no unit
 file; a root-owned file that would be group- or world-writable, setuid or
-setgid; a file the operator could not read back (both `Systemd.Unit` and
-`Remote.File` read every write back to compare digests).
+setgid; a file NOT on the `privilegedReads` list that the operator could not
+read back (both `Systemd.Unit` and `Remote.File` read every write back to
+compare digests); a listed file handed to a non-root uid, whatever its mode
+— the elevated read-back refuses anything but a root-owned regular file, so
+the handoff would land and then fail every read.
 
 🔴 **Adversarial review, 2026-09-23, two rounds — everything found is fixed
-and tested.** Round 1: a directory this runner elevates was checked for
-SHAPE only, never mode or owner. `mkdir -m 0777` and `chown <non-root uid>`
-both passed untouched, so a stack could declare `HostDirectory({ path:
-'/etc/systemd/system/x.service.d', mode: 0o777 })`, drop an `ExecStart=`
-override into it, and this runner's own next `daemon-reload` + `restart`
-would run it as root. Fixed: a directory this runner elevates is now always
-root-owned and never setuid/setgid or group/other-writable, unconditionally
-— a directory's OWNER always has write access through the owner bits alone,
-so no mode restriction alone could make a non-root-owned directory safe
-here. The same round tightened the shared `modeProblem` check
-(`../launchd/sudo-guard.ts`, used by both platforms): it exempted a file
-merely because its `uid` was non-root, missing that `{uid: 501, gid: 0,
-mode: 0o2775}` — setgid to root's own group — reaches the same escalation
-through the group instead. Round 2 found the round-1 `modeProblem` fix was
-itself incomplete (an OMITTED `gid`, not just an explicit `0`, defaults to
-root's own group under `install` — see the section above), the masked-unit
-and FragmentPath-scope gaps documented above, `install`'s own numeric-id
-ambiguity (also above), and a swallowed cleanup-`rm` failure (now included
-in the thrown error, with the leftover path named). All covered by tests:
-`sudo-allowlist.test.ts`, `sudo-lifecycle.test.ts`, `sudo-runner.test.ts`,
-`../launchd/sudo-modes.test.ts`.
+and tested** — the full record (the directory shape-only gap, the shared `modeProblem`
+escapes, the omitted-`gid` default, the masked-unit and `FragmentPath` scope gaps,
+`install`'s numeric-id ambiguity, the swallowed cleanup failure) lives in
+[linux-sudo-review-2026-09-23.md](./linux-sudo-review-2026-09-23.md).
 
 Every refusal throws `SudoRefusedError`: nothing ran as root. A privileged
 command that ran and failed throws a plain `Error` with its exit code.

package/docs/pve-scoped-api.md

@@ -0,0 +1,23 @@
+# Scoped PVE API helper (`pveScoped`)
+
+Break-glass Ceph and container operations over the PVE API when SSH to a node is unavailable.
+
+```ts
+import { pveScoped, scopedCalls } from '@homeflare/alchemy/proxmox';
+
+const target = { mount: 'proxmox-tb4', members: ['n2.mgmt.homeflare.dev'], scheme: 'pve' } as const;
+const status = await Effect.runPromise(
+  pveScoped(target, scopedCalls.cephStatus()).pipe(Effect.provide(FetchHttpClient.layer)),
+);
+```
+
+- Every call mints its own scoped tier from OpenBao: `<mount>/creds/ceph-ops` or `<mount>/creds/ct-config`.
+  `scopedTarget` pins both roles to that tier, so nothing can fall back to `read` or `provision`.
+- In the estate, `ceph-ops` is `hf-ceph-ops@pve` (HFCephOps on `/`), and `ct-config` is
+  `hf-ct-config@pve` (HFCTConfig on `/vms`). Both are declared in homeflare-proxmox
+  `src/access-scoped-tiers.ts`. The OpenBao roles and the proxmox-deploy grant are declared in homeflare-openbao.
+- The operations are a closed set: `cephStatus`, `cephFlags`, `cephSetFlag` (maintenance flags only),
+  `cephOsd` (in/out), `ctConfig`, `ctSetConfig` (cores, cpulimit, memory, swap, onboot, description, tags) and
+  `ctPower` (start, shutdown, reboot). Every path segment is validated.
+- OpenBao is resolved the same way as `mint` (`BAO_ADDR`/`BAO_TOKEN` or an agent). The secret is never returned.
+- Not a substitute for Alchemy: a change a stack owns still lands as a reviewed PR.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.54.0",
+  "version": "0.56.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",

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

@@ -4,19 +4,26 @@
  * split follows the same line the design docs already draw (2026-09-26-ceph-config-options.md is
  * its own companion to 2026-09-26-ceph-mon-transport.md).
  *
- * ⚠️ `<who>` IS NOT YET BOUNDED TO K-D's "declared daemons" (the config-options design's own
- *   acceptance test #1). `client.admin` still matches this shape. Latent today:
- *   `NAMED_CONFIG_OPTIONS` starts empty, so `namedOptionProblem` refuses every `config get/set/rm`
- *   regardless of `who` — LAND red team, 2026-09-26, flagged this as armed only once K-D's first
- *   named option lands, and narrowing it needs that family's own declared-daemon list, which does
- *   not exist yet. Tracked for `CephConfigOption` (K-D), not fixed here.
+ * ★ `<who>` IS BOUNDED PER OPTION (the config-options design's acceptance test #1). LAND red team,
+ *   2026-09-26, flagged the shape-only `WHO` check as armed the moment K-D's first named option
+ *   landed (`client.admin` matches it). That first option lands in the same change as this guard:
+ *   each `NAMED_CONFIG_OPTIONS` entry carries the sections it may be set for, and a `<who>` outside
+ *   that list is refused before anything dials.
  */
-import { NAMED_CONFIG_OPTIONS, isLockoutConfigOption } from './ceph-config-options.ts';
+import {
+  NAMED_CONFIG_OPTIONS,
+  allowedWhoFor,
+  isLockoutConfigOption,
+} from './ceph-config-options.ts';
 
 /** `config`'s `<who>`: a daemon class, optionally `.id` — never a path, never free text. */
 const WHO = /^(global|mon|osd|mgr|mds|client)(\.[A-Za-z0-9_-]{1,32})?$/;
-/** A ceph option name's own shape — snake_case, lowercase. Independent of the named list below. */
-const OPTION_NAME = /^[a-z][a-z0-9_]{0,63}$/;
+/**
+ * A ceph option name's own shape — snake_case, lowercase — or an mgr module option, which the mon
+ * config db keys as `mgr/<module>/<option>` (e.g. `mgr/prometheus/exclude_perf_counters`).
+ * Independent of the named list below; never a path beyond those exactly-three segments.
+ */
+const OPTION_NAME = /^(?:[a-z][a-z0-9_]{0,63}|mgr\/[a-z][a-z0-9_]{0,31}\/[a-z][a-z0-9_]{0,63})$/;
 /**
  * No shell metacharacters; the named list (below) is what actually decides secrecy, not this.
  * ⛔ NO LEADING `-` EXCEPT A NEGATIVE INTEGER, AND NEVER EMPTY. LAND red team (2026-09-26),
@@ -27,15 +34,13 @@ const OPTION_NAME = /^[a-z][a-z0-9_]{0,63}$/;
  *   `--admin-daemon=/var/run/ceph/ceph-mon.a.asok`, `--conf=/tmp/x`, `-n`, and the empty string.
  *   The sudoers entry has no argument restriction of its own (that is D4, a later step), so this
  *   allowlist is the only thing standing between a config value and an arbitrary ceph CLI flag.
- *   Latent while `NAMED_CONFIG_OPTIONS` is empty; K-D's first entry arms it.
+ *   Armed since K-D's first named entry (`mgr/prometheus/exclude_perf_counters`).
  */
 const CONFIG_VALUE = /^(?:[A-Za-z0-9][A-Za-z0-9 ._:/=,-]{0,255}|-[0-9]{1,255})$/;
 
 /**
  * `undefined` when `value` is a safe ceph config value — exported (like `boundedEntityProblem`)
- * so the shape itself is directly testable, since `NAMED_CONFIG_OPTIONS` being empty today means
- * `cephCommandProblem` never reaches this check on any real argv (`namedOptionProblem` refuses
- * first) — this stays exercised until K-D's first named option arms the path for real.
+ * so the shape itself is directly testable independently of whichever options are named.
  */
 export const configValueProblem = (value: string): string | undefined =>
   CONFIG_VALUE.test(value)
@@ -43,16 +48,19 @@ export const configValueProblem = (value: string): string | undefined =>
     : `config value ${JSON.stringify(value)} contains characters outside the safe set`;
 
 /**
- * `undefined` when `name` may be declared, adopted, read by value or written — see
+ * `undefined` when `name` may be declared for `who`, adopted, read by value or written — see
  * ceph-config-options.ts's header for why the list starts empty and stays reviewed line by line.
  */
-const namedOptionProblem = (name: string): string | undefined => {
+export const namedOptionProblem = (who: string, name: string): string | undefined => {
   if (!OPTION_NAME.test(name)) return `${JSON.stringify(name)} is not a plain ceph option name`;
   if (isLockoutConfigOption(name))
     return `${name} is a lockout-class option and can never be declared`;
-  return NAMED_CONFIG_OPTIONS.has(name)
+  if (!NAMED_CONFIG_OPTIONS.has(name))
+    return `${name} is not on the named option list (each entry is a reviewed PR line — see ceph-config-options.ts)`;
+  const allowed = allowedWhoFor(name);
+  return allowed.includes(who)
     ? undefined
-    : `${name} is not on the named option list (it starts empty — see ceph-config-options.ts)`;
+    : `${name} may only be set for ${allowed.join('/')} on the named option list, not ${JSON.stringify(who)}`;
 };
 
 /** `config get|set|rm <who> <name> [value]`, called with the operands after `config` stripped. */
@@ -64,14 +72,14 @@ export const configProblem = (rest: readonly string[]): string | undefined => {
   if (name === undefined) return 'config takes a `<name>` from the named option list';
   if (verb === 'get' || verb === 'rm') {
     return extra.length === 0
-      ? namedOptionProblem(name)
+      ? namedOptionProblem(who, name)
       : `config ${String(verb)} takes exactly \`<who> <name>\``;
   }
   if (verb === 'set') {
     const [value, ...more] = extra;
     if (value === undefined || more.length !== 0)
       return 'config set takes exactly `<who> <name> <value>`';
-    const named = namedOptionProblem(name);
+    const named = namedOptionProblem(who, name);
     return named !== undefined ? named : configValueProblem(value);
   }
   return `ceph config ${String(verb)} is not on the allowlist`;

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

@@ -161,7 +161,7 @@ describe('shape mismatches', () => {
   });
 });
 
-describe('config: the named list starts empty, so every shape is refused today', () => {
+describe('config: only options on the named list are accepted', () => {
   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']],
@@ -197,6 +197,42 @@ describe('config: the named list starts empty, so every shape is refused today',
     expect(problem).toBeString();
   });
 
+  const OPT = 'mgr/prometheus/exclude_perf_counters';
+  test.each([
+    ['get', [CEPH_BIN, 'config', 'get', 'mgr', OPT, '-f', 'json']],
+    ['set', [CEPH_BIN, 'config', 'set', 'mgr', OPT, 'false', '-f', 'json']],
+    ['rm', [CEPH_BIN, 'config', 'rm', 'mgr', OPT, '-f', 'json']],
+  ])('config %s of the first named option, for its own <who>, is accepted', (_verb, argv) => {
+    expect(cephCommandProblem(argv)).toBeUndefined();
+  });
+
+  test.each(['global', 'client.admin', 'mon', 'mgr.a'])(
+    'the named option is refused for a <who> it is not listed for (%s)',
+    (who) => {
+      const problem = cephCommandProblem([
+        CEPH_BIN,
+        'config',
+        'set',
+        who,
+        OPT,
+        'false',
+        '-f',
+        'json',
+      ]);
+      expect(problem).toContain('may only be set for mgr');
+    },
+  );
+
+  test('an mgr-module-shaped name not on the list is refused', () => {
+    const argv = [CEPH_BIN, 'config', 'set', 'mgr', 'mgr/dashboard/ssl', 'false', '-f', 'json'];
+    expect(cephCommandProblem(argv)).toContain('named option list');
+  });
+
+  test('a path-like name beyond mgr/<module>/<option> is refused by shape', () => {
+    const argv = [CEPH_BIN, 'config', 'get', 'mgr', 'mgr/prometheus/../x', '-f', 'json'];
+    expect(cephCommandProblem(argv)).toContain('not a plain ceph option name');
+  });
+
   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();

package/src/ceph/ceph-argv.ts

@@ -187,3 +187,28 @@ export const quorumStatusArgv = (): readonly string[] => [
   'quorum_status',
   ...JSON_FORMAT,
 ];
+
+/**
+ * `config set <who> <name> <value>` — `Ceph.ConfigOption`'s write. ⚠️ The VALUE is in argv, so it
+ * lands in the runner's log and the node's sudo journal; acceptable only because the named option
+ * list carries no secret-valued option (ceph-config-options.ts).
+ */
+export const configSetArgv = (who: string, name: string, value: string): readonly string[] => [
+  CEPH_BIN,
+  'config',
+  'set',
+  who,
+  name,
+  value,
+  ...JSON_FORMAT,
+];
+
+/** `config rm <who> <name>` — `Ceph.ConfigOption`'s delete; idempotent on the ceph side. */
+export const configRmArgv = (who: string, name: string): readonly string[] => [
+  CEPH_BIN,
+  'config',
+  'rm',
+  who,
+  name,
+  ...JSON_FORMAT,
+];

package/src/ceph/ceph-config-option-form.ts

@@ -0,0 +1,73 @@
+/**
+ * Props, attributes and the pure helpers for `Ceph.ConfigOption` (K-D) — split from
+ * config-option.ts the same way ceph-auth-form.ts is split from auth-entity.ts: nothing here
+ * talks to a cluster, so every rule is unit-tested without PVE or ssh.
+ * Design: docs/plans/2026-09-26-ceph-config-options.md.
+ *
+ * ⛔ VALIDATION IS THE TRANSPORT'S OWN ALLOWLIST, NOT A SECOND COPY OF IT. `configOptionProblem`
+ *   builds the exact `config set` argv the write would run and asks `cephCommandProblem` — so the
+ *   named list (ceph-config-options.ts), the per-option `<who>` bound, the lockout classes and the
+ *   flag-shaped-value refusal can never disagree between plan time and write time.
+ */
+import type { ListNodeCephCfgDbResponseBodyItem } from '@distilled.cloud/proxmox/nodes';
+import type { WithTarget } from '../proxmox/resource-spec.ts';
+import { cephCommandProblem, configSetArgv } from './ceph-argv.ts';
+
+export interface CephConfigOptionProps extends WithTarget {
+  /**
+   * The PVE node whose `GET /nodes/{node}/ceph/cfg/db` answers the mon config db — the plan-time
+   * read. Any node of the Ceph cluster answers the same db.
+   */
+  node: string;
+  /** ssh destinations of the mon hosts the write (`config set`/`rm`) is tried against, in order. */
+  monNodes: readonly string[];
+  /** The config section: `global`, `mon`, `osd`, `mgr`, `mds`, `client`, optionally `.<id>`. */
+  who: string;
+  /** The option name — must be on `NAMED_CONFIG_OPTIONS` for exactly this `who`. */
+  name: string;
+  /**
+   * The value as ceph stores it — a string, compared byte-for-byte with what the config db reports.
+   * ⚠️ Spell it the way ceph echoes it back (`false`, not `0`), or every plan is an `update`.
+   */
+  value: string;
+}
+
+export interface CephConfigOptionAttributes {
+  who: string;
+  name: string;
+  /** The mon-db value observed after the last reconcile. The only field `matches` compares. */
+  value: string;
+}
+
+/** One row of the mon config db, as the PVE API reports it (`ceph config dump`'s shape). */
+export type CfgDbRow = Pick<
+  ListNodeCephCfgDbResponseBodyItem,
+  'section' | 'name' | 'value' | 'mask'
+>;
+
+/** `undefined` when props may be declared at all; else why not. Runs before any read or write. */
+export const configOptionProblem = (props: CephConfigOptionProps): string | undefined => {
+  if (props.monNodes.length === 0) return 'monNodes must name at least one mon ssh destination';
+  const problem = cephCommandProblem(configSetArgv(props.who, props.name, props.value));
+  return problem === undefined
+    ? undefined
+    : `Ceph.ConfigOption ${props.who}/${props.name}: ${problem}`;
+};
+
+/**
+ * The live row for exactly `{who, name}` with NO mask. ⚠️ A masked row (`osd/class:ssd`) is a
+ * different setting the bare `config set <who>` neither writes nor removes, so it is never matched.
+ */
+export const findLive = (
+  rows: readonly CfgDbRow[],
+  who: string,
+  name: string,
+): CephConfigOptionAttributes | undefined => {
+  const row = rows.find((r) => r.section === who && r.name === name && (r.mask ?? '') === '');
+  return row === undefined ? undefined : { name, value: String(row.value), who };
+};
+
+export const matches = (
+  live: CephConfigOptionAttributes | undefined,
+  props: CephConfigOptionProps,
+) => live !== undefined && live.value === props.value;

package/src/ceph/ceph-config-option-reconcile.ts

@@ -0,0 +1,88 @@
+/**
+ * The observe -> ensure -> sync loop and the delete for `Ceph.ConfigOption` (K-D) — plain
+ * functions, so a fake-runner test drives the real loop (same split as ceph-auth-reconcile.ts).
+ *
+ * ★ OBSERVE IS THE PVE API, WRITES ARE THE SSH MON TRANSPORT. The PVE API is read-only for the
+ *   config db (`GET /nodes/{node}/ceph/cfg/db`; no write endpoint exists), so writes go through
+ *   ceph-transport.ts's `runCephCommand` — the one transport every Ceph family in this kit uses,
+ *   allowlist-checked before it dials — and each write is followed by `assertFreshQuorum`.
+ * ★ A DEPLOY WITH NO DRIFT MAKES ZERO WRITES (S10). If the observed mon-db value already equals
+ *   props — an adopted, already-set option included — nothing reaches ssh at all.
+ * ⛔ A FAILED READ IS NEVER "ABSENT". The caller's `readRows` propagates its own failure; only a
+ *   successful read with no matching row means the option is unset.
+ * ⛔ READ BACK AFTER EVERY WRITE and refuse to record a value the mon db does not report.
+ */
+import * as Effect from 'effect/Effect';
+import { configRmArgv, configSetArgv } from './ceph-argv.ts';
+import {
+  type CephConfigOptionAttributes,
+  type CephConfigOptionProps,
+  type CfgDbRow,
+  configOptionProblem,
+  findLive,
+  matches,
+} from './ceph-config-option-form.ts';
+import { type CephTransportOptions, assertFreshQuorum, runCephCommand } from './ceph-transport.ts';
+
+export type CephConfigDeps = Pick<CephTransportOptions, 'dial' | 'log'>;
+
+const asError = (cause: unknown): Error =>
+  cause instanceof Error ? cause : new Error(String(cause));
+
+const runWrite = (transport: CephTransportOptions, argv: readonly string[]) =>
+  Effect.gen(function* () {
+    const result = yield* Effect.tryPromise({
+      catch: asError,
+      try: () => runCephCommand(transport, argv),
+    });
+    if (result.exitCode !== 0) {
+      return yield* Effect.fail(
+        new Error(
+          `ceph ${argv.slice(1, 3).join(' ')} failed on mon ${result.node} (exit ` +
+            `${String(result.exitCode)}): ${result.stderr.trim().slice(0, 300)}`,
+        ),
+      );
+    }
+    yield* Effect.tryPromise({ catch: asError, try: () => assertFreshQuorum(transport) });
+  });
+
+export const reconcileCephConfigOption = <E, R>(
+  props: CephConfigOptionProps,
+  readRows: Effect.Effect<readonly CfgDbRow[], E, R>,
+  deps: CephConfigDeps,
+): Effect.Effect<CephConfigOptionAttributes, E | Error, R> =>
+  Effect.gen(function* () {
+    const problem = configOptionProblem(props);
+    if (problem !== undefined) return yield* Effect.fail(new Error(problem));
+
+    const live = findLive(yield* readRows, props.who, props.name);
+    if (live !== undefined && matches(live, props)) return live;
+
+    yield* runWrite(
+      { nodes: props.monNodes, ...deps },
+      configSetArgv(props.who, props.name, props.value),
+    );
+    const after = findLive(yield* readRows, props.who, props.name);
+    if (after === undefined || !matches(after, props)) {
+      return yield* Effect.fail(
+        new Error(
+          `Ceph.ConfigOption ${props.who}/${props.name}: 'ceph config set' succeeded but the mon ` +
+            `config db reports ${after === undefined ? 'no value' : JSON.stringify(after.value)}, ` +
+            `not ${JSON.stringify(props.value)}. Not recorded — check \`ceph config dump\`.`,
+        ),
+      );
+    }
+    return after;
+  });
+
+/** Idempotent: an option already absent from the mon db is success, with nothing sent. */
+export const deleteCephConfigOption = <E, R>(
+  props: Pick<CephConfigOptionProps, 'who' | 'name' | 'monNodes'>,
+  readRows: Effect.Effect<readonly CfgDbRow[], E, R>,
+  deps: CephConfigDeps,
+): Effect.Effect<void, E | Error, R> =>
+  Effect.gen(function* () {
+    const live = findLive(yield* readRows, props.who, props.name);
+    if (live === undefined) return;
+    yield* runWrite({ nodes: props.monNodes, ...deps }, configRmArgv(props.who, props.name));
+  });