webex-message-handler 0.3.1__tar.gz → 0.4.1__tar.gz

{webex_message_handler-0.3.1 → webex_message_handler-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webex-message-handler
-Version: 0.3.1
+Version: 0.4.1
 Summary: Lightweight Webex Mercury WebSocket + KMS decryption for receiving bot messages without the full Webex SDK
 Project-URL: Homepage, https://github.com/3rg0n/webex-message-handler
 Project-URL: Repository, https://github.com/3rg0n/webex-message-handler
@@ -99,6 +99,16 @@ asyncio.run(main())
 
 See `examples/basic_bot.py` for a complete working example.
 
+## Important: Implementing Loop Detection
+
+This library only handles the **receive side** of messaging — it decrypts incoming messages from the Mercury WebSocket. It has no visibility into messages your bot **sends** via the REST API. This means it cannot detect message loops on its own.
+
+If your bot replies to incoming messages, you **must** implement loop detection in your wrapper code. Without it, a bug or misconfiguration could cause your bot to endlessly reply to its own messages. Webex enforces a server-side rate limit (approximately 11 consecutive messages before throttling), but that still results in spam before the cutoff.
+
+**Recommended approach:** Track your bot's outgoing message rate. If it exceeds a threshold (e.g., 5 messages in 3 seconds to the same room), pause sending and log a warning.
+
+The `ignore_self_messages` option (default: `True`) provides a first line of defense by filtering out messages sent by this bot's own identity. If the library cannot verify the bot's identity during `connect()` (e.g., `/people/me` API failure), connection will fail rather than silently running without protection. Set `ignore_self_messages=False` to opt out, but only if you have your own loop prevention in place.
+
 ## Proxy Support (Enterprise)
 
 For corporate environments behind a proxy, pass a configured connector:
@@ -162,6 +172,7 @@ WebexMessageHandler(config: WebexMessageHandlerConfig)
 |--------|------|---------|-------------|
 | `token` | `str` | required | Webex bot access token |
 | `logger` | `Logger` | noop | Custom logger (`console_logger` provided) |
+| `ignore_self_messages` | `bool` | `True` | Filter out messages sent by this bot |
 | `connector` | `aiohttp.BaseConnector` | `None` | HTTP/HTTPS connector for proxy support |
 | `ping_interval` | `float` | `15.0` | Mercury ping interval (seconds) |
 | `pong_timeout` | `float` | `14.0` | Pong response timeout (seconds) |

{webex_message_handler-0.3.1 → webex_message_handler-0.4.1}/README.md

@@ -68,6 +68,16 @@ asyncio.run(main())
 
 See `examples/basic_bot.py` for a complete working example.
 
+## Important: Implementing Loop Detection
+
+This library only handles the **receive side** of messaging — it decrypts incoming messages from the Mercury WebSocket. It has no visibility into messages your bot **sends** via the REST API. This means it cannot detect message loops on its own.
+
+If your bot replies to incoming messages, you **must** implement loop detection in your wrapper code. Without it, a bug or misconfiguration could cause your bot to endlessly reply to its own messages. Webex enforces a server-side rate limit (approximately 11 consecutive messages before throttling), but that still results in spam before the cutoff.
+
+**Recommended approach:** Track your bot's outgoing message rate. If it exceeds a threshold (e.g., 5 messages in 3 seconds to the same room), pause sending and log a warning.
+
+The `ignore_self_messages` option (default: `True`) provides a first line of defense by filtering out messages sent by this bot's own identity. If the library cannot verify the bot's identity during `connect()` (e.g., `/people/me` API failure), connection will fail rather than silently running without protection. Set `ignore_self_messages=False` to opt out, but only if you have your own loop prevention in place.
+
 ## Proxy Support (Enterprise)
 
 For corporate environments behind a proxy, pass a configured connector:
@@ -131,6 +141,7 @@ WebexMessageHandler(config: WebexMessageHandlerConfig)
 |--------|------|---------|-------------|
 | `token` | `str` | required | Webex bot access token |
 | `logger` | `Logger` | noop | Custom logger (`console_logger` provided) |
+| `ignore_self_messages` | `bool` | `True` | Filter out messages sent by this bot |
 | `connector` | `aiohttp.BaseConnector` | `None` | HTTP/HTTPS connector for proxy support |
 | `ping_interval` | `float` | `15.0` | Mercury ping interval (seconds) |
 | `pong_timeout` | `float` | `14.0` | Pong response timeout (seconds) |

{webex_message_handler-0.3.1 → webex_message_handler-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "webex-message-handler"
-version = "0.3.1"
+version = "0.4.1"
 description = "Lightweight Webex Mercury WebSocket + KMS decryption for receiving bot messages without the full Webex SDK"
 readme = "README.md"
 license = "MIT"

{webex_message_handler-0.3.1 → webex_message_handler-0.4.1}/src/webex_message_handler/handler.py

@@ -31,10 +31,35 @@ from .types import (
 if TYPE_CHECKING:
     pass
 
+import base64
+
 # Type alias for event callbacks
 EventCallback = Callable[..., Any]
 
 
+def extract_person_uuid(person_id: str) -> str:
+    """Extract the raw UUID from a Webex person ID.
+
+    The Webex REST API returns base64-encoded IDs like:
+        "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mYjUx..." → "ciscospark://us/PEOPLE/fb51254f-..."
+
+    Mercury wire format uses raw UUIDs:
+        "fb51254f-3b37-4e50-aa04-45744c2effc7"
+
+    This function normalizes both formats to the raw UUID for comparison.
+    """
+    try:
+        decoded = base64.b64decode(person_id).decode("utf-8")
+        if decoded.startswith("ciscospark://"):
+            uuid = decoded.rsplit("/", 1)[-1]
+            if uuid:
+                return uuid
+    except Exception:
+        # Not base64 — treat as raw UUID
+        pass
+    return person_id
+
+
 class WebexMessageHandler:
     """Receives and decrypts Webex messages over Mercury WebSocket.
 
@@ -321,27 +346,31 @@ class WebexMessageHandler:
         )
 
     async def _fetch_bot_person_id(self) -> None:
-        """Fetch the bot's person ID for self-message filtering."""
-        try:
-            self._logger.debug("Fetching bot person info for self-message filtering")
-            response = await self._http_do(
-                FetchRequest(
-                    url="https://webexapis.com/v1/people/me",
-                    method="GET",
-                    headers={
-                        "Authorization": f"Bearer {self._token}",
-                        "Content-Type": "application/json",
-                    },
-                )
+        """Fetch the bot's person ID for self-message filtering.
+
+        Raises on failure — connect() will not proceed without a valid bot ID
+        when ignore_self_messages is enabled.
+        """
+        self._logger.debug("Fetching bot person info for self-message filtering")
+        response = await self._http_do(
+            FetchRequest(
+                url="https://webexapis.com/v1/people/me",
+                method="GET",
+                headers={
+                    "Authorization": f"Bearer {self._token}",
+                    "Content-Type": "application/json",
+                },
             )
-            if not response.ok:
-                self._logger.warning(f"Failed to fetch bot person info: HTTP {response.status}")
-                return
-            data = await response.json()
-            self._bot_person_id = data.get("id")
-            self._logger.info(f"Bot person ID cached for self-message filtering: {self._bot_person_id}")
-        except Exception as exc:
-            self._logger.warning(f"Error fetching bot person info: {exc}")
+        )
+        if not response.ok:
+            raise RuntimeError(
+                f"Failed to fetch bot identity for self-message filtering: HTTP {response.status}. "
+                "Set ignore_self_messages=False to skip this check (not recommended — may cause message loops)."
+            )
+        data = await response.json()
+        raw_id = data.get("id", "")
+        self._bot_person_id = extract_person_uuid(raw_id)
+        self._logger.info(f"Bot person ID cached for self-message filtering: {self._bot_person_id}")
 
     def _setup_mercury_listeners(self) -> None:
         # Forward KMS messages from Mercury to the KMS client
@@ -409,7 +438,7 @@ class WebexMessageHandler:
                 raw=decrypted,
             )
             # Filter self-messages if enabled
-            if self._ignore_self_messages and self._bot_person_id and message.person_id == self._bot_person_id:
+            if self._ignore_self_messages and self._bot_person_id and extract_person_uuid(message.person_id) == self._bot_person_id:
                 self._logger.debug(f"Ignoring self-message from bot ({self._bot_person_id})")
                 return
 

{webex_message_handler-0.3.1 → webex_message_handler-0.4.1}/tests/test_handler.py

@@ -130,6 +130,7 @@ class TestConnect:
         mock_kms_cls.return_value = mock_kms
 
         handler = _make_handler()
+        handler._fetch_bot_person_id = AsyncMock()
         connected_events = []
         handler.on("connected", lambda: connected_events.append(True))
 
@@ -183,6 +184,7 @@ class TestDisconnect:
         mock_kms_cls.return_value = mock_kms
 
         handler = _make_handler()
+        handler._fetch_bot_person_id = AsyncMock()
         await handler.connect()
         await handler.disconnect()