@mcp-audit-gateway/core 0.1.0

package/src/telemetry/metrics.ts

@@ -0,0 +1,83 @@
+import { metrics, ValueType } from "@opentelemetry/api";
+import type { Counter, Histogram, Gauge, Meter } from "@opentelemetry/api";
+import type { TelemetryConfig } from "../types.js";
+
+const METER_NAME = "mcp-audit-gateway";
+
+export interface MetricLabels {
+  toolCall: { namespace: string; tool: string; principal: string; success: string };
+  duration: { namespace: string; upstream: string };
+  upstreamStatus: { upstream: string; status: string };
+  policyDenial: { principal: string; tool: string; reason: string };
+}
+
+export class GatewayMetrics {
+  private meter: Meter;
+  private _toolCallsTotal: Counter;
+  private _toolCallDurationMs: Histogram;
+  private _upstreamStatus: Gauge;
+  private _policyDenialsTotal: Counter;
+  private _enabled: boolean;
+
+  constructor(config: TelemetryConfig) {
+    this._enabled = config.enabled;
+    this.meter = metrics.getMeter(METER_NAME, "0.1.0");
+
+    this._toolCallsTotal = this.meter.createCounter("mcp.gateway.tool_calls_total", {
+      description: "Total number of tool calls processed by the gateway",
+      valueType: ValueType.INT,
+    });
+
+    this._toolCallDurationMs = this.meter.createHistogram("mcp.gateway.tool_call_duration_ms", {
+      description: "Duration of tool call execution in milliseconds",
+      unit: "ms",
+      valueType: ValueType.DOUBLE,
+    });
+
+    this._upstreamStatus = this.meter.createGauge("mcp.gateway.upstream_status", {
+      description: "Current status of upstream servers (1=healthy, 0=unhealthy)",
+      valueType: ValueType.INT,
+    });
+
+    this._policyDenialsTotal = this.meter.createCounter("mcp.gateway.policy_denials_total", {
+      description: "Total number of policy denials",
+      valueType: ValueType.INT,
+    });
+  }
+
+  recordToolCall(labels: MetricLabels["toolCall"]): void {
+    if (!this._enabled) return;
+    this._toolCallsTotal.add(1, labels);
+  }
+
+  recordDuration(durationMs: number, labels: MetricLabels["duration"]): void {
+    if (!this._enabled) return;
+    this._toolCallDurationMs.record(durationMs, labels);
+  }
+
+  setUpstreamStatus(upstream: string, status: string, value: number): void {
+    if (!this._enabled) return;
+    this._upstreamStatus.record(value, { upstream, status });
+  }
+
+  recordPolicyDenial(labels: MetricLabels["policyDenial"]): void {
+    if (!this._enabled) return;
+    this._policyDenialsTotal.add(1, labels);
+  }
+
+  get toolCallsTotal(): Counter {
+    return this._toolCallsTotal;
+  }
+
+  get toolCallDurationMs(): Histogram {
+    return this._toolCallDurationMs;
+  }
+
+  get upstreamStatus(): Gauge {
+    return this._upstreamStatus;
+  }
+
+  get policyDenialsTotal(): Counter {
+    return this._policyDenialsTotal;
+  }
+}

package/src/telemetry/tracer.ts

