@cosmicdrift/kumiko-framework 0.288.0 → 0.290.0

package/src/crypto/__tests__/kek-source.test.ts

@@ -0,0 +1,298 @@
+import { describe, expect, test } from "bun:test";
+import { type KekSourceEnv, resolvePlatformKeks } from "../kek-source";
+import { buildPgKmsOptions } from "../kms-wiring";
+
+const TOKEN = "scw-secret-token";
+const CIPHERTEXT_A = Buffer.from("ciphertext-a").toString("base64");
+const CIPHERTEXT_B = Buffer.from("ciphertext-b").toString("base64");
+const PLAINTEXT_A = Buffer.alloc(32, 1).toString("base64");
+
+type FetchCall = { readonly url: string; readonly init: RequestInit };
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function trackedFetch(responses: ReadonlyArray<Response>): {
+  readonly fetch: typeof globalThis.fetch;
+  readonly calls: FetchCall[];
+} {
+  const calls: FetchCall[] = [];
+  let index = 0;
+  const fetch = (async (url: string | URL, init?: RequestInit) => {
+    calls.push({ url: String(url), init: init ?? {} });
+    const response = responses[index];
+    index++;
+    if (!response) throw new Error("trackedFetch: no more responses queued");
+    return response;
+  }) as typeof globalThis.fetch;
+  return { fetch, calls };
+}
+
+describe("resolvePlatformKeks", () => {
+  test("passes through unchanged when PLATFORM_KEK is set, without ever calling fetch", async () => {
+    const { fetch, calls } = trackedFetch([]);
+    const env: KekSourceEnv = { PLATFORM_KEK: PLAINTEXT_A };
+
+    const result = await resolvePlatformKeks(env, { fetch });
+
+    expect(result).toBe(env);
+    expect(calls.length).toBe(0);
+  });
+
+  test("decrypts a lone ciphertext, posting the key id in the path and the token in X-Auth-Token", async () => {
+    const { fetch, calls } = trackedFetch([jsonResponse(200, { plaintext: PLAINTEXT_A })]);
+    const env: KekSourceEnv = {
+      PLATFORM_KEK_CIPHERTEXT: CIPHERTEXT_A,
+      PLATFORM_KEK_KMS_KEY_ID: "key-1",
+      PLATFORM_KEK_KMS_TOKEN: TOKEN,
+    };
+
+    const result = await resolvePlatformKeks(env, { fetch });
+
+    expect(result.PLATFORM_KEK).toBe(PLAINTEXT_A);
+    expect(calls.length).toBe(1);
+    expect(calls[0]?.url).toContain("/keys/key-1/decrypt");
+    expect(new Headers(calls[0]?.init.headers).get("X-Auth-Token")).toBe(TOKEN);
+  });
+
+  test("decrypts both ciphertexts with two distinct requests", async () => {
+    const { fetch, calls } = trackedFetch([
+      jsonResponse(200, { plaintext: "active-plaintext" }),
+      jsonResponse(200, { plaintext: "previous-plaintext" }),
+    ]);
+    const env: KekSourceEnv = {
+      PLATFORM_KEK_CIPHERTEXT: CIPHERTEXT_A,
+      PLATFORM_KEK_PREVIOUS_CIPHERTEXT: CIPHERTEXT_B,
+      PLATFORM_KEK_PREVIOUS_VERSION: "1",
+      PLATFORM_KEK_KMS_KEY_ID: "key-1",
+      PLATFORM_KEK_KMS_TOKEN: TOKEN,
+    };
+
+    const result = await resolvePlatformKeks(env, { fetch });
+
+    expect(result.PLATFORM_KEK).toBe("active-plaintext");
+    expect(result.PLATFORM_KEK_PREVIOUS).toBe("previous-plaintext");
+    expect(calls.length).toBe(2);
+    const bodies = calls.map((call) => JSON.parse(String(call.init.body)).ciphertext);
+    expect(bodies).toEqual([CIPHERTEXT_A, CIPHERTEXT_B]);
+  });
+
+  test("throws without the token in the message when a ciphertext has no key id", async () => {
+    const { fetch } = trackedFetch([]);
+    const env: KekSourceEnv = {
+      PLATFORM_KEK_CIPHERTEXT: CIPHERTEXT_A,
+      PLATFORM_KEK_KMS_TOKEN: TOKEN,
+    };
+
+    try {
+      await resolvePlatformKeks(env, { fetch });
+      throw new Error("unreachable");
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error);
+      const message = error instanceof Error ? error.message : "";
+      expect(message).toMatch(/all-or-none/);
+      expect(message).not.toContain(TOKEN);
+    }
+  });
+
+  test("throws without the token in the message when a ciphertext has no token", async () => {
+    const { fetch } = trackedFetch([]);
+    const env: KekSourceEnv = {
+      PLATFORM_KEK_CIPHERTEXT: CIPHERTEXT_A,
+      PLATFORM_KEK_KMS_KEY_ID: "key-1",
+      PLATFORM_KEK_KMS_TOKEN: undefined,
+    };
+
+    await expect(resolvePlatformKeks(env, { fetch })).rejects.toThrow(/all-or-none/);
+    await expect(resolvePlatformKeks(env, { fetch })).rejects.not.toThrow(new RegExp(TOKEN));
+  });
+
+  test("retries a network failure and succeeds on the next attempt", async () => {
+    const calls: string[] = [];
+    let attempt = 0;
+    const fetch = (async (url: string | URL) => {
+      calls.push(String(url));
+      attempt++;
+      if (attempt === 1) throw new TypeError("fetch failed");
+      return jsonResponse(200, { plaintext: PLAINTEXT_A });
+    }) as typeof globalThis.fetch;
+    const env: KekSourceEnv = {
+      PLATFORM_KEK_CIPHERTEXT: CIPHERTEXT_A,
+      PLATFORM_KEK_KMS_KEY_ID: "key-1",
+      PLATFORM_KEK_KMS_TOKEN: TOKEN,
+    };
+
+    const result = await resolvePlatformKeks(env, { fetch });
+
+    expect(result.PLATFORM_KEK).toBe(PLAINTEXT_A);
+    expect(calls.length).toBe(2);
+  });
+
+  test("gives up after the last attempt when every call fails at the network level", async () => {
+    const calls: string[] = [];
+    const fetch = (async (url: string | URL): Promise<Response> => {
+      calls.push(String(url));
+      throw new TypeError("fetch failed");
+    }) as typeof globalThis.fetch;
+    const env: KekSourceEnv = {
+      PLATFORM_KEK_CIPHERTEXT: CIPHERTEXT_A,
+      PLATFORM_KEK_KMS_KEY_ID: "key-1",
+      PLATFORM_KEK_KMS_TOKEN: TOKEN,
+    };
+
+    await expect(resolvePlatformKeks(env, { fetch })).rejects.toThrow(/network error or timeout/);
+    expect(calls.length).toBe(3);
+  });
+
+  test("rejects a previous ciphertext with no previous version", async () => {
+    const { fetch } = trackedFetch([jsonResponse(200, { plaintext: "previous-plaintext" })]);
+    const env: KekSourceEnv = {
+      PLATFORM_KEK_PREVIOUS_CIPHERTEXT: CIPHERTEXT_B,
+      PLATFORM_KEK_KMS_KEY_ID: "key-1",
+      PLATFORM_KEK_KMS_TOKEN: TOKEN,
+    };
+
+    await expect(resolvePlatformKeks(env, { fetch })).rejects.toThrow(
+      /PLATFORM_KEK_PREVIOUS_VERSION must be set/,
+    );
+  });
+
+  test("returns env unchanged and calls fetch zero times when nothing is set", async () => {
+    const { fetch, calls } = trackedFetch([]);
+    const env: KekSourceEnv = { SUBJECT_KEYS_DATABASE_URL: "postgres://localhost/x" };
+
+    const result = await resolvePlatformKeks(env, { fetch });
+
+    expect(result).toBe(env);
+    expect(calls.length).toBe(0);
+  });
+
+  test("retries once on HTTP 500 and succeeds on the second attempt", async () => {
+    const { fetch, calls } = trackedFetch([
+      jsonResponse(500, {}),
+      jsonResponse(200, { plaintext: PLAINTEXT_A }),
+    ]);
+    const env: KekSourceEnv = {
+      PLATFORM_KEK_CIPHERTEXT: CIPHERTEXT_A,
+      PLATFORM_KEK_KMS_KEY_ID: "key-1",
+      PLATFORM_KEK_KMS_TOKEN: TOKEN,
+    };
+
+    const result = await resolvePlatformKeks(env, { fetch });
+
+    expect(result.PLATFORM_KEK).toBe(PLAINTEXT_A);
+    expect(calls.length).toBe(2);
+  });
+
+  test("gives up after exactly one attempt on HTTP 403, no retry", async () => {
+    const { fetch, calls } = trackedFetch([jsonResponse(403, {})]);
+    const env: KekSourceEnv = {
+      PLATFORM_KEK_CIPHERTEXT: CIPHERTEXT_A,
+      PLATFORM_KEK_KMS_KEY_ID: "key-1",
+      PLATFORM_KEK_KMS_TOKEN: TOKEN,
+    };
+
+    await expect(resolvePlatformKeks(env, { fetch })).rejects.toThrow(/HTTP 403/);
+    expect(calls.length).toBe(1);
+  });
+
+  test("throws when a 2xx response carries no plaintext field", async () => {
+    const { fetch } = trackedFetch([jsonResponse(200, { notPlaintext: "x" })]);
+    const env: KekSourceEnv = {
+      PLATFORM_KEK_CIPHERTEXT: CIPHERTEXT_A,
+      PLATFORM_KEK_KMS_KEY_ID: "key-1",
+      PLATFORM_KEK_KMS_TOKEN: TOKEN,
+    };
+
+    await expect(resolvePlatformKeks(env, { fetch })).rejects.toThrow(/no plaintext field/);
+  });
+
+  // The slot-to-version mapping is the part that "silently corrupts data when
+  // it is wrong" (kms-wiring.ts) — this is the one test that would catch a
+  // swapped active/previous assignment all the way through the adapter options.
+  test("maps a decrypted active slot and a plaintext previous slot into the correct buildPgKmsOptions fields", async () => {
+    const { fetch } = trackedFetch([jsonResponse(200, { plaintext: "decrypted-active" })]);
+    const env: KekSourceEnv = {
+      PLATFORM_KEK_CIPHERTEXT: CIPHERTEXT_A,
+      PLATFORM_KEK_KMS_KEY_ID: "key-1",
+      PLATFORM_KEK_KMS_TOKEN: TOKEN,
+      PLATFORM_KEK_VERSION: "2",
+      PLATFORM_KEK_PREVIOUS: "plaintext-previous",
+      PLATFORM_KEK_PREVIOUS_VERSION: "1",
+      SUBJECT_KEYS_DATABASE_URL: "postgres://localhost/x",
+    };
+
+    const resolved = await resolvePlatformKeks(env, { fetch });
+    const options = buildPgKmsOptions({
+      ...resolved,
+      PLATFORM_KEK: resolved.PLATFORM_KEK ?? "",
+      SUBJECT_KEYS_DATABASE_URL: resolved["SUBJECT_KEYS_DATABASE_URL"] ?? "",
+    });
+
+    expect(options.platformKek).toBe("decrypted-active");
+    expect(options.previousKeks).toEqual({ 1: "plaintext-previous" });
+  });
+
+  test("rollback state: both plaintexts win over a leftover ciphertext, no fetch, no error", async () => {
+    const { fetch, calls } = trackedFetch([]);
+    const env: KekSourceEnv = {
+      PLATFORM_KEK: "current-plaintext",
+      PLATFORM_KEK_CIPHERTEXT: CIPHERTEXT_A,
+      PLATFORM_KEK_PREVIOUS: "rolled-back-plaintext",
+      PLATFORM_KEK_PREVIOUS_CIPHERTEXT: CIPHERTEXT_B,
+      PLATFORM_KEK_PREVIOUS_VERSION: "1",
+    };
+
+    const result = await resolvePlatformKeks(env, { fetch });
+
+    expect(result.PLATFORM_KEK).toBe("current-plaintext");
+    expect(result.PLATFORM_KEK_PREVIOUS).toBe("rolled-back-plaintext");
+    expect(calls.length).toBe(0);
+  });
+
+  test("names the ignored ciphertext when a leftover plaintext wins", async () => {
+    const { fetch } = trackedFetch([]);
+    const lines: string[] = [];
+    const env: KekSourceEnv = {
+      PLATFORM_KEK: PLAINTEXT_A,
+      PLATFORM_KEK_CIPHERTEXT: CIPHERTEXT_A,
+      PLATFORM_KEK_KMS_KEY_ID: "key-1",
+      PLATFORM_KEK_KMS_TOKEN: TOKEN,
+    };
+
+    await resolvePlatformKeks(env, { fetch, log: (line) => lines.push(line), logPrefix: "[ps]" });
+
+    expect(lines).toEqual([
+      "[ps] PLATFORM_KEK source=plaintext-env (ciphertext present and ignored)",
+    ]);
+  });
+
+  test("names the key id and region when the ciphertext is used, without the token or the key", async () => {
+    const { fetch } = trackedFetch([jsonResponse(200, { plaintext: PLAINTEXT_A })]);
+    const lines: string[] = [];
+    const env: KekSourceEnv = {
+      PLATFORM_KEK_CIPHERTEXT: CIPHERTEXT_A,
+      PLATFORM_KEK_KMS_KEY_ID: "key-1",
+      PLATFORM_KEK_KMS_TOKEN: TOKEN,
+    };
+
+    await resolvePlatformKeks(env, { fetch, log: (line) => lines.push(line) });
+
+    expect(lines).toEqual(["PLATFORM_KEK source=key-manager keyId=key-1 region=fr-par"]);
+    expect(lines.join("\n")).not.toContain(TOKEN);
+    expect(lines.join("\n")).not.toContain(PLAINTEXT_A);
+  });
+
+  test("says nothing when neither slot is configured", async () => {
+    const { fetch } = trackedFetch([]);
+    const lines: string[] = [];
+
+    await resolvePlatformKeks({}, { fetch, log: (line) => lines.push(line) });
+
+    expect(lines).toEqual([]);
+  });
+});

