@podosoft/podokit 0.12.4 → 0.14.0

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

@@ -3,6 +3,8 @@ import { ready } from "../helpers/hydration";
 
 // admin storageState (project default)
 
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+
 async function saveGeneral(page: Page): Promise<void> {
   const saved = page.waitForResponse(
     (response) => response.url().endsWith("/api/site/settings") && response.request().method() === "PUT",
@@ -12,7 +14,7 @@ async function saveGeneral(page: Page): Promise<void> {
   await expect(page.getByText("General settings saved.").last()).toBeVisible();
 }
 
-test("settings has General and Authentication tabs @smoke", async ({ page }) => {
+test("settings has General and Authentication tabs", async ({ page }) => {
   await ready(page, "/admin/settings");
   await expect(page.getByRole("heading", { name: "Settings" })).toBeVisible();
   await expect(page.getByRole("tab", { name: "General" })).toBeVisible();
@@ -21,13 +23,13 @@ test("settings has General and Authentication tabs @smoke", async ({ page }) =>
   await expect(page.getByLabel("Site name")).toBeVisible();
 });
 
-test("general settings: shows the favicon uploader @smoke", async ({ page }) => {
+test("general settings: shows the favicon uploader", async ({ page }) => {
   await ready(page, "/admin/settings");
   await expect(page.getByText("Browser icon (favicon)")).toBeVisible();
   await expect(page.locator('input[type="file"]')).toBeVisible();
 });
 
-test("general settings: edit the site name, save, and apply live @smoke", async ({ page }) => {
+test("general settings: edit the site name, save, and apply live", async ({ page }) => {
   await ready(page, "/admin/settings");
   const name = page.getByLabel("Site name");
   const original = await name.inputValue();
@@ -40,7 +42,7 @@ test("general settings: edit the site name, save, and apply live @smoke", async
   await saveGeneral(page);
 });
 
-test("settings lists the auth features under the Authentication tab @smoke", async ({ page }) => {
+test("settings lists the auth features under the Authentication tab", async ({ page }) => {
   await ready(page, "/admin/settings");
   await page.getByRole("tab", { name: "Authentication" }).click();
   await expect(page.getByText("Email & password")).toBeVisible();
@@ -51,7 +53,7 @@ test("settings lists the auth features under the Authentication tab @smoke", asy
   await expect(page.getByText("Enabled", { exact: true }).first()).toBeVisible();
 });
 
-test("sidebar: back-to-home link returns to the landing page @smoke", async ({ page }) => {
+test("sidebar: back-to-home link returns to the landing page", async ({ page }) => {
   await ready(page, "/admin/settings");
   // the home link lives in the sidebar footer, above the user menu
   await page.getByRole("link", { name: "Back to home" }).click();
@@ -60,7 +62,7 @@ test("sidebar: back-to-home link returns to the landing page @smoke", async ({ p
   await expect(page.locator("main").first()).toBeVisible();
 });
 
-test("settings is reachable from the sidebar @smoke", async ({ page }) => {
+test("settings is reachable from the sidebar", async ({ page }) => {
   await ready(page, "/admin");
   await page.getByRole("link", { name: "Settings" }).click();
   await expect(page).toHaveURL(/\/admin\/settings/);
@@ -81,7 +83,7 @@ test("admin can toggle a feature flag and it applies live @smoke", async ({ page
   await expect(toggle).toBeChecked();
 });
 
-test("settings: the require-two-factor toggle is available @smoke", async ({ page }) => {
+test("settings: the require-two-factor toggle is available", async ({ page }) => {
   await ready(page, "/admin/settings");
   await page.getByRole("tab", { name: "Authentication" }).click();
   // The policy toggle renders under Authentication; its enforcement is covered by
@@ -89,4 +91,72 @@ test("settings: the require-two-factor toggle is available @smoke", async ({ pag
   // admin session.
   await expect(page.getByRole("switch", { name: "Require two-factor" })).toBeVisible();
   await expect(page.getByRole("switch", { name: "Sign-up approval" })).toBeVisible();
+  await expect(page.getByRole("switch", { name: "Automatic logout" })).toBeVisible();
+});
+
+test("inactive browser sessions are signed out automatically @smoke", async ({ browser, page: adminPage }) => {
+  // Idle sign-out revokes the active server session. Use a dedicated login so
+  // this test cannot invalidate the shared admin storageState used by later specs.
+  const context = await browser.newContext({ baseURL: base });
+  const page = await context.newPage();
+  const email = `idle-admin-${Date.now()}@example.com`;
+  let signOutRequests = 0;
+  let userId = "";
+  try {
+    const created = await adminPage.request.post("/api/auth/admin/create-user", {
+      headers: { origin: base },
+      data: { email, password: "Podokit3e-Str0ng!pw", name: "Idle Admin", role: "admin" },
+    });
+    expect(created.ok()).toBeTruthy();
+    userId = ((await created.json()).user?.id ?? "") as string;
+    expect(userId).toBeTruthy();
+
+    const signIn = await context.request.post("/api/auth/sign-in/email", {
+      headers: { origin: base },
+      data: { email, password: "Podokit3e-Str0ng!pw" },
+    });
+    expect(signIn.ok()).toBeTruthy();
+
+    const configured = await context.request.put("/api/account/auth-config", {
+      data: { server: { sessionIdleTimeoutMinutes: 5 } },
+    });
+    expect(configured.ok()).toBeTruthy();
+    await page.route("**/api/auth/sign-out", async (route) => {
+      signOutRequests += 1;
+      await route.fulfill({ status: 200, contentType: "application/json", body: '{"success":true}' });
+    });
+    await page.clock.install();
+
+    try {
+      await ready(page, "/admin");
+      await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
+    } finally {
+      // Keep the loaded page policy at five minutes while restoring the shared
+      // DB policy before the isolated session is revoked.
+      const restored = await context.request.put("/api/account/auth-config", {
+        data: { server: { sessionIdleTimeoutMinutes: null } },
+      });
+      expect(restored.ok()).toBeTruthy();
+    }
+
+    const removed = await adminPage.request.post("/api/auth/admin/remove-user", {
+      headers: { origin: base },
+      data: { userId },
+    });
+    expect(removed.ok()).toBeTruthy();
+    userId = "";
+
+    await page.clock.fastForward(5 * 60_000 + 1_000);
+    await expect.poll(() => signOutRequests).toBe(1);
+    await expect(page).toHaveURL(/\/login\?reason=idle$/);
+    await expect(page.getByTestId("session-timeout-message")).toBeVisible();
+  } finally {
+    if (userId) {
+      await adminPage.request.post("/api/auth/admin/remove-user", {
+        headers: { origin: base },
+        data: { userId },
+      });
+    }
+    await context.close();
+  }
 });

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

@@ -2,7 +2,7 @@ import { expect, test } from "@playwright/test";
 import { ready } from "../helpers/hydration";
 
 // admin storageState (project default)
-test("collapsing the sidebar hides the brand instead of overflowing @smoke", async ({ page }) => {
+test("collapsing the sidebar hides the brand instead of overflowing", async ({ page }) => {
   await ready(page, "/admin");
   const brand = page.getByTestId("sidebar-brand");
   const toggle = page.getByRole("button", { name: "Toggle Sidebar" });

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

@@ -3,7 +3,7 @@ import { ready } from "../helpers/hydration";
 
 // The shared toolbar: filters + search both commit on the Search button; the
 // search field itself is selectable (Email, Name, ...).
-test("users toolbar searches only when Search is pressed @smoke", async ({ page }) => {
+test("users toolbar searches only when Search is pressed", async ({ page }) => {
   await ready(page, "/admin/users");
   const main = page.getByRole("main");
   await page.locator("#toolbar-search").fill("admin@example.com");

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

@@ -17,7 +17,7 @@ async function openHydratedLogin(page: Page, redirect?: string): Promise<void> {
 
 // 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 }) => {
+test("two-factor: sign in with a backup code from the login page", 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");
@@ -55,7 +55,7 @@ test("two-factor: sign in with a backup code from the login page @smoke", async
   await expect(page).toHaveURL(/\/admin\/account/);
 });
 
-test("require-2fa: a new sign-up is forced through the enrolment page @smoke", async ({ page, playwright }) => {
+test("require-2fa: a new sign-up is forced through the enrolment page", 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");
@@ -106,7 +106,7 @@ test("require-2fa: a new sign-up is forced through the enrolment page @smoke", a
   }
 });
 
-test("account: regenerate backup codes shows a fresh set @smoke", async ({ page, playwright }) => {
+test("account: regenerate backup codes shows a fresh set", 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");

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

@@ -51,7 +51,7 @@ test("create rejects mismatched passwords", async ({ page }) => {
   await expect(dialog.getByText("Passwords do not match")).toBeVisible();
 });
 
-test("manage: edit profile name @smoke", async ({ page }) => {
+test("manage: edit profile name", async ({ page }) => {
   await ready(page, "/admin/users");
   const email = `ui-edit-${Date.now()}@example.com`;
   await seedUser(page, email);

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

@@ -3,7 +3,7 @@ import { ready } from "../helpers/hydration";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 
-test("admin can create a user with a custom role @smoke", async ({ page }) => {
+test("admin can create a user with a custom role", async ({ page }) => {
   await ready(page, "/admin/users");
   await page.getByRole("button", { name: "Add user" }).click();
   const role = page.locator("#c-role");
@@ -24,7 +24,7 @@ test("admin can create a user with a custom role @smoke", async ({ page }) => {
   await expect(page.getByRole("cell", { name: email })).toBeVisible();
 });
 
-test("admin sees the user list and can search @smoke", async ({ page }) => {
+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.
@@ -37,7 +37,7 @@ test("admin sees the user list and can search @smoke", async ({ page }) => {
   await expect(page.getByRole("cell", { name: "admin@example.com" })).toHaveCount(0);
 });
 
-test("user list shows the joined column @smoke", async ({ page }) => {
+test("user list shows the joined column", async ({ page }) => {
   await ready(page, "/admin/users");
   await expect(page.getByRole("columnheader", { name: "Joined" })).toBeVisible();
 });
@@ -52,7 +52,7 @@ test("row menu exposes admin actions", async ({ page }) => {
   await expect(page.getByRole("menuitem", { name: "Impersonate" })).toBeVisible();
 });
 
-test("admin can approve a pending registration from the user list @smoke", async ({ page }) => {
+test("admin can approve a pending registration from the user list", async ({ page }) => {
   const email = `pending-ui-${Date.now()}@example.com`;
   const created = await page.request.post("/api/auth/admin/create-user", {
     headers: { origin: base },

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

@@ -4,7 +4,7 @@ import { ready } from "../helpers/hydration";
 
 test.use({ storageState: anonState });
 
-test("verify-email renders the resend form with the address prefilled @smoke", async ({ page }) => {
+test("verify-email renders the resend form with the address prefilled", 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();

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

@@ -1,6 +1,7 @@
 {
+  "manifestVersion": 2,
   "name": "admin-dashboard",
-  "description": "Admin dashboard UI (SvelteKit + shadcn-svelte): login/signup/password-reset, a sidebar shell, and user + session management via the better-auth admin plugin. Requires auth.",
+  "description": "Admin console UI (SvelteKit + shadcn-svelte): the `(admin)` route group and `admin-sidebar.svelte` are reserved for `/admin/*`; put protected product pages in `(app)` or their own guarded layout. Requires auth.",
   "requires": [
     "auth",
     "object-storage-s3"
@@ -10,21 +11,22 @@
     "qrcode": "^1.5.4"
   },
   "devDependencies": {
-    "@types/qrcode": "^1.5.5",
-    "@types/multer": "^1.4.12"
+    "@types/qrcode": "^1.5.5"
   },
   "ownedGlobs": [
     "apps/web/src/lib/i18n/locales/**",
     "apps/web/src/lib/i18n/catalogs/app/**"
   ],
   "managedOverrides": [
+    "apps/web/src/lib/components/ui/input/input.svelte",
     "apps/web/src/routes/(app)/+layout.server.ts",
-    "apps/web/src/routes/(app)/admin/account/+page.server.ts",
-    "apps/web/src/routes/(app)/admin/audit/+page.server.ts",
-    "apps/web/src/routes/(app)/admin/organizations/+page.server.ts",
-    "apps/web/src/routes/(app)/admin/sessions/+page.server.ts",
-    "apps/web/src/routes/(app)/admin/settings/+page.server.ts",
-    "apps/web/src/routes/(app)/admin/users/+page.server.ts",
+    "apps/web/src/routes/(admin)/+layout.server.ts",
+    "apps/web/src/routes/(admin)/admin/account/+page.server.ts",
+    "apps/web/src/routes/(admin)/admin/audit/+page.server.ts",
+    "apps/web/src/routes/(admin)/admin/organizations/+page.server.ts",
+    "apps/web/src/routes/(admin)/admin/sessions/+page.server.ts",
+    "apps/web/src/routes/(admin)/admin/settings/+page.server.ts",
+    "apps/web/src/routes/(admin)/admin/users/+page.server.ts",
     "apps/web/src/routes/(auth)/login/+page.server.ts",
     "apps/web/src/routes/(auth)/signup/+page.server.ts",
     "apps/web/src/routes/account/+page.server.ts",
@@ -32,6 +34,12 @@
   ],
   "packageOverlays": {
     "api": {
+      "dependencies": {
+        "image-size": "^2.0.2"
+      },
+      "devDependencies": {
+        "@types/multer": "^1.4.12"
+      },
       "scripts": {
         "admin:bootstrap": "node scripts/bootstrap-admin.mjs"
       }
@@ -41,7 +49,52 @@
     "# admin-dashboard: emails auto-promoted to the admin role on sign-up (comma-separated)",
     "ADMIN_EMAILS=admin@example.com"
   ],
+  "migrations": [
+    {
+      "id": "admin-route-group",
+      "moves": [
+        {
+          "from": "apps/web/src/routes/(app)/+layout.svelte",
+          "to": "apps/web/src/routes/(admin)/+layout.svelte"
+        },
+        {
+          "from": "apps/web/src/routes/(app)/admin",
+          "to": "apps/web/src/routes/(admin)/admin"
+        },
+        {
+          "from": "apps/web/src/lib/components/app-sidebar.svelte",
+          "to": "apps/web/src/lib/components/admin-sidebar.svelte"
+        }
+      ],
+      "replacements": [
+        {
+          "path": "apps/web/src/routes/(admin)/+layout.svelte",
+          "from": "AppSidebar",
+          "to": "AdminSidebar",
+          "expected": 2
+        },
+        {
+          "path": "apps/web/src/routes/(admin)/+layout.svelte",
+          "from": "$lib/components/app-sidebar.svelte",
+          "to": "$lib/components/admin-sidebar.svelte",
+          "expected": 1
+        }
+      ]
+    }
+  ],
   "inject": [
+    {
+      "file": "apps/web/src/routes/+page.svelte",
+      "marker": "// podokit:end:landing-imports",
+      "optional": true,
+      "text": "import { page } from \"$app/state\";\n  import AccountMenu from \"$lib/components/account-menu.svelte\";\n  import LanguageSwitch from \"$lib/components/language-switch.svelte\";\n  import ThemeToggle from \"$lib/components/theme-toggle.svelte\";"
+    },
+    {
+      "file": "apps/web/src/routes/+page.svelte",
+      "marker": "<!-- podokit:end:landing-actions -->",
+      "optional": true,
+      "text": "<header class=\"flex items-center justify-end gap-2 p-4\">\n  <LanguageSwitch />\n  <ThemeToggle />\n  <AccountMenu user={page.data.user ?? null} />\n</header>"
+    },
     {
       "file": "apps/api/src/auth/auth.ts",
       "marker": "// podokit:end:auth-imports",
@@ -66,24 +119,34 @@
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",
       "optional": true,
-      "text": "### admin-dashboard\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Set `ADMIN_EMAILS`, then create or verify the initial account with `npm run admin:bootstrap -w <app>-api`; 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- Custom protected server layouts must call `requireBackendAvailable(locals)` from `$lib/server/guards` before redirecting anonymous users. This preserves sessions and returns 503 when authentication or maintenance policy cannot be checked.\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.\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 `npm run admin:bootstrap -w <app>-api`; 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- Custom protected server layouts must call `requireBackendAvailable(locals)` from `$lib/server/guards` before redirecting anonymous users. This preserves sessions and returns 503 when authentication or maintenance policy cannot be checked.\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.\n"
     },
     {
       "file": "apps/api/src/app.module.ts",
       "marker": "// podokit:end:imports",
       "text": "import { SiteSettingsModule } from \"./site-settings/site-settings.module\";"
     },
+    {
+      "file": "apps/api/src/app.module.ts",
+      "marker": "// podokit:end:imports",
+      "text": "import { ProfileImageModule } from \"./profile-image/profile-image.module\";"
+    },
     {
       "file": "apps/api/src/app.module.ts",
       "marker": "// podokit:end:module-imports",
       "text": "SiteSettingsModule,"
+    },
+    {
+      "file": "apps/api/src/app.module.ts",
+      "marker": "// podokit:end:module-imports",
+      "text": "ProfileImageModule,"
     }
   ],
   "instructions": [
     "Set ADMIN_EMAILS in .env (comma-separated). After building and migrating, inject ADMIN_BOOTSTRAP_EMAIL and ADMIN_BOOTSTRAP_PASSWORD for one command only, then run npm run admin:bootstrap -w <app>-api. The command creates a verified, approved admin or safely verifies an existing one.",
     "Re-run the auth migration to add the admin and sign-up approval columns:  npx @better-auth/cli migrate -y --config apps/api/src/auth/auth.ts",
     "Remove ADMIN_BOOTSTRAP_PASSWORD from the environment after bootstrap. Keep ADMIN_EMAILS so matching future sign-ups are promoted consistently.",
-    "Admin pages: /admin/users (list, approve pending registrations, 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.",
+    "Admin pages: /admin/users (list, approve pending registrations, ban, set role, revoke sessions). Signed-in users manage their profile, profile image, and security at /account; /admin/account remains available in the admin shell. Profile images accept PNG, JPEG, and WebP up to 2 MB and 2048 by 2048 pixels. 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/audit-log/module.manifest.json

@@ -40,6 +40,6 @@
     "List recent entries (admin session required):  curl -b cookies.txt localhost:5002/audit-logs"
   ],
   "dependencies": {
-    "@podosoft/podokit-auth": "^0.2.0"
+    "@podosoft/podokit-auth": "^0.3.0"
   }
 }

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

@@ -6,13 +6,9 @@ import { ApiTags } from "@nestjs/swagger";
 import { FEATURE_FLAGS, SettingsService, type FeatureFlag } from "../settings/settings.service";
 import { ROLE_NAMES } from "../auth/permissions";
 import { auth } from "../auth/auth";
-import { pool } from "../auth/db";
-import { createConfigStore } from "@podosoft/podokit-auth";
+import { authConfigStore } from "../auth/auth-config-store";
 import type { Capabilities } from "@podosoft/podokit-contracts";
 
-// Reads OAuth/server-toggle state (DB-first, env fallback) for capabilities.
-const configStore = createConfigStore(pool);
-
 function isAdmin(session: UserSession): boolean {
   const role = session.user?.role;
   const roles = Array.isArray(role) ? role : (role ?? "").split(",").map((r: string) => r.trim());
@@ -45,7 +41,7 @@ export class AccountController {
     const flags = this.settings.flags();
     // OAuth providers + server-enforced toggles are DB-backed (env fallback) and
     // applied live, so read them from the config store rather than process.env.
-    const snapshot = await configStore.capabilitiesSnapshot();
+    const snapshot = await authConfigStore.capabilitiesSnapshot();
     return {
       twoFactor: flags.twoFactor,
       magicLink: flags.magicLink,
@@ -63,6 +59,7 @@ export class AccountController {
       signupApprovalRequired: snapshot.requireSignupApproval,
       passwordBreachCheck: snapshot.passwordBreachCheck,
       auditLog: snapshot.auditLog,
+      sessionIdleTimeoutMinutes: snapshot.sessionIdleTimeoutMinutes,
       roles: ROLE_NAMES,
     };
   }

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

@@ -0,0 +1,6 @@
+import { createConfigStore } from "@podosoft/podokit-auth";
+import { pool } from "./db";
+
+// One process-wide store keeps the auth runtime and capabilities endpoint on the
+// same cache snapshot. Admin writes invalidate this store before rebuilding auth.
+export const authConfigStore = createConfigStore(pool);

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

@@ -1,6 +1,5 @@
 import { auth as bootstrapAuth, buildAuth } from "./auth";
-import { pool } from "./db";
-import { createConfigStore } from "@podosoft/podokit-auth";
+import { authConfigStore } from "./auth-config-store";
 
 // Runtime auth instance that rebuilds when the DB config changes, so admin edits
 // (OAuth credentials, SMTP, server-enforced toggles) apply WITHOUT a restart.
@@ -12,7 +11,6 @@ import { createConfigStore } from "@podosoft/podokit-auth";
 // current instance too. The guard/session behavior is unchanged (session tokens are
 // signed with the stable BETTER_AUTH_SECRET; trustedOrigins is baked into every build).
 
-const store = createConfigStore(pool);
 const TTL_MS = 3_000;
 
 let current = bootstrapAuth;
@@ -32,7 +30,7 @@ export async function refreshIfStale(): Promise<void> {
   checkedAt = Date.now();
   let latest: string;
   try {
-    latest = await store.currentVersion();
+    latest = await authConfigStore.currentVersion();
   } catch {
     return; // DB blip — keep serving the last-good instance
   }
@@ -40,7 +38,7 @@ export async function refreshIfStale(): Promise<void> {
   if (inflight) return inflight;
   inflight = (async () => {
     try {
-      const config = await store.load();
+      const config = await authConfigStore.load();
       current = buildAuth(config);
       currentVersion = config.version;
     } catch (err) {
@@ -52,6 +50,15 @@ export async function refreshIfStale(): Promise<void> {
   return inflight;
 }
 
+/** Apply a successful in-process admin write before the response is returned. */
+export async function refreshAuthNow(): Promise<void> {
+  authConfigStore.invalidate();
+  checkedAt = 0;
+  // Force a rebuild even if two writes receive the same millisecond timestamp.
+  currentVersion = `stale:${Date.now()}`;
+  await refreshIfStale();
+}
+
 // Stable handler reference the adapter captures once; redispatches per request.
 const dynamicHandler: typeof bootstrapAuth.handler = async (request) => {
   await refreshIfStale();

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

@@ -6,11 +6,12 @@ import { sendSms } from "../sms/sms";
 import { assertUserCreationAllowed, createFeatureGate, createSignupOpenCheck } from "./feature-gate";
 import { orgAc, orgRoles } from "./org-permissions";
 import { pool } from "./db";
-import { type AuthConfig, envAuthConfig, SUPPORTED_PROVIDER_IDS } from "@podosoft/podokit-auth";
+import { type AuthConfig, envAuthConfig, sessionIdleOptions, SUPPORTED_PROVIDER_IDS } from "@podosoft/podokit-auth";
 import { apiKey } from "@better-auth/api-key";
 import { passkey } from "@better-auth/passkey";
 import { oauthProvider } from "@better-auth/oauth-provider";
 import { SIGNUP_APPROVAL_REQUIRED } from "@podosoft/podokit-contracts";
+import { runUserDeletedHandlers } from "./user-delete-handlers";
 // podokit:begin:auth-imports
 // podokit:end:auth-imports
 
@@ -176,6 +177,8 @@ export function buildAuth(config: AuthConfig) {
   // podokit:begin:auth-hooks
   // podokit:end:auth-hooks
 
+  const session = sessionIdleOptions(config.sessionIdleTimeoutMinutes);
+
   return betterAuth({
     database: pool,
     emailAndPassword: {
@@ -208,6 +211,7 @@ export function buildAuth(config: AuthConfig) {
       },
     },
     socialProviders: buildSocial(config),
+    ...(session ? { session } : {}),
     plugins,
     hooks,
     secret: process.env.BETTER_AUTH_SECRET ?? "change-me-in-production-min-32-characters",
@@ -256,7 +260,10 @@ export function buildAuth(config: AuthConfig) {
         },
       },
       // Self-service account deletion — admin-toggleable (auth_config), applied live.
-      deleteUser: { enabled: config.allowDelete },
+      deleteUser: {
+        enabled: config.allowDelete,
+        afterDelete: runUserDeletedHandlers,
+      },
     },
     databaseHooks,
     // podokit:begin:auth-options

package/dist/templates/modules/auth/files/apps/api/src/auth/user-delete-handlers.spec.ts

@@ -0,0 +1,42 @@
+import { afterEach, describe, expect, it, jest } from "@jest/globals";
+import {
+  registerUserDeletedHandler,
+  runUserDeletedHandlers,
+  type UserDeletedHandler,
+} from "./user-delete-handlers";
+
+describe("user deletion handlers", () => {
+  const unregister: Array<() => void> = [];
+
+  afterEach(() => {
+    for (const remove of unregister.splice(0)) remove();
+    jest.restoreAllMocks();
+  });
+
+  function register(handler: UserDeletedHandler): void {
+    unregister.push(registerUserDeletedHandler(handler));
+  }
+
+  it("runs registered module cleanup with the deleted user", async () => {
+    const handler: UserDeletedHandler = jest.fn(async () => undefined);
+    register(handler);
+    const user = { id: "user-1", image: "/api/profile-images/avatar.png" };
+
+    await runUserDeletedHandlers(user);
+
+    expect(handler).toHaveBeenCalledWith(user);
+  });
+
+  it("does not fail account deletion when one cleanup rejects", async () => {
+    jest.spyOn(console, "error").mockImplementation(() => undefined);
+    register(async () => {
+      throw new Error("storage unavailable");
+    });
+
+    await expect(runUserDeletedHandlers({ id: "user-1" })).resolves.toBeUndefined();
+    expect(console.error).toHaveBeenCalledWith(
+      "Run user deletion cleanup failed",
+      expect.objectContaining({ userId: "user-1", error: "storage unavailable" }),
+    );
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/auth/user-delete-handlers.ts

@@ -0,0 +1,27 @@
+export interface DeletedUser {
+  id: string;
+  image?: string | null;
+}
+
+export type UserDeletedHandler = (user: DeletedUser) => Promise<void>;
+
+const handlers = new Set<UserDeletedHandler>();
+
+/** Register module-owned cleanup that should run after better-auth removes a user. */
+export function registerUserDeletedHandler(handler: UserDeletedHandler): () => void {
+  handlers.add(handler);
+  return () => handlers.delete(handler);
+}
+
+/** Run every cleanup without turning a completed account deletion into an error. */
+export async function runUserDeletedHandlers(user: DeletedUser): Promise<void> {
+  const results = await Promise.allSettled([...handlers].map((handler) => handler(user)));
+  for (const result of results) {
+    if (result.status === "rejected") {
+      console.error("Run user deletion cleanup failed", {
+        userId: user.id,
+        error: result.reason instanceof Error ? result.reason.message : String(result.reason),
+      });
+    }
+  }
+}