@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/auth-email-password/signed-token.ts

@@ -0,0 +1,85 @@
+// HMAC-signed single-purpose tokens for out-of-band auth flows
+// (password-reset, email-verification, future: magic-link).
+//
+// Format: <userId>.<expiresAtMs>.<hmac-base64url>
+//
+// The `purpose` is mixed INTO the HMAC input so a token minted for one
+// purpose (e.g. password-reset) can't be replayed against an endpoint that
+// expects another (e.g. verify-email), even if the caller knows the
+// userId and a valid expiry. Purpose is NOT carried in the token body —
+// verify() takes the purpose as argument and recomputes.
+//
+// Timing-safe comparison on verify so a valid-length forgery can't leak
+// signal through a short-circuit.
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { Temporal } from "temporal-polyfill";
+
+export type VerifyResult =
+  | { readonly ok: true; readonly userId: string; readonly expiresAtMs: number }
+  | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
+
+function sign(input: string, secret: string): string {
+  return createHmac("sha256", secret).update(input).digest("base64url");
+}
+
+function payload(purpose: string, userId: string, expiresAtMs: number): string {
+  return `${purpose}:${userId}.${expiresAtMs}`;
+}
+
+export function signToken(
+  userId: string,
+  purpose: string,
+  ttlMinutes: number,
+  secret: string,
+  now: Temporal.Instant = Temporal.Now.instant(),
+): { token: string; expiresAt: Temporal.Instant } {
+  const expiresAt = now.add({ minutes: ttlMinutes });
+  const expiresAtMs = expiresAt.epochMilliseconds;
+  const signature = sign(payload(purpose, userId, expiresAtMs), secret);
+  return {
+    token: `${userId}.${expiresAtMs}.${signature}`,
+    expiresAt,
+  };
+}
+
+export function verifyToken(
+  token: string,
+  purpose: string,
+  secret: string,
+  now: Temporal.Instant = Temporal.Now.instant(),
+): VerifyResult {
+  const parts = token.split(".");
+  if (parts.length !== 3) return { ok: false, reason: "malformed" };
+  const [userId, expiresAtRaw, providedSig] = parts;
+  if (!userId || !expiresAtRaw || !providedSig) return { ok: false, reason: "malformed" };
+
+  const expiresAtMs = Number(expiresAtRaw);
+  if (!Number.isFinite(expiresAtMs) || String(expiresAtMs) !== expiresAtRaw) {
+    return { ok: false, reason: "malformed" };
+  }
+
+  const expected = sign(payload(purpose, userId, expiresAtMs), secret);
+  const expectedBuf = Buffer.from(expected, "base64url");
+  const providedBuf = Buffer.from(providedSig, "base64url");
+  // Length mismatch fails BEFORE timingSafeEqual, which throws on different
+  // lengths — but that throw itself leaks via timing. Explicit length check
+  // keeps the path uniform.
+  if (expectedBuf.length !== providedBuf.length) return { ok: false, reason: "bad_signature" };
+  if (!timingSafeEqual(expectedBuf, providedBuf)) return { ok: false, reason: "bad_signature" };
+
+  if (Temporal.Instant.compare(now, Temporal.Instant.fromEpochMilliseconds(expiresAtMs)) > 0) {
+    return { ok: false, reason: "expired" };
+  }
+
+  // expiresAtMs surfaces so callers (burn-store TTL, telemetry, …) don't
+  // have to re-parse the token themselves.
+  return { ok: true, userId, expiresAtMs };
+}
+
+// Canonical purposes baked into the framework. Features that introduce new
+// flows extend this set (or just pass an inline string).
+export const TokenPurpose = {
+  passwordReset: "reset",
+  emailVerification: "verify",
+} as const;

package/src/auth-email-password/signup-token-store.ts

