@cosmicdrift/kumiko-bundled-features 0.116.1 → 0.119.0

package/src/sessions/schema/user-session.ts

@@ -53,15 +53,17 @@ export const userSessionEntity = createEntity({
     revokedAt: createTimestampField({
       access: { write: access.privileged },
     }),
+    // Subject is the session's user, not the session row — a user-forget
+    // must shred these, so the key hangs off userId (sid-self would orphan).
     ip: createTextField({
       maxLength: 64,
       access: { write: access.privileged },
-      pii: true,
+      userOwned: { ownerField: "userId" },
     }),
     userAgent: createTextField({
       maxLength: 512,
       access: { write: access.privileged },
-      pii: true,
+      userOwned: { ownerField: "userId" },
     }),
   },
 });

package/src/sessions/session-callbacks.ts

@@ -10,9 +10,10 @@ import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "temporal-polyfill";
+import { encryptForDirectWrite } from "../shared";
 import { USER_STATUS, type UserStatus, userTable } from "../user";
 import { DEFAULT_SESSION_EXPIRY_MS } from "./constants";
-import { userSessionTable } from "./schema/user-session";
+import { userSessionEntity, userSessionTable } from "./schema/user-session";
 
 // Locked accounts whose live sessions must be refused. deletionRequested is
 // intentionally absent — it's a reversible grace period and the user needs
@@ -55,15 +56,23 @@ export function createSessionCallbacks(opts: SessionCallbacksOptions): SessionCa
       const sid = generateId();
       const now = Temporal.Now.instant();
       const expiresAt = now.add({ milliseconds: ttlMs });
-      await insertOne(db, userSessionTable, {
-        id: sid,
-        tenantId: user.tenantId,
-        userId: user.id,
-        createdAt: now,
-        expiresAt,
-        ip: meta.ip,
-        userAgent: meta.userAgent,
-      });
+      await insertOne(
+        db,
+        userSessionTable,
+        await encryptForDirectWrite(
+          userSessionEntity,
+          {
+            id: sid,
+            tenantId: user.tenantId,
+            userId: user.id,
+            createdAt: now,
+            expiresAt,
+            ip: meta.ip,
+            userAgent: meta.userAgent,
+          },
+          "sessions:create",
+        ),
+      );
       return sid;
     },
 

package/src/shared/decrypt-stored-pii.ts

