Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(security): scope the REST rate-limit windows to controller routes
Yudhi Armyndharis6a85962de2c0
diff --git a/.env.example b/.env.exampleindex 641f7fa49..837932993 100644--- a/.env.example+++ b/.env.example@@ -662,10 +662,12 @@ WEBHOOK_SSRF_PROTECT=true# =============================================================================# RATE LIMITING (all TTLs are in MILLISECONDS)# =============================================================================-# All three windows (short/medium/long) apply to every non-exempt route, each counted per route-# handler and client IP; exceeding any one returns 429, and raising one tier does not lift the-# others. Unset values keep the defaults below. /api/health*, /api/metrics and /api/ingress/* are-# exempt (ingress has its own limits).+# All three windows (short/medium/long) apply to every non-exempt REST controller route, each+# counted per route handler and client IP; exceeding any one returns 429, and raising one tier does+# not lift the others. Unset values keep the defaults below. /api/health*, /api/metrics and+# /api/ingress/* are exempt (ingress has its own limits). The /mcp and /api/admin/queues mounts sit+# outside the controller pipeline and are not counted here: each has its own pre-auth per-IP+# throttle, set by MCP_IP_RATE_LIMIT_MAX / MCP_IP_RATE_LIMIT_WINDOW_MS.# RATE_LIMIT_MEDIUM_TTL=60000 # window in ms (default 60000 = 60s)# RATE_LIMIT_MEDIUM_LIMIT=100 # max requests per window# RATE_LIMIT_SHORT_TTL=1000 # 1s burst window (default)@@ -784,9 +786,10 @@ WEBHOOK_SSRF_PROTECT=true# Any blank/non-positive/non-numeric value falls back to the default.# MCP_RATE_LIMIT_MAX=60 # max tool calls per key per window (default 60)# 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 JSON-RPC messages per IP per window (default 120)+# Pre-auth, per-IP sliding-window throttle for the /mcp and /api/admin/queues mounts (gates+# invalid-key requests before key validation, since the raw mounts bypass the global throttler).+# Each mount counts separately. Same fallback rules.+# MCP_IP_RATE_LIMIT_MAX=120 # per IP per window: JSON-RPC messages on /mcp, HTTP requests on /api/admin/queues (default 120)# MCP_IP_RATE_LIMIT_WINDOW_MS=60000 # window size in ms (default 60000 = 1 min)# =============================================================================diff --git a/docs/04-security-design.md b/docs/04-security-design.mdindex 09e1b78ff..30fae4f45 100644--- a/docs/04-security-design.md+++ b/docs/04-security-design.md@@ -271,7 +271,7 @@ flowchart LR### Windows-Each window is counted **per route handler per client IP** (the IP resolved through `TRUSTED_PROXIES`) by a global `ThrottlerGuard`, so a client gets the full budget on every endpoint; for an aggregate per-client cap, add a limiter at your reverse proxy. There is **no per-endpoint limit table**: these three windows apply to every non-exempt route, and exceeding any one returns `429 Too Many Requests`:+Each window is counted **per route handler per client IP** (the IP resolved through `TRUSTED_PROXIES`) by a global `ThrottlerGuard`, so a client gets the full budget on every endpoint; for an aggregate per-client cap, add a limiter at your reverse proxy. There is **no per-endpoint limit table**: these three windows apply to every non-exempt REST controller route, and exceeding any one returns `429 Too Many Requests`:| Window | Default limit | Window length | Env overrides || -------- | ------------- | ------------- | --------------------------------------------------- |@@ -279,7 +279,7 @@ Each window is counted **per route handler per client IP** (the IP resolved thro| `medium` | 100 requests | 60 s | `RATE_LIMIT_MEDIUM_TTL` / `RATE_LIMIT_MEDIUM_LIMIT` || `long` | 1000 requests | 3600 s | `RATE_LIMIT_LONG_TTL` / `RATE_LIMIT_LONG_LIMIT` |-TTL values are in milliseconds. The `/api/metrics` and `/api/health*` routes are exempt (`@SkipThrottle`); `/api/health` still looks up at most 30 failed key presentations per client per minute, and past that answers without `version` and without a key lookup. To enforce tighter per-route limits, lower the global windows or add a limiter at your reverse proxy.+TTL values are in milliseconds. The `/api/metrics` and `/api/health*` routes are exempt (`@SkipThrottle`), and the ingress route has its own windows (below); `/api/health` still looks up at most 30 failed key presentations per client per minute, and past that answers without `version` and without a key lookup. The MCP endpoint (`/mcp`) and the Bull Board UI (`/api/admin/queues`) are raw Express mounts the guard never sees: RATE_LIMIT_* does not apply to them, and each is bounded by its own pre-auth per-IP throttle (`MCP_IP_RATE_LIMIT_MAX` / `MCP_IP_RATE_LIMIT_WINDOW_MS`). To enforce tighter per-route limits, lower the global windows or add a limiter at your reverse proxy.An IPv6 client is keyed on its /64, so rotating addresses inside one allocation does not mint fresh buckets. The same key is used by every other per-client limit: the MCP and Bull Board pre-auth throttles, the WebSocket limits below, the per-client share of the in-flight body budget for requests without an API key, the health route's key-lookup budget and auth-failure audit bound, and the REST, queue-dashboard and MCP auth-failure audit bound. `allowedIps` matching and audit rows still see the full address.