@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/auth-email-password/web/auth-client.ts

@@ -0,0 +1,350 @@
+// @runtime client
+// Browser-Seite der Auth-Routes. Dünne fetch-Wrapper um /api/auth/*
+// mit Cookie-Transport: JWT lebt im HttpOnly kumiko_auth-Cookie,
+// Double-Submit-CSRF-Token im JS-lesbaren kumiko_csrf-Cookie. Alle
+// state-changing Requests echo'n den CSRF-Token via X-CSRF-Token —
+// der Server rejected sonst mit csrf_token_missing.
+//
+// Die dispatcher-live nutzt denselben readCsrfToken-Helper; wir
+// reuse'n ihn hier, damit die Konstanten (Cookie-Name, Header-Name)
+// nicht divergieren.
+
+import { CSRF_HEADER_NAME, readCsrfToken } from "@cosmicdrift/kumiko-dispatcher-live";
+
+export type TenantSummary = {
+  readonly tenantId: string;
+  readonly roles: readonly string[];
+};
+
+export type LoginRequest = {
+  readonly email: string;
+  readonly password: string;
+};
+
+export type LoginResponse = {
+  readonly token: string;
+  readonly user: {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly roles: readonly string[];
+  };
+};
+
+export type LoginFailure = {
+  readonly reason: string;
+  readonly message?: string;
+  readonly retryAfterSeconds?: number;
+};
+
+export function csrfHeader(): Record<string, string> {
+  const token = readCsrfToken();
+  return token !== undefined ? { [CSRF_HEADER_NAME]: token } : {};
+}
+
+// POST /api/auth/login. Erfolg → token + user; Fehler → strukturiertes
+// failure-objekt mit reason (invalid_credentials, account_locked,
+// no_membership, rate_limited). Das UI rendert darüber eine passende
+// Fehler-Meldung; der Server setzt Cookies bei 200 automatisch.
+export async function login(
+  req: LoginRequest,
+): Promise<{ ok: true; data: LoginResponse } | { ok: false; error: LoginFailure }> {
+  const res = await fetch("/api/auth/login", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(req),
+  });
+  if (res.status === 429) {
+    return { ok: false, error: { reason: "rate_limited" } };
+  }
+  // @cast-boundary engine-payload — HTTP-API contract, server-side schema-validated
+  const body = (await res.json().catch(() => ({}))) as {
+    isSuccess?: boolean;
+    token?: string;
+    user?: LoginResponse["user"];
+    error?:
+      | {
+          code?: string;
+          message?: string;
+          details?: { reason?: string; retryAfterSeconds?: number };
+        }
+      | string;
+  };
+  if (body.isSuccess === true && body.token !== undefined && body.user !== undefined) {
+    return { ok: true, data: { token: body.token, user: body.user } };
+  }
+  // Der Server schickt error entweder als string ("invalid_body") oder als
+  // strukturiertes Objekt. Wir ziehen uns den sprechendsten Reason raus.
+  const err = body.error;
+  if (typeof err === "string") {
+    return { ok: false, error: { reason: err } };
+  }
+  const reason = err?.details?.reason ?? err?.code ?? "login_failed";
+  const retry = err?.details?.retryAfterSeconds;
+  return {
+    ok: false,
+    error: {
+      reason,
+      ...(err?.message !== undefined && { message: err.message }),
+      ...(retry !== undefined && { retryAfterSeconds: retry }),
+    },
+  };
+}
+
+// POST /api/auth/logout. Server revoked die Session (wenn sessionRevoker
+// gewired ist) und clear't die Cookies. Wir triggern hinterher einen
+// Navigation-Refresh, damit alle caches (React-State, query-cache) auf
+// Null gehen — billigster Weg zu sauberer Ausgangslage.
+export async function logout(): Promise<void> {
+  await fetch("/api/auth/logout", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json", ...csrfHeader() },
+  });
+}
+
+// Gemeinsamer Failure-Type für die vier Token-Flow-Endpoints (request-
+// password-reset, reset-password, request-email-verification, verify-
+// email). Server collapses alle Token-Verify-Fehler (malformed / bad-
+// signature / expired) auf einen einzigen Code pro Flow (anti-
+// enumeration); UI mappt reason → i18n-Key. Plus rate-limit (429) wird
+// als reason "rate_limited" + retryAfterSeconds durchgereicht — gleiche
+// Shape wie LoginFailure damit Apps die Errors uniform mappen können.
+export type AuthTokenFailure = {
+  readonly reason: string;
+  readonly retryAfterSeconds?: number;
+};
+
+// Backward-compat-Aliase für die alten Type-Namen — damit Code, der
+// `ResetPasswordFailure` / `VerifyEmailFailure` importiert hat, ohne
+// Änderung weiterläuft. Für neuen Code direkt `AuthTokenFailure` nutzen.
+export type ResetPasswordFailure = AuthTokenFailure;
+export type VerifyEmailFailure = AuthTokenFailure;
+
+// 4xx/5xx → typed AuthTokenFailure parsen. 429 (Rate-Limit) hat einen
+// dedizierten reason damit das UI einen Retry-Hinweis zeigen kann.
+async function parseTokenFailure(res: Response): Promise<AuthTokenFailure> {
+  if (res.status === 429) {
+    // @cast-boundary engine-payload — server schickt details.retryAfterSeconds bei 429
+    const body = (await res.json().catch(() => ({}))) as {
+      error?: { details?: { retryAfterSeconds?: number } };
+    };
+    const retry = body.error?.details?.retryAfterSeconds;
+    return { reason: "rate_limited", ...(retry !== undefined && { retryAfterSeconds: retry }) };
+  }
+  // @cast-boundary engine-payload — server-side schema-validated body
+  const body = (await res.json().catch(() => ({}))) as {
+    error?: { code?: string; details?: { reason?: string } };
+  };
+  const reason = body.error?.details?.reason ?? body.error?.code ?? "unknown";
+  return { reason };
+}
+
+// POST /api/auth/request-password-reset. 200 silent-success: auch wenn
+// die Email nicht existiert, sieht der caller `{ ok: true }` — kein
+// account-enumeration. Server triggert Mail nur intern wenn user
+// gefunden. 429 → typed rate-limit-Failure. 5xx → unknown-error.
+export async function requestPasswordReset(
+  email: string,
+): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
+  const res = await fetch("/api/auth/request-password-reset", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json", ...csrfHeader() },
+    body: JSON.stringify({ email }),
+  });
+  if (res.ok) return { ok: true };
+  return { ok: false, error: await parseTokenFailure(res) };
+}
+
+// POST /api/auth/reset-password. Token aus URL + neues Passwort. Auf
+// 422 collapses der Server alle Token-Verify-Fehler (malformed / bad-
+// signature / expired) auf den einzigen Code `invalid_reset_token` —
+// anti-enumeration. Plus zod-validation-failures (newPassword < 8) als
+// eigene 4xx mit code "validation_failed". UI mappt reason → i18n-Key.
+export async function resetPassword(
+  token: string,
+  newPassword: string,
+): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
+  const res = await fetch("/api/auth/reset-password", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json", ...csrfHeader() },
+    body: JSON.stringify({ token, newPassword }),
+  });
+  if (res.ok) return { ok: true };
+  return { ok: false, error: await parseTokenFailure(res) };
+}
+
+// POST /api/auth/request-email-verification. Same silent-success
+// semantik wie request-password-reset. 429 → rate-limit-Failure.
+export async function requestEmailVerification(
+  email: string,
+): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
+  const res = await fetch("/api/auth/request-email-verification", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json", ...csrfHeader() },
+    body: JSON.stringify({ email }),
+  });
+  if (res.ok) return { ok: true };
+  return { ok: false, error: await parseTokenFailure(res) };
+}
+
+// POST /api/auth/verify-email. Auto-submitted vom VerifyEmailScreen
+// nach `?token=...`-parse. Server collapses alle Verify-Failures auf
+// `invalid_verification_token` (anti-enumeration, parallel zu reset).
+export async function verifyEmail(
+  token: string,
+): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
+  const res = await fetch("/api/auth/verify-email", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json", ...csrfHeader() },
+    body: JSON.stringify({ token }),
+  });
+  if (res.ok) return { ok: true };
+  return { ok: false, error: await parseTokenFailure(res) };
+}
+
+// POST /api/auth/signup-request. Always-200 (anti-enumeration; wir
+// sagen nicht ob die Email schon registriert ist). Server schickt
+// Activation-Mail an die Adresse — beim Klick auf den Link landet der
+// User auf /signup/complete?token=… wo er sein Password setzt.
+export async function requestSignup(
+  email: string,
+): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
+  const res = await fetch("/api/auth/signup-request", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json", ...csrfHeader() },
+    body: JSON.stringify({ email }),
+  });
+  if (res.ok) return { ok: true };
+  return { ok: false, error: await parseTokenFailure(res) };
+}
+
+// POST /api/auth/signup-confirm. Token aus URL + Password. Erfolgreich:
+// Cookies (kumiko_auth + kumiko_csrf) werden gesetzt — User ist sofort
+// eingeloggt. Response liefert tenantKey für den Post-Signup-Redirect.
+// 422 invalid_signup_token bei abgelaufenem/unbekanntem Token.
+export type SignupConfirmSuccess = {
+  readonly user: { readonly id: string; readonly tenantId: string; readonly roles: string[] };
+  readonly tenantKey: string;
+};
+
+export async function confirmSignup(
+  token: string,
+  password: string,
+): Promise<{ ok: true; data: SignupConfirmSuccess } | { ok: false; error: AuthTokenFailure }> {
+  const res = await fetch("/api/auth/signup-confirm", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json", ...csrfHeader() },
+    body: JSON.stringify({ token, password }),
+  });
+  if (res.ok) {
+    const body = (await res.json()) as SignupConfirmSuccess;
+    return { ok: true, data: body };
+  }
+  return { ok: false, error: await parseTokenFailure(res) };
+}
+
+// GET /api/auth/tenants. Liefert die Memberships des aktuellen Users;
+// der Server liefert 401 wenn das Cookie fehlt oder abgelaufen ist.
+export async function fetchTenants(): Promise<{
+  readonly tenants: readonly TenantSummary[];
+  readonly activeTenantId: string;
+} | null> {
+  const res = await fetch("/api/auth/tenants", {
+    method: "GET",
+    credentials: "same-origin",
+  });
+  if (res.status === 401) return null;
+  if (!res.ok) throw new Error(`auth/tenants failed: ${res.status}`);
+  // @cast-boundary engine-payload — HTTP-API contract, server-side schema-validated
+  return (await res.json()) as {
+    tenants: readonly TenantSummary[];
+    activeTenantId: string;
+  };
+}
+
+// POST /api/auth/switch-tenant. Mintet ein neues JWT für den Ziel-Tenant
+// und rotated beide Cookies. 400 wenn already_in_tenant oder tenant_
+// switch_not_available, 403 wenn not_a_member.
+export async function switchTenant(tenantId: string): Promise<void> {
+  const res = await fetch("/api/auth/switch-tenant", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json", ...csrfHeader() },
+    body: JSON.stringify({ tenantId }),
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(`switch-tenant failed: ${res.status} ${JSON.stringify(body)}`);
+  }
+}
+
+// POST /api/query → user:query:user:me. Profil-Daten (email, displayName)
+// für das UserMenu im Topbar. 401 → kein Cookie / abgelaufen, wird
+// vom SessionProvider als "ausgeloggt" interpretiert.
+//
+// globalRoles: tenant-unabhängige user-rollen (z.B. SystemAdmin) aus
+// users.roles. Im JWT schon mit tenant-membership-roles gemerged, aber
+// das JWT ist HttpOnly + nicht JS-lesbar — der Client muss die globalen
+// Rollen separat aus dem user-row holen damit nav-filtering greift.
+export type CurrentUserProfile = {
+  readonly id: string;
+  readonly email: string;
+  readonly displayName: string;
+  readonly locale?: string;
+  readonly globalRoles: readonly string[];
+};
+
+export async function fetchCurrentUser(): Promise<CurrentUserProfile | null> {
+  const res = await fetch("/api/query", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json", ...csrfHeader() },
+    body: JSON.stringify({ type: "user:query:user:me", payload: {} }),
+  });
+  if (res.status === 401) return null;
+  if (!res.ok) throw new Error(`user:me failed: ${res.status}`);
+  // @cast-boundary engine-payload — HTTP-API contract, server-side schema-validated
+  const body = (await res.json()) as {
+    data?: {
+      id: string;
+      email: string;
+      displayName: string;
+      locale?: string;
+      // JSON-encoded string[] — siehe userEntity.roles. Default "[]" wenn
+      // keine globalen Rollen.
+      roles?: string;
+    };
+  };
+  if (!body.data) return null;
+  return {
+    id: body.data.id,
+    email: body.data.email,
+    displayName: body.data.displayName,
+    ...(body.data.locale !== undefined && { locale: body.data.locale }),
+    globalRoles: parseGlobalRoles(body.data.roles),
+  };
+}
+
+// Defensive parse — server-side ist die Spalte JSON-encoded string[],
+// aber bei migration-drift oder corrupted-row liefern wir [] statt einen
+// runtime-throw der die ganze SessionProvider-mount blockt.
+function parseGlobalRoles(raw: string | undefined): readonly string[] {
+  if (typeof raw !== "string" || raw.length === 0) return [];
+  try {
+    // @cast-boundary user-row.roles is JSON-encoded string[] per server contract
+    const parsed = JSON.parse(raw) as unknown;
+    if (Array.isArray(parsed) && parsed.every((r) => typeof r === "string")) {
+      return parsed;
+    }
+  } catch {
+    // malformed JSON → behave as empty
+  }
+  return [];
+}

