v2.15.0 — HMAC-SHA256 Keygen 算法

v2.15.0 — HMAC-SHA256 Keygen 算法（Breaking Change）

⚠️ Breaking Change

所有现有 sk-pp- API Key 在升级后立即失效。用户需通过 Dashboard /keygen/ 或 CLI 重新生成 Key。

配置文件新增必填字段 auth.keygen_secret（≥32 字符），缺失时服务启动报错。

新功能

HMAC-SHA256 API Key 生成算法

替换旧的指纹嵌入算法，修复碰撞漏洞（如 alice123 与 321ecila 生成相同 key 的问题）。

核心改进：

• HMAC-SHA256 签名：以 keygen_secret 为密钥，用户名为消息，生成 256 位签名
• Base62 编码：签名编码为 48 字符 Base62（0-9A-Za-z），key 总长 54 字符（sk-pp- + 48）
• 确定性生成：相同用户名 + secret → 相同 key（无随机性）
• 碰撞概率：< 2^-143（286 位熵，实际不可能碰撞）
• O(n) 验证：遍历活跃用户列表，逐一 HMAC 重计算比对；KeyCache LRU 缓存保证 >95% 命中率

配置示例：

auth:
  jwt_secret: "your-jwt-secret-at-least-32-chars"
  keygen_secret: "your-keygen-secret-at-least-32-chars"  # v2.15.0 新增必填

升级步骤：

1. 生成 keygen_secret：openssl rand -hex 32
2. 添加到 sproxy.yaml 的 auth.keygen_secret 字段
3. 重启 sproxy
4. 通知用户访问 /keygen/ 重新生成 API Key

测试

新增/重写 85 个测试，覆盖 HMAC 算法功能、错误路径、边界条件、安全性（碰撞/确定性）、集成测试。

总测试数：2,469 RUN（1,906 顶层 + 563 子测试），全部通过。

文档更新

• docs/manual.md §31：HMAC Keygen 完整章节（升级指南、配置、故障排查、回滚）
• docs/TEST_REPORT.md：v2.15.0 测试记录
• docs/ACCEPTANCE_REPORT.md：v2.15.0 验收记录
• README.md：功能特性表更新
• docs/OPENCLAW_OPS_GUIDE.md：v2.3 监控项和故障排查更新

升级指南

数据库：无 schema 变更。

配置文件：必须添加 auth.keygen_secret（≥32 字符），否则启动报错。

用户影响：所有 Direct Proxy 用户需重新生成 API Key（一次性操作）。通过 cproxy JWT 认证的用户不受影响。

回滚：移除 auth.keygen_secret 配置，回退到旧版本二进制即可。注意：v2.15.0 生成的 key 在旧版本上无法验证。

---

Full Changelog: v2.14.0...v2.15.0

Full Changelog: v2.14.1...v2.15.0