dsh-mobile-plugin 0.5.21 → 0.5.23

package/lib/tailcat/ingress.cjs

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * 隧道和插件之间的那道小门：在回环上占一个固定的端口，进来的每条连接都转给「当前」的
+ * 局域网端口。
+ *
+ * 为什么中间要隔这一层：局域网端口是会变的（首选 18787 被占就让内核另分一个，重启后还
+ * 可能再变），而隧道那边把它当固定地址写死。直接告诉助手那个会变的端口，端口一变隧道
+ * 就整段指向一个没人听的地方，而手机侧只会看到「连上就断」。隔一层之后助手只认这个
+ * 回环端口，端口怎么变都由这里在每次连接时临时决定。
+ *
+ * 只监听 127.0.0.1，不接受任何外部来源；隧道进来的是本进程内的连接。
+ */
+
+const net = require('node:net');
+
+/**
+ * @param {object} options
+ * @param {() => number} options.targetPort 当前局域网端口（每次连接现读，允许变化）
+ * @param {(message: string) => void} [options.log]
+ */
+function createLoopbackIngress(options) {
+  const log = options.log || (() => {});
+  let server = null;
+  let port = 0;
+  const live = new Set();
+
+  function pipe(socket) {
+    const target = Number(options.targetPort());
+    if (!Number.isInteger(target) || target <= 0) {
+      socket.destroy();
+      return;
+    }
+    const upstream = net.connect({ host: '127.0.0.1', port: target });
+    live.add(socket);
+    live.add(upstream);
+    const drop = () => {
+      live.delete(socket);
+      live.delete(upstream);
+      socket.destroy();
+      upstream.destroy();
+    };
+    socket.on('error', drop);
+    upstream.on('error', drop);
+    socket.on('close', drop);
+    upstream.on('close', drop);
+    socket.pipe(upstream);
+    upstream.pipe(socket);
+  }
+
+  let starting = null;
+
+  return {
+    /**
+     * 把回环端口开起来，拿到端口之后才算成；失败回 0。
+     *
+     * **必须是异步的**：`listen(0)` 之后 `address()` 要等 `listening` 事件才有值，同步读回来
+     * 恒是 null，端口就成了 0——隧道那边于是拿到一个「没有地址」的配置，整条通道静默不可用。
+     */
+    start() {
+      if (starting) return starting;
+      server = net.createServer(pipe);
+      server.on('error', error => {
+        log(`隧道入口没有开起来：${error && error.message ? error.message : error}`);
+      });
+      starting = new Promise(resolve => {
+        try {
+          server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            port = address && typeof address === 'object' ? address.port : 0;
+            resolve(port);
+          });
+        } catch (error) {
+          log(`隧道入口监听失败：${error && error.message ? error.message : error}`);
+          resolve(0);
+        }
+      });
+      return starting;
+    },
+    port: () => port,
+    close() {
+      for (const socket of live) socket.destroy();
+      live.clear();
+      if (server) {
+        try {
+          server.close();
+        } catch {
+          /* already closed */
+        }
+      }
+      server = null;
+      port = 0;
+      starting = null;
+    },
+  };
+}
+
+module.exports = { createLoopbackIngress };

package/lib/tailcat/session.cjs

