diff --git a/hermes_cli/web_server.py b/hermes_cli/web_server.py index 8528ced952..ce54ffbf7b 100644 --- a/hermes_cli/web_server.py +++ b/hermes_cli/web_server.py @@ -17908,6 +17908,32 @@ def mount_spa(application: FastAPI): @application.get("/{full_path:path}") async def no_frontend(full_path: str): + # Desktop token handshake (#94227): the Electron shell boots by + # fetching `/` and extracting ``window.__HERMES_SESSION_TOKEN__`` + # for /api/ws auth (apps/desktop/electron/dashboard-token.ts). + # When headless serve 404'd every path, a renderer whose spawn + # token no longer matched the backend's live token (e.g. after + # `hermes update` replaced the backend) had no way to adopt the + # served token — the WS handshake failed and the window + # white-screened (#95575). Serve a minimal token-only page at the + # exact root, but ONLY when the dashboard auth gate is off: on a + # gated (non-loopback/remote) serve the token must never be + # readable without auth, so the 404 JSON stays. + gated = bool(getattr(application.state, "auth_required", False)) + if full_path == "" and not gated: + token_js = json.dumps(_SESSION_TOKEN) + return HTMLResponse( + "" + "Headless backend (hermes serve): web UI disabled — use " + "`hermes dashboard` for the browser UI." + "", + headers={ + "Cache-Control": "no-store, no-cache, must-revalidate" + }, + ) return JSONResponse({"error": _msg}, status_code=404) return diff --git a/tests/hermes_cli/test_web_server.py b/tests/hermes_cli/test_web_server.py index 2002fa1615..d7b6360898 100644 --- a/tests/hermes_cli/test_web_server.py +++ b/tests/hermes_cli/test_web_server.py @@ -4859,6 +4859,66 @@ class TestServeIndexMissingIndex: assert "SPA-rebuilt" in resp.text +class TestHeadlessServeTokenPage: + """Headless `hermes serve` must serve the Desktop token handshake page + at `/` when the dashboard auth gate is off (#94227). + + The Electron renderer boots by fetching `/` and extracting + ``window.__HERMES_SESSION_TOKEN__`` for WebSocket auth. Headless serve + used to 404 every path, so after an update replaced the backend (and + the spawn-token env pin no longer matched the token the new backend + generated) the renderer was stuck with a stale token, /api/ws rejected + it, and the window white-screened (#95575). + """ + + @staticmethod + def _headless_client(monkeypatch, *, gated: bool): + from fastapi import FastAPI + from starlette.testclient import TestClient + import hermes_cli.web_server as ws + + monkeypatch.setenv("HERMES_SERVE_HEADLESS", "1") + spa_app = FastAPI() + spa_app.state.auth_required = gated + ws.mount_spa(spa_app) + return TestClient(spa_app), ws + + def test_root_serves_token_page_when_not_gated(self, monkeypatch): + import re + + client, ws = self._headless_client(monkeypatch, gated=False) + resp = client.get("/") + assert resp.status_code == 200 + assert resp.headers["content-type"].startswith("text/html") + assert "no-store" in resp.headers.get("cache-control", "") + # Must match the desktop's extraction regex exactly + # (apps/desktop/electron/dashboard-token.ts). + match = re.search( + r'window\.__HERMES_SESSION_TOKEN__\s*=\s*("(?:\\.|[^"\\])*")', + resp.text, + ) + assert match, resp.text + import json as _json + + assert _json.loads(match.group(1)) == ws._SESSION_TOKEN + assert "window.__HERMES_AUTH_REQUIRED__=false" in resp.text + + def test_root_stays_404_json_when_auth_gated(self, monkeypatch): + client, ws = self._headless_client(monkeypatch, gated=True) + resp = client.get("/") + assert resp.status_code == 404 + assert "web UI disabled" in resp.json()["error"] + assert ws._SESSION_TOKEN not in resp.text + + def test_non_root_paths_stay_404_json(self, monkeypatch): + client, ws = self._headless_client(monkeypatch, gated=False) + for route in ("/chat", "/api/status-page", "/assets/index-abc.js"): + resp = client.get(route) + assert resp.status_code == 404 + assert "web UI disabled" in resp.json()["error"] + assert ws._SESSION_TOKEN not in resp.text + + class TestHashedAssetCacheHeaders: """Hashed /assets/* responses must be immutable-cacheable; index.html must stay no-store so it always references the current hashes