package/src/auth-email-password/web/auth-form-primitives.tsx

@@ -0,0 +1,70 @@
+// @runtime client
+// Shared Web-Primitives für die Auth-Screens. Nur noch Layout/Style-
+// Helpers — Form/Field/Input/Button/Banner kommen jetzt über
+// usePrimitives() aus dem Framework-Vertrag, damit Native dieselben
+// Auth-Screens rendern kann (renderer-native registriert eigene
+// Implementations).
+//
+//   <AuthCard>          — Card-Wrapper für die Auth-Screen-Layouts
+//                         (full-screen, zentriert, max-w-sm). Web-only;
+//                         eine Native-Variante landet bei Bedarf
+//                         daneben (z.B. SafeArea + ScrollView).
+//   authButtonClass     — Tailwind-Class für anchor-styled-as-button
+//                         (z.B. "Zum Login"-Link nach Reset-Success).
+//                         Nur dort, wo ein <a>-Tag rendert.
+//   authMutedLinkClass  — Subtle-Link-Style.
+//   parseUrlToken       — URL-Param-Helper (window.location.search).
+
+import { cn } from "@cosmicdrift/kumiko-renderer-web";
+import type { ReactNode } from "react";
+
+export type AuthCardProps = {
+  readonly title?: string;
+  readonly subtitle?: ReactNode;
+  readonly children: ReactNode;
+};
+
+export function AuthCard({ title, subtitle, children }: AuthCardProps): ReactNode {
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-background px-4">
+      <div className="w-full max-w-sm rounded-lg border bg-card text-card-foreground shadow-sm">
+        {(title !== undefined || subtitle !== undefined) && (
+          <div className="flex flex-col space-y-1.5 p-6 pb-4">
+            {title !== undefined && (
+              <h1 className="text-xl font-semibold tracking-tight">{title}</h1>
+            )}
+            {subtitle !== undefined && <p className="text-sm text-muted-foreground">{subtitle}</p>}
+          </div>
+        )}
+        {children}
+      </div>
+    </div>
+  );
+}
+
+// Primary-button-Style für anchor-Tags die wie ein Button aussehen
+// (z.B. "Zum Login"-Link nach Reset-Success — kein <Button> weil <a>).
+export const authButtonClass = cn(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors",
+  "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+  "disabled:pointer-events-none disabled:opacity-50",
+  "bg-primary text-primary-foreground shadow hover:bg-primary/90 h-9 px-4 py-2",
+);
+
+// Subtle-Link-Style (für "Zurück zum Login"-Anchors). Fixed margin/
+// alignment-classes lassen wir den Caller setzen — nur Farbe + hover.
+export const authMutedLinkClass =
+  "text-sm text-muted-foreground hover:text-foreground underline-offset-4 hover:underline";
+
+// Liest `?<paramName>=<value>` aus der aktuellen URL — typisches
+// Pattern für Token-bearing Pages (reset, verify). Returnt "" wenn der
+// Browser nicht da ist (SSR-safety) oder der Parameter fehlt.
+//
+// Nicht über useState/useEffect - das wäre ein read-once-on-mount
+// pattern aber URL-changes sind hier irrelevant (Token-Pages re-loaden
+// für neue Tokens). Caller setzt useState(() => parseUrlToken(...)) wenn
+// gewünscht.
+export function parseUrlToken(paramName = "token"): string {
+  if (typeof window === "undefined") return "";
+  return new URLSearchParams(window.location.search).get(paramName) ?? "";
+}

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

