@cosmicdrift/kumiko-bundled-features 0.385.0 → 0.387.0

package/dist/user-data-rights/index.js

@@ -2,17 +2,15 @@ export { deletionTokenSecretEnvSchema } from "./env.js";
 export { createUserDataRightsFeature } from "./feature.js";
 export { denyIfTargetOutsideAdminTenant, TARGET_USER_NOT_IN_ADMIN_TENANT, } from "./lib/deny-if-target-outside-admin-tenant.js";
 export { isSystemAdminActor } from "./lib/is-admin-actor.js";
-// #494 Bestandsdaten-Reconcile — Apps rufen das einmalig vor dem Re-Enable
-// von read_users-Rebuilds (siehe lib-Doc).
+// Reconcile existing data once before re-enabling read_users rebuilds.
+// See the library documentation for the required procedure.
 export { backfillUserLifecycleEvents, updateUserLifecycle } from "./lib/update-user-lifecycle.js";
-// Runner-Exports — App-Tests dürfen export/forget deterministisch laufen
-// lassen, statt über den Job-Cron zu warten (siehe sample
-// user-data-rights-demo).
-// Shared retention→strategy mapping (single source of truth per its own
-// doc comment) — other EXT_USER_DATA delete hooks that must independently
-// consult a DIFFERENT entity's retention (e.g. notes-history-user-data's
-// host-entity check) reuse this instead of re-deriving the anonymize/delete
-// split.
+// Exported so app tests can run export/forget deterministically instead of
+// waiting for the job cron.
+// Shared retention-to-strategy mapping: other EXT_USER_DATA delete hooks that
+// independently consult a DIFFERENT entity's retention (for example,
+// notes-history-user-data's host-entity check) reuse this instead of
+// re-deriving the anonymize/delete split.
 export { policyToStrategy, runForgetCleanup } from "./run-forget-cleanup.js";
 export { runUserExport } from "./run-user-export.js";
 export { downloadAttemptEntity, downloadAttemptsTable } from "./schema/download-attempt.js";

package/dist/user-data-rights/lib/default-mailers.js

