Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

16.0 KB
Raw Blame
// Enable the MCP server before AppModule is imported.
process.env.MCP_ENABLED = 'true';

import { Test, TestingModule } from '@nestjs/testing';
import { type INestApplication } from '@nestjs/common';
import request from 'supertest';
import type { App } from 'supertest/types';
import { AppModule } from '../src/app.module';
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 { SessionService } from '../src/modules/session/session.service';
import { MessageService } from '../src/modules/message/message.service';

// --- MCP protocol helpers ---

const MCP_HEADERS = {
  'Content-Type': 'application/json',
  Accept: 'application/json, text/event-stream',
};

function jsonRpcRequest(method: string, params: Record<string, unknown> = {}, id = 1) {
  return { jsonrpc: '2.0', method, params, id };
}

/**
 * Parse the MCP response. The StreamableHTTP transport sends:
 *   - `text/event-stream` SSE for normal requests (tools/list, tools/call)
 *   - `application/json` directly for some responses
 *
 * Supertest parses `application/json` into `.body`. For SSE, `.body` is empty
 * and the actual content is in `.text` (raw string). We try both.
 */
function parseMcpResponse(res: { body: unknown; text: string }): Record<string, unknown> {
  // If supertest parsed JSON, body will be a non-empty object
  if (typeof res.body === 'object' && res.body !== null && Object.keys(res.body).length > 0) {
    return res.body as Record<string, unknown>;
  }
  // SSE format: "event: message\ndata: {...}\n\n" — extract the data line
  const text = res.text ?? '';
  const match = /^data:\s*(.+)$/m.exec(text);
  if (match) {
    return JSON.parse(match[1]) as Record<string, unknown>;
  }
  // Plain JSON text fallback
  if (text.trim().startsWith('{')) {
    return JSON.parse(text) as Record<string, unknown>;
  }
  return {};
}

// --- Test suite ---