@@ -0,0 +1,19 @@
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
+import {
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
+
+// Raw reads (fetchOne/selectMany) return the stored column value — with an
+// active KMS that is ciphertext (self-describing: it names its own subject,
+// so no entity/field context is needed). An erased subject yields the
+// sentinel, which matches no real value.
+export async function decryptStoredPii(value: string, fallbackRequestId: string): Promise<string> {
+  const kms = configuredPiiSubjectKms();
+  if (!kms) return value;
+  const out = await decryptPiiFieldValues({ value }, ["value"], kms, {
+    requestId: requestContext.get()?.requestId ?? fallbackRequestId,
+  });
+  const decrypted = out["value"];
+  return typeof decrypted === "string" ? decrypted : value;
+}

package/src/shared/encrypt-for-direct-write.ts

@@ -0,0 +1,23 @@
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
+import {
+  collectPiiSubjectFields,
+  configuredPiiSubjectKms,
+  encryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
+
+// Unmanaged direct-write stores (r.unmanagedTable) skip the executor, so its
+// PII encryption never runs — every insert of subject-annotated fields must
+// go through this instead, and the feature declares { piiEncryptedOnWrite:
+// true } at the registration site (enforced by the registry, #820).
+export async function encryptForDirectWrite(
+  entity: EntityDefinition,
+  row: Record<string, unknown>,
+  fallbackRequestId: string,
+): Promise<Record<string, unknown>> {
+  const kms = configuredPiiSubjectKms();
+  if (!kms) return row;
+  return encryptPiiFieldValues(row, entity, collectPiiSubjectFields(entity), kms, {
+    requestId: requestContext.get()?.requestId ?? fallbackRequestId,
+  });
+}

package/src/shared/index.ts

@@ -5,3 +5,5 @@ export {
   type MigrationRowOutcome,
   runChunkedMigration,
 } from "./chunked-entity-migration";
+export { decryptStoredPii } from "./decrypt-stored-pii";
+export { encryptForDirectWrite } from "./encrypt-for-direct-write";

package/src/tenant/handlers/invitations.query.ts

@@ -1,6 +1,7 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
+import { decryptStoredPii } from "../../shared";
 import { INVITATION_STATUS, tenantInvitationsTable } from "../invitation-table";
 
 // Pending-Invitations-Liste für den aktuellen Tenant. Admin-only.
@@ -17,10 +18,17 @@ export const invitationsQuery = defineQueryHandler({
   schema: z.object({}),
   access: { roles: ["Admin", "SystemAdmin"] },
   handler: async (query, ctx) => {
-    const rows = await selectMany(ctx.db, tenantInvitationsTable, {
+    const rows = await selectMany<Record<string, unknown>>(ctx.db, tenantInvitationsTable, {
       tenantId: query.user.tenantId,
       status: INVITATION_STATUS.pending,
     });
-    return rows ?? [];
+    return Promise.all(
+      (rows ?? []).map(async (row) => {
+        const email = row["email"];
+        return typeof email === "string"
+          ? { ...row, email: await decryptStoredPii(email, "tenant:invitations") }
+          : row;
+      }),
+    );
   },
 });

package/src/tenant/invitation-table.ts

@@ -58,7 +58,7 @@ export const tenantInvitationEntity = createEntity({
   fields: {
     // Eingeladene Email — case-insensitive normalisiert beim Insert.
     // PII bis zur Annahme (danach hat der User selbst seine email in users).
-    email: createTextField({ required: true, maxLength: 320, pii: true }),
+    email: createTextField({ required: true, maxLength: 320, pii: true, lookupable: true }),
     // Membership-Rolle die dem User nach Accept gegeben wird. Default
     // im handler ist "Admin" (Co-Admin-Pattern für kleine Teams).
     role: createTextField({ required: true, maxLength: 50 }),
@@ -70,7 +70,8 @@ export const tenantInvitationEntity = createEntity({
       default: "pending",
     }),
     // userId des einladenden Admins (für Audit-Trail "wer hat eingeladen").
-    invitedBy: createTextField({ required: true, pii: true }),
+    // Self-referencing ownerField: the field's own value IS the owner userId.
+    invitedBy: createTextField({ required: true, userOwned: { ownerField: "invitedBy" } }),
     // UI-Anzeige — Wahrheit liegt in Redis-TTL.
     expiresAt: createTimestampField({ required: true }),
   },

package/src/user/schema/user.ts

@@ -67,6 +67,7 @@ export const userEntity = createEntity({
       format: "email",
       maxLength: 320,
       pii: true,
+      lookupable: true,
       access: { write: access.privileged },
     }),
 
@@ -79,8 +80,10 @@ export const userEntity = createEntity({
     }),
 
     // Profile — user-editable. Display-name is real-name in most apps,
-    // so treat as PII for DSGVO export/forget pipelines.
-    displayName: createTextField({ required: true, maxLength: 100, searchable: true, pii: true }),
+    // so treat as PII for DSGVO export/forget pipelines. NOT searchable:
+    // substring search on an encrypted field would require plaintext copies
+    // in the search index (boot-validator rejects the combination, #818).
+    displayName: createTextField({ required: true, maxLength: 100, pii: true }),
     locale: createTextField({ maxLength: 10, default: "de" }),
 
     // Which tenant should this user land in on next login. Set by the login

package/src/user-data-rights/__tests__/anonymous-deletion-kms.integration.test.ts

@@ -0,0 +1,143 @@
+// Anonymer Deletion-Flow mit aktivem PII-KMS + Blind-Index (#818 PR 2):
+// die User-Row liegt verschlüsselt in der DB. request-deletion-by-email muss
+// den User über die email_bidx-Spalte finden und die Verify-Mail an den
+// KLARTEXT schicken (vorher: Ciphertext-Adresse → Mail unzustellbar).
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configureBlindIndexKey,
+  configurePiiSubjectKms,
+  InMemoryKmsAdapter,
+  isPiiCiphertext,
+  resetBlindIndexKeyForTests,
+  resetPiiSubjectKmsForTests,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { resetTestTables } from "@cosmicdrift/kumiko-framework/testing";
+import {
+  createComplianceProfilesFeature,
+  tenantComplianceProfileEntity,
+  tenantComplianceProfileTable,
+} from "../../compliance-profiles";
+import { createDataRetentionFeature } from "../../data-retention";
+import { createSessionsFeature } from "../../sessions";
+import { USER_STATUS, userEntity, userTable } from "../../user";
+import { createUserFeature } from "../../user/feature";
+import { seedUser } from "../../user/seeding";
+import { createUserDataRightsFeature } from "../feature";
+import type { SendDeletionVerificationEmailFn } from "../handlers/request-deletion-by-email.write";
+
+const REQUEST_BY_EMAIL = "user-data-rights:write:request-deletion-by-email";
+const CONFIRM_BY_TOKEN = "user-data-rights:write:confirm-deletion-by-token";
+const DELETION_SECRET = "test-deletion-secret-0123456789abcdef";
+const VERIFY_URL = "https://app.example.test/delete-account/confirm";
+const ALICE_EMAIL = "alice.kms-deletion@example.com";
+const BIDX_KEY = Buffer.alloc(32, 7).toString("base64");
+
+const tenantA = testTenantId(1);
+
+type VerifyArgs = Parameters<SendDeletionVerificationEmailFn>[0];
+const verifyCalls: VerifyArgs[] = [];
+const sendDeletionVerificationEmail: SendDeletionVerificationEmailFn = async (args) => {
+  verifyCalls.push(args);
+};
+
+let stack: TestStack;
+let aliceId: string;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createUserFeature(),
+      createDataRetentionFeature(),
+      createComplianceProfilesFeature(),
+      createSessionsFeature(),
+      createUserDataRightsFeature({
+        deletionTokenSecret: DELETION_SECRET,
+        deletionVerifyUrl: VERIFY_URL,
+        sendDeletionVerificationEmail,
+      }),
+    ],
+    anonymousAccess: { defaultTenantId: tenantA },
+  });
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantComplianceProfileEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  verifyCalls.length = 0;
+  await resetTestTables(stack.db, [userTable, tenantComplianceProfileTable, eventsTable]);
+
+  // KMS + bidx-Key VOR dem Seed — seedUser läuft über den Executor, die
+  // Row soll den verschlüsselten Prod-Zustand abbilden.
+  configurePiiSubjectKms(new InMemoryKmsAdapter());
+  configureBlindIndexKey(BIDX_KEY);
+  ({ id: aliceId } = await seedUser(stack.db, {
+    email: ALICE_EMAIL,
+    displayName: "Alice",
+    passwordHash: "hashed",
+    emailVerified: true,
+  }));
+});
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+  resetBlindIndexKeyForTests();
+});
+
+function tokenFromLastVerifyCall(): string {
+  const url = new URL(verifyCalls[0]?.verifyUrl ?? "");
+  return url.searchParams.get("token") ?? "";
+}
+
+describe("anonymous deletion flow with active KMS", () => {
+  test("request-by-email finds the encrypted row via bidx and mails the PLAINTEXT address", async () => {
+    const rows = await asRawClient(stack.db).unsafe<Record<string, unknown>>(
+      `SELECT email, email_bidx FROM "${userTable.tableName}" WHERE id = $1`,
+      [aliceId],
+    );
+    expect(isPiiCiphertext(rows[0]?.["email"])).toBe(true);
+    expect(String(rows[0]?.["email_bidx"])).toStartWith("kumiko-bidx:v1:");
+
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: REQUEST_BY_EMAIL,
+      payload: { email: ALICE_EMAIL },
+    });
+    expect(res.status).toBe(200);
+
+    expect(verifyCalls).toHaveLength(1);
+    expect(verifyCalls[0]?.email).toBe(ALICE_EMAIL);
+    expect(verifyCalls[0]?.verifyUrl).toContain("token=");
+  });
+
+  test("confirm-by-token flips to DeletionRequested; response carries no ciphertext", async () => {
+    await stack.http.raw("POST", "/api/write", {
+      type: REQUEST_BY_EMAIL,
+      payload: { email: ALICE_EMAIL },
+    });
+    const token = tokenFromLastVerifyCall();
+    expect(token).not.toBe("");
+
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: CONFIRM_BY_TOKEN,
+      payload: { token },
+    });
+    expect(res.status).toBe(200);
+    const bodyText = await res.text();
+    expect(bodyText).not.toContain("kumiko-pii:");
+    const body = JSON.parse(bodyText) as { data?: { status?: string } };
+    expect(body.data?.status).toBe(USER_STATUS.DeletionRequested);
+  });
+});

