anon_challenge.py 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494
  1. """Nous free tier: the browser challenge the account service may put in front of a token exchange.
  2. NAS can answer ``POST /api/anonymous/token`` with **428** ``challenge_required`` and a list of
  3. challenges. Hermes implements exactly one primitive, ``browser-v1``: *open this portal URL, poll
  4. until it clears, exchange again*. Everything the page does (bot detection, an in-browser proof of
  5. work, an interactive fallback, its copy) belongs to the portal and changes without a Hermes release.
  6. Who opens the URL depends on the surface:
  7. * **desktop** (``HERMES_DESKTOP=1``): this process never opens anything. It publishes the challenge
  8. (``free_tier.challenge`` global event, and ``free_tier.status``'s ``challenge`` field for a client
  9. that connects later); the renderer hands it to the Electron main process, which loads it in a
  10. HIDDEN window and reveals that window only if the page asks for the human.
  11. * **terminal**: print the URL, and open the system browser when there is a graphical one to open.
  12. The wait runs OUTSIDE the auth-store and shared-store locks: the exchange that hit the 428 has
  13. already unwound (the exception left the ``with`` blocks), so a slow page never stalls a sibling
  14. profile or process. One challenge is worked at a time per process; a second thread that hits the
  15. same 428 waits for the first and then simply exchanges again (NAS hands a retried mint the same
  16. ticket, and a cleared credential a token).
  17. Only a caller someone is waiting on waits for a challenge. A background reader (the keepalive tick,
  18. a status paint) runs inside :func:`background_caller`: it still gets the challenge in front of a
  19. desktop client (so the hidden window can clear it before anyone needs a token) but never blocks,
  20. prints, or opens a browser.
  21. An *optional* challenge (``required: false`` on a successful exchange: the service is measuring, not
  22. enforcing) is only ever announced to a desktop client, never opened in a user's browser, and
  23. nothing waits on it.
  24. """
  25. from __future__ import annotations
  26. import contextlib
  27. import contextvars
  28. import logging
  29. import math
  30. import platform
  31. import sys
  32. import threading
  33. import time
  34. from dataclasses import dataclass, field, replace
  35. from typing import Any, Callable, Dict, Optional, TypeVar
  36. from urllib.parse import urlparse
  37. from hermes_cli.anon_auth import (
  38. ANON_CHALLENGE_REQUIRED, ANON_FAILURE_COPY, ANON_SIGNIN_REQUIRED, _anon_headers, _mint_memo_key)
  39. from hermes_cli.auth_constants import AuthError, httpx
  40. logger = logging.getLogger("hermes_cli.auth")
  41. BROWSER_CAPABILITY = "browser-v1"
  42. CHALLENGE_EVENT = "free_tier.challenge"
  43. # How long one exchange attempt waits for its challenge. The page normally clears in seconds; this
  44. # bounds the interactive case (a human solving a check) without parking a request for the ticket's
  45. # whole ten minutes. A later attempt resumes the same ticket.
  46. CHALLENGE_WAIT_SECONDS = 120.0
  47. _POLL_MIN_SECONDS, _POLL_MAX_SECONDS = 1.0, 5.0
  48. # ``expires_in`` is network input that ends up in timers on two runtimes: keep it finite and sane.
  49. _EXPIRES_MIN_SECONDS, _EXPIRES_MAX_SECONDS, _EXPIRES_DEFAULT_SECONDS = 30.0, 900.0, 600.0
  50. _MESSAGE_MAX_CHARS = 300
  51. # After one attempt ran out of patience, the callers queued behind it fail fast for this long
  52. # instead of each parking for another full wait (boot fires a burst of token reads).
  53. _GAVE_UP_COOLDOWN_SECONDS = 30.0
  54. CHALLENGE_COPY = "Nous needs to run a quick check before starting your free session."
  55. T = TypeVar("T")
  56. @dataclass(frozen=True)
  57. class BrowserChallenge:
  58. url: str
  59. required: bool
  60. expires_in: float
  61. interval: float
  62. message: str
  63. attempt: int = 0
  64. def as_payload(self) -> dict[str, Any]:
  65. return {"type": "browser", "url": self.url, "required": self.required,
  66. "expires_in": int(self.expires_in), "message": self.message, "attempt": self.attempt}
  67. class AnonChallengeRequired(AuthError):
  68. """The exchange needs a browser challenge first. Carries what :func:`run_with_challenge` needs
  69. to work it: the challenge, and the portal, credential and auth state (its ``tls`` block) to poll with."""
  70. def __init__(self, challenge: BrowserChallenge, *, portal_base_url: str, anon_token: str,
  71. auth_state: dict[str, Any]) -> None:
  72. super().__init__(challenge.message, provider="nous", code=ANON_CHALLENGE_REQUIRED, retryable=True)
  73. self.challenge = challenge
  74. self.portal_base_url = portal_base_url
  75. self.anon_token = anon_token
  76. self.auth_state = auth_state
  77. def signin_required_error(message: Any = None) -> AuthError:
  78. """The service will not serve this client without an account (or asked for something this
  79. version cannot do). Terminal for the process, like a closed gate."""
  80. return AuthError(server_message(message) or ANON_FAILURE_COPY[ANON_SIGNIN_REQUIRED], provider="nous",
  81. code=ANON_SIGNIN_REQUIRED, retryable=False)
  82. def server_message(value: Any) -> str:
  83. """User-facing copy the service sent, if it is plausibly that: a short single paragraph."""
  84. if not isinstance(value, str):
  85. return ""
  86. # Printable text only: this reaches a terminal, and a control character there is an escape
  87. # sequence the service (or whoever answered as it) gets to run.
  88. text = " ".join("".join(ch if ch.isprintable() else " " for ch in value).split())
  89. return text if 0 < len(text) <= _MESSAGE_MAX_CHARS else ""
  90. # --- What this client tells the service about itself -------------------------------------------------
  91. def client_surface() -> str:
  92. """``gateway`` in the process that holds the messaging gateway's runtime lock (nobody is at its
  93. console) unless it is serving the local Desktop app, ``desktop`` for that and for the backend the
  94. desktop app spawned, else ``cli``. ``HERMES_DESKTOP``
  95. alone is inherited by every terminal-pane shell, so desktop ownership needs the spawn credential."""
  96. from hermes_cli.process_identity import is_desktop_owned_backend, serves_local_desktop_now
  97. if serves_local_desktop_now():
  98. return "desktop"
  99. status = sys.modules.get("gateway.status")
  100. if status is not None and status.owns_gateway_runtime_lock():
  101. return "gateway"
  102. return "desktop" if is_desktop_owned_backend() else "cli"
  103. def client_info() -> dict[str, Any]:
  104. """The self-reported ``client`` block on a token exchange. It sorts honest clients (which
  105. surface, which challenge primitives) for the service's rules; it proves nothing, by design."""
  106. from hermes_cli.version_info import get_version_info
  107. return {"name": "hermes-agent", "version": get_version_info().base_version, "surface": client_surface(),
  108. "platform": sys.platform, "capabilities": [BROWSER_CAPABILITY]}
  109. def user_agent() -> str:
  110. from hermes_cli.version_info import get_version_info
  111. return (f"hermes-agent/{get_version_info().base_version} "
  112. f"({client_surface()}; {sys.platform}; {platform.machine() or 'unknown'})")
  113. # --- Parsing ------------------------------------------------------------------------------------------
  114. def _same_origin(url: str, portal_base_url: str) -> bool:
  115. """A challenge URL is only ever opened on the portal the exchange itself went to: the response
  116. is network input, and "open this URL" must not become "open any URL"."""
  117. try:
  118. target, portal = urlparse(url), urlparse(portal_base_url)
  119. except ValueError:
  120. return False
  121. return (target.scheme in ("https", "http") and target.scheme == portal.scheme
  122. and bool(target.netloc) and target.netloc.lower() == portal.netloc.lower())
  123. def _number(value: Any, default: float) -> float:
  124. if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
  125. return default
  126. return float(value)
  127. def parse_browser_challenge(payload: dict[str, Any], portal_base_url: str) -> Optional[BrowserChallenge]:
  128. """The first challenge in ``payload["challenges"]`` this client can run, or None."""
  129. entries = payload.get("challenges")
  130. if not isinstance(entries, list):
  131. return None
  132. message = server_message(payload.get("message")) or CHALLENGE_COPY
  133. for entry in entries:
  134. if not isinstance(entry, dict) or entry.get("type") != "browser":
  135. continue
  136. url = entry.get("url")
  137. if not isinstance(url, str) or not url.isprintable() or not _same_origin(url, portal_base_url):
  138. logger.info("Nous free tier: ignoring a challenge URL outside the portal origin")
  139. continue
  140. return BrowserChallenge(
  141. url=url, required=entry.get("required") is not False,
  142. expires_in=min(_EXPIRES_MAX_SECONDS, max(
  143. _EXPIRES_MIN_SECONDS, _number(entry.get("expires_in"), _EXPIRES_DEFAULT_SECONDS))),
  144. interval=min(_POLL_MAX_SECONDS, max(_POLL_MIN_SECONDS, _number(entry.get("interval"), 2.0))),
  145. message=message)
  146. return None
  147. def challenge_error(payload: dict[str, Any], *, portal_base_url: str, anon_token: str,
  148. auth_state: dict[str, Any]) -> AuthError:
  149. """The error for a 428 ``challenge_required``: a challenge to work, or (nothing offered that
  150. this version can run) the sign-in fallback."""
  151. challenge = parse_browser_challenge(payload, portal_base_url)
  152. if challenge is None:
  153. # The payload's ``message`` describes the challenge, so it is not reused for the fallback.
  154. return signin_required_error()
  155. return AnonChallengeRequired(challenge, portal_base_url=portal_base_url, anon_token=anon_token,
  156. auth_state=auth_state)
  157. # --- Per-profile state: what a status read shows, and who is working it ---------------------------------
  158. @dataclass
  159. class _ProfileChallenge:
  160. """One profile's challenge state, behind ``_state_lock``. ``work_lock`` serialises waits PER
  161. PROFILE (a sibling profile's wait must not queue behind it)."""
  162. work_lock: threading.Lock = field(default_factory=threading.Lock)
  163. pending: Optional[BrowserChallenge] = None
  164. deadline: float = 0.0
  165. outcome: Optional[str] = None # how the host's window ended, for ``pending``'s attempt
  166. gave_up_until: float = 0.0
  167. _state_lock = threading.Lock()
  168. _profiles: dict[str, _ProfileChallenge] = {}
  169. _opened_urls: set[str] = set() # challenge URLs whose browser tab was opened (one per ticket)
  170. # Set by :func:`background_caller`: this caller has nobody waiting on it.
  171. _background: contextvars.ContextVar[bool] = contextvars.ContextVar("anon_challenge_background", default=False)
  172. @contextlib.contextmanager
  173. def background_caller():
  174. """Mark the enclosed token reads as background work (a keepalive tick, a status paint): a
  175. challenge is announced to a desktop client but never waited on, printed, or opened."""
  176. token = _background.set(True)
  177. try:
  178. yield
  179. finally:
  180. _background.reset(token)
  181. def _profile() -> _ProfileChallenge:
  182. """This profile's record. Callers hold ``_state_lock`` for anything but ``work_lock``."""
  183. with _state_lock:
  184. return _profiles.setdefault(_mint_memo_key(), _ProfileChallenge())
  185. def _live(record: _ProfileChallenge) -> Optional[BrowserChallenge]:
  186. if record.pending and record.deadline <= time.monotonic():
  187. record.pending, record.outcome = None, None
  188. return record.pending
  189. def pending_challenge() -> Optional[dict[str, Any]]:
  190. """The challenge this profile is waiting on, for ``free_tier.status`` (a client that connected
  191. after the event fired still learns it has a window to open). None once cleared or expired, or
  192. once the host said how its window ended (a window the user closed must not come back)."""
  193. record = _profile()
  194. with _state_lock:
  195. challenge = _live(record)
  196. if challenge is None or record.outcome not in (None, "timeout", "error"):
  197. return None
  198. return {**challenge.as_payload(), "expires_in": math.ceil(record.deadline - time.monotonic())}
  199. def _clear_pending() -> None:
  200. record = _profile()
  201. with _state_lock:
  202. record.pending, record.outcome = None, None
  203. def _record(challenge: BrowserChallenge, *, new_attempt: bool) -> BrowserChallenge:
  204. """Record *challenge* as the profile's pending one. A replay of the same ticket (a background
  205. read, a second 428) keeps the original deadline, attempt and host outcome; ``new_attempt`` (a
  206. foreground caller about to wait) bumps the attempt, which lets it reopen a window the user closed."""
  207. record = _profile()
  208. with _state_lock:
  209. previous = _live(record)
  210. deadline = time.monotonic() + challenge.expires_in
  211. if previous is None or previous.url != challenge.url:
  212. record.pending, record.deadline, record.outcome = replace(challenge, attempt=0), deadline, None
  213. else:
  214. attempt = previous.attempt + 1 if new_attempt else previous.attempt
  215. record.pending, record.deadline = replace(challenge, attempt=attempt), min(deadline, record.deadline)
  216. if new_attempt:
  217. record.outcome = None
  218. return record.pending
  219. def record_host_outcome(url: str, attempt: int, outcome: str) -> bool:
  220. """A presentation hint: wakes a waiter to re-mint, never grants clearance locally. A late
  221. reply belongs to the attempt that opened the window, not to a newer retry."""
  222. record = _profile()
  223. with _state_lock:
  224. challenge = _live(record)
  225. if challenge is None or (challenge.url, challenge.attempt) != (url, attempt):
  226. return False
  227. record.outcome = outcome
  228. return True
  229. def _host_outcome(challenge: BrowserChallenge) -> Optional[str]:
  230. record = _profile()
  231. with _state_lock:
  232. pending = record.pending
  233. matches = pending is not None and (pending.url, pending.attempt) == (challenge.url, challenge.attempt)
  234. return record.outcome if matches else None
  235. def _give_up() -> None:
  236. record = _profile()
  237. with _state_lock:
  238. record.gave_up_until = time.monotonic() + _GAVE_UP_COOLDOWN_SECONDS
  239. def _gave_up_recently() -> bool:
  240. record = _profile()
  241. with _state_lock:
  242. return time.monotonic() < record.gave_up_until
  243. def reset_for_tests() -> None:
  244. with _state_lock:
  245. _profiles.clear()
  246. _opened_urls.clear()
  247. # --- Presenting ---------------------------------------------------------------------------------------
  248. def _announce(challenge: BrowserChallenge) -> bool:
  249. """Broadcast to connected desktop clients. False when this process is not a gateway at all
  250. (``HERMES_DESKTOP`` is an env var, and a CLI the desktop spawned inherits it): importing the
  251. gateway here just to find nobody listening would also write an event frame to stdout."""
  252. server = sys.modules.get("tui_gateway.server")
  253. if server is None:
  254. return False
  255. try:
  256. server._broadcast_global_event(CHALLENGE_EVENT, challenge.as_payload())
  257. except (OSError, ValueError) as exc:
  258. # The stdio channel re-raises host I/O errors (ENOSPC, a locale that can't encode the
  259. # server's copy); the caller falls back to the terminal instead of losing the link.
  260. logger.debug("%s not broadcast: %s", CHALLENGE_EVENT, exc)
  261. return False
  262. return True
  263. def _present_in_terminal(challenge: BrowserChallenge) -> None:
  264. from hermes_cli.auth_device_flow import _can_open_graphical_browser, _is_remote_session
  265. opened = False
  266. # One tab per ticket, however many attempts resume it: a user who has not got to it yet is
  267. # not helped by a second copy. A gateway has no console of its own: it logs the link only.
  268. already_open = challenge.url in _opened_urls
  269. if (not already_open and client_surface() != "gateway"
  270. and not _is_remote_session() and _can_open_graphical_browser()):
  271. import webbrowser
  272. try:
  273. opened = bool(webbrowser.open(challenge.url))
  274. except (webbrowser.Error, OSError) as exc:
  275. logger.debug("could not open the challenge in a browser: %s", exc)
  276. if opened:
  277. _opened_urls.add(challenge.url)
  278. print(f"\n{challenge.message}", file=sys.stderr)
  279. print(f" Open: {challenge.url}", file=sys.stderr)
  280. print(" (Opened in your browser.)\n" if opened or already_open
  281. else " (Open that link in any browser; this continues on its own.)\n", file=sys.stderr)
  282. def present(challenge: BrowserChallenge) -> None:
  283. """Get the URL in front of something that can load it.
  284. The desktop backend hands every challenge to its hidden window. The stdio TUI gateway (whose
  285. stderr the TUI keeps as a log, never shows) hands its client a required one a foreground caller
  286. is waiting on: a background read there must not pop a browser any more than in a terminal."""
  287. if client_surface() == "desktop" and _announce(challenge):
  288. return
  289. if not challenge.required or _background.get():
  290. return
  291. server = sys.modules.get("tui_gateway.server")
  292. if server is not None and server._stdio_is_rpc_channel and _announce(challenge):
  293. return
  294. _present_in_terminal(challenge)
  295. # --- Working a challenge ----------------------------------------------------------------------------
  296. def _poll_status(client: httpx.Client, portal_base_url: str, anon_token: str) -> str:
  297. """One status read. Anything that is not a clear ``pending`` / ``needs_interaction`` ends the
  298. wait: the exchange that follows is the authority on whether the credential is cleared. (A
  299. passed challenge reads ``none``: passing detaches the ticket.)"""
  300. try:
  301. response = client.post(f"{portal_base_url.rstrip('/')}/api/anonymous/challenge/status",
  302. headers=_anon_headers(), json={"token": anon_token})
  303. if 400 <= response.status_code < 500 and response.status_code != 429:
  304. # The service will not answer this poll (credential reaped, surface off): waiting cannot
  305. # change that. End the wait; the exchange's own verdict says what happened.
  306. return "none"
  307. body = response.json() if response.status_code == 200 else None
  308. except (httpx.HTTPError, ValueError) as exc:
  309. logger.debug("challenge status poll failed: %s", exc)
  310. body = None
  311. status = body.get("status") if isinstance(body, dict) else None
  312. # Only a 200 that names a status is a verdict. A 429, a 5xx or a dropped connection is a
  313. # blip: keep waiting (the deadline bounds it) rather than abandon a check the user is on.
  314. return status if isinstance(status, str) else "pending"
  315. _WAITING = ("pending", "needs_interaction")
  316. _sleep = time.sleep # seam for tests (same idiom as ``free_tier_bootstrap._sleep``)
  317. def wait_for_challenge(exc: AnonChallengeRequired) -> bool:
  318. """Present *exc*'s challenge and poll until status or a host hint ends the wait.
  319. True = a result arrived; False = patience ran out. Re-mint is authoritative in either case.
  320. Called under the profile's work lock. A caller that queued behind another finds the ticket
  321. already settled on its first status read and returns without presenting anything."""
  322. from hermes_cli.auth import _resolve_verify
  323. from hermes_cli.auth_nous import _nous_http_client
  324. if _gave_up_recently():
  325. return False
  326. challenge = exc.challenge
  327. deadline = time.monotonic() + min(CHALLENGE_WAIT_SECONDS, challenge.expires_in)
  328. # Poll under the trust the credential was minted with: a guest's ``tls`` block is written from
  329. # the mint's own verify, so this is the context the 428 exchange just used, not a narrowing.
  330. verify = _resolve_verify(auth_state=exc.auth_state)
  331. told_interactive = False
  332. with _nous_http_client(10.0, verify) as client:
  333. if _poll_status(client, exc.portal_base_url, exc.anon_token) not in _WAITING:
  334. return True
  335. challenge = exc.challenge = _record(challenge, new_attempt=True)
  336. present(challenge)
  337. while time.monotonic() < deadline:
  338. if _host_outcome(challenge) is not None:
  339. return True
  340. _sleep(challenge.interval)
  341. status = _poll_status(client, exc.portal_base_url, exc.anon_token)
  342. if status not in _WAITING:
  343. return True
  344. if status == "needs_interaction" and not told_interactive:
  345. told_interactive = True
  346. if client_surface() != "desktop":
  347. print(" Finish the quick check in your browser to continue.", file=sys.stderr)
  348. _give_up()
  349. return False
  350. def _still_pending(cause: AnonChallengeRequired) -> AuthError:
  351. message = ("The quick check couldn't finish. Try again." if _host_outcome(cause.challenge)
  352. else ANON_FAILURE_COPY[ANON_CHALLENGE_REQUIRED])
  353. error = AuthError(message, provider="nous", code=ANON_CHALLENGE_REQUIRED, retryable=True)
  354. error.__cause__ = cause
  355. return error
  356. def run_with_challenge(exchange: Callable[[], T]) -> T:
  357. """Run *exchange*; if the service asks for a browser challenge, work it (outside every lock:
  358. the exception has already unwound them) and run *exchange* once more.
  359. A background caller (:func:`background_caller`) never waits: the challenge is announced so a
  360. desktop client can start clearing it, and the retryable error goes straight back.
  361. A second ``challenge_required`` is not looped on: it surfaces as a retryable error whose copy
  362. says what the user can do, the callers queued behind it fail fast for a while, and the next
  363. attempt resumes the same ticket."""
  364. try:
  365. return exchange()
  366. except AnonChallengeRequired as exc:
  367. first = exc
  368. # A messaging gateway has nobody at its console to clear a check, and its token reads can run
  369. # on the event loop: it never waits either.
  370. if _background.get() or client_surface() == "gateway":
  371. present(_record(first.challenge, new_attempt=False))
  372. raise _still_pending(first)
  373. with _profile().work_lock:
  374. wait_for_challenge(first)
  375. # Even a timed-out status poll can lag a committed clearance. Mint is
  376. # authoritative and gets one final attempt before we report a pending check.
  377. try:
  378. return exchange()
  379. except AnonChallengeRequired as again:
  380. # Whatever ended the wait (status, a host hint, patience), a second 428 starts the fail-fast
  381. # cooldown; the attempt after it opens a fresh window (``new_attempt``).
  382. again.challenge = _record(again.challenge, new_attempt=False)
  383. _give_up()
  384. raise _still_pending(again)
  385. except AuthError as error:
  386. if not error.retryable:
  387. _clear_pending()
  388. raise
  389. def note_optional_challenges(payload: dict[str, Any], portal_base_url: str) -> None:
  390. """A successful exchange may advertise a challenge nobody has to pass (the service is measuring
  391. before it enforces). Only a desktop client runs it, hidden; a terminal never opens a browser
  392. for something optional. Fire and forget."""
  393. challenge = parse_browser_challenge(payload, portal_base_url)
  394. if challenge is None:
  395. _clear_pending()
  396. elif not challenge.required and client_surface() == "desktop":
  397. _announce(_record(challenge, new_attempt=False))