Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs: describe what a chat-restricted key gets over WebSocket and MCP
Yudhi Armyndharisee9409e8132d
diff --git a/README.md b/README.mdindex ec55af301..357e97148 100644--- a/README.md+++ b/README.md@@ -64,11 +64,11 @@ A session-scoped key still reaches every chat on the sessions it may use. A key- **One or more selected** — the key reaches only those chats. Every authenticated REST route not explicitly marked as safe for a chat-scoped key refuses it with `403` (a request naming a session outside `allowedSessions` is refused first, with `403 "API key not authorized for this session"`), including routes added in later releases: the refusal is the default. Inside its chats an operator key can do what the marked routes allow, which is more than reading and sending: it can also delete or clear a chat, leave or rename a group, and block the contact. It cannot change who belongs to a group: adding, removing, promoting or demoting participants, answering join requests and reading or resetting the invite link all stay closed.- **The two scopes are independent** — a key may be limited to sessions, to chats, to both, or to neither.-This lets you point an **AI agent or third-party integration at a shared account** without handing it every chat. Give the agent a key scoped to the few groups (or DMs) it is meant to handle: it can send and reply there, but it cannot list your other chats, read any other DM, message a contact outside its set, or reach the queue dashboard. It reads its chats' stored messages on either engine through `GET /sessions/{sessionId}/messages?chatId=`, where `chatId` is required for such a key, and live history through `GET /sessions/{sessionId}/messages/{chatId}/history` on whatsapp-web.js only. It receives no pushed events, so it has to poll. It can still read the session's own status (`GET /sessions/{sessionId}`) so an integration can tell whether it is connected.+This lets you point an **AI agent or third-party integration at a shared account** without handing it every chat. Give the agent a key scoped to the few groups (or DMs) it is meant to handle: it can send and reply there, but it cannot list your other chats, read any other DM, message a contact outside its set, or reach the queue dashboard. It reads its chats' stored messages on either engine through `GET /sessions/{sessionId}/messages?chatId=`, where `chatId` is required for such a key, and live history through `GET /sessions/{sessionId}/messages/{chatId}/history` on whatsapp-web.js only. It can subscribe to the `/events` WebSocket, which delivers only events for its chats. It can still read the session's own status (`GET /sessions/{sessionId}`) so an integration can tell whether it is connected.Identity is matched through the lid mapping table: a contact allowlisted by phone number also matches the same person's `@lid` privacy id once the table maps the two, and an unmapped `@lid` is refused rather than guessed. A lid's digits are never mistaken for a phone number, so `555000111@lid` does not admit `[email protected]`.-The default covers REST routes only. Surfaces that authenticate outside the REST guard do not inherit it, so each one that can return chat data refuses a chat-scoped key with its own check: the `/events` WebSocket, the MCP mount (per tool call), and the Bull Board queue dashboard. Four list routes are usable, each filtered to the key's chats before paging: `GET /sessions/{sessionId}/chats`, `GET /sessions/{sessionId}/groups` (id, name and community parent id only), `GET /sessions/{sessionId}/contacts` and `GET /sessions/{sessionId}/labels/{labelId}/chats`.+The default covers REST routes only. Surfaces that authenticate outside the REST guard do not inherit it, so each one that can return chat data applies the fence with its own check: the `/events` WebSocket delivers only events inside the key's chats, the MCP mount authorizes each tool call against them, and the Bull Board queue dashboard refuses the key. Four list routes are usable, each filtered to the key's chats before paging: `GET /sessions/{sessionId}/chats`, `GET /sessions/{sessionId}/groups` (id, name and community parent id only), `GET /sessions/{sessionId}/contacts` and `GET /sessions/{sessionId}/labels/{labelId}/chats`.The API also accepts `allowedChats` on an admin key, but no admin-only route is open to a chat-scoped key, and the last usable admin key cannot be scoped this way.diff --git a/dashboard/src/i18n/locales/ar.json b/dashboard/src/i18n/locales/ar.jsonindex f4ff7542f..dd6b7f8a2 100644--- a/dashboard/src/i18n/locales/ar.json+++ b/dashboard/src/i18n/locales/ar.json@@ -727,7 +727,7 @@},"chats": {"label": "الوصول إلى المحادثات (اختياري)",- "hint": "محادثة واحدة في كل سطر: معرّف مجموعة ينتهي بـ @g.us، أو معرّف جهة اتصال ينتهي بـ @c.us أو @lid، أو رقم هاتف. اتركه فارغًا لكل المحادثات. لا يمكن للمفتاح المقيَّد بمحادثات إلا استخدام المسارات المفتوحة لهذا النوع من المفاتيح؛ ويرفضه WebSocket الأحداث و MCP.",+ "hint": "محادثة واحدة في كل سطر: معرّف مجموعة ينتهي بـ @g.us، أو معرّف جهة اتصال ينتهي بـ @c.us أو @lid، أو رقم هاتف. اتركه فارغًا لكل المحادثات. لا يمكن للمفتاح المقيَّد بمحادثات إلا استخدام المسارات المفتوحة لهذا النوع من المفاتيح؛ ويقتصر وصوله عبر WebSocket الأحداث و MCP على هذه المحادثات.","invalid": "ليس معرّف محادثة أو رقم هاتف: {{value}}"},"expiry": {diff --git a/dashboard/src/i18n/locales/de.json b/dashboard/src/i18n/locales/de.jsonindex bce9fb1bb..b09257220 100644--- a/dashboard/src/i18n/locales/de.json+++ b/dashboard/src/i18n/locales/de.json@@ -702,7 +702,7 @@},"chats": {"label": "Chat-Zugriff (optional)",- "hint": "Ein Chat pro Zeile: eine Gruppen-ID mit @g.us, eine Kontakt-ID mit @c.us oder @lid oder eine Telefonnummer. Leer lassen für alle Chats. Ein auf Chats beschränkter Schlüssel kann nur die für solche Schlüssel freigegebenen Routen nutzen; der Events-WebSocket und MCP lehnen ihn ab.",+ "hint": "Ein Chat pro Zeile: eine Gruppen-ID mit @g.us, eine Kontakt-ID mit @c.us oder @lid oder eine Telefonnummer. Leer lassen für alle Chats. Ein auf Chats beschränkter Schlüssel kann nur die für solche Schlüssel freigegebenen Routen nutzen; sein Zugriff über den Events-WebSocket und MCP bleibt auf diese Chats beschränkt.","invalid": "Keine Chat-ID und keine Telefonnummer: {{value}}"},"expiry": {diff --git a/dashboard/src/i18n/locales/en.json b/dashboard/src/i18n/locales/en.jsonindex 0250ed9ec..643c7a62e 100644--- a/dashboard/src/i18n/locales/en.json+++ b/dashboard/src/i18n/locales/en.json@@ -702,7 +702,7 @@},"chats": {"label": "Chat access (optional)",- "hint": "One chat per line: a group ID ending in @g.us, a contact ID ending in @c.us or @lid, or a phone number. Leave empty for every chat. A chat-restricted key can use only the routes open to chat-scoped keys; the events WebSocket and MCP refuse it.",+ "hint": "One chat per line: a group ID ending in @g.us, a contact ID ending in @c.us or @lid, or a phone number. Leave empty for every chat. A chat-restricted key can use only the routes open to chat-scoped keys; its events WebSocket and MCP access stay within these chats.","invalid": "Not a chat ID or phone number: {{value}}"},"expiry": {diff --git a/dashboard/src/i18n/locales/es.json b/dashboard/src/i18n/locales/es.jsonindex d68782cec..3a6e563f5 100644--- a/dashboard/src/i18n/locales/es.json+++ b/dashboard/src/i18n/locales/es.json@@ -658,7 +658,7 @@},"chats": {"label": "Acceso a chats (opcional)",- "hint": "Un chat por línea: un ID de grupo que termina en @g.us, un ID de contacto que termina en @c.us o @lid, o un número de teléfono. Déjalo vacío para todos los chats. Una clave restringida a chats solo puede usar las rutas abiertas a ese tipo de clave; el WebSocket de eventos y MCP la rechazan.",+ "hint": "Un chat por línea: un ID de grupo que termina en @g.us, un ID de contacto que termina en @c.us o @lid, o un número de teléfono. Déjalo vacío para todos los chats. Una clave restringida a chats solo puede usar las rutas abiertas a ese tipo de clave; su acceso por el WebSocket de eventos y MCP se limita a esos chats.","invalid": "No es un ID de chat ni un número de teléfono: {{value}}"},"expiry": {diff --git a/dashboard/src/i18n/locales/fr.json b/dashboard/src/i18n/locales/fr.jsonindex d44824233..e6a2c8e57 100644--- a/dashboard/src/i18n/locales/fr.json+++ b/dashboard/src/i18n/locales/fr.json@@ -708,7 +708,7 @@},"chats": {"label": "Accès aux discussions (facultatif)",- "hint": "Une discussion par ligne : un ID de groupe se terminant par @g.us, un ID de contact se terminant par @c.us ou @lid, ou un numéro de téléphone. Laissez vide pour toutes les discussions. Une clé limitée à des discussions ne peut utiliser que les routes ouvertes à ce type de clé ; le WebSocket des événements et MCP la refusent.",+ "hint": "Une discussion par ligne : un ID de groupe se terminant par @g.us, un ID de contact se terminant par @c.us ou @lid, ou un numéro de téléphone. Laissez vide pour toutes les discussions. Une clé limitée à des discussions ne peut utiliser que les routes ouvertes à ce type de clé ; son accès par le WebSocket des événements et MCP reste limité à ces discussions.","invalid": "Ni un ID de discussion ni un numéro de téléphone : {{value}}"},"expiry": {diff --git a/dashboard/src/i18n/locales/he.json b/dashboard/src/i18n/locales/he.jsonindex df7d35dcb..82cee9414 100644--- a/dashboard/src/i18n/locales/he.json+++ b/dashboard/src/i18n/locales/he.json@@ -715,7 +715,7 @@},"chats": {"label": "גישה לצ'אטים (אופציונלי)",- "hint": "צ'אט אחד בכל שורה: מזהה קבוצה שמסתיים ב[email protected], מזהה איש קשר שמסתיים ב[email protected] או ב-@lid, או מספר טלפון. השאירו ריק לכל הצ'אטים. מפתח שמוגבל לצ'אטים יכול להשתמש רק בנתיבים הפתוחים למפתחות כאלה; ה-WebSocket של האירועים ו-MCP דוחים אותו.",+ "hint": "צ'אט אחד בכל שורה: מזהה קבוצה שמסתיים ב[email protected], מזהה איש קשר שמסתיים ב[email protected] או ב-@lid, או מספר טלפון. השאירו ריק לכל הצ'אטים. מפתח שמוגבל לצ'אטים יכול להשתמש רק בנתיבים הפתוחים למפתחות כאלה; הגישה שלו דרך ה-WebSocket של האירועים ו-MCP מוגבלת לצ'אטים האלה.","invalid": "אינו מזהה צ'אט או מספר טלפון: {{value}}"},"expiry": {diff --git a/dashboard/src/i18n/locales/hi.json b/dashboard/src/i18n/locales/hi.jsonindex a34dabb69..d27cdd37c 100644--- a/dashboard/src/i18n/locales/hi.json+++ b/dashboard/src/i18n/locales/hi.json@@ -702,7 +702,7 @@},"chats": {"label": "चैट पहुँच (वैकल्पिक)",- "hint": "हर पंक्ति में एक चैट: @g.us पर समाप्त होने वाली ग्रुप ID, @c.us या @lid पर समाप्त होने वाली संपर्क ID, या फ़ोन नंबर। सभी चैट के लिए खाली छोड़ें। चैट तक सीमित कुंजी केवल ऐसी कुंजियों के लिए खुले रूट उपयोग कर सकती है; इवेंट WebSocket और MCP उसे अस्वीकार करते हैं।",+ "hint": "हर पंक्ति में एक चैट: @g.us पर समाप्त होने वाली ग्रुप ID, @c.us या @lid पर समाप्त होने वाली संपर्क ID, या फ़ोन नंबर। सभी चैट के लिए खाली छोड़ें। चैट तक सीमित कुंजी केवल ऐसी कुंजियों के लिए खुले रूट उपयोग कर सकती है; इवेंट WebSocket और MCP के ज़रिए उसकी पहुँच इन्हीं चैट तक सीमित रहती है।","invalid": "यह चैट ID या फ़ोन नंबर नहीं है: {{value}}"},"expiry": {diff --git a/dashboard/src/i18n/locales/id.json b/dashboard/src/i18n/locales/id.jsonindex 44692c6c1..592777513 100644--- a/dashboard/src/i18n/locales/id.json+++ b/dashboard/src/i18n/locales/id.json@@ -702,7 +702,7 @@},"chats": {"label": "Akses obrolan (opsional)",- "hint": "Satu obrolan per baris: ID grup yang diakhiri @g.us, ID kontak yang diakhiri @c.us atau @lid, atau nomor telepon. Kosongkan untuk semua obrolan. Kunci yang dibatasi obrolan hanya dapat menggunakan rute yang terbuka untuk kunci dengan cakupan obrolan; WebSocket kejadian dan MCP menolaknya.",+ "hint": "Satu obrolan per baris: ID grup yang diakhiri @g.us, ID kontak yang diakhiri @c.us atau @lid, atau nomor telepon. Kosongkan untuk semua obrolan. Kunci yang dibatasi obrolan hanya dapat menggunakan rute yang terbuka untuk kunci dengan cakupan obrolan; akses lewat WebSocket kejadian dan MCP tetap terbatas pada obrolan tersebut.","invalid": "Bukan ID obrolan atau nomor telepon: {{value}}"},"expiry": {diff --git a/dashboard/src/i18n/locales/it.json b/dashboard/src/i18n/locales/it.jsonindex 99b87c4e7..3f72eb80a 100644--- a/dashboard/src/i18n/locales/it.json+++ b/dashboard/src/i18n/locales/it.json@@ -708,7 +708,7 @@},"chats": {"label": "Accesso alle chat (facoltativo)",- "hint": "Una chat per riga: un ID di gruppo che termina con @g.us, un ID di contatto che termina con @c.us o @lid, oppure un numero di telefono. Lascia vuoto per tutte le chat. Una chiave limitata alle chat può usare solo le rotte aperte a questo tipo di chiave; il WebSocket degli eventi e MCP la rifiutano.",+ "hint": "Una chat per riga: un ID di gruppo che termina con @g.us, un ID di contatto che termina con @c.us o @lid, oppure un numero di telefono. Lascia vuoto per tutte le chat. Una chiave limitata alle chat può usare solo le rotte aperte a questo tipo di chiave; il suo accesso tramite il WebSocket degli eventi e MCP resta limitato a queste chat.","invalid": "Non è un ID chat né un numero di telefono: {{value}}"},"expiry": {diff --git a/dashboard/src/i18n/locales/ko.json b/dashboard/src/i18n/locales/ko.jsonindex b47d469ee..9cbafffce 100644--- a/dashboard/src/i18n/locales/ko.json+++ b/dashboard/src/i18n/locales/ko.json@@ -702,7 +702,7 @@},"chats": {"label": "채팅 접근 (선택)",- "hint": "한 줄에 채팅 하나: @g.us로 끝나는 그룹 ID, @c.us 또는 @lid로 끝나는 연락처 ID, 또는 전화번호. 모든 채팅을 허용하려면 비워 두세요. 채팅이 제한된 키는 해당 키에 열린 경로만 사용할 수 있으며, 이벤트 WebSocket과 MCP는 이를 거부합니다.",+ "hint": "한 줄에 채팅 하나: @g.us로 끝나는 그룹 ID, @c.us 또는 @lid로 끝나는 연락처 ID, 또는 전화번호. 모든 채팅을 허용하려면 비워 두세요. 채팅이 제한된 키는 해당 키에 열린 경로만 사용할 수 있으며, 이벤트 WebSocket과 MCP를 통한 접근도 이 채팅으로 제한됩니다.","invalid": "채팅 ID 또는 전화번호가 아닙니다: {{value}}"},"expiry": {diff --git a/dashboard/src/i18n/locales/pt-BR.json b/dashboard/src/i18n/locales/pt-BR.jsonindex d4fc781ff..cb0cdfc1e 100644--- a/dashboard/src/i18n/locales/pt-BR.json+++ b/dashboard/src/i18n/locales/pt-BR.json@@ -658,7 +658,7 @@},"chats": {"label": "Acesso a chats (opcional)",- "hint": "Um chat por linha: um ID de grupo terminado em @g.us, um ID de contato terminado em @c.us ou @lid, ou um número de telefone. Deixe em branco para todos os chats. Uma chave restrita a chats só pode usar as rotas abertas a esse tipo de chave; o WebSocket de eventos e o MCP a recusam.",+ "hint": "Um chat por linha: um ID de grupo terminado em @g.us, um ID de contato terminado em @c.us ou @lid, ou um número de telefone. Deixe em branco para todos os chats. Uma chave restrita a chats só pode usar as rotas abertas a esse tipo de chave; o acesso dela pelo WebSocket de eventos e pelo MCP fica limitado a esses chats.","invalid": "Não é um ID de chat nem um número de telefone: {{value}}"},"expiry": {diff --git a/dashboard/src/i18n/locales/te.json b/dashboard/src/i18n/locales/te.jsonindex 58a2a823b..75759aaee 100644--- a/dashboard/src/i18n/locales/te.json+++ b/dashboard/src/i18n/locales/te.json@@ -702,7 +702,7 @@},"chats": {"label": "చాట్ యాక్సెస్ (ఐచ్ఛికం)",- "hint": "ప్రతి పంక్తికి ఒక చాట్: @g.us తో ముగిసే గ్రూప్ ID, @c.us లేదా @lid తో ముగిసే కాంటాక్ట్ ID, లేదా ఫోన్ నంబర్. అన్ని చాట్ల కోసం ఖాళీగా వదిలేయండి. చాట్లకు పరిమితమైన కీ అలాంటి కీలకు తెరిచిన రూట్లను మాత్రమే ఉపయోగించగలదు; ఈవెంట్స్ WebSocket మరియు MCP దాన్ని తిరస్కరిస్తాయి.",+ "hint": "ప్రతి పంక్తికి ఒక చాట్: @g.us తో ముగిసే గ్రూప్ ID, @c.us లేదా @lid తో ముగిసే కాంటాక్ట్ ID, లేదా ఫోన్ నంబర్. అన్ని చాట్ల కోసం ఖాళీగా వదిలేయండి. చాట్లకు పరిమితమైన కీ అలాంటి కీలకు తెరిచిన రూట్లను మాత్రమే ఉపయోగించగలదు; ఈవెంట్స్ WebSocket మరియు MCP ద్వారా దాని యాక్సెస్ ఈ చాట్లకే పరిమితం.","invalid": "ఇది చాట్ ID లేదా ఫోన్ నంబర్ కాదు: {{value}}"},"expiry": {diff --git a/dashboard/src/i18n/locales/tr.json b/dashboard/src/i18n/locales/tr.jsonindex 2a0c12455..19683d60b 100644--- a/dashboard/src/i18n/locales/tr.json+++ b/dashboard/src/i18n/locales/tr.json@@ -702,7 +702,7 @@},"chats": {"label": "Sohbet erişimi (isteğe bağlı)",- "hint": "Her satıra bir sohbet: @g.us ile biten bir grup kimliği, @c.us veya @lid ile biten bir kişi kimliği ya da bir telefon numarası. Tüm sohbetler için boş bırakın. Sohbetle sınırlı bir anahtar yalnızca bu tür anahtarlara açık yolları kullanabilir; olay WebSocket'i ve MCP onu reddeder.",+ "hint": "Her satıra bir sohbet: @g.us ile biten bir grup kimliği, @c.us veya @lid ile biten bir kişi kimliği ya da bir telefon numarası. Tüm sohbetler için boş bırakın. Sohbetle sınırlı bir anahtar yalnızca bu tür anahtarlara açık yolları kullanabilir; olay WebSocket'i ve MCP üzerinden erişimi de bu sohbetlerle sınırlı kalır.","invalid": "Sohbet kimliği veya telefon numarası değil: {{value}}"},"expiry": {diff --git a/dashboard/src/i18n/locales/zh-CN.json b/dashboard/src/i18n/locales/zh-CN.jsonindex 1605d6125..4affbbfe5 100644--- a/dashboard/src/i18n/locales/zh-CN.json+++ b/dashboard/src/i18n/locales/zh-CN.json@@ -702,7 +702,7 @@},"chats": {"label": "聊天访问(可选)",- "hint": "每行一个聊天:以 @g.us 结尾的群组 ID、以 @c.us 或 @lid 结尾的联系人 ID,或电话号码。留空则允许所有聊天。受聊天限制的密钥只能使用对此类密钥开放的路由;事件 WebSocket 和 MCP 会拒绝它。",+ "hint": "每行一个聊天:以 @g.us 结尾的群组 ID、以 @c.us 或 @lid 结尾的联系人 ID,或电话号码。留空则允许所有聊天。受聊天限制的密钥只能使用对此类密钥开放的路由;通过事件 WebSocket 和 MCP 的访问也仅限于这些聊天。","invalid": "不是聊天 ID 或电话号码:{{value}}"},"expiry": {diff --git a/dashboard/src/i18n/locales/zh-HK.json b/dashboard/src/i18n/locales/zh-HK.jsonindex d99a80c3a..bf3c70801 100644--- a/dashboard/src/i18n/locales/zh-HK.json+++ b/dashboard/src/i18n/locales/zh-HK.json@@ -702,7 +702,7 @@},"chats": {"label": "聊天存取(選填)",- "hint": "每行一個聊天:以 @g.us 結尾的群組 ID、以 @c.us 或 @lid 結尾的聯絡人 ID,或電話號碼。留空則允許所有聊天。受聊天限制的金鑰只可使用對此類金鑰開放的路由;事件 WebSocket 及 MCP 會拒絕它。",+ "hint": "每行一個聊天:以 @g.us 結尾的群組 ID、以 @c.us 或 @lid 結尾的聯絡人 ID,或電話號碼。留空則允許所有聊天。受聊天限制的金鑰只可使用對此類金鑰開放的路由;透過事件 WebSocket 及 MCP 的存取亦僅限於這些聊天。","invalid": "不是聊天 ID 或電話號碼:{{value}}"},"expiry": {diff --git a/docs/04-security-design.md b/docs/04-security-design.mdindex 4e19c89fa..f0030509c 100644--- a/docs/04-security-design.md+++ b/docs/04-security-design.md@@ -83,11 +83,11 @@ three scoping dimensions enforced by `ApiKeyGuard`.A route declares its minimum level with `@RequireRole(...)`; a key passes when its role ranks at orabove that level (`AuthService.hasPermission`). A key below it is rejected with `403 Forbidden`.-| Scope | Field | Effect |-| --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |-| Source IP | `allowedIps` | Empty/absent = unrestricted; non-empty = fail-closed IP whitelist (see §4.3) |-| Sessions | `allowedSessions` | Empty/absent = every session; non-empty = a request carrying any other session id is rejected with `403` |-| Chats | `allowedChats` | Empty/absent = every chat; non-empty = default-deny: only chat-scoped routes, and only for a listed chat, else `403`; `/events`, MCP and Bull Board refuse the key |+| Scope | Field | Effect |+| --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Source IP | `allowedIps` | Empty/absent = unrestricted; non-empty = fail-closed IP whitelist (see §4.3) |+| Sessions | `allowedSessions` | Empty/absent = every session; non-empty = a request carrying any other session id is rejected with `403` |+| Chats | `allowedChats` | Empty/absent = every chat; non-empty = default-deny: only chat-scoped routes, MCP tools and events, only for a listed chat, else `403`; Bull Board refuses it |The key-lifecycle routes (`/api/auth/api-keys`) are additionally fenced with `@RequireUnscopedKey()`:a session-scoped key is refused there whatever its role, so it cannot mint or widen credentialsdiff --git a/docs/26-global-search.md b/docs/26-global-search.mdindex 5239a209d..4378419ff 100644--- a/docs/26-global-search.md+++ b/docs/26-global-search.md@@ -141,6 +141,11 @@ GET /api/search?q=<term>&sessionId=<id>&chatId=<id>&direction=<incoming|outgoingkey with a non-empty `allowedSessions` searches only those sessions, whatever its role, even if itpasses `sessionId`; a key with a null or empty `allowedSessions` searches all sessions. The DTOcarries no `sessionIds` field (it would be rejected as non-whitelisted).+- **Chat scope applies the same way.** A key with a non-empty `allowedChats` searches only those+ chats: the built-in provider narrows its hits before `limit`, `offset` and `total` apply, an explicit+ `chatId` outside the allowlist answers `403`, and a plugin provider answers `403` for such a key+ (set `SEARCH_PROVIDER=builtin-fts` to allow scoped search). On SQLite a hit's relevance `score` is+ computed over the whole index, so it reflects messages outside the allowed chats too.- **Response** is a `SearchResults` object: `{ hits: SearchHit[], total, tookMs, provider }`. Each hitcarries `messageId`, `waMessageId`, `sessionId`, `chatId`, `body`, `snippet`, `timestamp`, `type`,`direction`, `from`, and optional `score`. `total` is an exact count (bounded; computed lazily only