cheso-cli 0.2.0__py3-none-any.whl

cheso_cli/oauth.py

@@ -0,0 +1,797 @@
+"""Cheso 授权服务器的 OAuth 2.1 客户端。
+
+支持 RFC 8414 元数据、RFC 7591 注册、RFC 8252 回环重定向的授权码 + PKCE S256 登录、
+RFC 9207 ``iss`` 校验和 RFC 7009 撤销；没有浏览器或无法访问回环回调时，支持 RFC 8628 设备授权码流程。
+"""
+
+from __future__ import annotations
+
+import base64
+import contextlib
+import hashlib
+import html
+import http.server
+import math
+import secrets
+import time
+import webbrowser
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from typing import Any, NoReturn, TextIO
+from urllib.parse import parse_qs, urlencode, urlsplit
+
+import httpx
+
+from cheso_cli.client import Deadline, TimeLimitReached, call_until
+from cheso_cli.config import Settings
+from cheso_cli.credentials import CredentialStore, SiteCredentials
+from cheso_cli.errors import CliError, UsageError
+
+WELL_KNOWN_PATH = "/.well-known/oauth-authorization-server"
+SCOPE = "cheso"
+CLIENT_NAME = "Cheso CLI"
+LOOPBACK_HOST = "127.0.0.1"
+CALLBACK_PATH = "/callback"
+# 只注册一次；回环重定向 URI 可以匹配任意端口，见 RFC 8252 §7.3。
+REGISTERED_REDIRECT_URI = f"http://{LOOPBACK_HOST}{CALLBACK_PATH}"
+DEFAULT_LOGIN_TIMEOUT = 300.0
+HTTP_TIMEOUT = 30.0
+
+ERROR_INVALID_GRANT = "invalid_grant"
+ERROR_INVALID_CLIENT = "invalid_client"
+
+# 设备授权码流程，见 RFC 8628。
+DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code"
+DEFAULT_DEVICE_INTERVAL = 5.0
+SLOW_DOWN_STEP = 5.0
+# 连接或读取超时后，将下次轮询前的等待时间翻倍，最多增至以下秒数，见 RFC 8628 §3.5。
+MAX_BACKOFF_INTERVAL = 60.0
+# 登录成功后始终保存凭据；撤销被替换的旧登录和查询账号信息时，
+# 允许在 --timeout 之后额外运行以下时长。
+AFTER_LOGIN_GRACE = 5.0
+ERROR_AUTHORIZATION_PENDING = "authorization_pending"
+ERROR_SLOW_DOWN = "slow_down"
+ERROR_ACCESS_DENIED = "access_denied"
+ERROR_EXPIRED_TOKEN = "expired_token"
+KIND_LOGIN_DENIED = "login_denied"
+KIND_LOGIN_EXPIRED = "login_expired"
+
+
+class OAuthTimeout(CliError):
+    """连接或读取授权服务器时发生超时；轮询遇到此错误会增加退避等待。"""
+
+
+class OAuthProtocolError(CliError):
+    """授权服务器返回 RFC 6749 §5.2 定义的错误。"""
+
+    def __init__(self, error: str, description: str = "", *, http_status: int | None = None) -> None:
+        text = f"{error}: {description}" if description else error
+        super().__init__(f"authorization server error: {text}", kind="oauth_error", extra={"oauth_error": error})
+        self.error = error
+        self.description = description
+        self.http_status = http_status
+
+
+@dataclass(frozen=True)
+class ServerMetadata:
+    issuer: str
+    authorization_endpoint: str
+    token_endpoint: str
+    registration_endpoint: str
+    revocation_endpoint: str
+    device_authorization_endpoint: str = ""
+
+
+@dataclass(frozen=True)
+class DeviceLogin:
+    """等待用户确认的设备码登录信息，包括展示内容和轮询间隔。"""
+
+    verification_uri: str
+    user_code: str
+    expires_at: float
+    interval: float
+
+
+@dataclass(frozen=True)
+class TokenSet:
+    access_token: str
+    refresh_token: str
+    expires_at: float
+
+
+def pkce_pair() -> tuple[str, str]:
+    """生成 S256 的 ``(code_verifier, code_challenge)``：86 个 URL 安全字符和 base64url(sha256(verifier))。"""
+    verifier = secrets.token_urlsafe(64)
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+    return verifier, challenge
+
+
+def _origin(url: str) -> tuple[str, str, int | None]:
+    parts = urlsplit(url)
+    return parts.scheme, (parts.hostname or "").lower(), parts.port
+
+
+class OAuthClient:
+    """访问 OAuth 协议端点；表单通过 application/x-www-form-urlencoded 发送，不放进 URL。"""
+
+    def __init__(
+        self,
+        settings: Settings,
+        *,
+        transport: httpx.BaseTransport | None = None,
+        now: Callable[[], float] = time.time,
+    ) -> None:
+        self.settings = settings
+        self._now = now
+        headers = {"Accept": "application/json", **settings.extra_headers()}
+        self._http = httpx.Client(headers=headers, timeout=HTTP_TIMEOUT, transport=transport, follow_redirects=False)
+        self._deadline: Deadline | None = None
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> OAuthClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    @contextlib.contextmanager
+    def time_limit(self, deadline: Deadline) -> Iterator[None]:
+        """作用域内不在 ``deadline`` 之后发起请求，等待完整响应也不能超过该时刻；
+        到期后改为抛出 TimeLimitReached。
+        """
+        previous, self._deadline = self._deadline, deadline
+        try:
+            yield
+        finally:
+            self._deadline = previous
+
+    # ---- 发现服务与注册客户端 ----
+
+    def metadata(self) -> ServerMetadata:
+        base = self.settings.base_url
+        resp = self._send("GET", base + WELL_KNOWN_PATH, target=base)
+        if resp.status_code == 404:
+            raise CliError(f"{base} does not offer OAuth login yet; set CHESO_API_TOKEN instead")
+        raw = self._json(resp)
+        if resp.status_code != 200:
+            raise self._error(resp, raw)
+        meta = ServerMetadata(
+            issuer=str(raw.get("issuer") or "").rstrip("/"),
+            authorization_endpoint=str(raw.get("authorization_endpoint") or ""),
+            token_endpoint=str(raw.get("token_endpoint") or ""),
+            registration_endpoint=str(raw.get("registration_endpoint") or ""),
+            revocation_endpoint=str(raw.get("revocation_endpoint") or ""),
+            device_authorization_endpoint=str(raw.get("device_authorization_endpoint") or ""),
+        )
+        self._check_metadata(meta, raw)
+        return meta
+
+    def _check_metadata(self, meta: ServerMetadata, raw: dict[str, Any]) -> None:
+        base = self.settings.base_url
+        # RFC 8414 §3.3：issuer 必须与获取元数据时使用的 URL 一致。
+        if meta.issuer != base:
+            raise CliError(f"authorization server issuer {meta.issuer!r} does not match {base!r}; refusing to log in")
+        scheme, _, _ = _origin(base)
+        for name in ("authorization_endpoint", "token_endpoint", "registration_endpoint"):
+            value = getattr(meta, name)
+            if not value or _origin(value)[0] != scheme:
+                raise CliError(f"authorization server metadata has no usable {name}")
+        # 令牌和设备码只发送到 issuer 的同源地址。
+        for name in ("token_endpoint", "registration_endpoint", "revocation_endpoint", "device_authorization_endpoint"):
+            value = getattr(meta, name)
+            if value and _origin(value) != _origin(base):
+                raise CliError(f"authorization server {name} is not on {base}; refusing to log in")
+        methods = raw.get("code_challenge_methods_supported") or []
+        if "S256" not in methods:
+            raise CliError("authorization server does not support PKCE S256")
+
+    def register(self, meta: ServerMetadata) -> str:
+        body = {
+            "client_name": CLIENT_NAME,
+            "redirect_uris": [REGISTERED_REDIRECT_URI],
+            "grant_types": ["authorization_code", "refresh_token"],
+            "response_types": ["code"],
+            "token_endpoint_auth_method": "none",
+        }
+        resp = self._post(meta.registration_endpoint, json=body)
+        raw = self._json(resp)
+        if resp.status_code not in (200, 201):
+            raise self._error(resp, raw)
+        client_id = str(raw.get("client_id") or "")
+        if not client_id:
+            raise CliError("authorization server did not return a client_id")
+        return client_id
+
+    # ---- 令牌 ----
+
+    def exchange_code(
+        self, token_endpoint: str, *, client_id: str, code: str, redirect_uri: str, verifier: str
+    ) -> TokenSet:
+        return self._token_request(
+            token_endpoint,
+            {
+                "grant_type": "authorization_code",
+                "code": code,
+                "redirect_uri": redirect_uri,
+                "client_id": client_id,
+                "code_verifier": verifier,
+            },
+        )
+
+    def refresh(self, token_endpoint: str, *, client_id: str, refresh_token: str) -> TokenSet:
+        return self._token_request(
+            token_endpoint,
+            {"grant_type": "refresh_token", "refresh_token": refresh_token, "client_id": client_id},
+        )
+
+    def start_device(self, endpoint: str, *, client_id: str) -> tuple[str, DeviceLogin]:
+        """RFC 8628 §3.1：返回保密的轮询设备码，以及向用户展示的登录信息。"""
+        resp = self._post(endpoint, data={"client_id": client_id, "scope": SCOPE})
+        raw = self._json(resp)
+        if resp.status_code != 200:
+            raise self._error(resp, raw)
+        device_code = str(raw.get("device_code") or "")
+        user_code = str(raw.get("user_code") or "")
+        verification_uri = str(raw.get("verification_uri") or "")
+        if not device_code or not user_code or not verification_uri:
+            raise CliError("authorization server returned an incomplete device login")
+        # 展示给用户的登录页面必须与 Cheso 站点同源，不能指向其他站点。
+        base = self.settings.base_url
+        if _origin(verification_uri) != _origin(base):
+            raise CliError(f"authorization server sign-in page is not on {base}; refusing to log in")
+        try:
+            expires_in = float(raw.get("expires_in") or 0)
+            interval = float(raw.get("interval") or DEFAULT_DEVICE_INTERVAL)
+        except (TypeError, ValueError):
+            expires_in, interval = 0.0, DEFAULT_DEVICE_INTERVAL
+        if expires_in <= 0:
+            raise CliError("authorization server returned a device login without an expiry")
+        return device_code, DeviceLogin(
+            verification_uri=verification_uri,
+            user_code=user_code,
+            expires_at=self._now() + expires_in,
+            interval=max(interval, 1.0),
+        )
+
+    def poll_device(self, token_endpoint: str, *, client_id: str, device_code: str) -> TokenSet:
+        """RFC 8628 §3.4：authorization_pending、slow_down 及最终错误通过 OAuthProtocolError 抛出。"""
+        return self._token_request(
+            token_endpoint, {"grant_type": DEVICE_GRANT_TYPE, "device_code": device_code, "client_id": client_id}
+        )
+
+    def revoke(self, revocation_endpoint: str, *, client_id: str, token: str, hint: str) -> None:
+        """RFC 7009：5xx 表示撤销尚未完成，可以再次发送相同令牌；此处重试一次。"""
+        form = {"token": token, "token_type_hint": hint, "client_id": client_id}
+        resp = self._post(revocation_endpoint, data=form)
+        if resp.status_code >= 500:
+            resp = self._post(revocation_endpoint, data=form)
+        if resp.status_code != 200:
+            raise self._error(resp, self._json(resp))
+
+    def _token_request(self, endpoint: str, form: dict[str, str]) -> TokenSet:
+        resp = self._post(endpoint, data=form)
+        raw = self._json(resp)
+        if resp.status_code != 200:
+            raise self._error(resp, raw)
+        access = str(raw.get("access_token") or "")
+        refresh = str(raw.get("refresh_token") or "")
+        try:
+            expires_in = float(raw.get("expires_in") or 0)
+        except (TypeError, ValueError):
+            expires_in = 0.0
+        if not access:
+            raise CliError("authorization server returned no access token")
+        return TokenSet(access_token=access, refresh_token=refresh, expires_at=self._now() + max(expires_in, 0.0))
+
+    # ---- HTTP 请求与响应处理 ----
+
+    def _post(self, url: str, **kwargs: Any) -> httpx.Response:
+        return self._send("POST", url, **kwargs)
+
+    def _send(
+        self, method: str, url: str, *, target: str = "the authorization server", **kwargs: Any
+    ) -> httpx.Response:
+        deadline = self._deadline
+        try:
+            if deadline is None:
+                return self._http.request(method, url, **kwargs)
+            # 同时限制各阶段超时，避免已放弃的请求在后台滞留过久。
+            kwargs["timeout"] = deadline.cap(httpx.Timeout(HTTP_TIMEOUT))
+            return call_until(deadline, lambda: self._http.request(method, url, **kwargs))
+        except TimeLimitReached:
+            raise
+        except httpx.TimeoutException as e:
+            if deadline is not None and deadline.expired():
+                raise TimeLimitReached() from e  # 请求因 --timeout 被截断，而非请求自身过慢。
+            raise OAuthTimeout(f"{target} did not answer in time ({e.__class__.__name__})") from e
+        except httpx.HTTPError as e:
+            raise CliError(f"cannot reach {target}: {e.__class__.__name__}") from e
+
+    @staticmethod
+    def _json(resp: httpx.Response) -> dict[str, Any]:
+        try:
+            raw = resp.json()
+        except ValueError:
+            return {}
+        return raw if isinstance(raw, dict) else {}
+
+    @staticmethod
+    def _error(resp: httpx.Response, raw: dict[str, Any]) -> CliError:
+        error = str(raw.get("error") or "")
+        if error:
+            return OAuthProtocolError(error, str(raw.get("error_description") or ""), http_status=resp.status_code)
+        return CliError(f"authorization server request failed (http {resp.status_code})")
+
+
+# ---- 回环登录 ----
+
+
+@dataclass
+class _CallbackOutcome:
+    ok: bool
+    message: str
+
+
+class _CallbackServer(http.server.HTTPServer):
+    """一次性回环服务器：第一个携带 OAuth 参数的 /callback 请求会结束等待。"""
+
+    def __init__(self, port: int, handle: Callable[[dict[str, str]], _CallbackOutcome]) -> None:
+        super().__init__((LOOPBACK_HOST, port), _CallbackHandler)
+        self.handle_callback = handle
+        self.outcome: _CallbackOutcome | None = None
+
+
+class _CallbackHandler(http.server.BaseHTTPRequestHandler):
+    server: _CallbackServer
+
+    def do_GET(self) -> None:  # noqa: N802  # pylint: disable=invalid-name  # http.server 要求使用这个名称
+        parts = urlsplit(self.path)
+        query = {k: v[0] for k, v in parse_qs(parts.query, keep_blank_values=True).items()}
+        if parts.path != CALLBACK_PATH or not ({"code", "error", "state"} & query.keys()):
+            self._page(404, "Not found", "This address only receives the Cheso sign-in callback.")
+            return
+        if self.server.outcome is not None:
+            self._page(409, "Already handled", "This sign-in has already been processed. You can close this tab.")
+            return
+        try:
+            outcome = self.server.handle_callback(query)
+        except CliError as e:
+            outcome = _CallbackOutcome(False, e.message)
+        except Exception as e:  # pylint: disable=broad-except  # 错误交给 CLI 报告，不由 http.server 打印
+            outcome = _CallbackOutcome(False, f"unexpected error: {e.__class__.__name__}")
+        self.server.outcome = outcome
+        if outcome.ok:
+            self._page(200, "Signed in to Cheso", "The Cheso CLI is signed in. You can close this tab.")
+        else:
+            self._page(400, "Sign-in failed", outcome.message + " Return to the terminal for details.")
+
+    def _page(self, status: int, title: str, message: str) -> None:
+        body = (
+            "<!doctype html><html><head><meta charset='utf-8'><title>{t}</title></head>"
+            "<body style='font-family:sans-serif;margin:3em'><h2>{t}</h2><p>{m}</p></body></html>"
+        ).format(t=html.escape(title), m=html.escape(message))
+        payload = body.encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(payload)))
+        self.send_header("Cache-Control", "no-store")
+        self.send_header("Referrer-Policy", "no-referrer")
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def log_message(self, format: str, *args: Any) -> None:  # noqa: A002 - 签名由 http.server 规定
+        # 请求行中含有授权码，绝不能写入日志。
+        return
+
+
+def login(
+    settings: Settings,
+    store: CredentialStore,
+    *,
+    open_browser: bool = True,
+    timeout: float = DEFAULT_LOGIN_TIMEOUT,
+    port: int = 0,
+    transport: httpx.BaseTransport | None = None,
+    browser_open: Callable[[str], Any] = webbrowser.open,
+    out: TextIO,
+    now: Callable[[], float] = time.time,
+) -> SiteCredentials:
+    """执行浏览器登录并保存令牌，返回保存后的凭据。"""
+    base = settings.base_url
+    with OAuthClient(settings, transport=transport, now=now) as oauth:
+        meta = oauth.metadata()
+        client_id = _registered_client(oauth, store, base, meta)
+        verifier, challenge = pkce_pair()
+        state = secrets.token_urlsafe(32)
+        exchanged: list[TokenSet] = []
+
+        def handle(query: dict[str, str]) -> _CallbackOutcome:
+            # RFC 6749 §10.12 / RFC 9207：先校验 state，再校验 issuer，最后处理结果。
+            if not secrets.compare_digest(query.get("state", ""), state):
+                return _CallbackOutcome(
+                    False, "The sign-in response did not match this login attempt (state mismatch)."
+                )
+            if query.get("iss", "").rstrip("/") != meta.issuer:
+                return _CallbackOutcome(False, "The sign-in response came from an unexpected issuer (iss mismatch).")
+            if query.get("error"):
+                reason = query.get("error_description") or query["error"]
+                if query["error"] == "access_denied":
+                    reason = "Access was denied in the browser."
+                return _CallbackOutcome(False, f"Authorization failed: {reason}")
+            code = query.get("code", "")
+            if not code:
+                return _CallbackOutcome(False, "The sign-in response carried no authorization code.")
+            try:
+                tokens = oauth.exchange_code(
+                    meta.token_endpoint, client_id=client_id, code=code, redirect_uri=redirect_uri, verifier=verifier
+                )
+            except OAuthProtocolError as e:
+                if e.error == ERROR_INVALID_CLIENT:
+                    _forget_client(store, base)
+                    return _CallbackOutcome(False, "The CLI registration is no longer valid. Run `cheso login` again.")
+                raise
+            exchanged.append(tokens)
+            return _CallbackOutcome(True, "")
+
+        try:
+            server = _CallbackServer(port, handle)
+        except OSError as e:
+            raise CliError(f"cannot listen on {LOOPBACK_HOST}:{port}: {e.strerror or e}") from e
+        with server:
+            server.timeout = 0.5
+            redirect_uri = f"http://{LOOPBACK_HOST}:{server.server_address[1]}{CALLBACK_PATH}"
+            auth_url = (
+                meta.authorization_endpoint
+                + "?"
+                + urlencode(
+                    {
+                        "response_type": "code",
+                        "client_id": client_id,
+                        "redirect_uri": redirect_uri,
+                        "state": state,
+                        "code_challenge": challenge,
+                        "code_challenge_method": "S256",
+                        "scope": SCOPE,
+                    }
+                )
+            )
+            print(f"Open this URL in a browser on this machine to sign in to {base}:\n\n  {auth_url}\n", file=out)
+            print(
+                f"No browser on this machine (SSH, container, cloud agent)? "
+                f"Run `{settings.command('login --device')}` instead.",
+                file=out,
+            )
+            print(f"Waiting for the sign-in callback on {redirect_uri} ...", file=out)
+            if open_browser:
+                try:
+                    browser_open(auth_url)
+                except Exception as e:  # pylint: disable=broad-except  # 打开浏览器失败不致命，上方已打印 URL
+                    print(f"Could not open a browser ({e.__class__.__name__}); open the URL above.", file=out)
+            deadline = time.monotonic() + timeout
+            while server.outcome is None and time.monotonic() < deadline:
+                server.handle_request()
+        outcome = server.outcome
+        if outcome is None:
+            raise CliError(f"timed out after {int(timeout)} s waiting for the browser sign-in")
+        if not outcome.ok or not exchanged:
+            raise CliError(outcome.message or "sign-in failed")
+
+        return _save_login(oauth, store, base, meta, client_id, exchanged[0])
+
+
+def _save_login(
+    oauth: OAuthClient, store: CredentialStore, base: str, meta: ServerMetadata, client_id: str, tokens: TokenSet
+) -> SiteCredentials:
+    """保存新的浏览器或设备码登录，并撤销被替换的旧授权。"""
+    with store.locked():
+        creds = store.get(base)
+        previous = (creds.client_id, creds.refresh_token, creds.revocation_endpoint)
+        creds.client_id = client_id
+        creds.issuer = meta.issuer
+        creds.token_endpoint = meta.token_endpoint
+        creds.revocation_endpoint = meta.revocation_endpoint
+        creds.access_token = tokens.access_token
+        creds.refresh_token = tokens.refresh_token
+        creds.expires_at = tokens.expires_at
+        creds.pending_device = {}
+        store.put(base, creds, make_default=True)
+    # 再次登录会替换旧授权；撤销旧授权，避免它一直留在“已授权的应用”中。
+    old_client, old_refresh, old_endpoint = previous
+    if old_refresh and old_endpoint:
+        try:
+            oauth.revoke(old_endpoint, client_id=old_client, token=old_refresh, hint="refresh_token")
+        except (CliError, TimeLimitReached):
+            pass
+    return creds
+
+
+def after_login(deadline: Deadline) -> Deadline:
+    """登录成功后的收尾时限，用于撤销被替换的登录和查询账号信息。"""
+    return Deadline(deadline.at + AFTER_LOGIN_GRACE, deadline.clock)
+
+
+# ---- 设备码登录（RFC 8628）----
+
+
+def start_device_login(
+    settings: Settings,
+    store: CredentialStore,
+    *,
+    transport: httpx.BaseTransport | None = None,
+    now: Callable[[], float] = time.time,
+    deadline: Deadline | None = None,
+) -> DeviceLogin:
+    """申请设备码并保存到凭据文件，使 ``cheso login --wait`` 可以继续等待。
+    传入 ``deadline`` 时，任何请求都不能超过该截止时间，否则抛出 TimeLimitReached。
+    """
+    base = settings.base_url
+    with (
+        OAuthClient(settings, transport=transport, now=now) as oauth,
+        oauth.time_limit(deadline) if deadline else contextlib.nullcontext(),
+    ):
+        meta = oauth.metadata()
+        if not meta.device_authorization_endpoint:
+            raise CliError(
+                f"{base} does not offer sign-in with a code yet; run `{settings.command('login')}` "
+                "on a machine with a browser, or set CHESO_API_TOKEN"
+            )
+        client_id = _registered_client(oauth, store, base, meta)
+        try:
+            device_code, login = oauth.start_device(meta.device_authorization_endpoint, client_id=client_id)
+        except OAuthProtocolError as e:
+            if e.error == ERROR_INVALID_CLIENT:
+                _forget_client(store, base)
+                raise CliError(
+                    f"The CLI registration is no longer valid. Run `{settings.command('login --device')}` again."
+                ) from e
+            raise
+    with store.locked():
+        creds = store.get(base)
+        creds.pending_device = {
+            "device_code": device_code,
+            "client_id": client_id,
+            "issuer": meta.issuer,
+            "verification_uri": login.verification_uri,
+            "user_code": login.user_code,
+            "expires_at": login.expires_at,
+            "interval": login.interval,
+        }
+        store.put(base, creds)
+    return login
+
+
+def pending_device_login(settings: Settings, store: CredentialStore) -> DeviceLogin | None:
+    """返回当前站点等待用户确认的设备码登录；没有时返回 None。"""
+    pending = store.get(settings.base_url).pending_device
+    if not pending.get("device_code"):
+        return None
+    try:
+        return DeviceLogin(
+            verification_uri=str(pending.get("verification_uri") or ""),
+            user_code=str(pending.get("user_code") or ""),
+            expires_at=float(pending.get("expires_at") or 0),
+            interval=max(float(pending.get("interval") or DEFAULT_DEVICE_INTERVAL), 1.0),
+        )
+    except (TypeError, ValueError):
+        return None
+
+
+def _clear_pending(store: CredentialStore, base: str) -> None:
+    with store.locked():
+        creds = store.get(base)
+        creds.pending_device = {}
+        store.put(base, creds)
+
+
+def _remember_poll(
+    store: CredentialStore, base: str, device_code: str, *, interval: float, backoff: float, next_poll_at: float
+) -> None:
+    """保留轮询节奏，再次运行 ``cheso login --wait`` 时按原节奏继续，避免立即轮询，见 RFC 8628 §3.5。
+
+    ``interval`` 是基础间隔，slow_down 增大后持续生效；``backoff`` 是连续连接超时累计的退避间隔，
+    令牌端点正常答复后恢复为 ``interval``；``next_poll_at`` 是最早下次轮询时间。
+    """
+    with store.locked():
+        creds = store.get(base)
+        if creds.pending_device.get("device_code") != device_code:
+            return  # 等待期间，登录已完成或被另一个命令替换。
+        creds.pending_device["interval"] = interval
+        creds.pending_device["backoff"] = backoff
+        creds.pending_device["next_poll_at"] = next_poll_at
+        store.put(base, creds)
+
+
+def _resume_wait(pending: dict[str, Any], interval: float, now: float) -> float:
+    """运行 ``cheso login --wait`` 后，首次轮询前仍需等待的秒数。"""
+    try:
+        next_poll_at = float(pending.get("next_poll_at") or 0)
+    except (TypeError, ValueError):
+        next_poll_at = 0.0
+    return min(max(next_poll_at - now, 0.0), max(interval, MAX_BACKOFF_INTERVAL))
+
+
+def _resume_backoff(pending: dict[str, Any], interval: float) -> float:
+    """恢复上一条命令累计的连接超时退避间隔，限制在 [interval, max(60 秒, interval)] 内。
+    旧版本保存的记录没有该字段，或字段无效时，从 ``interval`` 开始。
+    """
+    try:
+        backoff = float(pending.get("backoff") or interval)
+    except (TypeError, ValueError):
+        return interval
+    if not math.isfinite(backoff):
+        return interval
+    return min(max(backoff, interval), max(MAX_BACKOFF_INTERVAL, interval))
+
+
+def _give_up(settings: Settings, store: CredentialStore, error: OAuthProtocolError) -> NoReturn:
+    """处理轮询的最终结果：清除待授权登录，并说明后续操作。"""
+    base = settings.base_url
+    _clear_pending(store, base)
+    if error.error == ERROR_ACCESS_DENIED:
+        raise CliError("The sign-in was denied in the browser.", kind=KIND_LOGIN_DENIED) from error
+    if error.error in (ERROR_EXPIRED_TOKEN, ERROR_INVALID_GRANT):
+        raise _expired(settings) from error
+    if error.error == ERROR_INVALID_CLIENT:
+        _forget_client(store, base)
+    raise error
+
+
+def wait_device_login(
+    settings: Settings,
+    store: CredentialStore,
+    *,
+    deadline: Deadline,
+    poll_first: bool,
+    transport: httpx.BaseTransport | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+    now: Callable[[], float] = time.time,
+    out: TextIO,
+) -> SiteCredentials | None:
+    """轮询令牌端点，直到用户允许。成功时返回已保存的登录；用户尚未回答而 ``deadline`` 已到时返回 None。
+    超时后保留待授权登录，可再次运行 ``cheso login --wait``。被拒绝或已过期时清除记录并抛出 CliError。
+
+    ``deadline`` 约束此处的每个请求，包括读取完整响应。成功登录的凭据保存不会被截断；
+    撤销被替换的旧登录可额外使用 AFTER_LOGIN_GRACE。
+    若允许授权的响应尚未完整到达就超时，此次授权已被消费，下次 ``cheso login --wait`` 会报告 login_expired。
+    """
+    base = settings.base_url
+    pending = dict(store.get(base).pending_device)
+    login = pending_device_login(settings, store)
+    if login is None:
+        raise UsageError(f"no sign-in is waiting; start one with `{settings.command('login --device')}`")
+    device_code, client_id = str(pending["device_code"]), str(pending.get("client_id") or "")
+    # 短码过期和 --timeout 使用同一时钟，以统一方式检查截止时间。
+    expires = Deadline(deadline.clock() + (login.expires_at - now()), deadline.clock)
+    interval = login.interval
+    # 续等时沿用上一条命令的退避级数：把一次等待拆成多条命令，不应清除连续连接超时的退避。
+    backoff = _resume_backoff(pending, interval)
+    wait_for = _resume_wait(pending, interval, now()) if poll_first else interval
+    with OAuthClient(settings, transport=transport, now=now) as oauth, oauth.time_limit(deadline):
+        try:
+            meta = oauth.metadata()
+        except TimeLimitReached:
+            return None
+        if meta.issuer != pending.get("issuer"):
+            _clear_pending(store, base)
+            raise CliError(
+                f"the waiting sign-in was started with another server; run `{settings.command('login --device')}`",
+                kind=KIND_LOGIN_EXPIRED,
+            )
+        while True:
+            if expires.expired():
+                _clear_pending(store, base)
+                raise _expired(settings)
+            if wait_for > 0:
+                if deadline.clock() + wait_for >= deadline.at:
+                    return None
+                # 等待时间不能超过短码有效期；退避间隔可能大于剩余有效时间。
+                sleep(min(wait_for, max(expires.at - deadline.clock(), 0.0)))
+                if expires.expired():
+                    continue
+            if deadline.expired():
+                return None
+            wait_for = interval
+            try:
+                tokens = oauth.poll_device(meta.token_endpoint, client_id=client_id, device_code=device_code)
+            except TimeLimitReached:
+                # 轮询可能已到达服务器，但没有得到答复：下次 --wait 先按当前节奏等待，
+                # 即基础间隔，或连续连接超时后的退避间隔；退避级数保持不变。
+                _remember_poll(
+                    store, base, device_code, interval=interval, backoff=backoff, next_poll_at=now() + backoff
+                )
+                return None
+            except OAuthProtocolError as e:
+                if e.error == ERROR_SLOW_DOWN:
+                    interval += SLOW_DOWN_STEP
+                    wait_for = backoff = interval
+                elif e.http_status is not None and e.http_status >= 500:
+                    # 5xx 不算正常答复：按基础间隔重试，退避级数不变（没有错误体的 5xx 走下面的 CliError，处理相同）。
+                    print(f"temporary server error ({e.error}); retrying", file=out)
+                elif e.error == ERROR_AUTHORIZATION_PENDING:
+                    backoff = interval  # 令牌端点正常答复，退避恢复为基础间隔。
+                else:
+                    _give_up(settings, store, e)
+            except OAuthTimeout as e:
+                # RFC 8628 §3.5：连接超时后降低轮询频率，使用指数退避。
+                backoff = min(backoff * 2, max(MAX_BACKOFF_INTERVAL, interval))
+                wait_for = backoff
+                print(f"temporary error ({e.message}); retrying in {wait_for:.0f} s", file=out)
+            except CliError as e:
+                # 其他网络错误不结束服务器上的待授权登录，在截止时间前继续重试。
+                print(f"temporary error ({e.message}); retrying", file=out)
+            else:
+                with oauth.time_limit(after_login(deadline)):
+                    return _save_login(oauth, store, base, meta, client_id, tokens)
+            _remember_poll(store, base, device_code, interval=interval, backoff=backoff, next_poll_at=now() + wait_for)
+
+
+def _expired(settings: Settings) -> CliError:
+    return CliError(
+        f"The sign-in code expired before it was approved. Run `{settings.command('login --device')}` again.",
+        kind=KIND_LOGIN_EXPIRED,
+        extra={"next": settings.command("login --device")},
+    )
+
+
+def _registered_client(oauth: OAuthClient, store: CredentialStore, base: str, meta: ServerMetadata) -> str:
+    """复用当前站点保存的客户端注册；没有注册信息时先注册。"""
+    creds = store.get(base)
+    if creds.client_id and creds.issuer == meta.issuer:
+        return creds.client_id
+    client_id = oauth.register(meta)
+    with store.locked():
+        creds = store.get(base)
+        creds.client_id = client_id
+        creds.issuer = meta.issuer
+        creds.token_endpoint = meta.token_endpoint
+        creds.revocation_endpoint = meta.revocation_endpoint
+        store.put(base, creds)
+    return client_id
+
+
+def _forget_client(store: CredentialStore, base: str) -> None:
+    with store.locked():
+        creds = store.get(base)
+        creds.client_id = ""
+        creds.clear_tokens()
+        store.put(base, creds)
+
+
+def logout(
+    settings: Settings,
+    store: CredentialStore,
+    *,
+    transport: httpx.BaseTransport | None = None,
+    out: TextIO,
+) -> bool:
+    """尽力撤销服务器上的授权，并删除本地令牌；返回此前是否存在令牌。"""
+    base = settings.base_url
+    with store.locked():
+        creds = store.get(base)
+        if not creds.logged_in:
+            return False
+        token, hint = (
+            (creds.refresh_token, "refresh_token") if creds.refresh_token else (creds.access_token, "access_token")
+        )
+        endpoint = creds.revocation_endpoint
+        try:
+            with OAuthClient(settings, transport=transport) as oauth:
+                if not endpoint:
+                    endpoint = oauth.metadata().revocation_endpoint
+                if endpoint:
+                    oauth.revoke(endpoint, client_id=creds.client_id, token=token, hint=hint)
+                else:
+                    print("warning: the server offers no revocation endpoint; only local tokens were removed", file=out)
+        except CliError as e:
+            print(
+                f"warning: could not revoke the authorization on the server ({e.message}); "
+                "remove it under Authorized apps on the Cheso website",
+                file=out,
+            )
+        creds.clear_tokens()
+        creds.pending_device = {}
+        store.put(base, creds)
+    return True