dsh-pocket-relay 1.0.0

package/lib/index.js

@@ -0,0 +1,414 @@
+// dsh-pocket-relay 插件入口（单包单插件：手机扫码访问 DSH + 自建 relay 远程，全在这一个包里）
+//
+// 设置一级入口「手机访问」：
+//   - 局域网二维码：自动显示（代理随插件启动）
+//   - 公网二维码：点「开启公网」→ cloudflared 隧道 → 扫码即用，人在外面也能访问
+//   - 更新提示：有新版本时显示一键更新按钮（dsh plugin update --latest）
+// 手机看到的界面 = 电脑上的 dsh web，实时同步（WebSocket 透传）。
+//
+// 注：Web Push 已移除——浏览器推送依赖 Google FCM（Chrome）等境外服务，
+// 国内直连被墙，普通用户用不了，且排障成本高。专注扫码同屏这一件事。
+
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { readFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { writeFile, readFile, mkdir, rm } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { randomBytes, randomInt } from 'node:crypto';
+
+import { createPocketService } from './service.mjs';
+import { installPocketRpc } from './web-rpc.js';
+import { restartHost } from './restart.js';
+import { advancedNoticeScript, DEFAULT_INJECT, classifyHost } from './proxy.mjs';
+import { lanEnabled, setLanEnabled, lanAuthEnabled, setLanAuthEnabled, lanIpOverride, setLanIpOverride, pinCustom, setPinCustom, tunnelMode, setTunnelMode, tunnelToken, setTunnelToken, tunnelHostname, setTunnelHostname, resetSettings, proxyPort, cloudflaredPath, relayConfig, setRelayConfig } from './settings.mjs';
+
+const name = 'dsh-pocket-relay';
+const inject = ['connection', 'webServer'];
+
+const pkgPath = fileURLToPath(new URL('../package.json', import.meta.url));
+
+/**
+ * 本插件磁盘上的已安装版本。注意：**不能用 require 缓存**（进程内永远不变），
+ * 必须实时读文件——一键更新会改写 package.json，「已更新未重启」靠它识别。
+ */
+function currentVersion() {
+  try {
+    return JSON.parse(readFileSync(pkgPath, 'utf8')).version;
+  } catch {
+    return '0.0.0';
+  }
+}
+
+/** 进程启动时加载的版本（模块加载瞬间固化；用于识别「磁盘已更新但进程还是旧代码」）。 */
+const loadedVersion = currentVersion();
+
+// ---------- 访问密码（issue #13 + #18 + #33） ----------
+// 公网与局域网**分开**：各自 8 位，存本机 $DSH_HOME/dsh-pocket/。
+// 公网密码（token）：默认每次开启公网时轮换（旧链接作废）；**用户自定义后不再轮换**；
+// 局域网密码（token-lan）：默认手动刷新（设置页按钮）；自定义后刷新会换回随机值。
+// 会话保持（issue #33）：登录 cookie 绑定进程级 sessionKey（见 apply）——
+// dsh web 重启/更新后 sessionKey 变化 → 手机需重新输入。
+// 密码规则：8 位英文字母（大小写）或数字（自动生成的为 8 位数字，自定义可为字母+数字）。
+const PIN_RE = /^[a-zA-Z0-9]{8}$/;
+function writePinToFile(p, fresh) {
+  try {
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, fresh, { mode: 0o600 });
+  } catch { /* 忽略 */ }
+  return fresh;
+}
+function readPin(p) {
+  try {
+    const existing = readFileSync(p, 'utf8').trim();
+    if (PIN_RE.test(existing)) return existing;
+  } catch { /* 无文件 */ }
+  return null;
+}
+/**
+ * 生成 8 位访问 PIN（issue #90）。
+ * 必须用 CSPRNG。语言内置的非加密随机数（V8 的 xorshift128+）是可预测的：拿到少量
+ * 输出即可还原内部状态并推算后续值——用它生成访问密码，等于把 9×10⁷ 的搜索空间
+ * 进一步压缩。`randomInt(min, max)` 上界开区间，取值 10000000..99999999。
+ * test/auth-routing.test.js 有源码守卫，禁止这里再出现非加密随机数调用。
+ */
+function newPin() {
+  return String(randomInt(10_000_000, 100_000_000));
+}
+
+// --- 公网密码 ---
+const tokenRel = join('dsh-pocket', 'token');
+function tokenPath() {
+  return join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), tokenRel);
+}
+/** 当前公网访问密码；文件不存在时生成一个。 */
+export function getAccessToken() {
+  return readPin(tokenPath()) ?? writePinToFile(tokenPath(), newPin());
+}
+/** 轮换公网密码（开启公网时调用）。用户自定义后不再轮换（尊重自定义值）。 */
+export function rotateAccessToken() {
+  if (pinCustom('public')) return getAccessToken();
+  return writePinToFile(tokenPath(), newPin());
+}
+
+// --- 局域网密码（issue #18：局域网与公网分开，手动刷新） ---
+const lanTokenRel = join('dsh-pocket', 'token-lan');
+function lanTokenPath() {
+  return join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), lanTokenRel);
+}
+/** 当前局域网访问密码；文件不存在时生成一个。 */
+function getLanToken() {
+  return readPin(lanTokenPath()) ?? writePinToFile(lanTokenPath(), newPin());
+}
+/** 刷新局域网密码（设置页按钮触发，旧密码立即作废）；换新后清除自定义标记。 */
+function refreshLanToken() {
+  setPinCustom('lan', false);
+  return writePinToFile(lanTokenPath(), newPin());
+}
+/**
+ * 按 Host 分发的访问密码（issue #66：fail closed）。
+ * 公网 = classifyHost 判为 public 的 Host（trycloudflare **或用户自建命名隧道的任意固定域名**），
+ * 一律校验公网密码；loopback/局域网（私网 IP、.local 等）才走局域网密码——
+ * 自建隧道 + 关闭局域网密码不再出现公网裸奔。
+ */
+export function tokenForHost(host) {
+  if (isLanOverrideHost(host)) return getLanToken();
+  return classifyHost(host) === 'public' ? getAccessToken() : getLanToken();
+}
+/** 去掉 Host 的端口（与 classifyHost 一致），用于和手动设置的局域网地址比较。 */
+function hostNameOnly(host) {
+  let name = String(host ?? '').trim().toLowerCase();
+  if (name.startsWith('[')) {
+    const end = name.indexOf(']');
+    if (end >= 0) name = name.slice(1, end);
+  } else {
+    name = name.replace(/:\d+$/, '');
+  }
+  return name;
+}
+/**
+ * 用户手动指定的「局域网地址」覆盖（issue #79）：无论什么网段（含 Radmin 26.x 等任意 overlay），
+ * 一律按局域网密码/开关裁决。优先级高于 classifyHost——避免某 overlay 地址落在公网判定里、
+ * 导致局域网入口被错判成公网、比对成公网密码而永远「密码错误」。
+ */
+export function isLanOverrideHost(host) {
+  const override = lanIpOverride().trim().toLowerCase();
+  return override.length > 0 && hostNameOnly(host) === override;
+}
+/**
+ * 用户自定义访问密码（issue #33）：公网/局域网各自设一个固定的 8 位密码（英文字母大小写或数字）。
+ * 自定义后公网开启时不再自动轮换（rotateAccessToken 见上）。
+ * 非法输入（非 8 位、含字母数字以外字符）抛错，由 RPC 层转成错误响应。
+ */
+export function setCustomPin(which, value) {
+  const v = String(value ?? '').trim();
+  if (!PIN_RE.test(v)) throw new Error('密码必须是 8 位英文字母或数字 | PIN must be exactly 8 characters (letters and digits only)');
+  if (which === 'public') {
+    writePinToFile(tokenPath(), v);
+    setPinCustom('public', true);
+    return v;
+  }
+  if (which === 'lan') {
+    writePinToFile(lanTokenPath(), v);
+    setPinCustom('lan', true);
+    return v;
+  }
+  throw new Error('未知密码类型 | unknown PIN kind');
+}
+
+/**
+ * 恢复出厂设置（设置页底部按钮）：清空本机设置 + 重设随机访问密码。
+ *
+ * 删除 settings.json → 所有开关回到默认（局域网访问开、访问密码开、局域网地址自动、
+ * 公网模式随机、固定域名/Tunnel Token 清空）；公网与局域网密码都换新随机 8 位值
+ * （旧密码立即作废，手机需重新输入）。只动 $DSH_HOME/dsh-pocket/ 下的文件，
+ * DSH 自身的会话、模型、插件配置不受影响。
+ *
+ * 注意：调用方应先停掉正在运行的公网隧道（RPC 层已处理），避免重置后仍按旧模式连接。
+ * @returns {{accessToken:string, lanToken:string}} 重置后的新密码
+ */
+export function resetPocketState() {
+  resetSettings();
+  writePinToFile(tokenPath(), newPin());
+  writePinToFile(lanTokenPath(), newPin());
+  return { accessToken: getAccessToken(), lanToken: getLanToken() };
+}
+
+const restartNoticeRel = join('dsh-pocket', 'restarted.json');
+function restartNoticePath() {
+  return join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), restartNoticeRel);
+}
+async function readRestartNotice() {
+  try {
+    const raw = JSON.parse(await readFile(restartNoticePath(), 'utf8'));
+    if (!raw?.at) return null;
+    if (Date.now() - raw.at > 30 * 60 * 1000) return null; // 30 分钟后过期
+    return raw;
+  } catch { return null; }
+}
+function writeRestartNotice() {
+  return mkdir(dirname(restartNoticePath()), { recursive: true })
+    .then(() => writeFile(restartNoticePath(), JSON.stringify({ at: Date.now(), pid: process.pid }), 'utf8'));
+}
+/**
+ * 读重启标记并**删除**（一次性消费）：重启后首次打开设置页显示一次「已重启」横幅，
+ * 之后不再出现——否则残留文件会让「已重启」一直显示（用户没点重启也误报）。
+ */
+async function consumeRestartNotice() {
+  const notice = await readRestartNotice();
+  if (notice) {
+    await rm(restartNoticePath(), { force: true }).catch(() => {});
+  }
+  return notice;
+}
+/**
+ * 自重启。
+ * 顺序很重要：先拉起 helper（失败就如实返回，不写标记、不停隧道）→ 停公网隧道
+ * （否则孤儿 cloudflared 让旧公网 URL 永活，与「重启即换 URL 作废」的宣传矛盾）→
+ * 写重启标记（新进程据此显示一次「已重启」横幅）。
+ */
+function pocketRestart(service) {
+  const result = restartHost();
+  if (!result || result.helperPid == null) return result; // helper 都没 spawn 出来 → 失败
+  // 停隧道是为了杀孤儿 cloudflared；保留自动恢复标记——重启后隧道要自动拉起（issue #11）
+  try { service?.stopTunnel({ keepAutoMarker: true }); } catch { /* 忽略 */ }
+  writeRestartNotice().catch(() => {});
+  return result;
+}
+
+/** 执行更新：dsh plugin --profile <p> update dsh-pocket-relay --latest -w（超时保护）。 */
+function performUpdate(profile, { timeoutMs = 180_000 } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn('dsh', ['plugin', '--profile', profile, 'update', 'dsh-pocket-relay', '--latest', '-w'], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      // Windows 上裸 spawn('dsh') 解析到无扩展名 POSIX shim → ENOENT；
+      // Node 22+ 直接 spawn .cmd 会 EINVAL（CVE-2024-27980），必须走 shell（PR #54）
+      shell: process.platform === 'win32',
+    });
+    let out = '';
+    const onData = (c) => { out += String(c); if (out.length > 4000) out = out.slice(-4000); };
+    child.stdout.on('data', onData);
+    child.stderr.on('data', onData);
+    const timer = setTimeout(() => child.kill(), timeoutMs);
+    child.once('exit', (code) => {
+      clearTimeout(timer);
+      resolve({ ok: code === 0, code, output: out.slice(-800) });
+    });
+    child.once('error', (err) => {
+      clearTimeout(timer);
+      resolve({ ok: false, error: err.message });
+    });
+  });
+}
+
+export function apply(ctx, config = {}, internals = {}) {
+  const logger = ctx.logger?.(name) ?? console;
+  const dshPort = internals.dshPort ?? ctx.webServer?.port;
+  if (!dshPort) {
+    logger.error('dsh-pocket-relay: webServer port unavailable — cannot start proxy | 拿不到 dsh web 端口，无法启动代理');
+    return () => {};
+  }
+
+  // cloudflared 自定义路径（issue #45）：远程 Linux 服务器下载源全失败时，
+  // 让用户能在 settings.json 写死一个已经存在的二进制路径，绕过自动下载。
+  // 同步到 env 让 lib/tunnel.mjs 的 resolveCloudflared 第一时间读到。
+  const cfPath = cloudflaredPath();
+  if (cfPath) {
+    process.env.DSH_POCKET_CLOUDFLARED = cfPath;
+    logger.info(`dsh-pocket-relay: using custom cloudflared at ${cfPath} (skipping auto-download) | 使用自定义 cloudflared 路径（跳过自动下载）`);
+  }
+
+  // 桌面端环境识别（官方兼容模式，见 desktop 的 plugin-development.md）：
+  // desktopProfiles / desktopPnpm 只在 DSH Desktop（Electron）里存在。
+  // 桌面端有自己的更新/进程管理，我们这两项功能在此环境**关闭**（不删除），
+  // 避免与 desktopPnpm / Electron 进程模型冲突；扫码同屏等正常功能照常。
+  const isDesktop = internals.isDesktop !== undefined
+    ? internals.isDesktop === true
+    : ctx.get?.('desktopProfiles') !== undefined || ctx.get?.('desktopPnpm') !== undefined;
+  if (isDesktop) {
+    logger.info('dsh-pocket-relay: DSH Desktop detected — update/restart disabled here | 检测到桌面端环境，更新/重启已关闭');
+  }
+
+  // 桌面端 advanced 模式检测（issue #19）：dsh-plugin-desktop 的 mode 配置存在
+  // $DSH_HOME/settings.yaml 的 dsh-plugin-desktop 命名空间下。advanced 组合禁用网页版
+  // ui-layout、手机页面又拿不到桌面 layout → 手机访问白屏，这里注入覆盖层提示用户切回。
+  const desktopAdvanced = isDesktop && (() => {
+    try {
+      const raw = readFileSync(join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'settings.yaml'), 'utf8');
+      return /dsh-plugin-desktop\s*:\s*[\s\S]{0,300}?mode\s*:\s*advanced/i.test(raw);
+    } catch { return false; }
+  })();
+  if (desktopAdvanced) {
+    logger.warn('dsh-pocket-relay: DSH Desktop advanced mode — phone access unsupported, injecting notice | 桌面端 advanced 模式：手机访问暂不支持，已注入提示');
+  }
+
+  const service = internals.service ?? createPocketService({
+    dshPort,
+    // 端口（issue #70）：插件模式优先级 settings.proxyPort > cordis patch config.port > 3081。
+    // 3081 被占时 createPocketService 内部 EADDRINUSE 抛错，按 DSH 插件启动失败处理（用户改端口重启即可）。
+    port: internals.port ?? config.port ?? (proxyPort() || 3081),
+    home: internals.home,
+    internals,
+    getLanIpOverride: () => lanIpOverride(),
+    getLanEnabled: () => lanEnabled(),
+    // 桌面端**不再**注入 dsh-desktop-* 标记（issue #76）：
+    //   - 旧版 dsh-plugin-desktop 缺 mode/platform 会抛错，当初正是为此加了补丁（issue #3/#4）；
+    //   - 但 2.0.3 起，mode 与 platform **同时缺失**时 parseDesktopClientEnvironment 直接返回
+    //     undefined（视作非桌面外壳，跳过全部桌面逻辑），正是手机页需要的效果；
+    //   - 反之只要 URL 上出现任一 dsh-desktop-* 标记，客户端就会强制校验整组
+    //     （material + semver version + mica），只补两个必然抛 "invalid or missing
+    //     dsh-desktop-material" → 插件树加载失败 → 页面变成「打开恢复模式」；
+    //   - 更糟的是 decideDesktopBrowserAccess 见到 dsh-desktop-* 前缀就把没有渲染器 token 的
+    //     普通浏览器判为 denied（403），刷新后直接打不开。
+    // 结论：手机/浏览器访问一律不带这些标记，advanced 模式另加警告覆盖层（issue #19）。
+    injectHtml: isDesktop
+      ? DEFAULT_INJECT + (desktopAdvanced ? advancedNoticeScript() : '')
+      : undefined,
+    // 访问密码（issue #13 + #18 + #24 + #33 + #66）：公网永远要密码（默认每次开启变新，
+    // 用户自定义后不再轮换）；局域网按开关（默认开启；关闭后局域网扫码直连）。
+    // 公网的判定是 fail closed：除了 loopback/私网 Host，一切陌生域名（含自建
+    // 命名隧道的固定域名）都按公网处理、强制公网密码。
+    auth: {
+      // sessionKey：进程级随机密钥——登录 cookie 绑定它（会话保持，issue #33）：
+      // dsh web 重启/更新后 sessionKey 变化 → 手机需重新输入
+      sessionKey: randomBytes(16).toString('hex'),
+      getToken: (host) => tokenForHost(host),
+      isProtected: (host) => {
+        if (isLanOverrideHost(host)) return lanAuthEnabled();
+        return classifyHost(host) === 'public' ? true : lanAuthEnabled();
+      },
+    },
+    // dsh web 浏览器会话启动 token（issue #77）：新版 dsh（>= 0.1.2-alpha.1）要求根路径
+    // 带一次 `?token=` 换 cookie，否则 /api 与 WebSocket 全 401。token 每次进程启动都变，
+    // 所以每次请求实时从 connection 服务取；老版本没有这个方法 → 返回空，行为不变。
+    launchToken: () => {
+      try {
+        const fn = ctx.connection?.authenticatedUrl;
+        if (typeof fn !== 'function') return '';
+        const url = new URL(fn.call(ctx.connection, `http://127.0.0.1:${dshPort}`));
+        return url.searchParams.get('token') ?? '';
+      } catch {
+        return '';
+      }
+    },
+    // 隧道模式（issue #66）：'quick'（默认，随机 trycloudflare.com）| 'named'（固定域名）
+    getTunnelConfig: () => ({ mode: tunnelMode(), token: tunnelToken(), hostname: tunnelHostname() }),
+    // 中继配置：service 启动时常驻连接（「无人监听」靠它）
+    getRelayConfig: () => relayConfig(),
+    // 隧道就绪回调：快速模式每次开启轮换 8 位密码（旧链接作废）；命名模式地址固定，
+    // 不自动轮换（重启后密码不变，用户可用「自定义密码」主动更换）。
+    onTunnelReady: (mode) => {
+      if (mode === 'named') {
+        logger.info('dsh-pocket-relay: named tunnel ready — PIN not rotated | 命名隧道就绪（公网密码不自动轮换）');
+        return getAccessToken();
+      }
+      const fresh = rotateAccessToken();
+      logger.info('dsh-pocket-relay: public access PIN refreshed | 公网访问密码已更新（自定义密码不受影响）');
+      return fresh;
+    },
+  });
+
+  const disposers = [];
+  const disposeRpc = installPocketRpc(ctx, {
+    service,
+    desktop: isDesktop,
+    getToken: () => getAccessToken(),
+    getLanToken: () => getLanToken(),
+    refreshLanToken: () => refreshLanToken(),
+    getLanAuthEnabled: () => lanAuthEnabled(),
+    setLanAuthEnabled: (on) => setLanAuthEnabled(on),
+    getLanEnabled: () => lanEnabled(),
+    setLanEnabled: (on) => setLanEnabled(on),
+    getLanIpOverride: () => lanIpOverride(),
+    setLanIpOverride: (ip) => setLanIpOverride(ip),
+    getPinCustom: (which) => pinCustom(which),
+    setCustomPin: (which, value) => setCustomPin(which, value),
+    // 命名隧道配置（issue #66）：RPC 只回显脱敏视图（token 只写不读）
+    getTunnelConfig: () => ({ mode: tunnelMode(), hostname: tunnelHostname(), tokenSet: tunnelToken().length > 0 }),
+    // 中继（自建服务器）：这里给的是**完整**配置（含 token），
+    // 因为 relayView() 要据它算 tokenSet、applyRelayState() 要据它判配置是否完整；
+    // 对外回显一律走 web-rpc 的 relayView() 脱敏，token 永不进响应体。
+    getRelayConfig: () => relayConfig(),
+    setRelayConfig: (patch) => setRelayConfig(patch),
+    // 恢复出厂设置：清空设置文件 + 重设随机密码（RPC 层已先停掉公网隧道）
+    resetPocket: () => resetPocketState(),
+    setTunnelConfig: ({ mode, hostname, token } = {}) => {
+      const m = mode === undefined ? tunnelMode() : mode;
+      if (m !== 'quick' && m !== 'named') throw new Error('未知隧道模式 | unknown tunnel mode');
+      setTunnelMode(m);
+      if (hostname !== undefined) setTunnelHostname(hostname);
+      if (token !== undefined) setTunnelToken(token);
+      return { mode: tunnelMode(), hostname: tunnelHostname(), tokenSet: tunnelToken().length > 0 };
+    },
+    runUpdate: internals.runUpdate ?? { currentVersion, perform: performUpdate, loadedVersion: () => loadedVersion },
+    restart: internals.restart ?? (() => pocketRestart(service)),
+    restartNotice: internals.restartNotice ?? consumeRestartNotice,
+    log: logger,
+  });
+  disposers.push(disposeRpc);
+
+  // 代理随插件自动启动（局域网二维码开箱即用，零配置）
+  void service.startProxy().then((proxy) => {
+    logger.info('dsh-pocket-relay: proxy ready on :%d | 局域网代理已就绪', proxy.port);
+    // 自动恢复上次开启的公网隧道（DSH 重启后 cloudflared 子进程被杀，issue #11）
+    void service.restoreTunnelIfNeeded?.().catch(() => {});
+    // 中继：配置好就直接连，**不等用户点任何按钮**——这就是「无人监听」。
+    // 放在 startProxy 之后：relay 的流量要打到代理上，代理必须先就绪。
+    // 失败只记日志、不抛出：中继连不上不该拖垮整个插件（局域网照常可用）。
+    const rc = relayConfig();
+    if (rc.enabled && rc.host && rc.port && rc.token) {
+      void service.startRelay().catch((err) => {
+        logger.warn('dsh-pocket-relay: relay start failed | 中继启动失败: %s', err?.message ?? err);
+      });
+    }
+  }).catch((err) => {
+    logger.error('dsh-pocket-relay: proxy start failed | 代理启动失败: %s', err?.message ?? err);
+  });
+
+  ctx.effect(() => async () => {
+    for (const d of disposers.reverse()) { try { d(); } catch { /* 忽略 */ } }
+    await service.dispose();
+  }, 'dsh-pocket-relay: stop proxy and tunnel');
+}
+
+export { name, inject, readRestartNotice, consumeRestartNotice };

package/lib/ip.mjs

@@ -0,0 +1,11 @@
+// Small shared helpers for the optional LAN IP override.
+
+/** @param {unknown} value
+ *  @returns {boolean} */
+export function isValidIpv4(value) {
+  const m = String(value ?? '').match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  return m !== null && m.slice(1).every((part) => {
+    const n = Number(part);
+    return n >= 0 && n <= 255;
+  });
+}