Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

6.0 KB
Raw Blame
import { BadRequestException, ForbiddenException, UnauthorizedException } from '@nestjs/common';
import { ZodError } from 'zod';
import { containsNul } from '../../common/validation/no-nul-character';
import type { AuthService } from '../../modules/auth/auth.service';
import type { ChatScopeService } from '../../modules/auth/chat-scope.service';
import type { AnyToolDescriptor } from './tool-descriptor';

/**
 * Run one tool call with REST-equivalent guarantees, reusing core's own auth:
 * auth (role + allowedSessions + IP fail-closed) → chat gate (a chat-restricted key may run only a
 * tool that carries a `chatScope` mark) → validate input → NUL check → chat arguments and
 * `quotedMessageId` → handler.
 * Mirrors the REST guard-then-pipe order (auth before validation). The chat arguments are checked
 * on the parsed values, so schema normalization cannot change the authorized target.
 * `clientIp` is undefined over MCP — a key with allowedIps therefore fails closed
 * inside validateApiKey (documented limitation).
 *
 * @param onAuthenticated Optional callback invoked with `apiKey.id` immediately
 * after `validateApiKey` succeeds and BEFORE role/input checks. Use this to
 * key rate-limiters off the authenticated identity rather than the raw header
 * string, preventing pre-auth bucket allocation by anonymous callers.
 * @param onAuthFailure Optional callback invoked with the error when the AUTH
 * phase rejects (missing/invalid/revoked/expired key, wrong role, IP/session not
 * allowed, a tool the chat-restricted key may not run, or a chat argument outside
 * its allowlist). Schema validation errors and handler errors do not reach this
 * callback. Re-thrown after it.
 * @param signal Optional cancellation signal (the MCP client went away or cancelled the request), handed
 * to the handler so a long call can stop.
 */
export async function invokeTool(
  tool: AnyToolDescriptor,
  rawInput: unknown,
  rawKey: string | undefined,
  authService: AuthService,
  onAuthenticated?: (apiKeyId: string) => void,
  onAuthFailure?: (error: unknown) => void,
  chatScope?: ChatScopeService,
  signal?: AbortSignal,
): Promise<unknown> {
  // AUTH PHASE — every rejection here is an authentication/authorization failure (the MCP analog of the
  // REST ApiKeyGuard's authorize()). Wrapped so onAuthFailure can record the audit trail at the boundary.
  let apiKey: Awaited<ReturnType<typeof authService.validateApiKey>>;
  try {
    if (!rawKey) {
      throw new UnauthorizedException('Missing API key');
    }
    // Pre-extract sessionId for the scope check BEFORE full validation (REST reads
    // req.params.sessionId in the guard, before the pipe).
    const probe = (rawInput ?? {}) as Record<string, unknown>;
    const sessionId = tool.sessionScoped && typeof probe.sessionId === 'string' ? probe.sessionId : undefined;

    // Fail closed: a sessionScoped tool MUST carry a non-empty sessionId before auth. Otherwise an
    // undefined scope would skip the per-key allowedSessions check inside validateApiKey, letting a
    // session-restricted key drive the tool against any session. This enforces the fence at the runtime
    // boundary regardless of an individual tool's input schema.
    if (tool.sessionScoped && !sessionId) {
      throw new BadRequestException('sessionId is required for this tool');
    }

    apiKey = await authService.validateApiKey(rawKey, undefined, sessionId);
    onAuthenticated?.(apiKey.id);

    if (tool.requiredRole && !authService.hasPermission(apiKey, tool.requiredRole)) {
      throw new ForbiddenException('API key lacks the required role');
    }

    // Restricted keys may reach only explicitly fenced, filtered or chat-independent tools.
    if ((apiKey.allowedChats?.length ?? 0) > 0 && (!tool.chatScope || !chatScope)) {
      throw new ForbiddenException('API key is restricted to selected chats');
    }
  } catch (error) {
    // auditMcpAuthFailure (the only current caller hook) filters to 401/403, so the BadRequestException
    // for a missing sessionId above is NOT audited (parity with the REST guard, which skips 400s).
    onAuthFailure?.(error);
    throw error;
  }

  // Validate before checking chat arguments; validation errors are not auth failures.
  let input: unknown;
  try {
    input = tool.inputSchema.parse(rawInput);
  } catch (e) {
    if (e instanceof ZodError) {
      throw new BadRequestException(e.issues.map(i => `${i.path.join('.') || '(root)'}: ${i.message}`));
    }
    throw e;
  }
  // PostgreSQL rejects U+0000 in every text parameter; REST refuses the same input in NulBodyPipe.
  if (containsNul(input)) throw new BadRequestException('Tool input must not contain a NUL character');
  if (chatScope?.isRestricted(apiKey)) {
    try {
      // Inspect the parsed values, so schema normalization cannot change the authorized target.
      const values = input !== null && typeof input === 'object' ? (input as Record<string, unknown>) : {};
      if (typeof tool.chatScope !== 'string') {
        const fields = tool.chatScope ?? [];
        if (fields.length === 0) throw new ForbiddenException('API key is restricted to selected chats');
        for (const field of fields) {
          const chatId = values[field];
          if (typeof chatId !== 'string' || !chatId.trim()) {
            throw new ForbiddenException(`${field} is required for a key restricted to selected chats`);
          }
          if (!(await chatScope.allows(apiKey, chatId))) {
            throw new ForbiddenException('API key not authorized for this chat');
          }
        }
      }
      const quote = values.quotedMessageId;
      if (!tool.chatQuotedAllowed && quote !== undefined && quote !== null && quote !== '') {
        throw new ForbiddenException('API key is restricted to selected chats');
      }
    } catch (error) {
      onAuthFailure?.(error);
      throw error;
    }
  }
  // The single cast the erasure needs, placed next to the parse that justifies it: `input` is
  // whatever this tool's own `inputSchema` just accepted, which is exactly what its handler declares.
  return tool.handler(input as never, apiKey, chatScope, signal);
}