security(ws): authenticate and origin-check Copilot WebSocket upgrades

[pjdoland]

Summary

WebsocketCopilotHandler subclassed raw tornado.websocket.WebSocketHandler with an empty open() body: no @authenticated, no explicit check_origin, no check_xsrf_cookie, no audit log. The handler drives the chat tool-execution pipeline (run_command_in_embedded_terminal, file edits, notebook edits, MCP tool calls), so it is the highest-privilege endpoint in the extension. Tornado's WebSocketHandler default check_origin enforces same-host only, which leaves the endpoint reachable from any cross-origin tab the browser allows to send WS upgrades, and from any in-network process on a multi-tenant Jupyter Server.

Solution

Adopt Jupyter's first-party WebSocket pattern, matching KernelWebsocketHandler and friends:

class WebsocketCopilotHandler(WebSocketMixin, websocket.WebSocketHandler, JupyterHandler):
    @ws_authenticated
    def open(self):
        log.info("Copilot WS upgrade accepted user=%r origin=%r", ...)

• WebSocketMixin (jupyter_server.base.websocket) contributes the upgrade-aware check_origin that respects the server's allow_origin / allow_origin_pat traitlets, plus the ping/pong keepalive Jupyter expects on every WS handler. The default WebSocketHandler check_origin (any same-host origin) is shadowed.
• JupyterHandler contributes identity-provider integration (current_user, check_xsrf_cookie) so cookies and tokens are resolved against the same machinery as the REST routes.
• ws_authenticated (jupyter_server.auth.decorator) raises HTTPError(403) on unauthenticated upgrades. tornado.web.authenticated would redirect(login_url) which is meaningless on a WS upgrade.

Accepted upgrades log the resolved user identity and origin so an incident can be correlated with the negotiated identity (Jupyter's identity provider returns a User dataclass; the getattr(..., "username", ...) fallback handles custom providers that return a string).

Testing

• tests/test_ws_handler_auth.py: pins inheritance from both WebSocketMixin and JupyterHandler; MRO ordering so WebSocketMixin.check_origin wins and JupyterHandler.check_xsrf_cookie provides the upgrade-aware XSRF check; behavioral assertion that open() raises HTTPError(403) when current_user is falsy; and a caplog assertion that an accepted upgrade emits the audit line with the resolved user identity. A regression that removes the decorator, reorders the bases, or drops the audit line fails one of these.
• Test scaffolds in tests/test_image_context.py and tests/test_websocket_handler_integration.py updated: the mocked Application now exposes the settings / transforms / ui_methods / ui_modules keys that JupyterHandler.set_default_headers walks during __init__.
• Full suites: pytest 779 pass, tsc clean, prettier clean, jest clean.

Risks / follow-ups

• Behavior change: cross-origin browser tabs that previously could open the WS without an allow_origin entry will see a 403. Same-origin (the labextension's normal flow) is unaffected. Operators running with --ServerApp.allow_origin='*' are unchanged: the WS upgrade now follows the same allow-list logic the REST endpoints already follow.
• No-auth dev mode: --ServerApp.token='' continues to work because Jupyter's identity provider supplies an anonymous User for which current_user is truthy.
• JupyterHub trusted-proxy: the inherited WebSocketMixin.check_origin checks skip_check_origin() which the proxy-trust path sets, so existing Hub deployments are unaffected.
• Audit log on reject: 403s are logged by Jupyter at WARNING already; a richer log_exception override is tracked separately if operators ask for more context (User-Agent, remote_ip, route) on rejected upgrades.
• Subprotocol negotiation: the handler doesn't override select_subprotocol. The default (echo none, ignore Sec-WebSocket-Protocol headers) is fine for the chat payload but worth a defensive no-op in a future hardening pass.

The admin guide HTTP-API surface section is updated to call out the new posture so an operator reading the docs knows the chat WS endpoint inherits the same gates as the REST handlers.