@basaltkit/audit 1.1.0 → 1.2.1

package/dist/index.d.ts

@@ -1,7 +1,5 @@
-import * as _basaltkit_core from '@basaltkit/core';
-
 /** One immutable line of the trail. */
-interface AuditEntry {
+export interface AuditEntry {
     readonly id: string;
     /** Where it came from: a lifecycle hook, a domain event or a manual record. */
     readonly source: 'hook' | 'event' | 'manual';
@@ -13,7 +11,7 @@ interface AuditEntry {
     readonly requestId?: string | undefined;
     readonly at: number;
 }
-interface AuditQuery {
+export interface AuditQuery {
     /** Wildcard pattern over the event name (e.g. 'auth:**'). */
     event?: string;
     tenantId?: string;
@@ -22,11 +20,11 @@ interface AuditQuery {
     limit?: number;
 }
 /** Append-only by contract: no update, no delete. */
-interface AuditStore {
+export interface AuditStore {
     append(entry: AuditEntry): Promise<void>;
     query(query: AuditQuery): Promise<AuditEntry[]>;
 }
-declare class MemoryAuditStore implements AuditStore {
+export declare class MemoryAuditStore implements AuditStore {
     private readonly entries;
     append(entry: AuditEntry): Promise<void>;
     query(query: AuditQuery): Promise<AuditEntry[]>;
@@ -35,13 +33,35 @@ declare class MemoryAuditStore implements AuditStore {
  * Wildcard matcher over ':' and '.' segments: 'auth:**' matches 'auth:login',
  * 'order.*' matches 'order.created', '**' matches everything.
  */
-declare function patternMatches(pattern: string, name: string): boolean;
+export declare function patternMatches(pattern: string, name: string): boolean;
 /** Recursively masks sensitive fields so secrets/PII never reach the trail. */
-declare function redactSensitive(value: unknown, depth?: number): unknown;
-type AuditRedactor = (payload: unknown, event: string) => unknown;
+export declare function redactSensitive(value: unknown, depth?: number): unknown;
+export type AuditRedactor = (payload: unknown, event: string) => unknown;
 /** Default payload scrubber: masks common secret keys, ignoring the event name. */
-declare const defaultAuditRedactor: AuditRedactor;
-declare class Audit {
+export declare const defaultAuditRedactor: AuditRedactor;
+/**
+ * Deterministically pseudonymizes a value: the same input always maps to the
+ * same opaque token, so records stay correlatable without persisting the raw PII.
+ */
+export declare function pseudonymize(value: string): string;
+/**
+ * Recursively masks secrets (like {@link redactSensitive}) AND replaces obvious
+ * PII — email/phone-shaped values, and values under common PII keys — with a
+ * stable pseudonym. Use it to minimize PII at rest in the trail while keeping
+ * entries correlatable.
+ */
+export declare function redactSensitiveAndPii(value: unknown, depth?: number): unknown;
+/**
+ * Payload scrubber that also pseudonymizes obvious PII (PII F3). Opt-in — pass it
+ * to `auditPlugin({ redact: piiMinimizingRedactor })` or `new Audit(store, piiMinimizingRedactor)`.
+ *
+ * TODO(PII F3 follow-up): the default capture set still persists whatever the
+ * emitting code puts in the payload. A fuller minimization pass would let callers
+ * declare per-event field policies; kept out of the default here to avoid changing
+ * existing capture/redaction behavior.
+ */
+export declare const piiMinimizingRedactor: AuditRedactor;
+export declare class Audit {
     private readonly store;
     /** Scrubs each payload before it is stored. Default masks common secret keys. */
     private readonly redact;
@@ -52,11 +72,35 @@ declare class Audit {
     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>;
+    /**
+     * Reads the audit trail, **always scoped to the current tenant**.
+     *
+     * Security model (PII F2):
+     * - When a tenant is present in the ambient context, the read is FORCED to
+     *   that tenant. Any caller-supplied `query.tenantId` is ignored/overridden
+     *   (the context tenant is spread LAST so it always wins), so a tenant-facing
+     *   handler that forwards client input — e.g. `trail({ tenantId: req.query.tenantId })`
+     *   — can never widen the scope and read another tenant's trail.
+     * - When there is NO tenant in context, an explicit single-tenant read
+     *   (`trail({ tenantId })`) is honoured, but a broad/unscoped read is refused:
+     *   returning every tenant's records must be a deliberate, system-only act via
+     *   {@link systemTrail}, never the silent default.
+     */
     trail(query?: AuditQuery): Promise<AuditEntry[]>;
+    /**
+     * SYSTEM-ONLY escape hatch: reads across ALL tenants (or whatever
+     * `query.tenantId` explicitly pins), bypassing the tenant auto-scoping that
+     * {@link trail} enforces.
+     *
+     * This exists for trusted platform/admin tooling only. NEVER call it with, or
+     * forward into it, client-controlled input — doing so re-opens the
+     * cross-tenant data-exposure that {@link trail} closes.
+     */
+    systemTrail(query?: AuditQuery): Promise<AuditEntry[]>;
     private build;
 }
-declare const AUDIT: _basaltkit_core.Token<Audit>;
-interface AuditPluginOptions {
+export declare const AUDIT: import("@basaltkit/core").Token<Audit>;
+export interface AuditPluginOptions {
     store?: AuditStore;
     /**
      * Lifecycle hook patterns to record automatically.
@@ -75,6 +119,4 @@ interface AuditPluginOptions {
      */
     redact?: AuditRedactor;
 }
-declare function auditPlugin(options?: AuditPluginOptions): _basaltkit_core.BasaltPlugin<unknown>;
-
-export { AUDIT, Audit, type AuditEntry, type AuditPluginOptions, type AuditQuery, type AuditRedactor, type AuditStore, MemoryAuditStore, auditPlugin, defaultAuditRedactor, patternMatches, redactSensitive };
+export declare function auditPlugin(options?: AuditPluginOptions): import("@basaltkit/core").BasaltPlugin<unknown>;

package/dist/index.js

@@ -1,111 +1,209 @@
-// 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;
+import { createHash, randomUUID } from 'node:crypto';
+import { createToken, definePlugin, tryCtx } from '@basaltkit/core';
+import { EVENTS } from '@basaltkit/events';
+export class MemoryAuditStore {
+    entries = [];
+    async append(entry) {
+        this.entries.push(Object.freeze({ ...entry }));
+    }
+    async query(query) {
+        let results = this.entries.filter((entry) => (query.event === undefined || patternMatches(query.event, entry.event)) &&
+            (query.tenantId === undefined || entry.tenantId === query.tenantId) &&
+            (query.actorId === undefined || entry.actorId === query.actorId) &&
+            (query.since === undefined || entry.at >= query.since));
+        results = [...results].reverse(); // newest first
+        return query.limit !== undefined ? results.slice(0, query.limit) : results;
+    }
 }
-var SENSITIVE_KEY = /pass(word|wd)?|secret|token|authorization|api[-_]?key|credential|cookie|session|otp|mfa/i;
-function redactSensitive(value, depth = 0) {
-  if (depth > 6 || value === null || typeof value !== "object") return value;
-  if (Array.isArray(value)) return value.map((v) => redactSensitive(v, depth + 1));
-  const out = {};
-  for (const [k, v] of Object.entries(value)) {
-    out[k] = SENSITIVE_KEY.test(k) ? "[redacted]" : redactSensitive(v, depth + 1);
-  }
-  return out;
+/**
+ * Wildcard matcher over ':' and '.' segments: 'auth:**' matches 'auth:login',
+ * 'order.*' matches 'order.created', '**' matches everything.
+ */
+export 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 defaultAuditRedactor = (payload) => redactSensitive(payload);
-var Audit = class {
-  constructor(store, redact = defaultAuditRedactor) {
-    this.store = store;
-    this.redact = redact;
-  }
-  store;
-  redact;
-  /** 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 = {}) {
-    const tenantId = query.tenantId ?? tryCtx()?.["tenant"]?.id;
-    return this.store.query(tenantId !== void 0 ? { ...query, tenantId } : query);
-  }
-  build(source, event, payload) {
-    const context = tryCtx();
-    const user = context?.["user"];
-    const tenant = context?.["tenant"];
-    return Object.freeze({
-      id: randomUUID(),
-      source,
-      event,
-      payload: this.redact(payload, event),
-      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(), options.redact ?? defaultAuditRedactor));
-      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);
-      });
+/** Object keys whose values are masked before an entry is persisted. */
+const SENSITIVE_KEY = /pass(word|wd)?|secret|token|authorization|api[-_]?key|credential|cookie|session|otp|mfa/i;
+/** Recursively masks sensitive fields so secrets/PII never reach the trail. */
+export function redactSensitive(value, depth = 0) {
+    if (depth > 6 || value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map((v) => redactSensitive(v, depth + 1));
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = SENSITIVE_KEY.test(k) ? '[redacted]' : redactSensitive(v, depth + 1);
+    }
+    return out;
+}
+/** Default payload scrubber: masks common secret keys, ignoring the event name. */
+export const defaultAuditRedactor = (payload) => redactSensitive(payload);
+/** Object keys that commonly carry direct PII and can be pseudonymized on request. */
+const PII_KEY = /e[-_]?mail|phone|msisdn|ssn|nif|taxid|passport/i;
+/** A value that looks like an email address. */
+const EMAIL_VALUE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/**
+ * Deterministically pseudonymizes a value: the same input always maps to the
+ * same opaque token, so records stay correlatable without persisting the raw PII.
+ */
+export function pseudonymize(value) {
+    return `pii_${createHash('sha256').update(value).digest('hex').slice(0, 16)}`;
+}
+/**
+ * Recursively masks secrets (like {@link redactSensitive}) AND replaces obvious
+ * PII — email/phone-shaped values, and values under common PII keys — with a
+ * stable pseudonym. Use it to minimize PII at rest in the trail while keeping
+ * entries correlatable.
+ */
+export function redactSensitiveAndPii(value, depth = 0) {
+    if (depth > 6 || value === null)
+        return value;
+    // Bound the length before the regex: a real email is <= 254 chars (RFC 5321),
+    // so only test plausibly-email-length strings — arbitrary logged values never
+    // reach the regex, avoiding ReDoS on attacker-influenceable input.
+    if (typeof value === 'string')
+        return value.length <= 320 && EMAIL_VALUE.test(value) ? pseudonymize(value) : value;
+    if (typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map((v) => redactSensitiveAndPii(v, depth + 1));
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (SENSITIVE_KEY.test(k))
+            out[k] = '[redacted]';
+        else if (PII_KEY.test(k) && typeof v === 'string')
+            out[k] = pseudonymize(v);
+        else
+            out[k] = redactSensitiveAndPii(v, depth + 1);
+    }
+    return out;
+}
+/**
+ * Payload scrubber that also pseudonymizes obvious PII (PII F3). Opt-in — pass it
+ * to `auditPlugin({ redact: piiMinimizingRedactor })` or `new Audit(store, piiMinimizingRedactor)`.
+ *
+ * TODO(PII F3 follow-up): the default capture set still persists whatever the
+ * emitting code puts in the payload. A fuller minimization pass would let callers
+ * declare per-event field policies; kept out of the default here to avoid changing
+ * existing capture/redaction behavior.
+ */
+export const piiMinimizingRedactor = (payload) => redactSensitiveAndPii(payload);
+export class Audit {
+    store;
+    redact;
+    constructor(store, 
+    /** Scrubs each payload before it is stored. Default masks common secret keys. */
+    redact = defaultAuditRedactor) {
+        this.store = store;
+        this.redact = redact;
+    }
+    /** 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));
+    }
+    /**
+     * Reads the audit trail, **always scoped to the current tenant**.
+     *
+     * Security model (PII F2):
+     * - When a tenant is present in the ambient context, the read is FORCED to
+     *   that tenant. Any caller-supplied `query.tenantId` is ignored/overridden
+     *   (the context tenant is spread LAST so it always wins), so a tenant-facing
+     *   handler that forwards client input — e.g. `trail({ tenantId: req.query.tenantId })`
+     *   — can never widen the scope and read another tenant's trail.
+     * - When there is NO tenant in context, an explicit single-tenant read
+     *   (`trail({ tenantId })`) is honoured, but a broad/unscoped read is refused:
+     *   returning every tenant's records must be a deliberate, system-only act via
+     *   {@link systemTrail}, never the silent default.
+     */
+    async trail(query = {}) {
+        const ctxTenantId = tryCtx()?.['tenant']?.id;
+        if (ctxTenantId !== undefined) {
+            // Force the scope: spread the context tenant LAST so a differing
+            // caller-supplied `tenantId` cannot override it.
+            return this.store.query({ ...query, tenantId: ctxTenantId });
+        }
+        if (query.tenantId !== undefined) {
+            // No context, but the caller explicitly pinned a single tenant.
+            return this.store.query(query);
+        }
+        // No tenant to scope to and no explicit tenant pinned: refuse to silently
+        // return every tenant's records. Cross-tenant/system reads go through
+        // systemTrail() so broad access is always deliberate.
+        throw new Error('Audit.trail() requires a tenant in context or an explicit `tenantId`. ' +
+            'For a deliberate system-wide, cross-tenant read use Audit.systemTrail().');
     }
-  });
+    /**
+     * SYSTEM-ONLY escape hatch: reads across ALL tenants (or whatever
+     * `query.tenantId` explicitly pins), bypassing the tenant auto-scoping that
+     * {@link trail} enforces.
+     *
+     * This exists for trusted platform/admin tooling only. NEVER call it with, or
+     * forward into it, client-controlled input — doing so re-opens the
+     * cross-tenant data-exposure that {@link trail} closes.
+     */
+    async systemTrail(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: this.redact(payload, event),
+            actorId: user?.id,
+            tenantId: tenant?.id,
+            requestId: context?.requestId,
+            at: Date.now(),
+        });
+    }
+}
+export const AUDIT = createToken('audit');
+const DEFAULT_HOOK_PATTERNS = ['auth:**', 'billing:**', 'tenancy:**', 'permission:**'];
+export 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(), options.redact ?? defaultAuditRedactor));
+            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,
-  defaultAuditRedactor,
-  patternMatches,
-  redactSensitive
-};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/audit",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "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",
@@ -14,15 +14,14 @@
     "dist"
   ],
   "dependencies": {
-    "@basaltkit/core": "^1.0.0",
+    "@basaltkit/core": "^1.1.1",
     "@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",
+    "@types/node": "^26.3.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11",
+    "zod": "^3.24.0 || ^4.0.0",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {
@@ -30,11 +29,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "url": "git+https://github.com/basaltkit/basalt.git",
     "directory": "packages/audit"
   },
-  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/audit#readme",
-  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "homepage": "https://github.com/basaltkit/basalt/tree/main/packages/audit#readme",
+  "bugs": "https://github.com/basaltkit/basalt/issues",
   "keywords": [
     "basalt",
     "typescript",
@@ -43,7 +42,7 @@
     "audit-log"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
+    "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }