@podosoft/podokit 0.8.0 → 0.10.0

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

@@ -0,0 +1,137 @@
+import { expect, test, type Page } 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 };
+
+async function openHydratedLogin(page: Page, redirect?: string): Promise<void> {
+  const query = redirect ? `?redirect=${encodeURIComponent(redirect)}` : "";
+  await page.goto(`/login${query}`);
+  // The form is server-rendered before Svelte attaches its submit handler. Wait
+  // for the client bundle so a fast test click cannot trigger a native reload.
+  await page.waitForLoadState("networkidle");
+}
+
+// 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 openHydratedLogin(page, "/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 openHydratedLogin(page);
+    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 openHydratedLogin(page, "/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/admin-dashboard/module.manifest.json

@@ -59,7 +59,7 @@
     "Set ADMIN_EMAILS in .env (comma-separated). Those emails become admins on sign-up.",
     "Re-run the auth migration to add the admin columns:  npx @better-auth/cli migrate -y --config apps/api/src/auth/auth.ts",
     "Start the app (npm run dev), open /signup, register an ADMIN_EMAILS address, then sign in.",
-    "Admin pages: /admin/users (list, ban, set role, revoke sessions). Everyone: /admin/sessions, /admin/account.",
+    "Admin pages: /admin/users (list, ban, set role, revoke sessions). Signed-in users manage their profile and security at /account; /admin/account remains available in the admin shell. Admin, account, authentication, maintenance, and API responses include X-Robots-Tag: noindex, nofollow by default.",
     "Password reset emails go through the mailer module (installed automatically with auth); in dev without SMTP they are logged to the API console. Configure SMTP in admin settings or via SMTP_* env for production."
   ]
 }

package/dist/templates/modules/api-key-auth/files/tests/api/machine.api.spec.ts

@@ -0,0 +1,25 @@
+import { expect, test } from "@playwright/test";
+
+// api-key auth is machine-to-machine: clients call the backend API directly, not
+// through the browser web proxy (which strips custom headers by design). So this
+// test targets the backend URL (`E2E_API_URL`) and skips when it isn't provided.
+const apiBase = process.env.E2E_API_URL;
+const apiOrigin = { origin: apiBase ?? "" };
+
+// The static service key(s) come from the `API_KEYS` env var; the module ships
+// `dev-key-please-change` as the default in .env.example.
+const KEY = process.env.E2E_API_KEY ?? "dev-key-please-change";
+
+test("api-key auth: a valid key passes, missing/invalid are 401 @smoke", async ({ request }) => {
+  test.skip(!apiBase, "E2E_API_URL (backend base) not set");
+  const ok = await request.get(`${apiBase}/machine/ping`, { headers: { ...apiOrigin, "x-api-key": KEY } });
+  test.skip(ok.status() === 404, "api-key-auth not installed");
+  expect(ok.status()).toBe(200);
+  expect(await ok.json()).toMatchObject({ ok: true, via: "api-key" });
+
+  const missing = await request.get(`${apiBase}/machine/ping`, { headers: apiOrigin });
+  expect(missing.status()).toBe(401);
+
+  const invalid = await request.get(`${apiBase}/machine/ping`, { headers: { ...apiOrigin, "x-api-key": "wrong-key" } });
+  expect(invalid.status()).toBe(401);
+});

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/modules/bullmq/files/tests/api/jobs.api.spec.ts