@@ -0,0 +1,264 @@
+'use strict';
+
+/**
+ * 直连隧道这一整套东西的宿主侧会话：拉起助手进程、把它的身份存进 relay.json、
+ * 开配对窗口、同步白名单、给面板一份状态。
+ *
+ * 只做「把助手和插件的存储接起来」，不掺 HTTP、不认识路由：路由那边拿 `status()` 和
+ * `openPairingWindow()` 就行，面板那边同理。这样它能被单测直接驱动（假助手进程即可）。
+ *
+ * 三件必须一直成立：
+ *   1. 存的是**助手自己的身份**（节点私钥 / 预共享密钥 / 区域），助手不落盘 —— 插件永远是
+ *      唯一真相，用户重置插件不会留下一把孤儿钥匙。
+ *   2. 配对窗口是一次性的：每次开窗口都换一把临时钥匙，换完（或过期）就作废。
+ *   3. 手机被吊销时白名单立刻变，助手那边整体重启节点；失败就把白名单退回原样，不能出现
+ *      「界面上已吊销、实际上还能连」。
+ */
+
+const { createTailcatHost, resolveBinary, TUNNEL_PORT, PAIRING_PORT } = require('./host-process.cjs');
+
+/** 开一个配对窗口最多等多久（拉起一个节点要 1~3 秒，弱网更久一点）。 */
+const PAIRING_WINDOW_TIMEOUT_MS = 20_000;
+
+/**
+ * 让一台老设备进来时最多等多久（节点要整体重启一次）。
+ *
+ * 必须留在手机那一发的总预算之内（App 侧一次逻辑请求是 8 秒）：等满 15 秒的话手机先超时，
+ * 界面上就变成「请求没送到电脑」，而电脑其实正在起节点。宁可早点认输 —— 手机 60 秒后会
+ * 自己再问一次，那时候节点已经起来了，第一发就能拿到地址。
+ */
+const ENROLL_TIMEOUT_MS = 6_000;
+
+/** 状态里放白名单与服务端身份的那几格（键名）。 */
+const STATE = {
+  enabled: 'tailcatEnabled',
+  identity: 'tailcatState',
+  allowed: 'tailcatAllowedClients',
+};
+
+/**
+ * @param {object} options
+ * @param {() => {enabled: boolean, identity: string|null, allowed: string[]}} options.readState 读盘上的隧道配置
+ * @param {(patch: object) => void} options.writeState 写回（只写这三个键）
+ * @param {number} options.localPort 插件本机端口，隧道里唯一的去处
+ * @param {() => string} [options.hostName] 电脑名（手机配对时显示）
+ * @param {(message: string) => void} [options.log] 诊断日志
+ * @param {object} [options.host] 测试注入的助手句柄
+ */
+function createTailcatSession(options) {
+  const log = options.log || (() => {});
+  const binary = options.host ? 'injected' : resolveBinary();
+  let host = null;
+  let lastError = '';
+  /** 正在等窗口的那次请求（一次只开一个窗口）。 */
+  let pendingWindow = null;
+
+  function snapshot() {
+    try {
+      const state = options.readState() || {};
+      return {
+        enabled: state[STATE.enabled] !== false,
+        identity: typeof state[STATE.identity] === 'string' ? state[STATE.identity] : null,
+        allowed: Array.isArray(state[STATE.allowed]) ? state[STATE.allowed] : [],
+      };
+    } catch {
+      return { enabled: true, identity: null, allowed: [] };
+    }
+  }
+
+  function persist(patch) {
+    try {
+      options.writeState(patch);
+      return true;
+    } catch (error) {
+      log(`直连隧道：写配置失败 ${error && error.message ? error.message : error}`);
+      return false;
+    }
+  }
+
+  function handleEvent(event) {
+    switch (event.event) {
+      case 'ready':
+        lastError = '';
+        break;
+      case 'pairing':
+        if (pendingWindow) {
+          const done = pendingWindow;
+          pendingWindow = null;
+          done.resolve({
+            address: event.address,
+            port: PAIRING_PORT,
+            key: event.key,
+            proof: event.proof,
+            expiresAt: event.expiresAt,
+          });
+        }
+        break;
+      case 'paired': {
+        // 助手已经把手机加进白名单；存下来，并让二维码作废（码里那把钥匙只服务这一次）。
+        const state = snapshot();
+        const allowed = state.allowed.includes(event.client) ? state.allowed : [...state.allowed, event.client];
+        persist({ [STATE.allowed]: allowed });
+        if (pendingWindowTimeout) clearTimeout(pendingWindowTimeout);
+        break;
+      }
+      case 'persist': {
+        // 助手的身份（私钥 / 预共享密钥 / 区域）与白名单都落在这里；存住了才回执。
+        const patch = { [STATE.allowed]: event.allowedClients };
+        if (typeof event.state === 'string' && event.state) patch[STATE.identity] = event.state;
+        const ok = persist(patch);
+        host && host.ack(event.id, ok);
+        break;
+      }
+      case 'pairingClosed':
+        if (pendingWindow) {
+          const done = pendingWindow;
+          pendingWindow = null;
+          done.resolve(null);
+        }
+        break;
+      case 'error':
+        lastError = event.code;
+        if (pendingWindow) {
+          const done = pendingWindow;
+          pendingWindow = null;
+          done.resolve(null);
+        }
+        break;
+      default:
+        break;
+    }
+  }
+
+  let pendingWindowTimeout = null;
+
+  function start() {
+    if (host) return;
+    if (!binary) {
+      lastError = 'helper-missing';
+      return;
+    }
+    const state = snapshot();
+    if (!state.enabled) return;
+    host = options.host || createTailcatHost({
+      localPort: options.localPort,
+      name: typeof options.hostName === 'function' ? options.hostName() : undefined,
+      state: state.identity,
+      allowedClients: state.allowed,
+      onEvent: handleEvent,
+    });
+    host.start();
+  }
+
+  function stop() {
+    if (pendingWindow) {
+      pendingWindow.resolve(null);
+      pendingWindow = null;
+    }
+    const current = host;
+    host = null;
+    if (current) return current.close();
+    return Promise.resolve();
+  }
+
+  /** 面板与路由看到的现状。 */
+  function status() {
+    const state = snapshot();
+    if (!binary) return { available: false, enabled: state.enabled, ready: false, address: '', paired: state.allowed.length, error: 'helper-missing' };
+    const live = host && typeof host.status === 'function' ? host.status() : { running: false, ready: false, address: '' };
+    return {
+      available: true,
+      enabled: state.enabled,
+      running: Boolean(live.running),
+      ready: Boolean(live.ready),
+      address: live.address || '',
+      paired: state.allowed.length,
+      error: lastError,
+    };
+  }
+
+  /**
+   * 开一个配对窗口。成功给出发给手机的那三样（地址 / 一次性私钥 / 证明串）；
+   * 拉不起节点或超时就给 null，调用方照「这次只能走原来的路子」处理。
+   */
+  function openPairingWindow(ttlSeconds) {
+    if (!binary) return Promise.resolve(null);
+    start();
+    if (!host) return Promise.resolve(null);
+    if (pendingWindow) return pendingWindow.promise;
+    let resolveFn;
+    const promise = new Promise(resolve => {
+      resolveFn = resolve;
+    });
+    pendingWindow = { promise, resolve: resolveFn };
+    pendingWindowTimeout = setTimeout(() => {
+      if (!pendingWindow) return;
+      pendingWindow = null;
+      resolveFn(null);
+    }, PAIRING_WINDOW_TIMEOUT_MS);
+    pendingWindowTimeout.unref?.();
+    host.pair(ttlSeconds);
+    return promise;
+  }
+
+  /**
+   * 让一台**已经配过对**的手机进来，并等回它的入口地址。
+   *
+   * 这是「插件更新之后手机不用重新扫码」的那条路：手机手上已经有这台电脑的凭据，只是
+   * 还不知道有隧道这回事。它把自己的公钥发上来，我们加进白名单、把节点拉起来，再把它该拨
+   * 的地址回给它 —— 与当初「宿主改了中转地址、手机跟着换」是同一套机制。
+   *
+   * 白名单变了节点要整体重启（v0.7 没有单独加人的接口），所以这里要等一小段。
+   */
+  async function enroll(publicKey) {
+    if (!binary || typeof publicKey !== 'string' || !publicKey.startsWith('nodekey:')) return null;
+    start();
+    if (!host) return null;
+    const state = snapshot();
+    if (!state.allowed.includes(publicKey)) {
+      if (!setAllowed([...state.allowed, publicKey])) return null;
+    }
+    const deadline = Date.now() + ENROLL_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      const live = status();
+      if (live.address) return { address: live.address, port: TUNNEL_PORT };
+      await new Promise(resolve => setTimeout(resolve, 250));
+    }
+    return null;
+  }
+
+  /** 换白名单（吊销手机、或者用户手动清空）。助手会整体重启节点。 */
+  function setAllowed(allowedClients) {
+    const allowed = Array.isArray(allowedClients) ? allowedClients : [];
+    if (!persist({ [STATE.allowed]: allowed })) return false;
+    host && host.setAllowed(allowed);
+    return true;
+  }
+
+  /** 面板上的总开关。关掉就是停进程、白名单留着（再打开不用重新配对）。 */
+  function setEnabled(enabled) {
+    const next = Boolean(enabled);
+    if (!persist({ [STATE.enabled]: next })) return false;
+    if (next) start();
+    else stop();
+    return true;
+  }
+
+  return {
+    start,
+    stop,
+    status,
+    enroll,
+    /** 测试缝：直接喂一条助手事件（真实路径是子进程 stdout）。 */
+    _event: handleEvent,
+    openPairingWindow,
+    setAllowed,
+    setEnabled,
+    /** 供测试与诊断：当前配置里的白名单。 */
+    allowedClients: () => snapshot().allowed,
+    constants: { TUNNEL_PORT, PAIRING_PORT },
+    stateKeys: STATE,
+  };
+}
+
+module.exports = { createTailcatSession, STATE, TUNNEL_PORT, PAIRING_PORT };

