@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/auth-mfa/web/index.ts

@@ -0,0 +1,27 @@
+// @runtime client
+// Public exports für die Browser-Seite des auth-mfa Features. Sub-Path-
+// Export `@cosmicdrift/kumiko-bundled-features/auth-mfa/web` — Server-Seite
+// (defineFeature) bleibt frei von React-/DOM-Deps, siehe auth-email-
+// password/web/index.ts für die selbe Trennung.
+
+export type { AuthMfaClientFeature, AuthMfaClientOptions } from "./client-plugin";
+export { authMfaClient } from "./client-plugin";
+export { defaultTranslations, mergeTranslations } from "./i18n";
+export type {
+  MfaSetupPreauthStart,
+  MfaSetupPreauthStartResult,
+  MfaVerifyResult,
+} from "./mfa-client";
+export { confirmMfaSetupPreauth, startMfaSetupPreauth, verifyMfaChallenge } from "./mfa-client";
+export type { MfaDisableDialogProps } from "./mfa-disable-dialog";
+export { MfaDisableDialog } from "./mfa-disable-dialog";
+export type { MfaEnableScreenProps } from "./mfa-enable-screen";
+export { MfaEnableScreen } from "./mfa-enable-screen";
+export type { MfaRecoveryCodesRevealProps } from "./mfa-recovery-codes-reveal";
+export { MfaRecoveryCodesReveal } from "./mfa-recovery-codes-reveal";
+export type { MfaRegenerateRecoveryDialogProps } from "./mfa-regenerate-recovery-dialog";
+export { MfaRegenerateRecoveryDialog } from "./mfa-regenerate-recovery-dialog";
+export type { MfaSetupPreauthScreenProps } from "./mfa-setup-preauth-screen";
+export { MfaSetupPreauthScreen } from "./mfa-setup-preauth-screen";
+export type { MfaVerifyScreenProps } from "./mfa-verify-screen";
+export { MfaVerifyScreen } from "./mfa-verify-screen";

package/src/auth-mfa/web/mfa-client.ts

