@homeflare/alchemy 0.41.0 → 0.43.0

package/src/proxmox/ceph-flag.ts

@@ -73,73 +73,24 @@
  *     "Permission check failed (/, Sys.Modify)" on the first deploy, and widen deliberately.
  */
 import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
-import { bool, flag } from './values.ts';
+import {
+  CEPH_FLAG_UPDATE,
+  readClusterCephFlag,
+  readClusterCephFlagForDiff,
+  updateForm,
+  writeClusterCephFlag,
+} from './ceph-flag-wire.ts';
+import { mintTier } from './credentials.ts';
+import { UNREADABLE, unreadableWarning } from './unreadable-read.ts';
+import { guardWrite } from './distilled-guard.ts';
+import type { CephFlagAttributes, CephFlagProps } from './ceph-flag-types.ts';
+import type { PveRequirements } from './resource-spec.ts';
+import { formToSend } from './update-guard.ts';
 
-/**
- * PVE's eleven flags, spelled as `PVE::Ceph::Tools::get_possible_osd_flags` spells them.
- *
- * ⚠️ THE ENUM IS CLOSED AND A TYPO IS A 400, WHICH IS WHY THIS IS A UNION AND NOT `string`. Both
- *   the GET and the PUT declare `additionalProperties => 0` over exactly this list.
- * ⚠️ CEPH HAS FLAGS PVE DOES NOT MODEL, and four of them are always on. MEASURED on C1:
- *   `ceph osd dump` reports `flags sortbitwise,recovery_deletes,purged_snapdirs,pglog_hardlimit`.
- *   PVE reads that same string and answers only about its own eleven, so the others can neither
- *   leak in here nor be set from here — `noautoscale` and `nosnaptrim` included.
- *   ⛔ IF SOMEBODY LATER "IMPROVES" THE READ BY PARSING `osd dump` DIRECTLY, those four become
- *     permanently-set flags that nothing declares: a forever-diff on a brand new cluster.
- */
-export type CephFlagName =
-  | 'nobackfill'
-  | 'nodeep-scrub'
-  | 'nodown'
-  | 'noin'
-  | 'noout'
-  | 'norebalance'
-  | 'norecover'
-  | 'noscrub'
-  | 'notieragent'
-  | 'noup'
-  | 'pause';
-
-export interface CephFlagProps extends WithTarget {
-  /**
-   * Which flag. PVE's primary key here, and the last segment of the path.
-   *
-   * ⚠️ EDITING IT IN PLACE ORPHANS THE OLD FLAG RATHER THAN MOVING ANYTHING. `diff` reads the NEW
-   *   path and reconcile writes it, while the old flag keeps whatever this stack last put there.
-   *   There is deliberately no replace override for it — acl.ts needs one because its `delete`
-   *   removes a real grant, and `delete` here is inert by design, so a replace would do exactly
-   *   what an update already does. Declare a second resource and set the old one to `value: false`
-   *   rather than renaming this one.
-   * ⛔ TWO RESOURCES DECLARING THE SAME FLAG ARE ONE CLUSTER OBJECT, and Alchemy sees two ids
-   *   rather than a collision — the acl.ts hazard exactly. Disagreeing, they take turns winning
-   *   and BOTH plan `update` for ever; agreeing, deleting either leaves the flag where the other
-   *   put it. One declaration per flag per cluster.
-   */
-  flag: CephFlagName;
-  /**
-   * Set the flag (`true`) or clear it (`false`).
-   *
-   * ⛔ REQUIRED, WITH NO DEFAULT — see the second ⛔ in the header, which is the whole safety
-   *   argument for this family. It is also the only field PVE accepts on this endpoint, and it is
-   *   not optional in the schema either: omitting it from the form is a 400, not an untouched
-   *   flag. (The BULK endpoint is the one where omission means "leave it alone"; this is not it.)
-   */
-  value: boolean;
-}
-
-export interface CephFlagAttributes {
-  /**
-   * ⚠️ REPORTED, NEVER COMPARED. It is the path key the read was made WITH, copied back out of
-   *   props, so comparing it against props would be true by construction — the same reasoning
-   *   acl.ts gives for the four identity fields it also declines to diff.
-   */
-  flag: CephFlagName;
-  /** Whether ceph has the flag set right now. The only field `matches` looks at. */
-  value: boolean;
-}
+export type { CephFlagAttributes, CephFlagName, CephFlagProps } from './ceph-flag-types.ts';
 
 export interface ProxmoxCephFlag extends Resource<
   'Proxmox.CephFlag',
