dsh-in-hand 1.7.0 → 1.7.2

package/README.md

@@ -109,11 +109,12 @@ DSH 的 Web GUI 没有内置鉴权，而默认 preset 往往是 `danger-full-acc
 | `/taskwatch/chat/page?...` | JSON | 往更早翻会话历史 |
 | `/taskwatch/chat/stream?sessionId=` | SSE | 跟随一个会话：开场快照 + 增量事件 + 逐字输出 |
 | `/taskwatch/chat/queue?sessionId=` | JSON | 该会话未领取的消息：`items`（下一轮队列，可重排）与 `steering`（已插到本回合下一步） |
+| `/taskwatch/entries` | JSON | 双入口清单：`{entries:[{kind:'remote'\|'lan',label,url,current}]}`；没配 `publicUrl` 时只有局域网一条 |
 | `/taskwatch/manifest.webmanifest` | JSON | PWA manifest |
 | `/taskwatch/sw.js` | JS | service worker |
 | `/taskwatch/icon-192.png` · `/taskwatch/icon-512.png` | PNG | 图标 |
 
-写（`POST`）—— **只有这 6 条**：
+写（`POST`）—— 只有这 6 条对话入口，外加一条不写宿主状态的换路票据：
 
 | 路径 | 请求体 | 说明 |
 |---|---|---|
@@ -123,9 +124,11 @@ DSH 的 Web GUI 没有内置鉴权，而默认 preset 往往是 `danger-full-acc
 | `/taskwatch/chat/create` | `{}` 或 `{workspace}` | 新建会话；`workspace` 必须命中 `/taskwatch/chat/workspaces` 列出的路径 |
 | `/taskwatch/chat/model` | `{sessionId,provider,model}` | 切换该会话使用的模型 |
 | `/taskwatch/chat/queue/reorder` | `{sessionId,ids:[...]}` | 重排下一轮队列；`ids` 必须是当前队列的完整 id 列表 |
+| `/taskwatch/ticket` | `{to:'remote'\|'lan'}` | 签发 60 秒的 **v2 HMAC 换路票据**（`v2.<exp>.<nonce>.<hmac>`），宿主与中继用同一密钥互认；只在内存里记已用的 nonce，不碰会话 / 文件 / 配置。没配 `publicUrl` 时远端请求回 `409 no-public-entry` |
 
 全部注册在 `ctx.webServer` 上，不代理 DSH 自身的 `/api`，也不转发任意路径。
-写入口就只有上面 6 条 —— 契约测试会**正面清点**路由表，增删都会让构建失败
+写入口就只有上面 6 条对话入口 + 1 条换路票据 —— 契约测试会**正面清点**路由表，
+新增路由必须在只读 / 对话 / 非对话写三张白名单里显式归类，漏一个就让构建失败
 （早先那条断言写的是"源码里不出现 `method === 'POST'`"。加了 5 个写路由之后它
 照样通过，是条假绿灯：它证明的是"没这么写"，不是"没有这个能力"）。
 
@@ -459,21 +462,60 @@ PWA 外壳由中继本地提供（而不是转发上游），这样它不随上
 换路等于换了一个**源**（`https://…` ↔ `http://192.168.x.x:3099`），而浏览器的 cookie 是
 **按源隔离**的 —— 在远端那条路上换到的 cookie，到了局域网这条路等于不存在。
 
-所以页面点切换时，先向当前这条路的中继要一张凭据：
+所以页面点切换时，先向当前这条路的**宿主**（中继，或插件宿主本身）要一张凭据：
 
-1. `POST /taskwatch/ticket`（带令牌）→ 中继返回另一条路的 URL，末尾带一次性 `?t=…`；
-2. 手机跳过去，中继兑换这张票：**60 秒有效、兑换即作废、重放无效**，同时给那条路种下
-   cookie；
-3. 于是不用重新输那 6 位配对码。
+1. `POST /taskwatch/ticket`（中继上要带令牌）→ 返回另一条路的 URL，末尾带 `?t=…`；
+2. 手机跳过去，对面兑换这张票并给那条路种下 cookie，于是不用重新输那 6 位配对码；
+3. 中继与插件宿主**跑在同一台机器、同一个用户下**，用同一个密钥验签，所以宿主签的票
+   打到公网（域名后面是中继）也能被中继认，反之亦然。
 
-这三个接口都在中继侧，**中继不在本仓库**：`GET /taskwatch/entries`（入口清单与当前入口）、
-`POST /taskwatch/ticket`（换路凭据）、`GET /taskwatch/upstream-health`（上游体检）。
-详细的实现与部署文档在中继仓库 **`dsh-in-hand-relay`**（该仓库尚未创建，此处只写仓库名）。
-中继没升级时，页面上的胶囊不会出现，其余功能不受影响。
+**v1.7.1 起，前两条插件宿主也自己实现了**（同一套语义）：`GET /taskwatch/entries`
+回答「现在有哪几条路」，`POST /taskwatch/ticket` 给一张换路票据。
+所以从宿主页面（例如 `http://127.0.0.1:52676/taskwatch`）点「去远端」不再拿到 405 / 404。
+`GET /taskwatch/upstream-health` 仍只有中继实现；宿主页面拿到它的 404 时按「未知」处理，
+并停掉探测 —— **不会**把「没有体检接口」误判成「这条路断了」。
 
-> 注：上面「在外网 / 手机上访问」一节描述的是只转发读路径的只读中继；实际的中继同时
-> 承载 `/taskwatch/chat/*` 的写入口（见上面的路由表）和本节这三个双入口接口。中继代码
-> 不在本仓库。
+#### 票据格式（v1.7.2）
+
+```text
+t = 'v2.' + <expMs 十进制> + '.' + <nonce base64url> + '.' + <hmac base64url>
+HMAC = HMAC-SHA256(secret, 'v2|' + expMs + '|' + nonce)
+nonce = crypto.randomBytes(16)         # base64url 后 22 个字符
+```
+
+校验顺序：格式 → `timingSafeEqual` 比 HMAC → `expMs > now` → `expMs - now <= 180000`
+（60 秒 TTL + 时钟偏差）。签名不对 / 过期 / 格式不符一律当作「不是本票」；只有**不是**
+`v2.` 形状的字符串才回落到原来的进程内 Map（老页面、老票仍然能用）。票据有效期内
+两边各自维护一个已用 nonce 的 Set（带 TTL 清理）做**进程内 best-effort 去重** ——
+这不是严格一次性，详见下面「安全边界」。
+
+公网地址只来自插件配置项 `publicUrl`（也支持环境变量 `DSH_TASKWATCH_PUBLIC_URL`），
+局域网入口可以选配 `lanUrl`（也支持 `DSH_TASKWATCH_LAN_URL`），代码里不写死任何域名：
+
+```yaml
+- insert:
+    - id: dsh-in-hand
+      name: dsh-in-hand
+      config:
+        publicUrl: https://dsh.example.com
+        lanUrl: http://192.168.1.5:3099     # 指向中继的局域网入口（有令牌门）
+```
+
+配了 `lanUrl` 就把 `entries` 的局域网条目换成它，不再自动探测内网 IP；没配保持现状。
+**插件自己的路由没有令牌门**（授权由中继那层负责），所以建议把 `lanUrl` 指到有鉴权的
+中继，而不是直接指回插件宿主。
+
+没配 `publicUrl` 时只报局域网入口；`ticket` 的远端请求明确回 `409 no-public-entry`。
+宿主这层仍然不做令牌校验（401 由中继负责），但票据是写路由，所以和中继的写路由同一套
+门禁：`POST` + `application/json` + 同源（`Origin` / `Sec-Fetch-Site`）校验。
+
+页面侧遇到这两条接口的 **404 / 405** 会进入**静态降级**：不重试、不弹错，胶囊按
+「只有一个入口」隐藏；设置 / 任务详情里留一行说明与一个手动「去远端」链接
+（上次成功的地址记在 `localStorage['tw-remote-url']`）。500 / 502 / 网络错误只提示一次
+（同一句 30 秒内不重复弹），不会变成重试风暴。
+
+> 中继那边另有独立实现，见中继仓库 `dsh-in-hand-relay`（该仓库尚未创建，此处只写仓库名）。
+> 中继没升级时，页面在宿主上仍能正常用，只是没有远端切换。
 
 ### 502 排查
 
