@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/search/__tests__/reindex-entity.integration.test.ts

@@ -0,0 +1,144 @@
+// reindexEntity — Integration Test
+// Proves: rows written before a search consumer ever indexed them (the
+// #1206 scenario — searchable:true added retroactively) become findable
+// after a backfill run, soft-deleted rows stay excluded, and dryRun writes
+// nothing.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  asRawClient,
+  buildEntityTable,
+  createEventStoreExecutor,
+  createTenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { reindexEntity } from "@cosmicdrift/kumiko-framework/search";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+
+const widgetEntity = createEntity({
+  table: "read_reindex_widgets",
+  softDelete: true,
+  fields: {
+    name: createTextField({ required: true, searchable: true }),
+  },
+});
+
+const widgetTable = buildEntityTable("widget", widgetEntity);
+
+const widgetFeature = defineFeature("reindex-test", (r) => {
+  r.entity("widget", widgetEntity);
+});
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [widgetFeature] });
+  await unsafeCreateEntityTable(stack.db, widgetEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+function seedExecutor() {
+  return createEventStoreExecutor(widgetTable, widgetEntity, { entityName: "widget" });
+}
+
+function tenantDb() {
+  return createTenantDb(stack.db, admin.tenantId, "system");
+}
+
+describe("reindexEntity", () => {
+  test("indexes rows that were never drained through the search consumer", async () => {
+    const executor = seedExecutor();
+    const created = await executor.create({ name: "Backfillable Widget" }, admin, tenantDb());
+    if (!created.isSuccess) throw new Error("seed failed");
+
+    // No stack.eventDispatcher.runOnce() call — simulates rows that existed
+    // before search indexing ever ran for this entity.
+    const preResults = await stack.search.search(admin.tenantId, "backfillable", {
+      filterType: "widget",
+    });
+    expect(preResults).toHaveLength(0);
+
+    const result = await reindexEntity(
+      stack.db,
+      stack.registry,
+      stack.search,
+      "widget",
+      admin.tenantId,
+    );
+    expect(result.indexedRows).toBe(1);
+    expect(result.failures).toHaveLength(0);
+
+    const postResults = await stack.search.search(admin.tenantId, "backfillable", {
+      filterType: "widget",
+    });
+    expect(postResults.some((r) => r.entityId === created.data.id)).toBe(true);
+  });
+
+  test("skips soft-deleted rows", async () => {
+    const executor = seedExecutor();
+    const created = await executor.create({ name: "Erased Widget" }, admin, tenantDb());
+    if (!created.isSuccess) throw new Error("seed failed");
+    const deleted = await executor.delete({ id: created.data.id }, admin, tenantDb());
+    if (!deleted.isSuccess) throw new Error("delete failed");
+
+    await reindexEntity(stack.db, stack.registry, stack.search, "widget", admin.tenantId);
+
+    const postResults = await stack.search.search(admin.tenantId, "erased", {
+      filterType: "widget",
+    });
+    expect(postResults.some((r) => r.entityId === created.data.id)).toBe(false);
+  });
+
+  test("dryRun scans without writing to the index", async () => {
+    const executor = seedExecutor();
+    await executor.create({ name: "DryRun Widget" }, admin, tenantDb());
+
+    const result = await reindexEntity(
+      stack.db,
+      stack.registry,
+      stack.search,
+      "widget",
+      admin.tenantId,
+      { dryRun: true },
+    );
+    expect(result.indexedRows).toBe(0);
+    expect(result.wouldIndexRows).toBeGreaterThan(0);
+
+    const postResults = await stack.search.search(admin.tenantId, "dryrun", {
+      filterType: "widget",
+    });
+    expect(postResults).toHaveLength(0);
+  });
+
+  // kumiko-framework#1549: a searchable field with no matching read-table
+  // column (dropped/never-migrated) used to push one identical failures[]
+  // entry per scanned row instead of failing fast — fails loud on the first
+  // row's column set instead, which is invariant across the whole scan.
+  test("throws immediately when a searchable field has no matching column, without scanning every row", async () => {
+    const executor = seedExecutor();
+    await executor.create({ name: "Row A" }, admin, tenantDb());
+    await executor.create({ name: "Row B" }, admin, tenantDb());
+
+    await asRawClient(stack.db).unsafe(`ALTER TABLE "read_reindex_widgets" DROP COLUMN "name"`);
+    try {
+      await expect(
+        reindexEntity(stack.db, stack.registry, stack.search, "widget", admin.tenantId),
+      ).rejects.toThrow(/searchable field "name" is not mappable/);
+    } finally {
+      await asRawClient(stack.db).unsafe(
+        `ALTER TABLE "read_reindex_widgets" ADD COLUMN "name" text`,
+      );
+    }
+  });
+});

package/src/search/index.ts

@@ -3,6 +3,12 @@
 // von SearchAdapter-Types. Apps die Meilisearch nicht nutzen, ziehen den
 // Client-Code nicht mit rein.
 export { createInMemorySearchAdapter } from "./in-memory-adapter";
+export type {
+  ReindexEntityFailure,
+  ReindexEntityOptions,
+  ReindexEntityResult,
+} from "./reindex-entity";
+export { reindexEntity } from "./reindex-entity";
 export type {
   SearchAdapter,
   SearchAdapterConfig,

package/src/search/meilisearch-adapter.ts

@@ -8,13 +8,14 @@ export type MeilisearchAdapterOptions = {
   indexPrefix?: string;
 };
 
-function tenantIndex(prefix: string, tenantId: TenantId): string {
+// Exported for unit tests (index-name / primary-key shape) without a live Meili.
+export function meilisearchTenantIndex(prefix: string, tenantId: TenantId): string {
   return `${prefix}t${tenantId}`;
 }
 
 // Meilisearch primary-key-ids: alphanumerics, `-`, `_`. UUIDs contain `-` —
 // legal. Replace anything else just in case callers pass unexpected shapes.
-function docId(entityType: string, entityId: EntityId): string {
+export function meilisearchDocId(entityType: string, entityId: EntityId): string {
   return `${entityType}_${String(entityId).replace(/[^0-9A-Za-z_-]/g, "_")}`;
 }
 
@@ -24,7 +25,7 @@ export function createMeilisearchAdapter(options: MeilisearchAdapterOptions): Se
 
   return {
     async configure(tenantId, config) {
-      const index = client.index(tenantIndex(prefix, tenantId));
+      const index = client.index(meilisearchTenantIndex(prefix, tenantId));
       const fields = config.rankingFields ?? config.searchableFields;
       await index.updateSearchableAttributes([...fields]).waitTask();
       await index.updateFilterableAttributes(["_type", "_weight"]).waitTask();
@@ -32,12 +33,12 @@ export function createMeilisearchAdapter(options: MeilisearchAdapterOptions): Se
     },
 
     async index(tenantId, doc) {
-      const index = client.index(tenantIndex(prefix, tenantId));
+      const index = client.index(meilisearchTenantIndex(prefix, tenantId));
       await index
         .addDocuments(
           [
             {
-              _id: docId(doc.entityType, doc.entityId),
+              _id: meilisearchDocId(doc.entityType, doc.entityId),
               _type: doc.entityType,
               _weight: doc.weight,
               _entityId: doc.entityId,
@@ -52,9 +53,9 @@ export function createMeilisearchAdapter(options: MeilisearchAdapterOptions): Se
     async indexBatch(tenantId, docs) {
       // skip: empty batch — avoid an unnecessary Meilisearch round-trip
       if (docs.length === 0) return;
-      const index = client.index(tenantIndex(prefix, tenantId));
+      const index = client.index(meilisearchTenantIndex(prefix, tenantId));
       const payload = docs.map((doc) => ({
-        _id: docId(doc.entityType, doc.entityId),
+        _id: meilisearchDocId(doc.entityType, doc.entityId),
         _type: doc.entityType,
         _weight: doc.weight,
         _entityId: doc.entityId,
@@ -69,13 +70,13 @@ export function createMeilisearchAdapter(options: MeilisearchAdapterOptions): Se
     async removeBatch(tenantId, items) {
       // skip: empty batch — avoid an unnecessary Meilisearch round-trip
       if (items.length === 0) return;
-      const index = client.index(tenantIndex(prefix, tenantId));
-      const ids = items.map((i) => docId(i.entityType, i.entityId));
+      const index = client.index(meilisearchTenantIndex(prefix, tenantId));
+      const ids = items.map((i) => meilisearchDocId(i.entityType, i.entityId));
       await index.deleteDocuments(ids).waitTask();
     },
 
     async search(tenantId, query, options) {
-      const index = client.index(tenantIndex(prefix, tenantId));
+      const index = client.index(meilisearchTenantIndex(prefix, tenantId));
 
       const filter: string[] = [];
       if (options?.filterType) {
@@ -99,8 +100,8 @@ export function createMeilisearchAdapter(options: MeilisearchAdapterOptions): Se
     },
 
     async remove(tenantId, entityType, entityId) {
-      const index = client.index(tenantIndex(prefix, tenantId));
-      await index.deleteDocument(docId(entityType, entityId)).waitTask();
+      const index = client.index(meilisearchTenantIndex(prefix, tenantId));
+      await index.deleteDocument(meilisearchDocId(entityType, entityId)).waitTask();
     },
   };
 }

package/src/search/reindex-entity.ts

@@ -0,0 +1,177 @@
+// One-time backfill for entities that only got `searchable: true` after rows
+// already existed (#1206). buildSearchDocument() only runs on the write path
+// (createSearchEventConsumer, system-hooks.ts) — pre-existing rows never
+// pass through it, so they stay unfindable until their next write. This
+// re-derives a SearchDocument straight from the read-table row for every
+// existing row and indexes it, same as a live write would.
+
+import type { DbRunner } from "../db/connection";
+import { resolveTableName } from "../db/entity-table-meta";
+import { executeRawQuery } from "../db/queries/raw-sql";
+import type { Registry, TenantId } from "../engine/types";
+import { buildSearchDocument } from "../pipeline/system-hooks";
+import { toSnakeCase } from "../utils/case";
+import type { SearchAdapter, SearchDocument } from "./types";
+
+export type ReindexEntityFailure = {
+  readonly entityId: string;
+  readonly reason: string;
+};
+
+export type ReindexEntityResult = {
+  readonly scannedRows: number;
+  readonly indexedRows: number;
+  // Only nonzero in a dry run — docs that would have been indexed. In a
+  // real run indexedRows already counts these; wouldIndexRows stays 0.
+  readonly wouldIndexRows: number;
+  readonly failures: readonly ReindexEntityFailure[];
+};
+
+export type ReindexEntityOptions = {
+  readonly batchSize?: number;
+  // Scan + build docs, write nothing.
+  readonly dryRun?: boolean;
+};
+
+function quoteIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+// Read-table state, forward-mapped from entity.fields (fieldName →
+// toSnakeCase(fieldName)). SELECT * + forward-map instead of building an
+// explicit column list: some field types (files/images) emit no column at
+// all, others (locatedTimestamp, money) emit companion columns under a
+// different name — an explicit alias list breaks on those. Missing columns
+// are just skipped, matching what a `.created` event payload would carry.
+function rowToState(
+  row: Record<string, unknown>,
+  fieldNames: readonly string[],
+): Record<string, unknown> {
+  const state: Record<string, unknown> = {};
+  for (const fieldName of fieldNames) {
+    const column = toSnakeCase(fieldName);
+    if (Object.hasOwn(row, column)) state[fieldName] = row[column];
+  }
+  return state;
+}
+
+export async function reindexEntity(
+  db: DbRunner,
+  registry: Registry,
+  searchAdapter: SearchAdapter,
+  entityName: string,
+  tenantId: TenantId,
+  options: ReindexEntityOptions = {},
+): Promise<ReindexEntityResult> {
+  const entity = registry.getEntity(entityName);
+  if (!entity) {
+    throw new Error(`reindexEntity: unknown entity "${entityName}"`);
+  }
+  const searchableFields = registry.getSearchableFields(entityName);
+  const extensions = registry.getSearchPayloadExtensions(entityName);
+  if (searchableFields.length === 0 && extensions.length === 0) {
+    throw new Error(
+      `reindexEntity: entity "${entityName}" has no searchable fields and no search-payload ` +
+        `extensions — nothing to index.`,
+    );
+  }
+
+  const batchSize = options.batchSize ?? 500;
+  const tableName = resolveTableName(entityName, entity, undefined);
+  const fieldNames = Object.keys(entity.fields);
+  // Soft-deleted rows already left the live index (the .deleted consumer
+  // calls searchAdapter.remove()) — resurrecting them here would make
+  // erased entities findable again.
+  const deletedFilter =
+    entity.softDelete === true ? `AND ${quoteIdent("is_deleted")} IS NOT TRUE` : "";
+
+  const result = {
+    scannedRows: 0,
+    indexedRows: 0,
+    wouldIndexRows: 0,
+    failures: [] as ReindexEntityFailure[],
+  };
+
+  let offset = 0;
+  // Whether a searchable field lacks a matching read-table column depends
+  // only on the table's column set (rowToState/Object.hasOwn), not on any
+  // particular row's data — every row from the same SELECT * has the same
+  // columns. Check once against the first row instead of every row, so a
+  // dropped/never-migrated column fails fast with one clear error instead
+  // of one identical failures[] entry per scanned row (1M rows → 1M
+  // entries, and the real schema problem is buried in "x failed").
+  let uncheckedSchema = true;
+
+  for (;;) {
+    // ponytail: LIMIT/OFFSET, not a keyset cursor — id can be uuid or
+    // serial depending on the entity, and a uniform cursor comparison
+    // across both types needs a text cast that breaks integer ordering.
+    // This is a one-time backfill over existing rows, not a live hot path;
+    // switch to keyset if it ever needs to run against a churning table.
+    const rows = await executeRawQuery<Record<string, unknown>>(
+      db,
+      `SELECT * FROM ${quoteIdent(tableName)}
+        WHERE ${quoteIdent("tenant_id")} = $1 ${deletedFilter}
+        ORDER BY ${quoteIdent("id")} ASC
+        LIMIT $2 OFFSET $3`,
+      [tenantId, batchSize, offset],
+    );
+    if (rows.length === 0) break;
+
+    if (uncheckedSchema) {
+      uncheckedSchema = false;
+      const sampleState = rowToState(rows[0] as Record<string, unknown>, fieldNames);
+      const unmappedField = searchableFields.find((fieldName) => !(fieldName in sampleState));
+      if (unmappedField !== undefined) {
+        throw new Error(
+          `reindexEntity: searchable field "${unmappedField}" is not mappable from read-table ` +
+            `column ${quoteIdent(tableName)} — likely a dropped/never-migrated column.`,
+        );
+      }
+    }
+
+    const docs: Array<{ entityId: string; doc: SearchDocument }> = [];
+    for (const row of rows) {
+      result.scannedRows++;
+      const entityId = String(row["id"]);
+      try {
+        const state = rowToState(row, fieldNames);
+        const doc = await buildSearchDocument(entityName, entityId, state, registry);
+        if (doc) docs.push({ entityId, doc });
+      } catch (e) {
+        result.failures.push({ entityId, reason: e instanceof Error ? e.message : String(e) });
+      }
+    }
+
+    if (!options.dryRun && docs.length > 0) {
+      if (searchAdapter.indexBatch) {
+        try {
+          await searchAdapter.indexBatch(
+            tenantId,
+            docs.map((d) => d.doc),
+          );
+          result.indexedRows += docs.length;
+        } catch (e) {
+          const reason = e instanceof Error ? e.message : String(e);
+          for (const { entityId } of docs) result.failures.push({ entityId, reason });
+        }
+      } else {
+        for (const { entityId, doc } of docs) {
+          try {
+            await searchAdapter.index(tenantId, doc);
+            result.indexedRows++;
+          } catch (e) {
+            result.failures.push({ entityId, reason: e instanceof Error ? e.message : String(e) });
+          }
+        }
+      }
+    } else if (options.dryRun) {
+      result.wouldIndexRows += docs.length;
+    }
+
+    offset += rows.length;
+    if (rows.length < batchSize) break;
+  }
+
+  return result;
+}

package/src/search/types.ts

@@ -1,39 +1 @@
-import type { EntityId, TenantId } from "../engine/types/identifiers";
-
-export type SearchAdapterConfig = {
-  searchableFields: readonly string[];
-  rankingFields?: readonly string[];
-};
-
-export type SearchDocument = {
-  entityType: string;
-  entityId: EntityId;
-  weight: number;
-  fields: Record<string, unknown>;
-};
-
-export type SearchResult = {
-  entityType: string;
-  entityId: EntityId;
-};
-
-export type SearchOptions = {
-  limit?: number;
-  filterType?: string;
-};
-
-export type SearchAdapter = {
-  configure(tenantId: TenantId, config: SearchAdapterConfig): Promise<void>;
-  index(tenantId: TenantId, doc: SearchDocument): Promise<void>;
-  search(tenantId: TenantId, query: string, options?: SearchOptions): Promise<SearchResult[]>;
-  remove(tenantId: TenantId, entityType: string, entityId: EntityId): Promise<void>;
-  // Bulk variants. Default implementations loop over the single-doc methods —
-  // adapters should override when the backend supports a real batch call
-  // (Meilisearch, Elasticsearch, Typesense all do). Cuts a batch-write from
-  // N sequential HTTP + waitTask round-trips to one.
-  indexBatch?(tenantId: TenantId, docs: readonly SearchDocument[]): Promise<void>;
-  removeBatch?(
-    tenantId: TenantId,
-    items: readonly { entityType: string; entityId: EntityId }[],
-  ): Promise<void>;
-};
+export type * from "@cosmicdrift/kumiko-types/search-adapter";

package/src/secrets/__tests__/contains-secret.test.ts

@@ -32,6 +32,18 @@ export type _R6TypeAssertions = [
   // the backstop. This is what keeps generic-over-response handlers compiling.
   Expect<Equal<ContainsSecret<unknown>, false>>,
   Expect<Equal<ContainsSecret<never>, false>>,
+  // 556/3: ContainsSecret<A | B> distributes over the union (naked type
+  // param) to `ContainsSecret<A> | ContainsSecret<B>` = `boolean`, not the
+  // literal `true` — pinned here so a future change to this predicate can't
+  // silently regress it. The actual leak-guard in define-handler.ts compares
+  // via `true extends ContainsSecret<TData>` (556/1) instead of `ContainsSecret<
+  // TData> extends true`, which is fail-closed for `boolean` either way.
+  Expect<Equal<ContainsSecret<{ ok: true } | { s: Secret<string> }>, boolean>>,
+  // 556/2: Map/Set are explicit SafeLeaf members now — pins that the runtime
+  // guard's "walk Map/Set entries separately" intent is mirrored, not an
+  // accidental compile-time blind spot.
+  Expect<Equal<ContainsSecret<Map<string, Secret<string>>>, false>>,
+  Expect<Equal<ContainsSecret<Set<Secret<string>>>, false>>,
 ];
 
 const schema = z.object({ q: z.string() });
@@ -57,6 +69,28 @@ function genericResponseHandler<K extends string>(kind: K) {
 }
 void genericResponseHandler;
 
+// 556/1: ContainsSecret<A | B> distributes over the union (naked type param
+// in the condition) to `ContainsSecret<A> | ContainsSecret<B>` = `boolean`,
+// not the literal `true` — a check written as `ContainsSecret<TData> extends
+// true` silently passes a union with a leak hidden in ONE branch. Both
+// assertions below must hold: the guard rejects the leaking union AND still
+// accepts the clean one, proving the fix (membership form on the phantom
+// param) is fail-closed for unions, not just for a bare Secret<>.
+declare const leakingUnion: { ok: true } | { apiKey: Secret<string> };
+// @ts-expect-error — R6: a Secret<> hidden in one union branch must still leak-guard
+defineQueryHandler({
+  name: "t:query:union-leak",
+  schema,
+  handler: async () => leakingUnion,
+});
+
+declare const cleanUnion: { ok: true } | { id: string };
+defineQueryHandler({
+  name: "t:query:union-clean",
+  schema,
+  handler: async () => cleanUnion,
+});
+
 describe("R6 ContainsSecret", () => {
   test("a clean query handler still builds — the guard param is invisible", () => {
     const def = defineQueryHandler({

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

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+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 — 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 is not valid JSON", async () => {
+    const cipher = createEnvelopeCipher(makeProvider());
+    await expect(cipher.decrypt("")).rejects.toThrow(/not valid JSON/);
+  });
+});

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

@@ -53,7 +53,7 @@ describe("envelope — encryptValue/decryptValue", () => {
       ...envelope,
       ciphertext: Buffer.concat([
         envelope.ciphertext.subarray(0, 1),
-        Buffer.from([envelope.ciphertext[0]! ^ 0xff]),
+        Buffer.from([envelope.ciphertext[1]! ^ 0xff]),
         envelope.ciphertext.subarray(2),
       ]),
     };

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 });