Changeset 0.28.8 (#194)

docs/ICD/websocket.md

@@ -6,10 +6,41 @@ WebSocket connection belonging to the recipient user.
 
 ### Connection
 
+**Preferred (v0.28.8+): Ticket exchange**
+
+```
+POST /api/v1/ws/ticket     (authenticated via JWT Bearer header)
+→ 200  { "ticket": "<opaque-hex-string>" }
+```
+
+Then connect with the opaque ticket:
+
+```
+ws://{host}{BASE_PATH}/ws?ticket={ticket}
+```
+
+Tickets are single-use (deleted on validation), 30-second TTL, and
+stored in server memory. This avoids exposing the JWT in server logs,
+proxy logs, and browser history.
+
+**Legacy (deprecated): JWT query parameter**
+
 ```
 ws://{host}{BASE_PATH}/ws?token={access_token}
 ```
 
+Still accepted for backward compatibility with pre-v0.28.8 clients.
+Server logs a deprecation warning on each legacy connection. Will be
+removed in a future version.
+
+**Non-browser clients** may also use the `Authorization: Bearer <jwt>`
+header on the upgrade request.
+
+**Origin validation:** The WebSocket upgrader validates the `Origin`
+header against `CORS_ALLOWED_ORIGINS`. Connections from unlisted
+origins are rejected at upgrade time. In development (no
+`CORS_ALLOWED_ORIGINS` set), all origins are accepted.
+
 **Lifecycle:**
 - Server sends WebSocket-level `ping` frames every 54 seconds
 - Client must respond with `pong` within 60 seconds or disconnection