@cosmicdrift/kumiko-framework 0.110.0 → 0.111.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.110.0",
+  "version": "0.111.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.110.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.111.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/db/__tests__/config-seed.integration.test.ts

@@ -10,10 +10,11 @@ import {
   SYSTEM_TENANT_ID,
 } from "../../engine";
 import type { ConfigSeedDef, Registry } from "../../engine/types";
+import { createEnvMasterKeyProvider } from "../../secrets/env-master-key-provider";
+import { createEnvelopeCipher } from "../../secrets/envelope-cipher";
 import { unsafeCreateEntityTable } from "../../stack";
 import { ensureTemporalPolyfill } from "../../time/polyfill";
 import { seedConfigValues } from "../config-seed";
-import { createEncryptionProvider } from "../encryption";
 import { buildEntityTable } from "../table-builder";
 
 // --- Test Entity ---
@@ -51,8 +52,15 @@ const mockRegistry = {
 } as unknown as Registry;
 
 // --- Helpers ---
-const encryption = createEncryptionProvider(
-  Buffer.from("0123456789abcdef0123456789abcdef").toString("base64"),
+const encryption = createEnvelopeCipher(
+  createEnvMasterKeyProvider({
+    env: {
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+      KUMIKO_SECRETS_MASTER_KEY_V1: Buffer.from("0123456789abcdef0123456789abcdef").toString(
+        "base64",
+      ),
+    },
+  }),
 );
 
 let testDb: BunTestDb;
@@ -214,7 +222,7 @@ describe("seedConfigValues", () => {
 
     await expect(
       seedConfigValues(seeds, configTable, configEntity, mockRegistry, testDb.db),
-    ).rejects.toThrow(/encrypted but no EncryptionProvider/);
+    ).rejects.toThrow(/encrypted but no EnvelopeCipher/);
   });
 
   test("encrypted seed with provider stores ciphertext, not plaintext", async () => {
@@ -240,7 +248,7 @@ describe("seedConfigValues", () => {
     // resolver later runs `decrypt → JSON.parse` to get the primitive
     // back; we replay the same round-trip here.
     expect(row!.value).not.toContain("sk_live_secret_token");
-    expect(JSON.parse(encryption.decrypt(row!.value))).toBe("sk_live_secret_token");
+    expect(JSON.parse(await encryption.decrypt(row!.value))).toBe("sk_live_secret_token");
   });
 
   test("race-safe parallel boot — two concurrent calls result in 1 created + 1 skipped", async () => {

package/src/db/__tests__/entity-field-encryption.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { createEntity, createTextField } from "../../engine";
-import { createEncryptionProvider } from "../encryption";
+import { createTestEnvelopeCipher } from "../../testing";
 import {
   collectEncryptedFieldNames,
   decryptEntityFieldValues,
@@ -18,25 +18,25 @@ describe("entity-field-encryption", () => {
     },
   });
   const encryptedFields = collectEncryptedFieldNames(entity);
-  const encryption = createEncryptionProvider(TEST_KEY);
+  const encryption = createTestEnvelopeCipher(TEST_KEY);
 
   test("collectEncryptedFieldNames finds encrypted text fields only", () => {
     expect([...encryptedFields]).toEqual(["secretNote"]);
   });
 
-  test("encrypt on write / decrypt on read round-trip", () => {
+  test("encrypt on write / decrypt on read round-trip", async () => {
     const plain = { email: "a@b.de", secretNote: "top secret" };
-    const stored = encryptEntityFieldValues(plain, encryptedFields, encryption);
+    const stored = await encryptEntityFieldValues(plain, encryptedFields, encryption);
     expect(stored["email"]).toBe(plain.email);
     expect(stored["secretNote"]).not.toBe("top secret");
 
-    const read = decryptEntityFieldValues(stored, encryptedFields, encryption);
+    const read = await decryptEntityFieldValues(stored, encryptedFields, encryption);
     expect(read).toEqual(plain);
   });
 
-  test("onlyKeys limits encryption to changed fields", () => {
+  test("onlyKeys limits encryption to changed fields", async () => {
     const row = { email: "a@b.de", secretNote: "note" };
-    const stored = encryptEntityFieldValues(row, encryptedFields, encryption, {
+    const stored = await encryptEntityFieldValues(row, encryptedFields, encryption, {
       onlyKeys: ["secretNote"],
     });
     expect(stored["email"]).toBe("a@b.de");

package/src/db/__tests__/event-store-executor.integration.test.ts

@@ -10,7 +10,7 @@ import {
   testTenantId,
   unsafeCreateEntityTable,
 } from "../../stack";
-import { createEncryptionProvider } from "../encryption";
+import { createTestEnvelopeCipher } from "../../testing";
 import { resetEntityFieldEncryptionCacheForTests } from "../entity-field-encryption";
 import { createEventStoreExecutor } from "../event-store-executor";
 import { buildEntityTable } from "../table-builder";
@@ -324,7 +324,7 @@ const encryptedSoftDeleteEntity = createEntity({
 const encryptedSoftDeleteTable = buildEntityTable("esExecEncSoft", encryptedSoftDeleteEntity);
 
 describe("event-store-executor — encrypted fields", () => {
-  const encryption = createEncryptionProvider(ENCRYPTION_TEST_KEY);
+  const encryption = createTestEnvelopeCipher(ENCRYPTION_TEST_KEY);
   const crud = createEventStoreExecutor(encryptedTable, encryptedEntity, {
     entityName: "esExecEncrypted",
     encryption,
@@ -337,7 +337,6 @@ describe("event-store-executor — encrypted fields", () => {
   );
 
   beforeAll(async () => {
-    process.env["ENCRYPTION_KEY"] = ENCRYPTION_TEST_KEY;
     resetEntityFieldEncryptionCacheForTests();
     await unsafeCreateEntityTable(testDb.db, encryptedEntity, "esExecEncrypted");
     await unsafeCreateEntityTable(testDb.db, encryptedSoftDeleteEntity, "esExecEncSoft");
@@ -524,7 +523,7 @@ describe("event-store-executor — entity cache + encrypted fields", () => {
       store.delete(`${tenantId}:${name}:${id}`);
     },
   };
-  const encryption = createEncryptionProvider(ENCRYPTION_TEST_KEY);
+  const encryption = createTestEnvelopeCipher(ENCRYPTION_TEST_KEY);
   const cachedEncryptedCrud = createEventStoreExecutor(encryptedTable, encryptedEntity, {
     entityName: "esExecEncrypted",
     entityCache,

package/src/db/config-seed.ts

@@ -2,8 +2,8 @@ import { v5 as uuidv5 } from "uuid";
 import type { EntityDefinition } from "../engine";
 import { createSystemUser, SYSTEM_TENANT_ID } from "../engine";
 import type { ConfigSeedDef, Registry } from "../engine/types";
+import type { EnvelopeCipher } from "../secrets/envelope-cipher";
 import type { DbConnection } from "./connection";
-import type { EncryptionProvider } from "./encryption";
 import { createEventStoreExecutor } from "./event-store-executor";
 import type { EntityTable } from "./table-builder";
 import { createTenantDb } from "./tenant-db";
@@ -30,7 +30,7 @@ export async function seedConfigValues<E extends EntityDefinition>(
   entity: E,
   registry: Registry,
   db: DbConnection,
-  encryption?: EncryptionProvider,
+  cipher?: EnvelopeCipher,
 ): Promise<{ created: number; skipped: number }> {
   let created = 0;
   let skipped = 0;
@@ -48,12 +48,12 @@ export async function seedConfigValues<E extends EntityDefinition>(
       continue;
     }
 
-    // Encrypted keys without an encryption provider would silently write
-    // plaintext to a column the resolver later tries to decrypt — fail
-    // loud at boot, not on first read in prod.
-    if (keyDef.encrypted && !encryption) {
+    // Encrypted keys without a cipher would silently write plaintext to a
+    // column the resolver later tries to decrypt — fail loud at boot, not
+    // on first read in prod.
+    if (keyDef.encrypted && !cipher) {
       throw new Error(
-        `seedConfigValues: key "${seed.key}" is encrypted but no EncryptionProvider was supplied.`,
+        `seedConfigValues: key "${seed.key}" is encrypted but no EnvelopeCipher was supplied.`,
       );
     }
 
@@ -77,8 +77,8 @@ export async function seedConfigValues<E extends EntityDefinition>(
     const aggregateId = uuidv5(idSource, CONFIG_SEED_NS);
 
     let value = JSON.stringify(seed.value);
-    if (keyDef.encrypted && encryption) {
-      value = encryption.encrypt(value);
+    if (keyDef.encrypted && cipher) {
+      value = await cipher.encrypt(value, { tenantId });
     }
 
     const payload: Record<string, unknown> = {

package/src/db/encryption.ts

@@ -9,6 +9,13 @@ export type EncryptionProvider = {
   decrypt(ciphertext: string): string;
 };
 
+/**
+ * @deprecated Legacy single-key format: base64(iv+tag+ct) with NO key id —
+ * a key change makes existing ciphertexts permanently undecryptable. Use
+ * `createEnvelopeCipher` (@cosmicdrift/kumiko-framework/secrets) for new code; this
+ * provider remains only as the decrypt-fallback for pre-envelope values
+ * (EnvelopeCipherOptions.legacy) until a re-encrypt job migrated them.
+ */
 export function createEncryptionProvider(key: string): EncryptionProvider {
   // Key must be 32 bytes for AES-256
   const keyBuffer = Buffer.from(key, "base64");

package/src/db/entity-field-encryption.ts

@@ -1,6 +1,13 @@
-import type { EntityDefinition } from "../engine/types";
-import type { EncryptionProvider } from "./encryption";
-import { createEncryptionProvider } from "./encryption";
+// Entity-field encryption (`encrypted: true` on text/longText fields),
+// backed by the same envelope cipher as encrypted config values: JSON
+// StoredEnvelope in the TEXT column, kekVersion per value, legacy
+// single-key ciphertexts (pre-envelope ENCRYPTION_KEY era) readable via
+// the cipher's legacy fallback until re-encrypted.
+
+import type { EntityDefinition, TenantId } from "../engine/types";
+import { createEnvMasterKeyProvider } from "../secrets/env-master-key-provider";
+import type { EnvelopeCipher } from "../secrets/envelope-cipher";
+import type { KeyScope } from "../secrets/types";
 
 export function collectEncryptedFieldNames(entity: EntityDefinition): ReadonlySet<string> {
   const names = new Set<string>();
@@ -12,70 +19,120 @@ export function collectEncryptedFieldNames(entity: EntityDefinition): ReadonlySe
   return names;
 }
 
-function encryptFieldValue(
+// BYOK hook: thread the row's tenant to the cipher when the row carries one
+// (system-scope rows may not).
+function scopeOf(row: Record<string, unknown>): KeyScope | undefined {
+  const tenantId = row["tenantId"];
+  return typeof tenantId === "string" ? { tenantId: tenantId as TenantId } : undefined; // @cast-boundary db-row
+}
+
+async function encryptFieldValue(
   fieldName: string,
   value: unknown,
-  encryption: EncryptionProvider,
-): string {
+  cipher: EnvelopeCipher,
+  scope: KeyScope | undefined,
+): Promise<string> {
   if (value === null || value === undefined) {
     throw new Error(`encrypted field "${fieldName}" cannot be null or undefined`);
   }
   if (typeof value !== "string") {
     throw new Error(`encrypted field "${fieldName}" must be a string, got ${typeof value}`);
   }
-  return encryption.encrypt(value);
+  return cipher.encrypt(value, scope);
 }
 
-export function encryptEntityFieldValues(
+export async function encryptEntityFieldValues(
   row: Record<string, unknown>,
   encryptedFields: ReadonlySet<string>,
-  encryption: EncryptionProvider,
+  cipher: EnvelopeCipher,
   opts?: { onlyKeys?: Iterable<string> },
-): Record<string, unknown> {
+): Promise<Record<string, unknown>> {
   if (encryptedFields.size === 0) return row;
   const only = opts?.onlyKeys ? new Set(opts.onlyKeys) : null;
   const out = { ...row };
+  const scope = scopeOf(row);
   for (const name of encryptedFields) {
     if (only && !only.has(name)) continue;
     if (!(name in out)) continue;
     const value = out[name];
     if (value === null || value === undefined) continue;
-    out[name] = encryptFieldValue(name, value, encryption);
+    out[name] = await encryptFieldValue(name, value, cipher, scope);
   }
   return out;
 }
 
-export function decryptEntityFieldValues(
+export async function decryptEntityFieldValues(
   row: Record<string, unknown>,
   encryptedFields: ReadonlySet<string>,
-  encryption: EncryptionProvider,
-): Record<string, unknown> {
+  cipher: EnvelopeCipher,
+): Promise<Record<string, unknown>> {
   if (encryptedFields.size === 0) return row;
   const out = { ...row };
+  const scope = scopeOf(row);
   for (const name of encryptedFields) {
     const value = out[name];
     if (value === null || value === undefined) continue;
     if (typeof value !== "string") continue;
-    out[name] = encryption.decrypt(value);
+    out[name] = await cipher.decrypt(value, scope);
   }
   return out;
 }
 
-let cachedProvider: EncryptionProvider | undefined;
+// Boot-injected app-wide cipher. run{Prod,Dev}App (and test setups that
+// exercise encrypted fields) call configureEntityFieldEncryption once with
+// the same cipher instance the config feature uses; executors resolve it
+// lazily so entities without encrypted fields never touch it.
+let injectedCipher: EnvelopeCipher | undefined;
 
-export function resolveEntityFieldEncryption(): EncryptionProvider {
-  if (cachedProvider) return cachedProvider;
-  const key = process.env["ENCRYPTION_KEY"];
-  if (!key) {
+export function configureEntityFieldEncryption(cipher: EnvelopeCipher | undefined): void {
+  injectedCipher = cipher;
+}
+
+export function resolveEntityFieldEncryption(): EnvelopeCipher {
+  if (!injectedCipher) {
     throw new Error(
-      "ENCRYPTION_KEY environment variable is required (encrypted entity fields in use)",
+      "entity-field encryption is not configured — encrypted entity fields need a master key " +
+        "(KUMIKO_SECRETS_MASTER_KEY_V<n>); run{Prod,Dev}App wire the cipher automatically, " +
+        "custom boots call configureEntityFieldEncryption(cipher).",
     );
   }
-  cachedProvider = createEncryptionProvider(key);
-  return cachedProvider;
+  return injectedCipher;
+}
+
+// Non-throwing probe for callers that degrade gracefully (DSGVO export
+// replaces encrypted fields with an explicit marker instead of failing
+// the whole export when no cipher is wired).
+export function configuredEntityFieldEncryption(): EnvelopeCipher | undefined {
+  return injectedCipher;
 }
 
 /** @internal test-only */
 export function resetEntityFieldEncryptionCacheForTests(): void {
-  cachedProvider = undefined;
+  injectedCipher = undefined;
+}
+
+// Boot-time availability probe for validateBoot: either a cipher was
+// injected, or the env keyring must be constructible — eager construction
+// surfaces missing AND malformed keys (wrong length, bad base64) at boot
+// instead of on the first encrypted read in prod. validateBoot runs before
+// configureEntityFieldEncryption, so the env probe is the common path.
+export function validateEntityFieldEncryptionAvailable(): void {
+  // skip: an injected cipher (test seam / custom KMS) satisfies availability
+  if (injectedCipher) return;
+  try {
+    createEnvMasterKeyProvider({
+      env: {
+        ...process.env,
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION:
+          process.env["KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION"] ?? "1",
+      },
+    });
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `encrypted entity fields in use but no usable master key (${reason}) — set ` +
+        "KUMIKO_SECRETS_MASTER_KEY_V1 (32 bytes, base64) or inject a cipher via " +
+        "configureEntityFieldEncryption().",
+    );
+  }
 }

package/src/db/event-store-executor.ts

@@ -39,13 +39,13 @@ import {
 } from "../event-store";
 import type { EntityCache } from "../pipeline/entity-cache";
 import type { SearchAdapter } from "../search/types";
+import type { EnvelopeCipher } from "../secrets/envelope-cipher";
 import { assertUnreachable, generateId } from "../utils";
 import { applyEntityEvent } from "./apply-entity-event";
 import { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types";
 import type { DbRow } from "./connection";
 import { decodeCursor, encodeCursor } from "./cursor";
 import type { TableColumns } from "./dialect";
-import type { EncryptionProvider } from "./encryption";
 import {
   collectEncryptedFieldNames,
   decryptEntityFieldValues,
@@ -119,8 +119,8 @@ export type EventStoreExecutorOptions = {
   searchAdapter?: SearchAdapter;
   entityName: string; // required — the aggregateType marker on every event
   entityCache?: EntityCache;
-  /** Override ENCRYPTION_KEY for entity fields marked `encrypted: true`. */
-  encryption?: EncryptionProvider;
+  /** Override the boot-injected cipher for fields marked `encrypted: true`. */
+  encryption?: EnvelopeCipher;
 };
 
 // F8 helper: PG-23505 (unique-violation) catched aus applyEntityEvent
@@ -307,24 +307,28 @@ export function createEventStoreExecutor(
   const encryptedFields = collectEncryptedFieldNames(entity);
   const hasEncryptedFields = encryptedFields.size > 0;
 
-  function encryptionProvider(): EncryptionProvider {
+  function fieldCipher(): EnvelopeCipher {
     if (options.encryption) return options.encryption;
     return resolveEntityFieldEncryption();
   }
 
-  function encryptForStorage(
+  // Async on purpose: the envelope cipher wraps/unwraps DEKs via the
+  // MasterKeyProvider. Callers MUST await — a missed await here writes
+  // "[object Promise]" into the projection, which the Promise return
+  // types turn into a compile error at every call site.
+  async function encryptForStorage(
     row: Record<string, unknown>,
     onlyKeys?: Iterable<string>,
-  ): Record<string, unknown> {
+  ): Promise<Record<string, unknown>> {
     if (!hasEncryptedFields) return row;
-    return encryptEntityFieldValues(row, encryptedFields, encryptionProvider(), {
+    return encryptEntityFieldValues(row, encryptedFields, fieldCipher(), {
       ...(onlyKeys !== undefined && { onlyKeys }),
     });
   }
 
-  function decryptForRead(row: Record<string, unknown>): Record<string, unknown> {
+  async function decryptForRead(row: Record<string, unknown>): Promise<Record<string, unknown>> {
     if (!hasEncryptedFields) return row;
-    return decryptEntityFieldValues(row, encryptedFields, encryptionProvider());
+    return decryptEntityFieldValues(row, encryptedFields, fieldCipher());
   }
 
   function applyDefaults(payload: Record<string, unknown>): Record<string, unknown> {
@@ -356,7 +360,7 @@ export function createEventStoreExecutor(
   async function loadById(id: EntityId, db: TenantDb): Promise<Record<string, unknown> | null> {
     const row = await db.fetchOne(table, idFilter(id));
     if (!row) return null;
-    return decryptForRead(rehydrateCompoundTypes(row as DbRow, entity));
+    return await decryptForRead(rehydrateCompoundTypes(row as DbRow, entity));
   }
 
   // Archive guard for the CRUD write paths. Archived streams are read-only —
@@ -465,7 +469,7 @@ export function createEventStoreExecutor(
       // Alle Compound-Types (locatedTimestamp, money, ...) gehen durch
       // dieselbe Pipeline. Caller schickt combined API-Form, Framework
       // speichert flat DB-Form. Siehe db/compound-types.ts.
-      const flatData = encryptForStorage(flattenCompoundTypes(data, entity));
+      const flatData = await encryptForStorage(flattenCompoundTypes(data, entity));
 
       // 1. Append event (same TX as the projection write — both must succeed
       //    or both roll back; the dispatcher wraps both in one transaction).
@@ -541,7 +545,9 @@ export function createEventStoreExecutor(
       const row = result.row;
       // Read-Side Auto-Convert: DB-Form → API-combined-Form für alle
       // Compound-Types in einem Pass.
-      const projection = decryptForRead(rehydrateCompoundTypes(row as DbRow, entity) as DbRow);
+      const projection = await decryptForRead(
+        rehydrateCompoundTypes(row as DbRow, entity) as DbRow,
+      );
 
       if (entityCache && entityName) {
         await entityCache.del(user.tenantId, entityName, aggregateId);
@@ -644,7 +650,7 @@ export function createEventStoreExecutor(
 
       try {
         // Compound-Types Auto-Convert (alle in einem Pass).
-        const flatChanges = encryptForStorage(
+        const flatChanges = await encryptForStorage(
           flattenCompoundTypes(payload.changes, entity),
           Object.keys(payload.changes),
         );
@@ -667,7 +673,7 @@ export function createEventStoreExecutor(
           type: entityEventName(entityName, "updated"),
           payload: {
             changes: stripSensitive(flatChanges),
-            previous: stripSensitive(encryptForStorage(previous)),
+            previous: stripSensitive(await encryptForStorage(previous)),
           },
           metadata: buildEventMetadata(user),
         });
@@ -695,7 +701,7 @@ export function createEventStoreExecutor(
           return writeFailure(new InternalError({ message: "projection update returned no row" }));
         }
         const row = result.row;
-        const data = decryptForRead(rehydrateCompoundTypes(row as DbRow, entity) as DbRow);
+        const data = await decryptForRead(rehydrateCompoundTypes(row as DbRow, entity) as DbRow);
 
         if (entityCache && entityName) {
           await entityCache.del(user.tenantId, entityName, payload.id);
@@ -777,7 +783,7 @@ export function createEventStoreExecutor(
         tenantId: streamTenantFor(user),
         expectedVersion: currentVersion,
         type: entityEventName(entityName, "deleted"),
-        payload: { previous: stripSensitive(encryptForStorage(existing)) },
+        payload: { previous: stripSensitive(await encryptForStorage(existing)) },
         metadata: buildEventMetadata(user),
       });
 
@@ -810,7 +816,7 @@ export function createEventStoreExecutor(
     async forget(payload, user, db) {
       const raw = await db.fetchOne<Record<string, unknown>>(table, { id: payload.id });
       if (!raw) return writeFailure(new NotFoundError(entityName, payload.id));
-      const existing = decryptForRead(rehydrateCompoundTypes(raw as DbRow, entity) as DbRow);
+      const existing = await decryptForRead(rehydrateCompoundTypes(raw as DbRow, entity) as DbRow);
 
       if (!userCanWriteFieldRow(user, entity.access?.write, existing, existing)) {
         return writeFailure(
@@ -937,7 +943,7 @@ export function createEventStoreExecutor(
       // row and `previous` snapshot must be plaintext for `encrypted` fields,
       // same as every other executor method — `data`/`restored` are raw rows
       // (selectMany / applyEntityEvent), never decrypted before this point.
-      const restoredHydrated = decryptForRead(
+      const restoredHydrated = await decryptForRead(
         rehydrateCompoundTypes(restored as DbRow, entity) as DbRow,
       );
 
@@ -948,7 +954,7 @@ export function createEventStoreExecutor(
           id: payload.id,
           data: restoredHydrated,
           changes: { isDeleted: false },
-          previous: decryptForRead(data),
+          previous: await decryptForRead(data),
           isNew: false,
           entityName,
           event,
@@ -1082,8 +1088,10 @@ export function createEventStoreExecutor(
       const rawRows = await executeRawQuery<Record<string, unknown>>(db.raw, listSql, params);
       // Read-Side rehydrate pro Row + snake→camel coercion für driver-agnostic Feldnamen
       const tableInfo = extractTableInfo(table);
-      const rows = rawRows.map((r) =>
-        coerceRow(decryptForRead(rehydrateCompoundTypes(r, entity)), tableInfo),
+      const rows = await Promise.all(
+        rawRows.map(async (r) =>
+          coerceRow(await decryptForRead(rehydrateCompoundTypes(r, entity)), tableInfo),
+        ),
       );
 
       // list rows carry the READ-ROW version (display-only), never an optimistic-lock
@@ -1156,19 +1164,24 @@ export function createEventStoreExecutor(
           // Cached rows are stored re-encrypted (see the `set` below) so an
           // `encrypted` field's plaintext never sits in a second at-rest
           // store (Redis) the field-encryption feature doesn't cover.
-          return withStreamVersion(decryptForRead(cached));
+          return withStreamVersion(await decryptForRead(cached));
         }
       }
 
       const rows = await loadWithOwnership(db, idWhere, ownership);
       const raw = rows[0];
       if (!raw) return null;
-      const row = decryptForRead(rehydrateCompoundTypes(raw, entity));
+      const row = await decryptForRead(rehydrateCompoundTypes(raw, entity));
       const rowInfo = extractTableInfo(table);
       const coerced = coerceRow(row, rowInfo);
 
       if (entityCache && entityName) {
-        await entityCache.set(user.tenantId, entityName, payload.id, encryptForStorage(coerced));
+        await entityCache.set(
+          user.tenantId,
+          entityName,
+          payload.id,
+          await encryptForStorage(coerced),
+        );
       }
 
       return withStreamVersion(coerced);

package/src/db/index.ts

@@ -38,8 +38,11 @@ export type { EncryptionProvider } from "./encryption";
 export { createEncryptionProvider } from "./encryption";
 export {
   collectEncryptedFieldNames,
+  configuredEntityFieldEncryption,
+  configureEntityFieldEncryption,
   decryptEntityFieldValues,
   encryptEntityFieldValues,
+  resetEntityFieldEncryptionCacheForTests,
 } from "./entity-field-encryption";
 export type {
   BuildEntityTableMetaOptions,

package/src/engine/__tests__/boot-validator.test.ts

@@ -106,8 +106,10 @@ describe("boot-validator", () => {
     expect(() => validateBoot(features)).toThrow(/token.*cannot be both encrypted and sortable/i);
   });
 
-  test("allows encrypted field when ENCRYPTION_KEY is set", () => {
-    process.env["ENCRYPTION_KEY"] = "test-key";
+  test("allows encrypted field when a master key keyring is available", () => {
+    process.env["KUMIKO_SECRETS_MASTER_KEY_V1"] = Buffer.from(
+      "0123456789abcdef0123456789abcdef",
+    ).toString("base64");
     try {
       const features = [
         defineFeature("a", (r) => {
@@ -124,12 +126,34 @@ describe("boot-validator", () => {
       ];
       expect(() => validateBoot(features)).not.toThrow();
     } finally {
-      delete process.env["ENCRYPTION_KEY"];
+      delete process.env["KUMIKO_SECRETS_MASTER_KEY_V1"];
+    }
+  });
+
+  test("throws at boot when the master key is malformed (not 32 bytes)", () => {
+    process.env["KUMIKO_SECRETS_MASTER_KEY_V1"] = Buffer.from("too-short").toString("base64");
+    try {
+      const features = [
+        defineFeature("a", (r) => {
+          r.entity(
+            "secret",
+            createEntity({
+              table: "Secrets",
+              fields: {
+                apiKey: { type: "text", encrypted: true },
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/master key/i);
+    } finally {
+      delete process.env["KUMIKO_SECRETS_MASTER_KEY_V1"];
     }
   });
 
-  test("throws when encrypted fields exist but ENCRYPTION_KEY not set", () => {
-    delete process.env["ENCRYPTION_KEY"];
+  test("throws when encrypted fields exist but no master key is available", () => {
+    delete process.env["KUMIKO_SECRETS_MASTER_KEY_V1"];
     const features = [
       defineFeature("a", (r) => {
         r.entity(
@@ -143,16 +167,16 @@ describe("boot-validator", () => {
         );
       }),
     ];
-    expect(() => validateBoot(features)).toThrow(/ENCRYPTION_KEY.*required/i);
+    expect(() => validateBoot(features)).toThrow(/master key/i);
   });
 
-  test("throws when longText encrypted field exists but ENCRYPTION_KEY not set", () => {
+  test("throws when longText encrypted field exists but no master key is available", () => {
     // Drift-pin Sprint-5b-vorab-Audit Issue 1: validateEncryptedFields
     // hatte `if (field.type !== "text") continue;` und ignorierte
     // longText-encrypted-fields silently — ENCRYPTION_KEY-check wurde
     // nie getriggert, encryption silent broken. Jetzt: beide string-
     // typed fields werden gechecked.
-    delete process.env["ENCRYPTION_KEY"];
+    delete process.env["KUMIKO_SECRETS_MASTER_KEY_V1"];
     const features = [
       defineFeature("a", (r) => {
         r.entity(
@@ -166,7 +190,7 @@ describe("boot-validator", () => {
         );
       }),
     ];
-    expect(() => validateBoot(features)).toThrow(/ENCRYPTION_KEY.*required/i);
+    expect(() => validateBoot(features)).toThrow(/master key/i);
   });
 
   test("rejects encrypted text field that is also filterable", () => {

package/src/engine/boot-validator/index.ts

@@ -1,3 +1,4 @@
+import { validateEntityFieldEncryptionAvailable } from "../../db/entity-field-encryption";
 import { QnTypes, qualifyEntityName } from "../qualified-name";
 import type { ClaimKeyDefinition, FeatureDefinition } from "../types";
 import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext";
@@ -179,8 +180,12 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
   validateGdprStoragePersistence(features);
   validateGdprHookCompleteness(features);
 
-  if (hasEncryptedFields && !process.env["ENCRYPTION_KEY"]) {
-    throw new Error("ENCRYPTION_KEY environment variable is required (encrypted fields in use)");
+  if (hasEncryptedFields) {
+    // Availability check, not env-presence: eagerly building the keyring
+    // catches malformed keys (wrong length, bad base64) at boot instead of
+    // on the first encrypted read in prod. An injected cipher (test seam,
+    // custom KMS provider) satisfies the requirement without env keys.
+    validateEntityFieldEncryptionAvailable();
   }
 
   if (hasFileFields && !process.env["FILE_STORAGE_PROVIDER"]) {

package/src/engine/types/handlers.ts

@@ -235,8 +235,9 @@ type SharedContextFields = {
   // Encryption round-trip partner for the config feature. Separate from
   // configResolver so the read-only resolver contract stays clean — the
   // set handler needs to encrypt on write, the resolver needs to decrypt
-  // on read, and both reach for the same provider. Wired via extraContext.
-  readonly configEncryption?: import("../../db").EncryptionProvider;
+  // on read, and both reach for the same cipher. Wired via extraContext;
+  // run{Prod,Dev}App build it from the secrets master key automatically.
+  readonly configEncryption?: import("../../secrets").EnvelopeCipher;
   // Rate-limit resolver. Wired by the framework when the `rate-limiting`
   // feature is loaded — pipeline reads handler.rateLimit and calls
   // .enforce() on this resolver before access-check. Absent when the

package/src/secrets/__tests__/envelope-cipher.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { createEncryptionProvider } from "../../db/encryption";
+import { createEnvMasterKeyProvider } from "../env-master-key-provider";
+import { createEnvelopeCipher } from "../envelope-cipher";
+import { isStoredEnvelope } from "../stored-envelope";
+
+function makeProvider(currentVersion = 1) {
+  return createEnvMasterKeyProvider({
+    env: {
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: String(currentVersion),
+      [`KUMIKO_SECRETS_MASTER_KEY_V${currentVersion}`]: randomBytes(32).toString("base64"),
+    },
+  });
+}
+
+describe("envelope-cipher — encrypt/decrypt", () => {
+  test("round-trips plaintext through the JSON envelope format", async () => {
+    const cipher = createEnvelopeCipher(makeProvider());
+    const stored = await cipher.encrypt("s3cret-smtp-pass");
+
+    expect(stored.startsWith("{")).toBe(true);
+    const parsed: unknown = JSON.parse(stored);
+    expect(isStoredEnvelope(parsed)).toBe(true);
+
+    expect(await cipher.decrypt(stored)).toBe("s3cret-smtp-pass");
+  });
+
+  test("stored value carries the kekVersion for later rotation", async () => {
+    const cipher = createEnvelopeCipher(makeProvider(7));
+    const stored = await cipher.encrypt("x");
+    expect((JSON.parse(stored) as { kekVersion: number }).kekVersion).toBe(7);
+  });
+
+  test("tampered ciphertext fails GCM authentication", async () => {
+    const cipher = createEnvelopeCipher(makeProvider());
+    const stored = JSON.parse(await cipher.encrypt("payload")) as Record<string, unknown>;
+    const cipherBytes = Buffer.from(stored["ciphertext"] as string, "base64");
+    cipherBytes[0] = (cipherBytes[0] ?? 0) ^ 0xff;
+    const tampered = JSON.stringify({ ...stored, ciphertext: cipherBytes.toString("base64") });
+    await expect(cipher.decrypt(tampered)).rejects.toThrow();
+  });
+});
+
+describe("envelope-cipher — legacy fallback", () => {
+  test("decrypts legacy single-key values when the legacy provider is configured", async () => {
+    const legacy = createEncryptionProvider(randomBytes(32).toString("base64"));
+    const legacyStored = legacy.encrypt("pre-envelope value");
+    // legacy wire format is base64 — never starts with "{"
+    expect(legacyStored.startsWith("{")).toBe(false);
+
+    const cipher = createEnvelopeCipher(makeProvider(), { legacy });
+    expect(await cipher.decrypt(legacyStored)).toBe("pre-envelope value");
+  });
+
+  test("throws with a remediation message when a legacy value has no legacy key", async () => {
+    const legacy = createEncryptionProvider(randomBytes(32).toString("base64"));
+    const legacyStored = legacy.encrypt("orphaned");
+
+    const cipher = createEnvelopeCipher(makeProvider());
+    await expect(cipher.decrypt(legacyStored)).rejects.toThrow(/legacy/);
+  });
+
+  test("never encrypts into the legacy format even when a legacy key is present", async () => {
+    const legacy = createEncryptionProvider(randomBytes(32).toString("base64"));
+    const cipher = createEnvelopeCipher(makeProvider(), { legacy });
+    const stored = await cipher.encrypt("always-envelope");
+    expect(stored.startsWith("{")).toBe(true);
+  });
+});
+
+describe("envelope-cipher — malformed input", () => {
+  test("rejects invalid JSON that looks like an envelope", async () => {
+    const cipher = createEnvelopeCipher(makeProvider());
+    await expect(cipher.decrypt("{garbage")).rejects.toThrow(/not valid JSON/);
+  });
+
+  test("rejects JSON that is not a StoredEnvelope", async () => {
+    const cipher = createEnvelopeCipher(makeProvider());
+    await expect(cipher.decrypt('{"foo":"bar"}')).rejects.toThrow(/not a StoredEnvelope/);
+  });
+
+  test("empty string routes to the legacy branch and throws without a legacy key", async () => {
+    const cipher = createEnvelopeCipher(makeProvider());
+    await expect(cipher.decrypt("")).rejects.toThrow(/legacy/);
+  });
+});

package/src/secrets/dek-cache.ts

@@ -9,7 +9,7 @@
 //   - maxEntries (default 1000): LRU eviction kicks in on insert when full.
 
 import { createHash } from "node:crypto";
-import type { MasterKeyProvider } from "./types";
+import type { KeyScope, MasterKeyProvider } from "./types";
 
 const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const DEFAULT_MAX_ENTRIES = 1000;
@@ -25,8 +25,16 @@ export type DekCacheOptions = {
 
 export type DekCache = {
   // Unwrap via the provider, caching the result. Second call within TTL
-  // returns the cached DEK without hitting the provider.
-  unwrapDek(encryptedDek: Buffer, kekVersion: number, provider: MasterKeyProvider): Promise<Buffer>;
+  // returns the cached DEK without hitting the provider. The cache key is
+  // (encryptedDek, kekVersion) — scope is only forwarded to the provider;
+  // encryptedDek bytes are unique per value, so scoped providers can't
+  // collide on the key either.
+  unwrapDek(
+    encryptedDek: Buffer,
+    kekVersion: number,
+    provider: MasterKeyProvider,
+    scope?: KeyScope,
+  ): Promise<Buffer>;
 
   // Drop every entry. Call after KEK rotation so old cached DEKs (still
   // valid, but referencing the old kekVersion) don't serve reads that
@@ -37,6 +45,19 @@ export type DekCache = {
   size(): number;
 };
 
+// Wrap a provider so its unwrapDek goes through the cache. Callers keep the
+// full MasterKeyProvider contract without knowing about caching —
+// decryptValue handles crypto, the cache handles cost.
+export function withDekCache(provider: MasterKeyProvider, cache: DekCache): MasterKeyProvider {
+  return {
+    wrapDek: (dek, scope) => provider.wrapDek(dek, scope),
+    unwrapDek: (encryptedDek, version, scope) =>
+      cache.unwrapDek(encryptedDek, version, provider, scope),
+    currentVersion: () => provider.currentVersion(),
+    isAvailable: () => provider.isAvailable(),
+  };
+}
+
 export function createDekCache(opts: DekCacheOptions = {}): DekCache {
   const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
   const maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
@@ -74,7 +95,7 @@ export function createDekCache(opts: DekCacheOptions = {}): DekCache {
   }
 
   return {
-    async unwrapDek(encryptedDek, kekVersion, provider) {
+    async unwrapDek(encryptedDek, kekVersion, provider, scope) {
       const key = cacheKey(encryptedDek, kekVersion);
       const hit = entries.get(key);
       if (hit && hit.expiresAt > now()) {
@@ -92,7 +113,7 @@ export function createDekCache(opts: DekCacheOptions = {}): DekCache {
         entries.delete(key);
       }
 
-      const dek = await provider.unwrapDek(encryptedDek, kekVersion);
+      const dek = await provider.unwrapDek(encryptedDek, kekVersion, scope);
       evictOldestIfFull();
       // Store a copy — caller can zero its own buffer after use.
       entries.set(key, { dek: Buffer.from(dek), expiresAt: now() + ttlMs });

package/src/secrets/envelope-cipher.ts

@@ -0,0 +1,81 @@
+// String-in/string-out envelope encryption for TEXT-column stores (config
+// values, entity fields). The stored string is JSON of StoredEnvelope; the
+// kekVersion inside makes every value rotatable via the MasterKeyProvider
+// keyring — unlike the legacy createEncryptionProvider format (raw
+// base64(iv+tag+ct), no key id), which this cipher still DECRYPTS through
+// the optional legacy provider so pre-envelope rows stay readable until a
+// re-encrypt job has migrated them.
+
+import type { EncryptionProvider } from "../db/encryption";
+import { InternalError } from "../errors/classes";
+import type { DekCache } from "./dek-cache";
+import { createDekCache, withDekCache } from "./dek-cache";
+import { decryptValue, encryptValue } from "./envelope";
+import { decodeStoredEnvelope, encodeStoredEnvelope, isStoredEnvelope } from "./stored-envelope";
+import type { KeyScope, MasterKeyProvider } from "./types";
+
+export type EnvelopeCipherOptions = {
+  // Decrypt-only fallback for legacy createEncryptionProvider ciphertexts
+  // (CONFIG_ENCRYPTION_KEY / ENCRYPTION_KEY era). Never used for encrypt.
+  readonly legacy?: EncryptionProvider;
+  // Shared DEK cache — pass the app-wide instance so config/entity reads
+  // amortise KEK unwraps together with ctx.secrets.
+  readonly dekCache?: DekCache;
+};
+
+export type EnvelopeCipher = {
+  encrypt(plaintext: string, scope?: KeyScope): Promise<string>;
+  decrypt(stored: string, scope?: KeyScope): Promise<string>;
+};
+
+// Format detection: envelope values are JSON objects, so they start with
+// "{" — a character the base64 alphabet of the legacy format can never
+// produce. No version byte or prefix marker needed.
+function isEnvelopeFormat(stored: string): boolean {
+  return stored.startsWith("{");
+}
+
+export function createEnvelopeCipher(
+  provider: MasterKeyProvider,
+  opts: EnvelopeCipherOptions = {},
+): EnvelopeCipher {
+  const cached = withDekCache(provider, opts.dekCache ?? createDekCache());
+
+  return {
+    async encrypt(plaintext, scope) {
+      const envelope = await encryptValue(plaintext, provider, scope);
+      return JSON.stringify(encodeStoredEnvelope(envelope));
+    },
+
+    async decrypt(stored, scope) {
+      if (isEnvelopeFormat(stored)) {
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(stored);
+        } catch {
+          throw new InternalError({
+            message: "[envelope-cipher] stored value looks like an envelope but is not valid JSON",
+            i18nKey: "secrets.errors.envelope_malformed",
+          });
+        }
+        if (!isStoredEnvelope(parsed)) {
+          throw new InternalError({
+            message: "[envelope-cipher] stored JSON is not a StoredEnvelope",
+            i18nKey: "secrets.errors.envelope_malformed",
+          });
+        }
+        return decryptValue(decodeStoredEnvelope(parsed), cached, scope);
+      }
+
+      if (!opts.legacy) {
+        throw new InternalError({
+          message:
+            "[envelope-cipher] value is in the legacy single-key format but no legacy key is configured — " +
+            "provision the legacy key (CONFIG_ENCRYPTION_KEY / ENCRYPTION_KEY) or run the re-encrypt job first",
+          i18nKey: "secrets.errors.legacy_key_missing",
+        });
+      }
+      return opts.legacy.decrypt(stored);
+    },
+  };
+}

package/src/secrets/envelope.ts

@@ -3,7 +3,7 @@
 // carries everything needed to decrypt later.
 
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
-import type { Envelope, MasterKeyProvider } from "./types";
+import type { Envelope, KeyScope, MasterKeyProvider } from "./types";
 
 const ALGORITHM = "aes-256-gcm";
 const DEK_LENGTH = 32; // AES-256
@@ -14,6 +14,7 @@ const IV_LENGTH = 12; // GCM standard nonce length
 export async function encryptValue(
   plaintext: string,
   provider: MasterKeyProvider,
+  scope?: KeyScope,
 ): Promise<Envelope> {
   // Fresh DEK per value. Reusing DEKs across rows would break forward
   // secrecy (one compromised ciphertext-IV pair leaks information about
@@ -26,7 +27,7 @@ export async function encryptValue(
     const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
     const authTag = cipher.getAuthTag();
 
-    const { encryptedDek, kekVersion } = await provider.wrapDek(dek);
+    const { encryptedDek, kekVersion } = await provider.wrapDek(dek, scope);
     return { ciphertext, iv, authTag, encryptedDek, kekVersion };
   } finally {
     // Zero the DEK on best effort regardless of success — if provider.wrapDek
@@ -42,8 +43,9 @@ export async function encryptValue(
 export async function decryptValue(
   envelope: Envelope,
   provider: MasterKeyProvider,
+  scope?: KeyScope,
 ): Promise<string> {
-  const dek = await provider.unwrapDek(envelope.encryptedDek, envelope.kekVersion);
+  const dek = await provider.unwrapDek(envelope.encryptedDek, envelope.kekVersion, scope);
   try {
     const decipher = createDecipheriv(ALGORITHM, dek, envelope.iv);
     decipher.setAuthTag(envelope.authTag);

package/src/secrets/index.ts

@@ -1,17 +1,29 @@
-export { createDekCache, type DekCache, type DekCacheOptions } from "./dek-cache";
+export { createDekCache, type DekCache, type DekCacheOptions, withDekCache } from "./dek-cache";
 export {
   createEnvMasterKeyProvider,
   type EnvMasterKeyProviderOptions,
   type Keyring,
 } from "./env-master-key-provider";
 export { decryptValue, encryptValue } from "./envelope";
+export {
+  createEnvelopeCipher,
+  type EnvelopeCipher,
+  type EnvelopeCipherOptions,
+} from "./envelope-cipher";
 export { assertNoSecretLeak } from "./leak-guard";
 export { rewrapDek } from "./rotation";
+export {
+  decodeStoredEnvelope,
+  encodeStoredEnvelope,
+  isStoredEnvelope,
+  type StoredEnvelope,
+} from "./stored-envelope";
 export {
   type ContainsSecret,
   createSecret,
   type Envelope,
   isSecret,
+  type KeyScope,
   type MasterKeyProvider,
   type Secret,
   type SecretAuditContext,

package/src/secrets/stored-envelope.ts

@@ -0,0 +1,46 @@
+// Canonical at-rest form of an Envelope: every Buffer as base64, ready for
+// jsonb columns (secrets feature) or JSON-stringified TEXT columns
+// (EnvelopeCipher for config values / entity fields). One wire shape for
+// every envelope-encrypted store in the framework.
+
+import type { Envelope } from "./types";
+
+export type StoredEnvelope = {
+  readonly ciphertext: string; // base64
+  readonly iv: string; // base64
+  readonly authTag: string; // base64
+  readonly encryptedDek: string; // base64
+  readonly kekVersion: number;
+};
+
+export function encodeStoredEnvelope(envelope: Envelope): StoredEnvelope {
+  return {
+    ciphertext: envelope.ciphertext.toString("base64"),
+    iv: envelope.iv.toString("base64"),
+    authTag: envelope.authTag.toString("base64"),
+    encryptedDek: envelope.encryptedDek.toString("base64"),
+    kekVersion: envelope.kekVersion,
+  };
+}
+
+export function decodeStoredEnvelope(stored: StoredEnvelope): Envelope {
+  return {
+    ciphertext: Buffer.from(stored.ciphertext, "base64"),
+    iv: Buffer.from(stored.iv, "base64"),
+    authTag: Buffer.from(stored.authTag, "base64"),
+    encryptedDek: Buffer.from(stored.encryptedDek, "base64"),
+    kekVersion: stored.kekVersion,
+  };
+}
+
+export function isStoredEnvelope(value: unknown): value is StoredEnvelope {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>; // @cast-boundary parse-boundary after typeof check
+  return (
+    typeof v["ciphertext"] === "string" &&
+    typeof v["iv"] === "string" &&
+    typeof v["authTag"] === "string" &&
+    typeof v["encryptedDek"] === "string" &&
+    typeof v["kekVersion"] === "number"
+  );
+}

package/src/secrets/types.ts

@@ -144,6 +144,14 @@ export type Envelope = {
   readonly kekVersion: number;
 };
 
+// BYOK hook: callers pass the tenant a value belongs to; a per-tenant-KMS
+// provider keys its wrap/unwrap on it. EnvMasterKeyProvider (app-wide
+// keyring) ignores it — the param exists so the contract doesn't have to
+// break when a tenant-scoped provider ships.
+export type KeyScope = {
+  readonly tenantId?: TenantId;
+};
+
 // The contract a KEK backend must fulfil. The framework sees only this
 // interface; concrete implementations live in separate packages
 // (@cosmicdrift/kumiko-secrets-vault, @cosmicdrift/kumiko-secrets-aws-kms, ...). The default is
@@ -152,12 +160,12 @@ export interface MasterKeyProvider {
   // Wrap a fresh DEK with the current KEK. Returns the wrapped bytes + the
   // KEK version used — the version ends up in the Envelope so decryption
   // later knows which KEK to ask for.
-  wrapDek(dek: Buffer): Promise<{ encryptedDek: Buffer; kekVersion: number }>;
+  wrapDek(dek: Buffer, scope?: KeyScope): Promise<{ encryptedDek: Buffer; kekVersion: number }>;
 
   // Unwrap a previously-wrapped DEK. During rotation the provider must
   // accept older kekVersion values (2-version window minimum), otherwise
   // old rows become unreadable.
-  unwrapDek(encryptedDek: Buffer, kekVersion: number): Promise<Buffer>;
+  unwrapDek(encryptedDek: Buffer, kekVersion: number, scope?: KeyScope): Promise<Buffer>;
 
   // Which KEK version new wraps use. Rotation flips this to a new value
   // and older-version reads continue to work until rows are re-wrapped.

package/src/testing/index.ts

@@ -25,6 +25,8 @@ export { createLateBoundHolder, type LateBoundHolder } from "./late-bound";
 export { buildMultipartBody, patchFileInstanceofForBunTest } from "./multipart-helper";
 export {
   createMutableMasterKeyProvider,
+  createTestEnvelopeCipher,
+  createTestMasterKeyProvider,
   type MutableMasterKeyProvider,
 } from "./mutable-master-key-provider";
 export {

package/src/testing/mutable-master-key-provider.ts

@@ -6,7 +6,14 @@
 // tests that want to exercise pre- and post-rotation behaviour in a
 // single suite.
 
-import type { MasterKeyProvider } from "../secrets";
+import { randomBytes } from "node:crypto";
+import {
+  createEnvelopeCipher,
+  createEnvMasterKeyProvider,
+  type EnvelopeCipher,
+  type EnvelopeCipherOptions,
+  type MasterKeyProvider,
+} from "../secrets";
 
 export type MutableMasterKeyProvider = MasterKeyProvider & {
   // Replace the backing provider. All future wrapDek/unwrapDek/currentVersion
@@ -20,8 +27,8 @@ export function createMutableMasterKeyProvider(
 ): MutableMasterKeyProvider {
   let current = initial;
   return {
-    wrapDek: (dek) => current.wrapDek(dek),
-    unwrapDek: (e, v) => current.unwrapDek(e, v),
+    wrapDek: (dek, scope) => current.wrapDek(dek, scope),
+    unwrapDek: (e, v, scope) => current.unwrapDek(e, v, scope),
     currentVersion: () => current.currentVersion(),
     isAvailable: () => current.isAvailable(),
     replace: (next) => {
@@ -29,3 +36,22 @@ export function createMutableMasterKeyProvider(
     },
   };
 }
+
+// Single-version env provider for tests — the shape every integration test
+// needs to exercise encrypted config keys / entity fields without caring
+// about keyring mechanics. Pass a fixed key to share it across stacks.
+export function createTestMasterKeyProvider(keyBase64?: string): MasterKeyProvider {
+  return createEnvMasterKeyProvider({
+    env: {
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+      KUMIKO_SECRETS_MASTER_KEY_V1: keyBase64 ?? randomBytes(32).toString("base64"),
+    },
+  });
+}
+
+export function createTestEnvelopeCipher(
+  keyBase64?: string,
+  opts?: EnvelopeCipherOptions,
+): EnvelopeCipher {
+  return createEnvelopeCipher(createTestMasterKeyProvider(keyBase64), opts ?? {});
+}