dsh-mobile-plugin 0.1.100 → 0.2.1

package/lib/mobile/pairing.js

@@ -9,9 +9,16 @@
  * 按老地址 POST `/pair`、请求被中转原样转给宿主、宿主没有这条路由，只能回 405。
  *
  * 与局域网那条（`lib/relay/lan-proxy.js` 的 `/__lan_pair`）是**同一件事的两个入口**：
- * 都是「配对码 → 签发凭据」，差别只在网络路径。凭据本身两条路签发的是同一种 HMAC
+ * 都是「配对码 / 票据 → 签发凭据」，差别只在网络路径。凭据本身两条路签发的是同一种 HMAC
  * （都用宿主 lanSecret 签名），所以经中转配对拿到的 token 可以直接用于局域网请求。
  *
+ * 请求体**两种形状都认**：
+ *   老形状  `{ instanceId?, code, device }`   —— 旧 App，明文，一字不改地照旧处理；
+ *   新形状  `{ instanceId, sealed }`          —— 协议 v2，`sealed` 是用二维码票据派生的
+ *                                                密钥封的，解出来是设备主密钥与设备信息。
+ * 新形状里**没有配对码**：票据本身就是资格证明。回包同样是密文 —— 里面是 token / cookie /
+ * 设备凭据，明文回包等于让中转顺手拿到这台设备未来一年的通行证。
+ *
  * 故意**不**在这里做的事：
  *  - 不问宿主再确认一次。宿主的配对策略（pairingPolicy）已经决定了它接不接受新设备，
  *    `deny` 时中转根本连不上；而这条路由本身就跑在宿主进程里。
@@ -21,44 +28,34 @@
 
 const { sendJson } = require('../shared/http-util');
 const { safeEqual } = require('../shared/dshtoken');
+const { createPairThrottle, PAIR_RATE_NORMAL } = require('../shared/pair-throttle');
+const { openSealedPairRequest, sealPairResponse } = require('../shared/e2ee-pair');
 
-/** 与局域网那条同口径：连错 5 次锁 60 秒。 */
-const PAIR_MAX_FAILS = 5;
-const PAIR_LOCK_MS = 60_000;
-
-/** ip -> { fails, lockedUntil }。放在模块作用域，两种入口共用同一份额度。 */
-const pairLocks = new Map();
-
-function isPairLocked(ip) {
-  const entry = pairLocks.get(ip);
-  return !!entry && entry.lockedUntil > Date.now();
-}
-
-function recordPairFail(ip) {
-  const entry = pairLocks.get(ip) || { fails: 0, lockedUntil: 0 };
-  entry.fails += 1;
-  if (entry.fails >= PAIR_MAX_FAILS) {
-    entry.lockedUntil = Date.now() + PAIR_LOCK_MS;
-    entry.fails = 0;
-  }
-  pairLocks.set(ip, entry);
-}
+/**
+ * 一条入口一份闸门（见 `shared/pair-throttle.js` 头部的取舍说明）。
+ *
+ * 原来这里是「按来源分桶、错五次锁一分钟」，而这条链路上没有可靠的来源：经中转进来的
+ * 请求对端永远是本机回环，客户端自带的来源头又能覆盖它。于是那套机制两头都错 ——
+ * 陌生人连错五次把所有人一起锁死，换一个来源头就绕过。现在改成不看来源的全局令牌桶。
+ */
+const throttle = createPairThrottle();
 
-function clearPairFails(ip) {
-  pairLocks.delete(ip);
-}
+/** 配对请求的线上上限：明文 16KB 按信封 4/3 放大（§8.3(9)）。超了就按畸形请求处理。 */
+const PAIR_MAX_BODY = Math.ceil(16 * 1024 * 4 / 3);
 
-/** 测试用：清空限流计数。 */
+/** 测试用：把闸门重置成满桶。 */
 function resetPairLocks() {
-  pairLocks.clear();
+  throttle.reset();
 }
 
-/** 请求方 IP。中转会把真实来源放进 x-real-ip（与 nginx 同一约定）。 */
+/**
+ * 请求方地址，**只用于审计日志与设备记录**，不参与任何限流判定。
+ *
+ * 不再读 `x-real-ip`：那个值决定不了任何事，留着只会让日志和凭据记录说谎。局域网那条
+ * 用的是连接对端（手机上真实的局域网地址，还有用）；经中转那条对端就是本机，本来没有
+ * 信息量，记本机也不算错。
+ */
 function clientIp(req) {
-  const headers = (req && req.headers) || {};
-  const raw = headers['x-real-ip'];
-  const header = Array.isArray(raw) ? raw[0] : raw;
-  if (typeof header === 'string' && header.trim()) return header.trim();
   return (req && req.socket && req.socket.remoteAddress) || '';
 }
 
