auth_device_flow.py 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474
  1. """Shared device-code / loopback-PKCE / browser / TLS helpers for interactive OAuth logins.
  2. Split out of ``hermes_cli/auth.py`` and re-exported there; origin helpers are imported lazily
  3. inside each function so ``hermes_cli.auth.<name>`` patches still intercept (and no import cycle).
  4. """
  5. from __future__ import annotations
  6. import base64
  7. import hashlib
  8. import logging
  9. import os
  10. import ssl
  11. import sys
  12. import threading
  13. import time
  14. import webbrowser
  15. from http.server import BaseHTTPRequestHandler, HTTPServer
  16. from pathlib import Path
  17. from typing import Any, Callable, Dict, FrozenSet, Optional
  18. from urllib.parse import parse_qs, urlparse
  19. from hermes_cli.auth_constants import (
  20. AuthError, DEFAULT_NOUS_PORTAL_URL, DEVICE_AUTH_POLL_INTERVAL_CAP_SECONDS,
  21. DEVICE_CODE_GRANT_TYPE, OAUTH_OVER_SSH_DOCS_URL, httpx)
  22. from hermes_cli.auth_error_copy import DeviceCodeExpired
  23. from utils import is_truthy_value
  24. # Log-record parity with the origin module (caplog tests pin "hermes_cli.auth").
  25. logger = logging.getLogger("hermes_cli.auth")
  26. # Console/text-mode browsers that ``webbrowser`` will launch INSIDE the terminal, hijacking the
  27. # user's TTY with an unusable text browser. When the resolved browser is one of these we refuse
  28. # to auto-open and fall back to the print-the-URL path, same as a remote session.
  29. _CONSOLE_BROWSER_NAMES: frozenset[str] = frozenset({
  30. "w3m", "lynx", "links", "links2", "elinks", "www-browser",
  31. "browsh", # TUI browser — still hijacks the terminal
  32. })
  33. # Browser-only remote IDEs / cloud shells (they don't set SSH_CLIENT / SSH_TTY). Keep this list
  34. # narrow — well-known env vars set by the host platform — so a local shell never trips it.
  35. _REMOTE_IDE_ENV_VARS = (
  36. "CLOUD_SHELL", # GCP Cloud Shell
  37. "CODESPACES", "CODESPACE_NAME", # GitHub Codespaces
  38. "GITPOD_WORKSPACE_ID", # Gitpod
  39. "REPL_ID", # Replit
  40. "STACKBLITZ", # StackBlitz
  41. )
  42. def _is_remote_session() -> bool:
  43. """Detect environments where loopback OAuth can't reach the local browser.
  44. Historically only SSH was checked, but #26923 surfaced that **browser-only remote consoles** (GCP Cloud
  45. Shell, GitHub Codespaces, AWS EC2 Instance Connect, Gitpod, Replit, etc.) hit the exact same problem —
  46. the user has a browser on their laptop but the loopback listener is bound on the remote VM that the
  47. laptop's browser can't reach. These environments typically don't set ``SSH_CLIENT`` / ``SSH_TTY``, so
  48. the SSH-only check left them with no guidance and no fallback.
  49. """
  50. return bool(
  51. os.getenv("SSH_CLIENT") or os.getenv("SSH_TTY")
  52. or any(os.getenv(var) for var in _REMOTE_IDE_ENV_VARS))
  53. def _names_console_browser(value: str) -> bool:
  54. token = value.strip().split()[0] if value.strip() else ""
  55. return os.path.basename(token).lower() in _CONSOLE_BROWSER_NAMES
  56. def _can_open_graphical_browser() -> bool:
  57. """Return True only when a *graphical* browser is likely to open.
  58. On a headless Linux box ``webbrowser.open()`` often resolves to a text-mode browser that takes
  59. over the terminal. Heuristics: a ``$BROWSER`` naming a console browser refuses; on Linux a
  60. display server (``$DISPLAY`` / ``$WAYLAND_DISPLAY``) is required unless ``$BROWSER`` is set
  61. (a console one already returned False, so a set ``$BROWSER`` here is graphical).
  62. """
  63. browser_env = os.environ.get("BROWSER", "")
  64. if browser_env and _names_console_browser(browser_env):
  65. return False
  66. if sys.platform.startswith("linux"):
  67. has_display = bool(os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"))
  68. if not has_display and not browser_env:
  69. return False
  70. try:
  71. controller = webbrowser.get()
  72. except Exception:
  73. return False # No browser resolvable at all → definitely don't auto-open.
  74. candidate = getattr(controller, "name", "") or getattr(controller, "basename", "") or ""
  75. return not (candidate and _names_console_browser(candidate))
  76. def _ssh_user_at_host() -> str:
  77. """Best-effort 'user@hostname' for the SSH tunnel hint; placeholders keep it valid syntax."""
  78. try:
  79. import socket as _socket
  80. hostname = _socket.gethostname() or "<this-host>"
  81. except OSError:
  82. hostname = "<this-host>"
  83. user = os.getenv("USER") or os.getenv("LOGNAME") or "<user>"
  84. return f"{user}@{hostname}"
  85. def _pkce_code_verifier(length: int = 64) -> str:
  86. return base64.urlsafe_b64encode(os.urandom(length)).decode("ascii").rstrip("=")[:128]
  87. def _pkce_code_challenge(code_verifier: str) -> str:
  88. digest = hashlib.sha256(code_verifier.encode("utf-8")).digest()
  89. return base64.urlsafe_b64encode(digest).decode("ascii").rstrip("=")
  90. def _make_loopback_callback_handler(
  91. expected_path: str, *, display_name: str,
  92. ) -> tuple[type[BaseHTTPRequestHandler], dict[str, Any]]:
  93. """Handler class for an RFC 8252 loopback redirect plus the dict it fills in.
  94. Only a GET on *expected_path* is accepted (anything else is a 404 and leaves the result
  95. untouched), so a nonce embedded in the path acts as the CSRF ``state`` for authorization
  96. servers that do not echo an explicit ``state`` parameter.
  97. """
  98. result: dict[str, Any] = {"code": None, "state": None, "error": None, "error_description": None}
  99. class _LoopbackCallbackHandler(BaseHTTPRequestHandler):
  100. def do_GET(self) -> None:
  101. parsed = urlparse(self.path)
  102. if parsed.path != expected_path:
  103. self.send_response(404)
  104. self.end_headers()
  105. self.wfile.write(b"Not found.")
  106. return
  107. params = parse_qs(parsed.query)
  108. for key in result:
  109. result[key] = params.get(key, [None])[0]
  110. self.send_response(200)
  111. self.send_header("Content-Type", "text/html; charset=utf-8")
  112. self.end_headers()
  113. outcome = "failed" if result["error"] else "received"
  114. self.wfile.write(
  115. f"<html><body><h1>{display_name} authorization {outcome}.</h1>"
  116. "You can close this tab.</body></html>".encode())
  117. def log_message(self, format: str, *args: Any) -> None:
  118. return
  119. return _LoopbackCallbackHandler, result
  120. def _bind_loopback_callback_server(
  121. host: str, port: int, handler_cls: type[BaseHTTPRequestHandler], *, err: Callable[..., AuthError],
  122. bind_failed_code: str,
  123. ) -> HTTPServer:
  124. """Bind the loopback listener up front (``port=0`` = OS-assigned) so the redirect URI sent to
  125. the authorization server names a port we already own — no probe-close-rebind race."""
  126. class _ReuseHTTPServer(HTTPServer):
  127. allow_reuse_address = True
  128. try:
  129. return _ReuseHTTPServer((host, port), handler_cls)
  130. except OSError as exc:
  131. raise err(f"Could not bind callback server on {host}:{port}: {exc}", bind_failed_code) from exc
  132. def _serve_loopback_callback(
  133. server: HTTPServer, result: dict[str, Any], *, timeout_seconds: float, err: Callable[..., AuthError],
  134. timeout_code: str,
  135. ) -> dict[str, Any]:
  136. """Serve *server* until the redirect lands in *result* or the deadline passes; always closes."""
  137. thread = threading.Thread(target=server.serve_forever, kwargs={"poll_interval": 0.1}, daemon=True)
  138. thread.start()
  139. deadline = time.monotonic() + max(5.0, timeout_seconds)
  140. try:
  141. while time.monotonic() < deadline:
  142. if result["code"] or result["error"]:
  143. return result
  144. time.sleep(0.1)
  145. finally:
  146. server.shutdown()
  147. server.server_close()
  148. thread.join(timeout=1.0)
  149. raise err("Authorization timed out waiting for the local callback.", timeout_code)
  150. def _print_loopback_ssh_hint(redirect_uri: str, *, docs_url: str | None = None) -> None:
  151. """Print an SSH tunnel hint when a loopback-redirect OAuth flow runs on a remote host.
  152. The auth server redirects the browser to ``127.0.0.1:<port>/callback``; when the browser is
  153. on another machine (the SSH case) the redirect needs a local port forward to reach us.
  154. """
  155. from hermes_cli.auth import _is_remote_session
  156. if not _is_remote_session():
  157. return
  158. try:
  159. parsed = urlparse(redirect_uri)
  160. except Exception:
  161. return
  162. host, port = parsed.hostname or "", parsed.port
  163. if host not in {"127.0.0.1", "::1", "localhost"} or not port:
  164. return
  165. divider = "-" * 60
  166. print(
  167. f"\n{divider}\nRemote session detected — SSH tunnel required\n{divider}\n"
  168. f"Hermes is waiting for the OAuth callback on {redirect_uri}\n"
  169. "but your browser is on a different machine. Run this command\n"
  170. "in a NEW terminal on your local machine BEFORE opening the URL:\n\n"
  171. f" ssh -N -L {port}:127.0.0.1:{port} {_ssh_user_at_host()}\n\n"
  172. "Then open the authorize URL above in your local browser.")
  173. if docs_url:
  174. print(f"Provider docs: {docs_url}")
  175. print(f"SSH/jump-box guide: {OAUTH_OVER_SSH_DOCS_URL}\n{divider}\n")
  176. def _default_verify() -> bool | ssl.SSLContext:
  177. """Platform-aware default SSL verify for httpx clients.
  178. On macOS with Homebrew Python the system OpenSSL cannot find the system trust store, so pin
  179. certifi's bundle when importable; elsewhere defer to httpx's built-in default. The bundle is
  180. resolved through ``agent.ssl_verify``, the one place that re-derives a path an
  181. install-environment rotation deleted: the Nous credential exchange builds its context here, and
  182. in a long-lived gateway it can be the first TLS client constructed after the rotation.
  183. """
  184. from agent.ssl_verify import certifi_bundle_path, platform_ssl_context
  185. bundle = certifi_bundle_path()
  186. if bundle is None:
  187. # No usable certifi bundle (absent, or deleted by a rotation and not re-derivable):
  188. # httpx's ``True`` would still resolve through certifi, so hand over the platform store.
  189. return platform_ssl_context()
  190. if sys.platform == "darwin":
  191. return ssl.create_default_context(cafile=bundle)
  192. return True
  193. def _resolve_verify(
  194. *, insecure: Optional[bool] = None, ca_bundle: Optional[str] = None,
  195. auth_state: Optional[dict[str, Any]] = None) -> bool | ssl.SSLContext:
  196. from hermes_cli.auth import _default_verify
  197. tls_state = auth_state.get("tls") if isinstance(auth_state, dict) else {}
  198. tls_state = tls_state if isinstance(tls_state, dict) else {}
  199. effective_insecure = (
  200. is_truthy_value(insecure, default=False) if insecure is not None
  201. else is_truthy_value(tls_state.get("insecure", False), default=False))
  202. effective_ca = (
  203. ca_bundle or tls_state.get("ca_bundle") or os.getenv("HERMES_CA_BUNDLE")
  204. or os.getenv("SSL_CERT_FILE") or os.getenv("REQUESTS_CA_BUNDLE"))
  205. if effective_insecure:
  206. return False
  207. if effective_ca:
  208. ca_path = str(effective_ca)
  209. if not os.path.isfile(ca_path):
  210. logger.warning(
  211. "CA bundle path does not exist: %s — falling back to default certificates",
  212. ca_path)
  213. return _default_verify()
  214. return ssl.create_default_context(cafile=ca_path)
  215. return _default_verify()
  216. def _request_device_code(
  217. client: httpx.Client, portal_base_url: str, client_id: str, scope: Optional[str],
  218. ) -> dict[str, Any]:
  219. """POST to the device code endpoint. Returns device_code, user_code, etc."""
  220. response = client.post(
  221. f"{portal_base_url}/api/oauth/device/code",
  222. data={"client_id": client_id, **({"scope": scope} if scope else {})})
  223. response.raise_for_status()
  224. data = response.json()
  225. required_fields = [
  226. "device_code", "user_code", "verification_uri", "verification_uri_complete", "expires_in",
  227. "interval"]
  228. missing = [f for f in required_fields if f not in data]
  229. if missing:
  230. raise ValueError(f"Device code response missing fields: {', '.join(missing)}")
  231. return data
  232. def _nous_device_auth_timeout_message(portal_base_url: str) -> str:
  233. """Actionable timeout text: the usual cause is Portal sign-in failing in the browser tab.
  234. A bare "Timed out waiting for device authorization" gives the user nothing to act on. The most common
  235. cause is Portal sign-in failing in the opened browser tab (including the server-side CAPTCHA loop from
  236. 20605), so point at the Portal login page and the retry command. See #20605.
  237. """
  238. portal = (portal_base_url or DEFAULT_NOUS_PORTAL_URL).rstrip("/")
  239. return (
  240. "Timed out waiting for device authorization.\n"
  241. " Portal sign-in is required before the device code can be approved.\n"
  242. " If the browser showed a CAPTCHA / 'You did not pass CAPTCHA' error,\n"
  243. " finish signing in at the Portal in a normal browser tab, then retry:\n"
  244. " hermes portal\n"
  245. f" Portal login: {portal}/login")
  246. def _print_device_code_instructions(
  247. verification_url: str, user_code: str, *, open_browser: bool, failure_dash: str = "--",
  248. swallow_open_errors: bool = False) -> None:
  249. """Print the shared "To continue" device-code block and optionally open the browser.
  250. Callers decide *whether* to open (remote-session / graphical-browser gating differs per
  251. provider); *failure_dash* keeps each provider's historical hint wording.
  252. """
  253. print()
  254. print("To continue:")
  255. print(f" 1. Open: {verification_url}")
  256. print(f" 2. If prompted, enter code: {user_code}")
  257. if not open_browser:
  258. return
  259. try:
  260. opened = webbrowser.open(verification_url)
  261. except Exception:
  262. if not swallow_open_errors:
  263. raise
  264. opened = False
  265. if opened:
  266. print(" (Opened browser for verification)")
  267. else:
  268. print(f" Could not open browser automatically {failure_dash} use the URL above.")
  269. class DeviceFlowCancelled(Exception):
  270. """The caller's ``cancelled`` hook fired while the token poll was waiting."""
  271. def _cancellable_sleep(seconds: float, cancelled: Optional[Callable[[], bool]]) -> None:
  272. """Sleep *seconds*; with a hook, in <= 1 s ticks so a cancel ends the poll within a second."""
  273. if cancelled is None:
  274. time.sleep(seconds)
  275. return
  276. wake = time.monotonic() + seconds
  277. while not cancelled():
  278. remaining = wake - time.monotonic()
  279. if remaining <= 0:
  280. return
  281. time.sleep(min(1.0, remaining))
  282. raise DeviceFlowCancelled()
  283. def _poll_device_token_generic(
  284. post: Callable[[], httpx.Response], *, expires_in: int, poll_interval: int,
  285. validate_success: Callable[[dict[str, Any]], None],
  286. on_non_json_error: Callable[[httpx.Response], Exception],
  287. on_error: Callable[[httpx.Response, dict[str, Any]], Exception],
  288. on_timeout: Callable[[], Exception], cancelled: Optional[Callable[[], bool]] = None) -> dict[str, Any]:
  289. """RFC 8628 device-code polling loop shared by the Nous and xAI flows.
  290. ``authorization_pending`` sleeps and retries; ``slow_down`` grows the interval by 1s (cap 30s).
  291. A non-JSON 408/429/5xx, or a 403 carrying ``x-vercel-mitigated`` (edge/WAF mitigation, never a
  292. real OAuth error), backs off — honoring ``Retry-After``, capped at 60s and at the device-code
  293. deadline — instead of aborting a login the user may still be approving. Every other error, a
  294. non-JSON error body, and the deadline become provider-specific exceptions via the supplied
  295. factories so each caller keeps its exact error contract. *cancelled* is checked before every
  296. request and during every wait; once it fires the poll raises :class:`DeviceFlowCancelled`.
  297. """
  298. deadline = time.monotonic() + max(1, expires_in)
  299. current_interval = poll_interval
  300. edge_backoff = 0.0 # kept apart from current_interval so slow_down/pending pacing is untouched
  301. unavailable = 0 # HTTP status of the latest edge/service failure; 0 once the endpoint answers again
  302. while time.monotonic() < deadline:
  303. if cancelled is not None and cancelled():
  304. raise DeviceFlowCancelled()
  305. response = post()
  306. if response.status_code == 200:
  307. payload = response.json()
  308. validate_success(payload)
  309. return payload
  310. try:
  311. error_payload = response.json()
  312. except Exception:
  313. status = response.status_code
  314. # Edge/WAF mitigation: back off and keep polling until the device code expires.
  315. if status in {408, 429} or status >= 500 or (
  316. status == 403 and response.headers.get("x-vercel-mitigated")):
  317. from agent.retry_utils import parse_retry_after_seconds
  318. unavailable = status
  319. retry_after = parse_retry_after_seconds(response.headers)
  320. if retry_after is not None:
  321. edge_backoff = min(max(current_interval, retry_after), 60)
  322. else:
  323. edge_backoff = min(max(edge_backoff * 2, current_interval * 2, 5), 60)
  324. _cancellable_sleep(max(0.0, min(edge_backoff, deadline - time.monotonic())), cancelled)
  325. continue
  326. response.raise_for_status()
  327. raise on_non_json_error(response)
  328. edge_backoff, unavailable = 0.0, 0
  329. error_code = str(error_payload.get("error") or "")
  330. if error_code == "authorization_pending":
  331. _cancellable_sleep(min(current_interval, max(0.0, deadline - time.monotonic())), cancelled)
  332. continue
  333. if error_code == "slow_down":
  334. current_interval = min(current_interval + 1, 30)
  335. _cancellable_sleep(current_interval, cancelled)
  336. continue
  337. raise on_error(response, error_payload)
  338. # Still failing when the code ran out: a service outage (``__cause__``), not a sign-in left unapproved.
  339. raise on_timeout() from (ConnectionError(f"token endpoint answered HTTP {unavailable}") if unavailable else None)
  340. def _poll_for_token(
  341. client: httpx.Client, portal_base_url: str, client_id: str, device_code: str,
  342. expires_in: int, poll_interval: int, cancelled: Optional[Callable[[], bool]] = None) -> dict[str, Any]:
  343. """Poll the Nous token endpoint until the user approves or the code expires."""
  344. def _validate(payload: dict[str, Any]) -> None:
  345. if "access_token" not in payload:
  346. raise ValueError("Token response did not include access_token")
  347. def _error(_response, error_payload) -> Exception:
  348. # Plain copy per OAuth error code; the raw ``code: description`` stays on a Details line.
  349. from hermes_cli.auth_error_copy import device_flow_error
  350. return device_flow_error(
  351. str(error_payload.get("error", "") or ""),
  352. str(error_payload.get("error_description") or "Unknown authentication error"))
  353. return _poll_device_token_generic(
  354. lambda: client.post(
  355. f"{portal_base_url}/api/oauth/token",
  356. data={
  357. "grant_type": DEVICE_CODE_GRANT_TYPE, "client_id": client_id,
  358. "device_code": device_code}),
  359. expires_in=expires_in,
  360. poll_interval=max(1, min(poll_interval, DEVICE_AUTH_POLL_INTERVAL_CAP_SECONDS)),
  361. validate_success=_validate, on_error=_error,
  362. on_non_json_error=lambda _r: RuntimeError(
  363. "Token endpoint returned a non-JSON error response"),
  364. # Enriched at the SOURCE so the CLI login and the dashboard/desktop poller
  365. # (web_server_oauth._nous_sign_in_poller surfaces it to the UI) both inherit the guidance.
  366. on_timeout=lambda: DeviceCodeExpired(_nous_device_auth_timeout_message(portal_base_url)),
  367. cancelled=cancelled)
  368. def _prompt_yes_no(prompt: str, *, default: str) -> bool:
  369. """``input()`` a [Y/n]-style question; EOF/Ctrl-C count as *default*."""
  370. try:
  371. answer = input(prompt).strip().lower()
  372. except (EOFError, KeyboardInterrupt):
  373. answer = default
  374. return answer in {"", "y", "yes"} if default == "y" else answer in {"y", "yes"}
  375. def _print_login_success(
  376. provider_id: str, config_path: Path, *, show_auth_state: bool = False) -> None:
  377. print()
  378. print("Login successful!")
  379. if show_auth_state:
  380. from hermes_constants import display_hermes_home as _dhh
  381. print(f" Auth state: {_dhh()}/auth.json")
  382. print(f" Config updated: {config_path} (model.provider={provider_id})")
  383. def _offer_existing_oauth_credentials(
  384. provider_id: str, *, resolve: Callable[[], dict[str, Any]],
  385. is_expiring: Callable[[str, int], bool], display_name: str, default_base_url: str,
  386. expired_notice: Optional[str] = None) -> bool:
  387. """Offer to reuse still-valid stored OAuth credentials. Returns True when the user accepted.
  388. *resolve* attempts a refresh, so a resolved token should be valid — but double-check the
  389. expiry before telling the user "Login successful!".
  390. """
  391. from hermes_cli.auth import _update_config_for_provider
  392. try:
  393. existing = resolve()
  394. api_key = existing.get("api_key", "")
  395. if isinstance(api_key, str) and api_key and not is_expiring(api_key, 60):
  396. print(f"Existing {display_name} credentials found in Hermes auth store.")
  397. if _prompt_yes_no("Use existing credentials? [Y/n]: ", default="y"):
  398. config_path = _update_config_for_provider(
  399. provider_id, existing.get("base_url", default_base_url))
  400. _print_login_success(provider_id, config_path)
  401. return True
  402. elif expired_notice:
  403. print(expired_notice)
  404. except AuthError:
  405. pass
  406. return False