@podosoft/podokit 1.4.2 → 1.6.0

package/dist/templates/fullstack/dot-claude/skills/podokit-update/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: podokit-update
-description: Use when the user wants to update a Bun-based project to a newer PodoKit v1 version, pull in template/module improvements, check local edits, or take ownership of a managed file. Covers podo status/diff/doctor/update/eject.
+description: Use when the user wants to update a Bun-based project to a newer PodoKit v1 version, pull in template/module improvements, check local edits, or take ownership of a managed file. Covers podo status/diff/doctor/update/eject/restore.
 ---
 
 # Keep a PodoKit project up to date
@@ -11,15 +11,18 @@ its own files while keeping the user's changes.
 ```bash
 podo status          # version, modules, file tiers, and how many managed files were edited
 podo diff            # list the PodoKit-managed files you've edited (owned files ignored)
+podo diff <path>     # line diff of one file against the template (owned files too)
 podo doctor          # check framework versions vs. the supported ranges
 podo update          # dry-run: preview what a newer version would change (writes nothing)
 podo update --apply  # apply it — clean updates are written; your edits are 3-way merged
 podo eject <path>    # take ownership of a managed file so update skips it
+podo restore <path>  # rewrite a managed file from the template; re-manages an ejected file
 ```
 
 Rules to respect:
 - **owned** files (routes, your components, `AGENTS.md`, shadcn `ui/**`) are never
-  touched by `update`.
+  touched by `update`. When their template changes, the plan lists them as
+  `review`; compare with `podo diff <path>` and copy what the app needs.
 - **assembled** files are recomputed from the module set — keep edits **outside**
   the `// podokit:begin…end` fences.
 - Run `podo update` (dry-run) first and read the plan before `--apply`. Commit or

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

@@ -12,15 +12,20 @@ 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
 # BACKEND_PROXY_TIMEOUT_MS=30000
-CORS_ORIGIN=http://{{projectName}}.localhost,http://localhost
+# podo dev sets CORS_ORIGIN and BETTER_AUTH_URL for web and api from
+# .podokit/dev.json. These two serve compose.dev.yaml run without podo dev,
+# such as from the devcontainer.
+CORS_ORIGIN={{devCorsOrigin}}
 REDIS_HOST=redis
 REDIS_PORT=6379
 BETTER_AUTH_SECRET=
-BETTER_AUTH_URL=http://{{projectName}}.localhost
+BETTER_AUTH_URL={{devAuthUrl}}
 ADMIN_EMAILS=admin@example.com
 AUDIT_LOG_ENABLED=true
 RATE_LIMIT_TTL=60

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

@@ -3,9 +3,13 @@
 # ── Required (runtime) ───────────────────────────────────────────────
 NODE_ENV=development
 PORT=5002
+# Address the API listens on (default 0.0.0.0); 127.0.0.1 keeps it off the network.
+# HOST=0.0.0.0
 
 # Canonical database connection. Set this for PostgreSQL or SQLite; POSTGRES_* remains a fallback.
 # DATABASE_URL=postgres://podokit:podokit@localhost:5432/podokit
+# With SQLite and no DATABASE_URL, the database file, relative to apps/api.
+# SQLITE_PATH=./data/podokit.sqlite
 POSTGRES_HOST=localhost
 POSTGRES_PORT=5432
 POSTGRES_USER=podokit
@@ -27,6 +31,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 +55,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/dot-podokit/dev.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "hostname": "{{projectName}}.localhost",
+  "hostname": "{{devHostname}}",
   "webSocketPaths": [],
   "apiPaths": []
 }

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

@@ -9,7 +9,11 @@ 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"
   XFF_DEPTH: "1"
+  # podokit:end:runtime-config

package/dist/templates/fullstack/tests/README.md