package/src/user-data-rights/__tests__/run-forget-cleanup.integration.test.ts

@@ -17,6 +17,7 @@
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { InMemoryKmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
 import type { JobContext } from "@cosmicdrift/kumiko-framework/engine";
 import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
 import {
@@ -747,3 +748,81 @@ describe("runForgetCleanup :: per-User-Sub-Tx-Isolation (advisor-pinned Architek
     }
   });
 });
+
+// eraseKey never fails in the in-memory adapter, so the rollback test
+// overrides it to simulate a KMS outage.
+class FailingEraseKms extends InMemoryKmsAdapter {
+  override async eraseKey(): Promise<void> {
+    throw new Error("kms unavailable");
+  }
+}
+
+describe("runForgetCleanup :: crypto-shredding (subject key erase)", () => {
+  test("successful forget erases the user's subject key", async () => {
+    await seedUser(ALICE_ID, {
+      status: USER_STATUS.DeletionRequested,
+      gracePeriodEnd: instantFromOffsetMs(-60 * 1000),
+    });
+    await seedMembership(ALICE_ID, TENANT_A);
+
+    const kms = new InMemoryKmsAdapter();
+    await kms.createKey({ kind: "user", userId: ALICE_ID });
+
+    const result = await runForgetCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      now: NOW(),
+      kms,
+    });
+
+    expect(result.processedUserIds).toEqual([ALICE_ID]);
+    expect(result.errors).toHaveLength(0);
+    await expect(kms.getKey({ kind: "user", userId: ALICE_ID })).rejects.toThrow(
+      "Subject key erased",
+    );
+  });
+
+  test("user without a subject key: erase is a no-op, forget still completes", async () => {
+    await seedUser(ALICE_ID, {
+      status: USER_STATUS.DeletionRequested,
+      gracePeriodEnd: instantFromOffsetMs(-60 * 1000),
+    });
+    await seedMembership(ALICE_ID, TENANT_A);
+
+    const result = await runForgetCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      now: NOW(),
+      kms: new InMemoryKmsAdapter(),
+    });
+
+    expect(result.processedUserIds).toEqual([ALICE_ID]);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  test("eraseKey failure rolls back the user's sub-tx (stays DeletionRequested, PII intact)", async () => {
+    await seedUser(ALICE_ID, {
+      status: USER_STATUS.DeletionRequested,
+      gracePeriodEnd: instantFromOffsetMs(-60 * 1000),
+      email: "alice.erase-fail@example.com",
+    });
+    await seedMembership(ALICE_ID, TENANT_A);
+
+    const result = await runForgetCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      now: NOW(),
+      kms: new FailingEraseKms(),
+    });
+
+    expect(result.processedUserIds).toHaveLength(0);
+    expect(result.errors.length).toBeGreaterThanOrEqual(1);
+    expect(result.errors[0]?.message).toContain("kms unavailable");
+
+    // Sub-tx rollback: the anonymize hooks ran but must be undone — a user
+    // whose key survives must keep retrying, not sit half-forgotten.
+    const alice = await fetchUser(ALICE_ID);
+    expect(alice?.status).toBe(USER_STATUS.DeletionRequested);
+    expect(alice?.email).toBe("alice.erase-fail@example.com");
+  });
+});

