Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import { BadRequestException, ForbiddenException, UnauthorizedException } from '@nestjs/common';
import { UnresolvedApiKeyException } from '../auth/auth.service';
import type { Request, Response } from 'express';
import { z } from 'zod';
import {
auditMcpAuthFailure,
createIpThrottle,
createKeyGate,
mountMcpServer,
resolveMcpReadOnly,
type MountMcpServerOptions,
} from './mcp.server';
import { KeyRateLimiter } from './mcp-rate-limit';
import { AuditAction } from '../audit/entities/audit-log.entity';
import type { AnyToolDescriptor } from '../../core/agent-tools/tool-descriptor';
import type { ToolRegistryService } from '../../core/agent-tools/tool-registry.service';
import type { AuthService } from '../auth/auth.service';
import type { AuditService } from '../audit/audit.service';
import { LoggerService } from '../../common/services/logger.service';
// The request-handling path news up an McpServer + StreamableHTTPServerTransport per POST. Both SDK
// classes are mocked so tests can observe the per-request transport (handleRequest args) and invoke
// the registered tool callbacks exactly as the SDK would — no sockets, no MCP protocol traffic.
// The closures dereference the mock handles lazily, so the factories stay valid before module init.
type ToolCallback = (input: Record<string, unknown>, extra: unknown) => Promise<unknown>;
const mockRegisteredTools: Array<{ name: string; callback: ToolCallback }> = [];
const mockServerConnect = jest.fn<Promise<void>, unknown[]>();
const mockServerClose = jest.fn<Promise<void>, unknown[]>();
jest.mock('@modelcontextprotocol/sdk/server/mcp.js', () => ({
McpServer: jest.fn().mockImplementation(() => ({
registerTool: (
name: string,
_config: unknown,
callback: (input: Record<string, unknown>, extra: unknown) => Promise<unknown>,
) => {
mockRegisteredTools.push({ name, callback });
},
connect: (...args: unknown[]) => mockServerConnect(...args),
close: () => mockServerClose(),
})),
}));
const mockHandleRequest = jest.fn<Promise<void>, unknown[]>();
const mockTransportClose = jest.fn<Promise<void>, unknown[]>();
jest.mock('@modelcontextprotocol/sdk/server/streamableHttp.js', () => ({
StreamableHTTPServerTransport: jest.fn().mockImplementation(() => ({
handleRequest: (...args: unknown[]) => mockHandleRequest(...args),
close: () => mockTransportClose(),
})),
}));
describe('resolveMcpReadOnly (secure-by-default MCP read-only flag)', () => {
const prev = process.env.MCP_READONLY;
afterEach(() => {
if (prev === undefined) delete process.env.MCP_READONLY;
else process.env.MCP_READONLY = prev;
});
it('defaults to read-only when MCP_READONLY is unset (write tools NOT exposed by default)', () => {
delete process.env.MCP_READONLY;
expect(resolveMcpReadOnly()).toBe(true);
});
it('exposes write tools only on an explicit MCP_READONLY=false opt-out', () => {
process.env.MCP_READONLY = 'false';
expect(resolveMcpReadOnly()).toBe(false);
});
it('stays read-only for any other value', () => {
process.env.MCP_READONLY = 'true';
expect(resolveMcpReadOnly()).toBe(true);
process.env.MCP_READONLY = 'yes';
expect(resolveMcpReadOnly()).toBe(true);
});
it('an explicit options.readOnly wins over the env', () => {
process.env.MCP_READONLY = 'false';
expect(resolveMcpReadOnly(true)).toBe(true);
delete process.env.MCP_READONLY;
expect(resolveMcpReadOnly(false)).toBe(false);
});
});
// The MCP mount is raw Express (outside the Nest guard pipeline) and the per-key limiter only fires
// after key validation, so a missing/invalid-key flood would otherwise reach a DB lookup unthrottled.
// createIpThrottle gates by resolved client IP BEFORE auth and answers with a JSON-RPC 429.
describe('createIpThrottle (pre-auth per-IP MCP throttle)', () => {
const makeReq = (ip: string, body?: unknown): Request =>
({ socket: { remoteAddress: ip }, headers: {}, body }) as unknown as Request;
type ResMock = { status: jest.Mock; json: jest.Mock; statusCode?: number; body?: unknown };
const makeRes = (): ResMock => {
const res: ResMock = { status: jest.fn(), json: jest.fn() };
res.status.mockImplementation((code: number) => {
res.statusCode = code;
return res;
});
res.json.mockImplementation((b: unknown) => {
res.body = b;
return res;
});
return res;
};
it('passes the first request from an IP and rejects the second with a 429', () => {
const throttle = createIpThrottle(new KeyRateLimiter(1, 60_000));
const next1 = jest.fn();
throttle(makeReq('1.2.3.4'), makeRes() as unknown as Response, next1);
expect(next1).toHaveBeenCalledWith(); // allowed through, no error
const next2 = jest.fn();
const res2 = makeRes();
throttle(makeReq('1.2.3.4'), res2 as unknown as Response, next2);
expect(next2).not.toHaveBeenCalled(); // short-circuited
expect(res2.status).toHaveBeenCalledWith(429);
expect((res2.body as { error?: { code?: number } }).error?.code).toBe(-32000);
});
it('buckets per IP — a different IP is not throttled', () => {
const throttle = createIpThrottle(new KeyRateLimiter(1, 60_000));
throttle(makeReq('1.1.1.1'), makeRes() as unknown as Response, jest.fn());
const next = jest.fn();
throttle(makeReq('2.2.2.2'), makeRes() as unknown as Response, next);
expect(next).toHaveBeenCalledWith();
});
it('buckets an IPv6 client on its /64, so rotating addresses inside it shares one bucket', () => {
const throttle = createIpThrottle(new KeyRateLimiter(1, 60_000));
throttle(makeReq('2001:db8:1:2::a'), makeRes() as unknown as Response, jest.fn());
const sameSubnet = jest.fn();
throttle(makeReq('2001:db8:1:2::b'), makeRes() as unknown as Response, sameSubnet);
expect(sameSubnet).not.toHaveBeenCalled();
const otherSubnet = jest.fn();
throttle(makeReq('2001:db8:1:3::a'), makeRes() as unknown as Response, otherSubnet);
expect(otherSubnet).toHaveBeenCalledWith();
});
// Every element of a JSON-RPC batch is dispatched (and each tools/call runs its own key lookup and
// auth-failure audit), so the budget is charged per message, not per HTTP request.
const call = { jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'SessionFindAll', arguments: {} } };
it('rejects a batch larger than the remaining per-IP budget', () => {
const throttle = createIpThrottle(new KeyRateLimiter(2, 60_000));
const next = jest.fn();
const res = makeRes();
throttle(makeReq('1.2.3.4', [call, call, call]), res as unknown as Response, next);
expect(next).not.toHaveBeenCalled();
expect(res.status).toHaveBeenCalledWith(429);
expect((res.body as { error?: { code?: number } }).error?.code).toBe(-32000);
});
it('charges each batch element, so the next request after a full batch is throttled', () => {
const throttle = createIpThrottle(new KeyRateLimiter(2, 60_000));
const next1 = jest.fn();
throttle(makeReq('1.2.3.4', [call, call]), makeRes() as unknown as Response, next1);
expect(next1).toHaveBeenCalledWith();
const next2 = jest.fn();
const res2 = makeRes();
throttle(makeReq('1.2.3.4', call), res2 as unknown as Response, next2);
expect(next2).not.toHaveBeenCalled();
expect(res2.status).toHaveBeenCalledWith(429);
});
it('charges an empty batch as one message', () => {
const throttle = createIpThrottle(new KeyRateLimiter(1, 60_000));
const next1 = jest.fn();
throttle(makeReq('1.2.3.4', []), makeRes() as unknown as Response, next1);
expect(next1).toHaveBeenCalledWith();
const next2 = jest.fn();
throttle(makeReq('1.2.3.4', call), makeRes() as unknown as Response, next2);
expect(next2).not.toHaveBeenCalled();
});
});
// MCP auth is raw Express (outside the Nest guard pipeline) so it bypasses the global ApiKeyGuard's
// auth-failure audit. auditMcpAuthFailure mirrors the REST guard: a WARN API_KEY_AUTH_FAILED record on
// a 401/403 only. Success and non-auth errors (bad input) must NOT be audited — parity with REST.
describe('auditMcpAuthFailure (MCP auth-failure audit trail, mirrors REST ApiKeyGuard)', () => {
const reqContext = { ipAddress: '203.0.113.7', method: 'POST', path: '/mcp' };
let auditService: { logWarn: jest.Mock };
beforeEach(() => {
auditService = { logWarn: jest.fn() };
});
it('writes a WARN API_KEY_AUTH_FAILED record on a missing/invalid key (UnauthorizedException)', () => {
auditMcpAuthFailure(auditService, new UnauthorizedException('Missing API key'), reqContext);
expect(auditService.logWarn).toHaveBeenCalledWith(AuditAction.API_KEY_AUTH_FAILED, {
ipAddress: '203.0.113.7',
method: 'POST',
path: '/mcp',
errorMessage: 'Missing API key',
});
});
it('writes a record on a wrong-role rejection (ForbiddenException)', () => {
auditMcpAuthFailure(auditService, new ForbiddenException('API key lacks the required role'), reqContext);
expect(auditService.logWarn).toHaveBeenCalledTimes(1);
const call = (auditService.logWarn.mock.calls as Array<[unknown, { errorMessage?: string }]>)[0];
expect(call[1].errorMessage).toBe('API key lacks the required role');
});
it('mirrors the REST guard exactly: IP-not-allowed (Forbidden) is audited', () => {
// validateApiKey throws Forbidden for IP-not-allowed / session-not-allowed, Unauthorized for revoked / expired.
auditMcpAuthFailure(auditService, new ForbiddenException('IP address not allowed'), reqContext);
expect(auditService.logWarn).toHaveBeenCalledWith(
AuditAction.API_KEY_AUTH_FAILED,
expect.objectContaining({ errorMessage: 'IP address not allowed' }),
);
});
it('does NOT audit a non-auth error (e.g. bad tool input — BadRequestException)', () => {
auditMcpAuthFailure(auditService, new BadRequestException('sessionId is required for this tool'), reqContext);
expect(auditService.logWarn).not.toHaveBeenCalled();
});
it('does nothing when auditService is unavailable (mount without DI)', () => {
expect(() => auditMcpAuthFailure(undefined, new UnauthorizedException('x'), reqContext)).not.toThrow();
});
});
describe('createKeyGate (every MCP request needs a valid key)', () => {
type ResMock = { status: jest.Mock; json: jest.Mock; set: jest.Mock; statusCode?: number; body?: unknown };
const makeRes = (): ResMock => {
const res: ResMock = { status: jest.fn(), json: jest.fn(), set: jest.fn() };
res.status.mockImplementation((code: number) => {
res.statusCode = code;
return res;
});
res.json.mockImplementation((b: unknown) => {
res.body = b;
return res;
});
res.set.mockReturnValue(res);
return res;
};
const run = async (
validateApiKey: jest.Mock,
headers: Record<string, string> = {},
logWarn: jest.Mock = jest.fn(),
ip = '203.0.113.7',
) => {
const gate = createKeyGate({ validateApiKey }, { logWarn });
const req = {
method: 'POST',
path: '/mcp',
headers,
socket: { remoteAddress: ip },
} as unknown as Request;
const res = makeRes();
const next = jest.fn();
await gate(req, res as unknown as Response, next);
return { res, next, logWarn };
};
it('refuses a request with no key before any lookup: 401, JSON-RPC body, audited within the IP budget', async () => {
const validateApiKey = jest.fn();
const { res, next, logWarn } = await run(validateApiKey);
expect(next).not.toHaveBeenCalled();
expect(validateApiKey).not.toHaveBeenCalled();
expect(res.statusCode).toBe(401);
expect(res.set).toHaveBeenCalledWith('WWW-Authenticate', 'Bearer');
expect(res.body).toEqual({ jsonrpc: '2.0', error: { code: -32000, message: 'Missing API key' }, id: null });
expect(logWarn).toHaveBeenCalledWith(
AuditAction.API_KEY_AUTH_FAILED,
expect.objectContaining({ ipAddress: '203.0.113.7', method: 'POST', path: '/mcp' }),
);
});
// The unauthenticated-row budget is a module-level singleton shared with the REST guard, so this
// test uses an IP no other test in this file uses.
it('writes at most 10 keyless rows a minute for one IP, and still records a revoked key after that', async () => {
const logWarn = jest.fn();
const ip = '198.51.100.91';
for (let i = 0; i < 11; i++) {
const { res, next } = await run(jest.fn(), {}, logWarn, ip);
expect(res.statusCode).toBe(401);
expect(next).not.toHaveBeenCalled();
}
expect(logWarn).toHaveBeenCalledTimes(10);
const revoked = jest.fn().mockRejectedValue(new UnauthorizedException('API key is revoked'));
const { res } = await run(revoked, { 'x-api-key': 'old-key' }, logWarn, ip);
expect(res.statusCode).toBe(401);
expect(logWarn).toHaveBeenCalledTimes(11);
expect(logWarn).toHaveBeenLastCalledWith(
AuditAction.API_KEY_AUTH_FAILED,
expect.objectContaining({ ipAddress: ip, errorMessage: 'API key is revoked' }),
);
});
it('refuses an unknown key with 401 and audits it', async () => {
const validateApiKey = jest.fn().mockRejectedValue(new UnresolvedApiKeyException('Invalid API key'));
const { res, next, logWarn } = await run(validateApiKey, { 'x-api-key': 'bad-key' });
expect(next).not.toHaveBeenCalled();
expect(validateApiKey).toHaveBeenCalledWith('bad-key', undefined, undefined, { recordUsage: false });
expect(res.statusCode).toBe(401);
expect(logWarn).toHaveBeenCalledWith(
AuditAction.API_KEY_AUTH_FAILED,
expect.objectContaining({ errorMessage: 'Invalid API key' }),
);
});
it.each([[{ 'x-api-key': 'good-key' }], [{ authorization: 'Bearer good-key' }]])(
'passes a valid key through without a client IP or session (%j)',
async headers => {
const validateApiKey = jest.fn().mockResolvedValue({ id: 'k1' });
const { res, next } = await run(validateApiKey, headers);
expect(next).toHaveBeenCalledWith();
expect(validateApiKey).toHaveBeenCalledWith('good-key', undefined, undefined, { recordUsage: false });
expect(res.status).not.toHaveBeenCalled();
},
);
it('refuses a malformed Authorization header without a lookup', async () => {
const validateApiKey = jest.fn();
const { res, next } = await run(validateApiKey, { authorization: 'Bearer good-key extra' });
expect(next).not.toHaveBeenCalled();
expect(validateApiKey).not.toHaveBeenCalled();
expect(res.statusCode).toBe(401);
});
it('answers 500, unaudited, when the key lookup itself fails', async () => {
const validateApiKey = jest.fn().mockRejectedValue(new Error('database is down'));
const { res, next, logWarn } = await run(validateApiKey, { 'x-api-key': 'good-key' });
expect(next).not.toHaveBeenCalled();
expect(res.statusCode).toBe(500);
expect(res.body).toEqual({ jsonrpc: '2.0', error: { code: -32603, message: 'Internal server error' }, id: null });
expect(logWarn).not.toHaveBeenCalled();
});
});
// mountMcpServer is raw Express: every POST passes the IP throttle and the key gate, then builds a
// fresh McpServer + transport and dispatches via transport.handleRequest(req, res, req.body). These
// tests drive the terminal handler directly with mock req/res, past the gate. Role, session and chat
// scope still run per tool call inside invokeTool (via the callback registered with the per-request
// server), so a key refused there is answered as a tool error result during the dispatch.
// mcp.module.ts is pure Nest wiring (module registration + the raw-Express mount call), stays at 0%
// coverage, and is intentionally not a target.
describe('mountMcpServer (raw-Express request-handling path)', () => {
const prevTrustedProxies = process.env.TRUSTED_PROXIES;
beforeEach(() => {
delete process.env.TRUSTED_PROXIES; // resolveClientIp then uses the socket IP, deterministically
mockRegisteredTools.length = 0;
mockServerConnect.mockReset().mockResolvedValue(undefined);
mockServerClose.mockReset().mockResolvedValue(undefined);
mockHandleRequest.mockReset().mockResolvedValue(undefined);
mockTransportClose.mockReset().mockResolvedValue(undefined);
});
afterEach(() => {
if (prevTrustedProxies === undefined) delete process.env.TRUSTED_PROXIES;
else process.env.TRUSTED_PROXIES = prevTrustedProxies;
});
interface Harness {
routeHandler: (req: Request, res: Response) => Promise<void>;
tool: AnyToolDescriptor;
authService: { validateApiKey: jest.Mock; hasPermission: jest.Mock };
auditService: { logWarn: jest.Mock };
adapter: { post: jest.Mock; get: jest.Mock; delete: jest.Mock };
registry: { list: jest.Mock };
}
const mount = (options: MountMcpServerOptions = { readOnly: false }): Harness => {
const tool = {
name: 'MessageSendText',
description: 'Send a text message (session-scoped write tool)',
inputSchema: z.object({ sessionId: z.string(), to: z.string(), text: z.string() }),
tier: 'write',
sessionScoped: true,
handler: jest.fn().mockResolvedValue({ sent: true }),
} as unknown as AnyToolDescriptor;
const registry = { list: jest.fn(() => [tool]) };
const authService = { validateApiKey: jest.fn(), hasPermission: jest.fn(() => true) };
const auditService = { logWarn: jest.fn() };
let routeHandlers: unknown[] = [];
const adapter = {
post: jest.fn((_path: string, ...handlers: unknown[]) => {
routeHandlers = handlers;
}),
get: jest.fn(),
delete: jest.fn(),
};
mountMcpServer(
adapter as unknown as Parameters<typeof mountMcpServer>[0],
registry as unknown as ToolRegistryService,
authService as unknown as AuthService,
new KeyRateLimiter(1000, 60_000),
new KeyRateLimiter(1000, 60_000),
options,
auditService as unknown as AuditService,
);
// adapter.post received [express.json(...), createIpThrottle(...), mcpHandler]; the tests drive
// the terminal handler directly with a pre-parsed body, as the file's middleware harness does.
const routeHandler = routeHandlers[routeHandlers.length - 1] as Harness['routeHandler'];
return { routeHandler, tool, authService, auditService, adapter, registry };
};
type ResMock = { on: jest.Mock; status: jest.Mock; json: jest.Mock; headersSent: boolean };
const makeRes = (): ResMock => {
const res: ResMock = { on: jest.fn(), status: jest.fn(), json: jest.fn(), headersSent: false };
res.status.mockReturnValue(res);
res.json.mockReturnValue(res);
return res;
};
const post = async (
h: Harness,
body: unknown,
headers: Record<string, string> = {},
): Promise<{ req: Request; res: ResMock }> => {
const req = {
method: 'POST',
path: '/mcp',
headers,
body,
socket: { remoteAddress: '203.0.113.7' },
} as unknown as Request;
const res = makeRes();
await h.routeHandler(req, res as unknown as Response);
return { req, res };
};
// The single registered tool callback, captured when the driven POST built its per-request server.
const toolCallback = (): ToolCallback => {
expect(mockRegisteredTools).toHaveLength(1);
return mockRegisteredTools[0].callback;
};
it('answers GET and DELETE with a JSON-RPC 405 carrying Allow: POST (stateless, no SSE stream)', () => {
const h = mount();
for (const verb of ['get', 'delete'] as const) {
expect(h.adapter[verb]).toHaveBeenCalledWith('/mcp', expect.any(Function));
const refuse = (h.adapter[verb].mock.calls[0] as unknown[])[1] as (req: Request, res: Response) => void;
const res = { status: jest.fn(), set: jest.fn(), json: jest.fn() };
res.status.mockReturnValue(res);
res.set.mockReturnValue(res);
refuse({} as Request, res as unknown as Response);
expect(res.status).toHaveBeenCalledWith(405);
expect(res.set).toHaveBeenCalledWith('Allow', 'POST');
expect(res.json).toHaveBeenCalledWith({
jsonrpc: '2.0',
error: { code: -32000, message: 'Method not allowed.' },
id: null,
});
}
});
it('parses the body before the per-IP throttle, and checks the key after the throttle', () => {
const h = mount();
const [path, parser, ...rest] = h.adapter.post.mock.calls[0] as unknown[];
expect(path).toBe('/mcp');
expect((parser as { name?: string }).name).toBe('jsonParser');
expect(rest).toHaveLength(3); // throttle, key gate, handler
});
it('refuses a keyless POST at the gate before any MCP server is built', async () => {
const h = mount();
const gate = (h.adapter.post.mock.calls[0] as unknown[])[3] as (
req: Request,
res: Response,
next: () => void,
) => Promise<void>;
const res = { status: jest.fn(), json: jest.fn(), set: jest.fn() };
res.status.mockReturnValue(res);
res.set.mockReturnValue(res);
const next = jest.fn();
const body = { jsonrpc: '2.0', id: 1, method: 'initialize' };
await gate(
{
method: 'POST',
path: '/mcp',
headers: {},
body,
socket: { remoteAddress: '203.0.113.7' },
} as unknown as Request,
res as unknown as Response,
next,
);
expect(res.status).toHaveBeenCalledWith(401);
expect(next).not.toHaveBeenCalled();
expect(h.auditService.logWarn).toHaveBeenCalledWith(AuditAction.API_KEY_AUTH_FAILED, expect.anything());
});
it('dispatches the request to transport.handleRequest with the parsed body', async () => {
const h = mount();
const body = {
jsonrpc: '2.0',
id: 1,
method: 'tools/call',
params: { name: 'MessageSendText', arguments: { sessionId: 's1', to: '123', text: 'hi' } },
};
const { req, res } = await post(h, body, { 'x-api-key': 'good-key' });
expect(mockServerConnect).toHaveBeenCalledTimes(1); // fresh server+transport wired per request
expect(mockHandleRequest).toHaveBeenCalledWith(req, res, body);
expect(res.on).toHaveBeenCalledWith('close', expect.any(Function)); // per-request teardown wired
expect(res.status).not.toHaveBeenCalled(); // no error fallback
});
it('builds a read-only catalogue on every request when MCP_READONLY is unset', async () => {
const prev = process.env.MCP_READONLY;
delete process.env.MCP_READONLY;
try {
const h = mount({});
expect(h.registry.list).toHaveBeenCalledWith({ readOnly: true });
h.registry.list.mockClear();
await post(h, { jsonrpc: '2.0', id: 1, method: 'tools/list' }, { 'x-api-key': 'good-key' });
expect(h.registry.list).toHaveBeenCalledTimes(1);
expect(h.registry.list).toHaveBeenLastCalledWith({ readOnly: true });
} finally {
if (prev === undefined) delete process.env.MCP_READONLY;
else process.env.MCP_READONLY = prev;
}
});
it('logs the tool count once at mount, not on every request', async () => {
const info = jest.spyOn(LoggerService.prototype, 'log');
try {
const h = mount();
expect(info).toHaveBeenCalledTimes(1);
await post(h, { jsonrpc: '2.0', id: 1, method: 'tools/list' }, { 'x-api-key': 'good-key' });
await post(h, { jsonrpc: '2.0', id: 2, method: 'tools/list' }, { 'x-api-key': 'good-key' });
expect(mockServerConnect).toHaveBeenCalledTimes(2);
expect(info).toHaveBeenCalledTimes(1);
} finally {
info.mockRestore();
}
});
it('refuses an invalid API key inside the dispatch: tool error result, tool handler never runs', async () => {
const h = mount();
h.authService.validateApiKey.mockRejectedValue(new UnauthorizedException('API key is invalid'));
await post(h, { jsonrpc: '2.0', id: 1 }, { 'x-api-key': 'bad-key' });
// Invoke the registered tool callback exactly as the SDK would while handling a tools/call.
const result = (await toolCallback()(
{ sessionId: 's1', to: '123', text: 'hi' },
{ requestInfo: { headers: { 'x-api-key': 'bad-key' } } },
)) as { isError?: boolean; content: Array<{ text: string }> };
expect(result.isError).toBe(true);
expect(JSON.parse(result.content[0].text)).toMatchObject({
success: false,
name: 'UnauthorizedException',
message: 'API key is invalid',
});
expect(h.authService.validateApiKey).toHaveBeenCalledWith('bad-key', undefined, 's1');
expect(h.tool.handler).not.toHaveBeenCalled(); // refused before the tool runs
// ...and the auth failure hits the audit trail with the real request context (mirrors REST).
expect(h.auditService.logWarn).toHaveBeenCalledWith(
AuditAction.API_KEY_AUTH_FAILED,
expect.objectContaining({
ipAddress: '203.0.113.7',
method: 'POST',
path: '/mcp',
errorMessage: 'API key is invalid',
}),
);
});
it('runs the tool on a valid key without writing an auth-failure record', async () => {
const h = mount();
h.authService.validateApiKey.mockResolvedValue({ id: 'k1' });
await post(h, { jsonrpc: '2.0', id: 1 }, { 'x-api-key': 'good-key' });
const result = (await toolCallback()(
{ sessionId: 's1', to: '123', text: 'hi' },
{ requestInfo: { headers: { 'x-api-key': 'good-key' } } },
)) as { isError?: boolean };
expect(result.isError).toBeFalsy();
expect(h.tool.handler).toHaveBeenCalledTimes(1);
expect(h.auditService.logWarn).not.toHaveBeenCalled();
});
it('hands the SDK request cancellation signal to the tool handler', async () => {
const h = mount();
h.authService.validateApiKey.mockResolvedValue({ id: 'k1' });
await post(h, { jsonrpc: '2.0', id: 1 });
const controller = new AbortController();
let received: AbortSignal | undefined;
h.tool.handler = (_input, _key, _scope, signal) => {
received = signal;
return Promise.resolve({ ok: true });
};
await toolCallback()(
{ sessionId: 's1', to: '123', text: 'hi' },
{ authInfo: { token: 'good-key' }, signal: controller.signal },
);
expect(received).toBe(controller.signal);
});
// One parser for every surface that reads Authorization, so a header the REST guard accepts is
// accepted here too and one it refuses is refused here too.
it.each([
['bearer good-key', 'good-key'],
['Bearer\tgood-key', 'good-key'],
['Bearer good-key extra', undefined],
])('reads the Authorization header %j like the REST guard', async (header, expected) => {
const h = mount();
h.authService.validateApiKey.mockResolvedValue({ id: 'k1' });
await post(h, { jsonrpc: '2.0', id: 1 }, { authorization: header });
await toolCallback()(
{ sessionId: 's1', to: '123', text: 'hi' },
{ requestInfo: { headers: { authorization: header } } },
);
if (expected === undefined) expect(h.authService.validateApiKey).not.toHaveBeenCalled();
else expect(h.authService.validateApiKey).toHaveBeenCalledWith(expected, undefined, 's1');
});
// Node keeps only the first of two Authorization headers, while the SDK's web Request joins them,
// so the tool call must reuse the key the gate validated rather than parse its own header copy.
it('uses the key the gate validated when the SDK headers carry a joined Authorization', async () => {
const h = mount();
h.authService.validateApiKey.mockResolvedValue({ id: 'k1' });
const gate = (h.adapter.post.mock.calls[0] as unknown[])[3] as (
req: Request,
res: Response,
next: () => void,
) => Promise<void>;
const req = {
method: 'POST',
path: '/mcp',
headers: { authorization: 'Bearer good-key' },
body: { jsonrpc: '2.0', id: 1 },
socket: { remoteAddress: '203.0.113.7' },
} as unknown as Request & { auth?: unknown };
const next = jest.fn();
await gate(req, makeRes() as unknown as Response, next);
expect(next).toHaveBeenCalledTimes(1);
await h.routeHandler(req, makeRes() as unknown as Response);
const result = (await toolCallback()(
{ sessionId: 's1', to: '123', text: 'hi' },
{ authInfo: req.auth, requestInfo: { headers: { authorization: 'Bearer good-key, Bearer other-key' } } },
)) as { isError?: boolean };
expect(result.isError).toBeFalsy();
expect(h.authService.validateApiKey).toHaveBeenLastCalledWith('good-key', undefined, 's1');
expect(h.tool.handler).toHaveBeenCalledTimes(1);
expect(h.auditService.logWarn).not.toHaveBeenCalled();
});
it('fails closed on a session-scoped tool call without sessionId (guard fires before the auth lookup)', async () => {
const h = mount();
await post(h, { jsonrpc: '2.0', id: 1 }, { authorization: 'Bearer good-key' });
const result = (await toolCallback()(
{ to: '123', text: 'hi' }, // no sessionId
{ requestInfo: { headers: { authorization: 'Bearer good-key' } } },
)) as { isError?: boolean; content: Array<{ text: string }> };
expect(result.isError).toBe(true);
expect(JSON.parse(result.content[0].text)).toMatchObject({
success: false,
message: 'sessionId is required for this tool',
});
// Fenced at the runtime boundary before the auth DB lookup, so a session-restricted key can
// never ride an undefined scope past validateApiKey's allowedSessions check.
expect(h.authService.validateApiKey).not.toHaveBeenCalled();
expect(h.tool.handler).not.toHaveBeenCalled();
expect(h.auditService.logWarn).not.toHaveBeenCalled(); // 400 parity with REST: not an auth failure
});
it('answers a JSON-RPC 500 when the transport throws', async () => {
const h = mount();
mockHandleRequest.mockRejectedValueOnce(new Error('boom'));
const { res } = await post(h, { jsonrpc: '2.0', id: 1 });
expect(res.status).toHaveBeenCalledWith(500);
expect(res.json).toHaveBeenCalledWith({
jsonrpc: '2.0',
error: { code: -32603, message: 'Internal server error' },
id: null,
});
});
});