@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.388.0

package/dist/user-data-rights/feature.js

@@ -1,4 +1,4 @@
-// kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312 (feature.ts > 300 lines)
+// kumiko-lint-ignore app-feature-structure feature.ts is over 300 lines and not yet split
 import { UNKNOWN_CLIENT_IP } from "@cosmicdrift/kumiko-framework/api";
 import { createSystemConfig, createSystemUser, defineFeature, EXT_USER_DATA, i18nKey, SYSTEM_USER_ID, } from "@cosmicdrift/kumiko-framework/engine";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
@@ -61,16 +61,16 @@ export function createUserDataRightsFeature(opts = {}) {
         r.envSchema(deletionTokenSecretEnvSchema);
         r.usesApi("compliance.forTenant");
         r.usesApi("retention.policyFor");
-        // S2.U6 — restrict-account ruft sessions.revokeAllForUser cross-feature.
-        // r.usesApi sorgt fuer Boot-Validation: App ohne sessions-feature wirft
-        // beim Boot, statt erst beim ersten Restrict-Call ein opaque "handler
-        // not found" zu werfen.
+        // restrict-account calls sessions.revokeAllForUser across features.
+        // r.usesApi enables boot validation: without the sessions feature, the app
+        // fails at boot instead of raising an opaque "handler not found" error
+        // on the first restrict call.
         r.usesApi("sessions.revokeAllForUser");
-        // file-foundation ist soft-dep: nur der Export-Worker (Atom 3b)
-        // braucht ihn fuer Storage-Schreiben. Apps die nur Forget nutzen
-        // (kein Export) muessen file-foundation nicht mounten.
+        // file-foundation is a soft dependency: only the export worker needs it
+        // for storage writes. Apps that use only forget (not export) do not need
+        // to mount file-foundation.
         r.extendsRegistrar(EXT_USER_DATA, {});
-        // GDPR-storage guards V2+V3 (#1314) — moved off the framework-internal
+        // GDPR-storage guards V2+V3 — moved off the framework-internal
         // boot-validator onto this feature's own r.bootCheck(), since it's the
         // EXT_USER_DATA channel owner: any r.useExtension(EXT_USER_DATA, ...)
         // usage already requires user-data-rights to be mounted.
@@ -93,20 +93,20 @@ export function createUserDataRightsFeature(opts = {}) {
             options: ["single-user", "multi-user"],
             env: "TENANT_MODEL",
         }));
-        // S2.U3 Atom 1b — ExportJob-Lifecycle-Entity.
+        // ExportJob-Lifecycle-Entity.
         r.entity({ name: "export-job", ...exportJobEntity });
-        // S2.U3 Atom 4a — Download-Token-Entity. Worker generiert Token beim
-        // Flip auf done (siehe run-export-jobs.ts). Hash in DB, plain im
-        // RunExportJobsResult fuer Atom 5 (Notification per Email).
+        // The worker generates the token when flipping the job to done (see
+        // run-export-jobs.ts). The hash is stored in the database, while the plain
+        // token is kept in RunExportJobsResult for email notification.
         r.entity({ name: "export-download-token", ...exportDownloadTokenEntity });
-        // S2.U7 — Audit-Trail invalid Download-Attempts (DPO Brute-Force-Detection).
+        // Audit-Trail invalid Download-Attempts (DPO Brute-Force-Detection).
         r.entity({ name: "download-attempt", ...downloadAttemptEntity });
-        // S2.U6 — DSGVO Art. 18 Account-Freeze (Verarbeitungs-Pause).
-        // Endpoints fuer Restrict + Lift. Login-Block fuer Restricted Users
-        // lebt in auth-email-password/login.write.ts.
+        // GDPR Article 18 account freeze (pause processing).
+        // The endpoints restrict and lift the restriction. The login block for
+        // restricted users lives in auth-email-password/login.write.ts.
         r.writeHandler(restrictAccountWrite);
         r.writeHandler(liftRestrictionWrite);