@@ -500,6 +542,17 @@ PWA 外壳由中继本地提供（而不是转发上游），这样它不随上
 - 手机上做的每一步都会落进该会话的日志，桌面上打开同一个会话就能看到全部经过 ——
   这是"远程操作可追溯"的那一半。
 - 插件的路由只在**回环**上监听，从不对外。
+- **跨进程票据密钥**放在 `<用户主目录>/.dsh/taskwatch-ticket.key`（UTF-8、`trim` 后
+  至少 32 字符）。两边的解析顺序完全一致：环境变量 `TASKWATCH_TICKET_SECRET` → 该文件
+  → 都没有时由**先用到的一方生成**（`crypto.randomBytes(32).toString('base64url')`）。
+  Windows 下生成后用 `icacls <file> /inheritance:r /grant:r <当前用户>:F` 去掉继承、
+  只留当前用户；Linux/macOS 用 `chmod 600`。该文件**绝不能进任何 git 仓库**：插件仓库的
+  `.gitignore` 已加 `taskwatch-ticket.key` 与 `*.key`，真实文件在 `~/.dsh/` 下、
+  本来就不在仓库里。
+- **票据不是严格一次性**。签名 + 60 秒时效 + 两边各自的进程内 nonce 去重，把重放窗口
+  压得很小，但跨进程没有共享的「已用」状态 —— 一张从未被这两个进程见过的票，理论上
+  在有效期内仍可能被重放一次。要严格一次性就得引入共享存储（Redis / SQLite），
+  当前「换路跳转」的场景不值得为此多一个依赖与故障点。
 - 页面带 `X-Robots-Tag: noindex, nofollow`，响应带 `nosniff`。除 `/taskwatch/data`
   （见下）外一律 `no-store`。
 - service worker 的作用域**限定为 `/taskwatch`**（注册时即指定，脚本也放在
@@ -546,7 +599,7 @@ PWA 外壳由中继本地提供（而不是转发上游），这样它不随上
 ## 开发
 
 ```sh
-npm run check                   # bundle、文件边界、上传路由与页面契约测试
+npm run check                   # bundle、文件边界、上传路由、页面契约与票据 HMAC 互认测试
 node scripts/make-icons.mjs     # 重新生成图标（自实现 PNG 编码，零依赖）
 node scripts/make-demo.mjs      # 生成 docs/demo.html（假数据，供截图与预览）
 ```
@@ -561,6 +614,12 @@ node scripts/make-demo.mjs      # 生成 docs/demo.html（假数据，供截图
 失败重试、数量 / 总大小限制、错误的请求方法与类型，以及宿主缺少上传服务时的错误提示；
 测试只使用内存 fake 服务，不会连接真实模型。
 
+`check-ticket-hmac.mjs` 覆盖跨进程票据：宿主签 → 中继实例验、中继签 → 宿主验、篡改签名、
+过期 / 超长跨度、老格式随机票仍走原 Map、以及密钥文件自动生成（只断言存在与长度，
+从不打印内容）。中继那一侧在本机存在时是**真的 spawn 一个临时端口实例**（临时令牌、
+不碰 3099 生产进程，测完杀掉）；中继目录不在本机时这两条明确 SKIP，公开仓库的 CI 不会
+因此变红。
+
 为什么宿主也要钉住：Cordis 的 `inject` 决定框架等哪些服务就绪后才调用 `apply`。
 `webServer` 的服务是在启动阶段之后才发布的，而 `apply` 在组合期就会被调用——
 只写 `ctx.get('webServer')` 软读会在那一刻拿到 `undefined`，于是整段路由注册被

package/lib/index.js

@@ -8,19 +8,25 @@
  * 采集面：会话（运行/空闲、最后活动、activeJobs）、后台任务 jobs、
  * 子代理树、目标轮次与阻塞、工作流阶段、等待审批/提问。
  *
- * 只读：不提供任何写操作、不接受请求体、不代理 DSH 自身的 /api。
+ * 只读为主：除对话接口外不写宿主状态、不代理 DSH 自身的 /api。唯一的例外是
+ * 换路票据（POST /taskwatch/ticket）—— v1.7.2 起签的是 60 秒、HMAC 签名的 v2 票，
+ * 与中继共用同一个本机密钥，所以跨进程能互认；进程内只记已用的 nonce，不碰会话、
+ * 文件或配置，见下方「双入口」一节与 lib/ticket.js。
  *
  * 静态资源（PWA）都挂在 /taskwatch/ 之下，service worker 的作用域也限定为
  * /taskwatch —— 绝不允许它有机会拦截主 GUI 的请求。
  */
 import { readFileSync, statSync } from 'node:fs'
-import { createHash, randomUUID } from 'node:crypto'
-import { homedir } from 'node:os'
+import { createHash, randomBytes, randomUUID } from 'node:crypto'
+import { homedir, networkInterfaces } from 'node:os'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 // 交付文件的解析与安全边界都在 files.js —— 白名单、穿越防护、类型白名单需要能被
 // 测试直接调用，放在路由闭包里就证明不了。
 import { MAX_BYTES, dispositionFor, infoOf, resolveTarget, rootsFrom } from './files.js'
+// 跨进程换路票据：宿主与中继共用同一套 v2 HMAC 格式与密钥解析顺序。
+// 单独成模块是为了纯函数能被测试直接钉住，也避免两边各写一份实现后悄悄漂移。
+import { createTicketGate, loadTicketSecret } from './ticket.js'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 
@@ -149,6 +155,130 @@ const why = (e) => (e && e.message ? String(e.message) : String(e))
 
 const ENV_ASSIGN = /^\$env:[A-Za-z_][A-Za-z0-9_]*\s*=/i
 
