coding-bridge 2026.7.3.2__tar.gz → 2026.7.3.4__tar.gz

{coding_bridge-2026.7.3.2 → coding_bridge-2026.7.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-bridge
-Version: 2026.7.3.2
+Version: 2026.7.3.4
 Summary: Node daemon for AceDataCloud Coding Bridge — run Claude Code on your own machine and drive it from the web.
 Project-URL: Homepage, https://github.com/AceDataCloud/CodingBridge
 Project-URL: Issues, https://github.com/AceDataCloud/CodingBridge/issues

{coding_bridge-2026.7.3.2 → coding_bridge-2026.7.3.4}/coding_bridge/channels/__init__.py

@@ -25,14 +25,17 @@ from .config import (
     parse_channels_config,
 )
 from .dispatcher import SessionDispatcher
+from .policy import ChannelPolicy, PolicyGate
 
 __all__ = [
     "ChannelAdapter",
+    "ChannelPolicy",
     "ChannelTarget",
     "ChannelsConfig",
     "ConfigError",
     "IncomingMessage",
     "MessageHandler",
+    "PolicyGate",
     "SendResult",
     "SessionDispatcher",
     "WeChatInstanceConfig",

{coding_bridge-2026.7.3.2 → coding_bridge-2026.7.3.4}/coding_bridge/channels/config.py

@@ -37,19 +37,34 @@ Design notes:
 
 from __future__ import annotations
 
+import math
 import os
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 from urllib.parse import urlparse
 
+if TYPE_CHECKING:
+    from .policy import ChannelPolicy
+
 try:
     import tomllib as _toml
 except ModuleNotFoundError:  # Python 3.10
     import tomli as _toml  # type: ignore[import-not-found]
 
 _WECHAT_KEYS = frozenset(
-    {"instance_id", "base_url", "token_env", "token_file", "enabled", "default_provider"}
+    {
+        "instance_id",
+        "base_url",
+        "token_env",
+        "token_file",
+        "enabled",
+        "default_provider",
+        "trigger_prefix",
+        "allowed_senders",
+        "rate_limit_per_min",
+        "dedup_window_seconds",
+    }
 )
 _CHANNELS_KEYS = frozenset({"wechat"})
 
@@ -76,6 +91,33 @@ class WeChatInstanceConfig:
     token_file: str | None = None
     enabled: bool = False
     default_provider: str | None = None
+    #: Message text must start with this to be forwarded. Empty string disables
+    #: the check. See ``coding_bridge.channels.policy.ChannelPolicy``.
+    trigger_prefix: str = "/ask "
+    #: Sender allowlist. Empty tuple = allow all (still gated by the WeChat
+    #: gateway token). Stored as tuple because ``WeChatInstanceConfig`` is frozen.
+    allowed_senders: tuple[str, ...] = ()
+    #: Sliding-window rate limit per sender_id over the last 60 s.
+    rate_limit_per_min: int = 6
+    #: Dedup window for repeat upstream ``msg_id`` (upstream retries). ``0``
+    #: disables dedup.
+    dedup_window_seconds: float = 300.0
+
+    def to_policy(self) -> ChannelPolicy:
+        """Build the runtime ``ChannelPolicy`` this instance describes."""
+        # Local import to avoid a circular module cycle
+        # (policy → base → nothing config-specific; config → policy would loop
+        # only at type-annotation time, but keep the runtime import lazy so
+        # ``coding_bridge.channels.config`` alone still loads without importing
+        # the whole channels stack).
+        from .policy import ChannelPolicy
+
+        return ChannelPolicy(
+            trigger_prefix=self.trigger_prefix,
+            allowed_senders=self.allowed_senders,
+            rate_limit_per_min=self.rate_limit_per_min,
+            dedup_window_seconds=self.dedup_window_seconds,
+        )
 
     def resolve_token(self, environ: dict[str, str] | None = None) -> str:
         """Load the token from env var or secrets file. Never logs it.
@@ -198,6 +240,50 @@ def _parse_wechat(block: dict[str, Any], index: int) -> WeChatInstanceConfig:
         raise ConfigError(
             f"[[channels.wechat]] {instance_id!r}: default_provider must be a string"
         )
+
+    trigger_prefix = block.get("trigger_prefix", "/ask ")
+    if not isinstance(trigger_prefix, str):
+        raise ConfigError(
+            f"[[channels.wechat]] {instance_id!r}: trigger_prefix must be a string"
+        )
+
+    allowed_senders_raw = block.get("allowed_senders", [])
+    if not isinstance(allowed_senders_raw, list) or not all(
+        isinstance(x, str) and x for x in allowed_senders_raw
+    ):
+        raise ConfigError(
+            f"[[channels.wechat]] {instance_id!r}: allowed_senders must be a "
+            "list of non-empty strings"
+        )
+
+    rate_limit = block.get("rate_limit_per_min", 6)
+    # Bool is a subclass of int in Python — reject explicit bools to catch
+    # `rate_limit_per_min = true` typos.
+    if isinstance(rate_limit, bool) or not isinstance(rate_limit, int) or rate_limit < 0:
+        raise ConfigError(
+            f"[[channels.wechat]] {instance_id!r}: rate_limit_per_min must be "
+            "a non-negative int"
+        )
+
+    dedup_window = block.get("dedup_window_seconds", 300.0)
+    if isinstance(dedup_window, bool) or not isinstance(dedup_window, (int, float)):
+        raise ConfigError(
+            f"[[channels.wechat]] {instance_id!r}: dedup_window_seconds must "
+            "be a number"
+        )
+    # NaN < 0 is False so a plain range check misses it — reject explicitly
+    # so ``_prune_dedup`` never sees a non-comparable value.
+    if math.isnan(dedup_window) or math.isinf(dedup_window):
+        raise ConfigError(
+            f"[[channels.wechat]] {instance_id!r}: dedup_window_seconds must "
+            "be finite"
+        )
+    if dedup_window < 0:
+        raise ConfigError(
+            f"[[channels.wechat]] {instance_id!r}: dedup_window_seconds must "
+            "be >= 0"
+        )
+
     return WeChatInstanceConfig(
         instance_id=instance_id,
         base_url=base_url.rstrip("/"),
@@ -205,6 +291,10 @@ def _parse_wechat(block: dict[str, Any], index: int) -> WeChatInstanceConfig:
         token_file=token_file,
         enabled=enabled,
         default_provider=default_provider,
+        trigger_prefix=trigger_prefix,
+        allowed_senders=tuple(allowed_senders_raw),
+        rate_limit_per_min=rate_limit,
+        dedup_window_seconds=float(dedup_window),
     )
 
 

coding_bridge-2026.7.3.4/coding_bridge/channels/policy.py

@@ -0,0 +1,230 @@
+"""Per-instance abuse-control policy for channel adapters.
+
+Wraps the ``MessageHandler`` you pass to ``ChannelAdapter.set_handler``. The
+adapter has no idea abuse controls exist; the wrapper enforces them **before**
+the message ever reaches the ``SessionDispatcher``.
+
+Enforced (in this order, cheapest to most-expensive):
+
+1. **Trigger prefix** — the raw message text must start with a configured
+   prefix (default ``"/ask "``) so a bot in a group chat only responds when
+   explicitly addressed. Prefix is stripped before the message is forwarded.
+   Empty string → prefix check disabled.
+2. **Sender allowlist** — if ``allowed_senders`` is non-empty, only those
+   ``sender_id`` values are accepted. Empty list → allow all (rely on
+   ``token`` for auth; useful when only the account owner can reach the
+   WeChat gateway endpoint anyway).
+3. **Per-sender rate limit** — sliding-window: at most ``rate_limit_per_min``
+   messages from one ``sender_id`` in the last 60 s. Default 6/min.
+
+Every rejection is logged at INFO with a stable ``reason`` code so operators
+can grep. Nothing sensitive (token, message body) ever appears in the log.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections import deque
+from collections.abc import Callable
+from dataclasses import dataclass, field, replace
+
+from .base import ChannelAdapter, IncomingMessage, MessageHandler
+
+logger = logging.getLogger("coding-bridge.channels")
+
+
+@dataclass(frozen=True)
+class ChannelPolicy:
+    """Per-instance abuse-control knobs. Frozen — build once at start-up."""
+
+    #: Only accept messages whose text starts with this string (default
+    #: ``"/ask "``). Empty string disables the prefix check.
+    trigger_prefix: str = "/ask "
+
+    #: Sender IDs that may talk to this bot. Empty tuple = allow all.
+    allowed_senders: tuple[str, ...] = ()
+
+    #: Per-sender sliding window: at most this many messages per 60 s.
+    rate_limit_per_min: int = 6
+
+    #: Dedup window in seconds. Repeat upstream ``msg_id`` inside this window
+    #: is silently dropped (upstream retries, duplicate deliveries). ``0``
+    #: disables dedup — useful in tests.
+    dedup_window_seconds: float = 300.0
+
+    #: How many recent ``msg_id`` values to remember per adapter instance.
+    dedup_max_ids: int = 1024
+
+    #: Cap on how many distinct ``sender_id`` rate-limit windows we keep in
+    #: memory. Beyond this the least-recently-active bucket is dropped so an
+    #: attacker spamming with random sender IDs can't grow the map without
+    #: bound. Real deployments serve at most a few hundred distinct senders.
+    rate_limit_max_senders: int = 4096
+
+
+@dataclass
+class _SlidingWindow:
+    """Per-sender timestamps for the last minute."""
+
+    window_seconds: float
+    limit: int
+    stamps: deque[float] = field(default_factory=deque)
+    last_touch: float = 0.0
+
+    def allow(self, now: float) -> bool:
+        self.last_touch = now
+        cutoff = now - self.window_seconds
+        while self.stamps and self.stamps[0] < cutoff:
+            self.stamps.popleft()
+        if len(self.stamps) >= self.limit:
+            return False
+        self.stamps.append(now)
+        return True
+
+
+class PolicyGate:
+    """Wraps a downstream ``MessageHandler`` with the policy checks above.
+
+    Usage::
+
+        gate = PolicyGate(policy, downstream=dispatcher.handle_message)
+        adapter.set_handler(gate.handle)
+    """
+
+    def __init__(
+        self,
+        policy: ChannelPolicy,
+        downstream: MessageHandler,
+        *,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._policy = policy
+        self._downstream = downstream
+        self._clock = clock
+        self._lock = asyncio.Lock()
+        self._windows: dict[str, _SlidingWindow] = {}
+        # dedup: ordered dict of msg_id → timestamp (arrival). We use a deque
+        # for insertion order + dict for O(1) membership. Bounded by
+        # ``dedup_max_ids``; oldest evicted first.
+        self._dedup_order: deque[str] = deque()
+        self._dedup_seen: dict[str, float] = {}
+
+    async def handle(self, msg: IncomingMessage, adapter: ChannelAdapter) -> None:
+        """Run all policy checks, then delegate. Never raises."""
+        # (1) trigger prefix
+        prefix = self._policy.trigger_prefix
+        text = msg.text
+        if prefix:
+            if not text.startswith(prefix):
+                self._reject(adapter, msg, "trigger_prefix_missing")
+                return
+            text = text[len(prefix) :].lstrip()
+            if not text:
+                self._reject(adapter, msg, "empty_after_prefix")
+                return
+
+        # (2) sender allowlist
+        allowed = self._policy.allowed_senders
+        if allowed and msg.sender_id not in allowed:
+            self._reject(adapter, msg, "sender_not_allowed")
+            return
+
+        # (3+4) rate limit + dedup share the lock so a burst can't race
+        async with self._lock:
+            # dedup
+            if self._policy.dedup_window_seconds > 0 and msg.upstream_id:
+                now = self._clock()
+                self._prune_dedup(now)
+                if msg.upstream_id in self._dedup_seen:
+                    self._reject(adapter, msg, "duplicate_msg_id")
+                    return
+                self._remember(msg.upstream_id, now)
+
+            # rate limit
+            if self._policy.rate_limit_per_min > 0:
+                now = self._clock()
+                self._evict_stale_windows(now)
+                window = self._windows.get(msg.sender_id)
+                if window is None:
+                    # Cap-check BEFORE insert so an attacker spamming with
+                    # random sender IDs can never grow the map past the cap.
+                    if len(self._windows) >= self._policy.rate_limit_max_senders:
+                        self._drop_lru_window()
+                    window = _SlidingWindow(
+                        window_seconds=60.0, limit=self._policy.rate_limit_per_min
+                    )
+                    self._windows[msg.sender_id] = window
+                if not window.allow(now):
+                    self._reject(adapter, msg, "rate_limited")
+                    return
+
+        # (5) forward to dispatcher — strip prefix out of the payload
+        forwarded = replace(msg, text=text)
+        try:
+            await self._downstream(forwarded, adapter)
+        except Exception as exc:  # dispatcher errors must not kill the adapter
+            # NOTE: intentionally `logger.error`, NOT `logger.exception`, so
+            # the traceback (which may include `repr(exc)` with the original
+            # message text embedded) never reaches the log. The exception
+            # class name is enough for operators to grep.
+            logger.error(
+                "downstream handler raised: adapter=%s instance=%s exc=%s",
+                adapter.name,
+                adapter.instance_id,
+                exc.__class__.__name__,
+            )
+
+    def _reject(self, adapter: ChannelAdapter, msg: IncomingMessage, reason: str) -> None:
+        # NOTE: never log ``msg.text`` (may contain user content or secrets that
+        # look like commands). Log the sender + reason only.
+        logger.info(
+            "channel message rejected: adapter=%s instance=%s sender=%s reason=%s",
+            adapter.name,
+            adapter.instance_id,
+            msg.sender_id,
+            reason,
+        )
+
+    def _prune_dedup(self, now: float) -> None:
+        cutoff = now - self._policy.dedup_window_seconds
+        while self._dedup_order and self._dedup_seen.get(self._dedup_order[0], 0) < cutoff:
+            oldest = self._dedup_order.popleft()
+            self._dedup_seen.pop(oldest, None)
+
+    def _remember(self, msg_id: str, now: float) -> None:
+        # Cap: evict oldest until size is under ``dedup_max_ids``.
+        while len(self._dedup_order) >= self._policy.dedup_max_ids:
+            oldest = self._dedup_order.popleft()
+            self._dedup_seen.pop(oldest, None)
+        self._dedup_order.append(msg_id)
+        self._dedup_seen[msg_id] = now
+
+    def _evict_stale_windows(self, now: float) -> None:
+        """Drop rate-limit windows that haven't fired in 2 × window_seconds.
+
+        Called on the hot path (inside ``self._lock``) so it must be cheap.
+        Windows are ~120 s stale — well past their rate-limit window — so
+        removing them can't affect a genuine sender's counter.
+        """
+        stale_cutoff = now - 120.0
+        stale = [k for k, w in self._windows.items() if w.last_touch < stale_cutoff]
+        for k in stale:
+            self._windows.pop(k, None)
+
+    def _drop_lru_window(self) -> None:
+        """Evict the least-recently-touched sender window.
+
+        Fires only when the map is at its ``rate_limit_max_senders`` cap AND
+        no idle-eviction cleared enough room. Cost is O(N) over the map, but
+        N is capped and this path fires at most once per unique-sender
+        insertion above the cap.
+        """
+        if not self._windows:
+            return
+        lru_key = min(self._windows, key=lambda k: self._windows[k].last_touch)
+        self._windows.pop(lru_key, None)
+
+
+__all__ = ["ChannelPolicy", "PolicyGate"]

{coding_bridge-2026.7.3.2 → coding_bridge-2026.7.3.4}/coding_bridge/channels/wechat/client.py

@@ -7,8 +7,10 @@ so tests can inject a transport via :func:`respx`.
 
 from __future__ import annotations
 
+import re
 import time
 from typing import Any
+from urllib.parse import quote
 
 import httpx
 
@@ -19,6 +21,11 @@ from ..base import ChannelTarget, SendResult
 # to the caller so operators have real diagnostics in the log.
 _ACCEPTED_STATUSES = frozenset({200, 201, 202})
 
+# Safe pattern for a gateway task id. The gateway generates UUID-like tokens; we
+# refuse anything with URL metacharacters so a caller can't inject a query
+# parameter or path segment into the GET.
+_TASK_ID_RE = re.compile(r"^[A-Za-z0-9_\-]{1,128}$")
+
 
 class WeChatClient:
     """Async client for one WeChat gateway endpoint (one CVM / one WeChat instance)."""
@@ -104,3 +111,33 @@ class WeChatClient:
             error=f"HTTP {resp.status_code}: {(err or '')[:200]}",
             latency_ms=latency_ms,
         )
+
+    async def get_task_status(self, task_id: str) -> dict[str, Any]:
+        """Fetch delivery status for a task returned by ``send_message``.
+
+        Returns the parsed JSON body as-is (the gateway's shape may evolve). Raises
+        ``httpx.HTTPStatusError`` on non-2xx so the caller can distinguish
+        "not delivered yet" (200 with status=queued) from "task unknown" (404).
+
+        Kept deliberately small: this is a debug / diagnostics primitive used
+        by the ``doctor`` CLI command (P4) and E2E validation, not by the
+        adapter's fast path.
+
+        Raises ``ValueError`` on an empty or unsafely-shaped ``task_id`` —
+        rather than URL-encode and pray, we refuse anything that could
+        contain path/query metacharacters (``?``, ``#``, ``/``, ``..``).
+        """
+        if not task_id:
+            raise ValueError("task_id must not be empty")
+        if not _TASK_ID_RE.fullmatch(task_id):
+            raise ValueError("task_id contains invalid characters")
+        # Belt-and-suspenders: `quote(safe="")` still produces a plain
+        # segment since the regex already rejects unsafe input.
+        path = f"/api/messages/tasks/{quote(task_id, safe='')}"
+        resp = await self._client.get(path)
+        resp.raise_for_status()
+        try:
+            body = resp.json()
+        except ValueError:
+            return {}
+        return body if isinstance(body, dict) else {}