dsh-mobile-plugin 0.0.0-stage → 0.1.57

package/lib/read-receipt.cjs

@@ -0,0 +1,124 @@
+'use strict';
+
+/**
+ * 「已读回执」台账：手机端读过哪个会话，桌面端据此清掉自己的未读绿点。
+ *
+ * 背景：两端侧边栏的绿点来自**两份互不相干**的状态。
+ *   - 手机端绿点 = 宿主按设备维度维护的完成提醒（lib/mobile/completion.js），
+ *     由 `POST /api/mobile/v1/session/read` 清掉；
+ *   - 桌面端绿点 = 浏览器渲染进程内存里的 `UiSession.completionUnread`
+ *     （@deepseek-ai/dsh-client-ui-session），既不落盘也不过服务端。
+ * 所以手机上点开一个会话，桌面那份完全不知情，绿点照旧。
+ *
+ * 这里补的就是这条缺失的通道：手机端每点开一个会话，宿主除了清自己那份提醒，
+ * 还往本模块记一条 `sessionId → readAt` 水位；插件的客户端半边
+ * （lib/client.js 的 startReadReceiptSync）每 2 秒拉一次 `GET /api/relay/read-receipt`，
+ * 对水位前进过的会话做一次瞬时 `sessions.retain(id, { source: 'mainView' })` +
+ * `release()`，借桌面自己的 `reconcileStatus()` 把 `completionUnread` 摘掉。
+ *
+ * 为什么存 readAt 而不是一个「已读」布尔：冲突策略是 last-write-wins。
+ * 桌面点开 → 客户端半边把该会话 POST 回 `/api/relay/desktop-read` → 宿主清掉
+ * **所有设备**维度上的完成提醒（`clearCompletionForAllDevices`）。而「读完又来一轮」
+ * 必须还能重新亮起来 —— 这一条由 completion.js 的 delete 语义本身保证：条目被清掉后
+ * 重建出来的 `wasRunning` 是 false，历史折叠会拒绝确认，于是只有**之后**真正跑完的
+ * 轮次才会把 completed 重新置真。
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const paths = require('./shared/paths');
+
+/** 单个 sessionId 长度上限；超长的一律丢弃（真实 id 只有十几字节）。 */
+const MAX_ID_LENGTH = 200;
+/** 台账条目数上限：超出时按 readAt 保留最新的，防止文件无限增长。 */
+const MAX_ENTRIES = 512;
+
+/** 台账文件：$DSH_HOME/read-receipts.json（DSH_HOME 在调用时解析，便于测试注入）。 */
+function stateFile() {
+  return path.join(paths.dshHome(), 'read-receipts.json');
+}
+
+/** null = 台账还没写过任何一条；否则 { readAt: { [sessionId]: number } }。 */
+let cached = null;
+let loaded = false;
+
+/**
+ * 归一化台账：只保留「合法的 sessionId → 有限正数 readAt」，并按 readAt 截到 MAX_ENTRIES。
+ * 形状不对返回 null（调用方按「还没有台账」处理，不报错）。
+ */
+function normalizeReceipts(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const entries = [];
+  for (const rawKey of Object.keys(input)) {
+    const value = input[rawKey];
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) continue;
+    const key = rawKey.trim();
+    if (!key || key.length > MAX_ID_LENGTH) continue;
+    entries.push([key, value]);
+  }
+  entries.sort((a, b) => b[1] - a[1]);
+  const out = {};
+  for (const [key, value] of entries.slice(0, MAX_ENTRIES)) out[key] = value;
+  return out;
+}
+
+function load() {
+  if (loaded) return cached;
+  loaded = true;
+  try {
+    const raw = JSON.parse(fs.readFileSync(stateFile(), 'utf8'));
+    const readAt = normalizeReceipts(raw && raw.readAt);
+    if (!readAt) {
+      cached = null;
+      return cached;
+    }
+    cached = { readAt };
+  } catch {
+    // 文件不存在 / 损坏都按「还没有台账」处理：客户端半边这轮就什么都不做。
+    cached = null;
+  }
+  return cached;
+}
+
+/** 当前台账的副本；从未写过时返回 null。 */
+function snapshot() {
+  const value = load();
+  if (!value) return null;
+  return { readAt: { ...value.readAt } };
+}
+
+function persist(readAt) {
+  const file = stateFile();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ readAt }, null, 2), { mode: 0o600 });
+  fs.renameSync(tmp, file);
+  cached = { readAt };
+  loaded = true;
+}
+
+/**
+ * 记一条已读：`sessionId` 在 `now` 被读过。返回 `{ sessionId, readAt, changed }`。
+ *
+ * 水位**只前进不后退**：`now` 不比已记的小就保留原值，`changed` 为 false。
+ * 这样客户端半边可以拿「本地见过的最大 readAt」当游标，重复读同一个会话不会
+ * 反复触发桌面侧的清除动作。
+ */
+function recordRead(sessionId, now = Date.now()) {
+  const id = typeof sessionId === 'string' ? sessionId.trim() : '';
+  if (!id || id.length > MAX_ID_LENGTH) {
+    return { sessionId: id, readAt: 0, changed: false };
+  }
+  const at = Number.isFinite(now) && now > 0 ? now : Date.now();
+  const current = load();
+  const previous = current ? current.readAt[id] : undefined;
+  if (typeof previous === 'number' && previous >= at) {
+    return { sessionId: id, readAt: previous, changed: false };
+  }
+  const next = { ...(current ? current.readAt : {}), [id]: at };
+  const pruned = normalizeReceipts(next);
+  persist(pruned || { [id]: at });
+  return { sessionId: id, readAt: at, changed: true };
+}
+
+module.exports = { stateFile, snapshot, recordRead };

