| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359 |
- """SMS (Twilio) platform adapter.
- Outbound SMS via the Twilio REST API; inbound via an aiohttp webhook server.
- Env vars — shared with the telephony skill: TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN,
- TWILIO_PHONE_NUMBER (E.164 from-number). Gateway-specific: SMS_WEBHOOK_PORT (8080),
- SMS_WEBHOOK_HOST (127.0.0.1), SMS_WEBHOOK_URL (public URL for Twilio signature
- validation — required), SMS_INSECURE_NO_SIGNATURE (true disables validation — dev only),
- SMS_ALLOWED_USERS (comma-separated E.164), SMS_ALLOW_ALL_USERS, SMS_HOME_CHANNEL (cron).
- """
- from __future__ import annotations
- import asyncio
- import base64
- import hashlib
- import hmac
- import logging
- import re
- import urllib.parse
- from typing import Any, Dict, Optional
- from gateway.config import Platform, PlatformConfig
- from gateway.platforms.base import gateway_trust_env, BasePlatformAdapter, SendResult
- from gateway.platforms.event import MessageEvent, MessageType
- from gateway.platforms.helpers import redact_phone, send_chunks, strip_markdown
- from gateway.platforms._shared import (
- env_is_connected as _env_is_connected, get_scoped_secret as _get_scoped_secret, send_error
- )
- from gateway.platforms.send_targets import StandaloneSendPolicy
- try:
- import aiohttp
- from aiohttp import web
- AIOHTTP_AVAILABLE = True
- except ImportError: # optional ([messaging] extra)
- AIOHTTP_AVAILABLE = False
- aiohttp = None # type: ignore[assignment]
- web = None # type: ignore[assignment]
- logger = logging.getLogger(__name__)
- TWILIO_API_BASE = "https://api.twilio.com/2010-04-01/Accounts"
- MAX_SMS_LENGTH = 1600 # ~10 SMS segments
- DEFAULT_WEBHOOK_PORT = 8080
- DEFAULT_WEBHOOK_HOST = "127.0.0.1"
- _TWILIO_WEBHOOK_MAX_BODY_BYTES = 65_536 # 64 KiB — Twilio payloads are small
- _EMPTY_TWIML = '<?xml version="1.0" encoding="UTF-8"?><Response></Response>'
- def _twiml_response(status: int = 200):
- """Empty TwiML reply — replies go out via the REST API, never inline TwiML."""
- return web.Response(text=_EMPTY_TWIML, content_type="application/xml", status=status)
- def _basic_auth(account_sid: str, auth_token: str) -> str:
- """HTTP Basic auth header value for Twilio."""
- encoded = base64.b64encode(f"{account_sid}:{auth_token}".encode("ascii")).decode("ascii")
- return f"Basic {encoded}"
- def _messages_endpoint(account_sid: str, auth_token: str) -> tuple:
- """(Messages.json URL, auth headers) for the account."""
- return f"{TWILIO_API_BASE}/{account_sid}/Messages.json", {"Authorization": _basic_auth(account_sid, auth_token)}
- def _twilio_form(from_number: str, to_number: str, body: str):
- """Twilio Messages.json form payload (aiohttp FormData)."""
- form_data = aiohttp.FormData()
- form_data.add_field("From", from_number)
- form_data.add_field("To", to_number)
- form_data.add_field("Body", body)
- return form_data
- def _new_session(**kwargs):
- return aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=30), **kwargs)
- def check_sms_requirements() -> bool:
- """Check if SMS adapter dependencies are available."""
- return AIOHTTP_AVAILABLE and bool(
- _get_scoped_secret("TWILIO_ACCOUNT_SID") and _get_scoped_secret("TWILIO_AUTH_TOKEN", "").strip())
- class SmsAdapter(BasePlatformAdapter):
- """Twilio SMS <-> Hermes: one session per inbound number; replies always from TWILIO_PHONE_NUMBER."""
- # Answers /p/<profile>/... on the default listener for a served secondary (shared_ingress).
- serves_profile_prefix: bool = True
- MAX_MESSAGE_LENGTH = MAX_SMS_LENGTH
- # send() splits at MAX_MESSAGE_LENGTH, so cron delivery hands over the full payload.
- splits_long_messages = True
- def __init__(self, config: PlatformConfig):
- super().__init__(config, Platform.SMS)
- self._account_sid: str = _get_scoped_secret("TWILIO_ACCOUNT_SID", "")
- # Stripped: a whitespace-only token must read as unset, not key the signature HMAC with blanks.
- self._auth_token: str = _get_scoped_secret("TWILIO_AUTH_TOKEN", "").strip()
- # Scoped like the sibling reads above: a secondary profile must not send from the default
- # profile's TWILIO_PHONE_NUMBER (#98738 class).
- self._from_number: str = _get_scoped_secret("TWILIO_PHONE_NUMBER", "")
- self._webhook_port: int = int(_get_scoped_secret("SMS_WEBHOOK_PORT", str(DEFAULT_WEBHOOK_PORT)))
- self._webhook_host: str = _get_scoped_secret("SMS_WEBHOOK_HOST", DEFAULT_WEBHOOK_HOST)
- self._webhook_url: str = _get_scoped_secret("SMS_WEBHOOK_URL", "").strip()
- self._runner = None
- self._http_session: Optional[aiohttp.ClientSession] = None
- # -- Lifecycle -----------------------------------------------------------
- async def connect(self, *, is_reconnect: bool = False) -> bool:
- insecure_no_sig = _get_scoped_secret("SMS_INSECURE_NO_SIGNATURE", "").lower() == "true"
- fatal = None
- if not self._from_number:
- fatal = "sms_missing_phone_number", "[sms] TWILIO_PHONE_NUMBER not set — cannot send replies"
- elif not self._webhook_url and not insecure_no_sig:
- fatal = "sms_missing_webhook_url", (
- "[sms] Refusing to start: SMS_WEBHOOK_URL is required for Twilio "
- "signature validation. Set it to the public URL configured in your "
- "Twilio console (e.g. https://example.com/webhooks/twilio). "
- "For local development without validation, set "
- "SMS_INSECURE_NO_SIGNATURE=true (NOT recommended for production).")
- if fatal:
- logger.error(fatal[1])
- self._set_fatal_error(fatal[0], fatal[1], retryable=False)
- return False
- if insecure_no_sig and not self._webhook_url:
- logger.warning(
- "[sms] SMS_INSECURE_NO_SIGNATURE=true — Twilio signature validation "
- "is DISABLED. Any client that can reach port %d can inject messages. "
- "Do NOT use this in production.",
- self._webhook_port)
- # client_max_size bounds every read path (incl. chunked bodies with no
- # Content-Length) before the handler's own 413 checks run.
- # See #58536, #58902, #59180.
- app = web.Application(client_max_size=_TWILIO_WEBHOOK_MAX_BODY_BYTES)
- app.router.add_post("/webhooks/twilio", self._handle_webhook)
- app.router.add_get("/health", lambda _: web.Response(text="ok"))
- # Shared-listener mode (multiplex secondary): no bind; served at /p/<profile>/webhooks/twilio.
- from gateway.platforms.shared_ingress import bind_listener
- self._runner = await bind_listener(self, app, self._webhook_host, self._webhook_port, "/webhooks/twilio")
- self._http_session = _new_session(trust_env=gateway_trust_env())
- self._running = True
- if self._runner is not None:
- logger.info(
- "[sms] Twilio webhook server listening on %s:%d, from: %s",
- self._webhook_host, self._webhook_port, redact_phone(self._from_number))
- self._wire_plugin_handlers(None)
- return True
- async def disconnect(self) -> None:
- if self._http_session:
- await self._http_session.close()
- self._http_session = None
- if self._runner:
- await self._runner.cleanup()
- self._runner = None
- self._running = False
- logger.info("[sms] Disconnected")
- # -- Outbound ------------------------------------------------------------
- async def send(
- self, chat_id: str, content: str, reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None,
- ) -> SendResult:
- url, headers = _messages_endpoint(self._account_sid, self._auth_token)
- session = self._http_session or _new_session(trust_env=gateway_trust_env())
- async def _send_one(chunk: str) -> SendResult:
- try:
- async with session.post(url, data=_twilio_form(self._from_number, chat_id, chunk), headers=headers) as resp:
- body = await resp.json()
- if resp.status >= 400:
- error_msg = body.get("message", str(body))
- logger.error("[sms] send failed to %s: %s %s", redact_phone(chat_id), resp.status, error_msg)
- return SendResult(success=False, error=f"Twilio {resp.status}: {error_msg}")
- return SendResult(success=True, message_id=body.get("sid", ""))
- except Exception as e:
- logger.error("[sms] send error to %s: %s", redact_phone(chat_id), e)
- return SendResult(success=False, error=str(e))
- try:
- return await send_chunks(self.truncate_message(self.format_message(content), self.MAX_MESSAGE_LENGTH), _send_one)
- finally:
- if not self._http_session and session: # close only a fallback session we created
- await session.close()
- async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
- return {"name": chat_id, "type": "dm"}
- def format_message(self, content: str) -> str:
- """Strip markdown — SMS renders it as literal characters."""
- return strip_markdown(content)
- # -- Twilio signature validation -----------------------------------------
- def _validate_twilio_signature(self, url: str, post_params: dict, signature: str) -> bool:
- """Validate ``X-Twilio-Signature`` (HMAC-SHA1, base64).
- Twilio may sign the URL with or without the scheme's default port, so
- both variants are tried. https://www.twilio.com/docs/usage/security#validating-requests
- """
- if self._check_signature(url, post_params, signature):
- return True
- variant = self._port_variant_url(url)
- return bool(variant and self._check_signature(variant, post_params, signature))
- def _check_signature(self, url: str, post_params: dict, signature: str) -> bool:
- if not self._auth_token: # an empty HMAC key is public: fail closed rather than verify against it
- return False
- data_to_sign = url + "".join(key + post_params[key] for key in sorted(post_params.keys()))
- mac = hmac.new(self._auth_token.encode("utf-8"), data_to_sign.encode("utf-8"), hashlib.sha1)
- computed = base64.b64encode(mac.digest()).decode("utf-8")
- # Compare as bytes: compare_digest raises TypeError on non-ASCII str,
- # and the signature is a raw request header.
- return hmac.compare_digest(computed.encode(), signature.encode())
- @staticmethod
- def _port_variant_url(url: str) -> str | None:
- """URL with the scheme's default port toggled (added/stripped); None for non-default ports."""
- parsed = urllib.parse.urlparse(url)
- default_port = {"https": 443, "http": 80}.get(parsed.scheme)
- if default_port is None:
- return None
- if parsed.port == default_port:
- netloc = parsed.hostname
- elif parsed.port is None:
- netloc = f"{parsed.hostname}:{default_port}"
- else:
- return None
- return urllib.parse.urlunparse(
- (parsed.scheme, netloc, parsed.path, parsed.params, parsed.query, parsed.fragment))
- # -- Inbound webhook -----------------------------------------------------
- async def _handle_webhook(self, request: web.Request) -> web.Response:
- try:
- content_length = request.content_length
- if content_length is not None and content_length > _TWILIO_WEBHOOK_MAX_BODY_BYTES:
- return _twiml_response(413)
- raw = await request.read()
- if len(raw) > _TWILIO_WEBHOOK_MAX_BODY_BYTES:
- return _twiml_response(413)
- # Twilio sends form-encoded data, not JSON; parse_qs values are lists.
- form = urllib.parse.parse_qs(raw.decode("utf-8"), keep_blank_values=True)
- except Exception as e:
- logger.error("[sms] webhook parse error: %s", e)
- return _twiml_response(400)
- if self._webhook_url:
- twilio_sig = request.headers.get("X-Twilio-Signature", "")
- flat_params = {k: v[0] for k, v in form.items() if v}
- rejected = ("missing X-Twilio-Signature header" if not twilio_sig
- else "" if self._validate_twilio_signature(self._webhook_url, flat_params, twilio_sig)
- else "invalid Twilio signature")
- if rejected:
- logger.warning("[sms] Rejected: %s", rejected)
- return _twiml_response(403)
- from_number, to_number, text, message_sid = (
- form.get(key, [""])[0].strip() for key in ("From", "To", "Body", "MessageSid"))
- if not from_number or not text:
- return _twiml_response()
- if from_number == self._from_number: # echo prevention
- logger.debug("[sms] ignoring echo from own number %s", redact_phone(from_number))
- return _twiml_response()
- logger.info("[sms] inbound from %s -> %s: %s", redact_phone(from_number), redact_phone(to_number), text[:80])
- source = self.build_source(
- chat_id=from_number, chat_name=from_number, chat_type="dm", user_id=from_number, user_name=from_number,
- message_id=message_sid)
- event = MessageEvent(
- text=text, message_type=MessageType.TEXT, source=source, raw_message=form, message_id=message_sid)
- # Non-blocking: Twilio expects a fast response
- task = asyncio.create_task(self.handle_message(event))
- self._background_tasks.add(task)
- task.add_done_callback(self._background_tasks.discard)
- return _twiml_response()
- # -- Plugin registration (TWILIO_* env→PlatformConfig seeding stays in gateway/config.py)
- # Standalone-send markdown stripping: looser than helpers.strip_markdown (no
- # word-boundary guards on underscores, ``[a-z]*`` fence tags) — kept for parity.
- _SMS_MARKDOWN_SUBS = (
- (re.compile(r"\*\*(.+?)\*\*", re.DOTALL), r"\1"), (re.compile(r"\*(.+?)\*", re.DOTALL), r"\1"),
- (re.compile(r"__(.+?)__", re.DOTALL), r"\1"), (re.compile(r"_(.+?)_", re.DOTALL), r"\1"),
- (re.compile(r"```[a-z]*\n?"), ""), (re.compile(r"`(.+?)`"), r"\1"),
- (re.compile(r"^#{1,6}\s+", re.MULTILINE), ""), (re.compile(r"\[([^\]]+)\]\([^\)]+\)"), r"\1"),
- (re.compile(r"\n{3,}"), "\n\n"))
- # ────────────────────────────────────────────────────────────────────────── Plugin migration glue (#41112 /
- # #3823) Added when the SMS (Twilio) adapter moved from gateway/platforms/sms.py into this bundled plugin.
- # register() exposes the platform via the registry, replacing the Platform.SMS elif in gateway/run.py, the
- # _PLATFORM_CONNECTED_CHECKERS entry in gateway/config.py, the _PLATFORMS["sms"] static dict in
- # hermes_cli/gateway.py, and the _send_sms dispatch in tools/send_message_tool.py. TWILIO_*
- # env→PlatformConfig seeding lives in this plugin's gateway_env.py.
- # ──────────────────────────────────────────────────────────────────────────
- def _strip_markdown_for_sms(message: str) -> str:
- """Strip markdown — SMS renders it as literal characters."""
- for pattern, repl in _SMS_MARKDOWN_SUBS:
- message = pattern.sub(repl, message)
- return message.strip()
- async def _standalone_send(pconfig, chat_id, message, *, thread_id=None, media_files=None, force_document=False):
- """Out-of-process SMS delivery via the Twilio REST API (standalone_sender_fn contract)."""
- auth_token = str(getattr(pconfig, "api_key", None) or _get_scoped_secret("TWILIO_AUTH_TOKEN", "") or "").strip()
- if not AIOHTTP_AVAILABLE:
- return send_error("aiohttp not installed. Run: pip install aiohttp")
- account_sid = _get_scoped_secret("TWILIO_ACCOUNT_SID", "")
- from_number = _get_scoped_secret("TWILIO_PHONE_NUMBER", "") # scoped like account_sid: never the default's number
- if not account_sid or not auth_token or not from_number:
- return send_error("SMS not configured (TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER required)")
- message = _strip_markdown_for_sms(message)
- try:
- from gateway.platforms.base import resolve_proxy_url, proxy_kwargs_for_aiohttp
- _sess_kw, _req_kw = proxy_kwargs_for_aiohttp(resolve_proxy_url())
- url, headers = _messages_endpoint(account_sid, auth_token)
- async with _new_session(**_sess_kw) as session:
- form_data = _twilio_form(from_number, chat_id, message)
- async with session.post(url, data=form_data, headers=headers, **_req_kw) as resp:
- body = await resp.json()
- if resp.status >= 400:
- error_msg = body.get("message", str(body))
- return send_error(f"Twilio API error ({resp.status}): {error_msg}")
- return {"success": True, "platform": "sms", "chat_id": chat_id, "message_id": body.get("sid", "")}
- except Exception as e:
- return send_error(f"SMS send failed: {e}")
- _is_connected = _env_is_connected("TWILIO_ACCOUNT_SID")
- # System-prompt platform hint (PlatformEntry.platform_hint); cached-prompt bytes, keep stable.
- _PLATFORM_HINT = (
- "You are communicating via SMS. Keep responses concise and use plain text only — no markdown, no "
- "formatting. SMS messages are limited to ~1600 characters, so be brief and direct."
- )
- 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(
- standalone_send=StandaloneSendPolicy(text_direct=True),
- name="sms", label="SMS (Twilio)", adapter_factory=SmsAdapter,
- dashboard_description="Send and receive text messages via Twilio.",
- docs_url="https://www.twilio.com/console",
- dashboard_env_vars=("TWILIO_ACCOUNT_SID", "TWILIO_AUTH_TOKEN"),
- dashboard_required_env=("TWILIO_ACCOUNT_SID", "TWILIO_AUTH_TOKEN"),
- check_fn=check_sms_requirements, is_connected=_is_connected,
- required_env=["TWILIO_ACCOUNT_SID", "TWILIO_AUTH_TOKEN", "TWILIO_PHONE_NUMBER"],
- install_hint="pip install aiohttp", cron_deliver_env_var="SMS_HOME_CHANNEL",
- standalone_sender_fn=_standalone_send, max_message_length=MAX_SMS_LENGTH, pii_safe=True,
- emoji="📱", allow_update_command=True,
- platform_hint=_PLATFORM_HINT,
- display_tier="minimal",
- env_overrides=gateway_env.ENV_OVERRIDES,
- env_enable_credentials=gateway_env.ENV_ENABLE_CREDENTIALS, **gateway_env.AUTHZ,
- )
|