@cosmicdrift/kumiko-bundled-features 0.269.2 → 0.270.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.269.2",
+  "version": "0.270.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -129,12 +129,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.269.2",
-    "@cosmicdrift/kumiko-framework": "0.269.2",
-    "@cosmicdrift/kumiko-headless": "0.269.2",
-    "@cosmicdrift/kumiko-renderer": "0.269.2",
-    "@cosmicdrift/kumiko-renderer-web": "0.269.2",
-    "@cosmicdrift/kumiko-types": "0.269.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.270.0",
+    "@cosmicdrift/kumiko-framework": "0.270.0",
+    "@cosmicdrift/kumiko-headless": "0.270.0",
+    "@cosmicdrift/kumiko-renderer": "0.270.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.270.0",
+    "@cosmicdrift/kumiko-types": "0.270.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -163,7 +163,7 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.269.2",
-    "@cosmicdrift/kumiko-locale-es": "0.269.2"
+    "@cosmicdrift/kumiko-locale-de": "0.270.0",
+    "@cosmicdrift/kumiko-locale-es": "0.270.0"
   }
 }

package/src/__tests__/account-security-composition.boot.test.ts

@@ -40,14 +40,32 @@ describe("account-security composed from bundled screens (fw#2841)", () => {
 
   test("the self-service screens are open to every signed-in user", () => {
     const [, , , , , sessions, mfa] = bootFeatures();
-    const screens = [
-      sessions?.screens[SESSION_MINE_SCREEN_ID],
-      mfa?.screens[MFA_ENABLE_SCREEN_ID],
-      mfa?.screens[MFA_DISABLE_SCREEN_ID],
-      mfa?.screens[MFA_REGENERATE_RECOVERY_SCREEN_ID],
+    const screensWithReason: ReadonlyArray<{
+      readonly screen: { readonly access?: unknown } | undefined;
+      readonly reason: string;
+    }> = [
+      {
+        screen: sessions?.screens[SESSION_MINE_SCREEN_ID],
+        reason:
+          "each signed-in user views and revokes only their own sessions, mirroring the mine/revoke handlers",
+      },
+      {
+        screen: mfa?.screens[MFA_ENABLE_SCREEN_ID],
+        reason:
+          "each signed-in user may enroll their own account in MFA, mirroring the enable-start handler",
+      },
+      {
+        screen: mfa?.screens[MFA_DISABLE_SCREEN_ID],
+        reason: "each signed-in user may turn off their own MFA, mirroring the disable handler",
+      },
+      {
+        screen: mfa?.screens[MFA_REGENERATE_RECOVERY_SCREEN_ID],
+        reason:
+          "each signed-in user may regenerate their own recovery codes, mirroring the regenerate-recovery handler",
+      },
     ];
-    for (const screen of screens) {
-      expect(screen?.access).toEqual({ openToAll: true });
+    for (const { screen, reason } of screensWithReason) {
+      expect(screen?.access).toEqual({ openToAll: { reason } });
     }
   });
 

package/src/__tests__/account-security-composition.integration.test.ts

@@ -114,7 +114,29 @@ describe("account-security dashboard on a real stack", () => {
       "auth-mfa:screen:auth-mfa-disable",
       "sessions:screen:my-sessions",
     ]);
-    for (const qn of targets) expect(embeddedScreen(qn).access).toEqual({ openToAll: true });
+    const expectedReasons: ReadonlyArray<{ readonly qn: string; readonly reason: string }> = [
+      {
+        qn: "auth-mfa:screen:auth-mfa-enable",
+        reason:
+          "each signed-in user may enroll their own account in MFA, mirroring the enable-start handler",
+      },
+      {
+        qn: "auth-mfa:screen:auth-mfa-regenerate-recovery",
+        reason:
+          "each signed-in user may regenerate their own recovery codes, mirroring the regenerate-recovery handler",
+      },
+      {
+        qn: "auth-mfa:screen:auth-mfa-disable",
+        reason: "each signed-in user may turn off their own MFA, mirroring the disable handler",
+      },
+      {
+        qn: "sessions:screen:my-sessions",
+        reason:
+          "each signed-in user views and revokes only their own sessions, mirroring the mine/revoke handlers",
+      },
+    ];
+    for (const { qn, reason } of expectedReasons)
+      expect(embeddedScreen(qn).access).toEqual({ openToAll: { reason } });
   });
 
   test("a plain User gets the flat visibleWhen record and their own sessions over HTTP", async () => {

package/src/agent-tools/__tests__/agent-doc-lint.test.ts

@@ -7,7 +7,9 @@ import {
 import { z } from "zod";
 import { AgentDocGapKinds, findAgentDocGaps, formatAgentDocGap } from "../agent-doc-lint";
 
-const OPEN_ACCESS = { openToAll: true } as const;
+const OPEN_ACCESS = {
+  openToAll: { reason: "test handler callable by any signed-in test user" },
+} as const;
 
 async function noopWriteHandler() {
   return { isSuccess: true as const, data: {} };

package/src/agent-tools/__tests__/feature.test.ts

@@ -9,9 +9,15 @@ async function noopWriteHandler() {
 
 function undocumentedHandlersFeature() {
   return defineFeature("doc-gap-demo", (r) => {
-    r.writeHandler("do-a", z.object({}), noopWriteHandler, { access: { openToAll: true } });
-    r.writeHandler("do-b", z.object({}), noopWriteHandler, { access: { openToAll: true } });
-    r.writeHandler("do-c", z.object({}), noopWriteHandler, { access: { openToAll: true } });
+    r.writeHandler("do-a", z.object({}), noopWriteHandler, {
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+    });
+    r.writeHandler("do-b", z.object({}), noopWriteHandler, {
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+    });
+    r.writeHandler("do-c", z.object({}), noopWriteHandler, {
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+    });
   });
 }
 
@@ -41,7 +47,7 @@ describe("createAgentToolsFeature", () => {
   test("boot check stays silent for a fully-described registry", () => {
     const describedFeature = defineFeature("doc-clean-demo", (r) => {
       r.writeHandler("do-a", z.object({}), noopWriteHandler, {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         description: "Does A.",
       });
     });

package/src/auth-email-password/handlers/invite-accept.write.ts

@@ -81,7 +81,14 @@ export function createInviteAcceptHandler() {
     // openToAll: any authenticated user (Branch 1). Branch 2+3 (anon)
     // nutzen `roles: ["all"]` weil dort GUEST_USER mit ["all"]-role
     // dispatched wird.
-    access: { openToAll: true },
+    access: {
+      openToAll: {
+        reason:
+          "any signed-in user may accept an invitation; the token identifies the pending " +
+          "invitation and its tenant, and the handler verifies the caller's own email matches " +
+          "the invitation before adding membership",
+      },
+    },
     agent: { expose: false },
     escapeHatch: {
       reason: INVITE_ACCEPT_ESCAPE_HATCH_REASON,

package/src/auth-mfa/handlers/disable.write.ts

@@ -30,7 +30,13 @@ export function createDisableHandler(opts: DisableOptions) {
   return defineWriteHandler({
     name: "disable",
     schema: z.object({ code: z.string().min(6).max(9) }),
-    access: { openToAll: true },
+    access: {
+      openToAll: {
+        reason:
+          "each signed-in user may disable only their own MFA enrollment after proving " +
+          "possession of a TOTP or recovery code; the handler looks up and removes the caller's own user-mfa row",
+      },
+    },
     description:
       "Removes the caller's TOTP enrollment for good after they prove possession with a TOTP or recovery code, and signs their other sessions and access tokens out; use it when a user wants two-factor authentication turned off.",
     agent: { risk: "high" },

package/src/auth-mfa/handlers/enable-confirm.write.ts

@@ -37,7 +37,13 @@ export function createEnableConfirmHandler(opts: EnableConfirmOptions) {
       setupToken: z.string().min(1),
       code: z.string().length(6),
     }),
-    access: { openToAll: true },
+    access: {
+      openToAll: {
+        reason:
+          "each signed-in user may complete their own MFA enrollment; the setup token is bound " +
+          "to the caller's id and any token minted for another user is rejected",
+      },
+    },
     description:
       "Completes TOTP enrollment for the signed-in user by checking a code against the secret carried in the setup token from enable-start, then storing the factor and signing every other session and access token out.",
     // Changes the caller's authentication state and signs their other sessions out.

package/src/auth-mfa/handlers/enable-start.write.ts

@@ -29,7 +29,13 @@ export function createEnableStartHandler(opts: EnableStartOptions) {
       // input fields) — derived server-side from the caller's own email below.
       accountLabel: z.string().min(1).max(200).optional(),
     }),
-    access: { openToAll: true },
+    access: {
+      openToAll: {
+        reason:
+          "each signed-in user may begin MFA enrollment for their own account only; nothing is " +
+          "persisted until enable-confirm and the label defaults from the caller's own session",
+      },
+    },
     description:
       "Begins TOTP enrollment for the signed-in user by generating a secret plus recovery codes and returning them as a short-lived setup token, an otpauth:// URI, the base32 secret for manual entry and the one-time plaintext recovery codes; nothing is persisted until enable-confirm. accountLabel defaults to the caller's own email.",
     // The result carries the TOTP secret, the otpauth:// URI and the plaintext

package/src/auth-mfa/handlers/regenerate-recovery.write.ts

@@ -26,7 +26,13 @@ export function createRegenerateRecoveryHandler(opts: RegenerateRecoveryOptions)
   return defineWriteHandler({
     name: "regenerate-recovery",
     schema: z.object({ code: z.string().min(6).max(9) }),
-    access: { openToAll: true },
+    access: {
+      openToAll: {
+        reason:
+          "each signed-in user may regenerate only their own recovery codes after proving " +
+          "possession of a TOTP or recovery code; the handler looks up the caller's own user-mfa row",
+      },
+    },
     description:
       "Destroys every existing recovery code of the caller, including unused ones, and returns a fresh set once in plaintext; use it when recovery codes may have leaked but TOTP itself should stay enrolled.",
     // Returns a fresh set of plaintext recovery codes — same transcript leak as

package/src/auth-mfa/handlers/status.query.ts

@@ -13,7 +13,13 @@ import { userMfaTable } from "../schema/user-mfa";
 export const mfaStatusQuery = defineQueryHandler({
   name: "user-mfa:status",
   schema: z.object({}),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user reads only their own MFA status; the query filters " +
+        "userMfaTable by the caller's own id",
+    },
+  },
   description:
     "Reports whether the calling user has TOTP two-factor authentication enrolled; use it before offering either the enrollment flow or the disable and recovery-code actions.",
   handler: async (query, ctx) => {

package/src/auth-mfa/screens.ts

@@ -10,6 +10,13 @@ import {
   MFA_REGENERATE_RECOVERY_SCREEN_ID,
 } from "./constants";
 
+const MFA_ENABLE_OPEN_REASON =
+  "each signed-in user may enroll their own account in MFA, mirroring the enable-start handler";
+const MFA_DISABLE_OPEN_REASON =
+  "each signed-in user may turn off their own MFA, mirroring the disable handler";
+const MFA_REGENERATE_RECOVERY_OPEN_REASON =
+  "each signed-in user may regenerate their own recovery codes, mirroring the regenerate-recovery handler";
+
 // Declarative TOTP-enrollment screen: mint (no input) -> reveal QR/secret/
 // recovery-codes -> confirm with a 6-digit code. `setupToken` is carried
 // from the mint payload into the confirm payload but never listed in
@@ -21,7 +28,11 @@ export const mfaEnableScreen: SecretMintScreenDefinition = {
   fields: {},
   layout: { sections: [] },
   submitLabel: i18nKey("mfa.enable.start"),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason: MFA_ENABLE_OPEN_REASON,
+    },
+  },
   description:
     "Self-service screen where a signed-in user enrolls in TOTP two-factor authentication: it shows the QR code and manual secret, reveals the recovery codes once, and confirms enrollment with a code from their authenticator app.",
   reveal: {
@@ -73,7 +84,11 @@ export const mfaDisableScreen: ActionFormScreenDefinition = {
   submitLabel: i18nKey("mfa.disable.submit"),
   submitStyle: "danger",
   cancelTarget: false,
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason: MFA_DISABLE_OPEN_REASON,
+    },
+  },
   description:
     "Self-service screen where a signed-in user turns two-factor authentication off by entering a code from their authenticator app or a recovery code; their other sessions and access tokens are signed out.",
 };
@@ -86,7 +101,11 @@ export const mfaRegenerateRecoveryScreen: SecretMintScreenDefinition = {
   layout: { sections: [{ fields: ["code"] }] },
   submitLabel: i18nKey("mfa.regenerate.submit"),
   cancelTarget: false,
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason: MFA_REGENERATE_RECOVERY_OPEN_REASON,
+    },
+  },
   description:
     "Self-service screen where a signed-in user with two-factor authentication replaces all recovery codes after confirming with a current code; the new codes are shown once.",
   reveal: {

package/src/channel-in-app/handlers/inbox.query.ts

@@ -9,7 +9,13 @@ export const inboxQuery = defineQueryHandler({
     limit: z.number().min(1).max(100).default(50),
     unreadOnly: z.boolean().default(false),
   }),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user reads only their own in-app inbox; the query filters " +
+        "inAppMessagesTable by the caller's own id",
+    },
+  },
   description:
     "Lists the calling user's own in-app notification messages newest-first, optionally only the unread ones; use it to show or inspect a user's notification inbox.",
   handler: async (query, ctx) => {

package/src/channel-in-app/handlers/mark-all-read.write.ts

@@ -6,7 +6,13 @@ import { inAppMessagesTable } from "../tables";
 export const markAllReadWrite = defineWriteHandler({
   name: "markAllRead",
   schema: z.object({}),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user marks only their own unread in-app messages as read; the " +
+        "update is scoped to the caller's own userId",
+    },
+  },
   description:
     "Marks every unread in-app message of the calling user as read and returns how many rows were touched; use it for a mark-all-as-read action.",
   handler: async (event, ctx) => {

package/src/channel-in-app/handlers/mark-read.write.ts

@@ -10,7 +10,13 @@ export const markReadWrite = defineWriteHandler({
     // inAppMessages.id is a serial integer (table is infra, not an ES aggregate).
     id: z.number().int(),
   }),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user marks only their own in-app message as read; the update " +
+        "requires id + the caller's own userId to match, otherwise it fails not-found",
+    },
+  },
   description:
     "Marks one in-app message of the calling user as read by its numeric id, failing with not-found when no such message belongs to the caller; use it when a user opens a single notification.",
   handler: async (event, ctx) => {

package/src/channel-in-app/handlers/unread-count.query.ts

@@ -6,7 +6,13 @@ import { inAppMessagesTable } from "../tables";
 export const unreadCountQuery = defineQueryHandler({
   name: "unreadCount",
   schema: z.object({}),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user counts only their own unread in-app messages; the query " +
+        "filters inAppMessagesTable by the caller's own id",
+    },
+  },
   description:
     "Counts the calling user's unread in-app notification messages; use it for an inbox badge or to check whether a user has pending notifications.",
   handler: async (query, ctx) => {

package/src/compliance-profiles/handlers/for-tenant.query.ts

@@ -19,7 +19,13 @@ import { tenantComplianceProfileTable } from "../schema/profile-selection";
 export const forTenantQuery = defineQueryHandler({
   name: "for-tenant",
   schema: z.object({}),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in tenant member may read their own tenant's effective compliance " +
+        "profile; the result carries policy metadata, never PII",
+    },
+  },
   description:
     "Returns the effective compliance profile for the caller's tenant with any tenant override merged in, falling back to minimal-no-region plus a no-profile-selected warning when the tenant has not picked one yet.",
   handler: async (query, ctx): Promise<EffectiveComplianceProfile> => {

package/src/compliance-profiles/handlers/list-profiles.query.ts

@@ -16,7 +16,13 @@ import { z } from "zod";
 export const listProfilesQuery = defineQueryHandler({
   name: "list-profiles",
   schema: z.object({}),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may list the selectable compliance profiles; the data is " +
+        "static, deployment-wide reference information, not tenant- or user-specific",
+    },
+  },
   description:
     "Lists the compliance profiles a tenant can choose from (key, region, label, supervisory-authority contact, notification languages), for rendering the onboarding profile picker; the minimal-no-region fallback is excluded because it is not selectable.",
   handler: async (): Promise<{ profiles: readonly ComplianceProfileSummary[] }> => {

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

@@ -173,7 +173,7 @@ const probeFeature = defineFeature("probe", (r) => {
         data: { orders: probe.orders, push: probe.push, betaEnabled: probe.betaEnabled },
       };
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 

package/src/config/__tests__/tz-resolution.integration.test.ts

@@ -38,7 +38,7 @@ const probeFeature = defineFeature("probe", (r) => {
       isSuccess: true,
       data: { tenant: ctx.tz.tenant, user: ctx.tz.user },
     }),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 

package/src/config/handlers/cascade.query.ts

@@ -16,7 +16,13 @@ export const cascadeQuery = defineQueryHandler({
   schema: z.object({
     keys: z.array(z.string()).optional(),
   }),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may call cascade; hasConfigAccess filters the result to " +
+        "only the config keys the caller's roles may read, before any value is returned",
+    },
+  },
   handler: async (query, ctx) => {
     const db = requireSystemDb(ctx, "config:query:cascade", query.user.tenantId);
     const registry = ctx.registry;

package/src/config/handlers/readiness.query.ts

@@ -131,7 +131,13 @@ export const readinessQuery = defineQueryHandler({
     "Lists the required config keys that are still unset for the caller's tenant, each with its scope and type; use it to find out what is missing before a feature can run.",
   schema: z.object({}),
   // Per-key read access enforced via hasConfigAccess inside the handler.
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may call readiness; collectMissingRequiredConfig filters " +
+        "candidate keys through hasConfigAccess so only keys the caller's roles may read are reported",
+    },
+  },
   handler: async (query, ctx) => {
     const db = requireSystemDb(ctx, "config:query:readiness", query.user.tenantId);
     const missing = await collectMissingRequiredConfig(

package/src/config/handlers/reset.write.ts

@@ -26,7 +26,13 @@ export const resetWrite = defineWriteHandler({
     scope: scopeEnum.optional(),
   }),
   // Per-key access enforcement lives inside the handler via checkWriteAccess.
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may call reset; prepareConfigWrite enforces the per-key " +
+        "write access rule before any value is touched",
+    },
+  },
   handler: async (event, ctx) => {
     const db = requireSystemDb(ctx, "config:write:reset", event.user.tenantId);
 

package/src/config/handlers/schema.query.ts

@@ -8,7 +8,13 @@ export const schemaQuery = defineQueryHandler({
     "Returns the definitions of all config keys the caller may read (scope, type, default, bounds, required flag) without any values; use it to discover which settings exist and how they may be set.",
   schema: z.object({}),
   // Per-key read access enforced via hasConfigAccess inside the handler.
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may call schema; hasConfigAccess filters the result to " +
+        "only the config key definitions the caller's roles may read",
+    },
+  },
   handler: async (query, ctx) => {
     const registry = ctx.registry;
     const allKeys = registry.getAllConfigKeys();

package/src/config/handlers/set.write.ts

@@ -44,7 +44,13 @@ export const setWrite = defineWriteHandler({
     scope: scopeEnum.optional(),
   }),
   // Per-key access enforcement lives inside the handler via checkWriteAccess.
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may call set; prepareConfigWrite enforces the per-key " +
+        "write access rule before any value is stored",
+    },
+  },
   handler: async (event, ctx) => {
     const db = requireSystemDb(ctx, "config:write:set", event.user.tenantId);
 

package/src/config/handlers/values.query.ts

@@ -16,7 +16,13 @@ export const valuesQuery = defineQueryHandler({
     "Returns the effective value, scope and winning source for every config key the caller may read, with encrypted and secret-backed values masked; use it to inspect the current settings.",
   schema: z.object({}),
   // Per-key read access enforced via hasConfigAccess inside the handler.
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may call values; hasConfigAccess filters the result to " +
+        "only the config keys the caller's roles may read, before any value is returned",
+    },
+  },
   handler: async (query, ctx) => {
     const db = requireSystemDb(ctx, "config:query:values", query.user.tenantId);
     const registry = ctx.registry;

package/src/data-retention/handlers/policy-for.query.ts

@@ -22,7 +22,14 @@ export const policyForQuery = defineQueryHandler({
   schema: z.object({
     entityName: z.string().min(1).max(100),
   }),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in tenant member (and other features calling cross-feature) may " +
+        "resolve the retention policy for an entity name in their own tenant; the result " +
+        "carries only policy metadata, no PII",
+    },
+  },
   description:
     "Resolves the effective retention policy for one entity name in the caller's tenant (keep-for duration plus delete or anonymize strategy) by layering the entity default, tenant preset and tenant override, so a forget flow or cleanup job knows how that data may be removed.",
   handler: async (query, ctx): Promise<EffectiveRetentionPolicy> => {

package/src/delivery/__tests__/delivery-pii-kms.integration.test.ts

@@ -65,7 +65,7 @@ const appFeature = defineFeature("app", (r) => {
         });
         return { isSuccess: true, data: { sent: true } };
       },
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     }),
   );
 
@@ -82,7 +82,7 @@ const appFeature = defineFeature("app", (r) => {
         });
         return { isSuccess: true, data: { sent: true } };
       },
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     }),
   );
 });

package/src/delivery/__tests__/delivery-screens.boot.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { access, validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { access, isOpenToAllGranted, validateBoot } from "@cosmicdrift/kumiko-framework/engine";
 import { rolesOf } from "@cosmicdrift/kumiko-framework/testing";
 import { DELIVERY_LOG_SCREEN_ID } from "../constants";
 import { createDeliveryFeature } from "../feature";
@@ -33,9 +33,7 @@ describe("delivery screens + handler access alignment", () => {
   test("access option leaves the preferences handler openToAll — that's per-user, not an admin surface", () => {
     const delivery = createDeliveryFeature({ access: access.systemAdmin });
     const preferencesAccess = delivery.queryHandlers["preferences"]?.access;
-    expect(
-      preferencesAccess && "openToAll" in preferencesAccess && preferencesAccess.openToAll,
-    ).toBe(true);
+    expect(preferencesAccess !== undefined && isOpenToAllGranted(preferencesAccess)).toBe(true);
   });
 
   test("boot-validates with a narrowed access option", () => {

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

@@ -101,7 +101,7 @@ const appFeature = defineFeature("app", (r) => {
 
         return { isSuccess: true, data: { assigned: true } };
       },
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     }),
   );
 
@@ -124,7 +124,7 @@ const appFeature = defineFeature("app", (r) => {
 
         return { isSuccess: true, data: { sent: true } };
       },
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     }),
   );
 
@@ -141,7 +141,7 @@ const appFeature = defineFeature("app", (r) => {
         title: z.string(),
         body: z.string(),
       }),
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       handler: async (event, ctx) => {
         const notify = ctx.notify as NotifyFn;
         await notify(event.payload.notificationType, {
@@ -173,7 +173,7 @@ const appFeature = defineFeature("app", (r) => {
 
         return { isSuccess: true, data: { sent: true } };
       },
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     }),
   );
 });
@@ -206,7 +206,7 @@ const ticketFeature = defineFeature("tickets", (r) => {
       status: z.string(),
     }),
     async (event, ctx) => ticketExecutor().create(event.payload, event.user, ctx.db),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   // Declarative: notify assignee when ticket is created with assigneeId

package/src/delivery/handlers/preferences.query.ts

@@ -7,7 +7,13 @@ import { notificationPreferencesTable } from "../tables";
 export const preferencesQuery = defineQueryHandler({
   name: "preferences",
   schema: z.object({}),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user reads only their own notification preference rows; the " +
+        "query filters notificationPreferencesTable by the caller's own tenantId and userId",
+    },
+  },
   description:
     "Returns the calling user's notification preference rows for their own tenant; use it to show which notification types and channels that user has enabled or muted.",
   handler: async (query, ctx) => {

package/src/delivery/handlers/set-preference.write.ts

@@ -11,7 +11,13 @@ export const setPreferenceWrite = defineWriteHandler({
     enabled: z.boolean(),
   }),
   // Every user manages their own preferences; tenant+user scoping is on the WHERE.
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user changes only their own notification preferences; the " +
+        "write is scoped to the caller's own tenantId and userId via assertTenantMatch",
+    },
+  },
   description:
     "Enables or disables one notification type and channel combination for the calling user, where either side may be the wildcard * as a catch-all; use it when a user changes their own notification settings.",
   handler: async (event, ctx) => {