dsh-mobile-plugin 0.1.100 → 0.2.1

package/lib/relay/tunnel.js

@@ -15,6 +15,7 @@ const { WebSocket } = require('ws');
 const { T, jsonFrame, encodeFrame, createFrameDecoder, parseJson, encodeClosePayload, decodeClosePayload } = require('./protocol.js');
 const { isFreshRequest } = require('../shared/fresh-request');
 const { encodeJsonBody } = require('../shared/http-util');
+const { withViaHeader } = require('../shared/via-header');
 
 const HEARTBEAT_INTERVAL_MS = 15_000;
 // Relay currently expires an idle tunnel after 60s. Keep a wider client-side
@@ -43,7 +44,7 @@ class RelayTunnel {
    * @param {object} opts
    * @param {string} opts.relayUrl  隧道 WSS 地址（含 /tunnel），如 wss://relay.example.com/tunnel
    * @param {string} opts.instanceId
-   * @param {string} opts.pairingCode
+   * @param {string} [opts.pairingCode] 仅本进程自用（面板显示）；**不发往中转**，见 registrationPayload
    * @param {string} [opts.name]
    * @param {string[]} [opts.lanUrls] LAN sidecar candidates (metadata only)
    * @param {object[]} [opts.lanCandidates] LAN candidate metadata (metadata only)
@@ -60,7 +61,7 @@ class RelayTunnel {
   constructor(opts) {
     this.relayUrl = opts.relayUrl;
     this.instanceId = opts.instanceId;
-    this.pairingCode = opts.pairingCode;
+    this.pairingCode = opts.pairingCode || '';
     this.name = opts.name || '';
     this.lanUrls = Array.isArray(opts.lanUrls) ? opts.lanUrls.slice() : [];
     this.lanCandidates = Array.isArray(opts.lanCandidates) ? opts.lanCandidates.slice() : [];
@@ -387,19 +388,28 @@ class RelayTunnel {
   }
 
   /**
-   * 更新配对码：先更新本地，再经已建立的隧道通知中转（旧码即刻失效）。
-   * 若隧道尚未连接，register 首条消息会携带新码（register 读取 this.pairingCode）。
+   * 更新配对码。
+   *
+   * **不再告诉中转**（§5.2）。中转那边从来没用过它 —— `ws.rs` 写明「不保存也不校验
+   * 注册帧里的实例号 / 配对码」，唯一的用处是控制台准入校验的 `license` 字段。删掉之后
+   * 「中转看得见配对码」这个既成事实就不存在了，而这一轮之后配对码本身也不再是
+   * 新协议的凭证（票据才是）。
+   *
+   * 保留这个方法只因为 `updateRegistration` 那条路还在用它更新本地值。
    */
   updatePairingCode(code) {
     this.pairingCode = code;
-    if (this.connected) this.sendJson(T.updatePairing, 0, { pairingCode: code });
   }
 
-  /** 注册帧的载荷。连接建立时发一次，之后元信息变了再由 updateRegistration 重发。 */
+  /**
+   * 注册帧的载荷。连接建立时发一次，之后元信息变了再由 updateRegistration 重发。
+   *
+   * **不带配对码**（§5.2）：中转从来没读过它，而带上它就等于把「谁能配这台机器」的
+   * 一半凭证交给链路上的第三方。删掉零成本。
+   */
   registrationPayload() {
     return {
       instanceId: this.instanceId,
-      pairingCode: this.pairingCode,
       name: this.name,
       // 可选：与中转端 TUNNEL_REGISTER_SECRET 对应，防止他人抢注 instanceId。
       ...(this.registerSecret ? { secret: this.registerSecret } : {}),
@@ -582,7 +592,7 @@ class RelayTunnel {
         // 读取隔离：命中本地快照时也走有界发送队列，避免快照响应在buffer高水位时丢帧。
         // 例外：带 ?fresh=1 的写后刷新必须回源（判定与实测见 lib/shared/fresh-request.js）。
         if (this.readSnapshot && !isFreshRequest(msg.path) && (msg.method === 'GET' || msg.method === undefined)) {
-          const body = this.readSnapshot({ method: msg.method, path: msg.path });
+          const body = this.readSnapshot({ method: msg.method, path: msg.path, headers: msg.headers });
           if (body && body.ok) {
             // 这条捷径回的是列表 / 工作区 / 消息 / 统计这几条最重的读取，压缩的收益全在这儿。
             const encoded = encodeJsonBody(JSON.stringify(body), msg.headers?.['accept-encoding']);
@@ -606,11 +616,7 @@ class RelayTunnel {
             port: this.upstream.port,
             method: msg.method,
             path: msg.path,
-            headers: {
-              ...(msg.headers || {}),
-              // 保留手机端原始 Host（信任围栏按 Host 判定）；缺省回退本地上游
-              host: (msg.headers && msg.headers.host) || this.upstream.host,
-            },
+            headers: withViaHeader(msg.headers, 'relay', this.upstream.host),
           },
           (res) => {
             entry.res = res;
@@ -749,7 +755,7 @@ class RelayTunnel {
     const url = `ws://${this.upstream.host}${path}`;
     let client;
     try {
-      client = new WebSocket(url, { headers });
+      client = new WebSocket(url, { headers: withViaHeader(headers, 'relay', this.upstream.host) });
     } catch (err) {
       if (!this.cancelledWs.has(id)) this.sendJson(T.wsError, id, { message: err.message });
       return;

package/lib/routes/control-plane.js

@@ -256,6 +256,13 @@ function registerControlPlaneRoutes(deps) {
     // 路由住在代里 —— 代被换掉之后服务还在，接口也就跟着活下来。
     // 缺省返回 null：`lib/impl.js` 单独挂载时（测试 / 老宿主）没有外壳，如实报不可用。
     getPluginRuntime = () => null,
+    /**
+     * 收掉某台设备已经开着的 SSE 流（吊销时用）。
+     *
+     * token 换了只保证「下一次请求」被拒，已经开着的流不会自己停。缺省返回 0（老宿主 /
+     * 测试里没有流登记）：那时吊销仍然对下一次请求生效，只是收不了在途的流。
+     */
+    dropDeviceStreams = () => 0,
   } = deps;
   const selfCheck = createSelfCheck({
     ctx,
@@ -293,6 +300,48 @@ function registerControlPlaneRoutes(deps) {
     // 不能等到第一次 status 轮询（那之前设备行画不出图标）。被拒时不给，没有意义。
     return sendJson(res, 200, { data: { approved: decision.approved, reason: decision.reason, ...(decision.approved ? pairingApproval.hostPlatform() : {}) } })
   } })
+  /**
+   * 旁路子进程的签发通道（§3.7）。局域网配对跑在旁路里，而凭据库只有一个写方 —— 主进程。
+   * 旁路把「给这台设备签一枚」交到这里，主进程落盘后把凭据回给它。
+   *
+   * 身份同 `/internal/approval`：sidecarToken，不走 localOnly。
+   */
+  registerRoute({ kind: 'exact', path: '/api/relay/internal/issue-credential', handler: async (req, res) => {
+    if (req.headers.authorization !== `Bearer ${sidecarToken}`) return sendJson(res, 401, { error: 'unauthorized' })
+    let body = {}
+    try { body = (await readJson(req)) || {} } catch { body = {} }
+    const device = body.device && typeof body.device === 'object' ? body.device : {}
+    const extra = body.extra && typeof body.extra === 'object' ? body.extra : {}
+    try {
+      const issued = credentials.issue(state.instanceId, device, '', undefined, extra)
+      return sendJson(res, 200, { data: issued })
+    } catch (error) {
+      return sendJson(res, 500, { ok: false, error: { code: 'internal', message: String(error?.message || error) } })
+    }
+  } })
+  /**
+   * 局域网配对成功之后换码 + 换票据（§5.1）的内部通道。
+   *
+   * 为什么需要一条内部路由：局域网代理跑在旁路子进程里，换码要写宿主的状态文件，而**唯一
+   * 能写的地方是主进程**。旁路配对成功后发一条到这里，主进程落盘、再让旁路重读。
+   * 身份同 `/internal/approval`：sidecarToken，不走 localOnly（没有本机 socket 可言）。
+   *
+   * 少了这条，局域网配对成功后码与票据都还是旧的 —— 截图里那张二维码长期有效，而它里面
+   * 是整条链路的密钥，正是 §8.10 第 3 条要堵的那条。旁路那边一句 `.catch(() => {})`
+   * 会把 404 吞掉，现场只表现为「配完还能拿旧图再配一次」。
+   */
+  registerRoute({ kind: 'exact', path: '/api/relay/internal/rotate-pairing', handler: async (req, res) => {
+    if (req.headers.authorization !== `Bearer ${sidecarToken}`) return sendJson(res, 401, { error: 'unauthorized' })
+    let next
+    try {
+      next = core.rotatePairing(state)
+    } catch (error) {
+      return sendJson(res, 500, { ok: false, error: { code: 'internal', message: String(error?.message || error) } })
+    }
+    // 落盘之后要让旁路重读：它手上那份还是旧码旧票，不推下去等于只换了主进程那一份。
+    try { await syncSidecar() } catch { /* 旁路不可达时下次 configure 会带上新值 */ }
+    return sendJson(res, 200, { ok: true, data: next })
+  } })
   // 控制面状态里额外带上面板页的绝对地址：客户端半边（lib/client.js）那一项现在只是
   // 一个「打开配置页面」的入口，链接必须是绝对的（原因见 panelUrlOf）。地址只在这里
   // 补，不动 createStatusView —— 那份 JSON 手机端也在读，127.0.0.1 的地址对它没意义。
@@ -318,9 +367,9 @@ function registerControlPlaneRoutes(deps) {
    * ——读到的是浏览器拦截，不是真实耗时，而且会把可用入口误判成不通。宿主是本机进程，
    * 出站没有 CORS 可言，测出来的才是用户实际能用的那条。
    *
-   * 判定与 App 探活一致：打 `/healthz`，2xx/3xx 即通，耗时从发出到收完响应头。
-   * 超时的照实报 `null`（前端按「不通」排在后面），不编造数字——这一条早先整个是 mock，
-   * 用户看到「测速结果」其实是随机数，选中的地址可能根本不存在。
+   * 判定分两步：`/healthz` 回 2xx **且** `/api/mobile/v1/health` 回的 `service` 是 `dsh-mobile-relay`。
+   * 只看 `/healthz` 不行——任何静态站都可能回 200，随手敲一个域名就被当成「可用中转」。
+   * 超时的照实报 `null`（前端按「不通」排在后面），不编造数字。
    */
   registerRoute({ kind: 'exact', path: '/api/relay/probe-relays', handler: localOnly('POST', async (req, res) => {
     const body = await readJson(req)
@@ -336,10 +385,21 @@ function registerControlPlaneRoutes(deps) {
         const controller = new AbortController()
         const timer = setTimeout(() => controller.abort(), RELAY_PROBE_TIMEOUT_MS)
         const response = await fetch(`${url}/healthz`, { signal: controller.signal, redirect: 'follow' })
-        clearTimeout(timer)
         // 读完响应体再停表：只等到响应头会把「连得上但发不出东西」算成很快。
-        await response.text().catch(() => '')
-        return response.ok ? { url, ms: Date.now() - started } : { url, ms: null }
+        const text = await response.text().catch(() => '')
+        if (!response.ok) {
+          clearTimeout(timer)
+          return { url, ms: null }
+        }
+        // **只认运维意义上「这一台确实是中转」**：`/healthz` 回 200 的站点满互联网都是，
+        // 光看它等于把 qq.com 也当可用中转（2026-10-24 用户实测随手敲一个就过）。
+        // 中转自己那条地址体检 `/api/mobile/v1/health` 会带回 `service`，对不上就不是它。
+        const who = await fetch(`${url}/api/mobile/v1/health`, { signal: controller.signal, redirect: 'follow' })
+          .then((r) => (r.ok ? r.json() : null))
+          .catch(() => null)
+        clearTimeout(timer)
+        if (!who || who.service !== 'dsh-mobile-relay') return { url, ms: null }
+        return { url, ms: Date.now() - started, service: who.service, version: who.version }
       } catch {
         return { url, ms: null }
       }
@@ -453,13 +513,40 @@ function registerControlPlaneRoutes(deps) {
     if (!guard) return sendJson(res, 200, { ok: true, installed: false, faults: [], stats: null })
     return sendJson(res, 200, { ok: true, installed: true, faults: guard.faults(), stats: guard.stats() })
   }) })
-  registerRoute({ kind: 'exact', path: '/api/relay/pairing', handler: localOnly('GET', async (_req, res) => {
+  registerRoute({ kind: 'exact', path: '/api/relay/pairing', handler: localOnly('GET', async (req, res) => {
+    // **二维码只在本机屏幕上出现**。
+    //
+    // 二维码里现在装的是一次性票据 —— 用它能派生出整条链路的密钥。而「经中转/局域网
+    // 代理转发来的请求在判据眼里长得像本机」这件事已经被实测证实过，所以这条不能只靠
+    // `localOnly`；它要的是**可信本机界面**这个更强的判据（socket 回环 + Host 回环 +
+    // 没有任何代理来源头）。网页管理窗口（两小时窗口那套）打开时能看到设备列表，但看
+    // 不到这张码 —— 窗口本身是从浏览器发起的，`trustedLocalUi` 对它不成立。
+    //
+    // 拿不到就回 423 而不是 403：面板那边据此显示「请在这台电脑上打开面板」，
+    // 也**不给**「点这里强制显示」——那等于把刚堵上的口子又开一遍。
+    if (typeof trustedLocalUi !== 'function' || !trustedLocalUi(req)) {
+      return sendJson(res, 423, {
+        ok: false,
+        error: { code: 'pairing_local_only', message: '配对二维码只在本机屏幕显示，请在这台电脑上打开面板' },
+      })
+    }
     if (!state.enabled) {
       sendJson(res, 409, { ok: false, error: '请先启用远程控制并保存配置' })
       return
     }
     await resolveLanPort()
-    const { payload, text } = pairingPayload(state, lanPortInUse())
+    /**
+     * `?relayUrl=` 是**只看不写**的预览：按这个候选地址生成二维码，但一个字都不落盘。
+     *
+     * 给「自建中转填完就想看到码」用（2026-10-24 用户要求）。以前那版是「填完就把地址写进
+     * 配置」，等于拿一条还没验过的地址覆盖正在用的设置；现在预览走这里，真写入只在用户
+     * 明确按下「连接中转」时发生。
+     */
+    const preview = typeof req.url === 'string' ? new URL(req.url, 'http://local').searchParams.get('relayUrl') : null
+    const source = preview && /^https?:\/\/[^\s]+$/i.test(preview.trim())
+      ? { ...state, relayUrl: preview.trim().replace(/\/+$/, '') }
+      : state
+    const { payload, text } = pairingPayload(source, lanPortInUse())
     if (!payload.relayUrl && payload.lanUrls.length === 0) {
       sendJson(res, 409, { ok: false, error: '没有可用的局域网或中转连接地址' })
       return
@@ -509,6 +596,44 @@ function registerControlPlaneRoutes(deps) {
     core.saveState(state)
     sendJson(res, 200, status())
   }) })
+  /**
+   * 已绑定的设备列表（§3.4）。
+   *
+   * 只回「面板画一行需要的东西」，**不回 `hash` / `hostToken`** —— 那些是凭据材料，
+   * 面板只是显示谁连着、什么时候来的。
+   *
+   * 与二维码那条不一样，这条**进** `WEB_ACCESS_ROUTES`：设备列表里没有密钥材料，
+   * 两小时窗口打开时能看、能踢是它的用途；而二维码里是整条链路的密钥，绝不能。
+   *
+   * `serverNow` 是给面板算「几分钟前」用的：手机与宿主的时钟可能差得多，但面板只需要
+   * 一个同一台机器上的基准。
+   */
+  registerRoute({ kind: 'exact', path: '/api/relay/devices', handler: localOnly('GET', async (_req, res) => {
+    sendJson(res, 200, {
+      ok: true,
+      serverNow: Date.now(),
+      devices: credentials.listDevices(state.instanceId),
+    })
+  }) })
+
+  /**
+   * 解除一台设备的绑定（§3.4）。
+   *
+   * 吊销该 deviceId 下所有仍有效的记录 —— 同一台手机重配过几次就是几条，只吊最新那条
+   * 等于旧的还能用。已建立的 SSE 要主动断开：token 换了只保证「下一次请求」被拒，
+   * 一条已经开着的流不会自己停。
+   */
+  registerRoute({ kind: 'exact', path: '/api/relay/devices/revoke', handler: localOnly('POST', async (req, res) => {
+    const body = await readJson(req)
+    const deviceId = body && typeof body.deviceId === 'string' ? body.deviceId.trim() : ''
+    if (!deviceId) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '缺少 deviceId' } })
+    const revoked = credentials.revokeDevice(state.instanceId, deviceId)
+    // 已建立的流主动收掉：否则被踢的设备还能继续收消息直到它自己重连。
+    let closed = 0
+    try { closed = typeof dropDeviceStreams === 'function' ? dropDeviceStreams(deviceId) : 0 } catch { /* 尽力 */ }
+    return sendJson(res, 200, { ok: true, revoked, closed })
+  }) })
+
   registerRoute({ kind: 'exact', path: '/api/relay/revoke-all', handler: localOnly('POST', async (_req, res) => {
     // 清除所有授权 = 中转清空本实例全部设备授权 + 本机吊销局域网设备凭据 +
     // 轮换 lanSecret/配对码。三处都要做：只清中转的话，同网设备仍能用旧的
@@ -540,6 +665,10 @@ function registerControlPlaneRoutes(deps) {
     if (typeof body?.preferredLanAddress === 'string' && body.preferredLanAddress.length <= 64) {
       patch.preferredLanAddress = body.preferredLanAddress.trim()
     }
+    // 用户手填的直连地址（内网穿透域名 / 公网 IP）。空串合法 = 清掉，理由同上。
+    if (typeof body?.manualLanUrl === 'string' && body.manualLanUrl.length <= 200) {
+      patch.manualLanUrl = body.manualLanUrl.trim().replace(/\/+$/, '')
+    }
     await settings.update(patch)
     await syncSidecar().catch(() => undefined)
     sendJson(res, 200, status())
@@ -817,10 +946,11 @@ const WEB_ACCESS_ROUTES = new Set([
   '/api/relay/panel/setup',
   '/api/relay/panel/settings',
   '/api/relay/faults',
-  '/api/relay/pairing',
   '/api/relay/toggle',
   '/api/relay/regenerate',
   '/api/relay/onboarded',
+  '/api/relay/devices',
+  '/api/relay/devices/revoke',
   '/api/relay/revoke-all',
   '/api/relay/config',
   '/api/relay/check-port',

package/lib/routes/mobile-api.js

@@ -20,7 +20,7 @@
  */
 
 const { sendJson } = require('../http/routing.js');
-const { orderCandidates } = require('../relay/lan-network.cjs');
+const { orderCandidates, withManualCandidate } = require('../relay/lan-network.cjs');
 
 const sessions = require('../mobile/sessions.js');
 const sessionModelOptions = require('../mobile/session-model-options.js');
@@ -43,13 +43,17 @@ const subagents = require('../mobile/subagents.js');
 const monitor = require('../mobile/monitor.js');
 const references = require('../mobile/references.js');
 const schedule = require('../mobile/schedule.js');
-const plugins = require('../mobile/plugins.js');
+const pushNotifyRoute = require('../mobile/push-notify-route.js');const plugins = require('../mobile/plugins.js');
 const pluginUpdate = require('../mobile/plugin-update.js');
+const pluginSelf = require('../mobile/plugin-self.js');
+const { createRelayControlHandlers } = require('../mobile/relay-control.js');
 const uploads = require('../mobile/uploads.js');
 const inboxClean = require('../mobile/inbox-clean.js');
 const git = require('../mobile/git.js');
 const pairing = require('../mobile/pairing.js');
 const { credentialsEntry } = require('../shared/credentials-entry.js');
+const { handleCredentialUpgrade } = require('../mobile/credential-upgrade.js');
+const extensions = require('../mobile/extensions.js');
 // 体检接口要自报身份：版本号只有一个来源，就是包自己的 package.json（与 relay/status.js 同）。
 const pkg = require('../../package.json');
 const desktopView = require('../desktop-view.cjs');
@@ -83,19 +87,33 @@ const API_VERSION = '1';
  *   一次拒绝或一次握手。
  */
 function registerMobileRoutes(deps) {
-  const { registerRoute, registerUpgradeRoute, guarded, state, hostMetadata, getSidecarSnapshot, safeLanCandidates, safeIpv6Candidates, lanPortInUse, preview, core, pairingApproval } = deps;
+  const { registerRoute, registerUpgradeRoute, guarded, state, hostMetadata, getSidecarSnapshot, safeLanCandidates, safeIpv6Candidates, lanPortInUse, preview, core, pairingApproval, rotatePairing } = deps;
   const route = (path, handler) => registerRoute({ kind: 'exact', path, handler: guarded(handler) })
+  // 中转配置那一组要**装配期已有的实例**（config store、sidecar 生命周期），不能靠模块级
+  // 单例去拿：同一进程里两份 relay.json 的真值只会打架。所以这里按装配层给的依赖建一次。
+  const relayControl = createRelayControlHandlers(deps.relayControl || {})
 
   registerRoute({ kind: 'exact', path: '/api/mobile/v1/status', handler: guarded(async (_ctx, _req, res) => {
     // 内存 `state` 是本进程唯一的真值。旧实现这里 `loadRelayState()` 重新读盘，
     // 于是同一份状态出现两个来源：控制面改完内存立刻返回，而移动端读到的还是
     // 上一次落盘的内容（多实例/慢盘时甚至永久不一致）。
+    //
+    // `relayUrl` 挂在这条上，是因为**这里每台设备每 30 秒必发一发**（它是判断设备在不在线
+    // 的心跳，与用户选的通道档位无关）。用户在插件里改了中转地址之后，手机手上还攥着旧
+    // 地址，而旧中转上没有这台电脑、只会回「那台不在线」——它能学到新地址的唯一机会，
+    // 是在还连得上宿主的那些时刻（局域网 / IPv6）从宿主嘴里听到。`/connection-info` 也有
+    // 这个字段，但它只在「先探到一条局域网或 IPv6 地址」时才会被问，而「只走公网」那一档
+    // 恰恰把这两条通道全排除了，于是那条路对她永远不会走。
+    //
+    // 所以这条不是「多带一个字段」，它是「改了地址之后，非局域网用户也能自己恢复」的那
+    // 一发。`enabled` 关掉时给 null，表示「这台机器没有中转」，与「地址是空的」区分开。
     sendJson(res, 200, {
       ok: true,
       apiVersion: API_VERSION,
       instanceId: state.instanceId || null,
       name: state.name || null,
       remoteEnabled: Boolean(state.enabled),
+      relayUrl: state.enabled ? (state.relayUrl || null) : null,
       ...hostMetadata(),
     })
   }) })
@@ -135,6 +153,8 @@ function registerMobileRoutes(deps) {
       lanCandidates: safeLanCandidates,
       ipv6Candidates: safeIpv6Candidates,
       lanPort: lanPortInUse,
+      // 配对成功即换码 + 换票据（§5.1）：谁截了二维码，那张图从这一刻起就没用了。
+      rotatePairing,
       log: (...args) => console.warn('[dsh-mobile-plugin] [pair]', ...args),
     }),
   })
@@ -142,11 +162,29 @@ function registerMobileRoutes(deps) {
   // 纯局域网配对（App 只扫到局域网二维码、完全不经中转）需要一个宿主自己回答的地址，
   // 否则 App 拿不到 lanCandidates，换网卡后就再也找不到这台机器；中转在中间时这条
   // 同样转发到这里，所以两条链路走的是同一份实现。
-  // 设备凭据吊销。**由宿主应答，中转只转发**——「哪台设备还能用」是宿主的判断。
-  // App 那边是尽力而为的调用（失败不阻断本地删除），所以这里回 ok 即可：
-  // 凭据库里的记录本身带有 TTL，残留会自然过期。
-  route('/api/mobile/v1/device-credential/revoke', async (_ctx, _req, res) => {
-    sendJson(res, 200, { ok: true })
+  // 设备凭据吊销 —— **手机自己解绑**这条路（§3.3）。由宿主应答，中转只转发：
+  // 「哪台设备还能用」是宿主的判断。
+  //
+  // 旧实现回一句 `{ok:true}` 什么都不做：手机点了「删除设备」、本地删干净了，宿主那份
+  // 凭据还活着，那枚 token 在到期之前仍然能用。这里按**这次请求出示的那一枚**吊销，
+  // 不是按 deviceId —— 手机手上只有自己的凭据，让它报 deviceId 等于允许吊销别人。
+  route('/api/mobile/v1/device-credential/revoke', async (_ctx, req, res) => {
+    const presented = req.headers['x-dsh-device-credential']
+      ? String(req.headers['x-dsh-device-credential'])
+      : (/^Bearer\s+([^\s]+)$/.exec(req.headers.authorization || '') || [])[1]
+    const store = credentialsEntry()
+    const instanceId = String(state.instanceId || '')
+    const revoked = presented ? store.revoke(presented, instanceId) : false
+    // 尽力而为的语义不变：手机那边失败也不阻断本地删除，所以这里始终回 ok，
+    // 但把「到底吊销了一张没有」如实带上 —— 排查「删了还能用」时这一格是唯一线索。
+    sendJson(res, 200, { ok: true, revoked })
+  })
+
+  // 旧会话升级成 T1（§3.3）：新 App 每次启动幂等调一次。判据、密钥归属与「为什么密钥
+  // 只能明文上行一次」都在 mobile/credential-upgrade.js 的文件头里。
+  route('/api/mobile/v1/device-credential/upgrade', async (_ctx, req, res) => {
+    // 必须 await：这条路要现读请求体（明文老会话的字节还挂在 socket 上，见 handler 文件头）。
+    await handleCredentialUpgrade(req, res, { instanceId: String(state.instanceId || ''), store: credentialsEntry() })
   })
 
   route('/api/mobile/v1/connection-info', async (_ctx, _req, res) => {
@@ -155,8 +193,10 @@ function registerMobileRoutes(deps) {
     const port = typeof lanPortInUse === 'function' ? lanPortInUse() : state.lanPort
     // 用户在面板上选过的「手机优先用这条」（设置项 `preferredLanAddress`）在这里同样兑现：
     // 手机是按顺序挨个试的，所以只挪顺序、不删候选。选的那条不在了就退回宿主排序。
+    // 手填的直连地址再盖到最前面：那是用户明确指定的那条，`preferredLanAddress` 只调网卡候选
+    // 的顺序，不该把它压到后面。
     const candidates = state.lanEnabled
-      ? orderCandidates(safeLanCandidates(port), state.preferredLanAddress)
+      ? withManualCandidate(orderCandidates(safeLanCandidates(port), state.preferredLanAddress), state.manualLanUrl)
       : []
     // IPv6 直连候选：单独一份、**不参与**上面的排序 —— 它和中转谁更快只有手机实测得出，
     // 宿主无从判断对端走哪条路由。与局域网那份同一个开关管（那条监听挂在同一个代理上），
@@ -185,6 +225,10 @@ function registerMobileRoutes(deps) {
   // 带 `?rev=` 条件刷新。它要替掉原生那边每 8 秒一发的完整清单（那份还得为 20 个
   // 会话各读一次 history 补预览），见 mobile/monitor.js。
   route('/api/mobile/v1/monitor', monitor.handleMonitor)
+  // iOS 推送令牌上报：App 把 APNs 令牌交给宿主，宿主经隧道帧转交中转落表。中转没配
+  // 密钥时那头静默忽略——这条路由照常回 ok，「推没推成」不是 App 要操心的事。
+  // 判据（要不要收这个令牌）与配对同一把锁：guarded 已核过设备身份。
+  route('/api/mobile/v1/push-token', pushNotifyRoute.createPushTokenHandler({ pushNotify: deps.pushNotify }))
   route('/api/mobile/v1/session', sessions.handleSession)
   route('/api/mobile/v1/session/messages', sessions.handleMessages)
   route('/api/mobile/v1/session/attachment', sessions.handleSessionAttachment)
@@ -334,6 +378,33 @@ function registerMobileRoutes(deps) {
   // 经 typertGateway 命名空间 pluginInventory 取，见 mobile/plugins.js。
   route('/api/mobile/v1/plugins', plugins.handlePlugins)
 
+  // 这台设备上的**中转与连接配置**（见 mobile/relay-control.js）。
+  //
+  // 这些项从前只有一个入口：电脑上的当机面板（`/api/relay/*`，全部 localOnly）。于是
+  // 「手机上发现连不上、想改个中转地址」必须回电脑前坐下才能做，而那往往正是人不在电脑前
+  // 的时候。它们与装/卸插件不是一类东西：**不会让插件代码变**，最坏只是这台从网上找不到，
+  // 而重连的主动权在手机这一侧。所以能力面有意放开给已配对设备。
+  //
+  // 改地址 / 关遥控 / 吊销 / 重连 / 重启后台服务这五条会掐断承载本请求的那条隧道，全部
+  // 「先回包再动手」，结果靠重连后读状态判 —— 与下面 `/plugin/update/apply` 同一个手感。
+  route('/api/mobile/v1/relay/config', relayControl.handleRelayConfig)
+  route('/api/mobile/v1/relay/config/save', relayControl.handleRelayConfigSave)
+  route('/api/mobile/v1/relay/enabled', relayControl.handleRelayToggle)
+  route('/api/mobile/v1/relay/pairing-code', relayControl.handleRelayRegenerate)
+  route('/api/mobile/v1/relay/revoke-all', relayControl.handleRelayRevokeAll)
+  route('/api/mobile/v1/relay/reconnect', relayControl.handleRelayReconnect)
+  route('/api/mobile/v1/relay/restart-sidecar', relayControl.handleRelayRestartSidecar)
+  route('/api/mobile/v1/relay/check-port', relayControl.handleRelayCheckPort)
+  route('/api/mobile/v1/relay/probe', relayControl.handleRelayProbe)
+  route('/api/mobile/v1/relay/diagnostics', relayControl.handleRelayDiagnostics)
+
+  // 这台插件**自己**的版本现场与自动更新开关（见 mobile/plugin-self.js）。
+  // 只管 dsh-mobile-plugin 这一个包：动别的插件会把承载 App 连接的那条链一起带走，而手机
+  // 没有在电脑前的那双手。与下面那三条 `/plugin/update/*` 是同一份真源（外壳的
+  // dshMobilePluginRuntime），这里补的是设备页要的另外几格：自动更新开关与回退结果。
+  route('/api/mobile/v1/plugin/self', pluginSelf.handlePluginSelf)
+  route('/api/mobile/v1/plugin/self/auto', pluginSelf.handlePluginAuto)
+
   // 插件自更新：APP 的「应用更新」页给这台宿主升级插件版本（见 mobile/plugin-update.js）。
   // 与桌面控制面 `/api/relay/update/*` 同一套实现，差别只在入口：那三条 localOnly，手机
   // 永远打不到，而手机上聊天时「有对话在跑」那道闸几乎总关着 —— 自动更新等于不跑。
@@ -342,6 +413,18 @@ function registerMobileRoutes(deps) {
   route('/api/mobile/v1/plugin/update/check', pluginUpdate.handlePluginUpdateCheck)
   route('/api/mobile/v1/plugin/update/apply', pluginUpdate.handlePluginUpdateApply)
 
+  // 扩展与当前这台宿主之间的三条（见 mobile/extensions.js）。
+  //
+  // 扩展的**产物与清单**不走这里 —— 那由 App 分发系统的公开接口提供，装与不装之前就要能读。
+  // 这三条只处理「宿主认账」：哪些卡被回写过、扩展自己改自己那张卡、以及让宿主替它办一件事。
+  //
+  // 能力面同样是有意收窄的：宿主动作由那份硬编码登记表预先枚举，**现在一张都没登记**，
+  // 所以第三条对任何动作名都回 403。将来放开时在登记表里逐条加，不在这里开透传口子 ——
+  // 移动 API 不暴露 shell / 系统设置 / 任意文件读写，这条也一样。
+  route('/api/mobile/v1/extension/cards', extensions.handleExtensionCards)
+  route('/api/mobile/v1/extension/card-state', extensions.handleExtensionCardState)
+  route('/api/mobile/v1/extension/action', extensions.handleExtensionAction)
+
   // 分享文件的落地通道（App 把手机分享进来的文件分片传上来，见 mobile/uploads.js）。
   // 手机端没有「把文件交给宿主」的路：图片能进 session.send 的 base64 内容块，其它格式
   // 一律进不去。四条端点只做「收字节 → 落盘到 ~/.dsh/mobile-inbox/<日期>/<文件名>」，

package/lib/shared/e2ee-pair.js

@@ -0,0 +1,91 @@
+'use strict';
+
+/**
+ * 配对请求与回包的加解密（协议 v2 配对）。**宿主侧**。
+ *
+ * 密钥只有一个来源：二维码里那张一次性票据。
+ *
+ *   pairKey = HKDF-SHA256(ikm = ticket, salt = instanceId, info = 'dsh-pair-v2', len = 32)
+ *
+ * 票据由宿主生成、写进二维码、绝不经过中转 —— 所以配对阶段不需要任何公钥操作
+ * （HPKE / X25519 在 §8.2 被实测否掉了）。
+ *
+ * 为什么回包也必须加密：里面有 `token`、`cookie`、`deviceCredential`，全是能直接冒用的
+ * 凭据。明文回包等于前面白做 —— 链路上的任何人只要老实转发，就顺手拿到这台设备未来
+ * 一年的通行证。
+ *
+ * 两条入口（宿主的主路由与局域网代理）共用这一份：它们在两个进程里，但字节口径必须一样。
+ */
+
+const e2ee = require('../shared/e2ee');
+
+/** 设备主密钥与标识的形状。两者都要进凭据库：验签要用 deviceKey 重算。 */
+const DEVICE_KEY_RE = /^[A-Za-z0-9_-]{43}$/;
+const KEY_ID_RE = /^[0-9a-f]{16}$/;
+
+/**
+ * 解一份加密的配对请求。
+ *
+ * @param {object} input
+ * @param {string} input.ticket 宿主当前的配对票据（base64url 43 字符）
+ * @param {string} input.instanceId 宿主实例号
+ * @param {string} input.sealed 请求体里的 `sealed`（base64）
+ * @param {string} [input.claimedInstanceId] 请求体里自报的实例号
+ * @returns {{ ok: true, pairKey: Buffer, device: object, deviceKey: string, keyId: string }
+ *          | { ok: false }}
+ */
+function openSealedPairRequest(input) {
+  const ticket = typeof input.ticket === 'string' ? input.ticket : '';
+  const instanceId = String(input.instanceId || '');
+  // 没有票据（旧状态文件、或者刚被换过）就无从解起。
+  if (!ticket || !instanceId) return { ok: false };
+  // 请求体里的实例号必须与本机一致：一张二维码只能配它自己那台机器。
+  const claimed = typeof input.claimedInstanceId === 'string' ? input.claimedInstanceId.trim() : '';
+  if (claimed && claimed !== instanceId) return { ok: false };
+
+  let pairKey;
+  let plain;
+  try {
+    pairKey = e2ee.derivePairKey(Buffer.from(ticket, 'base64url'), instanceId);
+    plain = e2ee.open(pairKey, Buffer.from(input.sealed, 'base64'), e2ee.pairAad(instanceId));
+  } catch {
+    return { ok: false };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(Buffer.from(plain).toString('utf8'));
+  } catch {
+    return { ok: false };
+  }
+  if (!parsed || typeof parsed !== 'object') return { ok: false };
+
+  const deviceKey = typeof parsed.deviceKey === 'string' ? parsed.deviceKey : '';
+  const keyId = typeof parsed.keyId === 'string' ? parsed.keyId : '';
+  // 形状不对就是实现错了（这两个值要进凭据库并被拿去验签），当场拒掉，
+  // 别把一条坏记录写进去。
+  if (!DEVICE_KEY_RE.test(deviceKey)) return { ok: false };
+  if (!KEY_ID_RE.test(keyId)) return { ok: false };
+
+  return {
+    ok: true,
+    pairKey,
+    device: parsed.device && typeof parsed.device === 'object' ? parsed.device : {},
+    deviceKey,
+    keyId,
+  };
+}
+
+/**
+ * 把配对回包封成 `{ ok, proto, sealed }`。
+ *
+ * @param {Buffer} pairKey
+ * @param {string} instanceId
+ * @param {object} payload 明文回包（token / cookie / deviceCredential / serverTime …）
+ * @returns {{ ok: true, proto: 2, sealed: string }}
+ */
+function sealPairResponse(pairKey, instanceId, payload) {
+  const sealed = e2ee.seal(pairKey, Buffer.from(JSON.stringify(payload), 'utf8'), e2ee.pairAad(instanceId));
+  return { ok: true, proto: 2, sealed: Buffer.from(sealed).toString('base64') };
+}
+
+module.exports = { openSealedPairRequest, sealPairResponse, DEVICE_KEY_RE, KEY_ID_RE };