@panguard-ai/panguard-mcp-proxy 1.7.1 → 1.7.3

package/dist/proxy.d.ts

@@ -14,6 +14,7 @@
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import type { EvalResult } from './evaluator.js';
 import type { McpGateVerdict } from '@panguard-ai/containment';
+import { type VerifyResult } from '@panguard-ai/panguard-guard/audit';
 export interface ProxyConfig {
     /** Command to start the upstream MCP server */
     readonly upstreamCommand: string;
@@ -23,6 +24,10 @@ export interface ProxyConfig {
     readonly evalTimeout?: number;
     /** Fail mode: 'closed' blocks on error (safer), 'open' allows on error (default for availability) */
     readonly failMode?: 'open' | 'closed';
+    /** Stable session id for this proxy run (default: per-process unique). */
+    readonly sessionId?: string;
+    /** Agent id behind this proxy (default: PANGUARD_AGENT_ID env or 'mcp-agent'). */
+    readonly agentId?: string;
 }
 /** The subset of ProxyEvaluator the proxy uses — injectable for testing. */
 export interface ProxyEvaluatorLike {
@@ -43,10 +48,18 @@ export declare class MCPProxy {
     private readonly riskStore;
     /** Confidence at/above which an evaluator deny escalates the whole session. */
     private static readonly ESCALATE_CONFIDENCE;
-    /** One stdio session per proxy process. */
+    /**
+     * One stdio session per proxy process. Defaults to a per-process unique id
+     * (not the old hardcoded constant) so verdict lines from distinct runs are
+     * distinguishable; overridable via config for correlation with an orchestrator.
+     */
     private readonly sessionId;
+    /** Agent id behind this proxy — written into every verdict line for attribution. */
+    private readonly agentId;
     /** Upstream tool names = the Layer 0 capability scope (populated in start()). */
     private upstreamToolNames;
+    /** Tamper-evident chain over proxy-verdicts.jsonl (lazily keyed in connect()). */
+    private chain;
     constructor(config: ProxyConfig, deps?: {
         evaluator?: ProxyEvaluatorLike;
     });
@@ -76,5 +89,21 @@ export declare class MCPProxy {
         confidence: number;
         matchedRules: readonly string[];
     }): void;
+    /**
+     * Lazily build the tamper-evident verdict chain. The audit key is resolved
+     * keychain-first (file fallback); getAuditKey never throws. Chain construction
+     * is best-effort — if it fails, verdict logging silently no-ops rather than
+     * bricking the proxy (fail-open on audit).
+     */
+    private ensureChain;
+    /**
+     * Append a verdict to the tamper-evident chain. The REAL sessionId/agentId are
+     * carried in actor.agent (the old code dropped them), plus a decisionId and the
+     * lifted matched rule id. AuditChain.append is fail-open so a broken audit file
+     * never blocks a tool call.
+     */
+    private logVerdict;
+    /** Verify the durable proxy-verdicts chain end-to-end. */
+    verify(): Promise<VerifyResult | null>;
     private registerHandlers;
 }

package/dist/proxy.js

@@ -16,21 +16,13 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { appendFileSync, mkdirSync } from 'node:fs';
+import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { ProxyEvaluator } from './evaluator.js';
 import { GuardGate, InlineGate, RiskAnalyzer, InMemoryRiskStore, NoopContainmentController, applyMcpGate, } from '@panguard-ai/containment';
+import { AuditChain, buildActor, newDecisionId, getAuditKey, } from '@panguard-ai/panguard-guard/audit';
 const VERDICT_LOG = join(homedir(), '.panguard-guard', 'proxy-verdicts.jsonl');
-function logVerdict(entry) {
-    try {
-        mkdirSync(join(homedir(), '.panguard-guard'), { recursive: true });
-        appendFileSync(VERDICT_LOG, JSON.stringify({ ...entry, ts: new Date().toISOString() }) + '\n');
-    }
-    catch {
-        /* best-effort logging */
-    }
-}
 export class MCPProxy {
     config;
     evaluator;
@@ -44,10 +36,18 @@ export class MCPProxy {
     riskStore;
     /** Confidence at/above which an evaluator deny escalates the whole session. */
     static ESCALATE_CONFIDENCE = 95;
-    /** One stdio session per proxy process. */
-    sessionId = 'mcp-proxy-session';
+    /**
+     * One stdio session per proxy process. Defaults to a per-process unique id
+     * (not the old hardcoded constant) so verdict lines from distinct runs are
+     * distinguishable; overridable via config for correlation with an orchestrator.
+     */
+    sessionId;
+    /** Agent id behind this proxy — written into every verdict line for attribution. */
+    agentId;
     /** Upstream tool names = the Layer 0 capability scope (populated in start()). */
     upstreamToolNames = new Set();
+    /** Tamper-evident chain over proxy-verdicts.jsonl (lazily keyed in connect()). */
+    chain = null;
     constructor(config, deps = {}) {
         this.config = config;
         this.evaluator = deps.evaluator ?? new ProxyEvaluator();
@@ -64,6 +64,9 @@ export class MCPProxy {
             config.failMode ??
                 (envFailMode === 'open' || envFailMode === 'closed' ? envFailMode : 'closed');
         this.evalTimeout = config.evalTimeout ?? 5000;
+        this.sessionId =
+            config.sessionId ?? `mcp-proxy-${process.pid}-${Date.now().toString(36)}`;
+        this.agentId = config.agentId ?? process.env['PANGUARD_AGENT_ID'] ?? 'mcp-agent';
         // Sync sub-ms pre-check. Runs in front of the async evaluator so the worst
         // payloads (and any session the brain flags) are blocked instantly — and,
         // with fail-closed as the default, an unavailable async evaluator denies.
@@ -90,6 +93,7 @@ export class MCPProxy {
      * in-memory transports without spawning a process.
      */
     async connect(upstreamTransport, agentTransport) {
+        await this.ensureChain();
         const ruleCount = await this.evaluator.loadRules();
         process.stderr.write(`[panguard-proxy] Loaded ${ruleCount} ATR rules\n`);
         this.client = new Client({ name: 'panguard-mcp-proxy', version: '0.1.0' }, { capabilities: {} });
@@ -133,7 +137,7 @@ export class MCPProxy {
             name,
             args: toolArgs,
             sessionId: this.sessionId,
-            agentId: 'mcp-agent',
+            agentId: this.agentId,
             capabilities: this.upstreamToolNames.size > 0 ? this.upstreamToolNames : new Set([name]),
         });
     }
@@ -149,6 +153,58 @@ export class MCPProxy {
             this.riskStore.set(this.sessionId, { level: 'high', reasons: [...verdict.matchedRules] });
         }
     }
+    /**
+     * Lazily build the tamper-evident verdict chain. The audit key is resolved
+     * keychain-first (file fallback); getAuditKey never throws. Chain construction
+     * is best-effort — if it fails, verdict logging silently no-ops rather than
+     * bricking the proxy (fail-open on audit).
+     */
+    async ensureChain() {
+        if (this.chain)
+            return;
+        try {
+            mkdirSync(join(homedir(), '.panguard-guard'), { recursive: true });
+            const key = await getAuditKey();
+            // Head-anchor defaults to `<VERDICT_LOG>.head` (per-file) so it never
+            // collides with the events / manifest chain anchors in the same dataDir.
+            this.chain = new AuditChain(VERDICT_LOG, { key });
+        }
+        catch (err) {
+            process.stderr.write(`[panguard-audit] proxy chain init failed (verdict logging disabled): ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    /**
+     * Append a verdict to the tamper-evident chain. The REAL sessionId/agentId are
+     * carried in actor.agent (the old code dropped them), plus a decisionId and the
+     * lifted matched rule id. AuditChain.append is fail-open so a broken audit file
+     * never blocks a tool call.
+     */
+    logVerdict(entry) {
+        if (!this.chain)
+            return;
+        const rules = entry.rules ?? [];
+        this.chain.append({
+            phase: entry.phase,
+            tool: entry.tool,
+            outcome: entry.outcome,
+            reason: entry.reason,
+            rules: [...rules],
+            ms: entry.ms,
+            ts: new Date().toISOString(),
+            decisionId: newDecisionId(),
+            actor: buildActor({
+                platform: 'mcp-proxy',
+                sessionId: this.sessionId,
+                agentId: this.agentId,
+            }),
+            ...(rules.length > 0 ? { rule: { id: rules[0] } } : {}),
+        });
+    }
+    /** Verify the durable proxy-verdicts chain end-to-end. */
+    async verify() {
+        await this.ensureChain();
+        return this.chain ? this.chain.verify() : null;
+    }
     registerHandlers() {
         const client = this.client;
         const server = this.server;
@@ -166,7 +222,7 @@ export class MCPProxy {
             // instantly, even if the async evaluator times out fail-open.
             const gateVerdict = this.gateCheck(name, toolArgs);
             if (!gateVerdict.allow) {
-                logVerdict({
+                this.logVerdict({
                     phase: 'pre-gate',
                     tool: name,
                     outcome: 'deny',
@@ -201,7 +257,7 @@ export class MCPProxy {
                     durationMs: this.evalTimeout,
                 };
             }
-            logVerdict({
+            this.logVerdict({
                 phase: 'pre',
                 tool: name,
                 outcome: preResult.outcome,
@@ -254,7 +310,7 @@ export class MCPProxy {
                         durationMs: this.evalTimeout,
                     };
                 }
-                logVerdict({
+                this.logVerdict({
                     phase: 'post',
                     tool: name,
                     outcome: postResult.outcome,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panguard-ai/panguard-mcp-proxy",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "MCP Proxy — runtime interception for AI agent tool calls using ATR rules",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,11 +21,12 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "agent-threat-rules": "^3.5.0",
-    "@panguard-ai/atr": "1.7.1",
-    "@panguard-ai/containment": "0.1.0"
+    "@panguard-ai/atr": "1.7.3",
+    "@panguard-ai/containment": "0.1.0",
+    "@panguard-ai/panguard-guard": "1.7.3"
   },
   "peerDependencies": {
-    "@panguard-ai/atr": "1.7.1"
+    "@panguard-ai/atr": "1.7.3"
   },
   "files": [
     "dist",