@cosmicdrift/kumiko-bundled-features 0.2.2 → 0.3.0

package/src/user-data-rights/handlers/download-by-token.query.ts

@@ -0,0 +1,255 @@
+// GET /api/query → user-data-rights:query:download-by-token (S2.U3 Atom 4b).
+//
+// **Magic-Link-Pfad** (anonymous): User klickt Email-Link mit
+// `?token=<plain>`. Worker hat beim done-flip Token-Hash in DB
+// persistiert (Atom 4a). Verify-Pipeline:
+//
+//   1. hashDownloadToken(plain) → fetchOne in download-tokens
+//   2. expiresAt > now (Multi-use within TTL — Plan-Decision)
+//   3. job.status === "done"
+//   4. job.downloadStorageKey != null (storage nicht gecleared)
+//   5. provider.getSignedUrl pflicht (501 wenn Provider local-fs ist)
+//   6. Audit-Update: useCount + 1, lastUsedAt, IP, UA (best-effort, race-tolerant)
+//   7. Return {url, expiresAt}
+//
+// **Sicherheit:**
+//   - Token-Hash-Compare via DB-fetchOne (nicht constant-time, aber
+//     timing-attacks auf SHA256-bytes brauchen >>10k requests + stable
+//     latenz — in Web-App-Kontext nicht ausnutzbar). Plan-Decision: harden
+//     wenn Pen-Test es flaggt.
+//   - 404 bei invalidem Token (kein Existenz-Leak) — gleicher Code-Pfad
+//     wie nicht-gefundenes Token.
+//   - tenant-agnostic: Token ist global eindeutig (UUID + SHA256), kein
+//     Tenant-Filter nötig.
+//
+// **r.httpRoute-Wrapper** (siehe feature.ts) macht 302-Redirect zu
+// signedUrl — User klickt 1× Email-Link, Browser folgt redirect, Download
+// startet. Dieser query-handler liefert nur das JSON.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { createFileProviderForTenant } from "../../file-foundation";
+import { recordDownloadUse, recordInvalidAttempt } from "../audit-download";
+import { exportDownloadTokensTable } from "../schema/download-token";
+import { EXPORT_JOB_STATUS, exportJobsTable } from "../schema/export-job";
+import { hashDownloadToken } from "../token-helpers";
+
+type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
+
+const SIGNED_URL_TTL_SECONDS = 300; // 5 min — kurz genug fuer Replay-Schutz, lang genug fuer slow connections
+
+interface TokenRow {
+  readonly id: string;
+  readonly version: number;
+  readonly jobId: string;
+  readonly expiresAt: Instant;
+  readonly useCount: number | null;
+}
+
+interface JobRow {
+  readonly id: string;
+  readonly userId: string;
+  readonly requestedFromTenantId: string;
+  readonly status: string;
+  readonly downloadStorageKey: string | null;
+  readonly bytesWritten: number | null;
+}
+
+export const downloadByTokenQuery = defineQueryHandler({
+  name: "download-by-token",
+  schema: z.object({
+    token: z.string().min(1, "token required"),
+    auditMeta: z
+      .object({
+        ip: z.string().nullable(),
+        userAgent: z.string().nullable(),
+      })
+      .optional(),
+  }),
+  access: { roles: ["anonymous", "Member", "User", "TenantAdmin", "SystemAdmin"] },
+  // Brute-Force-Schutz fuer Token-Hash-Probing. Anonymous-Endpoint mit
+  // 32-byte-Random-Token = 256 Bit Search-Space, aber rate-limit als
+  // defense-in-depth + Schutz gegen Storm-Patterns die DB-Last erzeugen.
+  // 30 attempts/min/IP reicht fuer legitime User (mehrere Klicks bei
+  // Connection-Abbruch); blockiert automatisierte Probing-Loops.
+  // Memory `feedback_security_default_on`.
+  rateLimit: { per: "ip", limit: 30, windowSeconds: 60 },
+  handler: async (query, ctx) => {
+    const T = getTemporal();
+    const now = T.Now.instant();
+
+    // Step 1: hash + lookup
+    const hash = await hashDownloadToken(query.payload.token);
+    // ctx.db.raw weil Token+Job tenant-agnostisch — anonymous-pfad hat
+    // keinen tenant-context im query.user.
+    const tokenRow = (await fetchOne(
+      ctx.db.raw,
+      exportDownloadTokensTable,
+      eq(exportDownloadTokensTable["tokenHash"], hash),
+    )) as TokenRow | null; // @cast-boundary db-row
+
+    if (!tokenRow) {
+      // Invalid token — 404 ohne Existenz-Leak. Generic NotFoundError
+      // damit alle Failure-Pfade die gleiche externe Shape haben (kein
+      // Probing zwischen "Token existiert nicht" vs "Job ist failed").
+      throw new NotFoundError("export-download", undefined, {
+        i18nKey: "userDataRights.errors.download.notFound",
+      });
+    }
+
+    const auditIp = query.payload.auditMeta?.ip ?? null;
+    const auditUa = query.payload.auditMeta?.userAgent ?? null;
+
+    // Step 2: TTL-check.
+    //
+    // **Pragma:** semantisch waere 410 Gone richtig (war mal da, jetzt
+    // nicht mehr). Framework hat keine GoneError-Class; wir nutzen
+    // NotFoundError + i18nKey "expired" als Kompromiss. UI rendert
+    // anhand des i18nKeys, nicht des HTTP-Status — also User sieht
+    // "Dein Download ist abgelaufen", nicht generic "not found".
+    if (tokenRow.expiresAt.epochMilliseconds <= now.epochMilliseconds) {
+      // Audit-Skip noch nicht moeglich — jobRow noch nicht geladen,
+      // tenantId unbekannt. Wir laden den Job hier noch fuer Audit-Context
+      // (best-effort — wenn Job auch fehlt, audit-skip ist akzeptabel).
+      const jobForAudit = (await fetchOne(
+        ctx.db.raw,
+        exportJobsTable,
+        eq(exportJobsTable["id"], tokenRow.jobId),
+      )) as { requestedFromTenantId: string } | null; // @cast-boundary db-row
+      if (jobForAudit) {
+        const auditDb = ctx.db.raw as DbConnection; // @cast-boundary db-runner
+        await recordInvalidAttempt({
+          db: auditDb,
+          tenantId: jobForAudit.requestedFromTenantId as Parameters<
+            typeof recordInvalidAttempt
+          >[0]["tenantId"], // @cast-boundary engine-bridge
+          now,
+          result: "expired",
+          via: "token",
+          tokenHash: hash,
+          jobId: tokenRow.jobId,
+          attemptedByUserId: null,
+          ip: auditIp,
+          userAgent: auditUa,
+        });
+      }
+      throw new NotFoundError("export-download", undefined, {
+        i18nKey: "userDataRights.errors.download.expired",
+      });
+    }
+
+    // Step 3-4: job-checks
+    const jobRow = (await fetchOne(
+      ctx.db.raw,
+      exportJobsTable,
+      eq(exportJobsTable["id"], tokenRow.jobId),
+    )) as JobRow | null; // @cast-boundary db-row
+
+    if (!jobRow) {
+      throw new NotFoundError("export-download", undefined, {
+        i18nKey: "userDataRights.errors.download.notFound",
+      });
+    }
+    if (jobRow.status !== EXPORT_JOB_STATUS.Done) {
+      await recordInvalidAttempt({
+        db: ctx.db.raw as DbConnection, // @cast-boundary db-runner
+        tenantId: jobRow.requestedFromTenantId as Parameters<
+          typeof recordInvalidAttempt
+        >[0]["tenantId"], // @cast-boundary engine-bridge
+        now,
+        result: "failed",
+        via: "token",
+        tokenHash: hash,
+        jobId: jobRow.id,
+        attemptedByUserId: null,
+        ip: auditIp,
+        userAgent: auditUa,
+      });
+      throw new NotFoundError("export-download", undefined, {
+        i18nKey: "userDataRights.errors.download.unavailable",
+      });
+    }
+    if (!jobRow.downloadStorageKey) {
+      await recordInvalidAttempt({
+        db: ctx.db.raw as DbConnection, // @cast-boundary db-runner
+        tenantId: jobRow.requestedFromTenantId as Parameters<
+          typeof recordInvalidAttempt
+        >[0]["tenantId"], // @cast-boundary engine-bridge
+        now,
+        result: "expired",
+        via: "token",
+        tokenHash: hash,
+        jobId: jobRow.id,
+        attemptedByUserId: null,
+        ip: auditIp,
+        userAgent: auditUa,
+      });
+      throw new NotFoundError("export-download", undefined, {
+        i18nKey: "userDataRights.errors.download.expired",
+      });
+    }
+
+    // Step 5: signed-URL via provider. createFileProviderForTenant nutzt
+    // requestedFromTenantId (gleicher Tenant wie beim Worker-Storage-Write).
+    const provider = await createFileProviderForTenant(
+      ctx,
+      jobRow.requestedFromTenantId,
+      "user-data-rights:query:download-by-token",
+    );
+    if (!provider.getSignedUrl) {
+      await recordInvalidAttempt({
+        db: ctx.db.raw as DbConnection, // @cast-boundary db-runner
+        tenantId: jobRow.requestedFromTenantId as Parameters<
+          typeof recordInvalidAttempt
+        >[0]["tenantId"], // @cast-boundary engine-bridge
+        now,
+        result: "signedUrlNotSupported",
+        via: "token",
+        tokenHash: hash,
+        jobId: jobRow.id,
+        attemptedByUserId: null,
+        ip: auditIp,
+        userAgent: auditUa,
+      });
+      throw new UnprocessableError("storage_provider_signed_url_not_supported", {
+        i18nKey: "userDataRights.errors.download.signedUrlNotSupported",
+      });
+    }
+
+    const signedUrl = await provider.getSignedUrl(
+      jobRow.downloadStorageKey,
+      SIGNED_URL_TTL_SECONDS,
+      {
+        contentDisposition: `attachment; filename="user-data-export-${jobRow.id}.zip"`,
+      },
+    );
+    const signedUrlExpiresAt = T.Instant.fromEpochMilliseconds(
+      now.epochMilliseconds + SIGNED_URL_TTL_SECONDS * 1000,
+    );
+
+    // Step 6: Audit-Update best-effort. auditMeta kommt vom httpRoute-
+    // Wrapper (trusted-source). Direct-API-caller koennen luegen, aber
+    // Audit ist nicht security-relevant.
+    await recordDownloadUse({
+      db: ctx.db.raw as DbConnection, // @cast-boundary db-runner
+      tokenId: tokenRow.id,
+      tokenVersion: tokenRow.version,
+      tokenUseCount: tokenRow.useCount ?? 0,
+      tenantId: jobRow.requestedFromTenantId as Parameters<typeof recordDownloadUse>[0]["tenantId"], // @cast-boundary engine-bridge
+      now,
+      ip: query.payload.auditMeta?.ip ?? null,
+      userAgent: query.payload.auditMeta?.userAgent ?? null,
+    });
+
+    return {
+      url: signedUrl,
+      expiresAt: signedUrlExpiresAt.toString(),
+      bytesWritten: jobRow.bytesWritten,
+    };
+  },
+});

