@homeflare/alchemy 0.39.0 → 0.40.0

package/docs/unifi-traffic-matching-list.md

@@ -0,0 +1,82 @@
+# UniFi Traffic Matching Lists — `Unifi.TrafficMatchingList`
+
+⛔ **READ-ONLY, BY TIM'S RULE (2026-09-24).** Same posture as `docs/unifi.md`'s `Unifi.Network`/
+`Unifi.FirewallZone`: `reconcile`/`delete` both fail with a typed `UnifiWriteRefused`, and the
+`GetOnlyHttpClient` wire guard (`resource.ts`) refuses any non-`GET` request before it reaches the
+transport. This family never calls `createTrafficMatchingList`, `updateTrafficMatchingList` or
+`deleteTrafficMatchingList` anywhere — `write-op-reference.test.ts` proves it statically.
+
+## The simplest object shape in this directory
+
+`TrafficMatchingList` is `{id, name, type, items?}` — no `metadata` field at all, unlike every
+other family here (`FirewallZone`/`DNSPolicy`/`ACLRule`/`FirewallPolicy` all carry a server-derived
+`metadata.origin`). Nothing in `TrafficMatchingListAttributes` is attributes-only the way
+`metadataOrigin`/`index` are elsewhere: every field this family reads is also declarable.
+
+## `items` is a real TS union post-A3, compared wholesale
+
+`items` decodes as `Array<IPv4Matching> | Array<IPv6Matching> | Array<PortMatching>`, keyed by the
+sibling `type` field (A3, `8ee11f1`) — previously opaque `unknown`. The runtime schema is still a
+passthrough `S.Unknown` (Argo CD's `union:` callback): narrower for a reader at the TYPE level only,
+so decode keeps every key including one this pinned spec doesn't yet declare, the same proof
+`discriminated-filter-decode.test.ts` runs for `FirewallPolicy`/`AclRule`.
+
+⚠️ **Known gap (T15, same shape `acl-rule-form.ts`/`docs/unifi-firewall-policy.md` both carry)**: a
+traffic matching list's `items` is semantically a SET of match entries — matching is "is this
+traffic covered by ANY entry," not order-dependent — but each entry is an OBJECT
+(`{type, value?, start?, stop?}`), not a bare string, so there is no cheap canonical sort key the
+way `sortedSet` gives a `string[]`. `deepEqual` compares `items` order-sensitively, so a
+console-side reorder with no membership change would report a spurious drift this read-only
+family's `reconcile` then refuses forever. Accepted, not fixed: a generic object-set normalizer is
+bigger, separate modelling work, not a mechanical extension of typing `items` per-discriminator.
+
+## T11 gate: per-tag closure diff, 10.4.57 vs 10.6.97 (checked 2026-09-26)
+
+Same method `docs/unifi-acl-rule.md`/`docs/unifi-firewall-policy.md` use, run here for the
+`Traffic Matching Lists` tag's 5 operations (`getTrafficMatchingLists`, `createTrafficMatchingList`,
+`deleteTrafficMatchingList`, `getTrafficMatchingList`, `updateTrafficMatchingList`).
+
+- **Pin**: `~/.cache/homeflare/schemas/unifi/network_v10.4.57_openapi.json`, re-verified against
+  its own `SHA256SUMS` today (`3773947b…c9df59d`).
+- **Mirror**: `raw.githubusercontent.com/beezly/unifi-apis/main/unifi-network/10.6.97.json`,
+  diffing aid only, never a spec of record — re-fetched today, still `info.version: "10.6.97"`,
+  `sha256: 44fd0e7f81603bb1279889a528a443d8f1a0102436e4a29675d8451adf32bd78`, unchanged since mirror
+  commit `f979dd64ec0ea6008c2a698c278fe49a10e102c8` (Andrew Beresford, 2026-08-20, "Add UniFi API
+  specs: Network 10.6.97", GitHub-verified signature) — the same file every other family doc cites.
+- **Operation count**: both versions carry exactly the same 5 operations for `Traffic Matching
+Lists` — zero added, zero removed, either direction.
+- **Full raw operation objects** (parameters, request body, responses, unresolved `$ref`s included):
+  byte-identical for all 5, both versions.
+- **Reachability** (`$ref` AND `discriminator.mapping`): the closure is **19 schema names**
+  (`IPv4Matching`/`IPv6Matching`/`Port matching` and each of the three list-shape Dto pairs, plus
+  their subnet/range/address variant Dtos), identical set in both versions. **Zero overlap** with
+  the 14 schemas that changed elsewhere in the document — re-diffed all 19 with an
+  order-independent structural compare: **zero differ**.
+- **Corroboration**: the A3 changeset's own broader re-check
+  (`.changeset/unifi-network-a3-typed-discriminator-filters.md`) independently walked all 25
+  FirewallPolicy/ACL rule/TrafficMatchingList operations together — a 139-schema closure, also
+  byte-identical between versions — against a mirror fetch the same day; see
+  `docs/unifi-firewall-policy.md`'s own T11 section for why that citation's different-looking
+  mirror commit is the same unchanged file.
+
+**Answer: `TrafficMatchingList` would not decode differently against 10.6.97.** This does not
+generalize past 10.6.97 or to any other tag — re-run this check, following BOTH `$ref` and
+`discriminator.mapping`, before importing or declaring against `Clients`, `Switching`, or any tag
+not yet covered by an existing `docs/unifi-*.md`.
+
+## The declaration renderer
+
+`declareTrafficMatchingList(live, siteId)` is a pure function, same contract as every other
+family's own (`docs/unifi.md`): given one `getTrafficMatchingList` response, it returns the `Props`
+a declaration needs so its plan is a no-op.
+
+## Field-level drift
+
+`traffic-matching-list.ts` exports a pure `driftOf(live, props)` (`traffic-matching-list-drift.ts`),
+built on the same `drift.ts`'s `makeDriftOf` framework as every other family — `matches` is exactly
+`fieldDrift(...).length === 0`, never a second hand-written comparison (MEDIUM-4).
+
+## Vendor version
+
+UniFi Network Integration API **10.4.57**, same pin as `docs/unifi.md`, via
+`@distilled.cloud/unifi-network` aliased onto `@homeflare/distilled-unifi-network@0.3.0`.

package/docs/unifi-wifi.md

@@ -0,0 +1,120 @@
+# UniFi WiFi Broadcasts — `Unifi.WifiBroadcast`
+
+⛔ **READ-ONLY, BY TIM'S RULE (2026-09-24).** Same posture as `docs/unifi.md`'s `Unifi.Network`/
+`Unifi.FirewallZone`: `reconcile`/`delete` both fail with a typed `UnifiWriteRefused`, and the
+`GetOnlyHttpClient` wire guard (`resource.ts`) refuses any non-`GET` request before it reaches the
+transport. This family calls no SDK write op anywhere — `write-op-reference.test.ts` proves it
+statically, and `wifi-broadcast.test.ts`'s own write-path tests prove `reconcile`/`destroy` never
+send anything but `GET`s.
+
+## T23: the passphrase-bearing details call is never made
+
+The pinned spec's WiFi Broadcast "details" shape (`getWifiBroadcastDetails`, and the create/update
+request bodies) — `WifiSecurityConfigurationDetailObject` — carries the WPA passphrase AND every
+PPSK entry's own passphrase, with **no `writeOnly` flag on either** (verified: 4 `passphrase`
+properties, 0 `writeOnly` flags, in the staged 10.4.57 spec). `README.md`'s claim that these fields
+are "write-only" was wrong; A2 (kit PR #300) fixed the SDK layer by decoding them `Redacted`
+instead of a plain string, proven at the wire in `errors-and-secrets.test.ts`.
+
+This family goes further and **never calls that shape at all.** The only SDK call
+`wifi-broadcast.ts` makes is `getWifiBroadcastPage` — the LIST endpoint, which answers
+`WifiBroadcastOverview` rows. That type's own `securityConfiguration`
+(`WifiSecurityConfigurationOverview`) is `{type, presharedKeyNetworkIds}`: no passphrase field
+exists on it, so there is no DECLARED field for `attributesOf`/`declareWifiBroadcast` to name a
+passphrase into. A static guard (`wifi-broadcast-details-call.test.ts`) additionally bans any
+source reference to `getWifiBroadcastDetails` itself under `src/unifi` (red team, IMPORTANT-2),
+with one named exception: `errors-and-secrets.test.ts` (A2) calls it directly on purpose, to prove
+the SDK's own redaction happens at the wire — a different, lower-layer claim than this family ever
+needing to make that call.
+
+⛔ **This is NOT enforced by the type system alone** (red team, IMPORTANT-1) — corrected from an
+earlier version of this doc that overclaimed it was. `@distilled.cloud/core`'s wire decode does not
+strip a key a schema doesn't declare, so a stray key nested inside `network`, `hotspotConfiguration`,
+`broadcastingDeviceFilter`, or one `presharedKeyNetworkIds` element could ride through a naive
+pass-through exactly like the top-level `securityConfiguration` object could. See "The stray-key
+defense" below — enumeration at runtime, not the TS annotation, is what actually stops it.
+
+### No get-by-id call exists for the overview shape
+
+Unlike every other family here (`getNetworkDetails`, `getFirewallZone`, `getDnsPolicy`,
+`getAclRule`), `wifi_broadcasts.ts` has no single-object GET that returns the overview shape — only
+the list (safe) and the details call (forbidden above). `wifi-broadcast.ts`'s `fetchLive` walks
+every page with B0b's `pageAll` (`paginate.ts`) and finds the row matching `wifiBroadcastId` — the
+first real resource-level consumer of that pager, previously exercised only in isolation by
+`paginate.test.ts`. A genuine site-not-found 404 on ANY page of the walk — not only the first —
+folds to `undefined` like every other family, discarding whatever rows the walk had already
+collected (red team, MINOR-4: an earlier version of this doc said "on the first page call", which
+overstated how narrowly the catch is scoped); the target id simply not being among the collected
+rows folds to `undefined` too — there is no separate vendor signal to tell any of these cases apart,
+and no other family's `fetchLive` has one either.
+
+### The stray-key defense (why `normalizeSecurityConfiguration` never spreads)
+
+Nothing in `@distilled.cloud/core`'s wire key-mapping strips an object key the schema does not
+declare — it only renames declared ones (measured directly against the installed
+`@distilled.cloud/core@1.0.0-rc.12`: a struct decode keeps every key from the raw response,
+declared or not). So a stray `passphrase`-shaped key on the WIRE `securityConfiguration` object — a
+vendor bug, or a future console version — physically survives into the `live` object `fetchLive`
+returns, even though `WifiBroadcastOverview`'s own TS type has no such field.
+
+`wifi-broadcast-form.ts`'s `normalizeSecurityConfiguration` is the one normalizer in this whole
+`Unifi.*` tree that does **not** use `{...value}` (every sibling normalizer, `network-form.ts`'s
+included, spreads its input). It enumerates exactly `{type, presharedKeyNetworkIds}` instead —
+`attributesOf`/`declareWifiBroadcast` are built the same way, field by field, never `{...live}`.
+
+⛔ **The same discipline applies to every OTHER nested object this family handles, not just
+`securityConfiguration`** (red team, IMPORTANT-1) — `normalizeRef` rebuilds `network` and each
+`presharedKeyNetworkIds` element as `{type, networkId?}`, `normalizeHotspot` rebuilds
+`hotspotConfiguration` as `{type}`, and `normalizeDeviceFilter` no longer spreads
+`broadcastingDeviceFilter` either. A `presharedKeyNetworkIds` element is the single most plausible
+leak site of the four: `IntegrationWifiPresharedKeyDto`, the details-call shape for a PPSK entry, is
+literally `{network: WifiNetworkReference, passphrase}` — the same reference shape this family's
+overview also uses, just with one more field the overview type doesn't declare.
+
+`wifi-broadcast-secrets.test.ts`'s sentinel tests prove the pipeline for all five locations
+(`securityConfiguration`, a `presharedKeyNetworkIds` element, `network`, `hotspotConfiguration`,
+`broadcastingDeviceFilter`): each plants a raw sentinel key that genuinely does survive into `live`
+(asserted directly, not assumed away), then proves `attributesOf`, `declareWifiBroadcast`, and the
+literal string a later import script would render into `alchemy.run.ts` none of them carry it
+forward.
+
+### The forced decode-failure test
+
+`wifi-broadcast-secrets.test.ts`'s decode-failure test sends a non-JSON 200 body (a genuine decode
+failure — this SDK's REST decode has no schema-validating step to reject a malformed body with; see
+`@distilled.cloud/core`'s `protocol-rest.ts`) that happens to contain a sentinel value, the way a
+garbled proxy or debug response might. `pageAll`'s own consistency check (`paginate.ts`) catches it
+— the malformed "page" has no `.offset`, so the walk refuses to trust it — and fails typed as
+`UnifiPaginationInconsistent`. That error's `reason`/`detail`/`message` are built from `offset`/
+`totalCount` values run through `paginate.ts`'s `numOrPlaceholder` (red team, MINOR-3: an earlier
+version of this doc said these fields were "never from the raw response body", but `offset`/
+`totalCount` themselves ARE unvalidated wire values — `paginate.test.ts`'s own test proves a
+non-numeric one renders as a fixed placeholder, never as itself), so none of them can ever echo
+attacker- or vendor-controlled text regardless of what the server actually sent.
+
+## Field-level drift
+
+Three fields are membership SETS, not ordered sequences, by the vendor description's own wording
+("Defines the custom scope of devices…") and unconfirmed against a live console (same caveat
+`network-form.ts` carries for its own three): `broadcastingDeviceFilter.deviceIds`/`.deviceTagIds`
+and `securityConfiguration.presharedKeyNetworkIds`. `wifi-broadcast-form.ts`'s
+`normalizeDeviceFilter`/`normalizeSecurityConfiguration`/`normalizeFrequencies` sort+dedupe them
+before comparison, on both the live AND declared sides (`wifi-broadcast-drift.ts`), the same
+`firewall-zone-form.ts`'s `networkIds` pattern — otherwise a console returning the same set in a
+different order would plan a spurious `update` that a read-only `reconcile` then refuses.
+
+`wifi-broadcast.ts` exports a pure `driftOf(live, props)`, built on `drift.ts`'s `makeDriftOf`
+framework. `matches` is exactly `fieldDrift(...).length === 0` (MEDIUM-4).
+
+## The declaration renderer
+
+`declareWifiBroadcast(live, siteId)` is a pure function: given one `WifiBroadcastOverview` row (as
+`getWifiBroadcastPage` returns it, never `getWifiBroadcastDetails`), it returns the `Props` a
+declaration needs so its plan is a no-op. A later import script pages every WiFi broadcast on a
+site and writes one `wifiBroadcast('<id>', declareWifiBroadcast(live, siteId))` row per result —
+nothing here performs that write.
+
+## Vendor version
+
+UniFi Network Integration API **10.4.57**, same pin as `docs/unifi.md`, via
+`@distilled.cloud/unifi-network` aliased onto `@homeflare/distilled-unifi-network@0.3.0`.

