@basaltkit/audit 1.2.1 → 1.3.0

package/README.md

@@ -1,3 +1,9 @@
+<p align="center">
+  <a href="https://basaltkit-docs.pages.dev">
+    <img src="https://basaltkit-docs.pages.dev/social-card.png" alt="Basalt" width="440">
+  </a>
+</p>
+
 # @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.
@@ -176,7 +182,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`
 
@@ -185,10 +191,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.
@@ -219,6 +236,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;

package/dist/index.js

@@ -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 = {};

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@basaltkit/audit",
-  "version": "1.2.1",
+  "version": "1.3.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/core": "^1.1.1",
-    "@basaltkit/events": "^1.0.0"
+    "@basaltkit/core": "^1.3.1",
+    "@basaltkit/events": "^1.1.1"
   },
   "devDependencies": {
     "@types/node": "^26.3.0",