@podosoft/podokit 1.5.0 → 1.6.1

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

@@ -1,7 +1,6 @@
 import { expect, test, type Page } from "@playwright/test";
 import { ADMIN, USER, anonState } from "../helpers/accounts";
 import { totpCode } from "../helpers/totp";
-import { exclusive } from "../helpers/exclusive";
 
 test.use({ storageState: anonState });
 
@@ -85,62 +84,60 @@ test("two-factor: sign in with an authenticator code from the login page", async
   await expectAccountPage(page);
 });
 
-test("require-2fa: a new sign-up is forced through the enrolment page", async ({ page, playwright }) => {
+test("require-2fa: a new sign-up is forced through the enrolment page", { tag: "@exclusive" }, async ({ page, playwright }) => {
   test.slow();
-  await exclusive("require2fa", async () => {
-    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 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 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 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 toward a protected route lands on the mandatory enrolment page.
+    await openHydratedLogin(page, "/account");
+    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 the regular user into their account page.
+    await expectAccountPage(page);
+
+    // An enrolled user who revisits setup is returned to the same non-admin page.
+    await page.goto("/setup-2fa");
+    await expectAccountPage(page);
+  } 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-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.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();
-
-      // Signing in toward a protected route lands on the mandatory enrolment page.
-      await openHydratedLogin(page, "/account");
-      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 the regular user into their account page.
-      await expectAccountPage(page);
-
-      // An enrolled user who revisits setup is returned to the same non-admin page.
-      await page.goto("/setup-2fa");
-      await expectAccountPage(page);
-    } 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.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();
-    }
-  });
+      expect(status).toBe(200);
+    }).toPass({ timeout: 8000 });
+    await admin.dispose();
+  }
 });
 
 test("account: regenerate backup codes shows a fresh set", async ({ page, playwright }) => {

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

@@ -1,4 +1,5 @@
 import { expect, test } from "../helpers/disposable-users";
+import { ADMIN, USER } from "../helpers/accounts";
 import { ready } from "../helpers/hydration";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
@@ -34,13 +35,13 @@ test("admin sees the user list and can search", async ({ page }) => {
   await ready(page, "/admin/users");
   await expect(page.getByRole("heading", { name: "Users" })).toBeVisible();
   // Search by exact address — robust to pagination as the user count grows.
-  await page.locator("#toolbar-search").fill("admin@example.com");
+  await page.locator("#toolbar-search").fill(ADMIN.email);
   await page.getByRole("button", { name: "Search", exact: true }).click();
-  await expect(page.getByRole("cell", { name: "admin@example.com" })).toBeVisible();
-  await page.locator("#toolbar-search").fill("user@example.com");
+  await expect(page.getByRole("cell", { name: ADMIN.email })).toBeVisible();
+  await page.locator("#toolbar-search").fill(USER.email);
   await page.getByRole("button", { name: "Search", exact: true }).click();
-  await expect(page.getByRole("cell", { name: "user@example.com" })).toBeVisible();
-  await expect(page.getByRole("cell", { name: "admin@example.com" })).toHaveCount(0);
+  await expect(page.getByRole("cell", { name: USER.email })).toBeVisible();
+  await expect(page.getByRole("cell", { name: ADMIN.email })).toHaveCount(0);
 });
 
 test("the user list asks the server for one page at a time", async ({ page }) => {
@@ -63,7 +64,7 @@ test("the user list asks the server for one page at a time", async ({ page }) =>
   expect(query.get("search")).toBe("Admin@Example.com");
   expect(query.get("searchField")).toBe("email");
   expect(query.get("offset")).toBe("0");
-  await expect(page.getByRole("cell", { name: "admin@example.com" })).toBeVisible();
+  await expect(page.getByRole("cell", { name: ADMIN.email })).toBeVisible();
   expect(requested.filter((url) => url.includes("/api/auth/admin/list-users"))).toEqual([]);
 });
 
@@ -78,12 +79,12 @@ test("row menu exposes admin actions", async ({ page }) => {
   const searched = page.waitForResponse((response) => {
     const url = new URL(response.url());
     return url.pathname === "/api/admin/users" &&
-      url.searchParams.get("search") === "user@example.com";
+      url.searchParams.get("search") === USER.email;
   });
-  await page.locator("#toolbar-search").fill("user@example.com");
+  await page.locator("#toolbar-search").fill(USER.email);
   await page.getByRole("button", { name: "Search", exact: true }).click();
   expect((await searched).ok()).toBeTruthy();
-  const row = page.getByRole("row", { name: /user@example.com/ });
+  const row = page.getByRole("row", { name: USER.email });
   await row.getByRole("button").click();
   await expect(page.getByRole("menuitem", { name: "Manage" })).toBeVisible();
   await expect(page.getByRole("menuitem", { name: "Impersonate" })).toBeVisible();

package/dist/templates/modules/admin-dashboard/module.manifest.json

@@ -15,7 +15,12 @@
     "apps/web/src/lib/i18n/locales/**",
     "apps/web/src/lib/i18n/catalogs/app/**",
     "apps/web/src/lib/server/public-paths.ts",
-    "apps/web/src/lib/server/asset-paths.ts"
+    "apps/web/src/lib/server/asset-paths.ts",
+    "tests/helpers/app-accounts.ts",
+    "apps/web/src/lib/server/app-hooks.ts",
+    "apps/web/src/lib/server/non-indexable-paths.ts",
+    "apps/web/src/lib/admin/app-nav.ts",
+    "apps/web/src/lib/admin/app-flags.ts"
   ],
   "managedOverrides": [
     "apps/web/src/lib/components/ui/input/input.svelte",
@@ -119,7 +124,7 @@
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",
       "optional": true,
-      "text": "### admin-dashboard\n- The `(admin)` route group and `admin-sidebar.svelte` are the admin-console shell for `/admin/*` only. Put signed-in product pages in `(app)` or in a separate route group with its own layout; do not place them under `(admin)`.\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Set `ADMIN_EMAILS`, then create or verify the initial account with `{{apiRun}} admin:bootstrap{{apiWorkspaceArg}}`; never commit or persist `ADMIN_BOOTSTRAP_PASSWORD`. When sign-up approval is enabled, self-registered users stay pending until an administrator approves them on `/admin/users`; administrator-created users bypass the queue.\n- Signed-in users can upload, replace, or remove their profile image from `/account` or `/admin/account`. Keep the shared policy visible in custom account UI: PNG, JPEG, or WebP; at most 2 MB and 2048 by 2048 pixels. Use the managed `/api/account/profile-image` endpoints instead of writing directly to storage or `user.image`.\n- `sidebar-user-menu.svelte` is specific to the admin sidebar. For a product shell outside `Sidebar.Provider`, use the managed `<AccountMenu {user} variant=\"identity\" side=\"top\" />` component.\n- Custom protected server layouts must call `requireBackendAvailable(locals)` from `#lib/server/guards.js` before redirecting anonymous users. This preserves sessions and returns 503 when authentication or maintenance policy cannot be checked.\n- Every page except the sign-in flow, `/`, and module pages requires a session, and fails closed with 503 when the API or site settings are unavailable. List the application's public pages (marketing, pricing, legal, `robots.txt`) in `APP_PUBLIC_PATHS` in the app-owned `apps/web/src/lib/server/public-paths.ts`; a prefix covers its subpaths. Do not edit the `PUBLIC_PATHS` list in the managed `guards.ts`.\n- `hooks.server.ts` loads the site settings and the session for pages, page data, form actions, remote functions, and the 404 page. When a `+server.ts` endpoint serves files or feeds that need neither, list its prefix in `APP_ASSET_PATHS` in the app-owned `apps/web/src/lib/server/asset-paths.ts` to skip both API calls; such endpoints see an anonymous `locals.user`, and page requests under the prefix still get the full context.\n- **Every list/table MUST use the shared `#lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `#lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand. For responsive columns, use `hideBelow` and apply the row context's `cellClass(columnKey)` to the matching cell.\n"
+      "text": "### admin-dashboard\n- The `(admin)` route group and `admin-sidebar.svelte` are the admin-console shell for `/admin/*` only. Put signed-in product pages in `(app)` or in a separate route group with its own layout; do not place them under `(admin)`.\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Set `ADMIN_EMAILS`, then create or verify the initial account with `{{apiRun}} admin:bootstrap{{apiWorkspaceArg}}`; never commit or persist `ADMIN_BOOTSTRAP_PASSWORD`. When sign-up approval is enabled, self-registered users stay pending until an administrator approves them on `/admin/users`; administrator-created users bypass the queue.\n- Signed-in users can upload, replace, or remove their profile image from `/account` or `/admin/account`. Keep the shared policy visible in custom account UI: PNG, JPEG, or WebP; at most 2 MB and 2048 by 2048 pixels. Use the managed `/api/account/profile-image` endpoints instead of writing directly to storage or `user.image`.\n- For the signed-in user block in a product shell outside `Sidebar.Provider`, use the managed `<AccountMenu {user} variant=\"identity\" side=\"top\" />`; `sidebar-user-menu.svelte` renders the same menu there and the sidebar menu item inside a `Sidebar.Provider`.\n- Custom protected server layouts must call `requireBackendAvailable(locals)` from `#lib/server/guards.js` before redirecting anonymous users. This preserves sessions and returns 503 when authentication or maintenance policy cannot be checked.\n- Every page except the sign-in flow, `/`, and module pages requires a session, and fails closed with 503 when the API or site settings are unavailable. List the application's public pages (marketing, pricing, legal, `robots.txt`) in `APP_PUBLIC_PATHS` in the app-owned `apps/web/src/lib/server/public-paths.ts`; a prefix covers its subpaths. Do not edit the `PUBLIC_PATHS` list in the managed `guards.ts`.\n- `hooks.server.ts` is managed: put request handling of your own (adjusting `event.locals`, extra headers) in `appHandle` of the app-owned `apps/web/src/lib/server/app-hooks.ts`, which runs after the runtime context is loaded. Add admin sidebar entries to `APP_ADMIN_NAV` in the app-owned `apps/web/src/lib/admin/app-nav.ts`, Settings switches for the API's `APP_FLAG_DEFAULTS` to `APP_FLAG_SETTINGS` in the app-owned `apps/web/src/lib/admin/app-flags.ts`, and private page prefixes that must send `X-Robots-Tag: noindex` to `APP_NON_INDEXABLE_PATHS` in the app-owned `apps/web/src/lib/server/non-indexable-paths.ts`; never edit `admin-sidebar.svelte` or `search-indexing.ts`.\n- `hooks.server.ts` loads the site settings and the session for pages, page data, form actions, remote functions, and the 404 page. When a `+server.ts` endpoint serves files or feeds that need neither, list its prefix in `APP_ASSET_PATHS` in the app-owned `apps/web/src/lib/server/asset-paths.ts` to skip both API calls; such endpoints see an anonymous `locals.user`, and page requests under the prefix still get the full context.\n- `routes/account`, `routes/setup-2fa`, `routes/(auth)/login`, `routes/(auth)/signup`, and the `routes/(admin)` pages are owned, but their `+page.server.ts` (and the `(admin)` layout load) stay managed. Keep the owned page passing `data` to the managed component (for example `<AccountPage {data} />`) and keep its own chrome; never move a managed load's fields into the owned page or edit the managed load.\n- **Every list/table MUST use the shared `#lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `#lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand. For responsive columns, use `hideBelow` and apply the row context's `cellClass(columnKey)` to the matching cell.\n"
     },
     {
       "file": "apps/api/src/app.ts",

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit.module.ts

@@ -29,7 +29,11 @@ export const auditModule: PodokitModule = {
       retention: { days: parseRetentionDays(process.env.AUDIT_LOG_RETENTION_DAYS) },
     });
     services.register(AUDIT, audit, () => audit.close());
-    services.onStart(() => audit.connect());
+    services.onStart(() => {
+      audit.connect();
+      // Not awaited: the toggle read may wait for the database, which startup does not.
+      void audit.warnIfDisabled();
+    });
   },
   plugin: auditPlugin,
 };

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit.service.spec.ts

@@ -192,6 +192,23 @@ describe("AuditService", () => {
     expect(capture.batches.map((batch) => batch[0]?.ip)).toEqual(["203.0.113.7", null]);
   });
 
+  test("warns once at startup when the toggle is off", async () => {
+    const warnings: string[] = [];
+    const logger: AuditLogger = { warn: (_details, message) => warnings.push(message) };
+    const sql = await sqliteDatabase();
+    await new AuditService(sql, { dialect: "sqlite", enabled: on, logger }).warnIfDisabled();
+    await new AuditService(sql, {
+      dialect: "sqlite",
+      enabled: () => Promise.reject(new Error("store down")),
+      logger,
+    }).warnIfDisabled();
+    expect(warnings).toEqual([]);
+    await new AuditService(sql, { dialect: "sqlite", enabled: off, logger }).warnIfDisabled();
+    expect(warnings).toEqual([
+      "Audit log is off; no audit entries are recorded until it is turned on in the admin Settings",
+    ]);
+  });
+
   test("a failing toggle read never breaks the caller", async () => {
     const sql = await sqliteDatabase();
     const service = new AuditService(sql, {

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit.service.ts

@@ -166,6 +166,24 @@ export class AuditService {
     if (this.retention.days > 0 && !this.pruneTimer && !this.pruning) this.schedulePrune(0);
   }
 
+  /**
+   * Logs one warning when the toggle is off, because every write is then skipped
+   * without a trace. A failing toggle read counts as on, as it does for writes.
+   */
+  async warnIfDisabled(): Promise<void> {
+    let enabled: boolean;
+    try {
+      enabled = await this.enabled();
+    } catch {
+      return;
+    }
+    if (enabled) return;
+    this.logger?.warn(
+      { AUDIT_LOG_ENABLED: process.env.AUDIT_LOG_ENABLED ?? null },
+      "Audit log is off; no audit entries are recorded until it is turned on in the admin Settings",
+    );
+  }
+
   /** Stops pruning and the registry, then writes the queue. */
   async close(): Promise<void> {
     this.closed = true;

package/dist/templates/modules/audit-log/module.manifest.json

@@ -4,8 +4,9 @@
   "requires": ["auth"],
   "targetApp": "api",
   "env": [
-    "# audit-log: managed on the admin Settings page, stored in the DB,",
-    "# and applied without restart. This environment value is the fallback.",
+    "# audit-log: on unless switched off. Managed on the admin Settings page,",
+    "# stored in the DB, and applied without restart; this value applies until an",
+    "# administrator saves the setting. Set it to false to start with the log off.",
     "AUDIT_LOG_ENABLED=true",
     "# audit-log: delete entries older than this many days. Unset or 0 keeps them",
     "# forever; set it only when your retention policy requires deleting them.",
@@ -31,6 +32,17 @@
       "file": "apps/api/src/auth/auth.ts",
       "marker": "// podokit:end:auth-hooks",
       "text": "hooks.after = auditAfterHook;"
+    },
+    {
+      "file": "infra/k3s/configmap.yaml",
+      "marker": "# podokit:end:runtime-config",
+      "text": "AUDIT_LOG_ENABLED: \"true\"",
+      "optional": true
+    },
+    {
+      "file": "apps/api/src/auth/auth-config-store.ts",
+      "marker": "// podokit:end:auth-config-defaults",
+      "text": "auditLog: true,"
     }
   ],
   "instructions": [
@@ -39,6 +51,6 @@
     "List entries newest first (admin session required): curl -i -b cookies.txt 'localhost:5002/audit-logs?limit=50' and pass the X-Next-Cursor header back as ?cursor= for the next page"
   ],
   "dependencies": {
-    "@podosoft/podokit-auth": "^0.5.0"
+    "@podosoft/podokit-auth": "^0.6.0"
   }
 }

package/dist/templates/modules/auth/files/apps/api/src/auth/auth-app-name.spec.ts

@@ -0,0 +1,21 @@
+import { describe, expect, test } from "bun:test";
+import { envAuthConfig } from "@podosoft/podokit-auth";
+import { buildAuth } from "./auth";
+
+interface PluginWithOptions {
+  id: string;
+  options?: { rpName?: string; issuer?: string };
+}
+
+function plugin(instance: ReturnType<typeof buildAuth>, id: string): PluginWithOptions | undefined {
+  return (instance.options.plugins as PluginWithOptions[]).find((candidate) => candidate.id === id);
+}
+
+describe("auth app name", () => {
+  test("names the app in Better Auth, the TOTP issuer, and the passkey prompt", () => {
+    const instance = buildAuth({ ...envAuthConfig(), appName: "Acme Cloud" });
+    expect(instance.options.appName).toBe("Acme Cloud");
+    expect(plugin(instance, "two-factor")?.options?.issuer).toBe("Acme Cloud");
+    expect(plugin(instance, "passkey")?.options?.rpName).toBe("Acme Cloud");
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/auth/auth-config-store.ts

@@ -1,14 +1,26 @@
-import { createConfigStore, type ConfigStore } from "@podosoft/podokit-auth";
+import { createConfigStore, type AuthConfigDefaults, type ConfigStore } from "@podosoft/podokit-auth";
 import { flagsFrom } from "../settings/flag-defaults";
 import { readAppSettings, readAuthConfig, readConfigVersions } from "./db";
 import { signupOpenFrom } from "./feature-gate";
 
+/** Values used when neither the auth_config table nor the environment sets one.
+ *  Other PodoKit modules add theirs below the marker. */
+export const AUTH_CONFIG_DEFAULTS: AuthConfigDefaults = {
+  appName: "{{projectName}}",
+  // podokit:begin:auth-config-defaults
+  // podokit:end:auth-config-defaults
+};
+
 /** A store over this app's auth_config and app_setting tables. */
 export function createAuthConfigStore(): ConfigStore {
   return createConfigStore({
     list: readAuthConfig,
     listSettings: readAppSettings,
     versions: readConfigVersions,
+  }, {
+    defaults: AUTH_CONFIG_DEFAULTS,
+    // The site name from the admin Settings, when the admin dashboard stores one.
+    appNameSetting: "site.name",
   });
 }
 

package/dist/templates/modules/auth/files/apps/api/src/auth/auth-environment.ts

@@ -13,6 +13,11 @@ export function authSecret(): string {
   return resolved;
 }
 
+/** A host that only this machine reaches, where plain HTTP exposes nothing. */
+function isLoopbackHost(hostname: string): boolean {
+  return hostname === "localhost" || hostname === "[::1]" || /^127(?:\.\d{1,3}){3}$/.test(hostname);
+}
+
 export function authBaseUrl(): string {
   const value = process.env.BETTER_AUTH_URL?.trim();
   if (process.env.NODE_ENV === "production" && !value) {
@@ -25,8 +30,10 @@ export function authBaseUrl(): string {
   } catch {
     throw new Error("BETTER_AUTH_URL must be a valid URL");
   }
-  if (process.env.NODE_ENV === "production" && url.protocol !== "https:") {
-    throw new Error("BETTER_AUTH_URL must use HTTPS in production");
+  // A loopback URL may stay HTTP, for example an API that a desktop shell runs
+  // on 127.0.0.1 in production mode.
+  if (process.env.NODE_ENV === "production" && url.protocol !== "https:" && !isLoopbackHost(url.hostname)) {
+    throw new Error("BETTER_AUTH_URL must use HTTPS in production unless it is a loopback address");
   }
   return resolved;
 }

package/dist/templates/modules/auth/files/apps/api/src/auth/auth-provider.ts

@@ -1,10 +1,11 @@
-import type { AuthConfig } from "@podosoft/podokit-auth";
+import { envAuthConfig, type AuthConfig } from "@podosoft/podokit-auth";
 import { validateEnv } from "../config/env.validation";
 import { auth as bootstrapAuth, buildAuth } from "./auth";
-import { authConfigStore } from "./auth-config-store";
+import { AUTH_CONFIG_DEFAULTS, authConfigStore } from "./auth-config-store";
 import { publishConfigChanged } from "./config-events";
 import { answersWithin, checkAuthResponse } from "./database-outage";
 import { authDatabaseReachable } from "./db";
+import { createSchemaRecheck } from "./schema-recheck";
 
 const REFRESH_WAIT_MS = validateEnv(process.env).READINESS_CHECK_TIMEOUT_MS;
 
@@ -16,8 +17,10 @@ const REFRESH_WAIT_MS = validateEnv(process.env).READINESS_CHECK_TIMEOUT_MS;
 // Auth instance. Session tokens remain valid because BETTER_AUTH_SECRET is stable.
 
 let current = bootstrapAuth;
+let currentConfig: AuthConfig = envAuthConfig(AUTH_CONFIG_DEFAULTS); // the bootstrap instance's
 let currentVersion = "env"; // matches envAuthConfig() bootstrap
 let failedVersion: string | null = null;
+const recheckSchema = createSchemaRecheck();
 
 export function getAuth(): typeof bootstrapAuth {
   return current;
@@ -38,6 +41,7 @@ export async function refreshIfStale(): Promise<void> {
   if (config.version === currentVersion || config.version === failedVersion) return;
   try {
     current = buildAuth(config);
+    currentConfig = config;
     currentVersion = config.version;
     failedVersion = null;
   } catch (err) {
@@ -64,7 +68,19 @@ export async function refreshAuthNow(): Promise<void> {
  * current instance serves the request, and the refresh finishes in the background.
  */
 export async function refreshForRequest(): Promise<void> {
-  await answersWithin(refreshIfStale, REFRESH_WAIT_MS);
+  await answersWithin(async () => {
+    await refreshIfStale();
+    await recheckSchema(current, rebuildCurrent);
+  }, REFRESH_WAIT_MS);
+}
+
+/** A new instance of the current configuration, which checks the schema again. */
+function rebuildCurrent(): void {
+  try {
+    current = buildAuth(currentConfig);
+  } catch (err) {
+    console.error("[auth-config] rebuild failed; keeping last-good auth instance:", err instanceof Error ? err.message : err);
+  }
 }
 
 // Stable handler reference the adapter captures once; redispatches per request.

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

@@ -17,6 +17,7 @@ import {
   AuthConfigService,
   type AuthConfigUpdate,
 } from "../auth-config/auth-config.service";
+import { APP_FLAGS } from "../settings/flag-defaults";
 import { FEATURE_FLAGS, SettingsService, type FeatureFlag } from "../settings/settings.service";
 import { authConfigStore } from "./auth-config-store";
 import { getAuth, authRuntime, primeAuth } from "./auth-provider";
@@ -101,6 +102,7 @@ const accountPlugin: AppPlugin = ({ services }) => {
         auditLog: snapshot.auditLog,
         sessionIdleTimeoutMinutes: snapshot.sessionIdleTimeoutMinutes,
         roles: ROLE_NAMES,
+        appFlags: Object.fromEntries(APP_FLAGS.map((flag) => [flag, flags[flag]])),
       };
     }, {
       detail: { tags: ["account"], summary: "Get authentication capabilities" },

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.runtime.spec.ts

@@ -29,7 +29,17 @@ describe("authentication production environment", () => {
     expect(() => authBaseUrl()).toThrow("must be set");
     process.env.BETTER_AUTH_URL = "http://app.example.com";
     expect(() => authBaseUrl()).toThrow("must use HTTPS");
+    process.env.BETTER_AUTH_URL = "http://127.0.0.1.example.com";
+    expect(() => authBaseUrl()).toThrow("must use HTTPS");
     process.env.BETTER_AUTH_URL = "https://app.example.com";
     expect(authBaseUrl()).toBe("https://app.example.com");
   });
+
+  test("lets a loopback production origin stay HTTP", () => {
+    process.env.NODE_ENV = "production";
+    for (const url of ["http://127.0.0.1:5002", "http://localhost:5002", "http://[::1]:5002"]) {
+      process.env.BETTER_AUTH_URL = url;
+      expect(authBaseUrl()).toBe(url);
+    }
+  });
 });

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

@@ -4,7 +4,7 @@ import { twoFactor, haveIBeenPwned, magicLink, emailOTP, username, multiSession,
 import { actionEmail, sendMail } from "../mail/mailer";
 import { sendSms } from "../sms/sms";
 import { assertUserCreationAllowed, createFeatureGate, featureGatePlugin, readSignupOpen, type FeatureGateSettings } from "./feature-gate";
-import { featureFlags, isSignupOpen } from "./auth-config-store";
+import { AUTH_CONFIG_DEFAULTS, featureFlags, isSignupOpen } from "./auth-config-store";
 import { orgAc, orgRoles } from "./org-permissions";
 import { authDatabase } from "./db";
 import { type AuthConfig, envAuthConfig, sessionIdleOptions, SUPPORTED_PROVIDER_IDS } from "@podosoft/podokit-auth";
@@ -59,7 +59,8 @@ export function buildAuth(config: AuthConfig) {
     featureGatePlugin(gateSettings),
     // "Sign out other sessions" revokes every other session, not only the first 100.
     revokeEveryOtherSession(),
-    twoFactor(),
+    // The issuer is the account name authenticator apps show.
+    twoFactor({ issuer: config.appName }),
     magicLink({
       sendMagicLink: async ({ email, url }: { email: string; url: string; token: string }) => {
         await sendMail({
@@ -95,8 +96,8 @@ export function buildAuth(config: AuthConfig) {
     apiKey(),
     // Passwordless sign-in with WebAuthn passkeys. The ceremony runs at the web
     // origin, so expected origins are the CORS origins and rpID is their host.
-    // Change rpName to your product name (shown in the browser passkey prompt).
-    passkey({ rpName: "PodoKit", rpID: new URL(webOrigins[0]).hostname, origin: webOrigins }),
+    // rpName is the name the browser shows in the passkey prompt.
+    passkey({ rpName: config.appName, rpID: new URL(webOrigins[0]).hostname, origin: webOrigins }),
     // Multi-tenant organizations: teams with members, roles, and email invitations.
     organization({
       // Custom member roles (adds "manager") and a parent-organization link so orgs
@@ -201,6 +202,7 @@ export function buildAuth(config: AuthConfig) {
   const session = sessionIdleOptions(config.sessionIdleTimeoutMinutes);
 
   return betterAuth({
+    appName: config.appName,
     database: authDatabase,
     emailAndPassword: {
       enabled: true,
@@ -297,4 +299,4 @@ export function buildAuth(config: AuthConfig) {
 // Bootstrap instance from environment config. Used by the better-auth CLI
 // (`--config auth.ts`) and as the guaranteed last-good fallback. The runtime
 // mount (auth-provider.ts) rebuilds from DB config on top of this.
-export const auth = buildAuth(envAuthConfig());
+export const auth = buildAuth(envAuthConfig(AUTH_CONFIG_DEFAULTS));

package/dist/templates/modules/auth/files/apps/api/src/auth/schema-recheck.spec.ts

@@ -0,0 +1,86 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { betterAuth, type BetterAuthOptions } from "better-auth";
+import { getMigrations } from "better-auth/db/migration";
+import { createSchemaRecheck, isSchemaMismatch, type SchemaCheckedAuth } from "./schema-recheck";
+
+const roots: string[] = [];
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function options(database: Database): BetterAuthOptions {
+  return {
+    database,
+    secret: "schema-recheck-test-secret-with-32-characters",
+    baseURL: "http://localhost:5002",
+    emailAndPassword: { enabled: true },
+    logger: { disabled: true },
+  };
+}
+
+async function signUp(auth: ReturnType<typeof betterAuth>): Promise<unknown> {
+  try {
+    await auth.api.signUpEmail({
+      body: { email: `${crypto.randomUUID()}@example.com`, password: "password123", name: "A" },
+    });
+    return "signed up";
+  } catch (error) {
+    return error;
+  }
+}
+
+function fakeAuth(check: () => Promise<void> | undefined): SchemaCheckedAuth {
+  return { $context: Promise.resolve({ checkSchema: check }) };
+}
+
+describe("schema recheck", () => {
+  it("lets an API that started before the migrations sign users up once another process ran them", async () => {
+    const root = mkdtempSync(join(tmpdir(), "schema-recheck-"));
+    roots.push(root);
+    const file = join(root, "auth.sqlite");
+    const api = new Database(file, { create: true });
+    try {
+      let auth = betterAuth(options(api));
+      expect(isSchemaMismatch(await signUp(auth))).toBe(true);
+
+      // migrate:all runs in a process of its own, with a connection of its own.
+      const migrator = new Database(file);
+      await (await getMigrations(options(migrator))).runMigrations();
+      migrator.close();
+      // Better Auth keeps the mismatch it found.
+      expect(isSchemaMismatch(await signUp(auth))).toBe(true);
+
+      await createSchemaRecheck()(auth, () => { auth = betterAuth(options(api)); });
+      expect(await signUp(auth)).toBe("signed up");
+    } finally {
+      api.close();
+    }
+  });
+
+  it("rebuilds at most once per interval while the mismatch lasts", async () => {
+    let clock = 0;
+    let rebuilds = 0;
+    const recheck = createSchemaRecheck({ intervalMs: 2_000, now: () => clock });
+    const mismatched = fakeAuth(() => Promise.reject(Object.assign(new Error("mismatch"), { code: "SCHEMA_MISMATCH" })));
+    await recheck(mismatched, () => { rebuilds += 1; });
+    clock = 1_999;
+    await recheck(mismatched, () => { rebuilds += 1; });
+    expect(rebuilds).toBe(1);
+    clock = 2_000;
+    await recheck(mismatched, () => { rebuilds += 1; });
+    expect(rebuilds).toBe(2);
+  });
+
+  it("leaves a clean schema and an unreachable database alone", async () => {
+    let rebuilds = 0;
+    const recheck = createSchemaRecheck();
+    await recheck(fakeAuth(() => undefined), () => { rebuilds += 1; });
+    await recheck(fakeAuth(() => Promise.reject(new Error("connect ECONNREFUSED"))), () => { rebuilds += 1; });
+    expect(rebuilds).toBe(0);
+  });
+});