mcp_oauth.py 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356
  1. """MCP OAuth worker and callback receivers used by connection cards and gateway RPC flows."""
  2. from __future__ import annotations
  3. import http.server
  4. import logging
  5. import os
  6. import secrets
  7. import threading
  8. import time
  9. from contextlib import suppress
  10. from dataclasses import dataclass
  11. from pathlib import Path
  12. from typing import Any, Callable, Dict, Optional
  13. from urllib.parse import urlparse
  14. logger = logging.getLogger(__name__)
  15. URL_TIMEOUT_SECONDS = 30.0
  16. def probe_with_rollback(
  17. server_name: str, cfg: dict, hermes_home: str, flow, reconnect_live: bool, *,
  18. on_commit: Optional[Callable[[], None]] = None) -> None:
  19. """Roll back failures through initialize; commit authorization before tool discovery.
  20. ``on_commit`` runs right after the configuration is saved: a card install persists its setup
  21. values there, so they land with the authorization and never before it."""
  22. from hermes_cli.mcp_config import _oauth_tokens_present, _probe_single_server
  23. from tools.mcp_dashboard_oauth import exception_message
  24. from tools.mcp_oauth import HermesTokenStorage, login_connect_timeout
  25. from tools.mcp_oauth_manager import get_manager
  26. manager = get_manager()
  27. storage = HermesTokenStorage(server_name)
  28. # An attempt that replaced a still-running one starts from that one's half-written files, so
  29. # it carries the older attempt's snapshot: the state from before either of them.
  30. backup = getattr(flow, "inherited_backup", None) or storage.snapshot()
  31. if flow is not None:
  32. flow.backup = backup
  33. previous_entry = None
  34. details: dict[str, Any] = {}
  35. tools: list = []
  36. discovery_error = ""
  37. def undo() -> None:
  38. # ``manager.remove`` cleared the pre-attempt tokens, so anything on disk now is this
  39. # attempt's grant, and it is not being kept: put the snapshot back. A newer attempt for
  40. # the same server owns the token files; an older one must not write over it.
  41. if flow is not None and _ACTIVE.get((hermes_home, server_name)) not in (None, flow):
  42. return
  43. storage.restore(backup)
  44. manager.restore_entry(server_name, previous_entry, hermes_home=hermes_home)
  45. try:
  46. previous_entry = manager.remove(server_name, hermes_home=hermes_home)
  47. tools = _probe_single_server(
  48. server_name, cfg, connect_timeout=login_connect_timeout(cfg), details=details)
  49. if not _oauth_tokens_present(server_name):
  50. details["initialized"] = False
  51. no_token = RuntimeError(
  52. "The server responded, but no OAuth token was obtained — "
  53. "this provider may require a manually-registered OAuth client.")
  54. no_token.failure_class = "auth_required" # type: ignore[attr-defined]
  55. raise no_token
  56. except Exception as exc:
  57. if not details.get("initialized"):
  58. undo()
  59. raise
  60. tools, discovery_error = [], exception_message(exc)
  61. try:
  62. _commit(server_name, cfg, on_commit, flow)
  63. except AttemptCanceled:
  64. undo()
  65. raise
  66. if flow is not None:
  67. flow.tools = [{"name": t, "description": d} for t, d in tools]
  68. flow.discovery_error = discovery_error
  69. flow.mark_approved()
  70. if discovery_error:
  71. return
  72. if reconnect_live:
  73. from tools.mcp_tool_loop import reconnect_mcp_server
  74. reconnect_mcp_server(server_name)
  75. class AttemptCanceled(RuntimeError):
  76. """The user canceled this attempt before it committed; nothing of it is kept."""
  77. # One lock orders a cancel against the commit, so an attempt is either canceled with nothing kept or
  78. # committed with everything kept. A worker parked inside the token request cannot be interrupted;
  79. # it is stopped here, at the one point where its result would be adopted.
  80. _COMMIT_GUARD = threading.Lock()
  81. # (hermes home, server) -> the newest card attempt. A retry or a new operation replaces an attempt
  82. # whose worker is still waiting on the browser; the older one is canceled so it cannot commit later.
  83. _ACTIVE: dict[tuple, Any] = {}
  84. def cancel_attempt(flow) -> bool:
  85. """Cancel a card attempt. True when it had already committed: the authorization stays."""
  86. with _COMMIT_GUARD:
  87. if getattr(flow, "committed", False):
  88. return True
  89. flow.cancelled = True
  90. # Wakes a worker that is still waiting for the browser; a cancelled flow is never re-minted.
  91. flow.mark_error("canceled", cancelled=True)
  92. return False
  93. def _commit(server_name: str, cfg: dict, on_commit: Optional[Callable[[], None]], flow=None) -> None:
  94. from hermes_cli.mcp_config import _save_mcp_server
  95. with _COMMIT_GUARD:
  96. if flow is not None and getattr(flow, "cancelled", False):
  97. raise AttemptCanceled("canceled")
  98. if not _save_mcp_server(server_name, cfg):
  99. raise RuntimeError(f"'{server_name}' was rejected: suspicious command/args configuration")
  100. if on_commit is not None:
  101. on_commit()
  102. if flow is not None:
  103. flow.committed = True
  104. def _reuse_saved_authorization(
  105. server_name: str, cfg: dict, flow, on_commit: Optional[Callable[[], None]]) -> bool:
  106. """Connect with the tokens already on disk, with no browser step and no consent.
  107. Retrying discovery for a server that is authorized must not ask the user to sign in again, and
  108. must not delete the working grant first. Any failure here falls through to the interactive
  109. flow, which replaces the grant."""
  110. from hermes_cli.mcp_config import _oauth_tokens_present, _probe_single_server
  111. from tools.mcp_oauth import suppress_interactive_oauth
  112. if not _oauth_tokens_present(server_name):
  113. return False
  114. try:
  115. with suppress_interactive_oauth():
  116. tools = _probe_single_server(server_name, cfg, connect_timeout=30)
  117. _commit(server_name, cfg, on_commit, flow)
  118. except Exception as exc:
  119. logger.debug("saved authorization for %s was not usable: %s", server_name, exc)
  120. return False
  121. if flow is not None:
  122. flow.tools = [{"name": t, "description": d} for t, d in tools]
  123. flow.discovery_error = ""
  124. flow.mark_approved()
  125. return True
  126. def run_worker(
  127. hermes_home: str, server_name: str, cfg: dict, reconnect_live: bool, *,
  128. flow, on_done: Optional[Callable[[], None]] = None,
  129. env: Optional[dict[str, str]] = None, on_commit: Optional[Callable[[], None]] = None,
  130. reuse_saved: bool = False) -> None:
  131. """Drive the interactive MCP OAuth probe under the shared callback bridge.
  132. ``env`` holds a card install's setup values. They join the secret scope for this attempt only,
  133. so the configuration can reference them before anything is saved. ``reuse_saved`` is the
  134. card's rule: a server whose saved tokens still work connects with no consent step. The RPC
  135. session surface keeps it off, because its caller waits for an authorization URL."""
  136. from hermes_constants import reset_hermes_home_override, set_hermes_home_override
  137. try:
  138. from agent.secret_scope import (
  139. build_profile_secret_scope, reset_secret_scope, set_secret_scope)
  140. from tools.mcp_dashboard_oauth import dashboard_oauth_flow
  141. from tools.mcp_oauth import force_interactive_oauth
  142. home_token = secret_token = None
  143. try:
  144. home_token = set_hermes_home_override(hermes_home)
  145. secret_token = set_secret_scope(
  146. {**build_profile_secret_scope(Path(hermes_home)), **(env or {})}, profile_home=hermes_home)
  147. if not (reuse_saved and flow is not None
  148. and _reuse_saved_authorization(server_name, cfg, flow, on_commit)):
  149. with force_interactive_oauth(), dashboard_oauth_flow(flow):
  150. probe_with_rollback(
  151. server_name, cfg, hermes_home, flow, reconnect_live, on_commit=on_commit)
  152. finally:
  153. if secret_token is not None:
  154. reset_secret_scope(secret_token)
  155. if home_token is not None:
  156. reset_hermes_home_override(home_token)
  157. except Exception as exc:
  158. from hermes_cli.mcp_config import probe_failure_class
  159. from tools.mcp_dashboard_oauth import exception_message
  160. msg = exception_message(exc)
  161. with suppress(Exception):
  162. from tools.mcp_oauth import humanize_oauth_registration_error
  163. msg = humanize_oauth_registration_error(
  164. server_name, exc, server_url=cfg.get("url") if isinstance(cfg, dict) else None
  165. ) or msg
  166. failure_class = probe_failure_class(exc)
  167. if failure_class == "connect_failed" and server_name not in msg: # e.g. a bare "Not Found"
  168. msg = f"Could not connect to '{server_name}' ({msg}). Check its URL and that this machine can reach it."
  169. if flow is not None:
  170. # Read by ``start``: its error is rebuilt from text, so the class rides on the flow.
  171. flow.failure_class = failure_class
  172. flow.mark_error(msg)
  173. finally:
  174. if flow is not None:
  175. flow.mark_worker_done()
  176. with _COMMIT_GUARD:
  177. if _ACTIVE.get((hermes_home, server_name)) is flow:
  178. _ACTIVE.pop((hermes_home, server_name), None)
  179. if on_done is not None:
  180. on_done()
  181. def _validate_client_redirect_uri(uri: str) -> str:
  182. """Accept only plain-http loopback URLs (RFC 8252)."""
  183. parsed = urlparse(str(uri or "").strip())
  184. host = (parsed.hostname or "").lower()
  185. if (parsed.scheme != "http" or host not in ("127.0.0.1", "localhost", "::1") or not parsed.port
  186. or parsed.username is not None or parsed.password is not None):
  187. raise ValueError(
  188. "client_redirect_uri must be a loopback http URL like http://127.0.0.1:<port>/callback")
  189. return f"http://{'[' + host + ']' if ':' in host else host}:{parsed.port}{parsed.path or '/callback'}"
  190. def _start_loopback_receiver(flow) -> http.server.HTTPServer:
  191. """Bind the single backend-hosted one-shot receiver and feed its callback into ``flow``."""
  192. from tools.mcp_oauth import _parse_redirect_query
  193. class _Handler(http.server.BaseHTTPRequestHandler):
  194. def do_GET(self):
  195. parsed = urlparse(self.path)
  196. if parsed.path.rstrip("/") not in ("/callback", ""):
  197. self.send_response(404)
  198. self.end_headers()
  199. return
  200. body = b"<h1>Authorization received</h1><p>You can close this tab and return to Hermes.</p>"
  201. status = 200
  202. try:
  203. flow.deliver_callback(**_parse_redirect_query(parsed.query))
  204. except Exception:
  205. body = b"<h1>OAuth callback rejected</h1><p>The callback was invalid or already used.</p>"
  206. status = 400
  207. self.send_response(status)
  208. self.send_header("Content-Type", "text/html; charset=utf-8")
  209. self.end_headers()
  210. with suppress(Exception):
  211. self.wfile.write(body)
  212. def log_message(self, format, *args):
  213. return
  214. httpd = http.server.HTTPServer(("127.0.0.1", 0), _Handler)
  215. threading.Thread(
  216. target=httpd.serve_forever, kwargs={"poll_interval": 0.5}, daemon=True,
  217. name=f"mcp-oauth-cb-{flow.server_name}").start()
  218. return httpd
  219. def _pinned_loopback(cfg: dict) -> bool:
  220. oauth = cfg.get("oauth") or {}
  221. return bool(oauth.get("client_id") and oauth.get("redirect_port"))
  222. def _pinned_redirect_uri(cfg: dict) -> str:
  223. oauth = cfg.get("oauth") or {}
  224. host = oauth.get("redirect_host") or "127.0.0.1"
  225. return f"http://{host}:{oauth['redirect_port']}/callback"
  226. def choose_callback_receiver(flow, cfg: dict, client_redirect_uri: Optional[str] = None):
  227. """Set the redirect consumed by the SDK and return the optional backend HTTP receiver."""
  228. if _pinned_loopback(cfg):
  229. flow.redirect_uri = _pinned_redirect_uri(cfg)
  230. return None
  231. if client_redirect_uri is not None:
  232. flow.redirect_uri = _validate_client_redirect_uri(client_redirect_uri)
  233. return None
  234. httpd = _start_loopback_receiver(flow)
  235. flow.redirect_uri = f"http://127.0.0.1:{httpd.server_address[1]}/callback"
  236. return httpd
  237. def _ssh_detail(redirect_uri: str) -> str:
  238. if not (os.environ.get("SSH_CLIENT") or os.environ.get("SSH_TTY")) or not redirect_uri:
  239. return ""
  240. from tools.mcp_oauth import _SSH_HINT_LOOPBACK
  241. parsed = urlparse(redirect_uri)
  242. return _SSH_HINT_LOOPBACK.format(host=parsed.hostname or "127.0.0.1", port=parsed.port or 0).strip()
  243. @dataclass
  244. class OAuthAttempt:
  245. """One flow in flight: its URL, callback bridge, and outcome."""
  246. auth_url: str
  247. flow: Any
  248. detail: str = ""
  249. def poll(self) -> dict[str, Any]:
  250. snapshot = self.flow.snapshot()
  251. raw = snapshot.get("status")
  252. status = raw if raw in ("approved", "error") else "pending"
  253. tools = [str(t.get("name") or "") for t in (getattr(self.flow, "tools", None) or [])]
  254. return {"status": status, "error": snapshot.get("error") or "",
  255. "tools": [t for t in tools if t] if status == "approved" else [],
  256. "discovery_error": (getattr(self.flow, "discovery_error", "") or "")
  257. if status == "approved" else ""}
  258. def start(
  259. server_name: str, *, url_timeout: float = URL_TIMEOUT_SECONDS,
  260. client_redirect_uri: Optional[str] = None, cfg: Optional[dict] = None,
  261. env: Optional[dict[str, str]] = None, on_commit: Optional[Callable[[], None]] = None,
  262. ) -> OAuthAttempt:
  263. """Start a card OAuth flow and wait until its authorization URL is published.
  264. ``cfg`` is an install's in-memory configuration; without it the saved one is authorized."""
  265. from hermes_cli.mcp_config import _get_mcp_servers
  266. from hermes_constants import get_hermes_home
  267. from tools.mcp_dashboard_oauth import DashboardOAuthFlow
  268. from tui_gateway import mcp_oauth_sessions
  269. cfg = dict(cfg if cfg is not None else _get_mcp_servers().get(server_name) or {})
  270. if not cfg:
  271. raise RuntimeError(f"'{server_name}' is not a configured MCP server")
  272. if not cfg.get("url"):
  273. raise RuntimeError(f"'{server_name}' is a stdio server: it takes env keys, not OAuth")
  274. cfg["auth"] = "oauth"
  275. hermes_home = str(get_hermes_home().expanduser().resolve(strict=False))
  276. flow = DashboardOAuthFlow(
  277. flow_id=secrets.token_urlsafe(24), server_name=server_name, profile=None,
  278. hermes_home=hermes_home, redirect_uri="", reconnect_live=False)
  279. with _COMMIT_GUARD:
  280. older = _ACTIVE.get((hermes_home, server_name))
  281. _ACTIVE[(hermes_home, server_name)] = flow
  282. if older is not None and not older.worker_done:
  283. flow.inherited_backup = getattr(older, "backup", None)
  284. cancel_attempt(older)
  285. httpd = choose_callback_receiver(flow, cfg, client_redirect_uri)
  286. mcp_oauth_sessions.register_flow(flow, httpd=httpd)
  287. threading.Thread(
  288. target=run_worker, args=(hermes_home, server_name, cfg, False),
  289. kwargs={"flow": flow, "on_done": lambda: mcp_oauth_sessions.finish_flow(flow.flow_id),
  290. "reuse_saved": True,
  291. **({"env": env, "on_commit": on_commit} if env or on_commit else {})},
  292. daemon=True, name=f"mcp-oauth-{server_name}").start()
  293. deadline = time.time() + url_timeout
  294. while time.time() < deadline:
  295. snapshot = flow.snapshot()
  296. if snapshot.get("status") == "approved":
  297. return OAuthAttempt(auth_url="", flow=flow) # the saved authorization still works
  298. if snapshot.get("authorization_url"):
  299. return OAuthAttempt(
  300. auth_url=snapshot["authorization_url"], flow=flow,
  301. detail=_ssh_detail(flow.redirect_uri) if client_redirect_uri is None else "")
  302. if snapshot.get("status") == "error":
  303. failed = RuntimeError(snapshot.get("error") or "the OAuth flow failed before authorization")
  304. failed.failure_class = getattr(flow, "failure_class", None) # type: ignore[attr-defined]
  305. raise failed
  306. time.sleep(0.05)
  307. flow.mark_error("Timed out waiting for MCP authorization URL")
  308. raise TimeoutError(f"timed out waiting for the authorization URL for '{server_name}'")