Skip to content
reaatech

@reaatech/mcp-gateway-audit

npm v1.1.0

A structured audit logging library for the MCP Gateway that captures security-relevant events with configurable severity, multiple storage backends (console, file, in-memory), tamper-evident SHA-256 chaining, and a query API. Provides logger classes and event creation utilities for compliance audit trails.

npm →source →

@reaatech/mcp-gateway-audit

npm version License: MIT CI

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

Compliance audit trail logging for the MCP Gateway. Captures security-relevant events with structured JSON output, supports multiple storage backends, tamper-evident chaining, and query capabilities.

Installation

terminal
npm install @reaatech/mcp-gateway-audit
# or
pnpm add @reaatech/mcp-gateway-audit

Feature Overview

  • 8 event types — auth.success, auth.failure, rate_limit.exceeded, allowlist.denied, tool.executed, cache.hit, cache.miss, upstream.error
  • Configurable severity — low, medium, high per event type
  • Three storage backends — console (stdout), file (JSONL), and in-memory (queryable)
  • Composite logging — fan out to multiple backends simultaneously
  • Tamper-evident mode — SHA-256 chaining for integrity verification
  • Query API — filter by tenant, event type, date range, limit, and success/failure
  • Dual ESM/CJS output — works with import and require

Quick Start

typescript
import {
  createAuditEvent,
  ConsoleAuditLogger,
  FileAuditLogger,
} from "@reaatech/mcp-gateway-audit";
 
// Console logger (development)
const consoleLogger = new ConsoleAuditLogger();
consoleLogger.log(createAuditEvent("tool.executed", {
  requestId: "req-abc123",
  tenantId: "acme-corp",
  userId: "user-456",
  tool: "glean_search",
  success: true,
  durationMs: 234,
}));
 
// File logger (production)
const fileLogger = new FileAuditLogger({ path: "/var/log/gateway/audit.json" });
fileLogger.log(createAuditEvent("auth.failure", {
  requestId: "req-def789",
  metadata: { reason: "invalid_token" },
}));

API Reference

Event Creation

ExportDescription
createAuditEvent(type, data?)Create a typed audit event with auto-generated ID, timestamp, and severity

Loggers

ExportDescription
ConsoleAuditLoggerWrites JSON events to console.log
FileAuditLoggerAppends JSONL events to a file
CompositeAuditLoggerFans out to multiple logger backends
TamperEvidentLoggerWraps a logger with SHA-256 chain integrity
AuditLoggerType alias for the logger interface

Storage

ExportDescription
MemoryAuditStorageIn-memory store with query capabilities
FileAuditStorageFile-based store with append and query
createAuditQueryService(store)Create a query service over any storage backend

Integrity

ExportDescription
computeEventHash(event)Compute SHA-256 hash of an event
verifyAuditChain(events)Verify the tamper-evident chain of events

Event Types

ExportDescription
getEventTypeConfig(type)Get metadata for an event type
getEventSeverity(type)Get severity for an event type
EVENT_TYPE_CONFIGSMap of all event type configurations

Event Types Reference

Event TypeSeverityDescription
auth.successlowSuccessful authentication
auth.failuremediumFailed authentication attempt
rate_limit.exceededmediumRate limit exceeded
allowlist.deniedhighTool access denied by allowlist
tool.executedlowTool execution completed
cache.hitlowCache served the response
cache.misslowCache miss — upstream was called
upstream.errorhighUpstream server returned an error

Types

TypeDescription
AuditEvent{ id, timestamp, eventType, severity, tenantId?, userId?, requestId?, tool?, success?, durationMs?, cacheHit?, upstream?, metadata? }
AuditEventTypeString union of all event types
AuditSeveritylow' | 'medium' | 'high
AuditStorageTypememory' | 'file
AuditQueryParams{ tenantId?, eventType?, startDate?, endDate?, limit?, success?, offset? }

Audit Log Format

json
{
  "id": "evt-abc123",
  "timestamp": "2026-04-15T23:00:00Z",
  "eventType": "tool.executed",
  "severity": "low",
  "tenantId": "acme-corp",
  "userId": "user-123",
  "requestId": "req-abc123",
  "tool": "glean_search",
  "success": true,
  "durationMs": 234,
  "cacheHit": false,
  "upstream": "primary"
}

Usage Patterns

Composite logging (console + file)

typescript
import { ConsoleAuditLogger, FileAuditLogger, CompositeAuditLogger } from "@reaatech/mcp-gateway-audit";
 
const logger = new CompositeAuditLogger([
  new ConsoleAuditLogger(),
  new FileAuditLogger({ path: "/var/log/gateway/audit.json" }),
]);
 
logger.log(createAuditEvent("auth.success", { tenantId: "acme-corp" }));
// → Written to both console and file

Tamper-evident audit chain

typescript
import { FileAuditLogger, TamperEvidentLogger, verifyAuditChain } from "@reaatech/mcp-gateway-audit";
 
const baseLogger = new FileAuditLogger({ path: "./audit.json" });
const logger = new TamperEvidentLogger(baseLogger);
 
// Log events — each gets a chain hash referencing the previous event
logger.log(createAuditEvent("tool.executed", { tool: "glean_search" }));
logger.log(createAuditEvent("tool.executed", { tool: "serval_query" }));
 
// Verify integrity later
const events = loadAuditLog("./audit.json");
const result = verifyAuditChain(events);
console.log(result.valid, result.errors);

Querying audit logs

typescript
import { MemoryAuditStorage, createAuditQueryService } from "@reaatech/mcp-gateway-audit";
 
const storage = new MemoryAuditStorage();
const query = createAuditQueryService(storage);
 
const results = query({
  tenantId: "acme-corp",
  eventType: "auth.failure",
  startDate: new Date("2026-01-01"),
  limit: 50,
});
 
console.log(`Found ${results.total} auth failures for acme-corp`);

Fastify

Recording is framework-agnostic (recordAudit(ctx, decision, options)). Both the Express middleware (auditMiddleware) and the Fastify plugin write through the same core, and both default to a silent sink — nothing is written to stdout (reserved for the MCP JSON-RPC stream) unless you supply a logger.

typescript
import Fastify from "fastify";
import { fastifyAuth } from "@reaatech/mcp-gateway-auth/fastify";
import { ConsoleAuditLogger } from "@reaatech/mcp-gateway-audit";
import { fastifyAudit } from "@reaatech/mcp-gateway-audit/fastify";
 
const app = Fastify();
 
await app.register(fastifyAuth);
await app.register(fastifyAudit, { logger: new ConsoleAuditLogger() });

Use SilentAuditLogger (the default) on hosts that forbid stdout writes, or any AuditLogger (FileAuditLogger, CompositeAuditLogger, custom). fastify is an optional peer dependency.

Registration order: auth → rate-limit → allowlist → audit → cache — register fastifyAudit after fastifyAllowlist and before fastifyCache.

Related Packages

License

MIT

All packagesmcp-gateway overview