package/docs/unifi.md

@@ -6,6 +6,11 @@ with a typed `UnifiWriteRefused` naming the policy rather than calling any SDK w
 Lifting the rule is a kit change — a PR that adds a write path, reviewed as one — not a flag a
 stack can pass. See `packages/alchemy/src/unifi/policy.ts`.
 
+This page covers `Unifi.Network`/`Unifi.FirewallZone` only. Every other read-only family has its
+own doc, per family (`docs/unifi.md` would breach the 200-line cap otherwise): [`Unifi.DnsPolicy`](./unifi-dns-policy.md), [`Unifi.AclRule`/`Unifi.AclRuleOrdering`](./unifi-acl-rule.md),
+[`Unifi.WifiBroadcast`](./unifi-wifi.md), [`Unifi.FirewallPolicy`/`Unifi.FirewallPolicyOrdering`](./unifi-firewall-policy.md),
+and [`Unifi.TrafficMatchingList`](./unifi-traffic-matching-list.md).
+
 ## What's declared, and why these two first
 
 `Unifi.Network` (`getNetworkDetails`/`getNetworksOverviewPage`) and `Unifi.FirewallZone`
@@ -13,9 +18,8 @@ stack can pass. See `packages/alchemy/src/unifi/policy.ts`.
 not runtime state (a connected client, a device statistic, a hotspot voucher, a switch stack).
 `Site` was the SDK README's other first suggestion; it has no `getSite`, only the list operation,
 so it fails this house's own "both a list and a get" bar for a first import. `FirewallPolicy` is