@@ -0,0 +1,33 @@
+// @runtime client
+// Auth-Gate: rendert den LoginScreen solange der Session-Status
+// "unauthenticated" ist, sonst die Kinder. "loading" zeigt einen
+// minimalen Placeholder — die initiale Refresh-Runde liefert in der
+// Regel in <100ms, also kein Spinner-Overkill.
+//
+// Die Factory makeAuthGate schließt die LoginScreen-Komponente in,
+// damit das Gate der ClientFeatureDefinition-Signatur entspricht
+// (nur `{ children }`-Prop). Der Sample kann so einen eigenen Login-
+// Screen rein konfigurieren, ohne den Gate selbst ersetzen zu müssen.
+
+import type { ComponentType, ReactNode } from "react";
+import { LoginScreen, type LoginScreenProps } from "./login-screen";
+import { useSession } from "./session";
+
+export function makeAuthGate(
+  LoginComponent: ComponentType<LoginScreenProps> = LoginScreen,
+  loginProps?: LoginScreenProps,
+): ComponentType<{ children: ReactNode }> {
+  function AuthGate({ children }: { readonly children: ReactNode }): ReactNode {
+    const { status } = useSession();
+    if (status === "loading") {
+      return (
+        <div className="min-h-screen flex items-center justify-center text-muted-foreground text-sm" />
+      );
+    }
+    if (status === "unauthenticated") {
+      return <LoginComponent {...loginProps} />;
+    }
+    return <>{children}</>;
+  }
+  return AuthGate;
+}