@@ -0,0 +1,104 @@
+// Redis-backed Pre-Activation-Token-Store für Magic-Link-Signup.
+//
+// Token-Material: opaque random 256-bit aus crypto.randomBytes
+// (siehe signup-request.write.ts → generateToken() aus framework/api).
+// Base64url-codiert zu 43 chars. NICHT no-confusable und NICHT für
+// menschliches Tippen — der User klickt den Mail-Link, niemand tippt
+// den Token ab.
+//
+// Anders als reset/verify-Tokens (HMAC-signed, stateless verifizierbar)
+// brauchen Signup-Tokens einen serverside Lookup: der User existiert
+// noch nicht, also gibt's keinen userId-claim den der HMAC binden
+// könnte. Wir mappen daher Token ↔ Email bidirektional in Redis und
+// löschen das Pair beim Confirm. Bidirektional weil:
+//   - by-token: confirm-handler braucht Token → Email
+//   - by-email: signup-request muss bei Resend einen existierenden
+//     Token wiederverwenden statt einen zweiten parallel laufen zu
+//     lassen (sonst hätte der User zwei Mails mit zwei verschiedenen
+//     Tokens, beide gültig, beide könnten zu zwei separaten Tenants
+//     führen wenn er beide klickt — unnötiges Risiko)
+//
+// TTL-Refresh bei Resend: wenn der Token noch lebt, refreshen wir
+// einfach beide Keys auf die volle TTL — der User bekommt eine neue
+// Mail mit dem GLEICHEN Token, alte Mail bleibt gültig (idempotent
+// für den User).
+//
+// Keine Kollision mit reset/verify-Tokens: alle Signup-Keys haben
+// `signup:`-Prefix.
+
+import type Redis from "ioredis";
+
+const TOKEN_KEY_PREFIX = "signup:by-token:";
+const EMAIL_KEY_PREFIX = "signup:by-email:";
+const BURN_KEY_PREFIX = "signup:burn:";
+
+/** Email-Normalisierung — single source für jede Lookup-Schicht (Store
+ *  intern UND Caller die im Return-Body / Mail-Send eine konsistente
+ *  Form brauchen). Vorher zwei Stellen mit `.toLowerCase()` — eine
+ *  Quelle = kein Drift. */
+export function normalizeEmail(email: string): string {
+  return email.toLowerCase();
+}
+
+function tokenKey(token: string): string {
+  return `${TOKEN_KEY_PREFIX}${token}`;
+}
+function emailKey(email: string): string {
+  return `${EMAIL_KEY_PREFIX}${normalizeEmail(email)}`;
+}
+function burnKey(token: string): string {
+  return `${BURN_KEY_PREFIX}${token}`;
+}
+
+/** Speichert das Pair bidirektional und setzt TTL auf beiden Keys.
+ *  Idempotent — re-write derselben Token-Email-Kombi ist OK. */
+export async function storeSignupToken(
+  redis: Redis,
+  args: { email: string; token: string; ttlSeconds: number },
+): Promise<void> {
+  await Promise.all([
+    redis.set(tokenKey(args.token), normalizeEmail(args.email), "EX", args.ttlSeconds),
+    redis.set(emailKey(args.email), args.token, "EX", args.ttlSeconds),
+  ]);
+}
+
+/** Lookup: Email für einen Token. Null wenn Token nicht (mehr) existiert
+ *  (abgelaufen, schon konsumiert, oder ungültig). */
+export async function getEmailForSignupToken(redis: Redis, token: string): Promise<string | null> {
+  return redis.get(tokenKey(token));
+}
+
+/** Lookup: Existierenden Token für eine Email — falls noch valid und
+ *  noch nicht konsumiert. Für Resend-Idempotenz im signup-request-Handler. */
+export async function getTokenForSignupEmail(redis: Redis, email: string): Promise<string | null> {
+  return redis.get(emailKey(email));
+}
+
+/** Single-Use-Burn: wenn zwei Tabs gleichzeitig den Confirm-Link klicken,
+ *  gewinnt der erste, der zweite kriegt "already-used". TTL = 1 Stunde
+ *  (kurz genug damit der Burn-Key Redis nicht dauerhaft belastet, lang
+ *  genug damit Replays in normalen Race-Windows abgefangen werden). */
+export async function burnSignupToken(
+  redis: Redis,
+  token: string,
+): Promise<"burned" | "already-used"> {
+  // SET NX EX — atomic check-and-set. Returnt "OK" wenn Key neu, null
+  // wenn schon da.
+  const result = await redis.set(burnKey(token), "1", "EX", 3600, "NX");
+  return result === "OK" ? "burned" : "already-used";
+}
+
+/** Cleanup nach erfolgreichem Confirm — beide Lookup-Keys löschen.
+ *  Burn-Key bleibt (verhindert Replay innerhalb der Burn-TTL). */
+export async function deleteSignupToken(
+  redis: Redis,
+  args: { email: string; token: string },
+): Promise<void> {
+  await Promise.all([redis.del(tokenKey(args.token)), redis.del(emailKey(args.email))]);
+}
+
+/** Burn-Release für Failed-Confirm-Pfade (DB-Error etc.) damit ein
+ *  legitimer Retry nicht durch einen stale Burn-Marker geblockt wird. */
+export async function unburnSignupToken(redis: Redis, token: string): Promise<void> {
+  await redis.del(burnKey(token));
+}

