@podosoft/podokit 0.7.0 → 0.9.0

package/dist/index.js

@@ -8,6 +8,7 @@ const create_1 = require("./create");
 const prompt_1 = require("./prompt");
 const templates_1 = require("./templates");
 const add_1 = require("./add");
+const remove_1 = require("./remove");
 const inspect_1 = require("./inspect");
 const update_1 = require("./update");
 const eject_1 = require("./eject");
@@ -16,6 +17,7 @@ const HELP = `podo — PodoKit project generator
 Usage:
   podo create <name> [options]
   podo add <module>
+  podo remove <module>     Un-apply a module (inverse of add)
   podo status              Show version, modules, file tiers, and local edits
   podo diff                List PodoKit-managed files you have edited
   podo doctor              Check framework versions against supported ranges
@@ -111,6 +113,29 @@ async function main(argv) {
         }
         return;
     }
+    if (args.command === "remove") {
+        const moduleName = args.name;
+        if (!moduleName) {
+            fail("Usage: podo remove <module>");
+        }
+        try {
+            const result = (0, remove_1.removeModule)({ projectRoot: process.cwd(), module: moduleName, modulesDir });
+            process.stdout.write(`\nRemoved ${result.module}: ${result.removed.length} file(s) deleted` +
+                `${result.unwired.length ? `, un-wired ${result.unwired.length} target(s)` : ""}.\n`);
+            if (result.keptShared.length) {
+                process.stdout.write(`\nKept (shared with another module): ${result.keptShared.join(", ")}\n`);
+            }
+            if (result.keptEdited.length) {
+                process.stdout.write(`\nKept (you edited these — delete manually if you want them gone):\n` +
+                    result.keptEdited.map((f) => `  ${f}`).join("\n") +
+                    "\n");
+            }
+        }
+        catch (err) {
+            fail(err.message);
+        }
+        return;
+    }
     if (args.command === "status") {
         try {
             const s = (0, inspect_1.status)(process.cwd());

package/dist/remove.d.ts

@@ -0,0 +1,28 @@
+export interface RemoveOptions {
+    projectRoot: string;
+    module: string;
+    modulesDir: string;
+    /** PodoKit version stamped into the lockfile. Defaults to the CLI version. */
+    podokitVersion?: string;
+}
+export interface RemoveResult {
+    module: string;
+    /** Module overlay files deleted from the project. */
+    removed: string[];
+    /** Module files kept because the user edited them (delete manually if desired). */
+    keptEdited: string[];
+    /** Module files kept because another installed module also ships them. */
+    keptShared: string[];
+    /** Injection targets whose wiring was removed. */
+    unwired: string[];
+}
+/**
+ * Remove a previously-added module from a generated project: the inverse of
+ * `podo add`. Un-wires the module's marker injections, deletes its overlay files
+ * (keeping any the user edited or another installed module also ships), prunes
+ * the package.json deps/scripts and .env.example lines it introduced that no
+ * other installed module still needs, then drops it from the manifest and
+ * recomputes the lock. Does not cascade: a module still required by another
+ * installed module is refused rather than force-removed.
+ */
+export declare function removeModule(options: RemoveOptions): RemoveResult;

package/dist/remove.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeModule = removeModule;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
+const add_1 = require("./add");
+const lockfile_1 = require("./lockfile");
+function readModuleManifest(moduleDir) {
+    return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(moduleDir, "module.manifest.json"), "utf8"));
+}
+function readJson(path) {
+    return JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
+}
+function projectName(projectRoot) {
+    const pkg = readJson((0, node_path_1.join)(projectRoot, "package.json"));
+    return typeof pkg.name === "string" ? pkg.name : "app";
+}
+/** Output paths a module writes into a project (dot- convention applied). */
+function moduleFilePaths(moduleDir, vars) {
+    const filesDir = (0, node_path_1.join)(moduleDir, "files");
+    if (!(0, node_fs_1.existsSync)(filesDir))
+        return [];
+    return [...(0, podokit_template_engine_1.renderTemplate)(filesDir, vars).keys()];
+}
+/**
+ * Remove a previously-added module from a generated project: the inverse of
+ * `podo add`. Un-wires the module's marker injections, deletes its overlay files
+ * (keeping any the user edited or another installed module also ships), prunes
+ * the package.json deps/scripts and .env.example lines it introduced that no
+ * other installed module still needs, then drops it from the manifest and
+ * recomputes the lock. Does not cascade: a module still required by another
+ * installed module is refused rather than force-removed.
+ */
+function removeModule(options) {
+    const { projectRoot, module, modulesDir } = options;
+    const manifest = (0, lockfile_1.readManifest)(projectRoot);
+    if (!manifest) {
+        throw new Error("Not a PodoKit project: .podokit/manifest.json not found.");
+    }
+    if (!manifest.modules.some((m) => m.name === module)) {
+        const installed = manifest.modules.map((m) => m.name).join(", ") || "(none)";
+        throw new Error(`Module "${module}" is not installed. Installed: ${installed}.`);
+    }
+    const moduleDir = (0, add_1.resolveModuleDir)(module, modulesDir, projectRoot);
+    if (!moduleDir) {
+        throw new Error(`Cannot resolve module "${module}" to un-apply it. Is it still installed/bundled?`);
+    }
+    const targetManifest = readModuleManifest(moduleDir);
+    // Resolve the manifests of the OTHER installed modules once — used for the
+    // requires guard and to decide which files/deps/env are shared.
+    const others = manifest.modules
+        .filter((m) => m.name !== module)
+        .map((m) => {
+        const dir = (0, add_1.resolveModuleDir)(m.name, modulesDir, projectRoot);
+        return dir ? { name: m.name, dir, manifest: readModuleManifest(dir) } : null;
+    })
+        .filter((m) => m !== null);
+    // Guard: refuse if another installed module requires this one.
+    const dependents = others.filter((o) => (o.manifest.requires ?? []).includes(module)).map((o) => o.name);
+    if (dependents.length) {
+        throw new Error(`Cannot remove "${module}": required by ${dependents.join(", ")}. Remove ${dependents.length > 1 ? "those" : "that"} first.`);
+    }
+    const vars = { projectName: projectName(projectRoot) };
+    const sharedFiles = new Set(others.flatMap((o) => moduleFilePaths(o.dir, vars)));
+    const lock = (0, lockfile_1.readFilesLock)(projectRoot);
+    // 1) un-wire marker injections (idempotent; skips optional/absent).
+    const unwired = [];
+    for (const injection of targetManifest.inject ?? []) {
+        const target = (0, node_path_1.join)(projectRoot, injection.file);
+        if (!(0, node_fs_1.existsSync)(target))
+            continue;
+        const content = (0, node_fs_1.readFileSync)(target, "utf8");
+        const next = (0, podokit_template_engine_1.removeAtMarker)(content, injection.text);
+        if (next !== content) {
+            (0, node_fs_1.writeFileSync)(target, next);
+            unwired.push(injection.file);
+        }
+    }
+    // 2) delete overlay files, preserving edited and shared ones.
+    const removed = [];
+    const keptEdited = [];
+    const keptShared = [];
+    for (const rel of moduleFilePaths(moduleDir, vars)) {
+        const abs = (0, node_path_1.join)(projectRoot, rel);
+        if (!(0, node_fs_1.existsSync)(abs))
+            continue;
+        if (sharedFiles.has(rel)) {
+            keptShared.push(rel);
+            continue;
+        }
+        const locked = lock?.files[rel];
+        if (locked && (0, podokit_template_engine_1.hashContent)((0, node_fs_1.readFileSync)(abs)) !== locked.outHash) {
+            keptEdited.push(rel);
+            continue;
+        }
+        (0, node_fs_1.rmSync)(abs);
+        pruneEmptyDirs(projectRoot, (0, node_path_1.dirname)(rel));
+        removed.push(rel);
+    }
+    // 3) prune package.json deps/scripts this module added that no other needs.
+    pruneAppPackage(projectRoot, targetManifest, others);
+    // 4) prune .env.example lines this module added that no other needs.
+    pruneEnvExample(projectRoot, targetManifest, others);
+    // 5) drop from the manifest (re-number order) and recompute the lock.
+    manifest.modules = manifest.modules
+        .filter((m) => m.name !== module)
+        .map((m, i) => ({ ...m, order: i }));
+    (0, lockfile_1.writeManifest)(projectRoot, manifest);
+    (0, lockfile_1.writeFilesLock)(projectRoot, (0, lockfile_1.computeFilesLock)(projectRoot, manifest.ownedGlobs));
+    return { module, removed, keptEdited, keptShared, unwired };
+}
+/** Remove now-empty directories left behind by a deleted file, up to the root. */
+function pruneEmptyDirs(projectRoot, relDir) {
+    let dir = relDir;
+    while (dir && dir !== "." && dir !== "/") {
+        const abs = (0, node_path_1.join)(projectRoot, dir);
+        try {
+            (0, node_fs_1.rmdirSync)(abs); // removes only an empty directory; throws otherwise
+        }
+        catch {
+            return; // not empty (or gone) — stop climbing
+        }
+        dir = (0, node_path_1.dirname)(dir);
+    }
+}
+function pruneAppPackage(projectRoot, target, others) {
+    if (!(target.dependencies || target.devDependencies || target.scripts))
+        return;
+    const appPkgPath = (0, node_path_1.join)(projectRoot, "apps", target.targetApp, "package.json");
+    if (!(0, node_fs_1.existsSync)(appPkgPath))
+        return;
+    const keep = (section) => new Set(others.flatMap((o) => Object.keys(o.manifest[section] ?? {})));
+    const pkg = readJson(appPkgPath);
+    let changed = false;
+    for (const section of ["dependencies", "devDependencies", "scripts"]) {
+        const declared = target[section];
+        const current = pkg[section];
+        if (!declared || !current)
+            continue;
+        const shared = keep(section);
+        for (const name of Object.keys(declared)) {
+            if (shared.has(name))
+                continue;
+            if (name in current) {
+                delete current[name];
+                changed = true;
+            }
+        }
+        if (current && Object.keys(current).length === 0)
+            delete pkg[section];
+    }
+    if (changed)
+        (0, node_fs_1.writeFileSync)(appPkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+function pruneEnvExample(projectRoot, target, others) {
+    if (!target.env?.length)
+        return;
+    const file = (0, node_path_1.join)(projectRoot, ".env.example");
+    if (!(0, node_fs_1.existsSync)(file))
+        return;
+    const shared = new Set(others.flatMap((o) => o.manifest.env ?? []));
+    const drop = new Set(target.env.filter((line) => !shared.has(line)));
+    if (!drop.size)
+        return;
+    const kept = (0, node_fs_1.readFileSync)(file, "utf8")
+        .split("\n")
+        .filter((line) => !drop.has(line));
+    (0, node_fs_1.writeFileSync)(file, kept.join("\n"));
+}

package/dist/templates/fullstack-nest-svelte/AGENTS.md

@@ -66,6 +66,7 @@ in `.podokit/files.lock` — respect it:
 Useful commands:
 
 - `podo add <module>` — add a feature (auth, admin-dashboard, redis, bullmq, …). It wires itself into the app; run `podo add` with no argument to list modules.
+- `podo remove <module>` — un-apply a module (inverse of add; refuses if another module needs it, keeps files you edited).
 - `podo status` / `podo diff` — see your local edits vs. what PodoKit generated.
 - `podo update` — pull in template/module improvements (3-way merges your edits; never touches owned files).
 

package/dist/templates/fullstack-nest-svelte/apps/web/vite.config.ts

@@ -3,8 +3,14 @@ import tailwindcss from "@tailwindcss/vite";
 import { defineConfig } from "vite";
 
 // Inside the dev container (compose.dev.yaml sets VITE_DOCKER=1): bind to all
-// interfaces, allow the Traefik hostname, and route HMR through Traefik on :80.
+// interfaces, allow the Traefik hostname, and route HMR's WebSocket back through
+// Traefik. The browser reaches the app at Traefik's published host port, so the
+// HMR client must target that same port — otherwise the ws connects to :80,
+// fails, and Vite silently falls back to a full page reload on every change
+// (which wipes in-progress form input). compose.dev.yaml injects
+// VITE_HMR_CLIENT_PORT to match the published Traefik port (default 80).
 const inDocker = process.env.VITE_DOCKER === "1";
+const hmrClientPort = Number(process.env.VITE_HMR_CLIENT_PORT) || 80;
 
 export default defineConfig({
   plugins: [tailwindcss(), sveltekit()],
@@ -13,7 +19,7 @@ export default defineConfig({
         host: true,
         port: 5001,
         allowedHosts: true,
-        hmr: { clientPort: 80 },
+        hmr: { clientPort: hmrClientPort },
       }
     : undefined,
 });

package/dist/templates/fullstack-nest-svelte/compose.dev.yaml

@@ -4,7 +4,10 @@
 #   docker compose -f compose.dev.yaml --profile cache \
 #     --profile storage --profile queue watch                     # with modules
 #
-# Only Traefik binds a host port (80). The app is at http://app.localhost.
+# Only Traefik binds a host port (default 80). The app is at http://app.localhost.
+# Set TRAEFIK_PORT to publish on another port (e.g. TRAEFIK_PORT=8001) so several
+# containerized stacks can run at once without colliding — the web container reads
+# the same value as VITE_HMR_CLIENT_PORT so Vite HMR follows automatically.
 # api/postgres/redis/minio have NO published ports — they talk by service name
 # on the internal network, so this stack never collides with other projects.
 #
@@ -29,8 +32,8 @@ services:
       - --api.dashboard=true
       - --api.insecure=true
     ports:
-      - "80:80"
-      - "127.0.0.1:8080:8080" # Traefik dashboard (dev only)
+      - "${TRAEFIK_PORT:-80}:80"
+      - "127.0.0.1:${TRAEFIK_DASHBOARD_PORT:-8080}:8080" # Traefik dashboard (dev only)
     volumes:
       - ./infra/traefik/dynamic.yml:/etc/traefik/dynamic.yml:ro
     networks: [podokit]
@@ -45,6 +48,10 @@ services:
     environment:
       - VITE_DOCKER=1
       - BACKEND_INTERNAL_URL=http://api:5002
+      # Match Traefik's published port so HMR's WebSocket targets the right port
+      # (default 80). Without this, HMR connects to :80 and a non-80 stack falls
+      # back to a full page reload on every edit.
+      - VITE_HMR_CLIENT_PORT=${TRAEFIK_PORT:-80}
     depends_on: [api]
     networks: [podokit]
     develop:

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),