web_server_boundary.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285
  1. """Listener boundary primitives shared by the dashboard app and the gateway's session listener:
  2. Host validation, the auth-gate decision and the native WebSocket ticket subprotocol.
  3. Import-light on purpose (no FastAPI): ``gateway.run_api`` serves the native session WebSocket
  4. without importing the dashboard app (about 690 routes, ~0.6 s), and must apply the same
  5. DNS-rebinding Host check and gate decision. ``hermes_cli.web_server`` and
  6. ``hermes_cli.web_server_chat`` re-export these names, so ``web_server.<name>`` keeps working.
  7. """
  8. import os
  9. import re
  10. import urllib.parse
  11. from typing import Optional
  12. # Accepted Host values for loopback binds. DNS rebinding TTL-flips an attacker
  13. # hostname to 127.0.0.1 so the browser treats it as same-origin; validating Host
  14. # at the app layer rejects it. See GHSA-ppp5-vxwm-4cf7.
  15. _LOOPBACK_HOST_VALUES: frozenset = frozenset({"localhost", "127.0.0.1", "::1"})
  16. # Starlette's TestClient reports the peer as "testclient"; treat it as
  17. # loopback so tests don't need to rewrite request scope.
  18. _LOOPBACK_HOSTS = frozenset({"127.0.0.1", "::1", "localhost", "testclient"})
  19. # Desktop file.attach sends a whole base64 data URL in one JSON-RPC frame;
  20. # uvicorn's 16 MiB default rejects files under the 256 MiB raw attach cap.
  21. _DESKTOP_ATTACHMENT_WS_MAX_BYTES = 384 * 1024 * 1024
  22. def _dashboard_public_hosts() -> frozenset[str]:
  23. """Return the exact hostname declared by ``dashboard.public_url``.
  24. One source of truth for OAuth redirects, Host and WS Origin validation.
  25. Malformed or unset values fail closed as an empty set.
  26. """
  27. from hermes_cli.dashboard_auth.prefix import resolve_public_url
  28. return public_url_hosts(resolve_public_url())
  29. def public_url_hosts(public_url: str) -> frozenset[str]:
  30. """The exact hostname *public_url* declares, as the trusted public host set; empty when unset or
  31. malformed."""
  32. try:
  33. hostname = urllib.parse.urlparse(public_url).hostname if public_url else None
  34. except ValueError:
  35. hostname = None
  36. return frozenset({hostname.lower()}) if hostname else frozenset()
  37. def _host_header_hostname(host_header: str) -> str:
  38. """Return a normalized hostname from a valid HTTP Host authority.
  39. Host headers are authorities, not full URLs. Reject ambiguous ports,
  40. malformed IPv6 brackets, and URL syntax so validation always fails closed.
  41. """
  42. value = (host_header or "").strip()
  43. if not value or "://" in value or any(c in value for c in '"\'<> \n\r\t/?#@'):
  44. return ""
  45. if value.startswith("["):
  46. close = value.find("]")
  47. if close == -1:
  48. return ""
  49. hostname = value[1:close]
  50. # Bracket notation is reserved for IPv6 literals.
  51. if ":" not in hostname:
  52. return ""
  53. suffix = value[close + 1:]
  54. if suffix and not re.fullmatch(r":\d+", suffix):
  55. return ""
  56. return hostname.lower()
  57. # Unbracketed IPv6 authorities are ambiguous with a port separator.
  58. if value.count(":") > 1:
  59. return ""
  60. if ":" in value:
  61. hostname, port = value.rsplit(":", 1)
  62. if not hostname or not port.isdigit():
  63. return ""
  64. return hostname.lower()
  65. return value.lower()
  66. def _is_accepted_host(
  67. host_header: str,
  68. bound_host: str,
  69. trusted_public_hosts: frozenset[str] = frozenset(),
  70. ) -> bool:
  71. """True if the Host header targets the interface we bound to.
  72. Accepts:
  73. - Exact bound host (with or without port suffix)
  74. - Loopback aliases when bound to loopback
  75. - Exact operator-declared public hosts (with or without port suffix)
  76. - Any host when bound to 0.0.0.0 (explicit opt-in to non-loopback,
  77. no protection possible at this layer)
  78. """
  79. host_only = _host_header_hostname(host_header)
  80. if not host_only:
  81. return False
  82. # All-interfaces bind: no Host-layer defence is possible; rely on operator
  83. # network controls.
  84. if host_only in trusted_public_hosts or bound_host in {"0.0.0.0", "::"}:
  85. return True
  86. bound_lc = bound_host.lower()
  87. if bound_lc in _LOOPBACK_HOST_VALUES:
  88. return host_only in _LOOPBACK_HOST_VALUES
  89. return host_only == bound_lc
  90. def should_require_auth(host: str, allow_public: bool = False) -> bool:
  91. """True iff the auth gate must be active: any non-loopback bind.
  92. RFC1918 / CGNAT / link-local are deliberately PUBLIC — a hostile LAN device
  93. is the threat model. ``allow_public`` (legacy ``--insecure``) is accepted for
  94. old launch scripts but IGNORED since the June 2026 hermes-0day campaign.
  95. """
  96. return host not in _LOOPBACK_HOST_VALUES
  97. def public_hosts_engage_gate(trusted_public_hosts: frozenset[str]) -> bool:
  98. """A non-loopback ``dashboard.public_url`` host engages the auth gate even on a loopback bind."""
  99. return any(h not in _LOOPBACK_HOST_VALUES for h in trusted_public_hosts)
  100. def _desktop_loopback_auth_exempt(
  101. host: str,
  102. ssh_session_token: Optional[str] = None,
  103. ssh_owner_nonce: Optional[str] = None,
  104. ) -> bool:
  105. """True for a Desktop-owned loopback backend (#96490).
  106. A non-loopback ``dashboard.public_url`` would otherwise engage the
  107. ticket-only gate for the private loopback backends Desktop spawns, whose
  108. per-spawn session token the gate's WS path refuses — Desktop could not boot.
  109. The public dashboard is a separate non-loopback process that stays gated, so
  110. this never opens the public surface. Requires ALL of: loopback bind,
  111. ``HERMES_DESKTOP=1``, and an operator-minted credential (env token, SSH
  112. session token, or owner nonce).
  113. """
  114. return (
  115. host in _LOOPBACK_HOST_VALUES
  116. and os.environ.get("HERMES_DESKTOP") == "1"
  117. and bool(os.environ.get("HERMES_DASHBOARD_SESSION_TOKEN") or ssh_session_token or ssh_owner_nonce)
  118. )
  119. def listener_auth_required(host: str, trusted_public_hosts: frozenset[str]) -> bool:
  120. """The ``app.state.auth_required`` value ``web_server._configure_auth_gate(host, False, None,
  121. None)`` resolves for a listener with no SSH credentials (the gateway's session listener)."""
  122. if _desktop_loopback_auth_exempt(host):
  123. return should_require_auth(host)
  124. return should_require_auth(host) or public_hosts_engage_gate(trusted_public_hosts)
  125. _GATEWAY_WS_PROTOCOL = "hermes-gateway-v1"
  126. _GATEWAY_WS_TICKET_PROTOCOL_PREFIX = "hermes-gateway-ticket."
  127. def _gateway_ws_ticket_from_subprotocol(ws) -> tuple[str, str]:
  128. """Return ``(ticket, reason)`` from an unambiguous gateway protocol set."""
  129. raw = str(ws.headers.get("sec-websocket-protocol", "") or "")
  130. protocols = [value.strip() for value in raw.split(",") if value.strip()]
  131. ticket_protocols = [
  132. value for value in protocols if value.startswith(_GATEWAY_WS_TICKET_PROTOCOL_PREFIX)]
  133. if not ticket_protocols:
  134. return "", "none"
  135. if _GATEWAY_WS_PROTOCOL not in protocols or len(ticket_protocols) != 1:
  136. return "", "invalid"
  137. ticket = ticket_protocols[0][len(_GATEWAY_WS_TICKET_PROTOCOL_PREFIX):]
  138. return (ticket, "ok") if ticket else ("", "invalid")
  139. def ws_client_reason(ws, state) -> Optional[str]:
  140. """Rejection reason token for the WebSocket peer IP under listener *state*
  141. (``auth_required`` / ``bound_host``), or None when allowed.
  142. Loopback bind: only loopback peers (the legacy ``?token=`` is the only auth,
  143. LAN hosts must not get to guess it); an empty peer fails closed. Explicit
  144. non-loopback bind (``--insecure``) or gated mode: any peer — DNS-rebinding is
  145. blocked by :func:`ws_host_origin_reason`, and in gated mode
  146. ``ws.client.host`` is the X-Forwarded-For value anyway.
  147. """
  148. if getattr(state, "auth_required", False):
  149. return None
  150. bound_host = (getattr(state, "bound_host", "") or "").strip().lower()
  151. if bound_host and bound_host not in _LOOPBACK_HOSTS:
  152. return None
  153. client_host = ws.client.host if ws.client else ""
  154. if not client_host:
  155. return f"missing_or_empty_peer bound={bound_host or '?'}"
  156. if client_host in _LOOPBACK_HOSTS:
  157. return None
  158. return f"peer_not_loopback peer={client_host} bound={bound_host or '?'}"
  159. # CORS: this backend's own loopback origin (the port actually bound) and the desktop dev renderer it
  160. # was spawned for, nothing else (web-dashboard.md § CORS). allow_origins=["*"] on 0.0.0.0 would let
  161. # any website read/modify config and secrets; ANY local port would let a page previewed from another
  162. # port (an agent-built site, Live Server, a compromised dev app) read index.html's session token and
  163. # drive /api/pty. No fixed dev port is trusted either: 3000, 5173 and 5174 are where most local dev
  164. # servers land (Vite takes 5174 when 5173 is busy). The dashboard's Vite dev server proxies with
  165. # Host and Origin unchanged (web/vite.config.ts), so its page's upgrades name the Host they dial and
  166. # ws_host_origin_reason admits them; it needs no grant here. The WebSocket Origin gate applies the
  167. # same rule (ws_host_origin_reason).
  168. def _loopback_origin(origin: str) -> Optional[tuple[str, str, int]]:
  169. """``(scheme, host, port)`` of an http(s) loopback origin (default port filled in), else None."""
  170. try:
  171. parsed = urllib.parse.urlparse(origin)
  172. port = parsed.port or {"http": 80, "https": 443}.get(parsed.scheme)
  173. except ValueError: # malformed authority, out-of-range / non-numeric port
  174. return None
  175. if parsed.scheme not in {"http", "https"} or parsed.hostname not in _LOOPBACK_HOST_VALUES:
  176. return None
  177. return parsed.scheme, parsed.hostname, port
  178. def public_url_origins(public_url: str) -> frozenset[tuple[str, str, int]]:
  179. """The loopback origin a ``public_url`` declares (a reverse proxy on another local port), as the
  180. set :func:`is_trusted_local_origin` reads from ``state.trusted_public_origins``; empty for an
  181. unset, malformed or non-loopback URL (a non-loopback Origin never meets the port check)."""
  182. origin = _loopback_origin(public_url) if public_url else None
  183. return frozenset({origin}) if origin else frozenset()
  184. def _dashboard_public_origins() -> frozenset[tuple[str, str, int]]:
  185. """:func:`public_url_origins` of ``dashboard.public_url``."""
  186. from hermes_cli.dashboard_auth.prefix import resolve_public_url
  187. return public_url_origins(resolve_public_url())
  188. def is_trusted_local_origin(origin: str, state) -> bool:
  189. """True for a loopback origin on *state*'s bound port, the exact origin of the configured public
  190. URL (``state.trusted_public_origins``: a proxy at ``https://localhost:8443`` that rewrites Host to
  191. the backend's), or the desktop dev renderer this backend serves. Electron hands its
  192. ``HERMES_DESKTOP_DEV_SERVER`` down to the backend it spawns, and worktree-ui-dev.md's ``hgui``
  193. slots run that renderer on 5174+N."""
  194. loopback = _loopback_origin(origin)
  195. if loopback is None:
  196. return False
  197. if loopback[2] == getattr(state, "bound_port", None):
  198. return True
  199. if loopback in (getattr(state, "trusted_public_origins", None) or frozenset()):
  200. return True
  201. return _loopback_origin(os.environ.get("HERMES_DESKTOP_DEV_SERVER", "")) == loopback
  202. def ws_host_origin_reason(ws, state) -> Optional[str]:
  203. """``host_mismatch …`` / ``origin_mismatch …`` under listener *state*, or None when allowed.
  204. HTTP middleware does not run for WebSocket routes, so the DNS-rebinding
  205. Host check is repeated here; an Origin header, when present, must target the
  206. bound host. Non-web origins (packaged Electron: file://, null, app://) are
  207. trusted — the credential check is the real auth boundary there.
  208. """
  209. bound_host = getattr(state, "bound_host", None)
  210. if not bound_host:
  211. return None
  212. trusted_public_hosts = getattr(state, "trusted_public_hosts", frozenset())
  213. host_header = ws.headers.get("host", "")
  214. if not _is_accepted_host(host_header, bound_host, trusted_public_hosts):
  215. return f"host_mismatch host={host_header or '?'} bound={bound_host}"
  216. origin = ws.headers.get("origin", "")
  217. if not origin:
  218. return None
  219. try:
  220. parsed = urllib.parse.urlparse(origin)
  221. except ValueError: # malformed authority, e.g. "http://[::1" — fail closed
  222. parsed = None
  223. if parsed is not None and parsed.scheme not in {"http", "https"}:
  224. return None
  225. if parsed is None or not parsed.netloc or not _is_accepted_host(parsed.netloc, bound_host, trusted_public_hosts):
  226. return f"origin_mismatch origin={origin} bound={bound_host}"
  227. # _is_accepted_host drops the port: a page on ANOTHER loopback port is a different origin, the
  228. # same one CORS refuses — without this it opens /api/pty with a token it read off index.html.
  229. # An Origin naming the very authority the upgrade targets is this server's own page reached
  230. # through a port forward (``ssh -L 8000:localhost:9119``, ``docker -p 8080:9119``): same-origin
  231. # by definition, and a page on another port cannot make the two match.
  232. if (parsed.hostname in _LOOPBACK_HOST_VALUES and parsed.netloc.lower() != host_header.strip().lower()
  233. and not is_trusted_local_origin(origin, state)):
  234. return f"origin_mismatch origin={origin} bound={bound_host}"
  235. return None