@@ -0,0 +1,90 @@
+import { trace, context, SpanKind, SpanStatusCode, propagation, INVALID_SPAN_CONTEXT } from "@opentelemetry/api";
+import type { Span, Tracer, SpanContext } from "@opentelemetry/api";
+import type { TelemetryConfig } from "../types.js";
+
+const NOOP_SPAN: Span = {
+  spanContext(): SpanContext { return INVALID_SPAN_CONTEXT; },
+  setAttribute() { return this; },
+  setAttributes() { return this; },
+  addEvent() { return this; },
+  addLink() { return this; },
+  addLinks() { return this; },
+  setStatus() { return this; },
+  updateName() { return this; },
+  end() {},
+  isRecording() { return false; },
+  recordException() {},
+};
+
+const TRACER_NAME = "mcp-audit-gateway";
+
+export class GatewayTracer {
+  private tracer: Tracer;
+
+  constructor(private config: TelemetryConfig) {
+    this.tracer = trace.getTracer(TRACER_NAME, "0.1.0");
+  }
+
+  startRouteSpan(
+    method: string,
+    toolName: string | undefined,
+    upstream: string,
+    traceContext?: { traceparent?: string; tracestate?: string },
+  ): Span {
+    if (!this.config.enabled) return NOOP_SPAN;
+
+    const spanName = toolName
+      ? `mcp.gateway/route ${upstream}`
+      : `mcp.${method}`;
+
+    const parentContext = traceContext?.traceparent
+      ? this.extractContext(traceContext)
+      : context.active();
+
+    const span = this.tracer.startSpan(
+      spanName,
+      {
+        kind: SpanKind.INTERNAL,
+        attributes: {
+          "mcp.method": method,
+          "mcp.gateway.name": this.config.serviceName,
+          "mcp.gateway.route.target": upstream,
+        },
+      },
+      parentContext,
+    );
+
+    if (toolName) {
+      span.setAttribute("mcp.tool.name", toolName);
+    }
+
+    return span;
+  }
+
+  endSpan(span: Span, success: boolean, errorCode?: number): void {
+    if (!success) {
+      span.setStatus({ code: SpanStatusCode.ERROR });
+      if (errorCode != null) {
+        span.setAttribute("mcp.error.code", errorCode);
+      }
+    }
+    span.end();
+  }
+
+  recordDuration(span: Span, durationMs: number): void {
+    span.setAttribute("mcp.duration_ms", durationMs);
+  }
+
+  getTraceParent(span: Span): string {
+    const spanContext = span.spanContext();
+    const flags = spanContext.traceFlags.toString(16).padStart(2, "0");
+    return `00-${spanContext.traceId}-${spanContext.spanId}-${flags}`;
+  }
+
+  private extractContext(traceContext: { traceparent?: string; tracestate?: string }) {
+    const carrier: Record<string, string> = {};
+    if (traceContext.traceparent) carrier["traceparent"] = traceContext.traceparent;
+    if (traceContext.tracestate) carrier["tracestate"] = traceContext.tracestate;
+    return propagation.extract(context.active(), carrier);
+  }
+}

package/src/types.ts

@@ -0,0 +1,113 @@
+import { z } from "zod";
+
+export const UpstreamConfigSchema = z.object({
+  name: z.string(),
+  namespace: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/),
+  transport: z.discriminatedUnion("type", [
+    z.object({
+      type: z.literal("stdio"),
+      command: z.string(),
+      args: z.array(z.string()).optional(),
+      env: z.record(z.string()).optional(),
+    }),
+    z.object({
+      type: z.literal("streamable-http"),
+      url: z.string().url(),
+      headers: z.record(z.string()).optional(),
+    }),
+  ]),
+  healthCheckIntervalMs: z.number().positive().optional(),
+});
+
+export const PolicyRuleSchema = z.object({
+  effect: z.enum(["allow", "deny"]),
+  principals: z.array(z.string()).optional(),
+  tools: z.array(z.string()).optional(),
+  namespaces: z.array(z.string()).optional(),
+  rateLimit: z
+    .object({
+      maxPerMinute: z.number().positive().optional(),
+      maxPerHour: z.number().positive().optional(),
+    })
+    .optional(),
+});
+
+export const AttestationConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  algorithm: z.enum(["ed25519", "hmac-sha256"]).default("ed25519"),
+  keyPath: z.string().optional(),
+  secret: z.string().optional(),
+  includeParams: z.boolean().optional().default(false),
+  includeResult: z.boolean().optional().default(false),
+});
+
+export const TelemetryConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  exporterEndpoint: z.string().url().optional(),
+  serviceName: z.string().default("mcp-audit-gateway"),
+  sampleRate: z.number().min(0).max(1).default(1.0),
+});
+
+export const GatewayConfigSchema = z.object({
+  name: z.string().default("mcp-audit-gateway"),
+  version: z.string().default("0.1.0"),
+  listen: z.object({
+    transport: z.enum(["stdio", "streamable-http"]).default("streamable-http"),
+    port: z.number().positive().default(3100),
+    host: z.string().default("127.0.0.1"),
+    principalHeader: z.string().optional(),
+  }).default({}),
+  upstreams: z.array(UpstreamConfigSchema).min(1),
+  policy: z.object({
+    defaultEffect: z.enum(["allow", "deny"]).default("allow"),
+    rules: z.array(PolicyRuleSchema).default([]),
+  }).default({}),
+  attestation: AttestationConfigSchema.default({}),
+  telemetry: TelemetryConfigSchema.default({}),
+  auditLog: z.object({
+    enabled: z.boolean().default(true),
+    path: z.string().default("./audit.jsonl"),
+    rotateAfterMb: z.number().positive().default(100),
+  }).default({}),
+});
+
+export type UpstreamConfig = z.infer<typeof UpstreamConfigSchema>;
+export type PolicyRule = z.infer<typeof PolicyRuleSchema>;
+export type AttestationConfig = z.infer<typeof AttestationConfigSchema>;
+export type TelemetryConfig = z.infer<typeof TelemetryConfigSchema>;
+export type GatewayConfig = z.infer<typeof GatewayConfigSchema>;
+
+export interface UpstreamStatus {
+  name: string;
+  namespace: string;
+  status: "healthy" | "degraded" | "unavailable" | "cooldown";
+  toolCount: number;
+  lastSuccessfulContact: string | null;
+  degradedReason?: string;
+  unavailableReason?: string;
+}
+
+export interface AuditRecord {
+  id: string;
+  timestamp: string;
+  method: string;
+  toolName?: string;
+  namespace?: string;
+  upstream?: string;
+  principal?: string;
+  durationMs: number;
+  success: boolean;
+  errorCode?: number;
+  previousHash?: string;
+  attestation?: string;
+}
+
+export interface ToolEntry {
+  name: string;
+  originalName: string;
+  namespace: string;
+  upstream: string;
+  description?: string;
+  inputSchema?: unknown;
+  annotations?: Record<string, unknown>;
+}

