@podosoft/podokit 1.1.6 → 1.3.0

package/dist/templates/modules/admin-dashboard/files/tests/ui/sessions.ui.spec.ts

@@ -1,22 +1,85 @@
-import { expect, test } from "@playwright/test";
+import { expect, test } from "../helpers/disposable-users";
 import { ready } from "../helpers/hydration";
 
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+
+function isSessionList(url: string): boolean {
+  return new URL(url).pathname === "/api/admin/sessions";
+}
+
 // admin storageState (project default) — sessions is an admin-only view
 test("sessions table shows the expires column", async ({ page }) => {
   await ready(page, "/admin/sessions");
   await expect(page.getByRole("columnheader", { name: "Expires" })).toBeVisible();
 });
 
+test("sessions page loads one server page without per-user requests or tokens", async ({ page }) => {
+  const requested: string[] = [];
+  page.on("request", (request) => requested.push(request.url()));
+  const listed = page.waitForResponse((response) => isSessionList(response.url()));
+  await ready(page, "/admin/sessions");
+  const response = await listed;
+
+  expect(response.status()).toBe(200);
+  const body = (await response.json()) as { items: Array<Record<string, unknown>>; total: number };
+  expect(body.items.length).toBeLessThanOrEqual(15);
+  for (const item of body.items) expect(item).not.toHaveProperty("token");
+  await expect(page.getByRole("table", { name: "User sessions" }).getByRole("row").nth(1)).toBeVisible();
+  expect(requested.filter(isSessionList)).toHaveLength(1);
+  expect(requested.filter((url) => url.includes("/api/auth/admin/list-user-sessions"))).toEqual([]);
+  expect(requested.filter((url) => url.includes("/api/auth/admin/list-users"))).toEqual([]);
+});
+
 test("admin sees user sessions across users", async ({ page }) => {
   await ready(page, "/admin/sessions");
   await expect(page.getByRole("heading", { name: "User sessions" })).toBeVisible();
   // Search by exact address — robust to pagination as sessions accumulate (the
   // admin account alone can fill the first page). This is the across-users view.
+  const searched = page.waitForResponse(
+    (response) => isSessionList(response.url()) && new URL(response.url()).searchParams.get("search") === "user@example.com",
+  );
   await page.locator("#toolbar-search").fill("user@example.com");
   await page.getByRole("button", { name: "Search", exact: true }).click();
+  expect((await searched).ok()).toBeTruthy();
   await expect(page.getByRole("main").getByText("user@example.com").first()).toBeVisible();
   // row actions are available
   await page.getByRole("row", { name: /user@example.com/ }).first().getByRole("button").click();
   await expect(page.getByRole("menuitem", { name: "Revoke session" })).toBeVisible();
   await expect(page.getByRole("menuitem", { name: "Revoke all for user" })).toBeVisible();
 });
+
+test("admin revokes a session by id and only the current page reloads", async ({
+  page,
+  playwright,
+  disposableUsers,
+}) => {
+  const email = `ui-sess-revoke-${Date.now()}@example.com`;
+  await disposableUsers.create({ email, name: "Session Revoke" });
+  // Sign the user in on an isolated context so the shared admin cookie is untouched.
+  const theirs = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: { origin: base } });
+  expect((await theirs.post("/api/auth/sign-in/email", { data: { email, password: "Podokit3e-Str0ng!pw" } })).ok())
+    .toBeTruthy();
+
+  await ready(page, "/admin/sessions");
+  await page.locator("#toolbar-search").fill(email);
+  await page.getByRole("button", { name: "Search", exact: true }).click();
+  const row = page.getByRole("row", { name: new RegExp(email) });
+  await expect(row).toHaveCount(1);
+
+  const revoked = page.waitForResponse(
+    (response) => response.request().method() === "DELETE" &&
+      new URL(response.url()).pathname.startsWith("/api/admin/sessions/"),
+  );
+  const reloaded = page.waitForResponse(
+    (response) => isSessionList(response.url()) && new URL(response.url()).searchParams.get("search") === email,
+  );
+  await row.getByRole("button").click();
+  await page.getByRole("menuitem", { name: "Revoke session" }).click();
+  expect((await revoked).status()).toBe(204);
+  const reload = await reloaded;
+  expect(new URL(reload.url()).searchParams.get("cursor")).toBeNull();
+  await expect(page.getByText("Session revoked")).toBeVisible();
+  await expect(row).toHaveCount(0);
+  expect(await (await theirs.get("/api/auth/get-session")).json()).toBeNull();
+  await theirs.dispose();
+});

