docs(protocol): document center-guild HMAC registration handshake v1

2026-05-12 11:12:48 +00:00
parent ab01a83a90
commit 676e838697
2 changed files with 91 additions and 1 deletions
--- a/docs/center-guild-handshake-v1.md
+++ b/docs/center-guild-handshake-v1.md
@@ -0,0 +1,90 @@
+# Center ↔ Guild 注册握手协议 v1（HMAC）
+
+## 1. 目标
+- 让 Guild Node 在注册时证明自己持有共享密钥（`CENTER_SHARED_SECRET`）
+- 防止中间人篡改与重放攻击
+
+---
+
+## 2. 注册接口
+- **Method:** `POST`
+- **Path:** `/api/nodes/register`
+- **Content-Type:** `application/json`
+
+### Body
+```json
+{
+  "nodeId": "guild-node-1",
+  "name": "Guild Node 1",
+  "endpoint": "http://guild-node-1:7002"
+}
+```
+
+### Required Headers
+- `X-Fabric-Timestamp`: ISO8601 UTC 时间（如 `2026-05-12T11:00:00.000Z`）
+- `X-Fabric-Nonce`: 随机字符串（建议 UUID）
+- `X-Fabric-Signature`: HMAC-SHA256 十六进制串
+
+---
+
+## 3. Canonical String
+签名输入格式（换行拼接）：
+
+```text
+{METHOD}\n{PATH}\n{TIMESTAMP}\n{NONCE}\n{BODY_JSON}
+```
+
+示例：
+```text
+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"}
+```
+
+签名算法：
+```text
+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`
+
+以支持协议平滑升级。