@cosmicdrift/kumiko-bundled-features 0.197.1 → 0.199.0

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

@@ -1,3 +1,4 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import {
   type ConfigKeyType,
   type ConfigScope,
@@ -7,7 +8,7 @@ import {
   toKebab,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
-import { requireConfigResolver } from "../feature";
+import { requireConfigResolver, requireSystemDb } from "../feature";
 import { hasConfigAccess } from "../write-helpers";
 
 export type ReadinessMissingKey = {
@@ -32,18 +33,23 @@ export type RequiredKeyGate = (qualifiedName: string) => boolean;
 // Builds the per-tenant gate from r.extensionSelector declarations: resolve
 // each selector through the config cascade, mark every provider-feature
 // registered under that point as counted/uncounted. Features without a
-// selector-gated registration always count.
+// selector-gated registration always count. `db` is the caller's own scoped
+// handle — config's own handlers pass requireSystemDb's result, the plain
+// tenant-scoped readiness feature passes its own ctx.db. This function makes
+// no scope decision itself; see readiness/handlers/status.query.ts and
+// config/handlers/readiness.query.ts's own handler for the two call sites.
 export async function buildProviderSelectionGate(
   ctx: HandlerContext,
   callerQn: string,
   user: SessionUser,
+  db: TenantDb,
 ): Promise<RequiredKeyGate> {
   const resolver = requireConfigResolver(ctx, callerQn);
   const countsByFeature = new Map<string, boolean>();
   for (const [extensionName, selectorKey] of ctx.registry.getAllExtensionSelectors()) {
     const keyDef = ctx.registry.getConfigKey(selectorKey);
     if (!keyDef) continue; // registry-build already failed this; defensive
-    const value = await resolver.get(selectorKey, keyDef, user.tenantId, user.id, ctx.db);
+    const value = await resolver.get(selectorKey, keyDef, user.tenantId, user.id, db);
     const selected = typeof value === "string" ? value.trim() : "";
     for (const usage of ctx.registry.getExtensionUsages(extensionName)) {
       if (usage.featureName === undefined) continue;
@@ -65,6 +71,7 @@ export async function collectMissingRequiredConfig(
   ctx: HandlerContext,
   callerQn: string,
   user: SessionUser,
+  db: TenantDb,
   gate?: RequiredKeyGate,
   options?: {
     /** Verdict-Pfade (Rollup, selbst role-gated) MÜSSEN ungefiltert zählen:
@@ -75,7 +82,7 @@ export async function collectMissingRequiredConfig(
   },
 ): Promise<ReadinessMissingKey[]> {
   const resolver = requireConfigResolver(ctx, callerQn);
-  const effectiveGate = gate ?? (await buildProviderSelectionGate(ctx, callerQn, user));
+  const effectiveGate = gate ?? (await buildProviderSelectionGate(ctx, callerQn, user, db));
   // Kandidaten erst sammeln, dann EIN Batch-Resolve — die sequentielle
   // resolver.get-Schleife war ein N+1 über alle required Keys (272/1).
   type KeyDef =
@@ -98,7 +105,7 @@ export async function collectMissingRequiredConfig(
     candidates,
     user.tenantId,
     user.id,
-    ctx.db,
+    db,
     ctx.secrets,
   );
   for (const [qualifiedKey, keyDef] of candidates) {
@@ -124,7 +131,13 @@ export const readinessQuery = defineQueryHandler({
   // Per-key read access enforced via hasConfigAccess inside the handler.
   access: { openToAll: true },
   handler: async (query, ctx) => {
-    const missing = await collectMissingRequiredConfig(ctx, "config:query:readiness", query.user);
+    const db = requireSystemDb(ctx, "config:query:readiness", query.user.tenantId);
+    const missing = await collectMissingRequiredConfig(
+      ctx,
+      "config:query:readiness",
+      query.user,
+      db,
+    );
     return { missing };
   },
 });

package/src/config/handlers/reencrypt.job.ts

@@ -15,15 +15,28 @@
 // so each rotation appends a normal `.updated` event whose payload carries
 // the NEW envelope: after a full run even a from-scratch rebuild only
 // ever sees the current-KEK envelope.
+//
+// systemScope() fail-closed pattern (framework#2056): the initial scan is
+// intentionally cross-tenant (system-wide key rotation), acknowledged via
+// UncheckedSystemDb.acknowledgeCrossTenant(). Rows are bucketed by tenant,
+// and assertRowsTenant() re-verifies each row against its bucket's tenant
+// right before the write — both checks are built locally from the exported
+// createUncheckedSystemDb().
 
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   createEventStoreExecutor,
   createTenantDb,
+  createUncheckedSystemDb,
   type DbConnection,
   type TenantDb,
+  type UncheckedSystemDb,
 } from "@cosmicdrift/kumiko-framework/db";
-import type { JobHandlerFn, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type JobHandlerFn,
+  type SessionUser,
+  SYSTEM_TENANT_ID,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
 import {
@@ -104,6 +117,22 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
     return existing;
   }
 
+  const sdbCache = new Map<TenantId, UncheckedSystemDb>();
+  function sdbFor(tenantId: TenantId): UncheckedSystemDb {
+    let existing = sdbCache.get(tenantId);
+    if (!existing) {
+      existing = createUncheckedSystemDb(tdbFor(tenantId));
+      sdbCache.set(tenantId, existing);
+    }
+    return existing;
+  }
+
+  // Standalone from sdbCache/tdbCache on purpose: this one is only ever used
+  // to acknowledge the cross-tenant scan below, never bound to a real
+  // tenant's writes — sharing it with sdbFor(SYSTEM_TENANT_ID) would make a
+  // write-path cache entry double as the scan's ack gate.
+  const scanDb = createUncheckedSystemDb(createTenantDb(db, SYSTEM_TENANT_ID, "system"));
+
   type ConfigRow = {
     id: string;
     key: string;
@@ -115,27 +144,51 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
   let alreadyCurrent = 0;
   const targetVersion = provider.currentVersion();
 
+  type BucketedRow = { tenantId: TenantId; row: ConfigRow };
+
   // ponytail: one full candidate scan — config rows are operator-scale
   // (tenants × encrypted keys), cursor pagination when that ever changes.
-  // Served to the shared loop in slices so its deadline/signal/failure
-  // checks run between chunks, not only once.
-  let pending: ConfigRow[] | undefined;
-  async function nextBatch(): Promise<readonly ConfigRow[]> {
-    if (pending === undefined) {
-      pending =
-        encryptedKeys.length === 0
-          ? []
-          : [
-              ...(await selectMany<ConfigRow>(db, configValuesTable, {
-                key: { in: encryptedKeys },
-              })),
-            ];
+  // Bucketed by tenant so each row keeps its bucket's tenant attached
+  // (assertRowsTenant below re-checks that against the row's own field
+  // right before the write) and the shared loop's deadline/signal/failure
+  // checks still run between chunks, not only once.
+  let buckets: Map<TenantId, ConfigRow[]> | undefined;
+  async function loadBuckets(): Promise<Map<TenantId, ConfigRow[]>> {
+    if (buckets) return buckets;
+    const grouped = new Map<TenantId, ConfigRow[]>();
+    if (encryptedKeys.length > 0) {
+      const scanned = await scanDb
+        .acknowledgeCrossTenant("system-wide key rotation")
+        .selectMany<ConfigRow>(configValuesTable, { key: { in: encryptedKeys } });
+      for (const row of scanned) {
+        const tenantId = row.tenantId as TenantId; // @cast-boundary db-row
+        const bucket = grouped.get(tenantId);
+        if (bucket) bucket.push(row);
+        else grouped.set(tenantId, [row]);
+      }
+    }
+    buckets = grouped;
+    return buckets;
+  }
+
+  async function nextBatch(): Promise<readonly BucketedRow[]> {
+    const grouped = await loadBuckets();
+    for (const [tenantId, rows] of grouped) {
+      if (rows.length === 0) {
+        grouped.delete(tenantId);
+        continue;
+      }
+      const slice = rows.splice(0, SCAN_SLICE_SIZE);
+      if (rows.length === 0) grouped.delete(tenantId);
+      return slice.map((row) => ({ tenantId, row }));
     }
-    const slice = pending;
-    return slice.splice(0, SCAN_SLICE_SIZE);
+    return [];
   }
 
-  async function migrateRow(row: ConfigRow): Promise<"migrated" | "skipped" | "failed"> {
+  async function migrateRow({
+    tenantId,
+    row,
+  }: BucketedRow): Promise<"migrated" | "skipped" | "failed"> {
     if (row.value === null || row.value === undefined) return "skipped";
     const classification = classifyStoredEnvelope(row.value, targetVersion);
     if (classification === "current") {
@@ -154,7 +207,12 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
       return "failed";
     }
 
-    const tenantId = row.tenantId as TenantId; // @cast-boundary db-row
+    // Re-verify the row's own tenantId against the bucket it was scanned
+    // into, right before the write (framework#2072) — a mismatch here
+    // fails this row only (via onRowError below), it does not abort the
+    // whole job.
+    sdbFor(tenantId).assertRowsTenant([row], "tenantId");
+
     const plaintext = await cipher.decrypt(row.value, { tenantId });
     const reencrypted = await cipher.encrypt(plaintext, { tenantId });
 
@@ -177,13 +235,13 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
     return "migrated";
   }
 
-  const outcome = await runChunkedMigration<ConfigRow>({
+  const outcome = await runChunkedMigration<BucketedRow>({
     nextBatch,
     migrateRow,
     maxFailures,
     deadlineAt: deadline,
     signal: ctx.signal,
-    onRowError: (row, err) => {
+    onRowError: ({ row }, err) => {
       ctx.log?.warn?.(`[config:reencrypt] failed to re-encrypt row ${row.id}`, { err });
     },
   });

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

@@ -6,7 +6,7 @@ import {
   isEncryptedAtRest,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
-import { requireConfigResolver } from "../feature";
+import { requireConfigResolver, requireSystemDb } from "../feature";
 import { MASKED, redactInheritedCascade, shouldRedactInherited } from "../read-redaction";
 import { hasConfigAccess } from "../write-helpers";
 
@@ -16,7 +16,7 @@ export const valuesQuery = defineQueryHandler({
   // Per-key read access enforced via hasConfigAccess inside the handler.
   access: { openToAll: true },
   handler: async (query, ctx) => {
-    const db = ctx.db;
+    const db = requireSystemDb(ctx, "config:query:values", query.user.tenantId);
     const registry = ctx.registry;
     const resolver = requireConfigResolver(ctx, "config:query:values");
 

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

@@ -15,13 +15,32 @@ describe("delivery screens + handler access alignment", () => {
     const delivery = createDeliveryFeature();
     const screen = delivery.screens[DELIVERY_LOG_SCREEN_ID];
     expect(screen?.type).toBe("custom");
-    if (screen && "access" in screen && screen.access && "roles" in screen.access) {
-      expect(screen.access.roles).toEqual(access.admin);
-    }
+    expect(rolesOf(screen?.access)).toEqual([...access.admin]);
   });
 
   test("delivery log handler shares access.admin", () => {
     const delivery = createDeliveryFeature();
     expect(rolesOf(delivery.queryHandlers["log"]?.access)).toEqual([...access.admin]);
   });
+
+  test("access option narrows the delivery-log screen and its log handler together (#2033)", () => {
+    const delivery = createDeliveryFeature({ access: access.systemAdmin });
+    const screen = delivery.screens[DELIVERY_LOG_SCREEN_ID];
+    expect(rolesOf(screen?.access)).toEqual([...access.systemAdmin]);
+    expect(rolesOf(delivery.queryHandlers["log"]?.access)).toEqual([...access.systemAdmin]);
+  });
+
+  test("access option leaves the preferences handler openToAll — that's per-user, not an admin surface", () => {
+    const delivery = createDeliveryFeature({ access: access.systemAdmin });
+    const preferencesAccess = delivery.queryHandlers["preferences"]?.access;
+    expect(
+      preferencesAccess && "openToAll" in preferencesAccess && preferencesAccess.openToAll,
+    ).toBe(true);
+  });
+
+  test("boot-validates with a narrowed access option", () => {
+    expect(() =>
+      validateBoot([createDeliveryFeature({ access: access.systemAdmin })]),
+    ).not.toThrow();
+  });
 });

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

@@ -9,7 +9,7 @@ import {
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { rolesOf } from "@cosmicdrift/kumiko-framework/testing";
-import { DELIVERY_LOG_SCREEN_ID, DeliveryQueries } from "../constants";
+import { DELIVERY_LOG_SCREEN_ID, DeliveryHandlers, DeliveryQueries } from "../constants";
 import { createDeliveryFeature } from "../feature";
 import { deliveryAttemptsTable, notificationPreferencesTable } from "../tables";
 
@@ -104,3 +104,46 @@ describe("delivery log tenant isolation", () => {
     expect(res.rows.some((r) => r.tenantId === tenantB)).toBe(false);
   });
 });
+
+describe("delivery preferences tenant isolation", () => {
+  // A userId is not tenant-unique — the same person can be a member of
+  // several tenants (tenant:write:add-member takes {userId, tenantId}).
+  // delivery runs in system-scope, so the preferences query handler must
+  // filter by tenantId too — otherwise setting a preference in tenant A
+  // leaks into (or gets read from) tenant B for the same userId.
+  test("user only sees their own tenant's preference for a shared userId", async () => {
+    const tenantA = testTenantId(31);
+    const tenantB = testTenantId(32);
+    const sharedUser = 41;
+    const userInTenantA = createTestUser({ id: sharedUser, roles: ["User"], tenantId: tenantA });
+    const userInTenantB = createTestUser({ id: sharedUser, roles: ["User"], tenantId: tenantB });
+    expect(userInTenantA.id).toBe(userInTenantB.id);
+
+    await stack.http.writeOk(
+      DeliveryHandlers.setPreference,
+      { notificationType: "welcome", channel: "email", enabled: false },
+      userInTenantA,
+    );
+    await stack.http.writeOk(
+      DeliveryHandlers.setPreference,
+      { notificationType: "welcome", channel: "push", enabled: false },
+      userInTenantB,
+    );
+
+    const resA = await stack.http.queryOk<{ rows: readonly { channel: string }[] }>(
+      DeliveryQueries.preferences,
+      {},
+      userInTenantA,
+    );
+    expect(resA.rows.length).toBeGreaterThan(0);
+    expect(resA.rows.every((r) => r.channel === "email")).toBe(true);
+
+    const resB = await stack.http.queryOk<{ rows: readonly { channel: string }[] }>(
+      DeliveryQueries.preferences,
+      {},
+      userInTenantB,
+    );
+    expect(resB.rows.length).toBeGreaterThan(0);
+    expect(resB.rows.every((r) => r.channel === "push")).toBe(true);
+  });
+});

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

@@ -1,14 +1,21 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { deleteMany, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import {
+  buildEntityTable,
+  createEventStoreExecutor,
+  createTenantDb,
+  createUncheckedSystemDb,
+} from "@cosmicdrift/kumiko-framework/db";
 import {
   createEntity,
   createTextField,
   defineFeature,
   defineWriteHandler,
+  type JobContext,
   type NotifyFn,
   qn,
+  type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { createJobRunner, type JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
 import {
@@ -16,6 +23,7 @@ import {
   setupTestStack,
   type TestStack,
   TestUsers,
+  testTenantId,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { z } from "zod";
@@ -39,7 +47,7 @@ import { tenantEntity } from "../../tenant/schema/tenant";
 import { DeliveryHandlers, DeliveryJobs, DeliveryQueries } from "../constants";
 import { collectChannels, createDeliveryService } from "../delivery-service";
 import { createDeliveryFeature } from "../feature";
-import { deliveryRenderJob } from "../jobs";
+import { deliveryRenderJob, deliverySendJob } from "../jobs";
 import { deliveryAttemptsTable, notificationPreferencesTable } from "../tables";
 import { createDeliveryTestContext } from "../testing";
 import type { DeliveryService } from "../types";
@@ -1501,6 +1509,14 @@ describe("flow 17: async render→send pipeline", () => {
     expect(emailRows.some((r) => r["status"] === "sent")).toBe(true);
   });
 
+  // Mirrors what job-runner.ts's handleJob really builds for a
+  // r.systemScope()'d job (framework#2105) — a real TenantDb wrapped by
+  // createUncheckedSystemDb, not a mock, so requireTenantScopedDeps'
+  // assertTenantMatch() call exercises the actual production code path.
+  function makeSystemDb(tenantId: TenantId) {
+    return createUncheckedSystemDb(createTenantDb(db, tenantId, "system"));
+  }
+
   test("delivery.render on a channel without a render step records failed and does not dispatch send", async () => {
     const { runner, dispatched } = makeStubRunner();
     const attemptId = "00000000-0000-4000-8000-0000000000aa";
@@ -1516,7 +1532,13 @@ describe("flow 17: async render→send pipeline", () => {
           priority: "normal",
           message: { notificationType: "app:notify:render-isolation", title: "X" },
         },
-        { db, registry: stack.registry, jobRunner: runner },
+        // @cast-boundary test-seam — job throws before touching systemUser/log/write/queryAs
+        {
+          db,
+          registry: stack.registry,
+          jobRunner: runner,
+          systemDb: makeSystemDb(admin.tenantId),
+        } as unknown as JobContext,
       ),
     ).rejects.toThrow(/no render step/);
 
@@ -1527,6 +1549,77 @@ describe("flow 17: async render→send pipeline", () => {
     });
     expect(rows.some((r) => r["status"] === "failed")).toBe(true);
   });
+
+  // The regression this diff exists to prevent: a payload.tenantId that
+  // doesn't match the systemDb's own tenant must be rejected, not silently
+  // used to read/write another tenant's stream (what ctx.db without
+  // assertTenantMatch would have allowed).
+  test("job handlers throw when payload.tenantId doesn't match ctx.systemDb's tenant", async () => {
+    const { runner, dispatched } = makeStubRunner();
+    const foreignTenantId = testTenantId(999);
+    const attemptId = "00000000-0000-4000-8000-0000000000cc";
+    // @cast-boundary test-seam — mirrors job-runner.ts's real systemDb shape
+    const ctxWithMismatchedSystemDb = {
+      db,
+      registry: stack.registry,
+      jobRunner: runner,
+      systemDb: makeSystemDb(admin.tenantId),
+    } as unknown as JobContext;
+
+    await expect(
+      deliveryRenderJob(
+        {
+          channelName: "email",
+          address: testEmail(asyncRecipient),
+          tenantId: foreignTenantId,
+          recipientId: String(asyncRecipient),
+          notificationType: "app:notify:cross-tenant",
+          deliveryAttemptId: attemptId,
+          priority: "normal",
+          message: { notificationType: "app:notify:cross-tenant", title: "X" },
+        },
+        ctxWithMismatchedSystemDb,
+      ),
+    ).rejects.toThrow(/tenant self-check failed/);
+
+    expect(dispatched).toHaveLength(0);
+    const rows = await selectMany(db, deliveryAttemptsTable, {
+      notificationType: "app:notify:cross-tenant",
+    });
+    expect(rows).toHaveLength(0);
+  });
+
+  // Unreachable via real dispatch (job-runner.ts only omits systemDb for jobs
+  // whose feature is NOT r.systemScope()'d, and delivery always is) — this
+  // exercises requireTenantScopedDeps' own defensive guard directly, the
+  // same way the missing-render-step case above exercises resolveChannel's.
+  test("job handlers throw when ctx.systemDb is missing on a system-scoped job", async () => {
+    const { runner } = makeStubRunner();
+    const attemptId = "00000000-0000-4000-8000-0000000000bb";
+    const payload = {
+      channelName: "email",
+      address: testEmail(asyncRecipient),
+      tenantId: admin.tenantId,
+      recipientId: String(asyncRecipient),
+      notificationType: "app:notify:missing-systemdb",
+      deliveryAttemptId: attemptId,
+      priority: "normal" as const,
+      message: { notificationType: "app:notify:missing-systemdb", title: "X" },
+    };
+    // @cast-boundary test-seam — no systemDb, unlike what job-runner.ts actually wires
+    const ctxWithoutSystemDb = {
+      db,
+      registry: stack.registry,
+      jobRunner: runner,
+    } as unknown as JobContext;
+
+    await expect(deliveryRenderJob(payload, ctxWithoutSystemDb)).rejects.toThrow(
+      /ctx\.systemDb missing/,
+    );
+    await expect(deliverySendJob(payload, ctxWithoutSystemDb)).rejects.toThrow(
+      /ctx\.systemDb missing/,
+    );
+  });
 });
 
 // --- Flow 18: priority maps onto the BullMQ job priority ---

package/src/delivery/feature.ts

@@ -19,7 +19,17 @@ import {
   notificationPreferencesTable,
 } from "./tables";
 
-export function createDeliveryFeature(): FeatureDefinition {
+export type DeliveryFeatureOptions = {
+  // Access gate for the delivery-log screen and the `log` query it reads —
+  // both move together so the nav entry a role sees always matches a
+  // callable handler (#2033). Default access.admin includes TenantAdmin,
+  // who in a line-of-business app is the operator, not the platform — pass
+  // access.systemAdmin to keep this platform-only and out of their nav.
+  readonly access?: readonly string[];
+};
+
+export function createDeliveryFeature(options?: DeliveryFeatureOptions): FeatureDefinition {
+  const resolvedAccess = options?.access ?? access.admin;
   return defineFeature("delivery", (r) => {
     r.describe(
       "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). It stores per-user channel preferences in the `notification-preference` entity, logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything.",
@@ -118,7 +128,7 @@ export function createDeliveryFeature(): FeatureDefinition {
     };
 
     const queries = {
-      log: r.queryHandler(logQuery),
+      log: r.queryHandler({ ...logQuery, access: { roles: resolvedAccess } }),
       preferences: r.queryHandler(preferencesQuery),
     };
 
@@ -126,7 +136,7 @@ export function createDeliveryFeature(): FeatureDefinition {
       id: DELIVERY_LOG_SCREEN_ID,
       type: "custom",
       renderer: { react: { __component: "DeliveryLogScreen" } },
-      access: { roles: access.admin },
+      access: { roles: resolvedAccess },
     });
     r.nav({
       id: "delivery-log",

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

@@ -1,5 +1,6 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { decryptStoredPii } from "../../shared";
 import { deliveryAttemptsTable } from "../tables";
@@ -11,11 +12,16 @@ export const logQuery = defineQueryHandler({
   }),
   access: { roles: access.admin },
   handler: async (query, ctx) => {
-    // delivery runs in system-scope (feature.ts r.systemScope()), so ctx.db is
-    // NOT auto-tenant-filtered — filter explicitly or a tenant admin reads every
-    // tenant's attempts (with decrypted recipient PII below).
+    if (!ctx.systemDb) {
+      throw new InternalError({ message: "delivery log handler requires ctx.systemDb" });
+    }
+    // delivery is r.systemScope()'d, so the TenantDb is system-mode (reads
+    // unfiltered). assertTenantMatch is a self-check on the caller's own
+    // tenantId, not a query filter — it returns that same unfiltered db, so
+    // the explicit `where` below still does the actual tenant scoping.
+    const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
     const rows = await selectMany(
-      ctx.db,
+      db,
       deliveryAttemptsTable,
       { tenantId: query.user.tenantId },
       {

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

@@ -1,5 +1,6 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { notificationPreferencesTable } from "../tables";
 
@@ -8,7 +9,19 @@ export const preferencesQuery = defineQueryHandler({
   schema: z.object({}),
   access: { openToAll: true },
   handler: async (query, ctx) => {
-    const rows = await selectMany(ctx.db, notificationPreferencesTable, { userId: query.user.id });
+    // delivery runs in system-scope, so ctx.db is not auto-tenant-filtered —
+    // userId alone is not tenant-unique, so a userId-only filter here leaked preferences cross-tenant.
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message: "preferences: ctx.systemDb missing on a system-scoped handler",
+      });
+    }
+    const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
+
+    const rows = await selectMany(db, notificationPreferencesTable, {
+      tenantId: query.user.tenantId,
+      userId: query.user.id,
+    });
 
     return { rows };
   },

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

@@ -1,4 +1,5 @@
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { upsertPreference } from "../upsert-preference";
 
@@ -15,7 +16,17 @@ export const setPreferenceWrite = defineWriteHandler({
     const { notificationType, channel, enabled } = event.payload;
     const { id: userId, tenantId } = event.user;
 
-    const result = await upsertPreference(ctx.db, event.user, {
+    // delivery runs in system-scope (feature.ts r.systemScope()) — ctx.systemDb
+    // is guaranteed there. No client-supplied userId exists on this payload;
+    // assertTenantMatch is the enforcement path that keeps it that way.
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message: "setPreference: ctx.systemDb missing on a system-scoped handler",
+      });
+    }
+    const db = ctx.systemDb.assertTenantMatch(tenantId);
+
+    const result = await upsertPreference(db, event.user, {
       tenantId,
       userId,
       notificationType,

package/src/delivery/index.ts

@@ -15,7 +15,7 @@ export {
   type KillSwitchResolver,
   type RateLimitConfig,
 } from "./delivery-service";
-export { createDeliveryFeature } from "./feature";
+export { createDeliveryFeature, type DeliveryFeatureOptions } from "./feature";
 export {
   deliveryAttemptsTable,
   notificationPreferenceEntity,