@cqrs-ddd/pipeline-audit 0.5.0

package/dist/helpers/json.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Serialize an audit value without silently collapsing or dropping JavaScript
+ * values that native JSON.stringify cannot represent faithfully. Tagged objects
+ * keep the representation explicit and portable across log and database sinks.
+ */
+export declare function stringifyAuditValue(value: unknown, space?: number): string;
+//# sourceMappingURL=json.d.ts.map

package/dist/helpers/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/helpers/json.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1E"}

package/dist/helpers/json.js

@@ -0,0 +1,102 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * Serialize an audit value without silently collapsing or dropping JavaScript
+ * values that native JSON.stringify cannot represent faithfully. Tagged objects
+ * keep the representation explicit and portable across log and database sinks.
+ */
+export function stringifyAuditValue(value, space) {
+    return JSON.stringify(normalizeAuditValue(value, new WeakSet()), null, space);
+}
+function normalizeAuditValue(value, ancestors) {
+    if (typeof value === 'bigint') {
+        return { $type: 'BigInt', value: value.toString() };
+    }
+    if (typeof value === 'number' && !Number.isFinite(value)) {
+        return { $type: 'Number', value: String(value) };
+    }
+    if (typeof value === 'function') {
+        return { $type: 'Function', name: value.name || null };
+    }
+    if (typeof value === 'symbol') {
+        return { $type: 'Symbol', description: value.description ?? null };
+    }
+    if (value === undefined)
+        return { $type: 'Undefined' };
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (ancestors.has(value))
+        return '[Circular]';
+    if (value instanceof Date)
+        return value.toISOString();
+    if (value instanceof RegExp) {
+        return {
+            $type: 'RegExp',
+            source: value.source,
+            flags: value.flags,
+            lastIndex: value.lastIndex,
+        };
+    }
+    ancestors.add(value);
+    try {
+        if (value instanceof Error) {
+            const symbolProperties = normalizeSymbolProperties(value, ancestors);
+            return {
+                $type: 'Error',
+                name: value.name,
+                message: value.message,
+                stack: value.stack,
+                properties: normalizeAuditValue(Object.fromEntries(Object.entries(value)), ancestors),
+                ...(symbolProperties.length > 0 ? { symbolProperties } : {}),
+            };
+        }
+        if (value instanceof Map) {
+            return {
+                $type: 'Map',
+                entries: Array.from(value, ([key, item]) => [
+                    normalizeAuditValue(key, ancestors),
+                    normalizeAuditValue(item, ancestors),
+                ]),
+            };
+        }
+        if (value instanceof Set) {
+            return {
+                $type: 'Set',
+                values: Array.from(value, (item) => normalizeAuditValue(item, ancestors)),
+            };
+        }
+        if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
+            const bytes = value instanceof ArrayBuffer
+                ? new Uint8Array(value)
+                : new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+            return {
+                $type: value.constructor.name,
+                bytes: Array.from(bytes),
+            };
+        }
+        if (Array.isArray(value)) {
+            return Array.from({ length: value.length }, (_, index) => index in value
+                ? normalizeAuditValue(value[index], ancestors)
+                : { $type: 'ArrayHole' });
+        }
+        const properties = Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            normalizeAuditValue(item, ancestors),
+        ]));
+        const symbolProperties = normalizeSymbolProperties(value, ancestors);
+        return symbolProperties.length > 0
+            ? { $type: 'Object', properties, symbolProperties }
+            : properties;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function normalizeSymbolProperties(value, ancestors) {
+    return Object.getOwnPropertySymbols(value)
+        .filter((key) => Object.getOwnPropertyDescriptor(value, key)?.enumerable === true)
+        .map((key) => [
+        normalizeAuditValue(key, ancestors),
+        normalizeAuditValue(Reflect.get(value, key), ancestors),
+    ]);
+}
+//# sourceMappingURL=json.js.map

package/dist/helpers/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/helpers/json.ts"],"names":[],"mappings":"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"}

