@cosmicdrift/kumiko-bundled-features 0.197.1 → 0.199.0

package/src/auth-mfa/__tests__/reencrypt-job.integration.test.ts

@@ -15,7 +15,7 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
 import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
-import type { AppContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { JobContext } from "@cosmicdrift/kumiko-framework/engine";
 import { rebuildProjection } from "@cosmicdrift/kumiko-framework/pipeline";
 import {
   createEnvelopeCipher,
@@ -107,13 +107,13 @@ const noopLog = {
   child: () => noopLog,
 };
 
-function jobCtx(): AppContext {
+function jobCtx(): JobContext {
   return {
     db: stack.db,
     registry: stack.registry,
     masterKeyProvider: mutableProvider,
     log: noopLog,
-  } as AppContext; // @cast-boundary test-seam — job only reads db/registry/masterKeyProvider/log
+  } as unknown as JobContext; // @cast-boundary test-seam — job only reads db/registry/masterKeyProvider/log
 }
 
 describe("auth-mfa KEK-rotation job — kumiko-framework#266 Step 8", () => {
@@ -227,7 +227,7 @@ describe("auth-mfa KEK-rotation job — unrecognized values are not silently ski
       registry: stack.registry,
       masterKeyProvider: mutableProvider,
       log: capturingLog,
-    } as AppContext);
+    } as unknown as JobContext);
 
     const completeLine = captured.info.find((line) =>
       line.includes("[auth-mfa:reencrypt] complete:"),
@@ -301,7 +301,7 @@ describe("auth-mfa KEK-rotation job — unrecognized values are not silently ski
       registry: stack.registry,
       masterKeyProvider: mutableProvider,
       log: capturingLog,
-    } as AppContext);
+    } as unknown as JobContext);
 
     const completeLine = captured.info.find((line) =>
       line.includes("[auth-mfa:reencrypt] complete:"),

package/src/auth-mfa/feature.ts

@@ -91,11 +91,14 @@ export function createAuthMfaFeature(opts: AuthMfaFeatureOptions): FeatureDefini
     // Dormant custom-screen — the client maps MFA_ENABLE_SCREEN_ID to
     // MfaEnableScreen (see personal-access-tokens/feature.ts for the same
     // convention). App places it via r.nav in its logged-in settings area.
+    // dormant: true skips createKumikoApp's missing-client-plugin boot
+    // diagnostic (#2025) for apps that don't nav this screen (#2034).
     r.screen({
       id: MFA_ENABLE_SCREEN_ID,
       type: "custom",
       renderer: { react: { __component: "MfaEnableScreen" } },
       access: { openToAll: true },
+      dormant: true,
     });
     r.translations({ keys: AUTH_MFA_FEATURE_I18N });
 

package/src/compliance-profiles/__tests__/compliance-profiles.integration.test.ts

@@ -1,5 +1,6 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { access } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
   createTestUser,
@@ -306,3 +307,89 @@ describe("compliance-profiles :: needs-profile (S1.5 — Onboarding-Banner)", ()
     expect(result.status).toBe(403);
   });
 });