package/src/wrap/proxy.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { spawn } from "node:child_process";
+import { readFile, rm, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const AUDIT_DIR = join(homedir(), ".mcp-audit");
+const LOG_PATH = join(AUDIT_DIR, "audit.jsonl");
+const CLI_PATH = join(import.meta.dirname, "../../dist/cli.js");
+
+function sendJsonRpc(proc: ReturnType<typeof spawn>, msg: object) {
+  proc.stdin!.write(JSON.stringify(msg) + "\n");
+}
+
+function collectLines(proc: ReturnType<typeof spawn>): Promise<string[]> {
+  return new Promise((resolve) => {
+    const lines: string[] = [];
+    proc.stdout!.on("data", (chunk) => {
+      const parts = chunk.toString().split("\n").filter((l: string) => l.trim());
+      lines.push(...parts);
+    });
+    proc.on("close", () => resolve(lines));
+  });
+}
+
+describe("wrap proxy", () => {
+  let originalLog: string | null = null;
+
+  beforeEach(async () => {
+    await mkdir(AUDIT_DIR, { recursive: true });
+    try {
+      originalLog = await readFile(LOG_PATH, "utf-8");
+    } catch {
+      originalLog = null;
+    }
+  });
+
+  afterEach(async () => {
+    if (originalLog !== null) {
+      const { writeFile } = await import("node:fs/promises");
+      await writeFile(LOG_PATH, originalLog);
+    } else {
+      try { await rm(LOG_PATH); } catch {}
+    }
+  });
+
+  it("forwards non-tool messages transparently", async () => {
+    const proc = spawn("node", [CLI_PATH, "wrap", "--", "node", "-e", `
+      process.stdin.setEncoding('utf-8');
+      let buf = '';
+      process.stdin.on('data', d => {
+        buf += d;
+        const lines = buf.split('\\n');
+        buf = lines.pop();
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          const req = JSON.parse(line);
+          if (req.method === 'initialize') {
+            process.stdout.write(JSON.stringify({jsonrpc:'2.0',id:req.id,result:{capabilities:{tools:{}}}}) + '\\n');
+          } else if (req.method === 'resources/list') {
+            process.stdout.write(JSON.stringify({jsonrpc:'2.0',id:req.id,result:{resources:[]}}) + '\\n');
+          }
+        }
+      });
+    `], { stdio: ["pipe", "pipe", "pipe"] });
+
+    const lines = collectLines(proc);
+
+    sendJsonRpc(proc, { jsonrpc: "2.0", id: 1, method: "initialize", params: {} });
+    sendJsonRpc(proc, { jsonrpc: "2.0", id: 2, method: "resources/list", params: {} });
+
+    await new Promise((r) => setTimeout(r, 500));
+    proc.stdin!.end();
+
+    const output = await lines;
+    const parsed = output.map((l) => JSON.parse(l));
+
+    expect(parsed).toHaveLength(2);
+    expect(parsed[0].id).toBe(1);
+    expect(parsed[0].result.capabilities).toBeDefined();
+    expect(parsed[1].id).toBe(2);
+    expect(parsed[1].result.resources).toBeDefined();
+  });
+
+  it("logs tool calls with attestation", async () => {
+    const proc = spawn("node", [CLI_PATH, "wrap", "--", "node", "-e", `
+      process.stdin.setEncoding('utf-8');
+      let buf = '';
+      process.stdin.on('data', d => {
+        buf += d;
+        const lines = buf.split('\\n');
+        buf = lines.pop();
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          const req = JSON.parse(line);
+          if (req.method === 'tools/call') {
+            process.stdout.write(JSON.stringify({
+              jsonrpc:'2.0', id:req.id,
+              result:{content:[{type:'text',text:'done'}]}
+            }) + '\\n');
+          }
+        }
+      });
+    `], { stdio: ["pipe", "pipe", "pipe"] });
+
+    const lines = collectLines(proc);
+
+    sendJsonRpc(proc, {
+      jsonrpc: "2.0", id: 1, method: "tools/call",
+      params: { name: "fs/read_file", arguments: { path: "/tmp/test" } },
+    });
+
+    await new Promise((r) => setTimeout(r, 500));
+    proc.stdin!.end();
+
+    const output = await lines;
+    expect(output.length).toBeGreaterThanOrEqual(1);
+
+    const response = JSON.parse(output[0]);
+    expect(response.result.content[0].text).toBe("done");
+
+    await new Promise((r) => setTimeout(r, 200));
+    const logContent = await readFile(LOG_PATH, "utf-8");
+    const logLines = logContent.trimEnd().split("\n");
+    const lastEntry = JSON.parse(logLines[logLines.length - 1]);
+
+    expect(lastEntry.toolName).toBe("fs/read_file");
+    expect(lastEntry.success).toBe(true);
+    expect(lastEntry.attestation).toBeDefined();
+    expect(lastEntry.attestation.length).toBe(64);
+    expect(lastEntry.previousHash).toBeDefined();
+  });
+
+  it("maintains hash chain across calls", async () => {
+    const proc = spawn("node", [CLI_PATH, "wrap", "--", "node", "-e", `
+      process.stdin.setEncoding('utf-8');
+      let buf = '';
+      process.stdin.on('data', d => {
+        buf += d;
+        const lines = buf.split('\\n');
+        buf = lines.pop();
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          const req = JSON.parse(line);
+          if (req.method === 'tools/call') {
+            process.stdout.write(JSON.stringify({
+              jsonrpc:'2.0', id:req.id,
+              result:{content:[{type:'text',text:'ok'}]}
+            }) + '\\n');
+          }
+        }
+      });
+    `], { stdio: ["pipe", "pipe", "pipe"] });
+
+    collectLines(proc);
+
+    sendJsonRpc(proc, { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "tool_a", arguments: {} } });
+    await new Promise((r) => setTimeout(r, 300));
+    sendJsonRpc(proc, { jsonrpc: "2.0", id: 2, method: "tools/call", params: { name: "tool_b", arguments: {} } });
+    await new Promise((r) => setTimeout(r, 300));
+    sendJsonRpc(proc, { jsonrpc: "2.0", id: 3, method: "tools/call", params: { name: "tool_c", arguments: {} } });
+
+    await new Promise((r) => setTimeout(r, 500));
+    proc.stdin!.end();
+    await new Promise((r) => setTimeout(r, 200));
+
+    const logContent = await readFile(LOG_PATH, "utf-8");
+    const logLines = logContent.trimEnd().split("\n");
+    const entries = logLines.slice(-3).map((l) => JSON.parse(l));
+
+    expect(entries[0].previousHash).toBeDefined();
+    expect(entries[1].previousHash).not.toBe(entries[0].previousHash);
+    expect(entries[2].previousHash).not.toBe(entries[1].previousHash);
+  });
+});

