Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
feat(auth): chat-scope search and group detail routes (#1774)
Yudhi Armyndharisd9e61b833957
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex d80224d50..debc50ecd 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Carry `chatId` in `message.ack` and `message.failed` payloads so a webhook `chatId` filter scopes delivery events per chat.- Filter stored messages by time, direction, type or message reference, with stable message-time pagination.+- Scope built-in message search and group detail/settings to a chat-restricted key's allowed chats; reject plugin search for these keys.- Expose poll choices and selection mode in message events, stored messages, history, and dashboard chats.- Expose optional last-message types in chat lists and SDKs.- Add bounded webhook failure redrive with optional payload retention.diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 1ba75aef4..0af4d5105 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -47,7 +47,7 @@ API keys carry one of three roles, ordered by privilege:A key may additionally be scoped to specific sessions (`allowedSessions`) and/or source IPs (`allowedIps`). The scope/IP check runs in the guard **before** any role check, so a request outside that scope is rejected with `403` even if the role would otherwise allow it. `401` is kept for a missing, unknown, revoked or expired key.-A key may also be restricted to selected chats (`allowedChats`: group `<id>@g.us`, contact `<phone>@c.us` or `<lid>@lid`, or a bare phone number, which is stored as `<phone>@c.us`). An empty or absent list leaves the key unrestricted. A chat-restricted key is **denied by default**: it may call only routes marked as chat-scoped, and every other route (webhooks, automation, status, channels, key management, and any route added later) answers `403 "API key is restricted to selected chats"` after the role check. On a chat-scoped route, every chat id the request names (a `:chatId` / `:groupId` / `:contactId` path param, `?chatId=`, a body `chatId` / `fromChatId` / `toChatId`, and each `messages[].chatId` of a bulk send) must be inside the allowlist, or the request answers `403 "API key not authorized for this chat"`; a contact entry also matches its mapped `@lid` form, and the reverse. The chat, group, contact and label-chat list routes (`GET /api/sessions/:sessionId/chats`, `/groups`, `/contacts` and `/labels/:labelId/chats`) return only the allowed entries, filtered before paging. On `GET /api/sessions/:sessionId/messages` such a key must pass `?chatId=`; omitting it answers `403`. A `quotedMessageId` is refused with `403` everywhere except the reply route, which binds the quote to the chat it sends into. The surfaces outside the REST guard refuse a chat-restricted key outright: the `/events` WebSocket at the handshake and on every subscribe, every MCP tool call (`403`), and the Bull Board queue dashboard (`403`).+A key may also be restricted to selected chats (`allowedChats`: group `<id>@g.us`, contact `<phone>@c.us` or `<lid>@lid`, or a bare phone number, which is stored as `<phone>@c.us`). An empty or absent list leaves the key unrestricted. A chat-restricted key is **denied by default**: it may call only routes marked as chat-scoped, and every other route (webhooks, automation, status, channels, key management, and any route added later) answers `403 "API key is restricted to selected chats"` after the role check. On a chat-scoped route, every chat id the request names (a `:chatId` / `:groupId` / `:contactId` path param, `?chatId=`, a body `chatId` / `fromChatId` / `toChatId`, and each `messages[].chatId` of a bulk send) must be inside the allowlist, or the request answers `403 "API key not authorized for this chat"`; a contact entry also matches its mapped `@lid` form, and the reverse. The chat, group, contact and label-chat list routes (`GET /api/sessions/:sessionId/chats`, `/groups`, `/contacts` and `/labels/:labelId/chats`) return only the allowed entries, filtered before paging. `GET /api/search` with the built-in provider narrows its hits to the allowed chats before `limit`/`offset`/`total` apply, and an optional `?chatId=` must name an allowed chat. Plugin providers return `403` for these keys before the worker is invoked; set `SEARCH_PROVIDER=builtin-fts` to enable scoped search. `GET /api/sessions/:sessionId/groups/:groupId` and its `GET`/`PUT .../settings` admit a group inside the allowlist and answer `403` for any other. On `GET /api/sessions/:sessionId/messages` such a key must pass `?chatId=`; omitting it answers `403`. A `quotedMessageId` is refused with `403` everywhere except the reply route, which binds the quote to the chat it sends into. The surfaces outside the REST guard refuse a chat-restricted key outright: the `/events` WebSocket at the handshake and on every subscribe, every MCP tool call (`403`), and the Bull Board queue dashboard (`403`).### API-Key Lifecycle@@ -2861,7 +2861,7 @@ Raw object (no envelope). `engine.getGroupInfo()` returns `GroupInfo | null`; th}```-**Errors:** `400` session is not started · `401` missing/invalid `X-API-Key` · `404` `Group <groupId> not found` · `409` conflict or engine not ready (retryable) · `503` session not ready or dependency unavailable (retryable); on Baileys, also when WhatsApp rate-limits or times out the request (code 429 or 408): retry after a pause+**Errors:** `400` session is not started · `401` missing/invalid `X-API-Key` · `403` a key restricted to selected chats names a group outside its allowlist · `404` `Group <groupId> not found` · `409` conflict or engine not ready (retryable) · `503` session not ready or dependency unavailable (retryable); on Baileys, also when WhatsApp rate-limits or times out the request (code 429 or 408): retry after a pause#### GET /api/sessions/:sessionId/groups/:groupId/picture@@ -3328,7 +3328,7 @@ accept it, but they encode it differently underneath — Baileys as a boolean wh_everyone_, whatsapp-web.js as WhatsApp's own `all_member_add`/`admin_add` strings (its typings claima boolean with the opposite sense). The adapters normalise both to these two values.-**Errors:** `400` session is not started · `401` missing/invalid `X-API-Key` · `404` group not found · `409` conflict or engine not ready (retryable) · `503` session not ready or dependency unavailable (retryable); on Baileys, also when WhatsApp rate-limits or times out the request (code 429 or 408): retry after a pause+**Errors:** `400` session is not started · `401` missing/invalid `X-API-Key` · `403` a key restricted to selected chats names a group outside its allowlist · `404` group not found · `409` conflict or engine not ready (retryable) · `503` session not ready or dependency unavailable (retryable); on Baileys, also when WhatsApp rate-limits or times out the request (code 429 or 408): retry after a pause#### PUT /api/sessions/:sessionId/groups/:groupId/settings@@ -3367,7 +3367,7 @@ Update group settings. Each present field maps to one engine call; absent fields{ "success": true, "message": "Group settings updated" }```-**Errors:** `400` session is not started / empty patch / unknown body field · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role, or the account is not a group admin (`memberAddMode` on whatsapp-web.js) · `501` `ephemeralSeconds` on the whatsapp-web.js engine (library limitation) · `409` conflict or engine not ready (retryable) · `503` session not ready or dependency unavailable (retryable); on Baileys, also when WhatsApp rate-limits or times out the request (code 429 or 408): retry after a pause+**Errors:** `400` session is not started / empty patch / unknown body field · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role, the account is not a group admin (`memberAddMode` on whatsapp-web.js), or a key restricted to selected chats names a group outside its allowlist · `501` `ephemeralSeconds` on the whatsapp-web.js engine (library limitation) · `409` conflict or engine not ready (retryable) · `503` session not ready or dependency unavailable (retryable); on Baileys, also when WhatsApp rate-limits or times out the request (code 429 or 408): retry after a pause#### GET /api/sessions/:sessionId/groups/:groupId/membership-requests@@ -6501,7 +6501,7 @@ Search messages across sessions (active search provider).| ----------- | ------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || `q` | string | **Yes** | — | Search term. Must be non-empty after trim; whitespace-only is rejected with `400`. Passed to the active provider's native full-text matcher. || `sessionId` | string | No | — | Restrict to a single session id (intersected with the key's `allowedSessions` scope). |-| `chatId` | string | No | — | Restrict to a single chat id. |+| `chatId` | string | No | — | Restrict to a single chat id. For a key restricted to selected chats this must name an allowed chat (`403` otherwise), and its hits are additionally narrowed to the allowlist. || `direction` | enum (`incoming` \| `outgoing`) | No | — | Filter by message direction. || `type` | string | No | — | Filter by stored message `type` (e.g. `text`, `image`, `video`). Compared against `messages.type`; not an enum validation, any string is accepted and unmatched values simply return no hits. || `from` | string | No | — | Filter by sender. |@@ -6546,7 +6546,8 @@ Search messages across sessions (active search provider).**Errors:** `400` empty/whitespace `q`, a non-numeric `dateFrom`/`dateTo`/`limit`/`offset`, an `offset` above `100000`, or a malformedSQLite FTS5 query (unbalanced quote/paren, bare operator) — Postgres's `websearch_to_tsquery` is-tolerant and has no equivalent · `401` missing/invalid `X-API-Key` · `403` key role below `OPERATOR` ·+tolerant and has no equivalent · `401` missing/invalid `X-API-Key` · `403` key role below `OPERATOR`, or a chat-restricted key+that names a `chatId` outside its allowlist or uses a plugin provider ·`501` no search provider configured (including a non-FTS5 SQLite build, where the provider is absent) ·`502` the active plugin provider returned an invalid result shape (not retryable until the plugin is fixed) ·`503` the active plugin provider did not answer (worker not running, timed out, or reported a failure;@@ -6554,7 +6555,11 @@ retryable). The built-in provider returns neither `502` nor `503`.> Scoping is authoritative: a scoped API key's `allowedSessions` is applied server-side and cannot be> overridden via the query — there is no `sessionIds` query parameter, and `SearchService` overwrites-> any session scope at the provider boundary.+> any session scope at the provider boundary. The same holds for the chat scope: a key restricted to+> selected chats sees only hits inside its allowlist with the built-in provider (expanded lid-aware+> before SQL filtering, so `limit`/`offset`/`total` all describe the scoped result set). A compiled+> chat scope with no valid ids returns no hits and a zero total. Plugin search refuses these keys+> before invoking the worker. There is no `chatIds` query parameter.### 6.4.13 Profile (own account)diff --git a/docs/27-plugin-search-providers.md b/docs/27-plugin-search-providers.mdindex 69d8c3faf..ac7d0cea8 100644--- a/docs/27-plugin-search-providers.md+++ b/docs/27-plugin-search-providers.md@@ -48,7 +48,7 @@ returns a `SearchResults`:```tsctx.registerSearchProvider(async (query) => {- // query: SearchQuery — { q, sessionIds?, sessionId?, chatId?, direction?, type?, from?, dateFrom?, dateTo?, limit?, offset? }+ // query: SearchQuery, { q, sessionIds?, sessionId?, chatId?, direction?, type?, from?, dateFrom?, dateTo?, limit?, offset? }// Run your backend's query here (e.g. a Meilisearch /search call).return {hits: [...], // SearchHit[] — see below@@ -292,6 +292,10 @@ ctx interface is planned; for now the search contract types above are the stable`query.sessionIds` — the plugin should honor it (filter by `sessionIds` in the backend query) forcorrect results + performance. The host re-filters as defense-in-depth, but a plugin that ignores`sessionIds` returns more rows than needed (wasteful) and relies on the host to strip them.+- **Chat-restricted keys require the built-in provider.** Plugin search returns `403` before invoking+ the worker for these keys. Filtering a plugin's returned page cannot enforce scoped offsets or+ counts. Use `SEARCH_PROVIDER=builtin-fts` to enable search for chat-restricted keys. A compiled+ chat scope with no valid ids returns no hits and a zero total without invoking the worker.- **`message:persisted` is fire-and-forget.** An error in the indexing handler is swallowed (it must notbreak the send/receive pipeline). Log errors via `ctx.logger` and retry/mirror in your backend's ownretry queue if you need stronger delivery guarantees.diff --git a/openapi.json b/openapi.jsonindex ee6355986..7de2f8a62 100644--- a/openapi.json+++ b/openapi.json@@ -9730,7 +9730,7 @@}},"403": {- "description": "The API key's role, session or chat scope, or IP allow-list does not allow this operation",+ "description": "The API key is restricted to selected chats and this group is outside its allowlist. Also returned when the API key's role, session or chat scope, or IP allow-list does not allow this operation.","content": {"application/json": {"schema": {@@ -9923,7 +9923,7 @@}},"403": {- "description": "The API key's role, session or chat scope, or IP allow-list does not allow this operation",+ "description": "The API key is restricted to selected chats and this group is outside its allowlist. Also returned when the API key's role, session or chat scope, or IP allow-list does not allow this operation.","content": {"application/json": {"schema": {@@ -17819,7 +17819,7 @@}},"403": {- "description": "The API key's role, session or chat scope, or IP allow-list does not allow this operation",+ "description": "Chat scope denied or chat-restricted search uses a plugin provider. Also returned when the API key's role, session or chat scope, or IP allow-list does not allow this operation.","content": {"application/json": {"schema": {diff --git a/src/modules/auth/chat-scope-coverage.spec.ts b/src/modules/auth/chat-scope-coverage.spec.tsindex 0e5cee96b..1592dc5a6 100644--- a/src/modules/auth/chat-scope-coverage.spec.ts+++ b/src/modules/auth/chat-scope-coverage.spec.ts@@ -14,7 +14,10 @@// `?chatId=` qualifies only when the handler also calls// `this.chatScope.requireChat(`, which refuses a restricted key that omits// it; on its own the guard would have nothing to check.-// @ChatScoped('filtered') the handler lists chats and returns through ChatScopeService.filter.+// @ChatScoped('filtered') the handler narrows a chat-typed result set to the key's chats: a list+// route returns through ChatScopeService.filter, and a query surface+// (search) passes ChatScopeService.idsForFilter into the provider so the+// filter applies before limit/offset/total.// @ChatScoped('agnostic') the handler cannot reach a chat at all. This is the one category the// spec cannot derive (a webhook with `events: ['*']` also names no chat),// so every grant must also appear in AGNOSTIC_GRANTS.@@ -87,6 +90,14 @@ export const MUST_STAY_MARKED: ReadonlyArray<readonly [string, string, string]>['session.controller.ts', 'getGroups', 'filtered'],['contact.controller.ts', 'findAll', 'filtered'],['label.controller.ts', 'getChatsByLabel', 'filtered'],+ // Search narrows hits to the key's chats inside the providers, before limit/offset/total; the+ // optional ?chatId= is fenced by the guard on top of that.+ ['search.controller.ts', 'search', 'filtered'],+ // Group detail and settings for a group the key may already read and write into: the roster is+ // member-visible data, largely inferable from the group's own messages.+ ['group.controller.ts', 'findOne', 'fenced'],+ ['group.controller.ts', 'getSettings', 'fenced'],+ ['group.controller.ts', 'updateSettings', 'fenced'],];const REQUIRED_GUARD_FIELD = new RegExp(`\\b(?:${GUARD_BODY_CHAT_FIELDS.join('|')})!\\s*:`);@@ -180,7 +191,8 @@ export function chatScopeViolations(/@Query\(\s*['"]chatId['"]\s*\)/.test(body) && /this\.chatScope\.requireChat\(/.test(body);if (kind === 'fenced' && !(hasPathChat || hasRequiredBodyChat || hasRequiredQueryChat))offenders.push(`${name} (fenced, no guard-read chat)`);- else if (kind === 'filtered' && !/chatScope\.filter\(/.test(body)) offenders.push(`${name} (filtered, no filter)`);+ else if (kind === 'filtered' && !/chatScope\.(filter|idsForFilter)\(/.test(body))+ offenders.push(`${name} (filtered, no filter)`);else if (kind === 'agnostic' && !agnosticGrants.some(([f, h]) => f === file && h === name))offenders.push(`${name} (agnostic, not on AGNOSTIC_GRANTS)`);else if (!['fenced', 'filtered', 'agnostic'].includes(kind)) offenders.push(`${name} (unknown kind '${kind}')`);diff --git a/src/modules/auth/chat-scope.service.spec.ts b/src/modules/auth/chat-scope.service.spec.tsindex 8b9220243..d78fe3447 100644--- a/src/modules/auth/chat-scope.service.spec.ts+++ b/src/modules/auth/chat-scope.service.spec.ts@@ -62,6 +62,16 @@ describe('ChatScopeService', () => {expect(await svc.filter({ allowedChats: null }, rows, r => r.id)).toEqual(rows);});+ it('idsForFilter returns the expanded id array, or undefined when unrestricted', async () => {+ const svc = new ChatScopeService(fakeStore());+ const ids = await svc.idsForFilter({ allowedChats: [`${PHONE}@c.us`, '[email protected]'] });+ expect(ids).toEqual(expect.arrayContaining([`${PHONE}@c.us`, `${PHONE}@s.whatsapp.net`, `${LID}@lid`, '[email protected]']));+ expect(await svc.idsForFilter({ allowedChats: null })).toBeUndefined();+ expect(await svc.idsForFilter({ allowedChats: [] })).toBeUndefined();+ expect(await svc.idsForFilter({ allowedChats: ['not-a-chat'] })).toEqual([]);+ expect(await svc.idsForFilter(undefined)).toBeUndefined();+ });+it('does not admit a phone whose lid another node has re-mapped', async () => {const rows = [{ lid: LID, phone: PHONE as string | null }];const hit = (value: string | null, cond?: string | FindOperator<unknown>) =>diff --git a/src/modules/auth/chat-scope.service.ts b/src/modules/auth/chat-scope.service.tsindex bf2102faf..a8164289b 100644--- a/src/modules/auth/chat-scope.service.ts+++ b/src/modules/auth/chat-scope.service.ts@@ -60,10 +60,20 @@ export class ChatScopeService {}/** The allowlist expanded once with the lid table (batched), for filtering a whole list. */- scopeForFilter(apiKey: Pick<ApiKey, 'allowedChats'> | null | undefined): Promise<ChatScope | null> {+ scopeForFilter(apiKey?: Pick<ApiKey, 'allowedChats'> | null): Promise<ChatScope | null> {return buildExpandedChatScope(apiKey?.allowedChats ?? null, this.batchDirectory());}+ /**+ * The expanded allowlist as a plain id array, for surfaces that filter at the query level+ * (search's SQL `IN`), or `undefined` when the key is unrestricted. Same expansion as+ * {@link scopeForFilter}: both stored dialects of every entry, lid twins included.+ */+ async idsForFilter(apiKey?: Pick<ApiKey, 'allowedChats'> | null): Promise<string[] | undefined> {+ const scope = await this.scopeForFilter(apiKey);+ return scope ? [...scope.allowed] : undefined;+ }+/** The subset of `items` whose chat id is inside the key's fence (unrestricted ⇒ unchanged). */async filter<T>(apiKey: Pick<ApiKey, 'allowedChats'> | null | undefined,diff --git a/src/modules/group/group.controller.ts b/src/modules/group/group.controller.tsindex fa89c1e08..95d502207 100644--- a/src/modules/group/group.controller.ts+++ b/src/modules/group/group.controller.ts@@ -108,11 +108,19 @@ export class GroupController {return this.groupService.getGroupJoinInfo(sessionId, code);}+ // Chat-fenced on `:groupId`: a key restricted to selected chats reads (and rewrites, below) the+ // settings of a group inside its allowlist and is refused on any other. The roster this route+ // returns is member-visible data the key can already largely infer from the group's own messages.+ @ChatScoped('fenced')@Get(':groupId')@ApiOperation({ summary: 'Get detailed group info' })@ApiParam({ name: 'sessionId', description: 'Session ID' })@ApiParam({ name: 'groupId', description: 'Group ID (e.g., [email protected])' })@ApiResponse({ status: 200, description: 'Group details with participants', type: GroupInfoDto })+ @ApiResponse({+ status: 403,+ description: 'The API key is restricted to selected chats and this group is outside its allowlist.',+ })@ApiResponse({status: 503,description:@@ -148,12 +156,17 @@ export class GroupController {return { success: true, groupId };}+ @ChatScoped('fenced')@Get(':groupId/settings')@ApiOperation({ summary: 'Get group settings (announce / locked / ephemeral timer)' })@ApiParam({ name: 'sessionId', description: 'Session ID' })@ApiParam({ name: 'groupId', description: 'Group ID' })@ApiResponse({ status: 200, description: 'Group settings', type: GroupSettingsResponseDto })@ApiResponse({ status: 404, description: 'Group not found' })+ @ApiResponse({+ status: 403,+ description: 'The API key is restricted to selected chats and this group is outside its allowlist.',+ })@ApiResponse({status: 503,description: 'WhatsApp did not answer within the request budget — nothing could be read.' + THROTTLED_503,@@ -164,6 +177,7 @@ export class GroupController {return this.groupService.getGroupSettings(sessionId, groupId);}+ @ChatScoped('fenced')@Put(':groupId/settings')@RequireRole(ApiKeyRole.OPERATOR)@ApiOperation({ summary: 'Update group settings (announce / locked / ephemeral timer)' })diff --git a/src/modules/search/dto/search-query.dto.ts b/src/modules/search/dto/search-query.dto.tsindex 960ec2a8a..ffa0f04dd 100644--- a/src/modules/search/dto/search-query.dto.ts+++ b/src/modules/search/dto/search-query.dto.ts@@ -12,9 +12,9 @@ import { SEARCH_OFFSET_MAX } from '../search.constants';* from the global ValidationPipe, never reaching the provider as a NaN SQL param. The epoch-ms* bounds `dateFrom`/`dateTo` use `@IsNumber()`; `limit`/`offset` use `@IsInt()`, because they are* bound straight into `LIMIT ?`/`OFFSET ?` where better-sqlite3 rejects a fractional value with- * SQLITE_MISMATCH: a fraction has to be a 400 here rather than a driver-level 500. `sessionIds` is- * intentionally absent: scope is injected by SearchService from the caller's API-key- * allowedSessions (never user-supplied).+ * SQLITE_MISMATCH: a fraction has to be a 400 here rather than a driver-level 500. `sessionIds` and+ * `chatIds` are intentionally absent: both scopes are injected by SearchService from the caller's+ * API-key allowedSessions/allowedChats (never user-supplied).*/export class SearchQueryDto {@ApiProperty({ description: 'Search term (required, non-empty)' })diff --git a/src/modules/search/providers/builtin-fts.provider.postgres.spec.ts b/src/modules/search/providers/builtin-fts.provider.postgres.spec.tsindex ec14f24b2..bb7264cd6 100644--- a/src/modules/search/providers/builtin-fts.provider.postgres.spec.ts+++ b/src/modules/search/providers/builtin-fts.provider.postgres.spec.ts@@ -79,6 +79,20 @@ describe('BuiltInFtsProvider (postgres probe)', () => {expect((await provider.health()).ok).toBe(true);});+ it.each([['[email protected]', '111@lid'], []])('applies chat scope to PostgreSQL rows and count (%j)', async (...chatIds) => {+ const { ds, query } = makePostgresDataSource({ bodyTsPresent: true });+ await new BuiltInFtsProvider(ds).search({ q: 'hello', chatIds, limit: 1, offset: 1 });+ const calls = query.mock.calls+ .map(call => call as unknown[])+ .filter(call => /websearch_to_tsquery/.test(String(call[0])));+ expect(calls).toHaveLength(2);+ for (const [sql] of calls) {+ expect(String(sql)).toContain(chatIds.length ? 'm."chatId" IN ($2,$3)' : '1 = 0');+ }+ expect(calls[0][1]).toEqual(['hello', ...chatIds, 1, 1]);+ expect(calls[1][1]).toEqual(['hello', ...chatIds]);+ });+it('does not credit a namesake in another schema: an empty active-schema probe means 501, not "available"', async () => {// A public.messages.body_ts must not make FTS look available when the table the search queries// resolve (active schema) lacks the column. The scripted probe answers for the resolved tablediff --git a/src/modules/search/providers/builtin-fts.provider.spec.ts b/src/modules/search/providers/builtin-fts.provider.spec.tsindex 84f35268b..1e04a9fdc 100644--- a/src/modules/search/providers/builtin-fts.provider.spec.ts+++ b/src/modules/search/providers/builtin-fts.provider.spec.ts@@ -132,6 +132,42 @@ describe('BuiltInFtsProvider (sqlite)', () => {expect(one.hits.map(h => h.sessionId)).toEqual(['s2']);});+ it('scopes by chatIds (auth allowlist) before limit/offset/total', async () => {+ // The chat fence arrives as the stored-dialect forms of the key's allowlist (lid expansion is+ // ChatScopeService's job); hits in any other chat disappear from the page AND from the count,+ // so pagination windows stay honest.+ const scoped = await provider.search({ q: 'hello', chatIds: ['c2'] });+ expect(scoped.hits.map(h => h.chatId)).toEqual(['c2']);+ expect(scoped.total).toBe(1);+ const none = await provider.search({ q: 'hello', chatIds: ['cX'] });+ expect(none.hits).toEqual([]);+ expect(none.total).toBe(0);+ await ds.getRepository(Message).insert({+ sessionId: 's2',+ chatId: 'c2',+ from: '[email protected]',+ to: '[email protected]',+ body: 'hello there',+ type: 'text',+ direction: MessageDirection.INCOMING,+ timestamp: 4,+ });+ const pages = await Promise.all(+ [0, 1, 2].map(offset => provider.search({ q: 'hello', chatIds: ['c2'], limit: 1, offset })),+ );+ expect(pages.map(page => page.total)).toEqual([2, 2, 2]);+ expect(pages.flatMap(page => page.hits).map(hit => hit.chatId)).toEqual(['c2', 'c2']);+ expect(new Set(pages.flatMap(page => page.hits).map(hit => hit.messageId)).size).toBe(2);+ expect((await provider.search({ q: 'hello', chatIds: ['c2'], chatId: 'c1' })).total).toBe(0);+ expect((await provider.search({ q: 'hello', chatIds: ['c2'], sessionIds: ['s1'] })).total).toBe(0);+ });++ it.each([0, 1])('returns no hits or count for an empty compiled chat scope at offset %s', async offset => {+ const result = await provider.search({ q: 'hello', chatIds: [], limit: 1, offset });+ expect(result.hits).toEqual([]);+ expect(result.total).toBe(0);+ });+it('returns empty (not error) for no matches', async () => {const res = await provider.search({ q: 'zzzznomatch' });expect(res.hits).toEqual([]);diff --git a/src/modules/search/providers/builtin-fts.provider.ts b/src/modules/search/providers/builtin-fts.provider.tsindex 6913380de..079caf54a 100644--- a/src/modules/search/providers/builtin-fts.provider.ts+++ b/src/modules/search/providers/builtin-fts.provider.ts@@ -375,6 +375,12 @@ export class BuiltInFtsProvider implements SearchProvider, OnModuleInit {where.push(`${prefix}"chatId" = ${ph()}`);params.push(q.chatId);}+ if (q.chatIds?.length === 0) where.push('1 = 0');+ else if (q.chatIds) {+ const placeholders = q.chatIds.map(() => ph()).join(',');+ where.push(`${prefix}"chatId" IN (${placeholders})`);+ params.push(...q.chatIds);+ }if (q.from) {where.push(`${prefix}"from" = ${ph()}`);params.push(q.from);diff --git a/src/modules/search/providers/plugin-search-provider.spec.ts b/src/modules/search/providers/plugin-search-provider.spec.tsindex 045a12de3..632fd508e 100644--- a/src/modules/search/providers/plugin-search-provider.spec.ts+++ b/src/modules/search/providers/plugin-search-provider.spec.ts@@ -1,4 +1,4 @@-import { BadGatewayException, ServiceUnavailableException } from '@nestjs/common';+import { BadGatewayException, ForbiddenException, ServiceUnavailableException } from '@nestjs/common';import { MessageDirection } from '../../message/entities/message.entity';import { PluginSearchProvider } from './plugin-search-provider';import type { PluginSearchTransport } from './plugin-search-provider';@@ -85,6 +85,31 @@ describe('PluginSearchProvider', () => {expect(res.provider).toBe('plugin:p');});+ it.each(['empty', 'allowed', 'outside'])('refuses chat-restricted searches before RPC (%s page)', async page => {+ const hits = page === 'empty' ? [] : [mkHit({ chatId: page === 'allowed' ? '[email protected]' : '[email protected]' })];+ const results: SearchResults = { hits, total: 731, tookMs: 3, provider: 'plugin:p' };+ const dispatchSearch = jest.fn().mockResolvedValue({ ok: true, results });+ const p = new PluginSearchProvider('p', 'P', fakeTransport({ dispatchSearch }), 1000);++ await expect(p.search({ q: 'hi', chatIds: ['[email protected]', '[email protected]'] })).rejects.toBeInstanceOf(+ ForbiddenException,+ );+ expect(dispatchSearch).not.toHaveBeenCalled();+ });++ it('returns no hits for an empty compiled chat scope without dispatching to the plugin', async () => {+ const dispatchSearch = jest.fn();+ const transport = fakeTransport({ dispatchSearch });+ const p = new PluginSearchProvider('p', 'P', transport, 1000);+ await expect(p.search({ q: 'hi', chatIds: [], offset: 5 })).resolves.toEqual({+ hits: [],+ total: 0,+ tookMs: 0,+ provider: 'plugin:p',+ });+ expect(dispatchSearch).not.toHaveBeenCalled();+ });+it('preserves the plugin total when all hits are in-scope (pagination must still work)', async () => {// A well-behaved plugin returns a full page of in-scope hits with the true total spanning more pages.// Overwriting total with the page hit count would make "Load More" (hits.length < total) never fire,diff --git a/src/modules/search/providers/plugin-search-provider.ts b/src/modules/search/providers/plugin-search-provider.tsindex d236e62a1..3defa04b5 100644--- a/src/modules/search/providers/plugin-search-provider.ts+++ b/src/modules/search/providers/plugin-search-provider.ts@@ -1,4 +1,4 @@-import { BadGatewayException, ServiceUnavailableException } from '@nestjs/common';+import { BadGatewayException, ForbiddenException, ServiceUnavailableException } from '@nestjs/common';import type { SearchProvider, SearchQuery, SearchResults, SearchHealth } from '../search.types';/**@@ -81,6 +81,11 @@ export class PluginSearchProvider implements SearchProvider {}async search(query: SearchQuery): Promise<SearchResults> {+ if (query.chatIds !== undefined) {+ if (query.chatIds.length === 0) return { hits: [], total: 0, tookMs: 0, provider: this.id };+ // Filtering an already paginated plugin response cannot enforce scoped offsets or counts.+ throw new ForbiddenException('Chat-restricted search requires the built-in search provider');+ }const reply = await this.transport.dispatchSearch({ query, timeoutMs: this.timeoutMs });if (!reply.ok) throw new ServiceUnavailableException(reply.error);// The result shape is untrusted wire data: reject an invalid payload with an honest 502 (bad@@ -96,18 +101,11 @@ export class PluginSearchProvider implements SearchProvider {tookMs: Math.round(reply.results.tookMs),hits: reply.results.hits.map(h => ({ ...h, timestamp: Math.trunc(h.timestamp) })),};- // Defense-in-depth: the plugin is expected to honor sessionIds, but re-filter host-side so a plugin- // bug or leak can never surface a hit outside the caller's allowed session scope — mirroring the- // SQL-enforced scoping the built-in provider gets for free. The guard mirrors the built-in- // provider's applyFilters condition (`sessionIds && sessionIds.length`) so the two providers never- // diverge for the same query (an empty array is a no-op on both paths). When no filtering is- // needed, return the normalized results as they are. Preserve the plugin's total when no hits were- // out of scope (the normal, well-behaved case) so pagination ("Load More" = hits.length < total)- // still works; fall back to the filtered page count only when a leak was actually stripped (the- // plugin's claimed total is then also suspect). tookMs/provider are metadata unrelated to scope.- if (!query.sessionIds || !query.sessionIds.length) return results;- const allowed = new Set(query.sessionIds);- const scoped = results.hits.filter(h => allowed.has(h.sessionId));+ // Keep the existing session defense: plugins must apply sessionIds before paging and counting.+ // Preserve total for compliant pages; discard it when an out-of-scope hit is returned.+ const sessionFilter = query.sessionIds?.length ? new Set(query.sessionIds) : null;+ if (!sessionFilter) return results;+ const scoped = results.hits.filter(h => sessionFilter.has(h.sessionId));const leaked = results.hits.length - scoped.length;return {hits: scoped,diff --git a/src/modules/search/search.controller.spec.ts b/src/modules/search/search.controller.spec.tsindex ae14b1172..ad00e4a58 100644--- a/src/modules/search/search.controller.spec.ts+++ b/src/modules/search/search.controller.spec.ts@@ -3,17 +3,25 @@ import { DECORATORS } from '@nestjs/swagger';import { SearchController } from './search.controller';import { SearchService } from './search.service';import { SearchQueryDto } from './dto/search-query.dto';+import type { ChatScopeService } from '../auth/chat-scope.service';import type { ApiKey } from '../auth/entities/api-key.entity';import type { SearchResults } from './search.types';describe('SearchController', () => {const search = jest.fn();- const ctrl = new SearchController({ search } as unknown as SearchService);+ const idsForFilter = jest.fn();+ const ctrl = new SearchController(+ { search } as unknown as SearchService,+ {+ idsForFilter,+ } as unknown as ChatScopeService,+ );const ok = { hits: [], total: 0, tookMs: 1, provider: 'builtin-fts' } satisfies SearchResults;beforeEach(() => {search.mockReset();+ idsForFilter.mockReset().mockResolvedValue(undefined);});it('throws 400 when q is empty', async () => {@@ -34,17 +42,26 @@ describe('SearchController', () => {const apiKey = { allowedSessions: ['s1', 's2'] } as unknown as ApiKey;const dto: SearchQueryDto = { q: 'hello', limit: 5 };const res = await ctrl.search(dto, apiKey);- expect(search).toHaveBeenCalledWith(dto, ['s1', 's2']);+ expect(search).toHaveBeenCalledWith(dto, ['s1', 's2'], undefined);expect(res).toBe(ok);});+ it('forwards the key expanded chat scope as callerChatIds', async () => {+ search.mockResolvedValue(ok);+ idsForFilter.mockResolvedValue(['[email protected]', '[email protected]', '111@lid']);+ const apiKey = { allowedChats: ['[email protected]'] } as unknown as ApiKey;+ await ctrl.search({ q: 'hello' }, apiKey);+ expect(idsForFilter).toHaveBeenCalledWith(apiKey);+ expect(search).toHaveBeenCalledWith({ q: 'hello' }, undefined, ['[email protected]', '[email protected]', '111@lid']);+ });+it('passes undefined (no scope) for an unrestricted key (null allowedSessions)', async () => {search.mockResolvedValue(ok);// A null/empty allowlist (e.g. ADMIN) sees all sessions — mirrors GET /webhooks behavior.const apiKey = { allowedSessions: null } as unknown as ApiKey;const dto: SearchQueryDto = { q: 'hello' };await ctrl.search(dto, apiKey);- expect(search).toHaveBeenCalledWith(dto, undefined);+ expect(search).toHaveBeenCalledWith(dto, undefined, undefined);});it('derives callerSessionIds only from the key, never from the query (anti-smuggling)', async () => {@@ -56,7 +73,7 @@ describe('SearchController', () => {const dto = { q: 'hello', sessionIds: ['sneaky'] } as unknown as SearchQueryDto;const apiKey = { allowedSessions: ['s1'] } as unknown as ApiKey;await ctrl.search(dto, apiKey);- expect(search).toHaveBeenCalledWith(dto, ['s1']);+ expect(search).toHaveBeenCalledWith(dto, ['s1'], undefined);});it('propagates 501 (NotImplementedException) from the service when no provider is active', async () => {diff --git a/src/modules/search/search.controller.ts b/src/modules/search/search.controller.tsindex 4575e71cd..8e6256fbe 100644--- a/src/modules/search/search.controller.ts+++ b/src/modules/search/search.controller.ts@@ -1,7 +1,8 @@import { Controller, Get, Query, BadRequestException } from '@nestjs/common';import { ApiTags, ApiOperation, ApiResponse, ApiQuery } from '@nestjs/swagger';import { SearchResultsResponseDto } from './dto/search-response.dto';-import { RequireRole, CurrentApiKey } from '../auth/decorators/auth.decorators';+import { ChatScoped, CurrentApiKey, RequireRole } from '../auth/decorators/auth.decorators';+import { ChatScopeService } from '../auth/chat-scope.service';import { ApiKey, ApiKeyRole } from '../auth/entities/api-key.entity';import { SearchService } from './search.service';import { SearchQueryDto } from './dto/search-query.dto';@@ -11,13 +12,18 @@ import type { SearchResults } from './search.types';@ApiTags('search')@Controller('search')export class SearchController {- constructor(private readonly searchService: SearchService) {}+ constructor(+ private readonly searchService: SearchService,+ private readonly chatScope: ChatScopeService,+ ) {}+ @ChatScoped('filtered')@Get()@RequireRole(ApiKeyRole.OPERATOR)@ApiOperation({ summary: 'Search messages across sessions (active search provider)' })@ApiResponse({ status: 200, description: 'Search results from the active provider', type: SearchResultsResponseDto })@ApiResponse({ status: 400, description: 'Empty or whitespace-only "q"' })+ @ApiResponse({ status: 403, description: 'Chat scope denied or chat-restricted search uses a plugin provider' })@ApiResponse({ status: 501, description: 'No search provider configured' })@ApiResponse({status: 502,@@ -51,10 +57,14 @@ export class SearchController {throw new BadRequestException('Query parameter "q" is required and must be non-empty.');}// callerSessionIds comes ONLY from the authenticated key's allowedSessions — never from the- // query/body — so a scoped key cannot broaden its reach. A null/empty allowlist (e.g. ADMIN)- // resolves to undefined → searches all sessions, mirroring GET /webhooks. The DTO carries no- // `sessionIds` field (the global ValidationPipe's forbidNonWhitelisted would reject it anyway),- // and SearchService makes scope authoritative by overwriting sessionIds at the provider boundary.- return this.searchService.search(dto, apiKey?.allowedSessions ?? undefined);+ // query/body — so a scoped key cannot broaden its reach; the same holds for the chat scope,+ // expanded lid-aware here and applied inside the providers BEFORE limit/offset/total. A null/empty+ // session allowlist (e.g. ADMIN) resolves to undefined → searches all sessions, mirroring GET+ // /webhooks. The DTO carries no `sessionIds` or `chatIds` field (the global ValidationPipe's+ // forbidNonWhitelisted would reject it anyway), and SearchService makes both scopes authoritative+ // by overwriting them at the provider boundary. An optional `?chatId=` is additionally fenced by+ // the guard against the key's allowlist, so a restricted key cannot name another chat either.+ const chatIds = await this.chatScope.idsForFilter(apiKey);+ return this.searchService.search(dto, apiKey?.allowedSessions ?? undefined, chatIds);}}diff --git a/src/modules/search/search.service.spec.ts b/src/modules/search/search.service.spec.tsindex fb41c315e..91285385d 100644--- a/src/modules/search/search.service.spec.ts+++ b/src/modules/search/search.service.spec.ts@@ -40,6 +40,17 @@ describe('SearchService', () => {expect(search).toHaveBeenCalledWith(expect.objectContaining({ sessionIds: ['s1'] }));});+ it('injects the caller chat scope and does not let a caller override chatIds either', async () => {+ const reg = new SearchProviderRegistry();+ const search = jest.fn().mockResolvedValue(emptyResults);+ reg.register(mkProvider('builtin-fts', search));+ const svc = new SearchService(reg);+ // The lid-expanded allowlist arrives from ChatScopeService via the controller; a smuggled+ // `chatIds` must be overwritten exactly like sessionIds.+ await svc.search({ q: 'x', chatIds: ['sneaky'] }, undefined, ['[email protected]', '111@lid']);+ expect(search).toHaveBeenCalledWith(expect.objectContaining({ chatIds: ['[email protected]', '111@lid'] }));+ });+it('clamps an excessive limit to SEARCH_LIMIT_MAX before it reaches any provider', async () => {// Without the host-side clamp a plugin provider would receive the raw caller value (9999) and// could pressure host heap by returning an oversized page. The built-in already rejected this indiff --git a/src/modules/search/search.service.ts b/src/modules/search/search.service.tsindex 7cd6487f4..e6631bf19 100644--- a/src/modules/search/search.service.ts+++ b/src/modules/search/search.service.ts@@ -7,16 +7,19 @@ import type { SearchQuery, SearchResults } from './search.types';export class SearchService {constructor(private readonly registry: SearchProviderRegistry) {}- async search(query: SearchQuery, callerSessionIds?: string[]): Promise<SearchResults> {+ async search(query: SearchQuery, callerSessionIds?: string[], callerChatIds?: string[]): Promise<SearchResults> {const provider = this.registry.active();if (!provider) throw new NotImplementedException('Search is not configured (no active search provider).');- // Auth scoping is authoritative — a caller cannot override it via the query.- // Bound pagination host-side so EVERY provider (built-in + plugin) receives capped values: the- // built-in re-clamps in its own SQL, but a plugin would otherwise receive the raw caller value- // and could pressure host heap by returning an oversized page.+ // Auth scoping is authoritative — a caller cannot override it via the query. This covers both+ // fences: sessions (allowedSessions) and chats (allowedChats, expanded lid-aware by the caller),+ // each undefined for an unrestricted key. Bound pagination host-side so EVERY provider+ // (built-in + plugin) receives capped values: the built-in re-clamps in its own SQL, but a+ // plugin would otherwise receive the raw caller value and could pressure host heap by+ // returning an oversized page.const scoped: SearchQuery = {...query,sessionIds: callerSessionIds,+ chatIds: callerChatIds,limit: Math.min(query.limit ?? SEARCH_DEFAULT_LIMIT, SEARCH_LIMIT_MAX),offset: Math.min(query.offset ?? 0, SEARCH_OFFSET_MAX),};diff --git a/src/modules/search/search.types.ts b/src/modules/search/search.types.tsindex 5389eb9c8..1a43c7b6d 100644--- a/src/modules/search/search.types.ts+++ b/src/modules/search/search.types.ts@@ -22,6 +22,8 @@ export interface SearchQuery {q: string;/** Scoped by SearchService from the caller's API-key allowedSessions (not user-supplied). */sessionIds?: string[];+ /** Host-set, lid-expanded chat scope: undefined is unrestricted, [] denies every chat. */+ chatIds?: string[];sessionId?: string;chatId?: string;direction?: MessageDirection;diff --git a/test/chat-scope.e2e-spec.ts b/test/chat-scope.e2e-spec.tsindex 42036479d..8f11d43f6 100644--- a/test/chat-scope.e2e-spec.ts+++ b/test/chat-scope.e2e-spec.ts@@ -12,6 +12,10 @@ import { applyGlobalValidation } from './../src/config/app-validation';import { AuthService } from './../src/modules/auth/auth.service';import { ApiKeyRole } from './../src/modules/auth/entities/api-key.entity';import { Session } from './../src/modules/session/entities/session.entity';+import { Message, MessageDirection } from './../src/modules/message/entities/message.entity';+import { SearchProviderRegistry } from './../src/modules/search/search-provider.registry';+import { PluginSearchProvider } from './../src/modules/search/providers/plugin-search-provider';+import type { SearchHit, SearchResults } from './../src/modules/search/search.types';/*** End-to-end proof of the chat fence through the real HTTP stack (guard + reflector metadata + DI +@@ -26,6 +30,7 @@ describe('Chat-restricted API keys (e2e)', () => {let sessionId: string;let chatKey: string; // OPERATOR, allowedChats: [ALLOWED]let openKey: string; // OPERATOR, unrestricted+ let groupKey: string;const get = (path: string, key: string) => request(app.getHttpServer()).get(path).set('X-API-Key', key);@@ -42,6 +47,23 @@ describe('Chat-restricted API keys (e2e)', () => {chatKey = (await authService.createApiKey({ name: 'e2e-chat', role: ApiKeyRole.OPERATOR, allowedChats: [ALLOWED] })).rawKey;openKey = (await authService.createApiKey({ name: 'e2e-open', role: ApiKeyRole.OPERATOR })).rawKey;+ groupKey = (+ await authService.createApiKey({ name: 'e2e-group', role: ApiKeyRole.OPERATOR, allowedChats: ['[email protected]'] })+ ).rawKey;+ app.get(SearchProviderRegistry).setActive('builtin-fts');+ const messageRepo: Repository<Message> = app.get(getRepositoryToken(Message, 'data'));+ await messageRepo.insert(+ [ALLOWED, OTHER, ALLOWED].map((chatId, index) => ({+ sessionId,+ chatId,+ from: chatId,+ to: '[email protected]',+ body: 'scopingprobe',+ type: 'text' as const,+ direction: MessageDirection.INCOMING,+ timestamp: index + 1,+ })),+ );});afterAll(async () => {@@ -87,4 +109,59 @@ describe('Chat-restricted API keys (e2e)', () => {it.each(['chats', 'groups', 'contacts', 'labels/1/chats'])('admits the filtered list route %s', async route => {expect((await get(`/api/sessions/${sessionId}/${route}`, chatKey)).status).not.toBe(403);});++ it('admits search for a restricted key and fences its optional ?chatId=', async () => {+ const outside = await get(`/api/search?q=hi&chatId=${OTHER}`, chatKey).expect(403);+ expect((outside.body as { message: string }).message).toBe('API key not authorized for this chat');+ const path = `/api/search?q=scopingprobe&sessionId=${sessionId}`;+ const pages: SearchHit[] = [];+ for (const offset of [0, 1, 2]) {+ const page = await get(`${path}&limit=1&offset=${offset}`, chatKey).expect(200);+ const body = page.body as SearchResults;+ expect(body.total).toBe(2);+ pages.push(...body.hits);+ }+ expect(pages.map(hit => hit.chatId)).toEqual([ALLOWED, ALLOWED]);+ expect(new Set(pages.map(hit => hit.messageId)).size).toBe(2);+ expect(((await get(path, openKey).expect(200)).body as SearchResults).total).toBe(3);+ });++ it('refuses plugin search for a chat-restricted key before invoking the worker', async () => {+ const registry = app.get(SearchProviderRegistry);+ const dispatchSearch = jest+ .fn()+ .mockResolvedValue({ ok: true, results: { hits: [], total: 731, tookMs: 1, provider: 'plugin:e2e' } });+ registry.register(new PluginSearchProvider('e2e', 'E2E', { dispatchSearch, healthCheck: jest.fn() }, 1000));+ registry.setActive('plugin:e2e');+ try {+ const refused = await get('/api/search?q=scopingprobe', chatKey).expect(403);+ expect((refused.body as { message: string }).message).toBe(+ 'Chat-restricted search requires the built-in search provider',+ );+ expect(dispatchSearch).not.toHaveBeenCalled();+ expect(((await get('/api/search?q=scopingprobe', openKey).expect(200)).body as SearchResults).total).toBe(731);+ expect(dispatchSearch).toHaveBeenCalledTimes(1);+ } finally {+ registry.unregister('plugin:e2e');+ registry.setActive('builtin-fts');+ }+ });++ it('admits group detail and settings for the allowed group, refuses any other', async () => {+ const detail = await get(`/api/sessions/${sessionId}/groups/[email protected]`, groupKey).expect(403);+ expect((detail.body as { message: string }).message).toBe('API key not authorized for this chat');+ await get(`/api/sessions/${sessionId}/groups/[email protected]/settings`, groupKey).expect(403);+ expect((await get(`/api/sessions/${sessionId}/groups/[email protected]`, groupKey)).status).not.toBe(403);+ expect((await get(`/api/sessions/${sessionId}/groups/[email protected]/settings`, groupKey)).status).not.toBe(403);+ await request(app.getHttpServer())+ .put(`/api/sessions/${sessionId}/groups/[email protected]/settings`)+ .set('X-API-Key', groupKey)+ .send({ announce: true })+ .expect(403);+ const allowed = await request(app.getHttpServer())+ .put(`/api/sessions/${sessionId}/groups/[email protected]/settings`)+ .set('X-API-Key', groupKey)+ .send({ announce: true });+ expect(allowed.status).not.toBe(403);+ });});