@qingflow-tech/qingflow-cli 1.1.43-beta.5 → 1.1.44-beta.1

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

@@ -3,9 +3,13 @@ from __future__ import annotations
 import argparse
 import getpass
 import sys
+import webbrowser
 
+from ...config import get_cli_oauth_resource_url, get_default_base_url, normalize_base_url
 from ...errors import QingflowApiError
 from ..context import CliContext
+from ..oauth_callback import OAuthCallbackServer
+from ..oauth_client import PKCEAuthorization
 from ..qingflow_login import login_with_qingflow_password
 from .common import read_secret_arg
 
@@ -15,11 +19,13 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     auth_subparsers = parser.add_subparsers(dest="auth_command", required=True)
 
     login = auth_subparsers.add_parser("login", help="登录 CLI：轻流账号密码交互")
+    login.add_argument("--method", choices=("password", "oauth"), default="password")
     login.add_argument("--base-url")
     login.add_argument("--qf-version")
     login.add_argument("--email", help="轻流账号邮箱；不传时在交互终端提示输入")
     login.add_argument("--password", help="轻流账号密码；建议仅用于本地调试，脚本请优先使用 --password-stdin")
     login.add_argument("--password-stdin", action="store_true", help="从标准输入读取轻流账号密码")
+    login.add_argument("--no-browser", action="store_true", help="不自动打开 OAuth 授权页")
     login.add_argument("--persist", action=argparse.BooleanOptionalAction, default=True)
     login.set_defaults(handler=_handle_login, format_hint="auth_whoami")
 
@@ -40,30 +46,94 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
 
 def _handle_login(args: argparse.Namespace, context: CliContext) -> dict:
-    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),
-    )
+    if args.method == "oauth":
+        return _handle_oauth_login(args, context)
+    if bool(args.no_browser):
+        raise QingflowApiError.config_error("--no-browser is only valid with --method oauth.")
+    _begin_legacy_login(context, args.profile)
+    try:
+        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),
+        )
+    except Exception:
+        _cancel_legacy_login(context, args.profile)
+        raise
+    switch_warnings = _complete_legacy_login(context, args.profile)
     warnings = list(result.get("warnings") or []) if isinstance(result, dict) else []
+    warnings.extend(switch_warnings)
     if isinstance(result, dict):
         result["cli_auth"] = {"flow": login_result.flow}
+        result["active_auth_type"] = "legacy_token"
+        result["auth_source"] = "legacy_token"
         if warnings:
             result["warnings"] = warnings
     return result
 
 
+def _handle_oauth_login(args: argparse.Namespace, context: CliContext) -> dict:
+    if args.email or args.password or bool(args.password_stdin):
+        raise QingflowApiError.config_error(
+            "--email, --password, and --password-stdin cannot be used with --method oauth."
+        )
+    if not bool(args.persist):
+        raise QingflowApiError.config_error("OAuth login must persist its refresh token; --no-persist is not supported.")
+    base_url = normalize_base_url(args.base_url) or get_default_base_url()
+    if not base_url:
+        raise QingflowApiError.config_error(
+            "base_url is required or configure default_base_url / QINGFLOW_MCP_DEFAULT_BASE_URL."
+        )
+    oauth_client = context.sessions.oauth.oauth_client
+    metadata = oauth_client.discover(base_url)
+    resource = get_cli_oauth_resource_url()
+    pkce = PKCEAuthorization.create()
+    callback = OAuthCallbackServer(pkce.state)
+    callback.start()
+    authorization_url = oauth_client.authorization_url(
+        metadata,
+        redirect_uri=callback.redirect_uri,
+        resource=resource,
+        pkce=pkce,
+    )
+    stream = getattr(args, "_stderr_stream", sys.stderr)
+    if bool(args.no_browser):
+        stream.write(f"Open this URL to authorize Qingflow CLI:\n{authorization_url}\n")
+    elif not webbrowser.open(authorization_url, new=1, autoraise=True):
+        stream.write(f"Could not open a browser. Open this URL to authorize Qingflow CLI:\n{authorization_url}\n")
+    try:
+        callback_result = callback.wait(timeout_seconds=300.0)
+        bundle = oauth_client.exchange_code(
+            metadata,
+            code=callback_result.code,
+            redirect_uri=callback.redirect_uri,
+            verifier=pkce.verifier,
+        )
+        result = context.auth.auth_use_oauth_token(
+            profile=args.profile,
+            base_url=base_url,
+            qf_version=args.qf_version,
+            issuer=metadata.issuer,
+            resource=resource,
+            bundle=bundle,
+        )
+    finally:
+        callback.close()
+    result["cli_auth"] = {"flow": "oauth_pkce"}
+    return result
+
+
 def _resolve_login_email(args: argparse.Namespace) -> str:
     email = str(args.email or "").strip()
     if email:
@@ -95,13 +165,25 @@ def _handle_use_credential(args: argparse.Namespace, context: CliContext) -> dic
         if args.credential or bool(args.credential_stdin)
         else ""
     )
-    return context.auth.auth_use_credential(
-        profile=args.profile,
-        base_url=args.base_url,
-        qf_version=args.qf_version,
-        credential=credential,
-        persist=bool(args.persist),
-    )
+    _begin_legacy_login(context, args.profile)
+    try:
+        result = context.auth.auth_use_credential(
+            profile=args.profile,
+            base_url=args.base_url,
+            qf_version=args.qf_version,
+            credential=credential,
+            persist=bool(args.persist),
+        )
+    except Exception:
+        _cancel_legacy_login(context, args.profile)
+        raise
+    warnings = list(result.get("warnings") or []) if isinstance(result, dict) else []
+    warnings.extend(_complete_legacy_login(context, args.profile))
+    result["active_auth_type"] = "credential"
+    result["auth_source"] = "credential"
+    if warnings:
+        result["warnings"] = warnings
+    return result
 
 
 def _handle_whoami(args: argparse.Namespace, context: CliContext) -> dict:
@@ -110,3 +192,23 @@ def _handle_whoami(args: argparse.Namespace, context: CliContext) -> dict:
 
 def _handle_logout(args: argparse.Namespace, context: CliContext) -> dict:
     return context.auth.auth_logout(profile=args.profile, forget_persisted=bool(args.forget_persisted))
+
+
+def _begin_legacy_login(context: CliContext, profile: str) -> None:
+    method = getattr(context.sessions, "begin_legacy_login", None)
+    if callable(method):
+        method(profile)
+
+
+def _cancel_legacy_login(context: CliContext, profile: str) -> None:
+    method = getattr(context.sessions, "cancel_legacy_login", None)
+    if callable(method):
+        method(profile)
+
+
+def _complete_legacy_login(context: CliContext, profile: str) -> list[dict[str, str]]:
+    method = getattr(context.sessions, "complete_legacy_login", None)
+    if not callable(method):
+        return []
+    warnings = method(profile)
+    return warnings if isinstance(warnings, list) else []

package/src/qingflow_mcp/cli/context.py

@@ -2,7 +2,10 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
+from ..auth_provider import CliSessionFacade, OAuthSessionProvider
 from ..backend_client import BackendClient
+from ..oauth_profile_store import OAuthProfileStore
+from ..oauth_token_store import OAuthTokenStore
 from ..session_store import SessionStore
 from ..tools.ai_builder_tools import AiBuilderTools
 from ..tools.app_tools import AppTools
@@ -16,11 +19,12 @@ from ..tools.record_tools import RecordTools
 from ..tools.resource_read_tools import ResourceReadTools
 from ..tools.task_context_tools import TaskContextTools
 from ..tools.workspace_tools import WorkspaceTools
+from .oauth_client import OAuthClient
 
 
 @dataclass(slots=True)
 class CliContext:
-    sessions: SessionStore
+    sessions: CliSessionFacade
     backend: BackendClient
     auth: AuthTools
     workspace: WorkspaceTools
@@ -36,11 +40,18 @@ class CliContext:
     builder: AiBuilderTools
 
     def close(self) -> None:
+        self.sessions.close()
         self.backend.close()
 
 
 def build_cli_context() -> CliContext:
