@basaltkit/audit 1.2.2 → 1.4.0

package/README.md

@@ -117,6 +117,35 @@ await audit.trail({ since: Date.now() - 86_400_000 }) // last 24h
 await audit.trail({ limit: 50 })                 // at most 50
 ```
 
+#### `trail()` vs `systemTrail()` — how the tenant scope is decided
+
+`@basaltkit/audit` is a **general-purpose** package: it works with or without
+`@basaltkit/tenancy`, and `trail()` is always the everyday read. What it does
+when it can't resolve a tenant depends on whether the app is multi-tenant at all
+— detected through tenancy's `tenancy:active` metadata marker, not an import.
+
+| Situation | `trail()` |
+|---|---|
+| Tenant in `ctx()` | **Forced** to that tenant. A caller-supplied `tenantId` is overridden, so forwarding client input can never widen the scope. |
+| No context tenant, explicit `trail({ tenantId })` | Honoured — a system job or CLI pinning one tenant deliberately. |
+| No context tenant, no `tenantId`, **no `tenancyPlugin`** | Returns the trail. A single-tenant app has no tenant dimension, so there is nothing to cross. |
+| No context tenant, no `tenantId`, **`tenancyPlugin` registered** | **Throws.** Returning every tenant's records must be deliberate — use `systemTrail()`. |
+
+`systemTrail(query)` is the **system-only** escape hatch: it reads across all
+tenants, bypassing the auto-scoping above. Use it from trusted platform/admin
+tooling only, and never pass client-controlled input into it — that re-opens
+exactly the cross-tenant exposure `trail()` closes.
+
+```ts
+// Single-tenant app (no tenancyPlugin): this is the normal read.
+await audit.trail()
+
+// Multi-tenant app: scoped automatically inside a request…
+await audit.trail()                    // → only ctx().tenant's entries
+// …and a platform-wide read is spelled out.
+await audit.systemTrail({ event: 'billing:**' })
+```
+
 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)
@@ -182,7 +211,7 @@ Registers an `Audit` (singleton, token `AUDIT`), hooks into **all** hooks (`hook
 | `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. |
+| `limit` | `number` | No | no limit | Maximum number of results. The SQL-backed stores push it into the database, so a limited query never loads the whole trail. |
 
 ### `interface AuditStore`
 
@@ -191,10 +220,21 @@ 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.
 
+Two helpers exist so a driver can push the limit down safely:
+
+- `exactEventMatch(pattern?: string): string | undefined` — the event filter that may be pushed into SQL as an equality. Returns `undefined` for a pattern containing `*` (a wildcard) **or** `.` (because `patternMatches` treats `.` and `:` as interchangeable, so an equality would miss `a:b` for the pattern `a.b`); those must still be matched in code.
+- `AUDIT_SCAN_PAGE: number` — rows a driver should read per round-trip when a wildcard forces a scan (500). Bounds peak memory.
+
 ### `class MemoryAuditStore`
 
 In-memory implementation of `AuditStore` (freezes each entry; filters and reverses on query). Ideal for dev and tests; does not persist.
 
+### Redaction
+
+Payloads are scrubbed before they are persisted. `redactSensitive` masks values under secret-looking keys (`password`, `token`, `api_key`, `authorization`, …) as `'[redacted]'`; the opt-in `redactSensitiveAndPii` / `piiMinimizingRedactor` additionally replaces email/phone-shaped values with a stable `pii_<hash>` pseudonym.
+
+Both walk **6 levels deep**. Anything deeper is replaced with `'[truncated]'` — not passed through. Payloads are arbitrary and the default subscription is `events: ['**']`, so returning the raw subtree meant a secret nested seven levels down reached the trail in cleartext. If your payloads are deeply nested, flatten them before recording rather than relying on depth.
+
 ### `patternMatches(pattern: string, name: string): boolean`
 
 Wildcard matcher over `:` and `.` segments — exported for reuse. `*` = one segment; `**` = one or more; `'**'` matches everything.
@@ -225,6 +265,9 @@ The defaults only cover `auth/billing/tenancy/permission`. Pass `hooks: [...]` w
 **I lost the history after restarting.**
 `MemoryAuditStore` is volatile. In production, implement `AuditStore` over a database.
 
+**A deeply-nested field comes back as `'[truncated]'`.**
+The redactors stop at 6 levels and drop everything below, so a secret can never slip past the depth bound. Flatten the payload (or record the interesting fields explicitly) if you need that data in the trail.
+
 **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.
 

package/dist/index.d.ts

@@ -34,6 +34,18 @@ export declare class MemoryAuditStore implements AuditStore {
  * 'order.*' matches 'order.created', '**' matches everything.
  */
 export declare function patternMatches(pattern: string, name: string): boolean;
+/**
+ * The event filter a driver may push into SQL as an equality. A pattern with a
+ * wildcard must still be matched in code; so must one containing `.`, because
+ * {@link patternMatches} treats `.` and `:` as interchangeable separators and an
+ * equality would miss `a:b` for the pattern `a.b`.
+ */
+export declare function exactEventMatch(pattern: string | undefined): string | undefined;
+/**
+ * Rows a driver reads per round-trip when a wildcard pattern forces a scan.
+ * Bounds peak memory: a limited query no longer materialises the whole trail.
+ */
+export declare const AUDIT_SCAN_PAGE = 500;
 /** Recursively masks sensitive fields so secrets/PII never reach the trail. */
 export declare function redactSensitive(value: unknown, depth?: number): unknown;
 export type AuditRedactor = (payload: unknown, event: string) => unknown;
@@ -65,26 +77,53 @@ export declare class Audit {
     private readonly store;
     /** Scrubs each payload before it is stored. Default masks common secret keys. */
     private readonly redact;
+    /**
+     * Whether the host app is multi-tenant, i.e. whether `@basaltkit/tenancy`
+     * is registered. `auditPlugin` wires this to the container's
+     * `'tenancy:active'` metadata marker; it is a *signal*, never an import —
+     * `@basaltkit/audit` is a generic package and must not depend on tenancy.
+     *
+     * Defaults to `false`: a hand-built `new Audit(store)` behaves like a
+     * single-tenant app, which is the only thing it can safely assume.
+     */
+    private readonly tenancyActive;
     constructor(store: AuditStore, 
     /** Scrubs each payload before it is stored. Default masks common secret keys. */
-    redact?: AuditRedactor);
+    redact?: AuditRedactor, 
+    /**
+     * Whether the host app is multi-tenant, i.e. whether `@basaltkit/tenancy`
+     * is registered. `auditPlugin` wires this to the container's
+     * `'tenancy:active'` metadata marker; it is a *signal*, never an import —
+     * `@basaltkit/audit` is a generic package and must not depend on tenancy.
+     *
+     * Defaults to `false`: a hand-built `new Audit(store)` behaves like a
+     * single-tenant app, which is the only thing it can safely assume.
+     */
+    tenancyActive?: () => boolean);
     /** 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**.
+     * Reads the audit trail — the everyday read.
      *
-     * Security model (PII F2):
+     * Tenant scoping (PII F2), applied only where a tenant dimension exists:
      * - 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.
+     * - With no tenant in context, an explicit single-tenant read
+     *   (`trail({ tenantId })`) is honoured.
+     * - With no tenant in context and no explicit `tenantId`, the behavior depends
+     *   on whether the app is multi-tenant at all:
+     *   - **Tenancy registered** (`@basaltkit/tenancy` present): the read is
+     *     REFUSED. Returning every tenant's records must be a deliberate,
+     *     system-only act via {@link systemTrail}, never the silent default.
+     *   - **No tenancy** (single-tenant/non-SaaS app): there is no tenant
+     *     dimension to scope to, so this is simply "read the trail" and returns
+     *     the rows. `@basaltkit/audit` is a general-purpose package; it must work
+     *     without the opt-in SaaS layer.
      */
     trail(query?: AuditQuery): Promise<AuditEntry[]>;
     /**

package/dist/index.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { createToken, definePlugin, tryCtx } from '@basaltkit/core';
+import { createToken, definePlugin, ensureMetadata, tryCtx } from '@basaltkit/core';
 import { EVENTS } from '@basaltkit/events';
 export class MemoryAuditStore {
     entries = [];
@@ -36,12 +36,37 @@ export function patternMatches(pattern, name) {
     }
     return patternSegments.length === nameSegments.length;
 }
+/** How deep the redactors walk a payload before dropping the rest. */
+const MAX_REDACT_DEPTH = 6;
+/** Stand-in for a subtree deeper than {@link MAX_REDACT_DEPTH}. */
+const TRUNCATED = '[truncated]';
+/**
+ * The event filter a driver may push into SQL as an equality. A pattern with a
+ * wildcard must still be matched in code; so must one containing `.`, because
+ * {@link patternMatches} treats `.` and `:` as interchangeable separators and an
+ * equality would miss `a:b` for the pattern `a.b`.
+ */
+export function exactEventMatch(pattern) {
+    if (pattern === undefined)
+        return undefined;
+    return /[*.]/.test(pattern) ? undefined : pattern;
+}
+/**
+ * Rows a driver reads per round-trip when a wildcard pattern forces a scan.
+ * Bounds peak memory: a limited query no longer materialises the whole trail.
+ */
+export const AUDIT_SCAN_PAGE = 500;
 /** 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')
+    // Past the depth bound the subtree is dropped, NOT passed through: event
+    // payloads are arbitrary, and returning the raw value here let a secret nested
+    // deeper than the limit reach the trail in cleartext.
+    if (value === null || typeof value !== 'object')
         return value;
+    if (depth > MAX_REDACT_DEPTH)
+        return TRUNCATED;
     if (Array.isArray(value))
         return value.map((v) => redactSensitive(v, depth + 1));
     const out = {};
@@ -70,7 +95,7 @@ export function pseudonymize(value) {
  * entries correlatable.
  */
 export function redactSensitiveAndPii(value, depth = 0) {
-    if (depth > 6 || value === null)
+    if (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
@@ -79,6 +104,8 @@ export function redactSensitiveAndPii(value, depth = 0) {
         return value.length <= 320 && EMAIL_VALUE.test(value) ? pseudonymize(value) : value;
     if (typeof value !== 'object')
         return value;
+    if (depth > MAX_REDACT_DEPTH)
+        return TRUNCATED;
     if (Array.isArray(value))
         return value.map((v) => redactSensitiveAndPii(v, depth + 1));
     const out = {};
@@ -105,11 +132,23 @@ export const piiMinimizingRedactor = (payload) => redactSensitiveAndPii(payload)
 export class Audit {
     store;
     redact;
+    tenancyActive;
     constructor(store, 
     /** Scrubs each payload before it is stored. Default masks common secret keys. */
-    redact = defaultAuditRedactor) {
+    redact = defaultAuditRedactor, 
+    /**
+     * Whether the host app is multi-tenant, i.e. whether `@basaltkit/tenancy`
+     * is registered. `auditPlugin` wires this to the container's
+     * `'tenancy:active'` metadata marker; it is a *signal*, never an import —
+     * `@basaltkit/audit` is a generic package and must not depend on tenancy.
+     *
+     * Defaults to `false`: a hand-built `new Audit(store)` behaves like a
+     * single-tenant app, which is the only thing it can safely assume.
+     */
+    tenancyActive = () => false) {
         this.store = store;
         this.redact = redact;
+        this.tenancyActive = tenancyActive;
     }
     /** Manual entry — for actions no hook covers. */
     async record(event, payload) {
@@ -122,18 +161,25 @@ export class Audit {
         await this.store.append(this.build(source, event, payload));
     }
     /**
-     * Reads the audit trail, **always scoped to the current tenant**.
+     * Reads the audit trail — the everyday read.
      *
-     * Security model (PII F2):
+     * Tenant scoping (PII F2), applied only where a tenant dimension exists:
      * - 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.
+     * - With no tenant in context, an explicit single-tenant read
+     *   (`trail({ tenantId })`) is honoured.
+     * - With no tenant in context and no explicit `tenantId`, the behavior depends
+     *   on whether the app is multi-tenant at all:
+     *   - **Tenancy registered** (`@basaltkit/tenancy` present): the read is
+     *     REFUSED. Returning every tenant's records must be a deliberate,
+     *     system-only act via {@link systemTrail}, never the silent default.
+     *   - **No tenancy** (single-tenant/non-SaaS app): there is no tenant
+     *     dimension to scope to, so this is simply "read the trail" and returns
+     *     the rows. `@basaltkit/audit` is a general-purpose package; it must work
+     *     without the opt-in SaaS layer.
      */
     async trail(query = {}) {
         const ctxTenantId = tryCtx()?.['tenant']?.id;
@@ -146,9 +192,14 @@ export class Audit {
             // 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.
+        if (!this.tenancyActive()) {
+            // Single-tenant app: no tenant dimension, so an unscoped read is correct
+            // and is the everyday call. Nothing to widen — every entry is "ours".
+            return this.store.query(query);
+        }
+        // Multi-tenant app with 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 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().');
     }
@@ -188,7 +239,14 @@ export function auditPlugin(options = {}) {
     return definePlugin({
         name: 'basalt:audit',
         register({ container, hooks }) {
-            container.singleton(AUDIT, () => new Audit(options.store ?? new MemoryAuditStore(), options.redact ?? defaultAuditRedactor));
+            // The 'tenancy:active' marker is set by tenancyPlugin. Reading it here
+            // (a string-keyed metadata bucket, not an import) is how a generic
+            // package learns the app is multi-tenant without depending on
+            // @basaltkit/tenancy — the same signal @basaltkit/cache uses. It is
+            // resolved per call, so plugin registration order does not matter.
+            const metadata = ensureMetadata(container);
+            const tenancyActive = () => metadata.get('tenancy:active').length > 0;
+            container.singleton(AUDIT, () => new Audit(options.store ?? new MemoryAuditStore(), options.redact ?? defaultAuditRedactor, tenancyActive));
             hooks.onAny(async (hook, payload) => {
                 if (!hookPatterns.some((pattern) => patternMatches(pattern, hook)))
                     return;

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@basaltkit/audit",
-  "version": "1.2.2",
+  "version": "1.4.0",
+  "engines": {
+    "node": ">=22.5.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",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -14,8 +18,8 @@
     "dist"
   ],
   "dependencies": {
-    "@basaltkit/events": "^1.0.1",
-    "@basaltkit/core": "^1.1.2"
+    "@basaltkit/core": "^1.3.1",
+    "@basaltkit/events": "^1.1.1"
   },
   "devDependencies": {
     "@types/node": "^26.3.0",