@basaltkit/audit-viewer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Machize Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @basaltkit/audit-viewer
+
+**Read-only** viewer for the audit trail produced by [`@basaltkit/audit`](https://www.npmjs.com/package/@basaltkit/audit): **per-tenant**, filterable and paginated queries, with aggregated **statistics**, and a self-contained **HTML page** to browse it. You need this module when you want to give admins (or yourself) a way to review who did what — for support, compliance, or debugging.
+
+## What this module solves
+
+`@basaltkit/audit` writes an *append-only* (immutable) trail of everything that happens. This module is the lens for reading it: filter by event/actor/period/source, paginate, view totals and distributions — plus a page ready to open in the browser. It never writes to or alters the trail.
+
+## Installation
+
+```bash
+pnpm add @basaltkit/audit-viewer @basaltkit/audit
+```
+
+Depends on `@basaltkit/core`, `@basaltkit/audit`, and `@basaltkit/fastify`. Requires the `auditPlugin` to be registered (that's where the trail comes from).
+
+## Get started in 5 minutes
+
+```ts
+import { createApp } from '@basaltkit/core'
+import { auditPlugin } from '@basaltkit/audit'
+import { auditViewerPlugin, auditViewerRoutes, AUDIT_VIEWER } from '@basaltkit/audit-viewer'
+import { fastifyPlugin } from '@basaltkit/fastify'
+
+const app = await createApp({
+  plugins: [
+    auditPlugin(),
+    auditViewerPlugin(),
+    fastifyPlugin({ routes: [...auditViewerRoutes()] }),
+  ],
+}).boot()
+
+// programmatically
+const viewer = app.container.get(AUDIT_VIEWER)
+const page = await viewer.page({ tenantId: 'acme', event: 'auth:**', limit: 50 })
+const stats = await viewer.stats({ tenantId: 'acme' })
+```
+
+## Routes
+
+`auditViewerRoutes()` (all require login — add your own admin *guard* on top):
+
+| Route | Description |
+|---|---|
+| `GET /audit?event=&actorId=&source=&since=&until=&limit=&offset=` | Page of entries (most recent first) + `total`. |
+| `GET /audit/stats?…` | Aggregates: by event, by actor, by source, timeline. |
+| `GET /audit/:id` | A single entry. |
+| `GET /audit/view` | HTML page for browsing (filters + table + pagination). |
+
+All are **tenant-isolated** (the tenant comes from the request context).
+
+## The HTML page
+
+`GET /audit/view` serves a vanilla page (no build step, no dependencies) that calls the JSON routes and shows a filterable table with pagination. Customize the title/base path:
+
+```ts
+auditViewerRoutes({ title: 'Audit — Acme', apiBase: '/admin' })
+```
+
+## API reference
+
+### `auditViewerPlugin({ bucketMs?, topN? })`
+
+Registers the `AUDIT_VIEWER` token. `bucketMs` is the timeline bucket size (default 1 day); `topN` limits the per-event/actor tables (default 20).
+
+### `class AuditViewer`
+
+| Method | Description |
+|---|---|
+| `page(query)` | `{ entries, total, limit, offset }`. |
+| `stats(query)` | `{ total, 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.
+
+## How it connects to other modules
+
+- **`@basaltkit/audit`** — the immutable source of the trail (this module only reads it).
+- **`@basaltkit/permissions`** — adds a *guard* (`meta.can: 'audit:read'`) to restrict access to admins.
+- **`@basaltkit/exports`** — exports a query's result to CSV for compliance reports.

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+import * as _basaltkit_core from '@basaltkit/core';
+import { BasaltError } from '@basaltkit/core';
+import { Audit, AuditEntry } from '@basaltkit/audit';
+import { BasaltRoute } from '@basaltkit/fastify';
+
+declare class AuditTenantRequiredError extends BasaltError {
+    readonly status = 400;
+    constructor();
+}
+interface ViewerQuery {
+    /** Wildcard pattern over the event name (e.g. `auth:**`). */
+    event?: string;
+    actorId?: string;
+    tenantId?: string;
+    source?: AuditEntry['source'];
+    /** Lower/upper time bounds (ms epoch). */
+    since?: number;
+    until?: number;
+    limit?: number;
+    offset?: number;
+}
+interface AuditPage {
+    entries: AuditEntry[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface AuditStats {
+    total: number;
+    byEvent: {
+        event: string;
+        count: number;
+    }[];
+    byActor: {
+        actorId: string;
+        count: number;
+    }[];
+    bySource: Record<string, number>;
+    /** Counts bucketed by `bucketMs` (default one day), oldest first. */
+    timeline: {
+        at: number;
+        count: number;
+    }[];
+}
+interface AuditViewerOptions {
+    /** Timeline bucket size in ms. Default one day. */
+    bucketMs?: number;
+    /** How many rows the byEvent/byActor breakdowns return. Default 20. */
+    topN?: number;
+}
+/**
+ * Read-only lens over the append-only audit trail: tenant-scoped, filterable,
+ * paginated queries plus aggregate stats. Wraps {@link Audit}; the trail itself
+ * stays immutable.
+ */
+declare class AuditViewer {
+    private readonly audit;
+    private readonly bucketMs;
+    private readonly topN;
+    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. */
+    private match;
+    private top;
+    private tenant;
+}
+
+interface AuditViewerHtmlOptions {
+    /** Base path where the audit JSON API is mounted. Default '' (same origin). */
+    apiBase?: string;
+    title?: 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
+ * route (see `auditViewerRoutes`).
+ */
+declare function auditViewerHtml(options?: AuditViewerHtmlOptions): string;
+
+declare const AUDIT_VIEWER: _basaltkit_core.Token<AuditViewer>;
+type AuditViewerPluginOptions = AuditViewerOptions;
+declare function auditViewerPlugin(options?: AuditViewerPluginOptions): _basaltkit_core.BasaltPlugin<unknown>;
+/**
+ * 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`.
+ */
+declare function auditViewerRoutes(options?: AuditViewerHtmlOptions): BasaltRoute[];
+
+export { AUDIT_VIEWER, type AuditPage, type AuditStats, AuditTenantRequiredError, AuditViewer, type AuditViewerHtmlOptions, type AuditViewerOptions, type AuditViewerPluginOptions, type ViewerQuery, auditViewerHtml, auditViewerPlugin, auditViewerRoutes };

package/dist/index.js

@@ -0,0 +1,222 @@
+// src/viewer.ts
+import { BasaltError, tryCtx } from "@basaltkit/core";
+var AuditTenantRequiredError = class extends BasaltError {
+  status = 400;
+  constructor() {
+    super("AUDIT_TENANT_REQUIRED", "A tenant is required \u2014 pass tenantId or run inside a tenant context.");
+  }
+};
+var DAY = 864e5;
+var AuditViewer = class {
+  constructor(audit, options = {}) {
+    this.audit = audit;
+    this.bucketMs = options.bucketMs ?? DAY;
+    this.topN = options.topN ?? 20;
+  }
+  audit;
+  bucketMs;
+  topN;
+  async page(query = {}) {
+    const all = 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 };
+  }
+  async get(id, tenantId) {
+    const all = await this.match({ ...tenantId !== void 0 ? { tenantId } : {} });
+    return all.find((entry) => entry.id === id) ?? null;
+  }
+  async stats(query = {}) {
+    const all = await this.match(query);
+    const byEvent = /* @__PURE__ */ new Map();
+    const byActor = /* @__PURE__ */ new Map();
+    const bySource = {};
+    const timeline = /* @__PURE__ */ new Map();
+    for (const entry of all) {
+      byEvent.set(entry.event, (byEvent.get(entry.event) ?? 0) + 1);
+      if (entry.actorId) byActor.set(entry.actorId, (byActor.get(entry.actorId) ?? 0) + 1);
+      bySource[entry.source] = (bySource[entry.source] ?? 0) + 1;
+      const bucket = Math.floor(entry.at / this.bucketMs) * this.bucketMs;
+      timeline.set(bucket, (timeline.get(bucket) ?? 0) + 1);
+    }
+    return {
+      total: all.length,
+      byEvent: this.top(byEvent).map(([event, count]) => ({ event, count })),
+      byActor: this.top(byActor).map(([actorId, count]) => ({ actorId, count })),
+      bySource,
+      timeline: [...timeline.entries()].sort((a, b) => a[0] - b[0]).map(([at, count]) => ({ at, count }))
+    };
+  }
+  /** Matching entries (newest first), after the extra source/until filters. */
+  async match(query) {
+    const tenantId = this.tenant(query.tenantId);
+    const trail = await this.audit.trail({
+      tenantId,
+      ...query.event !== void 0 ? { event: query.event } : {},
+      ...query.actorId !== void 0 ? { actorId: query.actorId } : {},
+      ...query.since !== void 0 ? { since: query.since } : {}
+    });
+    return trail.filter(
+      (entry) => (query.source === void 0 || entry.source === query.source) && (query.until === void 0 || entry.at <= query.until)
+    );
+  }
+  top(counts) {
+    return [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, this.topN);
+  }
+  tenant(explicit) {
+    const id = explicit ?? tryCtx()?.["tenant"]?.id;
+    if (!id) throw new AuditTenantRequiredError();
+    return id;
+  }
+};
+
+// src/html.ts
+function auditViewerHtml(options = {}) {
+  const apiBase = options.apiBase ?? "";
+  const title = options.title ?? "Audit trail";
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${title}</title>
+<style>
+  :root { color-scheme: light dark; --bd: #8883; }
+  body { font: 14px/1.5 system-ui, sans-serif; margin: 0; padding: 1.5rem; max-width: 1100px; margin-inline: auto; }
+  h1 { font-size: 1.3rem; margin: 0 0 1rem; }
+  form { display: flex; gap: .5rem; flex-wrap: wrap; margin-bottom: 1rem; }
+  input, select { padding: .35rem .5rem; border: 1px solid var(--bd); border-radius: 6px; background: transparent; color: inherit; }
+  button { padding: .35rem .8rem; border: 1px solid var(--bd); border-radius: 6px; cursor: pointer; background: transparent; color: inherit; }
+  #stats { display: flex; gap: 1.5rem; flex-wrap: wrap; margin-bottom: 1rem; opacity: .85; }
+  table { width: 100%; border-collapse: collapse; }
+  th, td { text-align: left; padding: .4rem .6rem; border-bottom: 1px solid var(--bd); vertical-align: top; }
+  th { position: sticky; top: 0; }
+  code { font-family: ui-monospace, monospace; }
+  .muted { opacity: .6; }
+  .nav { display: flex; gap: .5rem; align-items: center; margin-top: 1rem; }
+</style>
+</head>
+<body>
+<h1>${title}</h1>
+<form id="filters">
+  <input name="event" placeholder="event (auth:**)" />
+  <input name="actorId" placeholder="actor id" />
+  <select name="source"><option value="">any source</option><option>hook</option><option>event</option><option>manual</option></select>
+  <button type="submit">Filter</button>
+</form>
+<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 + '\u2013' + (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>
+</body>
+</html>`;
+}
+
+// src/plugin.ts
+import { createToken, ctx, definePlugin } from "@basaltkit/core";
+import { AUDIT } from "@basaltkit/audit";
+import { route } from "@basaltkit/fastify";
+import { z } from "zod";
+var AUDIT_VIEWER = createToken("audit:viewer");
+function auditViewerPlugin(options = {}) {
+  return definePlugin({
+    name: "basalt:audit-viewer",
+    register({ container }) {
+      container.singleton(AUDIT_VIEWER, () => new AuditViewer(container.get(AUDIT), options));
+    }
+  });
+}
+var viewer = () => ctx().container.get(AUDIT_VIEWER);
+var querySchema = z.object({
+  event: z.string().optional(),
+  actorId: z.string().optional(),
+  source: z.enum(["hook", "event", "manual"]).optional(),
+  since: z.coerce.number().optional(),
+  until: z.coerce.number().optional(),
+  limit: z.coerce.number().optional(),
+  offset: z.coerce.number().optional()
+});
+var toQuery = (q) => ({
+  ...q.event !== void 0 ? { event: q.event } : {},
+  ...q.actorId !== void 0 ? { actorId: q.actorId } : {},
+  ...q.source !== void 0 ? { source: q.source } : {},
+  ...q.since !== void 0 ? { since: q.since } : {},
+  ...q.until !== void 0 ? { until: q.until } : {},
+  ...q.limit !== void 0 ? { limit: q.limit } : {},
+  ...q.offset !== void 0 ? { offset: q.offset } : {}
+});
+function auditViewerRoutes(options = {}) {
+  return [
+    route({
+      method: "GET",
+      url: "/audit",
+      meta: { auth: true },
+      query: querySchema,
+      async handler({ query }) {
+        return viewer().page(toQuery(query));
+      }
+    }),
+    route({
+      method: "GET",
+      url: "/audit/stats",
+      meta: { auth: true },
+      query: querySchema,
+      async handler({ query }) {
+        return viewer().stats(toQuery(query));
+      }
+    }),
+    route({
+      method: "GET",
+      url: "/audit/view",
+      meta: { auth: true },
+      async handler({ reply }) {
+        return reply.header("content-type", "text/html; charset=utf-8").send(auditViewerHtml(options));
+      }
+    }),
+    route({
+      method: "GET",
+      url: "/audit/:id",
+      meta: { auth: true },
+      params: z.object({ id: z.string() }),
+      async handler({ params, reply }) {
+        const entry = await viewer().get(params.id);
+        return entry ?? reply.code(404).send({ error: { code: "AUDIT_NOT_FOUND", message: "Entry not found." } });
+      }
+    })
+  ];
+}
+export {
+  AUDIT_VIEWER,
+  AuditTenantRequiredError,
+  AuditViewer,
+  auditViewerHtml,
+  auditViewerPlugin,
+  auditViewerRoutes
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@basaltkit/audit-viewer",
+  "version": "1.0.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",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@basaltkit/core": "^1.0.0",
+    "@basaltkit/fastify": "^1.0.0",
+    "@basaltkit/audit": "^1.0.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.24.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0",
+    "zod": "^3.24.0",
+    "@basaltkit/tenancy": "^1.0.0",
+    "@basaltkit/auth": "^1.0.0",
+    "@basaltkit/tsconfig": "^0.24.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "directory": "packages/audit-viewer"
+  },
+  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/audit-viewer#readme",
+  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "keywords": [
+    "basalt",
+    "typescript",
+    "saas",
+    "audit",
+    "compliance"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}