# Class AuditLogger

GDPR-compliant audit logger with pluggable sinks, parameter sanitisation, data retention enforcement, and access-controlled log retrieval.

## Pluggable sinks

By default the logger writes to an in-memory buffer (queryable via `getLogs()`) and to `stderr` (MCP-compatible). Pass a `sinks` option to replace the default stderr sink with your own destinations (e.g. `FileAuditSink`, `StructuredJsonSink`).

## Parameter sanitisation

All `params` objects are passed through `sanitizeParams()` before storage. Only top-level keys matching `sensitiveKeys` (default: `DEFAULT_SENSITIVE_KEYS`) are replaced by `'[REDACTED]'` to prevent PII leakage into audit trails. Nested objects/arrays are not recursively sanitised; callers must avoid placing PII in nested structures or pre-sanitise such data before logging.

## Data retention

When `retentionMs` is set, `getLogs()` automatically filters out entries older than the configured maximum age (GDPR Article 5(1)(e)).

## Access control

When `requiredAuthToken` is set, `getLogs()`, `queryLogs()`, `clear()`, and `eraseByUser()` throw if the caller does not supply the correct token.

#### Example: Basic usage (backward-compatible)

    auditLogger.logDataAccess('get_meps', { country: 'SE' }, 5, 85);
    const entries = auditLogger.getLogs();

#### Example: With file sink and 30-day retention

    const requiredAuthToken = process.env['AUDIT_TOKEN'];
    if (!requiredAuthToken) {
      throw new Error(
        'AUDIT_TOKEN environment variable must be set for audit log access control',
      );
    }

    const logger = new AuditLogger({
      sinks: [new FileAuditSink({ filePath: '/var/log/ep-mcp-audit.ndjson' })],
      retentionMs: 30 * 24 * 60 * 60 * 1000,
      requiredAuthToken,
    });

#### Since

0.8.0

- Defined in utils/auditLogger.ts:154

##### Index

### Constructors

constructor

### Properties

extraSinks
memorySink
requiredAuthToken
retentionPolicy
sensitiveKeys

### Methods

checkAuthorization
clear
eraseByUser
getLogs
log
logDataAccess
logError
logToolCall
pruneExpiredEntries
queryLogs
writeSinks
buildRetentionPolicy

## Constructors

### constructor

- new AuditLogger(options?: AuditLoggerOptions): AuditLogger

  #### Parameters

  - `Optional` options: AuditLoggerOptions

  #### Returns AuditLogger

  - Defined in utils/auditLogger.ts:161

## Properties

### `Private` `Readonly` extraSinks

extraSinks: readonly AuditSink[]

- Defined in utils/auditLogger.ts:156

### `Private` `Readonly` memorySink

memorySink: MemoryAuditSink

- Defined in utils/auditLogger.ts:155

### `Private` `Readonly` requiredAuthToken

requiredAuthToken: string | undefined

- Defined in utils/auditLogger.ts:159

### `Private` `Readonly` retentionPolicy

retentionPolicy: RetentionPolicy | undefined

- Defined in utils/auditLogger.ts:158

### `Private` `Readonly` sensitiveKeys

sensitiveKeys: readonly string[]

- Defined in utils/auditLogger.ts:157

## Methods

### `Private` checkAuthorization

- checkAuthorization(authorization?: string): void

  #### Parameters

  - `Optional` authorization: string

  #### Returns void

  - Defined in utils/auditLogger.ts:360

### clear

- clear(authorization?: string): void

  Clears all in-memory audit log entries.

  For testing only. Clearing audit logs in production violates ISMS Policy AU-002 and GDPR Article 30.

  #### Parameters

  - `Optional` authorization: string

    Authorization token (required when configured)

  #### Returns void

  #### Since

  0.8.0

  - Defined in utils/auditLogger.ts:355

### eraseByUser

- eraseByUser(userId: string, authorization?: string): void

  Removes all audit entries associated with `userId` from in-memory storage.

  GDPR Article 17 — Right to Erasure. Only removes entries from the in-memory `MemoryAuditSink`; entries already flushed to persistent sinks (files, SIEM, etc.) must be erased separately via those sinks.

  #### Parameters

  - userId: string

    The user whose entries should be erased

  - `Optional` authorization: string

    Authorization token (required when configured)

  #### Returns void

  #### Since

  0.9.0

  - Defined in utils/auditLogger.ts:341

### getLogs

