diff --git a/.pr/design.html b/.pr/design.html index 8f0437cb972..a5307e6a4a8 100644 --- a/.pr/design.html +++ b/.pr/design.html @@ -2,146 +2,61 @@ - -Fallbacks keep the caller's accounting session +Public MCP OAuth redirect for the agent-server -
- -
-
-
Stacked fix for SDK PR #6690
-

Fallbacks keep the caller's accounting session.

-

A fallback changes the model serving a request. Its tokens, cost and telemetry still belong to the agent, condenser or ask-agent role that made the request.

-

The session refactor already records a fallback response in a conversation ledger. Its old post-call merge records the same usage again, and a profile's usage_id="default" can route auxiliary calls into the agent ledger. This fix gives a temporary fallback LLM the caller's existing session references and removes the second accounting path for SDK calls.

-

Before: fallback_strategy.py:99 · After: fallback_strategy.py:106

-
★ One successful provider request writes once to the caller's ledger. The individual records and completion logs identify the model that actually answered.
-
-
-

1. Bind the request before calling the fallback

-
- -An ask-agent fallback before and after the fix -Before, the fallback profile selects the default role and its metrics are merged into ask-agent, counting one response twice. After, a temporary fallback object is explicitly bound to ask-agent's session, which records one hundred tokens once. - - - - - - - - - -Before · profile role wins - - -try_fallback() → call_fn(fb) -Saved fallback keeps usage_id="default" -fallback_strategy.py:99 - - - -session_for() → sessions["default"] -Agent ledger receives +100 tokens -llm.py:975 - - - -primary_metrics.merge(metrics_diff) -Ask-agent ledger receives another +100 -fallback_strategy.py:110 -100 provider tokens → 200 recorded -Same-role fallback also doubles its single ledger. - - - -After · caller role stays - - -fb.model_copy(usage_id=caller.role) -Temporary copy disables nested fallbacks -fallback_strategy.py:106 - - - -Reuse _session + _registry_session -Existing role and aggregate ownership -fallback_strategy.py:117 - - - -session_for() → caller's session -Ask-agent records +100; its callbacks fire -llm.py:975 -100 provider tokens → 100 recorded -SDK calls skip the post-call metrics merge. - - -
Fig. 1 · The fallback profile supplies model configuration; the caller supplies accounting ownership. Orange arrows mark the changed path.
-
-
-

Context survives async fallback

asyncio.to_thread() carries the scoped call context into async fallback work. Explicit contexts already travel with the callback, so both paths preserve the conversation identity and prompt-cache key.

llm.py:1122 · _ahandle_error()
-

Records keep the answering model

Telemetry passes its current model into token, cost and latency entries. Session totals stay with the role while individual entries identify the fallback model.

telemetry.py:227 · on_response()
+

Public MCP OAuth redirect for the agent-server

+

Fixes OpenHands#18888 and the agent-server half of +OpenHands#15430. Install-time MCP OAuth +(POST /api/mcp/oauth/start) always registered http://localhost:<random port>/callback +as the redirect URI. That port lives on the agent-server host, so the browser can only reach it when the +browser and the agent-server share one machine and one network namespace.

+ +

Before / after

+
+
Before +
browser ── authorize ──▶ provider
+provider ── 302 ──▶ http://localhost:47071/callback
+                    (browser's own localhost:
+                     ERR_CONNECTION_REFUSED)
+probe waits 5 min ─▶ "Sign-in was not completed"
+
After (public URL known) +
browser ── authorize ──▶ provider
+provider ── 302 ──▶ https://canvas.example/api/mcp/oauth/redirect
+agent-server: find job by OAuth state, hand code to probe
+probe exchanges code ─▶ "Connected — N tool(s)"
-
-
-

2. Preserve existing call signatures

-

The original positional arguments remain valid. The fallback reuses existing session references; serialized LLM and profile shapes are unchanged. fallback_strategy.py:117

-
-

Before

try_fallback(model, error, metrics, call_fn)
-metrics.add_cost(value)
-metrics.add_response_latency(value, response_id)
-metrics.add_token_usage(...)
-

After · optional keyword additions

try_fallback(model, error, metrics, call_fn,
-             *, primary=None)
-metrics.add_cost(value, *, model_name=None)
-metrics.add_response_latency(..., model_name=None)
-metrics.add_token_usage(..., model_name=None)
-
-

fallback_strategy.py:73 · metrics.py:189

-

The original four-argument try_fallback() API keeps its metrics-diff merge. SDK calls pass primary=self, reuse the caller's sessions and callbacks, and skip that merge. The fallback example's accounting description is updated to match. fallback_strategy.py:117

-
-
-

3. Five operations, five corrected ledgers

