@podosoft/podokit 1.2.0 → 1.4.0

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

@@ -16,11 +16,18 @@ POSTGRES_DB=podokit
 # 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_QUERY_TIMEOUT_MS bounds how long a query waits for a server that stopped
+# answering; migrations and maintenance commands are not bounded.
 # DB_POOL_MAX=20
 # DB_CONNECT_TIMEOUT_MS=10000
 # DB_IDLE_TIMEOUT_MS=30000
+# DB_QUERY_TIMEOUT_MS=10000
 # DB_AUTH_POOL_MAX=10
 
+# 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
+
 # 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
@@ -44,3 +51,6 @@ REDIS_DB=0
 # REDIS_USERNAME=
 # REDIS_PASSWORD=
 REDIS_TLS=false
+# Longest wait in milliseconds for Redis to answer one command. A command that
+# gets no reply in time fails, and its connection is closed and reopened.
+# REDIS_COMMAND_TIMEOUT_MS=1000

package/dist/templates/fullstack/dot-gitignore

@@ -5,6 +5,7 @@ build/
 .env
 .env.*
 !.env.example
+!.env.docker.example
 .DS_Store
 *.log
 

package/dist/templates/fullstack/dot-podokit/dev.json

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

package/dist/templates/fullstack/infra/k3s/README.md

@@ -20,4 +20,6 @@ branch tags, and empty tags, and so should you.
 For a hand-managed API WebSocket endpoint, add a `pathType: Exact` Ingress path to
 the API service before the existing `/` web path. Do not route a prefix or the root
 to API. Deployment profiles express the same rule with
-`exposure.webSocketPaths` and validate it before rendering.
+`exposure.webSocketPaths` and validate it before rendering. A large-upload route
+under `/api/` needs `/api` removed on the way to the API; `exposure.apiPaths`
+renders a separate Ingress with a Traefik `stripPrefix` Middleware for that.

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

@@ -1,9 +1,9 @@
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { join } from "node:path";
-import type { TestConfig } from "@playwright/test";
+import type { PlaywrightTestConfig } from "@playwright/test";
 
-type Projects = NonNullable<TestConfig["projects"]>;
+type Projects = NonNullable<PlaywrightTestConfig["projects"]>;
 
 const requireFromTests = createRequire(__filename);
 

package/dist/templates/modules/admin-dashboard/files/apps/api/scripts/bootstrap-admin.mjs

@@ -1,7 +1,11 @@
 #!/usr/bin/env bun
 
