mcp_oauth.py 66 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269
  1. #!/usr/bin/env python3
  2. """MCP OAuth 2.1 client support: browser authorization-code flow with PKCE.
  3. The SDK's ``OAuthClientProvider`` does discovery, client identification, PKCE, exchange and
  4. refresh; this module supplies ``HermesTokenStorage`` (on-disk persistence), the localhost callback
  5. listener and ``build_oauth_auth()`` (legacy entry point). client_id is Hermes' Client ID Metadata
  6. Document URL (CIMD) when the server supports it, else RFC 7591 DCR. ``mcp_servers.<name>.oauth`` keys
  7. (all optional): client_id, client_secret, scope, redirect_port, redirect_uri (proxy callback),
  8. redirect_host, client_name, client_metadata_url, cimd, user_agent, timeout."""
  9. from pm import install_hint
  10. import asyncio
  11. import contextlib
  12. import contextvars
  13. import errno
  14. import html
  15. import importlib.util as _importlib_util
  16. import json
  17. import logging
  18. import os
  19. import re
  20. import socket
  21. import stat
  22. import sys
  23. import threading
  24. import time
  25. import webbrowser
  26. from functools import partialmethod
  27. # Cross-process advisory file locking for the refresh fence. Mirrors
  28. # cron/jobs.py: fcntl is Unix-only, msvcrt is the Windows fallback.
  29. try:
  30. import fcntl
  31. except ImportError: # pragma: no cover - non-Unix
  32. fcntl = None
  33. try:
  34. import msvcrt
  35. except ImportError: # pragma: no cover - non-Windows
  36. msvcrt = None
  37. from http.server import BaseHTTPRequestHandler, HTTPServer
  38. from pathlib import Path
  39. from typing import TYPE_CHECKING, Any
  40. from urllib.parse import parse_qs, urlparse
  41. from hermes_constants import secure_parent_dir
  42. from utils import atomic_json_write
  43. from tools.mcp_dashboard_oauth import contextvar_set as _contextvar_set, get_dashboard_oauth_flow
  44. if TYPE_CHECKING: # annotations only; the SDK is imported lazily at runtime
  45. from mcp.client.auth import OAuthClientProvider
  46. from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthMetadata, OAuthToken
  47. logger = logging.getLogger(__name__)
  48. # The refresh fence's critical section spans the token-endpoint POST, so it must
  49. # outlast a slow network round trip. Bounded anyway -- a wedged peer must not
  50. # strand us forever -- but generous enough that a healthy refresh never trips it.
  51. _REFRESH_FENCE_TIMEOUT_SECONDS = 60.0
  52. class RefreshFenceTimeout(RuntimeError):
  53. """The refresh fence could not be acquired within its bound.
  54. Raised so the caller FAILS CLOSED. Submitting a refresh token we are not
  55. certain we own is the whole defect class this fence exists to close: on a
  56. provider with single-use refresh tokens it burns the credential and logs
  57. the user out of a working session. Aborting this one refresh attempt is
  58. strictly cheaper -- the next request retries, and by then the peer that
  59. held the fence has published its replacement.
  60. """
  61. # POSIX flock: EWOULDBLOCK/EAGAIN, EACCES on some NFS; msvcrt.locking: EACCES/EDEADLK.
  62. # Same set as cron.scheduler._is_lock_contention_errno (not imported: that module is heavy).
  63. _FENCE_CONTENTION_ERRNOS = frozenset({errno.EWOULDBLOCK, errno.EAGAIN, errno.EACCES, errno.EDEADLK})
  64. def _refresh_lock_path(path: Path) -> Path:
  65. return path.with_suffix(path.suffix + ".refresh.lock")
  66. async def acquire_refresh_fence(path: Path, *, timeout: float = _REFRESH_FENCE_TIMEOUT_SECONDS) -> int:
  67. """Take the fence that owns one refresh generation across read -> POST -> persist.
  68. Token files are written atomically (``_write_json``), so a reader never
  69. sees a torn file; the only cross-process hazard is the read-modify-write
  70. of a single-use refresh token. The damaging interleaving is:
  71. A: get_tokens() -> R1
  72. B: get_tokens() -> R1
  73. A: POST R1 -> 200, receives R2
  74. B: POST R1 -> 400, credential already burned
  75. B: clear_tokens() -> user is logged out of a live session
  76. No lock scoped to one file read or write can prevent it: the fence must
  77. be held across the POST. It lives in a ``.refresh.lock`` sibling of the
  78. token file so the holder can still read/write the tokens normally.
  79. Entered from the SDK's coroutine-driven auth flow, so the wait is an
  80. ``asyncio.sleep`` poll on a non-blocking lock: a peer's slow network
  81. round trip must not freeze every other task on this event loop. No
  82. in-process lock layer is needed: an advisory lock on a fresh descriptor
  83. already excludes sibling tasks and threads of the same process.
  84. Acquisition failure RAISES. Degrading to "proceed unlocked" would
  85. reintroduce the exact race. Returns the locked descriptor; the caller
  86. hands it back to ``release_refresh_fence`` from its own exit path (the
  87. SDK drives the refresh as a generator, so no single ``with`` block can
  88. span the critical section).
  89. """
  90. lock_path = _refresh_lock_path(path)
  91. try:
  92. from hermes_constants import mkdir_under_hermes_home
  93. mkdir_under_hermes_home(lock_path.parent)
  94. secure_parent_dir(lock_path)
  95. fd = os.open(lock_path, os.O_RDWR | os.O_CREAT, 0o600)
  96. except OSError as exc:
  97. # No lock file means no ownership proof. Fail closed: see the
  98. # class docstring for why proceeding is worse than aborting.
  99. raise RefreshFenceTimeout(
  100. f"refresh fence unavailable ({lock_path.name}): {exc}"
  101. ) from exc
  102. deadline = time.monotonic() + timeout
  103. try:
  104. while True:
  105. try:
  106. if fcntl is not None:
  107. fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
  108. elif msvcrt is not None:
  109. msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
  110. else: # pragma: no cover - no advisory locking primitive
  111. raise RefreshFenceTimeout(
  112. "refresh fence unsupported: no flock/msvcrt on this platform"
  113. )
  114. return fd
  115. except OSError as exc:
  116. if exc.errno not in _FENCE_CONTENTION_ERRNOS:
  117. # Not "a peer holds it" but "this filesystem cannot lock"
  118. # (e.g. some network mounts). Still fail closed, but say so
  119. # now instead of spinning to the deadline and blaming a peer.
  120. raise RefreshFenceTimeout(
  121. f"refresh fence unavailable on this filesystem: {exc}"
  122. ) from exc
  123. if time.monotonic() >= deadline:
  124. raise RefreshFenceTimeout(
  125. f"refresh fence held by a peer for {timeout:.0f}s ({lock_path.name})"
  126. ) from None
  127. await asyncio.sleep(0.05)
  128. except BaseException:
  129. os.close(fd)
  130. raise
  131. def release_refresh_fence(fd: int) -> None:
  132. """Unlock and close a descriptor returned by ``acquire_refresh_fence``. Never raises."""
  133. try:
  134. if fcntl is not None:
  135. fcntl.flock(fd, fcntl.LOCK_UN)
  136. elif msvcrt is not None:
  137. msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
  138. except OSError:
  139. pass
  140. finally:
  141. with contextlib.suppress(OSError):
  142. os.close(fd)
  143. # ---------------------------------------------------------------------------
  144. # Lazy imports -- MCP SDK with OAuth support is optional
  145. # ---------------------------------------------------------------------------
  146. # SDK availability is detected WITHOUT importing mcp (~170 ms); classes bind lazily via _sdk_class().
  147. _OAUTH_AVAILABLE = _importlib_util.find_spec("mcp") is not None
  148. if not _OAUTH_AVAILABLE:
  149. logger.debug("MCP OAuth types not available -- OAuth MCP auth disabled")
  150. _SDK_CLASS_NAMES = ("OAuthClientProvider", "OAuthClientInformationFull", "OAuthClientMetadata", "OAuthMetadata", "OAuthToken")
  151. _SDK_CLASSES: dict[str, Any] = {}
  152. def _sdk_class(name: str) -> Any:
  153. """SDK OAuth class *name*, importing the SDK on first call; None when unavailable (a broken SDK is probed once)."""
  154. global _OAUTH_AVAILABLE
  155. if not _SDK_CLASSES:
  156. try:
  157. from mcp.client import auth as _client_auth
  158. from mcp.shared import auth as _shared_auth
  159. _SDK_CLASSES["OAuthClientProvider"] = _client_auth.OAuthClientProvider
  160. for _name in _SDK_CLASS_NAMES[1:]:
  161. _SDK_CLASSES[_name] = getattr(_shared_auth, _name)
  162. except (ImportError, AttributeError):
  163. _SDK_CLASSES.update(dict.fromkeys(_SDK_CLASS_NAMES))
  164. _OAUTH_AVAILABLE = False
  165. logger.debug("MCP OAuth types not available -- OAuth MCP auth disabled")
  166. return _SDK_CLASSES.get(name)
  167. try:
  168. from pydantic import AnyUrl
  169. except ImportError:
  170. AnyUrl = None # type: ignore[assignment, misc]
  171. class OAuthNonInteractiveError(RuntimeError):
  172. """Raised when OAuth requires browser interaction in a non-interactive env."""
  173. # Port of the most recent callback-port resolution. Legacy global; per-flow closures are the
  174. # real mechanism (concurrent flows must not share it).
  175. _oauth_port: int | None = None
  176. # Interactivity gates for OAuth stdin prompts. ContextVars, NOT threading.local: background
  177. # discovery sets them on its own thread while connect+OAuth runs on the `mcp-event-loop` thread
  178. # via run_coroutine_threadsafe, which copies the calling context into the coroutine. `forced`
  179. # pushes _is_interactive() past the TTY check for GUI-driven flows (dashboard/desktop REST; the
  180. # paste fallback degrades harmlessly to EOF). Suppression wins — background discovery must never
  181. # start a browser flow.
  182. _oauth_interactive_enabled = contextvars.ContextVar("_oauth_interactive_enabled", default=True)
  183. _oauth_interactive_forced = contextvars.ContextVar("_oauth_interactive_forced", default=False)
  184. # Paste-prompt tokens that exit OAuth without auth; the waiter maps the sentinel to
  185. # OAuthNonInteractiveError("user_skipped") so MCP setup continues without this server.
  186. _SKIP_TOKENS = frozenset({"skip", "cancel", "s", "n", "no", "q", "quit"})
  187. _USER_SKIPPED_SENTINEL = "__hermes_user_skipped__"
  188. def _get_token_dir(hermes_home: str | Path | None = None) -> Path:
  189. """``HERMES_HOME/mcp-tokens/`` — per-profile token directory."""
  190. from hermes_constants import get_hermes_home
  191. return Path(hermes_home if hermes_home is not None else get_hermes_home()) / "mcp-tokens"
  192. def _safe_filename(name: str) -> str:
  193. """Sanitize a server name for use as a filename (no path separators)."""
  194. return re.sub(r"[^\w\-]", "_", name).strip("_")[:128] or "default"
  195. # Callback-port reservation: bound-but-not-listening sockets keyed by port, held from selection
  196. # until the waiter adopts them (closes the select→bind TOCTOU window). Bounded so reconnect loops cannot leak fds.
  197. # Holding the socket from port-selection time until _wait_for_callback adopts it closes the TOCTOU window
  198. # where another process could grab the port between _find_free_port() closing its probe socket and
  199. # HTTPServer binding minutes later (#22161).
  200. _reserved_sockets: dict[int, socket.socket] = {}
  201. _MAX_RESERVED_SOCKETS = 8
  202. def _bind_reserved(port: int) -> int | None:
  203. """Bind ``127.0.0.1:port`` (0 = ephemeral) and park it until the waiter adopts it; None if taken.
  204. The cap evicts ephemeral parks only: losing a pinned CIMD port (the only ones the published
  205. document declares) mid-flow would reopen the race."""
  206. sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
  207. try:
  208. sock.bind(("127.0.0.1", port))
  209. except OSError:
  210. sock.close()
  211. if port:
  212. return None
  213. raise
  214. bound = sock.getsockname()[1]
  215. while len(_reserved_sockets) >= _MAX_RESERVED_SOCKETS:
  216. stale_port = next((p for p in _reserved_sockets if p not in _CIMD_PORTS), None)
  217. if stale_port is None:
  218. break # only pinned sockets remain — never evict those
  219. with contextlib.suppress(OSError):
  220. _reserved_sockets.pop(stale_port).close()
  221. _reserved_sockets[bound] = sock
  222. return bound
  223. def _reserve_callback_port() -> int:
  224. """Pick an ephemeral callback port and keep its socket bound (parked)."""
  225. return _bind_reserved(0) # type: ignore[return-value] # port 0 never returns None
  226. def _cached_client_info(storage: "HermesTokenStorage | None") -> dict | None:
  227. """The on-disk client registration for *storage*, or None."""
  228. try:
  229. info = _read_json(storage._client_info_path()) if storage is not None else None
  230. except (AttributeError, TypeError, ValueError):
  231. return None
  232. # A non-object payload is not a registration get_client_info could ever load, so callers
  233. # (CIMD eligibility, redirect reuse) must see "no cached registration", not "exists".
  234. return info if isinstance(info, dict) else None
  235. def _cached_redirect(storage: "HermesTokenStorage | None") -> tuple[str | None, int | None]:
  236. """``(https proxy URI, loopback callback port)`` from the cached client registration (None when
  237. absent): a DCR ``client_id`` is bound to its registered redirect URI, so a new random port under
  238. it gets ``redirect_uri does not match any registered URIs``."""
  239. uri = port = None
  240. info = _cached_client_info(storage)
  241. uris = info.get("redirect_uris") if isinstance(info, dict) else None
  242. for raw in uris if isinstance(uris, (list, tuple)) else ():
  243. try:
  244. parsed = urlparse(str(raw))
  245. # .port/.hostname are lazy properties that can raise ValueError on access —
  246. # resolve them inside the try so a malformed entry is skipped, not fatal.
  247. parsed_hostname, parsed_port = parsed.hostname, parsed.port
  248. except (TypeError, ValueError):
  249. continue
  250. if uri is None and parsed.scheme == "https" and parsed.netloc:
  251. uri = str(raw)
  252. is_loopback_callback = parsed.scheme == "http" and parsed.path == "/callback" and parsed_hostname in {"127.0.0.1", "localhost"}
  253. if port is None and is_loopback_callback and parsed_port is not None:
  254. port = int(parsed_port)
  255. return uri, port
  256. def _stdin_is_console() -> bool:
  257. """A human can type on stdin. ``isatty()`` alone is wrong on Windows: the CRT reports True for
  258. a DEVNULL / detached / CREATE_NO_WINDOW stdin (the gateway's), so a background process looked
  259. interactive and launched browser OAuth flows nobody could finish. Confirm with the console API
  260. there: ``GetConsoleMode`` fails on anything that is not a real console handle."""
  261. try:
  262. if not sys.stdin.isatty():
  263. return False
  264. except (AttributeError, ValueError):
  265. return False
  266. if os.name != "nt":
  267. return True
  268. try:
  269. import ctypes
  270. import msvcrt
  271. handle = msvcrt.get_osfhandle(sys.stdin.fileno())
  272. mode = ctypes.c_ulong()
  273. return bool(ctypes.windll.kernel32.GetConsoleMode(ctypes.c_void_p(handle), ctypes.byref(mode)))
  274. except Exception:
  275. return False
  276. def _is_interactive() -> bool:
  277. """True if we can reasonably expect to interact with a user."""
  278. if not _oauth_interactive_enabled.get():
  279. return False
  280. if _oauth_interactive_forced.get():
  281. return True
  282. return _stdin_is_console()
  283. def _raise_if_non_interactive(lead: str) -> None:
  284. """Raise ``OAuthNonInteractiveError`` unless interactive; *lead* is the boundary-specific first sentence.
  285. ``lead`` is the boundary-specific first sentence; this helper appends the shared, actionable ``hermes
  286. mcp login`` next-step so the guidance wording lives in one place across every non-interactive OAuth
  287. boundary (#57836).
  288. """
  289. if not _is_interactive():
  290. raise OAuthNonInteractiveError(
  291. f"{lead} Run `hermes mcp login <server>` interactively to (re)authorize, then restart or reload the gateway."
  292. )
  293. def force_interactive_oauth():
  294. """Treat the context as interactive despite no TTY (GUI-driven auth: the user IS present, just not
  295. on stdin). Crosses the MCP event-loop thread like ``suppress_interactive_oauth``.
  296. Opens the browser + localhost callback flow that the TTY heuristic would otherwise refuse. Same
  297. ContextVar propagation story as suppress_interactive_oauth() (#35927).
  298. """
  299. return _contextvar_set(_oauth_interactive_forced, True)
  300. def suppress_interactive_oauth():
  301. """Disable stdin-based OAuth prompts for the current context; ContextVar-based so a
  302. background-discovery thread's suppression reaches the coroutine on the MCP event-loop thread.
  303. Uses a ContextVar so the suppression propagates from a background-discovery thread onto the coroutine
  304. scheduled (via run_coroutine_threadsafe) on the dedicated MCP event-loop thread — where the OAuth
  305. callback actually runs (#35927). A threading.local would not cross that thread boundary.
  306. """
  307. return _contextvar_set(_oauth_interactive_enabled, False)
  308. def _can_open_browser() -> bool:
  309. """True if opening a browser is likely to work."""
  310. if os.environ.get("SSH_CLIENT") or os.environ.get("SSH_TTY"):
  311. return False # explicit SSH session → no local display
  312. if os.name == "nt" or (hasattr(os, "uname") and os.uname().sysname == "Darwin"):
  313. return True
  314. return bool(os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"))
  315. def _read_json(path: Path) -> dict | None:
  316. """Read a JSON file, returning None if it doesn't exist or is invalid."""
  317. if not path.exists():
  318. return None
  319. try:
  320. return json.loads(path.read_text(encoding="utf-8-sig"))
  321. except (json.JSONDecodeError, OSError) as exc:
  322. logger.warning("Failed to read %s: %s", path, exc)
  323. return None
  324. def _write_json(path: Path, data: dict) -> None:
  325. """OAuth tokens/client info at 0600 from creation, parent tightened to 0700 (``secure_parent_dir``
  326. refuses ``/``, top-level dirs and the install tree — #25821, #93050)."""
  327. from hermes_constants import mkdir_under_hermes_home
  328. mkdir_under_hermes_home(path.parent)
  329. secure_parent_dir(path)
  330. atomic_json_write(path, data, mode=0o600, default=str)
  331. def _model_json(model: Any) -> dict:
  332. """The on-disk JSON shape of an SDK pydantic model."""
  333. return model.model_dump(mode="json", exclude_none=True)
  334. class HermesTokenStorage:
  335. """Persist OAuth state as ``HERMES_HOME/mcp-tokens/<server_name>`` + ``.json`` (tokens),
  336. ``.client.json`` (client info), ``.meta.json`` (server metadata), ``.cimd-off`` (CIMD refused)."""
  337. def __init__(self, server_name: str, *, hermes_home: str | Path | None = None):
  338. self._server_name = _safe_filename(server_name)
  339. self._hermes_home = Path(hermes_home) if hermes_home is not None else None
  340. # Issuer binding: ``loaded_issuer`` is what the token file on disk recorded (the authorization
  341. # server that granted the stored refresh token); ``_bound_issuer`` is stamped onto the next
  342. # ``set_tokens`` write. See ``tools.mcp_oauth_provider.enforce_refresh_token_issuer``.
  343. self.loaded_issuer: str | None = None
  344. self._bound_issuer: str | None = None
  345. def _path(self, suffix: str) -> Path:
  346. return _get_token_dir(self._hermes_home) / f"{self._server_name}{suffix}"
  347. _tokens_path = partialmethod(_path, ".json")
  348. _client_info_path = partialmethod(_path, ".client.json")
  349. _meta_path = partialmethod(_path, ".meta.json")
  350. _cimd_rejected_path = partialmethod(_path, ".cimd-off")
  351. def _state_paths(self) -> tuple[Path, Path, Path]:
  352. return self._tokens_path(), self._client_info_path(), self._meta_path()
  353. @staticmethod
  354. def _load_model(path: Path, sdk_name: str, label: str, fixup=None):
  355. """Read *path* into SDK model *sdk_name*; None if absent, no SDK, or corrupt.
  356. ``fixup(data)`` may rewrite the raw dict before validation."""
  357. data = _read_json(path)
  358. if data is not None and not isinstance(data, dict):
  359. # A non-object payload (list/str/number) has no fields for the fixups' ``.get``/``.pop``
  360. # and cannot validate: treat it like any other corrupt file instead of crashing auth init.
  361. logger.warning("Corrupt %s at %s -- ignoring: expected a JSON object, got %s",
  362. label, path, type(data).__name__)
  363. return None
  364. cls = _sdk_class(sdk_name) if data is not None else None
  365. if (cls is not None and sdk_name == "OAuthMetadata" and isinstance(data, dict)
  366. and data.get("device_authorization_endpoint")):
  367. from tools.mcp_oauth_device import DeviceOAuthMetadata
  368. cls = DeviceOAuthMetadata
  369. if cls is None:
  370. return None
  371. if fixup is not None:
  372. fixup(data)
  373. try:
  374. return cls.model_validate(data)
  375. except (ValueError, TypeError, KeyError) as exc:
  376. # A pydantic ValidationError's str() echoes the raw input (the token material); log
  377. # only which fields failed.
  378. detail = exc
  379. if hasattr(exc, "errors"): # pydantic ValidationError
  380. detail = "validation failed for " + ", ".join(
  381. ".".join(map(str, e.get("loc", ()))) for e in exc.errors(include_input=False))
  382. logger.warning("Corrupt %s at %s -- ignoring: %s", label, path, detail)
  383. return None
  384. def _rebase_expires_in(self, data: dict) -> None:
  385. """Rewrite ``expires_in`` to seconds remaining from the stored absolute ``expires_at`` (not an
  386. SDK field, so stripped): a relative value reloaded after restart would make ``is_token_valid()``
  387. True for tokens that expired while down. Legacy files without it use the file mtime, clamped
  388. to zero (self-heals on the next ``set_tokens``)."""
  389. absolute_expiry = data.pop("expires_at", None)
  390. if absolute_expiry is not None:
  391. data["expires_in"] = int(max(absolute_expiry - time.time(), 0))
  392. elif data.get("expires_in") is not None:
  393. with contextlib.suppress(OSError, TypeError, ValueError):
  394. implied_expiry = self._tokens_path().stat().st_mtime + int(data["expires_in"])
  395. data["expires_in"] = int(max(implied_expiry - time.time(), 0))
  396. def _fixup_loaded_tokens(self, data: dict) -> None:
  397. # ``hermes_issuer`` is Hermes bookkeeping, not an SDK OAuthToken field: pop before validation.
  398. self.loaded_issuer = data.pop("hermes_issuer", None)
  399. self._rebase_expires_in(data)
  400. async def get_tokens(self) -> "OAuthToken | None":
  401. self.loaded_issuer = None
  402. return self._load_model(self._tokens_path(), "OAuthToken", "tokens", self._fixup_loaded_tokens)
  403. async def set_tokens(self, tokens: "OAuthToken") -> None:
  404. payload = _model_json(tokens)
  405. # Absolute ``expires_at``: see _rebase_expires_in.
  406. if payload.get("expires_in") is not None:
  407. with contextlib.suppress(TypeError, ValueError): # mock tokens / odd shapes: skip, don't fail persistence
  408. payload["expires_at"] = time.time() + int(payload["expires_in"])
  409. if self._bound_issuer: # which authorization server granted these tokens (never sent on the wire)
  410. payload["hermes_issuer"] = self._bound_issuer
  411. self.loaded_issuer = self._bound_issuer
  412. _write_json(self._tokens_path(), payload)
  413. logger.debug("OAuth tokens saved for %s", self._server_name)
  414. def bind_issuer(self, issuer: str | None) -> None:
  415. """Set the authorization-server issuer stamped on future token writes."""
  416. self._bound_issuer = str(issuer) if issuer else None
  417. def stamp_issuer(self, issuer: str) -> None:
  418. """Backfill ``hermes_issuer`` onto a pre-binding token file: adopt the currently discovered
  419. issuer once instead of forcing a re-login, so the *next* read is protected."""
  420. data = _read_json(self._tokens_path())
  421. if data is None or data.get("hermes_issuer"):
  422. return
  423. data["hermes_issuer"] = str(issuer)
  424. try:
  425. _write_json(self._tokens_path(), data)
  426. except OSError as exc: # non-fatal — worst case we stamp next time
  427. logger.debug("Could not stamp issuer on tokens for %s: %s", self._server_name, exc)
  428. return
  429. self.loaded_issuer = str(issuer)
  430. def strip_refresh_token(self) -> None:
  431. """Drop the refresh token (and its issuer record) from disk, keeping the access token: the
  432. unexpired access token may still be used, but a refresh token must never go to a different
  433. issuer than the one that granted it."""
  434. data = _read_json(self._tokens_path())
  435. if data is None or not data.get("refresh_token"):
  436. return
  437. data.pop("refresh_token", None)
  438. data.pop("hermes_issuer", None)
  439. self.loaded_issuer = None
  440. try:
  441. _write_json(self._tokens_path(), data)
  442. except OSError as exc:
  443. logger.warning("Could not strip refresh token for %s: %s", self._server_name, exc)
  444. return
  445. logger.info("Removed issuer-mismatched refresh token for %s (re-authorization will be required "
  446. "when the access token expires)", self._server_name)
  447. @staticmethod
  448. def _coerce_secret_auth_method(data: dict) -> bool:
  449. """Set ``client_secret_post`` when a secret is present but no method is: some DCR providers
  450. (Supabase) omit ``token_endpoint_auth_method``, the SDK defaults it to ``none`` and the
  451. exchange fails without the secret."""
  452. if data.get("client_secret") and data.get("token_endpoint_auth_method") in (None, "none", ""):
  453. data["token_endpoint_auth_method"] = "client_secret_post"
  454. return True
  455. return False
  456. async def get_client_info(self) -> "OAuthClientInformationFull | None":
  457. coerced: list[bool] = []
  458. info = self._load_model(
  459. self._client_info_path(), "OAuthClientInformationFull", "client info",
  460. lambda data: coerced.append(self._coerce_secret_auth_method(data)))
  461. if info is not None and coerced[0]:
  462. _write_json(self._client_info_path(), _model_json(info)) # persist so later flows skip the coercion
  463. return info
  464. async def set_client_info(self, client_info: "OAuthClientInformationFull") -> None:
  465. data = _model_json(client_info)
  466. self._coerce_secret_auth_method(data)
  467. _write_json(self._client_info_path(), data)
  468. logger.debug("OAuth client info saved for %s", self._server_name)
  469. def save_oauth_metadata(self, metadata: "OAuthMetadata") -> None:
  470. """Persist server metadata so a restarted process can refresh without re-discovery;
  471. otherwise the SDK guesses ``{server_url}/token`` (404) and forces re-auth."""
  472. _write_json(self._meta_path(), _model_json(metadata))
  473. logger.debug("OAuth metadata saved for %s", self._server_name)
  474. def load_oauth_metadata(self) -> "OAuthMetadata | None":
  475. return self._load_model(self._meta_path(), "OAuthMetadata", "OAuth metadata")
  476. def mark_cimd_rejected(self) -> None:
  477. """Durably record that this server refused our CIMD document so a restart does not re-present
  478. the refused client_id. Cleared by ``remove()`` so a fixed document gets a retry."""
  479. path = self._cimd_rejected_path()
  480. try:
  481. from hermes_constants import mkdir_under_hermes_home
  482. mkdir_under_hermes_home(path.parent)
  483. path.touch()
  484. except OSError as exc: # non-fatal — worst case we retry CIMD later
  485. logger.debug("Could not record CIMD rejection at %s: %s", path, exc)
  486. def cimd_rejected(self) -> bool:
  487. """True when this server has refused our metadata document before."""
  488. return self._cimd_rejected_path().exists()
  489. def remove(self, *, keep_metadata: bool = False) -> None:
  490. """Delete all stored OAuth state for this server; ``keep_metadata`` spares ``.meta.json`` so a
  491. re-login can still announce the discovered ``authorization_endpoint`` when the authorization
  492. server's metadata document cannot be re-fetched (#115329)."""
  493. # The ``.refresh.lock`` sidecar is deliberately kept: flock is inode-bound, so unlinking it
  494. # while a peer holds the fence would let the next acquirer lock a fresh inode (two holders).
  495. for p in (self._tokens_path(), self._client_info_path(), self._cimd_rejected_path(),
  496. *(() if keep_metadata else (self._meta_path(),))):
  497. p.unlink(missing_ok=True)
  498. def snapshot(self) -> dict[str, bytes]:
  499. """filename -> bytes of the existing state files; ``restore()`` it to undo a ``remove()`` after
  500. a failed re-auth so a valid token survives."""
  501. snap: dict[str, bytes] = {}
  502. for p in self._state_paths():
  503. with contextlib.suppress(OSError):
  504. snap[p.name] = p.read_bytes()
  505. return snap
  506. def restore(self, snapshot: dict[str, bytes], *, only_if_absent: bool = False) -> None:
  507. """Revert to a snapshot without overwriting a concurrent successful write."""
  508. if only_if_absent and any(path.exists() for path in self._state_paths()):
  509. logger.info("Skipping OAuth rollback for %s because newer state exists", self._server_name)
  510. return
  511. self.remove()
  512. if not snapshot:
  513. return
  514. token_dir = _get_token_dir(self._hermes_home)
  515. from hermes_constants import mkdir_under_hermes_home
  516. mkdir_under_hermes_home(token_dir)
  517. for fname, data in snapshot.items():
  518. try:
  519. fd = os.open(str(token_dir / fname), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, stat.S_IRUSR | stat.S_IWUSR)
  520. with os.fdopen(fd, "wb") as fh:
  521. fh.write(data)
  522. except OSError as exc:
  523. logger.warning("Failed to restore OAuth state %s: %s", fname, exc)
  524. def poison_client_registration(self) -> bool:
  525. """Discard a dead DCR client (``invalid_client`` at the token endpoint) plus stale ``meta.json``
  526. so the SDK re-registers next flow; tokens are kept (a valid refresh token survives if
  527. re-registration never completes). Keeps one ``.bak``. True if a client file was removed."""
  528. client_path = self._client_info_path()
  529. if not client_path.exists():
  530. return False
  531. backup = client_path.with_name(client_path.name + ".bak")
  532. try:
  533. backup.write_bytes(client_path.read_bytes())
  534. except OSError as exc: # non-fatal — proceed with the removal anyway
  535. logger.warning("Could not back up client info at %s: %s", client_path, exc)
  536. client_path.unlink(missing_ok=True)
  537. self._meta_path().unlink(missing_ok=True)
  538. logger.warning(
  539. "MCP OAuth '%s': cached client registration rejected as invalid_client; "
  540. "removed client.json + meta.json (backup at %s) to force re-registration",
  541. self._server_name, backup.name)
  542. return True
  543. def has_cached_tokens(self) -> bool:
  544. """True if we have tokens on disk (may be expired)."""
  545. return self._tokens_path().exists()
  546. def credential_stamp(self) -> tuple:
  547. """``stat()`` of the token and client files: what any re-authorization rewrites. No bytes read."""
  548. stamp = []
  549. for path in (self._tokens_path(), self._client_info_path()):
  550. try:
  551. st = path.stat()
  552. except OSError:
  553. stamp.append(None)
  554. else:
  555. stamp.append((st.st_mtime_ns, st.st_size, st.st_ino))
  556. return tuple(stamp)
  557. # Callback capture: the HTTP listener and the stdin paste reader share one result dict.
  558. def _authorization_code_result(code: str, state: str | None, iss: str | None = None):
  559. """Redirect parameters in the shape the installed SDK expects: mcp 2.0's ``callback_handler``
  560. returns an ``AuthorizationCodeResult`` (the SDK reads ``.state``/``.iss`` off it); older SDKs take a tuple."""
  561. try:
  562. from mcp.shared.auth import AuthorizationCodeResult
  563. except ImportError: # mcp < 2.0
  564. return code, state
  565. return AuthorizationCodeResult(code=code, state=state, iss=iss)
  566. def _parse_redirect_query(query: str) -> dict[str, Any]:
  567. """code/state/error/iss from a redirect query string. ``iss`` (RFC 9207 issuer) is kept: mcp 2.0
  568. rejects a response omitting it when the server advertised ``authorization_response_iss_parameter_supported``."""
  569. params = parse_qs(query)
  570. return {k: params.get(k, [None])[0] for k in ("code", "state", "error", "iss")}
  571. def _result_taken(result: dict) -> bool:
  572. return result.get("auth_code") is not None or result.get("error") is not None
  573. def _make_callback_handler() -> tuple[type, dict]:
  574. """Fresh ``(HandlerClass, result_dict)`` per flow so concurrent flows don't stomp on each other."""
  575. result: dict[str, Any] = {"auth_code": None, "state": None, "error": None, "iss": None}
  576. class _Handler(BaseHTTPRequestHandler):
  577. def do_GET(self) -> None:
  578. parsed = _parse_redirect_query(urlparse(self.path).query)
  579. status = 200
  580. if not parsed["code"] and not parsed["error"]:
  581. # Browsers follow the real /callback with queryless fetches (/favicon.ico); an unconditional
  582. # update here wrote four Nones over the code before the 500 ms waiter poll saw it (#116278).
  583. status, body = 404, "<h2>Not Found</h2>"
  584. elif _result_taken(result):
  585. # First terminal result (HTTP or paste) wins; a duplicate or refreshed callback never replaces it.
  586. body = "<h2>Authorization already received</h2><p>You can close this tab and return to Hermes.</p>"
  587. else:
  588. result.update(auth_code=parsed["code"], state=parsed["state"], error=parsed["error"], iss=parsed["iss"])
  589. body = ("<h2>Authorization Successful</h2><p>You can close this tab and return to Hermes.</p>" if parsed["code"]
  590. else f"<h2>Authorization Failed</h2><p>Error: {html.escape(parsed['error'] or 'unknown')}</p>")
  591. self.send_response(status)
  592. self.send_header("Content-Type", "text/html; charset=utf-8")
  593. self.end_headers()
  594. self.wfile.write(f"<html><body>{body}</body></html>".encode())
  595. def log_request(self, code: str = "-", size: str = "-") -> None:
  596. logger.debug("OAuth callback: %s %s", self.command, urlparse(self.path).path) # never the query (carries the code)
  597. def log_message(self, fmt: str, *args: Any) -> None:
  598. logger.debug("OAuth callback: %s", fmt % args)
  599. return _Handler, result
  600. def _paste_callback_reader(result: dict) -> None:
  601. """Read one stdin line as an OAuth redirect (full URL, bare query, or a ``_SKIP_TOKENS`` word that
  602. exits without auth) into *result*. Parse failures, EOF and interrupts are swallowed — best-effort
  603. fallback racing the HTTP listener, which stays primary."""
  604. try:
  605. line = sys.stdin.readline()
  606. except (KeyboardInterrupt, OSError, ValueError):
  607. return
  608. line = (line or "").strip()
  609. if not line or _result_taken(result):
  610. return # EOF / blank, or the HTTP listener already won
  611. if line.lower() in _SKIP_TOKENS:
  612. result["error"] = _USER_SKIPPED_SENTINEL
  613. print(
  614. " OAuth skipped. Run `hermes mcp login <server>` later to authenticate, "
  615. "or set ``enabled: false`` on that server in config.yaml to disable persistently.",
  616. file=sys.stderr)
  617. return
  618. # Full URL or "?code=...": take everything after the first "?".
  619. query = line.split("?", 1)[1] if "?" in line else line
  620. try:
  621. parsed = _parse_redirect_query(query.removeprefix("?"))
  622. except (ValueError, TypeError):
  623. print(" Could not parse pasted input as an OAuth redirect — ignoring.", file=sys.stderr)
  624. return
  625. if not parsed["code"] and not parsed["error"]:
  626. print(" Pasted input did not contain ``code=`` or ``error=`` — ignoring.", file=sys.stderr)
  627. return
  628. if _result_taken(result): # one more race-check before writing
  629. return
  630. result.update(auth_code=parsed["code"], state=parsed["state"], error=parsed["error"], iss=parsed["iss"])
  631. if parsed["code"]:
  632. print(" Got authorization code from paste — completing flow.", file=sys.stderr)
  633. # Remote-session hints printed under the authorization URL: a proxy callback forwards the redirect
  634. # here (no tunnel needed); on loopback it misses this machine, so the user pastes the URL back or SSH-forwards the port.
  635. _SSH_HINT_PROXY = (
  636. " Remote session detected. After you authorize, the provider redirects to\n"
  637. " {redirect_uri}\n"
  638. " which forwards to the callback listener on this machine — no SSH tunnel needed.\n")
  639. _SSH_HINT_LOOPBACK = (
  640. " Remote session detected. After you authorize, the provider redirects to\n"
  641. " http://{host}:{port}/callback\n"
  642. " which only the listener on THIS machine can receive. Two options:\n"
  643. "\n"
  644. " 1. Easiest — when your browser shows a connection error after\n"
  645. " authorizing, copy the full URL from the address bar and paste\n"
  646. " it at the prompt below. The pasted ``code=...&state=...`` is\n"
  647. " enough to complete the flow.\n"
  648. "\n"
  649. " 2. Or forward the port first in a separate terminal:\n"
  650. " ssh -N -L {port}:127.0.0.1:{port} <user>@<this-host>\n"
  651. " then open the URL above and let it redirect normally.\n"
  652. "\n"
  653. " See: https://hermes-agent.nousresearch.com/docs/guides/oauth-over-ssh\n")
  654. def _announce_authorization_url(
  655. authorization_url: str, port: int, redirect_uri: str | None, redirect_host: str | None = None,
  656. ) -> None:
  657. """Print the URL (always, as the fallback) and open the browser when possible."""
  658. print(f"\n MCP OAuth: authorization required.\n Open this URL in your browser:\n\n {authorization_url}\n", file=sys.stderr)
  659. if os.getenv("SSH_CLIENT") or os.getenv("SSH_TTY"):
  660. if redirect_uri:
  661. print(_SSH_HINT_PROXY.format(redirect_uri=redirect_uri), file=sys.stderr)
  662. elif port:
  663. print(_SSH_HINT_LOOPBACK.format(host=redirect_host or "127.0.0.1", port=port), file=sys.stderr)
  664. if not _can_open_browser():
  665. note = "Headless environment detected — open the URL manually."
  666. else:
  667. opened = False
  668. with contextlib.suppress(Exception):
  669. opened = webbrowser.open(authorization_url)
  670. note = "Browser opened automatically." if opened else "Could not open browser — please open the URL manually."
  671. print(f" ({note})\n", file=sys.stderr)
  672. def _make_redirect_handler(port: int, redirect_uri: str | None = None, redirect_host: str | None = None):
  673. """Redirect handler closing over this flow's port (a closure, not ``_oauth_port``, keeps concurrent
  674. flows isolated). ``redirect_uri`` is a configured proxy callback (None for loopback) and only tailors the
  675. hint; ``redirect_host`` is the loopback hostname the provider will actually redirect to (see
  676. :func:`_resolve_redirect_uri`).
  677. Using a closure instead of reading the module-level ``_oauth_port`` avoids cross-server state pollution
  678. when multiple MCP servers run OAuth concurrently (fixes #44588).
  679. """
  680. async def _redirect_handler(authorization_url: str) -> None:
  681. dashboard_flow = get_dashboard_oauth_flow()
  682. if dashboard_flow is not None:
  683. await dashboard_flow.publish_authorization_url(authorization_url)
  684. return
  685. # Fail fast when non-interactive: a cached-but-unusable token makes the SDK fall through to the
  686. # authorization-code flow past the token-file guard, and the waiter would block for the full timeout.
  687. # Fail fast at the authorization boundary in non-interactive contexts (systemd gateway, cron,
  688. # background MCP discovery). Without this check we would print a URL and launch a browser flow no
  689. # operator can complete, then block in _wait_for_callback for the full timeout. Raise before
  690. # launching so gateway adapters start promptly and the caller can skip this server with an
  691. # actionable warning. This intentionally re-checks interactivity here rather than trusting the
  692. # token-file existence guard alone. See #57836.
  693. _raise_if_non_interactive(
  694. "MCP OAuth requires browser authorization but no interactive session is available (non-interactive/background context)."
  695. )
  696. _announce_authorization_url(authorization_url, port, redirect_uri, redirect_host)
  697. return _redirect_handler
  698. def _start_callback_server(port: int, handler_cls: type) -> HTTPServer:
  699. """Bind the callback listener on *port*, adopting a parked reserved socket (closes the select→bind
  700. TOCTOU window). ``allow_reuse_address`` is set BEFORE binding (a no-op afterwards) so a lingering
  701. TIME_WAIT socket from a previous flow cannot block the next."""
  702. try:
  703. server = HTTPServer(("127.0.0.1", port), handler_cls, bind_and_activate=False)
  704. reserved = _reserved_sockets.pop(port, None)
  705. if reserved is not None:
  706. server.socket.close()
  707. server.socket, server.server_address = reserved, reserved.getsockname()
  708. else:
  709. server.allow_reuse_address = True
  710. server.server_bind()
  711. server.server_activate()
  712. except OSError as exc: # genuinely in use (concurrent flow / leftover listener / colliding redirect_port): say so, not "timed out"
  713. raise OAuthNonInteractiveError(
  714. f"OAuth callback port {port} is already in use ({exc}). Close any other in-progress login, "
  715. "or set a free `oauth.redirect_port` in the server config, then retry."
  716. ) from exc
  717. return server
  718. def _callback_outcome(result: dict, cimd_url: str | None):
  719. """Turn a filled/empty result dict into the SDK's callback value, or raise."""
  720. if result["error"] == _USER_SKIPPED_SENTINEL:
  721. raise OAuthNonInteractiveError("user_skipped")
  722. if result["error"]:
  723. raise RuntimeError(f"OAuth authorization failed: {result['error']}")
  724. if result["auth_code"] is None:
  725. hint = (
  726. " If the browser showed an invalid-client error instead of an approval prompt, the authorization "
  727. f"server rejected Hermes' Client ID Metadata Document ({cimd_url}); set ``cimd: false`` under that "
  728. "server's ``oauth:`` block in config.yaml to authorize via dynamic client registration instead."
  729. ) if cimd_url else ""
  730. raise OAuthNonInteractiveError(
  731. "OAuth callback timed out — no authorization code received. Ensure you completed the browser authorization flow." + hint
  732. )
  733. return _authorization_code_result(result["auth_code"], result["state"], result.get("iss"))
  734. def _make_callback_waiter(port: int, cimd_url: str | None = None, timeout: float = 300.0):
  735. """Callback waiter bound to one flow's port. ``timeout`` is where ``oauth.timeout`` applies (mcp 2.0
  736. dropped the provider's own). ``cimd_url`` only tailors the timeout message: a server refusing the
  737. document aborts at the authorization endpoint, so no redirect arrives and a bare "timed out" would
  738. hide the cause. Raises ``OAuthNonInteractiveError`` on timeout or when non-interactive.
  739. Closing over the port (instead of reading the module-level ``_oauth_port``) keeps concurrent OAuth flows
  740. isolated: flow A's waiter listens on flow A's port even when flow B's ``_configure_callback_port``
  741. overwrites the legacy global afterwards (#34260, the callback-side sibling of the #44588
  742. redirect-handler fix).
  743. """
  744. async def _wait():
  745. dashboard_flow = get_dashboard_oauth_flow()
  746. if dashboard_flow is not None and not port:
  747. # Dashboard flow speaks the legacy tuple; normalize to one shape. A pinned loopback port
  748. # (pre-registered client) listens locally instead; the dashboard only shows the URL.
  749. return _authorization_code_result(*await dashboard_flow.wait_for_callback())
  750. # The SDK entered the authorization-code flow, so any cached token is unusable. Reject BEFORE
  751. # binding: binding would block for the full timeout and collide with the TIME_WAIT port on retry.
  752. # Reject before binding the callback listener in non-interactive contexts. Reaching here means the
  753. # SDK entered the authorization-code flow (a valid or refreshable token would never call the
  754. # callback handler), so a cached token file is present but unusable. Binding the listener here would
  755. # block for the full 300s timeout and — on the next connection retry — collide with the
  756. # still-bound/TIME_WAIT port, surfacing as ``OSError: [Errno 98] Address already in use``. Failing
  757. # fast keeps gateway startup independent of an unusable optional MCP server. This guard holds
  758. # "regardless of whether a token file exists" — the point the build_oauth_auth token-file guard
  759. # cannot cover. See #57836.
  760. _raise_if_non_interactive(
  761. "OAuth callback requires an interactive session but none is available (non-interactive/background "
  762. "context); skipping browser authorization without binding a callback listener.")
  763. handler_cls, result = _make_callback_handler()
  764. server = _start_callback_server(port, handler_cls)
  765. # serve_forever/shutdown, not a bare handle_request thread: a thread parked in handle_request's
  766. # select() keeps the listening socket alive past server_close() (the kernel holds the file for
  767. # the duration of the poll), so a cancelled flow — e.g. the handshake timeout firing mid-login —
  768. # left the port bound and the retry on the same pinned/cached port died with EADDRINUSE (#113771).
  769. threading.Thread(target=server.serve_forever, kwargs={"poll_interval": 0.25}, daemon=True).start()
  770. # Paste fallback races the HTTP listener; whichever fills result first wins (no stdin reader
  771. # under a dashboard flow — the gateway's stdin is not the user's).
  772. if _is_interactive() and dashboard_flow is None:
  773. print(
  774. "\n Or paste the redirect URL here (or the ``?code=...&state=...`` portion) and press Enter. "
  775. "Type ``skip`` + Enter to continue without this server:",
  776. file=sys.stderr, flush=True)
  777. threading.Thread(target=_paste_callback_reader, args=(result,), daemon=True).start()
  778. elapsed = 0.0
  779. try:
  780. while elapsed < timeout and not _result_taken(result):
  781. await asyncio.sleep(0.5)
  782. elapsed += 0.5
  783. finally:
  784. server.shutdown() # returns once the serve loop exits (≤ poll_interval) — the port is free after close
  785. server.server_close()
  786. return _callback_outcome(result, cimd_url)
  787. return _wait
  788. # Legacy build_oauth_auth provider class, built lazily (SDK) and cached here.
  789. HermesOAuthClientProvider: Any = None
  790. def remove_oauth_tokens(server_name: str, *, hermes_home: str | Path | None = None) -> None:
  791. """Delete stored OAuth tokens and client info for a server."""
  792. HermesTokenStorage(server_name, hermes_home=hermes_home).remove()
  793. logger.info("OAuth tokens removed for '%s'", server_name)
  794. # CIMD (OAuth Client ID Metadata Documents): the client_id IS an HTTPS URL the server fetches for our
  795. # name/logo/redirect URIs, replacing per-install DCR. The SDK does the protocol; Hermes only decides
  796. # eligibility. Published from ``website/static/oauth/client-metadata.json``; the github.io origin is
  797. # deliberate — servers MUST NOT follow redirects when fetching it, and hermes-agent.nousresearch.com/docs/* 301s here.
  798. _CIMD_CLIENT_METADATA_URL = "https://nousresearch.github.io/hermes-agent/docs/oauth/client-metadata.json"
  799. # Loopback ports/hosts declared in that document (exact match, so no ephemeral port under CIMD);
  800. # below Linux's 32768 ephemeral floor. tests/tools/test_mcp_cimd.py keeps them in sync.
  801. _CIMD_PORTS = (27890, 27891, 27892, 27893, 27894)
  802. _CIMD_REDIRECT_HOSTS = frozenset({"127.0.0.1", "localhost"})
  803. def _is_valid_cimd_url(url: str) -> bool:
  804. """True when *url* is usable as a CIMD client_id on the installed SDK (ImportError = SDK predates
  805. CIMD → DCR only). The SDK checks only https + non-root path; userinfo, fragments and dot segments
  806. are rejected here because they fail mid-browser-flow as an opaque invalid-client page."""
  807. try:
  808. from mcp.client.auth.utils import is_valid_client_metadata_url
  809. if not is_valid_client_metadata_url(url):
  810. return False
  811. parsed = urlparse(url)
  812. has_userinfo = bool(parsed.username or parsed.password) # netloc parse can raise
  813. except (ImportError, ValueError):
  814. return False
  815. return not (has_userinfo or parsed.fragment or any(seg in {".", ".."} for seg in parsed.path.split("/")))
  816. # Pinned ports this process committed to (never released: a provider keeps its port for the process
  817. # lifetime), including ports restored from a cached registration.
  818. # Includes a port restored from a cached client registration, so a sibling server is never handed a port
  819. # another one is already registered on (#34260).
  820. _assigned_cimd_ports: list[int] = []
  821. def _pick_cimd_port() -> int | None:
  822. """Reserve a pinned CIMD callback port, or None when none is usable. Holding the bound socket makes
  823. contention cooperative: a sibling finds the bind refused and moves down the range. Once every pinned
  824. port belongs to this process the range wraps rather than falling back to DCR — a reused port only
  825. bites if both servers authorize at the same moment (reported by the waiter); DCR may be unsupported entirely.
  826. Holding the bound socket until ``_wait_for_callback`` adopts it does the same job here as
  827. ``_reserve_callback_port`` does for ephemeral ports (#22161): a fixed port is just as stealable in the
  828. minutes between selection and the browser redirect arriving.
  829. """
  830. for port in _CIMD_PORTS:
  831. if port not in _assigned_cimd_ports and _bind_reserved(port) is not None:
  832. _assigned_cimd_ports.append(port)
  833. return port
  834. return _assigned_cimd_ports[0] if _assigned_cimd_ports else None
  835. def _server_declined_cimd(storage: HermesTokenStorage | None) -> bool:
  836. """True when cached metadata shows this server doesn't advertise CIMD. The SDK decides CIMD vs DCR
  837. in its 401 branch — after Hermes must fix the redirect URI — so cached metadata closes the gap;
  838. only a genuinely unknown server pays the optimistic pin."""
  839. try:
  840. metadata = storage.load_oauth_metadata() if storage is not None else None
  841. except (AttributeError, TypeError, ValueError):
  842. return False
  843. return metadata is not None and getattr(metadata, "client_id_metadata_document_supported", None) is not True
  844. def _maybe_use_cimd(cfg: dict, storage: HermesTokenStorage | None = None) -> tuple[str, int] | None:
  845. """``(client_id URL, pinned callback port)``, or None to use DCR. Each ineligibility case means the
  846. redirect URI is not one the document declares, the client identity is already settled, or the
  847. server is known not to want a document — a metadata URL would be rejected."""
  848. url = cfg.get("client_metadata_url") or _CIMD_CLIENT_METADATA_URL
  849. ineligible = (
  850. cfg.get("cimd") is False
  851. or not _is_valid_cimd_url(url)
  852. # pinned client = explicit choice; a secret = confidential client, which the document forbids
  853. or cfg.get("client_id") or cfg.get("client_secret")
  854. # the document supplies name + auth method; setting either asks for an identity CIMD can't present
  855. or cfg.get("client_name") or (cfg.get("token_endpoint_auth_method") or "none") != "none"
  856. # dashboard/desktop flows redirect to a deployment-specific URL no static document declares
  857. or get_dashboard_oauth_flow() is not None
  858. or cfg.get("redirect_uri") or cfg.get("redirect_port")
  859. or (cfg.get("redirect_host") or "127.0.0.1") not in _CIMD_REDIRECT_HOSTS
  860. # an existing registration is bound to its redirect URI; swapping client_id would drop tokens
  861. or _cached_client_info(storage) is not None
  862. or (storage is not None and storage.cimd_rejected())
  863. or _server_declined_cimd(storage))
  864. port = None if ineligible else _pick_cimd_port()
  865. return None if port is None else (url, port)
  866. def cimd_provider_kwargs(cfg: dict) -> dict[str, Any]:
  867. """``client_metadata_url=`` kwargs for ``OAuthClientProvider`` when CIMD applies; omitted entirely
  868. on a DCR flow because an SDK too old for CIMD rejects the keyword outright."""
  869. url = cfg.get("_cimd_url")
  870. return {"client_metadata_url": url} if url else {}
  871. def token_request_user_agent(cfg: dict) -> str | None:
  872. """Configured ``oauth.user_agent`` for token-endpoint requests (exchange + refresh only, never MCP
  873. traffic or discovery), or None; a null/empty YAML value never sends a blank header. No other
  874. headers are configurable (secrets would land in config.yaml)."""
  875. ua = cfg.get("user_agent")
  876. return ua.strip() if isinstance(ua, str) and ua.strip() else None
  877. def login_connect_timeout(config: dict) -> float:
  878. """Connect bound for an interactive OAuth login probe (CLI ``hermes mcp login``, dashboard and
  879. Desktop re-auth): the server's ``connect_timeout`` or its ``oauth.timeout`` callback window
  880. (default 300 s) plus 15 s headroom for the token exchange, whichever is longer. A fixed 315 s
  881. floor here made raising ``oauth.timeout`` alone a no-op — the probe timed out first (#116278)."""
  882. def _seconds(value, default: float) -> float:
  883. try:
  884. return max(0.0, float(value))
  885. except (TypeError, ValueError):
  886. return default
  887. oauth_cfg = config.get("oauth") or {}
  888. return max(_seconds(config.get("connect_timeout"), 0.0),
  889. _seconds(oauth_cfg.get("timeout"), 300.0) + 15.0)
  890. def _configure_callback_port(cfg: dict, storage: HermesTokenStorage | None = None) -> int:
  891. """Resolve the callback port into ``cfg['_resolved_port']`` (0 = non-loopback URI). Precedence:
  892. dashboard flow / cached https redirect URI → CIMD pinned port (sets ``cfg['_cimd_url']``) →
  893. ``oauth.redirect_port`` → cached registration port → fresh ephemeral port (the only parked one).
  894. Also sets the legacy ``_oauth_port``.
  895. NOTE: also sets the legacy module-level ``_oauth_port`` so existing calls to ``_wait_for_callback`` keep
  896. working. The legacy global is the root cause of issue #5344 (port collision on concurrent OAuth flows);
  897. replacing it with a ContextVar is out of scope for this consolidation PR.
  898. """
  899. global _oauth_port
  900. dashboard_flow = get_dashboard_oauth_flow()
  901. # A pre-registered client with a pinned ``redirect_port`` (no DCR; the vendor matches the registered
  902. # loopback URI exactly) keeps its loopback listener even under the dashboard/Desktop flow: the
  903. # dashboard's own callback URL was never registered with the vendor, so that flow could not complete.
  904. pinned_loopback = bool(cfg.get("client_id") and cfg.get("redirect_port"))
  905. if dashboard_flow is not None and not pinned_loopback:
  906. cfg["_resolved_port"] = 0
  907. cfg["redirect_uri"] = cfg.get("redirect_uri") or dashboard_flow.redirect_uri
  908. return 0
  909. cached_uri, cached_port = _cached_redirect(storage)
  910. if cached_uri and not cfg.get("redirect_uri") and not pinned_loopback:
  911. cfg["redirect_uri"] = cached_uri
  912. cfg["_resolved_port"] = 0
  913. return 0
  914. cimd = _maybe_use_cimd(cfg, storage)
  915. if cimd is not None:
  916. cfg["_cimd_url"], port = cimd
  917. else:
  918. port = int(cfg.get("redirect_port", 0)) or cached_port or _reserve_callback_port()
  919. # A cached port may be a pinned CIMD port from an earlier login; claim it from siblings.
  920. if port in _CIMD_PORTS and port not in _assigned_cimd_ports:
  921. _assigned_cimd_ports.append(port)
  922. # Precedence: explicit config port → cached client-registration port → fresh ephemeral port. The cached
  923. # port keeps re-auth consistent with the redirect URI pinned at dynamic client registration (providers
  924. # reject a mismatched URI). Only a truly fresh ephemeral pick goes through _reserve_callback_port(),
  925. # which keeps the socket bound until _wait_for_callback adopts it — closing the select→bind TOCTOU race
  926. # (#22161). Explicit and cached ports are fixed, known values and bind via the reuse_address path
  927. # instead.
  928. cfg["_resolved_port"] = port
  929. _oauth_port = port
  930. return port
  931. def _resolve_redirect_uri(cfg: dict, port: int) -> str:
  932. """Configured ``redirect_uri`` (proxy) or ``http://<redirect_host>:<port>/callback``; the single
  933. derivation so client metadata and pre-registered info stay identical. ``redirect_host`` only changes
  934. the hostname (some WAFs reject a literal ``127.0.0.1``); the listener still binds ``127.0.0.1``."""
  935. return cfg.get("redirect_uri") or f"http://{cfg.get('redirect_host') or '127.0.0.1'}:{port}/callback"
  936. # Figma's remote MCP allowlists DCR by client_name ("Claude Code"/"Codex" register, others 403);
  937. # register under an allowlisted name so the flow can start. oauth.client_name overrides.
  938. _FIGMA_DCR_CLIENT_NAME = "Claude Code"
  939. _FIGMA_DEFAULT_SCOPE = "mcp:connect"
  940. def _is_figma_remote_mcp(server_name: str | None = None, server_url: str | None = None) -> bool:
  941. """True when this MCP server is Figma's hosted remote endpoint."""
  942. from utils import base_url_host_matches, base_url_hostname
  943. url = (server_url or "").lower()
  944. if base_url_host_matches(url, "mcp.figma.com") or (base_url_host_matches(url, "figma.com") and "/mcp" in url):
  945. return True
  946. # Name-only match only when the URL isn't some other host called figma-*.
  947. return "figma" in (server_name or "").lower() and (not url or "figma" in base_url_hostname(url))
  948. def apply_oauth_provider_defaults(cfg: dict, *, server_name: str = "", server_url: str | None = None) -> dict:
  949. """Mutate *cfg* with provider-specific OAuth workarounds (before building client metadata /
  950. pre-registering); returns *cfg*. Only fills keys the user left unset — explicit values win."""
  951. if _is_figma_remote_mcp(server_name, server_url):
  952. if not cfg.get("client_name"):
  953. cfg["client_name"] = _FIGMA_DCR_CLIENT_NAME
  954. logger.info(
  955. "MCP OAuth '%s': Figma DCR allowlist — registering as client_name=%r (override via oauth.client_name)",
  956. server_name or server_url, _FIGMA_DCR_CLIENT_NAME)
  957. if not cfg.get("scope"):
  958. cfg["scope"] = _FIGMA_DEFAULT_SCOPE
  959. # Figma advertises auth_method=none yet demands the returned client_secret at the token
  960. # endpoint; request a confidential registration so the SDK posts it.
  961. cfg["token_endpoint_auth_method"] = cfg.get("token_endpoint_auth_method") or "client_secret_post"
  962. return cfg
  963. def _build_client_metadata(cfg: dict) -> "OAuthClientMetadata":
  964. """Build OAuthClientMetadata; requires ``_configure_callback_port`` first."""
  965. port = cfg.get("_resolved_port")
  966. if port is None:
  967. raise ValueError("_configure_callback_port() must be called before _build_client_metadata()")
  968. metadata_cls = _sdk_class("OAuthClientMetadata")
  969. # Public client by default; confidential only with a known secret or a provider (Figma) needing confidential-style token posts.
  970. auth_method = cfg.get("token_endpoint_auth_method") or ("client_secret_post" if cfg.get("client_secret") else "none")
  971. metadata_kwargs: dict[str, Any] = {
  972. "client_name": cfg.get("client_name", "Hermes Agent"),
  973. "redirect_uris": [AnyUrl(_resolve_redirect_uri(cfg, port))],
  974. "grant_types": ["authorization_code", "refresh_token"],
  975. "response_types": ["code"],
  976. "token_endpoint_auth_method": auth_method,
  977. # SEP-837: OIDC-strict servers need application_type to accept loopback redirects; "native"
  978. # for a CLI/desktop app, overridable for a hosted https dashboard.
  979. "application_type": cfg.get("application_type", "native")}
  980. if cfg.get("scope"):
  981. metadata_kwargs["scope"] = cfg["scope"]
  982. try:
  983. return metadata_cls.model_validate(metadata_kwargs)
  984. except Exception: # mcp 1.x metadata models predate SEP-837 and reject the unknown field
  985. metadata_kwargs.pop("application_type", None)
  986. return metadata_cls.model_validate(metadata_kwargs)
  987. def _invalidate_tokens_on_client_change(
  988. storage: HermesTokenStorage, new_client_id: str, new_client_secret: str | None) -> None:
  989. """Drop cached tokens when the configured client identity changes: tokens minted under the old
  990. ``client_id`` fail refresh with ``invalid_client``, and pre-registered clients are exempt from
  991. auto-poison, so stale tokens would wedge every request until a manual wipe. Compares on-disk
  992. ``client.json`` BEFORE it is overwritten; a matching identity is a no-op.
  993. Matching identity is a no-op so live sessions and valid tokens are preserved. Port of
  994. cline/cline#12983's "invalidate tokens when OAuth client changes" invariant.
  995. """
  996. existing = _read_json(storage._client_info_path())
  997. old_client_id = existing.get("client_id") if isinstance(existing, dict) else None
  998. if not old_client_id or (old_client_id == new_client_id and (existing.get("client_secret") or None) == (new_client_secret or None)):
  999. return
  1000. removed = False
  1001. for path in (storage._tokens_path(), storage._meta_path()):
  1002. if not path.exists():
  1003. continue
  1004. try:
  1005. path.unlink()
  1006. removed = True
  1007. except OSError as exc: # non-fatal — stale tokens fail later anyway
  1008. logger.warning("MCP OAuth '%s': could not remove stale %s after client change: %s", storage._server_name, path.name, exc)
  1009. if removed:
  1010. logger.warning(
  1011. "MCP OAuth '%s': configured OAuth client changed (client_id %r -> %r); discarded tokens minted under "
  1012. "the previous client. Re-authorize with: hermes mcp login %s",
  1013. storage._server_name, old_client_id, new_client_id, storage._server_name)
  1014. def _maybe_preregister_client(storage: HermesTokenStorage, cfg: dict, client_metadata: "OAuthClientMetadata") -> None:
  1015. """If cfg has a pre-registered client_id, persist it to storage."""
  1016. client_id = cfg.get("client_id")
  1017. if not client_id:
  1018. return
  1019. info_cls = _sdk_class("OAuthClientInformationFull")
  1020. _invalidate_tokens_on_client_change(storage, client_id, cfg.get("client_secret"))
  1021. info_dict: dict[str, Any] = {
  1022. "client_id": client_id,
  1023. "redirect_uris": [_resolve_redirect_uri(cfg, cfg["_resolved_port"])],
  1024. "grant_types": client_metadata.grant_types,
  1025. "response_types": client_metadata.response_types,
  1026. "token_endpoint_auth_method": client_metadata.token_endpoint_auth_method,
  1027. **{key: cfg[key] for key in ("client_secret", "client_name", "scope") if cfg.get(key)}}
  1028. _write_json(storage._client_info_path(), _model_json(info_cls.model_validate(info_dict)))
  1029. logger.debug("Pre-registered client_id=%s for '%s'", client_id, storage._server_name)
  1030. def humanize_oauth_registration_error(
  1031. server_name: str, exc: BaseException | str, *, server_url: str | None = None) -> str | None:
  1032. """Turn a DCR 403/Forbidden or 404 into a useful next step; None for anything else so the caller keeps the
  1033. original text. Figma gates DCR on exact ``client_name`` (auto-set to ``Claude Code``), so this fires
  1034. when the user overrode it or an older Hermes is running."""
  1035. msg = str(exc)
  1036. lowered = msg.lower()
  1037. from tools.mcp_oauth_provider import _DISCOVERY_CONTEXT_LEAD
  1038. if msg.startswith(_DISCOVERY_CONTEXT_LEAD): # the 403 there is the metadata fetch, not a DCR refusal
  1039. return None
  1040. # A 404 on registration (Google's hosted Gmail/Drive MCP servers answer the SDK's guessed /register with
  1041. # one) is the same permanent "no RFC 7591 DCR" class as a 403 refusal (#78190).
  1042. if ("404" in msg and ("not found" in lowered or "/register" in lowered)
  1043. and any(k in lowered for k in ("regist", "dcr", "dynamic client"))):
  1044. return (
  1045. f"'{server_name}' does not support automatic client registration — the registration request returned "
  1046. "404 (typical for Google's hosted Gmail/Drive MCP servers and other providers without RFC 7591 dynamic "
  1047. "client registration). Create an OAuth client for this provider and add it under config.yaml as "
  1048. f"`oauth: {{client_id: ..., client_secret: ...}}`, then re-run:\n hermes mcp login {server_name}")
  1049. looks_like_registration = ("403" in msg or "forbidden" in lowered) and (
  1050. any(k in lowered for k in ("regist", "dcr", "dynamic client"))
  1051. or lowered.strip() in {"forbidden", "403 forbidden", "http 403: forbidden"}
  1052. or ("403" in msg and "forbidden" in lowered))
  1053. if not looks_like_registration:
  1054. return None
  1055. if _is_figma_remote_mcp(server_name, server_url):
  1056. return (
  1057. f"'{server_name}' is Figma's remote MCP — DCR is allowlisted by exact client_name "
  1058. f"(\"{_FIGMA_DCR_CLIENT_NAME}\" and \"Codex\" work; most other names 403). Hermes defaults to "
  1059. f"client_name: {_FIGMA_DCR_CLIENT_NAME!r} automatically. If you set oauth.client_name yourself, "
  1060. f"change it to one of those, or clear it and re-run:\n hermes mcp login {server_name}")
  1061. return (
  1062. f"'{server_name}' only allows pre-approved OAuth clients — it rejected client registration (403), so no "
  1063. "browser flow can start. Options: set oauth.client_name to a name the provider allowlists, add a "
  1064. "pre-registered client (oauth: {client_id: ..., client_secret: ...}), or use the provider's stdio / "
  1065. "API-key / local server instead.")
  1066. def build_oauth_auth(server_name: str, server_url: str, oauth_config: dict | None = None) -> "OAuthClientProvider | None":
  1067. """``httpx.Auth`` OAuth handler for an MCP server; None if the SDK lacks OAuth. Legacy API — new code
  1068. uses :func:`tools.mcp_oauth_manager.get_manager` so state is shared across config-time, runtime and reconnect paths."""
  1069. global HermesOAuthClientProvider
  1070. if not _OAUTH_AVAILABLE or _sdk_class("OAuthClientProvider") is None:
  1071. logger.warning("MCP OAuth requested for '%s' but SDK auth types are not available. Run: "
  1072. f"{install_hint('mcp')}", server_name)
  1073. return None
  1074. from tools.mcp_oauth_provider import build_provider_kwargs, prepare_oauth_config
  1075. cfg, storage = prepare_oauth_config(server_name, server_url, oauth_config)
  1076. if not _is_interactive() and not storage.has_cached_tokens():
  1077. raise OAuthNonInteractiveError(
  1078. f"MCP OAuth for '{server_name}': non-interactive environment and no cached tokens found. The OAuth flow "
  1079. f"requires browser authorization. Run `hermes mcp login {server_name}` interactively first to complete "
  1080. "initial authorization, then cached tokens will be reused.")
  1081. kwargs = build_provider_kwargs(cfg, storage, ssh_proxy_hint=True)
  1082. if HermesOAuthClientProvider is None:
  1083. from tools.mcp_oauth_provider import HermesProviderMixin
  1084. HermesOAuthClientProvider = type("HermesOAuthClientProvider", (HermesProviderMixin, _sdk_class("OAuthClientProvider")), {
  1085. "__doc__": "SDK provider plus Hermes' token-endpoint fixes (see ``HermesProviderMixin``).",
  1086. "__module__": __name__, "_hermes_logger": logger})
  1087. return HermesOAuthClientProvider(server_url=server_url, **kwargs)