@podosoft/podokit 0.8.0 → 0.10.0

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(app)/admin/settings/+page.server.ts

@@ -22,5 +22,14 @@ export const load: PageServerLoad = async ({ locals, fetch }) => {
   } catch {
     /* leave null — the page shows the DB-config sections as unavailable */
   }
-  return { authConfig };
+  // The require-two-factor policy lives in the feature-flag store (not the typed
+  // Capabilities), so read it from its own endpoint for the Settings toggle.
+  let require2fa = false;
+  try {
+    const res = await fetch("/api/account/require-2fa");
+    if (res.ok) require2fa = ((await res.json()) as { require2fa?: boolean }).require2fa === true;
+  } catch {
+    /* default off */
+  }
+  return { authConfig, require2fa };
 };

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(app)/admin/settings/+page.svelte

@@ -7,8 +7,10 @@
   import { Button } from "$lib/components/ui/button";
   import * as Card from "$lib/components/ui/card";
   import * as Dialog from "$lib/components/ui/dialog";
+  import * as Select from "$lib/components/ui/select";
   import * as Tabs from "$lib/components/ui/tabs";
   import GeneralSettings from "./general-settings.svelte";
+  import AppearanceCard from "$lib/components/settings/appearance-card.svelte";
   import { moduleSettingsSections } from "$lib/admin/registry.svelte";
   import { toast } from "svelte-sonner";
   import { api } from "$lib/api";
@@ -16,12 +18,15 @@
   import type { Capabilities } from "@podosoft/podokit-api-client";
   import type { AuthConfigView, SocialProviderView } from "./+page.server";
 
-  let { data }: { data: { capabilities: Capabilities; authConfig: AuthConfigView | null } } = $props();
+  let { data }: { data: { capabilities: Capabilities; authConfig: AuthConfigView | null; require2fa: boolean } } = $props();
   const i18n = getI18n();
   const caps = $derived(data.capabilities);
   const ac = $derived(data.authConfig);
 
   type EditableFlag = "twoFactor" | "magicLink" | "emailOtp" | "username" | "multiSession" | "phoneNumber" | "apiKey" | "passkey" | "organization" | "oidcProvider";
+  // require2fa is a policy flag stored alongside the feature flags but not part of
+  // the typed Capabilities, so it is toggled but never read from `caps`.
+  type ToggleFlag = EditableFlag | "require2fa";
   type ServerKey = "requireEmailVerification" | "hibp" | "allowDelete" | "auditLog";
 
   // Every card renders from this one shape, so they share size and structure: a
@@ -54,7 +59,7 @@
     return ok;
   }
   // Feature flags live in a separate store (app_setting) with their own endpoint.
