Audit Logging
Relevant source files
The following files were used as context for generating this wiki page:
Audit Logging records every action taken by AI agents through the Model Context Protocol (MCP) server. This system provides a transparent trail of tool executions, including read, search, and management actions across connected email and calendar accounts. The audit trail ensures security and accountability by tracking agent identity, specific actions, targets, and success statuses.
Sources: README.md:14-14, src/routes/audit.tsx:28-28, AGENTS.md:55-55
Database Schema
The system stores audit data in a Cloudflare D1 (SQLite) table named audit_logs. This table captures high-level metadata about each event without storing sensitive content such as draft bodies or raw email text.
Audit Log Data Model
| Field | Type | Description |
|---|---|---|
id | INTEGER | Primary key, auto-incremented. |
client_id | TEXT | Unique identifier of the MCP agent/client. |
client_name | TEXT | Human-readable name of the agent. |
action | TEXT | Name of the tool or action executed (e.g., read_recent_emails). |
target | TEXT | The resource acted upon, typically in account:ID format. |
details | TEXT | Additional context or parameters of the action. |
success | INTEGER | Boolean flag (1 for success, 0 for failure). |
error_message | TEXT | Captures the exception message if the action failed. |
created_at | TEXT | ISO timestamp of the event (default: datetime('now')). |
Sources: migrations/0004_audit_logs.sql:2-12, src/mcp/tools.ts:47-66
The database includes indexes on client_id, action, and created_at to optimize log retrieval and filtering in the management UI.
Sources: migrations/0004_audit_logs.sql:14-16
Logging Logic and Data Flow
Audit logging occurs within the MCP tool implementation layer. Every tool execution must call the logAudit function regardless of whether the operation succeeds or fails.
The logAudit Function
The logAudit function handles the insertion of log entries into the D1 database. It is designed to be non-blocking; if the logging attempt itself fails, it catches the error and logs to the console to prevent disrupting the primary tool execution.
Sources: src/mcp/tools.ts:47-68
Sequence of Logging
The following diagram illustrates the lifecycle of an audited tool call:
Explanation: The MCP server executes tool logic which triggers a database write to the audit log table before returning the final response to the agent.
Sources: src/mcp/server.ts:89-130, src/mcp/tools.ts:47-66
Security and Privacy Constraints
Audit logging follows specific privacy rules to protect sensitive user data while maintaining accountability:
- No Sensitive Content: Tools like
draft_email_replylog the action and the target message ID, but they specifically omit the draft body from thedetailsfield. - Sanitized Metadata: Calendar event reads are audited for success or failure, but the actual event content is excluded.
- Error Capturing: When a tool fails (e.g., due to a 401 Unauthorized or 403 Forbidden error from the provider), the system logs the specific error message to the
error_messagecolumn.
Sources: README.md:65-66, README.md:75-76, src/mcp/server.ts:133-144
Audit Management UI
The project includes a web interface for administrators to review the audit trail. This UI is served via the /audit route and provides a paginated table of events.
UI Features
- Pagination: Results are displayed in pages of 25 events.
- Status Indicators: Successes are marked with a green checkmark (✅), while failures display a red cross (❌) with the error message as a tooltip.
- Dynamic Identification: The "Agent" column displays the
client_nameif available, falling back to theclient_id. - Timestamping: Timestamps are localized using the user's browser settings via
toLocaleString().
Sources: src/routes/audit.tsx:11-82
Explanation: The audit route retrieves records from the database, applies pagination based on query parameters, and renders the log entries into a standard layout.
Sources: src/routes/audit.tsx:15-62
Summary
Audit Logging serves as a critical security layer for the e-zer0 project by recording all AI-initiated interactions with email and calendar resources. By persisting these events to the Cloudflare D1 database and exposing them through a secure administrative dashboard, the system ensures that every action taken by an autonomous or assisted agent is traceable and verifiable without compromising the actual content of the communications.