session_envelope.py 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356
  1. """Owner-only durable native input codec; never a client-supplied wire format.
  2. Ordinary context and local media are retained without serializing delegated trust.
  3. Multiplex callbacks bind current connector ownership; roles require fresh preflight.
  4. Relay snapshots bind the authenticated connector and exact source; replay rechecks both.
  5. """
  6. import asyncio
  7. from copy import copy, deepcopy
  8. from dataclasses import replace
  9. from datetime import datetime
  10. import json
  11. import logging
  12. import os
  13. from gateway.platforms.event import MessageEvent, MessageType
  14. from gateway.session import SessionSource
  15. from gateway.session_ingress_media import capture_native_media, restore_native_media
  16. from hermes_state_runtime import RuntimeStoreError
  17. logger = logging.getLogger(__name__)
  18. _EVENT_FIELDS = (
  19. 'user_id', 'user_name', 'message_id', 'platform_update_id',
  20. 'reply_to_message_id', 'reply_to_text', 'reply_to_author_id',
  21. 'reply_to_author_name', 'reply_to_is_own_message', 'allow_gateway_control',
  22. )
  23. # ``reply_anchor_override`` = '' is Telegram topic transfer's "do not quote the root DM" (#139136).
  24. _CONTEXT_FIELDS = ('auto_skill', 'channel_prompt', 'channel_context', 'reply_expected', 'reply_anchor_override',
  25. 'edit_revision')
  26. # Closed metadata contract: only the keys the Baileys adapter stamps on ordinary inbound
  27. # (``WhatsAppAdapter._build_message_event``) cross native admission; any other key refuses.
  28. _WHATSAPP_METADATA = frozenset({'whatsapp_native_type', 'whatsapp_native', 'whatsapp_from_owner'})
  29. # Top-level ``nativeMetadata`` keys the bridge emits (scripts/whatsapp-bridge/bridge_helpers.js).
  30. _WHATSAPP_NATIVE_KEYS = frozenset({'video', 'audio', 'sticker', 'location', 'contact', 'contacts',
  31. 'reaction', 'poll', 'pollUpdate'})
  32. _WHATSAPP_NATIVE_MAX_BYTES = 16 * 1024
  33. _MEDIA_FIELDS = ('media_urls', 'media_types', 'media_text_inlined', 'media_filenames')
  34. def _native_metadata(event):
  35. """JSON projection of the adapter metadata a native replay keeps; ``None`` refuses the event.
  36. An oversized ``whatsapp_native`` (vCards with photos) is dropped, never refused."""
  37. metadata = event.metadata
  38. if not metadata:
  39. return {}
  40. if (not isinstance(metadata, dict) or event.source.platform.value != 'whatsapp'
  41. or not set(metadata) <= _WHATSAPP_METADATA):
  42. return None
  43. kind, native = metadata.get('whatsapp_native_type'), metadata.get('whatsapp_native')
  44. if (kind is not None and not (isinstance(kind, str) and 0 < len(kind) <= 64)
  45. or metadata.get('whatsapp_from_owner') not in (None, True)
  46. or native is not None and not (isinstance(native, dict) and set(native) <= _WHATSAPP_NATIVE_KEYS)):
  47. return None
  48. projected = {key: metadata[key] for key in ('whatsapp_native_type', 'whatsapp_from_owner') if key in metadata}
  49. if native is not None:
  50. try:
  51. encoded = json.dumps(native, ensure_ascii=False, allow_nan=False)
  52. except (TypeError, ValueError):
  53. return None
  54. if len(encoded.encode()) <= _WHATSAPP_NATIVE_MAX_BYTES:
  55. projected['whatsapp_native'] = json.loads(encoded)
  56. return projected
  57. def _adapter_event(event, **changes):
  58. """An adapter's event at the envelope boundary: an absent media list (``None``) is no media.
  59. Any other non-list still reaches ``_validate_native`` and refuses."""
  60. changes.update({name: [] for name in _MEDIA_FIELDS if getattr(event, name) is None})
  61. return _drop_remote_media(replace(event, **changes) if changes else event)
  62. def _drop_remote_media(event):
  63. """An adapter that could not cache a download leaves its remote URL in ``media_urls`` (DingTalk
  64. always does). Capture takes only local files, so that one entry refused the whole message, text
  65. included: drop it and tell the agent instead. Malformed media lists still reach validation."""
  66. urls, types = event.media_urls, event.media_types
  67. if not isinstance(event.text, str) or _media_clause(event) is not None or all(map(os.path.isabs, urls)):
  68. return event
  69. kept = [index for index, url in enumerate(urls) if os.path.isabs(url)]
  70. notes = [f"[The user sent an attachment ({types[index] if types else 'file'}) that could not be retrieved.]"
  71. for index in range(len(urls)) if index not in kept]
  72. def keep(values):
  73. return [values[index] for index in kept] if values else values
  74. return replace(event, text='\n'.join(filter(None, [event.text, *notes])), media_urls=keep(urls),
  75. media_types=keep(types), media_text_inlined=keep(event.media_text_inlined),
  76. media_filenames=keep(event.media_filenames))
  77. def _refuse(event, reason, clause):
  78. """Name the refused clause in gateway.log and on the error; the wire reason stays stable."""
  79. source = event.source
  80. logger.warning('Native admission refused: %s (%s) platform=%s chat=%s message=%s', reason, clause,
  81. getattr(getattr(source, 'platform', None), 'value', None), getattr(source, 'chat_id', None),
  82. event.message_id)
  83. raise RuntimeStoreError(reason, field=clause)
  84. def _media_clause(event):
  85. urls, types, inlined = event.media_urls, event.media_types, event.media_text_inlined
  86. if not isinstance(urls, list) or not all(isinstance(item, str) for item in urls):
  87. return 'media_urls'
  88. if not isinstance(types, list) or not all(isinstance(item, str) for item in types):
  89. return 'media_types'
  90. if not isinstance(inlined, list) or not all(item is None or type(item) is bool for item in inlined):
  91. return 'media_text_inlined'
  92. if len(types) not in (0, len(urls)):
  93. return 'media_types_length'
  94. if len(inlined) not in (0, len(urls)):
  95. return 'media_text_inlined_length'
  96. names = event.media_filenames
  97. if not isinstance(names, list) or not all(isinstance(item, str) for item in names):
  98. return 'media_filenames'
  99. if len(names) not in (0, len(urls)):
  100. return 'media_filenames_length'
  101. return None
  102. def _event_clause(runner, event, provenance, fresh_roles):
  103. source = event.source
  104. if source is None:
  105. return 'source'
  106. if not isinstance(event.text, str):
  107. return 'text'
  108. if not isinstance(event.message_type, MessageType):
  109. return 'message_type'
  110. # The ingress router's own classifier: ``/tmp/x is broken`` is text, not a command.
  111. if event.get_command():
  112. return 'command'
  113. if event.internal:
  114. return 'internal'
  115. if _native_metadata(event) is None:
  116. return 'metadata'
  117. if event.prompt_response:
  118. return 'prompt_response'
  119. if source.role_authorized and not fresh_roles:
  120. return 'role_authorized_without_fresh_roles'
  121. if source.delivered_via_upstream_relay and not (provenance and 'relay' in provenance):
  122. return 'upstream_relay_without_provenance'
  123. if source.profile_route_rejected:
  124. return 'profile_route_rejected'
  125. if getattr(source, '_authorization_profile_home', None) is not None and provenance is None:
  126. return 'authorization_home_without_provenance'
  127. if getattr(runner.config, 'multiplex_profiles', False) and provenance is None:
  128. return 'multiplex_without_provenance'
  129. return None
  130. def _validate_native(runner, event, provenance=None, fresh_roles=False):
  131. source = event.source
  132. if (clause := _event_clause(runner, event, provenance, fresh_roles)) is not None:
  133. _refuse(event, 'invalid_params', clause)
  134. if provenance is not None:
  135. from gateway.session_ingress_context import restore_provenance
  136. restore_provenance(runner, source, provenance)
  137. delegated = fresh_roles or bool(provenance and 'relay' in provenance)
  138. if not delegated:
  139. # An adapter declaring ``authorization_is_upstream`` (A2A peers: bearer-token
  140. # authenticated in do_POST) owns the whole authorization, so its fresh native inputs
  141. # carry no relay seal to derive delegation from. Without this they fell to the
  142. # principal allowlist and — with no {PLATFORM}_ALLOWED_USERS — the admission
  143. # re-check denied what the inbound filter had just accepted (#139199).
  144. delegated = runner._adapter_flag(
  145. source.platform, "authorization_is_upstream", runner._adapter_profile_for_source(source))
  146. if not runner._is_user_authorized_for_source(source, allow_adapter_delegation=delegated):
  147. _refuse(event, 'permission_denied', 'user_not_authorized')
  148. for name in ('channel_prompt', 'channel_context', 'reply_anchor_override'):
  149. if getattr(event, name) is not None and not isinstance(getattr(event, name), str):
  150. _refuse(event, 'invalid_params', name)
  151. if event.reply_expected is not None and type(event.reply_expected) is not bool:
  152. _refuse(event, 'invalid_params', 'reply_expected')
  153. skill = event.auto_skill
  154. if not (skill is None or isinstance(skill, str)
  155. or isinstance(skill, list) and all(isinstance(item, str) for item in skill)):
  156. _refuse(event, 'invalid_params', 'auto_skill')
  157. if (clause := _media_clause(event)) is not None:
  158. _refuse(event, 'invalid_params', clause)
  159. encoded_source = source.to_dict()
  160. encoded_source['is_bot'] = source.is_bot
  161. restored_source = SessionSource.from_dict(encoded_source)
  162. restored_source.is_bot = source.is_bot
  163. if provenance is not None:
  164. restore_provenance(runner, restored_source, provenance)
  165. adapter = runner._adapter_for_source(source)
  166. if adapter is None or runner._adapter_for_source(restored_source) is not adapter:
  167. _refuse(event, 'not_found', 'adapter' if adapter is None else 'adapter_mismatch')
  168. return encoded_source
  169. def snapshot_native(runner, event):
  170. from gateway.session_ingress_context import capture_provenance
  171. provenance = capture_provenance(runner, event)
  172. return _snapshot_native(runner, _adapter_event(event), provenance)
  173. async def prepare_native(runner, event):
  174. from gateway.session_ingress_context import capture_provenance, reauthorize_roles
  175. provenance = capture_provenance(runner, event)
  176. # Freeze caller-owned identity and content before the first network yield.
  177. # Preserve dynamic trust fields too: validation must reject forged ones,
  178. # not silently discard them while freezing the caller's source identity.
  179. frozen = _adapter_event(event, source=copy(event.source))
  180. fresh_roles = await reauthorize_roles(runner, frozen.source, provenance)
  181. encoded_source = _validate_native(runner, frozen, provenance, fresh_roles)
  182. # Copy + SHA-256 + fsyncs of up to max_inbound_media_bytes stay off the owner loop; the
  183. # copied context carries the admission's capture lease.
  184. media = None
  185. if frozen.media_urls:
  186. from gateway.session_ingress_media import _lease_scope, abandon_capture, release_abandoned_capture
  187. from gateway.session_runtime_workers import track_mutation
  188. scope = _lease_scope.get()
  189. work = asyncio.to_thread(capture_native_media, frozen.media_urls)
  190. capture = (track_mutation(scope.authority, work) if scope is not None and scope.authority is not None
  191. else asyncio.create_task(work))
  192. try:
  193. # Cancelling this waiter must not cancel the thread's completion observer: the thread
  194. # may publish a path after the caller's lease context has already exited.
  195. media = await asyncio.shield(capture)
  196. except asyncio.CancelledError:
  197. if scope is not None and scope.authority is not None:
  198. scope.abandoned = True
  199. def finished(done):
  200. if not done.cancelled():
  201. done.exception() # observe a failed copy too; partial publishes still collect
  202. track_mutation(scope.authority, release_abandoned_capture(scope))
  203. capture.add_done_callback(finished)
  204. raise
  205. except BaseException:
  206. await abandon_capture(scope)
  207. raise
  208. return _snapshot_native(runner, frozen, provenance, fresh_roles, encoded_source, media)
  209. def _snapshot_native(runner, event, provenance, fresh_roles=False, encoded_source=None, media=None):
  210. if encoded_source is None:
  211. encoded_source = _validate_native(runner, event, provenance, fresh_roles)
  212. envelope = {'source': encoded_source,
  213. 'route': runner.session_store._generate_session_key(event.source),
  214. 'event': deepcopy({name: getattr(event, name) for name in _EVENT_FIELDS}),
  215. 'timestamp': event.timestamp.isoformat()}
  216. if event.source.platform.value == 'webhook':
  217. from gateway.platforms.webhook_delivery import route_digest, snapshot_destination
  218. adapter = runner._adapter_for_source(event.source)
  219. if provenance is None:
  220. raise RuntimeStoreError('permission_denied')
  221. delivery = snapshot_destination(adapter, adapter._delivery_info.get(event.source.chat_id))
  222. envelope['webhook_delivery'] = delivery
  223. envelope['webhook_route'] = route_digest(adapter, event.source.chat_id)
  224. if event.source.role_authorized:
  225. envelope['reauthorize'] = 'roles'
  226. if provenance is not None:
  227. envelope['provenance'] = provenance
  228. # Omit new defaults so an identical retry of an older text admission retains
  229. # its fingerprint. Explicit context (including an empty skill list) is exact.
  230. envelope['event'].update({name: deepcopy(getattr(event, name)) for name in _CONTEXT_FIELDS
  231. if getattr(event, name) is not None})
  232. if event.inherit_channel_pin is True: # synthetic goal/resume turn reuses the session's pins (#126109)
  233. envelope['event']['inherit_channel_pin'] = True
  234. if metadata := _native_metadata(event):
  235. envelope['event']['metadata'] = metadata
  236. # COMMAND that passed admission is path text (``/Users/x is broken``): replay it as text.
  237. if event.message_type not in (MessageType.TEXT, MessageType.COMMAND):
  238. envelope['message_type'] = event.message_type.value
  239. if event.media_urls:
  240. envelope['media'] = media if media is not None else capture_native_media(event.media_urls)
  241. envelope['event'].update(media_types=list(event.media_types),
  242. media_text_inlined=list(event.media_text_inlined))
  243. if any(event.media_filenames): # absent when unnamed: older admissions keep their fingerprint
  244. envelope['event']['media_filenames'] = list(event.media_filenames)
  245. # Keep the private dispatch key so previously committed text-only rows recover
  246. # under the same authority; optional media/context fields extend that envelope.
  247. payload = {'text': event.text, 'native_text_v1': envelope}
  248. # Only an exact persisted legacy retry retains its old fingerprint. New
  249. # ordinary admissions must bind homes too, including execution after restart.
  250. if provenance is not None and not getattr(runner.config, 'multiplex_profiles', False):
  251. from hermes_state_runtime import list_session_admissions
  252. from gateway.session_authorities import active_authority
  253. authority = active_authority(runner)
  254. entry = runner.session_store.lookup_by_session_key(envelope['route'])
  255. if entry is not None:
  256. legacy = deepcopy(payload)
  257. legacy['native_text_v1'].pop('provenance')
  258. for row in list_session_admissions(authority.db, session_id=entry.session_id, pending_only=False):
  259. if row['request_id'] == event.message_id and row['payload'] == legacy:
  260. return legacy
  261. return payload
  262. def restore_native_source(payload, runner=None):
  263. """restore_native's source (provenance included) without re-verifying the captured media:
  264. admission needs only the route; execution's restore_native still checks every byte."""
  265. envelope = payload['native_text_v1']
  266. source = SessionSource.from_dict(envelope['source'])
  267. source.is_bot = envelope['source']['is_bot']
  268. # Private descriptor requests a fresh check, never supplies the verdict.
  269. source.role_authorized = envelope.get('reauthorize') == 'roles'
  270. if 'provenance' in envelope:
  271. from gateway.session_ingress_context import callback_runner, restore_provenance
  272. runner = runner or callback_runner()
  273. if runner is not None:
  274. restore_provenance(runner, source, envelope['provenance'])
  275. return source
  276. def restore_native(payload, runner=None):
  277. envelope = payload['native_text_v1']
  278. source = restore_native_source(payload, runner)
  279. timestamp = datetime.fromisoformat(envelope['timestamp'])
  280. if timestamp.tzinfo is not None and timestamp.timestamp() == 0:
  281. # Epoch 0 pins the retry fingerprint of producers with no provider time (relay, webhook,
  282. # automation); the turn records local time, as main's arrival-stamped event did.
  283. timestamp = datetime.now()
  284. event = MessageEvent(text=payload['text'], source=source, timestamp=timestamp,
  285. message_type=MessageType(envelope.get('message_type', 'text')),
  286. media_urls=restore_native_media(envelope.get('media', [])),
  287. **deepcopy(envelope['event']))
  288. if 'automation' in envelope:
  289. event.internal = True
  290. if envelope['automation'].get('heartbeat'):
  291. event._heartbeat_session_id = envelope['automation']['heartbeat']
  292. event.metadata = {'gateway_session_key': envelope['route'],
  293. 'gateway_session_id': envelope['automation']['owner']}
  294. from gateway.session_automation import automation_display_metadata, automation_notification_metadata
  295. event.metadata.update(automation_notification_metadata(envelope['automation']))
  296. event.metadata.update(automation_display_metadata(envelope['automation']))
  297. return event
  298. async def check_native_route(runner, payload, session_id, available_source, adapter):
  299. """Read-only preflight: route/auth rejection must never consume a queued row."""
  300. if 'automation' in payload['native_text_v1']:
  301. from gateway.session_automation import check_automation_route
  302. return check_automation_route(runner, payload, session_id, available_source, adapter)
  303. event = restore_native(payload, runner)
  304. # Validate the stored sender without recapturing files or trusting the binding caller.
  305. from gateway.session_ingress_context import reauthorize_roles
  306. provenance = payload['native_text_v1'].get('provenance')
  307. fresh_roles = await reauthorize_roles(runner, event.source, provenance)
  308. _validate_native(runner, event, provenance, fresh_roles)
  309. route = payload['native_text_v1']['route']
  310. store = runner.session_store
  311. if (store._generate_session_key(event.source) != route
  312. or store._generate_session_key(available_source) != route):
  313. raise RuntimeStoreError('admission_conflict')
  314. entry = store.lookup_by_session_key(route)
  315. if entry is None or entry.session_id != session_id:
  316. raise RuntimeStoreError('admission_conflict')
  317. if adapter is None or runner._adapter_for_source(event.source) is not adapter:
  318. raise RuntimeStoreError('not_found')
  319. if event.source.platform.value == 'webhook':
  320. from gateway.platforms.webhook_delivery import route_digest, validate_destination
  321. envelope = payload['native_text_v1']
  322. validate_destination(envelope.get('webhook_delivery'))
  323. if envelope.get('webhook_route') != route_digest(adapter, event.source.chat_id):
  324. raise RuntimeStoreError('admission_conflict')
  325. return event.source, route