@josephyan/qingflow-app-user-mcp 0.2.0-beta.991 → 0.2.0-beta.993

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.991
+npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.993
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.991 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.993 qingflow-app-user-mcp
 ```
 
 Environment:

package/docs/local-agent-install.md

@@ -24,7 +24,6 @@
 
 - 对 stdio MCP 来说，主路径仍然只有 `auth_use_credential`。
 - 如果你是在终端里直接使用 `qingflow` CLI，可以额外使用 `qingflow auth login` 作为“人类登录”入口；默认会提示轻流邮箱和隐藏密码，拿到 `token` 后建立本地 CLI 会话。
-- 如果需要浏览器 Authorization Code + PKCE 或 Device Flow，请显式使用 `qingflow auth login --browser` 或 `qingflow auth login --device`；这条 OAuth 路径最终拿到 `credential` 后再复用 `auth_use_credential` 建会话。
 - 也就是说，这次新增的是 CLI 的登录入口，不是给 MCP 增加第二套会话模型。
 
 ## npm 安装器适用场景

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.991",
+  "version": "0.2.0-beta.993",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b991"
+version = "0.2.0b993"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/src/qingflow_mcp/__init__.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 __all__ = ["__version__"]
 
-_FALLBACK_VERSION = "0.2.0b991"
+_FALLBACK_VERSION = "0.2.0b993"
 
 
 def _resolve_local_pyproject_version() -> str | None:

package/src/qingflow_mcp/cli/commands/auth.py

@@ -6,7 +6,6 @@ import sys
 
 from ...errors import QingflowApiError
 from ..context import CliContext
-from ..oauth_login import login_with_cli_oauth
 from ..qingflow_login import login_with_qingflow_password
 from .common import read_secret_arg
 
@@ -15,17 +14,9 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     parser = subparsers.add_parser("auth", help="认证与会话")
     auth_subparsers = parser.add_subparsers(dest="auth_command", required=True)
 
-    login = auth_subparsers.add_parser("login", help="登录 CLI：默认轻流账号密码交互；--browser 使用 OAuth")
+    login = auth_subparsers.add_parser("login", help="登录 CLI：轻流账号密码交互")
     login.add_argument("--base-url")
     login.add_argument("--qf-version")
-    login.add_argument("--client-id")
-    login.add_argument("--authorization-endpoint")
-    login.add_argument("--token-endpoint")
-    login.add_argument("--device-authorization-endpoint")
-    login.add_argument("--scope")
-    login.add_argument("--credential-field")
-    login.add_argument("--browser", action="store_true", help="使用浏览器 OAuth 登录；无浏览器时可配合 --device")
-    login.add_argument("--device", action="store_true", help="使用 OAuth Device Flow（隐含 --browser）")
     login.add_argument("--email", help="轻流账号邮箱；不传时在交互终端提示输入")
     login.add_argument("--password", help="轻流账号密码；建议仅用于本地调试，脚本请优先使用 --password-stdin")
     login.add_argument("--password-stdin", action="store_true", help="从标准输入读取轻流账号密码")
@@ -49,86 +40,30 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
 
 def _handle_login(args: argparse.Namespace, context: CliContext) -> dict:
-    login_summary: dict[str, str | None]
-    if _should_use_browser_login(args):
-        if _has_account_login_inputs(args):
-            raise QingflowApiError.config_error(
-                "Choose either account/password login or --browser OAuth login; do not combine both."
-            )
-        oauth_result = login_with_cli_oauth(
-            base_url=args.base_url,
-            client_id=args.client_id,
-            authorization_endpoint=args.authorization_endpoint,
-            token_endpoint=args.token_endpoint,
-            device_authorization_endpoint=args.device_authorization_endpoint,
-            scope=args.scope,
-            credential_field=args.credential_field,
-            force_device=bool(args.device),
-        )
-        result = context.auth.auth_use_credential(
-            profile=args.profile,
-            base_url=args.base_url,
-            qf_version=args.qf_version,
-            credential=oauth_result.credential,
-            persist=bool(args.persist),
-        )
-        login_summary = {
-            "flow": oauth_result.flow,
-            "authorize_url": oauth_result.authorize_url,
-            "verification_uri": oauth_result.verification_uri,
-            "user_code": oauth_result.user_code,
-        }
-    else:
-        email = _resolve_login_email(args)
-        password = _resolve_login_password(args)
-        login_result = login_with_qingflow_password(
-            base_url=args.base_url,
-            email=email,
-            password=password,
-        )
-        result = context.auth.auth_use_token(
-            profile=args.profile,
-            base_url=args.base_url,
-            qf_version=args.qf_version,
-            token=login_result.token,
-            login_token=login_result.login_token,
-            user_info=login_result.user_info,
-            persist=bool(args.persist),
-        )
-        login_summary = {
-            "flow": login_result.flow,
-            "authorize_url": None,
-            "verification_uri": None,
-            "user_code": None,
-        }
+    email = _resolve_login_email(args)
+    password = _resolve_login_password(args)
+    login_result = login_with_qingflow_password(
+        base_url=args.base_url,
+        email=email,
+        password=password,
+    )
+    result = context.auth.auth_use_token(
+        profile=args.profile,
+        base_url=args.base_url,
+        qf_version=args.qf_version,
+        token=login_result.token,
+        login_token=login_result.login_token,
+        user_info=login_result.user_info,
+        persist=bool(args.persist),
+    )
     warnings = list(result.get("warnings") or []) if isinstance(result, dict) else []
     if isinstance(result, dict):
-        result["cli_auth"] = {key: value for key, value in login_summary.items() if value}
+        result["cli_auth"] = {"flow": login_result.flow}
         if warnings:
             result["warnings"] = warnings
     return result
 
 
-def _should_use_browser_login(args: argparse.Namespace) -> bool:
-    return any(
-        bool(getattr(args, name, None))
-        for name in (
-            "browser",
-            "device",
-            "client_id",
-            "authorization_endpoint",
-            "token_endpoint",
-            "device_authorization_endpoint",
-            "scope",
-            "credential_field",
-        )
-    )
-
-
-def _has_account_login_inputs(args: argparse.Namespace) -> bool:
-    return bool(args.email or args.password or bool(args.password_stdin))
-
-
 def _resolve_login_email(args: argparse.Namespace) -> str:
     email = str(args.email or "").strip()
     if email:
@@ -136,7 +71,7 @@ def _resolve_login_email(args: argparse.Namespace) -> str:
     if sys.stdin.isatty():
         return input("Qingflow email: ").strip()
     raise QingflowApiError.config_error(
-        "qingflow auth login needs an interactive terminal, or pass --email with --password-stdin, or use --browser."
+        "qingflow auth login needs an interactive terminal, or pass --email with --password-stdin."
     )
 
 
@@ -150,7 +85,7 @@ def _resolve_login_password(args: argparse.Namespace) -> str:
     if sys.stdin.isatty():
         return getpass.getpass("Qingflow password: ")
     raise QingflowApiError.config_error(
-        "qingflow auth login needs an interactive terminal, --password-stdin, or --browser."
+        "qingflow auth login needs an interactive terminal or --password-stdin."
     )
 
 

package/src/qingflow_mcp/tools/auth_tools.py

@@ -269,6 +269,15 @@ class AuthTools(ToolBase):
         )
         if selected_ws_id is not None:
             session_profile = self.sessions.select_workspace(profile, ws_id=selected_ws_id, ws_name=selected_ws_name)
+        backend_session = self.sessions.get_backend_session(profile)
+        permission_level = (
+            self._workspace_permission_level(
+                session_profile=session_profile,
+                backend_session=backend_session,
+            )
+            if backend_session is not None
+            else None
+        )
 
         return {
             "profile": session_profile.profile,
@@ -282,6 +291,7 @@ class AuthTools(ToolBase):
             "selected_ws_name": session_profile.selected_ws_name,
             "suggested_ws_id": session_profile.selected_ws_id,
             "suggested_ws_name": session_profile.selected_ws_name,
+            "permission_level": permission_level,
             "persisted": session_profile.persisted,
             "request_route": self._request_route_payload(
                 BackendRequestContext(
@@ -781,6 +791,13 @@ class AuthTools(ToolBase):
         if ws_id is None:
             return default_payload, []
 
+        permission_level = self._workspace_permission_level(
+            session_profile=session_profile,
+            backend_session=backend_session,
+        )
+        payload = dict(default_payload)
+        payload["permission_level"] = permission_level
+
         context = BackendRequestContext(
             base_url=backend_session.base_url,
             token=backend_session.token,
@@ -788,12 +805,6 @@ class AuthTools(ToolBase):
             qf_version=backend_session.qf_version,
             qf_version_source=backend_session.qf_version_source,
         )
-        permission_level = self._resolve_permission_level(
-            self._workspace_auth(context, ws_id=ws_id)
-        )
-        payload = dict(default_payload)
-        payload["permission_level"] = permission_level
-
         member = self._lookup_current_member(
             context=context,
             uid=session_profile.uid,
@@ -815,6 +826,25 @@ class AuthTools(ToolBase):
         payload["roles"] = self._compact_roles(member)
         return payload, []
 
+    def _workspace_permission_level(
+        self,
+        *,
+        session_profile,  # type: ignore[no-untyped-def]
+        backend_session,  # type: ignore[no-untyped-def]
+    ) -> str | None:
+        """Resolve the selected workspace permission label without requiring member lookup."""
+        ws_id = session_profile.selected_ws_id
+        if ws_id is None:
+            return None
+        context = BackendRequestContext(
+            base_url=backend_session.base_url,
+            token=backend_session.token,
+            ws_id=ws_id,
+            qf_version=backend_session.qf_version,
+            qf_version_source=backend_session.qf_version_source,
+        )
+        return self._resolve_permission_level(self._workspace_auth(context, ws_id=ws_id))
+
     def _workspace_auth(self, context: BackendRequestContext, *, ws_id: int) -> int | None:
         """执行内部辅助逻辑。"""
         workspace = self._fetch_workspace_auth_from_detail(context, ws_id=ws_id)

package/src/qingflow_mcp/cli/oauth_login.py

@@ -1,626 +0,0 @@
-from __future__ import annotations
-
-import base64
-import hashlib
-import json
-import os
-import sys
-import threading
-import time
-import webbrowser
-from dataclasses import dataclass
-from http.server import BaseHTTPRequestHandler, HTTPServer
-from typing import Any
-from urllib.parse import parse_qs, urlencode, urljoin, urlparse
-from uuid import uuid4
-
-import httpx
-
-from ..config import get_config_value, get_timeout_seconds
-from ..errors import QingflowApiError
-
-
-_DEFAULT_SCOPE = "openid profile email"
-_DEFAULT_CALLBACK_HOST = "127.0.0.1"
-_DEFAULT_CALLBACK_PATH = "/callback"
-_DEFAULT_BROWSER_TIMEOUT_SECONDS = 180.0
-_DEFAULT_DEVICE_INTERVAL_SECONDS = 5.0
-_SUCCESS_HTML = """<!doctype html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <title>Qingflow CLI Login Complete</title>
-</head>
-<body>
-  <p>Qingflow CLI login complete. You can return to the terminal.</p>
-</body>
-</html>
-"""
-
-
-@dataclass(slots=True)
-class CliOAuthConfig:
-    client_id: str
-    authorization_endpoint: str
-    token_endpoint: str
-    device_authorization_endpoint: str | None
-    scope: str
-    callback_host: str
-    callback_port: int
-    callback_path: str
-    browser_timeout_seconds: float
-    credential_field: str
-
-
-@dataclass(slots=True)
-class CliOAuthCredential:
-    credential: str
-    flow: str
-    authorize_url: str | None = None
-    verification_uri: str | None = None
-    user_code: str | None = None
-    warnings: list[str] | None = None
-
-
-class _LoopbackAuthServer:
-    def __init__(
-        self,
-        *,
-        host: str,
-        port: int,
-        callback_path: str,
-        timeout_seconds: float,
-        status_stream,
-    ) -> None:
-        self._host = host
-        self._port = port
-        self._callback_path = callback_path
-        self._timeout_seconds = timeout_seconds
-        self._status_stream = status_stream
-        self._event = threading.Event()
-        self._params: dict[str, str] | None = None
-        self._error: str | None = None
-        self._server = self._build_server()
-        self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
-
-    @property
-    def redirect_uri(self) -> str:
-        return f"http://{self._host}:{self._server.server_port}{self._callback_path}"
-
-    def start(self) -> None:
-        self._thread.start()
-
-    def wait(self) -> dict[str, str]:
-        if not self._event.wait(timeout=self._timeout_seconds):
-            raise QingflowApiError.config_error(
-                f"timed out waiting for browser callback after {int(self._timeout_seconds)} seconds"
-            )
-        if self._error:
-            raise QingflowApiError(category="auth", message=self._error)
-        if self._params is None:
-            raise QingflowApiError(category="auth", message="browser callback did not return any parameters")
-        return self._params
-
-    def close(self) -> None:
-        self._server.shutdown()
-        self._server.server_close()
-        self._thread.join(timeout=1)
-
-    def _build_server(self) -> HTTPServer:
-        parent = self
-
-        class CallbackServer(HTTPServer):
-            allow_reuse_address = True
-
-        class Handler(BaseHTTPRequestHandler):
-            def do_GET(self) -> None:  # noqa: N802
-                parsed = urlparse(self.path)
-                if parsed.path != parent._callback_path:
-                    self.send_error(404)
-                    return
-                query = {
-                    key: values[0]
-                    for key, values in parse_qs(parsed.query, keep_blank_values=True).items()
-                    if values
-                }
-                parent._params = query
-                parent._event.set()
-                self.send_response(200)
-                self.send_header("Content-Type", "text/html; charset=utf-8")
-                self.end_headers()
-                self.wfile.write(_SUCCESS_HTML.encode("utf-8"))
-
-            def log_message(self, format: str, *args: object) -> None:  # noqa: A003
-                return
-
-        try:
-            return CallbackServer((self._host, self._port), Handler)
-        except OSError as exc:
-            raise QingflowApiError.config_error(f"failed to start local callback server: {exc}") from exc
-
-
-class CliOAuthLoginHelper:
-    def __init__(
-        self,
-        *,
-        http_client: httpx.Client | None = None,
-        browser_opener=webbrowser.open,
-        sleep_fn=time.sleep,
-        status_stream=None,
-    ) -> None:
-        self._owns_client = http_client is None
-        self._http_client = http_client or httpx.Client(
-            timeout=get_timeout_seconds(),
-            follow_redirects=True,
-            trust_env=False,
-        )
-        self._browser_opener = browser_opener
-        self._sleep = sleep_fn
-        self._status_stream = status_stream or sys.stderr
-
-    def close(self) -> None:
-        if self._owns_client:
-            self._http_client.close()
-
-    def login(
-        self,
-        *,
-        base_url: str | None,
-        client_id: str | None = None,
-        authorization_endpoint: str | None = None,
-        token_endpoint: str | None = None,
-        device_authorization_endpoint: str | None = None,
-        scope: str | None = None,
-        credential_field: str | None = None,
-        force_device: bool = False,
-    ) -> CliOAuthCredential:
-        config = load_cli_oauth_config(
-            base_url=base_url,
-            client_id=client_id,
-            authorization_endpoint=authorization_endpoint,
-            token_endpoint=token_endpoint,
-            device_authorization_endpoint=device_authorization_endpoint,
-            scope=scope,
-            credential_field=credential_field,
-        )
-        if force_device:
-            return self._device_flow(config)
-        try:
-            return self._authorization_code_flow(config)
-        except _BrowserUnavailableError as exc:
-            if not config.device_authorization_endpoint:
-                raise QingflowApiError.config_error(
-                    "browser auth is unavailable and no device_authorization_endpoint is configured"
-                ) from exc
-            self._write_status("Browser unavailable, switching to device flow.")
-            return self._device_flow(config)
-
-    def _authorization_code_flow(self, config: CliOAuthConfig) -> CliOAuthCredential:
-        state = uuid4().hex
-        code_verifier = _generate_code_verifier()
-        code_challenge = _code_challenge_s256(code_verifier)
-        server = _LoopbackAuthServer(
-            host=config.callback_host,
-            port=config.callback_port,
-            callback_path=config.callback_path,
-            timeout_seconds=config.browser_timeout_seconds,
-            status_stream=self._status_stream,
-        )
-        try:
-            server.start()
-            authorize_url = self._build_authorize_url(
-                config=config,
-                redirect_uri=server.redirect_uri,
-                state=state,
-                code_challenge=code_challenge,
-            )
-            self._write_status(f"Opening browser for Qingflow login: {authorize_url}")
-            opened = False
-            try:
-                opened = bool(self._browser_opener(authorize_url))
-            except Exception as exc:  # pragma: no cover - depends on local browser runtime
-                raise _BrowserUnavailableError(str(exc)) from exc
-            if not opened:
-                raise _BrowserUnavailableError("system browser refused to open authorization URL")
-            callback_params = server.wait()
-        finally:
-            server.close()
-
-        if callback_params.get("error"):
-            error_description = callback_params.get("error_description") or callback_params["error"]
-            raise QingflowApiError(category="auth", message=f"authorization failed: {error_description}")
-        returned_state = str(callback_params.get("state") or "")
-        if returned_state != state:
-            raise QingflowApiError(category="auth", message="authorization callback state mismatch")
-        credential = self._extract_credential(callback_params, credential_field=config.credential_field)
-        if credential:
-            return CliOAuthCredential(
-                credential=credential,
-                flow="authorization_code",
-                authorize_url=authorize_url,
-            )
-        code = str(callback_params.get("code") or "").strip()
-        if not code:
-            raise QingflowApiError(category="auth", message="authorization callback did not return a code")
-        token_payload = self._post_form(
-            config.token_endpoint,
-            {
-                "grant_type": "authorization_code",
-                "client_id": config.client_id,
-                "code": code,
-                "redirect_uri": server.redirect_uri,
-                "code_verifier": code_verifier,
-            },
-        )
-        credential = self._extract_credential(token_payload, credential_field=config.credential_field)
-        if not credential:
-            raise QingflowApiError(
-                category="auth",
-                message=(
-                    "token exchange succeeded but did not return a Qingflow credential; "
-                    "configure cli_auth.credential_field if your broker uses a custom field"
-                ),
-            )
-        return CliOAuthCredential(
-            credential=credential,
-            flow="authorization_code",
-            authorize_url=authorize_url,
-        )
-
-    def _device_flow(self, config: CliOAuthConfig) -> CliOAuthCredential:
-        if not config.device_authorization_endpoint:
-            raise QingflowApiError.config_error("device_authorization_endpoint is required for device flow")
-        start_payload = self._post_form(
-            config.device_authorization_endpoint,
-            {
-                "client_id": config.client_id,
-                "scope": config.scope,
-            },
-        )
-        device_code = str(start_payload.get("device_code") or "").strip()
-        if not device_code:
-            raise QingflowApiError(category="auth", message="device authorization did not return device_code")
-        verification_uri = (
-            str(start_payload.get("verification_uri_complete") or "").strip()
-            or str(start_payload.get("verification_uri") or "").strip()
-        )
-        user_code = str(start_payload.get("user_code") or "").strip() or None
-        interval_seconds = _coerce_positive_float(start_payload.get("interval")) or _DEFAULT_DEVICE_INTERVAL_SECONDS
-        expires_in_seconds = _coerce_positive_float(start_payload.get("expires_in")) or config.browser_timeout_seconds
-        if verification_uri:
-            self._write_status(f"Open this URL to continue Qingflow login: {verification_uri}")
-        if user_code:
-            self._write_status(f"Device code: {user_code}")
-        deadline = time.monotonic() + expires_in_seconds
-        interval = interval_seconds
-        while time.monotonic() < deadline:
-            payload, status_code = self._post_form_with_status(
-                config.token_endpoint,
-                {
-                    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
-                    "device_code": device_code,
-                    "client_id": config.client_id,
-                },
-            )
-            if 200 <= status_code < 300:
-                credential = self._extract_credential(payload, credential_field=config.credential_field)
-                if not credential:
-                    raise QingflowApiError(
-                        category="auth",
-                        message=(
-                            "device token exchange succeeded but did not return a Qingflow credential; "
-                            "configure cli_auth.credential_field if your broker uses a custom field"
-                        ),
-                    )
-                return CliOAuthCredential(
-                    credential=credential,
-                    flow="device_code",
-                    verification_uri=verification_uri or None,
-                    user_code=user_code,
-                )
-            error_code = str(payload.get("error") or "").strip()
-            if error_code == "authorization_pending":
-                self._sleep(interval)
-                continue
-            if error_code == "slow_down":
-                interval += interval_seconds
-                self._sleep(interval)
-                continue
-            if error_code:
-                error_description = str(payload.get("error_description") or error_code).strip()
-                raise QingflowApiError(category="auth", message=f"device flow failed: {error_description}")
-            raise QingflowApiError(
-                category="auth",
-                message=f"device flow token polling failed with HTTP {status_code}",
-            )
-        raise QingflowApiError(
-            category="auth",
-            message="device flow expired before authorization completed",
-        )
-
-    def _build_authorize_url(
-        self,
-        *,
-        config: CliOAuthConfig,
-        redirect_uri: str,
-        state: str,
-        code_challenge: str,
-    ) -> str:
-        query = urlencode(
-            {
-                "response_type": "code",
-                "client_id": config.client_id,
-                "redirect_uri": redirect_uri,
-                "scope": config.scope,
-                "state": state,
-                "code_challenge": code_challenge,
-                "code_challenge_method": "S256",
-            }
-        )
-        separator = "&" if "?" in config.authorization_endpoint else "?"
-        return f"{config.authorization_endpoint}{separator}{query}"
-
-    def _post_form(self, url: str, form: dict[str, str]) -> dict[str, Any]:
-        payload, status_code = self._post_form_with_status(url, form)
-        if status_code >= 400:
-            error_text = str(payload.get("error_description") or payload.get("message") or payload.get("error") or "")
-            raise QingflowApiError(category="auth", message=error_text or f"HTTP {status_code}")
-        return payload
-
-    def _post_form_with_status(self, url: str, form: dict[str, str]) -> tuple[dict[str, Any], int]:
-        try:
-            response = self._http_client.post(
-                url,
-                data=form,
-                headers={"Content-Type": "application/x-www-form-urlencoded"},
-            )
-        except httpx.RequestError as exc:
-            raise QingflowApiError(category="network", message=str(exc)) from exc
-        return _parse_response_payload(response), response.status_code
-
-    def _extract_credential(self, payload: dict[str, Any], *, credential_field: str) -> str | None:
-        if not payload:
-            return None
-        candidate = _extract_nested_field(payload, credential_field)
-        if candidate:
-            return candidate
-        for alias in ("credential", "qingflow_credential", "x-qingflow-client-id"):
-            candidate = _extract_nested_field(payload, alias)
-            if candidate:
-                return candidate
-        return None
-
-    def _write_status(self, message: str) -> None:
-        self._status_stream.write(message.rstrip() + "\n")
-        self._status_stream.flush()
-
-
-class _BrowserUnavailableError(RuntimeError):
-    pass
-
-
-def login_with_cli_oauth(
-    *,
-    base_url: str | None,
-    client_id: str | None = None,
-    authorization_endpoint: str | None = None,
-    token_endpoint: str | None = None,
-    device_authorization_endpoint: str | None = None,
-    scope: str | None = None,
-    credential_field: str | None = None,
-    force_device: bool = False,
-) -> CliOAuthCredential:
-    helper = CliOAuthLoginHelper()
-    try:
-        return helper.login(
-            base_url=base_url,
-            client_id=client_id,
-            authorization_endpoint=authorization_endpoint,
-            token_endpoint=token_endpoint,
-            device_authorization_endpoint=device_authorization_endpoint,
-            scope=scope,
-            credential_field=credential_field,
-            force_device=force_device,
-        )
-    finally:
-        helper.close()
-
-
-def load_cli_oauth_config(
-    *,
-    base_url: str | None,
-    client_id: str | None = None,
-    authorization_endpoint: str | None = None,
-    token_endpoint: str | None = None,
-    device_authorization_endpoint: str | None = None,
-    scope: str | None = None,
-    credential_field: str | None = None,
-) -> CliOAuthConfig:
-    resolved_base_url = str(base_url or "").strip() or None
-    resolved_client_id = _first_text(
-        client_id,
-        os.getenv("QINGFLOW_CLI_AUTH_CLIENT_ID"),
-        get_config_value("cli_auth.client_id", default=None),
-    )
-    resolved_authorization_endpoint = _resolve_endpoint(
-        authorization_endpoint,
-        resolved_base_url,
-        env_var="QINGFLOW_CLI_AUTH_AUTHORIZATION_ENDPOINT",
-        config_key="cli_auth.authorization_endpoint",
-    )
-    resolved_token_endpoint = _resolve_endpoint(
-        token_endpoint,
-        resolved_base_url,
-        env_var="QINGFLOW_CLI_AUTH_TOKEN_ENDPOINT",
-        config_key="cli_auth.token_endpoint",
-    )
-    resolved_device_endpoint = _resolve_endpoint(
-        device_authorization_endpoint,
-        resolved_base_url,
-        env_var="QINGFLOW_CLI_AUTH_DEVICE_AUTHORIZATION_ENDPOINT",
-        config_key="cli_auth.device_authorization_endpoint",
-        required=False,
-    )
-    resolved_scope = _first_text(
-        scope,
-        os.getenv("QINGFLOW_CLI_AUTH_SCOPE"),
-        get_config_value("cli_auth.scope", default=None),
-        fallback=_DEFAULT_SCOPE,
-    )
-    callback_host = _first_text(
-        os.getenv("QINGFLOW_CLI_AUTH_CALLBACK_HOST"),
-        get_config_value("cli_auth.callback_host", default=None),
-        fallback=_DEFAULT_CALLBACK_HOST,
-    )
-    callback_path = _normalize_callback_path(
-        _first_text(
-            os.getenv("QINGFLOW_CLI_AUTH_CALLBACK_PATH"),
-            get_config_value("cli_auth.callback_path", default=None),
-            fallback=_DEFAULT_CALLBACK_PATH,
-        )
-    )
-    callback_port = _coerce_port(
-        os.getenv("QINGFLOW_CLI_AUTH_CALLBACK_PORT")
-        or get_config_value("cli_auth.callback_port", default=0)
-    )
-    browser_timeout_seconds = _coerce_positive_float(
-        os.getenv("QINGFLOW_CLI_AUTH_BROWSER_TIMEOUT_SECONDS")
-        or get_config_value("cli_auth.browser_timeout_seconds", default=_DEFAULT_BROWSER_TIMEOUT_SECONDS)
-    ) or _DEFAULT_BROWSER_TIMEOUT_SECONDS
-    resolved_credential_field = _first_text(
-        credential_field,
-        os.getenv("QINGFLOW_CLI_AUTH_CREDENTIAL_FIELD"),
-        get_config_value("cli_auth.credential_field", default=None),
-        fallback="credential",
-    )
-
-    missing: list[str] = []
-    if not resolved_client_id:
-        missing.append("cli_auth.client_id / QINGFLOW_CLI_AUTH_CLIENT_ID")
-    if not resolved_authorization_endpoint:
-        missing.append("cli_auth.authorization_endpoint / QINGFLOW_CLI_AUTH_AUTHORIZATION_ENDPOINT")
-    if not resolved_token_endpoint:
-        missing.append("cli_auth.token_endpoint / QINGFLOW_CLI_AUTH_TOKEN_ENDPOINT")
-    if missing:
-        raise QingflowApiError.config_error(
-            "CLI auth login requires OAuth config: " + ", ".join(missing)
-        )
-
-    return CliOAuthConfig(
-        client_id=resolved_client_id,
-        authorization_endpoint=resolved_authorization_endpoint,
-        token_endpoint=resolved_token_endpoint,
-        device_authorization_endpoint=resolved_device_endpoint,
-        scope=resolved_scope,
-        callback_host=callback_host,
-        callback_port=callback_port,
-        callback_path=callback_path,
-        browser_timeout_seconds=browser_timeout_seconds,
-        credential_field=resolved_credential_field,
-    )
-
-
-def _resolve_endpoint(
-    override: str | None,
-    base_url: str | None,
-    *,
-    env_var: str,
-    config_key: str,
-    required: bool = True,
-) -> str | None:
-    value = _first_text(
-        override,
-        os.getenv(env_var),
-        get_config_value(config_key, default=None),
-    )
-    if not value:
-        return None if not required else ""
-    parsed = urlparse(value)
-    if parsed.scheme and parsed.netloc:
-        return value
-    if not base_url:
-        raise QingflowApiError.config_error(
-            f"{config_key} is relative, but no base_url was provided to resolve it"
-        )
-    return urljoin(base_url.rstrip("/") + "/", value)
-
-
-def _first_text(*values: Any, fallback: str | None = None) -> str | None:
-    for value in values:
-        text = str(value or "").strip()
-        if text:
-            return text
-    return fallback
-
-
-def _normalize_callback_path(value: str) -> str:
-    normalized = str(value or "").strip() or _DEFAULT_CALLBACK_PATH
-    return normalized if normalized.startswith("/") else f"/{normalized}"
-
-
-def _coerce_positive_float(value: Any) -> float | None:
-    if value in (None, ""):
-        return None
-    try:
-        parsed = float(value)
-    except (TypeError, ValueError):
-        return None
-    return parsed if parsed > 0 else None
-
-
-def _coerce_port(value: Any) -> int:
-    if value in (None, ""):
-        return 0
-    try:
-        parsed = int(value)
-    except (TypeError, ValueError):
-        raise QingflowApiError.config_error("cli_auth.callback_port must be an integer") from None
-    if parsed < 0 or parsed > 65535:
-        raise QingflowApiError.config_error("cli_auth.callback_port must be between 0 and 65535")
-    return parsed
-
-
-def _generate_code_verifier() -> str:
-    random_bytes = os.urandom(32)
-    return base64.urlsafe_b64encode(random_bytes).decode("ascii").rstrip("=")
-
-
-def _code_challenge_s256(code_verifier: str) -> str:
-    digest = hashlib.sha256(code_verifier.encode("ascii")).digest()
-    return base64.urlsafe_b64encode(digest).decode("ascii").rstrip("=")
-
-
-def _parse_response_payload(response: httpx.Response) -> dict[str, Any]:
-    if not response.content:
-        return {}
-    content_type = str(response.headers.get("Content-Type") or "").lower()
-    if "application/json" in content_type:
-        payload = response.json()
-        return payload if isinstance(payload, dict) else {"value": payload}
-    if "application/x-www-form-urlencoded" in content_type:
-        return {
-            key: values[0]
-            for key, values in parse_qs(response.text, keep_blank_values=True).items()
-            if values
-        }
-    try:
-        payload = response.json()
-    except ValueError:
-        try:
-            return json.loads(response.text)
-        except (TypeError, ValueError):
-            return {"message": response.text}
-    return payload if isinstance(payload, dict) else {"value": payload}
-
-
-def _extract_nested_field(payload: dict[str, Any], key: str) -> str | None:
-    value = payload.get(key)
-    if isinstance(value, str) and value.strip():
-        return value.strip()
-    for container_key in ("data", "result", "payload"):
-        nested = payload.get(container_key)
-        if isinstance(nested, dict):
-            nested_value = nested.get(key)
-            if isinstance(nested_value, str) and nested_value.strip():
-                return nested_value.strip()
-    return None