package/dist/templates/modules/admin-dashboard/files/tests/ui/table-toolbar.ui.spec.ts

@@ -18,7 +18,36 @@ test("users toolbar applies filter + search together on Search", async ({ page }
   await page.locator('button[data-slot="select-trigger"]').first().click(); // Role select
   await page.getByRole("option", { name: "Admin", exact: true }).click();
   // Selecting a filter stages it; nothing applies until Search is pressed.
+  const filtered = page.waitForResponse((response) => {
+    const url = new URL(response.url());
+    return url.pathname === "/api/admin/users" && url.searchParams.get("role") === "admin";
+  });
   await page.getByRole("button", { name: "Search", exact: true }).click();
+  expect((await filtered).ok()).toBeTruthy();
+  await expect(main.getByRole("cell", { name: "admin@example.com" })).toBeVisible();
+  await expect(main.getByRole("cell", { name: "user@example.com" })).toHaveCount(0);
+});
+
+test("users toolbar combines the role and status filters", async ({ page }) => {
+  await ready(page, "/admin/users");
+  const main = page.getByRole("main");
+  const roleSelect = page.locator('button[data-slot="select-trigger"]').first();
+  const statusSelect = page.locator('button[data-slot="select-trigger"]').nth(1);
+  await roleSelect.click();
+  await page.getByRole("option", { name: "Admin", exact: true }).click();
+  await statusSelect.click();
+  await page.getByRole("option", { name: "Active", exact: true }).click();
+  await expect(roleSelect).toContainText("Admin");
+  await expect(statusSelect).toContainText("Active");
+
+  const filtered = page.waitForResponse((response) => {
+    const url = new URL(response.url());
+    return url.pathname === "/api/admin/users" &&
+      url.searchParams.get("role") === "admin" &&
+      url.searchParams.get("status") === "active";
+  });
+  await page.getByRole("button", { name: "Search", exact: true }).click();
+  expect((await filtered).ok()).toBeTruthy();
   await expect(main.getByRole("cell", { name: "admin@example.com" })).toBeVisible();
   await expect(main.getByRole("cell", { name: "user@example.com" })).toHaveCount(0);
 });

package/dist/templates/modules/admin-dashboard/files/tests/ui/users-crud.ui.spec.ts

