Add WS auth handshake manual test script + CHANGELOG entry

Author: JSv4

CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Security
+
+- **WebSocket authentication tokens no longer travel in URL query strings**
+  (issue: JWT leakage via nginx logs, browser history, `Referer` headers,
+  Sentry breadcrumbs, and CDN/WAF logs). All WS connections now authenticate
+  via the standard `Sec-WebSocket-Protocol` handshake header
+  (`opencontracts.jwt.v1, <jwt>`). Token rotation is in-band via
+  `{"type":"AUTH","token":"..."}` frames — no socket churn on refresh. Hard
+  cutover: `?token=` URL parameters are stripped by the new middleware
+  (`config/websocket/middleware.py`) and ignored. `Authorization: Bearer`
+  headers are also no longer consulted for WS auth (browsers cannot set them
+  on the WebSocket constructor anyway). Stale browser tabs from before the
+  deploy must reload to recover.
+
+  - **`AuthHandshakeMixin`** (`config/websocket/auth_handshake.py`) — added
+    to all three consumers. Refuses user-pk swap mid-connection
+    (`USER_MISMATCH` → close 4002), re-runs resource permission checks on
+    refresh (`PERMISSION_REVOKED` → close 4003), supports server-nudged
+    refresh via `AUTH_REFRESH_REQUIRED` with a grace timer that closes 4001
+    on timeout.
+
+  - **Frontend `useWebSocketAuth` hook**
+    (`frontend/src/hooks/useWebSocketAuth.ts`) — single shared lifecycle
+    owner used by `useAgentChat`, `useNotificationWebSocket`, and
+    `CorpusChat`. Token rotation no longer reconnects the socket.
+
+  - **Removed**: deprecated `getDocumentQueryWebSocket` and
+    `getCorpusQueryWebSocket` URL helpers (forwarded to the unified
+    endpoint and now gone per the no-dead-code rule). Removed the
+    `autoReconnect` / `reconnectDelay` options on `useNotificationWebSocket`
+    — reconnect is owned by the shared hook.
+
+  - **Tests**: `opencontractserver/tests/test_websocket_auth.py` gains four
+    new test classes (`JWTAuthMiddlewareSubprotocolTests`,
+    `AuthHandshakeMixinTests`, `UnifiedAgentHandshakeTests`,
+    `ThreadUpdatesHandshakeTests`, `NotificationUpdatesHandshakeTests`) —
+    ~30 cases covering middleware, mixin, per-consumer integration,
+    user-mismatch refusal, and `?token=` regression. Frontend adds
+    `useWebSocketAuth.test.ts` and `websocketAuth.test.ts`; the existing
+    `useNotificationWebSocket.auth.test.ts` is rewritten as a no-token-in-URL
+    regression suite.
+
+  - **Manual test script**:
+    `docs/test_scripts/websocket-auth-handshake.md` — verifies subprotocol
+    transport, in-band refresh, user-pk-swap refusal, and DevTools sanity
+    check that the JWT never appears in the request URL.
+
 ### Added
 
 - **Loud guardrail against the `system_prompt=` foot-gun in pydantic-ai** (Issue #1451): `pydantic_ai.Agent` accepts both `system_prompt=` and `instructions=`, but the `system_prompt` value is *only* materialised into the model request when `message_history` is `None`. OpenContracts' `chat()` flow always persists the user's HUMAN message before calling `Agent.run()`, so `message_history` is never empty in practice and any `system_prompt=` argument is silently dropped — the LLM runs without any system instruction. CLAUDE.md pitfall #14 documented the workaround (use `instructions=`), but a future pydantic-ai bump that renames or re-precedences these parameters could re-introduce the regression silently.

docs/test_scripts/websocket-auth-handshake.md

@@ -0,0 +1,158 @@
+# Test: WebSocket Auth Handshake (subprotocol + in-band refresh)
+
+## Purpose
+
+Verify that:
+
+1. WebSocket auth carries the JWT only via `Sec-WebSocket-Protocol`, never URL.
+2. Token rotation is in-band and does not churn the socket.
+3. Old `?token=` transport no longer authenticates (hard cutover).
+4. User-pk swap on a live socket is refused.
+
+## Prerequisites
+
+- Local stack running: `docker compose -f local.yml up`.
+- A Django superuser with a known password. To create or reset one:
+
+  ```bash
+  docker compose -f local.yml exec django python manage.py shell -c "
+  from django.contrib.auth import get_user_model
+  u = get_user_model().objects.filter(is_superuser=True).first()
+  u.set_password('testpass123')
+  u.save()
+  print(f'Password set for {u.username}')
+  "
+  ```
+
+## Steps
+
+### 1. Mint a fresh JWT
+
+```bash
+TOKEN=$(docker compose -f local.yml exec django python manage.py shell -c "
+from graphql_jwt.shortcuts import get_token
+from django.contrib.auth import get_user_model
+print(get_token(get_user_model().objects.filter(is_superuser=True).first()))
+" | tr -d '\r' | tail -1)
+echo "$TOKEN"
+```
+
+**Expected:** A long JWT string (3 dot-separated segments).
+
+### 2. Regression — query-string token must be ignored
+
+```bash
+python3 -c "
+import asyncio, websockets
+async def main():
+    try:
+        async with websockets.connect(
+            f'ws://localhost:8000/ws/notification-updates/?token=$TOKEN'
+        ) as ws:
+            msg = await asyncio.wait_for(ws.recv(), 5)
+            print('UNEXPECTED frame:', msg)
+    except Exception as e:
+        print('OK — connection rejected:', type(e).__name__, e)
+asyncio.run(main())
+"
+```
+
+**Expected:** Connection rejected. `NotificationUpdatesConsumer` requires auth and the URL token is not consulted, so the consumer closes 4001 (or the handshake fails because no subprotocol was negotiated).
+
+### 3. Subprotocol-based handshake succeeds
+
+```bash
+python3 -c "
+import asyncio, json, websockets
+async def main():
+    async with websockets.connect(
+        'ws://localhost:8000/ws/notification-updates/',
+        subprotocols=['opencontracts.jwt.v1', '$TOKEN']
+    ) as ws:
+        msg = json.loads(await asyncio.wait_for(ws.recv(), 5))
+        print('Frame 1:', msg)
+        msg = json.loads(await asyncio.wait_for(ws.recv(), 5))
+        print('Frame 2:', msg)
+asyncio.run(main())
+"
+```
+
+**Expected:**
+- Frame 1: `{"type":"AUTH_OK", "user_id":..., "anonymous":false, "refreshed":false, ...}`
+- Frame 2: `{"type":"CONNECTED", ...}`
+
+### 4. In-band refresh (no reconnect)
+
+```bash
+python3 -c "
+import asyncio, json, websockets
+async def main():
+    async with websockets.connect(
+        'ws://localhost:8000/ws/notification-updates/',
+        subprotocols=['opencontracts.jwt.v1', '$TOKEN']
+    ) as ws:
+        await asyncio.wait_for(ws.recv(), 5)  # AUTH_OK
+        await asyncio.wait_for(ws.recv(), 5)  # CONNECTED
+        await ws.send(json.dumps({'type':'AUTH','token':'$TOKEN'}))
+        msg = json.loads(await asyncio.wait_for(ws.recv(), 5))
+        print('Refresh result:', msg)
+asyncio.run(main())
+"
+```
+
+**Expected:** `{"type":"AUTH_OK","refreshed":true,...}`. No reconnect occurred.
+
+### 5. User-pk swap is refused
+
+```bash
+OTHER_TOKEN=$(docker compose -f local.yml exec django python manage.py shell -c "
+from django.contrib.auth import get_user_model
+from graphql_jwt.shortcuts import get_token
+User = get_user_model()
+u, _ = User.objects.get_or_create(username='wsswaptest', defaults={'is_active': True})
+print(get_token(u))
+" | tr -d '\r' | tail -1)
+
+python3 -c "
+import asyncio, json, websockets
+async def main():
+    try:
+        async with websockets.connect(
+            'ws://localhost:8000/ws/notification-updates/',
+            subprotocols=['opencontracts.jwt.v1', '$TOKEN']
+        ) as ws:
+            await asyncio.wait_for(ws.recv(), 5)  # AUTH_OK
+            await asyncio.wait_for(ws.recv(), 5)  # CONNECTED
+            await ws.send(json.dumps({'type':'AUTH','token':'$OTHER_TOKEN'}))
+            msg = await asyncio.wait_for(ws.recv(), 5)
+            print('Swap response:', msg)
+            await asyncio.wait_for(ws.recv(), 5)
+    except websockets.ConnectionClosed as e:
+        print(f'OK — server closed (code {e.code}, reason: {e.reason!r})')
+asyncio.run(main())
+"
+```
+
+**Expected:** Server emits `{"type":"AUTH_FAILED","reason":"USER_MISMATCH"}` then closes 4002.
+
+### 6. Browser DevTools sanity
+
+1. `cd frontend && yarn start` and log in.
+2. Open Chrome DevTools → Network → WS filter.
+3. Inspect the `notification-updates/` WebSocket request:
+   - **Request URL:** must NOT contain `token=` query parameter.
+   - **Request Headers:** must show `Sec-WebSocket-Protocol: opencontracts.jwt.v1, <jwt>`.
+   - **Response Headers:** must show `Sec-WebSocket-Protocol: opencontracts.jwt.v1`.
+4. In the WS Messages tab, confirm the FIRST frame is `AUTH_OK`.
+5. (Optional) trigger an Auth0 silent renewal (or wait for one). Confirm the WS connection is NOT torn down — only a single `{"type":"AUTH","token":"..."}` frame should appear in the message list, followed by `AUTH_OK refreshed:true`.
+
+## Cleanup
+
+None required for steps 1-4. Step 5 creates a `wsswaptest` user; remove it if desired:
+
+```bash
+docker compose -f local.yml exec django python manage.py shell -c "
+from django.contrib.auth import get_user_model
+get_user_model().objects.filter(username='wsswaptest').delete()
+"
+```