-also a list+get config object, but its `source`/`destination`/`ipProtocolScope` fields carry
-several of the vendor's converter-flattened discriminator variants each, and its ordering
-endpoint replaces the whole rule list — modelling that correctly is a bigger, separate PR.
+also a list+get config object; modelling it correctly needed its own PR (now shipped — [`docs/unifi-firewall-policy.md`](./unifi-firewall-policy.md)) because its ordering endpoint replaces the whole
+rule list per zone pair, and it was gated on A3 typing its filter fields' discriminator variants first.
 
 ## Credentials
 
@@ -102,8 +106,9 @@ operations (`getNetworksOverviewPage`, `getFirewallZones`, …), none of which p
 own — no `smithy.api#paginated` trait exists in the pinned spec, and neither the SDK nor
 `@distilled.cloud/core` gained one for this. It stops on the response's `totalCount`, never on
 `data.length < limit` (a page can legitimately come back short of the requested limit without
-being the last page). No family here has enough rows to need it yet; it exists ahead of
-`Unifi.FirewallPolicy` (hundreds of rows on a real console), which does.
+being the last page). `Unifi.WifiBroadcast` (`docs/unifi-wifi.md`) is its first resource-level
+consumer, walking every page because that family has no get-by-id call at all; `docs/unifi-firewall-policy.md`'s own decode-proof test exercises the same page shape for `getFirewallPolicies`
+(hundreds of rows on a real console — T9), though `Unifi.FirewallPolicy` itself still reads by id.
 
 It also fails with a typed `UnifiPaginationInconsistent` — never silently returns a wrong row
 set — the moment a paged response contradicts itself: a page's echoed `offset` doesn't match what

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.39.0",
+  "version": "0.40.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",
@@ -56,6 +56,10 @@
       "types": "./dist/proxmox/index.d.ts",
       "default": "./dist/proxmox/index.js"
     },
