Skip to content

The agent that grows with you

fix(webapp): say what plain HTTP loses when the Webapp's address is not secure

unsupportedpastels477937cfb899
diff --git a/hermes_cli/webapp_launcher.py b/hermes_cli/webapp_launcher.py
index c9c47b8b84e..b4b3c403706 100644
--- a/hermes_cli/webapp_launcher.py
+++ b/hermes_cli/webapp_launcher.py
@@ -15,12 +15,14 @@ link for the user to open instead.
from __future__ import annotations
import html
+import ipaddress
import json
import os
import secrets
import sys
import time
from pathlib import Path
+from urllib.parse import urlsplit
RESTART_COMMAND = "hermes gateway restart"
# The gateway reads the Webapp's settings and sign-in providers only when it starts.
@@ -30,6 +32,11 @@ STARTED_BEFORE_ON = f"The gateway started before the Webapp was turned on. Resta
# socket answers, so the gateway running predates them (an upgrade it has not restarted onto).
OLDER_GATEWAY = ("The running gateway is older than the Webapp and does not know its commands. Restart it "
f"onto this version of Hermes: {RESTART_COMMAND}")
+# Browsers keep secure-context APIs (crypto.subtle, mediaDevices, Notification) from a plain-HTTP origin
+# that is not loopback.
+PLAIN_HTTP_NOTE = ("This address is plain HTTP, so the browser turns off what needs a secure connection: the bot "
+ "screen, the microphone (dictation and live voice) and system notifications. Open the Webapp "
+ "over HTTPS (webapp.public_url) or through an SSH tunnel to 127.0.0.1 to use them.")
# How long --sign-out waits for a gateway that is still starting to answer (30 s).
_START_WAIT_ATTEMPTS, _START_WAIT_INTERVAL = 60, 0.5
@@ -181,6 +188,21 @@ def _off_message(target: Path, then: str) -> str:
return f"The Webapp is off. Set webapp.enabled: true in {target / 'config.yaml'}, then {then}."
+def _plain_http_note(url: str) -> str | None:
+ """:data:`PLAIN_HTTP_NOTE` when *url* is plain HTTP on a host other than loopback, else None.
+ Browsers count ``localhost``, ``*.localhost``, 127.0.0.0/8 and ``::1`` as secure contexts."""
+ parts = urlsplit(url)
+ if parts.scheme != "http":
+ return None
+ host = (parts.hostname or "").rstrip(".")
+ if host == "localhost" or host.endswith(".localhost"):
+ return None
+ try:
+ return None if ipaddress.ip_address(host).is_loopback else PLAIN_HTTP_NOTE
+ except ValueError:
+ return PLAIN_HTTP_NOTE
+
+
def _status(target: Path) -> int:
try:
response = _control(target, "webapp-status")
@@ -197,6 +219,8 @@ def _status(target: Path) -> int:
status = response["result"]
if status["state"] == "serving":
print(f"Serving at {status['url']}")
+ if note := _plain_http_note(status["url"]):
+ print(note)
from gateway.webapp_listener import webapp_settings
if not webapp_settings(target).enabled:
print(f"{target / 'config.yaml'} no longer turns the Webapp on: it stops at the next gateway restart "
@@ -345,6 +369,8 @@ def cmd_webapp(args) -> int:
if not response.get("ok"):
return _explain_refused_launch(target, response)
link = response["result"]
+ if note := _plain_http_note(link["url"]):
+ print(note)
if link.get("sign_in"):
# The Webapp is behind the dashboard's sign-in: the page asks for it, so its address is no secret.
if not args.no_open and _open(link["url"]):
diff --git a/tests/hermes_cli/test_webapp_launcher.py b/tests/hermes_cli/test_webapp_launcher.py
index 367868d27b6..c2a51ca806c 100644
--- a/tests/hermes_cli/test_webapp_launcher.py
+++ b/tests/hermes_cli/test_webapp_launcher.py
@@ -426,3 +426,42 @@ def test_a_link_for_the_user_to_open_by_hand_is_printed_and_never_handed_to_a_br
assert all("ticket" not in url for url in world["calls"]["opened"])
out = capsys.readouterr().out
assert LINK in out and "keep it private" in out and "60 seconds" in out and "once" in out
+
+
+def _says_what_plain_http_loses(out: str) -> bool:
+ lowered = out.lower()
+ return all(part in lowered for part in ("plain http", "bot screen", "microphone", "notifications", "https"))
+
+
[email protected]("no_open", [False, True])
+def test_a_webapp_opened_over_plain_http_on_the_lan_says_what_the_browser_loses(world, capsys, no_open):
+ """Browsers keep secure-context features (the bot screen's viewer, the microphone, notifications)
+ from a plain-HTTP origin that is not loopback: the launcher says so wherever it opens or prints one."""
+ url = "http://192.168.1.20:9120/"
+ world["answers"]["webapp-launch"] = {"ok": True, "result": {
+ "url": url, "private": False, "expires_in_seconds": None, "sign_in": True}}
+ assert launcher.cmd_webapp(_args(no_open=no_open)) == 0
+ assert _says_what_plain_http_loses(capsys.readouterr().out)
+
+
+def test_status_of_a_webapp_served_over_plain_http_on_the_lan_says_what_the_browser_loses(world, capsys):
+ world["answers"]["webapp-status"] = {"ok": True, "result": {
+ "state": "serving", "url": "http://10.0.1.170:9120", "reason": None}}
+ assert launcher.cmd_webapp(_args(status=True)) == 0
+ assert _says_what_plain_http_loses(capsys.readouterr().out)
+
+
[email protected]("url", ["http://127.0.0.1:9120/", "http://127.0.0.2:9120/", "http://localhost:9120/",
+ "http://hermes.localhost:9120/", "http://[::1]:9120/",
+ "https://hermes.example.ts.net/"])
+def test_loopback_and_https_addresses_are_secure_contexts_and_get_no_warning(world, capsys, url):
+ world["answers"]["webapp-launch"] = {"ok": True, "result": {
+ "url": url, "private": False, "expires_in_seconds": None, "sign_in": True}}
+ assert launcher.cmd_webapp(_args(no_open=True)) == 0
+ assert "plain http" not in capsys.readouterr().out.lower()
+
+
+def test_a_one_use_link_on_loopback_gets_no_plain_http_warning(world, capsys):
+ assert launcher.cmd_webapp(_args(no_open=True)) == 0
+ assert launcher.cmd_webapp(_args(status=True)) == 0
+ assert "plain http" not in capsys.readouterr().out.lower()
diff --git a/website/docs/user-guide/desktop.md b/website/docs/user-guide/desktop.md
index 118e98e5753..edd02cded40 100644
--- a/website/docs/user-guide/desktop.md
+++ b/website/docs/user-guide/desktop.md
@@ -79,8 +79,14 @@ requires the same sign-in. `hermes webapp` then opens the Webapp's address, wher
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.
+links serve only a Webapp that needs no sign-in. HTTPS is strongly recommended remotely.
+
+**What plain HTTP loses.** Browsers turn off features that need a secure context on a plain-HTTP
+address other than loopback (`http://localhost` and `http://127.0.0.1` count as secure): the bot
+screen viewer, the microphone (dictation and live voice) and system notifications. The bot screen and
+live voice say so instead of opening. `hermes webapp` and `hermes webapp --status` print a note when
+the address they give is plain HTTP on another host. To keep these features, open the Webapp over
+HTTPS (`webapp.public_url`) or through an SSH tunnel to `127.0.0.1`.
:::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,
@@ -118,8 +124,9 @@ and only that app can change it: a browser signed in over the network cannot.
- **This network:** devices on the same Wi-Fi open `http://<this computer's address>:<port>`, where the
port is `webapp.port` (9120 unless you set another, or Start chose one for a standalone profile).
- This is plain HTTP: the connection is not encrypted, so others on the network could read it. Use it
- only on a network you trust.
+ This is plain HTTP: the connection is not encrypted, so others on the network could read it, and
+ browsers turn off the features listed under **What plain HTTP loses** above. Use it only on a
+ network you trust.
- **My own URL:** an HTTPS address you already run (Tailscale Serve, a tunnel or a reverse proxy) that
forwards to `http://127.0.0.1:<port>`. It is saved as `webapp.public_url`. Never forward that port
from your router directly.