@podosoft/podokit 0.12.4 → 0.14.0

package/dist/templates/modules/admin-dashboard/files/apps/api/src/profile-image/profile-image.service.spec.ts

@@ -0,0 +1,43 @@
+import { afterAll, afterEach, describe, expect, it, jest } from "@jest/globals";
+import { runUserDeletedHandlers } from "../auth/user-delete-handlers";
+import { StorageService } from "../storage/storage.service";
+import { ProfileImageService } from "./profile-image.service";
+
+jest.mock("../auth/auth-provider", () => ({ getAuth: jest.fn() }));
+
+describe("ProfileImageService account deletion cleanup", () => {
+  const storage = {
+    put: jest.fn(async () => undefined),
+    get: jest.fn(async () => Buffer.alloc(0)),
+    presignedGetUrl: jest.fn(async () => "https://example.com/image"),
+    delete: jest.fn(async () => undefined),
+  };
+  const service = new ProfileImageService(storage as unknown as StorageService);
+
+  service.onModuleInit();
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  afterAll(() => {
+    service.onModuleDestroy();
+  });
+
+  it("deletes a managed image after the account is deleted", async () => {
+    await runUserDeletedHandlers({
+      id: "user-1",
+      image: "/api/profile-images/123e4567-e89b-42d3-a456-426614174000.webp",
+    });
+
+    expect(storage.delete).toHaveBeenCalledWith(
+      "profile-images/123e4567-e89b-42d3-a456-426614174000.webp",
+    );
+  });
+
+  it("does not delete an external identity-provider image", async () => {
+    await runUserDeletedHandlers({ id: "user-1", image: "https://example.com/avatar.png" });
+
+    expect(storage.delete).not.toHaveBeenCalled();
+  });
+});

package/dist/templates/modules/admin-dashboard/files/apps/api/src/profile-image/profile-image.service.ts