+import { existsSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 
+const compiledRuntime = new URL("../dist/bootstrap-admin-runtime.js", import.meta.url);
+const sourceRuntime = new URL("../src/bootstrap-admin-runtime.ts", import.meta.url);
+
 const args = process.argv.slice(2);
 
 function has(flag) {
@@ -130,34 +134,15 @@ async function main() {
   }
 
   const input = resolveBootstrapInput();
-  // Load the auth graph before importing one of its dependencies directly.
-  // Concurrent ESM imports can ask Node to link the same Better Auth submodule
-  // through two graph roots and fail before the command reaches the database.
-  const { auth } = await import("../dist/auth/auth.js");
-  const { pool } = await import("../dist/auth/db.js");
-  const { verifyPassword } = await import("better-auth/crypto");
+  // A production image runs the bundled entry; development runs the source.
+  const useCompiled = process.env.NODE_ENV === "production" && existsSync(compiledRuntime);
+  const runtime = await import((useCompiled ? compiledRuntime : sourceRuntime).href);
+  const { auth, findBootstrapUser, verifyPassword, closeAuthDatabase } = runtime;
 
   try {
     const result = await bootstrapAdmin(
       {
-        findUser: async (email) => {
-          const query = await pool.query(
-            `SELECT u.id,
-                    u.email,
-                    u.role,
-                    u."emailVerified" AS "emailVerified",
-                    u."signupApproved" AS "signupApproved",
-                    a.password AS "passwordHash"
-               FROM "user" AS u
-          LEFT JOIN "account" AS a
-                 ON a."userId" = u.id
-                AND a."providerId" = 'credential'
-              WHERE lower(u.email) = lower($1)
-              LIMIT 1`,
-            [email],
-          );
-          return query.rows[0] ?? null;
-        },
+        findUser: findBootstrapUser,
         createUser: async (user) => auth.api.createUser({ body: user }),
         verifyPassword: async (hash, password) => verifyPassword({ hash, password }),
       },
@@ -174,14 +159,24 @@ async function main() {
       console.log(`Verified existing administrator account ${result.email}.`);
     }
   } finally {
-    await pool.end();
+    await closeAuthDatabase();
+  }
+}
+
+// A refused PostgreSQL connection is an AggregateError with an empty message.
+export function errorMessage(error) {
+  if (!(error instanceof Error)) return String(error);
+  if (error.message) return error.message;
+  if (error instanceof AggregateError && error.errors.length > 0) {
+    return error.errors.map(errorMessage).join("; ");
   }
+  return error.name;
 }
 
 const invokedPath = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
 if (invokedPath === import.meta.url) {
   main().catch((error) => {
-    console.error(error instanceof Error ? error.message : String(error));
+    console.error(errorMessage(error));
     process.exitCode = 1;
   });
 }

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

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "bun:test";
+import { Database } from "bun:sqlite";
+import type { QueryRunner } from "typeorm";
+import { revertLatestSqliteMigration, runSqliteMigrations } from "../database/sqlite-migrator";
+import { IndexSessionCreatedAt1792060000000 } from "../migrations/1792060000000-IndexSessionCreatedAt";
+
+function runner(type: "postgres" | "better-sqlite3", queries: string[], invalid = false): QueryRunner {
+  return {
+    connection: { options: { type } },
+    query: (sql: string): Promise<unknown[]> => {
+      queries.push(sql);
+      return Promise.resolve(invalid && sql.includes("indisvalid") ? [{ invalid: 1 }] : []);
+    },
+  } as unknown as QueryRunner;
+}
+
+// Finalized at once: an open statement keeps SQLite from dropping an index.
+function rows<Row>(database: Database, sql: string): Row[] {
+  const statement = database.prepare<Row, []>(sql);
+  try {
+    return statement.all();
+  } finally {
+    statement.finalize();
+  }
+}
+
+const CREATE = 'CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_session_createdAt_id" ON "session" ("createdAt", "id")';
+
+describe("admin session list index migration", () => {
+  it("builds the PostgreSQL index concurrently outside a transaction", async () => {
+    const migration = new IndexSessionCreatedAt1792060000000();
+    expect(migration.transaction).toBe(false);
+    const up: string[] = [];
+    await migration.up(runner("postgres", up));
+    expect(up).toEqual([
+      "SELECT 1 AS \"invalid\" FROM pg_index WHERE indexrelid = to_regclass($1) AND NOT indisvalid",
+      CREATE,
+    ]);
+
+    const down: string[] = [];
+    await migration.down(runner("postgres", down));
+    expect(down).toEqual(['DROP INDEX IF EXISTS "IDX_session_createdAt_id"']);
+  });
+
+  it("rebuilds an invalid index left by an interrupted build", async () => {
+    const up: string[] = [];
+    await new IndexSessionCreatedAt1792060000000().up(runner("postgres", up, true));
+    expect(up.slice(1)).toEqual(['DROP INDEX CONCURRENTLY IF EXISTS "IDX_session_createdAt_id"', CREATE]);
+  });
+
+  it("serves the newest-first session page on SQLite and reverts", async () => {
+    const database = new Database(":memory:");
+    try {
+      database.run(`CREATE TABLE "session" (
+        "id" text PRIMARY KEY, "userId" text NOT NULL, "token" text NOT NULL,
+        "expiresAt" date NOT NULL, "createdAt" date NOT NULL, "updatedAt" date NOT NULL
+      )`);
+      const migrations = [{ timestamp: 1792060000000, migration: new IndexSessionCreatedAt1792060000000() }];
+      await runSqliteMigrations(database, migrations);
+      const plan = rows<{ detail: string }>(
+        database,
+        `EXPLAIN QUERY PLAN SELECT "id" FROM "session" WHERE "expiresAt" > '2026' ORDER BY "createdAt" DESC, "id" DESC LIMIT 16`,
+      ).map((row) => row.detail).join("\n");
+      expect(plan).toContain("IDX_session_createdAt_id");
+      expect(plan).not.toContain("TEMP B-TREE");
+
+      expect(await revertLatestSqliteMigration(database, migrations)).toBe(true);
+      expect(rows(database, `SELECT "name" FROM "sqlite_master" WHERE "type" = 'index' AND "name" LIKE 'IDX_%'`))
+        .toEqual([]);
+    } finally {
+      database.close();
+    }
+  });
+});

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

@@ -0,0 +1,76 @@
+import { afterEach, beforeEach, describe, expect, test } 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 { adminUserRoutes } from "./admin-users.routes";
+import { AdminUsersService } from "./admin-users.service";
+
+// Callers identify themselves with a test header; only "admin" passes.
+const auth: Pick<AuthService, "requireAdmin"> = {
+  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: {} };
+  },
+};
+
+describe("admin user routes", () => {
+  let db: SQL;
+  let handle: (path: string, role?: string) => Promise<Response>;
+
+  beforeEach(async () => {
+    db = new SQL(":memory:");
+    await db`
+      CREATE TABLE "user" (
+        "id" TEXT PRIMARY KEY, "name" TEXT NOT NULL, "email" TEXT NOT NULL,
+        "emailVerified" INTEGER NOT NULL, "createdAt" DATE NOT NULL, "role" TEXT,
+        "banned" INTEGER, "banReason" TEXT, "banExpires" DATE, "signupApproved" INTEGER
+      )
+    `;
+    await db`
+      INSERT INTO "user" VALUES
+        ('u1', 'Ada', 'ada@example.com', 1, '2026-01-01T00:00:01.000Z', 'admin', 0, NULL, NULL, 1),
+        ('u2', 'Bob', 'bob@example.com', 1, '2026-01-01T00:00:02.000Z', 'admin', 1, 'spam', NULL, 1)
+    `;
+    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(adminUserRoutes({ auth, users: new AdminUsersService(db, "sqlite") }));
+    handle = (path, role) =>
+      app.handle(new Request(`http://localhost${path}`, { headers: role ? { "x-test-role": role } : {} }));
+  });
+
+  afterEach(async () => {
+    await db.close();
+  });
+
+  test("requires an administrator", async () => {
+    expect((await handle("/admin/users")).status).toBe(401);
+    expect((await handle("/admin/users", "user")).status).toBe(403);
+  });
+
+  test("applies role and status together", async () => {
+    const response = await handle("/admin/users?role=admin&status=active&limit=10&offset=0", "admin");
+    expect(response.status).toBe(200);
+    const page = await response.json() as { items: Array<{ id: string; banned: boolean }>; total: number };
+    expect(page.items).toEqual([expect.objectContaining({ id: "u1", banned: false })]);
+    expect(page.total).toBe(1);
+  });
+
+  test("rejects unknown sort fields, statuses, and out-of-range limits", async () => {
+    for (const query of ["sortBy=password", "status=deleted", "sortDirection=up", "limit=0", "limit=101", "offset=-1", "searchField=role"]) {
+      expect((await handle(`/admin/users?${query}`, "admin")).status, query).toBe(400);
+    }
+  });
+});

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