@@ -93,9 +93,9 @@ function emailChannelOf(registry) {
 }
 export function makeDefaultDeletionExecutedEmail(deps, defaults = {}) {
     return async (args) => {
-        // Der User ist global, der Mail-Transport per-Tenant — wir senden ueber den
-        // Transport des ersten Memberships. Orphan-User (0 Memberships) liefert
-        // keine Tenant-Identitaet → kein Transport aufloesbar, Mail entfaellt.
+        // The user is global, but the mail transport is tenant-specific, so use the
+        // first membership's transport. An orphan user has no tenant identity, so no
+        // transport can be resolved and the mail is omitted.
         const tenantId = args.tenantIds[0];
         if (tenantId === undefined) {
             // skip: orphan user has no tenant whose transport could send the mail

package/dist/user-data-rights/lib/update-user-lifecycle.js

@@ -2,20 +2,17 @@ import { createEventStoreExecutor, createTenantDb, selectMany, } from "@cosmicdr
 import { createSystemUser, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { USER_STATUS, userEntity, userTable } from "../../user/index.js";
-// #494 — Lifecycle-Mutationen der user-Entity MUESSEN als `user.updated`-Event
-// laufen. Roh per updateMany geschrieben, wischt ein read_users-Rebuild sie
-// weg (er replayt nur `user.created` -> status faellt auf den Default zurueck;
-// gracePeriodEnd/pendingDeletionRequestId/Deleted gehen verloren = DSGVO-
-// Datenverlust).
+// Lifecycle mutations of the user entity MUST be emitted as `user.updated` events.
+// Writing them directly with updateMany causes a read_users rebuild to erase them
+// (it replays only `user.created`, so status falls back to its default;
+// gracePeriodEnd/pendingDeletionRequestId/Deleted are lost, causing GDPR data loss).
 //
-// Das Event MUSS in denselben (tenant_id, aggregate_id)-Stream wie
-// `user.created` landen, sonst splittet das Aggregat ueber Tenants und der
-// Rebuild rekonstruiert nichts. Die user-Entity laeuft `r.systemScope()`, ihre
-// Events landen aber auf einem konkreten Tenant-Stream (siehe
-// auth-email-password/stream-tenant.ts; Root-Cause-Fix tracked in #497). Darum:
-// Rescope auf den Stream-Tenant des Users — den des `user.created`-Events,
-// NICHT `event.user.tenantId` (das ist der aktive Tenant zur Lifecycle-Zeit und
-// kann abweichen).
+// The event MUST use the same (tenant_id, aggregate_id) stream as `user.created`,
+// otherwise the aggregate is split across tenants and cannot be reconstructed.
+// The user entity runs under `r.systemScope()`, but its events use a concrete
+// tenant stream (see auth-email-password/stream-tenant.ts). Therefore, rescope to
+// the user's stream tenant—the tenant of the `user.created` event—not
+// `event.user.tenantId`, which is the active tenant at lifecycle time and may differ.
 const userExecutor = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
 // `conn` is ctx.db.unsafeRaw() (regular handlers) or the open tx
 // (forget-cleanup sub-tx) — keeps the event append atomic with the write.
@@ -29,10 +26,10 @@ const userExecutor = createEventStoreExecutor(userTable, userEntity, { entityNam
 // throws — those callers never checked a return value, so silently dropping
 // their write would be silent data loss.
 export async function updateUserLifecycle(conn, userId, changes, options) {
-    // user ist systemStream (#497): der Executor-Choke-Point addressiert den
-    // Stream immer auf SYSTEM_TENANT_ID — ein Rescope auf die row-tenant_id
-    // waere wirkungslos. "system"-Mode, damit loadById auch Legacy-Rows findet,
-    // deren tenant_id noch vor dem #762-Backfill-Rebuild steht.
+    // The user is a system stream: the executor choke point always addresses the
+    // stream through SYSTEM_TENANT_ID; rescoping to row-tenant_id would have no
+    // effect. Use "system" mode so loadById also finds legacy rows whose tenant_id
+    // predates the backfill rebuild.
     // skipOptimisticLock: every caller is a server-side business transition
     // (restrict/lift-restriction/grace-period/cancel/forget) that holds no row
     // version to pass as `payload.version`, which update() requires otherwise.

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

@@ -28,29 +28,23 @@ export declare const tokenCrud: import("@cosmicdrift/kumiko-types/event-store-ex
     readonly useCount: unknown;
 }>;
 /**
- * Notification-Callback fuer den done-Pfad. Pattern matched
- * auth-routes.PasswordResetConfig.sendResetEmail. Plain-Token bleibt
- * ephemeral (nicht in DB/event-store/jobRunsTable). App-Author wired
- * den Callback an seinen Email-Provider:
- *   - existing `delivery.notify` (multi-channel + delivery_attempts-Log)
- *   - `mailFoundation.send` direkt
- *   - Custom Resend/SES/etc.
+ * Notification callback for the done path. The plain token remains ephemeral
+ * and is never stored in the database or event store. The application wires
+ * this callback to its email provider, such as `delivery.notify`,
+ * `mailFoundation.send`, or a custom Resend/SES integration.
  *
- * **Best-effort:** Throw vom Callback bubbelt zum r.job-Wrap; jobs-
- * Feature persistiert den Worker-Run als failed in jobRunsTable. Der
- * Failed-Pfad wird in `jobs/__tests__/jobs-feature.integration.ts`
- * Scenario 2 gepinnt — wir verweisen darauf statt end-zu-end zu
- * duplizieren. Operator sieht's im /jobs-Dashboard, kann via
- * jobs:write:retry den Worker-Run erneut anstossen (Job selbst bleibt
- * done; retry findet keinen pending mehr, aber Audit-Log zeigt den
- * Failure).
+ * **Best-effort:** a throw from the callback bubbles to the r.job wrap, and the
+ * jobs feature records the worker run as failed in jobRunsTable while the export
+ * job stays done. That failed path is covered by Scenario 2 in
+ * `jobs/__tests__/jobs-feature.integration.test.ts` instead of being duplicated
+ * end to end here. Operators see the failure in the /jobs dashboard and can
+ * re-run the worker via jobs:write:retry.
  *
- * **Plain-Token-Recovery bei Email-Fail:** plain ist ephemeral. Wenn
- * der Callback throwt, ist der plain verloren. Operator-Eingriff
- * noetig: Job auf pending flippen — NUR das. Die Token-Row NICHT
- * loeschen (eventloser Read-Side-Delete → Rebuild-Kollision, fw#832);
- * der naechste Worker-Run rotiert das Token in place auf demselben
- * Aggregat. Atom 5b (Re-issue-handler) wird das automatisieren.
+ * **Recovering the plain token after an email failure:** the plain token is
+ * ephemeral, so it is lost when the callback throws. Flip the job back to
+ * pending and nothing else: do not delete the token row, because an eventless
+ * read-side delete collides with projection rebuilds. The next worker run
+ * rotates the token in place on the same aggregate.
  */
 export type SendExportReadyEmailFn = (args: {
     readonly userId: string;
@@ -76,23 +70,26 @@ export interface RunExportJobsArgs {
     readonly db: DbConnection;
     readonly registry: Registry;
     /**
-     * Per-Tenant Storage-Provider-Builder. App-Bootstrap liefert den
-     * file-foundation-Resolver via `createFileProviderForTenant` —
-     * Worker bekommt eine kleinere Surface ohne HandlerContext-Dep.
+     * Builds a storage provider for a tenant. The application supplies the
+     * `createFileProviderForTenant` resolver so the worker does not depend on
+     * HandlerContext.
      */
     readonly buildStorageProvider: (tenantId: TenantId) => Promise<FileStorageProvider>;
-    /** Now-Injection — Tests pinnen den Wert ohne Date-Mock. */
+    /** Injected time lets tests avoid mocking the system clock. */
     readonly now: Instant;
-    /** S2.U3 Atom 5 — Email-Notification beim done-flip. Optional;
-     *  wenn nicht gesetzt, sendet der Worker keine notification (User
-     *  kann aber via export-status.query polln + UI-Klick). */
+    /**
+     * Optional notification on the done transition. When absent, callers can
+     * poll `export-status.query` and let the user trigger the download.
+     */
     readonly sendExportReadyEmail?: SendExportReadyEmailFn;
-    /** Optional Email beim failed-flip. */
+    /** Optional notification on the failed transition. */
     readonly sendExportFailedEmail?: SendExportFailedEmailFn;
-    /** Base-URL fuer den Magic-Link. App-Author setzt das (z.B.
-     *  "https://app.example.com/user-export/by-token"). Worker baut
-     *  a URL fragment (not a query param — see issue #1271) and passes that
-     *  Callback durch. Required wenn sendExportReadyEmail gesetzt. */
+    /**
+     * Base URL for the magic link, for example
+     * "https://app.example.com/user-export/by-token". The worker appends the
+     * token as a URL fragment rather than a query parameter. Required when
+     * `sendExportReadyEmail` is provided.
+     */
     readonly appExportDownloadUrl?: string;
     readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
     readonly escapeHatchAuditLog?: Logger;
@@ -110,21 +107,20 @@ export interface ExportJobError {
     readonly message: string;
 }
 export interface RunExportJobsResult {
-    /** Job-IDs die in diesem Pass von pending → done geflippt wurden. */
+    /** IDs of jobs transitioned from pending to done in this pass. */
     readonly completedJobIds: readonly string[];
-    /** Job-IDs die in diesem Pass von pending → failed geflippt wurden. */
+    /** IDs of jobs transitioned from pending to failed in this pass. */
     readonly failedJobIds: readonly string[];
-    /** Job-IDs die als stuck-running auf failed geflippt wurden (Stale-Pass). */
+    /** IDs of stuck running jobs transitioned to failed by stale detection. */
     readonly staleFailedJobIds: readonly string[];
-    /** Job-IDs deren downloadStorageKey im Cleanup-Pass geloescht wurde. */
+    /** IDs of jobs whose downloadStorageKey was deleted during cleanup. */
     readonly cleanedJobIds: readonly string[];
     readonly errors: readonly ExportJobError[];
     /**
-     * Plain-Tokens fuer in diesem Pass completed-Jobs. Map<jobId, plain>.
-     * Atom 5 (Notification) liest das + versendet plain per Email.
-     * NIEMALS persistiert — nur in-memory zwischen Worker-Run und
-     * Notification-Hook. NACH dem Run ist plain nur via DB-Hash
-     * verifizierbar (Atom 4b's Download-Endpoint).
+     * Plain tokens for jobs completed in this pass, keyed by job ID. These
+     * values are passed to the notification hook only in memory and are never
+     * persisted; after the run, the download endpoint can verify only the
+     * corresponding database hash.
      */
     readonly tokenByJobId: ReadonlyMap<string, string>;
 }