package/src/auth-email-password/stream-tenant.ts

@@ -0,0 +1,31 @@
+// user-feature runs with r.systemScope() but events land on a concrete
+// tenant stream. The row.version tracks whichever stream the user's last
+// modification wrote to — and that tenant is NOT discoverable from the
+// row alone.
+//
+// Strategy: prioritize lastActiveTenantId (most likely holds the latest
+// event), fall through to the remaining memberships in insertion order,
+// and let the caller try each one in sequence. The first stream whose
+// version matches row.version wins; the rest are bypassed.
+//
+// This is pragmatic — the real fix is to scope user events to
+// SYSTEM_TENANT_ID when the feature is r.systemScope(), which is a
+// framework-level change tracked separately. Until then, "try each
+// tenant the user belongs to" is robust against non-deterministic
+// memberships-query ordering (tenant:query:memberships has no ORDER BY).
+
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+
+export function orderTenantsByPreference(
+  memberships: readonly { readonly tenantId: TenantId }[],
+  lastActiveTenantId: string | null | undefined,
+): TenantId[] {
+  if (memberships.length === 0) return [];
+  const ids = memberships.map((m) => m.tenantId);
+  if (!lastActiveTenantId) return ids;
+  // Move lastActiveTenantId to the front; preserve relative order of rest.
+  const preferred = ids.find((id) => id === lastActiveTenantId);
+  if (!preferred) return ids;
+  const rest = ids.filter((id) => id !== preferred);
+  return [preferred, ...rest];
+}

package/src/auth-email-password/testing.ts

@@ -0,0 +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.
+
+export * from "./seeding";

package/src/auth-email-password/token-burn-store.ts

