Changeset 0.28.8 (#194)

docs/ARCHITECTURE.md

@@ -543,7 +543,18 @@ The appearance settings offer three modes: Light, Dark, System. System mode list
 - **Policies**: Boolean flags in `global_settings` table control registration, BYOK, team providers, etc.
 - **Audit**: All admin operations logged to `audit_log` with actor, action, resource type/ID, and diff
 - **Banner**: Environment classification banner configurable via admin settings (text, color, position)
-- **CORS**: Configurable allowed origins via env var
+- **CORS**: `CORS_ALLOWED_ORIGINS` env var controls which origins can make
+  cross-origin requests (HTTP and WebSocket). Comma-separated list of
+  allowed origins, e.g. `https://switchboard.corp,https://admin.corp`.
+  Behavior by environment:
+  - **Production** (`ENVIRONMENT=production`): if unset, defaults to
+    same-origin only (no `Access-Control-Allow-Origin` header). Set
+    explicitly to the domain(s) serving the frontend.
+  - **Development/test**: if unset, defaults to `*` (all origins).
+  - **Explicit `*`**: allowed but logs a startup warning. Not recommended
+    for production — restricts nothing and exposes the API to any origin.
+  The WebSocket upgrader's `CheckOrigin` respects the same setting.
+  Connections from origins not in the list are rejected at upgrade time.
 - **No sensitive terminology**: Banner system avoids classification-related terms for security compliance
 
 ## File Storage

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