dsh-mobile-plugin 0.5.20 → 0.5.22

package/lib/tailcat/host-process.cjs

@@ -0,0 +1,266 @@
+'use strict';
+
+/**
+ * 手机直连隧道的电脑端助手进程：找得到就拉起、挂了重拉、退出收掉。
+ *
+ * 这个文件只管「进程」：助手在哪、怎么起、stdout 上那几行事件是什么意思。业务判断
+ * （白名单该是谁、配对窗口什么时候开、状态存到哪）留给调用方——它通过 onEvent 收事件，
+ * 通过 `persist` 事件里的 id 回执告诉助手「这笔改动存住了没有」。助手自己不留状态，
+ * 所以插件永远只有一份真相。
+ *
+ * 二进制从按平台的 npm 包装出来（`dsh-mobile-tailcat-<平台>`），装不上就没有这条通道，
+ * 其余功能一点不受影响——这也是不做运行时下载的理由：走的还是插件自己那条包管理器链路，
+ * 国内镜像、完整性校验、断点重试都是包管理器现成的。
+ *
+ * 助手是 Go 编的原生程序，Windows 上是 .exe；它只监听回环（由插件告诉它本机端口），
+ * 隧道里也只开一个固定端口。
+ */
+
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+/** 助手 IPC 版本，跟 tailcat-host/main.go 的 protoVersion 一起改。 */
+const IPC_VERSION = 1;
+
+/** 隧道里那个固定端口，与 tailcat-host/node.go 的 virtualPort 一致。 */
+const TUNNEL_PORT = 48941;
+
+/** 配对窗口那个端口，与 pairingPort 一致（手机侧知道它，但只需拨它一次）。 */
+const PAIRING_PORT = 48942;
+
+/** 一行 IPC 的上限，与助手的 lineLimit 一致。 */
+const MAX_LINE = 64 * 1024;
+
+/** 重启退避：起不来时别把机器打满。 */
+const BACKOFF_MS = [1_000, 2_000, 5_000, 10_000, 30_000];
+
+/** 事件里允许出现的键，多一个少一个都当脏数据丢掉（stdout 是私有 IPC）。 */
+const EVENT_KEYS = {
+  ready: ['address'],
+  pairing: ['address', 'port', 'key', 'proof', 'expiresAt'],
+  paired: ['address', 'client'],
+  pairingClosed: [],
+  persist: ['id', 'state', 'allowedClients'],
+  error: ['code'],
+};
+
+const ADDRESS = /^tc[\x21-\x7e]{0,4095}$/;
+const PRIVATE_KEY = /^privkey:[0-9a-f]{64}$/;
+const CLIENT_KEY = /^nodekey:[0-9a-f]{64}$/;
+const PROOF = /^[A-Za-z0-9_-]{43}$/;
+
+/** 这台机器对应哪个平台包（与 tools/build-tailcat-helper.mjs 的 id 一致）。 */
+function platformId(platform = process.platform, arch = process.arch) {
+  const os = platform === 'win32' ? 'win32' : platform;
+  const cpu = arch === 'x64' ? 'x64' : arch === 'arm64' ? 'arm64' : arch;
+  const id = `${os}-${cpu}`;
+  return ['darwin-arm64', 'darwin-x64', 'linux-x64', 'linux-arm64', 'win32-x64'].includes(id) ? id : undefined;
+}
+
+/**
+ * 找助手二进制：先按平台包解析（npm 装出来的正常形态），找不到就回 null——
+ * 调用方据此把这条通道标成「不可用」，不要抛错、不要影响插件启动。
+ */
+function resolveBinary(options = {}) {
+  const platform = options.platformId || platformId(options.platform, options.arch);
+  if (!platform) return null;
+  const name = platform === 'win32-x64' ? 'dsh-tailcat-host.exe' : 'dsh-tailcat-host';
+  const pkg = `dsh-mobile-tailcat-${platform}`;
+
+  // 1. 平台包（可选依赖装出来的那份）。npm / pnpm 把可选依赖装在「插件自己这份 node_modules」里，
+  //    所以先按本模块自身所在位置解析（从本文件往上找，嵌套与 hoisted 布局都命中）——运行时的工作
+  //    目录（宿主可能是别处）跟安装目录不是一回事，只按工作目录找会在真实部署里找不到；再退回调用方
+  //    指定路径 / 当前工作目录（老行为，部署方把包放在工作目录时仍可用）。
+  for (const paths of [undefined, options.paths || [process.cwd()]]) {
+    try {
+      const manifest = require.resolve(`${pkg}/package.json`, paths ? { paths } : undefined);
+      const candidate = path.join(path.dirname(manifest), name);
+      if (fs.existsSync(candidate)) return candidate;
+    } catch {
+      /* 这一路没有：试下一路 */
+    }
+  }
+
+  // 2. 指定的路径（开发机、或者部署方自己放好的那一份）。
+  const override = process.env.DSHM_TAILCAT_HELPER;
+  if (typeof override === 'string' && override && fs.existsSync(override)) return override;
+
+  // 3. 本仓交叉编译的产物（开发与自测用）。
+  const dev = path.join(__dirname, '..', '..', '..', 'build', 'tailcat-runtime', platform, name);
+  if (fs.existsSync(dev)) return dev;
+  return null;
+}
+
+/**
+ * 拉起一个助手进程。
+ *
+ * options:
+ *   localPort        插件本机 HTTP 端口（隧道里唯一的去处）
+ *   name             这台电脑的名字（手机配对时显示）
+ *   state            上次存下来的身份（字符串）或 null
+ *   allowedClients   已经配过对的手机公钥
+ *   onEvent(event)   事件回调，event 已去掉 event 字段之外的脏数据
+ *   resolve          覆盖二进制查找（测试用）
+ */
+function createTailcatHost(options) {
+  const binary = (options.resolve || resolveBinary)(options);
+  let child;
+  let buffer = '';
+  let closed = false;
+  let restarts = 0;
+  let backoffIndex = 0;
+  let restartTimer;
+  let ready = false;
+  let address = '';
+
+  const status = () => ({ available: Boolean(binary), running: Boolean(child), ready, address, restarts });
+
+  function write(value) {
+    if (!child || !child.stdin || !child.stdin.writable) return;
+    child.stdin.write(`${JSON.stringify(value)}\n`);
+  }
+
+  function handleLine(line) {
+    let value;
+    try {
+      value = JSON.parse(line);
+    } catch {
+      return; // 脏行直接丢，从不回显
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return;
+    const kind = value.event;
+    if (typeof kind !== 'string' || !EVENT_KEYS[kind]) return;
+    const keys = Object.keys(value);
+    const fields = EVENT_KEYS[kind];
+    if (keys.length !== fields.length + 1 || fields.some(field => !(field in value))) return;
+
+    if (kind === 'ready' && typeof value.address === 'string' && (value.address === '' || ADDRESS.test(value.address))) {
+      ready = true;
+      address = value.address;
+      backoffIndex = 0;
+    } else if (kind === 'pairing') {
+      if (!ADDRESS.test(String(value.address)) || value.port !== PAIRING_PORT) return;
+      if (!PRIVATE_KEY.test(String(value.key)) || !PROOF.test(String(value.proof))) return;
+      if (!Number.isSafeInteger(value.expiresAt)) return;
+    } else if (kind === 'paired') {
+      if (!CLIENT_KEY.test(String(value.client)) || !ADDRESS.test(String(value.address))) return;
+      address = value.address;
+    } else if (kind === 'persist') {
+      if (typeof value.id !== 'string' || value.id.length > 32) return;
+      if (!Array.isArray(value.allowedClients)) return;
+    } else if (kind === 'error') {
+      if (typeof value.code !== 'string' || value.code.length > 64) return;
+      ready = false;
+    }
+    options.onEvent({ ...value });
+  }
+
+  function scheduleRestart() {
+    if (closed || restartTimer) return;
+    const delay = BACKOFF_MS[Math.min(backoffIndex, BACKOFF_MS.length - 1)];
+    backoffIndex += 1;
+    restarts += 1;
+    restartTimer = setTimeout(() => {
+      restartTimer = undefined;
+      launch();
+    }, delay);
+    restartTimer.unref?.();
+  }
+
+  function launch() {
+    if (closed || !binary) return;
+    let proc;
+    try {
+      proc = spawn(binary, [], { stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true });
+    } catch {
+      scheduleRestart();
+      return;
+    }
+    child = proc;
+    buffer = '';
+    ready = false;
+    proc.on('error', () => {});
+    proc.stdin?.on('error', () => {});
+    proc.stdout?.setEncoding('utf8');
+    proc.stdout?.on('data', chunk => {
+      if (child !== proc) return;
+      buffer += chunk;
+      for (let at = buffer.indexOf('\n'); at >= 0; at = buffer.indexOf('\n')) {
+        const line = buffer.slice(0, at);
+        buffer = buffer.slice(at + 1);
+        handleLine(line);
+      }
+      if (buffer.length > MAX_LINE) proc.kill();
+    });
+    proc.on('exit', () => {
+      if (child !== proc) return;
+      child = undefined;
+      ready = false;
+      address = '';
+      if (!closed) scheduleRestart();
+    });
+    write({
+      version: IPC_VERSION,
+      localPort: options.localPort,
+      name: String(options.name || os.hostname()).slice(0, 64),
+      state: options.state === undefined ? null : options.state,
+      allowedClients: Array.isArray(options.allowedClients) ? options.allowedClients : [],
+    });
+  }
+
+  return {
+    status,
+    start() {
+      if (closed || child) return;
+      launch();
+    },
+    /** 开一个配对窗口（助手自己管两分钟过期）。 */
+    pair(ttlSeconds) {
+      write({ command: 'pair', ttl: ttlSeconds });
+    },
+    cancelPairing() {
+      write({ command: 'cancelPairing' });
+    },
+    /** 换白名单（吊销手机就走这条）。 */
+    setAllowed(allowedClients) {
+      write({ command: 'setAllowed', allowedClients: allowedClients || [] });
+    },
+    /** 回执：state 存住了没有。 */
+    ack(id, ok) {
+      write({ command: 'ack', id, ok: Boolean(ok) });
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      if (restartTimer) clearTimeout(restartTimer);
+      restartTimer = undefined;
+      const proc = child;
+      child = undefined;
+      if (!proc || proc.exitCode !== null) return;
+      // 收起 stdin 就是助手的停止信号；它无视才强杀。
+      await new Promise(done => {
+        const timer = setTimeout(() => {
+          proc.kill();
+          done();
+        }, 3_000);
+        timer.unref?.();
+        proc.once('exit', () => {
+          clearTimeout(timer);
+          done();
+        });
+        proc.stdin?.end();
+      });
+    },
+  };
+}
+
+module.exports = {
+  IPC_VERSION,
+  TUNNEL_PORT,
+  PAIRING_PORT,
+  platformId,
+  resolveBinary,
+  createTailcatHost,
+};

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 };