tcaicc 1.4.0__py3-none-any.whl

tcaicc/__init__.py

@@ -0,0 +1,121 @@
+__version__ = "1.4.0"
+
+from .common.cipherx import (
+    ChunkDecryptor,
+    ChunkEncryptor,
+    CipherType,
+    CipherTypeError,
+    CipherxError,
+    DecryptError,
+    Envelope,
+    FormatError,
+    HashMismatchError,
+    KeySizeError,
+    Metadata,
+    StreamClosedError,
+    StreamVerifyError,
+    TooLargeError,
+    compute_prefix,
+    encrypt_prompt,
+    encrypt_response,
+    parse,
+)
+from .common.cryptox import (
+    CryptoxError,
+    DecryptError as CryptoxDecryptError,
+    HybridEphemeral,
+    HybridShare,
+    constant_time_equal,
+    derive_dek,
+    encode_lp,
+    hkdf_expand,
+    hkdf_extract,
+    hmac_sha256,
+    open_,
+    open_base64,
+    random_nonce,
+    respond_hybrid_exchange,
+    seal,
+    seal_base64,
+    zero,
+)
+from .common.security import (
+    ENDPOINT_NOT_FOUND,
+    FLAG_PROMPT_LONG,
+    FLAG_PROMPT_SHORT,
+    NO_ENDPOINT,
+    TLS_INSECURE,
+    TLS_NONE,
+    TLS_TLS,
+    ClosedError,
+    CreateResult,
+    CryptoError,
+    DeriveResult,
+    EncodingError,
+    EndpointNotFoundError,
+    EndpointPool,
+    HttpClient,
+    HttpTransportResponse,
+    ImportResult,
+    InsecureTLSWarning,
+    KeyGeneratorError,
+    KeySizeError as CryptoKeySizeError,
+    Logger,
+    LogLevel,
+    ModelPool,
+    NoEndpointError,
+    Policy,
+    Protocol,
+    Request,
+    SecuritySession,
+    SecuritySessionError,
+    SessionFactory,
+    SessionIDError,
+    SessionPool,
+    StreamDecryptor,
+    TimeoutException,
+    TlsMode,
+    Transport,
+    TransportError,
+    TransportRequest,
+    TransportResponse,
+    binding_key,
+    build_ssl_context,
+    default_policy,
+    describe_endpoints,
+    detect_envelope,
+    set_log_level,
+    set_logger,
+)
+
+__all__ = [
+    "__version__",
+    # cryptox(低层原语)
+    "CryptoxError", "CryptoxDecryptError", "HybridEphemeral", "HybridShare",
+    "constant_time_equal", "derive_dek", "encode_lp", "hkdf_expand", "hkdf_extract",
+    "hmac_sha256", "open_", "open_base64", "random_nonce",
+    "respond_hybrid_exchange", "seal", "seal_base64", "zero",
+    # cipherx(信封格式)
+    "CipherxError", "KeySizeError", "FormatError", "TooLargeError", "DecryptError",
+    "HashMismatchError", "CipherTypeError", "StreamClosedError", "StreamVerifyError",
+    "encrypt_prompt", "encrypt_response", "parse",
+    "ChunkEncryptor", "ChunkDecryptor", "Envelope", "Metadata", "CipherType",
+    "compute_prefix",
+    # 数据面加解密客户端
+    "CryptoError", "CryptoKeySizeError", "SessionIDError", "ClosedError", "EncodingError",
+    "Request", "StreamDecryptor", "detect_envelope",
+    "Policy", "Protocol", "default_policy",
+    # 传输(TLS 形态由 base_url scheme 决定,无 mTLS)
+    "HttpClient", "TransportResponse", "TransportRequest", "Transport",
+    "HttpTransportResponse", "InsecureTLSWarning", "build_ssl_context", "TlsMode",
+    "TLS_TLS", "TLS_INSECURE", "TLS_NONE",
+    # 安全会话
+    "SessionFactory", "SessionPool", "SecuritySession",
+    "EndpointPool", "ModelPool", "describe_endpoints", "binding_key",
+    "FLAG_PROMPT_SHORT", "FLAG_PROMPT_LONG",
+    "EndpointNotFoundError", "NoEndpointError", "ENDPOINT_NOT_FOUND", "NO_ENDPOINT",
+    "CreateResult", "ImportResult", "DeriveResult",
+    "SecuritySessionError", "TransportError", "TimeoutException", "KeyGeneratorError",
+    # 进程级日志(四级阈值,默认 error 即零输出)
+    "set_logger", "set_log_level", "LogLevel", "Logger",
+]