package/src/auth-email-password/web/client-plugin.ts

@@ -0,0 +1,48 @@
+// @runtime client
+// Client-Feature-Factory für auth-email-password. Wird vom App-Code
+// in createKumikoApp({ clientFeatures: [emailPasswordClient()] })
+// eingehängt und bringt Session-Context + AuthGate + Default-UI-
+// Translations (de/en) mit. Alles ist overridbar — Login-Screen,
+// Strings pro Locale, pro Key.
+
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ComponentType, ReactNode } from "react";
+import { defaultTranslations, mergeTranslations } from "../i18n";
+import { makeAuthGate } from "./auth-gate";
+import type { LoginScreenProps } from "./login-screen";
+import { SessionProvider } from "./session";
+
+export type EmailPasswordClientOptions = {
+  /** Eigener Login-Screen. Default: der shadcn-stylte LoginScreen
+   *  aus diesem Modul. Für Branding- oder Layout-Overrides einfach
+   *  eine eigene Komponente mit derselben Signatur reichen. */
+  readonly loginScreen?: ComponentType<LoginScreenProps>;
+  readonly loginScreenProps?: LoginScreenProps;
+  /** Key-Overrides pro Locale. Wird mit den Default-Bundles (de/en)
+   *  aus `translations.ts` gemerged — jeder hier gesetzte Key gewinnt.
+   *  Für Branding ("Sign in" → "Login to Acme") oder weitere Sprachen
+   *  (`fr`, `es`, …) zusätzlich. */
+  readonly translations?: TranslationsByLocale;
+};
+
+// Struktural identisch zur renderer-web ClientFeatureDefinition, aber
+// ohne harte Dep auf @cosmicdrift/kumiko-renderer-web — so bleibt das Feature auch
+// für React-Native-Renderer (wenn sie kommen) nutzbar.
+export type EmailPasswordClientFeature = {
+  readonly name: "auth-email-password";
+  readonly providers: readonly ComponentType<{ children: ReactNode }>[];
+  readonly gates: readonly ComponentType<{ children: ReactNode }>[];
+  readonly translations: TranslationsByLocale;
+};
+
+export function emailPasswordClient(
+  options: EmailPasswordClientOptions = {},
+): EmailPasswordClientFeature {
+  const translations = mergeTranslations(defaultTranslations, options.translations ?? {});
+  return {
+    name: "auth-email-password",
+    providers: [SessionProvider],
+    gates: [makeAuthGate(options.loginScreen, options.loginScreenProps)],
+    translations,
+  };
+}

