@basaltkit/audit-viewer 1.0.2 → 1.2.0

package/README.md

@@ -65,21 +65,39 @@ auditViewerRoutes({ title: 'Audit — Acme', apiBase: '/admin' })
 
 ## API reference
 
-### `auditViewerPlugin({ bucketMs?, topN? })`
+### `auditViewerPlugin({ bucketMs?, topN?, maxScan? })`
 
-Registers the `AUDIT_VIEWER` token. `bucketMs` is the timeline bucket size (default 1 day); `topN` limits the per-event/actor tables (default 20).
+Registers the `AUDIT_VIEWER` token.
+
+| Option | Type | Default | Purpose |
+|---|---|---|---|
+| `bucketMs` | `number` | `86_400_000` (1 day) | Timeline bucket size. |
+| `topN` | `number` | `20` | Rows returned by the per-event / per-actor breakdowns. |
+| `maxScan` | `number` | `10_000` | Upper bound on rows read from the store per call. |
+
+`maxScan` exists because the trail is unbounded and these routes forward client input: an unbounded read is an OOM vector. When a call hits the bound, the result carries `truncated: true` and `total` means "matches within the window", not a grand total.
 
 ### `class AuditViewer`
 
 | Method | Description |
 |---|---|
-| `page(query)` | `{ entries, total, limit, offset }`. |
-| `stats(query)` | `{ total, byEvent, byActor, bySource, timeline }`. |
+| `page(query)` | `{ entries, total, limit, offset, truncated }`. |
+| `stats(query)` | `{ total, truncated, byEvent, byActor, bySource, timeline }`. |
 | `get(id, tenantId?)` | A single entry, or `null`. |
 
 `ViewerQuery`: `event` (wildcard), `actorId`, `tenantId`, `source` (`hook`/`event`/`manual`), `since`, `until`, `limit`, `offset`. Without `tenantId`, it uses `ctx().tenant.id` (otherwise `AuditTenantRequiredError`).
 
-> Note: the extra filtering (source/until) and the aggregation happen in memory over the result of `Audit.trail`. For very large trails, use an `AuditStore` with rich database querying.
+> Note: the extra filtering (source/until) and the aggregation happen in memory over the result of `Audit.trail`, bounded by `maxScan`. `truncated: true` means the trail had more matches than the window — raise `maxScan`, narrow the query (`since`/`until`/`event`), or use an `AuditStore` with richer database querying.
+
+## Content-Security-Policy
+
+The route sets a route-scoped CSP by default: everything locked down and the
+page's inline script allowed only by sha256 hash (exported as `auditViewerCsp`). It
+works under `securityPlugin`'s strict app-wide CSP — do not disable CSP
+globally. Override with `csp: '…'` or opt out with `csp: false`; if you serve
+the raw HTML string yourself, set the matching CSP header on that route.
+Server-side inputs are HTML-escaped and embedded state cannot terminate the
+script block.
 
 ## How it connects to other modules
 

package/dist/html.d.ts

@@ -3,6 +3,13 @@ export interface AuditViewerHtmlOptions {
     apiBase?: string;
     title?: string;
 }
