@podosoft/podokit 1.4.2 → 1.6.0

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-hook.ts

@@ -1,4 +1,5 @@
 import { createAuthMiddleware } from "better-auth/api";
+import { clientAddressOf } from "../core/client-address";
 import { recordAudit } from "./audit-events";
 import { auditEnabled } from "./audit-enabled";
 
@@ -71,6 +72,6 @@ export const auditAfterHook = createAuthMiddleware(async (ctx) => {
     actorEmail: actor?.email ?? null,
     targetId,
     targetLabel,
-    ip: ctx.headers?.get("x-forwarded-for") ?? null,
+    ip: clientAddressOf(ctx.headers) ?? null,
   });
 });

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

@@ -2,6 +2,7 @@ import { afterEach, describe, expect, mock, test } from "bun:test";
 import { SQL } from "bun";
 import type { QueryRunner } from "typeorm";
 import type { AuthSession } from "../auth/auth.service";
+import { CLIENT_ADDRESS_HEADER } from "../core/client-address";
 import { InitAuditLogs1720300000000 } from "../migrations/1720300000000-InitAuditLogs";
 import { recordAudit, recordAuditLater } from "./audit-events";
 import { AppException } from "@podosoft/podokit-contracts";
@@ -176,6 +177,38 @@ describe("AuditService", () => {
     }
   });
 
