adapter.py 177 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220322132223223322432253226322732283229323032313232323332343235323632373238323932403241324232433244324532463247324832493250325132523253325432553256325732583259326032613262326332643265326632673268326932703271327232733274327532763277327832793280328132823283
  1. # health: allow FILE_LINES -- platform-tables refactor: core's PLATFORM_HINTS/_PLATFORM_DEFAULTS rows for this platform moved onto its register() call (hint text lives in adapter_hint.py); the growth is only those kwargs
  2. """Matrix gateway adapter (any homeserver, via mautrix; optional E2EE with ``mautrix[encryption]``).
  3. Env vars (config.yaml ``matrix:`` keys alias several — env wins):
  4. MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (preferred) | MATRIX_USER_ID + MATRIX_PASSWORD;
  5. MATRIX_E2EE_MODE off|optional|required (legacy MATRIX_ENCRYPTION=true => required);
  6. MATRIX_DEVICE_ID (stable E2EE device), MATRIX_RECOVERY_KEY (cross-signing after key rotation),
  7. MATRIX_RECOVERY_KEY_OUTPUT_FILE (one-time 0600 write of a bootstrapped key), MATRIX_PROXY;
  8. MATRIX_ALLOWED_USERS, MATRIX_ALLOWED_ROOMS (whitelist; DMs exempt), MATRIX_IGNORE_USER_PATTERNS
  9. (regexes for bridge ghosts), MATRIX_HOME_ROOM (cron delivery), MATRIX_REACTIONS (default true);
  10. MATRIX_REQUIRE_MENTION (default true), MATRIX_THREAD_REQUIRE_MENTION, MATRIX_FREE_RESPONSE_ROOMS,
  11. MATRIX_PROCESS_NOTICES, MATRIX_ALLOW_ROOM_MENTIONS, MATRIX_ALLOW_PUBLIC_ROOMS (all default false);
  12. MATRIX_AUTO_THREAD (default true), MATRIX_DM_AUTO_THREAD, MATRIX_DM_MENTION_THREADS,
  13. MATRIX_SESSION_SCOPE auto|room|thread; MATRIX_MAX_MESSAGE_LENGTH (UTF-8 bytes, default/max 15000),
  14. MATRIX_MAX_MEDIA_BYTES, MATRIX_ROOM_IDENTITY_TTL_SECONDS; MATRIX_APPROVAL_REQUIRE_SENDER (default
  15. true), MATRIX_APPROVAL_TIMEOUT_SECONDS (default 300).
  16. Note: any room with <=2 joined members is auto-classified as a DM (see
  17. ``_resolve_room_identity``), regardless of ``m.direct`` account data or an explicit room name —
  18. clients auto-name DMs like "Alice & Bot", so name alone can't be trusted. A DM-classified room
  19. therefore bypasses MATRIX_ALLOWED_ROOMS, MATRIX_FREE_RESPONSE_ROOMS, and MATRIX_REQUIRE_MENTION,
  20. and follows MATRIX_DM_AUTO_THREAD / MATRIX_DM_MENTION_THREADS instead of MATRIX_AUTO_THREAD /
  21. MATRIX_SESSION_SCOPE. To make a deliberately-created 2-person room behave like a regular room,
  22. add a third member so it has >2 joined members.
  23. """
  24. from __future__ import annotations
  25. import asyncio
  26. import array
  27. import inspect
  28. import json
  29. from contextlib import suppress
  30. import logging
  31. import mimetypes
  32. import os
  33. import re
  34. import shutil
  35. import subprocess
  36. import sys
  37. import time
  38. from urllib.parse import urljoin, urlsplit, urlunsplit
  39. from dataclasses import dataclass, field
  40. from html import escape as _html_escape
  41. from html.parser import HTMLParser
  42. from pathlib import Path
  43. from typing import Any, Dict, Optional, Set
  44. from agent.i18n import t
  45. from agent.secret_scope import get_secret
  46. from gateway.platforms._shared import (
  47. apply_yaml_bridge as _apply_yaml_bridge, extra_or_secret as _extra_or_secret,
  48. get_scoped_secret as _get_scoped_secret, send_error
  49. )
  50. try:
  51. from mautrix.types import (
  52. ContentURI, EventID, EventType, PresenceState, RoomCreatePreset, RoomID, TrustState, UserID)
  53. except ImportError:
  54. # Import-safe stubs without mautrix: check_matrix_requirements() gates production use, but
  55. # tests exercise adapter methods so the attributes must exist.
  56. ContentURI = EventID = RoomID = UserID = str # type: ignore[misc,assignment]
  57. EventType = type("_EventTypeStub", (), { # type: ignore[misc,assignment]
  58. "ROOM_MESSAGE": "m.room.message", "REACTION": "m.reaction",
  59. "ROOM_ENCRYPTED": "m.room.encrypted", "ROOM_NAME": "m.room.name"})
  60. PresenceState = type("_PresenceStateStub", (), { # type: ignore[misc,assignment]
  61. "ONLINE": "online", "OFFLINE": "offline", "UNAVAILABLE": "unavailable"})
  62. RoomCreatePreset = type("_RoomCreatePresetStub", (), { # type: ignore[misc,assignment]
  63. "PRIVATE": "private_chat", "PUBLIC": "public_chat", "TRUSTED_PRIVATE": "trusted_private_chat"})
  64. TrustState = type("_TrustStateStub", (), {"UNVERIFIED": 0, "VERIFIED": 1}) # type: ignore[misc,assignment]
  65. from gateway.config import Platform, PlatformConfig
  66. from gateway.platforms.base import (
  67. gateway_trust_env, BasePlatformAdapter, ExecApprovalPrompt,
  68. SendResult, resolve_proxy_url, proxy_kwargs_for_aiohttp, ssrf_redirect_guard,
  69. )
  70. from gateway.platforms.base import transcode_to_ogg_opus
  71. from gateway.platforms.event import MessageEvent, MessageType, ProcessingOutcome
  72. from gateway.platforms.helpers import ThreadParticipationTracker
  73. from plugins.platforms.matrix.voice_mention import ParkedVoices, VoiceGate, has_voice_marker, is_voice_event
  74. logger = logging.getLogger(__name__)
  75. _MATRIX_VOICE_WAVEFORM_BINS = 30
  76. def _run_media_tool(cmd: list, *, timeout: int, text: bool = False):
  77. """Run ffmpeg/ffprobe with captured output and no stdin."""
  78. return subprocess.run(cmd, capture_output=True, text=text, timeout=timeout, stdin=subprocess.DEVNULL, check=False)
  79. def _matrix_voice_metadata_for_file(path: Path) -> dict[str, Any]:
  80. """Best-effort duration + MSC1767 waveform for voice bubbles; must work without ffprobe/ffmpeg."""
  81. metadata: dict[str, Any] = {}
  82. ffprobe = shutil.which("ffprobe")
  83. if ffprobe:
  84. try:
  85. result = _run_media_tool(
  86. [ffprobe, "-v", "error", "-show_entries", "format=duration", "-of",
  87. "default=noprint_wrappers=1:nokey=1", str(path)], timeout=10, text=True)
  88. if result.returncode == 0:
  89. duration = float((result.stdout or "").strip() or 0)
  90. if duration > 0:
  91. metadata["duration"] = int(duration * 1000)
  92. except Exception:
  93. logger.debug("Matrix: failed to probe voice duration for %s", path, exc_info=True)
  94. ffmpeg = shutil.which("ffmpeg")
  95. if ffmpeg:
  96. try:
  97. result = _run_media_tool(
  98. [ffmpeg, "-v", "error", "-i", str(path), "-ac", "1", "-ar", "8000", "-f", "s16le", "-"], timeout=15)
  99. if result.returncode == 0 and result.stdout:
  100. samples = array.array("h")
  101. samples.frombytes(result.stdout)
  102. if sys.byteorder != "little":
  103. samples.byteswap()
  104. if samples:
  105. count, bins = len(samples), _MATRIX_VOICE_WAVEFORM_BINS
  106. waveform = []
  107. for idx in range(bins):
  108. start = idx * count // bins
  109. peak = max(abs(v) for v in samples[start:max(start + 1, (idx + 1) * count // bins)])
  110. waveform.append(min(1024, int(peak / 32767 * 1024)))
  111. metadata["waveform"] = waveform
  112. except Exception:
  113. logger.debug("Matrix: failed to build voice waveform for %s", path, exc_info=True)
  114. return metadata
  115. _MATRIX_BANG_COMMAND_RE = re.compile(r"^!([A-Za-z][A-Za-z0-9_-]*)(?=$|\s)(.*)$", re.DOTALL)
  116. def _resolve_matrix_bang_command(name: str) -> str | None:
  117. """Resolve a ``!command`` token (Matrix clients reserve ``/``) to a dispatchable token.
  118. Only known gateway/skill commands resolve, so ordinary exclamations stay chat text. Returns
  119. whichever candidate resolved — raw lowercased first, then ``_``→``-`` — never a forced
  120. canonical form: aliases pass through for the dispatcher."""
  121. if not name:
  122. return None
  123. candidates = list(dict.fromkeys((name.lower(), name.lower().replace("_", "-"))))
  124. try:
  125. from hermes_cli.commands import is_gateway_known_command
  126. for candidate in candidates:
  127. if is_gateway_known_command(candidate):
  128. return candidate
  129. except Exception:
  130. logger.debug("Matrix: is_gateway_known_command failed for %r", name, exc_info=True)
  131. try:
  132. from agent.skill_commands import get_skill_commands
  133. skill_commands = get_skill_commands() or {} # keys are slash-prefixed ("/arxiv")
  134. for candidate in candidates:
  135. if f"/{candidate}" in skill_commands:
  136. return candidate
  137. except Exception:
  138. logger.debug("Matrix: get_skill_commands failed for %r", name, exc_info=True)
  139. return None
  140. def _normalize_matrix_bang_command(text: str) -> str:
  141. """Convert Matrix ``!command`` aliases to normal Hermes ``/command`` text."""
  142. if not text or not text.startswith("!"):
  143. return text
  144. match = _MATRIX_BANG_COMMAND_RE.match(text)
  145. resolved = _resolve_matrix_bang_command(match.group(1)) if match else None
  146. if resolved is None:
  147. return text
  148. return f"/{resolved}{match.group(2) or ''}"
  149. # Reply fallback prefix: "> <@alice:example.org> quoted\n> more\n\nactual reply".
  150. _MATRIX_REPLY_FALLBACK_PILL_RE = re.compile(r"^>\s*<(@[^>]+)>\s*(.*)$")
  151. def _extract_reply_fallback(body: str) -> tuple[Optional[str], Optional[str]]:
  152. """Return (quoted_text, author_mxid) from the inline reply fallback; author from the first-line pill."""
  153. if not body or not body.startswith("> "):
  154. return None, None
  155. quoted_lines: list[str] = []
  156. author_id: Optional[str] = None
  157. for line in body.split("\n"):
  158. if not line.startswith("> "):
  159. break
  160. content = line[2:]
  161. if author_id is None:
  162. pill_match = _MATRIX_REPLY_FALLBACK_PILL_RE.match(line)
  163. if pill_match:
  164. author_id = pill_match.group(1)
  165. content = pill_match.group(2) # drop the pill from the visible quote
  166. quoted_lines.append(content)
  167. quoted_text = "\n".join(quoted_lines).strip() or None
  168. return quoted_text, author_id
  169. def _strip_reply_fallback(body: str) -> str:
  170. """Strip the inline ``> quote\\n\\nreply`` fallback prefix; unchanged if absent."""
  171. if not body or not body.startswith("> "):
  172. return body
  173. stripped = []
  174. past_fallback = False
  175. for line in body.split("\n"):
  176. if not past_fallback:
  177. if line.startswith("> ") or line == ">":
  178. continue
  179. past_fallback = True
  180. if line == "":
  181. continue
  182. stripped.append(line)
  183. return "\n".join(stripped) if stripped else body
  184. # Auth errcodes that genuinely require re-authentication (never retried).
  185. _MATRIX_PERMANENT_ERRCODES = frozenset({
  186. "m_unknown_token",
  187. "m_missing_token",
  188. "m_forbidden",
  189. })
  190. def _is_permanent_matrix_auth_error(exc: BaseException) -> bool:
  191. """Return True only for genuine auth failures that must stop the sync loop.
  192. A transient homeserver outage surfaces as a 5xx whose body may be an HTML
  193. error page (Umbrel's app-proxy returns one). Naive substring checks like
  194. ``"403" in str(exc)`` false-positive on digits embedded in that HTML (an SVG
  195. path coordinate such as ``1403.2`` contains ``403``) or in the ``since`` token
  196. echoed by a timeout message, which stopped the sync loop permanently on a
  197. passing blip. mautrix raises ``MatrixRequestError`` with ``errcode`` and
  198. ``http_status`` for every non-2xx, so classify on those alone; anything
  199. without a structured auth signal (timeouts, dropped connections, 5xx) is
  200. retried. Deliberately not ``.status``/``.status_code``/``.code``: those
  201. belong to unrelated exception shapes (aiohttp responses, OS errno) and can
  202. misclassify on a coincidental integer.
  203. """
  204. errcode = getattr(exc, "errcode", None)
  205. if isinstance(errcode, str) and errcode.strip().lower() in _MATRIX_PERMANENT_ERRCODES:
  206. return True
  207. status = getattr(exc, "http_status", None)
  208. return isinstance(status, int) and status in (401, 403)
  209. def _split_reply_fallback(body: str) -> tuple[str, str]:
  210. """Split ``> quote\\n\\nreply`` into ``(quote_block, reply_text)``; ``("", body)`` when absent.
  211. The two halves always concatenate back to *body* verbatim (``quote + reply == body``), so
  212. callers can transform one half and rebuild the body without disturbing the other. The blank
  213. separator line belongs to the quote block. Used to keep the ``> <@user:srv>`` reply pill —
  214. the only mention text in a reply-to-the-bot — out of whole-body rewrites.
  215. """
  216. if not body or not body.startswith("> "):
  217. return "", body
  218. lines = body.split("\n")
  219. idx = 0
  220. while idx < len(lines) and (lines[idx].startswith("> ") or lines[idx] == ">"):
  221. idx += 1
  222. if idx < len(lines) and lines[idx] == "":
  223. idx += 1 # the blank line separating the quote from the reply belongs to the quote
  224. head = "\n".join(lines[:idx])
  225. return (head, "") if idx >= len(lines) else (head + "\n", "\n".join(lines[idx:]))
  226. class _MatrixHtmlSanitizer(HTMLParser):
  227. """Allowlist sanitizer for Matrix-compatible formatted HTML."""
  228. _ALLOWED_TAGS = {
  229. "a", "b", "blockquote", "br", "code", "del", "em", "h1", "h2", "h3", "h4", "h5", "h6", "hr", "i", "li", "ol",
  230. "p", "pre", "s", "strike", "strong", "table", "tbody", "td", "th", "thead", "tr", "ul"}
  231. _VOID_TAGS = {"br", "hr"}
  232. def __init__(self) -> None:
  233. super().__init__(convert_charrefs=False)
  234. self._parts: list[str] = []
  235. self._skip_depth = 0
  236. @staticmethod
  237. def _safe_url(value: str) -> str:
  238. stripped = re.sub(r"[\x00-\x1f\x7f]+", "", value or "").strip()
  239. match = re.match(r"^([A-Za-z][A-Za-z0-9+.-]*):", stripped)
  240. scheme = match.group(1).lower() if match else ""
  241. if scheme and scheme not in {"http", "https", "matrix", "mailto"}:
  242. return ""
  243. return stripped
  244. def _safe_attrs(self, tag: str, attrs: list[tuple[str, str | None]]) -> str:
  245. safe: list[str] = []
  246. for key, value in attrs:
  247. attr = str(key or "").lower()
  248. raw_value = "" if value is None else str(value)
  249. if tag == "a" and attr == "href":
  250. href = self._safe_url(raw_value)
  251. if href:
  252. safe.append(f' href="{_html_escape(href, quote=True)}"')
  253. elif tag == "code" and attr == "class" and re.fullmatch(r"language-[A-Za-z0-9_+.-]{1,64}", raw_value):
  254. safe.append(f' class="{_html_escape(raw_value, quote=True)}"')
  255. return "".join(safe)
  256. def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
  257. tag = tag.lower()
  258. if tag in {"script", "style"}:
  259. self._skip_depth += 1
  260. elif not self._skip_depth and tag in self._ALLOWED_TAGS:
  261. self._parts.append(f"<{tag}>" if tag in self._VOID_TAGS else f"<{tag}{self._safe_attrs(tag, attrs)}>")
  262. def handle_endtag(self, tag: str) -> None:
  263. tag = tag.lower()
  264. if tag in {"script", "style"} and self._skip_depth:
  265. self._skip_depth -= 1
  266. return
  267. if self._skip_depth or tag not in self._ALLOWED_TAGS or tag in self._VOID_TAGS:
  268. return
  269. self._parts.append(f"</{tag}>")
  270. def _emit(self, text: str) -> None:
  271. if not self._skip_depth:
  272. self._parts.append(text)
  273. def handle_data(self, data: str) -> None:
  274. self._emit(_html_escape(data))
  275. def handle_entityref(self, name: str) -> None:
  276. self._emit(f"&{name};")
  277. def handle_charref(self, name: str) -> None:
  278. self._emit(f"&#{name};")
  279. def get_html(self) -> str:
  280. return "".join(self._parts)
  281. @dataclass(frozen=True)
  282. class MatrixRoomIdentity:
  283. """Resolved Matrix room identity for routing and prompt context."""
  284. room_id: str
  285. room_name: str | None
  286. room_topic: str | None
  287. canonical_alias: str | None
  288. server_name: str | None
  289. joined_member_count: int | None
  290. is_direct_account_data: bool
  291. display_name: str
  292. has_explicit_name: bool
  293. chat_type: str
  294. conflict: bool = False
  295. @dataclass
  296. class _MatrixApprovalPrompt:
  297. """Pending reaction-based exec approval prompt."""
  298. session_key: str
  299. chat_id: str
  300. message_id: str
  301. resolved: bool = False
  302. requester_user_id: str | None = None
  303. expires_at: float | None = None
  304. request_id: str | None = None # the tools.approval request this prompt answers
  305. bot_reaction_events: dict[str, str] = field(default_factory=dict, init=False) # emoji -> event_id
  306. @dataclass
  307. class _MatrixPickerPrompt:
  308. """Pending reaction-based picker; ``choices`` maps emoji -> selection, ``on_selected`` is the callback."""
  309. chat_id: str
  310. message_id: str
  311. session_key: str
  312. choices: dict
  313. on_selected: Any
  314. requester_user_id: str | None = None
  315. expires_at: float | None = None
  316. resolved: bool = False
  317. bot_reaction_events: dict[str, str] = field(default_factory=dict)
  318. _MatrixModelPickerPrompt = _MatrixChoicePickerPrompt = _MatrixPickerPrompt
  319. # The homeserver rejects an event whose JSON exceeds 65,536 bytes (M_TOO_LARGE). Event content stays
  320. # under this budget so the envelope (ids, hashes, signatures) and E2EE's 4/3 base64 inflation still fit.
  321. _MAX_CONTENT_BYTES = 45_000
  322. # Outbound text is measured in UTF-8 bytes (``message_len_fn``). A message carries it twice (body +
  323. # formatted_body, whose HTML runs up to about twice the Markdown), so a chunk gets a third of the
  324. # budget. The previous 4,000-char default split Markdown tables mid-row (#53026).
  325. MATRIX_MAX_MESSAGE_LENGTH_CEILING = _MAX_CONTENT_BYTES // 3
  326. DEFAULT_MAX_MESSAGE_LENGTH = MATRIX_MAX_MESSAGE_LENGTH_CEILING
  327. def _utf8_len(text: str) -> int:
  328. return len(text.encode("utf-8"))
  329. def _content_bytes(content: dict[str, Any]) -> int:
  330. """Size of event content as the homeserver counts it (canonical JSON is UTF-8, not \\u-escaped)."""
  331. return _utf8_len(json.dumps(content, ensure_ascii=False, separators=(",", ":")))
  332. def _resolve_max_message_length(config) -> int:
  333. """Resolve outbound chunk size from config, env, or plugin registry."""
  334. raw = _extra_or_secret(getattr(config, "extra", None), "max_message_length", "MATRIX_MAX_MESSAGE_LENGTH", None)
  335. if raw is None or not str(raw).strip():
  336. with suppress(Exception):
  337. from gateway.platform_registry import platform_registry
  338. entry = platform_registry.get("matrix")
  339. if entry and entry.max_message_length:
  340. raw = entry.max_message_length
  341. try:
  342. value = int(raw)
  343. except (TypeError, ValueError):
  344. return DEFAULT_MAX_MESSAGE_LENGTH
  345. return max(500, min(value, MATRIX_MAX_MESSAGE_LENGTH_CEILING))
  346. # E2EE store dir is resolved per adapter in connect() (``_resolve_store_dir``), NOT at module scope:
  347. # the multiplex gateway imports this once and a module constant would collide every profile's Olm
  348. # identity in one crypto.db.
  349. # Store directory for E2EE keys and sync state. Mirrors the pairing-store fix (a6397c379). See #89168.
  350. from hermes_constants import get_hermes_dir as _get_hermes_dir
  351. _STARTUP_GRACE_SECONDS = 5 # ignore messages older than this many seconds before startup
  352. _OUTBOUND_MENTION_RE = re.compile(r"(?<![\w/])(@[0-9A-Za-z._=/-]+:[0-9A-Za-z.-]+(?::\d+)?)")
  353. _E2EE_INSTALL_HINT = "Install with: pip install 'mautrix[encryption]' asyncpg aiosqlite (requires libolm C library)"
  354. _MATRIX_IMAGE_FILENAME_EXTS = frozenset({
  355. ".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp", ".svg", ".heic", ".heif", ".avif"})
  356. _MATRIX_MEDIA_FILENAME_EXTS = frozenset({
  357. ".ogg", ".oga", ".opus", ".m4a", ".mp3", ".wav", ".flac", ".aac", ".amr", ".mp4", ".webm", ".mov", ".mkv"})
  358. # Keycap 1-9, 🔟; choice pickers (/reasoning, /fast) can need 12 slots, so they add 🅰️ 🅱️.
  359. _MATRIX_MODEL_PICKER_REACTIONS = tuple(f"{d}\ufe0f\u20e3" for d in "123456789") + ("\U0001f51f",)
  360. _MATRIX_CHOICE_PICKER_REACTIONS = _MATRIX_MODEL_PICKER_REACTIONS + ("\U0001f170\ufe0f", "\U0001f171\ufe0f")
  361. def _looks_like_matrix_image_filename(text: str) -> bool:
  362. """True when an m.image body is just the uploaded filename (no caption) — not user text."""
  363. return _looks_like_transport_filename(text, "image/", _MATRIX_IMAGE_FILENAME_EXTS)
  364. def _looks_like_transport_filename(text: str, mime_prefixes, exts: frozenset, reject_spaces: bool = False) -> bool:
  365. """Bare single-token filename with a known media extension or a matching guessed MIME type."""
  366. candidate = str(text or "").strip()
  367. if not candidate or "\n" in candidate or candidate.endswith("/"):
  368. return False
  369. # A genuine caption essentially always contains whitespace; a bare transport filename does not.
  370. if reject_spaces and any(ch.isspace() for ch in candidate):
  371. return False
  372. if Path(candidate).name != candidate:
  373. return False
  374. suffix = Path(candidate).suffix.lower()
  375. if not suffix:
  376. return False
  377. guessed_type, _ = mimetypes.guess_type(candidate)
  378. return bool(guessed_type and guessed_type.startswith(mime_prefixes)) or suffix in exts
  379. def _looks_like_matrix_media_filename(text: str) -> bool:
  380. """True when an m.audio/m.file/m.video body is just the uploaded filename (no caption)."""
  381. return _looks_like_transport_filename(text, ("audio/", "video/"), _MATRIX_MEDIA_FILENAME_EXTS, True)
  382. def _is_bare_media_filename(msgtype: str, body: str) -> bool:
  383. """True when a media event body is only the uploaded filename for its msgtype."""
  384. if msgtype == "m.image":
  385. return _looks_like_matrix_image_filename(body)
  386. return msgtype in ("m.audio", "m.file", "m.video") and _looks_like_matrix_media_filename(body)
  387. def _matrix_event_timestamp_seconds(event: Any) -> float:
  388. """Return a Matrix event timestamp in seconds, accepting ms or sec values."""
  389. try:
  390. ts = float(getattr(event, "timestamp", None) or getattr(event, "server_timestamp", None) or 0)
  391. except (TypeError, ValueError):
  392. return 0.0
  393. # origin_server_ts is ms; some SDK objects/fakes expose seconds — keep both sane.
  394. return ts / 1000.0 if ts > 10_000_000_000 else ts
  395. def _create_matrix_session(proxy_url: str | None):
  396. """ClientSession whose proxy applies to *all* requests: mautrix's ``HTTPAPI._send()`` never
  397. forwards per-request ``proxy=``, so it must be session-level (``proxy=`` for HTTP(S),
  398. ``ProxyConnector`` for SOCKS); with no proxy, ``trust_env`` honours HTTP(S)_PROXY."""
  399. import aiohttp
  400. if not proxy_url:
  401. return aiohttp.ClientSession(trust_env=gateway_trust_env())
  402. if proxy_url.split("://")[0].lower().startswith("socks"):
  403. try:
  404. from aiohttp_socks import ProxyConnector
  405. return aiohttp.ClientSession(connector=ProxyConnector.from_url(proxy_url, rdns=True))
  406. except ImportError:
  407. logger.warning(
  408. "aiohttp_socks not installed — SOCKS proxy %s ignored. Run: pip install aiohttp-socks", proxy_url)
  409. return aiohttp.ClientSession(trust_env=gateway_trust_env())
  410. return aiohttp.ClientSession(proxy=proxy_url)
  411. def _check_e2ee_deps() -> bool:
  412. """True if all four E2EE deps import: olm, PgCryptoStore (also drives sqlite), asyncpg, aiosqlite.
  413. Without all four, encrypted rooms fail at connect with ``No module named 'asyncpg'``.
  414. Verifies python-olm (via mautrix.crypto.OlmMachine), the SQLite crypto store backend
  415. (mautrix.crypto.store.asyncpg.PgCryptoStore — yes, the PgCryptoStore class also drives the sqlite
  416. backend in mautrix 0.21), and the database drivers actually used at connect time (``asyncpg`` for the
  417. underlying upgrade_table machinery, ``aiosqlite`` for the ``sqlite:///`` URL we pass to
  418. ``Database.create``). See #31116.
  419. """
  420. try:
  421. from mautrix.crypto import OlmMachine
  422. from mautrix.crypto.store.asyncpg import PgCryptoStore
  423. import asyncpg
  424. import aiosqlite
  425. return True
  426. except (ImportError, AttributeError):
  427. return False
  428. def _normalize_e2ee_mode(value: Any) -> str:
  429. raw = str(value or "").strip().lower()
  430. if raw in ("required", "require", "true", "1", "yes", "on"):
  431. return "required"
  432. if raw in ("optional", "prefer", "preferred"):
  433. return "optional"
  434. return "off"
  435. def _resolve_e2ee_mode(extra: Optional[dict[str, Any]] = None) -> str:
  436. """Resolve E2EE mode with MATRIX_ENCRYPTION backwards compatibility."""
  437. extra = extra or {}
  438. explicit = extra.get("e2ee_mode") or _get_scoped_secret("MATRIX_E2EE_MODE", "")
  439. if explicit:
  440. return _normalize_e2ee_mode(explicit)
  441. legacy_enabled = extra.get("encryption", _env_truthy("MATRIX_ENCRYPTION"))
  442. return "required" if legacy_enabled else "off"
  443. def _env_truthy(name: str, default: str = "") -> bool:
  444. """Return True when the env var is one of true/1/yes (case-insensitive)."""
  445. return str(_get_scoped_secret(name, default)).lower() in ("true", "1", "yes")
  446. def _env_number(name: str, default, cast):
  447. """Parse a numeric env var, falling back to *default* on ValueError."""
  448. try:
  449. return cast(_get_scoped_secret(name, str(default)))
  450. except ValueError:
  451. return default
  452. def _csv_set(raw: Any) -> set[str]:
  453. """Normalize a comma-separated string or list into a set of stripped tokens."""
  454. if isinstance(raw, list):
  455. return {str(r).strip() for r in raw if str(r).strip()}
  456. return {r.strip() for r in str(raw).split(",") if r.strip()}
  457. def _thread_root(relates_to: dict) -> Optional[str]:
  458. """The m.thread root event_id an event belongs to, else None."""
  459. return relates_to.get("event_id") if relates_to.get("rel_type") == "m.thread" else None
  460. def _extra_csv_set(config, key: str, env_name: str) -> set[str]:
  461. """Resolve a room/user list: scoped env var → config.extra[key] → empty."""
  462. return _csv_set(_extra_or_secret(config.extra, key, env_name, "", blank_is_unset=False))
  463. def _recovery_key_output_path() -> Optional[Path]:
  464. """MATRIX_RECOVERY_KEY_OUTPUT_FILE via the profile-scoped reader: a bare os.getenv under
  465. multiplex resolves the default profile's path, writing/finding the wrong profile's file."""
  466. output_file = _get_scoped_secret("MATRIX_RECOVERY_KEY_OUTPUT_FILE", "").strip()
  467. return Path(output_file).expanduser() if output_file else None
  468. def _write_matrix_recovery_key_output_file(recovery_key: str) -> Optional[Path]:
  469. """Write a generated recovery key to MATRIX_RECOVERY_KEY_OUTPUT_FILE (0600, never overwritten)."""
  470. path = _recovery_key_output_path()
  471. if path is None:
  472. return None
  473. path.parent.mkdir(parents=True, exist_ok=True)
  474. fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
  475. try:
  476. with os.fdopen(fd, "w", encoding="utf-8") as fh:
  477. fh.write(recovery_key)
  478. fh.write("\n")
  479. except Exception:
  480. with suppress(OSError):
  481. os.close(fd)
  482. raise
  483. return path
  484. def _get_matrix_recovery_key_output_target() -> tuple[Optional[Path], str]:
  485. """Return a usable one-time recovery-key output path, or a redacted reason."""
  486. path = _recovery_key_output_path()
  487. if path is None:
  488. return None, "not_configured"
  489. if path.exists():
  490. return None, "exists"
  491. try:
  492. path.parent.mkdir(parents=True, exist_ok=True)
  493. except Exception as exc:
  494. return None, f"unusable: {exc}"
  495. return path, ""
  496. def _handle_generated_matrix_recovery_key(mxid: str, recovery_key: str) -> None:
  497. """Handle a freshly generated Matrix recovery key without logging it."""
  498. try:
  499. output_path = _write_matrix_recovery_key_output_file(recovery_key)
  500. except FileExistsError:
  501. logger.warning(
  502. "Matrix: bootstrapped cross-signing for %s. Recovery key output file "
  503. "already exists; refusing to overwrite. Store the generated key "
  504. "securely and set MATRIX_RECOVERY_KEY for future restarts.", mxid)
  505. return
  506. except Exception as exc:
  507. logger.warning(
  508. "Matrix: bootstrapped cross-signing for %s, but failed to write "
  509. "MATRIX_RECOVERY_KEY_OUTPUT_FILE: %s. Store the generated key "
  510. "securely and set MATRIX_RECOVERY_KEY for future restarts.", mxid, exc)
  511. return
  512. if output_path:
  513. logger.warning(
  514. "Matrix: bootstrapped cross-signing for %s. A new recovery key was written to %s with mode 0600. Move it "
  515. "to your secret store and set MATRIX_RECOVERY_KEY for future restarts.",
  516. mxid, output_path)
  517. else:
  518. logger.warning(
  519. "Matrix: bootstrapped cross-signing for %s. A new recovery key was generated but will "
  520. "not be logged. Set MATRIX_RECOVERY_KEY_OUTPUT_FILE to write it once with mode 0600, "
  521. "or configure MATRIX_RECOVERY_KEY from your Matrix client before future restarts.",
  522. mxid)
  523. def _scoped_recovery_key() -> str:
  524. """MATRIX_RECOVERY_KEY via the profile-scoped reader: a bare os.getenv under multiplex resolves
  525. the default profile's key and verification fails with "Key MAC does not match"."""
  526. return _get_scoped_secret("MATRIX_RECOVERY_KEY", "").strip()
  527. # --- LaTeX math ($...$, $$...$$) -> Element data-mx-maths markup ---
  528. # Element (feature_latex_maths) typesets <div|span data-mx-maths="TEX"> at display time.
  529. # Our sanitizer allowlists tags/attrs, so data-mx-maths cannot pass through HTML
  530. # sanitization directly. Instead, math is swapped for opaque sentinel tokens before
  531. # Markdown conversion (protecting TeX from escaping) and expanded back to math
  532. # markup after sanitization. Tokens are plain printable text with no special
  533. # HTML/Markdown meaning, so both the Markdown converter and the sanitizer
  534. # pass them through verbatim.
  535. _TEX_TOKEN_RE = re.compile(r"HERMESTEX(?:DISPLAY|INLINE)(\d+)HERMESTEXEND")
  536. _TEX_DISPLAY_TOKEN = "HERMESTEXDISPLAY%dHERMESTEXEND"
  537. _TEX_INLINE_TOKEN = "HERMESTEXINLINE%dHERMESTEXEND"
  538. def _latex_to_tokens(text: str) -> tuple[str, list[tuple[str, str]]]:
  539. """Replace ``$$...$$``/``$...$`` with sentinel tokens.
  540. Returns the tokenized text plus an ordered ``(tag, tex)`` store, where tag
  541. is ``div`` for display math and ``span`` for inline math. Dollars that do
  542. not form a pair (prices, literals) are left untouched.
  543. """
  544. if not text or "$" not in text:
  545. return text, []
  546. store: list[tuple[str, str]] = []
  547. def _sub_display(match: re.Match[str]) -> str:
  548. store.append(("div", match.group(1).strip()))
  549. return _TEX_DISPLAY_TOKEN % (len(store) - 1)
  550. def _sub_inline(match: re.Match[str]) -> str:
  551. store.append(("span", match.group(1).strip()))
  552. return _TEX_INLINE_TOKEN % (len(store) - 1)
  553. text = re.sub(r"\$\$([^\n$]+?)\$\$", _sub_display, text)
  554. text = re.sub(r"(?<![\\$\w])\$([^\n$]+?)\$(?!\w)", _sub_inline, text)
  555. return text, store
  556. def _tokens_to_mx_maths(html: str, store: list[tuple[str, str]]) -> str:
  557. """Expand sentinel tokens into ``data-mx-maths`` markup (TeX HTML-escaped)."""
  558. def _expand(match: re.Match[str]) -> str:
  559. idx = int(match.group(1))
  560. if idx >= len(store):
  561. # Not one of our tokens (user-typed text that collides with the
  562. # sentinel format) — leave it verbatim.
  563. return match.group(0)
  564. tag, tex = store[idx]
  565. escaped = _html_escape(tex, quote=True)
  566. return f'<{tag} data-mx-maths="{escaped}">{escaped}</{tag}>'
  567. return _TEX_TOKEN_RE.sub(_expand, html)
  568. def _sanitize_matrix_html(html: str) -> str:
  569. sanitizer = _MatrixHtmlSanitizer()
  570. try:
  571. sanitizer.feed(html or "")
  572. sanitizer.close()
  573. return sanitizer.get_html()
  574. except Exception:
  575. return _html_escape(html or "")
  576. def _redact_url_for_log(url: str) -> str:
  577. """Strip query/fragment from URLs before logging signed media links."""
  578. try:
  579. parts = urlsplit(str(url))
  580. if not parts.scheme and not parts.netloc:
  581. return str(url).split("?", 1)[0].split("#", 1)[0]
  582. return urlunsplit((parts.scheme, parts.netloc, parts.path, "", ""))
  583. except Exception:
  584. return "<url>"
  585. def _pre_sanitize_matrix_markdown(text: str) -> str:
  586. """Remove unsafe raw HTML before Markdown conversion can escape it."""
  587. result = re.sub(r"(?is)<\s*(script|style)\b[^>]*>.*?<\s*/\s*\1\s*>", "", text or "")
  588. result = re.sub(r"""(?is)\s+on[a-z0-9_-]+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)""", "", result)
  589. return re.sub(
  590. r"""(?is)\s+(href|src)\s*=\s*("[^"]*(?:javascript|data|vbscript):[^"]*"|'[^']*(?:javascript|data|vbscript):[^']*'|[^\s>]*(?:javascript|data|vbscript):[^\s>]*)""",
  591. "", result)
  592. def matrix_deps_present() -> bool:
  593. """PASSIVE registry ``check_fn`` — must never install; ``ensure_matrix_deps`` is the installer.
  594. Registry ``check_fn`` — called from status displays and config loading, so it must never install
  595. anything. The ACTIVE lazy-installer (``check_matrix_requirements``) is registered as ``ensure_deps_fn``
  596. and runs from ``create_adapter()`` when this returns False (#79812).
  597. """
  598. try:
  599. from pm import available as is_available
  600. return is_available("matrix")
  601. except Exception: # pragma: no cover — defensive
  602. return False
  603. def check_matrix_requirements() -> bool:
  604. """Credentials + deps answer for setup/status callers (credentials must NOT gate the installer)."""
  605. token = _get_scoped_secret("MATRIX_ACCESS_TOKEN", "").strip()
  606. password = _get_scoped_secret("MATRIX_PASSWORD", "").strip()
  607. homeserver = _get_scoped_secret("MATRIX_HOMESERVER", "").strip()
  608. if not token and not password:
  609. logger.debug("Matrix: neither MATRIX_ACCESS_TOKEN nor MATRIX_PASSWORD set")
  610. return False
  611. if not homeserver:
  612. logger.warning("Matrix: MATRIX_HOMESERVER not set")
  613. return False
  614. return ensure_matrix_deps()
  615. def ensure_matrix_deps() -> bool:
  616. """ACTIVE deps-only installer (registry ``ensure_deps_fn``); rebinds the type globals. Installs the
  617. whole ``platform.matrix`` group when ANY declared package is missing — short-circuiting on
  618. ``import mautrix`` left asyncpg/aiosqlite uninstalled forever.
  619. Lazy-installs the full ``platform.matrix`` feature group via
  620. ``pm.extras.ensure_and_bind`` whenever any of the declared
  621. packages (mautrix, Markdown, aiosqlite, asyncpg, aiohttp-socks) is
  622. missing — not just mautrix itself. Previously this short-circuited on
  623. ``import mautrix``, which left the other four packages uninstalled
  624. forever and broke E2EE connect with ``No module named 'asyncpg'``
  625. (#31116). Rebinds module-level type globals on success.
  626. """
  627. from pm import extras
  628. def _import():
  629. from mautrix.types import (
  630. ContentURI, EventID, EventType, PresenceState, RoomCreatePreset, RoomID, TrustState, UserID)
  631. return {
  632. "ContentURI": ContentURI,
  633. "EventID": EventID,
  634. "EventType": EventType,
  635. "PresenceState": PresenceState,
  636. "RoomCreatePreset": RoomCreatePreset,
  637. "RoomID": RoomID,
  638. "TrustState": TrustState,
  639. "UserID": UserID,
  640. }
  641. # A complete install (module-level imports already bound the types) needs no sync; only a
  642. # partial one goes through ensure_and_bind, which rebinds after the install.
  643. if extras.missing("matrix") and not extras.ensure_and_bind("matrix", _import, globals()):
  644. logger.warning(
  645. "Matrix: required packages not installed or need a restart. "
  646. "Run `hermes pm install`, then restart Hermes."
  647. )
  648. return False
  649. e2ee_mode = _resolve_e2ee_mode()
  650. if e2ee_mode == "required" and not _check_e2ee_deps():
  651. logger.error(
  652. "Matrix: E2EE is required but dependencies are missing. %s. Without this, encrypted "
  653. "rooms will not work. Set MATRIX_E2EE_MODE=off to disable E2EE.",
  654. _E2EE_INSTALL_HINT)
  655. return False
  656. if e2ee_mode == "optional" and not _check_e2ee_deps():
  657. logger.warning("Matrix: E2EE optional but dependencies are missing. %s", _E2EE_INSTALL_HINT)
  658. return True
  659. class MatrixAdapter(BasePlatformAdapter):
  660. """Gateway adapter for Matrix (any homeserver)."""
  661. serial_receive_loop = True # _sync_loop reads the next sync only after this sync's handlers return
  662. supports_code_blocks = True # Matrix renders fenced code blocks (HTML/markdown)
  663. splits_long_messages = True # send() chunks via truncate_message(max_message_length)
  664. typed_command_prefix = "!" # clients reserve typed "/" for local commands; "!command" always reaches Hermes
  665. # Class-level defaults keep object.__new__-built test instances working.
  666. max_message_length = DEFAULT_MAX_MESSAGE_LENGTH
  667. _SPLIT_THRESHOLD = DEFAULT_MAX_MESSAGE_LENGTH - 100
  668. @property
  669. def message_len_fn(self):
  670. """UTF-8 bytes, the unit of the homeserver's event cap (a CJK character is three)."""
  671. return _utf8_len
  672. def _resolve_store_dir(self) -> Path:
  673. """Pin the crypto-store dir to the active profile (connect() runs inside the profile
  674. scope); cached so later out-of-scope reads report the store actually in use."""
  675. self._store_dir = _get_hermes_dir("platforms/matrix/store", "matrix/store")
  676. return self._store_dir
  677. @property
  678. def _crypto_db_path(self) -> Path:
  679. return (self._store_dir or _get_hermes_dir("platforms/matrix/store", "matrix/store")) / "crypto.db"
  680. def __init__(self, config: PlatformConfig):
  681. super().__init__(config, Platform.MATRIX)
  682. self.max_message_length = _resolve_max_message_length(config)
  683. self.MAX_MESSAGE_LENGTH = self.max_message_length # mirrors other adapters for tooling
  684. # A chunk near the outbound limit almost certainly has a continuation.
  685. self._SPLIT_THRESHOLD = max(100, self.max_message_length - 100)
  686. # Homeserver/user_id/device_id go through the same scoped reader as the token/password:
  687. # under multiplex os.environ holds the DEFAULT profile's identity, and pairing it with a
  688. # secondary's credential sends that credential to the wrong homeserver (or reuses the
  689. # default's E2EE device id).
  690. self._homeserver: str = (config.extra.get("homeserver", "") or _get_scoped_secret("MATRIX_HOMESERVER", "").strip()).rstrip("/")
  691. self._access_token: str = config.token or _get_scoped_secret("MATRIX_ACCESS_TOKEN", "").strip()
  692. self._user_id: str = config.extra.get("user_id", "") or _get_scoped_secret("MATRIX_USER_ID", "").strip()
  693. self._password: str = config.extra.get("password", "") or _get_scoped_secret("MATRIX_PASSWORD", "").strip()
  694. self._e2ee_mode: str = _resolve_e2ee_mode(config.extra)
  695. self._encryption: bool = self._e2ee_mode != "off"
  696. self._device_id: str = config.extra.get("device_id", "") or _get_scoped_secret("MATRIX_DEVICE_ID", "").strip()
  697. self._device_id_unverified: bool = False
  698. self._client: Any = None # mautrix.client.Client
  699. self._crypto_db: Any = None # mautrix.util.async_db.Database
  700. self._store_dir: Optional[Path] = None # pinned per profile in connect()
  701. self._sync_task: Optional[asyncio.Task] = None
  702. self._invite_join_tasks: dict[str, asyncio.Task] = {}
  703. self._closing = False
  704. self._startup_ts: float = 0.0
  705. self._reset_clock_skew_detector()
  706. self._last_sync_ts: float = 0.0
  707. self._dm_rooms: dict[str, bool] = {}
  708. self._room_identities: dict[str, MatrixRoomIdentity] = {}
  709. self._room_identity_cached_at: dict[str, float] = {}
  710. self._room_identity_ttl_seconds = _env_number("MATRIX_ROOM_IDENTITY_TTL_SECONDS", 60.0, float)
  711. self._room_identity_cache_max = 256
  712. self._joined_rooms: set[str] = set()
  713. from collections import deque
  714. self._processed_events: deque = deque(maxlen=1000) # event dedup, newest kept
  715. self._processed_events_set: set = set()
  716. # Rooms already warned for dropping encrypted events this process lifetime (#131778).
  717. self._warned_encrypted_drop_rooms: set[str] = set()
  718. self._threads = ThreadParticipationTracker("matrix") # require_mention bypass
  719. self._parked_voices = ParkedVoices() # unmentioned voice awaiting a bare @mention
  720. self._require_mention: bool = self._parse_require_mention(config)
  721. self._thread_require_mention: bool = self._parse_thread_require_mention(config)
  722. self._free_rooms: set[str] = _extra_csv_set(config, "free_response_rooms", "MATRIX_FREE_RESPONSE_ROOMS")
  723. # If non-empty, bot ONLY responds in these rooms (whitelist); DMs exempt.
  724. self._allowed_rooms: set[str] = _extra_csv_set(config, "allowed_rooms", "MATRIX_ALLOWED_ROOMS")
  725. self._allow_room_mentions: bool = _env_truthy("MATRIX_ALLOW_ROOM_MENTIONS", "false")
  726. # Extra-first: the YAML bridge seeds these into extra and skips the env write under a
  727. # multiplexed secondary scope, where os.environ holds the DEFAULT profile's flags.
  728. self._auto_thread: bool = self._extra_truthy(config, "auto_thread", "MATRIX_AUTO_THREAD", "true")
  729. self._dm_auto_thread: bool = _env_truthy("MATRIX_DM_AUTO_THREAD", "false")
  730. self._dm_mention_threads: bool = self._extra_truthy(config, "dm_mention_threads", "MATRIX_DM_MENTION_THREADS", "false")
  731. raw_session_scope = str(_extra_or_secret(config.extra, "session_scope", "MATRIX_SESSION_SCOPE", "auto")).strip().lower()
  732. self._matrix_session_scope = raw_session_scope if raw_session_scope in {"auto", "room", "thread"} else "auto"
  733. self._process_notices: bool = self._extra_truthy(config, "process_notices", "MATRIX_PROCESS_NOTICES", "false")
  734. self._reactions_enabled: bool = str(_extra_or_secret(config.extra, "reactions", "MATRIX_REACTIONS", "true")).lower() not in {"false", "0", "no"}
  735. self._pending_reactions: dict[tuple[str, str], str] = {}
  736. # Let the final message land before redacting reactions ("missing event" in some
  737. # clients). 5s is empirically safe; if it must be tunable, use config.yaml not env.
  738. self._reaction_redaction_delay_seconds = 5.0
  739. self._reaction_redaction_tasks: set[asyncio.Task] = set()
  740. self._proxy_url: str | None = resolve_proxy_url(platform_env_var="MATRIX_PROXY")
  741. if self._proxy_url:
  742. logger.info("Matrix: proxy configured — %s", self._proxy_url)
  743. self._max_media_bytes = _env_number("MATRIX_MAX_MEDIA_BYTES", 100 * 1024 * 1024, int)
  744. # Text batching merges client-side splits (~4000 chars) of one long message.
  745. self._text_batch_delay_seconds = float(os.getenv("HERMES_MATRIX_TEXT_BATCH_DELAY_SECONDS", "0.6"))
  746. self._text_batch_split_delay_seconds = float(os.getenv("HERMES_MATRIX_TEXT_BATCH_SPLIT_DELAY_SECONDS", "2.0"))
  747. self._approval_reaction_map = {
  748. "✅": "once", "🌀": "session", "♾️": "always", "♾": "always", "\u267e\ufe0f": "always",
  749. "\u267e": "always", "❌": "deny", "❎": "deny"}
  750. self._approval_prompts_by_event: dict[str, _MatrixApprovalPrompt] = {}
  751. self._approval_prompt_by_session: dict[str, str] = {}
  752. self._approval_require_sender: bool = _env_truthy("MATRIX_APPROVAL_REQUIRE_SENDER", "true")
  753. self._approval_timeout_seconds = _env_number("MATRIX_APPROVAL_TIMEOUT_SECONDS", 300, int)
  754. self._model_picker_prompts_by_event: dict[str, _MatrixPickerPrompt] = {}
  755. self._choice_picker_prompts_by_event: dict[str, _MatrixPickerPrompt] = {}
  756. # Authz lists: scoped env → this profile's YAML (``allowed_users`` / ``ignore_user_patterns``,
  757. # seeded by the bridge) → empty. Under multiplex os.environ is the DEFAULT profile's allowlist,
  758. # which must not decide who approves tool calls on a secondary bot.
  759. self._allowed_user_ids: set[str] = _extra_csv_set(config, "allowed_users", "MATRIX_ALLOWED_USERS")
  760. self._allowed_room_ids: set[str] = set(self._allowed_rooms)
  761. self._ignored_user_patterns: list[re.Pattern[str]] = []
  762. for pattern in _csv_set(_extra_or_secret(config.extra, "ignore_user_patterns", "MATRIX_IGNORE_USER_PATTERNS", "")):
  763. try:
  764. self._ignored_user_patterns.append(re.compile(pattern))
  765. except re.error as exc:
  766. logger.warning("Matrix: ignoring invalid MATRIX_IGNORE_USER_PATTERNS entry %r: %s", pattern, exc)
  767. def _is_duplicate_event(self, event_id) -> bool:
  768. """Return True if this event was already processed. Tracks the ID otherwise."""
  769. if not event_id:
  770. return False
  771. if event_id in self._processed_events_set:
  772. return True
  773. if len(self._processed_events) == self._processed_events.maxlen:
  774. self._processed_events_set.discard(self._processed_events[0])
  775. self._processed_events.append(event_id)
  776. self._processed_events_set.add(event_id)
  777. return False
  778. @staticmethod
  779. def _extra_truthy(config, key: str, env_name: str, default: str) -> bool:
  780. """Scoped env var → ``config.extra[key]`` (YAML, per profile) → ``default``; true/1/yes semantics."""
  781. configured = _extra_or_secret(config.extra, key, env_name, default)
  782. return configured if isinstance(configured, bool) else str(configured).lower() in ("true", "1", "yes")
  783. @staticmethod
  784. def _configured_bool(config, key: str) -> Optional[bool]:
  785. """Parse a YAML bool / "true"/"off"-style string from config.extra; None if unset."""
  786. configured = config.extra.get(key)
  787. if configured is None:
  788. return None
  789. if isinstance(configured, bool):
  790. return configured
  791. if isinstance(configured, str):
  792. return configured.lower() not in {"false", "0", "no", "off"}
  793. return bool(configured)
  794. @staticmethod
  795. def _parse_require_mention(config) -> bool:
  796. """MATRIX_REQUIRE_MENTION (scoped) → ``require_mention`` in config.extra → true."""
  797. configured = _extra_or_secret(config.extra, "require_mention", "MATRIX_REQUIRE_MENTION", True)
  798. return configured if isinstance(configured, bool) else str(configured).lower() not in {"false", "0", "no", "off"}
  799. @staticmethod
  800. def _parse_thread_require_mention(config) -> bool:
  801. """MATRIX_THREAD_REQUIRE_MENTION (scoped) → ``thread_require_mention`` in config.extra → false."""
  802. configured = _extra_or_secret(config.extra, "thread_require_mention", "MATRIX_THREAD_REQUIRE_MENTION", False)
  803. return configured if isinstance(configured, bool) else str(configured).lower() not in {"false", "0", "no", "off"}
  804. @staticmethod
  805. def _extract_server_ed25519(device_keys_obj: Any) -> Optional[str]:
  806. for kid, kval in (getattr(device_keys_obj, "keys", {}) or {}).items():
  807. if str(kid).startswith("ed25519:"):
  808. return str(kval)
  809. return None
  810. @staticmethod
  811. async def _query_own_device_keys(client: Any):
  812. """query_keys for our own device; the DeviceKeys entry or None."""
  813. resp = await client.query_keys({client.mxid: [client.device_id]})
  814. our_user_devices = (getattr(resp, "device_keys", {}) or {}).get(str(client.mxid)) or {}
  815. return our_user_devices.get(str(client.device_id))
  816. async def _reverify_keys_after_upload(self, client: Any, local_ed25519: str) -> bool:
  817. """Re-query the server after share_keys() and verify our ed25519 key matches."""
  818. if not client.device_id or self._device_id_unverified:
  819. logger.warning("Matrix: skipping post-upload key verification — device_id not yet established")
  820. return True
  821. try:
  822. dev = await self._query_own_device_keys(client)
  823. if dev and self._extract_server_ed25519(dev) != local_ed25519:
  824. logger.error(
  825. "Matrix: device %s has immutable identity keys that don't match this "
  826. "installation. Generate a new access token with a fresh device.", client.device_id)
  827. return False
  828. except Exception as exc:
  829. logger.error("Matrix: post-upload key verification failed: %s", exc, exc_info=True)
  830. return False
  831. return True
  832. async def _reset_crypto_store_if_device_changed(self, crypto_store: Any, device_id: str) -> bool:
  833. """Reset the Olm account when the token's device changed; True if reset. The store is keyed
  834. by user ID, so a new device would inherit the old Olm account whose identity keys can never
  835. be published under the new device ID."""
  836. if not device_id:
  837. return False
  838. try:
  839. stored_device_id = await crypto_store.get_device_id()
  840. except Exception as exc:
  841. logger.warning("Matrix: could not read stored device ID: %s", exc)
  842. return False
  843. if not stored_device_id or stored_device_id == device_id:
  844. return False
  845. logger.warning(
  846. "Matrix: access token belongs to a new device (%s -> %s) — resetting local Olm account "
  847. "so fresh identity keys are generated for this device", stored_device_id, device_id)
  848. await crypto_store.delete()
  849. return True
  850. async def _migrate_legacy_crypto_pickle(
  851. self, crypto_store: Any, crypto_db: Any, acct_id: str, pickle_key: str) -> bool:
  852. """Re-pickle the Olm account under the current pickle key when it changed. The key embeds the
  853. device ID; an account created before MATRIX_DEVICE_ID was set lives under ``<acct>:default``
  854. and later fails with BAD_ACCOUNT_KEY (silently disabling optional E2EE). False only when an
  855. account exists but no key opens it."""
  856. with suppress(Exception):
  857. await crypto_store.get_account()
  858. return True
  859. from mautrix.crypto.store.asyncpg import PgCryptoStore
  860. for legacy_key in (f"{acct_id}:default", acct_id):
  861. if legacy_key == pickle_key:
  862. continue
  863. try:
  864. account = await PgCryptoStore(account_id=acct_id, pickle_key=legacy_key, db=crypto_db).get_account()
  865. except Exception:
  866. account = None
  867. if account is None:
  868. continue
  869. # Sessions first, account last: the account is the commit marker (the fast path
  870. # above short-circuits once it reads), so an interrupted sweep is retried.
  871. try:
  872. await self._repickle_crypto_sessions(crypto_db, acct_id, legacy_key, pickle_key)
  873. except Exception as exc:
  874. logger.error(
  875. "Matrix: pickle key migration failed while re-pickling sessions (%s) — leaving "
  876. "the account under the legacy key so the migration is retried on the next start.", exc)
  877. return False
  878. await crypto_store.put_account(account)
  879. logger.info(
  880. "Matrix: re-pickled crypto store account and sessions under the current pickle key "
  881. "(device ID was configured after the account was created)")
  882. return True
  883. logger.error(
  884. "Matrix: crypto store account exists but cannot be unpickled with the current or any "
  885. "legacy pickle key. If MATRIX_DEVICE_ID was changed manually, restore its previous value.")
  886. return False
  887. async def _repickle_crypto_sessions(self, crypto_db: Any, acct_id: str, legacy_key: str, pickle_key: str) -> None:
  888. """Re-pickle olm/megolm sessions too — they share the key; account-only breaks key sharing."""
  889. import olm as olm_lib
  890. tables = {
  891. "crypto_olm_session": olm_lib.Session, "crypto_megolm_inbound_session": olm_lib.InboundGroupSession,
  892. "crypto_megolm_outbound_session": olm_lib.OutboundGroupSession}
  893. for table, session_cls in tables.items():
  894. rows = await crypto_db.fetch(f"SELECT session_id, session FROM {table} WHERE account_id=$1", acct_id)
  895. for row in rows:
  896. if row["session"] is None:
  897. continue
  898. pickled = bytes(row["session"])
  899. with suppress(Exception):
  900. session_cls.from_pickle(pickled, pickle_key)
  901. continue # already readable with the current key
  902. try:
  903. session = session_cls.from_pickle(pickled, legacy_key)
  904. except Exception as exc:
  905. # Readable under neither key: leave it inert rather than delete crypto material.
  906. logger.warning(
  907. "Matrix: %s row %s cannot be unpickled with the current or legacy key; leaving "
  908. "it in place, its sessions are unrecoverable: %s", table, row["session_id"], exc)
  909. continue
  910. await crypto_db.execute(
  911. f"UPDATE {table} SET session=$1 WHERE account_id=$2 AND session_id=$3",
  912. session.pickle(pickle_key), acct_id, row["session_id"])
  913. async def _verify_device_keys_on_server(self, client: Any, olm: Any) -> bool:
  914. """True if our device keys are on the server (or were re-uploaded); False ⇒ refuse E2EE."""
  915. if not client.device_id or self._device_id_unverified:
  916. logger.warning("Matrix: skipping device key verification — device_id not yet established")
  917. return True
  918. try:
  919. our_keys = await self._query_own_device_keys(client)
  920. except Exception as exc:
  921. logger.error("Matrix: cannot verify device keys on server: %s — refusing E2EE", exc, exc_info=True)
  922. return False
  923. local_ed25519 = olm.account.identity_keys.get("ed25519")
  924. async def _reupload(error_fmt: str, *error_args) -> bool:
  925. try:
  926. await olm.share_keys()
  927. except Exception as exc:
  928. logger.error(error_fmt, *error_args, exc, exc_info=True)
  929. return False
  930. return await self._reverify_keys_after_upload(client, local_ed25519)
  931. if not our_keys:
  932. logger.warning("Matrix: device keys missing from server — re-uploading")
  933. olm.account.shared = False
  934. return await _reupload("Matrix: failed to re-upload device keys: %s")
  935. if self._extract_server_ed25519(our_keys) == local_ed25519:
  936. return True
  937. if olm.account.shared:
  938. logger.error(
  939. "Matrix: server has different identity keys for device %s — local crypto state is "
  940. "stale. Delete %s and restart.", client.device_id, str(self._crypto_db_path))
  941. return False
  942. logger.warning("Matrix: server has stale keys for device %s — attempting re-upload", client.device_id)
  943. with suppress(Exception):
  944. await client.api.request(
  945. client.api.Method.DELETE if hasattr(client.api, "Method") else "DELETE",
  946. f"/_matrix/client/v3/devices/{client.device_id}")
  947. logger.info("Matrix: deleted stale device %s from server", client.device_id)
  948. return await _reupload(
  949. "Matrix: cannot upload device keys for %s: %s. Try generating a new access token to get a fresh device.",
  950. client.device_id)
  951. @staticmethod
  952. async def _abort_connect(api: Any, crypto_db: Any = None) -> bool:
  953. """Close what connect() opened so far; always False so callers can ``return await``."""
  954. if crypto_db is not None:
  955. await crypto_db.stop()
  956. await api.session.close()
  957. return False
  958. async def _connect_authenticate(self, client: Any, api: Any) -> bool:
  959. """Authenticate via access token (whoami) or password login; resolve user/device IDs."""
  960. if self._access_token:
  961. api.token = self._access_token
  962. try:
  963. resp = await client.whoami()
  964. resolved_user_id = getattr(resp, "user_id", "") or self._user_id
  965. resolved_device_id = str(getattr(resp, "device_id", "") or "")
  966. if resolved_user_id:
  967. self._user_id = str(resolved_user_id)
  968. client.mxid = UserID(self._user_id)
  969. # The configured device_id wins when whoami() reports none, but a token can
  970. # only upload keys for its own device — on conflict whoami() wins, loudly.
  971. if resolved_device_id and self._device_id and resolved_device_id != self._device_id:
  972. logger.error(
  973. "Matrix: MATRIX_DEVICE_ID=%s does not match the device this access token "
  974. "belongs to (%s). A token can only upload keys for its own device, so the "
  975. "configured value is being ignored. Unset MATRIX_DEVICE_ID, or use a token "
  976. "issued for %s.", self._device_id, resolved_device_id, self._device_id)
  977. effective_device_id = resolved_device_id
  978. else:
  979. effective_device_id = self._device_id or resolved_device_id
  980. if effective_device_id:
  981. client.device_id = effective_device_id
  982. if not client.device_id:
  983. try:
  984. dev_resp = await client.query_keys({client.mxid: []})
  985. all_devices = (getattr(dev_resp, "device_keys", {}) or {}).get(str(client.mxid)) or {}
  986. if len(all_devices) == 1:
  987. client.device_id = next(iter(all_devices))
  988. elif not all_devices:
  989. logger.warning(
  990. "Matrix: no devices found for %s — key verification will be skipped", client.mxid)
  991. except Exception as exc:
  992. logger.warning("Matrix: device list query failed: %s", exc)
  993. if not client.device_id:
  994. logger.warning(
  995. "Matrix: device_id could not be resolved for %s. Set MATRIX_DEVICE_ID for full "
  996. "key verification. E2EE will proceed without server-side device key confirmation.",
  997. client.mxid)
  998. self._device_id_unverified = True
  999. logger.info(
  1000. "Matrix: using access token for %s%s", self._user_id or "(unknown user)",
  1001. f" (device {effective_device_id})" if effective_device_id else "")
  1002. except Exception as exc:
  1003. logger.error(
  1004. "Matrix: whoami failed — check MATRIX_ACCESS_TOKEN and MATRIX_HOMESERVER: %s", exc, exc_info=True)
  1005. return await self._abort_connect(api)
  1006. elif self._password and self._user_id:
  1007. try:
  1008. resp = await client.login(
  1009. identifier=self._user_id, password=self._password, device_name="Hermes Agent",
  1010. device_id=self._device_id or None)
  1011. if resp and hasattr(resp, "device_id"):
  1012. client.device_id = resp.device_id
  1013. logger.info("Matrix: logged in as %s", self._user_id)
  1014. except Exception as exc:
  1015. logger.error("Matrix: login failed — %s", exc)
  1016. return await self._abort_connect(api)
  1017. else:
  1018. logger.error("Matrix: need MATRIX_ACCESS_TOKEN or MATRIX_USER_ID + MATRIX_PASSWORD")
  1019. return await self._abort_connect(api)
  1020. return True
  1021. async def _connect_setup_e2ee(self, client: Any, api: Any, state_store: Any) -> bool:
  1022. """Set up the Olm machine + crypto store. Returns False when connect must abort."""
  1023. if not _check_e2ee_deps():
  1024. if self._e2ee_mode == "optional":
  1025. logger.warning(
  1026. "Matrix: E2EE optional but dependencies are missing. Continuing without "
  1027. "encrypted-room support. %s", _E2EE_INSTALL_HINT)
  1028. self._encryption = False
  1029. else:
  1030. logger.error(
  1031. "Matrix: E2EE is required but dependencies are missing. %s. Refusing to connect — "
  1032. "encrypted rooms would silently fail.", _E2EE_INSTALL_HINT)
  1033. return await self._abort_connect(api)
  1034. if not self._encryption:
  1035. return True
  1036. phase = "import"
  1037. try:
  1038. from mautrix.crypto import OlmMachine
  1039. from mautrix.crypto.store.asyncpg import PgCryptoStore
  1040. from mautrix.util.async_db import Database
  1041. self._store_dir.mkdir(parents=True, exist_ok=True)
  1042. phase = "create"
  1043. if (self._store_dir / "crypto_store.pickle").exists(): # pre-SQLite era
  1044. logger.info("Matrix: removing legacy crypto_store.pickle (migrated to SQLite)")
  1045. (self._store_dir / "crypto_store.pickle").unlink()
  1046. crypto_db = Database.create(
  1047. f"sqlite:///{self._crypto_db_path}", upgrade_table=PgCryptoStore.upgrade_table)
  1048. await crypto_db.start()
  1049. self._crypto_db = crypto_db
  1050. _acct_id = self._user_id or "hermes"
  1051. # Key on the RESOLVED client.device_id (token's real device), not the configured
  1052. # one, or the Olm account is stored under a key that can never be looked up.
  1053. _pickle_key = f"{_acct_id}:{client.device_id or self._device_id or 'default'}"
  1054. crypto_store = PgCryptoStore(account_id=_acct_id, pickle_key=_pickle_key, db=crypto_db)
  1055. await crypto_store.open()
  1056. _store_was_reset = False
  1057. if client.device_id:
  1058. _store_was_reset = await self._reset_crypto_store_if_device_changed(crypto_store, client.device_id)
  1059. await crypto_store.put_device_id(client.device_id)
  1060. # A just-deleted store has no account to migrate.
  1061. if not _store_was_reset and not await self._migrate_legacy_crypto_pickle(
  1062. crypto_store, crypto_db, _acct_id, _pickle_key):
  1063. logger.warning("Matrix: crypto pickle migration failed — E2EE may not work correctly")
  1064. from plugins.platforms.matrix.adapter_crypto import _CryptoStateStore
  1065. crypto_state = _CryptoStateStore(state_store, self._joined_rooms, client)
  1066. olm = OlmMachine(client, crypto_store, crypto_state)
  1067. olm.share_keys_min_trust = TrustState.UNVERIFIED
  1068. olm.send_keys_min_trust = TrustState.UNVERIFIED
  1069. await olm.load()
  1070. if not await self._verify_device_keys_on_server(client, olm):
  1071. return await self._abort_connect(api, crypto_db)
  1072. try:
  1073. await olm.share_keys()
  1074. except Exception as exc:
  1075. if "already exists" in str(exc):
  1076. logger.error(
  1077. "Matrix: device %s has stale one-time keys on the server signed with a "
  1078. "previous identity key. Delete the device from the homeserver and restart, "
  1079. "or generate a new access token to get a fresh device ID.", client.device_id)
  1080. return await self._abort_connect(api, crypto_db)
  1081. logger.warning("Matrix: share_keys() warning during startup: %s", exc)
  1082. await self._verify_or_bootstrap_cross_signing(olm, client)
  1083. client.crypto = olm
  1084. logger.info(
  1085. "Matrix: E2EE enabled (store: %s%s)", str(self._crypto_db_path),
  1086. f", device_id={client.device_id}" if client.device_id else "")
  1087. except Exception as exc:
  1088. return await self._e2ee_setup_failed(phase, exc, api)
  1089. return True
  1090. async def _e2ee_setup_failed(self, what: str, exc: Exception, api: Any) -> bool:
  1091. """Optional mode: log + disable E2EE and return True; required mode: close + return False."""
  1092. if self._e2ee_mode == "optional":
  1093. logger.warning(
  1094. "Matrix: failed to %s optional E2EE client; continuing without encrypted-room "
  1095. "support: %s. %s", what, exc, _E2EE_INSTALL_HINT)
  1096. self._encryption = False
  1097. return True
  1098. logger.error("Matrix: failed to %s E2EE client: %s. %s", what, exc, _E2EE_INSTALL_HINT)
  1099. return await self._abort_connect(api)
  1100. async def _verify_or_bootstrap_cross_signing(self, olm: Any, client: Any) -> None:
  1101. """Verify cross-signing via MATRIX_RECOVERY_KEY, or bootstrap a new key (non-fatal)."""
  1102. # Honor the active profile's secret scope so a secondary profile under gateway.multiplex_profiles
  1103. # resolves its own recovery key instead of the default profile's (which fails E2EE verification with
  1104. # "Key MAC does not match", #69090).
  1105. recovery_key = _scoped_recovery_key()
  1106. if recovery_key:
  1107. try:
  1108. await olm.verify_with_recovery_key(recovery_key)
  1109. logger.info("Matrix: cross-signing verified via recovery key")
  1110. except Exception as exc:
  1111. logger.warning("Matrix: recovery key verification failed: %s", exc)
  1112. else:
  1113. try:
  1114. own_xsign = await olm.get_own_cross_signing_public_keys()
  1115. except Exception as exc:
  1116. own_xsign = None
  1117. logger.warning("Matrix: cross-signing key lookup failed: %s", exc)
  1118. if own_xsign is None:
  1119. _, output_error = _get_matrix_recovery_key_output_target()
  1120. if output_error:
  1121. reason = {
  1122. "not_configured": "is not configured. Configure MATRIX_RECOVERY_KEY from your Matrix client "
  1123. "or set MATRIX_RECOVERY_KEY_OUTPUT_FILE to write a new recovery key once "
  1124. "with mode 0600.",
  1125. "exists": "already exists and will not be overwritten.",
  1126. }.get(output_error, "is not usable: %s")
  1127. logger.warning(
  1128. "Matrix: cross-signing keys are missing, but automatic bootstrap is skipped because "
  1129. "MATRIX_RECOVERY_KEY_OUTPUT_FILE " + reason,
  1130. *([output_error] if output_error not in ("not_configured", "exists") else []))
  1131. else:
  1132. try:
  1133. new_recovery_key = await olm.generate_recovery_key()
  1134. _handle_generated_matrix_recovery_key(str(client.mxid), new_recovery_key)
  1135. except Exception as exc:
  1136. logger.warning(
  1137. "Matrix: cross-signing bootstrap failed (non-fatal — Element will show "
  1138. "'not verified by its owner'): %s", exc)
  1139. async def _connect_initial_sync(self, client: Any) -> None:
  1140. """Full initial sync: seed joined rooms, DM cache, and dispatch queued to-device events."""
  1141. try:
  1142. sync_data = await client.sync(timeout=10000, full_state=True)
  1143. if isinstance(sync_data, dict):
  1144. self._joined_rooms.clear()
  1145. await self._absorb_sync(client, sync_data, initial=True)
  1146. else:
  1147. logger.warning("Matrix: initial sync returned unexpected type %s", type(sync_data).__name__)
  1148. except Exception as exc:
  1149. logger.warning("Matrix: initial sync error: %s", exc)
  1150. async def connect(self, *, is_reconnect: bool = False) -> bool:
  1151. self._device_id_unverified = False
  1152. if self._client is not None:
  1153. try:
  1154. await self.disconnect()
  1155. except Exception as exc:
  1156. logger.warning("Matrix: error disconnecting before reconnect: %s", exc)
  1157. from mautrix.api import HTTPAPI
  1158. from mautrix.client import Client
  1159. from mautrix.client.state_store import MemoryStateStore, MemorySyncStore
  1160. if not self._homeserver:
  1161. logger.error("Matrix: homeserver URL not configured")
  1162. return False
  1163. # Resolved here, inside the profile scope, so multiplexed profiles never share it.
  1164. self._resolve_store_dir().mkdir(parents=True, exist_ok=True)
  1165. client_session = _create_matrix_session(self._proxy_url)
  1166. api = HTTPAPI(base_url=self._homeserver, token=self._access_token or "", client_session=client_session)
  1167. state_store = MemoryStateStore()
  1168. sync_store = MemorySyncStore()
  1169. client = Client(
  1170. mxid=UserID(self._user_id) if self._user_id else UserID(""), device_id=self._device_id or None,
  1171. api=api, state_store=state_store, sync_store=sync_store)
  1172. self._client = client
  1173. if not await self._connect_authenticate(client, api):
  1174. return False
  1175. if self._encryption and not await self._connect_setup_e2ee(client, api, state_store):
  1176. return False
  1177. from mautrix.client import InternalEventType as IntEvt
  1178. from mautrix.client.dispatcher import MembershipEventDispatcher
  1179. client.add_dispatcher(MembershipEventDispatcher) # without this INVITE never fires
  1180. client.add_event_handler(EventType.ROOM_MESSAGE, self._on_room_message, wait_sync=True)
  1181. client.add_event_handler(EventType.REACTION, self._on_reaction, wait_sync=True)
  1182. client.add_event_handler(IntEvt.INVITE, self._on_invite, wait_sync=True)
  1183. self._startup_ts = time.time()
  1184. self._reset_clock_skew_detector() # a reconnect after an NTP fix starts clean
  1185. self._closing = False
  1186. await self._connect_initial_sync(client)
  1187. if self._encryption and getattr(client, "crypto", None):
  1188. try:
  1189. await client.crypto.share_keys()
  1190. except Exception as exc:
  1191. logger.warning("Matrix: initial key share failed: %s", exc)
  1192. self._sync_task = asyncio.create_task(self._sync_loop())
  1193. self._mark_connected()
  1194. self._wire_plugin_handlers(self._client) # plugin-registered native handlers
  1195. return True
  1196. async def disconnect(self) -> None:
  1197. self._closing = True
  1198. if self._sync_task and not self._sync_task.done():
  1199. self._sync_task.cancel()
  1200. try:
  1201. await self._sync_task
  1202. except (asyncio.CancelledError, Exception):
  1203. pass
  1204. for tasks in (self._invite_join_tasks.values(), self._reaction_redaction_tasks):
  1205. pending = list(tasks)
  1206. for task in pending:
  1207. if not task.done():
  1208. task.cancel()
  1209. if pending:
  1210. await asyncio.gather(*pending, return_exceptions=True)
  1211. self._invite_join_tasks.clear()
  1212. self._reaction_redaction_tasks.clear()
  1213. if getattr(self, "_crypto_db", None):
  1214. try:
  1215. await self._crypto_db.stop()
  1216. except Exception as exc:
  1217. logger.debug("Matrix: could not close crypto DB on disconnect: %s", exc)
  1218. if self._client:
  1219. with suppress(Exception):
  1220. await self._client.api.session.close()
  1221. self._client = None
  1222. logger.info("Matrix: disconnected")
  1223. async def send(
  1224. self, chat_id: str, content: str, reply_to: Optional[str] = None,
  1225. metadata: Optional[dict[str, Any]] = None) -> SendResult:
  1226. if not content:
  1227. return SendResult(success=True)
  1228. last_event_id = None
  1229. for chunk in self.truncate_message(
  1230. self.format_message(content), self.max_message_length, len_fn=self.message_len_fn):
  1231. msg_content = self._build_text_message_content(chunk)
  1232. self._apply_relation_metadata(msg_content, reply_to=reply_to, metadata=metadata)
  1233. try:
  1234. last_event_id = await self._send_room_message(chat_id, msg_content)
  1235. logger.info("Matrix: sent event %s to %s", last_event_id, chat_id)
  1236. except Exception as exc:
  1237. if not (self._encryption and getattr(self._client, "crypto", None)):
  1238. logger.error("Matrix: failed to send to %s: %s", chat_id, exc)
  1239. return SendResult(success=False, error=str(exc))
  1240. try: # E2EE error: retry once after sharing keys
  1241. await self._client.crypto.share_keys()
  1242. last_event_id = await self._send_room_message(chat_id, msg_content)
  1243. logger.info("Matrix: sent event %s to %s (after key share)", last_event_id, chat_id)
  1244. except Exception as retry_exc:
  1245. logger.error("Matrix: failed to send to %s after retry: %s", chat_id, retry_exc)
  1246. return SendResult(success=False, error=str(retry_exc))
  1247. return SendResult(success=True, message_id=last_event_id)
  1248. async def _send_room_message(self, chat_id: str, msg_content: dict[str, Any]) -> str:
  1249. """Send one m.room.message event (45s cap) and return its event ID as str."""
  1250. event_id = await asyncio.wait_for(
  1251. self._client.send_message_event(RoomID(chat_id), EventType.ROOM_MESSAGE, msg_content), timeout=45)
  1252. return str(event_id)
  1253. async def create_handoff_thread(self, parent_chat_id: str, name: str) -> Optional[str]:
  1254. """Post a seed message and return its ``event_id`` as the handoff ``thread_id``. Matrix has
  1255. no create-thread API: a thread is the events whose ``m.relates_to``/``rel_type: m.thread``
  1256. point at a root event (Slack-style), and ``_apply_relation_metadata`` already threads later
  1257. sends off a supplied ``thread_id``. ``None`` when disconnected or the seed send failed.
  1258. In-thread replies keep the ROOM's chat_type (``dm``/``group``) in the session key — the
  1259. handoff watcher and the cron seeder mirror that shape rather than the shared ``thread`` slot."""
  1260. if self._client is None:
  1261. return None
  1262. result = await self.send(parent_chat_id, (name or "").strip() or t("platform.matrix.handoff.default_name"))
  1263. root = result.message_id if result.success else None
  1264. if not root:
  1265. return None
  1266. await self._threads.mark_async(str(root)) # replies in this thread bypass require_mention, like inbound roots
  1267. return str(root)
  1268. async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
  1269. identity = await self._resolve_room_identity(chat_id)
  1270. return {"name": identity.display_name, "type": "dm" if identity.chat_type == "dm" else "group"}
  1271. def get_diagnostics(self) -> dict[str, Any]:
  1272. now = time.time()
  1273. token_present = bool(self._access_token)
  1274. user_id = self._user_id or getattr(self._client, "mxid", "") or ""
  1275. device_id = self._device_id or getattr(self._client, "device_id", "") or ""
  1276. return {
  1277. "platform": "matrix", "homeserver": self._homeserver,
  1278. "auth": {
  1279. "access_token_present": token_present, "password_present": bool(self._password),
  1280. "token_preview": "***" if token_present else "", "user_id": user_id,
  1281. "device_id_present": bool(device_id), "device_id_preview": "***" if str(device_id or "").strip() else ""},
  1282. "sync": {
  1283. "connected": self._client is not None, "joined_room_count": len(self._joined_rooms),
  1284. "last_sync_age_seconds": max(0.0, now - self._last_sync_ts) if self._last_sync_ts else None},
  1285. "e2ee": {
  1286. "mode": self._e2ee_mode, "enabled": bool(self._encryption), "deps_available": _check_e2ee_deps(),
  1287. "crypto_store_path": str(self._crypto_db_path),
  1288. "recovery_key_configured": bool(_scoped_recovery_key().strip())},
  1289. "policy": {
  1290. "allowed_user_count": len(self._allowed_user_ids), "allowed_room_count": len(self._allowed_room_ids),
  1291. "ignored_user_pattern_count": len(self._ignored_user_patterns),
  1292. "require_mention": self._require_mention, "free_response_room_count": len(self._free_rooms),
  1293. "allow_room_mentions": self._allow_room_mentions, "process_notices": self._process_notices,
  1294. "allow_public_rooms": _env_truthy("MATRIX_ALLOW_PUBLIC_ROOMS")},
  1295. "media": {"max_media_bytes": self._max_media_bytes}}
  1296. async def _set_typing(self, chat_id: str, timeout: int) -> None:
  1297. if self._client:
  1298. with suppress(Exception):
  1299. await self._client.set_typing(RoomID(chat_id), timeout=timeout)
  1300. async def send_typing(self, chat_id: str, metadata: Optional[dict[str, Any]] = None) -> None:
  1301. await self._set_typing(chat_id, 30000)
  1302. async def stop_typing(self, chat_id: str) -> None:
  1303. await self._set_typing(chat_id, 0)
  1304. async def edit_message(self, chat_id: str, message_id: str, content: str, *, finalize: bool = False) -> SendResult:
  1305. formatted = self.format_message(content)
  1306. new_content = self._build_text_message_content(formatted)
  1307. msg_content: dict[str, Any] = {"msgtype": "m.text", "body": f"* {formatted}", "m.new_content": new_content}
  1308. if "m.mentions" in new_content:
  1309. msg_content["m.mentions"] = new_content["m.mentions"]
  1310. if "formatted_body" in new_content:
  1311. msg_content["format"] = "org.matrix.custom.html"
  1312. msg_content["formatted_body"] = f'* {new_content["formatted_body"]}'
  1313. msg_content["m.relates_to"] = {"rel_type": "m.replace", "event_id": message_id}
  1314. if _content_bytes(msg_content) > _MAX_CONTENT_BYTES:
  1315. # The top-level copy is only the fallback for clients without edit support (edit-aware
  1316. # clients render m.new_content); shorten it rather than double the event past the cap.
  1317. msg_content.pop("format", None)
  1318. msg_content.pop("formatted_body", None)
  1319. msg_content["body"] = ""
  1320. if _content_bytes(msg_content) > _MAX_CONTENT_BYTES:
  1321. # Many distinct mentions: the top-level list only drives this edit's notifications,
  1322. # while m.new_content keeps the full list, so the duplicate goes rather than the edit.
  1323. msg_content.pop("m.mentions", None)
  1324. room = _MAX_CONTENT_BYTES - _content_bytes(msg_content)
  1325. # JSON escaping grows a character at most sixfold (\u00XX).
  1326. fallback = formatted.encode("utf-8")[: max(0, room // 6)].decode("utf-8", "ignore")
  1327. msg_content["body"] = f"* {fallback}…"
  1328. return await self._send_content_event(chat_id, msg_content)
  1329. async def send_image(
  1330. self, chat_id: str, image_url: str, caption: Optional[str] = None, reply_to: Optional[str] = None,
  1331. metadata: Optional[dict[str, Any]] = None) -> SendResult:
  1332. from tools.url_safety import is_safe_url
  1333. if not is_safe_url(image_url):
  1334. logger.warning("Matrix: blocked unsafe image URL (SSRF protection)")
  1335. return await super().send_image(chat_id, image_url, caption, reply_to, metadata=metadata)
  1336. try:
  1337. data, ct, fname = await self._download_external_media_with_cap(image_url)
  1338. except Exception as exc:
  1339. logger.warning("Matrix: failed to download image %s: %s", _redact_url_for_log(image_url), exc)
  1340. fallback = t("platform.matrix.media.image_download_failed")
  1341. return await self.emit_media_warning(chat_id, fallback, caption=caption, reply_to=reply_to, metadata=metadata)
  1342. return await self._upload_and_send(chat_id, data, fname, ct, "m.image", caption, reply_to, metadata)
  1343. async def _download_external_media_with_cap(self, url: str) -> tuple[bytes, str, str]:
  1344. """Download external media while enforcing redirect safety and size caps."""
  1345. from tools.url_safety import is_safe_url
  1346. if not is_safe_url(url):
  1347. raise ValueError("blocked unsafe media URL")
  1348. async def _read_capped(resp, chunks, content_type) -> tuple[bytes, str]:
  1349. """Enforce Content-Length + streamed size caps, then require an image/* type."""
  1350. try:
  1351. size = int(resp.headers.get("Content-Length") or resp.headers.get("content-length"))
  1352. except Exception:
  1353. size = None
  1354. if size is not None and size > self._max_media_bytes:
  1355. raise ValueError(f"media exceeds Matrix limit ({size} > {self._max_media_bytes} bytes)")
  1356. parts: list[bytes] = []
  1357. total = 0
  1358. async for chunk in chunks:
  1359. total += len(chunk)
  1360. if total > self._max_media_bytes:
  1361. raise ValueError(f"media exceeds Matrix limit (> {self._max_media_bytes} bytes)")
  1362. parts.append(bytes(chunk))
  1363. content_type = str(content_type or "").split(";", 1)[0].strip().lower()
  1364. if not content_type.startswith("image/"):
  1365. raise ValueError("external media is not an image")
  1366. return b"".join(parts), content_type
  1367. fname = url.rsplit("/", 1)[-1].split("?")[0] or "image.png"
  1368. try:
  1369. import aiohttp as _aiohttp
  1370. _sess_kw, _req_kw = proxy_kwargs_for_aiohttp(self._proxy_url)
  1371. async with _aiohttp.ClientSession(**_sess_kw) as http:
  1372. fetch_url = url
  1373. for _ in range(20):
  1374. async with http.get(
  1375. fetch_url, timeout=_aiohttp.ClientTimeout(total=30), allow_redirects=False, **_req_kw) as resp:
  1376. if resp.status in {301, 302, 303, 307, 308}:
  1377. location = resp.headers.get("Location")
  1378. if not location:
  1379. raise ValueError("redirect missing Location")
  1380. # Re-validate EVERY hop: a public URL can 302 toward loopback/metadata endpoints,
  1381. # and checking only the final URL is too late (the hop already connected).
  1382. fetch_url = urljoin(fetch_url, location)
  1383. if not is_safe_url(fetch_url):
  1384. raise ValueError("blocked unsafe redirect URL")
  1385. continue
  1386. resp.raise_for_status()
  1387. data, ct = await _read_capped(
  1388. resp, resp.content.iter_chunked(65536),
  1389. getattr(resp, "content_type", None)
  1390. or resp.headers.get("content-type", "application/octet-stream"))
  1391. return data, ct, fname
  1392. raise ValueError("too many redirects")
  1393. except ImportError:
  1394. from tools.url_safety import create_ssrf_safe_async_client
  1395. _httpx_kw: dict = {"proxy": self._proxy_url} if self._proxy_url else {}
  1396. _httpx_kw["event_hooks"] = {"response": [ssrf_redirect_guard]}
  1397. async with create_ssrf_safe_async_client(**_httpx_kw) as http:
  1398. async with http.stream("GET", url, follow_redirects=True, timeout=30) as resp:
  1399. resp.raise_for_status()
  1400. data, ct = await _read_capped(
  1401. resp, resp.aiter_bytes(), resp.headers.get("content-type", "application/octet-stream"))
  1402. return data, ct, fname
  1403. async def send_image_file(
  1404. self, chat_id: str, image_path: str, caption: Optional[str] = None, reply_to: Optional[str] = None,
  1405. metadata: Optional[dict[str, Any]] = None) -> SendResult:
  1406. return await self._send_local_file(chat_id, image_path, "m.image", caption, reply_to, metadata=metadata)
  1407. async def send_multiple_images(
  1408. self, chat_id: str, images: list[tuple[str, str]], metadata: Optional[dict[str, Any]] = None,
  1409. human_delay: float = 0.0) -> SendResult:
  1410. if not images:
  1411. return SendResult(success=False, error="no images to send")
  1412. from urllib.parse import unquote as _unquote
  1413. total = len(images)
  1414. delivered = False
  1415. for idx, (image_url, alt_text) in enumerate(images, start=1):
  1416. if human_delay > 0 and idx > 1:
  1417. await asyncio.sleep(human_delay)
  1418. caption = f"{alt_text} ({idx}/{total})" if alt_text and total > 1 else (alt_text or None)
  1419. if image_url.startswith("file://"):
  1420. result = await self.send_image_file(
  1421. chat_id=chat_id, image_path=_unquote(image_url[7:]), caption=caption, metadata=metadata)
  1422. else:
  1423. result = await self.send_image(chat_id=chat_id, image_url=image_url, caption=caption, metadata=metadata)
  1424. if not result.success:
  1425. logger.warning("Matrix: failed to send image %d/%d: %s", idx, total, result.error)
  1426. delivered = delivered or result.success
  1427. return SendResult(success=delivered, error=None if delivered else "all images failed to send")
  1428. async def send_document(
  1429. self, chat_id: str, file_path: str, caption: Optional[str] = None, file_name: Optional[str] = None,
  1430. reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None) -> SendResult:
  1431. return await self._send_local_file(chat_id, file_path, "m.file", caption, reply_to, file_name, metadata)
  1432. async def send_voice(
  1433. self, chat_id: str, audio_path: str, caption: Optional[str] = None, reply_to: Optional[str] = None,
  1434. metadata: Optional[dict[str, Any]] = None, is_voice: Optional[bool] = None) -> SendResult:
  1435. """Upload audio. The base media dispatch calls this with ``is_voice``: True for a voice-tagged
  1436. attachment → MSC3245 voice bubble; False for an audio-ext MEDIA attachment → plain ``m.audio``
  1437. in the original format. Voice bubbles need Ogg/Opus but callers pass any format (e.g. TTS
  1438. output), so transcode there — best-effort: without ffmpeg the original is sent. Callers that
  1439. don't pass the flag (``play_audio``) keep the voice-bubble behavior this method was written
  1440. for (#116776: the dispatch always passes ``is_voice``, and rejecting it dropped the file)."""
  1441. if is_voice is False:
  1442. return await self._send_local_file(
  1443. chat_id, audio_path, "m.audio", caption, reply_to, metadata=metadata, is_voice=False)
  1444. converted_path: Optional[str] = None
  1445. if not str(audio_path).lower().endswith((".ogg", ".oga", ".opus")):
  1446. # 48k (not the 32k default): Element renders voice bubbles at a higher quality tier.
  1447. converted_path = await asyncio.to_thread(transcode_to_ogg_opus, audio_path, bitrate="48k", timeout=30)
  1448. try:
  1449. return await self._send_local_file(
  1450. chat_id, converted_path or audio_path, "m.audio", caption, reply_to,
  1451. # keep the caller's basename (the temp transcode file has a generated name)
  1452. file_name=(Path(audio_path).with_suffix(".ogg").name if converted_path else None),
  1453. metadata=metadata, is_voice=True)
  1454. finally:
  1455. if converted_path:
  1456. with suppress(OSError):
  1457. os.unlink(converted_path)
  1458. async def send_video(
  1459. self, chat_id: str, video_path: str, caption: Optional[str] = None, reply_to: Optional[str] = None,
  1460. metadata: Optional[dict[str, Any]] = None) -> SendResult:
  1461. return await self._send_local_file(chat_id, video_path, "m.video", caption, reply_to, metadata=metadata)
  1462. # Template attrs for the shared _format_exec_approval core (header + fence + reason only;
  1463. # the smart-deny/scope wording lives in the reaction legend below).
  1464. _EA_CMD_BUDGET = 2000
  1465. @property
  1466. def _EA_HEADER(self) -> str:
  1467. return f"⚠️ **{t('gateway.exec_approval.header')}**\n"
  1468. async def _send_reaction_prompt(
  1469. self, chat_id: str, text: str, metadata: Optional[dict], make_prompt, registry: dict, emojis,
  1470. label: str) -> SendResult:
  1471. """Send *text*, register ``make_prompt(message_id, requester, expires_at)`` under
  1472. the resulting event, then seed the bot's reaction controls (recording their IDs)."""
  1473. result = await self.send(chat_id, text, metadata=metadata)
  1474. if not result.success or not result.message_id:
  1475. return result
  1476. prompt = make_prompt(
  1477. result.message_id, str((metadata or {}).get("requester_user_id") or "") or None,
  1478. time.monotonic() + max(self._approval_timeout_seconds, 0))
  1479. registry[result.message_id] = prompt
  1480. for emoji in emojis:
  1481. try:
  1482. reaction_event_id = await self._send_reaction(chat_id, result.message_id, emoji)
  1483. if reaction_event_id:
  1484. prompt.bot_reaction_events[emoji] = str(reaction_event_id)
  1485. except Exception as exc:
  1486. logger.debug("Matrix: failed to add %s reaction %s: %s", label, emoji, exc)
  1487. return result
  1488. _EA_REACTIONS = {"once": "✅", "session": "🌀", "always": "♾️", "deny": "❌"}
  1489. _EA_LEGEND_KEYS = {"once": "platform.matrix.approval.legend_once", "session": "platform.matrix.approval.legend_session",
  1490. "always": "platform.matrix.approval.legend_always", "deny": "platform.matrix.approval.legend_deny"}
  1491. # Whole sentences per offered tier (the highest tier wins) so translations never splice fragments.
  1492. _EA_TYPED_HINT_KEYS = {"once": "platform.matrix.approval.typed_hint_once",
  1493. "session": "platform.matrix.approval.typed_hint_session",
  1494. "always": "platform.matrix.approval.typed_hint_always"}
  1495. async def _send_exec_approval_prompt(self, prompt: ExecApprovalPrompt) -> SendResult:
  1496. """Reaction-driven approval: the bot seeds one reaction per offered choice."""
  1497. if not self._client:
  1498. return SendResult(success=False, error="Not connected")
  1499. choices = prompt.choices
  1500. tier = "once"
  1501. if not prompt.smart_denied:
  1502. tier = "always" if "always" in choices else ("session" if "session" in choices else "once")
  1503. text = (
  1504. f"{prompt.text}\n\n"
  1505. f"{t(self._EA_TYPED_HINT_KEYS[tier])}\n\n"
  1506. f"{t('platform.matrix.approval.legend_intro')}\n" + "\n".join(t(self._EA_LEGEND_KEYS[c]) for c in choices))
  1507. reactions = tuple(self._EA_REACTIONS[c] for c in choices)
  1508. session_key, chat_id = prompt.session_key, prompt.chat_id
  1509. def _make(message_id, requester, expires_at):
  1510. old_event = self._approval_prompt_by_session.get(session_key)
  1511. if old_event:
  1512. self._approval_prompts_by_event.pop(old_event, None)
  1513. self._approval_prompt_by_session[session_key] = message_id
  1514. return _MatrixApprovalPrompt(
  1515. session_key=session_key, chat_id=chat_id, message_id=message_id, requester_user_id=requester,
  1516. expires_at=expires_at, request_id=prompt.request_id)
  1517. return await self._send_reaction_prompt(
  1518. chat_id, text, prompt.metadata, _make, self._approval_prompts_by_event, reactions, "approval")
  1519. async def send_model_picker(
  1520. self, chat_id: str, providers: list, current_model: str, current_provider: str, session_key: str,
  1521. on_model_selected, metadata: Optional[dict[str, Any]] = None) -> SendResult:
  1522. if not self._client:
  1523. return SendResult(success=False, error="Not connected")
  1524. flat_choices = [
  1525. (str(model_id), str(p.get("slug") or ""), str(p.get("name") or p.get("slug") or ""))
  1526. for p in providers or [] for model_id in (p.get("models") or [])][:len(_MATRIX_MODEL_PICKER_REACTIONS)]
  1527. if not flat_choices:
  1528. return await self.send(
  1529. chat_id, t("platform.matrix.picker.no_models"), metadata=metadata)
  1530. try:
  1531. from hermes_cli.providers import get_label
  1532. provider_label = get_label(current_provider)
  1533. except Exception:
  1534. provider_label = current_provider
  1535. from hermes_cli.model_picker_usage import picker_row_suffix
  1536. rows_by_slug = {str(p.get("slug") or ""): p for p in providers or []}
  1537. plan_lines = [f"⚠️ {p['plan_line']}" for p in providers or [] if p.get("plan_line")]
  1538. unknown = t("platform.shared.unknown")
  1539. lines = [
  1540. t("platform.matrix.picker.title"), t("platform.matrix.picker.current_model", model=current_model or unknown),
  1541. t("platform.matrix.picker.provider", provider=provider_label or unknown), *plan_lines, "",
  1542. t("platform.matrix.picker.react_model")]
  1543. choices: dict[str, tuple[str, str]] = {}
  1544. for emoji, (model_id, provider_slug, provider_name) in zip(_MATRIX_MODEL_PICKER_REACTIONS, flat_choices):
  1545. choices[emoji] = (model_id, provider_slug)
  1546. suffix = picker_row_suffix(rows_by_slug.get(provider_slug), model_id)
  1547. lines.append(f"{emoji} `{model_id}` — {provider_name}" + (f" · {suffix}" if suffix else ""))
  1548. return await self._send_picker(
  1549. chat_id, lines, choices, session_key, on_model_selected, metadata, self._model_picker_prompts_by_event,
  1550. "model picker")
  1551. async def _send_picker(
  1552. self, chat_id: str, lines: list, choices: dict, session_key: str, on_selected, metadata, registry: dict,
  1553. label: str) -> SendResult:
  1554. """Send picker *lines*, register a _MatrixPickerPrompt under the event, seed its reactions."""
  1555. return await self._send_reaction_prompt(
  1556. chat_id, "\n".join(lines), metadata,
  1557. lambda message_id, requester, expires_at: _MatrixPickerPrompt(
  1558. chat_id=chat_id, message_id=message_id, session_key=session_key, choices=choices,
  1559. on_selected=on_selected, requester_user_id=requester, expires_at=expires_at),
  1560. registry, choices, label)
  1561. async def send_choice_picker(
  1562. self, chat_id: str, title: str, choices: list, session_key: str, on_choice_selected,
  1563. metadata: Optional[dict[str, Any]] = None) -> SendResult:
  1564. """Reaction-based choice picker (/reasoning, /fast); choice = {value, label, is_current}."""
  1565. if not self._client:
  1566. return SendResult(success=False, error="Not connected")
  1567. emoji_choices: dict[str, str] = {}
  1568. lines = [title, ""]
  1569. for emoji, choice in zip(_MATRIX_CHOICE_PICKER_REACTIONS, choices):
  1570. value = str(choice.get("value") or "")
  1571. label = str(choice.get("label") or value)
  1572. if choice.get("is_current"):
  1573. label = t("platform.matrix.picker.current_suffix", label=label)
  1574. emoji_choices[emoji] = value
  1575. lines.append(f"{emoji} {label}")
  1576. if not emoji_choices:
  1577. return SendResult(success=False, error="No choices")
  1578. lines += ["", t("platform.matrix.picker.react_choice")]
  1579. return await self._send_picker(
  1580. chat_id, lines, emoji_choices, session_key, on_choice_selected, metadata,
  1581. self._choice_picker_prompts_by_event, "choice picker")
  1582. def format_message(self, content: str) -> str:
  1583. """Markdown passes through; strip image markdown (media is uploaded separately)."""
  1584. return re.sub(r"!\[([^\]]*)\]\(([^)]+)\)", r"\2", content)
  1585. async def _upload_and_send(
  1586. self, room_id: str, data: bytes, filename: str, content_type: str, msgtype: str,
  1587. caption: Optional[str] = None, reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None,
  1588. is_voice: bool = False, voice_metadata: Optional[dict[str, Any]] = None) -> SendResult:
  1589. if len(data) > self._max_media_bytes:
  1590. return self._media_too_large(len(data))
  1591. upload_data = data
  1592. encrypted_file = None
  1593. if await self._room_needs_encrypted_upload(room_id):
  1594. try:
  1595. from mautrix.crypto.attachments import encrypt_attachment
  1596. upload_data, encrypted_file = encrypt_attachment(data)
  1597. except Exception as exc:
  1598. logger.error("Matrix: attachment encryption failed: %s", exc)
  1599. return SendResult(success=False, error=str(exc))
  1600. try:
  1601. mxc_url = await self._client.upload_media(
  1602. upload_data, mime_type=content_type, filename=filename, size=len(upload_data))
  1603. except Exception as exc:
  1604. logger.error("Matrix: upload failed: %s", exc)
  1605. return SendResult(success=False, error=str(exc))
  1606. msg_content: dict[str, Any] = {
  1607. "msgtype": msgtype, "body": caption or filename, "info": {"mimetype": content_type, "size": len(data)}}
  1608. if encrypted_file is not None:
  1609. msg_content["file"] = {**encrypted_file.serialize(), "url": str(mxc_url)}
  1610. else:
  1611. msg_content["url"] = str(mxc_url)
  1612. if is_voice: # MSC3245 native voice flag + MSC1767 audio metadata
  1613. msg_content["org.matrix.msc3245.voice"] = {}
  1614. audio_metadata = {
  1615. k: v for k in ("duration", "waveform") if (v := (voice_metadata or {}).get(k)) is not None}
  1616. if "duration" in audio_metadata:
  1617. msg_content["info"]["duration"] = audio_metadata["duration"]
  1618. if audio_metadata:
  1619. msg_content["org.matrix.msc1767.audio"] = audio_metadata
  1620. self._apply_relation_metadata(msg_content, reply_to=reply_to, metadata=metadata)
  1621. return await self._send_content_event(room_id, msg_content)
  1622. async def _room_needs_encrypted_upload(self, room_id: str) -> bool:
  1623. """E2EE on, Olm machine loaded, and the state store says the room is encrypted."""
  1624. if not (self._encryption and getattr(self._client, "crypto", None)):
  1625. return False
  1626. state_store = getattr(self._client, "state_store", None)
  1627. if not state_store:
  1628. return False
  1629. try:
  1630. return bool(await state_store.is_encrypted(RoomID(room_id)))
  1631. except Exception:
  1632. return False
  1633. def _media_too_large(self, size: int) -> SendResult:
  1634. return SendResult(
  1635. success=False, error=f"Media file exceeds Matrix limit ({size} > {self._max_media_bytes} bytes)")
  1636. async def _send_content_event(self, room_id: str, msg_content: dict[str, Any]) -> SendResult:
  1637. """Send a prebuilt m.room.message payload, mapping exceptions to SendResult."""
  1638. try:
  1639. event_id = await self._client.send_message_event(RoomID(room_id), EventType.ROOM_MESSAGE, msg_content)
  1640. return SendResult(success=True, message_id=str(event_id))
  1641. except Exception as exc:
  1642. return SendResult(success=False, error=str(exc))
  1643. async def _send_local_file(
  1644. self, room_id: str, file_path: str, msgtype: str, caption: Optional[str] = None,
  1645. reply_to: Optional[str] = None, file_name: Optional[str] = None, metadata: Optional[dict[str, Any]] = None,
  1646. is_voice: bool = False) -> SendResult:
  1647. p = Path(file_path).expanduser()
  1648. if not p.exists():
  1649. # file_path is host-local; never echo it into chat.
  1650. logger.warning("[%s] upload fallback: media file not found for %s", self.name, file_path)
  1651. text = t("platform.shared.media.attachment_failed")
  1652. return await self.emit_media_warning(room_id, text, caption=caption, reply_to=reply_to, metadata=metadata)
  1653. try:
  1654. file_size = p.stat().st_size
  1655. except OSError:
  1656. file_size = 0
  1657. if file_size > self._max_media_bytes:
  1658. return self._media_too_large(file_size)
  1659. fname = file_name or p.name
  1660. # ffprobe/ffmpeg probing is blocking (subprocess timeouts up to 15s) —
  1661. # run it off the event loop so voice uploads never stall the adapter.
  1662. voice_metadata = await asyncio.to_thread(_matrix_voice_metadata_for_file, p) if is_voice else None
  1663. return await self._upload_and_send(
  1664. room_id, p.read_bytes(), fname, mimetypes.guess_type(fname)[0] or "application/octet-stream", msgtype,
  1665. caption, reply_to, metadata, is_voice, voice_metadata)
  1666. async def _sync_loop(self) -> None:
  1667. client = self._client
  1668. next_batch = await client.sync_store.get_next_batch() # resume from the initial sync
  1669. while not self._closing:
  1670. try:
  1671. # 45s outer cap guards TCP-level hangs the 30s long-poll timeout cannot catch.
  1672. # mautrix raises on every non-2xx, so a non-dict here is never an error object.
  1673. sync_data = await asyncio.wait_for(client.sync(since=next_batch, timeout=30000), timeout=45.0)
  1674. if isinstance(sync_data, dict):
  1675. next_batch = await self._absorb_sync(client, sync_data) or next_batch
  1676. await asyncio.sleep(0) # let fresh invite joins start before the next sync
  1677. except asyncio.CancelledError:
  1678. return
  1679. except Exception as exc:
  1680. if self._closing:
  1681. return
  1682. # Detect permanent auth/permission failures. Transient 5xx outages must retry.
  1683. if _is_permanent_matrix_auth_error(exc):
  1684. logger.error("Matrix: permanent auth error, stopping sync: %s", exc)
  1685. return
  1686. logger.warning("Matrix: sync error: %s — retrying in 5s", exc)
  1687. await asyncio.sleep(5)
  1688. async def _absorb_sync(self, client: Any, sync_data: dict[str, Any], *, initial: bool = False) -> Optional[str]:
  1689. """Apply one sync response: joined rooms, next_batch, event dispatch, pending invites. Returns next_batch.
  1690. The initial (full-state) sync also seeds the DM cache and dispatches so the OlmMachine sees
  1691. to-device key shares queued while offline."""
  1692. self._last_sync_ts = time.time()
  1693. rooms_join = sync_data.get("rooms", {}).get("join", {})
  1694. if rooms_join or initial:
  1695. self._joined_rooms.update(rooms_join.keys())
  1696. self._invalidate_room_identities()
  1697. self._warn_encrypted_drops(rooms_join, client)
  1698. nb = sync_data.get("next_batch") # incremental syncs resume from here
  1699. if nb:
  1700. await client.sync_store.put_next_batch(nb)
  1701. if initial:
  1702. logger.info("Matrix: initial sync complete, joined %d rooms", len(self._joined_rooms))
  1703. await self._refresh_dm_cache()
  1704. try:
  1705. await self._dispatch_sync(sync_data)
  1706. except Exception as exc:
  1707. logger.warning("Matrix: %s: %s", "initial sync event dispatch error" if initial else "sync event dispatch error", exc)
  1708. self._schedule_pending_invite_joins(sync_data)
  1709. return nb
  1710. def _warn_encrypted_drops(self, rooms_join: dict[str, Any], client: Any) -> None:
  1711. """Fail loud when encrypted room events arrive but no decryptor is attached (#131778).
  1712. With E2EE off, or after the optional mode degraded (missing deps / failed setup) and
  1713. kept the connection, ``m.room.encrypted`` timeline events dispatch to an empty
  1714. ROOM_ENCRYPTED handler set — mautrix drops them without a trace, so an encrypted room
  1715. looks connected but deaf: syncs succeed, no errors, no warnings. One warning per room
  1716. per process; with a decryptor attached, mautrix's own machinery already reports
  1717. decryption failures."""
  1718. if getattr(client, "crypto", None) is not None:
  1719. return
  1720. for room_id, room_data in rooms_join.items():
  1721. if room_id in self._warned_encrypted_drop_rooms:
  1722. continue
  1723. events = room_data.get("timeline", {}).get("events", [])
  1724. if any(isinstance(ev, dict) and ev.get("type") == "m.room.encrypted" for ev in events):
  1725. self._warned_encrypted_drop_rooms.add(room_id)
  1726. if self._e2ee_mode == "off":
  1727. cause = f"{_E2EE_INSTALL_HINT}, then set MATRIX_E2EE_MODE=optional (or required)"
  1728. else:
  1729. cause = (f"E2EE mode is {self._e2ee_mode} but the decryptor was not set up at connect; "
  1730. "see the earlier Matrix E2EE warning for the cause")
  1731. logger.warning(
  1732. "Matrix: dropping encrypted messages in %s — this process has no E2EE decryptor. %s. "
  1733. "Without it, messages in encrypted rooms never reach the agent.",
  1734. room_id, cause)
  1735. async def _dispatch_sync(self, sync_data: dict[str, Any]) -> None:
  1736. """Dispatch a sync response through the mautrix event machinery."""
  1737. client = self._client
  1738. if not client or not hasattr(client, "handle_sync"):
  1739. return
  1740. tasks = client.handle_sync(sync_data)
  1741. if inspect.isawaitable(tasks):
  1742. tasks = await tasks
  1743. if tasks:
  1744. # return_exceptions=True: one failing handler must not drop its SIBLING events.
  1745. results = await asyncio.gather(*tasks, return_exceptions=True)
  1746. for result in results:
  1747. if isinstance(result, Exception):
  1748. logger.warning("Matrix: event handler failed during sync dispatch: %s", result)
  1749. def _is_self_sender(self, sender: str) -> bool:
  1750. """True if *sender* is the bot itself (case-insensitive: homeservers vary localpart case). With
  1751. no resolved user_id we can't prove a sender is NOT us, so return True — dropping our own
  1752. events beats an echo loop ("hall of mirrors").
  1753. Matrix user IDs are byte-compared after trimming whitespace and lowercasing — some homeservers
  1754. normalize the localpart case differently at different API surfaces, and the reply-loop tail of the
  1755. "hall of mirrors" bug (#15763) has been observed with the bot's own account bypassing a
  1756. case-sensitive equality check.
  1757. """
  1758. own = (self._user_id or "").strip().lower()
  1759. return not own or sender.strip().lower() == own
  1760. @staticmethod
  1761. def _is_system_or_bridge_sender(sender: str) -> bool:
  1762. """True for appservice/bridge/system identities (``@_telegram_123:server``) or malformed IDs.
  1763. Never offer these a pairing code: an approved bridge would relay every outbound message
  1764. back as an "authorized user message" (echo loop).
  1765. We treat these as system identities for pairing purposes: they should never be offered a pairing
  1766. code, because an operator approving the code would hand the bridge itself permanent authorization —
  1767. and every outbound message relayed by the bridge would then loop back into the agent as an
  1768. "authorized user message", which is the root of issue #15763.
  1769. """
  1770. localpart = (sender or "").strip().lstrip("@").partition(":")[0]
  1771. return not localpart or localpart.startswith("_")
  1772. async def _is_allowed_matrix_room_event(self, room_id: str) -> bool:
  1773. """MATRIX_ALLOWED_ROOMS gate; DMs are exempt so personal chats survive a project allowlist."""
  1774. if not self._allowed_room_ids or room_id in self._allowed_room_ids:
  1775. return True
  1776. try:
  1777. return await self._is_dm_room(room_id)
  1778. except Exception as exc:
  1779. logger.debug("Matrix: could not resolve room identity for allowlist check in %s: %s", room_id, exc)
  1780. return False
  1781. def _reset_clock_skew_detector(self) -> None:
  1782. """State for _note_late_grace_drop: consecutive-drop count, their skew, and the once-only warning."""
  1783. # Clock-skew detection: count grace-check drops that happen well after startup (i.e. not
  1784. # initial-sync backfill). If the host's system clock is set ahead of real time, the startup grace
  1785. # check `event_ts < startup_ts - 5` silently drops every live message. See #12614 — the symptom is
  1786. # "bot joins rooms but never replies". Drops only count when their skew matches the first sampled
  1787. # drop (within 60s), so varied-age backfill from freshly-invited rooms doesn't trip the heuristic.
  1788. self._late_grace_drops: int = 0
  1789. self._late_grace_skew: float = 0.0
  1790. self._clock_skew_warned: bool = False
  1791. def _note_late_grace_drop(self, event_ts: float) -> None:
  1792. """Clock-skew heuristic for grace-check drops well after startup. A host clock set ahead of
  1793. real time makes every live event look "older than startup" and the bot silently never
  1794. replies. Warn once when drops keep happening >30s after startup with a *consistent* skew —
  1795. unlike backfill from a freshly invited room, whose event ages vary widely and reset the counter."""
  1796. if self._clock_skew_warned or time.time() - self._startup_ts <= 30:
  1797. return
  1798. skew = self._startup_ts - event_ts
  1799. if not (5 < skew < 86400): # ignore malformed/absurd timestamps
  1800. return
  1801. if self._late_grace_drops and abs(skew - self._late_grace_skew) < 60:
  1802. self._late_grace_drops += 1
  1803. else:
  1804. self._late_grace_skew = skew
  1805. self._late_grace_drops = 1
  1806. if self._late_grace_drops >= 3:
  1807. logger.warning(
  1808. "Matrix: dropped %d consecutive live events as 'too old' more than 30s after startup "
  1809. "(skew ≈ %.0fs). The host system clock is likely set ahead of real time, which causes "
  1810. "the startup grace filter to silently discard every incoming message. Run "
  1811. "`timedatectl set-ntp true` (or sync NTP) and restart the bot.", self._late_grace_drops, skew)
  1812. self._clock_skew_warned = True
  1813. async def _on_room_message(self, event: Any) -> None:
  1814. room_id = str(getattr(event, "room_id", ""))
  1815. sender = str(getattr(event, "sender", ""))
  1816. # DEBUG-level proof the callback fires at all (silent-inbound troubleshooting).
  1817. logger.debug(
  1818. "Matrix: callback fired — event %s from %s in %s", getattr(event, "event_id", "?"), sender, room_id)
  1819. if self._is_self_sender(sender):
  1820. return
  1821. # Bridge/system identities must never reach the pairing flow (echo loop once paired).
  1822. # Ignore own messages (case-insensitive; also drops when our own user_id hasn't been resolved yet —
  1823. # see _is_self_sender docstring and issue #15763).
  1824. # Once a bridge user is paired, every outbound message it relays would loop back as an authorized
  1825. # user message (the "hall of mirrors" in #15763).
  1826. if self._is_system_or_bridge_sender(sender):
  1827. logger.debug("Matrix: ignoring system/bridge sender %s in %s", sender, room_id)
  1828. return
  1829. if any(pattern.search(sender or "") for pattern in self._ignored_user_patterns):
  1830. logger.debug("Matrix: ignoring sender %s in %s due to configured ignore pattern", sender, room_id)
  1831. return
  1832. if not await self._is_allowed_matrix_room_event(room_id):
  1833. logger.info("Matrix: ignoring message from unauthorized room %s", room_id)
  1834. return
  1835. event_id = str(getattr(event, "event_id", ""))
  1836. if self._is_duplicate_event(event_id):
  1837. return
  1838. # Startup grace: ignore old messages replayed by the initial sync.
  1839. event_ts = _matrix_event_timestamp_seconds(event)
  1840. if event_ts and event_ts < self._startup_ts - _STARTUP_GRACE_SECONDS:
  1841. self._note_late_grace_drop(event_ts)
  1842. return
  1843. content = getattr(event, "content", None)
  1844. if content is None:
  1845. return
  1846. if isinstance(content, dict):
  1847. source_content, msgtype = content, content.get("msgtype", "")
  1848. else:
  1849. source_content = content.serialize() if hasattr(content, "serialize") else {}
  1850. msgtype = str(content.msgtype) if hasattr(content, "msgtype") else ""
  1851. relates_to = source_content.get("m.relates_to", {})
  1852. if relates_to.get("rel_type") == "m.replace": # skip edits
  1853. return
  1854. # m.notice is the conventional bot-response msgtype; ignoring it prevents bot-to-bot loops.
  1855. if msgtype == "m.notice" and not self._process_notices:
  1856. return
  1857. if msgtype in ("m.image", "m.audio", "m.video", "m.file"):
  1858. await self._handle_media_message(room_id, sender, event_id, event_ts, source_content, relates_to, msgtype)
  1859. elif msgtype in ("m.text", "m.notice"):
  1860. await self._handle_text_message(room_id, sender, event_id, event_ts, source_content, relates_to)
  1861. async def _resolve_message_context(
  1862. self, room_id: str, sender: str, event_id: str, body: str, source_content: dict,
  1863. relates_to: dict, mention_claimed: bool = False,
  1864. voice_gate: Optional[VoiceGate] = None) -> Optional[tuple]:
  1865. """Shared mention/thread/DM gating. Returns (body, is_dm, chat_type, thread_id,
  1866. display_name, source) or None when the message should be dropped. ``mention_claimed``
  1867. marks a parked voice claimed by the sender's follow-up bare @mention; ``voice_gate`` is
  1868. the in-flight mark of a parkable voice, released once the park decision is made."""
  1869. identity = await self._resolve_room_identity(room_id)
  1870. is_dm = await self._is_dm_room(room_id)
  1871. chat_type = "dm" if is_dm else "group"
  1872. thread_id = _thread_root(relates_to)
  1873. is_mentioned = mention_claimed or self._content_mentions_bot(body, source_content)
  1874. if not is_dm:
  1875. # Whitelist first: non-listed rooms are dropped even when @mentioned (DMs exempt).
  1876. if self._allowed_rooms and room_id not in self._allowed_rooms:
  1877. logger.debug(
  1878. "Matrix: ignoring message %s in %s — room not in MATRIX_ALLOWED_ROOMS whitelist", event_id, room_id)
  1879. return None
  1880. is_free_room = room_id in self._free_rooms
  1881. in_bot_thread = bool(thread_id and thread_id in self._threads)
  1882. if self._require_mention and not is_free_room and not in_bot_thread:
  1883. if not is_mentioned and not body.startswith("/"):
  1884. if voice_gate is not None: # parkable voice: a bare @mention may follow (Element X)
  1885. self._parked_voices.park(room_id, sender, voice_gate, event_id, source_content, relates_to)
  1886. logger.debug(
  1887. "Matrix: ignoring message %s in %s — no @mention "
  1888. "(set MATRIX_REQUIRE_MENTION=false to disable)", event_id, room_id)
  1889. return None
  1890. # thread_require_mention: even inside a bot thread require @mention — prevents
  1891. # infinite reply loops when several bots share one thread.
  1892. elif self._thread_require_mention and in_bot_thread and not is_free_room and not is_mentioned:
  1893. logger.debug(
  1894. "Matrix: ignoring message %s in thread %s — no @mention (thread_require_mention=true)",
  1895. event_id, thread_id)
  1896. return None
  1897. if is_mentioned and self._require_mention:
  1898. # Strip the mention from the reply text only: the quote block carries the
  1899. # ``> <@bot:srv> ...`` reply pill, which _extract_reply_context parses later
  1900. # for reply_to_author_id. A whole-body replace rewrote the pill to ``> <>``
  1901. # and silently dropped the replied-to author (#111233). Only a real reply carries a
  1902. # pill; a hand-typed blockquote in a plain message is stripped whole as before.
  1903. if relates_to.get("m.in_reply_to"):
  1904. quote_block, reply_text = _split_reply_fallback(body)
  1905. body = quote_block + self._strip_mention(reply_text)
  1906. else:
  1907. body = self._strip_mention(body)
  1908. # Real thread roots are preserved above; synthetic roots (this event) follow policy: DM
  1909. # @mention threads / DM auto-thread, or room auto-thread unless session_scope pins the room.
  1910. if not thread_id:
  1911. if is_dm:
  1912. synthetic = (self._dm_mention_threads and is_mentioned) or self._dm_auto_thread
  1913. else:
  1914. synthetic = self._matrix_session_scope == "thread" or (
  1915. self._matrix_session_scope != "room" and self._auto_thread)
  1916. if synthetic:
  1917. thread_id = event_id
  1918. if voice_gate is not None: # decided (parked or passing): don't hold bare mentions any longer
  1919. self._parked_voices.release(room_id, sender, voice_gate)
  1920. display_name = await self._get_display_name(room_id, sender)
  1921. source = self.build_source(
  1922. chat_id=room_id, chat_name=identity.display_name, chat_type=chat_type, user_id=sender,
  1923. user_name=display_name, thread_id=thread_id, chat_topic=identity.room_topic,
  1924. guild_id=identity.server_name, parent_chat_id=room_id if thread_id else None, message_id=event_id)
  1925. if thread_id:
  1926. await self._threads.mark_async(thread_id) # covers real roots and synthetic ones alike
  1927. self._background_read_receipt(room_id, event_id)
  1928. return body, is_dm, chat_type, thread_id, display_name, source
  1929. async def _extract_reply_context(
  1930. self, room_id: str, body: str, relates_to: dict
  1931. ) -> tuple[str, Optional[str], Optional[str], Optional[str], Optional[str]]:
  1932. """Return (body, reply_to, reply_to_text, reply_to_author_id, reply_to_author_name). Captures
  1933. the inline reply fallback (``> <@user:srv> text\\n\\nreply``) BEFORE stripping it, so the
  1934. prompt layer can render "[Replying to: ...]" like Signal/Slack/Telegram."""
  1935. reply_to = (relates_to.get("m.in_reply_to") or {}).get("event_id")
  1936. reply_to_text = reply_to_author_id = reply_to_author_name = None
  1937. if reply_to and body.startswith("> "):
  1938. reply_to_text, reply_to_author_id = _extract_reply_fallback(body)
  1939. body = _strip_reply_fallback(body)
  1940. # Resolve the replied-to author's display name (falls back to localpart).
  1941. if reply_to_author_id:
  1942. reply_to_author_name = await self._get_display_name(room_id, reply_to_author_id)
  1943. return body, reply_to, reply_to_text, reply_to_author_id, reply_to_author_name
  1944. async def _build_inbound_event(
  1945. self, room_id: str, sender: str, event_id: str, body: str, source_content: dict, relates_to: dict,
  1946. ctx: Optional[tuple] = None, **extra) -> Optional[MessageEvent]:
  1947. """Gate + normalise an inbound event into a MessageEvent (None => drop). Text body may
  1948. still change (reply-fallback strip); ``extra`` carries media fields / message_type.
  1949. ``ctx`` is a pre-resolved ``_resolve_message_context`` result (media path gates before
  1950. downloading); resolving it twice would double the read receipt / thread mark."""
  1951. if ctx is None:
  1952. ctx = await self._resolve_message_context(room_id, sender, event_id, body, source_content, relates_to)
  1953. if ctx is None:
  1954. return None
  1955. body, _is_dm, _chat_type, _thread_id, display_name, source = ctx
  1956. body, reply_to, reply_to_text, reply_to_author_id, reply_to_author_name = (
  1957. await self._extract_reply_context(room_id, body, relates_to))
  1958. media_msgtype = extra.pop("media_msgtype", None)
  1959. if media_msgtype is None:
  1960. # Re-normalize after reply stripping so ``> quoted\n\n!model`` is still a command.
  1961. body = _normalize_matrix_bang_command(body)
  1962. extra["message_type"] = MessageType.COMMAND if body.startswith("/") else MessageType.TEXT
  1963. elif _is_bare_media_filename(media_msgtype, body):
  1964. body = "" # transport filename, not user text
  1965. return MessageEvent(
  1966. text=body, source=source, raw_message=source_content, message_id=event_id,
  1967. reply_to_message_id=reply_to, reply_to_text=reply_to_text, reply_to_author_id=reply_to_author_id,
  1968. reply_to_author_name=reply_to_author_name,
  1969. # Top-level sender fields mirror source.* — downstream prompt code reads them.
  1970. user_id=sender, user_name=display_name, **extra)
  1971. async def _handle_text_message(
  1972. self, room_id: str, sender: str, event_id: str, event_ts: float, source_content: dict,
  1973. relates_to: dict) -> None:
  1974. body = source_content.get("body", "") or ""
  1975. if not body:
  1976. return
  1977. # Dict lookup first: the mention regexes only run when a voice is parked or being gated
  1978. # (both only happen under require_mention).
  1979. if (self._parked_voices.pending(room_id, sender)
  1980. and not self._strip_mention(body).strip() and self._content_mentions_bot(body, source_content)):
  1981. limit = self._parked_voices.mark() # never claim a voice sent after this mention
  1982. await self._parked_voices.settle(room_id, sender) # same-/sync-batch voice still gating
  1983. parked = self._parked_voices.claim(room_id, sender, before=limit)
  1984. if parked: # answer the voice this bare mention was typed for, not an empty text
  1985. voice_id, voice_content, voice_relates = parked
  1986. await self._handle_media_message(
  1987. room_id, sender, voice_id, event_ts, voice_content, voice_relates, "m.audio",
  1988. mention_claimed=True)
  1989. self._background_read_receipt(room_id, event_id) # the claim receipted the voice
  1990. return
  1991. msg_event = await self._build_inbound_event(
  1992. room_id, sender, event_id, _normalize_matrix_bang_command(body), source_content, relates_to)
  1993. if msg_event is None:
  1994. return
  1995. if msg_event.message_type == MessageType.TEXT and self._text_batch_delay_seconds > 0:
  1996. self._enqueue_text_event(msg_event)
  1997. else:
  1998. await self.handle_message(msg_event)
  1999. async def _handle_media_message(
  2000. self, room_id: str, sender: str, event_id: str, event_ts: float, source_content: dict,
  2001. relates_to: dict, msgtype: str, mention_claimed: bool = False) -> None:
  2002. body = source_content.get("body", "") or ""
  2003. url = source_content.get("url", "")
  2004. if url and not str(url).startswith("mxc://"):
  2005. logger.warning("[Matrix] Rejecting inbound media %s with non-MXC URL", event_id)
  2006. return
  2007. content_info = source_content.get("info", {})
  2008. if not isinstance(content_info, dict):
  2009. content_info = {}
  2010. event_mimetype = content_info.get("mimetype", "")
  2011. try:
  2012. event_size_int = int(content_info.get("size") or 0)
  2013. except (TypeError, ValueError):
  2014. event_size_int = 0
  2015. if event_size_int and event_size_int > self._max_media_bytes:
  2016. logger.warning(
  2017. "[Matrix] Rejecting oversized inbound media %s (%d > %d bytes)", event_id, event_size_int,
  2018. self._max_media_bytes)
  2019. return
  2020. file_content = source_content.get("file", {}) # encrypted media carries file.url
  2021. if not url and isinstance(file_content, dict):
  2022. url = file_content.get("url", "") or ""
  2023. if url and not str(url).startswith("mxc://"):
  2024. logger.warning("[Matrix] Rejecting inbound encrypted media %s with non-MXC URL", event_id)
  2025. return
  2026. is_encrypted_media = bool(file_content and isinstance(file_content, dict) and file_content.get("url"))
  2027. msg_type, media_type, is_voice_message = self._classify_inbound_media(msgtype, event_mimetype, source_content)
  2028. # Gate (require_mention / allowed rooms) BEFORE the download: an unmentioned or
  2029. # non-allowlisted room must not pull media onto the host only to drop it.
  2030. # First await: mark a voice that may park in-flight so a concurrent bare mention waits for it.
  2031. gate = self._parked_voices.begin(room_id, sender) if self._voice_may_park(
  2032. room_id, body, source_content, relates_to, mention_claimed) else None
  2033. try:
  2034. ctx = await self._resolve_message_context(
  2035. room_id, sender, event_id, body, source_content, relates_to, mention_claimed=mention_claimed,
  2036. voice_gate=gate)
  2037. finally:
  2038. if gate is not None:
  2039. self._parked_voices.release(room_id, sender, gate)
  2040. if ctx is None:
  2041. return
  2042. # Cache locally so downstream tools get a real file path.
  2043. cached_path = None
  2044. if url:
  2045. try:
  2046. cached_path = await self._download_and_cache_media(
  2047. url, event_id, file_content if is_encrypted_media else None, msg_type, media_type,
  2048. is_voice_message, body)
  2049. except Exception as e:
  2050. logger.warning("[Matrix] Failed to cache media: %s", e)
  2051. # Unencrypted media may fall back to the HTTP download URL when caching failed.
  2052. http_url = self._mxc_to_http(url) if url and not is_encrypted_media else ""
  2053. media_urls = [cached_path] if cached_path else ([http_url] if http_url else None)
  2054. msg_event = await self._build_inbound_event(
  2055. room_id, sender, event_id, body, source_content, relates_to, ctx=ctx, message_type=msg_type,
  2056. media_urls=media_urls, media_types=[media_type] if media_urls else None, media_msgtype=msgtype)
  2057. if msg_event is not None:
  2058. await self.handle_message(msg_event)
  2059. @staticmethod
  2060. def _classify_inbound_media(
  2061. msgtype: str, event_mimetype: str, source_content: dict) -> tuple[MessageType, str, bool]:
  2062. """Map a Matrix media msgtype to (MessageType, mime type, is_voice_message)."""
  2063. if msgtype == "m.image":
  2064. return MessageType.PHOTO, event_mimetype or "image/png", False
  2065. if msgtype == "m.audio":
  2066. is_voice = has_voice_marker(source_content)
  2067. return (MessageType.VOICE if is_voice else MessageType.AUDIO), event_mimetype or "audio/ogg", is_voice
  2068. if msgtype == "m.video":
  2069. return MessageType.VIDEO, event_mimetype or "video/mp4", False
  2070. return MessageType.DOCUMENT, event_mimetype or "application/octet-stream", False
  2071. async def _download_and_cache_media(
  2072. self, url: str, event_id: str, encrypted_file: Optional[dict], msg_type: MessageType, media_type: str,
  2073. is_voice_message: bool, body: str) -> Optional[str]:
  2074. """Download (and decrypt, when *encrypted_file* is given) media into the local cache."""
  2075. file_bytes = await self._client.download_media(ContentURI(url))
  2076. if file_bytes is None:
  2077. return None
  2078. if encrypted_file is not None:
  2079. from mautrix.crypto.attachments import decrypt_attachment
  2080. hashes_value, key_value = encrypted_file.get("hashes"), encrypted_file.get("key")
  2081. hash_value = hashes_value.get("sha256") if isinstance(hashes_value, dict) else None
  2082. key_value = key_value.get("k") if isinstance(key_value, dict) else key_value
  2083. iv_value = encrypted_file.get("iv")
  2084. if not (key_value and hash_value and iv_value):
  2085. logger.warning("[Matrix] Encrypted media event missing decryption metadata for %s", event_id)
  2086. return None
  2087. file_bytes = decrypt_attachment(file_bytes, key_value, hash_value, iv_value)
  2088. from gateway.platforms.base import (
  2089. cache_audio_from_bytes_async,
  2090. cache_document_from_bytes_async,
  2091. cache_image_from_bytes_async,
  2092. )
  2093. if msg_type == MessageType.PHOTO:
  2094. ext_map = {"image/jpeg": ".jpg", "image/png": ".png", "image/gif": ".gif", "image/webp": ".webp"}
  2095. cached_path = await cache_image_from_bytes_async(file_bytes, ext=ext_map.get(media_type, ".jpg"))
  2096. logger.info("[Matrix] Cached user image at %s", cached_path)
  2097. return cached_path
  2098. if msg_type in {MessageType.AUDIO, MessageType.VOICE}:
  2099. ext = Path(body or ("voice.ogg" if is_voice_message else "audio.ogg")).suffix or ".ogg"
  2100. return await cache_audio_from_bytes_async(file_bytes, ext=ext)
  2101. filename = body or ("video.mp4" if msg_type == MessageType.VIDEO else "document")
  2102. return await cache_document_from_bytes_async(file_bytes, filename)
  2103. async def _on_invite(self, event: Any) -> None:
  2104. """Auto-join rooms when invited, recording DM rooms in m.direct."""
  2105. room_id = str(getattr(event, "room_id", ""))
  2106. is_direct = bool(getattr(getattr(event, "content", None), "is_direct", False))
  2107. inviter = str(getattr(event, "sender", ""))
  2108. # Only authorized inviters — otherwise any federated user could pull the bot into rooms.
  2109. if not self._is_authorized_user(inviter, str(room_id)):
  2110. logger.warning("Matrix: rejecting invite to %s from unauthorized user %s", room_id, inviter)
  2111. return
  2112. logger.info("Matrix: invited to %s — joining (is_direct=%s)", room_id, is_direct)
  2113. # Join off the sync path; a declared DM is recorded in m.direct once the join lands.
  2114. self._schedule_invite_join(room_id, is_direct=is_direct and bool(inviter), inviter=inviter)
  2115. async def _join_room_by_id(self, room_id: str) -> bool:
  2116. if not room_id or room_id in self._joined_rooms:
  2117. return bool(room_id)
  2118. try:
  2119. await self._client.join_room(RoomID(room_id))
  2120. self._joined_rooms.add(room_id)
  2121. self._invalidate_room_identities(room_id)
  2122. logger.info("Matrix: joined %s", room_id)
  2123. await self._refresh_dm_cache()
  2124. return True
  2125. except Exception as exc:
  2126. logger.warning("Matrix: error joining %s: %s", room_id, exc)
  2127. # Abandoned rooms ("no servers ..." / "room not found") would retry every startup
  2128. # unless we leave the invite; the match is narrow so transient errors keep retrying.
  2129. msg = str(exc).lower()
  2130. if ("no servers" in msg) or ("room not found" in msg):
  2131. with suppress(Exception):
  2132. await self._client.leave_room(RoomID(room_id))
  2133. logger.info("Matrix: declined dead invite to %s", room_id)
  2134. return False
  2135. def _schedule_invite_join(self, room_id: str, *, is_direct: bool = False, inviter: str = "") -> None:
  2136. """Schedule an invite join without blocking sync or gateway readiness."""
  2137. existing = self._invite_join_tasks.get(room_id)
  2138. if not room_id or room_id in self._joined_rooms or (existing and not existing.done()):
  2139. return
  2140. async def _join_invite() -> None:
  2141. try:
  2142. joined = await asyncio.wait_for(self._join_room_by_id(room_id), timeout=45.0)
  2143. if joined and is_direct and inviter:
  2144. await self._record_dm_room(room_id, inviter)
  2145. except TimeoutError:
  2146. logger.warning("Matrix: timed out joining invite %s", room_id)
  2147. finally:
  2148. self._invite_join_tasks.pop(room_id, None)
  2149. self._invite_join_tasks[room_id] = asyncio.create_task(_join_invite())
  2150. def _schedule_pending_invite_joins(self, sync_data: dict[str, Any]) -> None:
  2151. """Join rooms still present in rooms.invite after sync processing."""
  2152. invites = (sync_data.get("rooms", {}) if isinstance(sync_data, dict) else {}).get("invite", {})
  2153. if not isinstance(invites, dict):
  2154. return
  2155. for room_id, invited_room in invites.items():
  2156. if room_id in self._joined_rooms:
  2157. continue
  2158. # This reconcile pass runs after _dispatch_sync and sees every
  2159. # rooms.invite entry, whether _on_invite joined it, rejected
  2160. # it, or (for invites that arrived while the gateway was down)
  2161. # is only now seeing it. The invite event object is gone by
  2162. # this point, so the DM signal must be read from the stripped
  2163. # invite state; without it a direct invite joined here is never
  2164. # recorded in m.direct and gets misclassified as a group.
  2165. is_direct, inviter = self._extract_invite_dm_signal(invited_room)
  2166. # The inviter allowlist gate from _on_invite must apply here
  2167. # too: an unconditional join would re-admit a live invite that
  2168. # _on_invite just rejected milliseconds earlier, and would
  2169. # auto-join any invite from an arbitrary federated user on
  2170. # restart. An inviter missing from the stripped invite state
  2171. # fails closed, like an empty sender in _on_invite.
  2172. if not self._is_authorized_user(inviter, str(room_id)):
  2173. logger.warning(
  2174. "Matrix: rejecting invite to %s from unauthorized user %s",
  2175. room_id,
  2176. inviter,
  2177. )
  2178. continue
  2179. logger.info(
  2180. "Matrix: reconciling pending invite for %s (is_direct=%s)",
  2181. room_id,
  2182. is_direct,
  2183. )
  2184. self._schedule_invite_join(str(room_id), is_direct=is_direct, inviter=inviter)
  2185. def _extract_invite_dm_signal(self, invited_room: Any) -> tuple[bool, str]:
  2186. """Read the is_direct flag and inviter from a room's invite_state.
  2187. The stripped ``m.room.member`` event for our own user carries the
  2188. ``is_direct`` flag from the original invite; its sender is the
  2189. inviter. Returns ``(False, "")`` when the signal is absent.
  2190. """
  2191. if not self._user_id:
  2192. return False, ""
  2193. if not isinstance(invited_room, dict):
  2194. return False, ""
  2195. invite_state = invited_room.get("invite_state", {})
  2196. if not isinstance(invite_state, dict):
  2197. return False, ""
  2198. events = invite_state.get("events", [])
  2199. if not isinstance(events, list):
  2200. return False, ""
  2201. for event in events:
  2202. if not isinstance(event, dict):
  2203. continue
  2204. if event.get("type") != "m.room.member":
  2205. continue
  2206. if event.get("state_key") != self._user_id:
  2207. continue
  2208. content = event.get("content", {})
  2209. if not isinstance(content, dict):
  2210. continue
  2211. if content.get("membership") != "invite":
  2212. continue
  2213. return bool(content.get("is_direct")), str(event.get("sender", ""))
  2214. return False, ""
  2215. async def _send_reaction(self, room_id: str, event_id: str, emoji: str) -> Optional[str]:
  2216. """Send an emoji reaction; returns the reaction event_id, or None on failure."""
  2217. if not self._client:
  2218. return None
  2219. content = {"m.relates_to": {"rel_type": "m.annotation", "event_id": event_id, "key": emoji}}
  2220. try:
  2221. resp_event_id = await self._client.send_message_event(RoomID(room_id), EventType.REACTION, content)
  2222. logger.debug("Matrix: sent reaction %s to %s", emoji, event_id)
  2223. return str(resp_event_id)
  2224. except Exception as exc:
  2225. logger.debug("Matrix: reaction send error: %s", exc)
  2226. return None
  2227. async def _redact_reaction(self, room_id: str, reaction_event_id: str, reason: str = "") -> bool:
  2228. return await self.redact_message(room_id, reaction_event_id, reason)
  2229. def _schedule_reaction_redaction(self, room_id: str, reaction_event_id: str, reason: str = "") -> None:
  2230. """Redact a reaction after a short delay so message delivery settles."""
  2231. async def _redact_later() -> None:
  2232. try:
  2233. if self._reaction_redaction_delay_seconds:
  2234. await asyncio.sleep(self._reaction_redaction_delay_seconds)
  2235. if not await self._redact_reaction(room_id, reaction_event_id, reason):
  2236. logger.debug("Matrix: failed to redact reaction %s", reaction_event_id)
  2237. except asyncio.CancelledError:
  2238. raise
  2239. except Exception as exc:
  2240. logger.debug("Matrix: delayed reaction redaction failed for %s: %s", reaction_event_id, exc)
  2241. task = asyncio.create_task(_redact_later())
  2242. self._reaction_redaction_tasks.add(task)
  2243. task.add_done_callback(self._reaction_redaction_tasks.discard)
  2244. async def on_processing_start(self, event: MessageEvent) -> None:
  2245. msg_id, room_id = event.message_id, event.source.chat_id
  2246. if self._reactions_enabled and msg_id and room_id:
  2247. reaction_event_id = await self._send_reaction(room_id, msg_id, "\U0001f440")
  2248. if reaction_event_id:
  2249. self._pending_reactions[(room_id, msg_id)] = reaction_event_id
  2250. async def on_processing_complete(self, event: MessageEvent, outcome: ProcessingOutcome) -> None:
  2251. msg_id, room_id = event.message_id, event.source.chat_id
  2252. if not self._reactions_enabled or not msg_id or not room_id or outcome == ProcessingOutcome.CANCELLED:
  2253. return
  2254. eyes_event_id = self._pending_reactions.pop((room_id, msg_id), None)
  2255. if eyes_event_id:
  2256. self._schedule_reaction_redaction(room_id, eyes_event_id, "processing complete")
  2257. await self._send_reaction(room_id, msg_id, "\u2705" if outcome == ProcessingOutcome.SUCCESS else "\u274c")
  2258. async def _on_reaction(self, event: Any) -> None:
  2259. sender = str(getattr(event, "sender", ""))
  2260. if self._is_self_sender(sender):
  2261. return
  2262. event_id = str(getattr(event, "event_id", ""))
  2263. if self._is_duplicate_event(event_id):
  2264. return
  2265. room_id = str(getattr(event, "room_id", ""))
  2266. content = getattr(event, "content", None)
  2267. if not content:
  2268. return
  2269. relates_to = (content.get("m.relates_to", {}) if isinstance(content, dict)
  2270. else getattr(content, "relates_to", {}))
  2271. reacts_to = key = ""
  2272. if isinstance(relates_to, dict):
  2273. reacts_to = relates_to.get("event_id", "")
  2274. key = relates_to.get("key", "")
  2275. elif hasattr(relates_to, "event_id"):
  2276. reacts_to = str(getattr(relates_to, "event_id", ""))
  2277. key = str(getattr(relates_to, "key", ""))
  2278. logger.info("Matrix: reaction %s from %s on %s in %s", key, sender, reacts_to, room_id)
  2279. for handler in (self._handle_approval_reaction, self._handle_model_picker_reaction,
  2280. self._handle_choice_picker_reaction):
  2281. if await handler(room_id, reacts_to, key, sender):
  2282. return
  2283. async def _claim_reaction_prompt(
  2284. self, registry: dict, room_id: str, reacts_to: str, key: str, sender: str, label: str, invalid_text: str,
  2285. on_expired, choices: Optional[dict] = None) -> tuple[bool, Any, Any]:
  2286. """Shared gate for reaction prompts: (handled, prompt, selection). handled=False => not our
  2287. prompt; selection=None with handled=True => consumed without action (wrong room, expired,
  2288. unauthorized reactor, or a key that is not a choice). ``choices`` defaults to ``prompt.choices``."""
  2289. prompt = registry.get(reacts_to)
  2290. if not prompt or prompt.resolved:
  2291. return False, None, None
  2292. if room_id != prompt.chat_id:
  2293. return True, prompt, None
  2294. if self._matrix_prompt_expired(prompt):
  2295. await on_expired(room_id, reacts_to, prompt)
  2296. return True, prompt, None
  2297. if not await self._validate_matrix_prompt_reactor(room_id, reacts_to, sender, prompt, label):
  2298. return True, prompt, None
  2299. selection = (prompt.choices if choices is None else choices).get(key)
  2300. if selection is None:
  2301. await self._send_invalid_reaction_feedback(room_id, reacts_to, invalid_text)
  2302. return True, prompt, selection
  2303. async def _handle_approval_reaction(self, room_id: str, reacts_to: str, key: str, sender: str) -> bool:
  2304. """Resolve a pending exec-approval prompt from a reaction. True if it was the target."""
  2305. handled, prompt, choice = await self._claim_reaction_prompt(
  2306. self._approval_prompts_by_event, room_id, reacts_to, key, sender, "approval",
  2307. t("platform.matrix.approval.invalid_reaction"), self._expire_matrix_approval_prompt,
  2308. choices=self._approval_reaction_map)
  2309. if choice is None:
  2310. return handled
  2311. try:
  2312. from tools.approval import resolve_gateway_approval_card
  2313. count = resolve_gateway_approval_card(prompt.session_key, choice, prompt.request_id)
  2314. if count:
  2315. prompt.resolved = True
  2316. self._approval_prompts_by_event.pop(reacts_to, None)
  2317. self._approval_prompt_by_session.pop(prompt.session_key, None)
  2318. logger.info(
  2319. "Matrix reaction resolved %d approval(s) for session %s (choice=%s, user=%s)",
  2320. count, prompt.session_key, choice, sender)
  2321. await self._redact_bot_approval_reactions(room_id, prompt)
  2322. else: # this card's request already timed out or was answered elsewhere
  2323. await self._expire_matrix_approval_prompt(room_id, reacts_to, prompt)
  2324. except Exception as exc:
  2325. logger.error("Failed to resolve gateway approval from Matrix reaction: %s", exc)
  2326. return True
  2327. async def _handle_model_picker_reaction(self, room_id: str, reacts_to: str, key: str, sender: str) -> bool:
  2328. """Apply a model-picker reaction. True if the reaction targeted a pending picker."""
  2329. return await self._handle_picker_reaction(
  2330. self._model_picker_prompts_by_event, room_id, reacts_to, key, sender, "model picker",
  2331. t("platform.matrix.picker.invalid_model_reaction"), self._expire_matrix_model_picker_prompt,
  2332. ("switch model", "platform.matrix.picker.verb_switch_model"), redact_bot_reactions=True)
  2333. async def _handle_choice_picker_reaction(self, room_id: str, reacts_to: str, key: str, sender: str) -> bool:
  2334. """Apply a choice-picker reaction. True if the reaction targeted a pending picker."""
  2335. async def _expire(_room_id, target_event_id, _prompt):
  2336. self._choice_picker_prompts_by_event.pop(target_event_id, None)
  2337. return await self._handle_picker_reaction(
  2338. self._choice_picker_prompts_by_event, room_id, reacts_to, key, sender, "choice picker",
  2339. t("platform.matrix.picker.invalid_choice_reaction"), _expire,
  2340. ("apply choice", "platform.matrix.picker.verb_apply_selection"))
  2341. async def _handle_picker_reaction(
  2342. self, registry: dict, room_id: str, reacts_to: str, key: str, sender: str, label: str, invalid_text: str,
  2343. on_expired, verbs: tuple[str, str], *, redact_bot_reactions: bool = False) -> bool:
  2344. """Claim the picker, fire ``on_selected(room_id, *selection)`` and post its confirmation (or the error).
  2345. ``verbs`` = (log verb, catalog key of the user-facing verb)."""
  2346. handled, prompt, selection = await self._claim_reaction_prompt(
  2347. registry, room_id, reacts_to, key, sender, label, invalid_text, on_expired)
  2348. if selection is None:
  2349. return handled
  2350. prompt.resolved = True
  2351. registry.pop(reacts_to, None)
  2352. args = selection if isinstance(selection, tuple) else (selection,)
  2353. try:
  2354. confirmation = await prompt.on_selected(room_id, *args)
  2355. if redact_bot_reactions:
  2356. await self._redact_bot_model_picker_reactions(room_id, prompt)
  2357. if confirmation:
  2358. await self.send(room_id, confirmation, reply_to=reacts_to)
  2359. except Exception as exc:
  2360. logger.error("Failed to %s from Matrix reaction: %s", verbs[0], exc)
  2361. await self.send(room_id, t("platform.matrix.picker.failed", action=t(verbs[1]), error=str(exc)),
  2362. reply_to=reacts_to)
  2363. return True
  2364. def _matrix_prompt_expired(self, prompt: Any) -> bool:
  2365. expires_at = getattr(prompt, "expires_at", None)
  2366. return expires_at is not None and time.monotonic() > float(expires_at)
  2367. def _is_authorized_user(self, user_id: str, room_id: str | None = None) -> bool:
  2368. """Resolve live gateway authorization, falling back to the startup snapshot when unwired."""
  2369. if getattr(self, "_authorization_check", None) is not None:
  2370. return self._is_sender_authorized(user_id, chat_id=room_id) is True
  2371. # Scoped read — the DEFAULT profile's os.environ opt-in must not authorize on a secondary bot.
  2372. return _get_scoped_secret("GATEWAY_ALLOW_ALL_USERS", "").strip().lower() in ("true", "1", "yes") or bool(
  2373. self._allowed_user_ids and user_id in self._allowed_user_ids)
  2374. async def _validate_matrix_prompt_reactor(
  2375. self, room_id: str, target_event_id: str, sender: str, prompt: Any, prompt_label: str) -> bool:
  2376. if not self._is_authorized_user(sender, room_id):
  2377. logger.info(
  2378. "Matrix: ignoring %s reaction from unauthorized user %s on %s", prompt_label, sender, target_event_id)
  2379. await self._send_invalid_reaction_feedback(
  2380. room_id, target_event_id, t("platform.matrix.reaction.unauthorized"))
  2381. return False
  2382. requester = getattr(prompt, "requester_user_id", None)
  2383. # getattr: object.__new__-built test doubles may lack the attribute.
  2384. if getattr(self, "_approval_require_sender", True) and requester and sender != requester:
  2385. logger.info("Matrix: ignoring %s reaction from %s; requester is %s", prompt_label, sender, requester)
  2386. await self._send_invalid_reaction_feedback(
  2387. room_id, target_event_id, t("platform.matrix.reaction.not_requester"))
  2388. return False
  2389. return True
  2390. async def _send_invalid_reaction_feedback(self, room_id: str, target_event_id: str, text: str) -> None:
  2391. try:
  2392. await self.send(room_id, text, reply_to=target_event_id)
  2393. except Exception as exc:
  2394. logger.debug("Matrix: failed to send invalid reaction feedback: %s", exc)
  2395. async def _expire_matrix_approval_prompt(self, room_id: str, target_event_id: str, prompt: Any) -> None:
  2396. prompt.resolved = True
  2397. self._approval_prompts_by_event.pop(target_event_id, None)
  2398. self._approval_prompt_by_session.pop(prompt.session_key, None)
  2399. await self._redact_bot_approval_reactions(room_id, prompt)
  2400. await self._send_invalid_reaction_feedback(
  2401. room_id, target_event_id,
  2402. t("platform.matrix.approval.expired"))
  2403. async def _expire_matrix_model_picker_prompt(self, room_id: str, target_event_id: str, prompt: Any) -> None:
  2404. prompt.resolved = True
  2405. self._model_picker_prompts_by_event.pop(target_event_id, None)
  2406. await self._redact_bot_model_picker_reactions(room_id, prompt)
  2407. await self._send_invalid_reaction_feedback(
  2408. room_id, target_event_id, t("platform.shared.model_picker_expired"))
  2409. async def _redact_bot_approval_reactions(self, room_id: str, prompt: Any) -> None:
  2410. """Redact the bot's seeded approval reactions (delayed), leaving only the user's reaction."""
  2411. for emoji, evt_id in prompt.bot_reaction_events.items():
  2412. self._schedule_reaction_redaction(room_id, evt_id, "approval resolved")
  2413. logger.debug("Matrix: scheduled bot reaction redaction %s (%s)", emoji, evt_id)
  2414. async def _redact_bot_model_picker_reactions(self, room_id: str, prompt: Any) -> None:
  2415. for emoji, evt_id in prompt.bot_reaction_events.items():
  2416. try:
  2417. await self.redact_message(room_id, evt_id, "model picker resolved")
  2418. logger.debug("Matrix: redacted model picker reaction %s (%s)", emoji, evt_id)
  2419. except Exception as exc:
  2420. logger.debug("Matrix: failed to redact model picker reaction %s: %s", emoji, exc)
  2421. def _background_read_receipt(self, room_id: str, event_id: str) -> None:
  2422. async def _send() -> None:
  2423. try:
  2424. await self.send_read_receipt(room_id, event_id)
  2425. except Exception as exc: # pragma: no cover — defensive
  2426. logger.debug("Matrix: background read receipt failed: %s", exc)
  2427. asyncio.ensure_future(_send())
  2428. async def send_read_receipt(self, room_id: str, event_id: str) -> bool:
  2429. if not self._client:
  2430. return False
  2431. try:
  2432. room, event = RoomID(room_id), EventID(event_id)
  2433. if hasattr(self._client, "set_fully_read_marker"):
  2434. await self._client.set_fully_read_marker(room, event, event)
  2435. elif hasattr(self._client, "send_receipt"):
  2436. await self._client.send_receipt(room, event)
  2437. elif hasattr(self._client, "set_read_markers"):
  2438. await self._client.set_read_markers(room, fully_read_event=event, read_receipt=event)
  2439. else:
  2440. logger.debug("Matrix: client has no read receipt method")
  2441. return False
  2442. logger.debug("Matrix: sent read receipt for %s in %s", event_id, room_id)
  2443. return True
  2444. except Exception as exc:
  2445. logger.debug("Matrix: read receipt failed: %s", exc)
  2446. return False
  2447. async def _client_op(self, coro_factory, ok_msg: tuple, err_msg: str, *, level: str = "warning") -> bool:
  2448. """Run one client call when connected: log *ok_msg* and return True, or log the error and return False."""
  2449. if not self._client:
  2450. return False
  2451. try:
  2452. await coro_factory()
  2453. getattr(logger, "debug" if level == "debug" else "info")(*ok_msg)
  2454. return True
  2455. except Exception as exc:
  2456. getattr(logger, level)(err_msg, exc)
  2457. return False
  2458. async def redact_message(self, room_id: str, event_id: str, reason: str = "") -> bool:
  2459. return await self._client_op(
  2460. lambda: self._client.redact(RoomID(room_id), EventID(event_id), reason=reason or None),
  2461. ("Matrix: redacted %s in %s", event_id, room_id), "Matrix: redact error: %s")
  2462. async def create_room(
  2463. self, name: str = "", topic: str = "", invite: Optional[list] = None, is_direct: bool = False,
  2464. preset: str = "private_chat") -> Optional[str]:
  2465. if not self._client:
  2466. return None
  2467. if preset == "public_chat" and not _env_truthy("MATRIX_ALLOW_PUBLIC_ROOMS"):
  2468. logger.warning("Matrix: refusing to create public room without MATRIX_ALLOW_PUBLIC_ROOMS=true")
  2469. return None
  2470. try:
  2471. preset_enum = {
  2472. "private_chat": RoomCreatePreset.PRIVATE, "public_chat": RoomCreatePreset.PUBLIC,
  2473. "trusted_private_chat": RoomCreatePreset.TRUSTED_PRIVATE}.get(preset, RoomCreatePreset.PRIVATE)
  2474. room_id = await self._client.create_room(
  2475. name=name or None, topic=topic or None, invitees=[UserID(u) for u in (invite or [])],
  2476. is_direct=is_direct, preset=preset_enum)
  2477. room_id_str = str(room_id)
  2478. self._joined_rooms.add(room_id_str)
  2479. logger.info("Matrix: created room %s (%s)", room_id_str, name or "unnamed")
  2480. return room_id_str
  2481. except Exception as exc:
  2482. logger.warning("Matrix: create_room error: %s", exc)
  2483. return None
  2484. async def invite_user(self, room_id: str, user_id: str) -> bool:
  2485. return await self._client_op(
  2486. lambda: self._client.invite_user(RoomID(room_id), UserID(user_id)),
  2487. ("Matrix: invited %s to %s", user_id, room_id), "Matrix: invite error: %s")
  2488. _VALID_PRESENCE_STATES = frozenset(("online", "offline", "unavailable"))
  2489. async def set_presence(self, state: str = "online", status_msg: str = "") -> bool:
  2490. if not self._client:
  2491. return False
  2492. if state not in self._VALID_PRESENCE_STATES:
  2493. logger.warning("Matrix: invalid presence state %r", state)
  2494. return False
  2495. presence_map = {
  2496. "online": PresenceState.ONLINE, "offline": PresenceState.OFFLINE, "unavailable": PresenceState.UNAVAILABLE}
  2497. return await self._client_op(
  2498. lambda: self._client.set_presence(presence=presence_map[state], status=status_msg or None),
  2499. ("Matrix: presence set to %s", state), "Matrix: set_presence failed: %s", level="debug")
  2500. @staticmethod
  2501. def _state_event_value(event: Any, key: str) -> Optional[str]:
  2502. """Extract a simple value from a Matrix state event object or dict (top-level, then .content)."""
  2503. if event is None:
  2504. return None
  2505. for obj in (event, event.get("content") if isinstance(event, dict) else getattr(event, "content", None)):
  2506. value = obj.get(key) if isinstance(obj, dict) else getattr(obj, key, None)
  2507. if value:
  2508. return str(value)
  2509. return None
  2510. async def _get_room_member_count(self, room_id: str) -> Optional[int]:
  2511. """state_store first (cached), then a direct joined_members API query."""
  2512. state_store = getattr(self._client, "state_store", None) if self._client else None
  2513. if state_store:
  2514. with suppress(Exception):
  2515. members = await state_store.get_members(room_id)
  2516. if members is not None:
  2517. return len(members)
  2518. client = getattr(self, "_client", None) # object.__new__-built test doubles may lack it
  2519. if client is not None and hasattr(client, "joined_members"):
  2520. with suppress(Exception):
  2521. resp = await client.joined_members(room_id)
  2522. if getattr(resp, "members", None) is not None:
  2523. return len(resp.members)
  2524. return None
  2525. async def _get_room_state_value(self, room_id: str, event_type: str, key: str) -> Optional[str]:
  2526. """Fetch a stripped string field from a room state event, or None."""
  2527. if not self._client or not hasattr(self._client, "get_state_event"):
  2528. return None
  2529. try:
  2530. event = await self._client.get_state_event(RoomID(room_id), event_type)
  2531. except Exception:
  2532. return None
  2533. value = (self._state_event_value(event, key) or "").strip()
  2534. return value or None
  2535. def _invalidate_room_identities(self, room_id: str | None = None) -> None:
  2536. """Drop one cached room identity (or all when *room_id* is None)."""
  2537. if room_id is None:
  2538. self._room_identities.clear()
  2539. self._room_identity_cached_at.clear()
  2540. else:
  2541. self._room_identities.pop(room_id, None)
  2542. self._room_identity_cached_at.pop(room_id, None)
  2543. async def _resolve_room_identity(self, room_id: str, *, force_refresh: bool = False) -> MatrixRoomIdentity:
  2544. """Resolve room identity; member count is the primary DM signal (see below)."""
  2545. cached = self._room_identities.get(room_id)
  2546. ttl = self._room_identity_ttl_seconds
  2547. cache_fresh = ttl <= 0 or time.monotonic() - self._room_identity_cached_at.get(room_id, 0.0) <= ttl
  2548. if cached is not None and cache_fresh and not force_refresh:
  2549. return cached
  2550. room_name = await self._get_room_state_value(room_id, "m.room.name", "name")
  2551. room_topic = await self._get_room_state_value(room_id, "m.room.topic", "topic")
  2552. canonical_alias = await self._get_room_state_value(room_id, "m.room.canonical_alias", "alias")
  2553. member_count = await self._get_room_member_count(room_id)
  2554. has_explicit_name = bool(room_name)
  2555. is_direct = bool(self._dm_rooms.get(room_id, False))
  2556. # <=2 members is necessarily a DM regardless of m.direct/name (clients auto-name DMs
  2557. # like "Alice & Bot"); fall back to m.direct + unnamed only when the count is unknown.
  2558. is_likely_dm = (member_count is not None and member_count <= 2) or (is_direct and not has_explicit_name)
  2559. identity = MatrixRoomIdentity(
  2560. room_id=room_id, room_name=room_name, room_topic=room_topic, canonical_alias=canonical_alias,
  2561. server_name=(room_id.rsplit(":", 1)[-1].strip() or None) if ":" in room_id else None,
  2562. joined_member_count=member_count,
  2563. is_direct_account_data=is_direct, display_name=room_name or canonical_alias or room_id,
  2564. has_explicit_name=has_explicit_name, chat_type="dm" if is_likely_dm else "room",
  2565. conflict=bool(is_direct and has_explicit_name and (member_count is None or member_count > 2)))
  2566. if len(self._room_identities) >= self._room_identity_cache_max:
  2567. oldest = min(self._room_identity_cached_at, key=self._room_identity_cached_at.get, default=None)
  2568. if oldest:
  2569. self._invalidate_room_identities(oldest)
  2570. self._room_identities[room_id] = identity
  2571. self._room_identity_cached_at[room_id] = time.monotonic()
  2572. return identity
  2573. async def _is_dm_room(self, room_id: str) -> bool:
  2574. return (await self._resolve_room_identity(room_id)).chat_type == "dm"
  2575. async def _fetch_m_direct(self, *, log_failure: bool = False, require_dict: bool = False):
  2576. """Return the m.direct account-data mapping, or None when absent/unreadable."""
  2577. try:
  2578. resp = await self._client.get_account_data("m.direct")
  2579. except Exception as exc:
  2580. if log_failure:
  2581. logger.debug("Matrix: get_account_data('m.direct') failed: %s", exc)
  2582. return None
  2583. if hasattr(resp, "content") and (not require_dict or isinstance(resp.content, dict)):
  2584. return resp.content
  2585. return resp if isinstance(resp, dict) else None
  2586. async def _refresh_dm_cache(self) -> None:
  2587. if not self._client:
  2588. return
  2589. dm_data = await self._fetch_m_direct(log_failure=True)
  2590. if dm_data is None:
  2591. return
  2592. dm_room_ids = {str(r) for rooms in dm_data.values() if isinstance(rooms, list) for r in rooms if isinstance(r, str)}
  2593. self._dm_rooms = {rid: (rid in dm_room_ids) for rid in self._joined_rooms}
  2594. self._invalidate_room_identities()
  2595. async def _record_dm_room(self, room_id: str, inviter: str) -> None:
  2596. """Persist a room as DM in m.direct account data after an invite. ``m.direct`` is absent (404)
  2597. until the account has had a DM; fetch the current mapping (if any), append *room_id* under
  2598. *inviter*, write it back so ``_refresh_dm_cache`` sees the DM."""
  2599. if not self._client:
  2600. return
  2601. dm_data: dict[str, list] = await self._fetch_m_direct(require_dict=True) or {}
  2602. rooms_for_user = dm_data.get(inviter, [])
  2603. rooms_for_user = rooms_for_user if isinstance(rooms_for_user, list) else []
  2604. if room_id not in rooms_for_user:
  2605. rooms_for_user.append(room_id)
  2606. dm_data[inviter] = rooms_for_user
  2607. try:
  2608. await self._client.set_account_data("m.direct", dm_data)
  2609. logger.info("Matrix: recorded %s as DM room (inviter=%s)", room_id, inviter)
  2610. except Exception as exc:
  2611. logger.warning("Matrix: failed to update m.direct: %s", exc)
  2612. # Local cache so _resolve_room_identity sees it immediately.
  2613. self._dm_rooms[room_id] = True
  2614. self._invalidate_room_identities(room_id)
  2615. def _build_text_message_content(self, text: str, msgtype: str = "m.text") -> dict[str, Any]:
  2616. """Build Matrix text content with HTML and outbound mention metadata."""
  2617. msg_content: dict[str, Any] = {"msgtype": msgtype, "body": text}
  2618. mention_user_ids = self._extract_outbound_mentions(text)
  2619. if mention_user_ids:
  2620. msg_content["m.mentions"] = {"user_ids": mention_user_ids}
  2621. if self._allow_room_mentions and self._has_outbound_room_mention(text):
  2622. msg_content.setdefault("m.mentions", {})["room"] = True
  2623. html = self._markdown_to_html(self._inject_outbound_mention_links(text))
  2624. if html and html != text:
  2625. msg_content["format"] = "org.matrix.custom.html"
  2626. msg_content["formatted_body"] = html
  2627. if _content_bytes(msg_content) > _MAX_CONTENT_BYTES:
  2628. # Escape-heavy text can outgrow the budget as HTML; send it as plain text instead.
  2629. del msg_content["format"], msg_content["formatted_body"]
  2630. return msg_content
  2631. def _apply_relation_metadata(
  2632. self, msg_content: dict[str, Any], *, reply_to: Optional[str] = None,
  2633. metadata: Optional[dict[str, Any]] = None) -> None:
  2634. """Apply Matrix reply/thread relation metadata to an outbound payload."""
  2635. thread_id = str((metadata or {}).get("thread_id") or "")
  2636. if reply_to:
  2637. msg_content["m.relates_to"] = {"m.in_reply_to": {"event_id": reply_to}}
  2638. if thread_id:
  2639. relates_to = msg_content.get("m.relates_to", {})
  2640. relates_to["rel_type"] = "m.thread"
  2641. relates_to["event_id"] = thread_id
  2642. relates_to["is_falling_back"] = True
  2643. # Non-thread clients render the reply fallback; default it to the thread root.
  2644. relates_to.setdefault("m.in_reply_to", {"event_id": reply_to or thread_id})
  2645. msg_content["m.relates_to"] = relates_to
  2646. def _extract_outbound_mentions(self, text: str) -> list[str]:
  2647. protected, _ = self._protect_outbound_mention_regions(text)
  2648. return list(dict.fromkeys(m.group(1) for m in _OUTBOUND_MENTION_RE.finditer(protected)))
  2649. def _has_outbound_room_mention(self, text: str) -> bool:
  2650. """Return True when outbound text contains @room outside protected spans."""
  2651. protected, _ = self._protect_outbound_mention_regions(text)
  2652. return bool(re.search(r"(?<![\w/])@room(?![\w:.-])", protected))
  2653. def _inject_outbound_mention_links(self, text: str) -> str:
  2654. """Wrap outbound Matrix mentions in markdown links outside code spans."""
  2655. if not text:
  2656. return text
  2657. protected, placeholders = self._protect_outbound_mention_regions(text)
  2658. linked = _OUTBOUND_MENTION_RE.sub(lambda m: f"[{m.group(1)}](https://matrix.to/#/{m.group(1)})", protected)
  2659. for idx, original in enumerate(placeholders):
  2660. linked = linked.replace(f"\x00MENTION_PROTECTED{idx}\x00", original)
  2661. return linked
  2662. def _protect_outbound_mention_regions(self, text: str) -> tuple[str, list[str]]:
  2663. """Protect markdown regions where outbound mentions should stay literal."""
  2664. placeholders: list[str] = []
  2665. def _protect(fragment: str) -> str:
  2666. idx = len(placeholders)
  2667. placeholders.append(fragment)
  2668. return f"\x00MENTION_PROTECTED{idx}\x00"
  2669. protected = text or ""
  2670. for pattern in (r"```[\s\S]*?```", r"`[^`\n]+`", r"\[[^\]]+\]\([^)]+\)"):
  2671. protected = re.sub(pattern, lambda match: _protect(match.group(0)), protected)
  2672. return protected, placeholders
  2673. def _is_bot_mentioned(
  2674. self, body: str, formatted_body: Optional[str] = None, mention_user_ids: Optional[list] = None) -> bool:
  2675. """True if the bot is mentioned; ``m.mentions.user_ids`` (MSC3952) is authoritative
  2676. even when the body has no ``@bot`` text (pills may live only in formatted_body)."""
  2677. if mention_user_ids and self._user_id and self._user_id in mention_user_ids:
  2678. return True
  2679. if not body and not formatted_body:
  2680. return False
  2681. if self._user_id and self._user_id in body:
  2682. return True
  2683. localpart = self._user_localpart()
  2684. if localpart and re.search(r"\b" + re.escape(localpart) + r"\b", body, re.IGNORECASE):
  2685. return True
  2686. return bool(formatted_body and self._user_id and f"matrix.to/#/{self._user_id}" in formatted_body)
  2687. def _voice_may_park(self, room_id: str, body: str, content: dict, relates_to: dict,
  2688. mention_claimed: bool) -> bool:
  2689. """Synchronous pre-check of the ``_resolve_message_context`` park branch (only DM-ness
  2690. needs an await; a DM voice's mark is released as soon as that is known)."""
  2691. if mention_claimed or not self._require_mention or not is_voice_event(content):
  2692. return False
  2693. if room_id in self._free_rooms or (self._allowed_rooms and room_id not in self._allowed_rooms):
  2694. return False
  2695. thread_id = _thread_root(relates_to)
  2696. if thread_id and thread_id in self._threads:
  2697. return False
  2698. return not body.startswith("/") and not self._content_mentions_bot(body, content)
  2699. def _content_mentions_bot(self, body: str, content: dict) -> bool:
  2700. """``_is_bot_mentioned`` fed from an event's content (MSC3952 ``m.mentions`` is authoritative)."""
  2701. mentions = content.get("m.mentions") or {}
  2702. return self._is_bot_mentioned(
  2703. body, content.get("formatted_body"), mentions.get("user_ids") if isinstance(mentions, dict) else None)
  2704. def _user_localpart(self) -> str:
  2705. """``@bot:server`` -> ``bot``; empty when the user ID has no server part."""
  2706. return self._user_id.split(":")[0].lstrip("@") if self._user_id and ":" in self._user_id else ""
  2707. def _strip_mention(self, body: str) -> str:
  2708. """Strip explicit ``@user:server`` / ``@localpart`` tokens only — never bare localpart
  2709. words, or "Hermes Agent" would become "Agent"."""
  2710. if not body:
  2711. return ""
  2712. if self._user_id:
  2713. body = body.replace(self._user_id, "")
  2714. localpart = self._user_localpart()
  2715. if localpart:
  2716. body = re.sub(r'(?<![\w])@' + re.escape(localpart) + r'\b', '', body, flags=re.IGNORECASE)
  2717. # Normalize spacing after mention removal.
  2718. body = re.sub(r'[ \t]{2,}', ' ', body)
  2719. body = re.sub(r'\s+([,.;:!?])', r'\1', body)
  2720. return body.strip()
  2721. async def _get_display_name(self, room_id: str, user_id: str) -> str:
  2722. """Get a user's display name in a room, falling back to user_id."""
  2723. state_store = getattr(self._client, "state_store", None) if self._client else None
  2724. if state_store:
  2725. with suppress(Exception):
  2726. member = await state_store.get_member(room_id, user_id)
  2727. if member and getattr(member, "displayname", None):
  2728. return member.displayname
  2729. if user_id.startswith("@") and ":" in user_id:
  2730. return user_id[1:].split(":")[0]
  2731. return user_id
  2732. def _mxc_to_http(self, mxc_url: str) -> str:
  2733. if not mxc_url.startswith("mxc://"):
  2734. return mxc_url
  2735. return f"{self._homeserver}/_matrix/client/v1/media/download/{mxc_url[6:]}"
  2736. def _markdown_to_html(self, text: str) -> str:
  2737. """Markdown → org.matrix.custom.html via ``markdown`` when installed, else the regex fallback."""
  2738. text = _pre_sanitize_matrix_markdown(text)
  2739. text, tex_store = _latex_to_tokens(text)
  2740. with suppress(ImportError):
  2741. import markdown as _md
  2742. md = _md.Markdown(extensions=["fenced_code", "tables", "nl2br", "sane_lists"])
  2743. if "html_block" in md.preprocessors:
  2744. md.preprocessors.deregister("html_block")
  2745. html = md.convert(text)
  2746. md.reset()
  2747. if html.count("<p>") == 1:
  2748. html = html.replace("<p>", "").replace("</p>", "")
  2749. return _tokens_to_mx_maths(_sanitize_matrix_html(html), tex_store)
  2750. return _tokens_to_mx_maths(_sanitize_matrix_html(self._markdown_to_html_fallback(text)), tex_store)
  2751. @staticmethod
  2752. def _sanitize_link_url(url: str) -> str:
  2753. stripped = url.strip()
  2754. if ":" in stripped and stripped.split(":", 1)[0].lower().strip() in {"javascript", "data", "vbscript"}:
  2755. return ""
  2756. return stripped.replace('"', "&quot;")
  2757. @staticmethod
  2758. def _markdown_to_html_fallback(text: str) -> str:
  2759. """Comprehensive regex Markdown-to-HTML for Matrix."""
  2760. placeholders: list = []
  2761. def _is_bq_line(ln: str) -> bool:
  2762. return ln.startswith(("&gt; ", "> ")) or ln in ("&gt;", ">")
  2763. def _protect_html(html_fragment: str) -> str:
  2764. idx = len(placeholders)
  2765. placeholders.append(html_fragment)
  2766. return f"\x00PROTECTED{idx}\x00"
  2767. result = re.sub(
  2768. r"```(\w*)\n(.*?)```",
  2769. lambda m: _protect_html(
  2770. f'<pre><code class="language-{_html_escape(m.group(1))}">{_html_escape(m.group(2))}</code></pre>'
  2771. if m.group(1) else f"<pre><code>{_html_escape(m.group(2))}</code></pre>"),
  2772. text, flags=re.DOTALL)
  2773. result = re.sub(r"`([^`\n]+)`", lambda m: _protect_html(f"<code>{_html_escape(m.group(1))}</code>"), result)
  2774. # Protect markdown links before escaping.
  2775. result = re.sub(
  2776. r"\[([^\]]+)\]\(([^)]+)\)",
  2777. lambda m: _protect_html(
  2778. f'<a href="{MatrixAdapter._sanitize_link_url(m.group(2))}">{_html_escape(m.group(1))}</a>'),
  2779. result)
  2780. result = "".join(p if p.startswith("\x00PROTECTED") else _html_escape(p)
  2781. for p in re.split(r"(\x00PROTECTED\d+\x00)", result))
  2782. # Block-level transforms (line-oriented): hr, headers, blockquote, lists.
  2783. lines = result.split("\n")
  2784. out_lines: list = []
  2785. i = 0
  2786. while i < len(lines):
  2787. line = lines[i]
  2788. if re.match(r"^[\s]*([-*_])\s*\1\s*\1[\s\-*_]*$", line):
  2789. out_lines.append("<hr>")
  2790. i += 1
  2791. continue
  2792. hdr = re.match(r"^(#{1,6})\s+(.+)$", line)
  2793. if hdr:
  2794. level = len(hdr.group(1))
  2795. out_lines.append(f"<h{level}>{hdr.group(2).strip()}</h{level}>")
  2796. i += 1
  2797. continue
  2798. if _is_bq_line(line):
  2799. bq_lines = []
  2800. while i < len(lines) and _is_bq_line(lines[i]):
  2801. ln = lines[i]
  2802. bq_lines.append(ln[5:] if ln.startswith("&gt; ") else ln[2:] if ln.startswith("> ") else "")
  2803. i += 1
  2804. out_lines.append(f"<blockquote>{'<br>'.join(bq_lines)}</blockquote>")
  2805. continue
  2806. for item_re, tag in ((r"^[\s]*[-*+]\s+(.+)$", "ul"), (r"^[\s]*\d+[.)]\s+(.+)$", "ol")):
  2807. if re.match(item_re, line):
  2808. items = []
  2809. while i < len(lines) and re.match(item_re, lines[i]):
  2810. items.append(re.match(item_re, lines[i]).group(1))
  2811. i += 1
  2812. out_lines.append(f"<{tag}>{''.join(f'<li>{item}</li>' for item in items)}</{tag}>")
  2813. break
  2814. else:
  2815. out_lines.append(line)
  2816. i += 1
  2817. result = "\n".join(out_lines)
  2818. for pattern, repl in (
  2819. (r"\*\*(.+?)\*\*", r"<strong>\1</strong>"), (r"__(.+?)__", r"<strong>\1</strong>"),
  2820. (r"\*(.+?)\*", r"<em>\1</em>"), (r"(?<!\w)_(.+?)_(?!\w)", r"<em>\1</em>"),
  2821. (r"~~(.+?)~~", r"<del>\1</del>")):
  2822. result = re.sub(pattern, repl, result, flags=re.DOTALL)
  2823. result = re.sub(r"\n", "<br>\n", result)
  2824. result = re.sub(r"<br>\n(</?(?:pre|blockquote|h[1-6]|ul|ol|li|hr))", r"\n\1", result)
  2825. result = re.sub(r"(</(?:pre|blockquote|h[1-6]|ul|ol|li)>)<br>", r"\1", result)
  2826. for idx, original in enumerate(placeholders):
  2827. result = result.replace(f"\x00PROTECTED{idx}\x00", original)
  2828. return result
  2829. async def _standalone_send(pconfig, chat_id, message, *, thread_id=None, media_files=None, force_document=False):
  2830. """standalone_sender_fn: out-of-process delivery via the Client-Server API (cron without gateway)."""
  2831. extra = getattr(pconfig, "extra", {}) or {}
  2832. try:
  2833. import aiohttp
  2834. except ImportError:
  2835. return send_error("aiohttp not installed. Run: pip install aiohttp")
  2836. try:
  2837. # In-turn reads inside an installed secret scope: honor get_secret, no env fallback — for the
  2838. # homeserver too, so the scoped token is never sent to the default profile's server.
  2839. homeserver = (extra.get("homeserver") or get_secret("MATRIX_HOMESERVER", "") or "").rstrip("/")
  2840. token = getattr(pconfig, "token", None) or get_secret("MATRIX_ACCESS_TOKEN", "") or ""
  2841. if not homeserver or not token:
  2842. return send_error("Matrix not configured (MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN required)")
  2843. from urllib.parse import quote
  2844. headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
  2845. # asyncio.wait_for, not aiohttp.ClientTimeout: cron invokes this via
  2846. # run_coroutine_threadsafe ("Timeout context manager should be used inside a task").
  2847. async with aiohttp.ClientSession() as session:
  2848. async def _do_send(payload):
  2849. txn_id = f"hermes_{int(time.time() * 1000)}_{os.urandom(4).hex()}"
  2850. url = f"{homeserver}/_matrix/client/v3/rooms/{quote(chat_id, safe='')}/send/m.room.message/{txn_id}"
  2851. async with session.put(url, headers=headers, json=payload) as resp:
  2852. if resp.status not in {200, 201}:
  2853. return send_error(f"Matrix API error ({resp.status}): {await resp.text()}")
  2854. data = await resp.json()
  2855. return {"success": True, "platform": "matrix", "chat_id": chat_id,
  2856. "message_id": data.get("event_id")}
  2857. for payload in _standalone_payloads(message):
  2858. try:
  2859. result = await asyncio.wait_for(_do_send(payload), timeout=30)
  2860. except TimeoutError:
  2861. return send_error("Matrix API timeout (30s)")
  2862. if not result.get("success"):
  2863. return result
  2864. return result
  2865. except Exception as e:
  2866. return send_error(f"Matrix send failed: {e}")
  2867. def _standalone_payloads(message: str) -> list[dict[str, Any]]:
  2868. """One m.room.message content per chunk. The caller chunks on characters, and a chunk of
  2869. non-Latin text can still exceed the homeserver's byte cap, so re-chunk on UTF-8 bytes."""
  2870. _md = None
  2871. with suppress(ImportError):
  2872. import markdown as _md
  2873. payloads = []
  2874. for chunk in BasePlatformAdapter.truncate_message(message, MATRIX_MAX_MESSAGE_LENGTH_CEILING, _utf8_len):
  2875. payload = {"msgtype": "m.text", "body": chunk}
  2876. if _md is not None:
  2877. tokenized, tex_store = _latex_to_tokens(chunk)
  2878. html = _md.markdown(tokenized, extensions=["fenced_code", "tables"])
  2879. formatted = {"format": "org.matrix.custom.html", "formatted_body": _tokens_to_mx_maths(
  2880. re.sub(r"<h[1-6]>(.*?)</h[1-6]>", r"<strong>\1</strong>", html), tex_store)}
  2881. if _content_bytes({**payload, **formatted}) <= _MAX_CONTENT_BYTES:
  2882. payload.update(formatted)
  2883. payloads.append(payload)
  2884. return payloads
  2885. def interactive_setup() -> None:
  2886. """Interactive credential setup (setup_fn); CLI helpers are lazy-imported."""
  2887. from hermes_cli.config import get_env_value, remove_env_value, save_env_value
  2888. from hermes_cli.cli_output import prompt, prompt_yes_no, print_header, print_info, print_success, print_warning
  2889. from hermes_cli.setup_platforms import declines_reconfigure
  2890. print_header("Matrix")
  2891. if declines_reconfigure("Matrix", "Reconfigure Matrix?", "MATRIX_ACCESS_TOKEN", "MATRIX_PASSWORD"):
  2892. return
  2893. for line in ("Works with any Matrix homeserver (Synapse, Conduit, Dendrite, or matrix.org).",
  2894. " 1. Create a bot user on your homeserver, or use your own account",
  2895. " 2. Get an access token from Element, or provide user ID + password"):
  2896. print_info(line)
  2897. def _ask(key: str, question: str, **kw) -> str:
  2898. value = prompt(question, **kw)
  2899. if value:
  2900. save_env_value(key, value.rstrip("/") if key == "MATRIX_HOMESERVER" else value)
  2901. return value
  2902. _ask("MATRIX_HOMESERVER", "Homeserver URL (e.g. https://matrix.example.org)")
  2903. print_info("Auth: provide an access token (recommended), or user ID + password.")
  2904. token = _ask("MATRIX_ACCESS_TOKEN", "Access token (leave empty for password login)", password=True)
  2905. if token:
  2906. _ask("MATRIX_USER_ID", "User ID (@bot:server — optional, will be auto-detected)")
  2907. print_success("Matrix access token saved")
  2908. else:
  2909. _ask("MATRIX_USER_ID", "User ID (@bot:server)")
  2910. if _ask("MATRIX_PASSWORD", "Password", password=True):
  2911. print_success("Matrix credentials saved")
  2912. if token or get_env_value("MATRIX_PASSWORD"):
  2913. want_e2ee = prompt_yes_no("Enable end-to-end encryption (E2EE)?", False)
  2914. if want_e2ee:
  2915. save_env_value("MATRIX_ENCRYPTION", "true")
  2916. print_success("E2EE enabled")
  2917. try:
  2918. from pm import sync_venv
  2919. print_info("Preparing Matrix dependencies...")
  2920. sync_venv(["matrix"], explicit=True)
  2921. print_success("Matrix dependencies prepared. Restart Hermes to use them.")
  2922. except Exception as exc:
  2923. print_warning(f"Matrix dependencies could not be prepared: {exc}")
  2924. print_info("Run `hermes pm install`, then restart Hermes.")
  2925. print_info("🔒 Security: Restrict who can use your bot")
  2926. print_info(" Matrix user IDs look like @username:server")
  2927. allowed_users = prompt("Allowed user IDs (comma-separated, leave empty for open access)")
  2928. if allowed_users:
  2929. save_env_value("MATRIX_ALLOWED_USERS", allowed_users.replace(" ", ""))
  2930. print_success("Matrix allowlist configured")
  2931. else:
  2932. print_info("⚠️ No allowlist set - anyone who can message the bot can use it!")
  2933. for line in ("📬 Home Room: where Hermes delivers cron job results and notifications.",
  2934. " Room IDs look like !abc123:server (shown in Element room settings)",
  2935. " You can also set this later by typing /set-home in a Matrix room.",
  2936. "Leave blank to clear a previously saved home room (cron / notifications)."):
  2937. print_info(line)
  2938. home_room = prompt("Home room ID (leave empty to set later with /set-home)").strip()
  2939. if home_room:
  2940. save_env_value("MATRIX_HOME_ROOM", home_room)
  2941. elif remove_env_value("MATRIX_HOME_ROOM"):
  2942. print_info("Home room cleared.")
  2943. _YAML_BRIDGE = ( # (yaml key, env var, kind) for apply_yaml_bridge
  2944. ("require_mention", "MATRIX_REQUIRE_MENTION", "lower"), ("process_notices", "MATRIX_PROCESS_NOTICES", "lower"),
  2945. ("session_scope", "MATRIX_SESSION_SCOPE", "lower"), ("auto_thread", "MATRIX_AUTO_THREAD", "lower"),
  2946. ("dm_mention_threads", "MATRIX_DM_MENTION_THREADS", "lower"),
  2947. ("allowed_users", "MATRIX_ALLOWED_USERS", "csv"), ("free_response_rooms", "MATRIX_FREE_RESPONSE_ROOMS", "csv"),
  2948. ("allowed_rooms", "MATRIX_ALLOWED_ROOMS", "csv"), ("ignore_user_patterns", "MATRIX_IGNORE_USER_PATTERNS", "csv"),
  2949. ("max_message_length", "MATRIX_MAX_MESSAGE_LENGTH", "str"),
  2950. )
  2951. def _apply_yaml_config(yaml_cfg: dict, matrix_cfg: dict) -> dict | None:
  2952. """``apply_yaml_config_fn`` (#24849): config.yaml matrix: keys → MATRIX_* env (env wins; skipped under a
  2953. multiplexed secondary profile's scope) + ``PlatformConfig.extra`` (extra-first readers)."""
  2954. return _apply_yaml_bridge(matrix_cfg, _YAML_BRIDGE)
  2955. def _is_connected(config) -> bool:
  2956. """Connected = homeserver + token (or password). Reads via hermes_cli.gateway.get_env_value so
  2957. setup-status callers that patch it see the same value; PlatformConfig extras are honored."""
  2958. extra = getattr(config, "extra", {}) or {}
  2959. import hermes_cli.gateway as gateway_mod
  2960. homeserver = extra.get("homeserver") or gateway_mod.get_env_value("MATRIX_HOMESERVER") or ""
  2961. token = (getattr(config, "token", None) or gateway_mod.get_env_value("MATRIX_ACCESS_TOKEN")
  2962. or gateway_mod.get_env_value("MATRIX_PASSWORD") or "")
  2963. return bool(str(homeserver).strip() and str(token).strip())
  2964. def register(ctx) -> None:
  2965. from .adapter_hint import PLATFORM_HINT
  2966. from .send_targets import SEND_ENTRY_KWARGS
  2967. from .dashboard_card import DASHBOARD_CARD
  2968. from . import gateway_env # env -> GatewayConfig bridge (gateway.config_env)
  2969. ctx.register_platform(
  2970. **SEND_ENTRY_KWARGS, # send_message target syntax + routing
  2971. name="matrix", label="Matrix", adapter_factory=MatrixAdapter, check_fn=matrix_deps_present,
  2972. **DASHBOARD_CARD,
  2973. ensure_deps_fn=ensure_matrix_deps, is_connected=_is_connected,
  2974. required_env=["MATRIX_HOMESERVER", "MATRIX_ACCESS_TOKEN"], install_hint="pip install 'mautrix[encryption]'",
  2975. setup_fn=interactive_setup, apply_yaml_config_fn=_apply_yaml_config, cron_deliver_env_var="MATRIX_HOME_ROOM",
  2976. standalone_sender_fn=_standalone_send, max_message_length=DEFAULT_MAX_MESSAGE_LENGTH, emoji="🔐",
  2977. allow_update_command=True,
  2978. platform_hint=PLATFORM_HINT,
  2979. display_tier="medium",
  2980. env_overrides=gateway_env.ENV_OVERRIDES,
  2981. env_enable_credentials=gateway_env.ENV_ENABLE_CREDENTIALS, **gateway_env.AUTHZ,
  2982. )