describe('MCP server (e2e)', () => {
  let app: INestApplication<App>;
  let viewerKey: string;
  let chatKey: string;
  let ipKey: string;
  const scopedSession = '11111111-1111-4111-8111-111111111111';
  const initialize = () =>
    jsonRpcRequest('initialize', {
      protocolVersion: '2025-11-25',
      capabilities: {},
      clientInfo: { name: 'test-client', version: '0.0.1' },
    });

  beforeAll(async () => {
    const moduleFixture: TestingModule = await Test.createTestingModule({
      imports: [AppModule],
    }).compile();

    app = moduleFixture.createNestApplication();
    applyGlobalValidation(app);
    await app.init();

    const authService = app.get(AuthService);
    viewerKey = (await authService.createApiKey({ name: 'e2e-mcp-viewer', role: ApiKeyRole.VIEWER })).rawKey;
    chatKey = (
      await authService.createApiKey({
        name: 'e2e-mcp-chat',
        role: ApiKeyRole.VIEWER,
        allowedSessions: [scopedSession],
        allowedChats: ['[email protected]'],
      })
    ).rawKey;
    ipKey = (await authService.createApiKey({ name: 'e2e-mcp-ip', role: ApiKeyRole.VIEWER, allowedIps: ['127.0.0.1'] }))
      .rawKey;
  }, 30_000);

  afterAll(async () => {
    try {
      await app?.close();
    } catch {
      /* ignore TypeORM multi-datasource teardown quirk */
    }
  });

  // ---------------------------------------------------------------------------
  // 1. MCP endpoint is reachable with a key: initialize succeeds
  // ---------------------------------------------------------------------------
  it('POST /mcp with initialize request responds with 200', async () => {
    const res = await request(app.getHttpServer())
      .post('/mcp')
      .set(MCP_HEADERS)
      .set('X-API-Key', viewerKey)
      .send(initialize());

    expect([200, 202]).toContain(res.status);
  });

  // ---------------------------------------------------------------------------
  // 2. tools/list returns the tool catalogue with known names
  // ---------------------------------------------------------------------------
  it('tools/list returns the tool catalogue', async () => {
    const res = await request(app.getHttpServer())
      .post('/mcp')
      .set(MCP_HEADERS)
      .set('Authorization', `Bearer ${viewerKey}`)
      .send(jsonRpcRequest('tools/list'));

    expect(res.status).toBe(200);
    const body = parseMcpResponse(res);
    const result = body.result as Record<string, unknown> | undefined;
    expect(result).toBeDefined();
    const tools = result?.tools as Array<{ name: string }> | undefined;
    expect(Array.isArray(tools)).toBe(true);
    expect(tools!.length).toBeGreaterThan(0);
    // Verify well-known tools are present
    const names = tools!.map(t => t.name);
    expect(names).toContain('SessionFindAll');
  });

  // ---------------------------------------------------------------------------
  // 3. Every request needs a valid key: nothing is answered before it
  // ---------------------------------------------------------------------------
  it('initialize without a key answers 401 and discloses no server info', async () => {
    const res = await request(app.getHttpServer()).post('/mcp').set(MCP_HEADERS).send(initialize());

    expect(res.status).toBe(401);
    expect(res.headers['www-authenticate']).toBe('Bearer');
    expect(res.body).toEqual({ jsonrpc: '2.0', error: { code: -32000, message: 'Missing API key' }, id: null });
    expect(res.text).not.toContain('serverInfo');
  });

  it('tools/list with an unknown key answers 401 and lists no tools', async () => {
    const res = await request(app.getHttpServer())
      .post('/mcp')
      .set(MCP_HEADERS)
      .set('X-API-Key', 'owa_k1_not-a-real-key')
      .send(jsonRpcRequest('tools/list'));

    expect(res.status).toBe(401);
    expect(res.text).not.toContain('SessionFindAll');
  });

  it('tools/call without a key answers 401', async () => {
    const res = await request(app.getHttpServer())
      .post('/mcp')
      .set(MCP_HEADERS)
      .send(jsonRpcRequest('tools/call', { name: 'SessionFindAll', arguments: {} }));

    expect(res.status).toBe(401);
  });

  it('refuses a key with an IP allow-list at the gate, as every MCP tool call does', async () => {
    const res = await request(app.getHttpServer())
      .post('/mcp')
      .set(MCP_HEADERS)
      .set('X-API-Key', ipKey)
      .send(jsonRpcRequest('tools/list'));

    expect(res.status).toBe(403);
    expect(res.headers['www-authenticate']).toBeUndefined();
  });

  // Role, session and chat scope stay per tool call, answered in-band once the key passes the gate.
  it('a chat-restricted key passes the gate and is refused in-band by the tool call', async () => {
    const res = await request(app.getHttpServer())
      .post('/mcp')
      .set(MCP_HEADERS)
      .set('X-API-Key', chatKey)
      .send(jsonRpcRequest('tools/call', { name: 'SessionFindAll', arguments: {} }));

    expect(res.status).toBe(200);
    const result = parseMcpResponse(res).result as Record<string, unknown> | undefined;
    expect(result?.isError).toBe(true);
    const content = result?.content as Array<{ type: string; text?: string }> | undefined;
    expect(content?.find(c => c.type === 'text')?.text ?? '').toMatch(/restricted to selected chats/i);
  });

  it('a chat-restricted key receives only allowed chats before pagination', async () => {
    const list = jest
      .spyOn(app.get(SessionService), 'listChats')
      .mockResolvedValue([{ id: '[email protected]' }, { id: '[email protected]' }] as Awaited<
        ReturnType<SessionService['listChats']>
      >);
    try {
      const res = await request(app.getHttpServer())
        .post('/mcp')
        .set(MCP_HEADERS)
        .set('X-API-Key', chatKey)
        .send(
          jsonRpcRequest('tools/call', { name: 'SessionGetChats', arguments: { sessionId: scopedSession, limit: 1 } }),
        );
      expect(res.status).toBe(200);
      const result = parseMcpResponse(res).result as { isError?: boolean; content: Array<{ text: string }> };
      expect(result.isError).not.toBe(true);
      expect(JSON.parse(result.content[0].text)).toEqual([{ id: '[email protected]' }]);
      expect(list).toHaveBeenCalledWith(scopedSession, undefined);
    } finally {
      list.mockRestore();
    }
  });

  it('a chat-restricted key cannot read history from another chat', async () => {
    const res = await request(app.getHttpServer())
      .post('/mcp')
      .set(MCP_HEADERS)
      .set('X-API-Key', chatKey)
      .send(
        jsonRpcRequest('tools/call', {
          name: 'MessageHistory',
          arguments: { sessionId: scopedSession, chatId: '[email protected]' },
        }),
      );
    expect(res.status).toBe(200);
    const result = parseMcpResponse(res).result as { isError?: boolean; content: Array<{ text: string }> };
    expect(result.isError).toBe(true);
    expect(result.content[0].text).toContain('API key not authorized for this chat');
  });

  it('chat filtering retains the session fence', async () => {
    const list = jest.spyOn(app.get(SessionService), 'listChats');
    try {
      const res = await request(app.getHttpServer())
        .post('/mcp')
        .set(MCP_HEADERS)
        .set('X-API-Key', chatKey)
        .send(
          jsonRpcRequest('tools/call', {
            name: 'SessionGetChats',
            arguments: { sessionId: '22222222-2222-4222-8222-222222222222' },
          }),
        );
      expect(res.status).toBe(200);
      const result = parseMcpResponse(res).result as { isError?: boolean };
      expect(result.isError).toBe(true);
      expect(list).not.toHaveBeenCalled();
    } finally {
      list.mockRestore();
    }
  });

  // ---------------------------------------------------------------------------
  // 4. Unsupported Content-Type → 415
  // ---------------------------------------------------------------------------
  it('POST /mcp with wrong Content-Type returns 415', async () => {
    const res = await request(app.getHttpServer())
      .post('/mcp')
      .set({ 'Content-Type': 'text/plain', Accept: 'application/json, text/event-stream' })
      .set('X-API-Key', viewerKey)
      .send('{}');

    expect(res.status).toBe(415);
  });

  // ---------------------------------------------------------------------------
  // 4b. GET / DELETE: the stateless transport offers no SSE stream and no session,
  //     so both answer 405 (an SDK client treats anything else as an error)
  // ---------------------------------------------------------------------------
  it('GET and DELETE /mcp answer 405 with Allow: POST', async () => {
    const server = app.getHttpServer();
    const get = await request(server).get('/mcp').set('Accept', 'text/event-stream');
    expect(get.status).toBe(405);
    expect(get.headers['allow']).toBe('POST');
    expect(get.body).toEqual({ jsonrpc: '2.0', error: { code: -32000, message: 'Method not allowed.' }, id: null });

    const del = await request(server).delete('/mcp');
    expect(del.status).toBe(405);
    expect(del.headers['allow']).toBe('POST');
  });

  it('a session-restricted key cannot invoke a tool for another session', async () => {
    const { rawKey } = await app.get(AuthService).createApiKey({
      name: 'e2e-mcp-session',
      role: ApiKeyRole.VIEWER,
      allowedSessions: [scopedSession],
    });
    const chats = jest.spyOn(app.get(SessionService), 'getChats').mockResolvedValue([]);
    const call = (sessionId: string) =>
      request(app.getHttpServer())
        .post('/mcp')
        .set(MCP_HEADERS)
        .set('X-API-Key', rawKey)
        .send(jsonRpcRequest('tools/call', { name: 'SessionGetChats', arguments: { sessionId } }));
    try {
      const allowed = await call(scopedSession);
      expect(allowed.status).toBe(200);
      expect((parseMcpResponse(allowed).result as { isError?: boolean }).isError).not.toBe(true);
      expect(chats).toHaveBeenCalledWith(scopedSession, { limit: undefined, offset: undefined });
      chats.mockClear();

      const denied = await call('22222222-2222-4222-8222-222222222222');
      expect(denied.status).toBe(200);
      const result = parseMcpResponse(denied).result as { isError: boolean; content: Array<{ text: string }> };
      expect(result.isError).toBe(true);
      expect(JSON.parse(result.content[0].text)).toMatchObject({ message: 'API key not authorized for this session' });
      expect(chats).not.toHaveBeenCalled();
    } finally {
      chats.mockRestore();
    }
  });
});

