Trust Gate Mcp

Trust Gate MCP

作为 MCP 服务，为重要的 Agent 操作提供防篡改回执，并通过决策关卡返回 ALLOW、DENY 或 ESCALATE。

共提供 16 个工具：七个本地工具共用一个签名原语，开源项目 OpenAgentOntology 的 mint_receipt，以及九个可选的只读视图，用于查看 Trust Gate API（参见下文“只读 API 视图”）。

实际签名内容取决于你的安装方式——OAO 会在导入时检测其后端，因此值得坦诚说明这一点，而不是宣传最理想的情况：

安装方式	签名组成	说明
pip install trust-gate-mcp	Ed25519 + ML-DSA-65	默认配置。ML-DSA 部分来自 dilithium-py，这是一个纯 Python 库，其 README 明确指出不得用于密码学应用，且不具备恒定时间特性。它能确保回执可检测篡改，并满足 PQ-required 模式的要求，但应将该部分视为未经加固。
pip install "trust-gate-mcp[slh]"	Ed25519 + ML-DSA-65（原生后端）	安装 liboqs-python，这需要原生 liboqs 库；之后签名原语会优先使用 liboqs 实现 ML-DSA-65。只有当该 liboqs 仍包含 SPHINCS+-SHA2-128s-simple（一种预标准版本，与最终的 FIPS 205 标准不兼容）时，才会增加基于哈希的签名部分。liboqs-python 目前仅面向 liboqs 0.16.0，该版本已移除 SPHINCS+，因此截至 2026-09-29，这个额外安装项会提供原生 ML-DSA 后端，但不提供基于哈希的签名部分（尚未在安装 liboqs 的情况下验证）。如果无法导入 liboqs，该原语会静默回退到 dilithium-py；run_exit_drill 会显示当前使用的后端，以及基于哈希的签名部分是否可用。如果你在意后量子签名部分，请使用此安装方式。

PQ-required 验证（默认模式）要求至少有一个经过验证的后量子签名部分。这表示同一组字节上存在有效的后量子签名。这并不说明签名使用了谁的密钥（参见“有效回执能证明什么”），也不意味着默认后端达到了生产级标准。

工具	功能
mint_receipt_for_record_change	为 CRM 记录变更铸造回执。适用于任何 CRM（开源核心版 Relaticle、通过其自身 MCP 提供的托管 CRM、自定义 CRM）。新旧值均为 SHA-256 哈希（未加盐，因此可以从哈希猜出熵较低的值）。
audit_my_agent_inventory	按采取行动时可能造成的最大后悔程度，对调用方提供的 MCP 工具列表进行排序（基于名称的启发式方法，最看重名称的首词：delete_file 的排名高于 file_delete）。只读：不会铸造回执。 无法自动发现其他服务端——MCP 协议不允许这样做。非对象的行会报错，绝不会被静默跳过。
mint_action_receipt	为任何会造成重大后果的 Agent 操作生成回执。证明值（triggered_by_*、decision_model）是调用方声明：仅限安全字符，会经过签名，但不会验证。包含门控裁决词（allow、deny、escalate、grant、permit、approve、withheld、committed）的决策值、将 gate 作为词语的操作名称，以及门控自身的策略 ID，均会被拒绝。此检查尽力而为：若要将回执视为门控裁决，请固定签名者并检查已签名的 issuer_tool（见下文）。
verify_receipt	仅凭证书验证回执——离线进行，无需数据库。拒绝未签名的回执，检查 kid，并接受 expected_kid 以固定签名者（仅当该密钥自身的 Ed25519 签名验证通过时才计入）。默认启用 PQ 必需模式。返回 ok 时，会返回一个 verified 块（决策、证据哈希、签名时间、issuer_tool、operation 和完整的已验证 ontology 清单，包括操作和资源）：请读取这些值，而不要自行解析回执。
gate_decision	两阶段决策门控，提供真实裁决。PREVIEW 会返回 ALLOW、DENY 或 ESCALATE，以及风险等级和原因，但不会采取行动。COMMIT 会重新评估并为裁决铸造签名回执。只有 ALLOW 会返回 GRANTED 许可；DENY 返回 DENIED；ESCALATE 返回 WITHHELD_PENDING_HUMAN，由人工决定。见下文。
check_egress	检查数据样本中的敏感标记（有限的关键词列表、SSN 和卡号格式，以及常见凭据格式，包括 NAME=value 赋值），并将其标记为 NO_MARKERS_FOUND / INTERNAL / CONFIDENTIAL / RESTRICTED。符合凭据格式的值和个人标识符属于 RESTRICTED，并会设置 blocked: true；仅包含凭据关键词则属于 CONFIDENTIAL。看似在赋值密钥或密码的无害样本也可能被标记。它本身无法阻止任何操作：你的代码必须读取 blocked 并遵守其指示。NO_MARKERS_FOUND 并不代表获准发送。返回分类、保留信息和回执。
run_exit_drill	供应商退出就绪度演练。检查本地签名密钥（注明后量子后端及基于哈希的签名部分是否可用），并检查是否配置了本地模型端点（Ollama；不会连接该端点，远程主机不计入）。返回逐步检查结果和回执。仅供参考；它会签署一份回执，如果主机尚无签名密钥，则会创建该密钥。

