@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

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

@@ -5,10 +5,10 @@ import {
   createTimestampField,
 } from "@cosmicdrift/kumiko-framework/engine";
 
-// Audit-Trail invalid Download-Attempts (S2.U7).
-// Schreibt eine Row pro 4xx im download-by-{token,job}-Pfad. DPO erkennt
-// damit Brute-Force / Anomalien (gleiche IP, viele invalid-Versuche).
-// Success-Downloads landen in download-token.lastUsedAt — nicht hier.
+// Audit trail for rejected download attempts.
+// Writes one row per 4xx response on the download-by-{token,job} path, allowing the DPO
+// to detect brute-force probing and anomalies such as many invalid attempts from one IP.
+// Successful downloads are recorded in download-token.lastUsedAt instead.
 export const downloadAttemptEntity = createEntity({
   table: "read_download_attempts",
   idType: "uuid",
@@ -29,11 +29,11 @@ export const downloadAttemptEntity = createEntity({
       personal: false,
       reason: "technical_reference",
     }),
-    // Token-Hash (token-Pfad) oder NULL (job-Pfad / unbekannter Token).
+    // Token hash for the token path, or NULL for the job path or an unknown token.
     tokenHash: createTextField({ maxLength: 64, personal: false, reason: "technical_reference" }),
-    // Job-ID wenn der attempt einen kannte. NULL bei unbekanntem Token.
+    // Job ID when the attempt identified one; NULL for an unknown token.
     jobId: createTextField({ personal: false, reason: "technical_reference" }),
-    // User-ID wenn auth-Pfad (job). NULL bei anonymous (token-Pfad).
+    // User ID for the authenticated job path; NULL for anonymous token-path requests.
     attemptedByUserId: createTextField({ personal: false, reason: "pseudonymous_fk" }),
     // The anonymous token path has no owner, so those rows fall back to the tenant key;
     // find "exact" on ip because list-download-attempts filters by IP.
@@ -49,10 +49,10 @@ export const downloadAttemptEntity = createEntity({
     }),
     attemptedAt: createTimestampField({ required: true }),
   },
-  // 90d hardDelete: unbounded growth = disk-bomb genau gegen das System
-  // das den Brute-Force erkennen soll. Brute-Force-Patterns sind kurzfristig
-  // (Stunden bis Tage) — 90d Window deckt forensik-Reviews + DPO-quartal-
-  // Audits. Tenant kann via override verlängern (HR-Compliance).
+  // 90d hardDelete: unbounded growth would create a disk bomb targeting the system
+  // that detects brute-force activity. Brute-force patterns are short-lived (hours to days),
+  // while a 90d window covers forensic reviews and quarterly DPO audits.
+  // The tenant can extend retention through an override for HR compliance.
   retention: { keepFor: "90d", strategy: "hardDelete", reference: "attemptedAt" },
 });
 

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

@@ -6,43 +6,42 @@ import {
   createTimestampField,
 } from "@cosmicdrift/kumiko-framework/engine";
 
-// Export-Download-Token (S2.U3 Atom 4a).
+// Export-Download-Token.
 //
-// Sicherheits-Token fuer den Download-Endpoint (Atom 4b). Pattern:
-//   1. Worker generiert plain-Token (32 byte random base64url) +
-//      Hash (SHA256 hex) beim Flip auf done.
-//   2. crud.create(downloadTokenEntity, ...) emittiert
-//      `exportDownloadToken.created`-Event in den event-store. DB-Row
-//      wird via Projection synchron geschrieben (Marten-Pattern, NICHT
-//      direct-INSERT). Memory `feedback_event_store_tenant_consistency`.
-//   3. Plain bleibt im Worker-Memory + wird via RunExportJobsResult an
-//      Atom 5 (Notification) weitergegeben. NIEMALS plain in DB.
-//   4. Atom 4b's Download-Endpoint: hashed incoming-Token + sucht den
-//      Hash-Eintrag. Konstanter-Zeit-Vergleich gegen timing-attacks.
+// Security token for the download endpoint. Pattern:
+//   1. Worker generates a plain token (32 random bytes, base64url) +
+//      hash (SHA256 hex) when flipping to done.
+//   2. crud.create(downloadTokenEntity, ...) emits
+//      `exportDownloadToken.created`-Event in the event store. The DB row
+//      is written synchronously via the projection (Marten pattern, NOT
+//      direct INSERT).
+//   3. Plain token remains in worker memory + is passed via
+//      RunExportJobsResult to the notification flow. NEVER plain in DB.
+//   4. The download endpoint hashes the incoming token + looks up the
+//      hash entry. Constant-time comparison against timing attacks.
 //