describe('MCP read-only mode and tool rate limits (e2e)', () => {
  let app: INestApplication<App>;
  const savedEnv = {
    MCP_READONLY: process.env.MCP_READONLY,
    MCP_RATE_LIMIT_MAX: process.env.MCP_RATE_LIMIT_MAX,
  };

  beforeAll(async () => {
    process.env.MCP_READONLY = 'true';
    process.env.MCP_RATE_LIMIT_MAX = '2';
    const moduleFixture = await Test.createTestingModule({ imports: [AppModule] }).compile();
    app = moduleFixture.createNestApplication();
    applyGlobalValidation(app);
    await app.init();
  }, 30_000);

  afterAll(async () => {
    try {
      await app?.close();
    } finally {
      for (const [key, value] of Object.entries(savedEnv)) {
        if (value === undefined) delete process.env[key];
        else process.env[key] = value;
      }
    }
  });

  it('hides write tools and refuses a direct write call even with an admin key', async () => {
    const { rawKey } = await app.get(AuthService).createApiKey({ name: 'e2e-mcp-readonly', role: ApiKeyRole.ADMIN });
    const send = jest.spyOn(app.get(MessageService), 'sendText');
    try {
      const listed = await request(app.getHttpServer())
        .post('/mcp')
        .set(MCP_HEADERS)
        .set('X-API-Key', rawKey)
        .send(jsonRpcRequest('tools/list'));
      expect(listed.status).toBe(200);
      const tools = (parseMcpResponse(listed).result as { tools: Array<{ name: string }> }).tools;
      expect(tools.map(tool => tool.name)).toContain('SessionFindAll');
      expect(tools.map(tool => tool.name)).not.toContain('MessageSendText');

      const called = await request(app.getHttpServer())
        .post('/mcp')
        .set(MCP_HEADERS)
        .set('X-API-Key', rawKey)
        .send(
          jsonRpcRequest('tools/call', {
            name: 'MessageSendText',
            arguments: { sessionId: '11111111-1111-4111-8111-111111111111', chatId: '[email protected]', text: 'test' },
          }),
        );
      expect(called.status).toBe(200);
      const result = parseMcpResponse(called).result as { isError: boolean; content: Array<{ text: string }> };
      expect(result.isError).toBe(true);
      expect(result.content[0].text).toMatch(/Tool MessageSendText not found/i);
      expect(send).not.toHaveBeenCalled();
    } finally {
      send.mockRestore();
    }
  });

  it('returns an in-band rate-limit error before the handler and keeps another key usable', async () => {
    const auth = app.get(AuthService);
    const first = await auth.createApiKey({ name: 'e2e-mcp-rate-first', role: ApiKeyRole.VIEWER });
    const second = await auth.createApiKey({ name: 'e2e-mcp-rate-second', role: ApiKeyRole.VIEWER });
    const stats = jest.spyOn(app.get(SessionService), 'getStats');
    const call = (key: string) =>
      request(app.getHttpServer())
        .post('/mcp')
        .set(MCP_HEADERS)
        .set('X-API-Key', key)
        .send(jsonRpcRequest('tools/call', { name: 'SessionGetStats', arguments: {} }));
    try {
      for (let i = 0; i < 2; i++) {
        const response = await call(first.rawKey);
        expect(response.status).toBe(200);
        expect((parseMcpResponse(response).result as { isError?: boolean }).isError).not.toBe(true);
      }
      expect(stats).toHaveBeenCalledTimes(2);

      const limited = await call(first.rawKey);
      expect(limited.status).toBe(200);
      const result = parseMcpResponse(limited).result as { isError: boolean; content: Array<{ text: string }> };
      expect(result.isError).toBe(true);
      expect(JSON.parse(result.content[0].text)).toMatchObject({ message: 'MCP rate limit exceeded' });
      expect(stats).toHaveBeenCalledTimes(2);

      const independent = await call(second.rawKey);
      expect(independent.status).toBe(200);
      expect((parseMcpResponse(independent).result as { isError?: boolean }).isError).not.toBe(true);
      expect(stats).toHaveBeenCalledTimes(3);
    } finally {
      stats.mockRestore();
    }
  });
});