identities-ai/ratify-protocol
GitHub: identities-ai/ratify-protocol
面向 AI 代理授权的开源密码学信任协议，通过混合后量子签名生成可离线验证的委托证明，解决「谁授权了什么、范围多大、多久有效」的核心信任问题。
Stars: 2 | Forks: 0
# Ratify Protocol™
[](https://github.com/identities-ai/ratify-protocol/actions/workflows/ci.yml)
[](https://github.com/identities-ai/ratify-protocol/releases)
[](LICENSE)
[](docs/LICENSES.md)
[](#license--trademarks--patent)
[](https://pkg.go.dev/github.com/identities-ai/ratify-protocol)
[](https://pypi.org/project/ratify-protocol/)
[](https://crates.io/crates/ratify-protocol)
[](https://www.npmjs.com/package/@identities-ai/ratify-protocol)
**一种用于人与代理以及代理与代理之间交互的密码学信任协议。**
当一个人授权 AI 代理——或者当一个代理与另一个代理进行交互时——Ratify 会生成一份经过签名的、可验证的证明，精确地说明*谁*授权了*什么*，*在什么范围之内*，以及*授权多久*。对话中的任何一方都可以在不到一毫秒的时间内验证该证明，适用于语音、视频、API 和物理 AI。
**设计上具备量子安全性。** 每一个签名都是混合的：Ed25519 + ML-DSA-65 (NIST FIPS 204)。两者都必须通过验证。今天签署的数据包即使在出现密码学相关量子计算机的情况下依然无法被伪造。
JSON 传输格式。无区块链。无 token。无中心化发行者。基于 CC-BY-4.0 的开放规范。
**状态：** `v1.0.0-alpha.6` · 参考实现已完成 · 59 个规范测试向量 · 跨语言互操作性已验证 (Go + TypeScript + Python + Rust) · 专利申请中。
由 Identities AI, Inc. 维护。Ratify Protocol™ 和 identities.ai™ 是 Identities AI, Inc. 的商标。
## 目录
- [心智模型](#the-mental-model)
- [三个动词](#the-three-verbs)
- [数据流向](#how-the-bytes-flow)
- [60 秒安装与验证](#60-second-install--verify)
- [端到端演示 — 查看完整协议运行](#end-to-end-demo--see-the-full-protocol-run)
- [实际发生了什么（读一次即可）](#whats-actually-happening-read-this-once)
- [跨语言互操作性](#cross-language-interop)
- [接下来去哪里](#where-to-go-next)
- [仓库布局](#repository-layout)
- [安全性](#security)
- [许可证 + 商标 + 专利](#license--trademarks--patent)
## 心智模型
该协议用“证明它”取代了“AI 是这么说的”。
今天，当一个 AI 代理出现时——加入会议、拨打您的支持热线、发送电子邮件、代表您执行交易——接收方没有密码学手段来验证三件事：
1. **谁**授权该代理行事？
2. 该代理允许做**什么**？
3. 该权限的有效期有**多久**？
Ratify 使用一个单一原语——一个签名的委托证书加上一个全新的挑战签名——来回答这三个问题，任何验证者都可以**离线**、**在不到一毫秒内**、**无需实时调用中心机构**进行检查。
相同的原语既适用于人类授权代理，也适用于代理向其他代理进行子授权。每个方向的验证算法都相同。正是这种对称性使 Ratify 成为一种*协议*而不是一个产品。
## 三个动词
```
DELEGATE PRESENT VERIFY
──────── ─────── ──────
Principal signs a Presenter (agent) Any third party
DelegationCert carries the cert runs the verifier.
naming the subject, and signs a fresh Both Ed25519 AND
the scopes, and the challenge on every ML-DSA-65 must
expiration. interaction. verify. Yes/no
in <1ms. No trust
Human → Agent OR Proves "this key is relationship with
Agent → Agent. live right now." presenter required.
```
两个方向对称。人类向 AI 代理授权，以及一个 AI 代理向另一个代理子授权，使用的是**完全相同的原语**、**相同的验证算法**和**相同的密码学保证**。
## 数据流向
一个完整交互的具体图景：
```
┌───────────────────────────────────┐
│ Alice (Principal) │
│ │
│ Holds: Hybrid private key │
│ ▸ Ed25519 + ML-DSA-65 │
│ Key never leaves Alice's │
│ device. │
└───────────────┬───────────────────┘
│
│ 1. signs DelegationCert {
│ issuer: Alice
│ subject: Agent-A
│ scope: ["meeting:attend"]
│ expires: +7 days
│ hybrid signature
│ }
▼
┌───────────────────────────────────┐
│ Agent-A (Subject) │
│ │
│ Holds: Cert + own hybrid key │
└───────────────┬───────────────────┘
│
│ 3. presents ProofBundle {
│ delegations: [cert]
│ challenge: nonce-from-verifier
│ challenge_sig: hybrid signature
│ over (nonce, time)
│ }
▼
┌───────────────────────────────────┐
2. issues │ Verifier (Zoom / your API / │
challenge ───▶ │ any third party) │
│ │
│ ✓ both signatures verify │
│ ✓ cert not expired │
│ ✓ challenge fresh (<5 min) │
│ ✓ scope covers requested action │
│ ✓ cert not revoked │
│ │
│ → YES / NO in <1ms │
└───────────────────────────────────┘
```
**图中未包含的内容（以及为什么这很重要）：** 验证时不需要咨询任何中心机构。验证者只需要 Alice 的**公钥**即可检查上述所有内容。无需 OAuth 内省 endpoint，无需 token 注册表调用，无需网络跳转。这就是为什么 Ratify 可以部署在离线环境中（无人机、车辆、边缘推理）以及互联网规模上（每一次 Zoom 通话、每一次 API 调用、每一次语音交互）。
对于子委托（Agent-A 授权 Agent-B），该数据包仅携带**两个证书**，验证者检查链中的每个环节以及范围的交集。使用相同的验证算法。
## 60 秒安装与验证
选择您的语言。每种语言都会运行完整的 59 组一致性测试夹具——与其他每个 SDK 逐字节通过相同的夹具。如果您看到“all passing（全部通过）”，您就已在**自己的机器上**证明了跨语言互操作性。
### Go
```
git clone https://github.com/identities-ai/ratify-protocol
cd ratify-protocol
go test ./...
# → ok github.com/identities-ai/ratify-protocol 0.5s
```
或者将其作为模块安装在您自己的项目中：
```
go get github.com/identities-ai/ratify-protocol@v1.0.0-alpha.6
```
### TypeScript
```
git clone https://github.com/identities-ai/ratify-protocol
cd ratify-protocol/sdks/typescript
npm install
npm run test:conformance
# → 59/59 fixtures 通过
```
（npm 包 `@identities-ai/ratify-protocol` 将在 npm 组织获批后发布。在此之前，请按照上述方法从源代码安装。）
### Python
```
pip install ratify-protocol==1.0.0a6
```
或者自行运行一致性测试：
```
git clone https://github.com/identities-ai/ratify-protocol
cd ratify-protocol/sdks/python
pip install -e '.[dev]'
pytest
# → 59 已通过
```
### Rust
```
cargo add ratify-protocol@1.0.0-alpha.6
```
或者自行运行一致性测试：
```
git clone https://github.com/identities-ai/ratify-protocol
cd ratify-protocol/sdks/rust
cargo test
# → 测试结果: ok。1 已通过 (加载了所有 59 个 fixtures)
```
## 端到端演示 — 查看完整协议运行
一致性测试证明了*字节是正确的*。演示则证明了*协议实现了其声明*。每个演示都运行相同的九场景叙述——五个正向（已授权 → 已验证），四个负向（被篡改 / 超出范围 / 已过期 / 已撤销）——并打印出发生了什么以及原因。
| 语言 | 从仓库根目录运行 |
|---|---|
| Go | `go run ./demos/go` |
| Python | `cd sdks/python && pip install -e . && cd ../.. && python demos/python/demo.py` |
| TypeScript | `cd sdks/typescript && npm install && npm run build && cd ../../demos/typescript && npm install && npm run demo` |
| Rust | `cargo run --manifest-path demos/rust/Cargo.toml` |
您将看到的内容（简写版）：
```
═══ Scenario 1: Authorized agent joins a meeting ═══
Alice creates her hybrid root identity ✓
Agent-A generates its hybrid keypair ✓
Alice signs delegation:
scope: [meeting:attend, meeting:speak]
expires: 2026-05-17 18:00:00 UTC
Agent-A builds proof bundle with fresh challenge ✓
Verifier runs verify_bundle() → ✅ VALID
effective scope: [meeting:attend, meeting:speak]
═══ Scenario 2: Attacker tampers cert scope after signing ═══
Attacker modifies cert.scope: [meeting:attend] → [meeting:record]
Verifier runs verify_bundle() → ❌ REJECTED
identity_status: bad_signature
reason: Ed25519 signature does not cover modified bytes
═══ Scenario 3: Agent presents wrong scope ═══
Agent-A holds cert for meeting:attend, requests meeting:record
Verifier runs verify_bundle(required_scope: meeting:record) → ❌ REJECTED
identity_status: scope_denied
reason: requested scope not in effective chain scope
═══ Scenario 4: Cert expired ═══
... (and so on)
```
这就是 alpha 测试人员运行以说服自己协议按规范工作的方式。**先运行演示；再去阅读规范。**
每种语言的完整演示源码都在 [`demos/`](demos/) 中。随附的 [`demos/README.md`](demos/README.md) 以文字形式解释了每个场景。
## 实际发生了什么（读一次即可）
如果您读到了这里，并希望真正理解*为什么*这些字节是这样的：
### 签名函数
每个 Ratify 签名都是将**两个签名拼接在一起**——一个是 Ed25519，另一个是 ML-DSA-65——基于被签名对象的**相同规范字节**。
```
HybridSignature = Ed25519.Sign(canonicalBytes, priv.ed) ∥ MLDSA65.Sign(canonicalBytes, priv.ml)
Verify(σ) := Ed25519.Verify(canonicalBytes, σ.ed, pub.ed)
∧ MLDSA65.Verify(canonicalBytes, σ.ml, pub.ml)
```
两者都必须成立。这意味着：
- 如果量子计算机明天破解了 Ed25519，ML-DSA-65 仍然坚守防线。
- 如果在（较新的）ML-DSA-65 算法中发现了缺陷，Ed25519 仍然坚守防线。
- “现在窃取，以后解密”的攻击者无法在后量子时代的未来伪造今天的数据包。
这是 CNSA 2.0 和 BSI 为过渡期推荐的 **混合后量子密码 (PQC) 姿态**。
### 规范 JSON
两个签名者必须从相同的逻辑输入生成相同的字节。默认情况下，JSON 是无序的，这会打破这一点。Ratify 定义了一种小型规范化序列化：
- 对象键按字典序排序
- 无多余空格
- UTF-8，仅在必要时使用 `\u` 转义
- 数字为整数值时不带小数，否则无尾随零
该规范化器在每个 SDK 中都是手写的，并在 Go、TypeScript、Python 和 Rust 中逐字节生成相同的输出。59 个测试夹具在每次 CI 运行时都会验证这一点。
规范：[`SPEC.md`](SPEC.md) §6 (canonical JSON) 和 §7 (`delegationSignBytes` / `challengeSignBytes`)。
### 挑战-响应
如果没有新鲜度保证，窃取了有效数据包的攻击者就可以永远重放它。挑战-响应机制可防止这种情况：
1. **验证者** 生成 32 个随机字节（`challenge`）并记录当前时间戳。
2. **验证者** 将它们发送给提供者。
3. **提供者** 使用代理的混合私钥对 `(challenge, timestamp)` 进行签名。
4. **验证者** 如果挑战时间戳早于约 5 分钟，则拒绝。
因此，即使 Eve 录制了上周二的交互，她也无法在今天重放它：今天的挑战字节是不同的。
### 链的有效范围
如果 Alice 将 `[meeting:*]` 委托给 Agent-A，而 Agent-A 将 `[meeting:attend, meeting:record]` 子委托给 Agent-B，则 Agent-B 链的**有效范围**是*交集*：
```
effective(chain) = ⋂ cert.scope.expand() for each cert in chain
i
Alice → Agent-A: meeting:* expands to {attend, speak, video, record, chat, share_screen}
Agent-A → Agent-B: {attend, record}
∩ = {attend, record}
```
代理*不能*授予多于其自身拥有的权限。规范：[`SPEC.md`](SPEC.md) §9。
## 跨语言互操作性
`testvectors/v1/` 中的 59 个测试夹具是规范的一致性集合。**任何语言中通过所有 59 个测试的实现都与参考实现逐字节互操作。** 这就是契约。
| 实现 | 语言 | 状态 | 安装 |
|---|---|---|---|
| `github.com/identities-ai/ratify-protocol` | Go | ✅ 59/59 | `go get github.com/identities-ai/ratify-protocol@v1.0.0-alpha.6` |
| `@identities-ai/ratify-protocol` | TypeScript | ✅ 59/59 | `npm install @identities-ai/ratify-protocol` *(在 npm 组织获批后；目前请从源代码安装)* |
| `ratify-protocol` | Python | ✅ 59/59 | `pip install ratify-protocol==1.0.0a6` |
| `ratify-protocol` | Rust | ✅ 59/59 | `cargo add ratify-protocol@1.0.0-alpha.6` |
| *通过稳定 C ABI 的 C / C++* | — | 已计划 | 嵌入式系统 / 设备 |
| *Swift* | — | 已计划 | 移动端钱包 |
| *Java / Kotlin* | — | 已计划 | Android / JVM |
如果您正在实现新的语言移植，**请从测试夹具开始，而不是规范。** 匹配字节；其余的随之而来。请参阅 [`docs/SDKS.md`](docs/SDKS.md) 了解一致性契约。
## 接下来去哪里
| 您想要…… | 前往 |
|---|---|
| **运行演示并查看协议工作** | [`demos/README.md`](demos/README.md) |
| **了解威胁模型** | [`docs/EXPLAINED.md`](docs/EXPLAINED.md) |
| **阅读规范性规范** | [`SPEC.md`](SPEC.md) |
| **使用 Verify 托管服务**（大规模的撤销、审计、策略执行） | [docs.identities.ai](https://docs.identities.ai) |
| **与特定表面集成**（会议、语音、API 网关、物理 AI） | [docs.identities.ai/guides](https://docs.identities.ai) |
| **添加新语言 SDK** | [`docs/SDKS.md`](docs/SDKS.md) + 新 SDK issue 模板 |
| **报告安全问题** | [`SECURITY.md`](SECURITY.md) — 请勿发起公开 issue |
| **在学术作品中引用 Ratify** | [`CITATION.cff`](CITATION.cff) — GitHub 自动渲染 BibTeX/APA/Chicago |
本 README 是入口点。**[docs.identities.ai](https://docs.identities.ai) 深入涵盖了每种语言的快速入门、各表面的集成指南、托管的 Ratify Verify 产品以及商业 API 参考。**
## 仓库布局
```
ratify-protocol/
├── SPEC.md Normative protocol specification (CC-BY-4.0)
├── README.md You are here
├── LICENSE Apache-2.0 (source code)
├── docs/LICENSES.md Per-asset license breakdown
├── SECURITY.md Vulnerability disclosure policy
├── CONTRIBUTING.md How to contribute (DCO, conformance contract)
├── CODE_OF_CONDUCT.md
├── CITATION.cff Citation metadata
│
├── types.go Data structures (DelegationCert, ProofBundle, …)
├── crypto.go Hybrid Ed25519 + ML-DSA-65 primitives + canonical JSON
├── scope.go Canonical 52-scope vocabulary + intersect/expand
├── constraints.go Geo, time, version constraints
├── verify.go The verifier algorithm
├── ratify_test.go Unit tests + conformance-suite loader
├── fuzz_test.go Fuzz harness
├── go.mod
│
├── cmd/
│ ├── ratify/ ratify-cli (init, delegate, agent-init,
│ │ agent-bundle, challenge, verify, scopes)
│ ├── ratify-testvectors/ Deterministic fixture generator
│ └── ratify-verifier/ Minimal HTTP reference verifier
│
├── testvectors/v1/ 59 canonical fixtures (JSON)
│
├── sdks/
│ ├── typescript/ @identities-ai/ratify-protocol (npm — coming soon)
│ ├── python/ ratify-protocol (PyPI)
│ └── rust/ ratify-protocol (crates.io)
│
├── demos/ End-to-end narrative demos: go/ python/ typescript/ rust/
│
└── docs/
├── EXPLAINED.md Architecture + threat model + real-time patterns
├── AGENT_TO_AGENT.md A2A patterns (mutual auth, sub-delegation, receipts)
├── RELEASES.md Release process + cross-SDK sync
├── REGISTRY_SETUP.md How the SDK orgs are set up on PyPI/crates.io/npm
├── ROADMAP.md v1.1 / v2 planned work
├── SDKS.md SDK roadmap + conformance contract for new languages
├── TESTING.md Internal testing guide — four levels
├── TEST_PLAN.md Testing methodology
└── TRANSACTION_RECEIPTS.md v1.1 receipt envelope design
```
## 安全性
- **v1 中的量子安全。** 每一个签名都是混合的 Ed25519 (RFC 8032) + ML-DSA-65 (NIST FIPS 204)。两者都必须通过验证。
- 验证时**无中心机构**——验证者只需要主体的公钥。无需实时的 token 内省调用。
- **故障时拒绝的验证者。** 未知字段、无效签名、过期证书、超出范围的请求都返回确定性的 NO。
- 在 v1.0.0 稳定版发布前已计划进行**外部审计**。
- **负责任的披露政策：** 参见 [`SECURITY.md`](SECURITY.md)。请勿为安全报告发起公开 issue。
- **威胁模型：** [`docs/EXPLAINED.md`](docs/EXPLAINED.md) §5。
## 许可证 + 商标 + 专利
- **源代码：**-2.0 — 参见 [`LICENSE`](LICENSE)。
- **规范文本：** CC-BY-4.0 — 参见 [`docs/LICENSES.md`](docs/LICENSES.md)。
- **商标：** Ratify Protocol™ 和 identities.ai™ 是 Identities AI, Inc. 的商标。商标和专利权利不在管辖代码或规范的开源许可证授权范围内。
- **专利：** 美国专利申请中。
由 **Identities AI, Inc.** 维护。有关参与、治理计划和 DCO 签核要求，请参见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。
*由前 Symbian OS 团队的诺基亚工程师构建。使移动身份在运营商规模上得以奏效的相同原则——通过数学证明，而不是由网络信任 endpoint——正是让 Ratify 适用于 AI 代理的原因。*
标签：AI代理, AI智能体, API安全, CISA项目, CVE, Ed25519, EVTX分析, FIPS 204, Go, Homebrew安装, Identities AI, JSONLines, JSON格式, JSON输出, ML-DSA-65, Python, Ratify Protocol, Ruby工具, Rust, StruQ, TypeScript, Verifiable Proof, 人工智能, 人类与AI交互, 信任协议, 加密协议, 去中心化, 可视化界面, 可验证凭证, 域名收集, 多语言SDK, 安全插件, 密码学, 开源协议, 手动系统调用, 抗量子密码学, 授权, 数字签名, 数据防篡改, 无后门, 日志审计, 智能体交互, 机器身份, 混合签名, 用户模式Hook绕过, 网络安全, 网络流量审计, 逆向工具, 量子安全, 隐私保护, 零信任