-        // S2.U5a — Endpoints fuer DSGVO Art. 17 Forget-Pfad mit Grace.
+        // Endpoints for the GDPR Article 17 forget path with a grace period.
         r.writeHandler(createRequestDeletionHandler({
             ...(opts.sendDeletionRequestedEmail && {
                 sendDeletionRequestedEmail: opts.sendDeletionRequestedEmail,
@@ -129,26 +129,26 @@ export function createUserDataRightsFeature(opts = {}) {
         r.writeHandler(createConfirmDeletionByTokenHandler(opts.deletionTokenSecret !== undefined
             ? { deletionTokenSecret: opts.deletionTokenSecret }
             : {}));
-        // S2.U5b — Cleanup-Runner als privileged-Handler. Atom 5b: Wenn
-        // sendDeletionExecutedEmail gesetzt, reicht der Handler den Callback
-        // an runForgetCleanup weiter (Worker cached userEmail+tenantIds
-        // PRE-tx, siehe run-forget-cleanup.ts).
+        // Cleanup runner as a privileged handler. When
+        // sendDeletionExecutedEmail is set, the handler passes the callback to
+        // runForgetCleanup; the worker caches userEmail+tenantIds before the
+        // transaction (see run-forget-cleanup.ts).
         r.writeHandler(createRunForgetCleanupHandler(opts.sendDeletionExecutedEmail
             ? { sendDeletionExecutedEmail: opts.sendDeletionExecutedEmail }
             : {}));
         r.exposesApi("userDataRights.runForget");
-        // S2.U3 Atom 2 — User-Touchpoints fuer Async Export-Pipeline.
+        // User touchpoints for the asynchronous export pipeline.
         r.writeHandler(requestExportWrite);
         r.queryHandler(exportStatusQuery);
         r.exposesApi("userDataRights.runExport");
-        // S2.U3 Atom 4b — Download-Endpoints (Token-Pfad + Session-Pfad).
-        // Beide query-handlers verifizieren Token/Session, holen signed-URL
-        // vom Storage-Provider, und persistieren Audit-Felder am Token-Row.
-        // r.httpRoute-Wrapper unten machen den 302-Redirect zu signedUrl.
+        // Download endpoints for token and session paths.
+        // Both query handlers verify the token or session, obtain a signed URL
+        // from the storage provider, and persist audit fields on the token row.
+        // The r.httpRoute wrappers below issue the 302 redirect to signedUrl.
         r.queryHandler(downloadByTokenQuery);
         r.queryHandler(downloadByJobQuery);
-        // S2.U7 — User-Selbstauskunft (Art. 15) + Operator-Sicht auf
-        // invalid Download-Attempts (DPO).
+        // User self-access under Article 15 and operator access to invalid download
+        // attempts (DPO).
         r.queryHandler(myAuditLogQuery);
         r.queryHandler(listDownloadAttemptsQuery);
         // Read-only GDPR operator inspector (SystemAdmin) — screens stay inert until an app navs them.
@@ -306,12 +306,12 @@ export function createUserDataRightsFeature(opts = {}) {
         // Magic-link path (anonymous): the email link carries the token as a
         // URL fragment (`#token=<plain>`) instead of a query param — fragments
         // never leave the browser, so they never hit proxy/access logs
-        // (issue #1271). This route only serves the interstitial page; the
+        // This route only serves the interstitial page; the
         // external script reads the fragment client-side and exchanges the
         // token via POST for the signed URL.
         //
-        // No `?token=` query fallback: framework is zero-legacy (#1512) — no
-        // live customer data / no pre-#1271 emails in flight that would need
+        // No `?token=` query fallback: framework is zero-legacy — no
+        // live customer data / no emails in flight that would need
         // bridging, so there's nothing a fallback would need to cover. A query
         // param reaches the server as part of the request URL and gets written
         // to proxy/access logs regardless of what the handler does with it
@@ -353,7 +353,7 @@ export function createUserDataRightsFeature(opts = {}) {
             },
         });
         // Exchange endpoint for the interstitial page: the token arrives here
-        // as a POST body instead of a query string (issue #1271). A dedicated
+        // as a POST body instead of a query string. A dedicated
         // route rather than letting the browser JS call /api/query directly,
         // for two reasons:
         //   1. IP/UA audit — extractAuditMeta needs the raw request headers and
@@ -391,7 +391,7 @@ export function createUserDataRightsFeature(opts = {}) {
                 // defaults to 0, ignoring headers entirely) nor a socket, so every
                 // fragment-POST download would fall to the shared "unknown" bucket,
                 // turning the per-user 30/min backstop into one global bucket an
-                // attacker can exhaust for everyone (#1307). Passing `clientIp`
+                // attacker can exhaust for everyone. Passing `clientIp`
                 // directly as env — the same server-resolved, trustedProxyHops-
                 // aware value the outer request already trusted — reaches
                 // extractSocketAddress() without going through header/hop-count
@@ -417,7 +417,7 @@ export function createUserDataRightsFeature(opts = {}) {
             unit: "seconds",
             description: "Unix timestamp of the last export storage-cleanup pass that completed. Alert on time() minus this value exceeding the cron interval plus a buffer; the backlog-age gauge alone stays at its last value when the cron stops.",
         });
-        // S2.U3 Atom 3b — Worker fuer Async Export-Pipeline. Cron-getriggert.
+        // Worker for the asynchronous export pipeline, triggered by a cron job.
         const RUN_EXPORT_JOBS_REASON = "processes pending export jobs across every tenant";
         r.job({
             name: "run-export-jobs",
@@ -429,9 +429,9 @@ export function createUserDataRightsFeature(opts = {}) {
                     throw new Error("run-export-jobs: ctx.registry required (JobContext incomplete)");
                 }
                 const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
-                // SYSTEM_USER_ID ist die framework-weite Konvention. Der job-
-                // Discriminator wird via handlerName="user-data-rights:run-export-
-                // jobs" im Secret-Read-Audit erfasst.
+                // SYSTEM_USER_ID is the framework-wide convention. The job discriminator is
+                // recorded in the secret-read audit through
+                // handlerName="user-data-rights:run-export-jobs".
                 const exportUserId = SYSTEM_USER_ID;
                 const exportDb = ctx.db.unsafeRaw(); // @cast-boundary db-operator — jobs never run inside a DbTx
                 const exportRegistry = ctx.registry;
@@ -441,12 +441,13 @@ export function createUserDataRightsFeature(opts = {}) {
                 const exportMetrics = ctx.meter
                     ? createMetricsHandle(ctx.meter, "user-data-rights")
                     : createNoopMetricsHandle();
-                // C6 — ohne eigene send*Email-Opts aber mit gemountetem mail-transport
-                // versendet der Cron die Export-Notifications selbst (Default-Templates).
-                // Der Resolver baut den per-Tenant-Transport aus configResolver — gleiche
-                // Bruecke wie buildStorageProvider.
-                // The cron runs across tenants: each mail needs a notify bound to the
-                // recipient's tenant (template override, channel config).
+                // Without explicit send*Email options, a mounted mail transport sends the
+                // export notifications itself using the default templates. The resolver
+                // builds the per-tenant transport from configResolver, bridging it in
+                // the same way as buildStorageProvider.
+                // The cron runs across tenants, so each mail needs a notify function
+                // bound to the recipient's tenant for template overrides and channel
+                // configuration.
                 const notifyFactory = ctx._notifyFactory;
                 const exportNotifyFor = notifyFactory !== undefined && isGdprMailDeliveryAvailable(exportRegistry)
                     ? (tenantId) => notifyFactory(createSystemUser(tenantId), tenantId)
@@ -483,9 +484,9 @@ export function createUserDataRightsFeature(opts = {}) {
                         handlerName: "user-data-rights:run-export-jobs",
                     }),
                     now: T.Now.instant(),
-                    // App-Author-Callbacks haben Vorrang; sonst greift die mail-foundation-
-                    // Default oben. Beide optional: ohne mail-transport + ohne Callback
-                    // bleibt es bei Polling via export-status.query.
+                    // App-author callbacks take precedence; otherwise the mail-foundation default
+                    // is used. Both are optional: without a mail transport or callback,
+                    // clients continue polling via export-status.query.
                     ...(sendExportReadyEmail && { sendExportReadyEmail }),
                     ...(sendExportFailedEmail && { sendExportFailedEmail }),
                     ...(opts.appExportDownloadUrl !== undefined && {
@@ -498,11 +499,11 @@ export function createUserDataRightsFeature(opts = {}) {
                 });
             },
         });
-        // Autonomer Art.17-Forget-Cron. Spiegelt run-export-jobs: nach Ablauf der
-        // Grace-Period laeuft runForgetCleanup unbeaufsichtigt (der manuelle
-        // userDataRights.runForget-API bleibt fuer Operator-Runs). Ohne diesen
-        // Cron bleibt jeder Loesch-Antrag fuer immer in DeletionRequested haengen
-        // — Art.17 wuerde nie ausgefuehrt.
+        // Automatic Article 17 forget cron. After the grace period, it runs
+        // runForgetCleanup without supervision; the manual
+        // userDataRights.runForget API remains available for operator runs.
+        // Without this cron, deletion requests would remain in
+        // DeletionRequested indefinitely and Article 17 erasure would never run.
         const RUN_FORGET_CLEANUP_REASON = "executes overdue Art.17 forget requests across every tenant";
         r.job({
             name: "run-forget-cleanup",
@@ -568,7 +569,7 @@ export function createUserDataRightsFeature(opts = {}) {
                     escapeHatchAuditLog: ctx.log,
                     actor: ctx.systemUser.id,
                 });
-                // Persist each incomplete report on the job-run log (#1572). The write
+                // Persist each incomplete report on the job-run log. The write
                 // handler returns incomplete[] in its response; the cron path used to
                 // discard the array (only a console.warn for rolledBack cases).
                 // ctx.log feeds createJobRunLogger → store_job_run_logs.

package/dist/user-data-rights/handlers/cancel-deletion.write.js

@@ -5,17 +5,17 @@ import { isWithinGracePeriod } from "../../shared/index.js";
 import { USER_STATUS, userTable } from "../../user/index.js";
 import { updateUserLifecycle } from "../lib/update-user-lifecycle.js";
 const APPEND_LIFECYCLE_EVENT_REASON = "appends the user lifecycle event on the SYSTEM_TENANT_ID user stream";
-// POST /api/user/cancel-deletion (S2.U5).
+// POST /api/user/cancel-deletion.
 //
-// Innerhalb der Grace-Period kann User seinen Forget-Antrag zurueck-
-// nehmen. Setzt:
+// During the grace period, the user can withdraw a pending deletion request.
+// This restores:
 //   - status = "active"
 //   - gracePeriodEnd = null
 //
-// Nach Grace-Period: 422 (run-forget-cleanup hat in der Zwischenzeit
-// die Hooks schon getriggert — Reversal nicht moeglich).
+// After the grace period, return 422 because cleanup may already have triggered
+// irreversible hooks.
 //
-// Sonderfall: Cancel als "active"-User → 422 (kein pending Forget).
+// Cancelling as an "active" user also returns 422 because no deletion is pending.
 export const cancelDeletionWrite = defineWriteHandler({
     name: "cancel-deletion",
     schema: z.object({}),
@@ -48,12 +48,12 @@ export const cancelDeletionWrite = defineWriteHandler({
         await updateUserLifecycle(ctx.db.unsafeRaw(), event.user.id, {
             status: USER_STATUS.Active,
             gracePeriodEnd: null,
-            // #354/1: closes the replay-after-cancel window — a still-TTL-valid email
+            // Closes the replay-after-cancel window — a still-TTL-valid email
             // token verified against the nulled requestId can no longer arm a second grace period.
             pendingDeletionRequestId: null,
         });
-        // gracePeriodEnd=null im Response symmetrisch zu request-deletion's
-        // ISO-Timestamp — Frontend kann beide Endpoints uniform behandeln.
+        // gracePeriodEnd=null in the response mirrors request-deletion's
+        // ISO timestamp so the frontend can handle both endpoints uniformly.
         const gracePeriodEnd = null;
         return {
             isSuccess: true,

package/dist/user-data-rights/handlers/confirm-deletion-by-token.write.js

@@ -4,15 +4,15 @@ import * as z from "zod";
 import { USER_STATUS, userTable } from "../../user/index.js";
 import { redeemDeletionToken } from "../deletion-token.js";
 import { resolveGracePeriod, startDeletionGracePeriod } from "./deletion-grace-period.js";
-// Generischer 422 für jeden Token-Fehlerpfad (malformed / bad_signature /
-// expired / kein Secret) — kein Signal ob ein Token zu einem User gehört.
+// Use the same generic 422 for every token-error path (malformed / bad_signature /
+// expired / missing secret) so callers cannot determine whether a token belongs to a user.
 function invalidToken() {
     return new UnprocessableError("invalid_or_expired_token");
 }
-// userId stammt aus dem noch-unverifizierten Token (Angreifer-Eingabe). Ein
-// fehlgeschlagener Lookup — z.B. eine typfremde id auf einer int/uuid-Spalte —
-// darf nicht als 500 durchschlagen; null behandelt der Caller wie "kein offener
-// Antrag" (generischer 422). Die HMAC-Prüfung bleibt der eigentliche Gate.
+// userId comes from the not-yet-verified token (attacker-controlled input). A failed
+// lookup—for example, a type-mismatched id on an int/uuid column—must not surface as a
+// 500; null is treated by the caller as "no pending request" (generic 422). HMAC
+// verification remains the actual gate.
 async function readPendingDeletionRequestId(ctx, userId) {
     try {
         const row = await ctx.db
@@ -32,7 +32,7 @@ async function readPendingDeletionRequestId(ctx, userId) {
 // the actual grace-period transition, so a crash after the spend can no
 // longer lose the write step.
 //
-// Replay protection (#354/1): the row's requestId is part of the verify key.
+// Replay protection: the row's requestId is part of the verify key.
 // We read it via the (unverified, lookup-only) userId from the token, reject
 // a missing entry, and verify the token against the CURRENT requestId. After
 // a cancel-deletion (status → Active, pendingDeletionRequestId → null), a
@@ -42,7 +42,7 @@ async function readPendingDeletionRequestId(ctx, userId) {
 // the same requestId and both verify the HMAC — commitDeletion spends the
 // anchor AND writes the transition atomically (expect: status===Active &&
 // pendingDeletionRequestId===requestId), so exactly one wins. The loser gets
-// the same generic 422 as an invalid token — no status leak (#354/2).
+// the same generic 422 as an invalid token — no status leak.
 export function createConfirmDeletionByTokenHandler(opts = {}) {
     return defineWriteHandler({
         name: "confirm-deletion-by-token",

package/dist/user-data-rights/handlers/download-by-job.query.js

@@ -1,26 +1,26 @@
-// GET /api/query → user-data-rights:query:download-by-job (S2.U3 Atom 4b).
+// GET /api/query → user-data-rights:query:download-by-job
 //
-// **UI-Klick-Pfad** (session-auth): User pollt status, sieht "done",
-// klickt "Download" im UI mit jobId. Server checkt session.userId ==
-// job.userId — kein Token noetig (Session IS the auth).
+// **UI download flow** (session-auth): The user polls the status, sees
+// "done", and clicks "Download" with the jobId. The server checks
+// `session.userId == job.userId`; no token is needed because the session
+// provides authentication.
 //
-// **Cross-Tenant-Same-User:** Job ist tenant-agnostisch (1 Job pro
-// userId ueber alle Memberships). Alice triggert Export aus Tenant A,
-// loggt sich spaeter in Tenant B ein, klickt Download. Server akzeptiert
-// — `session.userId == job.userId` reicht, kein Tenant-Match-Check.
-// Plan-Decision (Atom 4b Plan, User-Choice).
+// **Cross-tenant same user:** Jobs are tenant-agnostic (one job per userId
+// across all memberships). If Alice starts an export in Tenant A, later
+// signs in to Tenant B, and clicks Download, the server accepts it:
+// `session.userId == job.userId` is sufficient; no tenant-match check applies.
 //
-// **Cross-User-Isolation:** Wenn session.userId != job.userId → 404
-// (NICHT 403, kein Existenz-Leak). Selber error wie "Job-ID nicht
-// gefunden".
+// **Cross-user isolation:** If session.userId != job.userId, return 404
+// (not 403) to avoid leaking whether the job exists. Use the same error as
+// for an unknown job ID.
 //
-// Verify-Pipeline:
-//   1. fetchOne job by jobId
-//   2. job.userId === session.userId (cross-user-isolation)
-//   3. job.status === "done"
-//   4. job.downloadStorageKey != null
-//   5. tokenRow lookup (audit-row update only)
-//   6. Audit-Update: useCount + 1, IP, UA, lastUsedAt (best-effort)
+// Verification pipeline:
+//   1. Fetch the job by jobId
+//   2. Check job.userId === session.userId (cross-user isolation)
+//   3. Check job.status === "done"
+//   4. Check job.downloadStorageKey != null
+//   5. Look up tokenRow (audit-row update only)
+//   6. Best-effort audit update: useCount + 1, IP, UA, lastUsedAt
 //   7. Return {url, expiresAt}
 import { requestContext } from "@cosmicdrift/kumiko-framework/api";
 import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
@@ -44,7 +44,7 @@ export const downloadByJobQuery = defineQueryHandler({
             reason: "each signed-in user downloads only their own finished export job; the job " +
                 "lookup checks jobRow.userId against the caller's own id and 404s otherwise",
         },
-    }, // openToAll = auth-required, kein anonymous
+    }, // openToAll requires authentication; anonymous access is not allowed
     description: "Returns a short-lived signed download URL for the calling user's own finished data-export job named by job id, backing the download button in the privacy center once export-status reports the job done.",
     escapeHatch: {
         grants: ["unsafeRaw"],
@@ -56,9 +56,8 @@ export const downloadByJobQuery = defineQueryHandler({
         const userId = query.user.id;
         const jobId = query.payload.jobId;
         const tenantId = query.user.tenantId;
-        // IP + UA aus dem request-scoped Kontext (von requestIdMiddleware
-        // befuellt) — server-trusted, anders als ein vom Client mitgeschickter
-        // Wert (603/2).
+        // IP and UA from the request-scoped context populated by
+        // requestIdMiddleware; these are server-trusted rather than client-supplied.
         const auditIp = requestContext.get()?.ip ?? null;
         const auditUa = requestContext.get()?.userAgent ?? null;
         const runner = ctx.db.unsafeRaw();
@@ -149,10 +148,10 @@ export const downloadByJobQuery = defineQueryHandler({
             contentDisposition: `attachment; filename="user-data-export-${jobRow.id}.zip"`,
         });
         const signedUrlExpiresAt = T.Instant.fromEpochMilliseconds(now.epochMilliseconds + SIGNED_URL_TTL_SECONDS * 1000);
-        // Step 6: Audit-Update via tokenRow-lookup. UI-Pfad benutzt nicht
-        // den plain-Token, aber wir wollen den useCount inkrementieren
-        // damit die Audit-Felder konsistent sind (UI-clicks zaehlen auch
-        // als Use). Lookup via jobId — UNIQUE-Index garantiert max 1 Row.
+        // Step 6: Look up tokenRow for the audit update. The UI flow has no plain
+        // token, but its useCount must still be incremented so audit fields remain
+        // consistent and UI clicks count as uses. The jobId lookup is safe because
+        // the UNIQUE index guarantees at most one row.
         const tokenRow = await fetchOne(runner, exportDownloadTokensTable, {
             jobId,
         });
@@ -168,9 +167,9 @@ export const downloadByJobQuery = defineQueryHandler({
                 userAgent: auditUa,
             });
         }
-        // Wenn tokenRow fehlt (sollte nicht passieren wenn Atom 4a sauber
-        // lief): Audit-Update skipped, Download laeuft weiter. Niemand wird
-        // hier durch Audit-Failure blockiert.
+        // If tokenRow is missing (which should not happen when the preceding token
+        // creation flow completed), skip the audit update and continue the download;
+        // an audit failure must not block the user.
         return {
             url: signedUrl,
             expiresAt: signedUrlExpiresAt.toString(),

package/dist/user-data-rights/handlers/download-by-token.query.js

@@ -1,30 +1,29 @@
-// GET /api/query → user-data-rights:query:download-by-token (S2.U3 Atom 4b).
+// GET /api/query → user-data-rights:query:download-by-token.
 //
-// **Magic-Link-Pfad** (anonymous): User klickt Email-Link mit
-// `#token=<plain>` (URL fragment, issue #1271). Worker hat beim done-flip Token-Hash in DB
-// persistiert (Atom 4a). Verify-Pipeline:
+// **Magic-link path** (anonymous): The user clicks an email link with
+// `#token=<plain>` (URL fragment). The worker persisted the token hash in the database
+// when marking the job done. Verification:
 //
 //   1. hashDownloadToken(plain) → fetchOne in download-tokens
-//   2. expiresAt > now (Multi-use within TTL — Plan-Decision)
+//   2. expiresAt > now (multiple uses within the TTL)
 //   3. job.status === "done"
-//   4. job.downloadStorageKey != null (storage nicht gecleared)
-//   5. provider.getSignedUrl pflicht (501 wenn Provider local-fs ist)
-//   6. Audit-Update: useCount + 1, lastUsedAt, IP, UA (best-effort, race-tolerant)
+//   4. job.downloadStorageKey != null (storage was not cleared)
+//   5. provider.getSignedUrl is required (501 when the provider is local-fs)
+//   6. Audit update: useCount + 1, lastUsedAt, IP, UA (best-effort, race-tolerant)
 //   7. Return {url, expiresAt}
 //
-// **Sicherheit:**
-//   - Token-Hash-Compare via DB-fetchOne (nicht constant-time, aber
-//     timing-attacks auf SHA256-bytes brauchen >>10k requests + stable
-//     latenz — in Web-App-Kontext nicht ausnutzbar). Plan-Decision: harden
-//     wenn Pen-Test es flaggt.
-//   - 404 bei invalidem Token (kein Existenz-Leak) — gleicher Code-Pfad
-//     wie nicht-gefundenes Token.
-//   - tenant-agnostic: Token ist global eindeutig (UUID + SHA256), kein
-//     Tenant-Filter nötig.
+// **Security:**
+//   - Token-hash comparison via DB-fetchOne is not constant-time, but timing attacks
+//     against SHA256 bytes require >>10k requests plus stable latency and are not
+//     exploitable in a web-app context.
+//   - Invalid tokens return 404 without leaking existence, using the same code path
+//     as a token that was not found.
+//   - The token is tenant-agnostic: UUID + SHA256 makes it globally unique, so no
+//     tenant filter is needed.
 //
-// **r.httpRoute-Wrapper** (siehe feature.ts) macht 302-Redirect zu
-// signedUrl — User klickt 1× Email-Link, Browser folgt redirect, Download
-// startet. Dieser query-handler liefert nur das JSON.
+// **r.httpRoute wrapper** (see feature.ts) redirects to signedUrl with a 302. The user
+// clicks the email link once, the browser follows the redirect, and the download
+// starts. This query handler returns only the JSON.
 import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler, SYSTEM_USER_ID, } from "@cosmicdrift/kumiko-framework/engine";
 import { NotFoundError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
@@ -35,7 +34,7 @@ import { makeTenantStorageProviderResolver } from "../lib/storage-provider-resol
 import { exportDownloadTokensTable } from "../schema/download-token.js";
 import { EXPORT_JOB_STATUS, exportJobsTable } from "../schema/export-job.js";
 import { hashDownloadToken } from "../token-helpers.js";
-const SIGNED_URL_TTL_SECONDS = 300; // 5 min — kurz genug fuer Replay-Schutz, lang genug fuer slow connections
+const SIGNED_URL_TTL_SECONDS = 300; // 5 min — short enough to limit replay, long enough for slow connections
 const DOWNLOAD_BY_TOKEN_REASON = "the download token, its job and audit rows are keyed by token hash / job id, not the caller's tenant — the anonymous magic-link path has no tenant context at all";
 export const downloadByTokenQuery = defineQueryHandler({
     name: "download-by-token",
@@ -54,12 +53,11 @@ export const downloadByTokenQuery = defineQueryHandler({
         personalData: "public-intake",
     },
     agent: { expose: false },
-    // Brute-Force-Schutz fuer Token-Hash-Probing. Anonymous-Endpoint mit
-    // 32-byte-Random-Token = 256 Bit Search-Space, aber rate-limit als
-    // defense-in-depth + Schutz gegen Storm-Patterns die DB-Last erzeugen.
-    // 30 attempts/min/IP reicht fuer legitime User (mehrere Klicks bei
-    // Connection-Abbruch); blockiert automatisierte Probing-Loops.
-    // Memory `feedback_security_default_on`.
+    // Brute-force protection for token-hash probing. This anonymous endpoint uses a
+    // 32-byte random token with a 256-bit search space, but rate limiting provides
+    // defense in depth and protects against storm patterns that generate database load.
+    // 30 attempts/min/IP allows legitimate users several retries after connection
+    // failures while blocking automated probing loops.
     rateLimit: { per: "ip+handler", limit: 30, windowSeconds: 60 },
     escapeHatch: {
         grants: ["unsafeRaw"],
@@ -75,26 +73,26 @@ export const downloadByTokenQuery = defineQueryHandler({
             tokenHash: hash,
         });
         if (!tokenRow) {
-            // Invalid token — 404 ohne Existenz-Leak. Generic NotFoundError
-            // damit alle Failure-Pfade die gleiche externe Shape haben (kein
-            // Probing zwischen "Token existiert nicht" vs "Job ist failed").
+            // Invalid token — 404 without leaking existence. Use a generic NotFoundError
+            // so all failure paths have the same external shape, preventing probing that
+            // distinguishes "Token does not exist" from "Job has failed".
             throw new NotFoundError("export-download", undefined, {
                 i18nKey: "userDataRights.errors.download.notFound",
             });
         }
         const auditIp = query.payload.auditMeta?.ip ?? null;
         const auditUa = query.payload.auditMeta?.userAgent ?? null;
-        // Step 2: TTL-check.
+        // Step 2: TTL check.
         //
-        // **Pragma:** semantisch waere 410 Gone richtig (war mal da, jetzt
-        // nicht mehr). Framework hat keine GoneError-Class; wir nutzen
-        // NotFoundError + i18nKey "expired" als Kompromiss. UI rendert
-        // anhand des i18nKeys, nicht des HTTP-Status — also User sieht
-        // "Dein Download ist abgelaufen", nicht generic "not found".
+        // 410 Gone would be semantically right (the download existed and is now
+        // gone), but the framework has no GoneError class. NotFoundError with
+        // i18nKey "expired" is the compromise: the UI renders by i18nKey, not by
+        // HTTP status, so the user sees "Your download has expired" instead of a
+        // generic "not found".
         if (tokenRow.expiresAt.epochMilliseconds <= now.epochMilliseconds) {
-            // Audit-Skip noch nicht moeglich — jobRow noch nicht geladen,
-            // tenantId unbekannt. Wir laden den Job hier noch fuer Audit-Context
-            // (best-effort — wenn Job auch fehlt, audit-skip ist akzeptabel).
+            // Auditing cannot be skipped yet because jobRow has not been loaded and the
+            // tenantId is unknown. Load the job to obtain audit context; if it is also
+            // missing, skipping the audit is acceptable (best-effort).
             const jobForAudit = await fetchOne(runner, exportJobsTable, {
                 id: tokenRow.jobId,
             });
@@ -193,9 +191,9 @@ export const downloadByTokenQuery = defineQueryHandler({
             contentDisposition: `attachment; filename="user-data-export-${jobRow.id}.zip"`,
         });
         const signedUrlExpiresAt = T.Instant.fromEpochMilliseconds(now.epochMilliseconds + SIGNED_URL_TTL_SECONDS * 1000);
-        // Step 6: Audit-Update best-effort. auditMeta kommt vom httpRoute-
-        // Wrapper (trusted-source). Direct-API-caller koennen luegen, aber
-        // Audit ist nicht security-relevant.
+        // Step 6: Best-effort audit update. auditMeta comes from the httpRoute wrapper
+        // (trusted source). Direct API callers can falsify it, but the audit data is not
+        // security-sensitive.
         await recordDownloadUse({
             db: runner,
             tokenId: tokenRow.id,

package/dist/user-data-rights/handlers/export-status.query.js

@@ -1,15 +1,14 @@
-// GET /api/user/export-status (S2.U3 Atom 2) — User-Polling.
+// GET /api/user/export-status — user polling.
 //
-// Liefert den meist-aktuellen ExportJob des aufrufenden Users (in
-// Reihenfolge: aktiver Job zuerst, sonst neuester done/failed).
+// Returns the calling user's most recent ExportJob (active jobs first,
+// otherwise the newest done/failed job).
 //
-// **Cross-User-Isolation:** Filter ist `userId === query.user.id` — kein
-// User kann fremde Job-Status sehen, auch nicht via ID-Guess. Pre-Check
-// uses ctx.db.unsafeRaw — ExportJob is tenant-agnostic (see plan doc,
-// "Cross-Tenant-Semantik").
+// **Cross-User-Isolation:** The filter is `userId === query.user.id`, so no
+// user can view another user's job status, even by guessing an ID. The
+// pre-check uses ctx.db.unsafeRaw because ExportJob is tenant-agnostic.
 //
-// **Read-Only-Endpoint:** Pollt nur, kein State-Flip. Idempotent + cache-
-// fest. UI poll-Intervall typisch 2-5s waehrend running.
+// **Read-Only-Endpoint:** Polling only; it does not change state. The endpoint
+// is idempotent and cacheable. The UI typically polls every 2-5s while running.
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";

package/dist/user-data-rights/handlers/lift-restriction.write.js

@@ -5,7 +5,7 @@ import { USER_STATUS, userTable } from "../../user/index.js";
 import { denyIfTargetOutsideAdminTenant } from "../lib/deny-if-target-outside-admin-tenant.js";
 import { updateUserLifecycle } from "../lib/update-user-lifecycle.js";
 const LIFT_RESTRICTION_ESCAPE_HATCH_REASON = "checks the target user's membership in the admin's tenant and appends the user lifecycle status change on the SYSTEM_TENANT_ID user stream, both via DbRunner helpers outside the admin's own tenant scope.";
-// POST /api/user/lift-restriction (S2.U6) — DSGVO Art. 18 Reverse.
+// POST /api/user/lift-restriction — GDPR Art. 18 Reverse.
 //
 // Operator-only. A Restricted user's own session is unconditionally
 // rejected by sessionChecker (BLOCKED_STATUSES) the moment their status
@@ -13,16 +13,15 @@ const LIFT_RESTRICTION_ESCAPE_HATCH_REASON = "checks the target user's membershi
 // endpoint. There is no self-service path today, so lifting a restriction
 // always targets someone else's account by id.
 //
-// Tenant scope: `access.admin` includes TenantAdmin (tenant-scoped) even
-// though the User-entity is global — see user-data-rights.md "Cross-Tenant-Semantik". Without a membership check, a TenantAdmin
-// from tenant A could unrestrict/reactivate a user who has never been a
-// member of tenant A. Only SystemAdmin (platform-wide) skips the check;
-// the target must have a membership row in the acting admin's
-// `event.user.tenantId` (row existence only — no active-status field).
+// Tenant scope: `access.admin` includes TenantAdmin (tenant-scoped) even though the User-entity is
+// global — see user-data-rights.md "Cross-Tenant Semantics". Without a membership check, a
+// TenantAdmin from tenant A could unrestrict/reactivate a user who has never been a member of
+// tenant A. Only SystemAdmin (platform-wide) skips the check; the target must have a membership row
+// in the acting admin's `event.user.tenantId` (row existence only — no active-status field).
 //
 // State-Transitions:
 //   Restricted → Active        ✓
-//   Active → ...               ✗ 422 not_restricted (Idempotenz-Guard)
+//   Active → ...               ✗ 422 not_restricted (Idempotency Guard)
 //   DeletionRequested → ...    ✗ 422 not_restricted
 //   Deleted → ...              ✗ 422 not_restricted
 export const liftRestrictionWrite = defineWriteHandler({

package/dist/user-data-rights/handlers/list-download-attempts.query.js

@@ -4,8 +4,8 @@ import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { decryptStoredPii } from "../../shared/index.js";
 import { downloadAttemptsTable } from "../schema/download-attempt.js";
-// Operator-Query: invalid Download-Attempts (S2.U7).
-// DPO-Sicht fuer Brute-Force-Detection. Tenant-isolated via WHERE.
+// Operator query for invalid download attempts. Provides tenant-isolated visibility for data
+// protection officers investigating brute-force probing.
 const MAX_LIMIT = 100;
 const REQUEST_ID = "user-data-rights:list-download-attempts";
 export const listDownloadAttemptsQuery = defineQueryHandler({