@mcp-audit-gateway/core 0.2.0 → 0.4.0

package/src/attestation/signer.test.ts

@@ -156,4 +156,18 @@ describe("Ed25519Signer", () => {
     expect(pubKey).not.toBeNull();
     expect(pubKey!.length).toBe(32);
   });
+
+  it("rejects signature from a different key (signature substitution)", async () => {
+    const signerA = new Ed25519Signer();
+    await signerA.init();
+    const signerB = new Ed25519Signer();
+    await signerB.init();
+
+    const sigFromA = await signerA.sign(mockRecord);
+    const validOnA = await signerA.verify(mockRecord, sigFromA);
+    expect(validOnA).toBe(true);
+
+    const validOnB = await signerB.verify(mockRecord, sigFromA);
+    expect(validOnB).toBe(false);
+  });
 });

package/src/attestation/signer.ts

@@ -1,9 +1,10 @@
-import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
-import type { AttestationConfig, AuditRecord } from "../types.js";
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import type { AttestationConfig, AuditRecord, CheckpointRecord, ChainBreakRecord, ChainRecord } from "../types.js";
+import { isCheckpoint, isChainBreak } from "../types.js";
 
 export interface Signer {
-  sign(record: AuditRecord): Promise<string>;
-  verify(record: AuditRecord, signature: string): Promise<boolean>;
+  sign(record: AuditRecord | CheckpointRecord | ChainBreakRecord): Promise<string>;
+  verify(record: AuditRecord | CheckpointRecord | ChainBreakRecord, signature: string): Promise<boolean>;
 }
 
 export class HmacSigner implements Signer {
@@ -13,24 +14,24 @@ export class HmacSigner implements Signer {
     this.secret = Buffer.from(secret, "hex");
   }
 
-  async sign(record: AuditRecord): Promise<string> {
-    const payload = this.canonicalize(record);
+  async sign(record: AuditRecord | CheckpointRecord | ChainBreakRecord): Promise<string> {
+    const payload = isChainBreak(record)
+      ? canonicalizeChainBreak(record)
+      : isCheckpoint(record)
+        ? canonicalizeCheckpoint(record)
+        : canonicalizeRecord(record);
     const hmac = createHmac("sha256", this.secret);
     hmac.update(payload);
     return hmac.digest("hex");
   }
 
-  async verify(record: AuditRecord, signature: string): Promise<boolean> {
+  async verify(record: AuditRecord | CheckpointRecord | ChainBreakRecord, signature: string): Promise<boolean> {
     const expected = await this.sign(record);
     const expectedBuf = Buffer.from(expected, "hex");
     const signatureBuf = Buffer.from(signature, "hex");
     if (expectedBuf.length !== signatureBuf.length) return false;
     return timingSafeEqual(expectedBuf, signatureBuf);
   }
-
-  private canonicalize(record: AuditRecord): string {
-    return canonicalizeRecord(record);
-  }
 }
 
 export class Ed25519Signer implements Signer {
@@ -51,18 +52,28 @@ export class Ed25519Signer implements Signer {
     this.publicKey = await ed.getPublicKeyAsync(this.privateKey);
   }
 
-  async sign(record: AuditRecord): Promise<string> {
+  async sign(record: AuditRecord | CheckpointRecord | ChainBreakRecord): Promise<string> {
     if (!this.privateKey) await this.init();
     const ed = await import("@noble/ed25519");
-    const payload = new TextEncoder().encode(this.canonicalize(record));
+    const canonical = isChainBreak(record)
+      ? canonicalizeChainBreak(record)
+      : isCheckpoint(record)
+        ? canonicalizeCheckpoint(record)
+        : canonicalizeRecord(record);
+    const payload = new TextEncoder().encode(canonical);
     const sig = await ed.signAsync(payload, this.privateKey!);
     return Buffer.from(sig).toString("hex");
   }
 
-  async verify(record: AuditRecord, signature: string): Promise<boolean> {
+  async verify(record: AuditRecord | CheckpointRecord | ChainBreakRecord, signature: string): Promise<boolean> {
     if (!this.publicKey) await this.init();
     const ed = await import("@noble/ed25519");
-    const payload = new TextEncoder().encode(this.canonicalize(record));
+    const canonical = isChainBreak(record)
+      ? canonicalizeChainBreak(record)
+      : isCheckpoint(record)
+        ? canonicalizeCheckpoint(record)
+        : canonicalizeRecord(record);
+    const payload = new TextEncoder().encode(canonical);
     const sig = Buffer.from(signature, "hex");
     return ed.verifyAsync(sig, payload, this.publicKey!);
   }
@@ -70,13 +81,35 @@ export class Ed25519Signer implements Signer {
   getPublicKey(): Uint8Array | null {
     return this.publicKey;
   }
+}
 
-  private canonicalize(record: AuditRecord): string {
-    return canonicalizeRecord(record);
+export function assertWellFormedString(value: string, context: string): void {
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code >= 0xD800 && code <= 0xDBFF) {
+      const next = i + 1 < value.length ? value.charCodeAt(i + 1) : 0;
+      if (next < 0xDC00 || next > 0xDFFF) {
+        throw new Error(`${context}: unpaired surrogate at index ${i}`);
+      }
+      i++;
+    } else if (code >= 0xDC00 && code <= 0xDFFF) {
+      throw new Error(`${context}: unpaired surrogate at index ${i}`);
+    }
   }
 }
 
-function canonicalizeRecord(record: AuditRecord): string {
+export function canonicalizeRecord(record: AuditRecord): string {
+  assertWellFormedString(record.id, "canonicalizeRecord.id");
+  assertWellFormedString(record.timestamp, "canonicalizeRecord.timestamp");
+  assertWellFormedString(record.method, "canonicalizeRecord.method");
+  if (record.toolName != null) assertWellFormedString(record.toolName, "canonicalizeRecord.toolName");
+  if (record.namespace != null) assertWellFormedString(record.namespace, "canonicalizeRecord.namespace");
+  if (record.upstream != null) assertWellFormedString(record.upstream, "canonicalizeRecord.upstream");
+  if (record.principal != null) assertWellFormedString(record.principal, "canonicalizeRecord.principal");
+  if (record.previousHash != null) assertWellFormedString(record.previousHash, "canonicalizeRecord.previousHash");
+  if (record.decisionContextDigest != null) assertWellFormedString(record.decisionContextDigest, "canonicalizeRecord.decisionContextDigest");
+  if (record.extensionsDigest != null) assertWellFormedString(record.extensionsDigest, "canonicalizeRecord.extensionsDigest");
+
   const ordered: [string, string | number | boolean | null | unknown][] = [
     ["id", record.id],
     ["timestamp", record.timestamp],
@@ -90,16 +123,116 @@ function canonicalizeRecord(record: AuditRecord): string {
     ["errorCode", record.errorCode ?? null],
     ["previousHash", record.previousHash ?? null],
   ];
+  // Conditional fields inserted in deterministic order:
+  // 1. decisionContextDigest (position 10, before previousHash moves to 11)
+  // 2. extensionsDigest (after decisionContextDigest or at position 11)
+  // 3. aiInvocation (after extensionsDigest; M/L-tagged via canonicalizeValue)
+  // 4. parties (last)
+  let insertAt = 11;
   if (record.decisionContextDigest != null) {
     ordered.splice(10, 0, ["decisionContextDigest", record.decisionContextDigest]);
+    insertAt = 12;
+  }
+  if (record.extensionsDigest != null) {
+    ordered.splice(insertAt, 0, ["extensionsDigest", record.extensionsDigest]);
+    insertAt++;
+  }
+  if (record.aiInvocation != null) {
+    ordered.splice(insertAt, 0, ["aiInvocation", canonicalizeValue(record.aiInvocation)]);
+    insertAt++;
   }
   if (record.parties != null) {
-    const insertAt = record.decisionContextDigest != null ? 12 : 11;
     ordered.splice(insertAt, 0, ["parties", record.parties]);
   }
   return JSON.stringify(ordered);
 }
 
+export function canonicalizeCheckpoint(record: CheckpointRecord): string {
+  assertWellFormedString(record.id, "canonicalizeCheckpoint.id");
+  assertWellFormedString(record.timestamp, "canonicalizeCheckpoint.timestamp");
+  assertWellFormedString(record.previousHash, "canonicalizeCheckpoint.previousHash");
+
+  const ordered: [string, string | number | null | unknown][] = [
+    ["id", record.id],
+    ["type", "checkpoint"],
+    ["timestamp", record.timestamp],
+    ["sequence", record.sequence],
+    ["recordCount", record.recordCount],
+    ["previousHash", record.previousHash],
+  ];
+  if (record.parties != null) {
+    ordered.push(["parties", record.parties]);
+  }
+  return JSON.stringify(ordered);
+}
+
+export function canonicalizeChainBreak(record: ChainBreakRecord): string {
+  assertWellFormedString(record.id, "canonicalizeChainBreak.id");
+  assertWellFormedString(record.timestamp, "canonicalizeChainBreak.timestamp");
+  assertWellFormedString(record.reason, "canonicalizeChainBreak.reason");
+  if (record.priorHead != null) assertWellFormedString(record.priorHead, "canonicalizeChainBreak.priorHead");
+
+  const ordered: [string, string | number | null][] = [
+    ["id", record.id],
+    ["type", "chain_break"],
+    ["timestamp", record.timestamp],
+    ["reason", record.reason],
+    ["priorHead", record.priorHead ?? null],
+    ["priorSequence", record.priorSequence ?? null],
+    ["priorRecordCount", record.priorRecordCount ?? null],
+  ];
+  return JSON.stringify(ordered);
+}
+
+/**
+ * Recursively canonicalize a value for deterministic, injective serialization.
+ *
+ * Objects become ["M", [[k,v],...]] (sorted pairs). Arrays become ["L", [...]].
+ * Type tags make the mapping injective: {a:1} and [["a",1]] produce distinct
+ * canonical forms, preventing type-confusion collisions in digests.
+ *
+ * Numbers must be safe integers — floats/unsafe integers throw (callers must
+ * pre-encode as strings). Strings, booleans, and null pass through as scalars.
+ * Keys with undefined values are dropped (matches JSON.stringify and Python).
+ */
+export function canonicalizeValue(value: unknown): unknown {
+  if (value === null || value === undefined) return null;
+
+  switch (typeof value) {
+    case "string":
+      assertWellFormedString(value, "canonicalizeValue");
+      return value;
+    case "boolean":
+      return value;
+    case "number":
+      if (!Number.isSafeInteger(value)) {
+        throw new Error(
+          `canonicalizeValue: unsafe number ${value}. ` +
+          `Only safe integers are allowed; encode floats/large numbers as strings.`
+        );
+      }
+      return value;
+    case "object":
+      if (Array.isArray(value)) {
+        return ["L", value.map(canonicalizeValue)];
+      }
+      const obj = value as Record<string, unknown>;
+      const keys = Object.keys(obj).sort().filter(k => obj[k] !== undefined);
+      for (const k of keys) {
+        assertWellFormedString(k, "canonicalizeValue.key");
+      }
+      return ["M", keys.map(k => [k, canonicalizeValue(obj[k])])];
+    default:
+      throw new Error(`canonicalizeValue: unsupported type ${typeof value}`);
+  }
+}
+
+export function computeExtensionsDigest(extensions: Record<string, unknown>): string {
+  const canonicalized = canonicalizeValue(extensions);
+  const serialized = JSON.stringify(canonicalized);
+  return createHash("sha256").update(serialized).digest("hex");
+}
+
 export function createSigner(config: AttestationConfig): Signer {
   if (!config.enabled) {
     return { sign: async () => "", verify: async () => true };

package/src/attestation/verify.ts

@@ -1,6 +1,7 @@
 import { createReadStream } from "node:fs";
 import { createInterface } from "node:readline";
-import type { AuditRecord } from "../types.js";
+import type { AuditRecord, CheckpointRecord, ChainBreakRecord, ChainRecord } from "../types.js";
+import { isCheckpoint, isChainBreak } from "../types.js";
 import { HmacSigner, Ed25519Signer, type Signer } from "./signer.js";
 import { hashRecord } from "./audit-log.js";
 
@@ -97,15 +98,34 @@ export async function verifyAuditLog(
   return result;
 }
 
-export async function verifyChain(records: AuditRecord[]): Promise<ChainVerifyResult> {
+function getRecordPreviousHash(record: ChainRecord): string | undefined {
+  if (isChainBreak(record)) return undefined;
+  return (record as AuditRecord | CheckpointRecord).previousHash;
+}
+
+export async function verifyChain(records: ChainRecord[]): Promise<ChainVerifyResult> {
   const result: ChainVerifyResult = { total: records.length, valid: true, errors: [] };
 
   for (let i = 0; i < records.length; i++) {
     const record = records[i];
     const lineNum = i + 1;
 
+    // chain_break records are valid chain starts (no previousHash required)
+    if (isChainBreak(record)) {
+      if (i !== 0) {
+        result.valid = false;
+        result.errors.push({
+          line: lineNum,
+          id: record.id,
+          reason: "chain_break record must be at position 0",
+        });
+      }
+      continue;
+    }
+
+    const prevHash = getRecordPreviousHash(record);
     if (i === 0) {
-      if (record.previousHash !== "genesis") {
+      if (prevHash !== "genesis") {
         result.valid = false;
         result.errors.push({
           line: lineNum,
@@ -116,7 +136,7 @@ export async function verifyChain(records: AuditRecord[]): Promise<ChainVerifyRe
     } else {
       const prevRecord = records[i - 1];
       const expectedHash = hashRecord(prevRecord);
-      if (record.previousHash !== expectedHash) {
+      if (prevHash !== expectedHash) {
         result.valid = false;
         result.errors.push({
           line: lineNum,
@@ -129,3 +149,249 @@ export async function verifyChain(records: AuditRecord[]): Promise<ChainVerifyRe
 
   return result;
 }
+
+export type TruncationFailureCode =
+  | "head_missing"
+  | "count_mismatch"
+  | "sequence_regression";
+
+export interface TruncationCheckResult {
+  truncated: boolean;
+  lastCheckpoint: CheckpointRecord | null;
+  expectedRecordCount: number | null;
+  actualRecordCount: number;
+  recordCountValid?: boolean;
+  absoluteCountVerified?: boolean;
+  verificationMode?: "strict" | "relative";
+  hasChainBreak?: boolean;
+  failureCode?: TruncationFailureCode;
+  reason?: string;
+}
+
+export interface VerifyCompletenessOptions {
+  mode?: "strict" | "relative";
+}
+
+export function verifyCompleteness(
+  records: ChainRecord[],
+  externalCheckpoint: { previousHash: string; sequence: number; recordCount: number },
+  options?: VerifyCompletenessOptions,
+): TruncationCheckResult {
+  const mode = options?.mode ?? "strict";
+  const actualRecordCount = records.length;
+  let foundCheckpoint: CheckpointRecord | null = null;
+  let checkpointIndex = -1;
+
+  for (let i = 0; i < records.length; i++) {
+    const record = records[i];
+    if (isCheckpoint(record)) {
+      if (
+        record.previousHash === externalCheckpoint.previousHash &&
+        record.sequence === externalCheckpoint.sequence &&
+        record.recordCount === externalCheckpoint.recordCount
+      ) {
+        foundCheckpoint = record;
+        checkpointIndex = i;
+        break;
+      }
+    }
+  }
+
+  if (!foundCheckpoint) {
+    let hasDescendant = false;
+    for (const record of records) {
+      if (isCheckpoint(record) && record.sequence > externalCheckpoint.sequence) {
+        hasDescendant = true;
+        break;
+      }
+    }
+
+    if (hasDescendant) {
+      // In relative mode: descendant is acceptable, but absolute counts are unverified
+      if (mode === "relative") {
+        const deltaResult = verifyAdjacentDeltas(records, "relative");
+        if (deltaResult) return { ...deltaResult, verificationMode: "relative" };
+        return {
+          truncated: false,
+          lastCheckpoint: null,
+          expectedRecordCount: externalCheckpoint.recordCount,
+          actualRecordCount,
+          absoluteCountVerified: false,
+          verificationMode: "relative",
+        };
+      }
+      return {
+        truncated: false,
+        lastCheckpoint: null,
+        expectedRecordCount: externalCheckpoint.recordCount,
+        actualRecordCount,
+        verificationMode: "strict",
+      };
+    }
+
+    return {
+      truncated: true,
+      lastCheckpoint: null,
+      expectedRecordCount: externalCheckpoint.recordCount,
+      actualRecordCount,
+      failureCode: "head_missing",
+      verificationMode: mode,
+      reason: "externalized checkpoint not found in chain and no descendant checkpoint exists",
+    };
+  }
+
+  // Check for sequence regression, segmented at chain_break boundaries.
+  // A chain_break legitimately resets counters, so monotonicity is only
+  // enforced within each segment (between breaks).
+  const regressionResult = checkSequenceRegression(records, externalCheckpoint, actualRecordCount, mode);
+  if (regressionResult) return regressionResult;
+
+  // Verify recordCount against prefix (strict mode: absolute; relative mode: delta only)
+  if (mode === "strict") {
+    let nonCheckpointsBefore = 0;
+    for (let i = 0; i < checkpointIndex; i++) {
+      if (!isCheckpoint(records[i])) nonCheckpointsBefore++;
+    }
+    const recordCountValid = nonCheckpointsBefore === foundCheckpoint.recordCount;
+
+    if (!recordCountValid) {
+      return {
+        truncated: true,
+        lastCheckpoint: foundCheckpoint,
+        expectedRecordCount: externalCheckpoint.recordCount,
+        actualRecordCount,
+        recordCountValid,
+        absoluteCountVerified: true,
+        failureCode: "count_mismatch",
+        verificationMode: "strict",
+        reason: `recordCount mismatch: checkpoint claims ${foundCheckpoint.recordCount} records but ${nonCheckpointsBefore} non-checkpoint records precede it`,
+      };
+    }
+  }
+
+  // Adjacent-pair delta checks (both modes; segment-initial anchor only in strict)
+  const deltaResult = verifyAdjacentDeltas(records, mode);
+  if (deltaResult) return { ...deltaResult, verificationMode: mode };
+
+  const chainContainsBreak = records.some(isChainBreak);
+
+  return {
+    truncated: false,
+    lastCheckpoint: foundCheckpoint,
+    expectedRecordCount: externalCheckpoint.recordCount,
+    actualRecordCount,
+    recordCountValid: true,
+    absoluteCountVerified: mode === "strict",
+    verificationMode: mode,
+    hasChainBreak: chainContainsBreak || undefined,
+  };
+}
+
+/**
+ * Check sequence monotonicity, segmented at chain_break boundaries.
+ * A chain_break legitimately resets counters, so regression is only
+ * flagged within a contiguous segment.
+ */
+function checkSequenceRegression(
+  records: ChainRecord[],
+  externalCheckpoint: { previousHash: string; sequence: number; recordCount: number },
+  actualRecordCount: number,
+  mode: "strict" | "relative",
+): TruncationCheckResult | null {
+  let segmentCheckpoints: CheckpointRecord[] = [];
+
+  for (const record of records) {
+    if (isChainBreak(record)) {
+      segmentCheckpoints = [];
+      continue;
+    }
+    if (isCheckpoint(record)) {
+      if (segmentCheckpoints.length > 0) {
+        const prev = segmentCheckpoints[segmentCheckpoints.length - 1];
+        if (record.sequence <= prev.sequence) {
+          return {
+            truncated: true,
+            lastCheckpoint: record,
+            expectedRecordCount: externalCheckpoint.recordCount,
+            actualRecordCount,
+            failureCode: "sequence_regression",
+            verificationMode: mode,
+            reason: `checkpoint sequence regressed: ${record.sequence} <= ${prev.sequence}`,
+          };
+        }
+      }
+      segmentCheckpoints.push(record);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Verify that the recordCount delta between adjacent checkpoints matches
+ * the actual number of non-checkpoint records between them.
+ * Segmented at chain_break boundaries (delta resets across breaks).
+ */
+function verifyAdjacentDeltas(records: ChainRecord[], mode?: "strict" | "relative"): TruncationCheckResult | null {
+  const checkpoints: { checkpoint: CheckpointRecord; index: number }[] = [];
+  // Segment start: index after the most recent chain_break (or 0 if none).
+  // No chain_break can occur between same-segment checkpoints — the reset clears the list.
+  let segmentStart = 0;
+
+  for (let i = 0; i < records.length; i++) {
+    if (isChainBreak(records[i])) {
+      checkpoints.length = 0;
+      segmentStart = i + 1;
+      continue;
+    }
+    if (isCheckpoint(records[i])) {
+      checkpoints.push({ checkpoint: records[i] as CheckpointRecord, index: i });
+    }
+  }
+
+  // Segment-initial checkpoint absolute anchor (strict mode only — relative mode
+  // receives a suffix and can't verify absolute counts).
+  if (mode === "strict" && checkpoints.length > 0) {
+    const first = checkpoints[0];
+    let nonCheckpointsBefore = 0;
+    for (let j = segmentStart; j < first.index; j++) {
+      if (!isCheckpoint(records[j]) && !isChainBreak(records[j])) nonCheckpointsBefore++;
+    }
+    if (nonCheckpointsBefore !== first.checkpoint.recordCount) {
+      return {
+        truncated: true,
+        lastCheckpoint: first.checkpoint,
+        expectedRecordCount: null,
+        actualRecordCount: records.length,
+        recordCountValid: false,
+        failureCode: "count_mismatch",
+        reason: `segment-initial checkpoint claims recordCount ${first.checkpoint.recordCount} but ${nonCheckpointsBefore} non-checkpoint records precede it in segment`,
+      };
+    }
+  }
+
+  for (let i = 1; i < checkpoints.length; i++) {
+    const prev = checkpoints[i - 1];
+    const curr = checkpoints[i];
+    const expectedDelta = curr.checkpoint.recordCount - prev.checkpoint.recordCount;
+
+    let actualNonCheckpoints = 0;
+    for (let j = prev.index + 1; j < curr.index; j++) {
+      if (!isCheckpoint(records[j])) actualNonCheckpoints++;
+    }
+
+    if (actualNonCheckpoints !== expectedDelta) {
+      return {
+        truncated: true,
+        lastCheckpoint: curr.checkpoint,
+        expectedRecordCount: null,
+        actualRecordCount: records.length,
+        recordCountValid: false,
+        failureCode: "count_mismatch",
+        reason: `adjacent checkpoint delta mismatch: checkpoints ${prev.checkpoint.sequence}->${curr.checkpoint.sequence} claim delta ${expectedDelta} but ${actualNonCheckpoints} non-checkpoint records found between them`,
+      };
+    }
+  }
+
+  return null;
+}

package/src/integration.test.ts

@@ -25,6 +25,7 @@ const config: GatewayConfig = {
   attestation: { enabled: true, algorithm: "hmac-sha256", secret: "c".repeat(64), includeParams: false, includeResult: false },
   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("Integration: Gateway with in-memory MCP server", () => {

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

@@ -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);
@@ -130,6 +131,7 @@ export class Gateway {
         success: false,
         errorCode: -32603,
         decisionContextDigest: contextDigest,
+        aiInvocation,
       });
       throw new ToolCallError(
         -32603,
@@ -177,6 +179,7 @@ export class Gateway {
         durationMs,
         success: true,
         decisionContextDigest: contextDigest,
+        aiInvocation,
       });
 
       return { result, auditRecord: record };
@@ -207,6 +210,7 @@ export class Gateway {
         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", () => {