@cosmicdrift/kumiko-bundled-features 0.385.0 → 0.387.0

package/dist/user-data-rights/feature.d.ts

@@ -5,75 +5,74 @@ import { type GdprMailDefaults } from "./lib/default-mailers.ts";
 import { type SendExportFailedEmailFn, type SendExportReadyEmailFn } from "./run-export-jobs.ts";
 import { type SendDeletionExecutedEmailFn } from "./run-forget-cleanup.ts";
 /**
- * Options fuer createUserDataRightsFeature. Notification-Callbacks
- * (Atom 5) folgen dem password-reset-Pattern aus auth-routes.ts.
+ * Options for createUserDataRightsFeature. Notification callbacks follow
+ * the password-reset pattern in auth-routes.ts.
  *
- * Plain-Token landet NIE in DB/event-store/jobRunsTable — Worker reicht
- * ihn ephemeral via Callback-arg an die App-Author-Implementation
- * (typisch: `delivery.notify(...)` mit `r.notification`-Templates,
- * `mailFoundation.send` direkt, oder Custom Resend/SES).
+ * The plain token is never stored in the DB, event store, or jobRunsTable.
+ * The worker passes it ephemerally as a callback argument to the app-author
+ * implementation (typically `delivery.notify(...)` with `r.notification`
+ * templates, `mailFoundation.send` directly, or custom Resend/SES).
  *
- * Worker-Run-Tracking + Retry kommt automatisch via existing
- * `jobs`-Feature (siehe CLAUDE.md "Bundled-Features by Concern").
+ * Worker-run tracking and retries are provided automatically by the existing
+ * `jobs` feature.
  */
 export type UserDataRightsOptions = {
-    /** Email-Notification beim Export-done. App-Author wired das an seinen
-     *  Email-Provider. Best-effort (Atom 5.fix3): send-Throw fuer Job A
-     *  killt den Batch nicht — restliche pending-Jobs werden weiter
-     *  verarbeitet, Failure wird via console.warn sichtbar. (Vorher
-     *  bubbelte der Throw zum r.job-Wrap, was bei mehreren pending Jobs
-     *  zum silent-miss fuehrte: Job A done committed, B/C/D nie
-     *  verarbeitet, retry findet niemand.) */
+    /** Email notification when the export completes. The app author connects it
+     * to an email provider. Best effort: a send failure for Job A does not stop
+     * the batch; remaining pending jobs continue, and the failure is exposed via
+     * console.warn. Previously, the error reached the r.job wrapper, so with
+     * multiple pending jobs A could commit while B/C/D were never processed and
+     * no retry could find them. */
     readonly sendExportReadyEmail?: SendExportReadyEmailFn;
     /** Email-Notification beim Export-failed. Best-effort analog
      *  sendExportReadyEmail. */
     readonly sendExportFailedEmail?: SendExportFailedEmailFn;
-    /** Base-URL fuer den Magic-Link, z.B.
-     *  "https://app.example.com/user-export/by-token". Worker bauen
-     *  a URL fragment (`#token=<plain>`, issue #1271). Required wenn
-     *  sendExportReadyEmail gesetzt. Per-Tenant via reverse-proxy host
-     *  routing — nicht via per-Tenant-config-key (App-Author-Decision). */
+    /** Base URL for the magic link, e.g.
+     *  "https://app.example.com/user-export/by-token". The worker builds
+     *  a URL fragment (`#token=<plain>`). Required when
+     *  sendExportReadyEmail is set. Routing uses the reverse-proxy host per
+     *  tenant rather than a per-tenant config key. */
     readonly appExportDownloadUrl?: string;
-    /** Atom 5b — Email-Notification beim deletion-requested-flip
-     *  ("Account-Loeschung in 30 Tagen"). Best-effort: send-failure killt
-     *  den Status-Flip nicht (siehe handlers/request-deletion.write.ts). */
+    /** Email notification when deletion is requested ("account deletion in
+     *  30 days"). Best effort: a send failure does not abort the status flip
+     *  (see handlers/request-deletion.write.ts). */
     readonly sendDeletionRequestedEmail?: SendDeletionRequestedEmailFn;
-    /** Atom 5b — Email-Notification beim Cleanup-Runner-done-Pfad
-     *  ("Account wurde geloescht"). Best-effort. Der Versand passiert NACH
-     *  dem User-Hook-Anonymisieren, deshalb cached der Worker
-     *  userEmail+tenantIds PRE-tx und reicht sie ephemeral an die
-     *  Callback-Implementation (siehe run-forget-cleanup.ts). */
+    /** Email notification after the cleanup runner completes ("account deleted").
+     *  Best effort. Delivery occurs after the user hook anonymizes the user, so
+     *  the worker caches userEmail+tenantIds before the transaction and passes
+     *  them ephemerally to the callback implementation (see
+     *  run-forget-cleanup.ts). */
     readonly sendDeletionExecutedEmail?: SendDeletionExecutedEmailFn;
-    /** Anonymer, email-verifizierter Apex-Deletion-Flow (Lockout-sicher).
-     *  HMAC-Secret zum Signieren des Verify-Tokens. Ohne Secret bleibt der
-     *  Flow deaktiviert (request-by-email antwortet still success, confirm-
-     *  by-token weist generisch ab). */
+    /** Anonymous, email-verified apex deletion flow that is safe against lockout.
+     *  HMAC secret for signing the verification token. Without a secret, the
+     *  flow remains disabled: request-by-email returns success silently, while
+     *  confirm-by-token rejects generically. */
     readonly deletionTokenSecret?: string;
-    /** Basis-URL des Apex-Confirm-Screens, z.B.
-     *  "https://app.example.com/delete-account/confirm". Der Handler hängt das
-     *  Token als URL-Fragment an (`#token=<token>`, fw#1554). Required wenn
-     *  deletionTokenSecret gesetzt. */
+    /** Base URL of the apex confirmation screen, e.g.
+     *  "https://app.example.com/delete-account/confirm". The handler appends
+     *  the token as a URL fragment (`#token=<token>`). Required when
+     *  deletionTokenSecret is set. */
     readonly deletionVerifyUrl?: string;
-    /** Versand des Verify-Magic-Links (Schritt 1 des anonymen Flows).
-     *  Best-effort, app-author-wired. MUSS non-blocking sein (enqueue, z.B.
-     *  delivery.notify) — ein synchroner Send reintroduziert ein Timing-Oracle
-     *  für Account-Enumeration (siehe SendDeletionVerificationEmailFn-Doc).
-     *  Bewusst KEINE mail-foundation-Default: ein synchroner Default-Send
-     *  brächte genau dieses Enumeration-Oracle zurück, deshalb app-wired. */
+    /** Sends the verification magic link (step 1 of the anonymous flow).
+     *  Best effort and wired by the app author. It MUST be non-blocking (enqueue,
+     *  e.g. via delivery.notify): a synchronous send would reintroduce a timing
+     *  oracle for account enumeration (see SendDeletionVerificationEmailFn-doc).
+     *  There is deliberately no mail-foundation default because a synchronous
+     *  default send would restore that enumeration oracle. */
     readonly sendDeletionVerificationEmail?: SendDeletionVerificationEmailFn;
-    /** C6 — Zero-Callback-GDPR-Mails: ist mail-foundation + ein mail-transport-*
-     *  gemountet, versendet user-data-rights die Export-/Loesch-Notifications
-     *  selbst (Export-ready/-failed, Deletion-requested/-executed) ueber die
-     *  Default-Templates (email-templates.ts) — die App schreibt keinen Callback.
-     *  `mailDefaults` brandet diese Default-Mails (Locale + App-Name). Greift NUR
-     *  wenn der jeweilige send*Email-Opt NICHT gesetzt ist; Export-ready braucht
-     *  zusaetzlich appExportDownloadUrl. */
+    /** Zero-callback GDPR mail: when mail-foundation and a mail-transport-* are
+     *  mounted, user-data-rights sends export and deletion notifications itself
+     *  (export-ready/-failed, deletion-requested/-executed) using the default
+     *  templates (email-templates.ts), without an app callback.
+     *  `mailDefaults` brands these default messages (locale and app name). It
+     *  applies only when the relevant send*Email option is unset; export-ready
+     *  also requires appExportDownloadUrl. */
     readonly mailDefaults?: GdprMailDefaults;
     /** Hides the Art. 17 deletion section + its request-deletion/cancel-deletion
      *  actions on the privacy-center screen — for apps that already offer
      *  account deletion elsewhere (e.g. a profile danger-zone), against
      *  duplication. Default `true` (deletion section shown).
-     *  BREAKING (fw#2312): replaces the removed client-side
+     *  BREAKING: replaces the removed client-side
      *  `userDataRightsClient({ privacyCenter: { showDeletion } })` option —
      *  the screen is now declared once, server-side (`type: "projectionDetail"`),
      *  so per-app visibility can only be a boot-time option, not a client-side

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(),