package/lib/tailcat/wiring.cjs

@@ -0,0 +1,96 @@
+'use strict';
+
+/**
+ * 把直连隧道挂进装配层：回环入口 + 助手会话 + 一条自己的启停 effect。
+ *
+ * 单独一个文件是因为装配层有行数上限（`test/assembly-layer.test.cjs` 钉着）——那些上限不是
+ * 「装配层恰好该多长」，而是「实现不许搬回装配层」。这里的三样东西都是装配动作，实现分别
+ * 在 `ingress.cjs` 与 `session.cjs`。
+ *
+ * 任何一步起不来都只意味着「这台机器没有这条通道」：`mount` 兜住异常并留一行日志，中转与
+ * 局域网一行不受影响。
+ */
+
+const { createLoopbackIngress } = require('./ingress.cjs');
+const { createTailcatSession } = require('./session.cjs');
+
+/**
+ * @param {object} options
+ * @param {(label: string, fn: Function) => any} options.mount 装配层的兜底挂载
+ * @param {(message: string) => void} options.warn 告警出口（拿不到 logger 时为空实现）
+ * @param {object} options.state relay.json 那份内存状态（唯一真值）
+ * @param {(state: object) => void} options.saveState 落盘
+ * @param {() => number} options.lanPortInUse 当前局域网端口（会漂）
+ * @param {() => string} options.hostName 电脑名
+ * @param {object} options.ctx 插件 ctx（只为 `ctx.effect`）
+ * @param {string} options.name 插件名，用于 effect 标签
+ * @returns {object|undefined} 会话；起不来就是 undefined（路由与面板按「不可用」处理）
+ */
+function mountTailcat(options) {
+  const { mount, warn, state, saveState, lanPortInUse, hostName, ctx, name } = options;
+  const ingress = mount('直连隧道入口', () =>
+    createLoopbackIngress({ targetPort: () => lanPortInUse(), log: message => warn(message) }),
+  );
+
+  /**
+   * 端口是异步拿到的（`listen(0)` 要等 `listening`），所以会话也是异步建好的。
+   * 路由和面板在装配阶段就要拿到一个对象，于是对外交的是**门面**：里面那格可能还是空，
+   * 调用方问到的就是「暂不可用」，等挂上了自然就通了 —— 不需要谁去等一次 Promise。
+   */
+  let session = null;
+  const door = {
+    status: () => (session ? session.status() : { available: Boolean(ingress), enabled: true, ready: false, address: '', paired: 0, error: 'starting' }),
+    openPairingWindow: ttl => (session ? session.openPairingWindow(ttl) : Promise.resolve(null)),
+    setAllowed: keys => (session ? session.setAllowed(keys) : false),
+    setEnabled: enabled => (session ? session.setEnabled(enabled) : false),
+    enroll: publicKey => (session ? session.enroll(publicKey) : Promise.resolve(null)),
+    allowedClients: () => (session ? session.allowedClients() : []),
+    start: () => (session ? session.start() : undefined),
+    stop: () => (session ? session.stop() : Promise.resolve()),
+  };
+
+  // 启停单独一条命：跟 sidecar 不是一件事，谁挂了都不该带走对方。
+  // 关的时候先停助手再关回环门——门是助手唯一的去处，反过来会让最后几条连接瞬间断在门上。
+  mount('直连隧道生命周期', () =>
+    ctx.effect(() => {
+      let closed = false;
+      const wiring = ingress
+        ? Promise.resolve(ingress.start())
+            .then(port => {
+              if (closed || !port) return;
+              session = createTailcatSession({
+                readState: () => state,
+                writeState: patch => {
+                  Object.assign(state, patch);
+                  saveState(state);
+                },
+                localPort: port,
+                hostName,
+                log: message => warn(message),
+              });
+              session.start();
+            })
+            .catch(error => warn(`直连隧道没有起来：${error && error.message ? error.message : error}`))
+        : Promise.resolve();
+      return () => {
+        closed = true;
+        void wiring.then(() => {
+          try {
+            if (session) session.stop();
+            session = null;
+          } catch {
+            /* 已经在停 */
+          }
+          try {
+            if (ingress) ingress.close();
+          } catch {
+            /* 已经关了 */
+          }
+        });
+      };
+    }, `${name}: tailcat`),
+  );
+  return door;
+}
+
+module.exports = { mountTailcat };