@@ -0,0 +1,41 @@
+import { Elysia, t } from "elysia";
+import type { AuthService } from "../auth/auth.service";
+import type { ElysiaPlugin } from "../core/services";
+import {
+  ADMIN_USER_SORT_FIELDS,
+  ADMIN_USER_STATUSES,
+  ADMIN_USERS_MAX_LIMIT,
+  type AdminUsersService,
+} from "./admin-users.service";
+
+export interface AdminUserRoutesOptions {
+  auth: Pick<AuthService, "requireAdmin">;
+  users: AdminUsersService;
+}
+
+export function adminUserRoutes({ auth, users }: AdminUserRoutesOptions): ElysiaPlugin {
+  return new Elysia({ name: "podokit.admin.users" })
+    .get("/admin/users", async ({ request, query }) => {
+      await auth.requireAdmin(request);
+      return users.list(query);
+    }, {
+      query: t.Object({
+        limit: t.Optional(t.Numeric({ minimum: 1, maximum: ADMIN_USERS_MAX_LIMIT })),
+        offset: t.Optional(t.Numeric({ minimum: 0 })),
+        search: t.Optional(t.String({ maxLength: 200 })),
+        searchField: t.Optional(t.Union([t.Literal("email"), t.Literal("name")])),
+        role: t.Optional(t.String({ minLength: 1, maxLength: 64 })),
+        status: t.Optional(t.Union(ADMIN_USER_STATUSES.map((status) => t.Literal(status)))),
+        sortBy: t.Optional(t.Union(ADMIN_USER_SORT_FIELDS.map((field) => t.Literal(field)))),
+        sortDirection: t.Optional(t.Union([t.Literal("asc"), t.Literal("desc")])),
+      }),
+      detail: {
+        tags: ["admin"],
+        summary: "List users",
+        description:
+          "Administrators only. Offset-paged with `limit` and `offset`; newest first unless " +
+          "`sortBy`/`sortDirection` say otherwise. `search` matches `searchField` (email by " +
+          "default) case-insensitively. `role` and `status` (active, pending, banned) combine.",
+      },
+    });
+}

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

