@podosoft/podokit 1.1.6 → 1.2.0

package/dist/templates/fullstack/compose.dev.yaml

@@ -1,8 +1,15 @@
 # Containerized Bun development environment.
+#
+# Every service has a memory limit equal to its swap limit, so a runaway process
+# is OOM-killed inside its container instead of exhausting the host. Override a
+# limit with the matching *_MEM_LIMIT variable from the shell or the project's
+# .env file (not .env.docker), e.g. API_MEM_LIMIT=3g podo dev watch.
 name: {{projectName}}-dev
 
 services:
   traefik:
+    mem_limit: ${TRAEFIK_MEM_LIMIT:-256m}
+    memswap_limit: ${TRAEFIK_MEM_LIMIT:-256m}
     profiles: [podokit-legacy-proxy]
     image: traefik:v3.5
     command:
@@ -19,6 +26,8 @@ services:
     networks: [podokit]
 
   web:
+    mem_limit: ${WEB_MEM_LIMIT:-2g}
+    memswap_limit: ${WEB_MEM_LIMIT:-2g}
     build:
       context: .
       dockerfile: Dockerfile.dev
@@ -42,6 +51,8 @@ services:
         - { action: rebuild, path: ./apps/web/package.json }
 
   api:
+    mem_limit: ${API_MEM_LIMIT:-2g}
+    memswap_limit: ${API_MEM_LIMIT:-2g}
     build:
       context: .
       dockerfile: Dockerfile.dev
@@ -61,6 +72,8 @@ services:
         - { action: rebuild, path: ./apps/api/package.json }
 
   worker:
+    mem_limit: ${WORKER_MEM_LIMIT:-1g}
+    memswap_limit: ${WORKER_MEM_LIMIT:-1g}
     profiles: [queue]
     build:
       context: .
@@ -81,6 +94,8 @@ services:
         - { action: rebuild, path: ./apps/api/package.json }
 
   postgres:
+    mem_limit: ${POSTGRES_MEM_LIMIT:-1g}
+    memswap_limit: ${POSTGRES_MEM_LIMIT:-1g}
     image: postgres:16-alpine
     environment:
       POSTGRES_USER: podokit
@@ -96,11 +111,15 @@ services:
     networks: [podokit]
 
   redis:
+    mem_limit: ${REDIS_MEM_LIMIT:-256m}
+    memswap_limit: ${REDIS_MEM_LIMIT:-256m}
     profiles: [cache]
     image: redis:7-alpine
     networks: [podokit]
 
   minio:
+    mem_limit: ${MINIO_MEM_LIMIT:-512m}
+    memswap_limit: ${MINIO_MEM_LIMIT:-512m}
     profiles: [storage]
     image: pgsty/silo:RELEASE.2026-09-16T00-00-00Z
     command: server /data --console-address ":9001"
@@ -112,6 +131,8 @@ services:
     networks: [podokit]
 
   minio-init:
+    mem_limit: ${MINIO_INIT_MEM_LIMIT:-128m}
+    memswap_limit: ${MINIO_INIT_MEM_LIMIT:-128m}
     profiles: [storage]
     image: pgsty/mc:RELEASE.2026-09-16T00-00-00Z
     depends_on:

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

@@ -1,3 +1,6 @@
+# Container environment for compose.dev.yaml. Compose does not interpolate
+# from this file: set container memory limits such as API_MEM_LIMIT=3g in the
+# shell or the project's .env file instead.
 NODE_ENV=development
 PORT=5002
 POSTGRES_HOST=postgres

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

@@ -12,6 +12,20 @@ POSTGRES_USER=podokit
 POSTGRES_PASSWORD=podokit
 POSTGRES_DB=podokit
 
