技术审计文档

            # 添加说明文件
            readme_content = f"""
维权证据包说明

生成时间：{datetime.now().strftime("%Y-%m-%d %H:%M:%S")}

本证据包包含以下内容：
1. 时间戳认证文件 - 证明作品创作时间及权属
2. 证据材料 - 原始作品文件
3. 截图证据 - 侵权行为截图
4. 律师函 - 法律维权文件

请妥善保管本证据包，作为法律维权的有效证据。

---
Nephele Workshop - 维权中心
ArisFusion Studio
"""
            zipf.writestr("说明.txt", readme_content.encode("utf-8"))

        return output_path

    except Exception as e:
        raise RightsError(f"创建证据包失败: {str(e)}")


def calculate_file_hash(file_path: Path, algorithm: str = "sha256") -> str:
    """
    计算文件的哈希值（极简版，仅用于非确权场景）

    Args:
        file_path: 文件路径
        algorithm: 哈希算法，默认 'sha256'

    Returns:
        文件的十六进制哈希值

    Raises:
        RightsError: 文件不存在或读取失败
    """
    if not file_path or not isinstance(file_path, Path):
        raise RightsError(f"无效的文件路径: {file_path}")

    if not file_path.exists():

class MerkleTree:
    """
    Merkle Tree 实现，用于将多个文件的哈希值聚合成单个根哈希

    优势：
    - 支持 100+ 文件批量处理
    - 单个根哈希可代表整个批次
    - 节省 TSA 调用成本（1 次调用 vs N 次调用）

    Known limitation (second-preimage resistance):
        This implementation does NOT use domain separation prefixes for leaf vs
        internal nodes (i.e. b'\\x00' for leaves, b'\\x01' for internal nodes as
        recommended by RFC 6962 §2.1).  Adding prefixes would change the root hash
        computation and break backward compatibility with all existing .nep files
        and the verification website (verify.arisfusion.com).  A future tree_version
        bump can introduce domain separation; the current version is safe for our
        threat model (user-submitted files, not adversarial tree construction).
    """

    def __init__(self, hash_algorithm: str = "sha256"):
        """
        初始化 Merkle Tree

        Args:
            hash_algorithm: 哈希算法，默认 'sha256'
        """
        self.hash_algorithm = hash_algorithm
        self.leaves: List[str] = []
        self.tree: List[List[str]] = []
        self.root_hash: Optional[str] = None

    def add_leaf(self, data: bytes) -> str:
        """
        添加叶子节点（文件哈希）

        Args:
            data: 文件数据或哈希值（bytes）

        Returns:
            叶子节点的哈希值
        """
        hash_obj = hashlib.new(self.hash_algorithm)
        hash_obj.update(data)
        leaf_hash = hash_obj.hexdigest()
        self.leaves.append(leaf_hash)
        return leaf_hash

    def add_file_hash(self, file_hash: str) -> None:
        """
        直接添加文件哈希值（已计算好的）

        Args:
            file_hash: 文件的十六进制哈希值
        """
        self.leaves.append(file_hash)

    def build(self) -> str:
        """
        构建 Merkle Tree 并返回根哈希

        Returns:
            根哈希值（十六进制字符串）
        """
        if not self.leaves:
            raise ValueError("Merkle Tree 没有叶子节点")

        # 如果只有一个叶子节点，直接返回
        if len(self.leaves) == 1:
            self.root_hash = self.leaves[0]
            return self.root_hash

        # 构建树：从叶子节点开始，逐层向上
        current_level = self.leaves.copy()
        self.tree = [current_level]

        while len(current_level) > 1:
            next_level = []

            # 成对处理节点
            for i in range(0, len(current_level), 2):
                if i + 1 < len(current_level):
                    # 两个节点：合并哈希
                    combined = current_level[i] + current_level[i + 1]
                else:
                    # 奇数个节点：最后一个节点复制后与自己合并
                    combined = current_level[i] + current_level[i]

                # 计算父节点哈希
                hash_obj = hashlib.new(self.hash_algorithm)
                hash_obj.update(combined.encode("utf-8"))
                parent_hash = hash_obj.hexdigest()
                next_level.append(parent_hash)

            self.tree.append(next_level)
            current_level = next_level

        # 根哈希是最后一层的唯一节点
        self.root_hash = current_level[0]
        return self.root_hash

    def get_proof(self, leaf_index: int) -> List[Dict]:
        """
        获取指定叶子节点的 Merkle Proof（用于验证）

        Args:
            leaf_index: 叶子节点索引

        Returns:
            Merkle Proof 路径，每个元素为 {'hash': str, 'position': 'left'|'right'}
            position 表示兄弟节点在合并时的位置
        """
        if not self.tree:
            self.build()

        if leaf_index >= len(self.leaves):
            raise IndexError(f"叶子节点索引超出范围: {leaf_index}")

        proof = []
        current_index = leaf_index
        current_level = 0

        while current_level < len(self.tree) - 1:
            level = self.tree[current_level]

            # 找到兄弟节点并记录位置
            if current_index % 2 == 0:
                # 当前是左节点，兄弟在右侧
                sibling_index = current_index + 1
                if sibling_index < len(level):
                    proof.append({"hash": level[sibling_index], "position": "right"})
                else:
                    # 奇数情况，兄弟是自己（已复制）
                    proof.append({"hash": level[current_index], "position": "right"})
            else:
                # 当前是右节点，兄弟在左侧
                sibling_index = current_index - 1
                proof.append({"hash": level[sibling_index], "position": "left"})

            # 移动到上一层
            current_index = current_index // 2
            current_level += 1

        return proof

    def verify_proof(self, leaf_hash: str, proof: List[Dict], root_hash: str) -> bool:
        """
        验证 Merkle Proof

        Args:
            leaf_hash: 叶子节点哈希
            proof: Merkle Proof 路径（由 get_proof 返回）
            root_hash: 根哈希

        Returns:
            验证是否通过
        """
        current_hash = leaf_hash

        for step in proof:
            sibling_hash = step["hash"]
            position = step["position"]

            # 按照 build() 相同的位置顺序合并：左 + 右
            if position == "right":
                combined = current_hash + sibling_hash
            else:
                combined = sibling_hash + current_hash

            hash_obj = hashlib.new(self.hash_algorithm)
            hash_obj.update(combined.encode("utf-8"))
            current_hash = hash_obj.hexdigest()

        return current_hash == root_hash

