ccs-mcp-server 1.0.0 → 1.1.1

package/README.md

@@ -1,107 +1,128 @@
 # CCS Runtime Evidence MCP Server
 
-A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that brings **CCS runtime verification** to any MCP-compatible client — Claude Desktop, Cursor, Windsurf, ChatGPT apps, and more.
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that brings **CCS runtime verification** to any MCP-compatible client — Claude Desktop, Cursor, Windsurf, and more.
 
-It verifies AI agent tool calls at runtime, blocks unsafe ones by default, and issues **tamper-evident evidence records** for every call (allowed and denied).
+It verifies AI agent tool calls at runtime, blocks unsafe ones by default, issues **tamper-evident evidence records** for every decision, and verifies that actual tool arguments match the agent's declared intent — catching cross-model parameter drift.
 
-> **This is a runtime enforcement layer, not a static scanner.** It runs on every live tool call — not once on source code.
-
-## Tools
-
-| Tool | What it does |
-|---|---|
-| `verify_tool_call` | Verify a tool call across 7 CCS dimensions + semantic attack-chain analysis + math overflow detection. Returns `verdict: allowed/denied`. **Blocks by default.** |
-| `issue_evidence` | Issue a cryptographically bound CCS evidence record (`content_hash` + `evidence_hash`) for a call. Independently verifiable. |
-| `audit_mcp_config` | Audit an MCP configuration JSON for security risks: plain HTTP, weak secrets, disabled TLS, missing commands. |
+> **Runtime evidence layer, not a static scanner.** Every decision is enforced at call time and produces independently verifiable cryptographic evidence.
 
 ## Quick Start
 
-### Install and run with npx
-
 ```bash
-npx @correctover/ccs-mcp-server
+npx -y ccs-mcp-server
 ```
 
-### Claude Desktop / Cursor configuration
-
-Add to your MCP client settings:
+### MCP Client Configuration
 
 ```json
 {
   "mcpServers": {
     "ccs-runtime-evidence": {
       "command": "npx",
-      "args": ["-y", "@correctover/ccs-mcp-server"]
+      "args": ["-y", "ccs-mcp-server"]
     }
   }
 }
 ```
 
-## What it detects
+Zero dependencies. 28KB. Pure Node.js stdlib. No install scripts.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `verify_tool_call` | 7-dimension runtime verification (Structure/Schema/Security/Identity/Integrity/Latency/Cost) + semantic attack-chain analysis + math overflow detection. **Blocks by default.** |
+| `issue_evidence` | Issue a tamper-evident evidence record (`content_hash` + `evidence_hash`, chainable). Produced for allowed AND denied calls. |
+| `audit_mcp_config` | Audit MCP configuration JSON for security risks. |
+| `verify_intent_binding` | **(v1.1.0)** Verify actual tool arguments match a declared intent — zero tolerance, zero LLM calls. Catches cross-model parameter drift (planner says `amount: 100`, executor writes `amount: 10000` → DENIED). |
+
+## Intent Binding — Cross-Model Drift Detection
+
+Agent planners (Claude, GPT) declare one thing; executors (Qwen, DeepSeek) sometimes write another. No existing protocol verifies that actual tool call arguments match the agent's declared intent:
 
-- **Command injection**: shell metacharacters, `$()`, backticks, dangerous commands
-- **Path traversal**: `../`, `/etc/passwd`, `/proc/self/`, Windows system paths
-- **SSRF**: localhost, link-local (169.254.x.x), private IP ranges
-- **Prompt injection**: "ignore previous instructions", system prompt extraction, special tokens
-- **SQL injection**: UNION SELECT, `OR 1=1`, `DROP TABLE`
-- **Attack chains**: multi-step combinations (e.g. path traversal + SSRF = exfiltration chain)
-- **Math safety**: integer overflow (>2^53-1), NaN/Infinity, DoS strings
-- **Caller identity**: agent ID verification against allowlist
-- **Schema violations**: type, enum, range, required field checks
-- **MCP config risks**: plain HTTP, weak secrets, `--insecure`, disabled TLS
+- **AP2** signs human authorization — not LLM intent
+- **AgentPay** does baseline tolerance (1%) — not zero-tolerance equivalence
+- **ACS** runs policy decisions — not argument-level equivalence
+- **VAP** (draft-samal-vap-00) explicitly excludes argument semantics from its wire schema
 
