Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

6.3 KB
Raw Blame
import { BadGatewayException, ForbiddenException, ServiceUnavailableException } from '@nestjs/common';
import type { SearchProvider, SearchQuery, SearchResults, SearchHealth } from '../search.types';

/**
 * The host-side transport a PluginSearchProvider uses to reach its worker: dispatch a search query and
 * run the plugin's general healthCheck. Satisfied structurally by PluginWorkerHost, so the search module
 * has no static dependency on the plugin sandbox — the loader (which knows both) passes the host in.
 */
export interface PluginSearchTransport {
  dispatchSearch(options: {
    query: SearchQuery;
    timeoutMs: number;
  }): Promise<{ ok: true; results: SearchResults } | { ok: false; error: string }>;
  healthCheck(timeoutMs: number): Promise<{ healthy: boolean; message?: string }>;
}

/** Required string fields of a SearchHit (score stays optional), mirrored for runtime checks. */
const SEARCH_HIT_STRING_FIELDS = [
  'messageId',
  'waMessageId',
  'sessionId',
  'chatId',
  'body',
  'snippet',
  'type',
  'direction',
  'from',
] as const;

/**
 * Validate a SearchResults payload that crossed the worker IPC boundary, returning a description of the
 * first violation or null when the shape is sound. The worker is not a security boundary and the wire
 * payload is untrusted: a plugin bug (or hostile worker) can post anything as `results` — a fabricated
 * `total`, a non-array `hits` (which would 500 the re-filter below), or hits missing the fields the
 * dashboard renders. Rules mirror the declared SearchResults contract; extra fields are tolerated so an
 * additive legit provider is never broken.
 */
export function validatePluginSearchResults(results: unknown): string | null {
  if (!results || typeof results !== 'object' || Array.isArray(results)) return 'results must be an object';
  const r = results as Record<string, unknown>;
  if (!Array.isArray(r.hits)) return 'results.hits must be an array';
  if (typeof r.total !== 'number' || !Number.isFinite(r.total) || r.total < 0) {
    return 'results.total must be a finite number >= 0';
  }
  if (typeof r.tookMs !== 'number' || !Number.isFinite(r.tookMs) || r.tookMs < 0) {
    return 'results.tookMs must be a finite number >= 0';
  }
  if (typeof r.provider !== 'string' || r.provider.length === 0) return 'results.provider must be a non-empty string';
  for (const [index, hit] of (r.hits as unknown[]).entries()) {
    if (!hit || typeof hit !== 'object' || Array.isArray(hit)) return `results.hits[${index}] must be an object`;
    const h = hit as Record<string, unknown>;
    for (const field of SEARCH_HIT_STRING_FIELDS) {
      if (typeof h[field] !== 'string') return `results.hits[${index}].${field} must be a string`;
    }
    if (typeof h.timestamp !== 'number' || !Number.isFinite(h.timestamp)) {
      return `results.hits[${index}].timestamp must be a finite number`;
    }
    if (h.score !== undefined && (typeof h.score !== 'number' || !Number.isFinite(h.score))) {
      return `results.hits[${index}].score must be a finite number when present`;
    }
  }
  return null;
}

/**
 * A SearchProvider backed by a sandboxed plugin's worker. The host routes a query to the worker via the
 * search RPC (dispatchSearch); the plugin runs its own backend logic (Meilisearch, Elasticsearch, etc.)
 * and returns SearchResults. health() reuses the worker's general healthCheck (healthy→ok, message→detail)
 * — no search-specific health message (Part 1 decision). All vendor-specific logic lives in the plugin.
 */
export class PluginSearchProvider implements SearchProvider {
  readonly id: string;

  constructor(
    pluginId: string,
    readonly label: string,
    private readonly transport: PluginSearchTransport,
    private readonly timeoutMs: number,
  ) {
    this.id = `plugin:${pluginId}`;
  }

  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');
    }
    // The expanded id lists are the built-in provider's business; a plugin keeps the query shape it was
    // written against (`chatId` and `from` as the caller sent them).
    const pluginQuery: SearchQuery = { ...query };
    delete pluginQuery.chatIdAliases;
    delete pluginQuery.fromAliases;
    const reply = await this.transport.dispatchSearch({ query: pluginQuery, 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
    // upstream) instead of fabricating a 200 — or crashing the re-filter below into a 500.
    const invalid = validatePluginSearchResults(reply.results);
    if (invalid) throw new BadGatewayException(`Search provider ${this.id} returned invalid results: ${invalid}`);
    // The Go and Java SDKs decode tookMs, total and a hit's timestamp into integer fields, as the
    // built-in provider only ever returns whole numbers there, so one fractional value from a plugin
    // would fail the whole call client-side. The validator accepts any finite number: round here.
    const results: SearchResults = {
      ...reply.results,
      total: Math.trunc(reply.results.total),
      tookMs: Math.round(reply.results.tookMs),
      hits: reply.results.hits.map(h => ({ ...h, timestamp: Math.trunc(h.timestamp) })),
    };
    // 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,
      total: leaked > 0 ? scoped.length : results.total,
      tookMs: results.tookMs,
      provider: results.provider,
    };
  }

  async health(): Promise<SearchHealth> {
    const result = await this.transport.healthCheck(this.timeoutMs);
    return { ok: result.healthy, detail: result.message };
  }
}