+/**
+ * The Content-Security-Policy matching {@link auditViewerHtml}: everything
+ * locked down, the page's inline script allowed by sha256 hash. Served by
+ * default from `auditViewerRoutes` so the page works under `securityPlugin`
+ * without weakening the app-wide policy.
+ */
+export declare function auditViewerCsp(options?: AuditViewerHtmlOptions): string;
 /**
  * A self-contained HTML page (no dependencies, no build) that browses the audit
  * trail by calling `GET {apiBase}/audit` and `/audit/stats`. Serve it from a

package/dist/html.js

@@ -1,3 +1,49 @@
+import { escapeHtml, pageCsp, scriptJson } from '@basaltkit/http';
+// The inline script, built separately so the page and its CSP hash (see
+// auditViewerCsp) come from the exact same source text. Embedded state uses
+// scriptJson (cannot terminate the script block); API responses render through
+// esc(), whose charset includes quotes for attribute positions.
+const pageScript = (apiBase) => `
+const API = ${scriptJson(apiBase)};
+let offset = 0; const LIMIT = 50;
+const esc = (s) => String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+function params() {
+  const f = new FormData(document.getElementById('filters'));
+  const q = new URLSearchParams();
+  for (const [k, v] of f) if (v) q.set(k, v);
+  q.set('limit', LIMIT); q.set('offset', offset);
+  return q.toString();
+}
+async function load() {
+  const [page, stats] = await Promise.all([
+    fetch(API + '/audit?' + params()).then((r) => r.json()),
+    fetch(API + '/audit/stats?' + params()).then((r) => r.json()),
+  ]);
+  document.getElementById('rows').innerHTML = (page.entries || []).map((e) =>
+    '<tr><td class="muted">' + new Date(e.at).toLocaleString() + '</td><td><code>' + esc(e.event) +
+    '</code></td><td>' + esc(e.source) + '</td><td>' + esc(e.actorId || '') + '</td></tr>').join('');
+  const top = (stats.byEvent || []).slice(0, 3).map((x) => esc(x.event) + ' (' + x.count + ')').join(', ');
+  document.getElementById('stats').innerHTML = '<span><b>' + (stats.total || 0) + '</b> entries</span>' + (top ? '<span>Top: ' + top + '</span>' : '');
+  document.getElementById('page').textContent = 'showing ' + offset + '–' + (offset + (page.entries || []).length) + ' of ' + (page.total || 0);
+}
+document.getElementById('filters').addEventListener('submit', (e) => { e.preventDefault(); offset = 0; load(); });
+document.getElementById('next').addEventListener('click', () => { offset += LIMIT; load(); });
+document.getElementById('prev').addEventListener('click', () => { offset = Math.max(0, offset - LIMIT); load(); });
+load();
+`;
+/**
+ * The Content-Security-Policy matching {@link auditViewerHtml}: everything
+ * locked down, the page's inline script allowed by sha256 hash. Served by
+ * default from `auditViewerRoutes` so the page works under `securityPlugin`
+ * without weakening the app-wide policy.
+ */
+export function auditViewerCsp(options = {}) {
+    const apiBase = options.apiBase ?? '';
+    return pageCsp({
+        scripts: [pageScript(apiBase)],
+        ...(/^https?:\/\//.test(apiBase) ? { connect: [new URL(apiBase).origin] } : {}),
+    });
+}
 /**
  * A self-contained HTML page (no dependencies, no build) that browses the audit
  * trail by calling `GET {apiBase}/audit` and `/audit/stats`. Serve it from a
@@ -5,7 +51,7 @@
  */
 export function auditViewerHtml(options = {}) {
     const apiBase = options.apiBase ?? '';
-    const title = options.title ?? 'Audit trail';
+    const title = escapeHtml(options.title ?? 'Audit trail');
     return `<!doctype html>
 <html lang="en">
 <head>
@@ -39,34 +85,7 @@ export function auditViewerHtml(options = {}) {
 <div id="stats"></div>
 <table><thead><tr><th>When</th><th>Event</th><th>Source</th><th>Actor</th></tr></thead><tbody id="rows"></tbody></table>
 <div class="nav"><button id="prev">Prev</button><span id="page" class="muted"></span><button id="next">Next</button></div>
-<script>
-const API = ${JSON.stringify(apiBase)};
-let offset = 0; const LIMIT = 50;
-const esc = (s) => String(s == null ? '' : s).replace(/[&<>]/g, (c) => ({'&':'&amp;','<':'&lt;','>':'&gt;'}[c]));
-function params() {
-  const f = new FormData(document.getElementById('filters'));
-  const q = new URLSearchParams();
-  for (const [k, v] of f) if (v) q.set(k, v);
-  q.set('limit', LIMIT); q.set('offset', offset);
-  return q.toString();
-}
-async function load() {
-  const [page, stats] = await Promise.all([
-    fetch(API + '/audit?' + params()).then((r) => r.json()),
-    fetch(API + '/audit/stats?' + params()).then((r) => r.json()),
-  ]);
-  document.getElementById('rows').innerHTML = (page.entries || []).map((e) =>
-    '<tr><td class="muted">' + new Date(e.at).toLocaleString() + '</td><td><code>' + esc(e.event) +
-    '</code></td><td>' + esc(e.source) + '</td><td>' + esc(e.actorId || '') + '</td></tr>').join('');
-  const top = (stats.byEvent || []).slice(0, 3).map((x) => esc(x.event) + ' (' + x.count + ')').join(', ');
-  document.getElementById('stats').innerHTML = '<span><b>' + (stats.total || 0) + '</b> entries</span>' + (top ? '<span>Top: ' + top + '</span>' : '');
-  document.getElementById('page').textContent = 'showing ' + offset + '–' + (offset + (page.entries || []).length) + ' of ' + (page.total || 0);
-}
-document.getElementById('filters').addEventListener('submit', (e) => { e.preventDefault(); offset = 0; load(); });
-document.getElementById('next').addEventListener('click', () => { offset += LIMIT; load(); });
-document.getElementById('prev').addEventListener('click', () => { offset = Math.max(0, offset - LIMIT); load(); });
-load();
-</script>
+<script>${pageScript(apiBase)}</script>
 </body>
 </html>`;
 }

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { AuditViewer, AuditTenantRequiredError, type ViewerQuery, type AuditPage, type AuditStats, type AuditViewerOptions, } from './viewer.js';
-export { auditViewerHtml, type AuditViewerHtmlOptions } from './html.js';
-export { auditViewerPlugin, auditViewerRoutes, AUDIT_VIEWER, type AuditViewerPluginOptions, } from './plugin.js';
+export { auditViewerCsp, auditViewerHtml, type AuditViewerHtmlOptions } from './html.js';
+export { auditViewerPlugin, auditViewerRoutes, AUDIT_VIEWER, type AuditViewerPluginOptions, type AuditViewerRoutesOptions, } from './plugin.js';

package/dist/index.js

@@ -1,3 +1,3 @@
 export { AuditViewer, AuditTenantRequiredError, } from './viewer.js';
-export { auditViewerHtml } from './html.js';
+export { auditViewerCsp, auditViewerHtml } from './html.js';
 export { auditViewerPlugin, auditViewerRoutes, AUDIT_VIEWER, } from './plugin.js';

package/dist/plugin.d.ts

@@ -4,9 +4,16 @@ import { type AuditViewerHtmlOptions } from './html.js';
 export declare const AUDIT_VIEWER: import("@basaltkit/core").Token<AuditViewer>;
 export type AuditViewerPluginOptions = AuditViewerOptions;
 export declare function auditViewerPlugin(options?: AuditViewerPluginOptions): import("@basaltkit/core").BasaltPlugin<unknown>;
+export interface AuditViewerRoutesOptions extends AuditViewerHtmlOptions {
+    /**
+     * Content-Security-Policy for the HTML page. Default: the hash-locked
+     * {@link auditViewerCsp}. Pass a string to override, or `false` to send none.
+     */
+    csp?: string | false;
+}
 /**
  * Read-only audit routes for the current tenant, requiring a logged-in user
  * (add your own admin guard on top): `GET /audit`, `/audit/stats`,
  * `/audit/:id`, and a browsable HTML page at `/audit/view`.
  */
-export declare function auditViewerRoutes(options?: AuditViewerHtmlOptions): BasaltRoute[];
+export declare function auditViewerRoutes(options?: AuditViewerRoutesOptions): BasaltRoute[];

package/dist/plugin.js

@@ -3,7 +3,7 @@ import { AUDIT } from '@basaltkit/audit';
 import { route } from '@basaltkit/http';
 import { z } from 'zod';
 import { AuditViewer } from './viewer.js';
-import { auditViewerHtml } from './html.js';
+import { auditViewerCsp, auditViewerHtml } from './html.js';
 export const AUDIT_VIEWER = createToken('audit:viewer');
 export function auditViewerPlugin(options = {}) {
     return definePlugin({
@@ -38,6 +38,7 @@ const toQuery = (q) => ({
  * `/audit/:id`, and a browsable HTML page at `/audit/view`.
  */
 export function auditViewerRoutes(options = {}) {
+    const csp = options.csp === false ? undefined : (options.csp ?? auditViewerCsp(options));
     return [
         route({
             method: 'GET',
@@ -62,6 +63,8 @@ export function auditViewerRoutes(options = {}) {
             url: '/audit/view',
             meta: { auth: true },
             async handler({ reply }) {
+                if (csp !== undefined)
+                    reply.header('content-security-policy', csp);
                 return reply.header('content-type', 'text/html; charset=utf-8').send(auditViewerHtml(options));
             },
         }),

package/dist/viewer.d.ts

@@ -18,12 +18,18 @@ export interface ViewerQuery {
 }
 export interface AuditPage {
     entries: AuditEntry[];
+    /** Matches found within the scan window — see `truncated`. */
     total: number;
     limit: number;
     offset: number;
+    /** True when the scan hit `maxScan`: there are more matches than `total` reports. */
+    truncated: boolean;
 }
 export interface AuditStats {
+    /** Entries counted within the scan window — see `truncated`. */
     total: number;
+    /** True when the scan hit `maxScan`: the aggregates cover only the newest rows. */
+    truncated: boolean;
     byEvent: {
         event: string;
         count: number;
@@ -44,6 +50,12 @@ export interface AuditViewerOptions {
     bucketMs?: number;
     /** How many rows the byEvent/byActor breakdowns return. Default 20. */
     topN?: number;
+    /**
+     * Upper bound on rows read from the store per call. The trail is unbounded, so
+     * an unbounded read is an OOM vector on any endpoint that forwards client input.
+     * Results past the bound are reported via `truncated`. Default 10 000.
+     */
+    maxScan?: number;
 }
 /**
  * Read-only lens over the append-only audit trail: tenant-scoped, filterable,
@@ -54,11 +66,13 @@ export declare class AuditViewer {
     private readonly audit;
     private readonly bucketMs;
     private readonly topN;
+    private readonly maxScan;
     constructor(audit: Audit, options?: AuditViewerOptions);
     page(query?: ViewerQuery): Promise<AuditPage>;
     get(id: string, tenantId?: string): Promise<AuditEntry | null>;
     stats(query?: ViewerQuery): Promise<AuditStats>;
     /** Matching entries (newest first), after the extra source/until filters. */
+    /** Reads at most `maxScan` rows and reports whether the trail had more. */
     private match;
     private top;
     private tenant;

package/dist/viewer.js

@@ -6,6 +6,7 @@ export class AuditTenantRequiredError extends BasaltError {
     }
 }
 const DAY = 86_400_000;
+const DEFAULT_MAX_SCAN = 10_000;
 /**
  * Read-only lens over the append-only audit trail: tenant-scoped, filterable,
  * paginated queries plus aggregate stats. Wraps {@link Audit}; the trail itself
@@ -15,23 +16,25 @@ export class AuditViewer {
     audit;
     bucketMs;
     topN;
+    maxScan;
     constructor(audit, options = {}) {
         this.audit = audit;
         this.bucketMs = options.bucketMs ?? DAY;
         this.topN = options.topN ?? 20;
+        this.maxScan = options.maxScan ?? DEFAULT_MAX_SCAN;
     }
     async page(query = {}) {
-        const all = await this.match(query);
+        const { entries: all, truncated } = await this.match(query);
         const limit = query.limit ?? 50;
         const offset = query.offset ?? 0;
-        return { entries: all.slice(offset, offset + limit), total: all.length, limit, offset };
+        return { entries: all.slice(offset, offset + limit), total: all.length, limit, offset, truncated };
     }
     async get(id, tenantId) {
-        const all = await this.match({ ...(tenantId !== undefined ? { tenantId } : {}) });
-        return all.find((entry) => entry.id === id) ?? null;
+        const { entries } = await this.match({ ...(tenantId !== undefined ? { tenantId } : {}) });
+        return entries.find((entry) => entry.id === id) ?? null;
     }
     async stats(query = {}) {
-        const all = await this.match(query);
+        const { entries: all, truncated } = await this.match(query);
         const byEvent = new Map();
         const byActor = new Map();
         const bySource = {};
@@ -46,6 +49,7 @@ export class AuditViewer {
         }
         return {
             total: all.length,
+            truncated,
             byEvent: this.top(byEvent).map(([event, count]) => ({ event, count })),
             byActor: this.top(byActor).map(([actorId, count]) => ({ actorId, count })),
             bySource,
@@ -53,16 +57,19 @@ export class AuditViewer {
         };
     }
     /** Matching entries (newest first), after the extra source/until filters. */
+    /** Reads at most `maxScan` rows and reports whether the trail had more. */
     async match(query) {
         const tenantId = this.tenant(query.tenantId);
         const trail = await this.audit.trail({
             tenantId,
+            limit: this.maxScan,
             ...(query.event !== undefined ? { event: query.event } : {}),
             ...(query.actorId !== undefined ? { actorId: query.actorId } : {}),
             ...(query.since !== undefined ? { since: query.since } : {}),
         });
-        return trail.filter((entry) => (query.source === undefined || entry.source === query.source) &&
+        const entries = trail.filter((entry) => (query.source === undefined || entry.source === query.source) &&
             (query.until === undefined || entry.at <= query.until));
+        return { entries, truncated: trail.length >= this.maxScan };
     }
     top(counts) {
         return [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, this.topN);

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@basaltkit/audit-viewer",
-  "version": "1.0.2",
+  "version": "1.2.0",
+  "engines": {
+    "node": ">=22.5.0"
+  },
   "description": "Read-only viewer for the @basaltkit/audit trail: tenant-scoped, filterable, paginated queries with aggregate stats, plus a self-contained HTML browser.",
   "license": "MIT",
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -14,9 +18,9 @@
     "dist"
   ],
   "dependencies": {
-    "@basaltkit/audit": "^1.2.2",
-    "@basaltkit/core": "^1.1.2",
-    "@basaltkit/http": "^1.9.1"
+    "@basaltkit/audit": "^1.3.0",
+    "@basaltkit/core": "^1.3.1",
+    "@basaltkit/http": "^1.14.0"
   },
   "peerDependencies": {
     "zod": "^3.24.0 || ^4.0.0"
@@ -26,9 +30,9 @@
     "typescript": "^7.0.2",
     "vitest": "^4.1.11",
     "zod": "^3.24.0 || ^4.0.0",
-    "@basaltkit/auth": "^1.6.3",
-    "@basaltkit/fastify": "^1.6.1",
-    "@basaltkit/tenancy": "^1.3.3",
+    "@basaltkit/auth": "^1.8.0",
+    "@basaltkit/fastify": "^1.8.1",
+    "@basaltkit/tenancy": "^1.4.2",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {