@securecoms/agent-bridge 0.6.0 → 0.8.0

package/connectors/hermes/tests/test_adapter_wiring.py

@@ -0,0 +1,541 @@
+# packages/connect-agent-bridge/connectors/hermes/tests/test_adapter_wiring.py
+#
+# adapter.py imports `gateway.*` (Hermes-only packages, absent from the
+# connect-app backend venv - spec §6's CI-honest split: ALL contract logic
+# lives in securecoms_transport.py/securecoms_gate.py, which are
+# gateway-import-free and covered case-for-case by
+# test_securecoms_transport.py/test_securecoms_gate.py). adapter.py itself is thin
+# glue over that contract layer, and its correctness on the real gateway is
+# proven by live validation (spec §6) - but the WIRING itself (which seam
+# calls which transport/gate function, in what order, with what fallback) is
+# still red-first testable without a real Hermes install, by installing a
+# minimal STUB of gateway.platforms.base / gateway.config into sys.modules
+# before importing adapter (F5). The stub covers only what adapter.py
+# actually touches: BasePlatformAdapter's
+# _mark_connected/_mark_disconnected/_set_fatal_error/handle_message/
+# set_message_handler/build_source, plus MessageEvent/SendResult/Platform/
+# MessageType.
+
+import asyncio
+import json
+import os
+import sys
+import types
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Optional
+
+import aiohttp
+import pytest
+
+
+def _install_gateway_stub():
+    """Install a stub gateway.platforms.base / gateway.config BEFORE
+    adapter.py's module-level `from gateway.platforms.base import ...`
+    executes. Must run before `import adapter` below."""
+
+    gateway_pkg = types.ModuleType("gateway")
+    platforms_pkg = types.ModuleType("gateway.platforms")
+    base_mod = types.ModuleType("gateway.platforms.base")
+    config_mod = types.ModuleType("gateway.config")
+
+    class Platform:
+        def __init__(self, value):
+            self.value = value
+
+    class MessageType(Enum):
+        TEXT = "text"
+
+    @dataclass
+    class MessageEvent:
+        text: str
+        message_type: Any = None
+        source: Any = None
+        message_id: Optional[str] = None
+        timestamp: Any = field(default_factory=datetime.now)
+
+    @dataclass
+    class SendResult:
+        success: bool
+        message_id: Optional[str] = None
+        error: Optional[str] = None
+
+    class BasePlatformAdapter:
+        """Stub covering only the seams SecureComsAdapter touches."""
+
+        def __init__(self, config, platform):
+            self.config = config
+            self.platform = platform
+            self._message_handler = None
+            self.mark_connected_calls = 0
+            self.mark_disconnected_calls = 0
+            self.fatal_errors = []  # list[(code, message, retryable)]
+
+        def set_message_handler(self, handler):
+            self._message_handler = handler
+
+        def _mark_connected(self):
+            self.mark_connected_calls += 1
+
+        def _mark_disconnected(self):
+            self.mark_disconnected_calls += 1
+
+        def _set_fatal_error(self, code, message, *, retryable):
+            self.fatal_errors.append((code, message, retryable))
+
+        async def handle_message(self, event):
+            if self._message_handler:
+                await self._message_handler(event)
+
+        def build_source(
+            self,
+            chat_id,
+            chat_name=None,
+            chat_type="dm",
+            user_id=None,
+            user_name=None,
+            **kw,
+        ):
+            return types.SimpleNamespace(
+                chat_id=chat_id,
+                chat_name=chat_name,
+                chat_type=chat_type,
+                user_id=user_id,
+                user_name=user_name,
+            )
+
+    base_mod.BasePlatformAdapter = BasePlatformAdapter
+    base_mod.SendResult = SendResult
+    base_mod.MessageEvent = MessageEvent
+    base_mod.MessageType = MessageType
+    config_mod.Platform = Platform
+
+    sys.modules["gateway"] = gateway_pkg
+    sys.modules["gateway.platforms"] = platforms_pkg
+    sys.modules["gateway.platforms.base"] = base_mod
+    sys.modules["gateway.config"] = config_mod
+
+
+_install_gateway_stub()
+
+import adapter  # noqa: E402  (must import AFTER the gateway stub is installed)
+
+
+# ---------------------------------------------------------------------------
+# Fakes: a minimal aiohttp.ClientSession/WS surface, recording what happened.
+# ---------------------------------------------------------------------------
+
+
+class _FakeWSMsg:
+    def __init__(self, type_, data=None):
+        self.type = type_
+        self.data = data
+
+
+class FakeWS:
+    def __init__(self, frames=None):
+        self._frames = list(frames or [])
+        self.closed = False
+        self.sent = []
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        if not self._frames:
+            raise StopAsyncIteration
+        return self._frames.pop(0)
+
+    async def send_json(self, payload):
+        self.sent.append(payload)
+
+    async def close(self):
+        self.closed = True
+
+
+class _FakeGetResponse:
+    def __init__(self, payload):
+        self._payload = payload
+
+    async def json(self):
+        return self._payload
+
+
+class _FakePostResponse:
+    def __init__(self, status, body):
+        self.status = status
+        self._body = body
+
+    async def json(self):
+        return self._body
+
+    async def text(self):
+        return self._body if isinstance(self._body, str) else json.dumps(self._body)
+
+
+class _FakePostCtx:
+    def __init__(self, response):
+        self._response = response
+
+    async def __aenter__(self):
+        return self._response
+
+    async def __aexit__(self, *exc):
+        return False
+
+
+class FakeSession:
+    """Records every call; ws_connect/post return canned fakes."""
+
+    def __init__(self, healthz_by_url=None, ws=None, post_response=None):
+        self._healthz_by_url = healthz_by_url or {}
+        self._ws = ws
+        self._post_response = post_response  # (status, body) or None
+        self.closed = False
+        self.get_calls = []
+        self.ws_connect_calls = []
+        self.post_calls = []
+
+    async def get(self, url):
+        self.get_calls.append(url)
+        if url not in self._healthz_by_url:
+            raise ConnectionError(f"connection refused: {url}")
+        return _FakeGetResponse(self._healthz_by_url[url])
+
+    async def ws_connect(self, url, headers=None, heartbeat=None):
+        self.ws_connect_calls.append((url, headers, heartbeat))
+        return self._ws
+
+    def post(self, url, headers=None, json=None):
+        self.post_calls.append((url, headers, json))
+        status, body = self._post_response
+        return _FakePostCtx(_FakePostResponse(status, body))
+
+    async def close(self):
+        self.closed = True
+
+
+BINDING_PATH = "/plugin/securecoms.binding.json"
+CONNECTIONS_DIR = "/home/.securecoms/connections"
+
+
+def make_fs(files: dict):
+    def read(path):
+        v = files.get(path)
+        if v is None:
+            raise FileNotFoundError(f"ENOENT: {path}")
+        return v
+
+    return read
+
+
+def binding(identity_id="A"):
+    return json.dumps({"identity_id": identity_id})
+
+
+def conn_file(bridge_url="ws://127.0.0.1:9001/v1/ws", token_file="/tok/A", identity_id="A"):
+    return json.dumps(
+        {
+            "identity_id": identity_id,
+            "bridge_url": bridge_url,
+            "token_file": token_file,
+        }
+    )
+
+
+def make_adapter(monkeypatch, files=None):
+    files = dict(files or {})
+    monkeypatch.setattr(adapter, "_read_file_text", make_fs(files))
+    monkeypatch.setattr(adapter, "_BINDING_PATH", BINDING_PATH)
+    monkeypatch.setattr(adapter, "_CONNECTIONS_DIR", CONNECTIONS_DIR)
+    cfg = types.SimpleNamespace(extra={})
+    a = adapter.SecureComsAdapter(cfg)
+    return a, files
+
+
+# ---------------------------------------------------------------------------
+# (1) Echo guard: inbound frame with sender_id == bound_identity is dropped
+# ---------------------------------------------------------------------------
+
+
+class TestEchoGuardWiring:
+    @pytest.mark.asyncio
+    async def test_own_sender_dropped_no_dispatch_but_still_acked(self, monkeypatch):
+        a, _ = make_adapter(monkeypatch)
+        a._bound_identity = "A"
+        handled = []
+
+        async def handler(event):
+            handled.append(event)
+
+        a.set_message_handler(handler)
+
+        frame = {
+            "type": "message",
+            "sender_id": "A",  # == bound_identity: our own echoed send
+            "channel_id": "chan-1",
+            "text": "echo",
+            "message_id": "m1",
+        }
+        ws = FakeWS(
+            [
+                _FakeWSMsg(aiohttp.WSMsgType.TEXT, json.dumps(frame)),
+                _FakeWSMsg(aiohttp.WSMsgType.CLOSED),
+            ]
+        )
+        a._ws = ws
+
+        await a._pump()
+
+        assert handled == []
+        assert ws.sent == [{"type": "ack", "message_id": "m1"}]
+
+    @pytest.mark.asyncio
+    async def test_other_sender_is_dispatched(self, monkeypatch):
+        a, _ = make_adapter(monkeypatch)
+        a._bound_identity = "A"
+        handled = []
+
+        async def handler(event):
+            handled.append(event)
+
+        a.set_message_handler(handler)
+
+        frame = {
+            "type": "message",
+            "sender_id": "B",
+            "channel_id": "chan-1",
+            "text": "hi",
+            "message_id": "m2",
+        }
+        ws = FakeWS(
+            [
+                _FakeWSMsg(aiohttp.WSMsgType.TEXT, json.dumps(frame)),
+                _FakeWSMsg(aiohttp.WSMsgType.CLOSED),
+            ]
+        )
+        a._ws = ws
+
+        await a._pump()
+
+        assert len(handled) == 1
+        assert handled[0].text == "hi"
+        assert ws.sent == [{"type": "ack", "message_id": "m2"}]
+
+
+# ---------------------------------------------------------------------------
+# (2) send() success fires the status manager's on_reply_posted
+# ---------------------------------------------------------------------------
+
+
+class TestSendWiring:
+    @pytest.mark.asyncio
+    async def test_send_success_fires_on_reply_posted(self, monkeypatch):
+        a, _ = make_adapter(monkeypatch)
+        calls = []
+
+        async def fake_on_reply_posted(channel_id):
+            calls.append(channel_id)
+
+        monkeypatch.setattr(a._status, "on_reply_posted", fake_on_reply_posted)
+
+        a._session = FakeSession(post_response=(200, {"message_id": "42"}))
+        a.bridge_url = "http://127.0.0.1:9001"
+        a._token = "tok"
+
+        result = await a.send("chan-1", "hello")
+
+        assert result.success is True
+        assert calls == ["chan-1"]
+
+    @pytest.mark.asyncio
+    async def test_send_failure_does_not_fire_on_reply_posted(self, monkeypatch):
+        a, _ = make_adapter(monkeypatch)
+        calls = []
+
+        async def fake_on_reply_posted(channel_id):
+            calls.append(channel_id)
+
+        monkeypatch.setattr(a._status, "on_reply_posted", fake_on_reply_posted)
+
+        a._session = FakeSession(post_response=(503, {}))
+        a.bridge_url = "http://127.0.0.1:9001"
+        a._token = "tok"
+
+        result = await a.send("chan-1", "hello")
+
+        assert result.success is False
+        assert result.error == "channel_pending"
+        assert calls == []
+
+
+# ---------------------------------------------------------------------------
+# (3) hold path: probe_and_gate_bound returns (None, reason) -> fatal error
+#     retryable=True AND the per-attempt session is closed
+# ---------------------------------------------------------------------------
+
+
+class TestHoldPathWiring:
+    @pytest.mark.asyncio
+    async def test_hold_sets_retryable_fatal_error_and_closes_session(self, monkeypatch):
+        a, _ = make_adapter(monkeypatch, files={})  # no connection file for "A" at all
+        a._bound_identity = "A"
+
+        session = FakeSession()  # every GET raises; also no connection file to read anyway
+        monkeypatch.setattr(adapter, "_new_client_session", lambda: session)
+
+        ok = await a._open_ws()
+
+        assert ok is False
+        assert session.closed is True
+        assert a.fatal_errors, "expected _set_fatal_error to have been called"
+        code, message, retryable = a.fatal_errors[-1]
+        assert retryable is True
+        assert session.ws_connect_calls == []
+
+    @pytest.mark.asyncio
+    async def test_hold_logs_once_per_state_change_not_per_retry(self, monkeypatch, caplog):
+        a, _ = make_adapter(monkeypatch, files={})
+        a._bound_identity = "A"
+
+        import logging
+
+        caplog.set_level(logging.WARNING, logger="adapter")
+
+        for _ in range(3):
+            session = FakeSession()
+            monkeypatch.setattr(adapter, "_new_client_session", lambda s=session: s)
+            ok = await a._open_ws()
+            assert ok is False
+
+        hold_lines = [r for r in caplog.records if "waiting for SecureComs daemon" in r.message]
+        assert len(hold_lines) == 1, "same-reason holds must log once, not per retry"
+
+
+# ---------------------------------------------------------------------------
+# (4) send_typing -> status manager's on_typing
+# ---------------------------------------------------------------------------
+
+
+class TestSendTypingWiring:
+    @pytest.mark.asyncio
+    async def test_send_typing_calls_on_typing(self, monkeypatch):
+        a, _ = make_adapter(monkeypatch)
+        calls = []
+
+        async def fake_on_typing(channel_id):
+            calls.append(channel_id)
+
+        monkeypatch.setattr(a._status, "on_typing", fake_on_typing)
+
+        await a.send_typing("chan-9")
+
+        assert calls == ["chan-9"]
+
+
+# ---------------------------------------------------------------------------
+# REQUIRED: BINDING-STABILITY - a binding-file rewrite between attempts must
+# NOT re-bind a running connector. bound_identity is resolved once (mirrored
+# here as a direct field set, standing in for connect()'s one-shot
+# resolution); every subsequent attempt must keep using that fixed value even
+# though the on-disk binding (and, in this adversarial setup, the connection
+# file + daemon at the SAME path our fixed identity reads) now agree on a
+# DIFFERENT identity - check 2 refuses, and zero re-bind occurs.
+# ---------------------------------------------------------------------------
+
+
+class TestBindingStabilityAcrossReconnect:
+    @pytest.mark.asyncio
+    async def test_stays_anchored_to_original_identity_after_binding_rewrite(self, monkeypatch):
+        files = {
+            BINDING_PATH: binding("A"),
+            CONNECTIONS_DIR + "/A.json": conn_file(identity_id="A"),
+            "/tok/A": "token-A",
+        }
+        a, files = make_adapter(monkeypatch, files=files)
+
+        # Attempt 1: connect()'s one-shot resolution, mirrored directly here.
+        a._bound_identity = adapter.resolve_bound_identity(
+            {}, adapter._read_file_text, adapter._BINDING_PATH
+        )
+        assert a._bound_identity == "A"
+
+        session1 = FakeSession(
+            healthz_by_url={"http://127.0.0.1:9001/healthz": {"identity_id": "A"}},
+            ws=FakeWS(),
+        )
+        monkeypatch.setattr(adapter, "_new_client_session", lambda: session1)
+        ok1 = await a._open_ws()
+        assert ok1 is True
+        assert a._bound_identity == "A"
+
+        # An external rewrite: the binding file now names "B", AND the
+        # connection-file slot our fixed identity reads (plus the daemon
+        # reachable there) now self-consistently describe "B" too - the
+        # exact scenario check 2 exists to catch even when file+daemon
+        # agree with each other.
+        files[BINDING_PATH] = binding("B")
+        files[CONNECTIONS_DIR + "/A.json"] = conn_file(identity_id="B")
+        session2 = FakeSession(
+            healthz_by_url={"http://127.0.0.1:9001/healthz": {"identity_id": "B"}},
+            ws=FakeWS(),
+        )
+        monkeypatch.setattr(adapter, "_new_client_session", lambda: session2)
+
+        # Attempt 2: bound_identity must NEVER be re-derived from the
+        # (now-rewritten) binding file.
+        ok2 = await a._open_ws()
+
+        assert a._bound_identity == "A", "bound_identity must never be re-derived after connect()"
+        assert ok2 is False, "check 2 must refuse: our bound identity no longer matches the daemon"
+        assert session2.closed is True
+        assert session2.ws_connect_calls == [], "a refused attempt must never open a websocket"
+        code, message, retryable = a.fatal_errors[-1]
+        assert retryable is True
+        assert "check 2 failed" in message
+
+
+# ---------------------------------------------------------------------------
+# check_requirements(): boot-time enablement - binding file OR the
+# SECURECOMS_CONNECTION_FILE override (task-3 review, reviewer one-liner (a)).
+# ---------------------------------------------------------------------------
+
+
+class TestCheckRequirementsWiring:
+    def test_true_when_binding_file_present(self, tmp_path, monkeypatch):
+        binding_path = tmp_path / "securecoms.binding.json"
+        binding_path.write_text(binding("A"))
+        monkeypatch.setattr(adapter, "_BINDING_PATH", str(binding_path))
+        monkeypatch.delenv("SECURECOMS_CONNECTION_FILE", raising=False)
+
+        assert adapter.check_requirements() is True
+
+    def test_false_when_neither_binding_file_nor_env_override_present(self, tmp_path, monkeypatch):
+        monkeypatch.setattr(adapter, "_BINDING_PATH", str(tmp_path / "absent.json"))
+        monkeypatch.delenv("SECURECOMS_CONNECTION_FILE", raising=False)
+
+        assert adapter.check_requirements() is False
+
+    def test_true_when_env_override_points_to_an_existing_file_and_binding_absent(
+        self, tmp_path, monkeypatch
+    ):
+        conn_path = tmp_path / "alt-connection.json"
+        conn_path.write_text(conn_file())
+        monkeypatch.setattr(adapter, "_BINDING_PATH", str(tmp_path / "absent.json"))
+        monkeypatch.setenv("SECURECOMS_CONNECTION_FILE", str(conn_path))
+
+        assert adapter.check_requirements() is True
+
+    def test_false_when_env_override_points_to_a_missing_file_even_if_binding_present(
+        self, tmp_path, monkeypatch
+    ):
+        # The override is a positive, exclusive choice, not a fallback-OR:
+        # a stale/misconfigured SECURECOMS_CONNECTION_FILE must not silently
+        # fall back to the binding file, even when the binding file exists.
+        binding_path = tmp_path / "securecoms.binding.json"
+        binding_path.write_text(binding("A"))
+        monkeypatch.setattr(adapter, "_BINDING_PATH", str(binding_path))
+        monkeypatch.setenv("SECURECOMS_CONNECTION_FILE", str(tmp_path / "does-not-exist.json"))
+
+        assert adapter.check_requirements() is False

