@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/config/__tests__/reencrypt-job-concurrent-write-race.integration.test.ts

@@ -0,0 +1,234 @@
+// Regression guard for kumiko-framework#1188: proves a write interleaved
+// with a running rotation survives — the event-store executor's optimistic
+// concurrency check rejects the rotation job's stale-version update, so the
+// version_conflict branch in reencrypt.job.ts's migrateRow (currently just
+// "a concurrent config:set beat us; the row now holds a fresh envelope —
+// already fine.") is verified, not just an unverified comment. Modeled on
+// reencrypt-job-kek-rotation.integration.test.ts (kumiko-framework#1187)
+// for the stack/rotation setup.
+//
+// The race is simulated deterministically: the job context's
+// configEncryption.encrypt is wrapped so the FIRST call (which migrateRow
+// makes right before its own executor.update) performs a second, unrelated
+// write to the same row first. That write lands on the row version the job
+// captured at batch-read time, so the job's own update — issued a moment
+// later with that now-stale version — is guaranteed to hit version_conflict.
+
+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,
+  createSystemConfig,
+  createSystemUser,
+  defineFeature,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { rebuildProjection } from "@cosmicdrift/kumiko-framework/pipeline";
+import {
+  createEnvelopeCipher,
+  createEnvMasterKeyProvider,
+  type EnvelopeCipher,
+} from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  setupTestStack,
+  type TestStack,
+  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 = "kek-rot-race:config:race-pass";
+const ORIGINAL_PLAINTEXT = "pre-race-value";
+const CONCURRENT_PLAINTEXT = "concurrent-write-value";
+const PROJECTION_NAME = "config:projection:config-value-entity";
+
+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 = createSystemConfig("text", {
+  encrypted: true,
+  read: access.systemAdmin,
+  write: access.systemAdmin,
+});
+
+const rotFeature = defineFeature("kek-rot-race", (r) => {
+  r.requires("config");
+  r.config({ keys: { "race-pass": keyDef } });
+});
+
+const executor = createEventStoreExecutor(configValuesTable, configValueEntity, {
+  entityName: "config-value",
+});
+
+let stack: TestStack;
+
+type ConfigRow = {
+  id: string;
+  key: string;
+  value: string | null;
+  tenantId: string;
+  version: number;
+};
+
+async function readRow(): Promise<ConfigRow> {
+  const rows = await selectMany<ConfigRow>(stack.db, configValuesTable, { key: KEY });
+  const row = rows[0];
+  if (!row) throw new Error("no config row");
+  return row;
+}
+
+async function seedV1Row(): Promise<void> {
+  const envelope = await cipher.encrypt(JSON.stringify(ORIGINAL_PLAINTEXT), {
+    tenantId: SYSTEM_TENANT_ID,
+  });
+  const systemUser = createSystemUser(SYSTEM_TENANT_ID);
+  const tdb = createTenantDb(stack.db, SYSTEM_TENANT_ID, "system");
+  const result = await executor.create(
+    { key: KEY, value: envelope, tenantId: SYSTEM_TENANT_ID, userId: null },
+    systemUser,
+    tdb,
+  );
+  if (!result.isSuccess) throw new Error(`seed failed: ${result.error.code}`);
+}
+
+// Writes CONCURRENT_PLAINTEXT to the row using the version the rotation job
+// itself captured at batch-read time — the same version-N -> N+1 bump a
+// real interleaved handler write would cause.
+async function writeConcurrently(atVersion: number): Promise<void> {
+  const envelope = await cipher.encrypt(JSON.stringify(CONCURRENT_PLAINTEXT), {
+    tenantId: SYSTEM_TENANT_ID,
+  });
+  const systemUser = createSystemUser(SYSTEM_TENANT_ID);
+  const tdb = createTenantDb(stack.db, SYSTEM_TENANT_ID, "system");
+  const row = await readRow();
+  const result = await executor.update(
+    { id: row.id, version: atVersion, changes: { value: envelope } },
+    systemUser,
+    tdb,
+  );
+  if (!result.isSuccess) throw new Error(`concurrent write setup failed: ${result.error.code}`);
+}
+
+const noopLog = {
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  debug: () => {},
+  child: () => noopLog,
+};
+
+// Fires the concurrent write on the first encrypt() call the job makes —
+// that's the point in migrateRow right after decrypt, right before its own
+// executor.update, so the job's captured row.version is guaranteed stale by
+// the time it issues that update.
+function racyJobCtx(
+  rowVersionAtBatchRead: number,
+  log: typeof noopLog = noopLog,
+): Parameters<typeof reencryptJob>[1] {
+  let fired = false;
+  const racyCipher: EnvelopeCipher = {
+    decrypt: (stored, scope) => cipher.decrypt(stored, scope),
+    encrypt: async (plaintext, scope) => {
+      if (!fired) {
+        fired = true;
+        await writeConcurrently(rowVersionAtBatchRead);
+      }
+      return cipher.encrypt(plaintext, scope);
+    },
+  };
+  return {
+    db: stack.db,
+    registry: stack.registry,
+    masterKeyProvider: mutableProvider,
+    configEncryption: racyCipher,
+    log,
+  } 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(), rotFeature],
+    masterKeyProvider: mutableProvider,
+    extraContext: { configResolver: resolver, configEncryption: cipher },
+  });
+  await unsafePushTables(stack.db, { configValuesTable });
+  await seedV1Row();
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("config KEK-rotation job — concurrent write race (kumiko-framework#1188)", () => {
+  test("a write interleaved with a running rotation wins — rotation's stale update is rejected, not silently applied", async () => {
+    const seeded = await readRow();
+    expect(JSON.parse(seeded.value as string).kekVersion).toBe(1);
+
+    // "ops flips CURRENT=2 mid-flight" — same rotation trigger as #1187's test.
+    mutableProvider.replace(
+      createEnvMasterKeyProvider({
+        env: {
+          KUMIKO_SECRETS_MASTER_KEY_V1: v1Key,
+          KUMIKO_SECRETS_MASTER_KEY_V2: v2Key,
+          KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "2",
+        },
+      }),
+    );
+
+    // Distinguishes "skipped" (version_conflict, row already fine) from
+    // "failed" (any other rejection) — both leave the row's end-state
+    // identical (reencrypt.job.ts:159-166), so a regression that silently
+    // turns this branch into "failed" would pass every assertion below it.
+    // The warn log at reencrypt.job.ts:171 is the only observable signature
+    // that fires on "failed" but not on "skipped" — assert it stayed silent.
+    const warnCalls: unknown[][] = [];
+    const spyLog = {
+      ...noopLog,
+      warn: (...args: unknown[]) => {
+        warnCalls.push(args);
+      },
+    };
+    await reencryptJob({}, racyJobCtx(seeded.version, spyLog));
+    expect(warnCalls).toEqual([]);
+
+    // The concurrent write already lands under the current key — its
+    // envelope must survive untouched; the rotation job's own update lost
+    // the version_conflict race and must not have overwritten it.
+    const afterJobRow = await readRow();
+    expect(JSON.parse(afterJobRow.value as string).kekVersion).toBe(2);
+    expect(await resolver.get(KEY, keyDef, SYSTEM_TENANT_ID, "u1", stack.db)).toBe(
+      CONCURRENT_PLAINTEXT,
+    );
+
+    // Rebuild guard: a from-scratch replay must land on the concurrent
+    // write's event, not resurrect the rotation job's rejected update (it
+    // never became an event) nor the original pre-race value.
+    expect(stack.registry.getAllProjections().has(PROJECTION_NAME)).toBe(true);
+    const rebuildResult = await rebuildProjection(PROJECTION_NAME, {
+      db: stack.db,
+      registry: stack.registry,
+    });
+    expect(rebuildResult.eventsProcessed).toBeGreaterThan(0);
+
+    const afterRebuildRow = await readRow();
+    expect(JSON.parse(afterRebuildRow.value as string).kekVersion).toBe(2);
+    expect(await resolver.get(KEY, keyDef, SYSTEM_TENANT_ID, "u1", stack.db)).toBe(
+      CONCURRENT_PLAINTEXT,
+    );
+  });
+});

