@spotify-confidence/csr-common 0.18.10 → 0.18.11

package/src/uploader/create-uploader.ts

@@ -2,6 +2,7 @@ import type { CreateUploaderOptions, Frame, Uploader } from './types';
 import { ClientContext, collectUserAgentContext } from './client-context';
 import { isSessionActivityEvent } from '../session-activity';
 import { workerScript } from './worker/worker-script';
+import { WORKER_HASH } from './worker-hash';
 
 const STORAGE_TAB_ID = 'csr:tabId';
 const STORAGE_SESSION = 'csr:session';
@@ -18,6 +19,7 @@ interface PortLike {
 interface WelcomeMessage {
   type: 'welcome';
   result: { sessionId: string; sessionToken: string } | { skipRecording: true };
+  workerHash?: string;
   adoptedFromSessionId?: string;
   /** Worker-assigned fresh tabId because this tab is a duplicate of another live one. */
   newTabId?: string;
@@ -154,6 +156,12 @@ export async function createUploader(opts: CreateUploaderOptions): Promise<Uploa
       ? `tab: welcome (${'sessionId' in welcome.result ? `sessionId=${welcome.result.sessionId}` : 'skipRecording'})`
       : `tab: dead reason=${welcome.reason}`,
   );
+  if (welcome.type === 'welcome' && urlScheme === 'custom' && welcome.workerHash !== WORKER_HASH) {
+    log?.(
+      'tab: WORKER MISMATCH — the self-hosted confidence-worker.js does not match the installed SDK. ' +
+        'Copy the updated file from node_modules/@spotify-confidence/session-recording/dist/confidence-worker.js',
+    );
+  }
   if (welcome.type === 'dead') {
     throw new Error(`uploader: ${welcome.reason}`);
   }

package/src/uploader/index.ts

@@ -13,3 +13,4 @@ export {
  * SharedWorker sharing (per-document blob URLs defeat sharing).
  */
 export { workerScript } from './worker/worker-script';
+export { WORKER_HASH } from './worker-hash';

package/src/uploader/types.ts

@@ -10,11 +10,12 @@ export interface CreateUploaderOptions {
   apiUrl: string;
   /**
    * URL of the WebSocket ingest endpoint, including the path (e.g.
-   * `wss://recording-ws.confidence.dev/sessions/stream`) but **without** any query —
-   * the worker appends `?session_token=…`. Optional: when omitted the worker derives
-   * one from `apiUrl` by swapping `http(s)://` → `ws(s)://` and appending
-   * `/sessions/stream`. Set this when the init endpoint and the WS ingest live on
-   * different hosts (e.g. prod).
+   * `wss://recording-ws.confidence.dev/sessions/stream`). The worker sends the session
+   * token through the WebSocket subprotocol header. A `session_token` query parameter is
+   * rejected. Other query parameters are retained. Optional: when omitted the worker
+   * derives one from `apiUrl` by swapping `http(s)://` → `ws(s)://` and appending
+   * `/sessions/stream`. Set this when the init endpoint and the WS ingest live on different
+   * hosts (e.g. prod).
    */
   websocketUrl?: string;
   /** Per-tenant secret. Hashed to scope the SharedWorker so different secrets never share a session, and sent in the `initSession` request body. */
@@ -55,7 +56,7 @@ export interface CreateUploaderOptions {
   onTerminate?: (info: { reason: string }) => void;
   /**
    * Optional verbose tracer. Called on key tab- and worker-side events
-   * (hello/welcome, init-session URL, ws connect URL, retries, transitions).
+   * (hello/welcome, init-session URL, credential-free ws connect URL, retries, transitions).
    * Worker messages are forwarded over the port and tagged so you can tell them apart.
    */
   debugLogger?: (msg: string) => void;

package/src/uploader/worker/core.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from 'vitest';
 import { createMockPort, installMockFetch, installMockWsServer, jsonResponse } from '../../test-utils';
 
 const API_URL = 'https://api.example';
-const WS_URL = 'wss://api.example/sessions/stream?session_token=tok-1';
+const WS_URL = 'wss://api.example/sessions/stream';
 
 async function loadCore() {
   vi.resetModules();
@@ -27,6 +27,7 @@ const isType = (type: string) => (m: unknown) => (m as { type: string }).type ==
 interface WelcomeMessage {
   type: 'welcome';
   result: { sessionId: string; sessionToken: string } | { skipRecording: true };
+  workerHash?: string;
   newTabId?: string;
   resetCounter?: boolean;
   adoptedFromSessionId?: string;
@@ -37,15 +38,18 @@ interface DeadMessage {
 }
 
 describe('worker/core', () => {
-  function setupBackend(initBody: unknown = { sessionId: 'sess-1', sessionToken: 'tok-1' }) {
+  function setupBackend(
+    initBody: unknown = { sessionId: 'sess-1', sessionToken: 'tok-1' },
+    selectProtocol?: (protocols: string[], connectionIndex: number) => string,
+  ) {
     const fetchHarness = installMockFetch(() => jsonResponse(initBody));
-    const wsHarness = installMockWsServer(WS_URL);
+    const wsHarness = installMockWsServer(WS_URL, { selectProtocol });
     return { fetchHarness, wsHarness };
   }
 
   describe('first hello', () => {
     it('runs initSession + openTransport, then sends welcome', async () => {
-      const { fetchHarness } = setupBackend();
+      const { fetchHarness, wsHarness } = setupBackend();
       const { registerPort } = await loadCore();
       const port = createMockPort();
       registerPort(port.adapter);
@@ -59,6 +63,34 @@ describe('worker/core', () => {
         sessionId: 'sess-1',
         sessionToken: 'tok-1',
       });
+      expect(wsHarness.connections[0].url).toBe(WS_URL);
+      expect(wsHarness.protocolOffers).toEqual([['recording.v1', 'auth.tok-1']]);
+    });
+
+    it('includes workerHash in welcome when set on globalThis', async () => {
+      (globalThis as Record<string, unknown>).__WORKER_HASH__ = 'abc123';
+      setupBackend();
+      const { registerPort } = await loadCore();
+      const port = createMockPort();
+      registerPort(port.adapter);
+
+      port.tabSends(helloMessage());
+      const welcome = await port.next<WelcomeMessage>(isType('welcome'));
+
+      expect(welcome.workerHash).toBe('abc123');
+      delete (globalThis as Record<string, unknown>).__WORKER_HASH__;
+    });
+
+    it('workerHash is undefined when not set on globalThis', async () => {
+      setupBackend();
+      const { registerPort } = await loadCore();
+      const port = createMockPort();
+      registerPort(port.adapter);
+
+      port.tabSends(helloMessage());
+      const welcome = await port.next<WelcomeMessage>(isType('welcome'));
+
+      expect(welcome.workerHash).toBeUndefined();
     });
 
     it('replies with skipRecording when the backend opts out', async () => {
@@ -222,9 +254,119 @@ describe('worker/core', () => {
       expect(debug.received.some(isType('log'))).toBe(true);
       expect(quiet.received.some(isType('log'))).toBe(false);
     });
+
+    it('does not expose a session token through configured URLs', async () => {
+      const token = 'leaky-sensitive';
+      setupBackend({ sessionId: 'session-1', sessionToken: token });
+      const { registerPort } = await loadCore();
+      const port = createMockPort();
+      registerPort(port.adapter);
+
+      port.tabSends(
+        helloMessage({
+          websocketUrl: `${WS_URL}?session_token=${token}`,
+          sessionIdHint: 'session-1',
+          sessionTokenHint: token,
+          debugLogs: true,
+        }),
+      );
+      await port.next<DeadMessage>(isType('dead'));
+
+      const logs = port.received.filter(isType('log')).map(message => (message as { msg: string }).msg);
+      expect(logs.length).toBeGreaterThan(0);
+      for (const log of logs) {
+        expect(log).not.toContain(token);
+      }
+    });
   });
 
   describe('lifecycle after active', () => {
+    it('uses a fresh header credential when a session hint fails protocol negotiation', async () => {
+      const { fetchHarness, wsHarness } = setupBackend(
+        { sessionId: 'fresh-session', sessionToken: 'fresh-sensitive' },
+        (protocols, connectionIndex) => (connectionIndex === 0 ? '' : protocols[0]),
+      );
+      const { registerPort } = await loadCore();
+      const port = createMockPort();
+      registerPort(port.adapter);
+
+      port.tabSends(
+        helloMessage({
+          sessionIdHint: 'stale-session',
+          sessionTokenHint: 'stale-sensitive',
+          debugLogs: true,
+        }),
+      );
+      const welcome = await port.next<WelcomeMessage>(isType('welcome'));
+
+      expect(welcome.result).toEqual({
+        sessionId: 'fresh-session',
+        sessionToken: 'fresh-sensitive',
+      });
+      expect(fetchHarness.calls).toHaveLength(1);
+      expect(wsHarness.protocolOffers).toEqual([
+        ['recording.v1', 'auth.stale-sensitive'],
+        ['recording.v1', 'auth.fresh-sensitive'],
+      ]);
+      expect(wsHarness.connections.every(connection => connection.url === WS_URL)).toBe(true);
+      const logs = port.received.filter(isType('log')).map(message => (message as { msg: string }).msg);
+      expect(logs.some(log => log.includes('sessionIdHint=stale-session'))).toBe(true);
+      expect(logs).toContain('adopting sessionIdHint=stale-session');
+      expect(logs).toContain('init-session ok sessionId=fresh-session');
+      for (const log of logs) {
+        expect(log).not.toContain('stale-sensitive');
+        expect(log).not.toContain('c3RhbGUtc2Vuc2l0aXZl');
+        expect(log).not.toContain('fresh-sensitive');
+        expect(log).not.toContain('ZnJlc2gtc2Vuc2l0aXZl');
+      }
+    });
+
+    it('stops when a hinted session upgrades with recording.v1 then immediately closes with 4401', async () => {
+      const { fetchHarness, wsHarness } = setupBackend();
+      // The API checks session state after the upgrade. A valid token for a missing or
+      // closed session therefore opens successfully before the server rejects it.
+      wsHarness.server.on('connection', () => {
+        setTimeout(() => wsHarness.server.close({ code: 4401, reason: 'Unauthorized', wasClean: true }), 0);
+      });
+      const { registerPort } = await loadCore();
+      const port = createMockPort();
+      registerPort(port.adapter);
+
+      port.tabSends(helloMessage({ sessionIdHint: 'stale-session', sessionTokenHint: 'stale-sensitive' }));
+      const welcome = await port.next<WelcomeMessage>(isType('welcome'));
+      const dead = await port.next<DeadMessage>(isType('dead'));
+
+      expect(welcome.result).toEqual({ sessionId: 'stale-session', sessionToken: 'stale-sensitive' });
+      expect(dead.reason).toBe('close code=4401 wasClean=true');
+      expect(fetchHarness.calls).toHaveLength(0);
+      expect(wsHarness.protocolOffers).toEqual([['recording.v1', 'auth.stale-sensitive']]);
+      expect(wsHarness.connections).toHaveLength(1);
+      expect(wsHarness.connections[0].url).toBe(WS_URL);
+    });
+
+    it('stops after one failed header-authenticated reconnect', async () => {
+      const { fetchHarness, wsHarness } = setupBackend(undefined, (protocols, connectionIndex) =>
+        connectionIndex === 0 ? protocols[0] : '',
+      );
+      const { registerPort } = await loadCore();
+      const port = createMockPort();
+      registerPort(port.adapter);
+
+      port.tabSends(helloMessage({ debugLogs: true }));
+      await port.next<WelcomeMessage>(isType('welcome'));
+      const first = await wsHarness.waitForConnection();
+      first.close({ code: 1000, reason: 'drain', wasClean: true });
+
+      const dead = await port.next<DeadMessage>(isType('dead'));
+      expect(dead.reason).toBe('reconnect-failed');
+      expect(fetchHarness.calls).toHaveLength(1);
+      expect(wsHarness.protocolOffers).toEqual([
+        ['recording.v1', 'auth.tok-1'],
+        ['recording.v1', 'auth.tok-1'],
+      ]);
+      expect(wsHarness.connections.every(connection => connection.url === WS_URL)).toBe(true);
+    });
+
     it('broadcasts dead to all ports when the transport closes abruptly', async () => {
       const { wsHarness } = setupBackend();
       const { registerPort } = await loadCore();

package/src/uploader/worker/core.ts

@@ -2,6 +2,8 @@ import type { ClientContext } from '../client-context';
 import type { Client, Frame, Transport } from '../types';
 import { CsrClient } from './csr-client';
 
+const WORKER_HASH: string | undefined = (globalThis as Record<string, unknown>).__WORKER_HASH__ as string | undefined;
+
 /** Adapter so this module is unaware of whether it's running in a SharedWorker or a dedicated Worker. */
 export interface PortAdapter {
   postMessage(message: unknown): void;
@@ -173,7 +175,7 @@ function onHello(handle: PortHandle): void {
       };
       log(
         `hello received apiUrl=${handle.hello!.apiUrl} websocketUrl=${
-          handle.hello!.websocketUrl ?? '(derive)'
+          handle.hello!.websocketUrl ? '(configured)' : '(derive)'
         } sessionIdHint=${handle.hello!.sessionIdHint ?? '(none)'}`,
       );
       state = { phase: 'initializing' };
@@ -202,6 +204,7 @@ function onHello(handle: PortHandle): void {
       handle.port.postMessage({
         type: 'welcome',
         result: { skipRecording: true },
+        workerHash: WORKER_HASH,
       });
       return;
     case 'dead':
@@ -332,6 +335,7 @@ function flushPendingWelcomes(): void {
       handle.port.postMessage({
         type: 'welcome',
         result: { skipRecording: true },
+        workerHash: WORKER_HASH,
       });
     } else if (state.phase === 'dead') {
       handle.port.postMessage({ type: 'dead', reason: state.reason });
@@ -346,6 +350,7 @@ function sendActiveWelcome(handle: PortHandle, currentSessionId: string, current
   handle.port.postMessage({
     type: 'welcome',
     result: { sessionId: currentSessionId, sessionToken: currentSessionToken },
+    workerHash: WORKER_HASH,
     adoptedFromSessionId: adopted ? hint : undefined,
     newTabId,
     resetCounter: adopted || newTabId !== undefined,

package/src/uploader/worker/csr-client.test.ts

@@ -69,48 +69,63 @@ describe('CsrClient.initSession', () => {
 });
 
 describe('CsrClient.openTransport', () => {
-  it('derives a ws:// URL from an http:// apiUrl when websocketUrl is unset', async () => {
-    installMockWsServer('ws://api.example/sessions/stream?session_token=tok');
+  it('derives the unchanged ws:// endpoint and sends the token as a protocol', async () => {
+    const ws = installMockWsServer('ws://api.example/sessions/stream');
 
     const client = new CsrClient('http://api.example', 'secret', undefined);
-    await expect(client.openTransport('tok')).resolves.toBeDefined();
+    await expect(client.openTransport('tok-1')).resolves.toBeDefined();
+
+    expect(ws.connections[0].url).toBe('ws://api.example/sessions/stream');
+    expect(ws.protocolOffers).toEqual([['recording.v1', 'auth.tok-1']]);
   });
 
   it('derives a wss:// URL from an https:// apiUrl', async () => {
-    installMockWsServer('wss://api.example/sessions/stream?session_token=tok');
+    installMockWsServer('wss://api.example/sessions/stream');
 
     const client = new CsrClient('https://api.example', 'secret', undefined);
     await expect(client.openTransport('tok')).resolves.toBeDefined();
   });
 
-  it('uses websocketUrl verbatim when provided (split-host prod layout)', async () => {
-    installMockWsServer('wss://recording-ws.confidence.dev/sessions/stream?session_token=tok');
+  it('preserves unrelated query parameters in a configured websocketUrl', async () => {
+    const ws = installMockWsServer('wss://recording-ws.confidence.dev/sessions/stream?region=eu');
 
     const client = new CsrClient(
       'https://recording.confidence.dev',
       'secret',
       undefined,
-      'wss://recording-ws.confidence.dev/sessions/stream',
+      'wss://recording-ws.confidence.dev/sessions/stream?region=eu',
     );
     await expect(client.openTransport('tok')).resolves.toBeDefined();
+
+    expect(ws.connections[0].url).toBe('wss://recording-ws.confidence.dev/sessions/stream?region=eu');
   });
 
-  it('redacts session_token from debug log', async () => {
-    installMockWsServer('wss://api/sessions/stream?session_token=secret-tok');
+  it('keeps the credential out of the URL and debug log', async () => {
+    const ws = installMockWsServer('wss://api/sessions/stream');
 
     const logs: string[] = [];
     const client = new CsrClient('https://api', 'secret', undefined, undefined, msg => logs.push(msg));
-    await client.openTransport('secret-tok');
+    await client.openTransport('sensitive-token');
 
     expect(logs).toHaveLength(1);
-    expect(logs[0]).toContain('session_token=[REDACTED]');
-    expect(logs[0]).not.toContain('secret-tok');
+    expect(logs[0]).toBe('WebSocket connect wss://api/sessions/stream');
+    for (const value of [ws.connections[0].url, ...logs]) {
+      expect(value).not.toContain('sensitive-token');
+    }
   });
 
-  it('URL-encodes the session token', async () => {
-    installMockWsServer('wss://api/sessions/stream?session_token=tok%2Fwith%3Dspecials');
-
-    const client = new CsrClient('https://api', 'secret', undefined);
-    await expect(client.openTransport('tok/with=specials')).resolves.toBeDefined();
-  });
+  it.each(['wss://api/sessions/stream?session_token=legacy', 'wss://api/sessions/stream?region=eu&session_token='])(
+    'rejects a configured legacy credential before logging or connecting: %s',
+    async websocketUrl => {
+      const ws = installMockWsServer(websocketUrl);
+      const logs: string[] = [];
+      const client = new CsrClient('https://api', 'secret', undefined, websocketUrl, msg => logs.push(msg));
+
+      await expect(client.openTransport('sensitive-token')).rejects.toThrowError(
+        'WebSocket URL must not include a session token',
+      );
+      expect(logs).toEqual([]);
+      expect(ws.connections).toEqual([]);
+    },
+  );
 });

package/src/uploader/worker/csr-client.ts

@@ -1,6 +1,7 @@
 import type { ClientContext } from '../client-context';
 import type { Client, Transport } from '../types';
 import { WebSocketTransport } from './web-socket-transport';
+import { recordingProtocols } from './websocket-auth';
 
 /**
  * Single Client implementation that talks to the recording backend's REST + WS protocol.
@@ -45,10 +46,18 @@ export class CsrClient implements Client {
 
   async openTransport(sessionToken: string): Promise<Transport> {
     const wsBase = this.websocketUrl ?? `${this.toWsScheme(this.trimSlash(this.apiUrl))}/sessions/stream`;
-    const sep = wsBase.includes('?') ? '&' : '?';
-    const url = `${wsBase}${sep}session_token=${encodeURIComponent(sessionToken)}`;
-    this.log(`WebSocket connect ${url.replace(/session_token=[^&]*/, 'session_token=[REDACTED]')}`);
-    const transport = new WebSocketTransport(url);
+    let parsedUrl: URL;
+    try {
+      parsedUrl = new URL(wsBase);
+    } catch (_error) {
+      throw new Error('Invalid WebSocket URL');
+    }
+    if (parsedUrl.searchParams.has('session_token')) {
+      throw new Error('WebSocket URL must not include a session token');
+    }
+    const protocols = recordingProtocols(sessionToken);
+    this.log(`WebSocket connect ${wsBase}`);
+    const transport = new WebSocketTransport(wsBase, protocols);
     await transport.ready();
     return transport;
   }

package/src/uploader/worker/web-socket-transport.test.ts

@@ -1,12 +1,24 @@
-import { describe, expect, it, vi } from 'vitest';
+import { describe, expect, it, onTestFinished, vi } from 'vitest';
 import { installMockWsServer } from '../../test-utils';
 import { WebSocketTransport } from './web-socket-transport';
 
-const URL = 'ws://localhost:1234/sessions/stream?session_token=abc';
+const URL = 'ws://localhost:1234/sessions/stream';
+const PROTOCOLS = ['recording.v1', 'auth.sensitive-token'];
 
 describe('WebSocketTransport', () => {
   const setup = () => installMockWsServer(URL);
 
+  it('copies and supplies the protocols on the first connection', async () => {
+    const ws = setup();
+    const protocols = [...PROTOCOLS];
+    const t = new WebSocketTransport(URL, protocols);
+    protocols[0] = 'changed-after-construction';
+
+    await expect(t.ready()).resolves.toBeUndefined();
+
+    expect(ws.protocolOffers).toEqual([PROTOCOLS]);
+  });
+
   it('resolves ready() once the server accepts the connection', async () => {
     setup();
     const t = new WebSocketTransport(URL);
@@ -48,8 +60,8 @@ describe('WebSocketTransport', () => {
   });
 
   it('reconnects on a graceful drain (code 1000) and emits state changes', async () => {
-    const { waitForConnection } = setup();
-    const t = new WebSocketTransport(URL);
+    const { protocolOffers, waitForConnection } = setup();
+    const t = new WebSocketTransport(URL, PROTOCOLS);
     const states: boolean[] = [];
     t.onStateChange(({ connected }) => states.push(connected));
     await t.ready();
@@ -61,6 +73,61 @@ describe('WebSocketTransport', () => {
     // First open → no state event (welcome implies connected).
     // Drain → state(false). Reconnect open → state(true).
     await vi.waitFor(() => expect(states).toEqual([false, true]));
+    expect(protocolOffers).toEqual([PROTOCOLS, PROTOCOLS]);
+  });
+
+  it.each([
+    ['no protocol', ''],
+    ['the authentication protocol', PROTOCOLS[1]],
+  ])('rejects readiness and keeps buffered frames when the server selects %s', async (_case, selectedProtocol) => {
+    const { messages } = installMockWsServer(URL, { selectProtocol: () => selectedProtocol });
+    const t = new WebSocketTransport(URL, PROTOCOLS);
+    t.send({ tabId: 'tab-1', eventCounter: 0, data: 'must-not-send' });
+
+    const error = await t.ready().catch((caught: unknown) => caught);
+
+    expect(String(error)).toContain('initial-failed');
+    expect(String(error)).not.toContain(PROTOCOLS[1]);
+    expect(messages).toEqual([]);
+  });
+
+  it('uses the protocols on reconnect and never flushes frames after wrong selection', async () => {
+    const ws = installMockWsServer(URL, {
+      selectProtocol: (_protocols, connectionIndex) => (connectionIndex === 0 ? PROTOCOLS[0] : PROTOCOLS[1]),
+    });
+    const t = new WebSocketTransport(URL, PROTOCOLS);
+    const closeReasons: string[] = [];
+    t.onClose(({ reason }) => closeReasons.push(reason));
+    t.onStateChange(({ connected }) => {
+      if (!connected) {
+        t.send({ tabId: 'tab-1', eventCounter: 0, data: 'must-not-send' });
+      }
+    });
+    await t.ready();
+
+    const first = await ws.waitForConnection();
+    first.close({ code: 1000, reason: 'drain', wasClean: true });
+
+    await vi.waitFor(() => expect(closeReasons).toEqual(['reconnect-failed']));
+    expect(ws.protocolOffers).toEqual([PROTOCOLS, PROTOCOLS]);
+    expect(ws.messages).toEqual([]);
+  });
+
+  it('hides protocol values from WebSocket constructor failures', async () => {
+    const protocolFromBrowserError = PROTOCOLS[1];
+    class ThrowingWebSocket {
+      constructor() {
+        throw new Error(`synthetic constructor failure for ${protocolFromBrowserError}`);
+      }
+    }
+    onTestFinished(() => vi.unstubAllGlobals());
+    vi.stubGlobal('WebSocket', ThrowingWebSocket);
+
+    const t = new WebSocketTransport(URL, PROTOCOLS);
+    const error = await t.ready().catch((caught: unknown) => caught);
+
+    expect(String(error)).toContain('initial-failed');
+    expect(String(error)).not.toContain(protocolFromBrowserError);
   });
 
   it('fires onClose with reason on abrupt close after open', async () => {

package/src/uploader/worker/web-socket-transport.ts

@@ -19,8 +19,10 @@ export class WebSocketTransport implements Transport {
   /** Frames buffered while a (re)connect is in progress. */
   private pending: Frame[] = [];
   private readyPromise: Promise<void>;
+  private readonly protocols: string[];
 
-  constructor(private readonly url: string) {
+  constructor(private readonly url: string, protocols: string[] = []) {
+    this.protocols = [...protocols];
     this.readyPromise = new Promise<void>((resolve, reject) => {
       this.connect(false, resolve, reject);
     });
@@ -56,11 +58,23 @@ export class WebSocketTransport implements Transport {
   }
 
   private connect(isReconnect: boolean, onReady?: () => void, onReadyFail?: (err: Error) => void): void {
-    const ws = new WebSocket(this.url);
+    let ws: WebSocket;
+    try {
+      ws = new WebSocket(this.url, [...this.protocols]);
+    } catch (_error) {
+      this.failConnection(isReconnect, onReadyFail);
+      return;
+    }
     this.ws = ws;
     let opened = false;
 
     ws.onopen = () => {
+      const expectedProtocol = this.protocols[0];
+      if (expectedProtocol !== undefined && ws.protocol !== expectedProtocol) {
+        this.failConnection(isReconnect, onReadyFail);
+        ws.close(1000, 'protocol-mismatch');
+        return;
+      }
       opened = true;
       onReady?.();
       // Emit state on every successful open EXCEPT the very first one (welcome already
@@ -75,20 +89,11 @@ export class WebSocketTransport implements Transport {
     };
 
     ws.onclose = event => {
-      if (this.intentionallyClosed) return;
+      if (this.intentionallyClosed || this.dead) return;
       if (!opened) {
-        // Server rejected the connection before it opened (e.g. unknown session).
-        const stage = isReconnect ? 'reconnect' : 'initial';
-        const reason = `${stage}-failed code=${event.code}`;
-        if (onReadyFail) {
-          // First attempt — surface the failure to whoever is awaiting `ready()` so they
-          // can decide whether to recover (e.g. fall back to a fresh initSession).
-          onReadyFail(new Error(reason));
-          this.dead = true;
-        } else {
-          // Reconnect failed; the consumer is past `ready()` and only learns about it via onClose.
-          this.die(reason);
-        }
+        // Browsers do not expose the HTTP status for a failed WebSocket handshake. Keep
+        // this failure generic and do not infer an authentication result from close 1006.
+        this.failConnection(isReconnect, onReadyFail);
         return;
       }
       // The WS opened and is now closing. Distinguish graceful drain (retry) from app
@@ -106,6 +111,16 @@ export class WebSocketTransport implements Transport {
     };
   }
 
+  private failConnection(isReconnect: boolean, onReadyFail?: (err: Error) => void): void {
+    const reason = isReconnect ? 'reconnect-failed' : 'initial-failed';
+    if (onReadyFail) {
+      this.dead = true;
+      onReadyFail(new Error(reason));
+    } else {
+      this.die(reason);
+    }
+  }
+
   private die(reason: string): void {
     this.dead = true;
     this.onCloseCb?.({ reason });

package/src/uploader/worker/websocket-auth.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { recordingProtocols } from './websocket-auth';
+
+describe('recordingProtocols', () => {
+  it('offers the issued token unchanged, including dots, hyphens, and underscores', () => {
+    expect(recordingProtocols('cGF5bG9hZA.c2lnbmF0dXJl_-')).toEqual(['recording.v1', 'auth.cGF5bG9hZA.c2lnbmF0dXJl_-']);
+  });
+
+  it('allows a token at the 4096-character limit', () => {
+    expect(recordingProtocols('a'.repeat(4096))[1]).toHaveLength('auth.'.length + 4096);
+  });
+
+  it('rejects a token longer than 4096 characters without exposing it', () => {
+    const token = `sensitive-${'a'.repeat(4097)}`;
+    expect(() => recordingProtocols(token)).toThrowError('Session token is too long for WebSocket authentication');
+    try {
+      recordingProtocols(token);
+    } catch (error) {
+      expect(String(error)).not.toContain(token);
+    }
+  });
+
+  it.each(['', 'sensitive/token', 'sensitive=token', 'sensitive token', 'tøken-☃', 'sensitive\n'])(
+    'rejects unsupported token characters without exposing the token',
+    token => {
+      expect(() => recordingProtocols(token)).toThrowError('Invalid session token for WebSocket authentication');
+    },
+  );
+});

package/src/uploader/worker/websocket-auth.ts

@@ -0,0 +1,15 @@
+export const RECORDING_PROTOCOL = 'recording.v1';
+
+const AUTH_PROTOCOL_PREFIX = 'auth.';
+const MAX_TOKEN_LENGTH = 4096;
+
+export function recordingProtocols(sessionToken: string): string[] {
+  if (sessionToken.length > MAX_TOKEN_LENGTH) {
+    throw new Error('Session token is too long for WebSocket authentication');
+  }
+  // Issued tokens are unpadded Base64URL parts joined by a dot; dev tokens are UUIDs.
+  if (!sessionToken || /[^A-Za-z0-9._-]/.test(sessionToken)) {
+    throw new Error('Invalid session token for WebSocket authentication');
+  }
+  return [RECORDING_PROTOCOL, `${AUTH_PROTOCOL_PREFIX}${sessionToken}`];
+}