foxclaw 0.1.0 → 0.1.3

package/python/tests/test_browser.py

@@ -0,0 +1,149 @@
+"""
+浏览器子系统(HIR-Browser 融入)测试 —— 全离线,不启动真实 chromium。
+
+覆盖:
+  1. 核心感知/校验逻辑(FakeDriver):reducer 编号稳定 + navigate 判生效 + noop-click 判失效
+  2. 动作类型校验:非法 type 抛错、from_dict 透传
+  3. BrowserService async 包装(注入假 session):perceive/act 经专用工作线程返回结构化结果
+  4. 可选依赖降级:available()=False 时 perceive/act 返回 available=False 而非崩溃
+  5. close() 幂等 + 关停后再调用被拒
+
+真实浏览器端到端(需 playwright install chromium)不在回归里跑,避免 CI 依赖内核二进制;
+本测试证明的是"融合层的线程/降级/契约"正确,浏览器操作正确性由 HIR 原生逻辑保证。
+"""
+import sys, asyncio
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.browser import BrowserService
+from foxclaw.browser.perception.dom_extractor import DomExtractor
+from foxclaw.browser.perception.element_indexer import ElementIndexer
+from foxclaw.browser.perception.semantic_reducer import SemanticReducer
+from foxclaw.browser.action.action_verifier import ActionVerifier
+from foxclaw.browser.action.action_types import WebAction, SUPPORTED_ACTIONS
+
+
+class FakeDriver:
+    """模拟一个只有一个按钮的页面,可切换 url/title 模拟导航。"""
+    def __init__(self):
+        self.url = "https://fake.test/p1"; self.title = "P1"; self._e = ["h1"]
+    def query_interactive_elements(self, roles): return self._e
+    def describe_element(self, h): return {"role": "button", "text": "提交", "attrs": {}}
+    def get_visible_text(self): return "fake body"
+    def current_url(self): return self.url
+    def current_title(self): return self.title
+
+
+class FakeSnapshot:
+    def to_dict(self): return {"url": "https://fake.test/p1", "title": "P1", "elements": [], "text_summary": ""}
+
+
+class FakeSession:
+    """假会话:不碰 playwright,验证 Service 的线程/契约。"""
+    def __init__(self): self.closed = False
+    def snapshot(self): return FakeSnapshot()
+    def execute(self, action: WebAction):
+        return {"raw": {"navigated_to": action.target}, "semantic_state": FakeSnapshot().to_dict(),
+                "verified": {"success": True, "url_changed": True, "diff": {}}}
+    def close(self): self.closed = True
+
+
+def test_core_logic():
+    print("\n【1】核心感知/校验逻辑(FakeDriver)")
+    d = FakeDriver()
+    reducer = SemanticReducer(DomExtractor(d), ElementIndexer())
+    snap = reducer.reduce()
+    assert snap.elements[0]["id"] == "1" and snap.elements[0]["role"] == "button"
+    print(f"  ✓ reducer 分配编号: id={snap.elements[0]['id']} role={snap.elements[0]['role']}")
+
+    before = reducer.reduce()
+    d.url = "https://fake.test/p2"; d.title = "P2"
+    after = reducer.reduce()
+    v = ActionVerifier()
+    nav = v.verify(before, after, WebAction(type="navigate", target="https://fake.test/p2"))
+    assert nav["success"] and nav["url_changed"]
+    print("  ✓ navigate 判定生效(url 变化)")
+
+    noop = v.verify(reducer.reduce(), reducer.reduce(), WebAction(type="click", target="1"))
+    assert noop["success"] is False
+    print("  ✓ 页面无变化的 click 判定为未生效(抓静默失败)")
+
+
+def test_action_types():
+    print("\n【2】动作类型契约")
+    assert set(SUPPORTED_ACTIONS) == {"navigate", "click", "type", "scroll", "extract", "wait"}
+    raised = False
+    try:
+        WebAction(type="explode")
+    except ValueError:
+        raised = True
+    assert raised, "非法动作类型必须抛 ValueError"
+    a = WebAction.from_dict({"type": "type", "target": "3", "value": "hi", "meta": {"x": 1}})
+    assert a.type == "type" and a.target == "3" and a.value == "hi" and a.meta == {"x": 1}
+    print("  ✓ 非法 type 抛错 + from_dict 透传 target/value/meta")
+
+
+@pytest.mark.anyio
+async def test_service_wrapper():
+    print("\n【3】BrowserService async 包装(注入假 session,经专用工作线程)")
+    svc = BrowserService()
+    fake = FakeSession()
+    svc._session = fake
+    svc.available = lambda: True
+
+    p = await svc.perceive()
+    assert p["ok"] and p["semantic_state"]["title"] == "P1"
+    print(f"  ✓ perceive() 经工作线程返回语义结构: title={p['semantic_state']['title']}")
+
+    r = await svc.act({"type": "navigate", "target": "https://fake.test/p2"})
+    assert r["ok"] and r["verified"]["success"]
+    print("  ✓ act(navigate) 返回校验后结果 verified.success=True")
+
+    bad = await svc.act({"target": "3"})
+    assert bad["ok"] is False and "非法动作" in bad["error"]
+    print("  ✓ 非法动作(缺 type)被结构化拒绝")
+
+    await svc.close()
+    assert fake.closed, "close() 必须在工作线程上释放会话"
+    print("  ✓ close() 释放了会话")
+    await svc.close()
+    after_close = await svc.perceive()
+    assert after_close["ok"] is False
+    print("  ✓ close() 幂等 + 关停后调用被安全拒绝")
+
+
+@pytest.mark.anyio
+async def test_degradation():
+    print("\n【4】可选依赖降级(available=False)")
+    svc = BrowserService()
+    svc.available = staticmethod(lambda: False)
+    p = await svc.perceive()
+    assert p["ok"] is False and p["available"] is False and "playwright" in p["error"]
+    a = await svc.act({"type": "navigate", "target": "x"})
+    assert a["ok"] is False and a["available"] is False
+    print("  ✓ playwright 缺失时 perceive/act 结构化降级,不崩溃")
+    st = svc.status()
+    assert set(["available", "session_active", "closed"]).issubset(st.keys())
+    print(f"  ✓ status() 暴露能力: {st}")
+
+
+def main():
+    print("=" * 60)
+    print("浏览器子系统 · HIR-Browser 融入(全离线)")
+    print("=" * 60)
+    test_core_logic()
+    test_action_types()
+    asyncio.run(test_service_wrapper())
+    asyncio.run(test_degradation())
+    print(f"\n  (真实浏览器可用性: playwright {'已装' if BrowserService.available() else '未装'};"
+          f" 真实 e2e 需 playwright install chromium,不在回归内)")
+    print("\n" + "=" * 60)
+    print("✓ 浏览器子系统验证完成:核心逻辑 + async线程包装 + 降级 + 幂等close")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