package/dist/helpers/redact.d.ts

@@ -0,0 +1,2 @@
+export { DEFAULT_REDACT_KEYS, REDACTED, redactValue, } from '@cqrs-ddd/safe-stringify';
+//# sourceMappingURL=redact.d.ts.map

package/dist/helpers/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../src/helpers/redact.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,mBAAmB,EACnB,QAAQ,EACR,WAAW,GACZ,MAAM,0BAA0B,CAAC"}

package/dist/helpers/redact.js

@@ -0,0 +1,3 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+export { DEFAULT_REDACT_KEYS, REDACTED, redactValue, } from '@cqrs-ddd/safe-stringify';
+//# sourceMappingURL=redact.js.map

package/dist/helpers/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../../src/helpers/redact.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EACL,mBAAmB,EACnB,QAAQ,EACR,WAAW,GACZ,MAAM,0BAA0B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { AUDIT_RECORD_ITEM, AUDIT_RECORD_ITEM_TOKEN, AUDIT_START_RECORD_ITEM_TOKEN, AuditBehavior, } from './audit.behavior.js';
+export { AUDIT_OUTCOMES, AUDIT_REQUEST_KINDS, AUDIT_SEVERITY, } from './constants/tokens.js';
+export { type AuditIntentOptions, audit, } from './helpers/audit.intent.js';
+export type { BuildAuditRecordInput, BuildAuditStartRecordInput, } from './helpers/build-record.js';
+export { buildAuditRecord, buildAuditStartRecord, } from './helpers/build-record.js';
+export { DEFAULT_REDACT_KEYS, REDACTED, redactValue, } from './helpers/redact.js';
+export type { AuditActorFactory, AuditBehaviorOptions, AuditMetadataFactory, AuditRedactor, } from './interfaces/audit-options.interface.js';
+export type { AuditActor, AuditError, AuditOutcome, AuditRecord, AuditRequestKind, AuditSeverity, AuditStartRecord, } from './interfaces/audit-record.interface.js';
+export type { AuditSink } from './interfaces/audit-sink.interface.js';
+export { type AuditLoggerLike, LogAuditSink, type LogAuditSinkOptions, } from './sinks/log.sink.js';
+export { createAuditTableSql, PostgresAuditSink, type PostgresAuditSinkOptions, type PostgresQueryableLike, } from './sinks/postgres.sink.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,6BAA6B,EAC7B,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,GACN,MAAM,2BAA2B,CAAC;AACnC,YAAY,EACV,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,mBAAmB,EACnB,QAAQ,EACR,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,GACd,MAAM,yCAAyC,CAAC;AACjD,YAAY,EACV,UAAU,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,gBAAgB,GACjB,MAAM,wCAAwC,CAAC;AAChD,YAAY,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AACtE,OAAO,EACL,KAAK,eAAe,EACpB,YAAY,EACZ,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,GAC3B,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+export { AUDIT_RECORD_ITEM, AUDIT_RECORD_ITEM_TOKEN, AUDIT_START_RECORD_ITEM_TOKEN, AuditBehavior, } from './audit.behavior.js';
+export { AUDIT_OUTCOMES, AUDIT_REQUEST_KINDS, AUDIT_SEVERITY, } from './constants/tokens.js';
+export { audit, } from './helpers/audit.intent.js';
+export { buildAuditRecord, buildAuditStartRecord, } from './helpers/build-record.js';
+export { DEFAULT_REDACT_KEYS, REDACTED, redactValue, } from './helpers/redact.js';
+export { LogAuditSink, } from './sinks/log.sink.js';
+export { createAuditTableSql, PostgresAuditSink, } from './sinks/postgres.sink.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,6BAA6B,EAC7B,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,KAAK,GACN,MAAM,2BAA2B,CAAC;AAKnC,OAAO,EACL,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,mBAAmB,EACnB,QAAQ,EACR,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAiB7B,OAAO,EAEL,YAAY,GAEb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,mBAAmB,EACnB,iBAAiB,GAGlB,MAAM,0BAA0B,CAAC"}

