@podosoft/podokit 0.8.0 → 0.9.0

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/i18n/messages.ts

@@ -16,6 +16,20 @@ const en = {
   language: { label: "Language" },
   toolbar: { filter: "Filter", search: "Search", searchButton: "Search", all: "All" },
   theme: { toggle: "Toggle theme", light: "Light", dark: "Dark", system: "System" },
+  setup2fa: {
+    title: "Set up two-factor authentication",
+    subtitle: "This site requires two-factor authentication. Add an authenticator app to continue.",
+    passwordLabel: "Confirm your password",
+    begin: "Continue",
+    step1: "1. Scan with your authenticator app",
+    step2: "2. Save your backup codes",
+    step3: "3. Enter the 6-digit code",
+    savedConfirm: "I've saved my backup codes",
+    activate: "Activate and continue",
+    signOut: "Sign out",
+    wrongPassword: "That password is incorrect.",
+    enableFailed: "Couldn't start setup. Please try again.",
+  },
   auth: {
     signInTitle: "Sign in",
     signInDesc: "Enter your credentials to continue.",
@@ -30,6 +44,15 @@ const en = {
     magicLinkSent: "Check your email for a sign-in link.",
     magicLinkNeedsEmail: "Enter your email first.",
     otpButton: "Email me a code", otpCode: "One-time code", otpVerify: "Verify code",
+    verify: "Verify",
+    twoFactorPrompt: "Enter the 6-digit code from your authenticator app.",
+    twoFactorBackupPrompt: "Enter one of your backup codes.",
+    twoFactorCodeLabel: "Authentication code",
+    backupCodeLabel: "Backup code",
+    twoFactorUseBackup: "Use a backup code instead",
+    twoFactorUseAuthenticator: "Use your authenticator app instead",
+    twoFactorInvalidCode: "That code isn't valid. Check it and try again.",
+    twoFactorLocked: "Too many attempts. Please wait a moment and try again.",
     noAccount: "No account?",
     signUp: "Sign up",
     signInFailed: "Sign in failed",
@@ -132,6 +155,7 @@ const en = {
     organization: "Organizations", organizationDesc: "Multi-tenant organizations with members and email invitations.",
     oidcProvider: "OIDC provider", oidcProviderDesc: "Act as an identity provider so other apps can sign in with this one.",
     twoFactor: "Two-factor authentication", twoFactorDesc: "TOTP second factor with backup codes.",
+    require2fa: "Require two-factor", require2faDesc: "Every user must enrol in 2FA after signing up before using the app.",
     socialProviders: "Social providers", socialProvidersDesc: "OAuth sign-in (Google, GitHub).",
     breachCheck: "Breached-password check", breachCheckDesc: "Reject passwords found in known breaches (Have I Been Pwned).",
     accountDeletion: "Account deletion", accountDeletionDesc: "Let users delete their own account.",
@@ -281,6 +305,11 @@ const en = {
     scanHint: "Add this to your authenticator app, then enter the 6-digit code.",
     setupKey: "Setup key (otpauth URI)",
     backupCodes: "Backup codes — store them somewhere safe",
+    backupCodesHint: "Each code works once if you lose your authenticator. Save them now — they won't be shown again.",
+    downloadBackupCodes: "Download",
+    regenerateBackupCodes: "Regenerate backup codes",
+    regenerateBackupCodesHint: "Generating a new set invalidates your previous backup codes.",
+    backupCodesRegenerated: "New backup codes generated",
     code: "Verification code",
     verify: "Verify",
     twoFactorEnabled: "Two-factor enabled",
@@ -322,6 +351,20 @@ const ko: Messages = {
   language: { label: "언어" },
   toolbar: { filter: "필터", search: "검색", searchButton: "검색", all: "전체" },
   theme: { toggle: "테마 전환", light: "라이트", dark: "다크", system: "시스템" },
+  setup2fa: {
+    title: "2단계 인증 설정",
+    subtitle: "이 사이트는 2단계 인증이 필수입니다. 계속하려면 인증 앱을 등록하세요.",
+    passwordLabel: "비밀번호 확인",
+    begin: "계속",
+    step1: "1. 인증 앱으로 스캔",
+    step2: "2. 백업 코드 저장",
+    step3: "3. 6자리 코드 입력",
+    savedConfirm: "백업 코드를 저장했습니다",
+    activate: "활성화하고 계속",
+    signOut: "로그아웃",
+    wrongPassword: "비밀번호가 올바르지 않습니다.",
+    enableFailed: "설정을 시작할 수 없습니다. 다시 시도해 주세요.",
+  },
   auth: {
     signInTitle: "로그인",
     signInDesc: "계속하려면 로그인하세요.",
@@ -336,6 +379,15 @@ const ko: Messages = {
     magicLinkSent: "이메일의 로그인 링크를 확인하세요.",
     magicLinkNeedsEmail: "먼저 이메일을 입력하세요.",
     otpButton: "코드 이메일로 받기", otpCode: "일회용 코드", otpVerify: "코드 확인",
+    verify: "확인",
+    twoFactorPrompt: "인증 앱의 6자리 코드를 입력하세요.",
+    twoFactorBackupPrompt: "백업 코드 중 하나를 입력하세요.",
+    twoFactorCodeLabel: "인증 코드",
+    backupCodeLabel: "백업 코드",
+    twoFactorUseBackup: "백업 코드로 대신 인증",
+    twoFactorUseAuthenticator: "인증 앱으로 대신 인증",
+    twoFactorInvalidCode: "코드가 올바르지 않습니다. 다시 확인해 주세요.",
+    twoFactorLocked: "시도가 너무 많습니다. 잠시 후 다시 시도해 주세요.",
     noAccount: "계정이 없으신가요?",
     signUp: "회원가입",
     signInFailed: "로그인에 실패했습니다",
@@ -438,6 +490,7 @@ const ko: Messages = {
     organization: "조직", organizationDesc: "멤버와 이메일 초대를 갖춘 멀티테넌트 조직.",
     oidcProvider: "OIDC 제공자", oidcProviderDesc: "다른 앱이 이 앱으로 로그인하도록 신원 제공자 역할.",
     twoFactor: "2단계 인증", twoFactorDesc: "TOTP 2차 인증 + 백업 코드.",
+    require2fa: "2FA 필수화", require2faDesc: "모든 사용자가 가입 후 2FA를 등록해야 앱을 사용할 수 있습니다.",
     socialProviders: "소셜 로그인", socialProvidersDesc: "OAuth 로그인 (Google, GitHub).",
     breachCheck: "유출 비밀번호 검사", breachCheckDesc: "유출된 비밀번호 거부 (Have I Been Pwned).",
     accountDeletion: "계정 삭제", accountDeletionDesc: "사용자가 자신의 계정을 삭제.",
@@ -587,6 +640,11 @@ const ko: Messages = {
     scanHint: "인증 앱에 등록한 뒤 6자리 코드를 입력하세요.",
     setupKey: "설정 키 (otpauth URI)",
     backupCodes: "백업 코드 — 안전한 곳에 보관하세요",
+    backupCodesHint: "인증 앱을 분실했을 때 각 코드는 한 번씩 사용할 수 있습니다. 지금 저장하세요 — 다시 표시되지 않습니다.",
+    downloadBackupCodes: "다운로드",
+    regenerateBackupCodes: "백업 코드 재발급",
+    regenerateBackupCodesHint: "새로 발급하면 이전 백업 코드는 무효화됩니다.",
+    backupCodesRegenerated: "새 백업 코드를 발급했습니다",
     code: "인증 코드",
     verify: "확인",
     twoFactorEnabled: "2단계 인증을 사용합니다",

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

@@ -1,3 +1,4 @@
+import { redirect } from "@sveltejs/kit";
 import type { LayoutServerLoad } from "./$types";
 import type { Capabilities } from "@podosoft/podokit-api-client";
 
@@ -26,5 +27,21 @@ export const load: LayoutServerLoad = async ({ locals, fetch }) => {
   } catch {
     /* keep defaults */
   }
+
+  // Require-two-factor policy: a signed-in user who hasn't enrolled is sent to the
+  // enrolment page until they do (the API's TwoFactorRequiredGuard is the real
+  // boundary; this is the UX). /setup-2fa lives outside this layout, so no loop.
+  const user = locals.user as (App.Locals["user"] & { twoFactorEnabled?: boolean }) | null;
+  let mustEnrol = false;
+  if (user && !user.twoFactorEnabled) {
+    try {
+      const res = await fetch("/api/account/require-2fa");
+      mustEnrol = res.ok && ((await res.json()) as { require2fa?: boolean }).require2fa === true;
+    } catch {
+      /* don't block the app if the policy check fails */
+    }
+  }
+  if (mustEnrol) redirect(302, "/setup-2fa");
+
   return { user: locals.user, impersonating: !!locals.session?.impersonatedBy, capabilities };
 };

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

@@ -162,8 +162,29 @@
     if (error) return void toast.error(error.message ?? i18n.t.account.changeFailed);
     twoFaOn = false;
     twoFaPassword = "";
+    regenCodes = null;
     toast.success(i18n.t.account.twoFactorDisabled);
   }
+  // Backup codes: regenerate a fresh set (invalidating the old ones) and download.
+  let regenCodes = $state<string[] | null>(null);
+  async function regenerateBackupCodes(): Promise<void> {
+    twoFaBusy = true;
+    const { data: res, error } = await api.auth.twoFactor.generateBackupCodes({ password: twoFaPassword });
+    twoFaBusy = false;
+    if (error) return void toast.error(error.message ?? i18n.t.account.changeFailed);
+    regenCodes = (res?.backupCodes ?? []) as string[];
+    twoFaPassword = "";
+    toast.success(i18n.t.account.backupCodesRegenerated);
+  }
+  function downloadBackupCodes(codes: string[]): void {
+    const blob = new Blob([codes.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);
+  }
 
   // Passkeys (WebAuthn) — passwordless credentials bound to this device/browser.
   type Passkey = { id: string; name: string | null; createdAt: string | Date };
@@ -470,7 +491,21 @@
                     <Label for="tf-off-pw">{i18n.t.account.password}</Label>
                     <Input id="tf-off-pw" type="password" bind:value={twoFaPassword} autocomplete="current-password" />
                   </div>
-                  <Button variant="destructive" class="w-fit" disabled={twoFaBusy || !twoFaPassword} onclick={disable2fa}>{i18n.t.account.disable}</Button>
+                  <div class="flex flex-wrap gap-2">
+                    <Button disabled={twoFaBusy || !twoFaPassword} onclick={regenerateBackupCodes}>{i18n.t.account.regenerateBackupCodes}</Button>
+                    <Button variant="destructive" disabled={twoFaBusy || !twoFaPassword} onclick={disable2fa}>{i18n.t.account.disable}</Button>
+                  </div>
+                  <p class="text-muted-foreground text-xs">{i18n.t.account.regenerateBackupCodesHint}</p>
+                  {#if regenCodes}
+                    <div class="flex flex-col gap-1">
+                      <Label>{i18n.t.account.backupCodes}</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 regenCodes as c (c)}<span>{c}</span>{/each}
+                      </div>
+                      <Button variant="outline" size="sm" class="w-fit" onclick={() => downloadBackupCodes(regenCodes!)}>{i18n.t.account.downloadBackupCodes}</Button>
+                    </div>
+                  {/if}
                 {:else if setup}
                   <p class="text-muted-foreground text-sm">{i18n.t.account.scanHint}</p>
                   {#if qrDataUrl}
@@ -482,9 +517,11 @@
                   </div>
                   <div class="flex flex-col gap-1">
                     <Label>{i18n.t.account.backupCodes}</Label>
-                    <div class="bg-muted grid grid-cols-2 gap-1 rounded p-2 font-mono text-xs">
+                    <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={() => downloadBackupCodes(setup!.backupCodes)}>{i18n.t.account.downloadBackupCodes}</Button>
                   </div>
                   <div class="flex flex-col gap-2">
                     <Label for="tf-code">{i18n.t.account.code}</Label>

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

@@ -16,12 +16,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 +57,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 +177,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),

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/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/ui/account-flows.ui.spec.ts

@@ -0,0 +1,74 @@
+import { expect, test } from "@playwright/test";
+import { anonState } from "../helpers/accounts";
+import { ready } from "../helpers/hydration";
+import { smsSinkReachable, clearSms, waitForSmsOtp } from "../helpers/sms";
+
+// Each test drives a fresh disposable account (via a real UI login) so the shared
+// admin/user sessions are never mutated.
+test.use({ storageState: anonState });
+
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const origin = { origin: base };
+const PW = "Podokit3e-Str0ng!pw";
+
+async function loginFresh(page: import("@playwright/test").Page, playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"], email: string): Promise<void> {
+  const api = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  await api.post("/api/auth/sign-up/email", { data: { email, password: PW, name: "Acc" } });
+  await api.dispose();
+  await ready(page, `/login?redirect=${encodeURIComponent("/admin/account")}`);
+  await page.locator("#email").fill(email);
+  await page.locator("#password").fill(PW);
+  await page.getByRole("button", { name: "Sign in", exact: true }).click();
+  await expect(page).toHaveURL(/\/admin\/account/);
+}
+
+test("account: register and verify a phone number @smoke", async ({ page, playwright }) => {
+  test.skip(!(await smsSinkReachable()), "sms sink unreachable");
+  await loginFresh(page, playwright, `acc-ph-${Date.now()}@example.com`);
+  const phoneInput = page.locator("#phone");
+  test.skip((await phoneInput.count()) === 0, "phone number feature disabled");
+
+  const phone = `+1555${String(Date.now()).slice(-7)}`;
+  await clearSms();
+  await phoneInput.fill(phone);
+  await page.getByRole("button", { name: "Send code" }).click();
+  const code = await waitForSmsOtp(phone);
+  await page.getByPlaceholder("Verification code").fill(code);
+  await page.getByRole("button", { name: "Verify", exact: true }).click();
+  await expect(page.getByText("Phone verified")).toBeVisible();
+});
+
+test("account: change email address @smoke", async ({ page, playwright }) => {
+  await loginFresh(page, playwright, `acc-em-${Date.now()}@example.com`);
+  await page.locator("#email").fill(`changed-${Date.now()}@example.com`);
+  await page.getByRole("button", { name: "Change email" }).click();
+  await expect(page.getByText(/Email address updated|approve the change/)).toBeVisible();
+});
+
+test("account: delete my own account @smoke", async ({ page, playwright }) => {
+  const admin = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  await admin.post("/api/auth/sign-in/email", { data: { email: "admin@example.com", password: PW } });
+  try {
+    // Account deletion is a server toggle (off by default) — enable it, then poll
+    // until the capability is live (config store has a short TTL).
+    await admin.put("/api/account/auth-config", { data: { server: { allowDelete: true } } });
+    await expect(async () => {
+      const caps = await (await admin.get("/api/account/capabilities")).json();
+      expect(caps.deleteAccount).toBe(true);
+    }).toPass({ timeout: 8000 });
+
+    await loginFresh(page, playwright, `acc-del-${Date.now()}@example.com`);
+    await page.getByRole("button", { name: "Danger zone" }).click();
+    await page.getByRole("button", { name: "Delete account" }).first().click();
+    await page.locator("#del-pw").fill(PW);
+    // The auth instance rebuilds a few seconds after allowDelete is enabled, so
+    // the first delete can be rejected — retry the confirm until it goes through.
+    await expect(async () => {
+      await page.getByRole("dialog").getByRole("button", { name: "Delete account" }).click();
+      await expect(page).toHaveURL(/\/login/, { timeout: 3000 });
+    }).toPass({ timeout: 15000 });
+  } finally {
+    await admin.put("/api/account/auth-config", { data: { server: { allowDelete: false } } });
+    await admin.dispose();
+  }
+});

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

@@ -43,3 +43,14 @@ test("reset-password without a token is disabled", async ({ page }) => {
   await expect(page.getByRole("alert")).toBeVisible();
   await expect(page.getByRole("button", { name: "Update password" })).toBeDisabled();
 });
+
+test("signup creates an account and enters the app @smoke", async ({ page }) => {
+  await ready(page, "/signup");
+  const email = `signup-${Date.now()}@example.com`;
+  await page.getByLabel("Name").fill("New User");
+  await page.getByLabel("Email").fill(email);
+  await page.getByLabel("Password").fill("Podokit3e-Str0ng!pw");
+  await page.getByRole("button", { name: "Create account" }).click();
+  // Verification off → straight into the app; on → the verify-email page.
+  await expect(page).toHaveURL(/\/admin|\/verify-email/);
+});

package/dist/templates/modules/admin-dashboard/files/tests/ui/impersonation.ui.spec.ts

@@ -0,0 +1,23 @@
+import { expect, test } from "@playwright/test";
+import { ready } from "../helpers/hydration";
+import { USER } from "../helpers/accounts";
+
+// admin storageState (project default)
+
+test("admin can impersonate a user and stop @smoke", async ({ page }) => {
+  await ready(page, "/admin/users");
+  await page.locator("#toolbar-search").fill(USER.email);
+  await page.getByRole("button", { name: "Search", exact: true }).click();
+
+  const row = page.getByRole("row", { name: new RegExp(USER.email) });
+  await row.getByRole("button").click();
+  await page.getByRole("menuitem", { name: "Impersonate" }).click();
+
+  // Impersonating drops us into the app with a banner offering to stop.
+  await expect(page).toHaveURL(/\/admin(\/|$)/);
+  const stop = page.getByRole("button", { name: "Stop impersonating" });
+  await expect(stop).toBeVisible();
+
+  await stop.click();
+  await expect(page.getByRole("button", { name: "Stop impersonating" })).toHaveCount(0);
+});

package/dist/templates/modules/admin-dashboard/files/tests/ui/login-methods.ui.spec.ts

@@ -0,0 +1,41 @@
+import { expect, test } from "@playwright/test";
+import { anonState } from "../helpers/accounts";
+import { ready } from "../helpers/hydration";
+import { mailpitReachable, clearMailpit, waitForOtp } from "../helpers/mailpit";
+
+test.use({ storageState: anonState });
+
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const origin = { origin: base };
+
+test("login: magic link shows a sent confirmation @smoke", async ({ page, playwright }) => {
+  const api = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const caps = await (await api.get("/api/account/capabilities")).json();
+  await api.dispose();
+  test.skip(!caps?.magicLink, "magic link disabled");
+
+  await ready(page, "/login");
+  await page.locator("#email").fill(`ml-${Date.now()}@example.com`);
+  await page.getByRole("button", { name: /sign-in link/i }).click();
+  await expect(page.getByTestId("magic-link-sent")).toBeVisible();
+});
+
+test("login: an emailed one-time code signs a user in @smoke", async ({ page, playwright }) => {
+  const api = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const caps = await (await api.get("/api/account/capabilities")).json();
+  test.skip(!caps?.emailOtp, "email otp disabled");
+  test.skip(!(await mailpitReachable()), "mailpit unreachable");
+
+  const email = `otp-${Date.now()}@example.com`;
+  await api.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "OTP" } });
+  await api.dispose();
+  await clearMailpit();
+
+  await ready(page, "/login");
+  await page.locator("#email").fill(email);
+  await page.getByRole("button", { name: "Email me a code" }).click();
+  const otp = await waitForOtp(email);
+  await page.getByLabel("One-time code").fill(otp);
+  await page.getByRole("button", { name: "Verify code" }).click();
+  await expect(page).toHaveURL(/\/admin/);
+});

package/dist/templates/modules/admin-dashboard/files/tests/ui/oidc.ui.spec.ts

@@ -26,14 +26,18 @@ test("OIDC provider: discovery, JWKS, client registration, authorize handoff @sm
     const jwks = await (await page.request.get(disc.jwks_uri)).json();
     expect(Array.isArray(jwks.keys) && jwks.keys.length).toBeTruthy();
 
-    // Dynamic client registration returns usable credentials.
-    const reg = await (
-      await page.request.post("/api/auth/oauth2/create-client", {
-        data: { client_name: "E2E RP", redirect_uris: [REDIRECT] },
-        headers,
-      })
-    ).json();
-    expect(reg.client_id).toBeTruthy();
+    // Dynamic client registration returns usable credentials. Retry: right after
+    // the provider is enabled the auth instance may still be rebuilding.
+    let reg: { client_id?: string; client_secret?: string } = {};
+    await expect(async () => {
+      reg = await (
+        await page.request.post("/api/auth/oauth2/create-client", {
+          data: { client_name: "E2E RP", redirect_uris: [REDIRECT] },
+          headers,
+        })
+      ).json();
+      expect(reg.client_id).toBeTruthy();
+    }).toPass({ timeout: 8000 });
     expect(reg.client_secret).toBeTruthy();
 
     // Authorize validates the client + PKCE and hands off to the consent page with

package/dist/templates/modules/admin-dashboard/files/tests/ui/organizations.ui.spec.ts

@@ -53,3 +53,38 @@ test("create an org with a non-ascii name, a parent, and a manager @smoke", asyn
   await page.getByRole("row", { name: new RegExp(parent) }).getByRole("button", { name: "Delete" }).first().click();
   await expect(page.getByText("Organization deleted").first()).toBeVisible();
 });
+
+test("organization manage: remove a member, invite one, and cancel the invite @smoke", async ({ page }) => {
+  await ready(page, "/admin/organizations");
+  const newBtn = page.getByRole("button", { name: "New organization" });
+  test.skip((await newBtn.count()) === 0, "organizations not enabled");
+
+  const name = `Mng ${Date.now()}`;
+  await newBtn.click();
+  await page.getByLabel("Name", { exact: true }).fill(name);
+  // Seed a specific non-owner member (the admin is always the owner, so pick the
+  // seeded user — .first() is order-dependent and could hit the owner).
+  await page.locator("label", { hasText: "user@example.com" }).getByRole("checkbox").click();
+  await page.getByRole("dialog").getByRole("button", { name: "Create", exact: true }).click();
+  await expect(page.getByText("Organization created").first()).toBeVisible();
+
+  try {
+    await page.getByRole("row", { name: new RegExp(name) }).getByRole("button", { name: "Manage" }).click();
+    const dialog = page.getByRole("dialog");
+
+    // The seeded non-owner member is removable.
+    const remove = dialog.getByRole("button", { name: "Remove" }).first();
+    await expect(remove).toBeVisible();
+    await remove.click();
+
+    // Invite a member by email → pending invitation appears → cancel it.
+    await dialog.locator("#invite-email").fill(`invitee-${Date.now()}@example.com`);
+    await dialog.getByRole("button", { name: "Invite", exact: true }).click();
+    await expect(page.getByText("Invitation sent").first()).toBeVisible();
+    await dialog.getByRole("button", { name: "Cancel", exact: true }).first().click();
+  } finally {
+    await page.keyboard.press("Escape").catch(() => undefined);
+    await page.getByRole("row", { name: new RegExp(name) }).getByRole("button", { name: "Delete" }).first().click();
+    await expect(page.getByText("Organization deleted").first()).toBeVisible();
+  }
+});

package/dist/templates/modules/admin-dashboard/files/tests/ui/settings-dialogs.ui.spec.ts

@@ -0,0 +1,61 @@
+import { expect, test } from "@playwright/test";
+import { ready } from "../helpers/hydration";
+
+// admin storageState (project default)
+
+test("settings: add and remove a social login provider @smoke", async ({ page }) => {
+  const dialog = page.getByRole("dialog");
+  const addBtn = dialog.getByRole("button", { name: "Add provider" });
+  const openConfigure = async (): Promise<void> => {
+    await page.getByRole("tab", { name: "Authentication" }).click();
+    await page.getByRole("button", { name: "Configure" }).click();
+  };
+
+  await ready(page, "/admin/settings");
+  // The auth-config catalog can be momentarily unavailable right after another
+  // spec toggles auth config (the auth instance rebuilds). Reload until the
+  // catalog is loaded (Add provider becomes enabled).
+  await expect(async () => {
+    await page.reload();
+    await openConfigure();
+    await expect(addBtn).toBeEnabled({ timeout: 3000 });
+  }).toPass({ timeout: 25000 });
+
+  await addBtn.click();
+  const select = dialog.locator("#social-provider");
+  await expect(select.locator("option").first()).toBeAttached();
+  const providerId = await select.inputValue(); // first addable provider (not hard-coded)
+  try {
+    await dialog.locator("#social-id").fill("test-client-id");
+    await dialog.locator("#social-secret").fill("test-secret");
+    await dialog.getByRole("button", { name: "Save", exact: true }).click();
+    // Save returns to the list view, where the new provider row has an enable switch.
+    await expect(dialog.getByRole("switch").first()).toBeVisible();
+  } finally {
+    if (providerId) {
+      await page.request
+        .put("/api/account/auth-config", { data: { social: { [providerId]: { delete: true } } } })
+        .catch(() => undefined);
+    }
+  }
+});
+
+test("settings: open and save the SMTP dialog @smoke", async ({ page }) => {
+  await ready(page, "/admin/settings");
+  await page.getByRole("tab", { name: "Authentication" }).click();
+  await page.getByRole("button", { name: "SMTP settings" }).click();
+  const dialog = page.getByRole("dialog");
+  try {
+    // Point at the same Mailpit the env already uses, so saving can't re-route mail
+    // for the other email specs.
+    await dialog.locator("#smtp-host").fill("localhost");
+    await dialog.locator("#smtp-port").fill("1125");
+    await dialog.getByRole("button", { name: "Save", exact: true }).click();
+    await expect(page.getByText("Setting updated").first()).toBeVisible();
+  } finally {
+    // Reset SMTP so the config store falls back to environment for later specs.
+    await page.request
+      .put("/api/account/auth-config", { data: { smtp: { enabled: false, host: "", port: 587, user: "", from: "", secure: false } } })
+      .catch(() => undefined);
+  }
+});

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

@@ -73,3 +73,12 @@ test("admin can toggle a feature flag and it applies live @smoke", async ({ page
   await toggle.click();
   await expect(toggle).toBeChecked();
 });
+
+test("settings: the require-two-factor toggle is available @smoke", async ({ page }) => {
+  await ready(page, "/admin/settings");
+  await page.getByRole("tab", { name: "Authentication" }).click();
+  // The policy toggle renders under Authentication; its enforcement is covered by
+  // the require-2fa api/ui specs. Not toggled here — turning it on would gate this
+  // admin session.
+  await expect(page.getByRole("switch", { name: "Require two-factor" })).toBeVisible();
+});

package/dist/templates/modules/admin-dashboard/files/tests/ui/two-factor.ui.spec.ts

@@ -0,0 +1,129 @@
+import { expect, test } from "@playwright/test";
+import { anonState } from "../helpers/accounts";
+import { totpCode } from "../helpers/totp";
+
+test.use({ storageState: anonState });
+
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const origin = { origin: base };
+
+// A disposable account (never the shared admin/user) so enabling 2FA here can't
+// invalidate the seeded sessions the other auth specs rely on.
+test("two-factor: sign in with a backup code from the login page @smoke", async ({ page, playwright }) => {
+  const api = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const caps = await (await api.get("/api/account/capabilities")).json();
+  test.skip(!caps?.twoFactor, "two-factor not enabled");
+
+  const email = `tf-ui-${Date.now()}@example.com`;
+  const pw = "Podokit3e-Str0ng!pw";
+  await api.post("/api/auth/sign-up/email", { data: { email, password: pw, name: "UI" } });
+  const enable = await (await api.post("/api/auth/two-factor/enable", { data: { password: pw } })).json();
+  await api.post("/api/auth/two-factor/verify-totp", { data: { code: totpCode(enable.totpURI) } });
+  const backupCode = (enable.backupCodes as string[])[0]!;
+  await api.dispose();
+
+  // Password sign-in hands off to the second-factor step (no session yet).
+  await page.goto(`/login?redirect=${encodeURIComponent("/admin/account")}`);
+  await page.getByLabel("Email").fill(email);
+  await page.getByLabel("Password").fill(pw);
+  await page.getByRole("button", { name: "Sign in", exact: true }).click();
+
+  const step = page.getByTestId("two-factor-step");
+  await expect(step).toBeVisible();
+
+  // Switch to the backup-code input.
+  await page.getByRole("button", { name: "Use a backup code instead" }).click();
+
+  // A wrong code surfaces a localized, mapped message — not better-auth's raw
+  // English string ("Invalid backup code").
+  await page.getByLabel("Backup code").fill("00000000");
+  await page.getByRole("button", { name: "Verify", exact: true }).click();
+  await expect(page.getByRole("alert")).toContainText("isn't valid");
+  await expect(page.getByRole("alert")).not.toContainText("Invalid backup code");
+
+  // The real code completes the login.
+  await page.getByLabel("Backup code").fill(backupCode);
+  await page.getByRole("button", { name: "Verify", exact: true }).click();
+  await expect(page).toHaveURL(/\/admin\/account/);
+});
+
+test("require-2fa: a new sign-up is forced through the enrolment page @smoke", async ({ page, 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@example.com", password: "Podokit3e-Str0ng!pw" } });
+
+  const email = `rq-ui-${Date.now()}@example.com`;
+  const pw = "Podokit3e-Str0ng!pw";
+  try {
+    await admin.put("/api/account/settings", { data: { require2fa: true } });
+    // A fresh un-enrolled user; poll (via API) until the guard cache picks up the policy.
+    const probe = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+    await probe.post("/api/auth/sign-up/email", { data: { email, password: pw, name: "RQUI" } });
+    await expect(async () => {
+      expect((await probe.get("/api/account/me")).status()).toBe(403);
+    }).toPass({ timeout: 8000 });
+    await probe.dispose();
+
+    // Signing in through the UI lands on the mandatory enrolment page.
+    await page.goto("/login");
+    await page.getByLabel("Email").fill(email);
+    await page.getByLabel("Password").fill(pw);
+    await page.getByRole("button", { name: "Sign in", exact: true }).click();
+    await expect(page).toHaveURL(/\/setup-2fa/);
+
+    // Complete enrolment entirely through the UI: password → QR + backup codes →
+    // authenticator code → activate. The code is computed from the on-page URI.
+    await page.getByLabel("Confirm your password").fill(pw);
+    await page.getByRole("button", { name: "Continue" }).click();
+    await expect(page.getByTestId("backup-codes")).toBeVisible();
+    await expect(page.getByRole("button", { name: "Download" })).toBeVisible();
+    const uri = (await page.locator("code").first().innerText()).trim();
+    await page.getByRole("checkbox").click();
+    await page.getByLabel("3. Enter the 6-digit code").fill(totpCode(uri));
+    await page.getByRole("button", { name: "Activate and continue" }).click();
+
+    // Enrolled → the gate lets them into the app (no longer bounced to /setup-2fa).
+    await expect(page).toHaveURL(/\/admin/);
+  } finally {
+    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@example.com", password: "Podokit3e-Str0ng!pw" } });
+      const status = (await probe.get("/api/account/me")).status();
+      await probe.dispose();
+      expect(status).toBe(200);
+    }).toPass({ timeout: 8000 });
+    await admin.dispose();
+  }
+});
+
+test("account: regenerate backup codes shows a fresh set @smoke", async ({ page, playwright }) => {
+  const api = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const caps = await (await api.get("/api/account/capabilities")).json();
+  test.skip(!caps?.twoFactor, "two-factor not enabled");
+  const email = `regen-ui-${Date.now()}@example.com`;
+  const pw = "Podokit3e-Str0ng!pw";
+  await api.post("/api/auth/sign-up/email", { data: { email, password: pw, name: "RG" } });
+  const enable = await (await api.post("/api/auth/two-factor/enable", { data: { password: pw } })).json();
+  await api.post("/api/auth/two-factor/verify-totp", { data: { code: totpCode(enable.totpURI) } });
+  const backupCode = (enable.backupCodes as string[])[0]!;
+  await api.dispose();
+
+  // Sign in (backup-code path) straight to the account page.
+  await page.goto(`/login?redirect=${encodeURIComponent("/admin/account")}`);
+  await page.getByLabel("Email").fill(email);
+  await page.getByLabel("Password").fill(pw);
+  await page.getByRole("button", { name: "Sign in", exact: true }).click();
+  await page.getByRole("button", { name: "Use a backup code instead" }).click();
+  await page.getByLabel("Backup code").fill(backupCode);
+  await page.getByRole("button", { name: "Verify", exact: true }).click();
+  await expect(page).toHaveURL(/\/admin\/account/);
+
+  // Security → regenerate backup codes → a fresh set is shown.
+  await page.getByRole("button", { name: "Security" }).click();
+  await page.locator("#tf-off-pw").fill(pw);
+  await page.getByRole("button", { name: "Regenerate backup codes" }).click();
+  await expect(page.getByTestId("backup-codes")).toBeVisible();
+  await expect(page.getByRole("button", { name: "Download" })).toBeVisible();
+});

package/dist/templates/modules/admin-dashboard/files/tests/ui/verify-email.ui.spec.ts

@@ -0,0 +1,17 @@
+import { expect, test } from "@playwright/test";
+import { anonState } from "../helpers/accounts";
+import { ready } from "../helpers/hydration";
+
+test.use({ storageState: anonState });
+
+test("verify-email renders the resend form with the address prefilled @smoke", async ({ page }) => {
+  await ready(page, "/verify-email?email=someone%40example.com");
+  await expect(page.getByLabel("Email")).toHaveValue("someone@example.com");
+  await expect(page.getByRole("button", { name: "Resend verification email" })).toBeVisible();
+  await expect(page.getByRole("link", { name: /sign in/i })).toBeVisible();
+});
+
+test("verify-email shows the link-error alert on a bad link", async ({ page }) => {
+  await ready(page, "/verify-email?error=invalid");
+  await expect(page.getByRole("alert")).toBeVisible();
+});

package/dist/templates/modules/auth/files/apps/api/src/account/account.controller.ts

@@ -29,6 +29,14 @@ export class AccountController {
     return session.user;
   }
 
+  // The "require two-factor" policy, for the web enrolment gate. Kept out of the
+  // typed Capabilities (that lives in a published package); allow-listed in
+  // TwoFactorRequiredGuard so a not-yet-enrolled user can still read it.
+  @Get("require-2fa")
+  requireTwoFactor(): { require2fa: boolean } {
+    return { require2fa: this.settings.getBool("require2fa") };
+  }
+
   // Which optional auth features are enabled, so the UI can show/hide sections.
   // Public so the login page (unauthenticated) can offer available sign-in methods.
   @Public()

package/dist/templates/modules/auth/files/apps/api/src/auth/two-factor-required.guard.ts

@@ -0,0 +1,68 @@
+import { type CanActivate, type ExecutionContext, Injectable } from "@nestjs/common";
+import type { Request } from "express";
+import { fromNodeHeaders } from "better-auth/node";
+import { AppException } from "@podosoft/podokit-contracts";
+import { FLAG_DEFAULTS } from "../settings/flag-defaults";
+import { pool } from "./db";
+import { auth } from "./auth";
+
+/**
+ * Enforces the "require two-factor" policy (admin Settings): while it is on, a
+ * signed-in user who has not enrolled in 2FA is blocked from every app route
+ * until they do — the security boundary behind the web enrolment gate (the web
+ * redirect is only UX).
+ *
+ * Registered after the better-auth AuthGuard. Requests with no user session
+ * (unauthenticated, or machine api-key/bearer calls) are not gated here — the
+ * auth guard owns authentication. A short allow-list keeps the endpoints needed
+ * to read the policy and enrol reachable; the 2FA enrol/verify endpoints live
+ * under /api/auth/two-factor (better-auth), never behind this guard.
+ *
+ * `require2fa` is read from app_setting through a small TTL cache (self-contained,
+ * so this global guard needs no DI), the same way auth/feature-gate.ts reads flags.
+ */
+@Injectable()
+export class TwoFactorRequiredGuard implements CanActivate {
+  // Reachable while gated: read the policy/capabilities, and — break-glass — the
+  // admin-only flag toggle, so an admin who turned the policy on (and isn't yet
+  // enrolled) can still turn it back off instead of being hard-locked.
+  private static readonly ALLOW = [
+    "/account/capabilities",
+    "/account/require-2fa",
+    "/account/settings",
+    "/health",
+  ];
+  private static readonly TTL_MS = 3_000;
+  private cached = FLAG_DEFAULTS.require2fa;
+  private fetchedAt = 0;
+
+  private async enforced(): Promise<boolean> {
+    if (Date.now() - this.fetchedAt < TwoFactorRequiredGuard.TTL_MS) return this.cached;
+    try {
+      const res = await pool.query<{ value: string }>(
+        'SELECT "value" FROM "app_setting" WHERE "key" = $1',
+        ["require2fa"],
+      );
+      this.cached = res.rows[0]?.value === "true";
+    } catch {
+      this.cached = FLAG_DEFAULTS.require2fa;
+    }
+    this.fetchedAt = Date.now();
+    return this.cached;
+  }
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    if (context.getType() !== "http") return true;
+    const req = context.switchToHttp().getRequest<Request>();
+    const path = req.path || req.url || "";
+    if (TwoFactorRequiredGuard.ALLOW.some((p) => path === p || path.startsWith(`${p}/`))) return true;
+    if (!(await this.enforced())) return true;
+
+    const session = await auth.api.getSession({ headers: fromNodeHeaders(req.headers) });
+    const user = session?.user as { twoFactorEnabled?: boolean } | undefined;
+    if (!user) return true; // unauthenticated or non-session (machine) request
+    if (user.twoFactorEnabled) return true;
+
+    throw new AppException("TWO_FACTOR_REQUIRED", "Two-factor enrolment is required.", 403);
+  }
+}

package/dist/templates/modules/auth/files/apps/api/src/settings/flag-defaults.ts

@@ -6,7 +6,7 @@
  *
  *  Must match the rows seeded by the InitAppSettings migration. phoneNumber is
  *  off by default because real delivery needs an SMS provider. */
-export type FeatureFlag = "twoFactor" | "magicLink" | "emailOtp" | "username" | "multiSession" | "phoneNumber" | "apiKey" | "passkey" | "organization" | "oidcProvider";
+export type FeatureFlag = "twoFactor" | "magicLink" | "emailOtp" | "username" | "multiSession" | "phoneNumber" | "apiKey" | "passkey" | "organization" | "oidcProvider" | "require2fa";
 
 export const FLAG_DEFAULTS: Record<FeatureFlag, boolean> = {
   twoFactor: true,
@@ -20,6 +20,10 @@ export const FLAG_DEFAULTS: Record<FeatureFlag, boolean> = {
   organization: true,
   // Acting as an OIDC identity provider is an enterprise opt-in; off by default.
   oidcProvider: false,
+  // Policy (not a feature endpoint): when on, every signed-in user must enrol in
+  // two-factor before using the app. Enforced by TwoFactorRequiredGuard + the web
+  // enrolment gate — the feature gate ignores it (no endpoint prefix). Off by default.
+  require2fa: false,
 };
 
 export const FEATURE_FLAGS = Object.keys(FLAG_DEFAULTS) as FeatureFlag[];

package/dist/templates/modules/auth/module.manifest.json

@@ -67,6 +67,11 @@
       "marker": "// podokit:end:imports",
       "text": "import { AuthConfigModule } from \"./auth-config/auth-config.module\";"
     },
+    {
+      "file": "apps/api/src/app.module.ts",
+      "marker": "// podokit:end:imports",
+      "text": "import { TwoFactorRequiredGuard } from \"./auth/two-factor-required.guard\";"
+    },
     {
       "file": "apps/api/src/app.module.ts",
       "marker": "// podokit:end:module-imports",
@@ -87,6 +92,11 @@
       "marker": "// podokit:end:providers",
       "text": "{ provide: APP_GUARD, useClass: AuthGuard },"
     },
+    {
+      "file": "apps/api/src/app.module.ts",
+      "marker": "// podokit:end:providers",
+      "text": "{ provide: APP_GUARD, useClass: TwoFactorRequiredGuard },"
+    },
     {
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "An opinionated but extensible starter toolkit and CLI for full-stack TypeScript apps with NestJS, SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.",
   "license": "Apache-2.0",
   "repository": {