只读 API 视图（可选，默认关闭）

九种工具可展示 Trust Gate API 根据你提供的记录计算出的结果。在设置 TRUST_GATE_API_URL（https；仅限 localhost 使用 http）、TRUST_GATE_API_KEY（为单个租户签发的 bearer 凭据）和 TRUST_GATE_TENANT_ID 之前，它们不会执行任何操作。上文的七种本地工具不需要这些设置，也绝不会调用外部服务。

工具	展示内容
inspect_oversight_case	单个监督案例的就绪情况报告
propose_role_question	针对某个案例分配给某个角色的问题。它只提出问题，不会向任何人提问
get_intervention_evidence	有关是否能够证明某项干预已生效的证据
compare_qualification_change	变更后每项拟议复测的状态：当前、非当前或未绑定
export_acceptance_pack	验收包导出，可选择映射到你指定的一个控制 ID 和版本
get_receipt_evidence	单个收据的证据视图，并说明服务能够和不能检查的内容
get_decision_evidence	某项决策及其事实的证据视图、判定和待解决问题
replay_decision	根据提供的记录重放一项决策的证据路径。它不会执行任何操作
propose_requalification	影响分析和重新鉴定方案。它绝不会运行复测

每种工具都接收一个对象 request，并将其作为调用正文转发。它们都遵循以下规则：

• 只读。 不会写入、签署、执行或授权任何内容。答复根据你传入的记录生成；其中的声明来自你，不是经过核实的事实。
• 租户由配置指定。 request 顶层不得指定租户；任何深度的租户键（任意大小写形式的 tenant、tenant_id、tenant-id、TenantId）都必须与 TRUST_GATE_TENANT_ID 相符，否则请求会在发起任何调用前被拒绝。只有 TRUST_GATE_TENANT_ID 会作为租户发送。
• 默认拒绝。 缺少设置、收到 404（该接口未启用或未部署）、遇到速率限制、服务器错误、传输错误或答复格式不正确时，都会返回带有 reason 的 status: "UNAVAILABLE"。API 拒绝请求时，会返回 REFUSED 和简短的 code。绝不会填充或提供默认数据。
• **绝不会记录或返回凭据，**也不会传递任何异常文本。
• 映射或读取结果并非合规结论。 每项结果都会说明这一点。
• 版本匹配。 收据、决策、重放、提案和重新鉴定视图（get_receipt_evidence、get_decision_evidence、replay_decision、propose_requalification、compare_qualification_change），以及案例、问题、证据和验收包视图，都需要由提供这些功能的 Trust Gate API 版本支持。若连接的是较旧的服务器，或相关接口已关闭，则在接口可用之前，这些视图会返回 UNAVAILABLE（surface_not_available）。
• 请求大小上限为 64 KiB；答复最多读取至 1 MiB（错误正文最多 4 KiB），不会继续读取。超时时间为 10 秒，不跟随重定向，并忽略代理环境变量。

此 Gate 的作用与不作用

