Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(mcp): charge the per-IP throttle per JSON-RPC message
Yudhi Armyndharise6f7289bbf8b
diff --git a/.env.example b/.env.exampleindex bc3793bf7..dd409f25c 100644--- a/.env.example+++ b/.env.example@@ -701,7 +701,7 @@ WEBHOOK_SSRF_PROTECT=true# MCP_RATE_LIMIT_WINDOW_MS=60000 # window size in ms (default 60000 = 1 min)# Pre-auth, per-IP sliding-window throttle for the /mcp mount (gates invalid-key requests before# key validation, since the raw mount bypasses the global throttler). Same fallback rules.-# MCP_IP_RATE_LIMIT_MAX=120 # max requests per IP per window (default 120)+# MCP_IP_RATE_LIMIT_MAX=120 # max JSON-RPC messages per IP per window (default 120)# MCP_IP_RATE_LIMIT_WINDOW_MS=60000 # window size in ms (default 60000 = 1 min)# =============================================================================diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex c737c74c7..e740b9630 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -6208,6 +6208,7 @@ Key facts:- Gated by **`MCP_ENABLED=true`**. When off, the module/route is never mounted and `POST /mcp` returns `404`.- MCP is **read-only by default**: only read-tier tools are registered unless you set `MCP_READONLY=false` to expose write tools. Per-key sliding-window rate limit: `MCP_RATE_LIMIT_MAX` (default 60) per `MCP_RATE_LIMIT_WINDOW_MS` (default 60000).- Stateless transport (no SSE/session id for normal calls).+- Pre-auth per-IP throttle: `MCP_IP_RATE_LIMIT_MAX` (default 120) JSON-RPC messages per `MCP_IP_RATE_LIMIT_WINDOW_MS` (default 60000). Each element of a batch counts; an over-budget request gets HTTP `429` with a JSON-RPC error body and runs none of its messages, but still spends whatever budget the IP had left.**Request body** — JSON-RPC 2.0 envelope (validated by the MCP SDK, **not** the Nest ValidationPipe)diff --git a/docs/24-mcp-integration.md b/docs/24-mcp-integration.mdindex a9b3cef08..92b0280ee 100644--- a/docs/24-mcp-integration.md+++ b/docs/24-mcp-integration.md@@ -176,7 +176,11 @@ only when an agent genuinely needs to send messages / mutate state.missing/invalid key would otherwise reach a DB lookup unthrottled). It keys on theresolved client IP (honoring `TRUSTED_PROXIES`) and is tuned with `MCP_IP_RATE_LIMIT_MAX`(default `120`) and `MCP_IP_RATE_LIMIT_WINDOW_MS` (default `60000`), with the same- fallback rules — independent of the per-key vars.+ fallback rules, independent of the per-key vars. It counts JSON-RPC messages, not HTTP+ requests: each element of a batch spends one unit, and a batch larger than the+ remaining budget is refused whole with a `429`. None of its messages run, but the+ refusal still spends whatever budget was left, so the IP is at the cap until the+ window slides.- **Response parity.** Tools reuse the REST response DTOs, so sensitive fields the RESTAPI strips (e.g. webhook HMAC secrets and custom headers, session proxy URLs and engineconfig) are **not** exposed over MCP.@@ -192,7 +196,7 @@ MCP_ENABLED=true npm run start:prod # or set MCP_ENABLED in your .env / composMCP_READONLY=false # expose write tools (default is read-only when unset)MCP_RATE_LIMIT_MAX=60 # max tool calls per key per window (default 60)MCP_RATE_LIMIT_WINDOW_MS=60000 # sliding window in ms (default 60000 = 1 min)-MCP_IP_RATE_LIMIT_MAX=120 # pre-auth per-IP request cap per window (default 120)+MCP_IP_RATE_LIMIT_MAX=120 # pre-auth per-IP message cap per window (default 120)MCP_IP_RATE_LIMIT_WINDOW_MS=60000 # per-IP window in ms (default 60000 = 1 min)```diff --git a/src/modules/mcp/mcp.server.spec.ts b/src/modules/mcp/mcp.server.spec.tsindex 8d18a9be5..c52a0f922 100644--- a/src/modules/mcp/mcp.server.spec.ts+++ b/src/modules/mcp/mcp.server.spec.ts@@ -76,7 +76,8 @@ describe('resolveMcpReadOnly (secure-by-default MCP read-only flag)', () => {// 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): Request => ({ socket: { remoteAddress: ip }, headers: {} }) as unknown as Request;+ 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 => {@@ -115,6 +116,44 @@ describe('createIpThrottle (pre-auth per-IP MCP throttle)', () => {throttle(makeReq('2.2.2.2'), makeRes() as unknown as Response, next);expect(next).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@@ -202,6 +241,7 @@ describe('mountMcpServer (raw-Express request-handling path)', () => {tool: AnyToolDescriptor;authService: { validateApiKey: jest.Mock; hasPermission: jest.Mock };auditService: { logWarn: jest.Mock };+ adapter: { post: jest.Mock };}const mount = (): Harness => {@@ -231,10 +271,10 @@ describe('mountMcpServer (raw-Express request-handling path)', () => {{ readOnly: false },auditService as unknown as AuditService,);- // adapter.post received [createIpThrottle(...), express.json(...), mcpHandler]; the tests drive+ // 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 };+ return { routeHandler, tool, authService, auditService, adapter };};type ResMock = { on: jest.Mock; status: jest.Mock; json: jest.Mock; headersSent: boolean };@@ -268,6 +308,13 @@ describe('mountMcpServer (raw-Express request-handling path)', () => {return mockRegisteredTools[0].callback;};+ it('parses the body before the per-IP throttle so a batch is charged per message', () => {+ const h = mount();+ const [path, parser] = h.adapter.post.mock.calls[0] as unknown[];+ expect(path).toBe('/mcp');+ expect((parser as { name?: string }).name).toBe('jsonParser');+ });+it('dispatches the request to transport.handleRequest with the parsed body', async () => {const h = mount();const body = {diff --git a/src/modules/mcp/mcp.server.ts b/src/modules/mcp/mcp.server.tsindex bde30cf3a..cb8a47ba0 100644--- a/src/modules/mcp/mcp.server.ts+++ b/src/modules/mcp/mcp.server.ts@@ -172,8 +172,13 @@ export interface MountMcpServerOptions {export function createIpThrottle(ipRateLimiter: KeyRateLimiter): RequestHandler {return (req, res, next) => {const ip = resolveClientIp(req, readTrustedProxies());+ // The unit of work is the JSON-RPC message, not the HTTP request: the transport dispatches every+ // element of a batch, and each tools/call element runs its own key lookup and auth-failure audit.+ // An over-budget batch throws on the first check past the cap, so a huge array costs at most+ // `max + 1` checks.+ const messages = Array.isArray(req.body) ? Math.max(1, req.body.length) : 1;try {- ipRateLimiter.check(ip);+ for (let i = 0; i < messages; i++) ipRateLimiter.check(ip);next();} catch (err) {const status = err instanceof HttpException ? err.getStatus() : 429;@@ -244,12 +249,13 @@ export function mountMcpServer(const adapter = httpAdapter as unknown as { post: (path: string, ...handlers: RequestHandler[]) => unknown };// The route throttle gates the auth DB lookup and per-request MCP server/transport construction. The// process-wide capped json() in main.ts runs first for all routes; this route-level parser is a- // defensive fallback and no-ops once the global parser has consumed the body.+ // defensive fallback and no-ops once the global parser has consumed the body. It sits before the+ // throttle so the throttle always sees a parsed body and can charge a batch per message.// `inflate: false` matches the global parsers: a compressed body is refused by the budget// middleware long before this runs, and this keeps the fallback from becoming the one parser that// would still gunzip an unaccounted body if that ordering ever changed.// `limit` mirrors the same global cap for the same reason: without it a middleware reorder would// silently leave this mount uncapped.const bodyLimit = resolveBodyLimit(process.env.BODY_SIZE_LIMIT);- adapter.post(basePath, createIpThrottle(ipRateLimiter), express.json({ limit: bodyLimit, inflate: false }), handler);+ adapter.post(basePath, express.json({ limit: bodyLimit, inflate: false }), createIpThrottle(ipRateLimiter), handler);}