package/dist/interfaces/audit-options.interface.d.ts

@@ -0,0 +1,95 @@
+import type { IPipelineContext } from '@cqrs-ddd/pipeline';
+import type { AuditActor, AuditRequestKind, AuditSeverity } from './audit-record.interface.js';
+/** Resolves the acting principal from the pipeline context. */
+export type AuditActorFactory = (context: IPipelineContext) => AuditActor | undefined;
+/** Produces extra, request-aware metadata to attach to an audit record. */
+export type AuditMetadataFactory = (context: IPipelineContext) => Record<string, unknown>;
+/** Custom redactor replacing a raw payload/response with a safe-to-store value. */
+export type AuditRedactor = (value: unknown) => unknown;
+/**
+ * Per-handler (and constructor-default) options for {@link AuditBehavior}.
+ *
+ * Supplied per handler via `pipeline.wrap(options, [AuditBehavior, { ... }])`,
+ * shallow-merged over the constructor defaults (handler keys win).
+ *
+ * @example Audit a sensitive login command
+ * ```ts
+ * class LoginHandler {
+ *   @pipeline.wrap({ kind: 'command' }, [AuditBehavior, {
+ *     action: 'auth.login',
+ *     severity: 'medium',
+ *     redactKeys: ['code'],
+ *     actor: (ctx) => {
+ *       const command = ctx.request as LoginCommand;
+ *       return { id: command.email, email: command.email };
+ *     },
+ *   }])
+ *   async handle(command: LoginCommand) {}
+ * }
+ * ```
+ */
+export interface AuditBehaviorOptions {
+    /**
+     * Logical action name recorded on the entry (e.g. `user.create`).
+     * Default: `context.requestName`.
+     */
+    action?: string;
+    /**
+     * Severity recorded on the entry. Default: `'medium'`, or `'low'` for queries.
+     */
+    severity?: AuditSeverity;
+    /**
+     * Resolve the acting principal — typically reads an id from `context.items`
+     * set by an upstream auth behavior, e.g.
+     * `actor: (c) => ({ id: c.items.get('currentUserId') })`.
+     */
+    actor?: AuditActorFactory;
+    /**
+     * Record the (redacted) request payload. Default `true`. Set `false` for
+     * high-volume or sensitive handlers where the action alone is enough.
+     */
+    captureRequest?: boolean;
+    /**
+     * Record the (redacted) handler response. Default `false` — responses are
+     * often large and rarely needed for an audit trail.
+     */
+    captureResponse?: boolean;
+    /**
+     * Request kinds to audit. Default `['command']`: queries change nothing, and
+     * a domain event follows a command that is already audited. Example:
+     * `['command', 'query']` to also audit reads.
+     */
+    captureKinds?: AuditRequestKind[];
+    /**
+     * Case-insensitive payload/response field names whose values are masked with
+     * `'[REDACTED]'` before storage. Merged with the built-in defaults
+     * (`password`, `token`, `secret`, …). Set `redact` for full control.
+     */
+    redactKeys?: string[];
+    /**
+     * Full custom redaction of the payload/response, replacing the built-in
+     * key-masking. Receives the raw value, returns the safe-to-store value.
+     */
+    redact?: AuditRedactor;
+    /** Produce extra metadata to merge into the audit record. */
+    metadata?: AuditMetadataFactory;
+    /**
+     * Write a pending start record before the handler runs, when the sink
+     * implements `begin`. Default `true`. Set `false` to save that write when a
+     * lost record is acceptable.
+     */
+    recordStart?: boolean;
+    /**
+     * Include the error stack trace on failure records. Default `true`.
+     */
+    includeStack?: boolean;
+    /**
+     * When record construction (actor/metadata/redactor factories) or the sink itself throws,
+     * allow the request to continue (`true`, default) or fail a successful request with the
+     * audit error (`false`). A handler error is always rethrown unchanged, and an audit failure
+     * on that path is only logged. Fail-open favors availability; fail-closed favors a
+     * guaranteed audit trail.
+     */
+    failOpen?: boolean;
+}
+//# sourceMappingURL=audit-options.interface.d.ts.map