package/src/crypto/__tests__/pii-field-encryption.test.ts

@@ -28,7 +28,7 @@ const ENTITY_NAME = "pii-entity";
 const userLikeEntity = createEntity({
   fields: {
     email: createTextField({ required: true, personal: "self", find: "none" }),
-    role: createTextField(),
+    role: createTextField({ personal: false, reason: "test_fixture" }),
   },
   table: "pii_users",
 });
@@ -39,7 +39,7 @@ const commentEntity = createEntity({
       personal: { of: "authorId" },
       find: "none",
     }),
-    authorId: createTextField({ required: true }),
+    authorId: createTextField({ personal: false, reason: "test_fixture", required: true }),
   },
   table: "pii_comments",
 });

package/src/crypto/__tests__/subject-resolver.test.ts

@@ -11,7 +11,7 @@ import {
 const userLikeEntity = createEntity({
   fields: {
     email: createTextField({ required: true, personal: "self", find: "none" }),
-    role: createTextField(),
+    role: createTextField({ personal: false, reason: "test_fixture" }),
   },
   table: "resolver_users",
   idType: "uuid",
@@ -23,7 +23,7 @@ const commentEntity = createEntity({
       personal: { of: "authorId" },
       find: "none",
     }),
-    authorId: createTextField({ required: true }),
+    authorId: createTextField({ personal: false, reason: "test_fixture", required: true }),
   },
   table: "resolver_comments",
 });