@@ -0,0 +1,57 @@
+// Single-use enforcement for HMAC-signed auth tokens (password-reset,
+// email-verification).
+//
+// Problem: the token itself carries only userId + expiry + signature.
+// Without server-side burn, the same token can be replayed within its
+// TTL — an attacker with short-lived mailbox access (Shoulder-Surfing,
+// Mail-Forwarding, stolen laptop) can re-use a link AFTER the legitimate
+// user has already consumed it. Industry standard (Auth0, Stripe, GitHub,
+// Google) is single-use.
+//
+// Mechanism: `SET burn:<purpose>:<userId>:<expiresAtMs> "1" EX <ttl> NX`.
+// First caller wins ("OK"), replay loses (`null`). The key's natural TTL
+// matches the token's — once the token would have expired anyway, Redis
+// reclaims the marker.
+//
+// Storage footprint: one small string per used token, auto-evicted. At
+// 10k password-resets/day × 15-min TTL, at any moment ~100 keys live.
+
+import type Redis from "ioredis";
+
+const BURN_KEY_PREFIX = "kumiko:auth:burn";
+
+export type BurnResult = "fresh" | "already-used";
+
+export async function burnToken(
+  redis: Redis,
+  purpose: string,
+  userId: string,
+  expiresAtMs: number,
+  now: number = Date.now(),
+): Promise<BurnResult> {
+  // Floor at 60s so a near-expiry token still leaves a burn marker long
+  // enough to block a replay; ceil() rounds token-TTL up so we never
+  // evict the marker before the token itself becomes invalid.
+  const ttlSeconds = Math.max(60, Math.ceil((expiresAtMs - now) / 1000));
+  const key = burnKey(purpose, userId, expiresAtMs);
+  const set = await redis.set(key, "1", "EX", ttlSeconds, "NX");
+  return set === "OK" ? "fresh" : "already-used";
+}
+
+// Release a burn marker. Called by handlers when the post-burn write path
+// failed for reasons unrelated to the token (e.g. every tenant stream
+// rejected version_conflict — the token itself was never consumed). Without
+// this, a legit retry with the same mail link would hit `already-used` and
+// lock the user out permanently within TTL.
+export async function unburnToken(
+  redis: Redis,
+  purpose: string,
+  userId: string,
+  expiresAtMs: number,
+): Promise<void> {
+  await redis.del(burnKey(purpose, userId, expiresAtMs));
+}
+
+function burnKey(purpose: string, userId: string, expiresAtMs: number): string {
+  return `${BURN_KEY_PREFIX}:${purpose}:${userId}:${expiresAtMs}`;
+}

package/src/auth-email-password/verification-token.ts

@@ -0,0 +1,27 @@
+// Thin wrapper around signed-token.ts pinning the purpose to "verify".
+// Mirrors reset-token.ts so callers can import a flow-specific helper
+// without knowing the underlying HMAC scheme.
+
+import type { Temporal } from "temporal-polyfill";
+import { signToken, TokenPurpose, verifyToken } from "./signed-token";
+
+export type VerifyResult =
+  | { readonly ok: true; readonly userId: string; readonly expiresAtMs: number }
+  | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
+
+export function signVerificationToken(
+  userId: string,
+  ttlMinutes: number,
+  secret: string,
+  now?: Temporal.Instant,
+): { token: string; expiresAt: Temporal.Instant } {
+  return signToken(userId, TokenPurpose.emailVerification, ttlMinutes, secret, now);
+}
+
+export function verifyVerificationToken(
+  token: string,
+  secret: string,
+  now?: Temporal.Instant,
+): VerifyResult {
+  return verifyToken(token, TokenPurpose.emailVerification, secret, now);
+}

package/src/auth-email-password/web/__tests__/auth-gate.test.tsx