@@ -0,0 +1,184 @@
+// @runtime client
+// Browser-Seite von POST /api/auth/mfa/verify — completes the two-step
+// login LoginScreen started when the server responded mfaRequired. Same
+// fetch/CSRF pattern as auth-email-password's login() (pre-session, no
+// csrfHeader() — there's no session yet to protect). Response shape is
+// byte-identical to /auth/login's ({isSuccess, token, user} | {isSuccess:
+// false, error}) since auth-routes.ts mints via the same
+// mintSessionAndRespond() for both routes.
+
+// kumiko-lint-ignore cross-feature-import client-only types, the feature's server barrel has no web/ re-export
+import type { LoginFailure, LoginResponse } from "../../auth-email-password/web";
+
+export type MfaVerifyResult =
+  | { readonly kind: "success"; readonly data: LoginResponse }
+  | { readonly kind: "failure"; readonly error: LoginFailure };
+
+export async function verifyMfaChallenge(
+  challengeToken: string,
+  code: string,
+): Promise<MfaVerifyResult> {
+  const res = await fetch("/api/auth/mfa/verify", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ challengeToken, code }),
+  });
+  if (res.status === 429) {
+    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"];
+    error?:
+      | {
+          code?: string;
+          message?: string;
+          details?: { reason?: string; retryAfterSeconds?: number };
+        }
+      | string;
+  };
+  if (body.isSuccess === true && body.token !== undefined && body.user !== undefined) {
+    return { kind: "success", data: { token: body.token, user: body.user } };
+  }
+  const err = body.error;
+  if (typeof err === "string") {
+    return { kind: "failure", error: { reason: err } };
+  }
+  const reason = err?.details?.reason ?? err?.code ?? "mfa_verify_failed";
+  const retry = err?.details?.retryAfterSeconds;
+  return {
+    kind: "failure",
+    error: {
+      reason,
+      ...(err?.message !== undefined && { message: err.message }),
+      ...(retry !== undefined && { retryAfterSeconds: retry }),
+    },
+  };
+}
+
+export type MfaSetupPreauthStart = {
+  readonly setupToken: string;
+  readonly otpauthUri: string;
+  readonly recoveryCodes: readonly string[];
+};
+
+export type MfaSetupPreauthStartResult =
+  | { readonly kind: "success"; readonly data: MfaSetupPreauthStart }
+  | { readonly kind: "failure"; readonly error: LoginFailure };
+
+// Browser-Seite von POST /api/auth/mfa/preauth-enable-start — lets a user
+// blocked at login by MFA enforcement generate a TOTP secret/QR without a
+// session, using the preauthSetupToken login()'s mfa-setup-required result
+// carries. No JWT/cookie here (see auth-routes.ts's route comment) — the
+// response's setupToken is consumed by confirmMfaSetupPreauth below.
+export async function startMfaSetupPreauth(
+  preauthSetupToken: string,
+  accountLabel: string,
+): Promise<MfaSetupPreauthStartResult> {
+  const res = await fetch("/api/auth/mfa/preauth-enable-start", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ preauthSetupToken, accountLabel }),
+  });
+  if (res.status === 429) {
+    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;
+    setupToken?: string;
+    otpauthUri?: string;
+    recoveryCodes?: readonly string[];
+    error?:
+      | {
+          code?: string;
+          message?: string;
+          details?: { reason?: string; retryAfterSeconds?: number };
+        }
+      | string;
+  };
+  if (
+    body.isSuccess === true &&
+    body.setupToken !== undefined &&
+    body.otpauthUri !== undefined &&
+    body.recoveryCodes !== undefined
+  ) {
+    return {
+      kind: "success",
+      data: {
+        setupToken: body.setupToken,
+        otpauthUri: body.otpauthUri,
+        recoveryCodes: body.recoveryCodes,
+      },
+    };
+  }
+  const err = body.error;
+  if (typeof err === "string") {
+    return { kind: "failure", error: { reason: err } };
+  }
+  const reason = err?.details?.reason ?? err?.code ?? "setup_failed";
+  const retry = err?.details?.retryAfterSeconds;
+  return {
+    kind: "failure",
+    error: {
+      reason,
+      ...(err?.message !== undefined && { message: err.message }),
+      ...(retry !== undefined && { retryAfterSeconds: retry }),
+    },
+  };
+}
+
+// Browser-Seite von POST /api/auth/mfa/preauth-confirm — completes both
+// the enrollment startMfaSetupPreauth began and the login mfa-setup-
+// required block. Response shape mirrors /auth/mfa/verify's (mints via
+// the same mintSessionAndRespond()), same as verifyMfaChallenge above —
+// kept as its own function rather than a shared helper so this file's
+// two already-tested request shapes stay independently editable.
+export async function confirmMfaSetupPreauth(
+  setupToken: string,
+  code: string,
+): Promise<MfaVerifyResult> {
+  const res = await fetch("/api/auth/mfa/preauth-confirm", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ setupToken, code }),
+  });
+  if (res.status === 429) {
+    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"];
+    error?:
+      | {
+          code?: string;
+          message?: string;
+          details?: { reason?: string; retryAfterSeconds?: number };
+        }
+      | string;
+  };
+  if (body.isSuccess === true && body.token !== undefined && body.user !== undefined) {
+    return { kind: "success", data: { token: body.token, user: body.user } };
+  }
+  const err = body.error;
+  if (typeof err === "string") {
+    return { kind: "failure", error: { reason: err } };
+  }
+  const reason = err?.details?.reason ?? err?.code ?? "mfa_setup_confirm_failed";
+  const retry = err?.details?.retryAfterSeconds;
+  return {
+    kind: "failure",
+    error: {
+      reason,
+      ...(err?.message !== undefined && { message: err.message }),
+      ...(retry !== undefined && { retryAfterSeconds: retry }),
+    },
+  };
+}