+# PostgreSQL pools. Each API replica opens up to DB_POOL_MAX connections for
+# queries, plus DB_AUTH_POOL_MAX for the auth module when it is installed. Keep
+# replicas x (DB_POOL_MAX + DB_AUTH_POOL_MAX), plus a few for migrations, below
+# the server's max_connections (100 by default). The timeouts are milliseconds.
+# DB_POOL_MAX=20
+# DB_CONNECT_TIMEOUT_MS=10000
+# DB_IDLE_TIMEOUT_MS=30000
+# DB_AUTH_POOL_MAX=10
+
+# 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).
+# READINESS_CHECK_TIMEOUT_MS=800
+# READINESS_CACHE_MS=2000
+
 # Web -> API boundary (server-side only; not exposed to the browser)
 BACKEND_INTERNAL_URL=http://localhost:5002
 

package/dist/templates/fullstack/infra/k3s/api-deployment.yaml

@@ -24,6 +24,8 @@ spec:
           readinessProbe:
             httpGet: { path: /health/ready, port: 3000 }
             initialDelaySeconds: 5
+            timeoutSeconds: 2
           livenessProbe:
             httpGet: { path: /health, port: 3000 }
             initialDelaySeconds: 15
+            timeoutSeconds: 2

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

@@ -0,0 +1,25 @@
+import { describe, expect, mock, test } from "bun:test";
+import { APIError } from "better-auth/api";
+import { createSessionRevoker, type RevokeUserSessionApi } from "./admin-sessions.revoker";
+
+describe("createSessionRevoker", () => {
+  test("revokes through the audited Better Auth admin endpoint as the caller", async () => {
+    const revokeUserSession = mock<RevokeUserSessionApi["revokeUserSession"]>(async () => ({ success: true }));
+    const headers = new Headers({ cookie: "admin-session=1" });
+
+    await createSessionRevoker(() => ({ revokeUserSession }))("secret-token", headers);
+
+    expect(revokeUserSession).toHaveBeenCalledWith({ body: { sessionToken: "secret-token" }, headers });
+  });
+
+  test("reports Better Auth refusals with the standard error shape", async () => {
+    const revoker = createSessionRevoker(() => ({
+      revokeUserSession: async (): Promise<unknown> => {
+        throw new APIError("FORBIDDEN", { message: "You are not allowed to revoke users sessions" });
+      },
+    }));
+
+    await expect(revoker("secret-token", new Headers()))
+      .rejects.toMatchObject({ code: "ADMIN_SESSION_REVOKE_FAILED", statusCode: 403 });
+  });
+});

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

@@ -0,0 +1,26 @@
+import { AppException } from "@podosoft/podokit-contracts";
+import { APIError } from "better-auth/api";
+import type { SessionRevoker } from "./admin-sessions.routes";
+
+export const ADMIN_SESSION_REVOKE_FAILED = "ADMIN_SESSION_REVOKE_FAILED";
+
+export interface RevokeUserSessionApi {
+  revokeUserSession(input: { body: { sessionToken: string }; headers: Headers }): Promise<unknown>;
+}
+
+/**
+ * Revokes through the Better Auth admin endpoint rather than deleting the row, so
+ * its permission check and after-hooks (including the audit log) still run.
+ */
+export function createSessionRevoker(api: () => RevokeUserSessionApi): SessionRevoker {
+  return async (sessionToken, headers) => {
+    try {
+      await api().revokeUserSession({ body: { sessionToken }, headers });
+    } catch (error) {
+      if (error instanceof APIError) {
+        throw new AppException(ADMIN_SESSION_REVOKE_FAILED, error.message, error.statusCode);
+      }
+      throw error;
+    }
+  };
+}

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

