@cosmicdrift/kumiko-framework 0.2.2 → 0.3.0

package/src/compliance/profiles.ts

@@ -0,0 +1,427 @@
+// Compliance-Profiles — DSGVO + sektorspezifische Regelwerke.
+//
+// Tenant-Admin waehlt ein Profile beim Onboarding (Pflicht). Profile
+// buendelt User-Rights (Forget-Grace, Restriction, Auskunftsfrist),
+// Notification-Sprache, Breach-Disclosure, Audit-Log-Retention,
+// Sub-Processor-Anforderungen und Tenant-Destroy-Grace.
+//
+// MVP-Set: 3 Profile + 1 Default-Fallback. Erweiterung via `extends`
+// trivial — neue Laender (uk-gdpr, ca-pipeda, us-ccpa, hipaa-healthcare)
+// kommen on-demand wenn Customer fragt.
+//
+// Edge-Case-Decisions (advisor-pinned 2026-05-06):
+//
+//   1. Default-Fallback: `resolveComplianceProfile(undefined)` returnt
+//      `minimal-no-region` mit `warning: "no-profile-selected"`. Caller
+//      sieht das und kann Onboarding-Banner triggern. Nie still
+//      resolven.
+//
+//   2. extends-Chain-Tiefe: nur 1-Level. de-hr-dsgvo-hgb extends
+//      eu-dsgvo, aber eu-dsgvo darf NICHT selbst extends haben. Boot-
+//      Validator (Sprint 1.3) prueft.
+//
+//   3. Deep-merge-Semantik vom Override: rekursiv. Override
+//      `{ userRights: { gracePeriod: { days: 60 } } }` auf eu-dsgvo
+//      laesst andere userRights-Felder unveraendert. Top-Level-Replace
+//      gibt es NICHT — Override muss strukturell exakt das Pfad-Tree
+//      treffen.
+//
+//   4. Required-Field-Override: Override-Type ist `DeepPartial<...>`.
+//      TypeScript verhindert null-Drops zur Compile-Time. Runtime-Cast
+//      durch Tenant-Admin-Override-Endpoint laeuft durch Zod-Schema
+//      mit allen-Properties-optional (kein nullable).
+//
+// Siehe docs/plans/datenschutz/compliance-profiles.md.
+
+import type { BundleTier } from "./sub-processors";
+
+// --- Profile-Schema ---
+
+export type ComplianceProfileKey =
+  | "eu-dsgvo"
+  | "swiss-dsg"
+  | "de-hr-dsgvo-hgb"
+  | "minimal-no-region";
+
+export type DurationSpec = { readonly days: number } | { readonly hours: number };
+
+export type AuthorityNotificationDeadline =
+  | DurationSpec
+  | "as-soon-as-feasible"
+  | "in-most-expedient-time"
+  | "manual";
+
+export type UserNotificationRequiredPolicy =
+  | "if-high-risk"
+  | "if-real-risk-of-significant-harm"
+  | "if-serious-risk-of-injury"
+  | "always-if-encrypted-data-or-pii"
+  | "always-without-undue-delay"
+  | "manual";
+
+export interface ComplianceProfile {
+  readonly key: ComplianceProfileKey;
+  readonly region: string;
+  readonly label: string;
+  readonly extends?: ComplianceProfileKey;
+
+  readonly userRights: {
+    readonly gracePeriod: DurationSpec;
+    readonly restrictionAllowed: boolean;
+    readonly objectionAllowed: boolean;
+    readonly portabilityFormat: readonly string[];
+    readonly auskunftFrist: DurationSpec;
+    readonly employeeAccessRight?: boolean;
+    readonly explicitConsentForAutomatedDecision?: boolean;
+    readonly doNotSellRequired?: boolean;
+    /**
+     * DSGVO Art. 15 + 20 Async-Export — Pipeline-Konfiguration. Spec:
+     * docs/plans/architecture/user-data-rights.md "Async Export-Pipeline".
+     */
+    readonly exportDownloadTtl: DurationSpec;
+    readonly exportStaleTimeoutMinutes: number;
+    readonly exportStorageCleanupGraceHours: number;
+  };
+
+  readonly notifications: {
+    readonly languages: readonly string[];
+    readonly languageDefault?: string;
+    readonly mandatoryBreachNotification: boolean;
+  };
+
+  readonly breach: {
+    readonly authorityNotificationDeadline: AuthorityNotificationDeadline;
+    readonly authorityContact: string;
+    readonly userNotificationRequired: UserNotificationRequiredPolicy;
+    readonly worksCouncilNotificationRequired?: boolean;
+    readonly mandatoryRegisterOfBreaches?: boolean;
+  };
+
+  readonly auditLog: {
+    readonly retention: DurationSpec | { readonly months: number } | { readonly years: number };
+    readonly reportFrequency: "quarterly" | "yearly" | "annual-required" | "manual";
+  };
+
+  readonly subProcessor: {
+    readonly consentRequired: boolean;
+    readonly changeNotificationLeadDays: number;
+    readonly mandatoryBaaWithSubProcessors?: boolean;
+    readonly worksCouncilApprovalRequired?: boolean;
+    readonly tierFilter?: readonly BundleTier[];
+  };
+
+  readonly tenantDestroyGracePeriod: DurationSpec;
+
+  readonly forgetDiscovery?: {
+    readonly enabled: boolean;
+    readonly mode?: "manual-redact" | "auto-redact-strict";
+  };
+}
+
+// --- Profile-Definitions (raw, before extends-Resolution) ---
+
+const RAW_PROFILES: Readonly<Record<ComplianceProfileKey, ComplianceProfileRaw>> = {
+  "eu-dsgvo": {
+    key: "eu-dsgvo",
+    region: "EU",
+    label: "EU — DSGVO Standard",
+    userRights: {
+      gracePeriod: { days: 30 },
+      restrictionAllowed: true,
+      objectionAllowed: true,
+      portabilityFormat: ["json"],
+      auskunftFrist: { days: 30 },
+      exportDownloadTtl: { days: 7 },
+      exportStaleTimeoutMinutes: 30,
+      exportStorageCleanupGraceHours: 24,
+    },
+    notifications: {
+      languages: ["de", "en"],
+      mandatoryBreachNotification: true,
+    },
+    breach: {
+      authorityNotificationDeadline: { hours: 72 },
+      authorityContact: "BlnBDI Berlin",
+      userNotificationRequired: "if-high-risk",
+    },
+    auditLog: {
+      retention: { months: 24 },
+      reportFrequency: "quarterly",
+    },
+    subProcessor: {
+      consentRequired: false,
+      changeNotificationLeadDays: 30,
+    },
+    tenantDestroyGracePeriod: { days: 30 },
+    forgetDiscovery: { enabled: false },
+  },
+
+  "swiss-dsg": {
+    key: "swiss-dsg",
+    region: "CH",
+    label: "Schweiz — Bundesgesetz über den Datenschutz (rev. 2023)",
+    extends: "eu-dsgvo",
+    notifications: {
+      languages: ["de", "fr", "it", "en"],
+      mandatoryBreachNotification: true,
+    },
+    breach: {
+      authorityNotificationDeadline: { hours: 72 },
+      authorityContact: "EDÖB Bern",
+      userNotificationRequired: "if-high-risk",
+    },
+  },
+
+  "de-hr-dsgvo-hgb": {
+    key: "de-hr-dsgvo-hgb",
+    region: "DE",
+    label: "Deutschland HR — DSGVO + HGB + Personalakten",
+    extends: "eu-dsgvo",
+    userRights: {
+      gracePeriod: { days: 30 },
+      restrictionAllowed: true,
+      objectionAllowed: true,
+      portabilityFormat: ["json"],
+      auskunftFrist: { days: 30 },
+      employeeAccessRight: true,
+      exportDownloadTtl: { days: 7 },
+      exportStaleTimeoutMinutes: 30,
+      exportStorageCleanupGraceHours: 24,
+    },
+    notifications: {
+      languages: ["de"],
+      mandatoryBreachNotification: true,
+    },
+    breach: {
+      authorityNotificationDeadline: { hours: 72 },
+      authorityContact: "Landes-Datenschutzbehörde",
+      userNotificationRequired: "if-high-risk",
+      worksCouncilNotificationRequired: true,
+    },
+    auditLog: {
+      retention: { years: 10 },
+      reportFrequency: "yearly",
+    },
+    subProcessor: {
+      consentRequired: false,
+      changeNotificationLeadDays: 30,
+      worksCouncilApprovalRequired: true,
+    },
+    tenantDestroyGracePeriod: { days: 60 },
+  },
+
+  "minimal-no-region": {
+    key: "minimal-no-region",
+    region: "—",
+    label: "Minimal — kein Compliance-Profile (NICHT für Production)",
+    userRights: {
+      gracePeriod: { days: 30 },
+      restrictionAllowed: false,
+      objectionAllowed: false,
+      portabilityFormat: ["json"],
+      auskunftFrist: { days: 30 },
+      exportDownloadTtl: { days: 7 },
+      exportStaleTimeoutMinutes: 30,
+      exportStorageCleanupGraceHours: 24,
+    },
+    notifications: {
+      languages: ["en"],
+      mandatoryBreachNotification: false,
+    },
+    breach: {
+      authorityNotificationDeadline: "manual",
+      authorityContact: "",
+      userNotificationRequired: "manual",
+    },
+    auditLog: {
+      retention: { months: 3 },
+      reportFrequency: "manual",
+    },
+    subProcessor: {
+      consentRequired: false,
+      changeNotificationLeadDays: 30,
+    },
+    tenantDestroyGracePeriod: { days: 30 },
+  },
+} satisfies Readonly<Record<ComplianceProfileKey, ComplianceProfileRaw>>;
+
+// Raw-Profile (vor extends-Resolution) — `extends`-Profile dürfen
+// Required-Felder weglassen, sie kommen vom Base-Profile dazu.
+type ComplianceProfileRaw = Partial<Omit<ComplianceProfile, "key" | "region" | "label">> & {
+  readonly key: ComplianceProfileKey;
+  readonly region: string;
+  readonly label: string;
+  readonly extends?: ComplianceProfileKey;
+};
+
+// --- Tenant-Auswählbare Liste (ohne minimal-no-region) ---
+
+/**
+ * Profile-Schluessel die der Tenant-Admin im Onboarding waehlen darf.
+ * `minimal-no-region` ist bewusst NICHT in der Liste — es ist der
+ * Default-Fallback fuer "noch keine Wahl getroffen", mit sichtbarer
+ * Warning. Production-Tenants sollen ein echtes Profile waehlen.
+ */
+export const SELECTABLE_PROFILE_KEYS = [
+  "eu-dsgvo",
+  "swiss-dsg",
+  "de-hr-dsgvo-hgb",
+] as const satisfies readonly ComplianceProfileKey[];
+
+/**
+ * Top-Level-Properties des `ComplianceProfile`-Type, die ein Tenant-
+ * Override modifizieren darf. Identifikations-Felder (key, region,
+ * label, extends) sind ausgeschlossen — wer die overriden wuerde,
+ * würde die Profile-Identität zerstoeren.
+ *
+ * Single source of truth fuer:
+ *   - set-profile-Handler-Whitelist (Tippfehler-Reject)
+ *   - Snapshot-Test gegen Profile-Top-Level (Drift-Guard)
+ *
+ * Wenn ein neues Top-Level-Property zu `ComplianceProfile` kommt
+ * (z.B. `dataSubjectRights` oder `crossBorderTransferRules`), MUSS es
+ * hier ergaenzt werden — sonst lehnt set-profile valide Overrides ab.
+ * Der Snapshot-Test in profiles.test.ts faengt Drift in beide
+ * Richtungen.
+ */
+export const OVERRIDABLE_PROFILE_KEYS: ReadonlySet<string> = new Set([
+  "userRights",
+  "notifications",
+  "breach",
+  "auditLog",
+  "subProcessor",
+  "tenantDestroyGracePeriod",
+  "forgetDiscovery",
+]);
+
+// --- Extends-Resolver (deep-merge) ---
+
+type DeepReadonly<T> = T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> } : T;
+
+export type ComplianceProfileOverride = DeepReadonly<DeepPartial<ComplianceProfile>>;
+
+type DeepPartial<T> = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T;
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// Pfade die als ganzes Atom ersetzt werden (NICHT rekursiv gemergt).
+// Notwendig fuer Diskriminierte-Union-Types wo das Patch ein Schwester-
+// Property statt einer Override sein kann — z.B. retention von
+// { months: 24 } auf { years: 10 } wuerde sonst zu { months: 24, years: 10 }
+// werden, semantisch nonsense.
+const ATOMIC_PATHS: ReadonlySet<string> = new Set([
+  "userRights.gracePeriod",
+  "userRights.auskunftFrist",
+  "userRights.exportDownloadTtl",
+  "tenantDestroyGracePeriod",
+  "breach.authorityNotificationDeadline",
+  "auditLog.retention",
+]);
+
+function deepMerge<T extends Record<string, unknown>>(
+  base: T,
+  patch: Record<string, unknown>,
+  path = "",
+): T {
+  const out: Record<string, unknown> = { ...base };
+  for (const [k, v] of Object.entries(patch)) {
+    if (v === undefined) continue;
+    const fullPath = path ? `${path}.${k}` : k;
+    const existing = out[k];
+    if (ATOMIC_PATHS.has(fullPath)) {
+      // Atomic — replace komplett statt rekursiv mergen.
+      out[k] = v;
+    } else if (isPlainObject(existing) && isPlainObject(v)) {
+      out[k] = deepMerge(existing, v, fullPath);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out as T; // @cast-boundary generic-record
+}
+
+/**
+ * Resolved ein Profile inklusive `extends`-Auflösung. Wirft wenn die
+ * extends-Chain tiefer als 1 Level ist (vermeidet Cycles + macht
+ * Boot-Validation einfach).
+ *
+ * Edge-Case (gepinnt): das `extends`-Target darf selbst KEIN extends
+ * haben. Wer doch eine Mehrstufen-Hierarchie braucht, definiert die
+ * Stufen explizit (z.B. `de-hr-strict extends eu-dsgvo`, statt
+ * `de-hr-strict extends de-hr-dsgvo-hgb extends eu-dsgvo`).
+ */
+function resolveExtends(key: ComplianceProfileKey): ComplianceProfile {
+  const raw = RAW_PROFILES[key];
+  if (!raw.extends) {
+    return raw as ComplianceProfile; // @cast-boundary schema-walk
+  }
+
+  const base = RAW_PROFILES[raw.extends];
+  if (base.extends) {
+    throw new Error(
+      `Compliance-Profile "${key}" extends "${raw.extends}" which itself extends "${base.extends}" — chain depth >1 not supported. Define a flat extends-hierarchy instead.`,
+    );
+  }
+
+  return deepMerge(
+    base as Record<string, unknown>, // @cast-boundary generic-record
+    raw as unknown as Record<string, unknown>,
+  ) as unknown as ComplianceProfile;
+}
+
+/**
+ * Pre-baked Profile-Liste (extends bereits aufgelöst). Beim Modul-Load
+ * einmal berechnet — wirft bei Definition-Fehlern (Cycle, missing target)
+ * sofort, nicht erst beim ersten Resolver-Call.
+ */
+export const COMPLIANCE_PROFILES: Readonly<Record<ComplianceProfileKey, ComplianceProfile>> =
+  Object.fromEntries(
+    (Object.keys(RAW_PROFILES) as ComplianceProfileKey[]).map((k) => [k, resolveExtends(k)]),
+  ) as Readonly<Record<ComplianceProfileKey, ComplianceProfile>>; // @cast-boundary dynamic-key
+
+// --- Effective-Profile-Resolver ---
+
+export interface EffectiveComplianceProfile {
+  readonly profile: ComplianceProfile;
+  readonly warning?: "no-profile-selected";
+}
+
+/**
+ * Liefert das effektive Compliance-Profile fuer einen Tenant inklusive
+ * Tenant-Override.
+ *
+ * Edge-Case-Verhalten (gepinnt):
+ *   - selection=undefined → minimal-no-region + warning="no-profile-selected"
+ *   - selection=valid + override=undefined → effective profile, kein warning
+ *   - selection=valid + override → deep-merged effective, kein warning
+ *
+ * Production-Marker: das frueher hier vorgesehene "minimal-in-production"-
+ * warning ist entfallen weil set-profile (Sprint 1.7 X1) minimal-no-region
+ * nicht mehr als Tenant-Wahl akzeptiert. Wer Production-spezifisches
+ * Verhalten braucht (z.B. Block-bei-Default), addiert den Marker spaeter
+ * bei Bedarf.
+ */
+export function resolveComplianceProfile(args: {
+  readonly selection?: ComplianceProfileKey;
+  readonly override?: ComplianceProfileOverride;
+}): EffectiveComplianceProfile {
+  if (!args.selection) {
+    return {
+      profile: COMPLIANCE_PROFILES["minimal-no-region"],
+      warning: "no-profile-selected",
+    };
+  }
+
+  const base = COMPLIANCE_PROFILES[args.selection];
+  if (!args.override) {
+    return { profile: base };
+  }
+
+  const merged = deepMerge(
+    base as unknown as Record<string, unknown>,
+    args.override as Record<string, unknown>, // @cast-boundary engine-payload
+  ) as unknown as ComplianceProfile;
+  return { profile: merged };
+}

package/src/compliance/sub-processors.ts

@@ -0,0 +1,152 @@
+// Sub-Processor-Liste der Kumiko-Plattform.
+//
+// Auftragsverarbeiter im Sinne von DSGVO Art. 28 die Kumiko fuer den
+// Plattform-Betrieb einsetzt. Wird oeffentlich exposed unter
+//   /api/compliance/sub-processors        (JSON, Sprint 1)
+//   /api/compliance/sub-processors.rss    (RSS, Sprint 1)
+//   kumiko.so/subprocessors               (HTML, Marketing-Repo)
+//
+// Tenant-Admins muessen ueber Add/Change/Remove informiert werden mit
+// Lead-Time aus dem Compliance-Profile (typisch 30d). Cron-Job kommt
+// in Sprint 1 (compliance-profiles).
+//
+// Quelle: docs/plans/datenschutz/compliance-profiles.md "Sub-Processor-
+// Management" + docs/plans/datenschutz/legal-artifacts.md.
+
+/**
+ * Bundle-Tier-Marker fuer SubProcessor.appliesTo. "all-tiers" matched
+ * unabhaengig vom konkreten Tenant-Bundle (z.B. Hetzner als Hosting-
+ * Provider). Konkrete Tier-Namen koennen per-Tenant gefiltert werden.
+ */
+export type BundleTier = "all-tiers" | "standard" | "business" | "enterprise";
+
+/**
+ * Beschreibt einen Auftragsverarbeiter (Art. 28 DSGVO) der von Kumiko
+ * fuer den Plattform-Betrieb eingesetzt wird.
+ */
+export interface SubProcessor {
+  /** Voller juristischer Name. */
+  readonly name: string;
+  /** Was macht der Sub-Processor fuer uns? */
+  readonly purpose: string;
+  /** Sitz / Datenverarbeitungs-Region. */
+  readonly region: string;
+  /** Link zum Auftragsverarbeitungsvertrag (DPA/AVV). */
+  readonly dpa: string;
+  /** Wann wurde der Sub-Processor zu unserer Plattform hinzugefuegt? */
+  readonly addedAt: string;
+  /**
+   * Welche Bundle-Tiers nutzen diesen Sub-Processor?
+   * Tenants nicht-betroffener Tiers brauchen keine Notification bei
+   * Aenderungen.
+   */
+  readonly appliesTo: readonly BundleTier[];
+  /**
+   * Standard Contractual Clauses (SCC) fuer Drittlandsuebermittlung
+   * abgeschlossen. Pflicht fuer alle Sub-Processors mit Sitz ausserhalb
+   * EU/EWR.
+   */
+  readonly sccRequired?: boolean;
+  /**
+   * Tenant muss explizit aktivieren (z.B. AI-Feature). Ohne Opt-In
+   * werden keine Daten an diesen Sub-Processor gesendet.
+   */
+  readonly optInOnly?: boolean;
+  /**
+   * Business Associate Agreement fuer HIPAA-Customers verfuegbar.
+   * Relevant nur fuer hipaa-healthcare Compliance-Profile.
+   */
+  readonly hipaaBaaAvailable?: boolean;
+  /**
+   * Geplant aber noch nicht aktiv (Vorbereitung fuer kommenden Sprint).
+   * Wird im Sub-Processor-Endpoint als "planned"-Sektion separat
+   * ausgegeben damit Tenants schon Lead-Time bekommen.
+   */
+  readonly status?: "active" | "planned";
+}
+
+/**
+ * Plattform-weite Sub-Processor-Liste.
+ *
+ * Reihenfolge: nach addedAt (aelteste zuerst). Bei Aenderungen
+ * Snapshot-Test im Test-File explizit updaten — der detektiert
+ * stille Aenderungen.
+ */
+export const KUMIKO_SUB_PROCESSORS: readonly SubProcessor[] = [
+  {
+    name: "Hetzner Online GmbH",
+    purpose: "Cloud-Infrastructure (CNPG-Postgres-Cluster, K8s-Pods, Volumes, Object-Storage)",
+    region: "EU (Germany)",
+    dpa: "https://www.hetzner.com/legal/dpa",
+    addedAt: "2024-01-01",
+    appliesTo: ["all-tiers"],
+    status: "active",
+  },
+  {
+    name: "Cloudflare, Inc.",
+    purpose: "DNS, CDN, DDoS-Protection, WAF",
+    region: "Global (US-headquartered)",
+    dpa: "https://www.cloudflare.com/cloudflare-customer-dpa",
+    addedAt: "2024-01-01",
+    appliesTo: ["all-tiers"],
+    sccRequired: true,
+    status: "active",
+  },
+  {
+    name: "Sendinblue SAS (Brevo)",
+    purpose: "Transactional Email Delivery",
+    region: "EU (France)",
+    dpa: "https://www.brevo.com/legal/dpa/",
+    addedAt: "2024-03-01",
+    appliesTo: ["standard", "business", "enterprise"],
+    status: "active",
+  },
+  {
+    name: "Heinlein Hosting (Mailbox.org)",
+    purpose: "Marketing Email Delivery",
+    region: "EU (Germany)",
+    dpa: "https://mailbox.org/de/datenschutzerklaerung",
+    addedAt: "2024-03-01",
+    appliesTo: ["all-tiers"],
+    status: "active",
+  },
+  {
+    name: "Anthropic PBC",
+    purpose: "AI Model Inference (L2 Composition Layer, AI-Foundation)",
+    region: "US",
+    dpa: "https://www.anthropic.com/legal/dpa",
+    addedAt: "2026-06-01",
+    appliesTo: ["business", "enterprise"],
+    sccRequired: true,
+    optInOnly: true,
+    hipaaBaaAvailable: true,
+    status: "planned",
+  },
+  {
+    name: "Stripe, Inc.",
+    purpose: "Payment Processing (Subscription-Stripe-Plugin)",
+    region: "Global (US-headquartered)",
+    dpa: "https://stripe.com/legal/dpa",
+    addedAt: "2026-06-01",
+    appliesTo: ["all-tiers"],
+    sccRequired: true,
+    status: "planned",
+  },
+];
+
+/**
+ * Filter helper — nur aktive Sub-Processors (kein status="planned").
+ * Genutzt vom oeffentlichen JSON-Endpoint (Sprint 1).
+ */
+export function getActiveSubProcessors(): readonly SubProcessor[] {
+  return KUMIKO_SUB_PROCESSORS.filter((sp) => sp.status !== "planned");
+}
+
+/**
+ * Filter helper — nur geplante Sub-Processors (status="planned"). Werden
+ * separat als "demnaechst aktiv"-Sektion ausgegeben damit Tenant-Admins
+ * schon Lead-Time fuer Compliance-Profile-Konfiguration bekommen.
+ */
+export function getPlannedSubProcessors(): readonly SubProcessor[] {
+  return KUMIKO_SUB_PROCESSORS.filter((sp) => sp.status === "planned");
+}