@cosmicdrift/kumiko-bundled-features 0.256.0 → 0.258.0

package/src/notes-history/__tests__/notes-history-ownership.integration.test.ts

@@ -35,7 +35,7 @@ import {
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { NotesHistoryHandlers, NotesHistoryQueries } from "../constants";
-import { createNoteEntryEntity, noteEntryEntity } from "../entity";
+import { createNoteEntryEntity, noteEntryEntity, noteMentionEntity } from "../entity";
 import { createNotesHistoryFeature } from "../feature";
 
 // Minimal fixture standing in for a real host projection: which team a host
@@ -123,6 +123,7 @@ beforeAll(async () => {
     features: [createNotesHistoryFeature({ ownership: teamOwnership }), projectFixtureFeature],
   });
   await unsafeCreateEntityTable(scopedStack.db, createNoteEntryEntity(teamOwnership));
+  await unsafeCreateEntityTable(scopedStack.db, noteMentionEntity);
   await unsafeCreateEntityTable(scopedStack.db, projectEntity);
   await createEventsTable(scopedStack.db);
   await asRawClient(scopedStack.db).unsafe(
@@ -138,6 +139,7 @@ beforeAll(async () => {
     features: [createNotesHistoryFeature(), projectFixtureFeature],
   });
   await unsafeCreateEntityTable(defaultStack.db, noteEntryEntity);
+  await unsafeCreateEntityTable(defaultStack.db, noteMentionEntity);
   await unsafeCreateEntityTable(defaultStack.db, projectEntity);
   await createEventsTable(defaultStack.db);
   await insertProjects(defaultStack, userA.tenantId, [PROJ_1]);
@@ -286,6 +288,7 @@ describe("unqualified where-rule fails closed, not open (fw#2639)", () => {
       ],
     });
     await unsafeCreateEntityTable(unqualifiedStack.db, createNoteEntryEntity(unqualifiedOwnership));
+    await unsafeCreateEntityTable(unqualifiedStack.db, noteMentionEntity);
     await unsafeCreateEntityTable(unqualifiedStack.db, projectEntity);
     await createEventsTable(unqualifiedStack.db);
     await asRawClient(unqualifiedStack.db).unsafe(

package/src/notes-history/__tests__/notes-history-parent-visibility.integration.test.ts

@@ -25,7 +25,7 @@ import {
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { NotesHistoryHandlers } from "../constants";
-import { createNoteEntryEntity } from "../entity";
+import { createNoteEntryEntity, noteMentionEntity } from "../entity";
 import { createNotesHistoryFeature } from "../feature";
 
 const PROJECT_TABLE = "notes_pv_test_projects";
@@ -118,6 +118,7 @@ beforeAll(async () => {
   });
   await unsafeCreateEntityTable(guardedStack.db, guardedProjectEntity);
   await unsafeCreateEntityTable(guardedStack.db, createNoteEntryEntity());
+  await unsafeCreateEntityTable(guardedStack.db, noteMentionEntity);
   await createEventsTable(guardedStack.db);
   await asRawClient(guardedStack.db).unsafe(
     `INSERT INTO ${PROJECT_TABLE} (id, tenant_id, team_id, name) VALUES
@@ -134,6 +135,7 @@ beforeAll(async () => {
   });
   await unsafeCreateEntityTable(openStack.db, guardedProjectEntity);
   await unsafeCreateEntityTable(openStack.db, createNoteEntryEntity());
+  await unsafeCreateEntityTable(openStack.db, noteMentionEntity);
   await createEventsTable(openStack.db);
   await asRawClient(openStack.db).unsafe(
     `INSERT INTO ${PROJECT_TABLE} (id, tenant_id, team_id, name) VALUES ($1, $2, 'team-a', 'Project Open')`,

package/src/notes-history/__tests__/notes-history.integration.test.ts

@@ -28,7 +28,7 @@ import {
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { NotesHistoryHandlers, NotesHistoryQueries } from "../constants";
-import { noteEntryEntity } from "../entity";
+import { noteEntryEntity, noteMentionEntity } from "../entity";
 import { createNotesHistoryFeature } from "../feature";
 
 const notesHistoryFeature = createNotesHistoryFeature();
@@ -73,6 +73,7 @@ const CONTACT_SHARED = "30000000-0000-4000-8000-000000000007";
 beforeAll(async () => {
   stack = await setupTestStack({ features: [notesHistoryFeature, contactFixtureFeature] });
   await unsafeCreateEntityTable(stack.db, noteEntryEntity);
+  await unsafeCreateEntityTable(stack.db, noteMentionEntity);
   await unsafeCreateEntityTable(stack.db, contactEntity);
   await createEventsTable(stack.db);
 

package/src/notes-history/__tests__/notes-read-gate.integration.test.ts

@@ -0,0 +1,243 @@
+// The read twin of notes-history-parent-visibility.integration.test.ts
+// (fw#2766). add-note was gated against the host row's own read path, but
+// `note-entry:list` returned every note of the tenant. None of the mounts
+// below set `ownership`, which used to be the only lever.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  createEntity,
+  createTextField,
+  defineFeature,
+  type EntityDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { userEntity } from "../../user";
+import { NotesHistoryHandlers, NotesHistoryQueries } from "../constants";
+import { createNoteEntryEntity, noteMentionEntity } from "../entity";
+import { createNotesHistoryFeature } from "../feature";
+
+const PROJECT_TABLE = "notes_rg_test_projects";
+
+const teamScopedRead: NonNullable<EntityDefinition["access"]> = {
+  read: {
+    TenantMember: {
+      kind: "where",
+      where: (user, ctx) => ({
+        sqlText: `${ctx.tableName}.team_id = $${ctx.paramStart}`,
+        params: [user.claims?.["team"] ?? null],
+      }),
+    },
+  },
+};
+
+const projectEntity = createEntity({
+  table: PROJECT_TABLE,
+  fields: {
+    teamId: createTextField({
+      required: true,
+      maxLength: 64,
+      personal: false,
+      reason: "technical_reference",
+    }),
+  },
+  access: teamScopedRead,
+});
+
+const hostFixturesFeature = defineFeature("notes-rg-test-fixtures", (r) => {
+  r.entity("project", projectEntity);
+});
+
+type TestUser = ReturnType<typeof createTestUser>;
+
+const userA: TestUser = createTestUser({
+  id: 80,
+  roles: ["TenantMember"],
+  claims: { team: "team-a" },
+});
+const userB: TestUser = createTestUser({
+  id: 81,
+  roles: ["TenantMember"],
+  claims: { team: "team-b" },
+});
+
+const PROJECT_A = "d0000000-0000-4000-8000-00000000000a";
+const PROJECT_B = "d0000000-0000-4000-8000-00000000000b";
+const ORPHAN_HOST_ID = "d0000000-0000-4000-8000-0000000000ff";
+
+type NoteRow = { id: string; entityType: string; entityId: string; body: string };
+type Page = { rows: readonly NoteRow[]; nextCursor: string | null; total?: number };
+
+const noteEntryEntity = createNoteEntryEntity();
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    // Deliberately no `ownership` — the gate must hold on a bare mount.
+    features: [createNotesHistoryFeature({ access: { openToAll: true } }), hostFixturesFeature],
+  });
+  await unsafeCreateEntityTable(stack.db, noteEntryEntity);
+  await unsafeCreateEntityTable(stack.db, noteMentionEntity);
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, projectEntity);
+  await createEventsTable(stack.db);
+
+  await asRawClient(stack.db).unsafe(
+    `INSERT INTO ${PROJECT_TABLE} (id, tenant_id, team_id) VALUES ($1, $3, 'team-a'), ($2, $3, 'team-b')`,
+    [PROJECT_A, PROJECT_B, userA.tenantId],
+  );
+
+  await stack.http.writeOk(
+    NotesHistoryHandlers.addNote,
+    { entityType: "project", entityId: PROJECT_A, body: "team-a note" },
+    userA,
+  );
+  await stack.http.writeOk(
+    NotesHistoryHandlers.addNote,
+    { entityType: "project", entityId: PROJECT_B, body: "team-b note" },
+    userB,
+  );
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+function listNotes(payload: Record<string, unknown>, user: TestUser): Promise<Page> {
+  return stack.http.queryOk<Page>(NotesHistoryQueries.noteList, payload, user);
+}
+
+describe("notes-history read-gate", () => {
+  test("the owning team reads the note trail of its own project", async () => {
+    const page = await listNotes(
+      { filter: { field: "entityId", op: "eq", value: PROJECT_A } },
+      userA,
+    );
+    expect(page.rows).toHaveLength(1);
+    expect(page.rows[0]?.body).toBe("team-a note");
+  });
+
+  test("a foreign team reads nothing there, without ownership being set", async () => {
+    const page = await listNotes(
+      { filter: { field: "entityId", op: "eq", value: PROJECT_A }, totalCount: true },
+      userB,
+    );
+    expect(page.rows).toHaveLength(0);
+    expect(page.total).toBe(0);
+  });
+
+  test("an unfiltered list returns only the notes whose host the caller can see", async () => {
+    const forA = await listNotes({ totalCount: true }, userA);
+    expect(forA.rows.map((r) => r.entityId)).toEqual([PROJECT_A]);
+    expect(forA.total).toBe(1);
+
+    const forB = await listNotes({ totalCount: true }, userB);
+    expect(forB.rows.map((r) => r.entityId)).toEqual([PROJECT_B]);
+    expect(forB.total).toBe(1);
+  });
+
+  test("a note whose entityType names no registered entity is invisible to everyone", async () => {
+    const orphanId = "d0000000-0000-4000-8000-0000000000f1";
+    await asRawClient(stack.db).unsafe(
+      `INSERT INTO read_note_entries (id, tenant_id, entity_type, entity_id, body)
+       VALUES ($1, $2, 'not-a-registered-entity', $3, 'orphan')`,
+      [orphanId, userA.tenantId, ORPHAN_HOST_ID],
+    );
+
+    for (const user of [userA, userB]) {
+      const page = await listNotes(
+        { filter: { field: "entityId", op: "eq", value: ORPHAN_HOST_ID }, totalCount: true },
+        user,
+      );
+      expect(page.rows).toHaveLength(0);
+      expect(page.total).toBe(0);
+    }
+
+    const raw = await asRawClient(stack.db).unsafe<{ n: number }>(
+      "SELECT count(*)::int AS n FROM read_note_entries WHERE id = $1",
+      [orphanId],
+    );
+    expect(raw[0]?.n).toBe(1);
+  });
+});
+
+describe("notes-history read-gate — parents allowlist narrows both paths", () => {
+  const OTHER_TABLE = "notes_rg_other_hosts";
+  const otherEntity = createEntity({
+    table: OTHER_TABLE,
+    fields: {
+      label: createTextField({
+        required: true,
+        maxLength: 64,
+        personal: false,
+        reason: "technical_reference",
+      }),
+    },
+  });
+  const fixtures = defineFeature("notes-rg-parents-fixtures", (r) => {
+    r.entity("project", projectEntity);
+    r.entity("widget", otherEntity);
+  });
+  const WIDGET = "d0000000-0000-4000-8000-00000000002a";
+
+  let allowStack: TestStack;
+
+  beforeAll(async () => {
+    allowStack = await setupTestStack({
+      features: [
+        createNotesHistoryFeature({ access: { openToAll: true }, parents: ["project"] }),
+        fixtures,
+      ],
+    });
+    await unsafeCreateEntityTable(allowStack.db, createNoteEntryEntity(undefined, ["project"]));
+    await unsafeCreateEntityTable(allowStack.db, noteMentionEntity);
+    await unsafeCreateEntityTable(allowStack.db, userEntity);
+    await unsafeCreateEntityTable(allowStack.db, projectEntity);
+    await unsafeCreateEntityTable(allowStack.db, otherEntity);
+    await createEventsTable(allowStack.db);
+    await asRawClient(allowStack.db).unsafe(
+      `INSERT INTO ${PROJECT_TABLE} (id, tenant_id, team_id) VALUES ($1, $2, 'team-a')`,
+      [PROJECT_A, userA.tenantId],
+    );
+    await asRawClient(allowStack.db).unsafe(
+      `INSERT INTO ${OTHER_TABLE} (id, tenant_id, label) VALUES ($1, $2, 'w')`,
+      [WIDGET, userA.tenantId],
+    );
+  });
+
+  afterAll(async () => {
+    await allowStack.cleanup();
+  });
+
+  test("a host type outside the allowlist is rejected on write", async () => {
+    const err = await allowStack.http.writeErr(
+      NotesHistoryHandlers.addNote,
+      { entityType: "widget", entityId: WIDGET, body: "nope" },
+      userA,
+    );
+    expect(err.code).toBe("not_found");
+  });
+
+  test("a row that slipped in on a non-allowlisted host stays invisible on read", async () => {
+    const smuggled = "d0000000-0000-4000-8000-0000000000f2";
+    await asRawClient(allowStack.db).unsafe(
+      `INSERT INTO read_note_entries (id, tenant_id, entity_type, entity_id, body)
+       VALUES ($1, $2, 'widget', $3, 'smuggled')`,
+      [smuggled, userA.tenantId, WIDGET],
+    );
+    const page = await allowStack.http.queryOk<Page>(
+      NotesHistoryQueries.noteList,
+      { filter: { field: "entityId", op: "eq", value: WIDGET }, totalCount: true },
+      userA,
+    );
+    expect(page.rows).toHaveLength(0);
+    expect(page.total).toBe(0);
+  });
+});

package/src/notes-history/entity.ts

@@ -37,12 +37,22 @@ import {
 // party without a structured @-mention is not tracked — regex/NLP over
 // free text is unreliable. The operator's manual `forget-subject` path
 // covers what this structured trigger misses.
-export function createNoteEntryEntity(access?: EntityDefinition["access"]) {
+export function createNoteEntryEntity(
+  access?: EntityDefinition["access"],
+  parents?: readonly string[],
+) {
   return createEntity({
     table: "read_note_entries",
     description:
       "One note attached to a host entity by entityType and entityId, holding the note body plus the id and the display name of the author as it stood when the note was written. Rows are append-only: a correction is a further note, never an edit of this one.",
     access,
+    // Declared unconditionally: the host-visibility gate is the default for
+    // both paths, and `parents` only narrows which hosts are admissible.
+    parentRef: {
+      entityTypeField: "entityType",
+      entityIdField: "entityId",
+      ...(parents !== undefined && { allowedTypes: parents }),
+    },
     fields: {
       entityType: createTextField({
         required: true,

package/src/notes-history/feature.ts

@@ -30,7 +30,7 @@ function registerNotesHistory(
   r: FeatureRegistrar<typeof NOTES_HISTORY_FEATURE_NAME>,
   access: AccessRule,
   ownership: EntityDefinition["access"] | undefined,
-  parents: ReadonlySet<string> | undefined,
+  parents: readonly string[] | undefined,
 ): void {
   r.describe(
     "Generic, host-agnostic, append-only note history for any entity. Owns one event-sourced entity, `note-entry` (`read_note_entries`), keyed by (entityType, entityId) — so attaching notes adds NO column to the host entity and needs no relational pivot or JOIN. Provides a `create` write-handler (author stamped server-side from the caller, never client-supplied) and a `list` query filterable on entityId. Deliberately append-only: no update or delete handler is registered — a correction is a new entry, not an edit, so who-said-what-when stays reconstructable. Every path uses one access rule — adopt the host's model with createNotesHistoryFeature({ access: { openToAll: true } }) or pin roles with createNotesHistoryFeature({ roles }).",
@@ -41,7 +41,7 @@ function registerNotesHistory(
     recommended: false,
   });
 
-  const entity = createNoteEntryEntity(ownership);
+  const entity = createNoteEntryEntity(ownership, parents);
   r.entity("note-entry", entity);
   // No write/query handler of its own — populated only as a side effect of
   // add-note (see handlers/add-note.write.ts), looked up by
@@ -50,7 +50,7 @@ function registerNotesHistory(
   // registry-wide GDPR boot guards and to executor.ts's table/projection setup.
   r.entity("note-mention", noteMentionEntity);
 
-  r.writeHandler(createAddNoteHandler(access, parents));
+  r.writeHandler(createAddNoteHandler(access));
   r.queryHandler(
     defineEntityListHandler("note-entry", entity, {
       access,
@@ -76,10 +76,11 @@ export type NotesHistoryFeatureOptions = {
   readonly roles?: readonly string[];
   /** Row-level ownership on the note-entry rows themselves — orthogonal to
    *  `access`, which only gates whether a caller may dispatch create/list at
-   *  all. Set `ownership.read` to close the read leak: without it — even if
-   *  `ownership.write` is set — `access.read` stays undefined and any
-   *  dispatch-eligible user can read every note in the tenant, including
-   *  notes on entities they can't otherwise see.
+   *  all. `ownership.read` is no longer what keeps a caller from reading notes
+   *  on host entities they can't see: that gate is default-on since fw#2766
+   *  and derives from the entity's `parentRef`. Use `ownership.read` for an
+   *  ADDITIONAL row rule on the note row itself (e.g. author-only visibility);
+   *  it is AND-ed with the host-visibility gate, never a replacement for it.
    *
    *  `ownership.write` is separate and does NOT affect list/read. It's
    *  consulted by the framework's generic delete/forget/restore paths (not
@@ -92,13 +93,14 @@ export type NotesHistoryFeatureOptions = {
   readonly ownership?: EntityDefinition["access"];
   /** Allowlist further narrowing which registered entities may be used as a
    *  note's parent (entityType). This is NOT what turns parent-checking on —
-   *  add-note always verifies that entityType names a registered entity and
+   *  both paths always verify that entityType names a registered entity and
    *  that the row is visible to the caller through that entity's own read
    *  path (tenant scope plus its `access.read` ownership); an entityType
    *  that names no registered entity is rejected regardless of this option.
    *  Setting `parents` narrows further, to a specific set of entity names —
    *  useful when a host entity is registered but should never be a valid
-   *  note parent. */
+   *  note parent. It also shrinks the read gate's SQL, which otherwise has to
+   *  consider every registered entity as a candidate host. */
   readonly parents?: readonly string[];
 };
 
@@ -142,8 +144,7 @@ export function createNotesHistoryFeature(
         "today's unrestricted behavior instead.",
     );
   }
-  const parents = opts.parents === undefined ? undefined : new Set(opts.parents);
   return defineFeature(NOTES_HISTORY_FEATURE_NAME, (r) =>
-    registerNotesHistory(r, resolveAccess(opts), opts.ownership, parents),
+    registerNotesHistory(r, resolveAccess(opts), opts.ownership, opts.parents),
   );
 }

package/src/notes-history/handlers/add-note.write.ts

@@ -1,7 +1,7 @@
 import { fetchOne, runInSavepointIfSupported } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
-import { decryptStoredPii, parentRowIsVisible } from "../../shared";
+import { decryptStoredPii, joinRowParentIsVisible } from "../../shared";
 import { userTable } from "../../user";
 import { DEFAULT_NOTES_HISTORY_ACCESS } from "../constants";
 import { noteEntryExecutor, noteMentionExecutor } from "../executor";
@@ -15,13 +15,12 @@ import { type AddNotePayload, addNotePayloadSchema } from "../schemas";
 //
 // entityType/entityId are never trusted client input: entityType must name a
 // registered entity, and the row must be visible to the caller through that
-// entity's own read path (tenant scope plus its `access.read` ownership) —
-// see shared/parent-visibility.ts. `parents`, when set, is an ADDITIONAL allowlist
-// narrowing which registered entities may be a note's parent at all; it is
-// not what turns the check on.
+// entity's own read path (tenant scope plus its `access.read` ownership).
+// Both the field names and the optional `parents` allowlist come from the
+// entity's own `parentRef` declaration, which the read gate reads too —
+// see shared/parent-visibility.ts.
 export function createAddNoteHandler(
   access: AccessRule = DEFAULT_NOTES_HISTORY_ACCESS,
-  parents?: ReadonlySet<string>,
 ): WriteHandlerDef {
   return {
     name: "add-note",
@@ -35,13 +34,10 @@ export function createAddNoteHandler(
       // NotFoundError, not an access-denied error, so the response doesn't
       // double as an existence oracle — same policy as executor.detail,
       // which never distinguishes "no access" from "doesn't exist".
-      if (parents !== undefined && !parents.has(payload.entityType)) {
-        return writeFailure(new NotFoundError(payload.entityType, payload.entityId));
-      }
-      const visible = await parentRowIsVisible(
+      const visible = await joinRowParentIsVisible(
         ctx.registry,
-        payload.entityType,
-        payload.entityId,
+        "note-entry",
+        payload,
         event.user,
         ctx.db,
       );

package/src/personal-access-tokens/__tests__/expiry.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "bun:test";
+import { Temporal } from "temporal-polyfill";
+import { isExpiredAt } from "../expiry";
+
+describe("isExpiredAt", () => {
+  it("null never expires", () => {
+    expect(isExpiredAt(null)).toBe(false);
+  });
+
+  it("a future instant is not expired", () => {
+    const future = Temporal.Now.instant().add({ hours: 1 });
+    expect(isExpiredAt({ epochMilliseconds: future.epochMilliseconds })).toBe(false);
+  });
+
+  it("a past instant is expired", () => {
+    const past = Temporal.Now.instant().subtract({ hours: 1 });
+    expect(isExpiredAt({ epochMilliseconds: past.epochMilliseconds })).toBe(true);
+  });
+});

package/src/personal-access-tokens/__tests__/feature.test.ts

@@ -1,7 +1,12 @@
 import { describe, expect, test } from "bun:test";
 import { PAT_TOKEN_PREFIX } from "@cosmicdrift/kumiko-framework/api";
+import { fieldOptionLabelKey } from "@cosmicdrift/kumiko-headless";
 import { EXT_TOKEN_VERIFIER } from "../../auth-foundation";
+import { PAT_MINT_SCREEN_ID, PAT_SCREEN_ID, PatHandlers, PatQueries } from "../constants";
 import { createPersonalAccessTokensFeature } from "../feature";
+import { patScopeOptionTranslations } from "../i18n";
+import { expandScopes, type PatScopeConfig, parseGrant } from "../scopes";
+import { patGrantOptions } from "../screens";
 
 describe("createPersonalAccessTokensFeature toggleable-option (tier-gating)", () => {
   test("without toggleable: feature is always-on (toggleableDefault undefined)", () => {
@@ -40,3 +45,91 @@ describe("createPersonalAccessTokensFeature — tokenVerifier registration (#136
     expect(feature.requires).toContain("auth-foundation");
   });
 });
+
+describe("createPersonalAccessTokensFeature — declarative screens (fw#2548 Teil B)", () => {
+  test('registers no screen of type "custom"', () => {
+    const feature = createPersonalAccessTokensFeature({ scopes: {} });
+    const screens = Object.values(feature.screens);
+    expect(screens.length).toBeGreaterThan(0);
+    expect(screens.some((screen) => screen.type === "custom")).toBe(false);
+  });
+
+  test("list screen is a projectionList on PatQueries.mine with a revoke rowAction", () => {
+    const feature = createPersonalAccessTokensFeature({ scopes: {} });
+    const list = feature.screens[PAT_SCREEN_ID];
+    expect(list?.type).toBe("projectionList");
+    if (list?.type !== "projectionList") throw new Error("expected a projectionList screen");
+    expect(list.query).toBe(PatQueries.mine);
+    const revoke = list.rowActions?.find((action) => action.id === "revoke");
+    expect(revoke).toMatchObject({ handler: PatHandlers.revoke, kind: "writeHandler" });
+  });
+
+  test('mint screen is a secretMint on PatHandlers.create whose reveal.fields is exactly ["token"]', () => {
+    const feature = createPersonalAccessTokensFeature({ scopes: {} });
+    const mint = feature.screens[PAT_MINT_SCREEN_ID];
+    expect(mint?.type).toBe("secretMint");
+    if (mint?.type !== "secretMint") throw new Error("expected a secretMint screen");
+    expect(mint.handler).toBe(PatHandlers.create);
+    expect(mint.reveal.fields.map((field) => field.field)).toEqual(["token"]);
+  });
+});
+
+describe("patGrantOptions (fw#2548 Teil B)", () => {
+  test("a read-only domain yields only <domain>:read", () => {
+    const scopes: PatScopeConfig = { billing: { label: "Billing", read: ["billing:query:*"] } };
+    expect(patGrantOptions(scopes)).toEqual(["billing:read"]);
+  });
+
+  test("a domain with a non-empty write set additionally yields <domain>:write", () => {
+    const scopes: PatScopeConfig = {
+      ledger: { label: "Ledger", read: ["ledger:query:*"], write: ["ledger:write:*"] },
+    };
+    expect(patGrantOptions(scopes)).toEqual(["ledger:read", "ledger:write"]);
+  });
+
+  test("every generated grant string round-trips through parseGrant/expandScopes", () => {
+    const scopes: PatScopeConfig = {
+      billing: { label: "Billing", read: ["billing:query:*"] },
+      ledger: { label: "Ledger", read: ["ledger:query:*"], write: ["ledger:write:*"] },
+    };
+    for (const grant of patGrantOptions(scopes)) {
+      const parsed = parseGrant(grant);
+      expect(parsed).not.toBeNull();
+      expect(scopes[parsed?.domain ?? ""]).toBeDefined();
+      expect(expandScopes(scopes, [grant]).length).toBeGreaterThan(0);
+    }
+    // A read-level grant must not leak the domain's write QNs.
+    expect(expandScopes(scopes, ["ledger:read"])).toEqual(["ledger:query:*"]);
+    expect(expandScopes(scopes, ["ledger:write"])).toEqual(
+      expect.arrayContaining(["ledger:query:*", "ledger:write:*"]),
+    );
+  });
+});
+
+describe("patScopeOptionTranslations (fw#2548 Teil B)", () => {
+  test("option-label keys match the renderer's actual resolution convention (fieldOptionLabelKey)", () => {
+    const scopes: PatScopeConfig = {
+      billing: { label: "Billing", read: ["billing:query:*"], write: ["billing:write:*"] },
+    };
+    const translations = patScopeOptionTranslations(scopes);
+    // fieldOptionLabelKey is the exact function the mint form's multiSelect
+    // uses at render time (buildOptionLabels, headless/view-model/edit.ts) —
+    // building the same key here and looking it up in `translations` proves
+    // the label actually reaches the renderer instead of silently falling
+    // back to the raw grant string.
+    const readKey = fieldOptionLabelKey(
+      "personal-access-tokens",
+      "__action-form__",
+      "scopes",
+      "billing:read",
+    );
+    const writeKey = fieldOptionLabelKey(
+      "personal-access-tokens",
+      "__action-form__",
+      "scopes",
+      "billing:write",
+    );
+    expect(translations[readKey]?.en).toBe("Billing (read)");
+    expect(translations[writeKey]?.en).toBe("Billing (read & write)");
+  });
+});