Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(security): scope the REST rate-limit windows to controller routes

Yudhi Armyndharis6a85962de2c0
diff --git a/.env.example b/.env.example
index 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.md
index 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.