- getLogs(authorization?: string): AuditLogEntry[]

  Returns a snapshot of all in-memory audit log entries, optionally filtered by the configured data-retention policy.

  When `requiredAuthToken` was set in the constructor, `authorization` must match; otherwise an `Error` is thrown.

  #### Parameters

  - `Optional` authorization: string

    Authorization token (required when configured)

  #### Returns AuditLogEntry[]

  Entries ordered oldest-first, filtered by retention policy

  #### Security

  When `requiredAuthToken` is configured, this method is access- controlled. Do not expose the returned entries through public APIs.

  #### Since

  0.8.0

  - Defined in utils/auditLogger.ts:307

### log

- log(entry: Omit<AuditLogEntry, "timestamp">): void

  Logs an audit event to the in-memory store and all configured sinks.

  Parameter values matching `sensitiveKeys` are automatically replaced by `'[REDACTED]'` before storage.

  #### Parameters

  - entry: Omit<AuditLogEntry, "timestamp">

    Audit log entry without a timestamp (generated automatically)

  #### Returns void

  #### Security

  Writes to sinks only (not stdout, which is reserved for MCP). Per ISMS Policy AU-002, all MCP tool calls must be audit-logged.

  #### Since

  0.8.0

  - Defined in utils/auditLogger.ts:197

### logDataAccess

- logDataAccess(
  action: string,
  params: Record<string, unknown>,
  count: number,
  duration?: number,
  ): void

  Logs a successful data-access event (e.g. a query returning records).

  #### Parameters

  - action: string

    Action name (e.g. `'get_meps'`, `'get_committee_meetings'`)

  - params: Record<string, unknown>

    Query parameters (sanitised automatically)

  - count: number

    Number of records returned

  - `Optional` duration: number

    Optional wall-clock duration in milliseconds

  #### Returns void

  #### Since

  0.8.0

  - Defined in utils/auditLogger.ts:256

### logError

- logError(
  action: string,
  params: Record<string, unknown>,
  error: string,
  duration?: number,
  ): void

  Logs a failed operation as an audit error event.

  #### Parameters

  - action: string

    Action name

  - params: Record<string, unknown>

    Parameters supplied to the failed operation (sanitised)

  - error: string

    Human-readable error message (must not contain secrets)

  - `Optional` duration: number

    Optional wall-clock duration in milliseconds

  #### Returns void

  #### Since

  0.8.0

  - Defined in utils/auditLogger.ts:279

### logToolCall

- logToolCall(
  toolName: string,
  params: Record<string, unknown>,
  success: boolean,
  duration?: number,
  error?: string,
  ): void

  Log an MCP tool call as an audit record.

  The tool's `params` are sanitised before being wrapped in the entry so that PII in top-level tool parameter keys is redacted. Nested objects are not recursively sanitised.

  #### Parameters

  - toolName: string

    Name of the MCP tool that was invoked

  - params: Record<string, unknown>

    Tool input parameters (sanitised automatically)

  - success: boolean

    Whether the tool call completed without error

  - `Optional` duration: number

    Optional wall-clock duration in milliseconds

  - `Optional` error: string

    Optional error message if the call failed

  #### Returns void

  #### Since

  0.8.0

  - Defined in utils/auditLogger.ts:228

### `Private` pruneExpiredEntries

- pruneExpiredEntries(policy: RetentionPolicy): void

  #### Parameters

  - policy: RetentionPolicy

  #### Returns void

  - Defined in utils/auditLogger.ts:371

### queryLogs

- queryLogs(filter: AuditFilter, authorization?: string): AuditLogEntry[]

  Queries the in-memory log using a filter.

  #### Parameters

  - filter: AuditFilter

    Field-based filter to apply

  - `Optional` authorization: string

    Authorization token (required when configured)

  #### Returns AuditLogEntry[]

  #### Since

  0.9.0

  - Defined in utils/auditLogger.ts:322

### `Private` writeSinks

- writeSinks(entry: AuditLogEntry): void

  #### Parameters

  - entry: AuditLogEntry

  #### Returns void

  - Defined in utils/auditLogger.ts:385

### `Private` `Static` buildRetentionPolicy

- buildRetentionPolicy(
  retentionMs: number | undefined,
  ): RetentionPolicy | undefined

  #### Parameters

  - retentionMs: number | undefined

  #### Returns RetentionPolicy | undefined

  - Defined in utils/auditLogger.ts:169