-  async function toggleFlag(flag: EditableFlag, next: boolean): Promise<void> {
+  async function toggleFlag(flag: ToggleFlag, next: boolean): Promise<void> {
     saving = true;
     try {
       await api.put("/account/settings", { [flag]: next });
@@ -174,6 +179,14 @@
   ]);
   const security = $derived<Item[]>([
     flagCard("twoFactor", i18n.t.settings.twoFactor, i18n.t.settings.twoFactorDesc),
+    {
+      key: "flag-require2fa",
+      name: i18n.t.settings.require2fa,
+      desc: i18n.t.settings.require2faDesc,
+      status: { on: data.require2fa, label: data.require2fa ? i18n.t.settings.enabled : i18n.t.settings.disabled },
+      // Only meaningful when 2FA itself is on; disabled otherwise.
+      toggle: { checked: data.require2fa, disabled: saving || !caps.twoFactor, onChange: (v) => toggleFlag("require2fa", v) },
+    },
     serverCard("hibp", i18n.t.settings.breachCheck, i18n.t.settings.breachCheckDesc, caps.passwordBreachCheck),
     serverCard("allowDelete", i18n.t.settings.accountDeletion, i18n.t.settings.accountDeletionDesc, caps.deleteAccount),
     serverCard("auditLog", i18n.t.settings.auditLog, i18n.t.settings.auditLogDesc, caps.auditLog),
@@ -226,6 +239,7 @@
   <Tabs.Root value="general">
     <Tabs.List>
       <Tabs.Trigger value="general">{i18n.t.general.tab}</Tabs.Trigger>
+      <Tabs.Trigger value="appearance">{i18n.t.general.appearanceTitle}</Tabs.Trigger>
       <Tabs.Trigger value="auth">{i18n.t.settings.tab}</Tabs.Trigger>
       {#each moduleSettingsSections as s (s.value)}
         <Tabs.Trigger value={s.value}>{s.label(i18n.t)}</Tabs.Trigger>
@@ -236,6 +250,10 @@
       <GeneralSettings />
     </Tabs.Content>
 
+    <Tabs.Content value="appearance" class="mt-6">
+      <AppearanceCard />
+    </Tabs.Content>
+
     <Tabs.Content value="auth" class="mt-6 flex flex-col gap-6">
       {#each sections as section (section.title)}
         <section class="flex flex-col gap-3">
@@ -295,15 +313,16 @@
         {#if socialForm.adding}
           <div class="flex flex-col gap-1">
             <Label for="social-provider">{i18n.t.settings.provider}</Label>
-            <select
-              id="social-provider"
-              bind:value={socialForm.id}
-              class="border-input bg-background ring-offset-background focus-visible:ring-ring h-9 rounded-md border px-3 text-sm focus-visible:ring-2 focus-visible:outline-none"
-            >
-              {#each addable as p (p.id)}
-                <option value={p.id}>{p.label}</option>
-              {/each}
-            </select>
+            <Select.Root type="single" bind:value={socialForm.id}>
+              <Select.Trigger id="social-provider" class="w-full">
+                {addable.find((p) => p.id === socialForm.id)?.label ?? i18n.t.settings.provider}
+              </Select.Trigger>
+              <Select.Content>
+                {#each addable as p (p.id)}
+                  <Select.Item value={p.id} label={p.label}>{p.label}</Select.Item>
+                {/each}
+              </Select.Content>
+            </Select.Root>
           </div>
         {/if}
         <label class="flex items-center justify-between gap-3 text-sm font-medium">{i18n.t.settings.smtpEnabled}<Switch aria-label={i18n.t.settings.smtpEnabled} bind:checked={socialForm.enabled} /></label>

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(app)/admin/settings/general-settings.svelte

@@ -19,7 +19,6 @@
     description: "",
     supportEmail: "",
     footerText: "",
-    brandColor: "",
     termsUrl: "",
     privacyUrl: "",
     locale: "",
@@ -35,7 +34,6 @@
       description: s.description ?? "",
       supportEmail: s.supportEmail ?? "",
       footerText: s.footerText ?? "",
-      brandColor: s.brandColor ?? "",
       termsUrl: s.termsUrl ?? "",
       privacyUrl: s.privacyUrl ?? "",
       locale: s.locale ?? "",
@@ -127,11 +125,6 @@
           </div>
         </div>
       </div>
-
-      <div class="flex flex-col gap-1.5">
-        <Label for="brand-color">{t.brandColor}</Label>
-        <Input id="brand-color" bind:value={form.brandColor} placeholder="#6d28d9" />
-      </div>
     </Card.Content>
   </Card.Root>
 

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(auth)/login/+page.svelte

@@ -22,6 +22,49 @@
   let unverified = $state(false);
   let loading = $state(false);
 
+  // Second-factor step: a password/OTP sign-in with 2FA enabled returns
+  // `twoFactorRedirect` and no session; the user then verifies with an
+  // authenticator code or a backup code to complete the login.
+  let twoFaRequired = $state(false);
+  let twoFaCode = $state("");
+  let useBackupCode = $state(false);
+  let twoFaLoading = $state(false);
+  const redirectTo = (): string => page.url.searchParams.get("redirect") ?? "/admin";
+
+  // Returns true when 2FA is still owed (caller shows the step instead of leaving).
+  function needsTwoFactor(data: unknown): boolean {
+    return Boolean(data && typeof data === "object" && (data as { twoFactorRedirect?: boolean }).twoFactorRedirect);
+  }
+
+  // Map better-auth's (English) two-factor error codes to localized copy — the
+  // backend returns a stable `code`, never a translated message (see i18n policy).
+  function twoFactorError(code: string | undefined): string {
+    switch (code) {
+      case "INVALID_CODE":
+      case "INVALID_BACKUP_CODE":
+        return i18n.t.auth.twoFactorInvalidCode;
+      case "TOO_MANY_ATTEMPTS_REQUEST_NEW_CODE":
+      case "ACCOUNT_TEMPORARILY_LOCKED":
+        return i18n.t.auth.twoFactorLocked;
+      default:
+        return i18n.t.auth.signInFailed;
+    }
+  }
+
+  async function verifyTwoFactor(): Promise<void> {
+    twoFaLoading = true;
+    error = null;
+    const { error: authError } = useBackupCode
+      ? await api.auth.twoFactor.verifyBackupCode({ code: twoFaCode.trim() })
+      : await api.auth.twoFactor.verifyTotp({ code: twoFaCode.trim() });
+    twoFaLoading = false;
+    if (authError) {
+      error = twoFactorError(authError.code);
+      return;
+    }
+    await goto(redirectTo(), { invalidateAll: true });
+  }
+
   // Passwordless sign-in, shown only when the server enabled the magic-link plugin.
   const magicLinkEnabled = $derived(data.capabilities?.magicLink ?? false);
   let magicLoading = $state(false);
@@ -69,13 +112,17 @@
   async function verifyOtp(): Promise<void> {
     otpLoading = true;
     error = null;
-    const { error: authError } = await api.auth.signIn.emailOtp({ email, otp: otpCode });
+    const { data, error: authError } = await api.auth.signIn.emailOtp({ email, otp: otpCode });
     otpLoading = false;
     if (authError) {
       error = authError.message ?? i18n.t.auth.signInFailed;
       return;
     }
-    await goto(page.url.searchParams.get("redirect") ?? "/admin", { invalidateAll: true });
+    if (needsTwoFactor(data)) {
+      twoFaRequired = true;
+      return;
+    }
+    await goto(redirectTo(), { invalidateAll: true });
   }
 
   // Passwordless sign-in with a registered passkey (WebAuthn), shown when enabled.
@@ -100,7 +147,7 @@
     unverified = false;
     // With the username plugin on, an identifier without "@" is treated as a username.
     const asUsername = usernameEnabled && !email.includes("@");
-    const { error: authError } = asUsername
+    const { data, error: authError } = asUsername
       ? await api.auth.signIn.username({ username: email, password })
       : await api.auth.signIn.email({ email, password });
     loading = false;
@@ -110,7 +157,11 @@
       error = unverified ? i18n.t.auth.emailNotVerified : (authError.message ?? i18n.t.auth.signInFailed);
       return;
     }
-    await goto(page.url.searchParams.get("redirect") ?? "/admin", { invalidateAll: true });
+    if (needsTwoFactor(data)) {
+      twoFaRequired = true;
+      return;
+    }
+    await goto(redirectTo(), { invalidateAll: true });
   }
 </script>
 
@@ -120,17 +171,47 @@
     <Card.Description>{i18n.t.auth.signInDesc}</Card.Description>
   </Card.Header>
   <Card.Content>
+    {#if error}
+      <Alert.Root variant="destructive" class="mb-4">
+        <Alert.Description>
+          {error}
+          {#if unverified}
+            <a href="/verify-email?email={encodeURIComponent(email)}" class="font-medium underline">{i18n.t.auth.resendVerification}</a>
+          {/if}
+        </Alert.Description>
+      </Alert.Root>
+    {/if}
+    {#if twoFaRequired}
+      <div class="flex flex-col gap-4" data-testid="two-factor-step">
+        <p class="text-muted-foreground text-sm">{useBackupCode ? i18n.t.auth.twoFactorBackupPrompt : i18n.t.auth.twoFactorPrompt}</p>
+        <div class="flex flex-col gap-2">
+          <Label for="twofa">{useBackupCode ? i18n.t.auth.backupCodeLabel : i18n.t.auth.twoFactorCodeLabel}</Label>
+          <Input
+            id="twofa"
+            bind:value={twoFaCode}
+            inputmode={useBackupCode ? "text" : "numeric"}
+            autocomplete="one-time-code"
+            autofocus
+          />
+        </div>
+        <Button type="button" disabled={twoFaLoading || !twoFaCode} onclick={verifyTwoFactor}>
+          {twoFaLoading ? i18n.t.auth.signingIn : i18n.t.auth.verify}
+        </Button>
+        <Button
+          type="button"
+          variant="link"
+          class="h-auto justify-start p-0 text-xs"
+          onclick={() => {
+            useBackupCode = !useBackupCode;
+            twoFaCode = "";
+            error = null;
+          }}
+        >
+          {useBackupCode ? i18n.t.auth.twoFactorUseAuthenticator : i18n.t.auth.twoFactorUseBackup}
+        </Button>
+      </div>
+    {:else}
     <form class="flex flex-col gap-4" onsubmit={submit}>
-      {#if error}
-        <Alert.Root variant="destructive">
-          <Alert.Description>
-            {error}
-            {#if unverified}
-              <a href="/verify-email?email={encodeURIComponent(email)}" class="font-medium underline">{i18n.t.auth.resendVerification}</a>
-            {/if}
-          </Alert.Description>
-        </Alert.Root>
-      {/if}
       <div class="flex flex-col gap-2">
         <Label for="email">{usernameEnabled ? i18n.t.auth.emailOrUsername : i18n.t.auth.email}</Label>
         <Input id="email" type={usernameEnabled ? "text" : "email"} bind:value={email} required autocomplete="username" />
@@ -177,6 +258,7 @@
         {/if}
       </div>
     {/if}
+    {/if}
   </Card.Content>
   {#if signupOpen}
     <Card.Footer class="justify-center">

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/+layout.server.ts

@@ -10,6 +10,7 @@ const PUBLIC_PATHS = [
   "/signup",
   "/forgot-password",
   "/reset-password",
+  "/verify-email",
   "/maintenance",
   // Modules add their public (no-session) page prefixes here.
   // podokit:begin:public-paths

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/account/+page.server.ts

@@ -0,0 +1,4 @@
+import { loadAccountData } from "$lib/account-data.server";
+import type { PageServerLoad } from "./$types";
+
+export const load: PageServerLoad = ({ locals, fetch }) => loadAccountData(locals, fetch);

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/account/+page.svelte

@@ -0,0 +1,35 @@
+<script lang="ts">
+  import AccountPage from "$lib/components/account-page.svelte";
+  import LanguageSwitch from "$lib/components/language-switch.svelte";
+  import SiteFooter from "$lib/components/site-footer.svelte";
+  import ThemeToggle from "$lib/components/theme-toggle.svelte";
+  import { Button } from "$lib/components/ui/button";
+  import { Toaster } from "$lib/components/ui/sonner";
+  import { getI18n } from "$lib/i18n";
+  import type { Capabilities } from "@podosoft/podokit-api-client";
+  import type { SessionUser } from "../../app.d.ts";
+
+  let {
+    data,
+  }: {
+    data: { user: SessionUser; currentSessionId: string | null; capabilities: Capabilities };
+  } = $props();
+  const i18n = getI18n();
+</script>
+
+<div class="flex min-h-svh flex-col">
+  <header class="flex h-14 items-center gap-2 border-b px-4">
+    <Button href="/" variant="ghost">{i18n.t.nav.home}</Button>
+    <div class="flex-1"></div>
+    {#if data.user.role === "admin"}
+      <Button href="/admin" variant="outline">{i18n.t.common.appName}</Button>
+    {/if}
+    <LanguageSwitch />
+    <ThemeToggle />
+  </header>
+  <main class="mx-auto w-full max-w-6xl flex-1 p-4 sm:p-6">
+    <AccountPage {data} />
+  </main>
+  <SiteFooter />
+</div>
+<Toaster />

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/setup-2fa/+page.server.ts

@@ -0,0 +1,11 @@
+import { redirect } from "@sveltejs/kit";
+import type { PageServerLoad } from "./$types";
+
+// The mandatory two-factor enrolment page (reached via the require-2fa gate).
+// Must be signed in; already-enrolled users have nothing to do here.
+export const load: PageServerLoad = ({ locals }) => {
+  if (!locals.user) redirect(302, "/login");
+  const user = locals.user as App.Locals["user"] & { twoFactorEnabled?: boolean };
+  if (user.twoFactorEnabled) redirect(302, "/admin");
+  return { user: locals.user };
+};

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/setup-2fa/+page.svelte

@@ -0,0 +1,122 @@
+<script lang="ts">
+  import { goto } from "$app/navigation";
+  import QRCode from "qrcode";
+  import { Button } from "$lib/components/ui/button";
+  import { Input } from "$lib/components/ui/input";
+  import { Label } from "$lib/components/ui/label";
+  import { Checkbox } from "$lib/components/ui/checkbox";
+  import * as Card from "$lib/components/ui/card";
+  import * as Alert from "$lib/components/ui/alert";
+  import { api } from "$lib/api";
+  import { getI18n } from "$lib/i18n";
+
+  const i18n = getI18n();
+  let password = $state("");
+  let code = $state("");
+  let busy = $state(false);
+  let error = $state<string | null>(null);
+  let saved = $state(false);
+  let setup = $state<{ totpURI: string; backupCodes: string[] } | null>(null);
+  let qrDataUrl = $state("");
+
+  $effect(() => {
+    const uri = setup?.totpURI;
+    if (!uri) {
+      qrDataUrl = "";
+      return;
+    }
+    QRCode.toDataURL(uri, { margin: 1, width: 176 })
+      .then((url) => (qrDataUrl = url))
+      .catch(() => (qrDataUrl = ""));
+  });
+
+  async function begin(): Promise<void> {
+    busy = true;
+    error = null;
+    const { data, error: e } = await api.auth.twoFactor.enable({ password });
+    busy = false;
+    if (e) {
+      error = e.code === "INVALID_PASSWORD" ? i18n.t.setup2fa.wrongPassword : i18n.t.setup2fa.enableFailed;
+      return;
+    }
+    setup = { totpURI: data?.totpURI ?? "", backupCodes: (data?.backupCodes ?? []) as string[] };
+  }
+
+  async function activate(): Promise<void> {
+    busy = true;
+    error = null;
+    const { error: e } = await api.auth.twoFactor.verifyTotp({ code: code.trim() });
+    busy = false;
+    if (e) {
+      error = i18n.t.auth.twoFactorInvalidCode;
+      return;
+    }
+    await goto("/admin", { invalidateAll: true });
+  }
+
+  function downloadCodes(): void {
+    if (!setup) return;
+    const blob = new Blob([setup.backupCodes.join("\n") + "\n"], { type: "text/plain" });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = "backup-codes.txt";
+    a.click();
+    URL.revokeObjectURL(url);
+  }
+
+  async function signOut(): Promise<void> {
+    await api.auth.signOut();
+    await goto("/login", { invalidateAll: true });
+  }
+</script>
+
+<div class="flex min-h-svh items-center justify-center p-4">
+  <Card.Root class="w-full max-w-md">
+    <Card.Header>
+      <Card.Title>{i18n.t.setup2fa.title}</Card.Title>
+      <Card.Description>{i18n.t.setup2fa.subtitle}</Card.Description>
+    </Card.Header>
+    <Card.Content class="flex flex-col gap-4">
+      {#if error}
+        <Alert.Root variant="destructive"><Alert.Description>{error}</Alert.Description></Alert.Root>
+      {/if}
+
+      {#if !setup}
+        <div class="flex flex-col gap-2">
+          <Label for="pw">{i18n.t.setup2fa.passwordLabel}</Label>
+          <Input id="pw" type="password" bind:value={password} autocomplete="current-password" />
+        </div>
+        <Button disabled={busy || !password} onclick={begin}>{i18n.t.setup2fa.begin}</Button>
+      {:else}
+        <div class="flex flex-col gap-1">
+          <Label>{i18n.t.setup2fa.step1}</Label>
+          {#if qrDataUrl}
+            <img src={qrDataUrl} alt="TOTP QR code" width="176" height="176" class="rounded border bg-white p-2" />
+          {/if}
+          <code class="bg-muted overflow-x-auto rounded px-2 py-1 text-xs">{setup.totpURI}</code>
+        </div>
+
+        <div class="flex flex-col gap-1">
+          <Label>{i18n.t.setup2fa.step2}</Label>
+          <p class="text-muted-foreground text-xs">{i18n.t.account.backupCodesHint}</p>
+          <div class="bg-muted grid grid-cols-2 gap-1 rounded p-2 font-mono text-xs" data-testid="backup-codes">
+            {#each setup.backupCodes as c (c)}<span>{c}</span>{/each}
+          </div>
+          <Button variant="outline" size="sm" class="w-fit" onclick={downloadCodes}>{i18n.t.account.downloadBackupCodes}</Button>
+          <label class="mt-1 flex items-center gap-2 text-sm">
+            <Checkbox bind:checked={saved} /> {i18n.t.setup2fa.savedConfirm}
+          </label>
+        </div>
+
+        <div class="flex flex-col gap-2">
+          <Label for="code">{i18n.t.setup2fa.step3}</Label>
+          <Input id="code" bind:value={code} inputmode="numeric" autocomplete="one-time-code" />
+        </div>
+        <Button disabled={busy || !saved || !code} onclick={activate}>{i18n.t.setup2fa.activate}</Button>
+      {/if}
+
+      <Button variant="link" class="h-auto justify-start p-0 text-xs" onclick={signOut}>{i18n.t.setup2fa.signOut}</Button>
+    </Card.Content>
+  </Card.Root>
+</div>

package/dist/templates/modules/admin-dashboard/files/tests/api/auth.api.spec.ts

@@ -74,6 +74,112 @@ test("two-factor: enable with a real TOTP code and require it at sign-in @smoke"
   await ctx2.dispose();
 });
 
+test("two-factor: a backup code completes sign-in and is single-use @smoke", async ({ playwright }) => {
+  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const caps = await (await ctx.get("/api/account/capabilities")).json();
+  test.skip(!caps?.twoFactor, "two-factor not enabled");
+  const email = `tf-bc-${Date.now()}@example.com`;
+  const pw = "Podokit3e-Str0ng!pw";
+  await ctx.post("/api/auth/sign-up/email", { data: { email, password: pw, name: "BC" } });
+
+  // Enable 2FA; the enable response includes the one-time backup codes.
+  const enable = await (await ctx.post("/api/auth/two-factor/enable", { data: { password: pw } })).json();
+  await ctx.post("/api/auth/two-factor/verify-totp", { data: { code: totpCode(enable.totpURI) } });
+  const backupCodes = enable.backupCodes as string[];
+  expect(Array.isArray(backupCodes)).toBe(true);
+  expect(backupCodes.length).toBeGreaterThan(0);
+  const code = backupCodes[0]!;
+
+  // A backup code completes a challenged sign-in (no authenticator needed).
+  const ctx2 = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const signin = await (await ctx2.post("/api/auth/sign-in/email", { data: { email, password: pw } })).json();
+  expect(signin.twoFactorRedirect).toBe(true);
+  const used = await ctx2.post("/api/auth/two-factor/verify-backup-code", { data: { code } });
+  expect(used.ok()).toBeTruthy();
+  const session = await (await ctx2.get("/api/auth/get-session")).json();
+  expect(session?.user?.email).toBe(email);
+
+  // The same code is single-use: a new challenge cannot reuse it.
+  const ctx3 = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  await ctx3.post("/api/auth/sign-in/email", { data: { email, password: pw } });
+  const reuse = await ctx3.post("/api/auth/two-factor/verify-backup-code", { data: { code } });
+  expect(reuse.ok()).toBeFalsy();
+
+  await ctx.dispose();
+  await ctx2.dispose();
+  await ctx3.dispose();
+});
+
+test("two-factor: regenerating backup codes invalidates the old set @smoke", async ({ playwright }) => {
+  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const caps = await (await ctx.get("/api/account/capabilities")).json();
+  test.skip(!caps?.twoFactor, "two-factor not enabled");
+  const email = `tf-rg-${Date.now()}@example.com`;
+  const pw = "Podokit3e-Str0ng!pw";
+  await ctx.post("/api/auth/sign-up/email", { data: { email, password: pw, name: "RG" } });
+  const enable = await (await ctx.post("/api/auth/two-factor/enable", { data: { password: pw } })).json();
+  await ctx.post("/api/auth/two-factor/verify-totp", { data: { code: totpCode(enable.totpURI) } });
+  const oldCode = (enable.backupCodes as string[])[0]!;
+
+  // Regenerating returns a fresh set; the previous codes are replaced.
+  const regen = await (await ctx.post("/api/auth/two-factor/generate-backup-codes", { data: { password: pw } })).json();
+  const newCodes = regen.backupCodes as string[];
+  expect(Array.isArray(newCodes)).toBe(true);
+  expect(newCodes.length).toBeGreaterThan(0);
+  expect(newCodes).not.toContain(oldCode);
+
+  // An old code no longer completes a challenge; a new one does.
+  const ctxOld = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  await ctxOld.post("/api/auth/sign-in/email", { data: { email, password: pw } });
+  expect((await ctxOld.post("/api/auth/two-factor/verify-backup-code", { data: { code: oldCode } })).ok()).toBeFalsy();
+
+  const ctxNew = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  await ctxNew.post("/api/auth/sign-in/email", { data: { email, password: pw } });
+  expect((await ctxNew.post("/api/auth/two-factor/verify-backup-code", { data: { code: newCodes[0]! } })).ok()).toBeTruthy();
+
+  await ctx.dispose();
+  await ctxOld.dispose();
+  await ctxNew.dispose();
+});
+
+test("require-2fa: gates an un-enrolled user until they enrol @smoke", async ({ playwright }) => {
+  const admin = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const caps = await (await admin.get("/api/account/capabilities")).json();
+  test.skip(!caps?.twoFactor, "two-factor not enabled");
+  await admin.post("/api/auth/sign-in/email", { data: { email: ADMIN.email, password: ADMIN.password } });
+
+  const user = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const email = `rq-${Date.now()}@example.com`;
+  const pw = "Podokit3e-Str0ng!pw";
+  await user.post("/api/auth/sign-up/email", { data: { email, password: pw, name: "RQ" } });
+
+  try {
+    // Turn the policy on (admin; the toggle endpoint is allow-listed by the guard).
+    await admin.put("/api/account/settings", { data: { require2fa: true } });
+    // The guard caches for a few seconds — poll until the un-enrolled user is gated.
+    await expect(async () => {
+      expect((await user.get("/api/account/me")).status()).toBe(403);
+    }).toPass({ timeout: 8000 });
+
+    // Enrolling restores access.
+    const enable = await (await user.post("/api/auth/two-factor/enable", { data: { password: pw } })).json();
+    await user.post("/api/auth/two-factor/verify-totp", { data: { code: totpCode(enable.totpURI) } });
+    expect((await user.get("/api/account/me")).status()).toBe(200);
+  } finally {
+    // Always turn it back off so the shared (un-enrolled) sessions aren't gated.
+    await admin.put("/api/account/settings", { data: { require2fa: false } });
+    await expect(async () => {
+      const probe = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+      await probe.post("/api/auth/sign-in/email", { data: { email: USER.email, password: USER.password } });
+      const status = (await probe.get("/api/account/me")).status();
+      await probe.dispose();
+      expect(status).toBe(200);
+    }).toPass({ timeout: 8000 });
+    await admin.dispose();
+    await user.dispose();
+  }
+});
+
 test("multi-session holds several accounts and switches between them @smoke", async ({ playwright }) => {
   const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
   const caps = await (await ctx.get("/api/account/capabilities")).json();

package/dist/templates/modules/admin-dashboard/files/tests/api/site-settings.api.spec.ts

@@ -0,0 +1,56 @@
+import { expect, test } from "@playwright/test";
+import { ADMIN } from "../helpers/accounts";
+
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const origin = { origin: base };
+
+// Fresh admin context so these never rotate the seeded admin session.
+async function adminCtx(playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"]) {
+  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  await ctx.post("/api/auth/sign-in/email", { data: { email: ADMIN.email, password: ADMIN.password } });
+  return ctx;
+}
+
+test("theme settings: valid preset/radius/accent round-trip @smoke", async ({ playwright }) => {
+  const admin = await adminCtx(playwright);
+  const put = await admin.put("/api/site/settings", {
+    data: { themePreset: "slate", themeRadius: "0.75", brandColor: "#2563eb" },
+  });
+  expect(put.ok()).toBeTruthy();
+
+  const anon = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const settings = await (await anon.get("/api/site/settings")).json();
+  expect(settings.themePreset).toBe("slate");
+  expect(settings.themeRadius).toBe("0.75");
+  expect(settings.brandColor).toBe("#2563eb");
+
+  // restore
+  await admin.put("/api/site/settings", { data: { themePreset: "", themeRadius: "", brandColor: "" } });
+  await anon.dispose();
+});
+
+test("theme settings: valid per-token overrides accepted @smoke", async ({ playwright }) => {
+  const admin = await adminCtx(playwright);
+  const overrides = JSON.stringify({ light: { primary: "#123456" }, dark: { background: "#0a0a0a" } });
+  const put = await admin.put("/api/site/settings", { data: { themeOverrides: overrides } });
+  expect(put.ok()).toBeTruthy();
+  await admin.put("/api/site/settings", { data: { themeOverrides: "" } }); // restore
+});
+
+test("theme settings: invalid values are rejected (no CSS injection)", async ({ playwright }) => {
+  const admin = await adminCtx(playwright);
+  const bad = [
+    { brandColor: "red; } body{display:none" },
+    { brandColor: "notacolor" },
+    { themeRadius: "9" },
+    { themeRadius: "-1" },
+    { themePreset: "bad preset!" },
+    { themeOverrides: "{not json" },
+    { themeOverrides: JSON.stringify({ light: { primary: "nothex" } }) },
+    { themeOverrides: JSON.stringify({ light: { bogusToken: "#ffffff" } }) },
+    { unknownKey: "x" },
+  ];
+  for (const data of bad) {
+    expect((await admin.put("/api/site/settings", { data })).status(), JSON.stringify(data)).toBe(400);
+  }
+});