package/src/crypto/index.ts

@@ -15,6 +15,7 @@ export {
 } from "./event-pii";
 export { InMemoryKmsAdapter } from "./in-memory-kms-adapter";
 export { isSelfPiiField } from "./is-self-pii-field";
+export { type KekSourceEnv, type KekSourceOptions, resolvePlatformKeks } from "./kek-source";
 export {
   isLocalKeyKmsAdapter,
   KeyAlreadyExistsError,
@@ -46,7 +47,9 @@ export {
   type PgKmsRotationEnv,
   type PlaintextPiiWiring,
   requireKmsWiring,
+  requireKmsWiringAsync,
   resolveKmsWiring,
+  resolveKmsWiringAsync,
 } from "./kms-wiring";
 export {
   createPgKmsAdapter,

package/src/crypto/kek-source.ts

@@ -0,0 +1,189 @@
+// Resolves PLATFORM_KEK / PLATFORM_KEK_PREVIOUS from a Key Manager ciphertext
+// when no plaintext is set, so the KEK need not sit in the pod env in the
+// clear. `PLATFORM_KEK` stays the source of truth: a plaintext value always
+// wins over its ciphertext sibling, with no request made at all.
+
+const SCALEWAY_KEY_MANAGER_API_VERSION = "v1alpha1";
+const DEFAULT_REGION = "fr-par";
+const DECRYPT_TIMEOUT_MS = 5_000;
+const RETRY_DELAYS_MS = [200, 800];
+
+export type KekSourceEnv = {
+  readonly PLATFORM_KEK?: string | undefined;
+  readonly PLATFORM_KEK_CIPHERTEXT?: string | undefined;
+  readonly PLATFORM_KEK_PREVIOUS?: string | undefined;
+  readonly PLATFORM_KEK_PREVIOUS_CIPHERTEXT?: string | undefined;
+  readonly PLATFORM_KEK_PREVIOUS_VERSION?: string | undefined;
+  readonly PLATFORM_KEK_KMS_KEY_ID?: string | undefined;
+  readonly PLATFORM_KEK_KMS_TOKEN?: string | undefined;
+  readonly PLATFORM_KEK_KMS_REGION?: string | undefined;
+  readonly [key: string]: string | undefined;
+};
+
+export type KekSourceOptions = {
+  readonly fetch?: typeof globalThis.fetch;
+  readonly logPrefix?: string;
+  /** Where the boot line naming the KEK source goes. Defaults to `console.info`. */
+  readonly log?: (message: string) => void;
+};
+
+function isRetryableStatus(status: number): boolean {
+  return status >= 500;
+}
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Scaleway's decrypt SLA is 99.5% — a bootpath that gives up on the first
+// transient 5xx or timeout trades a rare retry for a routine boot failure.
+// 4xx means the request itself is wrong (bad token, bad key id) and no
+// amount of retrying fixes that, so it fails fast instead of stalling boot.
+async function decryptCiphertext(
+  ciphertext: string,
+  keyId: string,
+  token: string,
+  region: string,
+  fetchImpl: typeof globalThis.fetch,
+  logPrefix: string | undefined,
+): Promise<string> {
+  const url = `https://api.scaleway.com/key-manager/${SCALEWAY_KEY_MANAGER_API_VERSION}/regions/${region}/keys/${keyId}/decrypt`;
+  const prefix = logPrefix ? `${logPrefix} ` : "";
+  const maxAttempts = RETRY_DELAYS_MS.length + 1;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    let response: Response;
+    try {
+      response = await fetchImpl(url, {
+        method: "POST",
+        headers: { "X-Auth-Token": token, "Content-Type": "application/json" },
+        body: JSON.stringify({ ciphertext }),
+        signal: AbortSignal.timeout(DECRYPT_TIMEOUT_MS),
+      });
+    } catch {
+      if (attempt < maxAttempts) {
+        await sleep(RETRY_DELAYS_MS[attempt - 1] ?? 0);
+        continue;
+      }
+      throw new Error(
+        `${prefix}Key Manager decrypt failed for key ${keyId}: network error or timeout`,
+      );
+    }
+
+    if (!response.ok) {
+      if (isRetryableStatus(response.status) && attempt < maxAttempts) {
+        await sleep(RETRY_DELAYS_MS[attempt - 1] ?? 0);
+        continue;
+      }
+      throw new Error(
+        `${prefix}Key Manager decrypt failed for key ${keyId}: HTTP ${response.status}`,
+      );
+    }
+
+    let body: { plaintext?: unknown };
+    try {
+      body = (await response.json()) as { plaintext?: unknown };
+    } catch {
+      throw new Error(
+        `${prefix}Key Manager decrypt for key ${keyId} returned an unparseable response`,
+      );
+    }
+    if (typeof body.plaintext !== "string") {
+      throw new Error(`${prefix}Key Manager decrypt for key ${keyId} returned no plaintext field`);
+    }
+    return body.plaintext;
+  }
+  throw new Error(`${prefix}Key Manager decrypt failed for key ${keyId}: retries exhausted`);
+}
+
+async function resolveSlot(
+  plaintext: string | undefined,
+  ciphertext: string | undefined,
+  env: KekSourceEnv,
+  options: KekSourceOptions,
+  fetchImpl: typeof globalThis.fetch,
+): Promise<string | undefined> {
+  if (plaintext) return plaintext;
+  if (!ciphertext) return undefined;
+
+  const keyId = env.PLATFORM_KEK_KMS_KEY_ID;
+  const token = env.PLATFORM_KEK_KMS_TOKEN;
+  if (!keyId || !token) {
+    const prefix = options.logPrefix ? `${options.logPrefix} ` : "";
+    throw new Error(
+      `${prefix}PLATFORM_KEK_KMS_KEY_ID / PLATFORM_KEK_KMS_TOKEN are all-or-none with a KEK ciphertext — a partial set means the KMS wiring is broken.`,
+    );
+  }
+  const region = env.PLATFORM_KEK_KMS_REGION ?? DEFAULT_REGION;
+  return decryptCiphertext(ciphertext, keyId, token, region, fetchImpl, options.logPrefix);
+}
+
+// A leftover plaintext beside a ciphertext boots green while nothing was
+// migrated, which is indistinguishable from a finished cutover unless the
+// boot says which source won. Never carries a key value, only its origin.
+function describeKekSource(
+  name: string,
+  plaintext: string | undefined,
+  ciphertext: string | undefined,
+  env: KekSourceEnv,
+): string | undefined {
+  if (plaintext) {
+    return ciphertext
+      ? `${name} source=plaintext-env (ciphertext present and ignored)`
+      : `${name} source=plaintext-env`;
+  }
+  if (!ciphertext) return undefined;
+  const region = env.PLATFORM_KEK_KMS_REGION ?? DEFAULT_REGION;
+  return `${name} source=key-manager keyId=${env.PLATFORM_KEK_KMS_KEY_ID} region=${region}`;
+}
+
+// Each slot resolves independently so a rollback that clears one slot's
+// plaintext (leaving its ciphertext/_VERSION behind or gone) never blocks the
+// other slot's fallback path — the trio check downstream still applies.
+export async function resolvePlatformKeks(
+  env: KekSourceEnv,
+  options: KekSourceOptions = {},
+): Promise<KekSourceEnv> {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+
+  const active = await resolveSlot(
+    env.PLATFORM_KEK,
+    env.PLATFORM_KEK_CIPHERTEXT,
+    env,
+    options,
+    fetchImpl,
+  );
+  const previous = await resolveSlot(
+    env.PLATFORM_KEK_PREVIOUS,
+    env.PLATFORM_KEK_PREVIOUS_CIPHERTEXT,
+    env,
+    options,
+    fetchImpl,
+  );
+
+  const prefix = options.logPrefix ? `${options.logPrefix} ` : "";
+  // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
+  const log = options.log ?? console.info;
+  for (const line of [
+    describeKekSource("PLATFORM_KEK", env.PLATFORM_KEK, env.PLATFORM_KEK_CIPHERTEXT, env),
+    describeKekSource(
+      "PLATFORM_KEK_PREVIOUS",
+      env.PLATFORM_KEK_PREVIOUS,
+      env.PLATFORM_KEK_PREVIOUS_CIPHERTEXT,
+      env,
+    ),
+  ]) {
+    if (line) log(`${prefix}${line}`);
+  }
+
+  if (previous && !env.PLATFORM_KEK_PREVIOUS_VERSION) {
+    throw new Error(
+      `${prefix}PLATFORM_KEK_PREVIOUS_VERSION must be set when PLATFORM_KEK_PREVIOUS is set.`,
+    );
+  }
+
+  if (active === env.PLATFORM_KEK && previous === env.PLATFORM_KEK_PREVIOUS) {
+    return env;
+  }
+  return { ...env, PLATFORM_KEK: active, PLATFORM_KEK_PREVIOUS: previous };
+}

package/src/crypto/kms-wiring.ts

@@ -8,6 +8,7 @@
 // is wrong), `resolveKmsWiring` is the boot entry point that also constructs
 // the adapter.
 
+import { type KekSourceOptions, resolvePlatformKeks } from "./kek-source";
 import { createPgKmsAdapter, type PgKmsAdapter, type PgKmsAdapterOptions } from "./pg-kms-adapter";
 
 // The index signature is what lets callers pass `process.env` directly. Without
@@ -186,3 +187,22 @@ export function requireKmsWiring(
   }
   return wiring;
 }
