`gj UdZddlmZddlZddlZddlZddlZddlmZm Z ddl m Z ddl m Z mZejeZddZeGdd Zdd ZeZd ed <Gd dZdaded<ej2ZddZddZy)u?Central manager for per-server MCP OAuth state. One instance shared across the process. Holds per-server OAuth provider instances and coordinates: - **Cross-process token reload** via mtime-based disk watch. When an external process (e.g. a user cron job) refreshes tokens on disk, the next auth flow picks them up without requiring a process restart. - **401 deduplication** via in-flight futures. When N concurrent tool calls all hit 401 with the same access_token, only one recovery attempt fires; the rest await the same result. - **Reconnect signalling** for long-lived MCP sessions. The manager itself does not drive reconnection — the `MCPServerTask` in `mcp_tool.py` does — but the manager is the single source of truth that decides when reconnect is warranted. Replaces what used to be scattered across eight call sites in `mcp_oauth.py`, `mcp_tool.py`, and `hermes_cli/mcp_config.py`. This module is the ONLY place that instantiates the MCP SDK's `OAuthClientProvider` — all other code paths go through `get_manager()`. Design reference: - Claude Code's ``invalidateOAuthCacheIfDiskChanged`` (``claude-code/src/utils/auth.ts:1320``, CC-1096 / GH#24317). Identical external-refresh staleness bug class. - Codex's ``refresh_oauth_if_needed`` / ``persist_if_needed`` (``codex-rs/rmcp-client/src/rmcp_client.rs:805``). We lean on the MCP SDK's lazy refresh rather than calling refresh before every op, because one ``stat()`` per tool call is cheaper than an ``await`` + potential refresh round-trip, and the SDK's in-memory expiry path is already correct. ) annotationsN) dataclassfield)Path)AnyOptionalc`ddlm} ||||}}|j|jk(xrn|jj |jj k(xr7|j jd|j jdk(S#t$rYywxYw)aReturn True if two URLs target the same endpoint (ignoring query/fragment). Compares scheme, host (case-insensitive), and path. Used to confirm a rejected response actually came from the OAuth token endpoint before we act on an ``invalid_client`` body. r)urlsplitF/) urllib.parser ValueErrorschemenetloclowerpathrstrip)abr papbs J/root/.hermes/venv/lib/python3.12/site-packages/tools/mcp_oauth_manager.py_same_endpointr0s&!hqkB RYY 7 IIOO !2 2 7 GGNN3 277>>##6 6 sB!! B-,B-ceZdZUdZded<ded<dZded<d Zd ed <eej Z d ed<ee Z ded<y)_ProviderEntryaPer-server OAuth state tracked by the manager. Fields: server_url: The MCP server URL used to build the provider. Tracked so we can discard a cached provider if the URL changes. oauth_config: Optional dict from ``mcp_servers..oauth``. provider: The ``httpx.Auth``-compatible provider wrapping the MCP SDK. None until first use. last_mtime_ns: Last-seen ``st_mtime_ns`` of the on-disk tokens file. Zero if never read. Used by :meth:`MCPOAuthManager.invalidate_if_disk_changed` to detect external refreshes. lock: Serialises concurrent access to this entry's state. Bound to whichever asyncio loop first awaits it (the MCP event loop). pending_401: In-flight 401-handler futures keyed by the failed access_token, for deduplicating thundering-herd 401s. Mirrors Claude Code's ``pending401Handlers`` map. str server_urlOptional[dict] oauth_configN Optional[Any]providerrint last_mtime_ns)default_factoryz asyncio.Locklockz!dict[str, 'asyncio.Future[bool]'] pending_401) __name__ __module__ __qualname____doc____annotations__r r"rasyncioLockr$dictr%rrrIsK$O  "Hm"M3w||.HermesMCPOAuthProvideraLOAuthClientProvider with pre-flow disk-mtime reload. Before every ``async_auth_flow`` invocation, asks the manager to check whether the tokens file on disk has been modified externally. If so, the manager resets ``_initialized`` so the next flow re-reads from storage. This makes external-process refreshes (cron, another CLI instance) visible to the running MCP session without requiring a restart. Reference: Claude Code's ``invalidateOAuthCacheIfDiskChanged`` (``src/utils/auth.ts:1320``, CC-1096 / GH#24317). F) server_name preregisteredcNt||i|||_d|_||_y)Nr5)super__init___hermes_server_name _hermes_home_hermes_preregistered)selfr6r7argskwargs __class__s rr:zD_make_hermes_provider_class..HermesMCPOAuthProvider.__init__s1 G d -f -'2D $ "D  *7D &r/cKt|d{|jj}|'|j|jj ||jj }ddlm}t||rd|jjN|j}|<||j_ tjd|j|j|1|jj |j!d{yyy77 #t"$r+}tjd|j|Yd}~yd}~wwxYww)uQLoad stored tokens + client info AND seed token_expiry_time. Also eagerly fetches OAuth authorization-server metadata (PRM + ASM) when we have stored tokens but no cached metadata, so the SDK's ``_refresh_token`` can build the correct token_endpoint URL on the preemptive-refresh path. Without this, the SDK falls back to ``{mcp_server_url}/token`` (wrong for providers whose AS is a different origin — BetterStack's MCP lives at ``https://mcp.betterstack.com`` but its token endpoint is at ``https://betterstack.com/oauth/token``), the refresh 404s, and we drop through to full browser reauth. The SDK's base ``_initialize`` populates ``current_tokens`` but does NOT call ``update_token_expiry``, so ``token_expiry_time`` stays ``None`` and ``is_token_valid()`` returns True for any loaded token regardless of actual age. After a process restart this ships stale Bearer tokens to the server; some providers return HTTP 401 (caught by the 401 handler), others return 200 with an app-level auth error (invisible to the transport layer, e.g. BetterStack returning "No teams found. Please check your authentication."). Seeding ``token_expiry_time`` from the reloaded token fixes that: ``is_token_valid()`` correctly reports False for expired tokens, ``async_auth_flow`` takes the ``can_refresh_token()`` branch, and the SDK quietly refreshes before the first real request. Paired with :class:`HermesTokenStorage` persisting an absolute ``expires_at`` timestamp (``mcp_oauth.py:set_tokens``) so the remaining TTL we compute here reflects real wall-clock age. NrHermesTokenStoragez?MCP OAuth '%s': restored metadata from disk (token_endpoint=%s)zDMCP OAuth '%s': pre-flight metadata discovery failed (non-fatal): %s)r9 _initializecontextcurrent_tokens expires_inupdate_token_expirystoragetools.mcp_oauthrD isinstanceoauth_metadataload_oauth_metadataloggerdebugr;token_endpoint_prefetch_oauth_metadata Exception)r>tokensrJrDmetaexcrAs rrEzG_make_hermes_provider_class..HermesMCPOAuthProvider._initializes7@'%' ' '\\00F!f&7&7&C 008ll**G :7$67LL//7224#26DLL/LL.00++ "LL//7 779998#A (H: LL100#sLEDC'E>DDDED E'!E E EEc Kddl}ddlm}m}m}m}m}|jj}|jd4d{}|d|D]|} || } |j| d{} || d{} | s8| |j_| j r't#| j d|j_n||jj$|D]} || } |j| d{} || d{\}}|sn{|s?||j_|jj(}ddlm}t/||r|j1|tjd |j|j2ndddd{y7r7G#|j$r-} tjd|j| | Yd} ~ d} ~ wwxYw7y7#|j$r-} tjd|j| | Yd} ~ Id} ~ wwxYw7!7#1d{7swYyxYww) aFetch PRM + ASM from the well-known endpoints, cache on context. Mirrors the SDK's 401-branch discovery (oauth2.py ~line 511-551) but runs synchronously before the first request instead of inside the httpx auth_flow generator. Uses the SDK's own URL builders and response handlers so we track whatever the SDK version we're pinned to expects. rN)8build_oauth_authorization_server_metadata_discovery_urls0build_protected_resource_metadata_discovery_urlscreate_oauth_metadata_requesthandle_auth_metadata_response"handle_protected_resource_responseg$@)timeoutz.MCP OAuth '%s': PRM discovery to %s failed: %sz.MCP OAuth '%s': ASM discovery to %s failed: %srCz;MCP OAuth '%s': pre-flight ASM discovered token_endpoint=%s)httpxmcp.client.auth.utilsrXrYrZr[r\rFr AsyncClientsend HTTPErrorrOrPr;protected_resource_metadataauthorization_serversrauth_server_urlrMrJrKrDrLsave_oauth_metadatarQ)r>r^rXrYrZr[r\rclienturlreqresprVprmokasmrJrDs rrRzT_make_hermes_provider_class..HermesMCPOAuthProvider._prefetch_oauth_metadatas7   00J(((65 5 &K*C8 # 9 9! <<DLL8'.TLL00*C8rUrJrDexistings r"_persist_oauth_metadata_if_changedz^_make_hermes_provider_class..HermesMCPOAuthProvider._persist_oauth_metadata_if_changed-s<<..D|ll**G :g'9:224H x../3t7J7J3KK++D1Lr/cK |jryt|dd}|dvryt|jdd}|"t|ddrt|jnd}t|dd}|t|j nd}|r|syt ||sy|jd{}tjd|jsy|jj}dd l m } t|| r|jd|j_d |_y7z#t$$r+} t&j)d |j*| Yd} ~ yd} ~ wwxYww) uDetect a dead client registration and force re-registration. When the IdP rejects our ``client_id`` with ``invalid_client`` on the token endpoint (token exchange or refresh), the cached client registration is provably dead server-side. We delete ``client.json`` (+ stale metadata) so the SDK's next ``async_auth_flow`` takes the ``if not client_info`` branch and re-runs RFC 7591 dynamic client registration. This addresses the recurring manual-reset ritual in GH#36767 for the auto-detectable subset (token-endpoint rejection); the browser-side "Redirect URI Mismatch" case has no HTTP signal and is handled by ``hermes mcp reauth``. Conservative by construction — acts ONLY when all hold: * status is 400/401, * the request hit the discovered ``token_endpoint`` (the only request carrying our ``client_id``), and * the body carries the ``invalid_client`` error code (word-boundary match, so RFC 7591's ``invalid_client_metadata`` registration error does not trip it). Pre-registered (config-supplied) clients are never poisoned. Fully best-effort: any failure here is swallowed so a detection miss never breaks the live auth flow. Covers both the authorization-code token exchange and the preemptive refresh — but only when ``token_endpoint`` was discovered (``_initialize`` prefetches it on cold-load). If that discovery was skipped, the guard returns early and the user falls back to ``hermes mcp reauth``. N status_code)iirMrQrequests\binvalid_client\brrCFz?MCP OAuth '%s': invalid_client detection failed (non-fatal): %s)r=getattrrFrrQrhrareadresearchrrJrKrDrLpoison_client_registration client_info _initializedrSrOrPr;) r>responsestatusrUrQrireq_urlbodyrJrDrVs r_maybe_flag_poisoned_clientzW_make_hermes_provider_class..HermesMCPOAuthProvider._maybe_flag_poisoned_clientBsB<$ -- =$?+t||-=tD'GD:JD,Q++, h 48*-/#cgg,t%W%g~>%^^--yy!7F,,..>g'9:668+/ ($)!.  U,,c szE D(ED(EA'D( E D(ED(+D&,(D(EAD(%E&D(( E1!EEEEcK tj|j|jd{t|!|} |jd{} |}|j|d{|j|d{}87e#t$r+}t j d|j|Yd}~d}~wwxYw7v7Y7B#t$r|jYywxYww)N hermes_homez:MCP OAuth '%s': pre-flow disk-watch failed (non-fatal): %s) get_managerinvalidate_if_disk_changedr;r<rSrOrPr9async_auth_flow __anext__rasendStopAsyncIterationrp)r>rsrVinneroutgoingincomingrAs rrzK_make_hermes_provider_class..HermesMCPOAuthProvider.async_auth_flows !m>>,, $ 1 1?0G+G4E !&!22%-~H::8DDD%*[[%::H 7  P,,c ,3 E:% 779  sC;2BBBC; CC C>C?CCCB C(!C C;CC;CCCC85C;7C88C;)r?rr6rr7boolr@rreturnNone)r{rrr) r&r'r(r)r:rErRrprr __classcell__)rAs@rHermesMCPOAuthProviderr4us_ " ""'  7 7 7  7   7"L \H T 2*B H* * r/r)mcp.client.auth.oauth2r2 ImportError)r2rs r_make_hermes_provider_classrjs7 >{!4{z "!A s  !!_HERMES_PROVIDER_CLSceZdZdZd dZ ddZe d ddZ ddZdd ddZ dd dd Z dd dd Z dd dd Z d dd Z y)MCPOAuthManageraSingle source of truth for per-server MCP OAuth state. Thread-safe: the ``_entries`` dict is guarded by ``_entries_lock`` for get-or-create semantics. Per-entry state is guarded by the entry's own ``asyncio.Lock`` (used from the MCP event loop thread). cbi|_tj|_t |_yN)_entries threadingr, _entries_lockset_inflight_tasks)r>s rr:zMCPOAuthManager.__init__s$?A &^^-36%r/c|j|}|j5|jj|}|3|j|k7r$t j d||j|d}|t||}||j|<|j7|j|||_|j|d|j_ |jcdddS#1swYyxYw)aVReturn a cached OAuth provider for ``server_name`` or build one. Idempotent: repeat calls with the same name return the same instance. If ``server_url`` changes for a given name, the cached entry is discarded and a fresh provider is built. Returns None if the MCP SDK's OAuth support is unavailable. Nz;MCP OAuth '%s': URL changed from %s to %s, discarding cache)rrr) _keyrrgetrrOinforr _build_providerr<)r>r6rrkeyentrys rget_or_build_providerz%MCPOAuthManager.get_or_build_providersii $    "MM%%c*E U%5%5%C Q!1!1:}&)!-&+ c"~~%!%!5!5k5!I>>-25a&ENN/>>+ " " "s B=C%%C.Ncddlm}| t|n|}t|j j d|fS)Nr)get_hermes_homeF)strict)hermes_constantsrrr expanduserresolve)r6rrhomes rrzMCPOAuthManager._keys@ 5$/$;tK ARDOO%--U-;r6rrDrrrrrrrrcfgrJrr resolved_portrrs rrzMCPOAuthManager._build_providers3 ' NN={   5%%+,$[1F % & .#%--/*=!>- !!  !g.05!'3@ 0!4 1-@0?##sww{34''+--#'')S12  r/rc|j5|jj|j||d}dddddlm}|||t jd|S#1swY1xYw)zEvict the provider from cache AND delete tokens from disk. Called by ``hermes mcp remove `` and (indirectly) by ``hermes mcp login `` during forced re-auth. Nr)remove_oauth_tokensrz8MCP OAuth '%s': evicted from cache and removed from disk)rrpoprrKrrOr)r>r6rrrs rremovezMCPOAuthManager.removeIso   QMM%%dii [&I4PE Q 8K[A F    Q Qs -A**A3c|y|j5|jj|j|||dddy#1swYyxYw)z>Restore a provider entry removed for a failed reauthorization.N)rr setdefaultr)r>r6rrs r restore_entryzMCPOAuthManager.restore_entry_sM =     Q MM $ $TYY{K%H% P Q Q Qs -AAc|j5|jj|j||ddddy#1swYyxYw)zDDrop only the in-process provider, preserving persisted OAuth state.N)rrrr)r>r6rs revictzMCPOAuthManager.evictlsE   I MM  dii [A4 H I I Is -AA cKddlm}m}|jj |j ||}| |j y|j4d{||||dz } |jj}||jk7rd|j}||_ t|j drd|j _tj!d||| dddd{y dddd{y7#ttf$rYdddd{7ywxYw7?7/#1d{7swYyxYww) aIf the tokens file on disk has a newer mtime than last-seen, force the MCP SDK provider to reload its in-memory state. Returns True if the cache was invalidated (mtime differed). This is the core fix for the external-refresh workflow: a cron job writes fresh tokens to disk, and on the next tool call the running MCP session picks them up without a restart. r)_get_token_dir_safe_filenameNFz.jsonrzzDMCP OAuth '%s': tokens file changed (mtime %d -> %d), forcing reloadT)rKrrrrrr r$stat st_mtime_nsFileNotFoundErrorOSErrorr"hasattrrzrOr) r>r6rrrr tokens_pathmtime_nsolds rrz*MCPOAuthManager.invalidate_if_disk_changedxsE C !!$))K"EF =ENN2::  (5>+;V:WW\8]]K &++-995...))&.#5>>>:27ENN/ %h )   *+   &w/            sAEDED:/D A"D:+ E6D67E<D:= ED8 ED3D: E+D.,E2D33D:6E8E:E E E Ec Kjjj jy|xsdt j }j 4d{jj |j j<d fd }t j|}jj||jjjdddd{ d{S77#1d{7swY!xYw7#t$r!}tj!d|Yd}~yd}~wwxYww)uxHandle a 401 from a tool call, deduplicated across concurrent callers. Returns: True if a (possibly new) access token is now available — caller should trigger a reconnect and retry the operation. False if no recovery path exists — caller should surface a ``needs_reauth`` error to the model so it stops hallucinating manual refresh attempts. Thundering-herd protection: if N concurrent tool calls hit 401 with the same ``failed_access_token``, only one recovery attempt fires. Others await the same future. NFz cK j d{}|r?jsjd jj dyj }t |dd}d}|)t |dd}t|r t|}jsj|jj dy7#t$rd}YMwxYw#t$rB}tjd |jsjdYd}~vd}~wwxYw#jj dwxYww)NTrFFcan_refresh_tokenz&MCP OAuth '%s': 401 handler failed: %s) rdone set_resultr%rr rtcallablerrSrOr) disk_changedr ctx can_refreshcan_refresh_fnrVrrpendingr>r6s r _do_handlez.MCPOAuthManager.handle_401.._do_handlesJ!9-1-L-L'.( (#*<<> ' 2 24 8"2))--c48)$)>>%h 4@&+ ?-4S:Mt-TN'7!826~7G2HK '||~#..{;))--c48?(&(1!827K!8%6D' '||~#..u5 6))--c48szE%C6C#'C6E%5C6C%%!C6E%#C6% C30C62C33C66 E?8D<7E<EEE""E%z/MCP OAuth '%s': awaiting 401 handler failed: %sr)rrrr r+get_running_loopr$r% create_future create_taskraddadd_done_callbackdiscardrSrOr) r>r6failed_access_tokenlooprtaskrVrrrs `` @@@r handle_401zMCPOAuthManager.handle_401sS$ !!$))K"89 =ENN2!0['')::, E, E''++C0G,,.)0!!#&"9"9H**:<8$$((.&&t';';'C'CDY, E, E\  = _, E, E, E, E, E^!  NNAS   sA$E3+D+,E3/B!D/ E3D-E3!E&E'E*E3-E3/E5D8 6E=E3E E0E+&E3+E00E3r)r6rrrrrrrr)r6rrstr | Path | Nonerztuple[str, str])r6rrrrr)r6rrrr_ProviderEntry | None)r6rrrrrrr)r6rrrrr)r6rrrrr)r6rrz Optional[str]rr)r&r'r(r)r:r staticmethodrrrrrrrr.r/rrrsl8$"$"$"% $"  $"L*.KK&K KKG G G   G Z*. '   6*. Q Q% Q ' Q  Q"*. II' I  I *. ))' )  )`.2NN+N  Nr/rzOptional[MCPOAuthManager]_MANAGERcft5t tatcdddS#1swYyxYw)z;Return the process-wide :class:`MCPOAuthManager` singleton.N) _MANAGER_LOCKrrr.r/rrrs-   &(Hs'0c>t5dadddy#1swYyxYw)z=Test-only helper: drop the singleton so fixtures start clean.N)rrr.r/rreset_manager_for_testsrs! s)rrrrrr)rr0)rrr)r) __future__rr+loggingrvr dataclassesrrpathlibrtypingrr getLoggerr&rOrrrrr*rrr,rrrr.r/rrsB# (   8 $2 QQ Q@H"X (C'DnDuuz '+ #*  r/