wop-python-sdk 0.1.0__py3-none-any.whl

wop_python_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: wop-python-sdk
+Version: 0.1.0
+Summary: WOP 商户侧官方 Python SDK：协议核心（签名/摘要/数字信封/验签解密）+ 可插拔 HTTP 适配层
+Author: wop-platform
+License: MIT
+Project-URL: Homepage, https://github.com/wop-platform/wop-python-sdk
+Keywords: wop,gateway,sm2,sm4-gcm,rsa,digital-envelope
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=41
+Requires-Dist: gmssl>=3.2.2
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.24; extra == "httpx"
+Provides-Extra: requests
+Requires-Dist: requests>=2.28; extra == "requests"
+Dynamic: license-file
+
+# WOP Python SDK
+
+WOP 网关商户侧官方 Python 客户端库：封装协议核心（套件解析 / 结构化签名 / 内容摘要 /
+L2 数字信封 / 验签解密）与可插拔 HTTP 适配层，使商户无需理解 canonicalRequest、
+算法套件推导与线上字节格式即可安全对接网关。
+
+- 协议真源：[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）
+- 向量真源：[crypto-vectors.json](https://github.com/wop-platform/wop-specs/blob/main/crypto/crypto-vectors.json)（本仓 fixture 为字节级副本，禁手改）
+- Python ≥ 3.9
+- 三套件全支持：`WOP-RSA3072-SHA256` / `WOP-RSA4096-SHA256` / `WOP-SM2-SM3`
+- 密码依赖（唯一指定路径）：`cryptography`（RSA/AES）+ `gmssl ≥ 3.2.2`（SM2/SM3/SM4）
+- 主包零额外依赖；HTTP 适配器以 peer 依赖交付（`wop-python-sdk[httpx]` / `wop-python-sdk[requests]`）
+
+## 快速开始
+
+```bash
+pip install wop-python-sdk            # 或从源码：pip install -e .
+pip install 'wop-python-sdk[httpx]'   # 可选：httpx peer 适配器（另含 requests extras）
+```
+
+```python
+from wop_sdk import WopClient, WopConfig
+from wop_sdk.transports import UrllibTransport, send_draft
+
+client = WopClient(WopConfig(
+    app_key="app_10012481831",
+    suite="WOP-RSA3072-SHA256",            # 或 WOP-RSA4096-SHA256 / WOP-SM2-SM3
+    merchant_private_key=MERCHANT_PRIV_PEM,  # 商户私钥（PEM 或 Base64 单行）
+    platform_public_key=PLATFORM_PUB_PEM,    # 平台公钥（PEM 或 Base64 单行）
+    gateway_base_url="https://wop.example.com",
+))
+
+# L0 明文请求
+draft = client.build_request("POST", "/gateway/order.create", {"orderId": 42})
+
+# 发送（任意 HTTP 栈；此处 stdlib urllib 适配器）
+resp = send_draft(UrllibTransport(), client._config.gateway_base_url, draft)
+
+# 校验平台响应（F6 固定顺序：验签 → digest 复核 → DEK 解包 → alg 族比对 → bulk 解密）
+result = client.verify_response(resp.headers, resp.body, "/gateway/order.create")
+if result.ok:
+    print(result.plaintext)
+else:
+    print(result.reason)  # 验签/解密失败对外模糊（I7），格式/完整性/一致性类明确
+```
+
+## 密钥准备
+
+密钥入参为字符串（PEM 或 Base64 单行），SDK 内部解析（D12 分发契约）：
+
+| 套件 | 商户私钥 | 平台公钥 | 约束 |
+|------|----------|----------|------|
+| `WOP-RSA3072-SHA256` | PKCS#8 DER，Base64/PEM | X.509 SPKI DER，Base64/PEM | 密钥必须 3072 位 |
+| `WOP-RSA4096-SHA256` | 同上 | 同上 | 密钥必须 4096 位 |
+| `WOP-SM2-SM3` | `d` 标量 32 字节，Base64 | 未压缩点 `04‖X‖Y` 65 字节，Base64 | 点必须在 sm2p256v1 曲线上（I5） |
+
+- RSA 公钥与私钥均接受 PEM 包装（`-----BEGIN PUBLIC KEY-----`）或裸 Base64；
+- SM2 材料喂给 RSA 套件（或反向）在配置期即拒绝；跨族算法组合（如 `WOP-RSA3072-SM3`）
+  在套件解析期拒绝。
+
+## L0 / L2 示例
+
+### L0（明文，摘要为唯一完整性防线）
+
+```python
+draft = client.build_request("POST", "/gateway/order.query", {"orderId": 42})
+# 有 body 必产 x-wop-content-digest 且必入 signedHeaders（D2/I1）；GET 无 body 则缺席
+```
+
+### L2（数字信封：AES-256-GCM / SM4-GCM 全文加密）
+
+```python
+draft = client.build_request("POST", "/gateway/order.create", {"card": "6222..."}, level="L2")
+# wire_body = {"encrypted":"<base64url(ciphertext||tag)>"}
+# x-wop-encrypt: L2;dek=<base64url(OAEP/SM2 包装的 DEK 载荷)>
+# DEK 与 IV 每次调用 CSPRNG 新生成（I4：同一密钥下 IV 永不复用）
+
+result = client.verify_response(resp.headers, resp.body, "/gateway/order.create")
+# result.plaintext = 解密后的业务报文
+
+# 回调校验（URI 取回调 path，方法恒 POST）
+cb = client.verify_callback(cb_headers, cb_body, "/callback/notify")
+```
+
+线上字节格式（F7/D9/D10）：全部 base64url **无填充**（严格拒收 `=`）；
+RSA 签名 = PKCS#1 v1.5；SM2 签名 = 裸 `r‖s` 64 字节（禁 DER）；
+SM2 密文 = `C1C3C2` 裸拼接（C1 = 未压缩点 65B）；RSA-OAEP = 显式双 SHA-256 + 空 label。
+
+## 向量自测
+
+黄金向量 fixture 位于 `tests/fixtures/crypto-vectors.json`（与网关真源字节级一致，
+禁手改）。本地复跑 conformance 套件：
+
+```bash
+pip install -e '.[httpx]' coverage
+python3 -m pytest --cov=wop_sdk --cov-branch --cov-fail-under=98
+```
+
+覆盖：RSA3072/4096 与 SM2 签名字节级断言、OAEP 包装/解包、AES-256-GCM 与 SM4-GCM
+密文字节级断言、SM3/SHA-256 摘要、DEK 载荷组装、digest 头全部格式规则；负向量含
+tamper / 跨族 / 63B、65B 签名 / 带 `=` 的 base64url / C1C2C3 旧国标顺序 /
+MGF1-SHA1 陷阱密文，全部必须拒绝。CI（3.9–3.14 矩阵）执行同一命令。
+
+## 错误处理与模糊化
+
+- **明确**（公开协议知识，帮助集成自查）：套件格式/跨族、密钥材料、digest 头格式与
+  不匹配、DEK alg 与套件族不符；
+- **模糊**（依赖密钥参与，防 oracle，I7）：签名验证失败、解密失败——对外消息不区分
+  tag 失败 / 密钥不符等原因细节。

wop_python_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+wop_python_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=9HPK_oKzyRh2oK3x0YiYrE1envRgKMfD1LWgGSStuW8,1069
+wop_sdk/__init__.py,sha256=TKAvYKNbLpjOzkmHpiAiXa6gPmWVE8vdYV165XNUeXM,905
+wop_sdk/canonical.py,sha256=LiWUctDCi71ZeHuTXLCWm_dlMXCxciJLPkgnTnIGM80,1508
+wop_sdk/client.py,sha256=BjISbQ7eIWjHrPcYGUdXafs5Ou4bLxx7a7jSIg8uFRI,10153
+wop_sdk/digest.py,sha256=hm7zXLTQsVsMlrdTw4o2G0HbJBb0dSeVvyl-OUp5dvk,2533
+wop_sdk/encoding.py,sha256=_xFhvErBtm9rwFS1nxLYQX0PriIDQibYmDqDJ9DFzMM,2505
+wop_sdk/envelope.py,sha256=yqSPsBW39As94xux6VsmhabfC2up6ZIyulmGoevqm7o,7241
+wop_sdk/errors.py,sha256=WQs_o-zNRNaxZoOQpPCO9oU47nZ6_2vbK5FJQw1n0AM,1690
+wop_sdk/keys.py,sha256=uEzcoydWFV20eSKCcUEWux_IuI3dCNFrkOD2S1PlzWQ,4343
+wop_sdk/signature.py,sha256=pasDfgPPhbbsDK-5_iG4n2bG5jCI-P8qjzykYCjevJg,2486
+wop_sdk/sm2crypto.py,sha256=IbZHsj8oRSy5sdktSGcYn7sagjngptungn5oS_vrZFQ,4695
+wop_sdk/sm4gcm.py,sha256=I5FViIfsyyFSsog7VYnkwRlTT_NNizFrMss6NRh5cjk,3247
+wop_sdk/suites.py,sha256=ipUumVrVmylvKMzX1JzewCC4bbKVS6btn_4VKp9oG5M,2960
+wop_sdk/transports/__init__.py,sha256=zArPclZXHvZsU73sZh_vMKp9FRp_GZVM4NWq6-J4tT8,1397
+wop_sdk/transports/httpx_transport.py,sha256=nDCCIiRmF2SjQy2Ele_TV9i93JFA3miIoTZhi2oXZLg,1188
+wop_sdk/transports/requests_transport.py,sha256=PBCfN1V6mJlXmcanvVdmSb-2vVv64bJjzgPXJ9fOq30,1212
+wop_sdk/transports/urllib_transport.py,sha256=2MSmKy-8LpV_emh87KOfTAkizy3UtuTE8pLxV-fDxkw,1040
+wop_python_sdk-0.1.0.dist-info/METADATA,sha256=rKrnIkixRxjnFP4h3CrS54QBDrAmzpqSJRwyxby7esM,6484
+wop_python_sdk-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+wop_python_sdk-0.1.0.dist-info/top_level.txt,sha256=TotiKMyRTEgc7yV8T6-Hwjl9NdddNjoBY3miEEKSEyY,8
+wop_python_sdk-0.1.0.dist-info/RECORD,,

wop_python_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

wop_python_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wop-platform
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wop_python_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+wop_sdk

wop_sdk/__init__.py

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+"""WOP 商户侧官方 Python SDK。
+
+协议核心（签名/摘要/数字信封/验签解密，纯函数、零网络 IO）+ 可插拔 HTTP 适配层。
+"""
+from .client import RequestDraft, VerifyResult, WopClient, WopConfig
+from .errors import (
+    DecryptError,
+    DekConsistencyError,
+    DigestMismatchError,
+    KeyMaterialError,
+    ProtocolFormatError,
+    SignatureVerifyError,
+    SuiteParseError,
+    UnsupportedSuiteError,
+    WopSdkError,
+)
+from .suites import Suite, parse_suite
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "WopClient",
+    "WopConfig",
+    "RequestDraft",
+    "VerifyResult",
+    "Suite",
+    "parse_suite",
+    "WopSdkError",
+    "SuiteParseError",
+    "UnsupportedSuiteError",
+    "ProtocolFormatError",
+    "KeyMaterialError",
+    "DigestMismatchError",
+    "SignatureVerifyError",
+    "DecryptError",
+    "DekConsistencyError",
+    "__version__",
+]

wop_sdk/canonical.py

@@ -0,0 +1,47 @@
+# -*- coding: utf-8 -*-
+"""canonicalRequest 构造（F2）。
+
+结构（5 段 '\\n' 连接，对照网关 CanonicalRequestBuilder）：
+
+    authString\\nHTTPMethod\\ncanonicalURI\\ncanonicalQueryString\\ncanonicalHeaders
+
+POST 的 canonicalQueryString 为空字符串（分隔空行不可省略）；
+header 值编码 = Java URLEncoder 语义（空格 → %20）。
+"""
+from typing import Dict, Optional
+
+from .encoding import java_urlencode, trimall
+
+
+def canonical_headers(headers: Optional[Dict[str, str]]) -> str:
+    """规范标头：名称 lowercase+trimall+urlencode，值 trimall+urlencode，
+    名称 ASCII 升序，行间 '\\n' 连接，尾行不加 '\\n'。"""
+    if not headers:
+        return ""
+    normalized = {}
+    for name, value in headers.items():
+        normalized[trimall(name).lower()] = trimall(value)
+    return "\n".join(
+        "%s:%s" % (java_urlencode(k), java_urlencode(normalized[k]))
+        for k in sorted(normalized)
+    )
+
+
+def build_canonical(
+    auth_string: Optional[str],
+    method: Optional[str],
+    canonical_uri: Optional[str],
+    query_string: Optional[str],
+    canonical_headers: Optional[str],
+) -> str:
+    """组装规范请求（5 段）；None 段落输出空串，保持 5 段结构。"""
+    safe_method = (method or "").strip().upper()
+    return "\n".join(
+        [
+            auth_string or "",
+            safe_method,
+            canonical_uri or "",
+            query_string or "",
+            canonical_headers or "",
+        ]
+    )

wop_sdk/client.py

@@ -0,0 +1,258 @@
+# -*- coding: utf-8 -*-
+"""WopClient：协议核心编排（spec §2 概念 API 的 Python 映射）。
+
+- build_request：组装协议头 + 签名 + 可选 L2 信封 → RequestDraft（零网络 IO）；
+- verify_response / verify_callback：F6 固定顺序（验签 → digest 复核 → DEK 解包 →
+  alg 族比对 → bulk 解密），失败统一 VerifyResult(ok=False, reason)，
+  验签/解密类 reason 模糊（I7），格式/完整性/一致性类 reason 明确（10.2）。
+"""
+import json
+import os
+import time
+from dataclasses import dataclass
+from typing import Callable, Dict, Optional
+
+from .canonical import build_canonical, canonical_headers
+from .digest import build_digest_header, verify_digest_header
+from .encoding import b64url_encode
+from .envelope import open_l2, seal_l2
+from .errors import (
+    DecryptError,
+    DekConsistencyError,
+    DigestMismatchError,
+    ProtocolFormatError,
+    SignatureVerifyError,
+    SuiteParseError,
+    UnsupportedSuiteError,
+    WopSdkError,
+)
+from .keys import (
+    load_rsa_private_key,
+    load_rsa_public_key,
+    load_sm2_private_key,
+    load_sm2_public_key,
+)
+from .signature import sign, verify
+from .sm2crypto import Sm2Ops, sm2_derive_public_hex
+from .suites import Suite, parse_suite
+
+Csprng = Callable[[int], bytes]
+
+_LEVELS = ("L0", "L2")
+_DEK_PREFIX = "L2;dek="
+
+
+def _now_ms() -> int:
+    """毫秒时间戳（F9）；独立函数便于测试冻结。"""
+    return int(time.time() * 1000)
+
+
+@dataclass(frozen=True)
+class WopConfig:
+    """商户接入配置（密钥为材料串：PEM 或 Base64 单行，D12）。"""
+
+    app_key: str
+    suite: str
+    merchant_private_key: str
+    platform_public_key: str
+    gateway_base_url: Optional[str] = None
+
+
+@dataclass
+class RequestDraft:
+    """出向请求草稿：headers + wireBody，商户可直接交给任意 HTTP 栈。"""
+
+    method: str
+    path: str
+    headers: Dict[str, str]
+    wire_body: Optional[bytes]
+    level: str
+
+
+@dataclass
+class VerifyResult:
+    """响应/回调校验结果；reason 对验签/解密类模糊（I7）。"""
+
+    ok: bool
+    plaintext: Optional[bytes] = None
+    reason: Optional[str] = None
+
+
+class WopClient:
+    """协议核心客户端（纯函数式产出，无连接状态）。"""
+
+    def __init__(self, config: WopConfig, csprng: Csprng = os.urandom):
+        if not config.app_key or not config.app_key.strip():
+            raise WopSdkError("appKey 不能为空")
+        self._config = config
+        self._suite = parse_suite(config.suite)
+        if self._suite.family == "RSA":
+            self._signer = load_rsa_private_key(
+                config.merchant_private_key, self._suite.key_bits
+            )
+            self._wrap_pub = load_rsa_public_key(
+                config.platform_public_key, self._suite.key_bits
+            )
+        else:
+            d = load_sm2_private_key(config.merchant_private_key)
+            merchant_pub_hex = sm2_derive_public_hex(d.hex())
+            self._signer = Sm2Ops(private_key_hex=d.hex(), public_xy_hex=merchant_pub_hex)
+            platform_pub = load_sm2_public_key(config.platform_public_key)
+            self._wrap_pub = Sm2Ops(public_xy_hex=platform_pub.xy_hex)
+        self._csprng = csprng
+
+    @property
+    def suite(self) -> Suite:
+        return self._suite
+
+    # ---------- 出向 ----------
+
+    def build_request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[object] = None,
+        *,
+        level: str = "L0",
+        query_string: str = "",
+        expired_seconds: int = 1800,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> RequestDraft:
+        """构造请求（F9）：协议头组装 → L2 可选封装 → canonicalRequest → 签名。"""
+        if level not in _LEVELS:
+            raise ValueError("level 必须为 L0 或 L2，实际 %r" % level)
+        safe_method = method.strip().upper()
+        wire: Optional[bytes] = None
+        encrypt_header: Optional[str] = None
+        if level == "L2":
+            wire, encrypt_header = seal_l2(
+                self._suite, self._wrap_pub, self._normalize_body(body), self._csprng
+            )
+        elif body is not None:
+            wire = self._normalize_body(body)
+
+        headers: Dict[str, str] = {
+            "x-wop-appkey": self._config.app_key,
+            "x-wop-timestamp": str(_now_ms()),
+            "x-wop-nonce": self._csprng(16).hex(),  # F9：CSPRNG nonce
+        }
+        if wire is not None:
+            # D2：有 body 必产 digest；I1：digest 必入 signedHeaders（下方签名集合即全部头）
+            headers["x-wop-content-digest"] = build_digest_header(self._suite, wire)
+        if encrypt_header is not None:
+            headers["x-wop-encrypt"] = encrypt_header
+
+        app_headers: Dict[str, str] = {}
+        for name, value in (extra_headers or {}).items():
+            low = name.strip().lower()
+            if low.startswith("x-wop-"):
+                headers[low] = str(value).strip()
+            else:
+                app_headers[low] = str(value).strip()
+
+        auth = "v1/%d" % int(expired_seconds)
+        canonical = build_canonical(
+            auth, safe_method, path, query_string or "", canonical_headers(headers)
+        )
+        sig = sign(self._suite, self._signer, canonical.encode("utf-8"), csprng=self._csprng)
+        headers["x-wop-sign"] = "%s %s/%s/%s" % (
+            self._suite.security_req,
+            auth,
+            ";".join(sorted(k for k in headers)),
+            b64url_encode(sig),
+        )
+        out: Dict[str, str] = dict(headers)
+        if wire is not None:
+            out.setdefault("content-type", "application/json")
+        out.update(app_headers)
+        return RequestDraft(safe_method, path, out, wire, level)
+
+    @staticmethod
+    def _normalize_body(body: Optional[object]) -> bytes:
+        if body is None:
+            raise ValueError("L2 封装需要明文 body")
+        if isinstance(body, bytes):
+            return body
+        if isinstance(body, str):
+            return body.encode("utf-8")
+        if isinstance(body, dict):
+            return json.dumps(body, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+        raise TypeError("body 仅接受 bytes/str/dict，实际 %r" % type(body).__name__)
+
+    # ---------- 入向 ----------
+
+    def verify_response(
+        self,
+        headers: Dict[str, str],
+        body: bytes,
+        path: str,
+        method: str = "POST",
+        query_string: str = "",
+    ) -> VerifyResult:
+        """校验平台响应（F6 顺序固定）。path/query_string = 触发本次请求的 URI。"""
+        lower = {str(k).lower().strip(): str(v).strip() for k, v in (headers or {}).items()}
+        try:
+            return self._verify_flow(lower, body, path, method.upper(), query_string or "")
+        except (SignatureVerifyError, DecryptError, ProtocolFormatError, DigestMismatchError,
+                DekConsistencyError, UnsupportedSuiteError, SuiteParseError) as exc:
+            return VerifyResult(ok=False, reason=str(exc))
+
+    def verify_callback(
+        self, headers: Dict[str, str], body: bytes, callback_path: str
+    ) -> VerifyResult:
+        """校验平台回调（URI 取回调 path，方法恒 POST）。"""
+        return self.verify_response(headers, body, callback_path, method="POST")
+
+    def _verify_flow(
+        self, lower: Dict[str, str], body: bytes, path: str, method: str, query_string: str
+    ) -> VerifyResult:
+        sign_header = lower.get("x-wop-sign")
+        if not sign_header:
+            raise ProtocolFormatError("x-wop-sign 头缺席")
+        suite_part, sep, rest = sign_header.partition(" ")
+        if not suite_part or not sep or not rest:
+            raise ProtocolFormatError("x-wop-sign 应为 '<securityReq> <authString>/<signedHeaders>/<signature>'")
+        segs = rest.split("/")
+        if len(segs) != 4:
+            raise ProtocolFormatError(
+                "x-wop-sign 应为 <protocolVersion>/<expiredSeconds>/<signedHeaders>/<signature> 四段"
+            )
+        version, _expired, signed_names, sig_b64u = segs
+        if version != "v1":
+            raise ProtocolFormatError("不支持的协议版本：%r" % version)
+        req_suite = parse_suite(suite_part)  # 解析类/支持类错误明确
+        if req_suite.security_req != self._suite.security_req:
+            raise UnsupportedSuiteError(
+                "响应声明套件 %s 与商户配置 %s 不符" % (suite_part, self._suite.security_req)
+            )
+        sig = _strict_decode_signature(sig_b64u)
+        auth = "%s/%s" % (version, _expired)
+        signed: Dict[str, str] = {}
+        for name in signed_names.split(";"):
+            if name not in lower:
+                raise ProtocolFormatError("签名声明的头在响应中缺席：%s" % name)
+            signed[name] = lower[name]
+        canonical = build_canonical(auth, method, path, query_string, canonical_headers(signed))
+        # F6 ①先验签（I2：先验签后解密）
+        verify(req_suite, self._wrap_pub, canonical.encode("utf-8"), sig)
+        # F6 ②digest 复核（D2：有 body 必传；对象 = wire 原始字节）
+        if body:
+            verify_digest_header(self._suite, lower.get("x-wop-content-digest"), body)
+        enc = lower.get("x-wop-encrypt")
+        if enc is None:
+            return VerifyResult(ok=True, plaintext=body)  # L0
+        # F6 ③④⑤ DEK 解包 → alg 族比对 → bulk 解密（envelope.open_l2 内序）
+        if not enc.startswith(_DEK_PREFIX):
+            raise ProtocolFormatError("x-wop-encrypt 头格式错误：应为 %s<base64url>" % _DEK_PREFIX)
+        plaintext = open_l2(self._suite, self._signer, body, enc[len(_DEK_PREFIX):])
+        return VerifyResult(ok=True, plaintext=plaintext)
+
+
+def _strict_decode_signature(sig_b64u: str) -> bytes:
+    """签名严格解码（F7：拒 '=' / 字母表外字符）；失败归解析类。"""
+    from .encoding import b64url_decode
+
+    try:
+        return b64url_decode(sig_b64u)
+    except ValueError as exc:
+        raise ProtocolFormatError("签名编码非法：%s" % exc) from exc

wop_sdk/digest.py

@@ -0,0 +1,64 @@
+# -*- coding: utf-8 -*-
+"""请求体摘要（D2/F4）：`x-wop-content-digest: <alg> <小写hex>`。
+
+- 恰好一个半角空格，多余空白拒绝而非容忍；
+- hex 统一小写、固定 64 字符；
+- 标签与套件族强耦合（I5）：sha-256 仅 RSA 族、sm3 仅 SM 族；
+- 摘要对象 = wire 原始报文字节；无 body（GET）则 header 缺席。
+"""
+import hashlib
+import re
+from typing import Optional
+
+from gmssl import sm3 as _sm3
+
+from .errors import DigestMismatchError, ProtocolFormatError, UnsupportedSuiteError
+from .suites import Suite
+
+_HEX64 = re.compile(r"^[0-9a-f]{64}$")
+
+
+def compute_digest(suite: Suite, data: bytes) -> bytes:
+    """按套件族计算摘要（SHA-256 / SM3）。"""
+    if suite.family == "RSA":
+        return hashlib.sha256(data).digest()
+    return bytes.fromhex(_sm3.sm3_hash(list(data)))
+
+
+def build_digest_header(suite: Suite, body: bytes) -> str:
+    """组装 `<alg> <小写hex>`（恰一空格）。"""
+    return "%s %s" % (suite.digest_tag, compute_digest(suite, body).hex())
+
+
+def check_digest_header(suite: Suite, value: Optional[str]) -> str:
+    """格式层校验，通过返回 hex 值。
+
+    拒绝：非两段/恰一空格不满足、未知标签、跨族标签（I5）、非小写 hex、长度 ≠ 64。
+    """
+    if value is None:
+        raise ProtocolFormatError("digest 头缺席")
+    parts = value.split(" ")
+    if len(parts) != 2:
+        raise ProtocolFormatError(
+            "digest 头格式错误：必须为 '<alg> <hex>' 恰一空格，实际 %r" % value
+        )
+    tag, hex_value = parts
+    expected_tag = suite.digest_tag
+    if tag != expected_tag:
+        # I5：标签与套件族强耦合（sha-256 仅 RSA 族、sm3 仅 SM 族）
+        if tag in ("sha-256", "sm3"):
+            raise UnsupportedSuiteError(
+                "digest 标签 %s 与套件族 %s 不符（跨族拒绝）" % (tag, suite.family)
+            )
+        raise ProtocolFormatError("digest 标签未知：%r" % tag)
+    if not _HEX64.match(hex_value):
+        raise ProtocolFormatError("digest 值必须为 64 字符小写 hex，实际 %r" % hex_value)
+    return hex_value
+
+
+def verify_digest_header(suite: Suite, value: Optional[str], body: bytes) -> None:
+    """格式 + 值双层校验（F6 第 2 步 digest 复核）。不匹配抛完整性类错误（明确）。"""
+    expected = check_digest_header(suite, value)
+    actual = compute_digest(suite, body).hex()
+    if expected != actual:
+        raise DigestMismatchError("内容摘要不匹配")

wop_sdk/encoding.py

@@ -0,0 +1,74 @@
+# -*- coding: utf-8 -*-
+"""线上编码工具：base64url 严格无填充（F7/D10）、小写 hex（F5）、Java URLEncoder 语义（F2）。
+
+严格模式参照 crypto-strategy-spec §3.4：服务端拒收带 '=' 的输入；
+canonicalRequest 的 header 值编码语义对照网关 CanonicalRequestBuilder（Java）。
+"""
+import base64
+import re
+from typing import Optional
+
+_B64URL_ALPHABET = re.compile(r"^[A-Za-z0-9_-]+$")
+
+# Java URLEncoder 的保留集：字母数字与 . - * _（空格单独处理为 %20）
+_SAFE_CHARS = frozenset(
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._*-"
+)
+
+
+def b64url_encode(data: bytes) -> str:
+    """字节 → base64url 无填充字符串。"""
+    return base64.urlsafe_b64encode(data).decode("ascii").rstrip("=")
+
+
+def b64url_decode(text: str) -> bytes:
+    """base64url 无填充字符串 → 字节。
+
+    严格模式（F7/D10）：
+    - 拒绝空串；
+    - 拒绝 '=' 填充字符；
+    - 拒绝字母表外字符（含 '+' '/' 空白等）；
+    - 拒绝长度 % 4 == 1（不可能的 base64 长度）。
+    """
+    if not text:
+        raise ValueError("base64url 输入为空")
+    if "=" in text:
+        raise ValueError("base64url 严格模式：拒绝 '=' 填充")
+    if not _B64URL_ALPHABET.match(text):
+        raise ValueError("base64url 字母表外字符")
+    if len(text) % 4 == 1:
+        raise ValueError("base64url 长度非法（% 4 == 1）")
+    return base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))
+
+
+def hex_lower(data: bytes) -> str:
+    """字节 → 小写 hex（F5/D10）。"""
+    return data.hex()
+
+
+def java_urlencode(text: Optional[str]) -> str:
+    """Java URLEncoder.encode(text, UTF-8) 语义（F2）。
+
+    - 保留集：字母数字与 . - * _；
+    - 空格 → %20（Java 输出 '+' 后替换，等价结果）；
+    - 其余字符按 UTF-8 字节逐字节 %XX（大写十六进制）；
+    - None / 空串 → ""。
+    """
+    if text is None or text == "":
+        return ""
+    out = []
+    for ch in text:
+        if ch in _SAFE_CHARS:
+            out.append(ch)
+        elif ch == " ":
+            out.append("%20")
+        else:
+            out.append("".join("%%%02X" % b for b in ch.encode("utf-8")))
+    return "".join(out)
+
+
+def trimall(text: Optional[str]) -> str:
+    """去首尾空白，连续空白折叠为单个空格（F2，对照 CanonicalRequestBuilder.trimall）。"""
+    if text is None:
+        return ""
+    return re.sub(r"\s+", " ", text.strip())