@qzsy/dsh-bridge 3.2.0 → 3.2.1

package/lib/saas/tunnel-client.mjs

@@ -1,764 +1,769 @@
-// SaaS 隧道客户端（控制通道协议 v2）——独立实现，不继承任何第三方隧道类。
-//
-// 契约见 docs/architecture/saas-tunnel.md §6 与 packages/tunnel-protocol/src/index.ts：
-//   C→S hello → S→C hello-ack → 转发 request/response(-start|chunk|end) 与 ws-*；
-//   v2 新增 heartbeat/heartbeat-ack、route-update、drain；未知 type 静默忽略。
-//   close 4001/4003/4004 为终态；4000/4002 可重连。
-import { WebSocket } from 'ws';
-import { request as httpRequest } from 'node:http';
-import { connect as netConnect } from 'node:net';
-
-export const SAAS_HEARTBEAT_INTERVAL_MS = 30_000;
-export const SAAS_HEARTBEAT_MAX_MISSED = 3;
-export const SAAS_HANDSHAKE_TIMEOUT_MS = 15_000;
-export const SAAS_RECONNECT_BASE_DELAY_MS = 1000;
-export const SAAS_RECONNECT_MAX_DELAY_MS = 60_000;
-export const SAAS_DEFAULT_GATEWAY_PATH = '/_gw/connect';
-export const SAAS_MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
-export const SAAS_TERMINAL_CLOSE_CODES = new Set([4001, 4003, 4004]);
-export const SAAS_TERMINAL_ERROR_CODES = new Set(['auth_failed', 'revoked', 'bad_request', 'unsupported_version', 'time_exhausted']);
-
-const HOP_BY_HOP = new Set(['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade']);
-const TUNNEL_HEADER = 'x-dsh-internal-tunnel';
-
-export class SaasTunnelError extends Error {
-  constructor(code, message, { terminal = false, closeCode = 0, cause } = {}) {
-    super(message, cause === undefined ? undefined : { cause });
-    this.name = 'SaasTunnelError';
-    this.code = code;
-    this.terminal = terminal;
-    this.closeCode = closeCode;
-  }
-}
-
-export function buildSaasConnectUrl({ gatewayUrl, gatewayPath = SAAS_DEFAULT_GATEWAY_PATH, deviceToken } = {}) {
-  let url;
-  try {
-    url = new URL(String(gatewayUrl ?? '').trim());
-  } catch {
-    throw new SaasTunnelError('invalid_gateway_url', `SaaS 网关地址不合法: ${gatewayUrl}`, { terminal: true });
-  }
-  if (url.protocol === 'http:') url.protocol = 'ws:';
-  else if (url.protocol === 'https:') url.protocol = 'wss:';
-  else if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
-    throw new SaasTunnelError('invalid_gateway_url', 'SaaS 网关地址只支持 ws/wss/http/https', { terminal: true });
-  }
-  let path = String(gatewayPath || SAAS_DEFAULT_GATEWAY_PATH);
-  if (!path.startsWith('/')) path = '/' + path;
-  const basePath = url.pathname.replace(/\/+$/, '');
-  url.pathname = (basePath && basePath !== '/' ? basePath : '') + path;
-  url.search = '';
-  url.hash = '';
-  if (deviceToken) url.searchParams.set('device_token', String(deviceToken));
-  return url.toString();
-}
-
-export function pickRoutePublicUrl(routes) {
-  const list = Array.isArray(routes) ? routes.filter((route) => route && typeof route === 'object') : [];
-  const host = list.find((route) => route.kind === 'host' && typeof route.url === 'string' && route.url);
-  const any = list.find((route) => typeof route.url === 'string' && route.url);
-  return String((host ?? any)?.url ?? '');
-}
-
-function sanitizeHeaders(headers) {
-  const out = {};
-  for (const [name, value] of Object.entries(headers ?? {})) {
-    if (HOP_BY_HOP.has(name.toLowerCase()) || value === undefined) continue;
-    out[name.toLowerCase()] = value;
-  }
-  return out;
-}
-
-export class SaasTunnelClient {
-  constructor(options = {}) {
-    const {
-      gatewayUrl = '',
-      gatewayPath = SAAS_DEFAULT_GATEWAY_PATH,
-      deviceToken = null,
-      tokenProvider = null,
-      localPort,
-      internalTunnelSecret = '',
-      protocol = 'v2',
-      heartbeatIntervalMs = SAAS_HEARTBEAT_INTERVAL_MS,
-      heartbeatMaxMissed = SAAS_HEARTBEAT_MAX_MISSED,
-      maxResponseBytes = SAAS_MAX_RESPONSE_BYTES,
-      reconnectBaseDelayMs = SAAS_RECONNECT_BASE_DELAY_MS,
-      reconnectMaxDelayMs = SAAS_RECONNECT_MAX_DELAY_MS,
-      maxReconnectAttempts = Number.POSITIVE_INFINITY,
-      random = Math.random,
-      deviceInfo = {},
-      sseStreaming = true,
-      onHelloAck = null,
-      onStateChange = null,
-      onRouteUpdate = null,
-      onDrain = null,
-      onDrainComplete = null,
-      logger = console,
-    } = options;
-
-    if (!localPort) throw new Error('localPort is required');
-    this.gatewayUrl = String(gatewayUrl);
-    this.gatewayPath = gatewayPath || SAAS_DEFAULT_GATEWAY_PATH;
-    this.deviceToken = deviceToken;
-    this.tokenProvider = typeof tokenProvider === 'function'
-      ? tokenProvider
-      : (deviceToken ? async () => deviceToken : null);
-    this.localPort = Number(localPort);
-    this.internalTunnelSecret = String(internalTunnelSecret ?? '');
-    this.protocol = protocol === 'auto' ? 'auto' : 'v2';
-    this.protocolVersion = 2;
-    this.heartbeatIntervalMs = Math.max(10, Number(heartbeatIntervalMs) || SAAS_HEARTBEAT_INTERVAL_MS);
-    this.heartbeatMaxMissed = Math.max(1, Number(heartbeatMaxMissed) || SAAS_HEARTBEAT_MAX_MISSED);
-    this.maxResponseBytes = Math.max(1024, Number(maxResponseBytes) || SAAS_MAX_RESPONSE_BYTES);
-    this.reconnectBaseDelayMs = Math.max(10, Number(reconnectBaseDelayMs) || SAAS_RECONNECT_BASE_DELAY_MS);
-    this.reconnectMaxDelayMs = Math.max(this.reconnectBaseDelayMs, Number(reconnectMaxDelayMs) || SAAS_RECONNECT_MAX_DELAY_MS);
-    this.maxReconnectAttempts = Number.isFinite(maxReconnectAttempts) ? Math.max(0, maxReconnectAttempts) : Number.POSITIVE_INFINITY;
-    this.random = typeof random === 'function' ? random : Math.random;
-    this.deviceInfo = deviceInfo ?? {};
-    this.sseStreaming = sseStreaming !== false;
-    this.onHelloAck = onHelloAck;
-    this.onStateChange = onStateChange;
-    this.onRouteUpdate = onRouteUpdate;
-    this.onDrain = onDrain;
-    this.onDrainComplete = onDrainComplete;
-    this.logger = logger ?? console;
-
-    this._connected = false;
-    this._state = 'idle';
-    this._stateDetail = '';
-    this._terminal = false;
-    this._draining = false;
-    this._manuallyClosed = false;
-    this._connecting = false;
-    this._ws = null;
-    this._awaitingHandshake = false;
-    this._handshakeResolve = null;
-    this._handshakeReject = null;
-    this._handshakeTimer = null;
-    this._heartbeatTimer = null;
-    this._heartbeatAckPending = false;
-    this._missedHeartbeatAcks = 0;
-    this._reconnectTimer = null;
-    this._reconnectAttempts = 0;
-    this._routes = [];
-    this._routeRev = 0;
-    this.tunnel = null;
-    this.publicUrl = '';
-    this.lastError = null;
-    this.lastAckAt = null;
-    this.limits = null;
-    this.features = null;
-    this.serverTime = null;
-    this.gateSecret = '';
-    this._inFlight = new Set();
-    this._localWs = new Map();
-    this._bytesIn = 0;
-    this._bytesOut = 0;
-    this._drainTimer = null;
-    this._suppressReconnect = false;
-  }
-
-  get connected() { return this._connected; }
-  get state() { return this._state; }
-  get stateDetail() { return this._stateDetail; }
-  get draining() { return this._draining; }
-  get terminal() { return this._terminal; }
-  get routes() { return this._routes; }
-  get routeRev() { return this._routeRev; }
-  get reconnectAttempts() { return this._reconnectAttempts; }
-
-  _setState(state, detail = '') {
-    this._state = state;
-    this._stateDetail = detail;
-    try { this.onStateChange?.({ state, detail, connected: this._connected, publicUrl: this.publicUrl }); } catch {}
-  }
-
-  async connect() {
-    if (this._connected || this._connecting || this._manuallyClosed) return;
-    this._connecting = true;
-    this._setState('connecting', '正在连接 SaaS 网关…');
-    try {
-      const token = await this._acquireToken();
-      await this._openSocket(token);
-      this._connected = true;
-      this._terminal = false;
-      this._manuallyClosed = false;
-      this._reconnectAttempts = 0;
-      this.lastError = null;
-      this.lastAckAt = Date.now();
-      this._startHeartbeat();
-      this._setState('ready', this.publicUrl ? `SaaS 隧道已建立 (${this.publicUrl})` : 'SaaS 隧道已建立');
-    } catch (err) {
-      this._connected = false;
-      this._stopHeartbeat();
-      const detail = err?.message ?? String(err);
-      this.lastError = detail;
-      const terminal = err?.terminal === true || this._terminal;
-      if (terminal) {
-        this._terminal = true;
-        this._setState('error', detail);
-      } else if (!this._manuallyClosed && !this._draining) {
-        this._scheduleReconnect(detail);
-      }
-      throw err;
-    } finally {
-      this._connecting = false;
-    }
-  }
-
-  async _acquireToken() {
-    if (!this.tokenProvider) {
-      throw new SaasTunnelError('missing_device_credentials', '尚未绑定设备，请先在面板获取设备码并绑定', { terminal: true });
-    }
-    const result = await this.tokenProvider();
-    const token = typeof result === 'string' ? result : result?.token;
-    if (!token) throw new SaasTunnelError('missing_device_token', '设备令牌获取失败，请重新绑定', { terminal: true });
-    if (result && typeof result === 'object') {
-      if (result.gateway?.url) this.gatewayUrl = result.gateway.url;
-      if (result.gateway?.path) this.gatewayPath = result.gateway.path;
-      if (result.tunnel) this.tunnel = result.tunnel;
-    }
-    this.deviceToken = String(token);
-    return this.deviceToken;
-  }
-
-  _openSocket(deviceToken) {
-    return new Promise((resolve, reject) => {
-      let ws;
-      try {
-        ws = new WebSocket(buildSaasConnectUrl({
-          gatewayUrl: this.gatewayUrl,
-          gatewayPath: this.gatewayPath,
-          deviceToken,
-        }), {
-          handshakeTimeout: 10_000,
-          headers: { authorization: `Bearer ${deviceToken}` },
-          perMessageDeflate: false,
-        });
-      } catch (err) {
-        reject(new SaasTunnelError('invalid_gateway_url', err?.message ?? String(err), { terminal: true, cause: err }));
-        return;
-      }
-      this._ws = ws;
-      this._awaitingHandshake = true;
-      this._handshakeResolve = resolve;
-      this._handshakeReject = reject;
-      this._handshakeTimer = setTimeout(() => {
-        if (!this._awaitingHandshake) return;
-        try { ws.terminate(); } catch {}
-        this._settleHandshake(new SaasTunnelError('handshake_timeout', 'SaaS 网关握手超时（15s 内未收到 hello-ack）'));
-      }, SAAS_HANDSHAKE_TIMEOUT_MS);
-
-      ws.on('open', () => {
-        this.logger?.info?.('SaaS tunnel WebSocket open');
-        this._sendHello();
-      });
-      ws.on('message', (data) => this._onMessage(data));
-      ws.on('close', (code, reason) => this._onClose(code, reason));
-      ws.on('error', (err) => {
-        this.logger?.error?.(`SaaS tunnel WebSocket error: ${err?.message ?? err}`);
-        if (this._awaitingHandshake) this._settleHandshake(err instanceof Error ? err : new Error(String(err)));
-      });
-    });
-  }
-
-  _settleHandshake(error) {
-    if (!this._awaitingHandshake) return;
-    this._awaitingHandshake = false;
-    if (this._handshakeTimer) {
-      clearTimeout(this._handshakeTimer);
-      this._handshakeTimer = null;
-    }
-    const resolve = this._handshakeResolve;
-    const reject = this._handshakeReject;
-    this._handshakeResolve = null;
-    this._handshakeReject = null;
-    if (error) reject?.(error);
-    else resolve?.();
-  }
-
-  _sendHello() {
-    const device = {};
-    for (const key of ['name', 'platform', 'hostname', 'pluginVersion', 'dshVersion']) {
-      const value = this.deviceInfo?.[key];
-      if (value !== undefined && value !== null && String(value).trim()) device[key] = String(value).trim();
-    }
-    if (!device.name) device.name = device.hostname || 'DSH Remote Tunnel';
-    if (!device.platform) device.platform = process.platform ?? 'unknown';
-    this._send({
-      type: 'hello',
-      v: 2,
-      device,
-      caps: { sseStreaming: this.sseStreaming, wsFrames: true, maxResponseBytes: this.maxResponseBytes },
-      ts: Math.floor(Date.now() / 1000),
-    });
-  }
-
-  _onMessage(data) {
-    let msg;
-    try {
-      msg = JSON.parse(typeof data === 'string' ? data : data.toString());
-    } catch {
-      return;
-    }
-    if (!msg || typeof msg !== 'object') return;
-
-    if (msg.type === 'hello-ack') {
-      if (this._awaitingHandshake) this._handleHelloAck(msg);
-      else if (msg.ok === false) this.logger?.warn?.('ignoring duplicate hello-ack');
-      return;
-    }
-    if (msg.type === 'ready' && this._awaitingHandshake && this.protocol === 'auto') {
-      this.protocolVersion = 1;
-      this.publicUrl = String(msg.publicUrl ?? '');
-      this._connected = true;
-      this._settleHandshake();
-      return;
-    }
-    switch (msg.type) {
-      case 'heartbeat-ack':
-        this._heartbeatAckPending = false;
-        this._missedHeartbeatAcks = 0;
-        this.lastAckAt = Date.now();
-        if (msg.serverTime) this.serverTime = msg.serverTime;
-        if (Array.isArray(msg.actions) && msg.actions.includes('drain') && !this._draining) {
-          this._startDrain({ deadline: Date.now() + this.heartbeatIntervalMs * 3 });
-        }
-        return;
-      case 'route-update':
-        this._routeRev = Number(msg.rev) || this._routeRev;
-        this._applyRoutes(msg.routes);
-        try { this.onRouteUpdate?.({ routes: this._routes, rev: this._routeRev, publicUrl: this.publicUrl }); } catch {}
-        return;
-      case 'drain':
-        this._handleDrain(msg);
-        return;
-      case 'ready':
-        if (this._connected && !this._routes.some((route) => route.kind === 'host')) {
-          if (msg.publicUrl) this.publicUrl = String(msg.publicUrl);
-        }
-        return;
-      case 'ping':
-        this._send({ type: 'pong', ts: Date.now() });
-        return;
-      case 'request':
-        this._handleRequest(msg);
-        return;
-      case 'ws-open':
-        this._handleWsOpen(msg);
-        return;
-      case 'ws-frame':
-        this._handleWsFrame(msg);
-        return;
-      case 'ws-close':
-        this._handleWsClose(msg);
-        return;
-      case 'pong':
-        return;
-      default:
-        // 未知 type 必须静默忽略（v1 前后兼容）
-        return;
-    }
-  }
-
-  _handleHelloAck(msg) {
-    if (msg.ok === false) {
-      const code = String(msg.error?.code ?? 'bad_request');
-      const message = String(msg.error?.message ?? '');
-      const detail = `SaaS 网关拒绝握手: ${message || code} (${code})`;
-      const terminal = SAAS_TERMINAL_ERROR_CODES.has(code);
-      this.lastError = detail;
-      if (terminal) this._terminal = true;
-      this._setState(terminal ? 'error' : 'connecting', detail);
-      try { this._ws?.terminate(); } catch {}
-      this._settleHandshake(new SaasTunnelError(code, detail, { terminal }));
-      return;
-    }
-    this.protocolVersion = Number(msg.v) || 2;
-    if (msg.tunnel) this.tunnel = { publicId: String(msg.tunnel.publicId ?? ''), name: String(msg.tunnel.name ?? '') };
-    this.limits = msg.limits ?? null;
-    this.features = msg.features ?? null;
-    // 网关为每条控制连接随机下发信任密钥；gate 用它验 x-qzsy-gate 的 HMAC。
-    this.gateSecret = typeof msg.gate?.secret === 'string' && /^[0-9a-f]{64}$/i.test(msg.gate.secret)
-      ? msg.gate.secret.toLowerCase()
-      : '';
-    this.serverTime = msg.serverTime ?? null;
-    if (this.limits?.heartbeatMs) this.heartbeatIntervalMs = Math.max(10, Number(this.limits.heartbeatMs) || this.heartbeatIntervalMs);
-    if (this.limits?.maxResponseBytes) this.maxResponseBytes = Math.max(1024, Number(this.limits.maxResponseBytes) || this.maxResponseBytes);
-    this._applyRoutes(msg.routes);
-    this._connected = true;
-    this._reconnectAttempts = 0;
-    this.lastAckAt = Date.now();
-    try { this.onHelloAck?.(msg); } catch {}
-    this._settleHandshake();
-  }
-
-  _applyRoutes(routes) {
-    const list = Array.isArray(routes) ? routes.filter((route) => route && typeof route === 'object') : [];
-    this._routes = list;
-    const picked = pickRoutePublicUrl(list);
-    if (picked) this.publicUrl = picked;
-  }
-
-  _handleDrain(msg) {
-    let deadline = Number(msg?.deadline);
-    if (!Number.isFinite(deadline) || deadline <= 0) deadline = Date.now() + this.heartbeatIntervalMs * 3;
-    else if (deadline < 1e12) deadline *= 1000;
-    this._startDrain({ deadline });
-  }
-
-  _startDrain({ deadline }) {
-    if (this._draining) return;
-    this._draining = true;
-    this._setState('draining', 'SaaS 网关下线中，等待在途请求结束');
-    try { this.onDrain?.({ deadline }); } catch {}
-    const finish = () => this._finishDrain();
-    if (this._inFlight.size === 0) {
-      this._drainTimer = setTimeout(finish, 20);
-    } else {
-      const poll = () => {
-        if (!this._draining) return;
-        if (this._inFlight.size === 0 || Date.now() >= deadline) return finish();
-        this._drainTimer = setTimeout(poll, Math.min(100, Math.max(10, deadline - Date.now())));
-      };
-      this._drainTimer = setTimeout(poll, 20);
-      setTimeout(() => { if (this._draining) finish(); }, Math.max(0, deadline - Date.now()) + 1000).unref?.();
-    }
-  }
-
-  _finishDrain() {
-    if (!this._draining) return;
-    this._draining = false;
-    this.gateSecret = '';
-    this._suppressReconnect = true;
-    if (this._drainTimer) { clearTimeout(this._drainTimer); this._drainTimer = null; }
-    this._connected = false;
-    this._stopHeartbeat();
-    this._cleanupLocalWs();
-    this._inFlight.clear();
-    this.lastError = 'SaaS 网关已下线（drain），隧道已优雅断开';
-    this._setState('closed', this.lastError);
-    try { this.onDrainComplete?.({ detail: this.lastError }); } catch {}
-    this._closeSocket(1000, 'drain');
-  }
-
-  _handleRequest(msg) {
-    const requestId = String(msg?.requestId ?? '');
-    if (!requestId) return;
-    if (this._draining) {
-      this._send({ type: 'response', requestId, statusCode: 503, headers: { 'content-type': 'text/plain; charset=utf-8' }, body: Buffer.from('tunnel is draining').toString('base64') });
-      return;
-    }
-    this._inFlight.add(requestId);
-    if (typeof msg.body === 'string') this._bytesIn += Math.floor((msg.body.length * 3) / 4);
-    const headers = sanitizeHeaders(msg.headers);
-    headers.host = `127.0.0.1:${this.localPort}`;
-    if (this.internalTunnelSecret) headers[TUNNEL_HEADER] = this.internalTunnelSecret;
-
-    const upstream = httpRequest({
-      host: '127.0.0.1',
-      port: this.localPort,
-      method: String(msg.method ?? 'GET'),
-      path: String(msg.path ?? '/'),
-      headers,
-    }, (res) => {
-      const responseHeaders = sanitizeHeaders(res.headers);
-      const isSse = String(res.headers['content-type'] ?? '').toLowerCase().includes('text/event-stream');
-      if (isSse && this.sseStreaming) {
-        this._send({ type: 'response-start', requestId, statusCode: res.statusCode ?? 200, headers: responseHeaders });
-        res.on('data', (chunk) => {
-          this._bytesOut += chunk.length;
-          this._send({ type: 'response-chunk', requestId, body: Buffer.from(chunk).toString('base64') });
-        });
-        res.on('end', () => {
-          this._send({ type: 'response-end', requestId });
-          this._inFlight.delete(requestId);
-        });
-        res.on('error', () => {
-          this._send({ type: 'response-end', requestId });
-          this._inFlight.delete(requestId);
-        });
-        return;
-      }
-      const chunks = [];
-      let total = 0;
-      let finished = false;
-      const fail = (code, text) => {
-        if (finished) return;
-        finished = true;
-        this._inFlight.delete(requestId);
-        this._send({ type: 'response', requestId, statusCode: code, headers: { 'content-type': 'text/plain; charset=utf-8' }, body: Buffer.from(text).toString('base64') });
-      };
-      res.on('data', (chunk) => {
-        total += chunk.length;
-        if (total > this.maxResponseBytes) {
-          fail(502, `Response too large for tunnel (>${Math.round(this.maxResponseBytes / 1024 / 1024)}MB cap)`);
-          res.destroy();
-          return;
-        }
-        chunks.push(chunk);
-      });
-      res.on('end', () => {
-        if (finished) return;
-        finished = true;
-        this._inFlight.delete(requestId);
-        const body = Buffer.concat(chunks).toString('base64');
-        this._bytesOut += Buffer.concat(chunks).length;
-        this._send({ type: 'response', requestId, statusCode: res.statusCode ?? 200, headers: responseHeaders, body });
-      });
-      res.on('error', () => fail(502, 'Response Error'));
-    });
-    upstream.on('error', (err) => {
-      this._inFlight.delete(requestId);
-      this._send({ type: 'response', requestId, statusCode: 502, headers: { 'content-type': 'text/plain; charset=utf-8' }, body: Buffer.from(`Bad Gateway: ${err?.message ?? err}`).toString('base64') });
-    });
-    if (typeof msg.body === 'string' && msg.body) upstream.write(Buffer.from(msg.body, 'base64'));
-    upstream.end();
-  }
-
-  // ── WebSocket 原始帧转发 ────────────────────────────────────────────────
-  // 网关契约（apps/gateway/src/proxy-ws.ts）：ws-frame 的 data 是**原始 WebSocket 帧字节**
-  // （含 opcode/mask/分片），不是消息 payload。因此这里用裸 TCP 完成 Upgrade 握手后
-  // 原样透传字节，绝不能再经 ws 库二次成帧。
-  _handleWsOpen(msg) {
-    const wsId = String(msg?.wsId ?? '');
-    if (!wsId) return;
-    if (this._draining) {
-      this._send({ type: 'ws-accept', wsId, statusCode: 503, statusMessage: 'Service Unavailable', replyHeaders: { 'content-type': 'text/plain' } });
-      return;
-    }
-    // Upgrade 请求必须原样保留 connection/upgrade/sec-websocket-*（不能套用普通
-    // HTTP 请求的逐跳过滤），只重写 Host 并补本地隧道标记。
-    const requestHeaders = {};
-    for (const [name, value] of Object.entries(msg.headers ?? {})) {
-      const lower = name.toLowerCase();
-      if (lower === 'host' || lower === TUNNEL_HEADER || value === undefined) continue;
-      requestHeaders[lower] = value;
-    }
-    requestHeaders.host = `127.0.0.1:${this.localPort}`;
-    // 网关按 hop-by-hop 规则剥掉了 Upgrade/Connection，这里必须补回，否则本机
-    // WebSocket 升级请求不合法（表现为浏览器收到非 101）。
-    requestHeaders.connection = requestHeaders.connection ?? 'Upgrade';
-    requestHeaders.upgrade = requestHeaders.upgrade ?? 'websocket';
-    if (this.internalTunnelSecret) requestHeaders[TUNNEL_HEADER] = this.internalTunnelSecret;
-
-    const socket = netConnect({ host: '127.0.0.1', port: this.localPort });
-    const state = { socket, buffer: Buffer.alloc(0), upgraded: false, closed: false, headerSent: false };
-    this._localWs.set(wsId, state);
-
-    const fail = (code, message) => {
-      if (state.closed) return;
-      state.closed = true;
-      this._send({ type: 'ws-accept', wsId, statusCode: code, statusMessage: message, replyHeaders: { 'content-type': 'text/plain' } });
-      try { socket.destroy(); } catch {}
-      this._localWs.delete(wsId);
-    };
-
-    socket.on('connect', () => {
-      const path = String(msg.path ?? '/');
-      const lines = [`GET ${path.startsWith('/') ? path : '/' + path} HTTP/1.1`];
-      for (const [name, value] of Object.entries(requestHeaders)) {
-        if (Array.isArray(value)) for (const item of value) lines.push(`${name}: ${item}`);
-        else if (value !== undefined) lines.push(`${name}: ${value}`);
-      }
-      lines.push('', '');
-      state.headerSent = true;
-      socket.write(lines.join('\r\n'));
-    });
-
-    socket.on('data', (chunk) => {
-      if (state.closed) return;
-      if (!state.upgraded) {
-        state.buffer = Buffer.concat([state.buffer, chunk]);
-        const separator = state.buffer.indexOf('\r\n\r\n');
-        if (separator === -1) {
-          if (state.buffer.length > 64 * 1024) fail(502, 'Bad Gateway');
-          return;
-        }
-        const head = state.buffer.subarray(0, separator).toString('latin1');
-        const rest = state.buffer.subarray(separator + 4);
-        state.buffer = Buffer.alloc(0);
-        state.upgraded = true;
-        const [statusLine, ...headerLines] = head.split('\r\n');
-        const match = /^HTTP\/1\.[01]\s+(\d{3})\s*(.*)$/.exec(statusLine ?? '');
-        const statusCode = match ? Number(match[1]) : 101;
-        const statusMessage = match ? match[2] : '';
-        const replyHeaders = {};
-        for (const line of headerLines) {
-          const index = line.indexOf(':');
-          if (index <= 0) continue;
-          replyHeaders[line.slice(0, index).trim().toLowerCase()] = line.slice(index + 1).trim();
-        }
-        if (statusCode !== 101) {
-          state.closed = true;
-          this.logger?.warn?.('local WS upgrade rejected: %s %s', statusCode, statusMessage);
-          this._send({ type: 'ws-accept', wsId, statusCode, statusMessage, replyHeaders });
-          try { socket.destroy(); } catch {}
-          this._localWs.delete(wsId);
-          return;
-        }
-        this._send({ type: 'ws-accept', wsId, statusCode: 101, replyHeaders });
-        if (rest.length > 0) this._send({ type: 'ws-frame', wsId, data: rest.toString('base64') });
-        return;
-      }
-      this._send({ type: 'ws-frame', wsId, data: chunk.toString('base64') });
-    });
-
-    const finish = () => {
-      if (state.closed) return;
-      state.closed = true;
-      this._localWs.delete(wsId);
-      this._send({ type: 'ws-close', wsId });
-    };
-    socket.on('close', finish);
-    socket.on('error', finish);
-  }
-
-  /** 网关下发的 ws-frame 是原始帧字节：直接写入本地 TCP，不能经 ws 库重编码。 */
-  _handleWsFrame(msg) {
-    const state = this._localWs.get(String(msg?.wsId ?? ''));
-    if (!state || state.closed || !state.upgraded) return;
-    const data = Buffer.from(String(msg?.data ?? ''), 'base64');
-    this._bytesIn += data.length;
-    try { state.socket.write(data); } catch { /* 忽略单帧写入失败，close 会收敛 */ }
-  }
-
-  _handleWsClose(msg) {
-    const wsId = String(msg?.wsId ?? '');
-    const state = this._localWs.get(wsId);
-    if (!state) return;
-    state.closed = true;
-    this._localWs.delete(wsId);
-    try { state.socket.destroy(); } catch {}
-  }
-
-  _cleanupLocalWs() {
-    for (const state of this._localWs.values()) {
-      state.closed = true;
-      try { state.socket.destroy(); } catch {}
-    }
-    this._localWs.clear();
-  }
-
-  _send(message) {
-    if (!this._ws || this._ws.readyState !== WebSocket.OPEN) return;
-    try { this._ws.send(JSON.stringify(message)); } catch (err) {
-      this.logger?.warn?.(`SaaS tunnel send failed: ${err?.message ?? err}`);
-    }
-  }
-
-  _heartbeatTick() {
-    if (!this._connected || this._draining) return;
-    if (this._heartbeatAckPending) {
-      this._missedHeartbeatAcks += 1;
-      if (this._missedHeartbeatAcks >= this.heartbeatMaxMissed) {
-        const detail = `SaaS 网关心跳连续 ${this._missedHeartbeatAcks} 次未确认，主动重连`;
-        this.lastError = detail;
-        this._setState('reconnecting', detail);
-        this._stopHeartbeat();
-        try { this._ws?.terminate(); } catch {}
-        return;
-      }
-    }
-    this._heartbeatAckPending = true;
-    this._send({
-      type: 'heartbeat',
-      ts: Date.now(),
-      state: {
-        requestsInFlight: this._inFlight.size,
-        wsOpen: this._localWs.size,
-        bytesIn: this._bytesIn,
-        bytesOut: this._bytesOut,
-        ...(this.lastError ? { lastError: String(this.lastError).slice(0, 500) } : {}),
-      },
-    });
-  }
-
-  _startHeartbeat() {
-    this._stopHeartbeat();
-    this._heartbeatAckPending = false;
-    this._missedHeartbeatAcks = 0;
-    this._heartbeatTimer = setInterval(() => this._heartbeatTick(), this.heartbeatIntervalMs);
-    this._heartbeatTimer.unref?.();
-    this._heartbeatTick();
-  }
-
-  _stopHeartbeat() {
-    if (this._heartbeatTimer) {
-      clearInterval(this._heartbeatTimer);
-      this._heartbeatTimer = null;
-    }
-  }
-
-  _onClose(code, reason) {
-    this._connected = false;
-    this.gateSecret = '';
-    this._stopHeartbeat();
-    this._cleanupLocalWs();
-    this._inFlight.clear();
-    const reasonText = reason?.toString?.() ?? '';
-    if (SAAS_TERMINAL_CLOSE_CODES.has(code)) {
-      this._terminal = true;
-      const detail = `SaaS 网关关闭连接 (${code}${reasonText ? `: ${reasonText}` : ''})，请重新绑定设备`;
-      this.lastError = detail;
-      this._setState('error', detail);
-      if (this._awaitingHandshake) {
-        this._settleHandshake(new SaasTunnelError('connection_closed', detail, { terminal: true, closeCode: code }));
-      }
-      return;
-    }
-    if (this._awaitingHandshake) {
-      this._settleHandshake(new SaasTunnelError('connection_closed', `SaaS 网关在握手完成前断开 (code=${code})`, { closeCode: code }));
-      return;
-    }
-    if (this._manuallyClosed || this._draining || this._suppressReconnect) return;
-    const detail = `SaaS 网关连接已断开 (code=${code})`;
-    this.lastError = detail;
-    this._scheduleReconnect(detail);
-  }
-
-  _scheduleReconnect(reason) {
-    if (this._manuallyClosed || this._draining || this._terminal) return;
-    if (this._reconnectTimer) return;
-    if (Number.isFinite(this.maxReconnectAttempts) && this._reconnectAttempts >= this.maxReconnectAttempts) {
-      this.lastError = `SaaS 隧道重连已达上限 (${this.maxReconnectAttempts} 次)`;
-      this._setState('error', this.lastError);
-      return;
-    }
-    this._reconnectAttempts += 1;
-    const attempt = this._reconnectAttempts;
-    const base = Math.min(this.reconnectBaseDelayMs * 2 ** (attempt - 1), this.reconnectMaxDelayMs);
-    const delay = Math.max(20, Math.round(base * (0.75 + this.random() * 0.5)));
-    this._setState('reconnecting', `SaaS 隧道断开${reason ? `：${reason}` : ''}，${Math.round(delay / 100) / 10}s 后重连（第 ${attempt} 次）`);
-    this._reconnectTimer = setTimeout(() => {
-      this._reconnectTimer = null;
-      this.connect().catch((err) => {
-        if (err?.terminal === true) this._setState('error', err.message);
-      });
-    }, delay);
-    this._reconnectTimer.unref?.();
-  }
-
-  _closeSocket(code = 1000, reason = '') {
-    const ws = this._ws;
-    this._ws = null;
-    if (!ws) return;
-    try { ws.close(code, reason); } catch {}
-    setTimeout(() => { try { ws.terminate(); } catch {} }, 1000).unref?.();
-  }
-
-  async disconnect() {
-    this._manuallyClosed = true;
-    this.gateSecret = '';
-    this._draining = false;
-    this._connected = false;
-    if (this._reconnectTimer) { clearTimeout(this._reconnectTimer); this._reconnectTimer = null; }
-    if (this._drainTimer) { clearTimeout(this._drainTimer); this._drainTimer = null; }
-    this._stopHeartbeat();
-    if (this._awaitingHandshake) this._settleHandshake(new SaasTunnelError('disconnected', '连接已取消'));
-    this._cleanupLocalWs();
-    this._inFlight.clear();
-    this._closeSocket(1000, 'client disconnect');
-    this._setState('idle', '已断开');
-  }
-}
+// SaaS 隧道客户端（控制通道协议 v2）——独立实现，不继承任何第三方隧道类。
+//
+// 契约见 docs/architecture/saas-tunnel.md §6 与 packages/tunnel-protocol/src/index.ts：
+//   C→S hello → S→C hello-ack → 转发 request/response(-start|chunk|end) 与 ws-*；
+//   v2 新增 heartbeat/heartbeat-ack、route-update、drain；未知 type 静默忽略。
+//   close 4001/4003/4004 为终态；4000/4002 可重连。
+import { WebSocket } from 'ws';
+import { request as httpRequest } from 'node:http';
+import { connect as netConnect } from 'node:net';
+
+export const SAAS_HEARTBEAT_INTERVAL_MS = 30_000;
+export const SAAS_HEARTBEAT_MAX_MISSED = 3;
+export const SAAS_HANDSHAKE_TIMEOUT_MS = 15_000;
+export const SAAS_RECONNECT_BASE_DELAY_MS = 1000;
+export const SAAS_RECONNECT_MAX_DELAY_MS = 60_000;
+export const SAAS_DEFAULT_GATEWAY_PATH = '/_gw/connect';
+export const SAAS_MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
+export const SAAS_TERMINAL_CLOSE_CODES = new Set([4001, 4003, 4004]);
+export const SAAS_TERMINAL_ERROR_CODES = new Set(['auth_failed', 'revoked', 'bad_request', 'unsupported_version', 'time_exhausted']);
+
+const HOP_BY_HOP = new Set(['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade']);
+const TUNNEL_HEADER = 'x-dsh-internal-tunnel';
+
+export class SaasTunnelError extends Error {
+  constructor(code, message, { terminal = false, closeCode = 0, cause } = {}) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'SaasTunnelError';
+    this.code = code;
+    this.terminal = terminal;
+    this.closeCode = closeCode;
+  }
+}
+
+export function buildSaasConnectUrl({ gatewayUrl, gatewayPath = SAAS_DEFAULT_GATEWAY_PATH, deviceToken } = {}) {
+  let url;
+  try {
+    url = new URL(String(gatewayUrl ?? '').trim());
+  } catch {
+    throw new SaasTunnelError('invalid_gateway_url', `SaaS 网关地址不合法: ${gatewayUrl}`, { terminal: true });
+  }
+  if (url.protocol === 'http:') url.protocol = 'ws:';
+  else if (url.protocol === 'https:') url.protocol = 'wss:';
+  else if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
+    throw new SaasTunnelError('invalid_gateway_url', 'SaaS 网关地址只支持 ws/wss/http/https', { terminal: true });
+  }
+  let path = String(gatewayPath || SAAS_DEFAULT_GATEWAY_PATH);
+  if (!path.startsWith('/')) path = '/' + path;
+  const basePath = url.pathname.replace(/\/+$/, '');
+  url.pathname = (basePath && basePath !== '/' ? basePath : '') + path;
+  url.search = '';
+  url.hash = '';
+  if (deviceToken) url.searchParams.set('device_token', String(deviceToken));
+  return url.toString();
+}
+
+export function pickRoutePublicUrl(routes) {
+  const list = Array.isArray(routes) ? routes.filter((route) => route && typeof route === 'object') : [];
+  const host = list.find((route) => route.kind === 'host' && typeof route.url === 'string' && route.url);
+  const any = list.find((route) => typeof route.url === 'string' && route.url);
+  return String((host ?? any)?.url ?? '');
+}
+
+function sanitizeHeaders(headers) {
+  const out = {};
+  for (const [name, value] of Object.entries(headers ?? {})) {
+    if (HOP_BY_HOP.has(name.toLowerCase()) || value === undefined) continue;
+    out[name.toLowerCase()] = value;
+  }
+  return out;
+}
+
+export class SaasTunnelClient {
+  constructor(options = {}) {
+    const {
+      gatewayUrl = '',
+      gatewayPath = SAAS_DEFAULT_GATEWAY_PATH,
+      deviceToken = null,
+      tokenProvider = null,
+      localPort,
+      internalTunnelSecret = '',
+      protocol = 'v2',
+      heartbeatIntervalMs = SAAS_HEARTBEAT_INTERVAL_MS,
+      heartbeatMaxMissed = SAAS_HEARTBEAT_MAX_MISSED,
+      maxResponseBytes = SAAS_MAX_RESPONSE_BYTES,
+      reconnectBaseDelayMs = SAAS_RECONNECT_BASE_DELAY_MS,
+      reconnectMaxDelayMs = SAAS_RECONNECT_MAX_DELAY_MS,
+      maxReconnectAttempts = Number.POSITIVE_INFINITY,
+      random = Math.random,
+      deviceInfo = {},
+      sseStreaming = true,
+      onHelloAck = null,
+      onStateChange = null,
+      onRouteUpdate = null,
+      onDrain = null,
+      onDrainComplete = null,
+      logger = console,
+    } = options;
+
+    if (!localPort) throw new Error('localPort is required');
+    this.gatewayUrl = String(gatewayUrl);
+    this.gatewayPath = gatewayPath || SAAS_DEFAULT_GATEWAY_PATH;
+    this.deviceToken = deviceToken;
+    this.tokenProvider = typeof tokenProvider === 'function'
+      ? tokenProvider
+      : (deviceToken ? async () => deviceToken : null);
+    this.localPort = Number(localPort);
+    this.internalTunnelSecret = String(internalTunnelSecret ?? '');
+    this.protocol = protocol === 'auto' ? 'auto' : 'v2';
+    this.protocolVersion = 2;
+    this.heartbeatIntervalMs = Math.max(10, Number(heartbeatIntervalMs) || SAAS_HEARTBEAT_INTERVAL_MS);
+    this.heartbeatMaxMissed = Math.max(1, Number(heartbeatMaxMissed) || SAAS_HEARTBEAT_MAX_MISSED);
+    this.maxResponseBytes = Math.max(1024, Number(maxResponseBytes) || SAAS_MAX_RESPONSE_BYTES);
+    this.reconnectBaseDelayMs = Math.max(10, Number(reconnectBaseDelayMs) || SAAS_RECONNECT_BASE_DELAY_MS);
+    this.reconnectMaxDelayMs = Math.max(this.reconnectBaseDelayMs, Number(reconnectMaxDelayMs) || SAAS_RECONNECT_MAX_DELAY_MS);
+    this.maxReconnectAttempts = Number.isFinite(maxReconnectAttempts) ? Math.max(0, maxReconnectAttempts) : Number.POSITIVE_INFINITY;
+    this.random = typeof random === 'function' ? random : Math.random;
+    this.deviceInfo = deviceInfo ?? {};
+    this.sseStreaming = sseStreaming !== false;
+    this.onHelloAck = onHelloAck;
+    this.onStateChange = onStateChange;
+    this.onRouteUpdate = onRouteUpdate;
+    this.onDrain = onDrain;
+    this.onDrainComplete = onDrainComplete;
+    this.logger = logger ?? console;
+
+    this._connected = false;
+    this._state = 'idle';
+    this._stateDetail = '';
+    this._terminal = false;
+    this._draining = false;
+    this._manuallyClosed = false;
+    this._connecting = false;
+    this._ws = null;
+    this._awaitingHandshake = false;
+    this._handshakeResolve = null;
+    this._handshakeReject = null;
+    this._handshakeTimer = null;
+    this._heartbeatTimer = null;
+    this._heartbeatAckPending = false;
+    this._missedHeartbeatAcks = 0;
+    this._reconnectTimer = null;
+    this._reconnectAttempts = 0;
+    this._routes = [];
+    this._routeRev = 0;
+    this.tunnel = null;
+    this.publicUrl = '';
+    this.lastError = null;
+    this.lastAckAt = null;
+    this.limits = null;
+    this.features = null;
+    this.serverTime = null;
+    this.gateSecret = '';
+    this._inFlight = new Set();
+    this._localWs = new Map();
+    this._bytesIn = 0;
+    this._bytesOut = 0;
+    this._drainTimer = null;
+    this._suppressReconnect = false;
+  }
+
+  get connected() { return this._connected; }
+  get state() { return this._state; }
+  get stateDetail() { return this._stateDetail; }
+  get draining() { return this._draining; }
+  get terminal() { return this._terminal; }
+  get routes() { return this._routes; }
+  get routeRev() { return this._routeRev; }
+  get reconnectAttempts() { return this._reconnectAttempts; }
+
+  _setState(state, detail = '') {
+    this._state = state;
+    this._stateDetail = detail;
+    try { this.onStateChange?.({ state, detail, connected: this._connected, publicUrl: this.publicUrl }); } catch {}
+  }
+
+  async connect() {
+    if (this._connected || this._connecting || this._manuallyClosed) return;
+    this._connecting = true;
+    this._setState('connecting', '正在连接 SaaS 网关…');
+    try {
+      const token = await this._acquireToken();
+      await this._openSocket(token);
+      this._connected = true;
+      this._terminal = false;
+      this._manuallyClosed = false;
+      this._reconnectAttempts = 0;
+      this.lastError = null;
+      this.lastAckAt = Date.now();
+      this._startHeartbeat();
+      this._setState('ready', this.publicUrl ? `SaaS 隧道已建立 (${this.publicUrl})` : 'SaaS 隧道已建立');
+    } catch (err) {
+      this._connected = false;
+      this._stopHeartbeat();
+      const detail = err?.message ?? String(err);
+      this.lastError = detail;
+      const terminal = err?.terminal === true || this._terminal;
+      if (terminal) {
+        this._terminal = true;
+        this._setState('error', detail);
+      } else if (!this._manuallyClosed && !this._draining) {
+        this._scheduleReconnect(detail);
+      }
+      throw err;
+    } finally {
+      this._connecting = false;
+    }
+  }
+
+  async _acquireToken() {
+    if (!this.tokenProvider) {
+      throw new SaasTunnelError('missing_device_credentials', '尚未绑定设备，请先在面板获取设备码并绑定', { terminal: true });
+    }
+    const result = await this.tokenProvider();
+    const token = typeof result === 'string' ? result : result?.token;
+    if (!token) throw new SaasTunnelError('missing_device_token', '设备令牌获取失败，请重新绑定', { terminal: true });
+    if (result && typeof result === 'object') {
+      if (result.gateway?.url) this.gatewayUrl = result.gateway.url;
+      if (result.gateway?.path) this.gatewayPath = result.gateway.path;
+      if (result.tunnel) this.tunnel = result.tunnel;
+    }
+    this.deviceToken = String(token);
+    return this.deviceToken;
+  }
+
+  _openSocket(deviceToken) {
+    return new Promise((resolve, reject) => {
+      let ws;
+      try {
+        ws = new WebSocket(buildSaasConnectUrl({
+          gatewayUrl: this.gatewayUrl,
+          gatewayPath: this.gatewayPath,
+          deviceToken,
+        }), {
+          handshakeTimeout: 10_000,
+          headers: { authorization: `Bearer ${deviceToken}` },
+          perMessageDeflate: false,
+        });
+      } catch (err) {
+        reject(new SaasTunnelError('invalid_gateway_url', err?.message ?? String(err), { terminal: true, cause: err }));
+        return;
+      }
+      this._ws = ws;
+      this._awaitingHandshake = true;
+      this._handshakeResolve = resolve;
+      this._handshakeReject = reject;
+      this._handshakeTimer = setTimeout(() => {
+        if (!this._awaitingHandshake) return;
+        try { ws.terminate(); } catch {}
+        this._settleHandshake(new SaasTunnelError('handshake_timeout', 'SaaS 网关握手超时（15s 内未收到 hello-ack）'));
+      }, SAAS_HANDSHAKE_TIMEOUT_MS);
+
+      ws.on('open', () => {
+        this.logger?.info?.('SaaS tunnel WebSocket open');
+        this._sendHello();
+      });
+      ws.on('message', (data) => this._onMessage(data));
+      ws.on('close', (code, reason) => this._onClose(code, reason));
+      ws.on('error', (err) => {
+        this.logger?.error?.(`SaaS tunnel WebSocket error: ${err?.message ?? err}`);
+        if (this._awaitingHandshake) this._settleHandshake(err instanceof Error ? err : new Error(String(err)));
+      });
+    });
+  }
+
+  _settleHandshake(error) {
+    if (!this._awaitingHandshake) return;
+    this._awaitingHandshake = false;
+    if (this._handshakeTimer) {
+      clearTimeout(this._handshakeTimer);
+      this._handshakeTimer = null;
+    }
+    const resolve = this._handshakeResolve;
+    const reject = this._handshakeReject;
+    this._handshakeResolve = null;
+    this._handshakeReject = null;
+    if (error) reject?.(error);
+    else resolve?.();
+  }
+
+  _sendHello() {
+    const device = {};
+    for (const key of ['name', 'platform', 'hostname', 'pluginVersion', 'dshVersion']) {
+      const value = this.deviceInfo?.[key];
+      if (value !== undefined && value !== null && String(value).trim()) device[key] = String(value).trim();
+    }
+    if (!device.name) device.name = device.hostname || 'DSH Remote Tunnel';
+    if (!device.platform) device.platform = process.platform ?? 'unknown';
+    this._send({
+      type: 'hello',
+      v: 2,
+      device,
+      caps: { sseStreaming: this.sseStreaming, wsFrames: true, maxResponseBytes: this.maxResponseBytes },
+      ts: Math.floor(Date.now() / 1000),
+    });
+  }
+
+  _onMessage(data) {
+    let msg;
+    try {
+      msg = JSON.parse(typeof data === 'string' ? data : data.toString());
+    } catch {
+      return;
+    }
+    if (!msg || typeof msg !== 'object') return;
+
+    if (msg.type === 'hello-ack') {
+      if (this._awaitingHandshake) this._handleHelloAck(msg);
+      else if (msg.ok === false) this.logger?.warn?.('ignoring duplicate hello-ack');
+      return;
+    }
+    if (msg.type === 'ready' && this._awaitingHandshake && this.protocol === 'auto') {
+      this.protocolVersion = 1;
+      this.publicUrl = String(msg.publicUrl ?? '');
+      this._connected = true;
+      this._settleHandshake();
+      return;
+    }
+    switch (msg.type) {
+      case 'heartbeat-ack':
+        this._heartbeatAckPending = false;
+        this._missedHeartbeatAcks = 0;
+        this.lastAckAt = Date.now();
+        if (msg.serverTime) this.serverTime = msg.serverTime;
+        if (Array.isArray(msg.actions) && msg.actions.includes('drain') && !this._draining) {
+          this._startDrain({ deadline: Date.now() + this.heartbeatIntervalMs * 3 });
+        }
+        return;
+      case 'route-update':
+        this._routeRev = Number(msg.rev) || this._routeRev;
+        this._applyRoutes(msg.routes);
+        try { this.onRouteUpdate?.({ routes: this._routes, rev: this._routeRev, publicUrl: this.publicUrl }); } catch {}
+        return;
+      case 'drain':
+        this._handleDrain(msg);
+        return;
+      case 'ready':
+        if (this._connected && !this._routes.some((route) => route.kind === 'host')) {
+          if (msg.publicUrl) this.publicUrl = String(msg.publicUrl);
+        }
+        return;
+      case 'ping':
+        this._send({ type: 'pong', ts: Date.now() });
+        return;
+      case 'request':
+        this._handleRequest(msg);
+        return;
+      case 'ws-open':
+        this._handleWsOpen(msg);
+        return;
+      case 'ws-frame':
+        this._handleWsFrame(msg);
+        return;
+      case 'ws-close':
+        this._handleWsClose(msg);
+        return;
+      case 'pong':
+        return;
+      default:
+        // 未知 type 必须静默忽略（v1 前后兼容）
+        return;
+    }
+  }
+
+  _handleHelloAck(msg) {
+    if (msg.ok === false) {
+      const code = String(msg.error?.code ?? 'bad_request');
+      const message = String(msg.error?.message ?? '');
+      const detail = `SaaS 网关拒绝握手: ${message || code} (${code})`;
+      const terminal = SAAS_TERMINAL_ERROR_CODES.has(code);
+      this.lastError = detail;
+      if (terminal) this._terminal = true;
+      this._setState(terminal ? 'error' : 'connecting', detail);
+      try { this._ws?.terminate(); } catch {}
+      this._settleHandshake(new SaasTunnelError(code, detail, { terminal }));
+      return;
+    }
+    this.protocolVersion = Number(msg.v) || 2;
+    if (msg.tunnel) this.tunnel = { publicId: String(msg.tunnel.publicId ?? ''), name: String(msg.tunnel.name ?? '') };
+    this.limits = msg.limits ?? null;
+    this.features = msg.features ?? null;
+    // 网关为每条控制连接随机下发信任密钥；gate 用它验 x-qzsy-gate 的 HMAC。
+    this.gateSecret = typeof msg.gate?.secret === 'string' && /^[0-9a-f]{64}$/i.test(msg.gate.secret)
+      ? msg.gate.secret.toLowerCase()
+      : '';
+    this.serverTime = msg.serverTime ?? null;
+    if (this.limits?.heartbeatMs) this.heartbeatIntervalMs = Math.max(10, Number(this.limits.heartbeatMs) || this.heartbeatIntervalMs);
+    if (this.limits?.maxResponseBytes) this.maxResponseBytes = Math.max(1024, Number(this.limits.maxResponseBytes) || this.maxResponseBytes);
+    this._applyRoutes(msg.routes);
+    this._connected = true;
+    this._reconnectAttempts = 0;
+    this.lastAckAt = Date.now();
+    try { this.onHelloAck?.(msg); } catch {}
+    this._settleHandshake();
+  }
+
+  _applyRoutes(routes) {
+    const list = Array.isArray(routes) ? routes.filter((route) => route && typeof route === 'object') : [];
+    this._routes = list;
+    const picked = pickRoutePublicUrl(list);
+    if (picked) this.publicUrl = picked;
+  }
+
+  _handleDrain(msg) {
+    let deadline = Number(msg?.deadline);
+    if (!Number.isFinite(deadline) || deadline <= 0) deadline = Date.now() + this.heartbeatIntervalMs * 3;
+    else if (deadline < 1e12) deadline *= 1000;
+    this._startDrain({ deadline });
+  }
+
+  _startDrain({ deadline }) {
+    if (this._draining) return;
+    this._draining = true;
+    this._setState('draining', 'SaaS 网关下线中，等待在途请求结束');
+    try { this.onDrain?.({ deadline }); } catch {}
+    const finish = () => this._finishDrain();
+    if (this._inFlight.size === 0) {
+      this._drainTimer = setTimeout(finish, 20);
+    } else {
+      const poll = () => {
+        if (!this._draining) return;
+        if (this._inFlight.size === 0 || Date.now() >= deadline) return finish();
+        this._drainTimer = setTimeout(poll, Math.min(100, Math.max(10, deadline - Date.now())));
+      };
+      this._drainTimer = setTimeout(poll, 20);
+      setTimeout(() => { if (this._draining) finish(); }, Math.max(0, deadline - Date.now()) + 1000).unref?.();
+    }
+  }
+
+  _finishDrain() {
+    if (!this._draining) return;
+    this._draining = false;
+    this.gateSecret = '';
+    this._suppressReconnect = true;
+    if (this._drainTimer) { clearTimeout(this._drainTimer); this._drainTimer = null; }
+    this._connected = false;
+    this._stopHeartbeat();
+    this._cleanupLocalWs();
+    this._inFlight.clear();
+    this.lastError = 'SaaS 网关已下线（drain），隧道已优雅断开';
+    this._setState('closed', this.lastError);
+    try { this.onDrainComplete?.({ detail: this.lastError }); } catch {}
+    this._closeSocket(1000, 'drain');
+    // 网关滚动发布/重启会主动 drain。drain 只表示「这一轮连接该结束了」，不是终态：
+    // 不自动重连的话，每次网关发布都要用户手动点「连接」，长连接会一直停在离线。
+    this._suppressReconnect = false;
+    this._reconnectAttempts = 0;
+    this._scheduleReconnect('网关已 drain 下线，准备重连');
+  }
+
+  _handleRequest(msg) {
+    const requestId = String(msg?.requestId ?? '');
+    if (!requestId) return;
+    if (this._draining) {
+      this._send({ type: 'response', requestId, statusCode: 503, headers: { 'content-type': 'text/plain; charset=utf-8' }, body: Buffer.from('tunnel is draining').toString('base64') });
+      return;
+    }
+    this._inFlight.add(requestId);
+    if (typeof msg.body === 'string') this._bytesIn += Math.floor((msg.body.length * 3) / 4);
+    const headers = sanitizeHeaders(msg.headers);
+    headers.host = `127.0.0.1:${this.localPort}`;
+    if (this.internalTunnelSecret) headers[TUNNEL_HEADER] = this.internalTunnelSecret;
+
+    const upstream = httpRequest({
+      host: '127.0.0.1',
+      port: this.localPort,
+      method: String(msg.method ?? 'GET'),
+      path: String(msg.path ?? '/'),
+      headers,
+    }, (res) => {
+      const responseHeaders = sanitizeHeaders(res.headers);
+      const isSse = String(res.headers['content-type'] ?? '').toLowerCase().includes('text/event-stream');
+      if (isSse && this.sseStreaming) {
+        this._send({ type: 'response-start', requestId, statusCode: res.statusCode ?? 200, headers: responseHeaders });
+        res.on('data', (chunk) => {
+          this._bytesOut += chunk.length;
+          this._send({ type: 'response-chunk', requestId, body: Buffer.from(chunk).toString('base64') });
+        });
+        res.on('end', () => {
+          this._send({ type: 'response-end', requestId });
+          this._inFlight.delete(requestId);
+        });
+        res.on('error', () => {
+          this._send({ type: 'response-end', requestId });
+          this._inFlight.delete(requestId);
+        });
+        return;
+      }
+      const chunks = [];
+      let total = 0;
+      let finished = false;
+      const fail = (code, text) => {
+        if (finished) return;
+        finished = true;
+        this._inFlight.delete(requestId);
+        this._send({ type: 'response', requestId, statusCode: code, headers: { 'content-type': 'text/plain; charset=utf-8' }, body: Buffer.from(text).toString('base64') });
+      };
+      res.on('data', (chunk) => {
+        total += chunk.length;
+        if (total > this.maxResponseBytes) {
+          fail(502, `Response too large for tunnel (>${Math.round(this.maxResponseBytes / 1024 / 1024)}MB cap)`);
+          res.destroy();
+          return;
+        }
+        chunks.push(chunk);
+      });
+      res.on('end', () => {
+        if (finished) return;
+        finished = true;
+        this._inFlight.delete(requestId);
+        const body = Buffer.concat(chunks).toString('base64');
+        this._bytesOut += Buffer.concat(chunks).length;
+        this._send({ type: 'response', requestId, statusCode: res.statusCode ?? 200, headers: responseHeaders, body });
+      });
+      res.on('error', () => fail(502, 'Response Error'));
+    });
+    upstream.on('error', (err) => {
+      this._inFlight.delete(requestId);
+      this._send({ type: 'response', requestId, statusCode: 502, headers: { 'content-type': 'text/plain; charset=utf-8' }, body: Buffer.from(`Bad Gateway: ${err?.message ?? err}`).toString('base64') });
+    });
+    if (typeof msg.body === 'string' && msg.body) upstream.write(Buffer.from(msg.body, 'base64'));
+    upstream.end();
+  }
+
+  // ── WebSocket 原始帧转发 ────────────────────────────────────────────────
+  // 网关契约（apps/gateway/src/proxy-ws.ts）：ws-frame 的 data 是**原始 WebSocket 帧字节**
+  // （含 opcode/mask/分片），不是消息 payload。因此这里用裸 TCP 完成 Upgrade 握手后
+  // 原样透传字节，绝不能再经 ws 库二次成帧。
+  _handleWsOpen(msg) {
+    const wsId = String(msg?.wsId ?? '');
+    if (!wsId) return;
+    if (this._draining) {
+      this._send({ type: 'ws-accept', wsId, statusCode: 503, statusMessage: 'Service Unavailable', replyHeaders: { 'content-type': 'text/plain' } });
+      return;
+    }
+    // Upgrade 请求必须原样保留 connection/upgrade/sec-websocket-*（不能套用普通
+    // HTTP 请求的逐跳过滤），只重写 Host 并补本地隧道标记。
+    const requestHeaders = {};
+    for (const [name, value] of Object.entries(msg.headers ?? {})) {
+      const lower = name.toLowerCase();
+      if (lower === 'host' || lower === TUNNEL_HEADER || value === undefined) continue;
+      requestHeaders[lower] = value;
+    }
+    requestHeaders.host = `127.0.0.1:${this.localPort}`;
+    // 网关按 hop-by-hop 规则剥掉了 Upgrade/Connection，这里必须补回，否则本机
+    // WebSocket 升级请求不合法（表现为浏览器收到非 101）。
+    requestHeaders.connection = requestHeaders.connection ?? 'Upgrade';
+    requestHeaders.upgrade = requestHeaders.upgrade ?? 'websocket';
+    if (this.internalTunnelSecret) requestHeaders[TUNNEL_HEADER] = this.internalTunnelSecret;
+
+    const socket = netConnect({ host: '127.0.0.1', port: this.localPort });
+    const state = { socket, buffer: Buffer.alloc(0), upgraded: false, closed: false, headerSent: false };
+    this._localWs.set(wsId, state);
+
+    const fail = (code, message) => {
+      if (state.closed) return;
+      state.closed = true;
+      this._send({ type: 'ws-accept', wsId, statusCode: code, statusMessage: message, replyHeaders: { 'content-type': 'text/plain' } });
+      try { socket.destroy(); } catch {}
+      this._localWs.delete(wsId);
+    };
+
+    socket.on('connect', () => {
+      const path = String(msg.path ?? '/');
+      const lines = [`GET ${path.startsWith('/') ? path : '/' + path} HTTP/1.1`];
+      for (const [name, value] of Object.entries(requestHeaders)) {
+        if (Array.isArray(value)) for (const item of value) lines.push(`${name}: ${item}`);
+        else if (value !== undefined) lines.push(`${name}: ${value}`);
+      }
+      lines.push('', '');
+      state.headerSent = true;
+      socket.write(lines.join('\r\n'));
+    });
+
+    socket.on('data', (chunk) => {
+      if (state.closed) return;
+      if (!state.upgraded) {
+        state.buffer = Buffer.concat([state.buffer, chunk]);
+        const separator = state.buffer.indexOf('\r\n\r\n');
+        if (separator === -1) {
+          if (state.buffer.length > 64 * 1024) fail(502, 'Bad Gateway');
+          return;
+        }
+        const head = state.buffer.subarray(0, separator).toString('latin1');
+        const rest = state.buffer.subarray(separator + 4);
+        state.buffer = Buffer.alloc(0);
+        state.upgraded = true;
+        const [statusLine, ...headerLines] = head.split('\r\n');
+        const match = /^HTTP\/1\.[01]\s+(\d{3})\s*(.*)$/.exec(statusLine ?? '');
+        const statusCode = match ? Number(match[1]) : 101;
+        const statusMessage = match ? match[2] : '';
+        const replyHeaders = {};
+        for (const line of headerLines) {
+          const index = line.indexOf(':');
+          if (index <= 0) continue;
+          replyHeaders[line.slice(0, index).trim().toLowerCase()] = line.slice(index + 1).trim();
+        }
+        if (statusCode !== 101) {
+          state.closed = true;
+          this.logger?.warn?.('local WS upgrade rejected: %s %s', statusCode, statusMessage);
+          this._send({ type: 'ws-accept', wsId, statusCode, statusMessage, replyHeaders });
+          try { socket.destroy(); } catch {}
+          this._localWs.delete(wsId);
+          return;
+        }
+        this._send({ type: 'ws-accept', wsId, statusCode: 101, replyHeaders });
+        if (rest.length > 0) this._send({ type: 'ws-frame', wsId, data: rest.toString('base64') });
+        return;
+      }
+      this._send({ type: 'ws-frame', wsId, data: chunk.toString('base64') });
+    });
+
+    const finish = () => {
+      if (state.closed) return;
+      state.closed = true;
+      this._localWs.delete(wsId);
+      this._send({ type: 'ws-close', wsId });
+    };
+    socket.on('close', finish);
+    socket.on('error', finish);
+  }
+
+  /** 网关下发的 ws-frame 是原始帧字节：直接写入本地 TCP，不能经 ws 库重编码。 */
+  _handleWsFrame(msg) {
+    const state = this._localWs.get(String(msg?.wsId ?? ''));
+    if (!state || state.closed || !state.upgraded) return;
+    const data = Buffer.from(String(msg?.data ?? ''), 'base64');
+    this._bytesIn += data.length;
+    try { state.socket.write(data); } catch { /* 忽略单帧写入失败，close 会收敛 */ }
+  }
+
+  _handleWsClose(msg) {
+    const wsId = String(msg?.wsId ?? '');
+    const state = this._localWs.get(wsId);
+    if (!state) return;
+    state.closed = true;
+    this._localWs.delete(wsId);
+    try { state.socket.destroy(); } catch {}
+  }
+
+  _cleanupLocalWs() {
+    for (const state of this._localWs.values()) {
+      state.closed = true;
+      try { state.socket.destroy(); } catch {}
+    }
+    this._localWs.clear();
+  }
+
+  _send(message) {
+    if (!this._ws || this._ws.readyState !== WebSocket.OPEN) return;
+    try { this._ws.send(JSON.stringify(message)); } catch (err) {
+      this.logger?.warn?.(`SaaS tunnel send failed: ${err?.message ?? err}`);
+    }
+  }
+
+  _heartbeatTick() {
+    if (!this._connected || this._draining) return;
+    if (this._heartbeatAckPending) {
+      this._missedHeartbeatAcks += 1;
+      if (this._missedHeartbeatAcks >= this.heartbeatMaxMissed) {
+        const detail = `SaaS 网关心跳连续 ${this._missedHeartbeatAcks} 次未确认，主动重连`;
+        this.lastError = detail;
+        this._setState('reconnecting', detail);
+        this._stopHeartbeat();
+        try { this._ws?.terminate(); } catch {}
+        return;
+      }
+    }
+    this._heartbeatAckPending = true;
+    this._send({
+      type: 'heartbeat',
+      ts: Date.now(),
+      state: {
+        requestsInFlight: this._inFlight.size,
+        wsOpen: this._localWs.size,
+        bytesIn: this._bytesIn,
+        bytesOut: this._bytesOut,
+        ...(this.lastError ? { lastError: String(this.lastError).slice(0, 500) } : {}),
+      },
+    });
+  }
+
+  _startHeartbeat() {
+    this._stopHeartbeat();
+    this._heartbeatAckPending = false;
+    this._missedHeartbeatAcks = 0;
+    this._heartbeatTimer = setInterval(() => this._heartbeatTick(), this.heartbeatIntervalMs);
+    this._heartbeatTimer.unref?.();
+    this._heartbeatTick();
+  }
+
+  _stopHeartbeat() {
+    if (this._heartbeatTimer) {
+      clearInterval(this._heartbeatTimer);
+      this._heartbeatTimer = null;
+    }
+  }
+
+  _onClose(code, reason) {
+    this._connected = false;
+    this.gateSecret = '';
+    this._stopHeartbeat();
+    this._cleanupLocalWs();
+    this._inFlight.clear();
+    const reasonText = reason?.toString?.() ?? '';
+    if (SAAS_TERMINAL_CLOSE_CODES.has(code)) {
+      this._terminal = true;
+      const detail = `SaaS 网关关闭连接 (${code}${reasonText ? `: ${reasonText}` : ''})，请重新绑定设备`;
+      this.lastError = detail;
+      this._setState('error', detail);
+      if (this._awaitingHandshake) {
+        this._settleHandshake(new SaasTunnelError('connection_closed', detail, { terminal: true, closeCode: code }));
+      }
+      return;
+    }
+    if (this._awaitingHandshake) {
+      this._settleHandshake(new SaasTunnelError('connection_closed', `SaaS 网关在握手完成前断开 (code=${code})`, { closeCode: code }));
+      return;
+    }
+    if (this._manuallyClosed || this._draining || this._suppressReconnect) return;
+    const detail = `SaaS 网关连接已断开 (code=${code})`;
+    this.lastError = detail;
+    this._scheduleReconnect(detail);
+  }
+
+  _scheduleReconnect(reason) {
+    if (this._manuallyClosed || this._draining || this._terminal) return;
+    if (this._reconnectTimer) return;
+    if (Number.isFinite(this.maxReconnectAttempts) && this._reconnectAttempts >= this.maxReconnectAttempts) {
+      this.lastError = `SaaS 隧道重连已达上限 (${this.maxReconnectAttempts} 次)`;
+      this._setState('error', this.lastError);
+      return;
+    }
+    this._reconnectAttempts += 1;
+    const attempt = this._reconnectAttempts;
+    const base = Math.min(this.reconnectBaseDelayMs * 2 ** (attempt - 1), this.reconnectMaxDelayMs);
+    const delay = Math.max(20, Math.round(base * (0.75 + this.random() * 0.5)));
+    this._setState('reconnecting', `SaaS 隧道断开${reason ? `：${reason}` : ''}，${Math.round(delay / 100) / 10}s 后重连（第 ${attempt} 次）`);
+    this._reconnectTimer = setTimeout(() => {
+      this._reconnectTimer = null;
+      this.connect().catch((err) => {
+        if (err?.terminal === true) this._setState('error', err.message);
+      });
+    }, delay);
+    this._reconnectTimer.unref?.();
+  }
+
+  _closeSocket(code = 1000, reason = '') {
+    const ws = this._ws;
+    this._ws = null;
+    if (!ws) return;
+    try { ws.close(code, reason); } catch {}
+    setTimeout(() => { try { ws.terminate(); } catch {} }, 1000).unref?.();
+  }
+
+  async disconnect() {
+    this._manuallyClosed = true;
+    this.gateSecret = '';
+    this._draining = false;
+    this._connected = false;
+    if (this._reconnectTimer) { clearTimeout(this._reconnectTimer); this._reconnectTimer = null; }
+    if (this._drainTimer) { clearTimeout(this._drainTimer); this._drainTimer = null; }
+    this._stopHeartbeat();
+    if (this._awaitingHandshake) this._settleHandshake(new SaasTunnelError('disconnected', '连接已取消'));
+    this._cleanupLocalWs();
+    this._inFlight.clear();
+    this._closeSocket(1000, 'client disconnect');
+    this._setState('idle', '已断开');
+  }
+}