package/dist/interfaces/audit-options.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-options.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/audit-options.interface.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,aAAa,EACd,MAAM,6BAA6B,CAAC;AAErC,+DAA+D;AAC/D,MAAM,MAAM,iBAAiB,GAAG,CAC9B,OAAO,EAAE,gBAAgB,KACtB,UAAU,GAAG,SAAS,CAAC;AAE5B,2EAA2E;AAC3E,MAAM,MAAM,oBAAoB,GAAG,CACjC,OAAO,EAAE,gBAAgB,KACtB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE7B,mFAAmF;AACnF,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB;;;;OAIG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAClC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;OAEG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}

package/dist/interfaces/audit-options.interface.js

@@ -0,0 +1,3 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+export {};
+//# sourceMappingURL=audit-options.interface.js.map

package/dist/interfaces/audit-options.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-options.interface.js","sourceRoot":"","sources":["../../src/interfaces/audit-options.interface.ts"],"names":[],"mappings":"AAAA,sEAAsE"}

package/dist/interfaces/audit-record.interface.d.ts

@@ -0,0 +1,79 @@
+/** Request kinds as classified by the pipeline. */
+export type AuditRequestKind = 'command' | 'query' | 'event' | 'unknown';
+/** Whether the audited operation succeeded or threw. */
+export type AuditOutcome = 'success' | 'failure';
+/** Relative importance of an audited action, for filtering / alerting. */
+export type AuditSeverity = 'low' | 'medium' | 'high' | 'critical';
+/**
+ * The principal that triggered the audited action — resolved from the pipeline
+ * context (e.g. read from `context.items` populated by an upstream auth
+ * behavior). `id` is conventional; arbitrary extra fields are allowed.
+ */
+export interface AuditActor {
+    /** Stable identifier of the actor (user id, service account, api key id). */
+    id?: string;
+    [key: string]: unknown;
+}
+/** Serializable description of a failure captured in an audit record. */
+export interface AuditError {
+    /** Error class name (e.g. `ForbiddenException`), or `'unknown'` for non-Error throws. */
+    name: string;
+    /** Error message. */
+    message: string;
+    /** Stack trace, unless suppressed via `includeStack: false`. */
+    stack?: string;
+}
+/**
+ * A single audit-trail entry for one pipeline operation (who did what, when,
+ * and with what outcome), forwarded to an
+ * {@link AuditSink}.
+ *
+ * Unlike a dead letter (failures only), an audit record is written for **both**
+ * successful and failed operations, so denied/rejected attempts are captured too.
+ */
+export interface AuditRecord {
+    /** Unique id for this entry (UUIDv7, so ids sort in start order). */
+    id: string;
+    /** Correlation ID of the pipeline run (for cross-system tracing). */
+    correlationId: string;
+    /** Active tenant identifier if execution occurred within a multi-tenant context. */
+    tenantId?: string;
+    /** Logical action name, e.g. `user.create`. Defaults to the request name. */
+    action: string;
+    /** Severity of the action. Defaults to `'medium'` (`'low'` for queries). */
+    severity: AuditSeverity;
+    /** Whether the operation succeeded or failed. */
+    outcome: AuditOutcome;
+    /** The principal that performed the action, if resolvable. */
+    actor?: AuditActor;
+    /** Whether the request was a command, query, event, or unknown. */
+    requestKind: AuditRequestKind;
+    /** Request class name, e.g. `CreateUserCommand`. */
+    requestName: string;
+    /** Handler class name, e.g. `CreateUserHandler`. */
+    handlerName: string;
+    /** The request payload (redacted), unless `captureRequest: false`. */
+    payload?: unknown;
+    /** The handler response (redacted), only when `captureResponse: true`. */
+    response?: unknown;
+    /** Error details — present only when `outcome` is `'failure'`. */
+    error?: AuditError;
+    /** Wall-clock duration of the operation in milliseconds. */
+    durationMs: number;
+    /** ISO-8601 timestamp of when the operation started. */
+    timestamp: string;
+    /** Metadata from the `metadata` factory, plus `tenantId` when present. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * The record written before the handler runs, when the sink implements
+ * {@link AuditSink.begin}. Its `outcome` stays `'pending'` until the final
+ * {@link AuditRecord}, written under the same `id`, replaces it. A record still
+ * pending after the process stopped marks an attempt whose outcome is unknown:
+ * the handler may or may not have completed.
+ */
+export type AuditStartRecord = Omit<AuditRecord, 'outcome' | 'response' | 'error' | 'durationMs'> & {
+    /** Always `'pending'`: the operation has not finished. */
+    outcome: 'pending';
+};
+//# sourceMappingURL=audit-record.interface.d.ts.map

package/dist/interfaces/audit-record.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-record.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/audit-record.interface.ts"],"names":[],"mappings":"AAEA,mDAAmD;AACnD,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;AAEzE,wDAAwD;AACxD,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC;AAEjD,0EAA0E;AAC1E,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAEnE;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,6EAA6E;IAC7E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,yEAAyE;AACzE,MAAM,WAAW,UAAU;IACzB,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,qEAAqE;IACrE,aAAa,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,QAAQ,EAAE,aAAa,CAAC;IACxB,iDAAiD;IACjD,OAAO,EAAE,YAAY,CAAC;IACtB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,mEAAmE;IACnE,WAAW,EAAE,gBAAgB,CAAC;IAC9B,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,kEAAkE;IAClE,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CACjC,WAAW,EACX,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,YAAY,CAChD,GAAG;IACF,0DAA0D;IAC1D,OAAO,EAAE,SAAS,CAAC;CACpB,CAAC"}

package/dist/interfaces/audit-record.interface.js

@@ -0,0 +1,3 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+export {};
+//# sourceMappingURL=audit-record.interface.js.map

package/dist/interfaces/audit-record.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-record.interface.js","sourceRoot":"","sources":["../../src/interfaces/audit-record.interface.ts"],"names":[],"mappings":"AAAA,sEAAsE"}

package/dist/interfaces/audit-sink.interface.d.ts

@@ -0,0 +1,37 @@
+import type { AuditRecord, AuditStartRecord } from './audit-record.interface.js';
+/**
+ * Backend-agnostic sink for audit records — the single seam every storage
+ * backend implements.
+ *
+ * Implement this once per backend; the bundled implementations are
+ * {@link LogAuditSink} (default, zero-dependency) and
+ * {@link PostgresAuditSink}. Because {@link AuditBehavior} depends only on this
+ * interface, swapping the backend (Postgres, an event store, Kafka, an HTTP
+ * collector, …) is a one-line change: the sink passed to its constructor.
+ */
+export interface AuditSink {
+    /**
+     * Persist / publish a single audit record.
+     *
+     * Implementations should be resilient. A throw here is logged by the
+     * behavior; with `failOpen: false` it also fails a successful request. A
+     * handler error is always rethrown unchanged.
+     *
+     * @param record - The completed audit entry to forward.
+     */
+    write(record: AuditRecord): Promise<void> | void;
+    /**
+     * Persist the start of an operation, before its handler runs. Optional:
+     * when implemented, {@link AuditBehavior} calls it first (unless
+     * `recordStart: false`), then calls {@link write} with the final record
+     * under the same `id`, which must replace this one. An attempt interrupted
+     * by a process stop then stays visible as `'pending'` instead of being lost.
+     *
+     * A throw here is logged by the behavior; with `failOpen: false` it also
+     * stops the request before its handler runs.
+     *
+     * @param record - The pending entry for the operation about to run.
+     */
+    begin?(record: AuditStartRecord): Promise<void> | void;
+}
+//# sourceMappingURL=audit-sink.interface.d.ts.map

package/dist/interfaces/audit-sink.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-sink.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/audit-sink.interface.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,WAAW,EACX,gBAAgB,EACjB,MAAM,6BAA6B,CAAC;AAErC;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAEjD;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACxD"}

package/dist/interfaces/audit-sink.interface.js

@@ -0,0 +1,3 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+export {};
+//# sourceMappingURL=audit-sink.interface.js.map

package/dist/interfaces/audit-sink.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-sink.interface.js","sourceRoot":"","sources":["../../src/interfaces/audit-sink.interface.ts"],"names":[],"mappings":"AAAA,sEAAsE"}

package/dist/sinks/log.sink.d.ts

@@ -0,0 +1,33 @@
+import type { AuditRecord } from '../interfaces/audit-record.interface.js';
+import type { AuditSink } from '../interfaces/audit-sink.interface.js';
+/** Minimal structural logger satisfied by the NestJS `Logger` and `console`. */
+export interface AuditLoggerLike {
+    log(message: string): void;
+    warn(message: string): void;
+}
+/** Options for {@link LogAuditSink}. */
+export interface LogAuditSinkOptions {
+    /** Logger to write to. Default: the global `console`. */
+    logger?: AuditLoggerLike;
+    /** Pretty-print the JSON record over multiple lines. Default `false`. */
+    pretty?: boolean;
+}
+/**
+ * Zero-dependency {@link AuditSink} that writes each record as a JSON line to a
+ * logger (the global `console` by default). The default sink — ideal for local
+ * development, tests, or shipping audit logs through your existing log pipeline.
+ *
+ * Failures are routed to `warn`, successes to `log`, so they are easy to filter.
+ *
+ * @example
+ * ```ts
+ *  * new LogAuditSink({ logger: console, pretty: true });
+ * ```
+ */
+export declare class LogAuditSink implements AuditSink {
+    private readonly logger;
+    private readonly pretty;
+    constructor(options?: LogAuditSinkOptions);
+    write(record: AuditRecord): void;
+}
+//# sourceMappingURL=log.sink.d.ts.map

package/dist/sinks/log.sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.sink.d.ts","sourceRoot":"","sources":["../../src/sinks/log.sink.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AAC3E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uCAAuC,CAAC;AAEvE,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,YAAa,YAAW,SAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IAEjC,YAAY,OAAO,GAAE,mBAAwB,EAG5C;IAED,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAQ/B;CACF"}

package/dist/sinks/log.sink.js

@@ -0,0 +1,31 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { stringifyAuditValue } from '../helpers/json.js';
+/**
+ * Zero-dependency {@link AuditSink} that writes each record as a JSON line to a
+ * logger (the global `console` by default). The default sink — ideal for local
+ * development, tests, or shipping audit logs through your existing log pipeline.
+ *
+ * Failures are routed to `warn`, successes to `log`, so they are easy to filter.
+ *
+ * @example
+ * ```ts
+ *  * new LogAuditSink({ logger: console, pretty: true });
+ * ```
+ */
+export class LogAuditSink {
+    logger;
+    pretty;
+    constructor(options = {}) {
+        this.logger = options.logger ?? console;
+        this.pretty = options.pretty ?? false;
+    }
+    write(record) {
+        const line = stringifyAuditValue(record, this.pretty ? 2 : undefined);
+        if (record.outcome === 'failure') {
+            this.logger.warn(line);
+            return;
+        }
+        this.logger.log(line);
+    }
+}
+//# sourceMappingURL=log.sink.js.map

package/dist/sinks/log.sink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.sink.js","sourceRoot":"","sources":["../../src/sinks/log.sink.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAkBzD;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,YAAY;IACN,MAAM,CAAkB;IACxB,MAAM,CAAU;IAEjC,YAAY,OAAO,GAAwB,EAAE;QAC3C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC;QACxC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,MAAmB;QACvB,MAAM,IAAI,GAAG,mBAAmB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAEtE,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACvB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;CACF"}

package/dist/sinks/postgres.sink.d.ts

@@ -0,0 +1,69 @@
+import type { AuditRecord, AuditStartRecord } from '../interfaces/audit-record.interface.js';
+import type { AuditSink } from '../interfaces/audit-sink.interface.js';
+/**
+ * Minimal structural shape of a `pg` `Pool` / `Client`. Declared locally so this
+ * package does not hard-depend on `pg` — a real `Pool` or `Client` satisfies it.
+ * Add it in your app: `pnpm add pg`.
+ */
+export interface PostgresQueryableLike {
+    query(text: string, values?: unknown[]): Promise<unknown>;
+}
+/** Options for {@link PostgresAuditSink}. */
+export interface PostgresAuditSinkOptions {
+    /**
+     * Destination table, optionally schema-qualified (e.g. `audit.audit_log`).
+     * Default `'audit_log'`. Validated as a safe SQL identifier.
+     */
+    table?: string;
+}
+/**
+ * SQL to create the audit table. Run once in a migration.
+ *
+ * A row whose `outcome` is `'pending'` is an operation that started and has no
+ * final record: `duration_ms` and `completed_at` stay null. An old pending row
+ * marks an attempt interrupted by a process stop, whose outcome is unknown:
+ *
+ * ```sql
+ * SELECT * FROM audit_log
+ * WHERE outcome = 'pending' AND occurred_at < now() - interval '1 hour';
+ * ```
+ *
+ * @param table - Table name (validated). Default `'audit_log'`.
+ */
+export declare function createAuditTableSql(table?: string): string;
+/**
+ * {@link AuditSink} backed by **Postgres** (`pg`) — a drop-in replacement for
+ * the console sink. {@link begin} inserts a pending row when an operation
+ * starts, and {@link write} completes it under the same id (or inserts it, when
+ * no pending row exists), so an operation interrupted by a process stop stays
+ * visible as `'pending'`.
+ *
+ * Create the table once with {@link createAuditTableSql}. The table name is
+ * validated as a plain SQL identifier (it is interpolated, not parameterized);
+ * all record values are passed as bound parameters. A NUL character or a lone
+ * surrogate, which `jsonb` rejects, is stored as U+FFFD (see
+ * `toPostgresJson`), so one such character cannot lose the whole record.
+ *
+ * @example
+ * ```ts
+ * import { Pool } from 'pg';
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * await pool.query(createAuditTableSql());
+ * const sink = new PostgresAuditSink(pool);
+ * ```
+ */
+export declare class PostgresAuditSink implements AuditSink {
+    private readonly db;
+    private readonly beginSql;
+    private readonly writeSql;
+    constructor(db: PostgresQueryableLike, options?: PostgresAuditSinkOptions);
+    /** Inserts the pending row of an operation about to run. */
+    begin(record: AuditStartRecord): Promise<void>;
+    /**
+     * Inserts the final row, or completes the pending row that {@link begin}
+     * inserted under the same id.
+     */
+    write(record: AuditRecord): Promise<void>;
+    private values;
+}
+//# sourceMappingURL=postgres.sink.d.ts.map

package/dist/sinks/postgres.sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.sink.d.ts","sourceRoot":"","sources":["../../src/sinks/postgres.sink.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,WAAW,EACX,gBAAgB,EACjB,MAAM,yCAAyC,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uCAAuC,CAAC;AAEvE;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3D;AAED,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAeD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,SAAc,GAAG,MAAM,CAoB/D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,iBAAkB,YAAW,SAAS;IAK/C,OAAO,CAAC,QAAQ,CAAC,EAAE;IAJrB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,YACmB,EAAE,EAAE,qBAAqB,EAC1C,OAAO,GAAE,wBAA6B,EAmBvC;IAED,4DAA4D;IACtD,KAAK,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnD;IAED;;;OAGG;IACG,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9C;IAED,OAAO,CAAC,MAAM;CA6Bf"}