Files
hermes-agent/hermes_cli/shared_session_attach.py
Maciej Lisiewski 27a5f29570 fix(cli): strip only other-user bits from the session registry; bind attach proof to the socket
Forcing the registry to 0600 and runtime/ to 0700 broke shared-group
HERMES_HOME deployments (NixOS module: UMask 0007, setgid 2770 home):
other hermes-group users got EACCES on active_sessions.lock, and the CLI
and gateway claim paths swallow that and run with no lease. Group members
are already trusted with .env and state.db; the threat is other users, so
clear only the 'other' bits and keep group bits and setgid. A loose
registry left by an older build is now also closed on read, since attach
discovery never writes.

attach_proof now MACs profile_home and websocket_url too
("hermes-session-attach:<sid>:<nonce>:<profile_home>:<websocket_url>"),
so a relay holding a genuine proof cannot swap in its own socket.

Fixes #120604
2026-11-13 16:54:40 +01:00

132 lines
7.0 KiB
Python

"""Discover a cooperative local runtime without taking its session lease.
The owner's handshake supplies the existing authenticated WebSocket URL. A
registry entry is discovery information, not authority to mint a credential.
The handshake lets the requester prove it read the registry without the lease
id travelling in the request: the client sends ``nonce`` plus
``client_proof = hex(HMAC_SHA256(lease_id, "hermes-session-attach-request:<session_id>:<nonce>"))``,
and the reply must echo the request fields and return
``attach_proof = hex(HMAC_SHA256(lease_id, "hermes-session-attach:<session_id>:<nonce>:<profile_home>:<websocket_url>"))``,
covering the returned socket so a relay holding a genuine proof cannot swap in its own.
The client checks the reply proof against its own registry copy, which refuses
a listener that only echoes request parameters. That check proves the listener
could read the registry, not that it is the live owner, so the registry itself
is never readable by other users. ``client_proof`` states the request-side half of the
contract; no shipped runtime verifies it yet.
"""
from __future__ import annotations
import hashlib
import hmac
import ipaddress
import json
import secrets
from pathlib import Path
from urllib.parse import urlencode, urlsplit
import httpx
from hermes_constants import get_hermes_home
from hermes_cli.active_sessions import active_session_registry_snapshot, session_owner_details
def _local_origin(url: str, scheme: str) -> tuple[str, int]:
parts = urlsplit(url)
host = parts.hostname or ""
try:
local = ipaddress.ip_address(host).is_loopback
except ValueError:
local = False
if (parts.scheme != scheme or not local or parts.username is not None
or parts.password is not None or parts.fragment or not parts.port):
raise ValueError("Shared runtime endpoint must be an explicit loopback address and port.")
return host, parts.port
def discover_attach_url(session_id: str, *, registry_home: str | Path | None = None) -> str | None:
"""Return a fenced authenticated URL, None for no owner, or refuse safely.
This deliberately does not scan ports or read another profile. The runtime
must advertise ``metadata.shared_runtime_url`` and implement the local
``/api/session-attach`` handshake. Unsupported owners keep their lease.
"""
home = Path(registry_home if registry_home is not None else get_hermes_home()).resolve()
owners = [entry for entry in active_session_registry_snapshot(home, strict=True)
if entry.get("session_id") == session_id]
if not owners:
return None
if len(owners) != 1:
raise ValueError("Session owner identity is ambiguous; no attachment was attempted.")
owner = owners[0]
endpoint = (owner.get("metadata") or {}).get("shared_runtime_url")
if not isinstance(endpoint, str) or not endpoint:
raise ValueError("This chat is open in another Hermes window/terminal, and attaching "
"this terminal to it is not available in this build. Close the chat "
"there and run hermes --resume " + session_id + " here to take it over.\n"
+ session_owner_details(session_id, owner))
origin = _local_origin(endpoint, "http")
parts = urlsplit(endpoint)
if parts.path not in ("", "/") or parts.query:
raise ValueError("Shared runtime endpoint must be an origin without a path or query.")
nonce = secrets.token_urlsafe(24)
# Proof the requester read the registry, without disclosing the lease id it keys on; the
# responder checks this instead of a lease_id parameter so the secret is never transmitted.
client_proof = hmac.new(
str(owner["lease_id"]).encode("utf-8"),
f"hermes-session-attach-request:{session_id}:{nonce}".encode(),
hashlib.sha256,
).hexdigest()
query = urlencode({"session_id": session_id, "nonce": nonce,
"profile_home": str(home), "client_proof": client_proof})
try:
# Ignore proxy env and redirects: local discovery must stay on the
# advertised endpoint, including on machines with corporate proxies.
with httpx.Client(trust_env=False, follow_redirects=False, timeout=3.0) as client:
with client.stream("GET", endpoint.rstrip("/") + "/api/session-attach?" + query) as response:
response.raise_for_status()
body = bytearray()
for chunk in response.iter_bytes():
body.extend(chunk)
if len(body) > 65536:
raise ValueError("Shared runtime handshake response is too large.")
reply = json.loads(body)
except (httpx.HTTPError, json.JSONDecodeError) as exc:
# Never include a remote body or authenticated URL in diagnostics.
raise ValueError("This chat is open in another Hermes window/terminal, and attaching "
"this terminal to it just failed. Use the chat where it is open, or "
"close it there and run hermes --resume " + session_id + " here.\n"
+ session_owner_details(session_id, owner)) from exc
# Echoed fields only prove the listener heard the request; the proof is what ties the
# reply to the registry's lease id, which a rogue listener cannot learn from the request.
# It can learn it from the registry file itself, which is why other users cannot read
# the registry (see _write_entries).
websocket_url = reply.get("websocket_url") if isinstance(reply, dict) else None
if not isinstance(websocket_url, str):
raise ValueError("Shared runtime handshake identity does not match the requested owner.")
expected_proof = hmac.new(
str(owner["lease_id"]).encode("utf-8"),
f"hermes-session-attach:{session_id}:{nonce}:{home}:{websocket_url}".encode("utf-8", "replace"),
hashlib.sha256,
).hexdigest()
if (any(reply.get(key) != value for key, value in {
"session_id": session_id, "nonce": nonce, "profile_home": str(home),
}.items())
or not hmac.compare_digest(
str(reply.get("attach_proof") or "").encode("utf-8", "replace"),
expected_proof.encode("ascii"))):
raise ValueError("Shared runtime handshake identity does not match the requested owner.")
if (_local_origin(websocket_url, "ws") != origin
or urlsplit(websocket_url).path != "/api/ws"):
raise ValueError("Shared runtime handshake returned a different endpoint.")
return websocket_url
def configure_tui_attachment(env: dict[str, str], session_id: str | None, *,
registry_home: str | Path | None = None) -> None:
"""Retain an explicit transport, otherwise attach a resumed owner's runtime."""
if not session_id or env.get("HERMES_TUI_GATEWAY_URL", "").strip():
return
url = discover_attach_url(session_id, registry_home=registry_home)
if url is not None:
env["HERMES_TUI_GATEWAY_URL"] = url