+
+describe("compliance-profiles :: needs-profile mit access.systemAdmin-Narrowing (#2063)", () => {
+  let narrowedStack: TestStack;
+  let narrowedDb: DbConnection;
+
+  beforeAll(async () => {
+    const narrowedFeature = createComplianceProfilesFeature({ access: access.systemAdmin });
+    narrowedStack = await setupTestStack({ features: [narrowedFeature] });
+    narrowedDb = narrowedStack.db;
+    await unsafeCreateEntityTable(narrowedDb, tenantComplianceProfileEntity);
+    await createEventsTable(narrowedDb);
+  });
+
+  afterAll(async () => {
+    await narrowedStack.cleanup();
+  });
+
+  // TenantAdmin can no longer reach the picker screen (access.systemAdmin
+  // excludes TenantAdmin) — needsSelection must stop pointing them at a
+  // screen they can't open.
+  test("TenantAdmin ohne Picker-Zugriff → needsSelection bleibt false, reason=picker_not_accessible_for_role", async () => {
+    const excludedTenantAdmin = createIsolatedTenantAdmin(200);
+    const result = await narrowedStack.http.queryOk<{
+      needsSelection: boolean;
+      currentProfile: string | null;
+      reason?: string;
+    }>(NEEDS_PROFILE, {}, excludedTenantAdmin);
+    expect(result.needsSelection).toBe(false);
+    expect(result.currentProfile).toBeNull();
+    expect(result.reason).toBe("picker_not_accessible_for_role");
+  });
+
+  // A user holding both roles can still reach the picker via SystemAdmin —
+  // the gate must intersect the caller's actual roles, not just check
+  // whether TenantAdmin (the query's fixed call-access role) is among the
+  // feature's configured picker roles.
+  test("TenantAdmin+SystemAdmin dual-role → needsSelection bleibt true (Picker via SystemAdmin erreichbar)", async () => {
+    const dualRoleUser = createTestUser({
+      id: 204,
+      tenantId: testTenantId(204),
+      roles: ["TenantAdmin", "SystemAdmin"],
+    });
+    const result = await narrowedStack.http.queryOk<{
+      needsSelection: boolean;
+      currentProfile: string | null;
+      reason?: string;
+    }>(NEEDS_PROFILE, {}, dualRoleUser);
+    expect(result.needsSelection).toBe(true);
+    expect(result.reason).toBe("no_profile_selected");
+  });
+
+  // The needs-profile call access itself stays TenantAdmin-only — the
+  // `access` option is not passed 1:1 to the query dispatcher (otherwise
+  // SystemAdmin could now call an endpoint only TenantAdmin used to be
+  // allowed to call — a widening #2063 does not ask for).
+  test("SystemAdmin darf needs-profile weiterhin nicht aufrufen (Call-Access unveraendert)", async () => {
+    const systemAdmin = createTestUser({
+      id: 201,
+      tenantId: testTenantId(201),
+      roles: ["SystemAdmin"],
+    });
+    const result = await narrowedStack.http.query(NEEDS_PROFILE, {}, systemAdmin);
+    expect(result.status).toBe(403);
+  });
+
+  test("TenantAdmin mit bereits gesetztem Profile → needsSelection bleibt false, kein reason-Sonderfall", async () => {
+    const setupAdmin = createIsolatedTenantAdmin(202);
+    // set-profile is also narrowed to access.systemAdmin — set up via
+    // SystemAdmin to create the profile row for the read test.
+    const systemAdminSetup = createTestUser({
+      id: 203,
+      tenantId: setupAdmin.tenantId,
+      roles: ["SystemAdmin"],
+    });
+    await narrowedStack.http.writeOk(SET_PROFILE, { profileKey: "eu-dsgvo" }, systemAdminSetup);
+
+    const result = await narrowedStack.http.queryOk<{
+      needsSelection: boolean;
+      currentProfile: string | null;
+      reason?: string;
+    }>(NEEDS_PROFILE, {}, setupAdmin);
+    expect(result.needsSelection).toBe(false);
+    expect(result.currentProfile).toBe("eu-dsgvo");
+    expect(result.reason).toBeUndefined();
+  });
+});

package/src/compliance-profiles/__tests__/profile-picker.boot.test.ts

