Searches the Mongo archive (*_chat_archive.messages) populated by the ejabberd mod_track_message hook. This is a parallel store to the live MAM history — denormalized, indexed for $text + substring queries, and isolated from the live XMPP DB so search load never touches the chat runtime.

Two query modes:

• substring (default): case-insensitive regex on body. Finds short queries like "h" inside "hello" — good for autocomplete-style flows. Special regex characters are escaped, so a query like "." matches a literal dot, not "any char".
• fulltext: Mongo $text operator. Token-based; won't match substrings of a word, but very fast and supports sort=relevance with a score field on each item.

Visibility:

• B2B server token: full access to every message in the target app.
• User token: restricted to chats the caller can see. Groupchat membership is resolved via user_to_chats; private 1-1 access is derived from the canonical chatId (the caller's xmppUsername must be one of the two participants).

When the caller passes an explicit chatId they have no access to, the response is 403 CHAT_FORBIDDEN (not an empty list) so the client can distinguish "denied" from "no matches".

Note: the archive only stores messages whose chat / users are registered in the Ethora API. Ad-hoc XMPP rooms and synthetic test fixtures don't pollute the searchable set.

{
  items: [
    {
      _id, appId, chatId, chatType, room,
      from, fromUserId, to, toUserId,
      body, messageId, stanzaId, createdAt,
      score?    // only when mode=fulltext AND sort=relevance
    }
  ],
  total: number,
  limit, offset, q, mode
}