package/src/user-data-rights/handlers/export-status.query.ts

@@ -0,0 +1,76 @@
+// GET /api/user/export-status (S2.U3 Atom 2) — User-Polling.
+//
+// Liefert den meist-aktuellen ExportJob des aufrufenden Users (in
+// Reihenfolge: aktiver Job zuerst, sonst neuester done/failed).
+//
+// **Cross-User-Isolation:** Filter ist `userId === query.user.id` — kein
+// User kann fremde Job-Status sehen, auch nicht via ID-Guess. Pre-Check
+// nutzt ctx.db.raw weil ExportJob tenant-agnostisch ist (Plan-Doc-
+// "Cross-Tenant-Semantik").
+//
+// **Read-Only-Endpoint:** Pollt nur, kein State-Flip. Idempotent + cache-
+// fest. UI poll-Intervall typisch 2-5s waehrend running.
+
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import type { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { desc, eq } from "drizzle-orm";
+import { z } from "zod";
+import { exportJobsTable } from "../schema/export-job";
+
+type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
+
+// @cast-boundary db-row — drizzle's typed-select gibt korrekte Shapes
+// fuer instant-Spalten zurueck (Temporal.Instant), aber TS-Inference
+// ueber TenantDb-Wrapper kennt das nicht. Cast auf den narrow-Shape
+// macht den Read-Pfad explizit. requestedAt ist `notNull` im Schema
+// → niemals null. Lifecycle-Felder (completedAt/expiresAt) sind
+// nullable bis Worker sie setzt.
+type ExportJobRow = {
+  readonly id: string;
+  readonly status: string;
+  readonly requestedAt: Instant;
+  readonly completedAt: Instant | null;
+  readonly expiresAt: Instant | null;
+  readonly errorMessage: string | null;
+  readonly bytesWritten: number | null;
+};
+
+export const exportStatusQuery = defineQueryHandler({
+  name: "export-status",
+  schema: z.object({}),
+  access: { openToAll: true },
+  handler: async (query, ctx) => {
+    // ctx.db.raw weil tenant-agnostisch — ein User der aus Tenant B
+    // pollt, sieht den aus Tenant A erstellten Job.
+    const rows = (await ctx.db.raw
+      .select({
+        id: exportJobsTable["id"],
+        status: exportJobsTable["status"],
+        requestedAt: exportJobsTable["requestedAt"],
+        completedAt: exportJobsTable["completedAt"],
+        expiresAt: exportJobsTable["expiresAt"],
+        errorMessage: exportJobsTable["errorMessage"],
+        bytesWritten: exportJobsTable["bytesWritten"],
+      })
+      .from(exportJobsTable)
+      .where(eq(exportJobsTable["userId"], query.user.id))
+      .orderBy(desc(exportJobsTable["requestedAt"]))
+      .limit(1)) as ExportJobRow[]; // @cast-boundary db-row
+
+    const latest = rows[0];
+    if (!latest) return { hasJob: false as const };
+
+    return {
+      hasJob: true as const,
+      job: {
+        id: latest.id,
+        status: latest.status,
+        requestedAt: latest.requestedAt.toString(),
+        completedAt: latest.completedAt?.toString() ?? null,
+        expiresAt: latest.expiresAt?.toString() ?? null,
+        errorMessage: latest.errorMessage,
+        bytesWritten: latest.bytesWritten,
+      },
+    };
+  },
+});

package/src/user-data-rights/handlers/lift-restriction.write.ts

@@ -0,0 +1,68 @@
+import { 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/lift-restriction (S2.U6) — DSGVO Art. 18 Reverse.
+//
+// **Wichtige Eigenheit:** Der User kann diesen Endpoint NICHT selber
+// aufrufen weil sein Login geblockt ist (Restricted-Status, siehe
+// login.write.ts Atom 3). Wer ein Restricted-Konto wieder aktiviert,
+// muss dafuer einen anderen Pfad nutzen — typisch Operator-Tool oder
+// Email-Magic-Link an die User-Email. App-Author entscheidet das per
+// access-Konfig oder Custom-Wrapper.
+//
+// MVP-Default: openToAll mit Self-Service-Semantik. Die Asymmetrie
+// (User koennte sich selbst freischalten WENN er einen Weg ohne Login
+// hat — z.B. valid Magic-Link aus pre-Restriction) ist akzeptabel:
+// Restriction ist *Verarbeitungs-Pause*, nicht *Sperre durch Operator*.
+// User der "ich will doch wieder mitmachen" sagt, soll das koennen.
+//
+// State-Transitions:
+//   Restricted → Active        ✓
+//   Active → ...               ✗ 422 not_restricted (Idempotenz-Guard)
+//   DeletionRequested → ...    ✗ 422 not_restricted
+//   Deleted → ...              ✗ 422 not_restricted
+export const liftRestrictionWrite = defineWriteHandler({
+  name: "lift-restriction",
+  schema: z.object({}),
+  access: { openToAll: true },
+  handler: async (event, ctx) => {
+    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("not_restricted", {
+          details: { reason: "not_restricted", currentStatus },
+        }),
+      );
+    }
+
+    await ctx.db.raw
+      .update(userTable)
+      .set({ status: USER_STATUS.Active })
+      .where(eq(userTable["id"], event.user.id));
+
+    return {
+      isSuccess: true as const,
+      data: {
+        userId: event.user.id,
+        status: USER_STATUS.Active,
+      },
+    };
+  },
+});