tcaicc/common/__init__.py

@@ -0,0 +1 @@
+"""common 共享子包。"""

tcaicc/common/cipherx/__init__.py

@@ -0,0 +1,151 @@
+"""cipherx —— LLM prompt/response/流式 chunk 的 Envelope 密文格式。
+
+逐字节移植 ``aicc-common/cipherx``(wire 规范权威,配套设计
+``docs/superpowers/specs/2026-08-06-cipherx-envelope-design.md``)。
+**wire 变更须与 Go 端同步并重冻 KAT**(见 ``_kat``)。
+
+Wire 布局(自尾部解析)::
+
+    prompt     = [Prefix][Ciphertext][Hash][Metadata][Suffix]
+    response   = [Ciphertext][Metadata][Suffix]
+    chunk 中间 = [Ciphertext][Metadata][Suffix]   (Metadata 仅 fp/fs/pl)
+    chunk 尾   = [Ciphertext][Metadata][Suffix]   (Flags.IsFinal=1)
+
+Suffix 10B = Magic "AICCv1"(6B) ‖ CipherType(1B: 1=prompt 2=response 3=chunk) ‖
+Flags(1B: bit0 HasPrefix, bit1 HasCiphertext, bit2 HasHash, bit3 HasMetadata,
+bit4 HasSuffix, bit5 IsFinal) ‖ MetadataLength(2B 大端)。
+Ciphertext = GCM nonce(12B) ‖ AES-256-GCM 密文(含 16B tag);prompt / response 的 GCM 明文是内层
+BE32(n) ‖ 真实数据 ‖ 随机填充(长取 1.5 倍几何桶,256 起共 27 桶、顶桶 9,695,112;pl = 桶长,
+Parse 核 pl ∈ 桶表;chunk 不填充、pl 为真实长;spec 2026-10-08);
+Hash = HMAC-SHA256("TCAICC", SHA-256(真实数据)) 32B;Metadata = UTF-8 JSON(短 key,
+除 ``pl`` 外全可选;明文可读、AAD 保完整性、不承诺机密性)。
+
+AAD(绑定除 Ciphertext 外的全部组件)::
+
+    非流式: AAD = Prefix ‖ Hash ‖ Metadata ‖ Suffix     (缺失组件为空串)
+    chunk : AAD = LP(request_id) ‖ Metadata ‖ Suffix    (request_id 隐式,两端各自持有)
+
+流式:一条流一把独立 key;中间片 Metadata 仅位置,尾片带完整绑定与
+stream_hash(hex(SHA256(全流明文,含尾片)))收尾校验;乱序/丢包/重放因 AAD 或
+位置比对失败,传输 EOF 时 ``finished`` 为 False 即截断。聚合流(``aggregated=True``)
+专供"流式密文被中间层拼回非流式字段"的场景:尾片不比 stream_hash。
+
+密钥为 32 字节(通常是安全会话派生的 request_dek/response_dek:prompt 用
+request_dek,response 与 chunk 用 response_dek)。本库不做 IO 与密钥管理。
+非流式函数并发安全;``ChunkEncryptor``/``ChunkDecryptor`` 非并发安全。
+
+公开面镜像 Go cipherx 包:``encrypt_prompt``/``encrypt_response``/``decrypt``/``parse``、
+``ChunkEncryptor``/``ChunkDecryptor``、``compute_prefix``;Go 的 ``With*`` Option
+用关键字参数(``session_id``/``nonce``/``token``/``encrypt_time``/``key_id``)表达。
+"""
+from __future__ import annotations
+
+from ._aead import open_with_aad, seal_with_aad
+from ._binding import (
+    Binding,
+    FieldPathAliases,
+    Mismatch,
+    Mode,
+    Position,
+    Protocol,
+    mode_string,
+    mode_valid,
+    protocol_string,
+    protocol_valid,
+    validate_field_path,
+    validate_field_path_aliases,
+)
+from ._constants import (
+    GCM_NONCE_SIZE,
+    GCM_TAG_SIZE,
+    HASH_SIZE,
+    KEY_SIZE,
+    MAGIC,
+    MAX_ENVELOPE,
+    MAX_METADATA_LEN,
+    MAX_PLAINTEXT,
+    MAX_PREFIX_LEN,
+    MIN_CIPHERTEXT,
+    SUFFIX_SIZE,
+)
+from ._decrypt import decrypt_prompt, decrypt_response
+from ._encrypt import encrypt_prompt, encrypt_response
+from ._envelope import (
+    FLAG_CIPHERTEXT,
+    FLAG_FINAL,
+    FLAG_HASH,
+    FLAG_METADATA,
+    FLAG_PREFIX,
+    FLAG_SUFFIX,
+    FLAGS_CHUNK_FINAL,
+    FLAGS_CHUNK_MID,
+    FLAGS_PROMPT,
+    FLAGS_RESPONSE,
+    CipherType,
+    Envelope,
+    assemble,
+    build_suffix,
+    chunk_aad,
+    has_hash,
+    is_final,
+    non_stream_aad,
+    parse,
+    parse_envelope,
+    split_stream,
+    type_label,
+    valid_flags,
+)
+from ._errors import (
+    BindingError,
+    BindingMismatchError,
+    CipherTypeError,
+    CipherxError,
+    DecryptError,
+    FormatError,
+    HashMismatchError,
+    KeySizeError,
+    RequestIdError,
+    RequestMismatchError,
+    StreamClosedError,
+    StreamVerifyError,
+    TooLargeError,
+)
+from ._hash import PROMPT_HASH_KEY, prompt_hash
+from ._metadata import Metadata, decode_metadata, encode_metadata
+from ._padding import MAX_PADDED_PLAINTEXT_LEN, padded_len
+from ._prefix import compute_prefix
+from ._requestid import MAX_REQUEST_ID_LEN, validate_request_id
+from ._stream import ChunkDecryptor, ChunkEncryptor
+
+__all__ = [
+    # 加解密入口
+    "encrypt_prompt", "encrypt_response", "decrypt_prompt", "decrypt_response", "parse",
+    "ChunkEncryptor", "ChunkDecryptor", "compute_prefix", "prompt_hash", "PROMPT_HASH_KEY",
+    # 类型
+    "Envelope", "Metadata", "CipherType",
+    # 绑定上下文
+    "Protocol", "Mode", "Binding", "Position", "Mismatch",
+    "protocol_valid", "protocol_string", "mode_valid", "mode_string",
+    "validate_field_path", "validate_field_path_aliases", "FieldPathAliases",
+    "validate_request_id", "MAX_REQUEST_ID_LEN",
+    # 常量
+    "MAGIC", "SUFFIX_SIZE", "GCM_NONCE_SIZE", "GCM_TAG_SIZE", "MIN_CIPHERTEXT",
+    "HASH_SIZE", "KEY_SIZE", "MAX_PLAINTEXT", "MAX_ENVELOPE", "MAX_METADATA_LEN",
+    "MAX_PREFIX_LEN", "MAX_PADDED_PLAINTEXT_LEN",
+    # 内层填充
+    "padded_len",
+    # flags
+    "FLAG_PREFIX", "FLAG_CIPHERTEXT", "FLAG_HASH", "FLAG_METADATA", "FLAG_SUFFIX",
+    "FLAG_FINAL", "FLAGS_PROMPT", "FLAGS_RESPONSE", "FLAGS_CHUNK_MID", "FLAGS_CHUNK_FINAL",
+    # wire 组装/解析(高级用法)
+    "build_suffix", "assemble", "non_stream_aad", "chunk_aad",
+    "parse_envelope", "split_stream", "valid_flags", "type_label", "has_hash", "is_final",
+    # metadata
+    "encode_metadata", "decode_metadata",
+    # AEAD 低层(高级用法)
+    "seal_with_aad", "open_with_aad",
+    # 错误
+    "CipherxError", "KeySizeError", "FormatError", "TooLargeError", "DecryptError",
+    "HashMismatchError", "CipherTypeError", "StreamClosedError", "StreamVerifyError",
+    "RequestIdError", "RequestMismatchError", "BindingError", "BindingMismatchError",
+]