-// **Multi-use within TTL** (Plan-Decision 4a): Token wird beim Download
-// nicht "consumed". Mehrfach-Download bis expiresAt erlaubt — UX bei
-// Connection-Abbrueche, kein Re-Export-Zwang. Pattern matched Google-
-// Takeout (7d) + Facebook-Data-Download (4d).
+// **Multi-use within TTL**: Token is not "consumed" on download.
+// Multiple downloads until expiresAt are allowed — better UX for connection
+// interruptions, no forced re-export. Pattern matches Google Takeout (7d)
+// + Facebook Data Download (4d).
 //
-// **TTL = job.expiresAt** (denormalized, gleicher Wert wie Job-Row).
-// Storage-Cleanup-Pass nullt downloadStorageKey nach
-// expiresAt + exportStorageCleanupGraceHours. Token-Row bleibt liegen
-// (Audit-Trail) — Atom 4b's Download-Endpoint check't job.downloadStorageKey
-// != null vor Streaming + returns 410 Gone wenn Storage cleared.
+// **TTL = job.expiresAt** (denormalized, same value as the job row).
+// Storage cleanup nulls downloadStorageKey after
+// expiresAt + exportStorageCleanupGraceHours. The token row remains
+// (audit trail) — the download endpoint checks job.downloadStorageKey
+// != null before streaming + returns 410 Gone when storage is cleared.
 //
