@cosmicdrift/kumiko-framework 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,7 @@
 # @cosmicdrift/kumiko-framework
 
+## 0.2.3
+
 ## 0.2.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "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>",
@@ -28,6 +28,7 @@
     "runtime": "runtime"
   },
   "exports": {
+    "./compliance": "./src/compliance/index.ts",
     "./engine": "./src/engine/index.ts",
     "./engine/types": "./src/engine/types/index.ts",
     "./errors": "./src/errors/index.ts",
@@ -73,7 +74,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.2.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.2.3",
     "@types/uuid": "^11.0.0",
     "bun-types": "^1.2.9",
     "drizzle-kit": "^0.31.0",

package/src/auth/__tests__/roles.test.ts

@@ -0,0 +1,24 @@
+// Snapshot-Tests fuer ROLES — faengt stille Drift ab.
+
+import { describe, expect, test } from "vitest";
+import { ROLES } from "../roles";
+
+describe("ROLES constants", () => {
+  test("Snapshot — explizit zu updaten bei Aenderungen", () => {
+    expect(ROLES).toMatchInlineSnapshot(`
+      {
+        "DataProtectionOfficer": "DataProtectionOfficer",
+        "Member": "Member",
+        "SystemAdmin": "SystemAdmin",
+        "TenantAdmin": "TenantAdmin",
+        "TenantOwner": "TenantOwner",
+      }
+    `);
+  });
+
+  test("ROLES-Werte sind identisch zu den Keys (keine Drift im Mapping)", () => {
+    for (const [key, value] of Object.entries(ROLES)) {
+      expect(value).toBe(key);
+    }
+  });
+});

package/src/auth/index.ts

@@ -0,0 +1,7 @@
+// `@cosmicdrift/kumiko-framework/auth` — Auth-Foundation (Roles, Token-
+// Helpers, Session-Types). Wird von Bundled-Features (auth-email-password,
+// tenant, user) und Datenschutz-Sprints (S1+ user-data-rights, S5 tenant-
+// lifecycle, S6 legal-hold) genutzt.
+
+export type { Role } from "./roles";
+export { ROLES } from "./roles";

package/src/auth/roles.ts

@@ -0,0 +1,42 @@
+// Zentrale Role-Konstanten der Plattform.
+//
+// Hintergrund: Bundled-Features driften zwischen "Admin" (text-content,
+// secrets, ai-foundation, file-provider-s3) und "TenantAdmin" (tenant-
+// handler, publicstatus, platform). App-Builder fallen in diese Falle.
+// Diese Datei ist die Single Source of Truth — Bundled-Features
+// migrieren schrittweise auf die ROLES-Constants in den Sprint-
+// Touchpoints, an denen sie ohnehin angefasst werden.
+//
+// Canonical-Names:
+//   TenantOwner            — Volle Tenant-Hoheit, einzige Rolle die
+//                            Tenant-Destroy triggern darf.
+//   TenantAdmin            — Tenant-Konfiguration + User-Management.
+//                            Bestehender String "Admin" wird hierauf
+//                            migriert.
+//   DataProtectionOfficer  — DPO; setzt Legal-Holds, sieht Authority-
+//                            Audit-Stream auch im silentMode (Sprint 6).
+//   SystemAdmin            — Plattform-Operator (NICHT Tenant-scoped).
+//                            Authority-Export, KMS-Recovery, Cross-
+//                            Tenant-Setup. Matched den bestehenden
+//                            "SystemAdmin"-String in text-content,
+//                            secrets, auth-email-password, etc.
+//   Member                 — Standard-Mitglied eines Tenants ohne
+//                            Admin-Rechte.
+
+/**
+ * Plattform-weit standardisierte Role-Namen. Alle Datenschutz-Sprints
+ * (1+) nutzen ausschliesslich diese Constants statt String-Literale.
+ */
+export const ROLES = {
+  TenantOwner: "TenantOwner",
+  TenantAdmin: "TenantAdmin",
+  DataProtectionOfficer: "DataProtectionOfficer",
+  SystemAdmin: "SystemAdmin",
+  Member: "Member",
+} as const;
+
+/**
+ * Type-Union aller bekannten Role-Namen (Compile-Time-Check fuer
+ * Handler-Access-Rules + Ownership-Maps).
+ */
+export type Role = (typeof ROLES)[keyof typeof ROLES];

package/src/compliance/__tests__/duration-spec.test.ts

@@ -0,0 +1,72 @@
+// Unit-Tests fuer DurationSpec-Helpers (S2.U5a.fix2).
+//
+// Pinst beide Discriminated-Union-Branches (`{days}` + `{hours}`) plus
+// Edge-Cases die in den Integration-Tests nicht auftauchen (0-Werte,
+// Singular/Plural). Der Bug aus dem U5a-Review (`{hours: 6}` fiel auf
+// 30d-Default) wird hier zentral verhindert.
+
+import { ensureTemporalPolyfill, getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { beforeAll, describe, expect, test } from "vitest";
+import { addDurationSpec, describeDurationSpec, durationSpecToMs } from "../duration-spec";
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+});
+
+describe("durationSpecToMs", () => {
+  test("days → days * 86_400_000", () => {
+    expect(durationSpecToMs({ days: 30 })).toBe(30 * 24 * 60 * 60 * 1000);
+    expect(durationSpecToMs({ days: 1 })).toBe(24 * 60 * 60 * 1000);
+  });
+
+  test("hours → hours * 3_600_000", () => {
+    expect(durationSpecToMs({ hours: 6 })).toBe(6 * 60 * 60 * 1000);
+    expect(durationSpecToMs({ hours: 72 })).toBe(72 * 60 * 60 * 1000);
+  });
+
+  test("0-Werte ergeben 0", () => {
+    expect(durationSpecToMs({ days: 0 })).toBe(0);
+    expect(durationSpecToMs({ hours: 0 })).toBe(0);
+  });
+});
+
+describe("addDurationSpec", () => {
+  test("days addiert exakt zu Instant.epochMilliseconds", () => {
+    const T = getTemporal();
+    const t0 = T.Instant.fromEpochMilliseconds(1_700_000_000_000);
+    const t1 = addDurationSpec(t0, { days: 30 });
+    expect(t1.epochMilliseconds - t0.epochMilliseconds).toBe(30 * 24 * 60 * 60 * 1000);
+  });
+
+  test("hours addiert exakt zu Instant.epochMilliseconds", () => {
+    const T = getTemporal();
+    const t0 = T.Instant.fromEpochMilliseconds(1_700_000_000_000);
+    const t1 = addDurationSpec(t0, { hours: 6 });
+    expect(t1.epochMilliseconds - t0.epochMilliseconds).toBe(6 * 60 * 60 * 1000);
+  });
+
+  // Regression-Guard fuer den U5a-Bug: vorher fiel `{hours: 6}` auf
+  // `30 * 86_400_000`-Default zurueck. Wenn jemand den Branch wieder
+  // verliert, faellt dieser Test sofort um.
+  test("hours-Branch ist NICHT auf days-Default mappable (U5a-Regression)", () => {
+    const T = getTemporal();
+    const t0 = T.Instant.fromEpochMilliseconds(1_700_000_000_000);
+    const tHours = addDurationSpec(t0, { hours: 6 });
+    const tDaysDefault = addDurationSpec(t0, { days: 30 });
+    expect(tHours.epochMilliseconds).not.toBe(tDaysDefault.epochMilliseconds);
+  });
+});
+
+describe("describeDurationSpec", () => {
+  test("days mit Pluralisierung", () => {
+    expect(describeDurationSpec({ days: 30 })).toBe("30 days");
+    expect(describeDurationSpec({ days: 1 })).toBe("1 day");
+    expect(describeDurationSpec({ days: 0 })).toBe("0 days");
+  });
+
+  test("hours mit Pluralisierung", () => {
+    expect(describeDurationSpec({ hours: 72 })).toBe("72 hours");
+    expect(describeDurationSpec({ hours: 1 })).toBe("1 hour");
+    expect(describeDurationSpec({ hours: 0 })).toBe("0 hours");
+  });
+});

