@homeflare/alchemy 0.40.0 → 0.42.0

package/src/opnsense/group.test.ts

@@ -12,6 +12,7 @@ import { spec } from './group.ts';
 import { fakeFailure, fakeOpnsense, fakeOpnsenseLayer, getOnlyOrFail } from './fake-opnsense.ts';
 import type { OpnsenseWriteRefused } from './policy.ts';
 import { opnsenseOperations } from './resource.ts';
+import { optionMap } from './wire.ts';
 
 const asRefusal = (value: unknown) => value as OpnsenseWriteRefused;
 
@@ -24,14 +25,18 @@ const PROPS: GroupProps = {
   uuid: UUID,
 };
 
-const liveItem = (overrides: Partial<group.GroupItem> = {}): group.GroupItem => ({
+// `liveItem` builds a `ModelIfgroupentryReadItem` — the WHOLE-MODEL `get()`'s read-shaped item,
+// whose `members` decodes as an option map, not a comma string (OPNSENSE-2 — see group-form.ts).
+const liveItem = (
+  overrides: Partial<group.ModelIfgroupentryReadItem> = {},
+): group.ModelIfgroupentryReadItem => ({
   ifname: 'IOT_DEVICES',
-  members: 'opt1,opt2',
+  members: optionMap('opt1', 'opt2'),
   sequence: '1',
   ...overrides,
 });
 
-const getResponse = (items: Record<string, group.GroupItem>) =>
+const getResponse = (items: Record<string, group.ModelIfgroupentryReadItem>) =>
   Response.json({ group: { ifgroupentry: items } });
 
 describe('Opnsense.Firewall.Group spec.fetchLive', () => {
@@ -86,17 +91,21 @@ describe('opnsenseOperations(spec).read — S7/S8, marker-less API', () => {
 
 describe('opnsenseOperations(spec).diff', () => {
   test('noop when the declared member set matches live, regardless of order', async () => {
-    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem({ members: 'opt2,opt1' }) }));
+    const fake = getOnlyOrFail(() =>
+      getResponse({ [UUID]: liveItem({ members: optionMap('opt2', 'opt1') }) }),
+    );
     const result = await Effect.runPromise(
       opnsenseOperations(spec)
-        .diff(PROPS, attributesOf(UUID, liveItem({ members: 'opt2,opt1' })))
+        .diff(PROPS, attributesOf(UUID, liveItem({ members: optionMap('opt2', 'opt1') })))
         .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
     );
     expect(result).toEqual({ action: 'noop' });
   });
 
   test('update when a member was removed live', async () => {
-    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem({ members: 'opt1' }) }));
+    const fake = getOnlyOrFail(() =>
+      getResponse({ [UUID]: liveItem({ members: optionMap('opt1') }) }),
+    );
     const result = await Effect.runPromise(
       opnsenseOperations(spec)
         .diff(PROPS, attributesOf(UUID, liveItem()))
@@ -108,7 +117,9 @@ describe('opnsenseOperations(spec).diff', () => {
 
 describe('opnsenseOperations(spec).reconcile and destroy — the read-only policy', () => {
   test('reconcile observes with one GET, then refuses — never a write', async () => {
-    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem({ members: 'opt1' }) }));
+    const fake = getOnlyOrFail(() =>
+      getResponse({ [UUID]: liveItem({ members: optionMap('opt1') }) }),
+    );
     const failure = asRefusal(
       await Effect.runPromise(
         Effect.flip(

package/src/opnsense/group.ts

@@ -2,8 +2,10 @@
  * `Opnsense.Firewall.Group` — a read-only declaration of one `firewall/group` item (an
  * "Interface Group", not a permission group) on the edge. READ-ONLY BY DESIGN — see policy.ts's
  * header. `reconcile`/`delete` always refuse. Mirrors alias.ts exactly; see that file's header
- * for why `get()` (whole model) is the read source rather than `getGroup` — the same generation
- * gap (no `uuid` in `GetGroupRequest`'s schema) applies here too.
+ * for why `get()` (whole model) is the read source uniformly across this family rather than the
+ * now-correct `getGroup` per-item operation (OPNSENSE-1 fixed `GetGroupRequest`'s missing `uuid`,
+ * but switching to it is a separate, later PR). `members` decodes as an option map, not a comma
+ * string — see `group-form.ts`'s `attributesOf` (OPNSENSE-2).
  */
 import { adopt } from 'alchemy/AdoptPolicy';
 import { Resource } from 'alchemy';
@@ -54,7 +56,12 @@ export const isOpnsenseFirewallGroup = (value: unknown): value is OpnsenseFirewa
   value !== null &&
   (value as { Type?: unknown }).Type === 'Opnsense.Firewall.Group';
 
-export const spec: OpnsenseSpec<GroupProps, Group.GroupItem, GroupAttributes, OpnsenseOpError> = {
+export const spec: OpnsenseSpec<
+  GroupProps,
+  Group.ModelIfgroupentryReadItem,
+  GroupAttributes,
+  OpnsenseOpError
+> = {
   attributes: attributesOf,
   fetchLive: (props) =>
     Group.get({}).pipe(Effect.map((res) => res.group?.ifgroupentry?.[props.uuid])),

package/src/opnsense/wire.ts

@@ -2,20 +2,27 @@
  * How OPNsense's MVC model spells a value on the wire, and how to get it back to something
  * comparable — the `../proxmox/values.ts` idea, scoped to this vendor's own spellings.
  *
- * ★ OPNSENSE HAS EXACTLY TWO WIRE SHAPES THIS FAMILY NEEDS. Every `BooleanField` is the string
- *   `"1"` or `"0"` (never a JSON boolean — `AliasItem.enabled: string`, `GroupItem.nogroup?:
- *   string`, see `firewall_alias.ts`/`firewall_group.ts`). Every multi-select `OptionField`/
- *   `ModelRelationField` is a SINGLE comma-joined string, not a JSON array (`AliasItem.categories`,
- *   `GroupItem.members` — both carry the doc comment "wire value is a single comma-joined string,
- *   not a JSON array" in the generated SDK). Nothing here is specific to one resource.
+ * ★ OPNSENSE HAS EXACTLY TWO WIRE SHAPES THIS FAMILY NEEDS ON WRITE (props stay plain values;
+ *   this family never writes, but `matches` compares against them). Every `BooleanField` is the
+ *   string `"1"` or `"0"` (never a JSON boolean). Every multi-select `OptionField`/
+ *   `ModelRelationField`'s WRITE-side spelling is a SINGLE comma-joined string, not a JSON array.
+ *
+ * ⚠️ READ IS A THIRD SHAPE (OPNSENSE-2, distilled `homeflare/opnsense`'s `read-shape.ts`): the
+ *   SAME list-shaped fields decode on GET as an option map `{key: {value, selected}}`, not a
+ *   string — `AliasItem`/`GroupItem` (this family's OLD, pre-fix type references) were the
+ *   WRITE-shaped structs; `fetchLive` actually decodes `ModelAliasReadItem`/
+ *   `ModelIfgroupentryReadItem` (the WHOLE-MODEL GET's read-shaped item), whose `type`/
+ *   `interface`/`proto`/`categories`/`members` are option maps. `selectedOf`/`selectedOneOf`
+ *   below extract the selected key(s) back to the SAME plain-string/string[] shape `matches`
+ *   already compares, so the rest of this family's logic (and `AliasAttributes`/
+ *   `GroupAttributes`'s own field types) is unchanged.
  *
  * ⚠️ COMMA-LIST ORDER ROUND-TRIP IS NOT ASSUMED STABLE. OPNsense builds these from a PHP
- *   associative array (`ModelRelationField`/`OptionField::getNodeData()`), and nothing in the
- *   model XML promises the join order survives a save-then-read unchanged. Sorting and
- *   deduplicating both sides before comparing is what makes `matches` (alias-form.ts,
- *   group-form.ts) actually settle instead of reporting drift on a re-ordered list that changed
- *   nothing — the same reasoning `../proxmox/user-wire.ts`'s `groupSet` documents for PVE's
- *   `groups` field.
+ *   associative array, and nothing in the model XML promises the join order survives a
+ *   save-then-read unchanged. Sorting and deduplicating both sides before comparing is what makes
+ *   `matches` (alias-form.ts, group-form.ts) actually settle instead of reporting drift on a
+ *   re-ordered list that changed nothing — the same reasoning `../proxmox/user-wire.ts`'s
+ *   `groupSet` documents for PVE's `groups` field.
  */
 
 /** OPNsense's own boolean spelling. Absent takes the caller's stated default — OPNsense's own
@@ -54,3 +61,41 @@ export const numField = (value: string | undefined, fallback: number): number =>
   const parsed = Number(value);
   return Number.isFinite(parsed) ? parsed : fallback;
 };
+
+/** One entry of a GET-decoded option map — `{value: <label>, selected: 0|1}`, see this file's
+ * module doc. Structural, not imported from the SDK: every generated `*Map` field shares this
+ * exact shape (`OptionEntry` in each service module), and staying structural here avoids a
+ * per-resource-file type import just for this. */
+export interface OpnsenseOptionEntry {
+  readonly value: string;
+  readonly selected: number;
+}
+
+/**
+ * The selected key(s) of a GET-decoded option map, normalised the same way `csvSet` normalises
+ * the write-side comma string — sorted, deduplicated, empty-key filtered. Use for a
+ * `Multiple="Y"` field (`AliasItem.proto`, `AliasItem.categories`, `GroupItem.members`); for a
+ * single-select field use `selectedOneOf`.
+ */
+export const selectedOf = (
+  map: Readonly<Record<string, OpnsenseOptionEntry | undefined>> | undefined,
+): readonly string[] => {
+  if (map === undefined) return [];
+  const keys = Object.entries(map)
+    .filter(([key, entry]) => key !== '' && entry?.selected === 1)
+    .map(([key]) => key);
+  return [...new Set(keys)].sort();
+};
+
+/** Single-select convenience over `selectedOf` — the one selected key, or `''` if none (the same
+ * "absent" spelling a plain string field uses, e.g. `AliasItem.type`/`GroupItem`'s own
+ * `.\InterfaceField` members when not `Multiple="Y"`). */
+export const selectedOneOf = (
+  map: Readonly<Record<string, OpnsenseOptionEntry | undefined>> | undefined,
+): string => selectedOf(map)[0] ?? '';
+
+/** The encode direction, for test fixtures: every listed key marked `selected: 1`, mirroring a
+ * real OPNsense GET response (`{[key]: {value, selected: 1}}`) — so a fixture exercises the exact
+ * decode path `selectedOf`/`selectedOneOf` handle, not the pre-fix plain-string shape. */
+export const optionMap = (...keys: readonly string[]): Record<string, OpnsenseOptionEntry> =>
+  Object.fromEntries(keys.map((key) => [key, { value: key, selected: 1 }]));

package/src/proxmox/acl.ts

@@ -50,6 +50,7 @@ import * as Effect from 'effect/Effect';
 import { attributesOf, bind, guardWrite, identity, matches, tuple } from './acl-wire.ts';
 import type { PveRequirements, WithTarget } from './resource-spec.ts';
 import { runPve } from './distilled-pve.ts';
+import { mintTier } from './credentials.ts';
 import {
   UNREADABLE,
   type Unreadable,
@@ -148,7 +149,12 @@ export const ProxmoxAclProvider = () =>
           // ⛔ THE CRIES-WOLF FIX: a refused read used to fall into `undefined` below and
           //   force `update` on a grant that was plainly there — see unreadable-read.ts.
           if (live === UNREADABLE) {
-            yield* unreadableWarning('Proxmox.Acl', identity(news));
+            yield* unreadableWarning(
+              'Proxmox.Acl',
+              identity(news),
+              news.target.mount,
+              mintTier(news.target, 'provision'),
+            );
             return { action: 'noop' } as const;
           }
           return live !== undefined && matches(live, news)

package/src/proxmox/api-token.ts

@@ -52,6 +52,7 @@ import * as Provider from 'alchemy/Provider';
 import * as access from '@distilled.cloud/proxmox/access';
 import * as Effect from 'effect/Effect';
 import { API_TOKEN_UPDATE, attributesOf, matches, shape } from './api-token-form.ts';
+import { mintTier } from './credentials.ts';
 import { guardWrite } from './distilled-guard.ts';
 import type { PveRequirements, WithTarget } from './resource-spec.ts';
 import { runPve } from './distilled-pve.ts';
@@ -190,7 +191,12 @@ export const ProxmoxApiTokenProvider = () =>
           // ⛔ THE CRIES-WOLF FIX: a refused read used to fall into `undefined` below and force
           //   `update` on a token that was plainly there — see unreadable-read.ts.
           if (live === UNREADABLE) {
-            yield* unreadableWarning('Proxmox.ApiToken', `${news.userid}!${news.tokenid}`);
+            yield* unreadableWarning(
+              'Proxmox.ApiToken',
+              `${news.userid}!${news.tokenid}`,
+              news.target.mount,
+              mintTier(news.target, 'provision'),
+            );
             return { action: 'noop' } as const;
           }
           // ⚠️ NO GUARDED-CREATE BRANCH HERE, UNLIKE EVERY OTHER FAMILY IN THIS SUB-AREA. There

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