messaging.py 64 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280
  1. """Messaging dashboard routes: WhatsApp/Telegram onboarding and per-platform enable/config/test.
  2. Extracted from ``hermes_cli.web_server``; helpers/state that tests monkeypatch on
  3. ``web_server`` stay there and are resolved late at call time (cycle-safe).
  4. """
  5. import asyncio
  6. import contextlib
  7. import json
  8. import logging
  9. import os
  10. import re
  11. import secrets
  12. import subprocess
  13. import threading
  14. import time
  15. import urllib.parse
  16. from datetime import datetime, timezone, UTC
  17. from pathlib import Path
  18. from collections.abc import Collection
  19. from typing import Any, Optional
  20. from fastapi import APIRouter, HTTPException
  21. from gateway.status import resolve_gateway_liveness, retained_gateway_state
  22. from hermes_cli._subprocess_compat import windows_hide_flags
  23. from hermes_cli.config import OPTIONAL_ENV_VARS, get_env_path
  24. from hermes_cli.process_identity import release_process_group_once_empty, spawn_owned
  25. from hermes_constants import get_process_hermes_home
  26. from hermes_cli.web_deps import LateState, late
  27. from hermes_cli.web_server_gateway import _restart_gateway_after
  28. from hermes_cli.web_whatsapp_session import _backup_whatsapp_session
  29. from hermes_cli.web_server_messaging import (
  30. _TelegramOnboardingPairing, _WhatsAppOnboardingSession, _messaging_platform_catalog, _telegram_onboarding_error_message, _telegram_onboarding_lock, _telegram_onboarding_pairings, _whatsapp_onboarding_payload, _whatsapp_onboarding_sessions,
  31. )
  32. from hermes_cli.web_routers._common import (
  33. REDACTED_CREDENTIAL_WRITE_DETAIL, http_failure, is_redacted_credential_preview,
  34. redacted_credential_preview,
  35. )
  36. from hermes_cli.web_models import (
  37. MessagingPlatformUpdate, TelegramOnboardingApply, TelegramOnboardingStart,
  38. WhatsAppOnboardingApply, WhatsAppOnboardingStart,
  39. )
  40. _log = logging.getLogger("hermes_cli.web_server")
  41. router = APIRouter()
  42. # Late-bound so a test's monkeypatch on the owning module wins at call time.
  43. _config_profile_scope = late("_config_profile_scope", "hermes_cli.web_server_profiles")
  44. _profile_scope = late("_profile_scope", "hermes_cli.web_server_profiles")
  45. _resolve_profile_dir = late("_resolve_profile_dir", "hermes_cli.web_server_profiles")
  46. _restart_gateway_after_whatsapp_onboarding = late("_restart_gateway_after_whatsapp_onboarding", "hermes_cli.web_server_messaging")
  47. _telegram_onboarding_request_sync = late("_telegram_onboarding_request_sync", "hermes_cli.web_server_messaging")
  48. _whatsapp_session_path = late("_whatsapp_session_path", "hermes_cli.web_server_messaging")
  49. _write_platform_enabled = late("_write_platform_enabled", "hermes_cli.web_server_messaging")
  50. load_env = late("load_env", "hermes_cli.config")
  51. get_secret_source_values = late("get_secret_source_values", "hermes_cli.env_loader")
  52. builtin_platform_status = late("builtin_platform_status", "gateway.config_env")
  53. load_config = late("load_config", "hermes_cli.config")
  54. read_runtime_status = late("read_runtime_status", "gateway.status")
  55. remove_env_value = late("remove_env_value", "hermes_cli.config")
  56. save_env_value = late("save_env_value", "hermes_cli.config")
  57. _gateway_subcommand = late("_gateway_subcommand", "hermes_cli.web_server_gateway")
  58. _probe_gateway_health = late("_probe_gateway_health", "hermes_cli.web_server_gateway")
  59. get_running_pid_cached = late("get_running_pid_cached", "gateway.status")
  60. get_runtime_status_running_pid = late("get_runtime_status_running_pid", "gateway.status")
  61. served_profile_runtime = late("served_profile_runtime", "gateway.status_served")
  62. _GATEWAY_HEALTH_URL = LateState("_GATEWAY_HEALTH_URL")
  63. # Display labels for env vars not in OPTIONAL_ENV_VARS (bridge toggles, Twilio, Email, ...)
  64. # so the UI can still render a friendly label. Rows: (key, description, prompt, extra flags).
  65. _MESSAGING_ENV_FALLBACKS: dict[str, dict[str, Any]] = {
  66. key: {"description": description, "prompt": prompt, **extra}
  67. for key, description, prompt, extra in (
  68. ("SIGNAL_HTTP_URL", "signal-cli REST API base URL, e.g. http://127.0.0.1:8080", "Signal bridge URL", {"url": "https://github.com/bbernhard/signal-cli-rest-api"}),
  69. ("SIGNAL_ACCOUNT", "Signal account phone number registered with the bridge", "Signal account", {}),
  70. ("SIGNAL_ALLOWED_USERS", "Comma-separated Signal users allowed to use the bot", "Allowed Signal users", {}),
  71. ("WHATSAPP_ENABLED", "Enable the WhatsApp gateway adapter", "Enable WhatsApp", {"advanced": True}),
  72. ("WHATSAPP_MODE", "WhatsApp bridge mode", "WhatsApp mode", {"advanced": True}),
  73. ("WHATSAPP_DM_POLICY", "How WhatsApp direct messages are authorized", "WhatsApp DM policy", {"advanced": True}),
  74. ("WHATSAPP_ALLOWED_USERS", "Comma-separated WhatsApp users allowed to use the bot", "Allowed WhatsApp users", {}),
  75. ("EMAIL_ADDRESS", "Email address to send and receive from", "Email address", {}),
  76. ("EMAIL_PASSWORD", "Email account password or app password", "Email password", {"password": True}),
  77. ("EMAIL_IMAP_HOST", "IMAP server host (e.g. imap.gmail.com)", "IMAP host", {}),
  78. ("EMAIL_SMTP_HOST", "SMTP server host (e.g. smtp.gmail.com)", "SMTP host", {}),
  79. ("TWILIO_ACCOUNT_SID", "Twilio Account SID", "Twilio Account SID", {"url": "https://www.twilio.com/console"}),
  80. ("TWILIO_AUTH_TOKEN", "Twilio Auth Token", "Twilio Auth Token", {"password": True}),
  81. ("WECOM_BOT_ID", "WeCom group bot ID", "WeCom Bot ID", {}),
  82. ("WECOM_SECRET", "WeCom group bot secret", "WeCom Secret", {"password": True}),
  83. ("WECOM_CALLBACK_CORP_ID", "WeCom corp ID", "WeCom Corp ID", {}),
  84. ("WECOM_CALLBACK_CORP_SECRET", "WeCom app corp secret", "WeCom Corp Secret", {"password": True}),
  85. ("WECOM_CALLBACK_AGENT_ID", "WeCom app agent ID", "WeCom Agent ID", {}),
  86. ("WECOM_CALLBACK_TOKEN", "WeCom callback verification token", "WeCom Token", {}),
  87. ("WECOM_CALLBACK_ENCODING_AES_KEY", "WeCom callback AES encoding key", "WeCom AES Key", {"password": True}),
  88. ("WEIXIN_ACCOUNT_ID", "iLink Bot account ID obtained through QR login in hermes gateway setup", "iLink Bot account ID", {}),
  89. ("WEIXIN_TOKEN", "iLink Bot token obtained through QR login in hermes gateway setup", "iLink Bot token", {"password": True}),
  90. ("WEIXIN_BASE_URL", "iLink API base URL saved by QR login (default: https://ilinkai.weixin.qq.com)", "iLink API base URL", {}),
  91. ("FEISHU_APP_ID", "Feishu / Lark app ID", "App ID", {}),
  92. ("FEISHU_APP_SECRET", "Feishu / Lark app secret", "App secret", {"password": True}),
  93. ("FEISHU_ENCRYPT_KEY", "Feishu / Lark encrypt key", "Encrypt key", {"password": True}),
  94. ("FEISHU_VERIFICATION_TOKEN", "Feishu / Lark verification token", "Verification token", {"password": True}),
  95. ("DINGTALK_CLIENT_ID", "DingTalk client ID (App key)", "Client ID", {}),
  96. ("DINGTALK_CLIENT_SECRET", "DingTalk client secret (App secret)", "Client secret", {"password": True}),
  97. )
  98. }
  99. def _env_value_rules(platform_id: str) -> dict[str, tuple[Any, str]]:
  100. """``{env key: (accepts(value), 400 detail)}`` declared on the platform plugin's PlatformEntry
  101. (``env_value_rules``; e.g. Telegram/Slack reject credentials clearly in the wrong field).
  102. Resolve this in the target profile's scope, right after :func:`_require_platform`: the catalog build
  103. there has just materialized that profile's plugin entries, so the lookup imports nothing, whereas in
  104. a scope whose catalog was never built the registry's overlay may not hold the entry and every rule
  105. would silently stop applying. Without rules on the entry (the dashboard's own profile disabled the
  106. plugin, a user plugin overrides it) a bundled platform's ``dashboard_card.py`` answers, read from
  107. its file: the rules guard the edited profile's values whatever the dashboard's profile loads."""
  108. from gateway.platform_env import bundled_sibling
  109. from gateway.platform_registry import platform_registry
  110. entry = platform_registry.get(platform_id)
  111. if entry is not None and entry.env_value_rules:
  112. return dict(entry.env_value_rules)
  113. card = getattr(bundled_sibling(platform_id, "dashboard_card"), "DASHBOARD_CARD", None) or {}
  114. return dict(card.get("env_value_rules") or {})
  115. def _validate_messaging_env_value(rules: dict[str, tuple[Any, str]], key: str, value: str) -> None:
  116. rule = rules.get(key)
  117. if value and rule and not rule[0](value):
  118. raise HTTPException(status_code=400, detail=rule[1])
  119. # Allowlists (``*_ALLOWED_USERS``, ``LINE_ALLOWED_GROUPS``, ``SIMPLEX_GROUP_ALLOWED``) are
  120. # comma-separated IDs, not secrets: clients render them as one editable entry per ID, which
  121. # needs the saved value instead of a redacted preview.
  122. _ALLOWLIST_KEY_RE = re.compile(r"_ALLOWED(?:_[A-Z]+)?$")
  123. def _messaging_env_info(key: str) -> dict[str, Any]:
  124. info = OPTIONAL_ENV_VARS.get(key) or _MESSAGING_ENV_FALLBACKS.get(key) or {}
  125. is_password = bool(info.get("password", False))
  126. return {
  127. "description": info.get("description", ""),
  128. "prompt": info.get("prompt", key),
  129. "help": info.get("help", ""),
  130. "url": info.get("url"),
  131. "is_password": is_password,
  132. "is_list": not is_password and bool(_ALLOWLIST_KEY_RE.search(key)),
  133. "advanced": info.get("advanced", False),
  134. }
  135. def _catalog_lookup(platform_id: str) -> dict[str, Any] | None:
  136. return next((e for e in _messaging_platform_catalog() if e["id"] == platform_id), None)
  137. def _require_platform(platform_id: str) -> dict[str, Any]:
  138. entry = _catalog_lookup(platform_id)
  139. if not entry:
  140. raise HTTPException(status_code=404, detail=f"Unknown messaging platform: {platform_id}")
  141. return entry
  142. def _platform_enablement(
  143. platform_id: str, entry: dict[str, Any], env_on_disk: dict[str, str], scoped: bool,
  144. source_keys: Collection[str] = (),
  145. ) -> tuple[bool, bool, dict | None]:
  146. """(enabled, configured, home_channel). Profile-scoped: the profile's config.yaml, .env and
  147. enabled secret sources only, never ``load_gateway_config()`` (see ``builtin_platform_status``)."""
  148. required = entry["required_env"]
  149. if scoped:
  150. # ``source_keys``: names the profile's enabled secret sources resolved (1Password, Bitwarden, a plugin).
  151. configured = bool(required) and all(env_on_disk.get(key) or key in source_keys for key in required)
  152. try:
  153. config = load_config()
  154. plat_cfg = (config.get("platforms") or {}).get(platform_id)
  155. plat_cfg = plat_cfg if isinstance(plat_cfg, dict) else {}
  156. hc = plat_cfg.get("home_channel")
  157. status = None if required else builtin_platform_status(platform_id, config)
  158. if status is not None:
  159. enabled, configured = status # token-free built-in: nothing to judge but the gateway's verdict
  160. else:
  161. # Setup writes credentials without a platforms entry; explicit disable wins.
  162. raw_enabled = plat_cfg.get("enabled")
  163. enabled = False if raw_enabled is False else bool(raw_enabled) or configured
  164. home_channel = hc if isinstance(hc, dict) else None
  165. except Exception: # health: allow BLE001 -- one platform's bad config must not blank the page
  166. _log.debug("Profile-scoped status for %s failed", platform_id, exc_info=True)
  167. enabled, home_channel = False, None
  168. return enabled, configured, home_channel
  169. try:
  170. from gateway.config import Platform, load_gateway_config
  171. gateway_config = load_gateway_config()
  172. platform = Platform(platform_id)
  173. platform_config = gateway_config.platforms.get(platform)
  174. enabled = bool(platform_config and platform_config.enabled)
  175. configured = bool(platform_config and gateway_config._is_platform_connected(platform, platform_config))
  176. home_channel = platform_config.home_channel.to_dict() if platform_config and platform_config.home_channel else None
  177. except Exception:
  178. enabled, home_channel = False, None
  179. configured = all(env_on_disk.get(key) or os.getenv(key, "") for key in required)
  180. return enabled, configured, home_channel
  181. def _relay_disabled_platform_ids(scoped: bool) -> frozenset[str]:
  182. """Platforms the GATEWAY_RELAY_URL relay-exclusive rule switches off at gateway load
  183. (#141175), read from the same load_gateway_config() the unscoped enablement arm uses, so the
  184. page can say "Team Gateway" instead of a bare "Disabled" that reverts every restart.
  185. Unscoped arm only: profile-scoped status is judged per profile (``_platform_enablement``)."""
  186. if scoped:
  187. return frozenset()
  188. try:
  189. from gateway.config import load_gateway_config
  190. platforms = load_gateway_config().platforms
  191. return frozenset(p.value for p, cfg in platforms.items() if cfg.disabled_by_relay)
  192. except Exception: # health: allow BLE001 -- advisory label; an unreadable config keeps the plain state
  193. _log.debug("relay-disabled platform lookup failed", exc_info=True)
  194. return frozenset()
  195. def _messaging_platform_payload(
  196. entry: dict[str, Any], env_on_disk: dict[str, str], runtime: dict | None,
  197. scoped: bool = False, profile_home: Optional[Path] = None, source_keys: Collection[str] = (),
  198. relay_disabled: frozenset[str] = frozenset(), relay_view: tuple[frozenset[str], bool] = (frozenset(), False),
  199. ) -> dict[str, Any]:
  200. platform_id = entry["id"]
  201. rt = runtime if isinstance(runtime, dict) else {}
  202. runtime_platforms = rt.get("platforms")
  203. runtime_platform = runtime_platforms.get(platform_id, {}) if isinstance(runtime_platforms, dict) else {}
  204. if not isinstance(runtime_platform, dict):
  205. runtime_platform = {}
  206. # Same shared liveness ladder /api/status uses, so the sidebar strip and the
  207. # Channels page can never disagree on one page load. profile_home is passed when
  208. # scoped to a named profile: gateway/status readers resolve process-level paths
  209. # and do NOT follow the HERMES_HOME contextvar override, so without it messaging
  210. # silently reports another profile's gateway.
  211. gateway_running = resolve_gateway_liveness(
  212. profile_dir=profile_home, runtime=runtime,
  213. health_probe=_probe_gateway_health if _GATEWAY_HEALTH_URL else None,
  214. pid_probe=get_running_pid_cached, runtime_reader=read_runtime_status,
  215. runtime_pid_probe=get_runtime_status_running_pid,
  216. ).running
  217. if not gateway_running:
  218. # gateway_state.json outlives its writer and keeps per-platform entries across
  219. # restarts, so a stopped gateway that once ran WITHOUT credentials still says
  220. # "fatal / No bot token configured" after the user saved a token. Only a live
  221. # process's verdict describes the current config; a dead one's is history.
  222. runtime_platform = {}
  223. def env_value(key: str) -> str:
  224. # Profile-scoped: judge only the profile's own .env — the dashboard process's
  225. # os.environ carries the ROOT install's .env and would report root credentials as the profile's.
  226. return env_on_disk.get(key) or ("" if scoped else os.getenv(key, ""))
  227. env_vars = []
  228. for key in entry["env_vars"]:
  229. value, info = env_value(key), _messaging_env_info(key)
  230. env_vars.append({
  231. "key": key, "required": key in entry["required_env"], "is_set": bool(value) or key in source_keys,
  232. "redacted_value": redacted_credential_preview(value),
  233. "value": value if info["is_list"] else None, **info,
  234. })
  235. enabled, configured, home_channel = _platform_enablement(platform_id, entry, env_on_disk, scoped, source_keys)
  236. if gateway_running and runtime_platform.get("mirrored_from"):
  237. # Served secondary: the default's shared listener already answers this platform at
  238. # /p/<profile>/... (enabling it locally 409s), so the secondary's own empty config
  239. # must not project Disabled over the live mirror (#121125).
  240. enabled, configured = True, True
  241. state = runtime_platform.get("state")
  242. if not enabled:
  243. state = "disabled"
  244. elif not configured:
  245. state = "not_configured"
  246. elif gateway_running and not state:
  247. state = "pending_restart"
  248. elif not gateway_running and not state:
  249. # Same verdict /api/status gives: ``hermes gateway stop`` keeps the last failure on disk,
  250. # and a profile the operator stopped must not wear a "Start failed" badge for it.
  251. state = "startup_failed" if retained_gateway_state(rt) == "startup_failed" else "gateway_stopped"
  252. error_code = runtime_platform.get("error_code")
  253. error_message = runtime_platform.get("error_message")
  254. if state == "startup_failed":
  255. error_code = error_code or "startup_failed"
  256. error_message = error_message or rt.get("exit_reason")
  257. payload = {
  258. "id": platform_id, "name": entry["name"], "description": entry["description"],
  259. "docs_url": entry["docs_url"], "enabled": enabled, "configured": configured,
  260. "gateway_running": gateway_running, "state": state, "error_code": error_code,
  261. "error_message": error_message, "updated_at": runtime_platform.get("updated_at"),
  262. "home_channel": home_channel, "env_vars": env_vars,
  263. "disabled_by_relay": not enabled and platform_id in relay_disabled,
  264. # Team Gateway's shared bot carries this platform: setup is linking an account to it, and a
  265. # direct bot is switched off at every start when ``relay_exclusive`` (#141546).
  266. "relay_fronted": platform_id in relay_view[0],
  267. "relay_exclusive": platform_id in relay_view[0] and relay_view[1],
  268. # Multiplex secondary served on the default's shared listener: the vendor callback URL.
  269. "ingress_url": runtime_platform.get("ingress_url") if gateway_running else None,
  270. }
  271. if platform_id == "whatsapp":
  272. whatsapp_mode = env_value("WHATSAPP_MODE").strip()
  273. payload["whatsapp_setup"] = {
  274. "mode": whatsapp_mode if whatsapp_mode in {"bot", "self-chat"} else "",
  275. "allowed_users_set": bool(env_value("WHATSAPP_ALLOWED_USERS").strip()),
  276. "home_channel_set": bool(home_channel),
  277. }
  278. return payload
  279. def _platform_payloads(scoped_dir: Optional[Path], entries) -> list[dict[str, Any]]:
  280. """Payloads for ``entries``; call inside ``_profile_scope`` (load_env honors the
  281. HERMES_HOME contextvar; the gateway status readers do not, hence the explicit path)."""
  282. env_on_disk = load_env()
  283. runtime = read_runtime_status(path=scoped_dir / "gateway_state.json") if scoped_dir is not None else read_runtime_status()
  284. # A profile served by the multiplexer writes no live record of its own; its adapters live in the
  285. # multiplexer's record under ``<profile>:<platform>``. A leftover ``gateway_state.json`` from the
  286. # profile's standalone days outranks nothing: only a record proving a live own gateway does —
  287. # the same rung order ``resolve_gateway_liveness`` uses (own runtime PID before the multiplexer),
  288. # so the two surfaces cannot disagree. Unscoped, the profile is the process's own home (a pooled
  289. # ``hermes --profile X serve``).
  290. own_home = scoped_dir if scoped_dir is not None else get_process_hermes_home()
  291. runtime = served_profile_runtime(own_home, runtime) or runtime
  292. # Credentials a secret manager supplies have no .env line; only values the profile's enabled
  293. # sources resolved (into its secret scope, by ``_profile_scope``) count, and an empty one is unset.
  294. scoped = scoped_dir is not None
  295. source_values = get_secret_source_values(scoped_dir) if scoped else {}
  296. source_keys = frozenset(key for key, value in source_values.items() if str(value).strip())
  297. relay_disabled = _relay_disabled_platform_ids(scoped)
  298. relay_view = _relay_channel_view(own_home)
  299. return [_messaging_platform_payload(entry, env_on_disk, runtime, scoped=scoped, profile_home=scoped_dir,
  300. source_keys=source_keys, relay_disabled=relay_disabled,
  301. relay_view=relay_view)
  302. for entry in entries]
  303. def _relay_channel_view(home: Path) -> tuple[frozenset[str], bool]:
  304. """The relay serves only the gateway's own (launch) profile; other profiles keep direct setup."""
  305. if Path(home).resolve() != Path(get_process_hermes_home()).resolve():
  306. return frozenset(), False
  307. from gateway.relay.link import relay_channel_view
  308. return relay_channel_view()
  309. @contextlib.contextmanager
  310. def _onboarding_save_errors(log_msg: str, detail: str):
  311. """Map onboarding env/config write failures: ValueError -> 400 (its text),
  312. anything else -> logged + fixed 500 ``detail``; HTTPException passes through."""
  313. try:
  314. yield
  315. except HTTPException:
  316. raise
  317. except ValueError as exc:
  318. raise HTTPException(status_code=400, detail=str(exc)) from exc
  319. except Exception as exc:
  320. _log.exception(log_msg)
  321. raise HTTPException(status_code=500, detail=detail) from exc
  322. # ── WhatsApp QR onboarding ─────────────────────────────────────
  323. _WHATSAPP_ONBOARDING_TTL_SECONDS = 600
  324. _WHATSAPP_ONBOARDING_TERMINAL_STATUSES = {"connected", "error", "expired", "cancelled"}
  325. _WHATSAPP_SESSION_NOT_FOUND = "WhatsApp setup session was not found. Start a new setup."
  326. _whatsapp_onboarding_lock = threading.RLock()
  327. def _normalize_whatsapp_onboarding_mode(value: Any) -> str:
  328. mode = str(value or "bot").strip().lower()
  329. if mode not in {"bot", "self-chat"}:
  330. raise HTTPException(status_code=400, detail="WhatsApp mode must be 'bot' or 'self-chat'.")
  331. return mode
  332. def _normalize_whatsapp_allowed_users(value: Any) -> str:
  333. raw = str(value or "").strip()
  334. if not raw:
  335. return ""
  336. return ",".join(part.replace(" ", "") for part in raw.split(",") if part.strip())
  337. def _whatsapp_phone_from_identifier(value: Any) -> str | None:
  338. raw = str(value or "").strip()
  339. if not raw:
  340. return None
  341. digits = re.sub(r"\D+", "", raw.split("@", 1)[0].split(":", 1)[0])
  342. return digits or None
  343. def _first_str(candidate: Any, keys: tuple[str, ...]) -> str | None:
  344. if not isinstance(candidate, dict):
  345. return None
  346. return next((v for v in (str(candidate.get(k) or "").strip() for k in keys) if v), None)
  347. def _whatsapp_linked_account_from_session(session_path: Path) -> tuple[str | None, str | None, str | None]:
  348. try:
  349. payload = json.loads((session_path / "creds.json").read_text(encoding="utf-8-sig"))
  350. except Exception:
  351. return None, None, None
  352. candidates = (payload.get("me"), payload.get("account"), payload)
  353. account_id = next((v for v in (_first_str(c, ("id", "jid", "lid")) for c in candidates) if v), None)
  354. account_name = next((v for v in (_first_str(c, ("name", "verifiedName", "notify", "pushName")) for c in candidates) if v), None)
  355. return account_id, account_name, _whatsapp_phone_from_identifier(account_id)
  356. def _ensure_whatsapp_bridge_dependencies(bridge_dir: Path) -> None:
  357. """Install bridge dependencies when the dashboard is the setup surface."""
  358. if (bridge_dir / "node_modules").exists():
  359. return
  360. from hermes_constants import find_node_executable, with_hermes_node_path
  361. from utils import env_int
  362. import pm
  363. npm = find_node_executable("npm")
  364. try:
  365. env = with_hermes_node_path()
  366. if npm is None:
  367. env = pm.ensure("npm", explicit=True).env
  368. installed = pm.installed_package("npm")
  369. if installed is None or installed.binary is None:
  370. raise pm.InstallError("npm", "npm binary is missing after preparation")
  371. npm = str(installed.binary)
  372. # npm output is UTF-8; encoding= guards the Windows ANSI-code-page
  373. # default against undefined bytes crashing the reader thread.
  374. result = subprocess.run(
  375. [npm, "install", "--silent"], cwd=str(bridge_dir), capture_output=True, text=True,
  376. encoding="utf-8", errors="replace", timeout=env_int("WHATSAPP_NPM_INSTALL_TIMEOUT", 300),
  377. env=env, creationflags=windows_hide_flags(),
  378. check=False,
  379. )
  380. except subprocess.TimeoutExpired as exc:
  381. raise HTTPException(status_code=500, detail="Installing WhatsApp bridge dependencies timed out.") from exc
  382. except (pm.InstallError, OSError) as exc:
  383. raise HTTPException(status_code=500, detail=f"Failed to install WhatsApp bridge dependencies: {exc}") from exc
  384. if result.returncode != 0:
  385. detail = "\n".join((result.stderr or result.stdout or "").strip().splitlines()[-10:])
  386. raise HTTPException(status_code=500, detail=f"npm install failed for WhatsApp bridge: {detail or 'no output'}")
  387. def _spawn_whatsapp_pairing_process(session_path: Path, mode: str) -> subprocess.Popen:
  388. from gateway.platforms.whatsapp_common import resolve_whatsapp_bridge_dir
  389. from hermes_constants import find_node_executable, with_hermes_node_path
  390. bridge_dir = resolve_whatsapp_bridge_dir()
  391. bridge_script = bridge_dir / "bridge.js"
  392. if not bridge_script.exists():
  393. raise HTTPException(status_code=500, detail=f"WhatsApp bridge script was not found at {bridge_script}.")
  394. _ensure_whatsapp_bridge_dependencies(bridge_dir)
  395. node = find_node_executable("node")
  396. if not node:
  397. import pm
  398. try:
  399. pm.ensure("node", explicit=True)
  400. installed = pm.installed_package("node")
  401. if installed is None or installed.binary is None:
  402. raise pm.InstallError("node", "Node.js binary is missing after preparation")
  403. node = str(installed.binary)
  404. except pm.InstallError as exc:
  405. raise HTTPException(status_code=500, detail=f"Node.js preparation failed: {exc}") from exc
  406. session_path.mkdir(parents=True, exist_ok=True)
  407. env = with_hermes_node_path()
  408. env["WHATSAPP_MODE"] = mode
  409. env["WHATSAPP_DM_POLICY"] = "pairing"
  410. # Owned: a SIGKILLed dashboard must not leave a pairing bridge holding the session dir.
  411. return spawn_owned(
  412. [node, str(bridge_script), "--pair-only", "--pair-json", "--session", str(session_path)],
  413. purpose="whatsapp-pairing", cwd=str(bridge_dir), stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
  414. text=True, encoding="utf-8", errors="replace", env=env, creationflags=windows_hide_flags(),
  415. )
  416. def _terminate_whatsapp_pairing(proc: subprocess.Popen | None) -> None:
  417. if proc is None:
  418. return
  419. if proc.poll() is None:
  420. try:
  421. proc.terminate()
  422. proc.wait(timeout=3)
  423. except Exception:
  424. with contextlib.suppress(Exception):
  425. proc.kill()
  426. proc.wait(timeout=3)
  427. if proc.poll() is not None:
  428. # Stopped; one we failed to stop stays covered by the owner-death supervisor. timeout=0:
  429. # callers run on the event loop.
  430. release_process_group_once_empty(proc.pid, proc=proc, timeout=0)
  431. def _fail_whatsapp_pairing(pairing_id: str, error: str, *, proc=None, unless=_WHATSAPP_ONBOARDING_TERMINAL_STATUSES) -> None:
  432. """Mark the session errored unless its status is in ``unless`` (or, when
  433. ``proc`` is given, it has since been superseded by another process)."""
  434. with _whatsapp_onboarding_lock:
  435. record = _whatsapp_onboarding_sessions.get(pairing_id)
  436. if record and (proc is None or record.proc is proc) and record.status not in unless:
  437. record.status = "error"
  438. record.error = error
  439. def _apply_pairing_event(record, payload: dict) -> None:
  440. event = str(payload.get("event") or "").strip()
  441. if event == "qr":
  442. qr = str(payload.get("qr") or "").strip()
  443. if qr:
  444. record.qr_payload = qr
  445. record.status = "waiting"
  446. record.error = None
  447. elif event == "connected":
  448. user = payload.get("user")
  449. if isinstance(user, dict):
  450. account_id = str(user.get("id") or "").strip()
  451. record.account_id = account_id or None
  452. record.account_name = str(user.get("name") or "").strip() or None
  453. record.account_phone = _whatsapp_phone_from_identifier(account_id)
  454. record.status = "connected"
  455. record.error = None
  456. elif event == "error":
  457. record.status = "error"
  458. record.error = str(payload.get("error") or "WhatsApp pairing failed.")
  459. elif event == "disconnected" and record.status == "starting":
  460. record.status = "waiting"
  461. def _watch_whatsapp_pairing(pairing_id: str, proc: subprocess.Popen) -> None:
  462. try:
  463. for line in proc.stdout or ():
  464. raw = line.strip()
  465. if not raw:
  466. continue
  467. try:
  468. payload = json.loads(raw)
  469. except json.JSONDecodeError:
  470. continue
  471. with _whatsapp_onboarding_lock:
  472. record = _whatsapp_onboarding_sessions.get(pairing_id)
  473. if not record or record.proc is not proc:
  474. return
  475. if record.status not in {"cancelled", "expired"}:
  476. _apply_pairing_event(record, payload)
  477. returncode = proc.wait()
  478. release_process_group_once_empty(proc.pid, proc=proc)
  479. except Exception as exc:
  480. _fail_whatsapp_pairing(pairing_id, str(exc), proc=proc)
  481. return
  482. # An "error" status from the stream may be overwritten by the exit reason.
  483. _fail_whatsapp_pairing(
  484. pairing_id, "WhatsApp pairing process exited before pairing completed." if returncode == 0
  485. else f"WhatsApp pairing process exited with code {returncode}.",
  486. proc=proc, unless={"connected", "cancelled", "expired"})
  487. def _run_whatsapp_pairing(pairing_id: str, session_path: Path, mode: str) -> None:
  488. with _whatsapp_onboarding_lock:
  489. record = _whatsapp_onboarding_sessions.get(pairing_id)
  490. if not record or record.status in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES:
  491. if record:
  492. _release_whatsapp_reservation(record)
  493. return
  494. record.status = "installing"
  495. record.starting_process = True
  496. try:
  497. try:
  498. proc = _spawn_whatsapp_pairing_process(session_path, mode)
  499. except Exception as exc:
  500. _fail_whatsapp_pairing(pairing_id, str(exc))
  501. return
  502. with _whatsapp_onboarding_lock:
  503. record.starting_process = False
  504. record.proc = proc
  505. if record.status in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES:
  506. _terminate_whatsapp_pairing(proc)
  507. return
  508. record.status = "starting"
  509. _watch_whatsapp_pairing(pairing_id, proc)
  510. finally:
  511. with _whatsapp_onboarding_lock:
  512. record.starting_process = False
  513. _release_whatsapp_reservation(record)
  514. def _release_whatsapp_reservation(record: _WhatsAppOnboardingSession) -> None:
  515. """Call under the onboarding lock. A live writer keeps its reservation."""
  516. if not record.session_reserved or record.starting_process:
  517. return
  518. if record.proc is None and record.status not in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES:
  519. return # A queued worker has not entered its startup section yet.
  520. if record.proc is not None and record.proc.poll() is None:
  521. return
  522. from gateway.status_scoped_locks import release_scoped_lock
  523. release_scoped_lock("whatsapp-session", record.session_path)
  524. record.session_reserved = False
  525. if record.expiry_timer is not None:
  526. record.expiry_timer.cancel()
  527. def _expire_whatsapp_pairing(record: _WhatsAppOnboardingSession) -> None:
  528. with _whatsapp_onboarding_lock:
  529. if record.status not in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES or record.session_reserved:
  530. record.status = "expired"
  531. record.error = "WhatsApp QR setup expired. Start a new setup."
  532. _terminate_whatsapp_pairing(record.proc)
  533. _release_whatsapp_reservation(record)
  534. def _prune_whatsapp_onboarding_sessions() -> None:
  535. now = time.time()
  536. remove_ids: list[str] = []
  537. for pairing_id, record in _whatsapp_onboarding_sessions.items():
  538. _release_whatsapp_reservation(record)
  539. live = record.status not in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES
  540. if live and record.proc is not None and record.proc.poll() is not None:
  541. record.status = "error"
  542. record.error = "WhatsApp pairing process exited before pairing completed."
  543. if record.expires_at_ts <= now:
  544. _expire_whatsapp_pairing(record)
  545. if record.status in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES and not record.session_reserved and record.expires_at_ts + 300 <= now:
  546. remove_ids.append(pairing_id)
  547. for pairing_id in remove_ids:
  548. _whatsapp_onboarding_sessions.pop(pairing_id, None)
  549. def _register_whatsapp_session(session_path: Path, record) -> str:
  550. """Store ``record`` under a fresh pairing id, cancelling any live session on
  551. the same session dir (superseded by the newer setup)."""
  552. pairing_id = secrets.token_urlsafe(16)
  553. with _whatsapp_onboarding_lock:
  554. _prune_whatsapp_onboarding_sessions()
  555. for existing in _whatsapp_onboarding_sessions.values():
  556. if existing.session_path == str(session_path) and existing.status not in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES:
  557. existing.status = "cancelled"
  558. existing.error = "Superseded by a newer WhatsApp setup session."
  559. _terminate_whatsapp_pairing(existing.proc)
  560. _whatsapp_onboarding_sessions[pairing_id] = record
  561. return pairing_id
  562. def _reserve_whatsapp_session(record: _WhatsAppOnboardingSession) -> None:
  563. """Reserve before moving keys or launching a writer, including its queued start."""
  564. from gateway.status import acquire_scoped_lock
  565. busy = "WhatsApp is in use. Disable WhatsApp and restart the gateway, then try re-pairing again."
  566. for existing in _whatsapp_onboarding_sessions.values():
  567. if existing.session_path == record.session_path and (
  568. existing.status not in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES
  569. or existing.session_reserved or existing.starting_process
  570. or (existing.proc is not None and existing.proc.poll() is None)
  571. ):
  572. raise HTTPException(status_code=409, detail="Another WhatsApp QR setup is still active. Cancel it or wait for it to stop before re-pairing.")
  573. acquired, previous = acquire_scoped_lock("whatsapp-session", record.session_path, metadata={"owner_kind": "process"})
  574. if not acquired or previous and previous.get("pid") == os.getpid():
  575. # Self-reacquisition is allowed for gateway reconnects. Reset must not
  576. # borrow or release a lock already held by this process.
  577. raise HTTPException(status_code=409, detail=busy)
  578. record.session_reserved = True
  579. def _launch_whatsapp_pairing(pairing_id: str, record: _WhatsAppOnboardingSession, session_path: Path) -> None:
  580. from agent.memory_provider import spawn_context_thread
  581. record.expiry_timer = threading.Timer(_WHATSAPP_ONBOARDING_TTL_SECONDS, _expire_whatsapp_pairing, args=(record,))
  582. record.expiry_timer.daemon = True
  583. launched = False
  584. try:
  585. record.expiry_timer.start()
  586. spawn_context_thread(_run_whatsapp_pairing, name="whatsapp-pairing",
  587. args=(pairing_id, session_path, record.mode)).start()
  588. launched = True
  589. finally:
  590. if not launched:
  591. record.status = "error"
  592. _release_whatsapp_reservation(record)
  593. @router.post("/api/messaging/whatsapp/onboarding/start")
  594. async def start_whatsapp_onboarding(body: WhatsAppOnboardingStart, profile: Optional[str] = None):
  595. mode = _normalize_whatsapp_onboarding_mode(body.mode)
  596. allowed_users = _normalize_whatsapp_allowed_users(body.allowed_users)
  597. target_profile = body.profile or profile
  598. with _config_profile_scope(target_profile), _whatsapp_onboarding_lock:
  599. _prune_whatsapp_onboarding_sessions()
  600. session_path = _whatsapp_session_path()
  601. if any(r.session_path == str(session_path) and r.session_reserved for r in _whatsapp_onboarding_sessions.values()):
  602. raise HTTPException(status_code=409, detail="Another WhatsApp QR setup is still active. Cancel it or wait for it to stop before re-pairing.")
  603. expires_at_ts = time.time() + _WHATSAPP_ONBOARDING_TTL_SECONDS
  604. fields: dict[str, Any] = dict(
  605. proc=None, mode=mode, allowed_users=allowed_users, session_path=str(session_path),
  606. expires_at=datetime.fromtimestamp(expires_at_ts, UTC).isoformat().replace("+00:00", "Z"),
  607. expires_at_ts=expires_at_ts, profile=target_profile,
  608. )
  609. already_linked = not body.reset_session and (session_path / "creds.json").exists()
  610. if already_linked: # creds on disk: report connected without pairing
  611. account_id, account_name, account_phone = _whatsapp_linked_account_from_session(session_path)
  612. fields.update(status="connected", account_id=account_id, account_name=account_name, account_phone=account_phone)
  613. record = _WhatsAppOnboardingSession(**fields)
  614. if already_linked:
  615. pairing_id = _register_whatsapp_session(session_path, record)
  616. else:
  617. _reserve_whatsapp_session(record)
  618. launched = False
  619. try:
  620. if body.reset_session:
  621. _backup_whatsapp_session(session_path)
  622. pairing_id = _register_whatsapp_session(session_path, record)
  623. _launch_whatsapp_pairing(pairing_id, record, session_path)
  624. launched = True
  625. finally:
  626. if not launched:
  627. record.status = "error"
  628. _release_whatsapp_reservation(record)
  629. return _whatsapp_onboarding_payload(pairing_id, record)
  630. def _whatsapp_record_or_404(pairing_id: str):
  631. """Call with ``_whatsapp_onboarding_lock`` held."""
  632. _prune_whatsapp_onboarding_sessions()
  633. record = _whatsapp_onboarding_sessions.get(pairing_id)
  634. if not record:
  635. raise HTTPException(status_code=404, detail=_WHATSAPP_SESSION_NOT_FOUND)
  636. return record
  637. @router.get("/api/messaging/whatsapp/onboarding/{pairing_id}")
  638. async def get_whatsapp_onboarding_status(pairing_id: str):
  639. with _whatsapp_onboarding_lock:
  640. record = _whatsapp_record_or_404(pairing_id)
  641. if record.status == "expired":
  642. raise HTTPException(status_code=410, detail=record.error or "WhatsApp setup expired.")
  643. return _whatsapp_onboarding_payload(pairing_id, record)
  644. @router.post("/api/messaging/whatsapp/onboarding/{pairing_id}/apply")
  645. async def apply_whatsapp_onboarding(pairing_id: str, body: WhatsAppOnboardingApply, profile: Optional[str] = None):
  646. await _wait_whatsapp_pairing_flush(pairing_id)
  647. with _whatsapp_onboarding_lock:
  648. record = _whatsapp_record_or_404(pairing_id)
  649. if record.status != "connected":
  650. raise HTTPException(status_code=409, detail="WhatsApp setup is not connected yet.")
  651. mode = _normalize_whatsapp_onboarding_mode(body.mode or record.mode)
  652. allowed_users = _normalize_whatsapp_allowed_users(record.allowed_users if body.allowed_users is None else body.allowed_users)
  653. if mode == "self-chat" and not allowed_users:
  654. allowed_users = record.account_phone or record.account_id or ""
  655. record_profile = record.profile
  656. effective_profile = body.profile or profile or record_profile
  657. with _onboarding_save_errors("WhatsApp onboarding apply failed", "Failed to save WhatsApp setup."):
  658. with _config_profile_scope(effective_profile):
  659. save_env_value("WHATSAPP_MODE", mode)
  660. save_env_value("WHATSAPP_DM_POLICY", "pairing")
  661. # Blank means "keep the existing allowlist"; explicit clearing
  662. # still lives in the normal config editor where the field is visible.
  663. if allowed_users:
  664. save_env_value("WHATSAPP_ALLOWED_USERS", allowed_users)
  665. save_env_value("WHATSAPP_ENABLED", "true")
  666. _write_platform_enabled("whatsapp", True)
  667. with _whatsapp_onboarding_lock:
  668. # A connected pair-only bridge may still be flushing credentials.
  669. # Retain it for reset's writer guard until that process has exited.
  670. if record.proc is None or record.proc.poll() is not None:
  671. _whatsapp_onboarding_sessions.pop(pairing_id, None)
  672. restart_result = _restart_gateway_after_whatsapp_onboarding(effective_profile)
  673. return {"ok": True, "platform": "whatsapp", "needs_restart": not restart_result["restart_started"], **restart_result}
  674. async def _wait_whatsapp_pairing_flush(pairing_id: str) -> None:
  675. with _whatsapp_onboarding_lock:
  676. record = _whatsapp_record_or_404(pairing_id)
  677. if record.status != "connected":
  678. raise HTTPException(status_code=409, detail="WhatsApp setup is not connected yet.")
  679. if record.session_reserved and record.proc is not None:
  680. try:
  681. await asyncio.to_thread(record.proc.wait, timeout=3)
  682. except subprocess.TimeoutExpired as exc:
  683. raise HTTPException(status_code=409, detail="WhatsApp is still saving its linked device. Wait a moment and try Save and restart again.") from exc
  684. with _whatsapp_onboarding_lock:
  685. _release_whatsapp_reservation(record)
  686. if record.session_reserved:
  687. raise HTTPException(status_code=409, detail="WhatsApp is still finishing pairing. Wait a moment and try Save and restart again.")
  688. @router.delete("/api/messaging/whatsapp/onboarding/{pairing_id}")
  689. async def cancel_whatsapp_onboarding(pairing_id: str):
  690. with _whatsapp_onboarding_lock:
  691. record = _whatsapp_onboarding_sessions.get(pairing_id)
  692. if record:
  693. record.status = "cancelled"
  694. _terminate_whatsapp_pairing(record.proc)
  695. _release_whatsapp_reservation(record)
  696. # Keep a cancelled worker visible until its process launch has
  697. # finished. It may still be opening the session directory.
  698. if not record.starting_process and (record.proc is None or record.proc.poll() is not None):
  699. _whatsapp_onboarding_sessions.pop(pairing_id, None)
  700. return {"ok": True}
  701. # ── Telegram QR onboarding ─────────────────────────────────────
  702. _TELEGRAM_SESSION_NOT_FOUND = "Telegram setup session was not found. Start a new setup."
  703. _TELEGRAM_INCOMPLETE_RESPONSE = "Telegram setup service returned an incomplete response."
  704. def _parse_expiry_ts(value: str) -> float:
  705. try:
  706. parsed = datetime.fromisoformat(value)
  707. if parsed.tzinfo is None:
  708. parsed = parsed.replace(tzinfo=UTC)
  709. return parsed.timestamp()
  710. except Exception:
  711. return time.time() + 600
  712. def _prune_telegram_onboarding_pairings() -> None:
  713. now = time.time()
  714. for pairing_id in [pid for pid, record in _telegram_onboarding_pairings.items() if record.expires_at_ts <= now]:
  715. _telegram_onboarding_pairings.pop(pairing_id, None)
  716. _TELEGRAM_USER_ID_RE = re.compile(r"\d+")
  717. def _normalize_telegram_user_id(value: Any) -> str | None:
  718. normalized = str(value or "").strip()
  719. return normalized if _TELEGRAM_USER_ID_RE.fullmatch(normalized) else None
  720. def _telegram_record_or_404(pairing_id: str):
  721. """Call with ``_telegram_onboarding_lock`` held."""
  722. _prune_telegram_onboarding_pairings()
  723. record = _telegram_onboarding_pairings.get(pairing_id)
  724. if not record:
  725. raise HTTPException(status_code=404, detail=_TELEGRAM_SESSION_NOT_FOUND)
  726. return record
  727. def _telegram_ready_payload(record) -> dict[str, Any]:
  728. return {
  729. "status": "ready", "bot_username": record.bot_username,
  730. "owner_user_id": record.owner_user_id, "expires_at": record.expires_at,
  731. }
  732. async def _telegram_onboarding_request(method: str, path: str, *, body=None, bearer_token=None) -> dict[str, Any]:
  733. return await asyncio.to_thread(_telegram_onboarding_request_sync, method, path, body=body, bearer_token=bearer_token)
  734. @router.post("/api/messaging/telegram/onboarding/start")
  735. async def start_telegram_onboarding(body: TelegramOnboardingStart):
  736. bot_name = (body.bot_name or "Hermes Agent").strip() or "Hermes Agent"
  737. payload = await _telegram_onboarding_request("POST", "/v1/telegram/pairings", body={"bot_name": bot_name})
  738. def field(key: str) -> str:
  739. return str(payload.get(key) or "").strip()
  740. pairing_id, poll_token, expires_at, deep_link = map(field, ("pairing_id", "poll_token", "expires_at", "deep_link"))
  741. if not pairing_id or not poll_token or not expires_at or not deep_link:
  742. raise HTTPException(status_code=502, detail=_TELEGRAM_INCOMPLETE_RESPONSE)
  743. with _telegram_onboarding_lock:
  744. _prune_telegram_onboarding_pairings()
  745. _telegram_onboarding_pairings[pairing_id] = _TelegramOnboardingPairing(
  746. poll_token=poll_token, expires_at=expires_at, expires_at_ts=_parse_expiry_ts(expires_at))
  747. return {
  748. "pairing_id": pairing_id, "suggested_username": field("suggested_username"), "deep_link": deep_link,
  749. "qr_payload": str(payload.get("qr_payload") or deep_link).strip(), "expires_at": expires_at,
  750. }
  751. @router.get("/api/messaging/telegram/onboarding/{pairing_id}")
  752. async def get_telegram_onboarding_status(pairing_id: str):
  753. with _telegram_onboarding_lock:
  754. record = _telegram_record_or_404(pairing_id)
  755. if record.bot_token:
  756. return _telegram_ready_payload(record)
  757. poll_token = record.poll_token
  758. payload = await _telegram_onboarding_request(
  759. "GET", f"/v1/telegram/pairings/{urllib.parse.quote(pairing_id, safe='')}", bearer_token=poll_token)
  760. status = str(payload.get("status") or "").strip()
  761. if status == "waiting":
  762. with _telegram_onboarding_lock:
  763. current = _telegram_onboarding_pairings.get(pairing_id)
  764. expires_at = current.expires_at if current else ""
  765. return {"status": "waiting", "expires_at": expires_at}
  766. if status == "ready":
  767. bot_token = str(payload.get("token") or "").strip()
  768. if not bot_token:
  769. raise HTTPException(status_code=502, detail=_TELEGRAM_INCOMPLETE_RESPONSE)
  770. with _telegram_onboarding_lock:
  771. record = _telegram_onboarding_pairings.get(pairing_id)
  772. if not record:
  773. raise HTTPException(status_code=404, detail=_TELEGRAM_SESSION_NOT_FOUND)
  774. record.bot_token = bot_token
  775. record.bot_username = str(payload.get("bot_username") or "").strip() or None
  776. record.owner_user_id = _normalize_telegram_user_id(payload.get("owner_user_id"))
  777. return _telegram_ready_payload(record)
  778. if status in {"expired", "claimed"}:
  779. with _telegram_onboarding_lock:
  780. _telegram_onboarding_pairings.pop(pairing_id, None)
  781. raise HTTPException(status_code=410, detail=_telegram_onboarding_error_message(
  782. status, "Telegram setup is no longer available. Start a new setup."))
  783. raise HTTPException(status_code=502, detail="Telegram setup service returned an unknown status.")
  784. @router.post("/api/messaging/telegram/onboarding/{pairing_id}/apply")
  785. async def apply_telegram_onboarding(pairing_id: str, body: TelegramOnboardingApply, profile: Optional[str] = None):
  786. normalized_ids = [_normalize_telegram_user_id(raw_id) for raw_id in body.allowed_user_ids]
  787. if not all(normalized_ids):
  788. raise HTTPException(status_code=400, detail="Allowed Telegram user IDs must be numeric.")
  789. allowed_user_ids = list(dict.fromkeys(normalized_ids))
  790. if not allowed_user_ids:
  791. raise HTTPException(status_code=400, detail="Add at least one allowed Telegram user ID.")
  792. with _telegram_onboarding_lock:
  793. record = _telegram_record_or_404(pairing_id)
  794. bot_token = record.bot_token
  795. bot_username = record.bot_username
  796. if not bot_token:
  797. raise HTTPException(status_code=409, detail="Telegram setup is not ready yet.")
  798. effective_profile = body.profile or profile
  799. def _apply():
  800. with _profile_scope(effective_profile):
  801. save_env_value("TELEGRAM_BOT_TOKEN", bot_token)
  802. save_env_value("TELEGRAM_ALLOWED_USERS", ",".join(allowed_user_ids))
  803. _write_platform_enabled("telegram", True)
  804. with _onboarding_save_errors("Telegram onboarding apply failed", "Failed to save Telegram setup."):
  805. await asyncio.to_thread(_apply)
  806. with _telegram_onboarding_lock:
  807. _telegram_onboarding_pairings.pop(pairing_id, None)
  808. # Best-effort restart: the QR flow pulls users into Telegram on another device, so a
  809. # saved token waiting on a manual restart click reads as "Hermes is broken" from the
  810. # chat side. The save stays authoritative; a failed restart is reported for the UI banner.
  811. restart_result = _restart_gateway_after(effective_profile, what="Telegram onboarding", label="Telegram onboarding")
  812. return {
  813. "ok": True, "platform": "telegram", "bot_username": bot_username,
  814. "needs_restart": not restart_result["restart_started"], **restart_result,
  815. }
  816. @router.delete("/api/messaging/telegram/onboarding/{pairing_id}")
  817. async def cancel_telegram_onboarding(pairing_id: str):
  818. with _telegram_onboarding_lock:
  819. _telegram_onboarding_pairings.pop(pairing_id, None)
  820. return {"ok": True}
  821. # ── platform list / update / test ──────────────────────────────
  822. @router.get("/api/messaging/platforms")
  823. async def get_messaging_platforms(profile: Optional[str] = None):
  824. # Profile-scoped so the global profile switcher shows the TARGET profile's channel state.
  825. def _run():
  826. # Profile-scoped so the dashboard's global profile switcher shows the TARGET profile's channel
  827. # credentials/state, not the root install's. load_env() honors the HERMES_HOME contextvar override;
  828. # the gateway status readers do NOT (they resolve process-level paths), so the profile directory is
  829. # passed explicitly for those (#71211).
  830. with _profile_scope(profile) as scoped_dir:
  831. return {
  832. "env_path": str(get_env_path()),
  833. "gateway_start_command": " ".join(["hermes", *_gateway_subcommand(profile, "start")]),
  834. "platforms": _platform_payloads(scoped_dir, _messaging_platform_catalog()),
  835. }
  836. return await asyncio.to_thread(_run)
  837. def _multiplex_port_binding_conflict(platform_id: str, requested_profile: Optional[str]) -> Optional[str]:
  838. """Reason enabling ``platform_id`` on the target profile is pointless under a multiplexed
  839. gateway, or ``None`` when allowed.
  840. With ``gateway.multiplex_profiles`` on, the default profile's listener already mirrors
  841. ``api_server`` and ``webhook`` at ``/p/<profile>/`` for every profile, so a SECONDARY must not
  842. enable a second one. Every other inbound-port platform (Twilio, LINE, Teams, ...) IS allowed on a
  843. secondary: the gateway serves it on the shared listener at ``/p/<profile>/<path>``.
  844. """
  845. from gateway.config import SHARED_LISTENER_MIRROR_PLATFORMS
  846. if platform_id not in SHARED_LISTENER_MIRROR_PLATFORMS:
  847. return None
  848. requested = (requested_profile or "").strip()
  849. if not requested or requested.lower() == "current":
  850. from hermes_cli.profiles import get_active_profile_name
  851. # The dashboard's own profile. "custom" (unrecognized HERMES_HOME) is outside
  852. # the profiles tree, so a multiplexed gateway never serves it.
  853. target = get_active_profile_name()
  854. else:
  855. _resolve_profile_dir(requested) # same 400/404 as _profile_scope
  856. target = requested
  857. if target in ("default", "custom"):
  858. return None
  859. # The flag that matters is the one the shared gateway settled at startup: its served record when
  860. # it runs, else the DEFAULT profile's explicit config (plus the process-wide
  861. # GATEWAY_MULTIPLEX_PROFILES override). An unset flag is decided by the gateway, not guessed here.
  862. from hermes_cli.gateway_multiplex_mode import default_gateway_multiplexes
  863. if not default_gateway_multiplexes():
  864. return None
  865. return (
  866. f"Cannot enable '{platform_id}' on profile '{target}': gateway.multiplex_profiles is on and the "
  867. f"default profile's listener already serves it for every profile at /p/{target}/. Configure it "
  868. "on the default profile instead (disabling or clearing it here is still allowed)."
  869. )
  870. @router.put("/api/messaging/platforms/{platform_id}")
  871. async def update_messaging_platform(platform_id: str, body: MessagingPlatformUpdate, profile: Optional[str] = None):
  872. target_profile = body.profile or profile
  873. def _resolve():
  874. # Plugin platforms (and their value rules) are registered per profile: resolve them in the
  875. # target's scope, the catalog GET /api/messaging/platforms?profile= lists.
  876. with _profile_scope(target_profile):
  877. return _require_platform(platform_id), _env_value_rules(platform_id)
  878. entry, env_value_rules = await asyncio.to_thread(_resolve)
  879. if body.enabled:
  880. conflict = await asyncio.to_thread(_multiplex_port_binding_conflict, platform_id, target_profile)
  881. if conflict:
  882. # Reject BEFORE any .env/config.yaml write so the profile stays
  883. # loadable by the multiplexed gateway.
  884. _log.info(
  885. "Rejected messaging platform update: platform=%s profile=%s "
  886. "(multiplex port-binding conflict)", platform_id, target_profile or "current",
  887. )
  888. raise HTTPException(status_code=409, detail=conflict)
  889. allowed_env = set(entry["env_vars"])
  890. def _check_allowed(key: str) -> None:
  891. if key not in allowed_env:
  892. raise HTTPException(status_code=400, detail=f"{key} is not configurable for {entry['name']}")
  893. def _apply():
  894. with _profile_scope(target_profile):
  895. updates: dict[str, str] = {}
  896. # Validate the whole request before clearing or replacing anything.
  897. for key in body.clear_env:
  898. _check_allowed(key)
  899. for key, value in body.env.items():
  900. _check_allowed(key)
  901. trimmed = value.strip()
  902. if not trimmed:
  903. continue
  904. if is_redacted_credential_preview(trimmed):
  905. raise HTTPException(status_code=400, detail=REDACTED_CREDENTIAL_WRITE_DETAIL)
  906. _validate_messaging_env_value(env_value_rules, key, trimmed)
  907. updates[key] = trimmed
  908. for key in body.clear_env:
  909. remove_env_value(key)
  910. for key, value in updates.items():
  911. save_env_value(key, value)
  912. if body.enabled is not None:
  913. _write_platform_enabled(platform_id, body.enabled)
  914. with http_failure(f"PUT /api/messaging/platforms/{platform_id} failed", 500, detail="Internal server error"):
  915. await asyncio.to_thread(_apply)
  916. # Audit trail for channel config mutations: names only, never values.
  917. _log.info(
  918. "Messaging platform updated: platform=%s profile=%s enabled=%s "
  919. "env_keys=%s cleared_keys=%s",
  920. platform_id, target_profile or "current", body.enabled, sorted(body.env), sorted(body.clear_env),
  921. )
  922. # A live multiplexer serving this named profile builds the adapter from the new token now
  923. # (its periodic rescan would otherwise pick it up within a cycle); no gateway restart.
  924. hot_served = await asyncio.to_thread(_notify_multiplexer_hot_serve, target_profile)
  925. return {"ok": True, "platform": platform_id, "hot_served": hot_served}
  926. def _notify_multiplexer_hot_serve(profile: Optional[str]) -> bool:
  927. """True when a live multiplexer serves the written profile and was told to rebuild its adapters.
  928. Unscoped (no ``?profile=``) means THIS process's profile: Desktop routes a pooled
  929. ``hermes --profile X serve`` without the query (#109088), so X must resolve here too."""
  930. from hermes_cli.gateway import _current_profile_name, named_profile_served_by_running_multiplexer
  931. from hermes_cli.gateway_multiplex_served import notify_multiplexer_profiles_changed
  932. name = (profile or "").strip() or _current_profile_name()
  933. if not name or name == "default" or not named_profile_served_by_running_multiplexer(name):
  934. return False
  935. return notify_multiplexer_profiles_changed(name) is not None
  936. def _gate_env(name: str) -> str:
  937. """Per-profile allow/deny gate env read, always stripped (gateway seam)."""
  938. from gateway.platforms._shared import platform_gate_env
  939. return platform_gate_env(name)
  940. def _platform_authz_env_names(platform_id: str) -> tuple[str, str]:
  941. """``(allowed_users_env, allow_all_env)`` for a platform, honoring plugin registry
  942. entries. Empty strings mean "this platform has no per-user authorization surface"
  943. (webhook-style trusted inbound or unknown), so no posture is computed for it."""
  944. allowed = allow_all = ""
  945. with contextlib.suppress(Exception):
  946. from gateway.platform_registry import platform_registry
  947. from gateway.platform_env import authz_field
  948. entry = platform_registry.get(platform_id)
  949. if entry is not None and getattr(entry, "trusted_inbound", False) is True:
  950. return "", ""
  951. allowed = authz_field(platform_id, "allowed_users_env", entry) or ""
  952. allow_all = authz_field(platform_id, "allow_all_env", entry) or ""
  953. return allowed, allow_all
  954. def _platform_dm_policy(platform_id: str) -> str:
  955. """Effective ``dm_policy`` for the ACTIVE profile's ``platforms.<id>`` config
  956. (``open``/``allowlist``/``disabled``/``pairing``). The default here is NOT the adapter
  957. default: adapters without a config key never consult ``dm_policy`` in
  958. ``_principal_authorized``, so a policy-shaped key only matters where one exists."""
  959. with contextlib.suppress(Exception):
  960. plat_cfg = (load_config().get("platforms") or {}).get(platform_id)
  961. if isinstance(plat_cfg, dict):
  962. policy = str(plat_cfg.get("extra", {}).get("dm_policy") or "").strip().lower()
  963. if policy:
  964. return policy
  965. return ""
  966. def _count_csv(value: str) -> int:
  967. return len([part for part in (value or "").split(",") if part.strip()])
  968. def _messaging_platform_posture(
  969. platform_id: str, entry: dict[str, Any], scoped: bool, authz_env: tuple[str, str]
  970. ) -> dict[str, Any] | None:
  971. """Auth-posture verdict for a CONNECTED platform (must be called inside the profile
  972. scope, after the connectivity chain has already reported ``connected``).
  973. Mirrors the decision ladder of ``AuthorizationMixin._principal_authorized``
  974. (gateway/authz_mixin.py) for the "can any user reach the bot" question, evaluated
  975. against the ACTIVE profile's env/config only — never the dashboard process's
  976. ``os.environ`` (which carries the ROOT profile's credentials, #66030):
  977. - allow-all flags: ``{PLATFORM}_ALLOW_ALL_USERS`` then ``GATEWAY_ALLOW_ALL_USERS``
  978. - allowlists: the platform's ``{PLATFORM}_ALLOWED_USERS``, ``GATEWAY_ALLOWED_USERS``,
  979. plus the Telegram group vars (a group-only grant still authorizes real users)
  980. - pairing grants: approved users in the profile's pairing store (the gateway honors
  981. the store as a UNION with the allowlists)
  982. - adapter/config-enforced policy (``dm_policy: allowlist`` with an ``allow_from``):
  983. the own-policy adapters (WeCom, Weixin, QQBot, WhatsApp, Yuanbao) gate at intake
  984. Everything failing → deny-all: the connection is up but no sender can get through,
  985. which the Channels "Test" button must not render as a plain green "connected".
  986. Returns ``None`` when the platform has no per-user authorization surface at all.
  987. *authz_env* is :func:`_platform_authz_env_names`, resolved OUTSIDE the profile scope (see
  988. :func:`_env_value_rules`: the scope's registry overlay may not hold the entry).
  989. """
  990. allowed_env, allow_all_env = authz_env
  991. if not allowed_env:
  992. return None
  993. # Same scoped-vs-process split _platform_enablement uses: under a named profile the
  994. # process env belongs to the ROOT install and must not authorize anyone here, and a
  995. # profile's .env must not borrow the root's allowlists (false green) either.
  996. def gate_env(name: str) -> str:
  997. if scoped:
  998. return load_env().get(name, "")
  999. return _gate_env(name)
  1000. if allow_all_env and gate_env(allow_all_env).lower() in ("true", "1", "yes"):
  1001. return {"posture": "open", "message": f"{entry['name']} is open: {allow_all_env} is set."}
  1002. if gate_env("GATEWAY_ALLOW_ALL_USERS").lower() in ("true", "1", "yes"):
  1003. return {"posture": "open", "message": "Gateway is open: GATEWAY_ALLOW_ALL_USERS is set."}
  1004. allowlists = {
  1005. allowed_env: gate_env(allowed_env),
  1006. "GATEWAY_ALLOWED_USERS": gate_env("GATEWAY_ALLOWED_USERS"),
  1007. "TELEGRAM_GROUP_ALLOWED_USERS": gate_env("TELEGRAM_GROUP_ALLOWED_USERS") if platform_id == "telegram" else "",
  1008. "TELEGRAM_GROUP_ALLOWED_CHATS": gate_env("TELEGRAM_GROUP_ALLOWED_CHATS") if platform_id == "telegram" else "",
  1009. }
  1010. for env_name, value in allowlists.items():
  1011. if value.strip():
  1012. n = _count_csv(value)
  1013. return {
  1014. "posture": "allowlist",
  1015. "message": f"Connected. {n} user{'s' if n != 1 else ''} allowlisted via {env_name}.",
  1016. }
  1017. if _platform_dm_policy(platform_id) == "allowlist":
  1018. return {"posture": "allowlist", "message": "Connected. Access restricted by the configured allow_from policy."}
  1019. # Pairing grants: the profile's approved users (the gateway honors the store as a
  1020. # union with any allowlist, gateway/authz_mixin.py `_pairing_store_for`).
  1021. approved = pending = 0
  1022. with contextlib.suppress(Exception):
  1023. from gateway.pairing import PairingStore
  1024. store = PairingStore()
  1025. approved = len(store.list_approved(platform_id))
  1026. pending = len(store.list_pending(platform_id))
  1027. if approved:
  1028. return {
  1029. "posture": "pairing",
  1030. "message": f"Connected. {approved} user{'s' if approved != 1 else ''} paired.",
  1031. }
  1032. base = (
  1033. f"{entry['name']} is connected, but no users are authorized yet — "
  1034. f"set {allowed_env}, approve a pairing request, or enable pairing for new users."
  1035. )
  1036. if pending:
  1037. base += f" {pending} pairing request{'s' if pending != 1 else ''} pending approval."
  1038. return {"posture": "deny_all", "message": base}
  1039. @router.post("/api/messaging/platforms/{platform_id}/test")
  1040. async def test_messaging_platform(platform_id: str, profile: Optional[str] = None):
  1041. def _run():
  1042. with _profile_scope(profile) as scoped_dir:
  1043. entry = _require_platform(platform_id)
  1044. authz_env = _platform_authz_env_names(platform_id)
  1045. payload = _platform_payloads(scoped_dir, [entry])[0]
  1046. posture = None
  1047. if payload["state"] == "connected":
  1048. # Still inside the profile scope: load_env()/load_config()/PairingStore
  1049. # must resolve the ACTIVE profile's env/config/pairing store, not the
  1050. # dashboard process's root home.
  1051. posture = _messaging_platform_posture(platform_id, entry, scoped_dir is not None, authz_env)
  1052. return entry, payload, posture
  1053. entry, payload, posture = await asyncio.to_thread(_run)
  1054. def result(ok: bool, message: str) -> dict[str, Any]:
  1055. return {"ok": ok, "state": payload["state"], "message": message}
  1056. if not payload["enabled"]:
  1057. return result(False, f"{entry['name']} is disabled. Enable it, then restart the gateway.")
  1058. if not payload["configured"]:
  1059. missing = [field["key"] for field in payload["env_vars"] if field["required"] and not field["is_set"]]
  1060. return result(False, f"Missing required setup: {', '.join(missing)}" if missing else "Platform setup is incomplete.")
  1061. if not payload["gateway_running"]:
  1062. return result(False, "Gateway is not running. Restart the gateway to connect this platform.")
  1063. if payload["state"] == "connected":
  1064. # Non-breaking extension (#66030): keep ok=True (the connection is genuinely up)
  1065. # but surface the platform's auth posture so the UI can render yellow on
  1066. # connected-but-unreachable, and say exactly what to configure.
  1067. if posture is None:
  1068. return result(True, f"{entry['name']} is connected.")
  1069. return {
  1070. "ok": True,
  1071. "state": payload["state"],
  1072. "message": posture["message"],
  1073. "auth_posture": posture["posture"],
  1074. }
  1075. if payload.get("error_message"):
  1076. return result(False, payload["error_message"])
  1077. return result(False, "Setup looks complete, but the gateway has not reported a connection yet. Restart the gateway.")