package/src/config/__tests__/reencrypt-job-kek-rotation.integration.test.ts

@@ -0,0 +1,243 @@
+// Regression guard for kumiko-framework#1187: proves the config
+// KEK-rotation job handles a real version-N → version-N+1 rotation. Modeled
+// directly on auth-mfa's
+// reencrypt-job.integration.test.ts, which is the reference regression
+// guard for this exact bug class (kumiko-framework#266 Step 8): rotation
+// must go through executor.update() (a real event), not a raw UPDATE on
+// the projection table — otherwise a full projection rebuild replays the
+// OLD event and resurrects the pre-rotation kekVersion.
+
+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,
+  createSystemConfig,
+  createSystemUser,
+  defineFeature,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { rebuildProjection } from "@cosmicdrift/kumiko-framework/pipeline";
+import {
+  createEnvelopeCipher,
+  createEnvMasterKeyProvider,
+} from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  setupTestStack,
+  type TestStack,
+  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 = "kek-rot:config:secret-pass";
+const PLAINTEXT = "rotate-me-please";
+const PROJECTION_NAME = "config:projection:config-value-entity";
+
+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 = createSystemConfig("text", {
+  encrypted: true,
+  read: access.systemAdmin,
+  write: access.systemAdmin,
+});
+
+const GARBAGE_KEY = "kek-rot:config:garbage-value";
+const GARBAGE_VALUE = "not-json-and-not-an-envelope";
+
+const rotFeature = defineFeature("kek-rot", (r) => {
+  r.requires("config");
+  r.config({ keys: { "secret-pass": keyDef, "garbage-value": keyDef } });
+});
+
+const executor = createEventStoreExecutor(configValuesTable, configValueEntity, {
+  entityName: "config-value",
+});
+
+let stack: TestStack;
+
+async function seedV1Row(): Promise<void> {
+  const envelope = await cipher.encrypt(JSON.stringify(PLAINTEXT), { tenantId: SYSTEM_TENANT_ID });
+  const systemUser = createSystemUser(SYSTEM_TENANT_ID);
+  const tdb = createTenantDb(stack.db, SYSTEM_TENANT_ID, "system");
+  const result = await executor.create(
+    { key: KEY, value: envelope, tenantId: SYSTEM_TENANT_ID, userId: null },
+    systemUser,
+    tdb,
+  );
+  if (!result.isSuccess) throw new Error(`seed failed: ${result.error.code}`);
+}
+
+async function seedGarbageRow(): Promise<void> {
+  const systemUser = createSystemUser(SYSTEM_TENANT_ID);
+  const tdb = createTenantDb(stack.db, SYSTEM_TENANT_ID, "system");
+  const result = await executor.create(
+    { key: GARBAGE_KEY, value: GARBAGE_VALUE, tenantId: SYSTEM_TENANT_ID, userId: null },
+    systemUser,
+    tdb,
+  );
+  if (!result.isSuccess) throw new Error(`seed failed: ${result.error.code}`);
+}
+
+type RawConfigRow = { value: string };
+
+async function readRawValue(key: string = KEY): Promise<RawConfigRow> {
+  const rows = await selectMany<RawConfigRow>(stack.db, configValuesTable, { key });
+  const row = rows[0];
+  if (!row) throw new Error("no config row");
+  return row;
+}
+
+const noopLog = {
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  debug: () => {},
+  child: () => noopLog,
+};
+
+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] {
+  const log = captured ? capturingLog(captured) : noopLog;
+  return {
+    db: stack.db,
+    registry: stack.registry,
+    masterKeyProvider: mutableProvider,
+    configEncryption: cipher,
+    log,
+  } 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(), rotFeature],
+    masterKeyProvider: mutableProvider,
+    extraContext: { configResolver: resolver, configEncryption: cipher },
+  });
+  await unsafePushTables(stack.db, { configValuesTable });
+  await seedV1Row();
+  await seedGarbageRow();
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("config KEK-rotation job — unrecognized values are not silently skipped (kumiko-framework#1513)", () => {
+  test("a non-envelope row is counted failed, never alreadyCurrent, and is left untouched", async () => {
+    const beforeRow = await readRawValue(GARBAGE_KEY);
+    expect(beforeRow.value).toBe(GARBAGE_VALUE);
+
+    // Runs before the #1187 rotation test below flips the master-key
+    // version, so counts are deterministic: the V1 row is current, the
+    // garbage row is unrecognized, nothing needs rotating yet.
+    const captured: CapturedLog = { info: [], warn: [] };
+    await reencryptJob({}, jobCtx(captured));
+
+    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.alreadyCurrent).toBe(1);
+    expect(result.migrated).toBe(0);
+    expect(result.failed).toBe(1);
+
+    const rejectedWarning = captured.warn.find((line) =>
+      line.includes("not a current-cipher envelope"),
+    );
+    expect(rejectedWarning).toBeDefined();
+
+    // Never written: an unreadable row must not be rewritten as if it
+    // decrypted cleanly, and must not be reported as already current.
+    const afterRow = await readRawValue(GARBAGE_KEY);
+    expect(afterRow.value).toBe(GARBAGE_VALUE);
+  });
+});
+
+describe("config KEK-rotation job — version-N to version-N+1 (kumiko-framework#1187)", () => {
+  test("rotation rewraps the value onto the current KEK, and a full projection rebuild still lands on it", async () => {
+    const beforeRow = await readRawValue();
+    expect(JSON.parse(beforeRow.value).kekVersion).toBe(1);
+
+    // "ops added a new master key version and flipped CURRENT=2" —
+    // same simulate-rotation-without-restart shape auth-mfa's test uses.
+    mutableProvider.replace(
+      createEnvMasterKeyProvider({
+        env: {
+          KUMIKO_SECRETS_MASTER_KEY_V1: v1Key,
+          KUMIKO_SECRETS_MASTER_KEY_V2: v2Key,
+          KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "2",
+        },
+      }),
+    );
+
+    await reencryptJob({}, jobCtx());
+
+    const afterJobRow = await readRawValue();
+    expect(JSON.parse(afterJobRow.value).kekVersion).toBe(2);
+
+    // Vacuous-rebuild guard: confirm the projection name actually exists
+    // before trusting a silent no-op rebuild as a pass.
+    expect(stack.registry.getAllProjections().has(PROJECTION_NAME)).toBe(true);
+
+    const rebuildResult = await rebuildProjection(PROJECTION_NAME, {
+      db: stack.db,
+      registry: stack.registry,
+    });
+    expect(rebuildResult.eventsProcessed).toBeGreaterThan(0);
+
+    // The regression guard itself: a from-scratch rebuild replays every
+    // event for this row and must land on the V2 envelope from the
+    // rotation job's own .updated event — NOT a resurrected V1 wrap from
+    // the original seed event. Kept alive with the V1 key still present
+    // in the env on purpose: a resurrected V1 row would still decrypt
+    // cleanly, so only this version-tag check (not the decrypt below)
+    // catches the regression this issue describes.
+    const afterRebuildRow = await readRawValue();
+    expect(JSON.parse(afterRebuildRow.value).kekVersion).toBe(2);
+
+    // Decrypt-level proof, not just the version tag: the plaintext
+    // survived rotation + rebuild byte-identically.
+    expect(await resolver.get(KEY, keyDef, SYSTEM_TENANT_ID, "u1", stack.db)).toBe(PLAINTEXT);
+  });
+});