+
+/** Same as `resolveKmsWiring`, but resolves `PLATFORM_KEK`/`PLATFORM_KEK_PREVIOUS`
+ *  from a Key Manager ciphertext first when no plaintext is set — see
+ *  `resolvePlatformKeks`. The validation stays in the sync function; this only
+ *  adds the KEK-fetching step in front of it. */
+export async function resolveKmsWiringAsync(
+  env: KmsWiringEnv,
+  options: KmsWiringOptions & KekSourceOptions = {},
+): Promise<KmsWiring> {
+  return resolveKmsWiring(await resolvePlatformKeks(env, options), options);
+}
+
+/** Async counterpart to `requireKmsWiring`, KEK-resolving like `resolveKmsWiringAsync`. */
+export async function requireKmsWiringAsync(
+  env: KmsWiringEnv,
+  options: KmsWiringOptions & KekSourceOptions = {},
+): Promise<ActiveKmsWiring> {
+  return requireKmsWiring(await resolvePlatformKeks(env, options), options);
+}

package/src/db/__tests__/blind-index.integration.test.ts

@@ -37,7 +37,7 @@ const personEntity = createEntity({
   table: "read_bidx_persons",
   fields: {
     email: createTextField({ required: true, personal: "self", find: "exact" }),
-    firstName: createTextField(),
+    firstName: createTextField({ personal: false, reason: "test_fixture" }),
   },
 });
 const personFeature = defineFeature("bidxtest", (r) => {

package/src/db/__tests__/eagerload.integration.test.ts

@@ -50,7 +50,12 @@ const contactEntity = createEntity({
   fields: {
     name: createTextField({ required: true, personal: false, reason: "test_fixture" }),
     email: createTextField({ required: true, personal: "tenant", find: "none" }),
-    iban: createTextField({ required: true, encrypted: true }),
+    iban: createTextField({
+      personal: false,
+      reason: "test_fixture",
+      required: true,
+      encrypted: true,
+    }),
   },
 });
 const leadEntity = createEntity({
@@ -72,7 +77,12 @@ const ownedContactEntity = createEntity({
   fields: {
     name: createTextField({ required: true, personal: false, reason: "test_fixture" }),
     email: createTextField({ required: true, personal: "tenant", find: "none" }),
-    iban: createTextField({ required: true, encrypted: true }),
+    iban: createTextField({
+      personal: false,
+      reason: "test_fixture",
+      required: true,
+      encrypted: true,
+    }),
   },
   access: { read: { admin: from("user:id", "ownerId") } },
 });

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

@@ -13,8 +13,8 @@ describe("entity-field-encryption", () => {
   const entity = createEntity({
     table: "read_enc_test",
     fields: {
-      email: createTextField({ required: true }),
-      secretNote: createTextField({ encrypted: true }),
+      email: createTextField({ personal: false, reason: "test_fixture", required: true }),
+      secretNote: createTextField({ personal: false, reason: "test_fixture", encrypted: true }),
     },
   });
   const encryptedFields = collectEncryptedFieldNames(entity);

package/src/db/__tests__/event-store-executor-context.pii-roundtrip.test.ts

@@ -16,7 +16,7 @@ describe("event-store-executor-context — encryptForStorage/decryptForRead laye
   const entity = createEntity({
     table: "pii_roundtrip_test",
     fields: {
-      userId: createTextField({ required: true }),
+      userId: createTextField({ personal: false, reason: "test_fixture", required: true }),
       // Both markers at once — the auth-mfa.totpSecret/recoveryCodes shape
       // that first surfaced the ordering bug (pii-subject-encryption
       // integration test).

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

@@ -34,9 +34,14 @@ const cipher = createTestEnvelopeCipher(TEST_KEY);
 const entity = createEntity({
   table: "read_money_orders",
   fields: {
-    ownerId: createTextField({ required: true }),
+    ownerId: createTextField({ personal: false, reason: "test_fixture", required: true }),
     grossTotal: createMoneyField(),
-    billingIban: createTextField({ required: true, encrypted: true }),
+    billingIban: createTextField({
+      personal: false,
+      reason: "test_fixture",
+      required: true,
+      encrypted: true,
+    }),
   },
   // A non-"all" read rule forces buildOwnershipClause into the
   // ownership.kind==="sql" raw-SQL branch that list()/detail() read through.