Skip to content

The agent that grows with you

fix(webapp): on the LAN, open the address Web Access registered Nous sign-in for

emozillae77feea88de4
diff --git a/gateway/webapp_listener.py b/gateway/webapp_listener.py
index 2c9e7856ff5..780e1d88f31 100644
--- a/gateway/webapp_listener.py
+++ b/gateway/webapp_listener.py
@@ -315,10 +315,14 @@ def register_control_verbs(runner, home) -> None:
from hermes_cli.web_server_surface import private_launch
if not private_launch(web.app.state):
# Behind the dashboard's sign-in the page asks for it; a launch link opens only a private Webapp.
- # With webapp.public_url set (the listener's own public URL), sign-in returns to a callback on
- # that URL and checks a state cookie set where it started, so the browser starts there too.
+ # Sign-in returns to a callback the provider must know and checks a state cookie set where it
+ # started, so the browser starts at that callback's origin: webapp.public_url when set (the
+ # listener's own public URL), else on the LAN the address Web Access registered Nous sign-in
+ # for, else the loopback address (a password provider, or sign-in set up by hand for it).
# Native clients keep the loopback address.
- address = getattr(web.app.state, "listener_public_url", "") or status["url"]
+ from hermes_cli.webapp_access import registered_lan_origin
+ address = (getattr(web.app.state, "listener_public_url", "")
+ or registered_lan_origin(home, urlsplit(status["url"]).port) or status["url"])
return {"url": f"{address}/{query}", "private": False, "expires_in_seconds": None, "sign_in": True}
# Where the browser's connection cannot be checked (macOS, the BSDs), the link is for the user to
# open by hand ("private": printed, never passed to a browser launcher), and its ticket spends
diff --git a/hermes_cli/webapp_access.py b/hermes_cli/webapp_access.py
index eeb0284a57e..e4143c1fb78 100644
--- a/hermes_cli/webapp_access.py
+++ b/hermes_cli/webapp_access.py
@@ -95,6 +95,23 @@ def _registered(record: dict) -> bool:
return False
+def registered_lan_origin(home: Path, port: int) -> Optional[str]:
+ """``http://<LAN address>:<port>`` when Web Access last registered Nous sign-in for *home*'s
+ Webapp on the LAN at that address and *port*, and the address is still this machine's; else None.
+ Sign-in returns only to the callback the Portal has, so ``hermes webapp`` opens this address."""
+ try:
+ record = json.loads((Path(home) / _REGISTRATION_PATH).read_text(encoding="utf-8-sig"))
+ parts = urlsplit(record["callback"])
+ recorded_port = parts.port
+ except (OSError, ValueError, KeyError, TypeError, AttributeError):
+ return None
+ if (parts.scheme, parts.path, parts.query, parts.fragment) != ("http", "/auth/callback", "", ""):
+ return None
+ if parts.username is not None or recorded_port != port or parts.hostname != lan_address():
+ return None
+ return f"http://{parts.hostname}:{port}"
+
+
def _register_nous_sign_in(callback_url: str) -> None:
"""Register (or update in place) this home's portal client with *callback_url*, as
``hermes dashboard register --redirect-uri`` does.
diff --git a/tests/gateway/test_webapp_listener.py b/tests/gateway/test_webapp_listener.py
index 71262a331b6..ef719c8154e 100644
--- a/tests/gateway/test_webapp_listener.py
+++ b/tests/gateway/test_webapp_listener.py
@@ -209,6 +209,58 @@ def test_behind_the_dashboard_sign_in_the_launcher_gets_the_webapp_address(monke
assert not getattr(state, "webapp_window_tickets", None)
+LAN = "192.168.1.20"
+
+
+def _lan_webapp(monkeypatch, tmp_path, *, registered=None, address=LAN, public_url=""):
+ """A gateway serving the Webapp on every interface (``webapp.host: 0.0.0.0``) behind the sign-in
+ gate, this machine's LAN address being *address*, after Web Access Start registered Nous sign-in
+ for the callback *registered* (None: never)."""
+ from hermes_cli import webapp_access
+
+ config = "webapp:\n enabled: true\n host: 0.0.0.0\n port: 9555\n"
+ runner, _, home = _start_runtime_api(monkeypatch, tmp_path, config)
+ if registered is not None:
+ record = home / "webapp" / "sign-in-registration.json"
+ record.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+ record.write_text(json.dumps({"portal": "https://portal.example", "client_id": "agent:x",
+ "callback": registered}) + "\n", encoding="utf-8")
+ record.chmod(0o600)
+ monkeypatch.setattr(webapp_access, "lan_address", lambda: address)
+ state = SimpleNamespace(ui_surface="webapp", auth_required=True, **(
+ {"listener_public_url": public_url} if public_url else {}))
+ runner.session_api.app = SimpleNamespace(web=SimpleNamespace(_SESSION_TOKEN="s" * 43, app=SimpleNamespace(state=state)))
+ return runner
+
+
+def test_on_the_lan_the_launcher_opens_the_address_web_access_registered_for_sign_in(monkeypatch, tmp_path):
+ """Nous sign-in returns to the callback Web Access Start registered with the Portal, the LAN
+ address's. Opened at the loopback address, sign-in would send a callback the Portal never saw,
+ so the launcher opens the registered address."""
+ runner = _lan_webapp(monkeypatch, tmp_path, registered=f"http://{LAN}:9555/auth/callback")
+ result = _ask(runner, "webapp-launch", params={"profile": "work"})["result"]
+ assert result == {"url": f"http://{LAN}:9555/?profile=work", "private": False,
+ "expires_in_seconds": None, "sign_in": True}
+
+
[email protected](("registered", "address"), [
+ (None, LAN), # set up by hand: a password provider, or a client registered for this address
+ (f"http://{LAN}:9120/auth/callback", LAN), # registered before webapp.port changed
+ (f"http://{LAN}:9555/auth/callback", "192.168.1.77"), # this machine's LAN address changed since
+ ("https://webapp.example.net/auth/callback", LAN), # registered for a public URL no longer set
+])
+def test_on_the_lan_without_a_current_registration_the_launcher_opens_the_loopback_address(
+ monkeypatch, tmp_path, registered, address):
+ runner = _lan_webapp(monkeypatch, tmp_path, registered=registered, address=address)
+ assert _ask(runner, "webapp-launch")["result"]["url"] == "http://127.0.0.1:9555/"
+
+
+def test_the_webapps_own_public_url_wins_over_a_lan_registration(monkeypatch, tmp_path):
+ runner = _lan_webapp(monkeypatch, tmp_path, registered=f"http://{LAN}:9555/auth/callback",
+ public_url="https://webapp.example.net")
+ assert _ask(runner, "webapp-launch")["result"]["url"] == "https://webapp.example.net/"
+
+
@pytest.mark.parametrize(("public_url", "params", "opened"), [
("https://webapp.example.net", {}, "https://webapp.example.net/"),
("https://example.net:8443/hermes", {"profile": "work"}, "https://example.net:8443/hermes/?profile=work"),
diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md
index bd470fee0b8..85c88b99b79 100644
--- a/website/docs/reference/cli-commands.md
+++ b/website/docs/reference/cli-commands.md
@@ -1945,8 +1945,11 @@ For a named profile served by the default gateway (`hermes -p work webapp`), the
profile.
Behind the dashboard sign-in gate (`webapp.host: 0.0.0.0` or `::`, or `webapp.public_url` set), the
-command opens the Webapp's address instead of a one-use link (with `webapp.public_url` set, that URL,
-where sign-in returns), and you sign in there with your dashboard account. When the gateway cannot
+command opens the Webapp's address instead of a one-use link, where sign-in returns: with
+`webapp.public_url` set, that URL; on the LAN, the address Web Access Start registered Nous sign-in
+for (`webapp/sign-in-registration.json`), while it is still this machine's LAN address and the
+Webapp's port; otherwise the loopback address, which serves a password provider or sign-in set up by
+hand for it. You sign in there with your dashboard account. When the gateway cannot
serve the Webapp, the command says why; the gateway reads its Webapp settings when it starts, so run
`hermes gateway restart` after fixing the cause. A Webapp bundle that is not built yet is the
exception: this command builds it, and the running gateway serves it at once.
diff --git a/website/docs/user-guide/desktop.md b/website/docs/user-guide/desktop.md
index 1df2cde9d51..7645903c81f 100644
--- a/website/docs/user-guide/desktop.md
+++ b/website/docs/user-guide/desktop.md
@@ -69,10 +69,12 @@ serves share its Webapp; a standalone profile's own gateway serves its own when
[dashboard sign-in gate](./features/web-dashboard.md#authentication-gated-mode) (username and password
for a trusted LAN or VPN, OAuth/OIDC for anything internet-facing). Behind a reverse proxy or tunnel
you run, keep the loopback host and set `webapp.public_url` to the address it serves instead; that
-requires the same sign-in. `hermes webapp` then opens the Webapp's address (`webapp.public_url` when
-set), where you sign in with your dashboard account; one-use links serve only a Webapp that needs no
-sign-in. HTTPS is strongly recommended remotely and browsers require it for some microphone and
-clipboard features.
+requires the same sign-in. `hermes webapp` then opens the Webapp's address, where you sign in with
+your dashboard account: `webapp.public_url` when set; on the LAN, the address **Web Access → Start**
+registered Nous sign-in for, while it is still this machine's address and the Webapp's port; else the
+loopback address (a password provider, or sign-in you set up by hand for that address). One-use
+links serve only a Webapp that needs no sign-in. HTTPS is strongly recommended remotely and browsers
+require it for some microphone and clipboard features.
:::warning Treat Webapp access like access to Hermes on the host
A signed-in Webapp user can run arbitrary commands as the OS account running Hermes, run agent tools,