+  test("records the address the API resolved, not the caller's forwarded header", async () => {
+    const capture = sqlCapture();
+    const service = new AuditService(capture.sql, { dialect: "postgres", enabled: on });
+    const session: AuthSession = { user: { id: "user-1" }, session: {} };
+    const headers = {
+      "x-forwarded-for": "198.51.100.66, 198.51.100.67",
+      [CLIENT_ADDRESS_HEADER]: "203.0.113.7",
+    };
+    await service.recordRequest("todo.create", new Request("http://localhost/todos", { headers }), session);
+    await service.recordRequest("todo.delete", new Request("http://localhost/todos", {
+      headers: { "x-forwarded-for": "198.51.100.66" },
+    }), session);
+    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

@@ -2,6 +2,7 @@ import type { SQL } from "bun";
 import { AppException } from "@podosoft/podokit-contracts";
 import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
 import type { AuthSession } from "../auth/auth.service";
+import { clientAddressOf } from "../core/client-address";
 import { setAuditRecorder, type AuditEntry } from "./audit-events";
 
 export interface AuditLogView extends AuditEntry {
@@ -165,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;
@@ -412,7 +431,7 @@ export class AuditService {
       targetId: target.id ?? null,
       targetLabel: target.label ?? null,
       metadata: target.metadata ?? null,
-      ip: request.headers.get("x-forwarded-for") ?? null,
+      ip: clientAddressOf(request.headers) ?? null,
     };
     if (options.defer) this.recordLater(entry);
     else await this.record(entry);

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

@@ -8,6 +8,7 @@ import {
   OPENAPI,
   REQUEST_GUARDS,
   REQUEST_IDENTITY,
+  RESOLVED_SESSIONS,
   type AppPlugin,
   type PodokitModule,
   type ServiceKey,
@@ -16,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";
@@ -100,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" },
@@ -158,7 +161,9 @@ export const authModule: PodokitModule = {
     setMailConfigStore(authConfigStore);
     const accessPolicy = services.resolve(ACCESS_POLICY);
     const settings = new SettingsService(database.sql, authConfigStore, publishConfigChanged);
-    const authService = new AuthService(settings, accessPolicy);
+    const authService = new AuthService(settings, accessPolicy, {
+      resolvedSessions: services.resolve(RESOLVED_SESSIONS),
+    });
     services.register(SETTINGS, settings);
     services.register(AUTH_CONFIG, new AuthConfigService(database.sql, database.provider));
     services.register(AUTH, authService, () => authService.close());

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.service.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expect, mock, test } from "bun:test";
-import { AccessPolicy, type RequestIdentity } from "../core/services";
+import { AccessPolicy, ResolvedSessions, type RequestIdentity, type ResolvedSession } from "../core/services";
 import type { SettingsService } from "../settings/settings.service";
 import {
   AuthService,
@@ -21,7 +21,7 @@ function session(
 }
 
 function identityFor(resolver: SessionResolver): RequestIdentity {
-  return createRequestIdentity(new AuthService(settings(false), new AccessPolicy(), resolver));
+  return createRequestIdentity(new AuthService(settings(false), new AccessPolicy(), { resolveSession: resolver }));
 }
 
 describe("AuthService", () => {
@@ -33,12 +33,12 @@ describe("AuthService", () => {
   test("keeps explicitly public routes unauthenticated", async () => {
     const policy = new AccessPolicy();
     policy.register("GET", "/public", "public");
-    const service = new AuthService(settings(false), policy, async () => null);
+    const service = new AuthService(settings(false), policy, { resolveSession: async () => null });
     await expect(service.guard(new Request("http://localhost/public"))).resolves.toBeUndefined();
   });
 
   test("requires a session by default", async () => {
-    const service = new AuthService(settings(false), new AccessPolicy(), async () => null);
+    const service = new AuthService(settings(false), new AccessPolicy(), { resolveSession: async () => null });
     const result = service.guard(new Request("http://localhost/private"));
     await expect(result).rejects.toMatchObject({ code: "AUTH_REQUIRED", statusCode: 401 });
   });
@@ -47,7 +47,7 @@ describe("AuthService", () => {
     const service = new AuthService(
       settings(true),
       new AccessPolicy(),
-      async () => session({ twoFactorEnabled: false }),
+      { resolveSession: async () => session({ twoFactorEnabled: false }) },
     );
     const result = service.guard(new Request("http://localhost/private"));
     await expect(result).rejects.toMatchObject({ code: "TWO_FACTOR_REQUIRED", statusCode: 403 });
@@ -57,13 +57,61 @@ describe("AuthService", () => {
     const service = new AuthService(
       settings(false),
       new AccessPolicy(),
-      async () => session({ role: "user" }),
+      { resolveSession: async () => session({ role: "user" }) },
     );
     await expect(service.requireAdmin(new Request("http://localhost/account/settings")))
       .rejects.toMatchObject({ code: "ADMIN_REQUIRED", statusCode: 403 });
   });
 });
 
+describe("AuthService resolved sessions", () => {
+  const expiresAt = new Date("2030-01-02T03:04:05.000Z");
+
+  function reporting(resolver: SessionResolver): { service: AuthService; reported: ResolvedSession[] } {
+    const resolvedSessions = new ResolvedSessions();
+    const reported: ResolvedSession[] = [];
+    resolvedSessions.listen((resolved) => reported.push(resolved));
+    return {
+      service: new AuthService(settings(false), new AccessPolicy(), { resolveSession: resolver, resolvedSessions }),
+      reported,
+    };
+  }
+
+  test("reports each resolved session once per request, before callers continue", async () => {
+    const resolver = mock(async () => session({}, { token: "session-token", expiresAt }));
+    const { service, reported } = reporting(resolver);
+    const request = new Request("http://localhost/private");
+
+    await service.requireSession(request);
+    expect(reported).toEqual([{ token: "session-token", userId: "user-1", expiresAt }]);
+    await service.session(request);
+    expect(resolver).toHaveBeenCalledTimes(1);
+    expect(reported).toHaveLength(1);
+
+    // A serialized expiry is accepted too.
+    const serialized = reporting(async () => session({}, { token: "t2", expiresAt: expiresAt.toISOString() }));
+    await serialized.service.session(new Request("http://localhost/private"));
+    expect(serialized.reported).toEqual([{ token: "t2", userId: "user-1", expiresAt }]);
+  });
+
+  test("reports nothing without a session, a token, or a valid expiry, and keeps lookup errors", async () => {
+    for (const resolver of [
+      async () => null,
+      async () => session({}, { expiresAt }),
+      async () => session({}, { token: "session-token", expiresAt: "soon" }),
+    ]) {
+      const { service, reported } = reporting(resolver);
+      await service.session(new Request("http://localhost/private"));
+      expect(reported).toEqual([]);
+    }
+    const failing = reporting(async () => {
+      throw new Error("database down");
+    });
+    await expect(failing.service.session(new Request("http://localhost/private"))).rejects.toThrow("database down");
+    expect(failing.reported).toEqual([]);
+  });
+});
+
 describe("createRequestIdentity", () => {
   const request = (): Request => new Request("http://localhost/events");
 

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

@@ -1,5 +1,5 @@
 import { AppException } from "@podosoft/podokit-contracts";
-import type { AccessPolicy, RequestIdentity } from "../core/services";
+import type { AccessPolicy, RequestIdentity, ResolvedSessions } from "../core/services";
 import type { SettingsService } from "../settings/settings.service";
 import { getAuth, refreshForRequest } from "./auth-provider";
 import { rethrowAuthError } from "./database-outage";
@@ -37,19 +37,34 @@ function activeOrganizationOf(session: AuthSession): string | undefined {
   return typeof value === "string" && value !== "" ? value : undefined;
 }
 
+export interface AuthServiceOptions {
+  /** Looks a request's session up; Better Auth's getSession by default. */
+  resolveSession?: SessionResolver;
+  /** Receives every session this service resolves, such as for the rate limiter. */
+  resolvedSessions?: ResolvedSessions;
+}
+
 export class AuthService {
   private readonly sessions = new WeakMap<Request, Promise<AuthSession | null>>();
+  private readonly resolveSession: SessionResolver;
+  private readonly resolvedSessions: ResolvedSessions | undefined;
 
   constructor(
     private readonly settings: SettingsService,
     private readonly accessPolicy: AccessPolicy,
-    private readonly resolveSession: SessionResolver = defaultSessionResolver,
-  ) {}
+    options: AuthServiceOptions = {},
+  ) {
+    this.resolveSession = options.resolveSession ?? defaultSessionResolver;
+    this.resolvedSessions = options.resolvedSessions;
+  }
 
   session(request: Request): Promise<AuthSession | null> {
     const cached = this.sessions.get(request);
     if (cached) return cached;
-    const result = this.resolveSession(request.headers);
+    const result = this.resolveSession(request.headers).then((session) => {
+      if (session) this.report(session);
+      return session;
+    });
     this.sessions.set(request, result);
     return result;
   }
@@ -84,6 +99,13 @@ export class AuthService {
   async close(): Promise<void> {
     await closeAuthDatabase();
   }
+
+  private report(session: AuthSession): void {
+    const { token, expiresAt } = session.session;
+    const expires = expiresAt instanceof Date ? expiresAt : new Date(String(expiresAt));
+    if (!this.resolvedSessions || typeof token !== "string" || Number.isNaN(expires.getTime())) return;
+    this.resolvedSessions.report({ token, userId: session.user.id, expiresAt: expires });
+  }
 }
 
 /** Answers identity questions for other modules from the one session lookup memoized per request. */