@basaltkit/audit 1.0.0 → 1.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Machize Contributors
+Copyright (c) 2026 Basalt 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

package/dist/index.d.ts

@@ -36,14 +36,69 @@ declare class MemoryAuditStore implements AuditStore {
  * 'order.*' matches 'order.created', '**' matches everything.
  */
 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;
+/** Default payload scrubber: masks common secret keys, ignoring the event name. */
+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.
+ */
+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.
+ */
+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.
+ */
+declare const piiMinimizingRedactor: AuditRedactor;
 declare class Audit {
     private readonly store;
-    constructor(store: AuditStore);
+    /** Scrubs each payload before it is stored. Default masks common secret keys. */
+    private readonly redact;
+    constructor(store: AuditStore, 
+    /** Scrubs each payload before it is stored. Default masks common secret keys. */
+    redact?: AuditRedactor);
     /** 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>;
+    /**
+     * 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>;
@@ -59,7 +114,13 @@ interface AuditPluginOptions {
      * Default: everything. Pass [] to disable.
      */
     events?: string[];
+    /**
+     * Scrubs each payload before it is stored. Defaults to masking common secret
+     * keys (password, token, secret, authorization, api-key, …). Pass a custom
+     * function to change the policy, or `(p) => p` to store payloads verbatim.
+     */
+    redact?: AuditRedactor;
 }
 declare function auditPlugin(options?: AuditPluginOptions): _basaltkit_core.BasaltPlugin<unknown>;
 
-export { AUDIT, Audit, type AuditEntry, type AuditPluginOptions, type AuditQuery, type AuditStore, MemoryAuditStore, auditPlugin, patternMatches };
+export { AUDIT, Audit, type AuditEntry, type AuditPluginOptions, type AuditQuery, type AuditRedactor, type AuditStore, MemoryAuditStore, auditPlugin, defaultAuditRedactor, patternMatches, piiMinimizingRedactor, pseudonymize, redactSensitive, redactSensitiveAndPii };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-import { randomUUID } from "crypto";
+import { createHash, randomUUID } from "crypto";
 import { createToken, definePlugin, tryCtx } from "@basaltkit/core";
 import { EVENTS } from "@basaltkit/events";
 var MemoryAuditStore = class {
@@ -28,11 +28,43 @@ function patternMatches(pattern, name) {
   }
   return patternSegments.length === nameSegments.length;
 }
+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;
+}
+var defaultAuditRedactor = (payload) => redactSensitive(payload);
+var PII_KEY = /e[-_]?mail|phone|msisdn|ssn|nif|taxid|passport/i;
+var EMAIL_VALUE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function pseudonymize(value) {
+  return `pii_${createHash("sha256").update(value).digest("hex").slice(0, 16)}`;
+}
+function redactSensitiveAndPii(value, depth = 0) {
+  if (depth > 6 || value === null) return value;
+  if (typeof value === "string") return 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;
+}
+var piiMinimizingRedactor = (payload) => redactSensitiveAndPii(payload);
 var Audit = class {
-  constructor(store) {
+  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);
@@ -43,7 +75,42 @@ var Audit = class {
   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 !== void 0) {
+      return this.store.query({ ...query, tenantId: ctxTenantId });
+    }
+    if (query.tenantId !== void 0) {
+      return this.store.query(query);
+    }
+    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) {
@@ -54,7 +121,7 @@ var Audit = class {
       id: randomUUID(),
       source,
       event,
-      payload,
+      payload: this.redact(payload, event),
       actorId: user?.id,
       tenantId: tenant?.id,
       requestId: context?.requestId,
@@ -70,7 +137,7 @@ function auditPlugin(options = {}) {
   return definePlugin({
     name: "basalt:audit",
     register({ container, hooks }) {
-      container.singleton(AUDIT, () => new Audit(options.store ?? new MemoryAuditStore()));
+      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);
@@ -91,5 +158,10 @@ export {
   Audit,
   MemoryAuditStore,
   auditPlugin,
-  patternMatches
+  defaultAuditRedactor,
+  patternMatches,
+  piiMinimizingRedactor,
+  pseudonymize,
+  redactSensitive,
+  redactSensitiveAndPii
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/audit",
-  "version": "1.0.0",
+  "version": "1.2.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",