• 范围。 它仅适用于你的代码通过 gate_decision 路由的操作。它不会观察、拦截或阻止 Agent 执行的任何操作，也不会事后检查操作是否已发生。你的代码（钩子、包装器）必须先发起询问，并遵守答复。
• ALLOW 是一个封闭列表。 只有当操作名称是已知的读取动词（read、get、list、search、query、find、show、view、inspect、describe）后面仅跟随小型内置词汇表中的名词（例如 read_file、list_files、search_files、list_dir、get_user、describe_table），名称是纯标识符，并且资源仅由该词汇表中的词、少量常见文档词（readme、guide、changelog……）以及源代码或散文文件类型（md、txt、py……）构成（词之间允许有数字，如 docs/2024/notes.md），操作才会获得 ALLOW。名称中包含任何其他词时，会升级为由人工审核，因为闸门未见过该名称。这是刻意设置得很窄的：大多数真实文件名都会升级。 扩展它意味着在源代码中向词汇表添加词，这是一个可见的更改。
• 结构规则也会触发升级。 隐藏路径（.env、.ssh、.git、..）、绝对路径、URL、路径首段为主机名（example.com/x、localhost）、任何常见写法的网络地址（任意位数的四段点分数字、十六进制、八进制，如 0177.1、一个长整数、0；短点分数字，如 1.2.3，仍视为版本号，除非最后一个数字超出版本号范围，或第一个数字是 0 或 127）、以 - 开头的资源、包含三个或更多词的短语、包含字母、数字、空格和 _ . - / 以外字符的任何内容（经过 Unicode 兼容性折叠后），以及实际类型属于配置、数据、密钥、状态或归档的文件（判断类型时忽略诸如 .1 的轮换计数器；点分名称中较早出现的已列出数据或归档类型也计入，例如 users.csv.txt）。资源中包含命令时也会升级：已列出的变更类词（alter、merge、flush、load……）、与其他词粘连的关键动词（deleteall），或 query 动词后面的任何多词资源。
• DENY 用于关键的首要动词（支付、删除、部署、代码执行、权限变更）。名称其他位置或资源中出现风险词时会升级，由人工决定；高风险首要动词（format、remove、reset、release、escalate）以及包含风险词的文件名（test_delete_user.py）也会触发升级。
• 风险词和敏感词均有明确列表，且列表有限。 已列出的机密和受监管数据词（password、token、key、pass、config、ssn、diagnosis……及其粘连形式、复数形式和数字替换形式）会为 HIGH 级别提供具体原因。阻止名称获得 ALLOW 的并不是这些列表（不在任何列表中的敏感名称仍会升级，因为 ALLOW 是封闭列表）。history 不是读取名词。匹配会跨越词边界，因此某些无害名称也会显示敏感原因（api/index.md 包含“pii”）。诸如 list_users 的查询属于普通读取：闸门不会判断它返回多少个人数据。名称包含同时也是风险动词的词的常见读取工具（get_email、list_messages）会升级。
• 这是基于名称的启发式规则，不是证明。 ALLOW 不代表操作安全：如果 Agent 将危险工具命名为 read_file 并调用，闸门不会发现，因为它检查的是名称，而非行为。context 会以哈希形式记录在回执中，不用于决策。此软件包没有操作员覆盖机制。
• 从回执中读取判定结果，并核验签发方。 receipt.decision（以及 receipt.evidence.ontology.verdict）经过签名。响应顶层的 verdict 和 permit 字段未经签名；verify_receipt 会列出其检查的任何回执中未签名的键。只有当使用 expected_kid 设置为你的服务端的 kid 调用 verify_receipt 后返回 signer_pinned: true，且 verified.issuer_tool 为 gate_decision、verified.operation 为 decision_gate_commit 时，回执才是来自你的服务端的闸门判定；其他每个工具都会对其自身的 issuer_tool 签名，而未固定签发方时，这些字段只是签名者提出的声明。
• 没有服务端会接受的回执，就不会授予许可。 只有在回执已铸造并签名，且按照此服务端自身的策略验证通过时，COMMIT 才会签发 GRANTED（在要求 PQ 的模式下，还必须包含有效的后量子签名）。
• 操作和资源会以明文记录在已签名的回执中。不要在其中放入机密或个人数据。
• 回执是判定结果的证据，不是日志条目。 atom_id 根据内容生成（取证据哈希的 40 位），因此相同的判定会共享同一个 ID，不同的判定也可能共享；应以 evidence_hash 和 signed_at 为键。服务端不会记录其签名的回执：请保存你需要的回执。系统不会检查重放或时效性：请将 evidence.ontology.action 和 resource 与即将执行的操作进行比较。
• 0.2.1 会对每个操作都返回 GRANTED。 请升级到 0.3.0 或更高版本。请参阅更新日志。

有效收据能证明什么

verify_receipt 返回 ok: true，表示证据自签名以来未被更改，收据带有签名，其中包含的任何 kid 都与其携带的密钥匹配，并且（在默认的 PQ-required 模式下）至少有一个后量子签名已针对相同字节验证通过。

这并不表示收据来自你信任的服务：任何人都可以生成密钥并签署收据。要检查签署者是谁，请传入 expected_kid（你通过带外渠道获知的、可信 Ed25519 密钥的 kid；32 个十六进制字符，忽略大小写和首尾空格；空白或格式错误的固定值会被拒绝）。只有当该密钥自己的 Ed25519 签名验证通过时，固定值才算有效；signer_pinned: true 表示验证通过（签名验证通过只能证明该密钥签署了这些字节，并不能证明有人持有其私钥：Ed25519 接受少数几个可以针对任意消息验证通过的特殊公钥，但这不会影响对你信任的密钥进行固定）；ok: true 且 signer_pinned: false 仅表示完整性验证通过；只有 Ed25519 签名验证通过时才会报告 kid。如果收据声明了 Ed25519 签署者（密钥或 kid），却没有该签署者的有效签名，收据就会被拒绝：这两个值都是公开的，可以复制到由其他密钥签署的收据中。

