# yh-platform 签名协议规范（v1.0）

> 权威源：Java `yh-utils-core` `utils.crypto.SignUtil` + `yh-app-auth-spring-boot-starter` `SignCanonical`。
> 本文档为双端（Java / C#）共同遵守的契约工件；任何变更须先改本文，再同步两侧实现。

## 1. 算法

统一使用 **HmacSHA256**，密钥与签名串均为 UTF-8 字节。

## 2. 双签名规则（长期并存，见方案 9.5 裁决 #5 收敛计划）

### 2.1 数据级签名（业务内容签名）

```
source      = data + "|" + timestamp
output      = HmacSHA256(source, secret) 的小写十六进制
timestamp   = 毫秒级时间戳字符串
```

- 验签忽略大小写比对（`equalsIgnoreCase`）。
- `verifyWithExpire`：先比对签名，再校验 `|now - ts| <= expireMs`（默认 5 分钟，双向偏差均拒绝）。

### 2.2 请求级签名（HTTP 请求签名，SDK 出站默认）

```
canonicalTarget = path + ("?" + sortedQuery   # query 为空则不带
source          = METHOD + "\n" + canonicalTarget + "\n" + timestamp
output          = HmacSHA256(source, secret) 的 Base64
```

- `METHOD`：大写（GET/POST），**大小写敏感**精确比对（这是既有行为，是否收敛见方案 9.5 裁决 #3）。
- `path`：**只取路径**，不含 host/port/context-path（保证服务发现/反代前后端天然对齐）。
- **basePath 剥离（客户端与服务端共同口径）**：客户端签名前从 path 剥离部署 basePath（与 UserBase 部署 context-path 一致，如 `/userbase`，对齐 Java `AppSignInterceptor.stripBasePath`）；服务端验签前剥 `request.getContextPath()`（对齐 Java `AppAuthFilter`）。剥离后 canonical 口径统一为 `/oapi/**`。剥离规则：path 不以 basePath 开头时原样保留；剥离后为空或丢失前导斜杠时补 `/`（`/userbase` → `/`）。
- `sortedQuery`：query 按 `k=v` 整串字典序排序后以 `&` 连接；k、v 先 URL 解码再参与排序；多值参数的值也排序。
- 验签为**精确比对**（Base64 区分大小写）。
- `verifyRequestWithExpire` 语义同数据级。
- 测试向量中的 `canonicalTarget` 即**剥离后**的服务端口径（含 `fullUrl`/`basePath` 字段可复现剥离前 URL）。

### 2.3 密钥约束

- secret 最小长度 **16** 位（`MIN_SECRET_LENGTH`），低于此值签名方法抛参数异常。

## 3. HTTP 头契约（逐字一致）

| 头名 | 值 |
|---|---|
| `X-App-Key` | 调用方在 UserBase 注册的 appKey |
| `X-Timestamp` | 毫秒级时间戳字符串 |
| `X-Signature` | 请求级签名（Base64） |

## 4. 防重放

- 时间窗口：`|now - X-Timestamp| > expireMs`（默认 **300000ms**）即拒绝。
- nonce（可选扩展）：同一 `(appKey, timestamp, nonce)` 在窗口内只允许提交一次；
  Redis 键 `sign:replay:{appKey}:{timestamp}:{nonce}`，SETNX + TTL=窗口。

## 5. 验签密钥解析链（服务端）

```
1. Redis  key = sign:app:{appKey}   → 值为 SignAppKeyPayload JSON {appKey, secret, enabled}
2. 进程内缓存（Caffeine / IMemoryCache，TTL 5min）
3. 兜底   GET {userbase}/oapi/internal/sign-key/{appKey} → 信封 data 为 SignAppKeyPayload
```

- 仅当 `enabled=true` 且 `secret` 非空才可用；未知 appKey 直接拒绝。
- 任一层异常静默降级到下一层（Redis 宕机不阻断业务）。

## 6. 测试向量

`fixtures/sign-vectors.json`：≥10 组向量（含空 body、超长参数、中文 UTF-8、query 排序、密钥长度边界、毫秒时间戳边界）。
**基线由 Java `SignUtil` 实际运行产出**；CI 中 Java 侧重算 fixture 防漂移，C# 侧逐字节对拍。