@@ -0,0 +1,122 @@
+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 { adminSessionRoutes, type SessionRevoker } from "./admin-sessions.routes";
+import { AdminSessionsService } from "./admin-sessions.service";
+
+type Auth = Pick<AuthService, "requireAdmin">;
+
+// Callers identify themselves with a test header; only "admin" passes.
+const auth: Auth = {
+  requireAdmin: async (request: Request): Promise<AuthSession> => {
+    const role = request.headers.get("x-test-role");
+    if (!role) throw new AppException("AUTH_REQUIRED", "Authentication is required", 401);
+    if (role !== "admin") throw new AppException("ADMIN_REQUIRED", "Administrator access is required", 403);
+    return { user: { id: "admin-1", role: "admin" }, session: {} };
+  },
+};
+
+interface Reply {
+  status: number;
+  text: string;
+}
+
+describe("admin session routes", () => {
+  let db: SQL;
+  let revoke: Mock<SessionRevoker>;
+  let handle: (request: Request) => Promise<Response>;
+
+  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', 'user@example.com', 'User')`;
+    const future = new Date(Date.now() + 86_400_000).toISOString();
+    await db`
+      INSERT INTO "session" VALUES
+        ('session-1', 'user-1', 'secret-token-1', NULL, NULL, NULL, '2026-01-01T00:00:01.000Z', ${future}),
+        ('session-2', 'user-1', 'secret-token-2', NULL, NULL, NULL, '2026-01-01T00:00:02.000Z', ${future})
+    `;
+    revoke = mock<SessionRevoker>(async () => undefined);
+    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(adminSessionRoutes({ auth, sessions: new AdminSessionsService(db, "sqlite"), revoke }));
+    handle = (request) => app.handle(request);
+  });
+
+  afterEach(async () => {
+    await db.close();
+  });
+
+  async function send(path: string, init: RequestInit = {}, role: string | null = "admin"): Promise<Reply> {
+    const headers = new Headers(init.headers);
+    if (role) headers.set("x-test-role", role);
+    const response = await handle(new Request(`http://localhost${path}`, { ...init, headers }));
+    return { status: response.status, text: await response.text() };
+  }
+
+  test("lists sessions for administrators without exposing tokens", async () => {
+    const reply = await send("/admin/sessions?limit=1");
+
+    expect(reply.status).toBe(200);
+    const body = JSON.parse(reply.text) as { items: Array<{ id: string }>; nextCursor: string | null; total: number };
+    expect(body.items.map((item) => item.id)).toEqual(["session-2"]);
+    expect(body.total).toBe(2);
+    expect(reply.text).not.toContain("secret-token");
+
+    const next = await send(`/admin/sessions?limit=1&cursor=${encodeURIComponent(body.nextCursor ?? "")}`);
+    expect(JSON.parse(next.text)).toMatchObject({ items: [{ id: "session-1" }], nextCursor: null });
+  });
+
+  test("refuses anonymous callers and non-administrators", async () => {
+    expect((await send("/admin/sessions", {}, null)).status).toBe(401);
+    expect((await send("/admin/sessions", {}, "user")).status).toBe(403);
+    expect((await send("/admin/sessions/session-1", { method: "DELETE" }, "user")).status).toBe(403);
+    expect(revoke).not.toHaveBeenCalled();
+  });
+
+  test("validates paging input", async () => {
+    expect((await send("/admin/sessions?limit=1000")).status).toBe(400);
+    expect(JSON.parse((await send("/admin/sessions?cursor=forged")).text))
+      .toEqual({ code: "ADMIN_SESSION_CURSOR_INVALID" });
+  });
+
+  test("revokes by id with the token looked up on the server", async () => {
+    const reply = await send("/admin/sessions/session-1", {
+      method: "DELETE",
+      headers: { cookie: "admin-session=1" },
+    });
+
+    expect(reply.status).toBe(204);
+    expect(revoke).toHaveBeenCalledTimes(1);
+    const [token, headers] = revoke.mock.calls[0] ?? [];
+    expect(token).toBe("secret-token-1");
+    expect(headers?.get("cookie")).toBe("admin-session=1");
+  });
+
+  test("reports an unknown session without revoking anything", async () => {
+    const reply = await send("/admin/sessions/missing", { method: "DELETE" });
+
+    expect(reply.status).toBe(404);
+    expect(JSON.parse(reply.text)).toEqual({ code: "ADMIN_SESSION_NOT_FOUND" });
+    expect(revoke).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,46 @@
+import { AppException } from "@podosoft/podokit-contracts";
+import { Elysia, t } from "elysia";
+import type { AuthService } from "../auth/auth.service";
+import type { ElysiaPlugin } from "../core/services";
+import { ADMIN_SESSIONS_MAX_LIMIT, type AdminSessionsService } from "./admin-sessions.service";
+
+export const ADMIN_SESSION_NOT_FOUND = "ADMIN_SESSION_NOT_FOUND";
+
+/** Revokes one session by its bearer token on behalf of the requesting administrator. */
+export type SessionRevoker = (sessionToken: string, headers: Headers) => Promise<void>;
+
+export interface AdminSessionRoutesOptions {
+  auth: Pick<AuthService, "requireAdmin">;
+  sessions: AdminSessionsService;
+  revoke: SessionRevoker;
+}
+
+export function adminSessionRoutes({ auth, sessions, revoke }: AdminSessionRoutesOptions): ElysiaPlugin {
+  return new Elysia({ name: "podokit.admin.sessions" })
+    .get("/admin/sessions", async ({ request, query }) => {
+      await auth.requireAdmin(request);
+      return sessions.list(query);
+    }, {
+      query: t.Object({
+        cursor: t.Optional(t.String({ minLength: 1, maxLength: 512 })),
+        limit: t.Optional(t.Numeric({ minimum: 1, maximum: ADMIN_SESSIONS_MAX_LIMIT })),
+        search: t.Optional(t.String({ maxLength: 200 })),
+        userId: t.Optional(t.String({ minLength: 1, maxLength: 255 })),
+      }),
+      detail: {
+        tags: ["admin"],
+        summary: "List active sessions across users",
+        description: "Newest first, keyset-paged with `cursor`. `search` matches the user's email or name case-insensitively. Session tokens are never returned.",
+      },
+    })
+    .delete("/admin/sessions/:id", async ({ request, params, set }) => {
+      await auth.requireAdmin(request);
+      const token = await sessions.tokenOf(params.id);
+      if (!token) throw new AppException(ADMIN_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: ["admin"], summary: "Revoke a session by id" },
+    });
+}

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

@@ -0,0 +1,187 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { SQL } from "bun";
+import { AdminSessionsService, type AdminSessionView } from "./admin-sessions.service";
+
+const DAY_MS = 86_400_000;
+
+interface SeedSession {
+  id: string;
+  userId: string;
+  createdAt: string;
+  expiresAt?: string;
+}
+
+async function createSchema(db: SQL): Promise<void> {
+  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
+    )
+  `;
+}
+
+async function seed(db: SQL, sessions: SeedSession[]): Promise<void> {
+  const future = new Date(Date.now() + DAY_MS).toISOString();
+  for (const session of sessions) {
+    await db`
+      INSERT INTO "session" VALUES (
+        ${session.id}, ${session.userId}, ${`token-${session.id}`}, '203.0.113.7', 'Agent', NULL,
+        ${session.createdAt}, ${session.expiresAt ?? future}
+      )
+    `;
+  }
+}
+
+async function collect(service: AdminSessionsService, limit: number, search?: string): Promise<{
+  pages: number;
+  items: AdminSessionView[];
+}> {
+  const items: AdminSessionView[] = [];
+  let cursor: string | undefined;
+  let pages = 0;
+  do {
+    const page = await service.list({ limit, cursor, search });
+    pages += 1;
+    items.push(...page.items);
+    cursor = page.nextCursor ?? undefined;
+  } while (cursor);
+  return { pages, items };
+}
+
+describe("AdminSessionsService", () => {
+  let db: SQL;
+  let service: AdminSessionsService;
+
+  beforeEach(async () => {
+    db = new SQL(":memory:");
+    await createSchema(db);
+    await db`
+      INSERT INTO "user" VALUES
+        ('alice', 'alice@example.com', 'Alice Smith'),
+        ('bob', 'bob_admin@example.com', 'Bob'),
+        ('carol', 'carol@example.com', 'Carol 100%')
+    `;
+    service = new AdminSessionsService(db, "sqlite");
+  });
+
+  afterEach(async () => {
+    await db.close();
+  });
+
+  test("pages through every active session newest first without gaps or repeats", async () => {
+    const base = Date.parse("2026-01-01T00:00:00.000Z");
+    const owners = ["alice", "bob", "carol"];
+    // Pairs share a creation time so the id tiebreaker decides the order.
+    await seed(db, Array.from({ length: 11 }, (_, index) => ({
+      id: `s${String(index).padStart(2, "0")}`,
+      userId: owners[index % owners.length] ?? "alice",
+      createdAt: new Date(base + Math.floor(index / 2) * 1_000).toISOString(),
+    })));
+
+    const { pages, items } = await collect(service, 4);
+
+    expect(pages).toBe(3);
+    expect(items.map((item) => item.id)).toEqual([
+      "s10", "s09", "s08", "s07", "s06", "s05", "s04", "s03", "s02", "s01", "s00",
+    ]);
+    const first = await service.list({ limit: 4 });
+    expect(first.total).toBe(11);
+    expect(first.nextCursor).toEqual(expect.any(String));
+  });
+
+  test("returns only active sessions", async () => {
+    await seed(db, [
+      { id: "live", userId: "alice", createdAt: "2026-01-01T00:00:00.000Z" },
+      {
+        id: "expired",
+        userId: "alice",
+        createdAt: "2026-01-02T00:00:00.000Z",
+        expiresAt: new Date(Date.now() - 1_000).toISOString(),
+      },
+    ]);
+
+    const page = await service.list();
+
+    expect(page.items.map((item) => item.id)).toEqual(["live"]);
+    expect(page.total).toBe(1);
+    expect(page.nextCursor).toBeNull();
+  });
+
+  test("searches the user's email or name case-insensitively and literally", async () => {
+    await seed(db, [
+      { id: "a", userId: "alice", createdAt: "2026-01-01T00:00:01.000Z" },
+      { id: "b", userId: "bob", createdAt: "2026-01-01T00:00:02.000Z" },
+      { id: "c", userId: "carol", createdAt: "2026-01-01T00:00:03.000Z" },
+    ]);
+
+    expect((await service.list({ search: "ALICE@" })).items.map((item) => item.id)).toEqual(["a"]);
+    expect((await service.list({ search: "smith" })).items.map((item) => item.id)).toEqual(["a"]);
+    // LIKE wildcards in the query match themselves, not every row.
+    expect((await service.list({ search: "_" })).items.map((item) => item.id)).toEqual(["b"]);
+    expect((await service.list({ search: "%" })).items.map((item) => item.id)).toEqual(["c"]);
+    expect((await service.list({ search: "  " })).total).toBe(3);
+    const searched = await collect(service, 1, "example.com");
+    expect(searched.items.map((item) => item.id)).toEqual(["c", "b", "a"]);
+  });
+
+  test("narrows the list to one user", async () => {
+    await seed(db, [
+      { id: "a1", userId: "alice", createdAt: "2026-01-01T00:00:01.000Z" },
+      { id: "b1", userId: "bob", createdAt: "2026-01-01T00:00:02.000Z" },
+      { id: "a2", userId: "alice", createdAt: "2026-01-01T00:00:03.000Z" },
+    ]);
+
+    const page = await service.list({ userId: "alice" });
+
+    expect(page.items.map((item) => item.id)).toEqual(["a2", "a1"]);
+    expect(page.total).toBe(2);
+  });
+
+  test("returns user details without the session token", async () => {
+    await seed(db, [{ id: "a", userId: "alice", createdAt: "2026-01-01T00:00:01.000Z" }]);
+
+    const [item] = (await service.list()).items;
+
+    expect(item).toEqual({
+      id: "a",
+      userId: "alice",
+      userEmail: "alice@example.com",
+      userName: "Alice Smith",
+      ipAddress: "203.0.113.7",
+      userAgent: "Agent",
+      impersonatedBy: null,
+      createdAt: "2026-01-01T00:00:01.000Z",
+      expiresAt: expect.any(String),
+    });
+    expect(JSON.stringify(item)).not.toContain("token-a");
+  });
+
+  test("rejects a cursor it did not issue", async () => {
+    await expect(service.list({ cursor: "not-a-cursor" }))
+      .rejects.toMatchObject({ code: "ADMIN_SESSION_CURSOR_INVALID", statusCode: 400 });
+    const forged = Buffer.from(JSON.stringify(["not a date", "id"])).toString("base64url");
+    await expect(service.list({ cursor: forged }))
+      .rejects.toMatchObject({ code: "ADMIN_SESSION_CURSOR_INVALID", statusCode: 400 });
+  });
+
+  test("keeps the page size within bounds", async () => {
+    const base = Date.parse("2026-01-01T00:00:00.000Z");
+    await seed(db, Array.from({ length: 3 }, (_, index) => ({
+      id: `s${index}`,
+      userId: "alice",
+      createdAt: new Date(base + index * 1_000).toISOString(),
+    })));
+
+    expect((await service.list({ limit: 0 })).items).toHaveLength(1);
+    expect((await service.list({ limit: 1_000 })).items).toHaveLength(3);
+  });
+
+  test("looks up a session token by id on the server", async () => {
+    await seed(db, [{ id: "a", userId: "alice", createdAt: "2026-01-01T00:00:01.000Z" }]);
+
+    expect(await service.tokenOf("a")).toBe("token-a");
+    expect(await service.tokenOf("missing")).toBeNull();
+  });
+});

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

@@ -0,0 +1,160 @@
+import { AppException } from "@podosoft/podokit-contracts";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import type { SQL } from "bun";
+
+export const ADMIN_SESSION_CURSOR_INVALID = "ADMIN_SESSION_CURSOR_INVALID";
+export const ADMIN_SESSIONS_DEFAULT_LIMIT = 20;
+export const ADMIN_SESSIONS_MAX_LIMIT = 100;
+
+/** An active session as administrators see it. The bearer token never leaves the server. */
+export interface AdminSessionView {
+  id: string;
+  userId: string;
+  userEmail: string;
+  userName: string;
+  ipAddress: string | null;
+  userAgent: string | null;
+  impersonatedBy: string | null;
+  createdAt: string;
+  expiresAt: string;
+}
+
+export interface AdminSessionPage {
+  items: AdminSessionView[];
+  nextCursor: string | null;
+  total: number;
+}
+
+export interface AdminSessionQuery {
+  limit?: number;
+  cursor?: string;
+  search?: string;
+  userId?: string;
+}
+
+interface SessionRow {
+  id: string;
+  userId: string;
+  userEmail: string;
+  userName: string | null;
+  ipAddress: string | null;
+  userAgent: string | null;
+  impersonatedBy: string | null;
+  createdAt: Date | string;
+  expiresAt: Date | string;
+  cursorAt: string;
+}
+
+interface Cursor {
+  createdAt: string;
+  id: string;
+}
+
+function iso(value: Date | string): string {
+  return (value instanceof Date ? value : new Date(value)).toISOString();
+}
+
+function encodeCursor(cursor: Cursor): string {
+  return Buffer.from(JSON.stringify([cursor.createdAt, cursor.id])).toString("base64url");
+}
+
+function decodeCursor(value: string): Cursor {
+  try {
+    const parsed: unknown = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+    if (
+      Array.isArray(parsed) &&
+      parsed.length === 2 &&
+      typeof parsed[0] === "string" &&
+      typeof parsed[1] === "string" &&
+      !Number.isNaN(Date.parse(parsed[0]))
+    ) {
+      return { createdAt: parsed[0], id: parsed[1] };
+    }
+  } catch {
+    // Reported below as one stable error code.
+  }
+  throw new AppException(ADMIN_SESSION_CURSOR_INVALID, "The sessions cursor is invalid.", 400);
+}
+
+function likePattern(search: string): string {
+  return `%${search.replace(/[\\%_]/g, (character) => `\\${character}`)}%`;
+}
+
+/**
+ * Lists active sessions across users with keyset paging on ("createdAt", "id"),
+ * so a page costs one bounded query however many users or sessions exist.
+ */
+export class AdminSessionsService {
+  constructor(
+    private readonly sql: SQL,
+    private readonly provider: DatabaseProviderName,
+  ) {}
+
+  async list(query: AdminSessionQuery = {}): Promise<AdminSessionPage> {
+    const limit = Math.min(Math.max(query.limit ?? ADMIN_SESSIONS_DEFAULT_LIMIT, 1), ADMIN_SESSIONS_MAX_LIMIT);
+    const cursor = query.cursor ? decodeCursor(query.cursor) : undefined;
+    const search = query.search?.trim() ?? "";
+    // ISO-8601 text matches the SQLite storage format and still compares as a
+    // timestamp against PostgreSQL timestamptz columns.
+    const now = new Date().toISOString();
+    const filters = (): SQL.Query<unknown> => this.sql`
+      WHERE s."expiresAt" > ${now}
+      ${query.userId ? this.sql`AND s."userId" = ${query.userId}` : this.sql``}
+      ${search ? this.searchFilter(likePattern(search)) : this.sql``}
+    `;
+    const [rows, totals] = await Promise.all([
+      this.sql<SessionRow[]>`
+        SELECT s."id", s."userId", u."email" AS "userEmail", u."name" AS "userName",
+               s."ipAddress", s."userAgent", s."impersonatedBy", s."createdAt", s."expiresAt",
+               CAST(s."createdAt" AS TEXT) AS "cursorAt"
+        FROM "session" s
+        JOIN "user" u ON u."id" = s."userId"
+        ${filters()}
+        ${cursor
+          ? this.sql`AND (s."createdAt" < ${cursor.createdAt}
+              OR (s."createdAt" = ${cursor.createdAt} AND s."id" < ${cursor.id}))`
+          : this.sql``}
+        ORDER BY s."createdAt" DESC, s."id" DESC
+        LIMIT ${limit + 1}
+      `,
+      this.sql<Array<{ total: number | string | bigint }>>`
+        SELECT COUNT(*) AS "total"
+        FROM "session" s
+        JOIN "user" u ON u."id" = s."userId"
+        ${filters()}
+      `,
+    ]);
+    const page = rows.slice(0, limit);
+    const last = page.at(-1);
+    return {
+      items: page.map((row) => ({
+        id: row.id,
+        userId: row.userId,
+        userEmail: row.userEmail,
+        userName: row.userName ?? "",
+        ipAddress: row.ipAddress,
+        userAgent: row.userAgent,
+        impersonatedBy: row.impersonatedBy,
+        createdAt: iso(row.createdAt),
+        expiresAt: iso(row.expiresAt),
+      })),
+      // The cursor keeps the database's own text form so sub-millisecond
+      // timestamps cannot skip or repeat rows at a page boundary.
+      nextCursor: rows.length > limit && last ? encodeCursor({ createdAt: last.cursorAt, id: last.id }) : null,
+      total: Number(totals[0]?.total ?? 0),
+    };
+  }
+
+  async tokenOf(sessionId: string): Promise<string | null> {
+    const rows = await this.sql<Array<{ token: string }>>`
+      SELECT "token" FROM "session" WHERE "id" = ${sessionId}
+    `;
+    return rows[0]?.token ?? null;
+  }
+
+  private searchFilter(pattern: string): SQL.Query<unknown> {
+    return this.provider === "sqlite"
+      ? this.sql`AND (u."email" LIKE ${pattern} ESCAPE '\\' OR u."name" LIKE ${pattern} ESCAPE '\\')`
+      : this.sql`AND (u."email" ILIKE ${pattern} ESCAPE '\\' OR u."name" ILIKE ${pattern} ESCAPE '\\')`;
+  }
+}