# Class FileAuditStorage

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

#### Implements

- IAuditStorage

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

##### Index

### Constructors

constructor

### Methods

create
write
flush
close
query

## Constructors

### constructor

- new FileAuditStorage(
  config: {
  logDir: string;
  filePrefix: string;
  maxFileSizeBytes: number;
  maxFiles: number;
  enableHashChain: boolean;
  enableCompression: boolean;
  flushIntervalMs: number;
  minSeverity: "info" | "warning" | "critical";
  categories?: (
  | "authorization"
  | "system"
  | "configuration"
  | "security"
  | "authentication"
  | "tool_invocation"
  | "data_access"
  | "data_modification"
  )[];
  },
  logger?: ILogger,
  skipValidation?: boolean,
  ): FileAuditStorage

  Constructor for FileAuditStorage.

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

  #### Parameters

  - config: {
    logDir: string;
    filePrefix: string;
    maxFileSizeBytes: number;
    maxFiles: number;
    enableHashChain: boolean;
    enableCompression: boolean;
    flushIntervalMs: number;
    minSeverity: "info" | "warning" | "critical";
    categories?: (
    | "authorization"
    | "system"
    | "configuration"
    | "security"
    | "authentication"
    | "tool_invocation"
    | "data_access"
    | "data_modification"
    )[];
    }

    Audit log configuration

  - `Optional` 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

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

## Methods

### `Static` create

- create(
  config: FileAuditStorageConfig,
  logger?: ILogger,
  ): Result<FileAuditStorage, SecurityError>

  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

  - `Optional` logger: ILogger

    Optional logger instance

  #### Returns Result<FileAuditStorage, SecurityError>

  Result with FileAuditStorage or SecurityError

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

### write

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

  Write an audit event to storage

  #### Parameters

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

  #### Returns Promise<void>

  Implementation of IAuditStorage.write

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

### flush

- flush(): Promise<void>

  Flush pending writes

  #### Returns Promise<void>

  Implementation of IAuditStorage.flush

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

### close

- close(): Promise<void>

  Close the storage

  #### Returns Promise<void>

  Implementation of IAuditStorage.close

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

### query

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

  Query events by criteria

  #### Parameters

  - criteria: {
    startTime?: Date;
    endTime?: Date;
    categories?: (
    | "authorization"
    | "system"
    | "configuration"
    | "security"
    | "authentication"
    | "tool_invocation"
    | "data_access"
    | "data_modification"
    )[];
    severities?: ("info" | "warning" | "critical")[];
    outcomes?: ("error" | "success" | "failure" | "denied")[];
    actorId?: string;
    resourceId?: string;
    requestId?: string;
    traceId?: string;
    limit: number;
    offset: number;
    }

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

  Implementation of IAuditStorage.query

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