@cosmicdrift/kumiko-bundled-features 0.2.2 → 0.2.3

package/src/user-data-rights/schema/download-token.ts

@@ -0,0 +1,111 @@
+import { buildDrizzleTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createBigIntField,
+  createEntity,
+  createTextField,
+  createTimestampField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// Export-Download-Token (S2.U3 Atom 4a).
+//
+// Sicherheits-Token fuer den Download-Endpoint (Atom 4b). Pattern:
+//   1. Worker generiert plain-Token (32 byte random base64url) +
+//      Hash (SHA256 hex) beim Flip auf done.
+//   2. crud.create(downloadTokenEntity, ...) emittiert
+//      `exportDownloadToken.created`-Event in den event-store. DB-Row
+//      wird via Projection synchron geschrieben (Marten-Pattern, NICHT
+//      direct-INSERT). Memory `feedback_event_store_tenant_consistency`.
+//   3. Plain bleibt im Worker-Memory + wird via RunExportJobsResult an
+//      Atom 5 (Notification) weitergegeben. NIEMALS plain in DB.
+//   4. Atom 4b's Download-Endpoint: hashed incoming-Token + sucht den
+//      Hash-Eintrag. Konstanter-Zeit-Vergleich gegen timing-attacks.
+//
+// **Multi-use within TTL** (Plan-Decision 4a): Token wird beim Download
+// nicht "consumed". Mehrfach-Download bis expiresAt erlaubt — UX bei
+// Connection-Abbrueche, kein Re-Export-Zwang. Pattern matched Google-
+// Takeout (7d) + Facebook-Data-Download (4d).
+//
+// **TTL = job.expiresAt** (denormalized, gleicher Wert wie Job-Row).
+// Storage-Cleanup-Pass nullt downloadStorageKey nach
+// expiresAt + exportStorageCleanupGraceHours. Token-Row bleibt liegen
+// (Audit-Trail) — Atom 4b's Download-Endpoint check't job.downloadStorageKey
+// != null vor Streaming + returns 410 Gone wenn Storage cleared.
+//
+// **idType: "uuid"** matched ExportJob — Token-IDs reisen ueber
+// Process-Grenzen (audit-events fuer DPO, ggf. Re-Issue-Pfade).
+
+export const exportDownloadTokenEntity = createEntity({
+  table: "read_export_download_tokens",
+  idType: "uuid",
+
+  fields: {
+    // FK auf export-jobs. UNIQUE (siehe indexes) — 1 Token pro Job.
+    // Audit-Trail-Argument: separate Token-Row statt Job-Spalten weil
+    // Audit-Felder (lastUsedAt/IP/UA) semantisch zum Token, nicht zum
+    // Job gehoeren.
+    jobId: createTextField({
+      required: true,
+    }),
+
+    // **Hash NICHT plain.** SHA256-hex (64 chars). Atom 4b verifiziert
+    // via konstanter-Zeit-Vergleich.
+    tokenHash: createTextField({
+      required: true,
+      maxLength: 64,
+    }),
+
+    // Wann wurde das Token ausgegeben (= Job-Done-Flip-Zeit).
+    issuedAt: createTimestampField({
+      required: true,
+    }),
+
+    // Wann laeuft das Token ab. Identisch zu job.expiresAt
+    // (denormalized — Worker setzt beide gleich beim Done-Flip).
+    expiresAt: createTimestampField({
+      required: true,
+    }),
+
+    // Audit: wann wurde das Token zuletzt fuer einen Download genutzt.
+    // NULL solange noch nie heruntergeladen. Atom 4b's Download-Endpoint
+    // setzt es bei jedem successful Stream.
+    lastUsedAt: createTimestampField({}),
+
+    // Audit: Anzahl der Downloads. Atom 4b incrementiert bei jedem
+    // Stream. bigInt fuer fall einer pathologischer Re-Download-Schleife
+    // (z.B. broken Sync-Tool).
+    useCount: createBigIntField({}),
+
+    // Audit: Source-IP des letzten Downloads. Hilft DPO bei Untersuchung
+    // ungewoehnlicher Aktivitaeten ("Token wurde von 5 verschiedenen
+    // IPs genutzt"). Plain-IP-V4/IPv6, kein hash — DPO braucht direkt
+    // lesbar. is-business-data weil Token-Audit kein User-PII ist
+    // (gehoert dem Tenant-Operator).
+    lastUsedFromIp: createTextField({
+      maxLength: 45, // IPv6 max
+      allowPlaintext: "is-business-data",
+    }),
+
+    // Audit: User-Agent des letzten Downloads. Audit-Wert (Email-Client
+    // vs Browser vs CLI-Tool unterscheidbar). is-business-data analog.
+    lastUsedUserAgent: createTextField({
+      maxLength: 500,
+      allowPlaintext: "is-business-data",
+    }),
+  },
+
+  // 1 Token pro Job. UNIQUE auf jobId — garantiert dass Worker-
+  // Idempotency (Atom 3b's "2× run done-Job → no-op") auch fuer
+  // Token-Generierung gilt: zweiter Versuch faellt auf Constraint.
+  indexes: [
+    {
+      unique: true,
+      columns: ["jobId"],
+      name: "read_export_download_tokens_one_per_job",
+    },
+  ],
+});
+
+export const exportDownloadTokensTable = buildDrizzleTable(
+  "exportDownloadToken",
+  exportDownloadTokenEntity,
+);

package/src/user-data-rights/schema/export-job.ts

@@ -0,0 +1,166 @@
+import { buildDrizzleTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createBigIntField,
+  createEntity,
+  createLongTextField,
+  createSelectField,
+  createTextField,
+  createTimestampField,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { sql } from "drizzle-orm";
+
+// Export-Job-Lifecycle (S2.U3+U4 Atom 1).
+//
+// Spec: docs/plans/architecture/user-data-rights.md "Async Export-Pipeline".
+// User triggert `request-export` → ExportJob (status="pending"). Worker
+// pickt auf → "running" → erfolgreich "done" + downloadStorageKey gesetzt
+// + expiresAt = completedAt + compliance-profile.userRights.exportDownloadTtl
+// (per-Tenant-konfigurierbar via Override, Default 7 Tage). Bei Throw
+// oder Stale-Timeout → "failed" mit errorMessage. Stale-Timeout +
+// Storage-Cleanup-Grace ebenfalls aus dem compliance-profile.
+//
+// Status-Werte als Constants — Single source of truth fuer Worker,
+// Application-Code (request-export-Handler), UI-Banner (Polling) und
+// Drift-Guard im Test.
+export const EXPORT_JOB_STATUS = {
+  Pending: "pending",
+  Running: "running",
+  Done: "done",
+  Failed: "failed",
+} as const;
+
+export type ExportJobStatus = (typeof EXPORT_JOB_STATUS)[keyof typeof EXPORT_JOB_STATUS];
+
+/**
+ * DB-Constraint-Name fuer den Partial-UNIQUE-Index (1 aktiver Job pro
+ * User). Single source of truth — request-export.write catched 23505
+ * mit diesem Namen als Race-Schutz, Tests pinnen ihn als
+ * `expectUniqueViolation`-Argument. Rename hier propagiert automatisch.
+ */
+export const ACTIVE_JOB_CONSTRAINT = "read_export_jobs_one_active_per_user";
+
+const EXPORT_JOB_STATUS_OPTIONS = [
+  EXPORT_JOB_STATUS.Pending,
+  EXPORT_JOB_STATUS.Running,
+  EXPORT_JOB_STATUS.Done,
+  EXPORT_JOB_STATUS.Failed,
+] as const;
+
+// **Tenant-agnostisch** wie userTable — 1 Job pro {userId} ueber alle
+// Memberships. Die Framework-Auto-`tenant_id`-Spalte ist da, wird aber
+// in der Domain ignoriert (Cross-Tenant-Iteration laeuft im Worker via
+// ctx.db.raw, gleiches Pattern wie runForgetCleanup).
+//
+// **Idempotency:** Partial-UNIQUE-Index auf `(userId)` WHERE
+// `status IN ('pending', 'running')`. User mit pending-Job kann keinen
+// zweiten parallelen Job starten — der Insert faellt mit Constraint-
+// Violation auf, der request-export-Handler (Atom 2) faengt das ab und
+// returnt den existing pending-Job (Insert-or-Return). Race-Window
+// null. Done/Failed-Jobs koennen beliebig viele pro User existieren
+// (Audit-Historie).
+//
+// **idType: "uuid"** — Job-IDs reisen ueber Process-Grenzen
+// (BullMQ-Payload, Job-Run-Logger, Audit-Events fuer DPO). Serial-IDs
+// sind nur prozess-lokal verlaesslich, UUIDs cross-process stabil.
+export const exportJobEntity = createEntity({
+  table: "read_export_jobs",
+  idType: "uuid",
+
+  fields: {
+    // Tenant-agnostisch: Wert wird beim Schreiben gesetzt (Framework
+    // braucht eine tenant_id-Spalte), domain-mäßig ignoriert.
+    // Kein maxLength — folgt userTable.id + tenantMembershipsTable.userId
+    // (beide ohne maxLength). UserId-Form ist Plattform-Konzern, hier
+    // nur Storage.
+    userId: createTextField({
+      required: true,
+    }),
+
+    // **requestedFromTenantId** — der Tenant aus dem der User den Antrag
+    // gestellt hat. Persistierter Audit-Pfad fuer den Worker (welches
+    // Compliance-Profile gilt fuer Job-TTL/Stale/Cleanup) — DSGVO-
+    // konsistent: 1 User = 1 effektives Profile pro Antrag, nicht "wechselt
+    // mit jedem Cross-Tenant-Klick". Plan-Doc-Decision: Tenant aus 1. Klick
+    // (Option a). Spalte heisst nicht einfach "tenantId" damit kein
+    // Verwechseln mit der Framework-Auto-Spalte tenant_id.
+    //
+    // **Atom 3b Worker-Hinweis:** Profile-Resolution muss ueber
+    // `requestedFromTenantId` laufen (`queryAs(systemUserOf(requestedFromTenantId),
+    // "compliance-profiles:query:for-tenant", {})`), NICHT ueber
+    // `executor.tenantId` — sonst kriegt ein Job-Pickup aus einem anderen
+    // Tenant-Context ein falsches Profile.
+    requestedFromTenantId: createTextField({
+      required: true,
+    }),
+
+    status: createSelectField({
+      required: true,
+      default: EXPORT_JOB_STATUS.Pending,
+      options: EXPORT_JOB_STATUS_OPTIONS,
+    }),
+
+    // Wann hat der User den Job angefordert. Required — kein Job-Row
+    // entsteht ohne Klick.
+    requestedAt: createTimestampField({
+      required: true,
+    }),
+
+    // Wann hat der Worker mit dem Pickup angefangen. NULL solange
+    // `pending`. Stale-Detection nutzt das +
+    // compliance-profile.userRights.exportStaleTimeoutMinutes.
+    startedAt: createTimestampField({}),
+
+    // Wann hat der Worker abgeschlossen (success oder fail). NULL
+    // solange running.
+    completedAt: createTimestampField({}),
+
+    // Storage-Key des fertigen ZIP-Files. NULL solange nicht `done`.
+    // Worker setzt das + die ZIP-Bytes via storage-provider.write(key).
+    // Dies ist KEIN signed-URL — der Download-Endpoint generiert den
+    // signed-URL on demand vom Storage-Provider (Atom 4).
+    downloadStorageKey: createTextField({
+      maxLength: 500,
+    }),
+
+    // Ab wann ist der Download nicht mehr abrufbar. Worker setzt
+    // `completedAt + compliance-profile.userRights.exportDownloadTtl`
+    // beim Flip auf `done`. NULL fuer pending/running/failed.
+    //
+    // Storage-Cleanup-Pflicht: Worker laesst nach
+    // `expiresAt + compliance-profile.userRights.exportStorageCleanupGraceHours`
+    // einen separaten Pass loeschen damit abgelaufene ZIPs nicht auf S3
+    // verbleiben.
+    expiresAt: createTimestampField({}),
+
+    // Failed-State Diagnose. longText weil Hook-Errors mit Stack-Trace
+    // mehrere KB werden koennen. is-business-data weil Job-Status
+    // public im UI-Polling sichtbar (kein PII).
+    errorMessage: createLongTextField({
+      allowPlaintext: "is-business-data",
+    }),
+
+    // Audit-Info fuer Operator: wie gross war der Export. Hilft beim
+    // Capacity-Planning + erkennt pathologische Cases (Streaming-ZIP
+    // mit 5 GB Files schreibt mehrere Mrd Bytes, integer-Overflow waere
+    // silent + Audit-Drift).
+    //
+    // bigInt liefert JS-`number` Round-trip via mode:"number" — sicher
+    // bis 2^53 ≈ 9 PB, JSON-tauglich fuer das Status-Polling.
+    bytesWritten: createBigIntField({}),
+  },
+
+  // Partial-UNIQUE-Index: nur 1 aktiver Job pro User, Done/Failed-
+  // Historie ist unbeschraenkt. request-export.write nutzt App-side-
+  // Pre-Check als primaeren Pfad + 23505-Catch dieser Constraint als
+  // Race-Schutz fuer das <1ms-Window zwischen fetchOne + crud.create.
+  indexes: [
+    {
+      unique: true,
+      columns: ["userId"],
+      name: ACTIVE_JOB_CONSTRAINT,
+      where: sql`status IN ('pending', 'running')`,
+    },
+  ],
+});
+
+export const exportJobsTable = buildDrizzleTable("exportJob", exportJobEntity);

package/src/user-data-rights/token-helpers.ts

@@ -0,0 +1,67 @@
+// Download-Token-Helper (S2.U3 Atom 4a).
+//
+// Generiert ein kryptographisch-sicheres Token zur Authorisierung des
+// Export-ZIP-Downloads. Pattern matched Magic-Link/Bearer-Token mit DB-
+// gespeichertem Hash:
+//
+//   1. Worker generiert plain-Token (32 byte random base64url) + Hash
+//      (SHA256 hex).
+//   2. DB speichert NUR den Hash. Plain bleibt im Worker-Memory.
+//   3. Atom 5 (Notification) versendet plain via Email an User.
+//   4. Atom 4b (Download-Endpoint) hashet incoming-Token + vergleicht
+//      mit DB-Hash → konstantes-Zeit-Vergleich gegen timing-attacks.
+//
+// **Multi-use within TTL** (User-Choice 4a-Plan): Token wird NICHT
+// "consumed" beim Download — User kann mehrfach downloaden bis expiresAt.
+// Pattern matched Google-Takeout (7d) + Facebook-Data-Download (4d).
+//
+// **Universal Web-Crypto API:** crypto.getRandomValues + crypto.subtle.digest
+// laeuft in Bun + Node 19+ + Browser identisch — keine plattform-
+// spezifischen Imports (Memory `feedback_universal_deps`).
+
+/**
+ * Generiert ein neues Download-Token. plain wird dem User via Email
+ * zugestellt (Atom 5); hash landet in der Token-DB-Row.
+ *
+ * Token-Format: 32 byte random → base64url-encoded (~43 chars). URL-safe
+ * fuer Magic-Link-Verwendung (kein +/= das URL-encoded werden muesste).
+ */
+export async function generateDownloadToken(): Promise<{
+  readonly plain: string;
+  readonly hash: string;
+}> {
+  const randomBytes = crypto.getRandomValues(new Uint8Array(32));
+  const plain = uint8ArrayToBase64Url(randomBytes);
+  const hash = await hashDownloadToken(plain);
+  return { plain, hash };
+}
+
+/**
+ * Hashed einen plain-Token zu seiner DB-Repraesentation. Verify-Pfad
+ * (Atom 4b's Download-Endpoint): hashed incoming-Token + sucht den Hash
+ * in DB. Konstante-Zeit-String-Vergleich verhindert timing-attacks
+ * (das macht der Caller via `crypto.subtle`-vergleich oder secure-
+ * compare-helper).
+ */
+export async function hashDownloadToken(plain: string): Promise<string> {
+  const encoded = new TextEncoder().encode(plain);
+  const digest = await crypto.subtle.digest("SHA-256", encoded);
+  return uint8ArrayToHex(new Uint8Array(digest));
+}
+
+function uint8ArrayToBase64Url(bytes: Uint8Array): string {
+  // btoa erwartet binary-string. atob/btoa sind universal in Bun + Node + Browser.
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i] as number);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function uint8ArrayToHex(bytes: Uint8Array): string {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    out += (bytes[i] as number).toString(16).padStart(2, "0");
+  }
+  return out;
+}

