Network Security

whoot. secures every network layer — from authenticated TURN/STUN relay servers and HMAC-signed API requests to encrypted WebSocket connections and rate-limited endpoints.

WebRTC Connectivity Model

WebRTC, the protocol behind whoot.'s voice channels, uses the ICE (Interactive Connectivity Establishment) framework to find the best network path between your browser and the media server. This involves:

• STUN (Session Traversal Utilities for NAT) — Helps discover your public IP address and port when behind a NAT or firewall. STUN traffic is lightweight and only used during connection setup
• TURN (Traversal Using Relays around NAT) — When direct connections aren't possible (e.g. behind restrictive corporate firewalls), audio is relayed through TURN servers. All relayed traffic is encrypted with the same DTLS-SRTP encryption as direct connections

Both STUN and TURN servers require authentication. Unauthenticated relay requests are rejected.

TURN Server Authentication

TURN credentials in whoot. are secured with multiple controls:

1. Authenticated credential request — To obtain TURN credentials, the client must make an HMAC-SHA256 signed request using the user's session token. The server validates the signature before issuing credentials
2. Time-limited credentials — TURN credentials include a timestamp and expire after a short window. Expired credentials are rejected by the TURN server
3. Per-user scoping — Each user receives unique TURN credentials. Credentials cannot be shared across users or sessions
4. Memory clearing — TURN credentials (username and password) are explicitly cleared from JavaScript memory when the page unloads, the user signs out, or the session ends

HMAC-Signed API Requests

Sensitive API endpoints in whoot. — particularly those involved in voice credential provisioning — require HMAC-signed requests:

• The client constructs a message containing the operation identifier, resource ID, and a Unix timestamp
• This message is signed using HMAC-SHA256 with the user's session token as the key
• The signature and timestamp are sent as custom HTTP headers
• The server independently computes the expected signature and rejects requests where the signature doesn't match or the timestamp is outside the acceptable window

This prevents several classes of attack:

• Replay attacks — Old requests cannot be replayed because the timestamp will be outside the validity window
• Request forgery — Without the session token, attackers cannot generate valid signatures
• Parameter tampering — The resource ID is included in the signed message, so it cannot be altered without invalidating the signature

WebSocket Security

whoot. uses WebSocket connections for real-time events (presence, channel updates, messages). These connections are secured as follows:

• WSS only — All WebSocket connections use WSS (WebSocket Secure), which is WebSocket over TLS. Unencrypted WS connections are not accepted
• Authentication on connect — The API token is provided during the WebSocket handshake. Unauthenticated connections are rejected immediately
• Tenant-scoped events — WebSocket events are scoped to the user's tenant. Users only receive events for tenants they are a member of
• Heartbeat monitoring — The server sends periodic pings (every 30 seconds). If the client doesn't respond, the connection is terminated, preventing stale connections from accumulating

Voice Signalling Security

Voice session signalling (call setup, teardown, and control messages) is transmitted over encrypted WebSocket connections:

• Encrypted transport — All signalling messages travel over WSS (TLS-encrypted WebSocket)
• Authenticated sessions — Signalling credentials are fetched via HMAC-signed requests and are scoped to the authenticated user
• Automatic teardown — When a session ends (user navigates away, signs out, or loses connection), signalling sessions are cleanly terminated and resources are freed
• Connection state monitoring — The client monitors the signalling transport state. If the connection drops unexpectedly, it is detected within seconds and an authenticated reconnection is attempted

SSRF Prevention

Server-Side Request Forgery (SSRF) is a class of attack where a server is tricked into making requests to unintended destinations. whoot. prevents SSRF with strict input validation:

• Cluster ID validation — Voice cluster identifiers are validated against a strict regex pattern: only lowercase alphanumeric characters and hyphens are allowed, with a maximum length of 64 characters. This prevents URL injection via crafted cluster IDs containing characters like @, /, #, or \
• URL construction — Server-side URLs are constructed using validated components, never by concatenating raw user input
• Webhook URL validation — Webhook endpoints must use HTTPS and are validated before deliveries are attempted

Rate Limiting

All API endpoints are rate-limited to prevent abuse:

Rate limit status is communicated via standard HTTP headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) so integrations can implement appropriate backoff strategies.

Webhook Delivery Security

Outbound webhook deliveries include security measures to protect your receiving endpoints:

• HTTPS only — Webhook endpoint URLs must use HTTPS. HTTP endpoints are rejected during configuration
• Signature verification — Every webhook delivery includes an X-Whoot-Signature header containing an HMAC-SHA256 signature of the payload, computed using your webhook signing secret. This allows your server to verify the request originated from whoot.
• Retry with backoff — Failed deliveries are retried up to 5 times with exponential backoff (1 minute → 5 minutes → 30 minutes → 2 hours). After all retries are exhausted, the delivery is marked as failed
• Idempotent event IDs — Each event includes a unique ID that your server can use to deduplicate retried deliveries

Next Steps

• Security Architecture — Full encryption model
• Authentication Security — MFA, SSO, and session management
• WebSocket API — Real-time event reference
• Webhooks — Webhook integration guide