ccs-mcp-server 1.1.2 → 1.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ccs-mcp-server",
-  "version": "1.1.2",
-  "description": "CCS Runtime Evidence MCP Server — verify AI agent tool calls, issue tamper-evident evidence, audit MCP configs, and bind execution to declared intent (cross-model amount drift protection). For Claude Desktop, Cursor, Windsurf, and any MCP client.",
+  "version": "1.2.0",
+  "description": "CCS Runtime Evidence MCP Server — verify AI agent tool calls, issue Ed25519-signed evidence receipts, audit MCP configs, and bind execution to declared intent (cross-model amount drift protection). For Claude Desktop, Cursor, Windsurf, and any MCP client.",
   "type": "commonjs",
   "bin": {
     "ccs-mcp-server": "src/index.js"
@@ -23,6 +23,7 @@
     "correctover",
     "audit",
     "evidence",
+    "ed25519",
     "supply-chain-security",
     "agent-security",
     "security",
@@ -38,9 +39,12 @@
     "node": ">=18"
   },
   "dependencies": {},
+  "scripts": {
+    "test": "node test/run-tests.js"
+  },
   "mcp": {
     "name": "ccs-runtime-evidence",
     "displayName": "CCS Runtime Evidence",
-    "description": "Verify AI agent tool calls and issue tamper-evident CCS evidence records. Blocks command injection, path traversal, SSRF, SQL injection; validates caller identity, schema, cost/latency budgets; produces cryptographically bound evidence."
+    "description": "Verify AI agent tool calls and issue Ed25519-signed CCS evidence receipts. Blocks command injection, path traversal, SSRF, SQL injection; validates caller identity, schema, cost/latency budgets; produces cryptographically signed and independently verifiable evidence."
   }
 }

package/src/index.js

@@ -26,12 +26,13 @@
 
 const crypto = require("crypto");
 const readline = require("readline");
+const receipts = require("./receipts");
 
 // ---------------------------------------------------------------------------
 // CCS Verifier Core (pure stdlib Node.js)
 // ---------------------------------------------------------------------------
 
