AuditBehavior

Defined in: pipeline-audit/src/audit.behavior.ts:106

Pipeline behavior that writes an AuditRecord for every audited request — on both success and failure — to a pluggable AuditSink. Only commands are audited unless captureKinds lists other request kinds.

For each run it times the handler, resolves the actor and action, redacts the payload (and optionally the response), then forwards the record. When the sink implements begin, a pending start record is written first under the same id, so a process stop during the handler leaves a pending record instead of none; with failOpen: false, a failed start write stops the request before its handler runs. Handler failures are recorded before propagation. With the default failOpen: true, sink failures are logged and the original handler result/error is preserved. With failOpen: false, a sink/build failure on the success path fails the request. If the handler already failed, the caller receives the handler’s own error, unchanged, and the audit failure is logged.

Sink-agnostic by design: it depends only on AuditSink, so the backend (console, Postgres, an event store, …) is a one-line swap: the sink passed to the constructor. Record-building failures are logged and ignored in fail-open mode, or propagated according to the same fail-closed semantics.

Ordering: place this near the outside of the chain (e.g. global before) so the duration covers the whole handler, and after any auth behavior that populates context.items for the AuditBehaviorOptions.actor factory.

Examples

Per-handler, with an actor read from an upstream auth behavior

class DeleteUserHandler {
  @pipeline.wrap({ kind: 'command' }, [AuditBehavior, {
    action: 'user.delete',
    severity: 'high',
    actor: (c) => ({ id: c.items.get('currentUserId') }),
  }])
  async handle(command: DeleteUserCommand) {}
}

Compliance-sensitive fail-closed auditing

class RefundPaymentHandler {
  @pipeline.wrap({ kind: 'command' }, [AuditBehavior, {
    action: 'payment.refund',
    failOpen: false,
    captureResponse: false,
  }])
  async handle(command: RefundPaymentCommand) {}
}