package/src/auth-mfa/web/mfa-disable-dialog.tsx

@@ -0,0 +1,69 @@
+// @runtime client
+// MfaDisableDialog — confirm-with-code before turning MFA off. Uses the
+// generic Dialog primitive (unlike MfaEnableScreen/MfaRegenerateRecovery-
+// Dialog): disable is single-step, no state to preserve after confirm, so
+// it doesn't hit the "Dialog always closes after onConfirm" problem that
+// ruled Dialog out for the multi-step enable/regenerate flows. Error
+// reporting still has to go through the parent (onError) rather than an
+// inline Banner, because Dialog closes in a `finally` regardless of
+// whether onConfirm's write succeeded — see profile-screen.tsx's
+// delete-account dialog for the same convention (StatusBanner rendered
+// by the caller, not the dialog).
+
+import { useDispatcher, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+import { AuthMfaHandlers } from "../constants";
+
+export type MfaDisableDialogProps = {
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+  readonly onDisabled: () => void;
+  readonly onError: (i18nKey: string) => void;
+};
+
+export function MfaDisableDialog({
+  open,
+  onOpenChange,
+  onDisabled,
+  onError,
+}: MfaDisableDialogProps): ReactNode {
+  const t = useTranslation();
+  const { Dialog, Field, Input } = usePrimitives();
+  const dispatcher = useDispatcher();
+  const [code, setCode] = useState("");
+
+  const confirm = async (): Promise<void> => {
+    const res = await dispatcher.write<{ disabled: boolean }>(AuthMfaHandlers.disable, { code });
+    setCode("");
+    if (!res.isSuccess) {
+      onError(res.error.i18nKey);
+      return;
+    }
+    onDisabled();
+  };
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={onOpenChange}
+      variant="danger"
+      title={t("auth.mfa.disable.title")}
+      description={t("auth.mfa.disable.description")}
+      confirmLabel={t("auth.mfa.disable.confirm")}
+      cancelLabel={t("auth.mfa.disable.cancel")}
+      onConfirm={confirm}
+      testId="mfa-disable-dialog"
+    >
+      <Field id="mfa-disable-code" label={t("auth.mfa.disable.code")} required>
+        <Input
+          kind="text"
+          id="mfa-disable-code"
+          name="mfa-disable-code"
+          value={code}
+          onChange={setCode}
+          autoComplete="one-time-code"
+        />
+      </Field>
+    </Dialog>
+  );
+}

package/src/auth-mfa/web/mfa-enable-screen.tsx

