fix: NCS-122 send WS token via first-message auth instead of query param #13

2026-06-17T09:42:52+02:00

lq64 commented

2026-06-17 09:42:52 +02:00

Remove token from WebSocket URL query parameters in ChallengeWebSocketService
and GameApiService. Instead, send {"type":"auth","token":"..."} as the first
text frame after the connection opens, matching the new backend auth protocol.

Note on authentication approach

The token is not sent via the HTTP Authorization header. The browser's native WebSocket API does not allow setting custom HTTP headers during the
handshake — this is a hard browser specification constraint, not a framework limitation.

Instead this PR implements first-message auth: the client sends {"type":"auth","token":""} as the first text frame immediately after the
connection opens. The server validates the token before processing any further messages and closes the connection if the token is missing or
invalid.

This moves the token out of the URL query parameter (visible in server logs and browser history) and into an encrypted WebSocket frame, which is
the standard approach used by production WebSocket APIs (Slack, Discord, etc.) for the same reason.

The alternatives that would put the token in an actual HTTP header are:

Cookie — store the JWT as Secure; SameSite=Strict cookie on login; browser sends it automatically with the upgrade request
Sec-WebSocket-Protocol trick — pass the token as a subprotocol value; non-standard and visible in tooling as a protocol string

If cookie-based auth is preferred in the future, that would be a separate ticket covering the login flow.

Remove token from WebSocket URL query parameters in ChallengeWebSocketService and GameApiService. Instead, send {"type":"auth","token":"..."} as the first text frame after the connection opens, matching the new backend auth protocol. Note on authentication approach The token is not sent via the HTTP Authorization header. The browser's native WebSocket API does not allow setting custom HTTP headers during the handshake — this is a hard browser specification constraint, not a framework limitation. Instead this PR implements first-message auth: the client sends {"type":"auth","token":"<JWT>"} as the first text frame immediately after the connection opens. The server validates the token before processing any further messages and closes the connection if the token is missing or invalid. This moves the token out of the URL query parameter (visible in server logs and browser history) and into an encrypted WebSocket frame, which is the standard approach used by production WebSocket APIs (Slack, Discord, etc.) for the same reason. The alternatives that would put the token in an actual HTTP header are: - Cookie — store the JWT as Secure; SameSite=Strict cookie on login; browser sends it automatically with the upgrade request - Sec-WebSocket-Protocol trick — pass the token as a subprotocol value; non-standard and visible in tooling as a protocol string If cookie-based auth is preferred in the future, that would be a separate ticket covering the login flow.

lq64 added 1 commit 2026-06-17 10:43:08 +02:00

fix(ncs-122): send WS token via first-message auth instead of query param 68395f820c

Remove token from WebSocket URL query parameters in ChallengeWebSocketService
and GameApiService. Instead, send {"type":"auth","token":"..."} as the first
text frame after the connection opens, matching the new backend auth protocol.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

lq64 force-pushed fix/NCS-122-ws-auth-header from 9dc0b4a7df to 68395f820c

2026-06-17 10:43:08 +02:00

Compare

lq64 merged commit 1d2c217da8 into main

2026-06-17 10:50:17 +02:00

lq64 deleted branch fix/NCS-122-ws-auth-header

2026-06-17 10:50:18 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: NowChess/NowChess-Frontend#13