package/src/user-data-rights/handlers/list-download-attempts.query.ts

@@ -0,0 +1,53 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { and, desc, eq, gte, lte } from "drizzle-orm";
+import { z } from "zod";
+import { downloadAttemptsTable } from "../schema/download-attempt";
+
+// Operator-Query: invalid Download-Attempts (S2.U7).
+// DPO-Sicht fuer Brute-Force-Detection. Tenant-isolated via WHERE.
+
+const MAX_LIMIT = 100;
+
+export const listDownloadAttemptsQuery = defineQueryHandler({
+  name: "list-download-attempts",
+  schema: z
+    .object({
+      limit: z.number().int().min(1).max(MAX_LIMIT).default(50),
+      result: z.enum(["notFound", "expired", "failed", "signedUrlNotSupported"]).optional(),
+      ip: z.string().optional(),
+      from: z.iso.datetime().optional(),
+      to: z.iso.datetime().optional(),
+    })
+    .refine((v) => !v.from || !v.to || v.from <= v.to, {
+      message: "`from` must be less than or equal to `to`",
+    }),
+  access: { roles: ["Admin", "SystemAdmin"] },
+  handler: async (query, ctx) => {
+    const p = query.payload;
+    const t = downloadAttemptsTable;
+    const conditions = [eq(t["tenantId"], query.user.tenantId)];
+    if (p.result) conditions.push(eq(t["result"], p.result));
+    if (p.ip) conditions.push(eq(t["ip"], p.ip));
+    if (p.from) conditions.push(gte(t["attemptedAt"], Temporal.Instant.from(p.from)));
+    if (p.to) conditions.push(lte(t["attemptedAt"], Temporal.Instant.from(p.to)));
+
+    const rows = await ctx.db
+      .select({
+        id: t["id"],
+        result: t["result"],
+        via: t["via"],
+        tokenHash: t["tokenHash"],
+        jobId: t["jobId"],
+        attemptedByUserId: t["attemptedByUserId"],
+        ip: t["ip"],
+        userAgent: t["userAgent"],
+        attemptedAt: t["attemptedAt"],
+      })
+      .from(t)
+      .where(and(...conditions))
+      .orderBy(desc(t["attemptedAt"]))
+      .limit(p.limit);
+
+    return { rows };
+  },
+});