-## Evidence format
+CCS Intent Binding fills this layer. The agent framework declares a structured intent before execution; CCS verifies actual arguments against it in sub-millisecond, zero-LLM time.
 
-Every call produces evidence like:
+### Example: amount drift
 
 ```json
+// Intent declared by planner
 {
-  "evidence_type": "ccs.tool_call.verification",
-  "evidence_id": "uuid-v4",
-  "tool": "shell.exec",
-  "caller": "agent-001",
-  "verdict": "denied",
-  "mode": "block",
-  "params_hash": "sha256:...",
-  "policy_hash": "sha256:...",
-  "content_hash": "sha256:...",
-  "evidence_hash": "sha256:...",
-  "dimensions": {
-    "Structure": {"status": "pass"},
-    "Schema": {"status": "pass"},
-    "Security": {"status": "fail", "reason": "cmd: command_injection; cmd: path_traversal; cmd: ssrf"},
-    "Identity": {"status": "pass"}
+  "intent_id": "int-001",
+  "intent_type": "payment",
+  "fields": {
+    "amount": { "value": 100, "binding_mode": "exact" },
+    "recipient": { "value": "Alice", "binding_mode": "exact" }
   },
-  "semantic_analysis": {
-    "attack_chains": [{"chain": "exfil_chain", "severity": "critical"}],
-    "semantic_severity": "critical"
-  },
-  "issued_at": "2026-08-22T12:00:00.000Z"
+  "issued_at": 1755000000000,
+  "ttl_ms": 30000
 }
+
+// Actual arguments from executor
+{ "amount": 10000, "recipient": "Alice" }
+
+// Result: DENIED — intent_arg_mismatch
+// field: amount, expected: 100, actual: 10000
 ```
 
-The dual-hash design (`content_hash` + `evidence_hash`) means any tampering is detectable by any third party.
+### Three binding modes
+
+| Mode | Behavior | Example |
+|------|----------|---------|
+| `exact` | Deep equality with math normalization | `100`, `100.0`, `1e2` all match; `10000` does not |
+| `numeric_tolerance` | Absolute tolerance | `100 ± 0.01` matches `100.005` |
+| `pattern` | Regex match on string fields | `^[A-Z]{3}$` matches `"USD"` |
+
+No intent declared? Falls through to standard 7-dimension verification. Zero breaking changes.
+
+## What It Detects
 
-## About CCS
+- **Command injection**: shell metacharacters, `curl|sh`, `rm -rf`, `eval()`
+- **Path traversal**: `../`, `/etc/passwd`, `/proc/self/`
+- **SSRF**: `169.254.169.254` (cloud metadata), localhost, private ranges — across any tool
+- **Cross-tool attack chains**: read sensitive file → network exfil = `exfil_chain`
+- **Environment variable exfiltration**: API keys, secrets, credentials
+- **Obfuscation**: hex encoding, base64, privilege escalation signals
+- **Math safety**: integer overflow (>2^53-1), NaN/Infinity
+- **MCP config risks**: plain HTTP, weak secrets, `--insecure`, TLS disabled
 
-CCS (Correctover Conformance Shape) is a 7-dimension runtime verification standard for AI agent tool calls:
+## Evidence Chain
+
+Every decision produces evidence with dual hashes (`content_hash` + `evidence_hash`) and chain linkage (`parent_evidence_hash`). Any third party can independently verify that evidence has not been tampered with — without trusting the operator.
+
+```
+evidence 1: allowed  (fs.read_file)       parent: null
+evidence 2: denied   (shell.exec curl|sh) parent: ev1
+evidence 3: denied   (http.fetch SSRF)    parent: ev2
+evidence 4: denied   (fs + curl exfil)    parent: ev3
+```
+
+## The 7 CCS Dimensions
 
 1. **Structure** — valid tool name, argument format, nesting depth, payload size
 2. **Schema** — type, required fields, enums, ranges, string lengths
