@cosmicdrift/kumiko-bundled-features 0.2.1 → 0.2.3

package/src/tier-engine/__tests__/auto-default-tier.integration.ts

@@ -0,0 +1,118 @@
+// auto-default-tier hook regression test — beweist dass beim
+// `tenant:write:create` der postSave-Hook von createTierEngineFeature
+// fired und automatisch ein tier-assignment-row mit `defaultTier`
+// schreibt.
+//
+// **Warum dieser Test existiert (2026-05-10):**
+// Der auto-default-tier-Hook wurde in Sprint 8a Phase 2 hinzugefügt aber
+// nie direkt getestet. Bei Sprint 8c (Studio-Mount mit auto-default-
+// compliance-companion-hook) flog der Bug auf: `ctx.db as DbConnection`
+// war ein Type-Lie — TenantDb exposed select/insert/update/delete, NICHT
+// execute(). Der event-store-append (event-store.ts:102) ruft
+// `db.execute(sql\`SELECT pg_notify(...)\`)` → TypeError. Fix:
+// `ctx.db.raw as DbConnection` (Pattern aus signup-confirm.write.ts:107).
+//
+// Pin-Verträge:
+//   1. tenant:write:create fired postSave-Hook mit isNew=true
+//   2. Hook erstellt tier-assignment-row im NEUEN tenant (nicht im caller-
+//      tenant — Memory `feedback_event_store_tenant_consistency`)
+//   3. Idempotency: tenant-update fired keinen weiteren row
+
+import { composeFeatures } from "@cosmicdrift/kumiko-dev-server/compose-features";
+import { buildDrizzleTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { eq } from "drizzle-orm";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { configValuesTable } from "../../config";
+import { TenantHandlers, tenantMembershipsTable, tenantTable } from "../../tenant";
+import { userTable } from "../../user";
+import type { TierMap } from "../compose-app";
+import { tierAssignmentEntity } from "../entity";
+import { createTierEngineFeature } from "../feature";
+
+const TEST_TIER_MAP: TierMap<{ readonly maxItems: number }> = {
+  free: { features: [], caps: { maxItems: 1 } },
+};
+
+const tierAssignmentTable = buildDrizzleTable("tier-assignment", tierAssignmentEntity);
+
+const features = composeFeatures(
+  [createTierEngineFeature({ defaultTier: "free", tierMap: TEST_TIER_MAP })],
+  { includeBundled: true },
+);
+
+let stack: TestStack;
+const PLATFORM_TENANT = "00000000-0000-4000-8000-000000000001";
+const sysadmin = createTestUser({
+  id: "platform-sysadmin",
+  tenantId: PLATFORM_TENANT,
+  roles: ["SystemAdmin"],
+});
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features });
+  await unsafePushTables(stack.db, {
+    config_values: configValuesTable,
+    users: userTable,
+    tenants: tenantTable,
+    tenant_memberships: tenantMembershipsTable,
+    tier_assignments: tierAssignmentTable,
+  });
+});
+
+afterAll(async () => stack?.cleanup());
+
+describe("auto-default-tier postSave hook on tenant-create", () => {
+  test("sysadmin creates a new tenant → free tier-assignment-row angelegt", async () => {
+    const data = (await stack.http.writeOk<Record<string, unknown>>(
+      TenantHandlers.create,
+      { key: "test-tenant-1", name: "Test Tenant One" },
+      sysadmin,
+    ))!;
+    const newTenantId = data["id"] as string;
+    expect(typeof newTenantId).toBe("string");
+
+    const rows = await stack.db
+      .select()
+      .from(tierAssignmentTable)
+      .where(eq(tierAssignmentTable["tenantId"], newTenantId));
+    expect(rows.length).toBe(1);
+    expect((rows[0] as Record<string, unknown>)["tier"]).toBe("free");
+  });
+
+  test("idempotency: tenant-update fired keinen weiteren tier-assignment-row", async () => {
+    const created = (await stack.http.writeOk<Record<string, unknown>>(
+      TenantHandlers.create,
+      { key: "test-tenant-2", name: "Test Tenant Two" },
+      sysadmin,
+    ))!;
+    const tenantId = created["id"] as string;
+
+    const existing = (await stack.db
+      .select()
+      .from(tenantTable)
+      .where(eq(tenantTable["id"], tenantId))) as Array<{ id: string; version: number }>;
+    const currentVersion = existing[0]!.version;
+
+    await stack.http.writeOk(
+      TenantHandlers.update,
+      {
+        id: tenantId,
+        version: currentVersion,
+        changes: { name: "Test Tenant Two — Renamed" },
+      },
+      sysadmin,
+    );
+
+    const rows = await stack.db
+      .select()
+      .from(tierAssignmentTable)
+      .where(eq(tierAssignmentTable["tenantId"], tenantId));
+    expect(rows.length).toBe(1);
+  });
+});

package/src/tier-engine/feature.ts

@@ -253,12 +253,22 @@ export function createTierEngineFeature<
           if (!ctx.db) return;
 
           // ctx.db ist im inTransaction-phase eine TenantDb (tenant-scoped