package/src/user-data-rights/zip-path.ts

@@ -0,0 +1,94 @@
+// Shared helper fuer ZIP-Path-Berechnung von fileRefs (S2.U3 Atom 3c).
+//
+// Das Bundle hat zwei Sichten auf die selben fileRefs:
+//   1. bundle.json: Eine flat-Liste mit `zipPath` pro fileRef. Reader-
+//      Tools koennen so JSON ↔ files/-Pfade verlinken.
+//   2. ZIP-Entries: Bytes liegen unter genau diesen `zipPath`-Schluesseln.
+//
+// Damit beide Sichten NICHT auseinander driften, lebt die Pfad-Berechnung
+// EXAKT EINMAL hier. run-user-export befuellt zipPath im fileRef-Item,
+// run-export-jobs's bundleToZipEntries nutzt dieselben Pfade als Entry-
+// Keys.
+
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+
+/**
+ * Maximale Laenge des sanitized fileName (ohne Extension). Realistic
+ * Filenames sind <50, 100 ist eine sichere Grenze fuer ZIP-Kompatibilitaet
+ * (PKWARE-spec keine harte limit, aber viele Reader haengen bei extrem
+ * langen Namen).
+ */
+const MAX_SANITIZED_BASENAME_LENGTH = 100;
+
+/**
+ * Erlaubte Filename-Chars: alphanumerisch, dot, dash, underscore. Alles
+ * andere wird zu underscore replaced. Path-Separator (`/`, `\`),
+ * relative-traversal (`..`), und null-bytes sind insbesondere ausgeschlossen.
+ */
+const FILENAME_SAFE_CHARS = /[^a-zA-Z0-9._-]/g;
+
+/**
+ * Sanitize einen vom User-Input stammenden fileName fuer Verwendung als
+ * ZIP-internal-path-Suffix. Defense gegen:
+ *   - Path-Traversal:  "../../etc/passwd" → "file.etc_passwd"
+ *   - Null-Bytes:      "report\x00.pdf"   → "report_.pdf"
+ *   - Path-Separator:  "sub/dir/file.txt" → "sub_dir_file.txt"
+ *   - Reserved-Names:  "." / ".." / "..."  → "file"
+ *   - Empty input:     "" / null / undef   → "unnamed"
+ *   - Ueberlange:      lange Strings auf MAX_SANITIZED_BASENAME_LENGTH gekappt
+ *                      (Extension bleibt erhalten falls vorhanden)
+ *   - Unicode:         non-ASCII → underscore. Leading-strip kann auch dazu
+ *                      fuehren dass alle-Unicode-Names zu "file" werden.
+ *
+ * Output ist garantiert: nicht leer, kein Path-Separator, max-len enforced,
+ * keine `..`-Sequenz im finalen String.
+ */
+export function sanitizeZipFilename(raw: string): string {
+  if (raw === undefined || raw === null || raw === "") return "unnamed";
+
+  // Extension extrahieren (letzte ".X" wo X kein "." enthaelt).
+  const lastDot = raw.lastIndexOf(".");
+  const hasExt = lastDot > 0 && lastDot < raw.length - 1;
+  const baseName = hasExt ? raw.slice(0, lastDot) : raw;
+  const extension = hasExt ? raw.slice(lastDot + 1) : "";
+
+  const safeBase = collapseUnsafe(baseName).slice(0, MAX_SANITIZED_BASENAME_LENGTH);
+  const safeExt = collapseUnsafe(extension).slice(0, 20);
+
+  // Empty oder all-underscores → "file" als reproduzierbarer Fallback.
+  const finalBase = safeBase.length === 0 ? "file" : safeBase;
+
+  return safeExt.length > 0 ? `${finalBase}.${safeExt}` : finalBase;
+}
+
+/**
+ * 3-step Sanitize:
+ *   1. Replace alles ausser [a-zA-Z0-9._-] mit "_"
+ *   2. Collapse `..` (oder mehr) → "_" — verhindert dass `..` nach
+ *      Sanitize uebrig bleibt (z.B. wenn input nur dots+slashes ist).
+ *   3. Strip leading [._-]+ — verhindert hidden-file-Patterns + leere
+ *      Basenames + leading-segments die nach den ersten zwei Steps
+ *      lauter underscores haetten.
+ */
+function collapseUnsafe(s: string): string {
+  let out = s.replace(FILENAME_SAFE_CHARS, "_");
+  out = out.replace(/\.{2,}/g, "_");
+  out = out.replace(/^[._-]+/, "");
+  return out;
+}
+
+/**
+ * Berechnet den ZIP-internal-Pfad fuer einen fileRef. Layout:
+ *   files/<tenantId>/<fileRefId>-<sanitized-fileName>
+ *
+ * tenantId + fileRefId sind UUID-shape (sicher); fileName geht durch
+ * sanitizeZipFilename. Garantiert kein path-traversal.
+ */
+export function buildFileRefZipPath(args: {
+  readonly tenantId: TenantId;
+  readonly fileRefId: string;
+  readonly fileName: string;
+}): string {
+  const safeName = sanitizeZipFilename(args.fileName);
+  return `files/${args.tenantId}/${args.fileRefId}-${safeName}`;
+}