-3. **Security** — injection, traversal, SSRF, prompt injection, SQL injection
+3. **Security** — injection, traversal, SSRF, env exfiltration, obfuscation + semantic attack chains
 4. **Identity** — caller agent ID verification
 5. **Integrity** — request hash validation
-6. **Latency** — execution time budget (warn)
-7. **Cost** — cost budget (warn)
+6. **Latency** — execution time budget
+7. **Cost** — cost budget
+
+## Protocol Context
 
-Plus: semantic intent analysis (attack chains, obfuscation signals, privilege escalation) and mathematical verification (overflow, NaN, DoS).
+- **IETF**: [draft-correctover-ccs-06](https://datatracker.ietf.org/doc/draft-correctover-ccs/) (Experimental) — RT#55620 submitted
+- **Complements**: [VAP draft-samal-vap-00](https://datatracker.ietf.org/doc/draft-samal-vap/) (scope/budget/purpose), [Microsoft ACS](https://github.com/microsoft/agent-governance-toolkit) (policy decisions), AP2 (human authorization)
+- **Does not replace**: authentication, payment networks, policy engines
 
 ## Links
 
-- npm: https://www.npmjs.com/package/@correctover/ccs-mcp-server
-- Website: https://correctover.com
-- IETF Draft: https://www.ietf.org/archive/id/draft-correctover-ccs-05.txt
-- SkillHub: https://skillhub.cn
+- npm: https://www.npmjs.com/package/ccs-mcp-server
+- GitHub: https://github.com/Correctover/ccs-mcp-server
+- IETF Draft: https://datatracker.ietf.org/doc/draft-correctover-ccs/
+- PyPI (full verifier): https://pypi.org/project/ccs-verifier/
 
 ## License
 

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "ccs-mcp-server",
-  "version": "1.0.0",
-  "description": "CCS Runtime Evidence MCP Server — verify AI agent tool calls, issue tamper-evident evidence, audit MCP configs. For Claude Desktop, Cursor, Windsurf, and any MCP client.",
+  "version": "1.1.1",
+  "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.",
   "type": "commonjs",
   "bin": {
     "ccs-mcp-server": "src/index.js"
   },
   "main": "src/index.js",
-  "files": ["src", "README.md", "LICENSE"],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
   "keywords": [
     "mcp",
     "model-context-protocol",

package/src/index.js

@@ -31,7 +31,7 @@ const readline = require("readline");
 // CCS Verifier Core (pure stdlib Node.js)
 // ---------------------------------------------------------------------------
 
-const CCS_VERSION = "1.0.0";
+const CCS_VERSION = "1.1.1";
 
 const DEFAULT_POLICY = {
   mode: "block",
@@ -307,6 +307,91 @@ function auditMcpConfig(config) {
                  issues.length ? "medium" : "low" };
 }
 
+// ---------------------------------------------------------------------------
+// Intent Binding (L4) — zero-LLM, deterministic, microsecond
+// ---------------------------------------------------------------------------
+// Agent framework declares structured intent before tool execution.
+// CCS verifies actual args match declared intent with zero tolerance.
+// This catches cross-model amount drift (planner says 100, executor writes 10000)
+// without any NLP or LLM call.
+
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b) {
+    // numeric normalization: 100 == 100.0 == 1e2
+    if (typeof a === "number" && typeof b === "string") {
+      const n = Number(b);
+      return Number.isFinite(n) && a === n;
+    }
+    if (typeof b === "number" && typeof a === "string") {
+      const n = Number(a);
+      return Number.isFinite(n) && b === n;
+    }
+    return false;
+  }
+  if (typeof a !== "object" || a === null || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const ka = Object.keys(a), kb = Object.keys(b);
+  if (ka.length !== kb.length) return false;
+  return ka.every((k) => deepEqual(a[k], b[k]));
+}
+
+function verifyIntentBinding(intent, toolName, toolArgs, now = Date.now()) {
+  const intentHash = crypto.createHash("sha256").update(canonical(intent)).digest("hex");
+  const argsHash = crypto.createHash("sha256").update(canonical(toolArgs)).digest("hex");
+
+  // 1. TTL check
+  if (intent.ttl_ms != null && now - intent.issued_at > intent.ttl_ms) {
+    return {
+      allowed: false,
+      reason: { type: "intent_expired", expected: intent.issued_at + intent.ttl_ms, actual: now },
+      intent_hash: intentHash,
+      args_hash: argsHash,
+      tool: toolName,
+    };
+  }
+
+  // 2. Field-by-field comparison
+  const fields = intent.fields || {};
+  for (const [field, spec] of Object.entries(fields)) {
+    const actual = toolArgs[field];
+    const expected = spec.value;
+    const mode = spec.binding_mode || "exact";
+    let match = false;
+    if (mode === "exact") {
+      match = deepEqual(expected, actual);
+    } else if (mode === "numeric_tolerance") {
+      if (typeof expected === "number" && typeof actual === "number") {
+        match = Math.abs(expected - actual) <= (spec.tolerance || 0);
+      }
+    } else if (mode === "pattern") {
+      if (typeof actual === "string") {
+        try { match = new RegExp(spec.pattern).test(actual); } catch { match = false; }
+      }
+    }
+    if (!match) {
+      return {
+        allowed: false,
+        reason: {
+          type: "intent_arg_mismatch",
+          field, binding_mode: mode,
+          expected, actual,
+        },
+        intent_hash: intentHash,
+        args_hash: argsHash,
+        tool: toolName,
+      };
+    }
+  }
+
+  return {
+    allowed: true,
+    intent_hash: intentHash,
+    args_hash: argsHash,
+    tool: toolName,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // MCP Protocol (stdio JSON-RPC 2.0)
 // ---------------------------------------------------------------------------
@@ -357,6 +442,44 @@ const TOOLS = [
       required: ["config"],
     },
   },
+  {
+    name: "verify_intent_binding",
+    description: "Verify that actual tool call arguments match a declared intent with zero tolerance. Catches cross-model parameter drift (planner says amount=100, executor writes amount=10000). No LLM needed — pure deterministic comparison. Supports exact match, numeric tolerance, and regex pattern binding modes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        intent: {
+          type: "object",
+          description: "Structured intent declaration from the agent framework",
+          properties: {
+            intent_id: { type: "string", description: "Unique intent identifier (UUID v7 recommended)" },
+            intent_type: { type: "string", description: "e.g. payment, file_write, api_call" },
+            fields: {
+              type: "object",
+              description: "Map of field name to binding specification",
+              additionalProperties: {
+                type: "object",
+                properties: {
+                  value: { description: "Expected value" },
+                  binding_mode: { type: "string", enum: ["exact", "numeric_tolerance", "pattern"] },
+                  tolerance: { type: "number", description: "Tolerance for numeric_tolerance mode" },
+                  pattern: { type: "string", description: "Regex for pattern mode" },
+                },
+                required: ["value"],
+              },
+            },
+            issued_at: { type: "integer", description: "Unix ms when intent was issued" },
+            ttl_ms: { type: "integer", description: "Time-to-live in ms (default 30000)" },
+            evidence_ref: { type: "string", description: "Optional hash of external evidence (invoice, authorization VC)" },
+          },
+          required: ["intent_id", "intent_type", "fields", "issued_at"],
+        },
+        tool: { type: "string", description: "Tool being called, e.g. payments.send" },
+        arguments: { type: "object", description: "Actual tool call arguments", additionalProperties: true },
+      },
+      required: ["intent", "tool", "arguments"],
+    },
+  },
 ];
 
 function handleRequest(req) {
@@ -396,6 +519,23 @@ function handleRequest(req) {
       } else if (name === "audit_mcp_config") {
         const report = auditMcpConfig(args.config || {});
         result = { content: [{ type: "text", text: JSON.stringify(report, null, 2) }] };
+      } 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,
+        };
       } else {
         result = { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
       }