FransDevelopment/open-agent-trust-registry

# Open Agent Trust Registry [](https://github.com/FransDevelopment/open-agent-trust-registry/actions/workflows/manifest-compiler.yml) [](https://github.com/FransDevelopment/open-agent-trust-registry/actions/workflows/verify-registration.yml) [](https://www.npmjs.com/package/@open-agent-trust/cli) [](LICENSE) 一个公开的、联邦式的可信证明签发者注册表——即被授权为代表人类行事的 Agent 进行担保的 Agent 运行时。服务通过此注册表验证 Agent 证明，以确定签发该证明的运行时是否合法。 这充当了 Agent 互联网的 Certificate Authority（证书颁发机构）信任存储。 ## 问题背景 网站如何知道一个 AI Agent 是否真的被允许代表你执行操作？ 目前，如果你登录银行等网站，你会使用密码或 FaceID。银行知道那是*你*。但如果你告诉 AI Agent “去付我的网费”，Agent 需要一种方式向银行证明：“我是代表我的用户行事的授权 Agent。” 为此，Agent 会出示一个数字“ID 徽章”（称为 *Attestation*）。但任何人都可以伪造数字 ID 徽章。银行需要一种方法来验证该 ID 徽章是否由可信组织（如信誉良好的开发者、平台或运行时）签发，而不是由黑客签发。 **本注册表是可信徽章签发者的主名单。** 它的作用就像为你的 Web 浏览器中挂锁图标提供支持的系统（Certificate Authorities）。当网站看到 Agent 的徽章时，它会检查 Open Agent Trust Registry，以查看该徽章的签发者是否在批准名单上。 ## 工作原理（简述） 1. **蜡封（Ed25519 Cryptography）：** 组织创建一个私钥（一个秘密，就像印章戒指）并将其公钥发布到我们的注册表（戒指在蜡上留下的印记）。当他们向 Agent 签发 ID 徽章时，他们会用私钥为其盖章。当网站获得徽章时，他们会查看印章，在我们的注册表中检查公钥印记，如果匹配，则徽章是真实的。 2. **无许可注册：** 组织通过加密证明他们拥有其网站域名（如 `my-company.com`）来进行注册。我们的自动化 CI Pipeline 会立即将他们添加到注册表中。没有人工看门人，没有偏见。 3. **阈值治理：** 为了防止任何人（即使是创始人）恶意更改注册表，主名单由一把加密锁保护，需要 5 把钥匙中的 3 把才能打开。我们将这 5 把钥匙分发给独立的生态系统领导者。每次撤销都需要数学上可证明的共识。 ### Zero-Trust Mirror Servers 注册表的一个核心特性是 `manifest.json` 经过加密签名。正因为如此，**任何人都可以托管注册表镜像服务器而不会危及安全性。** 如果恶意行为者托管镜像服务器并试图秘密将黑客添加到列表中，则该文件的加密签名会失效。当网站下载该列表时，SDK 将立即检测到无效签名并拒绝整个文件。镜像服务器是“零信任信使”——它们可以分发数据，但无法伪造数据。 SDK 从检入的 `root-keys.json` 信任锚引导此验证，并拒绝被篡改和过期的注册表 Artifacts。 ## 设计原则 1. **从第一天起就开放。** MIT 或 Apache 2.0 许可。没有专有扩展，没有双重许可，没有“Open Core”。 2. **没有单一控制点。** 多镜像、多方签名、治理设计旨在超越创始维护者进行扩展。 3. **本地验证。** 服务永远不需要针对每个请求调用中央服务器。下载注册表，在本地验证。 4. **小且可审计。** 数百到数千个条目。任何人都可以在几分钟内阅读完整的注册表。 5. **加密可验证。** 每个注册表状态都已签名。每个更改都可归因。构造上即具备防篡改能力。 ## 快速入门 **要求：** Node.js 18+ ### 1. 生成 Keypair ``` npx @open-agent-trust/cli keygen --issuer-id my-runtime ``` 这将创建： - 一个 **private key** 文件（`my-runtime.private.pem`）——保密，永远不要提交它 - 一个打印到终端的 **public key**——用于注册和验证 稍后读取私钥：`cat my-runtime.private.pem` ### 2. 创建你的注册文件 ``` npx @open-agent-trust/cli register \ --issuer-id my-runtime \ --display-name "My Agent Runtime" \ --website https://my-runtime.com \ --contact security@my-runtime.com \ --public-key ``` 这将生成一个 `my-runtime.json` 文件。在提交之前查看 `capabilities` 块以匹配你的运行时的实际配置。 ### 3. 托管你的域名验证 证明你控制了在步骤 2 中声明的域名。CI 按顺序检查两个位置： **选项 A（推荐）：将 `oatr_issuer_id` 添加到你的 `agent.json`** 如果你的域名已经托管了 [`agent.json`](https://github.com/FransDevelopment/agent-json) manifest（v1.4+），请将你的 Issuer ID 添加到 Identity 块中： ``` { "version": "1.4", "origin": "my-runtime.com", "payout_address": "0x...", "identity": { "did": "did:web:my-runtime.com", "public_key": "", "oatr_issuer_id": "my-runtime" } } ``` **选项 B：托管独立的 `agent-trust.json`** 在 `https://my-runtime.com/.well-known/agent-trust.json`： ``` { "issuer_id": "my-runtime", "public_key_fingerprint": "my-runtime-2026-03" } ``` `public_key_fingerprint` 将你的域名绑定到你的注册。CI 接受：keygen 的 `kid`、base64url 公钥、公钥的 SHA-256 Hash（base64url）或十六进制格式的 `Trunc16(SHA-256)`。 ### 4. 生成你的 Key Ownership Proof ``` npx @open-agent-trust/cli prove \ --issuer-id my-runtime \ --private-key my-runtime.private.pem ``` 这将创建 `registry/proofs/my-runtime.proof`——这是一个加密证明，证明你控制着与注册中的公钥匹配的私钥。私钥用于签名，但**永远不会出现**在 Proof 文件中。有关格式规范，请参阅 [spec 11](spec/11-proof-of-key-ownership.md)。 ### 5. 提交你的注册 使用自动化 CLI 命令将你的注册直接提交到全局注册表。这将安全地分支、通过 Git Tree API 提交并代表你打开 Pull Request： ``` npx @open-agent-trust/cli submit \ --issuer-id my-runtime \ --github-token ``` **自动验证（Tier 1）：** CI Pipeline 检查三件事——有效的 Ed25519 Key、Proof-of-Key-Ownership 签名和域名验证。如果三者都通过，PR 将自动合并。无需人工批准。有关完整的分层模型，请参阅 [GOVERNANCE.md](GOVERNANCE.md)。 **自助 Key Rotation：** 你可以使用相同的流程自助撤销或轮换受损的密钥。注册表实施严格的双锚安全模型：*仅*当你的 `website` 和 `issuer_id` 保持不变时，才在加密允许修改的自动合并。这明确防止了域名劫持接管，同时保留了你在紧急事件响应中的代理权。 ### 6. 签发和验证 Attestations 注册后，你的运行时可以签署 Attestations（JWT）以担保其运行的 Agent： ``` # 签发测试 attestation npx @open-agent-trust/cli issue \ --issuer-id my-runtime \ --kid \ --private-key my-runtime.private.pem \ --audience https://target-api.com # 根据 registry 验证 attestation npx @open-agent-trust/cli verify --audience https://target-api.com ``` ### 7. 集成到你的应用程序 ``` npm install @open-agent-trust/registry ``` ``` import { OpenAgentTrustRegistry } from '@open-agent-trust/registry'; const registry = await OpenAgentTrustRegistry.load('https://your-mirror.example'); const result = await registry.verifyToken(jwt, 'https://your-api.com'); ``` ### 理解角色 | 角色 | 含义 | 示例 | |------|--------------|---------| | **Runtime Operator** | 代表用户运行 Agent。在 Trust Registry 中注册，以便 API 可以验证其 Agent 是合法的。 | Agent Internet Runtime, LangChain Cloud | | **API Provider** | 接受来自 Agent 的请求。验证 Attestations 以确保请求 Agent 已获授权。 | Stripe, OpenAI, 任何付费 API | | **Agent** | 代表用户行事。携带由其运行时签名的 Attestation 以证明其身份。 | 购物助手，代码审查员 | ### 签名如何工作 当你的运行时发送 Agent 调用第三方 API 时： 1. 你的后端使用步骤 1 中的私钥签署 JWT 2. JWT 表示：“我是 [你的运行时]，并且此 Agent 被授权代表用户 X 行事” 3. 目标 API 接收 JWT，在 Trust Registry 中查找你的公钥，并验证签名 4. 如果有效，API 信任该请求 这会在你的服务器代码中自动发生。私钥永远不会离开你的基础设施。 ## 与 `agent.json` 的关系 此注册表与 [agent.json](https://github.com/FransDevelopment/agent-json) 标准高度互补。它们服务于不同但相互加强的目的： - **`agent.json`**：由 *Agent 所有者* 托管在其域名上。确切声明 Agent 能够做什么、其 API 集成及其运营商。 - **Registry Manifest（`manifest.json`）**：由 *本 Open Agent Trust Registry* 集中托管。这是被授权执行和证明这些 Agent 的 *Trusted Runtimes*（Issuers）的精选列表。 通过结合这两者，服务既可以保证 Agent 意图是*什么*（通过 `agent.json`），也可以保证*谁*在安全地授权执行（通过 Open Agent Trust Registry）。 ## 两个信任问题 当 AI Agent 代表人们行事、支付费用、调用 API 并做出决策时，每个人都需要知道他们在与谁打交道。就像你不会把信用卡交给街上的陌生人一样，API 不应盲目信任一个出现并声称代表某人的 Agent。此注册表的存在是为了使 Agent 和 API 之间的信任可以加密验证，而无需依赖任何单一公司作为看门人。 有两个截然不同的信任问题。它们看起来很相似，但解决方法不同： ### 问题 1：“此 API 是真实的吗？”（API Provider 身份） 当 Agent 在 [Open 402 Directory](https://github.com/ArcedeDev/open-402) 中发现 API 时，它如何知道该 API 是合法的？ **由以下解决：agent.json Tier 3。** API Provider 将 DID（Decentralized Identifier）和公钥添加到其 `agent.json`。这就像公证过的营业执照。它在加密上证明 Provider 拥有该域名，而无需中央机构。 ``` { "identity": { "did": "did:web:example.com", "public_key": "base64url-encoded-ed25519-public-key" } } ``` ### 问题 2：“此 Agent 已获授权吗？”（Agent Runtime 信任） 当 AI Agent 出现在 API 并说“我代表用户行事”时，API 如何知道 Agent 是合法的？任何人都可以编写声称代表某人的 Bot。 **由以下解决：此注册表。** 它的工作方式类似于为浏览器中的挂锁提供支持的 Certificate Authority 系统： 1. Agent Runtimes 在此注册表中注册其公钥 2. 当 Runtime 发送 Agent 调用 API 时，Agent 携带签名的 Attestation（数字 ID 徽章） 3. API 根据此注册表检查 Attestation：“此 Runtime 在批准名单上吗？” 4. 如果签名与注册的 Runtime 匹配，则该 Agent 受到信任 ### 一切如何连接 | 层 | 回答 | 谁维护它 | |-------|---------|-----------------| | **[Open 402 Directory](https://github.com/ArcedeDev/open-402)** | “存在哪些付费 API？” | 社区（开放注册表） | | **agent.json**（在每个域名上） | “此 API 能做什么？”+“它能证明它拥有此域名吗？” | 每个 API Provider | | **此 Trust Registry** | “调用我的 Agent 是否由合法平台授权？” | 阈值治理（3-of-5 Keys） | | **On-chain 数据**（Base） | “是否真的有资金流经此 API？” | 区块链（不可变） | 每一层回答不同的信任问题。它们共同构成了 Agent 经济的完整信任基础设施，没有中央权威机构，每一层都可以独立验证。这使得 Agent 能够与他们从未见过的 API 进行交易，并且仍然知道他们是安全的。 ## 规范 架构和协议在 `spec/` 目录中定义： - [01: Data Model](spec/01-data-model.md) - [02: Registration Protocol](spec/02-registration.md) - [03: Verification Protocol](spec/03-verification.md) - [04: Key Rotation Protocol](spec/04-key-rotation.md) - [05: Revocation Protocol](spec/05-revocation.md) - [06: Mirroring Protocol](spec/06-mirroring.md) - [07: Attestation Format](spec/07-attestation-format.md) - [08: Security Model](spec/08-security-model.md) - [09: Service Integration Guidance](spec/09-service-integration.md) - [10: Encrypted Transport](spec/10-encrypted-transport.md) - [11: Proof of Key Ownership](spec/11-proof-of-key-ownership.md) ### 草案规范 - [Multi-Signature Ceremony](docs/multi-sig-ceremony.md) — 用于注册表治理的 3-of-5 Threshold Signing（FROST） ## 治理与贡献 该项目归社区所有。请参阅 [GOVERNANCE.md](GOVERNANCE.md) 以了解如何制定决策、如何管理密钥以及如何作为维护者加入。

标签：CA, CLI, JSONLines, Manifest, MITM代理, Modbus, Streamlit, Web安全, WiFi技术, 人工智能代理, 代理运行时, 信任根, 公钥基础设施, 分布式, 可信计算, 授权, 数字身份, 暗色界面, 注册表, 网络安全, 自动化攻击, 蓝队分析, 访问控制, 证明, 防伪造, 隐私保护, 零信任