package/src/config/__tests__/write-helpers.test.ts

@@ -10,6 +10,7 @@ import type { KumikoError } from "@cosmicdrift/kumiko-framework/errors";
 import {
   checkScopeWriteAccess,
   hasConfigAccess,
+  resolvePiiSubject,
   resolveScopeIds,
   validatePattern,
   validateScope,
@@ -101,6 +102,28 @@ describe("resolveScopeIds", () => {
   });
 });
 
+describe("resolvePiiSubject (kumiko-platform#231/#459)", () => {
+  const tenant = "tenant-9" as TenantId;
+
+  test("tenant scope resolves to the tenant subject", () => {
+    expect(resolvePiiSubject(ConfigScopes.tenant, tenant, null)).toEqual({
+      kind: "tenant",
+      tenantId: tenant,
+    });
+  });
+
+  test("user scope resolves to the user subject — the row's target user, not necessarily the writer", () => {
+    expect(resolvePiiSubject(ConfigScopes.user, tenant, "user-1")).toEqual({
+      kind: "user",
+      userId: "user-1",
+    });
+  });
+
+  test("user scope without a userId throws instead of silently falling back to tenant", () => {
+    expect(() => resolvePiiSubject(ConfigScopes.user, tenant, null)).toThrow(/userId is null/);
+  });
+});
+
 describe("validateType", () => {
   const numberKey = createTenantConfig("number", {});
   const boolKey = createTenantConfig("boolean", {});

package/src/config/db/queries/resolver.ts

@@ -1,5 +1,5 @@
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 
 export type ConfigRow = {
@@ -11,7 +11,7 @@ export type ConfigRow = {
 };
 
 export async function selectConfigRowsForScope(
-  db: DbRunner,
+  db: DbRunner | TenantDb,
   systemTenantId: TenantId,
   tenantId: TenantId,
   userId: string,
@@ -27,7 +27,7 @@ export async function selectConfigRowsForScope(
 }
 
 export async function selectConfigRowsForKeys(
-  db: DbRunner,
+  db: DbRunner | TenantDb,
   keys: readonly string[],
   systemTenantId: TenantId,
   tenantId: TenantId,

package/src/config/feature.ts

@@ -1,4 +1,4 @@
-import type { DbConnection, EncryptionProvider, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import {
   type ConfigAccessor,
   type ConfigAccessorFactory,
@@ -13,12 +13,15 @@ import {
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
 import { cascadeQuery } from "./handlers/cascade.query";
 import { readinessQuery } from "./handlers/readiness.query";
+import { reencryptJob } from "./handlers/reencrypt.job";
 import { resetWrite } from "./handlers/reset.write";
 import { schemaQuery } from "./handlers/schema.query";
 import { setWrite } from "./handlers/set.write";
 import { valuesQuery } from "./handlers/values.query";
+import { CONFIG_FEATURE_I18N } from "./i18n";
 import type { ConfigResolver } from "./resolver";
 import { configValueEntity } from "./table";
 
@@ -27,7 +30,7 @@ export type ConfigContext = { readonly config: ConfigAccessor };
 export function createConfigFeature(): FeatureDefinition {
   return defineFeature("config", (r) => {
     r.describe(
-      "Stores per-tenant (and optionally per-user) configuration values with a multi-layer cascade: user-row \u2192 tenant-row \u2192 system-row \u2192 app-override (deploy-time `AppConfigOverrides`) \u2192 computed \u2192 feature default. Access a value in handlers via `ctx.config(handle)`, declare keys with `r.config({ keys: { ... } })` inside a feature's registry callback, and optionally mark them `encrypted: true` to route storage through an `EncryptionProvider`. Use this feature whenever a tenant admin needs to customise behaviour at runtime without a code deploy.",
+      "Stores per-tenant (and optionally per-user) configuration values with a multi-layer cascade: user-row \u2192 tenant-row \u2192 system-row \u2192 app-override (deploy-time `AppConfigOverrides`) \u2192 computed \u2192 feature default. Access a value in handlers via `ctx.config(handle)`, declare keys with `r.config({ keys: { ... } })` inside a feature's registry callback, and optionally mark them `encrypted: true` to route storage through the envelope cipher (versioned master key). Use this feature whenever a tenant admin needs to customise behaviour at runtime without a code deploy.",
     );
     r.uiHints({
       displayLabel: "Tenant Config Store",
@@ -55,6 +58,12 @@ export function createConfigFeature(): FeatureDefinition {
       readiness: r.queryHandler(readinessQuery),
     };
 
+    // KEK-rotation for encrypted values. Manual trigger — ops runs it once
+    // after adding a new master key version.
+    r.job("reencrypt", { trigger: { manual: true } }, reencryptJob);
+
+    r.translations({ keys: CONFIG_FEATURE_I18N });
+
     return { handlers, queries };
   });
 }
@@ -116,16 +125,14 @@ export function requireConfigResolver(ctx: HandlerContext, handlerName: string):
 // lazily so apps that never wire encryption still boot (and only crash
 // if a handler tries to write an encrypted key without the provider in
 // place, pointing at the exact wiring gap).
-export function requireConfigEncryption(
-  ctx: HandlerContext,
-  handlerName: string,
-): EncryptionProvider {
+export function requireConfigEncryption(ctx: HandlerContext, handlerName: string): EnvelopeCipher {
   if (!ctx.configEncryption) {
     throw new InternalError({
       message:
         `[${handlerName}] ctx.configEncryption missing — at least one config key declares ` +
-        `encrypted: true, so the boot wiring must pass an EncryptionProvider via ` +
-        `extraContext.configEncryption (same instance the resolver was built with).`,
+        `encrypted: true, so the boot wiring must pass an EnvelopeCipher via ` +
+        `extraContext.configEncryption (run{Prod,Dev}App wire it automatically from ` +
+        `KUMIKO_SECRETS_MASTER_KEY_V<n>; same instance the resolver was built with).`,
     });
   }
   return ctx.configEncryption;

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

@@ -2,6 +2,7 @@ import {
   type ConfigCascade,
   type ConfigCascadeLevel,
   defineQueryHandler,
+  isEncryptedAtRest,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { requireConfigResolver } from "../feature";
@@ -59,7 +60,7 @@ export const cascadeQuery = defineQueryHandler({
 
       // backing="secrets" is masked like encrypted — the resolver revealed the
       // plaintext for internal reads, but it must never reach the cascade UI.
-      if (keyDef.encrypted || keyDef.backing === "secrets") {
+      if (isEncryptedAtRest(keyDef)) {
         const maskedLevels: ConfigCascadeLevel[] = cascade.levels.map((l) => ({
           ...l,
           value: l.hasValue ? MASKED : l.value,