package/python/tests/test_browser_request_guard.py

@@ -0,0 +1,180 @@
+"""浏览器请求级准入(跳转 / iframe / 子资源)与路由拦截。
+
+只测判定与回调,不起真浏览器:PlaywrightDriver 的模块顶层不 import playwright,
+用 `object.__new__` 绕过 __init__ 即可直接测 `_on_route`。
+"""
+
+import pytest
+
+from foxclaw.browser.action import url_policy
+from foxclaw.browser.driver.playwright_driver import PlaywrightDriver
+
+
+@pytest.mark.parametrize("url", [
+    "data:image/png;base64,iVBORw0KGgo=",
+    "blob:https://example.com/2f8c-4a",
+    "about:blank",
+])
+def test_internal_schemes_are_allowed(monkeypatch, url):
+    """data:/blob:/about: 由页面自身产生、不过网络栈,拦了只会让内联图片裂掉。"""
+    monkeypatch.delenv("FOXCLAW_BROWSER_ALLOW_PRIVATE", raising=False)
+    assert url_policy.validate_request_url(url) == url
+
+
+@pytest.mark.parametrize("url", [
+    "file:///C:/Windows/win.ini",
+    "javascript:alert(1)",
+    "ftp://example.com/x",
+    "chrome-extension://abcdef/page.html",
+])
+def test_non_http_schemes_are_rejected(monkeypatch, url):
+    monkeypatch.delenv("FOXCLAW_BROWSER_ALLOW_PRIVATE", raising=False)
+    with pytest.raises(ValueError):
+        url_policy.validate_request_url(url)
+
+
+@pytest.mark.parametrize("url", [
+    "http://169.254.169.254/latest/meta-data/",
+    "http://127.0.0.1:8080/admin",
+    "http://[::1]/",
+    "http://10.0.0.5/",
+    "http://192.168.1.1/",
+])
+def test_private_addresses_are_rejected(monkeypatch, url):
+    monkeypatch.delenv("FOXCLAW_BROWSER_ALLOW_PRIVATE", raising=False)
+    with pytest.raises(ValueError):
+        url_policy.validate_request_url(url)
+
+
+def test_allow_private_env_opens_the_gate(monkeypatch):
+    monkeypatch.setenv("FOXCLAW_BROWSER_ALLOW_PRIVATE", "1")
+    assert url_policy.validate_request_url("http://127.0.0.1:8080/") == "http://127.0.0.1:8080/"
+
+
+def test_public_ip_literal_passes_without_dns(monkeypatch):
+    """IP 字面量不该触发解析:断网环境下也得能判定。"""
+    monkeypatch.delenv("FOXCLAW_BROWSER_ALLOW_PRIVATE", raising=False)
+
+    def _boom(*_a, **_k):
+        raise AssertionError("IP 字面量不应该走 getaddrinfo")
+
+    monkeypatch.setattr(url_policy.socket, "getaddrinfo", _boom)
+    assert url_policy.validate_request_url("http://93.184.216.34/x") == "http://93.184.216.34/x"
+
+
+def test_domain_resolving_to_internal_is_rejected(monkeypatch):
+    """域名指向内网必须拒。
+
+    回归点:旧实现把 `raise ValueError` 写在自己那个 `try/except ValueError: continue`
+    里,拒绝分支被同一个 except 吞掉 —— 「域名解析到内网」从来没生效过。
+    """
+    monkeypatch.delenv("FOXCLAW_BROWSER_ALLOW_PRIVATE", raising=False)
+    monkeypatch.setattr(url_policy, "_resolve_internal", lambda host: True)
+    with pytest.raises(ValueError) as ei:
+        url_policy.validate_request_url("http://intranet.example.com/x")
+    assert "内网" in str(ei.value)
+
+
+def test_domain_resolving_to_public_passes(monkeypatch):
+    monkeypatch.delenv("FOXCLAW_BROWSER_ALLOW_PRIVATE", raising=False)
+    monkeypatch.setattr(url_policy, "_resolve_internal", lambda host: False)
+    assert url_policy.validate_request_url(
+        "https://example.com/a.png") == "https://example.com/a.png"
+
+
+def test_resolution_is_cached_between_requests(monkeypatch):
+    """几十个子资源同域:只在首个请求上解析,后续走缓存。"""
+    monkeypatch.delenv("FOXCLAW_BROWSER_ALLOW_PRIVATE", raising=False)
+    url_policy._resolve_cache.clear()
+    calls = []
+
+    def _fake_getaddrinfo(host, *_a, **_k):
+        calls.append(host)
+        return [(2, 1, 6, "", ("93.184.216.34", 0))]
+
+    monkeypatch.setattr(url_policy.socket, "getaddrinfo", _fake_getaddrinfo)
+    for _ in range(5):
+        url_policy.validate_request_url("http://cdn.example.com/a.js")
+    assert calls == ["cdn.example.com"]
+    url_policy._resolve_cache.clear()
+
+
+def test_short_ipv6_with_scope_is_not_mistaken(monkeypatch):
+    """解析结果可能带 scope id(fe80::1%eth0),不能因此算「非内网」。"""
+    monkeypatch.delenv("FOXCLAW_BROWSER_ALLOW_PRIVATE", raising=False)
+    url_policy._resolve_cache.clear()
+    monkeypatch.setattr(url_policy.socket, "getaddrinfo",
+                        lambda host, *a, **k: [(10, 1, 6, "", ("fe80::1%eth0", 0, 0, 1))])
+    with pytest.raises(ValueError):
+        url_policy.validate_request_url("http://v6.example.com/")
+    url_policy._resolve_cache.clear()
+
+
+class _FakeRoute:
+    def __init__(self, url):
+        self.request = type("Req", (), {"url": url})()
+        self.aborted = None
+        self.continued = False
+
+    def abort(self, reason=None):
+        self.aborted = reason or "abort"
+
+    def continue_(self):
+        self.continued = True
+
+
+def _driver(monkeypatch):
+    monkeypatch.delenv("FOXCLAW_BROWSER_ALLOW_PRIVATE", raising=False)
+    d = object.__new__(PlaywrightDriver)
+    d.blocked_requests = []
+    return d
+
+
+def test_route_aborts_internal_subresource(monkeypatch):
+    """子资源打云元数据:这是「只校验 navigate 目标」漏掉的典型。"""
+    d = _driver(monkeypatch)
+    r = _FakeRoute("http://169.254.169.254/latest/meta-data/iam/")
+    d._on_route(r)
+    assert r.aborted == "blockedbyclient"
+    assert r.continued is False
+    assert d.blocked_requests and "169.254" in d.blocked_requests[0][0]
+
+
+def test_route_continues_public_request(monkeypatch):
+    d = _driver(monkeypatch)
+    r = _FakeRoute("http://93.184.216.34/index.html")
+    d._on_route(r)
+    assert r.continued is True and r.aborted is None
+
+
+def test_route_continues_data_uri(monkeypatch):
+    d = _driver(monkeypatch)
+    r = _FakeRoute("data:image/gif;base64,R0lGOD")
+    d._on_route(r)
+    assert r.continued is True and r.aborted is None
+
+
+def test_route_aborts_redirect_target(monkeypatch):
+    """3xx 跳转的目标是独立请求,同样过这一层(否则公网页跳一次转就绕过了)。"""
+    d = _driver(monkeypatch)
+    r = _FakeRoute("http://127.0.0.1:9200/_cat/indices")
+    d._on_route(r)
+    assert r.aborted == "blockedbyclient"
+
+
+def test_blocked_log_is_bounded(monkeypatch):
+    d = _driver(monkeypatch)
+    for i in range(70):
+        d._on_route(_FakeRoute(f"http://127.0.0.1/{i}"))
+    assert len(d.blocked_requests) <= 50
+
+
+def test_route_survives_closed_session(monkeypatch):
+    """回调和 close 竞争时 continue_ 会抛,不能让它冒到 Playwright 的事件循环。"""
+    d = _driver(monkeypatch)
+
+    class _DeadRoute(_FakeRoute):
+        def continue_(self):
+            raise RuntimeError("Target closed")
+
+    d._on_route(_DeadRoute("http://93.184.216.34/x"))

