Last reviewed: October 30, 2026 (Asia/Shanghai).
Direct answer
Review a coding-agent WebSocket patch as a long-lived network and authorization boundary. Require TLS (wss://) in production, an explicit allowlist for the browser Origin on every handshake, authentication before protected data is sent, authorization for each message action, bounded message and connection resources, and a defined close and session-expiry path. Then exercise those rules through the real upgrade path with an adversarial test matrix. A successful HTTP upgrade alone proves none of these controls.
The browser automatically includes cookies in a WebSocket handshake. A page hosted by an attacker can therefore attempt a connection to an application where the user is already signed in. The OWASP WebSocket Security Cheat Sheet
identifies this Cross-Site WebSocket Hijacking risk and recommends validating Origin against an explicit allowlist, while also requiring application authentication and message-level authorization. The protocol itself, specified by RFC 6455
, defines the opening handshake and close codes; it does not define your users, permissions, or business actions.
A patch can be structurally correct and still unsafe. It may accept every origin, treat the connection as an unlimited session, parse arbitrary message shapes, or leave authenticated sockets alive after logout. Make each decision visible in the patch and in evidence before merging.
Who this is for
Use this guide when an agent changes a browser or desktop WebSocket client, a server upgrade handler, a gateway, a chat or collaboration channel, a live build-status stream, or a protocol adapter. It applies to JSON and binary messages, authenticated and anonymous channels, and services behind a reverse proxy. It is especially important when a socket can read private data, start jobs, mutate state, or invoke tools.
For webhook-triggered agent work, pair this review with Verify Repository Webhooks Before They Launch Coding Agents . For browser API boundaries, use Prevent CORS Data Leaks in Coding-Agent API Patches and Set Safe Permission and Secret Boundaries for Coding Agents .
Key takeaways
- Use
wss://and verify that the proxy preserves the intended upgrade and timeout policy. - Match the complete
Originvalue against a trusted, code-owned allowlist. Do not use substring, suffix, wildcard, or reflected-origin matching. - Authenticate before sending protected data. If authentication is message-based, accept only the authentication message until it succeeds and expire unauthenticated sockets quickly.
- Check authorization for every action and resource. A valid socket is not an unlimited permission.
- Validate message schemas, binary signatures, replay fields, and size before business processing.
- Bound connections, message rates, queue depth, parser work, and backpressure. Close idle or dead sockets and clean up their state.
- Revalidate long-lived sessions and close sockets on logout or session expiry.
- Log connection and policy decisions without tokens, cookies, session IDs, or complete messages.
Sources checked
- OWASP WebSocket Security Cheat Sheet , fetched October 29, 2026 UTC. It supports WSS, origin validation, authentication, session expiry, message authorization, input and size validation, rate limits, backpressure, safe logging, and security tests.
- RFC 6455: The WebSocket Protocol , fetched October 29, 2026 UTC. It defines the opening handshake, framing and close semantics, and status codes such as 1008 (policy violation) and 1009 (message too big).
- MDN: Writing WebSocket client applications
, fetched October 29, 2026 UTC. It documents the browser
open,message,error, andcloselifecycle, disconnect handling, bfcache considerations, and client security responsibilities.
These references describe protocol and platform behavior. The allowlist, limits, session interval, and test values below are review recommendations for a particular application; they do not claim that a repository or deployment has passed them.
Contract details to verify
Write one contract per socket endpoint before reading helper code:
| Contract field | Decision to record | Evidence to retain |
|---|---|---|
| Transport | TLS termination point and accepted scheme | Proxy and application configuration plus an upgrade test |
| Origin | Complete approved browser origins | Exact-match policy test, including an untrusted lookalike |
| Identity | Cookie, bearer, mTLS, or first-message method | Authentication result and timeout case without secrets |
| Authorization | Allowed actions and resource scope per identity | Positive and denied message fixtures |
| Message | JSON schema or binary format, versions, and replay fields | Valid, malformed, duplicate, and oversized cases |
| Lifecycle | Idle timeout, heartbeat, logout, expiry, and reconnect rules | Close reason and cleanup evidence |
| Capacity | Per-user/socket limits, rate, queue, parser, and backpressure budgets | Boundary and flood tests |
| Observability | Sanitized fields and retention | Auth, policy, close, and abnormal-disconnect records |
Authenticate the upgrade and origin separately
An explicit origin check prevents a browser page on an untrusted site from reusing a cookie-backed session, but Origin is not an identity credential. Check the complete serialized value—scheme, host, and port—against a trusted configuration. Reject absent or null origins according to the endpoint’s documented client policy, and never infer approval from a hostname suffix. A non-browser client can construct an Origin header, so authentication still belongs in the endpoint.
If the server authenticates with a cookie, inspect the same-site and secure cookie settings and make the cross-site test meaningful. If it accepts a token, avoid putting the token in the URL, where proxies and access logs may retain it. A first-message token can be appropriate over wss://; until it verifies, the server should accept only the authentication message, impose a short deadline, and send no protected data. Treat an invalid or expired token as a terminal policy result rather than falling back to an anonymous mode that can reach privileged actions.
Authorize every message
Parse messages with a schema and an allowlist of action names. Resolve resource identifiers through the authenticated principal’s authorization check; do not let a client choose an arbitrary room, build, account, or file merely because it holds a valid socket. Keep user-authored text as data when a message is later passed to an agent or tool. For binary messages, enforce a byte limit and inspect format signatures instead of trusting a declared content type.
A message that repeats a state-changing operation may need a nonce, sequence number, or idempotency key. Reject duplicates according to the application contract and make the decision observable. Use protocol close code 1008 for a policy violation and 1009 when the message exceeds the negotiated or application limit, while keeping human-readable reasons short and free of secrets.
Bound long-lived resources
Set maximum frame or message size before parsing, and limit concurrent sockets per account or tenant. Rate-limit messages and bound internal queues so a fast producer cannot exhaust memory. Define backpressure behavior: pause reads, reject with a stable error, or close the connection. Heartbeats and idle timeouts detect dead peers, but they must not become an unbounded reconnect loop in the client.
Revalidate sessions during a long connection and close every socket associated with a session when the user logs out. The server should release subscriptions, timers, queues, and references on every close path. The browser client should distinguish a deliberate policy close from a transient network error before deciding whether to reconnect. MDN’s lifecycle guidance
covers the close and error events; use them to make cleanup and retry state explicit.
Test the real boundary
Use an integration harness that reaches the same proxy and upgrade handler as production. Include an approved origin with a disposable account, an untrusted origin with the same valid cookie, a missing or invalid credential, a stale session, a denied action, malformed JSON, an oversized text and binary message, a duplicate nonce, a flood, a dropped peer, logout during a live socket, and a reconnect after a policy close. Assert both the server decision and the absence of protected data in the untrusted client.
Do not treat a command-line client that sets an arbitrary Origin header as browser proof. Keep it for protocol and header tests, then run real browser contexts for cookie and cross-site behavior. Record endpoint policy ID, origin class, authentication result, action class, message-size bucket, close code, queue outcome, and cleanup result. Keep raw frames, tokens, cookies, and personal data out of routine logs.
Failure modes
The patch accepts every origin. A browser will attach ambient cookies to a cross-site handshake. Use an exact allowlist and test a controlled untrusted page.
Origin validation is treated as authentication. A permitted page can still contain an unauthenticated or underprivileged user. Keep identity and authorization checks separate.
The server sends data before first-message authentication. Hold protected subscriptions and responses until the authentication state is established or close the socket.
The client reconnects forever. Bound attempts and backoff, classify policy closes, and stop reconnecting when credentials or authorization are invalid.
Only the initial upgrade is logged. HTTP access logs miss message-level abuse. Emit sanitized authentication, authorization, validation, rate, and close events.
A frame-size check occurs after parsing. Count bytes before allocating or decoding. Use a parser and queue budget as well as a transport limit.
Logout leaves a socket alive. Maintain a session-to-connection index and close all associated channels when the session ends.
FAQ
Does wss:// make the channel safe?
No. It protects transport confidentiality and integrity when configured correctly. It does not choose origins, authenticate users, authorize actions, or limit resource use.
Is a valid cookie enough for a WebSocket connection?
No. The browser may send it from an untrusted page. Validate the handshake origin and authenticate the session, then authorize each message.
Can I use a wildcard origin for a public socket?
Only for a deliberately anonymous channel with no ambient credentials or protected data, and still document message and resource policy. A credentialed socket should use an explicit allowlist.
Should every message carry a token?
Not necessarily. Bind the socket to a validated session or token, then enforce action-level authorization. Use nonces or idempotency keys where replaying an action would cause a second side effect.
What should happen when authentication fails?
Send no protected data, record a sanitized reason, and close within the endpoint’s documented policy. Do not silently downgrade to a privileged anonymous mode.
Reader next step
Choose one WebSocket endpoint changed by a coding agent. Record its transport, complete origin allowlist, identity method, action permissions, message limits, replay rule, session-expiry behavior, reconnect policy, and cleanup owner. Add browser and protocol fixtures for an approved origin, an untrusted cookie-bearing page, failed authentication, denied action, malformed and oversized messages, duplicate operations, flood, logout, and policy close. Keep the patch blocked until the untrusted page cannot read protected data, every action is authorized, resource limits are enforced before parsing, and close paths release the socket’s state.