@@ -94,8 +91,9 @@ function readBody(req) {
     req.setEncoding('utf8');
     req.on('data', (chunk) => {
       raw += chunk;
-      if (raw.length > 16 * 1024) {
-        raw = raw.slice(0, 16 * 1024);
+      // 配对请求的明文上限仍是 16KB；线上多 4/3 是信封那层（§8.3(9)）。
+      if (raw.length > PAIR_MAX_BODY) {
+        raw = raw.slice(0, PAIR_MAX_BODY);
         req.destroy();
         finish();
       }
@@ -121,14 +119,26 @@ function readBody(req) {
  */
 function createPairHandler(deps) {
   const { state, core, credentials, pairingApproval, lanCandidates, ipv6Candidates, lanPort, log } = deps;
+  /**
+   * 配对成功之后换掉配对码与票据（§5.1）。
+   *
+   * **两件必须同一个动作**：只换码不换票据，那张截图里的票据依旧能配一次；只换票据不换码，
+   * 旧码在旧形状那条路上依旧能配。所以这里是一个回调，由装配层一次做完（写状态 + 同步
+   * 旁路），而不是在这里分两步。
+   *
+   * 传 null 表示不换（测试或旧装配方）。换不动不该让已经签发的配对失败 —— 用户手上已经
+   * 拿到凭据了，回滚反而更糟；记一行日志就够。
+   */
+  const rotatePairing = typeof deps.rotatePairing === 'function' ? deps.rotatePairing : null;
 
   // ⚠️ 签名必须是 `(req, res)` **两个**参数：宿主 webServer 就是 `handler(req, res)` 调的。
   // 写成 `(_ctx, req, res)` 会把 res 挤成 undefined，而 sendJson 的 catch 会把那个
   // TypeError 当成「连接已关闭」吞掉——既没报错也没回包，请求永久挂住（/health 踩过）。
   return async function handlePair(req, res) {
-    const ip = clientIp(req);
-
-    if (isPairLocked(ip)) {
+    // 闸门：不看来源，满了直接 429 + retry-after，不排队也不硬锁。
+    const gate = throttle.take();
+    if (!gate.allowed) {
+      res.setHeader?.('retry-after', String(gate.retryAfterSec));
       sendJson(res, 429, { ok: false, error: '尝试过于频繁，请稍后再试' });
       return;
     }
@@ -139,33 +149,80 @@ function createPairHandler(deps) {
       return;
     }
 
-    const code = typeof body.code === 'string' ? body.code.trim() : '';
-    if (!/^\d{6}$/.test(code)) {
-      sendJson(res, 400, { ok: false, error: '配对码需为 6 位数字' });
+    const ip = clientIp(req);
+    const instanceId = String(state.instanceId || '');
+
+    // ── 形状判定 ──────────────────────────────────────────────────
+    //
+    // 有 `sealed` 就是协议 v2；有 `code` 就是旧 App 的老形状，**一字不改地照旧走**；
+    // 两样都没有就是畸形请求。两条路只在「怎么拿到设备信息」上不同，签发凭据之后完全汇合。
+    const sealed = typeof body.sealed === 'string' ? body.sealed.trim() : '';
+    const isSealedShape = sealed !== '';
+
+    // ── 可猜形状的收口（§10.4(d)）─────────────────────────────────
+    //
+    // 新 App 已经没有手输这条路了：二维码里带着票据，扫到就走 `sealed`。所以「认得协议、
+    // 却还带着六位码」只可能是一张过期的旧二维码（截图、面板重开之前的那份）。这个形状
+    // 的码是逐位可试的，没有必要继续为它开门 —— 直接让它重扫当前那张。
+    //
+    // **判据是请求里带没带 `proto`，不是版本号**：老 App 没有协议概念、不带这个字段，
+    // 照旧能配；而版本号在 OTA 里并不一定变（热更换的是 JS，App 版本还是那个），拿它
+    // 当判据会把「就是不给更新的人」和「已经更新的人」一起判错。
+    if (!isSealedShape && body.proto !== undefined) {
+      sendJson(res, 400, {
+        ok: false,
+        code: 'legacy-pairing-retired',
+        error: '这张二维码已过期，请重新扫一下电脑面板上当前的二维码',
+      });
       return;
     }
 
-    const expected = String(state.pairingCode || '');
-    if (!expected || !safeEqual(code, expected)) {
-      recordPairFail(ip);
-      pairDenied(res);
-      return;
+    let supplied;
+    let issuedExtra;
+    let pairKey = null;
+    if (isSealedShape) {
+      const opened = openSealedPairRequest({
+        ticket: state.pairingTicket,
+        instanceId,
+        sealed,
+        claimedInstanceId: typeof body.instanceId === 'string' ? body.instanceId : '',
+      });
+      if (!opened.ok) {
+        // 解不开就是「配对失败」，不回细节 —— 与「配对码错」同形，不给探测空间。
+        throttle.noteFail();
+        pairDenied(res);
+        return;
+      }
+      supplied = opened.device;
+      issuedExtra = { deviceKey: opened.deviceKey, keyId: opened.keyId };
+      pairKey = opened.pairKey;
+    } else {
+      const code = typeof body.code === 'string' ? body.code.trim() : '';
+      if (!/^\d{6}$/.test(code)) {
+        sendJson(res, 400, { ok: false, error: '配对码需为 6 位数字' });
+        return;
+      }
+      const expected = String(state.pairingCode || '');
+      if (!expected || !safeEqual(code, expected)) {
+        throttle.noteFail();
+        pairDenied(res);
+        return;
+      }
+      supplied = body.device && typeof body.device === 'object' ? body.device : {};
     }
 
-    // 配对码对了，还要宿主自己的策略点头：'deny' 就是明确不收新设备。
-    const decision = pairingApproval.evaluate(state.pairingPolicy, body.device);
+    // 还要宿主自己的策略点头：'deny' 就是明确不收新设备。
+    const decision = pairingApproval.evaluate(state.pairingPolicy, supplied);
     if (!decision.approved) {
-      recordPairFail(ip);
+      // 被拒的尝试同样要记数，否则猜对码但被策略拒的一方可以无限重试。
+      throttle.noteFail();
       pairDenied(res);
       return;
     }
 
-    // **配对码正确时不清限流计数**：被拒的尝试同样要记数，否则猜对码但被策略拒的一方
-    // 可以无限重试。只有真正放行才清零。
-    clearPairFails(ip);
+    // 只有真正放行才清零并回满档。
+    throttle.noteSuccess();
 
-    const instanceId = String(state.instanceId || '');
-    const supplied = body.device && typeof body.device === 'object' ? body.device : {};
     const device = {
       ...Object.fromEntries(Object.entries(supplied).filter(([, value]) => value !== undefined)),
       ip,
@@ -173,19 +230,30 @@ function createPairHandler(deps) {
 
     let issued;
     try {
-      issued = credentials.issue(instanceId, device, '');
+      issued = credentials.issue(instanceId, device, '', undefined, issuedExtra);
     } catch (error) {
       log('pair issue failed:', error && error.message);
       sendJson(res, 500, { ok: false, error: 'internal error' });
       return;
     }
 
-    // 两样都要给，缺一样 App 就停在「配对响应缺少 token/cookie」：
-    //  - `token` 是 **bearer**（`Authorization: Bearer …`），365 天；
-    //  - `cookie` 是**中转路由**用的那张，30 天。
-    // 两者的 TTL 刻意不同，别合成一个常量（见 relay/core.js 的 MOBILE_BEARER_TTL_SEC 注释）。
-    const token = core.signLanToken(state.lanSecret, instanceId, core.MOBILE_BEARER_TTL_SEC);
-    const cookieValue = core.signLanToken(state.lanSecret, instanceId, core.MOBILE_TOKEN_TTL_SEC);
+    // 成功签发之后立刻换码 + 换票据：谁截了二维码，那张图从这一刻起就没有用了。
+    if (rotatePairing) {
+      try {
+        rotatePairing();
+      } catch (error) {
+        log('pair rotate failed:', error && error.message);
+      }
+    }
+
+    // 三样给的是**同一枚**（§3.2 的 T1 口径）：`token`（`Authorization: Bearer`）、
+    // `cookie`（中转路由用的那张）与 `deviceCredential` 全等于刚签发的每设备凭据。
+    //
+    // 不再另签一张全局 HMAC Bearer：那张有效期一年、不带设备身份，发出去就吊销不掉 ——
+    // 而「单台吊销」正是 T1 存在的理由。一枚凭据既是通行证、又能在库里查到。
+    // 老 App 把整串当不透明串存起来，三段形状没变，它不需要改。
+    const token = issued.credential;
+    const cookieValue = issued.credential;
     const hostPlatform = pairingApproval.hostPlatform().platform;
     // 宿主自己那批直连候选随配对一起回给手机：手输公网地址（域名 / 公网 IP）配对时没有
     // 二维码，这是手机拿到内网地址的唯一机会。回家后那个公网地址若打不通（路由器不支持
@@ -199,8 +267,11 @@ function createPairHandler(deps) {
     const v6Candidates = state.lanEnabled && typeof ipv6Candidates === 'function'
       ? ipv6Candidates(port).map((candidate) => candidate.url).filter(Boolean)
       : []
-    sendJson(res, 200, {
+    const payload = {
       ok: true,
+      // 协议版本回给手机：它据此把 `MobileSession.proto` 落盘，之后每条请求按它决定发不发
+      // 信封。**握手时定死**，不逐请求协商（协商就等于给中转一个降级开关）。
+      proto: isSealedShape ? 2 : 1,
       instanceId,
       token,
       // cookie 同时放进 body：RN 的 fetch 读不到 Set-Cookie，App 得自己带上。
@@ -208,6 +279,9 @@ function createPairHandler(deps) {
       deviceId: issued.deviceId,
       deviceCredential: issued.credential,
       credentialExpiresAt: issued.expiresAt,
+      // 手机拿它对一次时钟（§8.3(7)）：时钟偏太多会被当成重放，而用户完全不知道
+      // 「这个 App 连不上」的原因是手机时间不准。
+      serverTime: Date.now(),
       // 宿主自己的系统标识，不是手机的。键名**必须是 `hostPlatform`**：App 落盘的就是它
       //（app/src/services/pairApi.ts 读 `body.hostPlatform` 存进 `MobileSession.hostPlatform`），
       // 局域网那条（lan-proxy.js）给的也是它。`hostPlatform()` 回的是 `{platform}` 对象，
@@ -215,7 +289,20 @@ function createPairHandler(deps) {
       ...(hostPlatform ? { hostPlatform } : {}),
       ...(directCandidates.length ? { lanUrls: directCandidates } : {}),
       ...(v6Candidates.length ? { ipv6Candidates: v6Candidates } : {}),
-    });
+    };
+
+    // 新协议的回包必须加密：里面有 token / cookie / deviceCredential，明文回包等于让
+    // 中转顺手拿到这台设备未来一年的通行证。
+    if (pairKey) {
+      try {
+        sendJson(res, 200, sealPairResponse(pairKey, instanceId, payload));
+      } catch (error) {
+        log('pair seal failed:', error && error.message);
+        sendJson(res, 500, { ok: false, error: 'internal error' });
+      }
+      return;
+    }
+    sendJson(res, 200, payload);
   };
 }
 
@@ -223,6 +310,5 @@ module.exports = {
   createPairHandler,
   resetPairLocks,
   clientIp,
-  PAIR_MAX_FAILS,
-  PAIR_LOCK_MS,
+  openSealedPairRequest,
 };

package/lib/mobile/plugin-self.js

@@ -0,0 +1,187 @@
+'use strict';
+
+/**
+ * 移动端「这台设备上的移动端插件」自我管理：版本、来源、运行状态、更新与回滚结果。
+ *
+ * ## 范围：只管**我们自己这一个插件**
+ *
+ * 手机管的是 `dsh-mobile-plugin` 自己在这台电脑上的版本 —— 不是电脑上装的全部插件
+ * （那是桌面「设置 → 插件 / 插件市场」的事，App 这边不碰）。理由很直接：动别人的插件会
+ * 把承载 App 连接的那条链一起带走，而手机没有在电脑前的那双手。
+ *
+ * ## 与 `/plugin/update/*` 那三条的关系
+ *
+ * 那三条是上一版给「应用更新」页做的，只有 `status / check / apply`。这里补的是同一件事
+ * 在**设备页**里需要的另外几格：来源与版本要不要并成一行、更新完**有没有自动退回去**、
+ * 以及「这一台能不能更新」为什么不给按钮的原因。判定仍然只有一份真源（外壳的
+ * `dshMobilePluginRuntime`），这里只做投影与瘦身，不自己算。
+ *
+ * ## 回滚是宿主自己做的，不是手机按的
+ *
+ * 装坏了 App 就连不上这台设备 —— 那时候手机上任何「回滚」按钮都发不出去。所以外壳在
+ * 装之前备份正在跑的那一代、装完自检（见 `lib/shell/self-check-after-swap.js`），
+ * 不过就自己退回去。手机端只做两件事：
+ *   · 更新后断了就按现有逻辑重连（`usePluginUpdate` 的轮询本身）；
+ *   · 连上之后读 `rolledBack`，如实显示「上次装失败了，已自动退回 X」。
+ *
+ * `rolledBack` 由外壳落进 `lastApply`，这里只认它、**不重新判**：判据写在会真去医院的那
+ * 一头，手机端各写一套只会出现两套口径。
+ */
+
+const { sendJson, readJsonBody } = require('../shared/http-util');
+
+/** 一次更新结果的合法状态（外壳给的 `state` 只有这几种取值，别的一律当未知）。 */
+const APPLY_STATES = new Set([
+  'succeeded',
+  'failed',
+  'installed-not-swapped',
+  'skipped',
+  'rolled-back',
+  'rolled-back-partial',
+]);
+
+/** 来源枚举：与 `update-install.cjs` 的 `declaredSource` 同一份。 */
+const SOURCES = new Set(['npm', 'linked', 'file', 'workspace']);
+
+/** 外壳服务；没有它（无头部署 / 实现被直接挂载）就是「这台没有升级能力」。 */
+function runtimeOf(ctx) {
+  try {
+    return typeof ctx?.get === 'function' ? ctx.get('dshMobilePluginRuntime') || null : null;
+  } catch {
+    return null;
+  }
+}
+
+function textOrNull(value, max = 200) {
+  if (typeof value !== 'string') return null;
+  const text = value.trim();
+  return text ? text.slice(0, max) : null;
+}
+
+/**
+ * 上一轮更新的账：只挑前端要用的几格。
+ *
+ * 刻意**不带** `check`（注册表原始响应）与 `command`（本机装法命令行）：都不是 App 该显示
+ * 的东西，后端那条路由背了同样的规矩。
+ */
+function applyView(value) {
+  if (!value || typeof value !== 'object') return null;
+  const failure = value.failure && typeof value.failure === 'object'
+    ? {
+      code: textOrNull(value.failure.code, 64),
+      message: typeof value.failure.message === 'string' ? value.failure.message : '',
+    }
+    : null;
+  return {
+    installed: value.installed === true,
+    skipped: value.skipped === true,
+    state: typeof value.state === 'string' && APPLY_STATES.has(value.state) ? value.state : null,
+    beforeVersion: textOrNull(value.beforeVersion, 64),
+    installedVersion: textOrNull(value.installedVersion, 64),
+    swapped: value.swapped === true,
+    retryable: value.retryable === true,
+    /**
+     * 装上了、但新版装起来之后自检没过，外壳自己退回了上一代。
+     *
+     * 这是「回滚」在手机端唯一的表达：它不是一颗按钮，是一条已经发生过的事实。
+     */
+    rolledBack: value.rolledBack === true,
+    /** 退回之后跑着的是哪个版本（外壳只在真的退成功时给）。 */
+    runningAfterRollback: textOrNull(value.runningAfterRollback, 64),
+    failure,
+  };
+}
+
+/**
+ * 这一台的插件现场。
+ *
+ * `supported` = 有没有可就地换代的外壳。没有外壳时「装了也没法立刻生效」，界面上要说明
+ * 清（无头部署 / 源码挂载的机器就是这种）。
+ */
+function snapshot(ctx) {
+  const runtime = runtimeOf(ctx);
+  if (!runtime || typeof runtime.status !== 'function') {
+    return {
+      supported: false,
+      runningVersion: null,
+      installedVersion: null,
+      source: null,
+      appliedAt: null,
+      lastApply: null,
+      shellChanged: false,
+      autoUpdate: false,
+      autoIntervalMs: null,
+    };
+  }
+  let raw = {};
+  try {
+    raw = runtime.status() || {};
+  } catch {
+    raw = {};
+  }
+  const source = textOrNull(raw.source, 32);
+  return {
+    supported: typeof runtime.apply === 'function',
+    runningVersion: textOrNull(raw.version, 64),
+    installedVersion: textOrNull(raw.installedVersion, 64),
+    source: source && SOURCES.has(source) ? source : (source || null),
+    appliedAt: textOrNull(raw.appliedAt, 64),
+    lastApply: applyView(raw.lastApply),
+    /** 这个版本连外壳一起改了：换得掉实现，外壳那部分要等下次启动 DSH。 */
+    shellChanged: raw.shellChanged === true,
+    autoUpdate: raw.autoUpdate === true,
+    autoIntervalMs: typeof raw.autoIntervalMs === 'number' && Number.isFinite(raw.autoIntervalMs) ? raw.autoIntervalMs : null,
+  };
+}
+
+/** `GET /api/mobile/v1/plugin/self` */
+async function handlePluginSelf(ctx, _req, res) {
+  sendJson(res, 200, { ok: true, plugin: snapshot(ctx) });
+}
+
+/**
+ * `POST /api/mobile/v1/plugin/self/auto` —— 自动更新开关（每 10 分钟自己查一次）。
+ *
+ * 只收布尔：这个开关意味着「没人看着也换掉正在跑的代码」，它必须是一个明确的选择。
+ * 给不出外壳（`setAutoUpdate` 不在）时回 409，不假装已经打开 —— 开了却什么都不做的开关
+ * 比没有更糟。
+ */
+async function handlePluginAuto(ctx, req, res) {
+  const runtime = runtimeOf(ctx);
+  if (!runtime || typeof runtime.setAutoUpdate !== 'function') {
+    return sendJson(res, 409, {
+      ok: false,
+      error: {
+        code: 'plugin_auto_unavailable',
+        message: '这台宿主没有可就地换代的插件外壳，自动更新开不了；请在电脑上更新后重启 DSH',
+      },
+    });
+  }
+  let body = {};
+  try {
+    body = (await readJsonBody(req, 4 * 1024)) || {};
+  } catch {
+    body = {};
+  }
+  if (typeof body.enabled !== 'boolean') {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: 'enabled 必须是布尔值' } });
+  }
+  try {
+    const enabled = runtime.setAutoUpdate(body.enabled);
+    return sendJson(res, 200, { ok: true, plugin: { ...snapshot(ctx), autoUpdate: enabled === true } });
+  } catch (error) {
+    return sendJson(res, 500, {
+      ok: false,
+      error: { code: 'write-failed', message: `开关没写进去：${error?.message || error}` },
+    });
+  }
+}
+
+module.exports = {
+  handlePluginSelf,
+  handlePluginAuto,
+  snapshot,
+  applyView,
+  APPLY_STATES,
+  SOURCES,
+};

package/lib/mobile/push-notify-route.js

@@ -0,0 +1,37 @@
+'use strict';
+
+/**
+ * POST /api/mobile/v1/push-token —— iOS 推送令牌上报。
+ *
+ * App 拿到 APNs 令牌（应用启动时向系统注册）就打到这里；宿主核对完设备身份
+ * （guarded 已做），经隧道帧 `pushRegister` 转交中转落表。中转没配 APNs 密钥时
+ * 那头静默忽略——这条路由照常回 ok：「推没推成」不是 App 要操心的事，它没有
+ * 可以据此改变行为的下一步。
+ *
+ * 隧道不在时也回 ok：令牌上报是幂等的，App 下次启动会再报，不值得为它排队重试。
+ */
+
+const { sendJson, readJsonBody } = require('../shared/http-util');
+
+/**
+ * @param {object} deps 装配注入。`pushNotify` 是 `mobile/push-notify.js` 的出口
+ *   （缺了就只回 ok——推送没接线时令牌上报不该 500）。
+ */
+function createPushTokenHandler(deps) {
+  const pushNotify = deps.pushNotify || null;
+  return function handlePushToken(_ctx, req, res) {
+    void readJsonBody(req).then((body) => {
+      const deviceId = typeof body?.deviceId === 'string' ? body.deviceId.trim() : '';
+      const token = typeof body?.token === 'string' ? body.token.trim() : '';
+      const platform = typeof body?.platform === 'string' ? body.platform.trim() : 'ios';
+      if (!deviceId || !token) {
+        sendJson(res, 400, { ok: false, error: 'deviceId and token are required' });
+        return;
+      }
+      if (pushNotify) pushNotify.registerToken(deviceId, token, platform);
+      sendJson(res, 200, { ok: true });
+    }, () => sendJson(res, 400, { ok: false, error: 'invalid json' }));
+  };
+}
+
+module.exports = { createPushTokenHandler };

package/lib/mobile/push-notify.js

@@ -0,0 +1,84 @@
+'use strict';
+
+/**
+ * iOS 推送的宿主侧出口：完成 / 失败 / 待回话发生时，经隧道发一帧给中转，
+ * 由中转调 APNs 送到苹果。中转没配密钥时那头静默忽略，这里照发不误——
+ * 「推没推成」不是宿主的账，宿主只负责「该推的时候说一声」。
+ *
+ * 走隧道而不是直接 HTTP 打中转：隧道连接已带准入校验（x-dsh-license），复用它
+ * 就不用在中转上再开一条要鉴权的 HTTP 面。隧道不在时这次提醒就放弃——App 端
+ * 自己的本地通知通道会在它回到前台 / 后台刷新时补上，推送只是增强。
+ */
+
+const FRAME_TTL_MS = 10_000;
+
+/**
+ * @param {object} deps
+ * @param {() => object|null} deps.getSidecar 取 sidecar facade 的取值器（它有 pushSync 通道）。
+ * @param {() => boolean} deps.tunnelConnected 隧道在不在。
+ * @param {() => string} [deps.instanceId] 实例标识，帧里带上便于中转日志定位。
+ */
+function createPushNotifier(deps) {
+  const getSidecar = typeof deps.getSidecar === 'function' ? deps.getSidecar : () => null;
+  const tunnelConnected = typeof deps.tunnelConnected === 'function' ? deps.tunnelConnected : () => false;
+  const instanceId = typeof deps.instanceId === 'function' ? deps.instanceId : () => '';
+
+  /** 最近一次已发送的（会话, 轮次, 结局）指纹：同一次收尾会被事件流与列表折叠两条路
+   *  各观察到一次，中转那边没有去重账，宿主必须自己只放一帧过去。 */
+  let lastSent = null;
+  let lastSentAt = 0;
+
+  /**
+   * 报告一轮收尾。`fact` 是 session-last-turn 的 `lastTurnOf` 形状
+   * （{ turn, endedAt, status, ... }），只有 completed / failed 两种值得推。
+   */
+  function notifyTurnEnded(sessionId, fact, title) {
+    if (!sessionId || !fact || typeof fact.turn !== 'number') return;
+    if (fact.status !== 'completed' && fact.status !== 'failed') return;
+    const fingerprint = `${sessionId}:${fact.turn}:${fact.status}`;
+    const now = Date.now();
+    if (fingerprint === lastSent && now - lastSentAt < FRAME_TTL_MS) return;
+    lastSent = fingerprint;
+    lastSentAt = now;
+    const body = fact.status === 'failed'
+      ? `出错了${fact.message ? `：${String(fact.message).slice(0, 60)}` : ''}`
+      : '回复已完成';
+    void send('push', {
+      kind: 'push',
+      pushFrame: 'send',
+      deviceId: '',
+      // deviceId 留空 = 这台实例上全部已登记设备都推。completion 的按设备记账
+      // 在 App 自己手里（本机已读水位），中转只存「实例 → 令牌」一级。
+      title: title || '任务提醒',
+      body,
+      sessionId,
+      kind: fact.status === 'failed' ? 'failed' : 'completed',
+      instanceId: instanceId(),
+    });
+  }
+
+  /** App 侧上报的推送令牌转交给中转（登记 / 删除）。 */
+  function registerToken(deviceId, token, platform) {
+    return send('push', {
+      kind: 'push',
+      pushFrame: 'register',
+      deviceId,
+      ...(token ? { token, platform: platform || 'ios' } : { action: 'delete' }),
+      instanceId: instanceId(),
+    });
+  }
+
+  function send(kind, payload) {
+    if (!tunnelConnected()) return Promise.resolve(false);
+    const sidecar = getSidecar();
+    if (!sidecar) return Promise.resolve(false);
+    return sidecar.pushSync(payload).then(
+      () => true,
+      () => false,
+    );
+  }
+
+  return { notifyTurnEnded, registerToken };
+}
+
+module.exports = { createPushNotifier };