diff --git a/gateway/config_env.py b/gateway/config_env.py index a1e80ec0be..b5cf0c5e0e 100644 --- a/gateway/config_env.py +++ b/gateway/config_env.py @@ -450,7 +450,11 @@ def _relay(config: GatewayConfig) -> None: relay_url_yaml = str(existing_relay.extra.get("relay_url") or "").strip() if existing_relay else "" relay_url_val = relay_url_env or relay_url_yaml if relay_url_val: - _enable_from_env(config, Platform.RELAY).extra["relay_url"] = relay_url_val.rstrip("/") + relay_config = _enable_from_env(config, Platform.RELAY) + relay_config.extra["relay_url"] = relay_url_val.rstrip("/") + # An opted-out relay does not own this profile's native connections. + if not relay_config.enabled: + return if not relay_url_env or is_truthy_value(getenv("GATEWAY_RELAY_ALLOW_DIRECT_PLATFORMS")): return diff --git a/gateway/config_loader.py b/gateway/config_loader.py index df8f5f6382..fd276eb431 100644 --- a/gateway/config_loader.py +++ b/gateway/config_loader.py @@ -335,20 +335,34 @@ def bridge_core_env_settings(yaml_cfg: dict, platforms_data: dict) -> None: os.environ["SIGNAL_REQUIRE_MENTION"] = str(signal_cfg["require_mention"]).lower() -def load_yaml_layer(home: Path, gw_data: dict) -> None: - """Overlay ``config.yaml`` onto *gw_data* in place. Raises on any failure (caller warns + falls back).""" +def read_yaml_layers(home: Path) -> dict: + """User ``config.yaml`` with the managed overlay applied — the YAML the gateway loader sees. + + Raises on a malformed user file (the loader then falls back to env + gateway.json WITHOUT the + managed layer). An ABSENT user file is an empty layer, not a reason to skip the administrator's + values: a fleet host with no ``config.yaml`` must still honor them. Any pre-activation predicate + (``gateway.relay.relay_explicitly_disabled``) reads through here so it cannot disagree with + ``load_gateway_config()`` on which files count. + """ import yaml config_yaml_path = home / "config.yaml" - if not config_yaml_path.exists(): - return - with open(config_yaml_path, encoding="utf-8") as f: - yaml_cfg = yaml.safe_load(f) or {} + yaml_cfg: dict = {} + if config_yaml_path.exists(): + with open(config_yaml_path, encoding="utf-8") as f: + yaml_cfg = yaml.safe_load(f) or {} # Managed scope: overlay administrator-pinned values (this loader bypasses # hermes_cli.config.load_config, so managed quick_commands / stt would otherwise be ignored). from hermes_cli import managed_scope - yaml_cfg = managed_scope.apply_managed_overlay(yaml_cfg) + return managed_scope.apply_managed_overlay(yaml_cfg) + + +def load_yaml_layer(home: Path, gw_data: dict) -> None: + """Overlay ``read_yaml_layers`` onto *gw_data* in place. Raises on any failure (caller warns + falls back).""" + yaml_cfg = read_yaml_layers(home) + if not yaml_cfg: + return gateway_section = yaml_cfg.get("gateway") bridge_toplevel_keys(yaml_cfg, gateway_section, gw_data) diff --git a/gateway/relay/__init__.py b/gateway/relay/__init__.py index a3acc18146..32a1d6b472 100644 --- a/gateway/relay/__init__.py +++ b/gateway/relay/__init__.py @@ -6,7 +6,8 @@ hands it at handshake, and the production ``WebSocketRelayTransport``. The publi API MAY CHANGE without a deprecation cycle until >=2 real Class-1 platforms have shaken out the schema (``docs/relay-connector-contract.md``). Activation is config-driven: the relay platform is registered when a connector relay URL is set -(``GATEWAY_RELAY_URL`` env or ``gateway.relay_url``), like ``gateway.proxy_url``. +(``GATEWAY_RELAY_URL`` env or ``gateway.relay_url``), like ``gateway.proxy_url``, +unless the effective relay platform configuration explicitly disables it. """ from __future__ import annotations @@ -69,8 +70,39 @@ def _env_or_cfg_url(env_var: str, cfg_key: str) -> Optional[str]: return _env_or_cfg(env_var, cfg_key).rstrip("/") or None +def relay_explicitly_disabled() -> bool: + """``platforms.relay.enabled: false`` in the profile's YAML (user or managed). + + Same files, merge and boolean normalization as the gateway loader (a malformed user + file drops the whole YAML layer there too), minus its env/plugin side effects, so a + standalone scheduler can ask without bootstrapping the gateway. + Mirrors the loader's ``_enabled_explicit`` rule: only a YAML ``enabled`` key is + authoritative — a legacy ``gateway.json`` block is advisory for relay exactly as it + is for every other platform, and an absent key keeps URL-only activation. + """ + from gateway.config import Platform, PlatformConfig + from gateway.config_loader import bridge_platform_shared_keys, merge_platform_sections, read_yaml_layers + from hermes_constants import get_hermes_home + + try: + cfg = read_yaml_layers(get_hermes_home()) + except Exception: # noqa: BLE001 - same fallback as load_gateway_config: no YAML layer at all + return False + if not isinstance(cfg, dict): + return False + gateway = cfg.get("gateway") if isinstance(cfg.get("gateway"), dict) else {} + platforms = merge_platform_sections(cfg, gateway, {}) + bridge_platform_shared_keys(cfg, gateway.get("platforms"), {}, platforms, [Platform.RELAY]) + block = platforms.get("relay") + if not isinstance(block, dict) or not block.get("extra", {}).get("_enabled_explicit"): + return False + return not PlatformConfig.from_dict(block).enabled + + def relay_url() -> Optional[str]: - """The connector relay endpoint URL, or None. A non-empty value activates the relay platform.""" + """Effective connector URL; an explicit platform disable vetoes even an env URL.""" + if relay_explicitly_disabled(): + return None return _env_or_cfg_url("GATEWAY_RELAY_URL", "relay_url") @@ -97,6 +129,8 @@ def relay_fronted_platforms() -> set[str]: Same env source the live adapter's identity set comes from, so config-time validation (cron delivery preflight) and fire-time routing can never disagree — and it needs no live adapter, so a standalone scheduler can use it.""" + if relay_explicitly_disabled(): + return set() return {p for p, _ in relay_platform_identities() if p != "relay"} @@ -641,9 +675,12 @@ def send_relay_policy() -> bool: def register_relay_adapter(force: bool = False, url: Optional[str] = None) -> bool: """Register the generic ``relay`` platform when a relay URL is configured (or - ``force=True`` for tests: transport-less adapter). Returns True if registered. + ``force=True`` for tests: transport-less adapter). Neither overrides an + explicit profile disable. Returns True if registered. With a URL the factory builds a live ``WebSocketRelayTransport``; the adapter negotiates the real ``CapabilityDescriptor`` at ``connect()``.""" + if relay_explicitly_disabled(): + return False resolved_url = url if url is not None else relay_url() if not (force or resolved_url): return False diff --git a/gateway/run_startup.py b/gateway/run_startup.py index 8ce482df1e..8ce6a4c2f3 100644 --- a/gateway/run_startup.py +++ b/gateway/run_startup.py @@ -876,7 +876,8 @@ class GatewayStartupMixin: with _log_suppressed(logging.WARNING, "plugin discovery failed at gateway startup", exc_info=True): from hermes_cli.plugins import discover_plugins discover_plugins() - # Generic relay adapter only if GATEWAY_RELAY_URL / gateway.relay_url is set; no URL -> no-op. + # Relay entrypoints share the effective profile opt-out, including when a + # deployment injects a URL. No URL or explicitly disabled -> no side effects. try: from gateway.relay import ( register_relay_adapter, relay_url, self_provision_relay, send_relay_policy diff --git a/tests/gateway/relay/test_cold_opt_out.py b/tests/gateway/relay/test_cold_opt_out.py new file mode 100644 index 0000000000..ac6705e5db --- /dev/null +++ b/tests/gateway/relay/test_cold_opt_out.py @@ -0,0 +1,64 @@ +"""Standalone relay routing must not bootstrap the gateway or reload secrets.""" +import json +import os +from pathlib import Path +import subprocess +import sys +import textwrap + +import pytest +import yaml + + +@pytest.mark.parametrize("case", ["native", "url-only", "disabled", "managed", "managed-only", "scoped"]) +def test_cold_fronted_platforms_is_read_only(tmp_path, case): + home = tmp_path / "primary" + home.mkdir() + scoped = tmp_path / "secondary" + scoped.mkdir() + managed = tmp_path / "managed" + managed.mkdir() + config = {"platforms": {"relay": {"enabled": True}}} + if case == "disabled": + config["platforms"]["relay"]["enabled"] = False + if case not in {"native", "url-only", "managed-only"}: + (home / "config.yaml").write_text(yaml.safe_dump(config)) + if case in {"managed", "managed-only"}: + (managed / "config.yaml").write_text("platforms:\n relay:\n enabled: false\n") + if case == "scoped": + (scoped / "config.yaml").write_text("platforms:\n relay:\n enabled: false\n") + for root in (home, scoped): + (root / ".env").write_text("GATEWAY_RELAY_SECRET=dotenv-only-test-secret\n") + # Allowlist only: never inherit live credentials, profile selectors, or + # pytest's imported modules. HOME and cwd are temporary as well as HERMES_HOME. + env = {k: os.environ[k] for k in ("PATH", "SYSTEMROOT", "WINDIR") if k in os.environ} + env.update({"HOME": str(tmp_path), "USERPROFILE": str(tmp_path), + "HERMES_HOME": str(home), "HERMES_MANAGED_DIR": str(managed), + "PYTHONPATH": str(Path(__file__).resolve().parents[3]), + "PYTHONDONTWRITEBYTECODE": "1", "PYTHONUTF8": "1"}) + if case != "native": + env.update({"GATEWAY_RELAY_URL": "wss://connector.example/relay", + "GATEWAY_RELAY_PLATFORMS": "slack", + "GATEWAY_RELAY_SECRET": "inherited-test-secret"}) + code = textwrap.dedent(""" + import json, os, sys + from hermes_constants import set_hermes_home_override + if sys.argv[1] == "scoped": + set_hermes_home_override(sys.argv[2]) + before = dict(os.environ) + assert "gateway.run" not in sys.modules + from gateway.relay import relay_fronted_platforms + fronted = relay_fronted_platforms() + changed = {k: [before.get(k), os.environ.get(k)] + for k in before.keys() | os.environ.keys() + if before.get(k) != os.environ.get(k)} + print(json.dumps({"fronted": sorted(fronted), + "bootstrapped": "gateway.run" in sys.modules, + "changed_env": changed})) + """) + child = subprocess.run([sys.executable, "-c", code, case, str(scoped)], + cwd=tmp_path, env=env, text=True, capture_output=True, timeout=45) + assert child.returncode == 0, child.stderr + observed = json.loads(child.stdout.splitlines()[-1]) + assert observed == {"fronted": ["slack"] if case == "url-only" else [], + "bootstrapped": False, "changed_env": {}} diff --git a/tests/gateway/relay/test_explicit_disable.py b/tests/gateway/relay/test_explicit_disable.py new file mode 100644 index 0000000000..fb3114b264 --- /dev/null +++ b/tests/gateway/relay/test_explicit_disable.py @@ -0,0 +1,143 @@ +"""``platforms.relay.enabled: false`` beats a deployment-injected relay URL. + +Real profile files under a temp HERMES_HOME, the production startup hook and the +standalone predicate. Only the connector HTTP calls are replaced. +""" +from unittest.mock import Mock +import json +import os + +import pytest +import yaml + +import gateway.relay as relay +from gateway.config import Platform, load_gateway_config +from gateway.platform_registry import platform_registry +from gateway.run_startup import GatewayStartupMixin + +URL = "wss://connector.example/relay" +DISABLE = {"relay": {"enabled": False}} + +# Every place the loader accepts a relay block, plus the managed overlay. The verdict must be +# the same whichever one the operator used. +SPELLINGS = { + "top": {"platforms": DISABLE}, + "nested": {"gateway": {"platforms": DISABLE}}, + "string-false": {"platforms": {"relay": {"enabled": "false"}}}, + "top-beats-nested": {"platforms": DISABLE, "gateway": {"platforms": {"relay": {"enabled": True}}}}, + "managed": None, # user YAML absent; disable comes from HERMES_MANAGED_DIR +} + + +@pytest.fixture +def profile(tmp_path, monkeypatch): + monkeypatch.setenv("HERMES_HOME", str(tmp_path)) + for key in list(os.environ): + if key.startswith("GATEWAY_RELAY_"): + monkeypatch.delenv(key) + # A deployment stamp: URL + identity provider, no pinned secret, so an + # un-vetoed boot would resolve a token and provision credentials. + monkeypatch.setenv("GATEWAY_RELAY_URL", URL) + monkeypatch.setenv("GATEWAY_RELAY_PLATFORMS", "slack") + monkeypatch.setenv("GATEWAY_RELAY_IDP_TOKEN_URL", "https://identity.example/token") + monkeypatch.setenv("SLACK_BOT_TOKEN", "native-test-token") + monkeypatch.setattr("hermes_cli.plugins.discover_plugins", lambda: None) + monkeypatch.setattr(GatewayStartupMixin, "_register_config_hooks", lambda *a, **k: None) + platform_registry.unregister("relay") + yield tmp_path + platform_registry.unregister("relay") + + +def write_disable(home, spelling, monkeypatch): + doc = SPELLINGS[spelling] + if doc is None: + managed = home / "managed" + managed.mkdir() + (managed / "config.yaml").write_text(yaml.safe_dump({"platforms": DISABLE})) + monkeypatch.setenv("HERMES_MANAGED_DIR", str(managed)) + return + (home / "config.yaml").write_text(yaml.safe_dump(doc)) + + +@pytest.mark.parametrize("spelling", list(SPELLINGS)) +def test_disabled_relay_startup_hook_has_no_side_effects(profile, monkeypatch, spelling): + write_disable(profile, spelling, monkeypatch) + http = Mock(side_effect=AssertionError("disabled relay reached the connector")) + monkeypatch.setattr("urllib.request.urlopen", http) + monkeypatch.setattr(relay, "_resolve_relay_identity_token", http) + before = {k: v for k, v in os.environ.items() if k.startswith("GATEWAY_RELAY_")} + + GatewayStartupMixin._start_register_plugins_relay_hooks() + + http.assert_not_called() + assert not platform_registry.is_registered("relay") + assert {k: v for k, v in os.environ.items() if k.startswith("GATEWAY_RELAY_")} == before + # The test seam and an explicit URL do not override the operator either. + assert relay.register_relay_adapter(force=True, url=URL) is False + # Standalone routing (cron preflight) agrees: nothing is relay-fronted. + assert relay.relay_fronted_platforms() == set() + + +def test_url_only_activation_is_unchanged(profile, monkeypatch): + """Control: with no ``enabled`` key the injected URL still activates relay.""" + (profile / "config.yaml").write_text(yaml.safe_dump({"platforms": {"relay": {"extra": {"note": "kept"}}}})) + provision = Mock(return_value={"gatewayId": "g", "secret": "b" * 64, "deliveryKey": "d"}) + monkeypatch.setattr(relay, "_resolve_relay_identity_token", Mock(return_value="identity-token")) + monkeypatch.setattr(relay, "_post_provision", provision) + monkeypatch.setattr(relay, "_post_policy", Mock(return_value=200)) + + GatewayStartupMixin._start_register_plugins_relay_hooks() + + provision.assert_called_once() + assert platform_registry.is_registered("relay") + assert relay.relay_fronted_platforms() == {"slack"} + + +@pytest.mark.parametrize("spelling", list(SPELLINGS)) +def test_predicate_agrees_with_loader_and_keeps_native_adapters(profile, monkeypatch, spelling): + """The standalone predicate and ``load_gateway_config()`` are two readers of one rule, and an + opted-out relay does not own the profile's native connections.""" + write_disable(profile, spelling, monkeypatch) + config = load_gateway_config() + + assert relay.relay_explicitly_disabled() is True + assert config.platforms[Platform.RELAY].enabled is False + # Without the veto GATEWAY_RELAY_URL disables every directly-connected platform. + assert config.platforms[Platform.SLACK].enabled is True + + from cron.scheduler_delivery import _resolve_target_transport + + resolved, error = _resolve_target_transport( + {"id": "job"}, Platform.SLACK, "slack", {"chat_id": "channel"}, {}, config, + ) + assert error is None + assert resolved[1] is config.platforms[Platform.SLACK] + + +def test_legacy_json_disable_is_advisory_like_other_platforms(profile, monkeypatch): + (profile / "gateway.json").write_text(json.dumps({"platforms": { + "relay": {"enabled": False}, + "telegram": {"enabled": False}, + }})) + monkeypatch.setenv("TELEGRAM_BOT_TOKEN", "native-telegram-test-token") + monkeypatch.setenv("GATEWAY_RELAY_ALLOW_DIRECT_PLATFORMS", "true") + config = load_gateway_config() + + # Only a YAML ``enabled`` key sets ``_enabled_explicit``; env presence (the URL, the token) + # re-enables a gateway.json disable for relay exactly as it does for telegram. + assert relay.relay_explicitly_disabled() is False + assert config.platforms[Platform.RELAY].enabled is True + assert config.platforms[Platform.TELEGRAM].enabled is True + + +def test_malformed_user_yaml_drops_the_yaml_layer_for_both_readers(profile, monkeypatch): + """The loader falls back to env + gateway.json WITHOUT the managed layer on a malformed user + file; the predicate must fall back the same way or startup suppresses native adapters for a + relay it then refuses to register.""" + (profile / "config.yaml").write_text("platforms: [\n") + write_disable(profile, "managed", monkeypatch) + config = load_gateway_config() + + assert relay.relay_explicitly_disabled() is False + assert config.platforms[Platform.RELAY].enabled is True + assert relay.relay_url() == URL diff --git a/website/docs/user-guide/messaging/relay.md b/website/docs/user-guide/messaging/relay.md index d12ae3edc5..4ef23c6f60 100644 --- a/website/docs/user-guide/messaging/relay.md +++ b/website/docs/user-guide/messaging/relay.md @@ -96,12 +96,33 @@ environment. ## Configuration -Relay activates when a connector relay URL is configured — there is no -separate feature flag. Deployments that don't set it are unaffected. +Relay activates when a connector relay URL is configured. To keep a profile off +the relay even when the deployment injects a URL, disable the platform in +`config.yaml`: + +```yaml +platforms: + relay: + enabled: false +``` + +- **Explicit disable wins.** With `enabled: false` the gateway does not resolve + an identity token, provision or rewrite `GATEWAY_RELAY_*` credentials, register + the relay adapter or send the relevance policy — even with `gateway.relay_url` + or `GATEWAY_RELAY_URL` set. Native messaging adapters connect as if no relay + URL were present, and cron delivery treats no platform as relay-fronted. +- **Omitting `enabled` keeps URL-based activation.** `enabled: true` still needs + a connector URL. A `gateway.json` `enabled: false` is advisory, as for every + other platform; put the opt-out in `config.yaml` (user or managed). + +The verdict comes from the same files and merge the gateway loader uses (top-level +or `gateway.platforms` block, managed overlay) and is applied at activation time. +Restart the gateway after changing it; an open relay socket is not torn down. +`hermes gateway enroll` remains available while runtime relay is disabled. | Setting | Where | Meaning | |---------|-------|---------| -| `GATEWAY_RELAY_URL` | env (`~/.hermes/.env`) | Connector relay WebSocket URL. Presence enables the relay platform. | +| `GATEWAY_RELAY_URL` | env (`~/.hermes/.env`) | Connector relay WebSocket URL. Enables relay unless explicitly disabled in platform configuration. | | `gateway.relay_url` | `config.yaml` | Same as above, config-file form (env takes precedence). | | `GATEWAY_RELAY_ID` | env | This gateway instance's id (written by `enroll`). | | `GATEWAY_RELAY_SECRET` | env | Per-gateway secret authenticating the WebSocket upgrade (written by `enroll`). |