websocket-security

WebSocket Security

Rules (for AI agents)

ALWAYS

• Validate the Origin header on the upgrade handshake against an allowlist, and understand precisely what that buys: the browser sets Origin and script cannot forge it, so the check stops Cross-Site WebSocket Hijacking — a page on attacker.com opening wss://api.example.com/ws and inheriting the user's cookies. It buys nothing against a non-browser client, which sets any header it likes. Origin is a CSRF control, not authentication. The same-origin policy and CORS preflight do not apply to the upgrade at all, which is why this check must be written by hand.
• Authenticate the handshake, not the first frame. Once the upgrade completes the connection exists, has consumed the user's cookie context, and is already a resource the caller controls. A subscribe or auth message afterwards is too late.
• For a browser client, pick one of two mechanisms, because the browser WebSocket constructor cannot set request headers — there is no Authorization header available to you:
  1. Cookie on the upgrade plus the Origin check above as the CSRF control, or
  2. A single-use ticket: the authenticated page calls an ordinary HTTP endpoint, receives a short-lived opaque ticket bound to the user and to the intended resource, passes it in the URL, and the server redeems and invalidates it at handshake time. A ticket is safe in a URL precisely because replaying it fails.
• Re-authorize every frame, both the action and the subject it names. A frame like {"action":"write","subjectId":"X"} must be checked against the principal established at handshake — an authenticated socket must never be able to assert an arbitrary subject id per frame. That is per-frame BOLA, and the forged id reaches every consumer downstream of the socket that trusts it. Permissions also change while the connection is open: logout, role change, account lock, token expiry. A socket opened an hour ago carries an authorization decision an hour old.
• Bound the connection: maximum frame and message size, messages per second per connection, concurrent connections per user and per source address, and total connection lifetime after which the client must re-handshake. A WebSocket is an allocation that persists, so every limit HTTP gets per-request must be re-expressed per-connection. Concrete starting values, and the backpressure and heartbeat settings, are in references/limits-and-handshake.md.
• Use wss://. protocol-security owns the TLS configuration behind it; what belongs here is that ws:// exposes the session token, every frame, and the handshake itself to any on-path observer.
• Consult auth-security for the token's own properties — lifetime, rotation, and why a bearer token does not belong in a URL — and cors-security for the origin allowlist itself, including how to treat the serialized null origin.