@podosoft/podokit 1.1.6 → 1.2.0

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

@@ -18,11 +18,35 @@ 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/auth/admin/list-users" && url.searchParams.get("filterField") === "role";
+  });
   await page.getByRole("button", { name: "Search", exact: true }).click();
+  expect(new URL((await filtered).url()).searchParams.get("filterValue")).toBe("admin");
   await expect(main.getByRole("cell", { name: "admin@example.com" })).toBeVisible();
   await expect(main.getByRole("cell", { name: "user@example.com" })).toHaveCount(0);
 });
 
+test("users toolbar keeps one filter because the server accepts one", async ({ page }) => {
+  await ready(page, "/admin/users");
+  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: "Banned", exact: true }).click();
+  await expect(roleSelect).toContainText("All");
+  await expect(statusSelect).toContainText("Banned");
+
+  const filtered = page.waitForResponse((response) => {
+    const url = new URL(response.url());
+    return url.pathname === "/api/auth/admin/list-users" && url.searchParams.get("filterField") === "banned";
+  });
+  await page.getByRole("button", { name: "Search", exact: true }).click();
+  expect(new URL((await filtered).url()).searchParams.get("filterValue")).toBe("true");
+});
+
 test("users toolbar can pick the search field", async ({ page }) => {
   await ready(page, "/admin/users");
   const fieldSelect = page.locator('button[data-slot="select-trigger"]').last(); // after the filters

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/auth/admin/list-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,6 +43,26 @@ 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/auth/admin/list-users";
+  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");
+
+  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("searchValue")).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();
+});
+
 test("user list shows the joined column", async ({ page }) => {
   await ready(page, "/admin/users");
   await expect(page.getByRole("columnheader", { name: "Joined" })).toBeVisible();

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,6 +1,9 @@
 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 {
   return {
@@ -12,6 +15,31 @@ function runner(type: "postgres" | "better-sqlite3", queries: string[]): QueryRu
   } as unknown as QueryRunner;
 }
 
+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 +59,56 @@ describe("audit log migration", () => {
     expect(queries.join("\n")).not.toContain("CREATE EXTENSION");
   });
 });
+
+describe("audit filter index migration", () => {
+  it("replaces the single-column indexes on PostgreSQL and restores them on revert", async () => {
+    const migration = new IndexAuditLogFilters1792000000000();
+    const up: string[] = [];
+    await migration.up(runner("postgres", 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"',
+    ]);
+    expect(up.join("\n")).not.toContain("CONCURRENTLY");
+
+    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("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"]);
+  });
+});

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

@@ -0,0 +1,44 @@
+import { Elysia, t } from "elysia";
+import type { ElysiaPlugin } from "../core/services";
+import { MAX_AUDIT_PAGE_SIZE, type AuditService } from "./audit.service";
+
+/** Carries the cursor for the next page, so the body stays a plain array. */
+export const AUDIT_NEXT_CURSOR_HEADER = "x-next-cursor";
+
+const listQuery = t.Object({
+  cursor: t.Optional(t.String({ maxLength: 512 })),
+  limit: t.Optional(t.Numeric({ minimum: 1, maximum: MAX_AUDIT_PAGE_SIZE, multipleOf: 1 })),
+  // Not t.UnionEnum: Elysia fills an absent optional UnionEnum with its first value.
+  order: t.Optional(t.Union([t.Literal("asc"), t.Literal("desc")])),
+  action: t.Optional(t.String({ maxLength: 128 })),
+  actor: t.Optional(t.String({ maxLength: 512 })),
+  target: t.Optional(t.String({ maxLength: 512 })),
+});
+
+export function auditRoutes(
+  audit: AuditService,
+  requireAdmin: (request: Request) => Promise<unknown>,
+): ElysiaPlugin {
+  return new Elysia({ name: "podokit.audit" })
+    .get("/audit-logs", async ({ request, query, set }) => {
+      await requireAdmin(request);
+      const page = await audit.list(query);
+      if (page.nextCursor) set.headers[AUDIT_NEXT_CURSOR_HEADER] = page.nextCursor;
+      return page.entries;
+    }, {
+      query: listQuery,
+      detail: {
+        tags: ["audit"],
+        summary: "List audit entries",
+        description:
+          "Newest first unless order=asc. action, actor (email), and target (label) match exactly. " +
+          "When more entries follow, the X-Next-Cursor response header holds the cursor for the next page.",
+      },
+    })
+    .get("/audit-logs/actions", async ({ request }) => {
+      await requireAdmin(request);
+      return audit.actions();
+    }, {
+      detail: { tags: ["audit"], summary: "List the recorded audit action codes" },
+    });
+}