package/src/auth-email-password/web/default-topbar-actions.tsx

@@ -0,0 +1,47 @@
+// @runtime client
+// Standard-Topbar-Actions Komposition für Apps mit Auth + Workspaces.
+// Bündelt das Pattern das jeder App-Sample sonst hand-ausschreibt:
+// TenantSwitcher (links) → optional Extras (z.B. LanguageSwitcher) →
+// ThemeToggle → UserMenu (rechts). Apps mit eigener Anordnung
+// importieren weiter die Einzelkomponenten direkt — DefaultTopbarActions
+// ist Convenience, kein Muss.
+
+import { ThemeToggle } from "@cosmicdrift/kumiko-renderer-web";
+import type { ReactNode } from "react";
+import { TenantSwitcher } from "./tenant-switcher";
+import { UserMenu } from "./user-menu";
+
+export type DefaultTopbarActionsProps = {
+  /** Mapped Tenant-ID auf einen sprechenden Namen (z.B. branded label
+   *  pro Tenant). TenantSwitcher's Default zeigt sonst die ersten 8
+   *  Zeichen der UUID. */
+  readonly tenantName?: (tenantId: string) => string;
+  /** Slot zwischen TenantSwitcher und ThemeToggle. Typischer Use-Case:
+   *  LanguageSwitcher pro App. ReactNode (nicht Array) damit die App
+   *  selbst Reihenfolge + Spacing bestimmt. */
+  readonly extras?: ReactNode;
+  /** Light-Mode-Icon im ThemeToggle. Default: Unicode ☀. Apps die
+   *  Lucide-Icons o.ä. wollen, übergeben ein eigenes Icon-Element. */
+  readonly lightIcon?: ReactNode;
+  /** Dark-Mode-Icon. Default: Unicode ☾. */
+  readonly darkIcon?: ReactNode;
+};
+
+export function DefaultTopbarActions({
+  tenantName,
+  extras,
+  lightIcon,
+  darkIcon,
+}: DefaultTopbarActionsProps = {}): ReactNode {
+  return (
+    <div className="flex items-center gap-2">
+      <TenantSwitcher {...(tenantName !== undefined && { tenantName })} />
+      {extras}
+      <ThemeToggle
+        {...(lightIcon !== undefined && { lightIcon })}
+        {...(darkIcon !== undefined && { darkIcon })}
+      />
+      <UserMenu />
+    </div>
+  );
+}

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