@@ -0,0 +1,124 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { SQL } from "bun";
+import { AdminUsersService, type AdminUserQuery } from "./admin-users.service";
+
+interface SeedUser {
+  id: string;
+  name: string;
+  email: string;
+  role?: string | null;
+  banned?: boolean | null;
+  signupApproved?: boolean | null;
+  emailVerified?: boolean;
+  createdAt: string;
+}
+
+// Better Auth stores booleans as 0 or 1 and dates as ISO text on SQLite.
+async function createSchema(db: SQL): Promise<void> {
+  await db`
+    CREATE TABLE "user" (
+      "id" TEXT PRIMARY KEY, "name" TEXT NOT NULL, "email" TEXT NOT NULL,
+      "emailVerified" INTEGER NOT NULL, "image" TEXT, "createdAt" DATE NOT NULL,
+      "updatedAt" DATE NOT NULL, "role" TEXT, "banned" INTEGER, "banReason" TEXT,
+      "banExpires" DATE, "signupApproved" INTEGER
+    )
+  `;
+}
+
+function flag(value: boolean | null | undefined): number | null {
+  return value === undefined || value === null ? null : value ? 1 : 0;
+}
+
+async function seed(db: SQL, users: SeedUser[]): Promise<void> {
+  for (const user of users) {
+    await db`
+      INSERT INTO "user" ("id", "name", "email", "emailVerified", "createdAt", "updatedAt",
+                          "role", "banned", "banReason", "signupApproved")
+      VALUES (${user.id}, ${user.name}, ${user.email}, ${user.emailVerified ? 1 : 0},
+              ${user.createdAt}, ${user.createdAt}, ${user.role ?? null}, ${flag(user.banned)},
+              ${user.banned ? "spam" : null}, ${flag(user.signupApproved)})
+    `;
+  }
+}
+
+const at = (minute: number): string => `2026-01-01T00:${String(minute).padStart(2, "0")}:00.000Z`;
+
+const USERS: SeedUser[] = [
+  { id: "u1", name: "Ada Admin", email: "ada@example.com", role: "admin", signupApproved: true, createdAt: at(1) },
+  { id: "u2", name: "Bob", email: "bob@example.com", role: "user", signupApproved: true, createdAt: at(2) },
+  { id: "u3", name: "Cy Banned", email: "cy@example.com", role: "user", banned: true, signupApproved: true, createdAt: at(3) },
+  { id: "u4", name: "Di Pending", email: "di@example.com", role: "user", signupApproved: false, createdAt: at(4) },
+  { id: "u5", name: "Eve Banned Admin", email: "eve@example.com", role: "admin,user", banned: true, createdAt: at(5) },
+  { id: "u6", name: "Fay Legacy", email: "fay@example.com", role: null, banned: null, signupApproved: null, createdAt: at(6) },
+];
+
+describe("AdminUsersService", () => {
+  let db: SQL;
+  let service: AdminUsersService;
+
+  beforeEach(async () => {
+    db = new SQL(":memory:");
+    await createSchema(db);
+    await seed(db, USERS);
+    service = new AdminUsersService(db, "sqlite");
+  });
+
+  afterEach(async () => {
+    await db.close();
+  });
+
+  const ids = async (query: AdminUserQuery): Promise<string[]> =>
+    (await service.list(query)).items.map((user) => user.id);
+
+  test("pages newest first by default with a total", async () => {
+    const page = await service.list({ limit: 2, offset: 2 });
+    expect(page.items.map((user) => user.id)).toEqual(["u4", "u3"]);
+    expect(page.total).toBe(6);
+  });
+
+  test("combines the role and status filters", async () => {
+    expect(await ids({ role: "admin", status: "banned" })).toEqual(["u5"]);
+    expect(await ids({ role: "admin", status: "active" })).toEqual(["u1"]);
+    expect(await ids({ role: "user", status: "pending" })).toEqual(["u4"]);
+    expect((await service.list({ role: "user", status: "active" })).total).toBe(1);
+  });
+
+  test("treats unset approval and ban flags as an active user", async () => {
+    expect(await ids({ status: "active" })).toEqual(["u6", "u2", "u1"]);
+    expect(await ids({ status: "banned" })).toEqual(["u5", "u3"]);
+    expect(await ids({ status: "pending" })).toEqual(["u4"]);
+  });
+
+  test("matches one role in a comma-separated role list", async () => {
+    expect(await ids({ role: "user" })).toEqual(["u5", "u4", "u3", "u2"]);
+    expect(await ids({ role: "use" })).toEqual([]);
+  });
+
+  test("searches email or name case-insensitively with literal wildcards", async () => {
+    expect(await ids({ search: "ADA@EXAMPLE", searchField: "email" })).toEqual(["u1"]);
+    expect(await ids({ search: "banned", searchField: "name" })).toEqual(["u5", "u3"]);
+    expect(await ids({ search: "%", searchField: "name" })).toEqual([]);
+    expect(await ids({ search: "banned", searchField: "name", status: "banned", role: "admin" })).toEqual(["u5"]);
+  });
+
+  test("sorts by an allowed column with the id as a tiebreaker", async () => {
+    expect(await ids({ sortBy: "name", sortDirection: "asc", limit: 3 })).toEqual(["u1", "u2", "u3"]);
+    expect(await ids({ sortBy: "email", sortDirection: "desc", limit: 2 })).toEqual(["u6", "u5"]);
+  });
+
+  test("returns booleans and ISO dates without exposing other columns", async () => {
+    const [pending] = (await service.list({ status: "pending" })).items;
+    expect(pending).toEqual({
+      id: "u4",
+      name: "Di Pending",
+      email: "di@example.com",
+      role: "user",
+      emailVerified: false,
+      signupApproved: false,
+      banned: false,
+      banReason: null,
+      banExpires: null,
+      createdAt: at(4),
+    });
+  });
+});

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

