wop-python-sdk 0.1.6__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. {wop_python_sdk-0.1.6/src/wop_python_sdk.egg-info → wop_python_sdk-0.2.0}/PKG-INFO +53 -9
  2. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/README.md +52 -8
  3. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/pyproject.toml +9 -3
  4. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0/src/wop_python_sdk.egg-info}/PKG-INFO +53 -9
  5. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/src/wop_python_sdk.egg-info/SOURCES.txt +13 -0
  6. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/src/wop_sdk/__init__.py +29 -12
  7. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/src/wop_sdk/canonical.py +5 -4
  8. wop_python_sdk-0.2.0/src/wop_sdk/client.py +515 -0
  9. wop_python_sdk-0.2.0/src/wop_sdk/config/__init__.py +12 -0
  10. wop_python_sdk-0.2.0/src/wop_sdk/config/_loader.py +130 -0
  11. wop_python_sdk-0.2.0/src/wop_sdk/config/_models.py +122 -0
  12. wop_python_sdk-0.2.0/src/wop_sdk/config/_parser.py +186 -0
  13. wop_python_sdk-0.2.0/src/wop_sdk/config/_validator.py +114 -0
  14. wop_python_sdk-0.2.0/src/wop_sdk/config/wopSdkConfig.json +14 -0
  15. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/src/wop_sdk/digest.py +2 -4
  16. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/src/wop_sdk/encoding.py +1 -3
  17. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/src/wop_sdk/envelope.py +60 -11
  18. wop_python_sdk-0.2.0/src/wop_sdk/errors.py +103 -0
  19. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/src/wop_sdk/keys.py +2 -2
  20. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/src/wop_sdk/sm2crypto.py +55 -6
  21. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/src/wop_sdk/suites.py +7 -10
  22. wop_python_sdk-0.2.0/src/wop_sdk/transport_discovery.py +50 -0
  23. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/src/wop_sdk/transports/httpx_transport.py +2 -2
  24. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/src/wop_sdk/transports/requests_transport.py +2 -2
  25. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/src/wop_sdk/transports/urllib_transport.py +10 -4
  26. wop_python_sdk-0.2.0/tests/test_bdd.py +519 -0
  27. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/tests/test_client.py +160 -19
  28. wop_python_sdk-0.2.0/tests/test_config.py +352 -0
  29. wop_python_sdk-0.2.0/tests/test_config_loading.py +307 -0
  30. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/tests/test_coverage_gaps.py +152 -9
  31. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/tests/test_envelope.py +34 -8
  32. wop_python_sdk-0.2.0/tests/test_interop.py +288 -0
  33. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/tests/test_keys.py +10 -0
  34. wop_python_sdk-0.2.0/tests/test_mutation_gaps.py +124 -0
  35. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/tests/test_signature.py +16 -4
  36. wop_python_sdk-0.2.0/tests/test_submchid.py +193 -0
  37. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/tests/test_suites.py +17 -1
  38. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/tests/test_transports.py +11 -0
  39. wop_python_sdk-0.1.6/src/wop_sdk/client.py +0 -258
  40. wop_python_sdk-0.1.6/src/wop_sdk/errors.py +0 -48
  41. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/LICENSE +0 -0
  42. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/setup.cfg +0 -0
  43. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/src/wop_python_sdk.egg-info/dependency_links.txt +0 -0
  44. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/src/wop_python_sdk.egg-info/requires.txt +0 -0
  45. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/src/wop_python_sdk.egg-info/top_level.txt +0 -0
  46. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/src/wop_sdk/signature.py +0 -0
  47. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/src/wop_sdk/sm4gcm.py +0 -0
  48. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/src/wop_sdk/transports/__init__.py +0 -0
  49. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/tests/test_canonical.py +0 -0
  50. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/tests/test_digest.py +0 -0
  51. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/tests/test_encoding.py +0 -0
  52. {wop_python_sdk-0.1.6 → wop_python_sdk-0.2.0}/tests/test_transports_real.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: wop-python-sdk
3
- Version: 0.1.6
3
+ Version: 0.2.0
4
4
  Summary: WOP 商户侧官方 Python SDK:协议核心(签名/摘要/数字信封/验签解密)+ 可插拔 HTTP 适配层
5
5
  Author: wop-platform
6
6
  License: MIT
@@ -30,14 +30,20 @@ Dynamic: license-file
30
30
 
31
31
  # WOP Python SDK
32
32
 