tcaicc/common/cipherx/_aead.py

@@ -0,0 +1,43 @@
+"""AES-256-GCM 封解:随机 12B nonce 前置,AAD 由调用层传入(绑定信封其余组件)。
+
+镜像 aicc-common/cipherx/aead.go。``_rand_read`` 是 KAT 测试缝(默认 ``os.urandom``);
+生产路径每封一随机 nonce。认证失败统一 ``DecryptError``,不细分原因。
+"""
+from __future__ import annotations
+
+import os
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from ._constants import GCM_NONCE_SIZE, KEY_SIZE, MIN_CIPHERTEXT
+from ._errors import DecryptError, KeySizeError
+
+# KAT 测试缝:替换为确定性字节流,使信封字节可复现(Go randRead 同义)。生产恒为 os.urandom。
+_rand_read = os.urandom
+
+
+def _new_gcm(key: bytes) -> AESGCM:
+    if len(key) != KEY_SIZE:
+        raise KeySizeError(len(key), KEY_SIZE)
+    return AESGCM(key)
+
+
+def seal_with_aad(key: bytes, plaintext: bytes, aad: bytes) -> bytes:
+    """加密:返回 ``nonce(12)‖GCM 密文+tag``,AAD 绑定信封其余组件。"""
+    gcm = _new_gcm(key)
+    nonce = _rand_read(GCM_NONCE_SIZE)
+    ct = gcm.encrypt(nonce, plaintext, aad)  # ct = 密文 ‖ 16B tag
+    return nonce + ct
+
+
+def open_with_aad(key: bytes, sealed: bytes, aad: bytes) -> bytes:
+    """解密:``sealed = nonce(12)‖密文+tag``;认证失败统一 DecryptError(防 oracle)。"""
+    gcm = _new_gcm(key)
+    if len(sealed) < MIN_CIPHERTEXT:
+        raise DecryptError()
+    nonce = sealed[:GCM_NONCE_SIZE]
+    ct = sealed[GCM_NONCE_SIZE:]
+    try:
+        return gcm.decrypt(nonce, ct, aad)
+    except Exception:
+        raise DecryptError() from None