@@ -0,0 +1,153 @@
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import type { SQL } from "bun";
+
+export const ADMIN_USERS_DEFAULT_LIMIT = 15;
+export const ADMIN_USERS_MAX_LIMIT = 100;
+export const ADMIN_USER_SORT_FIELDS = ["createdAt", "name", "email", "role"] as const;
+export const ADMIN_USER_STATUSES = ["active", "pending", "banned"] as const;
+
+export type AdminUserSortField = (typeof ADMIN_USER_SORT_FIELDS)[number];
+export type AdminUserStatus = (typeof ADMIN_USER_STATUSES)[number];
+
+/** A user as the admin list shows it. Credentials and sessions stay on the server. */
+export interface AdminUserView {
+  id: string;
+  name: string;
+  email: string;
+  role: string | null;
+  emailVerified: boolean;
+  signupApproved: boolean;
+  banned: boolean;
+  banReason: string | null;
+  banExpires: string | null;
+  createdAt: string;
+}
+
+export interface AdminUserPage {
+  items: AdminUserView[];
+  total: number;
+}
+
+export interface AdminUserQuery {
+  limit?: number;
+  offset?: number;
+  search?: string;
+  searchField?: "email" | "name";
+  role?: string;
+  status?: AdminUserStatus;
+  sortBy?: AdminUserSortField;
+  sortDirection?: "asc" | "desc";
+}
+
+type Flag = boolean | number | null;
+
+interface UserRow {
+  id: string;
+  name: string;
+  email: string;
+  role: string | null;
+  emailVerified: Flag;
+  signupApproved: Flag;
+  banned: Flag;
+  banReason: string | null;
+  banExpires: Date | string | null;
+  createdAt: Date | string;
+}
+
+// SQLite stores booleans as 0 or 1. An unset approval predates sign-up approval.
+function flag(value: Flag, unset: boolean): boolean {
+  return value === null ? unset : value === true || value === 1;
+}
+
+function iso(value: Date | string): string {
+  return (value instanceof Date ? value : new Date(value)).toISOString();
+}
+
+function likePattern(search: string): string {
+  return `%${search.replace(/[\\%_]/g, (character) => `\\${character}`)}%`;
+}
+
+/**
+ * Lists users for the admin console with every filter applied in one query.
+ * Better Auth `listUsers` accepts a single filter, so role and status could not
+ * combine there. Mutations stay on Better Auth so its permission checks and the
+ * audit hooks still run.
+ */
+export class AdminUsersService {
+  constructor(
+    private readonly sql: SQL,
+    private readonly provider: DatabaseProviderName,
+  ) {}
+
+  async list(query: AdminUserQuery = {}): Promise<AdminUserPage> {
+    const limit = Math.min(Math.max(query.limit ?? ADMIN_USERS_DEFAULT_LIMIT, 1), ADMIN_USERS_MAX_LIMIT);
+    const offset = Math.max(query.offset ?? 0, 0);
+    const search = query.search?.trim() ?? "";
+    const filters = (): SQL.Query<unknown> => this.sql`
+      WHERE 1 = 1
+      ${search ? this.searchFilter(query.searchField ?? "email", likePattern(search)) : this.sql``}
+      ${query.role ? this.sql`AND (',' || u."role" || ',') LIKE ${`%,${query.role},%`}` : this.sql``}
+      ${query.status ? this.statusFilter(query.status) : this.sql``}
+    `;
+    const [rows, totals] = await Promise.all([
+      this.sql<UserRow[]>`
+        SELECT u."id", u."name", u."email", u."role", u."emailVerified", u."signupApproved",
+               u."banned", u."banReason", u."banExpires", u."createdAt"
+        FROM "user" u
+        ${filters()}
+        ${this.order(query.sortBy ?? "createdAt", query.sortDirection ?? "desc")}
+        LIMIT ${limit} OFFSET ${offset}
+      `,
+      this.sql<Array<{ total: number | string | bigint }>>`
+        SELECT COUNT(*) AS "total" FROM "user" u ${filters()}
+      `,
+    ]);
+    return {
+      items: rows.map((row) => ({
+        id: row.id,
+        name: row.name,
+        email: row.email,
+        role: row.role,
+        emailVerified: flag(row.emailVerified, false),
+        signupApproved: flag(row.signupApproved, true),
+        banned: flag(row.banned, false),
+        banReason: row.banReason,
+        banExpires: row.banExpires === null ? null : iso(row.banExpires),
+        createdAt: iso(row.createdAt),
+      })),
+      total: Number(totals[0]?.total ?? 0),
+    };
+  }
+
+  private searchFilter(field: "email" | "name", pattern: string): SQL.Query<unknown> {
+    const column = field === "name" ? this.sql`u."name"` : this.sql`u."email"`;
+    // SQLite LIKE ignores ASCII case; PostgreSQL needs ILIKE.
+    return this.provider === "sqlite"
+      ? this.sql`AND ${column} LIKE ${pattern} ESCAPE '\\'`
+      : this.sql`AND ${column} ILIKE ${pattern} ESCAPE '\\'`;
+  }
+
+  private statusFilter(status: AdminUserStatus): SQL.Query<unknown> {
+    switch (status) {
+      case "pending":
+        return this.sql`AND u."signupApproved" = FALSE`;
+      case "banned":
+        return this.sql`AND u."banned" = TRUE`;
+      case "active":
+        return this.sql`AND COALESCE(u."banned", FALSE) = FALSE AND COALESCE(u."signupApproved", TRUE) = TRUE`;
+    }
+  }
+
+  private order(field: AdminUserSortField, direction: "asc" | "desc"): SQL.Query<unknown> {
+    const column = {
+      createdAt: this.sql`u."createdAt"`,
+      name: this.sql`u."name"`,
+      email: this.sql`u."email"`,
+      role: this.sql`u."role"`,
+    }[field];
+    // The id breaks ties so offset pages neither skip nor repeat users.
+    return direction === "asc"
+      ? this.sql`ORDER BY ${column} ASC, u."id" ASC`
+      : this.sql`ORDER BY ${column} DESC, u."id" DESC`;
+  }
+}

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