-

The same script ran on PR #6690's 0a68ab94 and on this fix. Each operation sent one request that received HTTP 503, then one successful fallback request reporting 100 prompt tokens.

+ +

Which redirect URI is used

- - - - - - - - + + +
Public operationBefore: token increaseAfter: token increase
run(), first turndefault +200default +100
run(), second turndefault +200default +100
run(), third turndefault +200default +100
ask_agent()default +100; ask-agent-llm +100ask-agent-llm +100
condense()default +100; condenser +100condenser +100
OAuth clientweb_url / OH_WEB_URL setonly callback_base_url in the requestneither
dynamically registered (DCR){web_url}/api/mcp/oauth/redirect{callback_base_url}/api/mcp/oauth/redirectloopback (unchanged)
pre-registered (client_id or metadata URL){web_url}/api/mcp/oauth/redirectloopback (unchanged)loopback (unchanged)
-

Evidence: fallback-session-evidence.json · fallback-session-repro.py

-

macOS · Python 3.13.11 · real settings construction, profile save/load, conversation lifecycle and HTTP transport. The provider runs on loopback and supplies deterministic responses. These observations establish token totals and role attribution; they do not measure callback counts, actual provider billing or remote-service behavior.

-
Reproduce with the checkout's dependencies
OH_PERSISTENCE_DIR=/tmp/fallback-repro-state \
-OPENHANDS_SUPPRESS_BANNER=1 LITELLM_LOCAL_MODEL_COST_MAP=True \
-uv run python .pr/fallback-session-repro.py --assert-fixed

The final flag makes incorrect accounting fail with exit code 1. The script starts and shuts down its own local HTTP server and uses temporary profile and conversation directories.

-
-
-

4. Regression checks cover the other boundaries

-

1,791 tests passed; 2 expected failures. The LLM, conversation-session, model-switch and agent-server event-service checks passed. Two credential-path checks ran separately without the temporary persistence-directory override. The two fallback regression files account for 58 passing cases.

-

The focused regression file checks sync and async Chat Completions and Responses calls, explicit and scoped contexts, standalone use, a colliding default role, and one LLM shared across registries. Two fallback calls followed by a recovered primary call verify cumulative tokens, cost, callback counts, returned metrics and actual-model labels. A separate case exercises the original direct try_fallback() API.

-

test_fallback_preserves_caller_accounting:41 · test_direct_fallback_preserves_supplied_metrics:230

-
Focused regression command
uv run pytest tests/sdk/llm/test_llm_fallback_sessions.py \
-  tests/sdk/llm/test_llm_fallback.py tests/sdk/llm/test_llm_session.py -q

These regression tests replace provider responses at the LiteLLM boundary. The loopback reproduction above separately exercises real HTTP transport.

-
- -
-
+

A pre-registered client's redirect URIs are fixed at the provider, so a browser-supplied base must not +change them; only the operator's web_url does. A DCR client stored from an earlier +loopback registration is dropped and registered again when its redirect URIs do not contain the new URI.

+ +

API

+
POST /api/mcp/oauth/start          body: MCPTestRequest + callback_base_url?: string  (plain http(s) base, no query/fragment/userinfo)
+GET  /api/mcp/oauth/redirect       new, unauthenticated, not in OpenAPI; ?code&state[&iss] or ?error[&error_description]
+

The redirect route is outside the session-key dependency because the provider sends the user's browser +there. It accepts a request only for a registered, unexpired job that is currently waiting for a redirect and +whose OAuth state matches (constant-time compare). The first redirect wins; a replay gets 409; +a provider error fails the probe with the provider's description.

+ +

Compatibility

