Files
Teknium 44901b1db9 feat(webapp): Saved connections in the Webapp, reached through the forwarding proxy
The Webapp's Settings → Gateways now shows native Desktop's own Saved
connections page over the machine's one list (/api/gateway-connections):
Add, Test, Make primary, Remove and the launch-mode toggle. The browser
bridge's `connections` is REST-backed, publishes what changed on every read
(focus, and every 5 s while the page is open) as Desktop's
connections:changed reasons, and uses the registry's own ids, so profile
routes, Bot Mode and group-chat records name the same gateway on both hosts.

The forwarding proxy (/api/relay/<connection id>/...) keeps every response
hardening rule (header allowlist, sandbox CSP, no-store, redirects kept
inside the gateway, no cookie jar, close on remove) and now reaches each
saved gateway as an ordinary client with the credential saved for it:
X-Hermes-Session-Token or ?token= for token mode, a refreshed native bearer
and a one-use ws-ticket for oauth mode, plus the entry's extra headers.
The other gateway needs no code or config.

Removed the pairing machinery: consent page, grants, the hub key and
scopes, webapp/relay-gateways.json, the webapp.relay config key, and the
relay hooks in the sign-in gate, the upgrade gate, display tickets and
the RPC dispatcher; plus the relay settings UI and its strings.
2026-11-07 12:01:04 -08:00

407 lines
20 KiB
Python

