@mcp-audit-gateway/core 0.1.0 → 0.4.0

package/src/policy/engine.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { PolicyEngine } from "./engine.js";
+import { PolicyEngine, computeDecisionContextDigest } from "./engine.js";
 import type { ToolEntry } from "../types.js";
 
 const tool = (name: string, ns: string): ToolEntry => ({
@@ -92,4 +92,50 @@ describe("PolicyEngine", () => {
       expect(filtered.map((t) => t.originalName)).not.toContain("dangerous_delete");
     });
   });
+
+  describe("decisionContext", () => {
+    const engine = new PolicyEngine("allow", [
+      { effect: "deny", principals: ["agent:readonly-*"], tools: ["*/write_*"] },
+    ]);
+
+    it("returns decision context with evaluation", () => {
+      const t = tool("write_file", "fs");
+      const result = engine.evaluate("agent:readonly-bot", t);
+      expect(result.decisionContext).toBeDefined();
+      expect(result.decisionContext.principal).toBe("agent:readonly-bot");
+      expect(result.decisionContext.toolName).toBe("fs/write_file");
+      expect(result.decisionContext.toolNamespace).toBe("fs");
+      expect(result.decisionContext.effect).toBe("deny");
+      expect(result.decisionContext.matchedRule).toEqual({
+        effect: "deny",
+        principals: ["agent:readonly-*"],
+        tools: ["*/write_*"],
+      });
+    });
+
+    it("produces stable digest for same input", () => {
+      const t = tool("write_file", "fs");
+      const r1 = engine.evaluate("agent:readonly-bot", t);
+      const r2 = engine.evaluate("agent:readonly-bot", t);
+      const d1 = computeDecisionContextDigest(r1.decisionContext);
+      const d2 = computeDecisionContextDigest(r2.decisionContext);
+      expect(d1).toBe(d2);
+      expect(d1).toHaveLength(64);
+    });
+
+    it("produces different digest for different principal", () => {
+      const t = tool("read_data", "github");
+      const r1 = engine.evaluate("agent:alpha", t);
+      const r2 = engine.evaluate("agent:beta", t);
+      const d1 = computeDecisionContextDigest(r1.decisionContext);
+      const d2 = computeDecisionContextDigest(r2.decisionContext);
+      expect(d1).not.toBe(d2);
+    });
+
+    it("includes null principal when undefined", () => {
+      const t = tool("read_data", "github");
+      const result = engine.evaluate(undefined, t);
+      expect(result.decisionContext.principal).toBeNull();
+    });
+  });
 });

