@basaltkit/audit 1.3.0 → 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)

package/dist/index.d.ts

@@ -77,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 = [];
@@ -132,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) {
@@ -149,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;
@@ -173,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().');
     }
@@ -215,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,6 +1,6 @@
 {
   "name": "@basaltkit/audit",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "engines": {
     "node": ">=22.5.0"
   },