| 1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075 |
- """Generic webhook platform adapter: aiohttp server that validates HMAC-signed POSTs (GitHub, GitLab,
- Svix, Linear, generic), renders payloads into agent prompts, and routes responses back (github_comment
- or any gateway platform). Routes live under platforms.webhook.extra.routes: events (header filter),
- secret (REQUIRED; "INSECURE_NO_AUTH" skips validation, loopback only), prompt template, skills,
- deliver/deliver_extra, deliver_only (rendered prompt IS the message), cron_job (fire an existing cron
- job per event; the rendered prompt is transient per-run context; exclusive with deliver_only), mirror_to_session
- (opt-in: a delivered response is also written into the target chat's transcript so follow-ups there have
- context). Per-route rate limiting,
- idempotency cache, body-size caps checked before reading. Generic HMAC V2 binds a timestamp for
- replay protection; body-only V1 is deprecated but accepted with a warning."""
- import asyncio
- import base64
- import binascii
- import hashlib
- import hmac
- import json
- import logging
- import os
- import re
- import subprocess
- import time
- import uuid
- from collections import deque
- from datetime import datetime, timezone, UTC
- from contextlib import nullcontext, suppress
- from dataclasses import dataclass
- from typing import Any, Deque, Dict, List, Optional
- try:
- from aiohttp import web
- AIOHTTP_AVAILABLE = True
- except ImportError:
- AIOHTTP_AVAILABLE = False
- web = None # type: ignore[assignment]
- from gateway.config import Platform, PlatformConfig
- from gateway.platforms.base import BasePlatformAdapter, SendResult
- from gateway.platforms.event import MessageEvent, MessageType
- from gateway.platforms.tcp_site import start_tcp_site
- from gateway.platforms.webhook_coalesce import WebhookCoalescer, validate_coalesce_config
- from gateway.platforms.webhook_filters import DEFAULT_SCRIPT_TIMEOUT_SECONDS, WebhookRouteProcessor
- from gateway.platforms.webhook_mcp_events import (
- handle_mcp_event_control, mcp_event_delivery_id, render_mcp_event_prompt)
- from gateway.response_filters import is_autonomous_silence_response
- logger = logging.getLogger(__name__)
- # _resolve_request_profile sentinel: /p/<profile>/ names a profile this gateway does not serve (→ 404);
- # distinct from None (no prefix / default).
- _PROFILE_REJECTED = object()
- _UNPARSEABLE = object()
- _BUILTIN_DELIVER_PLATFORMS = {
- "telegram", "discord", "slack", "signal", "sms", "whatsapp", "matrix", "mattermost",
- "email", "dingtalk", "feishu", "wecom", "wecom_callback", "weixin",
- "bluebubbles", "qqbot", "yuanbao"}
- # ``None`` → aiohttp binds BOTH address families. "0.0.0.0" is IPv4-only (unreachable on IPv6-only
- # networks such as Fly.io 6PN); "::" becomes IPv6-only where the kernel sets IPV6_V6ONLY=1, breaking
- # the 127.0.0.1 health check. Users can pin a host via ``platforms.webhook.extra.host``.
- DEFAULT_HOST = None
- DEFAULT_PORT = 8644
- _INSECURE_NO_AUTH = "INSECURE_NO_AUTH"
- _DYNAMIC_ROUTES_FILENAME = "webhook_subscriptions.json"
- _RATE_WINDOW_SECONDS = 60.0
- # Hosts that only serve same-machine connections; anything else is a public bind.
- _LOOPBACK_HOSTS = frozenset({"127.0.0.1", "localhost", "::1", "ip6-localhost", "ip6-loopback"})
- _V2_REPLAY_WINDOW_SECONDS = 300
- _TEMPLATE_KEY_RE = re.compile(r"\{([a-zA-Z0-9_.]+)\}")
- _REPO_RE = re.compile(r"[A-Za-z0-9._-]+/[A-Za-z0-9._-]+")
- # Credentials `gh` reads; a routed profile's github_comment must use its own, never the process env's.
- _GH_TOKEN_VARS = ("GH_TOKEN", "GITHUB_TOKEN")
- def _header_delivery_id(headers) -> str:
- """The provider's delivery id (GitHub, Svix, Standard Webhooks, generic), else a fresh one."""
- return headers.get("X-GitHub-Delivery", headers.get("svix-id", headers.get(
- "webhook-id", headers.get("X-Request-ID", uuid.uuid4().hex))))
- @dataclass(frozen=True)
- class _WebhookDeliveryIdentity:
- """Collision-free identity for one provider delivery on one routed webhook route."""
- profile: str
- route: str
- delivery_id: str
- @classmethod
- def from_parts(cls, profile: Optional[str], route: str, delivery_id: str) -> "_WebhookDeliveryIdentity":
- return cls(profile=profile or "default", route=route, delivery_id=delivery_id)
- @property
- def session_chat_id(self) -> str:
- # A versioned canonical JSON tuple avoids delimiter ambiguity while keeping the chat id safe
- # for session-key persistence even when provider-controlled fields contain ':' or '/'.
- payload = json.dumps(
- (self.profile, self.route, self.delivery_id), ensure_ascii=False, separators=(",", ":")
- ).encode("utf-8")
- token = base64.urlsafe_b64encode(payload).decode("ascii").rstrip("=")
- return f"webhook:v2:{token}"
- @staticmethod
- def route_from_chat_id(chat_id: str) -> str:
- """The route a delivery chat id names: decoded from a ``webhook:v2:`` token, else the legacy
- ``webhook:{route}:{delivery}`` spelling that admissions queued before the upgrade still carry."""
- prefix = "webhook:v2:"
- if chat_id.startswith(prefix):
- token = chat_id[len(prefix):]
- _profile, route, _delivery = json.loads(base64.urlsafe_b64decode(token + "=" * (-len(token) % 4)))
- return str(route)
- return chat_id.split(":", 2)[1]
- def _is_loopback_host(host: Optional[str]) -> bool:
- """True when `host` binds only to the local machine (falsy → non-loopback: usually a public default bind)."""
- return bool(host) and host.strip().lower() in _LOOPBACK_HOSTS
- def _hmac_str_equal(provided: str, expected: str) -> bool:
- """Timing-safe str equality tolerant of non-ASCII: ``compare_digest`` raises TypeError on non-ASCII
- str and ``provided`` is an attacker-controlled header, so compare as UTF-8 bytes to fail closed."""
- return hmac.compare_digest(provided.encode(), expected.encode())
- def _hex_hmac(secret: str, data: bytes) -> str:
- return hmac.new(secret.encode(), data, hashlib.sha256).hexdigest()
- def _is_usable_secret(secret: object) -> bool:
- """True when ``secret`` is a string with at least one non-space character.
- A whitespace-only value is what an unset key looks like in config. It is
- falsy to a person and truthy to ``if not secret``, so a bare falsy check
- lets it through. Non-strings are rejected for the same reason.
- """
- return isinstance(secret, str) and bool(secret.strip())
- def _timestamp_fresh(raw: str, stale_msg: str, *args) -> bool:
- """True when integer timestamp header *raw* is within the replay window; unparseable → False,
- stale → warn ``stale_msg % args`` and False."""
- try:
- age = abs(int(time.time()) - int(raw))
- except (TypeError, ValueError):
- return False
- if age > _V2_REPLAY_WINDOW_SECONDS:
- logger.warning(stale_msg, *args)
- return False
- return True
- def _is_known_platform(name: str) -> bool:
- """Cross-platform delivery target: built-in names or plugin-registered platforms."""
- if name in _BUILTIN_DELIVER_PLATFORMS:
- return True
- with suppress(Exception):
- from gateway.platform_registry import platform_registry
- return platform_registry.is_registered(name)
- return False
- def _json_error(message: str, status: int) -> web.Response:
- return web.json_response({"error": message}, status=status)
- def check_webhook_requirements() -> bool:
- """Check if webhook adapter dependencies are available."""
- return AIOHTTP_AVAILABLE
- def _validate_svix_signature(body: bytes, secret: str, msg_id: str, timestamp: str, signature_header: str) -> bool:
- """Svix-compatible signatures (AgentMail): base64 HMAC-SHA256 of "{id}.{timestamp}.{body}"."""
- if not (msg_id and timestamp and signature_header and secret):
- return False
- if not _timestamp_fresh(timestamp, "[webhook] Svix signature timestamp outside replay window"):
- return False
- if secret.startswith("whsec_"):
- try:
- key = base64.b64decode(secret.removeprefix("whsec_"), validate=True)
- except (binascii.Error, ValueError):
- logger.debug("[webhook] Invalid whsec_ Svix signing secret")
- return False
- # "whsec_" alone decodes to b"": a public HMAC key, same as a blank secret. HMAC zero-pads the
- # key, so an all-NUL key signs exactly like b"" and is refused with it.
- if not key.strip(b"\x00 \t\r\n\x0b\x0c"):
- return False
- else:
- # Some providers document Svix-style headers but hand out raw shared secrets.
- logger.debug("[webhook] Validating Svix-style signature with raw secret")
- key = secret.encode()
- signed_content = msg_id.encode() + b"." + timestamp.encode() + b"." + body
- expected = base64.b64encode(hmac.new(key, signed_content, hashlib.sha256).digest()).decode()
- # Multiple space-separated "vN,<base64>" entries during secret rotation.
- for part in signature_header.split():
- version, _, signature = part.partition(",")
- if _ and version == "v1" and _hmac_str_equal(signature, expected):
- return True
- return False
- class WebhookAdapter(BasePlatformAdapter):
- """Generic webhook receiver that triggers agent runs from HTTP POSTs."""
- # Event-triggered, no human present: startup auto-resume must FINISH the interrupted work, not ask "what next?".
- # The startup auto-resume turn must instruct the model to FINISH the interrupted work instead of
- # emitting an interactive acknowledgement that abandons the task (#57056).
- interactive_resume: bool = False
- # ``/p/<profile>/webhooks/<route>`` on the shared listener (``_resolve_request_profile``).
- serves_profile_prefix: bool = True
- def __init__(self, config: PlatformConfig):
- super().__init__(config, Platform.WEBHOOK)
- extra = config.extra
- # Empty string / null host normalises to None ("bind all families").
- self._host: Optional[str] = extra.get("host", DEFAULT_HOST) or None
- self._port: int = int(extra.get("port", DEFAULT_PORT))
- self._global_secret: str = extra.get("secret", "")
- self._static_routes: dict[str, dict] = extra.get("routes", {})
- self._dynamic_routes: dict[str, dict] = {}
- self._dynamic_routes_stat: Optional[tuple] = None
- self._routes: dict[str, dict] = dict(self._static_routes)
- self._runner = None
- self._v1_signature_warned: set[str] = set() # routes already warned about legacy V1 (once per route)
- # Keyed by session chat_id; read by EVERY send() (interim status messages AND the final
- # response) so never pop on send(). TTL-pruned on each POST.
- self._delivery_info: dict[str, dict] = {}
- self._delivery_info_created: dict[str, float] = {}
- self._delivery_info_order: deque[tuple[float, str]] = deque()
- self.gateway_runner = None # set externally; needed for cross-platform delivery
- # Idempotency is scoped to the authenticated route and routed profile: provider delivery
- # IDs are not globally unique across unrelated webhook endpoints.
- self._seen_deliveries: dict[_WebhookDeliveryIdentity, float] = {}
- self._idempotency_ttl: int = 3600 # 1 hour
- self._seen_deliveries_next_prune_at: float = 0.0
- self._rate_counts: dict[str, deque[float]] = {} # per-route hit timestamps in a fixed window
- self._rate_limit: int = int(extra.get("rate_limit", 30)) # per minute
- self._max_body_bytes: int = int(extra.get("max_body_bytes", 1_048_576)) # 1MB
- self._script_timeout_seconds: int = int(extra.get("script_timeout_seconds", DEFAULT_SCRIPT_TIMEOUT_SECONDS))
- self._route_processor = WebhookRouteProcessor(script_timeout_seconds=self._script_timeout_seconds)
- # Opt-in per-route debounce of rapid same-entity events (route ``coalesce`` block). #92066
- self._coalescer = WebhookCoalescer(dispatch=self._spawn_agent_run, render=self._render_prompt)
- @property
- def token(self):
- # Bind native replay to the configured signing credentials. Static routes only: dynamic
- # subscriptions hot-reload on every POST, and an unrelated ``webhook subscribe`` must not
- # re-key the connector of already-admitted deliveries (their send() would see profile_mismatch).
- return json.dumps([self._global_secret, {name: route.get("secret", self._global_secret)
- for name, route in self._static_routes.items()}], sort_keys=True)
- # --- Lifecycle ---
- def _validate_route(self, name: str, route: dict) -> None:
- """Startup validation: secret required; INSECURE_NO_AUTH only on loopback (crash early on a public footgun)."""
- secret = route.get("secret", self._global_secret)
- if not _is_usable_secret(secret):
- raise ValueError(f"[webhook] Route '{name}' HMAC secret is missing, blank, or not a string. Set 'secret' "
- f"on the route or globally. "
- f"For testing without auth, set secret to '{_INSECURE_NO_AUTH}'.")
- if secret == _INSECURE_NO_AUTH and not _is_loopback_host(self._host):
- raise ValueError(f"[webhook] Route '{name}' uses INSECURE_NO_AUTH secret but is bound to non-loopback "
- f"host '{self._host}'. INSECURE_NO_AUTH is for local testing only. "
- f"Refusing to start to prevent accidental exposure.")
- if route.get("deliver_only"):
- deliver = route.get("deliver", "log")
- if not deliver or deliver == "log":
- raise ValueError(f"[webhook] Route '{name}' has deliver_only=true but deliver is '{deliver}'. Direct "
- f"delivery requires a real target (telegram, discord, slack, github_comment, etc.).")
- if route.get("cron_job"):
- raise ValueError(f"[webhook] Route '{name}' sets both deliver_only and cron_job. They are mutually "
- f"exclusive: deliver_only pushes the rendered template as a message, cron_job fires "
- f"an existing cron job (which handles its own delivery).")
- validate_coalesce_config(name, route)
- async def connect(self, *, is_reconnect: bool = False) -> bool:
- self._reload_dynamic_routes()
- for name, route in self._routes.items():
- self._validate_route(name, route)
- # client_max_size enforces the cap on every read path, including chunked bodies without
- # Content-Length that bypass the header check.
- app = web.Application(client_max_size=self._max_body_bytes)
- app.router.add_get("/health", self._handle_health)
- app.router.add_post("/webhooks/{route_name}", self._handle_webhook)
- # /p/<profile>/ routes the event to that profile (honored only under gateway.multiplex_profiles).
- app.router.add_post("/p/{profile}/webhooks/{route_name}", self._handle_webhook)
- # Without an api_server listener this port is the shared listener: forward a secondary's
- # inbound-port platforms (Twilio, LINE, Teams, ...) registered in shared-listener mode.
- app.router.add_route("*", "/p/{profile}/{tail:.*}", self._handle_profile_ingress)
- self._runner = web.AppRunner(app)
- await self._runner.setup()
- try:
- await start_tcp_site(self._runner, self._host, self._port, log_tag="webhook")
- except OSError as exc:
- await self._runner.cleanup()
- self._runner = None
- logger.error("[webhook] Could not bind %s:%d: %s. Set a different host or port in config.yaml under "
- "platforms.webhook.extra.", self._host or "all IPv4+IPv6 interfaces", self._port, exc)
- return False
- from gateway.platforms.shared_ingress import listener_base_url
- self._mark_connected(listener_base=listener_base_url(self._host, self._port))
- logger.info("[webhook] Listening on %s:%d — routes: %s", self._host or "* (all interfaces, IPv4+IPv6)",
- self._port, ", ".join(self._routes.keys()) or "(none configured)")
- self._wire_plugin_handlers(None)
- return True
- async def disconnect(self) -> None:
- await self._coalescer.flush() # buffered events are dispatched, not dropped, on shutdown/reconnect
- if self._runner:
- await self._runner.cleanup()
- self._runner = None
- self._mark_disconnected()
- logger.info("[webhook] Disconnected")
- async def send(self, chat_id: str, content: str, reply_to: Optional[str] = None,
- metadata: Optional[dict[str, Any]] = None) -> SendResult:
- """Deliver the agent's response to the destination stored for its opaque ``chat_id`` —
- read with ``.get()``, never popped."""
- # Autonomous lane (no human reader): the loose marker matcher shared with cron (marker on its own
- # first/last line), because models add a sentence explaining why they stayed quiet, which the
- # interactive exact-match rule would deliver.
- if is_autonomous_silence_response(content):
- logger.info("[webhook] Response for %s is a silence marker — not delivering", chat_id)
- return SendResult(success=True)
- from gateway.platforms.webhook_delivery import retained_destination
- try:
- delivery = retained_destination(self, chat_id)
- except Exception:
- logger.warning("[webhook] Destination unavailable for %s", chat_id, exc_info=True)
- return SendResult(success=False, error="Webhook destination unavailable or unauthorized")
- return await self._deliver_to(delivery, chat_id, content)
- async def _deliver_to(self, delivery: dict[str, Any], chat_id: str, content: str) -> SendResult:
- deliver_type = delivery["deliver"]
- if deliver_type == "log":
- logger.info("[webhook] Response for %s: %s", chat_id, content[:200])
- return SendResult(success=True)
- if deliver_type == "github_comment":
- return await self._deliver_github_comment(content, delivery)
- if self.gateway_runner and _is_known_platform(deliver_type):
- return await self._deliver_cross_platform(deliver_type, content, delivery)
- logger.warning("[webhook] Unknown deliver type: %s", deliver_type)
- return SendResult(success=False, error=f"Unknown deliver type: {deliver_type}")
- def _prune_delivery_info(self, now: float) -> None:
- """Drop delivery_info entries older than the idempotency TTL (bounds the dict by ``rate_limit * TTL``
- even when runs never produce a final response)."""
- created, order = self._delivery_info_created, self._delivery_info_order
- if len(order) < len(created):
- order = self._delivery_info_order = deque(
- (at, key) for key, at in sorted(created.items(), key=lambda kv: kv[1]))
- cutoff = now - self._idempotency_ttl
- while order and order[0][0] < cutoff:
- created_at, key = order.popleft()
- if created.get(key) == created_at:
- self._delivery_info.pop(key, None)
- created.pop(key, None)
- def _prune_seen_deliveries(self, now: float) -> None:
- """Occasionally prune expired delivery IDs without scanning every POST."""
- if now < self._seen_deliveries_next_prune_at:
- return
- cutoff = now - self._idempotency_ttl
- for k in [k for k, t in self._seen_deliveries.items() if t < cutoff]:
- self._seen_deliveries.pop(k, None)
- self._seen_deliveries_next_prune_at = now + min(60.0, max(1.0, self._idempotency_ttl / 10))
- def _record_rate_limit_hit(self, route_name: str, now: float) -> bool:
- """Return True if route is still within limit after recording this hit."""
- if not isinstance(window := self._rate_counts.get(route_name), deque):
- window = self._rate_counts[route_name] = deque(window or ())
- cutoff = now - _RATE_WINDOW_SECONDS
- while window and window[0] < cutoff:
- window.popleft()
- if len(window) >= self._rate_limit:
- return False
- window.append(now)
- return True
- def _record_delivery_id(self, identity: _WebhookDeliveryIdentity, now: float) -> bool:
- """Return True when this route/profile-qualified delivery should be processed."""
- if (seen_at := self._seen_deliveries.get(identity)) is not None and now - seen_at < self._idempotency_ttl:
- return False
- if seen_at is not None:
- self._seen_deliveries.pop(identity, None)
- self._seen_deliveries[identity] = now
- if len(self._seen_deliveries) > max(self._rate_limit * 2, 128):
- self._prune_seen_deliveries(now)
- return True
- async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
- return {"name": chat_id, "type": "webhook"}
- def toolsets_for_source(self, source) -> Optional[list[str]]:
- """Per-route ``toolsets`` override (config.yaml or a manual key in webhook_subscriptions.json —
- deliberately NOT settable via `hermes webhook subscribe`, so an agent-created subscription
- cannot self-grant tools). Keyed on ``user_id`` (exactly ``webhook:{route}`` as authenticated), not
- ``chat_id``, whose caller-supplied delivery id and ``:``-bearing route names make any split ambiguous
- (GHSA-2fmg-cjqm-hhrj)."""
- user_id = str(getattr(source, "user_id", "") or "")
- if not user_id.startswith("webhook:"):
- return None
- route_config = self._routes.get(user_id[len("webhook:"):])
- toolsets = route_config.get("toolsets") if isinstance(route_config, dict) else None
- if not isinstance(toolsets, list):
- return None
- return [str(t).strip() for t in toolsets if str(t).strip()] or None
- # --- HTTP handlers ---
- async def _handle_health(self, request: web.Request) -> web.Response:
- """GET /health — simple health check."""
- return web.json_response({"status": "ok", "platform": "webhook"})
- def _dynamic_route_allowed(self, name: str, route: dict) -> bool:
- """Reject dynamic routes whose effective secret is missing, blank, or not a string
- (_is_usable_secret); INSECURE_NO_AUTH is loopback-only."""
- effective_secret = route.get("secret", self._global_secret)
- if not _is_usable_secret(effective_secret):
- logger.warning("[webhook] Dynamic route '%s' skipped: 'secret' is missing, blank, or not a string. "
- "Set a valid HMAC secret, or use '%s' to explicitly disable auth (testing only).",
- name, _INSECURE_NO_AUTH)
- return False
- if effective_secret == _INSECURE_NO_AUTH and not _is_loopback_host(self._host):
- logger.warning("[webhook] Dynamic route '%s' skipped: INSECURE_NO_AUTH is only allowed on loopback "
- "hosts. Current host: '%s'.", name, self._host)
- return False
- try:
- # Hot-reloaded from the request handler: a malformed block must skip the route, not 500 the request.
- validate_coalesce_config(name, route)
- except ValueError as e:
- logger.warning("[webhook] Dynamic route '%s' skipped: %s", name, e)
- return False
- return True
- def _reload_dynamic_routes(self) -> None:
- """Reload agent-created subscriptions when the file's stat identity changes.
- Runs on every POST before auth, so it never takes the CLI writer lock: writers publish via
- atomic rename, which also gives the file a new inode, so a restored mtime cannot hide a change;
- ``file_cache_version`` also catches a same-tick same-size edit made in place (a hand edit).
- """
- from hermes_constants import get_hermes_home
- from utils import file_cache_version
- subs_path = get_hermes_home() / _DYNAMIC_ROUTES_FILENAME
- try:
- stat_key = file_cache_version(subs_path)
- except FileNotFoundError:
- if self._dynamic_routes:
- self._dynamic_routes, self._routes = {}, dict(self._static_routes)
- logger.debug("[webhook] Dynamic subscriptions file removed, cleared dynamic routes")
- self._dynamic_routes_stat = None
- return
- except OSError as e:
- logger.error("[webhook] Failed to read dynamic routes: %s", e)
- return
- if stat_key == self._dynamic_routes_stat:
- return # No change
- try:
- data = json.loads(subs_path.read_text(encoding="utf-8-sig"))
- except ValueError as e:
- # Keep the last good snapshot, and remember this version so it is parsed once, not per POST.
- self._dynamic_routes_stat = stat_key
- logger.error("[webhook] Failed to parse dynamic routes: %s", e)
- return
- except OSError as e:
- logger.error("[webhook] Failed to read dynamic routes: %s", e)
- return
- if not isinstance(data, dict):
- self._dynamic_routes_stat = stat_key # keep the last good snapshot; parse this version once
- return
- try:
- self._dynamic_routes = { # static routes take precedence
- k: v for k, v in data.items()
- if isinstance(v, dict) and k not in self._static_routes and self._dynamic_route_allowed(k, v)
- }
- self._routes = {**self._dynamic_routes, **self._static_routes}
- self._dynamic_routes_stat = stat_key
- logger.info("[webhook] Reloaded %d dynamic route(s): %s", len(self._dynamic_routes),
- ", ".join(self._dynamic_routes.keys()) or "(none)")
- except Exception as e:
- logger.error("[webhook] Failed to reload dynamic routes: %s", e)
- async def _handle_profile_ingress(self, request: web.Request) -> web.StreamResponse:
- profile = self._resolve_request_profile(request)
- if profile is _PROFILE_REJECTED or profile is None:
- return _json_error("Unknown or unconfigured profile", 404)
- from gateway.platforms.shared_ingress import dispatch_profile_ingress
- return await dispatch_profile_ingress(
- self.gateway_runner, profile, request.match_info.get("tail", ""), request)
- def _resolve_request_profile(self, request: web.Request):
- """Resolve + validate the /p/<profile>/ URL prefix: None (no prefix, or multiplexing off and the
- prefix names this gateway's own profile), the profile name (served under multiplexing), or
- ``_PROFILE_REJECTED`` (unknown / not served → 404)."""
- profile = (request.match_info.get("profile") or "").strip()
- if not profile:
- return None
- cfg = getattr(self.gateway_runner, "config", None)
- if not getattr(cfg, "multiplex_profiles", False):
- # Only a self-referential prefix may fall through to the bare route; anything else fails
- # closed (silently ignoring the prefix served the owner's routes under another profile's URL).
- with suppress(Exception):
- from hermes_cli.profiles import profile_matches_home
- if profile_matches_home(profile):
- return None
- return _PROFILE_REJECTED
- try:
- from hermes_cli.profiles import profiles_to_serve
- served = {name for name, _ in profiles_to_serve(multiplex=True)}
- except Exception:
- return _PROFILE_REJECTED
- return profile if profile in served else _PROFILE_REJECTED
- @staticmethod
- def _route_allows_profile(route_config: dict, request_profile: Optional[str]) -> bool:
- """Omitting ``profile`` binds a route to default; an explicit null/blank/non-string fails closed."""
- configured = route_config.get("profile") if "profile" in route_config else "default"
- if not isinstance(configured, str) or not configured.strip():
- return False
- return configured.strip() == (request_profile or "default")
- @staticmethod
- def _profile_scope(profile: Optional[str]):
- """Runtime scope for a resolved ``/p/<profile>/`` prefix; bare routes get a no-op."""
- if not profile or not isinstance(profile, str):
- return nullcontext()
- from gateway.run import _profile_runtime_scope
- from hermes_cli.profiles import get_profile_dir
- return _profile_runtime_scope(get_profile_dir(profile))
- async def _read_authenticated_body(self, request: web.Request, route_name: str,
- route_config: dict) -> tuple[Optional[bytes], Optional[web.Response]]:
- """Auth-before-body: size-cap, read, then HMAC-validate. Returns ``(body, None)`` or ``(None, response)``."""
- if (request.content_length or 0) > self._max_body_bytes:
- return None, _json_error("Payload too large", 413)
- try:
- raw_body = await request.read()
- except web.HTTPRequestEntityTooLarge: # client_max_size tripped — chunked or lying Content-Length
- return None, _json_error("Payload too large", 413)
- except Exception as e:
- logger.error("[webhook] Failed to read body: %s", e)
- return None, _json_error("Bad request", 400)
- if len(raw_body) > self._max_body_bytes: # defense in depth if the server-level limit was bypassed
- return None, _json_error("Payload too large", 413)
- # Missing, blank, or non-string secrets fail closed here too (not only in connect()), so direct
- # handler reuse cannot become an unauthenticated dispatch surface.
- secret = route_config.get("secret", self._global_secret)
- if not _is_usable_secret(secret):
- logger.error("[webhook] Route %s HMAC secret is missing, blank, or not a string; refusing request",
- route_name)
- return None, _json_error("Webhook route is missing an HMAC secret", 403)
- if secret != _INSECURE_NO_AUTH and not self._validate_signature(request, raw_body, secret):
- logger.warning("[webhook] Invalid signature for route %s", route_name)
- return None, _json_error("Invalid signature", 401)
- return raw_body, None
- @staticmethod
- def _parse_body(raw_body: bytes) -> Any:
- """JSON, falling back to form-encoded; ``_UNPARSEABLE`` when neither parses."""
- try:
- return json.loads(raw_body)
- except json.JSONDecodeError:
- try:
- import urllib.parse
- return dict(urllib.parse.parse_qsl(raw_body.decode("utf-8")))
- except Exception:
- return _UNPARSEABLE
- async def _handle_deliver_only(self, prompt: str, payload: Any, route_config: dict, route_name: str,
- event_type: str, delivery_id: str, profile: Optional[str] = None) -> web.Response:
- """deliver_only: the rendered prompt IS the message — skip the agent, reuse the same
- auth/rate-limit/idempotency/template pipeline."""
- delivery = {"deliver": route_config.get("deliver", "log"), "payload": payload, "profile": profile,
- "deliver_extra": self._render_delivery_extra(route_config.get("deliver_extra", {}), payload),
- "route": route_name,
- "mirror": route_config.get("mirror_to_session") is True}
- logger.info("[webhook] direct-deliver event=%s route=%s target=%s msg_len=%d delivery=%s", event_type,
- route_name, delivery["deliver"], len(prompt), delivery_id)
- failed = {"status": "error", "error": "Delivery failed", "delivery_id": delivery_id}
- try:
- result = await self._direct_deliver(prompt, delivery)
- except Exception:
- logger.exception("[webhook] direct-deliver failed route=%s delivery=%s", route_name, delivery_id)
- return web.json_response(failed, status=502)
- if result.success:
- return web.json_response({"status": "delivered", "route": route_name, "target": delivery["deliver"],
- "delivery_id": delivery_id}, status=200)
- # Target rejected it — 502 with a generic error (don't leak adapter detail).
- logger.warning("[webhook] direct-deliver target rejected route=%s target=%s error=%s", route_name,
- delivery["deliver"], result.error)
- return web.json_response(failed, status=502)
- def _handle_cron_trigger(self, prompt: str, route_config: dict, route_name: str, event_type: str,
- delivery_id: str, profile: Optional[str] = None) -> web.Response:
- """cron_job: fire an EXISTING cron job on this event instead of starting a webhook agent session.
- The rendered prompt is transient per-run context (same rail as ``cronjob(action='run', prompt=...)``);
- the job's own prompt, skills, model and delivery apply. Same auth/rate-limit/filter/script/idempotency
- pipeline as agent routes; 202 immediately, the run happens on a worker thread."""
- job_ref = str(route_config["cron_job"])
- event_context = (f"This run was triggered by webhook event '{event_type}' on route '{route_name}' "
- f"(not the schedule).\n\n{prompt}")
- logger.info("[webhook] cron-trigger event=%s route=%s job=%s delivery=%s", event_type, route_name, job_ref,
- delivery_id)
- async def _fire_cron_job() -> None:
- try:
- from tools.cronjob_tools import execute_job_for_event
- # The job store (cron/jobs.json) and the run belong to the ROUTED profile, not the gateway's
- # default home; to_thread copies contextvars so the scope follows. A cron job is a full agent
- # run (minutes) — keep it off the gateway event loop.
- with self._profile_scope(profile):
- result = await asyncio.to_thread(execute_job_for_event, job_ref, event_context)
- if not result.get("success"):
- logger.warning("[webhook] cron-trigger job=%s route=%s did not complete cleanly: %s", job_ref,
- route_name, result.get("error"))
- except Exception:
- logger.exception("[webhook] cron-trigger failed job=%s route=%s", job_ref, route_name)
- task = asyncio.create_task(_fire_cron_job())
- self._background_tasks.add(task)
- task.add_done_callback(self._background_tasks.discard)
- return web.json_response({"status": "accepted", "route": route_name, "cron_job": job_ref, "event": event_type,
- "delivery_id": delivery_id}, status=202)
- def _resolve_route(self, request: web.Request) -> tuple[str, Optional[dict], Any, Optional[web.Response]]:
- """Route + profile lookup for a POST; ``(route_name, route_config, profile, error_response)``."""
- self._reload_dynamic_routes() # hot-reload dynamic subscriptions (stat-gated, lock-free)
- route_name = request.match_info.get("route_name", "")
- route_config = self._routes.get(route_name)
- profile = self._resolve_request_profile(request)
- if profile is _PROFILE_REJECTED:
- return route_name, None, profile, _json_error("Unknown or unconfigured profile", 404)
- if not route_config:
- return route_name, None, profile, _json_error(f"Unknown route: {route_name}", 404)
- if not self._route_allows_profile(route_config, profile):
- logger.warning("[webhook] Route %s is not authorized for profile %r", route_name, profile or "default")
- # Same as unknown-route so profile mismatches can't enumerate route bindings.
- return route_name, None, profile, _json_error(f"Unknown route: {route_name}", 404)
- # Disabled routes stay in the subscriptions file (dashboard can re-enable) but reject events.
- # Only an explicit ``enabled: false`` turns a route off.
- if route_config.get("enabled", True) is False:
- return route_name, None, profile, _json_error(f"Route disabled: {route_name}", 403)
- return route_name, route_config, profile, None
- @staticmethod
- def _apply_skills(prompt: str, skills: list) -> str:
- """Inject the first matching skill via build_skill_invocation_message() directly — /skill-name slash
- commands would be intercepted by the command parser."""
- try:
- from agent.skill_commands import build_skill_invocation_message, get_skill_commands
- skill_cmds = get_skill_commands()
- for skill_name in skills:
- cmd_key = f"/{skill_name}"
- if cmd_key in skill_cmds:
- skill_content = build_skill_invocation_message(cmd_key, user_instruction=prompt)
- if skill_content:
- return skill_content
- else:
- logger.warning("[webhook] Skill '%s' not found", skill_name)
- except Exception as e:
- logger.warning("[webhook] Skill loading failed: %s", e)
- return prompt
- async def _handle_webhook(self, request: web.Request) -> web.Response:
- """POST /webhooks/{route_name} — receive and process a webhook event."""
- route_name, route_config, profile, error_response = self._resolve_route(request)
- if error_response is None:
- raw_body, error_response = await self._read_authenticated_body(request, route_name, route_config)
- if error_response is not None:
- return error_response
- headers = request.headers
- delivery_id = _header_delivery_id(headers)
- # A parked profile is retried, before any delivery id is recorded. The check resolves
- # ``profile_routes`` against the very source admission builds for this delivery.
- from gateway.platforms.webhook_ingress import parked_profile_refusal
- error_response = parked_profile_refusal(
- self.gateway_runner, profile, route_config,
- lambda: self._admission_source(route_name, profile, delivery_id))
- if error_response is not None:
- return error_response
- # Rate limiting (after auth)
- if not self._record_rate_limit_hit(route_name, time.time()):
- return _json_error("Rate limit exceeded", 429)
- payload = self._parse_body(raw_body)
- if payload is _UNPARSEABLE:
- return _json_error("Cannot parse body", 400)
- mcp_control = await handle_mcp_event_control(self, route_name, route_config, payload, profile)
- if mcp_control is not None:
- return mcp_control
- delivery_id = mcp_event_delivery_id(route_config, payload) or delivery_id
- event_type = (headers.get("X-GitHub-Event", "") or headers.get("X-GitLab-Event", "")
- or payload.get("event_type", "") or payload.get("type", "") or "unknown")
- allowed_events = route_config.get("events", [])
- if allowed_events and event_type not in allowed_events:
- logger.debug("[webhook] Ignoring event %s for route %s (allowed: %s)", event_type, route_name,
- allowed_events)
- return web.json_response({"status": "ignored", "event": event_type})
- if not self._route_processor.route_filters_match(route_config, payload, event_type, request.headers):
- logger.info("[webhook] filtered event=%s route=%s", event_type, route_name)
- return web.json_response({"status": "ignored", "reason": "filter", "route": route_name})
- # Script, prompt render and skill lookup read the profile's home (skills/, config); the runner
- # only enters the routed profile's scope later around handle_message, so enter it here.
- # See #67277.
- with self._profile_scope(profile):
- script = route_config.get("script")
- if script:
- # Shells out (up to its timeout) — worker thread so the loop isn't blocked; to_thread
- # copies contextvars so the profile scope follows.
- keep, transformed_payload = await asyncio.to_thread(
- self._route_processor.run_route_script, script, payload)
- if not keep:
- logger.info("[webhook] script ignored event=%s route=%s", event_type, route_name)
- return web.json_response({"status": "ignored", "reason": "script", "route": route_name})
- payload = transformed_payload or payload
- prompt = (render_mcp_event_prompt(self, route_config, payload, event_type, route_name)
- or self._render_prompt(route_config.get("prompt", ""), payload, event_type, route_name))
- # cron_job routes: the job's own skills apply; the rendered prompt is only per-run context.
- if (skills := route_config.get("skills", [])) and not route_config.get("cron_job"):
- prompt = self._apply_skills(prompt, skills)
- now = time.time() # idempotency: skip duplicate deliveries (webhook retries)
- delivery_identity = _WebhookDeliveryIdentity.from_parts(profile, route_name, delivery_id)
- coalesce = route_config.get("coalesce")
- # deliver_only, cron_job and coalesced events act before (or without) a durable admission, so
- # the ledger cannot dedupe a provider retry or a replayed signed delivery; the route-scoped
- # in-memory guard is their only replay defence (main dedupes every route here).
- non_durable = bool(route_config.get("deliver_only") or route_config.get("cron_job")
- or isinstance(coalesce, dict))
- if non_durable and not self._record_delivery_id(delivery_identity, now):
- logger.info("[webhook] Skipping duplicate delivery %s on route %s", delivery_id, route_name)
- return web.json_response({"status": "duplicate", "delivery_id": delivery_id}, status=200)
- if route_config.get("cron_job"):
- return self._handle_cron_trigger(prompt, route_config, route_name, event_type, delivery_id, profile)
- if route_config.get("deliver_only"):
- return await self._handle_deliver_only(prompt, payload, route_config, route_name, event_type, delivery_id,
- profile)
- if isinstance(coalesce, dict) and self._coalescer.enqueue(
- route_name=route_name, coalesce=coalesce, payload=payload, event_type=event_type, prompt=prompt,
- delivery_id=delivery_id, now=now, route_config=route_config, profile=profile):
- return web.json_response({"status": "coalesced", "route": route_name, "event": event_type,
- "delivery_id": delivery_id}, status=202)
- return await self._dispatch_agent_run(request, route_config, route_name, profile, payload, prompt, event_type,
- delivery_id, now)
- async def _dispatch_agent_run(self, request, route_config: dict, route_name: str, profile, payload: Any, prompt: str,
- event_type: str, delivery_id: str, now: float) -> web.Response:
- """Acknowledge only after the authority commits the immutable delivery."""
- logger.info("[webhook] %s event=%s route=%s prompt_len=%d delivery=%s", request.method, event_type, route_name,
- len(prompt), delivery_id)
- outcome = await self._admit_agent_run(payload, prompt, delivery_id, now, route_config=route_config,
- route_name=route_name, profile=profile, event_type=event_type)
- if outcome is None:
- return _json_error("Admission unavailable; retry this delivery", 503)
- if outcome == "duplicate":
- return web.json_response({"status": "duplicate", "delivery_id": delivery_id}, status=200)
- return web.json_response({"status": "accepted", "route": route_name, "event": event_type,
- "delivery_id": delivery_id}, status=202)
- def _spawn_agent_run(self, payload: Any, prompt: str, delivery_id: str, now: float, *, route_config: dict,
- route_name: str, profile, event_type: str, superseded=()) -> asyncio.Task:
- """Coalesced-path dispatch (settled timer / disconnect flush): admit the merged event as a task
- so ``WebhookCoalescer.flush`` can await the hand-off. The HTTP ack for these deliveries was
- already ``coalesced``: an admission failure is logged and gives back the batch's delivery ids
- (*superseded* too), so a resend of any of them is processed, not answered as a duplicate."""
- async def _admit_or_log():
- outcome = await self._admit_agent_run(payload, prompt, delivery_id, now, route_config=route_config,
- route_name=route_name, profile=profile, event_type=event_type)
- if outcome is None:
- logger.error("[webhook] Coalesced delivery %s on route %s was not admitted", delivery_id, route_name)
- for released in (*superseded, delivery_id):
- self._seen_deliveries.pop(_WebhookDeliveryIdentity.from_parts(profile, route_name, released), None)
- task = asyncio.create_task(_admit_or_log())
- self._background_tasks.add(task)
- task.add_done_callback(self._background_tasks.discard)
- return task
- def _admission_source(self, route_name: str, profile, delivery_id: str):
- """The ``SessionSource`` admission builds for one delivery, ``profile_routes`` resolved on it.
- The edge's coalesced-route check (``parked_profile_refusal``) asks this same source, so a
- route rule matches there exactly when it matches at admission."""
- identity = _WebhookDeliveryIdentity.from_parts(profile, route_name, delivery_id)
- source = self.build_source(chat_id=identity.session_chat_id, chat_name=f"webhook/{route_name}",
- chat_type="webhook", user_id=f"webhook:{route_name}", user_name=route_name)
- if profile and isinstance(profile, str):
- # The ``/p/<profile>/`` prefix names the profile and wins over ``profile_routes``; the
- # edge already refused it (retryable 503) when that profile is not served. Drop what
- # ``build_source`` resolved from the routes, or a rejected route would refuse it here.
- source.profile = profile
- source.profile_route_rejected, source._rejected_route_profile = False, None
- return source
- async def _admit_agent_run(self, payload: Any, prompt: str, delivery_id: str, now: float, *, route_config: dict,
- route_name: str, profile, event_type: str) -> Optional[str]:
- """Record delivery info and admit the run through the durable producer (shared by the immediate
- and coalesced paths). ``"accepted"`` / ``"duplicate"``, or None when admission failed."""
- # (profile, route, delivery_id) in the session key → concurrent webhooks get independent runs.
- identity = _WebhookDeliveryIdentity.from_parts(profile, route_name, delivery_id)
- session_chat_id = identity.session_chat_id
- # ``profile`` rides along so the reply leg (``send`` → ``_deliver_cross_platform``) egresses through
- # THIS profile's adapter, home channel and secrets — not the first profile that has the platform.
- self._delivery_info[session_chat_id] = {
- "deliver": route_config.get("deliver", "log"), "profile": profile,
- "deliver_extra": self._render_delivery_extra(route_config.get("deliver_extra", {}), payload),
- "route": route_name,
- "mirror": route_config.get("mirror_to_session") is True}
- self._delivery_info_created[session_chat_id] = now
- self._delivery_info_order.append((now, session_chat_id))
- self._prune_delivery_info(now)
- source = self._admission_source(route_name, profile, delivery_id)
- event = MessageEvent(text=prompt, message_type=MessageType.TEXT, source=source, raw_message=payload,
- message_id=delivery_id, timestamp=datetime.fromtimestamp(0, UTC))
- from gateway.platforms.webhook_ingress import admit_producer
- try:
- receipt = await admit_producer(self, event)
- except Exception:
- logger.exception("[webhook] Durable admission failed for %s", delivery_id)
- return None
- if getattr(event, '_webhook_duplicate', False):
- return "duplicate"
- if receipt is None:
- # A post_gateway_admission plugin consumed the delivery: nothing was committed, so the
- # reply goes to the destination this request just validated, not a retained row.
- reply = getattr(event, '_consumer_reply', None)
- if reply:
- from gateway.platforms.webhook_delivery import snapshot_destination
- await self._deliver_to(snapshot_destination(self, self._delivery_info.get(session_chat_id)),
- session_chat_id, reply)
- return "accepted"
- from gateway.session_authorities import active_authority, authority_for_profile_id
- runner = self._message_handler.__self__
- authority = authority_for_profile_id(runner, receipt.ref.profile_id) or active_authority(runner)
- task = asyncio.create_task(self._finalize_delivery(event, authority, receipt))
- self._background_tasks.add(task)
- task.add_done_callback(self._background_tasks.discard)
- return "accepted"
- async def _finalize_delivery(self, event, authority, receipt):
- from hermes_state_runtime import get_session_admission
- try:
- row = get_session_admission(authority.db, admission_id=receipt.admission_id)
- if row['status'] in {'queued', 'started'}:
- waiter = authority.waiters.setdefault(receipt.admission_id,
- asyncio.get_running_loop().create_future())
- await asyncio.shield(waiter)
- row = get_session_admission(authority.db, admission_id=receipt.admission_id)
- event._webhook_receipt = (authority, authority._receipt(row))
- await self._end_webhook_session(event, event.source.chat_id)
- except Exception:
- logger.exception("[webhook] Could not finalize admitted delivery %s", receipt.admission_id)
- async def _end_webhook_session(self, event: MessageEvent, session_chat_id: str) -> None:
- from gateway.platforms.webhook_ingress import finalize_webhook
- binding = getattr(event, '_webhook_receipt', None)
- if binding is not None:
- authority, receipt = binding
- finalize_webhook(authority, receipt)
- # --- Signature validation ---
- def _validate_signature(self, request: web.Request, body: bytes, secret: str) -> bool:
- """Validate webhook signature (GitHub, GitLab, Svix, Standard Webhooks, Linear, generic HMAC-SHA256)."""
- headers = request.headers
- def _header(name: str) -> str:
- return headers.get(name, "") or headers.get(name.lower(), "") or headers.get(name.upper(), "")
- # Svix / AgentMail: signed content is "{id}.{timestamp}.{raw_body}". Standard Webhooks
- # (webhook-*; GitLab signing tokens) is the same scheme under other header names, but GitLab
- # sends webhook-id/webhook-timestamp on EVERY delivery and webhook-signature only when a signing
- # token is configured, so only the signature header commits to this path — a legacy
- # X-Gitlab-Token install must keep validating below (#47451, #101837).
- svix = [_header(name) for name in ("svix-id", "svix-timestamp", "svix-signature")]
- if not any(svix) and _header("webhook-signature"):
- svix = [_header(name) for name in ("webhook-id", "webhook-timestamp", "webhook-signature")]
- if any(svix):
- return _validate_svix_signature(body, secret, *svix)
- # Linear (any header case): hex HMAC of the body. GitHub: sha256=<hex>. GitLab: plain token.
- for provided, expected in (
- (_header("linear-signature"), lambda: _hex_hmac(secret, body)),
- (headers.get("X-Hub-Signature-256", ""), lambda: "sha256=" + _hex_hmac(secret, body)),
- (headers.get("X-Gitlab-Token", ""), lambda: secret)):
- if provided:
- return _hmac_str_equal(provided, expected())
- route_name = request.match_info.get("route_name", "")
- # Generic V2: X-Webhook-Signature-V2 = hex HMAC-SHA256 of "<timestamp>.<body>", X-Webhook-Timestamp
- # required. Presence of the V2 header COMMITS to V2 — it must not fall through to V1 on a
- # missing/bad timestamp, or an attacker could strip the timestamp from a captured mixed V1+V2
- # request and replay it against the still-present body-only V1 signature.
- v2_sig = headers.get("X-Webhook-Signature-V2", "")
- if v2_sig:
- v2_timestamp = headers.get("X-Webhook-Timestamp", "")
- if not v2_timestamp:
- logger.warning("[webhook] Route '%s' sent X-Webhook-Signature-V2 with no X-Webhook-Timestamp — "
- "rejecting rather than falling back to legacy V1", route_name)
- return False
- if not _timestamp_fresh(
- v2_timestamp, "[webhook] Route '%s' generic HMAC V2 timestamp outside replay window", route_name):
- return False
- return _hmac_str_equal(v2_sig, _hex_hmac(secret, v2_timestamp.encode() + b"." + body))
- # Generic V1 (legacy, deprecated): body-only HMAC → replays indefinitely.
- generic_sig = headers.get("X-Webhook-Signature", "")
- if generic_sig:
- if route_name not in self._v1_signature_warned:
- self._v1_signature_warned.add(route_name)
- logger.warning("[webhook] Route '%s' uses legacy body-only HMAC (no timestamp), which is vulnerable "
- "to replay attacks. Add an 'X-Webhook-Timestamp' header and switch to "
- "'X-Webhook-Signature-V2' (HMAC-SHA256 of '<timestamp>.<body>').", route_name)
- return _hmac_str_equal(generic_sig, _hex_hmac(secret, body))
- logger.debug("[webhook] Secret configured but no signature header found")
- return False
- # --- Prompt rendering ---
- def _render_prompt(self, template: str, payload: dict, event_type: str, route_name: str) -> str:
- """Render a prompt template with dot-notation payload access (``{pull_request.title}``);
- ``{__raw__}`` dumps the whole payload as indented JSON (truncated to 4000 chars)."""
- if not template:
- truncated = json.dumps(payload, indent=2)[:4000]
- return f"Webhook event '{event_type}' on route '{route_name}':\n\n```json\n{truncated}\n```"
- def _resolve(match: re.Match) -> str:
- key = match.group(1)
- if key == "__raw__":
- return json.dumps(payload, indent=2)[:4000]
- if key == "event_type":
- return event_type
- value: Any = payload
- for part in key.split("."):
- if not isinstance(value, dict):
- return f"{{{key}}}"
- value = value.get(part, f"{{{key}}}")
- return json.dumps(value, indent=2)[:2000] if isinstance(value, (dict, list)) else str(value)
- return _TEMPLATE_KEY_RE.sub(_resolve, template)
- def _render_delivery_extra(self, extra: dict, payload: dict) -> dict:
- """Render delivery_extra template values with payload data."""
- return {key: self._render_prompt(value, payload, "", "") if isinstance(value, str) else value
- for key, value in extra.items()}
- # --- Response delivery ---
- async def _direct_deliver(self, content: str, delivery: dict) -> SendResult:
- """deliver_only: dispatch *content* to the same delivery helpers agent-mode ``send()`` uses."""
- deliver_type = delivery.get("deliver", "log")
- if deliver_type == "log": # startup validation rejects deliver_only + log; guard defensively
- logger.info("[webhook] direct-deliver log-only: %s", content[:200])
- return SendResult(success=True)
- if deliver_type == "github_comment":
- return await self._deliver_github_comment(content, delivery)
- return await self._deliver_cross_platform(deliver_type, content, delivery)
- async def _deliver_github_comment(self, content: str, delivery: dict) -> SendResult:
- """Post agent response as a GitHub PR/issue comment via ``gh`` CLI."""
- extra = delivery.get("deliver_extra", {})
- repo, pr_number = extra.get("repo", ""), extra.get("pr_number", "")
- if not repo or not pr_number:
- logger.error("[webhook] github_comment delivery missing repo or pr_number")
- return SendResult(success=False, error="Missing repo or pr_number")
- try: # input validation (prevent CLI argument injection)
- pr_int = int(pr_number)
- if pr_int <= 0:
- raise ValueError("non-positive")
- except (ValueError, TypeError):
- logger.error("[webhook] invalid pr_number: %r", pr_number)
- return SendResult(success=False, error="Invalid pr_number")
- if not _REPO_RE.fullmatch(repo):
- logger.error("[webhook] invalid repo format: %r", repo)
- return SendResult(success=False, error="Invalid repo format")
- try:
- # Off-loop: `gh` does network I/O up to its 30s timeout; inline it froze every adapter and
- # timer on the gateway event loop.
- # Running it inline froze every adapter and timer on the gateway event loop for the duration
- # (Pattern A, #91912 class). asyncio.to_thread keeps the loop serving while the subprocess runs;
- # the worker thread is bounded by the subprocess timeout below.
- result = await asyncio.to_thread(
- subprocess.run, ["gh", "pr", "comment", str(pr_int), "--repo", repo, "--body", content],
- capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=30,
- env=self._github_env(delivery.get("profile")))
- if result.returncode == 0:
- logger.info("[webhook] Posted comment on %s#%s", repo, pr_number)
- return SendResult(success=True)
- logger.error("[webhook] gh pr comment failed: %s", result.stderr)
- return SendResult(success=False, error=result.stderr)
- except FileNotFoundError:
- logger.error("[webhook] 'gh' CLI not found — install GitHub CLI for github_comment delivery")
- return SendResult(success=False, error="gh CLI not installed")
- except Exception as e:
- logger.error("[webhook] github_comment delivery error: %s", e)
- return SendResult(success=False, error=str(e))
- def _github_env(self, profile: Optional[str]) -> Optional[dict]:
- """``gh`` environment for a delivery: a routed profile authenticates with ITS ``GH_TOKEN`` /
- ``GITHUB_TOKEN`` from the profile secret scope; under multiplex ``os.environ`` carries the default
- profile's, so those keys are dropped when the profile has none (fail closed, ``gh`` then falls to
- its own stored login). ``None`` (inherit) for bare/default-bound routes."""
- if not profile or not isinstance(profile, str) or profile == "default":
- return None
- from agent.secret_scope import get_secret
- env = {k: v for k, v in os.environ.items() if k not in _GH_TOKEN_VARS}
- with self._profile_scope(profile):
- for name in _GH_TOKEN_VARS:
- if value := get_secret(name):
- env[name] = value
- return env
- def _find_adapter(self, target_platform: Platform, profile: Optional[str]):
- """The routed profile's own adapter, fail-closed. A ``/p/<profile>/`` route must never post as
- another profile's bot, and a bare (default-bound) route must not borrow a platform parked only on
- a secondary profile — both directions leaked before #65939."""
- return self.gateway_runner._authorization_adapter(target_platform, profile)
- async def _deliver_cross_platform(self, platform_name: str, content: str, delivery: dict) -> SendResult:
- """Route response to another platform (telegram, discord, etc.)."""
- if not self.gateway_runner:
- return SendResult(success=False, error="No gateway runner for cross-platform delivery")
- try:
- target_platform = Platform(platform_name)
- except ValueError:
- return SendResult(success=False, error=f"Unknown platform: {platform_name}")
- profile = delivery.get("profile")
- if not (adapter := self._find_adapter(target_platform, profile)):
- return SendResult(success=False, error=f"Platform {platform_name} not connected")
- extra = delivery.get("deliver_extra", {})
- chat_id = extra.get("chat_id", "")
- # Whole leg under the routed profile's scope: the home channel comes from THAT profile's config
- # (``self.gateway_runner.config`` is the default profile's), and the adapter's send reads its
- # credentials through the profile secret scope.
- with self._profile_scope(profile):
- if not chat_id:
- home = self._delivery_config(profile).get_home_channel(target_platform)
- if not home:
- return SendResult(success=False, error=f"No chat_id or home channel for {platform_name}")
- chat_id = home.chat_id
- thread_id = extra.get("message_thread_id") or extra.get("thread_id") # Telegram forum topics
- result = await adapter.send(chat_id, content, metadata={"thread_id": thread_id} if thread_id else None)
- if result.success:
- self._mirror_delivery(platform_name, str(chat_id), content, delivery, thread_id)
- return result
- def _delivery_config(self, profile: Optional[str]):
- """Gateway config of the profile a delivery is bound to (call inside ``_profile_scope``)."""
- if not profile or not isinstance(profile, str):
- return self.gateway_runner.config
- from gateway.config import load_gateway_config
- return load_gateway_config()
- def _mirror_delivery(self, platform_name: str, chat_id: str, content: str, delivery: dict,
- thread_id: Optional[str]) -> None:
- """Best-effort mirror of a delivered response into the TARGET chat's session transcript, so a
- follow-up there ("so he's out?") sees what the webhook run just told the user. Without this the
- text only lives in the ephemeral opaque per-delivery webhook session and the target chat's
- agent has no idea it sent anything. Same path and USER-role convention as cron briefs
- (``cron.scheduler_delivery._maybe_mirror_cron_delivery``, #2221): the text is not the target
- session's agent speaking, and a labelled user turn merges safely on strict-alternation providers.
- Opt-in per route (``mirror_to_session: true``), default off like cron's ``mirror_delivery``: the text
- lands with user authority in a chat the route author may not own, and on ``deliver_only`` routes it is
- the raw rendered payload. Called inside the routed profile's scope so the lookup hits THAT profile's
- state.db — a DM chat_id is the user's id on every bot, so an unscoped mirror lands in another
- profile's DM with the same person. Never raises — a delivered message must not be reported failed
- because the mirror broke."""
- if delivery.get("mirror") is not True:
- return
- route = delivery.get("route") or "webhook"
- try:
- from gateway.mirror import mirror_to_session
- ok = mirror_to_session(platform_name, chat_id, f"[Webhook delivery: {route}]\n{content}",
- source_label="webhook", thread_id=thread_id, role="user")
- logger.log(logging.INFO if ok else logging.DEBUG,
- "[webhook] Route '%s' delivery %smirrored into %s:%s session", route, "" if ok else "not ",
- platform_name, chat_id)
- except Exception as e:
- logger.debug("[webhook] Route '%s' delivery mirror into %s:%s failed: %s", route, platform_name, chat_id, e)
|