#19804: WhatsApp: add history fetching and chat-level access control

## Summary This PR adds three new WhatsApp features to improve message history access and chat-level access control: 1. **Message history fetching**: When the message store is empty for a chat, the `read` action now attempts to fetch historical messages from WhatsApp using Baileys' internal API 2. **Full history sync on startup**: New `syncFullHistory` config option enables syncing complete message history when the gateway connects 3. **Chat-level allowlist**: New `allowChats` config option restricts the bot to specific chats/groups by JID These features address limitations where the bot couldn't access messages sent before it joined a group or started monitoring a chat. ## Change Type - [x] Feature - [ ] Bug fix - [ ] Documentation - [ ] Refactor - [ ] Test - [ ] Build/CI - [ ] Other ## Scope - [x] Integrations (WhatsApp) - [ ] Core - [ ] CLI - [ ] Gateway - [ ] Agents - [ ] UI - [ ] Documentation - [ ] Infrastructure ## User-Visible Changes ### New Configuration Options **`syncFullHistory`** (boolean, default: `false`) - When enabled, Baileys syncs full message history on gateway connection (happens once at startup) - Useful for ensuring the bot has access to historical context in groups/chats **`allowChats`** (string array, optional) - Restricts bot to specific chats/groups by JID - Format: `[120363425273773444@g.us, 1234567890@s.whatsapp.net]` - When set, bot only reads/replies in specified chats - Checked before `dmPolicy` and `groupPolicy` ### Enhanced `read` Action **`fetchHistory`** parameter (boolean, default: `true`) - When enabled and message store is empty, attempts to fetch historical messages from WhatsApp - Uses Baileys' internal `fetchMessageHistory` method - Note: WhatsApp protocol limitations mean on-demand fetching may not always work reliably ### Example Configuration ```json { providers: { whatsapp: { accounts: [ { id: main, syncFullHistory: true, allowChats: [120363425273773444@g.us] } ] } } } ``` ## Security Impact - [ ] Increases attack surface - [ ] Decreases attack surface - [x] No security impact - [ ] Requires security review **Details**: The `allowChats` option provides additional access control, reducing the bot's exposure to unwanted chats. History fetching uses existing Baileys APIs with no new external connections. ## Breaking Changes - [ ] Yes - [x] No ## Verification ### Testing Steps 1. Configure WhatsApp account with `syncFullHistory: true` and `allowChats: [<group-jid>]` 2. Restart gateway 3. Use `read` action on the allowed group - should return historical messages 4. Try `read` action on a non-allowed chat - should be rejected by access control 5. Send new message to allowed group - bot should respond (if auto-reply enabled) ### Evidence - [x] Tested locally - [x] Added/updated tests - [x] Updated documentation **Local Testing Results**: - History fetching successfully retrieves messages from WhatsApp (when protocol allows) - `allowChats` correctly restricts bot to specified chats - `syncFullHistory` enables full message history on gateway startup - Access control properly enforces chat allowlist before policy checks ## Documentation - [x] Updated `docs/channels/whatsapp-actions.md` with new features - [x] Added configuration examples - [x] Updated CHANGELOG.md ## Additional Context ### Implementation Details - Created `src/web/fetch-history.ts` with `fetchAndStoreHistory` function - Integrated history fetching into `ActiveListener` via `fetchHistory` method - Added config validation in Zod schemas - Implemented chat allowlist check in `src/web/inbound/access-control.ts` - All files kept under 700 LOC guideline - Comprehensive logging for debugging ### Limitations - WhatsApp protocol limitations mean on-demand history fetching may not always work reliably - `syncFullHistory` happens once at startup (not continuously) - History fetching depends on Baileys' internal API availability ### Related Issues Addresses user need for accessing historical messages in groups where the bot wasn't present from the start. ## Checklist - [x] Code follows project style guidelines - [x] Self-reviewed the code - [x] Commented tricky/non-obvious logic - [x] Updated documentation - [x] Added/updated tests - [x] All tests pass locally - [x] No new warnings introduced - [x] Changelog updated (user-facing changes only)