@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/user-data-rights/handlers/lift-restriction.write.ts

@@ -1,24 +1,33 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
-import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  AccessDeniedError,
+  UnprocessableError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
+import { tenantMembershipsTable } from "../../tenant";
 import { USER_STATUS, userTable } from "../../user";
+import { isSystemAdminActor } from "../lib/is-admin-actor";
 import { updateUserLifecycle } from "../lib/update-user-lifecycle";
 
 // POST /api/user/lift-restriction (S2.U6) — DSGVO Art. 18 Reverse.
 //
-// **Wichtige Eigenheit:** Der User kann diesen Endpoint NICHT selber
-// aufrufen weil sein Login geblockt ist (Restricted-Status, siehe
-// login.write.ts Atom 3). Wer ein Restricted-Konto wieder aktiviert,
-// muss dafuer einen anderen Pfad nutzen — typisch Operator-Tool oder
-// Email-Magic-Link an die User-Email. App-Author entscheidet das per
-// access-Konfig oder Custom-Wrapper.
+// Operator-only. A Restricted user's own session is unconditionally
+// rejected by sessionChecker (BLOCKED_STATUSES) the moment their status
+// flips — their JWT/login can't reach this or any other authenticated
+// endpoint. There is no self-service path today, so lifting a restriction
+// always targets someone else's account by id.
 //
-// MVP-Default: openToAll mit Self-Service-Semantik. Die Asymmetrie
-// (User koennte sich selbst freischalten WENN er einen Weg ohne Login
-// hat — z.B. valid Magic-Link aus pre-Restriction) ist akzeptabel:
-// Restriction ist *Verarbeitungs-Pause*, nicht *Sperre durch Operator*.
-// User der "ich will doch wieder mitmachen" sagt, soll das koennen.
+// Tenant scope: `access.admin` includes TenantAdmin, which is tenant-
+// scoped even though the User-entity lookup below uses `ctx.db.raw`
+// (bypasses the auto-tenant-filter, same as restrict-account.write.ts —
+// User status is intentionally global, see user-data-rights.md
+// "Cross-Tenant-Semantik"). Without a membership check, a TenantAdmin
+// from tenant A could unrestrict/reactivate a user who has never been a
+// member of tenant A. Only SystemAdmin (platform-wide) skips the check;
+// TenantAdmin/Admin must have an active membership in the target's own
+// tenantId.
 //
 // State-Transitions:
 //   Restricted → Active        ✓