class TSAClient:
    """
    RFC 3161 时间戳服务客户端

    支持的服务：
    - FreeTSA (https://freetsa.org/tsr) - 免费，无需注册
    - DigiCert (http://timestamp.digicert.com)
    - IdenTrust (http://timestamp.identrust.com)
    - 其他 RFC 3161 兼容服务
    """

    # 预定义的 TSA 服务提供商
    PROVIDERS = {
        "freetsa": {
            "name": "FreeTSA",
            "url": "https://freetsa.org/tsr",
            "hashname": "sha256",
            "description": "免费时间戳服务，国际标准 RFC 3161",
            "requires_auth": False,
            "legal_strength": 3,  # 1-5 评分
            "price": 0,
        },
        "digicert": {
            "name": "DigiCert",
            "url": "http://timestamp.digicert.com",
            "hashname": "sha256",
            "description": "DigiCert 免费时间戳服务",
            "requires_auth": False,
            "legal_strength": 4,
            "price": 0,
        },
        "identrust": {
            "name": "IdenTrust",
            "url": "http://timestamp.identrust.com",
            "hashname": "sha256",
            "description": "IdenTrust 免费时间戳服务",
            "requires_auth": False,
            "legal_strength": 4,
            "price": 0,
        },
    }

    def __init__(
        self, provider: str = "freetsa", custom_url: Optional[str] = None, hashname: str = "sha256", timeout: int = 30
    ):
        """
        初始化 TSA 客户端

        Args:
            provider: 预定义的服务提供商名称 ('freetsa', 'digicert', 'identrust')
            custom_url: 自定义 TSA URL（如果指定，则忽略 provider）
            hashname: 哈希算法 ('sha256', 'sha512' 等)
            timeout: 请求超时时间（秒）
        """
        if not RFC3161_AVAILABLE:
            raise ImportError("rfc3161ng 库未安装。请运行: pip install rfc3161ng")

        if custom_url:
            self.url = custom_url
            self.provider_name = "Custom TSA"
            self.provider_key = None
        elif provider in self.PROVIDERS:
            config = self.PROVIDERS[provider]
            self.url = config["url"]
            self.provider_name = config["name"]
            self.provider_key = provider
            hashname = config["hashname"]
        else:
            raise ValueError(f"未知的 TSA 提供商: {provider}。支持的提供商: {', '.join(self.PROVIDERS.keys())}")

        self.hashname = hashname
        self.timeout = timeout

        # 初始化 rfc3161ng 时间戳器
        # 注意：某些环境可能遇到 SSL 握手问题，这是正常的
        # 我们的设计会自动降级到本地哈希
        try:
            # include_tsa_certificate (certReq)：令牌必须自带签名证书链，
            # 否则验证方（尤其 verify.arisfusion.com 拿到的孤令牌）无从验签
            self.stamper = rfc3161ng.RemoteTimestamper(
                url=self.url, hashname=self.hashname, timeout=self.timeout, include_tsa_certificate=True
            )
        except Exception as e:
            # 如果初始化失败，记录错误但不抛出异常
            # 后续调用时会返回失败状态
            self.stamper = None
            self._init_error = str(e)

    FAILOVER_ORDER: List[str] = ["digicert", "freetsa", "identrust"]

    def _call_with_retry(self, hash_bytes: bytes, max_retries: int = 3) -> bytes:
        """
        带指数退避和提供商故障转移的 TSA 调用

        Args:
            hash_bytes: 要签名的哈希值（二进制）
            max_retries: 每个提供商的最大重试次数

        Returns:
            TSR 令牌（二进制）

        Raises:
            Exception: 所有提供商均失败
        """
        # 构建尝试顺序：当前提供商优先，然后是其他提供商
        providers_to_try = []
        if self.provider_key:
            providers_to_try.append(self.provider_key)
            for p in self.FAILOVER_ORDER:
                if p != self.provider_key:
                    providers_to_try.append(p)
        else:
            # 自定义 URL，无故障转移
            providers_to_try = [None]

        last_error = None
        for provider_key in providers_to_try:
            if provider_key is not None:
                config = self.PROVIDERS[provider_key]
                url = config["url"]
                hashname = config["hashname"]
                provider_name = config["name"]
            else:
                url = self.url
                hashname = self.hashname
                provider_name = self.provider_name

            for attempt in range(max_retries):
                try:
                    stamper = rfc3161ng.RemoteTimestamper(
                        url=url, hashname=hashname, timeout=self.timeout, include_tsa_certificate=True
                    )
                    tsr_token = stamper(digest=hash_bytes)
                    # 成功后更新当前提供商信息
                    if provider_key is not None:
                        self.provider_name = provider_name
                        self.provider_key = provider_key
                        self.url = url
                        self.stamper = stamper
                    return tsr_token
                except Exception as e:
                    last_error = e
                    if attempt < max_retries - 1:
                        time.sleep(2**attempt)

        raise Exception(
            f"所有 TSA 提供商均失败 (尝试: {', '.join(p or 'custom' for p in providers_to_try)}): {last_error}"
        )

    def timestamp_data(self, data: bytes) -> bytes:
        """
        对原始数据生成时间戳

        Args:
            data: 要加时间戳的数据（二进制）

        Returns:
            TSR (Time-Stamp Response) 二进制令牌

        Raises:
            Exception: 时间戳请求失败
        """
        try:
            # 计算数据的哈希值
            hash_obj = hashlib.new(self.hashname)
            hash_obj.update(data)
            data_hash = hash_obj.digest()

            # 调用 TSA 服务获取时间戳（带重试和故障转移）
            tsr_token = self._call_with_retry(data_hash)

            return tsr_token
        except Exception as e:
            raise Exception(f"时间戳请求失败: {str(e)}")

    def timestamp_file(self, file_path: Path, output_path: Optional[Path] = None) -> Dict:
        """
        为文件生成时间戳（流式处理，不将整个文件载入内存）

        Args:
            file_path: 要加时间戳的文件路径
            output_path: TSR 文件输出路径（可选，默认为 file_path.tsr）

        Returns:
            包含时间戳信息的字典
        """
        file_path = Path(file_path)

        if not file_path.exists():
            return {"success": False, "message": f"文件不存在: {file_path}"}

        try:
            # 流式计算文件哈希（8KB 分块，避免大文件内存溢出）
            hash_obj = hashlib.new(self.hashname)
            with open(file_path, "rb") as f:
                while True:
                    chunk = f.read(8192)
                    if not chunk:
                        break
                    hash_obj.update(chunk)

            file_hash = hash_obj.hexdigest()

            # 确定输出路径
            if output_path is None:
                output_path = file_path.parent / f"{file_path.stem}.tsr"
            else:
                output_path = Path(output_path)

            # 委托给 timestamp_hash（处理 TSA 调用、重试和文件写入）
            result = self.timestamp_hash(file_hash, output_path)

            # 确保返回文件哈希
            if result.get("success"):
                result["hash"] = file_hash

            return result

        except Exception as e:
            return {"success": False, "message": f"时间戳生成失败: {str(e)}"}

    def timestamp_hash(self, hash_value: str, output_path: Path) -> Dict:
        """
        为已知的哈希值生成时间戳（用于 Merkle Root 等场景）

        Args:
            hash_value: 十六进制哈希值字符串
            output_path: TSR 文件输出路径

        Returns:
            包含时间戳信息的字典
        """
        try:
            # 将十六进制哈希值转换为二进制
            hash_bytes = bytes.fromhex(hash_value)

            # 获取时间戳令牌（带重试和故障转移）
            tsr_token = self._call_with_retry(hash_bytes)

            # 保存 TSR 文件
            output_path = Path(output_path)
            output_path.parent.mkdir(parents=True, exist_ok=True)
            with open(output_path, "wb") as f:
                f.write(tsr_token)

            # 从 TSR 令牌中提取 TSA 认证时间（而非本机时钟）
            tsa_timestamp = datetime.now().isoformat()  # fallback
            tsa_issuer = self.provider_name
            try:
                from asn1crypto import tsp, cms

                # Try TimeStampResp first, then ContentInfo
                signed_data = None
                try:
                    ts_resp = tsp.TimeStampResp.load(tsr_token)
                    signed_data = ts_resp["time_stamp_token"]["content"]
                except (ValueError, KeyError, TypeError):
                    try:
                        ci = cms.ContentInfo.load(tsr_token)
                        if ci["content_type"].native == "signed_data":
                            signed_data = ci["content"]
                    except (ValueError, KeyError, TypeError):
                        pass

                if signed_data:
                    tst_info = signed_data["encap_content_info"]["content"].parsed
                    gen_time = tst_info["gen_time"].native
                    if gen_time:
                        tsa_timestamp = gen_time.isoformat()

                    # Extract issuer CN from signer info
                    try:
                        signer_infos = signed_data["signer_infos"]
                        if signer_infos:
                            sid = signer_infos[0]["sid"]
                            if sid.name == "issuer_and_serial_number":
                                for rdn in sid.chosen["issuer"].chosen:
                                    for attr in rdn:
                                        if attr["type"].dotted == "2.5.4.3":
                                            tsa_issuer = attr["value"].native
                                            break
                    except (KeyError, IndexError, ValueError):
                        pass
            except ImportError:
                pass  # asn1crypto not available, use fallback values

            return {
                "success": True,
                "timestamp": tsa_timestamp,
                "hash": hash_value,
                "issuer": tsa_issuer,
                "tsr_path": str(output_path),
                "algorithm": self.hashname.upper(),
                "message": f"时间戳生成成功，TSR 文件: {output_path.name}",
            }

        except Exception as e:
            return {"success": False, "message": f"时间戳生成失败: {str(e)}"}

    def verify_tsr(
        self,
        tsr_path: Path,
        data: Optional[bytes] = None,
        digest: Optional[bytes] = None,
    ) -> Dict:
        """
        验证 TSR 时间戳令牌

        Args:
            tsr_path: TSR 文件路径
            data: 原始数据（可选，库内部计算哈希后比对）
            digest: 预计算的哈希值（可选，直接与 TSR 中记录的哈希比对）
                    data 和 digest 二选一；都不传则仅验证 TSR 结构

        Returns:
            验证结果字典，包含 'valid', 'message', 'issuer' 等字段。
            当 data/digest 未提供时，结果包含 'partial_verification': True 标志。
        """
        tsr_path = Path(tsr_path)

        if not tsr_path.exists():
            return {"valid": False, "message": f"TSR 文件不存在: {tsr_path}"}

        try:
            with open(tsr_path, "rb") as f:
                tsr_token = f.read()

            if digest is None and data is None:
                # 结构验证：无原始数据时，验证 TSR 文件结构有效性
                return self._verify_tsr_structure(tsr_token)

            # messageImprint 比对走 asn1crypto 自解析。不用 rfc3161ng.check_timestamp：
            # 它默认 sha1、且对 DigiCert 令牌在 load_certificate 处抛 TypeError，
            # 带 data/digest 的验证路径实际从未工作过。
            info = self._extract_tst_info(tsr_token)
            if info is None:
                res = self._verify_tsr_structure(tsr_token)
                res["valid"] = False
                res["message"] = "无法解析时间戳令牌中的 messageImprint"
                return res
            hashname, hashed_message, gen_time = info

            if digest is None:
                digest = hashlib.new(hashname, data).digest()
            if digest != hashed_message:
                return {"valid": False, "message": "时间戳验证失败：哈希值不匹配"}

            # 完整性通过后必须验签——messageImprint 比对只防误改，不防伪造：
            # 自造令牌可以写任意哈希和时间。签名+证书链才把令牌钉到真实 TSA。
            from .tsa_verify import verify_token_signature

            sig = verify_token_signature(tsr_token)
            base = {
                "issuer": self._extract_issuer_from_tsr(tsr_token),
                "algorithm": hashname.upper(),
                "timestamp": gen_time.isoformat() if gen_time else "",
                "signature": sig["signature"],
                "signer": sig.get("signer"),
                "chain_root": sig.get("chain_root"),
            }
            if sig["signature"] == "verified":
                return {
                    "valid": True,
                    "message": f"时间戳验证通过（数据完整性、TSA 签名与证书链均已确认，根: {sig['chain_root']}）",
                    **base,
                }
            if sig["signature"] == "unknown_signer":
                return {
                    "valid": False,
                    "message": "数据完整性匹配，但无法本地验证 TSA 签名（未知签发者）。"
                    "可用 openssl ts -verify 独立验证该令牌。",
                    **base,
                }
            return {
                "valid": False,
                "message": f"时间戳验证失败：{sig['message']}",
                **base,
            }

        except Exception as e:
            return {"valid": False, "message": f"时间戳验证失败: {str(e)}"}

    def _extract_tst_info(self, tsr_token: bytes):
        """从 TSR/令牌中解出 (hash 算法名, messageImprint 哈希, 签发时间)。
        兼容 TimeStampResp 与裸 ContentInfo/SignedData 两种落盘格式；
        解析失败返回 None。"""
        try:
            from asn1crypto import cms, tsp

            signed_data = None
            try:
                ts_resp = tsp.TimeStampResp.load(tsr_token)
                signed_data = ts_resp["time_stamp_token"]["content"]
            except (ValueError, KeyError, TypeError):
                try:
                    ci = cms.ContentInfo.load(tsr_token)
                    if ci["content_type"].native == "signed_data":
                        signed_data = ci["content"]
                except (ValueError, KeyError, TypeError):
                    pass
            if signed_data is None:
                return None

            econtent = signed_data["encap_content_info"]["content"]
            tst = None
            if isinstance(econtent, tsp.TSTInfo):
                tst = econtent
            else:
                try:
                    parsed = econtent.parsed
                    if isinstance(parsed, tsp.TSTInfo):
                        tst = parsed
                except (ValueError, AttributeError):
                    pass
                if tst is None:
                    raw = econtent.native
                    if isinstance(raw, bytes):
                        tst = tsp.TSTInfo.load(raw)
            if tst is None:
                return None

            imprint = tst["message_imprint"]
            hashname = imprint["hash_algorithm"]["algorithm"].native
            hashed_message = imprint["hashed_message"].native
            gen_time = None
            try:
                gen_time = tst["gen_time"].native
            except (ValueError, KeyError):
                pass
            return hashname, hashed_message, gen_time
        except Exception:
            return None

    def _extract_issuer_from_tsr(self, tsr_token: bytes) -> str:
        """Extract the actual issuer CN from a TSR token using asn1crypto.

        Falls back to self.provider_name if parsing fails or asn1crypto
        is unavailable.  This ensures verify_tsr() reports the real issuer
        even after failover to a different TSA provider.
        """
        try:
            from asn1crypto import tsp, cms

            signed_data = None
            try:
                ts_resp = tsp.TimeStampResp.load(tsr_token)
                signed_data = ts_resp["time_stamp_token"]["content"]
            except (ValueError, KeyError, TypeError):
                try:
                    ci = cms.ContentInfo.load(tsr_token)
                    if ci["content_type"].native == "signed_data":
                        signed_data = ci["content"]
                except (ValueError, KeyError, TypeError):
                    pass

            if signed_data:
                signer_infos = signed_data["signer_infos"]
                if signer_infos:
                    sid = signer_infos[0]["sid"]
                    if sid.name == "issuer_and_serial_number":
                        for rdn in sid.chosen["issuer"].chosen:
                            for attr in rdn:
                                if attr["type"].dotted == "2.5.4.3":  # CN
                                    return attr["value"].native
        except (ImportError, Exception):
            pass

        return self.provider_name

    def _verify_tsr_structure(self, tsr_token: bytes) -> Dict:
        """验证 TSR 令牌的结构 + TSA 签名与证书链（不验证数据完整性——
        无原始数据可比时，签名仍是自包含可验的）"""
        if len(tsr_token) < 20:
            return {"valid": False, "message": "TSR 文件过小，可能已损坏"}

        if tsr_token[0] != 0x30:
            return {"valid": False, "message": "TSR 文件不是有效的 ASN.1 DER 格式"}

        try:
            from asn1crypto import tsp

            try:
                ts_resp = tsp.TimeStampResp.load(tsr_token)
                status = ts_resp["status"]["status"].native
                if status not in ("granted", "granted_with_mods"):

                # 同时解析 TSR 获取时间戳详情（签发时间、签发方）
                tsr_result = parse_tsr(tsa_path)
                return True, {
                    "valid": True,
                    "message": (
                        "深度验证通过：作品文件与作者声明均已绑定 TSA 时间戳"
                        if metadata_bound
                        else "文件验证通过；旧版时间戳未覆盖作者等清单信息"
                    ),
                    "timestamp": tsr_result.get("timestamp"),
                    "issuer": tsr_result.get("issuer"),
                    "root_hash": computed_root,
                    "metadata_bound": metadata_bound,
                    "file_count": len(file_paths),
                }
            else:
                return False, {
                    "valid": False,
                    "message": f"TSA 签名验证失败：{verify_result.get('message', 'unknown')}",
                    "root_hash": computed_root,
                    "metadata_bound": False,
                    "file_count": len(file_paths),
                }

        except ImportError:
            # rfc3161ng 未安装（仅签发需要它）——parse_tsr 仍走签名+链验证，
            # 这里只补上 Merkle Root 与 imprint 的比对
            tsr_result = parse_tsr(tsa_path)
            if not tsr_result.get("valid"):
                return False, {
                    "valid": False,
                    "message": tsr_result.get("message", "时间戳验证失败"),
                    "root_hash": computed_root,
                    "metadata_bound": False,
                    "file_count": len(file_paths),
                }
            tsr_hash_raw = tsr_result.get("hash", "")
            tsr_hash = tsr_hash_raw.split(":", 1)[1] if ":" in tsr_hash_raw else tsr_hash_raw

            if expected_hash.lower() == tsr_hash.lower():
                return True, {
                    "valid": True,
                    "message": (
                        "验证通过：作品文件与作者声明均已绑定 TSA 时间戳"
                        if metadata_bound
                        else "文件验证通过；旧版时间戳未覆盖作者等清单信息"
                    ),
                    "timestamp": tsr_result.get("timestamp"),
                    "issuer": tsr_result.get("issuer"),
                    "root_hash": computed_root,
                    "metadata_bound": metadata_bound,
                    "file_count": len(file_paths),
                    "partial_verification": True,
                }
            else:
                return False, {
                    "valid": False,
                    "message": "验证失败：存证摘要与 TSR 记录的哈希不匹配",
                    "computed_root": computed_root,
                    "tsr_hash": tsr_hash,
                    "file_count": len(file_paths),
                }

    except Exception as e:
        return False, {"valid": False, "message": f"深度验证失败: {e}"}