@@ -0,0 +1,51 @@
+// @vitest-environment jsdom
+import { screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { describe, expect, test } from "vitest";
+import { makeAuthGate } from "../auth-gate";
+import { makeSessionApi, renderWithProviders } from "./test-utils";
+
+describe("makeAuthGate", () => {
+  function CustomLogin(): ReactNode {
+    return <div data-testid="custom-login">custom-login</div>;
+  }
+
+  test("loading → renders placeholder, not children, not login", () => {
+    const Gate = makeAuthGate(CustomLogin);
+    const session = makeSessionApi({ status: "loading", user: null });
+    const { container } = renderWithProviders(
+      <Gate>
+        <div data-testid="protected">secret</div>
+      </Gate>,
+      { session },
+    );
+    expect(screen.queryByTestId("protected")).toBeNull();
+    expect(screen.queryByTestId("custom-login")).toBeNull();
+    // Placeholder div ist gerendert (kein leerer Tree)
+    expect(container.firstChild).not.toBeNull();
+  });
+
+  test("unauthenticated → renders LoginComponent, not children", () => {
+    const Gate = makeAuthGate(CustomLogin);
+    const session = makeSessionApi({ status: "unauthenticated", user: null });
+    renderWithProviders(
+      <Gate>
+        <div data-testid="protected">secret</div>
+      </Gate>,
+      { session },
+    );
+    expect(screen.getByTestId("custom-login")).toBeTruthy();
+    expect(screen.queryByTestId("protected")).toBeNull();
+  });
+
+  test("authenticated → renders children, not login", () => {
+    const Gate = makeAuthGate(CustomLogin);
+    renderWithProviders(
+      <Gate>
+        <div data-testid="protected">secret</div>
+      </Gate>,
+    );
+    expect(screen.getByTestId("protected")).toBeTruthy();
+    expect(screen.queryByTestId("custom-login")).toBeNull();
+  });
+});

package/src/auth-email-password/web/__tests__/forgot-password-screen.test.tsx

@@ -0,0 +1,80 @@
+// @vitest-environment jsdom
+import { fireEvent, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { ForgotPasswordScreen } from "../forgot-password-screen";
+import { renderWithProviders } from "./test-utils";
+
+beforeEach(() => {
+  // global fetch wird von auth-client.ts gerufen — wir mocken pro Test.
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () => new Response(null, { status: 200 })),
+  );
+});
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("ForgotPasswordScreen", () => {
+  test("rendert title + email-input + submit-button (de)", () => {
+    renderWithProviders(<ForgotPasswordScreen />);
+    expect(screen.getByText("Passwort zurücksetzen")).toBeTruthy();
+    expect(screen.getByLabelText(/^E-Mail/)).toBeTruthy();
+    expect(screen.getByRole("button", { name: "Link anfordern" })).toBeTruthy();
+  });
+
+  test("submit ruft /api/auth/request-password-reset mit der Email", async () => {
+    const fetchMock = vi.fn(async () => new Response(null, { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    renderWithProviders(<ForgotPasswordScreen />);
+    fireEvent.change(screen.getByLabelText(/^E-Mail/), {
+      target: { value: "user@example.com" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Link anfordern" }));
+
+    await waitFor(() => {
+      expect(fetchMock).toHaveBeenCalledWith(
+        "/api/auth/request-password-reset",
+        expect.objectContaining({
+          method: "POST",
+          body: JSON.stringify({ email: "user@example.com" }),
+        }),
+      );
+    });
+  });
+
+  test("nach erfolgreichem Submit: success-Banner + 'Zurück zum Login'-Link", async () => {
+    renderWithProviders(<ForgotPasswordScreen />);
+    fireEvent.change(screen.getByLabelText(/^E-Mail/), {
+      target: { value: "user@example.com" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Link anfordern" }));
+
+    await waitFor(() => {
+      expect(screen.getByText("Mail gesendet")).toBeTruthy();
+    });
+    // Link zurück zum Login muss im Success-State da sein.
+    expect(screen.getByRole("link", { name: /Zurück zum Login/i })).toBeTruthy();
+  });
+
+  test("server 5xx → error-banner statt Success-State", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response(null, { status: 500 })),
+    );
+
+    renderWithProviders(<ForgotPasswordScreen />);
+    fireEvent.change(screen.getByLabelText(/^E-Mail/), {
+      target: { value: "user@example.com" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Link anfordern" }));
+
+    await waitFor(() => {
+      // unknownError-Bundle-key → "Etwas ist schief gegangen..."
+      expect(screen.getByRole("alert").textContent).toContain("schief");
+    });
+    // Kein success-state.
+    expect(screen.queryByText("Mail gesendet")).toBeNull();
+  });
+});

package/src/auth-email-password/web/__tests__/login-screen.test.tsx

@@ -0,0 +1,94 @@
+// @vitest-environment jsdom
+import { fireEvent, screen, waitFor } from "@testing-library/react";
+import { describe, expect, test, vi } from "vitest";
+import { LoginScreen } from "../login-screen";
+import { makeSessionApi, renderWithProviders } from "./test-utils";
+
+describe("LoginScreen", () => {
+  test("renders translated title + email + password labels (de)", () => {
+    renderWithProviders(<LoginScreen />);
+    expect(screen.getByText("Anmelden")).toBeTruthy();
+    expect(screen.getByLabelText(/^E-Mail/)).toBeTruthy();
+    expect(screen.getByLabelText(/^Passwort/)).toBeTruthy();
+    expect(screen.getByRole("button", { name: "Einloggen" })).toBeTruthy();
+  });
+
+  test("submit calls session.login with form values", async () => {
+    const session = makeSessionApi({ status: "unauthenticated", user: null });
+    renderWithProviders(<LoginScreen />, { session });
+
+    fireEvent.change(screen.getByLabelText(/^E-Mail/), {
+      target: { value: "demo@example.com" },
+    });
+    fireEvent.change(screen.getByLabelText(/^Passwort/), {
+      target: { value: "secret" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Einloggen" }));
+
+    await waitFor(() => {
+      expect(session.login).toHaveBeenCalledWith({
+        email: "demo@example.com",
+        password: "secret",
+      });
+    });
+  });
+
+  test("invalid_credentials → renders translated error message", async () => {
+    const session = makeSessionApi({
+      status: "unauthenticated",
+      user: null,
+      login: vi.fn(async () => ({ ok: false, error: { reason: "invalid_credentials" } })),
+    });
+    renderWithProviders(<LoginScreen />, { session });
+
+    fireEvent.change(screen.getByLabelText(/^E-Mail/), {
+      target: { value: "wrong@example.com" },
+    });
+    fireEvent.change(screen.getByLabelText(/^Passwort/), {
+      target: { value: "x" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Einloggen" }));
+
+    await waitFor(() => {
+      expect(screen.getByRole("alert")).toBeTruthy();
+      expect(screen.getByRole("alert").textContent).toBe("E-Mail oder Passwort falsch.");
+    });
+  });
+
+  test("account_locked with retryAfterSeconds renders interpolated minutes", async () => {
+    const session = makeSessionApi({
+      status: "unauthenticated",
+      user: null,
+      login: vi.fn(async () => ({
+        ok: false,
+        error: { reason: "account_locked", retryAfterSeconds: 540 },
+      })),
+    });
+    renderWithProviders(<LoginScreen />, { session });
+
+    fireEvent.change(screen.getByLabelText(/^E-Mail/), {
+      target: { value: "x@example.com" },
+    });
+    fireEvent.change(screen.getByLabelText(/^Passwort/), {
+      target: { value: "x" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Einloggen" }));
+
+    await waitFor(() => {
+      // 540s → 9 Minuten (Math.ceil)
+      expect(screen.getByRole("alert").textContent).toMatch(/9 Minuten/);
+    });
+  });
+
+  test("forgotPasswordHref-prop → Link rendert mit korrektem href", () => {
+    renderWithProviders(<LoginScreen forgotPasswordHref="/forgot-password" />);
+    const link = screen.getByRole("link", { name: /Passwort vergessen/i });
+    expect(link).toBeTruthy();
+    expect(link.getAttribute("href")).toBe("/forgot-password");
+  });
+
+  test("ohne forgotPasswordHref → KEIN Link (Login bleibt minimalistisch)", () => {
+    renderWithProviders(<LoginScreen />);
+    expect(screen.queryByRole("link", { name: /Passwort vergessen/i })).toBeNull();
+  });
+});

package/src/auth-email-password/web/__tests__/reset-password-screen.test.tsx

@@ -0,0 +1,108 @@
+// @vitest-environment jsdom
+import { fireEvent, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { ResetPasswordScreen } from "../reset-password-screen";
+import { renderWithProviders } from "./test-utils";
+
+beforeEach(() => {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () => new Response(null, { status: 200 })),
+  );
+});
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("ResetPasswordScreen", () => {
+  test("ohne Token in URL UND ohne token-Prop → missing-token-Page", () => {
+    // jsdom default location is "about:blank" → search = ""
+    renderWithProviders(<ResetPasswordScreen />);
+    expect(screen.getByText(/enthält keinen Token/i)).toBeTruthy();
+  });
+
+  test("mit token-Prop → Form rendert", () => {
+    renderWithProviders(<ResetPasswordScreen token="abc-token" />);
+    expect(screen.getByLabelText(/^Neues Passwort/)).toBeTruthy();
+    expect(screen.getByLabelText(/^Passwort bestätigen/)).toBeTruthy();
+    expect(screen.getByRole("button", { name: "Passwort speichern" })).toBeTruthy();
+  });
+
+  test("Passwort < 8 Zeichen → client-side error, kein fetch-Call", async () => {
+    const fetchMock = vi.fn(async () => new Response(null, { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    renderWithProviders(<ResetPasswordScreen token="abc" />);
+    fireEvent.change(screen.getByLabelText(/^Neues Passwort/), { target: { value: "short" } });
+    fireEvent.change(screen.getByLabelText(/^Passwort bestätigen/), { target: { value: "short" } });
+    fireEvent.click(screen.getByRole("button", { name: "Passwort speichern" }));
+
+    await waitFor(() => {
+      expect(screen.getByRole("alert").textContent).toContain("8 Zeichen");
+    });
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  test("mismatch zwischen Passwort und Confirm → client-side error", async () => {
+    renderWithProviders(<ResetPasswordScreen token="abc" />);
+    fireEvent.change(screen.getByLabelText(/^Neues Passwort/), {
+      target: { value: "validpass1" },
+    });
+    fireEvent.change(screen.getByLabelText(/^Passwort bestätigen/), {
+      target: { value: "differentpass" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Passwort speichern" }));
+
+    await waitFor(() => {
+      expect(screen.getByRole("alert").textContent).toContain("nicht überein");
+    });
+  });
+
+  test("happy path: gültiges Passwort → fetch-Call + success-State", async () => {
+    const fetchMock = vi.fn(async () => new Response(null, { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    renderWithProviders(<ResetPasswordScreen token="abc-token" />);
+    fireEvent.change(screen.getByLabelText(/^Neues Passwort/), {
+      target: { value: "validpass1" },
+    });
+    fireEvent.change(screen.getByLabelText(/^Passwort bestätigen/), {
+      target: { value: "validpass1" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Passwort speichern" }));
+
+    await waitFor(() => {
+      expect(fetchMock).toHaveBeenCalledWith(
+        "/api/auth/reset-password",
+        expect.objectContaining({
+          method: "POST",
+          body: JSON.stringify({ token: "abc-token", newPassword: "validpass1" }),
+        }),
+      );
+      expect(screen.getByText("Passwort gesetzt")).toBeTruthy();
+    });
+  });
+
+  test("server invalid_reset_token → mapped i18n-error im UI", async () => {
+    const errBody = JSON.stringify({
+      error: { code: "invalid_reset_token", details: { reason: "invalid_reset_token" } },
+    });
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response(errBody, { status: 422 })),
+    );
+
+    renderWithProviders(<ResetPasswordScreen token="bad" />);
+    fireEvent.change(screen.getByLabelText(/^Neues Passwort/), {
+      target: { value: "validpass1" },
+    });
+    fireEvent.change(screen.getByLabelText(/^Passwort bestätigen/), {
+      target: { value: "validpass1" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Passwort speichern" }));
+
+    await waitFor(() => {
+      expect(screen.getByRole("alert").textContent).toContain("ungültig");
+    });
+  });
+});