@basaltkit/audit 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,234 @@
+# @basaltkit/audit
+
+Audit trail for Basalt applications: automatically records, in an immutable history, who did what and when — from lifecycle hooks, domain events, and manual records.
+
+You need this module when you have to be able to answer questions like "who logged into this account?" or "who changed this billing plan?" — for security, support, or compliance reasons.
+
+---
+
+## What this module solves
+
+**Auditing** is the systematic recording of relevant actions in a system: logins, billing changes, permission changes. Unlike technical logs (which are for developers and can be deleted), the audit trail is a business record: **append-only** (only added to, never altered or deleted) and enriched with the **actor** (who did it), the **tenant** (which organization it belongs to), and the **request** (requestId) — all captured automatically from the active context at record time.
+
+The tedious part of auditing is remembering to record everywhere. This module solves that by hooking into what the application already emits: the `@basaltkit/core` lifecycle **hooks** (e.g. `auth:login`, `billing:subscribed`) and the `@basaltkit/events` **domain events** (e.g. `order.created`). You choose what gets recorded using wildcard patterns — by default, all `auth`, `billing`, `tenancy`, and `permission` activity (hooks) and **all** events.
+
+Each entry is frozen (`Object.freeze`) — code can't tamper with the in-memory history, even by accident. To query, use `audit.trail()` with filters on event (with wildcards), tenant, actor, and date.
+
+## Installation
+
+```bash
+pnpm add @basaltkit/audit
+```
+
+Depends on `@basaltkit/core` and `@basaltkit/events`. The default storage is in-memory (`MemoryAuditStore`) — for production you should provide a persistent `AuditStore` (see "Custom store").
+
+## Get started in 5 minutes
+
+**1. Register the plugin (along with the events plugin, if you use it):**
+
+```ts
+import { createApp } from '@basaltkit/core'
+import { eventsPlugin } from '@basaltkit/events'
+import { AUDIT, auditPlugin } from '@basaltkit/audit'
+
+const app = await createApp({
+  plugins: [eventsPlugin(), auditPlugin()],
+}).boot()
+```
+
+**2. From here on, relevant hooks and events get recorded on their own.** For example, when the auth module emits the `auth:login` hook, an audit entry is created with the actor and tenant from context.
+
+**3. Query the trail:**
+
+```ts
+const audit = app.container.get(AUDIT)
+
+const trail = await audit.trail()               // everything, most recent first
+const logins = await audit.trail({ event: 'auth:**' })
+console.log(logins[0])
+// {
+//   id: '4f1c…', source: 'hook', event: 'auth:login',
+//   payload: { user: { id: 'u1', email: 'a@b.c' } },
+//   actorId: 'u1', tenantId: 'acme', requestId: 'req-1', at: 1754500000000
+// }
+```
+
+**4. Manually record what hooks don't cover:**
+
+```ts
+await audit.record('data.export', { format: 'csv' })
+```
+
+## Usage guide
+
+### Automatic hook capture
+
+By default, hooks matching `auth:**`, `billing:**`, `tenancy:**`, or `permission:**` are recorded. You can replace the list:
+
+```ts
+import { auditPlugin } from '@basaltkit/audit'
+
+auditPlugin({
+  hooks: ['auth:**', 'billing:**', 'api-keys:**'], // replaces the defaults
+})
+```
+
+Enrichment comes from the active context: `ctx().user.id` → `actorId`, `ctx().tenant.id` → `tenantId`, `ctx().requestId` → `requestId`.
+
+### Automatic domain event capture
+
+If the container has an `EventBus` (`@basaltkit/events` registered), the plugin subscribes to `**` and records events that match the patterns. By default it records **everything**; you can narrow or disable it:
+
+```ts
+auditPlugin({ events: ['order.**', 'invoice.**'] }) // only these
+auditPlugin({ events: [] })                          // disable event capture
+```
+
+### Manual records
+
+For actions that no hook/event covers:
+
+```ts
+import { runWithContext } from '@basaltkit/core'
+
+await runWithContext({ user: { id: 'u1' }, tenant: { id: 'acme' } }, async () => {
+  const entry = await audit.record('data.export', { format: 'csv' })
+  // entry.source === 'manual', entry.actorId === 'u1', entry.tenantId === 'acme'
+})
+```
+
+`record` returns the created entry (already frozen).
+
+### Querying the trail
+
+`trail(query)` returns entries **most recent first**:
+
+```ts
+await audit.trail({ event: 'auth:**' })         // wildcard over the name
+await audit.trail({ tenantId: 'acme' })          // only for one tenant
+await audit.trail({ actorId: 'u1' })             // only for one user
+await audit.trail({ since: Date.now() - 86_400_000 }) // last 24h
+await audit.trail({ limit: 50 })                 // at most 50
+```
+
+Event patterns support segments separated by `:` (hooks) or `.` (events): `*` matches one segment, `**` matches one or more. E.g.: `auth:*` matches `auth:login`; `order.**` matches `order.created` and `order.item.added`; `**` matches everything.
+
+### Custom store (production)
+
+`MemoryAuditStore` loses everything when the process ends. In production, implement `AuditStore` over your database — the contract is append-only (no update or delete):
+
+```ts
+import type { AuditEntry, AuditQuery, AuditStore } from '@basaltkit/audit'
+import { auditPlugin } from '@basaltkit/audit'
+
+class SqlAuditStore implements AuditStore {
+  async append(entry: AuditEntry): Promise<void> {
+    // INSERT into the audit_entries table…
+  }
+  async query(query: AuditQuery): Promise<AuditEntry[]> {
+    // SELECT with filters, ORDER BY at DESC, LIMIT…
+    return []
+  }
+}
+
+auditPlugin({ store: new SqlAuditStore() })
+```
+
+## API reference
+
+### `auditPlugin(options?: AuditPluginOptions)`
+
+Registers an `Audit` (singleton, token `AUDIT`), hooks into **all** hooks (`hooks.onAny`) filtering by the patterns, and on `boot` subscribes to the `EventBus` (if present in the container) to record events.
+
+| Option | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `store` | `AuditStore` | No | `new MemoryAuditStore()` | Where entries are stored. |
+| `hooks` | `string[]` | No | `['auth:**', 'billing:**', 'tenancy:**', 'permission:**']` | Hook patterns recorded automatically (replaces the defaults). |
+| `events` | `string[]` | No | `['**']` (everything) | EventBus event patterns recorded. `[]` disables it. |
+
+### `class Audit`
+
+| Method | Signature | Description |
+|---|---|---|
+| `constructor` | `new Audit(store: AuditStore)` | Creates the facade over a store. |
+| `record` | `(event: string, payload?: unknown) => Promise<AuditEntry>` | Manual entry (`source: 'manual'`), enriched from context. Returns the entry. |
+| `trail` | `(query?: AuditQuery) => Promise<AuditEntry[]>` | Query, most recent first. |
+| `capture` | `(source: 'hook' \| 'event', event, payload) => Promise<void>` | **Advanced/internal**: used by the plugin's listeners. |
+
+### `interface AuditEntry` (all fields `readonly`)
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `string` | UUID generated at record time. |
+| `source` | `'hook' \| 'event' \| 'manual'` | Origin of the entry. |
+| `event` | `string` | Name of the hook/event/action. |
+| `payload` | `unknown` | Associated data. |
+| `actorId` | `string \| undefined` | `ctx().user.id` at record time. |
+| `tenantId` | `string \| undefined` | `ctx().tenant.id` at record time. |
+| `requestId` | `string \| undefined` | `ctx().requestId`. |
+| `at` | `number` | Timestamp (`Date.now()`, milliseconds). |
+
+### `interface AuditQuery`
+
+| Field | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `event` | `string` | No | all | Wildcard pattern over the name (e.g. `'auth:**'`). |
+| `tenantId` | `string` | No | all | Filters by tenant. |
+| `actorId` | `string` | No | all | Filters by actor. |
+| `since` | `number` | No | since forever | Only entries with `at >= since`. |
+| `limit` | `number` | No | no limit | Maximum number of results. |
+
+### `interface AuditStore`
+
+Storage contract, **append-only by contract** (no update/delete):
+
+- `append(entry: AuditEntry): Promise<void>`
+- `query(query: AuditQuery): Promise<AuditEntry[]>` — must return most recent first and apply filters/limit.
+
+### `class MemoryAuditStore`
+
+In-memory implementation of `AuditStore` (freezes each entry; filters and reverses on query). Ideal for dev and tests; does not persist.
+
+### `patternMatches(pattern: string, name: string): boolean`
+
+Wildcard matcher over `:` and `.` segments — exported for reuse. `*` = one segment; `**` = one or more; `'**'` matches everything.
+
+```ts
+import { patternMatches } from '@basaltkit/audit'
+
+patternMatches('auth:**', 'auth:login')      // true
+patternMatches('order.*', 'order.created')   // true
+patternMatches('auth:**', 'billing:paid')    // false
+```
+
+### Token
+
+- `AUDIT: Token<Audit>` — `app.container.get(AUDIT)`.
+
+## Common errors and solutions (FAQ)
+
+**Entries come back with empty `actorId`/`tenantId`.**
+There was no active context at record time. Make sure the code runs inside `runWithContext({ user, tenant }, …)` — in HTTP, this is established by the middleware.
+
+**Domain events aren't being recorded.**
+Either `eventsPlugin()` isn't registered (`auditPlugin` only subscribes to the bus if `container.has(EVENTS)`), or you passed `events: []`, or the patterns don't match the event names.
+
+**One of my hooks doesn't show up in the trail.**
+The defaults only cover `auth/billing/tenancy/permission`. Pass `hooks: [...]` with your own patterns — note that the list **replaces** the defaults, so include the ones you want to keep too.
+
+**I lost the history after restarting.**
+`MemoryAuditStore` is volatile. In production, implement `AuditStore` over a database.
+
+**Can I edit or delete an entry?**
+No — the contract is append-only and entries are frozen. This is a feature, not a limitation: it's what gives the trail evidentiary value.
+
+**What's the difference between `:` and `.` in names?**
+Convention: lifecycle hooks use `:` (`auth:login`); domain events use `.` (`order.created`). `patternMatches` treats both as segment separators.
+
+## How it connects to other modules
+
+- **`@basaltkit/core`** — lifecycle hooks (`hooks.onAny`) are the primary capture source; the ALS context (`tryCtx`) supplies actor/tenant/requestId; the plugin uses `definePlugin`/`createToken`.
+- **`@basaltkit/events`** — secondary capture source: any domain event emitted on the `EventBus` can land in the trail (`events` patterns).
+- **`@basaltkit/activity`** — sibling module with a different focus: **activity** is the "human-friendly" feed shown to the user ("Maria published the project"); **audit** is the automatic, immutable security/compliance record.
+- **`@basaltkit/logger`** — logs are ephemeral technical diagnostics; audit is durable business record. Use both.
+- **`@basaltkit/queue`** — since context travels to workers, entries recorded inside a job retain the actor/tenant of the original request.

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+import * as _basaltkit_core from '@basaltkit/core';
+
+/** One immutable line of the trail. */
+interface AuditEntry {
+    readonly id: string;
+    /** Where it came from: a lifecycle hook, a domain event or a manual record. */
+    readonly source: 'hook' | 'event' | 'manual';
+    readonly event: string;
+    readonly payload: unknown;
+    /** Enriched from the ALS context at record time. */
+    readonly actorId?: string | undefined;
+    readonly tenantId?: string | undefined;
+    readonly requestId?: string | undefined;
+    readonly at: number;
+}
+interface AuditQuery {
+    /** Wildcard pattern over the event name (e.g. 'auth:**'). */
+    event?: string;
+    tenantId?: string;
+    actorId?: string;
+    since?: number;
+    limit?: number;
+}
+/** Append-only by contract: no update, no delete. */
+interface AuditStore {
+    append(entry: AuditEntry): Promise<void>;
+    query(query: AuditQuery): Promise<AuditEntry[]>;
+}
+declare class MemoryAuditStore implements AuditStore {
+    private readonly entries;
+    append(entry: AuditEntry): Promise<void>;
+    query(query: AuditQuery): Promise<AuditEntry[]>;
+}
+/**
+ * Wildcard matcher over ':' and '.' segments: 'auth:**' matches 'auth:login',
+ * 'order.*' matches 'order.created', '**' matches everything.
+ */
+declare function patternMatches(pattern: string, name: string): boolean;
+declare class Audit {
+    private readonly store;
+    constructor(store: AuditStore);
+    /** Manual entry — for actions no hook covers. */
+    record(event: string, payload?: unknown): Promise<AuditEntry>;
+    /** @internal used by the plugin's hook/event taps. */
+    capture(source: 'hook' | 'event', event: string, payload: unknown): Promise<void>;
+    trail(query?: AuditQuery): Promise<AuditEntry[]>;
+    private build;
+}
+declare const AUDIT: _basaltkit_core.Token<Audit>;
+interface AuditPluginOptions {
+    store?: AuditStore;
+    /**
+     * Lifecycle hook patterns to record automatically.
+     * Default: auth, billing, tenancy and permission activity.
+     */
+    hooks?: string[];
+    /**
+     * Domain event patterns recorded from the EventBus (when present).
+     * Default: everything. Pass [] to disable.
+     */
+    events?: string[];
+}
+declare function auditPlugin(options?: AuditPluginOptions): _basaltkit_core.BasaltPlugin<unknown>;
+
+export { AUDIT, Audit, type AuditEntry, type AuditPluginOptions, type AuditQuery, type AuditStore, MemoryAuditStore, auditPlugin, patternMatches };

