devart-dl 4.4.0__tar.gz → 4.4.2__tar.gz

{devart_dl-4.4.0/devart_dl.egg-info → devart_dl-4.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devart-dl
-Version: 4.4.0
+Version: 4.4.2
 Summary: 专业的 DeviantArt 作品批量下载工具 - Professional DeviantArt batch downloader with anti-ban features
 Author: DeviantArt Downloader Team
 License-Expression: MIT
@@ -81,6 +81,11 @@ devart-dl whoami
 devart-dl login browser   # 打开你的 Chrome 登录，自动保存 Cookie，无需 F12 复制
 ```
 
+下载或 resolve 遇到 401/403 时，工具会用同一代理与浏览器 UA 核对网页会话，
+区分会话已过期、证据暂不可用和已登录但作品访问被拒。网络失败或页面结构变化
+不会当作登出，也不会清除 Cookie；只有明确的未登录证据才提示刷新登录。
+这一步只诊断错误，不自动重试下载，也不保证已登录账号有权访问所有作品。
+
 完整图文式步骤见 **[登录与认证教程](https://redtidev1918.github.io/deviantart-downloader/#/LOGIN)**。
 
 > 普通用户无需手动下载 GitHub Release 里的 `.whl`、`.tar.gz` 或 Source code，运行上面的 `pip install` 即可。文件区别和 SHA256 校验方法见[完整文档](https://redtidev1918.github.io/deviantart-downloader/#/?id=github-release-%e9%87%8c%e7%9a%84%e6%96%87%e4%bb%b6%e6%98%af%e4%bb%80%e4%b9%88)。

{devart_dl-4.4.0 → devart_dl-4.4.2}/README.md

@@ -47,6 +47,11 @@ devart-dl whoami
 devart-dl login browser   # 打开你的 Chrome 登录，自动保存 Cookie，无需 F12 复制
 ```
 
+下载或 resolve 遇到 401/403 时，工具会用同一代理与浏览器 UA 核对网页会话，
+区分会话已过期、证据暂不可用和已登录但作品访问被拒。网络失败或页面结构变化
+不会当作登出，也不会清除 Cookie；只有明确的未登录证据才提示刷新登录。
+这一步只诊断错误，不自动重试下载，也不保证已登录账号有权访问所有作品。
+
 完整图文式步骤见 **[登录与认证教程](https://redtidev1918.github.io/deviantart-downloader/#/LOGIN)**。
 
 > 普通用户无需手动下载 GitHub Release 里的 `.whl`、`.tar.gz` 或 Source code，运行上面的 `pip install` 即可。文件区别和 SHA256 校验方法见[完整文档](https://redtidev1918.github.io/deviantart-downloader/#/?id=github-release-%e9%87%8c%e7%9a%84%e6%96%87%e4%bb%b6%e6%98%af%e4%bb%80%e4%b9%88)。

devart_dl-4.4.2/da_downloader/auth.py

@@ -0,0 +1,342 @@
+"""认证和 Cookie 管理模块
+
+网页会话验证逻辑移植自 DAViewer `lib/core/auth/web_session_verifier.dart`
+（生产首页证据验证，2026-10 DAViewer 会话恢复工程）：首页
+``window.__INITIAL_STATE__`` 的 redux 风格键 ``@@publicSession`` 声明
+``isLoggedIn`` 与 ``user.username``。三态判定：
+
+- ``SIGNED_IN``：服务端确认登录且给出用户名；
+- ``ANONYMOUS``：服务端明确声明未登录（``isLoggedIn: false`` 或
+  ``anonymous`` 身份）；
+- ``UNAVAILABLE``：网络失败 / 页面结构变化 / 证据缺失——绝不能与
+  "未登录"混为一谈。
+
+``isLoggedIn: true`` 但读不到用户名时保持未验证，不猜测。
+"""
+
+import enum
+import json
+import logging
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+# 与 download.py 的 web provider 使用同一浏览器 UA（会话验证请求的 UA
+# 必须与实际带 Cookie 抓取的请求一致，否则验证的不是同一个会话）。
+_WEB_USER_AGENT = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120 Safari/537.36"
+)
+_HOME_URL = "https://www.deviantart.com/"
+_INITIAL_STATE_MARKER = "window.__INITIAL_STATE__ = JSON.parse("
+
+
+class WebSessionState(enum.Enum):
+    """首页对当前 Cookie 会话的三态判定（服务端答案，不是本地猜测）。"""
+
+    SIGNED_IN = "signed_in"
+    ANONYMOUS = "anonymous"
+    UNAVAILABLE = "unavailable"
+
+
+@dataclass(frozen=True)
+class WebSessionVerification:
+    state: WebSessionState
+    username: str = ""
+
+    @property
+    def is_signed_in(self) -> bool:
+        return self.state == WebSessionState.SIGNED_IN
+
+
+_JS_ESCAPES = {
+    '"': '"',
+    "'": "'",
+    "\\": "\\",
+    "/": "/",
+    "b": "\b",
+    "f": "\f",
+    "n": "\n",
+    "r": "\r",
+    "t": "\t",
+}
+
+
+def _json_parse_assignment(html: str, marker: str) -> Optional[object]:
+    """解析 ``JSON.parse('<json>')`` 形式的 JS 赋值，返回解析后的对象。
+
+    引号内是 JS 字符串字面量（含 ``\\"`` 等 JS 转义），先做 JS 反转义再
+    ``json.loads``。找不到 marker 或无法解析时返回 ``None``。
+    """
+    idx = html.find(marker)
+    if idx == -1:
+        return None
+    rest = html[idx + len(marker) :].lstrip()
+    if not rest or rest[0] not in ("'", '"'):
+        return None
+    quote = rest[0]
+    out: list[str] = []
+    i = 1
+    length = len(rest)
+    while i < length:
+        ch = rest[i]
+        if ch == "\\" and i + 1 < length:
+            nxt = rest[i + 1]
+            if nxt == "u" and i + 6 <= length:
+                hex4 = rest[i + 2 : i + 6]
+                try:
+                    out.append(chr(int(hex4, 16)))
+                    i += 6
+                    continue
+                except ValueError:
+                    pass
+            out.append(_JS_ESCAPES.get(nxt, nxt))
+            i += 2
+            continue
+        if ch == quote:
+            try:
+                value: object = json.loads("".join(out))
+                return value
+            except json.JSONDecodeError:
+                return None
+        out.append(ch)
+        i += 1
+    return None
+
+
+class AuthManager:
+    """认证管理器 - 处理 Cookie 和登录状态"""
+
+    def __init__(self, cookies_path: str = "cookies.txt"):
+        self.cookies_path = cookies_path
+        self.cookies: str = ""
+        self.is_logged_in: bool = False
+
+    def load_cookies(self) -> str:
+        """加载 Cookie 文件（支持 cookies.txt 和会话文件）"""
+        import json
+        from pathlib import Path
+
+        # 1. 尝试从会话文件加载
+        session_file = Path.home() / ".deviantart_dl" / "session.json"
+        if session_file.exists():
+            try:
+                with open(session_file, "r", encoding="utf-8") as f:
+                    session_data = json.load(f)
+                    cookies = str(session_data.get("cookies", ""))
+                    if cookies:
+                        logger.info(f"✓ Loaded cookies from session file: {session_file}")
+                        self.cookies = cookies
+                        return cookies
+            except Exception as e:
+                logger.debug(f"Failed to load session file: {e}")
+
+        # 2. 尝试从 cookies.txt 加载
+        if not os.path.isfile(self.cookies_path):
+            logger.info(
+                f"No cookie file found at {self.cookies_path} (optional for public content)"
+            )
+            return ""
+
+        try:
+            with open(self.cookies_path, "r", encoding="utf-8") as f:
+                cookies = f.read().strip()
+
+            # 移除注释行
+            lines = [
+                line.strip()
+                for line in cookies.split("\n")
+                if line.strip() and not line.strip().startswith("#")
+            ]
+            cookies = " ".join(lines)
+
+            if cookies:
+                logger.info(f"✓ Loaded cookies from: {self.cookies_path}")
+                self.cookies = cookies
+                return cookies
+            else:
+                logger.warning(f"Cookie file is empty: {self.cookies_path}")
+                return ""
+        except Exception as e:
+            logger.error(f"Error loading cookies: {e}")
+            return ""
+
+    def validate_cookies(self, cookies: Optional[str] = None) -> bool:
+        """验证 Cookie 是否包含认证信息"""
+        if cookies is None:
+            cookies = self.cookies
+
+        if not cookies:
+            return False
+
+        # 检查关键的认证 Cookie
+        auth_indicators = ["auth=", "auth_secure=", "userinfo="]
+        has_auth = any(indicator in cookies for indicator in auth_indicators)
+
+        if has_auth:
+            logger.info("✓ Cookies appear valid (contains auth tokens)")
+        else:
+            logger.warning("⚠ Cookies may be invalid or incomplete")
+
+        return has_auth
+
+    def verify_web_session(
+        self,
+        cookies: Optional[str] = None,
+        proxies: Optional[dict] = None,
+        timeout: float = 10.0,
+    ) -> WebSessionVerification:
+        """向 DeviantArt 首页确认当前 Cookie 会话（服务端答案，三态）。
+
+        网络失败、非 200、页面结构变化一律 ``UNAVAILABLE``，绝不误判为
+        未登录。仅在服务端明确声明未登录时返回 ``ANONYMOUS``。
+        """
+        if cookies is None:
+            cookies = self.cookies
+        headers = {
+            "Accept": "text/html,application/xhtml+xml",
+            "User-Agent": _WEB_USER_AGENT,
+        }
+        if cookies:
+            headers["Cookie"] = cookies
+        try:
+            response = requests.get(_HOME_URL, headers=headers, proxies=proxies, timeout=timeout)
+        except requests.RequestException as exc:
+            logger.debug(f"web session verify network failure: {exc}")
+            return WebSessionVerification(WebSessionState.UNAVAILABLE)
+        if response.status_code != 200:
+            logger.info("web session verify: HTTP %d -> unavailable", response.status_code)
+            return WebSessionVerification(WebSessionState.UNAVAILABLE)
+        username = self.page_username_from_initial_state(response.text)
+        if username == "anonymous":
+            verdict = WebSessionVerification(WebSessionState.ANONYMOUS)
+        elif username:
+            verdict = WebSessionVerification(WebSessionState.SIGNED_IN, username)
+        else:
+            verdict = WebSessionVerification(WebSessionState.UNAVAILABLE)
+        if verdict.state != WebSessionState.UNAVAILABLE:
+            self.is_logged_in = verdict.is_signed_in
+        logger.info("web session verify: %s", verdict.state.value)
+        return verdict
+
+    @staticmethod
+    def page_username_from_initial_state(html: str) -> Optional[str]:
+        """从首页 ``__INITIAL_STATE__`` 读取服务端渲染的用户名。
+
+        返回 ``None`` 表示证据缺失或无法解析；``'anonymous'`` 表示服务端
+        明确声明未登录（``isLoggedIn: false`` 或匿名身份）；其余为已登录
+        用户名。``isLoggedIn: true`` 但无用户名保持 ``None``，不猜测。
+        """
+        state = _json_parse_assignment(html, _INITIAL_STATE_MARKER)
+        if not isinstance(state, dict):
+            return None
+        session = state.get("@@publicSession") or state.get("@publicSession")
+        if not isinstance(session, dict):
+            return None
+        user = session.get("user")
+        raw_username = user.get("username") if isinstance(user, dict) else None
+        username = raw_username.strip() if isinstance(raw_username, str) else None
+        if session.get("isLoggedIn") is False:
+            return "anonymous"
+        return username
+
+    def reload_cookies(self) -> str:
+        """重新加载 Cookie"""
+        logger.info("Reloading cookies...")
+        return self.load_cookies()
+
+    @staticmethod
+    def show_login_guide() -> None:
+        """显示登录指南"""
+        guide = """
+╔══════════════════════════════════════════════════════════════════════╗
+║                    HOW TO GET DEVIANTART COOKIES                     ║
+╚══════════════════════════════════════════════════════════════════════╝
+
+1. Open DeviantArt in your browser and LOGIN to your account
+   → https://www.deviantart.com
+
+2. Open Browser Developer Tools:
+   • Chrome/Edge: Press F12 or Ctrl+Shift+I (Cmd+Option+I on Mac)
+   • Firefox: Press F12 or Ctrl+Shift+I (Cmd+Option+I on Mac)
+
+3. Go to "Application" tab (Chrome) or "Storage" tab (Firefox)
+
+4. In the left sidebar, expand "Cookies" and click on:
+   → https://www.deviantart.com
+
+5. Copy ALL cookie values in this format:
+   cookie1=value1; cookie2=value2; cookie3=value3
+
+   Important cookies to include:
+   • auth
+   • auth_secure
+   • userinfo
+
+6. Paste the copied cookies into a file named "cookies.txt"
+   in the same folder as this script
+
+Alternatively, you can use browser extensions like:
+• "EditThisCookie" (Chrome)
+• "Cookie-Editor" (Firefox/Chrome)
+
+"""
+        print(guide)
+
+    def prompt_for_cookies(self, require_auth: bool = False) -> bool:
+        """提示用户配置 Cookie"""
+        if not self.cookies:
+            print("! Running without cookies - only public content accessible")
+
+            if require_auth:
+                print("\n⚠ WARNING: This operation requires login!")
+                answer = input("Show login guide? (y/n): ").lower()
+                if answer in ["y", "yes"]:
+                    self.show_login_guide()
+                    input("\nPress Enter after setting up cookies, or Ctrl+C to exit...")
+                    self.cookies = self.reload_cookies()
+                    return bool(self.cookies)
+
+        elif not self.validate_cookies():
+            answer = input("Do you want to see the cookie setup guide? (y/n): ").lower()
+            if answer in ["y", "yes"]:
+                self.show_login_guide()
+
+        return bool(self.cookies)
+
+
+def diagnose_authentication_failure(
+    cookies: str,
+    proxy: Optional[str] = None,
+    timeout: float = 10.0,
+) -> Optional[str]:
+    """401/403 之后的会话诊断：给出明确原因，而不是让用户猜。
+
+    返回面向用户的英文提示（与 CLI 其余错误文案一致），无法诊断时返回
+    ``None``。绝不静默发起额外网络请求重试下载本身。
+    """
+    proxies = {"http": proxy, "https": proxy} if proxy else {}
+    if not cookies:
+        return (
+            "hint: no cookies were provided; mature/NSFW works need a login "
+            "session - run `devart-dl login browser`"
+        )
+    verdict = AuthManager().verify_web_session(cookies=cookies, proxies=proxies, timeout=timeout)
+    if verdict.state == WebSessionState.ANONYMOUS:
+        return (
+            "hint: the DeviantArt session has expired - run "
+            "`devart-dl login browser` to refresh it"
+        )
+    if verdict.state == WebSessionState.UNAVAILABLE:
+        return (
+            "hint: could not confirm the session state (network or page "
+            "challenge/change); stored cookies were not cleared"
+        )
+    return (
+        f"hint: the session is valid (signed in as {verdict.username}); "
+        "the request was denied, which may involve item permissions or a service challenge"
+    )

{devart_dl-4.4.0 → devart_dl-4.4.2}/da_downloader/cli.py

@@ -19,9 +19,9 @@ from importlib.metadata import PackageNotFoundError, version
 from pathlib import Path
 from typing import Optional, Sequence
 
-from .auth import AuthManager
+from .auth import AuthManager, diagnose_authentication_failure
 from .download import build_downloader
-from .errors import DeviantArtError
+from .errors import AuthenticationError, DeviantArtError
 from .oauth import (
     OAuthConfig,
     OAuthError,
@@ -138,6 +138,12 @@ def _execute(
             limit=limit,
         )
         outcomes = downloader.download(target)
+    except AuthenticationError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        hint = diagnose_authentication_failure(cookies, proxy=proxy, timeout=timeout)
+        if hint:
+            print(hint, file=sys.stderr)
+        return 1
     except (ValueError, DeviantArtError) as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 1
@@ -200,7 +206,6 @@ def _run_download(arguments: Sequence[str]) -> int:
     )
 
 
-
 def _run_resolve(arguments: Sequence[str]) -> int:
     parser = argparse.ArgumentParser(
         prog="devart-dl resolve",
@@ -215,9 +220,10 @@ def _run_resolve(arguments: Sequence[str]) -> int:
     parser.add_argument("--limit", type=int, default=24)
     args = parser.parse_args(list(arguments))
     try:
+        cookies = _load_cookies(args.cookies)
         downloader = build_downloader(
             destination=Path("."),
-            cookies=_load_cookies(args.cookies),
+            cookies=cookies,
             quality=args.quality,
             proxy=args.proxy,
             timeout=args.timeout,
@@ -225,6 +231,12 @@ def _run_resolve(arguments: Sequence[str]) -> int:
             limit=args.limit,
         )
         works = downloader.resolve(args.target)
+    except AuthenticationError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        hint = diagnose_authentication_failure(cookies, proxy=args.proxy, timeout=args.timeout)
+        if hint:
+            print(hint, file=sys.stderr)
+        return 1
     except (ValueError, DeviantArtError) as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 1

{devart_dl-4.4.0 → devart_dl-4.4.2/devart_dl.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devart-dl
-Version: 4.4.0
+Version: 4.4.2
 Summary: 专业的 DeviantArt 作品批量下载工具 - Professional DeviantArt batch downloader with anti-ban features
 Author: DeviantArt Downloader Team
 License-Expression: MIT
@@ -81,6 +81,11 @@ devart-dl whoami
 devart-dl login browser   # 打开你的 Chrome 登录，自动保存 Cookie，无需 F12 复制
 ```
 
+下载或 resolve 遇到 401/403 时，工具会用同一代理与浏览器 UA 核对网页会话，
+区分会话已过期、证据暂不可用和已登录但作品访问被拒。网络失败或页面结构变化
+不会当作登出，也不会清除 Cookie；只有明确的未登录证据才提示刷新登录。
+这一步只诊断错误，不自动重试下载，也不保证已登录账号有权访问所有作品。
+
 完整图文式步骤见 **[登录与认证教程](https://redtidev1918.github.io/deviantart-downloader/#/LOGIN)**。
 
 > 普通用户无需手动下载 GitHub Release 里的 `.whl`、`.tar.gz` 或 Source code，运行上面的 `pip install` 即可。文件区别和 SHA256 校验方法见[完整文档](https://redtidev1918.github.io/deviantart-downloader/#/?id=github-release-%e9%87%8c%e7%9a%84%e6%96%87%e4%bb%b6%e6%98%af%e4%bb%80%e4%b9%88)。

{devart_dl-4.4.0 → devart_dl-4.4.2}/devart_dl.egg-info/SOURCES.txt

@@ -40,4 +40,5 @@ tests/test_manager.py
 tests/test_official_provider.py
 tests/test_path.py
 tests/test_provider.py
-tests/test_targets.py
+tests/test_targets.py
+tests/test_web_session_verify.py

{devart_dl-4.4.0 → devart_dl-4.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "devart-dl"
-version = "4.4.0"
+version = "4.4.2"
 description = "专业的 DeviantArt 作品批量下载工具 - Professional DeviantArt batch downloader with anti-ban features"
 readme = "README.md"
 requires-python = ">=3.10"

devart_dl-4.4.2/tests/test_web_session_verify.py

@@ -0,0 +1,219 @@
+"""Web session verification tests (tri-state verdict).
+
+Fixture origin: fixtures/deviantart-home-evidence.md records the independent
+2026-10-13 anonymous home capture. Signed-in/malformed samples are synthetic
+mutations for policy checks; they do not prove real authenticated access.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+from pathlib import Path
+
+import pytest
+import requests
+
+from da_downloader.auth import (
+    AuthManager,
+    WebSessionState,
+    diagnose_authentication_failure,
+)
+
+# --- page_username_from_initial_state (ported production evidence) ---
+
+
+def test_parse_accepts_javascript_escapes() -> None:
+    html = r"""<script>window.__INITIAL_STATE__ = JSON.parse("{\"@@publicSession\":{\"isLoggedIn\":true,\"user\":{\"username\":\"artist\"}},\"title\":\"artist\'s work\"}");</script>"""
+    assert AuthManager.page_username_from_initial_state(html) == "artist"
+
+
+def test_single_quoted_initializer_keeps_anonymous_distinct_from_missing() -> None:
+    html = (
+        """<script>window.__INITIAL_STATE__ = JSON.parse('"""
+        """{"@@publicSession":{"isLoggedIn":false,"user":{"username":"anonymous"}}}"""
+        """');</script>"""
+    )
+    assert AuthManager.page_username_from_initial_state(html) == "anonymous"
+    assert AuthManager.page_username_from_initial_state("<html/>") is None
+
+
+def test_legacy_single_at_spelling_still_parses() -> None:
+    html = r"""<script>window.__INITIAL_STATE__ = JSON.parse("{\"@publicSession\":{\"user\":{\"username\":\"artist\"}}}");</script>"""
+    assert AuthManager.page_username_from_initial_state(html) == "artist"
+
+
+def test_is_logged_in_false_without_username_is_a_signed_out_statement() -> None:
+    html = r"""<script>window.__INITIAL_STATE__ = JSON.parse("{\"@@publicSession\":{\"isLoggedIn\":false}}");</script>"""
+    assert AuthManager.page_username_from_initial_state(html) == "anonymous"
+
+
+def test_is_logged_in_true_without_username_stays_unverified() -> None:
+    html = r"""<script>window.__INITIAL_STATE__ = JSON.parse("{\"@@publicSession\":{\"isLoggedIn\":true}}");</script>"""
+    assert AuthManager.page_username_from_initial_state(html) is None
+
+
+@pytest.mark.parametrize(
+    "fixture",
+    [
+        'window.__INITIAL_STATE__ = JSON.parse("broken");',
+        'window.__INITIAL_STATE__ = JSON.parse("{}");',
+        'window.__INITIAL_STATE__ = JSON.parse("{\\"@@publicSession\\":{}}");',
+    ],
+)
+def test_incomplete_or_malformed_state_is_none(fixture: str) -> None:
+    assert AuthManager.page_username_from_initial_state(fixture) is None
+
+
+# --- verify_web_session (tri-state over a mocked home page) ---
+
+
+class _FakeResponse:
+    def __init__(self, status_code: int, text: str) -> None:
+        self.status_code = status_code
+        self.text = text
+
+
+def _verify(html: str = "", status: int = 200, exc: Exception | None = None):
+    manager = AuthManager()
+
+    def fake_get(url, **kwargs):
+        assert url == "https://www.deviantart.com/"
+        assert kwargs["headers"]["User-Agent"].startswith("Mozilla/5.0")
+        assert kwargs["headers"]["Cookie"] == "auth=x"
+        if exc is not None:
+            raise exc
+        return _FakeResponse(status, html)
+
+    with patch("da_downloader.auth.requests.get", side_effect=fake_get):
+        return manager, manager.verify_web_session(cookies="auth=x")
+
+
+_SIGNED_IN_HTML = (
+    r"<script>window.__INITIAL_STATE__ = JSON.parse("
+    r'"{\"@@publicSession\":{\"isLoggedIn\":true,\"user\":{\"username\":\"alice\"}}}");</script>'
+)
+_ANONYMOUS_HTML = (Path(__file__).parent / "fixtures" / "deviantart-home-anonymous.html").read_text(
+    encoding="utf-8"
+)
+
+
+def test_verify_signed_in_with_username() -> None:
+    manager, verdict = _verify(_SIGNED_IN_HTML)
+    assert verdict.state == WebSessionState.SIGNED_IN
+    assert verdict.username == "alice"
+    assert manager.is_logged_in is True
+
+
+def test_verify_anonymous_is_a_server_statement() -> None:
+    manager, verdict = _verify(_ANONYMOUS_HTML)
+    assert verdict.state == WebSessionState.ANONYMOUS
+    assert manager.is_logged_in is False
+
+
+def test_verify_network_failure_is_unavailable_not_anonymous() -> None:
+    manager, verdict = _verify(exc=requests.ConnectionError("boom"))
+    assert verdict.state == WebSessionState.UNAVAILABLE
+    assert manager.is_logged_in is False
+
+
+@pytest.mark.parametrize("status", [202, 403, 500])
+def test_verify_non_200_is_unavailable(status: int) -> None:
+    _, verdict = _verify("challenge", status=status)
+    assert verdict.state == WebSessionState.UNAVAILABLE
+
+
+def test_verify_missing_marker_is_unavailable() -> None:
+    _, verdict = _verify("<html>waf challenge</html>")
+    assert verdict.state == WebSessionState.UNAVAILABLE
+
+
+def test_unavailable_page_does_not_erase_prior_identity() -> None:
+    manager = AuthManager()
+    manager.is_logged_in = True
+    with patch("da_downloader.auth.requests.get", return_value=_FakeResponse(200, "challenge")):
+        assert manager.verify_web_session().state == WebSessionState.UNAVAILABLE
+    assert manager.is_logged_in is True
+
+
+# --- diagnose_authentication_failure (401/403 hint text) ---
+
+
+def test_diagnose_without_cookies_suggests_login() -> None:
+    hint = diagnose_authentication_failure("")
+    assert hint is not None
+    assert "login browser" in hint
+
+
+def test_diagnose_expired_session(monkeypatch) -> None:
+    monkeypatch.setattr(
+        AuthManager,
+        "verify_web_session",
+        lambda self, cookies, proxies, timeout: type(
+            "V", (), {"state": WebSessionState.ANONYMOUS, "username": ""}
+        )(),
+    )
+    hint = diagnose_authentication_failure("auth=old")
+    assert hint is not None
+    assert "expired" in hint
+
+
+def test_diagnose_unavailable_session(monkeypatch) -> None:
+    monkeypatch.setattr(
+        AuthManager,
+        "verify_web_session",
+        lambda self, cookies, proxies, timeout: type(
+            "V", (), {"state": WebSessionState.UNAVAILABLE, "username": ""}
+        )(),
+    )
+    hint = diagnose_authentication_failure("auth=old")
+    assert hint is not None
+    assert "could not confirm" in hint
+
+
+def test_diagnose_valid_session_points_at_the_item(monkeypatch) -> None:
+    monkeypatch.setattr(
+        AuthManager,
+        "verify_web_session",
+        lambda self, cookies, proxies, timeout: type(
+            "V", (), {"state": WebSessionState.SIGNED_IN, "username": "alice"}
+        )(),
+    )
+    hint = diagnose_authentication_failure("auth=ok")
+    assert hint is not None
+    assert "signed in as alice" in hint
+    assert "denied" in hint
+
+
+# --- CLI integration: AuthenticationError prints the diagnosis ---
+
+
+def test_run_download_authentication_error_prints_hint(monkeypatch, capsys, tmp_path) -> None:
+    from da_downloader.errors import AuthenticationError
+
+    def boom(**kwargs):
+        raise AuthenticationError("HTTP 403 forbidden: https://example/x")
+
+    monkeypatch.setattr(cli_module(), "build_downloader", boom)
+    monkeypatch.setattr(cli_module(), "_load_cookies", lambda p: "auth=x")
+    hints: list = []
+    monkeypatch.setattr(
+        cli_module(),
+        "diagnose_authentication_failure",
+        lambda *a, **kw: hints.append((a, kw)) or "hint: session expired",
+    )
+
+    rc = cli_module()._run_download(
+        ["https://www.deviantart.com/alice/gallery", "--dest", str(tmp_path)]
+    )
+
+    assert rc == 1
+    err = capsys.readouterr().err
+    assert "error: HTTP 403 forbidden" in err
+    assert "hint: session expired" in err
+    assert hints and hints[0][0][0] == "auth=x"
+
+
+def cli_module():
+    from da_downloader import cli
+
+    return cli

devart_dl-4.4.0/da_downloader/auth.py

@@ -1,169 +0,0 @@
-"""认证和 Cookie 管理模块"""
-
-import os
-import logging
-from typing import Optional
-import requests
-
-
-logger = logging.getLogger(__name__)
-
-
-class AuthManager:
-    """认证管理器 - 处理 Cookie 和登录状态"""
-    
-    def __init__(self, cookies_path: str = "cookies.txt"):
-        self.cookies_path = cookies_path
-        self.cookies: str = ""
-        self.is_logged_in: bool = False
-        
-    def load_cookies(self) -> str:
-        """加载 Cookie 文件（支持 cookies.txt 和会话文件）"""
-        import json
-        from pathlib import Path
-        
-        # 1. 尝试从会话文件加载
-        session_file = Path.home() / '.deviantart_dl' / 'session.json'
-        if session_file.exists():
-            try:
-                with open(session_file, 'r', encoding='utf-8') as f:
-                    session_data = json.load(f)
-                    cookies = str(session_data.get('cookies', ''))
-                    if cookies:
-                        logger.info(f"✓ Loaded cookies from session file: {session_file}")
-                        self.cookies = cookies
-                        return cookies
-            except Exception as e:
-                logger.debug(f"Failed to load session file: {e}")
-        
-        # 2. 尝试从 cookies.txt 加载
-        if not os.path.isfile(self.cookies_path):
-            logger.info(f"No cookie file found at {self.cookies_path} (optional for public content)")
-            return ""
-        
-        try:
-            with open(self.cookies_path, 'r', encoding='utf-8') as f:
-                cookies = f.read().strip()
-            
-            # 移除注释行
-            lines = [line.strip() for line in cookies.split('\n') 
-                    if line.strip() and not line.strip().startswith('#')]
-            cookies = ' '.join(lines)
-            
-            if cookies:
-                logger.info(f"✓ Loaded cookies from: {self.cookies_path}")
-                self.cookies = cookies
-                return cookies
-            else:
-                logger.warning(f"Cookie file is empty: {self.cookies_path}")
-                return ""
-        except Exception as e:
-            logger.error(f"Error loading cookies: {e}")
-            return ""
-    
-    def validate_cookies(self, cookies: Optional[str] = None) -> bool:
-        """验证 Cookie 是否包含认证信息"""
-        if cookies is None:
-            cookies = self.cookies
-        
-        if not cookies:
-            return False
-        
-        # 检查关键的认证 Cookie
-        auth_indicators = ['auth=', 'auth_secure=', 'userinfo=']
-        has_auth = any(indicator in cookies for indicator in auth_indicators)
-        
-        if has_auth:
-            logger.info("✓ Cookies appear valid (contains auth tokens)")
-        else:
-            logger.warning("⚠ Cookies may be invalid or incomplete")
-        
-        return has_auth
-    
-    def check_login_status(self, headers: dict, proxies: dict) -> bool:
-        """检查登录状态"""
-        try:
-            response = requests.get(
-                'https://www.deviantart.com',
-                headers=headers,
-                proxies=proxies,
-                timeout=10
-            )
-            
-            if 'window.__CSRF_TOKEN__' in response.text:
-                if 'data-userid' in response.text or '"isLoggedIn":true' in response.text:
-                    logger.info("✓ Successfully logged in!")
-                    self.is_logged_in = True
-                    return True
-                else:
-                    logger.info("! Not logged in (public access only)")
-                    self.is_logged_in = False
-                    return False
-            return False
-        except Exception as e:
-            logger.warning(f"Could not verify login status: {e}")
-            return False
-    
-    def reload_cookies(self) -> str:
-        """重新加载 Cookie"""
-        logger.info("Reloading cookies...")
-        return self.load_cookies()
-    
-    @staticmethod
-    def show_login_guide() -> None:
-        """显示登录指南"""
-        guide = '''
-╔══════════════════════════════════════════════════════════════════════╗
-║                    HOW TO GET DEVIANTART COOKIES                     ║
-╚══════════════════════════════════════════════════════════════════════╝
-
-1. Open DeviantArt in your browser and LOGIN to your account
-   → https://www.deviantart.com
-
-2. Open Browser Developer Tools:
-   • Chrome/Edge: Press F12 or Ctrl+Shift+I (Cmd+Option+I on Mac)
-   • Firefox: Press F12 or Ctrl+Shift+I (Cmd+Option+I on Mac)
-
-3. Go to "Application" tab (Chrome) or "Storage" tab (Firefox)
-
-4. In the left sidebar, expand "Cookies" and click on:
-   → https://www.deviantart.com
-
-5. Copy ALL cookie values in this format:
-   cookie1=value1; cookie2=value2; cookie3=value3
-
-   Important cookies to include:
-   • auth
-   • auth_secure
-   • userinfo
-
-6. Paste the copied cookies into a file named "cookies.txt"
-   in the same folder as this script
-
-Alternatively, you can use browser extensions like:
-• "EditThisCookie" (Chrome)
-• "Cookie-Editor" (Firefox/Chrome)
-
-'''
-        print(guide)
-    
-    def prompt_for_cookies(self, require_auth: bool = False) -> bool:
-        """提示用户配置 Cookie"""
-        if not self.cookies:
-            print("! Running without cookies - only public content accessible")
-            
-            if require_auth:
-                print("\n⚠ WARNING: This operation requires login!")
-                answer = input("Show login guide? (y/n): ").lower()
-                if answer in ['y', 'yes']:
-                    self.show_login_guide()
-                    input("\nPress Enter after setting up cookies, or Ctrl+C to exit...")
-                    self.cookies = self.reload_cookies()
-                    return bool(self.cookies)
-        
-        elif not self.validate_cookies():
-            answer = input("Do you want to see the cookie setup guide? (y/n): ").lower()
-            if answer in ['y', 'yes']:
-                self.show_login_guide()
-        
-        return bool(self.cookies)