@dshfly/remote-connector 0.2.1

package/core/connector-core.js

@@ -0,0 +1,910 @@
+// packages/remote-connector/core/connector-core.js
+// ConnectorCore：把 connector 的核心逻辑（连接/E2EE/隧道/事件转发/配对/解除）抽成
+// 一个 GUI 无耦合、Node 可单测的类。自 services/connector/core.js 迁入（单一代码源，
+// 保留 M5.5 全部扩展）。Electron 主进程 / CLI / 插件 apply 都是它的消费者。
+
+import fs from 'node:fs';
+import os from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { loadOrCreateKeys, saveKeys } from './keys.js';
+import { createCloud } from './cloud.js';
+import { connectConnector } from './tunnel.js';
+import { PendingApprovalCache } from './pending-approvals.js';
+import { createSessionTitleCache } from './session-titles.js';
+import { createPushNotifier } from './push-notifier.js';
+import { guardPath } from './path-guard.js';
+import { deriveSessionKey, pairFingerprint, pairShortCode, signPairingConfirm, signDeviceLogin } from '@dshfly/crypto';
+
+// M4.x-c：mobile.* RPC 的本地适配器（spec §5.1 信封语义）。
+// 手机端把 mobile.* 当作普通 /api 方法调用（client-request 信封 + base64 body），
+// 本适配器在 connector 侧截获（tunnel 的 localHandler 只认 url 前缀），
+// 解析信封 → bridge.handleRpc → 组 server-response 回包。bridge 未接入时返回 null（回落反代）。
+const MOBILE_PREFIX = '/api/mobile.';
+
+/** PC 计算机名（去 .local 后缀；2026-08：手机端"我"页显示可读 PC 名）。 */
+function hostnameClean() {
+  return String(os.hostname() || '').replace(/\.local$/, '') || null;
+}
+
+/**
+ * 解析本地 JWT 的 exp（毫秒）。HS256 只需 base64url 解码 payload（不验签——本地 token，
+ * 签名是 relay 的，本地只看过期）。解析失败返回 null。
+ */
+function tokenExpiryMs(token) {
+  try {
+    const part = String(token || '').split('.')[1];
+    if (!part) return null;
+    const body = JSON.parse(Buffer.from(part.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8'));
+    return body?.exp ? body.exp * 1000 : null;
+  } catch {
+    return null;
+  }
+}
+
+/** cloud.call 抛的"token 失效/设备不存在"错误——需触发签名刷新重试。 */
+function isAuthError(e) {
+  const msg = String(e?.message || e);
+  // 401 = token 失效；404 'device not found' = 设备不在中继库（库被清/换库后旧 deviceId 失效）
+  //   → 同样触发刷新/重登记，否则 connector 一直拿着"未过期但已失效"的 1 年 TTL token 卡死在 404。
+  return /-> 401\b|\b401:|\bHTTP 401\b/i.test(msg) || /device not found/i.test(msg);
+}
+
+/** 续期提前量：token 剩余寿命少于该值时刷新（24h TTL 的一半 = 12h）。 */
+const TOKEN_REFRESH_LEAD_MS = 12 * 3600 * 1000;
+
+/** 组 HTTP 响应（与 replayInner 返回同构：status/headers/body(base64)/enc）。 */
+function httpJson(obj, status = 200) {
+  const body = Buffer.from(JSON.stringify(obj)).toString('base64');
+  return { status, headers: { 'content-type': 'application/json' }, body, enc: null };
+}
+
+/**
+ * 供 tunnel localHandler 使用；返回响应对象或 null（不接管）。
+ * opts.fullDisk：该手机的完整磁盘权限（缺省 true = 兼容旧版/未受限）；
+ * opts.resolveRoots：允许根提供者（已登记工作区 ∪ 主机 cwd）——受限手机的
+ * browse/mkdir 目标必须位于允许根内（2026-08 完整磁盘权限门禁）。
+ */
+export async function handleMobileLocal(bridge, inner, { fullDisk = true, resolveRoots = null } = {}) {
+  if (!inner?.url?.startsWith(MOBILE_PREFIX)) return null;
+  if (inner.method !== 'POST') {
+    return httpJson({ type: 'server-response', result: { ok: false, error: { code: 'INTERNAL', message: 'mobile.* 仅支持 POST' } } }, 405);
+  }
+  let req = null;
+  try {
+    req = JSON.parse(Buffer.from(inner.body || '', 'base64').toString('utf8'));
+  } catch {
+    return httpJson({ type: 'server-response', result: { ok: false, error: { code: 'INTERNAL', message: '请求信封解析失败' } } }, 400);
+  }
+  const method = req?.method;
+  // 完整磁盘权限门禁（P4/B2）：受限手机的 browse/mkdir/read/info/download 的**最终位置**必须在允许根内
+  // （即使手输路径）——browse/mkdir 判 path，read/info/download 判 root（它们的读取范围 = root 内）。
+  // fullDisk=true 时 guardPath 直接放行（null）。
+  const guardedMethod =
+    method === 'mobile.files.browse' || method === 'mobile.files.mkdir'
+      ? { path: req?.payload?.path }
+      : method === 'mobile.files.read' || method === 'mobile.files.info' || method === 'mobile.files.download'
+        ? { path: req?.payload?.root }
+        : null;
+  if (!fullDisk && guardedMethod && resolveRoots) {
+    let roots = [];
+    try {
+      roots = await resolveRoots();
+    } catch {
+      roots = [];
+    }
+    const code = await guardPath({ path: guardedMethod.path, fullDisk: false, roots });
+    if (code) {
+      // 业务错误用 200 + result.ok=false（与 bridge 其他错误一致）：手机端 call() 才能
+      // 解析出 error.code 显示友好文案；HTTP 非 2xx 会被传输层当"传输失败 HTTP xxx"吞掉错误码
+      return httpJson({
+        type: 'server-response',
+        rpcId: req?.rpcId ?? null,
+        result: { ok: false, error: { code, message: '目录在允许范围之外（PC 端可开启完整磁盘权限）' } },
+      });
+    }
+  }
+  try {
+    const value = await bridge.handleRpc(method, req?.payload ?? {});
+    // raw-bytes 响应（mobile.files.download，方案 file-image-download-plan.md §4.2）：
+    // bridge 以 {__raw: Uint8Array} 标记——此处直接回传该标记（不包 server-response JSON，
+    // 避免 JSON.stringify 把字节序列化成数字键对象），由 tunnel 检测后以原始字节作信封明文。
+    // 错误仍走下面 catch（files-too-large / files-not-found 等经 {__error} 回传）。
+    if (value && typeof value === 'object' && value.__raw instanceof Uint8Array) {
+      return { __raw: value.__raw };
+    }
+    return httpJson({ type: 'server-response', rpcId: req?.rpcId ?? null, result: { ok: true, value } });
+  } catch (e) {
+    // spec §5.3：错误码透传；INTERNAL 细节只进 PC 日志，不回传 App
+    const code = e?.code || 'INTERNAL';
+    if (code === 'INTERNAL') console.error(`[connector] mobile.* ${method} failed:`, e?.message);
+    return httpJson({
+      type: 'server-response',
+      rpcId: req?.rpcId ?? null,
+      result: { ok: false, error: { code, message: e?.message || code } },
+    });
+  }
+}
+
+export class ConnectorCore {
+  constructor({ relayUrl, deviceName, keysFile, target, controlPath = '/control', dshAdapter = null }) {
+    this.keys = loadOrCreateKeys(keysFile);
+    // 2026-09：DSH web 0.1.2 起 /api 需要 browser-session cookie 且协议结构性改动（斜杠端点、
+    // {args} 包装、事件走 remote.mux、/api/respond 移除）。connector 同进程 —— 改为进程内
+    // 直接调 DSH 的 typertGateway（免认证 + 免线协议）。dshAdapter 提供 invoke/事件订阅/审批结算。
+    this.dsh = dshAdapter;
+    this.cfg = {
+      // 中继地址：运行时修改（设置页"编辑"）持久化到 keys.relayUrl，重启后优先于插件配置
+      relayUrl: String(this.keys.relayUrl || relayUrl || '').replace(/\/$/, ''),
+      deviceName,
+      // D1（方案 B）：无账号层——loginName 字段彻底移除（keys.accountName 仅兼容旧 keys 文件）
+      keysFile,
+      target,
+      controlPath,
+    };
+    this.cloud = createCloud(this.cfg.relayUrl);
+    this.keys.lastUsed = this.keys.lastUsed || {};
+    this.sessionKeys = new Map(Object.entries(this.keys.sessionKeys || {}));
+    this.state = { connection: 'disconnected', deviceId: this.keys.deviceId || null };
+    /** 手机 /events 在线状态镜像（M5.12 方案C PHONE_STATE 回调驱动；
+     *  缺省=全在线——与 connector 门禁"默认全在线"语义一致，relay 快照到达后校正）。 */
+    this.phoneOnline = new Map(); // phonePk -> boolean
+    this.listeners = new Set();
+    this._saveTimer = null;
+    this._emitTimer = null;
+    this.mobileBridge = null; // M4.x-c：MobileBridge 服务（可选；由 setMobileBridge 接入）
+    this._tunnel = null;
+    this._bridgeUnsub = null;
+    /** 方案 A：pending 审批/提问镜像缓存（手机离线期间的审批经 mobile.approvals.list 补拉）。 */
+    this.pendingApprovals = new PendingApprovalCache();
+    /** 推送：sessionId→title 缓存 + 触发检测（只对离线手机）。 */
+    this.sessionTitles = createSessionTitleCache();
+    this.pushNotifier = createPushNotifier({
+      onNotify: (phonePk, kind, sessionId) => this._notifyPush(phonePk, kind, sessionId),
+    });
+    /**
+     * A0（S0）：配对中手机公钥缓存 pairingId -> {phoneIdPk, phoneTrPk, name}。
+     * 展示（短码）与派生（会话密钥）必须原子绑定同一份公钥——PC 确认页 GET pairing
+     * 时缓存，confirm 时用缓存值派生，绝不从 confirm 响应重新拉取（杜绝中继偷换）。
+     */
+    this._pendingPairKeys = new Map();
+    /** 完整磁盘权限门禁的允许根提供者（已登记工作区 ∪ 主机 cwd，loopback 实时取）。 */
+    // 完整磁盘权限门禁的允许根提供者（已登记工作区）。2026-09：一律走进程内 DSH 适配层取工作区
+    // （移除旧 loopback HTTP 兜底——升级后 workspace.list 端点已删除 + 需 cookie，会 401）；
+    // adapter 缺失/失败时 fail-closed 返回空根，使受限手机所有 files.* 被拒（安全方向）。
+    this._roots = async () => {
+      try {
+        if (!this.dsh) return [];
+        const r = await this.dsh.workspaceList();
+        return (r?.ok ? r.value?.items || [] : []).map((i) => i?.path).filter((p) => typeof p === 'string' && p);
+      } catch {
+        return [];
+      }
+    };
+    /** device token 刷新单飞（任意时刻最多一个刷新在跑，防并发竞态）。 */
+    this._tokenRefreshing = null;
+    /** 设备被中继主动撤销（不再自动重新登记；设置页醒目标识）。 */
+    this._deviceBlocked = null;
+    this._tokenTimer = null; // 续期定时器（按剩余寿命调度，替换旧的固定 12h setInterval）
+  }
+
+  onStateChange(cb) {
+    this.listeners.add(cb);
+    return () => this.listeners.delete(cb);
+  }
+
+  _emit() {
+    const s = this.getState();
+    for (const cb of this.listeners) {
+      try {
+        cb(s);
+      } catch {}
+    }
+  }
+
+  /** device token 健康状态（供 PC 设置页可见，提前预警而非 401 才去猜）。 */
+  getTokenState() {
+    if (this._deviceBlocked === 'revoked') return { state: 'revoked', expiringAt: null };
+    const t = this.keys.deviceToken;
+    if (!t || !this.keys.deviceId) return { state: 'unregistered', expiringAt: null };
+    const exp = tokenExpiryMs(t);
+    if (exp == null) return { state: 'unknown', expiringAt: null };
+    const left = exp - Date.now();
+    let state = 'ok';
+    if (left <= 0) state = 'expired';
+    else if (left < TOKEN_REFRESH_LEAD_MS) state = 'expiring';
+    return { state, expiringAt: exp };
+  }
+
+  getState() {
+    const devices = Object.entries(this.keys.sessionKeys || {}).map(([phonePk]) => ({
+      phonePk,
+      shortId: String(phonePk).slice(0, 8),
+      name: this.keys.deviceNames?.[phonePk] || null, // 手机上报的设备名（2026-08；缺省 null）
+      lastUsedAt: this.keys.lastUsed?.[phonePk] || null,
+      permission: this.getPermission(phonePk), // 完整磁盘权限（2026-08）
+      online: this.phoneOnline.get(phonePk) ?? true, // 手机 /events 在线状态（2026-08 M5.12）
+    }));
+    const tok = this.getTokenState();
+    return {
+      connection: this.state.connection,
+      deviceId: this.keys.deviceId || null,
+      hostname: hostnameClean(), // PC 计算机名（去 .local，2026-08：手机端显示可读 PC 名）
+      devices,
+      tokenState: tok.state, // device token 健康（2026-08 自愈）
+      deviceTokenExpiringAt: tok.expiringAt,
+    };
+  }
+
+  /** 手机权限（缺省最小权限：不允许完整磁盘）。 */
+  getPermission(phonePk) {
+    const p = this.keys.permissions?.[phonePk];
+    return { fullDisk: !!(p && p.fullDisk) };
+  }
+
+  /** 修改手机权限（PC 设置页设备列表；配对确认时写入）。 */
+  setPermission(phonePk, { fullDisk } = {}) {
+    if (!phonePk) return;
+    this.keys.permissions = this.keys.permissions || {};
+    this.keys.permissions[phonePk] = { fullDisk: !!fullDisk };
+    saveKeys(this.keys, this.cfg.keysFile);
+    this._emit();
+  }
+
+  /** 记录手机上报的设备名（配对后首次连接时上报；PC 设置页设备列表显示）。 */
+  setDeviceName(phonePk, name) {
+    if (!phonePk || typeof name !== 'string' || !name.trim()) return;
+    const clean = name.trim().slice(0, 64);
+    this.keys.deviceNames = this.keys.deviceNames || {};
+    if (this.keys.deviceNames[phonePk] === clean) return;
+    this.keys.deviceNames[phonePk] = clean;
+    saveKeys(this.keys, this.cfg.keysFile);
+    this._emit();
+  }
+
+  /** M5.12 方案C：relay PHONE_STATE 回调——手机 /events 订阅上下线，镜像进 getState().devices[].online。 */
+  _setPhoneOnline(phonePk, online) {
+    if (!phonePk) return;
+    this.phoneOnline.set(phonePk, !!online);
+    this._emit();
+  }
+
+  /** 手机焦点上报（2026-09 Phase 3）：开/关 session/follow 流重构消息级实时。 */
+  /** 当前离线手机集合（已配对且 phoneOnline 为 false）。供 pushNotifier 判定推送目标（只推离线手机）。 */
+  _offlinePhones() {
+    const set = new Set();
+    for (const pk of this.sessionKeys.keys()) {
+      if (this.phoneOnline.get(pk) === false) set.add(pk);
+    }
+    return set;
+  }
+
+  _setFocusSession(sessionId) {
+    this._followStop?.();
+    this._followStop = null;
+    this._focusSessionId = sessionId || null;
+    if (!sessionId || !this.dsh?.startSessionFollow || !this._tunnel) return;
+    this._followStop = this.dsh.startSessionFollow(sessionId, {
+      onFrames: (frames) => {
+        for (const f of frames) {
+          try {
+            this.sessionTitles?.ingest?.(JSON.stringify(f)); // 喂标题缓存（推送标题源；session/projection·event 帧）
+            this._tunnel.injectEvent(JSON.stringify(f));
+          } catch {}
+        }
+      },
+      onError: (e) => console.warn(`[dshfly-remote-connector] session/follow ${sessionId} error:`, e?.message),
+    });
+  }
+
+  /** 校验中继地址可达（GET /healthz）。返回错误文案或 null（可达）。
+  /** 校验中继地址可达（D1：GET /healthz——无账号层后无"登录"可探测；healthz 足够判可达）。 */
+  async checkRelay(url) {
+    const clean = String(url || '').trim();
+    if (!/^https?:\/\//.test(clean)) return '中继地址需以 http(s):// 开头';
+    try {
+      const res = await fetch(`${clean.replace(/\/$/, '')}/healthz`, { signal: AbortSignal.timeout(5000) });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      return null;
+    } catch (e) {
+      return `中继不可达或校验失败：${e?.message || '网络错误'}`;
+    }
+  }
+
+  /** 更换中继（2026-08，设置页"编辑"）：停旧连接 → 持久化 keys.relayUrl → 新中继
+   *  重新登记设备 → 重启隧道。⚠️ 中继间配对数据不共享：更换后已配对手机需在新中继
+   *  重新扫码配对。 */
+  async setRelayUrl(url) {
+    const clean = String(url || '').trim().replace(/\/$/, '');
+    if (!/^https?:\/\//.test(clean)) throw new Error('中继地址需以 http(s):// 开头');
+    if (clean === this.cfg.relayUrl) return this.getState();
+    this.stop();
+    this.cfg.relayUrl = clean;
+    this.keys.relayUrl = clean;
+    // 新中继上旧 deviceToken/deviceId 无效：强制重新登记（旧 relay 残留记录无害）
+    delete this.keys.deviceId;
+    delete this.keys.deviceToken;
+    this.state.deviceId = null;
+    saveKeys(this.keys, this.cfg.keysFile);
+    await this.start();
+    return this.getState();
+  }
+
+  async enroll() {
+    // D1（方案 B）：纯公钥登记（无账号层）——登记响应即 deviceToken
+    const reg = await this.cloud.registerDevice({
+      name: this.cfg.deviceName,
+      pk_identity: this.keys.identityPublicKey,
+      pk_transport: this.keys.transportPublicKey,
+    });
+    this.keys.deviceId = reg.deviceId;
+    this.keys.deviceToken = reg.deviceToken;
+    saveKeys(this.keys, this.cfg.keysFile);
+    this.state.deviceId = reg.deviceId;
+    this._emit();
+    return reg;
+  }
+
+  async ensureEnrolled() {
+    await this._ensureDeviceSession();
+  }
+
+  /** 保证本地有一份有效 deviceToken + deviceId（缺失/已过期/临近过期都会自愈）。 */
+  async _ensureDeviceSession(minSafeMs = TOKEN_REFRESH_LEAD_MS) {
+    const hasToken = !!this.keys.deviceToken;
+    const hasId = !!this.keys.deviceId;
+    if (!hasToken || !hasId) {
+      // D1（方案 B）：纯公钥登记（无账号层）——登记响应即 deviceToken
+      await this.enroll();
+      return { token: this.keys.deviceToken, deviceId: this.keys.deviceId, via: 'register' };
+    }
+    const exp = tokenExpiryMs(this.keys.deviceToken);
+    if (exp != null && exp - Date.now() > minSafeMs) {
+      // 有效且剩余寿命充足 → 直接复用
+      return { token: this.keys.deviceToken, deviceId: this.keys.deviceId, via: 'existing' };
+    }
+    return this._refreshDeviceToken();
+  }
+
+  /** device token 刷新（单飞）：优先 rotate（保 deviceId），失效/异常落 device-login，兜底 register。 */
+  _refreshDeviceToken() {
+    if (this._tokenRefreshing) return this._tokenRefreshing;
+    this._tokenRefreshing = this._doRefreshDeviceToken().finally(() => { this._tokenRefreshing = null; });
+    return this._tokenRefreshing;
+  }
+
+  async _doRefreshDeviceToken() {
+    const exp = tokenExpiryMs(this.keys.deviceToken);
+    // 1) 本地 token 尚有效（未过期）→ 先续期（rotate，最省、天然保 deviceId）
+    if (exp != null && exp > Date.now() && this.keys.deviceId) {
+      try {
+        const r = await this.cloud.rotateDeviceToken(this.keys.deviceToken, this.keys.deviceId);
+        this.keys.deviceToken = r.deviceToken;
+        saveKeys(this.keys, this.cfg.keysFile);
+        console.log(`[dshfly-remote-connector] device token rotated (deviceId=${this.keys.deviceId})`);
+        return { token: this.keys.deviceToken, deviceId: this.keys.deviceId, via: 'rotate' };
+      } catch (e) {
+        console.warn('[dshfly-remote-connector] token rotate failed, fallback device-login:', e?.message);
+      }
+    }
+    // 2) 过期或 rotate 失败 → device-login（身份签名；按身份公钥匹配回同一 deviceId）
+    const ts = Date.now();
+    const nonce = 'rt-' + randomBytes(6).toString('hex');
+    const sig = signDeviceLogin(this.keys.identitySecretKey, { publicKey: this.keys.identityPublicKey, ts, nonce });
+    try {
+      const r = await this.cloud.deviceLogin(this.keys.identityPublicKey, ts, nonce, sig);
+      this.keys.deviceToken = r.token;
+      if (r.deviceId) this.keys.deviceId = r.deviceId;
+      saveKeys(this.keys, this.cfg.keysFile);
+      console.log(`[dshfly-remote-connector] device token refreshed via device-login (deviceId=${this.keys.deviceId})`);
+      return { token: this.keys.deviceToken, deviceId: this.keys.deviceId, via: 'device-login' };
+    } catch (e) {
+      return this._fallbackEnroll(e);
+    }
+  }
+
+  /** device-login 失败降级：仅"身份无设备行"才重新登记（新 deviceId）；撤销态明确报错不自动登记。 */
+  async _fallbackEnroll(e) {
+    const msg = String(e?.message || e);
+    if (/device revoked/i.test(msg)) {
+      this._deviceBlocked = 'revoked';
+      console.error('[dshfly-remote-connector] PC 设备已被中继撤销，需重新初始化（不会自动重新登记）');
+      this._emit();
+      throw new Error('device revoked');
+    }
+    if (/identity not registered/i.test(msg)) {
+      console.warn('[dshfly-remote-connector] 设备行不存在（中继库被清/换中继）→ 重新登记（手机需重新扫码）');
+      await this.enroll(); // registerDevice -> 新 deviceId
+      return { token: this.keys.deviceToken, deviceId: this.keys.deviceId, via: 'register' };
+    }
+    throw e; // 网络等其余错误原样抛回，不误触发登记
+  }
+
+  /** 带 token 自愈的云端调用：token 失效（401）→ 刷新一次 → 重试一次。 */
+  async _callWithDeviceToken(fn) {
+    await this.ensureEnrolled();
+    try {
+      return await fn();
+    } catch (e) {
+      if (isAuthError(e)) {
+        console.warn('[dshfly-remote-connector] 云端返回 401（token 失效），刷新后重试');
+        await this._refreshDeviceToken();
+        return await fn();
+      }
+      throw e;
+    }
+  }
+
+  /** 接入 MobileBridge（M4.x-c，可选）：mobile.* RPC 本地处理 + 插件事件注入隧道。 */
+  setMobileBridge(bridge) {
+    this.mobileBridge = bridge;
+    this._wireMobileBridgeProviders();
+    if (this._tunnel && bridge?.onEvent) {
+      this._bridgeUnsub = bridge.onEvent((frame) => {
+        try {
+          this._tunnel.injectEvent(JSON.stringify(frame));
+        } catch {}
+      });
+    }
+  }
+
+  /** 方案 A + 2026-08：把 pending 审批缓存 / 中继用量查询接为 bridge 的数据源（幂等）。 */
+  _wireMobileBridgeProviders() {
+    if (this.mobileBridge?.setPendingApprovalProvider) {
+      this.mobileBridge.setPendingApprovalProvider(() => this.pendingApprovals.list());
+    }
+    if (this.mobileBridge?.setRelayUsageProvider) {
+      this.mobileBridge.setRelayUsageProvider(() => this._relayUsage());
+    }
+  }
+
+  /** 中继用量/配额（2026-08，quota-ux.md §5 定稿链路）：connector 持 deviceToken 查
+   *  relay GET /api/v1/usage（非计费只读——查询不落 /tunnel 计次，额度用尽后仍可查）。
+   *  返回 { plan, quota, used, resetAt, quotaDisabled }；quota=null 表示不限量。 */
+  async _relayUsage() {
+    const doFetch = async () => {
+      const res = await fetch(`${this.cfg.relayUrl}/api/v1/usage`, {
+        headers: { authorization: `Bearer ${this.keys.deviceToken}` },
+        signal: AbortSignal.timeout(5000),
+      });
+      if (!res.ok) throw new Error(`relay usage: HTTP ${res.status}`);
+      return res.json();
+    };
+    if (!this.keys.deviceToken || !this.cfg.relayUrl) {
+      throw new Error('relay usage: 未登记或未配置中继');
+    }
+    return this._callWithDeviceToken(doFetch);
+  }
+
+  /** 推送触发：connector → relay /push/notify（fire-and-forget，绝不阻塞事件流）。 */
+  _notifyPush(phonePk, kind, sessionId) {
+    const title = this.sessionTitles.titleOf(sessionId) ?? null;
+    // 2026-08 角标：携带当前待确认数（pending 审批/提问），relay 透传到推送 payload。
+    // ⚠️ 必须 Math.max(...,1)：**任何一次推送都代表"有事件要通知"**（尤其"会话完成"这类
+    // 通常没有 pending 审批 → 原逻辑算出 0），角标为 0 则通知/桌面角标不显示。取 max 保证
+    // 有推送就有角标；App 存活时仍以自己的 badgeCount 为准（更准）。
+    const pendingCount = this.pendingApprovals ? this.pendingApprovals.list().frames.length : 0;
+    const badge = Math.max(pendingCount, 1);
+    // 推送类日志不显示（避免刷屏）；失败仍静默——需要时可临时加回或经日志分级
+    this._callWithDeviceToken(() =>
+      this.cloud.notifyPush(this.keys.deviceToken, { phonePk, kind, title, sessionId, badge }),
+    ).then(() => {}).catch(() => {});
+  }
+
+  /**
+   * 隧道 localHandler：mobile.* 本地 RPC（含完整磁盘权限门禁）+ workspace.create 反代拦截。
+   * 返回响应对象或 null（不接管 → 回落通用反代）。
+   */
+  async _mobileLocal(inner, phonePk) {
+    if (inner?.url?.startsWith('/api/mobile.')) {
+      // PC 信息（2026-08）：手机端补拉计算机名（覆盖已配对手机，免重新配对）
+      if (inner?.url === '/api/mobile.getPcInfo') {
+        let req = null;
+        try {
+          req = JSON.parse(Buffer.from(inner.body || '', 'base64').toString('utf8'));
+        } catch {
+          return null;
+        }
+        return httpJson({
+          type: 'server-response',
+          rpcId: req?.rpcId ?? null,
+          result: { ok: true, value: { hostname: hostnameClean() } },
+        });
+      }
+      // 设备名上报（2026-08）：手机配对后首次连接时上报系统设备名，PC 设置页设备列表显示
+      if (inner?.url === '/api/mobile.setDeviceName') {
+        let req = null;
+        try {
+          req = JSON.parse(Buffer.from(inner.body || '', 'base64').toString('utf8'));
+        } catch {
+          return null;
+        }
+        this.setDeviceName(phonePk, req?.payload?.name);
+        return httpJson({
+          type: 'server-response',
+          rpcId: req?.rpcId ?? null,
+          result: { ok: true, value: { name: this.keys.deviceNames?.[phonePk] || null } },
+        });
+      }
+      if (!this.mobileBridge) return null;
+      return handleMobileLocal(this.mobileBridge, inner, {
+        fullDisk: this.getPermission(phonePk).fullDisk,
+        resolveRoots: this._roots,
+      });
+    }
+    // workspace.create 反代拦截（A6/P0-5）：受限手机的目标路径必须在允许根内（即使手输也受限）。
+    // 门禁判定改用【信封 body 的 method】（先解析），不再用 URL 字符串精确匹配——
+    // `/api/workspace.create?x=1`、`%2e` 编码、重复斜杠等 URL 拼写变体无法绕过门禁
+    // （HTTP 路由通常按 pathname 匹配并忽略 query，字符串匹配依赖下游路由行为，不安全）。
+    if (!this.getPermission(phonePk).fullDisk && inner?.url?.startsWith('/api/workspace.create')) {
+      let req = null;
+      try {
+        req = JSON.parse(Buffer.from(inner.body || '', 'base64').toString('utf8'));
+      } catch {
+        // 信封解析失败：明确业务错误（不再回落旧 HTTP 反代 → 401/404）
+        return httpJson({ type: 'server-response', rpcId: null, result: { ok: false, error: { code: 'bad-envelope', message: 'dshfly: request envelope parse failed', details: {} } } });
+      }
+      if (req?.method === 'workspace.create') {
+        return this._guardWorkspaceCreate(inner);
+      }
+    }
+    // 2026-09：其余 /api 方法 → 进程内 DSH 适配层（斜杠端点 + {args} 包装 + 免 HTTP 认证）。
+    // 不再回落 HTTP 反代（升级后那需要 browser-session cookie 且端点已改名）。
+    if (this.dsh && inner?.url?.startsWith('/api/')) {
+      let req = null;
+      try {
+        req = JSON.parse(Buffer.from(inner.body || '', 'base64').toString('utf8'));
+      } catch {
+        return httpJson({ type: 'server-response', rpcId: null, result: { ok: false, error: { code: 'bad-envelope', message: 'dshfly: request envelope parse failed', details: {} } } });
+      }
+      const method = req?.method;
+      // /api/respond：手机端应答是 {type:'client-response', rpcId, result}，**没有 method 字段**，
+      // 必须按 URL 判定（req.method==='respond' 恒为 false 会漏掉 → 落回已废的 HTTP 反代）。
+      if (inner?.url === '/api/respond' || method === 'respond') {
+        // 2026-09：/api/respond 已被 DSH 移除（审批/提问走 waterfall）。connector 以 $events
+        // 客户端身份经 $events/result 结算手机端的应答（resolveRespond）。
+        // ⚠️ 回执形状对齐旧 /api/respond：手机端 respondReceiptAction 判 receipt.accepted===true
+        // （→close）或 accepted===false && reason==='not-pending'（→close）才关卡片。
+        try {
+          const r = await this.dsh.resolveRespond(req);
+          if (r.ok && r.resolvedFrame) {
+            try {
+              const text = JSON.stringify(r.resolvedFrame);
+              // 剪枝缓存：手机端自己批时，网关不会向"此客户端"广播 cancel → 残留陈旧条目
+              // 会让后续 mobile.approvals.list（syncApprovals on open）重拉重弹卡片。
+              this.pendingApprovals?.ingest?.(text);
+              this._tunnel?.injectEvent(text);
+            } catch {}
+          }
+          if (r.ok) return httpJson({ accepted: true });
+          if (r.error?.code === 'approval-not-found') return httpJson({ accepted: false, reason: 'not-pending' });
+          console.warn('[dshfly-remote-connector] respond not settled:', r.error?.code, r.error?.message);
+          return httpJson({ accepted: false, reason: 'bad-response' });
+        } catch (e) {
+          console.warn('[dshfly-remote-connector] respond resolve failed:', e?.message);
+          return httpJson({ accepted: false, reason: 'internal' });
+        }
+      }
+      if (method && !method.startsWith('mobile.')) {
+        try {
+          const r = await this.dsh.invoke(method, req?.payload ?? {});
+          // 2026-09：session.list 不再走 HTTP 反代（replayInner），推送标题源改由此处喂
+          if (method === 'session.list' && r?.ok) {
+            try { this.sessionTitles?.ingestSessionList?.(JSON.stringify({ result: { ok: true, value: r.value } })); } catch {}
+          }
+          return httpJson({
+            type: 'server-response',
+            rpcId: req?.rpcId ?? null,
+            result: r.ok ? { ok: true, value: r.value } : { ok: false, error: r.error },
+          });
+        } catch (e) {
+          return httpJson({
+            type: 'server-response',
+            rpcId: req?.rpcId ?? null,
+            result: { ok: false, error: { code: 'INTERNAL', message: e?.message || String(e) } },
+          });
+        }
+      }
+    }
+    // 2026-09：DSH /api 已全部由适配层接管。此兜底仅当 this.dsh 缺失（测试/降级）时回 null（旧行为）；
+    // 否则对未接管请求返回明确业务错误，绝不回落旧 HTTP 反代（会 401/404）。
+    if (this.dsh) {
+      return httpJson({
+        type: 'server-response',
+        rpcId: null,
+        result: { ok: false, error: { code: 'unhandled', message: 'dshfly: unhandled DSH request', details: {} } },
+      });
+    }
+    return null;
+  }
+
+  async _guardWorkspaceCreate(inner) {
+    let req = null;
+    try {
+      req = JSON.parse(Buffer.from(inner.body || '', 'base64').toString('utf8'));
+    } catch {
+      // 信封解析失败：明确业务错误（不再回落旧 HTTP 反代 → 401/404）
+      return httpJson({ type: 'server-response', rpcId: null, result: { ok: false, error: { code: 'bad-envelope', message: 'dshfly: request envelope parse failed', details: {} } } });
+    }
+    let roots = [];
+    try {
+      roots = await this._roots();
+    } catch {
+      roots = [];
+    }
+    const code = await guardPath({ path: req?.payload?.path, fullDisk: false, roots });
+    // 在允许根内：放行 —— 进程内 DSH 适配层执行（不再回落 HTTP 反代，见 _mobileLocal 注释）
+    if (!code && this.dsh) {
+      try {
+        const r = await this.dsh.invoke('workspace.create', req?.payload ?? {});
+        return httpJson({
+          type: 'server-response',
+          rpcId: req?.rpcId ?? null,
+          result: r.ok ? { ok: true, value: r.value } : { ok: false, error: r.error },
+        });
+      } catch (e) {
+        return httpJson({
+          type: 'server-response',
+          rpcId: req?.rpcId ?? null,
+          result: { ok: false, error: { code: 'INTERNAL', message: e?.message || String(e) } },
+        });
+      }
+    }
+    if (!code) return null; // 兼容：无 adapter 时回落反代（旧行为）
+    // 业务错误用 200 + result.ok=false（同 handleMobileLocal 门禁）：错误码可被手机端解析
+    return httpJson({
+      type: 'server-response',
+      rpcId: req?.rpcId ?? null,
+      result: { ok: false, error: { code: 'workspace-permission-denied', message: '此目录在允许范围之外（PC 端可开启完整磁盘权限）' } },
+    });
+  }
+
+  /** 连接中继并维持；连接状态 / 设备活动 / 会话密钥热加载都从这里驱动。 */
+  async start() {
+    await this.ensureEnrolled();
+    // ALB 多实例（2026-09）：/control 也带 ?deviceId= 作一致性哈希路由键（metering §6.6-6.7）。
+    // relay 侧 hint 校验是"带了必须与 deviceToken.sub 一致"，keys.deviceId 与 deviceToken 同源，天然通过。
+    const wsUrlBase = this.cfg.relayUrl.replace(/^http/, 'ws') + this.cfg.controlPath;
+    const wsUrl = `${wsUrlBase}${wsUrlBase.includes('?') ? '&' : '?'}deviceId=${encodeURIComponent(this.keys.deviceId ?? '')}`;
+    this._tunnel = connectConnector({
+      relayWsUrl: wsUrl,
+      deviceToken: this.keys.deviceToken,
+      keys: this.keys,
+      keysFile: this.cfg.keysFile,
+      sessionKeys: this.sessionKeys,
+      target: this.cfg.target,
+      // M4.x-c：mobile.* 本地截获（bridge 未接入时 handleMobileLocal 恒返回 null，行为同旧版）；
+      // 2026-08：完整磁盘权限门禁——受限手机的 browse/mkdir/workspace.create 目标必须在
+      // 允许根内（phonePk 由 tunnel 随请求传入）
+      localHandler: (inner, phonePk) => this._mobileLocal(inner, phonePk),
+      onRevoke: (phonePk) => this._removeSessionKey(phonePk),
+      onConnection: (status) => {
+        this.state.connection = status;
+        this._emit();
+      },
+      onActivity: (phonePk) => this._markUsed(phonePk),
+      pendingApprovals: this.pendingApprovals, // 方案 A：事件流上镜像 pending 审批/提问
+      pushNotifier: this.pushNotifier, // 推送：审批/完成触发检测（对离线手机）
+      sessionTitles: this.sessionTitles, // 推送：sessionId→title 缓存（喂 session.list + 事件帧）
+      // M5.12 方案C：手机 /events 在线状态回调（设置页设备列表"连接状态"提示的数据源）
+      onPhoneOnlineChange: (phonePk, online) => this._setPhoneOnline(phonePk, online),
+      // 2026-08 token 自愈：控制 WS HELLO 认证被拒（token 过期/失效）时触发签名刷新，
+      // 让下一次重连带着有效 token——否则会用过期 token 反复重连死循环
+      onAuthFailure: () => this._refreshDeviceToken(),
+      // 2026-09：DSH 事件不再走 /api/events.mux|.host（已移除）。有 dshAdapter 时事件由
+      // 进程内订阅注入隧道，tunnel 不再连已死端点。
+      eventsDisabled: !!this.dsh,
+      // 2026-09 Phase 3：手机端焦点上报 → 开/关 session/follow 流重构消息级实时
+      onFocus: (phonePk, sessionId) => this._setFocusSession(sessionId),
+    });
+    this._stopConnector = this._tunnel;
+    // bridge 在 start 之后才接入（插件 apply 时序）：补挂事件注入 + 审批缓存数据源
+    if (this.mobileBridge?.onEvent) {
+      this._bridgeUnsub = this.mobileBridge.onEvent((frame) => {
+        try {
+          this._tunnel.injectEvent(JSON.stringify(frame));
+        } catch {}
+      });
+    }
+    this._wireMobileBridgeProviders();
+
+    // 2026-09：DSH 0.1.2 起 /api/events.mux|.host 已移除（事件改 remote.mux）。connector 以
+    // DSH $events 远程流客户端身份运行（进程内 openRemoteEvents）：接收 api-session/* emit +
+    // approval/request + user-questions/request 瀑布，转成手机端帧经合批通道注入隧道。
+    // 同时让 tunnel 不再连已死的 events 端点（tunnel.js 的 eventsDisabled）。
+    if (this.dsh?.startEventPump) {
+      this._eventsStop = this.dsh.startEventPump({
+        onFrames: (frames) => {
+          for (const f of frames) {
+            try {
+              const text = JSON.stringify(f);
+              this.pendingApprovals?.ingest?.(text); // 镜像进 cache（syncApprovals 离线/重连补拉）
+              // 2026-09：事件已不走 events.mux（eventsDisabled）→ 推送触发器改由进程内事件泵喂：
+              // approval/requested·question/requested（审批）与 host/session-status（完成）都在 pump 帧上。
+              this.pushNotifier?.ingest?.(text, this._offlinePhones());
+              this.sessionTitles?.ingest?.(text);
+              this._tunnel?.injectEvent(text);
+            } catch {}
+          }
+        },
+        onResolved: (frame) => {
+          try {
+            const text = JSON.stringify(frame);
+            this.pendingApprovals?.ingest?.(text); // resolved 帧按 approvalId/questionRpcId 剪枝
+            this._tunnel?.injectEvent(text);
+          } catch {}
+        },
+        onError: (e) => console.warn('[dshfly-remote-connector] events pump error:', e?.message),
+      });
+    }
+
+    // B3/D2：deviceToken 短 TTL（24h）在线续期。改为**按剩余寿命调度**（替换固定 12h
+    // setInterval）：进程重启/冷启动不再"从此刻再数 12h"（会复用过期的旧 token），
+    // 而是到期前 LEAD 提前量主动续期；refresh 走 _refreshDeviceToken（rotate→device-login
+    // →register 兜底），不再 catch{} 静默吞错。
+    this._scheduleTokenRefresh();
+
+    // pair 完成后写回 keys 文件，常驻进程热加载新会话密钥
+    fs.watchFile(this.cfg.keysFile, { interval: 1000 }, () => {
+      try {
+        const fresh = JSON.parse(fs.readFileSync(this.cfg.keysFile, 'utf8'));
+        this.sessionKeys.clear();
+        for (const [k, v] of Object.entries(fresh.sessionKeys || {})) this.sessionKeys.set(k, v);
+        this.keys.sessionKeys = fresh.sessionKeys || {};
+        this.keys.lastUsed = fresh.lastUsed || {};
+      } catch {}
+      this._emit();
+    });
+  }
+
+  /** 按 device token 剩余寿命调度下一次续期（失败时短间隔重试）。 */
+  _scheduleTokenRefresh(retryDelayMs = null) {
+    if (this._tokenTimer) clearTimeout(this._tokenTimer);
+    this._tokenTimer = null;
+    const exp = tokenExpiryMs(this.keys.deviceToken);
+    let delay = retryDelayMs;
+    if (delay == null) {
+      if (exp != null) {
+        // 剩余寿命 - LEAD 即为续期时刻；至少留 60s 兜底（token 已过期会 60s 后再试）
+        delay = Math.max(60 * 1000, exp - Date.now() - TOKEN_REFRESH_LEAD_MS);
+      } else {
+        delay = 12 * 3600 * 1000; // 无 exp（异常）退回固定周期
+      }
+    }
+    this._tokenTimer = setTimeout(async () => {
+      let ok = false;
+      try {
+        if (!this.keys.deviceToken || !this.keys.deviceId) {
+          this._scheduleTokenRefresh(12 * 3600 * 1000);
+          return;
+        }
+        await this._refreshDeviceToken();
+        ok = true;
+      } catch (e) {
+        console.warn('[dshfly-remote-connector] token refresh failed:', e?.message);
+      } finally {
+        // 成功按新 exp 重新调度；失败短间隔重试（默认 5min）
+        this._scheduleTokenRefresh(ok ? null : 5 * 60 * 1000);
+      }
+    }, delay);
+    this._tokenTimer.unref?.();
+  }
+
+  _markUsed(phonePk) {
+    this.keys.lastUsed[phonePk] = Date.now();
+    clearTimeout(this._saveTimer);
+    this._saveTimer = setTimeout(() => saveKeys(this.keys, this.cfg.keysFile), 500);
+    // 状态通知防抖：_markUsed 随每条事件调用（合批前 54-150/s），直接 _emit 会打满 Electron tray
+    clearTimeout(this._emitTimer);
+    this._emitTimer = setTimeout(() => this._emit(), 1000);
+  }
+
+  _removeSessionKey(phonePk) {
+    delete this.keys.sessionKeys[phonePk];
+    this.sessionKeys.delete(phonePk);
+    this.phoneOnline.delete(phonePk); // 已解除配对的设备不再有连接状态
+    if (this.keys.lastUsed) delete this.keys.lastUsed[phonePk];
+    saveKeys(this.keys, this.cfg.keysFile);
+    this._emit();
+  }
+
+  /** 新建配对：返回二维码内容（deep link + 二维码图片 data URL），手机扫码后可调用 confirmPairing 完成。 */
+  async createPairing() {
+    const p = await this._callWithDeviceToken(() => this.cloud.createPairing(this.keys.deviceToken));
+    const fp = pairFingerprint(this.keys.identityPublicKey, this.keys.transportPublicKey);
+    // D1（方案 B）：deep link 不再携带账号名（无账号层；手机配对前无凭证，扫码即授权）
+    const deepLink = `dshpair://${new URL(this.cfg.relayUrl).host}/p/${p.pairingId}?fp=${fp}`;
+    let qrDataUrl = null;
+    try {
+      const { default: QRCode } = await import('qrcode');
+      qrDataUrl = await QRCode.toDataURL(deepLink, { margin: 1, width: 240 });
+    } catch {}
+    return { pairingId: p.pairingId, fp, deepLink, qrDataUrl };
+  }
+
+  /**
+   * 配对状态（http-api 用）。A0：completed 时缓存手机公钥并计算短码——
+   * 未 pin 过的设备返回 shortCode（用户与手机屏幕比对）；已 pin 返回 known:true（免码）。
+   * 返回 st 附带 shortCode/phoneName/known 字段。
+   */
+  async getPairingStatus(pairingId) {
+    const st = await this.cloud.getPairing(pairingId);
+    if (st.status === 'completed' && st.phone?.pk_identity && st.phone?.pk_transport) {
+      // A0：拉取即缓存（展示的与派生的必须是同一份公钥）
+      this._pendingPairKeys.set(pairingId, {
+        phoneIdPk: st.phone.pk_identity,
+        phoneTrPk: st.phone.pk_transport,
+        name: st.phone.name || null,
+      });
+      const pinned = !!this.keys.pinnedPhones?.[st.phone.pk_identity];
+      st.shortCode = pinned ? null : pairShortCode(st.phone.pk_identity, st.phone.pk_transport);
+      st.phoneName = st.phone.name || null;
+      st.known = pinned;
+    }
+    return st;
+  }
+
+  /** 完成配对（用户在 GUI 点「确认」后调用）：确认 + 派生会话密钥 + 持久化。
+   *   opts.fullDisk：完整磁盘权限（2026-08，缺省 false=不允许；配对后可在设置页修改）。
+   *   A0/A2：PC 身份签名 confirm；用【已缓存/已展示】的手机公钥派生；首次 TOFU pin。 */
+  async confirmPairing(pairingId, { fullDisk = false } = {}) {
+    let keys = this._pendingPairKeys.get(pairingId);
+    if (!keys) {
+      // 兜底（autoConfirm/未先轮询）：拉取并缓存
+      const st = await this.cloud.getPairing(pairingId);
+      if (st.status !== 'completed' || !st.phone?.pk_identity || !st.phone?.pk_transport) {
+        throw new Error(`pairing not confirmable (${st.status})`);
+      }
+      keys = { phoneIdPk: st.phone.pk_identity, phoneTrPk: st.phone.pk_transport, name: st.phone.name || null };
+      this._pendingPairKeys.set(pairingId, keys);
+    }
+    // A2：PC 身份私钥签名（relay 用设备登记的 PC 公钥验签，中继不能冒充确认）
+    const sig = signPairingConfirm(this.keys.identitySecretKey, { pairingId, deviceId: this.keys.deviceId });
+    await this._callWithDeviceToken(() => this.cloud.confirmPairing(this.keys.deviceToken, pairingId, { sig }));
+    // A0：用已缓存公钥派生（绝不重新拉取）
+    const sk = deriveSessionKey(this.keys.transportSecretKey, keys.phoneTrPk);
+    this.keys.sessionKeys = this.keys.sessionKeys || {};
+    this.keys.sessionKeys[keys.phoneIdPk] = sk;
+    this.sessionKeys.set(keys.phoneIdPk, sk);
+    // TOFU pin（首次）
+    this.keys.pinnedPhones = this.keys.pinnedPhones || {};
+    this.keys.pinnedPhones[keys.phoneIdPk] = Date.now();
+    this.setPermission(keys.phoneIdPk, { fullDisk });
+    saveKeys(this.keys, this.cfg.keysFile);
+    this._emit();
+    this._pendingPairKeys.delete(pairingId);
+    return keys.phoneIdPk;
+  }
+
+  /** 拒绝配对：PC 身份签名（relay 验签，中继不能伪造拒绝）。 */
+  async rejectPairing(pairingId) {
+    const sig = signPairingConfirm(this.keys.identitySecretKey, { pairingId, deviceId: this.keys.deviceId });
+    return this._callWithDeviceToken(() => this.cloud.rejectPairing(this.keys.deviceToken, pairingId, { sig }));
+  }
+
+  /** 解除某台手机的配对（本地删除会话密钥；手机下次请求会收到 no session key 并提示重配）。 */
+  async unpair(phonePk) {
+    this._removeSessionKey(phonePk);
+  }
+
+  /** 停止：关闭连接、停掉热加载监听（Electron 退出 / 测试收尾时调用）。 */
+  stop() {
+    this._followStop?.();
+    this._followStop = null;
+    this._eventsStop?.();
+    this._eventsStop = null;
+    this._eventsUnsub?.();
+    this._eventsUnsub = null;
+    this._bridgeUnsub?.();
+    this._bridgeUnsub = null;
+    this._stopConnector?.();
+    if (this._rotateTimer) clearInterval(this._rotateTimer);
+    this._rotateTimer = null;
+    if (this._tokenTimer) clearTimeout(this._tokenTimer);
+    this._tokenTimer = null;
+    if (this._saveTimer) clearTimeout(this._saveTimer);
+    if (this._emitTimer) clearTimeout(this._emitTimer);
+    try {
+      fs.unwatchFile(this.cfg.keysFile);
+    } catch {}
+  }
+}