package/src/policy/engine.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import type { PolicyRule, ToolEntry } from "../types.js";
 
 export interface PolicyDecision {
@@ -6,6 +7,28 @@ export interface PolicyDecision {
   rateLimit?: { maxPerMinute?: number; maxPerHour?: number };
 }
 
+export interface DecisionContext {
+  principal: string | null;
+  toolName: string;
+  toolNamespace: string;
+  toolUpstream: string;
+  matchedRule: PolicyRule | null;
+  effect: "allow" | "deny";
+}
+
+export function computeDecisionContextDigest(ctx: DecisionContext): string {
+  const ordered: [string, unknown][] = [
+    ["principal", ctx.principal],
+    ["toolName", ctx.toolName],
+    ["toolNamespace", ctx.toolNamespace],
+    ["toolUpstream", ctx.toolUpstream],
+    ["matchedRule", ctx.matchedRule],
+    ["effect", ctx.effect],
+  ];
+  const canonical = JSON.stringify(ordered);
+  return createHash("sha256").update(canonical).digest("hex");
+}
+
 interface RateLimitState {
   minuteCounts: Map<string, { count: number; resetAt: number }>;
   hourCounts: Map<string, { count: number; resetAt: number }>;
@@ -22,7 +45,7 @@ export class PolicyEngine {
     private rules: PolicyRule[],
   ) {}
 
-  evaluate(principal: string | undefined, tool: ToolEntry): PolicyDecision {
+  evaluate(principal: string | undefined, tool: ToolEntry): PolicyDecision & { decisionContext: DecisionContext } {
     let matchedRule: PolicyRule | null = null;
 
     for (const rule of this.rules) {
@@ -32,23 +55,33 @@ export class PolicyEngine {
       }
     }
 
+    const buildContext = (effect: "allow" | "deny"): DecisionContext => ({
+      principal: principal ?? null,
+      toolName: tool.name,
+      toolNamespace: tool.namespace,
+      toolUpstream: tool.upstream,
+      matchedRule,
+      effect,
+    });
+
     if (!matchedRule) {
-      return { allowed: this.defaultEffect === "allow" };
+      const allowed = this.defaultEffect === "allow";
+      return { allowed, decisionContext: buildContext(allowed ? "allow" : "deny") };
     }
 
     if (matchedRule.effect === "deny") {
-      return { allowed: false, reason: "denied by policy rule" };
+      return { allowed: false, reason: "denied by policy rule", decisionContext: buildContext("deny") };
     }
 
     if (matchedRule.rateLimit) {
       const key = `${principal ?? "anonymous"}:${tool.name}`;
       const rateLimited = this.checkRateLimit(key, matchedRule.rateLimit);
       if (rateLimited) {
-        return { allowed: false, reason: "rate limit exceeded", rateLimit: matchedRule.rateLimit };
+        return { allowed: false, reason: "rate limit exceeded", rateLimit: matchedRule.rateLimit, decisionContext: buildContext("deny") };
       }
     }
 
-    return { allowed: true, rateLimit: matchedRule.rateLimit };
+    return { allowed: true, rateLimit: matchedRule.rateLimit, decisionContext: buildContext("allow") };
   }
 
   filterTools(principal: string | undefined, tools: ToolEntry[]): ToolEntry[] {

package/src/proxy/gateway.test.ts

@@ -26,6 +26,7 @@ const testConfig: GatewayConfig = {
   attestation: { enabled: true, algorithm: "hmac-sha256", secret: "a".repeat(64), includeParams: false, includeResult: false },
   telemetry: { enabled: false, serviceName: "test", sampleRate: 0 },
   auditLog: { enabled: true, path: "/tmp/test-audit.jsonl", rotateAfterMb: 10 },
+  checkpoint: { enabled: false, intervalRecords: 100, intervalSeconds: 60, trigger: "whichever_first" as const },
 };
 
 describe("Gateway", () => {
@@ -94,6 +95,23 @@ describe("Gateway", () => {
         gateway.handleToolsCall("test/dangerous_tool", {}, "agent:blocked"),
       ).rejects.toThrow();
     });
+
+    it("includes aiInvocation context and client-asserter party", async () => {
+      const aiInvocation = { turnId: "turn-abc", invocationReason: "user asked", model: "claude-4" };
+      try {
+        await gateway.handleToolsCall("test/safe_tool", {}, "user:test", undefined, aiInvocation);
+      } catch {
+        // upstream not connected, but the record should still be created on error path
+      }
+      // The denied path gives us a record we can inspect
+      try {
+        await gateway.handleToolsCall("test/dangerous_tool", {}, "agent:blocked", undefined, aiInvocation);
+      } catch (err: unknown) {
+        const record = (err as { auditRecord: { aiInvocation?: unknown; parties?: Array<{ party: string; role: string; scope: string[] }> } }).auditRecord;
+        expect(record.aiInvocation).toEqual(aiInvocation);
+        expect(record.parties).toContainEqual({ party: "client", role: "asserter", scope: ["aiInvocation"] });
+      }
+    });
   });
 
   describe("status", () => {

package/src/proxy/gateway.ts

@@ -5,7 +5,7 @@ import type {
   ToolEntry,
   AuditRecord,
 } from "../types.js";
-import { PolicyEngine } from "../policy/engine.js";
+import { PolicyEngine, computeDecisionContextDigest } from "../policy/engine.js";
 import { AuditLog } from "../attestation/audit-log.js";
 import { createSigner } from "../attestation/signer.js";
 import { GatewayTracer } from "../telemetry/tracer.js";
@@ -97,6 +97,7 @@ export class Gateway {
     args: Record<string, unknown>,
     principal?: string,
     traceContext?: { traceparent?: string; tracestate?: string },
+    aiInvocation?: { turnId?: string; invocationReason?: string; model?: string },
   ): Promise<{ result: unknown; auditRecord: AuditRecord }> {
     const startTime = Date.now();
     const tool = this.toolCatalog.get(toolName);
@@ -113,6 +114,8 @@ export class Gateway {
     }
 
     const decision = this.policyEngine.evaluate(principal, tool);
+    const contextDigest = computeDecisionContextDigest(decision.decisionContext);
+
     if (!decision.allowed) {
       this.metrics.recordPolicyDenial({
         principal: principal ?? "anonymous",
@@ -127,6 +130,8 @@ export class Gateway {
         durationMs: Date.now() - startTime,
         success: false,
         errorCode: -32603,
+        decisionContextDigest: contextDigest,
+        aiInvocation,
       });
       throw new ToolCallError(
         -32603,
@@ -173,6 +178,8 @@ export class Gateway {
         principal,
         durationMs,
         success: true,
+        decisionContextDigest: contextDigest,
+        aiInvocation,
       });
 
       return { result, auditRecord: record };
@@ -202,6 +209,8 @@ export class Gateway {
         durationMs,
         success: false,
         errorCode: -32603,
+        decisionContextDigest: contextDigest,
+        aiInvocation,
       });
       throw new ToolCallError(-32603, "Upstream server error", record);
     }

package/src/proxy/mcp-server-adapter.test.ts

@@ -42,6 +42,7 @@ const testConfig: GatewayConfig = {
   },
   telemetry: { enabled: false, serviceName: "test", sampleRate: 0 },
   auditLog: { enabled: true, path: AUDIT_PATH, rotateAfterMb: 10 },
+  checkpoint: { enabled: false, intervalRecords: 100, intervalSeconds: 60, trigger: "whichever_first" as const },
 };
 
 describe("McpServerAdapter", () => {

package/src/proxy/mcp-server-adapter.ts

@@ -76,6 +76,7 @@ export class McpServerAdapter {
       async (request) => {
         const principal = this.extractPrincipal(request.params?._meta);
         const traceContext = this.extractTraceContext(request.params?._meta);
+        const aiInvocation = this.extractAiInvocation(request.params?._meta);
         const toolName = request.params.name;
         const args = (request.params.arguments ?? {}) as Record<string, unknown>;
 
@@ -85,6 +86,7 @@ export class McpServerAdapter {
             args,
             principal,
             traceContext,
+            aiInvocation,
           );
 
           const upstreamResult = result as {
@@ -96,6 +98,7 @@ export class McpServerAdapter {
             content: upstreamResult?.content ?? [{ type: "text" as const, text: JSON.stringify(result) }],
             isError: upstreamResult?.isError,
             _meta: {
+              ...(aiInvocation?.turnId ? { "io.modelcontextprotocol/aiInvocation": { turnId: aiInvocation.turnId } } : {}),
               "x-gateway-attestation/v1": {
                 auditId: auditRecord.id,
                 attestation: auditRecord.attestation,
@@ -109,6 +112,7 @@ export class McpServerAdapter {
               content: [{ type: "text" as const, text: err.message }],
               isError: true,
               _meta: {
+                ...(aiInvocation?.turnId ? { "io.modelcontextprotocol/aiInvocation": { turnId: aiInvocation.turnId } } : {}),
                 "x-gateway-attestation/v1": {
                   auditId: err.auditRecord.id,
                   attestation: err.auditRecord.attestation,
@@ -137,4 +141,26 @@ export class McpServerAdapter {
     const tc = meta.traceContext as { traceparent?: string; tracestate?: string } | undefined;
     return tc;
   }
+
+  private extractAiInvocation(
+    meta?: Record<string, unknown>,
+  ): { turnId?: string; invocationReason?: string; model?: string } | undefined {
+    if (!meta) return undefined;
+    const key = "io.modelcontextprotocol/aiInvocation";
+    const inv = meta[key] as Record<string, unknown> | undefined;
+    if (!inv) return undefined;
+    const result: { turnId?: string; invocationReason?: string; model?: string } = {};
+    if (typeof inv.turnId === "string") result.turnId = inv.turnId;
+    if (typeof inv.invocationReason === "string") {
+      result.invocationReason = inv.invocationReason;
+    } else if (inv.invocationReason && typeof (inv.invocationReason as Record<string, unknown>).text === "string") {
+      result.invocationReason = (inv.invocationReason as Record<string, unknown>).text as string;
+    }
+    if (typeof inv.model === "string") {
+      result.model = inv.model;
+    } else if (inv.model && typeof (inv.model as Record<string, unknown>).name === "string") {
+      result.model = (inv.model as Record<string, unknown>).name as string;
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+  }
 }

package/src/types.ts

@@ -48,6 +48,13 @@ export const TelemetryConfigSchema = z.object({
   sampleRate: z.number().min(0).max(1).default(1.0),
 });
 
+export const CheckpointConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  intervalRecords: z.number().positive().default(100),
+  intervalSeconds: z.number().positive().default(60),
+  trigger: z.enum(["records", "time", "whichever_first"]).default("whichever_first"),
+});
+
 export const GatewayConfigSchema = z.object({
   name: z.string().default("mcp-audit-gateway"),
   version: z.string().default("0.1.0"),
@@ -69,6 +76,7 @@ export const GatewayConfigSchema = z.object({
     path: z.string().default("./audit.jsonl"),
     rotateAfterMb: z.number().positive().default(100),
   }).default({}),
+  checkpoint: CheckpointConfigSchema.default({}),
 });
 
 export type UpstreamConfig = z.infer<typeof UpstreamConfigSchema>;
@@ -87,6 +95,18 @@ export interface UpstreamStatus {
   unavailableReason?: string;
 }
 
+export interface PartyAttribution {
+  party: string;
+  role: "witness" | "asserter";
+  scope: string[];
+}
+
+export interface AiInvocationContext {
+  turnId?: string;
+  invocationReason?: string;
+  model?: string;
+}
+
 export interface AuditRecord {
   id: string;
   timestamp: string;
@@ -98,10 +118,46 @@ export interface AuditRecord {
   durationMs: number;
   success: boolean;
   errorCode?: number;
+  decisionContextDigest?: string;
+  extensionsDigest?: string;
+  aiInvocation?: AiInvocationContext;
+  parties?: PartyAttribution[];
   previousHash?: string;
   attestation?: string;
 }
 
+export interface CheckpointRecord {
+  id: string;
+  type: "checkpoint";
+  timestamp: string;
+  sequence: number;
+  recordCount: number;
+  previousHash: string;
+  parties?: PartyAttribution[];
+  attestation?: string;
+}
+
+export interface ChainBreakRecord {
+  id: string;
+  type: "chain_break";
+  timestamp: string;
+  reason: string;
+  priorHead?: string;
+  priorSequence?: number;
+  priorRecordCount?: number;
+  attestation?: string;
+}
+
+export type ChainRecord = AuditRecord | CheckpointRecord | ChainBreakRecord;
+
+export function isCheckpoint(record: ChainRecord): record is CheckpointRecord {
+  return "type" in record && (record as CheckpointRecord).type === "checkpoint";
+}
+
+export function isChainBreak(record: ChainRecord): record is ChainBreakRecord {
+  return "type" in record && (record as ChainBreakRecord).type === "chain_break";
+}
+
 export interface ToolEntry {
   name: string;
   originalName: string;

package/src/wrap/proxy.test.ts

@@ -44,7 +44,7 @@ describe("wrap proxy", () => {
     }
   });
 
-  it("forwards non-tool messages transparently", async () => {
+  it.skipIf(!process.env.RUN_E2E)("forwards non-tool messages transparently", async () => {
     const proc = spawn("node", [CLI_PATH, "wrap", "--", "node", "-e", `
       process.stdin.setEncoding('utf-8');
       let buf = '';
@@ -82,7 +82,7 @@ describe("wrap proxy", () => {
     expect(parsed[1].result.resources).toBeDefined();
   });
 
-  it("logs tool calls with attestation", async () => {
+  it.skipIf(!process.env.RUN_E2E)("logs tool calls with attestation", async () => {
     const proc = spawn("node", [CLI_PATH, "wrap", "--", "node", "-e", `
       process.stdin.setEncoding('utf-8');
       let buf = '';

package/test/vectors/README.md

@@ -0,0 +1,44 @@
+# Conformance Vectors
+
+Cross-implementation verification fixtures for mcp-audit-gateway's canonicalization and hash chain.
+
+## Two hash operations, two guarantees
+
+This implementation uses two distinct hash operations for different purposes:
+
+**Canonical hash (signing):** SHA-256 of a tuple-array serialization with a fixed 11-field order. The attestation field is excluded (it cannot sign itself). This form is cross-language reproducible — any implementation that follows the field order and null rule will produce identical bytes.
+
+**Chain hash (linking):** SHA-256 of `JSON.stringify(fullRecord)` including the attestation field. This binds the signature into the chain sequence. It depends on JavaScript insertion order and is JS-authoritative — other languages must serialize keys in the documented order to verify.
+
+## Running the verifiers
+
+```bash
+# JavaScript (Node.js 18+)
+node verify.mjs
+
+# Python (3.7+)
+python3 verify.py
+```
+
+## Regenerating vectors
+
+```bash
+node generate.mjs
+```
+
+The generator uses the same canonicalization logic as `src/attestation/signer.ts`. If the source changes, regenerate and re-run both verifiers to confirm cross-language agreement.
+
+## Vector coverage
+
+| Vector | Tests |
+|--------|-------|
+| genesis_all_fields | All fields populated, first record in chain |
+| genesis_null_optionals | Absent optional fields serialize as null |
+| error_with_code | success: false with negative error code |
+| zero_duration | durationMs: 0 boundary |
+| invalid_params_error | Different JSON-RPC error code |
+| unicode_in_fields | CJK and emoji in string fields |
+| max_safe_integer_duration | durationMs: 9007199254740991 (2^53-1) |
+| empty_string_tool_name | Empty string vs null distinction |
+| chain[0-2] | Three linked records with attestation |
+| dual_hash_demo | Same fields, different attestation: proves canonical hash matches while chain hash differs |