@@ -0,0 +1,110 @@
+import { randomUUID } from "node:crypto";
+import { Injectable, Logger, type OnModuleDestroy, type OnModuleInit } from "@nestjs/common";
+import {
+  AppException,
+  PROFILE_IMAGE_NOT_FOUND,
+  type ProfileImageResponse,
+} from "@podosoft/podokit-contracts";
+import { getAuth } from "../auth/auth-provider";
+import { registerUserDeletedHandler } from "../auth/user-delete-handlers";
+import { StorageService } from "../storage/storage.service";
+import { validateProfileImage, type ProfileImageUpload } from "./profile-image.validation";
+
+const FILE_NAME = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.(?:jpg|png|webp)$/;
+const PUBLIC_PREFIX = "/api/profile-images/";
+const STORAGE_PREFIX = "profile-images/";
+
+const CONTENT_TYPES: Record<string, string> = {
+  jpg: "image/jpeg",
+  png: "image/png",
+  webp: "image/webp",
+};
+
+export interface StoredProfileImage {
+  body: Buffer;
+  contentType: string;
+}
+
+@Injectable()
+export class ProfileImageService implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(ProfileImageService.name);
+  private unregisterUserDeleted?: () => void;
+
+  constructor(private readonly storage: StorageService) {}
+
+  onModuleInit(): void {
+    this.unregisterUserDeleted = registerUserDeletedHandler(async (user) => {
+      await this.deleteManagedImage(user.image ?? null);
+    });
+  }
+
+  onModuleDestroy(): void {
+    this.unregisterUserDeleted?.();
+  }
+
+  async upload(
+    currentImage: string | null,
+    file: ProfileImageUpload,
+    headers: Headers,
+  ): Promise<ProfileImageResponse> {
+    const metadata = validateProfileImage(file);
+    const fileName = `${randomUUID()}.${metadata.extension}`;
+    const key = STORAGE_PREFIX + fileName;
+    const image = PUBLIC_PREFIX + fileName;
+
+    await this.storage.put(key, file.buffer, metadata.contentType);
+    try {
+      await getAuth().api.updateUser({ body: { image }, headers });
+    } catch (error: unknown) {
+      await this.deleteKeyBestEffort(key);
+      throw error;
+    }
+    await this.deleteManagedImage(currentImage);
+    return { image };
+  }
+
+  async remove(currentImage: string | null, headers: Headers): Promise<ProfileImageResponse> {
+    await getAuth().api.updateUser({ body: { image: null }, headers });
+    await this.deleteManagedImage(currentImage);
+    return { image: null };
+  }
+
+  async get(fileName: string): Promise<StoredProfileImage> {
+    const key = this.keyFromFileName(fileName);
+    if (!key) {
+      throw new AppException(PROFILE_IMAGE_NOT_FOUND, "Profile image not found.", 404);
+    }
+    try {
+      const extension = fileName.slice(fileName.lastIndexOf(".") + 1);
+      return { body: await this.storage.get(key), contentType: CONTENT_TYPES[extension] ?? "application/octet-stream" };
+    } catch {
+      throw new AppException(PROFILE_IMAGE_NOT_FOUND, "Profile image not found.", 404);
+    }
+  }
+
+  private keyFromFileName(fileName: string): string | null {
+    return FILE_NAME.test(fileName) ? STORAGE_PREFIX + fileName : null;
+  }
+
+  private keyFromPublicUrl(image: string | null): string | null {
+    if (!image?.startsWith(PUBLIC_PREFIX)) return null;
+    return this.keyFromFileName(image.slice(PUBLIC_PREFIX.length));
+  }
+
+  private async deleteManagedImage(image: string | null): Promise<void> {
+    const key = this.keyFromPublicUrl(image);
+    if (key) await this.deleteKeyBestEffort(key);
+  }
+
+  private async deleteKeyBestEffort(key: string): Promise<void> {
+    try {
+      await this.storage.delete(key);
+    } catch (error: unknown) {
+      this.logger.warn({
+        message: "Delete profile image object failed",
+        key,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+}

package/dist/templates/modules/admin-dashboard/files/apps/api/src/profile-image/profile-image.validation.spec.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "@jest/globals";
+import {
+  AppException,
+  PROFILE_IMAGE_DIMENSIONS_INVALID,
+  PROFILE_IMAGE_POLICY,
+  PROFILE_IMAGE_TOO_LARGE,
+  PROFILE_IMAGE_TYPE_INVALID,
+} from "@podosoft/podokit-contracts";
+import { validateProfileImage, type ProfileImageUpload } from "./profile-image.validation";
+
+const PNG = "iVBORw0KGgoAAAANSUhEUgAAAAIAAAADAQMAAACDJEzCAAAAIGNIUk0AAHomAACAhAAA+gAAAIDoAAB1MAAA6mAAADqYAAAXcJy6UTwAAAAGUExURWYzmf///129H+IAAAABYktHRAH/Ai3eAAAAB3RJTUUH6gcVCSUTzXBDTwAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAyNi0wNy0yMVQwOTozNzoxOSswMDowMOuehLIAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMjYtMDctMjFUMDk6Mzc6MTkrMDA6MDCawzwOAAAAKHRFWHRkYXRlOnRpbWVzdGFtcAAyMDI2LTA3LTIxVDA5OjM3OjE5KzAwOjAwzdYd0QAAAAtJREFUCNdjYAABAAAGAAFm9MlsAAAAAElFTkSuQmCC";
+const JPEG = "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgICAgMCAgIDAwMDBAYEBAQEBAgGBgUGCQgKCgkICQkKDA8MCgsOCwkJDRENDg8QEBEQCgwSExIQEw8QEBD/2wBDAQMDAwQDBAgEBAgQCwkLEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBD/wAARCAAKAAoDAREAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAj/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFgEBAQEAAAAAAAAAAAAAAAAAAAYH/8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAwDAQACEQMRAD8AnpuCtAAAf//Z";
+const WEBP = "UklGRjQAAABXRUJQVlA4ICgAAACQAQCdASoCAAMAAgA0JaACdLoAA5gA/vCwN/8bx4FeS7K/1oWg+AAA";
+const TOO_WIDE_PNG = "iVBORw0KGgoAAAANSUhEUgAACAEAAAABAQMAAACfGLePAAAAIGNIUk0AAHomAACAhAAA+gAAAIDoAAB1MAAA6mAAADqYAAAXcJy6UTwAAAAGUExURWYzmf///129H+IAAAABYktHRAH/Ai3eAAAAB3RJTUUH6gcVCScoTk3I6QAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAyNi0wNy0yMVQwOTozOTo0MCswMDowMCgv/7YAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMjYtMDctMjFUMDk6Mzk6NDArMDA6MDBZckcKAAAAKHRFWHRkYXRlOnRpbWVzdGFtcAAyMDI2LTA3LTIxVDA5OjM5OjQwKzAwOjAwDmdm1QAAAAxJREFUGNNjYBjpAAABAgABRf+HpwAAAABJRU5ErkJggg==";
+
+function upload(base64: string, mimetype: string, size?: number): ProfileImageUpload {
+  const buffer = Buffer.from(base64, "base64");
+  return { buffer, mimetype, size: size ?? buffer.length };
+}
+
+function expectAppException(action: () => void, code: string, statusCode = 400): void {
+  try {
+    action();
+    throw new Error("Expected validation to throw");
+  } catch (error: unknown) {
+    expect(error).toBeInstanceOf(AppException);
+    expect(error).toMatchObject({ code, statusCode });
+  }
+}
+
+describe("validateProfileImage", () => {
+  const supported: Array<[string, string, "png" | "jpg" | "webp", number, number]> = [
+    [PNG, "image/png", "png", 2, 3],
+    [JPEG, "image/jpeg", "jpg", 10, 10],
+    [WEBP, "image/webp", "webp", 2, 3],
+  ];
+
+  it.each(supported)("accepts a valid supported image", (base64, mimetype, extension, width, height) => {
+    expect(validateProfileImage(upload(base64, mimetype))).toMatchObject({
+      contentType: mimetype,
+      extension,
+      width,
+      height,
+    });
+  });
+
+  it("rejects a MIME type that does not match the bytes", () => {
+    expectAppException(
+      () => validateProfileImage(upload(PNG, "image/jpeg")),
+      PROFILE_IMAGE_TYPE_INVALID,
+    );
+  });
+
+  it("rejects unsupported or malformed bytes", () => {
+    expectAppException(
+      () => validateProfileImage(upload(Buffer.from("not an image").toString("base64"), "image/png")),
+      PROFILE_IMAGE_TYPE_INVALID,
+    );
+  });
+
+  it("rejects a file larger than the shared byte limit", () => {
+    expectAppException(
+      () => validateProfileImage(upload(PNG, "image/png", PROFILE_IMAGE_POLICY.maxBytes + 1)),
+      PROFILE_IMAGE_TOO_LARGE,
+      413,
+    );
+  });
+
+  it("accepts arbitrary aspect ratios within the limit", () => {
+    expect(validateProfileImage(upload(PNG, "image/png"))).toMatchObject({ width: 2, height: 3 });
+  });
+
+  it("rejects a dimension above 2048 pixels", () => {
+    expectAppException(
+      () => validateProfileImage(upload(TOO_WIDE_PNG, "image/png")),
+      PROFILE_IMAGE_DIMENSIONS_INVALID,
+    );
+  });
+});

package/dist/templates/modules/admin-dashboard/files/apps/api/src/profile-image/profile-image.validation.ts

@@ -0,0 +1,74 @@
+import {
+  AppException,
+  PROFILE_IMAGE_DIMENSIONS_INVALID,
+  PROFILE_IMAGE_POLICY,
+  PROFILE_IMAGE_TOO_LARGE,
+  PROFILE_IMAGE_TYPE_INVALID,
+  type ProfileImageMimeType,
+} from "@podosoft/podokit-contracts";
+import { imageSize } from "image-size";
+
+export interface ProfileImageUpload {
+  buffer: Buffer;
+  mimetype: string;
+  size: number;
+}
+
+export interface ProfileImageMetadata {
+  contentType: ProfileImageMimeType;
+  extension: "jpg" | "png" | "webp";
+  width: number;
+  height: number;
+}
+
+const DETECTED_TYPES: Record<string, Pick<ProfileImageMetadata, "contentType" | "extension">> = {
+  jpg: { contentType: "image/jpeg", extension: "jpg" },
+  png: { contentType: "image/png", extension: "png" },
+  webp: { contentType: "image/webp", extension: "webp" },
+};
+
+/** Inspect image bytes instead of trusting the uploaded filename or MIME type. */
+export function validateProfileImage(file: ProfileImageUpload): ProfileImageMetadata {
+  if (Math.max(file.size, file.buffer.length) > PROFILE_IMAGE_POLICY.maxBytes) {
+    throw new AppException(
+      PROFILE_IMAGE_TOO_LARGE,
+      "Profile image must be 2 MB or smaller.",
+      413,
+    );
+  }
+
+  let dimensions: ReturnType<typeof imageSize>;
+  try {
+    dimensions = imageSize(file.buffer);
+  } catch {
+    throw new AppException(
+      PROFILE_IMAGE_TYPE_INVALID,
+      "Profile image must be a valid PNG, JPEG, or WebP file.",
+    );
+  }
+
+  const detected = dimensions.type ? DETECTED_TYPES[dimensions.type] : undefined;
+  if (!detected || detected.contentType !== file.mimetype) {
+    throw new AppException(
+      PROFILE_IMAGE_TYPE_INVALID,
+      "Profile image must be a valid PNG, JPEG, or WebP file.",
+    );
+  }
+  if (
+    dimensions.width === undefined
+    || dimensions.height === undefined
+    || dimensions.width > PROFILE_IMAGE_POLICY.maxWidth
+    || dimensions.height > PROFILE_IMAGE_POLICY.maxHeight
+  ) {
+    throw new AppException(
+      PROFILE_IMAGE_DIMENSIONS_INVALID,
+      "Profile image dimensions must not exceed 2048 by 2048 pixels.",
+    );
+  }
+
+  return {
+    ...detected,
+    width: dimensions.width,
+    height: dimensions.height,
+  };
+}

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/admin/registry.svelte.ts

@@ -6,7 +6,7 @@ import type { Messages } from "$lib/i18n/messages";
 
 // Module-driven admin menu registry. Modules append their sidebar nav entries and
 // settings tabs at the markers below via `podo add` injection, so the admin menu
-// grows and shrinks with the installed module set — no edits to app-sidebar or
+// grows and shrinks with the installed module set — no edits to admin-sidebar or
 // the settings page. Empty until a module registers.
 
 /** A sidebar nav entry contributed by a module: a link, a label resolved from the

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/components/account-page.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-  import { goto } from "$app/navigation";
+  import { goto, invalidateAll } from "$app/navigation";
   import QRCode from "qrcode";
   import { Button } from "$lib/components/ui/button";
   import { Input } from "$lib/components/ui/input";
@@ -14,7 +14,17 @@
   import { getI18n, fmt, formatDateTime } from "$lib/i18n";
   import { untrack } from "svelte";
   import type { SessionUser } from "../../app.d.ts";
-  import type { Capabilities } from "@podosoft/podokit-api-client";
+  import UserAvatar from "./user-avatar.svelte";
+  import {
+    ApiError,
+    PROFILE_IMAGE_DIMENSIONS_INVALID,
+    PROFILE_IMAGE_POLICY,
+    PROFILE_IMAGE_REQUIRED,
+    PROFILE_IMAGE_TOO_LARGE,
+    PROFILE_IMAGE_TYPE_INVALID,
+    type Capabilities,
+    type ProfileImageResponse,
+  } from "@podosoft/podokit-api-client";
 
   let {
     data,
@@ -45,6 +55,15 @@
   let name = $state(untrack(() => data.user.name));
   let username = $state(untrack(() => data.user.username ?? ""));
   let savingProfile = $state(false);
+  let profileImage = $state<string | null>(untrack(() => data.user.image ?? null));
+  let profileImageInput = $state<HTMLInputElement | null>(null);
+  let profileImageBusy = $state(false);
+  const profileImageAccept = PROFILE_IMAGE_POLICY.mimeTypes.join(",");
+  const profileImageHint = fmt(i18n.t.account.profileImageHint, {
+    size: PROFILE_IMAGE_POLICY.maxBytes / 1024 / 1024,
+    width: PROFILE_IMAGE_POLICY.maxWidth,
+    height: PROFILE_IMAGE_POLICY.maxHeight,
+  });
   const nameChanged = $derived(
     (name.trim() !== "" && name !== data.user.name) || (caps.username && username !== (data.user.username ?? "")),
   );
@@ -60,6 +79,93 @@
     else toast.success(i18n.t.account.saved);
   }
 
+  function profileImageErrorMessage(code: string): string {
+    switch (code) {
+      case PROFILE_IMAGE_REQUIRED:
+        return i18n.t.account.profileImageRequired;
+      case PROFILE_IMAGE_TOO_LARGE:
+        return i18n.t.account.profileImageTooLarge;
+      case PROFILE_IMAGE_DIMENSIONS_INVALID:
+        return i18n.t.account.profileImageDimensionsInvalid;
+      case PROFILE_IMAGE_TYPE_INVALID:
+        return i18n.t.account.profileImageTypeInvalid;
+      default:
+        return i18n.t.account.profileImageFailed;
+    }
+  }
+
+  function imageDimensions(file: File): Promise<{ width: number; height: number }> {
+    return new Promise((resolve, reject) => {
+      const url = URL.createObjectURL(file);
+      const image = new Image();
+      image.onload = () => {
+        URL.revokeObjectURL(url);
+        resolve({ width: image.naturalWidth, height: image.naturalHeight });
+      };
+      image.onerror = () => {
+        URL.revokeObjectURL(url);
+        reject(new Error("Invalid image"));
+      };
+      image.src = url;
+    });
+  }
+
+  async function validateProfileImageSelection(file: File): Promise<string | null> {
+    if (!(PROFILE_IMAGE_POLICY.mimeTypes as readonly string[]).includes(file.type)) {
+      return PROFILE_IMAGE_TYPE_INVALID;
+    }
+    if (file.size > PROFILE_IMAGE_POLICY.maxBytes) return PROFILE_IMAGE_TOO_LARGE;
+    try {
+      const dimensions = await imageDimensions(file);
+      if (
+        dimensions.width > PROFILE_IMAGE_POLICY.maxWidth
+        || dimensions.height > PROFILE_IMAGE_POLICY.maxHeight
+      ) {
+        return PROFILE_IMAGE_DIMENSIONS_INVALID;
+      }
+    } catch {
+      return PROFILE_IMAGE_TYPE_INVALID;
+    }
+    return null;
+  }
+
+  async function uploadProfileImage(event: Event): Promise<void> {
+    const input = event.currentTarget as HTMLInputElement;
+    const file = input.files?.[0];
+    input.value = "";
+    if (!file) return;
+    const validationCode = await validateProfileImageSelection(file);
+    if (validationCode) return void toast.error(profileImageErrorMessage(validationCode));
+
+    profileImageBusy = true;
+    try {
+      const form = new FormData();
+      form.set("file", file, file.name);
+      const response = await api.postForm<ProfileImageResponse>("/account/profile-image", form);
+      profileImage = response.image;
+      toast.success(i18n.t.account.profileImageUpdated);
+      await invalidateAll();
+    } catch (error: unknown) {
+      toast.error(profileImageErrorMessage(error instanceof ApiError ? error.code : ""));
+    } finally {
+      profileImageBusy = false;
+    }
+  }
+
+  async function removeProfileImage(): Promise<void> {
+    profileImageBusy = true;
+    try {
+      const response = await api.del<ProfileImageResponse>("/account/profile-image");
+      profileImage = response.image;
+      toast.success(i18n.t.account.profileImageRemoved);
+      await invalidateAll();
+    } catch (error: unknown) {
+      toast.error(profileImageErrorMessage(error instanceof ApiError ? error.code : ""));
+    } finally {
+      profileImageBusy = false;
+    }
+  }
+
   // Phone number — register + verify with an SMS code (dev delivery is a stub).
   let phone = $state(untrack(() => data.user.phoneNumber ?? ""));
   let phoneCode = $state("");
@@ -404,6 +510,53 @@
         <Card.Root>
           <Card.Header><Card.Title>{i18n.t.account.profile}</Card.Title></Card.Header>
           <Card.Content>
+            <div class="mb-6 flex max-w-md items-center gap-4 border-b pb-6">
+              <div data-testid="profile-image-preview">
+                <UserAvatar user={{ ...data.user, image: profileImage }} class="size-20 shrink-0" />
+              </div>
+              <div class="min-w-0 flex-1 space-y-2">
+                <Label for="profile-image">{i18n.t.account.profileImage}</Label>
+                <p id="profile-image-hint" class="text-muted-foreground text-xs" data-testid="profile-image-hint">
+                  {profileImageHint}
+                </p>
+                <Input
+                  id="profile-image"
+                  type="file"
+                  accept={profileImageAccept}
+                  class="sr-only"
+                  aria-describedby="profile-image-hint"
+                  disabled={profileImageBusy}
+                  bind:ref={profileImageInput}
+                  onchange={uploadProfileImage}
+                />
+                <div class="flex flex-wrap gap-2">
+                  <Button
+                    type="button"
+                    variant="outline"
+                    size="sm"
+                    disabled={profileImageBusy}
+                    onclick={() => profileImageInput?.click()}
+                  >
+                    {profileImageBusy
+                      ? i18n.t.account.profileImageUploading
+                      : profileImage
+                        ? i18n.t.account.profileImageReplace
+                        : i18n.t.account.profileImageUpload}
+                  </Button>
+                  {#if profileImage}
+                    <Button
+                      type="button"
+                      variant="ghost"
+                      size="sm"
+                      disabled={profileImageBusy}
+                      onclick={removeProfileImage}
+                    >
+                      {i18n.t.account.profileImageRemove}
+                    </Button>
+                  {/if}
+                </div>
+              </div>
+            </div>
             <form class="flex max-w-md flex-col gap-4" onsubmit={saveProfile}>
               <div class="flex flex-col gap-2">
                 <Label for="name">{i18n.t.account.name}</Label>

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/components/session-idle-timeout.svelte

@@ -0,0 +1,109 @@
+<script lang="ts">
+  import { goto } from "$app/navigation";
+  import { onMount } from "svelte";
+  import { api } from "$lib/api";
+
+  let { timeoutMinutes }: { timeoutMinutes: number | null } = $props();
+
+  const ACTIVITY_KEY = "podokit:session-last-activity";
+  const SERVER_REFRESH_INTERVAL_MS = 60_000;
+  const activityEvents = ["pointerdown", "keydown", "touchstart", "scroll"] as const;
+
+  let mounted = $state(false);
+  let lastActivityAt = $state(Date.now());
+  let lastServerRefreshAt = $state(Date.now());
+  let signingOut = false;
+  let previousTimeoutMs: number | null = null;
+  const timeoutMs = $derived(timeoutMinutes === null ? null : timeoutMinutes * 60_000);
+
+  function storeActivity(value: number): void {
+    try {
+      localStorage.setItem(ACTIVITY_KEY, String(value));
+    } catch {
+      // Storage can be unavailable in hardened browser modes; this tab still works.
+    }
+  }
+
+  async function signOutForIdleTimeout(): Promise<void> {
+    if (signingOut) return;
+    signingOut = true;
+    try {
+      await api.auth.signOut();
+    } finally {
+      try {
+        localStorage.removeItem(ACTIVITY_KEY);
+      } catch {
+        // Ignore unavailable storage while completing sign-out.
+      }
+      await goto("/login?reason=idle", { invalidateAll: true });
+    }
+  }
+
+  async function refreshServerSession(): Promise<void> {
+    const { data, error } = await api.auth.getSession();
+    if (error || !data) await signOutForIdleTimeout();
+  }
+
+  function recordActivity(): void {
+    if (timeoutMs === null || signingOut) return;
+    const now = Date.now();
+    if (now - lastActivityAt >= timeoutMs) {
+      void signOutForIdleTimeout();
+      return;
+    }
+    lastActivityAt = now;
+    storeActivity(now);
+    if (now - lastServerRefreshAt >= SERVER_REFRESH_INTERVAL_MS) {
+      lastServerRefreshAt = now;
+      void refreshServerSession();
+    }
+  }
+
+  function receiveActivity(event: StorageEvent): void {
+    if (event.key !== ACTIVITY_KEY || event.newValue === null) return;
+    const value = Number(event.newValue);
+    if (Number.isFinite(value) && value > lastActivityAt) lastActivityAt = value;
+  }
+
+  onMount(() => {
+    mounted = true;
+    const now = Date.now();
+    lastActivityAt = now;
+    lastServerRefreshAt = now;
+    storeActivity(now);
+    for (const event of activityEvents) {
+      document.addEventListener(event, recordActivity, { passive: true, capture: true });
+    }
+    window.addEventListener("focus", recordActivity);
+    window.addEventListener("storage", receiveActivity);
+    return () => {
+      for (const event of activityEvents) {
+        document.removeEventListener(event, recordActivity, { capture: true });
+      }
+      window.removeEventListener("focus", recordActivity);
+      window.removeEventListener("storage", receiveActivity);
+    };
+  });
+
+  $effect(() => {
+    if (!mounted) return;
+    const currentTimeoutMs = timeoutMs;
+    if (currentTimeoutMs !== previousTimeoutMs) {
+      previousTimeoutMs = currentTimeoutMs;
+      if (currentTimeoutMs !== null) {
+        const now = Date.now();
+        lastActivityAt = now;
+        lastServerRefreshAt = now;
+        storeActivity(now);
+      }
+    }
+    if (currentTimeoutMs === null) return;
+    const remaining = currentTimeoutMs - (Date.now() - lastActivityAt);
+    if (remaining <= 0) {
+      void signOutForIdleTimeout();
+      return;
+    }
+    const timer = window.setTimeout(() => void signOutForIdleTimeout(), remaining);
+    return () => window.clearTimeout(timer);
+  });
+</script>

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/components/sidebar-user-menu.svelte

@@ -22,7 +22,7 @@
 <Sidebar.Menu>
   <Sidebar.MenuItem>
     <DropdownMenu.Root>
-      <DropdownMenu.Trigger>
+      <DropdownMenu.Trigger data-testid="sidebar-user-menu">
         {#snippet child({ props })}
           <Sidebar.MenuButton {...props} size="lg" class="data-[state=open]:bg-sidebar-accent">
             <UserAvatar {user} class="size-8" />

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/components/site-runtime.svelte

@@ -3,10 +3,14 @@
   import { ModeWatcher } from "mode-watcher";
   import { site, type SiteSettings } from "$lib/site.svelte";
   import { applyTheme, themeConfigFromSettings } from "$lib/site/apply-theme";
+  import SessionIdleTimeout from "$lib/components/session-idle-timeout.svelte";
 
   const loadedSite = $derived(
     (page.data as { site?: Partial<SiteSettings> | null }).site,
   );
+  const sessionIdleTimeoutMinutes = $derived(
+    (page.data as { sessionIdleTimeoutMinutes?: number | null }).sessionIdleTimeoutMinutes ?? null,
+  );
 
   // Seed the reactive site settings for every route without taking ownership of
   // the application's root layout or public pages.
@@ -37,3 +41,4 @@
 </svelte:head>
 
 <ModeWatcher />
+<SessionIdleTimeout timeoutMinutes={sessionIdleTimeoutMinutes} />