@@ -0,0 +1,228 @@
+// @runtime client
+// MfaEnableScreen — logged-in self-service TOTP-Enrollment. Kein Dialog:
+// DefaultDialog schließt nach JEDEM onConfirm (siehe renderer-web/src/
+// primitives/dialog.tsx — onOpenChange(false) im finally-Block), das passt
+// nicht zu einem Mehrschritt-Flow (Secret zeigen → Recovery-Codes zeigen →
+// Code bestätigen). Folgt stattdessen pat-tokens-screen.tsx's embedded-
+// Screen-Konvention: Feature registriert das dormant via r.screen, App
+// platziert es via r.nav.
+
+import { useDispatcher, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { FormScreenShell } from "@cosmicdrift/kumiko-renderer-web";
+// qrcode's package.json#browser remap avoids Node-only deps (yargs/pngjs)
+// for bundlers that honor it — Metro doesn't, hence the explicit subpath.
+// @types/qrcode only covers the main "qrcode" entry, not this subpath, and
+// TypeScript can't auto-discover an ambient .d.ts sibling from inside a
+// node_modules package (consuming apps typecheck this raw .tsx source).
+// Apps mounting MfaEnableScreen need their own local ambient shim — see
+// qrcode-browser.d.ts in this directory for the declaration to copy.
+import QRCode from "qrcode/lib/browser";
+import { type ReactNode, useState } from "react";
+// kumiko-lint-ignore cross-feature-import client-only hook, the feature's server barrel has no web/ re-export
+import { useSession } from "../../auth-email-password/web";
+import { AuthMfaHandlers } from "../constants";
+
+type EnableStartResponse = {
+  readonly setupToken: string;
+  readonly otpauthUri: string;
+  readonly recoveryCodes: readonly string[];
+};
+
+type SetupState = {
+  readonly setupToken: string;
+  readonly secretParam: string;
+  readonly recoveryCodes: readonly string[];
+  readonly qrSvg: string;
+};
+
+// otpauth:// URIs put the secret in the query string — extract it for the
+// manual-entry fallback (authenticator apps without a camera / desktop use).
+function extractSecret(otpauthUri: string): string {
+  const query = otpauthUri.split("?")[1] ?? "";
+  return new URLSearchParams(query).get("secret") ?? "";
+}
+
+export type MfaEnableScreenProps = {
+  readonly embedded?: boolean;
+  // Fired once enable-confirm succeeds — MfaEnableScreen has no query of its
+  // own to invalidate, so a host screen composing it alongside other MFA
+  // state (e.g. a status query gating which section renders) needs this to
+  // know when to refetch/swap views instead of leaving the success banner
+  // as a dead end.
+  readonly onEnabled?: () => void;
+};
+
+export function MfaEnableScreen({
+  embedded = false,
+  onEnabled,
+}: MfaEnableScreenProps = {}): ReactNode {
+  const t = useTranslation();
+  const { Button, Banner, Field, Input, Section, Heading } = usePrimitives();
+  const dispatcher = useDispatcher();
+  const session = useSession();
+
+  const [setup, setSetup] = useState<SetupState | null>(null);
+  const [acknowledged, setAcknowledged] = useState(false);
+  const [code, setCode] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [enabled, setEnabled] = useState(false);
+
+  const startSetup = async (): Promise<void> => {
+    setBusy(true);
+    setError(null);
+    try {
+      const res = await dispatcher.write<EnableStartResponse>(AuthMfaHandlers.enableStart, {
+        accountLabel: session.user?.email ?? "",
+      });
+      if (!res.isSuccess) {
+        setError(res.error.i18nKey);
+        return;
+      }
+      // errorCorrectionLevel "H" (~30% redundancy) — more resilient to
+      // camera/lighting issues than the default, no downside for a code
+      // this short-lived.
+      const qrSvg = await QRCode.toString(res.data.otpauthUri, {
+        type: "svg",
+        errorCorrectionLevel: "H",
+      });
+      setSetup({
+        setupToken: res.data.setupToken,
+        secretParam: extractSecret(res.data.otpauthUri),
+        recoveryCodes: res.data.recoveryCodes,
+        qrSvg,
+      });
+      setAcknowledged(false);
+      setCode("");
+    } catch {
+      setError("auth.mfa.errors.setupFailed");
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const confirmSetup = async (): Promise<void> => {
+    if (!setup) return;
+    setBusy(true);
+    setError(null);
+    try {
+      const res = await dispatcher.write(AuthMfaHandlers.enableConfirm, {
+        setupToken: setup.setupToken,
+        code,
+      });
+      if (!res.isSuccess) {
+        setError(res.error.i18nKey);
+        return;
+      }
+      setEnabled(true);
+      setSetup(null);
+      onEnabled?.();
+    } catch {
+      setError("auth.mfa.errors.setupFailed");
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const content = (
+    <div className="flex flex-col gap-6">
+      <Heading>{t("auth.mfa.enable.title")}</Heading>
+
+      {enabled && <Banner variant="info">{t("auth.mfa.enable.success")}</Banner>}
+      {error !== null && <Banner variant="error">{t(error)}</Banner>}
+
+      {!setup && !enabled && (
+        <Section
+          testId="mfa-enable-intro"
+          actions={
+            <Button
+              variant="primary"
+              onClick={() => void startSetup()}
+              loading={busy}
+              disabled={busy}
+            >
+              {t("auth.mfa.enable.start")}
+            </Button>
+          }
+        >
+          <span className="text-sm text-muted-foreground">{t("auth.mfa.enable.intro")}</span>
+        </Section>
+      )}
+
+      {setup && (
+        <Section
+          testId="mfa-enable-setup"
+          actions={
+            <>
+              <Button variant="secondary" onClick={() => setSetup(null)} disabled={busy}>
+                {t("auth.mfa.enable.cancel")}
+              </Button>
+              <Button
+                variant="primary"
+                onClick={() => void confirmSetup()}
+                loading={busy}
+                disabled={busy || !acknowledged || code.length !== 6}
+              >
+                {t("auth.mfa.enable.confirm")}
+              </Button>
+            </>
+          }
+        >
+          <div className="flex flex-col items-center gap-2 text-center">
+            <span className="text-sm font-semibold">{t("auth.mfa.enable.scanTitle")}</span>
+            {/* qrcode's own SVG string output, not user input — safe to inline */}
+            <div
+              className="h-40 w-40"
+              // biome-ignore lint/security/noDangerouslySetInnerHtml: qrcode-generated SVG, no user input
+              dangerouslySetInnerHTML={{ __html: setup.qrSvg }}
+            />
+            <span className="text-xs text-muted-foreground">
+              {t("auth.mfa.enable.manualEntry")}
+            </span>
+            <code className="inline-block break-all rounded bg-muted px-3 py-2 font-mono text-sm">
+              {setup.secretParam}
+            </code>
+          </div>
+
+          <div className="flex flex-col gap-2">
+            <span className="text-sm font-semibold">{t("auth.mfa.enable.recoveryTitle")}</span>
+            <span className="text-xs text-muted-foreground">
+              {t("auth.mfa.enable.recoveryHint")}
+            </span>
+            <code className="block whitespace-pre-wrap break-all rounded bg-muted px-3 py-2 font-mono text-sm">
+              {setup.recoveryCodes.join("\n")}
+            </code>
+            <Field id="mfa-enable-ack" label={t("auth.mfa.enable.acknowledge")}>
+              <Input
+                kind="boolean"
+                id="mfa-enable-ack"
+                name="mfa-enable-ack"
+                value={acknowledged}
+                onChange={setAcknowledged}
+              />
+            </Field>
+          </div>
+
+          <Field id="mfa-enable-code" label={t("auth.mfa.enable.code")} required>
+            <Input
+              kind="text"
+              id="mfa-enable-code"
+              name="mfa-enable-code"
+              value={code}
+              onChange={setCode}
+              disabled={busy || !acknowledged}
+              autoComplete="one-time-code"
+            />
+          </Field>
+        </Section>
+      )}
+    </div>
+  );
+
+  if (embedded) return content;
+  return (
+    <FormScreenShell testId="mfa-enable-screen" maxWidth="3xl">
+      {content}
+    </FormScreenShell>
+  );
+}

package/src/auth-mfa/web/mfa-recovery-codes-reveal.tsx

@@ -0,0 +1,53 @@
+// @runtime client
+// MfaRecoveryCodesReveal — one-time display of a fresh recovery-code set,
+// with an acknowledge-then-dismiss gate (same UX as the codes block in
+// MfaEnableScreen). Standalone so MfaRegenerateRecoveryDialog's caller can
+// render it after the dialog closes — the codes only exist in memory for
+// this one render, never persisted anywhere the app could show them again.
+
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+
+export type MfaRecoveryCodesRevealProps = {
+  readonly codes: readonly string[];
+  readonly onDismiss: () => void;
+};
+
+export function MfaRecoveryCodesReveal({
+  codes,
+  onDismiss,
+}: MfaRecoveryCodesRevealProps): ReactNode {
+  const t = useTranslation();
+  const { Button, Field, Input, Section } = usePrimitives();
+  const [acknowledged, setAcknowledged] = useState(false);
+
+  return (
+    <Section
+      testId="mfa-regenerate-reveal"
+      actions={
+        <Button variant="primary" onClick={onDismiss} disabled={!acknowledged}>
+          {t("auth.mfa.regenerate.done")}
+        </Button>
+      }
+    >
+      <div className="flex flex-col items-center gap-2 text-center">
+        <span className="text-sm font-semibold">{t("auth.mfa.regenerate.newCodesTitle")}</span>
+        <span className="text-xs text-muted-foreground">
+          {t("auth.mfa.regenerate.newCodesHint")}
+        </span>
+        <code className="inline-block whitespace-pre-wrap break-all rounded bg-muted px-3 py-2 font-mono text-sm">
+          {codes.join("\n")}
+        </code>
+      </div>
+      <Field id="mfa-regenerate-ack" label={t("auth.mfa.regenerate.acknowledge")}>
+        <Input
+          kind="boolean"
+          id="mfa-regenerate-ack"
+          name="mfa-regenerate-ack"
+          value={acknowledged}
+          onChange={setAcknowledged}
+        />
+      </Field>
+    </Section>
+  );
+}

package/src/auth-mfa/web/mfa-regenerate-recovery-dialog.tsx

@@ -0,0 +1,68 @@
+// @runtime client
+// MfaRegenerateRecoveryDialog — confirm-with-code, then the caller reveals
+// the new codes. The reveal itself can't live inside this Dialog: Dialog
+// closes in a `finally` right after onConfirm resolves (see profile-screen.
+// tsx's delete-account dialog for the same constraint), so there's no way
+// to keep it open to show the result. onRegenerated hands the new codes to
+// the caller, which is expected to render them via MfaRecoveryCodesReveal
+// (or equivalent) once the dialog has closed.
+
+import { useDispatcher, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+import { AuthMfaHandlers } from "../constants";
+
+export type MfaRegenerateRecoveryDialogProps = {
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+  readonly onRegenerated: (codes: readonly string[]) => void;
+  readonly onError: (i18nKey: string) => void;
+};
+
+export function MfaRegenerateRecoveryDialog({
+  open,
+  onOpenChange,
+  onRegenerated,
+  onError,
+}: MfaRegenerateRecoveryDialogProps): ReactNode {
+  const t = useTranslation();
+  const { Dialog, Field, Input } = usePrimitives();
+  const dispatcher = useDispatcher();
+  const [code, setCode] = useState("");
+
+  const confirm = async (): Promise<void> => {
+    const res = await dispatcher.write<{ recoveryCodes: readonly string[] }>(
+      AuthMfaHandlers.regenerateRecovery,
+      { code },
+    );
+    setCode("");
+    if (!res.isSuccess) {
+      onError(res.error.i18nKey);
+      return;
+    }
+    onRegenerated(res.data.recoveryCodes);
+  };
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={onOpenChange}
+      title={t("auth.mfa.regenerate.title")}
+      description={t("auth.mfa.regenerate.description")}
+      confirmLabel={t("auth.mfa.regenerate.confirm")}
+      cancelLabel={t("auth.mfa.regenerate.cancel")}
+      onConfirm={confirm}
+      testId="mfa-regenerate-recovery-dialog"
+    >
+      <Field id="mfa-regenerate-code" label={t("auth.mfa.regenerate.code")} required>
+        <Input
+          kind="text"
+          id="mfa-regenerate-code"
+          name="mfa-regenerate-code"
+          value={code}
+          onChange={setCode}
+          autoComplete="one-time-code"
+        />
+      </Field>
+    </Dialog>
+  );
+}