@cosmicdrift/kumiko-bundled-features 0.269.2 → 0.273.0

package/src/delivery/testing.ts

@@ -1,6 +1,11 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type {
+  EscapeHatchAuditSink,
+  Registry,
+  TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { Logger } from "@cosmicdrift/kumiko-framework/logging";
 import type { Redis } from "ioredis";
 import type { KillSwitchResolver, RateLimitConfig } from "./delivery-service";
 import { collectChannels, createDeliveryService } from "./delivery-service";
@@ -10,6 +15,8 @@ export type CreateDeliveryTestContextOptions = {
   readonly tenantUserIdsQuery?: string;
   readonly rateLimit?: RateLimitConfig;
   readonly isChannelKilled?: KillSwitchResolver;
+  readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
+  readonly log?: Logger;
 };
 
 /**

package/src/derivatives-sharp/__tests__/derivatives-sharp.integration.test.ts

@@ -46,7 +46,7 @@ const variantTestFeature = defineFeature("derivativessharptest", (r) => {
       const meta = await imageMetadata(bytes);
       return { isSuccess: true as const, data: { ...result, ...meta } };
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 

package/src/folders/__tests__/feature.test.ts

@@ -93,7 +93,9 @@ describe("createFoldersFeature access-options", () => {
   });
 
   test("access:{openToAll} applies to every write- and query-path", () => {
-    const feature = createFoldersFeature({ access: { openToAll: true } });
+    const feature = createFoldersFeature({
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+    });
     for (const path of [
       "folder:create",
       "folder:update",
@@ -101,13 +103,20 @@ describe("createFoldersFeature access-options", () => {
       "set-folder",
       "clear-folder",
     ]) {
-      expect(rawWriteAccess(feature, path)).toEqual({ openToAll: true });
+      expect(rawWriteAccess(feature, path)).toEqual({
+        openToAll: { reason: "test handler callable by any signed-in test user" },
+      });
     }
   });
 
   test("access takes precedence over the roles shorthand", () => {
-    const feature = createFoldersFeature({ access: { openToAll: true }, roles: ["Admin"] });
-    expect(rawWriteAccess(feature, "set-folder")).toEqual({ openToAll: true });
+    const feature = createFoldersFeature({
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      roles: ["Admin"],
+    });
+    expect(rawWriteAccess(feature, "set-folder")).toEqual({
+      openToAll: { reason: "test handler callable by any signed-in test user" },
+    });
   });
 });
 
@@ -118,7 +127,7 @@ describe("createFoldersFeature toggleable-option (tier-gating)", () => {
 
   test("toggleable:{default:false} makes the feature tier-gatable, fail-closed", () => {
     const feature = createFoldersFeature({
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       toggleable: { default: false },
     });
     expect(feature.toggleableDefault).toBe(false);

package/src/folders/__tests__/folders-parent-visibility.integration.test.ts

@@ -93,7 +93,12 @@ let folderId: string;
 
 beforeAll(async () => {
   stack = await setupTestStack({
-    features: [createFoldersFeature({ access: { openToAll: true } }), hostFixturesFeature],
+    features: [
+      createFoldersFeature({
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      }),
+      hostFixturesFeature,
+    ],
   });
   await unsafeCreateEntityTable(stack.db, folderEntity);
   await unsafeCreateEntityTable(stack.db, folderAssignmentEntity);

package/src/folders/__tests__/folders-read-gate.integration.test.ts

@@ -79,7 +79,12 @@ let folderId: string;
 
 beforeAll(async () => {
   stack = await setupTestStack({
-    features: [createFoldersFeature({ access: { openToAll: true } }), hostFixturesFeature],
+    features: [
+      createFoldersFeature({
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      }),
+      hostFixturesFeature,
+    ],
   });
   await unsafeCreateEntityTable(stack.db, folderEntity);
   await unsafeCreateEntityTable(stack.db, folderAssignmentEntity);

package/src/folders/__tests__/folders.integration.test.ts

@@ -336,7 +336,12 @@ describe("folders integration — openToAll access model", () => {
 
   beforeAll(async () => {
     openStack = await setupTestStack({
-      features: [createFoldersFeature({ access: { openToAll: true } }), hostFixturesFeature],
+      features: [
+        createFoldersFeature({
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        }),
+        hostFixturesFeature,
+      ],
     });
     await unsafeCreateEntityTable(openStack.db, folderEntity);
     await unsafeCreateEntityTable(openStack.db, folderAssignmentEntity);

package/src/folders/feature.ts

@@ -47,7 +47,7 @@ function registerFolders(
   parents: readonly string[] | undefined,
 ): void {
   r.describe(
-    "Generic, host-agnostic hierarchical folders for any entity. Owns two event-sourced entities — the per-tenant `folder` tree (`read_folders`, self-referential via parentId) and SINGLE-membership `folder-assignment` rows keyed by (entityType, entityId) (`read_folder_assignments`) — so filing an entity adds NO column to the host and needs no relational pivot or JOIN. The folder catalog uses the generic entity handlers (create, update [= rename, optimistic-locked], delete, list, detail); set-folder puts/moves an entity into a folder (one folder per entity) and clear-folder unfiles it (both idempotent). Read which folder an entity is in, or which entities a folder holds, by listing `folder-assignment` filtered on `entityId` or `folderId`. Every path uses one access rule — adopt the host's model with createFoldersFeature({ access: { openToAll: true } }) or pin roles. Pass { toggleable: { default: false } } to make the whole feature tier-gatable via the tier-engine (no host hook).",
+    "Generic, host-agnostic hierarchical folders for any entity. Owns two event-sourced entities — the per-tenant `folder` tree (`read_folders`, self-referential via parentId) and SINGLE-membership `folder-assignment` rows keyed by (entityType, entityId) (`read_folder_assignments`) — so filing an entity adds NO column to the host and needs no relational pivot or JOIN. The folder catalog uses the generic entity handlers (create, update [= rename, optimistic-locked], delete, list, detail); set-folder puts/moves an entity into a folder (one folder per entity) and clear-folder unfiles it (both idempotent). Read which folder an entity is in, or which entities a folder holds, by listing `folder-assignment` filtered on `entityId` or `folderId`. Every path uses one access rule — adopt the host's model with createFoldersFeature({ access: { openToAll: { reason } } }) or pin roles. Pass { toggleable: { default: false } } to make the whole feature tier-gatable via the tier-engine (no host hook).",
   );
   r.uiHints({
     displayLabel: "Folders",
@@ -113,7 +113,7 @@ export const foldersFeature = defineFeature(FOLDERS_FEATURE_NAME, (r) =>
 
 export type FoldersFeatureOptions = {
   /** Access rule for all folder write/read paths. Default { roles: ["TenantAdmin","TenantMember"] }.
-   *  Adopt the host's model — e.g. { openToAll: true } when any authenticated
+   *  Adopt the host's model — e.g. { openToAll: { reason: "..." } } when any authenticated
    *  tenant user may file entities, or { roles: ["Admin"] } for a custom role
    *  vocabulary. Takes precedence over `roles`. */
   readonly access?: AccessRule;

package/src/form-draft/constants.ts

@@ -22,7 +22,13 @@ export const FormDraftQueries = {
 // Any authenticated tenant user may save/discard/read their OWN draft — the
 // per-row ownerId check in the handlers (not roles) is what keeps a draft
 // private to the user who created it. See handlers/*.ts.
-export const FORM_DRAFT_ACCESS: AccessRule = { openToAll: true };
+export const FORM_DRAFT_ACCESS: AccessRule = {
+  openToAll: {
+    reason:
+      "any signed-in tenant user may save, discard or read a draft; the per-row " +
+      "ownerId check in the handlers, not roles, keeps a draft private to its owner",
+  },
+};
 
 // Unique index name — shared between entity.ts (index declaration) and
 // handlers/save.write.ts (unique-violation race detection).

package/src/jobs/handlers/list.query.ts

@@ -43,7 +43,9 @@ export const listQuery = defineQueryHandler({
         message: "jobs:query:list requires ctx.systemDb (feature must declare r.systemScope())",
       });
     }
-    const db = ctx.systemDb.acknowledgeCrossTenant("cross-tenant job monitoring");
+    const db = ctx.systemDb.unsafeRaw(
+      "cross-tenant job monitoring: SystemAdmin lists job runs of every tenant",
+    );
     const where: WhereObject = {};
     if (query.payload.jobName) where["jobName"] = query.payload.jobName;
     const statusFilter = query.payload.filters?.find((filter) => filter.field === "status");

package/src/ledger/__tests__/ledger.integration.test.ts

@@ -11,6 +11,7 @@
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createSystemUser } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
   createTestUser,
