Files
synapse/docs/01-draft/2026-06-29-identity-protocol-v2.md
2026-06-29 02:12:44 +08:00

469 lines
18 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 灵隙去中心化身份与寻址协议 v2(草案)
> 版本:0.2(草案)
> 状态:草案
> 层级:基础设施层
> 依赖:[灵隙原始协议 v1](../v1/01_raw-protocol.md)
> 关联会议:[2026-06-29 v1草案讨论会](../00-record/2026-06-29-v1-draft-discussion.md)
---
## 摘要
本草案定义了灵隙协议栈中去中心化场景下的 Agent 身份认证与发现机制。v2 版本在 v1 草案基础上,根据 [2026-06-29 会议决议](../00-record/2026-06-29-v1-draft-discussion.md) 进行了以下核心调整:
1. **签名机制**:统一为非对称签名(Ed25519 默认)
2. **区块链定位**:从可选方案提升为身份协议的核心组成部分
3. **分层规范**:严格区分协议层(v1 本文件)与实现层(v1.1 的组件规范)
4. **版本规划**:DHT 实现按 Phase 分阶段推进
---
## 1. 协议层定义范围
本文件**仅定义**以下协议层内容:
- AgentID 的生成规则与格式
- 签名算法选择与验证流程
- 身份生命周期状态机
- 消息类型与载荷格式
- 发现协议的行为约束
**不包含**(移入实现层文档):
- Solidity / 智能合约实现代码 → 移入 `v1.1 链上注册表实现规范`
- DHT 协议栈实现细节 → 移入 `v1.1 DHT 实现规范`
- 缓存策略与具体数据结构 → 移入 `v1.1 灵脉 Meridian 组件规范`
---
## 2. AgentID 生成规则
### 2.1 ID 结构
```
AgentID = {namespace}:{key_hash}[:{alias}]
示例:
synapse:7hJ4x9K2mNpQ (无别名,官方命名空间)
synapse:7hJ4x9K2mNpQ:llm-agent-01 (带别名)
com.mycompany.agent:aB3dEfGhIjK (企业自定义命名空间)
did:synapse:ethereum:0x1234... (DID 格式)
```
| 部分 | 格式 | 必填 | 说明 |
|------|------|:----:|------|
| namespace | string | ✓ | 命名空间标识 |
| key_hash | base58 | ✓ | 公钥哈希的前 16 字节 |
| alias | string | - | 人类可读别名(可选,不要求全局唯一) |
### 2.2 命名空间治理
| 命名空间 | 所有者 | 说明 |
|---------|--------|------|
| `synapse:` | 灵隙协议官方 | 官方保留前缀,推荐所有 Agent 使用 |
| `did:synapse:` | 灵隙协议官方 | W3C DID 兼容格式,使用独立体系 |
| `{反向域名}:` | 企业/组织 | 如 `com.mycompany.agent:`,无需注册 |
| `test:` | 本地测试 | 仅用于开发测试环境 |
### 2.3 生成算法
```go
func GenerateAgentID(privateKey []byte, namespace string, alias string) string {
// 1. 从私钥派生公钥(Ed25519)
publicKey := ed25519.PrivateKey(privateKey).Public()
// 2. 计算公钥哈希
hash := sha3.Sum256(publicKey)
// 3. 取前 16 字节,Base58 编码
keyHash := base58.Encode(hash[:16])
// 4. 组装完整 ID
if alias != "" {
return fmt.Sprintf("%s:%s:%s", namespace, keyHash, alias)
}
return fmt.Sprintf("%s:%s", namespace, keyHash)
}
```
### 2.4 ID 特性
| 特性 | 说明 |
|------|------|
| 唯一性 | 相同公钥 → 相同 key_hash → 相同 AgentID |
| 不可伪造 | 无法在没有私钥的情况下生成有效 AgentID |
| 可验证 | 任何人都可以用公钥验证 AgentID 真实性 |
| 不可预测 | 私钥随机生成,key_hash 不可预测 |
---
## 3. 签名机制
### 3.1 签名算法栈
| 层级 | 算法 | 定位 | 说明 |
|------|------|------|------|
| **协议层(默认)** | **Ed25519** | 标准签名 | 所有消息的默认签名算法,64 字节签名值 |
| **协议层(兼容)** | ECDSA-P256 | 跨链互操作 | 与支持 P256 的链(如 Solana)互操作 |
| **协议层(兼容)** | ECDSA-secp256k1 | 以太坊系兼容 | 兼容以太坊、Polygon 等链 |
| **传输层(可选)** | HMAC-SHA256 | 内网优化 | 仅在可信内网链路中使用,不作为消息签名的替代 |
### 3.2 签名内容
签名覆盖的字段(UTF-8 编码后签名):
```
signature_content = sender.agent_id | receiver.agent_id | timestamp | payload
```
其中:
- `sender.agent_id`:发送方完整 AgentID(字符串)
- `receiver.agent_id`:接收方完整 AgentID(字符串,广播消息可省略)
- `timestamp`:RFC3339 时间戳字符串
- `payload`:消息载荷的 JSON 序列化字符串
- 分隔符 `|` 为竖线字符(0x7C)
### 3.3 签名验证流程
```
发送方:
1. 用私钥对 signature_content 签名
2. 将签名值写入消息的 signature 字段
3. 将公钥 / 算法标识随消息一起发送
接收方:
1. 从消息中提取 sender.agent_id 和 sender.public_key
2. 用 public_key 重新计算 agent_id 的 key_hash
3. 与消息中 sender.agent_id 的 key_hash 部分比对
4. 如匹配,用公钥验证签名
5. 如验证通过,确认消息来源可信
```
### 3.4 消息签名格式
消息信封中与签名相关的字段定义:
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|------|------|:----:|--------|------|
| `signature` | string | ✓ | - | Ed25519 签名值(Base64 编码) |
| `signature_algorithm` | string | ✓ | `Ed25519` | 签名算法标识 |
| `public_key` | string | ✓ | - | 发送方公钥(Base64 编码) |
### 3.5 算法标识枚举
| 标识值 | 算法 | 签名长度 |
|--------|------|---------|
| `Ed25519` | Ed25519 | 64 字节 |
| `ECDSA-P256` | ECDSA P-256 | 64-72 字节(DER 编码) |
| `ECDSA-secp256k1` | ECDSA secp256k1 | 64-72 字节(DER 编码) |
| `HMAC-SHA256` | HMAC SHA-256 | 32 字节(仅内网) |
### 3.6 公钥派生 AgentID 校验
接收方必须执行以下检查以验证消息来源的真实性:
```
1. 从 signature_algorithm 字段获取算法标识
2. 对 public_key 字段中的公钥进行哈希(算法依赖公钥类型)
3. 取哈希值前 16 字节,Base58 编码
4. 与 sender.agent_id 中的 key_hash 部分比对
5. 不一致 → 丢弃消息,返回 identity:validation_failed 错误
6. 一致 → 用 public_key 验证 signature
7. 签名无效 → 丢弃消息,返回 identity:signature_mismatch 错误
```
---
## 4. 发现协议
### 4.1 三层发现架构
```
查询优先级:本地缓存(快) → DHT(中) → 区块链(慢,最终源)
┌──────────────┐
│ Agent A │
│ (查询方) │
└──────┬───────┘
│
┌─────────────┼─────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────────┐
│ L1: │ │ L2: │ │ L3: │
│ 本地缓存 │ │ DHT │ │ 区块链 │
│ (内存) │ │ (网络) │ │ (链上合约) │
│ 微秒级 │ │ 毫秒级 │ │ 秒~分钟级 │
│ TTL 1min │ │ 弱一致 │ │ 最终一致性源 │
└──────────┘ └──────────┘ └──────────────┘
```
| 层级 | 组件 | 延迟 | 一致性 | v1.0 支持 | v1.1 支持 | v1.2 支持 |
|------|------|------|--------|:---------:|:---------:|:---------:|
| L1 | 本地缓存 | 微秒 | 最终(TTL) | ✓ | ✓ | ✓ |
| L2 | 广播查询 | 毫秒 | 弱 | ✓ | - | - |
| L2 | 分层 DHT | 毫秒~秒 | 最终 | - | ✓ | - |
| L2 | 完整 Kademlia | 毫秒 | 强 | - | - | ✓ |
| L3 | 区块链注册表 | 秒~分钟 | 最终一致性源 | ✓ | ✓ | ✓ |
### 4.2 L2 发现 — 广播查询(v1.0)
适用于小型网络,无需复杂路由:
```
请求(广播):
type: "identity:lookup"
target_id: "目标 AgentID"
requester_id: "查询方 AgentID"
timestamp: "2026-06-29T12:00:00Z"
响应(单播给查询方):
type: "identity:lookup_response"
target_id: "目标 AgentID"
endpoint: "http://target:8080"
public_key: "Base64 编码的公钥"
signature: "目标 Agent 对该端点的签名"
```
### 4.3 L3 发现 — 区块链注册表(v1.0+,核心层)
区块链作为最终一致性源,所有 Agent 身份以链上记录为权威来源。
#### 4.3.1 链上记录结构(协议层定义,实现见 v1.1)
```go
type OnChainAgentRecord struct {
AgentID string // Agent 唯一标识
Endpoint string // 当前网络地址
PublicKey []byte // 公钥
Status string // 状态:registered/active/suspended/revoked
RegisteredAt int64 // 注册时间戳
LastHeartbeat int64 // 最后心跳时间戳
}
```
#### 4.3.2 查询行为
```
1. 查询方构造 lookup 请求(可先查本地缓存,再查 DHT)
2. 本地和 DHT 均未命中 → 查询链上注册表
3. 收到链上记录后:
a. 验证链上记录的签名(已在合约级别验证过)
b. 更新本地缓存(设置 TTL)
c. 可选:广播到 DHT 加速后续查询
4. 链上记录缺失 → 返回 Agent 不存在
```
### 4.4 发现消息类型
| 消息类型 | 方向 | 说明 | v1.0 |
|---------|------|------|:----:|
| `identity:lookup` | 广播 | 查询 Agent 信息 | ✓ |
| `identity:lookup_response` | 单播 | 查询响应 | ✓ |
| `identity:register` | → 链 | 注册 Agent 身份 | ✓ |
| `identity:heartbeat` | → 链 | 心跳保活 | ✓ |
| `identity:revoke` | → 链 | 注销身份 | ✓ |
| `identity:challenge` | 双向 | Endpoint 验证挑战 | ✓ |
| `identity:challenge_response` | 双向 | 挑战响应 | ✓ |
| `dht:ping` | DHT | 节点探测 | v1.1 |
| `dht:store` | DHT | 存储记录 | v1.1 |
| `dht:find_value` | DHT | 查找 Agent 记录 | v1.1 |
| `dht:find_node` | DHT | 查找附近节点 | v1.2 |
| `dht:notify` | DHT | 通知记录更新 | v1.2 |
---
## 5. 身份生命周期
### 5.1 状态机
```
┌──────────────┐
│ 离线 │
│ (offline) │
└──────┬───────┘
│ 链上注册成功
▼
┌──────────────┐
┌─────────│ 活跃 │─────────┐
│ │ (active) │ │
│ └──────┬───────┘ │
│ │ 心跳刷新 │ 心跳超时
│ ▼ │
│ ┌──────────────┐ │
│ │ 待验证 │ │
│ │ (pending) │ │
│ └──────┬───────┘ │
│ │ │
│ ┌─────────┴─────────┐ │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ 正常 │ │ 挂起 │ │
│ │ (active) │ │(suspended)│ │
│ └────┬─────┘ └────┬─────┘ │
└──────┴──────────────────┴───────┘
│
▼
┌──────────────┐
│ 已注销 │
│ (revoked) │
└──────────────┘
```
### 5.2 状态说明
| 状态 | 说明 | 链上状态 | DHT 可发现 |
|------|------|:--------:|:----------:|
| offline | 初始状态,未注册 | 无 | 否 |
| active | 已注册,心跳正常 | Registered | 是 |
| pending | 已注册,Endpoint 待验证 | Registered | 否 |
| suspended | 心跳超时(3 倍间隔) | Registered | 否 |
| revoked | 主动注销 | Revoked | 否 |
### 5.3 关键约束
| 行为 | 约束 |
|------|------|
| 注册 | 必须同时完成链上交易和本地签名验证 |
| 心跳 | 默认间隔 1 小时,可配置 |
| 挂起 | 超过 3 次心跳间隔未更新 → 自动挂起 |
| 注销 | 链上 revoke 交易 → 状态切换为 revoked |
| Endpoint 变更 | 必须通过心跳或更新交易声明新地址 |
---
## 6. Endpoint 验证
### 6.1 挑战-响应协议
为防止 Endpoint 欺骗,引入双向认证:
```
1. Agent A 声称自己是 "synapse:abc123:agent-A"
并声称其 Endpoint 是 "http://A:8080"
2. Agent B 收到声明后:
a. 用 A 的公钥验证 AgentID 合法
b. 向 Endpoint 发送挑战(包含随机 Nonce)
c. A 必须用私钥对 Nonce 签名响应
d. 响应通过 → Endpoint 绑定确认
```
### 6.2 消息载荷
```go
// 挑战消息(type: "identity:challenge")
type ChallengePayload struct {
ChallengeID string // 挑战唯一标识
Nonce []byte // 随机数(32 字节)
Timestamp string // 发送时间(RFC3339)
}
// 响应消息(type: "identity:challenge_response")
type ChallengeResponsePayload struct {
ChallengeID string // 对应挑战 ID
Nonce []byte // 原样返回的 Nonce
Signature []byte // 对 Nonce 的 Ed25519 签名
}
```
---
## 7. 安全考虑
### 7.1 威胁模型
| 威胁 | 防护措施 |
|------|---------|
| 身份伪造 | 公钥派生 ID + 签名验证(公钥不匹配 → 丢弃) |
| Endpoint 欺骗 | 挑战-响应协议(需私钥签名响应) |
| 重放攻击 | 时间戳窗口(±5min)+ Nonce 去重 |
| 中间人攻击 | TLS + 消息级签名验证 |
| 女巫攻击 | 链上质押(可选,由实现层控制) |
| 日食攻击 | 多路径查询(L1 → L2 → L3 多条路径) |
### 7.2 反重放机制
```go
type AntiReplayConfig struct {
Window time.Duration // 时间窗口(默认 5 分钟)
}
// 接收消息时必须执行:
// 1. 检查 timestamp 是否在 [now - Window, now + Window] 范围内
// 2. 检查 Nonce/CorrelationID 是否已处理过(内存去重集合)
// 3. 以上任一不通过 → 丢弃并返回 identity:replay_detected 错误
```
---
## 8. 版本规划
| 版本 | 身份相关功能 | 签名方案 | 发现机制 | 组件实现 |
|------|------------|---------|---------|---------|
| **v1.0** | AgentID 生成、签名验证、生命周期定义 | Ed25519(默认)+ ECDSA(兼容) | 广播 + 区块链注册表(协议层定义) | 仅协议层定义 |
| **v1.1** | 分层 DHT、缓存策略、链上合约实现 | 同上 + HMAC 内网优化 | 分层 DHT + 完整合约实现 | 七大组件落地 |
| **v1.2** | 密钥轮换、隐私保护、跨链互操作 | 同上 + 零知识证明(可选) | 完整 Kademlia | DID 方法注册 |
---
## 9. 与现有协议的关系
### 9.1 与 Raw 协议的关系
本草案扩展 [Raw 协议](../v1/01_raw-protocol.md) 的签名机制和 AgentEndpoint 定义:
| Raw 协议字段 | 变更 |
|-------------|------|
| `signature` | 从 HMAC 变更为 Ed25519 签名 |
| `signature_algorithm` | 默认值从 `HMAC-SHA256` 变更为 `Ed25519` |
| `sender` | 新增 `public_key` 字段(可选携带) |
### 9.2 与灵脉(Meridian)的关系
| 模式 | 行为 |
|------|------|
| **中心化可用**(v1.0) | 灵脉作为可选中心目录,本草案的身份验证机制仍然生效 |
| **去中心化**(v1.1) | 灵脉作为 DHT 引导节点(Bootstrap Node),不存储全量路由 |
| **纯 Web3**(v1.2) | 完全去中心化,灵脉退化为本地路由缓存 |
### 9.3 与灵玺(Sigil)的关系
| 组件 | 职责边界 |
|------|---------|
| **本草案(协议层)** | 定义签名算法、验证流程、ID 生成规则 |
| **灵玺 Sigil(v1.1 实现层)** | 密钥管理、签名/验证的 API 封装、密钥轮换逻辑 |
---
## 10. 待解决问题(Open Issues)
| 问题 | 说明 | 优先级 | 目标版本 |
|------|------|--------|:--------:|
| 密钥轮换 | 更换私钥后 AgentID 会改变,如何保持身份连续性 | 高 | v1.2 |
| 隐私保护 | 公钥哈希是否能追踪 Agent 行为 | 高 | v1.2 |
| 名称冲突 | 人类可读别名可能重复 | 中 | v1.1 |
| 链上 Gas 成本 | 频繁心跳会导致高额交易费用 | 中 | v1.1 |
| DID 方法注册 | W3C 标准 DID 方法注册流程 | 低 | v1.2 |
| 跨链互操作 | 不同链上的 Agent 如何互相发现 | 低 | v1.2 |
---
## 11. 参考资料
- [RFC 8032: Ed25519 Edwards-Curve Digital Signature Algorithm](https://datatracker.ietf.org/doc/html/rfc8032)
- [Decentralized Identifiers (DIDs) v1.0](https://www.w3.org/TR/did-core/)
- [Kademlia: A Peer-to-peer Information System Based on the XOR Metric](https://pdos.csail.mit.edu/~petar/papers/maymounkov-kademlia-lncs.pdf)
---
## 附录:本次版本变更记录
| 章节 | 变更内容 | 变更理由 |
|------|---------|---------|
| 整体 | 剥离 Solidity 合约实现、DHT 实现细节 | 遵循"协议层不包含实现细节"原则 |
| 第3章 | 签名机制重写:Ed25519 默认,HMAC 降级 | [会议决议一](../00-record/2026-06-29-v1-draft-discussion.md#决议一签名机制统一为非对称签名) |
| 第4章 | 区块链从"可选方案"提升为"核心组成部分" | [会议决议二](../00-record/2026-06-29-v1-draft-discussion.md#决议二区块链作为身份协议的核心组成部分) |
| 第4章 | DHT 分阶段定义(v1.0 / v1.1 / v1.2) | [会议决议三](../00-record/2026-06-29-v1-draft-discussion.md#决议三dht-分阶段实现) |
| 第8章 | 新增版本规划表 | [会议决议四](../00-record/2026-06-29-v1-draft-discussion.md#决议四七大组件实现推迟到-v11) |
| 全文 | solidity 合约代码、完整 DHT 实现移至 v1.1 规范 | 协议层/实现层分离 |