@@ -0,0 +1,38 @@
+import { expect, test } from "@playwright/test";
+
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const origin = { origin: base };
+
+async function session(playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"]) {
+  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const email = `jobs-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
+  await ctx.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "J" } }).catch(() => undefined);
+  return ctx;
+}
+
+test("bullmq: enqueue a job, read its status, 404 for unknown @smoke", async ({ playwright }) => {
+  const ctx = await session(playwright);
+  const res = await ctx.post("/api/jobs", { data: { text: "hello" } });
+  test.skip(res.status() >= 500, "redis not reachable");
+  expect(res.ok()).toBeTruthy();
+  const { id } = await res.json();
+  expect(typeof id).toBe("string");
+
+  const status = await (await ctx.get(`/api/jobs/${id}`)).json();
+  expect(["waiting", "active", "completed", "delayed", "prioritized", "waiting-children"]).toContain(status.state);
+
+  const missing = await ctx.get(`/api/jobs/does-not-exist-${Date.now()}`);
+  expect(missing.status()).toBe(404);
+
+  // When a worker is running, the demo job completes with an uppercased result;
+  // without a worker it stays waiting (this stays green either way).
+  let final = status.state;
+  const deadline = Date.now() + 6000;
+  while (Date.now() < deadline && final !== "completed") {
+    const s = await (await ctx.get(`/api/jobs/${id}`)).json();
+    final = s.state;
+    if (final === "completed") expect(s.result).toMatchObject({ upper: "HELLO" });
+    else await new Promise((r) => setTimeout(r, 400));
+  }
+  await ctx.dispose();
+});

package/dist/templates/modules/file-upload/files/tests/api/files.api.spec.ts

@@ -0,0 +1,31 @@
+import { expect, test } from "@playwright/test";
+
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const origin = { origin: base };
+
+async function session(playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"]) {
+  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const email = `files-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
+  await ctx.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "F" } }).catch(() => undefined);
+  return ctx;
+}
+
+test("file upload: multipart upload returns a key and url @smoke", async ({ playwright }) => {
+  const ctx = await session(playwright);
+  const res = await ctx.post("/api/files", {
+    multipart: { file: { name: "hello.txt", mimeType: "text/plain", buffer: Buffer.from("hi there") } },
+  });
+  test.skip(res.status() >= 500, "object storage (MinIO/S3) not reachable");
+  expect(res.ok()).toBeTruthy();
+  const body = await res.json();
+  expect(typeof body.key).toBe("string");
+  expect(String(body.url)).toContain("http");
+  await ctx.dispose();
+});
+
+test("file upload: a request with no file is a 400 @smoke", async ({ playwright }) => {
+  const ctx = await session(playwright);
+  const res = await ctx.post("/api/files", { multipart: { notfile: "x" } });
+  expect(res.status()).toBe(400);
+  await ctx.dispose();
+});

package/dist/templates/modules/job-progress/files/tests/api/progress.api.spec.ts

@@ -0,0 +1,22 @@
+import { expect, test } from "@playwright/test";
+
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const origin = { origin: base };
+
+async function session(playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"]) {
+  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const email = `progress-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
+  await ctx.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "P" } }).catch(() => undefined);
+  return ctx;
+}
+
+// The end-to-end progress stream (worker → Redis pub/sub → SSE) needs the worker
+// process running; this asserts the API contract (a job is enqueued).
+test("job-progress: starting a job returns a job id @smoke", async ({ playwright }) => {
+  const ctx = await session(playwright);
+  const res = await ctx.post("/api/progress", { data: { steps: 3 } });
+  test.skip(res.status() >= 500, "redis not reachable");
+  expect(res.ok()).toBeTruthy();
+  expect(typeof (await res.json()).jobId).toBe("string");
+  await ctx.dispose();
+});

package/dist/templates/modules/object-storage-s3/files/tests/api/storage.api.spec.ts

@@ -0,0 +1,28 @@
+import { expect, test } from "@playwright/test";
+
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const origin = { origin: base };
+
+async function session(playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"]) {
+  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const email = `storage-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
+  await ctx.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "S" } }).catch(() => undefined);
+  return ctx;
+}
+
+test("object storage: put, get, and presign @smoke", async ({ playwright }) => {
+  const ctx = await session(playwright);
+  const key = `obj-${Date.now()}`;
+  const put = await ctx.put(`/api/storage/${key}`, { data: { content: "hello world" } });
+  test.skip(put.status() >= 500, "object storage (MinIO/S3) not reachable");
+  expect(put.ok()).toBeTruthy();
+  expect(await put.json()).toMatchObject({ key });
+
+  const got = await (await ctx.get(`/api/storage/${key}`)).json();
+  expect(got).toMatchObject({ key, content: "hello world" });
+
+  const pre = await (await ctx.get(`/api/storage/${key}/presigned`)).json();
+  expect(String(pre.url)).toContain(key);
+
+  await ctx.dispose();
+});