package/src/user-data-rights/handlers/my-audit-log.query.ts

@@ -0,0 +1,63 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { and, desc, eq, gte, lt, lte } from "drizzle-orm";
+import { z } from "zod";
+
+// DSGVO Art. 15 Selbstauskunft — User reads HIS OWN audit-log.
+// WHERE createdBy = ctx.user.id ist hard-coded (kein userId-Param,
+// anti-cross-user-Snooping). KEIN tenantId-Filter: User hat Anspruch
+// auf account-weite Sicht ueber alle Memberships — analog Forget-Pfad.
+const MAX_LIMIT = 100;
+
+export const myAuditLogQuery = defineQueryHandler({
+  name: "my-audit-log",
+  schema: z
+    .object({
+      before: z.string().regex(/^\d+$/, "cursor must be a positive integer").optional(),
+      limit: z.number().int().min(1).max(MAX_LIMIT).default(50),
+      aggregateType: z.string().optional(),
+      eventType: z.string().optional(),
+      from: z.iso.datetime().optional(),
+      to: z.iso.datetime().optional(),
+    })
+    .refine((v) => !v.from || !v.to || v.from <= v.to, {
+      message: "`from` must be less than or equal to `to`",
+      path: ["from"],
+    }),
+  access: { openToAll: true },
+  handler: async (query, ctx) => {
+    const p = query.payload;
+
+    const conditions = [eq(eventsTable.createdBy, query.user.id)];
+    if (p.aggregateType) conditions.push(eq(eventsTable.aggregateType, p.aggregateType));
+    if (p.eventType) conditions.push(eq(eventsTable.type, p.eventType));
+    if (p.from) conditions.push(gte(eventsTable.createdAt, Temporal.Instant.from(p.from)));
+    if (p.to) conditions.push(lte(eventsTable.createdAt, Temporal.Instant.from(p.to)));
+    if (p.before) conditions.push(lt(eventsTable.id, BigInt(p.before)));
+
+    // ctx.db.raw weil events-table tenantId-Spalte hat und TenantDb
+    // sonst auto-filtert auf currentTenant. Account-weite Sicht ist
+    // hier explizit gewollt; Sicherung erfolgt via createdBy-Filter.
+    const rows = await ctx.db.raw
+      .select({
+        id: eventsTable.id,
+        aggregateId: eventsTable.aggregateId,
+        aggregateType: eventsTable.aggregateType,
+        version: eventsTable.version,
+        type: eventsTable.type,
+        payload: eventsTable.payload,
+        createdAt: eventsTable.createdAt,
+      })
+      .from(eventsTable)
+      .where(and(...conditions))
+      .orderBy(desc(eventsTable.id))
+      .limit(p.limit);
+
+    const serialised = rows.map((r) => ({ ...r, id: String(r["id"]) }));
+    const last = serialised[serialised.length - 1];
+    return {
+      rows: serialised,
+      nextBefore: serialised.length === p.limit && last ? last["id"] : null,
+    };
+  },
+});

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

