@podosoft/podokit 0.7.0 → 0.9.0

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/dist/templates/todo/AGENTS.md

@@ -67,6 +67,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/todo/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/todo/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "0.7.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": {