33
+ [![PyPI](https://img.shields.io/pypi/v/wop-python-sdk)](https://pypi.org/project/wop-python-sdk/) [![Python 3.9+](https://img.shields.io/pypi/pyversions/wop-python-sdk)](https://pypi.org/project/wop-python-sdk/) [![Release](https://img.shields.io/github/v/release/wop-platform/wop-python-sdk)](https://github.com/wop-platform/wop-python-sdk/releases)
34
+ [![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/wop-platform/wop-python-sdk/actions/workflows/ci.yml) [![Gherkin](https://img.shields.io/badge/bdd-21%20scenarios-orange)](tests/features/wop_merchant.feature) ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/wop-platform/wop-python-sdk?utm_source=oss&utm_medium=github&utm_campaign=wop-platform%2Fwop-python-sdk&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
35
+
36
+
37
+ > **WOP · 万联易达开放平台** 官方 Python SDK —— 协议与黄金向量真源:[wop-specs](https://github.com/wop-platform/wop-specs)
38
+
33
39
  WOP 网关商户侧官方 Python 客户端库:封装协议核心(套件解析 / 结构化签名 / 内容摘要 /
34
40
  L2 数字信封 / 验签解密)与可插拔 HTTP 适配层,使商户无需理解 canonicalRequest、
35
41
  算法套件推导与线上字节格式即可安全对接网关。
36
42
 
37
- - 协议真源:[crypto-strategy-spec.md](https://github.com/wop-platform/wop-specs/blob/main/crypto/crypto-strategy-spec.md)(v0.3-reviewed)+ [wop-sdk-spec.md](https://github.com/wop-platform/wop-specs/blob/main/sdk/wop-sdk-spec.md)(v1.0-ratified)
43
+ - 协议真源:[crypto-strategy-spec.md](https://github.com/wop-platform/wop-specs/blob/main/crypto/crypto-strategy-spec.md)(v0.3-reviewed)+ [wop-sdk-spec.md](https://github.com/wop-platform/wop-specs/blob/main/docs/specs/wop-sdk-spec.md)(v1.0-ratified)
38
44
  - 向量真源:[crypto-vectors.json](https://github.com/wop-platform/wop-specs/blob/main/crypto/crypto-vectors.json)(本仓 fixture 为字节级副本,禁手改)
39
45
  - Python ≥ 3.9
40
- - 三套件全支持:`WOP-RSA3072-SHA256` / `WOP-RSA4096-SHA256` / `WOP-SM2-SM3`
46
+ - 四套件全支持:`WOP-RSA2048-SHA256` / `WOP-RSA3072-SHA256` / `WOP-RSA4096-SHA256` / `WOP-SM2-SM3`
41
47
  - 密码依赖(唯一指定路径):`cryptography`(RSA/AES)+ `gmssl ≥ 3.2.2`(SM2/SM3/SM4)
42
48
  - 主包零额外依赖;HTTP 适配器以 peer 依赖交付(`wop-python-sdk[httpx]` / `wop-python-sdk[requests]`)
43
49
 
@@ -54,7 +60,7 @@ from wop_sdk.transports import UrllibTransport, send_draft
54
60
 
55
61
  client = WopClient(WopConfig(
56
62
  app_key="app_10012481831",
57
- suite="WOP-RSA3072-SHA256", # 或 WOP-RSA4096-SHA256 / WOP-SM2-SM3
63
+ suite="WOP-RSA2048-SHA256", # 或 WOP-RSA4096-SHA256 / WOP-SM2-SM3
58
64
  merchant_private_key=MERCHANT_PRIV_PEM, # 商户私钥(PEM 或 Base64 单行)
59
65
  platform_public_key=PLATFORM_PUB_PEM, # 平台公钥(PEM 或 Base64 单行)
60
66
  gateway_base_url="https://wop.example.com",
@@ -74,12 +80,31 @@ else:
74
80
  print(result.reason) # 验签/解密失败对外模糊(I7),格式/完整性/一致性类明确
75
81
  ```
76
82
 
83
+ ## ISV 子商户身份(ISV D-13)
84
+
85
+ 代子商户调用业务 API 时,按请求传 `sub_mch_id`(值 = 子商户 `plf_co_id`):
86
+
87
+ ```python
88
+ draft = client.build_request("POST", "/gateway/order/create", body, level="L0",
89
+ sub_mch_id="PLF-SUB-001")
90
+ # 一站式调用:
91
+ result = client.execute("POST", "/gateway/order/create", body, level="L0",
92
+ sub_mch_id="PLF-SUB-001")
93
+ ```
94
+
95
+ SDK 在签名前写入 `x-wop-sub-mch-id`,并自动纳入 `x-wop-sign` 的 signedHeaders。
96
+ 首尾空白 trim 后发送;仅接受可打印 ASCII(0x20–0x7E)、无内部空白、≤128 字符,
97
+ 违规抛 `ConfigurationError`。不传或纯空白 = 应用自身身份,头缺席,请求头集合与签名
98
+ 与旧版逐字节一致(AC-20)。`extra_headers` 携带该头等价于参数;双来源同传构造即拒。
99
+ 该头仅在网关子商户灰度放行且应用为 ISV 应用(`app_type=20`)时生效。
100
+
77
101
  ## 密钥准备
78
102
 
79
103
  密钥入参为字符串(PEM 或 Base64 单行),SDK 内部解析(D12 分发契约):
80
104
 
81
105
  | 套件 | 商户私钥 | 平台公钥 | 约束 |
82
106
  |------|----------|----------|------|
107
+ | `WOP-RSA2048-SHA256` | PKCS#8 DER,Base64/PEM | X.509 SPKI DER,Base64/PEM | 密钥必须 2048 位 |
83
108
  | `WOP-RSA3072-SHA256` | PKCS#8 DER,Base64/PEM | X.509 SPKI DER,Base64/PEM | 密钥必须 3072 位 |
84
109
  | `WOP-RSA4096-SHA256` | 同上 | 同上 | 密钥必须 4096 位 |
85
110
  | `WOP-SM2-SM3` | `d` 标量 32 字节,Base64 | 未压缩点 `04‖X‖Y` 65 字节,Base64 | 点必须在 sm2p256v1 曲线上(I5) |
@@ -126,14 +151,33 @@ pip install -e '.[httpx]' coverage
126
151
  python3 -m pytest --cov=wop_sdk --cov-branch --cov-fail-under=98
127
152
  ```
128
153
 
129
- 覆盖:RSA3072/4096 与 SM2 签名字节级断言、OAEP 包装/解包、AES-256-GCM 与 SM4-GCM
154
+ 覆盖:RSA2048/3072/4096 与 SM2 签名字节级断言、OAEP 包装/解包、AES-256-GCM 与 SM4-GCM
130
155
  密文字节级断言、SM3/SHA-256 摘要、DEK 载荷组装、digest 头全部格式规则;负向量含
131
156
  tamper / 跨族 / 63B、65B 签名 / 带 `=` 的 base64url / C1C2C3 旧国标顺序 /
132
- MGF1-SHA1 陷阱密文,全部必须拒绝。CI(3.9–3.14 矩阵)执行同一命令。
157
+ MGF1-SHA1 陷阱密文,全部必须拒绝。CI(3.9–3.14 × linux/macOS 矩阵)执行同一命令。
158
+
159
+ 另消费 `wop-specs` 组织级 interop 样本集(`tests/fixtures/interop-cases.json` 字节
160
+ 副本,sha256 哨兵钉死):build 方向按冻结输入复现 draft(RSA byte-exact;SM2 按
161
+ opaque 剥离签名/包装段),verify 方向 24 条冻结样本逐条对账明文与错误分类
162
+ (canonical class 映射表见 `tests/test_interop.py`)。
133
163
 
134
164
  ## 错误处理与模糊化
135
165
 
136
- - **明确**(公开协议知识,帮助集成自查):套件格式/跨族、密钥材料、digest 头格式与
137
- 不匹配、DEK alg 与套件族不符;
166
+ - **明确**(公开协议知识,帮助集成自查):套件格式/跨族、密钥材料、digest 头格式、
167
+ 缺失与不匹配(D2/I1 结构前置校验)、信封 JSON 形态与各 base64url 段(F7)、
168
+ DEK alg 与套件族不符;
138
169
  - **模糊**(依赖密钥参与,防 oracle,I7):签名验证失败、解密失败——对外消息不区分
139
- tag 失败 / 密钥不符等原因细节。
170
+ tag 失败 / 密钥不符等原因细节;DEK 载荷(解包后明文)结构畸形除 alg 跨族外一律
171
+ 归入解密失败(interop 合同 n13 / 故障注入手册 P3)。
172
+
173
+ ---
174
+
175
+ ## 🧩 WOP 生态导航 | Ecosystem
176
+
177
+ | 类别 | 组件 |
178
+ |------|------|
179
+ | 协议与向量真源 | [wop-specs](https://github.com/wop-platform/wop-specs) —— crypto-strategy-spec · wop-sdk-spec · 黄金测试向量 |
180
+ | 官方 SDK(六语言) | [Java](https://github.com/wop-platform/wop-java-sdk) · [Go](https://github.com/wop-platform/wop-go-sdk) · [Python](https://github.com/wop-platform/wop-python-sdk) · [PHP](https://github.com/wop-platform/wop-php-sdk) · [.NET](https://github.com/wop-platform/wop-dotnet-sdk) · [TypeScript](https://github.com/wop-platform/wop-typescript-sdk) |
181
+ | 浏览器工作台 | [wop-web-tools](https://github.com/wop-platform/wop-web-tools) —— 密钥生成 · 报文联调 · 国密 · 六语言代码片段 |
182
+ | Agent 技能包 | [wop-skills](https://github.com/wop-platform/wop-skills) —— 零代码调用 · 联调对拍 · 62 错误码排错 |
183
+ | 平台服务(企业内部) | 统一接入网关 · 核心逻辑服务 · 回调服务 · 开发者门户 · 文档中心 |
@@ -1,13 +1,19 @@
1
1
  # WOP Python SDK
2
2
 
3
+ [![PyPI](https://img.shields.io/pypi/v/wop-python-sdk)](https://pypi.org/project/wop-python-sdk/) [![Python 3.9+](https://img.shields.io/pypi/pyversions/wop-python-sdk)](https://pypi.org/project/wop-python-sdk/) [![Release](https://img.shields.io/github/v/release/wop-platform/wop-python-sdk)](https://github.com/wop-platform/wop-python-sdk/releases)
4
+ [![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/wop-platform/wop-python-sdk/actions/workflows/ci.yml) [![Gherkin](https://img.shields.io/badge/bdd-21%20scenarios-orange)](tests/features/wop_merchant.feature) ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/wop-platform/wop-python-sdk?utm_source=oss&utm_medium=github&utm_campaign=wop-platform%2Fwop-python-sdk&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
5
+
6
+
7
+ > **WOP · 万联易达开放平台** 官方 Python SDK —— 协议与黄金向量真源:[wop-specs](https://github.com/wop-platform/wop-specs)
8
+
3
9
  WOP 网关商户侧官方 Python 客户端库:封装协议核心(套件解析 / 结构化签名 / 内容摘要 /
4
10
  L2 数字信封 / 验签解密)与可插拔 HTTP 适配层,使商户无需理解 canonicalRequest、
5
11
  算法套件推导与线上字节格式即可安全对接网关。
6
12
 
7
- - 协议真源:[crypto-strategy-spec.md](https://github.com/wop-platform/wop-specs/blob/main/crypto/crypto-strategy-spec.md)(v0.3-reviewed)+ [wop-sdk-spec.md](https://github.com/wop-platform/wop-specs/blob/main/sdk/wop-sdk-spec.md)(v1.0-ratified)
13
+ - 协议真源:[crypto-strategy-spec.md](https://github.com/wop-platform/wop-specs/blob/main/crypto/crypto-strategy-spec.md)(v0.3-reviewed)+ [wop-sdk-spec.md](https://github.com/wop-platform/wop-specs/blob/main/docs/specs/wop-sdk-spec.md)(v1.0-ratified)
8
14
  - 向量真源:[crypto-vectors.json](https://github.com/wop-platform/wop-specs/blob/main/crypto/crypto-vectors.json)(本仓 fixture 为字节级副本,禁手改)
9
15
  - Python ≥ 3.9
10
- - 三套件全支持:`WOP-RSA3072-SHA256` / `WOP-RSA4096-SHA256` / `WOP-SM2-SM3`
16
+ - 四套件全支持:`WOP-RSA2048-SHA256` / `WOP-RSA3072-SHA256` / `WOP-RSA4096-SHA256` / `WOP-SM2-SM3`
11
17
  - 密码依赖(唯一指定路径):`cryptography`(RSA/AES)+ `gmssl ≥ 3.2.2`(SM2/SM3/SM4)
12
18
  - 主包零额外依赖;HTTP 适配器以 peer 依赖交付(`wop-python-sdk[httpx]` / `wop-python-sdk[requests]`)
13
19
 
@@ -24,7 +30,7 @@ from wop_sdk.transports import UrllibTransport, send_draft
24
30
 
25
31
  client = WopClient(WopConfig(
26
32
  app_key="app_10012481831",
27
- suite="WOP-RSA3072-SHA256", # 或 WOP-RSA4096-SHA256 / WOP-SM2-SM3
33
+ suite="WOP-RSA2048-SHA256", # 或 WOP-RSA4096-SHA256 / WOP-SM2-SM3
28
34
  merchant_private_key=MERCHANT_PRIV_PEM, # 商户私钥(PEM 或 Base64 单行)
29
35
  platform_public_key=PLATFORM_PUB_PEM, # 平台公钥(PEM 或 Base64 单行)
30
36
  gateway_base_url="https://wop.example.com",
@@ -44,12 +50,31 @@ else:
44
50
  print(result.reason) # 验签/解密失败对外模糊(I7),格式/完整性/一致性类明确
45
51
  ```
46
52
 
53
+ ## ISV 子商户身份(ISV D-13)
54
+
55
+ 代子商户调用业务 API 时,按请求传 `sub_mch_id`(值 = 子商户 `plf_co_id`):
56
+
57
+ ```python
58
+ draft = client.build_request("POST", "/gateway/order/create", body, level="L0",
59
+ sub_mch_id="PLF-SUB-001")
60
+ # 一站式调用:
61
+ result = client.execute("POST", "/gateway/order/create", body, level="L0",
62
+ sub_mch_id="PLF-SUB-001")
63
+ ```
64
+
65
+ SDK 在签名前写入 `x-wop-sub-mch-id`,并自动纳入 `x-wop-sign` 的 signedHeaders。
66
+ 首尾空白 trim 后发送;仅接受可打印 ASCII(0x20–0x7E)、无内部空白、≤128 字符,
67
+ 违规抛 `ConfigurationError`。不传或纯空白 = 应用自身身份,头缺席,请求头集合与签名
68
+ 与旧版逐字节一致(AC-20)。`extra_headers` 携带该头等价于参数;双来源同传构造即拒。
69
+ 该头仅在网关子商户灰度放行且应用为 ISV 应用(`app_type=20`)时生效。
70
+
47
71
  ## 密钥准备
48
72
 
49
73
  密钥入参为字符串(PEM 或 Base64 单行),SDK 内部解析(D12 分发契约):
50
74
 
51
75
  | 套件 | 商户私钥 | 平台公钥 | 约束 |
52
76
  |------|----------|----------|------|
77
+ | `WOP-RSA2048-SHA256` | PKCS#8 DER,Base64/PEM | X.509 SPKI DER,Base64/PEM | 密钥必须 2048 位 |
53
78
  | `WOP-RSA3072-SHA256` | PKCS#8 DER,Base64/PEM | X.509 SPKI DER,Base64/PEM | 密钥必须 3072 位 |
54
79
  | `WOP-RSA4096-SHA256` | 同上 | 同上 | 密钥必须 4096 位 |
55
80
  | `WOP-SM2-SM3` | `d` 标量 32 字节,Base64 | 未压缩点 `04‖X‖Y` 65 字节,Base64 | 点必须在 sm2p256v1 曲线上(I5) |
@@ -96,14 +121,33 @@ pip install -e '.[httpx]' coverage
96
121
  python3 -m pytest --cov=wop_sdk --cov-branch --cov-fail-under=98
97
122
  ```
98
123
 
99
- 覆盖:RSA3072/4096 与 SM2 签名字节级断言、OAEP 包装/解包、AES-256-GCM 与 SM4-GCM
124
+ 覆盖:RSA2048/3072/4096 与 SM2 签名字节级断言、OAEP 包装/解包、AES-256-GCM 与 SM4-GCM
100
125
  密文字节级断言、SM3/SHA-256 摘要、DEK 载荷组装、digest 头全部格式规则;负向量含
101
126
  tamper / 跨族 / 63B、65B 签名 / 带 `=` 的 base64url / C1C2C3 旧国标顺序 /
102
- MGF1-SHA1 陷阱密文,全部必须拒绝。CI(3.9–3.14 矩阵)执行同一命令。
127
+ MGF1-SHA1 陷阱密文,全部必须拒绝。CI(3.9–3.14 × linux/macOS 矩阵)执行同一命令。
128
+
129
+ 另消费 `wop-specs` 组织级 interop 样本集(`tests/fixtures/interop-cases.json` 字节
130
+ 副本,sha256 哨兵钉死):build 方向按冻结输入复现 draft(RSA byte-exact;SM2 按
131
+ opaque 剥离签名/包装段),verify 方向 24 条冻结样本逐条对账明文与错误分类
132
+ (canonical class 映射表见 `tests/test_interop.py`)。
103
133
 
104
134
  ## 错误处理与模糊化
105
135
 
106
- - **明确**(公开协议知识,帮助集成自查):套件格式/跨族、密钥材料、digest 头格式与
107
- 不匹配、DEK alg 与套件族不符;
136
+ - **明确**(公开协议知识,帮助集成自查):套件格式/跨族、密钥材料、digest 头格式、
137
+ 缺失与不匹配(D2/I1 结构前置校验)、信封 JSON 形态与各 base64url 段(F7)、
138
+ DEK alg 与套件族不符;
108
139
  - **模糊**(依赖密钥参与,防 oracle,I7):签名验证失败、解密失败——对外消息不区分
109
- tag 失败 / 密钥不符等原因细节。
140
+ tag 失败 / 密钥不符等原因细节;DEK 载荷(解包后明文)结构畸形除 alg 跨族外一律
141
+ 归入解密失败(interop 合同 n13 / 故障注入手册 P3)。
142
+
143
+ ---
144
+
145
+ ## 🧩 WOP 生态导航 | Ecosystem
146
+
147
+ | 类别 | 组件 |
148
+ |------|------|
149
+ | 协议与向量真源 | [wop-specs](https://github.com/wop-platform/wop-specs) —— crypto-strategy-spec · wop-sdk-spec · 黄金测试向量 |
150
+ | 官方 SDK(六语言) | [Java](https://github.com/wop-platform/wop-java-sdk) · [Go](https://github.com/wop-platform/wop-go-sdk) · [Python](https://github.com/wop-platform/wop-python-sdk) · [PHP](https://github.com/wop-platform/wop-php-sdk) · [.NET](https://github.com/wop-platform/wop-dotnet-sdk) · [TypeScript](https://github.com/wop-platform/wop-typescript-sdk) |
151
+ | 浏览器工作台 | [wop-web-tools](https://github.com/wop-platform/wop-web-tools) —— 密钥生成 · 报文联调 · 国密 · 六语言代码片段 |
152
+ | Agent 技能包 | [wop-skills](https://github.com/wop-platform/wop-skills) —— 零代码调用 · 联调对拍 · 62 错误码排错 |
153
+ | 平台服务(企业内部) | 统一接入网关 · 核心逻辑服务 · 回调服务 · 开发者门户 · 文档中心 |
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "wop-python-sdk"
7
- version = "0.1.6"
7
+ version = "0.2.0"
8
8
  description = "WOP 商户侧官方 Python SDK:协议核心(签名/摘要/数字信封/验签解密)+ 可插拔 HTTP 适配层"
9
9
  readme = "README.md"
10
10
  license = { text = "MIT" }
@@ -36,9 +36,11 @@ httpx = ["httpx>=0.24"]
36
36
  requests = ["requests>=2.28"]
37
37
 
38
38
  [dependency-groups]
39
- # 发布构建前端(PEP 735,不进发布元数据):
39
+ # 发布构建前端 + BDD 测试工具链(PEP 735,不进发布元数据):
40
40
  # pip install --group dev && python -m build
41
- dev = ["build"]
41
+ # griffe:公共 API 快照门禁工具,版本锁定保证快照字节确定性
42
+ # (scripts/check-api-snapshot.py 与 ci.yml api-snapshot job)
43
+ dev = ["build", "pytest-bdd>=8.0,<9.0", "griffe==1.14.0"]
42
44
 
43
45
  [project.urls]
44
46
  Homepage = "https://github.com/wop-platform/wop-python-sdk"
@@ -46,6 +48,10 @@ Homepage = "https://github.com/wop-platform/wop-python-sdk"
46
48
  [tool.setuptools.packages.find]
47
49
  where = ["src"]
48
50
 
51
+ # 配置发现兜底来源(K6 优先级 6):打包资源随包分发,setuptools 默认不收 JSON
52
+ [tool.setuptools.package-data]
53
+ "wop_sdk.config" = ["*.json"]
54
+
49
55
  [tool.pytest.ini_options]
50
56
  testpaths = ["tests"]
51
57
  pythonpath = ["src"]
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: wop-python-sdk
3
- Version: 0.1.6
3
+ Version: 0.2.0
4
4
  Summary: WOP 商户侧官方 Python SDK:协议核心(签名/摘要/数字信封/验签解密)+ 可插拔 HTTP 适配层
5
5
  Author: wop-platform
6
6
  License: MIT
@@ -30,14 +30,20 @@ Dynamic: license-file
30
30
 
31
31
  # WOP Python SDK
32
32
 
33
+ [![PyPI](https://img.shields.io/pypi/v/wop-python-sdk)](https://pypi.org/project/wop-python-sdk/) [![Python 3.9+](https://img.shields.io/pypi/pyversions/wop-python-sdk)](https://pypi.org/project/wop-python-sdk/) [![Release](https://img.shields.io/github/v/release/wop-platform/wop-python-sdk)](https://github.com/wop-platform/wop-python-sdk/releases)
34
+ [![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/wop-platform/wop-python-sdk/actions/workflows/ci.yml) [![Gherkin](https://img.shields.io/badge/bdd-21%20scenarios-orange)](tests/features/wop_merchant.feature) ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/wop-platform/wop-python-sdk?utm_source=oss&utm_medium=github&utm_campaign=wop-platform%2Fwop-python-sdk&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
35
+
36
+
37
+ > **WOP · 万联易达开放平台** 官方 Python SDK —— 协议与黄金向量真源:[wop-specs](https://github.com/wop-platform/wop-specs)
38
+
33
39
  WOP 网关商户侧官方 Python 客户端库:封装协议核心(套件解析 / 结构化签名 / 内容摘要 /
34
40
  L2 数字信封 / 验签解密)与可插拔 HTTP 适配层,使商户无需理解 canonicalRequest、
35
41
  算法套件推导与线上字节格式即可安全对接网关。
36
42
 
37
- - 协议真源:[crypto-strategy-spec.md](https://github.com/wop-platform/wop-specs/blob/main/crypto/crypto-strategy-spec.md)(v0.3-reviewed)+ [wop-sdk-spec.md](https://github.com/wop-platform/wop-specs/blob/main/sdk/wop-sdk-spec.md)(v1.0-ratified)
43
+ - 协议真源:[crypto-strategy-spec.md](https://github.com/wop-platform/wop-specs/blob/main/crypto/crypto-strategy-spec.md)(v0.3-reviewed)+ [wop-sdk-spec.md](https://github.com/wop-platform/wop-specs/blob/main/docs/specs/wop-sdk-spec.md)(v1.0-ratified)
38
44
  - 向量真源:[crypto-vectors.json](https://github.com/wop-platform/wop-specs/blob/main/crypto/crypto-vectors.json)(本仓 fixture 为字节级副本,禁手改)
39
45
  - Python ≥ 3.9
40
- - 三套件全支持:`WOP-RSA3072-SHA256` / `WOP-RSA4096-SHA256` / `WOP-SM2-SM3`
46
+ - 四套件全支持:`WOP-RSA2048-SHA256` / `WOP-RSA3072-SHA256` / `WOP-RSA4096-SHA256` / `WOP-SM2-SM3`
41
47
  - 密码依赖(唯一指定路径):`cryptography`(RSA/AES)+ `gmssl ≥ 3.2.2`(SM2/SM3/SM4)
42
48
  - 主包零额外依赖;HTTP 适配器以 peer 依赖交付(`wop-python-sdk[httpx]` / `wop-python-sdk[requests]`)
43
49
 
@@ -54,7 +60,7 @@ from wop_sdk.transports import UrllibTransport, send_draft
54
60
 
55
61
  client = WopClient(WopConfig(
56
62
  app_key="app_10012481831",
57
- suite="WOP-RSA3072-SHA256", # 或 WOP-RSA4096-SHA256 / WOP-SM2-SM3
63
+ suite="WOP-RSA2048-SHA256", # 或 WOP-RSA4096-SHA256 / WOP-SM2-SM3
58
64
  merchant_private_key=MERCHANT_PRIV_PEM, # 商户私钥(PEM 或 Base64 单行)
59
65
  platform_public_key=PLATFORM_PUB_PEM, # 平台公钥(PEM 或 Base64 单行)
60
66
  gateway_base_url="https://wop.example.com",
@@ -74,12 +80,31 @@ else:
74
80
  print(result.reason) # 验签/解密失败对外模糊(I7),格式/完整性/一致性类明确
75
81
  ```
76
82
 
83
+ ## ISV 子商户身份(ISV D-13)
84
+
85
+ 代子商户调用业务 API 时,按请求传 `sub_mch_id`(值 = 子商户 `plf_co_id`):
86
+
87
+ ```python
88
+ draft = client.build_request("POST", "/gateway/order/create", body, level="L0",
89
+ sub_mch_id="PLF-SUB-001")
90
+ # 一站式调用:
91
+ result = client.execute("POST", "/gateway/order/create", body, level="L0",
92
+ sub_mch_id="PLF-SUB-001")
93
+ ```
94
+
95
+ SDK 在签名前写入 `x-wop-sub-mch-id`,并自动纳入 `x-wop-sign` 的 signedHeaders。
96
+ 首尾空白 trim 后发送;仅接受可打印 ASCII(0x20–0x7E)、无内部空白、≤128 字符,
97
+ 违规抛 `ConfigurationError`。不传或纯空白 = 应用自身身份,头缺席,请求头集合与签名
98
+ 与旧版逐字节一致(AC-20)。`extra_headers` 携带该头等价于参数;双来源同传构造即拒。
99
+ 该头仅在网关子商户灰度放行且应用为 ISV 应用(`app_type=20`)时生效。
100
+
77
101
  ## 密钥准备
78
102
 
79
103
  密钥入参为字符串(PEM 或 Base64 单行),SDK 内部解析(D12 分发契约):
80
104
 
81
105
  | 套件 | 商户私钥 | 平台公钥 | 约束 |
82
106
  |------|----------|----------|------|
107
+ | `WOP-RSA2048-SHA256` | PKCS#8 DER,Base64/PEM | X.509 SPKI DER,Base64/PEM | 密钥必须 2048 位 |
83
108
  | `WOP-RSA3072-SHA256` | PKCS#8 DER,Base64/PEM | X.509 SPKI DER,Base64/PEM | 密钥必须 3072 位 |
84
109
  | `WOP-RSA4096-SHA256` | 同上 | 同上 | 密钥必须 4096 位 |
85
110
  | `WOP-SM2-SM3` | `d` 标量 32 字节,Base64 | 未压缩点 `04‖X‖Y` 65 字节,Base64 | 点必须在 sm2p256v1 曲线上(I5) |
@@ -126,14 +151,33 @@ pip install -e '.[httpx]' coverage
126
151
  python3 -m pytest --cov=wop_sdk --cov-branch --cov-fail-under=98
127
152
  ```
128
153
 
129
- 覆盖:RSA3072/4096 与 SM2 签名字节级断言、OAEP 包装/解包、AES-256-GCM 与 SM4-GCM
154
+ 覆盖:RSA2048/3072/4096 与 SM2 签名字节级断言、OAEP 包装/解包、AES-256-GCM 与 SM4-GCM
130
155
  密文字节级断言、SM3/SHA-256 摘要、DEK 载荷组装、digest 头全部格式规则;负向量含
131
156
  tamper / 跨族 / 63B、65B 签名 / 带 `=` 的 base64url / C1C2C3 旧国标顺序 /
132
- MGF1-SHA1 陷阱密文,全部必须拒绝。CI(3.9–3.14 矩阵)执行同一命令。
157
+ MGF1-SHA1 陷阱密文,全部必须拒绝。CI(3.9–3.14 × linux/macOS 矩阵)执行同一命令。
158
+
159
+ 另消费 `wop-specs` 组织级 interop 样本集(`tests/fixtures/interop-cases.json` 字节
160
+ 副本,sha256 哨兵钉死):build 方向按冻结输入复现 draft(RSA byte-exact;SM2 按
161
+ opaque 剥离签名/包装段),verify 方向 24 条冻结样本逐条对账明文与错误分类
162
+ (canonical class 映射表见 `tests/test_interop.py`)。
133
163
 
134
164
  ## 错误处理与模糊化
135
165
 
136
- - **明确**(公开协议知识,帮助集成自查):套件格式/跨族、密钥材料、digest 头格式与
137
- 不匹配、DEK alg 与套件族不符;
166
+ - **明确**(公开协议知识,帮助集成自查):套件格式/跨族、密钥材料、digest 头格式、
167
+ 缺失与不匹配(D2/I1 结构前置校验)、信封 JSON 形态与各 base64url 段(F7)、
168
+ DEK alg 与套件族不符;
138
169
  - **模糊**(依赖密钥参与,防 oracle,I7):签名验证失败、解密失败——对外消息不区分
139
- tag 失败 / 密钥不符等原因细节。
170
+ tag 失败 / 密钥不符等原因细节;DEK 载荷(解包后明文)结构畸形除 alg 跨族外一律
171
+ 归入解密失败(interop 合同 n13 / 故障注入手册 P3)。
172
+
173
+ ---
174
+
175
+ ## 🧩 WOP 生态导航 | Ecosystem
176
+
177
+ | 类别 | 组件 |
178
+ |------|------|
179
+ | 协议与向量真源 | [wop-specs](https://github.com/wop-platform/wop-specs) —— crypto-strategy-spec · wop-sdk-spec · 黄金测试向量 |
180
+ | 官方 SDK(六语言) | [Java](https://github.com/wop-platform/wop-java-sdk) · [Go](https://github.com/wop-platform/wop-go-sdk) · [Python](https://github.com/wop-platform/wop-python-sdk) · [PHP](https://github.com/wop-platform/wop-php-sdk) · [.NET](https://github.com/wop-platform/wop-dotnet-sdk) · [TypeScript](https://github.com/wop-platform/wop-typescript-sdk) |
181
+ | 浏览器工作台 | [wop-web-tools](https://github.com/wop-platform/wop-web-tools) —— 密钥生成 · 报文联调 · 国密 · 六语言代码片段 |
182
+ | Agent 技能包 | [wop-skills](https://github.com/wop-platform/wop-skills) —— 零代码调用 · 联调对拍 · 62 错误码排错 |
183
+ | 平台服务(企业内部) | 统一接入网关 · 核心逻辑服务 · 回调服务 · 开发者门户 · 文档中心 |
@@ -18,18 +18,31 @@ src/wop_sdk/signature.py
18
18
  src/wop_sdk/sm2crypto.py
19
19
  src/wop_sdk/sm4gcm.py
20
20
  src/wop_sdk/suites.py
21
+ src/wop_sdk/transport_discovery.py
22
+ src/wop_sdk/config/__init__.py
23
+ src/wop_sdk/config/_loader.py
24
+ src/wop_sdk/config/_models.py
25
+ src/wop_sdk/config/_parser.py
26
+ src/wop_sdk/config/_validator.py
27
+ src/wop_sdk/config/wopSdkConfig.json
21
28
  src/wop_sdk/transports/__init__.py
22
29
  src/wop_sdk/transports/httpx_transport.py
23
30
  src/wop_sdk/transports/requests_transport.py
24
31
  src/wop_sdk/transports/urllib_transport.py
32
+ tests/test_bdd.py
25
33
  tests/test_canonical.py
26
34
  tests/test_client.py
35
+ tests/test_config.py
36
+ tests/test_config_loading.py
27
37
  tests/test_coverage_gaps.py
28
38
  tests/test_digest.py
29
39
  tests/test_encoding.py
30
40
  tests/test_envelope.py
41
+ tests/test_interop.py
31
42
  tests/test_keys.py
43
+ tests/test_mutation_gaps.py
32
44
  tests/test_signature.py
45
+ tests/test_submchid.py
33
46
  tests/test_suites.py
34
47
  tests/test_transports.py
35
48
  tests/test_transports_real.py
@@ -3,8 +3,12 @@
3
3
 
4
4
  协议核心(签名/摘要/数字信封/验签解密,纯函数、零网络 IO)+ 可插拔 HTTP 适配层。
5
5
  """
6
+ from importlib.metadata import PackageNotFoundError, version as _dist_version
7
+
6
8
  from .client import RequestDraft, VerifyResult, WopClient, WopConfig
9
+ from .config import HttpClientSettings, WopSdkConfig, clear_cache, load, load_default
7
10
  from .errors import (
11
+ ConfigurationError,
8
12
  DecryptError,
9
13
  DekConsistencyError,
10
14
  DigestMismatchError,
@@ -13,27 +17,40 @@ from .errors import (
13
17
  SignatureVerifyError,
14
18
  SuiteParseError,
15
19
  UnsupportedSuiteError,
20
+ WopGatewayResponseError,
16
21
  WopSdkError,
17
22
  )
18
23
  from .suites import Suite, parse_suite
19
24
 
20
- __version__ = "0.1.1"
25
+ # 版本单一源:pyproject [project].version(经分发元数据读取),
26
+ # 未安装场景(纯源码树 import)兜底 0.0.0
27
+ try:
28
+ __version__ = _dist_version("wop-python-sdk")
29
+ except PackageNotFoundError: # pragma: no cover —— 无分发元数据时的兜底分支
30
+ __version__ = "0.0.0"
21
31
 
22
32
  __all__ = [
23
- "WopClient",
24
- "WopConfig",
33
+ "ConfigurationError",
34
+ "DecryptError",
35
+ "DekConsistencyError",
36
+ "DigestMismatchError",
37
+ "HttpClientSettings",
38
+ "KeyMaterialError",
39
+ "ProtocolFormatError",
25
40
  "RequestDraft",
26
- "VerifyResult",
41
+ "SignatureVerifyError",
27
42
  "Suite",
28
- "parse_suite",
29
- "WopSdkError",
30
43
  "SuiteParseError",
31
44
  "UnsupportedSuiteError",
32
- "ProtocolFormatError",
33
- "KeyMaterialError",
34
- "DigestMismatchError",
35
- "SignatureVerifyError",
36
- "DecryptError",
37
- "DekConsistencyError",
45
+ "VerifyResult",
46
+ "WopClient",
47
+ "WopConfig",
48
+ "WopGatewayResponseError",
49
+ "WopSdkConfig",
50
+ "WopSdkError",
38
51
  "__version__",
52
+ "clear_cache",
53
+ "load",
54
+ "load_default",
55
+ "parse_suite",
39
56
  ]
@@ -18,11 +18,12 @@ def canonical_headers(headers: Optional[Dict[str, str]]) -> str:
18
18
  名称 ASCII 升序,行间 '\\n' 连接,尾行不加 '\\n'。"""
19
19
  if not headers:
20
20
  return ""
21
- normalized = {}
22
- for name, value in headers.items():
23
- normalized[trimall(name).lower()] = trimall(value)
21
+ normalized = {
22
+ trimall(name).lower(): trimall(value)
23
+ for name, value in headers.items()
24
+ }
24
25
  return "\n".join(
25
- "%s:%s" % (java_urlencode(k), java_urlencode(normalized[k]))
26
+ f"{java_urlencode(k)}:{java_urlencode(normalized[k])}"
26
27
  for k in sorted(normalized)
27
28
  )
28
29