@@ -135,9 +135,16 @@ test("users list shows pagination beyond one page", async ({ page, disposableUse
   }
   await page.locator("#toolbar-search").fill(prefix);
   await page.getByRole("button", { name: "Search", exact: true }).click();
+  await expect(page.getByText("16 users")).toBeVisible();
   const nav = page.getByRole("navigation", { name: "pagination" }).first();
   await expect(nav).toBeVisible();
-  await expect(nav.getByRole("button", { name: "Page 2", exact: true }).first()).toBeVisible();
+  const secondPage = page.waitForResponse((response) => {
+    const url = new URL(response.url());
+    return url.pathname === "/api/admin/users" && url.searchParams.get("offset") === "15";
+  });
+  await nav.getByRole("button", { name: "Page 2", exact: true }).first().click();
+  expect((await secondPage).ok()).toBeTruthy();
+  await expect(page.getByRole("table", { name: "Users" }).locator("tbody tr")).toHaveCount(1);
 });
 
 test("manage modal closes from its footer", async ({ page, disposableUsers }) => {

package/dist/templates/modules/admin-dashboard/files/tests/ui/users.ui.spec.ts

@@ -43,15 +43,46 @@ test("admin sees the user list and can search", async ({ page }) => {
   await expect(page.getByRole("cell", { name: "admin@example.com" })).toHaveCount(0);
 });
 
+test("the user list asks the server for one page at a time", async ({ page }) => {
+  const isListUsers = (url: string): boolean => new URL(url).pathname === "/api/admin/users";
+  const requested: string[] = [];
+  page.on("request", (request) => requested.push(request.url()));
+  const first = page.waitForResponse((response) => isListUsers(response.url()));
+  await ready(page, "/admin/users");
+  const initial = new URL((await first).url()).searchParams;
+  expect(initial.get("limit")).toBe("15");
+  expect(initial.get("sortBy")).toBe("createdAt");
+  expect(initial.get("sortDirection")).toBe("desc");
+  await expect(page.getByRole("columnheader", { name: "Joined" })).toHaveAttribute("aria-sort", "descending");
+
+  // The server matches case-insensitively, so the search goes as typed.
+  const searched = page.waitForResponse((response) => isListUsers(response.url()));
+  await page.locator("#toolbar-search").fill("Admin@Example.com");
+  await page.getByRole("button", { name: "Search", exact: true }).click();
+  const query = new URL((await searched).url()).searchParams;
+  expect(query.get("search")).toBe("Admin@Example.com");
+  expect(query.get("searchField")).toBe("email");
+  expect(query.get("offset")).toBe("0");
+  await expect(page.getByRole("cell", { name: "admin@example.com" })).toBeVisible();
+  expect(requested.filter((url) => url.includes("/api/auth/admin/list-users"))).toEqual([]);
+});
+
 test("user list shows the joined column", async ({ page }) => {
   await ready(page, "/admin/users");
   await expect(page.getByRole("columnheader", { name: "Joined" })).toBeVisible();
 });
 
 test("row menu exposes admin actions", async ({ page }) => {
-  await page.goto("/admin/users");
+  // The list shows one server page, so the search must run before the row exists.
+  await ready(page, "/admin/users");
+  const searched = page.waitForResponse((response) => {
+    const url = new URL(response.url());
+    return url.pathname === "/api/admin/users" &&
+      url.searchParams.get("search") === "user@example.com";
+  });
   await page.locator("#toolbar-search").fill("user@example.com");
   await page.getByRole("button", { name: "Search", exact: true }).click();
+  expect((await searched).ok()).toBeTruthy();
   const row = page.getByRole("row", { name: /user@example.com/ });
   await row.getByRole("button").click();
   await expect(page.getByRole("menuitem", { name: "Manage" })).toBeVisible();

package/dist/templates/modules/admin-dashboard/module.manifest.json

@@ -13,7 +13,8 @@
   },
   "ownedGlobs": [
     "apps/web/src/lib/i18n/locales/**",
-    "apps/web/src/lib/i18n/catalogs/app/**"
+    "apps/web/src/lib/i18n/catalogs/app/**",
+    "apps/web/src/lib/server/public-paths.ts"
   ],
   "managedOverrides": [
     "apps/web/src/lib/components/ui/input/input.svelte",
@@ -117,7 +118,7 @@
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",
       "optional": true,
-      "text": "### admin-dashboard\n- The `(admin)` route group and `admin-sidebar.svelte` are the admin-console shell for `/admin/*` only. Put signed-in product pages in `(app)` or in a separate route group with its own layout; do not place them under `(admin)`.\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Set `ADMIN_EMAILS`, then create or verify the initial account with `{{apiRun}} admin:bootstrap{{apiWorkspaceArg}}`; never commit or persist `ADMIN_BOOTSTRAP_PASSWORD`. When sign-up approval is enabled, self-registered users stay pending until an administrator approves them on `/admin/users`; administrator-created users bypass the queue.\n- Signed-in users can upload, replace, or remove their profile image from `/account` or `/admin/account`. Keep the shared policy visible in custom account UI: PNG, JPEG, or WebP; at most 2 MB and 2048 by 2048 pixels. Use the managed `/api/account/profile-image` endpoints instead of writing directly to storage or `user.image`.\n- `sidebar-user-menu.svelte` is specific to the admin sidebar. For a product shell outside `Sidebar.Provider`, use the managed `<AccountMenu {user} variant=\"identity\" side=\"top\" />` component.\n- Custom protected server layouts must call `requireBackendAvailable(locals)` from `#lib/server/guards.js` before redirecting anonymous users. This preserves sessions and returns 503 when authentication or maintenance policy cannot be checked.\n- **Every list/table MUST use the shared `#lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `#lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand. For responsive columns, use `hideBelow` and apply the row context's `cellClass(columnKey)` to the matching cell.\n"
+      "text": "### admin-dashboard\n- The `(admin)` route group and `admin-sidebar.svelte` are the admin-console shell for `/admin/*` only. Put signed-in product pages in `(app)` or in a separate route group with its own layout; do not place them under `(admin)`.\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Set `ADMIN_EMAILS`, then create or verify the initial account with `{{apiRun}} admin:bootstrap{{apiWorkspaceArg}}`; never commit or persist `ADMIN_BOOTSTRAP_PASSWORD`. When sign-up approval is enabled, self-registered users stay pending until an administrator approves them on `/admin/users`; administrator-created users bypass the queue.\n- Signed-in users can upload, replace, or remove their profile image from `/account` or `/admin/account`. Keep the shared policy visible in custom account UI: PNG, JPEG, or WebP; at most 2 MB and 2048 by 2048 pixels. Use the managed `/api/account/profile-image` endpoints instead of writing directly to storage or `user.image`.\n- `sidebar-user-menu.svelte` is specific to the admin sidebar. For a product shell outside `Sidebar.Provider`, use the managed `<AccountMenu {user} variant=\"identity\" side=\"top\" />` component.\n- Custom protected server layouts must call `requireBackendAvailable(locals)` from `#lib/server/guards.js` before redirecting anonymous users. This preserves sessions and returns 503 when authentication or maintenance policy cannot be checked.\n- Every page except the sign-in flow, `/`, and module pages requires a session, and fails closed with 503 when the API or site settings are unavailable. List the application's public pages (marketing, pricing, legal, `robots.txt`) in `APP_PUBLIC_PATHS` in the app-owned `apps/web/src/lib/server/public-paths.ts`; a prefix covers its subpaths. Do not edit the `PUBLIC_PATHS` list in the managed `guards.ts`.\n- **Every list/table MUST use the shared `#lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `#lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand. For responsive columns, use `hideBelow` and apply the row context's `cellClass(columnKey)` to the matching cell.\n"
     },
     {
       "file": "apps/api/src/app.ts",

package/dist/templates/modules/audit-log/files/apps/api/src/audit/README.md

@@ -42,7 +42,41 @@ await recordAudit({
 ```
 
 Resolve `AUDIT` from the application service registry to call
-`audit.record({ ... })`. Audit writes never break the request.
+`audit.record({ ... })`. Audit writes never break the request, and every write
+path checks the admin on/off toggle.
+
+## Deferred recording
+
+`recordAudit()` and `recordRequest()` await the INSERT, so the response waits for
+the write. For high-volume events that are not security relevant (comments,
+content edits, views), queue the entry instead:
+
+```ts
+import { recordAuditLater } from "../audit/audit-events";
+
+recordAuditLater({ action: "comment.create", actorId, targetType: "comment", targetId: comment.id });
+
+// or, in a route
+await audit.recordRequest("comment.create", request, session, { type: "comment", id: comment.id }, { defer: true });
+```
+
+Queued entries are written with one multi-row INSERT every 250 ms, as soon as
+100 are waiting, and when the API shuts down cleanly. **Entries still queued
+when the process crashes or is killed are lost.** The queue holds at most 1,000
+entries; past that, new deferred entries are dropped with a warning, and an
+`audit.dropped` entry (`metadata.count`) records the gap once a write succeeds.
+
+Keep `auth.*`, `user.*`, and other security events on the awaited path. The
+Better Auth hook always awaits.
+
+## Retention
+
+Entries are kept forever unless `AUDIT_LOG_RETENTION_DAYS` is set to a whole
+number of days. Then, on startup and about every hour, the API deletes older
+entries in batches of 1,000 rows and records an `audit.pruned` entry with the
+count and cutoff. Leave it unset or `0` unless a written retention policy
+requires deletion: many compliance regimes require a minimum retention period,
+and pruned entries cannot be recovered.
 
 ## Fields (`AuditEntry`)
 
@@ -53,8 +87,15 @@ survives renames/deletes), `targetType/targetId/targetLabel`, `ip`, `metadata`
 ## Customize
 
 - **Auth actions:** edit the `ACTIONS` map in `audit-hook.ts`.
-- **Your routes:** call `AuditService.recordRequest()` after successful operations.
+- **Your routes:** call `AuditService.recordRequest()` after successful operations;
+  pass `{ defer: true }` only for high-volume, non-security events.
 - **Schema:** add columns with a migration, and keep the
-  `AuditEntry` type in `audit-events.ts` in sync.
-- **Reading:** `GET /audit-logs` returns the latest 50 (admin only); extend the
-  Elysia plugin in `audit.module.ts` for filtering or pagination.
+  `AuditEntry` type in `audit-events.ts` in sync. A new list filter needs an
+  index that starts with its column and ends with `"createdAt"`, like those in
+  `1792000000000-IndexAuditLogFilters.ts`.
+- **Reading:** `GET /audit-logs` (admin only) returns a page as an array, newest
+  first, filtered by exact `action`, `actor` (email), and `target` (label). Pass
+  the `X-Next-Cursor` response header back as `cursor` for the next page; `limit`
+  is 1 to 100 (default 50) and `order=asc` reverses the order.
+  `GET /audit-logs/actions` lists the recorded action codes. Routes live in
+  `audit.routes.ts`.

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit-events.ts

@@ -15,22 +15,34 @@ export type AuditEntry = {
   metadata?: Record<string, unknown> | null;
 };
 
-type Recorder = (entry: AuditEntry) => Promise<void>;
-let recorder: Recorder | null = null;
+export interface AuditRecorder {
+  record(entry: AuditEntry): Promise<void>;
+  recordLater(entry: AuditEntry): void;
+}
+
+let recorder: AuditRecorder | null = null;
 
 // AuditService registers the recorder during Elysia configuration. The registry
 // stays available to Better Auth hooks and background jobs.
-export function setAuditRecorder(fn: Recorder): () => void {
-  recorder = fn;
+export function setAuditRecorder(next: AuditRecorder): () => void {
+  recorder = next;
   return () => {
-    if (recorder === fn) recorder = null;
+    if (recorder === next) recorder = null;
   };
 }
 
 // Record a custom audit event from anywhere. Awaits the write; a no-op until the
-// AuditService has started. Example:
+// AuditService has started or while the admin toggle is off. Example:
 //   await recordAudit({ action: "invoice.paid", actorId, targetLabel: invoice.number,
 //                       metadata: { amount } });
 export async function recordAudit(entry: AuditEntry): Promise<void> {
-  if (recorder) await recorder(entry);
+  if (recorder) await recorder.record(entry);
+}
+
+// Queue a high-volume, non-security event and return at once. Queued entries are
+// written in batches within about 250 ms and on shutdown; a crash loses whatever
+// is still queued. Keep auth.*, user.*, and other security events on recordAudit().
+//   recordAuditLater({ action: "comment.create", actorId, targetId: comment.id });
+export function recordAuditLater(entry: AuditEntry): void {
+  recorder?.recordLater(entry);
 }

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit-hook.ts

@@ -39,6 +39,8 @@ const ACTIONS: Record<string, string> = {
 export const auditAfterHook = createAuthMiddleware(async (ctx) => {
   const action = ACTIONS[ctx.path];
   if (!action) return;
+  // AuditService checks the toggle again on write; checking here as well skips
+  // the target lookup below when auditing is off.
   if (!(await auditEnabled())) return;
   const context = ctx.context as {
     session?: { user?: { id?: string; name?: string; email?: string } };

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit.migration.spec.ts

@@ -1,17 +1,53 @@
 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 { InitAuditLogs1720300000000 } from "../migrations/1720300000000-InitAuditLogs";
+import { IndexAuditLogFilters1792000000000 } from "../migrations/1792000000000-IndexAuditLogFilters";
 
-function runner(type: "postgres" | "better-sqlite3", queries: string[]): QueryRunner {
+function runner(
+  type: "postgres" | "better-sqlite3",
+  queries: string[],
+  invalidIndexes: string[] = [],
+): QueryRunner {
   return {
     connection: { options: { type } },
-    query: (sql: string): Promise<unknown[]> => {
+    query: (sql: string, parameters: unknown[] = []): Promise<unknown[]> => {
       queries.push(sql);
-      return Promise.resolve([]);
+      const invalid = sql.includes("indisvalid") && invalidIndexes.some((name) => parameters[0] === `"${name}"`);
+      return Promise.resolve(invalid ? [{ invalid: 1 }] : []);
     },
   } as unknown as QueryRunner;
 }
 
+const INVALID_CHECK =
+  "SELECT 1 AS \"invalid\" FROM pg_index WHERE indexrelid = to_regclass($1) AND NOT indisvalid";
+
+const FILTER_INDEXES = [
+  "IDX_audit_logs_action_createdAt",
+  "IDX_audit_logs_actorEmail_createdAt",
+  "IDX_audit_logs_createdAt_id",
+  "IDX_audit_logs_targetLabel_createdAt",
+];
+const INITIAL_INDEXES = ["IDX_audit_logs_action", "IDX_audit_logs_createdAt"];
+
+// 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();
+  }
+}
+
+function indexNames(database: Database): string[] {
+  return rows<{ name: string }>(
+    database,
+    `SELECT "name" FROM "sqlite_master" WHERE "type" = 'index' AND "tbl_name" = 'audit_logs' AND "name" LIKE 'IDX_%'`,
+  ).map((row) => row.name).sort();
+}
+
 describe("audit log migration", () => {
   it("retains PostgreSQL UUID and JSONB storage", async () => {
     const queries: string[] = [];
@@ -31,3 +67,90 @@ describe("audit log migration", () => {
     expect(queries.join("\n")).not.toContain("CREATE EXTENSION");
   });
 });
+
+describe("audit filter index migration", () => {
+  it("builds and drops the PostgreSQL indexes concurrently outside a transaction", async () => {
+    const migration = new IndexAuditLogFilters1792000000000();
+    // A transaction block would reject CONCURRENTLY; the runner must use "each".
+    expect(migration.transaction).toBe(false);
+    const up: string[] = [];
+    await migration.up(runner("postgres", up));
+    expect(up).toEqual([
+      INVALID_CHECK,
+      'CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_audit_logs_createdAt_id" ON "audit_logs" ("createdAt", "id")',
+      INVALID_CHECK,
+      'CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_audit_logs_action_createdAt" ON "audit_logs" ("action", "createdAt")',
+      INVALID_CHECK,
+      'CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_audit_logs_actorEmail_createdAt" ON "audit_logs" ("actorEmail", "createdAt")',
+      INVALID_CHECK,
+      'CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_audit_logs_targetLabel_createdAt" ON "audit_logs" ("targetLabel", "createdAt")',
+      'DROP INDEX CONCURRENTLY IF EXISTS "IDX_audit_logs_action"',
+      'DROP INDEX CONCURRENTLY IF EXISTS "IDX_audit_logs_createdAt"',
+    ]);
+  });
+
+  it("rebuilds an invalid index left by an interrupted concurrent build", async () => {
+    const up: string[] = [];
+    await new IndexAuditLogFilters1792000000000().up(
+      runner("postgres", up, ["IDX_audit_logs_action_createdAt"]),
+    );
+    const drop = up.indexOf('DROP INDEX CONCURRENTLY IF EXISTS "IDX_audit_logs_action_createdAt"');
+    expect(drop).toBeGreaterThan(-1);
+    expect(up[drop + 1]).toBe(
+      'CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_audit_logs_action_createdAt" ON "audit_logs" ("action", "createdAt")',
+    );
+    expect(up.filter((sql) => sql.startsWith("DROP INDEX CONCURRENTLY"))).toHaveLength(3);
+  });
+
+  it("restores the single-column PostgreSQL indexes on revert inside its transaction", async () => {
+    const migration = new IndexAuditLogFilters1792000000000();
+    const down: string[] = [];
+    await migration.down(runner("postgres", down));
+    expect(down).toEqual([
+      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_action" ON "audit_logs" ("action")',
+      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_createdAt" ON "audit_logs" ("createdAt")',
+      'DROP INDEX IF EXISTS "IDX_audit_logs_createdAt_id"',
+      'DROP INDEX IF EXISTS "IDX_audit_logs_action_createdAt"',
+      'DROP INDEX IF EXISTS "IDX_audit_logs_actorEmail_createdAt"',
+      'DROP INDEX IF EXISTS "IDX_audit_logs_targetLabel_createdAt"',
+    ]);
+  });
+
+  it("keeps plain index statements on SQLite", async () => {
+    const up: string[] = [];
+    await new IndexAuditLogFilters1792000000000().up(runner("better-sqlite3", up));
+    expect(up).toEqual([
+      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_createdAt_id" ON "audit_logs" ("createdAt", "id")',
+      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_action_createdAt" ON "audit_logs" ("action", "createdAt")',
+      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_actorEmail_createdAt" ON "audit_logs" ("actorEmail", "createdAt")',
+      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_targetLabel_createdAt" ON "audit_logs" ("targetLabel", "createdAt")',
+      'DROP INDEX IF EXISTS "IDX_audit_logs_action"',
+      'DROP INDEX IF EXISTS "IDX_audit_logs_createdAt"',
+    ]);
+  });
+
+  it("migrates up and down on SQLite", async () => {
+    const database = new Database(":memory:");
+    const migrations = [
+      { timestamp: 1720300000000, migration: new InitAuditLogs1720300000000() },
+      { timestamp: 1792000000000, migration: new IndexAuditLogFilters1792000000000() },
+    ];
+    try {
+      await runSqliteMigrations(database, migrations);
+      expect(indexNames(database)).toEqual(FILTER_INDEXES);
+      const plan = rows<{ detail: string }>(
+        database,
+        `EXPLAIN QUERY PLAN SELECT "id" FROM "audit_logs" WHERE "actorEmail" = 'a' ORDER BY "createdAt" DESC LIMIT 5`,
+      ).map((row) => row.detail).join("\n");
+      expect(plan).toContain("IDX_audit_logs_actorEmail_createdAt");
+
+      expect(await revertLatestSqliteMigration(database, migrations)).toBe(true);
+      expect(indexNames(database)).toEqual(INITIAL_INDEXES);
+
+      await runSqliteMigrations(database, migrations);
+      expect(indexNames(database)).toEqual(FILTER_INDEXES);
+    } finally {
+      database.close();
+    }
+  });
+});

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit.module.ts

@@ -1,31 +1,33 @@
-import { Elysia } from "elysia";
 import { AUTH } from "../auth/auth.module";
 import {
   DATABASE,
+  LOGGER,
   type AppPlugin,
   type PodokitModule,
   type ServiceKey,
 } from "../core/services";
-import { AuditService } from "./audit.service";
+import { auditEnabled } from "./audit-enabled";
+import { auditRoutes } from "./audit.routes";
+import { AuditService, parseRetentionDays } from "./audit.service";
 
 export const AUDIT = Symbol("audit") as ServiceKey<AuditService>;
 
 const auditPlugin: AppPlugin = ({ services }) => {
   const auth = services.resolve(AUTH);
-  const audit = services.resolve(AUDIT);
-  return new Elysia({ name: "podokit.audit" })
-    .get("/audit-logs", async ({ request }) => {
-      await auth.requireAdmin(request);
-      return audit.recent();
-    }, {
-      detail: { tags: ["audit"], summary: "List recent audit entries" },
-    });
+  return auditRoutes(services.resolve(AUDIT), (request) => auth.requireAdmin(request));
 };
 
 export const auditModule: PodokitModule = {
   name: "audit-log",
   configure: (_env, services): void => {
-    const audit = new AuditService(services.resolve(DATABASE).sql);
+    const database = services.resolve(DATABASE);
+    const audit = new AuditService(database.sql, {
+      dialect: database.provider,
+      enabled: auditEnabled,
+      // Resolved on use: the logging module may replace the logger after this point.
+      logger: { warn: (details, message) => services.resolve(LOGGER).warn(details, message) },
+      retention: { days: parseRetentionDays(process.env.AUDIT_LOG_RETENTION_DAYS) },
+    });
     services.register(AUDIT, audit, () => audit.close());
     services.onStart(() => audit.connect());
   },

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit.routes.spec.ts

@@ -0,0 +1,115 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { SQL } from "bun";
+import { AppException } from "@podosoft/podokit-contracts";
+import { Elysia } from "elysia";
+import type { QueryRunner } from "typeorm";
+import { InitAuditLogs1720300000000 } from "../migrations/1720300000000-InitAuditLogs";
+import { AUDIT_NEXT_CURSOR_HEADER, auditRoutes } from "./audit.routes";
+import { AuditService } from "./audit.service";
+
+let open: SQL | undefined;
+
+afterEach(async () => {
+  await open?.close();
+  open = undefined;
+});
+
+async function service(entries: number): Promise<AuditService> {
+  const sql = new SQL(":memory:");
+  open = sql;
+  const runner = {
+    connection: { options: { type: "better-sqlite3" } },
+    query: (query: string): Promise<unknown> => sql.unsafe(query),
+  } as unknown as QueryRunner;
+  await new InitAuditLogs1720300000000().up(runner);
+  for (let index = 0; index < entries; index += 1) {
+    await sql`
+      INSERT INTO "audit_logs" ("id", "action", "actorEmail", "createdAt")
+      VALUES (${`e${index}`}, ${index % 2 ? "user.ban" : "auth.login"}, ${"admin@example.com"},
+              ${new Date(Date.UTC(2026, 0, 1, 0, 0, index)).toISOString()})
+    `;
+  }
+  return new AuditService(sql, { dialect: "sqlite", enabled: () => Promise.resolve(true) });
+}
+
+type Get = (path: string) => Promise<Response>;
+
+function app(audit: AuditService, admin = true): Get {
+  const server = 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(auditRoutes(audit, () =>
+      admin
+        ? Promise.resolve()
+        : Promise.reject(new AppException("ADMIN_REQUIRED", "Administrator access is required", 403))
+    ));
+  return (path) => server.handle(new Request(`http://localhost${path}`));
+}
+
+describe("GET /audit-logs", () => {
+  test("returns an array and the next cursor in a header until the last page", async () => {
+    const get = app(await service(5));
+    const seen: string[] = [];
+    let path = "/audit-logs?limit=2";
+    for (let pages = 0; pages < 5; pages += 1) {
+      const response = await get(path);
+      expect(response.status).toBe(200);
+      const body = (await response.json()) as Array<{ id: string }>;
+      expect(Array.isArray(body)).toBe(true);
+      seen.push(...body.map((entry) => entry.id));
+      const next = response.headers.get(AUDIT_NEXT_CURSOR_HEADER);
+      if (!next) break;
+      path = `/audit-logs?limit=2&cursor=${encodeURIComponent(next)}`;
+    }
+    expect(seen).toEqual(["e4", "e3", "e2", "e1", "e0"]);
+  });
+
+  test("lists newest first unless order=asc", async () => {
+    const get = app(await service(3));
+    const ids = async (path: string): Promise<string[]> =>
+      ((await (await get(path)).json()) as Array<{ id: string }>).map((entry) => entry.id);
+    expect(await ids("/audit-logs")).toEqual(["e2", "e1", "e0"]);
+    expect(await ids("/audit-logs?order=desc")).toEqual(["e2", "e1", "e0"]);
+    expect(await ids("/audit-logs?order=asc")).toEqual(["e0", "e1", "e2"]);
+  });
+
+  test("filters on the server", async () => {
+    const get = app(await service(4));
+    const body = (await (await get("/audit-logs?action=user.ban")).json()) as Array<{ action: string }>;
+    expect(body.map((entry) => entry.action)).toEqual(["user.ban", "user.ban"]);
+  });
+
+  test("rejects out-of-range or malformed parameters", async () => {
+    const get = app(await service(1));
+    for (const query of ["limit=101", "limit=0", "limit=1.5", "order=sideways"]) {
+      const response = await get(`/audit-logs?${query}`);
+      expect(response.status).toBe(400);
+      expect(await response.json()).toEqual({ code: "VALIDATION_ERROR" });
+    }
+    const response = await get("/audit-logs?cursor=not-a-cursor");
+    expect(response.status).toBe(400);
+    expect(await response.json()).toEqual({ code: "INVALID_CURSOR" });
+  });
+
+  test("is admin-only", async () => {
+    const get = app(await service(1), false);
+    expect((await get("/audit-logs")).status).toBe(403);
+    expect((await get("/audit-logs/actions")).status).toBe(403);
+  });
+});
+
+describe("GET /audit-logs/actions", () => {
+  test("lists the recorded action codes", async () => {
+    const get = app(await service(3));
+    expect(await (await get("/audit-logs/actions")).json()).toEqual(["auth.login", "user.ban"]);
+  });
+});