ccs-mcp-server 1.2.17 → 1.3.0

package/README.md

@@ -1,150 +1,114 @@
-# CCS Runtime Evidence MCP Server
+# Agent Runtime Guard · Agent 运行时全栈拦截
 
 [![IETF Internet-Draft](https://img.shields.io/badge/IETF-draft--correctover--ccs-blue)](https://datatracker.ietf.org/doc/draft-correctover-ccs/)
-[![npm version](https://img.shields.io/npm/v/ccs-mcp-server.svg)](https://www.npmjs.com/package/ccs-mcp-server)
+[![npm version](https://img.shields.io/npm/v/agent-runtime-guard.svg)](https://www.npmjs.com/package/agent-runtime-guard)
 
-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.
+> **给 AI Agent 配一个运行时保安：它删库、偷密钥、闯内网、被注入诱导——当场拦下。**
+> 它是一道**运行时拦截层**，不是事后审计工具：危险动作在执行点就被挡住；每张 Ed25519 签名收据，都是拦截/放行时当场附带的裁决凭证。
 
-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.
+你给 Agent 接上 shell、网络、云凭证这些工具后，最大的风险是：**它手一抖，一条命令删掉整台机器；或被诱导，把密钥和数据偷偷传走。** 一个容易点过的"确认弹窗"挡不住。
 
-> **Runtime evidence layer, not a static scanner.** Every decision is enforced at call time and produces independently verifiable cryptographic evidence.
+`agent-runtime-guard` 在 **Agent 与危险操作之间**站一道确定性的拦截层——工具调用、shell 命令、网络请求、输出结果全栈覆盖，危险动作在**真正执行前**被 fail-closed 拦下，无需人工点击。
+
+- ✅ **零运行时依赖**，纯 Node.js 标准库（Node ≥ 18），无 install 脚本
+- ✅ **全栈拦截**：命令注入 / 路径穿越 / SSRF（含云元数据）/ 凭证外泄 / 提示注入 / 跨工具攻击链
+- ✅ **fail-closed**：判危险、验证器出错或超时，都不转发、不执行
+- ✅ **Ed25519 证据收据**：每次决策双哈希 + 可链，第三方可离线验证
+- ✅ **随处可用**：MCP server（Claude Code / Cursor / Cline / Windsurf）、透明 stdio 代理、DeepSeek Harness 插件
 
 ---
 
-## ⚡ Quick Start — running in 30 seconds
+## ⚡ 30 秒跑起来
 
 ```bash
-npx -y ccs-mcp-server
+npx -y agent-runtime-guard
 ```
 
-Add it to any MCP client — paste this into your `mcpServers` config in Claude Desktop, Cursor or Cline:
+把它加进任意 MCP 客户端的 `mcpServers` 配置：
 
 ```json
 {
   "mcpServers": {
-    "ccs-runtime-evidence": {
+    "agent-runtime-guard": {
       "command": "npx",
-      "args": ["-y", "ccs-mcp-server"]
+      "args": ["-y", "agent-runtime-guard"]
     }
   }
 }
 ```
 
-Or install from the official MCP Registry: search **"Correctover"** inside your client, or open [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/) and find `io.github.Correctover/ccs`.
-
-No API key, no account, no environment variables required — an Ed25519 signing key is generated automatically on first run (set `CCS_KEY_DIR`, or `CCS_PRIVATE_KEY`/`CCS_PUBLIC_KEY`, only if you want to pin a persistent key). Zero dependencies. Pure Node.js stdlib (Node ≥ 18). No install scripts.
-
-### 🇨🇳 免费验证之外 · 支付宝 SkillPay
-
-本服务的运行时验证与证据签发可免费使用。如果你需要人工深度审计或正式合规凭证，可以在支付宝 SkillPay 货架获取：
-
-- 货架首页：https://skillpay.alipay.com/public/correctover
-- 也可以在支持「支付宝 AI 付」的智能体对话里直接输入对应服务名唤起购买：
-  - **MCP配置安全体检**：`请通过 SkillPay 购买并安装 Skill「MCP配置安全体检」`
-  - **CCS收据批量审计**：`请通过 SkillPay 购买并安装 Skill「CCS收据批量审计」`
-  - **CCS收据验签**：`请通过 SkillPay 购买并安装 Skill「CCS收据验签」`
+无需 API key、账号或环境变量——首次运行自动生成 Ed25519 签名密钥（想固定持久密钥再设 `CCS_KEY_DIR` 或 `CCS_PRIVATE_KEY`/`CCS_PUBLIC_KEY`）。
 
-*Beyond the free verification: human-led deep audits and compliance evidence are available on the Alipay SkillPay shelf — open the link above, or type the service name (e.g. **CCS收据批量审计**) in an agent with Alipay AI Pay enabled.*
+---
 
-## 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` | 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). |
-| `verify_receipt` | Offline-verify a CCS Ed25519-signed receipt: checks the signature against the embedded signer public key, reports tampering, and optionally pins an expected signer key or fingerprint. |
-
-## Intent Binding — Cross-Model Drift Detection
+| **MCP 客户端**（Claude Code、Cursor、Cline、Windsurf） | 配置上面的 `mcpServers`，工具调用先过保安 |
+| **DeepSeek Harness** | `dsh plugin add agent-runtime-guard`，默认 bundle patch 自动启用，住进 `tools/pre-execute` / `post-execute` |
+| **网络边界独立拦一道** | 用透明 stdio 代理 [`agent-runtime-proxy`](https://www.npmjs.com/package/agent-runtime-proxy) 包住目标 MCP server，不信宿主内任何插件 |
 
-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:
-
-- **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
+---
 
-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.
+## 它拦什么
 
-### Example: amount drift
+- **命令注入**：shell 元字符、`curl|sh`、`rm -rf`、`eval()`
+- **路径穿越**：`../`、`/etc/passwd`、`/proc/self/`
+- **SSRF**：`169.254.169.254` 云元数据、localhost、私网地址——跨任何工具
+- **跨工具攻击链**：读敏感文件 → 网络外传 = `exfil_chain`
+- **凭证外泄**：API key、secret、credential 出现在参数或输出
+- **混淆提权**：hex/base64 编码、提权信号
+- **数值安全**：整数溢出（>2^53-1）、NaN/Infinity
+- **提示注入**：工具结果里的"忽略以上指令"等诱导
 
-```json
-// Intent declared by planner
-{
-  "intent_id": "int-001",
-  "intent_type": "payment",
-  "fields": {
-    "amount": { "value": 100, "binding_mode": "exact" },
-    "recipient": { "value": "Alice", "binding_mode": "exact" }
-  },
-  "issued_at": 1755000000000,
-  "ttl_ms": 30000
-}
+## Tools
 
-// Actual arguments from executor
-{ "amount": 10000, "recipient": "Alice" }
+| Tool | 用途 |
+|---|---|
+| `verify_tool_call` | 7 维运行时验证 + 语义攻击链分析 + 数值溢出检测，**默认拦截** |
+| `issue_evidence` | 出具防篡改证据（`content_hash` + `evidence_hash`，可链），放行和拦截都产生 |
+| `audit_mcp_config` | 审计 MCP 配置的安全风险 |
+| `verify_intent_binding` | 校验实际参数与声明意图是否一致——零容忍、零 LLM，抓跨模型参数漂移（规划写 `amount:100`，执行写成 `amount:10000` → 拦截） |
+| `verify_receipt` | 离线校验 Ed25519 收据签名、检测篡改，可固定可信签名者 |
 
-// Result: DENIED — intent_arg_mismatch
-// field: amount, expected: 100, actual: 10000
-```
+## 证据链
 
-### Three binding modes
+每次决策产生双哈希（`content_hash` + `evidence_hash`）与链指针（`parent_evidence_hash`）。任何第三方都能独立验证证据未被篡改，无需信任运营方。收据为 Ed25519 签名、JSON 形态，可用内置 `verify_receipt` 或任意 Ed25519 库离线验证。
 
-| 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"` |
+## FAQ（给 AI Agent 配运行时保安，常见疑问）
 
-No intent declared? Falls through to standard 7-dimension verification. Zero breaking changes.
+**黑名单为什么永远拦不全？** 危险命令可以用同义词、编码、拼接绕过，且新型调用不断出现。`agent-runtime-guard` 用语义判定（这段代码的意图是不是危险执行）而不是匹配关键词，未知攻击靠意图异常也能识别。
 
-## What It Detects
+**`Bash(prefix*)` 放行规则够安全吗？** 不够。`git status*` 这类前缀规则会被 `git status; rm -rf /`、`&&`、管道拼接绕过。判定应基于 shell 解析后的实际命令结构，而不是字符串前缀。
 
-- **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
+**安全判定能依赖宿主模型/远程分类器吗？** 不建议。远程服务一挂，要么全部拒绝（业务瘫痪）要么被建议绕过（裸奔）。本层策略在本地、默认 deny，裁决与模型可用性完全解耦。
 
-## Evidence Chain
+**子 agent 一开权限会被放大吗？** 会，这是真实出现过的问题：子 agent 把权限状态整个换成 allow-all。运行时权限状态应不可被子任务覆盖，并在每次实际调用时强制校验。
 
-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.
+**凭证为什么会自动泄露给子命令？** 子进程默认继承父进程全部环境变量，provider key、云凭证随之暴露给 `/run`、`/test` 等本不需要它们的命令。应按白名单最小化传递环境变量。
 
-```
-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
-```
+**拦了还是放了，事后怎么说清是谁的责任？** 每次裁决都出 Ed25519 签名收据（含内容哈希、时间、原因码、链指针），任何第三方可离线验证。这是把"AI 干的"变成可审计责任链的关键。
 
-Receipts are Ed25519-signed and JSON-based: verify them offline with the built-in `verify_receipt` tool, or independently with any Ed25519 library. Cross-tool receipt verification (same crypto, chain linkage, field mapping) is designed to work without this package installed.
+---
 
-## The 7 CCS Dimensions
+## 🇨🇳 免费验证之外 · 支付宝 SkillPay
 
-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, env exfiltration, obfuscation + semantic attack chains
-4. **Identity** — caller agent ID verification
-5. **Integrity** — request hash validation
-6. **Latency** — execution time budget
-7. **Cost** — cost budget
+运行时验证与证据签发免费使用。如需人工深度审计或正式合规凭证，可在支付宝 SkillPay 货架获取：https://skillpay.alipay.com/public/correctover
 
-## Protocol Context
+## 协议背景
 
-- **IETF**: [draft-correctover-ccs](https://datatracker.ietf.org/doc/draft-correctover-ccs/) — an individual Internet-Draft; not an RFC or IETF endorsement, and the Datatracker page is authoritative for revision and status
-- **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
+- **IETF**：[draft-correctover-ccs](https://datatracker.ietf.org/doc/draft-correctover-ccs/) —— 个人 Internet-Draft，**不是 RFC，也不代表 IETF 背书**，Datatracker 页面为权威状态
+- **互补**：VAP（范围/预算/目的）、Microsoft ACS（策略决策）、AP2（人工授权）
+- **不替代**：认证、支付网络、策略引擎
 
 ## Links
 
-- npm: https://www.npmjs.com/package/ccs-mcp-server
-- GitHub: https://github.com/DSHCorrectover/ccs-mcp-server
+- npm: https://www.npmjs.com/package/agent-runtime-guard
+- GitHub: https://github.com/DSHCorrectover/agent-runtime-guard
+- 透明代理: https://github.com/DSHCorrectover/agent-runtime-proxy
 - IETF Draft: https://datatracker.ietf.org/doc/draft-correctover-ccs/
-- PyPI (full verifier): https://pypi.org/project/ccs-verifier/
+- PyPI 完整验证器: https://pypi.org/project/ccs-verifier/
 
 ## License
 

package/package.json

@@ -1,52 +1,65 @@
 {
   "name": "ccs-mcp-server",
-  "version": "1.2.17",
-  "description": "MCP security server for AI agents — runtime verification and receipt verification for Claude Code, Cursor, Cline and Windsurf. 7-dimension CCS checks, Ed25519 tamper-evident receipts, offline verification, zero runtime dependencies.",
+  "version": "1.3.0",
+  "description": "MCP security server for AI agents — runtime verification, receipt verification and field-level tamper localization for Claude Code, Cursor, Cline and Windsurf. 7-dimension CCS checks, Ed25519 tamper-evident receipts, offline verification, zero runtime dependencies.",
   "type": "commonjs",
   "bin": {
     "ccs-mcp-server": "src/index.js"
   },
   "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./receipts": "./src/receipts.js",
+    "./tamper": "./src/locate_tampering.js",
+    "./package.json": "./package.json"
+  },
   "files": [
     "src",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "test"
   ],
   "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "mcp-server",
-    "mcp-security",
+    "agent-guard",
+    "agent-runtime",
+    "agent-security",
+    "ai-agent-security",
     "claude",
     "claude-code",
-    "cursor",
     "cline",
-    "windsurf",
-    "ai-agent",
-    "ai-agent-security",
-    "agent-security",
-    "runtime-verification",
-    "receipt-verification",
-    "agent-receipt",
+    "command-injection",
+    "correctover",
+    "credential-protection",
+    "cursor",
+    "deepseek-harness",
+    "dsh-plugin",
     "ed25519",
+    "fail-closed",
+    "forensics",
+    "json-pointer",
+    "mcp",
+    "mcp-security",
+    "mcp-server",
+    "model-context-protocol",
+    "prompt-injection",
+    "rfc6901",
+    "runtime-interception",
+    "runtime-verification",
+    "ssrf",
+    "supply-chain-security",
     "tamper-evident",
-    "offline-verification",
+    "tamper-localization",
     "tool-call-guardrail",
-    "mcp security audit",
-    "ccs",
-    "correctover",
-    "decision-provenance",
-    "json-rpc",
-    "supply-chain-security"
+    "windsurf"
   ],
   "license": "Elastic-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/DSHCorrectover/ccs-mcp-server.git"
   },
-  "homepage": "https://github.com/DSHCorrectover/ccs-mcp-server#readme",
+  "homepage": "https://github.com/DSHCorrectover/agent-runtime-guard#readme",
   "bugs": {
-    "url": "https://github.com/DSHCorrectover/ccs-mcp-server/issues"
+    "url": "https://github.com/DSHCorrectover/agent-runtime-guard/issues"
   },
   "engines": {
     "node": ">=18"
@@ -55,10 +68,5 @@
   "scripts": {
     "test": "node test/run-tests.js"
   },
-  "mcp": {
-    "name": "ccs-runtime-evidence",
-    "displayName": "CCS Runtime Evidence",
-    "description": "Verify AI agent tool calls and issue Ed25519-signed CCS evidence receipts."
-  },
   "mcpName": "io.github.DSHCorrectover/ccs-mcp-server"
 }

package/src/index.js

@@ -11,6 +11,9 @@
  *   verify_tool_call   Verify a tool call against CCS 7 dimensions + semantic + math
  *   issue_evidence     Issue a signed CCS evidence record (allow + deny)
  *   audit_mcp_config   Audit an MCP server configuration for security risks
+ *   verify_intent_binding  Verify call arguments match declared intent
+ *   verify_receipt     Offline-verify a CCS Ed25519-signed receipt
+ *   locate_tampering   Field-level localization of which fields differ (RFC 6901)
  *
  * Transport: stdio (per MCP spec). To run:
  *   npx @correctover/ccs-mcp-server
@@ -28,6 +31,7 @@ const crypto = require("crypto");
 const readline = require("readline");
 const receipts = require("./receipts");
 const skillpay = require("./skillpay");
+const tamper = require("./locate_tampering");
 
 // ---------------------------------------------------------------------------
 // CCS Verifier Core (pure stdlib Node.js)
@@ -604,6 +608,38 @@ const TOOLS = [
       required: ["receipt"],
     },
   },
+  {
+    name: "locate_tampering",
+    title: "Locate which fields differ between two artifacts",
+    description:
+      "Field-level tamper localization. Given an original and a suspect artifact, returns an " +
+      "RFC 6901 JSON-Pointer list of every changed field with change type, before/after values, " +
+      "severity, and remediation. This is what verify_receipt alone cannot tell you: it says WHICH " +
+      "field changed, not merely that the signature failed. Severity is assigned by field semantics " +
+      "(verdict-bearing fields are critical), not by diff size.",
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        original: {
+          type: "object",
+          description: "The trusted/original artifact (receipt, evidence record, or config).",
+          additionalProperties: true,
+        },
+        suspect: {
+          type: "object",
+          description: "The artifact to compare against the original.",
+          additionalProperties: true,
+        },
+      },
+      required: ["original", "suspect"],
+    },
+  },
 ];
 
 function handleRequest(req) {
@@ -649,6 +685,18 @@ function handleRequest(req) {
           content: [{ type: "text", text: JSON.stringify(verdict, null, 2) }],
           isError: verdict.allowed === false,
         };
+      } else if (name === "locate_tampering") {
+        if (typeof args.original !== "object" || args.original === null ||
+            typeof args.suspect !== "object" || args.suspect === null) {
+          result = {
+            content: [{ type: "text",
+              text: "Error: both 'original' and 'suspect' must be JSON objects." }],
+            isError: true,
+          };
+        } else {
+          const report = tamper.buildReport(args.original, args.suspect);
+          result = { content: [{ type: "text", text: JSON.stringify(report, null, 2) }] };
+        }
       } else if (name === "verify_receipt") {
         const v = args.expected_signer
           ? receipts.verifyReceiptWithKey(args.receipt, args.expected_signer)
@@ -692,4 +740,4 @@ function main() {
 }
 
 if (require.main === module) main();
-module.exports = { verifyCall, auditMcpConfig, verifyIntentBinding, receipts };
+module.exports = { verifyCall, auditMcpConfig, verifyIntentBinding, receipts, tamper };

package/src/locate_tampering.js

@@ -0,0 +1,240 @@
+"use strict";
+/**
+ * CCS 字段级篡改定位 —— locate_tampering
+ *
+ * 为什么需要这个（它不是 verify_receipt 的替代品）:
+ *   verify_receipt 回一个布尔：签名对不对。审计人员拿到 false 之后
+ *   仍然不知道**哪里被改了**。要把话说清楚、要能举证，需要一份差异清单。
+ *
+ *   本模块产出 RFC 6901 JSON-Pointer 形式的字段变更清单，
+ *   每条带变化类型、原值、新值、严重度与整改建议。
+ *
+ * 与 Python 侧 correctover-ccs-mcp 的 ccs_locate_tampering 输出结构对齐，
+ * 使两个渠道（npm 运行时 / PyPI 取证）给出同一份证据格式。
+ *
+ * 零依赖：仅 crypto 用于可选的内容摘要。
+ *
+ * License: Elastic-2.0 (c) Correctover
+ */
+
+const crypto = require("crypto");
+
+// ---------------------------------------------------------------------------
+// RFC 6901 JSON-Pointer 转义
+// ---------------------------------------------------------------------------
+
+function pointerEscape(token) {
+  // 顺序不可颠倒：必须先转义 ~，否则会把 / 转出来的 ~1 再转一次
+  return String(token).replace(/~/g, "~0").replace(/\//g, "~1");
+}
+
+function joinPointer(base, token) {
+  return base + "/" + pointerEscape(token);
+}
+
+// ---------------------------------------------------------------------------
+// 严重度：按字段语义分级，不是按"改了多少字节"
+//
+// 设计取舍：改一个字符的 verdict 比改一百个字符的 latency 严重得多。
+// 分级的依据是**这个字段决定谁的结论**，不是差异大小。
+// ---------------------------------------------------------------------------
+
+const CRITICAL_EXACT = [
+  "/verdict", "/signature", "/signer_public_key", "/signature_alg",
+  "/evidence_hash", "/content_hash", "/receipt_id", "/instruction_digest",
+];
+const CRITICAL_PREFIX = ["/checks/", "/policy/", "/decision"];
+const HIGH_EXACT = [
+  "/reason", "/allowed", "/action", "/tool", "/principal", "/subject",
+  "/policy_mode", "/delegation",
+];
+const MEDIUM_PREFIX = ["/latency", "/cost", "/model", "/provider", "/intent"];
+
+function classifySeverity(pointer) {
+  if (CRITICAL_EXACT.includes(pointer)) return "critical";
+  if (CRITICAL_PREFIX.some((p) => pointer.startsWith(p))) return "critical";
+  if (HIGH_EXACT.includes(pointer)) return "high";
+  if (MEDIUM_PREFIX.some((p) => pointer.startsWith(p))) return "medium";
+  return "low";
+}
+
+const REMEDIATION = {
+  critical:
+    "A verdict-bearing field changed. Treat the artifact as untrusted: do not act on it, " +
+    "re-derive the conclusion from the original source, and re-issue the receipt.",
+  high:
+    "A context field changed. Confirm with the counterparty which version is authoritative " +
+    "before relying on either.",
+  medium:
+    "An operational field changed. Usually affects interpretation rather than the verdict; " +
+    "verify if it feeds a downstream decision.",
+  low:
+    "A non-decisional field changed. Low impact; record for completeness.",
+};
+
+// ---------------------------------------------------------------------------
+// 深度差异
+// ---------------------------------------------------------------------------
+
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+/**
+ * 返回字段级变更清单。
+ * 数组按**下标**逐项比较，不用集合语义——收据里的数组是有序的，
+ * 把 [a,b] 与 [b,a] 判为"相同"会漏掉真实的顺序篡改。
+ */
+function deepDiff(original, suspect, base = "") {
+  const changes = [];
+
+  const bothObjects = isPlainObject(original) && isPlainObject(suspect);
+  const bothArrays = Array.isArray(original) && Array.isArray(suspect);
+
+  if (bothObjects) {
+    const keys = new Set([...Object.keys(original), ...Object.keys(suspect)]);
+    for (const k of Array.from(keys).sort()) {
+      const ptr = joinPointer(base, k);
+      const hasO = Object.prototype.hasOwnProperty.call(original, k);
+      const hasS = Object.prototype.hasOwnProperty.call(suspect, k);
+      if (hasO && !hasS) {
+        changes.push(mk(ptr, "removed", original[k], undefined));
+      } else if (!hasO && hasS) {
+        changes.push(mk(ptr, "added", undefined, suspect[k]));
+      } else {
+        changes.push(...deepDiff(original[k], suspect[k], ptr));
+      }
+    }
+    return changes;
+  }
+
+  if (bothArrays) {
+    const n = Math.max(original.length, suspect.length);
+    for (let i = 0; i < n; i++) {
+      const ptr = joinPointer(base, i);
+      if (i >= original.length) {
+        changes.push(mk(ptr, "added", undefined, suspect[i]));
+      } else if (i >= suspect.length) {
+        changes.push(mk(ptr, "removed", original[i], undefined));
+      } else {
+        changes.push(...deepDiff(original[i], suspect[i], ptr));
+      }
+    }
+    return changes;
+  }
+
+  if (!sameScalar(original, suspect)) {
+    changes.push(mk(base || "/", "modified", original, suspect));
+  }
+  return changes;
+}
+
+function sameScalar(a, b) {
+  if (a === b) return true;
+  if (typeof a === "number" && typeof b === "number" && Number.isNaN(a) && Number.isNaN(b)) {
+    return true;
+  }
+  if (isPlainObject(a) || isPlainObject(b) || Array.isArray(a) || Array.isArray(b)) {
+    // 类型不一致（对象 vs 标量）：交给 JSON 比较判等
+    return JSON.stringify(a) === JSON.stringify(b);
+  }
+  return false;
+}
+
+function preview(v) {
+  if (v === undefined) return null;
+  if (typeof v === "string") return v.length > 200 ? v.slice(0, 200) + "…" : v;
+  try {
+    const s = JSON.stringify(v);
+    return s && s.length > 200 ? s.slice(0, 200) + "…" : v;
+  } catch {
+    return String(v);
+  }
+}
+
+function mk(pointer, change, original, suspect) {
+  const severity = classifySeverity(pointer);
+  return {
+    path: pointer,
+    path_format: "rfc6901",
+    change,
+    original: preview(original),
+    suspect: preview(suspect),
+    severity,
+    remediation: REMEDIATION[severity],
+    // 兼容既有消费方（Python 侧曾输出点号路径）
+    path_dotted: pointer.replace(/^\//, "").replace(/\//g, "."),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 报告
+// ---------------------------------------------------------------------------
+
+function digestOf(obj) {
+  try {
+    return "sha256:" + crypto
+      .createHash("sha256")
+      .update(JSON.stringify(sortDeep(obj)))
+      .digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+function sortDeep(v) {
+  if (Array.isArray(v)) return v.map(sortDeep);
+  if (isPlainObject(v)) {
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = sortDeep(v[k]);
+    return out;
+  }
+  return v;
+}
+
+function buildReport(original, suspect) {
+  const changes = deepDiff(original, suspect);
+  const counts = { critical: 0, high: 0, medium: 0, low: 0 };
+  for (const c of changes) counts[c.severity]++;
+
+  const originalDigest = digestOf(original);
+  const suspectDigest = digestOf(suspect);
+
+  let conclusion;
+  if (changes.length === 0) {
+    conclusion =
+      "No field-level differences found between the two artifacts. " +
+      "Note: this compares content only; it does not by itself prove either artifact is authentic.";
+  } else if (counts.critical > 0) {
+    conclusion =
+      `${changes.length} field(s) differ, including ${counts.critical} verdict-bearing field(s). ` +
+      "At least one change affects the conclusion itself, so the two artifacts are not interchangeable.";
+  } else {
+    conclusion =
+      `${changes.length} field(s) differ. None are verdict-bearing; differences are likely ` +
+      "operational or contextual rather than decisional.";
+  }
+
+  return {
+    schema: "correctover.tamper-localization.v1",
+    tampered: changes.length > 0,
+    counts,
+    changes,
+    digests: { original: originalDigest, suspect: suspectDigest },
+    conclusion,
+    limitations: [
+      "This compares two artifacts you supplied. It does not prove which one is authentic.",
+      "It reports content differences only; it does not verify any cryptographic signature.",
+      "Pair it with verify_receipt to establish authenticity, then use this to localize the change.",
+    ],
+  };
+}
+
+module.exports = {
+  deepDiff,
+  buildReport,
+  classifySeverity,
+  pointerEscape,
+  joinPointer,
+  digestOf,
+};

package/test/run-tests.js

@@ -0,0 +1,259 @@
+"use strict";
+/**
+ * locate_tampering 测试套件
+ *
+ * 关键断言不是"函数能跑"，而是三件事：
+ *   1) 字段级定位真的指向**正确的指针**（RFC 6901 转义正确）
+ *   2) 严重度按**字段语义**分级，不按差异大小
+ *   3) 数组顺序变更必须被检出（不能退化成集合比较）
+ *
+ * 运行： node test/run-tests.js
+ */
+
+const assert = require("assert");
+const t = require("../src/locate_tampering");
+
+let passed = 0, failed = 0;
+const failures = [];
+
+function test(name, fn) {
+  try {
+    fn();
+    passed++;
+    console.log(`  PASS  ${name}`);
+  } catch (e) {
+    failed++;
+    failures.push({ name, msg: e.message });
+    console.log(`  FAIL  ${name}\n        ${e.message}`);
+  }
+}
+
+console.log("locate_tampering 测试套件\n");
+
+// ---------------------------------------------------------------------------
+console.log("1. JSON-Pointer 转义（RFC 6901）");
+// ---------------------------------------------------------------------------
+
+test("普通 token 不变", () => {
+  assert.strictEqual(t.pointerEscape("checks"), "checks");
+});
+
+test("~ 转义为 ~0", () => {
+  assert.strictEqual(t.pointerEscape("a~b"), "a~0b");
+});
+
+test("/ 转义为 ~1", () => {
+  assert.strictEqual(t.pointerEscape("a/b"), "a~1b");
+});
+
+test("~ 先于 / 转义（顺序敏感）", () => {
+  // "~/" 必须变成 "~0~1"，
+  // 若先转 / 会得到 "~~1" 再转 ~ 成 "~0~1"……不，先转 / 会错成 "~~01"
+  assert.strictEqual(t.pointerEscape("~/"), "~0~1");
+});
+
+test("含 / 的 key 仍产生合法单段指针", () => {
+  const ptr = t.joinPointer("", "a/b");
+  assert.strictEqual(ptr, "/a~1b");
+  // 指针段数必须是 1（因为 / 被转义了）
+  assert.strictEqual(ptr.split("/").length - 1, 1);
+});
+
+// ---------------------------------------------------------------------------
+console.log("\n2. 差异检出");
+// ---------------------------------------------------------------------------
+
+test("无差异返回空清单", () => {
+  const a = { x: 1, y: { z: "ok" } };
+  assert.strictEqual(t.deepDiff(a, JSON.parse(JSON.stringify(a))).length, 0);
+});
+
+test("标量修改被检出且指针正确", () => {
+  const d = t.deepDiff({ verdict: "valid" }, { verdict: "invalid" });
+  assert.strictEqual(d.length, 1);
+  assert.strictEqual(d[0].path, "/verdict");
+  assert.strictEqual(d[0].change, "modified");
+  assert.strictEqual(d[0].original, "valid");
+  assert.strictEqual(d[0].suspect, "invalid");
+});
+
+test("嵌套字段指针用 / 分隔", () => {
+  const d = t.deepDiff(
+    { checks: { security: { status: "pass" } } },
+    { checks: { security: { status: "fail" } } }
+  );
+  assert.strictEqual(d[0].path, "/checks/security/status");
+});
+
+test("新增字段标 added 且 original 为 null", () => {
+  const d = t.deepDiff({ a: 1 }, { a: 1, b: 2 });
+  assert.strictEqual(d.length, 1);
+  assert.strictEqual(d[0].change, "added");
+  assert.strictEqual(d[0].path, "/b");
+  assert.strictEqual(d[0].original, null);
+});
+
+test("删除字段标 removed", () => {
+  const d = t.deepDiff({ a: 1, b: 2 }, { a: 1 });
+  assert.strictEqual(d[0].change, "removed");
+  assert.strictEqual(d[0].path, "/b");
+});
+
+test("数组按下标比较，顺序变更被检出", () => {
+  // 关键：不能用集合语义，否则 ["a","b"] vs ["b","a"] 会被判为相同
+  const d = t.deepDiff({ list: ["a", "b"] }, { list: ["b", "a"] });
+  assert.ok(d.length > 0, "顺序变更必须被检出");
+  const paths = d.map((c) => c.path).sort();
+  assert.deepStrictEqual(paths, ["/list/0", "/list/1"]);
+});
+
+test("数组长度变化：新增项标 added", () => {
+  const d = t.deepDiff({ l: [1] }, { l: [1, 2] });
+  assert.strictEqual(d.length, 1);
+  assert.strictEqual(d[0].path, "/l/1");
+  assert.strictEqual(d[0].change, "added");
+});
+
+test("类型变更（对象→标量）被检出", () => {
+  const d = t.deepDiff({ a: { b: 1 } }, { a: "flat" });
+  assert.strictEqual(d.length, 1);
+  assert.strictEqual(d[0].path, "/a");
+});
+
+test("深层多处修改全部报出", () => {
+  const o = { v: "valid", lat: 12, c: { s: { st: "pass", d: "ok" } } };
+  const s = { v: "invalid", lat: 71, c: { s: { st: "fail", d: "ok" } } };
+  const d = t.deepDiff(o, s);
+  const paths = d.map((c) => c.path).sort();
+  assert.deepStrictEqual(paths, ["/c/s/st", "/lat", "/v"]);
+});
+
+// ---------------------------------------------------------------------------
+console.log("\n3. 严重度按字段语义（不是按差异大小）");
+// ---------------------------------------------------------------------------
+
+test("verdict 为 critical", () => {
+  assert.strictEqual(t.classifySeverity("/verdict"), "critical");
+});
+
+test("checks 下任意深度均为 critical", () => {
+  assert.strictEqual(t.classifySeverity("/checks/security/status"), "critical");
+  assert.strictEqual(t.classifySeverity("/checks/a/b/c/d"), "critical");
+});
+
+test("reason 为 high", () => {
+  assert.strictEqual(t.classifySeverity("/reason"), "high");
+});
+
+test("latency 为 medium", () => {
+  assert.strictEqual(t.classifySeverity("/latency_ms"), "medium");
+});
+
+test("未知字段为 low", () => {
+  assert.strictEqual(t.classifySeverity("/some_unknown_field"), "low");
+});
+
+test("改一个字符的 verdict 比改大对象的 latency 更严重", () => {
+  const d = t.deepDiff(
+    { verdict: "valid", latency_ms: 1 },
+    { verdict: "invali", latency_ms: 99999 }
+  );
+  const byPath = Object.fromEntries(d.map((c) => [c.path, c.severity]));
+  assert.strictEqual(byPath["/verdict"], "critical");
+  assert.strictEqual(byPath["/latency_ms"], "medium");
+  const rank = { critical: 3, high: 2, medium: 1, low: 0 };
+  assert.ok(rank[byPath["/verdict"]] > rank[byPath["/latency_ms"]]);
+});
+
+// ---------------------------------------------------------------------------
+console.log("\n4. 报告结构");
+// ---------------------------------------------------------------------------
+
+test("报告带 schema 标识", () => {
+  const r = t.buildReport({ a: 1 }, { a: 2 });
+  assert.strictEqual(r.schema, "correctover.tamper-localization.v1");
+});
+
+test("tampered 在有差异时为 true", () => {
+  assert.strictEqual(t.buildReport({ a: 1 }, { a: 2 }).tampered, true);
+});
+
+test("tampered 在无差异时为 false", () => {
+  assert.strictEqual(t.buildReport({ a: 1 }, { a: 1 }).tampered, false);
+});
+
+test("counts 按严重度汇总", () => {
+  const r = t.buildReport(
+    { verdict: "valid", reason: "x", latency_ms: 1 },
+    { verdict: "invalid", reason: "y", latency_ms: 2 }
+  );
+  assert.strictEqual(r.counts.critical, 1);
+  assert.strictEqual(r.counts.high, 1);
+  assert.strictEqual(r.counts.medium, 1);
+});
+
+test("结论在存在 critical 时明确说明不可互换", () => {
+  const r = t.buildReport({ verdict: "valid" }, { verdict: "invalid" });
+  assert.ok(/not interchangeable/i.test(r.conclusion), r.conclusion);
+});
+
+test("结论在无 critical 时不夸大", () => {
+  const r = t.buildReport({ latency_ms: 1 }, { latency_ms: 2 });
+  assert.ok(/likely operational|None are verdict-bearing/i.test(r.conclusion), r.conclusion);
+});
+
+test("无差异时结论不声称真实性", () => {
+  const r = t.buildReport({ a: 1 }, { a: 1 });
+  assert.ok(/does not by itself prove/i.test(r.conclusion), r.conclusion);
+});
+
+test("limitations 明确不做真实性判断", () => {
+  const r = t.buildReport({ a: 1 }, { a: 2 });
+  assert.ok(r.limitations.some((l) => /does not prove which one is authentic/i.test(l)));
+  assert.ok(r.limitations.some((l) => /does not verify any cryptographic signature/i.test(l)));
+});
+
+test("每条变更都带整改建议", () => {
+  const r = t.buildReport({ verdict: "a" }, { verdict: "b" });
+  assert.ok(r.changes.every((c) => typeof c.remediation === "string" && c.remediation.length > 10));
+});
+
+test("digests 对相同内容稳定", () => {
+  const a = t.buildReport({ x: 1, y: 2 }, { x: 1, y: 2 });
+  const b = t.buildReport({ y: 2, x: 1 }, { y: 2, x: 1 });
+  assert.strictEqual(a.digests.original, b.digests.original,
+    "键顺序不同不应导致摘要不同");
+});
+
+// ---------------------------------------------------------------------------
+console.log("\n5. 与 Python 侧输出对齐");
+// ---------------------------------------------------------------------------
+
+test("path_dotted 兼容字段存在且格式正确", () => {
+  const d = t.deepDiff(
+    { checks: { security: { status: "pass" } } },
+    { checks: { security: { status: "fail" } } }
+  );
+  assert.strictEqual(d[0].path_dotted, "checks.security.status");
+});
+
+test("path_format 声明为 rfc6901", () => {
+  const d = t.deepDiff({ a: 1 }, { a: 2 });
+  assert.strictEqual(d[0].path_format, "rfc6901");
+});
+
+test("指针与点号路径同时可查（既有消费方不被破坏）", () => {
+  const d = t.deepDiff({ a: { b: 1 } }, { a: { b: 2 } })[0];
+  assert.strictEqual(d.path, "/a/b");
+  assert.strictEqual(d.path_dotted, "a.b");
+});
+
+// ---------------------------------------------------------------------------
+console.log(`\n${"=".repeat(52)}`);
+console.log(`  ${passed}/${passed + failed} PASS`);
+console.log(`${"=".repeat(52)}`);
+if (failures.length) {
+  console.log("\n失败明细：");
+  for (const f of failures) console.log(`  - ${f.name}\n    ${f.msg}`);
+}
+process.exit(failed ? 1 : 0);