Missing option to provide HTTP headers (e.g. for authentication)

[djakielski]

Currently, the WebsocketClientBuilder in websocket-ts does not expose any way to inject custom HTTP headers when establishing the WebSocket handshake. This makes it impossible to use bearer tokens or other header-based authentication schemes with the library out of the box.

Many API Gateway or proxy setups require clients to present an Authorization header (e.g. Bearer ) at handshake time. Without the ability to set headers, users must resort to embedding tokens in query parameters (which is less secure) or reimplementing the underlying connection logic themselves.

const client = new WebsocketClientBuilder()
  .url("wss://example.com/socket")
  .build();

// No API to add headers:
// client.withHeader("Authorization", `Bearer ${token}`)  ← not supported

[jjxxs]

Thanks for reporting this. I’ll review it and, if appropriate, include it in #40 for the next release.

[jjxxs]

After looking into this: unfortunately, the WebSocket API in browsers does not allow setting arbitrary HTTP headers during the handshake. The only things you can control are the url and the protocols parameter. This is a platform restriction, not a limitation of websocket-ts.

The Sec-WebSocket-Protocol header is reserved for subprotocol negotiation, not for authentication. You can set it either via the withProtocols method on WebsocketBuilder or by passing protocols directly to the Websocket constructor.

For authentication, the recommended approaches are:

• Cookies: perform authentication beforehand and rely on a secure, HttpOnly cookie. The browser will automatically include it in the handshake.
• First-message auth: establish the connection and immediately send an authentication message containing the token. The server should treat the connection as unauthenticated until this message is received and verified.
• Query parameters: as a last resort, include a short-lived token in the connection URL (e.g. wss://example.com/socket?token=...).