(Gj4&UdZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl Z ddl m Z mZmZddlZddlmZmZmZmZmZmZejeZdZdZdZdZd Zd Z d a!d e"d <d!dZ#d"dZ$GddeZ%d#dZ&d$dZ'd%dZ(d&d Z)dS)'unSelfHostedOIDCProvider — generic self-hosted OpenID Connect dashboard auth. A standards-compliant OpenID Connect Relying Party for the ``hermes dashboard`` OAuth gate. Unlike the bundled ``nous`` provider (which encodes Nous Portal's bespoke contract — ``agent:{instance_id}`` client ids, a custom access-token JWT, the ``x-nous-refresh-token`` header, an ``oauth_contract_version`` claim), this provider speaks **plain OIDC** so it works against any conformant self-hosted identity provider: Authentik · Keycloak · Zitadel · Authelia · Auth0 · Okta · Google · … It is a pure drop-in plugin: it implements the five :class:`~hermes_cli.dashboard_auth.DashboardAuthProvider` methods and touches nothing in core auth/runtime/login. The HTTP round trip, cookies, CSRF ``state`` check and ``redirect_uri`` reconstruction are all owned by ``hermes_cli/dashboard_auth/routes.py``; this provider only: 1. discovers the IDP's endpoints from ``{issuer}/.well-known/openid-configuration``, 2. builds the ``/authorize`` URL with PKCE (S256), 3. exchanges the authorization code for tokens at the discovered ``token_endpoint``, 4. verifies the **ID token** (RS256/ES256) against the discovered ``jwks_uri`` with ``iss`` / ``aud`` pinned to the configured issuer / client id, and maps standard OIDC claims (``sub``, ``email``, ``name``) onto a :class:`~hermes_cli.dashboard_auth.Session`. Why the ID token (not the access token)? OIDC guarantees the ID token is a signed JWT carrying identity claims — that is its entire purpose. The access token's format is opaque to the client per the spec; many IDPs issue random opaque strings the client cannot verify locally. Verifying the ID token is the only choice that is universally correct across self-hosted IDPs. (The ``nous`` provider verifies its *access* token because Nous Portal mints a custom JWT access token with the dashboard claims baked in — a non-OIDC shortcut.) Both **public** (PKCE-only) and **confidential** (PKCE + ``client_secret``) clients are supported. A self-hoster who registers a public client configures no secret and the token-endpoint calls authenticate with PKCE alone (the default). A self-hoster whose IDP defaults the client to *confidential* (Authentik and Keycloak commonly do) sets ``client_secret`` and the provider additionally authenticates the client at the token endpoint, choosing ``client_secret_basic`` (HTTP Basic header) or ``client_secret_post`` (secret in the form body) from the IDP's advertised ``token_endpoint_auth_methods_supported``. PKCE is sent in **both** modes — the secret is client authentication layered on top, never a replacement for PKCE (OAuth 2.1 / RFC 9700 keep PKCE mandatory regardless). Configuration surfaces (env wins over config.yaml when set non-empty, so a provisioned-but-not-populated secret can't shadow a valid config.yaml entry — same precedence convention as the ``nous`` plugin):: # config.yaml — canonical surface dashboard: oauth: provider: self-hosted self_hosted: issuer: https://auth.example.com/application/o/hermes/ # required client_id: hermes-dashboard # required scopes: "openid profile email" # optional # client_secret: set ONLY for a confidential client. It is a # credential — prefer the env var / ~/.hermes/.env over config.yaml. # Environment overrides (Docker/Fly secret injection) HERMES_DASHBOARD_OIDC_ISSUER HERMES_DASHBOARD_OIDC_CLIENT_ID HERMES_DASHBOARD_OIDC_SCOPES # optional; defaults to "openid profile email" HERMES_DASHBOARD_OIDC_CLIENT_SECRET # optional; set for a confidential client # (the .env file is the canonical home — # it's a secret, not a behavioural setting) Skip reasons: when the plugin loads but can't register (missing issuer / client_id), it writes a human-readable reason to the module-level :data:`LAST_SKIP_REASON` so the gate's fail-closed branch can surface a useful operator error instead of the bare "no providers registered". ) annotationsN)AnyDictOptional)DashboardAuthProviderInvalidCodeError LoginStart ProviderErrorRefreshExpiredErrorSessionzopenid profile email)RS256ES256RS384RS512ES384ES512g$@ii,strLAST_SKIP_REASONrawbytesreturncttj|dS)u6Base64url-encode without ``=`` padding (RFC 7636 §4).=)base64urlsafe_b64encoderstripdecode)rs Q/home/rurouni/.hermes/hermes-agent/plugins/dashboard_auth/self_hosted/__init__.py_b64url_no_padr s-  #C ( ( / / 5 5 < < > >>urlfieldctj|}|jdkr|S|jdkr |jpddvr|St d|d|)a{Reject an endpoint URL that isn't HTTPS (loopback http is allowed). OAuth credentials (codes, tokens) flow over these URLs. We require HTTPS for everything except an explicit loopback host so a misconfigured issuer can't ship the authorization code / refresh token in cleartext. Returns the URL unchanged on success; raises :class:`ProviderError` otherwise. httpshttpr) localhostz 127.0.0.1z::1zOIDC z. must be https:// (or http on localhost), got )urllibparseurlparseschemehostnamer )r"r#parseds r_require_https_or_loopbackr.s|\ " "3 ' 'F }  }FO$9r?$$  LLLSLL  r!ceZdZdZdZdZeddd8d Zd9dZd:dZ d;dZ ddZ dd d!d?d*Zd@d+ZdAd,Zd@d-ZdBd/ZdCd1ZdDd3ZdEd4ZdFd7Zd S)GSelfHostedOIDCProviderzHGeneric self-hosted OpenID Connect provider (authorization-code + PKCE).z self-hostedzSelf-Hosted OIDCr)scopes client_secretissuerr client_idr1r2rNonec|std|std|d|_t|jd||_|pt |_|pd|_d|_ d|_ tj |_ d|_dS)Nzissuer is requiredzclient_id is required/r3r#rg) ValueErrorr_issuerr. _client_idstrip_DEFAULT_SCOPES_scopes_client_secret _discovery_discovery_fetched_at threadingLock_discovery_lock _jwks_client)selfr3r4r1r2s r__init__zSelfHostedOIDCProvider.__init__s 3122 2 6455 5 }}S)) "4r(r) urlencoder ) rFrHdisco code_verifierrRrQparamsrWrXs r start_loginz"SelfHostedOIDCProvider.start_logins ##L111##%%&w':2'>'>?? ' N=//88 9 9 @ @ B B  w226677$(\,%+  -. Q Q1G1G1O1O Q Q  "#LE#L#L]#L#L |NSSSSr!rMrQrcr c|}|}d|||j|d}||\}} ||||d|t | S)Nauthorization_code) grant_typerMrHr4rctoken_endpoint)bad_request_exc extra_headers)rZr;_token_endpoint_authupdate _exchanger) rFrMrQrcrH_rbdata extra_datarks rcomplete_loginz%SelfHostedOIDCProvider.complete_logins ##%%/(*   %)$=$=e$D$D! M J~~ " # ,'    r! refresh_tokenc|std|}d|j||jd}||\}}||||d|t||S)Nz#no refresh token present in sessionrs)rhr4rsrPri)rjprevious_refresh_tokenrk)r rZr;r>rlrmrn)rFrsrbrprqrks rrefresh_sessionz&SelfHostedOIDCProvider.refresh_sessions M%&KLL L##%%**\   %)$=$=e$D$D! M J~~ " # /#0'    r! access_tokenOptional[Session]c ||}n#t$rYdSt$rwxYw||d|S)Nrid_tokenrsclaims)_verify_id_tokenrr _session_from_tokens)rFrwr|s rverify_sessionz%SelfHostedOIDCProvider.verify_session.sy  **<88FF   44     ((!F)   s  0 0c|sdS |}n#t$rYdSwxYwt|dpd}|sdS|d|jd}ddi}||\}}|||| tj |||tn2#t$r%}t d|Yd}~nd}~wwxYwdS) Nrevocation_endpointrrs)tokentoken_type_hintr4Acceptapplication/jsonrpheaderstimeoutz-self-hosted OIDC: revoke failed (ignored): %s)rZr rgetr<r;rlrmhttpxpost_TOKEN_ENDPOINT_TIMEOUT_SEC Exceptionloggerdebug) rFrsrbendpointrprrqrkexcs rrevoke_sessionz%SelfHostedOIDCProvider.revoke_sessionAsc 4 ''))EE   44 uyy!677=2>>DDFF 4".   /0%)$=$=e$D$D! M J}%%% O J3        O O O LLH# N N N N N N N N Ots$ ))8C D DDrbDict[str, Any]%tuple[Dict[str, str], Dict[str, str]]c|jsiifS|dpg}d|vod|v}|r d|jiifStj|jddtj|jd}t j|d d }id d |ifS) uaReturn ``(extra_data, extra_headers)`` for token-endpoint client auth. Public client (no ``client_secret`` configured): returns ``({}, {})`` — the exchange authenticates with PKCE alone, exactly as before this method existed. Confidential client (``client_secret`` set): authenticates the client per RFC 6749 §2.3.1, choosing the method from the IDP's advertised ``token_endpoint_auth_methods_supported``: * ``client_secret_post`` advertised (and ``client_secret_basic`` not) → secret in the form body. * otherwise → HTTP Basic ``Authorization`` header (the OIDC default; also the fallback when the IDP advertises nothing). PKCE's ``code_verifier`` is sent regardless by the callers — the secret is layered on top, never a replacement. %token_endpoint_auth_methods_supportedclient_secret_postclient_secret_basicr2r)safe:zutf-8rK AuthorizationzBasic ) r?rr(r)quoter;r b64encoder_r)rFrbmethods prefer_postuserpassencodeds rrlz+SelfHostedOIDCProvider._token_endpoint_authfs*" r6M))CDDJ G + 5%W4   >#T%892= =|!!$/!;; B B|!!$"5B!?? B B "8??7#;#;<<CCGLLO%7g%7%7888r!N)rurkrirpDict[str, str]rjtype[Exception]rurkOptional[Dict[str, str]]cddi}|r|| tj|||t}n*#tj$r}t d||d}~wwxYw|jdkr9||} | dd} |d | |jd kr't d |jd |j dd ||} | d } | rt| tst dt| dd } | r| dkrt d| | | }| d}t|tr|s|pd}|| ||S)uPOST the token endpoint and turn the response into a Session. Shared by ``complete_login`` (auth-code grant) and ``refresh_session`` (refresh grant). ``bad_request_exc`` is raised on a 400 — ``InvalidCodeError`` for the auth-code path, ``RefreshExpiredError`` for the refresh path — preserving the middleware's distinct handling. ``extra_headers`` carries the confidential-client ``Authorization`` header when one applies (see ``_token_endpoint_auth``); it is empty for a public client, so the request is byte-identical to the pre- confidential-client behaviour in that case. rrrz!OIDC token endpoint unreachable: Nierrorinvalid_requestzIDP rejected token request: zOIDC token endpoint returned z: r{uOIDC token response missing id_token — ensure the 'openid' scope is configured and the client is allowed to receive an ID token. token_typerbearerzunexpected token_type=rsrz)rmrrr RequestErrorr status_code_parse_json_bodyrtext isinstancerlowerr}r~)rFrirprjrurkrresponserbody error_codepayloadr{rr|rss rrnz SelfHostedOIDCProvider._exchangesP*/0  * NN= ) ) ) z3 HH !   9C99    3 & &((22D'+<==J!/;z;;   3 & &+0D++=#&++  ''11;;z** z(C88   \26677==??  I*00 G G GHH H&&x00  O44 --- 9] 928bM((]6)   s;A" AA"ctj}|j||jz tkr|jS|j5tj}|j&||jz tkr|jcdddS|}||_||_d|_|cdddS#1swxYwYdS)z=Return the cached OIDC discovery document, fetching if stale.N)timer@rA_DISCOVERY_CACHE_TTL_SECrD_fetch_discoveryrE)rFnowrbs rrZz%SelfHostedOIDCProvider._get_discoverys!ikk O 't115MMM? "  !  )++C+4559QQQ        ))++E#DO),D &!%D                   s4B4=*B44B8;B8c|jdS)Nz!/.well-known/openid-configuration)r:)rFs r_discovery_urlz%SelfHostedOIDCProvider._discovery_urls,AAAAr!c|} tj|dditd}n*#tj$r}t d||d}~wwxYw|jdkrt d|jd|||}|st d t|d d pd  }t|d d pd  }t|d d pd  }|r|r|st dt|dd pd  }|r8| d|j krt d|d|j t|d t|d t|d t|dd pd  } |d} t| tr d| Dng} |p|j |||| | dS)NrrT)rrfollow_redirectszOIDC discovery unreachable: rzOIDC discovery returned z for z'OIDC discovery returned a non-JSON bodyrTrrijwks_urizPOIDC discovery missing one of authorization_endpoint / token_endpoint / jwks_urir3r7z4OIDC discovery issuer mismatch: document advertises z but configured issuer is r8rrc,g|]}t|Sr).0ms r z;SelfHostedOIDCProvider._fetch_discovery..Cs . . .SVV . . .r!)r3rTrirrr)rrr_DISCOVERY_TIMEOUT_SECrr rrrr<rr:r.rlist) rFr"rrrrTriradvertised_issuerrauth_methods_rawtoken_endpoint_auth_methodss rrz'SelfHostedOIDCProvider._fetch_discoverys!!## O y!#56.!% HH ! O O O Ds D DEE3 N O  3 & &M8+?MMcMM ''11 K IJJ J!$ KK0" 5 5 ;" " %'' W[[)92>>D"EEKKMMw{{:r228b99??AA% ^ 8 ,   Hb 9 9 ?R@@FFHH  !2!9!9#!>!>$,!N!N$$$$<$$  # "*B     #>9IJJJJ"8:>>>>! KK-r 2 2 8b  %'' #;;'NOO*D11  . .- . . . . $(74<&<, #65P    s6AAArc|j8ddlm}|}||ddt|_|jS)Nr) PyJWKClientrT) cache_keyslifespan)rEjwtrrZ_JWKS_CACHE_SECONDS)rFrrbs r_get_jwks_clientz'SelfHostedOIDCProvider._get_jwks_clientSs`   $ ' ' ' ' ' '''))E + j!,!!!D    r!r{c ddl}|} ||}nE#|j$r}t d||d}~wt $r}t d||d}~wwxYw |||jtt|j |ddgdi}n#|j $r}td||d}~w|j$r}d} ||d d d  }d |d d|dd|dd|j d }n#t $rYnwxYwt d|||d}~wwxYw|S)NrzJWKS lookup failed: r3require)expiataudisssub) algorithmsaudiencer3optionszID token expired: rF)verify_signature verify_exp)rz [token iss=rz aud=rz; expected iss=]zID token verification failed: )rrZrget_signing_key_from_jwtPyJWKClientErrorr rrkeyr_ALLOWED_ID_TOKEN_ALGSr;ExpiredSignatureErrorrInvalidTokenErrorr) rFr{rrb signing_keyrr|details unverifieds rr}z'SelfHostedOIDCProvider._verify_id_token_sF ##%% I//11JJKK# G G G s > >??S H I! ZZ 677X"$G$G$GH  FF( H H H"#=#=#=>>C G$    G  ZZ16eLL( 0:>>%#8#800%>>%0000$)(O00 ?000     ??g?? ' . sm'A B A B,A??BAC E<C'' E<4E77AEE7 EE7EE77E<r|c t|dd}|stdt|ddpd}t|dp-|dp|dp|pd}|dp|d pd}|sK|d }t|tr!|rd d |D}t|pd}t |||||jt|d ||S)u\Map verified OIDC claims onto a Session. The verified ID token is stored in ``Session.access_token`` so the per-request ``verify_session`` re-verifies a real JWT. The opaque OAuth access token is intentionally NOT stored — Hermes does not call any resource API with it; the dashboard only needs identity. rrz&ID token missing 'sub' (user_id) claimemailnamepreferred_usernamenicknameorg_id organizationgroups,c34K|]}t|VdS)Nr)rgs r z>SelfHostedOIDCProvider._session_from_tokens..s(!9!9Q#a&&!9!9!9!9!9!9r!r)user_idr display_namerprovider expires_atrwrs) rrr rrjoinr rint) rFr{rsr|rrrrrs rr~z+SelfHostedOIDCProvider._session_from_tokenss{fjj++,, J HII IFJJw++1r22 JJv   zz.// zz*%%     H%%IN)C)CIr :ZZ))F&$'' :F :!9!9&!9!9!999V\r""%Y6%=))!'    r!ctj|}|jdvrt d||jr|jdst d|dS)uFast-fail obviously-broken redirect_uris before bouncing to the IDP. The IDP's own allowlist is authoritative; this just catches the common operator-error case with a clear message. We allow any ``http://`` host (not just localhost) so self-hosted dashboards reached over plain HTTP — LAN IPs, internal hostnames, reverse proxies that terminate TLS upstream — are not rejected here; the IDP makes the final call on which redirect_uris are permitted. Mirrors the nous provider. )r%r&z"redirect_uri must be http(s), got z/auth/callbackz6redirect_uri path must end with '/auth/callback', got N)r(r)r*r+r pathendswith)rFrHr-s rrYz-SelfHostedOIDCProvider._validate_redirect_uris&&|44 = 1 1 1E\EE { &+"6"67G"H"H (#((   r!rhttpx.Responsec|jdd}|dsiS |}n#t$ricYSwxYwt |t r|niS)Nz content-typerr)rr startswithjsonr9rdict)rFrctypers rrz'SelfHostedOIDCProvider._parse_json_bodys $$^R88 233 I ==??DD   III !$--5tt25sA AA) r3rr4rr1rr2rrr5)rHrrr ) rMrrQrrcrrHrrr )rsrrr )rwrrrx)rsrrr5)rbrrr) rirrprrjrrurrkrrr )rr)rr)rr)r{rrr)r{rrsrr|rrr )rHrrr5)rrrr)__name__ __module__ __qualname____doc__rrr=rGrerrrvrrrlrnrZrrrr}r~rYrrr!rr0r0sRR D%L& & & & & & &HTTTT:    >    4    &!!!!J*9*9*9*9d')26I I I I I I Z.BBBBU U U U r ! ! ! !1111j. . . . `*666666r!r0rc ddlm}m}|}n4#t$r'}td|icYd}~Sd}~wwxYw||ddd}t |tr|niS)uReturn the ``dashboard.oauth`` block from config.yaml, or ``{}``. Robust to load_config() raising, the ``dashboard`` key being absent or non-dict, and ``oauth`` being present but not a dict — each falls through to ``{}`` so callers can rely on ``.get(...)``. r)cfg_get load_configz[dashboard-auth-self-hosted: load_config() raised %s; falling back to env-only configurationN dashboardoauth)default)hermes_cli.configrrrrrrr)rrcfgrsections r_load_config_oauth_sectionrs ::::::::kmm   5     gc;>>>G $// 777R7s AAAA oauth_sectionc^|d}t|tr|niS)z@Return the ``dashboard.oauth.self_hosted`` sub-block, or ``{}``. self_hosted)rrr)rrs r_oidc_subsectionrs.   M * *CS$'' /33R/r!env_var cfg_valuerctj|d}|r|St |pdS)zenv-wins-config with empty-is-unset precedence. 1. ``env_var`` when non-empty after strip (an empty provisioned secret must not shadow a valid config.yaml entry). 2. ``cfg_value`` from config.yaml. 3. Empty string. r)osenvironrr<r)rrenvs r_resolve_settingrsP *.." % % + + - -C  yB   % % ' ''r!r5c .dat}t|}td|d}td|d}td|dpt }td|d }|r|sEd t |d t |d atd tdS t||||}nD#ttf$r0}d|at d tYd}~dSd}~wwxYw| |td|||t |dS)uPlugin entry — called by the plugin loader at startup. Registers :class:`SelfHostedOIDCProvider` only when both an issuer and a client_id are configured (via ``HERMES_DASHBOARD_OIDC_*`` env vars or the ``dashboard.oauth.self_hosted`` block in config.yaml). Operator-owned loopback / ``--insecure`` dashboards leave these unset, so the plugin is a no-op for them. On skip, writes a reason to :data:`LAST_SKIP_REASON` that names BOTH configuration surfaces so operators don't guess wrong about which to set. rHERMES_DASHBOARD_OIDC_ISSUERr3HERMES_DASHBOARD_OIDC_CLIENT_IDr4HERMES_DASHBOARD_OIDC_SCOPESr1#HERMES_DASHBOARD_OIDC_CLIENT_SECRETr2u:Self-hosted OIDC dashboard auth is not configured. Set both an issuer and a client_id — either as env vars (HERMES_DASHBOARD_OIDC_ISSUER + HERMES_DASHBOARD_OIDC_CLIENT_ID) or under dashboard.oauth.self_hosted.{issuer,client_id} in config.yaml — or pass --insecure to skip the OAuth gate entirely. (issuer set: z; client_id set: )zdashboard-auth-self-hosted: %sN)r3r4r1r2z,SelfHostedOIDCProvider construction failed: zedashboard-auth-self-hosted: registered provider (issuer=%s, client_id=%s, scopes=%r, confidential=%s))rrrrrr=boolrrr0r9r warning register_dashboard_auth_providerinfo) ctxroidc_cfgr3r4r1r2rrs rregisterr's.00M ..H & X(>(>F!)8<< +D+DI 7h9O9OPP   %-x||O/L/LM   F||||T)____  .   57GHHH )'      & @3 @ @  79IJJJ ((222 KK @ ]s=DE"%E  E)rrrr)r"rr#rrr)rr)rrrr)rrrrrr)rr5)*r __future__rrr]loggingrr[rBr urllib.parser(typingrrrrhermes_cli.dashboard_authrrr r r r getLoggerrrr=rrrrrr__annotations__r r.r0rrrr'rr!rr/sIIIV#"""""   &&&&&&&&&&   8 $ $) P"  ???? 6s6s6s6s6s62s6s6s6v8888,0000 ( ( ( (GGGGGGr!