@cosmicdrift/kumiko-samples 0.338.0

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

@@ -0,0 +1,808 @@
+// kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312 (feature.ts > 300 lines)
+import { UNKNOWN_CLIENT_IP } from "@cosmicdrift/kumiko-framework/api";
+import {
+  createSystemConfig,
+  defineFeature,
+  EXT_USER_DATA,
+  type FeatureDefinition,
+  i18nKey,
+  SYSTEM_USER_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createMetricsHandle,
+  createNoopMetricsHandle,
+} from "@cosmicdrift/kumiko-framework/observability";
+import { validateGdprHookCompleteness, validateGdprPiiHookCoverage } from "./boot-checks.js";
+import {
+  EXPORT_SECTION_EXTENSION_NAME,
+  PRIVACY_CENTER_SCREEN_ID,
+  STATUS_OPTION_KEY_PREFIX,
+  USER_ME_QUERY,
+  UserDataRightsHandlers,
+} from "./constants.js";
+import { cancelDeletionWrite } from "./handlers/cancel-deletion.write.js";
+import { createConfirmDeletionByTokenHandler } from "./handlers/confirm-deletion-by-token.write.js";
+import { downloadAttemptListQuery } from "./handlers/download-attempt-list.query.js";
+import { downloadByJobQuery } from "./handlers/download-by-job.query.js";
+import { downloadByTokenQuery } from "./handlers/download-by-token.query.js";
+import { exportJobDetailQuery } from "./handlers/export-job-detail.query.js";
+import { exportJobListQuery } from "./handlers/export-job-list.query.js";
+import { exportStatusQuery } from "./handlers/export-status.query.js";
+import { liftRestrictionWrite } from "./handlers/lift-restriction.write.js";
+import { listDownloadAttemptsQuery } from "./handlers/list-download-attempts.query.js";
+import { myAuditLogQuery } from "./handlers/my-audit-log.query.js";
+import {
+  createRequestDeletionHandler,
+  type SendDeletionRequestedEmailFn,
+} from "./handlers/request-deletion.write.js";
+import {
+  createRequestDeletionByEmailHandler,
+  type SendDeletionVerificationEmailFn,
+} from "./handlers/request-deletion-by-email.write.js";
+import { requestExportWrite } from "./handlers/request-export.write.js";
+import { restrictAccountWrite } from "./handlers/restrict-account.write.js";
+import { createRunForgetCleanupHandler } from "./handlers/run-forget-cleanup.write.js";
+import { USER_DATA_RIGHTS_I18N } from "./i18n.js";
+import {
+  type GdprMailDefaults,
+  isMailTransportAvailable,
+  makeDefaultDeletionExecutedEmail,
+  makeDefaultExportFailedEmail,
+  makeDefaultExportReadyEmail,
+} from "./lib/default-mailers.js";
+import { makeTenantMailTransportResolver } from "./lib/mail-transport-resolver.js";
+import { resolveAppTenantModel } from "./lib/resolve-tenant-model.js";
+import { makeTenantStorageProviderResolver } from "./lib/storage-provider-resolver.js";
+import {
+  EXPORT_CLEANUP_BACKLOG_AGE_METRIC,
+  EXPORT_CLEANUP_LAST_RUN_TIMESTAMP_METRIC,
+  runExportJobs,
+  type SendExportFailedEmailFn,
+  type SendExportReadyEmailFn,
+} from "./run-export-jobs.js";
+import {
+  runForgetCleanup,
+  type SendDeletionExecutedEmailFn,
+  sanitizeReasonForLog,
+} from "./run-forget-cleanup.js";
+import { downloadAttemptEntity } from "./schema/download-attempt.js";
+import { exportDownloadTokenEntity } from "./schema/download-token.js";
+import { exportJobEntity } from "./schema/export-job.js";
+import {
+  downloadAttemptListScreen,
+  exportJobDetailScreen,
+  exportJobListScreen,
+} from "./screens.js";
+
+// user-data-rights — DSGVO Art. 15 (Auskunft) + Art. 17 (Löschung) +
+// Art. 18 (Restriction) + Art. 20 (Portabilität) als Core-Feature.
+//
+// Pattern (Plan-Roadmap docs/plans/datenschutz/user-data-rights.md):
+// Statt jedes Feature seine eigene Forget-/Export-Logik schreibt,
+// haengt es sich via `r.useExtension(EXT_USER_DATA, "<entity>", {
+// export, delete })` an. user-data-rights orchestriert:
+//   - Export-Job: iteriert alle Extension-Registrierungen, sammelt JSON
+//   - Forget-Job: iteriert alle, ruft delete-Hook mit Strategy aus
+//                 retention.policyFor (data-retention)
+//   - Restriction: status-Flip auf user-Schema, Auth-Middleware-Guard
+/**
+ * Options fuer createUserDataRightsFeature. Notification-Callbacks
+ * (Atom 5) folgen dem password-reset-Pattern aus 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).
+ *
+ * Worker-Run-Tracking + Retry kommt automatisch via existing
+ * `jobs`-Feature (siehe CLAUDE.md "Bundled-Features by Concern").
+ */
+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.) */
+  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). */
+  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). */
+  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). */
+  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). */
+  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. */
+  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. */
+  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. */
+  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
+   *  `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
+   *  component swap. Consumers that passed `showDeletion: false` client-side
+   *  must move it here. */
+  readonly privacyCenterShowDeletion?: boolean;
+};
+
+export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): FeatureDefinition {
+  // One-shot operator warning (the export cron fires daily — warn once per
+  // process, not every run). Lives in the factory scope so the cron closure
+  // shares it across runs.
+  let warnedMissingExportUrl = false;
+  const showDeletion = opts.privacyCenterShowDeletion ?? true;
+  return defineFeature("user-data-rights", (r) => {
+    r.describe(
+      'Implements GDPR Art. 15 (access / `my-audit-log` query), Art. 17 (erasure / `request-deletion` + `cancel-deletion`, plus the anonymous email-verified `request-deletion-by-email` + `confirm-deletion-by-token` flow for lockout-safe self-service, + cron cleanup with grace period), Art. 18 (restriction / `restrict-account` + `lift-restriction`), and Art. 20 (portability / async `request-export` \u2192 ZIP via `file-foundation`, Magic-Link download) as first-class HTTP handlers and cron jobs. Each domain feature opts in by calling `r.useExtension(EXT_USER_DATA, "<entity>", { export, delete })` \u2014 the feature then orchestrates the export and forget pipelines across all registered hooks automatically. When `mail-foundation` and a `mail-transport-*` are mounted, it also sends the four GDPR notifications (export ready/failed, deletion requested/executed) itself with no app callback code, rendered in each recipient’s locale. Requires `user`, `data-retention`, `compliance-profiles`, and `sessions`.',
+    );
+    r.uiHints({
+      displayLabel: "User Data Rights \u00b7 GDPR",
+      category: "compliance",
+      recommended: false,
+    });
+    r.requires("user", "data-retention", "compliance-profiles", "sessions");
+    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.
+    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.
+
+    r.extendsRegistrar(EXT_USER_DATA, {});
+
+    // GDPR-storage guards V2+V3 (#1314) — 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.
+    r.bootCheck(({ features }) => validateGdprHookCompleteness(features));
+    r.bootCheck(({ features }) => validateGdprPiiHookCoverage(features));
+
+    // App-level tenant-occupancy model. Default "multi-user" → tenant-scoped
+    // contributors (e.g. credit) NEVER erase tenant data on a per-user forget
+    // (would harm co-members). An app with one user per tenant sets this to
+    // "single-user" via appOverrides (TENANT_MODEL_CONFIG_KEY) so the forget
+    // pipeline may erase the tenant's data as that user's personal data — still
+    // gated by a runtime sole-member check in run-forget-cleanup.
+    r.config(
+      "tenantModel",
+      createSystemConfig("select", {
+        default: "multi-user",
+        options: ["single-user", "multi-user"],
+        env: "TENANT_MODEL",
+      }),
+    );
+
+    // S2.U3 Atom 1b — ExportJob-Lifecycle-Entity.
+    r.entity("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).
+    r.entity("export-download-token", exportDownloadTokenEntity);
+
+    // S2.U7 — Audit-Trail invalid Download-Attempts (DPO Brute-Force-Detection).
+    r.entity("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.
+    r.writeHandler(restrictAccountWrite);
+    r.writeHandler(liftRestrictionWrite);
+
+    // S2.U5a — Endpoints fuer DSGVO Art. 17 Forget-Pfad mit Grace.
+    r.writeHandler(
+      createRequestDeletionHandler({
+        ...(opts.sendDeletionRequestedEmail && {
+          sendDeletionRequestedEmail: opts.sendDeletionRequestedEmail,
+        }),
+        ...(opts.mailDefaults && { mailDefaults: opts.mailDefaults }),
+      }),
+    );
+    r.writeHandler(cancelDeletionWrite);
+
+    // Anonymer, email-verifizierter Apex-Deletion-Flow (Lockout-sicher):
+    // request-by-email (Schritt 1, Magic-Link) + confirm-by-token (Schritt 2,
+    // startet dieselbe Grace-Period via startDeletionGracePeriod).
+    r.writeHandler(
+      createRequestDeletionByEmailHandler({
+        ...(opts.deletionTokenSecret !== undefined && {
+          deletionTokenSecret: opts.deletionTokenSecret,
+        }),
+        ...(opts.deletionVerifyUrl !== undefined && { deletionVerifyUrl: opts.deletionVerifyUrl }),
+        ...(opts.sendDeletionVerificationEmail !== undefined && {
+          sendDeletionVerificationEmail: opts.sendDeletionVerificationEmail,
+        }),
+      }),
+    );
+    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).
+    r.writeHandler(
+      createRunForgetCleanupHandler(
+        opts.sendDeletionExecutedEmail
+          ? { sendDeletionExecutedEmail: opts.sendDeletionExecutedEmail }
+          : {},
+      ),
+    );
+    r.exposesApi("userDataRights.runForget");
+
+    // S2.U3 Atom 2 — User-Touchpoints fuer Async 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.
+    r.queryHandler(downloadByTokenQuery);
+    r.queryHandler(downloadByJobQuery);
+
+    // S2.U7 — User-Selbstauskunft (Art. 15) + Operator-Sicht auf
+    // invalid Download-Attempts (DPO).
+    r.queryHandler(myAuditLogQuery);
+    r.queryHandler(listDownloadAttemptsQuery);
+
+    // Read-only GDPR operator inspector (SystemAdmin) — screens stay inert until an app navs them.
+    r.queryHandler(exportJobListQuery);
+    r.queryHandler(exportJobDetailQuery);
+    r.queryHandler(downloadAttemptListQuery);
+    r.screen(exportJobListScreen);
+    r.screen(exportJobDetailScreen);
+    r.screen(downloadAttemptListScreen);
+
+    r.nav({
+      id: "export-job-list",
+      label: "user-data-rights:nav.exportJobs",
+      icon: "download",
+      screen: "user-data-rights:screen:export-job-list",
+      order: 25,
+      access: { roles: ["SystemAdmin"] },
+    });
+
+    r.translations({ keys: USER_DATA_RIGHTS_I18N });
+    // Privacy-center dot-form labels (i18nKey()-marked below), duplicated in
+    // web/i18n.ts's client bundle since privacy-center-screen.tsx renders
+    // them client-side.
+    r.translations({
+      keys: {
+        "userDataRights.privacyCenter.field.status": { en: "Account status" },
+        "userDataRights.privacyCenter.field.gracePeriodEnd": { en: "Scheduled deletion date" },
+        "userDataRights.privacyCenter.export.title": { en: "Export your data (Art. 20)" },
+        "userDataRights.privacyCenter.restriction.title": { en: "Restrict processing (Art. 18)" },
+        "userDataRights.privacyCenter.restriction.explainer": {
+          en: "Freeze your account: processing of your data is paused and you are signed out. Lifting the restriction afterwards is only possible via support.",
+        },
+        "userDataRights.privacyCenter.restriction.restrict": { en: "Restrict account" },
+        "userDataRights.privacyCenter.restriction.dialogTitle": { en: "Restrict your account?" },
+        "userDataRights.privacyCenter.restriction.dialogDescription": {
+          en: "You will be signed out immediately and cannot sign in again until support lifts the restriction.",
+        },
+        "userDataRights.privacyCenter.deletion.title": { en: "Delete account (Art. 17)" },
+        "userDataRights.privacyCenter.deletion.explainer": {
+          en: "Request deletion of your account. Until the grace period ends you can cancel the deletion.",
+        },
+        "userDataRights.privacyCenter.deletion.delete": { en: "Delete account" },
+        "userDataRights.privacyCenter.deletion.cancel": { en: "Cancel deletion" },
+        "userDataRights.privacyCenter.deletion.dialogTitle": { en: "Delete your account?" },
+        "userDataRights.privacyCenter.deletion.dialogDescription": {
+          en: "Confirming starts the deletion grace period. You can cancel the deletion until it ends.",
+        },
+      },
+    });
+
+    // Self-service screen (Art. 15/17/18/20): export, restriction, deletion
+    // in one projectionDetail screen bound to the user's own `me` row. No
+    // r.nav — the app places it in its logged-in area; `dormant: true` opts
+    // it out of the nav-area boot check. access is openToAll because no app role name is
+    // portable; the per-user handlers enforce auth server-side.
+    //
+    // Restriction/Deletion are declarative fields + actions; Export stays a
+    // custom extension section (web/client-plugin.tsx registers the
+    // component under EXPORT_SECTION_EXTENSION_NAME) since it needs
+    // async-job polling + a signed-URL download that a declarative action
+    // can't express. entityName: "export-job" names the domain entity the
+    // extension persists against (projectionDetail has no real entity of
+    // its own for the extension to default to).
+    r.screen({
+      id: PRIVACY_CENTER_SCREEN_ID,
+      type: "projectionDetail",
+      query: USER_ME_QUERY,
+      singleton: true,
+      access: {
+        openToAll: {
+          reason:
+            "each signed-in user manages GDPR self-service actions (export, restriction, " +
+            "deletion) for only their own account; the bound query and every action handler " +
+            "operate on the caller's own userId, and no app role name is portable enough to gate this",
+        },
+      },
+      dormant: true,
+      description: "userDataRights.privacyCenter.subtitle",
+      fieldLabels: {
+        status: i18nKey("userDataRights.privacyCenter.field.status"),
+        gracePeriodEnd: i18nKey("userDataRights.privacyCenter.field.gracePeriodEnd"),
+      },
+      layout: {
+        sections: [
+          {
+            kind: "extension",
+            title: i18nKey("userDataRights.privacyCenter.export.title"),
+            component: { react: { __component: EXPORT_SECTION_EXTENSION_NAME } },
+            entityName: "export-job",
+          },
+          {
+            // `status` lives here (not in Deletion) because this is the one
+            // section always on the screen — Deletion is dropped entirely
+            // when `showDeletion` is false, and status covers restriction
+            // AND deletion state, so it can't hang off the optional section.
+            title: i18nKey("userDataRights.privacyCenter.restriction.title"),
+            description: i18nKey("userDataRights.privacyCenter.restriction.explainer"),
+            fields: [
+              {
+                field: "status",
+                renderer: { format: "enumOption", keyPrefix: STATUS_OPTION_KEY_PREFIX },
+              },
+            ],
+          },
+          ...(showDeletion
+            ? [
+                {
+                  title: i18nKey("userDataRights.privacyCenter.deletion.title"),
+                  description: i18nKey("userDataRights.privacyCenter.deletion.explainer"),
+                  // gracePeriodEnd is only meaningful once a deletion is
+                  // actually pending — hide it instead of showing an empty
+                  // date when status isn't deletionRequested.
+                  fields: [
+                    {
+                      field: "gracePeriodEnd",
+                      renderer: { format: "date" as const },
+                      visible: { field: "status", eq: "deletionRequested" },
+                    },
+                  ],
+                },
+              ]
+            : []),
+        ],
+      },
+      actions: [
+        {
+          id: "restrict",
+          icon: "lock",
+          label: i18nKey("userDataRights.privacyCenter.restriction.restrict"),
+          handler: UserDataRightsHandlers.restrictAccount,
+          confirm: i18nKey("userDataRights.privacyCenter.restriction.dialogDescription"),
+          visible: { field: "status", ne: "restricted" },
+          style: "danger",
+        },
+        ...(showDeletion
+          ? [
+              {
+                id: "request-deletion",
+                label: i18nKey("userDataRights.privacyCenter.deletion.delete"),
+                handler: UserDataRightsHandlers.requestDeletion,
+                confirm: i18nKey("userDataRights.privacyCenter.deletion.dialogDescription"),
+                visible: { field: "status", ne: "deletionRequested" },
+                style: "danger" as const,
+              },
+              {
+                id: "cancel-deletion",
+                label: i18nKey("userDataRights.privacyCenter.deletion.cancel"),
+                handler: UserDataRightsHandlers.cancelDeletion,
+                visible: { field: "status", eq: "deletionRequested" },
+                style: "secondary" as const,
+                // Declared: the id's last segment ("deletion") would otherwise resolve to the destructive trash icon.
+                icon: "x" as const,
+              },
+            ]
+          : []),
+      ],
+    });
+
+    // 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
+    // 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
+    // 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
+    // afterward (a redirect doesn't undo an already-logged request) — the
+    // only leak-proof fix is to never accept the token that way.
+    //
+    // Path sits outside /api/* — r.httpRoute must not claim the /api namespace
+    // (reserved for write/query/batch/auth/sse-dispatcher).
+    //
+    // The session path (logged-in download) needs no httpRoute wrapper: the
+    // client calls download-by-job via the Dispatcher (with X-CSRF-Token) and
+    // navigates to the returned signed URL — see postWithDownload in
+    // privacy-center-screen.
+    r.httpRoute({
+      method: "GET",
+      path: "/user-export/by-token",
+      anonymous: true,
+      handler: async (c) => {
+        return c.body(TOKEN_EXCHANGE_PAGE_HTML, 200, {
+          "content-type": "text/html; charset=utf-8",
+        });
+      },
+    });
+
+    // External script for the interstitial page above — same-origin file
+    // instead of inline <script>, so the page also works under a strict
+    // `script-src 'self'` CSP (apps set CSP via the security-headers
+    // option, without assuming `unsafe-inline`).
+    r.httpRoute({
+      method: "GET",
+      path: "/user-export/by-token.js",
+      anonymous: true,
+      handler: async (c) => {
+        return c.body(TOKEN_EXCHANGE_PAGE_JS, 200, {
+          "content-type": "application/javascript; charset=utf-8",
+        });
+      },
+    });
+
+    // Exchange endpoint for the interstitial page: the token arrives here
+    // as a POST body instead of a query string (issue #1271). 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
+    //      the framework-resolved client IP, which only the server has, not
+    //      the browser (see the GET path above). Without this route every
+    //      fragment-path download would land in download-attempt with
+    //      lastUsedFromIp/UA = null.
+    //   2. /api/query is the reserved dispatcher namespace for
+    //      authenticated writes/queries — an anonymous cross-origin POST
+    //      there isn't guaranteed to be reachable (origin guard).
+    r.httpRoute({
+      method: "POST",
+      path: "/user-export/by-token",
+      anonymous: true,
+      handler: async (c, { app, clientIp }) => {
+        const url = new URL(c.req.url);
+        const parsedBody = await c.req.json().catch(() => null);
+        const token =
+          parsedBody && typeof parsedBody === "object" && "token" in parsedBody
+            ? (parsedBody as { token?: unknown }).token
+            : undefined;
+        if (typeof token !== "string" || token.length === 0) {
+          return c.json({ error: "missing_token" }, 400);
+        }
+        const auditMeta = extractAuditMeta(c.req.raw.headers, clientIp);
+        return app.fetch(
+          new Request(`${url.origin}/api/query`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+              type: "user-data-rights:query:download-by-token",
+              payload: { token, auditMeta },
+            }),
+          }),
+          // download-by-token.query.ts's `rateLimit: { per: "ip", limit: 30 }`
+          // resolves the client IP from this internal request's env (2nd
+          // app.fetch arg), same as Bun.serve's socket address — without it,
+          // the resolver has neither a trusted XFF entry (trustedProxyHops
+          // 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`
+          // directly as env — the same server-resolved, trustedProxyHops-
+          // aware value the outer request already trusted — reaches
+          // extractSocketAddress() without going through header/hop-count
+          // logic at all.
+          clientIp,
+        );
+      },
+    });
+
+    // Surfaces a stalled export-cleanup cron: if the daily
+    // pass stops running, done-status export bundles keep sitting in
+    // storage past their TTL+grace with downloadStorageKey still set
+    // (unencrypted PII at rest). Gauges keep their last value in-process, so
+    // a dead cron does NOT make the backlog gauge absent; the last-run
+    // timestamp gauge below is the liveness signal.
+    // Scope: Done-status bundles past expiresAt+grace plus Failed-status
+    // orphans (no TTL, due from completedAt ?? startedAt; see storageCleanupPass).
+    r.metric(EXPORT_CLEANUP_BACKLOG_AGE_METRIC, {
+      type: "gauge",
+      unit: "seconds",
+      description:
+        "Age in seconds of the oldest export bundle (done: expiresAt+grace passed; failed: orphaned ZIP since completedAt or startedAt) whose downloadStorageKey is still set. 0 when the storage-cleanup pass has no backlog.",
+    });
+    r.metric(EXPORT_CLEANUP_LAST_RUN_TIMESTAMP_METRIC, {
+      type: "gauge",
+      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.
+    const RUN_EXPORT_JOBS_REASON = "processes pending export jobs across every tenant";
+    r.job({
+      name: "run-export-jobs",
+      trigger: { cron: "0 3 * * *" },
+      concurrency: "skip",
+      escapeHatch: { reason: RUN_EXPORT_JOBS_REASON },
+      handler: async (_payload, ctx) => {
+        if (!ctx.registry) {
+          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.
+        const exportUserId = ctx._userId ?? SYSTEM_USER_ID;
+        const exportDb = ctx.db.unsafeRaw(
+          RUN_EXPORT_JOBS_REASON,
+        ) as import("@cosmicdrift/kumiko-framework/db").DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
+        const exportRegistry = ctx.registry;
+        // JobContext carries ctx.meter (raw), not ctx.metrics — that bound
+        // handle only exists on HandlerContext (built per write/query call
+        // in dispatch-shared.ts). Build the same handle explicitly here.
+        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.
+        const exportMailResolver = isMailTransportAvailable(exportRegistry)
+          ? makeTenantMailTransportResolver({
+              registry: exportRegistry,
+              configResolver: ctx.configResolver,
+              secrets: ctx.secrets,
+              db: exportDb,
+              userId: exportUserId,
+              handlerName: "user-data-rights:run-export-jobs",
+            })
+          : undefined;
+        const sendExportReadyEmail =
+          opts.sendExportReadyEmail ??
+          (exportMailResolver && opts.appExportDownloadUrl !== undefined
+            ? makeDefaultExportReadyEmail(exportMailResolver, opts.mailDefaults)
+            : undefined);
+        const sendExportFailedEmail =
+          opts.sendExportFailedEmail ??
+          (exportMailResolver
+            ? makeDefaultExportFailedEmail(exportMailResolver, opts.mailDefaults)
+            : undefined);
+        if (
+          exportMailResolver &&
+          !opts.sendExportReadyEmail &&
+          opts.appExportDownloadUrl === undefined &&
+          !warnedMissingExportUrl
+        ) {
+          warnedMissingExportUrl = true;
+          // biome-ignore lint/suspicious/noConsole: one-shot operator visibility for misconfig
+          console.warn(
+            "[user-data-rights:run-export-jobs] mail transport mounted but appExportDownloadUrl unset — default export-ready emails disabled (export-failed + deletion mails still send)",
+          );
+        }
+
+        await runExportJobs({
+          db: exportDb,
+          registry: exportRegistry,
+          // Per-tenant provider from the mounted file-foundation. The cron
+          // context carries configResolver (not the per-request ConfigAccessor),
+          // so the resolver builds a per-tenant accessor from it — otherwise
+          // createFileProviderForTenant throws and every export lands on failed.
+          buildStorageProvider: makeTenantStorageProviderResolver({
+            registry: exportRegistry,
+            configResolver: ctx.configResolver,
+            secrets: ctx.secrets,
+            db: exportDb,
+            userId: exportUserId,
+            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.
+          ...(sendExportReadyEmail && { sendExportReadyEmail }),
+          ...(sendExportFailedEmail && { sendExportFailedEmail }),
+          ...(opts.appExportDownloadUrl !== undefined && {
+            appExportDownloadUrl: opts.appExportDownloadUrl,
+          }),
+          escapeHatchAuditSink: ctx._escapeHatchAuditSink,
+          actor: ctx.systemUser.id,
+          metrics: exportMetrics,
+        });
+      },
+    });
+
+    // 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.
+    const RUN_FORGET_CLEANUP_REASON = "executes overdue Art.17 forget requests across every tenant";
+    r.job({
+      name: "run-forget-cleanup",
+      trigger: { cron: "0 3 * * *" },
+      concurrency: "skip",
+      escapeHatch: { reason: RUN_FORGET_CLEANUP_REASON },
+      handler: async (_payload, ctx) => {
+        if (!ctx.registry) {
+          throw new Error("run-forget-cleanup: ctx.registry required (JobContext incomplete)");
+        }
+        const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
+        const forgetUserId = ctx._userId ?? SYSTEM_USER_ID;
+        const forgetDb = ctx.db.unsafeRaw(
+          RUN_FORGET_CLEANUP_REASON,
+        ) as import("@cosmicdrift/kumiko-framework/db").DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
+        const forgetRegistry = ctx.registry;
+        const tenantModel = await resolveAppTenantModel({
+          registry: forgetRegistry,
+          configResolver: ctx.configResolver,
+          db: forgetDb,
+          userId: forgetUserId,
+        });
+
+        // C6 — Default-Mail beim delete-flip wenn kein Callback gesetzt + ein
+        // mail-transport gemountet ist (gleiche per-Tenant-Bruecke wie Export).
+        const forgetMailResolver = isMailTransportAvailable(forgetRegistry)
+          ? makeTenantMailTransportResolver({
+              registry: forgetRegistry,
+              configResolver: ctx.configResolver,
+              secrets: ctx.secrets,
+              db: forgetDb,
+              userId: forgetUserId,
+              handlerName: "user-data-rights:run-forget-cleanup",
+            })
+          : undefined;
+        const sendDeletionExecutedEmail =
+          opts.sendDeletionExecutedEmail ??
+          (forgetMailResolver
+            ? makeDefaultDeletionExecutedEmail(forgetMailResolver, opts.mailDefaults)
+            : undefined);
+
+        const forgetResult = await runForgetCleanup({
+          db: forgetDb,
+          registry: forgetRegistry,
+          now: T.Now.instant(),
+          tenantModel,
+          ...(ctx.searchAdapter !== undefined && { searchAdapter: ctx.searchAdapter }),
+          // Same per-tenant provider resolution as the export cron — forget
+          // deletes binaries from the store upload + export use.
+          buildStorageProvider: makeTenantStorageProviderResolver({
+            registry: forgetRegistry,
+            configResolver: ctx.configResolver,
+            secrets: ctx.secrets,
+            db: forgetDb,
+            userId: forgetUserId,
+            handlerName: "user-data-rights:run-forget-cleanup",
+          }),
+          ...(sendDeletionExecutedEmail && { sendDeletionExecutedEmail }),
+          escapeHatchAuditSink: ctx._escapeHatchAuditSink,
+          actor: ctx.systemUser.id,
+        });
+
+        // Persist each incomplete report on the job-run log (#1572). 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.
+        for (const entry of forgetResult.incomplete) {
+          ctx.log?.warn?.(
+            `[user-data-rights:run-forget-cleanup] incomplete hook ` +
+              `userId=${entry.userId} tenantId=${entry.tenantId} ` +
+              `entityName=${entry.entityName} rolledBack=${entry.rolledBack} ` +
+              `reason=${sanitizeReasonForLog(entry.reason)}`,
+          );
+        }
+      },
+    });
+  });
+}
+
+// `clientIp` comes from the server's trustedProxyHops-aware resolver instead
+// of reading X-Forwarded-For here, where a forged first entry would spoof the
+// audit IP. A caller hitting /api/query directly (bypassing this httpRoute
+// wrapper) with its own auditMeta can still lie — accepted, see
+// download-by-token.query.ts.
+export function extractAuditMeta(
+  headers: Headers,
+  clientIp: string,
+): { ip: string | null; userAgent: string | null } {
+  return {
+    ip: clientIp === UNKNOWN_CLIENT_IP ? null : clientIp,
+    userAgent: headers.get("user-agent"),
+  };
+}
+
+// Interstitial page for the magic-link fragment exchange (see the
+// httpRoute above). Plain static markup — no build step, no i18n lookup
+// (the server doesn't know a user locale here; anonymous path).
+const TOKEN_EXCHANGE_PAGE_HTML = `<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>Export Download</title></head>
+<body>
+<p id="status">Preparing your download…</p>
+<script src="/user-export/by-token.js"></script>
+</body>
+</html>`;
+
+// Reads the token client-side from the URL fragment (never sent to the
+// server) and exchanges it via POST for the signed URL. Same-origin
+// external file instead of inline <script>, so the page also works under
+// a strict `script-src 'self'` CSP.
+const TOKEN_EXCHANGE_PAGE_JS = `(async () => {
+  const status = document.getElementById("status");
+  const params = new URLSearchParams(location.hash.slice(1));
+  const token = params.get("token");
+  if (!token) {
+    status.textContent = "Invalid download link.";
+    return;
+  }
+  try {
+    const res = await fetch("/user-export/by-token", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ token }),
+    });
+    const body = await res.json();
+    if (!res.ok || !body || !body.data || !body.data.url) {
+      status.textContent = "This download link is invalid or has expired.";
+      return;
+    }
+    location.href = body.data.url;
+  } catch {
+    status.textContent = "Could not start the download.";
+  }
+})();`;