@cosmicdrift/kumiko-bundled-features 0.270.0 → 0.273.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.270.0",
+  "version": "0.273.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.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",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.273.0",
+    "@cosmicdrift/kumiko-framework": "0.273.0",
+    "@cosmicdrift/kumiko-headless": "0.273.0",
+    "@cosmicdrift/kumiko-renderer": "0.273.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.273.0",
+    "@cosmicdrift/kumiko-types": "0.273.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.270.0",
-    "@cosmicdrift/kumiko-locale-es": "0.270.0"
+    "@cosmicdrift/kumiko-locale-de": "0.273.0",
+    "@cosmicdrift/kumiko-locale-es": "0.273.0"
   }
 }

package/src/__tests__/account-security-fixture.ts

@@ -24,6 +24,9 @@ export const accountSecurityFeature = defineFeature("account-security", (r) => {
   r.screen({
     id: ACCOUNT_SECURITY_SCREEN_ID,
     type: "dashboard",
+    // Test fixture demonstrating composition — a real app would nav this,
+    // but that's out of scope here.
+    dormant: true,
     panels: [
       {
         kind: "screen",

package/src/audit/__tests__/escape-hatch-audit.integration.test.ts

@@ -0,0 +1,96 @@
+// fw#2861 — createEscapeHatchAuditSink persists an escape-hatch-use event as
+// audit:event:escape-hatch-used, visible through the existing audit:query:list
+// handler. Real HTTP calls + setupTestStack — never createTestDispatcher.
+// Modelled on audit.integration.test.ts for users/tenant setup + resetEventStore.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { defineFeature, type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { z } from "zod";
+import { createConfigFeature } from "../../config";
+import { createTenantFeature } from "../../tenant";
+import { AuditQueries } from "../constants";
+import { createEscapeHatchAuditSink, ESCAPE_HATCH_USED_EVENT } from "../escape-hatch-audit-sink";
+import { createAuditFeature } from "../feature";
+
+const UNSAFE_RAW_REASON = "fw#2861 bundled-features integration test — declared unsafeRaw write";
+
+const probeFeature = defineFeature("escape-hatch-audit-sink-probe", (r) => {
+  r.writeHandler(
+    "unsafe-raw-write",
+    z.object({}),
+    async (_event, ctx) => {
+      ctx.db.unsafeRaw(UNSAFE_RAW_REASON);
+      return { isSuccess: true as const, data: { ok: true } };
+    },
+    { access: { roles: ["User"] }, escapeHatch: { reason: UNSAFE_RAW_REASON } },
+  );
+});
+
+let stack: TestStack;
+
+const tenantId = testTenantId(1);
+const user: SessionUser = createTestUser({ id: 9, tenantId, roles: ["User"] });
+const adminOfSameTenant: SessionUser = createTestUser({ id: 10, tenantId, roles: ["Admin"] });
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [probeFeature, createConfigFeature(), createTenantFeature(), createAuditFeature()],
+    extraContext: ({ db }) => ({ _escapeHatchAuditSink: createEscapeHatchAuditSink({ db }) }),
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await resetEventStore(stack);
+});
+
+type AuditRow = {
+  id: string;
+  type: string;
+  createdBy: string;
+  payload: Record<string, unknown>;
+};
+
+type AuditResponse = { rows: AuditRow[]; nextBefore: string | null };
+
+async function pollForEscapeHatchRow(): Promise<AuditRow> {
+  const deadline = Date.now() + 2000;
+  while (Date.now() < deadline) {
+    const res = await stack.http.queryOk<AuditResponse>(
+      AuditQueries.list,
+      { eventType: ESCAPE_HATCH_USED_EVENT },
+      adminOfSameTenant,
+    );
+    const row = res.rows[0];
+    if (row) return row;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  throw new Error("escape-hatch-used audit row did not appear within 2s");
+}
+
+describe("createEscapeHatchAuditSink — persists audit:event:escape-hatch-used", () => {
+  test("an unsafeRaw use is queryable via audit:query:list", async () => {
+    await stack.http.writeOk("escape-hatch-audit-sink-probe:write:unsafe-raw-write", {}, user);
+
+    const row = await pollForEscapeHatchRow();
+
+    expect(row.type).toBe(ESCAPE_HATCH_USED_EVENT);
+    expect(row.createdBy).toBe(user.id);
+    expect(row.payload).toEqual({
+      handler: "escape-hatch-audit-sink-probe:write:unsafe-raw-write",
+      kind: "unsafe-raw",
+      reason: UNSAFE_RAW_REASON,
+      actor: user.id,
+    });
+  });
+});

package/src/audit/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.271.0",
+    "type": "improvement",
+    "title": "escapeHatchUsedSchema.kind accepts the new unsafe-all-tenants EscapeHatchKind (fw#2913).",
+    "detail": "`escapeHatchUsedSchema.kind` (`audit/escape-hatch-audit-sink.ts`) now also accepts `\"unsafe-all-tenants\"`, keeping the `satisfies readonly EscapeHatchKind[]` tuple in sync with the framework's new `EscapeHatchKind` member for a granted `ctx.queryProjection(qn, { unsafeAllTenants: true })` call — see the framework changelog for fw#2913. No consumer action needed; existing sinks already accept any `EscapeHatchKind`."
+  },
+  {
+    "version": "0.271.0",
+    "type": "improvement",
+    "title": "New escape-hatch-used audit sink: createEscapeHatchAuditSink records security:escape-hatch-used as audit:event:escape-hatch-used (fw#2861).",
+    "detail": "New `createEscapeHatchAuditSink({ db })` (`@cosmicdrift/kumiko-bundled-features/audit`) implements the framework's `EscapeHatchAuditSink` — it parses each escape-hatch-use event against the new `escapeHatchUsedSchema` and appends it as an `audit:event:escape-hatch-used` event (`r.defineEvent(\"escape-hatch-used\", ...)`, `piiFields: \"none\"`) on the unbound pool, so the entry survives a rollback of the handler that triggered it. `server-runtime`'s `buildBootExtraContext` wires it as `AppContext._escapeHatchAuditSink` automatically whenever the `audit` feature is mounted; without the feature, escape-hatch uses fall back to a structured warn log. Events show up in the existing `audit:query:list`/`audit-log` screen like any other event."
+  },
   {
     "version": "0.241.0",
     "type": "breaking",

package/src/audit/escape-hatch-audit-sink.ts

@@ -0,0 +1,52 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { EscapeHatchAuditSink, EscapeHatchKind } from "@cosmicdrift/kumiko-framework/engine";
+import { append } from "@cosmicdrift/kumiko-framework/event-store";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { z } from "zod";
+
+export const ESCAPE_HATCH_USED_EVENT = "audit:event:escape-hatch-used";
+export const ESCAPE_HATCH_USE_AGGREGATE_TYPE = "escapeHatchUse";
+
+// Kept as a tuple so `satisfies` catches a kind added/removed/renamed on
+// EscapeHatchKind without this schema following along.
+const escapeHatchKinds = [
+  "unsafe-raw",
+  "acknowledge-cross-tenant",
+  "global-write",
+  "identity-switch",
+  "unsafe-all-tenants",
+] as const satisfies readonly EscapeHatchKind[];
+
+export const escapeHatchUsedSchema = z.object({
+  handler: z.string(),
+  kind: z.enum(escapeHatchKinds),
+  reason: z.string(),
+  actor: z.string(),
+  targetUserId: z.string().optional(),
+  targetTenantId: z.string().optional(),
+});
+
+export function createEscapeHatchAuditSink(opts: {
+  readonly db: DbConnection;
+}): EscapeHatchAuditSink {
+  return async (event) => {
+    const payload = escapeHatchUsedSchema.parse({
+      handler: event.handler,
+      kind: event.kind,
+      reason: event.reason,
+      actor: event.actor,
+      ...(event.target && { targetUserId: event.target.id, targetTenantId: event.target.tenantId }),
+    });
+    // Appends on the unbound pool, never the handler tx — an audit entry must
+    // survive a rollback of the handler that used the hatch.
+    await append(opts.db, {
+      aggregateId: generateId(),
+      aggregateType: ESCAPE_HATCH_USE_AGGREGATE_TYPE,
+      tenantId: event.tenantId,
+      expectedVersion: 0,
+      type: ESCAPE_HATCH_USED_EVENT,
+      payload,
+      metadata: { userId: event.actor },
+    });
+  };
+}

package/src/audit/feature.ts

@@ -5,6 +5,7 @@ import {
   i18nKey,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { AUDIT_LOG_DETAIL_SCREEN_ID, AUDIT_LOG_SCREEN_ID, AuditQueries } from "./constants";
+import { escapeHatchUsedSchema } from "./escape-hatch-audit-sink";
 import { detailsQuery } from "./handlers/details.query";
 import { listQuery } from "./handlers/list.query";
 import { AUDIT_I18N } from "./i18n";
@@ -24,7 +25,7 @@ import { AUDIT_I18N } from "./i18n";
 export function createAuditFeature(): FeatureDefinition {
   return defineFeature("audit", (r) => {
     r.describe(
-      "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection \u2014 the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range.",
+      "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection \u2014 the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).",
     );
     r.uiHints({
       displayLabel: "Audit Log",
@@ -35,6 +36,9 @@ export function createAuditFeature(): FeatureDefinition {
     // Screens resolve actor names via tenant:query:members.
     r.requires("tenant");
 
+    // Registered so ops tools/MSPs can discover the type — escape-hatch-audit-sink.ts appends it via the low-level event-store API.
+    r.defineEvent("escape-hatch-used", escapeHatchUsedSchema, { piiFields: "none" });
+
     const queries = {
       list: r.queryHandler(listQuery),
       details: r.queryHandler(detailsQuery),

package/src/audit/index.ts

@@ -1,2 +1,3 @@
 export { AUDIT_FEATURE, AuditQueries } from "./constants";
+export { createEscapeHatchAuditSink, ESCAPE_HATCH_USED_EVENT } from "./escape-hatch-audit-sink";
 export { createAuditFeature } from "./feature";

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-mfa/screens.ts

@@ -10,13 +10,6 @@ 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
@@ -30,9 +23,13 @@ export const mfaEnableScreen: SecretMintScreenDefinition = {
   submitLabel: i18nKey("mfa.enable.start"),
   access: {
     openToAll: {
-      reason: MFA_ENABLE_OPEN_REASON,
+      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: {
@@ -86,9 +83,12 @@ export const mfaDisableScreen: ActionFormScreenDefinition = {
   cancelTarget: false,
   access: {
     openToAll: {
-      reason: MFA_DISABLE_OPEN_REASON,
+      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.",
 };
@@ -103,9 +103,13 @@ export const mfaRegenerateRecoveryScreen: SecretMintScreenDefinition = {
   cancelTarget: false,
   access: {
     openToAll: {
-      reason: MFA_REGENERATE_RECOVERY_OPEN_REASON,
+      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: {