@@ -8,6 +8,8 @@ import { Elysia, t } from "elysia";
 import { adminSessionRoutes } from "./admin-sessions/admin-sessions.routes";
 import { createSessionRevoker, type RevokeUserSessionApi } from "./admin-sessions/admin-sessions.revoker";
 import { AdminSessionsService } from "./admin-sessions/admin-sessions.service";
+import { adminUserRoutes } from "./admin-users/admin-users.routes";
+import { AdminUsersService } from "./admin-users/admin-users.service";
 import { AUTH } from "./auth/auth.module";
 import { getAuth } from "./auth/auth-provider";
 import {
@@ -30,6 +32,7 @@ import { validateSiteSetting } from "./site-settings/site-settings.validation";
 export const SITE_SETTINGS = Symbol("site-settings") as ServiceKey<SiteSettingsService>;
 export const PROFILE_IMAGES = Symbol("profile-images") as ServiceKey<ProfileImageService>;
 export const ADMIN_SESSIONS = Symbol("admin-sessions") as ServiceKey<AdminSessionsService>;
+export const ADMIN_USERS = Symbol("admin-users") as ServiceKey<AdminUsersService>;
 
 const ICON_TYPES = new Set([
   "image/svg+xml",
@@ -54,6 +57,7 @@ const adminPlugin: AppPlugin = ({ services }) => {
       sessions: services.resolve(ADMIN_SESSIONS),
       revoke: createSessionRevoker(() => getAuth().api as unknown as RevokeUserSessionApi),
     }))
+    .use(adminUserRoutes({ auth, users: services.resolve(ADMIN_USERS) }))
     .use(siteAssetRoutes(site, profileImages))
     .get("/site/settings", async () => {
       // The favicon fields are site.* rows too, so one read serves the response.
@@ -127,6 +131,7 @@ export const adminModule: PodokitModule = {
   configure: (_env, services): void => {
     const database = services.resolve(DATABASE);
     services.register(ADMIN_SESSIONS, new AdminSessionsService(database.sql, database.provider));
+    services.register(ADMIN_USERS, new AdminUsersService(database.sql, database.provider));
     const storage = services.resolve(OBJECT_STORAGE);
     const site = new SiteSettingsService(services.resolve(DATABASE).sql, storage);
     const profileImages = new ProfileImageService(storage, services.resolve(LOGGER));