+// ── 双入口：入口清单与一次性换路票据 ────────────────────────────────────────
+//
+// 背景（2026-10-21，v1.7.1 修的真实故障）：页面在插件宿主上打开时，点「去远端」
+// 会打 POST /taskwatch/ticket 与 GET /taskwatch/entries。这两个接口原先**只有中继
+// 实现**，宿主没有：实测宿主回 405 / 404，页面拿不到 url，探测循环每 12 秒再试一次，
+// 于是在手机上看就是"点了去远端就一直报错"。
+//
+// 现在宿主按中继的语义补齐这两条；公网地址只从配置项 publicUrl 来，**绝不写死域名**。
+// 没配就只报价局域网入口，ticket 明确回 409 no-public-entry。
+//
+// v1.7.2：票据从"进程内随机串"升级成 v2 HMAC。根因是宿主签的票打到公网（域名后面是
+// 中继）→ 中继只认自己 Map 里的串 → 401。两边共用 <home>/.dsh/taskwatch-ticket.key，
+// 所以现在互认；老格式随机票仍回落到进程内 Map。
+//
+// 鉴权边界不变：宿主这层不做令牌校验（和中继的分工见 README），但 ticket 是**写**路由，
+// 所以和中继的写路由一样要求 POST + application/json（跨站表单发不出这个 content-type，
+// 天然需要 preflight，而宿主不应答 CORS 预检），另加一道 Origin / Sec-Fetch-Site 校验。
+export const TICKET_TTL_MS = 60 * 1000
+const TICKET_MAX = 256
+
+/** 公网入口只接受纯 origin（https://host[:port]），带路径的一律当作没配 ——
+ *  否则 302 的 Location 是根绝对路径，和子路径部署对不上，切换会静默跳到错地方。 */
+export function normalizePublicUrl(raw) {
+  const text = typeof raw === 'string' ? raw.trim().replace(/\/+$/, '') : ''
+  if (!text) return ''
+  try {
+    const parsed = new URL(text)
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return ''
+    if (!parsed.hostname) return ''
+    if (parsed.pathname && parsed.pathname !== '/') return ''
+    return parsed.origin
+  } catch {
+    return ''
+  }
+}
+
+/** 局域网 IPv4 地址。虚拟网卡（WSL / Hyper-V / docker）不算"手机能连的入口"，
+ *  否则入口清单里会出现一个手机永远打不开的地址 —— 那比不显示更糟。 */
+const VIRTUAL_IFACE = /vEthernet|Hyper-V|WSL|VMware|VirtualBox|Loopback|docker|Bluetooth|TAP-/i
+export function lanAddresses(ifaces, includeVirtual = false) {
+  const table = ifaces && typeof ifaces === 'object' ? ifaces : networkInterfaces()
+  const out = []
+  for (const name of Object.keys(table)) {
+    if (!includeVirtual && VIRTUAL_IFACE.test(name)) continue
+    for (const addr of table[name] || []) {
+      if (!addr || addr.internal) continue
+      if (addr.family !== 'IPv4' && addr.family !== 4) continue
+      const ip = asText(addr.address)
+      if (ip) out.push({ iface: name, ip })
+    }
+  }
+  return out
+}
+
+/** 局域网入口也可以指向别处（通常是中继的局域网入口）。只接受纯 origin：
+ *  带路径的值和 publicUrl 一样会让 302 / 入口清单对不上，一律当作没配。 */
+export function normalizeLanUrl(raw) {
+  return normalizePublicUrl(raw)
+}
+
+/** 票据存储：60 秒、一次性。单独抽出来的原因是"过期"要能被测试钉住 ——
+ *  真等 60 秒的测试不会有人跑，而"只删不校验过期"是这类实现最常见的漏洞。
+ *
+ *  v1.7.2 起它只承担**向后兼容**：老页面的随机串仍在这个 Map 里兑换；新签发的
+ *  票是 v2 HMAC（见 lib/ticket.js），跨进程可用。 */
+export function createTicketStore({ ttlMs = TICKET_TTL_MS, now = Date.now } = {}) {
+  const tickets = new Map()
+  return {
+    mint() {
+      const at = now()
+      for (const [key, exp] of tickets) if (exp <= at) tickets.delete(key)
+      // 突发时丢最早的一张：票据只有 60 秒寿命，超出上限的多半是重试风暴的残留。
+      while (tickets.size >= TICKET_MAX) {
+        const oldest = tickets.keys().next().value
+        if (oldest === undefined) break
+        tickets.delete(oldest)
+      }
+      const ticket = randomBytes(18).toString('base64url')
+      tickets.set(ticket, at + ttlMs)
+      return ticket
+    },
+    /** 命中即删 —— 无论是否过期，同一张票据第二次兑换一律无效。 */
+    redeem(ticket) {
+      const key = asText(ticket)
+      if (!key) return false
+      const exp = tickets.get(key)
+      if (exp === undefined) return false
+      tickets.delete(key)
+      return exp > now()
+    },
+    get size() { return tickets.size },
+  }
+}
+
+/** 写路由的跨站门禁：显式声明 cross-site 的直接拒；带 Origin 的必须与 Host 同源。
+ *  没有 Origin 的（curl、非浏览器客户端）放行 —— 与"宿主不做令牌校验"的边界一致，
+ *  这里只负责挡住浏览器里的跨站页面。 */
+function isCrossSite(req) {
+  const headers = (req && req.headers) || {}
+  if (String(headers['sec-fetch-site'] || '').toLowerCase() === 'cross-site') return true
+  const origin = asText(headers.origin)
+  if (!origin) return false
+  let originHost = ''
+  try { originHost = new URL(origin).host.toLowerCase() } catch { return true }
+  const host = asText(headers.host).toLowerCase()
+  return Boolean(host) && originHost !== host
+}
+
+function hostOnly(value) {
+  return asText(value).toLowerCase().replace(/:\d+$/, '')
+}
+
+function requestHost(req) {
+  return hostOnly(req && req.headers && req.headers.host)
+}
+
+/** 端口取自请求的 Host 头 —— 这样同一个插件在任意端口上都报得对，不需要写死 52676。 */
+function requestPort(req) {
+  const m = /:(\d+)$/.exec(asText(req && req.headers && req.headers.host))
+  if (!m) return ''
+  const port = Number(m[1])
+  return Number.isFinite(port) && port > 0 && port < 65536 ? String(port) : ''
+}
+
 /** 后台任务的 label 常是多行 shell 命令（含纯环境变量赋值行），折成一行可读文本。 */
 function cleanLabel(raw) {
   const all = asText(raw).split(/\r?\n/).map((line) => line.trim()).filter(Boolean)
@@ -170,7 +300,7 @@ function safe(fn, fallback, errors, label) {
   }
 }
 
-export function apply(ctx) {
+export function apply(ctx, config) {
   const jobsSvc = ctx.get('jobs')
   const agentsSvc = ctx.get('agents')
   const sessionsSvc = ctx.get('sessions')
@@ -1733,10 +1863,245 @@ export function apply(ctx) {
       }), 'in-hand: chat model route')
     }
 