@@ -151,86 +102,82 @@ export interface ProxmoxCephFlag extends Resource<
 
 export const ProxmoxCephFlag = Resource<ProxmoxCephFlag>('Proxmox.CephFlag');
 
-const handlers = pveHandlers<CephFlagProps, CephFlagAttributes>({
-  /**
-   * ⚠️ `live` IS A BARE BOOLEAN HERE, NOT AN OBJECT, AND IT IS HANDED TO `bool` WHOLE ON PURPOSE.
-   *   `get_flag` returns perl `1` or `0` under a `type => 'boolean'` return schema, so the wire is
-   *   `{"data":0}` or `{"data":false}` depending on how the REST layer renders it. `bool` accepts
-   *   every one of those spellings, which is exactly why it is a shared coercion. The factory
-   *   types this parameter `Record<string, unknown>` because every OTHER PVE read is an object;
-   *   reaching for `live['value']` here would answer undefined on every plan and diff `false`
-   *   forever against a set flag.
-   *   ⚠️ THE SCALAR IS A MEASURED PROPERTY OF THIS PVE, NOT A PROMISE. A later version wrapping
-   *     the answer in an object would make `bool` read a SET flag as false, and `value: false`
-   *     would then plan `noop` over a live flag — silently. Re-measure
-   *     `GET /cluster/ceph/flags/noout` after a major upgrade; cheaper than a second parse path.
-   *
-   * ⛔ IT NEVER ANSWERS undefined, WHICH MAKES THE CREATE BRANCH UNREACHABLE, AND ITS ERROR WILL
-   *   MISLEAD YOU. All eleven flags always exist; there is nothing for "absent" to mean. So a POST
-   *   to `collection` means the READ failed — an expired 300s lease, node-b down, or ceph simply not
-   *   configured on the cluster (every one of these four handlers opens with
-   *   `check_ceph_configured()`, which dies). Read the resulting "Method 'POST /cluster/ceph/flags'
-   *   not implemented" as "the read failed" and go and look at the credential, not at ceph. Same
-   *   shape as the unreachable POST in acl.ts, same advice.
-   */
-  attributes: (live, props) => ({ flag: props.flag, value: bool(live) }),
-  collection: () => 'cluster/ceph/flags',
-  /**
-   * ⛔ UNREACHABLE — see the second ⛔ in `attributes`. It is written in the BULK endpoint's shape
-   *   (the flag name is the parameter, not `value`) rather than left empty, because that is the
-   *   only body `cluster/ceph/flags` has ever documented. Nothing sends it today.
-   */
-  createForm: (props) => ({ [props.flag]: flag(props.value) ?? '0' }),
-  endpoint: { update: 'pve:PUT /cluster/ceph/flags/{flag}' }, // ⛔ No create: see above.
-  /**
-   * ⚠️ `value` IS THE ONLY THING COMPARED, AND THE LIST OF THINGS DELIBERATELY NOT COMPARED IS THE
-   *   point of this resource. `flag` is props-derived (see `CephFlagAttributes`). `description`
-   *   and `name` exist only on the bulk GET, which this file does not read, so neither can be
-   *   compared by accident. Nothing PVE returns here is rewritten, re-ordered or re-typed by the
-   *   cluster, because all PVE returns here is one boolean.
-   *   ★ MEASURED: on C1, `GET /cluster/ceph/flags` answers value 0 for all eleven flags, so a
-   *     declaration of `value: false` reads back false and plans `noop`.
-   */
-  matches: (attributes, props) => attributes.value === props.value,
-  path: (props) => `cluster/ceph/flags/${props.flag}`,
-  /**
-   * ⚠️ ONLY `value` GOES IN THE BODY. `flag` is already bound by the path and the PUT declares
-   *   `additionalProperties => 0`, so a second copy in the form could only disagree with the URL.
-   * ⚠️ THE `?? '0'` IS UNREACHABLE, AND IS WRITTEN RATHER THAN CAST AWAY. `flag()` types its
-   *   answer `string | undefined` because it serves OPTIONAL props, and `value` here is required,
-   *   so the branch cannot be taken; a cast would claim a proof the type system has not made.
-   */
-  updateForm: (props) => ({ value: flag(props.value) ?? '0' }),
-});
+/**
+ * ⚠️ `value` IS THE ONLY THING COMPARED, AND THE LIST OF THINGS DELIBERATELY NOT COMPARED IS THE
+ *   point of this resource. `flag` is props-derived (see `CephFlagAttributes`). `description`
+ *   and `name` exist only on the bulk GET, which this file does not read, so neither can be
+ *   compared by accident. Nothing PVE returns here is rewritten, re-ordered or re-typed by the
+ *   cluster, because all PVE returns here is one boolean.
+ *   ★ MEASURED: on C1, `GET /cluster/ceph/flags` answers value 0 for all eleven flags, so a
+ *     declaration of `value: false` reads back false and plans `noop`.
+ */
+const matches = (attributes: CephFlagAttributes, props: CephFlagProps) =>
+  attributes.value === props.value;
 