package/python/tests/test_capabilities.py

@@ -0,0 +1,152 @@
+"""
+能力注册中枢(P1-3:God Object → Composition Root)测试 —— 全离线。
+
+覆盖:
+  1. CapabilityRegistry:register / get / register_lazy(首次才构造且只构造一次) / has / names
+  2. 打断两处直接环(结构):
+     · Agent 不再持有 _search_runtime,改持 _caps(经中枢解析 search_runtime)
+     · Orchestrator 不再把 agents 存为实例字段,改为经中枢解析的 property
+  3. 行为保持:cross_request 经中枢解析 agents 仍工作;search_internal 经中枢解析 search_runtime
+"""
+import os, sys, asyncio, tempfile, shutil
+from pathlib import Path
+os.environ.setdefault("HF_HUB_OFFLINE", "1")
+os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
+os.environ["FOXCLAW_EMBEDDING_MODEL"] = "foxclaw-nonexistent-fast"
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.kernel import CapabilityRegistry
+
+
+def test_registry_primitive():
+    print("\n【1】CapabilityRegistry:register / lazy / has / names")
+    reg = CapabilityRegistry()
+    reg.register("a", 123)
+    assert reg.get("a") == 123
+    assert reg.get("missing") is None and reg.get("missing", "d") == "d"
+
+    calls = {"n": 0}
+    def factory():
+        calls["n"] += 1
+        return {"built": True}
+    reg.register_lazy("b", factory)
+    assert reg.has("b") and "b" not in reg._caps, "惰性:注册后未构造"
+    v1 = reg.get("b"); v2 = reg.get("b")
+    assert v1 is v2 and calls["n"] == 1, "惰性只构造一次并缓存"
+    assert set(reg.names()) >= {"a", "b"}
+    print(f"  ✓ register/get/lazy(构造 {calls['n']} 次)/has/names 均正确")
+
+
+def test_cycles_broken_structural():
+    print("\n【2】结构:两处直接环被打断")
+    d = tempfile.mkdtemp(prefix="cap_os_")
+    try:
+        from foxclaw import Foxclaw
+        os_ = Foxclaw(data_dir=d, shadow_rounds=50)
+        assert not hasattr(os_.finance, "_search_runtime"), "Agent 不应有 _search_runtime 直接引用"
+        assert os_.finance._caps is os_.capabilities, "Agent 改持能力中枢"
+        assert "agents" not in os_.orchestrator.__dict__, "orchestrator 不应把 agents 存为实例字段"
+        assert os_.orchestrator._caps is os_.capabilities
+        assert os_.orchestrator.agents is os_._agents, "orchestrator.agents 经中枢解析"
+        print("  ✓ Agent→search / Orchestrator→agents 的直接互持已改为中枢解析")
+        print(f"    capabilities.names() = {os_.capabilities.names()}")
+        asyncio.run(os_.aclose())
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+def test_behavior_preserved():
+    print("\n【3】行为保持:编排 + 双向搜索 经中枢解析仍工作")
+    d = tempfile.mkdtemp(prefix="cap_beh_")
+    try:
+        from foxclaw import Foxclaw
+        os_ = Foxclaw(data_dir=d, shadow_rounds=50)
+        r = os_.supervisor.cross_request(
+            from_agent="admin", to_agent="finance", request_type="budget_request",
+            payload={"amount": 150, "category": "travel", "entity": "高铁", "account": "default"},
+            reason="出差")
+        assert r["status"] in ("approved", "confirm_required", "rejected"), f"裁决异常 {r}"
+        print(f"  ✓ cross_request 经中枢解析 agents → 状态 {r['status']}")
+        res = os_.finance.search_internal("测试查询")
+        assert res is not None, "search_internal 应经中枢解析到 search_runtime"
+        assert os_.capabilities.get("search_runtime") is os_.search_runtime
+        print("  ✓ search_internal 经中枢解析 search_runtime(缓存一致)")
+        asyncio.run(os_.aclose())
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+def test_lazy_build_once_concurrent():
+    print("\n【4】F1:并发下 per-name 惰性只构造一次(慢构造不持全局锁)")
+    import threading, time
+    reg = CapabilityRegistry()
+    calls = {"n": 0}
+    lock = threading.Lock()
+    def slow():
+        time.sleep(0.05)
+        with lock:
+            calls["n"] += 1
+        return object()
+    reg.register_lazy("x", slow)
+    results = []
+    def worker():
+        results.append(reg.get("x"))
+    ts = [threading.Thread(target=worker) for _ in range(12)]
+    for t in ts: t.start()
+    for t in ts: t.join()
+    assert calls["n"] == 1, f"并发下惰性应只构造 1 次,实得 {calls['n']}"
+    assert len({id(r) for r in results}) == 1, "12 线程应拿到同一实例"
+    reg.register_lazy("y", lambda: object())
+    assert reg.get("y") is reg.get("y")
+    print("  ✓ 12 线程并发 get 同一惰性 → 只构造 1 次、同一实例;不同能力独立")
+
+
+def test_hkc_single_init_concurrent():
+    print("\n【5】F2:hkc 惰性属性并发首访只装配一次(防句柄泄漏)")
+    import threading
+    d = tempfile.mkdtemp(prefix="cap_hkc_")
+    try:
+        from foxclaw import Foxclaw
+        import foxclaw.knowledge as K
+        os_ = Foxclaw(data_dir=d, shadow_rounds=50)
+        orig = K.init_hkc
+        cnt = {"n": 0}
+        clock = threading.Lock()
+        def counting(*a, **k):
+            with clock:
+                cnt["n"] += 1
+            return orig(*a, **k)
+        K.init_hkc = counting
+        try:
+            out = []
+            def w():
+                out.append(os_.hkc)
+            ts = [threading.Thread(target=w) for _ in range(10)]
+            for t in ts: t.start()
+            for t in ts: t.join()
+            assert cnt["n"] == 1, f"并发首访 hkc 应只装配 1 次,实得 {cnt['n']}"
+            assert len({id(o) for o in out}) == 1, "10 线程应拿到同一 HKCService"
+            print("  ✓ 10 线程并发首访 os_.hkc → init_hkc 只调 1 次")
+        finally:
+            K.init_hkc = orig
+        asyncio.run(os_.aclose())
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+def main():
+    print("=" * 60)
+    print("能力注册中枢 · Composition Root(P1-3)")
+    print("=" * 60)
+    test_registry_primitive()
+    test_cycles_broken_structural()
+    test_behavior_preserved()
+    test_lazy_build_once_concurrent()
+    test_hkc_single_init_concurrent()
+    print("\n" + "=" * 60)
+    print("✓ P1-3 验证完成:能力中枢 + 两处直接环打断 + 行为保持")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

