@cosmicdrift/kumiko-bundled-features 0.110.0 → 0.111.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.110.0",
+  "version": "0.111.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>",
@@ -95,11 +95,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.110.0",
-    "@cosmicdrift/kumiko-framework": "0.110.0",
-    "@cosmicdrift/kumiko-headless": "0.110.0",
-    "@cosmicdrift/kumiko-renderer": "0.110.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.110.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.111.0",
+    "@cosmicdrift/kumiko-framework": "0.111.0",
+    "@cosmicdrift/kumiko-headless": "0.111.0",
+    "@cosmicdrift/kumiko-renderer": "0.111.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.111.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.0",

package/src/auth-email-password/__tests__/account-lockout-no-redis.integration.test.ts

@@ -13,7 +13,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
@@ -22,6 +21,7 @@ import {
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
 import { createConfigFeature } from "../../config";
 import { createConfigResolver } from "../../config/resolver";
 import { configValuesTable } from "../../config/table";
@@ -42,8 +42,8 @@ const systemAdmin = TestUsers.systemAdmin;
 const encryptionKey = randomBytes(32).toString("base64");
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(encryptionKey);
-  const resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(encryptionKey);
+  const resolver = createConfigResolver({ cipher: encryption });
 
   stack = await setupTestStack({
     features: [

package/src/auth-email-password/__tests__/account-lockout.integration.test.ts

@@ -12,7 +12,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
@@ -21,6 +20,7 @@ import {
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
 import { createConfigFeature } from "../../config";
 import { createConfigResolver } from "../../config/resolver";
 import { configValuesTable } from "../../config/table";
@@ -48,8 +48,8 @@ const MAX_ATTEMPTS = 3;
 const LOCK_MINUTES = 1;
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(encryptionKey);
-  const resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(encryptionKey);
+  const resolver = createConfigResolver({ cipher: encryption });
 
   stack = await setupTestStack({
     features: [

package/src/auth-email-password/__tests__/auth-claims.integration.test.ts

@@ -1,7 +1,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -12,7 +11,7 @@ import {
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
-import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
+import { createTestEnvelopeCipher, seedRow } from "@cosmicdrift/kumiko-framework/testing";
 import { createConfigFeature } from "../../config";
 import { createConfigResolver } from "../../config/resolver";
 import { configValuesTable } from "../../config/table";
@@ -68,8 +67,8 @@ const segmentsByUserAndTenant = new Map<string, string>();
 const plansByTenant = new Map<TenantId, string>();
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(encryptionKey);
-  const resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(encryptionKey);
+  const resolver = createConfigResolver({ cipher: encryption });
 
   stack = await setupTestStack({
     features: [
@@ -260,8 +259,8 @@ describe("scenario 2: switch-tenant recomputes claims (no stale tenant-A claims
 
 describe("scenario 2.5: reserved separator + multi-feature isolation", () => {
   test("one feature returns key with ':' → only that key dropped, other features merge cleanly", async () => {
-    const localEncryption = createEncryptionProvider(encryptionKey);
-    const localResolver = createConfigResolver({ encryption: localEncryption });
+    const localEncryption = createTestEnvelopeCipher(encryptionKey);
+    const localResolver = createConfigResolver({ cipher: localEncryption });
     // A polluted feature that tries to smuggle in a qualified-name-shaped
     // inner key (injecting ":" would otherwise let it spoof another
     // feature's prefix). Plus a clean companion to prove the drop is
@@ -337,8 +336,8 @@ describe("scenario 2.5: reserved separator + multi-feature isolation", () => {
 
 describe("scenario 2.6: multi-feature drift warnings fire independently", () => {
   test("feature A + feature B both return undeclared keys → each logs its own warning", async () => {
-    const localEncryption = createEncryptionProvider(encryptionKey);
-    const localResolver = createConfigResolver({ encryption: localEncryption });
+    const localEncryption = createTestEnvelopeCipher(encryptionKey);
+    const localResolver = createConfigResolver({ cipher: localEncryption });
 
     // Capture warn() calls to verify drift warnings fire per-feature, not
     // globally collapsed.
@@ -425,8 +424,8 @@ describe("scenario 2.6: multi-feature drift warnings fire independently", () =>
 
 describe("scenario 3: a broken claims hook does not break login", () => {
   test("hook throws → login still succeeds, broken feature simply contributes nothing, warn logged with featureName+err", async () => {
-    const localEncryption = createEncryptionProvider(encryptionKey);
-    const localResolver = createConfigResolver({ encryption: localEncryption });
+    const localEncryption = createTestEnvelopeCipher(encryptionKey);
+    const localResolver = createConfigResolver({ cipher: localEncryption });
 
     // Capture warn-calls so the test can verify the resolver actually
     // logged the broken hook with featureName + err.message — previously

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

@@ -1,7 +1,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
 import { SYSTEM_TENANT_ID, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   createTestUser,
@@ -13,6 +12,7 @@ import {
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
 import {
+  createTestEnvelopeCipher,
   expectErrorIncludes,
   getSetCookieRaw,
   getSetCookieValue,
@@ -37,8 +37,8 @@ const systemAdmin = TestUsers.systemAdmin;
 const encryptionKey = randomBytes(32).toString("base64");
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(encryptionKey);
-  const resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(encryptionKey);
+  const resolver = createConfigResolver({ cipher: encryption });
 
   stack = await setupTestStack({
     features: [
@@ -374,8 +374,8 @@ describe("scenario 7b: login rate limiting", () => {
   let rlStack: TestStack;
 
   beforeAll(async () => {
-    const encryption = createEncryptionProvider(encryptionKey);
-    const resolver = createConfigResolver({ encryption });
+    const encryption = createTestEnvelopeCipher(encryptionKey);
+    const resolver = createConfigResolver({ cipher: encryption });
     const { createInMemoryLoginRateLimiter } = await import("@cosmicdrift/kumiko-framework/api");
 
     rlStack = await setupTestStack({

package/src/auth-email-password/__tests__/email-verification.integration.test.ts

@@ -1,7 +1,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
 import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
 import { SYSTEM_TENANT_ID, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
@@ -10,7 +9,11 @@ import {
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
-import { seedRow, updateRows } from "@cosmicdrift/kumiko-framework/testing";
+import {
+  createTestEnvelopeCipher,
+  seedRow,
+  updateRows,
+} from "@cosmicdrift/kumiko-framework/testing";
 import { Temporal } from "temporal-polyfill";
 import { createChannelEmailFeature, createInMemoryTransport } from "../../channel-email";
 import { createConfigFeature } from "../../config";
@@ -50,8 +53,8 @@ const appVerifyUrl = "https://app.example.com/verify";
 const appResetUrl = "https://app.example.com/reset";
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(encryptionKey);
-  const resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(encryptionKey);
+  const resolver = createConfigResolver({ cipher: encryption });
 
   stack = await setupTestStack({
     features: [

package/src/auth-email-password/__tests__/identity-v3-login.integration.test.ts

@@ -8,7 +8,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { pbkdf2Sync, randomBytes } from "node:crypto";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
@@ -18,6 +17,7 @@ import {
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
 import { createConfigFeature } from "../../config";
 import { createConfigResolver } from "../../config/resolver";
 import { configValuesTable } from "../../config/table";
@@ -50,8 +50,8 @@ function buildBmcStyleV3Hash(password: string, salt: Buffer): string {
 }
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(encryptionKey);
-  const resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(encryptionKey);
+  const resolver = createConfigResolver({ cipher: encryption });
 
   stack = await setupTestStack({
     features: [

package/src/auth-email-password/__tests__/password-reset.integration.test.ts

@@ -1,7 +1,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
 import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
 import { SYSTEM_TENANT_ID, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
@@ -10,7 +9,7 @@ import {
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
-import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
+import { createTestEnvelopeCipher, seedRow } from "@cosmicdrift/kumiko-framework/testing";
 import { Temporal } from "temporal-polyfill";
 import { createChannelEmailFeature, createInMemoryTransport } from "../../channel-email";
 import { createConfigFeature } from "../../config";
@@ -51,8 +50,8 @@ const resetSecret = randomBytes(32).toString("base64");
 const appResetUrl = "https://app.example.com/reset";
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(encryptionKey);
-  const resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(encryptionKey);
+  const resolver = createConfigResolver({ cipher: encryption });
 
   stack = await setupTestStack({
     features: [

package/src/auth-email-password/__tests__/public-routes-rate-limit.integration.test.ts

@@ -7,13 +7,13 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
 import {
   setupTestStack,
   type TestStack,
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
 import { createChannelEmailFeature, createInMemoryTransport } from "../../channel-email";
 import { createConfigFeature } from "../../config";
 import { createConfigResolver } from "../../config/resolver";
@@ -40,8 +40,8 @@ const resetSecret = randomBytes(32).toString("base64");
 const verifySecret = randomBytes(32).toString("base64");
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(encryptionKey);
-  const resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(encryptionKey);
+  const resolver = createConfigResolver({ cipher: encryption });
 
   stack = await setupTestStack({
     features: [

package/src/auth-email-password/__tests__/session-callbacks.integration.test.ts

@@ -1,7 +1,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
@@ -10,6 +9,7 @@ import {
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
 import * as jose from "jose";
 import { createConfigFeature } from "../../config";
 import { createConfigResolver } from "../../config/resolver";
@@ -90,8 +90,8 @@ const TENANT_A: TenantId = "00000000-0000-4000-8000-0000000000a1";
 const TENANT_B: TenantId = "00000000-0000-4000-8000-0000000000b1";
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(encryptionKey);
-  const resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(encryptionKey);
+  const resolver = createConfigResolver({ cipher: encryption });
 
   store = createFakeStore();
   sidStream = deterministicSids();

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

@@ -1,11 +1,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 {
-  createEncryptionProvider,
-  type DbConnection,
-  seedConfigValues,
-} from "@cosmicdrift/kumiko-framework/db";
+import { type DbConnection, seedConfigValues } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
   createSeed,
@@ -24,7 +20,10 @@ import {
   TestUsers,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
-import { expectErrorIncludes } from "@cosmicdrift/kumiko-framework/testing";
+import {
+  createTestEnvelopeCipher,
+  expectErrorIncludes,
+} from "@cosmicdrift/kumiko-framework/testing";
 import { z } from "zod";
 import { ConfigHandlers, ConfigQueries } from "../constants";
 import { createConfigAccessor, createConfigAccessorFactory, createConfigFeature } from "../feature";
@@ -257,8 +256,8 @@ const transportFeature = defineFeature("transport", (r) => {
 const testEncryptionKey = randomBytes(32).toString("base64");
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(testEncryptionKey);
-  resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(testEncryptionKey);
+  resolver = createConfigResolver({ cipher: encryption });
 
   stack = await setupTestStack({
     features: [

package/src/config/__tests__/encrypted-legacy-migration.integration.test.ts

@@ -0,0 +1,179 @@
+// Pins the legacy → envelope migration story for encrypted config values:
+//   1. rows written under the old CONFIG_ENCRYPTION_KEY format stay readable
+//      as long as the legacy key is wired as the cipher's fallback,
+//   2. reading an encrypted row WITHOUT any cipher throws (the pre-envelope
+//      code silently returned the ciphertext as the value),
+//   3. the reencrypt job migrates legacy rows onto the envelope format
+//      through the event-store executor (event payload carries the new
+//      envelope, so a projection rebuild no longer needs the legacy key),
+//      and is idempotent on re-run.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { asRawClient, fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  createEncryptionProvider,
+  createEventStoreExecutor,
+  createTenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  type AppContext,
+  access,
+  createRegistry,
+  createSystemUser,
+  createTenantConfig,
+  defineFeature,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEnvelopeCipher,
+  type EnvelopeCipher,
+  isStoredEnvelope,
+} from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTestMasterKeyProvider } 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 = "enc-mig:config:secret-pass";
+const TENANT: TenantId = testTenantId(1);
+const PLAINTEXT = "legacy-smtp-password";
+
+const keyDef = createTenantConfig("text", {
+  encrypted: true,
+  read: access.all,
+  write: access.all,
+});
+
+// legacy single-key provider — the pre-envelope CONFIG_ENCRYPTION_KEY world
+const legacy = createEncryptionProvider(randomBytes(32).toString("base64"));
+const masterKeyProvider = createTestMasterKeyProvider();
+const cipherWithLegacy = createEnvelopeCipher(masterKeyProvider, { legacy });
+const cipherWithoutLegacy = createEnvelopeCipher(masterKeyProvider);
+
+const encMigFeature = defineFeature("enc-mig", (r) => {
+  r.config({ keys: { "secret-pass": keyDef } });
+});
+
+const executor = createEventStoreExecutor(configValuesTable, configValueEntity, {
+  entityName: "config-value",
+});
+
+let stack: TestStack;
+
+async function seedLegacyRow(): Promise<string> {
+  const legacyValue = legacy.encrypt(JSON.stringify(PLAINTEXT));
+  const systemUser = createSystemUser(TENANT);
+  const tdb = createTenantDb(stack.db, TENANT, "system");
+  const result = await executor.create(
+    { key: KEY, value: legacyValue, tenantId: TENANT, userId: null },
+    systemUser,
+    tdb,
+  );
+  if (!result.isSuccess) throw new Error(`seed failed: ${result.error.code}`);
+  return (result.data as { id: string }).id;
+}
+
+async function readStoredValue(): Promise<string> {
+  const row = await fetchOne<{ value: string }>(stack.db, configValuesTable, {
+    key: KEY,
+    tenantId: TENANT,
+  });
+  if (!row) throw new Error("row missing");
+  return row.value;
+}
+
+type ReencryptCtx = Pick<AppContext, "db" | "masterKeyProvider" | "configEncryption" | "registry">;
+function jobCtx(cipher: EnvelopeCipher): Parameters<typeof reencryptJob>[1] {
+  const ctx: ReencryptCtx = {
+    db: stack.db,
+    masterKeyProvider,
+    configEncryption: cipher,
+    registry: stack.registry,
+  };
+  return ctx as unknown as Parameters<typeof reencryptJob>[1];
+}
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [createConfigFeature(), encMigFeature] });
+  await unsafePushTables(stack.db, { configValuesTable });
+  await seedLegacyRow();
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("legacy encrypted config rows", () => {
+  test("stay readable through the cipher's legacy fallback (get + cascade path)", async () => {
+    const resolver = createConfigResolver({ cipher: cipherWithLegacy });
+    const value = await resolver.get(KEY, keyDef, TENANT, "u1", stack.db);
+    expect(value).toBe(PLAINTEXT);
+
+    const cascade = await resolver.getCascade(KEY, keyDef, TENANT, "u1", stack.db);
+    const active = cascade.levels.find((l) => l.hasValue);
+    expect(active?.value).toBe(PLAINTEXT);
+  });
+
+  test("throw without any cipher instead of leaking ciphertext as the value", async () => {
+    const resolver = createConfigResolver({});
+    await expect(resolver.get(KEY, keyDef, TENANT, "u1", stack.db)).rejects.toThrow(
+      /encrypted but no cipher/,
+    );
+    await expect(resolver.getCascade(KEY, keyDef, TENANT, "u1", stack.db)).rejects.toThrow(
+      /encrypted but no cipher/,
+    );
+  });
+
+  test("throw with a remediation hint when the legacy key is missing", async () => {
+    const resolver = createConfigResolver({ cipher: cipherWithoutLegacy });
+    await expect(resolver.get(KEY, keyDef, TENANT, "u1", stack.db)).rejects.toThrow(/legacy/);
+  });
+});
+
+describe("config:reencrypt job", () => {
+  test("migrates the legacy row to envelope format via the executor", async () => {
+    expect((await readStoredValue()).startsWith("{")).toBe(false);
+
+    await reencryptJob({}, jobCtx(cipherWithLegacy));
+
+    const stored = await readStoredValue();
+    expect(stored.startsWith("{")).toBe(true);
+    expect(isStoredEnvelope(JSON.parse(stored))).toBe(true);
+
+    // decryptable WITHOUT the legacy key now — retiring CONFIG_ENCRYPTION_KEY
+    // after a clean run is safe
+    const resolver = createConfigResolver({ cipher: cipherWithoutLegacy });
+    expect(await resolver.get(KEY, keyDef, TENANT, "u1", stack.db)).toBe(PLAINTEXT);
+  });
+
+  test("event payload carries the new envelope — rebuild-safe without legacy key", async () => {
+    // The migration wrote a configValue.updated event whose payload holds
+    // the envelope value; replaying events verbatim reproduces the
+    // migrated state, so the final projection never needs the legacy key.
+    const registryCheck = createRegistry([createConfigFeature(), encMigFeature]);
+    expect(registryCheck.getConfigKey(KEY)?.encrypted).toBe(true);
+
+    const events = await asRawClient(stack.db).unsafe<{
+      payload: { changes?: { value?: string } };
+    }>(
+      `SELECT payload FROM kumiko_events WHERE aggregate_type = 'config-value' AND type LIKE '%.updated' ORDER BY created_at DESC LIMIT 1`,
+    );
+    const lastValue = events[0]?.payload?.changes?.value;
+    expect(typeof lastValue).toBe("string");
+    expect((lastValue as string).startsWith("{")).toBe(true);
+  });
+
+  test("is idempotent — a second run migrates nothing", async () => {
+    const before = await readStoredValue();
+    await reencryptJob({}, jobCtx(cipherWithLegacy));
+    expect(await readStoredValue()).toBe(before);
+  });
+});

package/src/config/__tests__/inherited-redaction.integration.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
-import { createEncryptionProvider, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
   type ConfigCascade,
@@ -14,6 +14,7 @@ import {
   TestUsers,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
 import { ConfigHandlers, ConfigQueries } from "../constants";
 import { createConfigAccessorFactory, createConfigFeature } from "../feature";
 import { type ConfigResolver, createConfigResolver } from "../resolver";
@@ -76,8 +77,8 @@ const platformFeature = defineFeature("platform", (r) => {
 });
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(randomBytes(32).toString("base64"));
-  resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(randomBytes(32).toString("base64"));
+  resolver = createConfigResolver({ cipher: encryption });
 
   stack = await setupTestStack({
     features: [configFeature, platformFeature],

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,8 +13,10 @@ 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";
@@ -27,7 +29,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 +57,12 @@ export function createConfigFeature(): FeatureDefinition {
       readiness: r.queryHandler(readinessQuery),
     };
 
+    // Migration + KEK-rotation for encrypted values (legacy-format →
+    // envelope, old kekVersion → current). Manual trigger — ops runs it
+    // once after adding a new master key version or before retiring the
+    // legacy CONFIG_ENCRYPTION_KEY.
+    r.job("reencrypt", { trigger: { manual: true } }, reencryptJob);
+
     return { handlers, queries };
   });
 }
@@ -116,16 +124,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;