@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

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

@@ -34,8 +34,24 @@ export type LoginResponse = {
   };
 };
 
+// Reason codes the login-handler is known to emit today (login-screen.tsx's
+// reasonToKey maps every one of these to an i18n key). The server can also
+// send a reason this client doesn't know about yet (rolling deploys, a new
+// enforcement policy) — `string & {}` keeps that open while still giving
+// autocomplete/typo-checking on the known set, instead of collapsing both
+// to plain `string` (coding-standards: no magic strings without a union).
+export type KnownLoginFailureReason =
+  | "invalid_credentials"
+  | "no_membership"
+  | "account_locked"
+  | "email_not_verified"
+  | "rate_limited"
+  | "invalid_body"
+  | "mfa_not_supported"
+  | "mfa_setup_required";
+
 export type LoginFailure = {
-  readonly reason: string;
+  readonly reason: KnownLoginFailureReason | (string & {});
   readonly message?: string;
   readonly retryAfterSeconds?: number;
 };
@@ -45,13 +61,24 @@ export function csrfHeader(): Record<string, string> {
   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 }> {
+// LoginResult mirrors the two-step login contract auth-routes.ts owns: a
+// straight success, an MFA challenge (auth-mfa mints the token), an
+// MFA-setup-required block (enforcement policy blocks an unenrolled user),
+// or a plain failure. One discriminated union, not `{ok}` booleans, because
+// callers branch on 4 arms.
+export type LoginResult =
+  | { readonly kind: "success"; readonly data: LoginResponse }
+  | { readonly kind: "mfa-challenge"; readonly challengeToken: string }
+  | { readonly kind: "mfa-setup-required"; readonly preauthSetupToken: string }
+  | { readonly kind: "failure"; readonly error: LoginFailure };
+
+// POST /api/auth/login. Success → token + user; MFA-enrolled user → a
+// challenge token the caller completes via auth-mfa's verify screen;
+// unenrolled user blocked by enforcement policy → mfa-setup-required;
+// otherwise a structured failure with reason (invalid_credentials,
+// account_locked, no_membership, rate_limited). The server sets cookies
+// automatically on any 200.
+export async function login(req: LoginRequest): Promise<LoginResult> {
   const res = await fetch("/api/auth/login", {
     method: "POST",
     credentials: "same-origin",
@@ -59,13 +86,17 @@ export async function login(
     body: JSON.stringify(req),
   });
   if (res.status === 429) {
-    return { ok: false, error: { reason: "rate_limited" } };
+    return { kind: "failure", 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"];
+    mfaRequired?: boolean;
+    challengeToken?: string;
+    mfaSetupRequired?: boolean;
+    preauthSetupToken?: string;
     error?:
       | {
           code?: string;
@@ -74,19 +105,33 @@ export async function login(
         }
       | string;
   };
-  if (body.isSuccess === true && body.token !== undefined && body.user !== undefined) {
-    return { ok: true, data: { token: body.token, user: body.user } };
+  if (body.isSuccess === true) {
+    if (body.mfaRequired === true && typeof body.challengeToken === "string") {
+      return { kind: "mfa-challenge", challengeToken: body.challengeToken };
+    }
+    if (body.mfaSetupRequired === true) {
+      // Older servers / mounts may set the flag without minting a preauth token —
+      // surface an explicit failure (login-screen maps mfa_setup_required) instead
+      // of falling through to generic login_failed.
+      if (typeof body.preauthSetupToken === "string") {
+        return { kind: "mfa-setup-required", preauthSetupToken: body.preauthSetupToken };
+      }
+      return { kind: "failure", error: { reason: "mfa_setup_required" } };
+    }
+    if (body.token !== undefined && body.user !== undefined) {
+      return { kind: "success", 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 } };
+    return { kind: "failure", error: { reason: err } };
   }
   const reason = err?.details?.reason ?? err?.code ?? "login_failed";
   const retry = err?.details?.retryAfterSeconds;
   return {
-    ok: false,
+    kind: "failure",
     error: {
       reason,
       ...(err?.message !== undefined && { message: err.message }),
@@ -144,10 +189,10 @@ async function parseTokenFailure(res: Response): Promise<AuthTokenFailure> {
   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.
+// POST /api/auth/request-password-reset. 200 silent-success: even if the
+// email doesn't exist, the caller sees `{ ok: true }` — no account
+// enumeration. Server only triggers the mail internally when a user is
+// found. 429 → typed rate-limit failure. 5xx → unknown-error.
 export async function requestPasswordReset(
   email: string,
 ): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
@@ -181,7 +226,7 @@ export async function resetPassword(
 }
 
 // POST /api/auth/request-email-verification. Same silent-success
-// semantik wie request-password-reset. 429 → rate-limit-Failure.
+// semantics as request-password-reset. 429 → rate-limit failure.
 export async function requestEmailVerification(
   email: string,
 ): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
@@ -211,6 +256,39 @@ export async function verifyEmail(
   return { ok: false, error: await parseTokenFailure(res) };
 }
 
+// POST /api/auth/request-account-unlock. Same silent-success semantics as
+// request-password-reset. 429 → rate-limit failure.
+export async function requestAccountUnlock(
+  email: string,
+): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
+  const res = await fetch("/api/auth/request-account-unlock", {
+    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/confirm-account-unlock. Auto-submitted by
+// ConfirmAccountUnlockScreen after parsing `?token=...`. Server collapses
+// every verify failure into `invalid_unlock_token` (anti-enumeration,
+// parallel to reset/verify). Only clears the Redis lockout state, no
+// entity write.
+export async function confirmAccountUnlock(
+  token: string,
+): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
+  const res = await fetch("/api/auth/confirm-account-unlock", {
+    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

package/src/auth-email-password/web/auth-form-logic.ts

@@ -0,0 +1,30 @@
+// @runtime client
+// Pure form helpers shared by auth screens. Extracted so unit tests can
+// pin password / rate-limit / redirect rules without mounting React.
+
+export type PasswordPairIssue = "too_short" | "mismatch";
+
+/** Client-side password + confirm check before calling signup/reset APIs. */
+export function passwordPairIssue(
+  password: string,
+  confirmPassword: string,
+  minLength = 8,
+): PasswordPairIssue | null {
+  if (password.length < minLength) return "too_short";
+  if (password !== confirmPassword) return "mismatch";
+  return null;
+}
+
+/** Maps server `retryAfterSeconds` to whole minutes for i18n interpolation. */
+export function retryAfterMinutes(retryAfterSeconds?: number): number | undefined {
+  if (retryAfterSeconds === undefined) return undefined;
+  return Math.ceil(retryAfterSeconds / 60);
+}
+
+/** Resolves post-login redirect: string template or function of tenantKey. */
+export function resolveLoggedInHref(
+  href: string | ((args: { readonly tenantKey: string }) => string),
+  tenantKey: string,
+): string {
+  return typeof href === "function" ? href({ tenantKey }) : href;
+}

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

@@ -9,15 +9,14 @@
 //                         (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).
+//
+// Link-Styles laufen über das Link-Primitive (variant="button"/"muted") —
+// die früheren authButtonClass/authMutedLinkClass sind dorthin gewandert.
 
 import { usePrimitives } from "@cosmicdrift/kumiko-renderer";
-import { BareFormProvider, cn } from "@cosmicdrift/kumiko-renderer-web";
-import { createContext, type ReactNode, useContext } from "react";
+import { BareFormProvider } from "@cosmicdrift/kumiko-renderer-web";
+import { createContext, type ReactNode, useContext, useEffect, useState } from "react";
 
 // Wrappt die zentrierte Auth-Card in ihre Umgebung. Default = Fullscreen-
 // zentriert (Standalone-Auth-Page). Eine Apex-/Marketing-Chrome reicht über
@@ -80,20 +79,6 @@ export function AuthCard({ title, subtitle, children }: AuthCardProps): ReactNod
   return shell(card);
 }
 
-// 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.
@@ -106,3 +91,20 @@ export function parseUrlToken(paramName = "token"): string {
   if (typeof window === "undefined") return "";
   return new URLSearchParams(window.location.search).get(paramName) ?? "";
 }
+
+// Reads the magic-link token from `?<paramName>=` once on mount, then strips
+// that param from the URL via history.replaceState so the single-use token
+// doesn't linger in browser history / Referer (#774). An explicit `override`
+// (server-injected token) short-circuits both the URL read and the scrub.
+export function useUrlToken(override?: string, paramName = "token"): string {
+  const [token] = useState(() => override ?? parseUrlToken(paramName));
+  useEffect(() => {
+    if (override !== undefined) return;
+    if (typeof window === "undefined") return;
+    const url = new URL(window.location.href);
+    if (!url.searchParams.has(paramName)) return;
+    url.searchParams.delete(paramName);
+    window.history.replaceState(window.history.state, "", url.toString());
+  }, [override, paramName]);
+  return token;
+}

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

@@ -9,38 +9,159 @@
 // (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 { type ComponentType, type ReactNode, useEffect, useState } from "react";
 import { LoginScreen, type LoginScreenProps } from "./login-screen";
 import { SessionProvider, 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();
+// Generic — NOT auth-mfa's MfaVerifyScreenProps directly, so this feature
+// stays unaware of auth-mfa's concrete shape (same coupling direction as
+// login.write.ts's mfaStatusChecker callback on the server side). Apps
+// wire auth-mfa's MfaVerifyScreen in here via EmailPasswordClientOptions.
+export type MfaVerifyComponentProps = {
+  readonly challengeToken: string;
+  readonly onSuccess?: () => void;
+  readonly onCancel?: () => void;
+};
+
+// Same coupling reasoning as MfaVerifyComponentProps above — generic, not
+// auth-mfa's MfaSetupPreauthScreenProps directly. Apps wire auth-mfa's
+// MfaSetupPreauthScreen in here via EmailPasswordClientOptions.
+export type MfaSetupComponentProps = {
+  readonly preauthSetupToken: string;
+  readonly accountLabel: string;
+  readonly onSuccess?: () => void;
+  readonly onCancel?: () => void;
+};
+
+export type LoginRouteOptions = {
+  readonly loginScreen?: ComponentType<LoginScreenProps>;
+  readonly loginScreenProps?: LoginScreenProps;
+  readonly mfaVerifyScreen?: ComponentType<MfaVerifyComponentProps>;
+  readonly mfaSetupScreen?: ComponentType<MfaSetupComponentProps>;
+  /** Called once the session becomes authenticated. makeAuthGate ignores
+   *  this (it renders `children` on its own authenticated branch instead);
+   *  standalone routes — no parent gate, e.g. an anonymous apex/marketing
+   *  surface — use it to redirect. */
+  readonly onAuthenticated?: () => void;
+};
+
+// The one sanctioned way to render a login flow that correctly completes
+// an MFA challenge — makeAuthGate below is just this wrapped for the
+// `{ children }` gate shape. Also exported directly for apps that render
+// their own standalone login route outside any gate (createPublicSurface
+// apex pages stack providers, not gates — see auth-mount.tsx recipes).
+// Handing an app raw LoginScreen + telling it to hand-roll the challenge-
+// token swap itself is exactly how kumiko-framework#266's login-time MFA
+// step went missing in a real apex surface; this prevents the *most common*
+// version of that mistake. MFA still only actually works once a consumer
+// wires `mfaVerifyScreen` — omitting it is a silent no-MFA fallback, not
+// something this route can catch on its own (auth-mfa is a separate,
+// optional package).
+export function createLoginRoute(
+  opts: LoginRouteOptions = {},
+): ComponentType<Record<string, never>> {
+  const LoginComponent = opts.loginScreen ?? LoginScreen;
+  const MfaVerifyComponent = opts.mfaVerifyScreen;
+  const MfaSetupComponent = opts.mfaSetupScreen;
+
+  function LoginRoute(): ReactNode {
+    const { status, refresh } = useSession();
+    const { onAuthenticated } = opts;
+    // Pending challenge-token from LoginScreen's onMfaChallenge. Lives here
+    // (not in SessionState) because it's a UI-only transition — the server
+    // never considers this session authenticated until verify succeeds.
+    const [challengeToken, setChallengeToken] = useState<string | null>(null);
+    const [setupRequest, setSetupRequest] = useState<{
+      readonly preauthSetupToken: string;
+      readonly accountLabel: string;
+    } | null>(null);
+
+    useEffect(() => {
+      if (status === "authenticated") onAuthenticated?.();
+    }, [status]);
+
     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} />;
+    // A standalone mount (no parent gate, no onAuthenticated wired — e.g. an
+    // apex/marketing surface that just places <LoginRoute /> directly) has no
+    // way to navigate away once authenticated. Blanking the page there is a
+    // regression against the old raw LoginScreen (which had no session check
+    // at all); fall through to the form instead. A route WITH onAuthenticated
+    // still returns null and trusts the effect above to redirect.
+    if (status === "authenticated" && onAuthenticated) return null;
+    if (challengeToken !== null && MfaVerifyComponent) {
+      return (
+        <MfaVerifyComponent
+          challengeToken={challengeToken}
+          onSuccess={() => setChallengeToken(null)}
+          onCancel={() => setChallengeToken(null)}
+        />
+      );
+    }
+    // Pending preauthSetupToken from LoginScreen's onMfaSetupRequired. Same
+    // reasoning as challengeToken — a UI-only transition, not session state.
+    if (setupRequest !== null && MfaSetupComponent) {
+      return (
+        <MfaSetupComponent
+          preauthSetupToken={setupRequest.preauthSetupToken}
+          accountLabel={setupRequest.accountLabel}
+          onSuccess={() => {
+            // MfaSetupPreauthScreen has no session to refresh itself with
+            // (it runs pre-auth) — the gate owns the session, so it refreshes.
+            // Keep setupRequest until refresh settles: clearing first would
+            // dump the user back on the login form with no retry if refresh
+            // rejects (cookie+JWT already minted server-side).
+            void refresh().then(
+              () => setSetupRequest(null),
+              () => {
+                // leave setupRequest set so the user can cancel/retry
+              },
+            );
+          }}
+          onCancel={() => setSetupRequest(null)}
+        />
+      );
     }
-    return <>{children}</>;
+    return (
+      <LoginComponent
+        {...opts.loginScreenProps}
+        onMfaChallenge={
+          MfaVerifyComponent ? setChallengeToken : opts.loginScreenProps?.onMfaChallenge
+        }
+        onMfaSetupRequired={
+          MfaSetupComponent
+            ? (preauthSetupToken, accountLabel) =>
+                setSetupRequest({ preauthSetupToken, accountLabel })
+            : opts.loginScreenProps?.onMfaSetupRequired
+        }
+      />
+    );
+  }
+  return LoginRoute;
+}
+
+export function makeAuthGate(opts: LoginRouteOptions = {}): ComponentType<{
+  children: ReactNode;
+}> {
+  const LoginRoute = createLoginRoute(opts);
+  function AuthGate({ children }: { readonly children: ReactNode }): ReactNode {
+    const { status } = useSession();
+    if (status === "authenticated") return <>{children}</>;
+    return <LoginRoute />;
   }
   return AuthGate;
 }
 
-/** SessionProvider + AuthGate als ein Gate — damit öffentliche Gates davor
- *  (z.B. /rechner) den Session-Bootstrap nicht mounten. createKumikoApp
- *  stackt providers außerhalb aller gates; SessionProvider darf deshalb
- *  kein provider mehr sein. */
-export function makeSessionAuthGate(
-  LoginComponent: ComponentType<LoginScreenProps> = LoginScreen,
-  loginProps?: LoginScreenProps,
-): ComponentType<{ children: ReactNode }> {
-  const AuthGate = makeAuthGate(LoginComponent, loginProps);
+// SessionProvider + AuthGate as one gate, so a public gate in front (e.g.
+// /calculator) doesn't mount the session bootstrap — createKumikoApp stacks
+// providers outside all gates, so SessionProvider can't be a provider anymore.
+export function makeSessionAuthGate(opts: LoginRouteOptions = {}): ComponentType<{
+  children: ReactNode;
+}> {
+  const AuthGate = makeAuthGate(opts);
   function SessionAuthGate({ children }: { readonly children: ReactNode }): ReactNode {
     return (
       <SessionProvider>

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

@@ -8,7 +8,11 @@
 import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
 import type { ComponentType, ReactNode } from "react";
 import { defaultTranslations, mergeTranslations } from "../i18n";
-import { makeSessionAuthGate } from "./auth-gate";
+import {
+  type MfaSetupComponentProps,
+  type MfaVerifyComponentProps,
+  makeSessionAuthGate,
+} from "./auth-gate";
 import type { LoginScreenProps } from "./login-screen";
 
 export type EmailPasswordClientOptions = {
@@ -17,6 +21,17 @@ export type EmailPasswordClientOptions = {
    *  eine eigene Komponente mit derselben Signatur reichen. */
   readonly loginScreen?: ComponentType<LoginScreenProps>;
   readonly loginScreenProps?: LoginScreenProps;
+  /** auth-mfa's MfaVerifyScreen, wired in from the app so this feature
+   *  stays unaware of auth-mfa's concrete shape. When LoginScreen's
+   *  onMfaChallenge fires, the gate swaps to this component instead of
+   *  requiring the app to own that state itself. Apps not mounting
+   *  auth-mfa simply don't pass this — LoginScreen's built-in fallback
+   *  error covers that case. */
+  readonly mfaVerifyScreen?: ComponentType<MfaVerifyComponentProps>;
+  /** auth-mfa's MfaSetupPreauthScreen, wired in from the app the same way
+   *  as mfaVerifyScreen above. Apps not mounting auth-mfa simply don't
+   *  pass this. */
+  readonly mfaSetupScreen?: ComponentType<MfaSetupComponentProps>;
   /** 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
@@ -41,7 +56,14 @@ export function emailPasswordClient(
   return {
     name: "auth-email-password",
     providers: [],
-    gates: [makeSessionAuthGate(options.loginScreen, options.loginScreenProps)],
+    gates: [
+      makeSessionAuthGate({
+        loginScreen: options.loginScreen,
+        loginScreenProps: options.loginScreenProps,
+        mfaVerifyScreen: options.mfaVerifyScreen,
+        mfaSetupScreen: options.mfaSetupScreen,
+      }),
+    ],
     translations,
   };
 }

package/src/auth-email-password/web/confirm-account-unlock-screen.tsx

@@ -0,0 +1,95 @@
+// @runtime client
+// ConfirmAccountUnlockScreen — reads `?token=...` from the URL, auto-posts
+// it to /api/auth/confirm-account-unlock on mount, shows success/error.
+// Idempotent server-side (clearLockoutState is a no-op when already
+// unlocked), so no re-submit risk. Mirrors VerifyEmailScreen 1:1.
+//
+// useEffect with empty deps + a once-guard so React Strict Mode's double
+// useEffect dispatch in dev fires the confirm call only once.
+
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useEffect, useRef, useState } from "react";
+import { confirmAccountUnlock } from "./auth-client";
+import { AuthCard, useUrlToken } from "./auth-form-primitives";
+
+export type ConfirmAccountUnlockScreenProps = {
+  readonly title?: string;
+  /** Override for the token from the URL. Default: parsed from `?token=...`. */
+  readonly token?: string;
+  /** href for the "go to sign in" link. Default "/login". */
+  readonly loginHref?: string;
+};
+
+type Status = "verifying" | "success" | "error" | "missing-token";
+
+export function ConfirmAccountUnlockScreen({
+  title,
+  token: tokenProp,
+  loginHref = "/login",
+}: ConfirmAccountUnlockScreenProps): ReactNode {
+  const t = useTranslation();
+  const { Link } = usePrimitives();
+  const token = useUrlToken(tokenProp);
+  const [status, setStatus] = useState<Status>(token === "" ? "missing-token" : "verifying");
+  const startedRef = useRef(false);
+
+  useEffect(() => {
+    if (status !== "verifying") return;
+    if (startedRef.current) return;
+    startedRef.current = true;
+    void (async () => {
+      const res = await confirmAccountUnlock(token);
+      setStatus(res.ok ? "success" : "error");
+    })();
+  }, [status, token]);
+
+  if (status === "missing-token") {
+    return (
+      <AuthCard title={title ?? t("auth.unlockAccount.errorTitle")}>
+        <div className="p-6 pt-0 flex flex-col gap-4">
+          <p className="text-sm text-muted-foreground">{t("auth.unlockAccount.missingToken")}</p>
+          <Link href={loginHref} variant="muted">
+            {t("auth.unlockAccount.goToLogin")}
+          </Link>
+        </div>
+      </AuthCard>
+    );
+  }
+
+  if (status === "verifying") {
+    return (
+      <AuthCard>
+        <div className="p-6">
+          <p className="text-sm text-muted-foreground" role="status">
+            {t("auth.unlockAccount.verifying")}
+          </p>
+        </div>
+      </AuthCard>
+    );
+  }
+
+  if (status === "success") {
+    return (
+      <AuthCard title={title ?? t("auth.unlockAccount.successTitle")}>
+        <div className="p-6 pt-0 flex flex-col gap-4">
+          <p className="text-sm text-muted-foreground">{t("auth.unlockAccount.successBody")}</p>
+          <Link href={loginHref} variant="button">
+            {t("auth.unlockAccount.goToLogin")}
+          </Link>
+        </div>
+      </AuthCard>
+    );
+  }
+
+  // status === "error"
+  return (
+    <AuthCard title={title ?? t("auth.unlockAccount.errorTitle")}>
+      <div className="p-6 pt-0 flex flex-col gap-4">
+        <p className="text-sm text-muted-foreground">{t("auth.unlockAccount.errorBody")}</p>
+        <Link href={loginHref} variant="muted">
+          {t("auth.unlockAccount.goToLogin")}
+        </Link>
+      </div>
+    </AuthCard>
+  );
+}

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

@@ -12,7 +12,7 @@
 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";
+import { AuthCard } from "./auth-form-primitives";
 
 export type ForgotPasswordScreenProps = {
   readonly title?: string;
@@ -28,7 +28,7 @@ export function ForgotPasswordScreen({
   loginHref = "/login",
 }: ForgotPasswordScreenProps): ReactNode {
   const t = useTranslation();
-  const { Form, Field, Input, Button, Banner } = usePrimitives();
+  const { Form, Field, Input, Button, Banner, Link } = usePrimitives();
   const [email, setEmail] = useState("");
   const [submitting, setSubmitting] = useState(false);
   const [done, setDone] = useState(false);
@@ -77,9 +77,9 @@ export function ForgotPasswordScreen({
             <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}>
+          <Link href={loginHref} variant="muted">
             {t("auth.forgotPassword.backToLogin")}
-          </a>
+          </Link>
         </div>
       ) : (
         <div className="p-6 pt-0 flex flex-col gap-4">
@@ -101,9 +101,9 @@ export function ForgotPasswordScreen({
               {submitting ? t("auth.forgotPassword.submitting") : t("auth.forgotPassword.submit")}
             </Button>
           </Form>
-          <a href={loginHref} className={`${authMutedLinkClass} self-center`}>
+          <Link href={loginHref} variant="muted" className="self-center">
             {t("auth.forgotPassword.backToLogin")}
-          </a>
+          </Link>
         </div>
       )}
     </AuthCard>