@cosmicdrift/kumiko-bundled-features 0.2.2 → 0.3.0

package/src/user-data-rights/feature.ts

@@ -0,0 +1,310 @@
+import {
+  defineFeature,
+  EXT_USER_DATA,
+  type FeatureDefinition,
+  SYSTEM_USER_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createFileProviderForTenant } from "../file-foundation";
+import { cancelDeletionWrite } from "./handlers/cancel-deletion.write";
+import { downloadByJobQuery } from "./handlers/download-by-job.query";
+import { downloadByTokenQuery } from "./handlers/download-by-token.query";
+import { exportStatusQuery } from "./handlers/export-status.query";
+import { liftRestrictionWrite } from "./handlers/lift-restriction.write";
+import { listDownloadAttemptsQuery } from "./handlers/list-download-attempts.query";
+import { myAuditLogQuery } from "./handlers/my-audit-log.query";
+import {
+  createRequestDeletionHandler,
+  type SendDeletionRequestedEmailFn,
+} from "./handlers/request-deletion.write";
+import { requestExportWrite } from "./handlers/request-export.write";
+import { restrictAccountWrite } from "./handlers/restrict-account.write";
+import { createRunForgetCleanupHandler } from "./handlers/run-forget-cleanup.write";
+import {
+  runExportJobs,
+  type SendExportFailedEmailFn,
+  type SendExportReadyEmailFn,
+} from "./run-export-jobs";
+import type { SendDeletionExecutedEmailFn } from "./run-forget-cleanup";
+import { downloadAttemptEntity } from "./schema/download-attempt";
+import { exportDownloadTokenEntity } from "./schema/download-token";
+import { exportJobEntity } from "./schema/export-job";
+
+// 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
+   *  `${appExportDownloadUrl}?token=<plain>`. 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;
+};
+
+export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): FeatureDefinition {
+  return defineFeature("user-data-rights", (r) => {
+    r.requires("user", "data-retention", "compliance-profiles");
+    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, {});
+
+    // 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 }
+          : {},
+      ),
+    );
+    r.writeHandler(cancelDeletionWrite);
+
+    // 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);
+
+    // r.httpRoute-Wrapper: Magic-Link-Pfad (anonymous) + UI-Klick-Pfad.
+    //
+    // Beide rufen via app.fetch /api/query → wenn success: 302-Redirect
+    // zur signed-URL → Browser folgt → Download startet beim Object-Store.
+    // Bei error: passthrough (404/410/501) als JSON.
+    //
+    // **Token-Pfad (anonymous):** GET /user-export/by-token?token=<plain>
+    //
+    // Path liegt AUSSERHALB /api/* weil r.httpRoute den /api-namespace
+    // nicht claimen darf (reserved fuer write/query/batch/auth/sse-
+    // dispatcher).
+    r.httpRoute({
+      method: "GET",
+      path: "/user-export/by-token",
+      anonymous: true,
+      handler: async (c, { app }) => {
+        const url = new URL(c.req.url);
+        const token = url.searchParams.get("token");
+        if (!token) {
+          return c.json({ error: "missing_token" }, 400);
+        }
+        const queryRes = await 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: extractAuditMeta(c.req.raw.headers) },
+            }),
+          }),
+        );
+        return mapQueryResponseToRedirect(c, queryRes);
+      },
+    });
+
+    // **Session-Pfad (auth):** GET /user-export/by-job/:jobId
+    r.httpRoute({
+      method: "GET",
+      path: "/user-export/by-job/:jobId",
+      handler: async (c, { app }) => {
+        const url = new URL(c.req.url);
+        const jobId = c.req.param("jobId");
+        if (!jobId) {
+          return c.json({ error: "missing_job_id" }, 400);
+        }
+        const queryRes = await app.fetch(
+          new Request(`${url.origin}/api/query`, {
+            method: "POST",
+            headers: {
+              "content-type": "application/json",
+              ...forwardAuthHeaders(c.req.raw.headers),
+            },
+            body: JSON.stringify({
+              type: "user-data-rights:query:download-by-job",
+              payload: { jobId, auditMeta: extractAuditMeta(c.req.raw.headers) },
+            }),
+          }),
+        );
+        return mapQueryResponseToRedirect(c, queryRes);
+      },
+    });
+
+    // S2.U3 Atom 3b — Worker fuer Async Export-Pipeline. Cron-getriggert.
+    r.job(
+      "run-export-jobs",
+      { trigger: { cron: "0 * * * * *" }, concurrency: "skip" },
+      async (_payload, ctx) => {
+        if (!ctx.db || !ctx.registry) {
+          throw new Error(
+            "run-export-jobs: ctx.db + 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 providerCtx = {
+          config: ctx.config,
+          registry: ctx.registry,
+          secrets: ctx.secrets,
+          _userId: ctx._userId ?? SYSTEM_USER_ID,
+        };
+        await runExportJobs({
+          db: ctx.db as import("@cosmicdrift/kumiko-framework/db").DbConnection, // @cast-boundary db-operator
+          registry: ctx.registry,
+          buildStorageProvider: async (tenantId) =>
+            createFileProviderForTenant(providerCtx, tenantId, "user-data-rights:run-export-jobs"),
+          now: T.Now.instant(),
+          // Atom 5 — App-Author-Callbacks fuer Email-Notification.
+          // Optional: wenn nicht gesetzt, kein Email; User pollt
+          // export-status.query + UI-Klick.
+          ...(opts.sendExportReadyEmail && {
+            sendExportReadyEmail: opts.sendExportReadyEmail,
+          }),
+          ...(opts.sendExportFailedEmail && {
+            sendExportFailedEmail: opts.sendExportFailedEmail,
+          }),
+          ...(opts.appExportDownloadUrl !== undefined && {
+            appExportDownloadUrl: opts.appExportDownloadUrl,
+          }),
+        });
+      },
+    );
+  });
+}
+
+// Map /api/query-Response auf 302-Redirect oder Error-Passthrough.
+async function mapQueryResponseToRedirect(
+  c: import("hono").Context,
+  queryRes: Response,
+): Promise<Response> {
+  if (!queryRes.ok) {
+    const errorBody = await queryRes.text();
+    const statusCode = queryRes.status as 400 | 401 | 404 | 410 | 500; // @cast-boundary engine-payload
+    return c.body(errorBody, statusCode, {
+      "content-type": queryRes.headers.get("content-type") ?? "application/json",
+    });
+  }
+  const body = (await queryRes.json()) as { data?: { url?: string } }; // @cast-boundary engine-payload
+  if (!body.data?.url) {
+    return c.json({ error: "download_resolution_failed" }, 500);
+  }
+  return c.redirect(body.data.url, 302);
+}
+
+function forwardAuthHeaders(headers: Headers): Record<string, string> {
+  const out: Record<string, string> = {};
+  const auth = headers.get("authorization");
+  if (auth) out["authorization"] = auth;
+  const cookie = headers.get("cookie");
+  if (cookie) out["cookie"] = cookie;
+  return out;
+}
+
+// Extract Audit-Meta (IP + UA) aus den HTTP-Headers + steck es in die
+// query-payload. Der httpRoute-Wrapper ist trusted-source — er hat den
+// raw-request gesehen, nicht der direkter /api/query-Caller. User der
+// /api/query direkt mit eigenem auditMeta aufruft kann luegen, aber
+// auditMeta ist nicht security-relevant (operator kann mit server-logs
+// crossreferencen wenn forensik gebraucht).
+function extractAuditMeta(headers: Headers): { ip: string | null; userAgent: string | null } {
+  const xff = headers.get("x-forwarded-for");
+  let ip: string | null = null;
+  if (xff) {
+    const first = xff.split(",")[0]?.trim();
+    if (first && first.length > 0) ip = first;
+  }
+  if (!ip) {
+    const real = headers.get("x-real-ip");
+    if (real && real.length > 0) ip = real;
+  }
+  return { ip, userAgent: headers.get("user-agent") };
+}

