灵隙(synapse) v1.0.0 版本
This commit is contained in:
468
docs/01-draft/2026-06-29-identity-protocol-v2.md
Normal file
468
docs/01-draft/2026-06-29-identity-protocol-v2.md
Normal file
@@ -0,0 +1,468 @@
|
||||
# 灵隙去中心化身份与寻址协议 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 规范 | 协议层/实现层分离 |
|
||||
Reference in New Issue
Block a user