@cosmicdrift/kumiko-bundled-features 0.2.1 → 0.2.3

package/src/user-data-rights/handlers/request-export.write.ts

@@ -0,0 +1,155 @@
+// POST /api/user/request-export (S2.U3 Atom 2) — DSGVO Art. 15 + 20 Trigger.
+//
+// User triggert Export-Job. Persistenz via createEventStoreExecutor
+// (ES-Pattern, Memory: ES kein CRUD). Idempotency-Strategie zweistufig:
+//
+//   1) **App-side-Pre-Check (primaerer Pfad):** fetchOne aktive Jobs
+//      (status pending|running) fuer den userId. Wenn existing,
+//      return `{jobId, isExisting: true}` — KEIN neues Event,
+//      sauberer Audit-Trail (1 Klick-Storm = 1 Event, nicht N).
+//
+//   2) **DB-Constraint als Race-Schutz (Sekundaerpfad):** Bei parallelem
+//      Klick zwischen fetchOne + crud.create wirft die Tx 23505 mit
+//      constraint_name === "read_export_jobs_one_active_per_user".
+//      Catch + re-fetch + return existing als isExisting=true. Race-
+//      Window <1ms, in Production extrem selten.
+//
+// **Cross-Tenant-Semantik:** ExportJob ist tenant-agnostisch (1 Job pro
+// userId ueber alle Memberships). Pre-Check nutzt ctx.db.raw (kein
+// TenantDb-Filter) — Alice klickt aus Tenant A, klickt dann aus Tenant
+// B → Pre-Check aus B findet den A-Job, kein 2. Job entsteht.
+// `requestedFromTenantId` persistiert den Initial-Tenant aus dem
+// 1. Klick — Worker liest sein Compliance-Profile aus DIESEM Tenant
+// fuer Job-TTL/Stale/Cleanup.
+
+import { createEventStoreExecutor, fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler, type SaveContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { WriteFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { eq, inArray } from "drizzle-orm";
+import { z } from "zod";
+import {
+  ACTIVE_JOB_CONSTRAINT,
+  EXPORT_JOB_STATUS,
+  exportJobEntity,
+  exportJobsTable,
+} from "../schema/export-job";
+
+const crud = createEventStoreExecutor(exportJobsTable, exportJobEntity, {
+  entityName: "export-job",
+});
+
+/**
+ * Race-Loss-Detection: createEventStoreExecutor.create catched 23505
+ * intern + returnt `WriteFailure(UniqueViolationError)`, **kein throw**.
+ * Wir checken den Failure-Code + constraintName um den App-side-vs-Race-
+ * Pfad zu unterscheiden. Andere Failures (validation, version-conflict,
+ * ...) propagieren unveraendert.
+ */
+function isActiveJobConflict(failure: WriteFailure): boolean {
+  const error = failure.error as {
+    code?: string;
+    details?: { constraintName?: string };
+  };
+  return (
+    error.code === "unique_violation" && error.details?.constraintName === ACTIVE_JOB_CONSTRAINT
+  );
+}
+
+export const requestExportWrite = defineWriteHandler({
+  name: "request-export",
+  schema: z.object({}),
+  access: { openToAll: true },
+  handler: async (event, ctx) => {
+    const userId = event.user.id;
+    const T = getTemporal();
+    const now = T.Now.instant();
+
+    // Pre-Check: ctx.db.raw weil ExportJob tenant-agnostisch ist —
+    // der TenantDb-Wrapper wuerde Cross-Tenant-Jobs ausblenden.
+    const existing = await findActiveJob(ctx.db.raw, userId);
+    if (existing) {
+      // Snapshot-Status (kann zwischen fetchOne + Response stale werden
+      // wenn Worker parallel den State flippt; window minimal). User
+      // pollt fuer Live-Wahrheit ueber export-status.query.
+      return {
+        isSuccess: true as const,
+        data: {
+          jobId: existing.id,
+          status: existing.status,
+          isExisting: true,
+        },
+      };
+    }
+
+    // Kein active Job — neuen anlegen via crud.create. requestedFromTenantId
+    // = aktueller Tenant des Users; Worker liest sein Compliance-Profile
+    // aus diesem Tenant.
+    const result = await crud.create(
+      {
+        userId,
+        requestedFromTenantId: event.user.tenantId,
+        requestedAt: now,
+        tenantId: event.user.tenantId,
+      },
+      event.user,
+      ctx.db,
+    );
+
+    if (!result.isSuccess) {
+      // Race-Pfad: paralleler Klick hat zwischen findActiveJob + crud.create
+      // einen aktiven Job angelegt → UniqueViolationError mit unserem
+      // Constraint. Re-fetch + return existing als isExisting=true.
+      // Andere Failures (validation, version-conflict, ...) propagieren.
+      if (isActiveJobConflict(result)) {
+        const winner = await findActiveJob(ctx.db.raw, userId);
+        if (!winner) {
+          // Sollte nie passieren — Constraint-Violation ohne existing
+          // active Job hiesse der Constraint matcht etwas anderes.
+          // Original-Failure zurueckgeben damit das auffaellt.
+          return result;
+        }
+        return {
+          isSuccess: true as const,
+          data: {
+            jobId: winner.id,
+            status: winner.status,
+            isExisting: true,
+          },
+        };
+      }
+      return result;
+    }
+
+    // Happy path: neuer Job. SaveContext.id ist EntityId (number | string);
+    // exportJobEntity hat idType:"uuid" → garantiert string, String()
+    // schuetzt vor Drift falls jemand die Entity auf serial migriert.
+    const created = result.data as SaveContext;
+    return {
+      isSuccess: true as const,
+      data: {
+        jobId: String(created.id),
+        // Snapshot: just-created → pending. Live-Wahrheit kommt ueber
+        // export-status.query, status hier ist nice-to-have fuer das
+        // initial UI-Render ("Anfrage angenommen, currently pending").
+        status: EXPORT_JOB_STATUS.Pending,
+        isExisting: false,
+      },
+    };
+  },
+});
+
+async function findActiveJob(
+  db: import("@cosmicdrift/kumiko-framework/db").DbRunner,
+  userId: string,
+): Promise<{ id: string; status: string } | null> {
+  // @cast-boundary db-row — fetchOne liefert generic DbRow.
+  // Variadic-conditions werden intern mit AND verknuepft.
+  const row = (await fetchOne(
+    db,
+    exportJobsTable,
+    eq(exportJobsTable["userId"], userId),
+    inArray(exportJobsTable["status"], [EXPORT_JOB_STATUS.Pending, EXPORT_JOB_STATUS.Running]),
+  )) as { id: string; status: string } | null;
+  return row;
+}

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

@@ -0,0 +1,81 @@
+import { createSystemUser, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { USER_STATUS, userTable } from "../../user";
+
+// 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).
+//
+// 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").
+//
+// State-Transitions:
+//   Active → Restricted        ✓ (dieser Handler)
+//   Restricted → Restricted    ✗ 422 already_restricted (Idempotenz-Guard)
+//   DeletionRequested → ...    ✗ 422 user_not_in_active_state
+//   Deleted → ...              ✗ 422 user_not_in_active_state
+export const restrictAccountWrite = defineWriteHandler({
+  name: "restrict-account",
+  schema: z.object({}),
+  access: { openToAll: true },
+  handler: async (event, ctx) => {
+    // ctx.db.raw weil User-Entity tenant-agnostisch ist (analog
+    // request-deletion.write.ts Cross-Tenant-Section).
+    const userRow = await ctx.db.raw
+      .select({ status: userTable["status"] })
+      .from(userTable)
+      .where(eq(userTable["id"], event.user.id))
+      .limit(1);
+
+    if (userRow.length === 0) {
+      return writeFailure(
+        new UnprocessableError("user_not_found", {
+          details: { reason: "user_not_found", userId: event.user.id },
+        }),
+      );
+    }
+
+    const currentStatus = userRow[0]?.status;
+    if (currentStatus === USER_STATUS.Restricted) {
+      return writeFailure(
+        new UnprocessableError("already_restricted", {
+          details: { reason: "already_restricted", currentStatus },
+        }),
+      );
+    }
+    if (currentStatus !== USER_STATUS.Active) {
+      return writeFailure(
+        new UnprocessableError("user_not_in_active_state", {
+          details: { reason: "user_not_in_active_state", currentStatus },
+        }),
+      );
+    }
+
+    await ctx.db.raw
+      .update(userTable)
+      .set({ status: USER_STATUS.Restricted })
+      .where(eq(userTable["id"], event.user.id));
+
+    // 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.
+    const systemUser = createSystemUser(event.user.tenantId);
+    await ctx.writeAs(systemUser, "sessions:write:user-session:revoke-all-for-user", {
+      userId: event.user.id,
+    });
+
+    return {
+      isSuccess: true as const,
+      data: {
+        userId: event.user.id,
+        status: USER_STATUS.Restricted,
+      },
+    };
+  },
+});

package/src/user-data-rights/handlers/run-forget-cleanup.write.ts

@@ -0,0 +1,61 @@
+// POST /userDataRights/run-forget-cleanup (S2.U5b).
+//
+// 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).
+//
+// Access: privileged — nur System-Caller (cron, ops-script). Im Cron-
+// Setup laeuft der Job mit `createSystemUser(...)` als executor.
+//
+// Rueckgabe: Stats fuer Operator-Monitoring (processed-count, error-list).
+
+import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { z } from "zod";
+import { runForgetCleanup, type SendDeletionExecutedEmailFn } from "../run-forget-cleanup";
+
+export type RunForgetCleanupOptions = {
+  readonly sendDeletionExecutedEmail?: SendDeletionExecutedEmailFn;
+};
+
+export function createRunForgetCleanupHandler(opts: RunForgetCleanupOptions = {}) {
+  return defineWriteHandler({
+    name: "run-forget-cleanup",
+    schema: z.object({}),
+    access: { roles: access.privileged },
+    handler: async (_event, ctx) => {
+      if (!ctx.registry) {
+        return writeFailure(
+          new InternalError({
+            message: "run-forget-cleanup: ctx.registry missing",
+          }),
+        );
+      }
+
+      // ctx.db.raw ist DbRunner. runForgetCleanup oeffnet pro User eine
+      // Sub-Tx (SAVEPOINT wenn Outer-Dispatcher-Tx aktiv) — siehe
+      // run-forget-cleanup.ts Header. Kein DbConnection-Cast noetig.
+      const T = getTemporal();
+      const result = await runForgetCleanup({
+        db: ctx.db.raw,
+        registry: ctx.registry,
+        now: T.Now.instant(),
+        ...(opts.sendDeletionExecutedEmail && {
+          sendDeletionExecutedEmail: opts.sendDeletionExecutedEmail,
+        }),
+      });
+
+      return {
+        isSuccess: true as const,
+        data: {
+          processedUserIds: result.processedUserIds,
+          hookCallsAttempted: result.hookCallsAttempted,
+          errorCount: result.errors.length,
+          errors: result.errors,
+        },
+      };
+    },
+  });
+}

package/src/user-data-rights/i18n.ts

@@ -0,0 +1,37 @@
+// @runtime client
+//
+// Default-Translations fuer user-data-rights Error-Wire-Keys (S2.U3 Atom 4b.fix3).
+//
+// Wire-Errors aus den download-handlers tragen i18nKeys statt fixe
+// Strings — UI rendert die Keys ueber den Renderer-LocaleProvider. Apps
+// koennen einzelne Keys via `userDataRightsClient({ translations: { de:
+// {...} } })` ueberschreiben (Pattern matched auth-email-password).
+//
+// **Scope 4b.fix3:** nur die download-error-keys. Andere Keys (UI-
+// Texte fuer Forget-Pfad, Status-Labels, Banner) kommen mit Atom 6+
+// (UI-Integration).
+
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+
+export const defaultTranslations: TranslationsByLocale = {
+  de: {
+    "userDataRights.errors.download.notFound":
+      "Der Download-Link ist ungültig oder gehört zu einem anderen Konto.",
+    "userDataRights.errors.download.expired":
+      "Dein Download ist abgelaufen. Bitte fordere einen neuen Export an.",
+    "userDataRights.errors.download.unavailable":
+      "Der Export ist noch nicht fertig oder fehlgeschlagen. Bitte schau im Status-Polling nach.",
+    "userDataRights.errors.download.signedUrlNotSupported":
+      "Der Download steht aufgrund einer Server-Konfiguration aktuell nicht zur Verfügung. Der Operator wurde benachrichtigt.",
+  },
+  en: {
+    "userDataRights.errors.download.notFound":
+      "The download link is invalid or belongs to a different account.",
+    "userDataRights.errors.download.expired":
+      "Your download has expired. Please request a new export.",
+    "userDataRights.errors.download.unavailable":
+      "The export is not yet ready or has failed. Please check the status endpoint.",
+    "userDataRights.errors.download.signedUrlNotSupported":
+      "The download is currently unavailable due to a server configuration issue. The operator has been notified.",
+  },
+};

package/src/user-data-rights/index.ts

@@ -0,0 +1,19 @@
+export { createUserDataRightsFeature, type UserDataRightsOptions } from "./feature";
+export type {
+  SendExportFailedEmailFn,
+  SendExportReadyEmailFn,
+} from "./run-export-jobs";
+export type { SendDeletionExecutedEmailFn } from "./run-forget-cleanup";
+// Runner-Exports — App-Tests dürfen export/forget deterministisch laufen
+// lassen, statt über den Job-Cron zu warten (siehe sample
+// user-data-rights-demo).
+export { runForgetCleanup } from "./run-forget-cleanup";
+export type { UserExportBundle } from "./run-user-export";
+export { runUserExport } from "./run-user-export";
+export {
+  ACTIVE_JOB_CONSTRAINT,
+  EXPORT_JOB_STATUS,
+  type ExportJobStatus,
+  exportJobEntity,
+  exportJobsTable,
+} from "./schema/export-job";