@basaltkit/audit 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -41,6 +41,28 @@ 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;
     /** Scrubs each payload before it is stored. Default masks common secret keys. */
@@ -52,7 +74,31 @@ 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>;
@@ -77,4 +123,4 @@ interface AuditPluginOptions {
 }
 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 { 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 {
@@ -39,6 +39,25 @@ function redactSensitive(value, depth = 0) {
   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, redact = defaultAuditRedactor) {
     this.store = store;
@@ -56,9 +75,43 @@ 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 tenantId = query.tenantId ?? tryCtx()?.["tenant"]?.id;
-    return this.store.query(tenantId !== void 0 ? { ...query, tenantId } : 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) {
     const context = tryCtx();
@@ -107,5 +160,8 @@ export {
   auditPlugin,
   defaultAuditRedactor,
   patternMatches,
-  redactSensitive
+  piiMinimizingRedactor,
+  pseudonymize,
+  redactSensitive,
+  redactSensitiveAndPii
 };

package/package.json

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