@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

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

@@ -10,15 +10,16 @@ import { denyIfTargetOutsideAdminTenant } from "../lib/deny-if-target-outside-ad
 import { isAdminActor } from "../lib/is-admin-actor.ts";
 import { updateUserLifecycle } from "../lib/update-user-lifecycle.ts";
 
-// 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
@@ -27,14 +28,16 @@ import { updateUserLifecycle } from "../lib/update-user-lifecycle.ts";
 // 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({
@@ -107,10 +110,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/packages/bundled-features/src/user-data-rights/handlers/run-forget-cleanup.write.ts

@@ -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 type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";

package/packages/bundled-features/src/user-data-rights/index.ts

@@ -6,22 +6,20 @@ export {
   TARGET_USER_NOT_IN_ADMIN_TENANT,
 } from "./lib/deny-if-target-outside-admin-tenant.ts";
 export { isSystemAdminActor } from "./lib/is-admin-actor.ts";
-// #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.ts";
 export type {
   SendExportFailedEmailFn,
   SendExportReadyEmailFn,
 } from "./run-export-jobs.ts";
 export type { SendDeletionExecutedEmailFn } from "./run-forget-cleanup.ts";
-// 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.ts";
 export type { UserExportBundle } from "./run-user-export.ts";
 export { runUserExport } from "./run-user-export.ts";

package/packages/bundled-features/src/user-data-rights/lib/default-mailers.ts

@@ -167,9 +167,9 @@ export function makeDefaultDeletionExecutedEmail(
   defaults: GdprMailDefaults = {},
 ): SendDeletionExecutedEmailFn {
   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/packages/bundled-features/src/user-data-rights/lib/update-user-lifecycle.ts

@@ -9,20 +9,17 @@ import { createSystemUser, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framewor
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { USER_STATUS, userEntity, userTable } from "../../user/index.ts";
 
-// #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" });
 
 export type UpdateUserLifecycleOptions = {
@@ -57,10 +54,10 @@ export async function updateUserLifecycle(
   changes: Record<string, unknown>,
   options?: UpdateUserLifecycleOptions,
 ): Promise<{ readonly applied: boolean }> {
-  // 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.
@@ -92,16 +89,16 @@ export async function updateUserLifecycle(
   });
 }
 
-// #494 Bestandsdaten-Reconcile: Rows, deren Lifecycle-State der alte
-// raw-updateMany-Pfad gesetzt hat, haben kein `user.updated`-Event — ein
-// Rebuild wuerde sie auf die `user.created`-Defaults zuruecksetzen. Diese
-// Funktion emittiert pro divergenter Row ein `user.updated` mit dem aktuellen
-// Live-State, sodass Event-Log und Live-Tabelle wieder uebereinstimmen.
-// MUSS einmalig ueber den Bestand laufen, BEVOR eine App read_users-Rebuilds
-// re-enabled. Idempotent gegen State (ein zweiter Lauf haengt ein identisches
-// user.updated an — harmlos, last-write-wins beim Replay).
-// ponytail: full read_users-Scan, in JS gefiltert — einmalige Migration, kein
-// Index/Streaming noetig. Bei Millionen-Rows: batchen.
+// Reconcile existing data: rows whose lifecycle state was set by the old
+// raw-updateMany path have no `user.updated` event, so a rebuild would restore
+// their `user.created` defaults. This function emits one `user.updated` event per
+// divergent row with its current live state, bringing the event log and live table
+// back into agreement.
+// MUST run once over the existing data BEFORE an app re-enables read_users
+// rebuilds. State-idempotent: a second run appends an identical user.updated
+// event, which is harmless because replay uses last-write-wins.
+// ponytail: full read_users scan, filtered in JS—a one-time migration; no
+// index/streaming is needed. For millions of rows, batch the work.
 export type BackfillResult = {
   readonly backfilled: number;
   readonly failed: ReadonlyArray<{ readonly id: string; readonly error: string }>;