@basaltkit/audit-viewer 1.1.0 → 1.3.0

package/README.md

@@ -65,21 +65,29 @@ 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
 

package/dist/plugin.js

@@ -1,4 +1,4 @@
-import { createToken, ctx, definePlugin } from '@basaltkit/core';
+import { createToken, ctx, definePlugin, ensureMetadata } from '@basaltkit/core';
 import { AUDIT } from '@basaltkit/audit';
 import { route } from '@basaltkit/http';
 import { z } from 'zod';
@@ -9,7 +9,10 @@ export function auditViewerPlugin(options = {}) {
     return definePlugin({
         name: 'basalt:audit-viewer',
         register({ container }) {
-            container.singleton(AUDIT_VIEWER, () => new AuditViewer(container.get(AUDIT), options));
+            // 'tenancy:active' is tenancyPlugin's marker: how a generic package
+            // learns the app is multi-tenant without importing @basaltkit/tenancy.
+            const metadata = ensureMetadata(container);
+            container.singleton(AUDIT_VIEWER, () => new AuditViewer(container.get(AUDIT), options, () => metadata.get('tenancy:active').length > 0));
         },
     });
 }

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,
@@ -52,14 +64,44 @@ export interface AuditViewerOptions {
  */
 export declare class AuditViewer {
     private readonly audit;
+    /**
+     * Whether the host app is multi-tenant, i.e. whether `@basaltkit/tenancy`
+     * is registered. `auditViewerPlugin` wires this to the container's
+     * `'tenancy:active'` metadata marker — a signal, not an import, so this
+     * generic package never depends on the opt-in SaaS layer.
+     *
+     * Defaults to `false`: a hand-built viewer behaves single-tenant.
+     */
+    private readonly tenancyActive;
     private readonly bucketMs;
     private readonly topN;
-    constructor(audit: Audit, options?: AuditViewerOptions);
+    private readonly maxScan;
+    constructor(audit: Audit, options?: AuditViewerOptions, 
+    /**
+     * Whether the host app is multi-tenant, i.e. whether `@basaltkit/tenancy`
+     * is registered. `auditViewerPlugin` wires this to the container's
+     * `'tenancy:active'` metadata marker — a signal, not an import, so this
+     * generic package never depends on the opt-in SaaS layer.
+     *
+     * Defaults to `false`: a hand-built viewer behaves single-tenant.
+     */
+    tenancyActive?: () => boolean);
     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;
+    /**
+     * The tenant to scope a read to, or `undefined` when the app has no tenant
+     * dimension at all.
+     *
+     * In a multi-tenant app an unresolvable tenant is an error — an unscoped read
+     * would cross tenants. In a single-tenant app (no `tenancyPlugin`) there is
+     * nothing to scope to and nothing to cross, so the read proceeds unscoped;
+     * `Audit.trail()` applies the same rule one layer down and still forces the
+     * ambient tenant whenever one exists.
+     */
     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
@@ -13,25 +14,38 @@ const DAY = 86_400_000;
  */
 export class AuditViewer {
     audit;
+    tenancyActive;
     bucketMs;
     topN;
-    constructor(audit, options = {}) {
+    maxScan;
+    constructor(audit, options = {}, 
+    /**
+     * Whether the host app is multi-tenant, i.e. whether `@basaltkit/tenancy`
+     * is registered. `auditViewerPlugin` wires this to the container's
+     * `'tenancy:active'` metadata marker — a signal, not an import, so this
+     * generic package never depends on the opt-in SaaS layer.
+     *
+     * Defaults to `false`: a hand-built viewer behaves single-tenant.
+     */
+    tenancyActive = () => false) {
         this.audit = audit;
+        this.tenancyActive = tenancyActive;
         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 +60,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,24 +68,39 @@ 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,
+            ...(tenantId !== undefined ? { 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);
     }
+    /**
+     * The tenant to scope a read to, or `undefined` when the app has no tenant
+     * dimension at all.
+     *
+     * In a multi-tenant app an unresolvable tenant is an error — an unscoped read
+     * would cross tenants. In a single-tenant app (no `tenancyPlugin`) there is
+     * nothing to scope to and nothing to cross, so the read proceeds unscoped;
+     * `Audit.trail()` applies the same rule one layer down and still forces the
+     * ambient tenant whenever one exists.
+     */
     tenant(explicit) {
         const id = explicit ?? tryCtx()?.['tenant']?.id;
-        if (!id)
+        if (id)
+            return id;
+        if (this.tenancyActive())
             throw new AuditTenantRequiredError();
-        return id;
+        return undefined;
     }
 }

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@basaltkit/audit-viewer",
-  "version": "1.1.0",
+  "version": "1.3.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.3.0",
-    "@basaltkit/http": "^1.11.0"
+    "@basaltkit/audit": "^1.4.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.7.0",
-    "@basaltkit/tenancy": "^1.4.0",
+    "@basaltkit/auth": "^1.8.0",
+    "@basaltkit/fastify": "^1.8.1",
+    "@basaltkit/tenancy": "^1.4.2",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {