Skip to main content
Dotset CLI API Documentation / tollgate / AuditLogger

Class: AuditLogger

Defined in: src/tollgate/audit/logger.ts:73 AuditLogger records all tool calls and session grants to SQLite. Uses WAL mode for concurrent access and prepared statements for performance.

Example

const logger = new AuditLogger();

// Log a tool call attempt
const id = logger.logAttempt(context, decision);

// Later, log the result
logger.logResult(id, 'approved', 'success', undefined, 150);

// Log a session grant
logger.logSessionGrant(grant);

Constructors

Constructor

new AuditLogger(optionsOrPath?): AuditLogger;
Defined in: src/tollgate/audit/logger.ts:91

Parameters

optionsOrPath?
string | AuditLoggerOptions

Returns

AuditLogger

Methods

close()

close(): void;
Defined in: src/tollgate/audit/logger.ts:602 Closes the database connection.

Returns

void

getActiveSessionGrants()

getActiveSessionGrants(server?): SessionGrantRecord[];
Defined in: src/tollgate/audit/logger.ts:482 Gets active session grants for a server.

Parameters

server?
string Server name to filter by (optional)

Returns

SessionGrantRecord[] Array of active grants

getRecentCalls()

getRecentCalls(limitOrOptions): AuditRecord[];
Defined in: src/tollgate/audit/logger.ts:378 Gets recent tool calls with optional filtering.

Parameters

limitOrOptions
number | { includeRedacted?: boolean; limit?: number; riskLevel?: AuditRiskLevel; server?: string; since?: Date; until?: Date; }

Returns

AuditRecord[]

getSessionStats()

getSessionStats(): {
  activeGrants: number;
  expiredGrants: number;
  revokedGrants: number;
  totalGrants: number;
  totalUsage: number;
};
Defined in: src/tollgate/audit/logger.ts:563 Gets session grant statistics.

Returns

{
  activeGrants: number;
  expiredGrants: number;
  revokedGrants: number;
  totalGrants: number;
  totalUsage: number;
}
activeGrants
activeGrants: number;
expiredGrants
expiredGrants: number;
revokedGrants
revokedGrants: number;
totalGrants
totalGrants: number;
totalUsage
totalUsage: number;

getStats()

getStats(): {
  allowed: number;
  denied: number;
  prompted: number;
  sessionAuthorized: number;
  total: number;
};
Defined in: src/tollgate/audit/logger.ts:526 Gets aggregate statistics for tool calls.

Returns

{
  allowed: number;
  denied: number;
  prompted: number;
  sessionAuthorized: number;
  total: number;
}
allowed
allowed: number;
denied
denied: number;
prompted
prompted: number;
sessionAuthorized
sessionAuthorized: number;
total
total: number;

logAttempt()

logAttempt(
   context, 
   decision, 
   sessionGrantId?, 
   metadata?): string;
Defined in: src/tollgate/audit/logger.ts:244 Logs a tool call attempt.

Parameters

context
The tool call context
decision
The policy decision
sessionGrantId?
string ID of session grant that authorized this call (if any)
metadata?
Additional metadata for the audit record
clientId?
string
correlationId?
string

Returns

string The generated audit record ID

logResult()

logResult(
   id, 
   userDecision, 
   result, 
   errorMessage?, 
   durationMs?): void;
Defined in: src/tollgate/audit/logger.ts:309 Updates a tool call record with the final result.

Parameters

id
string The audit record ID from logAttempt
userDecision
The user’s approval decision (if prompted) ApprovalResult | null
result
Whether the tool call succeeded or failed "error" | "success"
errorMessage?
string Error message (if result is ‘error’)
durationMs?
number Total duration of the tool call

Returns

void

logSessionGrant()

logSessionGrant(grant): void;
Defined in: src/tollgate/audit/logger.ts:334 Logs a new session grant.

Parameters

grant
The session grant to log

Returns

void

logSessionGrantUsage()

logSessionGrantUsage(grantId): void;
Defined in: src/tollgate/audit/logger.ts:352 Increments the usage count for a session grant.

Parameters

grantId
string The session grant ID

Returns

void

revokeSessionGrant()

revokeSessionGrant(grantId, revokedBy): void;
Defined in: src/tollgate/audit/logger.ts:362 Marks a session grant as revoked.

Parameters

grantId
string The session grant ID
revokedBy
string Who revoked it (e.g., ‘user’, ‘timeout’, ‘policy’)

Returns

void