feat: BlueBubbles/iMessage messenger channel integration

[aecs4u]

Summary

Add iMessage integration via BlueBubbles API to enable RustyClaw agents to communicate using Apple's iMessage protocol.

Background

BlueBubbles is an open-source ecosystem that enables iMessage functionality on non-Apple platforms by proxying through a macOS server. It provides:

• Full iMessage feature support (texts, group chats, reactions, typing indicators)
• REST API and WebSocket support
• Cross-platform compatibility (Android, Windows, Linux, Web)

Prior Art

• OpenClaw has native iMessage support (18+ messenger channels include iMessage)
• BlueBubbles provides a documented REST API: https://docs.bluebubbles.app/server/api

Motivation

iMessage is the default messaging platform for iOS/macOS users (1.3B+ active devices). Adding BlueBubbles integration would enable:

• Enterprise teams using Mac-based workflows
• Cross-platform iMessage access without Apple hardware requirements
• Unified messaging experience for Apple ecosystem users

Proposed Design

1. BlueBubbles Server Setup:

   • Requires macOS server running BlueBubbles Server app
   • Server exposes REST API on configurable port (default: 1234)
   • Authentication via API key

2. Configuration (config.toml):

   [[messengers]]
   name = "imessage"
   type = "bluebubbles"
   enabled = true
   api_url = "http://localhost:1234"
   api_key = "your-bluebubbles-api-key"
   password = "optional-server-password"

3. Core Functionality:

   • Send messages via POST /api/v1/message/text
   • Receive messages via WebSocket /socket.io
   • Handle group chats, reactions, attachments
   • Typing indicators and read receipts

4. Implementation (src/messengers/bluebubbles.rs):

   pub struct BlueBubblesMessenger {
       api_url: String,
       api_key: String,
       client: reqwest::Client,
       ws_client: Option<tokio_tungstenite::WebSocketStream>,
   }
   
   impl BlueBubblesMessenger {
       pub async fn send_message(&self, chat_guid: &str, text: &str) -> Result<()> {
           self.client
               .post(&format!("{}/api/v1/message/text", self.api_url))
               .header("Authorization", &self.api_key)
               .json(&serde_json::json!({
                   "chatGuid": chat_guid,
                   "message": text
               }))
               .send()
               .await?;
           Ok(())
       }
   
       pub async fn connect_websocket(&mut self) -> Result<()> {
           let ws_url = format!("{}/socket.io/?EIO=4&transport=websocket", 
               self.api_url.replace("http", "ws"));
           self.ws_client = Some(tokio_tungstenite::connect_async(ws_url).await?.0);
           Ok(())
       }
   }

API Endpoints

Endpoint	Method	Purpose
/api/v1/message/text	POST	Send text message
/api/v1/message/attachment	POST	Send attachment
/api/v1/chat	GET	List chats
/api/v1/chat/{guid}/message	GET	Get chat messages
/socket.io	WebSocket	Real-time message events

Dependencies

[dependencies]
tokio-tungstenite = "0.21"  # WebSocket client
socketio-client = "0.4"      # Socket.IO protocol

Acceptance Criteria

• BlueBubbles configuration in config.toml
• Send text messages to individuals and groups
• Receive messages via WebSocket
• Handle group chats and threads
• Support reactions and typing indicators
• Attachment upload/download
• Integration tests with mock BlueBubbles server
• Documentation in docs/MESSENGER_IMESSAGE.md

Security Considerations

• API key stored in encrypted secrets vault (feat: Secure credential memory with zeroize/secrecy crate #86)
• TLS/HTTPS required for production deployments
• Per-chat access controls (feat: Per-chat working directory isolation with path guards #74)
• Message content sanitization (feat: PII redaction and output sanitizer for agent responses #71)

Related Issues

• feat: Per-channel message chunking and delivery queue #82 (Per-channel message chunking)
• feat: Secure credential memory with zeroize/secrecy crate #86 (Secure credential memory)
• feat: PII redaction and output sanitizer for agent responses #71 (PII redaction)
• feat: Per-chat working directory isolation with path guards #74 (Per-chat isolation)

References

• BlueBubbles Documentation
• BlueBubbles Server API
• BlueBubbles GitHub