audit

Classes

AuditError

Defined in: packages/nexus-agents/src/audit/audit-types.ts:18

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

Extends

Error

Constructors

Constructor

new AuditError(message, options?): AuditError;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:23

Parameters

message

string

options?

cause?

Error

context?

Record<string, unknown>

Returns

AuditError

Overrides

Error.constructor

Properties

cause

readonly cause: Error | undefined;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:21

Overrides

Error.cause

code

readonly code: "AUDIT_ERROR" = 'AUDIT_ERROR';

Defined in: packages/nexus-agents/src/audit/audit-types.ts:19

context

readonly context: Record<string, unknown> | undefined;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:20

message

message: string;

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075

Inherited from

Error.message

name

name: string;

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074

Inherited from

Error.name

stack?

optional stack?: string;

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

Error.stack

stackTraceLimit

static stackTraceLimit: number;

Defined in: node_modules/.pnpm/@types+node@25.9.8/node_modules/@types/node/globals.d.ts:67

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from

Error.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@25.9.8/node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

Error.captureStackTrace

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/.pnpm/@types+node@25.9.8/node_modules/@types/node/globals.d.ts:55

Parameters

err

Error

stackTraces

CallSite[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

Error.prepareStackTrace

AuditLogger

Defined in: packages/nexus-agents/src/audit/audit-logger.ts:358

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

Implements

IAuditLogger

Constructors

Constructor

new AuditLogger(
   config, 
   storage?, 
   logger?, 
   onPersistFailure?
): AuditLogger;

Defined in: packages/nexus-agents/src/audit/audit-logger.ts:375

Parameters

config

categories?

enableCompression

boolean = ...

enableHashChain

boolean = ...

filePrefix

string = ...

flushIntervalMs

number = ...

logDir

string = ...

maxFiles

number = ...

maxFileSizeBytes

number = ...

maxQueueDepth

number = ...

Maximum in-memory event queue depth before drop-oldest backpressure engages. Bounds memory under load when storage.write is slow or the flush timer is overlapping; see #2979.

minSeverity

"critical" | "info" | "warning" = ...

storage?

IAuditStorage

logger?

ILogger

onPersistFailure?

(error) => void

Returns

AuditLogger

Methods

close()

close(): Promise<void>;

Defined in: packages/nexus-agents/src/audit/audit-logger.ts:823

Close the logger

Returns

Promise<void>

Implementation of

IAuditLogger.close

flush()

flush(): Promise<void>;

Defined in: packages/nexus-agents/src/audit/audit-logger.ts:804

Drain the in-memory queue to storage AND flush the storage’s own buffer to disk. Concurrent calls are coalesced into a single in-flight promise so an overlapping flush-timer tick cannot spawn parallel drains (see #2979). A caller arriving while a flush is already running awaits the existing promise; their newly-queued events, if any, are picked up by the next flush — the timer’s, or the extra passes close runs (#6573).

Returns

Promise<void>

Implementation of

IAuditLogger.flush

getPersistFailureCount()

getPersistFailureCount(): number;

Defined in: packages/nexus-agents/src/audit/audit-logger.ts:456

Process-lifetime count of audit flushes that FAILED to persist (#3916). A non-zero value means at least one audit event was not durably written — the hash chain may have a gap. Surfaced so the failure is observable rather than silent.

Returns

number

log()

log(input): void;

Defined in: packages/nexus-agents/src/audit/audit-logger.ts:532

Log an audit event

Parameters

input

action

string = ...

actor

{ id: string; ip?: string; name?: string; type: "system" | "user" | "external" | "agent"; userAgent?: string; } = AuditActorSchema

actor.id

string = ...

actor.ip?

string = ...

actor.name?

string = ...

actor.type

"system" | "user" | "external" | "agent" = ...

actor.userAgent?

string = ...

category

description?

string = ...

durationMs?

number = ...

metadata?

Record<string, unknown> = ...

outcome

"error" | "success" | "failure" | "denied" = AuditOutcomeSchema

policyDecision?

string = ...

policyName?

string = ...

policyOccurrence?

number = ...

See

AuditEventSchema.policyOccurrence (#5228 review).

requestId?

string = ...

resource?

{ id: string; name?: string; path?: string; type: string; } = ...

resource.id

string = ...

resource.name?

string = ...

resource.path?

string = ...

resource.type

string = ...

sessionId?

string = ...

severity

"critical" | "info" | "warning" = ...

toolName?

string = ...

traceId?

string = ...

violationType?

string = ...

Returns

void

Implementation of

IAuditLogger.log

logPolicyDecision()

logPolicyDecision(opts): void;

Defined in: packages/nexus-agents/src/audit/audit-logger.ts:592

Log a policy decision. See the interface note on parameter variance.

Parameters

opts

PolicyDecisionAuditOpts

Returns

void

Implementation of

IAuditLogger.logPolicyDecision

logRateLimitViolation()

logRateLimitViolation(opts): void;

Defined in: packages/nexus-agents/src/audit/audit-logger.ts:622

Log a rate limit violation

Parameters

opts

RateLimitAuditOpts

Returns

void

Implementation of

IAuditLogger.logRateLimitViolation

logSecurityEvent()

logSecurityEvent(opts): void;

Defined in: packages/nexus-agents/src/audit/audit-logger.ts:608

Log a security event

Parameters

opts

SecurityEventAuditOpts

Returns

void

Implementation of

IAuditLogger.logSecurityEvent

logSystemShutdown()

logSystemShutdown(metadata?): void;

Defined in: packages/nexus-agents/src/audit/audit-logger.ts:735

Parameters

metadata?

Record<string, unknown>

Optional structured detail attached to the record.

Returns

void

Deprecated

Use logSystemShutdownBegin. Kept so #5577 does not remove a published method; it now delegates, so the record it writes is system.shutdown.begin rather than the old system.shutdown / success, which claimed a shutdown that had not happened. Removal is tracked for the next major.

logSystemShutdownBegin()

logSystemShutdownBegin(metadata?): void;

Defined in: packages/nexus-agents/src/audit/audit-logger.ts:755

Log that shutdown has begun (#5577).

There is deliberately no matching completion record. This logger is the FIRST thing closed in the cleanup handler — the EventBus, observer, memory, bridge and server are torn down after it — so by the time shutdown has actually completed the sink is closed and nothing can be written. The previous system.shutdown / success record claimed a completed shutdown that had not happened.

Known consequence, raised by the panel that chose this shape: a system.shutdown.begin with no successor is indistinguishable from a hard kill. That cannot be resolved from inside a dying process; recording the real outcome needs a supervisor outside it. Absence of a completion record here is by construction, not a lost event.

Parameters

metadata?

Record<string, unknown>

Returns

void

logSystemStartup()

logSystemStartup(metadata?, outcome?): void;

Defined in: packages/nexus-agents/src/audit/audit-logger.ts:711

Log the startup COMPLETION record (#5577).

Must be called only once startup has actually finished. Before #5577 this was written the moment the audit logger was constructed, so a throw in authentication, tool registration or transport connect left a durable “startup succeeded” record for a server that never started.

Parameters

metadata?

Record<string, unknown>

Optional structured detail attached to the record.

outcome?

"success" | "failure"

success when the server reached “waiting for requests”; failure when the startup sequence threw.

Returns

void

logSystemStartupBegin()

logSystemStartupBegin(metadata?): void;

Defined in: packages/nexus-agents/src/audit/audit-logger.ts:687

Log that startup has begun (#5577).

Emitted when the audit logger itself is constructed, which is long before authentication, tool registration and transport connect have run. The completion record is system.startup, written at the point the server reaches “waiting for requests” — see logSystemStartup.

outcome is success because the enum has no in-progress value; the phase lives in the action name, not the outcome.

Parameters

metadata?

Record<string, unknown>

Returns

void

logTierTransition()

logTierTransition(opts): void;

Defined in: packages/nexus-agents/src/audit/audit-logger.ts:652

Log an authority-tier transition (Epic D / ADR-0017, #3842). A promotion or demotion of a loop’s authority tier is recorded as a hash-chained governance-category event whose metadata.tierTransition carries the structured TierTransitionPayload ({subject, fromTier, toTier, evidenceRef, ratificationVoteRef?}).

The emitter does NOT itself enforce the ratification invariant (a promotion with no ratificationVoteRef is still chained — tampering with the log to remove the field must not erase the event). The invariant is enforced by the ratification gate (scripts/check-authority-tier-drift.ts), which reads the chained events back and FAILS a promotion lacking a vote ref. A promotion is emitted at warning severity (it grants authority) so it surfaces above the default info floor; a demotion is info (it is the safe direction).

Parameters

opts

TierTransitionAuditOpts

Returns

void

Implementation of

IAuditLogger.logTierTransition

logToolInvocation()

logToolInvocation(opts): void;

Defined in: packages/nexus-agents/src/audit/audit-logger.ts:575

Log a tool invocation

Parameters

opts

ToolInvocationAuditOpts

Returns

void

Implementation of

IAuditLogger.logToolInvocation

FileAuditStorage

Defined in: packages/nexus-agents/src/audit/audit-storage.ts:142

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

Implements

IAuditStorage

Constructors

Constructor

new FileAuditStorage(
   config, 
   logger?, 
   skipValidation?
): FileAuditStorage;

Defined in: packages/nexus-agents/src/audit/audit-storage.ts:195

Constructor for FileAuditStorage.

SECURITY NOTE: Prefer using FileAuditStorage.create() for safe instantiation with proper path validation and error handling.

Parameters

config

Audit log configuration

categories?

enableCompression

boolean = ...

enableHashChain

boolean = ...

filePrefix

string = ...

flushIntervalMs

number = ...

logDir

string = ...

maxFiles

number = ...

maxFileSizeBytes

number = ...

maxQueueDepth

number = ...

Maximum in-memory event queue depth before drop-oldest backpressure engages. Bounds memory under load when storage.write is slow or the flush timer is overlapping; see #2979.

minSeverity

"critical" | "info" | "warning" = ...

logger?

ILogger

Optional logger instance

skipValidation?

boolean = false

Internal flag, set by create() after validation

Returns

FileAuditStorage

Throws

SecurityError if path validation fails and skipValidation is false

Methods

appendChained()

appendChained(seal): Promise<void>;

Defined in: packages/nexus-agents/src/audit/audit-storage.ts:333

Append a chained batch under the cross-process lock (#6546). The tail read, the seal and the flush to disk all happen while the lock is held, so two processes can neither both chain from the same tail (a fork) nor interleave lines between another process’s read and write.

Parameters

seal

(tailHash) => readonly { action: string; actor: { id: string; ip?: string; name?: string; type: "system" | "user" | "external" | "agent"; userAgent?: string; }; category: | "governance" | "system" | "authorization" | "configuration" | "security" | "authentication" | "tool_invocation" | "data_access" | "data_modification"; description?: string; durationMs?: number; hash?: string; hashVersion?: number; id: string; metadata?: Record<string, unknown>; outcome: "error" | "success" | "failure" | "denied"; policyDecision?: string; policyName?: string; policyOccurrence?: number; previousHash?: string; requestId?: string; resource?: { id: string; name?: string; path?: string; type: string; }; sessionId?: string; severity: "critical" | "info" | "warning"; timestamp: string; timestampMs: number; toolName?: string; traceId?: string; version: "1.0"; violationType?: string; }[]

Returns

Promise<void>

Implementation of

IAuditStorage.appendChained

close()

close(): Promise<void>;

Defined in: packages/nexus-agents/src/audit/audit-storage.ts:386

Close the storage

Returns

Promise<void>

Implementation of

IAuditStorage.close

flush()

flush(): Promise<void>;

Defined in: packages/nexus-agents/src/audit/audit-storage.ts:308

Flush pending writes

Returns

Promise<void>

Implementation of

IAuditStorage.flush

query()

query(criteria): Promise<{
  action: string;
  actor: {
     id: string;
     ip?: string;
     name?: string;
     type: "system" | "user" | "external" | "agent";
     userAgent?: string;
  };
  category:   | "governance"
     | "system"
     | "authorization"
     | "configuration"
     | "security"
     | "authentication"
     | "tool_invocation"
     | "data_access"
     | "data_modification";
  description?: string;
  durationMs?: number;
  hash?: string;
  hashVersion?: number;
  id: string;
  metadata?: Record<string, unknown>;
  outcome: "error" | "success" | "failure" | "denied";
  policyDecision?: string;
  policyName?: string;
  policyOccurrence?: number;
  previousHash?: string;
  requestId?: string;
  resource?: {
     id: string;
     name?: string;
     path?: string;
     type: string;
  };
  sessionId?: string;
  severity: "critical" | "info" | "warning";
  timestamp: string;
  timestampMs: number;
  toolName?: string;
  traceId?: string;
  version: "1.0";
  violationType?: string;
}[]>;

Defined in: packages/nexus-agents/src/audit/audit-storage.ts:401

Query events by criteria

Parameters

criteria

actorId?

string = ...

categories?

endTime?

Date = ...

limit

number = ...

offset

number = ...

outcomes?

("error" | "success" | "failure" | "denied")[] = ...

requestId?

string = ...

resourceId?

string = ...

severities?

("critical" | "info" | "warning")[] = ...

startTime?

Date = ...

traceId?

string = ...

Returns

Promise<{ action: string; actor: { id: string; ip?: string; name?: string; type: "system" | "user" | "external" | "agent"; userAgent?: string; }; category: | "governance" | "system" | "authorization" | "configuration" | "security" | "authentication" | "tool_invocation" | "data_access" | "data_modification"; description?: string; durationMs?: number; hash?: string; hashVersion?: number; id: string; metadata?: Record<string, unknown>; outcome: "error" | "success" | "failure" | "denied"; policyDecision?: string; policyName?: string; policyOccurrence?: number; previousHash?: string; requestId?: string; resource?: { id: string; name?: string; path?: string; type: string; }; sessionId?: string; severity: "critical" | "info" | "warning"; timestamp: string; timestampMs: number; toolName?: string; traceId?: string; version: "1.0"; violationType?: string; }[]>

Implementation of

IAuditStorage.query

write()

write(event): Promise<void>;

Defined in: packages/nexus-agents/src/audit/audit-storage.ts:295

Write an audit event to storage

Parameters

event

action

string = ...

actor

{ id: string; ip?: string; name?: string; type: "system" | "user" | "external" | "agent"; userAgent?: string; } = AuditActorSchema

actor.id

string = ...

actor.ip?

string = ...

actor.name?

string = ...

actor.type

"system" | "user" | "external" | "agent" = ...

actor.userAgent?

string = ...

category

description?

string = ...

durationMs?

number = ...

hash?

string = ...

hashVersion?

number = ...

Hash-projection version (#3921). ABSENT/1 = the legacy projection ({id,timestamp,category,action,outcome,actor,previousHash}); 2 = the legacy projection PLUS the canonicalized metadata.tierTransition payload, so a tier-transition’s integrity-critical payload is hash-covered. Versioned so pre-existing v1 chains keep verifying under their own projection (see AUDIT_HASH_VERSION_TIER_TRANSITION).

id

string = ...

metadata?

Record<string, unknown> = ...

outcome

"error" | "success" | "failure" | "denied" = AuditOutcomeSchema

policyDecision?

string = ...

policyName?

string = ...

policyOccurrence?

number = ...

Which occurrence of this {tool, rule} near-miss the record represents (#5228 review). Present only on a sampled would_deny.

TYPED and queryable rather than prose in description. The first version of the sampler wrote the ordinal into the reason string to “avoid a second schema widening” — two reviewers rejected that, correctly: a machine consumer counting records would read 14 records as 14 near-misses when 10,000 occurred, so the record did not structurally represent its own partial coverage. That is the defect this PR exists to fix, reintroduced one field over. An additive OPTIONAL field is a minor change, not a second break, so the stated reason for avoiding it did not hold.

Absent means “not sampled” — every occurrence was recorded — which is distinct from 1.

previousHash?

string = ...

requestId?

string = ...

resource?

{ id: string; name?: string; path?: string; type: string; } = ...

resource.id

string = ...

resource.name?

string = ...

resource.path?

string = ...

resource.type

string = ...

sessionId?

string = ...

severity

"critical" | "info" | "warning" = AuditSeveritySchema

timestamp

string = ...

timestampMs

number = ...

toolName?

string = ...

traceId?

string = ...

version

"1.0" = ...

violationType?

string = ...

Returns

Promise<void>

Implementation of

IAuditStorage.write

create()

static create(config, logger?): Result<FileAuditStorage, SecurityError>;

Defined in: packages/nexus-agents/src/audit/audit-storage.ts:161

Creates a FileAuditStorage instance with path validation. Use this factory method for safe instantiation with proper error handling.

Parameters

config

FileAuditStorageConfig

Audit log configuration with optional allowedRoot

logger?

ILogger

Optional logger instance

Returns

Result<FileAuditStorage, SecurityError>

Result with FileAuditStorage or SecurityError

InMemoryAuditStorage

Defined in: packages/nexus-agents/src/audit/audit-storage-queries.ts:136

In-memory audit storage implementation for testing. Events are stored in memory with configurable maximum capacity.

Implements

IAuditStorage

Constructors

Constructor

new InMemoryAuditStorage(maxEvents?): InMemoryAuditStorage;

Defined in: packages/nexus-agents/src/audit/audit-storage-queries.ts:140

Parameters

maxEvents?

number = 10000

Returns

InMemoryAuditStorage

Methods

clear()

clear(): void;

Defined in: packages/nexus-agents/src/audit/audit-storage-queries.ts:175

Clear all events (for testing)

Returns

void

close()

close(): Promise<void>;

Defined in: packages/nexus-agents/src/audit/audit-storage-queries.ts:156

Close the storage

Returns

Promise<void>

Implementation of

IAuditStorage.close

flush()

flush(): Promise<void>;

Defined in: packages/nexus-agents/src/audit/audit-storage-queries.ts:152

Flush pending writes

Returns

Promise<void>

Implementation of

IAuditStorage.flush

getAll()

getAll(): {
  action: string;
  actor: {
     id: string;
     ip?: string;
     name?: string;
     type: "system" | "user" | "external" | "agent";
     userAgent?: string;
  };
  category:   | "governance"
     | "system"
     | "authorization"
     | "configuration"
     | "security"
     | "authentication"
     | "tool_invocation"
     | "data_access"
     | "data_modification";
  description?: string;
  durationMs?: number;
  hash?: string;
  hashVersion?: number;
  id: string;
  metadata?: Record<string, unknown>;
  outcome: "error" | "success" | "failure" | "denied";
  policyDecision?: string;
  policyName?: string;
  policyOccurrence?: number;
  previousHash?: string;
  requestId?: string;
  resource?: {
     id: string;
     name?: string;
     path?: string;
     type: string;
  };
  sessionId?: string;
  severity: "critical" | "info" | "warning";
  timestamp: string;
  timestampMs: number;
  toolName?: string;
  traceId?: string;
  version: "1.0";
  violationType?: string;
}[];

Defined in: packages/nexus-agents/src/audit/audit-storage-queries.ts:170

Get all events (for testing)

Returns

query()

query(criteria): Promise<{
  action: string;
  actor: {
     id: string;
     ip?: string;
     name?: string;
     type: "system" | "user" | "external" | "agent";
     userAgent?: string;
  };
  category:   | "governance"
     | "system"
     | "authorization"
     | "configuration"
     | "security"
     | "authentication"
     | "tool_invocation"
     | "data_access"
     | "data_modification";
  description?: string;
  durationMs?: number;
  hash?: string;
  hashVersion?: number;
  id: string;
  metadata?: Record<string, unknown>;
  outcome: "error" | "success" | "failure" | "denied";
  policyDecision?: string;
  policyName?: string;
  policyOccurrence?: number;
  previousHash?: string;
  requestId?: string;
  resource?: {
     id: string;
     name?: string;
     path?: string;
     type: string;
  };
  sessionId?: string;
  severity: "critical" | "info" | "warning";
  timestamp: string;
  timestampMs: number;
  toolName?: string;
  traceId?: string;
  version: "1.0";
  violationType?: string;
}[]>;

Defined in: packages/nexus-agents/src/audit/audit-storage-queries.ts:160

Query events by criteria

Parameters

criteria

actorId?

string = ...

categories?

endTime?

Date = ...

limit

number = ...

offset

number = ...

outcomes?

("error" | "success" | "failure" | "denied")[] = ...

requestId?

string = ...

resourceId?

string = ...

severities?

("critical" | "info" | "warning")[] = ...

startTime?

Date = ...

traceId?

string = ...

Returns

Implementation of

IAuditStorage.query

write()

write(event): Promise<void>;

Defined in: packages/nexus-agents/src/audit/audit-storage-queries.ts:144

Write an audit event to storage

Parameters

event

action

string = ...

actor

{ id: string; ip?: string; name?: string; type: "system" | "user" | "external" | "agent"; userAgent?: string; } = AuditActorSchema

actor.id

string = ...

actor.ip?

string = ...

actor.name?

string = ...

actor.type

"system" | "user" | "external" | "agent" = ...

actor.userAgent?

string = ...

category

description?

string = ...

durationMs?

number = ...

hash?

string = ...

hashVersion?

number = ...

id

string = ...

metadata?

Record<string, unknown> = ...

outcome

"error" | "success" | "failure" | "denied" = AuditOutcomeSchema

policyDecision?

string = ...

policyName?

string = ...

policyOccurrence?

number = ...

Which occurrence of this {tool, rule} near-miss the record represents (#5228 review). Present only on a sampled would_deny.

Absent means “not sampled” — every occurrence was recorded — which is distinct from 1.

previousHash?

string = ...

requestId?

string = ...

resource?

{ id: string; name?: string; path?: string; type: string; } = ...

resource.id

string = ...

resource.name?

string = ...

resource.path?

string = ...

resource.type

string = ...

sessionId?

string = ...

severity

"critical" | "info" | "warning" = AuditSeveritySchema

timestamp

string = ...

timestampMs

number = ...

toolName?

string = ...

traceId?

string = ...

version

"1.0" = ...

violationType?

string = ...

Returns

Promise<void>

Implementation of

IAuditStorage.write

Interfaces

AuditHandlerConfig

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:17

Configuration for audit-enabled secure handler.

Properties

auditLogger

auditLogger: IAuditLogger;

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:19

Audit logger instance

defaultActor?

optional defaultActor?: {
  id: string;
  ip?: string;
  name?: string;
  type: "system" | "user" | "external" | "agent";
  userAgent?: string;
};

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:21

Default actor for requests without caller info

id

id: string;

ip?

optional ip?: string;

name?

optional name?: string;

type

type: "system" | "user" | "external" | "agent";

userAgent?

optional userAgent?: string;

IAuditLogger

Defined in: packages/nexus-agents/src/audit/audit-types.ts:411

Sink for audit records.

Every member is declared as a function PROPERTY, not a method, and that is load-bearing (#4991.) TypeScript exempts method-shorthand parameters from strictFunctionTypes and checks them bivariantly. When PolicyAuditDecision gained would_deny, an out-of-tree implementor still typed against the old two-value union would have kept COMPILING and then received a value it cannot handle at runtime — silently dropping the audit record, or throwing inside the authorization path. A major version bump is a note in a changelog; a property signature is a compile error.

EVERY member is converted, not just the one whose union widened. (Stated without a count on purpose: a literal here drifts the moment a member is added, which is the same doc-accuracy defect this file is fixing elsewhere. audit-types-variance.test.ts asserts the property, whatever the count.) An earlier revision converted only logPolicyDecision, on the reasoning that touching the others “would break implementors for no reason”. That reasoning was wrong, and a panel caught it: an ES6 class using ordinary method syntax satisfies a property signature perfectly well, as does an object literal with method shorthand — the ONLY implementor a property signature rejects is one whose parameter is narrower than declared, which is exactly the unsound case. Converting one member and leaving six is the dangerous state: it looks consistent enough to imitate, and the next person to widen a parameter on any of the other six silently reopens the same hole.

Limit, stated because it is real: contravariant checking requires strictFunctionTypes (implied by strict) in the CONSUMER’s tsconfig. A downstream project compiling without it falls back to bivariance, compiles a stale implementor, and drops would_deny records at runtime. That flag is outside this package’s control, so the guarantee here is “strict consumers get a compile error”, not “no consumer can get this wrong”.

Pinned by audit-types-variance.test.ts, whose @ts-expect-error probe fails with TS2578 if any of these reverts to method shorthand.

Properties

close

close: () => Promise<void>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:434

Close the logger

Returns

Promise<void>

flush

flush: () => Promise<void>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:431

Flush pending events

Returns

Promise<void>

log

log: (input) => void;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:413

Log an audit event

Parameters

input

action

string = ...

actor

{ id: string; ip?: string; name?: string; type: "system" | "user" | "external" | "agent"; userAgent?: string; } = AuditActorSchema

actor.id

string = ...

actor.ip?

string = ...

actor.name?

string = ...

actor.type

"system" | "user" | "external" | "agent" = ...

actor.userAgent?

string = ...

category

description?

string = ...

durationMs?

number = ...

metadata?

Record<string, unknown> = ...

outcome

"error" | "success" | "failure" | "denied" = AuditOutcomeSchema

policyDecision?

string = ...

policyName?

string = ...

policyOccurrence?

number = ...

See

AuditEventSchema.policyOccurrence (#5228 review).

requestId?

string = ...

resource?

{ id: string; name?: string; path?: string; type: string; } = ...

resource.id

string = ...

resource.name?

string = ...

resource.path?

string = ...

resource.type

string = ...

sessionId?

string = ...

severity

"critical" | "info" | "warning" = ...

toolName?

string = ...

traceId?

string = ...

violationType?

string = ...

Returns

void

logPolicyDecision

logPolicyDecision: (opts) => void;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:419

Log a policy decision. See the interface note on parameter variance.

Parameters

opts

PolicyDecisionAuditOpts

Returns

void

logRateLimitViolation

logRateLimitViolation: (opts) => void;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:425

Log a rate limit violation

Parameters

opts

RateLimitAuditOpts

Returns

void

logSecurityEvent

logSecurityEvent: (opts) => void;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:422

Log a security event

Parameters

opts

SecurityEventAuditOpts

Returns

void

logTierTransition

logTierTransition: (opts) => void;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:428

Log an authority-tier transition (promotion/demotion) — Epic D, #3842.

Parameters

opts

TierTransitionAuditOpts

Returns

void

logToolInvocation

logToolInvocation: (opts) => void;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:416

Log a tool invocation

Parameters

opts

ToolInvocationAuditOpts

Returns

void

IAuditStorage

Defined in: packages/nexus-agents/src/audit/audit-types.ts:326

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

Properties

appendChained?

optional appendChained?: (seal) => Promise<void>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:349

Append a batch as one step of a chain that other PROCESSES may also be appending to (#6546). Under the storage’s cross-process lock it reads the hash of the last event already persisted (undefined for an empty log), calls seal with it to link the batch, then writes and flushes the sealed events before releasing the lock.

Optional: a storage without it is single-process, and the logger chains from its own in-memory head instead.

Parameters

seal

Returns

Promise<void>

close

close: () => Promise<void>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:334

Close the storage

Returns

Promise<void>

flush

flush: () => Promise<void>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:331

Flush pending writes

Returns

Promise<void>

query

query: (criteria) => Promise<{
  action: string;
  actor: {
     id: string;
     ip?: string;
     name?: string;
     type: "system" | "user" | "external" | "agent";
     userAgent?: string;
  };
  category:   | "governance"
     | "system"
     | "authorization"
     | "configuration"
     | "security"
     | "authentication"
     | "tool_invocation"
     | "data_access"
     | "data_modification";
  description?: string;
  durationMs?: number;
  hash?: string;
  hashVersion?: number;
  id: string;
  metadata?: Record<string, unknown>;
  outcome: "error" | "success" | "failure" | "denied";
  policyDecision?: string;
  policyName?: string;
  policyOccurrence?: number;
  previousHash?: string;
  requestId?: string;
  resource?: {
     id: string;
     name?: string;
     path?: string;
     type: string;
  };
  sessionId?: string;
  severity: "critical" | "info" | "warning";
  timestamp: string;
  timestampMs: number;
  toolName?: string;
  traceId?: string;
  version: "1.0";
  violationType?: string;
}[]>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:337

Query events by criteria

Parameters

criteria

actorId?

string = ...

categories?

endTime?

Date = ...

limit

number = ...

offset

number = ...

outcomes?

("error" | "success" | "failure" | "denied")[] = ...

requestId?

string = ...

resourceId?

string = ...

severities?

("critical" | "info" | "warning")[] = ...

startTime?

Date = ...

traceId?

string = ...

Returns

write

write: (event) => Promise<void>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:328

Write an audit event to storage

Parameters

event

action

string = ...

actor

{ id: string; ip?: string; name?: string; type: "system" | "user" | "external" | "agent"; userAgent?: string; } = AuditActorSchema

actor.id

string = ...

actor.ip?

string = ...

actor.name?

string = ...

actor.type

"system" | "user" | "external" | "agent" = ...

actor.userAgent?

string = ...

category

description?

string = ...

durationMs?

number = ...

hash?

string = ...

hashVersion?

number = ...

id

string = ...

metadata?

Record<string, unknown> = ...

outcome

"error" | "success" | "failure" | "denied" = AuditOutcomeSchema

policyDecision?

string = ...

policyName?

string = ...

policyOccurrence?

number = ...

Which occurrence of this {tool, rule} near-miss the record represents (#5228 review). Present only on a sampled would_deny.

Absent means “not sampled” — every occurrence was recorded — which is distinct from 1.

previousHash?

string = ...

requestId?

string = ...

resource?

{ id: string; name?: string; path?: string; type: string; } = ...

resource.id

string = ...

resource.name?

string = ...

resource.path?

string = ...

resource.type

string = ...

sessionId?

string = ...

severity

"critical" | "info" | "warning" = AuditSeveritySchema

timestamp

string = ...

timestampMs

number = ...

toolName?

string = ...

traceId?

string = ...

version

"1.0" = ...

violationType?

string = ...

Returns

Promise<void>

LogPolicyAuditOpts

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:78

Options for logging policy audit

Properties

actor

actor: {
  id: string;
  ip?: string;
  name?: string;
  type: "system" | "user" | "external" | "agent";
  userAgent?: string;
};

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:84

id

id: string;

ip?

optional ip?: string;

name?

optional name?: string;

type

type: "system" | "user" | "external" | "agent";

userAgent?

optional userAgent?: string;

auditLogger

auditLogger: IAuditLogger;

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:79

decision

decision: "allow" | "deny";

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:81

policyName

policyName: string;

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:80

reason

reason: string;

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:82

requestId

requestId: string;

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:85

toolName

toolName: string;

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:83

LogRateLimitAuditOpts

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:103

Options for logging rate limit audit

Properties

actor

actor: {
  id: string;
  ip?: string;
  name?: string;
  type: "system" | "user" | "external" | "agent";
  userAgent?: string;
};

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:106

id

id: string;

ip?

optional ip?: string;

name?

optional name?: string;

type

type: "system" | "user" | "external" | "agent";

userAgent?

optional userAgent?: string;

auditLogger

auditLogger: IAuditLogger;

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:104

currentRate

currentRate: number;

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:107

limitRate

limitRate: number;

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:108

requestId

requestId: string;

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:109

toolName

toolName: string;

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:105

LogToolInvocationOpts

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:53

Options for logging tool invocation audit

Properties

actor

actor: {
  id: string;
  ip?: string;
  name?: string;
  type: "system" | "user" | "external" | "agent";
  userAgent?: string;
};

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:57

id

id: string;

ip?

optional ip?: string;

name?

optional name?: string;

type

type: "system" | "user" | "external" | "agent";

userAgent?

optional userAgent?: string;

auditLogger

auditLogger: IAuditLogger;

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:54

durationMs?

optional durationMs?: number;

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:59

errorMessage?

optional errorMessage?: string;

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:60

outcome

outcome: "error" | "success" | "failure" | "denied";

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:56

requestId

requestId: string;

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:58

toolName

toolName: string;

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:55

PolicyDecisionAuditOpts

Defined in: packages/nexus-agents/src/audit/audit-types.ts:480

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

Properties

actor

actor: {
  id: string;
  ip?: string;
  name?: string;
  type: "system" | "user" | "external" | "agent";
  userAgent?: string;
};

Defined in: packages/nexus-agents/src/audit/audit-types.ts:485

id

id: string;

ip?

optional ip?: string;

name?

optional name?: string;

type

type: "system" | "user" | "external" | "agent";

userAgent?

optional userAgent?: string;

decision

decision: PolicyAuditDecision;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:482

metadata?

optional metadata?: Record<string, unknown>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:487

occurrence?

optional occurrence?: number;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:493

Which occurrence of this {tool, rule} near-miss this record represents (#5228 review). Set only for a sampled would_deny; absent means every occurrence was recorded.

policyName

policyName: string;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:481

reason

reason: string;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:483

requestId?

optional requestId?: string;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:486

toolName

toolName: string;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:484

RateLimitAuditOpts

Defined in: packages/nexus-agents/src/audit/audit-types.ts:505

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

Properties

actor

actor: {
  id: string;
  ip?: string;
  name?: string;
  type: "system" | "user" | "external" | "agent";
  userAgent?: string;
};

Defined in: packages/nexus-agents/src/audit/audit-types.ts:507

id

id: string;

ip?

optional ip?: string;

name?

optional name?: string;

type

type: "system" | "user" | "external" | "agent";

userAgent?

optional userAgent?: string;

currentRate

currentRate: number;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:508

limitRate

limitRate: number;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:509

requestId?

optional requestId?: string;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:510

toolName

toolName: string;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:506

SecurityEventAuditOpts

Defined in: packages/nexus-agents/src/audit/audit-types.ts:496

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

Properties

actor

actor: {
  id: string;
  ip?: string;
  name?: string;
  type: "system" | "user" | "external" | "agent";
  userAgent?: string;
};

Defined in: packages/nexus-agents/src/audit/audit-types.ts:499

id

id: string;

ip?

optional ip?: string;

name?

optional name?: string;

type

type: "system" | "user" | "external" | "agent";

userAgent?

optional userAgent?: string;

description

description: string;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:500

eventType

eventType: string;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:497

metadata?

optional metadata?: Record<string, unknown>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:502

requestId?

optional requestId?: string;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:501

severity

severity: "critical" | "info" | "warning";

Defined in: packages/nexus-agents/src/audit/audit-types.ts:498

ToolInvocationAuditOpts

Defined in: packages/nexus-agents/src/audit/audit-types.ts:441

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

Properties

actor

actor: {
  id: string;
  ip?: string;
  name?: string;
  type: "system" | "user" | "external" | "agent";
  userAgent?: string;
};

Defined in: packages/nexus-agents/src/audit/audit-types.ts:444

id

id: string;

ip?

optional ip?: string;

name?

optional name?: string;

type

type: "system" | "user" | "external" | "agent";

userAgent?

optional userAgent?: string;

durationMs?

optional durationMs?: number;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:446

errorMessage?

optional errorMessage?: string;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:447

metadata?

optional metadata?: Record<string, unknown>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:448

outcome

outcome: "error" | "success" | "failure" | "denied";

Defined in: packages/nexus-agents/src/audit/audit-types.ts:443

policyDecision?

optional policyDecision?: PolicyAuditDecision;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:458

The policy verdict for this invocation, when a rule fired (#5228 review).

Only would_deny reaches here: a real deny returns before the handler runs, so it produces no invocation record at all. Set on EVERY near-miss invocation, including those whose separate policy record was sampled out — otherwise an executed near-miss would be indistinguishable from a call no rule touched, which is the inference this change exists to break.

requestId?

optional requestId?: string;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:445

toolName

toolName: string;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:442

Type Aliases

AuditActor

type AuditActor = z.infer<typeof AuditActorSchema>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:165

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

AuditCategory

type AuditCategory = z.infer<typeof AuditCategorySchema>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:46

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

AuditEvent

type AuditEvent = z.infer<typeof AuditEventSchema>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:250

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

AuditEventInput

type AuditEventInput = z.infer<typeof AuditEventInputSchema>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:287

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

AuditLogConfig

type AuditLogConfig = z.infer<typeof AuditLogConfigSchema>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:320

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

AuditOutcome

type AuditOutcome = z.infer<typeof AuditOutcomeSchema>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:152

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

AuditQueryCriteria

type AuditQueryCriteria = z.infer<typeof AuditQueryCriteriaSchema>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:369

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

AuditResource

type AuditResource = z.infer<typeof AuditResourceSchema>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:177

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

AuditSeverity

type AuditSeverity = z.infer<typeof AuditSeveritySchema>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:140

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

Variables

AuditActorSchema

const AuditActorSchema: ZodObject<{
  id: ZodString;
  ip: ZodOptional<ZodString>;
  name: ZodOptional<ZodString>;
  type: ZodEnum<{
     agent: "agent";
     external: "external";
     system: "system";
     user: "user";
  }>;
  userAgent: ZodOptional<ZodString>;
}, $strip>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:158

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

AuditCategorySchema

const AuditCategorySchema: ZodEnum<{
  authentication: "authentication";
  authorization: "authorization";
  configuration: "configuration";
  data_access: "data_access";
  data_modification: "data_modification";
  governance: "governance";
  security: "security";
  system: "system";
  tool_invocation: "tool_invocation";
}>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:35

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

AuditEventInputSchema

const AuditEventInputSchema: ZodObject<{
  action: ZodString;
  actor: ZodObject<{
     id: ZodString;
     ip: ZodOptional<ZodString>;
     name: ZodOptional<ZodString>;
     type: ZodEnum<{
        agent: "agent";
        external: "external";
        system: "system";
        user: "user";
     }>;
     userAgent: ZodOptional<ZodString>;
  }, $strip>;
  category: ZodEnum<{
     authentication: "authentication";
     authorization: "authorization";
     configuration: "configuration";
     data_access: "data_access";
     data_modification: "data_modification";
     governance: "governance";
     security: "security";
     system: "system";
     tool_invocation: "tool_invocation";
  }>;
  description: ZodOptional<ZodString>;
  durationMs: ZodOptional<ZodNumber>;
  metadata: ZodOptional<ZodRecord<ZodString, ZodUnknown>>;
  outcome: ZodEnum<{
     denied: "denied";
     error: "error";
     failure: "failure";
     success: "success";
  }>;
  policyDecision: ZodOptional<ZodString>;
  policyName: ZodOptional<ZodString>;
  policyOccurrence: ZodOptional<ZodNumber>;
  requestId: ZodOptional<ZodString>;
  resource: ZodOptional<ZodObject<{
     id: ZodString;
     name: ZodOptional<ZodString>;
     path: ZodOptional<ZodString>;
     type: ZodString;
  }, $strip>>;
  sessionId: ZodOptional<ZodString>;
  severity: ZodDefault<ZodOptional<ZodEnum<{
     critical: "critical";
     info: "info";
     warning: "warning";
  }>>>;
  toolName: ZodOptional<ZodString>;
  traceId: ZodOptional<ZodString>;
  violationType: ZodOptional<ZodString>;
}, $strip>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:267

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

AuditEventSchema

const AuditEventSchema: ZodObject<{
  action: ZodString;
  actor: ZodObject<{
     id: ZodString;
     ip: ZodOptional<ZodString>;
     name: ZodOptional<ZodString>;
     type: ZodEnum<{
        agent: "agent";
        external: "external";
        system: "system";
        user: "user";
     }>;
     userAgent: ZodOptional<ZodString>;
  }, $strip>;
  category: ZodEnum<{
     authentication: "authentication";
     authorization: "authorization";
     configuration: "configuration";
     data_access: "data_access";
     data_modification: "data_modification";
     governance: "governance";
     security: "security";
     system: "system";
     tool_invocation: "tool_invocation";
  }>;
  description: ZodOptional<ZodString>;
  durationMs: ZodOptional<ZodNumber>;
  hash: ZodOptional<ZodString>;
  hashVersion: ZodOptional<ZodNumber>;
  id: ZodString;
  metadata: ZodOptional<ZodRecord<ZodString, ZodUnknown>>;
  outcome: ZodEnum<{
     denied: "denied";
     error: "error";
     failure: "failure";
     success: "success";
  }>;
  policyDecision: ZodOptional<ZodString>;
  policyName: ZodOptional<ZodString>;
  policyOccurrence: ZodOptional<ZodNumber>;
  previousHash: ZodOptional<ZodString>;
  requestId: ZodOptional<ZodString>;
  resource: ZodOptional<ZodObject<{
     id: ZodString;
     name: ZodOptional<ZodString>;
     path: ZodOptional<ZodString>;
     type: ZodString;
  }, $strip>>;
  sessionId: ZodOptional<ZodString>;
  severity: ZodEnum<{
     critical: "critical";
     info: "info";
     warning: "warning";
  }>;
  timestamp: ZodString;
  timestampMs: ZodNumber;
  toolName: ZodOptional<ZodString>;
  traceId: ZodOptional<ZodString>;
  version: ZodLiteral<"1.0">;
  violationType: ZodOptional<ZodString>;
}, $strip>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:183

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

AuditLogConfigSchema

const AuditLogConfigSchema: ZodObject<{
  categories: ZodOptional<ZodArray<ZodEnum<{
     authentication: "authentication";
     authorization: "authorization";
     configuration: "configuration";
     data_access: "data_access";
     data_modification: "data_modification";
     governance: "governance";
     security: "security";
     system: "system";
     tool_invocation: "tool_invocation";
  }>>>;
  enableCompression: ZodDefault<ZodOptional<ZodBoolean>>;
  enableHashChain: ZodDefault<ZodOptional<ZodBoolean>>;
  filePrefix: ZodDefault<ZodOptional<ZodString>>;
  flushIntervalMs: ZodDefault<ZodOptional<ZodNumber>>;
  logDir: ZodString;
  maxFiles: ZodDefault<ZodOptional<ZodNumber>>;
  maxFileSizeBytes: ZodDefault<ZodOptional<ZodNumber>>;
  maxQueueDepth: ZodDefault<ZodOptional<ZodNumber>>;
  minSeverity: ZodDefault<ZodOptional<ZodEnum<{
     critical: "critical";
     info: "info";
     warning: "warning";
  }>>>;
}, $strip>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:293

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

AuditOutcomeSchema

const AuditOutcomeSchema: ZodEnum<{
  denied: "denied";
  error: "error";
  failure: "failure";
  success: "success";
}>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:146

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

AuditQueryCriteriaSchema

const AuditQueryCriteriaSchema: ZodObject<{
  actorId: ZodOptional<ZodString>;
  categories: ZodOptional<ZodArray<ZodEnum<{
     authentication: "authentication";
     authorization: "authorization";
     configuration: "configuration";
     data_access: "data_access";
     data_modification: "data_modification";
     governance: "governance";
     security: "security";
     system: "system";
     tool_invocation: "tool_invocation";
  }>>>;
  endTime: ZodOptional<ZodDate>;
  limit: ZodDefault<ZodOptional<ZodNumber>>;
  offset: ZodDefault<ZodOptional<ZodNumber>>;
  outcomes: ZodOptional<ZodArray<ZodEnum<{
     denied: "denied";
     error: "error";
     failure: "failure";
     success: "success";
  }>>>;
  requestId: ZodOptional<ZodString>;
  resourceId: ZodOptional<ZodString>;
  severities: ZodOptional<ZodArray<ZodEnum<{
     critical: "critical";
     info: "info";
     warning: "warning";
  }>>>;
  startTime: ZodOptional<ZodDate>;
  traceId: ZodOptional<ZodString>;
}, $strip>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:356

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

AuditResourceSchema

const AuditResourceSchema: ZodObject<{
  id: ZodString;
  name: ZodOptional<ZodString>;
  path: ZodOptional<ZodString>;
  type: ZodString;
}, $strip>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:171

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

AuditSeveritySchema

const AuditSeveritySchema: ZodEnum<{
  critical: "critical";
  info: "info";
  warning: "warning";
}>;

Defined in: packages/nexus-agents/src/audit/audit-types.ts:135

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

Functions

actorFromContext()

function actorFromContext(ctx, fallback?): {
  id: string;
  ip?: string;
  name?: string;
  type: "system" | "user" | "external" | "agent";
  userAgent?: string;
};

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:27

Creates an AuditActor from RequestContext.

Parameters

ctx

RequestContext

fallback?

id

string = ...

ip?

string = ...

name?

string = ...

type

"system" | "user" | "external" | "agent" = ...

userAgent?

string = ...

Returns

{
  id: string;
  ip?: string;
  name?: string;
  type: "system" | "user" | "external" | "agent";
  userAgent?: string;
}

id

id: string;

ip?

optional ip?: string;

name?

optional name?: string;

type

type: "system" | "user" | "external" | "agent";

userAgent?

optional userAgent?: string;

createAuditLogger()

function createAuditLogger(
   config, 
   storage?, 
   logger?, 
   onPersistFailure?
): AuditLogger;

Defined in: packages/nexus-agents/src/audit/audit-logger.ts:881

Audit exports - Structured audit logging (Issue #193) Split from index.ts for file size compliance (Issue #285)

Parameters

config

categories?

enableCompression

boolean = ...

enableHashChain

boolean = ...

filePrefix

string = ...

flushIntervalMs

number = ...

logDir

string = ...

maxFiles

number = ...

maxFileSizeBytes

number = ...

maxQueueDepth

number = ...

Maximum in-memory event queue depth before drop-oldest backpressure engages. Bounds memory under load when storage.write is slow or the flush timer is overlapping; see #2979.

minSeverity

"critical" | "info" | "warning" = ...

storage?

IAuditStorage

logger?

ILogger

onPersistFailure?

(error) => void

Returns

AuditLogger

logPolicyAudit()

function logPolicyAudit(opts): void;

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:91

Logs policy decision to audit logger.

Parameters

opts

LogPolicyAuditOpts

Returns

void

logRateLimitAudit()

function logRateLimitAudit(opts): void;

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:115

Logs rate limit violation to audit logger.

Parameters

opts

LogRateLimitAuditOpts

Returns

void

logToolInvocationAudit()

function logToolInvocationAudit(opts): void;

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:66

Logs tool invocation to audit logger.

Parameters

opts

LogToolInvocationOpts

Returns

void

resultToOutcome()

function resultToOutcome(isError, isPolicyDenied): "error" | "success" | "failure" | "denied";

Defined in: packages/nexus-agents/src/audit/secure-handler-audit.ts:43

Maps tool result to audit outcome.

Parameters

isError

boolean | undefined

isPolicyDenied

boolean

Returns

"error" | "success" | "failure" | "denied"