feat(whatsapp): add HMAC-SHA256 webhook signature verification

Implements secure webhook verification for WhatsApp Cloud API alongside
the existing Slack HMAC verification:

- Add verify_hmac_sha256() for X-Hub-Signature-256 header validation
  (WhatsApp/GitHub-style, simple body-only HMAC)
- Add webhook deduplication via database to prevent replay attacks
- Add mark_as_read support for blue checkmarks
- Update WhatsApp capabilities.json with hmac_secret_name config
- Add on_message_persisted callback for post-DB persistence actions
- Move WhatsApp-specific logic to WASM channel from host

The router supports both verification styles:
- Slack: X-Slack-Signature + X-Slack-Request-Timestamp (v0:{ts}:{body})
- WhatsApp: X-Hub-Signature-256 (sha256={hex})

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jrevillard

.gitignore

@@ -22,3 +22,4 @@ bench-results/
 # WASM build artifacts (loaded from disk, not bundled)
 *.wasm
 
+.serena/

FEATURE_PARITY.md

@@ -65,7 +65,7 @@ This document tracks feature parity between IronClaw (Rust implementation) and O
 | HTTP webhook | ✅ | ✅ | - | axum with secret validation |
 | REPL (simple) | ✅ | ✅ | - | For testing |
 | WASM channels | ❌ | ✅ | - | IronClaw innovation |
-| WhatsApp | ✅ | ❌ | P1 | Baileys (Web), same-phone mode with echo detection |
+| WhatsApp | ✅ | ✅ | P1 | Cloud API (WASM), DM pairing, text messages; voice/media TODO |
 | Telegram | ✅ | ✅ | - | WASM channel(MTProto), DM pairing, caption, /start, bot_username |
 | Discord | ✅ | ❌ | P2 | discord.js, thread parent binding inheritance |
 | Signal | ✅ | ✅ | P2 | signal-cli daemonPC, SSE listener HTTP/JSON-R, user/group allowlists, DM pairing |
@@ -526,7 +526,7 @@ This document tracks feature parity between IronClaw (Rust implementation) and O
 ### P1 - High Priority
 - ❌ Slack channel (real implementation)
 - ✅ Telegram channel (WASM, DM pairing, caption, /start)
-- ❌ WhatsApp channel
+- ✅ WhatsApp channel (WASM, Cloud API, HMAC webhook verification, text messages)
 - ✅ Multi-provider failover (`FailoverProvider` with retryable error classification)
 - ✅ Hooks system (core lifecycle hooks + bundled/plugin/workspace hooks + outbound webhooks)
 

channels-src/discord/src/lib.rs

