authz_mixin.py 48 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859
  1. """User-authorization mixin for ``GatewayRunner``: may this user/chat talk to the agent,
  2. the per-adapter DM policy, the unauthorized-DM behavior, and the bot loop guard.
  3. ``gateway.run`` is never imported at module import time (cycle). The unauthorized-DM method still
  4. logs through ``gateway.run``'s logger so its records keep that name.
  5. """
  6. from __future__ import annotations
  7. import contextlib
  8. import logging
  9. import os
  10. import threading
  11. from pathlib import Path
  12. from typing import Optional
  13. from gateway.bot_loop_guard import BotLoopGuard
  14. from gateway.config import Platform
  15. from gateway.session import SessionSource
  16. from gateway.whatsapp_identity import (
  17. expand_whatsapp_aliases as _expand_whatsapp_auth_aliases,
  18. normalize_whatsapp_identifier as _normalize_whatsapp_identifier,
  19. )
  20. _GROUP_CHAT_TYPES = frozenset({"group", "forum", "channel"})
  21. _GROUP_FORUM_TYPES = frozenset({"group", "forum"})
  22. _TRUTHY = frozenset({"true", "1", "yes"})
  23. _BOT_LOOP_GUARD_INIT_LOCK = threading.Lock()
  24. logger = logging.getLogger(__name__)
  25. # ``<PLATFORM>_ALLOWED_USERS`` / ``<PLATFORM>_ALLOW_ALL_USERS``, the group-chat allowlist env and
  26. # whether an allowlist suppresses pairing come from each platform's ``PlatformEntry``
  27. # (``allowed_users_env`` / ``allow_all_env`` / ``group_allowed_chats_env`` /
  28. # ``allowlist_suppresses_pairing``), so a plugin platform declares them like a bundled one.
  29. _GROUP_USER_ENV = {Platform.TELEGRAM: "TELEGRAM_GROUP_ALLOWED_USERS"}
  30. # Gate reads use the shared per-profile isolated reader (allowlist leak under multiplex, #72348).
  31. from gateway.platforms._shared import decode_json_list_literal as _decode_json_list_literal
  32. from gateway.platforms._shared import extra_or_secret as _extra_or_secret
  33. from gateway.platforms._shared import platform_gate_env as _auth_env
  34. def _env_truthy(name: str) -> bool:
  35. return _auth_env(name).lower() in _TRUTHY
  36. def authz_field(name, field, entry):
  37. """Late-bound :func:`gateway.platform_env.authz_field` (entry field, else the bundled declaration)."""
  38. from gateway.platform_env import authz_field as _field
  39. return _field(name, field, entry)
  40. def _group_chat_env(platform, entry=None) -> str:
  41. """The platform's group-chat allowlist env name (``PlatformEntry.group_allowed_chats_env``), or ""."""
  42. if platform is None:
  43. return ""
  44. return authz_field(platform.value, "group_allowed_chats_env", entry or _registry_entry(platform)) or ""
  45. def _registry_entry(platform):
  46. """Platform-registry entry for a (plugin) platform, or None. Discovers first (idempotent): the
  47. allowlist env names live only on the entry, so an undiscovered process must not read "no list"."""
  48. if platform is None:
  49. return None
  50. with contextlib.suppress(Exception):
  51. from hermes_cli.plugins import discover_plugins
  52. discover_plugins()
  53. with contextlib.suppress(Exception):
  54. from gateway.platform_registry import platform_registry
  55. return platform_registry.get(platform.value)
  56. return None
  57. def _coerce_allow_set(raw) -> set[str]:
  58. """Parse an allowlist (YAML list, JSON list literal string, or comma-separated scalar) into a set of strings."""
  59. if raw is None:
  60. return set()
  61. raw = _decode_json_list_literal(raw)
  62. if isinstance(raw, list):
  63. return {str(part).strip() for part in raw if str(part).strip()}
  64. return {part.strip() for part in str(raw).split(",") if part.strip()}
  65. def _allows(allowed: set[str], candidate: Optional[str]) -> bool:
  66. return "*" in allowed or candidate in allowed
  67. def _adapter_config_extra(adapter) -> dict:
  68. return getattr(getattr(adapter, "config", None), "extra", None) or {}
  69. # Nostr npub -> hex (Buzz): ``BUZZ_ALLOWED_USERS`` accepts hex or ``npub1…`` but inbound pubkeys
  70. # are always hex. Pure stdlib; mirrors plugins/platforms/buzz/adapter.py.
  71. # Without decoding, the central allowlist comparison string-matches the raw npub against the hex pubkey and
  72. # an operator who listed only their npub sees every message rejected ("Unauthorized user: <hex pubkey>",
  73. # #78428).
  74. _BECH32_CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l"
  75. _BECH32_GENERATOR = (0x3B6A57B2, 0x26508E6D, 0x1EA119FA, 0x3D4233DD, 0x2A1462B3)
  76. def _bech32_polymod(values):
  77. chk = 1
  78. for value in values:
  79. top = chk >> 25
  80. chk = (chk & 0x1FFFFFF) << 5 ^ value
  81. for i, gen in enumerate(_BECH32_GENERATOR):
  82. chk ^= gen if ((top >> i) & 1) else 0
  83. return chk
  84. def _bech32_hrp_expand(hrp: str):
  85. return [ord(c) >> 5 for c in hrp] + [0] + [ord(c) & 31 for c in hrp]
  86. def _convertbits(data, frombits: int, tobits: int, pad: bool = True):
  87. acc = 0
  88. bits = 0
  89. ret = []
  90. maxv = (1 << tobits) - 1
  91. for value in data:
  92. if value < 0 or (value >> frombits):
  93. return None
  94. acc = (acc << frombits) | value
  95. bits += frombits
  96. while bits >= tobits:
  97. bits -= tobits
  98. ret.append((acc >> bits) & maxv)
  99. if pad and bits:
  100. ret.append((acc << (tobits - bits)) & maxv)
  101. elif not pad and (bits >= frombits or ((acc << (tobits - bits)) & maxv)):
  102. return None
  103. return ret
  104. def _npub_to_hex(npub: str) -> Optional[str]:
  105. """Decode an ``npub1…`` bech32 string to a 64-char hex pubkey, else None."""
  106. npub = npub.strip().lower()
  107. if not npub.startswith("npub1"):
  108. return None
  109. try:
  110. data = [_BECH32_CHARSET.index(c) for c in npub[len("npub1"):]]
  111. except ValueError:
  112. return None
  113. if _bech32_polymod(_bech32_hrp_expand("npub") + data) != 1:
  114. return None
  115. decoded = _convertbits(data[:-6], 5, 8, pad=False)
  116. if decoded is None or len(decoded) != 32:
  117. return None
  118. return bytes(decoded).hex()
  119. def _normalize_nostr_allow_entries(entries: set) -> set:
  120. """Add the hex form of every valid ``npub1…`` entry; invalid entries are kept as-is.
  121. Hex entries pass through unchanged; each valid ``npub1…`` entry is decoded and its 64-char hex form
  122. added, so either form authorizes the same identity (#78428). Invalid entries are kept as-is (they simply
  123. never match an inbound hex pubkey).
  124. """
  125. return set(entries) | {h for e in entries if e.lower().startswith("npub1") and (h := _npub_to_hex(e))}
  126. def _principal_matches_allowlist(source, user_id: str, allowed_ids: set) -> bool:
  127. """Whether *user_id* (under any platform-specific alias) is in *allowed_ids*."""
  128. check_ids = {user_id}
  129. # WhatsApp (Baileys + Cloud): phone<->LID / JID aliases match the same principal.
  130. if source.platform in {Platform.WHATSAPP, Platform.WHATSAPP_CLOUD}:
  131. allowed_ids = set().union(*(_expand_whatsapp_auth_aliases(a) for a in allowed_ids)) or allowed_ids
  132. check_ids.update(_expand_whatsapp_auth_aliases(user_id))
  133. normalized_user_id = _normalize_whatsapp_identifier(user_id)
  134. if normalized_user_id:
  135. check_ids.add(normalized_user_id)
  136. platform_value = source.platform.value if source.platform is not None else None
  137. # SimpleX: SIMPLEX_ALLOWED_USERS matches only the stable numeric contactId (user_id).
  138. # The display name (user_name) is attacker-controlled — any contact can adopt another
  139. # contact's display name, so matching it would bypass the allowlist (#44729).
  140. # Buzz: allowlist may hold npub or hex; inbound pubkeys are hex.
  141. if platform_value == "buzz":
  142. # Buzz (Nostr-based): BUZZ_ALLOWED_USERS accepts npub or hex, but inbound event pubkeys are always
  143. # 64-char hex. Decode npub entries to hex so an operator who listed only their npub authorizes the
  144. # same identity as the hex form (#78428). Hex entries pass through unchanged, so existing hex-only
  145. # allowlists keep working.
  146. allowed_ids = _normalize_nostr_allow_entries(allowed_ids)
  147. hex_user = _npub_to_hex(user_id) if user_id.startswith("npub") else None
  148. if hex_user:
  149. check_ids.add(hex_user)
  150. return bool(check_ids & allowed_ids)
  151. class GatewayAuthorizationMixin:
  152. """User/chat authorization methods for ``GatewayRunner``."""
  153. # ``getattr(self, ...)`` throughout: test helpers build bare runners via ``object.__new__``
  154. # without ``adapters`` / ``config``.
  155. def _primary_adapters(self) -> dict:
  156. return getattr(self, "adapters", None) or {}
  157. def _profile_adapters_map(self) -> dict:
  158. return getattr(self, "_profile_adapters", None) or {}
  159. def _authorization_adapter(self, platform: Optional[Platform], profile: Optional[str] = None):
  160. """Live adapter whose intake policy gates authorization (``_adapters_for_profile`` for the
  161. profile rule). ``None`` when the profile has no adapter for *platform*.
  162. """
  163. if not platform:
  164. return None
  165. return self._adapters_for_profile(profile).get(platform)
  166. def _adapters_for_profile(self, profile: Optional[str]) -> dict:
  167. """The live adapter map *profile* may deliver through: ``_profile_adapters[p]`` for a
  168. secondary, ``self.adapters`` only for the primary/default. ``_profile_adapters`` is consulted
  169. BEFORE the active profile name: multiplex turns override ``HERMES_HOME`` so
  170. ``_active_profile_name()`` reports the secondary profile mid-turn, and treating it as primary
  171. would hand it the default bot. A named profile with no map gets ``{}`` — fail closed: a
  172. secondary whose adapter failed to connect must NOT fall back to the default profile's adapter
  173. (replies, tool sends, marker-file notices out the wrong bot)."""
  174. profile_name = (profile or "").strip() or None
  175. if not profile_name or profile_name == "default":
  176. return self._primary_adapters()
  177. profile_adapters = self._profile_adapters_map()
  178. if profile_name in profile_adapters:
  179. adapters = profile_adapters[profile_name]
  180. from cron.scheduler_preflight import has_credential_platform
  181. if has_credential_platform(adapters) or not self._is_shared_bot_satellite(profile_name):
  182. return adapters
  183. # Its own LOCAL adapter stays layered over the borrowed primary bots.
  184. return {**self._primary_adapters(), **adapters}
  185. # Identity captured at construction, not the per-turn HERMES_HOME-derived name.
  186. primary_profile = getattr(self, "_primary_profile_name", None)
  187. if not primary_profile:
  188. with contextlib.suppress(Exception):
  189. primary_profile = self._active_profile_name()
  190. return self._primary_adapters() if profile_name == primary_profile else {}
  191. def _routed_primary_adapter(self, source: Optional[SessionSource]):
  192. """The primary's transport for *source* when it is a routed destination of a shared-bot satellite.
  193. Destination-gated: the most specific default-bot route matching *source*'s chat must name
  194. *source*'s profile, and that profile must own no bot on the platform. A platform-only lookup
  195. (``_adapters_for_profile``, ``send_message``, the platform-events API) never reaches here, so a
  196. satellite cannot write to an arbitrary chat through the primary's credentials.
  197. """
  198. from gateway.delivery import resolve_delivery_transport
  199. platform = getattr(source, "platform", None)
  200. profile = (getattr(source, "profile", None) or "").strip()
  201. if platform is None or not profile or not self._is_shared_bot_satellite(profile, platform):
  202. return None
  203. if platform in (self._profile_adapters_map().get(profile) or {}):
  204. return None
  205. if not self._default_bot_routes_to(source, profile):
  206. return None
  207. transport = resolve_delivery_transport(platform, self.config, self._primary_adapters())
  208. return transport.adapter if transport is not None else None
  209. def _default_bot_routes_to(self, source: SessionSource, profile: str) -> bool:
  210. """Whether the most specific default-bot route matching *source*'s chat names *profile*."""
  211. from gateway.profile_routing import match_profile_route
  212. route = match_profile_route(
  213. self.config.profile_routes, source.platform.value, guild_id=getattr(source, "scope_id", None),
  214. chat_id=getattr(source, "chat_id", None), thread_id=getattr(source, "thread_id", None),
  215. parent_chat_id=getattr(source, "parent_chat_id", None), user_id=getattr(source, "user_id", None),
  216. )
  217. return route is not None and route.profile == profile
  218. def _restored_transport_trusted(self, source: SessionSource, identity) -> bool:
  219. """Whether a persisted receiving bot can stand in for the live one. Routes saved before inferred
  220. transports stopped being persisted may hold the primary-profile GUESS, indistinguishable on disk
  221. from a primary bot that really received the chat; for another runtime that is only genuine
  222. where a default-bot route sends the chat to that runtime. A live transport is always trusted."""
  223. if identity.transport is not None:
  224. return True
  225. primary = getattr(self, "_primary_profile_name", None) or "default"
  226. if identity.transport_profile != primary or identity.runtime_profile == primary:
  227. return True
  228. return self._default_bot_routes_to(source, identity.runtime_profile)
  229. def _names_receiving_bot(self, source: SessionSource, identity) -> bool:
  230. """Whether a multiplexed *identity* names the bot that received *source*: not inferred, and not
  231. a restored primary guess (:meth:`_restored_transport_trusted`). The shared-listener mirrors
  232. (api_server, webhook) are exempt: a secondary profile's /p/<profile>/ surface IS the primary's
  233. listener by construction (``SHARED_LISTENER_MIRROR_PLATFORMS``), never a guess.
  234. LOCAL is not: its saved launch-profile transport is the session authority's fact, but the bot
  235. that answers is the runtime profile's own LocalSessionAdapter (#139060), as on a live turn."""
  236. if identity is None or not identity.multiplexed or identity.transport_inferred:
  237. return False
  238. from gateway.config import SHARED_LISTENER_MIRROR_PLATFORMS
  239. platform = getattr(getattr(source, "platform", None), "value", None)
  240. return (platform in SHARED_LISTENER_MIRROR_PLATFORMS
  241. or self._restored_transport_trusted(source, identity))
  242. def _is_shared_bot_satellite(self, profile_name: str, platform: Optional[Platform] = None) -> bool:
  243. """A served profile that a ``profile_routes`` entry targets through the default profile's bot
  244. (gateway/AGENTS.md). With no *platform*, it must own no bot at all: such a profile drains
  245. through the primary's adapters (its ``_profile_adapters`` entry is the ``{}`` startup
  246. placeholder). With *platform*, only a bot it owns on THAT platform makes it a credential
  247. boundary there — the per-destination borrow in ``_routed_primary_adapter``. Restored/cached
  248. sources carry no transport ref, so this keeps heartbeats, completions and goal notices
  249. deliverable after a restart (the same rule ``kanban_watchers_notifier`` and cron apply)."""
  250. config = getattr(self, "config", None)
  251. if not getattr(config, "multiplex_profiles", False):
  252. return False
  253. # A bot of its own that is down (failed to connect, or dropped) still makes it a credential boundary.
  254. owned = (getattr(self, "_profile_bot_platforms", None) or {}).get(profile_name)
  255. if owned and (platform is None or platform in owned):
  256. return False
  257. routes = getattr(config, "profile_routes", None) or []
  258. if not any(r.enabled and r.profile == profile_name and r.bot_profile is None for r in routes):
  259. return False
  260. from gateway.run import _multiplex_profile_homes
  261. try:
  262. return profile_name in {name for name, _home in _multiplex_profile_homes(config)}
  263. except Exception:
  264. return False
  265. def _intake_adapter_for(self, source: Optional[SessionSource]):
  266. """The adapter that RECEIVED *source*'s event — the only one whose intake policy (ignored
  267. channels, relay fronting, re-dispatch of a still-live event) may act on it.
  268. Live provenance only: the registered transport that built the source, the process-level
  269. RelayAdapter for relay-delivered events, or the receiving bot named by a pinned
  270. ``RoutingIdentity`` (``transport_profile``) when its adapter reconnected. A source with none
  271. of these (restored row, hand-built) fails closed under multiplexing — nothing can say which
  272. bot admitted it, and guessing the runtime profile's bot is exactly the shared-bot /
  273. route-override confusion the identity exists to end. A standalone gateway owns one adapter
  274. per platform, so that adapter is the receiver by construction.
  275. """
  276. if source is None:
  277. return None
  278. owner = self._transport_owner(source)
  279. if owner is not None:
  280. return owner[0]
  281. # Relay ingress keeps the underlying platform on the source, but the one process-level
  282. # RelayAdapter owns the connector socket; a profile-aware lookup would silently disable
  283. # streaming/typing/tool progress.
  284. if getattr(source, "delivered_via_upstream_relay", False) is True:
  285. return self._primary_adapters().get(Platform.RELAY)
  286. platform = getattr(source, "platform", None)
  287. from gateway.session_identity import identity_of
  288. identity = identity_of(source)
  289. # An INFERRED transport is a guess (the primary profile), not a receiving bot: a hand-built
  290. # internal source canonicalized by ``run_inbound`` (the CLI handoff turn) would otherwise take
  291. # the primary's adapter for any chat, skipping the satellite route gate in
  292. # ``_delivery_adapter_for`` and an owned-but-down bot's fail-closed row. So would that guess
  293. # saved by an older release and restored after a restart. Neither has live provenance, so
  294. # intake is None and delivery resolves the runtime profile's owner. Covers LOCAL (#139060).
  295. if self._names_receiving_bot(source, identity):
  296. return self._adapters_for_profile(identity.transport_profile).get(platform) if platform else None
  297. if not getattr(getattr(self, "config", None), "multiplex_profiles", False):
  298. return self._primary_adapters().get(platform) if platform else None
  299. return None
  300. def _delivery_adapter_for(self, source: Optional[SessionSource]):
  301. """The adapter that ANSWERS *source*: sends, edits, typing, progress, pickers, pending slots.
  302. The receiving bot whenever it is known (:meth:`_intake_adapter_for` — a routed event replies
  303. through the bot that received it, whether the runtime is a shared-bot satellite or a profile
  304. with a bot of its own). With no live provenance the unique owner of ``(platform,
  305. runtime_profile)`` delivers — ``_adapters_for_profile`` holds one adapter per platform per
  306. profile, a shared-bot satellite drains through the primary, and a disconnected secondary
  307. fails closed to ``{}`` rather than borrowing the default bot. Restored sessions, cron,
  308. kanban and completion notices all rely on this row. Matrix: gateway/AGENTS.md § Profile scope.
  309. """
  310. if source is None:
  311. return None
  312. from gateway.session_detached import detached_route_of
  313. if detached_route_of(source):
  314. # A conversation its chat moved past answers its app viewers only, through the local
  315. # adapter's event-stream delivery (gateway/session_detached.py), never the chat.
  316. from gateway.session_identity import identity_of
  317. identity = identity_of(source)
  318. profile = identity.runtime_profile if identity is not None else getattr(source, "profile", None)
  319. return self._adapters_for_profile(profile).get(Platform.LOCAL)
  320. adapter = self._intake_adapter_for(source)
  321. if adapter is not None:
  322. return adapter
  323. # A pinned identity NAMES the receiving bot (live or restored from ``transport_profile``).
  324. # If that bot has no adapter right now it is offline: fail closed rather than fall through to
  325. # the runtime profile's bot — that fallthrough is the "restored lane answers from the wrong
  326. # bot" row the identity exists to close. Only an identity-less source (legacy row, bare
  327. # fixture) uses the unique-owner heuristic below.
  328. from gateway.session_identity import identity_of
  329. identity = identity_of(source)
  330. if self._names_receiving_bot(source, identity):
  331. return None
  332. # No identity, or one whose transport was only guessed (hand-built source, pre-column row, a
  333. # primary guess an older release saved):
  334. # the unique owner of ``(platform, runtime_profile)`` delivers.
  335. # ``getattr``: test fixtures build bare SimpleNamespace sources without ``profile``.
  336. # A satellite with no bot on the platform borrows the primary only for its routed chats.
  337. return (self._authorization_adapter(getattr(source, "platform", None), getattr(source, "profile", None))
  338. or self._routed_primary_adapter(source))
  339. def _owning_profile(self, adapter, platform):
  340. """Return (registered, profile) for a live adapter: profile is None for primary."""
  341. if adapter is self._primary_adapters().get(platform):
  342. return True, None
  343. for profile, profile_adapters in self._profile_adapters_map().items():
  344. if adapter is profile_adapters.get(platform):
  345. return True, profile
  346. return False, None
  347. def _transport_owner(self, source: SessionSource):
  348. """``(adapter, profile)`` of the registered adapter that created *source*, if retained; else None.
  349. ``source.profile`` may differ from the adapter profile when one shared credential serves
  350. several routed runtimes; ``build_source`` keeps the receiving adapter as provenance so replies
  351. stay on that transport. Restored/hand-built sources fall back (fail-closed) to profile lookup.
  352. """
  353. adapter_ref = getattr(source, "_transport_adapter_ref", None)
  354. adapter = adapter_ref() if callable(adapter_ref) else None
  355. platform = getattr(source, "platform", None)
  356. if adapter is None or platform is None:
  357. return None
  358. registered, profile = self._owning_profile(adapter, platform)
  359. return (adapter, profile) if registered else None
  360. def _authorization_home_for_source(self, source: SessionSource):
  361. """HERMES_HOME whose allowlist admits *source*: the identity's transport home (or the
  362. ingress-stamped one), else the home of the profile owning the adapter that delivers it.
  363. ``None`` = authorize in the ambient scope (multiplex off, or no live adapter — the check then
  364. fails closed on its own).
  365. Inside a routed satellite's turn the ambient scope is the satellite's, whose ``.env`` has no
  366. token/allowlist; every authorization decision made mid-turn (``/topic``, sibling ``/stop``, plugin
  367. injection, voice, auto-resume) must read the admitting bot's allowlist instead."""
  368. from gateway.session_identity import identity_of
  369. identity = identity_of(source)
  370. if identity is not None:
  371. return identity.authorization_home if identity.multiplexed else None
  372. stamped = getattr(source, "_authorization_profile_home", None)
  373. if stamped is not None:
  374. return Path(stamped)
  375. if not getattr(getattr(self, "config", None), "multiplex_profiles", False):
  376. return None
  377. # A restored/hand-built source is admitted by the bot that will answer it (auto-resume,
  378. # plugin injection) — the same unique-owner row delivery uses.
  379. adapter = self._delivery_adapter_for(source)
  380. if adapter is None:
  381. return None
  382. _registered, profile = self._owning_profile(adapter, getattr(source, "platform", None))
  383. if profile is None:
  384. from hermes_constants import get_process_hermes_home
  385. return get_process_hermes_home() # the primary bot's home, never the per-turn override
  386. from hermes_cli.profiles import get_profile_dir
  387. return get_profile_dir(profile)
  388. def _adapter_profile_for_source(self, source: SessionSource) -> Optional[str]:
  389. """Resolve the transport-owning profile for adapter policy lookups."""
  390. owner = self._transport_owner(source)
  391. if owner is not None:
  392. return owner[1]
  393. from gateway.session_identity import identity_of
  394. identity = identity_of(source)
  395. if identity is not None and identity.multiplexed:
  396. return None if identity.transport_profile == "default" else identity.transport_profile
  397. return getattr(source, "profile", None)
  398. def _restored_source(self, entry) -> Optional[SessionSource]:
  399. """``entry.origin`` with its identity re-pinned from the routing entry's persisted
  400. ``transport_profile`` (no live adapter: the restored row of the transport matrix). Every path
  401. that revives a session from durable state — auto-resume, heartbeat restore, plugin injection,
  402. background-process events — reads the origin through here, so the receiving bot decides
  403. delivery and authorization after a restart, not the runtime profile's heuristics."""
  404. source = getattr(entry, "origin", None)
  405. if source is None:
  406. return None
  407. from gateway.session_identity import restore_identity
  408. restore_identity(source, runner=self, transport_profile=getattr(entry, "transport_profile", None))
  409. return source
  410. def _adapter_flag(self, platform, name: str, profile) -> bool:
  411. """Adapter-declared boolean, False when unknown. ``authorization_is_upstream`` (relay: a trusted
  412. authenticated upstream decides) is honored directly; ``enforces_own_access_policy`` (WeCom, Weixin,
  413. Yuanbao, QQBot, WhatsApp gate at intake) is NOT "already authorized" — those adapters default to
  414. ``open``, so ``_is_user_authorized`` only trusts them under an actual ``allowlist`` policy."""
  415. if not platform:
  416. return False
  417. adapter = self._authorization_adapter(platform, profile)
  418. return adapter is not None and bool(getattr(adapter, name, False))
  419. def _config_extra(self, platform) -> dict:
  420. """``config.platforms[platform].extra`` as a dict ({} when absent)."""
  421. platforms = getattr(getattr(self, "config", None), "platforms", None)
  422. extra = getattr(platforms.get(platform), "extra", None) if platforms is not None else None
  423. return extra if isinstance(extra, dict) else {}
  424. def _adapter_setting(self, platform, attr: str, extra_key: str, profile):
  425. """Live adapter's resolved ``attr`` (folds in the ``<PLATFORM>_*`` env override),
  426. else ``config.extra[extra_key]`` for bare runners with no adapter."""
  427. adapter = self._authorization_adapter(platform, profile)
  428. value = getattr(adapter, attr, None) if adapter is not None else None
  429. if value is None:
  430. value = self._config_extra(platform).get(extra_key)
  431. return value
  432. def _adapter_policy(self, platform, kind: str, profile) -> str:
  433. """Lowercased effective ``dm_policy`` (open/allowlist/disabled/pairing) or ``group_policy``
  434. (open/allowlist/disabled) for *kind* in {"dm", "group"}; ``""`` if unknown."""
  435. if not platform:
  436. return ""
  437. return str(self._adapter_setting(platform, f"_{kind}_policy", f"{kind}_policy", profile) or "").strip().lower()
  438. def _adapter_group_has_sender_allowlist(
  439. self, platform: Optional[Platform], chat_id: Optional[str], *, profile: Optional[str] = None
  440. ) -> bool:
  441. """Whether a per-group sender allowlist (WeCom ``groups.<id>.allow_from``) gated this message:
  442. a group may be open at the chat level while restricting senders, so reaching the gateway
  443. means the adapter already checked that list."""
  444. if not platform or not chat_id:
  445. return False
  446. groups = self._adapter_setting(platform, "_groups", "groups", profile)
  447. if not isinstance(groups, dict):
  448. return False
  449. chat_id_str = str(chat_id)
  450. group_cfg = groups.get(chat_id_str)
  451. if not isinstance(group_cfg, dict):
  452. lowered = chat_id_str.lower()
  453. group_cfg = next(
  454. (v for k, v in groups.items() if isinstance(k, str) and k.lower() == lowered and isinstance(v, dict)),
  455. groups.get("*"),
  456. )
  457. if not isinstance(group_cfg, dict):
  458. return False
  459. sender_allow = group_cfg.get("allow_from") or group_cfg.get("allowFrom")
  460. if isinstance(sender_allow, str):
  461. return bool(sender_allow.strip())
  462. return isinstance(sender_allow, (list, tuple, set)) and any(str(item).strip() for item in sender_allow)
  463. def _pairing_store_for(self, source: SessionSource):
  464. """Per-profile PairingStore for a source, else the global ``self.pairing_store``."""
  465. per_profile = getattr(self, "pairing_stores", None) or {}
  466. profile = getattr(source, "profile", None)
  467. return per_profile[profile] if profile and profile in per_profile else getattr(self, "pairing_store", None)
  468. def _adapter_extra_for_source(self, source) -> dict:
  469. return _adapter_config_extra(self._delivery_adapter_for(source))
  470. def _own_policy_authorizes(self, source, user_id, is_group, adapter_profile) -> Optional[bool]:
  471. """Own-policy adapter verdict when no env allowlist exists; None = no verdict.
  472. Trusted only when the effective policy for THIS chat type is ``allowlist``: ``open`` forwards
  473. EVERY sender (the fail-open SECURITY.md §2.6 forbids), ``disabled`` never forwards, ``pairing``
  474. forwards unpaired DMs for the handshake (already denied by the pairing-store check).
  475. Anything else → default-deny.
  476. """
  477. if is_group and self._adapter_group_has_sender_allowlist(source.platform, source.chat_id, profile=adapter_profile):
  478. return True
  479. if self._adapter_policy(source.platform, "group" if is_group else "dm", adapter_profile) != "allowlist":
  480. return None
  481. # Re-check DMs via the live adapter's ``_is_dm_allowed`` when present: pairing revoke can clear
  482. # WHATSAPP_ALLOWED_USERS while a construction-time snapshot would keep authorizing until
  483. # restart. Others keep the historical rubber-stamp.
  484. if not is_group:
  485. adapter = self._authorization_adapter(source.platform, profile=adapter_profile)
  486. dm_check = getattr(adapter, "_is_dm_allowed", None) if adapter is not None else None
  487. if callable(dm_check):
  488. return bool(dm_check(user_id))
  489. return True
  490. def _adapter_extra_allowlist_authorizes(self, source, user_id, is_group) -> bool:
  491. """Adapters (e.g. Telegram) that gate via config.extra.allow_from / group_allow_from
  492. without setting enforces_own_access_policy."""
  493. adapter = self._delivery_adapter_for(source)
  494. if adapter is None:
  495. return False
  496. extra = _adapter_config_extra(adapter)
  497. # ``group_allow_from`` is a separate group list (Telegram); an adapter with a single user
  498. # allowlist (Discord) declares ``allow_from_covers_groups`` so its groups read ``allow_from``.
  499. groups_use_allow_from = getattr(adapter, "allow_from_covers_groups", False) is True
  500. group_key = "allow_from" if groups_use_allow_from else "group_allow_from"
  501. adapter_allow = extra.get(group_key if is_group else "allow_from")
  502. if not adapter_allow:
  503. # Plugin platforms (Buzz, DingTalk) spell their env allowlist as ``extra.allowed_users``;
  504. # under multiplex only the default profile's list reaches the env (first-writer-wins
  505. # bridge), so read the live adapter's.
  506. entry = _registry_entry(source.platform)
  507. if authz_field(source.platform.value, "allowed_users_env", entry):
  508. # Buzz) carry the same operator-configured allowlist in
  509. # ``PlatformConfig.extra.allowed_users``. An absent/empty entry changes nothing here — the
  510. # default-deny below still applies. See #82871, #98738.
  511. adapter_allow = extra.get("allowed_users")
  512. if not adapter_allow:
  513. return False
  514. allowed = _coerce_allow_set(adapter_allow)
  515. normalize = getattr(adapter, "normalize_user_id", None)
  516. if callable(normalize):
  517. # Ids and entries may spell the same principal differently (Buzz hex vs npub).
  518. allowed = {normalize(entry) or entry for entry in allowed}
  519. return _allows(allowed, user_id)
  520. def _adapter_resolved_allowlist_ids(self, source) -> set[str]:
  521. """IDs an adapter resolved from username-shaped allowlist entries at connect time (Discord).
  522. The per-turn .env hot-reload restores RAW usernames, so from the second turn on the env
  523. allowlist holds usernames while user_id is numeric. Never a widening: the empty-allowlist
  524. branch already returned and adapters only resolve operator-written entries. Only called with
  525. a non-empty platform allowlist so group/global-only configs never consult adapter memory;
  526. type-checked so mocks cannot auto-truthy in.
  527. """
  528. adapter = resolved_ids = None
  529. with contextlib.suppress(Exception):
  530. adapter = self._delivery_adapter_for(source)
  531. resolver = getattr(adapter, "resolved_allowlist_user_ids", None)
  532. if callable(resolver):
  533. with contextlib.suppress(Exception):
  534. resolved_ids = resolver()
  535. if not isinstance(resolved_ids, (set, frozenset, list, tuple)):
  536. return set()
  537. return {s for e in resolved_ids if isinstance(e, (str, int)) and (s := str(e).strip())}
  538. def _chat_scoped_grant(self, source, adapter_profile, is_group: bool, allow_adapter_delegation: bool) -> bool:
  539. """Grants that need no ``user_id`` (checked before the no-user-id guard)."""
  540. # Trusted-upstream delegation (relay): the connector authenticates this gateway's WS and
  541. # resolves owner bindings BEFORE delivering, so there is no local RELAY_ALLOWED_USERS. Not a
  542. # fail-open: fires only for events actually delivered over the relay WS
  543. # (``delivered_via_upstream_relay``) or whose adapter declares ``authorization_is_upstream``.
  544. # The delivery marker is PRIMARY because a relayed message carries the UNDERLYING platform,
  545. # not ``Platform.RELAY``. ``is True``: a MagicMock stand-in must not auto-truthy into authz.
  546. if allow_adapter_delegation and (
  547. source.delivered_via_upstream_relay is True
  548. or self._adapter_flag(source.platform, "authorization_is_upstream", adapter_profile)
  549. ):
  550. return True
  551. # Chat-scoped group allowlists must work with ``user_id is None`` (anonymous admins,
  552. # sender_chat posts, channel broadcasts).
  553. if is_group and source.chat_id:
  554. chat_allowlist_env = _group_chat_env(source.platform)
  555. if chat_allowlist_env and _allows(_coerce_allow_set(_auth_env(chat_allowlist_env)), source.chat_id):
  556. return True
  557. # config.yaml fallback (``extra.group_allowed_chats``): Telegram observe-unmentioned mode
  558. # strips user_id, so the env-only check above misses it.
  559. with contextlib.suppress(Exception):
  560. adapter_group_allowed = self._adapter_extra_for_source(source).get("group_allowed_chats")
  561. if adapter_group_allowed and _allows(_coerce_allow_set(adapter_group_allowed), source.chat_id):
  562. return True
  563. # Bots admitted by the platform's ``allow_bots_env`` (scoped env → the routed adapter's YAML
  564. # ``allow_bots`` → none) bypass the human allowlist (#4466). Checked here, before the no-user-id
  565. # guard: Slack Workflow Builder posts arrive as subtype=bot_message with user=None. The YAML rung
  566. # is what a secondary profile has: its config is never bridged into the process env. No entry
  567. # (plugin not loaded) = no bypass: fails closed.
  568. if getattr(source, "is_bot", False):
  569. # Idempotent: the env name lives on the plugin's entry, so a runner that never ran the
  570. # config passes (which discover) must still see it rather than silently deny.
  571. with contextlib.suppress(Exception):
  572. from hermes_cli.plugins import discover_plugins
  573. discover_plugins()
  574. allow_bots_var = authz_field(source.platform.value, "allow_bots_env", _registry_entry(source.platform)) or ""
  575. if allow_bots_var:
  576. extra = {}
  577. with contextlib.suppress(Exception):
  578. extra = self._adapter_extra_for_source(source)
  579. mode = str(_extra_or_secret(extra, "allow_bots", allow_bots_var, "none")).lower().strip()
  580. if mode in {"mentions", "all"}:
  581. return True
  582. return False
  583. def _legacy_telegram_chat_grant(self, source, group_user_allowlist: str) -> bool:
  584. """TELEGRAM_GROUP_ALLOWED_USERS was once (mis)used as a chat-ID allowlist; "-"-prefixed
  585. values are chat IDs, honor them and warn once."""
  586. from gateway.run import logger
  587. legacy_chat_ids = {v.strip() for v in group_user_allowlist.split(",") if v.strip().startswith("-")}
  588. if not legacy_chat_ids:
  589. return False
  590. if not getattr(self, "_warned_telegram_group_users_legacy", False):
  591. logger.warning(
  592. "TELEGRAM_GROUP_ALLOWED_USERS contains chat-ID-shaped values "
  593. "(%s). Treating them as chat IDs for backward compatibility. "
  594. "Move chat IDs to TELEGRAM_GROUP_ALLOWED_CHATS — the _USERS var "
  595. "is now for sender user IDs.",
  596. ",".join(sorted(legacy_chat_ids)),
  597. )
  598. self._warned_telegram_group_users_legacy = True
  599. return source.chat_id in legacy_chat_ids
  600. def _bot_loop_guard_instance(self) -> BotLoopGuard:
  601. guard = getattr(self, "_bot_loop_guard", None)
  602. if guard is None:
  603. with _BOT_LOOP_GUARD_INIT_LOCK:
  604. guard = getattr(self, "_bot_loop_guard", None)
  605. if guard is None:
  606. guard = self._bot_loop_guard = BotLoopGuard()
  607. return guard
  608. def _bot_loop_guard_conversation(self, source: SessionSource) -> tuple:
  609. # One budget per conversation, not per sender pair: a per-pair key would hand N bots N budgets.
  610. platform = source.platform.value if source.platform else ""
  611. return (self._adapter_profile_for_source(source) or "", platform, str(source.chat_id or ""))
  612. def _admit_bot_message(self, source: SessionSource) -> bool:
  613. """Count one authorized bot-authored inbound message. False when it trips the budget or the chat is cooling down.
  614. The inbound handler calls this once per message; ``_is_user_authorized`` only peeks because it is asked several times."""
  615. if not getattr(source, "is_bot", False):
  616. return True
  617. allowed, state = self._bot_loop_guard_instance().admit(self._bot_loop_guard_conversation(source))
  618. if state == "tripped":
  619. logger.warning(
  620. "Bot loop guard is dropping bot messages in %s chat %s: bot %s sent one message too many "
  621. "for the window, cooling down (gateway.bot_loop_guard in config.yaml).",
  622. source.platform.value if source.platform else "", source.chat_id, source.user_id,
  623. )
  624. return allowed
  625. def _admit_bot_chain(self, event) -> bool:
  626. """The chain rules for one admitted inbound message (``BotLoopGuard.chain_admit``), read under the
  627. transport profile like the budget. A human message resets its conversation's chain; a bot message
  628. past ``max_hops``, a repeat of the same ask, or a bot answering the reply this bot just gave it
  629. starts no turn (#137027)."""
  630. from gateway.session_ingress import executing_admission
  631. source = event.source
  632. is_bot = bool(getattr(source, "is_bot", False))
  633. # A committed admission re-enters the handler to execute; ingress already judged that message.
  634. if executing_admission.get() or getattr(event, "internal", False) or (
  635. not is_bot and not self._bot_loop_guard_instance().tracking_chains):
  636. return True
  637. allowed, state = self._under_authorization_profile(source, lambda: self._bot_loop_guard_instance().chain_admit(
  638. self._bot_loop_guard_conversation(source), str(source.user_id or ""), str(event.text or ""), is_bot=is_bot))
  639. if not allowed:
  640. logger.info("Bot loop guard ended a bot exchange in %s chat %s (%s from %s; gateway.bot_loop_guard).",
  641. source.platform.value if source.platform else "", source.chat_id, state, source.user_id)
  642. return allowed
  643. def _note_bot_reply(self, source) -> None:
  644. """This turn's reply to a bot peer went out: its next message answers an answer."""
  645. if getattr(source, "is_bot", False):
  646. self._under_authorization_profile(source, lambda: self._bot_loop_guard_instance().note_reply(
  647. self._bot_loop_guard_conversation(source), str(source.user_id or "")))
  648. def _is_user_authorized(self, source: SessionSource, *, allow_adapter_delegation: bool = True) -> bool:
  649. """Whether a user may use the bot.
  650. Order: trusted-upstream delegation, chat-scoped group allowlists, ``{PLATFORM}_ALLOW_BOTS``,
  651. per-platform allow-all, adapter role auth, pairing store, env/config allowlists,
  652. ``GATEWAY_ALLOW_ALL_USERS``, default deny. A bot-authored message that any of these admits
  653. is still refused while its chat's loop guard is cooling down.
  654. """
  655. if not self._principal_authorized(source, allow_adapter_delegation=allow_adapter_delegation):
  656. return False
  657. if not getattr(source, "is_bot", False):
  658. return True
  659. # The guard judges the final verdict: a chat allowlist admits a bot before the ALLOW_BOTS block runs.
  660. return not self._bot_loop_guard_instance().blocked(self._bot_loop_guard_conversation(source))
  661. def _principal_authorized(self, source: SessionSource, *, allow_adapter_delegation: bool) -> bool:
  662. """The allowlist verdict alone, before the bot loop guard."""
  663. from gateway.session_local import authorize_local_source
  664. local_verdict = authorize_local_source(self, source)
  665. if local_verdict is not None:
  666. return local_verdict
  667. # Webhook events are HMAC-verified; a ``trusted_inbound`` platform's events come from the
  668. # service its adapter authenticated to (no human sender to allowlist).
  669. if source.platform == Platform.WEBHOOK or getattr(_registry_entry(source.platform), "trusted_inbound", False) is True:
  670. return True
  671. adapter_profile = self._adapter_profile_for_source(source)
  672. is_group = source.chat_type in _GROUP_CHAT_TYPES
  673. is_group_or_forum = source.chat_type in _GROUP_FORUM_TYPES
  674. if self._chat_scoped_grant(source, adapter_profile, is_group, allow_adapter_delegation):
  675. return True
  676. user_id = source.user_id
  677. if not user_id:
  678. return False
  679. entry = _registry_entry(source.platform)
  680. platform_allow_env = authz_field(source.platform.value, "allowed_users_env", entry) or ""
  681. platform_allow_all_var = authz_field(source.platform.value, "allow_all_env", entry) or ""
  682. if platform_allow_all_var and _env_truthy(platform_allow_all_var):
  683. return True
  684. # Adapter-verified role auth (Discord DISCORD_ALLOWED_ROLES). ``is True``: no MagicMock pass.
  685. if allow_adapter_delegation and getattr(source, "role_authorized", False) is True:
  686. return True
  687. # Pairing store: a first-class grant created only by an operator approving a code. Honored as
  688. # a UNION with the allowlist (approval also mirrors into it).
  689. pairing_store = self._pairing_store_for(source)
  690. if pairing_store is not None and pairing_store.is_approved(source.platform.value if source.platform else "", user_id):
  691. return True
  692. platform_allowlist = _auth_env(platform_allow_env)
  693. group_user_allowlist = _auth_env(_GROUP_USER_ENV.get(source.platform, "")) if is_group_or_forum else ""
  694. group_chat_allowlist = _auth_env(_group_chat_env(source.platform, entry)) if is_group_or_forum else ""
  695. global_allowlist = _auth_env("GATEWAY_ALLOWED_USERS")
  696. if not (platform_allowlist or group_user_allowlist or group_chat_allowlist or global_allowlist):
  697. # No env allowlist: own-policy adapters gate at intake (see _own_policy_authorizes).
  698. if allow_adapter_delegation and self._adapter_flag(source.platform, "enforces_own_access_policy", adapter_profile):
  699. verdict = self._own_policy_authorizes(source, user_id, is_group, adapter_profile)
  700. if verdict is not None:
  701. return verdict
  702. if self._adapter_extra_allowlist_authorizes(source, user_id, is_group):
  703. return True
  704. return _env_truthy("GATEWAY_ALLOW_ALL_USERS")
  705. if is_group_or_forum and source.chat_id:
  706. # Telegram group traffic authorized by chat ID (TELEGRAM_GROUP_ALLOWED_USERS gates the sender).
  707. if group_chat_allowlist and _allows(_coerce_allow_set(group_chat_allowlist), source.chat_id):
  708. return True
  709. if (
  710. source.platform == Platform.TELEGRAM and group_user_allowlist
  711. and self._legacy_telegram_chat_grant(source, group_user_allowlist)
  712. ):
  713. return True
  714. # TELEGRAM_GROUP_ALLOWED_USERS is group-scoped (no DM access); TELEGRAM_ALLOWED_USERS is platform-wide.
  715. allowed_ids = (
  716. _coerce_allow_set(platform_allowlist)
  717. | _coerce_allow_set(group_user_allowlist)
  718. | _coerce_allow_set(global_allowlist)
  719. )
  720. if platform_allowlist:
  721. allowed_ids |= self._adapter_resolved_allowlist_ids(source)
  722. return "*" in allowed_ids or _principal_matches_allowlist(source, user_id, allowed_ids)
  723. def _get_unauthorized_dm_behavior(self, platform: Optional[Platform], *, profile: Optional[str] = None) -> str:
  724. """How unauthorized DMs are handled ("pair" / "ignore" / "decline") for a platform.
  725. Order: explicit per-platform config; Email → "ignore" (inboxes hold arbitrary mail); explicit
  726. non-default global; adapter dm_policy (pairing → "pair", allowlist/disabled → "ignore"); any
  727. configured allowlist → "ignore" (spamming unknown contacts with codes is noisy and leaks); else "pair".
  728. 1. 2. Email defaults to ``"ignore"`` unless explicitly opted into pairing. 3. Explicit global
  729. ``unauthorized_dm_behavior`` in config — wins for chat-shaped platforms when no per-platform
  730. override is set. 4. When an adapter-level DM policy opts into pairing or silent drop, honor it. 5.
  731. When an allowlist (``PLATFORM_ALLOWED_USERS``, ``PLATFORM_GROUP_ALLOWED_USERS`` /
  732. ``PLATFORM_GROUP_ALLOWED_CHATS``, or ``GATEWAY_ALLOWED_USERS``) is configured, default to
  733. ``"ignore"`` — the allowlist signals that the owner has deliberately restricted access; spamming
  734. unknown contacts with pairing codes is both noisy and a potential info-leak. (#9337) 6.
  735. """
  736. config = getattr(self, "config", None)
  737. if (
  738. config and hasattr(config, "get_unauthorized_dm_behavior") and platform
  739. and "unauthorized_dm_behavior" in self._config_extra(platform)
  740. ):
  741. return config.get_unauthorized_dm_behavior(platform)
  742. if platform == Platform.EMAIL:
  743. return "ignore"
  744. if config and hasattr(config, "unauthorized_dm_behavior") and config.unauthorized_dm_behavior != "pair":
  745. return config.unauthorized_dm_behavior
  746. allowlist_keys = ["GATEWAY_ALLOWED_USERS"]
  747. if platform:
  748. dm_policy = self._adapter_policy(platform, "dm", profile)
  749. if not dm_policy:
  750. dm_policy = str(self._config_extra(platform).get("dm_policy") or "").strip().lower()
  751. if dm_policy == "pairing":
  752. return "pair"
  753. if dm_policy in {"allowlist", "disabled"}:
  754. return "ignore"
  755. entry = _registry_entry(platform)
  756. # A group allowlist alone must not silence DM pairing: only platforms that opt in.
  757. if authz_field(platform.value, "allowlist_suppresses_pairing", entry):
  758. allowlist_keys = [authz_field(platform.value, "allowed_users_env", entry) or "",
  759. _GROUP_USER_ENV.get(platform), _group_chat_env(platform, entry), *allowlist_keys]
  760. if any(key and _auth_env(key).strip() for key in allowlist_keys):
  761. return "ignore"
  762. return "pair"