diff --git a/docs/TODO-backend-center-guild.md b/docs/TODO-backend-center-guild.md index 14da932..6d72cd3 100644 --- a/docs/TODO-backend-center-guild.md +++ b/docs/TODO-backend-center-guild.md @@ -64,7 +64,7 @@ ## 3. Center ↔ Guild 协议层 - [x] 鉴权方案定稿(node token / HMAC) -- [ ] 注册握手协议文档化 +- [x] 注册握手协议文档化 - [ ] 错误码与重试策略统一 - [ ] 版本协商(`X-Fabric-Version`) diff --git a/docs/center-guild-handshake-v1.md b/docs/center-guild-handshake-v1.md new file mode 100644 index 0000000..6427618 --- /dev/null +++ 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` + +以支持协议平滑升级。