@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.388.0

package/dist/user/schema/user.js

@@ -2,10 +2,9 @@ import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import { access, createBooleanField, createDerivedField, createEntity, createMultiSelectField, createSelectField, createTextField, createTimestampField, createTzField, } from "@cosmicdrift/kumiko-framework/engine";
 import { GLOBAL_ROLE_OPTIONS } from "../web/constants.js";
 /**
- * User-Lifecycle-Status (S2.U1). Single source of truth — Auth-Middleware
- * (S2.U6), Forget-Job (S2.U5) und Restriction-Handler nutzen diese
- * Constants statt Magic-Strings (Memory feedback_role_naming_drift —
- * gleiches Pattern wie ROLES.SystemAdmin).
+ * User lifecycle status. This is the single source of truth used by the
+ * auth middleware, forget job, and restriction handler instead of duplicated
+ * magic strings, following the same pattern as ROLES.SystemAdmin.
  */
 export const USER_STATUS = {
     Active: "active",
@@ -14,24 +13,25 @@ export const USER_STATUS = {
     Deleted: "deleted",
 };
 /**
- * Anonymize-Display-Strings fuer userDeleteHook (S2.H1). Constants statt
- * Magic-Strings damit i18n-Mapping moeglich + drift-fest. Default-DE,
- * App-Author kann via i18n-System uebersetzen wenn gewuenscht.
+ * Display strings anonymized by userDeleteHook. Constants keep i18n mapping
+ * possible and prevent drift. The default is German; app authors can
+ * translate it through the i18n system if desired.
  */
 export const USER_DELETED_DISPLAY_NAME = "[Geloescht]";
 export const USER_ANONYMIZED_DISPLAY_NAME = "[Anonymisiert]";
 /**
- * Email-Pseudonyme nach Forget. `<prefix>-<userId>@anonymized.invalid`
- * — der userId-Suffix ist als Pseudo-Audit-Marker fuer Operator
- * (Tracing-fall) erlaubt; user-id selbst ist UUID, kein PII.
- * `.invalid`-TLD ist RFC2606-reserviert — niemals deliverbare Email.
+ * Email pseudonyms used after forgetting. `<prefix>-<userId>@anonymized.invalid`
+ * — the userId suffix is permitted as a pseudo-audit marker for operator
+ * tracing; the user ID itself is a UUID, not PII.
+ * The `.invalid` TLD is reserved by RFC2606, so the address can never be
+ * delivered.
  */
 export const USER_DELETED_EMAIL_PREFIX = "deleted";
 export const USER_ANONYMIZED_EMAIL_PREFIX = "anonymized";
 export const USER_ANONYMIZED_EMAIL_DOMAIN = "anonymized.invalid";
-// Tuple form fuer createSelectField (erfordert non-empty readonly tuple).
-// Object.values(USER_STATUS) waere string[] — statisches Tuple ist
-// type-sicher.
+// Tuple form for createSelectField (requires a non-empty readonly tuple).
+// Object.values(USER_STATUS) would be string[]; the static tuple preserves
+// type safety.
 const USER_STATUS_OPTIONS = [
     USER_STATUS.Active,
     USER_STATUS.Restricted,
@@ -45,10 +45,10 @@ export const userEntity = createEntity({
     table: "read_users",
     softDelete: true,
     // Tenant-independent identity aggregate — its event stream lives on
-    // SYSTEM_TENANT_ID instead of whichever tenant happened to create it (#497).
+    // SYSTEM_TENANT_ID instead of whichever tenant happened to create it.
     systemStream: true,
     // Every row lives on SYSTEM_TENANT_ID; writes with another tenantId are
-    // rejected (fw#2858).
+    // rejected.
     tenancy: "global",
     fields: {
         // Identity — anyone who can see the user can read the email, but only
@@ -81,17 +81,17 @@ export const userEntity = createEntity({
             reason: "credential_hash_read_without_decrypt",
         }),
         // Profile — user-editable. Real name in most apps → PII. Searchable via
-        // the derived Meili index; events/projection stay ciphertext (#1610).
+        // the derived Meili index; events/projection stay ciphertext.
         displayName: createTextField({
             required: true,
             maxLength: 100,
             personal: "self",
             find: "fuzzy",
         }),
-        // No default here — tenant-settings owns the app-wide locale default; see #1637.
+        // No default here — tenant-settings owns the app-wide locale default.
         locale: createTextField({ maxLength: 10, personal: false, reason: "technical_reference" }),
         // No default here — mirrors locale: ctx.tz falls back to tenant.timezone
-        // (then "UTC") when unset, see buildHandlerContext (fw#1636).
+        // (then "UTC") when unset, see buildHandlerContext.
         timezone: createTzField(),
         // Which tenant should this user land in on next login. Set by the login
         // handler (SYSTEM), read by the login flow + UI for deep-linking.
@@ -121,21 +121,22 @@ export const userEntity = createEntity({
             default: [],
             access: { write: access.privileged },
         }),
-        // S2.U1: User-Lifecycle-Status für user-data-rights (Sprint 2).
-        //   - "active":            Normaler State, alle Operationen erlaubt
-        //   - "restricted":        Art. 18 Restriction — Login blockiert + jede
-        //                          Live-Session wird vom sessionChecker abgewiesen
+        // User lifecycle status for user-data-rights.
+        //   - "active":            Normal state; all operations are allowed.
+        //   - "restricted":        Art. 18 restriction — login is blocked and every
+        //                          live session is rejected by sessionChecker
         //                          ("blocked"). Recovery via lift-restriction
-        //                          (openToAll, session-unabhängig).
-        //   - "deletionRequested": delete-account aufgerufen, gracePeriodEnd gesetzt,
-        //                          Login blockiert. Bestehende Session bleibt LIVE
-        //                          (reversibel) — User kann via cancel-deletion
-        //                          zurück auf "active".
-        //   - "deleted":           Forget executed nach Grace, Row anonymisiert via
-        //                          softDelete. Login blockiert + Session "blocked".
+        //                          (openToAll, independent of the session).
+        //   - "deletionRequested": delete-account was called and gracePeriodEnd set;
+        //                          login is blocked. Existing sessions remain LIVE
+        //                          (reversible), so the user can return to "active"
+        //                          via cancel-deletion.
+        //   - "deleted":           Forget was executed after the grace period; the row
+        //                          was anonymized via softDelete. Login is blocked and
+        //                          the session is "blocked".
         //
-        // Schreibrecht privileged: nur die request-deletion / restrict / lift /
-        // execute-forget-Handler (alle SYSTEM-context) duerfen status flippen.
+        // Write access is privileged: only the request-deletion / restrict / lift /
+        // execute-forget handlers (all in SYSTEM context) may change the status.
         status: createSelectField({
             required: true,
             default: USER_STATUS.Active,
@@ -143,21 +144,21 @@ export const userEntity = createEntity({
             sortable: true,
             access: { write: access.privileged },
         }),
-        // Wann darf der pending-Forget tatsaechlich ausgefuehrt werden?
-        // Cron-Job in user-data-rights checkt taeglich gracePeriodEnd < now()
-        // und triggert dann die EXT_USER_DATA-Hooks. NULL solange kein
-        // Forget pending — wird beim delete-account-Call gesetzt
-        // (= now() + Compliance-Profile.userRights.gracePeriod), beim
-        // cancel-deletion zurueckgesetzt.
+        // When a pending forget may actually be executed.
+        // The user-data-rights cron job checks daily whether gracePeriodEnd < now()
+        // and then triggers the EXT_USER_DATA hooks. NULL means no forget is pending;
+        // delete-account sets it to
+        // (= now() + Compliance-Profile.userRights.gracePeriod), and
+        // cancel-deletion resets it.
         gracePeriodEnd: createTimestampField({
             access: { write: access.privileged },
         }),
-        // Replay-Schutz für den anonymen email-Token-Deletion-Flow (#354/1).
-        // Gesetzt von request-deletion-by-email (eine UUID pro Mail-Antrag),
-        // genullt von cancel-deletion. confirm-deletion-by-token faltet diese ID
-        // in die HMAC-Purpose des Tokens — ein nach einem Cancel nachgespieltes
-        // (noch TTL-gültiges) Token verifiziert gegen die genullte/erneuerte ID
-        // nicht mehr. NULL solange kein email-Antrag offen ist.
+        // Replay protection for the anonymous email-token deletion flow.
+        // request-deletion-by-email sets one UUID per email request, and
+        // cancel-deletion clears it. confirm-deletion-by-token incorporates this ID
+        // into the token's HMAC purpose, so a token replayed after cancellation
+        // (while still within its TTL) no longer verifies against the cleared or
+        // renewed ID. NULL means no email request is pending.
         pendingDeletionRequestId: createTextField({
             maxLength: 36,
             access: { write: access.privileged },

package/dist/user/seeding.d.ts

@@ -4,28 +4,28 @@ import { type SeedTenantHooks } from "../tenant/seeding.ts";
 export type SeedUserOptions = {
     readonly email: string;
     readonly displayName: string;
-    /** Optional bereits-gehashtes Passwort. Für plain-password-Tests
-     *  besser den Convenience-Wrapper aus
-     *  `@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding` nutzen,
-     *  der argon2-Hashing übernimmt. */
+    /** Optional pre-hashed password. For plain-password tests, prefer the
+     * convenience wrapper from
+     * `@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding`,
+     * which performs argon2 hashing. */
     readonly passwordHash?: string;
     readonly locale?: string;
-    /** Global roles — land in users.roles as jsonb string[].
-     *  Werden vom login-handler in die Session-Roles parallel zu tenant-
-     *  membership-roles gemerged. Default: leer-array. Typisches Beispiel:
-     *  `["SystemAdmin"]` für den Plattform-Operator. */
+    /** Global roles—stored in users.roles as jsonb string[].
+     * The login handler merges them into the session roles alongside tenant-
+     * membership roles. Default: empty array. Typical example:
+     * `["SystemAdmin"]` for the platform operator. */
     readonly roles?: readonly string[];
-    /** Initial-State für emailVerified. Default false (Pflicht-Verify-Flow
-     *  muss explizit "true" setzen wenn Email-Ownership schon bewiesen ist —
-     *  z.B. Magic-Link-Signup, wo der User den Mail-Link klicken musste
-     *  bevor sein Account überhaupt entsteht). */
+    /** Initial state for emailVerified. Default: false. The required
+     * verification flow must explicitly set "true" when email ownership has
+     * already been proven—for example, in a Magic-Link signup where the user
+     * clicked the email link before the account was created. */
     readonly emailVerified?: boolean;
     readonly by?: SessionUser;
 };
 /**
- * Seed a user. Returns the userId (existing oder neu angelegt).
- * Idempotent add-only über die `email`-Spalte: wenn ein User mit dieser
- * Email existiert, kommt seine ID zurück ohne neuen Insert.
+ * Seeds a user. Returns the userId (existing or newly created).
+ * Idempotent and add-only via the `email` column: if a user with this
+ * email exists, its ID is returned without a new insert.
  */
 export declare function seedUser(db: DbConnection, options: SeedUserOptions, hooks?: SeedTenantHooks): Promise<{
     id: string;

package/dist/user/seeding.js

@@ -1,40 +1,40 @@
-// Testing-Helper fürs user-Feature. `seedUser` legt einen User direkt
-// über den Event-Store-Executor an — gleicher Pfad wie der echte
-// `UserHandlers.create`, aber ohne Access-Check und ohne ConflictError
-// bei Duplikaten. Idempotent add-only über die `email`-Spalte: ein
-// existierender User → return ohne Event. Kein update-Pfad — Profilfelder
-// ändern läuft über den regulären Handler.
+// Testing helper for the user feature. `seedUser` creates a user directly
+// through the event-store executor—the same path as the real
+// `UserHandlers.create`, but without access checks or ConflictError on
+// duplicates. It is idempotent and add-only via the `email` column: an
+// existing user returns without emitting an event. There is no update path;
+// profile changes go through the regular handler.
 //
-// Warum nicht direkt `db.insert(userTable)`: das würde den Event-Store
-// umgehen, also kein `user.created`-Event und keine MSP-Konsumenten
-// (audit, search-index) sehen den Seed. Der Executor-Pfad emittiert
-// das Event UND schreibt die Projection-Zeile in einer TX.
+// Directly calling `db.insert(userTable)` would bypass the event store, so no
+// `user.created` event would be emitted and no MSP consumers (audit,
+// search-index) would see the seed. The executor path emits the event and
+// writes the projection row in one transaction.
 import { computeBlindIndex, configuredBlindIndexKey } from "@cosmicdrift/kumiko-framework/crypto";
 import { createEventStoreExecutor, createTenantDb, fetchOne, } from "@cosmicdrift/kumiko-framework/db";
 import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
-// kumiko-lint-ignore cross-feature-import shares the postSave-hooks fixture contract with tenant/seeding (#1478)
+// kumiko-lint-ignore cross-feature-import shares the postSave-hooks fixture contract with tenant/seeding
 import { fireEntityPostSave } from "../tenant/seeding.js";
 import { userEntity, userTable } from "./schema/user.js";
 const userExecutor = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
 /**
- * Seed a user. Returns the userId (existing oder neu angelegt).
- * Idempotent add-only über die `email`-Spalte: wenn ein User mit dieser
- * Email existiert, kommt seine ID zurück ohne neuen Insert.
+ * Seeds a user. Returns the userId (existing or newly created).
+ * Idempotent and add-only via the `email` column: if a user with this
+ * email exists, its ID is returned without a new insert.
  */
 export async function seedUser(db, options, 
 // Optional, append-only — same rationale as tenant/seeding's seedTenant
-// hooks param (#1478): fires user's postSave hooks (e.g. a Welcome-
+// hooks param: fires user's postSave hooks (e.g. a Welcome-
 // notification hook keyed off `allOf: "user"`) for fixtures/self-signup
 // that opt in. Omit to keep today's hook-less behavior.
 hooks) {
     const by = options.by ?? TestUsers.systemAdmin;
-    // executor.create erwartet eine TenantDb (mit .insert()-API). User
-    // ist zwar tenant-agnostic (kein tenant_id-Spalte), aber das runtime-
-    // Interface braucht den Wrap.
+    // executor.create expects a TenantDb (with an .insert() API). Although
+    // User is tenant-agnostic (it has no tenant_id column), the runtime
+    // interface requires this wrapper.
     const tdb = createTenantDb({ db, tenantId: by.tenantId, mode: "system" });
     const existing = await fetchOne(db, userTable, { email: options.email, isDeleted: false });
-    // @cast-boundary db-row: users.id ist uuid-Spalte (string), fetchOne
-    // liefert die Projection-Row als Record<string, unknown>.
+    // @cast-boundary db-row: users.id is a uuid column (string), and fetchOne
+    // returns the projection row as Record<string, unknown>.
     if (existing) {
         const id = existing["id"];
         if (options.emailVerified === true) {
@@ -57,13 +57,13 @@ hooks) {
     return { id: extractId(result.data, "seedUser") };
 }
 // A re-run seed onto a row created before emailVerified flipped to true must
-// still set it (#1687) — via the executor, so it lands as a real `.updated` event.
+// still set it — via the executor, so it lands as a real `.updated` event.
 export async function reconcileSeededUserEmailVerified(db, existingRow, by) {
     // skip: already verified, nothing to reconcile
     if (existingRow["emailVerified"] === true)
         return;
-    // @cast-boundary db-row: users.id ist uuid-Spalte (string), fetchOne
-    // liefert die Projection-Row als Record<string, unknown>.
+    // @cast-boundary db-row: users.id is a uuid column (string), and fetchOne
+    // returns the projection row as Record<string, unknown>.
     const id = existingRow["id"];
     const tdb = createTenantDb({ db, tenantId: by.tenantId, mode: "system" });
     const result = await userExecutor.update({ id, version: existingRow["version"], changes: { emailVerified: true } }, by, tdb);
@@ -111,11 +111,11 @@ export async function rewriteSeededUserEmail(db, existingRow, email, by) {
         throw new Error(`rewriteSeededUserEmail failed: ${result.error.code} — ${JSON.stringify(result.error.details ?? {})}`);
     }
 }
-// Extrahiert die `id`-Spalte aus dem executor.create-Result. Der
-// Executor liefert ein Record<string, unknown> (die Projection-Row), in
-// das die DB die Aggregat-id reinschreibt — wir prüfen runtime statt
-// blindem `as { id: string }`-Cast, damit ein API-Vertragsbruch sofort
-// als ehrlicher Throw rauskommt statt downstream als undefined-Bug.
+// Extracts the `id` column from the executor.create result. The executor
+// returns a Record<string, unknown> (the projection row), into which the DB
+// writes the aggregate ID. We validate it at runtime instead of using a
+// blind `as { id: string }` cast, so an API contract violation throws an
+// explicit error rather than surfacing downstream as an undefined-value bug.
 function extractId(data, who) {
     if (typeof data === "object" && data !== null && "id" in data) {
         const id = data.id; // @cast-boundary engine-bridge

package/dist/user/testing.js

@@ -1,4 +1,4 @@
-// /testing re-exportiert /seeding. Siehe ../tenant/testing.ts für die
-// Begründung — Helpers sind shared zwischen Tests und Dev-Server-
-// Bootstrap, /seeding ist die stabile Heimat.
+// /testing re-exports /seeding. See ../tenant/testing.ts for the
+// reason: helpers are shared between tests and Dev-Server bootstrap,
+// and /seeding is the stable home.
 export * from "./seeding.js";

package/dist/user-data-rights/audit-download.d.ts

@@ -8,11 +8,11 @@ export interface RecordDownloadUseArgs {
     readonly tokenVersion: number;
     readonly tokenUseCount: number;
     /**
-     * Tenant fuer die system-mode-TenantDb. ExportDownloadToken ist
-     * tenant-agnostisch (1:1 zum tenant-agnostic Job), aber der event-
-     * store-Stream-Lookup braucht einen Tenant-Context. Wir nutzen
-     * job.requestedFromTenantId — dieselbe Identitaet wie beim
-     * Token-Create im Worker (Atom 4a).
+     * Tenant for the system-mode TenantDb. ExportDownloadToken is
+     * tenant-agnostic (1:1 with the tenant-agnostic job), but the event-store
+     * stream lookup requires a tenant context. We use
+     * job.requestedFromTenantId — the same identity used when creating the
+     * token in the worker.
      */
     readonly tenantId: TenantId;
     readonly now: Instant;
@@ -20,9 +20,9 @@ export interface RecordDownloadUseArgs {
     readonly userAgent: string | null;
 }
 /**
- * Audit-Update: useCount, lastUsedAt, IP, UA. Best-effort —
- * version-conflicts (parallel-downloads) werden swallowed, Download
- * succeeded trotzdem.
+ * Audit update: useCount, lastUsedAt, IP, and UA. Best-effort —
+ * version conflicts (parallel downloads) are swallowed, so the download
+ * still succeeds.
  */
 export declare function recordDownloadUse(args: RecordDownloadUseArgs): Promise<void>;
 export type DownloadAttemptResult = "notFound" | "expired" | "failed" | "signedUrlNotSupported";

package/dist/user-data-rights/audit-download.js

@@ -1,19 +1,18 @@
-// Audit-Helper fuer Download-Endpoint (S2.U3 Atom 4b).
+// Audit helper for the download endpoint.
 //
-// Beim Download (Token-Pfad oder Job-Pfad) werden Audit-Felder am
-// Token-Row aktualisiert:
+// During a download (token path or job path), audit fields on the token row
+// are updated:
 //   - useCount + 1
 //   - lastUsedAt = now
-//   - lastUsedFromIp = caller-IP (X-Forwarded-For oder Connection-IP)
-//   - lastUsedUserAgent = UA-Header
+//   - lastUsedFromIp = caller IP (X-Forwarded-For or connection IP)
+//   - lastUsedUserAgent = UA header
 //
-// **Best-Effort-Update:** version-conflicts (zwei parallel-Downloads
-// raceen um den update) werden silent geswallowt — Audit ist "letzter
-// Use", nicht "alle Uses". Der zweite Download succeeded trotzdem
-// (kein download-block bei race).
+// **Best-effort update:** version conflicts (two downloads racing to update)
+// are silently swallowed — the audit records the "last use", not "all uses".
+// The second download still succeeds (a race does not block the download).
 //
-// **ES via tokenCrud.update:** kein direct-UPDATE. Memory
-// `feedback_no_fake_dispatcher` + `feedback_event_store_tenant_consistency`.
+// **ES via tokenCrud.update:** no direct UPDATE, so the event-store and tenant
+// consistency rules remain in effect.
 import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import { createSystemUser } from "@cosmicdrift/kumiko-framework/engine";
 import { tokenCrud } from "./run-export-jobs.js";
@@ -22,9 +21,9 @@ const attemptCrud = createEventStoreExecutor(downloadAttemptsTable, downloadAtte
     entityName: "download-attempt",
 });
 /**
- * Audit-Update: useCount, lastUsedAt, IP, UA. Best-effort —
- * version-conflicts (parallel-downloads) werden swallowed, Download
- * succeeded trotzdem.
+ * Audit update: useCount, lastUsedAt, IP, and UA. Best-effort —
+ * version conflicts (parallel downloads) are swallowed, so the download
+ * still succeeds.
  */
 export async function recordDownloadUse(args) {
     const { db, tokenId, tokenVersion, tokenUseCount, tenantId, now, ip, userAgent } = args;
@@ -42,14 +41,14 @@ export async function recordDownloadUse(args) {
         },
     }, executor, tdb)
         .catch(() => {
-        // version-conflict bei parallelen Downloads → der erste hat
-        // bereits useCount inkrementiert. Wir behalten den Audit-Eintrag
-        // des ersten Downloads (lastUsedAt etc.). Kein download-block.
+        // A version conflict means a parallel download already incremented
+        // useCount. Keep the first download's audit entry (lastUsedAt, etc.);
+        // do not block the download.
     });
 }
-// Best-effort INSERT in read_download_attempts. Throws im Audit-Pfad
-// duerfen den Download-Endpoint nicht killen (User soll seinen 404
-// bekommen, nicht 500); failures werden silent geswallowt.
+// Best-effort INSERT into read_download_attempts. Errors in the audit path
+// must not kill the download endpoint: the user should receive their 404,
+// not a 500; failures are silently swallowed.
 export async function recordInvalidAttempt(args) {
     const { db, tenantId, now } = args;
     const executor = createSystemUser(tenantId);

package/dist/user-data-rights/boot-checks.js

@@ -7,7 +7,7 @@ import { entitiesOf } from "../shared/index.js";
 // only; runtime no-ops (a delete hook that silently skips) are not detectable
 // here — those are covered by the export/forget integration tests.
 //
-// Registered as an `r.bootCheck()` by this feature (#1314) — EXT_USER_DATA is
+// Registered as an `r.bootCheck()` by this feature — EXT_USER_DATA is
 // owned by user-data-rights (r.extendsRegistrar(EXT_USER_DATA, {})), so any
 // r.useExtension(EXT_USER_DATA, ...) usage across the app already requires
 // user-data-rights to be mounted (boot-validator's extension-provider check

package/dist/user-data-rights/deletion-token.js

@@ -2,7 +2,7 @@
 // subject is the user, the anchor is the pending request id stored on the
 // user row. Minting and verification both run through
 // shared/row-bound-grant, so a token from a cancelled cycle (id nulled) or a
-// superseded one (row holds a newer id) fails verification — see #354/1.
+// superseded one (row holds a newer id) fails verification.
 //
 // The purpose string and the anchoring are unchanged from the hand-rolled
 // version this replaced, so tokens stay byte-compatible.

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

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