Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(security): list the /events frame size bound

Yudhi Armyndharis061b96ab7e9f
diff --git a/docs/04-security-design.md b/docs/04-security-design.md
index 15d7856f3..bdf6de8a8 100644
--- a/docs/04-security-design.md
+++ b/docs/04-security-design.md
@@ -395,8 +395,9 @@ Socket.IO frames never pass through the Nest enhancer pipeline, so the HTTP wind
| Client frames (subscribe/unsubscribe/ping) — token bucket | API key (IP, IPv6 on its /64, before auth completes) | 60 frames/s sustained, 120-frame burst | `WS_RATE_LIMIT_FRAME_PER_SECOND` / `WS_RATE_LIMIT_FRAME_BURST` |
| New handshakes — sliding window, enforced **before** key validation | client IP (resolved through `TRUSTED_PROXIES`, IPv6 on its /64) | 10 per 60 s | `WS_RATE_LIMIT_HANDSHAKE_MAX` / `WS_RATE_LIMIT_HANDSHAKE_WINDOW_MS` |
| Simultaneous sockets | API key | 16 | `WS_MAX_SOCKETS_PER_KEY` |
+| Size of one client frame | connection | 8 KiB (a larger frame closes it) | none, fixed in code |
-The frame budget is sized ~6x above legitimate traffic: the dashboard emits ~8 subscribe frames at page mount and only occasional ping/unsubscribe frames afterwards (server→client event fan-out is not limited). The handshake window stops an unauthenticated connection flood from forcing a DB `validateApiKey` per attempt; Socket.IO's exponential-backoff reconnect (~6 attempts/min per tab) stays under it. The socket cap covers multi-tab dashboards and SDK clients sharing one key. A rejected handshake or excess socket is answered with a `RATE_LIMITED` error frame and a clean disconnect; an over-budget frame gets a `RATE_LIMITED` error frame and is not dispatched. Violations are audited as `rate_limit_exceeded`, sampled to at most one row per subject+kind per minute (suppressed occurrences are counted into the next row) so the audit trail itself cannot become the flood.
+The frame budget is sized ~6x above legitimate traffic: the dashboard emits ~8 subscribe frames at page mount and only occasional ping/unsubscribe frames afterwards (server→client event fan-out is not limited). The handshake window stops an unauthenticated connection flood from forcing a DB `validateApiKey` per attempt; Socket.IO's exponential-backoff reconnect (~6 attempts/min per tab) stays under it. The socket cap covers multi-tab dashboards and SDK clients sharing one key. A rejected handshake or excess socket is answered with a `RATE_LIMITED` error frame and a clean disconnect; an over-budget frame gets a `RATE_LIMITED` error frame and is not dispatched. A frame over 8 KiB closes the connection (close code `1009`) without an answer, and a polling client learns the bound in the handshake and splits its batches to it; the longest legal frame is under 1 KiB. Violations are audited as `rate_limit_exceeded`, sampled to at most one row per subject+kind per minute (suppressed occurrences are counted into the next row) so the audit trail itself cannot become the flood.
## 4.7 CORS Configuration