package/connectors/hermes/tests/test_securecoms_gate.py

@@ -0,0 +1,113 @@
+# packages/connect-agent-bridge/connectors/hermes/tests/test_securecoms_gate.py
+#
+# Python port of ../../openclaw/gate.test.ts, case-for-case. Reason strings
+# must match gate.js verbatim (audit ADR-0009: the connector contract isn't
+# language-shaped).
+
+import json
+import os
+
+from securecoms_gate import backoff_delay_ms, evaluate_gate, resolve_bound_identity
+
+_GATE_SRC_PATH = os.path.join(os.path.dirname(os.path.dirname(__file__)), "securecoms_gate.py")
+
+
+class TestEvaluateGate:
+    def test_passes_when_file_healthz_bound_all_agree(self):
+        ok, _reason = evaluate_gate("A", "A", "A")
+        assert ok is True
+
+    def test_check_1_fails_on_stale_port_reuse(self):
+        # file A, daemon reports B
+        ok, reason = evaluate_gate("A", "A", "B")
+        assert ok is False
+        assert reason == "check 1 failed: file identity != daemon identity (stale port reuse)"
+
+    def test_check_2_fails_on_wrong_file_compartment_crossing(self):
+        # C1-regression shape: file(A) and daemon(A) agree, but bound to B.
+        ok, reason = evaluate_gate("B", "A", "A")
+        assert ok is False
+        assert reason == "check 2 failed: bound identity != daemon identity (wrong file / compartment)"
+
+    def test_refuses_when_no_binding(self):
+        # refuses when there is no binding (None) - no directory census
+        ok, reason = evaluate_gate(None, "A", "A")
+        assert ok is False
+        assert reason == "unwired: no binding (refusing to guess)"
+
+
+class TestResolveBoundIdentity:
+    def test_reads_identity_from_env_connection_file(self):
+        def read(path):
+            return json.dumps({"identity_id": "A"}) if path == "/conn/A.json" else ""
+
+        result = resolve_bound_identity(
+            {"SECURECOMS_CONNECTION_FILE": "/conn/A.json"},
+            read,
+            "/plugin/securecoms.binding.json",
+        )
+        assert result == "A"
+
+    def test_reads_identity_from_binding_json_when_no_env(self):
+        def read(path):
+            return json.dumps({"identity_id": "B"}) if path == "/plugin/securecoms.binding.json" else ""
+
+        result = resolve_bound_identity({}, read, "/plugin/securecoms.binding.json")
+        assert result == "B"
+
+    def test_returns_none_when_neither_present(self):
+        # connector must wait, never guess
+        def read(_path):
+            raise FileNotFoundError("ENOENT")
+
+        result = resolve_bound_identity({}, read, "/plugin/securecoms.binding.json")
+        assert result is None
+
+
+class TestBackoffDelayMs:
+    def test_ceiling_is_non_decreasing_and_saturates_at_cap(self):
+        # F6: full jitter is NOT monotone. Never assert delay(i) <= delay(i+1)
+        # on jittered output - assert the ceiling instead via rand=lambda:1.0.
+        prev = -1
+        for attempt in range(20):
+            ceiling = backoff_delay_ms(attempt, lambda: 1.0)
+            assert ceiling >= prev
+            assert ceiling <= 30000
+            prev = ceiling
+        assert backoff_delay_ms(19, lambda: 1.0) == 30000
+
+    def test_zero_rand_returns_zero_every_attempt(self):
+        for attempt in range(20):
+            assert backoff_delay_ms(attempt, lambda: 0.0) == 0
+
+    def test_bounded_by_cap_and_never_negative(self):
+        for attempt in range(20):
+            d = backoff_delay_ms(attempt, lambda: 1.0)
+            assert d >= 0
+            assert d <= 30000
+
+    def test_attempt_0_bounded_by_base(self):
+        d = backoff_delay_ms(0, lambda: 1.0)
+        assert 0 <= d <= 250
+
+    def test_attempt_20_bounded_by_cap(self):
+        d = backoff_delay_ms(20, lambda: 1.0)
+        assert d <= 30000
+
+
+class TestNoAutoDiscovery:
+    def test_gate_source_has_zero_directory_census_tokens(self):
+        # Reviewer-recommended trip-wire (task-2-brief.md): pins the ADR-0009
+        # no-auto-discovery property at the source level, not just via the
+        # behavioral "returns None when neither present" test above (which a
+        # future edit could satisfy while ALSO adding a directory-census
+        # fallback that only fires in some other branch). securecoms_gate.py
+        # must never contain os.listdir/os.scandir/glob.glob/iterdir -
+        # bound_identity is a positive wiring act ONLY, never inferred by
+        # scanning a connections directory for a sole entry (audit C1).
+        with open(_GATE_SRC_PATH, "r", encoding="utf-8") as f:
+            source = f.read()
+        for token in ("os.listdir", "os.scandir", "glob.glob", "iterdir"):
+            assert token not in source, (
+                f"securecoms_gate.py must not contain {token!r} (ADR-0009 no-auto-discovery)"
+            )