package/src/compliance/__tests__/profiles.test.ts

@@ -0,0 +1,308 @@
+// Tests fuer Compliance-Profile-Constants + extends-Resolver.
+//
+// Edge-Cases (advisor-pinned 2026-05-06):
+//   1. Default-Fallback bei selection=undefined → minimal-no-region + warning
+//   2. extends-Chain max 1 Level (Cycle-/Tiefe-Schutz)
+//   3. Deep-merge-Semantik beim Override (rekursiv, Top-Level-Replace nicht)
+//   4. Override darf einzelne Felder gezielt setzen ohne Required-Drops
+
+import { describe, expect, test } from "vitest";
+import { complianceProfileOverrideSchema } from "../override-schema";
+import {
+  COMPLIANCE_PROFILES,
+  OVERRIDABLE_PROFILE_KEYS,
+  resolveComplianceProfile,
+  SELECTABLE_PROFILE_KEYS,
+} from "../profiles";
+
+// Identifikations-Keys die ein Override NICHT modifizieren darf — sie
+// definieren die Profile-Identität. Werden vom Drift-Test ausgeschlossen.
+const IDENTIFICATION_KEYS = new Set(["key", "region", "label", "extends"]);
+
+describe("COMPLIANCE_PROFILES — Pre-baked", () => {
+  test("eu-dsgvo hat alle Required-Felder", () => {
+    const p = COMPLIANCE_PROFILES["eu-dsgvo"];
+    expect(p.key).toBe("eu-dsgvo");
+    expect(p.region).toBe("EU");
+    expect(p.userRights.gracePeriod).toEqual({ days: 30 });
+    expect(p.notifications.languages).toContain("de");
+    expect(p.breach.authorityContact).toBe("BlnBDI Berlin");
+    expect(p.tenantDestroyGracePeriod).toEqual({ days: 30 });
+  });
+
+  test("swiss-dsg extends eu-dsgvo — übernimmt Base-Felder", () => {
+    const p = COMPLIANCE_PROFILES["swiss-dsg"];
+    expect(p.key).toBe("swiss-dsg");
+    expect(p.region).toBe("CH");
+    // Override: andere Sprachen + andere Aufsicht
+    expect(p.notifications.languages).toEqual(["de", "fr", "it", "en"]);
+    expect(p.breach.authorityContact).toBe("EDÖB Bern");
+    // Geerbt von eu-dsgvo
+    expect(p.userRights.gracePeriod).toEqual({ days: 30 });
+    expect(p.userRights.restrictionAllowed).toBe(true);
+    expect(p.tenantDestroyGracePeriod).toEqual({ days: 30 });
+  });
+
+  test("de-hr-dsgvo-hgb extends eu-dsgvo — HR-Override greift, Base bleibt", () => {
+    const p = COMPLIANCE_PROFILES["de-hr-dsgvo-hgb"];
+    expect(p.region).toBe("DE");
+    expect(p.userRights.employeeAccessRight).toBe(true);
+    expect(p.breach.worksCouncilNotificationRequired).toBe(true);
+    expect(p.subProcessor.worksCouncilApprovalRequired).toBe(true);
+    expect(p.auditLog.retention).toEqual({ years: 10 });
+    expect(p.tenantDestroyGracePeriod).toEqual({ days: 60 });
+    // Geerbt: portabilityFormat aus eu-dsgvo bleibt
+    expect(p.userRights.portabilityFormat).toEqual(["json"]);
+  });
+
+  test("minimal-no-region ist eigenständig (kein extends)", () => {
+    const p = COMPLIANCE_PROFILES["minimal-no-region"];
+    expect(p.region).toBe("—");
+    expect(p.notifications.mandatoryBreachNotification).toBe(false);
+    expect(p.breach.authorityNotificationDeadline).toBe("manual");
+  });
+});
+
+describe("SELECTABLE_PROFILE_KEYS", () => {
+  test('enthält 3 Profile, ohne "minimal-no-region" (kein Production-Default)', () => {
+    expect(SELECTABLE_PROFILE_KEYS).toEqual(["eu-dsgvo", "swiss-dsg", "de-hr-dsgvo-hgb"]);
+    expect(SELECTABLE_PROFILE_KEYS).not.toContain("minimal-no-region");
+  });
+});
+
+describe("OVERRIDABLE_PROFILE_KEYS — Drift-Guard (S1.8 N2)", () => {
+  // Wenn ein neues Top-Level-Property zu ComplianceProfile kommt
+  // (oder eines wegfaellt), muss OVERRIDABLE_PROFILE_KEYS synchron
+  // gehalten werden — sonst lehnt set-profile valide Overrides ab
+  // ODER akzeptiert ungueltige. Dieser Test detektiert den Drift in
+  // beide Richtungen anhand des voll aufgeloesten eu-dsgvo-Profile.
+  test("Override-Whitelist matched die uebrigen Top-Level-Keys von eu-dsgvo (minus Identifikations-Felder)", () => {
+    const allTopLevelKeys = new Set(Object.keys(COMPLIANCE_PROFILES["eu-dsgvo"]));
+    for (const idKey of IDENTIFICATION_KEYS) {
+      allTopLevelKeys.delete(idKey);
+    }
+    const expected = [...allTopLevelKeys].sort();
+    const actual = [...OVERRIDABLE_PROFILE_KEYS].sort();
+    expect(actual).toEqual(expected);
+  });
+
+  test("Identifikations-Keys (key, region, label, extends) sind NICHT in OVERRIDABLE_PROFILE_KEYS", () => {
+    for (const idKey of IDENTIFICATION_KEYS) {
+      expect(OVERRIDABLE_PROFILE_KEYS.has(idKey)).toBe(false);
+    }
+  });
+});
+
+describe("complianceProfileOverrideSchema — Schema↔Profile-Konsistenz (S1.10 M2)", () => {
+  // Wenn Profile-Type erweitert wird (neues Sub-Property in userRights /
+  // breach / auditLog / etc.) ohne dass override-schema.ts mitgepflegt
+  // wird, fail dieser Test. Prinzip: ein voll aufgelöstes Profile ist
+  // ein triviales valides Override-Object — wenn Schema das ablehnt, ist
+  // entweder Schema oder Profile out of sync.
+  test("Schema akzeptiert ein vollständig aufgelöstes Profile als Override (Drift-Guard)", () => {
+    // Identifikations-Felder rausnehmen weil die nicht override-bar sind.
+    const fullProfile = COMPLIANCE_PROFILES["eu-dsgvo"];
+    const {
+      key: _key,
+      region: _region,
+      label: _label,
+      extends: _extends,
+      ...overridable
+    } = fullProfile;
+
+    const result = complianceProfileOverrideSchema.safeParse(overridable);
+    if (!result.success) {
+      throw new Error(
+        `Schema↔Profile-Drift: vollständig aufgelöstes eu-dsgvo wird vom Override-Schema abgelehnt. ` +
+          `Issue at "${result.error.issues[0]?.path.join(".")}": ${result.error.issues[0]?.message}. ` +
+          "Entweder ComplianceProfile-Type erweitert ohne Schema-Update, oder Schema strikter als Profile-Type.",
+      );
+    }
+    expect(result.success).toBe(true);
+  });
+
+  test("Schema akzeptiert auch swiss-dsg + de-hr-dsgvo-hgb (extends-Profile mit Override-Feldern)", () => {
+    for (const key of ["swiss-dsg", "de-hr-dsgvo-hgb"] as const) {
+      const fullProfile = COMPLIANCE_PROFILES[key];
+      const {
+        key: _key,
+        region: _region,
+        label: _label,
+        extends: _extends,
+        ...overridable
+      } = fullProfile;
+      const result = complianceProfileOverrideSchema.safeParse(overridable);
+      expect(result.success, `Schema lehnt voll aufgelöstes ${key} ab`).toBe(true);
+    }
+  });
+});
+
+describe("resolveComplianceProfile — Default-Fallback", () => {
+  test("selection=undefined → minimal-no-region + warning=no-profile-selected", () => {
+    const result = resolveComplianceProfile({});
+    expect(result.profile.key).toBe("minimal-no-region");
+    expect(result.warning).toBe("no-profile-selected");
+  });
+
+  test("selection=minimal-no-region (DB-Edge-Case) → kein warning, fallback aktiv", () => {
+    // Sprint 1.7 X1: minimal-no-region ist ueber set-profile nicht mehr
+    // setzbar. Wer den State trotzdem in der DB hat (Migration, Direct-
+    // Insert) bekommt das minimal-Profile zurueck — der needs-profile-
+    // Banner-Endpoint markiert ihn separat als "needsSelection=true".
+    // Resolver selber zieht keine warning, weil "explicit selection".
+    const result = resolveComplianceProfile({ selection: "minimal-no-region" });
+    expect(result.profile.key).toBe("minimal-no-region");
+    expect(result.warning).toBeUndefined();
+  });
+
+  test("selection=eu-dsgvo + kein override → keine warning", () => {
+    const result = resolveComplianceProfile({ selection: "eu-dsgvo" });
+    expect(result.profile.key).toBe("eu-dsgvo");
+    expect(result.warning).toBeUndefined();
+  });
+});
+
+describe("resolveComplianceProfile — Override deep-merge", () => {
+  test("Override gracePeriod.days überschreibt rekursiv, andere userRights bleiben", () => {
+    const result = resolveComplianceProfile({
+      selection: "eu-dsgvo",
+      override: {
+        userRights: { gracePeriod: { days: 60 } },
+      },
+    });
+    expect(result.profile.userRights.gracePeriod).toEqual({ days: 60 });
+    // Andere userRights-Felder unverändert
+    expect(result.profile.userRights.restrictionAllowed).toBe(true);
+    expect(result.profile.userRights.objectionAllowed).toBe(true);
+    expect(result.profile.userRights.portabilityFormat).toEqual(["json"]);
+    expect(result.profile.userRights.auskunftFrist).toEqual({ days: 30 });
+  });
+
+  test("Override breach.authorityContact ändert nur diesen einen Pfad", () => {
+    const result = resolveComplianceProfile({
+      selection: "eu-dsgvo",
+      override: {
+        breach: { authorityContact: "Hamburgischer DSB" },
+      },
+    });
+    expect(result.profile.breach.authorityContact).toBe("Hamburgischer DSB");
+    // Rest des breach-Objects unverändert
+    expect(result.profile.breach.authorityNotificationDeadline).toEqual({ hours: 72 });
+    expect(result.profile.breach.userNotificationRequired).toBe("if-high-risk");
+  });
+
+  test("Override mehrerer Top-Level-Pfade gleichzeitig", () => {
+    const result = resolveComplianceProfile({
+      selection: "swiss-dsg",
+      override: {
+        userRights: { gracePeriod: { days: 45 } },
+        tenantDestroyGracePeriod: { days: 90 },
+      },
+    });
+    expect(result.profile.userRights.gracePeriod).toEqual({ days: 45 });
+    expect(result.profile.tenantDestroyGracePeriod).toEqual({ days: 90 });
+    // swiss-dsg extends eu-dsgvo war drin
+    expect(result.profile.region).toBe("CH");
+    expect(result.profile.breach.authorityContact).toBe("EDÖB Bern");
+  });
+
+  test("Atomic path: retention {months} → {years} ersetzt komplett (kein object-merge)", () => {
+    // Bug-Regression: deepMerge auf Diskriminierten-Union-Objects
+    // wuerde sonst { months: 24, years: 10 } produzieren — semantisch
+    // Nonsense, retention ist EINE Wahl.
+    const result = resolveComplianceProfile({
+      selection: "eu-dsgvo",
+      override: {
+        auditLog: { retention: { years: 10 } },
+      },
+    });
+    expect(result.profile.auditLog.retention).toEqual({ years: 10 });
+    // reportFrequency darf NICHT mit ersetzt werden — auditLog ist
+    // nicht atomic, nur retention darunter.
+    expect(result.profile.auditLog.reportFrequency).toBe("quarterly");
+  });
+
+  test("Atomic path: gracePeriod {days} → {hours} ersetzt komplett", () => {
+    const result = resolveComplianceProfile({
+      selection: "eu-dsgvo",
+      override: {
+        userRights: { gracePeriod: { hours: 24 } },
+      },
+    });
+    expect(result.profile.userRights.gracePeriod).toEqual({ hours: 24 });
+    expect(result.profile.userRights.gracePeriod).not.toHaveProperty("days");
+  });
+
+  test("Array-Property im Override ersetzt komplett (Top-Level-Replace, kein concat)", () => {
+    const result = resolveComplianceProfile({
+      selection: "eu-dsgvo",
+      override: {
+        notifications: { languages: ["en"] },
+      },
+    });
+    // Replace, nicht append: ["de", "en"] wird zu ["en"]
+    expect(result.profile.notifications.languages).toEqual(["en"]);
+    // Andere notifications-Felder bleiben
+    expect(result.profile.notifications.mandatoryBreachNotification).toBe(true);
+  });
+});
+
+describe("Profile-Definition-Snapshots — fängt Drift ab", () => {
+  test("eu-dsgvo voll-resolved", () => {
+    expect(COMPLIANCE_PROFILES["eu-dsgvo"]).toMatchInlineSnapshot(`
+      {
+        "auditLog": {
+          "reportFrequency": "quarterly",
+          "retention": {
+            "months": 24,
+          },
+        },
+        "breach": {
+          "authorityContact": "BlnBDI Berlin",
+          "authorityNotificationDeadline": {
+            "hours": 72,
+          },
+          "userNotificationRequired": "if-high-risk",
+        },
+        "forgetDiscovery": {
+          "enabled": false,
+        },
+        "key": "eu-dsgvo",
+        "label": "EU — DSGVO Standard",
+        "notifications": {
+          "languages": [
+            "de",
+            "en",
+          ],
+          "mandatoryBreachNotification": true,
+        },
+        "region": "EU",
+        "subProcessor": {
+          "changeNotificationLeadDays": 30,
+          "consentRequired": false,
+        },
+        "tenantDestroyGracePeriod": {
+          "days": 30,
+        },
+        "userRights": {
+          "auskunftFrist": {
+            "days": 30,
+          },
+          "exportDownloadTtl": {
+            "days": 7,
+          },
+          "exportStaleTimeoutMinutes": 30,
+          "exportStorageCleanupGraceHours": 24,
+          "gracePeriod": {
+            "days": 30,
+          },
+          "objectionAllowed": true,
+          "portabilityFormat": [
+            "json",
+          ],
+          "restrictionAllowed": true,
+        },
+      }
+    `);
+  });
+});

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

