# 30. WebSocket Production Hardening

meta:
  id: web-production-30
  feature: web-production
  priority: P1
  depends_on: []
  tags: [security, websockets, production]

objective:
- Harden WebSocket server for production with authentication, rate limiting, and connection management

deliverables:
- Authenticated WebSocket connections
- Connection rate limiting
- Connection cleanup on logout
- Horizontal scaling support (Redis adapter)

steps:
1. Harden WebSocket authentication:
   - Validate JWT token in connection query param
   - Reject unauthenticated connections immediately
   - Re-authenticate periodically (every 15 minutes)
   - Close connection on token expiry
2. Implement connection rate limiting:
   - Max 1 WebSocket connection per user
   - Max 5 reconnection attempts per minute
   - IP-based connection limits (100 per IP)
3. Add connection management:
   - Track active connections per user
   - Close duplicate connections
   - Heartbeat with timeout (current implementation good)
   - Graceful close on server shutdown
4. Implement horizontal scaling:
   - Use Redis adapter for ws (socket.io-redis or @socket.io/redis-adapter)
   - Or use Redis pub/sub for broadcast across instances
   - Ensure alerts reach all connected clients regardless of instance
5. Add message validation:
   - Validate all incoming message schemas
   - Reject malformed messages
   - Limit message size (max 10KB)
   - Sanitize message content
6. Add monitoring:
   - Track active connection count
   - Track messages per second
   - Track connection duration
   - Alert on connection spikes (possible DDoS)
7. Secure WebSocket server:
   - Run on separate port or path
   - TLS encryption (wss://)
   - No mixed content (ws on https page)

tests:
- Unit: Test authentication rejection
- Integration: Test duplicate connection handling
- Load: Test 1000 concurrent WebSocket connections
- Security: Test unauthenticated connection rejection

acceptance_criteria:
- All WebSocket connections authenticated with valid JWT
- Unauthenticated connections rejected immediately
- Max 1 connection per user (duplicates closed)
- Heartbeat/ping-pong working with 30s interval
- Redis adapter active for multi-instance deployment
- Message size limited to 10KB
- TLS encryption (wss://) in production
- Connection metrics visible in monitoring
- Graceful shutdown closes all connections cleanly

validation:
- Connect without token → connection rejected
- Connect with valid token → connection accepted
- Open second connection → first connection closed
- Send 20KB message → connection closed with error
- Scale to 2 server instances → alerts broadcast to all clients
- Check metrics → active connections, message rate visible

notes:
- Current WebSocket in web/src/lib/websocket.ts and web/src/server/websocket.ts
- ws library supports Redis adapter for scaling
- Consider using Socket.io for more robust connection management
- WebSocket auth via query params is common but consider cookie-based for security