cookiecloud-decrypt 0.1.0__tar.gz

cookiecloud_decrypt-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,120 @@
+# 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/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-0.1.0/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}")