From 2a5e7764ad811525e14ff44c53564357ff8c5893 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Wed, 2 Sep 2026 15:58:57 -0700 Subject: [PATCH 1/2] refactor(gateway/hosted_rooms): compact peer/links/execution_policy onto common validators, extract catalog endpoint/link-mode parsers --- gateway/hosted_room_execution_policy.py | 39 +- gateway/hosted_room_links.py | 57 +-- gateway/hosted_room_peer.py | 479 +++++++----------------- 3 files changed, 163 insertions(+), 412 deletions(-) diff --git a/gateway/hosted_room_execution_policy.py b/gateway/hosted_room_execution_policy.py index da00c49d8f..41da1e08cf 100644 --- a/gateway/hosted_room_execution_policy.py +++ b/gateway/hosted_room_execution_policy.py @@ -14,6 +14,9 @@ POLICY_VERSION = 1 MAX_POLICY_TOOLSETS = 128 MAX_POLICY_ITERATIONS = (1 << 53) - 1 _IDENTIFIER_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]*$") +_POLICY_FIELDS = { + "version", "target_profile", "enabled_toolsets", "approval_mode", "max_iterations", "policy_digest", +} class RoomExecutionPolicyError(ValueError): @@ -21,13 +24,12 @@ class RoomExecutionPolicyError(ValueError): def _policy_digest(unsigned: Mapping[str, Any]) -> str: - encoded = json.dumps( - unsigned, ensure_ascii=True, sort_keys=True, separators=(",", ":") - ).encode("ascii") + encoded = json.dumps(unsigned, ensure_ascii=True, sort_keys=True, separators=(",", ":")).encode("ascii") return hashlib.sha256(encoded).hexdigest() def _identifier(value: Any, *, field: str) -> str: + # Stringifies first (``None`` -> ""), so non-strings also fail as "is invalid". normalized = str(value or "").strip() if not normalized or len(normalized) > 128 or _IDENTIFIER_RE.fullmatch(normalized) is None: raise RoomExecutionPolicyError(f"{field} is invalid") @@ -47,25 +49,15 @@ class RoomExecutionPolicy: @classmethod def from_mapping(cls, value: Mapping[str, Any]) -> "RoomExecutionPolicy": - required = { - "version", "target_profile", "enabled_toolsets", - "approval_mode", "max_iterations", "policy_digest", - } - if not isinstance(value, Mapping) or set(value) != required: + if not isinstance(value, Mapping) or set(value) != _POLICY_FIELDS: raise RoomExecutionPolicyError("execution policy fields are invalid") if value["version"] != POLICY_VERSION: raise RoomExecutionPolicyError("execution policy version is unsupported") target_profile = _identifier(value["target_profile"], field="target_profile") raw_toolsets = value["enabled_toolsets"] - if ( - not isinstance(raw_toolsets, list) - or not raw_toolsets - or len(raw_toolsets) > MAX_POLICY_TOOLSETS - ): + if not isinstance(raw_toolsets, list) or not 1 <= len(raw_toolsets) <= MAX_POLICY_TOOLSETS: raise RoomExecutionPolicyError("enabled_toolsets are invalid") - toolsets = tuple( - sorted(_identifier(item, field="enabled_toolset") for item in raw_toolsets) - ) + toolsets = tuple(sorted(_identifier(item, field="enabled_toolset") for item in raw_toolsets)) if len(set(toolsets)) != len(toolsets) or "bot_room" not in toolsets: raise RoomExecutionPolicyError("enabled_toolsets are invalid") approval_mode = str(value["approval_mode"] or "").strip().lower() @@ -94,13 +86,8 @@ class RoomExecutionPolicy: return {**asdict(self), "enabled_toolsets": list(self.enabled_toolsets)} -def execution_policy_mapping( - *, - target_profile: str, - config: Mapping[str, Any] | None = None, -) -> dict[str, Any]: +def execution_policy_mapping(*, target_profile: str, config: Mapping[str, Any] | None = None) -> dict[str, Any]: """Resolve the effective API-server policy from the target's own config.""" - if config is None: from gateway.run import _load_gateway_config @@ -114,9 +101,7 @@ def execution_policy_mapping( toolsets = sorted({*_get_platform_tools(dict(config), "api_server"), "bot_room"}) agent = config.get("agent") if isinstance(config.get("agent"), Mapping) else {} - approvals = ( - config.get("approvals") if isinstance(config.get("approvals"), Mapping) else {} - ) + approvals = config.get("approvals") if isinstance(config.get("approvals"), Mapping) else {} unsigned = { "version": POLICY_VERSION, "target_profile": _identifier(target_profile, field="target_profile"), @@ -130,9 +115,7 @@ def execution_policy_mapping( return RoomExecutionPolicy.from_mapping(value).as_mapping() -_CURRENT_POLICY: ContextVar[RoomExecutionPolicy | None] = ContextVar( - "hosted_room_execution_policy", default=None -) +_CURRENT_POLICY: ContextVar[RoomExecutionPolicy | None] = ContextVar("hosted_room_execution_policy", default=None) def bind_room_execution_policy(policy: RoomExecutionPolicy) -> Token: diff --git a/gateway/hosted_room_links.py b/gateway/hosted_room_links.py index 98841b0421..44363cfda3 100644 --- a/gateway/hosted_room_links.py +++ b/gateway/hosted_room_links.py @@ -7,6 +7,7 @@ never included in reprs, status payloads, or exception messages. from __future__ import annotations +import contextlib import json import os import time @@ -21,36 +22,20 @@ from gateway.hosted_room_peer import ( TransportSecurity, validate_room_link_url, ) -import contextlib MAX_LINKS = 512 MAX_GRANT_CHARS = 16 * 1024 _LEGACY_FIELDS = { - "room_id", - "member_id", - "target_url", - "target_profile", - "grant", - "catalog", - "cancellation_scope_id", - "trace_id", - "updated_at", + "room_id", "member_id", "target_url", "target_profile", "grant", "catalog", + "cancellation_scope_id", "trace_id", "updated_at", } _OPTIONAL_FIELDS = {"transport_security", "status"} # SQLite record columns that map 1:1 onto mapping fields, in record order # (``catalog_json`` is the serialized ``catalog``). _RECORD_FIELDS = ( - "room_id", - "member_id", - "target_url", - "target_profile", - "grant", - "cancellation_scope_id", - "trace_id", - "transport_security", - "status", - "updated_at", + "room_id", "member_id", "target_url", "target_profile", "grant", "cancellation_scope_id", + "trace_id", "transport_security", "status", "updated_at", ) _STATUSES = {"ready", "unavailable", "needs_reauthorization"} @@ -96,9 +81,7 @@ class StoredRoomLink: target_profile=target_profile, grant=grant, catalog=GatewayRoomCatalog.from_mapping(value["catalog"]), - cancellation_scope_id=_short_string( - value["cancellation_scope_id"], "cancellation_scope_id" - ), + cancellation_scope_id=_short_string(value["cancellation_scope_id"], "cancellation_scope_id"), trace_id=_short_string(value["trace_id"], "trace_id"), transport_security=transport_security, # type: ignore[arg-type] status=status, @@ -111,18 +94,14 @@ class StoredRoomLink: catalog = json.loads(str(value["catalog_json"])) except Exception as exc: raise HostedRoomPeerError("stored room link catalog is unreadable") from exc - return cls.from_mapping( - {**{name: value[name] for name in _RECORD_FIELDS}, "catalog": catalog} - ) + return cls.from_mapping({**{name: value[name] for name in _RECORD_FIELDS}, "catalog": catalog}) def catalog_mapping(self) -> dict[str, Any]: return self.catalog.as_mapping() def as_record(self) -> dict[str, Any]: record = {name: getattr(self, name) for name in _RECORD_FIELDS} - record["catalog_json"] = json.dumps( - self.catalog_mapping(), sort_keys=True, separators=(",", ":") - ) + record["catalog_json"] = json.dumps(self.catalog_mapping(), sort_keys=True, separators=(",", ":")) return record @@ -144,9 +123,7 @@ def load_room_links(db_path: Path | str) -> tuple[StoredRoomLink, ...]: return tuple(StoredRoomLink.from_record(row) for row in _link_rows(db_path)) -def load_room_links_tolerant( - db_path: Path | str, -) -> tuple[tuple[StoredRoomLink, ...], tuple[str, ...]]: +def load_room_links_tolerant(db_path: Path | str) -> tuple[tuple[StoredRoomLink, ...], tuple[str, ...]]: """Load healthy routes while quarantining malformed rows by identity.""" links = [] errors = [] @@ -161,27 +138,17 @@ def load_room_links_tolerant( def save_room_link(db_path: Path | str, link: StoredRoomLink) -> None: - hosted_rooms.upsert_room_link_record( - db_path, record=link.as_record(), max_links=MAX_LINKS - ) + hosted_rooms.upsert_room_link_record(db_path, record=link.as_record(), max_links=MAX_LINKS) if os.name == "posix": with contextlib.suppress(OSError): Path(db_path).chmod(0o600) -def mark_room_link_status( - db_path: Path | str, - *, - room_id: str, - member_id: str, - status: str, -) -> bool: +def mark_room_link_status(db_path: Path | str, *, room_id: str, member_id: str, status: str) -> bool: if status not in _STATUSES: raise HostedRoomPeerError("stored room link status is invalid") return hosted_rooms.update_room_link_status( - db_path, - room_id=_short_string(room_id, "room_id"), - member_id=_short_string(member_id, "member_id"), + db_path, room_id=_short_string(room_id, "room_id"), member_id=_short_string(member_id, "member_id"), status=status, ) diff --git a/gateway/hosted_room_peer.py b/gateway/hosted_room_peer.py index a881b9e594..ce88f47760 100644 --- a/gateway/hosted_room_peer.py +++ b/gateway/hosted_room_peer.py @@ -23,10 +23,8 @@ from functools import lru_cache from pathlib import Path from typing import Any, Callable, Iterable, Literal, Mapping -from gateway.hosted_room_execution_policy import ( - RoomExecutionPolicy, - execution_policy_mapping, -) +from gateway.hosted_room_execution_policy import RoomExecutionPolicy, execution_policy_mapping +from gateway.hosted_rooms_common import exact_fields, identifier, positive_int # v2 adds authority/member lineage to scoped grants and is deliberately not @@ -53,10 +51,20 @@ class HostedRoomGrantError(HostedRoomPeerError): _ROOM_GRANT_SECRET_FILE = ".room-link-grant-secret" +def _fsync_dir(directory: Path) -> None: + try: + parent_fd = os.open(directory, os.O_RDONLY) + try: + os.fsync(parent_fd) + finally: + os.close(parent_fd) + except OSError: + pass + + @lru_cache(maxsize=32) def _gateway_room_grant_secret_for_home(home_value: str) -> bytes: """Load one restart-scoped grant secret for an exact installation root.""" - home = Path(home_value) home.mkdir(parents=True, exist_ok=True) path = home / _ROOM_GRANT_SECRET_FILE @@ -65,18 +73,17 @@ def _gateway_room_grant_secret_for_home(home_value: str) -> bytes: data = path.read_bytes() if len(data) != 32: raise HostedRoomGrantError("gateway RoomLink secret is invalid") - mode = stat.S_IMODE(path.stat().st_mode) - if mode & 0o077: + if stat.S_IMODE(path.stat().st_mode) & 0o077: path.chmod(0o600) return data try: material = _read() except FileNotFoundError: + # Atomic create: O_EXCL temp file, hard-link into place (loser re-reads + # the winner's secret), fsync the directory, always drop the temp name. material = os.urandom(32) - temporary = home / ( - f".{_ROOM_GRANT_SECRET_FILE}.{os.getpid()}.{os.urandom(8).hex()}" - ) + temporary = home / f".{_ROOM_GRANT_SECRET_FILE}.{os.getpid()}.{os.urandom(8).hex()}" fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600) try: with os.fdopen(fd, "wb", closefd=True) as stream: @@ -88,21 +95,10 @@ def _gateway_room_grant_secret_for_home(home_value: str) -> bytes: except FileExistsError: material = _read() else: - try: - parent_fd = os.open(home, os.O_RDONLY) - try: - os.fsync(parent_fd) - finally: - os.close(parent_fd) - except OSError: - pass + _fsync_dir(home) finally: temporary.unlink(missing_ok=True) - return hmac.new( - material, - b"hermes-hosted-room-installation-grant-v1", - hashlib.sha256, - ).digest() + return hmac.new(material, b"hermes-hosted-room-installation-grant-v1", hashlib.sha256).digest() def gateway_room_grant_secret(root: Path | str | None = None) -> bytes: @@ -113,15 +109,13 @@ def gateway_room_grant_secret(root: Path | str | None = None) -> bytes: installation root, is not exposed by configuration or capability RPCs, and is shared only by the gateway processes that serve this installation. """ - if root is None: from hermes_constants import get_hermes_home # Profile routing uses a context-local HERMES_HOME override. The process # environment retains the installation root and is the authority here. root = os.environ.get("HERMES_HOME") or get_hermes_home() - home = Path(root).expanduser().resolve() - return _gateway_room_grant_secret_for_home(str(home)) + return _gateway_room_grant_secret_for_home(str(Path(root).expanduser().resolve())) def derive_room_grant_secret(api_key: str) -> bytes: @@ -132,26 +126,18 @@ def derive_room_grant_secret(api_key: str) -> bytes: """ if not isinstance(api_key, str) or len(api_key) < 8: raise HostedRoomGrantError("room grants require a strong gateway API key") - return hmac.new( - api_key.encode("utf-8"), - b"hermes-hosted-room-grant-v1", - hashlib.sha256, - ).digest() + return hmac.new(api_key.encode("utf-8"), b"hermes-hosted-room-grant-v1", hashlib.sha256).digest() def _identifier(value: Any, *, field: str) -> str: - if not isinstance(value, str): - raise HostedRoomPeerError(f"{field} must be a string") - normalized = value.strip() - if not _IDENTIFIER_RE.fullmatch(normalized): - raise HostedRoomPeerError(f"{field} is invalid") - return normalized + return identifier( + value, label=field, error=HostedRoomPeerError, max_chars=256, pattern=_IDENTIFIER_RE, + invalid=f"{field} is invalid", + ) def _positive_int(value: Any, *, field: str) -> int: - if isinstance(value, bool) or not isinstance(value, int) or value < 1: - raise HostedRoomPeerError(f"{field} must be a positive integer") - return value + return positive_int(value, error=HostedRoomPeerError, message=f"{field} must be a positive integer") def _digest(value: Any, *, field: str) -> str: @@ -160,34 +146,15 @@ def _digest(value: Any, *, field: str) -> str: return value -def _exact_fields( - value: Mapping[str, Any], - *, - required: set[str], - optional: set[str] | None = None, - label: str, -) -> None: - optional = optional or set() - fields = set(value) - missing = required - fields - unknown = fields - required - optional - if missing: - raise HostedRoomPeerError( - f"{label} missing fields: {', '.join(sorted(missing))}" - ) - if unknown: - raise HostedRoomPeerError( - f"{label} unknown fields: {', '.join(sorted(unknown))}" - ) +def _exact_fields(value: Mapping[str, Any], *, required: set[str], optional: set[str] = frozenset(), label: str) -> None: + exact_fields( + value, label=label, required=required, optional=optional, error=HostedRoomPeerError, + missing_fmt="{label} missing fields: {fields}", unknown_fmt="{label} unknown fields: {fields}", + ) def _canonical_json(value: Mapping[str, Any]) -> bytes: - return json.dumps( - value, - sort_keys=True, - separators=(",", ":"), - ensure_ascii=True, - ).encode("ascii") + return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True).encode("ascii") def _b64encode(value: bytes) -> str: @@ -195,13 +162,47 @@ def _b64encode(value: bytes) -> str: def _b64decode(value: str) -> bytes: - padding = "=" * (-len(value) % 4) try: - return base64.urlsafe_b64decode(value + padding) + return base64.urlsafe_b64decode(value + "=" * (-len(value) % 4)) except Exception as exc: raise HostedRoomGrantError("room grant encoding is invalid") from exc +def _split_token(token: str) -> tuple[str, str]: + encoded_token, separator, signature_token = token.partition(".") + if not separator: + raise HostedRoomGrantError("room grant is invalid") + return encoded_token, signature_token + + +def _parse_link_modes(links_raw: Any) -> tuple[LinkMode, ...]: + if not isinstance(links_raw, list) or not links_raw: + raise HostedRoomPeerError("link_modes must be a non-empty list") + if any(item not in _LINK_MODES for item in links_raw): + raise HostedRoomPeerError("link_modes contains an unsupported mode") + return tuple(dict.fromkeys(links_raw)) + + +def _parse_endpoint(endpoint: Any) -> tuple[str | None, str | None, TransportSecurity | None]: + """Return ``(url, reason, transport_security)`` for an advertised endpoint capability.""" + if not isinstance(endpoint, Mapping) or not isinstance(endpoint.get("available"), bool): + raise HostedRoomPeerError("endpoint capability is invalid") + if not endpoint["available"]: + _exact_fields(endpoint, required={"available", "reason"}, label="endpoint capability") + return None, _identifier(endpoint["reason"], field="endpoint.reason"), None + _exact_fields(endpoint, required={"available", "url", "transport_security"}, label="endpoint capability") + url, transport_security = validate_room_link_url(endpoint["url"]) + if endpoint["transport_security"] != transport_security: + raise HostedRoomPeerError("endpoint transport_security does not match its URL") + return url, None, transport_security + + +_CATALOG_FIELDS = { + "installation_id", "protocol_versions", "link_modes", "persistent_process", "text", + "attachments", "execution_policy", "catalog_digest", +} + + @dataclass(frozen=True) class GatewayRoomCatalog: """Authenticated gateway capabilities inherited by its Bots.""" @@ -220,85 +221,25 @@ class GatewayRoomCatalog: @classmethod def from_mapping(cls, value: Mapping[str, Any]) -> "GatewayRoomCatalog": - _exact_fields( - value, - required={ - "installation_id", - "protocol_versions", - "link_modes", - "persistent_process", - "text", - "attachments", - "execution_policy", - "catalog_digest", - }, - optional={"endpoint"}, - label="capability catalog", - ) + _exact_fields(value, required=_CATALOG_FIELDS, optional={"endpoint"}, label="capability catalog") installation_id = _identifier(value["installation_id"], field="installation_id") versions_raw = value["protocol_versions"] if not isinstance(versions_raw, list) or not versions_raw: raise HostedRoomPeerError("protocol_versions must be a non-empty list") - versions = tuple( - sorted({ - _positive_int(item, field="protocol_version") for item in versions_raw - }) - ) - links_raw = value["link_modes"] - if not isinstance(links_raw, list) or not links_raw: - raise HostedRoomPeerError("link_modes must be a non-empty list") - links: list[LinkMode] = [] - for item in links_raw: - if item not in _LINK_MODES: - raise HostedRoomPeerError("link_modes contains an unsupported mode") - if item not in links: - links.append(item) + versions = tuple(sorted({_positive_int(item, field="protocol_version") for item in versions_raw})) + links = _parse_link_modes(value["link_modes"]) for field in ("persistent_process", "text", "attachments"): if not isinstance(value[field], bool): raise HostedRoomPeerError(f"{field} must be a boolean") policy = RoomExecutionPolicy.from_mapping(value["execution_policy"]) - endpoint_url = endpoint_reason = transport_security = None if "endpoint" in value: - endpoint = value["endpoint"] - if not isinstance(endpoint, Mapping) or not isinstance( - endpoint.get("available"), bool - ): - raise HostedRoomPeerError("endpoint capability is invalid") - if endpoint["available"]: - _exact_fields( - endpoint, - required={"available", "url", "transport_security"}, - label="endpoint capability", - ) - endpoint_url, transport_security = validate_room_link_url( - endpoint["url"] - ) - if endpoint["transport_security"] != transport_security: - raise HostedRoomPeerError( - "endpoint transport_security does not match its URL" - ) - else: - _exact_fields( - endpoint, - required={"available", "reason"}, - label="endpoint capability", - ) - endpoint_reason = _identifier( - endpoint["reason"], field="endpoint.reason" - ) + endpoint_url, endpoint_reason, transport_security = _parse_endpoint(value["endpoint"]) catalog = cls( - installation_id=installation_id, - protocol_versions=versions, - link_modes=tuple(links), - persistent_process=value["persistent_process"], - text=value["text"], - attachments=value["attachments"], - execution_policy=policy, - catalog_digest=_digest(value["catalog_digest"], field="catalog_digest"), - endpoint_url=endpoint_url, - endpoint_reason=endpoint_reason, - transport_security=transport_security, + installation_id=installation_id, protocol_versions=versions, link_modes=links, + persistent_process=value["persistent_process"], text=value["text"], attachments=value["attachments"], + execution_policy=policy, catalog_digest=_digest(value["catalog_digest"], field="catalog_digest"), + endpoint_url=endpoint_url, endpoint_reason=endpoint_reason, transport_security=transport_security, ) unsigned = catalog.as_mapping() del unsigned["catalog_digest"] @@ -310,14 +251,10 @@ class GatewayRoomCatalog: def as_mapping(self) -> dict[str, Any]: """Canonical catalog mapping; ``endpoint`` appears only when advertised.""" value = { - "installation_id": self.installation_id, - "protocol_versions": list(self.protocol_versions), - "link_modes": list(self.link_modes), - "persistent_process": self.persistent_process, - "text": self.text, - "attachments": self.attachments, - "execution_policy": self.execution_policy.as_mapping(), - "catalog_digest": self.catalog_digest, + "installation_id": self.installation_id, "protocol_versions": list(self.protocol_versions), + "link_modes": list(self.link_modes), "persistent_process": self.persistent_process, + "text": self.text, "attachments": self.attachments, + "execution_policy": self.execution_policy.as_mapping(), "catalog_digest": self.catalog_digest, } if self.endpoint_url is not None or self.endpoint_reason is not None: value["endpoint"] = self.endpoint_mapping() @@ -326,55 +263,32 @@ class GatewayRoomCatalog: def endpoint_mapping(self) -> dict[str, Any]: """Return the normalized self-advertised endpoint capability.""" if self.endpoint_url is not None: - return { - "available": True, - "url": self.endpoint_url, - "transport_security": self.transport_security, - } - return { - "available": False, - "reason": self.endpoint_reason or "not_configured", - } + return {"available": True, "url": self.endpoint_url, "transport_security": self.transport_security} + return {"available": False, "reason": self.endpoint_reason or "not_configured"} def catalog_mapping( - *, - installation_id: str, - protocol_versions: Iterable[int] = (PROTOCOL_VERSION,), - link_modes: Iterable[LinkMode] = ("direct", "pull"), - persistent_process: bool, - text: bool = True, - attachments: bool = False, - endpoint: Mapping[str, Any] | None = None, - target_profile: str | None = None, + *, installation_id: str, protocol_versions: Iterable[int] = (PROTOCOL_VERSION,), + link_modes: Iterable[LinkMode] = ("direct", "pull"), persistent_process: bool, text: bool = True, + attachments: bool = False, endpoint: Mapping[str, Any] | None = None, target_profile: str | None = None, execution_policy: Mapping[str, Any] | None = None, ) -> dict[str, Any]: """Build a canonical catalog mapping with its digest.""" # A Desktop-managed gateway exits with the app: the caller's flag is only an # upper bound, so call sites that still pass ``True`` stay honest. persistent_process = bool(persistent_process and os.getenv("HERMES_DESKTOP") != "1") + profile = str(target_profile or "").strip() or (os.getenv("HERMES_PROFILE") or "default").strip() or "default" checked_policy = RoomExecutionPolicy.from_mapping( - execution_policy - or execution_policy_mapping( - target_profile=( - str(target_profile or "").strip() - or (os.getenv("HERMES_PROFILE") or "default").strip() - or "default" - ) - ) + execution_policy or execution_policy_mapping(target_profile=profile) ) # A RoomLink run is initiated by another installation. Process-wide YOLO # mode bypasses the scoped approval ContextVar, so rewriting the advertised # policy cannot make it safe: refuse until manual or smart approvals are on. if checked_policy.approval_mode == "off": - raise HostedRoomPeerError( - "remote room execution requires manual or smart approvals" - ) + raise HostedRoomPeerError("remote room execution requires manual or smart approvals") value = { "installation_id": _identifier(installation_id, field="installation_id"), - "protocol_versions": sorted({ - _positive_int(item, field="protocol_version") for item in protocol_versions - }), + "protocol_versions": sorted({_positive_int(item, field="protocol_version") for item in protocol_versions}), # Direct HTTPS/loopback is the only RoomLink transport implemented by # this backend slice. Do not advertise pull/relay placeholders. "link_modes": [mode for mode in dict.fromkeys(link_modes) if mode == "direct"], @@ -382,34 +296,22 @@ def catalog_mapping( "text": bool(text), "attachments": bool(attachments), "execution_policy": checked_policy.as_mapping(), + "endpoint": dict(local_room_link_endpoint() if endpoint is None else endpoint), } - value["endpoint"] = dict( - local_room_link_endpoint() if endpoint is None else endpoint - ) value["catalog_digest"] = hashlib.sha256(_canonical_json(value)).hexdigest() GatewayRoomCatalog.from_mapping(value) return value def local_catalog_mapping( - *, - installation_id: str, - protocol_versions: Iterable[int] = (PROTOCOL_VERSION,), - link_modes: Iterable[LinkMode] = ("direct", "pull"), - text: bool = True, - attachments: bool = False, - target_profile: str | None = None, - execution_policy: Mapping[str, Any] | None = None, + *, installation_id: str, protocol_versions: Iterable[int] = (PROTOCOL_VERSION,), + link_modes: Iterable[LinkMode] = ("direct", "pull"), text: bool = True, attachments: bool = False, + target_profile: str | None = None, execution_policy: Mapping[str, Any] | None = None, ) -> dict[str, Any]: """Build the one truthful catalog advertised by this local process.""" return catalog_mapping( - installation_id=installation_id, - protocol_versions=protocol_versions, - link_modes=link_modes, - persistent_process=True, - text=text, - attachments=attachments, - target_profile=target_profile, + installation_id=installation_id, protocol_versions=protocol_versions, link_modes=link_modes, + persistent_process=True, text=text, attachments=attachments, target_profile=target_profile, execution_policy=execution_policy, ) @@ -423,22 +325,14 @@ def local_room_link_endpoint(value: Any | None = None) -> dict[str, Any]: url, transport_security = validate_room_link_url(configured) except HostedRoomPeerError: return {"available": False, "reason": "invalid_configuration"} - return { - "available": True, - "url": url, - "transport_security": transport_security, - } + return {"available": True, "url": url, "transport_security": transport_security} @lru_cache(maxsize=16) def _room_link_url_from_config(home: str) -> str | None: """Read the restart-scoped user setting without polling config on probes.""" from gateway.config import load_gateway_config - from hermes_constants import ( - get_hermes_home, - reset_hermes_home_override, - set_hermes_home_override, - ) + from hermes_constants import get_hermes_home, reset_hermes_home_override, set_hermes_home_override if str(get_hermes_home()) == home: value = load_gateway_config().room_link_url @@ -462,14 +356,11 @@ def _configured_room_link_url() -> str | None: configured = _room_link_url_from_config(str(home)) if configured: return configured - # RoomLink is a gateway reachability property, not a Bot personality # setting: named profiles may override it but otherwise inherit the process # gateway's root endpoint, so adding a Bot needs no repeated network config. root = get_default_hermes_root() - if root != home: - return _room_link_url_from_config(str(root)) - return None + return _room_link_url_from_config(str(root)) if root != home else None def validate_room_link_url(value: Any) -> tuple[str, TransportSecurity]: @@ -508,23 +399,13 @@ def validate_room_link_url(value: Any) -> tuple[str, TransportSecurity]: # Validator per dispatch field, in validation order. ``prompt`` and # ``prompt_digest`` are checked together against each other in from_mapping. -_DISPATCH_FIELDS: dict[str, Callable[..., Any]] = { - "protocol_version": _positive_int, - "room_id": _identifier, - "home_install_id": _identifier, - "authority_gateway_id": _identifier, - "authority_epoch": _positive_int, - "member_id": _identifier, - "target_install_id": _identifier, - "target_profile": _identifier, - "task_id": _identifier, - "execution_generation": _positive_int, - "source_event_seq": _positive_int, - "cancellation_scope_id": _identifier, - "capability_digest": _digest, - "execution_policy_digest": _digest, - "trace_id": _identifier, -} +_DISPATCH_FIELDS: dict[str, Callable[..., Any]] = dict( + protocol_version=_positive_int, room_id=_identifier, home_install_id=_identifier, + authority_gateway_id=_identifier, authority_epoch=_positive_int, member_id=_identifier, + target_install_id=_identifier, target_profile=_identifier, task_id=_identifier, + execution_generation=_positive_int, source_event_seq=_positive_int, cancellation_scope_id=_identifier, + capability_digest=_digest, execution_policy_digest=_digest, trace_id=_identifier, +) @dataclass(frozen=True) @@ -555,11 +436,7 @@ class HostedMemberDispatch: @classmethod def from_mapping(cls, value: Mapping[str, Any]) -> "HostedMemberDispatch": - _exact_fields( - value, - required=set(_DISPATCH_FIELDS) | {"prompt", "prompt_digest"}, - label="dispatch", - ) + _exact_fields(value, required=set(_DISPATCH_FIELDS) | {"prompt", "prompt_digest"}, label="dispatch") prompt = value["prompt"] if not isinstance(prompt, str) or not prompt.strip(): raise HostedRoomPeerError("prompt must be a non-empty string") @@ -570,51 +447,32 @@ class HostedMemberDispatch: if not hmac.compare_digest(expected_prompt_digest, prompt_digest): raise HostedRoomPeerError("prompt_digest does not match prompt") return cls( - prompt=prompt, - prompt_digest=prompt_digest, - **{ - name: check(value[name], field=name) - for name, check in _DISPATCH_FIELDS.items() - }, + prompt=prompt, prompt_digest=prompt_digest, + **{name: check(value[name], field=name) for name, check in _DISPATCH_FIELDS.items()}, ) +# Grant scope fields, in issue-time validation order; each is validated with +# the same checker as the matching dispatch field (``grant_id`` is an identifier). +_GRANT_SCOPE = ( + "grant_id", "room_id", "home_install_id", "authority_gateway_id", "authority_epoch", + "member_id", "target_install_id", "target_profile", +) _GRANT_FIELDS = { - "version", - "grant_id", - "room_id", - "home_install_id", - "authority_gateway_id", - "authority_epoch", - "member_id", - "target_install_id", - "target_profile", - "execution_policy_digest", - "permissions", - "issued_at", - "expires_at", + "version", *_GRANT_SCOPE, "execution_policy_digest", "permissions", "issued_at", "expires_at", } _GRANT_REFRESH_FIELDS = _GRANT_FIELDS | {"status_expires_at"} +_GRANT_PERMISSIONS = {"approve", "dispatch", "status", "stop"} MAX_DISPATCH_GRANT_TTL_SECONDS = 24 * 60 * 60 MAX_STATUS_GRANT_TTL_SECONDS = 30 * 24 * 60 * 60 def issue_room_grant( - secret: bytes, - *, - grant_id: str, - room_id: str, - home_install_id: str, - authority_gateway_id: str, - authority_epoch: int, - member_id: str, - target_install_id: str, - target_profile: str, + secret: bytes, *, grant_id: str, room_id: str, home_install_id: str, authority_gateway_id: str, + authority_epoch: int, member_id: str, target_install_id: str, target_profile: str, execution_policy_digest: str | None = None, permissions: Iterable[str] = ("approve", "dispatch", "status", "stop"), - issued_at: float | None = None, - ttl_seconds: float = 3600, - status_ttl_seconds: float | None = None, + issued_at: float | None = None, ttl_seconds: float = 3600, status_ttl_seconds: float | None = None, status_expires_at: float | None = None, ) -> str: """Issue a target-verifiable bearer grant scoped to one room member.""" @@ -627,44 +485,28 @@ def issue_room_grant( else float(status_expires_at) ) if ( - not math.isfinite(now) - or ttl_seconds <= 0 - or ttl_seconds > MAX_DISPATCH_GRANT_TTL_SECONDS - or not math.isfinite(bounded_status_expiry) - or bounded_status_expiry < now + float(ttl_seconds) + not math.isfinite(now) or ttl_seconds <= 0 or ttl_seconds > MAX_DISPATCH_GRANT_TTL_SECONDS + or not math.isfinite(bounded_status_expiry) or bounded_status_expiry < now + float(ttl_seconds) or bounded_status_expiry > now + MAX_STATUS_GRANT_TTL_SECONDS ): raise HostedRoomGrantError("room grant lifetime is invalid") allowed = tuple(sorted(set(permissions))) - if not allowed or not set(allowed) <= { - "approve", - "dispatch", - "status", - "stop", - }: + if not allowed or not set(allowed) <= _GRANT_PERMISSIONS: raise HostedRoomGrantError("room grant permissions are invalid") + scope = { + "grant_id": grant_id, "room_id": room_id, "home_install_id": home_install_id, + "authority_gateway_id": authority_gateway_id, "authority_epoch": authority_epoch, + "member_id": member_id, "target_install_id": target_install_id, "target_profile": target_profile, + } payload = { "version": PROTOCOL_VERSION, - "grant_id": _identifier(grant_id, field="grant_id"), - "room_id": _identifier(room_id, field="room_id"), - "home_install_id": _identifier(home_install_id, field="home_install_id"), - "authority_gateway_id": _identifier( - authority_gateway_id, field="authority_gateway_id" - ), - "authority_epoch": _positive_int( - authority_epoch, field="authority_epoch" - ), - "member_id": _identifier(member_id, field="member_id"), - "target_install_id": _identifier(target_install_id, field="target_install_id"), - "target_profile": _identifier(target_profile, field="target_profile"), + **{name: _DISPATCH_FIELDS.get(name, _identifier)(scope[name], field=name) for name in _GRANT_SCOPE}, "execution_policy_digest": _digest( execution_policy_digest or execution_policy_mapping(target_profile=target_profile)["policy_digest"], field="execution_policy_digest", ), - "permissions": list(allowed), - "issued_at": now, - "expires_at": now + float(ttl_seconds), + "permissions": list(allowed), "issued_at": now, "expires_at": now + float(ttl_seconds), "status_expires_at": bounded_status_expiry, } encoded = _canonical_json(payload) @@ -676,50 +518,24 @@ def issue_room_grant( def verify_room_grant( - secret: bytes, - token: str, - dispatch: HostedMemberDispatch, - *, - permission: str = "dispatch", + secret: bytes, token: str, dispatch: HostedMemberDispatch, *, permission: str = "dispatch", now: float | None = None, ) -> dict[str, Any]: """Verify one room grant against exact recipient dispatch coordinates.""" - payload = decode_room_grant( - secret, - token, - permission=permission, - now=now, - ) + payload = decode_room_grant(secret, token, permission=permission, now=now) if payload["version"] != dispatch.protocol_version: raise HostedRoomGrantError("room grant protocol does not match dispatch") - expected = { - "room_id": dispatch.room_id, - "home_install_id": dispatch.home_install_id, - "authority_gateway_id": dispatch.authority_gateway_id, - "authority_epoch": dispatch.authority_epoch, - "member_id": dispatch.member_id, - "target_install_id": dispatch.target_install_id, - "target_profile": dispatch.target_profile, - "execution_policy_digest": dispatch.execution_policy_digest, - } - if any(payload.get(field) != value for field, value in expected.items()): + scope = (*_GRANT_SCOPE[1:], "execution_policy_digest") + if any(payload.get(field) != getattr(dispatch, field) for field in scope): raise HostedRoomGrantError("room grant scope does not match dispatch") return payload -def decode_room_grant( - secret: bytes, - token: str, - *, - permission: str, - now: float | None = None, -) -> dict[str, Any]: +def decode_room_grant(secret: bytes, token: str, *, permission: str, now: float | None = None) -> dict[str, Any]: """Verify grant signature, lifetime and operation without a dispatch.""" if not isinstance(token, str) or len(token.encode("utf-8")) > MAX_TOKEN_BYTES: raise HostedRoomGrantError("room grant is invalid") - encoded_token, separator, signature_token = token.partition(".") - if not separator: - raise HostedRoomGrantError("room grant is invalid") + encoded_token, signature_token = _split_token(token) encoded = _b64decode(encoded_token) supplied_signature = _b64decode(signature_token) expected_signature = hmac.new(secret, encoded, hashlib.sha256).digest() @@ -730,8 +546,7 @@ def decode_room_grant( except Exception as exc: raise HostedRoomGrantError("room grant payload is invalid") from exc if not isinstance(payload, dict) or frozenset(payload) not in { - frozenset(_GRANT_FIELDS), - frozenset(_GRANT_REFRESH_FIELDS), + frozenset(_GRANT_FIELDS), frozenset(_GRANT_REFRESH_FIELDS), }: raise HostedRoomGrantError("room grant fields are invalid") checked_now = time.time() if now is None else float(now) @@ -744,17 +559,11 @@ def decode_room_grant( except (TypeError, ValueError) as exc: raise HostedRoomGrantError("room grant lifetime is invalid") from exc if not ( - math.isfinite(issued_at) - and math.isfinite(expires_at) - and math.isfinite(status_expires_at) + all(map(math.isfinite, (issued_at, expires_at, status_expires_at))) and issued_at < expires_at <= status_expires_at ): raise HostedRoomGrantError("room grant lifetime is invalid") - operation_expires_at = ( - status_expires_at - if permission in {"approve", "status", "stop"} - else expires_at - ) + operation_expires_at = status_expires_at if permission in {"approve", "status", "stop"} else expires_at if checked_now < issued_at - 30 or checked_now >= operation_expires_at: raise HostedRoomGrantError("room grant is expired or not active") permissions = payload.get("permissions") @@ -763,22 +572,14 @@ def decode_room_grant( return payload -def room_grant_needs_dispatch_refresh( - token: str, - *, - now: float | None = None, - leeway_seconds: float = 5 * 60, -) -> bool: +def room_grant_needs_dispatch_refresh(token: str, *, now: float | None = None, leeway_seconds: float = 5 * 60) -> bool: """Read only grant timing to schedule target-validated refresh. This deliberately does not establish trust; the target validates the signature and immutable scope before issuing a replacement. """ try: - encoded_token, separator, _signature = token.partition(".") - if not separator: - return True - payload = json.loads(_b64decode(encoded_token).decode("ascii")) + payload = json.loads(_b64decode(_split_token(token)[0]).decode("ascii")) expires_at = float(payload["expires_at"]) checked_now = time.time() if now is None else float(now) return checked_now + max(0.0, float(leeway_seconds)) >= expires_at From 7e046408a79294866187f67715f7369bfa0097c7 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Wed, 2 Sep 2026 16:01:31 -0700 Subject: [PATCH 2/2] refactor(gateway/hosted_rooms): peer grant token split/fsync helpers, frozen grant field sets --- gateway/hosted_room_peer.py | 50 +++++++++++++++++++++---------------- 1 file changed, 29 insertions(+), 21 deletions(-) diff --git a/gateway/hosted_room_peer.py b/gateway/hosted_room_peer.py index ce88f47760..a1e547ee2b 100644 --- a/gateway/hosted_room_peer.py +++ b/gateway/hosted_room_peer.py @@ -146,7 +146,9 @@ def _digest(value: Any, *, field: str) -> str: return value -def _exact_fields(value: Mapping[str, Any], *, required: set[str], optional: set[str] = frozenset(), label: str) -> None: +def _exact_fields( + value: Mapping[str, Any], *, required: set[str], optional: set[str] = frozenset(), label: str +) -> None: exact_fields( value, label=label, required=required, optional=optional, error=HostedRoomPeerError, missing_fmt="{label} missing fields: {fields}", unknown_fmt="{label} unknown fields: {fields}", @@ -237,9 +239,11 @@ class GatewayRoomCatalog: endpoint_url, endpoint_reason, transport_security = _parse_endpoint(value["endpoint"]) catalog = cls( installation_id=installation_id, protocol_versions=versions, link_modes=links, - persistent_process=value["persistent_process"], text=value["text"], attachments=value["attachments"], - execution_policy=policy, catalog_digest=_digest(value["catalog_digest"], field="catalog_digest"), - endpoint_url=endpoint_url, endpoint_reason=endpoint_reason, transport_security=transport_security, + persistent_process=value["persistent_process"], text=value["text"], + attachments=value["attachments"], execution_policy=policy, + catalog_digest=_digest(value["catalog_digest"], field="catalog_digest"), + endpoint_url=endpoint_url, endpoint_reason=endpoint_reason, + transport_security=transport_security, ) unsigned = catalog.as_mapping() del unsigned["catalog_digest"] @@ -263,7 +267,9 @@ class GatewayRoomCatalog: def endpoint_mapping(self) -> dict[str, Any]: """Return the normalized self-advertised endpoint capability.""" if self.endpoint_url is not None: - return {"available": True, "url": self.endpoint_url, "transport_security": self.transport_security} + return { + "available": True, "url": self.endpoint_url, "transport_security": self.transport_security, + } return {"available": False, "reason": self.endpoint_reason or "not_configured"} @@ -277,7 +283,9 @@ def catalog_mapping( # A Desktop-managed gateway exits with the app: the caller's flag is only an # upper bound, so call sites that still pass ``True`` stay honest. persistent_process = bool(persistent_process and os.getenv("HERMES_DESKTOP") != "1") - profile = str(target_profile or "").strip() or (os.getenv("HERMES_PROFILE") or "default").strip() or "default" + profile = ( + str(target_profile or "").strip() or (os.getenv("HERMES_PROFILE") or "default").strip() or "default" + ) checked_policy = RoomExecutionPolicy.from_mapping( execution_policy or execution_policy_mapping(target_profile=profile) ) @@ -288,13 +296,13 @@ def catalog_mapping( raise HostedRoomPeerError("remote room execution requires manual or smart approvals") value = { "installation_id": _identifier(installation_id, field="installation_id"), - "protocol_versions": sorted({_positive_int(item, field="protocol_version") for item in protocol_versions}), + "protocol_versions": sorted( + {_positive_int(item, field="protocol_version") for item in protocol_versions} + ), # Direct HTTPS/loopback is the only RoomLink transport implemented by # this backend slice. Do not advertise pull/relay placeholders. "link_modes": [mode for mode in dict.fromkeys(link_modes) if mode == "direct"], - "persistent_process": persistent_process, - "text": bool(text), - "attachments": bool(attachments), + "persistent_process": persistent_process, "text": bool(text), "attachments": bool(attachments), "execution_policy": checked_policy.as_mapping(), "endpoint": dict(local_room_link_endpoint() if endpoint is None else endpoint), } @@ -458,9 +466,9 @@ _GRANT_SCOPE = ( "grant_id", "room_id", "home_install_id", "authority_gateway_id", "authority_epoch", "member_id", "target_install_id", "target_profile", ) -_GRANT_FIELDS = { +_GRANT_FIELDS = frozenset({ "version", *_GRANT_SCOPE, "execution_policy_digest", "permissions", "issued_at", "expires_at", -} +}) _GRANT_REFRESH_FIELDS = _GRANT_FIELDS | {"status_expires_at"} _GRANT_PERMISSIONS = {"approve", "dispatch", "status", "stop"} MAX_DISPATCH_GRANT_TTL_SECONDS = 24 * 60 * 60 @@ -531,7 +539,9 @@ def verify_room_grant( return payload -def decode_room_grant(secret: bytes, token: str, *, permission: str, now: float | None = None) -> dict[str, Any]: +def decode_room_grant( + secret: bytes, token: str, *, permission: str, now: float | None = None +) -> dict[str, Any]: """Verify grant signature, lifetime and operation without a dispatch.""" if not isinstance(token, str) or len(token.encode("utf-8")) > MAX_TOKEN_BYTES: raise HostedRoomGrantError("room grant is invalid") @@ -545,9 +555,7 @@ def decode_room_grant(secret: bytes, token: str, *, permission: str, now: float payload = json.loads(encoded.decode("ascii")) except Exception as exc: raise HostedRoomGrantError("room grant payload is invalid") from exc - if not isinstance(payload, dict) or frozenset(payload) not in { - frozenset(_GRANT_FIELDS), frozenset(_GRANT_REFRESH_FIELDS), - }: + if not isinstance(payload, dict) or frozenset(payload) not in {_GRANT_FIELDS, _GRANT_REFRESH_FIELDS}: raise HostedRoomGrantError("room grant fields are invalid") checked_now = time.time() if now is None else float(now) if not math.isfinite(checked_now): @@ -558,10 +566,8 @@ def decode_room_grant(secret: bytes, token: str, *, permission: str, now: float status_expires_at = float(payload.get("status_expires_at", expires_at)) except (TypeError, ValueError) as exc: raise HostedRoomGrantError("room grant lifetime is invalid") from exc - if not ( - all(map(math.isfinite, (issued_at, expires_at, status_expires_at))) - and issued_at < expires_at <= status_expires_at - ): + finite = all(map(math.isfinite, (issued_at, expires_at, status_expires_at))) + if not (finite and issued_at < expires_at <= status_expires_at): raise HostedRoomGrantError("room grant lifetime is invalid") operation_expires_at = status_expires_at if permission in {"approve", "status", "stop"} else expires_at if checked_now < issued_at - 30 or checked_now >= operation_expires_at: @@ -572,7 +578,9 @@ def decode_room_grant(secret: bytes, token: str, *, permission: str, now: float return payload -def room_grant_needs_dispatch_refresh(token: str, *, now: float | None = None, leeway_seconds: float = 5 * 60) -> bool: +def room_grant_needs_dispatch_refresh( + token: str, *, now: float | None = None, leeway_seconds: float = 5 * 60 +) -> bool: """Read only grant timing to schedule target-validated refresh. This deliberately does not establish trust; the target validates the