@@ -18,6 +19,7 @@ import {
   type TestStack,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { generateDeterministicId } from "@cosmicdrift/kumiko-framework/utils";
 import { type AccountType, LedgerHandlers, LedgerQueries } from "../constants";
 import { accountEntity, scheduleEntity, transactionEntity } from "../entity";
 import { createLedgerFeature } from "../feature";
@@ -544,6 +546,61 @@ describe("ledger integration — confirm-schedule-period (recurring)", () => {
   });
 });
 
+describe("ledger integration — createSchedule with a caller-chosen id (idempotent job creates)", () => {
+  // An event-triggered job derives the schedule id deterministically from
+  // its own contract line instead of matching on description text. It acts
+  // as createSystemUser(tenantId, extraRoles) — extraRoles clears the
+  // handler's normal TenantAdmin/TenantMember access gate while roles still
+  // carrying "system" is what lets the create handler honor the id at all.
+  const jobUser = createSystemUser(admin.tenantId, ["TenantAdmin"]);
+
+  test("the chosen id is honored; redelivering the same event is recognized, not duplicated", async () => {
+    const bank = await createAccount("Bank", "asset");
+    const rent = await createAccount("Mieterträge", "income");
+    const scheduleId = generateDeterministicId(`ledger:schedule:${admin.tenantId}`, "contract-42");
+    const payload = {
+      description: "Miete WE1",
+      startDate: "2026-01-01",
+      interval: "monthly",
+      amount: 50000,
+      debitAccountId: bank,
+      creditAccountId: rent,
+      id: scheduleId,
+    };
+
+    const created = await stack.http.writeOk<{ id: string }>(
+      LedgerHandlers.createSchedule,
+      payload,
+      jobUser,
+    );
+    expect(created.id).toBe(scheduleId);
+
+    const redelivered = await stack.http.writeErr(LedgerHandlers.createSchedule, payload, jobUser);
+    expect(redelivered.code).toBe("version_conflict");
+  });
+
+  test("an ordinary tenant user's chosen id is ignored — create still succeeds with a fresh id", async () => {
+    const bank = await createAccount("Bank", "asset");
+    const rent = await createAccount("Mieterträge", "income");
+    const chosenId = generateDeterministicId(`ledger:schedule:${admin.tenantId}`, "contract-99");
+
+    const created = await stack.http.writeOk<{ id: string }>(
+      LedgerHandlers.createSchedule,
+      {
+        description: "Miete WE2",
+        startDate: "2026-01-01",
+        interval: "monthly",
+        amount: 30000,
+        debitAccountId: bank,
+        creditAccountId: rent,
+        id: chosenId,
+      },
+      admin,
+    );
+    expect(created.id).not.toBe(chosenId);
+  });
+});
+
 describe("ledger integration — subject dimension (filterable business-object reference)", () => {
   test("a booking with subjectType/subjectId round-trips and is findable via an eq filter", async () => {
     const bank = await createAccount("Bank", "asset");

package/src/managed-pages/screens/branding-screen.ts

@@ -81,6 +81,9 @@ export function createBrandingSettingsScreen(opts: {
       ],
     },
     access: { roles: ADMIN_ROLES },
+    // See file header: nav placement is app-specific, so this opts out of
+    // the boot-validator's nav-area check.
+    dormant: true,
   };
   if (!opts.allowCustomCss) return base;
   return {

package/src/managed-pages/screens/page-screens.ts

@@ -52,6 +52,9 @@ export const pageListScreen: EntityListScreenDefinition = {
     },
   ],
   access: { roles: ADMIN_ROLES },
+  // Nav/placement is app-specific (see file header) — no nav area to
+  // resolve in isolation.
+  dormant: true,
 };
 
 export const pageEditScreen: EntityEditScreenDefinition = {

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

@@ -81,7 +81,12 @@ 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],
+    features: [
+      createNotesHistoryFeature({
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      }),
+      hostFixturesFeature,
+    ],
   });
   await unsafeCreateEntityTable(stack.db, noteEntryEntity);
   await unsafeCreateEntityTable(stack.db, noteMentionEntity);
