@cosmicdrift/kumiko-bundled-features 0.269.2 → 0.273.0

package/src/auth-email-password/__tests__/query-as-member.integration.test.ts

@@ -3,6 +3,8 @@
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
+import type { SchemaTable } from "@cosmicdrift/kumiko-framework/db";
+import { asRawClient, entityTableFromRegistry, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import type { HandlerContext, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   createEntity,
@@ -67,6 +69,9 @@ const noteEntity = createEntity({
   },
 });
 
+// Needs stack.registry — assigned in beforeAll.
+let noteTable: SchemaTable;
+
 const hookNoteAEntity = createEntity({
   table: "qam_hook_note_a",
   fields: { label: createTextField({ personal: false, reason: "test_fixture", required: true }) },
@@ -94,6 +99,13 @@ const TRIES_WRITE_QN = "queryasmemberprobe:query:tries-write";
 const TRIES_APPEND_EVENT_QN = "queryasmemberprobe:query:tries-append-event";
 const TRIES_FETCH_FOR_WRITING_QN = "queryasmemberprobe:query:tries-fetch-for-writing";
 const TRIES_JOB_RUNNER_QN = "queryasmemberprobe:query:tries-job-runner";
+const TRIES_DB_WRITE_QN = "queryasmemberprobe:query:tries-db-write";
+const TRIES_UNSAFE_RAW_WRITE_QN = "queryasmemberprobe:query:tries-unsafe-raw-write";
+const TRIES_READ_WRITE_RESET_QN = "queryasmemberprobe:query:tries-read-write-reset";
+const NESTED_DB_WRITE_QN = "queryasmemberprobe:query:nested-db-write";
+const TRIES_SELECT_FOR_UPDATE_QN = "queryasmemberprobe:query:tries-select-for-update";
+const TRIES_QUERY_AS_QN = "queryasmemberprobe:query:tries-query-as";
+const READ_AS_MEMBER_QUERY_QN = "queryasmemberprobe:query:read-as-member-query";
 const SYSTEM_SCOPE_READ_AS_MEMBER_QN = "queryasmembersystemscope:write:read-as-member";
 
 const probeFeature = defineFeature("queryasmemberprobe", (r) => {
@@ -170,6 +182,88 @@ const probeFeature = defineFeature("queryasmemberprobe", (r) => {
     { access: { roles: ["Admin", "User"] } },
   );
 
+  // ctx.db stays available to a resolved member; these targets write through it.
+  r.queryHandler(
+    "tries-db-write",
+    z.object({}),
+    async (query, ctx) => {
+      await ctx.db.updateMany(noteTable, { body: "tampered" }, { tenantId: query.user.tenantId });
+      return { ok: true };
+    },
+    { access: { roles: ["Admin", "User"] } },
+  );
+  r.queryHandler(
+    "tries-unsafe-raw-write",
+    z.object({}),
+    async (_query, ctx) => {
+      await asRawClient(ctx.db.unsafeRaw("test: raw write probe")).unsafe(
+        "UPDATE qam_notes SET body = 'tampered'",
+      );
+      return { ok: true };
+    },
+    {
+      access: { roles: ["Admin", "User"] },
+      escapeHatch: { reason: "test: raw write probe" },
+    },
+  );
+  r.queryHandler(
+    "tries-read-write-reset",
+    z.object({}),
+    async (_query, ctx) => {
+      const raw = asRawClient(ctx.db.unsafeRaw("test: raw write probe"));
+      await raw.unsafe("SET TRANSACTION READ WRITE");
+      await raw.unsafe("UPDATE qam_notes SET body = 'tampered'");
+      return { ok: true };
+    },
+    {
+      access: { roles: ["Admin", "User"] },
+      escapeHatch: { reason: "test: raw write probe" },
+    },
+  );
+  r.queryHandler(
+    "nested-db-write",
+    z.object({}),
+    async (_query, ctx) => ctx.query(TRIES_DB_WRITE_QN, {}),
+    { access: { roles: ["Admin", "User"] } },
+  );
+  r.queryHandler(
+    "tries-select-for-update",
+    z.object({}),
+    async (_query, ctx) => {
+      const rows = await asRawClient(ctx.db.unsafeRaw("test: select-for-update probe")).unsafe(
+        "SELECT id FROM qam_notes FOR UPDATE",
+      );
+      return { ok: true, count: Array.isArray(rows) ? rows.length : 0 };
+    },
+    {
+      access: { roles: ["Admin", "User"] },
+      escapeHatch: { reason: "test: select-for-update probe" },
+    },
+  );
+  r.queryHandler(
+    "tries-query-as",
+    z.object({}),
+    async (query, ctx) => ctx.queryAs({ ...query.user, origin: undefined }, WHOAMI_QN, {}),
+    {
+      access: { roles: ["Admin", "User"] },
+      escapeHatch: { reason: "test: query-as identity switch probe" },
+    },
+  );
+  r.queryHandler(
+    "read-as-member-query",
+    z.object({
+      userId: z.string(),
+      targetQn: z.string(),
+      payload: z.record(z.string(), z.unknown()).default({}),
+    }),
+    async (query, ctx) =>
+      ctx.queryAsMember(query.payload.userId, query.payload.targetQn, query.payload.payload),
+    {
+      access: { roles: ["Admin"] },
+      escapeHatch: { reason: "test: reads as a stored member via a query caller" },
+    },
+  );
+
   // Caller-facing write handler that reads as a member — WITH and WITHOUT
   // escapeHatch (systemIdentitySwitchDenied gate).
   r.writeHandler(
@@ -226,6 +320,22 @@ const probeFeature = defineFeature("queryasmemberprobe", (r) => {
     },
     { access: { roles: ["Admin"] }, escapeHatch: { reason: "test: two-user cache check" } },
   );
+  r.writeHandler(
+    "read-as-member-then-write",
+    z.object({ userId: z.string() }),
+    async (event, ctx) => {
+      await ctx.queryAsMember(event.payload.userId, NOTE_LIST_QN, {});
+      const result = await ctx.write("queryasmemberprobe:write:note:create", {
+        ownerId: event.payload.userId,
+        body: "after-read",
+      });
+      if (!result.isSuccess) {
+        throw new Error(`nested write after queryAsMember failed: ${JSON.stringify(result.error)}`);
+      }
+      return { isSuccess: true as const, data: { ok: true } };
+    },
+    { access: { roles: ["Admin"] }, escapeHatch: { reason: "test: read-then-write probe" } },
+  );
 
   // authClaims — counter parity with cache + real-login-claims check.
   r.authClaims(async (user) => {
@@ -330,6 +440,7 @@ beforeAll(async () => {
   await unsafeCreateEntityTable(stack.db, tenantEntity);
   await unsafeCreateEntityTable(stack.db, tenantComplianceProfileEntity);
   await unsafeCreateEntityTable(stack.db, noteEntity);
+  noteTable = entityTableFromRegistry(stack.registry, "note", noteEntity);
   await unsafeCreateEntityTable(stack.db, hookNoteAEntity);
   await unsafeCreateEntityTable(stack.db, hookNoteBEntity);
   await unsafePushTables(stack.db, { configValuesTable, tenantMembershipsTable });
@@ -417,6 +528,27 @@ async function createNote(ownerId: string, body: string): Promise<void> {
   await stack.http.writeOk("queryasmemberprobe:write:note:create", { ownerId, body }, admin);
 }
 
+async function readAsMemberViaQuery<T = unknown>(
+  userId: string,
+  targetQn: string,
+  payload: Record<string, unknown> = {},
+): Promise<T> {
+  return stack.http.queryOk<T>(READ_AS_MEMBER_QUERY_QN, { userId, targetQn, payload }, admin);
+}
+
+async function readAsMemberViaQueryErr(
+  userId: string,
+  targetQn: string,
+  payload: Record<string, unknown> = {},
+) {
+  return stack.http.queryErr(READ_AS_MEMBER_QUERY_QN, { userId, targetQn, payload }, admin);
+}
+
+async function readNoteBodies(): Promise<readonly string[]> {
+  const rows = await selectMany<{ body: string }>(stack.db, noteTable);
+  return [...rows.map((row) => row.body)].sort();
+}
+
 // ── 1. Ownership — reading as a member applies THEIR row filters ──────────
 
 describe("ctx.queryAsMember — ownership rules of the resolved member apply", () => {
@@ -722,6 +854,16 @@ describe("ctx.queryAsMember — the resolved principal is read-only (no writeAsM
     expect(errorReason(err.details)).toBe("member_resolution_read_only");
   });
 
+  test("target query handler calling ctx.queryAs → denied with member_resolution_read_only", async () => {
+    await createTenant(TENANT_A);
+    const userId = await createUser("triesQueryAs@example.com", "pw-long-enough-33");
+    await addMembership(userId, TENANT_A);
+
+    const err = await readAsMemberErr(userId, TRIES_QUERY_AS_QN);
+    expect(err.code).toBe("access_denied");
+    expect(errorReason(err.details)).toBe("member_resolution_read_only");
+  });
+
   test("stack.dispatcher.write called directly with a resolved-like user (origin set) → denied", async () => {
     await createTenant(TENANT_A);
     const userId = await createUser("directdispatch@example.com", "pw-long-enough-21");
@@ -745,3 +887,164 @@ describe("ctx.queryAsMember — the resolved principal is read-only (no writeAsM
     }
   });
 });
+
+// ── 7. Database-level read-only — the resolved principal's Postgres tx is
+//      itself READ ONLY, so even a raw ctx.db/unsafeRaw write is rejected ──
+
+describe("ctx.queryAsMember — database-level read-only (READ ONLY transaction)", () => {
+  beforeEach(async () => {
+    await resetTestTables(stack.db, [noteTable]);
+  });
+
+  test("a) tries-db-write via a write-caller (savepoint path) is denied, notes unchanged", async () => {
+    await createTenant(TENANT_A);
+    const userId = await createUser("dbwrite-write@example.com", "pw-long-enough-22");
+    await addMembership(userId, TENANT_A);
+    await createNote(userId, "note-1");
+    await createNote(userId, "note-2");
+
+    const err = await readAsMemberErr(userId, TRIES_DB_WRITE_QN);
+    expect(err.code).toBe("access_denied");
+    expect(errorReason(err.details)).toBe("member_resolution_read_only");
+    expect(await readNoteBodies()).toEqual(["note-1", "note-2"]);
+  });
+
+  test("b) tries-db-write via a query-caller (pool path) is denied, notes unchanged", async () => {
+    await createTenant(TENANT_A);
+    const userId = await createUser("dbwrite-query@example.com", "pw-long-enough-23");
+    await addMembership(userId, TENANT_A);
+    await createNote(userId, "note-1");
+
+    const err = await readAsMemberViaQueryErr(userId, TRIES_DB_WRITE_QN);
+    expect(err.code).toBe("access_denied");
+    expect(errorReason(err.details)).toBe("member_resolution_read_only");
+    expect(await readNoteBodies()).toEqual(["note-1"]);
+  });
+
+  test("c1) tries-unsafe-raw-write via a write-caller (savepoint path) is denied, notes unchanged", async () => {
+    await createTenant(TENANT_A);
+    const userId = await createUser("rawwrite-write@example.com", "pw-long-enough-24");
+    await addMembership(userId, TENANT_A);
+    await createNote(userId, "note-1");
+
+    const err = await readAsMemberErr(userId, TRIES_UNSAFE_RAW_WRITE_QN);
+    expect(err.code).toBe("access_denied");
+    expect(errorReason(err.details)).toBe("member_resolution_read_only");
+    expect(await readNoteBodies()).toEqual(["note-1"]);
+  });
+
+  test("c2) tries-unsafe-raw-write via a query-caller (pool path) is denied, notes unchanged", async () => {
+    await createTenant(TENANT_A);
+    const userId = await createUser("rawwrite-query@example.com", "pw-long-enough-25");
+    await addMembership(userId, TENANT_A);
+    await createNote(userId, "note-1");
+
+    const err = await readAsMemberViaQueryErr(userId, TRIES_UNSAFE_RAW_WRITE_QN);
+    expect(err.code).toBe("access_denied");
+    expect(errorReason(err.details)).toBe("member_resolution_read_only");
+    expect(await readNoteBodies()).toEqual(["note-1"]);
+  });
+
+  test("d1) tries-read-write-reset via a write-caller: request fails, notes unchanged", async () => {
+    await createTenant(TENANT_A);
+    const userId = await createUser("resetwrite-write@example.com", "pw-long-enough-26");
+    await addMembership(userId, TENANT_A);
+    await createNote(userId, "note-1");
+
+    // SQLSTATE 25001, not 25006 — surfaces as internal_error rather than member_resolution_read_only.
+    const err = await readAsMemberErr(userId, TRIES_READ_WRITE_RESET_QN);
+    expect(err.code).toBe("internal_error");
+    expect(await readNoteBodies()).toEqual(["note-1"]);
+  });
+
+  test("d2) tries-read-write-reset via a query-caller: request fails, notes unchanged", async () => {
+    await createTenant(TENANT_A);
+    const userId = await createUser("resetwrite-query@example.com", "pw-long-enough-27");
+    await addMembership(userId, TENANT_A);
+    await createNote(userId, "note-1");
+
+    const err = await readAsMemberViaQueryErr(userId, TRIES_READ_WRITE_RESET_QN);
+    expect(err.code).toBe("internal_error");
+    expect(await readNoteBodies()).toEqual(["note-1"]);
+  });
+
+  test("e) nested-db-write via a write-caller → denied with member_resolution_read_only, notes unchanged", async () => {
+    await createTenant(TENANT_A);
+    const userId = await createUser("nesteddbwrite@example.com", "pw-long-enough-28");
+    await addMembership(userId, TENANT_A);
+    await createNote(userId, "note-1");
+
+    const err = await readAsMemberErr(userId, NESTED_DB_WRITE_QN);
+    expect(err.code).toBe("access_denied");
+    expect(errorReason(err.details)).toBe("member_resolution_read_only");
+    expect(await readNoteBodies()).toEqual(["note-1"]);
+  });
+
+  test("e2) nested-db-write via a query-caller (pool path) → denied with member_resolution_read_only, notes unchanged", async () => {
+    await createTenant(TENANT_A);
+    const userId = await createUser("nesteddbwritequery@example.com", "pw-long-enough-34");
+    await addMembership(userId, TENANT_A);
+    await createNote(userId, "note-1");
+
+    const err = await readAsMemberViaQueryErr(userId, NESTED_DB_WRITE_QN);
+    expect(err.code).toBe("access_denied");
+    expect(errorReason(err.details)).toBe("member_resolution_read_only");
+    expect(await readNoteBodies()).toEqual(["note-1"]);
+  });
+
+  test("f) note:list via a query-caller (pool path) returns only the resolved member's own rows", async () => {
+    await createTenant(TENANT_A);
+    const userA = await createUser("dblist-a@example.com", "pw-long-enough-29");
+    const userB = await createUser("dblist-b@example.com", "pw-long-enough-30");
+    await addMembership(userA, TENANT_A);
+    await addMembership(userB, TENANT_A);
+    await createNote(userA, "a-note-1");
+    await createNote(userB, "b-note-1");
+
+    const result = await readAsMemberViaQuery<{ rows: Array<{ ownerId: string }> }>(
+      userA,
+      NOTE_LIST_QN,
+    );
+    expect(result.rows).toHaveLength(1);
+    expect(result.rows[0]?.ownerId).toBe(userA);
+  });
+
+  test("g) tries-db-write via the normal dispatch path (no queryAsMember) succeeds, updates every row", async () => {
+    await createTenant(TENANT_A);
+    const userId = await createUser("directwrite@example.com", "pw-long-enough-31");
+    await addMembership(userId, TENANT_A);
+    await createNote(userId, "note-1");
+    await createNote(userId, "note-2");
+
+    const result = await stack.http.queryOk<{ ok: boolean }>(TRIES_DB_WRITE_QN, {}, admin);
+    expect(result.ok).toBe(true);
+    expect(await readNoteBodies()).toEqual(["tampered", "tampered"]);
+  });
+
+  test("h) read-as-member-then-write: a read via queryAsMember followed by a normal write succeeds", async () => {
+    await createTenant(TENANT_A);
+    const userId = await createUser("readthenwrite@example.com", "pw-long-enough-32");
+    await addMembership(userId, TENANT_A);
+    await createNote(userId, "existing-note");
+
+    const result = await stack.http.writeOk<{ ok: boolean }>(
+      "queryasmemberprobe:write:read-as-member-then-write",
+      { userId },
+      admin,
+    );
+    expect(result.ok).toBe(true);
+    expect(await readNoteBodies()).toEqual(["after-read", "existing-note"]);
+  });
+
+  test("i) tries-select-for-update via a query-caller (pool path) is denied, notes unchanged", async () => {
+    await createTenant(TENANT_A);
+    const userId = await createUser("selectforupdate-query@example.com", "pw-long-enough-35");
+    await addMembership(userId, TENANT_A);
+    await createNote(userId, "note-1");
+
+    const err = await readAsMemberViaQueryErr(userId, TRIES_SELECT_FOR_UPDATE_QN);
+    expect(err.code).toBe("access_denied");
+    expect(errorReason(err.details)).toBe("member_resolution_read_only");
+    expect(await readNoteBodies()).toEqual(["note-1"]);
+  });
+});

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

@@ -21,7 +21,15 @@ export const mfaEnableScreen: SecretMintScreenDefinition = {
   fields: {},
   layout: { sections: [] },
   submitLabel: i18nKey("mfa.enable.start"),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user may enroll their own account in MFA, mirroring the enable-start handler",
+    },
+  },
+  // Reached only via a direct link from account settings, never from a
+  // list — no nav area to resolve in isolation.
+  dormant: true,
   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 +81,14 @@ export const mfaDisableScreen: ActionFormScreenDefinition = {
   submitLabel: i18nKey("mfa.disable.submit"),
   submitStyle: "danger",
   cancelTarget: false,
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason: "each signed-in user may turn off their own MFA, mirroring the disable handler",
+    },
+  },
+  // Reached only via a direct link from account settings, never from a
+  // list — no nav area to resolve in isolation.
+  dormant: true,
   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,15 @@ export const mfaRegenerateRecoveryScreen: SecretMintScreenDefinition = {
   layout: { sections: [{ fields: ["code"] }] },
   submitLabel: i18nKey("mfa.regenerate.submit"),
   cancelTarget: false,
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user may regenerate their own recovery codes, mirroring the regenerate-recovery handler",
+    },
+  },
+  // Reached only via a direct link from account settings, never from a
+  // list — no nav area to resolve in isolation.
+  dormant: true,
   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/cap-counter/feature.ts

@@ -66,8 +66,6 @@ import {
 import { markSoftWarnedHandler } from "./handlers/mark-soft-warned.write";
 import { CAP_COUNTER_I18N } from "./i18n";
 
-const sysadminAccess = { access: { roles: access.systemAdmin }, crossTenant: true } as const;
-
 export const capCounterFeature = defineFeature(CAP_COUNTER_FEATURE, (r) => {
   r.describe(
     "Tracks per-tenant usage against configurable limits using two complementary storage models: calendar-period counters (one projection row per tenant/capName/period, reset implicitly by period rollover) and rolling-window counters (append-only event stream, no projection). Use `enforceCap` / `enforceRollingCap` (or the `withCapEnforcement` / `withRollingCapEnforcement` handler wrappers) in your write-handlers to check limits with soft-warn and hard-block tolerances; call `enforceCapAndMaybeNotify` when you also want to trigger a delivery notification on soft-threshold hits.",
@@ -100,7 +98,11 @@ export const capCounterFeature = defineFeature(CAP_COUNTER_FEATURE, (r) => {
   // über aggregate-id).
   r.queryHandler(
     defineEntityListHandler("cap-counter", capCounterEntity, {
-      ...sysadminAccess,
+      access: { roles: access.systemAdmin },
+      escapeHatch: {
+        reason:
+          "SystemAdmin quota operator view lists usage counters of every tenant to see who consumes which cap",
+      },
       description:
         "Lists usage-counter rows across all tenants with cap name, current value, period start and soft-warn timestamp; use it as the operator view of who is consuming which quota.",
     }),

package/src/cap-overview/screens.ts

@@ -66,6 +66,9 @@ export function createTenantCapListScreen(
     ],
     defaultSort: { field: "name", dir: "asc" },
     access: { roles: ["SystemAdmin"] },
+    // No nav wiring yet (see feature.ts header) — no nav area to resolve
+    // in isolation.
+    dormant: true,
   };
 }
 
@@ -80,6 +83,9 @@ export const myCapsScreen: ScreenDefinition = {
     },
   ],
   access: { roles: MY_CAPS_ACCESS_ROLES },
+  // No nav wiring yet (see feature.ts header) — no nav area to resolve in
+  // isolation.
+  dormant: true,
 };
 
 export const platformTenantCapsScreen: ScreenDefinition = {

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" } } },
   );
 });