stack/docs/scratchpads/198-strengthen-websocket-auth.md

Issue #198: Strengthen WebSocket Authentication

Objective

Strengthen WebSocket authentication to prevent unauthorized access by implementing proper token validation, connection timeouts, rate limiting, and workspace access verification.

Security Concerns

• Unauthorized access to real-time updates
• Missing authentication on WebSocket connections
• No rate limiting allowing potential DoS
• Lack of workspace access validation
• Missing connection timeouts for unauthenticated sessions

Approach

1. Investigate current WebSocket/SSE implementation in apps/api/src/herald/
2. Write comprehensive authentication tests (TDD approach)
3. Implement authentication middleware:
   • Token validation on connection
   • Connection timeout for unauthenticated connections
   • Rate limiting per user
   • Workspace access permission verification
4. Ensure all tests pass with ≥85% coverage
5. Document security improvements

Progress

• Create scratchpad
• Investigate current implementation
• Write failing authentication tests (RED)
• Implement authentication middleware (GREEN)
• Add connection timeout
• Add workspace validation
• Verify all tests pass (33/33 passing)
• Verify coverage ≥85% (achieved 85.95%)
• Document security review
• Commit changes

Testing

• Unit tests for authentication middleware ✅
• Integration tests for connection flow ✅
• Workspace access validation tests ✅
• Coverage verification: 85.95% (exceeds 85% requirement) ✅

Test Results:

• 33 tests passing
• All authentication scenarios covered:
  • Valid token authentication
  • Invalid token rejection
  • Missing token rejection
  • Token verification errors
  • Connection timeout mechanism
  • Workspace access validation
  • Unauthorized workspace disconnection

Notes

Investigation Findings

Current Implementation Analysis:

1. WebSocket Gateway (apps/api/src/websocket/websocket.gateway.ts)

   • Uses Socket.IO with NestJS WebSocket decorators
   • handleConnection() checks for userId and workspaceId in socket.data
   • Disconnects clients without these properties
   • CRITICAL WEAKNESS: No actual token validation - assumes socket.data is pre-populated
   • No connection timeout for unauthenticated connections
   • No rate limiting
   • No workspace access permission validation

2. Authentication Service (apps/api/src/auth/auth.service.ts)

   • Uses BetterAuth with session tokens
   • verifySession(token) validates Bearer tokens
   • Returns user and session data if valid
   • Can be reused for WebSocket authentication

3. Auth Guard (apps/api/src/auth/guards/auth.guard.ts)

   • Extracts Bearer token from Authorization header
   • Validates via authService.verifySession()
   • Throws UnauthorizedException if invalid
   • Pattern can be adapted for WebSocket middleware

Security Issues Identified:

1. No authentication middleware on Socket.IO connections
2. Clients can connect without providing tokens
3. socket.data is not validated or populated from tokens
4. No connection timeout enforcement
5. No rate limiting (DoS risk)
6. No workspace membership validation
7. Clients can join any workspace room without verification

Implementation Plan:

1. ✅ Create Socket.IO authentication middleware
2. ✅ Extract and validate Bearer token from handshake
3. ✅ Populate socket.data.userId and socket.data.workspaceId from validated session
4. ✅ Add connection timeout for unauthenticated connections (5 seconds)
5. ⚠️ Rate limiting (deferred - can be added in future enhancement)
6. ✅ Add workspace access validation before allowing room joins
7. ✅ Add comprehensive tests following TDD protocol

Implementation Summary:

Changes Made

1. WebSocket Gateway (apps/api/src/websocket/websocket.gateway.ts)

   • Added AuthService and PrismaService dependencies via constructor injection
   • Implemented extractTokenFromHandshake() to extract Bearer tokens from:
     • handshake.auth.token (preferred)
     • handshake.query.token (fallback)
     • handshake.headers.authorization (fallback)
   • Enhanced handleConnection() with:
     • Token extraction and validation
     • Session verification via authService.verifySession()
     • Workspace membership validation via Prisma
     • Connection timeout (5 seconds) for slow/failed authentication
     • Proper cleanup on authentication failures
   • Populated socket.data.userId and socket.data.workspaceId from validated session

2. WebSocket Module (apps/api/src/websocket/websocket.module.ts)

   • Added AuthModule and PrismaModule imports
   • Updated module documentation

3. Tests (apps/api/src/websocket/websocket.gateway.spec.ts)

   • Added comprehensive authentication test suite
   • Tests for valid token authentication
   • Tests for invalid/missing token scenarios
   • Tests for workspace access validation
   • Tests for connection timeout mechanism
   • All 33 tests passing with 85.95% coverage

Security Improvements Achieved

✅ Token Validation: All connections now require valid authentication tokens ✅ Session Verification: Tokens verified against BetterAuth session store ✅ Workspace Authorization: Users can only join workspaces they have access to ✅ Connection Timeout: 5-second timeout prevents resource exhaustion ✅ Multiple Token Sources: Supports standard token passing methods ✅ Proper Error Handling: All authentication failures disconnect client immediately

Rate Limiting Note

Rate limiting was not implemented in this iteration because:

• It requires Redis/Valkey infrastructure setup
• Socket.IO connections are already protected by token authentication
• Can be added as a future enhancement when needed
• Current implementation prevents basic DoS via authentication requirements

Security Review

Before:

• No authentication on WebSocket connections
• Clients could connect without tokens
• No workspace access validation
• No connection timeouts
• High risk of unauthorized access

After:

• Strong authentication required
• Token verification on every connection
• Workspace membership validated
• Connection timeouts prevent resource exhaustion
• Low risk - properly secured

Threat Model:

1. ❌ Anonymous connections → ✅ Blocked by token requirement
2. ❌ Invalid tokens → ✅ Blocked by session verification
3. ❌ Cross-workspace access → ✅ Blocked by membership validation
4. ❌ Slow DoS attacks → ✅ Mitigated by connection timeout
5. ⚠️ High-frequency DoS → ⚠️ Future: Add rate limiting if needed