dsh-mobile-plugin 0.1.100 → 0.2.1

package/lib/relay/lan-proxy.js

@@ -18,6 +18,9 @@ const { advertisedCandidates, ipv6Candidates, isGlobalUnicastV6 } = require('./l
 const { safeEqual } = require('../shared/dshtoken');
 const { isFreshRequest } = require('../shared/fresh-request');
 const { encodeJsonBody } = require('../shared/http-util');
+const { withViaHeader } = require('../shared/via-header');
+const { createPairThrottle } = require('../shared/pair-throttle');
+const { openSealedPairRequest, sealPairResponse } = require('../shared/e2ee-pair');
 const credentials = require('../shared/credentials-entry.js').credentialsEntry();
 
 const HOP_BY_HOP = new Set([
@@ -25,8 +28,6 @@ const HOP_BY_HOP = new Set([
   'te', 'trailer', 'transfer-encoding', 'upgrade', 'content-length',
 ]);
 
-const PAIR_MAX_FAILS = 5;
-const PAIR_LOCK_MS = 60_000;
 // 上游 WS 握手的一发超时：连上之后这条连接就是长连接（HMR、SSE 都从它过），
 // 所以只在「还没握上」这段时间里计时。
 const WS_UPSTREAM_HANDSHAKE_MS = 10_000;
@@ -46,6 +47,7 @@ function createLanProxy(opts) {
   const {
     lanPort,
     pairingCode,
+    pairingTicket = '',
     instanceId,
     lanSecret,
     upstreamPort,
@@ -57,6 +59,11 @@ function createLanProxy(opts) {
      * 都会退化成「知道 6 位配对码即可直连」的 fail-open——授权判断必须显式给出。
      */
     onApprove = async () => ({ approved: false }),
+    /**
+     * 配对成功之后调一次：换码 + 换票据（§5.1）。来回调交回装配层，因为「换」这件事要
+     * 同时写宿主状态并让旁路重读配置，不是这个代理的职责。
+     */
+    onPaired = null,
     /** 读取隔离：本地镜像快照读取回调，命中时直接回（不再连主进程）。 */
     readSnapshot = () => null,
     /** 上游 SSE 的失控闸，默认见 MAX_UPSTREAM_SSE_CONNECTIONS。 */
@@ -75,7 +82,34 @@ function createLanProxy(opts) {
   // 配对二维码里带的都是那个根本没在监听的死端口。
   let actualPort = lanPort;
   // 配对失败限流：ip -> { fails, lockedUntil }（与 relay 侧策略一致：5 次失败锁 60s）
-  const pairLocks = new Map();
+  /**
+   * 配对闸门（§10.4）。局域网这条**不用分来源**：来源就是手机真实的局域网地址，
+   * 而按来源分桶只解决「一个人打错把所有人锁死」；这里换成不看来源的全局令牌桶，
+   * 与宿主那条完全同口径（`shared/pair-throttle.js`）。
+   *
+   * 两份状态各自独立：这条跑在旁路子进程里、那条跑在主进程里，跨进程共享要么加锁
+   * 要么走 RPC，而两条路的网络含义本来就不同。
+   */
+  const pairThrottle = createPairThrottle();
+
+  /**
+   * 签发凭据。**在旁路子进程里必须走 IPC**（§3.7）：这个进程拿的是凭据库的只读副本，
+   * 自己写盘只会和主进程那份互相覆盖（旁路签的吊销会被回滚、主进程签的在旁路查不到，
+   * 经中转配上的手机回局域网就是 401）。装配层传进来就走它，测试里不传就用本地库。
+   */
+  const issueCredential = typeof opts.issueCredential === 'function'
+    ? opts.issueCredential
+    : (device, extra) => credentials.issue(instanceId, device, '', undefined, extra);
+
+  /**
+   * 当前配对码与票据。
+   *
+   * **必须是取值而不是快照**：配对成功之后宿主会立刻换码 + 换票据（§5.1），而重建局域网
+   * 代理会把刚握上的连接全掐掉。传入的是取值器就只换值、不动监听。
+   */
+  const currentPairing = typeof opts.currentPairing === 'function'
+    ? opts.currentPairing
+    : () => ({ code: pairingCode, ticket: pairingTicket });
 
   function log(...args) {
     onLog('[lan-proxy]', ...args);
@@ -86,48 +120,62 @@ function createLanProxy(opts) {
     return text.includes(':') ? `[${text}]` : text;
   }
 
-  function isPairLocked(ip) {
-    const l = pairLocks.get(ip);
-    return !!l && l.lockedUntil > Date.now();
-  }
-  function recordPairFail(ip) {
-    const l = pairLocks.get(ip) || { fails: 0, lockedUntil: 0 };
-    l.fails += 1;
-    if (l.fails >= PAIR_MAX_FAILS) {
-      l.lockedUntil = Date.now() + PAIR_LOCK_MS;
-      l.fails = 0;
-    }
-    pairLocks.set(ip, l);
-  }
-  function clearPairFails(ip) {
-    pairLocks.delete(ip);
+  /** 闸门状态重置（测试用）。 */
+  function resetPairThrottle() {
+    pairThrottle.noteSuccess();
   }
 
   /**
-   * 请求出示的设备凭据（`dshc_…`），取不到返回 null。
+   * 请求出示的凭据原文，取不到返回 null。
    *
-   * App 把设备凭据放在独立的 `X-Dsh-Device-Credential` 头里，`Authorization`
-   * 留给宿主 token（`app/src/services/authHeaders.ts`）。旧实现只从
-   * `Authorization` 里找 `dshc_`，于是本函数对真实 App 流量恒为 null，
-   * 「吊销能作用于局域网直连」从未落地。`Authorization` 分支仅用于兼容早期
-   * 客户端，保留但不作为主路径。
+   * 接受**任意非空串**，不再只认 `dshc_` 前缀（§3.2）：T1 是 `<实例号>.<exp>.<随机>`，
+   * 旧版是 `dshc_…`，升级前的老 App 还有 HMAC Bearer —— 三种都从这里过，由查库结果决定
+   * 走哪条路。App 把设备凭据放在独立的 `X-Dsh-Device-Credential` 头里，`Authorization`
+   * 留给宿主 token；`Authorization` 分支是给「只有一枚 Bearer 的旧客户端」的兜底。
+   *
+   * 旧实现只在这两处找 `dshc_`，于是本函数对真实 App 的 T1 流量恒为 null，
+   * 「吊销能作用于局域网直连」永远落不了地。
    */
   function presentedCredential(req) {
     const raw = req.headers['x-dsh-device-credential'];
     const header = Array.isArray(raw) ? raw[0] : raw;
-    if (typeof header === 'string' && header.startsWith('dshc_')) return header;
+    if (typeof header === 'string' && header.trim()) return header.trim();
     const m = /^Bearer\s+([^\s]+)$/.exec(req.headers.authorization || '');
-    return m && m[1].startsWith('dshc_') ? m[1] : null;
+    return m ? m[1] : null;
   }
-  /** 当前仍然有效的本机设备凭据；用于把该设备对应的宿主 token 转发给上游。 */
+  /**
+   * 这条请求对应的凭据记录（可能来自凭据头、Bearer 或 cookie）。
+   *
+   * 换上游令牌用（§3.3）：
+   *  - 新 T1 记录**不带 `hostToken`**，代理把请求里出示的那一枚原样设成上游 `Authorization`；
+   *  - 旧的 HMAC 记录仍用存下来的 `hostToken`（它那一枚是宿主的无状态令牌，规整不了）。
+   * 只有 cookie、没有 Bearer/头的请求（预览这类）也要能从 cookie 查记录，否则那条路径
+   * 换不到上游令牌，只能拿无状态 token 硬顶。
+   */
   function credential(req) {
     const presented = presentedCredential(req);
-    return presented ? credentials.find(presented, instanceId) : null;
+    if (presented) {
+      const found = credentials.lookup(presented, instanceId);
+      if (found) return { record: found, presented };
+      // 本机不认识这一枚（中转签的 / 升级前的 HMAC），往下按 cookie 再找一次。
+    }
+    const m = /dsh_lan=([^;]+)/.exec(req.headers.cookie || '');
+    const token = m ? m[1] : '';
+    if (!token) return null;
+    const byCookie = credentials.lookup(token, instanceId);
+    return byCookie ? { record: byCookie, presented: token } : null;
+  }
+  /** 上游要带的 `Authorization` 值：新记录用出示的那一枚，旧记录用存下的宿主令牌。 */
+  function upstreamTokenOf(found) {
+    if (!found) return null;
+    if (found.record && found.record.hostToken) return found.record.hostToken;
+    return found.presented || null;
   }
   /**
    * 无状态凭据校验：dsh_lan cookie 或 `Authorization: Bearer <token>`。两者同源
    * 同格式，均为 lanSecret 签名的 HMAC token；RN 在部分平台会丢弃手动 Cookie
-   * 头，故 Bearer 兜底。
+   * 头，故 Bearer 兜底。**只在凭据库查不到之后才走这里**：新配对发的是 T1，
+   * 而 T1 不是 HMAC 签名，验签必然不过。
    */
   function cookieValid(req) {
     const m = /dsh_lan=([^;]+)/.exec(req.headers.cookie || '');
@@ -138,23 +186,45 @@ function createLanProxy(opts) {
     return !!m && core.verifyLanToken(lanSecret, m[1], instanceId);
   }
   /**
-   * 鉴权。
+   * 鉴权结果，**带上被拒原因**（§3.8）：被吊销 / 已过期 / 只是没有凭据。
    *
-   * 顺序是这里唯一的要点：出示了**本机签发过**的设备凭据时以它为准，一旦被吊销
-   * 或过期就直接拒绝，不再回退到无状态 token —— HMAC token 有效期一年，允许回退
-   * 就等于吊销永远不生效。
+   * 顺序是这里唯一要紧的东西（§3.3）：**凭据头 → Bearer → cookie → 旧 HMAC**。前三种
+   * 都按「整串拿去查库」处理 —— 查到就按记录判（吊销/过期立即拒绝、绝不回退），查不到才
+   * 往下走。
    *
-   * 但「本机不认识这张凭据」必须回退：公网配对时凭据由中转签发并存在中转的凭据
-   * 库里（`dsh-mobile-server/lib/tunnel-handler.js`），宿主这里查不到。若一律拒绝，
-   * 「公网配对后回到局域网直连」这个主要用法会直接 401。
+   * 「本机不认识这一枚」必须能回退：公网配对时凭据可能是中转签的（那条库在中转那边），
+   * 宿主这里查不到；升级前的老 App 手上还有一枚 HMAC token。两种都靠无状态校验兜住，
+   * 若一律拒绝，「公网配对后回到局域网直连」这个主要用法会直接 401。
+   *
+   * 局域网这条也要分原因：被踢的手机回家连局域网，只回一句 401 的话用户看到的还是
+   * 「请求失败」，而它其实已经不能做任何事了。
    */
-  function authorized(req) {
-    const presented = presentedCredential(req);
-    if (presented) {
-      const known = credentials.lookup(presented, instanceId);
-      if (known) return credentials.isLive(known);
+  function authOutcome(req) {
+    const candidates = [];
+    const headerRaw = req.headers['x-dsh-device-credential'];
+    const header = Array.isArray(headerRaw) ? headerRaw[0] : headerRaw;
+    if (typeof header === 'string' && header.trim()) candidates.push(header.trim());
+    const bearer = /^Bearer\s+([^\s]+)$/.exec(req.headers.authorization || '');
+    if (bearer) candidates.push(bearer[1]);
+    const cookie = /dsh_lan=([^;]+)/.exec(req.headers.cookie || '');
+    if (cookie) candidates.push(cookie[1]);
+    // 候选里有**任何一枚**是本机签发过的，就以它为准：三种出示方式里只要有一枚能查到记录，
+    // 「这台设备被吊销了」就是答案，不能靠另外两枚里更宽松的那个绕过它。
+    for (const candidate of candidates) {
+      const known = credentials.lookup(candidate, instanceId);
+      if (!known) continue;
+      if (known.revokedAt) return { ok: false, reason: 'revoked' };
+      if (known.expiresAt && known.expiresAt <= Date.now()) return { ok: false, reason: 'expired' };
+      // 还剩不到一半就顺手续期（§3.9）。
+      try { credentials.renew(known); } catch { /* 续期失败不影响这一次 */ }
+      return { ok: true, record: known };
     }
-    return cookieValid(req) || bearerValid(req);
+    if (cookieValid(req) || bearerValid(req)) return { ok: true };
+    return { ok: false, reason: 'unauthorized' };
+  }
+
+  function authorized(req) {
+    return authOutcome(req).ok;
   }
   /**
    * 配对失败的统一响应。
@@ -170,10 +240,17 @@ function createLanProxy(opts) {
     } catch { /* 客户端已断开 */ }
   }
 
-  function setCookie(res) {
+  /**
+   * 下发 cookie。**值必须是请求里要返回的那一枚凭据**（§3.3）：新配对发 T1，
+   * 一边 T1 一边 HMAC 会让「浏览器侧」与「App 侧」拿到两种不同身份的东西。
+   *
+   * `Max-Age` 是浏览器侧的事，服务端一律以记录的到期为准，所以这里沿用 30 天；
+   * App 不受它影响（它自己带着 Bearer）。
+   */
+  function setCookie(res, credentialValue) {
     res.setHeader(
       'set-cookie',
-      `dsh_lan=${core.signLanToken(lanSecret, instanceId, core.MOBILE_TOKEN_TTL_SEC)}`
+      `dsh_lan=${credentialValue}`
       + `; Path=/; HttpOnly; SameSite=Lax; Max-Age=${core.MOBILE_TOKEN_TTL_SEC}`,
     );
   }
@@ -187,10 +264,24 @@ function createLanProxy(opts) {
    * 随后 `res.json()` 解析失败，桌面端换过 lanSecret 或凭据被吊销之后就永久卡住 ——
    * 一个「谁都能打开的页面」换来的这点便利不值这条风险。
    */
-  function sendUnauthorized(res) {
+  /**
+   * 未认证的统一出口。
+   *
+   * **绝不能回 200 HTML**：App 的 `response.ok` 会为真、把连接通道永久钉在局域网并重置
+   * 熔断，随后 `res.json()` 失败报「请求失败 (HTTP 200)」，既不回退中转也不提示重配。
+   *
+   * 被吊销 / 已过期的要说清是哪一种（§3.8）：只回一句「缺少或无效的移动 token」时，
+   * 用户看到的还是「请求失败」，而它其实已经不能做任何事了。
+   */
+  function sendUnauthorized(res, reason = 'unauthorized') {
+    const body = reason === 'revoked'
+      ? { ok: false, error: { code: 'device-revoked', message: '这台设备已被解除绑定，请重新扫码' } }
+      : reason === 'expired'
+        ? { ok: false, error: { code: 'device-expired', message: '这台设备的授权已过期，请重新扫码' } }
+        : { ok: false, error: { code: 'unauthorized', message: '缺少或无效的移动 token' } };
     try {
       res.writeHead(401, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
-      res.end(JSON.stringify({ ok: false, error: { code: 'unauthorized', message: '缺少或无效的移动 token' } }));
+      res.end(JSON.stringify(body));
     } catch { /* 客户端已断开 */ }
   }
 
@@ -198,7 +289,9 @@ function createLanProxy(opts) {
     // 读取隔离：命中本地镜像快照时直接回，不再连主进程。
     // 例外：带 ?fresh=1 的写后刷新必须回源——镜像最多旧 500ms，撞上写操作会把刚做完的
     // 事显示成没生效（判定与实测见 lib/shared/fresh-request.js）。
-    const body = isFreshRequest(req.url) ? null : readSnapshot({ method: req.method, path: req.url });
+    // 带上请求头：工人侧靠 `x-dsh-proto` 判「这条会话是不是加密的」，加密的必须回源主进程
+    // （快照那把捷径不封信封，见 sidecar-facade-worker 的 snapshotRead）。
+    const body = isFreshRequest(req.url) ? null : readSnapshot({ method: req.method, path: req.url, headers: req.headers });
     if (body && body.ok) {
       try {
         // 与中转那条同一条捷径：列表 / 工作区 / 消息 / 统计都在这里回，压缩才省得下来。
@@ -213,12 +306,11 @@ function createLanProxy(opts) {
       } catch { /* 已关闭 */ }
       return;
     }
-    const headers = {};
-    for (const [k, v] of Object.entries(req.headers)) {
-      if (!HOP_BY_HOP.has(k)) headers[k] = v;
-    }
-    // 保留手机端原始 Host（信任围栏按 Host 判定，配合桌面壳 --trusted-host 本机 IP）；缺省回退本地上游
-    if (!headers.host) headers.host = `${upstreamHost}:${upstreamPort}`;
+    const headers = withViaHeader(
+      Object.fromEntries(Object.entries(req.headers).filter(([k]) => !HOP_BY_HOP.has(k))),
+      'lan',
+      `${upstreamHost}:${upstreamPort}`,
+    );
     const isSse = String(req.headers.accept || '').toLowerCase().includes('text/event-stream');
     if (isSse && upstreamSseOpen >= maxUpstreamSse) {
       // 留一行日志：否则事后只看到手机端「连不上」，看不出是被这道闸挡的。
@@ -239,6 +331,9 @@ function createLanProxy(opts) {
           if (!HOP_BY_HOP.has(k)) out[k] = v;
         }
         res.writeHead(ures.statusCode, out);
+        // SSE 的第一段（`: connected` 与响应头）要立刻到手机，别等内核攒够一个段。
+        // 少了这一下，弱网 / 代理缓冲会把「流建好了」拖到十几秒之后。
+        if (typeof res.flushHeaders === 'function') res.flushHeaders();
         ures.pipe(res);
       },
     );
@@ -270,7 +365,11 @@ function createLanProxy(opts) {
       if (res.writableEnded) return;
       try { up.destroy() } catch { /* 已断开 */ }
     });
-    req.pipe(up);
+    // GET/HEAD 没有请求体：直接收尾发出去，不要依赖 `req` 的 `end` 事件 —— SSE 客户端的
+    // 那条连接未必会像普通 fetch 一样把请求流收掉，`pipe` 一直不 end，上游就永远不处理
+    // （2026-10-24 现场：设备级 SSE 每 32 秒重试，宿主侧一次都没进处理器）。
+    if (req.method === 'GET' || req.method === 'HEAD') up.end();
+    else req.pipe(up);
   }
 
   /** 升级还没被 ws 接管时的普通 HTTP 应答（对方看到的是握手失败与状态码）。 */
@@ -314,13 +413,15 @@ function createLanProxy(opts) {
       return;
     }
 
-    const headers = {};
-    for (const [key, value] of Object.entries(req.headers)) {
-      if (!HOP_BY_HOP.has(key) && value !== undefined) headers[key] = value;
-    }
-    if (!headers.host) headers.host = `${upstreamHost}:${upstreamPort}`;
-    const device = credential(req);
-    if (device?.hostToken) headers.authorization = `Bearer ${device.hostToken}`;
+    const headers = withViaHeader(
+      Object.fromEntries(Object.entries(req.headers).filter(([key, value]) => !HOP_BY_HOP.has(key) && value !== undefined)),
+      'lan',
+      `${upstreamHost}:${upstreamPort}`,
+    );
+    // 上游要认得这条请求：新 T1 记录没有存下来的宿主令牌，就把请求里出示的那一枚
+    // 原样带上去；旧 HMAC 记录仍用它自己的 hostToken。
+    const upstreamToken = upstreamTokenOf(credential(req));
+    if (upstreamToken) headers.authorization = `Bearer ${upstreamToken}`;
 
     let up;
     try {
@@ -470,43 +571,76 @@ function createLanProxy(opts) {
             req.on('data', (c) => (b += c));
             req.on('end', () => {
               try {
-                let code = '';
-                try { code = (JSON.parse(b || '{}').code || '').trim(); } catch { /* ignore */ }
-                // 长度不符直接判错（timingSafeEqual 长度不同会抛异常，曾导致整个 dsh web 崩溃）
-                if (!/^\d{6}$/.test(code)) {
-                  res.writeHead(400, { 'content-type': 'application/json' });
-                  res.end(JSON.stringify({ ok: false, error: '配对码需为 6 位数字' }));
+                const gate = pairThrottle.take();
+                if (!gate.allowed) {
+                  res.writeHead(429, { 'content-type': 'application/json', 'retry-after': String(gate.retryAfterSec) });
+                  res.end(JSON.stringify({ ok: false, error: '尝试过于频繁，请稍后再试' }));
                   return;
                 }
-                if (isPairLocked(ip)) {
-                  res.writeHead(429, { 'content-type': 'application/json' });
-                  res.end(JSON.stringify({ error: '尝试过于频繁，请稍后再试' }));
+                const input = JSON.parse(b || '{}')
+                // 两种形状（§8.3(2)）：带 `sealed` 是协议 v2，带 `code` 是旧 App。
+                const sealed = typeof input?.sealed === 'string' ? input.sealed.trim() : '';
+                // 与 `/pair` 同一条收口（§10.4(d)）：认得协议（请求里带 `proto`）却还带
+                // 六位码，只可能是过期的旧二维码 —— 那条形状逐位可试，不值得继续开门。
+                if (!sealed && input?.proto !== undefined) {
+                  res.writeHead(400, { 'content-type': 'application/json' });
+                  res.end(JSON.stringify({
+                    ok: false,
+                    code: 'legacy-pairing-retired',
+                    error: '这张二维码已过期，请重新扫一下电脑面板上当前的二维码',
+                  }));
                   return;
                 }
-                if (!safeEqual(code, String(pairingCode))) {
-                  recordPairFail(ip);
-                  pairDenied(res);
-                  return;
+                let suppliedDevice;
+                let issuedExtra;
+                let pairKey = null;
+                if (sealed) {
+                  const opened = openSealedPairRequest({
+                    ticket: currentPairing().ticket || '',
+                    instanceId,
+                    sealed,
+                    claimedInstanceId: typeof input.instanceId === 'string' ? input.instanceId : '',
+                  });
+                  if (!opened.ok) {
+                    // 解不开就是「配对失败」，与「配对码错误」同形，不给探测空间。
+                    pairThrottle.noteFail();
+                    pairDenied(res);
+                    return;
+                  }
+                  suppliedDevice = opened.device;
+                  issuedExtra = { deviceKey: opened.deviceKey, keyId: opened.keyId };
+                  pairKey = opened.pairKey;
+                } else {
+                  const code = typeof input?.code === 'string' ? input.code.trim() : '';
+                  // 长度不符直接判错（timingSafeEqual 长度不同会抛异常，曾导致整个 dsh web 崩溃）
+                  if (!/^\d{6}$/.test(code)) {
+                    res.writeHead(400, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: '配对码需为 6 位数字' }));
+                    return;
+                  }
+                  if (!safeEqual(code, String(currentPairing().code || ''))) {
+                    pairThrottle.noteFail();
+                    pairDenied(res);
+                    return;
+                  }
+                  suppliedDevice = input && typeof input.device === 'object' && input.device !== null
+                    ? input.device
+                    : {
+                      name: input?.name,
+                      platform: input?.platform,
+                      osVersion: input?.osVersion,
+                      version: input?.version,
+                      appVersion: input?.appVersion,
+                      id: input?.id,
+                      deviceId: input?.deviceId,
+                    }
                 }
-                // 配对码正确 → 桌面端授权（TeamViewer 模型）。保留旧版
-                // 仅传 code 的请求，同时透传手机端完整设备元数据。
+                // 配对码正确 / 票据解得开 → 桌面端授权（TeamViewer 模型）。透传手机端完整设备元数据。
                 // 注意：这里**不**清限流计数——被拒绝的尝试同样要计数，否则
                 // 猜对配对码但被拒的一方可以无限次重试。
-                const input = JSON.parse(b || '{}')
-                const suppliedDevice = input && typeof input.device === 'object' && input.device !== null
-                  ? input.device
-                  : {
-                    name: input?.name,
-                    platform: input?.platform,
-                    osVersion: input?.osVersion,
-                    version: input?.version,
-                    appVersion: input?.appVersion,
-                    id: input?.id,
-                    deviceId: input?.deviceId,
-                  }
                 const device = {
-                  ...Object.fromEntries(Object.entries(suppliedDevice).filter(([, value]) => value !== undefined)),
-                  ip: suppliedDevice.ip || ip,
+                  ...Object.fromEntries(Object.entries(suppliedDevice || {}).filter(([, value]) => value !== undefined)),
+                  ip: (suppliedDevice && suppliedDevice.ip) || ip,
                 }
                 onApprove(device)
                   .then(({ approved, token, platform }) => {
@@ -515,33 +649,59 @@ function createLanProxy(opts) {
                       pairDenied(res);
                       return;
                     }
-                    clearPairFails(ip);
-                    const issued = credentials.issue(instanceId, device, token);
-                    const cookieValue = core.signLanToken(lanSecret, instanceId, core.MOBILE_TOKEN_TTL_SEC);
-                    setCookie(res);
-                    // 宿主自己那批直连候选一起回给手机：手输公网地址（域名 / 公网 IP）配对时，
-                    // 二维码那条路没有、也就只有这一处能拿到内网地址。回家后如果那个公网地址
-                    // 打不通（路由器不支持回环 / 域名只在外网解析），手机还能靠这批候选找到这台
-                    // 机器，否则只能删设备重配。App 的 `doPair` 本来就合并响应里的 `lanUrls`
-                    // 与 `ipv6Candidates`，这里不回它就只能记住手输的那一个地址。
-                    const directCandidates = advertisedCandidates(actualPort).map((candidate) => candidate.url).filter(Boolean);
-                    const v6Candidates = ipv6Candidates(actualPort).map((candidate) => candidate.url).filter(Boolean);
-                    res.writeHead(200, { 'content-type': 'application/json' });
-                    // cookie 同时放进 body：RN fetch 读不到 Set-Cookie 响应头，App 需自行携带
-                    res.end(JSON.stringify({
-                      ok: true,
-                      instanceId,
-                      token: token || '',
-                      cookie: `dsh_lan=${cookieValue}`,
-                      ...(directCandidates.length ? { lanUrls: directCandidates } : {}),
-                      ...(v6Candidates.length ? { ipv6Candidates: v6Candidates } : {}),
-                      deviceId: issued.deviceId,
-                      deviceCredential: issued.credential,
-                      credentialExpiresAt: issued.expiresAt,
-                      // 宿主自己的系统标识，不是手机的。手机把它存进设备记录，
-                      // 好让设备行在第一次 status 轮询之前就画得出图标。
-                      ...(platform ? { hostPlatform: platform } : {}),
-                    }));
+                    pairThrottle.noteSuccess();
+                    // 新签发的是每设备凭据本身，它同时当 Bearer、cookie 与 deviceCredential
+                    // （§3.2）。旁路子进程里这一步要打到主进程（唯一写方，§3.7）。
+                    return Promise.resolve(issueCredential(device, issuedExtra)).then((issued) => {
+                      const credentialValue = issued.credential;
+                      setCookie(res, credentialValue);
+                      // 配对成功即换码 + 换票据（§5.1）。谁截了二维码，那张图从这一刻起就作废。
+                      if (typeof onPaired === 'function') {
+                        try { onPaired(); } catch (error) { log('rotate pair failed:', error && error.message); }
+                      }
+                      // 宿主自己那批直连候选一起回给手机：手输公网地址（域名 / 公网 IP）配对时，
+                      // 二维码那条路没有、也就只有这一处能拿到内网地址。回家后如果那个公网地址
+                      // 打不通（路由器不支持回环 / 域名只在外网解析），手机还能靠这批候选找到这台
+                      // 机器，否则只能删设备重配。App 的 `doPair` 本来就合并响应里的 `lanUrls`
+                      // 与 `ipv6Candidates`，这里不回它就只能记住手输的那一个地址。
+                      const directCandidates = advertisedCandidates(actualPort).map((candidate) => candidate.url).filter(Boolean);
+                      const v6Candidates = ipv6Candidates(actualPort).map((candidate) => candidate.url).filter(Boolean);
+                      const payload = {
+                        ok: true,
+                        proto: pairKey ? 2 : 1,
+                        instanceId,
+                        token: credentialValue,
+                        cookie: `dsh_lan=${credentialValue}`,
+                        // 手机拿它对一次时钟（§8.3(7)）：时钟偏太多会被当成重放，
+                        // 而用户完全不知道「这个 App 连不上」的原因是手机时间不准。
+                        serverTime: Date.now(),
+                        ...(directCandidates.length ? { lanUrls: directCandidates } : {}),
+                        ...(v6Candidates.length ? { ipv6Candidates: v6Candidates } : {}),
+                        deviceId: issued.deviceId,
+                        deviceCredential: issued.credential,
+                        credentialExpiresAt: issued.expiresAt,
+                        // 宿主自己的系统标识，不是手机的。手机把它存进设备记录，
+                        // 好让设备行在第一次 status 轮询之前就画得出图标。
+                        ...(platform ? { hostPlatform: platform } : {}),
+                      };
+                      // 新协议的回包必须加密：里面有 token / cookie / deviceCredential，
+                      // 明文回包等于让链路上的任何人顺手拿到这台设备未来一年的通行证。
+                      if (pairKey) {
+                        try {
+                          res.writeHead(200, { 'content-type': 'application/json' });
+                          res.end(JSON.stringify(sealPairResponse(pairKey, instanceId, payload)));
+                          return;
+                        } catch (error) {
+                          log('pair seal failed:', error && error.message);
+                          res.writeHead(500, { 'content-type': 'application/json' });
+                          res.end(JSON.stringify({ ok: false, error: 'internal error' }));
+                          return;
+                        }
+                      }
+                      res.writeHead(200, { 'content-type': 'application/json' });
+                      // cookie 同时放进 body：RN fetch 读不到 Set-Cookie 响应头，App 需自行携带
+                      res.end(JSON.stringify(payload));
+                      })
                   })
                   .catch((err) => {
                     log('approve error:', err.message);
@@ -572,13 +732,14 @@ function createLanProxy(opts) {
             proxyToUpstream(req, res);
             return;
           }
-          if (!authorized(req)) {
-            sendUnauthorized(res);
+          const auth = authOutcome(req);
+          if (!auth.ok) {
+            sendUnauthorized(res, auth.reason);
             return;
           }
-          const c = credential(req);
-           if (c?.hostToken) req.headers.authorization = `Bearer ${c.hostToken}`;
-           proxyToUpstream(req, res);
+          const upstreamToken = upstreamTokenOf(credential(req));
+          if (upstreamToken) req.headers.authorization = `Bearer ${upstreamToken}`;
+          proxyToUpstream(req, res);
         } catch (err) {
           log('request error:', err.message);
           try {

package/lib/relay/protocol.js

@@ -20,9 +20,9 @@
  */
 
 const T = {
-  register: 0x01,      // id=0  JSON {instanceId, pairingCode, name, lanUrls?, lanCandidates?}
+  register: 0x01,      // id=0  JSON {instanceId, name, lanUrls?, lanCandidates?, secret?}
   registered: 0x02,    // id=0  JSON {}
-  updatePairing: 0x03, // id=0  JSON {pairingCode}
+  updatePairing: 0x03, // id=0  JSON {}（保留编号，宿主已不再发；中转从不读）
   httpRequest: 0x04,   // id=N  JSON {method, path, headers}；body 随后以 httpBody 流式发送
   httpBody: 0x05,      // id=N  raw bytes（空 payload = body 结束）
   httpHead: 0x06,      // id=N  JSON {status, headers}
@@ -45,6 +45,8 @@ const T = {
   sync: 0x17,          // id=0  JSON {kind, ...}；桌面→中转主动推送（移动端镜像缓存）
   revokeAll: 0x18,     // id=0  JSON {at}；桌面请求中转清空本实例全部设备授权
   revokeAllAck: 0x19,  // id=0  JSON {ok, revoked}；中转确认已清空
+  pushRegister: 0x1A,  // id=0  JSON {deviceId, platform, token}；宿主代 App 上报 iOS 推送令牌（本实例）
+  pushSend: 0x1B,      // id=0  JSON {deviceId, title, body, sessionId?, kind}；宿主请求中转发一条 APNs 推送
 };
 
 const TYPE_NAME = {};