-const CCS_VERSION = "1.1.2";
+const CCS_VERSION = "1.2.0";
 
 const DEFAULT_POLICY = {
   mode: "block",
@@ -283,7 +284,12 @@ function verifyCall(call, policyOverride) {
   // Finalize evidence_hash
   const hashBody = { ...evidence };
   evidence.evidence_hash = sha256(canonical(hashBody));
-  return evidence;
+
+  // Sign the full evidence record with Ed25519. This makes the receipt
+  // independently verifiable offline: any party holding the signer's
+  // public key can verify that this evidence record was produced by the
+  // holder of the corresponding private key and has not been tampered with.
+  return receipts.signReceipt(evidence);
 }
 
 function auditMcpConfig(config) {
@@ -340,15 +346,24 @@ function verifyIntentBinding(intent, toolName, toolArgs, now = Date.now()) {
   const intentHash = "sha256:" + crypto.createHash("sha256").update(canonical(intent)).digest("hex");
   const argsHash = "sha256:" + crypto.createHash("sha256").update(canonical(toolArgs)).digest("hex");
 
+  let body;
+
   // 1. TTL check
   if (intent.ttl_ms != null && now - intent.issued_at > intent.ttl_ms) {
-    return {
+    body = {
+      evidence_type: "ccs.intent_binding",
+      evidence_version: CCS_VERSION,
+      evidence_id: crypto.randomUUID(),
       allowed: false,
       reason: { type: "intent_expired", expected: intent.issued_at + intent.ttl_ms, actual: now },
+      intent_id: intent.intent_id,
+      intent_type: intent.intent_type,
       intent_hash: intentHash,
       args_hash: argsHash,
       tool: toolName,
+      issued_at: new Date().toISOString(),
     };
+    return receipts.signReceipt(body);
   }
 
   // 2. Field-by-field comparison
@@ -370,26 +385,40 @@ function verifyIntentBinding(intent, toolName, toolArgs, now = Date.now()) {
       }
     }
     if (!match) {
-      return {
+      body = {
+        evidence_type: "ccs.intent_binding",
+        evidence_version: CCS_VERSION,
+        evidence_id: crypto.randomUUID(),
         allowed: false,
         reason: {
           type: "intent_arg_mismatch",
           field, binding_mode: mode,
           expected, actual,
         },
+        intent_id: intent.intent_id,
+        intent_type: intent.intent_type,
         intent_hash: intentHash,
         args_hash: argsHash,
         tool: toolName,
+        issued_at: new Date().toISOString(),
       };
+      return receipts.signReceipt(body);
     }
   }
 
-  return {
+  body = {
+    evidence_type: "ccs.intent_binding",
+    evidence_version: CCS_VERSION,
+    evidence_id: crypto.randomUUID(),
     allowed: true,
+    intent_id: intent.intent_id,
+    intent_type: intent.intent_type,
     intent_hash: intentHash,
     args_hash: argsHash,
     tool: toolName,
+    issued_at: new Date().toISOString(),
   };
+  return receipts.signReceipt(body);
 }
 
 // ---------------------------------------------------------------------------
@@ -480,6 +509,25 @@ const TOOLS = [
       required: ["intent", "tool", "arguments"],
     },
   },
+  {
+    name: "verify_receipt",
+    description: "Offline-verify a CCS Ed25519-signed receipt. Auditors call this with a receipt JSON produced by issue_evidence or verify_intent_binding; it checks the signature against the embedded signer_public_key and reports whether the body was tampered with. Optionally pin an expected signer public key (PEM string or sha256: fingerprint) to reject receipts from untrusted signers.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        receipt: {
+          type: "object",
+          description: "The signed receipt object (must include signer_public_key, signature_alg, signature, and the signed body fields).",
+          additionalProperties: true,
+        },
+        expected_signer: {
+          type: "string",
+          description: "Optional. Either the expected PEM public key, or a sha256:<hex> fingerprint of the DER SPKI public key.",
+        },
+      },
+      required: ["receipt"],
+    },
+  },
 ];
 
 function handleRequest(req) {
@@ -522,19 +570,16 @@ function handleRequest(req) {
       } else if (name === "verify_intent_binding") {
         const verdict = verifyIntentBinding(args.intent, args.tool, args.arguments || {});
         result = {
-          content: [{ type: "text", text: JSON.stringify({
-            allowed: verdict.allowed,
-            intent_id: args.intent.intent_id,
-            intent_hash: verdict.intent_hash,
-            args_hash: verdict.args_hash,
-            tool: args.tool,
-            ...(verdict.reason ? { reason: verdict.reason } : {}),
-            blocked: !verdict.allowed,
-            message: verdict.allowed
-              ? "Intent binding verified — actual arguments match declared intent"
-              : `Intent binding DENIED: ${verdict.reason?.type}`,
-          }, null, 2) }],
-          isError: !verdict.allowed,
+          content: [{ type: "text", text: JSON.stringify(verdict, null, 2) }],
+          isError: verdict.allowed === false,
+        };
+      } else if (name === "verify_receipt") {
+        const v = args.expected_signer
+          ? receipts.verifyReceiptWithKey(args.receipt, args.expected_signer)
+          : receipts.verifyReceipt(args.receipt);
+        result = {
+          content: [{ type: "text", text: JSON.stringify(v, null, 2) }],
+          isError: v.valid === false,
         };
       } else {
         result = { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
@@ -550,7 +595,13 @@ function handleRequest(req) {
 }
 
 function main() {
-  process.stderr.write(`[ccs-mcp-server] v${CCS_VERSION} starting on stdio\n`);
+  const kp = receipts.getKeypair();
+  const fp = receipts.publicKeyFingerprint();
+  process.stderr.write(
+    `[ccs-mcp-server] v${CCS_VERSION} starting on stdio\n` +
+    `[ccs-mcp-server] signing key source: ${kp.source}\n` +
+    `[ccs-mcp-server] signer fingerprint: ${fp}\n`
+  );
   const rl = readline.createInterface({ input: process.stdin });
   rl.on("line", (line) => {
     if (!line.trim()) return;
@@ -563,4 +614,4 @@ function main() {
 }
 
 if (require.main === module) main();
-module.exports = { verifyCall, auditMcpConfig };
+module.exports = { verifyCall, auditMcpConfig, verifyIntentBinding, receipts };

package/src/receipts.js

@@ -0,0 +1,219 @@
+/**
+ * CCS Ed25519 receipt signing and verification (pure Node.js stdlib).
+ *
+ * Key sourcing order:
+ *   1. CCS_PRIVATE_KEY / CCS_PUBLIC_KEY env vars (PEM strings)
+ *   2. CCS_KEY_DIR / ~/.ccs/ed25519-private.pem + ed25519-public.pem
+ *   3. If none found, generate a new keypair and persist it to the key dir.
+ *
+ * Receipts include:
+ *   - all original evidence fields (verdict, dimensions, hashes, ...)
+ *   - signer_public_key  (SPKI PEM, multiline preserved)
+ *   - signature_alg      "Ed25519"
+ *   - signature          base64(crypto.sign over canonical receipt_body)
+ *
+ * The signed body excludes signer_public_key/signature_alg/signature/verified.
+ * Verification uses only the signer_public_key embedded in the receipt itself;
+ * auditors can additionally pin a known pubkey out-of-band.
+ */
+
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const ALG = "Ed25519";
+const ALG_INTERNAL = "ed25519";
+const SIGNATURE_FIELDS = ["signer_public_key", "signature_alg", "signature", "verified"];
+
+function canonical(obj) {
+  return JSON.stringify(obj, Object.keys(obj).sort());
+}
+
+function defaultKeyDir() {
+  if (process.env.CCS_KEY_DIR) return process.env.CCS_KEY_DIR;
+  return path.join(os.homedir(), ".ccs");
+}
+
+function ensureKeypair() {
+  // 1. Env vars
+  if (process.env.CCS_PRIVATE_KEY && process.env.CCS_PUBLIC_KEY) {
+    return {
+      privateKey: crypto.createPrivateKey(
+        process.env.CCS_PRIVATE_KEY.includes("-----BEGIN")
+          ? process.env.CCS_PRIVATE_KEY
+          : Buffer.from(process.env.CCS_PRIVATE_KEY, "base64").toString("utf8")
+      ),
+      publicKey: crypto.createPublicKey(
+        process.env.CCS_PUBLIC_KEY.includes("-----BEGIN")
+          ? process.env.CCS_PUBLIC_KEY
+          : Buffer.from(process.env.CCS_PUBLIC_KEY, "base64").toString("utf8")
+      ),
+      source: "env",
+    };
+  }
+
+  // 2. / 3. Disk
+  const dir = defaultKeyDir();
+  const privPath = path.join(dir, "ed25519-private.pem");
+  const pubPath = path.join(dir, "ed25519-public.pem");
+
+  if (fs.existsSync(privPath) && fs.existsSync(pubPath)) {
+    return {
+      privateKey: crypto.createPrivateKey(fs.readFileSync(privPath, "utf8")),
+      publicKey: crypto.createPublicKey(fs.readFileSync(pubPath, "utf8")),
+      source: "file",
+    };
+  }
+
+  // 3. Generate
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const { privateKey, publicKey } = crypto.generateKeyPairSync(ALG_INTERNAL, {
+    privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    publicKeyEncoding: { type: "spki", format: "pem" },
+  });
+  // Atomic-ish writes with restrictive perms
+  fs.writeFileSync(privPath, privateKey, { mode: 0o600 });
+  fs.writeFileSync(pubPath, publicKey, { mode: 0o644 });
+  return {
+    privateKey: crypto.createPrivateKey(privateKey),
+    publicKey: crypto.createPublicKey(publicKey),
+    source: "generated",
+  };
+}
+
+let _keypair = null;
+function getKeypair() {
+  if (!_keypair) _keypair = ensureKeypair();
+  return _keypair;
+}
+
+function publicKeyPem() {
+  const { publicKey } = getKeypair();
+  return publicKey.export({ type: "spki", format: "pem" });
+}
+
+/**
+ * Sign a receipt body. Returns a new object containing all original fields
+ * plus signer_public_key / signature_alg / signature. The original object
+ * is not mutated.
+ */
+function signReceipt(body) {
+  const { privateKey, publicKey } = getKeypair();
+
+  // Strip any existing signature fields so re-signing is idempotent.
+  const cleaned = { ...body };
+  for (const k of SIGNATURE_FIELDS) delete cleaned[k];
+
+  const pubPem = publicKey.export({ type: "spki", format: "pem" });
+  const payload = canonical(cleaned);
+  const sigBuf = crypto.sign(null, Buffer.from(payload, "utf8"), privateKey);
+
+  return {
+    ...cleaned,
+    signer_public_key: pubPem,
+    signature_alg: ALG,
+    signature: sigBuf.toString("base64"),
+  };
+}
+
+/**
+ * Verify a signed receipt. Returns { valid, reason?, signer_public_key }.
+ * Does NOT require a trusted key — it verifies that the signature matches
+ * the body under the embedded signer_public_key. Callers who need to pin
+ * a known pubkey should compare signer_public_key themselves after this
+ * returns valid=true.
+ */
+function verifyReceipt(receipt) {
+  if (!receipt || typeof receipt !== "object") {
+    return { valid: false, reason: "receipt is not an object" };
+  }
+  const sig = receipt.signature;
+  const alg = receipt.signature_alg;
+  const pubPem = receipt.signer_public_key;
+  if (!sig || !pubPem || !alg) {
+    return { valid: false, reason: "missing signature/signature_alg/signer_public_key" };
+  }
+  if (alg !== ALG) {
+    return { valid: false, reason: `unsupported signature_alg: ${alg}` };
+  }
+
+  const cleaned = { ...receipt };
+  for (const k of SIGNATURE_FIELDS) delete cleaned[k];
+
+  let key;
+  try {
+    key = crypto.createPublicKey(pubPem);
+  } catch (e) {
+    return { valid: false, reason: `invalid signer_public_key: ${e.message}` };
+  }
+  if (key.asymmetricKeyType !== ALG_INTERNAL) {
+    return { valid: false, reason: `signer_public_key is not ${ALG}` };
+  }
+
+  const payload = canonical(cleaned);
+  let sigBuf;
+  try {
+    sigBuf = Buffer.from(sig, "base64");
+  } catch (e) {
+    return { valid: false, reason: "signature is not valid base64" };
+  }
+
+  const ok = crypto.verify(null, Buffer.from(payload, "utf8"), key, sigBuf);
+  if (!ok) {
+    return {
+      valid: false,
+      reason: "signature verification failed (body was tampered or signed by a different key)",
+      signer_public_key: pubPem,
+    };
+  }
+  return { valid: true, signer_public_key: pubPem };
+}
+
+/**
+ * Helper: verify a receipt AND pin it to an expected public key fingerprint.
+ * expectedPem can be a PEM string, or the string "sha256:<hex>" fingerprint.
+ */
+function verifyReceiptWithKey(receipt, expectedPemOrFp) {
+  const v = verifyReceipt(receipt);
+  if (!v.valid) return v;
+
+  if (!expectedPemOrFp) return v;
+
+  if (expectedPemOrFp.startsWith("sha256:")) {
+    // Fingerprint: sha256 of DER-encoded SPKI public key
+    const der = crypto.createPublicKey(v.signer_public_key).export({ type: "spki", format: "der" });
+    const fp = "sha256:" + crypto.createHash("sha256").update(der).digest("hex");
+    if (fp !== expectedPemOrFp) {
+      return { valid: false, reason: `signer fingerprint mismatch: got ${fp}, expected ${expectedPemOrFp}` };
+    }
+    return { valid: true, signer_public_key: v.signer_public_key, signer_fingerprint: fp };
+  }
+
+  // PEM string compare (normalize whitespace)
+  const normA = v.signer_public_key.replace(/\s+/g, "");
+  const normB = String(expectedPemOrFp).replace(/\s+/g, "");
+  if (normA !== normB) {
+    return { valid: false, reason: "signer_public_key does not match the pinned key" };
+  }
+  return { valid: true, signer_public_key: v.signer_public_key };
+}
+
+function publicKeyFingerprint() {
+  const { publicKey } = getKeypair();
+  const der = publicKey.export({ type: "spki", format: "der" });
+  return "sha256:" + crypto.createHash("sha256").update(der).digest("hex");
+}
+
+module.exports = {
+  ALG,
+  canonical,
+  getKeypair,
+  publicKeyPem,
+  publicKeyFingerprint,
+  signReceipt,
+  verifyReceipt,
+  verifyReceiptWithKey,
+};