Phase 12 batch 9: F03 — WS reconnect tokens + queue-broadcast scrubbing

- New persistent reconnectToken issued at /join, stashed on the queue
  entry, returned in the join response. Paid-reconnect now verifies
  it via timingSafeEqual; the old "paid players reconnect without
  any token" branch is gone.
- queue_update, pre-identify welcome, and post-identify welcome
  broadcasts no longer emit raw playerIds of peer entries. The
  post-identify welcome echoes only the caller's own playerId.
- SDK: new reconnectToken field on JoinResponse + WSIdentifyMessage.
  Client tracks hasIdentified, uses single-use wsToken on first
  identify and reconnectToken after that. Builds clean with tsc + tsup.

Tests: 192/192.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: back2matching

CHANGELOG.md

@@ -35,6 +35,7 @@ Multi-agent audit ran 2026-04-22; produced 43 ranked findings (see internal `.lo
 - **F16** — Webhook dispatcher now claims pending rows atomically via `claim_pending_webhooks(batch_size)` (`UPDATE … WHERE status='pending' FOR UPDATE SKIP LOCKED SET status='in_flight', locked_at=NOW() RETURNING *`). Rows locked longer than 2 minutes are automatically reclaimed as crash recovery. Previously two overlapping dispatcher ticks could both read the same pending rows and double-deliver.
 - **F17** — Entry-fee split (pool increment + ticket insert/update) now happens in a single `record_entry_fee(wallet, amount, tickets)` RPC (migration `20260422_005_entry_fee_atomic.sql`). Previously the two independent RPC calls could leave state inconsistent on partial failure — orphan pool money with no matching ticket row, or ticket row with no matching pool contribution.
 - **F10** — Jackpot-win bookkeeping is now atomic: pool deduction + `payouts` rows for each winner commit together via `record_jackpot_win_and_deduct(payout, tier, game_id, winners_jsonb)` (migration `20260422_006_jackpot_win_atomic.sql`). Previously `deductFromJackpotPoolForWin` committed first and `savePendingPayouts` ran only inside `processJackpotPayouts` — a crash in between left pool money gone with no record of who was owed. Fallback to the two-step path on RPC failure keeps rollout safe.
+- **F03** — WebSocket paid-reconnect now requires a persistent `reconnectToken` issued at `/join`. Broadcasts (`queue_update`, pre-identify spectator welcome, post-identify own welcome) no longer expose raw `playerId`s of other queue entries. Previously a spectator who saw a peer's playerId in a queue broadcast could disconnect and re-identify as that playerId in the "paid reconnect" branch to hijack the seat. The SDK now saves the token on `join()` and auto-switches from `wsToken` (single-use first identify) to `reconnectToken` (subsequent reconnects).
 
 Pre-Phase-12 items from this Unreleased window:
 

packages/snakey-sdk/src/client.ts

@@ -69,6 +69,10 @@ export class SnakeyClient {
   private config: Required<SnakeyConfig>;
   private ws: WebSocketLike | null = null;
   private wsToken: string | null = null;
+  // F03 — persistent reconnect token stashed from /join; used on any identify
+  // after the single-use wsToken has been consumed.
+  private reconnectToken: string | null = null;
+  private hasIdentified = false;
   private playerId: string | null = null;
   private handlers: SnakeyEventHandlers = {};
   private reconnectAttempts = 0;
@@ -146,6 +150,8 @@ export class SnakeyClient {
         headers: extraHeaders,
       });
       this.wsToken = response.wsToken;
+      this.reconnectToken = response.reconnectToken ?? null;
+      this.hasIdentified = false;
 
       if (this.config.autoConnect) {
         await this.connect(this.handlers);
@@ -161,6 +167,8 @@ export class SnakeyClient {
       headers: extraHeaders,
     });
     this.wsToken = response.wsToken;
+    this.reconnectToken = response.reconnectToken ?? null;
+    this.hasIdentified = false;
 
     if (this.config.autoConnect) {
       await this.connect(this.handlers);
@@ -575,12 +583,21 @@ export class SnakeyClient {
 
           this.ws.onopen = () => {
             this.reconnectAttempts = 0;
-            // Send identify message
+            // F03 — first identify uses the single-use wsToken; after that
+            // it's consumed server-side and we need the persistent reconnect
+            // token. `hasIdentified` flips to true on the first welcome.
             const identifyMsg: WSIdentifyMessage = {
               type: 'identify',
               playerId: this.playerId!,
-              wsToken: this.wsToken!,
             };
+            if (!this.hasIdentified && this.wsToken) {
+              identifyMsg.wsToken = this.wsToken;
+            } else if (this.reconnectToken) {
+              identifyMsg.reconnectToken = this.reconnectToken;
+            } else if (this.wsToken) {
+              // Fallback: server that predates F03 still accepts wsToken.
+              identifyMsg.wsToken = this.wsToken;
+            }
             this.ws!.send(JSON.stringify(identifyMsg));
 
             // Keepalive ping every 30s to prevent connection timeout
@@ -751,6 +768,9 @@ export class SnakeyClient {
   private handleMessage(msg: WSServerMessage): void {
     switch (msg.type) {
       case 'welcome':
+        // F03 — first welcome confirms the single-use wsToken has been
+        // consumed; any subsequent reconnect must use reconnectToken.
+        this.hasIdentified = true;
         this.handlers.onWelcome?.(msg);
         break;
       case 'countdown':

packages/snakey-sdk/src/types.ts

@@ -96,6 +96,14 @@ export interface JoinResponse {
   jackpotPool: string;
   yourTickets: number;
   wsToken: string;
+  /**
+   * F03 — Persistent reconnect token. The initial `wsToken` is single-use
+   * (consumed on the first identify); if the WS drops and the paid player
+   * wants to reclaim their seat, the identify message must carry this
+   * `reconnectToken` instead. Without it, spectators who learned a peer's
+   * playerId (old behaviour) could previously hijack their queue slot.
+   */
+  reconnectToken?: string;
   /** Phase 10 — true if a callbackUrl was registered */
   webhookRegistered?: boolean;
   /** Phase 10 — present only when the server generated the secret (agent did not supply one) */
@@ -365,7 +373,17 @@ export interface QuickPlayResult extends PlayResult {
 export interface WSIdentifyMessage {
   type: 'identify';
   playerId: string;
-  wsToken: string;
+  /**
+   * Single-use token from the /join response. Required on the first
+   * identify; consumed server-side on successful auth.
+   */
+  wsToken?: string;
+  /**
+   * F03 — Persistent reconnect token from the /join response. Required
+   * on any reconnect after the first identify (the single-use wsToken is
+   * gone by then). Send one or the other, not neither.
+   */
+  reconnectToken?: string;
 }
 
 export interface WSWelcomeMessage {

src/server.js

@@ -1439,8 +1439,10 @@ app.post('/join', joinLimiter, async (req, res) => {
     const jackpotStatus = await jackpot.getJackpotStatus();
     broadcast({
       type: 'queue_update',
+      // F03 — do not broadcast raw playerId; spectators could previously
+      // copy a paid player's playerId from this payload and use it in a
+      // token-less reconnect. displayName + position is enough for the UI.
       queue: queue.map(p => ({
-        playerId: p.playerId,
         displayName: p.displayName,
         position: queue.indexOf(p) + 1
       })),
@@ -1461,8 +1463,19 @@ app.post('/join', joinLimiter, async (req, res) => {
       recordWalletJoin(walletAddress);
     }
 
-    // Generate WebSocket auth token
+    // Generate WebSocket auth token.
+    // F03 — Also stash a persistent reconnect token on the queue entry.
+    // Previously any paid player's playerId was sufficient for a reconnect
+    // (isPaidReconnect allowed token-less identify), and queue_update
+    // broadcasts leaked those playerIds to every spectator. Now reconnects
+    // must present a token the server only gave to the original payer.
     const wsToken = generateWsAuthToken(playerId);
+    const reconnectToken = crypto.randomBytes(32).toString('hex');
+    const queuedForReconnect = queue.find(p => p.playerId === playerId);
+    if (queuedForReconnect) {
+      queuedForReconnect.reconnectToken = reconnectToken;
+      syncQueueToDB('join-reconnect-token');
+    }
 
     const allTickets = await getAllJackpotTickets();
 
@@ -1476,6 +1489,7 @@ app.post('/join', joinLimiter, async (req, res) => {
       jackpotPool: `$${jackpotStatus.currentPool.toFixed(2)}`,
       yourTickets: walletAddress ? (allTickets.find(t => t.wallet_address === walletAddress)?.tickets || 1) : 0,
       wsToken, // Token for authenticated WebSocket connection
+      reconnectToken, // F03 — presented in the identify message after a drop
       // Phase 10 — passive-agent extras
       webhookRegistered: !!callbackUrl,
       webhookSecret: callbackUrl ? resolvedWebhookSecret : undefined  // only returned if server generated it
@@ -1790,8 +1804,8 @@ app.post('/join/bulk', joinLimiter, async (req, res) => {
     const jackpotStatus = await jackpot.getJackpotStatus();
     broadcast({
       type: 'queue_update',
+      // F03 — see above: no raw playerId in broadcasts.
       queue: queue.map((p, idx) => ({
-        playerId: p.playerId,
         displayName: p.displayName,
         position: idx + 1
       })),
@@ -2592,10 +2606,12 @@ wss.on('connection', (ws, req) => {
     type: 'welcome',
     gameStatus: currentGame?.gameStatus || 'IDLE',
     queueSize: queue.length,
-    queue: queue.map(p => ({
-      playerId: p.playerId,
+    // F03 — pre-identify, the caller is treated as a spectator. Do not leak
+    // paid players' playerIds; displayName + colorIndex is enough for the UI.
+    queue: queue.map((p, idx) => ({
       displayName: p.displayName,
-      colorIndex: p.colorIndex
+      colorIndex: p.colorIndex,
+      position: idx + 1
     })),
     countdown: countdownTimer !== null ? countdownSecondsLeft : null,
     maxPlayers: MAX_PLAYERS,
@@ -2614,26 +2630,35 @@ wss.on('connection', (ws, req) => {
           const isInQueue = !!queuedPlayerForAuth;
 
           if (isInQueue) {
-            // Check if this is a paid player reconnecting (they already authenticated)
-            const isPaidReconnect = queuedPlayerForAuth.gamePoolContribution > 0 && queuedPlayerForAuth.disconnected;
-            
-            if (isPaidReconnect) {
-              // Paid player reconnecting - allow without token, they already paid
+            // F03 — Paid-reconnect flow now requires the reconnect token
+            // issued at /join (or re-issued during initial welcome). The old
+            // token-less isPaidReconnect branch let any spectator who had
+            // learned a paid player's playerId from a queue_update broadcast
+            // silently hijack that seat. The broadcast is also scrubbed of
+            // playerId below, but the token check is the real defense.
+            const providedReconnectToken = msg.reconnectToken || '';
+            const storedReconnectToken = queuedPlayerForAuth.reconnectToken || '';
+            const tokenMatchesReconnect = !!providedReconnectToken
+              && !!storedReconnectToken
+              && providedReconnectToken.length === storedReconnectToken.length
+              && crypto.timingSafeEqual(Buffer.from(providedReconnectToken), Buffer.from(storedReconnectToken));
+
+            if (tokenMatchesReconnect) {
               queuedPlayerForAuth.disconnected = false;
               queuedPlayerForAuth.disconnectedAt = null;
+              syncQueueToDB('ws-reconnect');
               authenticated = true;
-              log.info({ playerId: msg.playerId }, 'Paid player reconnected to queue');
+              log.info({ playerId: msg.playerId }, 'Paid player reconnected to queue (reconnect token OK)');
             } else if (!msg.wsToken || !verifyWsAuthToken(msg.playerId, msg.wsToken)) {
-              // New player or unpaid - must provide valid token
-              log.warn({ playerId: msg.playerId }, 'WebSocket auth failed - invalid token');
+              log.warn({ playerId: msg.playerId, hasReconnect: !!providedReconnectToken }, 'WebSocket auth failed - invalid token');
               ws.send(JSON.stringify({
                 type: 'error',
                 error: 'Invalid or expired authentication token'
               }));
               ws.close(4001, 'Unauthorized');
               return;
             } else {
-              // FIX 4: Delete token after successful verification (single-use)
+              // Single-use wsToken consumed on first identify.
               wsAuthTokens.delete(msg.playerId);
               authenticated = true;
             }
@@ -2643,15 +2668,21 @@ wss.on('connection', (ws, req) => {
           connections.set(playerId, { ws, displayName: msg.displayName, authenticated });
           log.debug({ playerId, displayName: msg.displayName, authenticated }, 'Player identified');
 
-          // Send current state including full queue
+          // Send current state including full queue. F03 — only the caller's
+          // own playerId is echoed back; other entries expose only displayName
+          // + colorIndex so a compromised WS client can't learn neighbors'
+          // playerIds.
           ws.send(JSON.stringify({
             type: 'welcome',
             gameStatus: currentGame?.gameStatus || 'IDLE',
             queueSize: queue.length,
-            queue: queue.map(p => ({
-              playerId: p.playerId,
+            yourPlayerId: playerId,
+            queue: queue.map((p, idx) => ({
               displayName: p.displayName,
-              colorIndex: p.colorIndex
+              colorIndex: p.colorIndex,
+              position: idx + 1,
+              // echo own playerId back so the frontend can identify itself
+              playerId: p.playerId === playerId ? p.playerId : undefined
             })),
             countdown: countdownTimer !== null ? countdownSecondsLeft : null,
             maxPlayers: MAX_PLAYERS,