在 stdio 模式下，签名密钥以未加密形式存储在用户的主目录中，因此以该用户身份运行的 Agent 可以读取它：固定密钥无法防范你正在限制的那个 Agent。kid 仅为 Ed25519 密钥生成指纹。收据中的 ML-DSA 和基于哈希的密钥不受其保护，因此，面对量子攻击者时，固定密钥检查的安全性仅与 Ed25519 相当。结果还可能取决于验证主机安装了哪些后量子后端（无法检查的部分会报告为 unverifiable）。

加固

• H1 密钥持久化 + 引导时执行 FAIL-CLOSED kid 漂移检查（容器部署；引导过程仅检查 Ed25519 密钥）
• H2 按 IP 进行令牌桶速率限制（FIFO 淘汰）。它会像 MCP 传输层一样，从原始字节中精确解析请求正文（也支持读取字节顺序标记、UTF-16 和 UTF-32），并按正文中指定的工具计费；签名工具共用签名预算。无法解析的正文或超过 64 KiB 的正文会计入签名预算；请求正文一旦超过 1 MiB 就会立即以 413 拒绝（最多缓冲 1 MiB）。签名（使用默认后端时每次调用约 70 ms）和验证（约 20 ms）都在事件循环中运行，且预算按客户端单独计算，因此这类工作没有总量上限。客户端身份由 uvicorn 解析出的连接地址确定：将 TRUST_GATE_FORWARDED_ALLOW_IPS 设置为代理的地址，否则任何客户端都可以通过 X-Forwarded-For 标头选择自己的身份。
• H3 验证时要求 PQ：没有已验证的后量子签名（以及任何未签名的收据）都会被拒绝
• H4 每份生成的收据都包含 128 位 kid；根据规范化密钥字节重新计算，并在验证时检查
• 可选的 bearer 身份验证和更严格的 CORS 允许列表：通过 TRUST_GATE_BEARER_TOKEN + TRUST_GATE_ALLOWED_ORIGINS 配置
• 测试套件会逐一固定所有列出的动词、名词和敏感词（列表来自独立副本），并测试它们的词形变化、复数形式、粘连形式、数字替换形式和兼容字符形式；此外，还会测试针对收据伪造和移除 PQ 签名的对抗性用例；真实 MCP 请求会经过完整 HTTP 堆栈发送

通过 HTTP 部署

HTTP 入口点（server_http.py）是为容器映像编写的，其模块并排放置；使用 pip install 时，请使用 stdio 服务。Bearer 身份验证默认关闭，在该模式下，CORS 为 *。任何能够访问开放部署的人都可以获取使用其密钥签名的凭证，包括针对只读名称的“ALLOW”凭证；来自开放部署的凭证无法说明是谁发起了请求。如果你要托管它，请设置 TRUST_GATE_BEARER_TOKEN 和 TRUST_GATE_ALLOWED_ORIGINS。

HTTP 入口点会将 ?via=<label> 访问记录为一行日志（标签、类型、用户代理系列）。系统只记录三个内置标签以及 TRUST_GATE_CHANNELS 中指定的标签（以逗号分隔）；主机自己的访问日志也会记录请求行，包括客户端地址。

DNS 重绑定防护默认关闭，且没有开关：在没有 Bearer 身份验证的本地 HTTP 服务上，你访问的任何网页都可以调用它。请将其置于会检查 Host 标头的代理之后，或设置 TRUST_GATE_BEARER_TOKEN。

安装（stdio）

pip install trust-gate-mcp
trust-gate-mcp

添加 [slh] 以使用原生 ML-DSA 后端（见上表）。在代码库检出目录中，先运行 pip install -e ".[dev]"，然后运行 python -m trust_gate_mcp。

容器部署（Smithery / 任意容器主机）

docker build -t trust-gate-mcp .
docker run -p 8081:8081 -v trust-gate-data:/data/oao trust-gate-mcp

生产环境必须将卷挂载到 /data/oao：如果没有此挂载，每次容器重启都会更换签名密钥；重启前签名的凭证仍可通过其自身证书验证，但固定的 kid 将不再与新凭证匹配。持久化的 key_metadata.json 保存签名者的 kid；如果该值发生变化，引导步骤会拒绝启动。映像默认安装 dilithium-py；见上表。

许可证

Apache-2.0（完整文本见 LICENSE）。版权所有 © 2026 Cyber Warrior Network。基于开源 OpenAgentOntology 基元构建。