@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.388.0

package/dist/user-data-rights/run-forget-cleanup.d.ts

@@ -6,18 +6,15 @@ import { type SearchAdapter } from "@cosmicdrift/kumiko-framework/search";
 import type { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
 /**
- * Notification-Callback fuer den Forget-Cleanup-Pfad (Atom 5b). Pattern
- * matched Atom 5 (Export). Throw bubbelt zum r.job-Wrap; jobs-feature
- * persistiert den failed-Run in jobRunsTable (siehe
- * jobs/__tests__/jobs-feature.integration.ts Scenario 2 — der throw-
- * Pfad eines r.job-handlers wird dort gepinnt).
+ * Callback for the forget-cleanup path. A callback failure propagates to the
+ * r.job wrapper so the jobs feature can persist the failed run.
  *
- * **executedAt:** Zeitpunkt des delete-Flips. Wird als ISO-String
- * uebergeben damit App-Author den frei in Email-Template einbauen kann.
+ * **executedAt:** The time of the delete flip, passed as an ISO string so the
+ * app author can insert it into an email template.
  *
- * **tenantIds:** alle Memberships die der User vor dem Delete hatte.
- * Email-Template kann das nutzen ("dein Account in Tenant X+Y wurde
- * geloescht"). Bei orphan-User (0 Memberships) ist die Liste leer.
+ * **tenantIds:** All memberships the user had before deletion. An email
+ * template can use this to describe which tenant accounts were deleted. The
+ * list is empty for an orphan user with no memberships.
  */
 export type SendDeletionExecutedEmailFn = (args: {
     readonly userId: string;
@@ -32,13 +29,12 @@ export interface RunForgetCleanupArgs {
     readonly db: DbRunner;
     readonly registry: Registry;
     /**
-     * Now-Injection — Tests koennen den Wert pinnen ohne Date-Mock.
-     * Pattern aus data-retention/keep-for.ts (advisor-pinned).
+     * Injects the current time so tests can control it without mocking the date.
      */
     readonly now: Instant;
-    /** Atom 5b — Email-Notification beim delete-flip. Optional;
-     *  ohne Callback laeuft Worker still (User hatte schon
-     *  request-deletion-Email + grace-period-Erinnerung). */
+    /** Sends an optional email notification after the delete flip. Without a
+     * callback, the worker remains silent because the user already received the
+     * request-deletion email and grace-period reminder. */
     readonly sendDeletionExecutedEmail?: SendDeletionExecutedEmailFn;
     /**
      * Per-tenant file-storage-provider resolver (the forget cron builds it from
@@ -56,8 +52,8 @@ export interface RunForgetCleanupArgs {
      */
     readonly kms?: KmsAdapter;
     /**
-     * Search adapter for purging derived Meili docs of searchable subject-PII
-     * (#1610). Same seam as forget-subject. Omitted → no search purge (apps
+     * Search adapter for purging derived Meili docs of searchable subject-PII.
+     * Same seam as forget-subject. Omitted → no search purge (apps
      * without Meili).
      */
     readonly searchAdapter?: SearchAdapter;
@@ -97,11 +93,11 @@ export interface ForgetCleanupIncomplete {
     readonly rolledBack: boolean;
 }
 export interface RunForgetCleanupResult {
-    /** User die in diesem Lauf von DeletionRequested → Deleted geflippt wurden. */
+    /** Users flipped from DeletionRequested to Deleted during this run. */
     readonly processedUserIds: readonly string[];
-    /** Anzahl entity-hook-calls die wirklich gelaufen sind (success oder fail). */
+    /** Number of entity-hook calls that actually ran, whether successful or failed. */
     readonly hookCallsAttempted: number;
-    /** Hook-Errors fuer Operator-Visibility. Lauf bricht nicht ab — siehe Header. */
+    /** Hook errors collected for operator visibility; the run continues. */
     readonly errors: readonly ForgetCleanupError[];
     /** Hooks that reported `{status:"incomplete"}` — partial success, user still Deleted. */
     readonly incomplete: readonly ForgetCleanupIncomplete[];

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

@@ -1,39 +1,32 @@
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
-// Forget-Cleanup-Runner (S2.U5b) — pure-Function Pipeline.
+// Forget-cleanup runner — pure-function pipeline.
 //
-// After the grace period (S2.U5a sets gracePeriodEnd) this runner iterates
-// over all users in DeletionRequested state and triggers the EXT_USER_DATA
-// delete hooks in every tenant the user is or was a member of (membership
-// history from kumiko_events).
+// After the grace period, this runner processes users in DeletionRequested
+// state and triggers EXT_USER_DATA delete hooks in every tenant where the user
+// is or was a member, using membership history from kumiko_events.
 //
-// **Cross-tenant iteration:** a forget request in tenant A must remove the
-// user's data in ALL of their tenants, including tenants they left before
-// the request — see
-// docs/plans/architecture/user-data-rights.md "Cross-Tenant-Semantik".
+// **Cross-tenant iteration:** a request in tenant A must remove the user's data
+// in all of their tenants, including tenants they left before the request.
 //
-// **Strategy-Dispatch:** Pro Entity entscheidet die data-retention-
-// policy (per-Tenant Override moeglich), ob "delete" oder "anonymize"
-// gefahren wird. blockDelete (Aufbewahrungs-Pflicht) ergibt zwingend
-// "anonymize" — Daten-Objekt bleibt physisch da, Personen-Bezug raus.
+// **Strategy dispatch:** each entity's data-retention policy determines whether
+// to run "delete" or "anonymize". A blockDelete policy always produces
+// "anonymize", leaving the data object in place while removing its association
+// with the person.
 //
-// **Per-User-Atomicity (advisor-pinned):** Jeder User wird in einer
-// eigenen Sub-Transaction abgewickelt (db.transaction → SAVEPOINT wenn
-// Outer-Tx aktiv, BEGIN sonst). Folge: ein failing Hook bei User A
-// rollt nur dessen Sub-Tx zurueck, User B + bisherige User-Status-Flips
-// bleiben commit-able. Ohne diese Sub-Tx wuerde der Outer-Dispatcher-Tx
-// (alle writeHandler laufen in `db.begin(...)`) den ganzen
-// Cleanup-Run beim ersten Hook-Throw zurueckrollen.
+// **Per-user atomicity:** each user runs in its own sub-transaction
+// (db.transaction → SAVEPOINT when an outer transaction is active, BEGIN
+// otherwise). A failing hook rolls back only that user's transaction, while
+// other users and previously completed status changes remain commit-able.
+// Without this isolation, the outer dispatcher transaction would roll back the
+// entire cleanup run on the first hook failure.
 //
-// **Idempotenz:** Hooks sind idempotent designed (siehe
-// engine/extensions/user-data.ts). Doppellauf nach Crash-Recovery muss
-// safe sein. Status-Flip auf "Deleted" am Ende sorgt dafuer, dass next
-// Lauf den User nicht mehr findet.
+// **Idempotency:** hooks are designed to be idempotent, so rerunning after
+// crash recovery is safe. Flipping the status to "Deleted" at the end keeps
+// the user out of subsequent runs.
 //
-// **Error-Handling:** Ein hook der wirft soll den Lauf NICHT stoppen —
-// andere User sollen weiter abgearbeitet werden. Errors werden
-// gesammelt + zurueckgegeben fuer Operator-Visibility. Ein User mit
-// gefailten Hooks bleibt im DeletionRequested-Status (next Lauf
-// retried automatisch).
+// **Error handling:** a throwing hook must not stop the run. Errors are
+// collected and returned for operator visibility, while a user with failed
+// hooks remains in DeletionRequested for automatic retry.
 import { configuredPiiSubjectKms, subjectIdToKey, } from "@cosmicdrift/kumiko-framework/crypto";
 import { createTenantDb, entityEventName, executeRawQuery, fetchOne, nullBlindIndexesForSubject, selectMany, WritePurposes, } from "@cosmicdrift/kumiko-framework/db";
 import { deleteStoredFileAndDerivatives } from "@cosmicdrift/kumiko-framework/derivatives";
@@ -85,8 +78,8 @@ export async function runForgetCleanup(args) {
     if (dueUsers.length === 0) {
         return { processedUserIds: [], hookCallsAttempted: 0, errors: [], incomplete: [] };
     }
-    // Step 2: Sammle alle EXT_USER_DATA-Usages einmalig — Liste der
-    // (entityName, deleteHook)-Pairs aller registrierten Provider-Features.
+    // Step 2: collect all EXT_USER_DATA usages once, i.e. the
+    // (entityName, deleteHook) pairs of all registered provider features.
     const usages = registry.getExtensionUsages(EXT_USER_DATA);
     const hookEntries = usages
         .map((u) => {
@@ -112,7 +105,7 @@ export async function runForgetCleanup(args) {
     const incomplete = [];
     const processedUserIds = [];
     let hookCallsAttempted = 0;
-    // Step 3: Pro User iterieren — eigene Sub-Tx pro User (siehe Header).
+    // Step 3: iterate per user, each in its own sub-transaction (see header).
     for (const user of dueUsers) {
         const userResult = await processUser({
             db,
@@ -132,17 +125,14 @@ export async function runForgetCleanup(args) {
         incomplete.push(...userResult.incomplete);
         if (userResult.success) {
             processedUserIds.push(user.id);
-            // Atom 5b — Email-Notification nach success-flip. userEmail wurde
-            // VOR der Tx gecacht (user-Hook anonymisiert in der Tx).
+            // userEmail was cached BEFORE the transaction because the user hook
+            // anonymizes it inside the transaction.
             //
-            // Best-effort: ein Email-Throw fuer User A darf nicht den Batch
-            // killen — User A ist bereits geloescht (Sub-Tx committed), und
-            // die Users B, C, ... muessen noch verarbeitet werden. Throw waere
-            // hier ein Bug: r.job-Wrap markiert den Run failed, retry findet
-            // keine User mehr im DeletionRequested+grace-expired-Status (alle
-            // schon Deleted) → silent miss. console.warn ist die einzige
-            // Operator-Sichtbarkeit — runForgetCleanup-args fuehren AppContext.
-            // log aktuell nicht durch (pure-function-Pattern).
+            // The email is best-effort: a send failure must not abort the batch after the
+            // user's sub-transaction has committed. Otherwise the job would be marked
+            // failed, and a retry would find no eligible users, causing a silent miss.
+            // console.warn is the only operator-visible reporting path because the
+            // runForgetCleanup args do not carry AppContext.log (pure-function pattern).
             if (sendDeletionExecutedEmail && userResult.userEmailBeforeDelete) {
                 try {
                     await sendDeletionExecutedEmail({
@@ -167,11 +157,9 @@ async function processUser(args) {
     const errors = [];
     const incomplete = [];
     let hookCallsAttempted = 0;
-    // Atom 5b — userEmail VOR der Tx cachen. user-Hook (user-data-rights-
-    // defaults) anonymisiert email/displayName/passwordHash IN der Tx.
-    // Nach der Tx ist email = "deleted-{id}@{tenant}.example" oder NULL.
-    // Memory-cache laesst Atom-5b-Callback nach success-flip den
-    // ORIGINAL-email an App-Author-Callback geben.
+    // Cache the email before the transaction because the user hook anonymizes
+    // email/displayName/passwordHash inside it. The cache lets the callback after
+    // a successful status flip receive the original email address.
     const userPreTx = await fetchOne(db, userTable, {
         id: userId,
     });
@@ -179,13 +167,12 @@ async function processUser(args) {
         ? await decryptStoredPii(userPreTx.email, "email", "user-data-rights:forget-cleanup")
         : null;
     const userLocaleBeforeDelete = userPreTx?.locale ?? null;
-    // Memberships fuer diesen User holen — alle Tenants in denen er Mitglied ist.
     const memberships = await selectMany(db, tenantMembershipsTable, {
         userId,
     });
-    // tenant-Liste fuer Atom 5b Email — Memberships VOR Tx, weil hooks
-    // memberships in der Tx loeschen. Orphan-User (0 memberships) liefert
-    // [] in Email-args; App-Author-Template kann das case-handlen.
+    // Capture memberships before the transaction deletes them so the email
+    // callback receives the original tenant list. Orphan users provide an empty
+    // list.
     const tenantIdsBeforeDelete = memberships.map((m) => m.tenantId);
     // Departed tenants: removeMember deletes only the projection row, so data
     // the user left behind there (e.g. note mentions) must still be reached.
@@ -197,19 +184,17 @@ async function processUser(args) {
     // nothing there and no-op. Without this path status=Deleted would be set
     // while the original PII stays — compliant-looking, but not compliant.
     const tenantList = hookTenantIds.length > 0 ? hookTenantIds : [SYSTEM_TENANT_ID_FOR_ORPHANS];
-    // Per-User-Sub-Tx: hooks + status-flip atomar. Bei Hook-Throw rollt
-    // nur dieser User zurueck, andere User bleiben commit-fest. Die Sub-Tx
-    // nestet korrekt: eine Top-Level-Connection oeffnet sie via `.begin`
-    // (BEGIN), eine TransactionSql — der Fall im Dispatcher, wo jeder
-    // writeHandler bereits IN der Outer-Tx laeuft — via `.savepoint`
-    // (SAVEPOINT). Siehe runInSubTransaction.
+    // Hooks and the status flip run atomically per user. A hook failure rolls back
+    // only that user, while other users remain commit-able. runInSubTransaction
+    // uses `.begin` (BEGIN) for a top-level connection and `.savepoint`
+    // (SAVEPOINT) when the dispatcher is already inside an outer transaction.
     let txSucceeded = false;
     let currentTenantId = null;
     let currentEntityName = null;
     try {
         await runInSubTransaction(db, async (tx) => {
             // Discover + purge search docs for this subject BEFORE any delete
-            // hook runs (fw#1611). purgeSearchDocumentsForSubject finds candidate
+            // hook runs. purgeSearchDocumentsForSubject finds candidate
             // rows via a live SELECT on each entity's read-table — a hook that
             // hard-deletes a row (UserDataDeleteStrategy "delete") makes that row
             // invisible to a purge running afterward, permanently stranding its
@@ -289,7 +274,8 @@ async function processUser(args) {
             // is what makes this crash-safe: eraseKey-throw → tx rollback → user
             // stays DeletionRequested → next run retries; flip-throw after a
             // successful erase → retry re-runs the idempotent hooks and eraseKey
-            // (contractually a no-op on an erased/unknown subject). Erasing after
+            // (idempotent: a repeat erase keeps the original tombstone, an unknown
+            // subject gets one). Erasing after
             // the flip instead would risk a permanent silent miss: user already
             // Deleted, no run ever picks him up again, key stays live.
             if (kms) {
@@ -298,24 +284,22 @@ async function processUser(args) {
                     userId,
                     eraseReason: "user-data-rights:forget",
                 });
-                // Blind-Index-Sweep (#818): bidx-Spalten des erased Subjects sofort
-                // nullen — sonst bliebe der deterministische HMAC bis zum nächsten
-                // Rebuild equality-matchbar (Linkage-Fenster). In der Sub-Tx, damit
-                // ein Rollback auch den Sweep zurücknimmt.
+                // Null blind-index columns immediately after erasing the subject key; otherwise
+                // the deterministic HMAC would remain equality-matchable until the next
+                // rebuild. Keeping this in the sub-transaction makes the sweep rollback
+                // with the rest of the user's cleanup.
                 await nullBlindIndexesForSubject(tx, registry.features, subjectIdToKey({ kind: "user", userId }));
             }
-            // Status-Flip in derselben Sub-Tx. Falls einer der Hooks oben
-            // geworfen hat, kommen wir hier nicht an — die Tx rollback'd
-            // alles, der User bleibt im DeletionRequested-Status, naechster
-            // Run retried.
+            // Flip the status in the same sub-transaction. If a hook throws, execution
+            // never reaches this point, so the user remains in DeletionRequested for
+            // the next retry.
             await updateUserLifecycle(tx, userId, { status: USER_STATUS.Deleted }, { writePurpose: WritePurposes.erasure });
             txSucceeded = true;
         });
     }
     catch (e) {
-        // currentTenantId/currentEntityName tracken den Failing-Hook —
-        // Operator sieht "Hook fileRef in Tenant A failed for user X" statt
-        // generisches "<sub-transaction>".
+        // Track the failing hook so operators see its tenant and entity instead of a
+        // generic sub-transaction error.
         errors.push({
             userId,
             tenantId: currentTenantId ?? "",
@@ -357,10 +341,9 @@ function resolveForgetFileBytesDeleter(buildStorageProvider) {
         }
     };
 }
-// Pseudo-Tenant fuer User ohne aktive Memberships. RFC4122-konforme
-// Null-UUID. Tenant-scoped Hooks finden hier nichts (no-op),
-// tenant-agnostische Hooks (z.B. user) operieren auf der globalen
-// User-Row und ignorieren tenantId.
+// Use a pseudo-tenant for users with no active or historical memberships.
+// Tenant-scoped hooks find nothing there, while tenant-agnostic hooks such as
+// the user hook still operate on the global user row and ignore tenantId.
 const SYSTEM_TENANT_ID_FOR_ORPHANS = "00000000-0000-0000-0000-000000000000";
 // "single-user" requires BOTH the app config AND a runtime sole-member check —
 // the config asserts the deployment model, the count guards against a stray
@@ -380,7 +363,7 @@ async function resolveEffectiveTenantModel(db, tenantId, appTenantModel) {
 // removeMemberWrite only deletes the tenant-membership PROJECTION row — the
 // event history survives forever, and a departed member's own tenant-scoped
 // data rows (contributor-style records with no per-user column) can
-// outlive their membership (ent#346). A live count of 1 is therefore not
+// outlive their membership. A live count of 1 is therefore not
 // enough: a tenant that ever had >1 distinct member must stay multi-user for
 // the forget path even after everyone but one is removed, or the sole
 // remaining member's forget request wipes the departed co-member's leftover
@@ -390,7 +373,7 @@ async function resolveEffectiveTenantModel(db, tenantId, appTenantModel) {
 // tenant SystemAdmin adds land under the actor's tenant_id.
 //
 // Counting created-ROWS against distinct userIds latched a tenant to
-// multi-user as soon as its sole member was removed and re-added (#2608) —
+// multi-user as soon as its sole member was removed and re-added —
 // two created-events, one identity, no co-member ever. The fail-safe only
 // needs to cover payloads whose userId cannot be READ, so the unreadable
 // remainder is measured directly instead of inferred from the row count.
@@ -426,14 +409,13 @@ async function readHistoricalMembershipTenantIds(db, userId) {
        AND NULLIF(payload->>'tenantId', '') IS NOT NULL`, [entityEventName("tenant-membership", "created"), userId]);
     return rows.map((row) => row.tenant_id); // @cast-boundary db-row
 }
-// Mapping retention.strategy → user-data-rights.UserDataDeleteStrategy.
-//   - "anonymize" / "blockDelete" → "anonymize" (Aufbewahrungs-Pflicht
-//     blockDelete: Daten muessen physisch bleiben, nur Personen-Bezug raus)
-//   - "hardDelete" / "softDelete" / null → "delete" (Default)
+// Map retention.strategy to user-data-rights.UserDataDeleteStrategy.
+//   - "anonymize" / "blockDelete" → "anonymize": retention requirements keep
+//     the data physically present while removing its association with the person.
+//   - "hardDelete" / "softDelete" / null → "delete" (default).
 //
-// Eigene Funktion damit Strategie-Drift zwischen retention-strategies
-// und user-data-rights-Hooks an EINER Stelle dokumentiert + getestet
-// werden kann (siehe run-forget-cleanup.test.ts).
+// Keeping this mapping in one function makes drift between retention strategies
+// and user-data-rights hooks explicit and testable.
 export function policyToStrategy(retentionStrategy) {
     if (retentionStrategy === "anonymize" || retentionStrategy === "blockDelete") {
         return "anonymize";

package/dist/user-data-rights/run-user-export.d.ts

@@ -16,63 +16,64 @@ export interface UserExportFileRef {
     readonly fileRefId: string;
     readonly storageKey: string;
     readonly fileName: string;
-    /** Tenant in dem die Datei haengt — gleicher fileRefId kann nicht ueber Tenants geteilt sein. */
+    /** Tenant containing the file; the same fileRefId cannot be shared across tenants. */
     readonly tenantId: TenantId;
     /**
-     * ZIP-internal Pfad unter dem die Datei im Export-ZIP landet. Reader-
-     * Tools (Compliance-Audit, Self-Service-Portal) verlinken bundle.json
-     * fileRefs[] auf die files/-Pfade ueber dieses Feld. Garantiert
-     * path-traversal-frei via sanitizeZipFilename.
+     * ZIP-internal path under which the file is placed in the export ZIP.
+     * Reader tools (compliance audit, self-service portal) use this field
+     * to link bundle.json fileRefs[] to the files/-paths. Guaranteed to be
+     * safe from path traversal via sanitizeZipFilename.
      */
     readonly zipPath: string;
 }
 export interface UserExportTenantSection {
     readonly tenantId: TenantId;
-    /** Pro Entity ein Snippet ({entity, rows[]}). Empty wenn Hook null returned. */
+    /** One snippet per entity ({entity, rows[]}); empty when the hook returns null. */
     readonly entities: ReadonlyArray<UserDataExportSnippet>;
 }
 export interface UserExportBundle {
     readonly userId: string;
-    /** ISO-8601 Generation-Timestamp — fuer Audit-Trail. */
+    /** ISO-8601 generation timestamp for the audit trail. */
     readonly generatedAt: string;
-    /** Pro Tenant in dem User Mitglied ist eine Section. Orphan-User → tenants=[]. */
+    /** One section for each tenant the user belongs to; orphan users have tenants=[]. */
     readonly tenants: ReadonlyArray<UserExportTenantSection>;
     /**
-     * Flat-Liste aller fileRefs aus allen Tenant-Sections — der spaetere
-     * ZIP-Bau-Job iteriert hier durch + zieht Binaries aus dem Storage-
-     * Provider. Bis dahin ist das die Stueckliste fuer den Operator.
+     * Flat list of all fileRefs from every tenant section. The later ZIP
+     * construction job iterates over this list and retrieves binaries from
+     * the storage provider. Until then, it is the operator's manifest.
      */
     readonly fileRefs: ReadonlyArray<UserExportFileRef>;
 }
 /**
- * Pure function: iteriert alle EXT_USER_DATA-Hooks pro Tenant (Cross-
- * Tenant-Memberships) + sammelt Snippets in ein UserExportBundle.
+ * Pure function: invokes all EXT_USER_DATA hooks for each tenant
+ * membership and collects snippets into a UserExportBundle.
  *
- * **Memory-Footprint:**
+ * **Memory footprint:**
  *
- * Der gesamte Storage-Pfad ist streaming-bound:
- *   - File-Binaries via provider.readStream → chunk-streaming, skaliert
- *     auf beliebige File-Sizes ohne Heap-Spike.
- *   - ZIP-Schreiben via provider.writeStream — local nutzt fs.createWriteStream,
- *     S3 nutzt lib-storage.Upload (multipart, ~20MB Heap-Bound bei 4
- *     concurrent parts).
+ * The entire storage path is streaming-bound:
+ *   - File binaries use provider.readStream and chunk streaming, scaling
+ *     to arbitrary file sizes without a heap spike.
+ *   - ZIP writing uses provider.writeStream; local storage uses
+ *     fs.createWriteStream, while S3 uses lib-storage.Upload (multipart,
+ *     with an approximately 20 MB heap bound at 4 concurrent parts).
  *
- * **EINZIGER nicht-streaming Pfad:** das Bundle-Object selbst (bundle.json
- * Inhalt). Es wird komplett in-memory gebaut bevor `bundleToZipEntries`
- * es als ZIP-Entry yieldet. Hooks geben Snippets als Plain-Objects
- * zurueck (siehe UserDataExportSnippet).
+ * **Only non-streaming path:** the bundle object itself (the bundle.json
+ * content). It is built entirely in memory before `bundleToZipEntries`
+ * yields it as a ZIP entry. Hooks return snippets as plain objects
+ * (see UserDataExportSnippet).
  *
- * **Threshold:** Web-App mit ~500 Tabellen-Rows pro User ≈ 500 KB JSON.
- * 50k Rows ≈ 50 MB. 100k+ Rows pro User (z.B. langjaehrige Mietportal-
- * Logs) macht Heap-Druck merkbar.
+ * **Threshold:** A web app with approximately 500 table rows per user
+ * produces about 500 KB of JSON. 50k rows produce about 50 MB. 100k+
+ * rows per user (for example, long-running rental-portal logs) create
+ * noticeable heap pressure.
  *
- * **Wenn das knapp wird:** runUserExport auf AsyncIterable-Form refactoren —
- * Hooks yielden snippets statt Object-Returns; Bundle-Schema bekommt
- * JSON-Lines-Format. bundleToZipEntries wuerde line-by-line streamen.
- * Eigener Sprint, nicht-trivialer Schema-Bruch.
+ * **If this becomes a problem:** refactor runUserExport to use an
+ * AsyncIterable; hooks would yield snippets instead of returning objects,
+ * and the bundle schema would use JSON Lines. bundleToZipEntries would
+ * stream entries line by line. This is a non-trivial schema change.
  *
- * **Operator-Signal:** wenn bundle.json im ZIP > 100 MB ist, sollte
- * Telemetry triggern + Schema-Refactor evaluieren.
+ * **Operator signal:** if bundle.json exceeds 100 MB in the ZIP, trigger
+ * telemetry and evaluate a schema refactor.
  */
 export declare function runUserExport(args: RunUserExportArgs): Promise<UserExportBundle>;
 export {};

package/dist/user-data-rights/run-user-export.js

@@ -1,25 +1,24 @@
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
-// User-Data-Export-Pipeline (S2.U3) — DSGVO Art. 15 (Auskunft) +
-// Art. 20 (Datenportabilität).
+// User data export pipeline — GDPR Art. 15 (access) +
+// Art. 20 (data portability).
 //
-// Pure Pipeline-Function: ruft alle EXT_USER_DATA-export-Hooks ueber
-// alle Tenant-Memberships eines Users + sammelt das Ergebnis als
-// strukturiertes Bundle.
+// Pure pipeline function: invokes all EXT_USER_DATA export hooks for
+// all of a user's tenant memberships and collects the results into a
+// structured bundle.
 //
-// **Async ZIP + Storage (S2.U3-ext) bewusst spaeter:** Diese Foundation
-// gibt das Bundle inline zurueck (JSON-Object). Apps mit grossen
-// File-Mengen brauchen einen Job-Wrap der das Bundle nach S3 / lokalem
-// Storage schreibt + signed-URLs ergibt — kommt drauf wenn ein realer
-// User-Case >10MB Output produziert. Bis dahin reicht inline fuer
-// 99% der Apps (User-Profil + Files-Metadata + Aktivitaeten-History).
+// **Async ZIP + storage deferred:** This foundation returns the bundle
+// inline as a JSON object. Apps with large file collections need a job
+// wrapper that writes the bundle to S3 or local storage and produces
+// signed URLs; that can be added when a real use case produces more than
+// 10 MB of output. Until then, inline output covers 99% of apps
+// (user profiles, file metadata, and activity history).
 //
-// **Cross-Tenant-Iteration:** Wie beim Forget-Pfad — User-Daten in
-// Tenant A + B kommen in dasselbe Bundle. Plan-Doc:
-// docs/plans/architecture/user-data-rights.md "Cross-Tenant-Semantik".
+// **Cross-tenant iteration:** As with the forget path, data from Tenant A
+// and Tenant B is included in the same bundle.
 //
-// **PII-Surface:** Hooks definieren selbst welche Felder ins Bundle
-// landen. user-data-rights-defaults/hooks/user.userdata-hook expose
-// expliziert KEIN passwordHash + KEINE roles (privileged columns).
+// **PII surface:** Hooks decide which fields enter the bundle.
+// user-data-rights-defaults/hooks/user.userdata-hook explicitly exposes
+// neither passwordHash nor roles (privileged columns).
 import { configuredPiiSubjectKms, decryptPiiFieldValues, isPiiCiphertext, } from "@cosmicdrift/kumiko-framework/crypto";
 import { collectEncryptedFieldNames, configuredEntityFieldEncryption, createTenantDb, decryptEntityFieldValues, selectMany, } from "@cosmicdrift/kumiko-framework/db";
 import { EXT_USER_DATA, extensionUsageEscapeHatchReason, maskWriteOnlyFields, } from "@cosmicdrift/kumiko-framework/engine";
@@ -45,38 +44,38 @@ function buildHookDb(db, tenantId, entry, args) {
     });
 }
 /**
- * Pure function: iteriert alle EXT_USER_DATA-Hooks pro Tenant (Cross-
- * Tenant-Memberships) + sammelt Snippets in ein UserExportBundle.
+ * Pure function: invokes all EXT_USER_DATA hooks for each tenant
+ * membership and collects snippets into a UserExportBundle.
  *
- * **Memory-Footprint:**
+ * **Memory footprint:**
  *
- * Der gesamte Storage-Pfad ist streaming-bound:
- *   - File-Binaries via provider.readStream → chunk-streaming, skaliert
- *     auf beliebige File-Sizes ohne Heap-Spike.
- *   - ZIP-Schreiben via provider.writeStream — local nutzt fs.createWriteStream,
- *     S3 nutzt lib-storage.Upload (multipart, ~20MB Heap-Bound bei 4
- *     concurrent parts).
+ * The entire storage path is streaming-bound:
+ *   - File binaries use provider.readStream and chunk streaming, scaling
+ *     to arbitrary file sizes without a heap spike.
+ *   - ZIP writing uses provider.writeStream; local storage uses
+ *     fs.createWriteStream, while S3 uses lib-storage.Upload (multipart,
+ *     with an approximately 20 MB heap bound at 4 concurrent parts).
  *
- * **EINZIGER nicht-streaming Pfad:** das Bundle-Object selbst (bundle.json
- * Inhalt). Es wird komplett in-memory gebaut bevor `bundleToZipEntries`
- * es als ZIP-Entry yieldet. Hooks geben Snippets als Plain-Objects
- * zurueck (siehe UserDataExportSnippet).
+ * **Only non-streaming path:** the bundle object itself (the bundle.json
+ * content). It is built entirely in memory before `bundleToZipEntries`
+ * yields it as a ZIP entry. Hooks return snippets as plain objects
+ * (see UserDataExportSnippet).
  *
- * **Threshold:** Web-App mit ~500 Tabellen-Rows pro User ≈ 500 KB JSON.
- * 50k Rows ≈ 50 MB. 100k+ Rows pro User (z.B. langjaehrige Mietportal-
- * Logs) macht Heap-Druck merkbar.
+ * **Threshold:** A web app with approximately 500 table rows per user
+ * produces about 500 KB of JSON. 50k rows produce about 50 MB. 100k+
+ * rows per user (for example, long-running rental-portal logs) create
+ * noticeable heap pressure.
  *
- * **Wenn das knapp wird:** runUserExport auf AsyncIterable-Form refactoren —
- * Hooks yielden snippets statt Object-Returns; Bundle-Schema bekommt
- * JSON-Lines-Format. bundleToZipEntries wuerde line-by-line streamen.
- * Eigener Sprint, nicht-trivialer Schema-Bruch.
+ * **If this becomes a problem:** refactor runUserExport to use an
+ * AsyncIterable; hooks would yield snippets instead of returning objects,
+ * and the bundle schema would use JSON Lines. bundleToZipEntries would
+ * stream entries line by line. This is a non-trivial schema change.
  *
- * **Operator-Signal:** wenn bundle.json im ZIP > 100 MB ist, sollte
- * Telemetry triggern + Schema-Refactor evaluieren.
+ * **Operator signal:** if bundle.json exceeds 100 MB in the ZIP, trigger
+ * telemetry and evaluate a schema refactor.
  */
 export async function runUserExport(args) {
     const { db, registry, userId, now } = args;
-    // Memberships → Tenant-Liste fuer Hook-Iteration.
     const memberships = await selectMany(db, tenantMembershipsTable, {
         userId,
     });
@@ -126,15 +125,15 @@ export async function runUserExport(args) {
         }
         tenants.push({ tenantId, entities });
     }
-    // Edge-Case "0 Memberships": Tenant-agnostische Hooks (z.B. user-Hook)
-    // wuerden bei Cross-Tenant-Iteration mehrfach laufen. Bei orphan-User
-    // (kein Membership) wuerden sie gar nicht laufen. Loesung wie beim
-    // Forget-Runner: einen Sonder-Lauf mit einem Pseudo-Tenant ergaenzen
-    // damit die globale User-Row IM Bundle landet. Tenant-scoped Hooks
-    // sind no-op.
+    // Edge case "0 memberships": tenant-agnostic hooks (for example, the
+    // user hook) would run multiple times during cross-tenant iteration.
+    // An orphan user with no membership would otherwise skip them entirely.
+    // As in the forget runner, add a special run with a pseudo-tenant so
+    // the global user row is included in the bundle. Tenant-scoped hooks
+    // are no-ops.
     //
-    // Das Pattern matched run-forget-cleanup.ts; Memory: Cross-Tenant-
-    // Konsistenz darf nicht silent kippen wenn Memberships leer sind.
+    // Cross-tenant consistency must not silently break when memberships are
+    // empty.
     if (tenantList.length === 0 && hookEntries.length > 0) {
         const orphanEntities = [];
         for (const entry of hookEntries) {
@@ -173,14 +172,14 @@ export async function runUserExport(args) {
         fileRefs,
     };
 }
-// Art. 20 verlangt die DATEN, nicht deren Ciphertext: Export-Hooks lesen
-// raw rows an der Executor-Decrypt-Schicht vorbei, darum entschluesselt
-// dieser zentrale Pass encrypted entity fields nach jedem Hook. Ohne
-// konfigurierten Cipher wird ein expliziter Marker exportiert statt den
-// base64-Blob als "Wert" auszuliefern (leak-by-confusion).
+// Art. 20 requires the data, not its ciphertext: export hooks read raw
+// rows outside the executor's decryption layer, so this central pass
+// decrypts encrypted entity fields after each hook. Without a configured
+// cipher, it exports an explicit marker instead of presenting the base64
+// blob as a value (leak by confusion).
 const ENCRYPTED_UNAVAILABLE = "[encrypted:unavailable]";
 // Shared decrypt sweep, used for both `snippet.rows` and `snippet.fileRefs`
-// (#1955) — `encryptedFields` is keyed by field NAME, so it stays a no-op
+// `encryptedFields` is keyed by field NAME, so it stays a no-op
 // for today's `fileRef` entity but covers a future generically-encrypted
 // side-channel field too.
 async function decryptRecords(records, encryptedFields, kms) {
@@ -236,7 +235,6 @@ async function decryptSnippetFields(registry, hookEntityName, snippet) {
     }));
     return { ...snippet, rows, fileRefs };
 }
-// Pseudo-Tenant fuer User ohne aktive Memberships. Identisch zum
-// Pattern in run-forget-cleanup.ts — RFC4122-Null-UUID. Tenant-scoped
-// Hooks finden hier nichts (no-op).
+// Pseudo-tenant for users without active memberships. It uses an
+// RFC4122 null UUID; tenant-scoped hooks find no data here (no-op).
 const SYSTEM_TENANT_ID_FOR_ORPHANS = "00000000-0000-0000-0000-000000000000";