@dshfly/remote-connector 0.2.1

package/core/tunnel.js

@@ -0,0 +1,607 @@
+// packages/remote-connector/core/tunnel.js
+// connector 的控制通道（WSS 客户端）与 E2EE 终点 + dsh web 事件转发：
+// 自 services/connector/tunnel.js 迁入（单一代码源）。
+//   - 收到 REQ（E2EE 信封）→ 解密 → 明文重放到 dsh web → 加密响应 → RES
+//   - 连上 dsh web 的 /api/events.mux + /api/events.host（WS），把每条 server-request
+//     帧 E2EE 加密后作为 EVENT 帧推给中继（中继再路由给手机）。
+
+import WebSocket from 'ws';
+import zlib from 'node:zlib';
+import { promisify } from 'node:util';
+import { TYPE, encode, decodeFrame, toJson, jsonFrame } from '@dshfly/tunnel-protocol';
+import { sealEnvelope, openEnvelope, deriveDirectionalKeys, ReplayGuard, utf8Decode, utf8, verifyUnpair } from '@dshfly/crypto';
+import { claimOutSeq, saveKeys } from './keys.js';
+
+// C2（P2-8）：异步 deflate（大响应压缩不阻塞宿主主线程）
+const zlibDeflate = promisify(zlib.deflate);
+
+// 协议 v2 方向密钥：PC 封 PC→手机 用 down、解 手机→PC 用 up（手机侧恰好相反）。
+// 96-bit nonce 的碰撞域要求按方向隔离，不能直接用根会话密钥。
+const dirOf = (sessionKey) => deriveDirectionalKeys(sessionKey);
+
+const HOP = new Set([
+  'host', 'connection', 'content-length', 'transfer-encoding',
+  'keep-alive', 'upgrade', 'te', 'trailer',
+]);
+// B8（P1-10）：入站 REQ 帧 payload 上限（信封 JSON，业务 RPC 载荷远小于此）。
+// 2026-08 调至 8MB 与中继 MAX_TUNNEL_BODY 对齐：多模态图片的 E2EE 信封（≈1.78×图片 base64）
+// 会突破原 4MB，而中继本来就允许到 8MB（docs/mobile-image-upload-plan.md §4.1）——原 4MB 会把
+// 合法图片帧静默丢弃（tunnel.js `> MAX_REQ_FRAME return`），导致手机端 30s 后 504 的"假死"。
+const MAX_REQ_FRAME = 8 * 1024 * 1024;
+function stripHop(h) {
+  const o = {};
+  for (const [k, v] of Object.entries(h || {})) if (!HOP.has(k.toLowerCase())) o[k] = v;
+  return o;
+}
+
+// ws readyState: CONNECTING=0 OPEN=1 CLOSING=2 CLOSED=3
+const WS_OPEN = 1;
+
+// 安全出站：ws.send 在非 OPEN 状态（CONNECTING/CLOSING/CLOSED）会抛
+// 'WebSocket is not open: readyState ...'。定时器/事件回调里的未捕获异常会
+// 崩掉宿主进程（relay 重启重连窗口的 flushBatch 曾因此杀死 dsh web）——
+// 统一走本函数，只对 OPEN 连接发送且吞掉一切发送错误。
+export function safeSend(ws, data) {
+  try {
+    if (ws && !ws.destroyed && ws.readyState === WS_OPEN) ws.send(data);
+  } catch {}
+}
+
+// 大响应体 deflate 压缩（手机端 pako 解压），减少隧道传输量
+const COMPRESS_THRESHOLD = 4096;
+
+/** session.list 响应瘦身（2026-08 性能）：剥除 App 无消费的投影字段（goal/
+ *  subagentTiming/subagent/plan/todos）——列表刷新体量与解析随会话数线性增长。
+ *  permissions 2026-08 起保留：会话详情页"权限设定"卡片在读（写走 commands/execute，
+ *  与 session.list 无关）。非目标结构/解析失败 → 原样返回（绝不破坏响应）。纯函数，可单测。 */
+export function stripSessionListJson(jsonStr) {
+  try {
+    const full = JSON.parse(jsonStr);
+    if (full?.result?.ok && Array.isArray(full.result.value?.items)) {
+      for (const it of full.result.value.items) {
+        const v = it?.projections?.values;
+        if (v && typeof v === 'object') {
+          delete v.goal;
+          delete v.subagentTiming;
+          delete v.subagent;
+          delete v.plan;
+          delete v.todos;
+        }
+      }
+      return JSON.stringify(full);
+    }
+  } catch { /* 解析失败原样返回 */ }
+  return jsonStr;
+}
+async function replayInner(target, inner, sessionTitles = null) {
+  // A5（P0-4，SSRF 修复）：反代目标必须与 target 同源。
+  // inner.url 是手机 E2EE 明文，可被恶意手机/被劫持会话设置为任意绝对 URL——
+  // 不做校验时 dsh web 进程会替手机请求任意内网/云 metadata 地址并把响应密封回传。
+  // 只允许相对 /api/* 路径解析到 target 同源；绝对 URL/跨源/带 userinfo 一律拒绝。
+  const u = new URL(inner.url || '/', target);
+  const t = new URL(target);
+  if (u.protocol !== t.protocol || u.host !== t.host || u.username || u.password) {
+    throw new Error('proxy target must be same-origin');
+  }
+  const res = await fetch(u, {
+    method: inner.method || 'GET',
+    headers: stripHop(inner.headers),
+    body: inner.body ? Buffer.from(inner.body, 'base64') : undefined,
+  });
+  let buf = Buffer.from(await res.arrayBuffer());
+  // D 项 history 响应瘦身（docs/bug-report-phone-duplicate-stream.md §9.4-D）：
+  // session.history 响应含"该区间全部事件"（含每条消息的全部 chunk——实测 10 条消息
+  // ≈2.3 万事件 ≈4.3MB，密集会话尾页可达 10MB+），其中 chunk 对手机端历史重建零消费
+  // （消息级事件才是权威内容）却贡献 99% 字节与 JSON.parse 时间——进入会话加载变长的
+  // 主因。代理层剥掉 assistant/chunk（保留 hasMore/projections 等全部协议字段）。
+  if (inner.body) {
+    try {
+      const req = JSON.parse(Buffer.from(inner.body, 'base64').toString('utf8'));
+      if (req?.method === 'session.history') {
+        const full = JSON.parse(buf.toString('utf8'));
+        if (full?.result?.ok && Array.isArray(full.result.value?.events)) {
+          full.result.value.events = full.result.value.events.filter((e) => e?.event?.type !== 'assistant/chunk');
+          buf = Buffer.from(JSON.stringify(full));
+        }
+      } else if (req?.method === 'session.list') {
+        // 2026-08 性能：剥除 App 无消费的投影字段（goal/subagentTiming/subagent/plan/
+        // todos，实测合计约 21.5% 字节中的大头）——列表刷新体量与解析随会话数线性增长。
+        // 保留：title/sessionStats/tokenUsage/contextPressure/contextBreakdown/
+        // sessionListMetadata/imageLimits/permissions（详情页/聊天页/权限设定在用）
+        // + 全部顶层字段（cwd/running 等）。
+        const stripped = stripSessionListJson(buf.toString('utf8'));
+        buf = Buffer.from(stripped);
+        sessionTitles?.ingestSessionList(stripped); // 推送：顺手落 sessionId→title（title 未被剥除）
+      }
+    } catch {
+      /* 剥取失败按原样透传（绝不破坏响应） */
+    }
+  }
+  let body = buf.length ? buf.toString('base64') : null;
+  let enc = null;
+  if (buf.length >= COMPRESS_THRESHOLD) {
+    // C2（P2-8）：同步 deflateSync 会阻塞 dsh web 主线程（10MB+ history 响应数百 ms）——
+    // 改异步 deflate（promisify），大响应压缩不冻结宿主
+    body = (await zlibDeflate(buf)).toString('base64');
+    enc = 'deflate';
+  }
+  return {
+    status: res.status,
+    headers: Object.fromEntries(res.headers.entries()),
+    body,
+    enc,
+  };
+}
+
+export function connectConnector({ relayWsUrl, deviceToken, keys, keysFile, sessionKeys, target, localHandler, onRevoke, onConnection, onActivity, pendingApprovals, pushNotifier, sessionTitles, onPhoneOnlineChange, onAuthFailure, eventsDisabled = false, onFocus = null }) {
+  const guard = new ReplayGuard();
+  let backoff = 1000;
+  let dshStreams = [];
+  let stopped = false;
+  let currentWs = null;
+  let reconnectTimer = null;
+  // 2026-08 token 自愈：HELLO 认证被拒（token 过期/失效）标记，close 时触发 onAuthFailure
+  // 刷新 token，下次重连不再用过期 token 死循环
+  let authFailed = false;
+
+  // outSeq 持久化：启动时从 keys 领取（含 1000 预留窗口），崩溃/重启后新 seq 必高于
+  // 手机端记住的旧水位 → ReplayGuard 不会静默丢弃（Kimi Blocker 修复）。
+  // 运行中每次出站 seq = keys.outSeq++，500ms 防抖落盘。
+  const outSeqTimer = { current: null };
+  claimOutSeq(keys, keysFile, 1000);
+  const nextSeq = () => {
+    const seq = keys.outSeq++;
+    if (!outSeqTimer.current) {
+      outSeqTimer.current = setTimeout(() => {
+        outSeqTimer.current = null;
+        try { saveKeys(keys, keysFile); } catch {}
+      }, 500);
+    }
+    return seq;
+  };
+
+  // 每台手机的合批缓冲：phonePk -> { frames: [{text, sid, isChunk}], timer }
+  // 250ms 时间兜底 + 16 帧立即发（帧数优先）：Hermes 验签 4-10ms/帧，
+  // 峰值 54fps 时 60ms 窗口只攒 3-4 帧（降幅 3-4 倍，远低于"降 10-20 倍"目标）→
+  // 调大窗口 + 帧数优先（docs/bug-report-phone-duplicate-stream.md §2.1）。
+  // 2026-08 再调优（§9.4-F）：16 帧/批使多会话并行时批数减半（验签次数减半）；
+  // 250ms 兜底与手机端 flush 节奏对齐。手机端零改动（格式不变）。
+  // 连接级状态（按 phonePk 键控）：dsh web 事件流与 M4.x-c 本地事件（injectEvent）共用。
+  const batchBufs = new Map();
+  const BATCH_MS = 250;
+  const BATCH_MAX_FRAMES = 16;
+
+  // 方案C（省流）：手机 /events 在线门禁。默认"全在线"（安全方向：旧 relay 不发
+  // PHONE_STATE 帧时退化为现状；新手机配对后立即推送，等 relay 通知校正）。
+  // relay 在手机订阅建立/关闭及 connector HELLO 时下发 {phonePk, online} 快照，
+  // 离线手机不再合批推送——手机全离线时 connector 完全不上传事件（白省上行 + 加解密 CPU）。
+  const phoneOffline = new Set();
+
+  function setPhoneOnline(phonePk, online) {
+    if (!phonePk) return;
+    // C2（P2-5）：PHONE_STATE 仅接受已配对手机——恶意中继用随机 phonePk 刷状态帧
+    // 会导致 phoneOffline Set / phoneOnline Map 无界增长（内存 DoS）并静默停推
+    if (!sessionKeys.has(phonePk)) return;
+    if (online) {
+      phoneOffline.delete(phonePk);
+    } else {
+      phoneOffline.add(phonePk);
+      // 清掉该手机的积压缓冲：离线期间的帧已无意义（relay 无缓冲，恢复后由手机补拉兜底）
+      const b = batchBufs.get(phonePk);
+      if (b) {
+        if (b.timer) clearTimeout(b.timer);
+        batchBufs.delete(phonePk);
+      }
+    }
+    // 状态上抛（ConnectorCore 镜像 → 设置页设备列表"连接状态"提示）
+    onPhoneOnlineChange?.(phonePk, online);
+  }
+
+  function flushBatch(phonePk) {
+    // 定时器回调：任何异常都不能逃出（否则崩宿主进程）；缓冲清理必须先行
+    try {
+      const b = batchBufs.get(phonePk);
+      if (!b) return;
+      batchBufs.delete(phonePk);
+      if (b.timer) clearTimeout(b.timer);
+      const sessionKey = sessionKeys.get(phonePk);
+      if (!sessionKey) return;
+      const frames = b.frames.map((f) => f.text);
+      // 方案A（省流）：EVENT 合批包整体 deflate（明文侧压缩，封进密文后中继下行字节
+      // 同比例缩小）。reasoning/text delta 高度重复，deflate 通常 5-15×；
+      // 与 RES ≥4KB 同阈值同标记（enc:'deflate'），手机端 pako inflate（两端同步升级）。
+      // 格式：压缩 → {batch:true, enc:'deflate', data:<b64>}；未达阈值 → 原 {batch:true, frames}。
+      let batchInner;
+      const framesJson = JSON.stringify(frames);
+      if (framesJson.length >= COMPRESS_THRESHOLD) {
+        batchInner = JSON.stringify({ batch: true, enc: 'deflate', data: zlib.deflateSync(framesJson).toString('base64') });
+      } else {
+        batchInner = JSON.stringify({ batch: true, frames });
+      }
+      const env = sealEnvelope(
+        dirOf(sessionKey).down,
+        {
+          fromPublicKey: keys.identityPublicKey,
+          toPublicKey: phonePk,
+          seq: nextSeq(),
+          identitySecretKey: keys.identitySecretKey,
+        },
+        utf8(batchInner),
+      );
+      safeSend(currentWs, encode(TYPE.EVENT, 0, JSON.stringify(env)));
+    } catch {}
+  }
+
+  // 全量推送（H1 根治，docs/bug-report-phone-duplicate-stream.md §8.3-A）：
+  // 原按会话焦点过滤 chunk——"进入进行中的会话"焦点上报生效前、上报失败静默、
+  // connector 重启焦点内存丢失，都会静默丢弃该会话 chunk（思考前半/尾部永久缺失，
+  // 且进行中轮次不在 history、无法补拉）。移除过滤后：
+  //   · 内容完整性 > 省流：合批后批数不增（多会话帧打包进同一批）、解密次数不变；
+  //   · 手机端按 sessionId 分发天然隔离（非当前会话 chunk 解包即弃，不渲染）；
+  //   · 中继下行 EVENT 只计字节不计次数（M5.7），KB 级增量无计量影响；
+  //   · `_focus` 保留 ack（兼容旧版 App），但不再参与过滤。
+  function pushToBatch(phonePk, text) {
+    onActivity?.(phonePk);
+    let b = batchBufs.get(phonePk);
+    if (!b) {
+      b = { frames: [], timer: null, bytes: 0 };
+      batchBufs.set(phonePk, b);
+    }
+    b.frames.push({ text, sid: null, isChunk: false });
+    b.bytes += text.length;
+    if (!b.timer) {
+      b.timer = setTimeout(() => flushBatch(phonePk), BATCH_MS);
+    }
+    // 帧数优先：攒满 BATCH_MAX_FRAMES 立即发（峰值输出下延迟封顶 ~148ms，
+    // 不必等满 150ms 时间窗）；字节上限兜底：突发积压（如重连回放）时提前 flush，
+    // 避免超大信封
+    if (b.frames.length >= BATCH_MAX_FRAMES || b.bytes > 256 * 1024) {
+      if (b.timer) clearTimeout(b.timer);
+      flushBatch(phonePk);
+    }
+  }
+
+  function openDshStream(controlWs, url) {
+    let s;
+    try {
+      s = new WebSocket(url);
+    } catch {
+      return;
+    }
+    dshStreams.push(s);
+    // 主动关闭标记（缺陷 B 根治，见 docs/bug-report-phone-duplicate-stream.md §3）：
+    // startDshEvents 换流时置位再 close；close 处理器据此区分"主动换流"与"意外断开"——
+    // 否则每次控制面重连都会把旧流误判为意外断开而 +1s 重开，事件流 2→4→6…翻倍，
+    // 同一批事件从 N 条流双份/多份转发（碎片级 ×N 重复、N× 卡顿）。
+    s.intentional = false;
+    let b = 1000;
+
+    s.on('open', () => {
+      b = 1000;
+      // 方案 A（pending 审批缓存）：mux 重开时 DSH 会把全部 pending 审批/提问重放进
+      // 新队列（mux-open replay）——清空旧缓存等重放重建，避免 resolved 帧在断线窗口
+      // 丢失导致的陈旧条目残留
+      if (url.includes('events.mux')) pendingApprovals?.clear();
+    });
+
+    s.on('message', (data) => {
+      // ws 包可能以 Buffer 投递，统一转成字符串
+      const text = typeof data === 'string' ? data : Buffer.from(data).toString('utf8');
+      // 方案 A：镜像 pending 审批/提问（手机离线期间的事件被 relay 丢弃，重连后经
+      // mobile.approvals.list 拉取，与实时帧同路径分发）；非审批帧零成本跳过
+      pendingApprovals?.ingest(text);
+      // 推送：喂 sessionId→title 缓存（事件帧）+ 触发检测（只对离线手机，见 pushNotifier）
+      sessionTitles?.ingest(text);
+      pushNotifier?.ingest(text, phoneOffline);
+      // 全量推送（H1 根治，§8.3-A）：不做会话焦点过滤——进入会话瞬间/上报失败/
+      // connector 重启的焦点黑洞都会造成 chunk 永久缺失；手机端按 sessionId 分发隔离
+      // 方案C（省流）：跳过在线门禁判定的离线手机（relay 通知，见 setPhoneOnline）
+      for (const phonePk of sessionKeys.keys()) {
+        if (phoneOffline.has(phonePk)) continue;
+        pushToBatch(phonePk, text);
+      }
+    });
+    s.on('error', () => {});
+    s.on('close', () => {
+      // 连接关闭：清空合批缓冲
+      for (const b of batchBufs.values()) if (b.timer) clearTimeout(b.timer);
+      batchBufs.clear();
+      // 仅"意外断开"自动重开；主动换流（startDshEvents）不重开（缺陷 B 根治）
+      if (!s.intentional && !stopped && !controlWs.destroyed) {
+        setTimeout(() => openDshStream(controlWs, url), b);
+        b = Math.min(b * 2, 30000);
+      }
+    });
+  }
+
+  function startDshEvents(controlWs) {
+    for (const s of dshStreams) {
+      // 主动换流：先置标记再关闭，避免 close 处理器把它当意外断开重开（缺陷 B 根治）
+      try {
+        s.intentional = true;
+        s.close();
+      } catch {}
+    }
+    dshStreams = [];
+    // 2026-09：DSH 0.1.2 起 /api/events.mux|.host 已移除（改 /api/remote.mux）。connector 用
+    // 进程内 cordis 订阅注入事件（见 connector-core），不再连已死端点。
+    if (eventsDisabled) return;
+    const wsBase = target.replace(/^http/, 'ws');
+    for (const p of ['/api/events.mux', '/api/events.host']) openDshStream(controlWs, wsBase + p);
+  }
+
+  const connect = () => {
+    const ws = new WebSocket(relayWsUrl);
+    currentWs = ws;
+
+    // 心跳保活：检测半开连接（PC 断网时 close/error 可能不触发，靠 ping/pong 超时探测）
+    let alive = true;
+    let heartbeatTimer = null;
+    const stopHeartbeat = () => {
+      if (heartbeatTimer) clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    };
+    const startHeartbeat = () => {
+      alive = true;
+      stopHeartbeat();
+      heartbeatTimer = setInterval(() => {
+        if (!alive) {
+          // 上次 pong 未回来：连接已死（半开），强制断开以触发重连
+          console.warn('[connector] heartbeat timeout, terminating dead connection');
+          try { ws.terminate(); } catch {}
+          return;
+        }
+        alive = false;
+        try { ws.ping(); } catch {}
+      }, 30000); // 每 30s ping，60s 内无 pong 判死
+    };
+
+    ws.on('open', () => {
+      onConnection?.('connecting');
+      startHeartbeat();
+      // B3/D2：HELLO 用 keys 里最新的 deviceToken（短 TTL 在线续期后重连用新 token）
+      safeSend(ws, jsonFrame(TYPE.HELLO, 0, { deviceToken: keys.deviceToken || deviceToken }));
+    });
+    ws.on('pong', () => { alive = true; });
+    ws.on('error', (e) => {
+      stopHeartbeat();
+      console.error('[connector] ws error:', e.message);
+    });
+
+    ws.on('message', async (data) => {
+      let f;
+      try {
+        f = decodeFrame(data);
+      } catch {
+        return;
+      }
+
+      if (f.type === TYPE.HELLO_OK) {
+        // B9（P1-11）：畸形 HELLO_OK 不得逃逸异常崩宿主（async 回调 rejection → Node 默认退出）
+        try {
+          backoff = 1000;
+          onConnection?.('connected');
+          console.log('[connector] registered as', toJson(f.payload).deviceId, 'sessionKeys=', sessionKeys.size);
+          startDshEvents(ws);
+        } catch (e) {
+          console.error('[connector] bad HELLO_OK:', e?.message);
+        }
+        return;
+      }
+      if (f.type === TYPE.ERROR) {
+        try {
+          const msg = f.payload.toString('utf8');
+          console.error('[connector] relay error:', msg);
+          // 认证被拒（HELLO 用的 deviceToken 过期/失效）→ 标记，close 时刷新 token
+          if (/unauthorized/i.test(msg) || /not device/i.test(msg)) authFailed = true;
+        } catch {}
+        return;
+      }
+
+      if (f.type === TYPE.REVOKE) {
+        try {
+          const msg = toJson(f.payload);
+          const phonePk = msg.phonePk;
+          // A3/P0-2：REVOKE 必须携带手机身份私钥签名（relay 转发时已验签；本地再兜底验一次）。
+          // 无签名/验签失败 → 拒绝删除（中继/他人无法伪造 REVOKE）。
+          if (!phonePk || typeof msg.sig !== 'string' || !verifyUnpair(phonePk, msg.sig, { deviceId: keys.deviceId, phonePk, ts: String(msg.ts ?? '') })) {
+            throw new Error('bad revoke signature');
+          }
+          sessionKeys.delete(phonePk);
+          phoneOffline.delete(phonePk); // 会话密钥已删，门禁状态一并清理
+          onRevoke?.(phonePk);
+          console.log('[connector] revoked session key for', String(phonePk).slice(0, 8));
+        } catch {}
+        return;
+      }
+
+      // 方案C（省流）：手机 /events 上下线通知——离线手机停止合批推送。默认全在线
+      // （旧 relay 不发本帧时行为与现状一致）；HELLO 快照补齐 relay 重启后的陈旧状态。
+      if (f.type === TYPE.PHONE_STATE) {
+        try {
+          const msg = toJson(f.payload);
+          setPhoneOnline(msg.phonePk, msg.online === true);
+        } catch {}
+        return;
+      }
+
+      if (f.type === TYPE.REQ) {
+        // B8（P1-10）：入站 REQ 帧 payload 上限（恶意/失控中继超大帧 → OOM 宿主）
+        if (f.payload.length > MAX_REQ_FRAME) return;
+        try {
+          const env = toJson(f.payload);
+          const sessionKey = sessionKeys.get(env.from);
+          if (!sessionKey) {
+            // 无会话密钥（PC 端已解除配对 / 该手机从未配对过）：此前直接 throw，而 catch 里
+            // 也因无密钥封不了错误信封 → **静默丢弃** → relay 等 REQ_TIMEOUT(30s) → 手机端
+            // 得到不透明 504「电脑响应超时」。改为**立即**回一个可识别的明文错误
+            // （与下方 replay detected 同风格：错误本身不携带任何载荷/密文，中继只能看到
+            // "该手机未配对"），手机端 tunnelFetch 映射 'no session key' → UNPAIRED →
+            // 友好提示"请重新扫码配对"，无漫长等待。
+            safeSend(ws, encode(TYPE.RES, f.streamId, JSON.stringify({ __error: 'no session key' })));
+            return;
+          }
+          onActivity?.(env.from);
+          // A7（P0-6）：先验签解密成功，再推进防重放水位——
+          // 未认证帧（中继注入的垃圾 REQ）不能污染水位（否则受害手机后续合法帧全被拒）
+          const innerBytes = openEnvelope(dirOf(sessionKey).up, env);
+          if (!guard.check(env.from, env.seq)) {
+            // seq 回退（手机 App 重启后 5s 持久化窗口未落盘）：回包当前水位，
+            // 手机端据此快进 seq 并自动重试一次，用户无感
+            const errRes = { __error: 'replay detected', replayWatermark: guard.watermarkOf(env.from) };
+            safeSend(ws, encode(TYPE.RES, f.streamId, JSON.stringify(errRes)));
+            return;
+          }
+          const innerStr = utf8Decode(innerBytes);
+          let inner;
+          try {
+            inner = JSON.parse(innerStr);
+          } catch {
+            // A8：错误消息绝不携带解密内容（中继可见）
+            throw new Error('bad inner json');
+          }
+
+          // 控制帧：手机会话焦点上报（H1 根治后不再参与过滤，仅保留 ack 兼容旧版 App）
+          if (inner?.method === '_focus') {
+            const ack = sealEnvelope(
+              dirOf(sessionKey).down,
+              {
+                fromPublicKey: keys.identityPublicKey,
+                toPublicKey: env.from,
+                seq: nextSeq(),
+                identitySecretKey: keys.identitySecretKey,
+              },
+              utf8(JSON.stringify({ status: 200, body: null })),
+            );
+            safeSend(ws, encode(TYPE.RES, f.streamId, JSON.stringify(ack)));
+            // 2026-09：焦点上报 → connector 开 session/follow 流重构消息级实时（Phase 3）
+            try { onFocus?.(env.from, inner?.sessionId ?? null); } catch {}
+            return;
+          }
+
+          // M4.x-c：本地处理面（mobile.* RPC）。localHandler 返回 null 表示不接管，
+          // 回落通用反代（如 dsh web 自己的 /api 方法）。返回值与 replayInner 同构。
+          // phonePk（env.from）随请求传入：供权限门禁（fullDisk）按手机判定。
+          const local = localHandler ? await localHandler(inner, env.from) : null;
+          // raw-bytes 响应（mobile.files.download，方案 file-image-download-plan.md §4.2）：
+          // localHandler/bridge 以 {__raw: Uint8Array} 标记——以原始字节作信封明文展开
+          // （越过 utf8(JSON.stringify(...))，避开业务层 base64）。错误仍走下方 catch。
+          if (local && typeof local === 'object' && local.__raw instanceof Uint8Array) {
+            const rawEnv = sealEnvelope(
+              dirOf(sessionKey).down,
+              {
+                fromPublicKey: keys.identityPublicKey,
+                toPublicKey: env.from,
+                seq: nextSeq(),
+                identitySecretKey: keys.identitySecretKey,
+              },
+              local.__raw,
+            );
+            // 性能：raw-bytes 分块的信封对 ≥4KB deflate（base64 密文是 ASCII，可压缩；文本/二进制均省网 25-33%）。
+            // 与 replayInner 的 RES 压缩同标记（enc:'deflate'）；手机端 callBinary 先解压再 openEnvelope。
+            const envStr = JSON.stringify(rawEnv);
+            let out;
+            if (envStr.length >= COMPRESS_THRESHOLD) {
+              out = JSON.stringify({ enc: 'deflate', data: zlib.deflateSync(envStr).toString('base64') });
+            } else {
+              out = envStr;
+            }
+            safeSend(ws, encode(TYPE.RES, f.streamId, out));
+            return;
+          }
+          const innerRes = local ?? (await replayInner(target, inner, sessionTitles));
+          const resEnv = sealEnvelope(
+            dirOf(sessionKey).down,
+            {
+              fromPublicKey: keys.identityPublicKey,
+              toPublicKey: env.from,
+              seq: nextSeq(),
+              identitySecretKey: keys.identitySecretKey,
+            },
+            utf8(JSON.stringify(innerRes)),
+          );
+          safeSend(ws, encode(TYPE.RES, f.streamId, JSON.stringify(resEnv)));
+        } catch (e) {
+          // A8（P1-4）：错误响应密封为信封（down 方向密钥）且不回显任何载荷/明文片段——
+          // 中继只能看到密文，不能注入/读取错误通道内容；无会话密钥时静默（零泄露）。
+          let errEnv = null;
+          try {
+            const parsed = JSON.parse(f.payload.toString('utf8'));
+            const sk = sessionKeys.get(parsed.from);
+            if (sk) {
+              errEnv = sealEnvelope(
+                dirOf(sk).down,
+                {
+                  fromPublicKey: keys.identityPublicKey,
+                  toPublicKey: parsed.from,
+                  seq: nextSeq(),
+                  identitySecretKey: keys.identitySecretKey,
+                },
+                utf8(JSON.stringify({ __error: String(e?.message || 'internal') })),
+              );
+            }
+          } catch {}
+          if (errEnv) safeSend(ws, encode(TYPE.RES, f.streamId, JSON.stringify(errEnv)));
+        }
+      }
+    });
+
+    ws.on('close', () => {
+      stopHeartbeat();
+      onConnection?.('disconnected');
+      for (const s of dshStreams) {
+        try {
+          s.close();
+        } catch {}
+      }
+      dshStreams = [];
+      console.log('[connector] control closed, reconnect in', backoff, 'ms');
+      if (!stopped) {
+        // 认证失败：触发 token 自愈刷新（异步，更新 keys.deviceToken），并以较快退避重连
+        if (authFailed) {
+          authFailed = false;
+          backoff = 1000;
+          try {
+            Promise.resolve(onAuthFailure?.()).catch((e) =>
+              console.warn('[connector] auth-failure token refresh failed:', e?.message),
+            );
+          } catch {}
+        }
+        reconnectTimer = setTimeout(connect, backoff);
+        backoff = Math.min(backoff * 2, 30000);
+      }
+    });
+  };
+
+  // M4.x-c：本地事件注入面——bridge 的 mobile/event 帧从这里进入合批队列
+  // （与 dsh web 事件同一加密 EVENT 通道；广播给所有已配对手机，App 按 pluginId 过滤）。
+  // 方案C：离线手机同样跳过（在线门禁与 dsh 事件共用）。
+  function injectEvent(text) {
+    for (const phonePk of sessionKeys.keys()) {
+      if (phoneOffline.has(phonePk)) continue;
+      pushToBatch(phonePk, text);
+    }
+  }
+
+  connect();
+
+  const stop = () => {
+    stopped = true;
+    clearTimeout(reconnectTimer);
+    if (outSeqTimer.current) {
+      clearTimeout(outSeqTimer.current);
+      outSeqTimer.current = null;
+    }
+    for (const s of dshStreams) {
+      try {
+        s.close();
+      } catch {}
+    }
+    try {
+      currentWs?.close();
+    } catch {}
+  };
+  // 可调用 + 携带方法（connector-core 用 this._stopConnector?.() 停止，injectEvent 供 bridge 事件接线）
+  stop.injectEvent = injectEvent;
+  return stop;
+}