feat: simplify HTTP request signing and publish revised client guide
CSS quality / css-quality (push) Has been cancelled
CSS quality / css-quality (push) Has been cancelled
This commit is contained in:
hectorzhao
+605
-819
File diff suppressed because it is too large
Load Diff
@@ -2307,3 +2307,8 @@ Webhook需在当前受支持Node运行时通过真实HTTPS投递；SSRF校验后
|
||||
## 2026-09-14 客户端页面与文档调整
|
||||
|
||||
模板正文统一高度并纵向滚动，添加按钮按内容宽度，删除采用公共风险确认按钮；表单顺序为应用、模板名称、签名、内容，不再展示模板分类，历史分类不清空。接口文档使用独立客户端页面，所有示例紧随对应说明并按用途命名；工作台最近批次显示短信正文和统一中文状态；发送详情必须返回并显示真实回执状态与北京时间，未收到回执不伪造数据。设计与兼容边界见 [客户端整改设计](client-ui-remediation-20260914.md)。
|
||||
|
||||
|
||||
## 2026-09-15 HTTP 客户手册与签名简化
|
||||
|
||||
按用户确认的 B6 手册实施，原2.4移为1.4。POST直接签原始UTF-8正文，GET四项LF分隔且末尾无LF；不兼容尝试旧摘要签名。保持凭据、权限、时间窗、nonce去重、内部发送幂等及Webhook规则。公开页、客户端独立文档页与MD下载共用权威手册，Node示例和完整HTTP报文按新规则验证。新规则替代此前三步正文摘要签名需求，适用本次代码版本；仅授权测试部署，预生产不变。设计及兼容影响见[HTTP整改方案](http-api-assessment-20260910.md)的2026-09-15章节。
|
||||
|
||||
@@ -305,3 +305,15 @@ HTTP-FULL-B02：去除URL IPv6方括号后区分IP字面量与DNS，DNS失败转
|
||||
截至 2026-09-14T07:49:14.156Z，测试环境精确版本97d133442350b9725422ed4e55386f47e37004fd。HTTP-FULL-B01至B04已修复、提交、推送、标准发布并真实复验；74套809项精确候选测试、格式、Lint、类型、构建及安全门禁通过。235项真实请求/断言中229项通过，另6条原始非通过记录已分类并有复测，不删除失败历史。20条短信19送达/1预期失败退款，23个模拟CMPP Submit，21成功计费单位，净扣6825，余额1848101→1841276。7条上行3歧义隐藏/4匹配且ACK完成；24个Webhook事件22送达/2预设终止，31次真实HTTPS收件，签名、密钥轮换、状态码、退避、超时和人工重试均核验。三个Redis Stream pending/lag均0；本轮待办排空、三个应用停用/凭据撤销、receiver及隧道关闭、hosts原字节恢复。未操作预生产、真实运营商或其他客户配置。
|
||||
|
||||
完整矩阵、根因、发布恢复资产/容量与未执行项见 [HTTP全量验收报告](http-api-full-acceptance-20260914.md)。本段更新此前阶段性“待修/待授权/阻塞”状态，不将其当当前状态。
|
||||
|
||||
|
||||
## 2026-09-15 已确认的新请求签名规则（实施中）
|
||||
|
||||
本节按用户最终 B6 手册及本轮实施授权，替代前述 R01/3.2 的摘要签名保留要求；历史日期的实现证据仍保留。本轮公开手册采用 B6 内容，将原 2.4 cURL 使用说明移到 1.4；公开阅读器、客户端 iframe 和 MD 下载继续共用 docs/client-http-api-guide.md。
|
||||
|
||||
- POST：UTF-8 编码的方法、路径、timestamp、nonce 以 LF 分隔，nonce 后一个 LF，再原样追加 rawBody 字节，直接 HMAC-SHA256。禁止对解析后 JSON 重建正文；POST 缺失 rawBody 时拒绝，避免签署与收到的字节不一致。
|
||||
- GET：仅四项以 LF 分隔，末尾无 LF，无正文；携带非空正文拒绝。query 仍不参与签名，路径仍不含域名及 query，不新增编码/排序协议。
|
||||
- 使用原四个鉴权头、路径和凭据；不自动尝试旧摘要算法，不引入隐式双算法。旧签名返回 SIGNATURE_INVALID，既有接入须同步升级。测试环境本轮发布，预生产不发布；回退应用同时恢复原手册，客户须恢复匹配算法。
|
||||
- 时间戳窗口、nonce Redis 原子去重、租户/应用隔离、白名单、QPS 和日志脱敏保持。发送幂等使用的内部 bodyHash 保持，已有请求快照/计费/消息/队列均不迁移、不补投。Webhook 验签不变。
|
||||
- 数据模型、基础设施配置和 Gateway 无改动。历史查询 startTime/endTime 能力保留；手册简化介绍不代表删除后台兼容参数。
|
||||
- 验收：固定 POST/GET 向量、旧签名拒绝、末尾 LF/CRLF/字面反斜杠/正文空格与字段顺序篡改、缺失 rawBody、非空 GET、重放、权限与隔离；真实 HTTP/PG/Redis 验证以隔离数据和无发送请求完成，线上不创建短信或更改客户配置。两段 Node 示例从权威文档提取运行并与全部 HTTP 报文复算；公开页面三尺寸、目录/检索/下载及客户端共享入口验收。按精确提交标准 validate/preflight/prepare/deploy/verify。
|
||||
|
||||
@@ -5526,3 +5526,18 @@ HTTP-FULL-B02：去除URL IPv6方括号后区分IP字面量与DNS，DNS失败转
|
||||
### CLIENT-0914 系列执行结果（2026-09-14 23:25 CST）
|
||||
|
||||
CLIENT-0914-01～07 的模板样式/顺序、文档归属与检索、中文状态/短信正文、回执聚合字段与时区已在独立真实 PostgreSQL/服务组件环境验证；测试部署应用为 4665079。在线文档三尺寸、接口内容和真实数据库查询回执已复核通过；HTTP 环境剪贴板自动复制受限时选中示例并提示手动复制。线上登录后模板/工作台/短信详情全流程因未取得客户端账号仍未执行，不以本地隔离组件或公开文档页面替代。详细日志、首轮 worker 超时与完整复测结果见 [整改记录](client-ui-remediation-20260914.md)。
|
||||
|
||||
|
||||
## 2026-09-15 HTTP 签名简化验收
|
||||
|
||||
本组替代现行版本的旧GET{}摘要/三步签名断言，历史执行记录不改写。
|
||||
|
||||
| 用例 | 验收内容 |
|
||||
| --- | --- |
|
||||
| HTTP-SIGN-0915-01 | 手册2.2 POST原始字节HMAC与固定向量一致；2.3 GET四项以LF分隔、末尾无LF；两段Node示例实际运行，五个完整HTTP报文签名复算一致。 |
|
||||
| HTTP-SIGN-0915-02 | 真实HTTP鉴权拒绝旧摘要签名、GET末尾LF、CRLF和字面反斜杠n；POST正文空格/末尾换行/内容篡改拒绝。 |
|
||||
| HTTP-SIGN-0915-03 | POST无rawBody、GET非空正文返回400；不从解析后JSON重建签名字节。 |
|
||||
| HTTP-SIGN-0915-04 | 真实PG查询仅当前应用资料，其他应用详情404；Redis nonce重放401、过期timestamp及无效凭据401。 |
|
||||
| HTTP-SIGN-0915-05 | 同幂等键/同正文仍读取既有requires_review；改正文409冲突；无消息、批次或队列新增，不恢复未知发送。 |
|
||||
| HTTP-SIGN-0915-06 | 原2.4移到1.4并修正引用；MD下载与源一致，三尺寸目录/刷新/检索/空结果/复制正常，加粗标题成为具名示例；不执行示例请求。 |
|
||||
| HTTP-SIGN-0915-07 | 精确提交测试发布后核对真实文档及新签名查询；旧算法拒绝。账号/凭据缺失时不恢复或新建线上配置，明确未执行范围。 |
|
||||
|
||||
@@ -5018,3 +5018,14 @@ HTTP-FULL-B02：去除URL IPv6方括号后区分IP字面量与DNS，DNS失败转
|
||||
三条真实测试消息的数据库回执保持不变，已部署客户端分页查询服务已由 null 恢复返回 delivered 和真实时间。线上文档三尺寸/43 内嵌示例/检索通过；HTTP 剪贴板受限时实际提供选中后手动复制。当前版本、服务、迁移、队列和日志检查通过无警告。完整登录后客户端页面仍待可用账号；连接器失败不等于用户未登录，本地真实 PG/服务组件验收不替代线上登录验收。
|
||||
|
||||
计划 20260914T151450-4665079ca3d2-874a39f8，备份 attempt-1789399125391792291。远端准备 61.7 秒、备份 34.5 秒、停止开始至启动完成约 13.4 秒。系统盘净增约 1.46 GiB、可用约 17.21 GiB，历史资产未清理。设计、详细证据及未验证项见 [客户端页面与接口文档整改](client-ui-remediation-20260914.md)。预生产未部署；未发送短信或修改业务配置。
|
||||
|
||||
|
||||
## 2026-09-15 HTTP 签名简化实施与测试发布（进行中）
|
||||
|
||||
起点main/实际远端bcb278be29857b73ec11e04650923f473875ca9b，暂存空，53个已有文件保护摘要在.local-data/http-signature-20260915/protected-hashes.json。测试机SSH初期超时、Tailscale relay可达，后续恢复并回读线上4665079ca3d2f985c85c5c1d08f8fe173047e9bd；sudo仍需掩码输入。
|
||||
|
||||
按B6实施POST原始正文HMAC、GET末尾无LF，保留内部幂等摘要和Webhook规则；旧签名不回退尝试。原2.4移1.4、公开/客户端共用MD，补OpenAPI签名描述。页面只读复现加粗示例标题未识别，reader支持加粗标题。相关设计先更新于http-api-assessment-20260910.md。
|
||||
|
||||
定向31项、初轮API全量75套817项及构建通过。独立本地PG16424/cmpp_qa_http_signature（104迁移）、Redis16425、真实Nest16426验收16组通过，包含查询、隔离、篡改、旧算法、重放、幂等及MD下载，短信/批次数均0。仅安全辅助日志隔离为空实现，不将日志持久化标为验收。未启动发送或回调Worker；Redis5.0.14提示建议6.2+，实际nonce命令通过。样本初轮漏carriers、参数错误码断言与真实DTO不一致、幂等样本漏credentialId，修正并保留失败日志；不视为业务缺陷。另一本地PG16安装缺dict_snowball，使用既有完整pgsql安装启动本轮隔离实例。
|
||||
|
||||
CUA本轮可用，实际后端文档三尺寸1600×1000/1366×768/390×844无页面横向溢出；1.4/2.2/2.3顺序、36个具名示例、目录跳转、复制、刷新、错误码检索和空结果通过，控制台无warn/error。当前仅本地页面，线上验收另记。证据目录.local-data/http-signature-20260915；最终精确候选门禁/提交/推送/发布后补。无预生产或业务配置修改、无短信发送。
|
||||
|
||||
Reference in New Issue
Block a user