package/dist/index.js

@@ -0,0 +1,95 @@
+// src/index.ts
+import { randomUUID } from "crypto";
+import { createToken, definePlugin, tryCtx } from "@basaltkit/core";
+import { EVENTS } from "@basaltkit/events";
+var MemoryAuditStore = class {
+  entries = [];
+  async append(entry) {
+    this.entries.push(Object.freeze({ ...entry }));
+  }
+  async query(query) {
+    let results = this.entries.filter(
+      (entry) => (query.event === void 0 || patternMatches(query.event, entry.event)) && (query.tenantId === void 0 || entry.tenantId === query.tenantId) && (query.actorId === void 0 || entry.actorId === query.actorId) && (query.since === void 0 || entry.at >= query.since)
+    );
+    results = [...results].reverse();
+    return query.limit !== void 0 ? results.slice(0, query.limit) : results;
+  }
+};
+function patternMatches(pattern, name) {
+  if (pattern === name || pattern === "**") return true;
+  const split = (value) => value.split(/[.:]/);
+  const patternSegments = split(pattern);
+  const nameSegments = split(name);
+  for (let i = 0; i < patternSegments.length; i++) {
+    const segment = patternSegments[i];
+    if (segment === "**") return i < nameSegments.length;
+    if (i >= nameSegments.length) return false;
+    if (segment !== "*" && segment !== nameSegments[i]) return false;
+  }
+  return patternSegments.length === nameSegments.length;
+}
+var Audit = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  /** Manual entry — for actions no hook covers. */
+  async record(event, payload) {
+    const entry = this.build("manual", event, payload);
+    await this.store.append(entry);
+    return entry;
+  }
+  /** @internal used by the plugin's hook/event taps. */
+  async capture(source, event, payload) {
+    await this.store.append(this.build(source, event, payload));
+  }
+  async trail(query = {}) {
+    return this.store.query(query);
+  }
+  build(source, event, payload) {
+    const context = tryCtx();
+    const user = context?.["user"];
+    const tenant = context?.["tenant"];
+    return Object.freeze({
+      id: randomUUID(),
+      source,
+      event,
+      payload,
+      actorId: user?.id,
+      tenantId: tenant?.id,
+      requestId: context?.requestId,
+      at: Date.now()
+    });
+  }
+};
+var AUDIT = createToken("audit");
+var DEFAULT_HOOK_PATTERNS = ["auth:**", "billing:**", "tenancy:**", "permission:**"];
+function auditPlugin(options = {}) {
+  const hookPatterns = options.hooks ?? DEFAULT_HOOK_PATTERNS;
+  const eventPatterns = options.events ?? ["**"];
+  return definePlugin({
+    name: "basalt:audit",
+    register({ container, hooks }) {
+      container.singleton(AUDIT, () => new Audit(options.store ?? new MemoryAuditStore()));
+      hooks.onAny(async (hook, payload) => {
+        if (!hookPatterns.some((pattern) => patternMatches(pattern, hook))) return;
+        await container.get(AUDIT).capture("hook", hook, payload);
+      });
+    },
+    boot({ container }) {
+      if (eventPatterns.length === 0 || !container.has(EVENTS)) return;
+      const bus = container.get(EVENTS);
+      bus.on("**", async (payload, meta) => {
+        if (!eventPatterns.some((pattern) => patternMatches(pattern, meta.name))) return;
+        await container.get(AUDIT).capture("event", meta.name, payload);
+      });
+    }
+  });
+}
+export {
+  AUDIT,
+  Audit,
+  MemoryAuditStore,
+  auditPlugin,
+  patternMatches
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@basaltkit/audit",
+  "version": "1.0.0",
+  "description": "Append-only audit trail for Basalt: automatically records lifecycle hooks and domain events, enriched with actor/tenant/request from the context.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@basaltkit/core": "^1.0.0",
+    "@basaltkit/events": "^1.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/tsconfig": "^0.24.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "directory": "packages/audit"
+  },
+  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/audit#readme",
+  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "keywords": [
+    "basalt",
+    "typescript",
+    "saas",
+    "audit",
+    "audit-log"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}