-          // proxy auf die echte TX). Für event-store-reads (cross-tenant
-          // stream-lookup via aggregate-id) brauchen wir die rohe TX —
-          // TenantDb wrapped die echte DbConnection, der select-call
-          // funktioniert structural identisch. Cast als DbConnection ist
-          // boundary-cast für event-store-API, kein narrowing-escape.
-          const rawDb = ctx.db as DbConnection;
+          // proxy auf die echte TX). Für event-store-Pfade brauchen wir
+          // die rohe DbConnection — TenantDb exposes nur select/insert/
+          // update/delete, NICHT execute (event-store-append.ts:102 ruft
+          // db.execute(sql`SELECT pg_notify(...)`) → TypeError sonst).
+          // Pattern matched signup-confirm.write.ts:107 (.raw), nicht
+          // `as DbConnection` — das ist Type-Lie der erst beim ersten
+          // .execute()-Call crashed.
+          //
+          // AppContext.db ist union (DbConnection | TenantDb). Im
+          // inTransaction-phase garantiert TenantDb — der dispatcher
+          // wrapped vorher (siehe pipeline/dispatcher.ts createTenantDb-
+          // Aufruf). TypeGuard via `"raw" in ...` ist robuster als
+          // `as TenantDb` gegen future refactor.
+          // skip: defensive — sollte im inTransaction nie greifen.
+          if (!("raw" in ctx.db)) return;
+          const rawDb = ctx.db.raw as DbConnection;
 
           // Idempotency: stream-existence-check vor create. Pattern aus
           // seedTenant.ts. Bei re-replay (rebuild) nicht versionsbumpen.

package/src/user/__tests__/user-status.test.ts

@@ -0,0 +1,39 @@
+// Drift-Guard fuer USER_STATUS (S2.D2.5 N1).
+//
+// Plus: USER_STATUS_OPTIONS wird nicht direkt exportiert (private im
+// schema/user.ts), wird aber via createSelectField in der Entity
+// referenziert. Wenn USER_STATUS-Object erweitert wird ohne dass das
+// Tuple synchron mitwaechst, faengt der Test es ab — entity.fields.status
+// liefert die options-Liste.
+
+import { describe, expect, test } from "vitest";
+import { USER_STATUS, userEntity } from "../schema/user";
+
+describe("USER_STATUS — Drift-Guard (S2.D2.5 N1)", () => {
+  test("Snapshot-Vergleich: USER_STATUS-Object und entity.fields.status.options synchron", () => {
+    const objectValues = Object.values(USER_STATUS).sort();
+    // entity.fields.status ist createSelectField — options ist die Tuple
+    const statusField = userEntity.fields["status"] as { options: readonly string[] };
+    const optionValues = [...statusField.options].sort();
+
+    expect(optionValues).toEqual(objectValues);
+  });
+
+  test("USER_STATUS-Snapshot — explizit zu updaten bei Aenderungen", () => {
+    expect(USER_STATUS).toMatchInlineSnapshot(`
+      {
+        "Active": "active",
+        "Deleted": "deleted",
+        "DeletionRequested": "deletionRequested",
+        "Restricted": "restricted",
+      }
+    `);
+  });
+
+  test("USER_STATUS-Werte sind camelCase (Convention fuer status-Strings)", () => {
+    // Erwartung: alle Werte starten mit lowercase und enthalten kein Leerzeichen
+    for (const value of Object.values(USER_STATUS)) {
+      expect(value).toMatch(/^[a-z][a-zA-Z]*$/);
+    }
+  });
+});

package/src/user/index.ts

@@ -1,4 +1,14 @@
 export { UserCommandSchemas } from "./command-schemas";
 export { USER_FEATURE, UserErrors, UserHandlers, UserQueries } from "./constants";
 export { createUserFeature } from "./feature";
-export { userEntity, userTable } from "./schema/user";
+export type { UserStatus } from "./schema/user";
+export {
+  USER_ANONYMIZED_DISPLAY_NAME,
+  USER_ANONYMIZED_EMAIL_DOMAIN,
+  USER_ANONYMIZED_EMAIL_PREFIX,
+  USER_DELETED_DISPLAY_NAME,
+  USER_DELETED_EMAIL_PREFIX,
+  USER_STATUS,
+  userEntity,
+  userTable,
+} from "./schema/user";

package/src/user/schema/user.ts

@@ -3,9 +3,54 @@ import {
   access,
   createBooleanField,
   createEntity,
+  createSelectField,
   createTextField,
+  createTimestampField,
 } from "@cosmicdrift/kumiko-framework/engine";
 
