@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

package/packages/bundled-features/src/user/schema/user.ts

@@ -13,10 +13,9 @@ import {
 import { GLOBAL_ROLE_OPTIONS } from "../web/constants.ts";
 
 /**
- * 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",
@@ -28,26 +27,27 @@ export const USER_STATUS = {
 export type UserStatus = (typeof USER_STATUS)[keyof typeof USER_STATUS];
 
 /**
- * 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,
@@ -63,10 +63,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
@@ -101,17 +101,17 @@ export const userEntity = createEntity({
     }),
 
     // 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
@@ -145,21 +145,22 @@ export const userEntity = createEntity({
       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,
@@ -168,22 +169,22 @@ export const userEntity = createEntity({
       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/packages/bundled-features/src/user/seeding.ts

@@ -1,14 +1,14 @@
-// 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 {
@@ -19,7 +19,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
 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, type SeedTenantHooks } from "../tenant/seeding.ts";
 import { userEntity, userTable } from "./schema/user.ts";
 
@@ -28,48 +28,48 @@ const userExecutor = createEventStoreExecutor(userTable, userEntity, { entityNam
 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 async function seedUser(
   db: DbConnection,
   options: SeedUserOptions,
   // 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?: SeedTenantHooks,
 ): Promise<{ id: string }> {
   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"] as string;
     if (options.emailVerified === true) {
@@ -100,7 +100,7 @@ export async function 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: DbConnection,
   existingRow: Record<string, unknown>,
@@ -108,8 +108,8 @@ export async function reconcileSeededUserEmailVerified(
 ): Promise<void> {
   // 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"] as string;
   const tdb = createTenantDb({ db, tenantId: by.tenantId, mode: "system" });
   const result = await userExecutor.update(
@@ -173,11 +173,11 @@ export async function rewriteSeededUserEmail(
   }
 }
 
-// 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: unknown, who: string): string {
   if (typeof data === "object" && data !== null && "id" in data) {
     const id = (data as { id: unknown }).id; // @cast-boundary engine-bridge

package/packages/bundled-features/src/user/testing.ts

@@ -1,5 +1,5 @@
-// /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.ts";

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

@@ -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 type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
@@ -34,11 +33,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;
@@ -47,9 +46,9 @@ export interface RecordDownloadUseArgs {
 }
 
 /**
- * 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: RecordDownloadUseArgs): Promise<void> {
   const { db, tokenId, tokenVersion, tokenUseCount, tenantId, now, ip, userAgent } = args;
@@ -72,15 +71,15 @@ export async function recordDownloadUse(args: RecordDownloadUseArgs): Promise<vo
       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.
     });
 }
 
-// extractCallerIp lebt in feature.ts (extractAuditMeta) — query-handler
-// haben keinen direkten Header-Zugriff (transport-agnostic), httpRoute-
-// Wrapper extrahiert + steckt in payload.auditMeta.
+// extractCallerIp lives in feature.ts (extractAuditMeta) — query handlers
+// have no direct header access because they are transport-agnostic. The
+// httpRoute wrapper extracts it and places it in payload.auditMeta.
 
 export type DownloadAttemptResult = "notFound" | "expired" | "failed" | "signedUrlNotSupported";
 
@@ -97,9 +96,9 @@ export interface RecordInvalidAttemptArgs {
   readonly userAgent: string | null;
 }
 
-// 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: RecordInvalidAttemptArgs): Promise<void> {
   const { db, tenantId, now } = args;
   const executor = createSystemUser(tenantId);

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

@@ -12,7 +12,7 @@ import { entitiesOf } from "../shared/index.ts";
 // 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/packages/bundled-features/src/user-data-rights/deletion-token.ts

@@ -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.