+    // ---- 双入口（远端 / 局域网）--------------------------------------------
+    //
+    // 与 taskwatch-relay 的 /taskwatch/entries、/taskwatch/ticket 同一套语义：
+    // 入口清单说明"现在有哪几条路"，ticket 给一张 60 秒、一次性、用后即焚的通行证。
+    // 差别只有一个：宿主自己不做鉴权，所以兑换后的 Set-Cookie 只是与中继同形的
+    // "换路已完成"标记，不承担授权（授权仍由中继那层负责）。
+    //
+    // 2026-10-21（v1.7.1）：这两条原先**只有中继实现**，宿主没有 —— 页面从宿主加载时
+    // 点「去远端」拿到 405/404，拿不到 url 又每 12 秒重试一次，就是"点了就一直报错"。
+    const settings = config && typeof config === 'object' ? config : {}
+    // 公网地址只从配置来：插件配置项 publicUrl，其次环境变量（与 DSH_TASKWATCH_ROOTS
+    // 同一习惯）。没有配置就只报局域网入口 —— 代码里绝不写死任何域名。
+    const publicUrl = normalizePublicUrl(
+      asText(settings.publicUrl) || asText(process.env.DSH_TASKWATCH_PUBLIC_URL),
+    )
+    // 局域网入口可以指到别处（通常是有令牌门的中继）。没配就沿用自动探测内网 IP。
+    const lanUrl = normalizeLanUrl(asText(settings.lanUrl) || asText(process.env.DSH_TASKWATCH_LAN_URL))
+    // 票据 v2：密钥解析顺序在 lib/ticket.js 里与中继保持一致；文件权限也在那里收紧。
+    // **按需初始化**（第一次签发/兑换时才解析）—— 只读监控、不换路的会话不该在启动时
+    // 就去碰用户主目录，测试里也能避免无意写入真实 ~/.dsh。
+    // 注意日志只写来源与路径，绝不打印密钥本身。
+    let ticketGate = null
+    function tickets() {
+      if (ticketGate) return ticketGate
+      const resolved = loadTicketSecret()
+      if (resolved.source === 'generated') {
+        console.log('dsh-in-hand: 已生成跨进程票据密钥 ' + resolved.file
+          + '（权限：' + resolved.permission + '）')
+      } else if (resolved.source === 'memory') {
+        console.error('dsh-in-hand: 票据密钥无法写入 ' + resolved.file
+          + '，只能在本进程内使用（跨进程互认不可用）')
+      }
+      ticketGate = createTicketGate({
+        secret: resolved.secret,
+        // 老格式随机票的向后兼容仍然走这个进程内 Map。
+        store: createTicketStore(),
+      })
+      return ticketGate
+    }
+    const routeJson = (res, status, obj) =>
+      send(res, status, 'application/json; charset=utf-8', JSON.stringify(obj))
+
+    /** 入口清单。current 用布尔标在每条上（新契约）；同时保留中继的
+     *  remote / lan / current 字段，好让同一份 page.html 在两种外壳下都能读。 */
+    function entryList(req) {
+      const host = requestHost(req)
+      const port = requestPort(req)
+      const remoteHost = publicUrl ? hostOnly(new URL(publicUrl).host) : ''
+      const isRemote = Boolean(remoteHost) && host === remoteHost
+      const entries = []
+      let lanUrls = []
+      if (publicUrl) {
+        entries.push({
+          kind: 'remote',
+          label: '远端（公网）',
+          url: publicUrl + '/taskwatch',
+          current: isRemote,
+        })
+      }
+      if (lanUrl) {
+        // 配了 lanUrl 就不再探测内网 IP：那通常是中继的局域网入口，比自动探测更准，
+        // 也更可能是"有鉴权"的那一条（插件自己的路由没有令牌门）。
+        lanUrls = [lanUrl + '/taskwatch']
+        entries.push({
+          kind: 'lan',
+          label: '局域网 · 中继',
+          url: lanUrls[0],
+          current: !isRemote,
+        })
+      } else {
+        const lan = lanAddresses()
+        lanUrls = lan.map((a) => 'http://' + a.ip + (port ? ':' + port : '') + '/taskwatch')
+        const lanCurrent = lan.findIndex((a) => a.ip === host)
+        lanUrls.forEach((url, i) => {
+          // 本机回环访问时没有哪条局域网地址"等于"当前地址，但它们连的是同一个服务，
+          // 所以把第一条标成当前 —— 只影响胶囊文案，不影响任何跳转。
+          const current = !isRemote && (lanCurrent >= 0 ? i === lanCurrent : i === 0)
+          entries.push({ kind: 'lan', label: '局域网 · ' + lan[i].ip, url, current })
+        })
+      }
+      return { entries, remote: publicUrl, lan: lanUrls, current: isRemote ? 'remote' : 'lan' }
+    }
+
+    // ticket 的请求体上限比对话接口还小：这里只该有一个 {"to":"remote"}。
+    function readTicketBody(req) {
+      return new Promise((resolve, reject) => {
+        let size = 0
+        const chunks = []
+        req.on('data', (chunk) => {
+          size += chunk.length
+          if (size > 1024) {
+            reject(new Error('请求体过大'))
+            try { req.destroy() } catch { /* 已断开 */ }
+            return
+          }
+          chunks.push(chunk)
+        })
+        req.on('end', () => {
+          try {
+            const raw = Buffer.concat(chunks).toString('utf8')
+            const parsed = raw ? JSON.parse(raw) : {}
+            resolve(parsed && typeof parsed === 'object' ? parsed : {})
+          } catch (e) { reject(e) }
+        })
+        req.on('error', reject)
+      })
+    }
+
+    ctx.effect(() => webServer.register({
+      kind: 'exact',
+      path: '/taskwatch/entries',
+      handler: (req, res) => {
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+          res.setHeader('allow', 'GET, HEAD')
+          routeJson(res, 405, { ok: false, code: 'method-not-allowed', error: '只接受 GET' })
+          return
+        }
+        const view = entryList(req)
+        routeJson(res, 200, {
+          ok: true,
+          entries: view.entries,
+          // 中继那套字段（页面旧逻辑仍读它们；新逻辑读 entries）
+          remote: view.remote,
+          lan: view.lan,
+          current: view.current,
+        })
+      },
+    }), 'in-hand: entries route')
+
+    // 换路票据：写路由，沿用中继写路由的门禁 —— POST + application/json + 同源。
+    // 宿主不校验令牌（和中继的分工），但绝不能让任意网页用表单 POST 触发一次跳转。
+    ctx.effect(() => webServer.register({
+      kind: 'exact',
+      path: '/taskwatch/ticket',
+      handler: async (req, res) => {
+        if (req.method !== 'POST') {
+          res.setHeader('allow', 'POST')
+          routeJson(res, 405, { ok: false, code: 'method-not-allowed', error: '只接受 POST' })
+          return
+        }
+        if (isCrossSite(req)) {
+          routeJson(res, 403, { ok: false, code: 'cross-site', error: '禁止跨站触发换路' })
+          return
+        }
+        const type = String(req.headers['content-type'] || '').split(';', 1)[0].trim().toLowerCase()
+        if (type !== 'application/json') {
+          routeJson(res, 415, { ok: false, code: 'unsupported-media-type', error: '请求必须使用 application/json' })
+          return
+        }
+        let want = 'lan'
+        try {
+          const body = await readTicketBody(req)
+          if (asText(body.to) === 'remote') want = 'remote'
+        } catch {
+          routeJson(res, 400, { ok: false, code: 'bad-request', error: '请求体不合法' })
+          return
+        }
+        if (want === 'remote') {
+          if (!publicUrl) {
+            routeJson(res, 409, {
+              ok: false,
+              code: 'no-public-entry',
+              error: '还没有配置公网入口（插件配置项 publicUrl），这里只能走局域网',
+            })
+            return
+          }
+          const ticket = tickets().mint()
+          routeJson(res, 200, {
+            ok: true,
+            to: 'remote',
+            url: publicUrl + '/taskwatch?t=' + ticket,
+            expiresInMs: TICKET_TTL_MS,
+          })
+          return
+        }
+        if (lanUrl) {
+          // 指到中继的局域网入口：票据是同一套 v2 HMAC，中继能直接验签兑换。
+          routeJson(res, 200, {
+            ok: true,
+            to: 'lan',
+            address: hostOnly(new URL(lanUrl).host),
+            url: lanUrl + '/taskwatch?t=' + tickets().mint(),
+            expiresInMs: TICKET_TTL_MS,
+          })
+          return
+        }
+        const lan = lanAddresses()
+        if (!lan.length) {
+          routeJson(res, 409, {
+            ok: false,
+            code: 'no-lan-entry',
+            error: '没有局域网地址（网卡没连上 Wi-Fi？）',
+          })
+          return
+        }
+        // 和中继一样优先挑与请求方同网段的那条，否则第一条。
+        const peer = String((req.socket && req.socket.remoteAddress) || '').replace(/^::ffff:/, '')
+        const net = (ip) => ip.split('.').slice(0, 3).join('.')
+        const pick = lan.find((a) => net(a.ip) === net(peer)) || lan[0]
+        const port = requestPort(req)
+        const ticket = tickets().mint()
+        routeJson(res, 200, {
+          ok: true,
+          to: 'lan',
+          address: pick.ip,
+          iface: pick.iface,
+          url: 'http://' + pick.ip + (port ? ':' + port : '') + '/taskwatch?t=' + ticket,
+          expiresInMs: TICKET_TTL_MS,
+        })
+      },
+    }), 'in-hand: ticket route')
+
+    // 页面外壳。带 ?t= 时先兑换票据：命中 → 302 到 /taskwatch 并种一张换路标记 cookie
+    // （与中继同形）；未知/过期 → 401，和中继在换路凭据无效时的选择保持一致。
+    // v1.7.2：v2 票靠签名 + 60 秒时效 + 进程内 nonce 去重；老格式仍走 Map（用后即焚）。
     ctx.effect(() => webServer.register({
       kind: 'exact',
       path: '/taskwatch',
-      handler: (req, res) => send(res, 200, 'text/html; charset=utf-8', readPage()),
+      handler: (req, res) => {
+        let ticket = ''
+        try { ticket = new URL(req.url || '/', 'http://127.0.0.1').searchParams.get('t') || '' } catch { ticket = '' }
+        if (ticket) {
+          if (!tickets().redeem(ticket)) {
+            send(res, 401, 'text/plain; charset=utf-8', '换路凭据无效或已过期，请再点一次切换。\n')
+            return
+          }
+          try {
+            res.writeHead(302, {
+              location: '/taskwatch',
+              // 宿主不鉴权，这张 cookie 只是"换路已完成"的标记，不承担授权。
+              'set-cookie': 'tw-route=remote; Path=/taskwatch; HttpOnly; SameSite=Lax; Max-Age=2592000',
+              'cache-control': 'no-store',
+            })
+            res.end()
+          } catch { /* 已断开 */ }
+          return
+        }
+        send(res, 200, 'text/html; charset=utf-8', readPage())
+      },
     }), 'in-hand: page route')
 
     ctx.effect(() => webServer.register({

package/lib/page.html

@@ -573,6 +573,20 @@ main{
 
 .note{font-size:var(--fs-2);color:var(--faint);text-align:center;padding:var(--sp-2) var(--sp-4)}
 
+/* 双入口的静态降级说明（2026-10-21，v1.7.1）。
+   页面由插件宿主提供、宿主没有中继的换路接口时，这里只留一句说明 + 一个手动回跳链接；
+   链接的 padding/margin 是让 44px 的命中区不把这一行撑高（视觉仍是一行）。 */
+.route-note{
+  margin:var(--sp-2) 0;padding:var(--sp-2) var(--sp-3);text-align:left;line-height:1.65;
+  color:var(--faint);font-size:var(--fs-2);background:color-mix(in srgb,currentColor 6%,transparent);
+  border:1px solid color-mix(in srgb,currentColor 16%,transparent);
+  border-radius:var(--dsw-radius-sm);overflow-wrap:anywhere;
+}
+.route-note a{
+  color:var(--accent);text-decoration:underline;text-underline-offset:2px;
+  display:inline-block;padding:12px 2px;margin:-12px 2px;
+}
+
 /* ── 输入区 ─────────────────────────────────────────────────────────── */
 footer{
   flex:0 0 auto;background:var(--panel);border-top:1px solid var(--line);
@@ -3436,6 +3450,12 @@ function bindSheetClose(){
   for (var i = 0; i < xs.length; i++) xs[i].addEventListener('click', closeSheet)
 }
 
+// 双入口的静态降级说明由页面末尾那段独立脚本提供（window.twRouteNote）：
+// 只在「宿主没有中继换路接口」时返回一行，其余时候是空串。
+function routeNote(){
+  try { return (window.twRouteNote && window.twRouteNote()) || '' } catch (e) { return '' }
+}
+
 function openCapability(kind){
   var title = kind === 'plugins' ? '插件' : '自动化'
   var h = sheetHead(title)
@@ -3465,7 +3485,7 @@ async function openSessions(){
   catch (e) { openSheet(sheetHead('会话') + '<div class="note">读取失败：' + esc(e.message) + '</div>'); bindSheetClose(); return }
   if (d && d.error) { openSheet(sheetHead('会话') + '<div class="note">读取失败：' + esc(d.error) + '</div>'); bindSheetClose(); return }
   S.sessions = (d && d.sessions) || []
-  var h = sheetHead('会话', S.sessions.length)
+  var h = sheetHead('会话', S.sessions.length) + routeNote()
   h += '<label class="sheet-search"><svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="10.8" cy="10.8" r="6.4"></circle><path d="m16 16 4.2 4.2"></path></svg><input id="sessionSearch" type="search" placeholder="搜索会话或工作区" autocomplete="off" aria-label="搜索会话或工作区"></label>'
   // 显示设置：字号三档 + 只看对话。放在会话列表上方，打开「对话」就能看到。
   var fcur = document.documentElement.getAttribute('data-font') || 'medium'
@@ -3640,15 +3660,15 @@ function kv(k, v){
 async function openStatus(){
   var stBtn = document.getElementById('status')
   if (stBtn) stBtn.setAttribute('aria-expanded', 'true')
-  openSheet(sheetHead('任务详情') + '<div class="note">读取中…</div>')
+  openSheet(sheetHead('任务详情') + routeNote() + '<div class="note">读取中…</div>')
   var d = lastData
   if (!d || d.error) {
     try { d = await (await fetch('/taskwatch/data', { cache:'no-cache' })).json() } catch (e) { d = null }
   }
-  if (!d) { openSheet(sheetHead('任务详情') + '<div class="note">读取失败</div>'); bindSheetClose(); return }
-  if (d.error) { openSheet(sheetHead('任务详情') + '<div class="note">读取失败：' + esc(d.error) + '</div>'); bindSheetClose(); return }
+  if (!d) { openSheet(sheetHead('任务详情') + routeNote() + '<div class="note">读取失败</div>'); bindSheetClose(); return }
+  if (d.error) { openSheet(sheetHead('任务详情') + routeNote() + '<div class="note">读取失败：' + esc(d.error) + '</div>'); bindSheetClose(); return }
   var t = d.totals || {}
-  var h = sheetHead('任务详情') + '<h3>当前会话</h3>'
+  var h = sheetHead('任务详情') + routeNote() + '<h3>当前会话</h3>'
   h += kv('会话', S.title || shortId(S.sessionId) || '未选择')
   h += kv('会话 ID', S.sessionId || '未选择')
   h += kv('工作区', S.workspace || '默认工作区')
@@ -4511,12 +4531,24 @@ if ('serviceWorker' in navigator) {
 (function () {
   try {
     var PREF_KEY = 'tw-route-pref'
+    var REMOTE_KEY = 'tw-remote-url'
     var ORIGIN = 'unknown'
     var REMOTE = ''
     var LAN = []
     var failed = false
     var upstreamOk = true
     var busy = false
+    // 2026-10-21（v1.7.1）：静态降级。宿主没有中继的 ticket / entries 接口时
+    // （拿到的就是 404 / 405），**永远不再重试**，也不弹错 —— 只是把胶囊按
+    // 「只有一个入口」隐藏，并在设置 / 详情里留一行说明与一个手动回跳链接。
+    var DEGRADED = false
+    var probeOff = false          // 宿主没有上游体检：不知道 ≠ 失败，关掉探测别每 12 秒一个 404
+    var timer = 0                  // 轮询句柄；降级 / 探测不可用时必须清掉
+    var failAt = 0                 // 换路失败后的冷却起点，防止每次轮询都重试同一次失败
+    var toastMsg = ''
+    var toastAt = 0
+    var TOAST_COOLDOWN = 30 * 1000
+    var RETRY_COOLDOWN = 30 * 1000
 
     /* ROUTE-LOGIC-BEGIN */
     function decideRoute(c) {
@@ -4536,6 +4568,102 @@ if ('serviceWorker' in navigator) {
     }
     function setPref(v) { try { localStorage.setItem(PREF_KEY, v) } catch (e) {} }
 
+    function readStore(key) { try { return localStorage.getItem(key) || '' } catch (e) { return '' } }
+    function writeStore(key, value) { try { localStorage.setItem(key, value) } catch (e) {} }
+
+    /** 上次成功切换 / 打开过的远端地址。只认 http(s)，避免 localStorage 被第三方
+     *  写进 javascript: 一类的东西后，这个链接变成一个可点的执行入口。 */
+    function rememberedRemote() {
+      var value = readStore(REMOTE_KEY)
+      return /^https?:\/\//i.test(value) ? value : ''
+    }
+    function rememberRemote(url) {
+      if (!url) return
+      var base = String(url).split('?')[0]
+      if (/^https?:\/\//i.test(base)) writeStore(REMOTE_KEY, base)
+    }
+
+    /** 其它错误的提示：同一句 30 秒内只弹一次（404/405 的降级路径不弹）。 */
+    function toast(message) {
+      if (!message) return
+      var now = Date.now()
+      if (message === toastMsg && now - toastAt < TOAST_COOLDOWN) return
+      toastMsg = message
+      toastAt = now
+      var el = document.getElementById('tw-route-toast')
+      if (!el) {
+        el = document.createElement('div')
+        el.id = 'tw-route-toast'
+        el.setAttribute('role', 'status')
+        el.setAttribute('aria-live', 'polite')
+        document.body.appendChild(el)
+      }
+      el.textContent = message
+      el.className = 'on'
+      clearTimeout(el._hide)
+      el._hide = setTimeout(function () { el.className = '' }, 3200)
+    }
+
+    function stopTimer() {
+      if (timer) { clearInterval(timer); timer = 0 }
+    }
+    function startTimer() {
+      if (timer || DEGRADED || probeOff) return
+      timer = setInterval(function () { apply(); probe() }, 12000)
+    }
+
+    /** 降级：宿主没有换路接口。清掉轮询、隐藏胶囊、不报错。 */
+    function degrade() {
+      if (DEGRADED) return
+      DEGRADED = true
+      stopTimer()
+      ORIGIN = 'unknown'
+      apply()
+    }
+
+    function isGone(status) { return status === 404 || status === 405 }
+
+    /** 兼容两种 entries 形状：中继的 {remote, lan, current} 与新契约的
+     *  {entries:[{kind, label, url, current}]}。同一份页面在中继和宿主下都能跑。 */
+    function parseEntries(j) {
+      if (!j || j.ok !== true) return false
+      var list = Array.isArray(j.entries) ? j.entries : null
+      if (list) {
+        var rem = ''
+        var lan = []
+        var current = ''
+        for (var i = 0; i < list.length; i++) {
+          var e = list[i]
+          if (!e || typeof e.url !== 'string' || !/^https?:\/\//i.test(e.url)) continue
+          if (e.kind === 'remote') { if (!rem) rem = e.url }
+          else if (e.kind === 'lan') { if (lan.indexOf(e.url) < 0) lan.push(e.url) }
+          else continue
+          if (e.current === true) current = e.kind
+        }
+        REMOTE = rem
+        LAN = lan
+        ORIGIN = current || (lan.length ? 'lan' : (rem ? 'remote' : 'unknown'))
+      } else {
+        if (j.current !== 'lan' && j.current !== 'remote') return false
+        ORIGIN = j.current
+        REMOTE = typeof j.remote === 'string' ? j.remote : ''
+        LAN = Array.isArray(j.lan) ? j.lan.slice() : []
+      }
+      if (ORIGIN === 'remote') rememberRemote(location.origin + '/taskwatch')
+      return true
+    }
+
+    /** 降级态在设置 / 详情里的一行说明。宿主页面没有中继接口这件事本身不是错误，
+     *  所以这里只陈述事实，并把「上次成功用过的远端地址」留成手动入口。 */
+    function noteHtml() {
+      if (!DEGRADED) return ''
+      var last = rememberedRemote()
+      var text = '当前页面由插件宿主提供，远端切换需要中继接口'
+      if (last) text += '；也可直接打开 <a href="' + esc(last) + '">' + esc(last) + '</a>'
+      return '<div class="note route-note">' + text + '</div>'
+    }
+    window.twRouteNote = noteHtml
+
     function mount() {
       // 2026-10-21：胶囊必须待在**标题行**里（标题与连接三点之间）。
       // 旧写法是 append 到 header 末尾、再靠 margin-left:auto 靠右，它于是成了
@@ -4580,6 +4708,7 @@ if ('serviceWorker' in navigator) {
 
     function apply() {
       var el = mount()
+      if (DEGRADED) { el.style.display = 'none'; el.setAttribute('aria-hidden', 'true'); return }
       var text = label()
       if (!text) { el.style.display = 'none'; el.setAttribute('aria-hidden', 'true'); return }
       el.textContent = text
@@ -4591,22 +4720,56 @@ if ('serviceWorker' in navigator) {
         hasLan: LAN.length > 0, hasRemote: !!REMOTE,
       })
       if (decision === 'stay' || busy) return
+      // 刚失败过就先停 30 秒：轮询每 12 秒一次，不设冷却就变成"点一次、失败、每 12 秒重试"。
+      if (Date.now() - failAt < RETRY_COOLDOWN) return
       busy = true
       fetch('/taskwatch/ticket', {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ to: decision === 'toLan' ? 'lan' : 'remote' }),
-      }).then(function (r) { return r.json() }).then(function (j) {
-        if (j && j.ok && j.url) location.href = j.url
-        else busy = false
-      }).catch(function () { busy = false })
+      }).then(function (r) {
+        // 宿主没有换路接口（405）或这条路由不存在（404）：静态降级，绝不重试。
+        if (isGone(r.status)) { degrade(); return null }
+        if (!r.ok) throw new Error('HTTP ' + r.status)
+        return r.json()
+      }).then(function (j) {
+        if (j === null) { busy = false; return }
+        if (j && j.ok && j.url) {
+          if (decision === 'toRemote') rememberRemote(j.url)
+          location.href = j.url
+          return
+        }
+        busy = false
+        failAt = Date.now()
+        toast((j && j.error) || '无法切换连接方式')
+      }).catch(function (e) {
+        busy = false
+        failAt = Date.now()
+        toast('切换连接方式失败：' + ((e && e.message) || '网络错误'))
+      })
     }
 
     function probe() {
+      if (DEGRADED || probeOff) return
       fetch('/taskwatch/upstream-health', { cache: 'no-store' })
-        .then(function (r) { return r.json() })
-        .then(function (j) { failed = false; upstreamOk = !!(j && j.ok); apply() })
-        .catch(function () { failed = true; apply() })
+        .then(function (r) {
+          // 404 / 405 = 这个外壳没有上游体检（插件宿主）。拿它当"这条路断了"会误触发
+          // 一次到远端的切换，所以只关掉探测，不改失败判据。
+          if (isGone(r.status)) { probeOff = true; stopTimer(); return null }
+          if (!r.ok) throw new Error('HTTP ' + r.status)
+          return r.json()
+        })
+        .then(function (j) {
+          if (j === null) return
+          failed = false
+          upstreamOk = !!(j && j.ok)
+          apply()
+        })
+        .catch(function (e) {
+          failed = true
+          apply()
+          toast('状态检查失败：' + ((e && e.message) || '网络错误'))
+        })
     }
 
     // 样式随手挂上，不依赖页面里已有的 class（两份外壳的样式表可能不同）
@@ -4624,20 +4787,35 @@ if ('serviceWorker' in navigator) {
       + 'border:1px solid color-mix(in srgb,currentColor 24%,transparent);cursor:pointer;white-space:nowrap}'
       + '#tw-route-pill[style*="inline-flex"]{display:inline-flex!important}'
       + '#tw-route-pill:active{transform:translateY(1px)}'
+      // 换路失败的一次性提示（同一错误 30 秒内不重复弹）。同样只用 currentColor 混合，
+      // 明暗两套都能读；max-width 留出两侧 12px，390 宽下不会出现横向滚动。
+      + '#tw-route-toast{position:fixed;left:50%;bottom:calc(96px + var(--safe-b,0px));'
+      + 'transform:translateX(-50%);z-index:90;max-width:calc(100vw - 24px);box-sizing:border-box;'
+      + 'padding:10px 14px;border-radius:12px;opacity:0;pointer-events:none;transition:opacity .18s;'
+      + 'font:600 12.5px/1.45 -apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC",system-ui,sans-serif;'
+      + 'color:inherit;background:color-mix(in srgb,currentColor 12%,transparent);'
+      + 'border:1px solid color-mix(in srgb,currentColor 22%,transparent);overflow-wrap:anywhere}'
+      + '#tw-route-toast.on{opacity:1}'
+      + '@media (prefers-reduced-motion:reduce){#tw-route-toast{transition:none}}'
     document.head.appendChild(css)
 
+    // 入口清单只取一次：404/405 → 静态降级并不再重试；其它错误 → 提示一次后收手。
     fetch('/taskwatch/entries', { cache: 'no-store' })
-      .then(function (r) { return r.ok ? r.json() : null })
+      .then(function (r) {
+        if (isGone(r.status)) { degrade(); return null }
+        if (!r.ok) throw new Error('HTTP ' + r.status)
+        return r.json()
+      })
       .then(function (j) {
-        if (!j || !j.ok || (j.current !== 'lan' && j.current !== 'remote')) return
-        ORIGIN = j.current
-        REMOTE = j.remote || ''
-        LAN = j.lan || []
+        if (j === null) return
+        if (!parseEntries(j)) return
         apply()
         probe()
-        setInterval(function () { apply(); probe() }, 12000)
+        if (!probeOff) startTimer()
+      })
+      .catch(function (e) {
+        toast('入口清单读取失败：' + ((e && e.message) || '网络错误'))
       })
-      .catch(function () { /* 插件侧没有这些路由（例如从 DSH GUI 打开）→ 安静地不显示 */ })
   } catch (e) { console.warn('taskwatch: 双入口切换未启用', e) }
 })()
 </script>

package/lib/ticket.js

@@ -0,0 +1,194 @@
+/**
+ * 跨进程换路票据（v2）：HMAC 签名，让插件宿主与中继互认同一张票。
+ *
+ * 背景（2026-10-21 的真实故障）：宿主签的票打到公网（域名后面是中继）→ 中继只认
+ * 自己进程内 Map 里的随机串 → 401。两边跑在同一台机器、同一个用户下，所以只要
+ * **共用同一个密钥**，就能互相验签而不必共享内存。
+ *
+ * 票格式（两边必须一致）：
+ *   t = 'v2.' + <expMs 十进制> + '.' + <nonce base64url> + '.' + <hmac base64url>
+ *   HMAC = HMAC-SHA256(secret, 'v2|' + expMs + '|' + nonce)
+ *
+ * 安全边界（诚实写清，别把"签名"说成"严格一次性"）：
+ *   - 签名保证票是本机签的、内容没被改；短时效（60 秒 TTL）压缩重放窗口；
+ *   - 跨进程无法共享"已用过"的状态，所以只在**各自进程内**做 best-effort 去重
+ *     （nonce Set + TTL 清理）。两个进程都还没见过的票在窗口内理论上可重放一次。
+ *   - 这不是"严格一次性"。要严格一次性得引入共享存储（Redis/SQLite），代价与
+ *     可用性影响都不小，当前场景（换路跳转，60 秒）不值得。
+ *
+ * 这个模块不碰 HTTP、不碰宿主服务，只做纯函数与密钥解析，方便直接测。
+ */
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+export const TICKET_TTL_MS = 60 * 1000
+/** 允许 60 秒 TTL + 时钟偏差；超过这个跨度的一律当伪造/过期，不给无限期票。 */
+export const TICKET_MAX_AGE_MS = 180 * 1000
+export const TICKET_RE = /^v2\.\d{13}\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{20,}$/
+export const SECRET_MIN_LENGTH = 32
+export const SECRET_FILE_NAME = 'taskwatch-ticket.key'
+
+/** 任何端口上的这个插件/中继都读同一个文件：同一台机器、同一个用户。 */
+export function secretPath(home = homedir()) {
+  return join(home, '.dsh', SECRET_FILE_NAME)
+}
+
+function normalizeSecret(raw) {
+  const text = typeof raw === 'string' ? raw.trim() : ''
+  return text.length >= SECRET_MIN_LENGTH ? text : ''
+}
+
+/** 签发一张 v2 票。nonce 必须是 16 字节（base64url 后 22 字符）。 */
+export function signTicket(secret, { now = Date.now, ttlMs = TICKET_TTL_MS } = {}) {
+  if (!normalizeSecret(secret)) throw new Error('票据密钥至少需要 ' + SECRET_MIN_LENGTH + ' 个字符')
+  const expMs = now() + ttlMs
+  const nonce = randomBytes(16).toString('base64url')
+  const hmac = createHmac('sha256', secret).update('v2|' + expMs + '|' + nonce).digest('base64url')
+  return 'v2.' + expMs + '.' + nonce + '.' + hmac
+}
+
+/** 校验 v2 票。格式不符 / 签名不对 / 过期 / 超出最大跨度 → false（当作"不是本票"）。 */
+export function verifyTicket(secret, ticket, { now = Date.now } = {}) {
+  if (!normalizeSecret(secret) || typeof ticket !== 'string' || !TICKET_RE.test(ticket)) return false
+  const parts = ticket.split('.')
+  const expMs = Number(parts[1])
+  if (!Number.isSafeInteger(expMs)) return false
+  const expected = createHmac('sha256', secret).update('v2|' + expMs + '|' + parts[2]).digest()
+  let given
+  try {
+    given = Buffer.from(parts[3], 'base64url')
+  } catch {
+    return false
+  }
+  // timingSafeEqual 要求等长；长度不同本身就不是本票。
+  if (given.length !== expected.length) return false
+  if (!timingSafeEqual(given, expected)) return false
+  const at = now()
+  if (!(expMs > at)) return false
+  if (expMs - at > TICKET_MAX_AGE_MS) return false
+  return true
+}
+
+export function nonceOf(ticket) {
+  return typeof ticket === 'string' ? String(ticket.split('.')[2] || '') : ''
+}
+
+export function expOf(ticket) {
+  const n = Number(typeof ticket === 'string' ? ticket.split('.')[1] : NaN)
+  return Number.isSafeInteger(n) ? n : 0
+}
+
+/** 进程内 best-effort 去重：记下见过的 nonce，过期就清。不是跨进程的严格一次性。 */
+export function createReplayGuard({ now = Date.now, max = 1024 } = {}) {
+  const seen = new Map()
+  const prune = (at) => {
+    for (const [nonce, exp] of seen) if (exp <= at) seen.delete(nonce)
+  }
+  return {
+    /** 第一次见到返回 false；重复的 nonce 返回 true。 */
+    replayed(nonce, expMs) {
+      const at = now()
+      if (seen.size >= max) prune(at)
+      if (seen.has(nonce)) return true
+      seen.set(nonce, Math.max(expMs || 0, at + 1000))
+      return false
+    },
+    get size() { return seen.size },
+  }
+}
+
+/**
+ * 票据闸门：统一签发 v2、统一兑换。
+ *
+ * redeem 的回落规则是刻意写成"只认格式"的：非 v2 形状（老页面/老票）才走原来的
+ * 进程内 Map；一旦长得像 v2 就只按签名/时效判断，签名不对直接拒绝，**不**回落 ——
+ * 否则伪造一张 `v2.…` 反而比随机串更容易被误放行。
+ */
+export function createTicketGate({ secret, store, now = Date.now, ttlMs = TICKET_TTL_MS, replay } = {}) {
+  const guard = replay || createReplayGuard({ now })
+  return {
+    mint() {
+      return signTicket(secret, { now, ttlMs })
+    },
+    redeem(ticket) {
+      const text = typeof ticket === 'string' ? ticket.trim() : ''
+      if (!text) return false
+      if (TICKET_RE.test(text)) {
+        if (!verifyTicket(secret, text, { now })) return false
+        return !guard.replayed(nonceOf(text), expOf(text))
+      }
+      // 向后兼容：老格式随机票仍只在本进程 Map 里有效。
+      return store ? store.redeem(text) : false
+    },
+    get replaySize() { return guard.size },
+  }
+}
+
+/**
+ * 两边同一套解析顺序：
+ *   1. 环境变量 TASKWATCH_TICKET_SECRET（trim 后至少 32 字符）
+ *   2. <home>/.dsh/taskwatch-ticket.key（UTF-8、trim、至少 32 字符）
+ *   3. 都没有 → 先生成 32 字节随机值写进该文件，**收紧权限**后使用。
+ *
+ * 返回 { secret, source, file, permission }；任何失败都退回内存密钥，
+ * 绝不因为一个密钥文件写不了就让插件/中继启动失败。调用方不得把 secret 打日志。
+ */
+export function loadTicketSecret({
+  env = process.env,
+  home = homedir(),
+  platform = process.platform,
+  fs = { mkdirSync, writeFileSync, readFileSync, chmodSync },
+  run = spawnSync,
+} = {}) {
+  const fromEnv = normalizeSecret(env && env.TASKWATCH_TICKET_SECRET)
+  if (fromEnv) return { secret: fromEnv, source: 'env', file: '', permission: 'n/a' }
+
+  const file = secretPath(home)
+  let existing = ''
+  try {
+    existing = normalizeSecret(fs.readFileSync(file, 'utf8'))
+  } catch { /* 没有文件就走生成 */ }
+  if (existing) return { secret: existing, source: 'file', file, permission: 'existing' }
+
+  const secret = randomBytes(32).toString('base64url')
+  let permission = 'unknown'
+  try {
+    fs.mkdirSync(dirname(file), { recursive: true, mode: 0o700 })
+    // mode 只在创建时生效；已存在的文件由下面的 chmod / icacls 收紧。
+    fs.writeFileSync(file, secret + '\n', { mode: 0o600 })
+    if (platform === 'win32') {
+      // Windows 没有 POSIX 权限位。用 icacls 去掉继承、只给当前用户完全控制。
+      // 这一步失败时文件仍在（用户目录下），但权限状态要如实标成 failed。
+      const user = String((env && (env.USERNAME || env.USER)) || '').trim()
+      if (!user) {
+        permission = 'icacls-no-user'
+      } else {
+        const result = run('icacls', [file, '/inheritance:r', '/grant:r', user + ':F'], {
+          windowsHide: true,
+          timeout: 5000,
+        })
+        permission = result && result.status === 0 ? 'icacls-owner' : 'icacls-failed'
+      }
+    } else {
+      try {
+        fs.chmodSync(file, 0o600)
+        permission = 'chmod-600'
+      } catch {
+        permission = 'chmod-failed'
+      }
+    }
+    return { secret, source: 'generated', file, permission }
+  } catch (error) {
+    // 目录只读 / 磁盘满：仍然能签发与校验（本进程内），只是无法跨进程互认。
+    return {
+      secret,
+      source: 'memory',
+      file,
+      permission: 'write-failed',
+      error: String((error && error.message) || error),
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-in-hand",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "description": "掌上 DSH：DeepSeek Harness 的手机端，不用装 App——会话、实时对话、交付文件、后台任务与待批准。 / DSH in hand: the phone client for DeepSeek Harness with no app to install.",
   "type": "module",
   "main": "lib/index.js",
@@ -33,7 +33,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "check": "node scripts/check-bundle.mjs && node scripts/check-files.mjs && node scripts/check-uploads.mjs && node scripts/check-queue.mjs",
+    "check": "node scripts/check-bundle.mjs && node scripts/check-files.mjs && node scripts/check-uploads.mjs && node scripts/check-queue.mjs && node scripts/check-entries.mjs && node scripts/check-ticket-hmac.mjs",
     "demo": "node scripts/make-demo.mjs",
     "icons": "node scripts/make-icons.mjs"
   },