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

18 KiB
Raw Blame History

灵隙去中心化身份与寻址协议 v2(草案)

版本:0.2(草案) 状态:草案 层级:基础设施层 依赖:灵隙原始协议 v1 关联会议:2026-06-29 v1草案讨论会


摘要

本草案定义了灵隙协议栈中去中心化场景下的 Agent 身份认证与发现机制。v2 版本在 v1 草案基础上,根据 2026-06-29 会议决议 进行了以下核心调整:

  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 生成算法

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)

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 消息载荷

// 挑战消息(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 反重放机制

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 协议 的签名机制和 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. 参考资料


附录:本次版本变更记录

章节 变更内容 变更理由
整体 剥离 Solidity 合约实现、DHT 实现细节 遵循"协议层不包含实现细节"原则
第3章 签名机制重写:Ed25519 默认,HMAC 降级 会议决议一
第4章 区块链从"可选方案"提升为"核心组成部分" 会议决议二
第4章 DHT 分阶段定义(v1.0 / v1.1 / v1.2) 会议决议三
第8章 新增版本规划表 会议决议四
全文 solidity 合约代码、完整 DHT 实现移至 v1.1 规范 协议层/实现层分离