+/**
+ * User-Lifecycle-Status (S2.U1). Single source of truth — Auth-Middleware
+ * (S2.U6), Forget-Job (S2.U5) und Restriction-Handler nutzen diese
+ * Constants statt Magic-Strings (Memory feedback_role_naming_drift —
+ * gleiches Pattern wie ROLES.SystemAdmin).
+ */
+export const USER_STATUS = {
+  Active: "active",
+  Restricted: "restricted",
+  DeletionRequested: "deletionRequested",
+  Deleted: "deleted",
+} as const;
+
+export type UserStatus = (typeof USER_STATUS)[keyof typeof USER_STATUS];
+
+/**
+ * Anonymize-Display-Strings fuer userDeleteHook (S2.H1). Constants statt
+ * Magic-Strings damit i18n-Mapping moeglich + drift-fest. Default-DE,
+ * App-Author kann via i18n-System uebersetzen wenn gewuenscht.
+ */
+export const USER_DELETED_DISPLAY_NAME = "[Geloescht]";
+export const USER_ANONYMIZED_DISPLAY_NAME = "[Anonymisiert]";
+
+/**
+ * Email-Pseudonyme nach Forget. `<prefix>-<userId>@anonymized.invalid`
+ * — der userId-Suffix ist als Pseudo-Audit-Marker fuer Operator
+ * (Tracing-fall) erlaubt; user-id selbst ist UUID, kein PII.
+ * `.invalid`-TLD ist RFC2606-reserviert — niemals deliverbare Email.
+ */
+export const USER_DELETED_EMAIL_PREFIX = "deleted";
+export const USER_ANONYMIZED_EMAIL_PREFIX = "anonymized";
+export const USER_ANONYMIZED_EMAIL_DOMAIN = "anonymized.invalid";
+
+// Tuple form fuer createSelectField (erfordert non-empty readonly tuple).
+// Object.values(USER_STATUS) waere string[] — statisches Tuple ist
+// type-sicher.
+const USER_STATUS_OPTIONS = [
+  USER_STATUS.Active,
+  USER_STATUS.Restricted,
+  USER_STATUS.DeletionRequested,
+  USER_STATUS.Deleted,
+] as const;
+
 // User entity — tenant-agnostic. A single user can belong to multiple tenants
 // via tenantMemberships. No tenantId column on this table.
 export const userEntity = createEntity({
@@ -63,6 +108,37 @@ export const userEntity = createEntity({
       default: "[]",
       access: { write: access.privileged },
     }),
+
+    // S2.U1: User-Lifecycle-Status für user-data-rights (Sprint 2).
+    //   - "active":            Normaler State, alle Operationen erlaubt
+    //   - "restricted":        Art. 18 Restriction — Auth-Middleware blockiert
+    //                          Schreib-Endpoints, Read bleibt erlaubt damit
+    //                          User das Banner sieht + lift-restriction klicken kann
+    //   - "deletionRequested": delete-account aufgerufen, gracePeriodEnd
+    //                          gesetzt, User kann via cancel-deletion zurueck
+    //                          auf "active". Auth-Middleware blockiert wie
+    //                          "restricted".
+    //   - "deleted":           Forget executed nach Grace, Row anonymisiert via
+    //                          softDelete. Auth-Middleware blockt Login.
+    //
+    // Schreibrecht privileged: nur die request-deletion / restrict / lift /
+    // execute-forget-Handler (alle SYSTEM-context) duerfen status flippen.
+    status: createSelectField({
+      required: true,
+      default: USER_STATUS.Active,
+      options: USER_STATUS_OPTIONS,
+      access: { write: access.privileged },
+    }),
+
+    // Wann darf der pending-Forget tatsaechlich ausgefuehrt werden?
+    // Cron-Job in user-data-rights checkt taeglich gracePeriodEnd < now()
+    // und triggert dann die EXT_USER_DATA-Hooks. NULL solange kein
+    // Forget pending — wird beim delete-account-Call gesetzt
+    // (= now() + Compliance-Profile.userRights.gracePeriod), beim
+    // cancel-deletion zurueckgesetzt.
+    gracePeriodEnd: createTimestampField({
+      access: { write: access.privileged },
+    }),
   },
 });
 

package/src/user-data-rights/COMPLIANCE.md

@@ -0,0 +1,182 @@
+# 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?token=…` | Anonym (Magic-Link-Pfad) | Token-Hash-Lookup → 302-Redirect auf signed Storage-URL. 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 |
+
+---
+
+## 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/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.ts` | Cross-User-Isolation, Account-weite Sicht, eventType-Filter, Admin-only operator-query, download-attempt 90d-retention |
+| `cross-data-matrix.integration.ts` | 3-Provider-Pipeline (user + fileRef + custom-domain), Cross-Tenant Forget mit user-anonymize, Other-User-Isolation |
+| `download.integration.ts` | HTTP-e2e via `r.httpRoute`: Magic-Link, multi-use, expired, failed-job, storage-cleared, cross-tenant-same-user, malicious-filename |
+| `request-export.integration.ts` | Idempotency, active-job-constraint, cross-tenant-anyMember-userId-pattern |
+| `request-deletion-callback.integration.ts` + `request-cancel-deletion.integration.ts` | Grace + Cancel-Pfad + Email-Callback best-effort |
+| `restriction-flow.integration.ts` | Status-Flip + Auth-Middleware-Block + Lift |
+| `run-{export-jobs,forget-cleanup,user-export}.integration.ts` | Worker-Logic + Idempotency + Email-Callbacks |
+| `policy-to-strategy.test.ts` | Retention.strategy → UserDataDeleteStrategy mapping |
+| `user-data-rights.integration.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.