Skip to content

The agent that grows with you

fix(gateway): the Webapp names a browser credential file it cannot use, and replaces one that is not text

emozilla21fd6dd020ac
diff --git a/gateway/run_api.py b/gateway/run_api.py
index 2ecf286903b..576c13d01ca 100644
--- a/gateway/run_api.py
+++ b/gateway/run_api.py
@@ -73,11 +73,17 @@ class GatewayDashboardMount:
return self.web.app.state if self.web is not None else self._state
def _bind_state(self, web) -> None:
+ webapp = getattr(self._state, "webapp", None)
+ # The browser credential before any app state: one the home cannot store fails the mount
+ # with nothing set, and the gateway falls back to its private listener.
+ token = None
+ if webapp is not None:
+ from gateway.webapp_listener import browser_session_token
+ token = browser_session_token(webapp.home)
# Local clients authenticate with tickets minted on the owner-only control socket. The SPA
# session token is a bearer credential any loopback peer (any OS user) could read from
# GET /, so the gateway-hosted listener never publishes it.
web.app.state.withhold_session_token = True
- webapp = getattr(self._state, "webapp", None)
own_url = _listener_public_url(webapp)
if own_url is not None:
web.app.state.listener_public_url = own_url
@@ -95,12 +101,11 @@ class GatewayDashboardMount:
# The browser-hosted Desktop: its bundle at /, its routes (launch handoff, socket tickets,
# host terminal) on, and the browser credential kept in the home so tabs survive a restart.
# The page itself still never carries the credential (the webapp surface withholds it).
- from gateway.webapp_listener import browser_session_token
web.app.state.ui_surface = "webapp"
web.app.state.web_dist = webapp.dist
web.app.state.webapp_home = webapp.home
self._replaced_session_token = web._SESSION_TOKEN
- web._SESSION_TOKEN = browser_session_token(webapp.home)
+ web._SESSION_TOKEN = token
def _unbind_state(self) -> None:
undo_own_sign_in, self._undo_own_sign_in = self._undo_own_sign_in, None
@@ -139,8 +144,9 @@ class GatewayDashboardMount:
if getattr(web.app.state, "gateway_runner", None) not in (None, self.runner):
raise RuntimeError("gateway API already started")
try:
- # Binding may fail too (the Webapp's browser credential cannot be read or written);
- # its app state and swapped session token roll back with a failed lifespan's.
+ # A bind that fails partway (the auth gate refusing a gated bind, or the Webapp's
+ # browser credential that cannot be read or written) is undone like a failed lifespan:
+ # the listener the gateway falls back to finds the app as main's does.
self._bind_state(web)
lifespan = web.app.router.lifespan_context(web.app)
await lifespan.__aenter__()
diff --git a/gateway/run_runtime.py b/gateway/run_runtime.py
index f705bf013e3..1ef7f38c985 100644
--- a/gateway/run_runtime.py
+++ b/gateway/run_runtime.py
@@ -496,7 +496,9 @@ async def recover_bot_mailbox(authority):
async def start_gateway_runtime_api(runner):
from gateway import run_api
- from gateway.webapp_listener import browser_session_token, dial_origin, listener_plan, register_control_verbs
+ from gateway.webapp_listener import (
+ BrowserCredentialError, browser_session_token, dial_origin, listener_plan, register_control_verbs,
+ )
from hermes_constants import get_hermes_home
home = get_hermes_home()
host, port, webapp, unusable = listener_plan(home)
@@ -510,11 +512,14 @@ async def start_gateway_runtime_api(runner):
except (Exception, SystemExit) as exc:
if webapp is None:
raise
- # The Webapp's listener could not start (port taken, address unavailable, or the dashboard's
- # auth gate exiting on a wildcard bind with no sign-in provider): native clients still need
- # this gateway, so it keeps main's private listener and reports why the Webapp is not served.
+ # The Webapp's listener could not start (port taken, address unavailable, its browser credential
+ # not storable in the home, or the dashboard's auth gate exiting on a wildcard bind with no
+ # sign-in provider): native clients still need this gateway, so it keeps main's private
+ # listener and reports why the Webapp is not served.
if isinstance(exc, SystemExit):
reason = str(exc.code).strip() # the gate's own message names the fix
+ elif isinstance(exc, BrowserCredentialError):
+ reason = str(exc) # names the file and why it cannot be stored
elif isinstance(exc, OSError) and exc.filename: # the browser credential's file, not the port
reason = f"could not use {exc.filename} ({exc.strerror or exc})"
else:
diff --git a/gateway/webapp_listener.py b/gateway/webapp_listener.py
index fb53a45c0cf..acbc9ee1e9e 100644
--- a/gateway/webapp_listener.py
+++ b/gateway/webapp_listener.py
@@ -222,11 +222,17 @@ def use_own_sign_in(webapp: WebappMount):
return None if client is None else listener_client.use(*client)
+class BrowserCredentialError(OSError):
+ """The Webapp's browser credential cannot be stored in the home; ``str()`` names the file and why."""
+
+
def browser_session_token(home, *, rotate: bool = False) -> str:
"""The dashboard session token a Webapp browser holds, kept user-only in *home*.
- Created on first use; *rotate* replaces it, which signs every open tab out. A stored token other
- users could read is replaced the same way, and its folder is closed to them again (POSIX)."""
+ Created on first use; *rotate* replaces it, which signs every open tab out. A stored token that
+ cannot be read, is not text or is malformed, or that other users could read, is replaced the same
+ way, and its folder is closed to them again (POSIX). Raises :class:`BrowserCredentialError` when
+ no token can be written there."""
from utils import atomic_write_text
path = Path(home) / TOKEN_PATH
@@ -234,13 +240,17 @@ def browser_session_token(home, *, rotate: bool = False) -> str:
if not rotate:
try:
token = path.read_text(encoding="utf-8-sig").strip()
- except OSError:
+ except (OSError, ValueError): # missing, unreadable or not UTF-8: replaced below
token = ""
if _TOKEN_FORMAT.fullmatch(token) and not _readable_by_other_users(path):
return token
token = secrets.token_urlsafe(32)
- path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
- atomic_write_text(path, token + "\n", mode=0o600)
+ try:
+ path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+ atomic_write_text(path, token + "\n", mode=0o600)
+ except OSError as exc:
+ raise BrowserCredentialError(
+ f"could not store the Webapp's browser credential in {path} ({exc.strerror or exc})") from exc
return token
diff --git a/hermes_cli/webapp_launcher.py b/hermes_cli/webapp_launcher.py
index 023a6028b2b..03fa1214df1 100644
--- a/hermes_cli/webapp_launcher.py
+++ b/hermes_cli/webapp_launcher.py
@@ -158,7 +158,7 @@ def _signed_out_summary(result: dict) -> str:
def _sign_out(target: Path) -> int:
- from gateway.webapp_listener import browser_session_token
+ from gateway.webapp_listener import BrowserCredentialError, browser_session_token
for attempt in range(_START_WAIT_ATTEMPTS + 1):
try:
response = _control(target, "webapp-sign-out")
@@ -171,7 +171,11 @@ def _sign_out(target: Path) -> int:
if response is None and state == "absent":
# No gateway is running: replace the stored credential so no browser can use the old one
# when one starts. Behind the sign-in gate, logins bound to it end too.
- browser_session_token(target, rotate=True)
+ try:
+ browser_session_token(target, rotate=True)
+ except BrowserCredentialError as exc:
+ print(f"Nobody was signed out: {exc}")
+ return 1
print("No gateway is running for this profile. Replaced the stored Webapp credential: every browser "
"must sign in again when the gateway next serves the Webapp.")
return 0
diff --git a/tests/gateway/fixtures/webapp_fallback_peer.py b/tests/gateway/fixtures/webapp_fallback_peer.py
index d5d45f4b2f1..0f1c14356fb 100644
--- a/tests/gateway/fixtures/webapp_fallback_peer.py
+++ b/tests/gateway/fixtures/webapp_fallback_peer.py
@@ -16,7 +16,11 @@ Run as ``python webapp_fallback_peer.py '<spec json>'`` with an isolated ``HERME
- ``built``: whether the Webapp bundle has its ``index.html``;
- ``update_fails``: before the gateway starts, ``hermes update``'s Webapp step runs for this home and its
build fails; once the gateway serves, ``hermes webapp``'s build succeeds;
-- ``probe_host``: a Host header to send (a public hostname), or null.
+- ``probe_host``: a Host header to send (a public hostname), or null;
+- ``credential``: the stored browser credential this gateway finds: ``"folder-is-a-file"`` (a plain
+ file where the ``webapp/`` folder goes), ``"token-is-a-folder"`` (a folder where
+ ``webapp/session-token`` goes), ``"not-utf8"`` (the token saved as UTF-16), or null for a
+ readable token an earlier gateway stored.
Writes ``receipt.json`` into ``HERMES_HOME`` (the gateway redirects stdout). No inference: the model points
at a closed port and no turn is submitted. Tests start it with :func:`run`.
@@ -75,6 +79,32 @@ def _config(spec) -> str:
return json.dumps(document, indent=2) # JSON is YAML
+def _seed_credential(home, kind):
+ """The browser credential an earlier gateway stored, or (*kind*) one this gateway cannot use."""
+ folder = home / "webapp"
+ if kind == "folder-is-a-file":
+ folder.write_text("not a folder\n", encoding="utf-8")
+ return
+ # Seeded user-only, as the gateway writes it: a stored token other users can read is replaced.
+ folder.mkdir(mode=0o700, exist_ok=True)
+ token = folder / "session-token"
+ if kind == "token-is-a-folder":
+ token.mkdir()
+ elif kind == "not-utf8":
+ token.write_bytes((SEEDED_TOKEN + "\n").encode("utf-16"))
+ else:
+ token.write_text(SEEDED_TOKEN + "\n", encoding="utf-8")
+ token.chmod(0o600)
+
+
+def _stored_token(home):
+ """The browser credential stored in *home*, or None when it cannot be read as text."""
+ try:
+ return (home / "webapp" / "session-token").read_text(encoding="utf-8").strip()
+ except (OSError, ValueError):
+ return None
+
+
def _fail_startup_once():
"""The listener's first startup raises the error a lost listen() race gives."""
import uvicorn
@@ -147,10 +177,7 @@ def _mounted_state(home):
if web is None:
return {"mounted": False}
state = web.app.state
- try:
- stored = (home / "webapp" / "session-token").read_text(encoding="utf-8").strip()
- except OSError:
- stored = ""
+ stored = _stored_token(home)
return {
"mounted": True,
"surface": getattr(state, "ui_surface", "<absent>"),
@@ -187,13 +214,8 @@ async def probe(spec):
home = Path(os.environ["HERMES_HOME"])
(home / "config.yaml").write_text(_config(spec), encoding="utf-8")
- # Seeded user-only, as the gateway writes it: a stored token other users can read is replaced.
- if spec.get("credential_unusable"):
- (home / "webapp").write_text("not a folder\n", encoding="utf-8")
- else:
- (home / "webapp").mkdir(mode=0o700, exist_ok=True)
- (home / "webapp" / "session-token").write_text(SEEDED_TOKEN + "\n", encoding="utf-8")
- (home / "webapp" / "session-token").chmod(0o600)
+ # A file where the folder belongs (``credential_unusable``) is the ``folder-is-a-file`` case.
+ _seed_credential(home, "folder-is-a-file" if spec.get("credential_unusable") else spec.get("credential"))
dist = home.parent / "dist-webapp"
dist.mkdir(exist_ok=True)
if spec.get("built", True):
@@ -284,8 +306,7 @@ async def probe(spec):
built = await client.get("/")
report["index_once_built"] = {"status": built.status_code,
"is_webapp": "WEBAPP_BUNDLE rebuilt" in built.text}
- if not spec.get("credential_unusable"):
- report["token_rotated"] = (home / "webapp" / "session-token").read_text().strip() != SEEDED_TOKEN
+ report["token_rotated"] = _stored_token(home) != SEEDED_TOKEN
finally:
await stop_gateway_api(api)
if rival is not None:
diff --git a/tests/gateway/test_webapp_browser_credential.py b/tests/gateway/test_webapp_browser_credential.py
index 3208e912747..417c7f23990 100644
--- a/tests/gateway/test_webapp_browser_credential.py
+++ b/tests/gateway/test_webapp_browser_credential.py
@@ -62,6 +62,32 @@ def test_a_private_credential_is_reused(tmp_path):
assert webapp.browser_session_token(tmp_path) == first
+def test_a_credential_file_that_is_not_text_is_replaced(tmp_path):
+ """A token file that is not UTF-8 (saved as UTF-16 by an editor, damaged on disk) is corrupt: it is
+ replaced like a malformed one, never raised to the gateway mounting the Webapp."""
+ path = tmp_path / webapp.TOKEN_PATH
+ path.parent.mkdir(parents=True)
+ path.write_bytes((STORED + "\n").encode("utf-16"))
+ token = webapp.browser_session_token(tmp_path)
+ assert token != STORED
+ assert path.read_text(encoding="utf-8").strip() == token
+
+
[email protected]("block", ["folder-is-a-file", "token-is-a-folder"])
+def test_a_credential_that_cannot_be_stored_names_its_file(tmp_path, block):
+ """A credential that can be neither read nor written (a stray file or folder at its path, a folder
+ another user owns, a full or read-only home) raises an OSError that names the file, so the gateway
+ reports that file as why the Webapp is unavailable."""
+ if block == "folder-is-a-file":
+ (tmp_path / "webapp").write_text("not a folder\n", encoding="utf-8")
+ else:
+ (tmp_path / webapp.TOKEN_PATH).mkdir(parents=True)
+ with pytest.raises(webapp.BrowserCredentialError) as raised:
+ webapp.browser_session_token(tmp_path)
+ assert isinstance(raised.value, OSError)
+ assert str(tmp_path / webapp.TOKEN_PATH) in str(raised.value)
+
+
@pytest.mark.parametrize("status", [
{"state": "off", "url": None, "reason": None},
{"state": "unavailable", "url": None, "reason": "could not listen on 127.0.0.1:9120 (in use)"},
diff --git a/tests/gateway/test_webapp_listener_fallback.py b/tests/gateway/test_webapp_listener_fallback.py
index d5d962074ad..5981f887c86 100644
--- a/tests/gateway/test_webapp_listener_fallback.py
+++ b/tests/gateway/test_webapp_listener_fallback.py
@@ -1,10 +1,11 @@
"""The gateway keeps a listener for native clients whatever happens to the Webapp's.
When the Webapp's listener cannot start, even after its dashboard mount is up (another process won the
-race to listen on the port), the gateway comes up on main's private loopback listener instead: native
-Desktop, CLI and TUI clients still connect, the mount carries none of the Webapp's state, and
-``hermes webapp --status`` says why the Webapp is not served. Each case runs a real gateway listener
-in a child process (``fixtures/webapp_fallback_peer.py``) with its own ``HERMES_HOME``.
+race to listen on the port, or the browser credential in the home cannot be read or written), the
+gateway comes up on main's private loopback listener instead: native Desktop, CLI and TUI clients still
+connect, the mount carries none of the Webapp's state, and ``hermes webapp --status`` says why the
+Webapp is not served. Each case runs a real gateway listener in a child process
+(``fixtures/webapp_fallback_peer.py``) with its own ``HERMES_HOME``.
"""
import ipaddress
from urllib.parse import urlsplit
@@ -53,6 +54,41 @@ def test_a_webapp_that_loses_its_port_replaces_the_browser_credential(lost_liste
assert held["token_rotated"] is True
[email protected](scope="module", params=["folder-is-a-file", "token-is-a-folder"])
+def unusable_credential(request, tmp_path_factory):
+ spec = {"webapp": {"enabled": True, "port": _free_port()}, "credential": request.param}
+ return _run(tmp_path_factory.mktemp(request.param), spec)
+
+
+def test_a_browser_credential_that_cannot_be_stored_leaves_native_clients_mains_listener(unusable_credential):
+ """A Webapp whose browser credential cannot be read or written (a stray file or folder at its path, a
+ folder another user owns, a full or read-only home) is unavailable, and the gateway still starts on
+ main's private listener with none of the Webapp's state, as for a taken port."""
+ report = unusable_credential
+ assert report["start_error"] is None, report.get("start_traceback")
+ assert report["native_session_list"] is True
+ assert report["status"]["state"] == "unavailable"
+ assert report["state"]["surface"] == "<absent>"
+ assert report["state"]["web_dist_set"] is False
+ assert "WEBAPP_BUNDLE" not in report["index"]["body"]
+
+
+def test_a_browser_credential_that_cannot_be_stored_is_the_reason_given(unusable_credential):
+ """The reason ``hermes webapp --status`` prints names the credential file, not the port."""
+ reason = unusable_credential["status"]["reason"]
+ assert "could not listen" not in reason, reason
+ assert "session-token" in reason and "credential" in reason, reason
+
+
+def test_a_browser_credential_that_is_not_text_is_replaced_and_served(tmp_path):
+ """A token file that is not UTF-8 (saved as UTF-16 by an editor, damaged on disk) is a corrupt
+ credential: like a malformed one it is replaced, and the Webapp is served with the new one."""
+ report = _run(tmp_path, {"webapp": {"enabled": True, "port": _free_port()}, "credential": "not-utf8"})
+ assert report["start_error"] is None, report.get("start_traceback")
+ assert report["status"]["state"] == "serving"
+ assert report["state"]["session_token_is_browser_credential"] is True
+
+
def test_a_webapp_that_starts_keeps_the_browser_credential(tmp_path):
report = _run(tmp_path, {"webapp": {"enabled": True, "port": _free_port()}})
assert report["status"]["state"] == "serving"
diff --git a/tests/hermes_cli/test_webapp_launcher.py b/tests/hermes_cli/test_webapp_launcher.py
index af4e4810f71..ee195df4edd 100644
--- a/tests/hermes_cli/test_webapp_launcher.py
+++ b/tests/hermes_cli/test_webapp_launcher.py
@@ -255,6 +255,18 @@ def test_signing_out_with_no_gateway_running_still_replaces_the_stored_credentia
assert "No gateway is running" in out and "sign in again" in out
+def test_signing_out_with_no_gateway_and_a_credential_that_cannot_be_stored_says_nobody_was(world, capsys):
+ """With no gateway running, sign-out replaces the stored credential itself. When the home cannot
+ store one (a stray file where its folder goes, a folder another user owns), it says nobody was
+ signed out and names the file."""
+ from gateway.webapp_listener import TOKEN_PATH
+ (world["root"] / "webapp").write_text("not a folder\n", encoding="utf-8")
+ world["answers"]["webapp-sign-out"] = launcher.GatewayUnreachable("no gateway")
+ assert launcher.cmd_webapp(_args(sign_out=True)) == 1
+ out = capsys.readouterr().out
+ assert "Nobody was signed out" in out and str(world["root"] / TOKEN_PATH) in out
+
+
STARTING = {"ok": False, "error": "unknown verb: 'webapp-sign-out'"} # its verbs register once it is up
SIGNED_OUT = {"ok": True, "result": {"signed_out": True, "serving": True, "sign_in_gate": False,
"connections_closed": 1}}