+ diff --git a/.pr/oh-15430-after.png b/.pr/oh-15430-after.png new file mode 100644 index 00000000000..22ebb4c1ca5 Binary files /dev/null and b/.pr/oh-15430-after.png differ diff --git a/.pr/oh-15430-before.png b/.pr/oh-15430-before.png new file mode 100644 index 00000000000..323d94d5f23 Binary files /dev/null and b/.pr/oh-15430-before.png differ diff --git a/.pr/oh-18888-after.png b/.pr/oh-18888-after.png new file mode 100644 index 00000000000..58ca49f80b3 Binary files /dev/null and b/.pr/oh-18888-after.png differ diff --git a/.pr/oh-18888-before.png b/.pr/oh-18888-before.png new file mode 100644 index 00000000000..c0be394ecf9 Binary files /dev/null and b/.pr/oh-18888-before.png differ diff --git a/.pr/sdk-6221-weburl-after.png b/.pr/sdk-6221-weburl-after.png new file mode 100644 index 00000000000..75173aaece6 Binary files /dev/null and b/.pr/sdk-6221-weburl-after.png differ diff --git a/openhands-agent-server/openhands/agent_server/api.py b/openhands-agent-server/openhands/agent_server/api.py index 53180fe0080..d919cb7191c 100644 --- a/openhands-agent-server/openhands/agent_server/api.py +++ b/openhands-agent-server/openhands/agent_server/api.py @@ -71,7 +71,7 @@ ) from openhands.agent_server.llm_router import llm_router from openhands.agent_server.local_secret_resolver import local_secret_resolution -from openhands.agent_server.mcp_router import mcp_router +from openhands.agent_server.mcp_router import mcp_oauth_redirect_router, mcp_router from openhands.agent_server.meta_profiles_router import meta_profiles_router from openhands.agent_server.middleware import CORSDispatcher from openhands.agent_server.openai.router import ( @@ -639,6 +639,9 @@ def _add_api_routes(app: FastAPI) -> None: init_api_router = APIRouter(prefix="/api") init_api_router.include_router(init_router) app.include_router(init_api_router) + app.include_router( + mcp_oauth_redirect_router, dependencies=[Depends(require_initialized)] + ) # Header-only auth: applied to every /api/* route EXCEPT the workspace # static-file routes (handled separately below). Cookies are NOT honored diff --git a/openhands-agent-server/openhands/agent_server/config.py b/openhands-agent-server/openhands/agent_server/config.py index bdf4522fa64..a5cddce61e9 100644 --- a/openhands-agent-server/openhands/agent_server/config.py +++ b/openhands-agent-server/openhands/agent_server/config.py @@ -381,7 +381,9 @@ class Config(BaseModel): web_url: str | None = Field( default_factory=_default_web_url, description=( - "The URL where this agent server instance is available externally" + "The URL where this agent server instance is available externally. " + "Its path becomes the root path, and install-time MCP OAuth uses " + "{web_url}/api/mcp/oauth/redirect as the provider redirect URI." ), ) app_backend_public_url: str | None = Field( diff --git a/openhands-agent-server/openhands/agent_server/mcp_router.py b/openhands-agent-server/openhands/agent_server/mcp_router.py index cc8599cc001..07284fc50f2 100644 --- a/openhands-agent-server/openhands/agent_server/mcp_router.py +++ b/openhands-agent-server/openhands/agent_server/mcp_router.py @@ -21,25 +21,41 @@ import asyncio import base64 +import html import json import logging import os import re +import secrets import threading import time import traceback import uuid from collections.abc import Callable, Collection from typing import Annotated, Any, Final, Literal -from urllib.parse import urlparse +from urllib.parse import parse_qs, urlparse import httpx import mcp.types -from fastapi import APIRouter, Depends +from fastapi import APIRouter, Depends, Request +from fastapi.responses import HTMLResponse from fastmcp.client.auth.oauth import ClientNotFoundError, OAuth -from pydantic import BaseModel, Field, ValidationError, model_validator +from mcp.shared.auth import AuthorizationCodeResult +from pydantic import ( + AnyUrl, + BaseModel, + Field, + ValidationError, + field_validator, + model_validator, +) -from openhands.agent_server.dependencies import get_cipher, get_secrets_store +from openhands.agent_server.config import Config +from openhands.agent_server.dependencies import ( + get_cipher, + get_config, + get_secrets_store, +) from openhands.agent_server.mcp_oauth_store import ( InMemoryMCPOAuthTokenStore, ) @@ -66,6 +82,10 @@ logger = get_logger(__name__) mcp_router = APIRouter(prefix="/mcp", tags=["MCP"]) +# The OAuth provider redirects the browser here, so the route cannot require +# the session API key; the OAuth ``state`` of a pending probe authenticates it. +mcp_oauth_redirect_router = APIRouter(prefix="/api/mcp/oauth", tags=["MCP"]) +MCP_OAUTH_REDIRECT_PATH: Final[str] = "/api/mcp/oauth/redirect" # --------------------------------------------------------------------------- @@ -293,6 +313,39 @@ class MCPTestFailure(BaseModel): ] +class MCPOAuthStartRequest(MCPTestRequest): + """Body for ``POST /api/mcp/oauth/start``.""" + + callback_base_url: str | None = Field( + default=None, + description=( + "Agent-server base URL as the user's browser reaches it, e.g. " + "`https://canvas.example.com`. When set and the server has no " + "`web_url`, a dynamically registered OAuth client is redirected to " + f"`{MCP_OAUTH_REDIRECT_PATH}` instead of a " + "loopback port on the agent-server host, which a browser on " + "another machine or outside a container cannot reach." + ), + ) + + @field_validator("callback_base_url") + @classmethod + def _validate_callback_base_url(cls, value: str | None) -> str | None: + if value is None: + return None + parsed = urlparse(value) + if ( + parsed.scheme not in {"http", "https"} + or not parsed.hostname + or parsed.username is not None + or parsed.password is not None + or parsed.query + or parsed.fragment + ): + raise ValueError("callback_base_url must be a plain http(s) base URL") + return value.rstrip("/") + + class MCPOAuthStartResponse(BaseModel): """Response for starting an install-time OAuth MCP probe.""" @@ -325,13 +378,31 @@ class MCPOAuthCallbackRequest(BaseModel): class _MCPOAuthProbeJob: - def __init__(self, *, request: MCPTestRequest, cipher: Cipher | None): + def __init__( + self, + *, + request: MCPTestRequest, + cipher: Cipher | None, + public_redirect_url: str | None = None, + static_client_redirect_url: str | None = None, + ): self.id = uuid.uuid4().hex self.request = request self.cipher = cipher + # Where the provider sends the browser back to, served by + # ``receive_mcp_oauth_redirect``; ``None`` keeps FastMCP's loopback + # callback server. A pre-registered client (static ``client_id`` or a + # metadata document) has its redirect URI fixed at the provider, so it + # only follows an operator-configured ``web_url``. + self.public_redirect_url = public_redirect_url + self.static_client_redirect_url = static_client_redirect_url self.created_at = time.monotonic() self.authorization_url: str | None = None self.callback_url: str | None = None + self.oauth_state: str | None = None + self.redirect_result: AuthorizationCodeResult | None = None + self.redirect_error: str | None = None + self.redirect_received = threading.Event() self.result: MCPTestResponse | None = None self.status: Literal["pending", "authorizing", "succeeded", "failed"] = ( "pending" @@ -352,6 +423,28 @@ def set_callback_ready(self, callback_url: str) -> None: self.callback_url = callback_url self.callback_ready.set() + def accept_redirect( + self, + *, + code: str | None, + state: str, + iss: str | None, + error: str | None, + ) -> bool: + """Record the provider's redirect; ``False`` if one was already taken.""" + with self.lock: + if self.redirect_received.is_set(): + return False + if error is not None: + self.redirect_error = error + else: + assert code is not None + self.redirect_result = AuthorizationCodeResult( + code=code, state=state, iss=iss + ) + self.redirect_received.set() + return True + def set_result(self, result: MCPTestResponse) -> None: with self.lock: self.result = result @@ -460,11 +553,40 @@ class _BrowserCoordinatedOAuth(MCPOAuth): """FastMCP OAuth client that lets the frontend own browser navigation.""" def __init__(self, *, job: _MCPOAuthProbeJob, **kwargs: Any): - super().__init__(**kwargs) self._job = job + super().__init__(**kwargs) + + @property + def _redirect_url(self) -> str | None: + if self._client_id or self._client_metadata_url: + return self._job.static_client_redirect_url + return self._job.public_redirect_url + + def _bind(self, mcp_url: str) -> None: + super()._bind(mcp_url) + redirect_url = self._redirect_url + if redirect_url is None: + return + redirect_uris: list[AnyUrl] = [AnyUrl(redirect_url)] + self.context.client_metadata.redirect_uris = redirect_uris + if self._static_client_info is not None: + self._static_client_info.redirect_uris = redirect_uris async def redirect_handler(self, authorization_url: str) -> None: """Capture the URL instead of opening a browser from the backend.""" + # Keep the original client for refresh; only fresh authorization needs + # a registration for this redirect. FastMCP retries stale clients once. + redirect_url = self._redirect_url + client_info = self.context.client_info + if ( + redirect_url is not None + and self._static_client_info is None + and client_info is not None + and redirect_url + not in {str(uri) for uri in client_info.redirect_uris or []} + ): + raise ClientNotFoundError("OAuth client has a different redirect URI") + async with self.httpx_client_factory() as client: response = await client.get(authorization_url, follow_redirects=False) if response.status_code == 400: @@ -477,6 +599,9 @@ async def redirect_handler(self, authorization_url: str) -> None: ) logger.info("MCP OAuth authorization URL captured for job %s", self._job.id) + state = parse_qs(urlparse(authorization_url).query).get("state", [None])[0] + with self._job.lock: + self._job.oauth_state = state self._job.set_authorization_url(authorization_url) async def callback_handler(self): @@ -486,14 +611,36 @@ async def callback_handler(self): rejects -- it wants an ``AuthorizationCodeResult``. Only ``redirect_port`` is read: ``_callback_host`` is absent in fastmcp 3.2.0. """ - callback_url = f"http://localhost:{self.redirect_port}/callback" - self._job.set_callback_ready(callback_url) + redirect_url = self._redirect_url + if redirect_url is None: + callback_url = f"http://localhost:{self.redirect_port}/callback" + self._job.set_callback_ready(callback_url) + logger.info( + "MCP OAuth callback server ready for job %s at %s", + self._job.id, + callback_url, + ) + return await super().callback_handler() + + self._job.set_callback_ready(redirect_url) logger.info( - "MCP OAuth callback server ready for job %s at %s", + "MCP OAuth job %s waiting for the redirect to %s", self._job.id, - callback_url, + redirect_url, ) - return await super().callback_handler() + deadline = time.monotonic() + self._callback_timeout + while not self._job.redirect_received.is_set(): + if time.monotonic() >= deadline: + raise TimeoutError( + f"OAuth callback timed out after {self._callback_timeout} seconds" + ) + await asyncio.sleep(0.25) + with self._job.lock: + result = self._job.redirect_result + error = self._job.redirect_error + if result is None: + raise RuntimeError(f"OAuth authorization failed: {error}") + return result def _run_tool_call( @@ -858,6 +1005,33 @@ def oauth_factory( job.set_result(result) +def _oauth_redirect_url(base_url: str | None) -> str | None: + if not base_url: + return None + return f"{base_url.rstrip('/')}{MCP_OAUTH_REDIRECT_PATH}" + + +def _find_oauth_job_by_state(state: str) -> _MCPOAuthProbeJob | None: + with _oauth_probe_jobs_lock: + _sweep_oauth_probe_jobs_locked() + jobs = list(_oauth_probe_jobs.values()) + for job in jobs: + with job.lock: + expected = job.oauth_state + callback_url = job.callback_url + waits_for_redirect = callback_url is not None and callback_url in ( + job.public_redirect_url, + job.static_client_redirect_url, + ) + if ( + waits_for_redirect + and expected is not None + and secrets.compare_digest(state.encode(), expected.encode()) + ): + return job + return None + + def _register_oauth_job(job: _MCPOAuthProbeJob) -> None: with _oauth_probe_jobs_lock: _sweep_oauth_probe_jobs_locked() @@ -880,13 +1054,28 @@ def _get_oauth_job(job_id: str) -> _MCPOAuthProbeJob: summary="Start an MCP OAuth install probe", ) async def start_mcp_oauth( - request: MCPTestRequest, cipher: Cipher | None = Depends(get_cipher) + request: MCPOAuthStartRequest, + cipher: Cipher | None = Depends(get_cipher), + config: Config = Depends(get_config), ) -> MCPOAuthStartResponse: - """Start OAuth for a candidate MCP server and return the authorization URL.""" + """Start OAuth for a candidate MCP server and return the authorization URL. + + With ``web_url`` configured, or ``callback_base_url`` sent by the browser, + the provider redirects to this server's ``/api/mcp/oauth/redirect`` route + instead of a loopback port on the agent-server host. + """ if request.resolved_server.oauth_auth is None: raise Invalid("MCP OAuth start requires auth.strategy='oauth2'") - job = _MCPOAuthProbeJob(request=request, cipher=cipher) + configured_redirect_url = _oauth_redirect_url(config.web_url) + job = _MCPOAuthProbeJob( + request=request, + cipher=cipher, + public_redirect_url=( + configured_redirect_url or _oauth_redirect_url(request.callback_base_url) + ), + static_client_redirect_url=configured_redirect_url, + ) _register_oauth_job(job) thread = threading.Thread( target=_run_oauth_probe_job, @@ -941,6 +1130,51 @@ async def get_mcp_oauth_status(job_id: str) -> MCPOAuthStatusResponse: return _get_oauth_job(job_id).to_status_response() +def _oauth_redirect_page(message: str, status_code: int) -> HTMLResponse: + title = "Authorization complete" if status_code == 200 else "Authorization failed" + return HTMLResponse( + "" + f"{title}" + f"

{title}

{html.escape(message)}

", + status_code=status_code, + ) + + +@mcp_oauth_redirect_router.get("/redirect", include_in_schema=False) +async def receive_mcp_oauth_redirect(request: Request) -> HTMLResponse: + """Receive the provider's OAuth redirect for a pending install probe. + + The probe job is found by the OAuth ``state`` it put in the authorization + URL, which only the provider and the browser that signed in have seen. + The probe then exchanges the code; the status route reports the outcome. + """ + params = request.query_params + state = params.get("state") + job = _find_oauth_job_by_state(state) if state else None + if state is None or job is None: + return _oauth_redirect_page( + "This sign-in is unknown or has expired. " + "Start the connection again in OpenHands.", + 400, + ) + error = params.get("error") + code = params.get("code") + if error is None and not code: + error = "the provider returned no authorization code" + if error is not None: + error = params.get("error_description") or error + if not job.accept_redirect( + code=code, state=state, iss=params.get("iss"), error=error + ): + return _oauth_redirect_page("This sign-in was already completed.", 409) + if error is not None: + logger.info("MCP OAuth job %s was not authorized: %s", job.id, error) + return _oauth_redirect_page(f"The provider reported: {error}", 400) + return _oauth_redirect_page( + "You can close this window and return to OpenHands.", 200 + ) + + def _validate_callback_url(callback_url: str, job: _MCPOAuthProbeJob) -> None: try: parsed = urlparse(callback_url) diff --git a/tests/agent_server/test_mcp_oauth_redirect.py b/tests/agent_server/test_mcp_oauth_redirect.py new file mode 100644 index 00000000000..dd1b78336e4 --- /dev/null +++ b/tests/agent_server/test_mcp_oauth_redirect.py @@ -0,0 +1,400 @@ +"""Install-time MCP OAuth through the agent-server's own redirect route. + +A real FastMCP server protected by FastMCP's in-memory OAuth provider performs +dynamic client registration, validates the redirect URI and exchanges the +code. The test plays the browser: it follows the authorization URL and +delivers the provider's redirect to wherever the provider sent it. +""" + +from __future__ import annotations + +import time +from collections.abc import Generator +from urllib.parse import parse_qs, urlparse + +import httpx +import pytest +from fastapi.testclient import TestClient +from fastmcp.server.auth.providers.in_memory import InMemoryOAuthProvider +from pydantic import SecretStr + +from openhands.agent_server.api import create_app +from openhands.agent_server.config import Config +from openhands.agent_server.mcp_router import ( + MCPTestRequest, + _BrowserCoordinatedOAuth, + _MCPOAuthProbeJob, + _oauth_probe_jobs, + _register_oauth_job, +) +from tests.agent_server.test_mcp_oauth_store import ( # noqa: F401 - fixtures + oauth_provider, + protected_oauth_mcp_server, +) + + +PUBLIC_REDIRECT = "https://canvas.example.test/api/mcp/oauth/redirect" + + +def _client(**config: object) -> TestClient: + return TestClient( + create_app( + Config( + session_api_keys=[], + secret_key=SecretStr("mcp-oauth-redirect-test-key"), + **config, # type: ignore[arg-type] + ) + ), + raise_server_exceptions=False, + ) + + +def _oauth_server(url: str, state: dict | None = None) -> dict: + auth: dict = { + "strategy": "oauth2", + "authentication": { + "type": "oauth", + "client_auth_method": "none", + "scopes": ["mail.read"], + }, + } + if state is not None: + auth["state"] = state + return {"transport": "http", "url": url, "auth": auth} + + +def _start(client: TestClient, body: dict) -> tuple[str, str]: + response = client.post("/api/mcp/oauth/start", json={"timeout": 10.0, **body}) + assert response.status_code == 200, response.text + started = response.json() + assert started["ok"] is True, started + job_id = started["job_id"] + for _ in range(100): + if client.get(f"/api/mcp/oauth/status/{job_id}").json()["callback_ready"]: + break + time.sleep(0.05) + return job_id, started["authorization_url"] + + +def _redirect_uri(authorization_url: str) -> str: + return parse_qs(urlparse(authorization_url).query)["redirect_uri"][0] + + +def _sign_in(authorization_url: str) -> str: + """Return where the provider redirects the browser after consent.""" + response = httpx.get(authorization_url, follow_redirects=False, timeout=10.0) + assert response.status_code in {302, 303, 307, 308}, response.text + return response.headers["location"] + + +def _wait_for_result(client: TestClient, job_id: str) -> dict: + status: dict = {} + for _ in range(200): + status = client.get(f"/api/mcp/oauth/status/{job_id}").json() + if status["status"] in {"succeeded", "failed"}: + return status + time.sleep(0.05) + raise AssertionError(f"OAuth job {job_id} did not finish: {status}") + + +@pytest.fixture +def jobs() -> Generator[None]: + yield + _oauth_probe_jobs.clear() + + +def test_browser_redirect_goes_to_callback_base_url_and_completes( + protected_oauth_mcp_server: str, # noqa: F811 + jobs: None, +): + client = _client() + job_id, authorization_url = _start( + client, + { + "server": _oauth_server(protected_oauth_mcp_server), + "callback_base_url": "https://canvas.example.test/", + }, + ) + + assert _redirect_uri(authorization_url) == PUBLIC_REDIRECT + location = _sign_in(authorization_url) + assert location.startswith(f"{PUBLIC_REDIRECT}?") + assert client.get(f"/api/mcp/oauth/status/{job_id}").json()["status"] == ( + "authorizing" + ) + + redirect = urlparse(location) + landing = client.get(f"{redirect.path}?{redirect.query}") + + assert landing.status_code == 200 + assert "Authorization complete" in landing.text + status = _wait_for_result(client, job_id) + assert status["status"] == "succeeded", status + assert status["tools"] == ["read_subject"] + assert status["oauth_state"]["tokens"]["access_token"].startswith("gAAAA") + + +def test_web_url_with_path_prefix_wins_over_callback_base_url( + protected_oauth_mcp_server: str, # noqa: F811 + jobs: None, +): + client = _client(web_url="https://agent.example.com/openhands/") + job_id, authorization_url = _start( + client, + { + "server": _oauth_server(protected_oauth_mcp_server), + "callback_base_url": "https://canvas.example.test", + }, + ) + + assert _redirect_uri(authorization_url) == ( + "https://agent.example.com/openhands/api/mcp/oauth/redirect" + ) + redirect = urlparse(_sign_in(authorization_url)) + # The reverse proxy strips the path prefix before the agent-server. + assert redirect.path == "/openhands/api/mcp/oauth/redirect" + landing = client.get(f"/api/mcp/oauth/redirect?{redirect.query}") + + assert landing.status_code == 200 + assert _wait_for_result(client, job_id)["status"] == "succeeded" + + +def test_without_a_public_url_the_loopback_callback_is_unchanged( + protected_oauth_mcp_server: str, # noqa: F811 + jobs: None, +): + client = _client() + job_id, authorization_url = _start( + client, {"server": _oauth_server(protected_oauth_mcp_server)} + ) + + redirect_uri = urlparse(_redirect_uri(authorization_url)) + assert (redirect_uri.scheme, redirect_uri.hostname, redirect_uri.path) == ( + "http", + "localhost", + "/callback", + ) + assert client.get(f"/api/mcp/oauth/status/{job_id}").json()["status"] == ( + "authorizing" + ) + # The loopback callback server inside the probe receives the redirect. + httpx.get(_sign_in(authorization_url), timeout=10.0) + + assert _wait_for_result(client, job_id)["status"] == "succeeded" + + +def test_a_client_registered_for_the_loopback_callback_is_registered_again( + protected_oauth_mcp_server: str, # noqa: F811 + jobs: None, +): + client = _client() + job_id, authorization_url = _start( + client, {"server": _oauth_server(protected_oauth_mcp_server)} + ) + httpx.get(_sign_in(authorization_url), timeout=10.0) + first = _wait_for_result(client, job_id) + stored_client = first["oauth_state"]["client_info"] + assert stored_client["redirect_uris"][0].startswith("http://localhost:") + + job_id, authorization_url = _start( + client, + { + "server": _oauth_server( + protected_oauth_mcp_server, {"client_info": stored_client} + ), + "callback_base_url": "https://canvas.example.test", + }, + ) + redirect = urlparse(_sign_in(authorization_url)) + client.get(f"{redirect.path}?{redirect.query}") + second = _wait_for_result(client, job_id) + + assert second["status"] == "succeeded", second + assert ( + second["oauth_state"]["client_info"]["client_id"] + != (stored_client["client_id"]) + ) + assert second["oauth_state"]["client_info"]["redirect_uris"] == [PUBLIC_REDIRECT] + + +def test_changed_callback_refreshes_stored_tokens_without_authorization( + protected_oauth_mcp_server: str, # noqa: F811 + oauth_provider: InMemoryOAuthProvider, # noqa: F811 + jobs: None, +): + client = _client() + job_id, authorization_url = _start( + client, {"server": _oauth_server(protected_oauth_mcp_server)} + ) + httpx.get(_sign_in(authorization_url), timeout=10.0) + first = _wait_for_result(client, job_id) + state = first["oauth_state"] + state["token_expires_at"] = time.time() - 60 + registered_clients = set(oauth_provider.clients) + refresh_tokens = set(oauth_provider.refresh_tokens) + + response = client.post( + "/api/mcp/oauth/start", + json={ + "timeout": 10.0, + "server": _oauth_server(protected_oauth_mcp_server, state), + "callback_base_url": "https://canvas.example.test", + }, + ) + + assert response.status_code == 200, response.text + started = response.json() + assert started["ok"] is True, started + assert "authorization_url" not in started, started + second = _wait_for_result(client, started["job_id"]) + assert second["status"] == "succeeded", second + assert second["tools"] == ["read_subject"] + assert second["oauth_state"]["client_info"] == state["client_info"] + assert second["oauth_state"]["token_expires_at"] > time.time() + assert set(oauth_provider.clients) == registered_clients + assert not refresh_tokens.intersection(oauth_provider.refresh_tokens) + + +def _job() -> _MCPOAuthProbeJob: + return _MCPOAuthProbeJob( + request=MCPTestRequest.model_validate( + {"server": _oauth_server("https://mcp.example.com/mcp")} + ), + cipher=None, + public_redirect_url=PUBLIC_REDIRECT, + ) + + +def _waiting_job(state: str) -> _MCPOAuthProbeJob: + job = _job() + job.oauth_state = state + job.set_callback_ready(PUBLIC_REDIRECT) + _register_oauth_job(job) + return job + + +def test_redirect_with_an_unknown_state_completes_no_job(jobs: None): + job = _waiting_job("expected-state") + + response = _client().get("/api/mcp/oauth/redirect?code=abc&state=other-state") + + assert response.status_code == 400 + assert "unknown or has expired" in response.text + assert not job.redirect_received.is_set() + + +def test_redirect_before_the_job_waits_for_it_is_rejected(jobs: None): + job = _job() + job.oauth_state = "early-state" + _register_oauth_job(job) + + response = _client().get("/api/mcp/oauth/redirect?code=abc&state=early-state") + + assert response.status_code == 400 + assert not job.redirect_received.is_set() + + +def test_redirect_for_an_expired_job_is_rejected( + jobs: None, monkeypatch: pytest.MonkeyPatch +): + job = _waiting_job("late-state") + monkeypatch.setattr(job, "created_at", time.monotonic() - 16 * 60) + + response = _client().get("/api/mcp/oauth/redirect?code=abc&state=late-state") + + assert response.status_code == 400 + assert job.id not in _oauth_probe_jobs + + +def test_provider_error_fails_the_job_and_a_replay_is_rejected(jobs: None): + job = _waiting_job("the-state") + client = _client() + + denied = client.get( + "/api/mcp/oauth/redirect?state=the-state&error=access_denied" + "&error_description=The+user+denied+access" + ) + replay = client.get("/api/mcp/oauth/redirect?state=the-state&code=abc") + + assert denied.status_code == 400 + assert "The user denied access" in denied.text + assert job.redirect_error == "The user denied access" + assert job.redirect_result is None + assert replay.status_code == 409 + + +def test_redirect_route_does_not_need_the_session_api_key(jobs: None): + job = _waiting_job("keyless-state") + client = TestClient( + create_app(Config(session_api_keys=["a-session-key"])), + raise_server_exceptions=False, + ) + + assert client.get("/api/mcp/oauth/status/x").status_code == 401 + response = client.get("/api/mcp/oauth/redirect?code=abc&state=keyless-state") + + assert response.status_code == 200 + assert job.redirect_result is not None + assert job.redirect_result.code == "abc" + + +@pytest.mark.parametrize( + ("client_id", "static_redirect", "expected"), + [ + (None, None, PUBLIC_REDIRECT), + ("static-client", None, "http://localhost:"), + ( + "static-client", + "https://agent.example.com/api/mcp/oauth/redirect", + "https://agent.example.com/api/mcp/oauth/redirect", + ), + ], + ids=["dynamic-client", "static-client-keeps-loopback", "static-client-web-url"], +) +def test_pre_registered_clients_only_follow_a_configured_web_url( + client_id: str | None, static_redirect: str | None, expected: str +): + job = _MCPOAuthProbeJob( + request=MCPTestRequest.model_validate( + {"server": _oauth_server("https://mcp.example.com/mcp")} + ), + cipher=None, + public_redirect_url=static_redirect or PUBLIC_REDIRECT, + static_client_redirect_url=static_redirect, + ) + oauth = _BrowserCoordinatedOAuth( + job=job, mcp_url="https://mcp.example.com/mcp", client_id=client_id + ) + + redirect_uris = [ + str(uri) for uri in oauth.context.client_metadata.redirect_uris or [] + ] + assert len(redirect_uris) == 1 + assert redirect_uris[0].startswith(expected) + if client_id is not None: + assert oauth._static_client_info is not None + assert [ + str(uri) for uri in oauth._static_client_info.redirect_uris or [] + ] == redirect_uris + + +@pytest.mark.parametrize( + "callback_base_url", + [ + "ftp://canvas.example.test", + "https://user:pass@canvas.example.test", + "https://canvas.example.test/?next=x", + "https://canvas.example.test/#x", + "not a url", + ], +) +def test_callback_base_url_must_be_a_plain_http_base(callback_base_url: str): + response = _client().post( + "/api/mcp/oauth/start", + json={ + "server": _oauth_server("https://mcp.example.com/mcp"), + "callback_base_url": callback_base_url, + }, + ) + + assert response.status_code == 422