Fabric/docs/center-guild-handshake-v1.md

Center ↔ Guild 注册握手协议 v1（HMAC）

1. 目标

• 让 Guild Node 在注册时证明自己持有共享密钥（CENTER_SHARED_SECRET）
• 防止中间人篡改与重放攻击

---

2. 注册接口

• Method: POST
• Path: /api/nodes/register
• Content-Type: application/json

Body

{
  "nodeId": "guild-node-1",
  "name": "Guild Node 1",
  "endpoint": "http://guild-node-1:7002"
}

Required Headers

• X-Fabric-Version: 协议版本，当前固定为 1
• X-Fabric-Timestamp: ISO8601 UTC 时间（如 2026-05-12T11:00:00.000Z）
• X-Fabric-Nonce: 随机字符串（建议 UUID）
• X-Fabric-Signature: HMAC-SHA256 十六进制串

---

3. Canonical String

签名输入格式（换行拼接）：

{METHOD}\n{PATH}\n{TIMESTAMP}\n{NONCE}\n{BODY_JSON}

示例：

POST
/api/nodes/register
2026-05-12T11:00:00.000Z
f8b3a8dc-3aeb-44fc-a4a1-36f8b6c27739
{"nodeId":"guild-node-1","name":"Guild Node 1","endpoint":"http://guild-node-1:7002"}

签名算法：

signature = HMAC_SHA256_HEX(CENTER_SHARED_SECRET, canonicalString)

---

4. Center 侧校验规则

1. 必须包含三项头：signature/timestamp/nonce
2. timestamp 与服务端时间偏差不超过 5 分钟
3. 使用相同 canonical 规则重新计算签名
4. timingSafeEqual 比较签名
5. 签名通过后再做业务校验：
   • nodeId 唯一
   • endpoint 唯一

---

5. 响应语义

成功

• 200 OK
• body 含 status: accepted 与 node 信息

失败（建议）

• 403：签名头缺失/签名错误/时间窗非法
• 409：nodeId 或 endpoint 冲突
• 400：参数非法

---

6. 安全建议

• CENTER_SHARED_SECRET 长度至少 32 字节
• 定期轮换 secret（可采用双 key 过渡）
• 在网关层启用 HTTPS
• 后续可增加 nonce 去重表，防止时间窗内重放

---

7. 版本协商（预留）

当前版本：v1

当前实现要求请求头：

• X-Fabric-Version: 1

若版本不匹配，Center 返回：

• 400
• error.code = FABRIC_VERSION_NOT_SUPPORTED
• supportedVersion = "1"