package/src/user-data-rights/handlers/cancel-deletion.write.ts

@@ -0,0 +1,84 @@
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { eq, sql } from "drizzle-orm";
+import { z } from "zod";
+import { USER_STATUS, userTable } from "../../user";
+
+// POST /api/user/cancel-deletion (S2.U5).
+//
+// Innerhalb der Grace-Period kann User seinen Forget-Antrag zurueck-
+// nehmen. Setzt:
+//   - status = "active"
+//   - gracePeriodEnd = null
+//
+// Nach Grace-Period: 422 (run-forget-cleanup hat in der Zwischenzeit
+// die Hooks schon getriggert — Reversal nicht moeglich).
+//
+// Sonderfall: Cancel als "active"-User → 422 (kein pending Forget).
+export const cancelDeletionWrite = defineWriteHandler({
+  name: "cancel-deletion",
+  schema: z.object({}),
+  access: { openToAll: true },
+  handler: async (event, ctx) => {
+    // ctx.db.raw (kein TenantDb-Wrapper) weil User-Entity tenant-agnostisch
+    // ist — siehe request-deletion.write.ts fuer die Begruendung. Cancel
+    // muss aus jedem Tenant-Mode den User finden + zuruecksetzen koennen.
+    //
+    // Combined query: status + grace_period_end-vs-now in einem Pass.
+    const checkRows = await ctx.db.raw
+      .select({
+        status: userTable["status"],
+        inGrace: sql<boolean>`(${userTable["gracePeriodEnd"]} > now())`,
+      })
+      .from(userTable)
+      .where(eq(userTable["id"], event.user.id))
+      .limit(1);
+
+    if (checkRows.length === 0) {
+      return writeFailure(
+        new UnprocessableError("user_not_found", {
+          details: { reason: "user_not_found", userId: event.user.id },
+        }),
+      );
+    }
+
+    const row = checkRows[0];
+    if (!row || row.status !== USER_STATUS.DeletionRequested) {
+      return writeFailure(
+        new UnprocessableError("no_pending_deletion", {
+          details: {
+            reason: "no_pending_deletion",
+            currentStatus: row?.status,
+          },
+        }),
+      );
+    }
+
+    if (!row.inGrace) {
+      return writeFailure(
+        new UnprocessableError("grace_period_expired", {
+          details: { reason: "grace_period_expired" },
+        }),
+      );
+    }
+
+    await ctx.db.raw
+      .update(userTable)
+      .set({
+        status: USER_STATUS.Active,
+        gracePeriodEnd: null,
+      })
+      .where(eq(userTable["id"], event.user.id));
+
+    // gracePeriodEnd=null im Response symmetrisch zu request-deletion's
+    // ISO-Timestamp — Frontend kann beide Endpoints uniform behandeln.
+    return {
+      isSuccess: true as const,
+      data: {
+        userId: event.user.id,
+        status: USER_STATUS.Active,
+        gracePeriodEnd: null as string | null, // @cast-boundary generic-record
+      },
+    };
+  },
+});

