dsh-mobile-plugin 0.1.99 → 0.2.0

package/lib/client.js

@@ -85,7 +85,13 @@ window.__ModuleLoader__.load({
     const PUSH_INTERVAL_MS = 2000;
     /** 与宿主 lib/desktop-view.cjs 的上限保持一致，避免无谓的超大请求。 */
     const MAX_KEYS = 512;
-    const DESKTOP_VIEW_ENDPOINT = '/api/relay/desktop-view';
+    /**
+     * 浏览器侧的应用路由一律写成**文档相对**形式（没有前导斜杠），与 DSH 自己的客户端
+     * 一致：宿主给 index 注入了 `<base href="./">`，页面挂在哪个前缀下，请求就跟着哪个
+     * 前缀走。写成 `/api/...` 这种站点根绝对地址，DSH 被反向代理挂到子路径（例如
+     * `/dsh/`）时会直接打到站点根、拿回 404 —— 设置页看到的正是「读取宿主状态失败: HTTP 404」。
+     */
+    const DESKTOP_VIEW_ENDPOINT = 'api/relay/desktop-view';
 
     /** 读桌面端最新的视图状态；读不到返回 null（首次使用、隐私模式、键名变更等）。 */
     function readDesktopView() {
@@ -167,8 +173,12 @@ window.__ModuleLoader__.load({
     /* ── 二：控制面调用 ─────────────────────────────────────────────────────
      * 全部走同源 fetch，天然满足宿主的 `localOnly` 守卫（拒绝 cross-site、要求
      * Origin 与 Host 同源）——设置页与宿主同源，正是它被设计成的样子。
+     *
+     * 地址一律是**文档相对**的：宿主给 index 注入了 `<base href="./">`，把它挂在
+     * 子路径下（反向代理 `/dsh/` 之类）时请求才会跟着前缀走。DSH 自己的客户端也是
+     * 这么写的（`PATH.slice(1)`）。站点根绝对地址在那种部署下会打到根路径并 404。
      */
-    const RELAY = '/api/relay';
+    const RELAY = 'api/relay';
 
     /** 错误正文有三种形状：字符串、{code,message}、{ok:false,error}。这里拍平成一句话。 */
     function errorText(body, status) {
@@ -185,22 +195,27 @@ window.__ModuleLoader__.load({
     }
 
     /**
-     * 控制面调用。`path` 既可以是 `/xxx` 这样的**相对控制面的短路径**（推荐，与
+     * 控制面调用。`path` 既可以是 `/xxx` / `xxx` 这样的**短路径**（推荐，与
      * `postJson('/desktop-read')` 的写法一致），也可以直接甩一个完整的
-     * `/api/relay/xxx`——两种都接受。
+     * `/api/relay/xxx` 或 `api/relay/xxx`——几种都接受，最终一律折成文档相对地址。
      *
-     * **为什么必须两种都接受（2026-10-10 真机故障）**：这里以前是无条件
+     * **为什么必须几种都接受（2026-10-10 真机故障）**：这里以前是无条件
      * `${RELAY}${path}`，而绿点那两条同步传进来的偏偏是**已经带 `/api/relay` 的全路径**
      * （`READ_RECEIPT_ENDPOINT` / `DESKTOP_READ_ENDPOINT`），于是真正发出去的是
      * `/api/relay/api/relay/read-receipt` —— 一个不存在的地址。它返回 401/404，被
      * 两条同步各自的 `catch` 静静吞掉，所以「手机上读过桌面不灭灯」「桌面上读过手机
      * 不灭灯」从来就没通过，而且**一条日志都不留**（宿主侧活体台账里那两个计数恒为 0）。
-     * 同一文件里的展开态同步之所以一直正常，只是因为它用的是裸 `fetch` + 全路径。
      * 改断言而不是改实现是不行的：守卫测试里的假 fetch 按 `endsWith(endpoint)` 匹配，
      * 而 `/api/relay/api/relay/read-receipt` 也满足这个后缀 —— 测试因此一直是绿的。
      */
+    function controlUrl(path) {
+      const raw = String(path);
+      if (raw.startsWith('/api/') || raw.startsWith('api/')) return raw.replace(/^\//, '');
+      return `${RELAY}${raw.startsWith('/') ? raw : `/${raw}`}`;
+    }
+
     async function call(path, init) {
-      const url = /^\/api\//.test(String(path)) ? String(path) : `${RELAY}${path}`;
+      const url = controlUrl(path);
       let response;
       try {
         response = await fetch(url, {
@@ -503,6 +518,7 @@ window.__ModuleLoader__.load({
         panelPending: '正在读取页面地址…',
         panelMissing: '宿主还没给出页面地址，稍后再打开这一页试试。',
         loadFailed: '读取宿主状态失败',
+        loadMissing: '插件宿主侧没有加载：把 DSH 完整退出再打开一次；还不行就在插件市场重装一遍插件。',
         webAccessOn: '公网网页管理已开放，到期时间',
         webAccessOff: '公网网页管理已关闭',
         webAccessOpen: '开放网页管理 2 小时',
@@ -520,6 +536,7 @@ window.__ModuleLoader__.load({
         panelPending: 'Reading the page address…',
         panelMissing: 'The host has not reported a page address yet — reopen this item in a moment.',
         loadFailed: 'Failed to read host status',
+        loadMissing: 'The plugin host half is not loaded: quit and reopen DSH; if that does not help, reinstall the plugin from the market.',
         webAccessOn: 'Public web management is open until',
         webAccessOff: 'Public web management is closed',
         webAccessOpen: 'Open web management for 2 hours',
@@ -544,6 +561,8 @@ window.__ModuleLoader__.load({
       const [webAccess, setWebAccess] = useState(null);
       const [webAccessError, setWebAccessError] = useState(null);
       const [webAccessBusy, setWebAccessBusy] = useState(false);
+      /** 最近一次失败的 HTTP 状态码（0 = 网络异常 / 还没失败过）。404 单独说。 */
+      const [errorStatus, setErrorStatus] = useState(0);
 
       useEffect(() => {
         let alive = true;
@@ -557,6 +576,7 @@ window.__ModuleLoader__.load({
             const next = await call('/status');
             if (!alive) return;
             setError(null);
+            setErrorStatus(0);
             setPanelUrl(typeof next.panelUrl === 'string' ? next.panelUrl : '');
             setWebAccess(next.webAccess && typeof next.webAccess.enabled === 'boolean' ? next.webAccess : null);
             if (retryTimer !== null) {
@@ -572,6 +592,7 @@ window.__ModuleLoader__.load({
           } catch (problem) {
             if (!alive) return;
             setError(String((problem && problem.message) || problem));
+            setErrorStatus(Number(problem && problem.status) || 0);
             setWebAccess(null);
             if (refreshTimer !== null) {
               clearTimer(refreshTimer);
@@ -618,7 +639,9 @@ window.__ModuleLoader__.load({
 
       return h('div', { className: 'dshm_root' }, [
         h('h2', { className: 'dshm_heading' }, t('heading')),
-        error ? h('p', { className: 'dshm_error' }, `${t('loadFailed')}: ${error}`) : null,
+        error
+          ? h('p', { className: 'dshm_error' }, errorStatus === 404 ? t('loadMissing') : `${t('loadFailed')}: ${error}`)
+          : null,
 
         // 用 `<a target="_blank">` 而不是 iframe：DSH 桌面端会把这个链接交给系统浏览器
         // 打开（网页版有自己的地址与刷新节奏，嵌在设置弹窗里反而不好用）。

package/lib/http/routing.js

@@ -14,12 +14,45 @@
  */
 
 const net = require('node:net');
+const { isProto2, openRequest, sealResponse, readRawBody } = require('../shared/e2ee-request');
 const { sendJson, readJsonBody } = require('../shared/http-util');
 
+/**
+ * 「这个请求是谁转发的」。
+ *
+ * 中转与局域网代理都跑在这台机器上，它们转给本地上游的请求 socket 对端就是回环地址，
+ * `host` 还会被补成 `127.0.0.1:<上游端口>` —— 于是**任何看来源地址或 Host 的判据都对它们
+ * 失效**，经中转打进来的控制面请求长得和本机 DSH 设置页一模一样（实测：不带实例头、不带
+ * cookie 的 `POST /api/relay/config` 照样执行，能改中转地址、改注册密钥、`revoke-all`）。
+ *
+ * 所以判据换成「谁转发的」这个事实：两个代理在转发前**先删掉客户端自带的同名头、再写入
+ * 自己的值**（`relay` / `lan`），控制面见到它就按远程处理。客户端自己塞一个也没用 ——
+ * 代理会先把它删掉。
+ */
+const VIA_HEADER = 'x-dsh-via';
+
+/** 请求是否由本机的中转或局域网代理转发而来（值即转发方）。 */
+const proxiedRequest = (req) => {
+  const headers = req?.headers;
+  if (!headers || typeof headers !== 'object') return false;
+  // 按小写比对而不是直接取键：Node 会把入站头名压成小写，但假 req、反代注入、
+  // 以及 `WebSocket` 升级那条路的 headers 对象不保证如此，靠大小写绕过太便宜。
+  for (const [name, raw] of Object.entries(headers)) {
+    if (name.toLowerCase() !== VIA_HEADER) continue;
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof value === 'string' && value.trim() !== '') return true;
+  }
+  return false;
+};
+
 // Relay pairing cookies and instance headers are routing credentials only;
 // never allow them to reach the local control plane.
+//
+// `x-dsh-via` 也在这里：它是「转发来的」这个事实本身。手机走 `/api/mobile/v1/**` 时通常
+// 既不待实例头也不带 cookie，只靠这两条挡不住转发来的控制面请求。
 const remoteRelayRequest = (req) => Boolean(
-  (typeof req.headers['x-dsh-instance'] === 'string' && req.headers['x-dsh-instance'])
+  proxiedRequest(req)
+    || (typeof req.headers['x-dsh-instance'] === 'string' && req.headers['x-dsh-instance'])
     || /(?:^|;\s*)dsh_(?:pair|lan)=/.test(String(req.headers.cookie || '')),
 )
 
@@ -57,6 +90,8 @@ const isLoopbackAddress = (address) => {
 const trustedLocalUi = (req) => {
   const socket = req?.socket || req?.connection
   if (!isLoopbackAddress(socket?.remoteAddress)) return false
+  // 转发来的一律不算本机界面：隧道与局域网代理都是从回环连出去的，光看 socket 分不出来。
+  if (proxiedRequest(req)) return false
   const headers = req?.headers && typeof req.headers === 'object' ? req.headers : {}
   for (const [name, value] of Object.entries(headers)) {
     if (/^(?:forwarded$|x-forwarded-|x-real-ip$|via$|true-client-ip$|cf-connecting-ip$)/i.test(name)
@@ -101,19 +136,140 @@ const readJson = (req) => readJsonBody(req, 256 * 1024).then(body => body || {})
  *   否则随便谁打一下也能把面板骗成「连上了」。
  * @returns {(handler: (ctx: object, req: object, res: object) => Promise<unknown>) => (req: object, res: object) => Promise<unknown>}
  */
-const createGuarded = (ctx, authorized, note = null) => (handler) => async (req, res) => {
-  if (!authorized(req)) return sendJson(res, 401, { ok: false, error: { code: 'unauthorized', message: '缺少或无效的移动 token' } })
-  if (note) {
-    // 记账本身绝不能影响请求结果：它坏了也只是面板少一个确认。
-    try { note() } catch { /* 忽略 */ }
-  }
-  try { await handler(ctx, req, res) } catch (error) {
-    sendJson(res, 500, { ok: false, error: { code: 'internal', message: String(error?.message || error) } })
+/**
+ * 移动端路由守卫：token + 协议 v2 信封 + 把 handler 抛出的异常统一收成 500 信封。
+ *
+ * 与 localOnly 的不对称是刻意的：移动端请求本来就要从公网进来，跨站不是它的风险；
+ * 它的风险是「没带 token 也能读别人的会话」，所以只校验 token。
+ *
+ * **信封的顺序在这里定死**（§8.3(11)）：鉴权（token）→ 验签 → 重放 → 解封请求体 →
+ * 业务 handler → 封响应。鉴权放在最前，是因为「这台设备是谁」决定了拿哪把密钥验签；
+ * 而鉴权自身失败时回的是明文 401（`e2ee-unknown-device` 之外的一切凭据问题），
+ * 因为 App 必须先在解不开信封的情况下读懂它。
+ *
+ * @param {object} ctx 插件 ctx，透传给 handler
+ * @param {(req: object) => boolean} authorized 移动 token 校验，由调用方注入
+ * @param {() => void} [note] 通过 token 校验之后叫一声：宿主用它记「手机来过」的时刻，
+ *   引导最后一页据此说「手机已经连上了」。**只在校验通过之后叫**，401 那条不算——
+ *   否则随便谁打一下也能把面板骗成「连上了」。
+ * @param {(req: object) => void} [onAuthorized] 带请求对象的记账（要读凭据记录时用）。
+ * @param {object} [envelope] 协议 v2 的信封钩子：`{ keyFor, readBody }`。不给就是纯明文。
+ * @returns {(handler: (ctx: object, req: object, res: object) => Promise<unknown>) => (req: object, res: object) => Promise<unknown>}
+ */
+const createGuarded = (ctx, authorized, note = null, extra = {}) => {
+  const onAuthorized = typeof extra.onAuthorized === 'function' ? extra.onAuthorized : null
+  const envelope = extra.envelope && typeof extra.envelope === 'object' ? extra.envelope : null
+  return (handler) => async (req, res) => {
+    // 鉴权失败要**说清是哪一种**（§3.8）：被吊销 / 已过期 / 只是没有 token。
+    //
+    // 前两种必须让手机知道「我被踢了」并停止轮询 —— 只回一句「缺少或无效的移动 token」，
+    // 用户看到的是「请求失败」，而它其实已经不能再做任何事了。这三条响应都是明文：
+    // 客户端要在解不开信封的情况下读懂它们。
+    // `authorized` 的两种返回值都认：布尔（老调用方/测试）与带 reason 的对象（宿主用，
+    // 这样才能区分「被踢了」与「没带 token」）。
+    const outcome = authorized(req)
+    const passed = outcome === true || (outcome && typeof outcome === 'object' && outcome.ok === true)
+    if (!passed) {
+      const reason = outcome && typeof outcome === 'object' ? outcome.reason : 'unauthorized'
+      if (reason === 'revoked') return sendJson(res, 401, { ok: false, error: { code: 'device-revoked', message: '这台设备已被解除绑定，请重新扫码' } })
+      if (reason === 'expired') return sendJson(res, 401, { ok: false, error: { code: 'device-expired', message: '这台设备的授权已过期，请重新扫码' } })
+      return sendJson(res, 401, { ok: false, error: { code: 'unauthorized', message: '缺少或无效的移动 token' } })
+    }
+    // 鉴权结果里的凭据记录挂到请求上：流那条路要按设备登记（吊销时主动断流，§3.3），
+    // 而设备 id 只在这条记录里。挂在 req 上而不是再查一次库，是因为这一条请求上已经查过了。
+    if (outcome && typeof outcome === 'object' && outcome.record) req.__dshRecord = outcome.record
+    if (note) {
+      // 记账本身绝不能影响请求结果：它坏了也只是面板少一个确认。
+      try { note() } catch { /* 忽略 */ }
+    }
+    if (onAuthorized) {
+      try { onAuthorized(req) } catch { /* 同上 */ }
+    }
+
+    // **被动降级要被发现，不能悄悄变明文**（§8.3(7) 的 `e2ee-required`）。
+    //
+    // 判据：这枚凭据的记录里有 `deviceKey`（说明它当初是按协议 v2 配的），而这条请求没带
+    // `X-Dsh-Proto` —— 中转把那个头删掉时就是这个形状。不判的话宿主会按老协议解析一个
+    // 信封 JSON，得到一个「请求体不是合法 JSON」的 400，看起来像 App 的 bug。
+    // 老 App 的凭据里没有 `deviceKey`，不受这一条影响。
+    const authRecord = req.__dshRecord
+    if (envelope && authRecord && authRecord.deviceKey && !isProto2(req)) {
+      return sendJson(res, 400, { ok: false, error: { code: 'e2ee-required', message: '这条会话是加密的，请用信封重发' } })
+    }
+    // 协议 v2：只有带 `X-Dsh-Proto: 2` 的请求才走信封。老客户端没有这个头，一字不改地照旧。
+    let sealed = null
+    if (envelope && isProto2(req)) {
+      let rawBody
+      try {
+        rawBody = await envelope.readBody(req)
+      } catch {
+        return sendJson(res, 413, { ok: false, error: { code: 'e2ee-bad-envelope', message: '请求体过大' } })
+      }
+      const opened = openRequest(req, { keyFor: envelope.keyFor }, rawBody)
+      if (!opened.ok) {
+        // 错误响应永远明文（§8.3(11)）：App 要先读懂它才谈得上重发或校准时钟。
+        if (opened.extra) sendJson(res, opened.status, { ok: false, error: { code: opened.code, ...opened.extra } })
+        else sendJson(res, opened.status, { ok: false, error: { code: opened.code } })
+        return
+      }
+      sealed = opened
+      // 业务 handler 拿到的是明文 JSON：域代码一行业务逻辑都不用知道信封存在。
+      if (opened.body !== undefined) req.body = opened.body
+      // SSE 那条路要逐帧封装（帧没有请求头可用），所以把密钥与这次请求的 AAD 材料
+      // 挂在 req 上，由开流那一处取。**只在内存里、只活这一条请求**。
+      req.__dshE2ee = { keys: opened.keys, req: opened.req }
+    }
+
+    try {
+      if (!sealed) {
+        await handler(ctx, req, res)
+        return
+      }
+      // 封响应：业务代码照常 `sendJson(res, status, payload)`，这里把**写出去的那一份**包成
+      // 信封。劫的是 `res.end` 而不是 `res.json` —— 宿主侧写响应一律走 `sendJson`，
+      // 而它内部是 `writeHead` + `end`，没有 `res.json` 这一层。
+      const originalEnd = res.end.bind(res)
+      const originalWriteHead = res.writeHead.bind(res)
+      let chosenStatus = 200
+      res.writeHead = (status, ...rest) => {
+        chosenStatus = Number(status) || 200
+        return originalWriteHead(status, ...rest)
+      }
+      res.end = (chunk, ...rest) => {
+        res.end = originalEnd
+        res.writeHead = originalWriteHead
+        let payload = chunk
+        if (typeof chunk === 'string' || Buffer.isBuffer(chunk)) {
+          const text = Buffer.isBuffer(chunk) ? chunk.toString('utf8') : chunk
+          let parsed
+          try {
+            parsed = JSON.parse(text)
+          } catch {
+            parsed = null
+          }
+          if (parsed !== null) {
+            const sealedPayload = sealResponse(req, { statusCode: chosenStatus }, sealed.keys, sealed.req, parsed)
+            // **封完直接发，不再 gzip**：`content-encoding` 只能在头出去之前声明，而这个
+            // 钩子跑在 `sendJson` 的 `writeHead` 之后，`setHeader` 会被静默忽略 —— 结果
+            // 是「线上是 gzip、头却说 identity」，客户端解不开，报「请求失败 (HTTP 200)」
+            // （2026-10-24 现场）。信封是 base64 密文，外层压缩本来也只省几个百分点；
+            // 要省带宽靠载荷裁剪，不靠这一层。
+            payload = JSON.stringify(sealedPayload)
+          }
+        }
+        return originalEnd(payload, ...rest)
+      }
+      await handler(ctx, req, res)
+    } catch (error) {
+      sendJson(res, 500, { ok: false, error: { code: 'internal', message: String(error?.message || error) } })
+    }
   }
 }
 
 module.exports = {
   remoteRelayRequest,
+  proxiedRequest,
+  VIA_HEADER,
   crossSiteRequest,
   isLoopbackAddress,
   trustedLocalUi,

package/lib/impl.js

@@ -20,7 +20,10 @@ const { localOnly, trustedLocalUi, readJson, createGuarded } = require('./http/r
 const { registerMobileRoutes } = require('./routes/mobile-api.js')
 const { registerControlPlaneRoutes } = require('./routes/control-plane.js')
 const { hostMetadata, createStatusView } = require('./relay/status.js')
-const { authorized } = require('./mobile/auth.js')
+const { authorized, authOutcome, presentedCredential } = require('./mobile/auth.js')
+const { readRawBody } = require('./shared/e2ee-request')
+const streamRegistry = require('./mobile/stream-registry.js')
+const { viaChannel } = require('./shared/via-header')
 const { createSidecarLifecycle } = require('./sidecar-lifecycle.cjs')
 const { createMirrorPusher } = require('./mirror/pusher.cjs')
 const { randomBytes } = require('node:crypto')
@@ -38,6 +41,8 @@ const { installQuestionBridge } = require('./mobile/questions.js')
 const activity = require('./mobile/activity.cjs')
 const { installAutoArchive } = require('./auto-archive.cjs')
 const { installSessionCleanup } = require('./session-cleanup.cjs')
+// 扩展卡的宿主侧：`extension_present` 工具与卡状态账本（见 mobile/extensions.js）。
+const { installExtensions } = require('./mobile/extensions.js')
 const { activeGuard } = require('./host-guard.cjs')
 // 桌面端侧栏展开态的快照存储。桌面把这份状态只记在浏览器 localStorage 里，宿主必须
 // 有一个落盘处：客户端半边（lib/client.js）上报 → 这里 → 移动端读取。
@@ -136,7 +141,12 @@ function createConfigStore(state) {
   }
   return {
     get: () => configOf(state),
-    async update(patch) {
+    /**
+     * 写配置。`notify: false` 只落盘、不通知订阅者 —— 手机端改中转地址时要用它：
+     * 订阅者一跑就会重配隧道，而那一发响应还没吐完（详见 mobile/relay-control.js）。
+     */
+    notify() { notify() },
+    async update(patch, options = {}) {
       const next = configOf(state)
       for (const [key, value] of Object.entries(patch || {})) {
         if (value === undefined || !(key in next)) continue
@@ -150,7 +160,7 @@ function createConfigStore(state) {
       }
       Object.assign(state, parsed)
       core.saveState(state)
-      notify()
+      if (options.notify !== false) notify()
       return configOf(state)
     },
     watch(listener) {
@@ -172,6 +182,15 @@ function pairingPayload(state, lanPort) {
     name: state.name || os.hostname(),
     instanceId: state.instanceId,
     code: state.pairingCode,
+    // 协议版本与一次性票据（§8.3(1)）。
+    //
+    // `proto: 2` 由**宿主**写、也由宿主生成，中转没有任何机会改写它 —— 所以「新 App 被
+    // 中转骗回明文」这个问题从一开始就不存在。`ticket` 是 32 字节随机数，手机拿它派生
+    // 配对密钥；二维码是屏幕对摄像头，这条通道完全绕开中转。
+    //
+    // 老 App 只取自己认识的那几个字段，多出来的两个会被忽略 —— 一张二维码同时服务新旧两种。
+    proto: 2,
+    ticket: state.pairingTicket || '',
     relayUrl,
     lanUrls: urls,
     // 候选列表随二维码一起带走：App 配对后即使换了网段，也能按这份列表
@@ -290,7 +309,12 @@ function apply(ctx) {
     // 显式传入能让「re-fork 前清的是不是正在跑的那份缓存」不依赖巧合。
     pluginLibDir: path.dirname(fileURLToPath(import.meta.url)),
     // 下发给 worker 的配置：这里的字段集就是 sidecar 的启动契约，改名要同步 worker。
-    buildConfig: (lanPort) => ({ enabled: state.enabled, relayUrl: state.relayUrl, instanceId: state.instanceId, pairingCode: state.pairingCode, name: state.name, upstreamPort: ctx.webServer.port, lanPort, lanEnabled: state.lanEnabled, lanSecret: state.lanSecret, registerSecret: state.registerSecret }),
+    //
+    // `pairingTicket` 与 `pairingCode` 都必须在这里：局域网代理的配对要拿票据派生配对
+    // 密钥（协议 v2 的请求在旁路里解封）。漏了票据时旁路读到的是空串，任何一次扫码配对
+    // 都回「配对码错误或桌面端已拒绝」，而主进程那条 `/pair` 一切正常 —— 症状是「同一个
+    // 二维码，走中转能配、走局域网不能」。
+    buildConfig: (lanPort) => ({ enabled: state.enabled, relayUrl: state.relayUrl, instanceId: state.instanceId, pairingCode: state.pairingCode, pairingTicket: state.pairingTicket || '', name: state.name, upstreamPort: ctx.webServer.port, lanPort, lanEnabled: state.lanEnabled, lanSecret: state.lanSecret, registerSecret: state.registerSecret }),
   })
   const { sidecarToken, syncSidecar, restartSidecar, tunnelConnected } = sidecarLifecycle
 
@@ -314,6 +338,13 @@ function apply(ctx) {
     }
     return undefined
   }, `${name}: session cleanup tool`)
+  ctx.effect(() => {
+    // 卡状态账本与三条路由不靠这个工具，所以缺 tools 注入时只少一个工具，别把整块装配丢掉。
+    try { installExtensions(ctx) } catch (error) {
+      if (!String(error).includes('without inject')) throw error
+    }
+    return undefined
+  }, `${name}: extension tool`)
 
   const status = createStatusView({
     state,
@@ -370,10 +401,33 @@ function apply(ctx) {
     getMirrorPush: mirror.getMirrorPush,
     getMirrorPushFailures: mirror.getPushFailures,
     getLanProxyStats: () => sidecarLifecycle.getSnapshot()?.streams?.lan ?? null,
+    // 吊销时收掉这台设备已经开着的流（§3.3）：token 换了只保证「下一次请求」被拒，
+    // 一条已经开着的 SSE 不会自己停，被踢的手机还能继续收消息直到它自己重连。
+    dropDeviceStreams: (deviceId) => streamRegistry.drop(deviceId),
   })
 
 
-  const guarded = createGuarded(ctx, authorized, activity.note)
+  /**
+   * 协议 v2 信封的宿主侧钩子（§8.3(4)）。
+   *
+   * `keyFor` 按 **keyId** 查密钥，不按 deviceId：后者是手机自填的，克隆/迁移后会撞，
+   * 撞了就变成「两台手机能用同一把密钥验签」。凭据库是唯一的密钥来源，而它只在宿主
+   * 主进程里可写。
+   */
+  const envelope = {
+    keyFor: (keyId) => credentials.findByKeyId(state.instanceId, keyId),
+    readBody: (req) => readRawBody(req),
+  }
+  const guarded = createGuarded(ctx, authOutcome, activity.note, {
+    // 鉴权通过后立刻记「最近连接 + 走的是哪条路」：两条代理都注入了 `x-dsh-via`。
+    onAuthorized: (req) => {
+      const presented = presentedCredential(req)
+      if (!presented) return
+      const record = credentials.lookup(presented, state.instanceId)
+      if (record) credentials.touch(record, { channel: viaChannel(req) })
+    },
+    envelope,
+  })
 
   // 内置浏览器预览的宿主端：手机按端口在它自己的环回上监听，把内置浏览器写下的原始
   // 字节通过 WebSocket 送到这里，这里与 `127.0.0.1:<port>` 对搬。
@@ -423,6 +477,26 @@ function apply(ctx) {
     // 收不收新设备（'deny' 时一律拒）。两者本文件都已有，透传给移动端路由。
     core,
     pairingApproval,
+    // 配对成功之后换码 + 换票据（§5.1）：状态变更在 core 里，这里只补「让旁路重读」。
+    rotatePairing: () => { core.rotatePairing(state); applyServices() },
+    // 「这台设备的中转与连接配置」那十条（见 lib/mobile/relay-control.js）。
+    // 它们与控制面 `/api/relay/*` 写的是**同一份** relay.json（同一个 `settings` store），
+    // 只是入口不同：控制面只认本机，移动端认已配对 token。这里的每一项都是本文件已有的
+    // 取值器/实例，没有一行实现搬进装配层。
+    relayControl: {
+      state,
+      settings,
+      syncSidecar,
+      status,
+      resolveLanPort,
+      lanPortInUse: advertisedLanPort,
+      getLanPortAdjusted: () => lanPortAdjusted,
+      restartSidecar,
+      // **取值器**：sidecar 会被自重启整体替换，存实例就是存一份指向已 stop 的 facade。
+      getSidecar: sidecarLifecycle.getSidecar,
+      credentials,
+      activeGuard,
+    },
   })
   ctx.effect(() => {
     const stopWatching = settings.watch(next => {

package/lib/index.js

@@ -154,7 +154,7 @@ export function apply(ctx) {
   })
 
   runtime
-    .start(ctx)
+    .start(ctx, { log })
     .then(() => {
       log('info', 'dsh-mobile-plugin: 已装载 %s（来源 %s）', runtime.status().version, runtime.status().source)
       // 每 10 分钟让已落盘的正式版接管 OTA，并补上「盘上比运行中新」的那一次换代；

package/lib/mirror/pusher.cjs

@@ -35,6 +35,7 @@ const { listSignal: sharedListSignal } = require('../shared/list-signal.js');
 const { sessionSignal: sharedSessionSignal } = require('../shared/session-signal.js');
 const { dropSessionListCache } = require('../mobile/session-cache.js');
 const { observeCompletionEvent } = require('../mobile/completion.js');
+const { lastTurnOf } = require('../mobile/session-last-turn.js');
 
 /** 后台循环每个 tick 补推一个冷会话，保证没人动的会话镜像也不长期不更新。 */
 const HIGH_PRIORITY_WINDOW_MS = 5 * 60 * 1000;
@@ -83,6 +84,11 @@ const MAX_CONSECUTIVE_EVENT_BUILDS = 3;
 
 function createMirrorPusher(deps) {
   const { ctx, tunnelConnected, getSidecar, listSignal = sharedListSignal, sessionSignal = sharedSessionSignal } = deps;
+  // iOS 推送出口（`mobile/push-notify.js` 的 `notifyTurnEnded`）。不传就完全不推——
+  // 装配层漏接线时不该在这里崩。标题从镜像清单现查（noteMirrorList 维护缓存）。
+  const notifyTurnEnded = typeof deps.notifyTurnEnded === 'function' ? deps.notifyTurnEnded : null;
+  const titleCache = new Map();
+  const sessionTitleOf = (sessionId) => titleCache.get(sessionId) || '';
   /**
    * 「手机最近来过没有」的取值器（`mobile/activity.cjs` 的 `snapshot` 形态）。
    *
@@ -179,6 +185,17 @@ function createMirrorPusher(deps) {
   // 也是同一个值，语义上就是「这份列表换了」。
   let lastSignalRevision = '';
   const sessionsRevisionOf = (body) => (body && typeof body.revision === 'string' ? body.revision : '');
+  /**
+   * 工作区清单的内容指纹也进信号总线。
+   *
+   * 不这么做，「`/workspaces` 的构建前短路」就没有可信的变更判据 —— 手机只能每 15 秒
+   * 让宿主把整份工作区（含归档会话 id 列表，几十 KB）重建一遍。这里只报指纹（幂等），
+   * 推送照旧按原来的指纹判重。
+   */
+  const observeWorkspaces = (body) => {
+    if (body && typeof body.revision === 'string' && body.revision) listSignal.bumpWorkspaces(body.revision);
+    return body;
+  };
   const announceSessionsRevision = (revision) => {
     if (!revision || revision === lastSignalRevision) return false;
     // 只在真正广播时才前移基准：构建失败、守卫拦下、推送失败这些路径都不该消耗掉
@@ -331,6 +348,13 @@ function createMirrorPusher(deps) {
     mirrorListActiveSessions = items.filter(isHighPriority).length;
     mirrorListSubagents = items.filter((s) => s && s.origin === 'subagent').length;
     mirrorListAt = Date.now();
+    // 标题缓存：推送帧的标题从这里现查（列表本来就带 title，白拿）。
+    titleCache.clear();
+    for (const item of items) {
+      if (item && typeof item.sessionId === 'string' && typeof item.title === 'string' && item.title.trim()) {
+        titleCache.set(item.sessionId, item.title.trim());
+      }
+    }
   };
 
   // Every session snapshot fans out to three Host RPCs. Bound the number of sessions
@@ -508,7 +532,7 @@ function createMirrorPusher(deps) {
       );
       const [sessionsBody, workspacesBody, data] = await Promise.all([
         sessionsPromise,
-        workspaces.buildWorkspacesBody(ctx),
+        workspaces.buildWorkspacesBody(ctx).then(observeWorkspaces),
         // event slot covers the full push; call the unlocked builder to avoid nesting the semaphore.
         buildSessionDataUnlocked(sessionId, summaryPromise, { reuseCache: false }),
       ]);
@@ -568,7 +592,7 @@ function createMirrorPusher(deps) {
     try {
       const [sessionsBody, workspacesBody] = await Promise.all([
         sessions.buildSessionsResponse(ctx, 'legacy'),
-        workspaces.buildWorkspacesBody(ctx),
+        workspaces.buildWorkspacesBody(ctx).then(observeWorkspaces),
       ]);
       const wsBlocked = guardWorkspaces(workspacesBody) || guardSessions(sessionsBody)
       if (!(sessionsBody?.status === 200) || wsBlocked) {
@@ -663,7 +687,7 @@ function createMirrorPusher(deps) {
         // 空清单（dsh-mobile-server/lib/mirror-state.js 的 installMirror，谓词与
         // dsh-mobile-server/server.js:110 一致）。这里推的就是 buildSessionsResponse 的
         // 原样 body，天然带这个字段。
-        const workspacesBodyEmpty = await workspaces.buildWorkspacesBody(ctx);
+        const workspacesBodyEmpty = await workspaces.buildWorkspacesBody(ctx).then(observeWorkspaces);
         const wsBlockedEmpty = guardWorkspaces(workspacesBodyEmpty);
         if (wsBlockedEmpty) {
           // 工作区那份快照不可用：别拿一份「没取到」的工作区去覆盖镜像，只广播清单。
@@ -684,7 +708,7 @@ function createMirrorPusher(deps) {
       // 门（见 BG_COLD_ROTATE_MIN_INTERVAL_MS）：清单与工作区都还停在中转镜像里那一版、
       // 又不到冷会话轮转时间时，这一轮到此为止 —— 省掉统计/模型投影与一个冷会话的 200 条
       // 正文（那才是这个 tick 的大头）。工作区体提前到这里构建，正是为了拿到它的 revision。
-      const workspacesBody = await workspaces.buildWorkspacesBody(ctx);
+      const workspacesBody = await workspaces.buildWorkspacesBody(ctx).then(observeWorkspaces);
       const workspacesRevision = workspacesBody && typeof workspacesBody.revision === 'string' ? workspacesBody.revision : '';
       const now = Date.now();
       // 清掉已经不在清单里的会话（归档/删除），免得这张表无限长。
@@ -800,6 +824,13 @@ function createMirrorPusher(deps) {
           // sidecar，形成推送风暴（配合 pushSessionImmediately 的单飞才有稳定上界）。
           observeCompletionEvent(ctx, sessionId, p?.event);
           if (p?.event?.type === 'assistant/chunk') continue;
+          // iOS 推送：turn/end 是「可能刚收尾」的信号，把事实（lastTurnOf 现读）交给
+          // 通知器判断——只有 completed / failed 且这一轮之前没推过才会真发一帧。
+          // 标题从镜像快照现查：中转与苹果都只认纯文本，没查到就用会话 id 前缀。
+          if (p?.event?.type === 'turn/end' && notifyTurnEnded) {
+            const fact = lastTurnOf(ctx, sessionId);
+            if (fact) notifyTurnEnded(sessionId, fact, sessionTitleOf(sessionId));
+          }
           void pushSessionImmediately(sessionId);
         }
       } catch { /* stream ended */ }