def batch_protect_works(
    file_paths: List[Path],
    author_name: str,
    inspiration: Optional[str] = None,
    output_dir: Optional[Path] = None,
    password: Optional[str] = None,
    progress_callback=None,
    tsa_provider: str = "digicert",
    tsa_timeout: int = 30,
    cert_mode: str = "simple",
    credential_signer=None,
) -> Dict:
    """
    批量保护作品（数字存证核心流程）

    流程：
    0. （可选）为图片作品生成 C2PA 带凭证副本 —— 必须排在哈希之前
    1. 计算所有文件哈希（原图 + 副本一起进树）
    2. 构建 Merkle Tree
    3. 生成 manifest.json
    4. 生成缩略图拼贴
    5. 调用 TSA 获取时间戳（覆盖完整清单摘要）
    6. 生成 PDF 报告
    7. 打包为 .nep 文件

    Args:
        file_paths: 文件路径列表
        author_name: 作者名称
        inspiration: 创作灵感（可选）
        output_dir: 输出目录
        password: .nep 文件密码（可选）
        progress_callback: 进度回调 (current, total, message)
        credential_signer: c2pa Signer；给了就为每张图生成带凭证副本。
            副本与原图**一同进入 Merkle Tree**，被同一个 TSA 时间戳覆盖 ——
            否则「先打包证据、再做副本」会让副本的哈希不在证据里，用户拿副本
            去核验存证包必然对不上。两份都在，手上是哪一份都验得上。

    Returns:
        包含处理结果的字典
    """
    from .utils import build_merkle_tree_from_files
    from .rights_packer import RightsPacker
    from .pdf_generator import PDFGenerator

    if not file_paths:
        raise RightsError("文件列表为空")

    if output_dir is None:
        output_dir = Path.cwd() / "digital_evidence"
    output_dir = Path(output_dir)
    output_dir.mkdir(parents=True, exist_ok=True)

    image_extensions = {".jpg", ".jpeg", ".png", ".webp", ".bmp"}

    try:
        # 步骤 0: 带凭证副本（可选）。必须早于哈希 —— 副本的字节要进 Merkle
        # Tree，才能和原图共用同一个 TSA 时间戳。签名失败不阻断存证：凭证是
        # 增值，时间戳才是这个流程的本体。
        credential_map: Dict[Path, Path] = {}
        credential_errors: List[str] = []
        if credential_signer is not None:
            from tools.validator.c2pa_signer import SUPPORTED_EXTENSIONS, sign_file

            cred_dir = output_dir / "credentialed"
            for src in file_paths:
                if src.suffix.lower() not in SUPPORTED_EXTENSIONS:
                    continue  # 源文件（PSD/CLIP/SAI…）C2PA 不支持，跳过
                if progress_callback:
                    progress_callback(0, len(file_paths), f"正在生成凭证副本: {src.name}")
                dst = cred_dir / f"{src.stem}_credentialed{src.suffix}"
                res = sign_file(str(src), str(dst), author=author_name, signer=credential_signer)
                if res.ok:
                    credential_map[src] = dst
                else:
                    credential_errors.append(f"{src.name}: {res.error}")

        # 步骤 1: 计算文件哈希并构建 Merkle Tree
        if progress_callback:
            progress_callback(0, len(file_paths), "正在计算文件哈希...")

        def hash_progress(current, total):
            if progress_callback:
                progress_callback(current, total, f"计算哈希: {current}/{total}")

        if pdf_report and pdf_report.exists():
            zipf.write(pdf_report, "VerificationReport.pdf")

        # 5. 原始作品文件 → works/ 目录
        # Use indexed filenames (e.g. works/000_photo.jpg) to avoid collisions
        # when multiple source files share the same basename.  Must match the
        # indexed keys in manifest_data['works_map'].
        if source_files:
            for idx, file_path in enumerate(source_files):
                if isinstance(file_path, str):
                    file_path = Path(file_path)
                if file_path.exists() and file_path.is_file():
                    zipf.write(file_path, f"works/{idx:03d}_{file_path.name}")

        # 6. 添加额外文件
        if additional_files:
            for file_path in additional_files:
                if file_path.exists():
                    zipf.write(file_path, f"additional/{file_path.name}")

    def calculate_package_hash(self) -> str:
        """
        计算 .nep 文件包的哈希值（用于验证）

        Returns:
            文件包的 SHA256 哈希值
        """
        if not self.output_path.exists():
            raise ValueError(f"文件包不存在: {self.output_path}")

        hash_obj = hashlib.sha256()
        with open(self.output_path, "rb") as f:
            for chunk in iter(lambda: f.read(4096), b""):
                hash_obj.update(chunk)

        return hash_obj.hexdigest()

                result["timestamp_file"] = str(local_ts_path)
                result["message"] += f"，本地时间戳已保存: {local_ts_filename}（建议安装 rfc3161ng 以获取权威时间戳）"
        except OSError as e:
            result["message"] += f"（时间戳文件保存失败: {e}）"

    return result


