@cosmicdrift/kumiko-bundled-features 0.269.2 → 0.270.0

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/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/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/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

@@ -6,6 +6,11 @@ import {
 import { PAT_MINT_SCREEN_ID, PAT_SCREEN_ID, PatHandlers, PatQueries } from "./constants";
 import type { PatScopeConfig } from "./scopes";
 
+const PAT_LIST_OPEN_REASON =
+  "each signed-in user views only their own personal access tokens, mirroring the list handler";
+const PAT_MINT_OPEN_REASON =
+  "each signed-in user mints a token for their own account only, mirroring the create handler";
+
 export const patListScreen: ProjectionListScreenDefinition = {
   id: PAT_SCREEN_ID,
   type: "projectionList",
@@ -47,7 +52,11 @@ export const patListScreen: ProjectionListScreenDefinition = {
       style: "primary",
     },
   ],
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason: PAT_LIST_OPEN_REASON,
+    },
+  },
 };
 
 // Grant-string vocabulary for a scope config's multiSelect field — a
@@ -102,6 +111,10 @@ export function createPatMintScreen(scopes: PatScopeConfig): SecretMintScreenDef
     },
     redirect: PAT_SCREEN_ID,
     cancelTarget: PAT_SCREEN_ID,
-    access: { openToAll: true },
+    access: {
+      openToAll: {
+        reason: PAT_MINT_OPEN_REASON,
+      },
+    },
   };
 }

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",

package/src/sessions/handlers/mine.query.ts

@@ -12,7 +12,13 @@ import { userSessionTable } from "../schema/user-session";
 export const mineQuery = definePagedQueryHandler({
   name: "user-session:mine",
   schema: z.object({}),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user lists only their own live sessions; the query filters " +
+        "userSessionTable by the caller's own userId",
+    },
+  },
   description:
     "Lists the calling user's own still-live sessions, newest first, each flagged whether it is the one making the request; use it to show a user their signed-in devices.",
   outputSchema: z.object({

package/src/sessions/handlers/revoke-all-others.write.ts

@@ -15,7 +15,13 @@ import { SESSION_REVOKED_AGGREGATE_TYPE, SESSION_REVOKED_EVENT_QN } from "../ses
 export const revokeAllOthersWrite = defineWriteHandler({
   name: "user-session:revoke-all-others",
   schema: z.object({}),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user revokes only their own other sessions; the update is " +
+        "scoped to the caller's own userId, keeping only their current session (sid)",
+    },
+  },
   description:
     'Irreversibly signs the calling user out of every session except the one making the request and reports how many were dropped; use it for a "sign out everywhere else" action after a suspected compromise.',
   agent: { risk: "high" },

package/src/sessions/handlers/revoke.write.ts

@@ -28,7 +28,13 @@ export const revokeWrite = defineWriteHandler({
   schema: z.object({
     id: z.uuid(),
   }),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user revokes only their own session by id; the update is " +
+        "scoped to the caller's own userId",
+    },
+  },
   description:
     "Irreversibly signs one of the caller's own sessions out by id; use it when a user wants to drop a single device, and note that revoking their current session logs them out.",
   agent: { risk: "high" },

package/src/sessions/screens.ts

@@ -13,6 +13,8 @@ import {
 } from "./constants";
 
 const listAccess = { roles: access.admin };
+const SESSION_MINE_OPEN_REASON =
+  "each signed-in user views and revokes only their own sessions, mirroring the mine/revoke handlers";
 
 export const sessionListScreen: ProjectionListScreenDefinition = {
   id: SESSION_LIST_SCREEN_ID,
@@ -140,5 +142,9 @@ export const sessionMineScreen: ProjectionListScreenDefinition = {
       confirm: i18nKey("sessions.mine.revokeAllOthers.confirm"),
     },
   ],
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason: SESSION_MINE_OPEN_REASON,
+    },
+  },
 };

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