package/src/wrap/proxy.ts

@@ -0,0 +1,192 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { createInterface } from "node:readline";
+import { appendFile, mkdir, readFile, stat } from "node:fs/promises";
+import { createHmac, randomBytes, createHash, timingSafeEqual } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+interface AuditEntry {
+  id: string;
+  timestamp: string;
+  method: string;
+  toolName: string;
+  namespace: null;
+  upstream: null;
+  principal: null;
+  args: Record<string, unknown>;
+  durationMs: number;
+  success: boolean;
+  errorCode: null;
+  previousHash: string;
+  attestation: string;
+}
+
+interface PendingCall {
+  toolName: string;
+  args: Record<string, unknown>;
+  startTime: number;
+}
+
+export async function runWrapProxy(command: string, args: string[]): Promise<void> {
+  const auditDir = join(homedir(), ".mcp-audit");
+  await mkdir(auditDir, { recursive: true });
+
+  const keyPath = join(auditDir, "key.hex");
+  const logPath = join(auditDir, "audit.jsonl");
+  const secret = await ensureKey(keyPath);
+
+  let lastHash = await restoreLastHash(logPath);
+  let writeQueue: Promise<void> = Promise.resolve();
+  const pending = new Map<string | number, PendingCall>();
+
+  const child = spawn(command, args, {
+    stdio: ["pipe", "pipe", "inherit"],
+    env: process.env,
+  });
+
+  child.on("error", (err) => {
+    process.stderr.write(`[mcp-audit] failed to spawn: ${err.message}\n`);
+    process.exit(1);
+  });
+
+  child.on("exit", (code) => {
+    process.exit(code ?? 0);
+  });
+
+  const clientRl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+  const serverRl = createInterface({ input: child.stdout!, crlfDelay: Infinity });
+
+  clientRl.on("line", (line) => {
+    if (!line.trim()) return;
+    try {
+      const msg = JSON.parse(line);
+      if (msg.method === "tools/call" && msg.id !== undefined) {
+        pending.set(msg.id, {
+          toolName: msg.params?.name ?? "unknown",
+          args: msg.params?.arguments ?? {},
+          startTime: Date.now(),
+        });
+      }
+    } catch {}
+    child.stdin!.write(line + "\n");
+  });
+
+  serverRl.on("line", (line) => {
+    if (!line.trim()) return;
+
+    process.stdout.write(line + "\n");
+
+    let msg: any;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return;
+    }
+
+    if (msg.id !== undefined && pending.has(msg.id)) {
+      const call = pending.get(msg.id)!;
+      pending.delete(msg.id);
+
+      const durationMs = Date.now() - call.startTime;
+      const success = !msg.error;
+
+      writeQueue = writeQueue.then(async () => {
+        try {
+          const entry = createEntry(call.toolName, call.args, durationMs, success, lastHash);
+          const signed = sign(entry, secret);
+          lastHash = hashEntry(signed);
+          await appendFile(logPath, JSON.stringify(signed) + "\n");
+        } catch (err) {
+          process.stderr.write(`[mcp-audit] log write failed: ${err}\n`);
+        }
+      });
+    }
+  });
+
+  clientRl.on("close", () => {
+    child.stdin!.end();
+  });
+
+  process.on("SIGINT", () => {
+    child.kill("SIGINT");
+  });
+
+  process.on("SIGTERM", () => {
+    child.kill("SIGTERM");
+  });
+}
+
+function createEntry(
+  toolName: string,
+  args: Record<string, unknown>,
+  durationMs: number,
+  success: boolean,
+  previousHash: string,
+): Omit<AuditEntry, "attestation"> {
+  return {
+    id: crypto.randomUUID(),
+    timestamp: new Date().toISOString(),
+    method: "tools/call",
+    toolName,
+    namespace: null,
+    upstream: null,
+    principal: null,
+    args,
+    durationMs,
+    success,
+    errorCode: null,
+    previousHash,
+  };
+}
+
+function sign(entry: Omit<AuditEntry, "attestation">, secret: Buffer): AuditEntry {
+  const canonical = JSON.stringify([
+    ["id", entry.id],
+    ["timestamp", entry.timestamp],
+    ["method", entry.method],
+    ["toolName", entry.toolName],
+    ["namespace", null],
+    ["upstream", null],
+    ["principal", null],
+    ["durationMs", entry.durationMs],
+    ["success", entry.success],
+    ["errorCode", null],
+    ["previousHash", entry.previousHash],
+  ]);
+  const hmac = createHmac("sha256", secret);
+  hmac.update(canonical);
+  const attestation = hmac.digest("hex");
+  return { ...entry, attestation };
+}
+
+function hashEntry(entry: AuditEntry): string {
+  return createHash("sha256").update(JSON.stringify(entry)).digest("hex");
+}
+
+async function ensureKey(keyPath: string): Promise<Buffer> {
+  try {
+    const hex = await readFile(keyPath, "utf-8");
+    return Buffer.from(hex.trim(), "hex");
+  } catch {
+    const key = randomBytes(32);
+    await appendFile(keyPath, key.toString("hex") + "\n");
+    process.stderr.write(`[mcp-audit] generated signing key: ${keyPath}\n`);
+    return key;
+  }
+}
+
+async function restoreLastHash(logPath: string): Promise<string> {
+  try {
+    const s = await stat(logPath);
+    if (s.size === 0) return "genesis";
+    const content = await readFile(logPath, "utf-8");
+    const lines = content.trimEnd().split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+      try {
+        const entry: AuditEntry = JSON.parse(lines[i]);
+        return hashEntry(entry);
+      } catch {}
+    }
+  } catch {}
+  return "genesis";
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}