-// **idType: "uuid"** matched ExportJob — Token-IDs reisen ueber
-// Process-Grenzen (audit-events fuer DPO, ggf. Re-Issue-Pfade).
+// **idType: "uuid"** matches ExportJob — token IDs cross process
+// boundaries (audit events for the DPO, possible re-issue paths).
 
 export const exportDownloadTokenEntity = createEntity({
   table: "read_export_download_tokens",
   idType: "uuid",
 
   fields: {
-    // FK auf export-jobs. UNIQUE (siehe indexes) — 1 Token pro Job.
-    // Audit-Trail-Argument: separate Token-Row statt Job-Spalten weil
-    // Audit-Felder (lastUsedAt/IP/UA) semantisch zum Token, nicht zum
-    // Job gehoeren.
+    // Foreign key to export jobs. UNIQUE (see indexes) enforces one token per
+    // job. A separate token row keeps token-specific audit fields
+    // (`lastUsedAt`/IP/UA) separate from the job.
     jobId: createTextField({
       required: true,
       personal: false,
@@ -58,25 +57,24 @@ export const exportDownloadTokenEntity = createEntity({
       reason: "technical_reference",
     }),
 
-    // Wann wurde das Token ausgegeben (= Job-Done-Flip-Zeit).
+    // The time the token was issued, when the job was marked done.
     issuedAt: createTimestampField({
       required: true,
     }),
 
-    // Wann laeuft das Token ab. Identisch zu job.expiresAt
-    // (denormalized — Worker setzt beide gleich beim Done-Flip).
+    // The token expires at the same time as `job.expiresAt`; the worker sets both
+    // values when marking the job done.
     expiresAt: createTimestampField({
       required: true,
     }),
 
-    // Audit: wann wurde das Token zuletzt fuer einen Download genutzt.
-    // NULL solange noch nie heruntergeladen. Atom 4b's Download-Endpoint
-    // setzt es bei jedem successful Stream.
+    // Audit timestamp for the most recent download. NULL means the token has
+    // never been downloaded; the endpoint updates it after each successful
+    // stream.
     lastUsedAt: createTimestampField({}),
 
-    // Audit: Anzahl der Downloads. Atom 4b incrementiert bei jedem
-    // Stream. bigInt fuer fall einer pathologischer Re-Download-Schleife
-    // (z.B. broken Sync-Tool).
+    // Audit count of downloads. `bigInt` accommodates pathological re-download
+    // loops, such as those caused by a broken sync tool.
     useCount: createBigIntField({}),
 
     // Audit: source IP of the last download. Helps the DPO investigate
@@ -99,11 +97,9 @@ export const exportDownloadTokenEntity = createEntity({
     }),
   },
 
-  // 1 Token pro Job. UNIQUE auf jobId — Backstop fuer Worker-Idempotency
-  // (Atom 3b's "2× run done-Job → no-op"). Der Worker created NIE ein
-  // zweites Aggregat fuers gleiche jobId: Re-Runs rotieren das Token
-  // in place via update (fw#832) — sonst kollidiert der Projection-
-  // Rebuild an genau diesem Index.
+  // UNIQUE on `jobId` provides an idempotency backstop: rerunning a completed
+  // job must not create a second token aggregate. Re-runs update the existing
+  // token in place; otherwise projection rebuilds would collide on this index.
   indexes: [
     {
       unique: true,

package/packages/bundled-features/src/user-data-rights/schema/export-job.ts

@@ -8,19 +8,18 @@ import {
   createTimestampField,
 } from "@cosmicdrift/kumiko-framework/engine";
 
-// Export-Job-Lifecycle (S2.U3+U4 Atom 1).
+// Export-job lifecycle.
 //
-// Spec: docs/plans/architecture/user-data-rights.md "Async Export-Pipeline".
-// User triggert `request-export` → ExportJob (status="pending"). Worker
-// pickt auf → "running" → erfolgreich "done" + downloadStorageKey gesetzt
+// User triggers `request-export` → ExportJob (status="pending"). The worker
+// picks it up → "running" → on success, "done" + downloadStorageKey set
 // + expiresAt = completedAt + compliance-profile.userRights.exportDownloadTtl
-// (per-Tenant-konfigurierbar via Override, Default 7 Tage). Bei Throw
-// oder Stale-Timeout → "failed" mit errorMessage. Stale-Timeout +
-// Storage-Cleanup-Grace ebenfalls aus dem compliance-profile.
+// (configurable per tenant via override, default 7 days). On throw or stale
+// timeout → "failed" with errorMessage. Stale timeout and storage-cleanup
+// grace are also read from the compliance profile.
 //
-// Status-Werte als Constants — Single source of truth fuer Worker,
-// Application-Code (request-export-Handler), UI-Banner (Polling) und
-// Drift-Guard im Test.
+// Status values are constants—the single source of truth for the worker,
+// application code (`request-export` handler), UI polling banner, and test
+// drift guard.
 export const EXPORT_JOB_STATUS = {
   Pending: "pending",
   Running: "running",
@@ -31,10 +30,10 @@ export const EXPORT_JOB_STATUS = {
 export type ExportJobStatus = (typeof EXPORT_JOB_STATUS)[keyof typeof EXPORT_JOB_STATUS];
 
 /**
- * DB-Constraint-Name fuer den Partial-UNIQUE-Index (1 aktiver Job pro
- * User). Single source of truth — request-export.write catched 23505
- * mit diesem Namen als Race-Schutz, Tests pinnen ihn als
- * `expectUniqueViolation`-Argument. Rename hier propagiert automatisch.
+ * Database constraint name for the partial UNIQUE index (one active job per
+ * user). This is the single source of truth: request-export.write catches
+ * 23505 with this name as race protection, and tests pin it as the
+ * `expectUniqueViolation` argument. Renaming it propagates automatically.
  */
 export const ACTIVE_JOB_CONSTRAINT = "read_export_jobs_one_active_per_user";
 
@@ -48,17 +47,16 @@ const EXPORT_JOB_STATUS_OPTIONS = [
 // **Tenant-agnostic** like userTable — one job per userId across all
 // memberships; the worker iterates cross-tenant via ctx.db.unsafeRaw (same pattern as runForgetCleanup).
 //
-// **Idempotency:** Partial-UNIQUE-Index auf `(userId)` WHERE
-// `status IN ('pending', 'running')`. User mit pending-Job kann keinen
-// zweiten parallelen Job starten — der Insert faellt mit Constraint-
-// Violation auf, der request-export-Handler (Atom 2) faengt das ab und
-// returnt den existing pending-Job (Insert-or-Return). Race-Window
-// null. Done/Failed-Jobs koennen beliebig viele pro User existieren
-// (Audit-Historie).
+// **Idempotency:** Partial UNIQUE index on `(userId)` WHERE
+// `status IN ('pending', 'running')`. A user with a pending job cannot start
+// a second parallel job—the insert fails with a constraint violation, which
+// the request-export handler catches and uses to return the existing pending
+// job (insert-or-return). This closes the race window. Done/failed jobs can
+// be retained indefinitely per user for audit history.
 //
-// **idType: "uuid"** — Job-IDs reisen ueber Process-Grenzen
-// (BullMQ-Payload, Job-Run-Logger, Audit-Events fuer DPO). Serial-IDs
-// sind nur prozess-lokal verlaesslich, UUIDs cross-process stabil.
+// **idType: "uuid"** — job IDs cross process boundaries (BullMQ payloads,
+// job-run logger, and audit events for the DPO). Serial IDs are only reliable
+// within one process; UUIDs remain stable across processes.
 export const exportJobEntity = createEntity({
   table: "read_export_jobs",
   idType: "uuid",
@@ -66,11 +64,11 @@ export const exportJobEntity = createEntity({
     "One user's GDPR Art. 20 data-export request and its lifecycle: who asked, from which tenant, the pending/running/done/failed status, the timestamps, the download storage key and expiry, and any error the export worker hit.",
 
   fields: {
-    // Tenant-agnostisch: Wert wird beim Schreiben gesetzt (Framework
-    // braucht eine tenant_id-Spalte), domain-mäßig ignoriert.
-    // Kein maxLength — folgt userTable.id + tenantMembershipsTable.userId
-    // (beide ohne maxLength). UserId-Form ist Plattform-Konzern, hier
-    // nur Storage.
+    // Tenant-agnostic: set when writing because the framework requires a
+    // tenant_id column, but ignored at the domain level.
+    // No maxLength — follows userTable.id and tenantMembershipsTable.userId
+    // (both have no maxLength). The userId shape is platform-wide; here it is
+    // only used for storage.
     userId: createTextField({
       required: true,
       searchable: true,
@@ -78,19 +76,19 @@ export const exportJobEntity = createEntity({
       reason: "pseudonymous_fk",
     }),
 
-    // **requestedFromTenantId** — der Tenant aus dem der User den Antrag
-    // gestellt hat. Persistierter Audit-Pfad fuer den Worker (welches
-    // Compliance-Profile gilt fuer Job-TTL/Stale/Cleanup) — DSGVO-
-    // konsistent: 1 User = 1 effektives Profile pro Antrag, nicht "wechselt
-    // mit jedem Cross-Tenant-Klick". Plan-Doc-Decision: Tenant aus 1. Klick
-    // (Option a). Spalte heisst nicht einfach "tenantId" damit kein
-    // Verwechseln mit der Framework-Auto-Spalte tenant_id.
+    // **requestedFromTenantId** — the tenant from which the user submitted the
+    // request. This persisted audit path tells the worker which compliance
+    // profile applies to the job TTL, stale timeout, and cleanup. This keeps
+    // one effective profile per request instead of changing with every
+    // cross-tenant click. The tenant is taken from the first click (option a).
+    // The column is not simply named "tenantId" to avoid confusion with the
+    // framework-generated tenant_id column.
     //
-    // **Atom 3b Worker-Hinweis:** Profile-Resolution muss ueber
-    // `requestedFromTenantId` laufen (`queryAs(systemUserOf(requestedFromTenantId),
-    // "compliance-profiles:query:for-tenant", {})`), NICHT ueber
-    // `executor.tenantId` — sonst kriegt ein Job-Pickup aus einem anderen
-    // Tenant-Context ein falsches Profile.
+    // **Worker note:** Profile resolution must use `requestedFromTenantId`
+    // (`queryAs(systemUserOf(requestedFromTenantId),
+    // "compliance-profiles:query:for-tenant", {})`), not
+    // `executor.tenantId`; otherwise a job picked up from another tenant
+    // context would use the wrong profile.
     requestedFromTenantId: createTextField({
       required: true,
       personal: false,
@@ -103,40 +101,40 @@ export const exportJobEntity = createEntity({
       options: EXPORT_JOB_STATUS_OPTIONS,
     }),
 
-    // Wann hat der User den Job angefordert. Required — kein Job-Row
-    // entsteht ohne Klick.
+    // When the user requested the job. Required because no job row exists
+    // without a request.
     requestedAt: createTimestampField({
       required: true,
       sortable: true,
     }),
 
-    // Wann hat der Worker mit dem Pickup angefangen. NULL solange
-    // `pending`. Stale-Detection nutzt das +
+    // When the worker began processing the job. NULL while `pending`.
+    // Stale detection uses this together with
     // compliance-profile.userRights.exportStaleTimeoutMinutes.
     startedAt: createTimestampField({}),
 
-    // Wann hat der Worker abgeschlossen (success oder fail). NULL
-    // solange running.
+    // When the worker completed the job, successfully or with failure. NULL
+    // while `running`.
     completedAt: createTimestampField({}),
 
-    // Storage-Key des fertigen ZIP-Files. NULL solange nicht `done`.
-    // Worker setzt das + die ZIP-Bytes via storage-provider.write(key).
-    // Dies ist KEIN signed-URL — der Download-Endpoint generiert den
-    // signed-URL on demand vom Storage-Provider (Atom 4).
+    // Storage key of the completed ZIP file. NULL until `done`.
+    // The worker sets this and writes the ZIP bytes via
+    // storage-provider.write(key).
+    // This is not a signed URL—the download endpoint generates the signed URL
+    // on demand through the storage provider.
     downloadStorageKey: createTextField({
       maxLength: 500,
       personal: false,
       reason: "technical_reference",
     }),
 
-    // Ab wann ist der Download nicht mehr abrufbar. Worker setzt
+    // When the download is no longer available. The worker sets
     // `completedAt + compliance-profile.userRights.exportDownloadTtl`
-    // beim Flip auf `done`. NULL fuer pending/running/failed.
+    // when switching to `done`. NULL for pending, running, and failed jobs.
     //
-    // Storage-Cleanup-Pflicht: Worker laesst nach
-    // `expiresAt + compliance-profile.userRights.exportStorageCleanupGraceHours`
-    // einen separaten Pass loeschen damit abgelaufene ZIPs nicht auf S3
-    // verbleiben.
+    // Storage cleanup requirement: after
+    // `expiresAt + compliance-profile.userRights.exportStorageCleanupGraceHours`,
+    // a separate pass deletes expired ZIPs so they do not remain on S3.
     expiresAt: createTimestampField({}),
 
     // Failed-state diagnostics. longText because hook errors with stack
@@ -147,20 +145,20 @@ export const exportJobEntity = createEntity({
       reason: "is_business_data",
     }),
 
-    // Audit-Info fuer Operator: wie gross war der Export. Hilft beim
-    // Capacity-Planning + erkennt pathologische Cases (Streaming-ZIP
-    // mit 5 GB Files schreibt mehrere Mrd Bytes, integer-Overflow waere
-    // silent + Audit-Drift).
+    // Audit information for operators: the export size. This supports capacity
+    // planning and detects pathological cases (a streaming ZIP containing 5 GB
+    // of files writes several billion bytes, so integer overflow would cause
+    // silent audit drift).
     //
-    // bigInt liefert JS-`number` Round-trip via mode:"number" — sicher
-    // bis 2^53 ≈ 9 PB, JSON-tauglich fuer das Status-Polling.
+    // bigInt provides a JS-`number` round trip via mode:"number", safe up to
+    // 2^53 ≈ 9 PB and suitable for JSON-based status polling.
     bytesWritten: createBigIntField({}),
   },
 
-  // Partial-UNIQUE-Index: nur 1 aktiver Job pro User, Done/Failed-
-  // Historie ist unbeschraenkt. request-export.write nutzt App-side-
-  // Pre-Check als primaeren Pfad + 23505-Catch dieser Constraint als
-  // Race-Schutz fuer das <1ms-Window zwischen fetchOne + crud.create.
+  // Partial UNIQUE index: only one active job per user; done/failed history
+  // is unlimited. request-export.write uses an application-side pre-check as
+  // the primary path and catches this constraint's 23505 as race protection
+  // for the <1ms window between fetchOne and crud.create.
   indexes: [
     {
       unique: true,

package/packages/bundled-features/src/user-data-rights/token-helpers.ts

@@ -1,30 +1,27 @@
-// Download-Token-Helper (S2.U3 Atom 4a).
+// Generates a cryptographically secure token to authorize the export ZIP download.
+// Follows the Magic-Link/Bearer-Token pattern with a hash stored in the database:
 //
-// Generiert ein kryptographisch-sicheres Token zur Authorisierung des
-// Export-ZIP-Downloads. Pattern matched Magic-Link/Bearer-Token mit DB-
-// gespeichertem Hash:
-//
-//   1. Worker generiert plain-Token (32 byte random base64url) + Hash
+//   1. The worker generates a plain token (32 random bytes, base64url) and its hash
 //      (SHA256 hex).
-//   2. DB speichert NUR den Hash. Plain bleibt im Worker-Memory.
-//   3. Atom 5 (Notification) versendet plain via Email an User.
-//   4. Atom 4b (Download-Endpoint) hashet incoming-Token + vergleicht
-//      mit DB-Hash → konstantes-Zeit-Vergleich gegen timing-attacks.
+//   2. The database stores ONLY the hash. The plain token remains in worker memory.
+//   3. The notification step sends the plain token to the user by email.
+//   4. The download endpoint hashes the incoming token and compares it with the
+//      database hash using a constant-time comparison to prevent timing attacks.
 //
-// **Multi-use within TTL** (User-Choice 4a-Plan): Token wird NICHT
-// "consumed" beim Download — User kann mehrfach downloaden bis expiresAt.
-// Pattern matched Google-Takeout (7d) + Facebook-Data-Download (4d).
+// **Multi-use within TTL:** The token is NOT "consumed" on download, so the user
+// can download repeatedly until expiresAt. This matches Google-Takeout (7d) and
+// Facebook-Data-Download (4d).
 //
 // **Universal Web-Crypto API:** crypto.getRandomValues + crypto.subtle.digest
-// laeuft in Bun + Node 19+ + Browser identisch — keine plattform-
-// spezifischen Imports (Memory `feedback_universal_deps`).
+// runs identically in Bun, Node 19+, and browsers, avoiding platform-specific
+// imports.
 
 /**
- * Generiert ein neues Download-Token. plain wird dem User via Email
- * zugestellt (Atom 5); hash landet in der Token-DB-Row.
+ * Generates a new download token. The plain token is sent to the user by email;
+ * the hash is stored in the token database row.
  *
- * Token-Format: 32 byte random → base64url-encoded (~43 chars). URL-safe
- * fuer Magic-Link-Verwendung (kein +/= das URL-encoded werden muesste).
+ * Token format: 32 random bytes → base64url-encoded (~43 chars). URL-safe for
+ * Magic-Link use (no +/= characters that would need to be URL-encoded).
  */
 export async function generateDownloadToken(): Promise<{
   readonly plain: string;
@@ -37,11 +34,10 @@ export async function generateDownloadToken(): Promise<{
 }
 
 /**
- * Hashed einen plain-Token zu seiner DB-Repraesentation. Verify-Pfad
- * (Atom 4b's Download-Endpoint): hashed incoming-Token + sucht den Hash
- * in DB. Konstante-Zeit-String-Vergleich verhindert timing-attacks
- * (das macht der Caller via `crypto.subtle`-vergleich oder secure-
- * compare-helper).
+ * Hashes a plain token into its database representation. In the verification path,
+ * the download endpoint hashes the incoming token and looks up the hash in the
+ * database. A constant-time string comparison prevents timing attacks; the caller
+ * performs it via `crypto.subtle` or a secure comparison helper.
  */
 export async function hashDownloadToken(plain: string): Promise<string> {
   const encoded = new TextEncoder().encode(plain);
@@ -50,7 +46,7 @@ export async function hashDownloadToken(plain: string): Promise<string> {
 }
 
 function uint8ArrayToBase64Url(bytes: Uint8Array): string {
-  // btoa erwartet binary-string. atob/btoa sind universal in Bun + Node + Browser.
+  // btoa expects a binary string. atob/btoa are universal in Bun, Node, and browsers.
   let binary = "";
   for (let i = 0; i < bytes.length; i++) {
     binary += String.fromCharCode(bytes[i] as number); // @cast-boundary dynamic-key

package/packages/bundled-features/src/user-data-rights/web/client-plugin.tsx

@@ -6,7 +6,7 @@
 // createKumikoApp({ clientFeatures: [userDataRightsClient()] }); the screen
 // has no own r.nav, the app places it via r.nav.
 //
-// fw#2312: the former `privacyCenter: { showDeletion }` option is gone — a
+// The former `privacyCenter: { showDeletion }` option is gone — a
 // declarative screen is now registered server-side once for all apps, so a
 // client prop can no longer toggle its sections/actions per app. Its
 // replacement is the server-side
@@ -22,12 +22,12 @@ import { ExportSection } from "./privacy-center-screen.tsx";
 import { makePublicDeletionGate, type PublicDeletionRoutes } from "./public-deletion-gate.tsx";
 
 export type UserDataRightsClientOptions = {
-  /** Key-weise Overrides über die Default-Bundles (de/en). */
+  /** Overrides merged into the default bundles (de/en). */
   readonly translations?: TranslationsByLocale;
-  /** Wenn gesetzt: registriert die anonymen (login-freien) Lösch-Screens als
-   *  Gate auf den angegebenen Pfaden. Weglassen → nur der eingeloggte
-   *  privacy-center-Screen. Den Client VOR dem Auth-Client listen, sonst
-   *  landet der anonyme Besucher auf der Login-Maske. */
+  /** When set, registers the anonymous (login-free) deletion screens as a
+   *  gate on the specified paths. If omitted, only the authenticated
+   *  privacy-center screen is available. Register this client BEFORE the auth
+   *  client; otherwise, anonymous visitors are redirected to the login screen. */
   readonly publicDeletion?: PublicDeletionRoutes;
 };
 

package/packages/bundled-features/src/user-data-rights/web/confirm-deletion-screen.tsx

@@ -1,9 +1,10 @@
-// ConfirmAccountDeletionScreen — anonymer Apex-Screen Schritt 2. Liest das
-// Token aus dem URL-Fragment (`#token=…`, nie an den Server gesendet — landet
-// so nicht in Proxy-/Access-Logs, fw#1554) und dispatcht beim Bestätigen
-// user-data-rights:write:confirm-deletion-by-token → startet die Grace-Period.
+// ConfirmAccountDeletionScreen — anonymous Apex screen, step 2. Reads the
+// token from the URL fragment (`#token=…`, never sent to the server, so it does
+// not appear in proxy/access logs) and dispatches
+// user-data-rights:write:confirm-deletion-by-token on confirmation to start the
+// grace period.
 //
-// App mountet den Screen unter der deletionVerifyUrl-Route (z.B.
+// The app mounts this screen at the deletionVerifyUrl route (for example,
 // /delete-account/confirm) via createPublicSurface.
 
 import { useDispatcher, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";

package/packages/bundled-features/src/user-data-rights/web/constants.ts

@@ -17,7 +17,7 @@ export const PRIVACY_CENTER_SCREEN_ID = "privacy-center" as const;
 export const EXPORT_SECTION_EXTENSION_NAME = "UserDataRightsExportSection" as const;
 
 // enumOption keyPrefix for the privacy-center screen's `status` field
-// (fw#2315 pattern) — resolves the raw user-lifecycle enum value
+// pattern — resolves the raw user-lifecycle enum value
 // (active/restricted/deletionRequested/deleted) to a translated label
 // instead of showing the raw string.
 export const STATUS_OPTION_KEY_PREFIX =

package/packages/bundled-features/src/user-data-rights/web/index.ts

@@ -1,8 +1,8 @@
-// Public exports für die Browser-Seite des user-data-rights Features —
-// die anonymen Apex-Deletion-Screens. Konsumiert via Sub-Path-Export
-// `@cosmicdrift/kumiko-bundled-features/user-data-rights/web`. Die Server-
-// Seite (defineFeature, Handler) lebt unter `.../user-data-rights` und hat
-// keine React-/DOM-Deps.
+// Public exports for the browser side of the user-data-rights feature —
+// the anonymous Apex deletion screens. Consumed via the subpath export
+// `@cosmicdrift/kumiko-bundled-features/user-data-rights/web`. The server
+// side (defineFeature, Handler) lives under `.../user-data-rights` and has
+// no React/DOM dependencies.
 
 export { type UserDataRightsClientOptions, userDataRightsClient } from "./client-plugin.tsx";
 export type { ConfirmAccountDeletionScreenProps } from "./confirm-deletion-screen.tsx";

package/packages/bundled-features/src/user-data-rights/web/privacy-center-screen.tsx

@@ -1,6 +1,6 @@
 import { EMPTY_VALUE_PLACEHOLDER } from "@cosmicdrift/kumiko-renderer/headless";
 // Export section (Art. 20) — the one part of user-data-rights' privacy-center
-// screen that stays custom (fw#2312). Registered as an EditExtensionSection
+// screen that stays custom. Registered as an EditExtensionSection
 // component (see web/client-plugin.tsx); the projectionDetail screen
 // (feature.ts) supplies the surrounding Section chrome (title, testId), so
 // this component renders only its own body content.
@@ -26,9 +26,9 @@ import {
   UserDataRightsQueries,
 } from "./constants.ts";
 
-// Export-Job läuft async (worker-Lane-Cron, ~1 Min). Solange er pending/running
-// ist, pollt der Screen den Status, damit der Download ohne manuellen Reload
-// erscheint.
+// The export job runs asynchronously (worker-Lane-Cron, ~1 Min). While it is
+// pending/running, the screen polls its status so the download appears without
+// a manual reload.
 const EXPORT_POLL_MS = 4000;
 
 type ExportJob = {
@@ -47,15 +47,16 @@ type SectionStatus =
   | { kind: "success"; messageKey: string }
   | { kind: "error"; messageKey: string };
 
-// Dispatcher-Failures tragen i18nKey nur wenn der Handler einen setzt —
-// Boundary-Read mit generischem Fallback.
+// Dispatcher failures include i18nKey only when the handler sets one; read it
+// at the boundary with a generic fallback.
 function failureKey(error: unknown): string {
   const key = propertyOf(error, "i18nKey");
   return typeof key === "string" ? key : "userDataRights.privacyCenter.errors.generic";
 }
 
-// Roher ISO-Instant → nur der Datums-Teil ist relevant; reiner String-Slice,
-// kein Date-API (no-date-api-Guard) und universell. Leer/null → "—".
+// Only the date portion of the raw ISO instant is relevant; use a string slice
+// instead of the Date API (no-date-api-Guard) for universal support. Empty/null
+// values become "—".
 export function formatDate(iso: string | null | undefined): string {
   if (!iso) return EMPTY_VALUE_PLACEHOLDER;
   const tIndex = iso.indexOf("T");
@@ -97,10 +98,10 @@ export function ExportSection(): ReactNode {
     void statusQuery.refetch?.();
   };
 
-  // Download laeuft ueber den Dispatcher (traegt X-CSRF-Token) statt ueber
-  // eine <a>-Navigation: download-by-job liefert eine signed URL zurueck, auf
-  // die postWithDownload den Browser navigiert (content-disposition:
-  // attachment → laedt herunter).
+  // Download runs through the dispatcher (which supplies X-CSRF-Token) instead of
+  // an <a>-navigation: download-by-job returns a signed URL, which
+  // postWithDownload navigates the browser to (content-disposition:
+  // attachment → triggers a download).
   const downloadExport = async (jobId: string): Promise<void> => {
     const err = await postWithDownload(dispatcher, UserDataRightsQueries.downloadByJob, { jobId });
     if (err) setStatus({ kind: "error", messageKey: failureKey(err) });
@@ -116,7 +117,7 @@ export function ExportSection(): ReactNode {
 
   // While the job is running: poll until Done/Failed, then auto-stop.
   const refetch = statusQuery.refetch;
-  // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
+  // kumiko-lint-ignore no-raw-hooks not yet converted to the framework hook set
   useEffect(() => {
     if (!inProgress || !refetch) return;
     const id = setInterval(() => void refetch(), EXPORT_POLL_MS);