package/dist/templates/modules/rate-limit/files/tests/api/rate-limit.api.spec.ts

@@ -0,0 +1,35 @@
+import { expect, test } from "@playwright/test";
+
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const origin = { origin: base };
+
+// rate-limit installs a global throttler guard (default RATE_LIMIT_MAX requests
+// per RATE_LIMIT_TTL seconds, per client). This module ships a global guard, so
+// it never joins the shared Outer smoke app (it would throttle every other
+// spec); this spec ships with the module and runs against a dedicated app.
+//
+// Honor RATE_LIMIT_MAX when the test runner has it (a dedicated app sets a small
+// value so the window is crossed in a handful of requests); otherwise fall back
+// to the module default and allow a little headroom.
+const limit = Number(process.env.RATE_LIMIT_MAX ?? 100);
+
+test("rate limit: exceeding the window returns 429 @smoke", async ({ playwright }) => {
+  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  // /health is public — no session needed. If the first hit is a 5xx the
+  // throttler's Redis backing isn't reachable; nothing to assert.
+  const probe = await ctx.get("/api/health");
+  test.skip(probe.status() >= 500, "throttler storage (redis) not reachable");
+
+  let seen200 = probe.status() === 200;
+  let got429 = false;
+  for (let i = 0; i < limit + 5 && !got429; i++) {
+    const r = await ctx.get("/api/health");
+    if (r.status() === 200) seen200 = true;
+    if (r.status() === 429) got429 = true;
+  }
+  // A fresh window serves the first requests (200) and rejects once the limit is
+  // crossed (429).
+  expect(seen200).toBe(true);
+  expect(got429).toBe(true);
+  await ctx.dispose();
+});

package/dist/templates/modules/redis/files/tests/api/redis.api.spec.ts

@@ -0,0 +1,30 @@
+import { expect, test } from "@playwright/test";
+
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const origin = { origin: base };
+
+// Self-contained: sign up + sign in a disposable account so the test works when
+// `auth`'s global guard is installed (the common case). Harmless if the API is open.
+async function session(playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"]) {
+  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const email = `redis-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
+  await ctx.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "R" } }).catch(() => undefined);
+  return ctx;
+}
+
+test("redis cache: set, get, and miss @smoke", async ({ playwright }) => {
+  const ctx = await session(playwright);
+  const key = `k-${Date.now()}`;
+  const put = await ctx.put(`/api/cache/${key}`, { data: { value: "hello", ttl: 60 } });
+  test.skip(put.status() >= 500, "redis not reachable");
+  expect(put.ok()).toBeTruthy();
+  expect(await put.json()).toMatchObject({ key });
+
+  const got = await (await ctx.get(`/api/cache/${key}`)).json();
+  expect(got).toMatchObject({ key, value: "hello" });
+
+  const miss = await (await ctx.get(`/api/cache/missing-${Date.now()}`)).json();
+  expect(miss.value).toBeNull();
+
+  await ctx.dispose();
+});

package/dist/templates/modules/sse/files/tests/api/events.api.spec.ts

@@ -0,0 +1,46 @@
+import { expect, test } from "@playwright/test";
+
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const origin = { origin: base };
+
+async function session(playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"]) {
+  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const email = `sse-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
+  await ctx.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "E" } }).catch(() => undefined);
+  return ctx;
+}
+
+test("sse: publish accepts a message @smoke", async ({ playwright }) => {
+  const ctx = await session(playwright);
+  const pub = await ctx.post("/api/events", { data: { message: `hi-${Date.now()}` } });
+  expect(pub.ok()).toBeTruthy();
+  expect(await pub.json()).toMatchObject({ ok: true });
+  await ctx.dispose();
+});
+
+test("sse: a published message is delivered over the event stream @smoke", async ({ playwright }) => {
+  const ctx = await session(playwright);
+  // The stream is behind the auth guard — carry the session cookie on the raw fetch.
+  const cookies = (await ctx.storageState()).cookies.map((c) => `${c.name}=${c.value}`).join("; ");
+  const ac = new AbortController();
+  const stream = await fetch(`${base}/api/events/stream`, { headers: { ...origin, cookie: cookies }, signal: ac.signal }).catch(() => null);
+  test.skip(!stream || !stream.ok || !stream.body, "sse stream not reachable");
+  expect(stream!.headers.get("content-type")).toContain("text/event-stream");
+
+  // Subscriber is attached now; publish, then read until the message arrives.
+  const msg = `sse-${Date.now()}`;
+  await ctx.post("/api/events", { data: { message: msg } });
+
+  const reader = stream!.body!.getReader();
+  const decoder = new TextDecoder();
+  let seen = false;
+  const deadline = Date.now() + 8000;
+  while (Date.now() < deadline && !seen) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    if (decoder.decode(value).includes(msg)) seen = true;
+  }
+  ac.abort();
+  expect(seen).toBe(true);
+  await ctx.dispose();
+});

