@cosmicdrift/kumiko-framework 0.109.0 → 0.111.0

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/db/tenant-db.ts

@@ -12,10 +12,21 @@ import { SYSTEM_TENANT_ID, type TenantId } from "../engine/types/identifiers";
 import { emitDbQuery, type Meter, registerStandardMetrics, type Tracer } from "../observability";
 import type { DbRunner } from "./connection";
 import type { TableColumns } from "./dialect";
+import type { EntityTableMeta } from "./entity-table-meta";
+import type { NotExecutorOnly } from "./table-builder";
 
 // biome-ignore lint/suspicious/noExplicitAny: Dynamic tables — keys depend on user-defined schema.
 type Table = TableColumns<any>;
 
+// Method-form writes reject the executor-only brand exactly like the free-function
+// helpers (#742): a managed EntityTable is a rebuildable projection, so writing it
+// directly — free-function OR method-form — drifts the row past its event stream and
+// a rebuild wipes it. The permissive base stays (raw pgTables AND unmanaged entity
+// metas are not projections → writable); `& NotExecutorOnly` strips only branded
+// EntityTables (its `[EXECUTOR_ONLY]: true` violates the optional-never). Reads keep
+// the plain `Table` param.
+type WritableTable = (Table | EntityTableMeta) & NotExecutorOnly;
+
 /**
  * TenantDb scope modes:
  *
@@ -45,21 +56,15 @@ export type TenantDb = {
   ): Promise<readonly T[]>;
   fetchOne<T = Record<string, unknown>>(table: Table, where: WhereObject): Promise<T | undefined>;
   insertOne<T = Record<string, unknown>>(
-    table: Table,
+    table: WritableTable,
     values: Record<string, unknown>,
   ): Promise<T | undefined>;
   updateMany<T = Record<string, unknown>>(
-    table: Table,
+    table: WritableTable,
     set: Record<string, unknown>,
     where: WhereObject,
   ): Promise<readonly T[]>;
-  // Method-form writes (ctx.db.insertOne/updateMany/deleteMany) keep the erased
-  // Table param: the executor-only brand is enforced on the free-function
-  // helpers (the reflexive path all production writes take), while method-form
-  // on a branded table is covered by the guard-direct-entity-writes AST guard
-  // (P5) — branding it here would force every push+write test into casts for
-  // zero production benefit (no prod code writes a projection via method-form).
-  deleteMany(table: Table, where: WhereObject): Promise<void>;
+  deleteMany(table: WritableTable, where: WhereObject): Promise<void>;
 };
 
 // @cast-boundary tenant-db-row

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/observability/__tests__/observability.integration.test.ts

@@ -1,5 +1,6 @@
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "bun:test";
 import { z } from "zod";
+import type { TableColumns } from "../../db/dialect";
 import { buildEntityTable } from "../../db/table-builder";
 import { createRegistry, defineFeature } from "../../engine";
 import type { AppContext, SaveContext } from "../../engine/types";
@@ -65,7 +66,9 @@ const todoEntity = {
 
 let postSaveInvocations = 0;
 const todoFeature = defineFeature("todo", (r) => {
-  const todoTable = buildEntityTable("todo", todoEntity);
+  // Brand (#742) is compile-time-only; the unbranded TableColumns view keeps the
+  // method-form insert (and its observability span) working — runtime shape is identical.
+  const todoTable: TableColumns = buildEntityTable("todo", todoEntity);
   r.entity("todo", todoEntity);
 
   r.writeHandler(

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 ?? {});
+}