@@ -192,7 +197,10 @@ describe("notes-history read-gate — parents allowlist narrows both paths", ()
   beforeAll(async () => {
     allowStack = await setupTestStack({
       features: [
-        createNotesHistoryFeature({ access: { openToAll: true }, parents: ["project"] }),
+        createNotesHistoryFeature({
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+          parents: ["project"],
+        }),
         fixtures,
       ],
     });

package/src/notes-history/__tests__/notes-section.test.tsx

@@ -127,6 +127,29 @@ function renderSection(): ReturnType<typeof render> {
   return render(<NotesSection entityName="contact" entityId="contact-1" />, { wrapper });
 }
 
+describe("NotesSection — two-card layout", () => {
+  test("renders a 'new note' card and a 'history' card as two separate cards", async () => {
+    const view = renderSection();
+    await waitFor(() => expect(view.getByTestId("notes-section-history")).toBeTruthy());
+
+    const newNoteCard = view.getByTestId("notes-section-new");
+    const historyCard = view.getByTestId("notes-section-history");
+    expect(newNoteCard).not.toBe(historyCard);
+    expect(newNoteCard.textContent).toContain("New note");
+    expect(historyCard.textContent).toContain("History");
+  });
+
+  test("history entries are separated by dividers, not individual borders", async () => {
+    const view = renderSection();
+    await waitFor(() => expect(view.getByTestId("notes-section-row-note-1")).toBeTruthy());
+
+    const row = view.getByTestId("notes-section-row-note-1");
+    expect(row.className).not.toContain("border");
+    const historyCard = view.getByTestId("notes-section-history");
+    expect(historyCard.querySelector(".divide-y")).not.toBeNull();
+  });
+});
+
 describe("NotesSection — entry display", () => {
   test("note body and meta line render as two distinct nodes, not one run-on line", async () => {
     const view = renderSection();

package/src/notes-history/feature.ts

@@ -33,7 +33,7 @@ function registerNotesHistory(
   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 }).",
+    "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: { reason } } }) or pin roles with createNotesHistoryFeature({ roles }).",
   );
   r.uiHints({
     displayLabel: "Notes",
@@ -68,7 +68,7 @@ export const notesHistoryFeature = defineFeature(NOTES_HISTORY_FEATURE_NAME, (r)
 
 export type NotesHistoryFeatureOptions = {
   /** Access rule for the create/list paths. Default { roles: ["TenantAdmin","TenantMember"] }.
-   *  Adopt the host's model — e.g. { openToAll: true } when the host lets any
+   *  Adopt the host's model — e.g. { openToAll: { reason: "..." } } when the host lets any
    *  authenticated tenant user write (like the rest of its handlers), or
    *  { roles: ["Admin"] } for a custom role vocabulary. Takes precedence over `roles`. */
   readonly access?: AccessRule;

package/src/notes-history/web/i18n.ts

@@ -15,5 +15,8 @@ export const defaultTranslations: TranslationsByLocale = {
     "notesHistory.section.add": "Add note",
     "notesHistory.section.meta": "{author} · {date}",
     "notesHistory.section.authorUnknown": "Unknown author",
+    "notesHistory.section.newNoteTitle": "New note",
+    "notesHistory.section.historyTitle": "History",
+    "notesHistory.section.shortcutHint": "Ctrl+Enter saves",
   },
 };

package/src/notes-history/web/notes-section.tsx

@@ -48,7 +48,7 @@ export function NotesSection({
   readonly entityName: string;
   readonly entityId: string | null;
 }): ReactNode {
-  const { Banner, Button, Text, Input } = usePrimitives();
+  const { Banner, Button, Card, Grid, Text, Input } = usePrimitives();
   const t = useTranslation();
   const dispatcher = useDispatcher();
   const enabled = entityId !== null;
@@ -118,57 +118,67 @@ export function NotesSection({
   };
 
   return (
-    <div data-testid="notes-section" className="flex flex-col gap-3">
-      <div className="flex flex-col gap-2">
-        <Input
-          kind="textarea"
-          id="notes-section-draft"
-          name="draft"
-          value={draft}
-          onChange={setDraft}
-          onSubmitShortcut={() => {
-            if (!busy && draft.trim() !== "") addNote();
-          }}
-        />
-        <div>
-          <Button
-            variant="primary"
-            disabled={busy || draft.trim() === ""}
-            onClick={() => addNote()}
-            testId="notes-section-add"
-          >
-            {busy ? t("notesHistory.section.working") : t("notesHistory.section.add")}
-          </Button>
-        </div>
-      </div>
-
-      {rows.length === 0 ? (
-        <Text variant="small">{t("notesHistory.section.empty")}</Text>
-      ) : (
-        <div className="flex flex-col gap-2">
-          {rows.map((n) => (
-            <div
-              key={n.id}
-              data-testid={`notes-section-row-${n.id}`}
-              className="flex flex-col gap-1 rounded-md border p-2"
+    <Grid columns={1} testId="notes-section">
+      <Card slots={{ title: t("notesHistory.section.newNoteTitle") }} testId="notes-section-new">
+        <Grid columns={1}>
+          <Input
+            kind="textarea"
+            id="notes-section-draft"
+            name="draft"
+            value={draft}
+            onChange={setDraft}
+            onSubmitShortcut={() => {
+              if (!busy && draft.trim() !== "") addNote();
+            }}
+          />
+          <div className="flex items-center justify-between gap-2">
+            <Text variant="small">{t("notesHistory.section.shortcutHint")}</Text>
+            <Button
+              variant="primary"
+              disabled={busy || draft.trim() === ""}
+              onClick={() => addNote()}
+              testId="notes-section-add"
             >
-              <Text testId={`notes-section-body-${n.id}`}>{n.body}</Text>
-              <Text variant="small" testId={`notes-section-meta-${n.id}`}>
-                {t("notesHistory.section.meta", {
-                  author: displayAuthorName(n.authorName, t("notesHistory.section.authorUnknown")),
-                  date: formatWhen(n.insertedAt),
-                })}
-              </Text>
-            </div>
-          ))}
-        </div>
-      )}
+              {busy ? t("notesHistory.section.working") : t("notesHistory.section.add")}
+            </Button>
+          </div>
+          {errorKey !== null && (
+            <Banner variant="error" testId="notes-section-action-error">
+              <Text>{t(errorKey)}</Text>
+            </Banner>
+          )}
+        </Grid>
+      </Card>
 
-      {errorKey !== null && (
-        <Banner variant="error" testId="notes-section-action-error">
-          <Text>{t(errorKey)}</Text>
-        </Banner>
-      )}
-    </div>
+      <Card
+        slots={{ title: t("notesHistory.section.historyTitle") }}
+        testId="notes-section-history"
+      >
+        {rows.length === 0 ? (
+          <Text variant="small">{t("notesHistory.section.empty")}</Text>
+        ) : (
+          <div className="flex flex-col divide-y">
+            {rows.map((n) => (
+              <div
+                key={n.id}
+                data-testid={`notes-section-row-${n.id}`}
+                className="flex flex-col gap-1 py-3 first:pt-0 last:pb-0"
+              >
+                <Text testId={`notes-section-body-${n.id}`}>{n.body}</Text>
+                <Text variant="small" testId={`notes-section-meta-${n.id}`}>
+                  {t("notesHistory.section.meta", {
+                    author: displayAuthorName(
+                      n.authorName,
+                      t("notesHistory.section.authorUnknown"),
+                    ),
+                    date: formatWhen(n.insertedAt),
+                  })}
+                </Text>
+              </div>
+            ))}
+          </div>
+        )}
+      </Card>
+    </Grid>
   );
 }

package/src/personal-access-tokens/handlers/available-scopes.query.ts

@@ -10,7 +10,13 @@ export function buildAvailableScopesQuery(scopes: PatScopeConfig) {
   return defineQueryHandler({
     name: "available-scopes",
     schema: z.object({}),
-    access: { openToAll: true },
+    access: {
+      openToAll: {
+        reason:
+          "any signed-in user may list the deployment-wide PAT scope domains; the data " +
+          "is static configuration, not per-user or per-tenant",
+      },
+    },
     description:
       "Lists the API scope domains this deployment declares, each with its display label and whether it offers write access, for choosing what a new personal access token may do.",
     handler: async () =>

package/src/personal-access-tokens/handlers/create.write.ts

@@ -57,7 +57,13 @@ export function createPatCreateHandler(opts: CreatePatOptions = {}) {
       currentPassword: z.string().min(1),
       mfaCode: z.string().optional(),
     }),
-    access: { openToAll: true },
+    access: {
+      openToAll: {
+        reason:
+          "each signed-in user may mint a personal access token for their own account " +
+          "only, after re-verifying their own password (and MFA code, if enrolled)",
+      },
+    },
     escapeHatch: {
       reason:
         "Reads the caller's own passwordHash (privileged-only field) via ctx.queryAs(SYSTEM, " +

package/src/personal-access-tokens/handlers/list.query.ts

@@ -46,7 +46,13 @@ export const listPatQuery = definePagedQueryHandler({
     sort: z.string().optional(),
     sortDirection: z.enum(["asc", "desc"]).optional(),
   }),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user lists only their own personal access tokens; the query " +
+        "filters apiTokenTable by the caller's own userId",
+    },
+  },
   description:
     "Lists the calling user's personal access tokens with metadata only (name, key prefix, scopes, computed status, created/expiry/revoked timestamps, including revoked ones) and never the token secret.",
   outputSchema: z.object({

package/src/personal-access-tokens/handlers/revoke.write.ts

@@ -13,7 +13,13 @@ import { apiTokenTable } from "../schema/api-token";
 export const revokePatWrite = defineWriteHandler({
   name: "revoke",
   schema: z.object({ id: z.uuid() }),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user revokes only their own personal access token; ownership " +
+        "is enforced in the WHERE (userId = caller)",
+    },
+  },
   description:
     "Permanently revokes one of the caller's own personal access tokens so it stops authenticating; use it when a token leaked or is no longer needed.",
   agent: { risk: "high" },

package/src/personal-access-tokens/screens.ts

@@ -47,7 +47,15 @@ export const patListScreen: ProjectionListScreenDefinition = {
       style: "primary",
     },
   ],
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user views only their own personal access tokens, mirroring the list handler",
+    },
+  },
+  // Self-service settings-area screen, placed by the consuming app's own
+  // r.nav() — no nav area to resolve in isolation.
+  dormant: true,
 };
 
 // Grant-string vocabulary for a scope config's multiSelect field — a
@@ -102,6 +110,11 @@ export function createPatMintScreen(scopes: PatScopeConfig): SecretMintScreenDef
     },
     redirect: PAT_SCREEN_ID,
     cancelTarget: PAT_SCREEN_ID,
-    access: { openToAll: true },
+    access: {
+      openToAll: {
+        reason:
+          "each signed-in user mints a token for their own account only, mirroring the create handler",
+      },
+    },
   };
 }

package/src/secrets/__tests__/access-options-precedence.test.ts

@@ -7,12 +7,19 @@ describe("createSecretsFeature access/roles precedence", () => {
   });
 
   test("access-only is accepted", () => {
-    expect(() => createSecretsFeature({ access: { openToAll: true } })).not.toThrow();
+    expect(() =>
+      createSecretsFeature({
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      }),
+    ).not.toThrow();
   });
 
   test("access + roles together fail fast", () => {
-    expect(() => createSecretsFeature({ access: { openToAll: true }, roles: ["Admin"] })).toThrow(
-      /either `access` or `roles`/,
-    );
+    expect(() =>
+      createSecretsFeature({
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        roles: ["Admin"],
+      }),
+    ).toThrow(/either `access` or `roles`/);
   });
 });

package/src/secrets/__tests__/access-options.integration.test.ts

@@ -100,7 +100,11 @@ describe("secrets — access: { openToAll: true } (#2296)", () => {
   let stack: TestStack;
 
   beforeAll(async () => {
-    stack = await buildStack(createSecretsFeature({ access: { openToAll: true } }));
+    stack = await buildStack(
+      createSecretsFeature({
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      }),
+    );
   });
 
   afterAll(async () => {

package/src/secrets/feature.ts

@@ -93,7 +93,7 @@ export function requireSecretsContext(
 export type SecretsFeatureOptions = {
   /** Access rule for the `set`, `delete` and `list` handlers. Default
    *  { roles: ["TenantAdmin"] }. Adopt the host's role vocabulary with
-   *  { roles: [...] }, or { openToAll: true } to let any authenticated tenant
+   *  { roles: [...] }, or { openToAll: { reason: "..." } } to let any authenticated tenant
    *  user manage secrets — note this is a much larger blast radius than the
    *  default: tenant credentials (API keys, tokens) become writable/deletable,
    *  and their previews/hints listable, by every tenant member, not just
@@ -121,7 +121,7 @@ export function createSecretsFeature(opts: SecretsFeatureOptions = {}): FeatureD
   const access = resolveSecretsAccess(opts);
   return defineFeature(SECRETS_FEATURE_NAME, (r) => {
     r.describe(
-      'Stores arbitrary per-tenant secrets (API keys, tokens, credentials) encrypted at rest using AES-256 with a KEK loaded from `KUMIKO_SECRETS_MASTER_KEY_V1` (and successive versions for rotation). Read a secret in handlers via `ctx.secrets.get(tenantId, handle)`, which automatically appends a `tenantSecretRead` audit event so every access is traceable. A `rotate` job re-encrypts all envelopes after a KEK version bump. The `set`/`delete`/`list` handlers share one access rule — default { roles: ["TenantAdmin"] }; adopt the host\'s role vocabulary with createSecretsFeature({ roles }) or open it to every authenticated tenant user with { access: { openToAll: true } } (larger blast radius: any tenant member can then read secret previews and write/delete secrets, not just admins).',
+      'Stores arbitrary per-tenant secrets (API keys, tokens, credentials) encrypted at rest using AES-256 with a KEK loaded from `KUMIKO_SECRETS_MASTER_KEY_V1` (and successive versions for rotation). Read a secret in handlers via `ctx.secrets.get(tenantId, handle)`, which automatically appends a `tenantSecretRead` audit event so every access is traceable. A `rotate` job re-encrypts all envelopes after a KEK version bump. The `set`/`delete`/`list` handlers share one access rule — default { roles: ["TenantAdmin"] }; adopt the host\'s role vocabulary with createSecretsFeature({ roles }) or open it to every authenticated tenant user with { access: { openToAll: { reason } } } (larger blast radius: any tenant member can then read secret previews and write/delete secrets, not just admins).',
     );
     r.uiHints({
       displayLabel: "Tenant Secrets",