package/src/user-data-rights/__tests__/run-user-export.integration.test.ts

@@ -16,6 +16,12 @@
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configurePiiSubjectKms,
+  encryptPiiFieldValues,
+  InMemoryKmsAdapter,
+  resetPiiSubjectKmsForTests,
+} from "@cosmicdrift/kumiko-framework/crypto";
 import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
 import {
   setupTestStack,
@@ -288,3 +294,70 @@ describe("runUserExport :: Empty-State", () => {
     expect(allUserSnippets).toEqual([]);
   });
 });
+
+describe("runUserExport :: PII-Subject-Ciphertexte (#820)", () => {
+  test("Art. 20: bundle carries plaintext, never kumiko-pii: blobs", async () => {
+    const kms = new InMemoryKmsAdapter();
+    configurePiiSubjectKms(kms);
+    try {
+      await seedUser(ALICE_ID, { email: "alice.kms@example.com", displayName: "Alice KMS" });
+      await seedMembership(ALICE_ID, TENANT_A);
+      // Read-Pfad-Test: die Spalten tragen echten Subject-Ciphertext, wie
+      // sie ein Executor-Write hinterlassen haette (Write-Pfad: PR 1/2).
+      const encrypted = await encryptPiiFieldValues(
+        { id: ALICE_ID, email: "alice.kms@example.com", displayName: "Alice KMS" },
+        userEntity,
+        ["email", "displayName"],
+        kms,
+        { requestId: "test" },
+      );
+      await asRawClient(stack.db).unsafe(
+        `UPDATE read_users SET email = $1, display_name = $2 WHERE id = $3`,
+        [String(encrypted["email"]), String(encrypted["displayName"]), ALICE_ID],
+      );
+
+      const bundle = await runUserExport({
+        db: stack.db,
+        registry: stack.registry,
+        userId: ALICE_ID,
+        now: NOW(),
+      });
+
+      const json = JSON.stringify(bundle);
+      expect(json).not.toContain("kumiko-pii:");
+      expect(json).toContain("alice.kms@example.com");
+      expect(json).toContain("Alice KMS");
+    } finally {
+      resetPiiSubjectKmsForTests();
+    }
+  });
+
+  test("ciphertext without a configured KMS exports an explicit marker, not the blob", async () => {
+    const kms = new InMemoryKmsAdapter();
+    configurePiiSubjectKms(kms);
+    await seedUser(ALICE_ID, { email: "alice.nokms@example.com" });
+    await seedMembership(ALICE_ID, TENANT_A);
+    const encrypted = await encryptPiiFieldValues(
+      { id: ALICE_ID, email: "alice.nokms@example.com" },
+      userEntity,
+      ["email"],
+      kms,
+      { requestId: "test" },
+    );
+    await asRawClient(stack.db).unsafe(`UPDATE read_users SET email = $1 WHERE id = $2`, [
+      String(encrypted["email"]),
+      ALICE_ID,
+    ]);
+    resetPiiSubjectKmsForTests();
+
+    const bundle = await runUserExport({
+      db: stack.db,
+      registry: stack.registry,
+      userId: ALICE_ID,
+      now: NOW(),
+    });
+    const json = JSON.stringify(bundle);
+    expect(json).not.toContain("kumiko-pii:");
+    expect(json).toContain("[encrypted:unavailable]");
+  });
+});