@@ -0,0 +1,123 @@
+import { addDurationSpec, type DurationSpec } from "@cosmicdrift/kumiko-framework/compliance";
+import { createSystemUser, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { USER_STATUS, userTable } from "../../user";
+
+// Atom 5b — Email-Notification beim deletion-requested-flip. Pattern:
+// password-reset-Callback aus auth-routes.ts. Best-effort — Throw beim
+// Send wird gefangen + per console.warn geloggt, der Status-Flip selbst
+// bleibt erfolgreich. Reasoning: user-Aktion ist abgeschlossen sobald
+// die DB-Row geflipt ist; Email-Versand ist Beleg, keine Vorbedingung.
+// Wenn Email broken ist soll der User nicht erneut "Account löschen"
+// klicken muessen.
+export type SendDeletionRequestedEmailFn = (args: {
+  readonly userId: string;
+  readonly userEmail: string;
+  readonly tenantId: string;
+  readonly gracePeriodEnd: string;
+}) => Promise<void>;
+
+export type RequestDeletionOptions = {
+  readonly sendDeletionRequestedEmail?: SendDeletionRequestedEmailFn;
+};
+
+// POST /api/user/request-deletion (S2.U5a) — DSGVO Art. 17 Forget-Antrag.
+// Flippt status=Active → deletionRequested, setzt gracePeriodEnd aus
+// Compliance-Profile. Account-weite Semantik (1 User-Row global), siehe
+// docs/plans/architecture/user-data-rights.md "Cross-Tenant-Semantik".
+export function createRequestDeletionHandler(opts: RequestDeletionOptions = {}) {
+  return defineWriteHandler({
+    name: "request-deletion",
+    schema: z.object({}),
+    access: { openToAll: true },
+    handler: async (event, ctx) => {
+      // ctx.db.raw (kein TenantDb-Wrapper) weil User-Entity tenant-agnostisch
+      // ist — siehe Plan-Doc Cross-Tenant-Section.
+      const userRow = await ctx.db.raw
+        .select({ status: userTable["status"], email: userTable["email"] })
+        .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 },
+          }),
+        );
+      }
+
+      if (userRow[0]?.status !== USER_STATUS.Active) {
+        return writeFailure(
+          new UnprocessableError("user_not_in_active_state", {
+            details: {
+              reason: "user_not_in_active_state",
+              currentStatus: userRow[0]?.status,
+            },
+          }),
+        );
+      }
+
+      // Compliance-Profile fuer gracePeriod via Cross-Feature-Query. Pattern:
+      // ctx.queryAs(user, qn, payload) — siehe auth-email-password/change-
+      // password.write.ts. @cast-boundary engine-bridge — queryAs liefert
+      // unknown, narrow auf den effektiven Profile-Shape.
+      const profile = (await ctx.queryAs(
+        createSystemUser(event.user.tenantId),
+        "compliance-profiles:query:for-tenant",
+        {},
+      )) as { profile: { userRights: { gracePeriod: DurationSpec } } }; // @cast-boundary engine-payload
+
+      // addDurationSpec deckt `{days}` und `{hours}` ab. App-Server-Clock
+      // ist authoritative — instant() customType nimmt Temporal.Instant
+      // direkt, kein SQL-interval-Bypass des Codecs.
+      const gracePeriod = profile.profile.userRights.gracePeriod;
+      const T = getTemporal();
+      const gracePeriodEnd = addDurationSpec(T.Now.instant(), gracePeriod);
+
+      await ctx.db.raw
+        .update(userTable)
+        .set({
+          status: USER_STATUS.DeletionRequested,
+          gracePeriodEnd,
+        })
+        .where(eq(userTable["id"], event.user.id));
+
+      // Best-effort Email-Notification. Send-Failure darf das Write nicht
+      // killen — siehe Type-Doc oben. console.warn ist die Operator-
+      // Sichtbarkeit; defineWriteHandler-Context fuehrt aktuell keinen
+      // structured-logger durch, Refactor-Kandidat wenn ctx.log threadet.
+      const userEmail = userRow[0]?.email;
+      if (opts.sendDeletionRequestedEmail && userEmail && userEmail.length > 0) {
+        try {
+          await opts.sendDeletionRequestedEmail({
+            userId: event.user.id,
+            userEmail,
+            tenantId: event.user.tenantId,
+            gracePeriodEnd: gracePeriodEnd.toString(),
+          });
+        } catch (err) {
+          // biome-ignore lint/suspicious/noConsole: operator-visibility for email-send-failure
+          console.warn(
+            `[user-data-rights:request-deletion] sendDeletionRequestedEmail failed userId=${event.user.id} tenantId=${event.user.tenantId} err=${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+      }
+
+      // Response liefert den absoluten gracePeriodEnd-Timestamp damit
+      // Frontend/Audit/Cleanup-Runner alle denselben Wert lesen — nicht
+      // den Input-`{days|hours}`, der ist Konfiguration nicht Result.
+      return {
+        isSuccess: true as const,
+        data: {
+          userId: event.user.id,
+          status: USER_STATUS.DeletionRequested,
+          gracePeriodEnd: gracePeriodEnd.toString(),
+        },
+      };
+    },
+  });
+}