@cosmicdrift/kumiko-framework 0.288.0 → 0.289.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.288.0",
+  "version": "0.289.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>",
@@ -198,8 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.288.0",
-    "@cosmicdrift/kumiko-types": "0.288.0",
+    "@cosmicdrift/kumiko-http": "0.289.0",
+    "@cosmicdrift/kumiko-types": "0.289.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.288.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.289.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,61 @@
 [
+  {
+    "version": "0.289.0",
+    "type": "breaking",
+    "title": "appendProvenanceEvent enforces event.tenantId === db.tenantId",
+    "detail": "`appendProvenanceEvent(db, event)` checked the event type namespace but wrote `event.tenantId` unverified while granting itself the framework-fixed unsafeRaw reason internally. Since `createLLMProviderForTenant(ctx, tenantId, …)` takes the tenantId as an argument, that made the entry point a cross-tenant write door with no escapeHatch declaration behind it.\nThe check now runs after `unsafeRawForDeclaredStep` — so a holder not built by `createTenantDb` still fails closed with `InternalError` first — and before the savepoint, so a rejected append leaves no row. It is unconditional, including `mode: \"system\"`: `crossTenantRebinders` keeps the original tenantId and only flips the mode, so a system-scoped db must not append provenance for a foreign tenant either.\n`appendProvenanceEvent` deliberately keeps `withUnsafeRawGrant` + `unsafeRawForDeclaredStep` instead of resolving the runner through the ungated `tenantDbRunner`, because that grant path is the choke point the member-read lock in kumiko-framework#2927 hooks into.",
+    "migration": "appendProvenanceEvent rejects with AccessDeniedError when event.tenantId does not match the tenantId of the passed TenantDb. Provenance for a foreign tenant has no path left through this entry point — a caller that needs it declares its own escapeHatch path instead. Blast radius checked: every known call site in kumiko-enterprise passes event.user.tenantId through, so no call site changes."
+  },
+  {
+    "version": "0.289.0",
+    "type": "breaking",
+    "title": "Boot fails when an anonymous-accessible handler declares no rateLimit",
+    "detail": "validateAnonymousRateLimit (packages/framework/src/engine/boot-validator/entity-handler.ts) previously returned early when a handler declared no rateLimit at all, so an anonymous, internet-facing handler with zero throttling passed boot silently while one with a merely wrong bucket (rateLimit.per=\"user\") was rejected. The check now runs for every handler whose access.roles includes \"anonymous\": it still skips openToAll handlers (they never admit anonymous) and rateLimit: { disabled: true, reason } declarations, but a handler with access.roles including \"anonymous\" and no rateLimit at all now throws at boot, naming the handler.",
+    "migration": "Every handler whose access.roles includes \"anonymous\" needs a rateLimit declaration: either rateLimit: { per: \"ip\" | \"ip+handler\", limit, windowSeconds } (per must not be \"user\"/\"user+handler\" — anonymous callers share user.id=\"anonymous\", so a user-keyed bucket is a single global tap), or the documented exception rateLimit: { disabled: true, reason: \"...\" } for a handler that must not be rate-limited. This PR fixes the eight bundled-features handlers that tripped this at authoring time: compliance-profiles:query:sub-processors, template-resolver:query:by-slug, template-resolver:query:by-tenant, managed-pages:query:by-slug, managed-pages:query:by-tenant-published, managed-pages:query:branding, auth-email-password:query:signup-registration-status, seo:query:config."
+  },
+  {
+    "version": "0.289.0",
+    "type": "breaking",
+    "title": "ctx.db.unsafeRaw is denied under ctx.queryAsMember",
+    "migration": "Query handlers reached through ctx.queryAsMember can no longer call ctx.db.unsafeRaw — not even for reads. Move them to the ctx.db query APIs, or stop calling them via queryAsMember. Consequence for kumiko-enterprise: ai-call provenance writes under queryAsMember now fail closed; withProvenance swallows the error and counts provenance_drop_total."
+  },
+  {
+    "version": "0.289.0",
+    "type": "improvement",
+    "title": "Drawer gains a modal prop for non-modal side panels",
+    "detail": "Drawer accepts modal (default true, behavior unchanged). With modal={false} the overlay and the focus trap are gone, so the page behind stays interactive and its text can be selected and copied; Escape still closes, a click beside the panel does not."
+  },
+  {
+    "version": "0.289.0",
+    "type": "improvement",
+    "title": "Entity graph traversal helpers for cross-tenant ownership changes",
+    "detail": "physicalColumnName is now exported from @cosmicdrift/kumiko-framework/db (was framework-internal). storageKeyStemPrefix (files/file-handle.ts) gives the prefix that covers a stored file's key plus every derive()d variant. StorageProviderHookCtx (EXT_STORAGE_PROVIDER destroy hooks) gains db: DbRunner — the tenant-destroy stage runner already carried it for this hook family unconditionally, this only widens the declared type to match. TenantDataHookCtx (EXT_TENANT_DATA destroy hooks) gains fileProviderResolver and log, threaded through from the same stage runner. Built for the tenant-handover bundled feature (kumiko-framework#3035); no behavior change for existing hook implementations that don't read the new fields."
+  },
+  {
+    "version": "0.289.0",
+    "type": "fix",
+    "title": "EventDispatcher gains drain() for race-free test teardown",
+    "detail": "New `EventDispatcher.drain(): Promise<void>` waits out a pass already in flight (the timer tick or LISTEN/NOTIFY wake-up a suite's own `.start()` triggered) without touching the timer or the LISTEN subscription — unlike `stop()`, the dispatcher keeps running afterwards. `stack/table-helpers.ts`'s `resetEventStore` now calls it before truncating `kumiko_events` and the other framework tables, so a beforeEach/afterEach reset can no longer race a pass this same dispatcher started (kumiko-framework#3017): every suite that calls `resetEventStore` after starting the dispatcher (directly or via `jobs`) inherits the fix automatically. No behavior change for suites that never start the dispatcher — `drain()` is then a no-op, since nothing is ever in flight."
+  },
+  {
+    "version": "0.289.0",
+    "type": "improvement",
+    "title": "Event-store executor writes accept a declarative `expect:` precondition",
+    "detail": "`expect: { field: value }` on an executor write applies the change only if those fields still hold at write time, turning a check-then-act sequence into one step. Values are scalars (string/number/boolean/null) compared with strict equality; several fields mean AND, and the first mismatch names its field. A failed precondition raises the new `PreconditionFailedError` instead of writing.\nThe precondition fields and the `version` used for the append are read in one query, so a concurrent writer cannot slip between the check and the append — reading them separately reproduced a ~40% failure rate under real concurrency. The version is taken from the event stream itself, not from the projection row: a projection `version` is only in step for rows the executor wrote, so a row seeded directly would otherwise be checked against a predecessor that never existed."
+  },
+  {
+    "version": "0.289.0",
+    "type": "improvement",
+    "title": "PLATFORM_KEK can now be resolved from a Key Manager ciphertext at boot",
+    "detail": "New `resolvePlatformKeks` (packages/framework/src/crypto/kek-source.ts) decrypts `PLATFORM_KEK_CIPHERTEXT` / `PLATFORM_KEK_PREVIOUS_CIPHERTEXT` through Scaleway Key Manager when the matching plaintext (`PLATFORM_KEK` / `PLATFORM_KEK_PREVIOUS`) is absent, so the KEK no longer has to sit in the pod env in the clear. Each slot resolves independently: a plaintext value always wins over its ciphertext sibling with no request made, which keeps a KEK rollback bootable without a network call. `resolveKmsWiringAsync` and `requireKmsWiringAsync` wrap the existing sync `resolveKmsWiring` / `requireKmsWiring` with this resolution step; the sync functions and every other exported signature are unchanged. `PLATFORM_KEK` plaintext stays fully valid and keeps precedence — this is purely additive. Boot now logs one line per configured slot naming the source it used (`source=plaintext-env`, `source=key-manager keyId=… region=…`, and explicitly `(ciphertext present and ignored)` when a leftover plaintext wins), because a half-finished cutover otherwise boots green and looks exactly like a finished one. The line carries no key material and no token; `options.log` redirects it, the default is `console.info`."
+  },
+  {
+    "version": "0.289.0",
+    "type": "breaking",
+    "title": "requiredKeysFromScreen reads section.groups — group field labels and group titles are i18n-required",
+    "detail": "`requiredKeysFromScreen` (packages/framework/src/i18n/required-surface-keys.ts) read only `section.fields` in all six `EditFieldsSection` branches (`entityEdit`, `actionForm`, `secretMint` mint + confirm layout, `configEdit`, `projectionDetail`), so a field declared through `section.groups` never reached the required-key set and `groups[].title` was never required at all — while `computeEditViewModel` translates a group title exactly like a section title. `validateI18nSurfaceKeys` therefore let a screen boot with untranslated group field labels and group titles, the one error class that guard exists for.\nThe new `sectionFieldSpecs` in packages/framework/src/engine/screen-helpers.ts returns the union of `section.fields` and `section.groups[].fields` (a union, unlike the boot-validator's either-or `flattenFieldsOrGroups`, which runs after the fields-XOR-groups check) and is used at all six branches; each branch now also pushes every `groups[].title` alongside `section.title`, honoring the same `treatDotFormAsKey` option. The `writeForm` branch in `projectionDetail` is unchanged — `EditWriteFormSection` has no `groups`.",
+    "migration": "The i18n boot guard now demands translations it silently skipped before. An app whose entityEdit/actionForm/secretMint/configEdit/projectionDetail screens declare fields through `layout.sections[].groups` can newly fail boot with `required translation key missing: \"<feature>:entity:<entity>:field:<name>\"`. Add the missing field-label keys (or a `fieldLabels` override, where that screen type supports one) for every field declared under `groups[].fields`. Colon-form `groups[].title` values are now required too — add the key, or keep the title as literal display text (no colon, no `i18nKey()`) if it is not meant to be translated. Dot-form group titles behave exactly like dot-form section titles: only required when the caller passes `treatDotFormAsKey`."
+  },
   {
     "version": "0.287.0",
     "type": "improvement",

package/src/compliance/__tests__/sub-processors.test.ts

@@ -113,6 +113,16 @@ describe("KUMIKO_SUB_PROCESSORS", () => {
           "sccRequired": false,
           "status": "active",
         },
+        {
+          "appliesTo": [
+            "all-tiers",
+          ],
+          "name": "Scaleway SAS",
+          "optInOnly": false,
+          "region": "EU (France)",
+          "sccRequired": false,
+          "status": "active",
+        },
       ]
     `);
   });

package/src/compliance/sub-processors.ts

@@ -4,7 +4,10 @@
 // Plattform-Betrieb einsetzt. Wird oeffentlich exposed unter
 //   /api/compliance/sub-processors        (JSON, Sprint 1)
 //   /api/compliance/sub-processors.rss    (RSS, Sprint 1)
-//   kumiko.rocks/subprocessors               (HTML, Marketing-Repo)
+//
+// Separate from the public marketing overview (kumiko.rocks/subprocessors),
+// which is compiled independently from templates/legal/_shared/subprocessors/
+// catalog.*.md. The two lists are not synced.
 //
 // Tenant-Admins muessen ueber Add/Change/Remove informiert werden mit
 // Lead-Time aus dem Compliance-Profile (typisch 30d). Cron-Job kommt
@@ -132,6 +135,16 @@ export const KUMIKO_SUB_PROCESSORS: readonly SubProcessor[] = [
     appliesTo: ["all-tiers"],
     status: "active",
   },
+  {
+    name: "Scaleway SAS",
+    purpose:
+      "Offsite Backup Mirror (Object Storage); planned: platform key custody (Key Manager) and Transactional Email",
+    region: "EU (France)",
+    dpa: "https://www.scaleway.com/en/contracts/",
+    addedAt: "2026-09-18",
+    appliesTo: ["all-tiers"],
+    status: "active",
+  },
 ];
 
 /**

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/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 };
+}