package/dist/templates/todo/apps/web/src/lib/components/site-runtime.svelte

@@ -0,0 +1,7 @@
+<script lang="ts">
+  // Modules can replace this managed component with global site behavior while
+  // the surrounding route layout remains application-owned.
+  import { ModeWatcher } from "mode-watcher";
+</script>
+
+<ModeWatcher />

package/dist/templates/todo/apps/web/src/lib/server/backend-proxy.ts

@@ -37,7 +37,9 @@ export async function proxyRequest(
   const upstream = await fetch(targetUrl, {
     method: request.method,
     headers,
-    body: hasBody ? await request.text() : undefined,
+    // Preserve multipart uploads and other binary bodies byte-for-byte. Reading
+    // them as text corrupts bytes that are not valid UTF-8 before forwarding.
+    body: hasBody ? await request.arrayBuffer() : undefined,
     redirect: "manual",
   });
 

package/dist/templates/todo/apps/web/src/routes/+layout.svelte

@@ -1,9 +1,9 @@
 <script lang="ts">
   import "../app.css";
-  import { ModeWatcher } from "mode-watcher";
+  import SiteRuntime from "$lib/components/site-runtime.svelte";
 
   let { children } = $props();
 </script>
 
-<ModeWatcher />
+<SiteRuntime />
 {@render children()}

package/dist/templates/todo/dot-gitignore

@@ -12,3 +12,9 @@ build/
 tests/playwright/
 tests/playwright-report/
 tests/test-results/
+playwright/.auth/
+playwright-report/
+test-results/
+
+# local performance reports
+output/lighthouse/

package/dist/templates/todo/infra/k3s/ingress.yaml

@@ -1,8 +1,18 @@
+apiVersion: traefik.io/v1alpha1
+kind: Middleware
+metadata:
+  name: compression
+  namespace: podokit
+spec:
+  compress: {}
+---
 apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
   name: app
   namespace: podokit
+  annotations:
+    traefik.ingress.kubernetes.io/router.middlewares: podokit-compression@kubernetescrd
 spec:
   rules:
     - host: example.com

package/dist/templates/todo/infra/traefik/dynamic.yml

@@ -5,7 +5,11 @@ http:
     web:
       rule: "PathPrefix(`/`)"  # any host on this dedicated proxy -> web
       entryPoints: [web]
+      middlewares: [compression]
       service: web
+  middlewares:
+    compression:
+      compress: {}
   services:
     web:
       loadBalancer: