cookiecloud-decrypt 0.1.0__py3-none-any.whl

cookiecloud_decrypt/__init__.py

@@ -0,0 +1,61 @@
+"""
+cookiecloud_decrypt
+~~~~~~~~~~~~~~~~~~
+
+CookieCloud 数据解密 SDK。
+
+支持两种加密模式：
+
+- **aes-128-cbc-fixed**: 新版 CookieCloud 服务器（MD5(key) + 零 IV）
+- **legacy**:           旧版（MD5 chain + Salted__ header，兼容 pycookiecloud）
+
+用法::
+
+    from cookiecloud_decrypt import decrypt, to_playwright_cookies, to_cookie_str
+
+    # 解密
+    data = decrypt(encrypted="BASE64STRING...", uuid="...", password="...")
+
+    # Playwright 格式
+    cookies = to_playwright_cookies(data, domains=[".example.com"])
+
+    # "k1=v1; k2=v2" 格式
+    cookie_str = to_cookie_str(data, domain="example.com", keys=["a1", "b2"])
+"""
+
+from .decrypt import (
+    decrypt,
+    encrypt_legacy,
+    encrypt_aes_128_cbc_fixed,
+    DecryptMode,
+    CookieCloudDecryptError,
+    InvalidKeyError,
+    CorruptedDataError,
+)
+from .format import (
+    to_cookie_dict,
+    to_playwright_cookies,
+    to_cookie_str,
+)
+from .models import (
+    CookieEntry,
+    CookieCloudData,
+)
+
+__all__ = [
+    # 解密
+    "decrypt",
+    "encrypt_legacy",
+    "encrypt_aes_128_cbc_fixed",
+    "DecryptMode",
+    "CookieCloudDecryptError",
+    "InvalidKeyError",
+    "CorruptedDataError",
+    # 格式化
+    "to_cookie_dict",
+    "to_playwright_cookies",
+    "to_cookie_str",
+    # 类型
+    "CookieEntry",
+    "CookieCloudData",
+]

cookiecloud_decrypt/decrypt.py

@@ -0,0 +1,309 @@
+"""
+CookieCloud 数据解密核心实现。
+
+支持两种加密模式：
+- aes-128-cbc-fixed: 新版 CookieCloud 服务器（MD5(key) + 零 IV）
+- legacy:           旧版使用（MD5 chain + Salted__ header，兼容 pycookiecloud）
+
+加密流程由 CookieCloud 服务端完成，参考：
+https://github.com/easychen/CookieCloud
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from enum import Enum
+from typing import Any
+
+from Cryptodome.Cipher import AES
+from Cryptodome.Util.Padding import unpad
+
+
+class DecryptMode(str, Enum):
+    """解密模式。"""
+    LEGACY = "legacy"
+    """旧版模式：MD5 chain + Salted__ header，与 pycookiecloud 兼容。"""
+    AES_128_CBC_FIXED = "aes-128-cbc-fixed"
+    """新版模式：MD5(key) + 零 IV。"""
+    AUTO = "auto"
+    """自动检测：优先尝试 aes-128-cbc-fixed，再尝试 legacy。"""
+
+
+class CookieCloudDecryptError(Exception):
+    """解密失败基类。"""
+    pass
+
+
+class InvalidKeyError(CookieCloudDecryptError):
+    """密钥错误（密码/UUID 不正确）。"""
+    pass
+
+
+class CorruptedDataError(CookieCloudDecryptError):
+    """数据损坏（密文格式异常）。"""
+    pass
+
+
+# ---------------------------------------------------------------------------
+# 内部工具
+# ---------------------------------------------------------------------------
+
+SALTED_HEADER = b"Salted__"
+"""OpenSSL salted format header (legacy 模式)。"""
+
+
+def _derive_key_md5(data: bytes, salt: bytes, output: int = 48) -> bytes:
+    """
+    MD5 chain key derivation — legacy 模式使用。
+    等价于 OpenSSL EVP_BytesToKey(MD5)。
+
+    Args:
+        data: 初始种子（通常是 key + salt）
+        salt: 8 字节盐
+        output: 需要输出的总字节数
+
+    Returns:
+        key || iv (前 32 字节为 key，后 16 字节为 IV)
+    """
+    result = b""
+    prev = b""
+    while len(result) < output:
+        prev = hashlib.md5(prev + data + salt).digest()
+        result += prev
+    return result[:output]
+
+
+def _derive_key_fixed(key: str) -> bytes:
+    """
+    MD5(key) key derivation — aes-128-cbc-fixed 模式使用。
+
+    Args:
+        key: UUID + '-' + password 的 MD5 十六进制字符串的前 16 字符
+
+    Returns:
+        16 字节密钥
+    """
+    return hashlib.md5(key.encode()).digest()
+
+
+# ---------------------------------------------------------------------------
+# 加密函数（测试用，生产环境不需要）
+# ---------------------------------------------------------------------------
+
+def encrypt_legacy(plaintext: str, uuid: str, password: str) -> str:
+    """
+    用 legacy 模式加密数据（用于生成测试 fixture）。
+    流程与 CookieCloud 服务端一致。
+
+    Args:
+        plaintext: JSON 字符串
+        uuid: CookieCloud UUID
+        password: CookieCloud 密码
+
+    Returns:
+        base64 编码后的密文
+    """
+    import os
+
+    key_str = f"{uuid}-{password}"
+    hash_hex = hashlib.md5(key_str.encode()).hexdigest()
+    key = hash_hex[:16].encode()
+
+    salt = os.urandom(8)
+    key_iv = _derive_key_md5(key, salt, output=48)
+    aes_key, aes_iv = key_iv[:32], key_iv[32:]
+
+    padded = _pad(plaintext.encode("utf-8"))
+    cipher = AES.new(aes_key, AES.MODE_CBC, aes_iv)
+    ciphertext = cipher.encrypt(padded)
+
+    return base64.b64encode(b"Salted__" + salt + ciphertext).decode()
+
+
+def encrypt_aes_128_cbc_fixed(plaintext: str, uuid: str, password: str) -> str:
+    """
+    用 aes-128-cbc-fixed 模式加密数据（用于生成测试 fixture）。
+
+    Args:
+        plaintext: JSON 字符串
+        uuid: CookieCloud UUID
+        password: CookieCloud 密码
+
+    Returns:
+        base64 编码后的密文
+    """
+    import os
+
+    key_str = f"{uuid}-{password}"
+    hash_hex = hashlib.md5(key_str.encode()).hexdigest()
+    key = hash_hex[:16].encode()
+
+    aes_key = _derive_key_fixed(key_str)
+    zero_iv = b"\x00" * 16
+
+    padded = _pad(plaintext.encode("utf-8"))
+    cipher = AES.new(aes_key, AES.MODE_CBC, zero_iv)
+    ciphertext = cipher.encrypt(padded)
+
+    return base64.b64encode(ciphertext).decode()
+
+
+def _pad(data: bytes) -> bytes:
+    """PKCS#7 padding。"""
+    block_size = 16
+    pad_len = block_size - (len(data) % block_size)
+    return data + bytes([pad_len] * pad_len)
+
+
+# ---------------------------------------------------------------------------
+# 解密函数
+# ---------------------------------------------------------------------------
+
+def _decrypt_legacy(encrypted_b64: str, uuid: str, password: str) -> dict[str, Any]:
+    """
+    用 legacy 模式解密。
+    与 pycookiecloud PyCryptoJS.py 的 decrypt() 完全兼容。
+
+    Raises:
+        CorruptedDataError: 密文格式损坏（Salted__ header 不匹配）
+        InvalidKeyError: 密钥错误（解密后不是合法 JSON）
+    """
+    try:
+        encrypted = base64.b64decode(encrypted_b64)
+    except Exception as e:
+        raise CorruptedDataError(f"base64 decode failed: {e}") from e
+
+    if not encrypted.startswith(SALTED_HEADER):
+        raise CorruptedDataError(
+            f"Missing OpenSSL salted header. Expected {SALTED_HEADER!r}, "
+            f"got {encrypted[:8]!r}. Data may use aes-128-cbc-fixed mode instead."
+        )
+
+    salt = encrypted[8:16]
+    ciphertext = encrypted[16:]
+
+    key_str = f"{uuid}-{password}"
+    hash_hex = hashlib.md5(key_str.encode()).hexdigest()
+    key = hash_hex[:16].encode()
+
+    key_iv = _derive_key_md5(key, salt, output=48)
+    aes_key, aes_iv = key_iv[:32], key_iv[32:]
+
+    try:
+        cipher = AES.new(aes_key, AES.MODE_CBC, aes_iv)
+        padded = cipher.decrypt(ciphertext)
+        plaintext = unpad(padded, AES.block_size)
+        return json.loads(plaintext.decode("utf-8"))
+    except (ValueError, json.JSONDecodeError) as e:
+        raise InvalidKeyError(
+            f"Decryption failed — wrong key or corrupted data. "
+            f"Verify uuid and password are correct. Cause: {e}"
+        ) from e
+
+
+def _decrypt_aes_128_cbc_fixed(encrypted_b64: str, uuid: str, password: str) -> dict[str, Any]:
+    """
+    用 aes-128-cbc-fixed 模式解密。
+    新版 CookieCloud 服务器使用此模式。
+
+    Raises:
+        CorruptedDataError: 密文格式损坏（长度不是 16 的倍数）
+        InvalidKeyError: 密钥错误（解密后不是合法 JSON）
+    """
+    try:
+        encrypted = base64.b64decode(encrypted_b64)
+    except Exception as e:
+        raise CorruptedDataError(f"base64 decode failed: {e}") from e
+
+    if len(encrypted) % 16 != 0:
+        raise CorruptedDataError(
+            f"Encrypted data length ({len(encrypted)}) is not a multiple of 16. "
+            f"Data may use legacy mode instead."
+        )
+
+    key_str = f"{uuid}-{password}"
+    aes_key = _derive_key_fixed(key_str)
+    zero_iv = b"\x00" * 16
+
+    try:
+        cipher = AES.new(aes_key, AES.MODE_CBC, zero_iv)
+        padded = cipher.decrypt(encrypted)
+        plaintext = unpad(padded, AES.block_size)
+        return json.loads(plaintext.decode("utf-8"))
+    except (ValueError, json.JSONDecodeError) as e:
+        # ValueError 可能是：1) wrong key（解密内容非合法 PKCS#7），
+        # 2) wrong format（legacy 数据用 fixed 模式解密）。
+        # 用 Salted__ header 区分：legacy 格式有 header，fixed 没有。
+        # 若有 header 说明是 legacy 格式未匹配，转 CorruptedDataError 以便 auto fallback；
+        # 否则视为密钥错误。
+        if encrypted.startswith(SALTED_HEADER):
+            raise CorruptedDataError(
+                f"Data has OpenSSL salted header — appears to be legacy format. "
+                f"Retry with mode='legacy'."
+            ) from e
+        raise InvalidKeyError(
+            f"Decryption failed — wrong key or corrupted data. "
+            f"Verify uuid and password are correct. Cause: {e}"
+        ) from e
+
+
+def decrypt(
+    encrypted: str,
+    uuid: str,
+    password: str,
+    mode: DecryptMode | str = DecryptMode.AUTO,
+) -> dict[str, Any]:
+    """
+    解密 CookieCloud 服务端返回的加密数据。
+
+    Args:
+        encrypted: CookieCloud GET /get/{uuid} 返回的 ``encrypted`` 字段（base64）
+        uuid: CookieCloud UUID
+        password: CookieCloud 密码
+        mode: 解密模式，默认 auto（自动检测）
+
+            - ``"auto"``: 优先尝试 aes-128-cbc-fixed，再尝试 legacy
+            - ``"legacy"``: 仅使用 legacy 模式（兼容 pycookiecloud）
+            - ``"aes-128-cbc-fixed"``: 仅使用新版模式
+
+    Returns:
+        解密后的原始 JSON dict（含 ``cookie_data`` 等顶层字段）
+
+    Raises:
+        CookieCloudDecryptError: 解密失败
+        InvalidKeyError: 密钥错误（uuid 或 password 不正确）
+        CorruptedDataError: 密文格式损坏
+
+    Example::
+
+        from cookiecloud_decrypt import decrypt
+
+        data = decrypt(
+            encrypted="BASE64STRING...",
+            uuid="your-uuid",
+            password="your-password",
+        )
+        cookie_dict = data["cookie_data"]
+    """
+    if isinstance(mode, str):
+        mode = DecryptMode(mode.lower())
+
+    if mode == DecryptMode.AUTO:
+        # 优先尝试 aes-128-cbc-fixed（新版）
+        try:
+            return _decrypt_aes_128_cbc_fixed(encrypted, uuid, password)
+        except CorruptedDataError:
+            # 不是 fixed 格式，尝试 legacy
+            return _decrypt_legacy(encrypted, uuid, password)
+        # InvalidKeyError 直接抛出，不 fallback（密钥错误时 legacy 也会失败）
+
+    elif mode == DecryptMode.AES_128_CBC_FIXED:
+        return _decrypt_aes_128_cbc_fixed(encrypted, uuid, password)
+
+    elif mode == DecryptMode.LEGACY:
+        return _decrypt_legacy(encrypted, uuid, password)
+
+    else:
+        raise ValueError(f"Unknown decrypt mode: {mode}")

cookiecloud_decrypt/format.py

@@ -0,0 +1,222 @@
+"""
+CookieCloud 解密结果的格式化工具。
+支持 dict / Playwright add_cookies / "k1=v1; k2=v2" 三种导出格式。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .models import CookieCloudData, CookieEntry
+
+
+# ---------------------------------------------------------------------------
+# 内部工具
+# ---------------------------------------------------------------------------
+
+_COOKIE_PRIORITY_DEFAULT = "Medium"
+"""CookieCloud 默认 priority。"""
+
+_SAME_SITE_DEFAULT = "Lax"
+"""Playwright add_cookies 默认 sameSite。"""
+
+
+# ---------------------------------------------------------------------------
+# 导出函数
+# ---------------------------------------------------------------------------
+
+def to_cookie_dict(
+    data: CookieCloudData,
+    domains: list[str] | None = None,
+    *,
+    unwrap: bool = True,
+) -> dict[str, list[CookieEntry]]:
+    """
+    将解密结果导出为 ``{域名: [CookieEntry, ...]}`` 格式。
+
+    Args:
+        data: :func:`~cookiecloud_decrypt.decrypt` 的返回值
+        domains: 仅导出的域名白名单，默认为全部域名。
+                 支持精确匹配（如 ``"xiaohongshu.com"``）和通配符
+                 （如 ``".xiaohongshu.com"``，以点开头表示匹配该域及子域）。
+        unwrap: 若为 ``True``（默认），自动去掉 ``data["cookie_data"]`` 外层；
+                 若为 ``False``，直接使用原始返回值（不含 ``cookie_data`` 包装）。
+
+    Returns:
+        ``{域名: [CookieEntry, ...]}``
+
+    Example::
+
+        cookie_dict = to_cookie_dict(
+            data,
+            domains=[".xiaohongshu.com", "xiaohongshu.com"],
+        )
+    """
+    cookie_data = data if not unwrap else data.get("cookie_data", data)
+
+    if domains is None:
+        return dict(cookie_data)
+
+    result: dict[str, list[CookieEntry]] = {}
+    for domain in cookie_data:
+        # 域名匹配
+        if not _domain_matches(domain, domains):
+            continue
+        result[domain] = cookie_data[domain]
+
+    return result
+
+
+def to_playwright_cookies(
+    data: CookieCloudData,
+    domains: list[str] | None = None,
+    *,
+    unwrap: bool = True,
+) -> list[dict[str, Any]]:
+    """
+    将解密结果导出为 Playwright ``BrowserContext.add_cookies()`` 所需格式。
+
+    Args:
+        data: :func:`~cookiecloud_decrypt.decrypt` 的返回值
+        domains: 仅导出的域名白名单，默认为全部域名
+        unwrap: 若为 ``True``（默认），自动去掉 ``data["cookie_data"]`` 外层
+
+    Returns:
+        Playwright add_cookies 格式的 cookie 列表::
+
+            [
+                {
+                    "name": "a1",
+                    "value": "xxx",
+                    "domain": "xiaohongshu.com",
+                    "path": "/",
+                    "secure": True,
+                    "httpOnly": False,
+                    "sameSite": "Lax",
+                },
+                ...
+            ]
+
+    Note:
+        Playwright add_cookies 要求 domain 不带前导点。
+        此函数会自动去掉 ``.xiaohongshu.com`` → ``xiaohongshu.com``。
+
+    Example::
+
+        from playwright.async_api import async_playwright
+
+        cookies = to_playwright_cookies(data, domains=[".xiaohongshu.com"])
+        async with async_playwright() as p:
+            ctx = await p.chromium.launch()
+            await ctx.add_cookies(cookies)
+    """
+    cookie_dict = to_cookie_dict(data, domains, unwrap=unwrap)
+
+    result: list[dict[str, Any]] = []
+    for domain, entries in cookie_dict.items():
+        # Playwright 要求 domain 不带前导点
+        playwright_domain = domain.lstrip(".")
+
+        for entry in entries:
+            name = entry.get("name", "")
+            value = entry.get("value", "")
+            if not name:
+                continue
+
+            result.append({
+                "name": name,
+                "value": value,
+                "domain": playwright_domain,
+                "path": entry.get("path", "/"),
+                "secure": entry.get("secure", True),
+                "httpOnly": entry.get("httpOnly", False),
+                "sameSite": entry.get("sameSite") or _SAME_SITE_DEFAULT,
+            })
+
+    return result
+
+
+def to_cookie_str(
+    data: CookieCloudData,
+    domain: str,
+    keys: list[str] | None = None,
+    *,
+    unwrap: bool = True,
+    separator: str = "; ",
+    ends_with_separator: bool = False,
+) -> str:
+    """
+    将解密结果导出为 ``"k1=v1; k2=v2"`` 格式的 cookie 字符串。
+
+    Args:
+        data: :func:`~cookiecloud_decrypt.decrypt` 的返回值
+        domain: 目标域名（如 ``"xiaohongshu.com"`` 或 ``".xiaohongshu.com"``）。
+                 会自动尝试带点和不带点两种形式匹配。
+        keys: 仅导出的 cookie 名称白名单，默认为全部。
+        unwrap: 若为 ``True``（默认），自动去掉 ``data["cookie_data"]`` 外层
+        separator: key=value 对之间的分隔符，默认为 ``"; "``
+        ends_with_separator: 若为 ``True``，结果以分隔符结尾
+
+    Returns:
+        cookie 字符串，如 ``"a1=xxx; web_session=yyy"``
+
+    Example::
+
+        cookie_str = to_cookie_str(
+            data,
+            domain=".xiaohongshu.com",
+            keys=["a1", "web_session"],
+        )
+    """
+    cookie_data = data if not unwrap else data.get("cookie_data", data)
+
+    # 域名匹配
+    entries: list[CookieEntry] = []
+    for d, entry_list in cookie_data.items():
+        if _domain_matches(d, [domain]):
+            entries.extend(entry_list)
+            break  # 匹配到第一个即停止
+
+    if not entries:
+        return ""
+
+    parts: list[str] = []
+    for entry in entries:
+        name = entry.get("name", "")
+        value = entry.get("value", "")
+        if not name:
+            continue
+        if keys is not None and name not in keys:
+            continue
+        parts.append(f"{name}={value}")
+
+    result = separator.join(parts)
+    if ends_with_separator and result and not result.endswith(separator):
+        result += separator
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# 内部工具
+# ---------------------------------------------------------------------------
+
+def _domain_matches(domain: str, patterns: list[str]) -> bool:
+    """
+    判断 domain 是否匹配 patterns 中的任意一个。
+
+    匹配规则：
+    - 精确匹配：``"xiaohongshu.com"`` 匹配 ``"xiaohongshu.com"``
+    - 带点前缀：``".xiaohongshu.com"`` 匹配 ``"xiaohongshu.com"`` 及所有子域
+    - 子域匹配：``"www.xiaohongshu.com"`` 匹配 ``".xiaohongshu.com"``
+    """
+    domain_clean = domain.lstrip(".")
+
+    for pattern in patterns:
+        pattern_clean = pattern.lstrip(".")
+        if pattern_clean == domain_clean:
+            return True
+        if pattern.startswith(".") and domain.endswith(pattern_clean):
+            return True
+
+    return False

cookiecloud_decrypt/models.py

@@ -0,0 +1,40 @@
+"""
+CookieCloud 数据类型定义。
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+
+class CookieEntry(TypedDict, total=False):
+    """CookieCloud 返回的单条 Cookie 条目。"""
+    name: str
+    value: str
+    domain: str
+    path: str
+    expires: int
+    size: int
+    httpOnly: bool
+    secure: bool
+    sameSite: str
+    session: bool
+    priority: str
+    sameParty: bool
+    sourceScheme: str
+    sourcePort: int
+
+
+# CookieCloud 原始解密结果结构（最外层 JSON）
+CookieCloudData = dict[str, Any]
+"""
+解密后的完整 JSON dict，结构为::
+
+    {
+        "cookie_data": {
+            ".example.com": [CookieEntry, ...],
+            "www.example.com": [CookieEntry, ...],
+        },
+        "update_time": 1234567890
+    }
+"""

cookiecloud_decrypt-0.1.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: cookiecloud_decrypt
+Version: 0.1.0
+Summary: CookieCloud data decryption SDK — supports legacy and aes-128-cbc-fixed modes
+Author-email: cky <cky@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/YOUR_USERNAME/cookiecloud_decrypt
+Project-URL: Repository, https://github.com/YOUR_USERNAME/cookiecloud_decrypt
+Keywords: cookiecloud,cookie,decrypt,web-scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pycryptodome>=3.19
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-vcr>=1.0; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: python-dotenv>=1.0; extra == "dev"
+
+# cookiecloud_decrypt
+
+CookieCloud 数据解密 SDK，纯 Python，无其他运行时依赖。
+
+支持两种加密模式：
+
+- **aes-128-cbc-fixed**：新版 CookieCloud 服务器（MD5(key) + 零 IV）
+- **legacy**：旧版使用（MD5 chain + Salted__ header，与 pycookiecloud 兼容）
+
+## 安装
+
+```bash
+pip install cookiecloud_decrypt
+```
+
+## 快速开始
+
+```python
+from cookiecloud_decrypt import decrypt, to_playwright_cookies, to_cookie_str
+
+# 1. 从 CookieCloud 服务端获取加密数据（任意 HTTP 库）
+import httpx
+resp = httpx.get(
+    "https://your-server.com/get/YOUR_UUID",
+    params={"password": "YOUR_PASSWORD"},
+)
+encrypted = resp.json()["encrypted"]
+
+# 2. 解密（auto 模式自动识别格式）
+data = decrypt(encrypted, uuid="YOUR_UUID", password="YOUR_PASSWORD")
+
+# 3. 格式化输出
+# Playwright add_cookies 格式
+cookies = to_playwright_cookies(data, domains=[".example.com"])
+
+# "k1=v1; k2=v2" 字符串格式
+cookie_str = to_cookie_str(data, domain=".example.com", keys=["a1", "session"])
+```
+
+## API
+
+### `decrypt(encrypted, uuid, password, mode="auto")`
+
+解密 CookieCloud 服务端返回的加密数据。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `encrypted` | `str` | CookieCloud GET `/get/{uuid}` 返回的 `encrypted` 字段（base64） |
+| `uuid` | `str` | CookieCloud UUID |
+| `password` | `str` | CookieCloud 密码 |
+| `mode` | `str` | 解密模式：`"auto"`（默认，自动检测）、`"legacy"`、`"aes-128-cbc-fixed"` |
+
+**返回值**：解密后的 dict，结构为 `{"cookie_data": {域名: [CookieEntry, ...]}, "update_time": ...}`
+
+**异常**：
+- `InvalidKeyError` — UUID 或密码错误
+- `CorruptedDataError` — 密文格式损坏
+
+### `to_playwright_cookies(data, domains=None)`
+
+导出为 Playwright `BrowserContext.add_cookies()` 所需格式。
+
+```python
+from playwright.async_api import async_playwright
+
+cookies = to_playwright_cookies(data, domains=[".xiaohongshu.com"])
+async with async_playwright() as p:
+    ctx = await p.chromium.launch()
+    await ctx.add_cookies(cookies)
+```
+
+### `to_cookie_str(data, domain, keys=None)`
+
+导出为 `k1=v1; k2=v2` 格式的字符串。
+
+```python
+cookie_str = to_cookie_str(
+    data,
+    domain=".xiaohongshu.com",
+    keys=["a1", "web_session"],
+)
+# → "a1=xxx; web_session=yyy"
+```
+
+### `to_cookie_dict(data, domains=None)`
+
+导出为 `{域名: [CookieEntry, ...]}` 格式。
+
+## 开发
+
+```bash
+# 安装
+pip install -e ".[dev]"
+
+# 运行测试
+pytest tests/ -v
+
+# 端到端测试（首次需要联网录制 cassette）
+cp .env.example .env
+# 填入真实 COOKIECLOUD_SERVER / COOKIECLOUD_UUID / COOKIECLOUD_PASSWORD
+pytest tests/e2e_test.py -v --vcr-record=new_episodes
+```
+
+## 发布到 PyPI
+
+```bash
+# 1. 安装构建工具
+pip install build twine
+
+# 2. 构建 wheel 和 sdist
+python -m build
+
+# 3. 上传到 TestPyPI（先测）
+twine upload --repository testpypi dist/*
+
+# 4. 上传到正式 PyPI
+twine upload dist/*
+```
+
+发布后外部用户直接 `pip install cookiecloud_decrypt` 即可使用。

