@podosoft/podokit 1.4.2 → 1.5.0

package/dist/templates/fullstack/apps/web/src/lib/server/backend-proxy.ts

@@ -1,5 +1,6 @@
 import { APP_BODY_LIMITS } from "./body-limits";
 import { APP_FORWARDED_REQUEST_HEADERS, APP_RELAYED_RESPONSE_HEADERS } from "./proxy-headers";
+import { APP_PROXY_TIMEOUTS } from "./proxy-timeouts";
 
 // Server-side proxy boundary. The browser never talks to the API directly:
 // requests go through SvelteKit server routes, which forward an allowlist of
@@ -118,46 +119,115 @@ export interface BodyLimit {
   maxBytes: number;
 }
 
-const BODY_LIMIT_PREFIX = /^\/api(?:\/[A-Za-z0-9._~!$&'()+,;=:@-]+)*\/?$/;
-
-/** Validate application body limits and order them so the longest prefix
- *  matches first. Prefixes are stored without a trailing slash. */
-export function sortedBodyLimits(limits: ReadonlyArray<BodyLimit>): BodyLimit[] {
-  const seen = new Set<string>();
-  const sorted = limits.map(({ pathPrefix, maxBytes }) => {
-    if (
-      !BODY_LIMIT_PREFIX.test(pathPrefix) ||
-      pathPrefix.split("/").some((segment) => segment === "." || segment === "..")
-    ) {
+/** A literal path segment, or null for a `:name` parameter. */
+type PathSegment = string | null;
+
+/** An application path rule with its prefix split into segments. */
+export type PathRule<T extends { pathPrefix: string }> = T & { readonly segments: readonly PathSegment[] };
+
+const LITERAL_SEGMENT = /^[A-Za-z0-9._~!$&'()+,;=:@-]+$/;
+const PARAMETER_SEGMENT = /^:[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** The segments of a prefix under /api/, or undefined when it is not one. */
+function parsePathPrefix(pathPrefix: string): PathSegment[] | undefined {
+  const base = pathPrefix.endsWith("/") ? pathPrefix.slice(0, -1) : pathPrefix;
+  const [root, ...segments] = base.split("/");
+  if (root !== "" || segments[0] !== "api") return undefined;
+  const parsed: PathSegment[] = [];
+  for (const segment of segments) {
+    if (PARAMETER_SEGMENT.test(segment)) {
+      parsed.push(null);
+    } else if (LITERAL_SEGMENT.test(segment) && !segment.startsWith(":") && segment !== "." && segment !== "..") {
+      parsed.push(segment);
+    } else {
+      return undefined;
+    }
+  }
+  return parsed;
+}
+
+/**
+ * Below zero when `a` is more specific: more segments, then, from the left, a
+ * literal segment before a parameter.
+ */
+function compareSpecificity(a: readonly PathSegment[], b: readonly PathSegment[]): number {
+  if (a.length !== b.length) return b.length - a.length;
+  for (let index = 0; index < a.length; index += 1) {
+    const literal = a[index] !== null;
+    if (literal !== (b[index] !== null)) return literal ? -1 : 1;
+  }
+  return 0;
+}
+
+/** Validate an application list of /api path prefixes and order it so the
+ *  most specific prefix matches first. Prefixes are stored without a trailing
+ *  slash. */
+function sortedByPrefix<T extends { pathPrefix: string }>(
+  entries: ReadonlyArray<T>,
+  listName: string,
+  example: string,
+  check: (entry: T) => void,
+): PathRule<T>[] {
+  const seen = new Map<string, string>();
+  const rules = entries.map((entry) => {
+    const { pathPrefix } = entry;
+    const segments = parsePathPrefix(pathPrefix);
+    if (!segments) {
       throw new Error(
-        `APP_BODY_LIMITS pathPrefix must be a static path under /api/, such as "/api/feedback/": ${JSON.stringify(pathPrefix)}`,
+        `${listName} pathPrefix must be a path under /api/ made of literal segments and ":name" parameters, ` +
+          `such as "${example}": ${JSON.stringify(pathPrefix)}`,
       );
     }
-    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
-      throw new Error(`APP_BODY_LIMITS maxBytes for ${pathPrefix} must be a positive whole number of bytes.`);
+    check(entry);
+    // Parameter names do not change which paths a prefix covers.
+    const key = segments.map((segment) => segment ?? ":").join("/");
+    const listed = seen.get(key);
+    if (listed !== undefined) {
+      throw new Error(
+        `${listName} lists the same paths twice: ${JSON.stringify(listed)} and ${JSON.stringify(pathPrefix)}.`,
+      );
     }
-    const base = pathPrefix.endsWith("/") ? pathPrefix.slice(0, -1) : pathPrefix;
-    if (seen.has(base)) throw new Error(`APP_BODY_LIMITS lists ${pathPrefix} more than once.`);
-    seen.add(base);
-    return { pathPrefix: base, maxBytes };
+    seen.set(key, pathPrefix);
+    return { ...entry, pathPrefix: pathPrefix.endsWith("/") ? pathPrefix.slice(0, -1) : pathPrefix, segments };
   });
-  return sorted.sort((left, right) => right.pathPrefix.length - left.pathPrefix.length);
+  return rules.sort((left, right) => compareSpecificity(left.segments, right.segments));
 }
 
-const bodyLimits = sortedBodyLimits(APP_BODY_LIMITS);
-
-/** The body limit for a request path, matched on the decoded path so an encoded
- *  segment cannot step around a prefix. */
-export function bodyLimitFor(pathname: string, limits: readonly BodyLimit[] = bodyLimits): number | undefined {
+/** The most specific rule for a request path. Prefixes match whole segments of
+ *  the decoded path, so an encoded segment cannot step around them, and a
+ *  parameter matches exactly one non-empty segment. */
+function entryFor<T extends { pathPrefix: string }>(
+  pathname: string,
+  rules: readonly PathRule<T>[],
+): PathRule<T> | undefined {
   let path = pathname;
   try {
     path = decodeURIComponent(pathname);
   } catch {
     // Keep the raw path when it holds a malformed escape.
   }
-  return limits.find(
-    ({ pathPrefix }) => path === pathPrefix || path.startsWith(`${pathPrefix}/`),
-  )?.maxBytes;
+  const segments = path.split("/").slice(1);
+  return rules.find(
+    (rule) =>
+      rule.segments.length <= segments.length &&
+      rule.segments.every((segment, index) =>
+        segment === null ? segments[index] !== "" : segment === segments[index],
+      ),
+  );
+}
+
+export function sortedBodyLimits(limits: ReadonlyArray<BodyLimit>): PathRule<BodyLimit>[] {
+  return sortedByPrefix(limits, "APP_BODY_LIMITS", "/api/feedback/", ({ pathPrefix, maxBytes }) => {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+      throw new Error(`APP_BODY_LIMITS maxBytes for ${pathPrefix} must be a positive whole number of bytes.`);
+    }
+  });
+}
+
+const bodyLimits = sortedBodyLimits(APP_BODY_LIMITS);
+
+export function bodyLimitFor(pathname: string, limits: readonly PathRule<BodyLimit>[] = bodyLimits): number | undefined {
+  return entryFor(pathname, limits)?.maxBytes;
 }
 
 /** Read a request body, or return null as soon as it exceeds maxBytes. The rest
@@ -220,13 +290,15 @@ export function backendBaseUrl(): string {
 
 /**
  * Milliseconds one server-side API call may take, response body included, and
- * how long the proxy waits for response headers before it checks whether the
- * API still answers at all.
+ * how often the proxy checks whether the API still answers at all while it waits
+ * for response headers.
  */
 const DEFAULT_BACKEND_TIMEOUT_MS = 2_000;
 /**
- * Milliseconds the proxy waits for the API's response headers, matching the
- * API's default idle timeout. Streamed bodies are not cut off once they start.
+ * Milliseconds the proxy waits for the API's response headers, unless
+ * APP_PROXY_TIMEOUTS lists the path. The API's default idle timeout of 35
+ * seconds outlasts it.
+ * Streamed bodies are not cut off once they start.
  */
 const DEFAULT_BACKEND_PROXY_TIMEOUT_MS = 30_000;
 /** Seconds between checks while the API is unreachable, also sent as Retry-After. */
@@ -259,10 +331,84 @@ function backendProxyTimeoutMs(): number {
 backendTimeoutMs();
 backendProxyTimeoutMs();
 
+export interface ProxyTimeout {
+  pathPrefix: string;
+  /** Milliseconds to wait for response headers, or null for no deadline. */
+  timeoutMs: number | null;
+}
+
+export function sortedProxyTimeouts(timeouts: ReadonlyArray<ProxyTimeout>): PathRule<ProxyTimeout>[] {
+  return sortedByPrefix(timeouts, "APP_PROXY_TIMEOUTS", "/api/exports/", ({ pathPrefix, timeoutMs }) => {
+    if (timeoutMs !== null && (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_TIMER_MS)) {
+      throw new Error(
+        `APP_PROXY_TIMEOUTS timeoutMs for ${pathPrefix} must be null or a whole number of milliseconds from 1 to ${MAX_TIMER_MS}.`,
+      );
+    }
+  });
+}
+
+const proxyTimeouts = sortedProxyTimeouts(APP_PROXY_TIMEOUTS);
+
+/** How long the proxy waits for response headers on a request path, or null for no deadline. */
+export function proxyTimeoutFor(
+  pathname: string,
+  timeouts: readonly PathRule<ProxyTimeout>[] = proxyTimeouts,
+): number | null {
+  const entry = entryFor(pathname, timeouts);
+  return entry ? entry.timeoutMs : backendProxyTimeoutMs();
+}
+
+/** Bun closes silent connections on a 4-second tick, up to 4 seconds before their idle timeout. */
+const IDLE_TICK_SECONDS = 4;
+/** The longest idle timeout Bun accepts; 0 turns it off. */
+const MAX_IDLE_TIMEOUT_SECONDS = 255;
+
+/**
+ * Throw unless the web server keeps a silent connection open longer than the
+ * proxy waits for response headers. adapter-bun takes its idle timeout from
+ * CONNECTION_IDLE_TIMEOUT (Bun's 10 seconds when unset) and closes a connection
+ * that sends nothing for that long without a response, so neither the API's late
+ * answer nor the proxy's 504 would reach the browser.
+ */
+export function checkIdleTimeout(
+  idleTimeout: string | undefined,
+  defaultTimeoutMs: number,
+  timeouts: readonly ProxyTimeout[],
+): void {
+  // adapter-bun rejects a malformed value itself when it starts.
+  if (idleTimeout === undefined || !/^\d+$/.test(idleTimeout) || Number(idleTimeout) === 0) return;
+  let longest: { timeoutMs: number | null; source: string } = {
+    timeoutMs: defaultTimeoutMs,
+    source: "BACKEND_PROXY_TIMEOUT_MS",
+  };
+  for (const { pathPrefix, timeoutMs } of timeouts) {
+    if (longest.timeoutMs !== null && (timeoutMs === null || timeoutMs > longest.timeoutMs)) {
+      longest = { timeoutMs, source: `APP_PROXY_TIMEOUTS for ${pathPrefix}` };
+    }
+  }
+  const seconds = Number(idleTimeout);
+  if (longest.timeoutMs !== null && (seconds - IDLE_TICK_SECONDS) * 1000 > longest.timeoutMs) return;
+  const minimum =
+    longest.timeoutMs === null ? Infinity : Math.floor(longest.timeoutMs / 1000) + IDLE_TICK_SECONDS + 1;
+  const wait = longest.timeoutMs === null ? "no deadline" : `${longest.timeoutMs} ms`;
+  const fix =
+    minimum <= MAX_IDLE_TIMEOUT_SECONDS
+      ? `at least ${minimum}, or to 0 to turn the idle timeout off`
+      : `0 to turn the idle timeout off, since Bun allows at most ${MAX_IDLE_TIMEOUT_SECONDS} seconds`;
+  throw new Error(
+    `CONNECTION_IDLE_TIMEOUT=${seconds} lets the web server close a silent connection before the /api proxy ` +
+      `stops waiting for response headers (${wait}, ${longest.source}); Bun closes idle connections up to ` +
+      `${IDLE_TICK_SECONDS} seconds early. Set CONNECTION_IDLE_TIMEOUT to ${fix}.`,
+  );
+}
+
+checkIdleTimeout(process.env.CONNECTION_IDLE_TIMEOUT, backendProxyTimeoutMs(), proxyTimeouts);
+
 // The API counts as unreachable only when GET /health gets no HTTP answer
-// within BACKEND_TIMEOUT_MS. It is checked when a request gets no answer, or
-// when the proxy waits longer than that for response headers, so one slow
-// endpoint does not fail every request in the process. Once the API is found
+// within BACKEND_TIMEOUT_MS. It is checked when a request gets no answer, and
+// every BACKEND_TIMEOUT_MS while the proxy waits for response headers, so one
+// slow endpoint does not fail every request in the process, while an API that
+// stops answering still ends a long or unbounded wait. Once the API is found
 // unreachable, requests still waiting for it fail, new ones fail at once instead
 // of each waiting for a refused connection, a DNS lookup, or a hung server, and
 // a background check runs at most every BACKEND_RETRY_AFTER_SECONDS. Any HTTP
@@ -303,6 +449,11 @@ export function checkBackend(): Promise<void> {
   return pendingCheck;
 }
 
+/** Check the API unless a check is running or one ended within BACKEND_TIMEOUT_MS. */
+function recheckBackend(now = Date.now()): void {
+  if (!pendingCheck && now - lastCheckEnded >= backendTimeoutMs()) void checkBackend();
+}
+
 /** Record an HTTP answer from the API, whatever its status. */
 export function reportBackendAnswer(): void {
   answers += 1;
@@ -400,15 +551,19 @@ export async function proxyRequest(
       body = limited;
     }
   }
-  // The deadline, the health check, and the outage signal cover only the wait
+  // The deadline, the health checks, and the outage signal cover only the wait
   // for response headers, so streamed bodies such as server-sent events are not
   // cut off.
   const waiting = new AbortController();
-  const deadline = setTimeout(
-    () => waiting.abort(new DOMException("The API did not respond in time", "TimeoutError")),
-    backendProxyTimeoutMs(),
-  );
-  const healthCheck = setTimeout(() => void checkBackend(), backendTimeoutMs());
+  const timeoutMs = proxyTimeoutFor(pathname);
+  const deadline =
+    timeoutMs === null
+      ? undefined
+      : setTimeout(
+          () => waiting.abort(new DOMException("The API did not respond in time", "TimeoutError")),
+          timeoutMs,
+        );
+  const healthChecks = setInterval(() => recheckBackend(), backendTimeoutMs());
   const outage = backendOutageSignal();
   const failOnOutage = (): void => waiting.abort(outage.reason);
   outage.addEventListener("abort", failOnOutage);
@@ -432,7 +587,7 @@ export async function proxyRequest(
     return backendFailure(pathname, waiting.signal.aborted ? 504 : 503);
   } finally {
     clearTimeout(deadline);
-    clearTimeout(healthCheck);
+    clearInterval(healthChecks);
     outage.removeEventListener("abort", failOnOutage);
   }
   reportBackendAnswer();

package/dist/templates/fullstack/apps/web/src/lib/server/body-limits.ts

@@ -3,8 +3,11 @@
  * proxies to the API. An entry caps the body of every request whose path is
  * pathPrefix or below it, for example
  *   { pathPrefix: "/api/feedback/", maxBytes: 64 * 1024 }
- * and the longest matching prefix wins. Above the limit the proxy stops reading
- * and answers 413 PAYLOAD_TOO_LARGE without contacting the API.
+ *   { pathPrefix: "/api/hosts/:hostId/uploads", maxBytes: 1024 * 1024 }
+ * where a :name segment matches exactly one non-empty path segment. The most
+ * specific entry wins: more segments, then a literal segment over a parameter
+ * from the left. Above the limit the proxy stops reading and answers 413
+ * PAYLOAD_TOO_LARGE without contacting the API.
  *
  * BODY_SIZE_LIMIT remains the ceiling for every web route: Bun rejects a larger
  * body before this code runs, so a maxBytes above it has no effect. Routes that

package/dist/templates/fullstack/apps/web/src/lib/server/proxy-timeouts.ts

@@ -0,0 +1,22 @@
+/**
+ * Application-owned deadlines for /api requests that the web server proxies to
+ * the API. An entry replaces BACKEND_PROXY_TIMEOUT_MS for every request whose
+ * path is pathPrefix or below it, for example
+ *   { pathPrefix: "/api/exports/", timeoutMs: 120_000 }
+ *   { pathPrefix: "/api/hosts/:hostId/file-transfers", timeoutMs: null }
+ * where a :name segment matches exactly one non-empty path segment. The most
+ * specific entry wins: more segments, then a literal segment over a parameter
+ * from the left. timeoutMs is how long the proxy waits for the API's response
+ * headers before it answers 504 BACKEND_TIMEOUT; null waits as long as the API
+ * takes. Either way the proxy answers 503 BACKEND_UNAVAILABLE once the API's
+ * GET /health stops answering, and the deadline ends when the response headers
+ * arrive.
+ *
+ * Bun closes a silent connection up to 4 seconds before its idle timeout, so a
+ * longer wait also needs the API's API_IDLE_TIMEOUT and the web server's
+ * CONNECTION_IDLE_TIMEOUT (35 seconds each by default) more than 4 seconds above
+ * the deadline, or 0 for null or anything above 250 seconds. The proxy refuses
+ * to load when CONNECTION_IDLE_TIMEOUT cannot cover an entry here.
+ * PodoKit creates this file once and never overwrites it.
+ */
+export const APP_PROXY_TIMEOUTS: ReadonlyArray<{ pathPrefix: string; timeoutMs: number | null }> = [];

package/dist/templates/fullstack/dot-env.docker.example

@@ -12,6 +12,8 @@ POSTGRES_USER=podokit
 POSTGRES_PASSWORD=podokit
 POSTGRES_DB=podokit
 BACKEND_INTERNAL_URL=http://api:5002
+# API: the web container and the gateway are the one proxy in front of it.
+TRUSTED_PROXY_HOPS=1
 # Web: milliseconds per server-side API call, and the /api proxy's wait for
 # response headers.
 # BACKEND_TIMEOUT_MS=2000

package/dist/templates/fullstack/dot-env.example

@@ -27,6 +27,18 @@ POSTGRES_DB=podokit
 # Largest API request body in bytes (Bun's default is 128 MiB). Requests through
 # the web app's /api proxy are also bounded by BODY_SIZE_LIMIT below.
 # API_MAX_REQUEST_BODY_SIZE=134217728
+# Seconds the API keeps a silent connection open (0 to 255, 0 turns it off). Keep
+# it, like CONNECTION_IDLE_TIMEOUT below, more than 4 above the longest /api proxy
+# deadline in seconds.
+# API_IDLE_TIMEOUT=35
+
+# Reverse proxies in front of the API whose X-Forwarded-For names the caller. The
+# web app's /api proxy is one, so 1 records the browser's address for sessions,
+# audit entries, and rate limits; 0 uses the socket peer. Count only proxies that
+# every request passes: with 1, a caller that reaches the API directly chooses
+# its own recorded address.
+TRUSTED_PROXY_HOPS=1
+# TRUSTED_PROXY_HEADER=x-forwarded-for
 
 # Readiness (GET /health/ready): the longest one dependency check may run, and how
 # long a result is reused across probes (0 checks on every request).
@@ -39,13 +51,17 @@ BACKEND_INTERNAL_URL=http://localhost:5002
 # waits for response headers (504 BACKEND_TIMEOUT after the second value). When
 # the API's GET /health does not answer within BACKEND_TIMEOUT_MS either, API
 # calls fail at once until it does. Raise BACKEND_PROXY_TIMEOUT_MS together with
-# the API's apiServerOptions.idleTimeout.
+# API_IDLE_TIMEOUT above and CONNECTION_IDLE_TIMEOUT below.
 # BACKEND_TIMEOUT_MS=2000
 # BACKEND_PROXY_TIMEOUT_MS=30000
 
 CORS_ORIGIN=http://localhost:5001
 # Web request limit; leave room for a 2 MiB multipart upload
 BODY_SIZE_LIMIT=3M
+# Seconds the built web server keeps a silent connection open (0 to 255, 0 turns
+# it off). Keep it more than 4 above the longest /api proxy deadline in seconds,
+# BACKEND_PROXY_TIMEOUT_MS or APP_PROXY_TIMEOUTS; the proxy refuses to load otherwise.
+CONNECTION_IDLE_TIMEOUT=35
 
 # ── Optional / development ───────────────────────────────────────────
 # Redis — only needed by cache/queue modules (redis, bullmq, rate-limit,

package/dist/templates/fullstack/infra/k3s/configmap.yaml

@@ -9,6 +9,9 @@ data:
   CORS_ORIGIN: "https://example.com"
   BACKEND_INTERNAL_URL: "http://api:3000"
   BODY_SIZE_LIMIT: "3M"
+  CONNECTION_IDLE_TIMEOUT: "35"
+  API_IDLE_TIMEOUT: "35"
+  TRUSTED_PROXY_HOPS: "1"
   PROTOCOL_HEADER: "x-forwarded-proto"
   HOST_HEADER: "x-forwarded-host"
   ADDRESS_HEADER: "x-forwarded-for"

package/dist/templates/modules/admin-dashboard/files/apps/api/src/account-sessions/account-sessions.routes.spec.ts

@@ -0,0 +1,152 @@
+import { afterEach, beforeEach, describe, expect, mock, test, type Mock } from "bun:test";
+import { SQL } from "bun";
+import { AppException } from "@podosoft/podokit-contracts";
+import { Elysia } from "elysia";
+import type { AuthService, AuthSession } from "../auth/auth.service";
+import { AdminSessionsService } from "../admin-sessions/admin-sessions.service";
+import {
+  accountSessionRoutes,
+  type AccountSessionPage,
+  type OwnSessionRevoker,
+} from "./account-sessions.routes";
+
+// More sessions than Better Auth's /list-sessions returns.
+const OTHER_SESSIONS = 150;
+const DAY_MS = 86_400_000;
+
+// Callers name their session with a test header; its row says whose it is.
+function authFor(db: SQL): Pick<AuthService, "requireSession"> {
+  return {
+    requireSession: async (request: Request): Promise<AuthSession> => {
+      const id = request.headers.get("x-test-session");
+      const [row] = id
+        ? await db<Array<{ userId: string; createdAt: string }>>`
+            SELECT "userId", "createdAt" FROM "session" WHERE "id" = ${id}
+          `
+        : [];
+      if (!row) throw new AppException("AUTH_REQUIRED", "Authentication is required", 401);
+      return { user: { id: row.userId }, session: { id, createdAt: row.createdAt } };
+    },
+  };
+}
+
+describe("account session routes", () => {
+  let db: SQL;
+  let revoke: Mock<OwnSessionRevoker>;
+  let freshAge: number;
+  let handle: (request: Request) => Promise<Response>;
+  const now = Date.now();
+
+  beforeEach(async () => {
+    db = new SQL(":memory:");
+    await db`CREATE TABLE "user" ("id" TEXT PRIMARY KEY, "email" TEXT NOT NULL, "name" TEXT NOT NULL)`;
+    await db`
+      CREATE TABLE "session" (
+        "id" TEXT PRIMARY KEY, "userId" TEXT NOT NULL, "token" TEXT NOT NULL,
+        "ipAddress" TEXT, "userAgent" TEXT, "impersonatedBy" TEXT,
+        "createdAt" TEXT NOT NULL, "expiresAt" TEXT NOT NULL
+      )
+    `;
+    await db`INSERT INTO "user" VALUES ('user-1', 'one@example.com', 'One'), ('user-2', 'two@example.com', 'Two')`;
+    const expires = new Date(now + DAY_MS).toISOString();
+    // The current session is the oldest, so newest-first paging would put it last.
+    await db`
+      INSERT INTO "session" VALUES ('current', 'user-1', 'secret-current', '203.0.113.7', 'Agent',
+        NULL, ${new Date(now - 60_000).toISOString()}, ${expires})
+    `;
+    for (let index = 0; index < OTHER_SESSIONS; index += 1) {
+      await db`
+        INSERT INTO "session" VALUES (${`other-${index}`}, 'user-1', ${`secret-${index}`}, NULL, NULL, NULL,
+          ${new Date(now - 30_000 + index).toISOString()}, ${expires})
+      `;
+    }
+    await db`
+      INSERT INTO "session" VALUES ('foreign', 'user-2', 'secret-foreign', NULL, NULL, NULL,
+        ${new Date(now).toISOString()}, ${expires})
+    `;
+    revoke = mock<OwnSessionRevoker>(async () => undefined);
+    freshAge = 86_400;
+    const app = new Elysia()
+      .onError(({ code, error, set }) => {
+        if (error instanceof AppException) {
+          set.status = error.statusCode;
+          return { code: error.code };
+        }
+        if (code === "VALIDATION") {
+          set.status = 400;
+          return { code: "VALIDATION_ERROR" };
+        }
+        return undefined;
+      })
+      .use(accountSessionRoutes({
+        auth: authFor(db),
+        sessions: new AdminSessionsService(db, "sqlite"),
+        revoke,
+        freshAgeSeconds: async () => freshAge,
+      }));
+    handle = (request) => app.handle(request);
+  });
+
+  afterEach(async () => {
+    await db.close();
+  });
+
+  async function send(path: string, init: RequestInit = {}, session: string | null = "current"): Promise<Response> {
+    const headers = new Headers(init.headers);
+    if (session) headers.set("x-test-session", session);
+    return handle(new Request(`http://localhost${path}`, { ...init, headers }));
+  }
+
+  test("returns the current session on every page and pages through every other one", async () => {
+    const seen: string[] = [];
+    let cursor: string | null = null;
+    let pages = 0;
+    do {
+      const response = await send(`/account/sessions?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`);
+      expect(response.status).toBe(200);
+      const text = await response.text();
+      expect(text).not.toContain("secret-");
+      const page = JSON.parse(text) as AccountSessionPage;
+      expect(page.current).toMatchObject({ id: "current", ipAddress: "203.0.113.7", userAgent: "Agent" });
+      expect(page.total).toBe(OTHER_SESSIONS + 1);
+      seen.push(...page.items.map((item) => item.id));
+      cursor = page.nextCursor;
+      pages += 1;
+    } while (cursor);
+
+    expect(pages).toBe(2);
+    expect(seen).toHaveLength(OTHER_SESSIONS);
+    expect(new Set(seen).size).toBe(OTHER_SESSIONS);
+    expect(seen).not.toContain("current");
+    expect(seen).not.toContain("foreign");
+    expect(seen[0]).toBe(`other-${OTHER_SESSIONS - 1}`);
+  });
+
+  test("refuses anonymous callers and a session too old to list sessions", async () => {
+    expect((await send("/account/sessions", {}, null)).status).toBe(401);
+    await db`UPDATE "session" SET "createdAt" = ${new Date(now - 2 * DAY_MS).toISOString()} WHERE "id" = 'current'`;
+    const stale = await send("/account/sessions");
+    expect(stale.status).toBe(403);
+    expect(await stale.json()).toEqual({ code: "SESSION_NOT_FRESH" });
+    freshAge = 0;
+    expect((await send("/account/sessions")).status).toBe(200);
+  });
+
+  test("revokes one of the caller's sessions by id with the token looked up on the server", async () => {
+    const response = await send("/account/sessions/other-3", { method: "DELETE", headers: { cookie: "session=1" } });
+
+    expect(response.status).toBe(204);
+    expect(revoke).toHaveBeenCalledTimes(1);
+    const [token, headers] = revoke.mock.calls[0] ?? [];
+    expect(token).toBe("secret-3");
+    expect(headers?.get("cookie")).toBe("session=1");
+  });
+
+  test("does not reveal or revoke another user's session", async () => {
+    const response = await send("/account/sessions/foreign", { method: "DELETE" });
+
+    expect(response.status).toBe(404);
+    expect(await response.json()).toEqual({ code: "ACCOUNT_SESSION_NOT_FOUND" });
+    expect(revoke).not.toHaveBeenCalled();
+  });
+});

package/dist/templates/modules/admin-dashboard/files/apps/api/src/account-sessions/account-sessions.routes.ts

@@ -0,0 +1,112 @@
+import { AppException } from "@podosoft/podokit-contracts";
+import { Elysia, t } from "elysia";
+import type { AuthService, AuthSession } from "../auth/auth.service";
+import type { ElysiaPlugin } from "../core/services";
+import {
+  ADMIN_SESSIONS_MAX_LIMIT,
+  type AdminSessionsService,
+  type AdminSessionView,
+} from "../admin-sessions/admin-sessions.service";
+
+export const ACCOUNT_SESSION_NOT_FOUND = "ACCOUNT_SESSION_NOT_FOUND";
+/** Better Auth's code for a session older than `session.freshAge`. */
+export const SESSION_NOT_FRESH = "SESSION_NOT_FRESH";
+
+/** One of the caller's own sessions. The bearer token never leaves the server. */
+export interface AccountSessionView {
+  id: string;
+  ipAddress: string | null;
+  userAgent: string | null;
+  createdAt: string;
+  expiresAt: string;
+}
+
+export interface AccountSessionPage {
+  /** The session making the request, on every page. */
+  current: AccountSessionView | null;
+  /** The caller's other active sessions, newest first. */
+  items: AccountSessionView[];
+  nextCursor: string | null;
+  /** Every active session of the caller, the current one included. */
+  total: number;
+}
+
+/** Revokes one of the caller's sessions by its bearer token. */
+export type OwnSessionRevoker = (sessionToken: string, headers: Headers) => Promise<void>;
+
+export interface AccountSessionRoutesOptions {
+  auth: Pick<AuthService, "requireSession">;
+  sessions: AdminSessionsService;
+  revoke: OwnSessionRevoker;
+  /** Better Auth's `session.freshAge` in seconds; 0 turns the check off. */
+  freshAgeSeconds: () => Promise<number>;
+}
+
+function accountView(session: AdminSessionView): AccountSessionView {
+  return {
+    id: session.id,
+    ipAddress: session.ipAddress,
+    userAgent: session.userAgent,
+    createdAt: session.createdAt,
+    expiresAt: session.expiresAt,
+  };
+}
+
+// Better Auth lists sessions only for a fresh session; this list keeps that rule.
+function requireFresh(session: AuthSession, freshAgeSeconds: number): void {
+  if (freshAgeSeconds === 0) return;
+  const createdAt = new Date(session.session.createdAt as string | Date).getTime();
+  if (Date.now() - createdAt >= freshAgeSeconds * 1000) {
+    throw new AppException(SESSION_NOT_FRESH, "Session is not fresh", 403);
+  }
+}
+
+/**
+ * The signed-in user's own sessions, paged on the server. Better Auth's
+ * `/list-sessions` returns at most 100 sessions, which could leave out the
+ * current one.
+ */
+export function accountSessionRoutes({
+  auth,
+  sessions,
+  revoke,
+  freshAgeSeconds,
+}: AccountSessionRoutesOptions): ElysiaPlugin {
+  return new Elysia({ name: "podokit.account.sessions" })
+    .get("/account/sessions", async ({ request, query }) => {
+      const session = await auth.requireSession(request);
+      requireFresh(session, await freshAgeSeconds());
+      const currentId = String(session.session.id);
+      const [page, current] = await Promise.all([
+        sessions.list({ ...query, userId: session.user.id, excludeId: currentId }),
+        sessions.find(currentId),
+      ]);
+      const result: AccountSessionPage = {
+        current: current ? accountView(current) : null,
+        items: page.items.map(accountView),
+        nextCursor: page.nextCursor,
+        total: page.total + (current ? 1 : 0),
+      };
+      return result;
+    }, {
+      query: t.Object({
+        cursor: t.Optional(t.String({ minLength: 1, maxLength: 512 })),
+        limit: t.Optional(t.Numeric({ minimum: 1, maximum: ADMIN_SESSIONS_MAX_LIMIT })),
+      }),
+      detail: {
+        tags: ["account"],
+        summary: "List the current user's active sessions",
+        description: "`current` is the session making the request; `items` are the other sessions, newest first, keyset-paged with `cursor`. Session tokens are never returned. A session older than Better Auth's `session.freshAge` gets 403 `SESSION_NOT_FRESH`, as with `/api/auth/list-sessions`.",
+      },
+    })
+    .delete("/account/sessions/:id", async ({ request, params, set }) => {
+      const session = await auth.requireSession(request);
+      const token = await sessions.tokenOf(params.id, session.user.id);
+      if (!token) throw new AppException(ACCOUNT_SESSION_NOT_FOUND, "Session not found.", 404);
+      await revoke(token, request.headers);
+      set.status = 204;
+    }, {
+      params: t.Object({ id: t.String({ minLength: 1, maxLength: 255 }) }),
+      detail: { tags: ["account"], summary: "Revoke one of the current user's sessions by id" },
+    });
+}