package/lib/update-install.cjs

@@ -207,6 +207,41 @@ function installedVersion(profileNodeModules, name = DEFAULT_NAME) {
   }
 }
 
+/**
+ * 这次装完后，插件「按当前平台装上的」可选依赖（例如 tailcat 平台包）各自的实际版本。
+ *
+ * 它们和插件本体一样可能刚发布就被装进来，登记排除清单时要一并写 —— 否则这些包自己的
+ * 锁条目会把后续的安装挡在 24 小时冷却窗口里（漏的正是刚发的那几个平台包）。只统计真的
+ * 落在 node_modules 里的那些：os / cpu 不匹配被包管理器跳过的平台包不登记。
+ *
+ * 读不到插件清单或读不到某个依赖都只跳过、不抛 —— 登记是善后，不该把装好的版本说成没装上。
+ */
+function installedOptionalDeps(profileNodeModules, name = DEFAULT_NAME) {
+  const readVersion = (dir) => {
+    try {
+      const raw = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+      return typeof raw.version === 'string' && raw.version ? raw.version : null;
+    } catch {
+      return null;
+    }
+  };
+  const out = [];
+  let optional;
+  try {
+    optional = JSON.parse(fs.readFileSync(path.join(profileNodeModules, name, 'package.json'), 'utf8')).optionalDependencies;
+  } catch {
+    return out;
+  }
+  if (!optional || typeof optional !== 'object') return out;
+  for (const depName of Object.keys(optional)) {
+    // hoisted 布局在 profile/node_modules 顶层；严格布局下在插件自己的 node_modules 里。
+    const version = readVersion(path.join(profileNodeModules, depName))
+      || readVersion(path.join(profileNodeModules, name, 'node_modules', depName));
+    if (version) out.push({ name: depName, version });
+  }
+  return out;
+}
+
 /**
  * profile 的依赖声明里这个包是怎么装的（`profileDir` 是 profile 根，不是它的 node_modules）。
  *
@@ -719,6 +754,13 @@ async function installLatest({
   const changed = after !== null && after !== beforeVersion;
   // 这一版是我们绕开晾置期装进去的，登记进排除清单，免得它反过来把别的安装挡 24 小时。
   const releaseAgeRecorded = changed ? recordReleaseAgeExclusion(profileDir, name, after) : false;
+  // 插件按平台带出来的可选依赖（如 tailcat 平台包）也是刚发就可能刚装上的，同批登记，
+  // 否则这些包自己的锁条目会把后续安装挡在冷却窗口里。逐条尽力写，失败不影响主结果。
+  if (changed) {
+    for (const dep of installedOptionalDeps(profileNodeModules, name)) {
+      recordReleaseAgeExclusion(profileDir, dep.name, dep.version);
+    }
+  }
   return {
     installed: changed,
     skipped: false,
@@ -845,6 +887,7 @@ module.exports = {
   installLatest,
   installLatestIfNeeded,
   installedVersion,
+  installedOptionalDeps,
   declaredSource,
   // 「Windows 上怎么起包管理器」在本机跑不起来，守卫只能验拼好的那一行，所以这两样露出来。
   cmdInvocation,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mobile-plugin",
-  "version": "0.5.21",
+  "version": "0.5.23",
   "description": "Mobile API (/api/mobile/v1) and relay client for the DSH mobile app — desktop profile build (dsh 0.2.x, peers resolved by the host)",
   "license": "MIT",
   "icon": "./icon.png",
@@ -42,6 +42,8 @@
     "dsh-mobile-credentials",
     "locale/*.json",
     "icon.png",
+    "assets/pets/**",
+    "extensions/**",
     "README.md"
   ],
   "publishConfig": {
@@ -58,6 +60,13 @@
     "qrcode": "1.5.4",
     "ws": "8.18.0"
   },
+  "optionalDependencies": {
+    "dsh-mobile-tailcat-darwin-arm64": "1.0.0",
+    "dsh-mobile-tailcat-darwin-x64": "1.0.0",
+    "dsh-mobile-tailcat-linux-arm64": "1.0.0",
+    "dsh-mobile-tailcat-linux-x64": "1.0.0",
+    "dsh-mobile-tailcat-win32-x64": "1.0.0"
+  },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.1",
     "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.2 || ^0.2.0-rc.1 || ^0.2.1-rc.2",