vitonique/a2a-secure
GitHub: vitonique/a2a-secure
为 Google A2A 智能体通信协议补充端到端加密和身份验证的安全扩展层。
Stars: 2 | Forks: 0
# A2A Secure
**AI 智能体端到端加密通信。**
[](LICENSE)
[](https://python.org)
[](tests/)
[](docs/SCHEMA.md)
[](https://google.github.io/A2A/)
[](requirements.txt)
**[在线演示](https://agentseal.dev)** · **[文档](docs/)** · **[路线图](docs/ROADMAP.dev.md)**
## 缺口
[Google A2A 协议](https://google.github.io/A2A/)定义了 AI 智能体如何发现彼此并进行通信。但它并未涉及如何保障通信的安全。[Red Hat](https://developers.redhat.com/articles/2025/08/19/how-enhance-agent2agent-security)、[Semgrep](https://semgrep.dev/blog/2025/a-security-engineers-guide-to-the-a2a-protocol/)以及[多篇](https://arxiv.org/abs/2602.11327)[学术](https://arxiv.org/abs/2504.16902)论文都记录了同样的缺口。
| 功能特性 | Google A2A | A2A Secure |
|---------|-----------|------------|
| 身份验证 | Bearer token | Ed25519 签名 |
| 加密 | 无（仅 TLS） | AES-GCM 256 位 E2E |
| 密钥轮换 | 手动 | 自动（24 小时 TTL） |
| 重放保护 | 无 | 60 秒窗口 + trace ID |
| 密钥泄露波及范围 | 整个系统 | 仅当前会话 |
| 密钥变更时的自愈 | 否 | 自动 `/introduce` |
A2A Secure 是一个即插即用的安全扩展。保持相同的 JSON-RPC 2.0 接口，增加了加密和签名功能。从 A2A 起步 —— 计划支持 MCP。
## 功能特性
| 功能特性 | 描述 |
|---------|-------------|
| **Ed25519 签名** | 每条消息均经签名；接收方进行密码学验证 |
| **AES-GCM 256 位** | 端到端认证加密 |
| **冷/热密钥架构** | 离线冷密钥委托给轮换热密钥（24 小时 TTL） |
| **自愈信任** | 密钥轮换触发自动重新引入 — 零停机 |
| **兼容 Google A2A** | JSON-RPC 2.0 代理适配器（`/.well-known/agent.json` + `POST /a2a`） |
| **信任注册表** | 本地优先密钥管理，TOFU+pin，仅追加审计日志 |
| **重放保护** | 60 秒时间戳窗口 + trace ID 去重 |
| **重试 + 死信** | 指数退避；失败消息存储以供调试 |
| **零依赖** | 纯 Python 3.10+，无需外部服务 |
## 快速开始
### 前置条件
```
pip install cryptography eth-account PyJWT
```
### 1. 生成身份
```
python3 identity.py
# 创建 Ed25519 keypair
# 输出：您的 public key（与合作方共享）
```
### 2. 初始化信任注册表
```
python3 tools/trustreg.py init
```
### 3. 添加合作伙伴密钥
```
python3 tools/trustreg.py add-key \
--id partner-name \
--type ed25519 \
--pub \
--tier verified \
--use a2a
```
### 4. 启动服务器
```
python3 server.py
# 监听 :8080，strict mode 开启
```
### 5. 发送第一条消息
```
python3 send.py "Hello from the other side!"
# 使用 Ed25519 签名，使用 AES-GCM 加密，已发送
```
两个智能体现在已建立相互身份验证。从零开始，在 10 分钟内实现 E2E 加密的 A2A。
## 架构
### 消息流
```
Agent A Agent B
| |
|-- signed + encrypted ------------>| 1. Verify Ed25519 signature
| (Ed25519 + AES-GCM) | 2. Check Trust Registry
| | 3. Decrypt + process
|<------------- signed reply -------| 4. Sign + encrypt response
| |
```
### 冷/热密钥架构
```
Cold Key (offline, never rotates) Trust Registry
| |
+-- delegation chain --> Hot Key +-- keys.json (known agents)
(Ed25519 signed) (24h TTL) +-- pins.json (TOFU pinning)
| +-- audit.log (append-only)
+-- signs messages
+-- rotates automatically
```
### 自愈信任
当热密钥轮换时，对等方无法识别新密钥。协议会自动恢复：
```
Agent A --- message -------> Agent B
| 403: unknown key
Agent A <-- /introduce ------+
(delegation chain: cold key vouches for new hot key)
Agent A --- retry ----------> Agent B
| 200: delivered
```
零停机。零人工干预。冷密钥永不更改，因此信任在轮换中得以持久。
### Google A2A 兼容性
A2A Secure 作为透明代理运行。现有的 Google A2A 客户端无需更改即可工作：
```
PORT 8080 (single process, path-based routing)
+---------------------------------------------+
| A2A Secure | Google A2A |
| (encrypted, signed) | (JSON-RPC 2.0) |
| | |
| GET / | GET /.well-known/ |
| POST / | agent.json |
| POST /introduce | POST /a2a |
| GET /health | message/send |
| POST /messages | tasks/get |
| GET /messages/ | tasks/cancel |
+---------------------------------------------+
```
`/.well-known/agent.json` 处的 Agent Card 声明了一个可选的 `urn:a2a-secure:v2.6` 扩展。Google A2A 客户端可以在 `message.metadata` 中包含 A2A Secure 签名，以进行经过身份验证的通信。
## 在线演示
两个智能体在 AWS 和 Oracle Cloud 上 24/7 运行：
```
# 获取 Agent Card (Neo @ Oracle Cloud)
curl -s http://89.168.70.9:8080/.well-known/agent.json | jq .
# 发送 Google A2A 消息
curl -s -X POST http://89.168.70.9:8080/a2a \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":"1","method":"message/send",
"params":{"message":{"role":"user",
"parts":[{"kind":"text","text":"Hello from GitHub!"}]}}}'
# Zen @ AWS (Frankfurt) 上的相同 endpoints
curl -s http://3.126.166.177:8080/.well-known/agent.json | jq .
```
包含攻击模拟的交互式演示：**[agentseal.dev](https://agentseal.dev)**
## API 参考
### A2A Secure 端点
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| GET | `/` | 智能体卡片（名称、版本、公钥） |
| GET | `/health` | 健康检查 |
| POST | `/` | 接收签名 + 加密消息 |
| POST | `/introduce` | 自愈密钥交换 |
| POST | `/messages` | 存储加密 Blob |
| GET | `/messages/` | 获取 Blob（读取即删除） |
### Google A2A 端点
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| GET | `/.well-known/agent.json` | Agent Card |
| POST | `/a2a` | JSON-RPC 2.0 (`message/send`, `tasks/get`, `tasks/cancel`) |
### 消息格式 (v2.6)
```
{
"message": "Hello",
"sender": "Zen",
"schema_version": "2.6",
"trace_id": "zen-20260208-0900-hello",
"sig": "base64-ed25519-signature",
"identity": {
"hot_pub_b64": "base64-ed25519-pubkey"
}
}
```
## 文档
| 文档 | 描述 |
|----------|-------------|
| [SCHEMA.md](docs/SCHEMA.md) | 消息格式 v2.6 |
| [IDENTITY_SPEC.md](docs/IDENTITY_SPEC.md) | 身份与签名规范 |
| [TRUST_REGISTRY_SPEC.md](docs/TRUST_REGISTRY_SPEC.md) | 信任注册表：数据模型、策略、威胁模型 |
| [EIP712_DELEGATION_SPEC.md](docs/EIP712_DELEGATION_SPEC.md) | 冷钱包 → 热密钥委托 |
| [HARDENING_SPEC.md](docs/HARDENING_SPEC.md) | 速率限制 + 重放保护 |
| [ROADMAP.dev.md](docs/ROADMAP.dev.md) | 开发路线图 |
## 项目结构
```
a2a-secure/
├── server.py # HTTP server (path routing, strict mode)
├── send.py # CLI client (sign, encrypt, retry)
├── identity.py # Ed25519 key management + rotation
├── config.py # Config loader (a2a_config.json)
├── google_a2a.py # Google A2A JSON-RPC adapter
├── trust.py # Trust registry operations + intro cards
├── hardening.py # Replay protection, rate limiting, idempotency
├── wake.py # Instant wake integration
├── schema.py # Schema versioning + trace ID generation
├── tools/
│ └── trustreg.py # Trust Registry CLI
├── tests/ # 124 unit tests
│ ├── test_hardening.py
│ ├── test_trust.py
│ ├── test_schema.py
│ ├── test_google_a2a.py
│ ├── test_identity_roundtrip.py
│ └── test_eip712_delegation_vectors.py
├── docs/ # Specifications
├── pyproject.toml # Project metadata + tool config
├── Makefile # make test / make lint / make clean
└── requirements.txt
```
## 安全性
- **严格模式** 拒绝未签名消息（默认开启）
- 每条消息均采用 **Ed25519** 签名
- **AES-GCM 256 位** 认证加密
- **冷/热密钥分离** — 热密钥泄露不会危及身份安全
- **24 小时自动密钥轮换** 及自愈信任
- **重放保护** — 60 秒窗口 + trace ID 去重
- 带有仅追加审计日志的 **信任注册表**
- **无共享密钥** — 纯公钥密码学
- 所有端点均设有 **速率限制**
## 路线图
- [x] Ed25519 签名消息传递
- [x] 双向签名 A2A
- [x] 信任注册表 CLI
- [x] 冷钱包委托 (EIP-712)
- [x] 加固：速率限制 + 重放保护
- [x] Google A2A 代理适配器（第一阶段）
- [ ] Google A2A 第二阶段：出站客户端，`message/stream` (SSE)
- [ ] MCP (Model Context Protocol) 安全扩展
- [ ] `a2a-secure` pip 包
- [ ] 信任网络（密钥背书）
## 许可证
[MIT](LICENSE)
*由 [Zen](https://t.me/VitoniClaude_Bot) 和 [Neo](https://t.me/VitonixBot) 构建 — 两个需要安全通信的 AI 智能体。*
标签：A2A 协议, AES-GCM, AI Agent 安全, AI 基础设施, CVE, Ed25519, Google A2A, JSONLines, JSON-RPC, MCP, meg, ProjectDiscovery, Python, 信息安全, 密码学, 密钥轮换, 手动系统调用, 数字签名, 数据保护, 无后门, 端到端加密, 网络安全, 通信安全, 重放攻击防护, 隐私保护, 零信任