@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.387.0

package/dist/user-data-rights/schema/download-attempt.js

@@ -1,9 +1,9 @@
 import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import { createEntity, createTextField, 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",
@@ -23,11 +23,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.
@@ -43,10 +43,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" },
 });
 export const downloadAttemptsTable = buildEntityTable("downloadAttempt", downloadAttemptEntity);

package/dist/user-data-rights/schema/download-token.js

@@ -1,40 +1,39 @@
 import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import { createBigIntField, createEntity, createTextField, 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,
@@ -48,22 +47,21 @@ export const exportDownloadTokenEntity = createEntity({
             personal: false,
             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
         // unusual activity ("token was used from 5 different IPs"). Plain
@@ -83,11 +81,9 @@ export const exportDownloadTokenEntity = createEntity({
             reason: "is_business_data",
         }),
     },
-    // 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/dist/user-data-rights/schema/export-job.d.ts

@@ -6,10 +6,10 @@ export declare 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 declare const ACTIVE_JOB_CONSTRAINT = "read_export_jobs_one_active_per_user";
 export declare const exportJobEntity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{

package/dist/user-data-rights/schema/export-job.js

@@ -1,18 +1,17 @@
 import { buildEntityTable, sql } from "@cosmicdrift/kumiko-framework/db";
 import { createBigIntField, createEntity, createLongTextField, createSelectField, createTextField, 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",
@@ -20,10 +19,10 @@ export const EXPORT_JOB_STATUS = {
     Failed: "failed",
 };
 /**
- * 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";
 const EXPORT_JOB_STATUS_OPTIONS = [
@@ -35,46 +34,45 @@ 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",
     description: "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,
             personal: false,
             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,
@@ -85,36 +83,36 @@ export const exportJobEntity = createEntity({
             default: EXPORT_JOB_STATUS.Pending,
             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
         // traces can run several KB. `reason: "is_business_data"` because
@@ -123,19 +121,19 @@ export const exportJobEntity = createEntity({
             personal: false,
             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/dist/user-data-rights/token-helpers.d.ts

@@ -1,19 +1,18 @@
 /**
- * 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 declare function generateDownloadToken(): Promise<{
     readonly plain: string;
     readonly hash: string;
 }>;
 /**
- * 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 declare function hashDownloadToken(plain: string): Promise<string>;

package/dist/user-data-rights/token-helpers.js

@@ -1,29 +1,26 @@
-// 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() {
     const randomBytes = crypto.getRandomValues(new Uint8Array(32));
@@ -32,11 +29,10 @@ export async function generateDownloadToken() {
     return { plain, hash };
 }
 /**
- * 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) {
     const encoded = new TextEncoder().encode(plain);
@@ -44,7 +40,7 @@ export async function hashDownloadToken(plain) {
     return uint8ArrayToHex(new Uint8Array(digest));
 }
 function uint8ArrayToBase64Url(bytes) {
-    // 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]); // @cast-boundary dynamic-key

package/dist/user-data-rights/web/client-plugin.d.ts

@@ -2,12 +2,12 @@ import { type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
 import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer/web";
 import { 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;
 };
 export declare function userDataRightsClient(options?: UserDataRightsClientOptions): ClientFeatureDefinition;

package/dist/user-data-rights/web/client-plugin.js

@@ -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

package/dist/user-data-rights/web/confirm-deletion-screen.js

@@ -1,10 +1,11 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-// 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";
 import { useState } from "react";

package/dist/user-data-rights/web/constants.js

@@ -13,7 +13,7 @@ export const PRIVACY_CENTER_SCREEN_ID = "privacy-center";
 // compliance-profiles' COMPLIANCE_PROFILE_CATALOG_EXTENSION_NAME.
 export const EXPORT_SECTION_EXTENSION_NAME = "UserDataRightsExportSection";
 // 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 = "userDataRights.privacyCenter.field.status.option.";

package/dist/user-data-rights/web/index.js

@@ -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 { userDataRightsClient } from "./client-plugin.js";
 export { ConfirmAccountDeletionScreen } from "./confirm-deletion-screen.js";
 export { defaultTranslations } from "./default-translations.js";