Skip to content

The agent that grows with you

fix(webapp): print a one-use link on macOS instead of the long-lived browser credential

emozillab140bf4039bf
diff --git a/gateway/webapp_listener.py b/gateway/webapp_listener.py
index e837123a8f4..2c9e7856ff5 100644
--- a/gateway/webapp_listener.py
+++ b/gateway/webapp_listener.py
@@ -242,10 +242,11 @@ def _close_to_other_users(folder: Path) -> None:
def _one_use_links_work() -> bool:
- """Whether a browser can redeem a one-use launch link here. Redemption needs proof that the
- browser's connection belongs to the gateway's OS user (``web_routers.webapp._peer_is_server_user``)
- on Linux, or a browser launcher whose arguments other users cannot read (Windows). macOS and the
- BSDs offer neither."""
+ """Whether a browser the server opens can redeem a one-use launch link here. Redemption needs
+ proof that the browser's connection belongs to the gateway's OS user
+ (``web_routers.webapp._peer_is_server_user``) on Linux, or a browser launcher whose arguments other
+ users cannot read (Windows). macOS and the BSDs offer neither, so there the link is printed for
+ the user to open by hand and spends without that proof."""
return sys.platform in ("linux", "win32")
@@ -270,8 +271,8 @@ def _bundle_missing(web) -> str | None:
def register_control_verbs(runner, home) -> None:
"""The private control-socket verbs ``hermes webapp`` uses; only an authenticated same-user peer
reaches them. ``webapp-launch`` returns a one-use launch link, so the credential crosses neither
- the socket nor a browser's argv; where such a link cannot be redeemed (macOS) it returns the
- private credential link instead, for the user to open by hand. ``webapp-sign-out`` replaces the
+ the socket nor a browser's argv; where nothing can check who redeems such a link (macOS) it is
+ marked private, for the user to open by hand. ``webapp-sign-out`` replaces the
browser credential, which also ends every login bound to it behind the sign-in gate, closes the
browser sockets those opened, and reports how many it closed."""
server = getattr(runner, "session_control_server", None)
@@ -300,7 +301,8 @@ def register_control_verbs(runner, home) -> None:
def webapp_launch(params, _peer):
from urllib.parse import urlencode
- from hermes_cli.web_routers.webapp import LAUNCH_TICKET_TTL_SECONDS, mint_launch_ticket
+ from hermes_cli.web_routers.webapp import (
+ LAUNCH_TICKET_TTL_SECONDS, mint_launch_ticket, mint_printed_launch_ticket)
from hermes_constants import PROFILE_ID_RE
profile = params.get("profile")
if profile is not None and not (isinstance(profile, str) and PROFILE_ID_RE.match(profile)):
@@ -318,11 +320,13 @@ def register_control_verbs(runner, home) -> None:
# Native clients keep the loopback address.
address = getattr(web.app.state, "listener_public_url", "") or status["url"]
return {"url": f"{address}/{query}", "private": False, "expires_in_seconds": None, "sign_in": True}
- if not _one_use_links_work():
- return {"url": f"{status['url']}/{query}#hermes-session={web._SESSION_TOKEN}", "private": True,
- "expires_in_seconds": None}
- fragment = urlencode({"ticket": mint_launch_ticket(web.app.state), **({"query": query} if query else {})})
- return {"url": f"{status['url']}/webapp/launch#{fragment}", "private": False,
+ # 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
+ # without that check. Either way it works once, for 60 seconds, and carries no lasting credential.
+ checked = _one_use_links_work()
+ ticket = mint_launch_ticket(web.app.state) if checked else mint_printed_launch_ticket(web.app.state)
+ fragment = urlencode({"ticket": ticket, **({"query": query} if query else {})})
+ return {"url": f"{status['url']}/webapp/launch#{fragment}", "private": not checked,
"expires_in_seconds": LAUNCH_TICKET_TTL_SECONDS}
def webapp_sign_out(_params, _peer):
diff --git a/hermes_cli/web_routers/webapp.py b/hermes_cli/web_routers/webapp.py
index e35656e43de..8a77dca3502 100644
--- a/hermes_cli/web_routers/webapp.py
+++ b/hermes_cli/web_routers/webapp.py
@@ -82,6 +82,13 @@ def mint_launch_ticket(state) -> str:
return _mint_handoff_ticket(state, LAUNCH_TICKET_TTL_SECONDS, launch=True)
+def mint_printed_launch_ticket(state) -> str:
+ """Ticket for a launch link the user opens by hand where nothing identifies the redeeming
+ connection's owner (macOS, the BSDs): it spends without that check, as a window ticket does, so
+ ``hermes webapp`` prints it and never passes it to a browser launcher."""
+ return _mint_handoff_ticket(state, LAUNCH_TICKET_TTL_SECONDS, launch=False)
+
+
def _loopback_peer_uid(client: tuple[str, int], server: tuple[str, int]) -> int | None:
"""Owner UID of the client end of a local TCP connection, from Linux ``/proc/net/tcp*``.
@@ -128,7 +135,8 @@ def _peer_is_server_user(request: Request) -> bool:
where the launch ticket travels, is readable only by its own user, SYSTEM and elevated
administrators. Elsewhere (macOS, the BSDs) every local user can read the launcher's argv
and nothing here identifies the connection's owner, so an argv-carried launch ticket cannot
- be redeemed. Authenticated child-window tickets do not use this launcher channel.
+ be redeemed. Authenticated child-window tickets and the launch tickets ``hermes webapp`` prints for
+ the user to open by hand (``mint_printed_launch_ticket``) do not use this launcher channel.
"""
if sys.platform == "win32":
return True
diff --git a/hermes_cli/webapp_launcher.py b/hermes_cli/webapp_launcher.py
index 78544e5a02e..e5e09316285 100644
--- a/hermes_cli/webapp_launcher.py
+++ b/hermes_cli/webapp_launcher.py
@@ -3,8 +3,8 @@
The gateway serves the Webapp on its own listener when its home's config sets ``webapp.enabled``
(``gateway.webapp_listener``). This command builds the bundle when it is stale, starts the gateway that
serves the current profile, asks it for a one-use launch link over the control socket (same OS user
-only) and opens that link, so the credential appears in no argv, output or link. On macOS and the
-BSDs, where a one-use link cannot be redeemed, it prints the gateway's private link for the user to open instead.
+only) and opens that link, so the credential appears in no argv, output or link. On macOS and the BSDs,
+where nothing checks who redeems the link, it prints the one-use link for the user to open instead.
``--status`` and ``--sign-out`` talk to a running gateway and never start one.
"""
from __future__ import annotations
@@ -251,9 +251,10 @@ def cmd_webapp(args) -> int:
print(f"Open the Webapp and sign in with your dashboard account: {link['url']}")
return 0
if link.get("private"):
- # The gateway's own credential (macOS, the BSDs: a one-use link cannot be redeemed): for the user
- # to open, never for a browser launcher whose arguments other processes can read.
- print("Open this link in your browser. It signs the browser in as you, so keep it private:")
+ # macOS, the BSDs: nothing checks who redeems this one-use link, so it is for the user to
+ # open, never for a browser launcher whose arguments other processes can read.
+ print(f"Open this link in your browser within {link['expires_in_seconds']} seconds. It works "
+ "once and signs the browser in as you, so keep it private:")
print(f" {link['url']}")
return 0
if not args.no_open and _open(link["url"]):
diff --git a/tests/gateway/test_webapp_listener.py b/tests/gateway/test_webapp_listener.py
index 7c62b7a1aea..71262a331b6 100644
--- a/tests/gateway/test_webapp_listener.py
+++ b/tests/gateway/test_webapp_listener.py
@@ -176,16 +176,25 @@ def test_webapp_verbs_answer_only_an_authenticated_same_user_peer(monkeypatch, t
assert refused["ok"] is False and "PermissionError" in refused["error"]
-def test_where_one_use_links_cannot_be_redeemed_the_launcher_gets_the_private_link(monkeypatch, tmp_path):
+def test_where_one_use_links_cannot_be_checked_the_launcher_gets_one_to_open_by_hand(monkeypatch, tmp_path):
+ """Where the server cannot tell who redeems a launch link (macOS, the BSDs), the launcher still gets
+ a one-use link that lasts 60 seconds, never the long-lived browser credential: it spends without a
+ peer check, as a window ticket does, and the launcher prints it rather than opening it."""
+ from urllib.parse import parse_qs
+
monkeypatch.setattr(webapp, "_one_use_links_work", lambda: False) # macOS
runner, _, _ = _start_runtime_api(monkeypatch, tmp_path, "webapp:\n enabled: true\n port: 9555\n")
# The gateway mounts the dashboard app as the Webapp surface on a private (loopback) listener.
web = SimpleNamespace(_SESSION_TOKEN="s" * 43, app=SimpleNamespace(state=SimpleNamespace(ui_surface="webapp")))
runner.session_api.app = SimpleNamespace(web=web)
result = _ask(runner, "webapp-launch")["result"]
- assert result == {"url": "http://127.0.0.1:9555/#hermes-session=" + "s" * 43, "private": True,
- "expires_in_seconds": None}
- assert not getattr(web.app.state, "webapp_window_tickets", None)
+ page, fragment = result["url"].split("#", 1)
+ assert page == "http://127.0.0.1:9555/webapp/launch"
+ assert (result["private"], result["expires_in_seconds"]) == (True, 60)
+ assert "s" * 43 not in result["url"] and "hermes-session" not in result["url"]
+ [ticket] = parse_qs(fragment)["ticket"]
+ _expires, _token, peer_checked = web.app.state.webapp_window_tickets[ticket]
+ assert peer_checked is False
def test_behind_the_dashboard_sign_in_the_launcher_gets_the_webapp_address(monkeypatch, tmp_path):
@@ -230,13 +239,12 @@ def _serving_runner(monkeypatch, tmp_path):
def test_a_launch_link_for_a_named_profile_opens_that_profile(monkeypatch, tmp_path):
from urllib.parse import parse_qs
runner = _serving_runner(monkeypatch, tmp_path)
- url = _ask(runner, "webapp-launch", params={"profile": "work"})["result"]["url"]
- page, fragment = url.split("#", 1)
- assert page == "http://127.0.0.1:9555/webapp/launch"
- assert parse_qs(fragment)["query"] == ["?profile=work"]
- monkeypatch.setattr(webapp, "_one_use_links_work", lambda: False)
- private = _ask(runner, "webapp-launch", params={"profile": "work"})["result"]["url"]
- assert private == "http://127.0.0.1:9555/?profile=work#hermes-session=" + "s" * 43
+ for checked in (True, False): # Linux and Windows; macOS and the BSDs
+ monkeypatch.setattr(webapp, "_one_use_links_work", lambda checked=checked: checked)
+ url = _ask(runner, "webapp-launch", params={"profile": "work"})["result"]["url"]
+ page, fragment = url.split("#", 1)
+ assert page == "http://127.0.0.1:9555/webapp/launch"
+ assert parse_qs(fragment)["query"] == ["?profile=work"]
@pytest.mark.parametrize("profile", ["../etc", "a b", "", "x" * 65, 7])
diff --git a/tests/hermes_cli/test_webapp_launch.py b/tests/hermes_cli/test_webapp_launch.py
index 1146141181d..2454a9fb03a 100644
--- a/tests/hermes_cli/test_webapp_launch.py
+++ b/tests/hermes_cli/test_webapp_launch.py
@@ -70,6 +70,40 @@ def test_macos_launch_handoff_fails_closed_without_consuming_child_window_author
client.close()
+def test_a_link_for_the_user_to_open_by_hand_spends_once_without_a_peer_check(monkeypatch):
+ """Where nothing identifies the connection's owner (macOS, the BSDs), ``hermes webapp`` prints a
+ link for the user to open by hand. Its ticket spends without the peer check, once and within 60
+ seconds, as a window ticket does; an argv launch ticket still never spends there."""
+ from types import SimpleNamespace
+
+ from fastapi.testclient import TestClient
+ from hermes_cli import web_server as server
+ from hermes_cli.web_routers import webapp
+
+ monkeypatch.setattr(server.app.state, "ui_surface", "webapp", raising=False)
+ monkeypatch.setattr(server.app.state, "auth_required", False, raising=False)
+ monkeypatch.setattr(server.app.state, "bound_host", "127.0.0.1", raising=False)
+ monkeypatch.setattr(server.app.state, "webapp_window_tickets", {}, raising=False)
+ monkeypatch.setattr(server, "_SESSION_TOKEN", "a" * 43)
+ monkeypatch.setattr(webapp, "_peer_is_server_user", lambda request: False) # macOS
+ client = TestClient(server.app, base_url="http://127.0.0.1")
+
+ def redeem(ticket):
+ return client.post("/webapp/window-session", headers={"Origin": "http://127.0.0.1",
+ "X-Hermes-Window-Ticket": ticket})
+ try:
+ printed = webapp.mint_printed_launch_ticket(server.app.state)
+ assert redeem(printed).json() == {"token": "a" * 43}
+ assert redeem(printed).status_code == 403
+ assert redeem(webapp.mint_launch_ticket(server.app.state)).status_code == 403
+ late = webapp.mint_printed_launch_ticket(server.app.state)
+ now = webapp.time.monotonic()
+ monkeypatch.setattr(webapp, "time", SimpleNamespace(monotonic=lambda: now + webapp.LAUNCH_TICKET_TTL_SECONDS + 1))
+ assert redeem(late).status_code == 403
+ finally:
+ client.close()
+
+
def _loopback_request():
from types import SimpleNamespace
return SimpleNamespace(client=SimpleNamespace(host="127.0.0.1", port=50123),
@@ -79,8 +113,9 @@ def _loopback_request():
@pytest.mark.parametrize("platform", ["freebsd14", "openbsd7", "sunos5"])
def test_where_no_peer_check_exists_a_launch_ticket_is_never_spent(monkeypatch, platform):
"""Other Unixes show every process's argv to all local users by default and Hermes cannot tell
- who owns a loopback connection there. As on macOS, the launcher hands out the private
- credential link rather than a launch ticket, and a launch ticket is never spent."""
+ who owns a loopback connection there. As on macOS, the launcher prints a link for the user to open
+ by hand rather than passing a launch ticket to a browser launcher, and a launch ticket is never
+ spent."""
import sys
from gateway import webapp_listener
diff --git a/tests/hermes_cli/test_webapp_launcher.py b/tests/hermes_cli/test_webapp_launcher.py
index 476f1ef30bb..af4e4810f71 100644
--- a/tests/hermes_cli/test_webapp_launcher.py
+++ b/tests/hermes_cli/test_webapp_launcher.py
@@ -339,11 +339,13 @@ def test_the_webapp_command_takes_one_action_at_a_time():
parser.parse_args(["webapp", *clash])
-def test_a_private_link_is_printed_for_the_user_and_never_handed_to_a_browser_launcher(world, capsys):
- private = "http://127.0.0.1:9120/#hermes-session=" + "s" * 43
- world["answers"]["webapp-launch"] = {"ok": True, "result": {"url": private, "private": True,
- "expires_in_seconds": None}}
+def test_a_link_for_the_user_to_open_by_hand_is_printed_and_never_handed_to_a_browser_launcher(world, capsys):
+ """Where the gateway cannot check who redeems a launch link (macOS, the BSDs) it marks the link
+ private: the command prints it with its lifetime and never passes it to a browser launcher, whose
+ arguments other local users can read."""
+ world["answers"]["webapp-launch"] = {"ok": True, "result": {"url": LINK, "private": True,
+ "expires_in_seconds": 60}}
assert launcher.cmd_webapp(_args()) == 0
assert world["calls"]["opened"] == []
out = capsys.readouterr().out
- assert private in out and "keep it private" in out
+ assert LINK in out and "keep it private" in out and "60 seconds" in out and "once" in out
diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md
index 01f103f4416..bd470fee0b8 100644
--- a/website/docs/reference/cli-commands.md
+++ b/website/docs/reference/cli-commands.md
@@ -1938,8 +1938,8 @@ use. See [Desktop App → Use the Desktop workspace from a browser](../user-guid
The link is valid for 60 seconds and works once; the browser exchanges it for the sign-in it keeps in
that tab. Only your own OS user can get a link: the gateway answers this command over its private
control socket. On macOS and the BSDs, where a one-use link cannot be checked against your OS user,
-the command prints the gateway's private link instead and never passes it to a browser launcher. That
-link signs a browser in as you until you run `hermes webapp --sign-out`; keep it private.
+the command prints the link for you to open and never passes it to a browser launcher. Until it is
+used it signs a browser in as you, so keep it private.
For a named profile served by the default gateway (`hermes -p work webapp`), the Webapp opens on that
profile.
diff --git a/website/docs/user-guide/desktop.md b/website/docs/user-guide/desktop.md
index 8b602f383f2..1df2cde9d51 100644
--- a/website/docs/user-guide/desktop.md
+++ b/website/docs/user-guide/desktop.md
@@ -53,8 +53,9 @@ serves the CLI, the native Desktop and messaging, so every surface sees one conv
keeps in that tab, so reloading keeps you signed in, and so does a gateway restart. A fresh tab or a
bare URL shows instructions instead of access: run `hermes webapp` again for a new link. **New
Window**, profile windows and session pop-outs hand the sign-in over with their own one-use link. On
-macOS and the BSDs the command prints the gateway's private link instead, for you to open; it signs a
-browser in as you until you sign out, so keep it private. `hermes webapp --sign-out` signs out every
+macOS and the BSDs, where Hermes cannot check which OS user's browser opens the link, the command
+prints the one-use link for you to open instead of opening a browser; until it is used it signs a
+browser in as you, so keep it private. `hermes webapp --sign-out` signs out every
tab at once: their open connections close, Bot Desktop viewers included, and each shows the sign-in
instructions. Behind the sign-in gate (below) it also signs out every browser that signed in with a
dashboard account; each must sign in again. The account tokens such a login keeps in its cookies work