package/src/user-data-rights/handlers/deletion-grace-period.ts

@@ -3,6 +3,7 @@ import { addDurationSpec, type DurationSpec } from "@cosmicdrift/kumiko-framewor
 import { createSystemUser, type HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { decryptStoredPii } from "../../shared";
 import { USER_STATUS, userTable } from "../../user";
 import { updateUserLifecycle } from "../lib/update-user-lifecycle";
 
@@ -73,7 +74,9 @@ export async function startDeletionGracePeriod(
   return {
     ok: true,
     gracePeriodEnd,
-    userEmail: userRow["email"] ?? "",
+    userEmail: userRow["email"]
+      ? await decryptStoredPii(userRow["email"], "user-data-rights:grace-period")
+      : "",
     userLocale: userRow["locale"] ?? null,
   };
 }

package/src/user-data-rights/handlers/request-deletion-by-email.write.ts

@@ -95,7 +95,9 @@ export function createRequestDeletionByEmailHandler(opts: RequestDeletionByEmail
       if (opts.sendDeletionVerificationEmail) {
         try {
           await opts.sendDeletionVerificationEmail({
-            email: userRow["email"],
+            // Row value is ciphertext with an active KMS; the lookup above
+            // only matches byte-exact, so the payload IS the stored plaintext.
+            email: event.payload.email,
             verifyUrl,
             expiresAt: expiresAt.toString(),
           });

package/src/user-data-rights/run-export-jobs.ts

@@ -46,6 +46,7 @@
 
 import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { addDurationSpec } from "@cosmicdrift/kumiko-framework/compliance";
+import { PII_ERASED_SENTINEL } from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbConnection, DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
@@ -57,6 +58,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/files";
 import type { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { resolveProfileForTenant } from "../compliance-profiles";
+import { decryptStoredPii } from "../shared";
 import { userTable } from "../user";
 import { selectExportJobsForStorageCleanup } from "./db/queries/export-jobs";
 import { runUserExport, type UserExportBundle } from "./run-user-export";
@@ -767,7 +769,9 @@ async function lookupUserContact(
     locale: string | null;
   } | null;
   if (!row?.email) return null;
-  return { email: row.email, locale: row.locale ?? null };
+  const email = await decryptStoredPii(row.email, "user-data-rights:export-ready");
+  if (email === PII_ERASED_SENTINEL) return null;
+  return { email, locale: row.locale ?? null };
 }
 
 // Atom 5 — Email-Notification beim done-flip. Best-effort:

package/src/user-data-rights/run-forget-cleanup.ts

@@ -33,7 +33,12 @@
 // retried automatisch).
 
 import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import {
+  configuredPiiSubjectKms,
+  type KmsAdapter,
+  subjectIdToKey,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import { type DbRunner, nullBlindIndexesForSubject } from "@cosmicdrift/kumiko-framework/db";
 import {
   EXT_USER_DATA,
   EXT_USER_DATA_ORDER,
@@ -46,6 +51,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import type { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { resolveRetentionPolicyForTenant } from "../data-retention";
+import { decryptStoredPii } from "../shared";
 import { tenantMembershipsTable } from "../tenant";
 import { USER_STATUS, userTable } from "../user";
 import { selectUsersDueForForgetCleanup } from "./db/queries/forget-cleanup";
@@ -101,6 +107,15 @@ export interface RunForgetCleanupArgs {
     tenantId: TenantId,
   ) => Promise<UserDataStorageProvider | undefined>;
 
+  /**
+   * KMS for crypto-shredding: erases the per-user subject key after the
+   * delete-hooks, inside the per-user sub-tx, right before the status flip.
+   * Defaults to the boot-configured adapter (configurePiiSubjectKms);
+   * explicit arg is the test seam. Omitted + none configured → plaintext
+   * deployment, nothing to shred.
+   */
+  readonly kms?: KmsAdapter;
+
   /**
    * App-level tenant-occupancy model (resolved from the `tenantModel` config by
    * the cron/handler). The pipeline refines it PER TENANT with a sole-member
@@ -144,6 +159,7 @@ export async function runForgetCleanup(
   args: RunForgetCleanupArgs,
 ): Promise<RunForgetCleanupResult> {
   const { db, registry, now, sendDeletionExecutedEmail, buildStorageProvider } = args;
+  const kms = args.kms ?? configuredPiiSubjectKms();
   const appTenantModel: TenantUserModel = args.tenantModel ?? "multi-user";
 
   // Step 1: Find users with expired grace period.
@@ -188,6 +204,7 @@ export async function runForgetCleanup(
       hookEntries,
       buildStorageProvider,
       appTenantModel,
+      kms,
     });
     hookCallsAttempted += userResult.hookCallsAttempted;
     errors.push(...userResult.errors);
@@ -248,8 +265,9 @@ async function processUser(args: {
   hookEntries: readonly HookEntry[];
   buildStorageProvider?: (tenantId: TenantId) => Promise<UserDataStorageProvider | undefined>;
   appTenantModel: TenantUserModel;
+  kms?: KmsAdapter;
 }): Promise<ProcessUserResult> {
-  const { db, registry, userId, hookEntries, buildStorageProvider, appTenantModel } = args;
+  const { db, registry, userId, hookEntries, buildStorageProvider, appTenantModel, kms } = args;
   const errors: ForgetCleanupError[] = [];
   let hookCallsAttempted = 0;
 
@@ -262,7 +280,9 @@ async function processUser(args: {
     id: userId,
   });
   const userEmailBeforeDelete =
-    userPreTx?.email && userPreTx.email.length > 0 ? userPreTx.email : null;
+    userPreTx?.email && userPreTx.email.length > 0
+      ? await decryptStoredPii(userPreTx.email, "user-data-rights:forget-cleanup")
+      : null;
   const userLocaleBeforeDelete = userPreTx?.locale ?? null;
 
   // Memberships fuer diesen User holen — alle Tenants in denen er Mitglied ist.
@@ -328,6 +348,34 @@ async function processUser(args: {
         }
       }
 
+      // Crypto-shredding: erase the user's subject key AFTER the hooks and
+      // BEFORE the status flip. The KMS is not a tx participant, so ordering
+      // is what makes this crash-safe: eraseKey-throw → tx rollback → user
+      // stays DeletionRequested → next run retries; flip-throw after a
+      // successful erase → retry re-runs the idempotent hooks and eraseKey
+      // (contractually a no-op on an erased/unknown subject). Erasing after
+      // the flip instead would risk a permanent silent miss: user already
+      // Deleted, no run ever picks him up again, key stays live.
+      if (kms) {
+        await kms.eraseKey(
+          { kind: "user", userId },
+          {
+            requestId: "user-data-rights:run-forget-cleanup",
+            userId,
+            eraseReason: "user-data-rights:forget",
+          },
+        );
+        // Blind-Index-Sweep (#818): bidx-Spalten des erased Subjects sofort
+        // nullen — sonst bliebe der deterministische HMAC bis zum nächsten
+        // Rebuild equality-matchbar (Linkage-Fenster). In der Sub-Tx, damit
+        // ein Rollback auch den Sweep zurücknimmt.
+        await nullBlindIndexesForSubject(
+          tx,
+          registry.features,
+          subjectIdToKey({ kind: "user", userId }),
+        );
+      }
+
       // Status-Flip in derselben Sub-Tx. Falls einer der Hooks oben
       // geworfen hat, kommen wir hier nicht an — die Tx rollback'd
       // alles, der User bleibt im DeletionRequested-Status, naechster