def verify_timestamp_file(file_path: Path) -> Tuple[bool, Dict]:
    """
    验证时间戳文件（便捷方法，仅结构验证）

    支持 .tsr/.tsa (RFC 3161) 和 .json (本地时间戳) 格式。

    Args:
        file_path: .tsr/.tsa 或 .json 时间戳文件路径

    Returns:
        (是否有效, 验证结果字典)
    """
    try:
        result = parse_tsr(file_path)
        return result.get("valid", False), result
    except RightsError as e:
        return False, {"valid": False, "message": str(e)}
    except Exception as e:
        return False, {"valid": False, "message": f"验证失败: {str(e)}"}


def verify_evidence_package(
    tsa_path: Path,
    file_paths: List[Path],
    manifest_data: Optional[Dict] = None,
) -> Tuple[bool, Dict]:
    """
    深度验证存证包：重算文件哈希 → 重建 Merkle Tree → 与 TSR 中签名的哈希比对。

    验证链路:
      v1: 文件列表 → Merkle Root → TSA
      v2: 文件列表 → Merkle Root → 完整清单摘要 → TSA

    Args:
        tsa_path: .tsa/.tsr 时间戳文件路径
        file_paths: 被存证的原始文件路径列表（顺序必须与存证时一致）
        manifest_data: v2 存证必须提供完整清单；v1 可省略，仅验证文件

    Returns:
        (是否通过, 验证结果字典)
    """
    from .utils import build_merkle_tree_from_files

    if not tsa_path.exists():
        return False, {"valid": False, "message": f"时间戳文件不存在: {tsa_path}"}

    missing = [str(p) for p in file_paths if not p.exists()]
    if missing:
        return False, {"valid": False, "message": f"原始文件缺失: {', '.join(missing)}"}

    try:
        # Step 1: 重算文件哈希，重建 Merkle Tree
        tree = build_merkle_tree_from_files(file_paths)
        computed_root = tree.root_hash
        expected_hash = computed_root
        metadata_bound = False
        if manifest_data is not None:
            from .certification_manifest import certification_binding

            binding = certification_binding(manifest_data)
            if list(tree.file_hashes.values()) != list(manifest_data.get("file_hashes", {}).values()):
                raise ValueError("原始文件与清单中的文件列表不匹配")
            if computed_root != manifest_data.get("merkle_root"):
                raise ValueError("文件 Merkle Root 与清单不匹配")
            if binding == "manifest-sha256-v1":
                expected_hash = manifest_data["manifest_sha256"]
                metadata_bound = True

        # Step 2: 检查是否为本地时间戳（无第三方签名，不具备证明力）
        suffix = tsa_path.suffix.lower()
        if suffix == ".json":
            tsr_result = parse_tsr(tsa_path)
            tsr_hash = tsr_result.get("hash", tsr_result.get("work_identity", ""))
            if expected_hash.lower() == tsr_hash.lower():
                return False, {
                    "valid": False,
                    "message": "本地时间戳无第三方签名，不具备密码学证明力。文件哈希一致但无法证明时间。",
                    "root_hash": computed_root,
                    "metadata_bound": False,
                    "local_only": True,
                    "file_count": len(file_paths),
                }
            else:
                return False, {
                    "valid": False,
                    "message": "验证失败：存证摘要与本地时间戳记录不匹配",
                    "computed_root": computed_root,
                    "file_count": len(file_paths),
                }

        # Step 3: RFC 3161 TSR — 完整性比对 + TSA 签名与证书链验证 (tsa_verify)
        computed_digest = bytes.fromhex(expected_hash)
        try:
            from .tsa_client import TSAClient

            tsa_client = TSAClient()
            verify_result = tsa_client.verify_tsr(tsa_path, digest=computed_digest)

            if verify_result.get("valid"):
                # 同时解析 TSR 获取时间戳详情（签发时间、签发方）

                        width: w,
                        height: h
                    });
                }
                return results;
            }
        """,
            min_size,
        )

        # 去重 + CDN URL 升级（缩略图 → 大图）
        seen = set()
        unique = []
        for img in images:
            src = img["src"]

            ensure_ascii=False,
            sort_keys=True,
            separators=(",", ":"),
            default=str,
        )
        manifest_sha256 = hashlib.sha256(manifest_json.encode("utf-8")).hexdigest()
        manifest["manifest_sha256"] = manifest_sha256
        manifest["manifest_sha256_note"] = (
            "To verify: remove 'manifest_sha256' and 'manifest_sha256_note' keys, "
            "json.dumps(sort_keys=True, ensure_ascii=False, separators=(',', ':')), "
            "SHA-256 the UTF-8 bytes."
        )

        # Write manifest to disk.
        # NOTE: We intentionally do NOT write a separate manifest_canonical.json.
        # The canonical form is reproducible by any verifier: remove "manifest_sha256"
        # and "manifest_sha256_note" keys, then json.dumps(sort_keys=True,
        # ensure_ascii=False) and SHA-256 the UTF-8 bytes.  Writing it as a separate
        # file would be redundant and was previously included in the .nep archive
        # without being tracked in file_hashes (circular dependency).
        manifest_path = self._output_dir / "manifest.json"
        with open(manifest_path, "w", encoding="utf-8") as f:
            json.dump(manifest, f, indent=2, ensure_ascii=False, default=str)

        self._record(f"Manifest saved (sha256={manifest_sha256[:16]}...)")
        return manifest

    # ===== Step 8: Timestamp =====

    def timestamp_manifest(self, manifest: Dict) -> Dict:
        """Request RFC 3161 timestamp for the manifest hash."""
        manifest_sha256 = manifest.get("manifest_sha256", "")
        if not manifest_sha256:
            self._record("No manifest hash to timestamp")
            return {"success": False, "message": "No manifest hash"}

        self._record("Requesting RFC 3161 timestamp for manifest")
        tsa_path = self._output_dir / "manifest.tsa"

        try:
            from .tsa_client import TSAClient

            client = TSAClient(
                provider=self._tsa_provider,
                timeout=self._tsa_timeout,
            )
            result = client.timestamp_hash(manifest_sha256, tsa_path)
            if result.get("success"):
                self._record(f"TSA timestamp obtained: {result.get('issuer')}")
                return {
                    "success": True,
                    "tsa_path": str(tsa_path),
                    "timestamp": result.get("timestamp"),
                    "issuer": result.get("issuer"),
                }
            else:
                self._record(f"TSA failed: {result.get('message')}")
        except Exception as e:
            self._record(f"TSA error: {e}")

        # Fallback: local timestamp
        local_ts = {
            "type": "local_timestamp",
            "timestamp": datetime.now(timezone.utc).isoformat(),
            "manifest_sha256": manifest_sha256,
            "note": "TSA unavailable, local timestamp only",
        }
        local_path = self._output_dir / "manifest_timestamp.json"
        with open(local_path, "w", encoding="utf-8") as f:
            json.dump(local_ts, f, indent=2, ensure_ascii=False)

        self._record("Falling back to local timestamp")
        return {
            "success": True,
            "tsa_path": str(local_path),
            "timestamp": local_ts["timestamp"],
            "issuer": "Nephele Workshop (local)",
            "local_only": True,
        }

    # ===== Step 9: Save operation log =====

    def save_log(self) -> str:
        """Write the operation log to file."""
        log_path = self._output_dir / "operation_log.txt"
        with open(log_path, "w", encoding="utf-8") as f:
            f.write("Nephele Workshop - URL Evidence Capture Log\n")
            f.write(f"Evidence ID: {self._evidence_id}\n")
            f.write("=" * 60 + "\n\n")
            for entry in self._log:
                f.write(entry + "\n")
        return str(log_path)

    # ===== Orchestrator =====

    def capture(
        self,
        url: str,
        progress_callback=None,
    ) -> Dict:
        """
        Execute the full URL evidence capture pipeline.

        Args:
            url: Target URL to capture
            progress_callback: Optional (step, total, message) callback

        Returns:
            {
                "success": bool,
                "evidence_id": str,
                "output_dir": str,
                "manifest": dict,
                "timestamp_info": dict,
                "message": str,
            }
        """
        total_phases = 5
        self._record(f"Starting evidence capture for: {url}")

        try:
            # Phase 1: Environment + DNS + TLS certificate
            if progress_callback:
                progress_callback(1, total_phases, "Collecting environment info...")
            environment = self.collect_environment()
            dns_info = self.resolve_dns(url)
            tls_info = self.capture_tls_certificate(url)

            # Phase 2: Browser capture (navigate + screenshot + HTML + images)
            if progress_callback:
                progress_callback(2, total_phases, "Capturing page...")
            artifacts = self.capture_page(url, progress_callback=None)

            # Phase 3: Hash all artifacts (including TLS cert files)
            if progress_callback:

        return env

    # ===== Step 1b: TLS certificate =====

    def capture_tls_certificate(self, url: str) -> Dict:
        """
        Capture the server's TLS certificate chain.
        This proves the connection was made to the authentic server —
        you can't forge a CA-signed certificate.
        """
        import ssl
        from urllib.parse import urlparse

        self._record("Capturing TLS server certificate")
        parsed = urlparse(url if "://" in url else f"https://{url}")
        hostname = parsed.hostname or ""
        port = parsed.port or 443

        if not hostname:
            return {"error": "Invalid hostname"}

        try:
            ctx = ssl.create_default_context()
            with ctx.wrap_socket(
                socket.socket(socket.AF_INET, socket.SOCK_STREAM),
                server_hostname=hostname,
            ) as sock:
                sock.settimeout(10)
                sock.connect((hostname, port))
                cert = sock.getpeercert()
                cert_der = sock.getpeercert(binary_form=True)

            # Save DER certificate to file
            cert_path = self._output_dir / "server_certificate.der"
            cert_path.write_bytes(cert_der)

            # Also save human-readable PEM
            import base64

            pem_data = (
                "-----BEGIN CERTIFICATE-----\n" + base64.encodebytes(cert_der).decode() + "-----END CERTIFICATE-----\n"
            )
            pem_path = self._output_dir / "server_certificate.pem"
            pem_path.write_text(pem_data, encoding="utf-8")

            # Extract key fields
            subject = dict(x[0] for x in cert.get("subject", ()))
            issuer = dict(x[0] for x in cert.get("issuer", ()))
            cert_info = {
                "subject_cn": subject.get("commonName", ""),
                "issuer_cn": issuer.get("commonName", ""),
                "issuer_org": issuer.get("organizationName", ""),
                "not_before": cert.get("notBefore", ""),
                "not_after": cert.get("notAfter", ""),
                "serial_number": cert.get("serialNumber", ""),
                "san": [entry[1] for entry in cert.get("subjectAltName", ()) if entry[0] == "DNS"],
                "der_path": str(cert_path),
                "pem_path": str(pem_path),
                "der_sha256": hashlib.sha256(cert_der).hexdigest(),
            }

            self._record(
                f"TLS cert captured: {cert_info['subject_cn']} "
                f"(issuer: {cert_info['issuer_org']}, "
                f"serial: {cert_info['serial_number'][:16]}...)"
            )
            return cert_info

        except Exception as e:
            self._record(f"TLS certificate capture failed: {e}")
            return {"error": str(e)}

    # ===== Step 2: DNS resolution =====

    def resolve_dns(self, url: str) -> Dict:

    _CAPTCHA_KEYWORDS = (
        "验证码",
        "验证",
        "captcha",
        "verify",
        "challenge",
        "human verification",
        "robot",
        "机器人",
    )

    def _is_captcha_page(self, title: str, url: str) -> bool:
        """Detect if the loaded page is a CAPTCHA or anti-bot challenge."""
        text = (title or "").lower()

"""Local invisible watermarks with authenticated payloads and legacy extraction."""

import hashlib
import hmac
import logging
import os
import secrets
import tempfile
from enum import Enum
from pathlib import Path
from typing import Optional, Tuple

import numpy as np
from PIL import Image

from . import watermark_keys as keys
from .watermark_keys import WatermarkError
from .watermark_keys import export_watermark_keys as export_watermark_keys
from .watermark_keys import import_watermark_keys as import_watermark_keys

logger = logging.getLogger(__name__)

WATERMARK_BYTES = 32
WATERMARK_BITS = WATERMARK_BYTES * 8
_V2_MAGIC = b"NW\x02"
# Header (3), mark ID (12), text length (1), UTF-8 text (32), HMAC tag (16).
_V2_BYTES = 64
_V2_BITS = _V2_BYTES * 8
_LEGACY_PASSWORD_IMG = 2024
_LEGACY_PASSWORD_WM = 1314
_user_seeds_cache: Optional[Tuple[int, int]] = None


def _seed_file() -> Path:
    return keys.seed_file()


def _get_user_seeds() -> Tuple[int, int]:
    global _user_seeds_cache
    key = keys.load_store(create=True)["keys"][0]
    _user_seeds_cache = (key["password_img"], key["password_wm"])
    return _user_seeds_cache


class ProtectionLevel(Enum):
    NONE = "none"
    INVISIBLE = "invisible"


LEVEL_ALIASES = {"maximum": "invisible"}


def _label_bytes(text: str) -> bytes:
    if not text.strip() or any(not ch.isprintable() for ch in text):
        raise WatermarkError("水印署名不能为空或包含控制字符")
    raw = text.encode("utf-8")
    if len(raw) > WATERMARK_BYTES:
        raise WatermarkError("水印署名最多 32 个 UTF-8 字节（通常为 10 个汉字或 32 个英文字母）")
    return raw


def _bytes_to_bits(raw: bytes) -> list[int]:
    return np.unpackbits(np.frombuffer(raw, dtype=np.uint8)).tolist()


def _bits_to_bytes(bits: list) -> bytes:
    values = np.asarray(bits).reshape(-1) > 0.5

def _text_to_bits(text: str) -> list[int]:
    return _bytes_to_bits(_label_bytes(text).ljust(WATERMARK_BYTES, b"\x00"))


def _bits_to_text(bits: list) -> str:
    return _bits_to_bytes(bits).rstrip(b"\x00").decode("utf-8", errors="replace")


def _bits_to_valid_text(bits: list) -> Optional[str]:
    """Best-effort legacy text; this format has no authentication."""
    prefix = _bits_to_bytes(bits).split(b"\x00", 1)[0]
    if len(prefix) < 2:
        return None
    try:
        text = prefix.decode("utf-8").strip()
    except UnicodeDecodeError:
        return None
    return text if text and all(ch.isprintable() for ch in text) else None


def _make_payload(text: str, key: dict) -> bytes:
    label = _label_bytes(text)
    body = _V2_MAGIC + secrets.token_bytes(12) + bytes([len(label)]) + label.ljust(WATERMARK_BYTES, b"\x00")
    tag = hmac.new(bytes.fromhex(key["auth_key"]), body, hashlib.sha256).digest()[:16]
    return body + tag


def _read_payload(raw: bytes, key: dict) -> dict | None:
    if len(raw) != _V2_BYTES or not raw.startswith(_V2_MAGIC) or not key.get("auth_key"):
        return None
    expected = hmac.new(bytes.fromhex(key["auth_key"]), raw[:48], hashlib.sha256).digest()[:16]
    if not hmac.compare_digest(raw[48:], expected):
        return None
    size = raw[15]
    if not 0 < size <= WATERMARK_BYTES or any(raw[16 + size : 48]):
        return None
    try:
        label = raw[16 : 16 + size].decode("utf-8")
        _label_bytes(label)
    except (UnicodeDecodeError, WatermarkError):
        return None
    return {
        "status": "verified",
        "text": label,
        "mark_id": raw[3:15].hex(),
        "message": "水印认证校验通过；该结果不代表原创或作者身份认证",
    }


def _bgr(image: Image.Image) -> np.ndarray:
    # OpenCV's filename APIs cannot read Windows CJK paths.
    return np.asarray(image.convert("RGB"))[:, :, ::-1].copy()

def _extract_bits(image: Image.Image, key: dict, bit_count: int) -> list:
    from blind_watermark import WaterMark

    engine = WaterMark(password_img=key["password_img"], password_wm=key["password_wm"])
    return engine.extract(embed_img=_bgr(image), wm_shape=bit_count, mode="bit")


def _capacity(image: Image.Image) -> int:
    return ((image.width + 1) // 8) * ((image.height + 1) // 8)


class WatermarkEngine:
    def embed(self, image: Image.Image, text: str) -> Image.Image:
        """Authenticate the quantized pixels; never return an unmarked fallback."""
        _label_bytes(text)
        if _capacity(image) <= _V2_BITS:
            raise WatermarkError("图片尺寸不足以嵌入隐形水印，请使用更大的图片")
        try:
            from blind_watermark import WaterMark

            key = keys.load_store(create=True)["keys"][0]

            payload = _make_payload(text, key)
            engine = WaterMark(password_img=key["password_img"], password_wm=key["password_wm"])
            engine.read_img(img=_bgr(image))
            engine.read_wm(np.asarray(_bytes_to_bits(payload)), mode="bit")
            pixels = np.rint(engine.embed()).clip(0, 255).astype(np.uint8)
            result = Image.fromarray(pixels[:, :, ::-1].copy())
            if image.mode == "RGBA":
                result = result.convert("RGBA")
                result.putalpha(image.getchannel("A"))
            recovered = _bits_to_bytes(_extract_bits(result, key, _V2_BITS))
            if not hmac.compare_digest(recovered, payload):
                raise WatermarkError("隐形水印回读校验失败，图片未导出")
            result.info["nephele_watermark"] = {"payload": payload, "key": key}
            return result
        except WatermarkError:
            raise
        except Exception as exc:
            logger.exception("Invisible watermark embedding failed")
            raise WatermarkError("隐形水印嵌入失败，图片未导出") from exc

    def extract(self, image: Image.Image) -> Optional[str]:
        result = inspect_watermark(image)

def pack_image(
    input_path: str,
    watermark_path: Optional[str] = None,
    output_dir: Optional[str] = None,
    watermark_mode: str = "center",
    watermark_opacity: float = 0.3,
    preview_max_size: int = 1920,
    thumbnail_max_size: int = 500,
    protection_level: str = "none",
    copyright_info: str = "© ArisFusion Studio",
    output_folder_name: str = "Delivery_Pack",
) -> dict:
    """Burn a visible watermark + creator declaration onto the image (single output).

    The old multi-size delivery export (HD/preview/thumbnail) was removed; the
    preview_max_size / thumbnail_max_size args are legacy no-ops kept for signature
    compatibility — process_image now writes one file.
    """
    try:
        src = Path(input_path)
        if not src.exists():
            return api_err(f"文件不存在: {input_path}")

        mode_map = {"center": WatermarkMode.CENTER, "tile": WatermarkMode.TILE}
        wm_mode = mode_map.get(watermark_mode, WatermarkMode.CENTER)

        wm_path = Path(watermark_path) if watermark_path else None
        if wm_path and not wm_path.exists():
            return api_err(f"水印文件不存在: {watermark_path}")

        out_dir = Path(output_dir) if output_dir else None

        packer = DeliveryPacker(
            preview_max_size=preview_max_size,
            thumbnail_max_size=thumbnail_max_size,
            watermark_opacity=watermark_opacity,
            protection_level=protection_level,
            copyright_info=copyright_info,
            output_folder_name=output_folder_name,
        )

        result_dir, results = packer.process_image(
            input_path=src,
            watermark_path=wm_path,
            output_dir=out_dir,
            watermark_mode=wm_mode,
        )

        file_info = {k: str(v) for k, v in results.items()}
        return api_ok(
            f"打包完成，共生成 {len(results)} 个文件",
            output_path=str(result_dir),
            data={"files": file_info},
        )

    except PackerError as e:
        logger.error("打包失败: %s", e)
        return api_err(str(e))

"""Background watermark inspection and encrypted key backup."""

import json
import logging
from pathlib import Path

from PySide6.QtCore import QT_TRANSLATE_NOOP, QCoreApplication, QThread, QUrl, Signal

from .._utils import ensure_src_path

logger = logging.getLogger(__name__)


# Keep dynamically translated headless errors discoverable by lupdate.
_WATERMARK_ERROR_MESSAGES = (
    QT_TRANSLATE_NOOP("WatermarkError", "水印署名不能为空或包含控制字符"),
    QT_TRANSLATE_NOOP("WatermarkError", "水印署名最多 32 个 UTF-8 字节（通常为 10 个汉字或 32 个英文字母）"),
    QT_TRANSLATE_NOOP("WatermarkError", "图片尺寸不足以嵌入隐形水印，请使用更大的图片"),
    QT_TRANSLATE_NOOP("WatermarkError", "隐形水印回读校验失败，图片未导出"),
    QT_TRANSLATE_NOOP("WatermarkError", "隐形水印嵌入失败，图片未导出"),
    QT_TRANSLATE_NOOP("WatermarkError", "水印提取器运行失败，无法判断图片是否含有水印"),
    QT_TRANSLATE_NOOP("WatermarkError", "不支持的水印保护级别"),
    QT_TRANSLATE_NOOP("WatermarkError", "导出文件的水印校验失败，原有文件已保留"),
    QT_TRANSLATE_NOOP("WatermarkError", "图片保存失败，请检查输出位置；原有文件已保留"),
    QT_TRANSLATE_NOOP("WatermarkError", "水印密钥无法读取或保存，请从备份恢复；原密钥文件已保留"),
    QT_TRANSLATE_NOOP("WatermarkError", "水印密钥已变化，请重新导出图片"),
    QT_TRANSLATE_NOOP("WatermarkError", "无法保存水印记录，图片尚未导出"),
    QT_TRANSLATE_NOOP("WatermarkError", "请输入密钥备份密码"),
    QT_TRANSLATE_NOOP("WatermarkError", "备份文件不能覆盖正在使用的水印密钥"),
    QT_TRANSLATE_NOOP("WatermarkError", "备份密码至少需要 8 个字符"),
    QT_TRANSLATE_NOOP("WatermarkError", "水印密钥备份失败，请检查保存位置"),
    QT_TRANSLATE_NOOP("WatermarkError", "备份无法解密：请检查密码和备份文件"),
    QT_TRANSLATE_NOOP("WatermarkError", "无法保留原密钥文件，恢复已停止"),
    QT_TRANSLATE_NOOP("WatermarkError", "无法保存恢复的水印密钥"),
)


def watermark_error_text(error: Exception) -> str:
    """Localize known watermark failures at the Qt boundary."""
    from tools.packer.watermark_keys import WatermarkError

    current = error
    while current is not None:
        if isinstance(current, WatermarkError):
            return QCoreApplication.translate("WatermarkError", str(current))
        current = current.__cause__ or current.__context__
    return str(error)