@@ -312,6 +312,11 @@ impl Guest for DiscordChannel {
 
     fn on_status(_update: StatusUpdate) {}
 
+    fn on_message_persisted(_metadata_json: String) -> Result<(), String> {
+        // Discord doesn't need post-persistence actions
+        Ok(())
+    }
+
     fn on_shutdown() {
         channel_host::log(
             channel_host::LogLevel::Info,

channels-src/slack/src/lib.rs

@@ -306,6 +306,11 @@ impl Guest for SlackChannel {
 
     fn on_status(_update: StatusUpdate) {}
 
+    fn on_message_persisted(_metadata_json: String) -> Result<(), String> {
+        // Slack doesn't need post-persistence actions
+        Ok(())
+    }
+
     fn on_shutdown() {
         channel_host::log(channel_host::LogLevel::Info, "Slack channel shutting down");
     }

channels-src/telegram/src/lib.rs

@@ -707,6 +707,11 @@ impl Guest for TelegramChannel {
         }
     }
 
+    fn on_message_persisted(_metadata_json: String) -> Result<(), String> {
+        // Telegram doesn't need post-persistence actions like mark_as_read
+        Ok(())
+    }
+
     fn on_shutdown() {
         channel_host::log(
             channel_host::LogLevel::Info,

channels-src/whatsapp/src/lib.rs

@@ -476,6 +476,98 @@ impl Guest for WhatsAppChannel {
 
     fn on_status(_update: StatusUpdate) {}
 
+    fn on_message_persisted(metadata_json: String) -> Result<(), String> {
+        channel_host::log(
+            channel_host::LogLevel::Debug,
+            "on_message_persisted callback invoked",
+        );
+
+        // Parse metadata to get message_id and phone_number_id
+        let metadata: WhatsAppMessageMetadata = match serde_json::from_str(&metadata_json) {
+            Ok(m) => m,
+            Err(e) => {
+                channel_host::log(
+                    channel_host::LogLevel::Warn,
+                    &format!("Failed to parse metadata in on_message_persisted: {}", e),
+                );
+                // Don't fail the ACK - just log and return
+                return Ok(());
+            }
+        };
+
+        // Read api_version from workspace (set during on_start), fallback to default
+        let api_version = channel_host::workspace_read("channels/whatsapp/api_version")
+            .filter(|s| !s.is_empty())
+            .unwrap_or_else(|| "v18.0".to_string());
+
+        // Build WhatsApp mark_as_read API URL
+        let url = format!(
+            "https://graph.facebook.com/{}/{}/messages",
+            api_version, metadata.phone_number_id
+        );
+
+        // Build mark_as_read payload
+        let payload = serde_json::json!({
+            "messaging_product": "whatsapp",
+            "status": "read",
+            "message_id": metadata.message_id
+        });
+
+        let payload_bytes = serde_json::to_vec(&payload)
+            .map_err(|e| format!("Failed to serialize mark_as_read payload: {}", e))?;
+
+        // Headers with Bearer token placeholder
+        // Host will inject the actual access token
+        let headers = serde_json::json!({
+            "Content-Type": "application/json",
+            "Authorization": "Bearer {WHATSAPP_ACCESS_TOKEN}"
+        });
+
+        channel_host::log(
+            channel_host::LogLevel::Debug,
+            &format!("Calling mark_as_read for message: {}", metadata.message_id),
+        );
+
+        let result = channel_host::http_request(
+            "POST",
+            &url,
+            &headers.to_string(),
+            Some(&payload_bytes),
+            None,
+        );
+
+        match result {
+            Ok(http_response) => {
+                if http_response.status >= 200 && http_response.status < 300 {
+                    channel_host::log(
+                        channel_host::LogLevel::Debug,
+                        &format!("Marked message {} as read", metadata.message_id),
+                    );
+                    Ok(())
+                } else {
+                    let body_str = String::from_utf8_lossy(&http_response.body);
+                    channel_host::log(
+                        channel_host::LogLevel::Warn,
+                        &format!(
+                            "mark_as_read API error: {} - {}",
+                            http_response.status, body_str
+                        ),
+                    );
+                    // Don't fail the ACK - mark_as_read is best-effort
+                    Ok(())
+                }
+            }
+            Err(e) => {
+                channel_host::log(
+                    channel_host::LogLevel::Warn,
+                    &format!("mark_as_read HTTP request failed: {}", e),
+                );
+                // Don't fail the ACK - mark_as_read is best-effort
+                Ok(())
+            }
+        }
+    }
+
     fn on_shutdown() {
         channel_host::log(
             channel_host::LogLevel::Info,
@@ -652,6 +744,11 @@ fn handle_message(
         return;
     }
 
+    // Note: mark_as_read is now handled by the host after DB persistence.
+    // The host will call the WhatsApp API directly after receiving the ACK
+    // from the agent loop. This ensures the webhook returns 200 OK only after
+    // the message is durably stored.
+
     // Build metadata for response routing
     // This is critical - the response handler uses this to know where to send
     let metadata = WhatsAppMessageMetadata {
@@ -681,10 +778,6 @@ fn handle_message(
     );
 }
 
-// ============================================================================
-// Utilities
-// ============================================================================
-
 // ============================================================================
 // Permission & Pairing
 // ============================================================================

channels-src/whatsapp/whatsapp.capabilities.json

@@ -16,9 +16,14 @@
         "prompt": "Webhook verify token (leave empty to auto-generate)",
         "optional": true,
         "auto_generate": { "length": 32 }
+      },
+      {
+        "name": "whatsapp_app_secret",
+        "prompt": "Enter your WhatsApp App Secret (from Meta Developer Portal > App Settings > Basic)",
+        "validation": "^[a-f0-9]{32}$"
       }
     ],
-    "validation_endpoint": "https://graph.facebook.com/v18.0/me?access_token={whatsapp_access_token}",
+    "validation_endpoint": "https://graph.facebook.com/v25.0/me?access_token={whatsapp_access_token}",
     "setup_url": "https://developers.facebook.com/apps"
   },
   "capabilities": {
@@ -45,12 +50,14 @@
       "webhook": {
         "secret_header": "X-Hub-Signature-256",
         "secret_name": "whatsapp_verify_token",
-        "verify_token_param": "hub.verify_token"
+        "verification_mode": "query_param",
+        "hmac_secret_name": "whatsapp_app_secret",
+        "message_id_json_pointer": "/message_id"
       }
     }
   },
   "config": {
-    "api_version": "v18.0",
+    "api_version": "v25.0",
     "reply_to_message": true,
     "owner_id": null,
     "dm_policy": "pairing",

migrations/V10__webhook_dedup.sql

@@ -0,0 +1,24 @@
+-- Webhook message deduplication table
+-- Tracks which webhook messages have been processed to prevent duplicates
+-- when WhatsApp retries after a 500 response
+
+CREATE TABLE webhook_message_dedup (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    channel TEXT NOT NULL,
+    external_message_id TEXT NOT NULL,
+    processed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    UNIQUE(channel, external_message_id)
+);
+
+-- Index for fast lookup by channel + message_id
+CREATE INDEX idx_webhook_dedup_channel_msg ON webhook_message_dedup(channel, external_message_id);
+
+-- Auto-cleanup: delete entries older than 7 days (WhatsApp max retry window)
+-- Meta's webhook retry policy: retries for up to 7 days on 5xx errors
+-- See: https://developers.facebook.com/docs/graph-api/webhooks#retry
+-- This keeps the table small while covering all retry scenarios
+CREATE OR REPLACE FUNCTION cleanup_old_dedup_entries() RETURNS void AS $$
+BEGIN
+    DELETE FROM webhook_message_dedup WHERE processed_at < NOW() - INTERVAL '7 days';
+END;
+$$ LANGUAGE plpgsql;

src/agent/agent_loop.rs

@@ -77,6 +77,10 @@ pub struct AgentDeps {
     pub sse_tx: Option<tokio::sync::broadcast::Sender<crate::channels::web::types::SseEvent>>,
     /// HTTP interceptor for trace recording/replay.
     pub http_interceptor: Option<Arc<dyn crate::llm::recording::HttpInterceptor>>,
+    /// WASM channel router for webhook ACK signaling.
+    /// When set, the agent will signal ACK after persisting messages,
+    /// allowing webhooks to wait for persistence before returning 200 OK.
+    pub wasm_router: Option<Arc<crate::channels::wasm::router::WasmChannelRouter>>,
 }
 
 /// The main agent that coordinates all components.

src/agent/dispatcher.rs

@@ -1078,6 +1078,7 @@ mod tests {
             cost_guard: Arc::new(CostGuard::new(CostGuardConfig::default())),
             sse_tx: None,
             http_interceptor: None,
+            wasm_router: None,
         };
 
         Agent::new(
@@ -1818,6 +1819,7 @@ mod tests {
             cost_guard: Arc::new(CostGuard::new(CostGuardConfig::default())),
             sse_tx: None,
             http_interceptor: None,
+            wasm_router: None,
         };
 
         Agent::new(
@@ -1931,6 +1933,7 @@ mod tests {
                 cost_guard: Arc::new(CostGuard::new(CostGuardConfig::default())),
                 sse_tx: None,
                 http_interceptor: None,
+                wasm_router: None,
             };
 
             Agent::new(