# 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`

以支持协议平滑升级。