"""Webapp-only routes: the host terminal (loopback or authenticated binds), the
one-use ticket each browser socket dial mints (``/api/webapp/socket-ticket?socket=`` for
``/api/ws`` on this same origin, the host terminal and each voice stream), and the one-use
handoffs (child window, auto-opened launch tab) for the private, loopback Webapp session."""
from __future__ import annotations
import ipaddress
import json
import logging
import os
import secrets
import sys
import threading
import time
from fastapi import APIRouter, HTTPException, Request, WebSocket
from fastapi.responses import HTMLResponse, JSONResponse
from hermes_cli.dashboard_auth.request_utils import _http_origin
from hermes_cli.web_server_surface import policy, private_launch
from hermes_cli.web_session_sockets import (
GATEWAY_SOCKET, HOST_TERMINAL_SOCKET, RELAY_SOCKET, SPEAK_STREAM_SOCKET, TRANSCRIBE_STREAM_SOCKET)
_log = logging.getLogger("hermes_cli.web_server")
router = APIRouter()
WINDOW_TICKET_TTL_SECONDS = 30
#: A sandboxed (snap/Flatpak) browser's cold start can take several seconds to reach the page.
LAUNCH_TICKET_TTL_SECONDS = 60
_MAX_WINDOW_TICKETS = 128
_ticket_lock = threading.Lock()
#: Who a socket opened with the loopback session token is (``chat_ws.gateway_ws`` gives a
#: ``?token=`` socket the same identity, and REST mutations are forwarded as it).
SESSION_TOKEN_OWNER = {"user_id": "legacy-token-owner", "provider": "session-token", "issuer": ""}
def _require_private_webapp(request: Request) -> None:
if not private_launch(request.app.state):
raise HTTPException(404, "Private Webapp window handoff is unavailable")
@router.websocket("/api/host-terminal")
async def host_terminal_ws(ws: WebSocket) -> None:
from hermes_cli import web_host_terminal
from hermes_cli.web_host_terminal_sessions import host_terminal
from hermes_cli.web_server_chat import _PTY_BRIDGE_AVAILABLE, PtyUnavailableError, _pty_fail, _ws_gate
gate = await _ws_gate(ws, HOST_TERMINAL_SOCKET)
if gate is None:
return
peer, mode, cred = gate
if not web_host_terminal.request_allowed():
await ws.close(code=4403, reason="host terminal requires authenticated Webapp")
return
await ws.accept()
_log.info("host terminal accepted peer=%s mode=%s cred=%s", peer, mode, cred)
if not _PTY_BRIDGE_AVAILABLE:
await _pty_fail(
ws, PtyUnavailableError("Pseudo-terminal support is not installed on this host."), surface="Terminal")
return
await host_terminal(ws)
def _mint_handoff_ticket(state, ttl: float, *, launch: bool) -> str:
"""One-use ticket that ``/webapp/window-session`` exchanges for this start's session token. The
store keeps ``(expiry, browser credential generation, launch)``, never the credential itself."""
from hermes_cli import browser_credential
now = time.monotonic()
with _ticket_lock:
tickets = getattr(state, "webapp_window_tickets", {})
tickets = {key: value for key, value in tickets.items()
if value[0] > now and browser_credential.is_current(value[1])}
state.webapp_window_tickets = tickets
if len(tickets) >= _MAX_WINDOW_TICKETS:
raise HTTPException(429, "Too many pending Webapp windows; try again shortly")
ticket = secrets.token_urlsafe(32)
tickets[ticket] = (now + ttl, browser_credential.generation(), launch)
return ticket
def mint_launch_ticket(state) -> str:
"""Ticket for the browser the server opens itself: a launcher's argv carries this, not the token."""
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, WSL): 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*``.
Both ends of a loopback connection are listed with their socket owner; the client's is
the row whose local address is *client* and remote address is *server*. None when absent
(another network namespace, a closed connection) or unreadable.
"""
def _normal(host: str | bytes, port: int):
address = ipaddress.ip_address(host)
return getattr(address, "ipv4_mapped", None) or address, port
def _row_address(field: str):
host_hex, port_hex = field.split(":")
raw = bytes.fromhex(host_hex)
# The kernel prints each 32-bit word of the address in host byte order.
packed = b"".join(int.from_bytes(raw[i:i + 4], "big").to_bytes(4, sys.byteorder)
for i in range(0, len(raw), 4))
return _normal(packed, int(port_hex, 16))
try:
wanted = (_normal(*client), _normal(*server))
except ValueError:
return None
for table in ("/proc/net/tcp", "/proc/net/tcp6"):
try:
with open(table, encoding="ascii") as stream:
rows = stream.read().splitlines()[1:]
except OSError:
continue
for row in rows:
fields = row.split()
try:
if (_row_address(fields[1]), _row_address(fields[2])) == wanted:
return int(fields[7])
except (IndexError, ValueError):
continue
return None
def _peer_is_server_user(request: Request, platform: str = sys.platform) -> bool:
"""Whether a launch ticket that crossed a browser launcher's argv may be spent over this
request's connection on *platform* (a ``sys.platform`` value, this host's by default).
Linux checks that the connection belongs to the OS user running the server. Windows checks
nothing and always says yes: the protection there is that the ticket travels only in the
launcher's command line, which only its own user, SYSTEM and elevated administrators can read.
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; WSL
never mints one. 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 platform == "win32":
return True
if platform != "linux":
return False
client, server = request.client, request.scope.get("server")
if client is None or not server:
return False
return _loopback_peer_uid((client.host, client.port), (server[0], server[1])) == os.getuid() # windows-footgun: ok — Linux-only branch
@router.post("/api/webapp/window-ticket")
async def issue_window_ticket(request: Request):
from hermes_cli.web_server import _require_token
_require_private_webapp(request)
_require_token(request)
ticket = _mint_handoff_ticket(request.app.state, WINDOW_TICKET_TTL_SECONDS, launch=False)
return JSONResponse({"ticket": ticket}, headers={"Cache-Control": "no-store"})
def _ticket_principal(request: Request) -> tuple[dict, str | None]:
"""``({user_id, provider, issuer}, session_token)`` of the caller: its verified login (no
token), or on an unauthenticated loopback bind ``SESSION_TOKEN_OWNER`` and the session token
it presented."""
session = getattr(request.state, "session", None)
if session is not None:
return {"user_id": session.user_id, "provider": session.provider,
"issuer": getattr(session, "issuer", "") or ""}, None
if not getattr(request.app.state, "auth_required", False):
from hermes_cli.web_server import _SESSION_HEADER_NAME, _has_valid_session_token
presented = (request.headers.get(_SESSION_HEADER_NAME)
or request.headers.get("authorization", "").removeprefix("Bearer "))
if _has_valid_session_token(request):
return dict(SESSION_TOKEN_OWNER), presented
raise HTTPException(status_code=401, detail="Unauthorized")
def mint_socket_ticket(identity: dict, socket: str, *, session_token: str | None = None,
sign_in: str | None = None, profile_home: str | None = None) -> str:
"""A one-use ticket that opens only *socket* (``web_session_sockets.GATEWAY_SOCKET``,
``HOST_TERMINAL_SOCKET`` or one of ``AUDIO_SOCKETS``) as *identity*. Minted with
*session_token*, or by a login whose sign-in binding was checked against the browser credential
of generation *sign_in* (``hermes_cli.webapp_sign_in``), it records that credential's generation
(``hermes_cli.browser_credential``): it opens nothing once that credential is replaced, and the
socket it opens closes when the browser signs out. With *profile_home* the socket it opens answers
for that profile (``chat_ws.gateway_ws``)."""
from hermes_cli.browser_credential import generation_of
from hermes_cli.dashboard_auth.ws_tickets import mint_ticket
extra = {"socket": socket}
if session_token is not None:
extra["session_token"] = generation_of(session_token)
if sign_in is not None:
extra["sign_in"] = sign_in
if profile_home is not None:
extra["profile_home"] = profile_home
return mint_ticket(user_id=identity["user_id"], provider=identity["provider"],
issuer=identity.get("issuer", ""), extra=extra)
def _socket_ticket_response(request: Request, identity: dict, socket: str, session_token: str | None,
profile_home: str | None = None) -> JSONResponse:
from hermes_cli.dashboard_auth.ws_tickets import TTL_SECONDS
from hermes_cli.webapp_sign_in import sign_in_of
ticket = mint_socket_ticket(identity, socket, session_token=session_token, sign_in=sign_in_of(request),
profile_home=profile_home)
return JSONResponse({"ticket": ticket, "ttl_seconds": TTL_SECONDS}, headers={"Cache-Control": "no-store"})
#: Every socket a Webapp page dials with a one-use ticket from ``POST /api/webapp/socket-ticket``, by
#: its ``web_session_sockets`` name: the ``web_server_surface.SurfacePolicy`` field that lets a surface
#: mint it, and whether the mint checks the profile the page will dial (400/404), so a stale tab learns
#: its profile is gone there rather than from a socket that keeps closing.
SOCKET_TICKETS: dict[str, tuple[str, bool]] = {
GATEWAY_SOCKET: ("gateway_ticket", True),
HOST_TERMINAL_SOCKET: ("host_terminal", False),
SPEAK_STREAM_SOCKET: ("gateway_ticket", False),
TRANSCRIBE_STREAM_SOCKET: ("gateway_ticket", False),
RELAY_SOCKET: ("gateway_connections", False),
}
@router.post("/api/webapp/socket-ticket")
async def issue_socket_ticket(request: Request, socket: str = "", profile: str | None = None):
"""The browser's one-use ticket for one dial of *socket* on this same origin: ``gateway`` for
``/api/ws`` (also offered as the ``hermes-gateway-ticket.`` subprotocol), ``host-terminal`` for
``/api/host-terminal``, ``speak-stream`` and ``transcribe-stream`` for ``/api/audio/<name>``. The
upgrade gate (``web_server_chat._consume_ws_ticket``) redeems it as this caller's login; it opens
that socket and nothing else, so the browser mints one per dial. Minted locally: the server that
serves this page runs the socket's sessions. A ``gateway`` ticket minted with *profile* names
it: that socket answers a request that names no profile for *profile*, as a native ticket does
(``chat_ws.gateway_ws``), never for the gateway's launch profile."""
from hermes_cli.web_server_cron import _cron_profile_home
if socket not in SOCKET_TICKETS:
raise HTTPException(400, "Unknown socket")
surface, checks_profile = SOCKET_TICKETS[socket]
if not getattr(policy(request.app.state), surface):
raise HTTPException(404, f"Webapp {socket} tickets are unavailable on this surface")
identity, session_token = _ticket_principal(request)
profile_home = None
if checks_profile:
_name, home = _cron_profile_home(profile)
if socket == GATEWAY_SOCKET and profile:
profile_home = str(home)
return _socket_ticket_response(request, identity, socket, session_token, profile_home=profile_home)
@router.post("/webapp/window-session")
async def redeem_window_ticket(request: Request):
from hermes_cli import browser_credential
_require_private_webapp(request)
# This endpoint deliberately sits outside /api: the child window or launch
# tab has no session yet. Only a purpose-specific ticket can exchange for
# the existing one.
# Private links use the actual bind origin, which may differ from a
# configured loopback public_url. Host validation remains in middleware;
# proxy-normalized ASGI scheme/Host (not raw forwarded headers) are trusted.
origins = request.headers.getlist("origin")
origin = _http_origin(origins[0]) if len(origins) == 1 else None
target_origin = _http_origin(f"{request.url.scheme}://{request.url.netloc}")
if origin is None or origin != target_origin:
raise HTTPException(403, "Webapp window handoff requires a same-origin request")
# Keep the unauthenticated exchange body-free; never parse an arbitrary
# JSON/multipart payload just to extract a fixed-size capability.
ticket = request.headers.get("X-Hermes-Window-Ticket", "")
with _ticket_lock:
tickets = getattr(request.app.state, "webapp_window_tickets", {})
entry = tickets.get(ticket)
# A launch ticket crossed a browser launcher's argv: only a connection owned by this
# server's user may spend it, and a refused attempt must not burn it for the real browser.
if entry is not None and entry[2] and not _peer_is_server_user(request):
entry = None
elif entry is not None:
del tickets[ticket]
token = browser_credential.current_if(entry[1]) if entry is not None and entry[0] > time.monotonic() else None
if token is None:
raise HTTPException(403, "Webapp window link expired or was already used; open a new window")
return JSONResponse({"token": token}, headers={"Cache-Control": "no-store"})
# The credential goes to this tab's sessionStorage, where the Webapp reads it at boot
# (browser-launch-session.ts), never into a URL: the browser keeps every address it opens in its history.
_LAUNCH_SCRIPT = r"""
const basePath = __BASE_PATH__;
const params = new URLSearchParams(location.hash.slice(1));
history.replaceState(null, '', location.pathname);
const ticket = params.get('ticket') || '';
const show = message => { document.getElementById('status').textContent = message; };
const fail = () => show('This launch link was already used or has expired. Run hermes webapp again for a new one.');
if (!/^[A-Za-z0-9_-]{43}$/.test(ticket)) {
fail();
} else {
fetch(`${basePath}/webapp/window-session`, {
method: 'POST', credentials: 'same-origin', headers: {'X-Hermes-Window-Ticket': ticket}
}).then(response => response.ok ? response.json() : Promise.reject()).then(({token}) => {
if (typeof token !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(token)) throw new Error();
try {
sessionStorage.setItem(`hermes.webapp.session.v1:${JSON.stringify([location.origin, basePath])}`, token);
} catch {
show('This browser does not let the Webapp keep its sign-in in this tab. Allow site data for this '
+ 'address, then run hermes webapp again.');
return;
}
const target = new URL(`${basePath}/`, location.origin);
target.search = params.get('query') || '';
location.replace(target.href);
}).catch(fail);
}
"""
def _handoff_page(request: Request, title: str, status: str, script: str) -> HTMLResponse:
"""Credential-free, uncached page whose only script is *script* (``__BASE_PATH__`` bound)."""
from hermes_cli.web_server_dashboard import _normalise_prefix
prefix = _normalise_prefix(request.headers.get("x-forwarded-prefix"))
nonce = secrets.token_urlsafe(16)
script = script.replace("__BASE_PATH__", json.dumps(prefix).replace("</", "<\\/"))
return HTMLResponse(
'<!doctype html><meta charset="utf-8"><meta name="referrer" content="no-referrer">'
f'<title>{title}</title><p id="status">{status}</p>'
f'<script nonce="{nonce}">{script}</script>',
headers={
"Cache-Control": "no-store",
"Referrer-Policy": "no-referrer",
"Content-Security-Policy": f"default-src 'none'; script-src 'nonce-{nonce}'; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'",
},
)
@router.get("/webapp/launch")
async def launch_page(request: Request):
"""Where the server's own browser-open lands: spends the one-use launch ticket from the
fragment (never sent to the server), keeps the credential it receives in this tab's
sessionStorage and enters the Webapp at an address that carries neither."""
_require_private_webapp(request)
return _handoff_page(request, "Opening Hermes", "Opening Hermes Webapp…", _LAUNCH_SCRIPT)
# No credential appears in this public page or in its URL. The fragment
# names a transient channel; the authorized parent mints a one-use ticket.
_WINDOW_SCRIPT = r"""
const basePath = __BASE_PATH__;
const params = new URLSearchParams(location.hash.slice(1));
history.replaceState(null, '', location.pathname);
const id = params.get('channel') || '';
const status = document.getElementById('status');
if (!/^[a-f0-9-]{36}$/.test(id)) {
status.textContent = 'Open this window from an authorized Hermes Webapp tab.';
} else {
const channel = new BroadcastChannel(`hermes.webapp.window:${id}`);
let receiving = false;
let finished = false;
const controller = new AbortController();
const fail = message => {
if (finished) return;
finished = true;
controller.abort();
status.textContent = message;
channel.postMessage({type: 'error'});
channel.close();
clearTimeout(timeout);
};
const timeout = setTimeout(() => fail('This window link expired. Open a new window from the original tab.'), 30000);
channel.onmessage = async event => {
if (receiving) return;
if (event.data?.error) { fail(event.data.error); return; }
const ticket = event.data?.ticket;
if (typeof ticket !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(ticket)) return;
receiving = true;
try {
const response = await fetch(`${basePath}/webapp/window-session`, {
method: 'POST', credentials: 'same-origin',
headers: {'X-Hermes-Window-Ticket': ticket}, signal: controller.signal
});
if (!response.ok) throw new Error('Window authorization expired. Open a new window from the original tab.');
const {token} = await response.json();
if (finished) return;
if (typeof token !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(token)) throw new Error('Invalid window authorization.');
sessionStorage.setItem(`hermes.webapp.session.v1:${JSON.stringify([location.origin, basePath])}`, token);
const target = new URL(`${basePath}/`, location.origin);
target.search = params.get('query') || '';
target.hash = params.get('route') || '/';
channel.postMessage({type: 'done'});
finished = true;
clearTimeout(timeout);
channel.close();
location.replace(target.href);
} catch (error) { fail(error.message || 'Could not authorize this window. Open it again from the original tab.'); }
};
channel.postMessage({type: 'ready'});
}
"""
@router.get("/webapp/window")
async def child_window_page(request: Request):
_require_private_webapp(request)
return _handoff_page(request, "Opening Hermes", "Authorizing this Hermes window…", _WINDOW_SCRIPT)