@@ -0,0 +1,139 @@
+// Snapshot-Tests fuer KUMIKO_SUB_PROCESSORS. Fangen still-Drift ab —
+// jede Aenderung an der Liste muss bewusst durch ein Snapshot-Update
+// gehen, damit niemand versehentlich einen Sub-Processor entfernt
+// oder hinzufuegt ohne dass die DPA/Tenant-Notification-Pipeline das
+// mitbekommt.
+
+import { describe, expect, test } from "vitest";
+import {
+  getActiveSubProcessors,
+  getPlannedSubProcessors,
+  KUMIKO_SUB_PROCESSORS,
+} from "../sub-processors";
+
+describe("KUMIKO_SUB_PROCESSORS", () => {
+  test("Liste ist nicht leer (Plattform hat mindestens Hetzner+Cloudflare)", () => {
+    expect(KUMIKO_SUB_PROCESSORS.length).toBeGreaterThan(0);
+  });
+
+  test("Alle Eintraege haben Pflicht-Felder (name, purpose, region, dpa, addedAt, appliesTo)", () => {
+    for (const sp of KUMIKO_SUB_PROCESSORS) {
+      expect(sp.name).toBeTruthy();
+      expect(sp.purpose).toBeTruthy();
+      expect(sp.region).toBeTruthy();
+      expect(sp.dpa).toMatch(/^https?:\/\//);
+      expect(sp.addedAt).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+      expect(sp.appliesTo.length).toBeGreaterThan(0);
+    }
+  });
+
+  test("US-Sub-Processors haben sccRequired: true (DSGVO Art. 44+ Drittland)", () => {
+    const usProcessors = KUMIKO_SUB_PROCESSORS.filter(
+      (sp) => sp.region.includes("US") && !sp.region.startsWith("EU"),
+    );
+    for (const sp of usProcessors) {
+      expect(
+        sp.sccRequired,
+        `Sub-Processor "${sp.name}" with US-region should have sccRequired: true`,
+      ).toBe(true);
+    }
+  });
+
+  test("Snapshot — explizit zu updaten bei jeder Liste-Aenderung", () => {
+    const summary = KUMIKO_SUB_PROCESSORS.map((sp) => ({
+      name: sp.name,
+      region: sp.region,
+      status: sp.status ?? "active",
+      appliesTo: sp.appliesTo,
+      sccRequired: sp.sccRequired ?? false,
+      optInOnly: sp.optInOnly ?? false,
+    }));
+    expect(summary).toMatchInlineSnapshot(`
+      [
+        {
+          "appliesTo": [
+            "all-tiers",
+          ],
+          "name": "Hetzner Online GmbH",
+          "optInOnly": false,
+          "region": "EU (Germany)",
+          "sccRequired": false,
+          "status": "active",
+        },
+        {
+          "appliesTo": [
+            "all-tiers",
+          ],
+          "name": "Cloudflare, Inc.",
+          "optInOnly": false,
+          "region": "Global (US-headquartered)",
+          "sccRequired": true,
+          "status": "active",
+        },
+        {
+          "appliesTo": [
+            "standard",
+            "business",
+            "enterprise",
+          ],
+          "name": "Sendinblue SAS (Brevo)",
+          "optInOnly": false,
+          "region": "EU (France)",
+          "sccRequired": false,
+          "status": "active",
+        },
+        {
+          "appliesTo": [
+            "all-tiers",
+          ],
+          "name": "Heinlein Hosting (Mailbox.org)",
+          "optInOnly": false,
+          "region": "EU (Germany)",
+          "sccRequired": false,
+          "status": "active",
+        },
+        {
+          "appliesTo": [
+            "business",
+            "enterprise",
+          ],
+          "name": "Anthropic PBC",
+          "optInOnly": true,
+          "region": "US",
+          "sccRequired": true,
+          "status": "planned",
+        },
+        {
+          "appliesTo": [
+            "all-tiers",
+          ],
+          "name": "Stripe, Inc.",
+          "optInOnly": false,
+          "region": "Global (US-headquartered)",
+          "sccRequired": true,
+          "status": "planned",
+        },
+      ]
+    `);
+  });
+});
+
+describe("getActiveSubProcessors / getPlannedSubProcessors", () => {
+  test("active + planned partitionieren die Gesamt-Liste vollstaendig", () => {
+    const active = getActiveSubProcessors();
+    const planned = getPlannedSubProcessors();
+    expect(active.length + planned.length).toBe(KUMIKO_SUB_PROCESSORS.length);
+  });
+
+  test("kein Sub-Processor in active hat status=planned", () => {
+    for (const sp of getActiveSubProcessors()) {
+      expect(sp.status).not.toBe("planned");
+    }
+  });
+
+  test("alle planned-Eintraege haben status=planned", () => {
+    for (const sp of getPlannedSubProcessors()) {
+      expect(sp.status).toBe("planned");
+    }
+  });
+});

package/src/compliance/duration-spec.ts

@@ -0,0 +1,44 @@
+// DurationSpec ↔ SQL-Interval ↔ Temporal.Duration converter.
+//
+// Hintergrund: ComplianceProfile.userRights.gracePeriod ist
+// `{ days: number } | { hours: number }` (Discriminated Union). Caller
+// die das in eine Postgres-`interval`-SQL einsetzen brauchen einen
+// einzigen vertrauenswuerdigen Punkt, sonst springt ein
+// `{ hours: 6 }`-Override stillschweigend auf einen days-Default.
+//
+// Single source of truth: hier. Andere Spec-Forms (months/years) im
+// retention-Pfad gehen ueber den breiteren `keep-for`-Parser, sind hier
+// bewusst nicht abgedeckt — das engt den Type ein und macht die SQL-
+// Renderung total.
+
+import { getTemporal } from "../time";
+import type { DurationSpec } from "./profiles";
+
+type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
+
+// Spec in Millisekunden. Source of truth fuer alle Konvertierungen
+// (Instant-add, optional fuer JS-Datumsrechnung).
+export function durationSpecToMs(spec: DurationSpec): number {
+  if ("days" in spec) return spec.days * 24 * 60 * 60 * 1000;
+  return spec.hours * 60 * 60 * 1000;
+}
+
+// Frist berechnen ohne DB-now() — der App-Server-Clock ist
+// authoritative. Fuer Forget-Grace, Token-TTLs und Frist-Setzungen
+// where eine Toleranz von wenigen ms zwischen App und DB irrelevant
+// ist (Grace-Periods >= 6h, Tokens >= Minuten).
+//
+// Schreibt direkt in `instant()`-customType-Spalten — kein interval-
+// SQL-Fragment, kein Codec-Bypass.
+export function addDurationSpec(now: Instant, spec: DurationSpec): Instant {
+  return getTemporal().Instant.fromEpochMilliseconds(
+    now.epochMilliseconds + durationSpecToMs(spec),
+  );
+}
+
+// Lesbare Beschreibung fuer Logs / Error-Messages. Nicht i18n —
+// English-only-Operator-Output.
+export function describeDurationSpec(spec: DurationSpec): string {
+  if ("days" in spec) return `${spec.days} day${spec.days === 1 ? "" : "s"}`;
+  return `${spec.hours} hour${spec.hours === 1 ? "" : "s"}`;
+}