AuditBehaviorOptions

Defined in: pipeline-audit/src/interfaces/audit-options.interface.ts:45

Per-handler (and constructor-default) options for AuditBehavior.

Supplied per handler via pipeline.wrap(options, [AuditBehavior, { ... }]), shallow-merged over the constructor defaults (handler keys win).

Example

Audit a sensitive login command

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) {}
}

Properties

action?

optional action?: string

Defined in: pipeline-audit/src/interfaces/audit-options.interface.ts:50

Logical action name recorded on the entry (e.g. user.create). Default: context.requestName.

---

actor?

optional actor?: AuditActorFactory

Defined in: pipeline-audit/src/interfaces/audit-options.interface.ts:60

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') }).

---

captureKinds?

optional captureKinds?: AuditRequestKind[]

Defined in: pipeline-audit/src/interfaces/audit-options.interface.ts:76

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.

---

captureRequest?

optional captureRequest?: boolean

Defined in: pipeline-audit/src/interfaces/audit-options.interface.ts:65

Record the (redacted) request payload. Default true. Set false for high-volume or sensitive handlers where the action alone is enough.

---

captureResponse?

optional captureResponse?: boolean

Defined in: pipeline-audit/src/interfaces/audit-options.interface.ts:70

Record the (redacted) handler response. Default false — responses are often large and rarely needed for an audit trail.

---

failOpen?

optional failOpen?: boolean

Defined in: pipeline-audit/src/interfaces/audit-options.interface.ts:107

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.

---

includeStack?

optional includeStack?: boolean

Defined in: pipeline-audit/src/interfaces/audit-options.interface.ts:99

Include the error stack trace on failure records. Default true.

---

metadata?

optional metadata?: AuditMetadataFactory

Defined in: pipeline-audit/src/interfaces/audit-options.interface.ts:89

Produce extra metadata to merge into the audit record.

---

recordStart?

optional recordStart?: boolean

Defined in: pipeline-audit/src/interfaces/audit-options.interface.ts:95

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.

---

redact?

optional redact?: AuditRedactor

Defined in: pipeline-audit/src/interfaces/audit-options.interface.ts:87

Full custom redaction of the payload/response, replacing the built-in key-masking. Receives the raw value, returns the safe-to-store value.

---

redactKeys?

optional redactKeys?: string[]

Defined in: pipeline-audit/src/interfaces/audit-options.interface.ts:82

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.

---

severity?

optional severity?: AuditSeverity

Defined in: pipeline-audit/src/interfaces/audit-options.interface.ts:54

Severity recorded on the entry. Default: 'medium', or 'low' for queries.