@@ -27,17 +36,33 @@ import { updateUserLifecycle } from "../lib/update-user-lifecycle";
 //   Deleted → ...              ✗ 422 not_restricted
 export const liftRestrictionWrite = defineWriteHandler({
   name: "lift-restriction",
-  schema: z.object({}),
-  access: { openToAll: true },
+  schema: z.object({ userId: z.string().uuid() }),
+  access: { roles: access.admin },
   handler: async (event, ctx) => {
+    const targetUserId = event.payload.userId;
+
+    if (!isSystemAdminActor(event.user)) {
+      const membership = await fetchOne(ctx.db.raw, tenantMembershipsTable, {
+        userId: targetUserId,
+        tenantId: event.user.tenantId,
+      });
+      if (!membership) {
+        return writeFailure(
+          new AccessDeniedError({
+            details: { reason: "target_user_not_in_admin_tenant" },
+          }),
+        );
+      }
+    }
+
     const userRow = await fetchOne<{ status: string }>(ctx.db.raw, userTable, {
-      id: event.user.id,
+      id: targetUserId,
     });
 
     if (!userRow) {
       return writeFailure(
         new UnprocessableError("user_not_found", {
-          details: { reason: "user_not_found", userId: event.user.id },
+          details: { reason: "user_not_found", userId: targetUserId },
         }),
       );
     }
@@ -51,12 +76,12 @@ export const liftRestrictionWrite = defineWriteHandler({
       );
     }
 
-    await updateUserLifecycle(ctx.db.raw, event.user.id, { status: USER_STATUS.Active });
+    await updateUserLifecycle(ctx.db.raw, targetUserId, { status: USER_STATUS.Active });
 
     return {
       isSuccess: true as const,
       data: {
-        userId: event.user.id,
+        userId: targetUserId,
         status: USER_STATUS.Active,
       },
     };

package/src/user-data-rights/handlers/list-download-attempts.query.ts

@@ -1,5 +1,6 @@
 import { selectMany, type WhereObject } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { Temporal } from "temporal-polyfill";
 import { z } from "zod";
 import { downloadAttemptsTable } from "../schema/download-attempt";
 

package/src/user-data-rights/handlers/my-audit-log.query.ts

@@ -1,6 +1,7 @@
 import { selectMany, type WhereObject } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { Temporal } from "temporal-polyfill";
 import { z } from "zod";
 
 // DSGVO Art. 15 Selbstauskunft — User reads HIS OWN audit-log.

package/src/user-data-rights/handlers/request-deletion-by-email.write.ts

@@ -95,7 +95,9 @@ export function createRequestDeletionByEmailHandler(opts: RequestDeletionByEmail
       if (opts.sendDeletionVerificationEmail) {
         try {
           await opts.sendDeletionVerificationEmail({
-            email: userRow["email"],
+            // Row value is ciphertext with an active KMS; the lookup above
+            // only matches byte-exact, so the payload IS the stored plaintext.
+            email: event.payload.email,
             verifyUrl,
             expiresAt: expiresAt.toString(),
           });

package/src/user-data-rights/handlers/restrict-account.write.ts

@@ -1,8 +1,14 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createSystemUser, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
-import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  AccessDeniedError,
+  UnprocessableError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
+import { tenantMembershipsTable } from "../../tenant";
 import { USER_STATUS, userTable } from "../../user";
+import { isAdminActor, isSystemAdminActor } from "../lib/is-admin-actor";
 import { updateUserLifecycle } from "../lib/update-user-lifecycle";
 
 // POST /api/user/restrict (S2.U6) — DSGVO Art. 18 Account-Freeze.
@@ -15,6 +21,22 @@ import { updateUserLifecycle } from "../lib/update-user-lifecycle";
 //     muss gemountet sein). App-Author ohne sessions-feature kriegt einen
 //     Boot-Resolver-Error via r.usesApi("sessions.revokeAllForUser").
 //
+// Self-service by default (userId omitted → event.user.id). An admin can
+// also target someone else's account — needed once a user is already
+// Restricted, since their own session is then unconditionally rejected by
+// sessionChecker and they can no longer call this (or any) endpoint
+// themselves; only an operator path reaches it at that point.
+//
+// Tenant scope: `isAdminActor` accepts access.admin, which includes
+// TenantAdmin — tenant-scoped, even though the User-entity lookup below
+// uses `ctx.db.raw` (bypasses the auto-tenant-filter, same as
+// lift-restriction.write.ts — User status is intentionally global, see
+// user-data-rights.md "Cross-Tenant-Semantik"). Without a membership
+// check, a TenantAdmin from tenant A could restrict/unrestrict a user who
+// has never been a member of tenant A. Only SystemAdmin (platform-wide)
+// skips the check; TenantAdmin/Admin must have an active membership in
+// the target's own tenantId.
+//
 // State-Transitions:
 //   Active → Restricted        ✓ (dieser Handler)
 //   Restricted → Restricted    ✗ 422 already_restricted (Idempotenz-Guard)
@@ -22,19 +44,48 @@ import { updateUserLifecycle } from "../lib/update-user-lifecycle";
 //   Deleted → ...              ✗ 422 user_not_in_active_state
 export const restrictAccountWrite = defineWriteHandler({
   name: "restrict-account",
-  schema: z.object({}),
+  schema: z.object({ userId: z.string().uuid().optional() }),
   access: { openToAll: true },
   handler: async (event, ctx) => {
+    const targetUserId = event.payload.userId ?? event.user.id;
+    if (targetUserId !== event.user.id) {
+      if (!isAdminActor(event.user)) {
+        return writeFailure(
+          new AccessDeniedError({
+            details: { reason: "admin_required_for_other_user" },
+          }),
+        );
+      }
+      // Same cross-tenant guard as lift-restriction.write.ts: only
+      // SystemAdmin (platform-wide) may target a user without an active
+      // membership in the caller's own tenant. Without this, a TenantAdmin
+      // from tenant A could restrict — and force-revoke the sessions of —
+      // a user who has never been a member of tenant A.
+      if (!isSystemAdminActor(event.user)) {
+        const membership = await fetchOne(ctx.db.raw, tenantMembershipsTable, {
+          userId: targetUserId,
+          tenantId: event.user.tenantId,
+        });
+        if (!membership) {
+          return writeFailure(
+            new AccessDeniedError({
+              details: { reason: "target_user_not_in_admin_tenant" },
+            }),
+          );
+        }
+      }
+    }
+
     // ctx.db.raw weil User-Entity tenant-agnostisch ist (analog
     // request-deletion.write.ts Cross-Tenant-Section).
     const userRow = await fetchOne<{ status: string }>(ctx.db.raw, userTable, {
-      id: event.user.id,
+      id: targetUserId,
     });
 
     if (!userRow) {
       return writeFailure(
         new UnprocessableError("user_not_found", {
-          details: { reason: "user_not_found", userId: event.user.id },
+          details: { reason: "user_not_found", userId: targetUserId },
         }),
       );
     }
@@ -55,7 +106,7 @@ export const restrictAccountWrite = defineWriteHandler({
       );
     }
 
-    await updateUserLifecycle(ctx.db.raw, event.user.id, { status: USER_STATUS.Restricted });
+    await updateUserLifecycle(ctx.db.raw, targetUserId, { status: USER_STATUS.Restricted });
 
     // Cross-Feature: alle live sessions revoken — sonst koennte der User
     // mit existierendem JWT bis zur Token-Expiry weiter schreiben.
@@ -63,13 +114,13 @@ export const restrictAccountWrite = defineWriteHandler({
     // System-User-Roles im access-gate hat.
     const systemUser = createSystemUser(event.user.tenantId);
     await ctx.writeAs(systemUser, "sessions:write:user-session:revoke-all-for-user", {
-      userId: event.user.id,
+      userId: targetUserId,
     });
 
     return {
       isSuccess: true as const,
       data: {
-        userId: event.user.id,
+        userId: targetUserId,
         status: USER_STATUS.Restricted,
       },
     };

package/src/user-data-rights/handlers/run-forget-cleanup.write.ts

@@ -77,6 +77,8 @@ export function createRunForgetCleanupHandler(opts: RunForgetCleanupOptions = {}
           hookCallsAttempted: result.hookCallsAttempted,
           errorCount: result.errors.length,
           errors: result.errors,
+          incompleteCount: result.incomplete.length,
+          incomplete: result.incomplete,
         },
       };
     },

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

@@ -1,37 +1,40 @@
 // @runtime client
-//
-// Default-Translations fuer user-data-rights Error-Wire-Keys (S2.U3 Atom 4b.fix3).
-//
-// Wire-Errors aus den download-handlers tragen i18nKeys statt fixe
-// Strings — UI rendert die Keys ueber den Renderer-LocaleProvider. Apps
-// koennen einzelne Keys via `userDataRightsClient({ translations: { de:
-// {...} } })` ueberschreiben (Pattern matched auth-email-password).
-//
-// **Scope 4b.fix3:** nur die download-error-keys. Andere Keys (UI-
-// Texte fuer Forget-Pfad, Status-Labels, Banner) kommen mit Atom 6+
-// (UI-Integration).
+// Server + client i18n for user-data-rights (operator screens + nav). Pure
+// data, importable from the web bundle (web/i18n.ts derives the client keys).
+type LocalizedString = { readonly de: string; readonly en: string };
 
-import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
-
-export const defaultTranslations: TranslationsByLocale = {
-  de: {
-    "userDataRights.errors.download.notFound":
-      "Der Download-Link ist ungültig oder gehört zu einem anderen Konto.",
-    "userDataRights.errors.download.expired":
-      "Dein Download ist abgelaufen. Bitte fordere einen neuen Export an.",
-    "userDataRights.errors.download.unavailable":
-      "Der Export ist noch nicht fertig oder fehlgeschlagen. Bitte schau im Status-Polling nach.",
-    "userDataRights.errors.download.signedUrlNotSupported":
-      "Der Download steht aufgrund einer Server-Konfiguration aktuell nicht zur Verfügung. Der Operator wurde benachrichtigt.",
+export const USER_DATA_RIGHTS_I18N: Readonly<Record<string, LocalizedString>> = {
+  "user-data-rights:nav.exportJobs": { de: "DSGVO-Exporte", en: "GDPR exports" },
+  "screen:export-job-list.title": { de: "DSGVO-Exporte", en: "GDPR exports" },
+  "screen:export-job-detail.title": { de: "Export-Job", en: "Export job" },
+  "screen:download-attempt-list.title": { de: "Download-Versuche", en: "Download attempts" },
+  "screen:privacy-center.title": { de: "Datenschutz", en: "Privacy" },
+  "user-data-rights:entity:export-job:field:userId": { de: "Benutzer", en: "User" },
+  "user-data-rights:entity:export-job:field:status": { de: "Status", en: "Status" },
+  "user-data-rights:entity:export-job:field:requestedAt": { de: "Angefordert", en: "Requested" },
+  "user-data-rights:entity:export-job:field:completedAt": { de: "Abgeschlossen", en: "Completed" },
+  "user-data-rights:entity:export-job:field:expiresAt": { de: "Läuft ab", en: "Expires" },
+  "user-data-rights:entity:export-job:field:requestedFromTenantId": {
+    de: "Mandant",
+    en: "Tenant",
+  },
+  "user-data-rights:entity:export-job:field:startedAt": { de: "Gestartet", en: "Started" },
+  "user-data-rights:entity:export-job:field:downloadStorageKey": {
+    de: "Speicher-Schlüssel",
+    en: "Storage key",
+  },
+  "user-data-rights:entity:export-job:field:bytesWritten": { de: "Bytes", en: "Bytes" },
+  "user-data-rights:entity:export-job:field:errorMessage": { de: "Fehler", en: "Error" },
+  "user-data-rights:entity:download-attempt:field:attemptedAt": {
+    de: "Zeitpunkt",
+    en: "Attempted at",
   },
-  en: {
-    "userDataRights.errors.download.notFound":
-      "The download link is invalid or belongs to a different account.",
-    "userDataRights.errors.download.expired":
-      "Your download has expired. Please request a new export.",
-    "userDataRights.errors.download.unavailable":
-      "The export is not yet ready or has failed. Please check the status endpoint.",
-    "userDataRights.errors.download.signedUrlNotSupported":
-      "The download is currently unavailable due to a server configuration issue. The operator has been notified.",
+  "user-data-rights:entity:download-attempt:field:result": { de: "Ergebnis", en: "Result" },
+  "user-data-rights:entity:download-attempt:field:via": { de: "Via", en: "Via" },
+  "user-data-rights:entity:download-attempt:field:ip": { de: "IP", en: "IP" },
+  "user-data-rights:entity:download-attempt:field:attemptedByUserId": {
+    de: "Benutzer",
+    en: "User",
   },
+  "user-data-rights:entity:download-attempt:field:jobId": { de: "Job", en: "Job" },
 };

package/src/user-data-rights/lib/is-admin-actor.ts

@@ -0,0 +1,19 @@
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { access } from "@cosmicdrift/kumiko-framework/engine";
+
+const ADMIN_ROLES: ReadonlySet<string> = new Set(access.admin);
+const SYSTEM_ADMIN_ROLES: ReadonlySet<string> = new Set(access.systemAdmin);
+
+// Reused by handlers that are `openToAll: true` but still need a manual
+// self-or-admin gate (e.g. restrict-account.write.ts) — Set-lookup instead
+// of the O(n·m) `roles.some(role => access.admin.includes(role))` re-scan.
+export function isAdminActor(user: Pick<SessionUser, "roles">): boolean {
+  return user.roles.some((role) => ADMIN_ROLES.has(role));
+}
+
+// Platform-wide operator role — exempt from the cross-tenant membership
+// check that otherwise gates the tenant-scoped admin roles (TenantAdmin/
+// Admin) before they act on another tenant's user.
+export function isSystemAdminActor(user: Pick<SessionUser, "roles">): boolean {
+  return user.roles.some((role) => SYSTEM_ADMIN_ROLES.has(role));
+}

package/src/user-data-rights/lib/storage-provider-resolver.ts

@@ -4,8 +4,9 @@
 // construction). Extracted from the export cron so both crons + the manual
 // forget handler share one construction site instead of inlining it three times.
 
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { ConfigResolver, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import type { FileStorageProvider } from "@cosmicdrift/kumiko-framework/files";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import { createConfigAccessor } from "../../config";
@@ -18,7 +19,7 @@ export interface TenantStorageResolverCtx {
   // Undefined → the returned resolver throws (callers decide fail-loud vs skip).
   readonly configResolver: ConfigResolver | undefined;
   readonly secrets: SecretsContext | undefined;
-  readonly db: DbConnection;
+  readonly db: DbConnection | TenantDb;
   readonly userId: string;
   readonly handlerName: string;
 }
@@ -28,9 +29,9 @@ export function makeTenantStorageProviderResolver(
 ): (tenantId: TenantId) => Promise<FileStorageProvider> {
   return async (tenantId) => {
     if (!ctx.configResolver) {
-      throw new Error(
-        `${ctx.handlerName}: ctx.configResolver missing — cannot resolve the file provider for tenant ${tenantId}`,
-      );
+      throw new InternalError({
+        message: `[${ctx.handlerName}] ctx.configResolver missing — cannot resolve the file provider for tenant ${tenantId}`,
+      });
     }
     const config = createConfigAccessor(
       ctx.registry,

package/src/user-data-rights/lib/update-user-lifecycle.ts

@@ -1,7 +1,7 @@
-import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
-import { createSystemUser, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { createSystemUser, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { USER_STATUS, userEntity, userTable } from "../../user";
 
@@ -21,16 +21,6 @@ import { USER_STATUS, userEntity, userTable } from "../../user";
 // kann abweichen).
 const userExecutor = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
 
-// Stream-Tenant = die framework-injizierte tenant_id der read_users-Row. Der
-// Reducer setzt sie aus `user.created`.tenantId, ein Rebuild rekonstruiert sie
-// daraus — sie IST also der Stream-Key des Aggregats. Die Row direkt zu lesen
-// (statt das created-Event zu joinen) deckt auch direkt-geseedete Rows ab.
-async function streamTenantOf(conn: DbRunner, userId: string): Promise<TenantId | null> {
-  const row = await fetchOne<{ tenantId?: string }>(conn, userTable, { id: userId });
-  // @cast-boundary db-row — tenant_id ist eine TenantId-shaped uuid-Spalte.
-  return row?.tenantId ? (row.tenantId as TenantId) : null;
-}
-
 // `conn` ist ctx.db.raw (regulaere Handler) ODER die offene tx (forget-cleanup
 // Sub-Tx) — so bleibt der Event-Append atomar mit dem umgebenden Write.
 export async function updateUserLifecycle(
@@ -38,20 +28,14 @@ export async function updateUserLifecycle(
   userId: string,
   changes: Record<string, unknown>,
 ): Promise<void> {
-  const streamTenantId = await streamTenantOf(conn, userId);
-  if (!streamTenantId) {
-    throw new InternalError({
-      message: `read_users row ${userId} has no tenant_id — cannot rescope lifecycle write to its stream tenant`,
-    });
-  }
-
-  // Rescope BEIDE Achsen auf den Stream-Tenant: der db-Arg treibt loadById +
-  // den Stream-Read, der user-Arg die Event-tenantId + Ownership. Nur beide
-  // zusammen halten created + updated auf einem Stream.
-  const tenantDb = createTenantDb(conn, streamTenantId, "tenant");
+  // user ist systemStream (#497): der Executor-Choke-Point addressiert den
+  // Stream immer auf SYSTEM_TENANT_ID — ein Rescope auf die row-tenant_id
+  // waere wirkungslos. "system"-Mode, damit loadById auch Legacy-Rows findet,
+  // deren tenant_id noch vor dem #762-Backfill-Rebuild steht.
+  const tenantDb = createTenantDb(conn, SYSTEM_TENANT_ID, "system");
   const result = await userExecutor.update(
     { id: userId, changes },
-    createSystemUser(streamTenantId),
+    createSystemUser(SYSTEM_TENANT_ID),
     tenantDb,
     { skipOptimisticLock: true },
   );

package/src/user-data-rights/run-export-jobs.ts

@@ -46,6 +46,7 @@
 
 import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { addDurationSpec } from "@cosmicdrift/kumiko-framework/compliance";
+import { PII_ERASED_SENTINEL } from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbConnection, DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
@@ -57,6 +58,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/files";
 import type { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { resolveProfileForTenant } from "../compliance-profiles";
+import { decryptStoredPii } from "../shared";
 import { userTable } from "../user";
 import { selectExportJobsForStorageCleanup } from "./db/queries/export-jobs";
 import { runUserExport, type UserExportBundle } from "./run-user-export";
@@ -103,9 +105,10 @@ export const tokenCrud = createEventStoreExecutor(
  *
  * **Plain-Token-Recovery bei Email-Fail:** plain ist ephemeral. Wenn
  * der Callback throwt, ist der plain verloren. Operator-Eingriff
- * noetig (Token in DB nullen + Job auf pending → next Worker-Run
- * generiert neuen Token). Atom 5b (Re-issue-handler) wird das
- * automatisieren.
+ * noetig: Job auf pending flippen — NUR das. Die Token-Row NICHT
+ * loeschen (eventloser Read-Side-Delete → Rebuild-Kollision, fw#832);
+ * der naechste Worker-Run rotiert das Token in place auf demselben
+ * Aggregat. Atom 5b (Re-issue-handler) wird das automatisieren.
  */
 export type SendExportReadyEmailFn = (args: {
   readonly userId: string;
@@ -149,7 +152,7 @@ export interface RunExportJobsArgs {
   readonly sendExportFailedEmail?: SendExportFailedEmailFn;
   /** Base-URL fuer den Magic-Link. App-Author setzt das (z.B.
    *  "https://app.example.com/user-export/by-token"). Worker baut
-   *  `${appExportDownloadUrl}?token=<plain>` und reicht das im
+   *  a URL fragment (not a query param — see issue #1271) and passes that
    *  Callback durch. Required wenn sendExportReadyEmail gesetzt. */
   readonly appExportDownloadUrl?: string;
 }
@@ -425,22 +428,53 @@ async function processJob(args: {
     // Plain-Token bleibt im Worker-Memory + wird via RunExportJobsResult
     // an Atom 5 (Notification) weitergegeben. NUR der hash landet in DB.
     // ES via tokenCrud.create — kein direct-INSERT.
+    //
+    // **Re-Run (fw#832):** Flippt ein Operator einen done/failed-Job
+    // zurueck auf pending (Plain-Token verloren, Email-Fail), existiert
+    // fuers jobId schon eine Token-Row. Ein zweites create wuerde ein
+    // zweites `created`-Event auf frischem Aggregat emittieren — der
+    // Projection-Rebuild kollidiert dann dauerhaft am one_per_job-Index.
+    // Stattdessen: Token-Rotation in place auf demselben Aggregat
+    // (update mit frischem Hash + Reset der Audit-Felder).
     const expiresAt = addDurationSpec(now, ttl);
     const { plain: tokenPlain, hash: tokenHash } = await generateDownloadToken();
-    const tokenCreateResult = await tokenCrud.create(
-      {
-        jobId: job.id,
-        tokenHash,
-        issuedAt: now,
-        expiresAt,
-        // Atom 4a.fix: useCount explizit 0 statt default null. 4b's
-        // Verify-Pfad incrementiert via `useCount + 1` ohne COALESCE-
-        // Defensiv-Code.
-        useCount: 0,
-      },
-      executor,
-      tdb,
+    const existingToken = await fetchOne<{ id: string; version: number }>(
+      db,
+      exportDownloadTokensTable,
+      { jobId: job.id },
     );
+    const tokenCreateResult = existingToken
+      ? await tokenCrud.update(
+          {
+            id: existingToken.id,
+            version: existingToken.version,
+            changes: {
+              tokenHash,
+              issuedAt: now,
+              expiresAt,
+              useCount: 0,
+              lastUsedAt: null,
+              lastUsedFromIp: null,
+              lastUsedUserAgent: null,
+            },
+          },
+          executor,
+          tdb,
+        )
+      : await tokenCrud.create(
+          {
+            jobId: job.id,
+            tokenHash,
+            issuedAt: now,
+            expiresAt,
+            // Atom 4a.fix: useCount explizit 0 statt default null. 4b's
+            // Verify-Pfad incrementiert via `useCount + 1` ohne COALESCE-
+            // Defensiv-Code.
+            useCount: 0,
+          },
+          executor,
+          tdb,
+        );
     if (!tokenCreateResult.isSuccess) {
       // Token-Creation failed VOR done-flip → Job bleibt running.
       // Catch-Pfad flippt auf failed mit klarer Diagnose. Storage-
@@ -767,7 +801,9 @@ async function lookupUserContact(
     locale: string | null;
   } | null;
   if (!row?.email) return null;
-  return { email: row.email, locale: row.locale ?? null };
+  const email = await decryptStoredPii(row.email, "email", "user-data-rights:export-ready");
+  if (email === PII_ERASED_SENTINEL) return null;
+  return { email, locale: row.locale ?? null };
 }
 
 // Atom 5 — Email-Notification beim done-flip. Best-effort:
@@ -808,7 +844,7 @@ async function fireExportReadyCallback(args: {
       "user-data-rights: sendExportReadyEmail gesetzt aber appExportDownloadUrl fehlt — beide muessen zusammen konfiguriert sein",
     );
   }
-  const downloadUrl = `${baseUrl}?token=${encodeURIComponent(args.plainToken)}`;
+  const downloadUrl = `${baseUrl}#token=${encodeURIComponent(args.plainToken)}`;
   await args.send({
     userId: args.job.userId,
     userEmail: contact.email,