@@ -15,9 +15,7 @@ describe("compliance profile screen + handler access alignment", () => {
     const feature = createComplianceProfilesFeature();
     const screen = feature.screens[COMPLIANCE_PROFILE_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("set-profile handler shares access.admin", () => {
@@ -25,4 +23,17 @@ describe("compliance profile screen + handler access alignment", () => {
     expect(rolesOf(feature.writeHandlers["set-profile"]?.access)).toEqual([...access.admin]);
     void ComplianceProfileHandlers;
   });
+
+  test("access option narrows the profile-picker screen and its set-profile handler together (#2033)", () => {
+    const feature = createComplianceProfilesFeature({ access: access.systemAdmin });
+    const screen = feature.screens[COMPLIANCE_PROFILE_SCREEN_ID];
+    expect(rolesOf(screen?.access)).toEqual([...access.systemAdmin]);
+    expect(rolesOf(feature.writeHandlers["set-profile"]?.access)).toEqual([...access.systemAdmin]);
+  });
+
+  test("boot-validates with a narrowed access option", () => {
+    expect(() =>
+      validateBoot([createComplianceProfilesFeature({ access: access.systemAdmin })]),
+    ).not.toThrow();
+  });
 });

package/src/compliance-profiles/feature.ts

@@ -6,7 +6,7 @@ import {
 import { COMPLIANCE_PROFILE_SCREEN_ID } from "./constants";
 import { forTenantQuery } from "./handlers/for-tenant.query";
 import { listProfilesQuery } from "./handlers/list-profiles.query";
-import { needsProfileQuery } from "./handlers/needs-profile.query";
+import { createNeedsProfileQuery } from "./handlers/needs-profile.query";
 import { setProfileWrite } from "./handlers/set-profile.write";
 import { subProcessorsQuery } from "./handlers/sub-processors.query";
 import { COMPLIANCE_PROFILES_I18N } from "./i18n";
@@ -31,7 +31,20 @@ export {
 // Architektur-Note: Profile-Selection lebt als separate Entity
 // (tenantComplianceProfile), nicht als config-key im tenant-Feature.
 // Begruendung in schema/profile-selection.ts.
-export function createComplianceProfilesFeature(): FeatureDefinition {
+export type ComplianceProfilesFeatureOptions = {
+  // Access gate for the profile-picker screen and the `set-profile` write it
+  // submits to — 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 createComplianceProfilesFeature(
+  options?: ComplianceProfilesFeatureOptions,
+): FeatureDefinition {
+  const resolvedAccess = options?.access ?? access.admin;
   return defineFeature("compliance-profiles", (r) => {
     r.describe(
       "Lets each tenant select a compliance regime (e.g. `eu-dsgvo`, `swiss-dsg`, `de-hr-dsgvo-hgb`) that bundles user-rights grace periods, breach-disclosure deadlines, sub-processor requirements, and audit-retention rules into a single named profile. Tenant admins call `compliance-profiles:write:set-profile` to choose a profile (with optional JSON override for edge cases); other features resolve the effective profile via the `compliance.forTenant` cross-feature API. Required by `user-data-rights` \u2014 mount this feature before it.",
@@ -50,21 +63,21 @@ export function createComplianceProfilesFeature(): FeatureDefinition {
     r.exposesApi("compliance.forTenant");
 
     const handlers = {
-      setProfile: r.writeHandler(setProfileWrite),
+      setProfile: r.writeHandler({ ...setProfileWrite, access: { roles: resolvedAccess } }),
     };
 
     const queries = {
       forTenant: r.queryHandler(forTenantQuery),
       listProfiles: r.queryHandler(listProfilesQuery),
       subProcessors: r.queryHandler(subProcessorsQuery),
-      needsProfile: r.queryHandler(needsProfileQuery),
+      needsProfile: r.queryHandler(createNeedsProfileQuery(resolvedAccess)),
     };
 
     r.screen({
       id: COMPLIANCE_PROFILE_SCREEN_ID,
       type: "custom",
       renderer: { react: { __component: "ComplianceProfileScreen" } },
-      access: { roles: access.admin },
+      access: { roles: resolvedAccess },
     });
     r.nav({
       id: "profile-picker",

package/src/compliance-profiles/handlers/needs-profile.query.ts

@@ -5,49 +5,69 @@ import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { tenantComplianceProfileTable } from "../schema/profile-selection";
 
-// Onboarding-Banner-Trigger fuer Tenant-Admin.
+// Onboarding banner trigger for tenant admin.
 //
-// Sprint 1.5 — minimaler API-Endpoint, UI-Banner kommt in einem
-// spaeteren UI-Sprint. Reine Read-Query: gibt es einen Eintrag in
-// tenantComplianceProfile fuer den aktuellen Tenant?
+// Sprint 1.5 — minimal API endpoint, the UI banner comes in a later UI
+// sprint. Pure read query: does an entry exist in tenantComplianceProfile
+// for the current tenant?
 //
-// Wenn nein → Tenant-Admin muss Profile waehlen (Pflicht beim
-// Onboarding). Bis zur Wahl laeuft minimal-no-region mit warning,
-// das in der Tenant-Dashboard-Banner sichtbar gemacht werden soll.
+// If not → tenant admin must pick a profile (mandatory during onboarding).
+// Until picked, minimal-no-region runs with a warning that should surface
+// in the tenant dashboard banner.
 //
-// Access: TenantAdmin only — der Banner ist nur fuer Tenant-Admins
-// relevant, nicht fuer normale Member.
-export const needsProfileQuery = defineQueryHandler({
-  name: "needs-profile",
-  schema: z.object({}),
-  access: { roles: [ROLES.TenantAdmin] },
-  handler: async (query, ctx): Promise<NeedsProfileResponse> => {
-    const row = (await fetchOne(ctx.db, tenantComplianceProfileTable, {
-      tenantId: query.user.tenantId,
-    })) as { profileKey: ComplianceProfileKey } | null; // @cast-boundary db-runner
+// Access: TenantAdmin only — the banner is only relevant to tenant admins,
+// not regular members. Stays hard-coded to TenantAdmin (not the `access`
+// option of createComplianceProfilesFeature) — passing the option through
+// would widen call access by default to all three access.admin roles
+// (including SystemAdmin). Instead the handler takes `pickerReachableRoles`
+// and deliberately resolves the #2063 special case: if the *caller's*
+// roles no longer intersect the picker's `access` option, the query stops
+// reporting needsSelection — otherwise a tenant admin would be told to
+// open a screen they can't reach.
+export function createNeedsProfileQuery(pickerReachableRoles: readonly string[]) {
+  return defineQueryHandler({
+    name: "needs-profile",
+    schema: z.object({}),
+    access: { roles: [ROLES.TenantAdmin] },
+    handler: async (query, ctx): Promise<NeedsProfileResponse> => {
+      const row = (await fetchOne(ctx.db, tenantComplianceProfileTable, {
+        tenantId: query.user.tenantId,
+      })) as { profileKey: ComplianceProfileKey } | null; // @cast-boundary db-runner
+
+      if (row) {
+        // S1.7 X1: minimal-no-region is no longer settable via set-profile
+        // (Zod). If Sprint 2 ships a seedComplianceProfile helper that
+        // reintroduces the migration edge case, a defensive path belongs
+        // here again — until then, every existing entry is a deliberately
+        // chosen production profile.
+        return {
+          needsSelection: false,
+          currentProfile: row.profileKey,
+        };
+      }
+
+      const callerCanReachPicker = query.user.roles.some((role) =>
+        pickerReachableRoles.includes(role),
+      );
+      if (!callerCanReachPicker) {
+        return {
+          needsSelection: false,
+          currentProfile: null,
+          reason: "picker_not_accessible_for_role",
+        };
+      }
 
-    if (!row) {
       return {
         needsSelection: true,
         currentProfile: null,
         reason: "no_profile_selected",
       };
-    }
-
-    // S1.7 X1: minimal-no-region ist via set-profile (Zod) nicht mehr
-    // setzbar. Wenn Sprint 2 einen seedComplianceProfile-Helper liefert
-    // der den Migration-Edge-Case einführt, kommt hier wieder ein
-    // defensiver Pfad rein — bis dahin: jeder existierende Eintrag ist
-    // ein bewusst gewähltes Production-Profile.
-    return {
-      needsSelection: false,
-      currentProfile: row.profileKey,
-    };
-  },
-});
+    },
+  });
+}
 
 interface NeedsProfileResponse {
   readonly needsSelection: boolean;
   readonly currentProfile: ComplianceProfileKey | null;
-  readonly reason?: "no_profile_selected";
+  readonly reason?: "no_profile_selected" | "picker_not_accessible_for_role";
 }

package/src/compliance-profiles/index.ts

@@ -5,6 +5,7 @@ export {
   ComplianceProfileQueries,
 } from "./constants";
 export {
+  type ComplianceProfilesFeatureOptions,
   createComplianceProfilesFeature,
   tenantComplianceProfileEntity,
   tenantComplianceProfileTable,

package/src/config/__tests__/reencrypt-job-tenant-checks.integration.test.ts

@@ -0,0 +1,185 @@
+// Regression guard for kumiko-framework#2072: the KEK-rotation job's
+// systemScope() fail-closed checks — createUncheckedSystemDb().
+// acknowledgeCrossTenant() gating the initial cross-tenant scan,
+// assertRowsTenant() re-verifying each per-tenant slice before it's served
+// to the write loop — must not block legitimate multi-tenant rotation. A
+// systemDb accidentally bound to the wrong tenant (e.g. always
+// SYSTEM_TENANT_ID instead of the scanned row's own tenant) would make
+// every non-system-tenant row fail closed via assertRowsTenant, landing in
+// `failed` (not thrown — chunked-entity-migration.ts routes migrateRow
+// throws through onRowError) rather than `migrated`.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  createSystemUser,
+  createTenantConfig,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEnvelopeCipher,
+  createEnvMasterKeyProvider,
+} from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createMutableMasterKeyProvider } from "@cosmicdrift/kumiko-framework/testing";
+import { createConfigFeature } from "../feature";
+import { reencryptJob } from "../handlers/reencrypt.job";
+import { createConfigResolver } from "../resolver";
+import { configValueEntity, configValuesTable } from "../table";
+
+const KEY = "tenant-check-rot:config:secret-pass";
+const TENANT_A = testTenantId(201);
+const TENANT_B = testTenantId(202);
+
+const v1Key = randomBytes(32).toString("base64");
+const v2Key = randomBytes(32).toString("base64");
+const mutableProvider = createMutableMasterKeyProvider(
+  createEnvMasterKeyProvider({
+    env: {
+      KUMIKO_SECRETS_MASTER_KEY_V1: v1Key,
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+    },
+  }),
+);
+const cipher = createEnvelopeCipher(mutableProvider, {});
+const resolver = createConfigResolver({ cipher });
+
+const keyDef = createTenantConfig("text", {
+  encrypted: true,
+  read: access.admin,
+  write: access.admin,
+});
+
+const tenantCheckFeature = defineFeature("tenant-check-rot", (r) => {
+  r.requires("config");
+  r.config({ keys: { "secret-pass": keyDef } });
+});
+
+const executor = createEventStoreExecutor(configValuesTable, configValueEntity, {
+  entityName: "config-value",
+});
+
+let stack: TestStack;
+
+async function seedRow(tenantId: string, plaintext: string): Promise<void> {
+  const envelope = await cipher.encrypt(JSON.stringify(plaintext), { tenantId });
+  const systemUser = createSystemUser(tenantId);
+  const tdb = createTenantDb(stack.db, tenantId, "system");
+  const result = await executor.create(
+    { key: KEY, value: envelope, tenantId, userId: null },
+    systemUser,
+    tdb,
+  );
+  if (!result.isSuccess) throw new Error(`seed failed: ${result.error.code}`);
+}
+
+type RawConfigRow = { value: string; tenantId: string };
+
+async function readRawValues(): Promise<readonly RawConfigRow[]> {
+  return await selectMany<RawConfigRow>(stack.db, configValuesTable, { key: KEY });
+}
+
+type CapturedLog = { info: string[]; warn: string[] };
+
+type TestJobLog = {
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: () => void;
+  debug: () => void;
+  child: () => TestJobLog;
+};
+
+function capturingLog(captured: CapturedLog): TestJobLog {
+  const log: TestJobLog = {
+    info: (msg) => captured.info.push(msg),
+    warn: (msg) => captured.warn.push(msg),
+    error: () => {},
+    debug: () => {},
+    child: () => log,
+  };
+  return log;
+}
+
+function jobCtx(captured: CapturedLog): Parameters<typeof reencryptJob>[1] {
+  return {
+    db: stack.db,
+    registry: stack.registry,
+    masterKeyProvider: mutableProvider,
+    configEncryption: cipher,
+    log: capturingLog(captured),
+  } as unknown as Parameters<typeof reencryptJob>[1]; // @cast-boundary test-seam — job only reads db/registry/masterKeyProvider/configEncryption/log
+}
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [createConfigFeature(), tenantCheckFeature],
+    masterKeyProvider: mutableProvider,
+    extraContext: { configResolver: resolver, configEncryption: cipher },
+  });
+  await unsafePushTables(stack.db, { configValuesTable });
+  await seedRow(TENANT_A, "tenant-a-secret");
+  await seedRow(TENANT_B, "tenant-b-secret");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("config KEK-rotation job — multi-tenant scan + write checks (kumiko-framework#2072)", () => {
+  test("acknowledgeCrossTenant scan + per-tenant assertRowsTenant checks still rotate every tenant's row", async () => {
+    const beforeRows = await readRawValues();
+    expect(beforeRows).toHaveLength(2);
+    for (const row of beforeRows) {
+      expect(JSON.parse(row.value).kekVersion).toBe(1);
+    }
+
+    // "ops added a new master key version and flipped CURRENT=2".
+    mutableProvider.replace(
+      createEnvMasterKeyProvider({
+        env: {
+          KUMIKO_SECRETS_MASTER_KEY_V1: v1Key,
+          KUMIKO_SECRETS_MASTER_KEY_V2: v2Key,
+          KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "2",
+        },
+      }),
+    );
+
+    const captured: CapturedLog = { info: [], warn: [] };
+    await reencryptJob({}, jobCtx(captured));
+
+    // No warn output — an over-restrictive systemDb binding would reject a
+    // row via assertRowsTenant, landing it in `failed` with a warn log
+    // instead of `migrated`.
+    expect(captured.warn).toEqual([]);
+
+    const completeLine = captured.info.find((line) =>
+      line.includes("[config:reencrypt] complete:"),
+    );
+    if (!completeLine) throw new Error("job did not log a completion summary");
+    const result = JSON.parse(completeLine.slice(completeLine.indexOf("{"))) as {
+      migrated: number;
+      failed: number;
+      alreadyCurrent: number;
+    };
+    expect(result.migrated).toBe(2);
+    expect(result.failed).toBe(0);
+    expect(result.alreadyCurrent).toBe(0);
+
+    const afterRows = await readRawValues();
+    expect(afterRows).toHaveLength(2);
+    for (const row of afterRows) {
+      expect(JSON.parse(row.value).kekVersion).toBe(2);
+    }
+
+    expect(await resolver.get(KEY, keyDef, TENANT_A, "u1", stack.db)).toBe("tenant-a-secret");
+    expect(await resolver.get(KEY, keyDef, TENANT_B, "u1", stack.db)).toBe("tenant-b-secret");
+  });
+});

package/src/config/__tests__/require-system-db.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { createUncheckedSystemDb } from "@cosmicdrift/kumiko-framework/db";
+import type { HandlerContext, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { AccessDeniedError } from "@cosmicdrift/kumiko-framework/errors";
+import { requireSystemDb } from "../feature";
+
+// Minimal TenantDb stub — only .tenantId is read by assertTenantMatch /
+// createUncheckedSystemDb; the real db-query methods are never called by
+// requireSystemDb itself.
+function fakeTenantDb(tenantId: TenantId): TenantDb {
+  return { tenantId, mode: "system" } as unknown as TenantDb;
+}
+
+// Minimal HandlerContext stub — only .db / .systemDb are read by requireSystemDb.
+function contextStub(db: TenantDb, withSystemDb: boolean): HandlerContext {
+  return {
+    db,
+    systemDb: withSystemDb ? createUncheckedSystemDb(db) : undefined,
+    // biome-ignore lint/suspicious/noExplicitAny: rest of HandlerContext isn't touched by requireSystemDb.
+  } as any;
+}
+
+const TENANT_A = "tenant-a" as TenantId;
+const TENANT_B = "tenant-b" as TenantId;
+
+describe("requireSystemDb", () => {
+  test("throws InternalError when ctx.systemDb is missing", () => {
+    const ctx = contextStub(fakeTenantDb(TENANT_A), false);
+    expect(() => requireSystemDb(ctx, "config:query:test", TENANT_A)).toThrow(
+      /ctx\.systemDb missing/,
+    );
+  });
+
+  test("returns the underlying TenantDb when tenantId matches", () => {
+    const db = fakeTenantDb(TENANT_A);
+    const ctx = contextStub(db, true);
+    expect(requireSystemDb(ctx, "config:query:test", TENANT_A)).toBe(db);
+  });
+
+  test("fails closed with AccessDeniedError when tenantId does not match ctx.db's own tenant", () => {
+    const db = fakeTenantDb(TENANT_A);
+    const ctx = contextStub(db, true);
+    expect(() => requireSystemDb(ctx, "config:query:test", TENANT_B)).toThrow(AccessDeniedError);
+  });
+});

package/src/config/feature.ts

@@ -120,6 +120,34 @@ export function requireConfigResolver(ctx: HandlerContext, handlerName: string):
   return ctx.configResolver;
 }
 
+// Config declares r.systemScope() (raw ctx.db is unfiltered across tenants
+// in that mode), so config's own query handlers must go through ctx.systemDb's
+// explicit self-check instead of touching ctx.db directly. Only valid for
+// handlers dispatched as config:query:* — those always run under config's
+// own system-scoped context, so ctx.systemDb is never actually missing here;
+// the throw documents that invariant instead of silently degrading.
+// buildProviderSelectionGate / collectMissingRequiredConfig (readiness.query.ts)
+// are shared with the separate, plain tenant-scoped readiness feature, so they
+// take the already-scoped db as an explicit parameter instead of resolving it
+// themselves — each call site (config's own handler here, readiness's
+// status.query.ts) makes its own scope decision instead of this function
+// guessing from ctx.systemDb's presence.
+export function requireSystemDb(
+  ctx: HandlerContext,
+  handlerName: string,
+  tenantId: TenantId,
+): TenantDb {
+  if (!ctx.systemDb) {
+    throw new InternalError({
+      message:
+        `[${handlerName}] ctx.systemDb missing — only present for r.systemScope() handlers; ` +
+        `the config feature declares r.systemScope() in feature.ts, so this points at a ` +
+        `pipeline wiring bug rather than a missing feature declaration.`,
+    });
+  }
+  return ctx.systemDb.assertTenantMatch(tenantId);
+}
+
 // Mirror of requireConfigResolver for the encryption round-trip side.
 // Only keys declared `encrypted: true` need this — the setter calls it
 // lazily so apps that never wire encryption still boot (and only crash

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

@@ -5,7 +5,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 cascadeQuery = defineQueryHandler({
   }),
   access: { openToAll: true },
   handler: async (query, ctx) => {
-    const db = ctx.db;
+    const db = requireSystemDb(ctx, "config:query:cascade", query.user.tenantId);
     const registry = ctx.registry;
     const resolver = requireConfigResolver(ctx, "config:query:cascade");