package/python/tests/test_channel_signing.py

@@ -0,0 +1,185 @@
+"""渠道出站签名 / 入站验签。
+
+锁住:canonical 结构不被随手改、正文与时间戳都在签名覆盖内、重放被拒、header 名大小写
+无关、桥接层"签的就是发的"(content= 的字节)且签名失败 fail-closed 不发。
+"""
+
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+
+from foxclaw.channels import OutboundMessage
+from foxclaw.channels import signing as S
+from foxclaw.channels.openclaw_bridge import OpenClawBridgeAdapter
+
+SECRET = "test-shared-secret"
+
+
+def _headers(secret: str = SECRET, body: bytes = b'{"a":1}', ts: float = 1_700_000_000):
+    signer = S.OutboundSigner(secret, key_id="k1")
+    return signer.headers(body, nonce="n0nce", now=ts)
+
+
+def test_canonical_format_is_locked() -> None:
+    """canonical 是两端的协议:字段顺序/分隔符一改,对方全部验签失败。"""
+    line = S.canonical("1700000000", "abc", b"body").decode()
+    assert line == f"v1\n1700000000\nabc\n{S.body_digest(b'body')}"
+    assert len(line.split("\n")) == 4
+
+
+def test_roundtrip_ok_and_body_tamper_detected() -> None:
+    body = b'{"text":"hi"}'
+    h = _headers(body=body)
+    ok, why = S.verify(h, body, SECRET, now=1_700_000_000)
+    assert (ok, why) == (True, "ok")
+    ok, why = S.verify(h, b'{"text":"transfer 5000"}', SECRET, now=1_700_000_000)
+    assert (ok, why) == (False, "bad_signature"), "正文被改必须失效"
+
+
+def test_timestamp_skew_rejected() -> None:
+    body = b"{}"
+    h = _headers(body=body, ts=1_700_000_000)
+    ok, why = S.verify(h, body, SECRET, tolerance=300, now=1_700_000_000 + 301)
+    assert (ok, why) == (False, "expired")
+    ok, _ = S.verify(h, body, SECRET, tolerance=300, now=1_700_000_000 + 299)
+    assert ok is True
+
+
+def test_signature_cannot_be_forged_with_wrong_secret() -> None:
+    body = b"{}"
+    h = _headers(body=body)
+    ok, why = S.verify(h, body, "another-secret", now=1_700_000_000)
+    assert (ok, why) == (False, "bad_signature")
+
+
+def test_replay_guard_rejects_second_use() -> None:
+    body = b"{}"
+    h = _headers(body=body)
+    guard = S.ReplayGuard(ttl=300)
+    assert S.verify(h, body, SECRET, replay=guard, now=1_700_000_000) == (True, "ok")
+    assert S.verify(h, body, SECRET, replay=guard, now=1_700_000_000) == (False, "replay")
+    h2 = S.OutboundSigner(SECRET).headers(body, nonce="other", now=1_700_000_000)
+    assert S.verify(h2, body, SECRET, replay=guard, now=1_700_000_000) == (True, "ok")
+
+
+def test_verify_reason_codes() -> None:
+    body = b"{}"
+    assert S.verify({}, body, SECRET)[1] == "missing_header"
+    assert S.verify(_headers(body=body), body, "")[1] == "missing_secret"
+    bad = dict(_headers(body=body))
+    bad[S.SIGNATURE_HEADER] = "v2=deadbeef"
+    assert S.verify(bad, body, SECRET, now=1_700_000_000)[1] == "bad_version"
+    no_ts = dict(_headers(body=body))
+    no_ts[S.TIMESTAMP_HEADER] = "not-a-number"
+    assert S.verify(no_ts, body, SECRET)[1] == "bad_version"
+
+
+def test_header_lookup_is_case_insensitive() -> None:
+    body = b"{}"
+    h = {k.lower(): v for k, v in _headers(body=body).items()}
+    assert S.verify(h, body, SECRET, now=1_700_000_000) == (True, "ok")
+
+
+def test_signer_optional_key_id_and_disabled_state() -> None:
+    h = S.OutboundSigner(SECRET, key_id="k9").headers(b"{}")
+    assert h[S.KEY_ID_HEADER] == "k9"
+    assert S.SIGNATURE_HEADER in h and h[S.TIMESTAMP_HEADER].isdigit()
+    off = S.OutboundSigner("")
+    assert off.enabled is False
+    with pytest.raises(ValueError):
+        off.headers(b"{}")
+
+
+def test_from_env_opt_in() -> None:
+    assert S.from_env({}) is None
+    s = S.from_env({S.ENV_SECRET: "abc", S.ENV_KEY_ID: "k2"})
+    assert s is not None and s.key_id == "k2" and s.enabled
+    assert S.from_env({S.ENV_SECRET: "   "}) is None
+
+
+class _Resp:
+    status_code = 200
+    text = ""
+
+    def json(self):
+        return {"message_id": "m1"}
+
+
+class _Client:
+    """捕获真实发出的 (url, content, headers) —— 签名必须覆盖这些字节。"""
+
+    captured: dict = {}
+
+    def __init__(self, *a, **k):
+        pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+    def post(self, url, content=None, headers=None, timeout=None):
+        _Client.captured = {"url": url, "content": content, "headers": dict(headers or {})}
+        return _Resp()
+
+
+@pytest.fixture
+def fake_http(monkeypatch):
+    _Client.captured = {}
+    monkeypatch.setattr(httpx, "Client", _Client)
+    return _Client
+
+
+def _msg() -> OutboundMessage:
+    return OutboundMessage(conversation_id="c1", text="hi", extra={"upstream_channel": "wechat"})
+
+
+def test_bridge_signs_the_bytes_it_sends(fake_http) -> None:
+    bridge = OpenClawBridgeAdapter("http://gw.local", api_token="t",
+                                   signer=S.OutboundSigner(SECRET))
+    res = bridge.send(_msg())
+    assert res.ok and res.message_id == "m1"
+    cap = fake_http.captured
+    body = cap["content"]
+    assert isinstance(body, bytes) and json.loads(body)["text"] == "hi"
+    assert cap["headers"]["Content-Type"] == "application/json"
+    assert cap["headers"]["Authorization"] == "Bearer t"
+    ok, why = S.verify(cap["headers"], body, SECRET)
+    assert (ok, why) == (True, "ok")
+
+
+def test_bridge_unsigned_without_secret(fake_http, monkeypatch) -> None:
+    monkeypatch.delenv(S.ENV_SECRET, raising=False)
+    bridge = OpenClawBridgeAdapter("http://gw.local")
+    assert bridge.signer is None
+    assert bridge.send(_msg()).ok
+    assert S.SIGNATURE_HEADER not in fake_http.captured["headers"]
+    assert fake_http.captured["headers"]["Content-Type"] == "application/json"
+
+
+def test_bridge_fail_closed_when_signing_fails(fake_http) -> None:
+    class _Broken:
+        enabled = True
+
+        def headers(self, body, nonce="", now=None):
+            raise RuntimeError("kms down")
+
+    bridge = OpenClawBridgeAdapter("http://gw.local", signer=_Broken())
+    res = bridge.send(_msg())
+    assert res.ok is False and "签名失败" in res.error
+    assert fake_http.captured == {}, "签名失败必须不发(fail-closed)"
+
+
+def test_bridge_verify_webhook(fake_http) -> None:
+    body = b'{"message":{"text":"hi"}}'
+    bridge = OpenClawBridgeAdapter("http://gw.local", signer=S.OutboundSigner(SECRET))
+    h = S.OutboundSigner(SECRET).headers(body)
+    assert bridge.verify_webhook(h, body) == (True, "ok")
+    assert bridge.verify_webhook(h, body + b" ") == (False, "bad_signature")
+
+    unsigned = OpenClawBridgeAdapter("http://gw.local", signer=S.OutboundSigner(""))
+    assert unsigned.verify_webhook(h, body) == (False, "missing_secret"), "没配密钥要拒收"