v1.1.2 — Query接口声明补全

OpenAPI / SDK 商户视角文案与接口说明更新

变更内容

• 统一 OpenAPI 中文/英文文档为商户技术人员视角。
• 移除“平台侧、上游渠道、内部运营”等实现视角描述。
• 明确 channel_order_no 始终返回 null，订单查询与业务关联请使用：
  • order_no
  • out_order_no
  • payout_no
  • out_payout_no
  • refund_no
  • out_refund_no
• 同步更新回调说明、错误码说明、支付方式、银行编码和凭证查询文案。
• 同步更新 Node.js、Python、PHP、Go、Java SDK 的 README、接口契约、签名说明、示例和类型注释。
• 已废弃 TypeScript SDK 的 README、声明文件及 dist 产物同步更新。
• 保留“AI 对接提示词”功能；文档中未加入 AI 自述内容。
• PUBLISHING.md 仍保持 SDK 发布维护文档定位，发布流程未改变。

兼容性说明

• 不改变 API 端点、请求参数、签名算法和业务处理流程。
• channel_order_no 的文档说明与现有服务端实际返回行为保持一致，属于文档口径修正。
• SDK 仅调整文案、类型说明和错误提示，不影响正常请求与验签。

v1.1.1 — TypeScript 类型声明 + 纵深加固 / Types & defense-in-depth

向后兼容的「加固 + 类型补强」版本。11 条标准签名向量逐字节不变，合法请求/回调签名零变化——可安全直接升级。
Backward-compatible hardening & typing release. The 11 standard signing vectors are byte-for-byte unchanged — safe drop-in upgrade.

✨ 新增 / Added

• Node.js：新增 index.d.ts 完整 TypeScript 类型声明 / full TypeScript type declarations.
• CI：新增 GitHub Actions 五语言测试向量矩阵 / cross-language test-vector CI matrix.
• 英文文档 / English docs：README / SIGNING / INTERFACES 及各语言子文档.

🔒 加固（纵深防御）/ Hardening (defense-in-depth)

• Go：nonce 生成在 crypto/rand 失败时直接 panic，绝不退化为可预测时间戳（防重放）.
• Node.js：回调 sign 先校验为小写 64 位十六进制再算 HMAC，与其余语言对齐.
• Python：允许只配代收或只配代付密钥，缺失时调用对应方法才 fail-closed（绝不空密钥签名）.
• 版本号与 User-Agent 统一为单一事实源（不再硬编码 1.0.0）.
• INTERFACES 补全 7 个错误码.

🧰 其他 / Misc

• release.sh 健壮性修复.

📦 安装 / Install

• npm: @bebebus/merchant-openapi-sdk@1.1.1
• PyPI: bebebus-merchant-openapi-sdk==1.1.1
• Go: github.com/bebebus/SDK/go@v1.1.1
• Packagist: bebebus/merchant-openapi-sdk

v1.1.0 已包含空密钥回调伪造的 HIGH 安全修复；v1.1.1 在其之上补充类型声明、CI 与纵深加固。
The HIGH empty-key callback-forgery fix already shipped in 1.1.0; 1.1.1 adds types, CI and defense-in-depth.

Full changelog: v1.1.0...v1.1.1

v1.1.0 — 回调验签 fail-closed 安全加固

概要

本版聚焦回调验签与签名链路的安全加固(由 6
语言对抗审计驱动),并统一对外文档口径。
合法整数载荷的签名结果零变化——11
条标准向量(test-vectors.json)逐字节不变,1.0.0 的正常用法无需改代码即可平滑升级。

🔒 安全加固

• 回调验签 fail-closed(重点,建议所有用户升级):verifyCallback 在计算 HMAC
  之前即拒绝空 / 全空白 / 非字符串密钥(返回 false),并拒绝非字符串 /
  非十六进制的 sign;sign()
  对空密钥直接报错。消除"密钥误配为空时验签退化为可被任意伪造"的 fail-open 隐患。
• 验签对非法输入恒返回布尔:非 ASCII / 畸形 sign、null /
  非对象回调体一律判失败,不再抛异常冒泡,保证 fail-closed 契约。
• Go 具体类型容器签名:map[string]string / []string / struct
  等以前被静默签成空串(签名豁免面),现经反射正确序列化。
• 数值守卫:签名载荷中的 NaN / Infinity /
  非整数浮点一律拒绝(合约要求整数最小单位),-0 归一为 "0",超 2^53 大整数拒绝(防
  Java (long) 饱和把不同大额改写成同一错值)。
• 传输加固:非 localhost 基址强制 https;Go / TS 禁止跟随重定向;PHP 钉死
  CURLOPT_SSL_VERIFYPEER/VERIFYHOST;Python 拒绝 file:// 等非 http(s) 协议。
• PHP 新增 verifyCallbackRaw():内部以 JSON_BIGINT_AS_STRING
  解码,避免大整数被转 float 致验签误拒。

📝 文档

• 金额口径统一为「= 实际金额 × 10000 的整数」,移除"精度 0.0001 / 10000 = 1
  元"表述与货币假设。
• INTERFACES.md 的 channel_order_no 由"恒
  null"改为统一标注"(可空)",与服务端对外文档口径一致。

✅ 兼容性 / 升级

向后兼容:合法用法(整数金额、非空密钥、合法回调体)的行为与签名完全不变,11
条标准向量逐字节通过。

• 行为收紧仅作用于非法 /
  异常输入:之前被静默接受或静默分叉的空密钥、浮点、非法 sign、明文 http 等现在
  fail-closed(返回 false
  或抛清晰错误)。若此前依赖这些"碰巧能用",升级后会显式报错——这是预期的安全改进。

📦 安装

• npm: npm i @bebebus/merchant-openapi-sdk@1.1.0
• PyPI: pip install -U bebebus-merchant-openapi-sdk==1.1.0
• Packagist: composer require bebebus/merchant-openapi-sdk:^1.1
• Go: go get github.com/bebebus/SDK/go@v1.1.0

Full Changelog: v1.0.0...v1.1.0

v1.0.0

商户支付 OpenAPI 多语言 SDK 首个正式版。PHP / Python / Java / Go / Node.js
五套，零第三方依赖，覆盖全部 11 个端点 + HMAC-SHA256 签名 + 回调验签 + 双环境。

安装

• Node.js: npm i @bebebus/merchant-openapi-sdk
• Python: pip install bebebus-merchant-openapi-sdk
• PHP: composer require bebebus/merchant-openapi-sdk
• Go: go get github.com/bebebus/SDK/go@v1.0.0
• Java: 源码引入（cloud.cniia.openapi.sdk，未发 Maven）

亮点

• 全 11 端点（代收 5 + 代付 6）
• 跨语言签名逐字节一致（test-vectors.json 11 向量锁定，五套单测全绿）
• 五语言 dev 联调各 10/10（含真实冻结、签名拒绝负例、回调验签）
• 双环境（SANDBOX 内置 / PRODUCTION 传 baseUrl）
• 零第三方依赖，MIT