package/lib/reconnect-scheduler.cjs

@@ -0,0 +1,37 @@
+'use strict'
+
+/**
+ * 幂等重连调度器。
+ *
+ * worker 的隧道有两条失败路径：RelayTunnel 的 `onClose` 与 `start()` 的 reject
+ * （见 lib/sidecar-facade-worker.cjs 的 startTunnel）。两条路径都会请求重连，
+ * 如果各自排一个定时器，每次失败就会重连两次，形成重连风暴。
+ *
+ * 这里把「同一个待触发窗口内只保留一个定时器」这一不变量收敛成一个模块，
+ * 以便用毫秒级延迟做真实的行为测试。端到端数连接次数是分不出来的：
+ * 生产里延迟固定 5s，且 startTunnel 开头的 stopTunnel 会吸收重复定时器
+ * 造成的大部分可见差异。
+ */
+function createReconnectScheduler({ delayMs, onFire, setTimer = setTimeout, clearTimer = clearTimeout } = {}) {
+  if (typeof delayMs !== 'number' || !(delayMs >= 0)) throw new Error('invalid delayMs')
+  if (typeof onFire !== 'function') throw new Error('invalid onFire')
+  let timer = null
+  return {
+    /** 排程一次重连；已有待触发的定时器时返回 false，表示被幂等吸收。 */
+    schedule() {
+      if (timer !== null) return false
+      timer = setTimer(() => { timer = null; onFire() }, delayMs)
+      return true
+    },
+    /** 取消待触发的重连（显式停止隧道时调用）。 */
+    cancel() {
+      if (timer === null) return
+      clearTimer(timer)
+      timer = null
+    },
+    /** 是否已有待触发的重连。 */
+    pending() { return timer !== null },
+  }
+}
+
+module.exports = { createReconnectScheduler }

