@podosoft/podokit 0.12.2 → 0.12.4

package/dist/templates/modules/admin-dashboard/files/apps/web/src/app.d.ts

@@ -20,8 +20,10 @@ declare global {
     interface Locals {
       user: SessionUser | null;
       session: { id: string; impersonatedBy?: string | null } | null;
+      authUnavailable: boolean;
       locale: Locale;
       site: SiteSettings | null;
+      siteUnavailable: boolean;
     }
   }
 }

package/dist/templates/modules/admin-dashboard/files/apps/web/src/hooks.server.ts

@@ -1,8 +1,15 @@
-import type { Handle } from "@sveltejs/kit";
+import { error, type Handle } from "@sveltejs/kit";
 import { serverApiClient } from "$lib/server/api";
 import { resolveLocale } from "$lib/i18n/messages";
 import { applySearchIndexingHeaders } from "$lib/server/search-indexing";
+import { isPublicPath } from "$lib/server/guards";
 import type { SiteSettings } from "$lib/site.svelte";
+import { ApiError } from "@podosoft/podokit-api-client";
+
+function isTemporaryServiceFailure(cause: unknown): boolean {
+  if (!(cause instanceof ApiError)) return true;
+  return cause.statusCode === 408 || cause.statusCode === 429 || cause.statusCode >= 500;
+}
 
 export const handle: Handle = async ({ event, resolve }) => {
   // Static assets and API proxy requests do not render application layouts.
@@ -16,23 +23,46 @@ export const handle: Handle = async ({ event, resolve }) => {
   // Public site settings (branding, locale/timezone defaults, maintenance, …),
   // loaded once here and reused by the layout load. A visitor with no locale
   // cookie falls back to the admin-configured site locale, then the app default.
+  event.locals.siteUnavailable = false;
   let site: SiteSettings | null = null;
   try {
     site = await serverApiClient(event).get<SiteSettings>("/site/settings");
-  } catch {
+  } catch (cause: unknown) {
     site = null;
+    // A request-level 4xx proves that the backend is reachable. In particular,
+    // the require-2FA guard returns 403 until enrolment and must remain able to
+    // redirect the user to /setup-2fa instead of being masked as an outage.
+    event.locals.siteUnavailable = isTemporaryServiceFailure(cause);
   }
   event.locals.site = site;
   event.locals.locale = resolveLocale(event.cookies.get("locale") ?? site?.locale ?? undefined);
+
+  event.locals.user = null;
+  event.locals.session = null;
+  event.locals.authUnavailable = false;
   try {
-    const { data } = await serverApiClient(event).auth.getSession();
-    event.locals.user = (data?.user as App.Locals["user"]) ?? null;
-    event.locals.session = data?.session
-      ? { id: data.session.id, impersonatedBy: (data.session as { impersonatedBy?: string | null }).impersonatedBy ?? null }
-      : null;
+    const { data, error } = await serverApiClient(event).auth.getSession();
+    // Better Auth returns HTTP authentication failures as data/error. A 401 is
+    // a confirmed anonymous session; every other error means that the session
+    // could not be checked and must not be treated as a logout.
+    if (error && error.status !== 401) {
+      event.locals.authUnavailable = true;
+    } else {
+      event.locals.user = (data?.user as App.Locals["user"]) ?? null;
+      event.locals.session = data?.session
+        ? { id: data.session.id, impersonatedBy: (data.session as { impersonatedBy?: string | null }).impersonatedBy ?? null }
+        : null;
+    }
   } catch {
-    event.locals.user = null;
-    event.locals.session = null;
+    // Transport failures do not invalidate the browser's session cookie. A
+    // protected loader will fail closed with 503 until the backend recovers.
+    event.locals.authUnavailable = true;
+  }
+  if (
+    (event.locals.authUnavailable || event.locals.siteUnavailable) &&
+    !isPublicPath(event.url.pathname)
+  ) {
+    error(503, "Service temporarily unavailable");
   }
   const response = await resolve(event, {
     transformPageChunk: ({ html }) =>

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/server/guards.ts

@@ -4,8 +4,34 @@ import { error } from "@sveltejs/kit";
  *  added here (and, later, replaced by a permission check) without touching every
  *  page loader. better-auth stores a user's role(s) as a comma-separated string. */
 const ADMIN_ROLES = ["admin"];
+const PUBLIC_PATHS = [
+  "/",
+  "/login",
+  "/signup",
+  "/forgot-password",
+  "/reset-password",
+  "/verify-email",
+  "/pending-approval",
+  "/maintenance",
+  // Modules add their public (no-session) page prefixes here.
+  // podokit:begin:public-paths
+  // podokit:end:public-paths
+];
 
 type WithRole = { role?: string | null } | null | undefined;
+type BackendAvailability = Pick<App.Locals, "authUnavailable" | "siteUnavailable">;
+
+/** True for routes that may render without a confirmed session or site policy. */
+export function isPublicPath(pathname: string): boolean {
+  return PUBLIC_PATHS.some((path) => pathname === path || (path !== "/" && pathname.startsWith(`${path}/`)));
+}
+
+/** Stop protected loaders when authentication or runtime policy cannot be checked. */
+export function requireBackendAvailable(locals: BackendAvailability): void {
+  if (locals.authUnavailable || locals.siteUnavailable) {
+    error(503, "Service temporarily unavailable");
+  }
+}
 
 /** True when the user holds at least one admin role. */
 export function isAdmin(user: WithRole): boolean {
@@ -16,7 +42,8 @@ export function isAdmin(user: WithRole): boolean {
   return roles.some((r) => ADMIN_ROLES.includes(r));
 }
 
-/** Guard an admin-only loader: throws 403 unless the user holds an admin role. */
-export function requireAdmin(user: WithRole): void {
+/** Guard an admin-only loader after confirming the backend is available. */
+export function requireAdmin(user: WithRole, availability?: BackendAvailability): void {
+  if (availability) requireBackendAvailable(availability);
   if (!isAdmin(user)) error(403, "Admins only");
 }

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(app)/+layout.server.ts

@@ -1,8 +1,11 @@
 import { redirect } from "@sveltejs/kit";
 import type { LayoutServerLoad } from "./$types";
 import type { Capabilities } from "@podosoft/podokit-api-client";
+import { requireBackendAvailable } from "$lib/server/guards";
 
 export const load: LayoutServerLoad = async ({ locals, fetch }) => {
+  requireBackendAvailable(locals);
+
   let capabilities: Capabilities = {
     twoFactor: false,
     providers: [],

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(app)/admin/audit/+page.server.ts

@@ -2,5 +2,5 @@ import type { PageServerLoad } from "./$types";
 import { requireAdmin } from "$lib/server/guards";
 
 export const load: PageServerLoad = ({ locals }) => {
-  requireAdmin(locals.user);
+  requireAdmin(locals.user, locals);
 };

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(app)/admin/organizations/+page.server.ts

@@ -2,5 +2,5 @@ import type { PageServerLoad } from "./$types";
 import { requireAdmin } from "$lib/server/guards";
 
 export const load: PageServerLoad = ({ locals }) => {
-  requireAdmin(locals.user);
+  requireAdmin(locals.user, locals);
 };

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(app)/admin/sessions/+page.server.ts

@@ -2,6 +2,6 @@ import type { PageServerLoad } from "./$types";
 import { requireAdmin } from "$lib/server/guards";
 
 export const load: PageServerLoad = ({ locals }) => {
-  requireAdmin(locals.user);
+  requireAdmin(locals.user, locals);
   return { currentSessionId: locals.session?.id ?? null };
 };

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(app)/admin/settings/+page.server.ts

@@ -14,7 +14,7 @@ export type AuthConfigView = {
 };
 
 export const load: PageServerLoad = async ({ locals, fetch }) => {
-  requireAdmin(locals.user);
+  requireAdmin(locals.user, locals);
   let authConfig: AuthConfigView | null = null;
   try {
     const res = await fetch("/api/account/auth-config");

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(app)/admin/users/+page.server.ts

@@ -2,6 +2,6 @@ import type { PageServerLoad } from "./$types";
 import { requireAdmin } from "$lib/server/guards";
 
 export const load: PageServerLoad = ({ locals }) => {
-  requireAdmin(locals.user);
+  requireAdmin(locals.user, locals);
   return { currentUserId: locals.user!.id };
 };

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/+layout.server.ts

@@ -2,29 +2,13 @@ import type { LayoutServerLoad } from "./$types";
 import { redirect } from "@sveltejs/kit";
 import { safeAuthRedirect } from "$lib/auth-redirect";
 import { loadMessages } from "$lib/i18n/messages";
+import { isPublicPath, requireBackendAvailable } from "$lib/server/guards";
 
 // "/" is a public landing page. Auth pages return signed-in users to their safe
 // requested page, and the admin area requires a session. /maintenance is public
 // so it renders while the rest of the site is held back.
-const PUBLIC_PATHS = [
-  "/",
-  "/login",
-  "/signup",
-  "/forgot-password",
-  "/reset-password",
-  "/verify-email",
-  "/pending-approval",
-  "/maintenance",
-  // Modules add their public (no-session) page prefixes here.
-  // podokit:begin:public-paths
-  // podokit:end:public-paths
-];
 const AUTH_PATHS = ["/login", "/signup", "/forgot-password", "/reset-password"];
 
-function isPublic(pathname: string): boolean {
-  return PUBLIC_PATHS.some((path) => pathname === path || (path !== "/" && pathname.startsWith(`${path}/`)));
-}
-
 export const load: LayoutServerLoad = async (event) => {
   const { locals, url } = event;
   const { pathname } = url;
@@ -32,13 +16,18 @@ export const load: LayoutServerLoad = async (event) => {
   const site = locals.site;
   const isAdmin = locals.user?.role === "admin";
 
+  // Authentication and maintenance policy are both security boundaries. If
+  // either could not be checked, deny protected content without redirecting to
+  // login or modifying the session cookie. Public pages keep their static fallbacks.
+  if (!isPublicPath(pathname)) requireBackendAvailable(locals);
+
   // Maintenance mode holds everyone but admins on a maintenance page. /login and
   // /maintenance stay reachable so an admin can still sign in and turn it off.
   const maintenance = site?.maintenanceMode === "true";
   if (maintenance && !isAdmin && pathname !== "/maintenance" && pathname !== "/login") {
     redirect(303, "/maintenance");
   }
-  if (!maintenance && pathname === "/maintenance") {
+  if (!locals.siteUnavailable && !maintenance && pathname === "/maintenance") {
     redirect(303, "/");
   }
   // Registration closed from the admin Settings: send /signup back to /login.
@@ -50,7 +39,7 @@ export const load: LayoutServerLoad = async (event) => {
   if (locals.user && AUTH_PATHS.includes(pathname)) {
     redirect(303, safeAuthRedirect(url.searchParams.get("redirect")));
   }
-  if (!locals.user && !isPublic(pathname)) {
+  if (!locals.user && !isPublicPath(pathname)) {
     redirect(303, `/login?redirect=${encodeURIComponent(`${pathname}${url.search}`)}`);
   }
   const messages = await loadMessages(locals.locale, site?.locale);

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/setup-2fa/+page.server.ts

@@ -1,9 +1,11 @@
 import { redirect } from "@sveltejs/kit";
 import type { PageServerLoad } from "./$types";
+import { requireBackendAvailable } from "$lib/server/guards";
 
 // The mandatory two-factor enrolment page (reached via the require-2fa gate).
 // Must be signed in; already-enrolled users have nothing to do here.
 export const load: PageServerLoad = ({ locals }) => {
+  requireBackendAvailable(locals);
   if (!locals.user) redirect(302, "/login");
   const user = locals.user as App.Locals["user"] & { twoFactorEnabled?: boolean };
   if (user.twoFactorEnabled) redirect(302, "/admin");

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

@@ -17,6 +17,19 @@
     "apps/web/src/lib/i18n/locales/**",
     "apps/web/src/lib/i18n/catalogs/app/**"
   ],
+  "managedOverrides": [
+    "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/(auth)/login/+page.server.ts",
+    "apps/web/src/routes/(auth)/signup/+page.server.ts",
+    "apps/web/src/routes/account/+page.server.ts",
+    "apps/web/src/routes/setup-2fa/+page.server.ts"
+  ],
   "packageOverlays": {
     "api": {
       "scripts": {
@@ -53,7 +66,7 @@
       "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- **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- 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"
     },
     {
       "file": "apps/api/src/app.module.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "0.12.2",
+  "version": "0.12.4",
   "description": "An opinionated but extensible starter toolkit and CLI for full-stack TypeScript apps with NestJS, SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.",
   "license": "Apache-2.0",
   "repository": {