@@ -13,9 +13,48 @@ The suite runs against a live stack (web on `E2E_BASE_URL`, proxying `/api/*` to
 the API). With the recommended containerized loop, start `podo dev watch` and run:
 
 ```bash
-E2E_BASE_URL=http://{{projectName}}.localhost {{rootRun}} test:e2e
+E2E_BASE_URL=http://{{devHostname}} {{rootRun}} test:e2e
 ```
 
 The default `http://localhost:5001` is for the alternative `{{rootRun}} dev`
 host-process loop. Files ending in `*.api.spec.ts` run in the request-only `api`
 project; `*.ui.spec.ts` run in the chromium `ui` project.
+
+## Workers and exclusive tests
+
+The suite runs on one worker unless `E2E_WORKERS` says otherwise. For the whole
+suite, more workers finish sooner:
+
+```bash
+E2E_WORKERS=2 {{rootRun}} test:e2e
+```
+
+Set the count with `E2E_WORKERS`, not `--workers`: the global setup refuses more
+than one worker when `E2E_WORKERS` is unset.
+
+Every test shares one API, database, mail catcher, and SMS sink. A test that
+changes state other tests rely on takes the `@exclusive` tag:
+
+```ts
+test("maintenance mode holds visitors back", { tag: "@exclusive" }, async ({ page }) => {
+  // ...
+});
+```
+
+Tag a test when it changes a server-wide setting (a feature flag, the
+authentication configuration such as SMTP, social providers, or sign-up
+approval, the site settings, or a module's settings) or the profile of a seeded
+account. Each project has an `<name>-exclusive` twin, such as `ui-exclusive`,
+that runs only the tagged tests, one at a time. With more than one worker the
+twins wait for every other test, so an exclusive test never runs alongside
+another one. Never empty the shared mail catcher or SMS sink in a test: send to
+an address or number of the test's own instead.
+
+More than one worker suits the whole suite. When a run selects exclusive tests
+with a file name, `--grep`, or `--project`, Playwright also runs every other test
+first, because the twins depend on them, and a test that fails there marks the
+exclusive tests as not run. Use the default single worker for a few files, and
+do not combine `--no-deps` with `E2E_WORKERS` above 1.
+
+Application-owned projects in `playwright.projects.cjs` get twins too. A project
+that another project depends on is a setup project and keeps a single copy.

package/dist/templates/fullstack/tests/helpers/app-paths.ts

@@ -0,0 +1,18 @@
+import type { AppPaths } from "./paths";
+
+/**
+ * Where this application's screens differ from the generated ones, for the
+ * managed e2e specs. PodoKit creates this file once and never overwrites it.
+ * Set only what differs; `paths.ts` documents each entry and its default. For
+ * example, an app whose first screen is a signed-in workspace without a
+ * heading, and which shows no public footer:
+ *
+ * ```ts
+ * export const appPaths: Partial<AppPaths> = {
+ *   homeReady: (page) => page.getByTestId("workspace"),
+ *   indexable: [],
+ *   footer: null,
+ * };
+ * ```
+ */
+export const appPaths: Partial<AppPaths> = {};

package/dist/templates/fullstack/tests/helpers/paths.ts

@@ -0,0 +1,33 @@
+import type { Locator, Page } from "@playwright/test";
+import { appPaths } from "./app-paths";
+
+/**
+ * The application screens managed specs visit. The defaults describe the
+ * generated pages; `app-paths.ts`, which the application owns, overrides any
+ * of them, so a managed spec never needs editing for an app's own screens.
+ */
+export interface AppPaths {
+  /** The first screen a visitor opens. */
+  home: string;
+  /** Visible once the first screen has rendered. */
+  homeReady: (page: Page) => Locator;
+  /** Public pages search engines may index: they carry no `X-Robots-Tag`. */
+  indexable: string[];
+  /** A public page that renders the managed `SiteFooter`, or null when none does. */
+  footer: string | null;
+  /**
+   * A page that renders the managed `LanguageSwitch`, `ThemeToggle`, and
+   * `AccountMenu` for a signed-in user, or null when none does.
+   */
+  accountMenu: string | null;
+}
+
+const defaults: AppPaths = {
+  home: "/",
+  homeReady: (page) => page.getByRole("heading", { level: 1 }),
+  indexable: ["/"],
+  footer: "/login",
+  accountMenu: "/",
+};
+
+export const paths: AppPaths = { ...defaults, ...appPaths };

package/dist/templates/fullstack/tests/package.json

@@ -4,8 +4,8 @@
   "private": true,
   "scripts": {
     "test:e2e": "bunx playwright test",
-    "test:e2e:ui": "bunx playwright test --project=ui",
-    "test:e2e:api": "bunx playwright test --project=api",
+    "test:e2e:ui": "bunx playwright test --project=ui --project=ui-exclusive",
+    "test:e2e:api": "bunx playwright test --project=api --project=api-exclusive",
     "test:e2e:report": "bunx playwright show-report"
   },
   "devDependencies": {

package/dist/templates/fullstack/tests/playwright.config.ts

@@ -1,11 +1,14 @@
 import { defineConfig, devices } from "@playwright/test";
-import { loadPlaywrightProjects } from "./playwright.extensions";
+import { e2eWorkers, loadPlaywrightProjects, withExclusivePhase } from "./playwright.extensions";
 
 // The suite runs against a live stack: web on E2E_BASE_URL (proxying /api/* to
 // the API). Start it first (see docs/testing.md) — locally via the dev harness,
 // in CI via scripts/e2e-ci.mjs. Two projects: `api` (request-only, backend e2e)
 // and `ui` (chromium, pages). Files are routed by suffix (*.api/*.ui.spec.ts).
+// E2E_WORKERS sets the worker count (default 1); tests tagged @exclusive run in
+// `<project>-exclusive` twins after the others (see playwright.extensions.ts).
 const baseURL = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const workers = e2eWorkers();
 const coreProjects = [
   { name: "api", testMatch: /.*\.api\.spec\.ts/ },
   { name: "ui", testMatch: /.*\.ui\.spec\.ts/, use: { ...devices["Desktop Chrome"] } },
@@ -16,12 +19,13 @@ export default defineConfig({
   fullyParallel: true,
   forbidOnly: !!process.env.CI,
   retries: process.env.CI ? 2 : 0,
-  workers: process.env.CI ? 1 : undefined,
+  workers,
+  globalSetup: "./playwright.extensions.ts",
   reporter: [["list"], ["html", { open: "never" }]],
   use: {
     baseURL,
     trace: "on-first-retry",
     screenshot: "only-on-failure",
   },
-  projects: [...coreProjects, ...loadPlaywrightProjects(coreProjects)],
+  projects: withExclusivePhase([...coreProjects, ...loadPlaywrightProjects(coreProjects)], workers),
 });

package/dist/templates/fullstack/tests/playwright.extensions.ts

@@ -1,17 +1,33 @@
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { join } from "node:path";
-import type { PlaywrightTestConfig } from "@playwright/test";
+import type { FullConfig, PlaywrightTestConfig } from "@playwright/test";
 
 type Projects = NonNullable<PlaywrightTestConfig["projects"]>;
+type Project = Projects[number];
 
 const requireFromTests = createRequire(__filename);
 
+// A test that changes state the other tests rely on, such as a server-wide
+// setting or the profile of a seeded account, takes the `@exclusive` tag:
+//
+//   test("maintenance mode holds visitors back", { tag: "@exclusive" }, async ({ page }) => { ... });
+//
+// Playwright matches project grep patterns against the title path followed by
+// the test's tags, separated by spaces.
+const TAGGED = /(?:^|\s)@exclusive(?=\s|$)/;
+const UNTAGGED = /^(?![\s\S]*(?:^|\s)@exclusive(?=\s|$))/;
+
 function projectName(project: unknown): string | null {
   if (typeof project !== "object" || project === null || !("name" in project)) return null;
   return typeof project.name === "string" && project.name.length > 0 ? project.name : null;
 }
 
+function patterns(value: Project["grepInvert"]): RegExp[] {
+  if (value === undefined) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
 /**
  * Merge application-owned Playwright projects into PodoKit's managed config.
  * The optional CommonJS file stays owned so applications can add devices and
@@ -42,3 +58,74 @@ export function loadPlaywrightProjects(coreProjects: Projects): Projects {
 
   return loaded as Projects;
 }
+
+/** The number of Playwright workers: `E2E_WORKERS`, or 1 when it is unset. */
+export function e2eWorkers(value = process.env.E2E_WORKERS): number {
+  if (value === undefined || value.trim() === "") return 1;
+  const workers = Number(value);
+  if (!Number.isInteger(workers) || workers < 1) {
+    throw new Error(`E2E_WORKERS must be a whole number of at least 1, got "${value}".`);
+  }
+  return workers;
+}
+
+/**
+ * Splits each test project into one that skips tests tagged `@exclusive` and an
+ * `<name>-exclusive` twin that runs only them on one worker. Projects that
+ * another project depends on, or that tear one down, are setup and cleanup
+ * projects and stay as they are.
+ *
+ * With more than one worker the twins depend on every other test project, and
+ * each twin on the one before it, so an exclusive test never runs alongside
+ * another test. A dependency runs in full, though: a run that selects only
+ * exclusive tests, with a file, `--grep`, or `--project`, then also runs every
+ * other test first, and a test that fails there skips the exclusive tests. Use
+ * more than one worker for the whole suite. With one worker no dependency is
+ * needed, so filtered runs stay small.
+ */
+export function withExclusivePhase(projects: Projects, workers: number): Projects {
+  const support = new Set(
+    projects.flatMap((project) => [...(project.dependencies ?? []), ...(project.teardown ? [project.teardown] : [])]),
+  );
+  const tested = projects.filter((project) => !support.has(projectName(project) ?? ""));
+  const shared = new Map(
+    tested.map((project) => [project, { ...project, grepInvert: [...patterns(project.grepInvert), TAGGED] }]),
+  );
+
+  let before = [...shared.values()].map((project) => projectName(project) ?? "");
+  const twins = tested.map((project) => {
+    const name = `${projectName(project) ?? ""}-exclusive`;
+    const twin: Project = {
+      ...project,
+      name,
+      grepInvert: [...patterns(project.grepInvert), UNTAGGED],
+      workers: 1,
+      dependencies: workers > 1 ? [...(project.dependencies ?? []), ...before] : project.dependencies,
+    };
+    before = [name];
+    return twin;
+  });
+
+  const result = [...projects.map((project) => shared.get(project) ?? project), ...twins];
+  const names = new Set<string>();
+  for (const project of result) {
+    const name = projectName(project) ?? "";
+    if (names.has(name)) throw new Error(`Duplicate Playwright project name: ${name}`);
+    names.add(name);
+  }
+  return result;
+}
+
+/**
+ * Global setup: refuses more workers than `E2E_WORKERS` allows for. `--workers`
+ * changes the count after the projects were built, so with it the exclusive
+ * twins would run alongside the other tests.
+ */
+export default function checkWorkers(config: FullConfig): void {
+  if (config.workers > 1 && e2eWorkers() === 1) {
+    throw new Error(
+      `Set the worker count with E2E_WORKERS=${config.workers} instead of --workers. ` +
+        "Tests tagged @exclusive run after the others only when E2E_WORKERS is above 1.",
+    );
+  }
+}

package/dist/templates/fullstack/tests/ui/smoke.ui.spec.ts

@@ -1,9 +1,10 @@
 import { expect, test } from "@playwright/test";
+import { paths } from "../helpers/paths";
 
-// Module-agnostic: the app responds at "/" (a page or a redirect to it).
+// Module-agnostic: the app's first screen responds (a page or a redirect to it)
+// and renders. Its locator comes from tests/helpers/app-paths.ts.
 test("app is reachable @smoke", async ({ page }) => {
-  const res = await page.goto("/");
+  const res = await page.goto(paths.home);
   expect(res?.status()).toBeLessThan(400);
-  await expect(page.locator("main")).toBeVisible();
-  await expect(page.getByRole("heading", { level: 1 })).toBeVisible();
+  await expect(paths.homeReady(page)).toBeVisible();
 });

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" },
+    });
+}