@@ -105,7 +105,9 @@ describe("createTagsFeature access-options", () => {
   });
 
   test("access:{openToAll} applies to every write- and query-path", () => {
-    const feature = createTagsFeature({ access: { openToAll: true } });
+    const feature = createTagsFeature({
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+    });
     for (const path of [
       "create-tag",
       "update-tag",
@@ -116,17 +118,28 @@ describe("createTagsFeature access-options", () => {
       "assign-tag",
       "remove-tag",
     ]) {
-      expect(rawWriteAccess(feature, path)).toEqual({ openToAll: true });
+      expect(rawWriteAccess(feature, path)).toEqual({
+        openToAll: { reason: "test handler callable by any signed-in test user" },
+      });
     }
     for (const query of ["tag:list", "tag:detail", "tag-assignment:list"]) {
-      expect(rawQueryAccess(feature, query)).toEqual({ openToAll: true });
+      expect(rawQueryAccess(feature, query)).toEqual({
+        openToAll: { reason: "test handler callable by any signed-in test user" },
+      });
     }
   });
 
   test("access takes precedence over the roles shorthand", () => {
-    const feature = createTagsFeature({ access: { openToAll: true }, roles: ["Admin"] });
-    expect(rawWriteAccess(feature, "create-tag")).toEqual({ openToAll: true });
-    expect(rawQueryAccess(feature, "tag:list")).toEqual({ openToAll: true });
+    const feature = createTagsFeature({
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      roles: ["Admin"],
+    });
+    expect(rawWriteAccess(feature, "create-tag")).toEqual({
+      openToAll: { reason: "test handler callable by any signed-in test user" },
+    });
+    expect(rawQueryAccess(feature, "tag:list")).toEqual({
+      openToAll: { reason: "test handler callable by any signed-in test user" },
+    });
   });
 
   test("access:{roles} threads through like the roles shorthand", () => {
@@ -139,12 +152,16 @@ describe("createTagsFeature access-options", () => {
 describe("createTagsFeature toggleable-option (tier-gating)", () => {
   test("without toggleable: feature is always-on (toggleableDefault undefined)", () => {
     expect(createTagsFeature().toggleableDefault).toBeUndefined();
-    expect(createTagsFeature({ access: { openToAll: true } }).toggleableDefault).toBeUndefined();
+    expect(
+      createTagsFeature({
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      }).toggleableDefault,
+    ).toBeUndefined();
   });
 
   test("toggleable:{default:false} makes the feature tier-gatable, fail-closed", () => {
     const feature = createTagsFeature({
-      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/tags/__tests__/tags-parent-visibility.integration.test.ts

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

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

@@ -99,7 +99,12 @@ let tagId: string;
 beforeAll(async () => {
   stack = await setupTestStack({
     // Deliberately no `ownership` — the gate must hold on a bare mount.
-    features: [createTagsFeature({ access: { openToAll: true } }), hostFixturesFeature],
+    features: [
+      createTagsFeature({
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      }),
+      hostFixturesFeature,
+    ],
   });
   await unsafeCreateEntityTable(stack.db, tagEntity);
   await unsafeCreateEntityTable(stack.db, tagAssignmentEntity);
@@ -303,7 +308,7 @@ describe("tags read-gate — ownership narrows further, it does not replace the
     ownedStack = await setupTestStack({
       features: [
         createTagsFeature({
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           // An extra row rule on the assignment row itself, unrelated to who
           // may see the host: the caller's claim must name the row's host type.
           ownership: {

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

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

package/src/tags/constants.ts

@@ -55,7 +55,7 @@ export const TagsQueries = {
 export const DEFAULT_TAG_ROLES = ["TenantAdmin", "TenantMember"] as const;
 
 // The default access rule applied to every tag handler when the app passes
-// neither `access` nor `roles`. createTagsFeature({ access: { openToAll: true } })
+// neither `access` nor `roles`. createTagsFeature({ access: { openToAll: { reason } } })
 // makes tagging reachable for any authenticated tenant user — matching apps
 // whose other handlers are openToAll rather than role-gated.
 export const DEFAULT_TAG_ACCESS: AccessRule = { roles: DEFAULT_TAG_ROLES };

package/src/tags/feature.ts

@@ -54,7 +54,7 @@ function registerTags(
   parents: readonly string[] | undefined,
 ): void {
   r.describe(
-    "Generic, host-agnostic tagging for any entity. Owns two event-sourced entities — the per-tenant `tag` catalog (`read_tags`, with optional `color` and `scope`) and `tag-assignment` join rows keyed by (entityType, entityId) (`read_tag_assignments`) — so tagging adds NO column to the host entity and needs no relational pivot or JOIN. Catalog screens are declarative (`entityList` + `entityEdit`) and use convention QNs `tag:{create,update,delete}`; TagManager/TagPicker keep `create-tag`/`update-tag`/`delete-tag`. Also: `assign-tag` (idempotent), `remove-tag` (idempotent) and list queries for the catalog and the assignments. Read which tags an entity has, or which entities carry a tag, by listing `tag-assignment` filtered on `entityId` or `tagId` and composing in the read-layer. A tag with empty `scope` is global; a `scope` of an entityType restricts it to that type in the picker. Every path uses one access rule — adopt the host's model with createTagsFeature({ access: { openToAll: true } }) or pin roles with createTagsFeature({ roles }). Pass { toggleable: { default: false } } to make the whole feature tier-gatable via the tier-engine (no host hook).",
+    "Generic, host-agnostic tagging for any entity. Owns two event-sourced entities — the per-tenant `tag` catalog (`read_tags`, with optional `color` and `scope`) and `tag-assignment` join rows keyed by (entityType, entityId) (`read_tag_assignments`) — so tagging adds NO column to the host entity and needs no relational pivot or JOIN. Catalog screens are declarative (`entityList` + `entityEdit`) and use convention QNs `tag:{create,update,delete}`; TagManager/TagPicker keep `create-tag`/`update-tag`/`delete-tag`. Also: `assign-tag` (idempotent), `remove-tag` (idempotent) and list queries for the catalog and the assignments. Read which tags an entity has, or which entities carry a tag, by listing `tag-assignment` filtered on `entityId` or `tagId` and composing in the read-layer. A tag with empty `scope` is global; a `scope` of an entityType restricts it to that type in the picker. Every path uses one access rule — adopt the host's model with createTagsFeature({ access: { openToAll: { reason } } }) or pin roles with createTagsFeature({ roles }). Pass { toggleable: { default: false } } to make the whole feature tier-gatable via the tier-engine (no host hook).",
   );
   r.uiHints({
     displayLabel: "Tags",
@@ -134,7 +134,7 @@ export const tagsFeature = defineFeature(TAGS_FEATURE_NAME, (r) =>
 
 export type TagsFeatureOptions = {
   /** Access rule for all tag write/read 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 tag (like the rest of its handlers), or
    *  { roles: ["Admin"] } for a custom role vocabulary. Takes precedence over `roles`. */
   readonly access?: AccessRule;

package/src/tenant/__tests__/tenant-timezone-boot.integration.test.ts

@@ -25,7 +25,7 @@ const probeFeature = defineFeature("tz-probe", (r) => {
     "read-tz",
     z.object({}),
     async (_event, ctx) => ({ isSuccess: true, data: { tenant: ctx.tz.tenant } }),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 
@@ -35,7 +35,7 @@ const probeFeature = defineFeature("tz-probe", (r) => {
 const queryProbeFeature = defineFeature("tz-cache-probe", (r) => {
   r.requires("tenant");
   r.queryHandler("read-tz", z.object({}), async (_query, ctx) => ({ tenant: ctx.tz.tenant }), {
-    access: { openToAll: true },
+    access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
   });
 });
 

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

@@ -401,7 +401,11 @@ describe("scenario 7: access rules on handlers", () => {
       "SystemAdmin",
     ]);
     expect(stack.registry.getQueryHandler(TenantQueries.me)?.access).toEqual({
-      openToAll: true,
+      openToAll: {
+        reason:
+          "any signed-in user reads only their own active tenant; the query is scoped " +
+          "to the caller's own tenantId",
+      },
     });
   });
 });

package/src/tenant/handlers/me.query.ts

@@ -9,7 +9,13 @@ import { tenantTable } from "../schema/tenant";
 export const meQuery = defineQueryHandler({
   name: "me",
   schema: z.object({}),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user reads only their own active tenant; the query is scoped " +
+        "to the caller's own tenantId",
+    },
+  },
   description:
     "Returns the record of the tenant the caller is currently signed in to, or null if it is gone; use it whenever the active tenant's own name, key or settings are needed.",
   handler: async (query, ctx) => {

package/src/user/handlers/me.query.ts

@@ -11,7 +11,13 @@ const crud = createEventStoreExecutor(userTable, userEntity, { entityName: "user
 export const meQuery = defineQueryHandler({
   name: "user:me",
   schema: z.object({}),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user reads only their own identity record; the detail lookup " +
+        "is by the caller's own id",
+    },
+  },
   description:
     "Returns the signed-in caller's own identity record, with the password hash stripped by field-level read access; use it whenever the current user's own profile data is needed.",
   handler: async (query, ctx) => {