@walkhi/code-relax 0.1.0-beta.50 → 0.1.0-beta.59

package/dist/src/lan-socket-server.mjs

@@ -1,266 +1,338 @@
-import { EventEmitter } from 'node:events';
-import crypto from 'node:crypto';
-import { WebSocketServer, WebSocket } from 'ws';
-import timelineSync from '../shared/timeline-sync.cjs';
-import { createFileUploadSession, FILE_CHUNK_BYTES, MAX_FILE_BYTES, MAX_FILE_COUNT, MAX_TOTAL_BYTES } from './file-upload-session.mjs';
-import { FILE_READ_LIMIT } from './file-transfer-range.mjs';
-
-// One authenticated connection carries requests and explicitly owned subscriptions.
-// The dispatcher is shared business routing, not an HTTP loopback proxy.
-export function attachLanSocket(server, { token, dispatch, authorizeDevice = () => false, onDeviceAuthorizationsChanged, onDeviceConnected, uploadsRoot }) {
-  // Allow four individually valid images to reach the aggregate-size validator,
-  // so an oversized composition returns an error instead of dropping the connection.
-  const wss = new WebSocketServer({ noServer: true, maxPayload: 48 * 1024 * 1024, perMessageDeflate: false });
-  const uploadWss = new WebSocketServer({ noServer: true, maxPayload: 512 * 1024, perMessageDeflate: false });
-  const activeUploads = new Map();
-  const deviceConnections = new Map();
-  const stopWatching = onDeviceAuthorizationsChanged?.(() => {
-    for (const connection of deviceConnections.values()) {
-      if (!authorizeDevice(connection.clientId, connection.credential)) connection.revoke();
-    }
-  });
-  server.on('upgrade', (request, socket, head) => {
-    const origin = request.headers.origin;
-    const upload = request.url === '/api/file-transfer' && Boolean(uploadsRoot);
-    let allowed = request.url === '/api/socket' || upload;
-    // Packaged ArkWeb pages have an opaque ("null") origin; device authentication remains required.
-    if (origin && origin !== 'null') {
-      try {
-        const originUrl = new URL(origin);
-        const requestUrl = new URL(`http://${request.headers.host}`);
-        const nativeClient = request.headers['x-code-relax-native'] === '1';
-        allowed &&= ['http:', 'https:'].includes(originUrl.protocol) &&
-          (originUrl.host === request.headers.host || (nativeClient && originUrl.hostname === requestUrl.hostname));
-      }
-      catch { allowed = false; }
-    }
-    if (!allowed) { socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n'); return; }
-    const target = upload ? uploadWss : wss;
-    target.handleUpgrade(request, socket, head, ws => target.emit('connection', ws));
-  });
-  uploadWss.on('connection', ws => {
-    let authenticated = false, stopped = false, identity = '', upload, purpose, chunk;
-    let queued = 0;
-    let pending = Promise.resolve();
-    const authTimer = setTimeout(() => ws.close(1008, 'Authentication required'), 5000);
-    const reply = value => { if (!stopped && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(value)); };
-    ws.on('error', () => {});
-    const stop = () => {
-      if (stopped) return;
-      stopped = true;
-      deviceConnections.delete(ws);
-      clearTimeout(authTimer);
-      void pending.finally(async () => {
-        await upload?.close();
-        activeUploads.delete(ws);
-      });
-    };
-    ws.on('close', stop);
-    ws.on('message', (bytes, binary) => {
-      if (stopped || ws.readyState !== WebSocket.OPEN) return;
-      // Three upload chunks may be in flight, each with a header and binary frame.
-      if (++queued > 8) { stop(); ws.close(1013, 'File request queue exceeded'); return; }
-      pending = pending.then(async () => {
-        if (stopped || ws.readyState !== WebSocket.OPEN) return;
-        if (binary) {
-          if (!authenticated || purpose !== 'upload' || !chunk || bytes.length !== chunk.length) throw new Error('无效的文件分片');
-          const current = chunk; chunk = undefined;
-          reply(await upload.receive({ ...current, data: bytes })); return;
-        }
-        if (bytes.length > 16 * 1024 || chunk) throw new Error('无效的文件请求');
-        const message = JSON.parse(bytes.toString());
-        if (!authenticated) {
-          purpose = message.purpose;
-          if (!['upload', 'download'].includes(purpose)) throw new Error('文件通道用途无效');
-          if (message?.type === 'device-auth' && typeof message.clientId === 'string' &&
-              authorizeDevice(message.clientId, message.credential) === true) identity = `device:${message.clientId}`;
-          else if (token && message?.type === 'auth' && typeof message.token === 'string') {
-            const supplied = Buffer.from(message.token), expected = Buffer.from(token || '');
-            if (supplied.length === expected.length && crypto.timingSafeEqual(supplied, expected)) identity = 'local-token';
-          }
-          const same = [...activeUploads.values()].filter(item => item.identity === identity && item.purpose === purpose);
-          const uploads = [...activeUploads.values()].filter(item => item.purpose === 'upload').length;
-          if (!identity || same.length >= (purpose === 'upload' ? 1 : 3) || activeUploads.size >= 8 ||
-              (purpose === 'upload' && uploads >= 2)) throw new Error('文件身份无效或文件任务过多');
-          if (message.type === 'device-auth') deviceConnections.set(ws, {
-            clientId: message.clientId, credential: message.credential,
-            revoke() { stop(); ws.close(4401, 'Device authorization revoked'); },
-          });
-          activeUploads.set(ws, { identity, purpose }); authenticated = true; clearTimeout(authTimer);
-          if (message.type === 'device-auth') onDeviceConnected?.(message.clientId, message);
-          if (purpose === 'upload') upload = createFileUploadSession(uploadsRoot);
-          reply({ type: 'ready', version: 2, purpose, maxDownloadBytes: FILE_READ_LIMIT, maxFileBytes: MAX_FILE_BYTES, maxFileCount: MAX_FILE_COUNT,
-            maxTotalBytes: MAX_TOTAL_BYTES, chunkBytes: FILE_CHUNK_BYTES });
-          return;
-        }
-        if (purpose === 'download') {
-          if (message.type !== 'read' || typeof message.path !== 'string' || message.path.length > 12000 ||
-              !/^\/api\/(?:images\/[a-f0-9]{64}|files\/(?:local|[a-f0-9]{64})|code\/(?:image|binary)|desktop\/frames\/[a-f0-9]{32})(?:\?|$)/.test(message.path) || message.path.includes('#')) throw new Error('无效的文件读取请求');
-          await dispatch({ method: 'GET', url: message.path, headers: {}, socketRequest: true, fileTransfer: true }, {
-            json(status, body) { reply({ type: 'error', status, error: body?.error || '文件读取失败' }); },
-            filePart(metadata, data) {
-              if (stopped || ws.readyState !== WebSocket.OPEN) return;
-              if (!Buffer.isBuffer(data) || data.length > FILE_CHUNK_BYTES || ws.bufferedAmount > 1024 * 1024) throw new Error('文件接收过慢或分片无效');
-              reply({ type: 'part', ...metadata, length: data.length });
-              ws.send(data);
-            },
-          });
-          return;
-        }
-        if (message.type === 'chunk') {
-          if (!Number.isSafeInteger(message.length) || message.length < 1 || message.length > FILE_CHUNK_BYTES) throw new Error('文件分片大小无效');
-          chunk = message; return;
-        }
-        reply(await upload.receive(message));
-      }).catch(error => { reply({ type: 'error', error: error.message }); stop(); ws.close(1008, 'File request rejected'); })
-        .finally(() => { queued--; });
-    });
-  });
-  wss.on('connection', ws => {
-    let authenticated = false, alive = true, stopped = false;
-    const active = new Map();
-    const send = value => {
-      if (stopped || ws.readyState !== WebSocket.OPEN) return;
-      if (ws.bufferedAmount > 64 * 1024 * 1024) { ws.close(1013, 'Client too slow'); return; }
-      ws.send(JSON.stringify(value));
-    };
-    const authTimer = setTimeout(() => ws.close(1008, 'Authentication required'), 5000);
-    const heartbeat = setInterval(() => {
-      if (!alive) { ws.terminate(); return; }
-      alive = false; ws.ping();
-    }, 30000);
-    ws.on('pong', () => { alive = true; });
-    ws.on('error', () => {}); // close rejects requests and releases every subscription.
-    const stop = () => {
-      if (stopped) return;
-      stopped = true;
-      deviceConnections.delete(ws);
-      clearTimeout(authTimer); clearInterval(heartbeat);
-      for (const reply of active.values()) reply.end();
-      active.clear();
-    };
-    ws.on('close', stop);
-    ws.on('message', async (bytes, binary) => {
-      if (stopped || ws.readyState !== WebSocket.OPEN) return;
-      let message;
-      try { if (binary) throw new Error(); message = JSON.parse(bytes.toString()); }
-      catch { ws.close(1008, 'Invalid JSON'); return; }
-      if (!message || typeof message !== 'object') { ws.close(1008, 'Invalid message'); return; }
-      if (!authenticated) {
-        let accepted = false;
-        if (message.type === 'device-auth') {
-          accepted = authorizeDevice(message.clientId, message.credential) === true;
-        } else if (message.type === 'auth') {
-          const supplied = Buffer.from(typeof message.token === 'string' ? message.token : '');
-          const expected = Buffer.from(token || '');
-          accepted = supplied.length === expected.length && crypto.timingSafeEqual(supplied, expected);
-        }
-        if (!accepted) {
-          ws.close(1008, 'Authentication failed'); return;
-        }
-        if (message.type === 'device-auth') onDeviceConnected?.(message.clientId, message);
-        if (message.type === 'device-auth') deviceConnections.set(ws, {
-          clientId: message.clientId, credential: message.credential,
-          revoke() { stop(); ws.close(4401, 'Device authorization revoked'); },
-        });
-        authenticated = true; clearTimeout(authTimer); send({ type: 'ready', version: 1 }); return;
-      }
-      const { id, type } = message;
-      if (!Number.isSafeInteger(id) || id < 1) { ws.close(1008, 'Invalid request id'); return; }
-      if (type === 'response-ack') { active.get(id)?.acknowledge?.(message.batch); return; }
-      if (type === 'cancel') { active.get(id)?.end(); return; }
-      if (type === 'unsubscribe') { const reply = active.get(id); if (reply?.subscription) reply.end(); return; }
-      if (!['request', 'subscribe'].includes(type) || active.has(id)) { ws.close(1008, 'Invalid request'); return; }
-      const subscription = type === 'subscribe';
-      const path = message.path;
-      const isStream = typeof path === 'string' && /^\/api\/(?:usage-events|thread-events|turn-events|shared-recovery\/events|threads\/[^/?]+\/(?:events|dots-activity-events))(?:\?|$)/.test(path);
-      // Native recovery, usage, catalog, current chat, and the main Dot's sidebar
-      // share one station connection (including when viewing a delegated task).
-      if (active.size >= 32 || (subscription && [...active.values()].filter(r => r.subscription).length >= 5)) {
-        send({ type: 'response', id, status: 429, body: { error: '同时进行的请求过多' } }); return;
-      }
-      if (typeof path !== 'string' || !path.startsWith('/api/') || path.includes('#') ||
-          path.startsWith('/api/attachments/') || path === '/api/socket' || path === '/api/uploads' ||
-          subscription !== isStream || !['GET', 'POST', 'PUT', 'DELETE'].includes(message.method || 'GET') ||
-          (subscription && message.method && message.method !== 'GET') ||
-          (message.body !== undefined && (!message.body || typeof message.body !== 'object' || Array.isArray(message.body)))) {
-        send({ type: 'response', id, status: 400, body: { error: '无效的连接请求' } }); return;
-      }
-      const reply = new EventEmitter();
-      let waiting, batch = 0;
-      const sendPart = (pieces, pageEnd = false) => new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new Error('历史接收确认超时')), 20000);
-        waiting = { resolve, reject, timer, batch: ++batch };
-        send({ type: subscription ? 'event-part' : 'response-part', id, batch, pieces, ...(pageEnd ? { pageEnd: true } : {}) });
-      });
-      const sendTimeline = async (status, body, event) => {
-        if (event) batch = 0;
-        try {
-          for (const pieces of timelineSync.timelineBatches(body)) {
-            if (reply.writableEnded) return;
-            await sendPart(pieces);
-          }
-          if (!reply.writableEnded) {
-            send(event ? { type: 'event', id, event, streamed: true } : { type: 'response', id, status, streamed: true });
-            if (!event) reply.end();
-          }
-        } catch (error) {
-          if (!reply.writableEnded) {
-            send(event ? { type: 'event', id, event: 'bridge-error', data: { error: error.message } }
-              : { type: 'response', id, status: 500, body: { error: error.message } });
-            reply.end();
-          }
-        }
-      };
-      Object.assign(reply, {
-        subscription, headersSent: false, writableEnded: false, destroyed: false,
-        async historyPage(page) {
-          const parts = timelineSync.timelineBatches(page);
-          let part = parts.next();
-          while (!part.done) {
-            if (this.writableEnded) throw new Error('历史读取已取消');
-            const next = parts.next();
-            await sendPart(part.value, next.done);
-            part = next;
-          }
-        },
-        json(status, body) {
-          if (this.writableEnded) return;
-          if (status < 400 && body?.schemaVersion === 1 && Array.isArray(body.turns)) {
-            void sendTimeline(status, body); return;
-          }
-          send({ type: 'response', id, status, body }); this.end();
-        },
-        acknowledge(sequence) {
-          if (!waiting || sequence !== waiting.batch) return;
-          const completed = waiting; waiting = null; clearTimeout(completed.timer);
-          this.emit('progress'); completed.resolve();
-        },
-        startEvents() {
-          if (this.writableEnded) return;
-          this.headersSent = true; send({ type: 'subscribed', id });
-        },
-        event(event, data) {
-          if (this.writableEnded) return;
-          if (event === 'update' && data?.schemaVersion === 1) return sendTimeline(200, data, event);
-          send({ type: 'event', id, event, data });
-        },
-        end() {
-          if (this.writableEnded) return;
-          this.writableEnded = this.destroyed = true; active.delete(id);
-          if (waiting) { clearTimeout(waiting.timer); waiting.reject(new Error('历史读取已取消')); waiting = null; }
-          if (subscription) send({ type: 'end', id });
-          this.emit('close');
-        },
-      });
-      active.set(id, reply);
-      try { await dispatch({ method: message.method || 'GET', url: path, body: message.body || {}, headers: {}, socketRequest: true }, reply); }
-      catch (error) { reply.json(500, { error: error.message }); }
-    });
-  });
-  return { close() {
-    stopWatching?.();
-    for (const ws of wss.clients) ws.terminate(); wss.close();
-    for (const ws of uploadWss.clients) ws.terminate(); uploadWss.close();
-  } };
-}
+import { EventEmitter } from 'node:events';
+import crypto from 'node:crypto';
+import { WebSocketServer, WebSocket } from 'ws';
+import timelineSync from '../shared/timeline-sync.cjs';
+import { createFileUploadSession, FILE_CHUNK_BYTES, MAX_FILE_BYTES, MAX_FILE_COUNT, MAX_TOTAL_BYTES } from './file-upload-session.mjs';
+import { FILE_READ_LIMIT } from './file-transfer-range.mjs';
+
+// One authenticated connection carries requests and explicitly owned subscriptions.
+// The dispatcher is shared business routing, not an HTTP loopback proxy.
+export function attachLanSocket(server, { token, dispatch, authorizeDevice = () => false, onDeviceAuthorizationsChanged, onDeviceConnected,
+  onPhoneConnected, onPhoneDisconnected, uploadsRoot }) {
+  // Allow four individually valid images to reach the aggregate-size validator,
+  // so an oversized composition returns an error instead of dropping the connection.
+  const wss = new WebSocketServer({ noServer: true, maxPayload: 48 * 1024 * 1024, perMessageDeflate: false });
+  const uploadWss = new WebSocketServer({ noServer: true, maxPayload: 512 * 1024, perMessageDeflate: false });
+  const activeUploads = new Map();
+  const uploadSessions = new Map();
+  let closing = false;
+  const expireUpload = async (id, entry) => {
+    if (uploadSessions.get(id) !== entry) return;
+    uploadSessions.delete(id);
+    clearTimeout(entry.timer);
+    await entry.session.close();
+  };
+  const deviceConnections = new Map();
+  const stopWatching = onDeviceAuthorizationsChanged?.(() => {
+    for (const connection of deviceConnections.values()) {
+      if (!authorizeDevice(connection.clientId, connection.credential)) connection.revoke();
+    }
+  });
+  server.on('upgrade', (request, socket, head) => {
+    const origin = request.headers.origin;
+    const upload = request.url === '/api/file-transfer' && Boolean(uploadsRoot);
+    let allowed = request.url === '/api/socket' || upload;
+    // Packaged ArkWeb pages have an opaque ("null") origin; device authentication remains required.
+    if (origin && origin !== 'null') {
+      try {
+        const originUrl = new URL(origin);
+        const requestUrl = new URL(`http://${request.headers.host}`);
+        const nativeClient = request.headers['x-code-relax-native'] === '1';
+        allowed &&= ['http:', 'https:'].includes(originUrl.protocol) &&
+          (originUrl.host === request.headers.host || (nativeClient && originUrl.hostname === requestUrl.hostname));
+      }
+      catch { allowed = false; }
+    }
+    if (!allowed) { socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n'); return; }
+    const target = upload ? uploadWss : wss;
+    target.handleUpgrade(request, socket, head, ws => target.emit('connection', ws));
+  });
+  uploadWss.on('connection', ws => {
+    let authenticated = false, stopped = false, identity = '', upload, purpose, chunk, uploadEntry, uploadId;
+    let release, discardUpload = false;
+    const released = new Promise(resolve => { release = resolve; });
+    let queued = 0;
+    let pending = Promise.resolve();
+    const authTimer = setTimeout(() => ws.close(1008, 'Authentication required'), 5000);
+    const reply = value => { if (!stopped && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(value)); };
+    ws.on('error', () => {});
+    const stop = () => {
+      if (stopped) return;
+      stopped = true;
+      deviceConnections.delete(ws);
+      clearTimeout(authTimer);
+      void pending.finally(async () => {
+        activeUploads.delete(ws);
+        if (uploadEntry) {
+          uploadEntry.ws = null;
+          if (discardUpload || closing) await expireUpload(uploadId, uploadEntry);
+          else {
+            uploadEntry.timer = setTimeout(() => { void expireUpload(uploadId, uploadEntry); }, 5 * 60 * 1000);
+            uploadEntry.timer.unref();
+          }
+        }
+        release();
+      });
+    };
+    ws.on('close', stop);
+    ws.on('message', (bytes, binary) => {
+      if (stopped || ws.readyState !== WebSocket.OPEN) return;
+      // Three upload chunks may be in flight, each with a header and binary frame.
+      if (++queued > 8) { stop(); ws.close(1013, 'File request queue exceeded'); return; }
+      pending = pending.then(async () => {
+        if (stopped || ws.readyState !== WebSocket.OPEN) return;
+        if (binary) {
+          if (!authenticated || purpose !== 'upload' || !chunk || bytes.length !== chunk.length) throw new Error('无效的文件分片');
+          const current = chunk; chunk = undefined;
+          reply(await upload.receive({ ...current, data: bytes })); return;
+        }
+        if (bytes.length > 16 * 1024 || chunk) throw new Error('无效的文件请求');
+        const message = JSON.parse(bytes.toString());
+        if (!authenticated) {
+          purpose = message.purpose;
+          if (!['upload', 'download'].includes(purpose)) throw new Error('文件通道用途无效');
+          if (message?.type === 'device-auth' && typeof message.clientId === 'string' &&
+              authorizeDevice(message.clientId, message.credential) === true) identity = `device:${message.clientId}`;
+          else if (token && message?.type === 'auth' && typeof message.token === 'string') {
+            const supplied = Buffer.from(message.token), expected = Buffer.from(token || '');
+            if (supplied.length === expected.length && crypto.timingSafeEqual(supplied, expected)) {
+              identity = typeof message.relayClientId === 'string' && message.relayClientId.length <= 200
+                ? `relay:${message.relayClientId}` : 'local-token';
+            }
+          }
+          if (identity && purpose === 'upload') {
+            uploadId = message.uploadSessionId;
+            if (typeof uploadId !== 'string' || !/^[a-f0-9-]{36}$/.test(uploadId)) throw new Error('上传批次编号无效');
+            const entry = uploadSessions.get(uploadId);
+            if (entry) {
+              if (entry.identity !== identity) throw new Error('上传批次身份不一致');
+              if (entry.ws) { entry.ws.terminate(); await entry.released; }
+              if (uploadSessions.get(uploadId) !== entry) throw new Error('上传批次已失效，无法确认原批次状态');
+            } else if (message.resumeUpload) throw new Error('上传断点已过期或工作站已重启，请重新发送');
+          }
+          // Taking over a connection can await an in-flight disk write. The new
+          // socket and its authorization must still be live when that finishes.
+          if (stopped || closing || ws.readyState !== WebSocket.OPEN) return;
+          if (message.type === 'device-auth' && !authorizeDevice(message.clientId, message.credential)) throw new Error('设备授权已失效');
+          const same = [...activeUploads.values()].filter(item => item.identity === identity && item.purpose === purpose);
+          const uploads = [...activeUploads.values()].filter(item => item.purpose === 'upload').length;
+          if (!identity || same.length >= (purpose === 'upload' ? 1 : 3) || activeUploads.size >= 8 ||
+              (purpose === 'upload' && uploads >= 2)) throw new Error('文件身份无效或文件任务过多');
+          if (message.type === 'device-auth') deviceConnections.set(ws, {
+            clientId: message.clientId, credential: message.credential,
+            revoke() { discardUpload = true; stop(); ws.close(4401, 'Device authorization revoked'); },
+          });
+          activeUploads.set(ws, { identity, purpose }); authenticated = true; clearTimeout(authTimer);
+          if (message.type === 'device-auth') onDeviceConnected?.(message.clientId, message);
+          if (purpose === 'upload') {
+            uploadEntry = uploadSessions.get(uploadId);
+            if (!uploadEntry) {
+              if ([...uploadSessions.values()].filter(entry => !entry.committed).length >= 2) throw new Error('待完成上传批次过多，请稍后再试');
+              if (uploadSessions.size >= 32) {
+                const oldest = [...uploadSessions].find(([, entry]) => entry.committed && !entry.ws);
+                if (!oldest) throw new Error('上传批次过多，请稍后再试');
+                await expireUpload(...oldest);
+              }
+              if (stopped || closing || ws.readyState !== WebSocket.OPEN) return;
+              uploadEntry = { identity, session: createFileUploadSession(uploadsRoot) };
+              uploadSessions.set(uploadId, uploadEntry);
+            }
+            clearTimeout(uploadEntry.timer);
+            Object.assign(uploadEntry, { ws, released });
+            upload = uploadEntry.session;
+          }
+          reply({ type: 'ready', version: 3, purpose, maxDownloadBytes: FILE_READ_LIMIT, maxFileBytes: MAX_FILE_BYTES, maxFileCount: MAX_FILE_COUNT,
+            maxTotalBytes: MAX_TOTAL_BYTES, chunkBytes: FILE_CHUNK_BYTES, uploadSessionId: uploadId });
+          return;
+        }
+        if (purpose === 'download') {
+          if (message.type !== 'read' || typeof message.path !== 'string' || message.path.length > 12000 ||
+              !/^\/api\/(?:images\/[a-f0-9]{64}|files\/(?:local|[a-f0-9]{64})|code\/(?:image|binary)|desktop\/frames\/[a-f0-9]{32})(?:\?|$)/.test(message.path) || message.path.includes('#')) throw new Error('无效的文件读取请求');
+          await dispatch({ method: 'GET', url: message.path, headers: {}, socketRequest: true, fileTransfer: true }, {
+            json(status, body) { reply({ type: 'error', status, error: body?.error || '文件读取失败' }); },
+            filePart(metadata, data) {
+              if (stopped || ws.readyState !== WebSocket.OPEN) return;
+              if (!Buffer.isBuffer(data) || data.length > FILE_CHUNK_BYTES || ws.bufferedAmount > 1024 * 1024) throw new Error('文件接收过慢或分片无效');
+              reply({ type: 'part', ...metadata, length: data.length });
+              ws.send(data);
+            },
+          });
+          return;
+        }
+        if (message.type === 'chunk') {
+          if (!Number.isSafeInteger(message.length) || message.length < 1 || message.length > FILE_CHUNK_BYTES) throw new Error('文件分片大小无效');
+          chunk = message; return;
+        }
+        reply(await upload.receive(message));
+        if (message.type === 'commit') uploadEntry.committed = true;
+        if (message.type === 'cancel') {
+          await expireUpload(uploadId, uploadEntry);
+          uploadEntry = null;
+        }
+      }).catch(error => { reply({ type: 'error', error: error.message }); discardUpload = true; stop(); ws.close(1008, 'File request rejected'); })
+        .finally(() => { queued--; });
+    });
+  });
+  wss.on('connection', ws => {
+    let authenticated = false, alive = true, stopped = false;
+    let phone, reported = false;
+    const connectionId = crypto.randomUUID();
+    const active = new Map();
+    const send = value => {
+      if (stopped || ws.readyState !== WebSocket.OPEN) return;
+      if (ws.bufferedAmount > 64 * 1024 * 1024) { ws.close(1013, 'Client too slow'); return; }
+      ws.send(JSON.stringify(value));
+    };
+    const authTimer = setTimeout(() => ws.close(1008, 'Authentication required'), 5000);
+    const heartbeat = setInterval(() => {
+      if (!alive) { ws.terminate(); return; }
+      alive = false; ws.ping();
+    }, 30000);
+    ws.on('pong', () => { alive = true; });
+    ws.on('error', () => {}); // close rejects requests and releases every subscription.
+    const stop = () => {
+      if (stopped) return;
+      stopped = true;
+      deviceConnections.delete(ws);
+      clearTimeout(authTimer); clearInterval(heartbeat);
+      if (reported) onPhoneDisconnected?.(connectionId);
+      for (const reply of active.values()) reply.end();
+      active.clear();
+    };
+    ws.on('close', stop);
+    ws.on('message', async (bytes, binary) => {
+      if (stopped || ws.readyState !== WebSocket.OPEN) return;
+      let message;
+      try { if (binary) throw new Error(); message = JSON.parse(bytes.toString()); }
+      catch { ws.close(1008, 'Invalid JSON'); return; }
+      if (!message || typeof message !== 'object') { ws.close(1008, 'Invalid message'); return; }
+      if (!authenticated) {
+        let accepted = false;
+        if (message.type === 'device-auth') {
+          accepted = authorizeDevice(message.clientId, message.credential) === true;
+        } else if (message.type === 'auth') {
+          const supplied = Buffer.from(typeof message.token === 'string' ? message.token : '');
+          const expected = Buffer.from(token || '');
+          accepted = supplied.length === expected.length && crypto.timingSafeEqual(supplied, expected);
+        }
+        if (!accepted) {
+          ws.close(1008, 'Authentication failed'); return;
+        }
+        if (message.type === 'device-auth') phone = { clientId: message.clientId, mode: 'lan' };
+        else if (typeof message.relayClientId === 'string' && /^[\w-]{16,128}$/.test(message.relayClientId)) {
+          phone = { clientId: message.relayClientId, mode: 'self-relay' };
+        }
+        if (message.type === 'device-auth') onDeviceConnected?.(message.clientId, message);
+        if (message.type === 'device-auth') deviceConnections.set(ws, {
+          clientId: message.clientId, credential: message.credential,
+          revoke() { stop(); ws.close(4401, 'Device authorization revoked'); },
+        });
+        authenticated = true; clearTimeout(authTimer); send({ type: 'ready', version: 1 }); return;
+      }
+      const { id, type } = message;
+      if (!Number.isSafeInteger(id) || id < 1) { ws.close(1008, 'Invalid request id'); return; }
+      if (type === 'response-ack') { active.get(id)?.acknowledge?.(message.batch); return; }
+      if (type === 'cancel') { active.get(id)?.end(); return; }
+      if (type === 'unsubscribe') { const reply = active.get(id); if (reply?.subscription) reply.end(); return; }
+      if (!['request', 'subscribe'].includes(type) || active.has(id)) { ws.close(1008, 'Invalid request'); return; }
+      const subscription = type === 'subscribe';
+      const path = message.path;
+      const isStream = typeof path === 'string' && /^\/api\/(?:usage-events|thread-events|turn-events|shared-recovery\/events|threads\/[^/?]+\/(?:events|dots-activity-events))(?:\?|$)/.test(path);
+      // Native recovery, usage, catalog, current chat, and the main Dot's sidebar
+      // share one station connection (including when viewing a delegated task).
+      if (active.size >= 32 || (subscription && [...active.values()].filter(r => r.subscription).length >= 5)) {
+        send({ type: 'response', id, status: 429, body: { error: '同时进行的请求过多' } }); return;
+      }
+      if (typeof path !== 'string' || !path.startsWith('/api/') || path.includes('#') ||
+          path.startsWith('/api/attachments/') || path === '/api/socket' || path === '/api/uploads' ||
+          subscription !== isStream || !['GET', 'POST', 'PUT', 'DELETE'].includes(message.method || 'GET') ||
+          (subscription && message.method && message.method !== 'GET') ||
+          (message.body !== undefined && (!message.body || typeof message.body !== 'object' || Array.isArray(message.body)))) {
+        send({ type: 'response', id, status: 400, body: { error: '无效的连接请求' } }); return;
+      }
+      // Health probes, management and file sockets are not chat connections.
+      // Three message sources share this catalog/events entry point.
+      if (phone && !reported && /^\/api\/(?:threads(?:\?|$)|thread-events(?:\?|$)|threads\/[^/?]+\/(?:events|dots-activity-events)(?:\?|$))/.test(path)) {
+        reported = true;
+        onPhoneConnected?.(connectionId, phone.clientId, phone.mode);
+      }
+      const reply = new EventEmitter();
+      let waiting, batch = 0;
+      const sendPart = (pieces, pageEnd = false) => new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('历史接收确认超时')), 20000);
+        waiting = { resolve, reject, timer, batch: ++batch };
+        send({ type: subscription ? 'event-part' : 'response-part', id, batch, pieces, ...(pageEnd ? { pageEnd: true } : {}) });
+      });
+      const sendTimeline = async (status, body, event) => {
+        if (event) batch = 0;
+        try {
+          for (const pieces of timelineSync.timelineBatches(body)) {
+            if (reply.writableEnded) return;
+            await sendPart(pieces);
+          }
+          if (!reply.writableEnded) {
+            send(event ? { type: 'event', id, event, streamed: true } : { type: 'response', id, status, streamed: true });
+            if (!event) reply.end();
+          }
+        } catch (error) {
+          if (!reply.writableEnded) {
+            send(event ? { type: 'event', id, event: 'bridge-error', data: { error: error.message } }
+              : { type: 'response', id, status: 500, body: { error: error.message } });
+            reply.end();
+          }
+        }
+      };
+      Object.assign(reply, {
+        subscription, headersSent: false, writableEnded: false, destroyed: false,
+        async historyPage(page) {
+          const parts = timelineSync.timelineBatches(page);
+          let part = parts.next();
+          while (!part.done) {
+            if (this.writableEnded) throw new Error('历史读取已取消');
+            const next = parts.next();
+            await sendPart(part.value, next.done);
+            part = next;
+          }
+        },
+        json(status, body) {
+          if (this.writableEnded) return;
+          if (status < 400 && body?.schemaVersion === 1 && Array.isArray(body.turns)) {
+            void sendTimeline(status, body); return;
+          }
+          send({ type: 'response', id, status, body }); this.end();
+        },
+        acknowledge(sequence) {
+          if (!waiting || sequence !== waiting.batch) return;
+          const completed = waiting; waiting = null; clearTimeout(completed.timer);
+          this.emit('progress'); completed.resolve();
+        },
+        startEvents() {
+          if (this.writableEnded) return;
+          this.headersSent = true; send({ type: 'subscribed', id });
+        },
+        event(event, data) {
+          if (this.writableEnded) return;
+          if (event === 'update' && data?.schemaVersion === 1) return sendTimeline(200, data, event);
+          send({ type: 'event', id, event, data });
+        },
+        end() {
+          if (this.writableEnded) return;
+          this.writableEnded = this.destroyed = true; active.delete(id);
+          if (waiting) { clearTimeout(waiting.timer); waiting.reject(new Error('历史读取已取消')); waiting = null; }
+          if (subscription) send({ type: 'end', id });
+          this.emit('close');
+        },
+      });
+      active.set(id, reply);
+      try { await dispatch({ method: message.method || 'GET', url: path, body: message.body || {}, headers: {}, socketRequest: true }, reply); }
+      catch (error) { reply.json(500, { error: error.message }); }
+    });
+  });
+  return { close() {
+    closing = true;
+    stopWatching?.();
+    for (const ws of wss.clients) ws.terminate(); wss.close();
+    for (const ws of uploadWss.clients) ws.terminate(); uploadWss.close();
+    for (const [id, entry] of uploadSessions) if (!entry.ws) void expireUpload(id, entry);
+  } };
+}