webhook.py 63 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075
  1. """Generic webhook platform adapter: aiohttp server that validates HMAC-signed POSTs (GitHub, GitLab,
  2. Svix, Linear, generic), renders payloads into agent prompts, and routes responses back (github_comment
  3. or any gateway platform). Routes live under platforms.webhook.extra.routes: events (header filter),
  4. secret (REQUIRED; "INSECURE_NO_AUTH" skips validation, loopback only), prompt template, skills,
  5. deliver/deliver_extra, deliver_only (rendered prompt IS the message), cron_job (fire an existing cron
  6. job per event; the rendered prompt is transient per-run context; exclusive with deliver_only), mirror_to_session
  7. (opt-in: a delivered response is also written into the target chat's transcript so follow-ups there have
  8. context). Per-route rate limiting,
  9. idempotency cache, body-size caps checked before reading. Generic HMAC V2 binds a timestamp for
  10. replay protection; body-only V1 is deprecated but accepted with a warning."""
  11. import asyncio
  12. import base64
  13. import binascii
  14. import hashlib
  15. import hmac
  16. import json
  17. import logging
  18. import os
  19. import re
  20. import subprocess
  21. import time
  22. import uuid
  23. from collections import deque
  24. from datetime import datetime, timezone, UTC
  25. from contextlib import nullcontext, suppress
  26. from dataclasses import dataclass
  27. from typing import Any, Deque, Dict, List, Optional
  28. try:
  29. from aiohttp import web
  30. AIOHTTP_AVAILABLE = True
  31. except ImportError:
  32. AIOHTTP_AVAILABLE = False
  33. web = None # type: ignore[assignment]
  34. from gateway.config import Platform, PlatformConfig
  35. from gateway.platforms.base import BasePlatformAdapter, SendResult
  36. from gateway.platforms.event import MessageEvent, MessageType
  37. from gateway.platforms.tcp_site import start_tcp_site
  38. from gateway.platforms.webhook_coalesce import WebhookCoalescer, validate_coalesce_config
  39. from gateway.platforms.webhook_filters import DEFAULT_SCRIPT_TIMEOUT_SECONDS, WebhookRouteProcessor
  40. from gateway.platforms.webhook_mcp_events import (
  41. handle_mcp_event_control, mcp_event_delivery_id, render_mcp_event_prompt)
  42. from gateway.response_filters import is_autonomous_silence_response
  43. logger = logging.getLogger(__name__)
  44. # _resolve_request_profile sentinel: /p/<profile>/ names a profile this gateway does not serve (→ 404);
  45. # distinct from None (no prefix / default).
  46. _PROFILE_REJECTED = object()
  47. _UNPARSEABLE = object()
  48. _BUILTIN_DELIVER_PLATFORMS = {
  49. "telegram", "discord", "slack", "signal", "sms", "whatsapp", "matrix", "mattermost",
  50. "email", "dingtalk", "feishu", "wecom", "wecom_callback", "weixin",
  51. "bluebubbles", "qqbot", "yuanbao"}
  52. # ``None`` → aiohttp binds BOTH address families. "0.0.0.0" is IPv4-only (unreachable on IPv6-only
  53. # networks such as Fly.io 6PN); "::" becomes IPv6-only where the kernel sets IPV6_V6ONLY=1, breaking
  54. # the 127.0.0.1 health check. Users can pin a host via ``platforms.webhook.extra.host``.
  55. DEFAULT_HOST = None
  56. DEFAULT_PORT = 8644
  57. _INSECURE_NO_AUTH = "INSECURE_NO_AUTH"
  58. _DYNAMIC_ROUTES_FILENAME = "webhook_subscriptions.json"
  59. _RATE_WINDOW_SECONDS = 60.0
  60. # Hosts that only serve same-machine connections; anything else is a public bind.
  61. _LOOPBACK_HOSTS = frozenset({"127.0.0.1", "localhost", "::1", "ip6-localhost", "ip6-loopback"})
  62. _V2_REPLAY_WINDOW_SECONDS = 300
  63. _TEMPLATE_KEY_RE = re.compile(r"\{([a-zA-Z0-9_.]+)\}")
  64. _REPO_RE = re.compile(r"[A-Za-z0-9._-]+/[A-Za-z0-9._-]+")
  65. # Credentials `gh` reads; a routed profile's github_comment must use its own, never the process env's.
  66. _GH_TOKEN_VARS = ("GH_TOKEN", "GITHUB_TOKEN")
  67. def _header_delivery_id(headers) -> str:
  68. """The provider's delivery id (GitHub, Svix, Standard Webhooks, generic), else a fresh one."""
  69. return headers.get("X-GitHub-Delivery", headers.get("svix-id", headers.get(
  70. "webhook-id", headers.get("X-Request-ID", uuid.uuid4().hex))))
  71. @dataclass(frozen=True)
  72. class _WebhookDeliveryIdentity:
  73. """Collision-free identity for one provider delivery on one routed webhook route."""
  74. profile: str
  75. route: str
  76. delivery_id: str
  77. @classmethod
  78. def from_parts(cls, profile: Optional[str], route: str, delivery_id: str) -> "_WebhookDeliveryIdentity":
  79. return cls(profile=profile or "default", route=route, delivery_id=delivery_id)
  80. @property
  81. def session_chat_id(self) -> str:
  82. # A versioned canonical JSON tuple avoids delimiter ambiguity while keeping the chat id safe
  83. # for session-key persistence even when provider-controlled fields contain ':' or '/'.
  84. payload = json.dumps(
  85. (self.profile, self.route, self.delivery_id), ensure_ascii=False, separators=(",", ":")
  86. ).encode("utf-8")
  87. token = base64.urlsafe_b64encode(payload).decode("ascii").rstrip("=")
  88. return f"webhook:v2:{token}"
  89. @staticmethod
  90. def route_from_chat_id(chat_id: str) -> str:
  91. """The route a delivery chat id names: decoded from a ``webhook:v2:`` token, else the legacy
  92. ``webhook:{route}:{delivery}`` spelling that admissions queued before the upgrade still carry."""
  93. prefix = "webhook:v2:"
  94. if chat_id.startswith(prefix):
  95. token = chat_id[len(prefix):]
  96. _profile, route, _delivery = json.loads(base64.urlsafe_b64decode(token + "=" * (-len(token) % 4)))
  97. return str(route)
  98. return chat_id.split(":", 2)[1]
  99. def _is_loopback_host(host: Optional[str]) -> bool:
  100. """True when `host` binds only to the local machine (falsy → non-loopback: usually a public default bind)."""
  101. return bool(host) and host.strip().lower() in _LOOPBACK_HOSTS
  102. def _hmac_str_equal(provided: str, expected: str) -> bool:
  103. """Timing-safe str equality tolerant of non-ASCII: ``compare_digest`` raises TypeError on non-ASCII
  104. str and ``provided`` is an attacker-controlled header, so compare as UTF-8 bytes to fail closed."""
  105. return hmac.compare_digest(provided.encode(), expected.encode())
  106. def _hex_hmac(secret: str, data: bytes) -> str:
  107. return hmac.new(secret.encode(), data, hashlib.sha256).hexdigest()
  108. def _is_usable_secret(secret: object) -> bool:
  109. """True when ``secret`` is a string with at least one non-space character.
  110. A whitespace-only value is what an unset key looks like in config. It is
  111. falsy to a person and truthy to ``if not secret``, so a bare falsy check
  112. lets it through. Non-strings are rejected for the same reason.
  113. """
  114. return isinstance(secret, str) and bool(secret.strip())
  115. def _timestamp_fresh(raw: str, stale_msg: str, *args) -> bool:
  116. """True when integer timestamp header *raw* is within the replay window; unparseable → False,
  117. stale → warn ``stale_msg % args`` and False."""
  118. try:
  119. age = abs(int(time.time()) - int(raw))
  120. except (TypeError, ValueError):
  121. return False
  122. if age > _V2_REPLAY_WINDOW_SECONDS:
  123. logger.warning(stale_msg, *args)
  124. return False
  125. return True
  126. def _is_known_platform(name: str) -> bool:
  127. """Cross-platform delivery target: built-in names or plugin-registered platforms."""
  128. if name in _BUILTIN_DELIVER_PLATFORMS:
  129. return True
  130. with suppress(Exception):
  131. from gateway.platform_registry import platform_registry
  132. return platform_registry.is_registered(name)
  133. return False
  134. def _json_error(message: str, status: int) -> web.Response:
  135. return web.json_response({"error": message}, status=status)
  136. def check_webhook_requirements() -> bool:
  137. """Check if webhook adapter dependencies are available."""
  138. return AIOHTTP_AVAILABLE
  139. def _validate_svix_signature(body: bytes, secret: str, msg_id: str, timestamp: str, signature_header: str) -> bool:
  140. """Svix-compatible signatures (AgentMail): base64 HMAC-SHA256 of "{id}.{timestamp}.{body}"."""
  141. if not (msg_id and timestamp and signature_header and secret):
  142. return False
  143. if not _timestamp_fresh(timestamp, "[webhook] Svix signature timestamp outside replay window"):
  144. return False
  145. if secret.startswith("whsec_"):
  146. try:
  147. key = base64.b64decode(secret.removeprefix("whsec_"), validate=True)
  148. except (binascii.Error, ValueError):
  149. logger.debug("[webhook] Invalid whsec_ Svix signing secret")
  150. return False
  151. # "whsec_" alone decodes to b"": a public HMAC key, same as a blank secret. HMAC zero-pads the
  152. # key, so an all-NUL key signs exactly like b"" and is refused with it.
  153. if not key.strip(b"\x00 \t\r\n\x0b\x0c"):
  154. return False
  155. else:
  156. # Some providers document Svix-style headers but hand out raw shared secrets.
  157. logger.debug("[webhook] Validating Svix-style signature with raw secret")
  158. key = secret.encode()
  159. signed_content = msg_id.encode() + b"." + timestamp.encode() + b"." + body
  160. expected = base64.b64encode(hmac.new(key, signed_content, hashlib.sha256).digest()).decode()
  161. # Multiple space-separated "vN,<base64>" entries during secret rotation.
  162. for part in signature_header.split():
  163. version, _, signature = part.partition(",")
  164. if _ and version == "v1" and _hmac_str_equal(signature, expected):
  165. return True
  166. return False
  167. class WebhookAdapter(BasePlatformAdapter):
  168. """Generic webhook receiver that triggers agent runs from HTTP POSTs."""
  169. # Event-triggered, no human present: startup auto-resume must FINISH the interrupted work, not ask "what next?".
  170. # The startup auto-resume turn must instruct the model to FINISH the interrupted work instead of
  171. # emitting an interactive acknowledgement that abandons the task (#57056).
  172. interactive_resume: bool = False
  173. # ``/p/<profile>/webhooks/<route>`` on the shared listener (``_resolve_request_profile``).
  174. serves_profile_prefix: bool = True
  175. def __init__(self, config: PlatformConfig):
  176. super().__init__(config, Platform.WEBHOOK)
  177. extra = config.extra
  178. # Empty string / null host normalises to None ("bind all families").
  179. self._host: Optional[str] = extra.get("host", DEFAULT_HOST) or None
  180. self._port: int = int(extra.get("port", DEFAULT_PORT))
  181. self._global_secret: str = extra.get("secret", "")
  182. self._static_routes: dict[str, dict] = extra.get("routes", {})
  183. self._dynamic_routes: dict[str, dict] = {}
  184. self._dynamic_routes_stat: Optional[tuple] = None
  185. self._routes: dict[str, dict] = dict(self._static_routes)
  186. self._runner = None
  187. self._v1_signature_warned: set[str] = set() # routes already warned about legacy V1 (once per route)
  188. # Keyed by session chat_id; read by EVERY send() (interim status messages AND the final
  189. # response) so never pop on send(). TTL-pruned on each POST.
  190. self._delivery_info: dict[str, dict] = {}
  191. self._delivery_info_created: dict[str, float] = {}
  192. self._delivery_info_order: deque[tuple[float, str]] = deque()
  193. self.gateway_runner = None # set externally; needed for cross-platform delivery
  194. # Idempotency is scoped to the authenticated route and routed profile: provider delivery
  195. # IDs are not globally unique across unrelated webhook endpoints.
  196. self._seen_deliveries: dict[_WebhookDeliveryIdentity, float] = {}
  197. self._idempotency_ttl: int = 3600 # 1 hour
  198. self._seen_deliveries_next_prune_at: float = 0.0
  199. self._rate_counts: dict[str, deque[float]] = {} # per-route hit timestamps in a fixed window
  200. self._rate_limit: int = int(extra.get("rate_limit", 30)) # per minute
  201. self._max_body_bytes: int = int(extra.get("max_body_bytes", 1_048_576)) # 1MB
  202. self._script_timeout_seconds: int = int(extra.get("script_timeout_seconds", DEFAULT_SCRIPT_TIMEOUT_SECONDS))
  203. self._route_processor = WebhookRouteProcessor(script_timeout_seconds=self._script_timeout_seconds)
  204. # Opt-in per-route debounce of rapid same-entity events (route ``coalesce`` block). #92066
  205. self._coalescer = WebhookCoalescer(dispatch=self._spawn_agent_run, render=self._render_prompt)
  206. @property
  207. def token(self):
  208. # Bind native replay to the configured signing credentials. Static routes only: dynamic
  209. # subscriptions hot-reload on every POST, and an unrelated ``webhook subscribe`` must not
  210. # re-key the connector of already-admitted deliveries (their send() would see profile_mismatch).
  211. return json.dumps([self._global_secret, {name: route.get("secret", self._global_secret)
  212. for name, route in self._static_routes.items()}], sort_keys=True)
  213. # --- Lifecycle ---
  214. def _validate_route(self, name: str, route: dict) -> None:
  215. """Startup validation: secret required; INSECURE_NO_AUTH only on loopback (crash early on a public footgun)."""
  216. secret = route.get("secret", self._global_secret)
  217. if not _is_usable_secret(secret):
  218. raise ValueError(f"[webhook] Route '{name}' HMAC secret is missing, blank, or not a string. Set 'secret' "
  219. f"on the route or globally. "
  220. f"For testing without auth, set secret to '{_INSECURE_NO_AUTH}'.")
  221. if secret == _INSECURE_NO_AUTH and not _is_loopback_host(self._host):
  222. raise ValueError(f"[webhook] Route '{name}' uses INSECURE_NO_AUTH secret but is bound to non-loopback "
  223. f"host '{self._host}'. INSECURE_NO_AUTH is for local testing only. "
  224. f"Refusing to start to prevent accidental exposure.")
  225. if route.get("deliver_only"):
  226. deliver = route.get("deliver", "log")
  227. if not deliver or deliver == "log":
  228. raise ValueError(f"[webhook] Route '{name}' has deliver_only=true but deliver is '{deliver}'. Direct "
  229. f"delivery requires a real target (telegram, discord, slack, github_comment, etc.).")
  230. if route.get("cron_job"):
  231. raise ValueError(f"[webhook] Route '{name}' sets both deliver_only and cron_job. They are mutually "
  232. f"exclusive: deliver_only pushes the rendered template as a message, cron_job fires "
  233. f"an existing cron job (which handles its own delivery).")
  234. validate_coalesce_config(name, route)
  235. async def connect(self, *, is_reconnect: bool = False) -> bool:
  236. self._reload_dynamic_routes()
  237. for name, route in self._routes.items():
  238. self._validate_route(name, route)
  239. # client_max_size enforces the cap on every read path, including chunked bodies without
  240. # Content-Length that bypass the header check.
  241. app = web.Application(client_max_size=self._max_body_bytes)
  242. app.router.add_get("/health", self._handle_health)
  243. app.router.add_post("/webhooks/{route_name}", self._handle_webhook)
  244. # /p/<profile>/ routes the event to that profile (honored only under gateway.multiplex_profiles).
  245. app.router.add_post("/p/{profile}/webhooks/{route_name}", self._handle_webhook)
  246. # Without an api_server listener this port is the shared listener: forward a secondary's
  247. # inbound-port platforms (Twilio, LINE, Teams, ...) registered in shared-listener mode.
  248. app.router.add_route("*", "/p/{profile}/{tail:.*}", self._handle_profile_ingress)
  249. self._runner = web.AppRunner(app)
  250. await self._runner.setup()
  251. try:
  252. await start_tcp_site(self._runner, self._host, self._port, log_tag="webhook")
  253. except OSError as exc:
  254. await self._runner.cleanup()
  255. self._runner = None
  256. logger.error("[webhook] Could not bind %s:%d: %s. Set a different host or port in config.yaml under "
  257. "platforms.webhook.extra.", self._host or "all IPv4+IPv6 interfaces", self._port, exc)
  258. return False
  259. from gateway.platforms.shared_ingress import listener_base_url
  260. self._mark_connected(listener_base=listener_base_url(self._host, self._port))
  261. logger.info("[webhook] Listening on %s:%d — routes: %s", self._host or "* (all interfaces, IPv4+IPv6)",
  262. self._port, ", ".join(self._routes.keys()) or "(none configured)")
  263. self._wire_plugin_handlers(None)
  264. return True
  265. async def disconnect(self) -> None:
  266. await self._coalescer.flush() # buffered events are dispatched, not dropped, on shutdown/reconnect
  267. if self._runner:
  268. await self._runner.cleanup()
  269. self._runner = None
  270. self._mark_disconnected()
  271. logger.info("[webhook] Disconnected")
  272. async def send(self, chat_id: str, content: str, reply_to: Optional[str] = None,
  273. metadata: Optional[dict[str, Any]] = None) -> SendResult:
  274. """Deliver the agent's response to the destination stored for its opaque ``chat_id`` —
  275. read with ``.get()``, never popped."""
  276. # Autonomous lane (no human reader): the loose marker matcher shared with cron (marker on its own
  277. # first/last line), because models add a sentence explaining why they stayed quiet, which the
  278. # interactive exact-match rule would deliver.
  279. if is_autonomous_silence_response(content):
  280. logger.info("[webhook] Response for %s is a silence marker — not delivering", chat_id)
  281. return SendResult(success=True)
  282. from gateway.platforms.webhook_delivery import retained_destination
  283. try:
  284. delivery = retained_destination(self, chat_id)
  285. except Exception:
  286. logger.warning("[webhook] Destination unavailable for %s", chat_id, exc_info=True)
  287. return SendResult(success=False, error="Webhook destination unavailable or unauthorized")
  288. return await self._deliver_to(delivery, chat_id, content)
  289. async def _deliver_to(self, delivery: dict[str, Any], chat_id: str, content: str) -> SendResult:
  290. deliver_type = delivery["deliver"]
  291. if deliver_type == "log":
  292. logger.info("[webhook] Response for %s: %s", chat_id, content[:200])
  293. return SendResult(success=True)
  294. if deliver_type == "github_comment":
  295. return await self._deliver_github_comment(content, delivery)
  296. if self.gateway_runner and _is_known_platform(deliver_type):
  297. return await self._deliver_cross_platform(deliver_type, content, delivery)
  298. logger.warning("[webhook] Unknown deliver type: %s", deliver_type)
  299. return SendResult(success=False, error=f"Unknown deliver type: {deliver_type}")
  300. def _prune_delivery_info(self, now: float) -> None:
  301. """Drop delivery_info entries older than the idempotency TTL (bounds the dict by ``rate_limit * TTL``
  302. even when runs never produce a final response)."""
  303. created, order = self._delivery_info_created, self._delivery_info_order
  304. if len(order) < len(created):
  305. order = self._delivery_info_order = deque(
  306. (at, key) for key, at in sorted(created.items(), key=lambda kv: kv[1]))
  307. cutoff = now - self._idempotency_ttl
  308. while order and order[0][0] < cutoff:
  309. created_at, key = order.popleft()
  310. if created.get(key) == created_at:
  311. self._delivery_info.pop(key, None)
  312. created.pop(key, None)
  313. def _prune_seen_deliveries(self, now: float) -> None:
  314. """Occasionally prune expired delivery IDs without scanning every POST."""
  315. if now < self._seen_deliveries_next_prune_at:
  316. return
  317. cutoff = now - self._idempotency_ttl
  318. for k in [k for k, t in self._seen_deliveries.items() if t < cutoff]:
  319. self._seen_deliveries.pop(k, None)
  320. self._seen_deliveries_next_prune_at = now + min(60.0, max(1.0, self._idempotency_ttl / 10))
  321. def _record_rate_limit_hit(self, route_name: str, now: float) -> bool:
  322. """Return True if route is still within limit after recording this hit."""
  323. if not isinstance(window := self._rate_counts.get(route_name), deque):
  324. window = self._rate_counts[route_name] = deque(window or ())
  325. cutoff = now - _RATE_WINDOW_SECONDS
  326. while window and window[0] < cutoff:
  327. window.popleft()
  328. if len(window) >= self._rate_limit:
  329. return False
  330. window.append(now)
  331. return True
  332. def _record_delivery_id(self, identity: _WebhookDeliveryIdentity, now: float) -> bool:
  333. """Return True when this route/profile-qualified delivery should be processed."""
  334. if (seen_at := self._seen_deliveries.get(identity)) is not None and now - seen_at < self._idempotency_ttl:
  335. return False
  336. if seen_at is not None:
  337. self._seen_deliveries.pop(identity, None)
  338. self._seen_deliveries[identity] = now
  339. if len(self._seen_deliveries) > max(self._rate_limit * 2, 128):
  340. self._prune_seen_deliveries(now)
  341. return True
  342. async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
  343. return {"name": chat_id, "type": "webhook"}
  344. def toolsets_for_source(self, source) -> Optional[list[str]]:
  345. """Per-route ``toolsets`` override (config.yaml or a manual key in webhook_subscriptions.json —
  346. deliberately NOT settable via `hermes webhook subscribe`, so an agent-created subscription
  347. cannot self-grant tools). Keyed on ``user_id`` (exactly ``webhook:{route}`` as authenticated), not
  348. ``chat_id``, whose caller-supplied delivery id and ``:``-bearing route names make any split ambiguous
  349. (GHSA-2fmg-cjqm-hhrj)."""
  350. user_id = str(getattr(source, "user_id", "") or "")
  351. if not user_id.startswith("webhook:"):
  352. return None
  353. route_config = self._routes.get(user_id[len("webhook:"):])
  354. toolsets = route_config.get("toolsets") if isinstance(route_config, dict) else None
  355. if not isinstance(toolsets, list):
  356. return None
  357. return [str(t).strip() for t in toolsets if str(t).strip()] or None
  358. # --- HTTP handlers ---
  359. async def _handle_health(self, request: web.Request) -> web.Response:
  360. """GET /health — simple health check."""
  361. return web.json_response({"status": "ok", "platform": "webhook"})
  362. def _dynamic_route_allowed(self, name: str, route: dict) -> bool:
  363. """Reject dynamic routes whose effective secret is missing, blank, or not a string
  364. (_is_usable_secret); INSECURE_NO_AUTH is loopback-only."""
  365. effective_secret = route.get("secret", self._global_secret)
  366. if not _is_usable_secret(effective_secret):
  367. logger.warning("[webhook] Dynamic route '%s' skipped: 'secret' is missing, blank, or not a string. "
  368. "Set a valid HMAC secret, or use '%s' to explicitly disable auth (testing only).",
  369. name, _INSECURE_NO_AUTH)
  370. return False
  371. if effective_secret == _INSECURE_NO_AUTH and not _is_loopback_host(self._host):
  372. logger.warning("[webhook] Dynamic route '%s' skipped: INSECURE_NO_AUTH is only allowed on loopback "
  373. "hosts. Current host: '%s'.", name, self._host)
  374. return False
  375. try:
  376. # Hot-reloaded from the request handler: a malformed block must skip the route, not 500 the request.
  377. validate_coalesce_config(name, route)
  378. except ValueError as e:
  379. logger.warning("[webhook] Dynamic route '%s' skipped: %s", name, e)
  380. return False
  381. return True
  382. def _reload_dynamic_routes(self) -> None:
  383. """Reload agent-created subscriptions when the file's stat identity changes.
  384. Runs on every POST before auth, so it never takes the CLI writer lock: writers publish via
  385. atomic rename, which also gives the file a new inode, so a restored mtime cannot hide a change;
  386. ``file_cache_version`` also catches a same-tick same-size edit made in place (a hand edit).
  387. """
  388. from hermes_constants import get_hermes_home
  389. from utils import file_cache_version
  390. subs_path = get_hermes_home() / _DYNAMIC_ROUTES_FILENAME
  391. try:
  392. stat_key = file_cache_version(subs_path)
  393. except FileNotFoundError:
  394. if self._dynamic_routes:
  395. self._dynamic_routes, self._routes = {}, dict(self._static_routes)
  396. logger.debug("[webhook] Dynamic subscriptions file removed, cleared dynamic routes")
  397. self._dynamic_routes_stat = None
  398. return
  399. except OSError as e:
  400. logger.error("[webhook] Failed to read dynamic routes: %s", e)
  401. return
  402. if stat_key == self._dynamic_routes_stat:
  403. return # No change
  404. try:
  405. data = json.loads(subs_path.read_text(encoding="utf-8-sig"))
  406. except ValueError as e:
  407. # Keep the last good snapshot, and remember this version so it is parsed once, not per POST.
  408. self._dynamic_routes_stat = stat_key
  409. logger.error("[webhook] Failed to parse dynamic routes: %s", e)
  410. return
  411. except OSError as e:
  412. logger.error("[webhook] Failed to read dynamic routes: %s", e)
  413. return
  414. if not isinstance(data, dict):
  415. self._dynamic_routes_stat = stat_key # keep the last good snapshot; parse this version once
  416. return
  417. try:
  418. self._dynamic_routes = { # static routes take precedence
  419. k: v for k, v in data.items()
  420. if isinstance(v, dict) and k not in self._static_routes and self._dynamic_route_allowed(k, v)
  421. }
  422. self._routes = {**self._dynamic_routes, **self._static_routes}
  423. self._dynamic_routes_stat = stat_key
  424. logger.info("[webhook] Reloaded %d dynamic route(s): %s", len(self._dynamic_routes),
  425. ", ".join(self._dynamic_routes.keys()) or "(none)")
  426. except Exception as e:
  427. logger.error("[webhook] Failed to reload dynamic routes: %s", e)
  428. async def _handle_profile_ingress(self, request: web.Request) -> web.StreamResponse:
  429. profile = self._resolve_request_profile(request)
  430. if profile is _PROFILE_REJECTED or profile is None:
  431. return _json_error("Unknown or unconfigured profile", 404)
  432. from gateway.platforms.shared_ingress import dispatch_profile_ingress
  433. return await dispatch_profile_ingress(
  434. self.gateway_runner, profile, request.match_info.get("tail", ""), request)
  435. def _resolve_request_profile(self, request: web.Request):
  436. """Resolve + validate the /p/<profile>/ URL prefix: None (no prefix, or multiplexing off and the
  437. prefix names this gateway's own profile), the profile name (served under multiplexing), or
  438. ``_PROFILE_REJECTED`` (unknown / not served → 404)."""
  439. profile = (request.match_info.get("profile") or "").strip()
  440. if not profile:
  441. return None
  442. cfg = getattr(self.gateway_runner, "config", None)
  443. if not getattr(cfg, "multiplex_profiles", False):
  444. # Only a self-referential prefix may fall through to the bare route; anything else fails
  445. # closed (silently ignoring the prefix served the owner's routes under another profile's URL).
  446. with suppress(Exception):
  447. from hermes_cli.profiles import profile_matches_home
  448. if profile_matches_home(profile):
  449. return None
  450. return _PROFILE_REJECTED
  451. try:
  452. from hermes_cli.profiles import profiles_to_serve
  453. served = {name for name, _ in profiles_to_serve(multiplex=True)}
  454. except Exception:
  455. return _PROFILE_REJECTED
  456. return profile if profile in served else _PROFILE_REJECTED
  457. @staticmethod
  458. def _route_allows_profile(route_config: dict, request_profile: Optional[str]) -> bool:
  459. """Omitting ``profile`` binds a route to default; an explicit null/blank/non-string fails closed."""
  460. configured = route_config.get("profile") if "profile" in route_config else "default"
  461. if not isinstance(configured, str) or not configured.strip():
  462. return False
  463. return configured.strip() == (request_profile or "default")
  464. @staticmethod
  465. def _profile_scope(profile: Optional[str]):
  466. """Runtime scope for a resolved ``/p/<profile>/`` prefix; bare routes get a no-op."""
  467. if not profile or not isinstance(profile, str):
  468. return nullcontext()
  469. from gateway.run import _profile_runtime_scope
  470. from hermes_cli.profiles import get_profile_dir
  471. return _profile_runtime_scope(get_profile_dir(profile))
  472. async def _read_authenticated_body(self, request: web.Request, route_name: str,
  473. route_config: dict) -> tuple[Optional[bytes], Optional[web.Response]]:
  474. """Auth-before-body: size-cap, read, then HMAC-validate. Returns ``(body, None)`` or ``(None, response)``."""
  475. if (request.content_length or 0) > self._max_body_bytes:
  476. return None, _json_error("Payload too large", 413)
  477. try:
  478. raw_body = await request.read()
  479. except web.HTTPRequestEntityTooLarge: # client_max_size tripped — chunked or lying Content-Length
  480. return None, _json_error("Payload too large", 413)
  481. except Exception as e:
  482. logger.error("[webhook] Failed to read body: %s", e)
  483. return None, _json_error("Bad request", 400)
  484. if len(raw_body) > self._max_body_bytes: # defense in depth if the server-level limit was bypassed
  485. return None, _json_error("Payload too large", 413)
  486. # Missing, blank, or non-string secrets fail closed here too (not only in connect()), so direct
  487. # handler reuse cannot become an unauthenticated dispatch surface.
  488. secret = route_config.get("secret", self._global_secret)
  489. if not _is_usable_secret(secret):
  490. logger.error("[webhook] Route %s HMAC secret is missing, blank, or not a string; refusing request",
  491. route_name)
  492. return None, _json_error("Webhook route is missing an HMAC secret", 403)
  493. if secret != _INSECURE_NO_AUTH and not self._validate_signature(request, raw_body, secret):
  494. logger.warning("[webhook] Invalid signature for route %s", route_name)
  495. return None, _json_error("Invalid signature", 401)
  496. return raw_body, None
  497. @staticmethod
  498. def _parse_body(raw_body: bytes) -> Any:
  499. """JSON, falling back to form-encoded; ``_UNPARSEABLE`` when neither parses."""
  500. try:
  501. return json.loads(raw_body)
  502. except json.JSONDecodeError:
  503. try:
  504. import urllib.parse
  505. return dict(urllib.parse.parse_qsl(raw_body.decode("utf-8")))
  506. except Exception:
  507. return _UNPARSEABLE
  508. async def _handle_deliver_only(self, prompt: str, payload: Any, route_config: dict, route_name: str,
  509. event_type: str, delivery_id: str, profile: Optional[str] = None) -> web.Response:
  510. """deliver_only: the rendered prompt IS the message — skip the agent, reuse the same
  511. auth/rate-limit/idempotency/template pipeline."""
  512. delivery = {"deliver": route_config.get("deliver", "log"), "payload": payload, "profile": profile,
  513. "deliver_extra": self._render_delivery_extra(route_config.get("deliver_extra", {}), payload),
  514. "route": route_name,
  515. "mirror": route_config.get("mirror_to_session") is True}
  516. logger.info("[webhook] direct-deliver event=%s route=%s target=%s msg_len=%d delivery=%s", event_type,
  517. route_name, delivery["deliver"], len(prompt), delivery_id)
  518. failed = {"status": "error", "error": "Delivery failed", "delivery_id": delivery_id}
  519. try:
  520. result = await self._direct_deliver(prompt, delivery)
  521. except Exception:
  522. logger.exception("[webhook] direct-deliver failed route=%s delivery=%s", route_name, delivery_id)
  523. return web.json_response(failed, status=502)
  524. if result.success:
  525. return web.json_response({"status": "delivered", "route": route_name, "target": delivery["deliver"],
  526. "delivery_id": delivery_id}, status=200)
  527. # Target rejected it — 502 with a generic error (don't leak adapter detail).
  528. logger.warning("[webhook] direct-deliver target rejected route=%s target=%s error=%s", route_name,
  529. delivery["deliver"], result.error)
  530. return web.json_response(failed, status=502)
  531. def _handle_cron_trigger(self, prompt: str, route_config: dict, route_name: str, event_type: str,
  532. delivery_id: str, profile: Optional[str] = None) -> web.Response:
  533. """cron_job: fire an EXISTING cron job on this event instead of starting a webhook agent session.
  534. The rendered prompt is transient per-run context (same rail as ``cronjob(action='run', prompt=...)``);
  535. the job's own prompt, skills, model and delivery apply. Same auth/rate-limit/filter/script/idempotency
  536. pipeline as agent routes; 202 immediately, the run happens on a worker thread."""
  537. job_ref = str(route_config["cron_job"])
  538. event_context = (f"This run was triggered by webhook event '{event_type}' on route '{route_name}' "
  539. f"(not the schedule).\n\n{prompt}")
  540. logger.info("[webhook] cron-trigger event=%s route=%s job=%s delivery=%s", event_type, route_name, job_ref,
  541. delivery_id)
  542. async def _fire_cron_job() -> None:
  543. try:
  544. from tools.cronjob_tools import execute_job_for_event
  545. # The job store (cron/jobs.json) and the run belong to the ROUTED profile, not the gateway's
  546. # default home; to_thread copies contextvars so the scope follows. A cron job is a full agent
  547. # run (minutes) — keep it off the gateway event loop.
  548. with self._profile_scope(profile):
  549. result = await asyncio.to_thread(execute_job_for_event, job_ref, event_context)
  550. if not result.get("success"):
  551. logger.warning("[webhook] cron-trigger job=%s route=%s did not complete cleanly: %s", job_ref,
  552. route_name, result.get("error"))
  553. except Exception:
  554. logger.exception("[webhook] cron-trigger failed job=%s route=%s", job_ref, route_name)
  555. task = asyncio.create_task(_fire_cron_job())
  556. self._background_tasks.add(task)
  557. task.add_done_callback(self._background_tasks.discard)
  558. return web.json_response({"status": "accepted", "route": route_name, "cron_job": job_ref, "event": event_type,
  559. "delivery_id": delivery_id}, status=202)
  560. def _resolve_route(self, request: web.Request) -> tuple[str, Optional[dict], Any, Optional[web.Response]]:
  561. """Route + profile lookup for a POST; ``(route_name, route_config, profile, error_response)``."""
  562. self._reload_dynamic_routes() # hot-reload dynamic subscriptions (stat-gated, lock-free)
  563. route_name = request.match_info.get("route_name", "")
  564. route_config = self._routes.get(route_name)
  565. profile = self._resolve_request_profile(request)
  566. if profile is _PROFILE_REJECTED:
  567. return route_name, None, profile, _json_error("Unknown or unconfigured profile", 404)
  568. if not route_config:
  569. return route_name, None, profile, _json_error(f"Unknown route: {route_name}", 404)
  570. if not self._route_allows_profile(route_config, profile):
  571. logger.warning("[webhook] Route %s is not authorized for profile %r", route_name, profile or "default")
  572. # Same as unknown-route so profile mismatches can't enumerate route bindings.
  573. return route_name, None, profile, _json_error(f"Unknown route: {route_name}", 404)
  574. # Disabled routes stay in the subscriptions file (dashboard can re-enable) but reject events.
  575. # Only an explicit ``enabled: false`` turns a route off.
  576. if route_config.get("enabled", True) is False:
  577. return route_name, None, profile, _json_error(f"Route disabled: {route_name}", 403)
  578. return route_name, route_config, profile, None
  579. @staticmethod
  580. def _apply_skills(prompt: str, skills: list) -> str:
  581. """Inject the first matching skill via build_skill_invocation_message() directly — /skill-name slash
  582. commands would be intercepted by the command parser."""
  583. try:
  584. from agent.skill_commands import build_skill_invocation_message, get_skill_commands
  585. skill_cmds = get_skill_commands()
  586. for skill_name in skills:
  587. cmd_key = f"/{skill_name}"
  588. if cmd_key in skill_cmds:
  589. skill_content = build_skill_invocation_message(cmd_key, user_instruction=prompt)
  590. if skill_content:
  591. return skill_content
  592. else:
  593. logger.warning("[webhook] Skill '%s' not found", skill_name)
  594. except Exception as e:
  595. logger.warning("[webhook] Skill loading failed: %s", e)
  596. return prompt
  597. async def _handle_webhook(self, request: web.Request) -> web.Response:
  598. """POST /webhooks/{route_name} — receive and process a webhook event."""
  599. route_name, route_config, profile, error_response = self._resolve_route(request)
  600. if error_response is None:
  601. raw_body, error_response = await self._read_authenticated_body(request, route_name, route_config)
  602. if error_response is not None:
  603. return error_response
  604. headers = request.headers
  605. delivery_id = _header_delivery_id(headers)
  606. # A parked profile is retried, before any delivery id is recorded. The check resolves
  607. # ``profile_routes`` against the very source admission builds for this delivery.
  608. from gateway.platforms.webhook_ingress import parked_profile_refusal
  609. error_response = parked_profile_refusal(
  610. self.gateway_runner, profile, route_config,
  611. lambda: self._admission_source(route_name, profile, delivery_id))
  612. if error_response is not None:
  613. return error_response
  614. # Rate limiting (after auth)
  615. if not self._record_rate_limit_hit(route_name, time.time()):
  616. return _json_error("Rate limit exceeded", 429)
  617. payload = self._parse_body(raw_body)
  618. if payload is _UNPARSEABLE:
  619. return _json_error("Cannot parse body", 400)
  620. mcp_control = await handle_mcp_event_control(self, route_name, route_config, payload, profile)
  621. if mcp_control is not None:
  622. return mcp_control
  623. delivery_id = mcp_event_delivery_id(route_config, payload) or delivery_id
  624. event_type = (headers.get("X-GitHub-Event", "") or headers.get("X-GitLab-Event", "")
  625. or payload.get("event_type", "") or payload.get("type", "") or "unknown")
  626. allowed_events = route_config.get("events", [])
  627. if allowed_events and event_type not in allowed_events:
  628. logger.debug("[webhook] Ignoring event %s for route %s (allowed: %s)", event_type, route_name,
  629. allowed_events)
  630. return web.json_response({"status": "ignored", "event": event_type})
  631. if not self._route_processor.route_filters_match(route_config, payload, event_type, request.headers):
  632. logger.info("[webhook] filtered event=%s route=%s", event_type, route_name)
  633. return web.json_response({"status": "ignored", "reason": "filter", "route": route_name})
  634. # Script, prompt render and skill lookup read the profile's home (skills/, config); the runner
  635. # only enters the routed profile's scope later around handle_message, so enter it here.
  636. # See #67277.
  637. with self._profile_scope(profile):
  638. script = route_config.get("script")
  639. if script:
  640. # Shells out (up to its timeout) — worker thread so the loop isn't blocked; to_thread
  641. # copies contextvars so the profile scope follows.
  642. keep, transformed_payload = await asyncio.to_thread(
  643. self._route_processor.run_route_script, script, payload)
  644. if not keep:
  645. logger.info("[webhook] script ignored event=%s route=%s", event_type, route_name)
  646. return web.json_response({"status": "ignored", "reason": "script", "route": route_name})
  647. payload = transformed_payload or payload
  648. prompt = (render_mcp_event_prompt(self, route_config, payload, event_type, route_name)
  649. or self._render_prompt(route_config.get("prompt", ""), payload, event_type, route_name))
  650. # cron_job routes: the job's own skills apply; the rendered prompt is only per-run context.
  651. if (skills := route_config.get("skills", [])) and not route_config.get("cron_job"):
  652. prompt = self._apply_skills(prompt, skills)
  653. now = time.time() # idempotency: skip duplicate deliveries (webhook retries)
  654. delivery_identity = _WebhookDeliveryIdentity.from_parts(profile, route_name, delivery_id)
  655. coalesce = route_config.get("coalesce")
  656. # deliver_only, cron_job and coalesced events act before (or without) a durable admission, so
  657. # the ledger cannot dedupe a provider retry or a replayed signed delivery; the route-scoped
  658. # in-memory guard is their only replay defence (main dedupes every route here).
  659. non_durable = bool(route_config.get("deliver_only") or route_config.get("cron_job")
  660. or isinstance(coalesce, dict))
  661. if non_durable and not self._record_delivery_id(delivery_identity, now):
  662. logger.info("[webhook] Skipping duplicate delivery %s on route %s", delivery_id, route_name)
  663. return web.json_response({"status": "duplicate", "delivery_id": delivery_id}, status=200)
  664. if route_config.get("cron_job"):
  665. return self._handle_cron_trigger(prompt, route_config, route_name, event_type, delivery_id, profile)
  666. if route_config.get("deliver_only"):
  667. return await self._handle_deliver_only(prompt, payload, route_config, route_name, event_type, delivery_id,
  668. profile)
  669. if isinstance(coalesce, dict) and self._coalescer.enqueue(
  670. route_name=route_name, coalesce=coalesce, payload=payload, event_type=event_type, prompt=prompt,
  671. delivery_id=delivery_id, now=now, route_config=route_config, profile=profile):
  672. return web.json_response({"status": "coalesced", "route": route_name, "event": event_type,
  673. "delivery_id": delivery_id}, status=202)
  674. return await self._dispatch_agent_run(request, route_config, route_name, profile, payload, prompt, event_type,
  675. delivery_id, now)
  676. async def _dispatch_agent_run(self, request, route_config: dict, route_name: str, profile, payload: Any, prompt: str,
  677. event_type: str, delivery_id: str, now: float) -> web.Response:
  678. """Acknowledge only after the authority commits the immutable delivery."""
  679. logger.info("[webhook] %s event=%s route=%s prompt_len=%d delivery=%s", request.method, event_type, route_name,
  680. len(prompt), delivery_id)
  681. outcome = await self._admit_agent_run(payload, prompt, delivery_id, now, route_config=route_config,
  682. route_name=route_name, profile=profile, event_type=event_type)
  683. if outcome is None:
  684. return _json_error("Admission unavailable; retry this delivery", 503)
  685. if outcome == "duplicate":
  686. return web.json_response({"status": "duplicate", "delivery_id": delivery_id}, status=200)
  687. return web.json_response({"status": "accepted", "route": route_name, "event": event_type,
  688. "delivery_id": delivery_id}, status=202)
  689. def _spawn_agent_run(self, payload: Any, prompt: str, delivery_id: str, now: float, *, route_config: dict,
  690. route_name: str, profile, event_type: str, superseded=()) -> asyncio.Task:
  691. """Coalesced-path dispatch (settled timer / disconnect flush): admit the merged event as a task
  692. so ``WebhookCoalescer.flush`` can await the hand-off. The HTTP ack for these deliveries was
  693. already ``coalesced``: an admission failure is logged and gives back the batch's delivery ids
  694. (*superseded* too), so a resend of any of them is processed, not answered as a duplicate."""
  695. async def _admit_or_log():
  696. outcome = await self._admit_agent_run(payload, prompt, delivery_id, now, route_config=route_config,
  697. route_name=route_name, profile=profile, event_type=event_type)
  698. if outcome is None:
  699. logger.error("[webhook] Coalesced delivery %s on route %s was not admitted", delivery_id, route_name)
  700. for released in (*superseded, delivery_id):
  701. self._seen_deliveries.pop(_WebhookDeliveryIdentity.from_parts(profile, route_name, released), None)
  702. task = asyncio.create_task(_admit_or_log())
  703. self._background_tasks.add(task)
  704. task.add_done_callback(self._background_tasks.discard)
  705. return task
  706. def _admission_source(self, route_name: str, profile, delivery_id: str):
  707. """The ``SessionSource`` admission builds for one delivery, ``profile_routes`` resolved on it.
  708. The edge's coalesced-route check (``parked_profile_refusal``) asks this same source, so a
  709. route rule matches there exactly when it matches at admission."""
  710. identity = _WebhookDeliveryIdentity.from_parts(profile, route_name, delivery_id)
  711. source = self.build_source(chat_id=identity.session_chat_id, chat_name=f"webhook/{route_name}",
  712. chat_type="webhook", user_id=f"webhook:{route_name}", user_name=route_name)
  713. if profile and isinstance(profile, str):
  714. # The ``/p/<profile>/`` prefix names the profile and wins over ``profile_routes``; the
  715. # edge already refused it (retryable 503) when that profile is not served. Drop what
  716. # ``build_source`` resolved from the routes, or a rejected route would refuse it here.
  717. source.profile = profile
  718. source.profile_route_rejected, source._rejected_route_profile = False, None
  719. return source
  720. async def _admit_agent_run(self, payload: Any, prompt: str, delivery_id: str, now: float, *, route_config: dict,
  721. route_name: str, profile, event_type: str) -> Optional[str]:
  722. """Record delivery info and admit the run through the durable producer (shared by the immediate
  723. and coalesced paths). ``"accepted"`` / ``"duplicate"``, or None when admission failed."""
  724. # (profile, route, delivery_id) in the session key → concurrent webhooks get independent runs.
  725. identity = _WebhookDeliveryIdentity.from_parts(profile, route_name, delivery_id)
  726. session_chat_id = identity.session_chat_id
  727. # ``profile`` rides along so the reply leg (``send`` → ``_deliver_cross_platform``) egresses through
  728. # THIS profile's adapter, home channel and secrets — not the first profile that has the platform.
  729. self._delivery_info[session_chat_id] = {
  730. "deliver": route_config.get("deliver", "log"), "profile": profile,
  731. "deliver_extra": self._render_delivery_extra(route_config.get("deliver_extra", {}), payload),
  732. "route": route_name,
  733. "mirror": route_config.get("mirror_to_session") is True}
  734. self._delivery_info_created[session_chat_id] = now
  735. self._delivery_info_order.append((now, session_chat_id))
  736. self._prune_delivery_info(now)
  737. source = self._admission_source(route_name, profile, delivery_id)
  738. event = MessageEvent(text=prompt, message_type=MessageType.TEXT, source=source, raw_message=payload,
  739. message_id=delivery_id, timestamp=datetime.fromtimestamp(0, UTC))
  740. from gateway.platforms.webhook_ingress import admit_producer
  741. try:
  742. receipt = await admit_producer(self, event)
  743. except Exception:
  744. logger.exception("[webhook] Durable admission failed for %s", delivery_id)
  745. return None
  746. if getattr(event, '_webhook_duplicate', False):
  747. return "duplicate"
  748. if receipt is None:
  749. # A post_gateway_admission plugin consumed the delivery: nothing was committed, so the
  750. # reply goes to the destination this request just validated, not a retained row.
  751. reply = getattr(event, '_consumer_reply', None)
  752. if reply:
  753. from gateway.platforms.webhook_delivery import snapshot_destination
  754. await self._deliver_to(snapshot_destination(self, self._delivery_info.get(session_chat_id)),
  755. session_chat_id, reply)
  756. return "accepted"
  757. from gateway.session_authorities import active_authority, authority_for_profile_id
  758. runner = self._message_handler.__self__
  759. authority = authority_for_profile_id(runner, receipt.ref.profile_id) or active_authority(runner)
  760. task = asyncio.create_task(self._finalize_delivery(event, authority, receipt))
  761. self._background_tasks.add(task)
  762. task.add_done_callback(self._background_tasks.discard)
  763. return "accepted"
  764. async def _finalize_delivery(self, event, authority, receipt):
  765. from hermes_state_runtime import get_session_admission
  766. try:
  767. row = get_session_admission(authority.db, admission_id=receipt.admission_id)
  768. if row['status'] in {'queued', 'started'}:
  769. waiter = authority.waiters.setdefault(receipt.admission_id,
  770. asyncio.get_running_loop().create_future())
  771. await asyncio.shield(waiter)
  772. row = get_session_admission(authority.db, admission_id=receipt.admission_id)
  773. event._webhook_receipt = (authority, authority._receipt(row))
  774. await self._end_webhook_session(event, event.source.chat_id)
  775. except Exception:
  776. logger.exception("[webhook] Could not finalize admitted delivery %s", receipt.admission_id)
  777. async def _end_webhook_session(self, event: MessageEvent, session_chat_id: str) -> None:
  778. from gateway.platforms.webhook_ingress import finalize_webhook
  779. binding = getattr(event, '_webhook_receipt', None)
  780. if binding is not None:
  781. authority, receipt = binding
  782. finalize_webhook(authority, receipt)
  783. # --- Signature validation ---
  784. def _validate_signature(self, request: web.Request, body: bytes, secret: str) -> bool:
  785. """Validate webhook signature (GitHub, GitLab, Svix, Standard Webhooks, Linear, generic HMAC-SHA256)."""
  786. headers = request.headers
  787. def _header(name: str) -> str:
  788. return headers.get(name, "") or headers.get(name.lower(), "") or headers.get(name.upper(), "")
  789. # Svix / AgentMail: signed content is "{id}.{timestamp}.{raw_body}". Standard Webhooks
  790. # (webhook-*; GitLab signing tokens) is the same scheme under other header names, but GitLab
  791. # sends webhook-id/webhook-timestamp on EVERY delivery and webhook-signature only when a signing
  792. # token is configured, so only the signature header commits to this path — a legacy
  793. # X-Gitlab-Token install must keep validating below (#47451, #101837).
  794. svix = [_header(name) for name in ("svix-id", "svix-timestamp", "svix-signature")]
  795. if not any(svix) and _header("webhook-signature"):
  796. svix = [_header(name) for name in ("webhook-id", "webhook-timestamp", "webhook-signature")]
  797. if any(svix):
  798. return _validate_svix_signature(body, secret, *svix)
  799. # Linear (any header case): hex HMAC of the body. GitHub: sha256=<hex>. GitLab: plain token.
  800. for provided, expected in (
  801. (_header("linear-signature"), lambda: _hex_hmac(secret, body)),
  802. (headers.get("X-Hub-Signature-256", ""), lambda: "sha256=" + _hex_hmac(secret, body)),
  803. (headers.get("X-Gitlab-Token", ""), lambda: secret)):
  804. if provided:
  805. return _hmac_str_equal(provided, expected())
  806. route_name = request.match_info.get("route_name", "")
  807. # Generic V2: X-Webhook-Signature-V2 = hex HMAC-SHA256 of "<timestamp>.<body>", X-Webhook-Timestamp
  808. # required. Presence of the V2 header COMMITS to V2 — it must not fall through to V1 on a
  809. # missing/bad timestamp, or an attacker could strip the timestamp from a captured mixed V1+V2
  810. # request and replay it against the still-present body-only V1 signature.
  811. v2_sig = headers.get("X-Webhook-Signature-V2", "")
  812. if v2_sig:
  813. v2_timestamp = headers.get("X-Webhook-Timestamp", "")
  814. if not v2_timestamp:
  815. logger.warning("[webhook] Route '%s' sent X-Webhook-Signature-V2 with no X-Webhook-Timestamp — "
  816. "rejecting rather than falling back to legacy V1", route_name)
  817. return False
  818. if not _timestamp_fresh(
  819. v2_timestamp, "[webhook] Route '%s' generic HMAC V2 timestamp outside replay window", route_name):
  820. return False
  821. return _hmac_str_equal(v2_sig, _hex_hmac(secret, v2_timestamp.encode() + b"." + body))
  822. # Generic V1 (legacy, deprecated): body-only HMAC → replays indefinitely.
  823. generic_sig = headers.get("X-Webhook-Signature", "")
  824. if generic_sig:
  825. if route_name not in self._v1_signature_warned:
  826. self._v1_signature_warned.add(route_name)
  827. logger.warning("[webhook] Route '%s' uses legacy body-only HMAC (no timestamp), which is vulnerable "
  828. "to replay attacks. Add an 'X-Webhook-Timestamp' header and switch to "
  829. "'X-Webhook-Signature-V2' (HMAC-SHA256 of '<timestamp>.<body>').", route_name)
  830. return _hmac_str_equal(generic_sig, _hex_hmac(secret, body))
  831. logger.debug("[webhook] Secret configured but no signature header found")
  832. return False
  833. # --- Prompt rendering ---
  834. def _render_prompt(self, template: str, payload: dict, event_type: str, route_name: str) -> str:
  835. """Render a prompt template with dot-notation payload access (``{pull_request.title}``);
  836. ``{__raw__}`` dumps the whole payload as indented JSON (truncated to 4000 chars)."""
  837. if not template:
  838. truncated = json.dumps(payload, indent=2)[:4000]
  839. return f"Webhook event '{event_type}' on route '{route_name}':\n\n```json\n{truncated}\n```"
  840. def _resolve(match: re.Match) -> str:
  841. key = match.group(1)
  842. if key == "__raw__":
  843. return json.dumps(payload, indent=2)[:4000]
  844. if key == "event_type":
  845. return event_type
  846. value: Any = payload
  847. for part in key.split("."):
  848. if not isinstance(value, dict):
  849. return f"{{{key}}}"
  850. value = value.get(part, f"{{{key}}}")
  851. return json.dumps(value, indent=2)[:2000] if isinstance(value, (dict, list)) else str(value)
  852. return _TEMPLATE_KEY_RE.sub(_resolve, template)
  853. def _render_delivery_extra(self, extra: dict, payload: dict) -> dict:
  854. """Render delivery_extra template values with payload data."""
  855. return {key: self._render_prompt(value, payload, "", "") if isinstance(value, str) else value
  856. for key, value in extra.items()}
  857. # --- Response delivery ---
  858. async def _direct_deliver(self, content: str, delivery: dict) -> SendResult:
  859. """deliver_only: dispatch *content* to the same delivery helpers agent-mode ``send()`` uses."""
  860. deliver_type = delivery.get("deliver", "log")
  861. if deliver_type == "log": # startup validation rejects deliver_only + log; guard defensively
  862. logger.info("[webhook] direct-deliver log-only: %s", content[:200])
  863. return SendResult(success=True)
  864. if deliver_type == "github_comment":
  865. return await self._deliver_github_comment(content, delivery)
  866. return await self._deliver_cross_platform(deliver_type, content, delivery)
  867. async def _deliver_github_comment(self, content: str, delivery: dict) -> SendResult:
  868. """Post agent response as a GitHub PR/issue comment via ``gh`` CLI."""
  869. extra = delivery.get("deliver_extra", {})
  870. repo, pr_number = extra.get("repo", ""), extra.get("pr_number", "")
  871. if not repo or not pr_number:
  872. logger.error("[webhook] github_comment delivery missing repo or pr_number")
  873. return SendResult(success=False, error="Missing repo or pr_number")
  874. try: # input validation (prevent CLI argument injection)
  875. pr_int = int(pr_number)
  876. if pr_int <= 0:
  877. raise ValueError("non-positive")
  878. except (ValueError, TypeError):
  879. logger.error("[webhook] invalid pr_number: %r", pr_number)
  880. return SendResult(success=False, error="Invalid pr_number")
  881. if not _REPO_RE.fullmatch(repo):
  882. logger.error("[webhook] invalid repo format: %r", repo)
  883. return SendResult(success=False, error="Invalid repo format")
  884. try:
  885. # Off-loop: `gh` does network I/O up to its 30s timeout; inline it froze every adapter and
  886. # timer on the gateway event loop.
  887. # Running it inline froze every adapter and timer on the gateway event loop for the duration
  888. # (Pattern A, #91912 class). asyncio.to_thread keeps the loop serving while the subprocess runs;
  889. # the worker thread is bounded by the subprocess timeout below.
  890. result = await asyncio.to_thread(
  891. subprocess.run, ["gh", "pr", "comment", str(pr_int), "--repo", repo, "--body", content],
  892. capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=30,
  893. env=self._github_env(delivery.get("profile")))
  894. if result.returncode == 0:
  895. logger.info("[webhook] Posted comment on %s#%s", repo, pr_number)
  896. return SendResult(success=True)
  897. logger.error("[webhook] gh pr comment failed: %s", result.stderr)
  898. return SendResult(success=False, error=result.stderr)
  899. except FileNotFoundError:
  900. logger.error("[webhook] 'gh' CLI not found — install GitHub CLI for github_comment delivery")
  901. return SendResult(success=False, error="gh CLI not installed")
  902. except Exception as e:
  903. logger.error("[webhook] github_comment delivery error: %s", e)
  904. return SendResult(success=False, error=str(e))
  905. def _github_env(self, profile: Optional[str]) -> Optional[dict]:
  906. """``gh`` environment for a delivery: a routed profile authenticates with ITS ``GH_TOKEN`` /
  907. ``GITHUB_TOKEN`` from the profile secret scope; under multiplex ``os.environ`` carries the default
  908. profile's, so those keys are dropped when the profile has none (fail closed, ``gh`` then falls to
  909. its own stored login). ``None`` (inherit) for bare/default-bound routes."""
  910. if not profile or not isinstance(profile, str) or profile == "default":
  911. return None
  912. from agent.secret_scope import get_secret
  913. env = {k: v for k, v in os.environ.items() if k not in _GH_TOKEN_VARS}
  914. with self._profile_scope(profile):
  915. for name in _GH_TOKEN_VARS:
  916. if value := get_secret(name):
  917. env[name] = value
  918. return env
  919. def _find_adapter(self, target_platform: Platform, profile: Optional[str]):
  920. """The routed profile's own adapter, fail-closed. A ``/p/<profile>/`` route must never post as
  921. another profile's bot, and a bare (default-bound) route must not borrow a platform parked only on
  922. a secondary profile — both directions leaked before #65939."""
  923. return self.gateway_runner._authorization_adapter(target_platform, profile)
  924. async def _deliver_cross_platform(self, platform_name: str, content: str, delivery: dict) -> SendResult:
  925. """Route response to another platform (telegram, discord, etc.)."""
  926. if not self.gateway_runner:
  927. return SendResult(success=False, error="No gateway runner for cross-platform delivery")
  928. try:
  929. target_platform = Platform(platform_name)
  930. except ValueError:
  931. return SendResult(success=False, error=f"Unknown platform: {platform_name}")
  932. profile = delivery.get("profile")
  933. if not (adapter := self._find_adapter(target_platform, profile)):
  934. return SendResult(success=False, error=f"Platform {platform_name} not connected")
  935. extra = delivery.get("deliver_extra", {})
  936. chat_id = extra.get("chat_id", "")
  937. # Whole leg under the routed profile's scope: the home channel comes from THAT profile's config
  938. # (``self.gateway_runner.config`` is the default profile's), and the adapter's send reads its
  939. # credentials through the profile secret scope.
  940. with self._profile_scope(profile):
  941. if not chat_id:
  942. home = self._delivery_config(profile).get_home_channel(target_platform)
  943. if not home:
  944. return SendResult(success=False, error=f"No chat_id or home channel for {platform_name}")
  945. chat_id = home.chat_id
  946. thread_id = extra.get("message_thread_id") or extra.get("thread_id") # Telegram forum topics
  947. result = await adapter.send(chat_id, content, metadata={"thread_id": thread_id} if thread_id else None)
  948. if result.success:
  949. self._mirror_delivery(platform_name, str(chat_id), content, delivery, thread_id)
  950. return result
  951. def _delivery_config(self, profile: Optional[str]):
  952. """Gateway config of the profile a delivery is bound to (call inside ``_profile_scope``)."""
  953. if not profile or not isinstance(profile, str):
  954. return self.gateway_runner.config
  955. from gateway.config import load_gateway_config
  956. return load_gateway_config()
  957. def _mirror_delivery(self, platform_name: str, chat_id: str, content: str, delivery: dict,
  958. thread_id: Optional[str]) -> None:
  959. """Best-effort mirror of a delivered response into the TARGET chat's session transcript, so a
  960. follow-up there ("so he's out?") sees what the webhook run just told the user. Without this the
  961. text only lives in the ephemeral opaque per-delivery webhook session and the target chat's
  962. agent has no idea it sent anything. Same path and USER-role convention as cron briefs
  963. (``cron.scheduler_delivery._maybe_mirror_cron_delivery``, #2221): the text is not the target
  964. session's agent speaking, and a labelled user turn merges safely on strict-alternation providers.
  965. Opt-in per route (``mirror_to_session: true``), default off like cron's ``mirror_delivery``: the text
  966. lands with user authority in a chat the route author may not own, and on ``deliver_only`` routes it is
  967. the raw rendered payload. Called inside the routed profile's scope so the lookup hits THAT profile's
  968. state.db — a DM chat_id is the user's id on every bot, so an unscoped mirror lands in another
  969. profile's DM with the same person. Never raises — a delivered message must not be reported failed
  970. because the mirror broke."""
  971. if delivery.get("mirror") is not True:
  972. return
  973. route = delivery.get("route") or "webhook"
  974. try:
  975. from gateway.mirror import mirror_to_session
  976. ok = mirror_to_session(platform_name, chat_id, f"[Webhook delivery: {route}]\n{content}",
  977. source_label="webhook", thread_id=thread_id, role="user")
  978. logger.log(logging.INFO if ok else logging.DEBUG,
  979. "[webhook] Route '%s' delivery %smirrored into %s:%s session", route, "" if ok else "not ",
  980. platform_name, chat_id)
  981. except Exception as e:
  982. logger.debug("[webhook] Route '%s' delivery mirror into %s:%s failed: %s", route, platform_name, chat_id, e)