| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724 |
- """BlueBubbles iMessage platform adapter: local BlueBubbles macOS server for outbound REST sends and
- inbound webhooks (text, media attachments, typing indicators, read receipts)."""
- import asyncio
- import json
- import logging
- import os
- import re
- import uuid
- from collections import OrderedDict
- from contextlib import suppress
- from datetime import datetime
- from pathlib import Path
- from typing import Any, Dict, List, Optional
- from urllib.parse import parse_qs, quote
- import httpx
- from gateway.config import Platform, PlatformConfig
- from gateway.platforms._shared import extra_or_secret as _extra_or_secret, get_scoped_secret as _get_scoped_secret
- from gateway.platforms._shared import config_connected_extra
- from gateway.platforms.base import (
- BasePlatformAdapter, SendResult,
- cache_image_from_bytes_async, cache_audio_from_bytes_async, cache_document_from_bytes_async,
- )
- from gateway.platforms.event import MessageEvent, MessageType
- from gateway.platforms.media_cache import ext_for_mime
- from gateway.platforms.helpers import compile_mention_patterns, strip_markdown
- from utils import TRUTHY_STRINGS
- # Historical BlueBubbles mime→ext maps, preserved verbatim as overrides for the shared dispatch in
- # gateway.platforms.media_cache. Both maps are CLOSED: unlisted mimes fall back to .jpg / .mp3.
- _BLUEBUBBLES_IMAGE_EXT_OVERRIDES = {
- "image/jpeg": ".jpg", "image/png": ".png", "image/gif": ".gif", "image/webp": ".webp",
- "image/heic": ".jpg", "image/heif": ".jpg", "image/tiff": ".jpg", # historical mapping
- }
- _BLUEBUBBLES_AUDIO_EXT_OVERRIDES = {
- "audio/mp3": ".mp3", "audio/mpeg": ".mp3", "audio/ogg": ".ogg", "audio/wav": ".wav",
- "audio/x-caf": ".mp3", "audio/mp4": ".m4a",
- "audio/aac": ".m4a", # historical mapping (shared table says .aac)
- }
- logger = logging.getLogger(__name__)
- DEFAULT_WEBHOOK_HOST = "127.0.0.1"
- # Webhook events are small JSON/form payloads (attachments come through the REST API); 1 MiB keeps
- # oversized/chunked bodies from buffering unbounded.
- _WEBHOOK_MAX_BODY_BYTES = 1_048_576
- DEFAULT_WEBHOOK_PORT = 8645
- DEFAULT_WEBHOOK_PATH = "/bluebubbles-webhook"
- MAX_TEXT_LENGTH = 4000
- # iMessage has no stable bot mention identity (unlike <@U...>/@botname/MXID), so
- # `require_mention: true` without custom aliases uses Hermes wake words.
- DEFAULT_MENTION_PATTERNS = [r"(?<![\w@])@?hermes\s+agent\b[,:\-]?", r"(?<![\w@])@?hermes\b[,:\-]?"]
- # Tapback associatedMessageType codes: 2000-2005 added, 3000-3005 removed (love, like, dislike, ...).
- _TAPBACK_CODES = {*range(2000, 2006), *range(3000, 3006)}
- _MESSAGE_EVENTS = {"new-message", "message", "updated-message"} # webhook event types carrying user messages
- _PHONE_RE = re.compile(r"\+?\d{7,15}")
- _EMAIL_RE = re.compile(r"[\w.+-]+@[\w-]+\.[\w.]+")
- _PAGINATION_SUFFIX_RE = re.compile(r"\s*\(\d+/\d+\)$")
- _ADDRESS_RE = re.compile(r"^\+\d+")
- _GUID_CACHE_SIZE = 500 # LRU cap for resolved chat-GUID lookups
- _LOCAL_HOSTS = {"0.0.0.0", "127.0.0.1", "localhost", "::"}
- def _redact(text: str) -> str:
- """Redact phone numbers and emails from log output."""
- return _EMAIL_RE.sub("[REDACTED]", _PHONE_RE.sub("[REDACTED]", text))
- def check_bluebubbles_requirements() -> bool:
- try:
- import aiohttp
- except ImportError:
- return False
- return True
- def _normalize_server_url(raw: str) -> str:
- value = (raw or "").strip()
- if value and not re.match(r"^https?://", value, flags=re.IGNORECASE):
- value = f"http://{value}"
- return value.rstrip("/")
- def _closed_ext(mime: str, overrides: dict[str, str], fallback: str) -> str:
- """Historical maps were closed: unlisted mimes fall back without consulting mimetypes."""
- return ext_for_mime(mime, overrides=overrides, use_defaults=False, use_mimetypes=False,
- fallback=fallback) or fallback
- def _temp_guid() -> str:
- return f"temp-{datetime.utcnow().timestamp()}"
- def _ok():
- """Plain ``ok`` acknowledgement for webhook events we accept but don't process."""
- from aiohttp import web
- return web.Response(text="ok")
- class BlueBubblesAdapter(BasePlatformAdapter):
- # Answers /p/<profile>/... on the default listener for a served secondary (shared_ingress).
- serves_profile_prefix: bool = True
- platform = Platform.BLUEBUBBLES
- SUPPORTS_MESSAGE_EDITING = False
- MAX_MESSAGE_LENGTH = MAX_TEXT_LENGTH
- splits_long_messages = True # send() chunks via truncate_message(MAX_MESSAGE_LENGTH)
- def __init__(self, config: PlatformConfig):
- super().__init__(config, Platform.BLUEBUBBLES)
- extra = config.extra or {}
- self.server_url = _normalize_server_url(_extra_or_secret(extra, "server_url", "BLUEBUBBLES_SERVER_URL"))
- self.password = extra.get("password") or _get_scoped_secret("BLUEBUBBLES_PASSWORD", "")
- self.webhook_host = _extra_or_secret(extra, "webhook_host", "BLUEBUBBLES_WEBHOOK_HOST", DEFAULT_WEBHOOK_HOST)
- self.webhook_port = int(_extra_or_secret(extra, "webhook_port", "BLUEBUBBLES_WEBHOOK_PORT", str(DEFAULT_WEBHOOK_PORT)))
- path = str(_extra_or_secret(extra, "webhook_path", "BLUEBUBBLES_WEBHOOK_PATH", DEFAULT_WEBHOOK_PATH))
- self.webhook_path = path if path.startswith("/") else f"/{path}"
- self.send_read_receipts = bool(extra.get("send_read_receipts", True))
- _require_mention = extra.get("require_mention")
- if _require_mention is None:
- _require_mention = _get_scoped_secret("BLUEBUBBLES_REQUIRE_MENTION")
- self.require_mention = str(_require_mention).strip().lower() in TRUTHY_STRINGS
- self._mention_patterns = self._compile_mention_patterns(
- extra["mention_patterns"] if "mention_patterns" in extra else _get_scoped_secret("BLUEBUBBLES_MENTION_PATTERNS"))
- self.client: Optional[httpx.AsyncClient] = None
- self._runner = None
- self._private_api_enabled: Optional[bool] = None
- self._helper_connected: bool = False
- self._guid_cache: OrderedDict[str, str] = OrderedDict()
- # --- API helpers ---
- def _api_url(self, path: str) -> str:
- return f"{self.server_url}{path}{'&' if '?' in path else '?'}password={quote(self.password, safe='')}"
- @staticmethod
- def _compile_mention_patterns(raw: Any) -> list[re.Pattern]:
- """Compile group-mention wake words; ``raw`` is a list, a raw env string (JSON list or
- comma/newline-separated), or None (Hermes defaults)."""
- return compile_mention_patterns(raw, log_prefix="bluebubbles", defaults=DEFAULT_MENTION_PATTERNS,
- logger_=logger)
- def _message_matches_mention_patterns(self, text: str) -> bool:
- return bool(text) and any(pattern.search(text) for pattern in self._mention_patterns)
- def _clean_mention_text(self, text: str) -> str:
- """Strip a leading wake word only — patterns are regexes, so stripping anywhere later in the
- prompt could delete ordinary words."""
- stripped = (text or "").lstrip()
- for pattern in self._mention_patterns:
- if match := pattern.match(stripped):
- return stripped[match.end():].lstrip(" ,:-") or text
- return text
- async def _api_json(self, method: str, path: str, **kwargs) -> dict[str, Any]:
- """Authenticated request to the BlueBubbles REST API; raises on HTTP errors, returns decoded JSON."""
- assert self.client is not None
- res = await getattr(self.client, method)(self._api_url(path), **kwargs)
- res.raise_for_status()
- return res.json()
- async def _api_get(self, path: str) -> dict[str, Any]:
- return await self._api_json("get", path)
- async def _api_post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
- return await self._api_json("post", path, json=payload)
- async def _post_message(self, path: str, payload: dict[str, Any]) -> SendResult:
- """POST a message payload and wrap the outcome as a SendResult."""
- try:
- res = await self._api_post(path, payload)
- data = res.get("data") or {}
- msg_id = str(data.get("guid") or data.get("messageGuid") or "ok")
- return SendResult(success=True, message_id=msg_id, raw_response=res)
- except Exception as exc:
- return SendResult(success=False, error=str(exc) or type(exc).__name__)
- async def _private_api_chat_call(self, chat_id: str, action: str, method: str) -> bool:
- """Fire a private-API chat action (typing/read); True only if the call was made."""
- if not self._private_api_enabled or not self._helper_connected or not self.client:
- return False
- with suppress(Exception):
- if guid := await self._resolve_chat_guid(chat_id):
- url = self._api_url(f"/api/v1/chat/{quote(guid, safe='')}/{action}")
- await getattr(self.client, method)(url, timeout=5)
- return True
- return False
- # --- Lifecycle ---
- async def connect(self, *, is_reconnect: bool = False) -> bool:
- if not self.server_url or not self.password:
- logger.error("[bluebubbles] BLUEBUBBLES_SERVER_URL and BLUEBUBBLES_PASSWORD are required")
- return False
- from aiohttp import web
- # Tighter keepalive so idle CLOSE_WAIT drains promptly.
- # See #18451.
- from gateway.platforms._http_client_limits import platform_httpx_limits
- self.client = httpx.AsyncClient(timeout=30.0, limits=platform_httpx_limits())
- try:
- await self._api_get("/api/v1/ping")
- info = await self._api_get("/api/v1/server/info")
- server_data = (info or {}).get("data", {})
- self._private_api_enabled = bool(server_data.get("private_api"))
- self._helper_connected = bool(server_data.get("helper_connected"))
- logger.info("[bluebubbles] connected to %s (private_api=%s, helper=%s)",
- self.server_url, self._private_api_enabled, self._helper_connected)
- except Exception as exc:
- logger.error("[bluebubbles] cannot reach server at %s: %s", self.server_url, exc)
- await self._close_client()
- return False
- # client_max_size makes aiohttp enforce the cap on every read path, incl. chunked requests
- # with no Content-Length.
- # Explicit body cap: BlueBubbles webhook events are small JSON (or form-encoded) payloads.
- # client_max_size makes aiohttp enforce the cap on every read path — including chunked requests that
- # carry no Content-Length (same pattern as webhook.py / raft, #58536/#58902).
- app = web.Application(client_max_size=_WEBHOOK_MAX_BODY_BYTES)
- app.router.add_get("/health", lambda _: web.Response(text="ok"))
- app.router.add_post(self.webhook_path, self._handle_webhook)
- # The webhook auth value rides in the query string (BlueBubbles cannot send custom headers)
- # — keep it out of aiohttp access logs.
- # Shared-listener mode (multiplex secondary): no bind; served at /p/<profile>/<webhook_path>.
- from gateway.platforms.shared_ingress import bind_listener
- self._runner = await bind_listener(
- self, app, self.webhook_host, self.webhook_port, self.webhook_path, access_log=None)
- self._mark_connected()
- if self._runner is not None:
- logger.info("[bluebubbles] webhook listening on http://%s:%s%s", self.webhook_host, self.webhook_port,
- self.webhook_path)
- await self._register_webhook() # the server only sends events to webhooks registered via its API
- # Plugin-registered native handlers (ctx.register_platform_handler).
- self._wire_plugin_handlers(None)
- return True
- async def _close_client(self) -> None:
- if self.client:
- await self.client.aclose()
- self.client = None
- async def disconnect(self) -> None:
- await self._unregister_webhook()
- await self._close_client()
- if self._runner:
- await self._runner.cleanup()
- self._runner = None
- self._mark_disconnected()
- @property
- def _webhook_url(self) -> str:
- """External webhook URL for BlueBubbles registration (local binds → localhost). In
- shared-listener mode it is the default listener's ``/p/<profile>/`` URL."""
- shared = getattr(self, "_shared_ingress_url", None)
- if shared:
- return shared
- host = "localhost" if self.webhook_host in _LOCAL_HOSTS else self.webhook_host
- return f"http://{host}:{self.webhook_port}{self.webhook_path}"
- def _webhook_register_url_with(self, password_param: str) -> str:
- return f"{self._webhook_url}?password={password_param}" if self.password else self._webhook_url
- @property
- def _webhook_register_url(self) -> str:
- """Registered webhook URL with the password as a query param: BlueBubbles posts to the exact
- registered URL and cannot set custom headers, so this is the only way to authenticate inbound
- webhooks without disabling auth."""
- return self._webhook_register_url_with(quote(self.password, safe=""))
- @property
- def _webhook_register_url_for_log(self) -> str:
- return self._webhook_register_url_with("***")
- async def _find_registered_webhooks(self, url: str) -> list:
- """Return list of BB webhook entries matching *url*."""
- with suppress(Exception):
- data = (await self._api_get("/api/v1/webhook")).get("data")
- if isinstance(data, list):
- return [wh for wh in data if wh.get("url") == url]
- return []
- async def _register_webhook(self) -> bool:
- """Register this webhook URL, reusing an existing registration if present (crash resilience —
- avoids duplicates after an unclean shutdown)."""
- if not self.client:
- return False
- webhook_url, log_url = self._webhook_register_url, self._webhook_register_url_for_log
- if await self._find_registered_webhooks(webhook_url):
- logger.info("[bluebubbles] webhook already registered: %s", log_url)
- return True
- try:
- res = await self._api_post("/api/v1/webhook",
- {"url": webhook_url, "events": ["new-message", "updated-message"]})
- status = res.get("status", 0)
- if 200 <= status < 300:
- logger.info("[bluebubbles] webhook registered with server: %s", log_url)
- return True
- logger.warning("[bluebubbles] webhook registration returned status %s: %s", status, res.get("message"))
- return False
- except Exception as exc:
- logger.warning("[bluebubbles] failed to register webhook with server: %s", exc)
- return False
- async def _unregister_webhook(self) -> bool:
- """Remove *all* registrations matching our URL (cleans up crash duplicates)."""
- if not self.client:
- return False
- removed = False
- try:
- for wh in await self._find_registered_webhooks(self._webhook_register_url):
- if wh_id := wh.get("id"):
- (await self.client.delete(self._api_url(f"/api/v1/webhook/{wh_id}"))).raise_for_status()
- removed = True
- if removed:
- logger.info("[bluebubbles] webhook unregistered: %s", self._webhook_register_url_for_log)
- except Exception as exc:
- logger.debug("[bluebubbles] failed to unregister webhook (non-critical): %s", exc)
- return removed
- # --- Chat GUID resolution ---
- async def _resolve_chat_guid(self, target: str) -> Optional[str]:
- """Resolve an email/phone to a chat GUID (raw ``a;-;b`` GUIDs pass through). Matches strictly on
- ``chatIdentifier`` / ``identifier``; participant membership is intentionally NOT a fallback —
- the same contact appears in a 1:1 DM and any number of groups, so a participant match could
- leak a DM reply into a group thread. ``None`` lets the caller create a fresh DM.
- See #24157.
- """
- target = (target or "").strip()
- if not target or ";" in target:
- return target or None
- if target in self._guid_cache:
- self._guid_cache.move_to_end(target)
- return self._guid_cache[target]
- with suppress(Exception):
- payload = await self._api_post("/api/v1/chat/query", {"limit": 100, "offset": 0})
- for chat in payload.get("data", []) or []:
- if (chat.get("chatIdentifier") or chat.get("identifier")) != target:
- continue
- if guid := chat.get("guid") or chat.get("chatGuid"):
- self._guid_cache[target] = guid
- while len(self._guid_cache) > _GUID_CACHE_SIZE:
- self._guid_cache.popitem(last=False)
- return guid
- return None
- async def _create_chat_for_handle(self, address: str, message: str) -> SendResult:
- """Create a new chat by sending the first message to *address*."""
- return await self._post_message(
- "/api/v1/chat/new", {"addresses": [address], "message": message, "tempGuid": _temp_guid()})
- # --- Text sending ---
- @staticmethod
- def truncate_message(content: str, max_length: int = MAX_TEXT_LENGTH) -> list[str]:
- # Base splitter minus "(1/3)" pagination suffixes — iMessage bubbles flow naturally.
- return [_PAGINATION_SUFFIX_RE.sub("", c) for c in BasePlatformAdapter.truncate_message(content, max_length)]
- async def send(self, chat_id: str, content: str, reply_to: Optional[str] = None,
- metadata: Optional[dict[str, Any]] = None) -> SendResult:
- text = self.format_message(content)
- if not text:
- return SendResult(success=False, error="BlueBubbles send requires text")
- # Each paragraph becomes its own iMessage bubble; truncate any still too long.
- paragraphs = [p.strip() for p in re.split(r'\n\s*\n', text) if p.strip()] or [text]
- chunks = [c for para in paragraphs for c in (
- [para] if len(para) <= self.MAX_MESSAGE_LENGTH else self.truncate_message(para, self.MAX_MESSAGE_LENGTH))]
- last = SendResult(success=True)
- for chunk in chunks:
- guid = await self._resolve_chat_guid(chat_id)
- if not guid:
- if self._private_api_enabled and ("@" in chat_id or _ADDRESS_RE.match(chat_id)): # address → new chat
- return await self._create_chat_for_handle(chat_id, chunk)
- return SendResult(success=False, error=f"BlueBubbles chat not found for target: {chat_id}")
- payload: dict[str, Any] = {"chatGuid": guid, "tempGuid": _temp_guid(), "message": chunk}
- if reply_to and self._private_api_enabled and self._helper_connected:
- payload.update(method="private-api", selectedMessageGuid=reply_to, partIndex=0)
- if not (last := await self._post_message("/api/v1/message/text", payload)).success:
- return last
- return last
- # --- Media sending (outbound) ---
- async def _send_attachment(self, chat_id: str, file_path: str, filename: Optional[str] = None,
- caption: Optional[str] = None, is_audio_message: bool = False) -> SendResult:
- """Send a file attachment via BlueBubbles multipart upload."""
- if not self.client:
- return SendResult(success=False, error="Not connected")
- if not await asyncio.to_thread(os.path.isfile, file_path):
- return SendResult(success=False, error=f"File not found: {file_path}")
- guid = await self._resolve_chat_guid(chat_id)
- if not guid:
- return SendResult(success=False, error=f"Chat not found: {chat_id}")
- fname = filename or os.path.basename(file_path)
- try:
- # httpx's async multipart iterator reads file objects through a sync chunk generator —
- # read the bytes off the event-loop thread first.
- payload = await asyncio.to_thread(Path(file_path).read_bytes)
- data: dict[str, str] = {"chatGuid": guid, "name": fname, "tempGuid": uuid.uuid4().hex}
- if is_audio_message:
- data["isAudioMessage"] = "true"
- res = await self.client.post(self._api_url("/api/v1/message/attachment"), data=data, timeout=120,
- files={"attachment": (fname, payload, "application/octet-stream")})
- res.raise_for_status()
- result = res.json()
- if caption:
- await self.send(chat_id, caption)
- if result.get("status") == 200:
- rdata = result.get("data") or {}
- return SendResult(success=True, message_id=rdata.get("guid") if isinstance(rdata, dict) else None,
- raw_response=result)
- return SendResult(success=False, error=result.get("message", "Attachment upload failed"))
- except Exception as e:
- return SendResult(success=False, error=str(e))
- async def send_image(self, chat_id: str, image_url: str, caption: Optional[str] = None,
- reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None) -> SendResult:
- try:
- from gateway.platforms.base import cache_image_from_url
- return await self._send_attachment(chat_id, await cache_image_from_url(image_url), caption=caption)
- except Exception:
- return await super().send_image(chat_id, image_url, caption, reply_to)
- async def send_image_file(self, chat_id, image_path, caption=None, reply_to=None, **kw) -> SendResult:
- return await self._send_attachment(chat_id, image_path, caption=caption)
- async def send_voice(self, chat_id, audio_path, caption=None, reply_to=None, is_voice=None, **kw) -> SendResult:
- # is_voice=False is a plain audio MEDIA file (music, a sound effect): a normal attachment,
- # never an iMessage voice memo.
- return await self._send_attachment(chat_id, audio_path, caption=caption, is_audio_message=is_voice is not False)
- async def send_video(self, chat_id, video_path, caption=None, reply_to=None, **kw) -> SendResult:
- return await self._send_attachment(chat_id, video_path, caption=caption)
- async def send_document(self, chat_id, file_path, caption=None, file_name=None, reply_to=None, **kw) -> SendResult:
- return await self._send_attachment(chat_id, file_path, filename=file_name, caption=caption)
- async def send_animation(self, chat_id, animation_url, caption=None, reply_to=None, metadata=None) -> SendResult:
- return await self.send_image(chat_id, animation_url, caption, reply_to, metadata)
- # --- Typing indicators / read receipts (private API only) ---
- async def send_typing(self, chat_id: str, metadata=None) -> None:
- await self._private_api_chat_call(chat_id, "typing", "post")
- async def stop_typing(self, chat_id: str) -> None:
- await self._private_api_chat_call(chat_id, "typing", "delete")
- async def mark_read(self, chat_id: str) -> bool:
- return await self._private_api_chat_call(chat_id, "read", "post")
- # --- Chat info ---
- async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
- is_group = ";+;" in (chat_id or "")
- info: dict[str, Any] = {"name": chat_id, "type": "group" if is_group else "dm"}
- with suppress(Exception):
- if guid := await self._resolve_chat_guid(chat_id):
- res = await self._api_get(f"/api/v1/chat/{quote(guid, safe='')}?with=participants")
- data = (res or {}).get("data", {})
- info["name"] = data.get("displayName") or data.get("chatIdentifier") or chat_id
- participants = [addr for p in data.get("participants", []) or []
- if (addr := (p.get("address") or "").strip())]
- if participants:
- info["participants"] = participants
- return info
- def format_message(self, content: str) -> str:
- return strip_markdown(content, keep_link_targets=True) # iMessage auto-links bare URLs only
- # --- Inbound attachment downloading ---
- async def _download_attachment(self, att_guid: str, att_meta: dict[str, Any]) -> Optional[str]:
- """Download an attachment and cache it locally; local path or None on failure."""
- if not self.client:
- return None
- try:
- resp = await self.client.get(self._api_url(f"/api/v1/attachment/{quote(att_guid, safe='')}/download"),
- timeout=60, follow_redirects=True)
- resp.raise_for_status()
- data = resp.content
- mime = (att_meta.get("mimeType") or "").lower()
- if mime.startswith("image/"):
- return await cache_image_from_bytes_async(data, _closed_ext(mime, _BLUEBUBBLES_IMAGE_EXT_OVERRIDES, ".jpg"))
- if mime.startswith("audio/"):
- return await cache_audio_from_bytes_async(data, _closed_ext(mime, _BLUEBUBBLES_AUDIO_EXT_OVERRIDES, ".mp3"))
- # Videos, documents, and everything else
- return await cache_document_from_bytes_async(data, att_meta.get("transferName", "") or f"file_{uuid.uuid4().hex[:8]}")
- except Exception as exc:
- logger.warning("[bluebubbles] failed to download attachment %s: %s", _redact(att_guid), exc)
- return None
- # --- Webhook handling ---
- def _extract_payload_record(self, payload: dict[str, Any]) -> Optional[dict[str, Any]]:
- data = payload.get("data")
- if isinstance(data, dict):
- return data
- if isinstance(data, list) and (first := next((i for i in data if isinstance(i, dict)), None)):
- return first
- if isinstance(payload.get("message"), dict):
- return payload.get("message")
- return payload if isinstance(payload, dict) else None
- @staticmethod
- def _value(*candidates: Any) -> Optional[str]:
- return next((c.strip() for c in candidates if isinstance(c, str) and c.strip()), None)
- @staticmethod
- def _parse_webhook_body(raw: bytes) -> Any:
- """Decode a webhook body: JSON, else form-encoded with a JSON field."""
- body = raw.decode("utf-8", errors="replace")
- try:
- return json.loads(body)
- except Exception:
- form = parse_qs(body)
- payload_str = (form.get("payload") or form.get("data") or form.get("message") or [""])[0]
- return json.loads(payload_str) if payload_str else {}
- async def _collect_attachments(self, record: dict[str, Any]):
- """Download inbound attachments; returns (media_urls, media_types, msg_type)."""
- media_urls: list[str] = []
- media_types: list[str] = []
- msg_type = MessageType.TEXT
- for att in record.get("attachments") or []:
- att_guid = att.get("guid", "")
- cached = await self._download_attachment(att_guid, att) if att_guid else None
- if not cached:
- continue
- mime = (att.get("mimeType") or "").lower()
- media_urls.append(cached)
- media_types.append(mime)
- is_voice = mime.startswith("audio/") or (att.get("uti") or "").endswith("caf")
- msg_type = (MessageType.PHOTO if mime.startswith("image/") else MessageType.VOICE if is_voice
- else MessageType.VIDEO if mime.startswith("video/") else MessageType.DOCUMENT)
- if len(media_urls) > 1 and any(m.split("/")[0] == "image" for m in media_types): # any image → PHOTO
- msg_type = MessageType.PHOTO
- return media_urls, media_types, msg_type
- def _webhook_token(self, request) -> Optional[str]:
- return (request.query.get("password") or request.query.get("guid") or request.headers.get("x-password")
- or request.headers.get("x-guid") or request.headers.get("x-bluebubbles-guid"))
- def _resolve_chat_and_sender(self, payload: dict[str, Any], record: dict[str, Any]):
- """Returns ``(chat_guid, chat_identifier, sender)`` from the many BlueBubbles payload shapes."""
- chat_guid = self._value(record.get("chatGuid"), payload.get("chatGuid"), record.get("chat_guid"),
- payload.get("chat_guid"), payload.get("guid"))
- # BlueBubbles v1.9+ payloads omit top-level chatGuid; it's nested under data.chats[0].guid.
- _chats = record.get("chats") or []
- if not chat_guid and _chats and isinstance(_chats[0], dict):
- chat_guid = _chats[0].get("guid") or _chats[0].get("chatGuid")
- chat_identifier = self._value(record.get("chatIdentifier"), record.get("identifier"),
- payload.get("chatIdentifier"), payload.get("identifier"))
- handle = record.get("handle")
- sender = (self._value(handle.get("address") if isinstance(handle, dict) else None, record.get("sender"),
- record.get("from"), record.get("address")) or chat_identifier or chat_guid)
- if not (chat_guid or chat_identifier) and sender:
- chat_identifier = sender
- return chat_guid, chat_identifier, sender
- async def _handle_webhook(self, request):
- from aiohttp import web
- if self._webhook_token(request) != self.password:
- return web.json_response({"error": "unauthorized"}, status=401)
- try:
- payload = self._parse_webhook_body(await request.read())
- except Exception as exc:
- logger.error("[bluebubbles] webhook parse error: %s", exc)
- return web.json_response({"error": "invalid payload"}, status=400)
- event_type = self._value(payload.get("type"), payload.get("event")) or ""
- if event_type and event_type not in _MESSAGE_EVENTS: # ack non-message events silently
- return _ok()
- record = self._extract_payload_record(payload) or {}
- if record.get("isFromMe") or record.get("fromMe") or record.get("is_from_me"):
- return _ok()
- assoc_type = record.get("associatedMessageType")
- if isinstance(assoc_type, int) and assoc_type in _TAPBACK_CODES: # tapback reactions delivered as messages
- return _ok()
- text = self._value(record.get("text"), record.get("message"), record.get("body")) or ""
- chat_guid, chat_identifier, sender = self._resolve_chat_and_sender(payload, record)
- session_chat_id = chat_guid or chat_identifier
- is_group = bool(record.get("isGroup")) or (";+;" in (chat_guid or ""))
- # Mention gate BEFORE the attachment downloads: an unmentioned group message must not
- # pull every attachment through the REST API only to be dropped.
- if is_group and self.require_mention:
- if not self._message_matches_mention_patterns(text):
- logger.debug("[bluebubbles] ignoring group message (require_mention=true, no mention pattern matched)")
- return _ok()
- text = self._clean_mention_text(text)
- media_urls, media_types, msg_type = await self._collect_attachments(record)
- if not text and media_urls:
- text = "(attachment)"
- if not sender or not (chat_guid or chat_identifier) or not text:
- return web.json_response({"error": "missing message fields"}, status=400)
- source = self.build_source(chat_id=session_chat_id, chat_name=chat_identifier or sender,
- chat_type="group" if is_group else "dm", user_id=sender, user_name=sender,
- chat_id_alt=chat_identifier)
- event = MessageEvent(
- text=text, message_type=msg_type, source=source, raw_message=payload,
- message_id=self._value(record.get("guid"), record.get("messageGuid"), record.get("id")),
- reply_to_message_id=self._value(record.get("threadOriginatorGuid"), record.get("associatedMessageGuid")),
- media_urls=media_urls, media_types=media_types)
- task = asyncio.create_task(self.handle_message(event))
- self._background_tasks.add(task)
- task.add_done_callback(self._background_tasks.discard)
- if self.send_read_receipts and session_chat_id: # fire-and-forget read receipt
- asyncio.create_task(self.mark_read(session_chat_id))
- return _ok()
- # --- Plugin hooks (registered via register(ctx) below) ---
- _INSTALL_HINT = "BlueBubbles: aiohttp/httpx missing or BLUEBUBBLES_SERVER_URL/BLUEBUBBLES_PASSWORD not configured"
- def _is_connected(config) -> bool:
- """Server URL + password present in ``PlatformConfig.extra`` (the env table seeds it) or the env."""
- extra = getattr(config, "extra", None) or {}
- if extra.get("server_url") and extra.get("password"):
- return True
- import hermes_cli.gateway as gateway_mod
- return all((gateway_mod.get_env_value(n) or "").strip() for n in ("BLUEBUBBLES_SERVER_URL", "BLUEBUBBLES_PASSWORD"))
- async def _standalone_send(pconfig, chat_id: str, message: str, *, thread_id: Optional[str] = None,
- media_files: Optional[list] = None, force_document: bool = False, **_kw) -> dict[str, Any]:
- """Out-of-process send (cron without a co-resident gateway): one-shot adapter connect → send →
- disconnect against the BlueBubbles REST API. Text only; ``thread_id``/``media_files``/
- ``force_document`` are signature parity (send_message drops media with a warning)."""
- from gateway.platforms._shared import send_error
- if not check_bluebubbles_requirements():
- return send_error("BlueBubbles requirements not met (need aiohttp + httpx).")
- try:
- adapter = BlueBubblesAdapter(PlatformConfig(extra=dict(getattr(pconfig, "extra", None) or {})))
- if not await adapter.connect():
- return send_error("BlueBubbles: failed to connect to server")
- try:
- result = await adapter.send(chat_id, message)
- finally:
- await adapter.disconnect()
- if not result.success:
- return send_error(f"BlueBubbles send failed: {result.error}")
- return {"success": True, "platform": "bluebubbles", "chat_id": chat_id, "message_id": result.message_id}
- except Exception as e:
- logger.debug("BlueBubbles standalone send failed", exc_info=True)
- return send_error(f"BlueBubbles send failed: {e}")
- def interactive_setup() -> None:
- """Configure BlueBubbles iMessage gateway (``hermes setup`` / ``hermes gateway setup``)."""
- from hermes_cli.setup import _info, print_header, print_success, prompt, prompt_yes_no
- from hermes_cli.setup_platforms import _prompt_allowlist, _save_port, declines_reconfigure, save_prompted
- print_header("BlueBubbles (iMessage)")
- if declines_reconfigure("BlueBubbles", "Reconfigure BlueBubbles?", "BLUEBUBBLES_SERVER_URL"):
- return
- _info("Connects Hermes to iMessage via BlueBubbles — a free, open-source",
- "macOS server that bridges iMessage to any device.",
- " Requires a Mac running BlueBubbles Server v1.0.0+",
- " Download: https://bluebubbles.app/", None,
- "In BlueBubbles Server → Settings → API, note your Server URL and Password.", None)
- for label, env_var, secret, what, transform in (
- ("BlueBubbles server URL (e.g. http://192.168.1.10:1234)", "BLUEBUBBLES_SERVER_URL", False, "Server URL",
- lambda v: v.rstrip("/")),
- ("BlueBubbles server password", "BLUEBUBBLES_PASSWORD", True, "Password", None),
- ):
- if not save_prompted(env_var, label, password=secret, transform=transform,
- skip_msg=f"{what} is required — skipping BlueBubbles setup"):
- return
- print_success("BlueBubbles credentials saved")
- _info(None, "🔒 Security: Restrict who can message your bot",
- " Use iMessage addresses: email (user@icloud.com) or phone (+15551234567)", None)
- _prompt_allowlist("BLUEBUBBLES_ALLOWED_USERS", "Allowed iMessage addresses (comma-separated, leave empty for open access)",
- "BlueBubbles allowlist configured", "⚠️ No allowlist set — anyone who can iMessage you can use the bot!")
- _info(None, "📬 Home Channel: phone or email for cron job delivery and notifications.",
- " You can also set this later with /set-home in your iMessage chat.")
- save_prompted("BLUEBUBBLES_HOME_CHANNEL", "Home channel address (leave empty to set later)")
- _info(None, "Advanced settings (defaults are fine for most setups):")
- if prompt_yes_no("Configure webhook listener settings?", False):
- _save_port("BLUEBUBBLES_WEBHOOK_PORT", prompt("Webhook listener port (default: 8645)"), "8645")
- _info(None, "Requires the BlueBubbles Private API helper for typing indicators,",
- "read receipts, and tapback reactions. Basic messaging works without it.",
- " Install: https://docs.bluebubbles.app/helper-bundle/installation")
- # System-prompt platform hint (PlatformEntry.platform_hint); cached-prompt bytes, keep stable.
- _PLATFORM_HINT = (
- # The adapter runs strip_markdown(keep_link_targets=True): markers vanish, the layout stays.
- "You are texting via iMessage (BlueBubbles). Replies arrive as plain text bubbles, so write like a person "
- "texting: short and conversational, answer first, no preamble or recap. Markdown does not render and is "
- "stripped, so skip headers, tables, code fences and backticks; for a few items use short lines or a "
- "sentence rather than nested bullets. Put a command or code snippet on its own line as plain text so it "
- "can be copied. Write links as bare URLs (iMessage auto-links them). "
- "You can send files natively: write MEDIA:/absolute/path/to/file in your response. "
- "Images (.jpg, .png, .heic) appear as photos and other files arrive as attachments."
- )
- def register(ctx) -> None:
- """Plugin entry point — called by the Hermes plugin system."""
- from . import gateway_env # env -> GatewayConfig bridge (gateway.config_env)
- ctx.register_platform(
- name="bluebubbles", label="BlueBubbles (iMessage)", adapter_factory=BlueBubblesAdapter,
- dashboard_description="Use Hermes through iMessage via a BlueBubbles server.",
- docs_url="https://bluebubbles.app/",
- dashboard_env_vars=("BLUEBUBBLES_SERVER_URL", "BLUEBUBBLES_PASSWORD", "BLUEBUBBLES_ALLOWED_USERS"),
- check_fn=check_bluebubbles_requirements, is_connected=_is_connected,
- config_connected_fn=config_connected_extra("server_url", "password"),
- required_env=["BLUEBUBBLES_SERVER_URL", "BLUEBUBBLES_PASSWORD"], install_hint=_INSTALL_HINT,
- setup_fn=interactive_setup,
- cron_deliver_env_var="BLUEBUBBLES_HOME_CHANNEL",
- standalone_sender_fn=_standalone_send, # out-of-process cron / send_message
- # 0 = send_message does not pre-chunk: the adapter's send() splits per paragraph and
- # truncates itself (MAX_MESSAGE_LENGTH), exactly as the former core sender did.
- max_message_length=0, pii_safe=True, emoji="💬", allow_update_command=True,
- platform_hint=_PLATFORM_HINT,
- display_tier="low",
- env_overrides=gateway_env.ENV_OVERRIDES,
- env_enable_credentials=gateway_env.ENV_ENABLE_CREDENTIALS, **gateway_env.AUTHZ,
- )
|