package/src/user-data-rights/handlers/download-by-job.query.ts

@@ -0,0 +1,206 @@
+// GET /api/query → user-data-rights:query:download-by-job (S2.U3 Atom 4b).
+//
+// **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).
+//
+// **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-User-Isolation:** Wenn session.userId != job.userId → 404
+// (NICHT 403, kein Existenz-Leak). Selber error wie "Job-ID nicht
+// gefunden".
+//
+// 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)
+//   7. Return {url, expiresAt}
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { createFileProviderForTenant } from "../../file-foundation";
+import { recordDownloadUse, recordInvalidAttempt } from "../audit-download";
+import { exportDownloadTokensTable } from "../schema/download-token";
+import { EXPORT_JOB_STATUS, exportJobsTable } from "../schema/export-job";
+
+const SIGNED_URL_TTL_SECONDS = 300; // 5 min — matched download-by-token
+
+interface TokenRow {
+  readonly id: string;
+  readonly version: number;
+  readonly useCount: number | null;
+}
+
+interface JobRow {
+  readonly id: string;
+  readonly userId: string;
+  readonly requestedFromTenantId: string;
+  readonly status: string;
+  readonly downloadStorageKey: string | null;
+  readonly bytesWritten: number | null;
+}
+
+export const downloadByJobQuery = defineQueryHandler({
+  name: "download-by-job",
+  schema: z.object({
+    jobId: z.string().min(1, "jobId required"),
+    auditMeta: z
+      .object({
+        ip: z.string().nullable(),
+        userAgent: z.string().nullable(),
+      })
+      .optional(),
+  }),
+  access: { openToAll: true }, // openToAll = auth-required, kein anonymous
+  handler: async (query, ctx) => {
+    const T = getTemporal();
+    const now = T.Now.instant();
+    const userId = query.user.id;
+    const jobId = query.payload.jobId;
+    const tenantId = query.user.tenantId;
+    const auditIp = query.payload.auditMeta?.ip ?? null;
+    const auditUa = query.payload.auditMeta?.userAgent ?? null;
+
+    // Step 1-2: job-lookup + cross-user-isolation
+    // ctx.db.raw weil tenant-agnostisch — Alice in Tenant B sucht den
+    // aus Tenant A erstellten Job.
+    const jobRow = (await fetchOne(
+      ctx.db.raw,
+      exportJobsTable,
+      eq(exportJobsTable["id"], jobId),
+    )) as JobRow | null; // @cast-boundary db-row
+
+    if (!jobRow || jobRow.userId !== userId) {
+      await recordInvalidAttempt({
+        db: ctx.db.raw as DbConnection, // @cast-boundary db-runner
+        tenantId,
+        now,
+        result: "notFound",
+        via: "job",
+        tokenHash: null,
+        jobId,
+        attemptedByUserId: userId,
+        ip: auditIp,
+        userAgent: auditUa,
+      });
+      throw new NotFoundError("export-download", jobId, {
+        i18nKey: "userDataRights.errors.download.notFound",
+      });
+    }
+
+    if (jobRow.status !== EXPORT_JOB_STATUS.Done) {
+      await recordInvalidAttempt({
+        db: ctx.db.raw as DbConnection, // @cast-boundary db-runner
+        tenantId,
+        now,
+        result: "failed",
+        via: "job",
+        tokenHash: null,
+        jobId,
+        attemptedByUserId: userId,
+        ip: auditIp,
+        userAgent: auditUa,
+      });
+      throw new NotFoundError("export-download", jobId, {
+        i18nKey: "userDataRights.errors.download.unavailable",
+      });
+    }
+    if (!jobRow.downloadStorageKey) {
+      await recordInvalidAttempt({
+        db: ctx.db.raw as DbConnection, // @cast-boundary db-runner
+        tenantId,
+        now,
+        result: "expired",
+        via: "job",
+        tokenHash: null,
+        jobId,
+        attemptedByUserId: userId,
+        ip: auditIp,
+        userAgent: auditUa,
+      });
+      throw new NotFoundError("export-download", jobId, {
+        i18nKey: "userDataRights.errors.download.expired",
+      });
+    }
+
+    const provider = await createFileProviderForTenant(
+      ctx,
+      jobRow.requestedFromTenantId,
+      "user-data-rights:query:download-by-job",
+    );
+    if (!provider.getSignedUrl) {
+      await recordInvalidAttempt({
+        db: ctx.db.raw as DbConnection, // @cast-boundary db-runner
+        tenantId,
+        now,
+        result: "signedUrlNotSupported",
+        via: "job",
+        tokenHash: null,
+        jobId,
+        attemptedByUserId: userId,
+        ip: auditIp,
+        userAgent: auditUa,
+      });
+      throw new UnprocessableError("storage_provider_signed_url_not_supported", {
+        i18nKey: "userDataRights.errors.download.signedUrlNotSupported",
+      });
+    }
+
+    const signedUrl = await provider.getSignedUrl(
+      jobRow.downloadStorageKey,
+      SIGNED_URL_TTL_SECONDS,
+      {
+        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.
+    const tokenRow = (await fetchOne(
+      ctx.db.raw,
+      exportDownloadTokensTable,
+      eq(exportDownloadTokensTable["jobId"], jobId),
+    )) as TokenRow | null; // @cast-boundary db-row
+
+    if (tokenRow) {
+      await recordDownloadUse({
+        db: ctx.db.raw as DbConnection, // @cast-boundary db-runner
+        tokenId: tokenRow.id,
+        tokenVersion: tokenRow.version,
+        tokenUseCount: tokenRow.useCount ?? 0,
+        tenantId: jobRow.requestedFromTenantId as Parameters<
+          typeof recordDownloadUse
+        >[0]["tenantId"], // @cast-boundary engine-bridge
+        now,
+        ip: query.payload.auditMeta?.ip ?? null,
+        userAgent: query.payload.auditMeta?.userAgent ?? null,
+      });
+    }
+    // Wenn tokenRow fehlt (sollte nicht passieren wenn Atom 4a sauber
+    // lief): Audit-Update skipped, Download laeuft weiter. Niemand wird
+    // hier durch Audit-Failure blockiert.
+
+    return {
+      url: signedUrl,
+      expiresAt: signedUrlExpiresAt.toString(),
+      bytesWritten: jobRow.bytesWritten,
+    };
+  },
+});