-    sessions = SessionStore()
+    legacy_sessions = SessionStore()
+    oauth_profiles = OAuthProfileStore()
+    oauth_tokens = OAuthTokenStore(oauth_profiles)
+    sessions = CliSessionFacade(
+        legacy_sessions,
+        OAuthSessionProvider(oauth_profiles, oauth_tokens, OAuthClient()),
+    )
     backend = BackendClient()
     return CliContext(
         sessions=sessions,

package/src/qingflow_mcp/cli/main.py

@@ -458,6 +458,13 @@ def _emit_cli_effective_context_notice(args: argparse.Namespace, context: CliCon
         session_profile = None
     workspace_id = getattr(session_profile, "selected_ws_id", None) if session_profile is not None else None
     workspace_name = getattr(session_profile, "selected_ws_name", None) if session_profile is not None else None
+    active_auth_type = None
+    auth_type_resolver = getattr(sessions, "active_auth_type", None)
+    if callable(auth_type_resolver):
+        try:
+            active_auth_type = str(auth_type_resolver(profile_name) or "none")
+        except Exception:
+            active_auth_type = "config_error"
     if workspace_id is None:
         workspace_label = "(not selected)"
     elif workspace_name:
@@ -466,7 +473,8 @@ def _emit_cli_effective_context_notice(args: argparse.Namespace, context: CliCon
         workspace_label = str(workspace_id)
     lines: list[str] = []
     if not hide_context_line:
-        lines.append(f"Context: profile={profile_name} workspace={workspace_label}")
+        auth_label = f" auth={active_auth_type}" if active_auth_type is not None else ""
+        lines.append(f"Context: profile={profile_name}{auth_label} workspace={workspace_label}")
     if spec.cli_context_write and profile_name == "default":
         lines.append("Warning: using default profile for a workspace-sensitive write command")
     if not lines:

package/src/qingflow_mcp/cli/oauth_callback.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import secrets
+import threading
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlsplit
+
+from ..errors import QingflowApiError
+
+
+CALLBACK_PATH = "/oauth/callback"
+
+
+@dataclass(frozen=True, slots=True)
+class OAuthCallbackResult:
+    code: str
+    state: str
+
+
+class OAuthCallbackServer:
+    def __init__(self, expected_state: str) -> None:
+        self._expected_state = expected_state
+        self._result: OAuthCallbackResult | None = None
+        self._error: QingflowApiError | None = None
+        self._completed = threading.Event()
+        self._result_lock = threading.Lock()
+        self._started = False
+        self._closed = False
+        handler = self._handler_type()
+        self._server = ThreadingHTTPServer(("127.0.0.1", 0), handler)
+        self._server.daemon_threads = True
+        self._thread = threading.Thread(target=self._server.serve_forever, name="qingflow-oauth-callback", daemon=True)
+
+    @property
+    def redirect_uri(self) -> str:
+        port = int(self._server.server_address[1])
+        return f"http://127.0.0.1:{port}{CALLBACK_PATH}"
+
+    def start(self) -> None:
+        if self._started:
+            return
+        self._started = True
+        self._thread.start()
+
+    def wait(self, timeout_seconds: float = 300.0) -> OAuthCallbackResult:
+        try:
+            if not self._completed.wait(timeout=max(0.0, timeout_seconds)):
+                raise QingflowApiError(
+                    category="auth",
+                    message="OAuth authorization timed out. Run auth login --method oauth again.",
+                    details={"reason": "oauth_callback_timeout"},
+                )
+            if self._error is not None:
+                raise self._error
+            if self._result is None:
+                raise QingflowApiError(category="auth", message="OAuth callback did not return an authorization code.")
+            return self._result
+        finally:
+            self.close()
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        if not self._started:
+            self._server.server_close()
+            return
+        self._server.shutdown()
+        self._server.server_close()
+        if self._thread.is_alive() and threading.current_thread() is not self._thread:
+            self._thread.join(timeout=2.0)
+
+    def _handler_type(self) -> type[BaseHTTPRequestHandler]:
+        callback_server = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def do_GET(self) -> None:  # noqa: N802
+                callback_server._handle(self)
+
+            def do_POST(self) -> None:  # noqa: N802
+                self.send_error(405)
+
+            def log_message(self, _format: str, *_args: object) -> None:
+                return
+
+        return Handler
+
+    def _handle(self, handler: BaseHTTPRequestHandler) -> None:
+        parsed = urlsplit(handler.path)
+        if parsed.path != CALLBACK_PATH:
+            self._respond(handler, 404, "OAuth callback path not found.")
+            return
+        query = parse_qs(parsed.query, keep_blank_values=True, strict_parsing=False)
+        state_values = query.get("state") or []
+        if len(state_values) != 1 or not secrets.compare_digest(state_values[0], self._expected_state):
+            self._respond(handler, 400, "OAuth callback state is invalid. Return to the CLI and retry login.")
+            return
+        with self._result_lock:
+            if self._completed.is_set():
+                self._respond(handler, 409, "OAuth callback has already been handled.")
+                return
+            error_values = query.get("error") or []
+            code_values = query.get("code") or []
+            if len(error_values) == 1 and error_values[0]:
+                error_code = error_values[0]
+                description_values = query.get("error_description") or []
+                description = description_values[0] if len(description_values) == 1 else None
+                self._error = QingflowApiError(
+                    category="auth",
+                    message=description or f"OAuth authorization failed: {error_code}.",
+                    details={"reason": "oauth_authorization_failed", "oauth_error": error_code},
+                )
+                self._completed.set()
+                self._respond(handler, 200, "Authorization was not completed. You can return to the CLI.")
+                return
+            if len(code_values) != 1 or not code_values[0]:
+                self._error = QingflowApiError(
+                    category="auth",
+                    message="OAuth callback did not contain exactly one authorization code.",
+                    details={"reason": "oauth_callback_invalid"},
+                )
+                self._completed.set()
+                self._respond(handler, 400, "Authorization response is invalid. Return to the CLI and retry login.")
+                return
+            self._result = OAuthCallbackResult(code=code_values[0], state=state_values[0])
+            self._completed.set()
+            self._respond(handler, 200, "Authorization completed. You can close this page and return to the CLI.")
+
+    def _respond(self, handler: BaseHTTPRequestHandler, status: int, message: str) -> None:
+        body = (
+            "<!doctype html><html><head><meta charset=\"utf-8\"><title>Qingflow CLI</title></head>"
+            f"<body><main><h1>Qingflow CLI</h1><p>{message}</p></main></body></html>"
+        ).encode("utf-8")
+        handler.send_response(status)
+        handler.send_header("Content-Type", "text/html; charset=utf-8")
+        handler.send_header("Cache-Control", "no-store")
+        handler.send_header("Content-Length", str(len(body)))
+        handler.end_headers()
+        handler.wfile.write(body)

package/src/qingflow_mcp/cli/oauth_client.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Any
+from urllib.parse import urlencode, urlsplit
+
+import httpx
+
+from ..config import DEFAULT_CLI_OAUTH_RESOURCE_URL, get_timeout_seconds, normalize_base_url
+from ..errors import QingflowApiError
+from ..oauth_token_store import OAuthTokenBundle
+
+
+CLI_OAUTH_CLIENT_ID = "qf_public_vlaBZbGtWzkKzsp0lmx-vwidnNuI5_l9Dj1Vv0HKSJ8"
+CLI_OAUTH_SOURCE_CODE = "qingflow_cli"
+CLI_OAUTH_SCOPE = "read write"
+CLI_OAUTH_RESOURCE_URI = DEFAULT_CLI_OAUTH_RESOURCE_URL
+
+
+@dataclass(frozen=True, slots=True)
+class OAuthServerMetadata:
+    issuer: str
+    authorization_endpoint: str
+    token_endpoint: str
+
+
+@dataclass(frozen=True, slots=True)
+class PKCEAuthorization:
+    state: str
+    verifier: str
+    challenge: str
+
+    @classmethod
+    def create(cls) -> "PKCEAuthorization":
+        verifier = _base64url(secrets.token_bytes(64))
+        digest = hashlib.sha256(verifier.encode("ascii")).digest()
+        return cls(
+            state=_base64url(secrets.token_bytes(32)),
+            verifier=verifier,
+            challenge=_base64url(digest),
+        )
+
+
+class OAuthClient:
+    def __init__(self, client: httpx.Client | None = None) -> None:
+        self._owns_client = client is None
+        self._client = client or httpx.Client(
+            timeout=get_timeout_seconds(),
+            follow_redirects=True,
+            trust_env=False,
+        )
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def discover(self, base_url: str) -> OAuthServerMetadata:
+        normalized = normalize_base_url(base_url)
+        if not normalized:
+            raise QingflowApiError.config_error("OAuth base_url is required.")
+        url = f"{normalized}/.well-known/oauth-authorization-server"
+        try:
+            response = self._client.get(url, headers={"Accept": "application/json"})
+        except httpx.HTTPError as exc:
+            raise _network_error("OAuth metadata request failed", exc) from exc
+        payload = self._json_response(response, operation="OAuth metadata discovery")
+        issuer = _text(payload.get("issuer"))
+        authorization_endpoint = _text(payload.get("authorization_endpoint"))
+        token_endpoint = _text(payload.get("token_endpoint"))
+        missing = [
+            name
+            for name, value in (
+                ("issuer", issuer),
+                ("authorization_endpoint", authorization_endpoint),
+                ("token_endpoint", token_endpoint),
+            )
+            if not value
+        ]
+        if missing:
+            raise QingflowApiError.config_error(
+                "OAuth metadata is missing required fields: " + ", ".join(missing) + "."
+            )
+        self._validate_endpoint(normalized, authorization_endpoint, "authorization_endpoint")
+        self._validate_endpoint(normalized, token_endpoint, "token_endpoint")
+        challenge_methods = payload.get("code_challenge_methods_supported")
+        if not isinstance(challenge_methods, list) or "S256" not in challenge_methods:
+            raise QingflowApiError.config_error("OAuth server metadata does not advertise PKCE S256 support.")
+        grant_types = payload.get("grant_types_supported")
+        if not isinstance(grant_types, list) or not {"authorization_code", "refresh_token"}.issubset(grant_types):
+            raise QingflowApiError.config_error(
+                "OAuth server metadata does not advertise authorization_code and refresh_token support."
+            )
+        return OAuthServerMetadata(
+            issuer=issuer,
+            authorization_endpoint=authorization_endpoint,
+            token_endpoint=token_endpoint,
+        )
+
+    def authorization_url(
+        self,
+        metadata: OAuthServerMetadata,
+        *,
+        redirect_uri: str,
+        resource: str,
+        pkce: PKCEAuthorization,
+    ) -> str:
+        query = urlencode(
+            {
+                "response_type": "code",
+                "client_id": CLI_OAUTH_CLIENT_ID,
+                "redirect_uri": redirect_uri,
+                "state": pkce.state,
+                "code_challenge": pkce.challenge,
+                "code_challenge_method": "S256",
+                "scope": CLI_OAUTH_SCOPE,
+                "resource": resource,
+            }
+        )
+        separator = "&" if "?" in metadata.authorization_endpoint else "?"
+        return f"{metadata.authorization_endpoint}{separator}{query}"
+
+    def exchange_code(
+        self,
+        metadata: OAuthServerMetadata,
+        *,
+        code: str,
+        redirect_uri: str,
+        verifier: str,
+    ) -> OAuthTokenBundle:
+        payload = self._token_request(
+            metadata.token_endpoint,
+            {
+                "grant_type": "authorization_code",
+                "client_id": CLI_OAUTH_CLIENT_ID,
+                "code": code,
+                "redirect_uri": redirect_uri,
+                "code_verifier": verifier,
+            },
+        )
+        return self._bundle_from_response(payload, generation=0)
+
+    def refresh(
+        self,
+        metadata: OAuthServerMetadata,
+        *,
+        refresh_token: str,
+        generation: int,
+    ) -> OAuthTokenBundle:
+        payload = self._token_request(
+            metadata.token_endpoint,
+            {
+                "grant_type": "refresh_token",
+                "client_id": CLI_OAUTH_CLIENT_ID,
+                "refresh_token": refresh_token,
+            },
+        )
+        return self._bundle_from_response(payload, generation=generation + 1)
+
+    def revoke(self, base_url: str, refresh_token: str) -> None:
+        normalized = normalize_base_url(base_url)
+        if not normalized:
+            raise QingflowApiError.config_error("OAuth base_url is required for logout.")
+        try:
+            response = self._client.post(
+                f"{normalized}/oauth/revoke",
+                data={
+                    "client_id": CLI_OAUTH_CLIENT_ID,
+                    "token": refresh_token,
+                    "token_type_hint": "refresh_token",
+                },
+                headers={"Accept": "application/json"},
+            )
+        except httpx.HTTPError as exc:
+            raise _network_error("OAuth revocation request failed", exc) from exc
+        if response.status_code not in {200, 204}:
+            self._raise_protocol_error(response, operation="OAuth revocation")
+
+    def _token_request(self, endpoint: str, form: dict[str, str]) -> dict[str, Any]:
+        try:
+            response = self._client.post(
+                endpoint,
+                data=form,
+                headers={"Accept": "application/json"},
+            )
+        except httpx.HTTPError as exc:
+            raise _network_error("OAuth token request failed", exc) from exc
+        return self._json_response(response, operation="OAuth token request")
+
+    def _json_response(self, response: httpx.Response, *, operation: str) -> dict[str, Any]:
+        if response.status_code < 200 or response.status_code >= 300:
+            self._raise_protocol_error(response, operation=operation)
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise QingflowApiError(
+                category="auth",
+                message=f"{operation} returned invalid JSON.",
+                http_status=response.status_code,
+            ) from exc
+        if not isinstance(payload, dict):
+            raise QingflowApiError(
+                category="auth",
+                message=f"{operation} returned an invalid response.",
+                http_status=response.status_code,
+            )
+        return payload
+
+    def _raise_protocol_error(self, response: httpx.Response, *, operation: str) -> None:
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = {}
+        oauth_error = _text(payload.get("error")) if isinstance(payload, dict) else None
+        description = _text(payload.get("error_description")) if isinstance(payload, dict) else None
+        raise QingflowApiError(
+            category="auth" if response.status_code < 500 else "network",
+            message=description or f"{operation} failed with HTTP {response.status_code}.",
+            http_status=response.status_code,
+            details={"reason": "oauth_protocol_error", "oauth_error": oauth_error or "unknown"},
+        )
+
+    def _bundle_from_response(self, payload: dict[str, Any], *, generation: int) -> OAuthTokenBundle:
+        access_token = _text(payload.get("access_token"))
+        refresh_token = _text(payload.get("refresh_token"))
+        token_type = _text(payload.get("token_type"))
+        try:
+            expires_in = int(payload.get("expires_in"))
+        except (TypeError, ValueError):
+            expires_in = 0
+        if not access_token or not refresh_token or token_type is None or token_type.lower() != "bearer" or expires_in <= 0:
+            raise QingflowApiError(
+                category="auth",
+                message="OAuth token response is missing a valid access token, refresh token, token type, or expiry.",
+                details={"reason": "oauth_token_response_invalid"},
+            )
+        expires_at = datetime.now(timezone.utc) + timedelta(seconds=expires_in)
+        return OAuthTokenBundle(
+            access_token=access_token,
+            refresh_token=refresh_token,
+            access_expires_at=expires_at.isoformat(),
+            generation=generation,
+        )
+
+    def _validate_endpoint(self, base_url: str, endpoint: str, field: str) -> None:
+        base = urlsplit(base_url)
+        candidate = urlsplit(endpoint)
+        if candidate.scheme not in {"http", "https"} or not candidate.netloc:
+            raise QingflowApiError.config_error(f"OAuth metadata {field} is not an absolute HTTP URL.")
+        if (candidate.scheme.lower(), candidate.netloc.lower()) != (base.scheme.lower(), base.netloc.lower()):
+            raise QingflowApiError.config_error(f"OAuth metadata {field} must use the configured base_url origin.")
+        base_path = base.path.rstrip("/")
+        if base_path and candidate.path != base_path and not candidate.path.startswith(base_path + "/"):
+            raise QingflowApiError.config_error(f"OAuth metadata {field} must remain under the configured base_url path.")
+
+
+def _base64url(value: bytes) -> str:
+    return base64.urlsafe_b64encode(value).decode("ascii").rstrip("=")
+
+
+def _text(value: object) -> str | None:
+    if value is None:
+        return None
+    normalized = str(value).strip()
+    return normalized or None
+
+
+def _network_error(message: str, error: Exception) -> QingflowApiError:
+    return QingflowApiError(
+        category="network",
+        message=f"{message}: {error}",
+        details={"reason": "oauth_network_error"},
+    )