tcaicc/common/cipherx/_binding.py

@@ -0,0 +1,208 @@
+"""绑定上下文:协议 / 模式枚举、字段位置、入参校验、Simple 归一化与解密侧比对原语
+(镜像 aicc-common/cipherx/binding.go,规范 spec 2026-09-14 §3.1 / §3.6 / §4.2)。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import IntEnum
+
+from ._errors import BindingError, BindingMismatchError, FormatError
+from ._metadata import Metadata
+from ._requestid import validate_request_id
+
+
+class Protocol(IntEnum):
+    """密文所属的 LLM 协议;int 上 wire,0 保留为"未设置"。"""
+
+    OPENAI_CHAT_COMPLETIONS = 1
+    OPENAI_RESPONSES = 2
+    ANTHROPIC_MESSAGES = 3
+
+
+class Mode(IntEnum):
+    """位置校验模式;int 上 wire,0 保留为"未设置"。"""
+
+    STRICT = 1  # 位置 / 协议对不上即拒
+    COMPATIBLE = 2  # 对不上记 mismatches 后照解
+    SIMPLE = 3  # 不做位置绑定:field_path 恒空、field_seq 恒 0;协议仍记
+
+
+def protocol_valid(p: int) -> bool:
+    return Protocol.OPENAI_CHAT_COMPLETIONS <= p <= Protocol.ANTHROPIC_MESSAGES
+
+
+def protocol_string(p: int) -> str:
+    """可读名,只用于日志与错误信息,不上 wire。"""
+    if p == Protocol.OPENAI_CHAT_COMPLETIONS:
+        return "openai_chat_completions"
+    if p == Protocol.OPENAI_RESPONSES:
+        return "openai_responses"
+    if p == Protocol.ANTHROPIC_MESSAGES:
+        return "anthropic_messages"
+    return f"protocol({p})"
+
+
+def mode_valid(m: int) -> bool:
+    return Mode.STRICT <= m <= Mode.SIMPLE
+
+
+def mode_string(m: int) -> str:
+    """可读名,只用于日志与错误信息,不上 wire。"""
+    if m == Mode.STRICT:
+        return "strict"
+    if m == Mode.COMPATIBLE:
+        return "compatible"
+    if m == Mode.SIMPLE:
+        return "simple"
+    return f"mode({m})"
+
+
+@dataclass(frozen=True)
+class Binding:
+    """请求 / 流级绑定上下文,进 Metadata(随之进 AAD)。"""
+
+    request_id: str
+    protocol: int
+    mode: int
+
+    def validate(self) -> None:
+        """加密侧与解密期望值共用:request_id 规则不变,protocol / mode 须已知。"""
+        validate_request_id(self.request_id)
+        if not protocol_valid(self.protocol):
+            raise BindingError(f"unknown protocol {int(self.protocol)}")
+        if not mode_valid(self.mode):
+            raise BindingError(f"unknown mode {int(self.mode)}")
+
+
+MAX_FIELD_PATH_LEN = 1024
+MAX_FIELD_SEQ = 2**31 - 1  # 与 proto int32 往返不截断
+
+
+def validate_field_path(field_path: str) -> None:
+    """格式校验:UTF-8 字节数 ≤ 1024、合法 UTF-8、无控制字符;空串合法(空与否由模式规则决定)。"""
+    try:
+        n = len(field_path.encode("utf-8"))
+    except UnicodeEncodeError:
+        raise BindingError("field_path invalid utf-8") from None
+    if n > MAX_FIELD_PATH_LEN:
+        raise BindingError(f"field_path {n} bytes, max {MAX_FIELD_PATH_LEN}")
+    for ch in field_path:
+        c = ord(ch)
+        if c < 0x20 or c == 0x7F:
+            raise BindingError(f"field_path control character {hex(c)}")
+
+
+@dataclass(frozen=True)
+class Position:
+    """字段级位置:field_path 为命中该字段的点分路径(不含数组下标),field_seq 为该路径内第几次加密(从 0 起)。"""
+
+    field_path: str = ""
+    field_seq: int = 0
+
+    def validate(self) -> None:
+        """格式 + 范围;解密期望值只用这一层(空 field_path 合法)。"""
+        validate_field_path(self.field_path)
+        if self.field_seq < 0 or self.field_seq > MAX_FIELD_SEQ:
+            raise BindingError(f"field_seq {self.field_seq} out of range")
+
+    def normalize(self, mode: int) -> Position:
+        """加密侧:Simple 归一为零值(调用方不必感知模式);其余模式校验并要求 field_path 非空。"""
+        if mode == Mode.SIMPLE:
+            return Position()
+        self.validate()
+        if self.field_path == "":
+            raise BindingError(f"field_path required in {mode_string(mode)} mode")
+        return self
+
+
+#: 解密侧容忍表(单协议、key 不带前缀):expected field_path → 可接受的 carried field_path 列表;
+#: 命中即视同相等(不产生 field_path 项,field_seq 照比);None / 空 = 无别名。
+FieldPathAliases = dict[str, list[str]]
+
+
+def validate_field_path_aliases(a: FieldPathAliases | None) -> None:
+    """key 与每个 value 非空且过 ``validate_field_path``;不合规抛 ``BindingError``。"""
+    if not a:
+        return
+    for k, vs in a.items():
+        if k == "":
+            raise BindingError("alias key empty")
+        try:
+            validate_field_path(k)
+        except BindingError as exc:
+            raise BindingError(f'alias key "{k}": {exc}') from None
+        for v in vs:
+            if v == "":
+                raise BindingError(f'alias of "{k}" empty')
+            try:
+                validate_field_path(v)
+            except BindingError as exc:
+                raise BindingError(f'alias of "{k}": {exc}') from None
+
+
+def alias_accepts(a: FieldPathAliases | None, expected: str, carried: str) -> bool:
+    """carried 是否在 expected 的别名列表内。"""
+    return bool(a) and carried in a.get(expected, ())
+
+
+@dataclass(frozen=True)
+class Mismatch:
+    """一项被容忍(Compatible / Simple)的不一致;Strict 下同样内容进 BindingMismatchError 文本。"""
+
+    field: str  # "protocol" | "field_path" | "field_seq"
+    expected: str
+    carried: str
+
+    def __str__(self) -> str:
+        """形如 ``field_path expected "a" carried "b"``(与 Go %q 一致)。"""
+        return f'{self.field} expected "{self.expected}" carried "{self.carried}"'
+
+
+def require_binding(md: Metadata | None) -> None:
+    """带完整 Metadata 的信封(prompt / response / 尾片):request_id / protocol 存在、mode 已知。"""
+    if md is None:
+        raise FormatError("metadata required")
+    if not md.request_id:
+        raise FormatError("metadata missing request_id")
+    if not md.protocol:
+        raise FormatError("metadata missing protocol")
+    if not mode_valid(md.mode):
+        raise FormatError(f"metadata mode {md.mode} missing or unknown")
+
+
+def check_mode_echo(md: Metadata, want: int) -> None:
+    """response / 尾片的 mode 须等于本地配置(回文 mode 由 agent 复制自 prompt),任何模式恒拒。"""
+    if md.mode != want:
+        raise BindingMismatchError(
+            f'mode expected "{mode_string(want)}" carried "{mode_string(md.mode)}"'
+        )
+
+
+def mismatch_protocol(md: Metadata, want: int) -> list[Mismatch]:
+    """协议比对(三模式都比);中间片不带 protocol,调用方不调它。"""
+    if md.protocol == want:
+        return []
+    return [Mismatch("protocol", protocol_string(want), protocol_string(md.protocol))]
+
+
+def mismatch_position(
+    md: Metadata, mode: int, want: Position, aliases: FieldPathAliases | None = None
+) -> list[Mismatch]:
+    """位置比对;Simple 不比;carried field_path 在 aliases[want.field_path] 内视同相等(field_seq 照比)。"""
+    if mode == Mode.SIMPLE:
+        return []
+    mm: list[Mismatch] = []
+    if md.field_path != want.field_path and not alias_accepts(
+        aliases, want.field_path, md.field_path
+    ):
+        mm.append(Mismatch("field_path", want.field_path, md.field_path))
+    if md.field_seq != want.field_seq:
+        mm.append(Mismatch("field_seq", str(want.field_seq), str(md.field_seq)))
+    return mm
+
+
+def settle(mm: list[Mismatch], mode: int) -> list[Mismatch]:
+    """按 mode 落定:Strict 有不一致即抛(文本列全部项);其余模式原样回报给调用方记日志。"""
+    if mm and mode == Mode.STRICT:
+        raise BindingMismatchError("; ".join(str(m) for m in mm))
+    return mm

tcaicc/common/cipherx/_constants.py

@@ -0,0 +1,17 @@
+"""cipherx wire 常量(镜像 aicc-common/cipherx/envelope.go 的常量块)。
+
+独立模块以打破 ``_envelope`` ↔ ``_metadata`` 的循环导入,并作单一事实源。
+"""
+from __future__ import annotations
+
+MAGIC = b"AICCv1"
+SUFFIX_SIZE = 10
+GCM_NONCE_SIZE = 12
+GCM_TAG_SIZE = 16
+MIN_CIPHERTEXT = GCM_NONCE_SIZE + GCM_TAG_SIZE  # 28
+HASH_SIZE = 32
+KEY_SIZE = 32
+MAX_PLAINTEXT = 64 << 20
+MAX_ENVELOPE = 65 << 20
+MAX_METADATA_LEN = 65535
+MAX_PREFIX_LEN = 1024

tcaicc/common/cipherx/_decrypt.py

@@ -0,0 +1,109 @@
+"""非流式解密(镜像 aicc-common/cipherx/decrypt.go)。
+
+结构 → 类型 → 必填绑定字段存在性 → AAD 重建(wire 原始切片)→ GCM → 剥内层填充 → Hash
+→ request_id → mode → protocol / 位置比对(spec 2026-09-14 §4.2)。
+chunk 属流式语义,须用 ``ChunkDecryptor``。
+"""
+from __future__ import annotations
+
+from ..cryptox._subtle import constant_time_equal
+from ._aead import open_with_aad
+from ._binding import (
+    Binding,
+    FieldPathAliases,
+    Position,
+    check_mode_echo,
+    mismatch_position,
+    mismatch_protocol,
+    protocol_valid,
+    require_binding,
+    settle,
+    validate_field_path_aliases,
+)
+from ._envelope import (
+    CipherType,
+    _to_envelope,
+    has_hash,
+    non_stream_aad,
+    parse_envelope,
+    type_label,
+)
+from ._errors import (
+    BindingError,
+    CipherTypeError,
+    FormatError,
+    HashMismatchError,
+    RequestIdError,
+    RequestMismatchError,
+)
+from ._hash import prompt_hash
+from ._padding import unpad
+from ._requestid import validate_request_id
+
+
+def _open_non_stream(key: bytes, p):
+    """两类型共通尾段:AAD 原样重建 → GCM → 剥内层填充(spec 2026-10-08 §4)→ Hash(仅 prompt,对真实数据)。"""
+    inner = open_with_aad(key, p.ciphertext, non_stream_aad(p.prefix, p.hash, p.meta_raw, p.suffix))
+    pt = unpad(inner)
+    if has_hash(p.flags) and not constant_time_equal(prompt_hash(pt), p.hash):
+        raise HashMismatchError()
+    env = _to_envelope(p)
+    env.plaintext = pt
+    return env
+
+
+def decrypt_prompt(key: bytes, envelope: bytes, protocol: int, pos: Position):
+    """解 prompt 信封:request_id / mode 取 wire(缺失 / 不合规 → FormatError)。
+
+    protocol 与 pos 为解密方(gateway 端点与 JSON 遍历)算出的期望值,按 wire mode
+    比对(Strict 拒 / Compatible 记 / Simple 只比 protocol);非 prompt → CipherTypeError。
+    """
+    if not protocol_valid(protocol):
+        raise BindingError(f"unknown protocol {int(protocol)}")
+    pos.validate()
+    p = parse_envelope(envelope)
+    if p.typ != CipherType.PROMPT:
+        raise CipherTypeError(f"{type_label(p.typ)} envelope is not a prompt")
+    # flags 白名单保证 prompt 必有 metadata。
+    try:
+        validate_request_id(p.meta.request_id if p.meta is not None else "")
+    except RequestIdError as exc:
+        raise FormatError(f"metadata request_id: {exc}") from None
+    require_binding(p.meta)
+    env = _open_non_stream(key, p)
+    md = env.metadata
+    env.mismatches = settle(
+        mismatch_protocol(md, protocol) + mismatch_position(md, md.mode, pos), md.mode
+    )
+    return env
+
+
+def decrypt_response(
+    key: bytes,
+    b: Binding,
+    pos: Position,
+    envelope: bytes,
+    *,
+    aliases: FieldPathAliases | None = None,
+):
+    """解 response 信封:b 为本请求的 request_id / 端点协议 / 本地 mode,pos 为自算位置。
+
+    GCM 通过后:request_id 相等(RequestMismatchError)→ mode 回显相等(恒拒)
+    → protocol / 位置按本地 mode 比对(位置经别名表 aliases)。
+    """
+    b.validate()
+    pos.validate()
+    validate_field_path_aliases(aliases)
+    p = parse_envelope(envelope)
+    if p.typ != CipherType.RESPONSE:
+        raise CipherTypeError(f"{type_label(p.typ)} envelope is not a response")
+    require_binding(p.meta)
+    env = _open_non_stream(key, p)
+    md = env.metadata
+    if md.request_id != b.request_id:
+        raise RequestMismatchError(f'envelope carries "{md.request_id}"')
+    check_mode_echo(md, b.mode)
+    env.mismatches = settle(
+        mismatch_protocol(md, b.protocol) + mismatch_position(md, b.mode, pos, aliases), b.mode
+    )
+    return env