@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.387.0

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

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

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

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

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

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

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

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

package/dist/user-data-rights/handlers/my-audit-log.query.js

@@ -4,10 +4,10 @@ import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { redactPiiCiphertext } from "../../shared/index.js";
-// DSGVO Art. 15 Selbstauskunft — User reads HIS OWN audit-log.
-// WHERE createdBy = ctx.user.id ist hard-coded (kein userId-Param,
-// anti-cross-user-Snooping). KEIN tenantId-Filter: User hat Anspruch
-// auf account-weite Sicht ueber alle Memberships — analog Forget-Pfad.
+// GDPR Art. 15 self-disclosure: users may read only their own audit log.
+// `createdBy = ctx.user.id` is hard-coded to prevent cross-user snooping;
+// no `tenantId` filter is applied because the user is entitled to an
+// account-wide view across all memberships, as in the forget path.
 const MAX_LIMIT = 100;
 const MY_AUDIT_LOG_REASON = "reads the caller's own events across all tenant memberships, bounded by createdBy = caller";
 export const myAuditLogQuery = defineQueryHandler({

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

@@ -5,12 +5,12 @@ export type SendDeletionVerificationEmailFn = (args: {
     readonly expiresAt: string;
 }) => Promise<void>;
 export type RequestDeletionByEmailOptions = {
-    /** HMAC-Secret zum Signieren des Verify-Tokens. Ohne Secret ist der Flow
-     *  deaktiviert (Handler antwortet still mit success, kein Link). */
+    /** HMAC secret used to sign the verification token. Without a secret, the flow
+     *  is disabled (the handler silently responds with success and no link). */
     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). Ohne URL kein Link. */
+    /** 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>`). Without a URL, no link is sent. */
     readonly deletionVerifyUrl?: string;
     readonly sendDeletionVerificationEmail?: SendDeletionVerificationEmailFn;
 };

package/dist/user-data-rights/handlers/request-deletion-by-email.write.js

@@ -3,13 +3,13 @@ import * as z from "zod";
 import { USER_STATUS, userTable } from "../../user/index.js";
 import { signDeletionToken } from "../deletion-token.js";
 import { updateUserLifecycle } from "../lib/update-user-lifecycle.js";
-// TTL des Verify-Links. 60 min — lang genug für einen Mail-Roundtrip,
-// kurz genug dass ein abgefangener Link nicht ewig gültig ist.
+// Verification-link TTL: 60 minutes — long enough for an email round trip,
+// but short enough that an intercepted link does not remain valid indefinitely.
 const DELETION_VERIFY_TTL_MINUTES = 60;
 // Token goes in the URL fragment, not a query param — fragments never leave
 // the browser (not sent to the server, so they never land in proxy/access
 // logs, unlike `?token=`). Same convention as the export-download link
-// (feature.ts, issue #1271). Preserves any existing query params on `base`
+// (feature.ts). Preserves any existing query params on `base`
 // (`?lang=de` stays a query param; only the token is a fragment).
 const APPEND_LIFECYCLE_EVENT_REASON = "appends the user lifecycle event on the SYSTEM_TENANT_ID user stream";
 export function buildDeletionVerifyUrl(base, token) {
@@ -17,14 +17,14 @@ export function buildDeletionVerifyUrl(base, token) {
     url.hash = `token=${encodeURIComponent(token)}`;
     return url.toString();
 }
-// Anonymer Apex-Flow Schritt 1: "Account-Löschung beantragen" per Email.
-// DSGVO-relevant gerade wenn der User sich NICHT mehr einloggen kann
-// (Lockout). Email → Magic-Link → confirm-deletion-by-token.
+// Anonymous Apex flow step 1: request account deletion by email.
+// This is especially relevant for GDPR when the user can no longer log in
+// (lockout). Email → magic link → confirm-deletion-by-token.
 //
-// Enumeration-safe (content): antwortet IMMER mit derselben success-Shape,
-// egal ob die Email existiert, der User aktiv ist oder der Flow konfiguriert
-// ist. Ein Link wird nur für einen existierenden, aktiven User generiert.
-// Timing-Safety hängt am non-blocking Callback (siehe Type-Doc oben).
+// Enumeration-safe (content): always returns the same success shape,
+// regardless of whether the email exists, the user is active, or the flow is
+// configured. A link is generated only for an existing, active user.
+// Timing safety depends on the non-blocking callback (see the type doc above).
 export function createRequestDeletionByEmailHandler(opts = {}) {
     return defineWriteHandler({
         name: "request-deletion-by-email",
@@ -33,7 +33,7 @@ export function createRequestDeletionByEmailHandler(opts = {}) {
         description: "Mails an account-deletion verification link to the given address, for a user who wants to be erased but can no longer log in; it answers identically whether or not the address belongs to an active account and never returns the link.",
         // Mails a deletion link to any address the caller names.
         agent: { risk: "high" },
-        // Defense-in-depth gegen Email-Probing auf dem anonymen Endpoint.
+        // Defense in depth against email probing on the anonymous endpoint.
         rateLimit: { per: "ip+handler", limit: 10, windowSeconds: 60 },
         escapeHatch: {
             grants: ["unsafeRaw", "globalWrites"],
@@ -41,7 +41,8 @@ export function createRequestDeletionByEmailHandler(opts = {}) {
         },
         handler: async (event, ctx) => {
             const success = { isSuccess: true, data: { kind: "requested" } };
-            // not-configured-safe: ohne Secret/URL kein Link, aber gleiche Antwort.
+            // Safe when not configured: without a secret or URL, no link is sent, but the response is
+            // unchanged.
             if (!opts.deletionTokenSecret || !opts.deletionVerifyUrl)
                 return success;
             const userRow = await ctx.db
@@ -53,9 +54,9 @@ export function createRequestDeletionByEmailHandler(opts = {}) {
             if (!userRow || userRow["status"] !== USER_STATUS.Active || !userRow["email"]) {
                 return success;
             }
-            // Replay-Schutz (#354/1): pro Antrag eine frische requestId, die auf der
-            // user-Row landet und in die Token-HMAC-Purpose gefaltet wird. cancel
-            // nullt sie → ein nach Cancel nachgespieltes Token verifiziert nicht mehr.
+            // Replay protection: each request gets a fresh requestId, which is stored on
+            // the user row and incorporated into the token HMAC purpose. cancel
+            // nulls it, so a token replayed after cancellation no longer verifies.
             const requestId = crypto.randomUUID();
             await updateUserLifecycle(ctx.db.unsafeRaw(), userRow["id"], {
                 pendingDeletionRequestId: requestId,

package/dist/user-data-rights/handlers/request-deletion.write.d.ts

@@ -11,8 +11,8 @@ export type SendDeletionRequestedEmailFn = (args: {
 }) => Promise<void>;
 export type RequestDeletionOptions = {
     readonly sendDeletionRequestedEmail?: SendDeletionRequestedEmailFn;
-    /** Branding fuer die Default-Mail wenn kein sendDeletionRequestedEmail
-     *  gesetzt ist + mail-foundation gemountet ist. */
+    /** Branding for the default email when sendDeletionRequestedEmail is not set
+     *  and mail-foundation is mounted. */
     readonly mailDefaults?: GdprMailDefaults;
 };
 export declare function createRequestDeletionHandler(opts?: RequestDeletionOptions): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"request-deletion", z.ZodObject<{}, z.core.$strip>, {

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

@@ -4,11 +4,10 @@ import * as z from "zod";
 import { USER_STATUS } from "../../user/index.js";
 import { isGdprMailDeliveryAvailable, makeDefaultDeletionRequestedEmail, } from "../lib/default-mailers.js";
 import { resolveGracePeriod, startDeletionGracePeriod } from "./deletion-grace-period.js";
-// POST /api/user/request-deletion (S2.U5a) — DSGVO Art. 17 Forget-Antrag.
-// Flippt status=Active → deletionRequested, setzt gracePeriodEnd aus dem
-// Compliance-Profile (geteilte Logik: startDeletionGracePeriod). Account-
-// weite Semantik (1 User-Row global), siehe docs/plans/architecture/
-// user-data-rights.md "Cross-Tenant-Semantik".
+// POST /api/user/request-deletion — GDPR Art. 17 erasure request.
+// Changes status=Active → deletionRequested and sets gracePeriodEnd from the compliance
+// profile using the shared startDeletionGracePeriod logic. The operation applies to the
+// account-wide user row, so the user identity is global across tenants.
 export function createRequestDeletionHandler(opts = {}) {
     return defineWriteHandler({
         name: "request-deletion",
@@ -39,8 +38,7 @@ export function createRequestDeletionHandler(opts = {}) {
                 (ctx.notify !== undefined && isGdprMailDeliveryAvailable(ctx.registry)
                     ? makeDefaultDeletionRequestedEmail(ctx.notify, opts.mailDefaults)
                     : undefined);
-            // Best-effort Email-Notification. Send-Failure darf das Write nicht
-            // killen — siehe Type-Doc oben.
+            // Best-effort email notification: a send failure must not abort the write.
             if (send && userEmail.length > 0) {
                 try {
                     await send({
@@ -56,8 +54,8 @@ export function createRequestDeletionHandler(opts = {}) {
                     console.warn(`[user-data-rights:request-deletion] sendDeletionRequestedEmail failed userId=${event.user.id} tenantId=${event.user.tenantId} err=${err instanceof Error ? err.message : String(err)}`);
                 }
             }
-            // Response liefert den absoluten gracePeriodEnd-Timestamp damit
-            // Frontend/Audit/Cleanup-Runner alle denselben Wert lesen.
+            // Returns the absolute gracePeriodEnd timestamp so the frontend, audit, and cleanup
+            // runner all use the same value.
             return {
                 isSuccess: true,
                 data: {

package/dist/user-data-rights/handlers/request-export.write.js

@@ -1,24 +1,25 @@
-// POST /api/user/request-export (S2.U3 Atom 2) — DSGVO Art. 15 + 20 Trigger.
+// POST /api/user/request-export — GDPR Art. 15 and 20 trigger.
 //
-// User triggert Export-Job. Persistenz via createEventStoreExecutor
-// (ES-Pattern, Memory: ES kein CRUD). Idempotency-Strategie zweistufig:
+// The user triggers an export job, persisted through
+// createEventStoreExecutor (event-sourced pattern; ES has no CRUD).
+// Idempotency uses two stages:
 //
-//   1) **App-side-Pre-Check (primaerer Pfad):** fetchOne aktive Jobs
-//      (status pending|running) fuer den userId. Wenn existing,
-//      return `{jobId, isExisting: true}` — KEIN neues Event,
-//      sauberer Audit-Trail (1 Klick-Storm = 1 Event, nicht N).
+//   1) **App-side pre-check (primary path):** fetch active jobs with
+//      (status pending|running) for the userId. If one exists, return
+//      `{jobId, isExisting: true}` without creating an event, so a click
+//      storm produces one audit event rather than N.
 //
-//   2) **DB-Constraint als Race-Schutz (Sekundaerpfad):** Bei parallelem
-//      Klick zwischen fetchOne + crud.create wirft die Tx 23505 mit
-//      constraint_name === "read_export_jobs_one_active_per_user".
-//      Catch + re-fetch + return existing als isExisting=true. Race-
-//      Window <1ms, in Production extrem selten.
+//   2) **DB constraint as race protection (secondary path):** if a parallel
+//      click occurs between fetchOne and crud.create, the transaction raises
+//      23505 with constraint_name === "read_export_jobs_one_active_per_user".
+//      Catch, re-fetch, and return the existing job with isExisting=true.
 //
-// **Cross-Tenant-Semantik:** ExportJob is tenant-agnostic (1 job per userId
-// across all memberships) — the pre-check uses ctx.db.unsafeRaw (no TenantDb filter) so a click from tenant B still finds the job from tenant A.
-// `requestedFromTenantId` persistiert den Initial-Tenant aus dem
-// 1. Klick — Worker liest sein Compliance-Profile aus DIESEM Tenant
-// fuer Job-TTL/Stale/Cleanup.
+// **Cross-tenant semantics:** ExportJob is tenant-agnostic (one job per
+// userId across all memberships), so the pre-check uses ctx.db.unsafeRaw
+// (no TenantDb filter) and a click from tenant B can find the job from tenant
+// A. `requestedFromTenantId` persists the tenant from the first click; the
+// worker reads its compliance profile from this tenant for job TTL, stale
+// handling, and cleanup.
 import { createEventStoreExecutor, fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
@@ -29,11 +30,11 @@ const crud = createEventStoreExecutor(exportJobsTable, exportJobEntity, {
 });
 const REQUEST_EXPORT_REASON = "export jobs are keyed by userId across all of the user's tenant memberships, not the caller's current tenant";
 /**
- * Race-Loss-Detection: createEventStoreExecutor.create catched 23505
- * intern + returnt `WriteFailure(UniqueViolationError)`, **kein throw**.
- * Wir checken den Failure-Code + constraintName um den App-side-vs-Race-
- * Pfad zu unterscheiden. Andere Failures (validation, version-conflict,
- * ...) propagieren unveraendert.
+ * `createEventStoreExecutor.create` catches 23505 internally and returns
+ * `WriteFailure(UniqueViolationError)` rather than throwing. Check the
+ * failure code and constraintName to distinguish the app-side and race
+ * paths; propagate other failures (validation, version conflicts, ...)
+ * unchanged.
  */
 function isActiveJobConflict(failure) {
     const error = failure.error; // @cast-boundary error-details
@@ -62,9 +63,9 @@ export const requestExportWrite = defineWriteHandler({
         // TenantDb-Wrapper would hide cross-tenant jobs.
         const existing = await findActiveJob(exportJobRunner, userId);
         if (existing) {
-            // Snapshot-Status (kann zwischen fetchOne + Response stale werden
-            // wenn Worker parallel den State flippt; window minimal). User
-            // pollt fuer Live-Wahrheit ueber export-status.query.
+            // The returned status is a snapshot and can become stale between fetchOne
+            // and the response if the worker changes the state concurrently. The
+            // window is minimal; clients poll export-status.query for live status.
             return {
                 isSuccess: true,
                 data: {
@@ -74,9 +75,9 @@ export const requestExportWrite = defineWriteHandler({
                 },
             };
         }
-        // Kein active Job — neuen anlegen via crud.create. requestedFromTenantId
-        // = aktueller Tenant des Users; Worker liest sein Compliance-Profile
-        // aus diesem Tenant.
+        // No active job exists, so create one through crud.create. Persist the
+        // user's current tenant in requestedFromTenantId so the worker reads the
+        // compliance profile from that tenant.
         const result = await crud.create({
             userId,
             requestedFromTenantId: event.user.tenantId,
@@ -84,16 +85,16 @@ export const requestExportWrite = defineWriteHandler({
             tenantId: event.user.tenantId,
         }, event.user, ctx.db);
         if (!result.isSuccess) {
-            // Race-Pfad: paralleler Klick hat zwischen findActiveJob + crud.create
-            // einen aktiven Job angelegt → UniqueViolationError mit unserem
-            // Constraint. Re-fetch + return existing als isExisting=true.
-            // Andere Failures (validation, version-conflict, ...) propagieren.
+            // A parallel click may create an active job between findActiveJob and
+            // crud.create, causing UniqueViolationError for our constraint. Re-fetch
+            // and return the existing job with isExisting=true. Propagate other
+            // failures (validation, version conflicts, ...) unchanged.
             if (isActiveJobConflict(result)) {
                 const winner = await findActiveJob(exportJobRunner, userId);
                 if (!winner) {
-                    // Sollte nie passieren — Constraint-Violation ohne existing
-                    // active Job hiesse der Constraint matcht etwas anderes.
-                    // Original-Failure zurueckgeben damit das auffaellt.
+                    // This should be impossible: a constraint violation without an existing
+                    // active job would mean the constraint matched something else.
+                    // Return the original failure so the inconsistency is visible.
                     return result;
                 }
                 return {
@@ -107,17 +108,17 @@ export const requestExportWrite = defineWriteHandler({
             }
             return result;
         }
-        // Happy path: neuer Job. SaveContext.id ist EntityId (number | string);
-        // exportJobEntity hat idType:"uuid" → garantiert string, String()
-        // schuetzt vor Drift falls jemand die Entity auf serial migriert.
+        // SaveContext.id is EntityId (number | string), while exportJobEntity has
+        // idType:"uuid" and therefore guarantees a string. String() protects
+        // against drift if the entity is migrated to serial.
         const created = result.data; // @cast-boundary engine-payload
         return {
             isSuccess: true,
             data: {
                 jobId: String(created.id),
-                // Snapshot: just-created → pending. Live-Wahrheit kommt ueber
-                // export-status.query, status hier ist nice-to-have fuer das
-                // initial UI-Render ("Anfrage angenommen, currently pending").
+                // This is a snapshot: a just-created job is pending. Live status comes
+                // from export-status.query; this value is only a convenience for the
+                // initial UI render ("Anfrage angenommen, currently pending").
                 status: EXPORT_JOB_STATUS.Pending,
                 isExisting: false,
             },

package/dist/user-data-rights/handlers/restrict-account.write.js

@@ -5,15 +5,16 @@ import { USER_STATUS, userTable } from "../../user/index.js";
 import { denyIfTargetOutsideAdminTenant } from "../lib/deny-if-target-outside-admin-tenant.js";
 import { isAdminActor } from "../lib/is-admin-actor.js";
 import { updateUserLifecycle } from "../lib/update-user-lifecycle.js";
-// POST /api/user/restrict (S2.U6) — DSGVO Art. 18 Account-Freeze.
-// Flippt status=Active → Restricted und revoked alle live sessions
-// des Users via cross-feature ctx.writeAs(sessions.revokeAllForUser).
+// POST /api/user/restrict — GDPR Art. 18 account freeze.
+// Flips status=Active → Restricted and revokes all live sessions
+// for the user via cross-feature ctx.writeAs(sessions.revokeAllForUser).
 //
-// Plan-Doc-Verhalten ("Schreib-API geblockt"):
-//   - Login geblockt: login.write.ts checked status=Restricted (Atom 3).
-//   - Active sessions: revoked durch cross-feature-call (sessions-feature
-//     muss gemountet sein). App-Author ohne sessions-feature kriegt einen
-//     Boot-Resolver-Error via r.usesApi("sessions.revokeAllForUser").
+// Write API behaviour:
+//   - Login is blocked: login.write.ts checks status=Restricted (Atom 3).
+//   - Active sessions are revoked through a cross-feature call (the
+//     sessions feature must be mounted). An app author without the
+//     sessions feature gets a 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
@@ -22,14 +23,16 @@ import { updateUserLifecycle } from "../lib/update-user-lifecycle.js";
 // 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 is 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; the target must have a membership row in the acting
-// admin's `event.user.tenantId` (row existence only — no active-status field).
+// (tenant-scoped) even though the User entity is global — see user-data-rights.md
+// "Cross-Tenant-Semantik". Without a membership check, a TenantAdmin from tenant A
+// could restrict or unrestrict a user who has never been a member of tenant A.
+// Only SystemAdmin (platform-wide) skips the check; the target must have a
+// membership row in the acting admin's `event.user.tenantId` (row existence only —
+// no active-status field).
 //
-// State-Transitions:
-//   Active → Restricted        ✓ (dieser Handler)
-//   Restricted → Restricted    ✗ 422 already_restricted (Idempotenz-Guard)
+// State transitions:
+//   Active → Restricted        ✓ (this handler)
+//   Restricted → Restricted    ✗ 422 already_restricted (idempotency guard)
 //   DeletionRequested → ...    ✗ 422 user_not_in_active_state
 //   Deleted → ...              ✗ 422 user_not_in_active_state
 export const restrictAccountWrite = defineWriteHandler({
@@ -83,10 +86,10 @@ export const restrictAccountWrite = defineWriteHandler({
             }));
         }
         await updateUserLifecycle(ctx.db.unsafeRaw(), targetUserId, { status: USER_STATUS.Restricted });
-        // Cross-Feature: alle live sessions revoken — sonst koennte der User
-        // mit existierendem JWT bis zur Token-Expiry weiter schreiben.
-        // ctx.writeAs(systemUser, ...) damit der privileged-Handler die
-        // System-User-Roles im access-gate hat.
+        // Cross-feature: all live sessions are revoked; otherwise the user could
+        // continue writing with an existing JWT until token expiry.
+        // ctx.writeAs(systemUser, ...) gives the privileged handler the
+        // System user roles required by its access gate.
         const systemUser = createSystemUser(event.user.tenantId);
         await ctx.writeAs(systemUser, "sessions:write:user-session:revoke-all-for-user", {
             userId: targetUserId,

package/dist/user-data-rights/handlers/run-forget-cleanup.write.js

@@ -1,14 +1,14 @@
-// POST /userDataRights/run-forget-cleanup (S2.U5b).
+// POST /userDataRights/run-forget-cleanup.
 //
-// Cron-Trigger fuer den Forget-Cleanup-Pipeline. Der Handler wrapt nur
-// `runForgetCleanup` damit er via dispatcher (System-User) aufrufbar
-// wird — die Pipeline-Logik selbst lebt im pure-function Modul
-// `run-forget-cleanup.ts` (testbar ohne dispatcher).
+// Cron trigger for the forget-cleanup pipeline. The handler only wraps
+// `runForgetCleanup` so the dispatcher can invoke it as the system user;
+// the pipeline logic itself lives in the pure-function module
+// `run-forget-cleanup.ts`, which can be tested without the dispatcher.
 //
-// Access: privileged — nur System-Caller (cron, ops-script). Im Cron-
-// Setup laeuft der Job mit `createSystemUser(...)` als executor.
+// Access: privileged — only system callers (cron, ops script). In the cron
+// setup, the job runs with `createSystemUser(...)` as executor.
 //
-// Rueckgabe: Stats fuer Operator-Monitoring (processed-count, error-list).
+// Returns stats for operator monitoring (processed count, error list).
 import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";