cookiecloud_decrypt-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+cookiecloud_decrypt/__init__.py,sha256=DsNr-sNp0WHuEwk7ybZGFh58do_Euae7rvZ9WwnVp18,1330
+cookiecloud_decrypt/decrypt.py,sha256=IuBsmL6V2vBtDM_W0BNt6qBh0gmFiG7VspTMHYoLIbM,9799
+cookiecloud_decrypt/format.py,sha256=zfFDog6r4AKEzkgPF6PTB6Bz5duEBKVUtTqUo77xLGs,6948
+cookiecloud_decrypt/models.py,sha256=-VIvwDN0RLZ9pG0hscO7nl-jeVwV3SeJ6t9Fbu3x1N0,782
+cookiecloud_decrypt-0.1.0.dist-info/METADATA,sha256=lrSdy1zZFEg-QJmuLB8-9SjLvIsUVSRxn84aYQMokBQ,4080
+cookiecloud_decrypt-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cookiecloud_decrypt-0.1.0.dist-info/top_level.txt,sha256=vWhyzS-8JH12XXUEkTHtK-AYtpFkSdcpylycM_plLgs,20
+cookiecloud_decrypt-0.1.0.dist-info/RECORD,,

cookiecloud_decrypt-0.1.0.dist-info/WHEEL

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

cookiecloud_decrypt-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cookiecloud_decrypt