+    "./ceph": {
+      "types": "./dist/ceph/index.d.ts",
+      "default": "./dist/ceph/index.js"
+    },
     "./launchd": {
       "types": "./dist/launchd/index.d.ts",
       "default": "./dist/launchd/index.js"
@@ -131,7 +135,7 @@
     "@distilled.cloud/paperless-ngx": "npm:@homeflare/distilled-paperless-ngx@0.3.0",
     "@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.3.3",
     "@distilled.cloud/proxmox-backup": "npm:@homeflare/distilled-proxmox-backup@0.3.1",
-    "@distilled.cloud/unifi-network": "npm:@homeflare/distilled-unifi-network@0.3.0"
+    "@distilled.cloud/unifi-network": "npm:@homeflare/distilled-unifi-network@0.4.0"
   },
   "peerDependencies": {
     "@distilled.cloud/argocd": "1.0.0-rc.12",

package/src/ceph/auth-entity.ts

@@ -0,0 +1,74 @@
+/**
+ * `Ceph.AuthEntity` (K-A4) — a Ceph client auth entity (`client.k8s-*`), minted over the ssh
+ * mon-command transport and stored only in OpenBao. Design: docs/plans/2026-09-26-ceph-mon-
+ * transport.md, "`Ceph.AuthEntity` (K-A4)"; the loop itself lives in ceph-auth-reconcile.ts, the
+ * transport in ceph-transport.ts, the allowlist in ceph-argv.ts.
+ *
+ * ⛔ `read` AND `diff` NEVER SSH. "A plan never elevates" (../linux/sudo-runner.ts's own header
+ *   makes the same rule for the file family): this family's props/state comparison is the whole
+ *   of `diff`, and `read` hands back exactly the attributes state already holds. Live drift is
+ *   caught only at `reconcile` (which does elevate, on the admin lane) and by the post-deploy
+ *   operator check — this family cannot prove live convergence at plan time, and says so rather
+ *   than pretending an unprivileged probe exists where none does.
+ * ⛔ `delete` IS REFUSED UNCONDITIONALLY. `defaultRemovalPolicy: 'retain'` keeps Alchemy from ever
+ *   calling it on an ordinary `destroy`, and the handler itself refuses too — belt and suspenders
+ *   with ceph-argv.ts's own refusal of the `auth del` shape, so there is no path, `--adopt` or a
+ *   resource-level removal-policy override included, that ever reaches it (D3).
+ * ⛔ NEVER ADOPTED. See ceph-auth-reconcile.ts's header for why the generic `refuseTakeover` is not
+ *   used here.
+ * ⛔ ROWS ARE CREATES THROUGH THE FIRST-CREATE GATE, NO `adopt()` — `list` answers empty, the same
+ *   as every Ceph family in this kit (ceph-pool.ts's header has the reason a non-empty list would
+ *   invite exactly the takeover this family refuses).
+ */
+import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import type { CephAuthEntityAttributes, CephAuthEntityProps } from './ceph-auth-form.ts';
+import { planCephAuthEntity } from './ceph-auth-form.ts';
+import { reconcileCephAuthEntity } from './ceph-auth-reconcile.ts';
+
+export type { CephAuthEntityAttributes, CephAuthEntityProps } from './ceph-auth-form.ts';
+export type { CephCaps } from './ceph-auth-parse.ts';
+
+export interface CephAuthEntity extends Resource<
+  'Ceph.AuthEntity',
+  CephAuthEntityProps,
+  CephAuthEntityAttributes,
+  never,
+  HttpClient.HttpClient
+> {}
+
+/** ★ `retain` — the delete handler below refuses regardless, but this stops Alchemy calling it. */
+export const CephAuthEntity = Resource<CephAuthEntity>('Ceph.AuthEntity', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const refusedDelete = (entity: string): Error =>
+  new Error(
+    `Ceph.AuthEntity ${entity}: 'ceph auth del' is refused entirely — lockout safety, never ` +
+      'auto-delete (D3). Nothing was sent to any mon. If the entity truly must go, remove it by ' +
+      'hand, deliberately, along with its OpenBao key — this family will never do it for you.',
+  );
+
+export const CephAuthEntityProvider = () =>
+  Provider.effect(
+    CephAuthEntity,
+    Effect.succeed(
+      CephAuthEntity.Provider.of({
+        list: () => Effect.succeed([]),
+
+        /** State only — see the header. Never `Unowned`: this family is never adopted. */
+        read: ({ output }) => Effect.succeed(output),
+
+        /** State only — see the header. `output === undefined` lets reconcile decide (a create). */
+        diff: ({ news, output }) =>
+          Effect.succeed(isResolved(news) ? planCephAuthEntity(news, output) : undefined),
+
+        reconcile: ({ news, output }) => reconcileCephAuthEntity(news, output, {}),
+
+        delete: ({ output }) => Effect.die(refusedDelete(output.entity)),
+      }),
+    ),
+  );

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

@@ -0,0 +1,78 @@
+/**
+ * The `ceph config get/set/rm` half of the argv allowlist — split out of ceph-argv.ts (which
+ * re-exports `configProblem`) purely to keep that file under the house's 250-line file cap; the
+ * 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.
+ */
+import { NAMED_CONFIG_OPTIONS, 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}$/;
+/**
+ * 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),
+ *   CONFIRMED: the prior pattern let a config VALUE start with `-`, and this argv reaches
+ *   `sudo -n /usr/bin/ceph` with no shell in between — no shell means no quoting boundary, so
+ *   `ceph config set global x -o/etc/ceph/ceph.conf` parses as ceph's own `-o <file>` flag, not
+ *   as the string `-o/etc/ceph/ceph.conf`. Accepted flag-shaped values included
+ *   `--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.
+ */
+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.
+ */
+export const configValueProblem = (value: string): string | undefined =>
+  CONFIG_VALUE.test(value)
+    ? 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
+ * ceph-config-options.ts's header for why the list starts empty and stays reviewed line by line.
+ */
+const namedOptionProblem = (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)
+    ? undefined
+    : `${name} is not on the named option list (it starts empty — see ceph-config-options.ts)`;
+};
+
+/** `config get|set|rm <who> <name> [value]`, called with the operands after `config` stripped. */
+export const configProblem = (rest: readonly string[]): string | undefined => {
+  const [verb, who, name, ...extra] = rest;
+  if (who === undefined || !WHO.test(who)) {
+    return 'config takes a bounded `<who>` (global/mon/osd/mgr/mds/client[.id])';
+  }
+  if (name === undefined) return 'config takes a `<name>` from the named option list';
+  if (verb === 'get' || verb === 'rm') {
+    return extra.length === 0
+      ? namedOptionProblem(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);
+    return named !== undefined ? named : configValueProblem(value);
+  }
+  return `ceph config ${String(verb)} is not on the allowlist`;
+};

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

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