mcp-proof 0.3.11 → 0.3.12

package/bin/mcp-proof.js

@@ -9,9 +9,9 @@
 //   mcp-proof --self-test
 //
 // Exit codes:
-//   0 — verdict allow
+//   0 — verdict allow (and, with --vetokernel-endpoint, VetoKernel authorized it)
 //   1 — verdict warn
-//   2 — verdict block
+//   2 — verdict block, or VetoKernel denied the action
 //   64 — usage error
 //   65 — input parse error
 //
@@ -24,6 +24,7 @@ const os = require('os');
 const path = require('path');
 const { spawn } = require('child_process');
 const { evaluate, evaluateCall, scanSkillManifest, verifyPublisherAsync } = require('../engine.js');
+const { authorizeCall } = require('../vetokernel-client.js');
 
 const DEFAULT_MAX_INPUT_BYTES = 5 * 1024 * 1024;
 const DEFAULT_TIMEOUT_MS = 15000;
@@ -53,6 +54,9 @@ Options:
   --skill <path>     scan a Claude SKILL.md (educational/warning context aware)
   --inspect-call [<path>] inspect a tools/call payload before execution (reads stdin if path omitted)
   --execute [<path>] deprecated alias for --inspect-call
+  --vetokernel-endpoint <url>  with --inspect-call, ask VetoKernel to authorize the
+                     proposed action before execution and verify the returned receipt
+                     (env: VETOKERNEL_ENDPOINT, VETOKERNEL_API_KEY, VETOKERNEL_TENANT_ID)
   --markdown         emit a shareable Markdown Trust Card
   --trust-card       alias for --markdown
   --sarif            emit SARIF 2.1.0 for GitHub code scanning