@@ -0,0 +1,110 @@
+// @runtime client
+// ForgotPasswordScreen — Form mit email-input. Submit triggert
+// /api/auth/request-password-reset (silent-success, kein account-
+// enumeration). UI zeigt unconditional ein "Wenn Account existiert,
+// Mail unterwegs"-Confirm — auch wenn der Server intern erkannt hat
+// dass die Email nicht existiert.
+//
+// App ist verantwortlich, den Screen unter einer URL zu mounten (z.B.
+// /forgot-password) und ihn zu erreichen — der LoginScreen kann einen
+// "Passwort vergessen?"-Link auf die App-Route setzen.
+
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type FormEvent, type ReactNode, useState } from "react";
+import { requestPasswordReset } from "./auth-client";
+import { AuthCard, authMutedLinkClass } from "./auth-form-primitives";
+
+export type ForgotPasswordScreenProps = {
+  readonly title?: string;
+  readonly subtitle?: ReactNode;
+  /** href für den "Zurück zum Login"-Link in success + form. App-
+   *  spezifisch — Default "/login". */
+  readonly loginHref?: string;
+};
+
+export function ForgotPasswordScreen({
+  title,
+  subtitle,
+  loginHref = "/login",
+}: ForgotPasswordScreenProps): ReactNode {
+  const t = useTranslation();
+  const { Form, Field, Input, Button, Banner } = usePrimitives();
+  const [email, setEmail] = useState("");
+  const [submitting, setSubmitting] = useState(false);
+  const [done, setDone] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const doSubmit = async (): Promise<void> => {
+    setSubmitting(true);
+    setError(null);
+    try {
+      const res = await requestPasswordReset(email);
+      if (res.ok) {
+        setDone(true);
+      } else if (res.error.reason === "rate_limited") {
+        const minutes =
+          res.error.retryAfterSeconds !== undefined
+            ? Math.ceil(res.error.retryAfterSeconds / 60)
+            : undefined;
+        setError(
+          minutes !== undefined
+            ? t("auth.errors.accountLockedRetry", { minutes })
+            : t("auth.errors.rateLimited"),
+        );
+      } else {
+        setError(t("auth.errors.unknownError"));
+      }
+    } catch {
+      setError(t("auth.errors.unknownError"));
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const onSubmit = (e?: FormEvent): void => {
+    e?.preventDefault();
+    void doSubmit();
+  };
+
+  const effectiveTitle = title ?? t("auth.forgotPassword.title");
+
+  return (
+    <AuthCard title={effectiveTitle} subtitle={subtitle}>
+      {done ? (
+        <div className="p-6 pt-0 flex flex-col gap-4">
+          <Banner variant="info">
+            <p className="font-medium text-foreground">{t("auth.forgotPassword.successTitle")}</p>
+            <p className="mt-1">{t("auth.forgotPassword.successBody")}</p>
+          </Banner>
+          <a href={loginHref} className={authMutedLinkClass}>
+            {t("auth.forgotPassword.backToLogin")}
+          </a>
+        </div>
+      ) : (
+        <div className="p-6 pt-0 flex flex-col gap-4">
+          <p className="text-sm text-muted-foreground">{t("auth.forgotPassword.intro")}</p>
+          <Form onSubmit={onSubmit}>
+            <Field id="forgot-email" label={t("auth.forgotPassword.email")} required>
+              <Input
+                kind="text"
+                id="forgot-email"
+                name="forgot-email"
+                value={email}
+                onChange={setEmail}
+                disabled={submitting}
+                required
+              />
+            </Field>
+            {error !== null && <Banner variant="error">{error}</Banner>}
+            <Button type="submit" loading={submitting} disabled={submitting}>
+              {submitting ? t("auth.forgotPassword.submitting") : t("auth.forgotPassword.submit")}
+            </Button>
+          </Form>
+          <a href={loginHref} className={`${authMutedLinkClass} self-center`}>
+            {t("auth.forgotPassword.backToLogin")}
+          </a>
+        </div>
+      )}
+    </AuthCard>
+  );
+}