_shared.py 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332
  1. """Helpers shared by the bundled dashboard-auth providers.
  2. Each provider module keeps its own ``logger`` / ``LAST_SKIP_REASON`` (the gate reads
  3. those by module) and its ``register(ctx)``; the config/env resolution, skip/register
  4. bookkeeping, PKCE login start, token-endpoint exchange and JWT verification live here.
  5. """
  6. from __future__ import annotations
  7. import base64
  8. import hashlib
  9. import logging
  10. import math
  11. import os
  12. import secrets
  13. import urllib.parse
  14. from typing import Any, Callable, Dict, Optional
  15. import httpx
  16. from hermes_cli.dashboard_auth import (
  17. DashboardAuthProvider, InvalidCodeError, LoginStart, ProviderError, RefreshExpiredError, Session,
  18. classify_jwks_lookup_error)
  19. # JWKS Cache-Control max-age (nous contract C7); self-hosted mirrors it.
  20. JWKS_CACHE_SECONDS = 300
  21. TOKEN_ENDPOINT_TIMEOUT_SEC = 10.0
  22. JSON_HEADERS = {"Accept": "application/json"}
  23. # Clock-skew leeway (seconds) for JWT time-claim verification (RFC 7519 §4.1.4-4.1.6
  24. # allow "some small leeway, usually no more than a few minutes"). Applied symmetrically
  25. # to exp/nbf/iat by PyJWT; 60s absorbs the sub-second NTP jitter / unsynced-container
  26. # drift seen in the field (#47815) without meaningfully extending token lifetime.
  27. DEFAULT_TOKEN_LEEWAY_SECONDS = 60.0
  28. # ---- Config / env resolution ----
  29. def load_config_section(logger: logging.Logger, tag: str, *path: str) -> dict:
  30. """The ``config.yaml`` block at ``path`` as a dict, or ``{}`` — robust to load_config()
  31. raising (fresh install, malformed YAML), absent keys, or a non-dict value."""
  32. try:
  33. from hermes_cli.config import cfg_get, load_config
  34. cfg = load_config()
  35. except Exception as exc:
  36. logger.debug("%s: load_config() raised %s; falling back to env-only configuration", tag, exc)
  37. return {}
  38. section = cfg_get(cfg, *path, default=None)
  39. return section if isinstance(section, dict) else {}
  40. def resolve_env_or_cfg(env_name: str, cfg_value: Any) -> str:
  41. """Env-wins-over-config; an empty env value is treated as unset so a
  42. provisioned-but-blank secret can't shadow a valid config.yaml entry."""
  43. return os.environ.get(env_name, "").strip() or str(cfg_value or "").strip()
  44. def parse_leeway(raw: Any) -> float:
  45. """Seconds of clock-skew tolerance for JWT time claims, fail-closed.
  46. Unset → :data:`DEFAULT_TOKEN_LEEWAY_SECONDS` (60s — the zero-leeway default
  47. made any issuer-ahead clock skew fail, #47815). An explicit value must be a
  48. finite, non-negative number: unparseable / negative / NaN / inf fall back to
  49. ``0.0`` so a typo can only ever *lose* tolerance, never widen the window.
  50. ``0`` is honoured (strict pre-fix behaviour for operators who want it).
  51. """
  52. if raw is None:
  53. return DEFAULT_TOKEN_LEEWAY_SECONDS
  54. text = str(raw).strip()
  55. if not text:
  56. return DEFAULT_TOKEN_LEEWAY_SECONDS
  57. try:
  58. value = float(text)
  59. except ValueError:
  60. return 0.0
  61. if not math.isfinite(value) or value < 0:
  62. return 0.0
  63. return value
  64. # ---- register() bookkeeping ----
  65. class SkipRegistration(Exception):
  66. """Raised by a provider's settings resolver to decline registration; ``reason`` is
  67. the operator-facing text stored in the module's ``LAST_SKIP_REASON``."""
  68. def __init__(self, reason: str, level: str = "debug") -> None:
  69. super().__init__(reason)
  70. self.reason, self.level = reason, level
  71. def register_provider(
  72. ctx, logger: logging.Logger, tag: str, provider_cls: type, settings: Callable[[], dict],
  73. ) -> tuple[Optional[dict], str]:
  74. """Build ``provider_cls(**settings())`` and register it on ``ctx``.
  75. Returns ``(kwargs, "")`` on success, ``(None, skip_reason)`` when ``settings`` raised
  76. ``SkipRegistration`` (logged at its level) or construction raised ``ValueError`` /
  77. ``ProviderError`` (logged as a warning). Callers store the reason in ``LAST_SKIP_REASON``.
  78. """
  79. try:
  80. kwargs = settings()
  81. provider = provider_cls(**kwargs)
  82. except SkipRegistration as skip:
  83. getattr(logger, skip.level)("%s: %s", tag, skip.reason)
  84. return None, skip.reason
  85. except (ValueError, ProviderError) as exc:
  86. reason = f"{provider_cls.__name__} construction failed: {exc}"
  87. logger.warning("%s: %s", tag, reason)
  88. return None, reason
  89. ctx.register_dashboard_auth_provider(provider)
  90. return kwargs, ""
  91. # ---- OAuth / PKCE ----
  92. def b64url_no_pad(raw: bytes) -> str:
  93. """Base64url-encode without ``=`` padding (RFC 7636 §4)."""
  94. return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
  95. def validate_redirect_uri(redirect_uri: str) -> None:
  96. """Fast-fail obviously-broken redirect_uris before bouncing to the IDP (whose allowlist
  97. is authoritative). Any ``http://`` host is allowed so dashboards behind TLS-terminating
  98. proxies / on LAN IPs aren't rejected."""
  99. parsed = urllib.parse.urlparse(redirect_uri)
  100. if parsed.scheme not in ("https", "http"):
  101. raise ProviderError(f"redirect_uri must be http(s), got {redirect_uri!r}")
  102. if not parsed.path or not parsed.path.endswith("/auth/callback"):
  103. raise ProviderError(f"redirect_uri path must end with '/auth/callback', got {redirect_uri!r}")
  104. def pkce_login_start(authorize_url: str, *, client_id: str, scope: str, redirect_uri: str) -> LoginStart:
  105. """Build the authorization-code + PKCE (S256) redirect and cookie payload. Callers
  106. validate ``redirect_uri`` first. The auth-route layer expects
  107. ``cookie_payload["hermes_session_pkce"]`` as a flat ``state=…;verifier=…`` string
  108. (it prepends ``provider=``)."""
  109. code_verifier = b64url_no_pad(secrets.token_bytes(64)) # ~86 chars
  110. state = b64url_no_pad(secrets.token_bytes(32))
  111. params = {
  112. "response_type": "code", "client_id": client_id, "redirect_uri": redirect_uri, "scope": scope, "state": state,
  113. "code_challenge": b64url_no_pad(hashlib.sha256(code_verifier.encode("ascii")).digest()),
  114. "code_challenge_method": "S256"}
  115. return LoginStart(
  116. redirect_url=f"{authorize_url}?{urllib.parse.urlencode(params)}",
  117. cookie_payload={"hermes_session_pkce": f"state={state};verifier={code_verifier}"})
  118. def parse_json_body(response: httpx.Response) -> dict[str, Any]:
  119. """JSON object body, or ``{}`` for non-JSON content-type / parse error / non-dict."""
  120. if not response.headers.get("content-type", "").startswith("application/json"):
  121. return {}
  122. try:
  123. body = response.json()
  124. except ValueError:
  125. return {}
  126. return body if isinstance(body, dict) else {}
  127. def exchange_token(
  128. url: str, data: dict[str, str], *, headers: Optional[dict[str, str]] = None, bad_request_exc: type[Exception],
  129. idp: str, endpoint: str, token_key: str, missing_msg: str) -> tuple[str, dict[str, Any]]:
  130. """POST a token grant and return ``(token, payload)``.
  131. A 400 (OAuth-shaped error envelope) raises ``bad_request_exc`` — ``InvalidCodeError``
  132. for the auth-code path, ``RefreshExpiredError`` for refresh — so the middleware's
  133. distinct handling is preserved. Any other non-200, transport failure, missing
  134. ``token_key`` or non-bearer ``token_type`` raises ``ProviderError``. Redirects are
  135. deliberately NOT followed: the body carries an auth code / refresh token.
  136. """
  137. try:
  138. response = httpx.post(url, data=data, headers={**JSON_HEADERS, **(headers or {})}, timeout=TOKEN_ENDPOINT_TIMEOUT_SEC)
  139. except httpx.RequestError as exc:
  140. raise ProviderError(f"{endpoint} unreachable: {exc}") from exc
  141. if response.status_code == 400:
  142. error_code = parse_json_body(response).get("error", "invalid_request")
  143. raise bad_request_exc(f"{idp} rejected token request: {error_code}")
  144. if response.status_code != 200:
  145. raise ProviderError(f"{endpoint} returned {response.status_code}: {response.text[:200]!r}")
  146. payload = parse_json_body(response)
  147. token = payload.get(token_key)
  148. if not token or not isinstance(token, str):
  149. raise ProviderError(missing_msg)
  150. token_type = str(payload.get("token_type", "")).lower()
  151. if token_type and token_type != "bearer":
  152. raise ProviderError(f"unexpected token_type={token_type!r}")
  153. return token, payload
  154. def refresh_token_from(payload: dict[str, Any], fallback: str = "") -> str:
  155. """The token response's refresh token, or ``fallback`` when absent/non-string
  156. (the session then behaves as access-token-only until expiry)."""
  157. rt = payload.get("refresh_token")
  158. return rt if isinstance(rt, str) and rt else fallback
  159. def session_from_claims(
  160. provider: str, claims: dict[str, Any], *, access_token: str, refresh_token: str,
  161. label: str = "token", email: str = "", display_name: str = "", org_id: str = "") -> Session:
  162. """Map verified JWT claims onto a Session; ``sub`` is mandatory."""
  163. user_id = str(claims.get("sub", ""))
  164. if not user_id:
  165. raise ProviderError(f"{label} missing 'sub' (user_id) claim")
  166. return Session(
  167. user_id=user_id, email=email, display_name=display_name, org_id=org_id, provider=provider,
  168. expires_at=int(claims["exp"]), access_token=access_token, refresh_token=refresh_token,
  169. issuer=str(claims.get("iss") or ""))
  170. # ---- JWT verification ----
  171. def make_jwks_client(jwks_url: str) -> Any:
  172. """PyJWKClient with explicit Accept/User-Agent (some WAFs block the library default).
  173. Imported lazily so plugin discovery stays cheap."""
  174. from jwt import PyJWKClient
  175. return PyJWKClient(
  176. jwks_url, cache_keys=True, lifespan=JWKS_CACHE_SECONDS,
  177. headers={"Accept": "application/json", "User-Agent": "HermesAgent/1.0"})
  178. def verify_jwt(
  179. token: str, jwks_client: Any, *, algorithms: list[str], audience: str, issuer: str, label: str,
  180. leeway: float = DEFAULT_TOKEN_LEEWAY_SECONDS,
  181. ) -> dict[str, Any]:
  182. """Verify ``token`` against ``jwks_client`` with pinned ``aud``/``iss``.
  183. ``leeway`` is seconds of clock-skew tolerance on the time claims (default
  184. 60 — the previous zero-leeway made any issuer-ahead skew fail login, #47815).
  185. Unreachable JWKS → ``ProviderError`` (503); a bearer that is not one of our JWTs
  186. (opaque peer key, foreign kid) → ``InvalidCodeError`` (None / next provider); folding
  187. both into 503 broke peer-key bearers. Expiry and not-yet-valid (``iat``/``nbf`` in
  188. the future beyond the leeway — a *token* failure, not a transport failure) raise
  189. ``InvalidCodeError`` (verify_session maps it to None); any other claim failure raises
  190. ``ProviderError`` with the unverified iss/aud appended so operators can spot config
  191. drift.
  192. """
  193. import jwt # lazy — keeps startup fast for the ungated path
  194. try:
  195. signing_key = jwks_client.get_signing_key_from_jwt(token)
  196. except Exception as exc:
  197. # Unreachable JWKS -> ProviderError (503); a bearer that is not one of our JWTs (opaque peer key,
  198. # foreign kid) -> InvalidCodeError (None / next provider). Folding both into 503 produced #94558.
  199. raise classify_jwks_lookup_error(exc) from exc
  200. try:
  201. return jwt.decode(
  202. token, signing_key.key, algorithms=algorithms, audience=audience, issuer=issuer, leeway=leeway,
  203. options={"require": ["exp", "iat", "aud", "iss", "sub"]})
  204. except jwt.ExpiredSignatureError as exc:
  205. raise InvalidCodeError(f"{label} expired: {exc}") from exc
  206. except jwt.InvalidSignatureError as exc:
  207. # A forged/tampered bearer is "not my token", never an IDP outage: a 503 here would let a
  208. # remote caller with garbage credentials look like a provider incident (and keep cookies).
  209. raise InvalidCodeError(f"{label} signature invalid: {exc}") from exc
  210. except jwt.ImmatureSignatureError as exc:
  211. # iat/nbf ahead of now beyond the leeway = clock skew or a bad token — the
  212. # provider is *reachable*, so this must NOT surface as ProviderError/503
  213. # (which discarded rotated refresh tokens and forced re-login, #47815).
  214. raise InvalidCodeError(f"{label} not yet valid: {exc}") from exc
  215. except jwt.InvalidTokenError as exc:
  216. # Decoding without verification is safe here: verification already failed and
  217. # these values are surfaced for diagnostics only, never trusted.
  218. details = ""
  219. try:
  220. unverified = jwt.decode(token, options={"verify_signature": False, "verify_exp": False})
  221. details = (
  222. f" [token iss={unverified.get('iss')!r} aud={unverified.get('aud')!r}; "
  223. f"expected iss={issuer!r} aud={audience!r}]")
  224. except Exception:
  225. pass
  226. raise ProviderError(f"{label} verification failed: {exc}{details}") from exc
  227. # ---- Shared provider skeletons ----
  228. class NonInteractiveMixin:
  229. """OAuth-redirect stubs for providers without a browser login flow (password / service
  230. credential). ``_NOT_INTERACTIVE`` is the operator-facing reason; ``_NO_START_LOGIN``
  231. optionally overrides the ``start_login`` message."""
  232. _NOT_INTERACTIVE: str = ""
  233. _NO_START_LOGIN: str = ""
  234. def start_login(self, *, redirect_uri: str) -> LoginStart:
  235. raise NotImplementedError(self._NO_START_LOGIN or self._NOT_INTERACTIVE)
  236. def complete_login(self, *, code: str, state: str, code_verifier: str, redirect_uri: str) -> Session:
  237. raise NotImplementedError(self._NOT_INTERACTIVE)
  238. class JwtOAuthProvider(DashboardAuthProvider):
  239. """Authorization-code + PKCE provider whose session token is a JWT we verify ourselves
  240. (nous: Portal access token; self-hosted: OIDC ID token). Subclasses set ``_client_id`` and
  241. implement: ``_jwks_uri() -> str``; ``_claims_for(token) -> claims`` (raises
  242. ``InvalidCodeError`` on expiry/foreign token, ``ProviderError`` otherwise);
  243. ``_grant(data, *, bad_request_exc, headers=None, previous_refresh_token="") -> Session``;
  244. ``_refresh_request(refresh_token) -> (form_data, extra_headers)``;
  245. ``_session(token, refresh_token, claims) -> Session``."""
  246. _jwks_client: Any = None
  247. _client_id: str = ""
  248. def _get_jwks_client(self) -> Any:
  249. if self._jwks_client is None:
  250. self._jwks_client = make_jwks_client(self._jwks_uri())
  251. return self._jwks_client
  252. def complete_login(self, *, code: str, state: str, code_verifier: str, redirect_uri: str) -> Session:
  253. # ``state`` is verified by the auth-route layer before this call.
  254. return self._grant(
  255. {"grant_type": "authorization_code", "code": code, "redirect_uri": redirect_uri,
  256. "client_id": self._client_id, "code_verifier": code_verifier},
  257. bad_request_exc=InvalidCodeError)
  258. def refresh_session(self, *, refresh_token: str) -> Session:
  259. if not refresh_token:
  260. raise RefreshExpiredError("no refresh token present in session")
  261. data, headers = self._refresh_request(refresh_token)
  262. return self._grant(
  263. data, headers=headers, bad_request_exc=RefreshExpiredError, previous_refresh_token=refresh_token)
  264. def verify_session(self, *, access_token: str) -> Optional[Session]:
  265. # None on expiry/invalidity (middleware then tries refresh); a ProviderError
  266. # (JWKS unreachable) bubbles up so middleware emits 503.
  267. try:
  268. claims = self._claims_for(access_token)
  269. except InvalidCodeError:
  270. return None
  271. return self._session(access_token, "", claims)