@@ -150,14 +154,25 @@ async function main() {
 
   if (args.inspectCall) {
     let result;
+    let call;
     try {
-      result = runExecute(args);
+      ({ result, call } = runExecute(args));
     } catch (err) {
       process.stderr.write(`mcp-proof: ${err.message}\n`);
       process.exit(err.exitCode || 65);
     }
+    if (args.vetokernelEndpoint) {
+      try {
+        result.authorization = await authorizeInspectedCall(result, call, args);
+      } catch (err) {
+        // Fail closed: if the authorization service is unreachable, the action
+        // is not authorized.
+        process.stderr.write(`mcp-proof: vetokernel authorization failed: ${err.message}\n`);
+        process.exit(2);
+      }
+    }
     emitOutput(result, args);
-    process.exit(exitCodeForDecision(result.decision));
+    process.exit(exitCodeForInspectedCall(result));
   }
 
   let raw;
@@ -212,6 +227,7 @@ function parseArgs(argv) {
     source: '', transport: '', bind: '', json: false, selfTest: false,
     help: false, version: false, file: '', stdio: '', config: '', skill: '',
     inspectCall: false, deprecatedExecute: false, format: 'human', live: false, timeoutMs: DEFAULT_TIMEOUT_MS,
+    vetokernelEndpoint: process.env.VETOKERNEL_ENDPOINT || '',
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -239,6 +255,7 @@ function parseArgs(argv) {
         break;
       case '--live': out.live = true; break;
       case '--timeout': out.timeoutMs = parseTimeout(argv[++i] || ''); break;
+      case '--vetokernel-endpoint': out.vetokernelEndpoint = argv[++i] || ''; break;
       default:
         if (a.startsWith('-')) {
           process.stderr.write(`mcp-proof: unknown flag ${a}\n`);
@@ -654,7 +671,40 @@ function runExecute(args) {
   const result = evaluateCall(parsed);
   result.mode = 'inspect-call';
   result.name = args.file || 'stdin';
-  return result;
+  return { result, call: parsed };
+}
+
+// authorizeInspectedCall asks VetoKernel to authorize the exact action this
+// call proposes. action_type and target_id come from the call file itself,
+// falling back to the tool name and arguments.target_id, so a call fixture is
+// self-describing and needs no extra flags.
+function authorizeInspectedCall(result, call, args) {
+  const callArgs = call.arguments || (call.params && call.params.arguments) || {};
+  const parametersJSON = JSON.stringify(callArgs);
+  return authorizeCall({
+    endpoint: args.vetokernelEndpoint,
+    apiKey: process.env.VETOKERNEL_API_KEY || '',
+    tenantId: process.env.VETOKERNEL_TENANT_ID || 'default',
+    agentId: call.agent_id || 'mcp-proof',
+    actionId: call.action_id || `mcp-proof-${Date.now()}`,
+    toolName: result.tool,
+    actionType: call.action_type || result.tool,
+    targetId: call.target_id || callArgs.target_id || '',
+    parametersJSON,
+    context: call.context,
+    scanner: {
+      name: 'mcp-proof',
+      decision: result.decision,
+      severity: result.call_scan.severity,
+      reason: result.call_scan.reason,
+    },
+    timeoutMs: args.timeoutMs,
+  });
+}
+
+function exitCodeForInspectedCall(result) {
+  if (result.authorization && result.authorization.decision !== 'allow') return 2;
+  return exitCodeForDecision(result.decision);
 }
 
 function exitCodeForDecision(d) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-proof",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "description": "Auditable, privacy-preserving MCP (Model Context Protocol) server verifier with local Trust Cards and SARIF output — test servers before connecting them to an AI system.",
   "main": "engine.js",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "engine.js",
+    "vetokernel-client.js",
     "bin/mcp-proof.js",
     "README.md",
     "LICENSE"

package/vetokernel-client.js

@@ -0,0 +1,168 @@
+// vetokernel-client.js — post an inspected tools/call to VetoKernel's
+// execution-authorization endpoint and independently verify the receipt.
+//
+// Node stdlib only (http, https, crypto, url) — mcp-proof adds no dependencies.
+
+'use strict';
+
+const crypto = require('crypto');
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+
+const SCHEMA_VERSION = '1.0';
+
+// goJSONString matches Go's encoding/json string encoding, which HTML-escapes
+// <, > and & by default. Everything else Node's JSON.stringify already agrees on.
+function goJSONString(value) {
+  return JSON.stringify(String(value))
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026');
+}
+
+// canonicalReceiptJSON reproduces, in JavaScript, the exact byte sequence
+// VetoKernel hashes into receipt_hash (Go: backend/auth/execution_authorization.go
+// CanonicalReceiptBytes). It is deliberately an INDEPENDENT re-implementation:
+// agreement between the two is what makes the receipt independently verified
+// rather than merely re-read. Field order and the omitempty set are load-bearing
+// and are pinned by a golden vector in both test suites.
+function canonicalReceiptJSON(receipt) {
+  const fields = [
+    ['schema_version', receipt.schema_version, false],
+    ['decision', receipt.decision, false],
+    ['action_id', receipt.action_id, false],
+    ['action_type', receipt.action_type, false],
+    ['target_id', receipt.target_id, false],
+    ['tool_name', receipt.tool_name, true],
+    ['parameters_hash', receipt.parameters_hash, true],
+    ['tenant_id', receipt.tenant_id, false],
+    ['payload_hash', receipt.payload_hash, false],
+    ['context_hash', receipt.context_hash, false],
+    ['authorized_by_agent_id', receipt.authorized_by_agent_id, true],
+    ['issued_at', receipt.issued_at, false],
+  ];
+  const parts = [];
+  for (const [key, raw, omitempty] of fields) {
+    const value = raw === undefined || raw === null ? '' : raw;
+    if (omitempty && value === '') continue;
+    parts.push(goJSONString(key) + ':' + goJSONString(value));
+  }
+  return '{' + parts.join(',') + '}';
+}
+
+// verifyReceipt re-derives both bindings the receipt claims: that payload_hash
+// is sha256 of the exact parameter bytes we sent, and that receipt_hash is
+// sha256 of the canonical receipt fields.
+function verifyReceipt(receipt, parametersJSON) {
+  if (!receipt || typeof receipt !== 'object') {
+    return { verified: false, problems: ['no receipt returned'], payload_hash: '', receipt_hash: '' };
+  }
+  const problems = [];
+  if (receipt.schema_version !== SCHEMA_VERSION) {
+    problems.push(`unexpected schema_version ${receipt.schema_version}`);
+  }
+  if (receipt.decision !== 'allow') {
+    problems.push(`unexpected receipt decision ${receipt.decision}`);
+  }
+  const payloadHash = crypto.createHash('sha256')
+    .update(Buffer.from(String(parametersJSON), 'utf8')).digest('hex');
+  if (receipt.payload_hash !== payloadHash) {
+    problems.push(`payload_hash does not bind the parameters we sent (recomputed ${payloadHash})`);
+  }
+  const receiptHash = crypto.createHash('sha256')
+    .update(canonicalReceiptJSON(receipt), 'utf8').digest('hex');
+  if (receipt.receipt_hash !== receiptHash) {
+    problems.push(`receipt_hash mismatch (recomputed ${receiptHash})`);
+  }
+  return { verified: problems.length === 0, problems, payload_hash: payloadHash, receipt_hash: receiptHash };
+}
+
+// authorizeCall proposes a consequential action to VetoKernel and returns its
+// decision. It fails closed: an allow whose receipt does not independently
+// verify is downgraded to a deny.
+function authorizeCall(options) {
+  const {
+    endpoint,
+    apiKey = '',
+    tenantId = 'default',
+    agentId = 'mcp-proof',
+    actionId = '',
+    toolName = '',
+    actionType = '',
+    targetId = '',
+    parametersJSON = '{}',
+    context,
+    scanner = { name: 'mcp-proof', decision: 'allow', severity: 'low', reason: 'clean' },
+    timeoutMs = 5000,
+  } = options;
+
+  const body = JSON.stringify({
+    schema_version: SCHEMA_VERSION,
+    action_id: actionId,
+    agent_id: agentId,
+    tool_name: toolName,
+    action_type: actionType,
+    target_id: targetId,
+    parameters_json: parametersJSON,
+    context: context || undefined,
+    scanner,
+  });
+
+  const url = new URL(endpoint);
+  const transport = url.protocol === 'https:' ? https : http;
+
+  return new Promise((resolve, reject) => {
+    const req = transport.request({
+      protocol: url.protocol,
+      hostname: url.hostname,
+      port: url.port,
+      path: url.pathname + url.search,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+        'X-API-Key': apiKey,
+        'X-Tenant-ID': tenantId,
+      },
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const raw = Buffer.concat(chunks).toString('utf8');
+        let parsed;
+        try {
+          parsed = JSON.parse(raw);
+        } catch (_) {
+          reject(new Error(`vetokernel returned non-JSON (status ${res.statusCode}): ${raw.slice(0, 200)}`));
+          return;
+        }
+        const out = {
+          endpoint,
+          status: res.statusCode,
+          decision: parsed.decision === 'allow' ? 'allow' : 'deny',
+          reason: parsed.reason || '',
+          receipt: parsed.receipt || null,
+          verification: null,
+        };
+        out.verification = out.decision === 'allow'
+          ? verifyReceipt(parsed.receipt, parametersJSON)
+          : { verified: false, problems: ['denied — no receipt issued'], payload_hash: '', receipt_hash: '' };
+        if (out.decision === 'allow' && !out.verification.verified) {
+          out.decision = 'deny';
+          out.reason = `receipt failed independent verification: ${out.verification.problems.join('; ')}`;
+        }
+        resolve(out);
+      });
+    });
+
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error(`vetokernel request timed out after ${timeoutMs}ms`));
+    });
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+module.exports = { authorizeCall, verifyReceipt, canonicalReceiptJSON, SCHEMA_VERSION };