@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/user-data-rights/COMPLIANCE.md

@@ -0,0 +1,202 @@
+# DSGVO Compliance — Operator-Guide
+
+Dieses Dokument bündelt die **technischen Fakten** zur DSGVO-Pipeline
+(Art. 15/17/18/20) als Grundlage für:
+
+- **Verarbeitungsverzeichnis** (Art. 30) — was wird wo wie lange gespeichert
+- **Datenschutzerklärung** — welche Endpoints decken welchen Artikel ab
+- **AVV mit Sub-Processors** — welche TOM sind eingebaut
+- **Operator-Runbook** — was triggert wann, wer kann was sehen
+
+> Juristische Texte (AVV-Wortlaut, Datenschutzerklärung-Bausteine,
+> Verarbeitungsverzeichnis-Strukturierung) gehören zu Marc + Anwalt —
+> dieses Dokument liefert nur die technischen Fakten dafür.
+
+---
+
+## 1. Endpoint → Artikel-Mapping
+
+| Artikel | Endpoint / Runner | Wer ruft auf | Was passiert |
+|---------|-------------------|--------------|--------------|
+| **Art. 15 (Auskunft, light)** | `user-data-rights:query:my-audit-log` | User | Liest eigene Framework-Events aus `kumiko_events` (account-weit über alle Memberships). Filterbar nach `eventType`, `aggregateType`, `from`/`to`. Domain-Entities ohne `ctx.appendEvent` erscheinen NICHT — die kommen im Export-Bundle (Art. 20). |
+| **Art. 15 + 20 (Auskunft + Portabilität)** | `user-data-rights:write:request-export` | User | Async Job → ZIP mit user-Profil + fileRefs + alle EXT_USER_DATA-Provider-Daten (cross-tenant) + signed Magic-Link per Email. Idempotent: nur 1 active Job pro User (`ACTIVE_JOB_CONSTRAINT`). |
+| **Art. 15 + 20** | `GET /user-export/by-token` (interstitial) + `POST /user-export/by-token` (exchange) | Anonym (Magic-Link-Pfad) | Email-Link trägt den Token als URL-Fragment (`#token=`, nie an den Server gesendet, issue #1271); Interstitial-Script liest das Fragment client-seitig und tauscht es per POST-Body gegen die signed Storage-URL. Kein `?token=`-Query-Fallback (#1512) — Query-Param landet unveränderlich in Proxy-/Access-Logs. Multi-use innerhalb TTL. Audit: `lastUsedAt`, `lastUsedFromIp`, `lastUsedUserAgent`. |
+| **Art. 15 + 20** | `GET /user-export/by-job/:jobId` | User (Session-Auth) | UI-Klick-Pfad. Cross-tenant-same-user: User in Tenant B kann Job aus Tenant A laden wenn er der Owner ist. |
+| **Art. 17 (Löschung)** | `user-data-rights:write:request-deletion` | User | Soft-Delete: `status=DeletionRequested` + `gracePeriodEnd = now + profile.gracePeriod`. Cron `run-forget-cleanup` führt nach Grace die Anonymisierung durch. |
+| **Art. 17** | `user-data-rights:write:cancel-deletion` | User | Während Grace: status zurück auf `Active`. |
+| **Art. 17** | `run-forget-cleanup` (Cron) | System | Findet User mit `status=DeletionRequested AND gracePeriodEnd < now`. Pro User Sub-TX über alle EXT_USER_DATA-Provider mit Strategy aus `retention.policyFor`. user-Hook anonymisiert (PII raus, Sentinel-Email). |
+| **Art. 18 (Restriction)** | `user-data-rights:write:restrict-account` | Admin / SystemAdmin | Status-Flip → Auth-Middleware-Guard blockt Logins. `sessions.revokeAllForUser` killt aktive Sessions. |
+| **Art. 18** | `user-data-rights:write:lift-restriction` | Admin / SystemAdmin | Restriction aufheben. |
+| **Operator (DPO)** | `user-data-rights:query:list-download-attempts` | Admin / SystemAdmin | Brute-Force-Detection: zeigt invalid Download-Versuche (notFound / expired / failed / signedUrlNotSupported) gefiltert nach Result, IP, Zeitraum. |
+
+---
+
+## 2. Speicherorte (Verarbeitungsverzeichnis Art. 30)
+
+| Tabelle | Inhalt | Personenbezug | Retention | Zweck |
+|---------|--------|---------------|-----------|-------|
+| `read_users` | User-Profil (email, displayName, passwordHash, locale, status, gracePeriodEnd, roles) | direkt | per Domain (typ. blockDelete bei Aufbewahrungspflicht, sonst hardDelete via Forget-Pipeline) | Authentifizierung, Nutzer-Profil |
+| `read_tenant_memberships` | User↔Tenant-Verknüpfung + Rollen | direkt (via userId) | per Tenant-Lifecycle | Mehrmandant-Zuordnung |
+| `kumiko_events` | Event-Store (alle write-Events) | direkt (`createdBy = userId`) | per Domain-Policy via `data-retention` | Audit-Trail (Art. 15-Selbstauskunft Quelle), Event-Sourcing |
+| `read_export_jobs` | Async Export-Status (queued/running/done/failed), userId, requestedAt, doneAt, storageKey | direkt (userId) | per `compliance-profiles` Profil-Default | Idempotenz + Status-Polling |
+| `read_export_download_tokens` | Magic-Link-Hash (SHA-256), TTL, useCount, lastUsedAt, lastUsedFromIp, lastUsedUserAgent | indirekt (Token→Job→User) | `compliance-profiles.userRights.exportDownloadTtl` (default 7d) | Magic-Link-Auth + Multi-Use-Audit |
+| `read_download_attempts` | Invalid Download-Versuche: result, via, tokenHash, ip, userAgent, attemptedAt | indirekt (IP) | **90d hardDelete** (Entity-Default, Disk-Bomb-Schutz) | DPO-Brute-Force-Detection |
+| `read_tenant_compliance_profiles` | Per-Tenant Profile-Wahl + Override | nein | unbounded (Konfiguration) | Region-/Branchen-Defaults |
+| `read_tenant_retention_overrides` | Per-Tenant Retention-Override pro Entity | nein | unbounded (Konfiguration) | Aufbewahrungspflicht-Edge-Cases |
+| Storage-Provider (Local / S3) | Export-ZIPs + File-Binaries | indirekt (Inhalt) | Local: per `exportDownloadTtl` Cleanup. S3: lifecycle-Policy (App-Author-Verantwortung) | Daten-Export-Auslieferung |
+
+### Bekanntes Residuum: `createdBy` / `metadata.userId` in `kumiko_events`
+
+Nach der Forget-Pipeline (Art. 17, Abschnitt 1) bleiben `kumiko_events.created_by`
+und `metadata.userId` (Event-Store-Schema `events-schema.ts`, EventMetadata-Feld)
+als Klartext-UUID stehen. Die Forget-Hooks aus `user-data-rights-defaults` fassen
+`kumiko_events` nicht an — `createdBy`/`metadata.userId` sind keine über
+`defineEvent(..., { piiFields })` deklarierten Payload-PII-Felder (siehe
+`packages/framework/src/crypto/event-pii.ts`) und laufen deshalb nicht durch die
+Payload-Verschlüsselung. Löschung dieser Rows erfolgt ausschließlich über die
+zeitbasierte `data-retention`-Policy (`keepFor`, s. `kumiko_events`-Zeile in Abschnitt
+2 oben), unabhängig vom User-Forget-Antrag.
+
+Technische Basis: Der `read_users`-Row zur betroffenen UUID wird beim Forget-Run
+in-place anonymisiert, nicht hard-gelöscht (Sentinel-Pattern, siehe Abschnitt 4
+„Integrität"). Email, Displayname und Passwort-Hash werden dabei entfernt/ersetzt —
+das ist der Schlüssel, der die Verknüpfung kappt: Sobald diese Felder weg sind, gibt
+es keinen Rückweg von der UUID in `created_by` zu einer realen Identität mehr. Die
+UUID bleibt als stabiler, aber orphaned Pseudonym-Wert bestehen, bis die
+Retention-Policy irgendwann das Event selbst löscht.
+
+---
+
+## 3. Compliance-Profile
+
+| Profil | gracePeriod | exportDownloadTtl | Stale-After | Sub-Processors |
+|--------|-------------|-------------------|-------------|----------------|
+| `eu-dsgvo` | 30d | 7d | 30d | per Tenant konfigurierbar |
+| `swiss-dsg` | 30d | 7d | 30d | + EDÖB-Meldepfad |
+| `de-hr-dsgvo-hgb` | 30d | 7d | 30d | + HR-Aufbewahrung 10y für HR-Entities (anonymize statt delete) |
+| `minimal-no-region` | 30d | 7d | 30d | Migration-Edge-Case ohne Region |
+
+Tenant kann via `compliance-profiles:write:set-profile` + Override (`override.userRights.gracePeriod={ days: N }` etc.) eigene Werte setzen.
+
+---
+
+## 4. Technische und Organisatorische Maßnahmen (TOM)
+
+Eingebaute Schutzmaßnahmen — können 1:1 in den AVV-Anhang "Technische
+und Organisatorische Maßnahmen" übernommen werden:
+
+### Vertraulichkeit / Zugriffskontrolle
+
+- **Magic-Link-Token-Hashing**: Plain-Token landet NIE in DB / Event-Store. SHA-256-Hash via `crypto.subtle.digest` (Web-Crypto-API). Plain-Token kommt nur ephemeral via Email-Callback an die App-Author-Implementation.
+- **Download-Token Multi-Use within TTL**: kein consume-on-use (Pattern Google Takeout) — User kann ZIP mehrfach laden, aber TTL gilt absolut.
+- **Audit-Felder am Token**: useCount, lastUsedAt, lastUsedFromIp, lastUsedUserAgent. Operator sieht ob Token mehrfach verwendet wurde, von welcher IP.
+- **Account-weite Auskunft via `ctx.db.raw`**: `my-audit-log` umgeht TenantDb-Auto-Filter explizit (Account-weite Sicht für Art. 15 ist Pflicht); Sicherung über hard-coded `WHERE createdBy = ctx.user.id` (kein userId-Parameter, kein Cross-User-Snooping möglich).
+- **Cross-User-Schutz im Download-Pfad**: `download-by-job` checkt `jobRow.userId === session.user.id` — User kann nur eigene Jobs laden.
+- **Restriction killt Sessions**: `restrict-account` triggert `sessions.revokeAllForUser` — restricted User kann existierende Tabs nicht weiternutzen.
+
+### Integrität
+
+- **Event-Sourcing first-class**: alle DSGVO-Schreib-Operationen (request-deletion, restrict, lift, request-export) sind Events im `kumiko_events`-Store mit `version_conflict`-Schutz.
+- **Forget-Strategy aus `data-retention`**: Cleanup-Runner konsultiert `retention.policyFor` pro Entity — `blockDelete` für gesetzliche Aufbewahrungspflicht (HR/HGB), `anonymize` als Alternative zu `hardDelete`.
+- **Strategy-respect-Pattern in Default-Hooks**: user-Hook anonymisiert mit Sentinel-Pattern `deleted-<id>@anonymized.invalid` — Unique-Constraint + FK-Refs bleiben intakt.
+
+### Verfügbarkeit / Belastbarkeit
+
+- **Best-Effort-Audit beim Download**: Audit-INSERT in `read_download_attempts` ist `try/catch` swallowed — Audit-Failure killt nicht den User-facing 4xx.
+- **Idempotenz im Export-Job**: `ACTIVE_JOB_CONSTRAINT` (UNIQUE-Index auf `(userId, status='active')`) verhindert Doppel-Jobs. Worker-Crash → Job bleibt `running`, Recovery-Pfad via Job-Run-Tracking aus `jobs`-Feature.
+- **Per-User Sub-TX im Forget-Runner**: Ein User-Hook-Throw rollback'd nur diesen User; andere User im Batch laufen weiter.
+- **Best-Effort-Notification-Callbacks**: send-Throw für Job A killt nicht Batch B/C (Memory: Atom 5.fix3).
+
+### Brute-Force-Schutz
+
+- **Edge-Rate-Limit auf Download-Endpoint**: `rateLimit: { per: "ip", limit: 30, windowSeconds: 60 }` für `download-by-token`.
+- **Download-Attempt-Audit** mit 90d hardDelete: invalid Versuche werden persistiert für DPO-Detection, Tabelle ist begrenzt → kein Disk-Bomb durch Brute-Force.
+- **Token-Hash-Suchraum**: 32-Byte-Random = 256 Bit, Brute-Force über Edge-Limit praktisch nicht möglich.
+
+### Zweckbindung / Datenminimierung
+
+- **Export-Bundle Default-PII-Filter**: user-Hook entfernt `passwordHash`, `roles`, `status` aus dem Bundle (App-Author kann das per Custom-Hook überschreiben).
+- **fileRefs separat**: Export-Bundle enthält Datei-Metadaten (id, fileName, mimeType, size); Binaries werden via signed-URL separat ins ZIP gepackt — kein Inline-Base64-Memory-Druck.
+
+### Auftragskontrolle (gegenüber Sub-Processors)
+
+- **Storage-Provider als Plugin** (`file-foundation` + `file-provider-{s3,inmemory}`): App-Author wählt Provider; AVV mit S3-Hoster (Hetzner / AWS) ist vom Provider abhängig.
+- **Email-Transport als Plugin** (`mail-foundation` + `mail-transport-{smtp,inmemory}`): SMTP / SES / Resend per Plugin austauschbar.
+- **`compliance-profiles:query:sub-processors`**: Per-Tenant Liste der aktiven Sub-Processors, abrufbar für AVV-Anhang.
+
+---
+
+## 5. Cron-Jobs / Operationale Trigger
+
+| Job | Trigger | Was passiert | Operator-Sichtbarkeit |
+|-----|---------|--------------|------------------------|
+| `run-forget-cleanup` | Cron (per App-Author konfigurierbar, typisch täglich) | Findet User mit abgelaufener Grace, ruft `EXT_USER_DATA.delete` pro Provider, anonymisiert User, sendet `sendDeletionExecutedEmail`-Callback | `read_job_runs` (success/fail), Hook-Errors als `errors[]` im Result |
+| `run-export-jobs` | Cron + Event-getriggert | Findet pending Export-Jobs, ruft `runUserExport` → ZIP-Bau → Storage-Upload → Magic-Link-Token → `sendExportReadyEmail` | `read_job_runs`, `read_export_jobs.status` |
+| `data-retention-cleanup` | Cron (in `data-retention`) | Cleant abgelaufene Rows pro Entity per `retention.keepFor` | `read_job_runs` |
+| Token-Cleanup (implizit) | Per `compliance-profiles.userRights.exportDownloadTtl` | Worker-Job entfernt expired Magic-Link-Tokens + Storage-Binaries | `read_export_download_tokens` |
+| Download-Attempt-Cleanup | Per Entity-Default 90d | Cleant `read_download_attempts` | — |
+
+App-Author registriert die Cron-Trigger im run-config; `jobs`-Feature
+persistiert Run-Tracking + Retry-Pfad.
+
+---
+
+## 6. Doku-Snippets für Marc
+
+### Datenschutzerklärung — Betroffenenrechte
+
+> **Recht auf Auskunft (Art. 15 DSGVO):** Sie können jederzeit eine
+> Kopie aller bei uns über Sie gespeicherten Daten anfordern. Über die
+> Funktion "Daten exportieren" in den Account-Einstellungen erhalten
+> Sie ein vollständiges JSON-/ZIP-Bundle Ihrer Profildaten, hochgeladenen
+> Dateien und [App-Author: Domain-Daten ergänzen] per signed Magic-Link
+> auf Ihre hinterlegte E-Mail-Adresse. Der Link ist 7 Tage gültig.
+
+> **Recht auf Löschung (Art. 17 DSGVO):** Über "Account löschen" können
+> Sie Ihren Account jederzeit zur Löschung vormerken. Es gilt eine
+> Karenzzeit von 30 Tagen, in der Sie den Antrag widerrufen können
+> (Funktion "Löschung widerrufen"). Nach Ablauf werden Ihre Daten
+> automatisch gelöscht oder anonymisiert. Daten mit gesetzlicher
+> Aufbewahrungspflicht (z. B. Rechnungen nach §147 AO) bleiben bis zum
+> Fristablauf gesperrt erhalten und werden danach automatisch gelöscht.
+
+> **Recht auf Einschränkung (Art. 18 DSGVO):** Auf begründeten Antrag
+> kann Ihr Account temporär gesperrt werden. Während der Sperre können
+> Sie sich nicht mehr einloggen, Ihre Daten werden aber nicht gelöscht
+> oder verändert.
+
+### AVV-TOM-Anhang
+
+Für den AVV-Anhang "Technische und Organisatorische Maßnahmen" siehe
+**Abschnitt 4** dieses Dokuments — komplette Liste mit Verweisen auf
+die Code-Implementierung.
+
+### Verarbeitungsverzeichnis
+
+Spalte "Speicherorte / Empfänger" → siehe **Abschnitt 2** (Tabellen-
+Übersicht). Spalte "Löschfristen" → siehe **Abschnitt 3** + Spalte
+"Retention" in Abschnitt 2.
+
+---
+
+## 7. Was NICHT in diesem Framework abgedeckt ist
+
+Bewusst ausserhalb — App-Author-Verantwortung:
+
+- **Auswahl + AVV mit konkretem Storage-Provider** (Hetzner / AWS / etc.)
+- **Auswahl + AVV mit konkretem Email-Provider** (SMTP-Host / SES / Resend)
+- **Datenpannen-Meldung** an Aufsichtsbehörde (organisatorisch, nicht technisch)
+- **DSFA** (Datenschutz-Folgenabschätzung) — Framework liefert die TOM-Inputs, App-Author macht die Bewertung
+- **Cookie-Consent-Layer** (das ist Frontend-Sache + separate consent-Feature, nicht Teil von user-data-rights)
+- **Tenant-Lifecycle-Destroy** (Account-Löschung des Tenants selbst, nicht der User darin) — kommt als separates `tenant-lifecycle`-Feature in Sprint 5
+
+---
+
+## Referenzen
+
+- Code: `packages/bundled-features/src/user-data-rights/`
+- Default-Hooks: `packages/bundled-features/src/user-data-rights-defaults/`
+- Compliance-Profile: `packages/bundled-features/src/compliance-profiles/`
+- Retention-Engine: `packages/bundled-features/src/data-retention/`
+- Sample-App: `samples/apps/user-data-rights-demo/`
+- Tests: `packages/bundled-features/src/user-data-rights/__tests__/` (188 Tests)

package/packages/bundled-features/src/user-data-rights/README.md

@@ -0,0 +1,109 @@
+# user-data-rights
+
+DSGVO Art. 15 (Auskunft) + Art. 17 (Löschung) + Art. 18 (Restriction) +
+Art. 20 (Portabilität) als Core-Feature.
+
+**Status:** S2 abgeschlossen — alle Endpoints, Hooks, Default-Provider,
+Cron-Pipeline, Tests + Sample wired.
+
+## Pattern
+
+Statt jedes Feature seine eigene Forget-/Export-Logik schreibt, hängt
+es sich via `r.useExtension(EXT_USER_DATA, "<entity>", { export, delete })`
+an. user-data-rights orchestriert Export- und Forget-Pipeline:
+
+```ts
+defineFeature("tasks", (r) => {
+  r.requires("user-data-rights");
+  r.useExtension(EXT_USER_DATA, "task", {
+    export: async (ctx) => ({
+      entity: "task",
+      rows: await ctx.db.select().from(tasksTable)
+        .where(eq(tasksTable.authorId, ctx.userId)),
+    }),
+    delete: async (ctx, strategy) => {
+      if (strategy === "anonymize") {
+        await ctx.db.update(tasksTable).set({ authorId: null })
+          .where(eq(tasksTable.authorId, ctx.userId));
+      } else {
+        await ctx.db.delete(tasksTable)
+          .where(eq(tasksTable.authorId, ctx.userId));
+      }
+    },
+  });
+});
+```
+
+Hook-Signaturen in `framework/src/engine/extensions/user-data.ts`:
+
+- `UserDataExportHook(ctx) => Promise<UserDataExportSnippet | null>`
+- `UserDataDeleteHook(ctx, strategy) => Promise<void>`
+- `UserDataDeleteStrategy = "delete" | "anonymize"`
+
+## Endpoints
+
+| Article | Handler | Zweck |
+|---------|---------|-------|
+| Art. 15 | `user-data-rights:query:my-audit-log` | User sieht eigene Framework-Events (account-weit über alle Memberships). Domain-Entities ohne `ctx.appendEvent` erscheinen NICHT — nur im Export-Bundle. |
+| Art. 15+20 | `user-data-rights:write:request-export` | Async Job → ZIP mit user-Profil + fileRefs + alle EXT_USER_DATA-Provider-Daten + signed Magic-Link |
+| Art. 17 | `user-data-rights:write:request-deletion` | Soft-Delete mit Grace-Period, anschließend Cron anonymisiert User + cleant Domain-Entities |
+| Art. 17 | `user-data-rights:write:cancel-deletion` | User widerruft seinen Forget-Request während der Grace |
+| Art. 18 | `user-data-rights:write:restrict-account` | Auth-Middleware blockt Logins bis Lift |
+| Art. 18 | `user-data-rights:write:lift-restriction` | Admin/SystemAdmin hebt Restriction auf |
+| Operator | `user-data-rights:query:list-download-attempts` | DPO-Sicht auf invalid Download-Versuche (Brute-Force-Detection, Admin/SystemAdmin only) |
+
+Plus 2 anonyme HTTP-Routes für Export-Download (Magic-Link-Pfad +
+session-auth-Pfad), siehe `handlers/download-by-{token,job}.query.ts`.
+
+## Cross-Feature-API
+
+**Exposes:**
+- `userDataRights.runExport` — über die public Runner-Exports
+  (`runUserExport`, `runForgetCleanup`)
+- `userDataRights.runForget`
+
+**Uses:**
+- `compliance.forTenant` (Grace-Period aus Profile)
+- `retention.policyFor` (blockDelete-Konsultation, anonymize statt delete)
+- `sessions.revokeAllForUser` (Restriction killt aktive Sessions)
+
+## Default-Hooks (`user-data-rights-defaults`)
+
+Optional-mountbares Sub-Feature liefert Default-Hooks für
+Core-Entities `user` (anonymize: email→`deleted-<id>@anonymized.invalid`,
+displayName→`(deleted)`, passwordHash=null) und `fileRef` (delete: row +
+storage-binary; anonymize: insertedById=null). App-Author kann es
+weglassen wenn er Custom-Hooks registrieren will.
+
+## Audit-Trail
+
+| Tabelle | Zweck | Retention |
+|---------|-------|-----------|
+| `kumiko_events` | Framework-Event-Store, Quelle für `my-audit-log` | per Domain-Policy |
+| `read_export_jobs` | Async Export-Status (queued / done / failed) | per `compliance-profiles` |
+| `read_export_download_tokens` | Magic-Link-Hash + TTL + lastUsed-Audit | per `compliance-profiles` (default `exportDownloadTtl`) |
+| `read_download_attempts` | Invalid-Download-Versuche für DPO-Brute-Force-Detection | **90d hardDelete** (Entity-Default — schützt vor Disk-Bomb bei aktiven Angriffen) |
+
+## Tests
+
+18 Testdateien, 188 Tests, alle grün:
+
+| Datei | Pinst |
+|-------|-------|
+| `audit-log.integration.test.ts` | Cross-User-Isolation, Account-weite Sicht, eventType-Filter, Admin-only operator-query, download-attempt 90d-retention |
+| `cross-data-matrix.integration.test.ts` | 3-Provider-Pipeline (user + fileRef + custom-domain), Cross-Tenant Forget mit user-anonymize, Other-User-Isolation |
+| `download.integration.test.ts` | HTTP-e2e via `r.httpRoute`: Magic-Link, multi-use, expired, failed-job, storage-cleared, cross-tenant-same-user, malicious-filename |
+| `request-export.integration.test.ts` | Idempotency, active-job-constraint, cross-tenant-anyMember-userId-pattern |
+| `request-deletion-callback.integration.test.ts` + `request-cancel-deletion.integration.test.ts` | Grace + Cancel-Pfad + Email-Callback best-effort |
+| `restriction-flow.integration.test.ts` | Status-Flip + Auth-Middleware-Block + Lift |
+| `run-{export-jobs,forget-cleanup,user-export}.integration.test.ts` | Worker-Logic + Idempotency + Email-Callbacks |
+| `policy-to-strategy.test.ts` | Retention.strategy → UserDataDeleteStrategy mapping |
+| `user-data-rights.integration.test.ts` | Boot-Smoke + Feature-Meta |
+| `token-helpers.test.ts` + `zip-path.test.ts` | Token-Hashing + Path-Traversal-Schutz |
+| `export-job-{idempotency,schema}.test.ts` | Active-job-uniqueness + Schema-Constraints |
+
+## Sample
+
+`samples/apps/user-data-rights-demo` — runnable Demo mit todos-Domain,
+EXT_USER_DATA-Hook für strategy-aware delete (anonymize → authorId=null,
+delete → DROP), 3 living-doc Integration-Tests.

package/packages/bundled-features/src/user-data-rights/audit-download.ts

@@ -0,0 +1,125 @@
+// Audit-Helper fuer Download-Endpoint (S2.U3 Atom 4b).
+//
+// Beim Download (Token-Pfad oder Job-Pfad) werden Audit-Felder am
+// Token-Row aktualisiert:
+//   - useCount + 1
+//   - lastUsedAt = now
+//   - lastUsedFromIp = caller-IP (X-Forwarded-For oder Connection-IP)
+//   - lastUsedUserAgent = UA-Header
+//
+// **Best-Effort-Update:** version-conflicts (zwei parallel-Downloads
+// raceen um den update) werden silent geswallowt — Audit ist "letzter
+// Use", nicht "alle Uses". Der zweite Download succeeded trotzdem
+// (kein download-block bei race).
+//
+// **ES via tokenCrud.update:** kein direct-UPDATE. Memory
+// `feedback_no_fake_dispatcher` + `feedback_event_store_tenant_consistency`.
+
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { createSystemUser, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { tokenCrud } from "./run-export-jobs.js";
+import { downloadAttemptEntity, downloadAttemptsTable } from "./schema/download-attempt.js";
+
+const attemptCrud = createEventStoreExecutor(downloadAttemptsTable, downloadAttemptEntity, {
+  entityName: "download-attempt",
+});
+
+type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
+
+export interface RecordDownloadUseArgs {
+  readonly db: DbRunner;
+  readonly tokenId: string;
+  readonly tokenVersion: number;
+  readonly tokenUseCount: number;
+  /**
+   * Tenant fuer die system-mode-TenantDb. ExportDownloadToken ist
+   * tenant-agnostisch (1:1 zum tenant-agnostic Job), aber der event-
+   * store-Stream-Lookup braucht einen Tenant-Context. Wir nutzen
+   * job.requestedFromTenantId — dieselbe Identitaet wie beim
+   * Token-Create im Worker (Atom 4a).
+   */
+  readonly tenantId: TenantId;
+  readonly now: Instant;
+  readonly ip: string | null;
+  readonly userAgent: string | null;
+}
+
+/**
+ * Audit-Update: useCount, lastUsedAt, IP, UA. Best-effort —
+ * version-conflicts (parallel-downloads) werden swallowed, Download
+ * succeeded trotzdem.
+ */
+export async function recordDownloadUse(args: RecordDownloadUseArgs): Promise<void> {
+  const { db, tokenId, tokenVersion, tokenUseCount, tenantId, now, ip, userAgent } = args;
+  const executor = createSystemUser(tenantId);
+  const tdb = createTenantDb(db, tenantId, "system");
+
+  await tokenCrud
+    .update(
+      {
+        id: tokenId,
+        version: tokenVersion,
+        changes: {
+          useCount: tokenUseCount + 1,
+          lastUsedAt: now,
+          lastUsedFromIp: ip,
+          lastUsedUserAgent: userAgent,
+        },
+      },
+      executor,
+      tdb,
+    )
+    .catch(() => {
+      // version-conflict bei parallelen Downloads → der erste hat
+      // bereits useCount inkrementiert. Wir behalten den Audit-Eintrag
+      // des ersten Downloads (lastUsedAt etc.). Kein download-block.
+    });
+}
+
+// extractCallerIp lebt in feature.ts (extractAuditMeta) — query-handler
+// haben keinen direkten Header-Zugriff (transport-agnostic), httpRoute-
+// Wrapper extrahiert + steckt in payload.auditMeta.
+
+export type DownloadAttemptResult = "notFound" | "expired" | "failed" | "signedUrlNotSupported";
+
+export interface RecordInvalidAttemptArgs {
+  readonly db: DbRunner;
+  readonly tenantId: TenantId;
+  readonly now: Instant;
+  readonly result: DownloadAttemptResult;
+  readonly via: "token" | "job";
+  readonly tokenHash: string | null;
+  readonly jobId: string | null;
+  readonly attemptedByUserId: string | null;
+  readonly ip: string | null;
+  readonly userAgent: string | null;
+}
+
+// Best-effort INSERT in read_download_attempts. Throws im Audit-Pfad
+// duerfen den Download-Endpoint nicht killen (User soll seinen 404
+// bekommen, nicht 500); failures werden silent geswallowt.
+export async function recordInvalidAttempt(args: RecordInvalidAttemptArgs): Promise<void> {
+  const { db, tenantId, now } = args;
+  const executor = createSystemUser(tenantId);
+  const tdb = createTenantDb(db, tenantId, "system");
+  await attemptCrud
+    .create(
+      {
+        result: args.result,
+        via: args.via,
+        tokenHash: args.tokenHash,
+        jobId: args.jobId,
+        attemptedByUserId: args.attemptedByUserId,
+        ip: args.ip,
+        userAgent: args.userAgent,
+        attemptedAt: now,
+      },
+      executor,
+      tdb,
+    )
+    .catch(() => {
+      // best-effort
+    });
+}

package/packages/bundled-features/src/user-data-rights/boot-checks.ts

@@ -0,0 +1,71 @@
+import {
+  EXT_USER_DATA,
+  type FeatureDefinition,
+  type ResolvedPiiFlags,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { entitiesOf } from "../shared/index.js";
+
+// V2: export-without-erase gate. A feature that registers an EXT_USER_DATA
+// export hook without a matching delete hook exports data under Art.20 but
+// never erases it on forget — an Art.17 violation. Hard boot failure: no app
+// should ship a GDPR export path with no erase path. Registry-level signal
+// only; runtime no-ops (a delete hook that silently skips) are not detectable
+// here — those are covered by the export/forget integration tests.
+//
+// Registered as an `r.bootCheck()` by this feature (#1314) — EXT_USER_DATA is
+// owned by user-data-rights (r.extendsRegistrar(EXT_USER_DATA, {})), so any
+// r.useExtension(EXT_USER_DATA, ...) usage across the app already requires
+// user-data-rights to be mounted (boot-validator's extension-provider check
+// fails otherwise); running this from user-data-rights' own bootCheck is
+// equivalent to the framework-internal call it replaces.
+export function validateGdprHookCompleteness(features: readonly FeatureDefinition[]): void {
+  for (const feature of features) {
+    for (const usage of feature.extensionUsages) {
+      if (usage.extensionName !== EXT_USER_DATA) continue;
+      const hasExport = typeof usage.options?.["export"] === "function";
+      const hasDelete = typeof usage.options?.["delete"] === "function";
+      if (hasExport && !hasDelete) {
+        throw new Error(
+          `[kumiko:boot] Feature "${feature.name}" exports entity "${usage.entityName}" via EXT_USER_DATA but registers no delete hook — data is included in Art.20 exports but never erased on forget (Art.17 violation). Add a delete hook. If erasure is intentionally handled elsewhere (e.g. crypto-shredding key-erase, parent cascade), register a no-op delete: async () => {} with a comment explaining why.`,
+        );
+      }
+    }
+  }
+}
+
+// V3: PII-entity-without-hook gate. V2 checks registered hooks for
+// completeness; V3 catches the entity nobody registered at all — fields
+// annotated as user-subject data (pii / userOwned / subjectRef) yet
+// invisible to the Art.15/20 export and Art.17 forget pipeline. Hard boot
+// failure: a
+// subject-data entity that skips the pipeline is exactly the "feature built
+// past GDPR" leak this gate exists to stop. No "is user-data-rights mounted"
+// guard needed here (unlike the framework-internal predecessor) — this runs
+// as user-data-rights' own bootCheck, so it's only reachable when mounted.
+// Matching is by entity name across all features (usage.entityName is
+// unqualified); a same-named entity in another feature can mask a gap —
+// accepted, as the common case is a distinct entity name.
+export function validateGdprPiiHookCoverage(features: readonly FeatureDefinition[]): void {
+  const hookedEntities = new Set<string>();
+  for (const f of features) {
+    for (const usage of f.extensionUsages) {
+      if (usage.extensionName === EXT_USER_DATA) hookedEntities.add(usage.entityName);
+    }
+  }
+
+  for (const feature of features) {
+    for (const [entityName, entity] of entitiesOf(feature)) {
+      if (hookedEntities.has(entityName)) continue;
+      const subjectFields = Object.entries(entity.fields)
+        .filter(([, field]) => {
+          const annot = field as ResolvedPiiFlags; // @cast-boundary schema-walk
+          return Boolean(annot.pii) || Boolean(annot.userOwned) || Boolean(annot.subjectRef);
+        })
+        .map(([name]) => name);
+      if (subjectFields.length === 0) continue;
+      throw new Error(
+        `[kumiko:boot] Entity "${entityName}" (feature "${feature.name}") has user-subject fields (${subjectFields.join(", ")}) but no feature registers an EXT_USER_DATA hook for it — the data never appears in Art.15/20 exports and is never erased on forget (Art.17 gap). Register r.useExtension(EXT_USER_DATA, "${entityName}", { export, delete }) in the owning feature or a defaults feature. If this entity is intentionally out of the pipeline (e.g. crypto-shredding key-erase covers it), register a no-op hook { export: async () => null, delete: async () => {} } with a comment explaining why.`,
+      );
+    }
+  }
+}

package/packages/bundled-features/src/user-data-rights/changes.json

@@ -0,0 +1,116 @@
+[
+  {
+    "version": "0.338.0",
+    "type": "fix",
+    "title": "Forget cleanup covers tenants the user already left",
+    "detail": "`runForgetCleanup` builds the per-user tenant list from live memberships plus the user's `tenant-membership.created` history (read from the event payload, so cross-tenant SystemAdmin adds count too), deduplicated. Delete hooks, such as the notes-history mention shred, therefore also run in tenants the user left before the request. The `tenantIdsBeforeDelete` list passed to the deletion-executed mail still contains only the live memberships. Mentions written before notes recorded structured mention rows for non-members are not covered."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Public deletion and download handlers rate-limit per IP and handler"
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Export cleanup reports a last-run timestamp gauge and still reports backlog age when the pass throws",
+    "detail": "The export storage-cleanup pass now also reports an `export_cleanup_last_run_timestamp` gauge (Unix seconds, set only when a pass completes) so a stalled cron can be alerted on with `time() - metric > interval + buffer`; the backlog gauge keeps its last value when the cron stops, so `absent()` never fires. The backlog gauge is now reported even when the pass throws. The workflow-runner event wakeup uses the framework `getTemporal()` instead of the global `Temporal`, and a redelivered `workflow.waiting-for-event` no longer resets an already matched trigger."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Backlog gauge covers failed export orphans, explainer labels translated, unattributed escape-hatch actor constant",
+    "detail": "`OWNER_INVITE_ROLE_OPTIONS` is now exported from the tenant barrel so apps can compose it into custom invite screens. The privacy-center and profile deletion explainer descriptions are registered as `i18nKey()` labels with server-side English translations. The export storage-cleanup backlog gauge now also covers failed jobs with an orphaned ZIP. Escape-hatch audit events from the forget-cleanup, user-export and tenant-lifecycle runners use the exported `UNATTRIBUTED_ACTOR` constant (value `\"system\"`, unchanged) when no actor is passed. Deletion requests no longer query the tenant compliance profile for users that are not active."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "cancel-deletion actions declare the x icon instead of resolving to the destructive trash icon"
+  },
+  {
+    "version": "0.330.0",
+    "type": "fix",
+    "title": "The privacy-center restriction and deletion dialog titles are registered in English by the feature",
+    "detail": "The new i18n-parity test in `use-all-bundled` harvests the English copy from the real registrations (feature translations, client plugins, renderer defaults, mail templates) and fails with `key -> locale` when `locale-de` or `locale-es` lacks a key or an en-catalog drifts. This added the missing German and Spanish copy for billing plans, the privacy-center status field and many more keys, and removed 110 translation keys no feature registers any more. German uses \"Ereignisprotokoll\" for the audit log everywhere. `userDataRights.privacyCenter.restriction.dialogTitle` and `.deletion.dialogTitle` are registered in English by the feature."
+  },
+  {
+    "version": "0.320.0",
+    "type": "fix",
+    "title": "Audit IP comes from the framework's trustedProxyHops-aware resolver, not a self-parsed X-Forwarded-For",
+    "detail": "`extractAuditMeta` no longer reads `X-Forwarded-For`/`X-Real-IP` itself —\nit takes the `clientIp` the `/user-export/by-token` httpRoute handler now\nreceives from `HttpRouteHandlerDeps`, mapping the resolver's `unknown`\nsentinel to `null`. Closes the spoofed-first-XFF-entry gap for that\nroute. A caller invoking `/api/query`'s `download-by-token` handler\ndirectly (not through this httpRoute) can still pass its own `auditMeta`\nin the payload — a pre-existing, documented tradeoff (the handler's own\ncomment: audit data isn't security-relevant), unchanged by this fix."
+  },
+  {
+    "version": "0.313.0",
+    "type": "fix",
+    "title": "Privacy-center screen subtitle is now translatable",
+    "detail": "The Privacy screen's description was hardcoded English prose baked\ninto feature.ts instead of an i18n key, so it never localized. It's\nnow userDataRights.privacyCenter.subtitle, registered in i18n.ts with\nde/es translations."
+  },
+  {
+    "version": "0.308.0",
+    "type": "fix",
+    "title": "The privacy-center screen's \"restrict\" action declares an explicit icon",
+    "detail": "The boot validator now requires every projectionDetail action to resolve an icon (fw#3234); \"restrict\" resolved none from the shared id-derived map, so it now declares `icon: \"lock\"` explicitly. \"request-deletion\" needed no change — it now resolves via the shared map's new `deletion: \"trash\"` entry (@cosmicdrift/kumiko-types)."
+  },
+  {
+    "version": "0.289.0",
+    "type": "improvement",
+    "title": "Deletion tokens are genuinely single-use, and a losing redeem no longer leaks status",
+    "detail": "`redeemDeletionToken` previously carried an `unsafeSkip` and a separate status check before the lifecycle write, so two concurrent redemptions of the same token could both get through. The lifecycle transition now rides the executor's `expect:` precondition inside the anchor spend, so exactly one redemption wins.\nExternally visible: the loser of a concurrent redeem now receives the same generic `invalid_or_expired_token` reason on the anonymous path as an unknown token, instead of `cannot_process_deletion`. That was the point — the old reason distinguished \"known token, wrong state\" from \"unknown token\" to an unauthenticated caller. Integrators matching on the old string on that endpoint should expect the generic one.\n`pendingDeletionRequestId` is now cleared on confirm as well, closing a pre-existing gap. `skipOptimisticLock: true` stays in the lifecycle path and now carries the reason it is correct there: callers structurally never hold a row version to pass through."
+  },
+  {
+    "version": "0.287.0",
+    "type": "improvement",
+    "title": "export-cleanup cron now emits an export_cleanup_backlog_age gauge to surface stalled runs",
+    "detail": "storageCleanupPass deletes expired export bundles via provider.delete, but the storage provider only exposes list() (no timestamps), so a silent failure left unencrypted PII bundles sitting in the bucket with no signal. runExportJobs now accepts an optional MetricsHandle and, after the cleanup loop, reports the age in seconds of the oldest done-status job whose expiresAt+grace has passed while downloadStorageKey is still set (0 if none) via the new EXPORT_CLEANUP_BACKLOG_AGE_METRIC (\"export_cleanup_backlog_age\", a gauge — no _total/_seconds suffix per validateMetricName, unit: \"seconds\" carried in the r.metric() definition instead). feature.ts's job handler builds the handle itself with createMetricsHandle(ctx.meter, \"user-data-rights\") since JobContext has no bound ctx.metrics (that only exists on HandlerContext, built per write/query dispatch) — falls back to createNoopMetricsHandle() when ctx.meter is unset. Metric emission is wrapped in try/catch so an observability hiccup never fails an otherwise-successful cleanup pass. Scope is deliberately done-status only; failed-status cleanup candidates have no expiresAt/TTL."
+  },
+  {
+    "version": "0.287.0",
+    "type": "fix",
+    "title": "GDPR forget only hard-deletes files that are PII of the forgotten person",
+    "detail": "fileRefDeleteHook picked rows via insertedById (who uploaded the file) and treated every matched row the same on strategy=\"delete\", so forgetting an uploader hard-deleted third-party business files they had merely uploaded (e.g. a dealer's vehicle photos uploaded by an employee). FileFieldDef/ImageFieldDef/FilesFieldDef/ImagesFieldDef now support \"& ResolvedPiiFlags\" like every other field type (createFileField/createImageField/createFilesField/createImagesField thread personal/reason through expandPersonalAnnotations), and fileRefDeleteHook's strategy=\"delete\" branch splits rows per-row via the new isPersonalFileRow/isPersonalPiiField predicates: pii/userOwned/recordOwned fields take the existing hard-delete path (storageProvider.delete() + derivatives + row), every other row (explicit personal:false, tenantOwned, subjectRef, no annotation, or an unresolvable entity/field) goes through severPersonLink instead, same as the existing strategy=\"anonymize\" path. Unattached uploads (no entityType/fieldName) still hard-delete. Derivatives have no own file_refs row, so they keep following their original's decision (the #2461 \"GDPR derivatives survive forget\" test stays green). POST /files now resolves entityType/fieldName against the registry and rejects the upload with 400 when they're set but don't resolve to a real field, closing the gap that let a client attach a file to a field the forget-hook could never look up; both unset (unattached upload) still passes. No new column or migration — the decision uses the entityType/fieldName file_refs already stores."
+  },
+  {
+    "version": "0.285.2",
+    "type": "fix",
+    "title": "export ZIPs write to exports/{tenantId}/{jobId}.zip, enabling one bucket-wide S3 lifecycle rule",
+    "detail": "buildExportStorageKey previously put the tenant first ({tenantId}/exports/{jobId}.zip), so no S3 prefix rule could target \"all tenants, then /exports/\" without also matching normal user uploads in the same bucket. The key now starts with the fixed exports/ segment via the new @cosmicdrift/kumiko-framework/files tenantExportPrefix() helper, tenant stays as the second segment. downloadStorageKey is stored per job and never recomputed, so existing rows keep resolving through their old key — no migration needed. tenantStoragePrefixes() (also new in framework/files) lists every prefix a tenant's binaries can live under; files-tenant-data's fileRefStorageDestroyHook now sweeps all of them on tenant-destroy instead of only {tenantId}/, closing a gap where a destroyed tenant's decrypted GDPR export bundles would have survived under the new exports/ prefix."
+  },
+  {
+    "version": "0.241.0",
+    "type": "breaking",
+    "title": "privacy-center is now a declarative screen; userDataRightsClient's privacyCenter.showDeletion option is removed (fw#2312).",
+    "detail": "`privacy-center` is now a declarative `projectionDetail` screen instead of a custom React component: the Restriction and Deletion sections render through the generic renderer (`EditFieldsSection` + `actions: RowAction[]`), preserving the original confirmation dialogs (`RowActionWriteHandler.confirm`) and visibility rules (`visible: {field, eq/ne}`) 1:1. The Export section (Art. 20) stays a custom `EditExtensionSection` — it needs polling + a signed-URL download — registered via the new `ClientFeatureDefinition.extensionSectionComponents` under `EXPORT_SECTION_EXTENSION_NAME`. `PrivacyCenterScreen` is a dead export (the renderer selects the screen by `screen.type`, not the client component registry). The single `status` field now renders through the `enumOption` format instead of the raw enum string; `gracePeriodEnd` is hidden when no deletion is pending instead of showing an empty date. Known UI regression, accepted for this pass: the confirm-dialog title is now always the action's `label` (the renderer hardcodes this) — the original's distinct `dialogTitle` copy and its dynamic composed banner sentence (e.g. \"Your account will be deleted on {date}\") are gone, replaced by the translated `status` label plus a separately labeled `gracePeriodEnd` date.",
+    "migration": "A declarative screen is registered once and can no longer be toggled per-app on the client: `userDataRightsClient(options)`'s `privacyCenter: { showDeletion }` option is removed. Move the flag server-side instead — replace `createUserDataRightsFeature({})` with `createUserDataRightsFeature({ privacyCenterShowDeletion: false })` (default `true`) — it conditionally omits the Deletion section and its `request-deletion`/`cancel-deletion` actions from the screen definition. Then drop the now-unused `privacyCenter` option from the matching `userDataRightsClient({ privacyCenter: { showDeletion: false } })` call. Known affected consumer: `money-horse` (`src/app/client-features.tsx:74`)."
+  },
+  {
+    "version": "0.165.3",
+    "type": "improvement",
+    "title": "Forget cleanup purges derived Meili docs for searchable subject-PII (fw#1610).",
+    "detail": "run-forget-cleanup (and the forget cron path) call purgeSearchDocumentsForSubject after crypto-shred so searchable userOwned fields do not linger in Meili as plaintext after Art. 17."
+  },
+  {
+    "version": "0.165.1",
+    "type": "fix",
+    "title": "restrict-account runs the same cross-tenant membership check as lift-restriction (fw#1543).",
+    "detail": "Any Admin/TenantAdmin — not just SystemAdmin — could restrict a user's account and force-revoke their sessions regardless of tenant, as long as they held an admin role in some tenant. Also: the GET /user-export/by-token fallback now forwards x-forwarded-for to the internal query call, so the per-IP 30/min limit stops collapsing into one global bucket."
+  },
+  {
+    "version": "0.165.0",
+    "type": "breaking",
+    "title": "Export download: removed ?token= query param",
+    "detail": "GET /user-export/by-token no longer accepts the token as a query parameter. Only POST body (read from URL fragment) is supported now. Old email links with ?token= in the URL will stop working.",
+    "migration": "Replace any existing export links that use ?token= in the URL with POST-based links. The token is now only read from the URL fragment (#token), which browsers never send to the server."
+  },
+  {
+    "version": "0.122.0",
+    "type": "fix",
+    "title": "user-data-rights: export-download-token re-runs rotate the token in place on the same agg…",
+    "detail": "user-data-rights: export-download-token re-runs rotate the token in place on the same aggregate (update) instead of creating a second aggregate for the same jobId. A second `created` event without a `deleted` in between made every projection rebuild collide on the `one_per_job` unique index (fw#832). Operator recovery after a lost plain token is now just \"flip the job back to pending\" — never delete the token row read-side. - @cosmicdrift/kumiko-framework@0.122.0 - @cosmicdrift/kumiko-headless@0.122.0 - @cosmicdrift/kumiko-renderer@0.122.0 - @cosmicdrift/kumiko-dispatcher-live@0.122.0 - @cosmicdrift/kumiko-renderer-web@0.122.0"
+  },
+  {
+    "version": "0.119.0",
+    "type": "improvement",
+    "title": "Crypto-shredding phase D: forget wire.",
+    "detail": "Crypto-shredding phase D: forget wire. New `crypto-shredding` bundled feature with the `forget-subject` operator command (DPO/SystemAdmin) — erases a user/tenant subject key and appends a `subject-forgotten` audit event. `user-data-rights` forget-cleanup now erases the user's subject key inside the per-user sub-tx (crash-safe, before the status flip). Fixes `list()` returning ciphertext for camelCase encrypted/pii fields and caching plaintext rows."
+  }
+]