package/lib/relay/core.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const sharedToken = require('../shared/dshtoken');
+const paths = require('../shared/paths');
+
+const STATE_FILE = paths.relayStateFile();
+/** 浏览器/局域网代理签发的 `dsh_lan` Cookie 有效期（30 天）。 */
+const MOBILE_TOKEN_TTL_SEC = 30 * 24 * 3600;
+/**
+ * App 侧长期 bearer token 的有效期（1 年）。
+ *
+ * App 没有续签流程，这个 token 只能靠宿主轮换 `lanSecret`（`/api/relay/revoke-all`）
+ * 整体作废；单设备吊销改由 `dshc_` 设备凭据承担（见 `lib/mobile/auth.js`）。
+ * 旧实现把它写成 10 年，且与 Cookie 的 30 天完全脱钩，`MOBILE_TOKEN_TTL_SEC`
+ * 这个常量实际上从未被任何人使用过。
+ */
+const MOBILE_BEARER_TTL_SEC = 365 * 24 * 3600;
+
+function genInstanceId() { return crypto.randomBytes(4).toString('hex'); }
+function genPairingCode() { return String(crypto.randomInt(0, 1000000)).padStart(6, '0'); }
+function defaultState() {
+  return {
+    instanceId: genInstanceId(), pairingCode: genPairingCode(), relayUrl: '', name: os.hostname(),
+    lanEnabled: true, lanPort: 18787, lanSecret: crypto.randomBytes(32).toString('hex'), enabled: false,
+    // 中转侧 TUNNEL_REGISTER_SECRET 的对偶值。为空时隧道注册会被中转以
+    // close(1008, 'bad registration secret') 拒掉（除非中转根本没开校验）。
+    registerSecret: '',
+    // 首次接入引导走完没有。**刻意不进 RemoteControlSettingsSchema**：它不是一项
+    // 「远程控制设置」，改它不该触发 sidecar 重配（那条链上每加一个字段都要同步改
+    // schema、worker 的 allowed 数组与 buildConfig，漏一处就抛 unknown field）。
+    // 它只是面板用来决定「打开先走引导还是直接进主页」的一个落盘标记，
+    // `settings.update()` 的 Object.assign 不会碰它（schema 里没这个键）。
+    onboarded: false,
+  };
+}
+function loadState() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));
+    return { ...defaultState(), ...raw };
+  } catch {
+    const state = defaultState();
+    saveState(state);
+    return state;
+  }
+}
+function saveState(state) {
+  fs.mkdirSync(path.dirname(STATE_FILE), { recursive: true });
+  const tmp = `${STATE_FILE}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+  fs.renameSync(tmp, STATE_FILE);
+}
+/**
+ * 中转地址 → 隧道 WebSocket 地址。
+ *
+ * 旧实现只是把 `http` 前缀替换成 `ws`，因此 `example.com:8700`、`//relay.example`
+ * 这类缺协议的输入会生成一个 `new WebSocket()` 直接拒绝的字符串，错误要等到
+ * 隧道连接阶段才以 `tunnel.state='error'` 的形式浮现。这里提前抛错，让
+ * `/api/relay/config` 能在保存时就给出明确反馈。
+ */
+function tunnelWsUrl(relayUrl) {
+  const raw = String(relayUrl || '').trim().replace(/\/+$/, '');
+  if (!/^https?:\/\/[^\s/]+/i.test(raw)) {
+    throw new Error(`无效的中转地址「${relayUrl || ''}」：必须以 http:// 或 https:// 开头`);
+  }
+  return `${raw.replace(/^http/i, 'ws')}/tunnel`;
+}
+function signLanToken(secret, instanceId, ttlSec = MOBILE_TOKEN_TTL_SEC) { return sharedToken.signLanToken(secret, instanceId, ttlSec); }
+function verifyLanToken(secret, token, instanceId) { return sharedToken.verifyLanToken(secret, token, instanceId); }
+
+module.exports = {
+  STATE_FILE, MOBILE_TOKEN_TTL_SEC, MOBILE_BEARER_TTL_SEC, loadState, saveState, genInstanceId, genPairingCode,
+  tunnelWsUrl, signLanToken, verifyLanToken,
+};

package/lib/relay/lan-network.cjs

@@ -0,0 +1,85 @@
+'use strict'
+
+const os = require('node:os')
+
+// Only advertise RFC1918 addresses. This intentionally excludes VPN/CGNAT,
+// link-local and benchmarking/test ranges (notably 198.18.0.0/15).
+function ipv4Number(address) {
+  const parts = String(address).split('.').map(Number)
+  if (parts.length !== 4 || parts.some((part, i) => !Number.isInteger(part) || part < 0 || part > 255 || String(part) !== String(address).split('.')[i])) return null
+  return (((parts[0] * 256 + parts[1]) * 256 + parts[2]) * 256 + parts[3]) >>> 0
+}
+function inRange(value, start, end) { return value >= start && value <= end }
+function isPrivateLanAddress(address) {
+  const value = ipv4Number(address)
+  if (value === null) return false
+  return inRange(value, 0x0a000000, 0x0affffff) // 10/8
+    || inRange(value, 0xac100000, 0xac1fffff) // 172.16/12
+    || inRange(value, 0xc0a80000, 0xc0a8ffff) // 192.168/16
+}
+function isVpnInterface(name) {
+  return /^(?:utun|tun|tap|ppp|ipsec|wg|tailscale|vpn|zt|nebula)/i.test(String(name))
+}
+
+// Interfaces that routinely hold an RFC1918 address but are NOT reachable from a
+// phone sitting on the physical LAN: container bridges, hypervisor host-only
+// networks and overlay VPNs. Advertising them used to cost the app one 1.2s
+// probe per dead candidate before it reached the real address.
+//
+// Container/WAF bridges are the easy ones to miss because they are named after
+// the product, not after Docker: `safeline-ce` (SafeLine WAF) sits on
+// 192.168.0.1/24 and used to be the ONLY candidate on a host whose physical NIC
+// carries public addresses, so the app was told to dial a WAF container. Same
+// for `cni0` / `lxcbr0` / `podman0` / `flannel.1` / `cali<hash>` / `kube-ipvs0`.
+//
+// Deliberately NOT filtered: macOS `bridge100` / `ap*`, because Internet Sharing
+// hands out a genuine LAN on those interfaces.
+const VIRTUAL_INTERFACE = /^(?:docker|br-|veth|virbr|virbr-|vmnet|vboxnet|vbox|vnic|vEthernet|Hyper-V|Default Switch|zt|nebula|ham\d|llw\d|awdl\d|safeline|cni|lxcbr|podman|flannel|cali|kube)/i
+function isVirtualInterface(name) { return VIRTUAL_INTERFACE.test(String(name)) }
+
+// Rank candidates so the address most likely to face the phone goes first. The
+// relay and the app both probe in order, so ordering is a latency optimisation,
+// not a correctness requirement.
+function interfaceRank(name) {
+  const n = String(name)
+  if (/^(?:eth\d+$|enp\ds?\d*$|ens\d|eno\d|enx)/i.test(n)) return 0 // Linux ethernet
+  if (/^en\d+$/i.test(n)) return 1 // macOS: en0 (Wi-Fi) / enN (thunderbolt ethernet)
+  if (/^(?:wl|wlan)/i.test(n)) return 2 // Linux Wi-Fi
+  return 3
+}
+
+// Structured view of the usable LAN endpoints. The relay's `normalizeLanMetadata`
+// and the app's `candidateUrls()` both accept this shape, so callers that want
+// interface metadata (for diagnostics or smarter ordering) should prefer it.
+function lanInterfaces(port, interfaces = os.networkInterfaces()) {
+  const found = []
+  let order = 0
+  for (const [name, entries] of Object.entries(interfaces || {})) {
+    const current = order++
+    if (isVpnInterface(name) || isVirtualInterface(name)) continue
+    for (const entry of entries || []) {
+      if (!entry || entry.internal) continue
+      if (entry.family !== 'IPv4' && entry.family !== 4) continue
+      if (!isPrivateLanAddress(entry.address)) continue
+      found.push({ name, address: entry.address, order: current })
+    }
+  }
+  const seen = new Set()
+  return found
+    .sort((a, b) => interfaceRank(a.name) - interfaceRank(b.name) || a.order - b.order)
+    .filter((item) => {
+      if (seen.has(item.address)) return false
+      seen.add(item.address)
+      return true
+    })
+    .slice(0, 16)
+    .map((item) => ({ url: `http://${item.address}:${port}`, interface: item.name, family: 'IPv4', address: item.address }))
+}
+function lanUrls(port, interfaces = os.networkInterfaces()) {
+  return lanInterfaces(port, interfaces).map((candidate) => candidate.url)
+}
+function lanCandidates(port, interfaces = os.networkInterfaces()) {
+  return lanInterfaces(port, interfaces)
+}
+
+module.exports = { ipv4Number, isPrivateLanAddress, isVpnInterface, isVirtualInterface, interfaceRank, lanInterfaces, lanUrls, lanCandidates }