+/**
+ * ★ MIGRATED OFF `pveHandlers`/`client.ts`'s generic `pve()` ONTO `@distilled.cloud/proxmox`'s
+ *   typed `cluster.getClusterCephFlag`/`cluster.putClusterCephFlag` (ceph-flag-wire.ts).
+ *   `pveHandlers` cannot run a distilled operation, so `diff`/`reconcile` are hand-written here,
+ *   the same way ceph-pool.ts and backup-job.ts hand-write theirs for the same reason.
+ *
+ * ⛔ THIS FAMILY HAS NO CREATE KEY, AND THAT IS THE VENDOR'S DOING, NOT AN OMISSION HERE. PVE
+ *   registers only `PUT /cluster/ceph/flags/{flag}`; `POST /cluster/ceph/flags` does not exist
+ *   (constraints-forms.test.ts's own regression test), which is why the second ⛔ in the header
+ *   above calls the create branch unreachable — there is no create form and no create endpoint to
+ *   guard, only `CEPH_FLAG_UPDATE`.
+ */
 export const ProxmoxCephFlagProvider = () =>
   Provider.effect(
     ProxmoxCephFlag,
     Effect.succeed(
       ProxmoxCephFlag.Provider.of({
-        /**
-         * ⚠️ NOT THE ONE-LINE `Provider.of(handlers)` EVERY OTHER FILE HERE USES, AND THE TWO
-         *   REASONS ARE BOTH acl.ts's. PVE implements no DELETE on this path, and the factory's
-         *   read-back guard is dead whenever `attributes` cannot answer undefined. Unlike acl.ts
-         *   this SPREADS the factory's handlers instead of retyping them, so `list`, `read` and
-         *   `diff` cannot drift from the shared ones — only the two that genuinely differ are
-         *   written out below.
-         */
-        ...handlers,
+        /** ⛔ Empty, like every resource in this package — see resource.ts's own ⚠️ on why. */
+        list: () => Effect.succeed([]),
+        read: ({ olds }) => readClusterCephFlag(olds),
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news)) return undefined;
+          yield* guardWrite(CEPH_FLAG_UPDATE, updateForm(news), false);
+          if (output === undefined) return undefined;
+          // ⛔ Never absent — see the second ⛔ above. A failed read other than a refused mint
+          //   propagates instead of reaching this point. A refused mint must NOT fail `diff`:
+          //   that aborts the whole plan (unreadable-read.ts). `read` still propagates.
+          const live = yield* readClusterCephFlagForDiff(news);
+          if (live === UNREADABLE) {
+            yield* unreadableWarning(
+              'Proxmox.CephFlag',
+              news.flag,
+              news.target.mount,
+              mintTier(news.target, 'read'),
+            );
+            return { action: 'noop' } as const;
+          }
+          return { action: matches(live, news) ? 'noop' : 'update' } as const;
+        }),
         /** ⛔ Inert, deliberately. The third ⛔ in the header is the whole argument; read it. */
         delete: () => Effect.void,
         /**
-         * ⚠️ THE READ-BACK GUARD, RESTORED FOR A FAMILY WHOSE "ABSENT" DOES NOT EXIST.
-         *   `ops.reconcile` refuses when the object is still missing after a write, and a flag is
-         *   never missing, so that check can never fire here — exactly the hole acl.ts patches
-         *   with `bound`. PVE answers 200 with `{"data":null}` on calls that did nothing, and this
-         *   PUT's documented return IS null, so the status code carries no evidence at all.
+         * ⚠️ THE READ-BACK GUARD, RESTORED FOR A FAMILY WHOSE "ABSENT" DOES NOT EXIST. A generic
+         *   `reconcile` (resource.ts) refuses when the object is still missing after a write, and
+         *   a flag is never missing, so that check could never fire here. PVE answers 200 with
+         *   `{"data":null}` on calls that did nothing, and this PUT's documented return IS null,
+         *   so the status code carries no evidence at all — only a read-back does.
          * ⚠️ THE PER-FLAG PUT IS SYNCHRONOUS (`$rados->mon_command` inline, MEASURED in Ceph.pm),
          *   which is what makes this check fair rather than a race against a worker task. If it
          *   ever fires spuriously the honest fix is to look at the mon, not to delete the guard.
+         * ⛔ `formToSend` IS WHAT MAKES ADOPTING AN ALREADY-MATCHING FLAG FREE. Alchemy's
+         *   `adopted` action reaches `reconcile` exactly like `update` does (resource.ts's own ⛔
+         *   on this), so without this guard adopting a flag that already reads correctly would
+         *   still fire a PUT — pointless against ceph, and update-guard.ts's header has the
+         *   incident where the equivalent gap on CephPool forked an unnecessary worker.
          */
         reconcile: Effect.fn(function* ({ news }) {
-          const after = yield* handlers.reconcile({ news });
+          const live = yield* readClusterCephFlag(news);
+          const form = formToSend(matches, live, news, updateForm(news));
+          if (form !== undefined) {
+            yield* guardWrite(CEPH_FLAG_UPDATE, updateForm(news), false);
+            yield* writeClusterCephFlag(news);
+          }
+          const after = yield* readClusterCephFlag(news);
           if (after.value !== news.value) {
             return yield* Effect.die(
               new Error(

package/src/proxmox/ceph-osd-write.ts

@@ -102,19 +102,16 @@ export const createOsd = Effect.fn(function* (news: CephOsdProps) {
  * ⚠️ `cleanup` DEFAULTS TO FALSE, so the logical volumes survive and the disk can be re-added
  *   without a rebuild. Ceph still starts backfilling the missing copies the moment the OSD goes.
  *
- * ⚠️ `cleanup` RIDES A DELETE BODY, ON `client.ts` AND ON DISTILLED ALIKE — PRE-EXISTING, NOT
- *   INTRODUCED HERE. `client.ts`'s own `buildRequest` (client.ts) puts `form` in the body for
- *   every method, DELETE included, and CHECKED against distilled's generated
- *   `DeleteNodeCephOsdRequest`: `cleanup` carries no `T.Query()` annotation either, so it also
- *   defaults to a body field. ceph-fs-wire.ts's own ⛔ (measured from PVE's `AnyEvent.pm`) is that
- *   PVE's server never reads a body on DELETE — so `cleanup=1` was ALREADY silently ignored by
- *   the live cluster before this migration, on the unmigrated code too. Migrating carries the
- *   SAME behaviour forward exactly, byte-for-byte, rather than introducing a new gap; unlike
- *   `Proxmox.CephFs`'s delete, this is not a reason to keep the call on the hand client. It has
- *   zero practical effect today regardless, since the whole DELETE 403s for this package's
- *   credential either way (the root-only ⛔ at the top of ceph-osd.ts) — flagged separately as a
- *   pre-existing, out-of-scope bug worth its own fix (move `cleanup` into the query string, the
- *   way `destroyPath` in ceph-fs-wire.ts already does).
+ * ★ CORRECTED 2026-09-28: `cleanup` IS QUERY-BOUND ON DISTILLED, NOT BODY. This comment previously
+ *   claimed `DeleteNodeCephOsdRequest.cleanup` carried no `T.Query()` annotation and so rode the
+ *   DELETE body, silently ignored by PVE's server (which never reads a body on DELETE, per
+ *   ceph-fs-wire.ts's measurement of `AnyEvent.pm`). That was true of the old `client.ts` hand
+ *   client, but distilled-proxmox's generated schema
+ *   (`packages/distilled-proxmox/src/services/nodes.ts`) declares
+ *   `cleanup: S.optional(S.String.pipe(T.Query()))` — query-bound — as of SDK 0.3.0, the same fix
+ *   that landed for the sibling `Proxmox.CephFs`'s `destroyFs`. Since this file already runs on
+ *   distilled (`import * as nodes from '@distilled.cloud/proxmox/nodes'`), `cleanup: '1'` below
+ *   reaches PVE correctly today. No code change needed here; this was a stale doc claim only.
  */
 export const destroyOsd = (olds: CephOsdProps) =>
   runPve(

package/src/proxmox/credential-errors.ts

@@ -3,11 +3,10 @@
  * 250-line cap once this class grew a real header (2026-09-24, the cries-wolf fix).
  */
 import * as Data from 'effect/Data';
-import type { PveRole } from './credentials.ts';
 
 /**
- * OpenBao answered 403 to `GET /v1/<mount>/creds/<role>`: this identity's AppRole has no grant
- * for `role` on `mount` — measured 2026-09-24 as "the agent lane cannot mint `provision`" (the
+ * OpenBao answered 403 to `GET /v1/<mount>/creds/<tier>`: this identity's AppRole has no grant
+ * for `tier` on `mount` — measured 2026-09-24 as "the agent lane cannot mint `provision`" (the
  * lane's policy grants `read` but not `provision`). A TYPED tag, not the plain `Error` every
  * other mint failure still is (404 no such role/mount, 503 sealed, a network failure), because
  * this ONE case means "refused, not evidence of anything about the object" — a family's
@@ -18,15 +17,30 @@ import type { PveRole } from './credentials.ts';
  *   BROKEN, not this identity being narrowly scoped — folding those into "unreadable, report
  *   noop" would hide a real outage behind a quiet, misleadingly reassuring plan. Only 403 is
  *   "this identity, this role, denied" and safe to read as "cannot see, not evidence of absence".
+ *
+ * ⛔ NO `role` FIELD (removed, K-T1 second red-team pass). `mint.ts` knows the semantic `PveRole`
+ *   it was asked for, but `lease-cache.ts`'s synthetic `mintForKey` reconstruction (after M3
+ *   dropped `role` from `LeaseKey`) cannot supply the ORIGINAL caller's role on a cache-path
+ *   mint — only the tier. A `role` field would then read as `'read'` on every pve cache miss
+ *   regardless of which role was actually denied, which is exactly the stale/misleading-field
+ *   trap M6 existed to close, one layer down. `tier` alone is what the message reads and what
+ *   `readOrUnreadable`'s callers act on; nothing needs the semantic role name.
  */
 export class PveCredentialDenied extends Data.TaggedError('PveCredentialDenied')<{
   readonly mount: string;
-  readonly role: PveRole;
+  /**
+   * The OpenBao mint TIER actually requested (`credentials.ts`'s `mintTier`). ⛔ THE MESSAGE
+   *   READS THIS, NOT A SEMANTIC ROLE NAME: printing `'read'` for a denied `talos-provision`
+   *   mint would spell it as `creds/read`, exactly the path that was never called — silently
+   *   wrong at precisely the moment an operator is reading this string to decide whether a
+   *   grant, a policy or a target config is wrong (K-T1's own PR discussion).
+   */
+  readonly tier: string;
   readonly detail: string;
 }> {
   override get message(): string {
     return (
-      `OpenBao GET /v1/${this.mount}/creds/${this.role} -> 403: ${this.detail}. This identity's ` +
+      `OpenBao GET /v1/${this.mount}/creds/${this.tier} -> 403: ${this.detail}. This identity's ` +
       'AppRole has no grant for this role -- a refused read, not evidence the object is gone.'
     );
   }

package/src/proxmox/credentials.test.ts

@@ -12,7 +12,7 @@ import { join } from 'node:path';
 import { describe, it } from 'node:test';
 import * as Effect from 'effect/Effect';
 import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
-import type { BaoEnvironment, PveTarget } from './credentials.ts';
+import { type BaoEnvironment, type PbsTarget, type PveTarget, mintTier } from './credentials.ts';
 import { mint } from './mint.ts';
 
 /**
@@ -165,4 +165,76 @@ describe('mint', () => {
     );
     rmSync(socket, { force: true });
   });
+
+  // ⛔ K-T1: the whole point of `target.roles` is that a real HTTP request goes to the
+  //   OVERRIDDEN tier's path, not the bare role's — checked end to end here, not only through
+  //   `mintTier`'s own unit tests below.
+  it('requests the overridden tier, not the bare role, when target.roles names one', async () => {
+    const scoped: PveTarget = { ...C1, roles: { read: 'talos-provision' } };
+    await withFake(CREDENTIAL, async (address, seen) => {
+      await Effect.runPromise(
+        mint(scoped, 'read', { BAO_ADDR: address, BAO_TOKEN: TOKEN }).pipe(
+          Effect.provide(FetchHttpClient.layer),
+        ),
+      );
+      assert.equal(seen[0]?.path, '/v1/proxmox-c1/creds/talos-provision');
+    });
+  });
+
+  // ⛔ A role `target.roles` does not mention falls back to itself — an override on `read` alone
+  //   must never touch `provision` on the same target.
+  it('leaves an unmentioned role alone on a partially overridden target', async () => {
+    const scoped: PveTarget = { ...C1, roles: { read: 'talos-provision' } };
+    await withFake(CREDENTIAL, async (address, seen) => {
+      await Effect.runPromise(
+        mint(scoped, 'provision', { BAO_ADDR: address, BAO_TOKEN: TOKEN }).pipe(
+          Effect.provide(FetchHttpClient.layer),
+        ),
+      );
+      assert.equal(seen[0]?.path, '/v1/proxmox-c1/creds/provision');
+    });
+  });
+});
+
+describe('mintTier', () => {
+  it('is the bare role when the target carries no override', () => {
+    assert.equal(mintTier(C1, 'read'), 'read');
+    assert.equal(mintTier(C1, 'provision'), 'provision');
+  });
+
+  it('reads a PveTarget.roles override when one names the role', () => {
+    const scoped: PveTarget = { ...C1, roles: { provision: 'talos-provision' } };
+    assert.equal(mintTier(scoped, 'provision'), 'talos-provision');
+    assert.equal(mintTier(scoped, 'read'), 'read', 'unmentioned role: unchanged');
+  });
+
+  // ⛔ PbsTarget carries no `roles` field at all (credentials.ts's own ⛔) — this pins that a PBS
+  //   target can never override, structurally, not just "nobody has set one yet".
+  it('never overrides a PbsTarget: the field does not exist on that type', () => {
+    const pbs: PbsTarget = {
+      api: 'https://pbs.example:8007/api2/json',
+      mount: 'pbs-c1',
+      scheme: 'pbs',
+    };
+    assert.equal(mintTier(pbs, 'read'), 'read');
+    assert.equal(mintTier(pbs, 'provision'), 'provision');
+  });
+
+  // K-T1/M5 (second red-team pass): an override that resolves to a DIFFERENT OpenBao path than
+  // the one it names must throw, not silently mint a wider or nonexistent tier. Each of these
+  // reaches a different path than `<mount>/creds/<tier>` while containing no literal `/`.
+  const invalidTiers: Array<[tier: string, reason: string]> = [
+    ['', 'an empty override falls back to the bare role rather than minting <mount>/creds/'],
+    ['..', 'a parent-path segment escapes the creds/ prefix entirely'],
+    ['.', 'a same-directory segment is not a real tier name'],
+    ['?x=y', 'a querystring is appended instead of naming a tier'],
+    ['#frag', 'a fragment is appended instead of naming a tier'],
+    ['a/b', 'a literal slash inserts a second path segment'],
+  ];
+  for (const [bad, reason] of invalidTiers) {
+    it(`rejects ${JSON.stringify(bad)} as a tier name: ${reason}`, () => {
+      const scoped: PveTarget = { ...C1, roles: { provision: bad } };
+      assert.throws(() => mintTier(scoped, 'provision'), /not a valid OpenBao tier name/);
+    });
+  }
 });

package/src/proxmox/credentials.ts

@@ -86,9 +86,42 @@ export type PveTarget = {
    *   and a wrong guess fails closed with a 401 rather than doing something odd.
    */
   readonly scheme: 'pve';
+  /**
+   * Overrides which OpenBao mint TIER NAME (`<mount>/creds/<tier>`) a semantic role resolves to.
+   * Omitted or missing a role: unchanged, `role` is also the tier name, as every consumer before
+   * this field got. Present: `mintTier` below reads it first.
+   *
+   * ★ WHY A TARGET-LEVEL OVERRIDE, NOT A THIRD `PveRole`. A consumer whose OpenBao mount vends a
+   *   single least-privilege tier for BOTH read and write (one tier that can only ever reach the
+   *   scope that consumer needs, rather than the estate's general `read`/`provision` split) sets
+   *   `roles: { read: 'my-tier', provision: 'my-tier' }` and every read/diff/reconcile/delete this
+   *   package already issues resolves to that tier, with no new call site anywhere in the package.
+   *   Widening `PveRole` itself to a per-consumer string would instead touch every literal
+   *   `'read'`/`'provision'` call site across the package (`client.ts`, `lxc-read.ts`,
+   *   `lxc-task.ts`, `network-apply-read.ts`, `network-apply-run.ts`, `qemu-read.ts`,
+   *   `qemu-task.ts`, `storage-download-task.ts` — the eight this field's `mintTier` indirection
+   *   above already covers) for something only the TARGET, never the CALL, needs to know.
+   *
+   * ⛔ SET BOTH ROLES OR NEITHER (I2, red team on K-T1). An unmentioned role is NOT scoped down —
+   *   it still mints the estate-wide tier this file's own header describes (`hf-provision@pve`,
+   *   27 privileges including `Permissions.Modify`/`Sys.Modify` for `provision`). Setting only
+   *   `roles: { read: 'my-tier' }` leaves every reconcile/delete on this target minting that wide
+   *   credential while the plan output looks fully scoped down — nothing here warns. See
+   *   `docs/credentials.md`'s override paragraph for the same warning at the consumer-facing level.
+   */
+  readonly roles?: {
+    readonly read?: string;
+    readonly provision?: string;
+  };
 };
 
-/** The same client against a Proxmox Backup Server. See the ⛔ on `scheme` above. */
+/**
+ * The same client against a Proxmox Backup Server. See the ⛔ on `scheme` above.
+ * ⛔ NO `roles` FIELD. The estate has no PBS consumer with a scoped tier yet, and a PBS mount
+ *   vending only `read`/`provision` is the same shape `mint.ts` always assumed — `mintTier` below
+ *   never overrides a PBS target for exactly that reason. Add the field here, the same way, when
+ *   a PBS consumer needs it.
+ */
 export type PbsTarget = {
   readonly mount: string;
   readonly api: string;
@@ -98,6 +131,44 @@ export type PbsTarget = {
 /** Either product. What `pve()` and `pveOperations` accept; what a RESOURCE accepts is narrower. */
 export type ApiTarget = PbsTarget | PveTarget;
 
+/**
+ * The OpenBao mint tier a role resolves to for `target` — `target.roles`'s override (PVE only)
+ * or `role` itself, unchanged. THE single place `<mount>/creds/<tier>` gets its tier segment from
+ * a `PveRole`: `mint.ts`'s path and `lease-cache.ts`'s cache key both call this rather than either
+ * reading `role` or `target.roles` directly, so there is exactly one definition of "the tier" for
+ * both to agree on — `lease-cache.ts`'s own header says why the cache needed this too, not just
+ * the mint call.
+ *
+ * ⛔ AN OVERRIDE THAT IS NOT A PLAIN TIER NAME THROWS RATHER THAN BUILDING A PATH (M5, red team on
+ *   K-T1; widened after a second red-team pass found the first fix incomplete). `role` itself is
+ *   a compile-time literal and never needs this check; only `target.roles`, a plain string a
+ *   caller can set to anything, does. This is an ALLOWLIST, not a denylist of `/` alone — the
+ *   value is concatenated straight into `${mount}/creds/${tier}` and then into a URL (`mint.ts`),
+ *   so `''`, `'..'`, `'?x'` and `'#x'` are each their own way to land on a DIFFERENT OpenBao path
+ *   (a dropped segment, a parent path, a querystring, a fragment) without containing `/` at all.
+ *   Every one of those produces a 404 `mint.ts`'s own `refuse` reports as a mint failure, and
+ *   every `pveOperations` family folds a mint failure into "absent" (`unreadable-read.ts`'s ⛔),
+ *   so the plan would say CREATE for an object that is plainly there instead of naming the bad
+ *   config — the exact hazard the first version of this check believed it had closed. `role` is
+ *   source-controlled and this fires at the first `mintTier` call, before any network request, so
+ *   the fix cannot itself widen what an operator's config can reach.
+ */
+const VALID_TIER = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export const mintTier = (target: ApiTarget, role: PveRole): string => {
+  if (target.scheme !== 'pve') return role;
+  const tier = target.roles?.[role];
+  if (tier === undefined) return role;
+  if (!VALID_TIER.test(tier)) {
+    throw new Error(
+      `PveTarget.roles.${role} = ${JSON.stringify(tier)} is not a valid OpenBao tier name -- ` +
+        'it would be interpolated straight into "<mount>/creds/<tier>" and must be a plain name ' +
+        '(letters, digits, ".", "_", "-", not starting with one of those and not "..").',
+    );
+  }
+  return tier;
+};
+
 /**
  * What a mint returns.
  *

package/src/proxmox/group.ts

@@ -85,6 +85,7 @@ import {
 } from './group-wire.ts';
 import type { PveRequirements, WithTarget } from './resource-spec.ts';
 import { runPve } from './distilled-pve.ts';
+import { mintTier } from './credentials.ts';
 import { UNREADABLE, unreadableWarning } from './unreadable-read.ts';
 
 export interface GroupProps extends WithTarget {
@@ -162,7 +163,12 @@ export const ProxmoxGroupProvider = () =>
           // ⛔ THE CRIES-WOLF FIX: a refused read used to fall into `undefined` below and force
           //   `update` on a group that was plainly there — see unreadable-read.ts.
           if (live === UNREADABLE) {
-            yield* unreadableWarning('Proxmox.Group', news.groupid);
+            yield* unreadableWarning(
+              'Proxmox.Group',
+              news.groupid,
+              news.target.mount,
+              mintTier(news.target, 'read'),
+            );
             return { action: 'noop' } as const;
           }
           if (live === undefined) {

package/src/proxmox/lease-cache-mint.test.ts

@@ -0,0 +1,70 @@
+/**
+ * ⚠️ EXERCISES `mintForKey` ITSELF, NOT A HAND-REPRODUCTION OF ITS CHOICES (second red-team pass
+ *   on K-T1). `lease-cache.test.ts`'s `targetForKey` tests call `mintTier(targetForKey(key),
+ *   'read')` — passing `'read'` as a LITERAL that happens to match `mintForKey`'s own hardcoded
+ *   pve role, so those tests would keep passing even if `mintForKey` minted with a different role
+ *   than it reconstructs the target for. A fake OpenBao server pins the ACTUAL request path
+ *   `mintForKey` sends.
+ *
+ * Split out of lease-cache.test.ts (2026-09-27) to keep that file under the 250-line cap once this
+ * describe block needed its own fake-server helper and imports — same reasoning as
+ * tests/apply-main-ruleset-update.test.ts.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import * as Effect from 'effect/Effect';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { type BaoEnvironment } from './credentials.ts';
+import { type LeaseKey, mintForKey } from './lease-cache.ts';
+
+/** ⚠️ Same minimal Bun typing as credentials.test.ts — this package's tsconfig has no Bun types. */
+type ServeOptions = { fetch(request: Request): Promise<Response>; hostname: string; port: number };
+const { Bun } = globalThis as unknown as {
+  Bun: { serve(options: ServeOptions): { url: URL; stop(closeActive: boolean): void } };
+};
+
+describe("K-T1/M3: mintForKey requests the key's own tier, not a re-derived role", () => {
+  const withFakeBao = async (body: (address: string, seen: string[]) => Promise<void>) => {
+    const seen: string[] = [];
+    const server = Bun.serve({
+      fetch: async (request: Request) => {
+        seen.push(new URL(request.url).pathname);
+        return Response.json({ data: { secret: 'x', token_id: 'hf-read@pve!hf-read-1' } });
+      },
+      hostname: '127.0.0.1',
+      port: 0,
+    });
+    try {
+      await body(server.url.origin, seen);
+    } finally {
+      server.stop(true);
+    }
+  };
+  const env = (address: string): BaoEnvironment => ({ BAO_ADDR: address, BAO_TOKEN: 't' });
+  const run = (key: LeaseKey, address: string) =>
+    Effect.runPromise(mintForKey(key, env(address)).pipe(Effect.provide(FetchHttpClient.layer)));
+
+  it('a plain pve key mints /creds/<tier> with the bare role tier', async () => {
+    await withFakeBao(async (address, seen) => {
+      const key: LeaseKey = { mount: 'proxmox-tb4', scheme: 'pve', tier: 'read' };
+      await run(key, address);
+      assert.equal(seen[0], '/v1/proxmox-tb4/creds/read');
+    });
+  });
+
+  it('an overridden pve key mints the OVERRIDDEN tier, not a bare role', async () => {
+    await withFakeBao(async (address, seen) => {
+      const key: LeaseKey = { mount: 'proxmox-tb4', scheme: 'pve', tier: 'talos-provision' };
+      await run(key, address);
+      assert.equal(seen[0], '/v1/proxmox-tb4/creds/talos-provision');
+    });
+  });
+
+  it('a pbs key mints its own tier directly', async () => {
+    await withFakeBao(async (address, seen) => {
+      const key: LeaseKey = { mount: 'pbs-c1', scheme: 'pbs', tier: 'provision' };
+      await run(key, address);
+      assert.equal(seen[0], '/v1/pbs-c1/creds/provision');
+    });
+  });
+});