dsh-mobile-plugin 0.0.0-stage → 0.1.58

package/lib/desktop-half-stats.cjs

@@ -0,0 +1,101 @@
+'use strict';
+
+/**
+ * 「桌面页面里的客户端半边」活体台账。
+ *
+ * 绿点的两条同步通道都是**单向轮询 + 无回执**：客户端半边每 2s 一次 GET/POST，宿主
+ * 只管收下，收没收到、跑没跑，宿主侧一点痕迹都没有。2026-10-10 的绿点不同步故障里，
+ * 正是这一点把排查卡住了 —— 桌面看得见绿点、手机看得见绿点，却没人能说出「桌面那一半
+ * 到底有没有来敲过门」，于是「通道断了」和「通道通了但没清掉」两种可能一直分不开。
+ *
+ * 这里只记**计数与最近时刻**（不含任何会话内容、不含 id），经 `/api/relay/status` 的
+ * `desktopHalf` 字段暴露。三个计数是一组对照：
+ *   - `readReceiptGets`：方向二（手机读过 → 桌面灭灯）的输入，**无条件 2s 轮询**，
+ *     所以它只要在涨，就说明这条 effect 真的在跑；
+ *   - `desktopReadPosts`：方向一（桌面读过 → 手机灭灯）的输出，只在「桌面绿点刚掉出去」
+ *     时才会发，所以它不涨既可能是「没人读过」也可能是「没检测出来」；
+ *   - `desktopViewPosts`：同一个半边、同一套 fetch 的**已知可用**对照组（侧栏展开态），
+ *     它涨而别的两个不涨，等于「半边活着，是那两条 effect 没跑」。
+ *
+ * 刻意不做上限/轮转：三个整数加三个时刻，涨到天荒地老也只是几个数字。
+ */
+
+const state = {
+  /** 宿主进程起算的时刻，便于判断「计数很老」还是「刚重启过」。 */
+  since: Date.now(),
+  readReceiptGets: 0,
+  readReceiptLastAt: 0,
+  desktopReadPosts: 0,
+  desktopReadLastAt: 0,
+  /** 累计上报过的会话 id 数（不是条数：一次 POST 可以带多个 id）。 */
+  desktopReadIds: 0,
+  /** 累计真正清掉的设备维度条目数（0 说明上报的 id 在宿主这边本来就没亮）。 */
+  desktopReadCleared: 0,
+  desktopViewPosts: 0,
+  desktopViewLastAt: 0,
+  /** 客户端半边自检上报：次数 / 最近一次时刻 / 第一次时刻 / 最近一份内容。 */
+  clientReports: 0,
+  clientLastAt: 0,
+  clientSeenAt: 0,
+  client: null,
+};
+
+/** 客户端半边拉了一次已读回执台账（方向二的输入侧）。 */
+function noteReadReceiptGet() {
+  state.readReceiptGets += 1;
+  state.readReceiptLastAt = Date.now();
+}
+
+/** 客户端半边报了一次「桌面读过了」。 */
+function noteDesktopRead({ ids = 0, cleared = 0 } = {}) {
+  state.desktopReadPosts += 1;
+  state.desktopReadLastAt = Date.now();
+  state.desktopReadIds += Number.isFinite(ids) ? ids : 0;
+  state.desktopReadCleared += Number.isFinite(cleared) ? cleared : 0;
+}
+
+/** 客户端半边推了一次桌面侧栏展开态（对照组）。 */
+function noteDesktopViewPost() {
+  state.desktopViewPosts += 1;
+  state.desktopViewLastAt = Date.now();
+}
+
+/**
+ * 客户端半边的**自检上报**：它在页面里能不能看见那两个服务、两条同步各跑了几轮。
+ *
+ * 这是唯一能回答「那半边到底看见了什么」的通道 —— 宿主能数出「它没来敲门」，但数不出
+ * 「它为什么没来」。字段全部白名单收敛到布尔/短字符串/整数：这份体是页面递进来的，
+ * 入口已经限长，这里再挡一道，免得把任意对象灌进 status 视图。
+ */
+const CLIENT_REPORT_KEYS = [
+  'loaded', 'effectUiSession', 'effectSessions',
+  'getUiSession', 'getSessions', 'getRetain', 'injectUiSession', 'injectSessions',
+  'receiptGets', 'readPosts', 'unreadCount', 'lastError',
+];
+
+function noteClientHalf(report) {
+  const clean = {};
+  if (report && typeof report === 'object' && !Array.isArray(report)) {
+    for (const key of CLIENT_REPORT_KEYS) {
+      const value = report[key];
+      if (typeof value === 'boolean' || typeof value === 'number') {
+        clean[key] = typeof value === 'number' && !Number.isFinite(value) ? null : value;
+      } else if (typeof value === 'string') {
+        clean[key] = value.slice(0, 120);
+      }
+    }
+  }
+  state.clientReports += 1;
+  state.clientLastAt = Date.now();
+  state.clientSeenAt = state.clientSeenAt || state.clientLastAt;
+  state.client = clean;
+  return clean;
+}
+
+/** 当前计数副本；status 视图只读它，绝不改。 */
+function snapshot() {
+  const { client, ...counters } = state;
+  return { ...counters, client: client ? { ...client } : null };
+}
+
+module.exports = { noteReadReceiptGet, noteDesktopRead, noteDesktopViewPost, noteClientHalf, snapshot };

package/lib/desktop-view.cjs

@@ -0,0 +1,109 @@
+'use strict';
+
+/**
+ * 桌面端工作区视图快照（侧边栏展开/折叠）的宿主侧存储。
+ *
+ * 桌面端把「哪些工作区分组是展开的」只记在**浏览器 localStorage**
+ * （`dsh.workspace.view.v5`，见 @deepseek-ai/dsh-client-ui-workspace 的
+ * createWorkspaceViewStore → dsh-client-store 的 localStorage 持久化），
+ * 宿主进程、中转和手机都读不到它。插件因此带了一个客户端半边（lib/client.js）：
+ * 桌面页面里每 2 秒读一次这份状态，变了就 POST `/api/relay/desktop-view`，
+ * 由本模块落到 `$DSH_HOME/desktop-view.json`，再由 `/api/mobile/v1/desktop-view`
+ * 下发给 App。
+ *
+ * 语义与桌面端严格一致：`groupExpansion` 以 **workspaceId** 为键（未分组分组固定为
+ * 空串 `''`），只有**显式 true** 表示展开，缺省＝折叠；桌面端在「当前会话所属分组
+ * 还没有记录」时会自动展开它并落盘，所以「当前会话所在工作区」通常也在里面。
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const paths = require('./shared/paths');
+
+/** 单个键（workspaceId）长度上限；超长的一律丢弃（真实 id 只有十几字节）。 */
+const MAX_KEY_LENGTH = 200;
+/** 键数量上限：桌面端可能的分组数远小于它，这里只用于防灌爆。 */
+const MAX_KEYS = 512;
+/** 上报来源标识（桌面端的 localStorage 键名）长度上限。 */
+const MAX_SOURCE_LENGTH = 64;
+
+/** 快照文件：$DSH_HOME/desktop-view.json（DSH_HOME 在调用时解析，便于测试注入）。 */
+function stateFile() {
+  return path.join(paths.dshHome(), 'desktop-view.json');
+}
+
+/** null = 还没有可用快照；否则 { groupExpansion, receivedAt, source }。 */
+let cached = null;
+let loaded = false;
+
+/** 归一化上报的 groupExpansion：只保留布尔值、限长限量；形状不对返回 null。 */
+function normalizeGroupExpansion(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const out = {};
+  let count = 0;
+  for (const rawKey of Object.keys(input)) {
+    const value = input[rawKey];
+    if (typeof value !== 'boolean') continue;
+    const key = rawKey.trim();
+    if (key.length > MAX_KEY_LENGTH) continue;
+    out[key] = value;
+    count += 1;
+    if (count >= MAX_KEYS) break;
+  }
+  return out;
+}
+
+function load() {
+  if (loaded) return cached;
+  loaded = true;
+  try {
+    const raw = JSON.parse(fs.readFileSync(stateFile(), 'utf8'));
+    const groupExpansion = normalizeGroupExpansion(raw && raw.groupExpansion);
+    if (!groupExpansion) {
+      cached = null;
+      return cached;
+    }
+    cached = {
+      groupExpansion,
+      receivedAt: Number.isFinite(raw && raw.receivedAt) ? raw.receivedAt : 0,
+      source: typeof (raw && raw.source) === 'string' ? raw.source : '',
+    };
+  } catch {
+    // 文件不存在 / 损坏都按「桌面端还没上报过」处理：App 侧退回折叠缺省。
+    cached = null;
+  }
+  return cached;
+}
+
+/** 当前快照的副本；从未收到过上报时返回 null。 */
+function snapshot() {
+  const value = load();
+  if (!value) return null;
+  return {
+    groupExpansion: { ...value.groupExpansion },
+    updatedAt: value.receivedAt,
+    source: value.source,
+  };
+}
+
+/** 记录一次桌面页面上报；非法形状抛错（调用方回 400）。返回落盘后的快照。 */
+function update(input, now = Date.now()) {
+  const groupExpansion = normalizeGroupExpansion(input && input.groupExpansion);
+  if (!groupExpansion) throw new Error('groupExpansion 必须是对象');
+  const rawSource = input && (typeof input.source === 'string' ? input.source : input.storageKey);
+  const next = {
+    groupExpansion,
+    receivedAt: now,
+    source: typeof rawSource === 'string' ? rawSource.slice(0, MAX_SOURCE_LENGTH) : '',
+  };
+  const file = stateFile();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(next, null, 2), { mode: 0o600 });
+  fs.renameSync(tmp, file);
+  cached = next;
+  loaded = true;
+  return snapshot();
+}
+
+module.exports = { stateFile, snapshot, update };

package/lib/host-guard.cjs

@@ -0,0 +1,230 @@
+'use strict';
+
+/**
+ * 宿主进程级错误边界（crash guard）。
+ *
+ * ## 为什么要这个模块
+ *
+ * DSH 宿主是**长驻进程**：装在桌面版 DSH 里（macOS/Windows），也被 systemd 以
+ * `Restart=on-failure` 托管（服务器无头实例）。任何一次真正逃逸到事件循环的异常都会
+ * 带走整个 DSH——用户那边表现为「DSH 崩了/插件把 DSH 搞挂了」，而且桌面端连个
+ * 插件隔离层都没有，插件的 bug 直接就是宿主的 bug。
+ *
+ * 路由层其实已经被兜住了（`dsh-host-webserver` 给每个 handler 挂了 `.catch`），
+ * 但**进程层那层兜底在本插件里是完全没有的**：`grep -rn "unhandledRejection\|uncaughtException"`
+ * 在整个 dsh-mobile-plugin/ 与 dsh-mobile-server/ 里零命中。缺口正在于：
+ *
+ *  1. **游离的 Promise 拒绝**。Node 15+ 起 `unhandledRejection` 默认行为是 *throw*，
+ *     也就是**杀进程**。插件里凡是 `void someAsync()`（fire-and-forget）的地方，
+ *     一个没 catch 的 reject 就等于一次 DSH 崩溃。这类点极多：自动归档轮询、
+ *     镜像推送、隧道重连、遥测上报……任意一个后台任务炸一次就够了。
+ *  2. **第三方回调里抛错**。宿主事件流、WS 回调、timer 回调抛出的异常没有 try 包裹，
+ *     直接升级为 `uncaughtException`。
+ *
+ * ## 策略：记录 + 保持存活，连续 5 次才退出
+ *
+ * 单个异常通常不致命（最常见的是"某个后台任务这一次没成"）。一刀切退出等于把
+ * 偶发故障变成必然崩溃；一味吞掉又会掩盖真正的崩溃循环。所以取中间值：
+ *
+ *  - **记录**：每一条都进内存账本，带时间/类型/消息/是否致命，供 `status()` 暴露
+ *    （「及时阻止」的前提是能看见）；
+ *  - **保持存活**：`unhandledRejection` 与单次 `uncaughtException` 都只记录并继续跑，
+ *    不退出。这把「插件的偶发 bug」和「DSH 崩溃」解耦了；
+ *  - **熔断**：只有 `uncaughtException` 计入致命计数，且**必须落在时间窗内**。
+ *    超过 `windowMs` 没再犯就重新计数——这样捕获的是「崩溃循环」（秒级连炸），
+ *    而不是「跑三个月偶发 5 次」的正常长驻。真正熔断时再主动退出，交给
+ *    `Restart=on-failure` / 桌面端重启拉起，拿到一个干净的新进程。
+ *
+ * ## 为什么把状态机和进程接线拆开
+ *
+ * `createGuard()` 是纯状态机（时间/日志/退出都注入），测试可以完全确定性地驱动它，
+ * 不必真的往 `process` 上挂处理器、也不会在跑测试时把测试进程搞死；
+ * `installProcessGuard()` 才是那层薄薄的进程接线。这个拆分是本模块能被守卫测试
+ * 覆盖的前提。
+ */
+
+const FATAL_FAULT_COUNT = 5;
+const CONSECUTIVE_FAULT_WINDOW_MS = 60 * 1000;
+const FAULT_LEDGER_LIMIT = 50;
+const FATAL_EXIT_CODE = 1;
+
+/** 把任意 throw 出来的值压成一行可读文本。 */
+function describeError(err) {
+  if (err === null || err === undefined) return String(err);
+  if (err instanceof Error) return err.stack || `${err.name}: ${err.message}`;
+  if (typeof err === 'object') {
+    try { return JSON.stringify(err); } catch { return Object.prototype.toString.call(err); }
+  }
+  return String(err);
+}
+
+/**
+ * 建立一个错误边界状态机（不碰 process）。
+ *
+ * @param {object}   [options]
+ * @param {number}   [options.fatalCount]     窗口内多少个 uncaughtException 判定致命，缺省 5
+ * @param {number}   [options.windowMs]       「连续」的时间窗，缺省 60s
+ * @param {number}   [options.ledgerLimit]    账本上限，缺省 50
+ * @param {() => number} [options.now]        注入时钟，便于测试
+ * @param {(line: string) => void} [options.log] 注入日志，便于测试
+ * @param {(code: number) => void} [options.exit] 注入退出，便于测试
+ * @returns {{handleUncaughtException: Function, handleUnhandledRejection: Function,
+ *            record: Function, faults: Function, stats: Function, clear: Function,
+ *            isFatal: Function}}
+ */
+function createGuard(options = {}) {
+  const fatalCount = options.fatalCount ?? FATAL_FAULT_COUNT;
+  const windowMs = options.windowMs ?? CONSECUTIVE_FAULT_WINDOW_MS;
+  const ledgerLimit = options.ledgerLimit ?? FAULT_LEDGER_LIMIT;
+  const now = options.now ?? (() => Date.now());
+  const exit = options.exit ?? ((code) => process.exit(code));
+  const log = options.log ?? ((line) => { process.stderr.write(`${line}\n`); });
+
+  /** @type {{at: number, kind: string, message: string, fatal: boolean}[]} */
+  let ledger = [];
+  let consecutive = 0;
+  let lastFatalKindAt = 0;
+  let fatalEver = false;
+
+  function record(kind, message, fatal) {
+    // 满了就丢最旧的：账本是用来回答「刚才发生了什么」，不是完整审计日志。
+    if (ledger.length >= ledgerLimit) ledger.shift();
+    ledger.push({ at: now(), kind, message, fatal: Boolean(fatal) });
+  }
+
+  return {
+    /**
+     * `process.on('uncaughtException')` 的处理函数。
+     * 记一笔，计入连续计数，够数才退出。
+     */
+    handleUncaughtException(err) {
+      const at = now();
+      // 「连续」= 距离上一个致命类异常没超过窗口。超窗则重新从 1 数，
+      // 这样零星故障不会累加到熔断，只有崩溃循环才会。
+      consecutive = (lastFatalKindAt !== 0 && at - lastFatalKindAt <= windowMs) ? consecutive + 1 : 1;
+      lastFatalKindAt = at;
+      const fatal = consecutive >= fatalCount;
+      if (fatal) fatalEver = true;
+      record('uncaughtException', describeError(err), fatal);
+      log(`[dsh-mobile-plugin] 未捕获异常（连续 ${consecutive}/${fatalCount}${fatal ? '，判定崩溃循环，将退出' : ''}）: ${describeError(err)}`);
+      if (fatal) exit(FATAL_EXIT_CODE);
+      return fatal;
+    },
+
+    /**
+     * `process.on('unhandledRejection')` 的处理函数。
+     *
+     * 刻意**不计入熔断**：游离 reject 在长驻服务里非常常见（一次后台推送失败就
+     * 一个），把它们累加成退出条件会制造新的崩溃源。挂上处理器本身就已经把
+     * Node 的默认「throw 并杀进程」改成了「记录并继续」。
+     */
+    handleUnhandledRejection(reason) {
+      record('unhandledRejection', describeError(reason), false);
+      log(`[dsh-mobile-plugin] 未处理的 Promise 拒绝（已忽略）: ${describeError(reason)}`);
+      return false;
+    },
+
+    /** 手动记一条非致命故障（例如某个 handler 自己 catch 后上报的）。 */
+    recordFault(kind, message) {
+      record(kind, String(message), false);
+      return false;
+    },
+
+    /** 账本快照（按时间正序）。 */
+    faults() { return ledger.slice(); },
+
+    /** 供 `status()` 暴露的汇总。 */
+    stats() {
+      return {
+        total: ledger.length,
+        consecutive,
+        lastAt: ledger.length ? ledger[ledger.length - 1].at : 0,
+        fatalCount,
+        windowMs,
+        fatal: fatalEver,
+      };
+    },
+
+    /** 清空账本与计数（测试用 / 运维排障后复位）。 */
+    clear() { ledger = []; consecutive = 0; lastFatalKindAt = 0; fatalEver = false; },
+
+    /** 当前是否已经熔断过。 */
+    isFatal() { return fatalEver; },
+  };
+}
+
+/** @type {ReturnType<typeof createGuard>|null} 已安装的边界，供 safeAsync 复用。 */
+let installed = null;
+
+/**
+ * 把状态机接到真实 process 上。**必须在任何业务代码之前调用**，
+ * 否则启动阶段的游离 reject 仍然会按 Node 默认行为杀进程。
+ *
+ * @param {object} [options] 同 createGuard，另可传 `target`（默认 process）便于测试
+ * @returns {{guard: ReturnType<typeof createGuard>, uninstall: () => void}}
+ */
+function installProcessGuard(options = {}) {
+  const { target = process, ...rest } = options;
+  const guard = rest.guard ?? createGuard(rest);
+  const onUncaught = (err) => { guard.handleUncaughtException(err); };
+  const onRejection = (reason) => { guard.handleUnhandledRejection(reason); };
+  target.on('uncaughtException', onUncaught);
+  target.on('unhandledRejection', onRejection);
+  installed = guard;
+  return {
+    guard,
+    uninstall() {
+      target.off('uncaughtException', onUncaught);
+      target.off('unhandledRejection', onRejection);
+      if (installed === guard) installed = null;
+    },
+  };
+}
+
+/** 取当前已安装的边界（没装返回 null）。 */
+function activeGuard() { return installed; }
+
+/**
+ * 把一个可能抛/可能 reject 的调用包成「永不把异常带出去」的函数。
+ *
+ * 这是本模块想复用的那一块：插件里大量 fire-and-forget 的调用点（自动归档轮询、
+ * 镜像推送、遥测、隧道重连……）都可以直接套一层，再也不必各自 try/catch，
+ * 也再也不会有一处忘了 catch 就把 DSH 带走。
+ *
+ * @param {Function} fn                 原始函数
+ * @param {string}   [label]            出错时用于定位的来源名
+ * @param {ReturnType<typeof createGuard>|null} [guard] 指定边界，缺省用已安装的那个
+ * @returns {(...args: any[]) => Promise<void>} 永不 reject
+ */
+function safeAsync(fn, label = 'anonymous', guard = null) {
+  return function guarded(...args) {
+    const report = (err) => {
+      const g = guard ?? installed;
+      const message = `${label}: ${describeError(err)}`;
+      if (g) g.recordFault('safeAsync', message);
+      else process.stderr.write(`[dsh-mobile-plugin] 未保护的异步调用 ${message}\n`);
+    };
+    try {
+      return Promise.resolve(fn(...args)).then(
+        () => undefined,
+        (err) => { report(err); },
+      );
+    } catch (err) {
+      // 同步抛也要吞：调用点写的是 fire-and-forget，不该因为参数错就把进程带走。
+      report(err);
+      return Promise.resolve();
+    }
+  };
+}
+
+module.exports = {
+  createGuard,
+  installProcessGuard,
+  activeGuard,
+  safeAsync,
+  describeError,
+  FATAL_FAULT_COUNT,
+  CONSECUTIVE_FAULT_WINDOW_MS,
+  FAULT_LEDGER_LIMIT,
+  FATAL_EXIT_CODE,
+};

package/lib/host-patches.cjs

@@ -0,0 +1,46 @@
+'use strict'
+
+/**
+ * 无头宿主拼 patch 层时的两处修正。抽成独立文件是为了能直接测：host.js 一 import
+ * 就 `boot()` 整个 Cordis 宿主，测试碰不得。
+ */
+
+/**
+ * 摘掉「按裸包名挂载本插件」的 patch 行。
+ *
+ * `cordis.patch.yml` 里有一行 `- insert: [{ id: dsh-mobile, name: 'dsh-mobile-plugin' }]`，
+ * 那是给**桌面端**用的：DSH 的插件管理器把这个包装进
+ * `~/.dsh/profiles/<profile>/node_modules`，Loader 从那里按包名解析得到 `lib/index.js`。
+ *
+ * 无头宿主没有那次安装 —— 插件**就是** Loader 正在跑的那个包，没人把它放进
+ * `node_modules` —— 于是这一行解析不到。而 loader 对解析失败**不是**留一条警告，是整棵树
+ * 加载失败：
+ *
+ *   dsh-mobile-plugin: boot failed: Error: dsh-mobile-plugin: plugin tree failed to load:
+ *   failed to apply loader entry include (cordis:include): failed to import loader entry
+ *   dsh-mobile (dsh-mobile-plugin): Cannot find package 'dsh-mobile-plugin'
+ *     code: 'ERR_MODULE_NOT_FOUND'
+ *
+ * （实测：服务器宿主从引入这一行的提交起就再也起不来了。）宿主自己用绝对路径另插一行
+ * `mobile-api` 挂载本插件，所以这一行在这里只有害处。
+ *
+ * 不改 `cordis.patch.yml` 本身：桌面端还要靠它。只在无头宿主装载前从内存里摘掉。
+ *
+ * @param {Array} patches 已加载的 patch 层（loadOverlayPatches 的返回值）
+ * @param {string} binName 本插件的包名
+ * @returns {Array} 新数组；空的 insert 壳会被整条去掉
+ */
+function dropBareNameSelfMounts(patches, binName) {
+  return patches.flatMap((patch) => {
+    if (!patch || !Array.isArray(patch.insert)) return [patch]
+    const kept = patch.insert.filter((row) => !(row && typeof row === 'object' && row.name === binName))
+    if (kept.length === patch.insert.length) return [patch]
+    const rest = { ...patch }
+    delete rest.insert
+    // 整条 patch 就只剩这一行时，连壳一起去掉（空 insert 合法但没有意义）。
+    if (kept.length > 0) return [{ ...rest, insert: kept }]
+    return Object.keys(rest).length > 0 ? [rest] : []
+  })
+}
+
+module.exports = { dropBareNameSelfMounts }

package/lib/http/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/lib/http/routing.js

@@ -0,0 +1,84 @@
+'use strict';
+
+/**
+ * 插件 HTTP 路由基建：控制面与移动端两套守卫的共用地基。
+ *
+ * 这些函数此前是 lib/index.js 里的局部闭包，紧挨着 65 条路由注册写在一起。它们
+ * 本身是纯函数（只依赖 req/res），却因为住在 apply() 里而无法单测——而这几条守卫
+ * 恰好是最该有测试的地方：它们挡的是「谁能调控制面」「谁能调移动端」，写错一行的
+ * 后果是鉴权被绕过而不是某个页面显示不出来。
+ *
+ * 抽出来单独放一个文件是为了让它们能被直接 require 并喂假 req/res 测试。抽出后
+ * 两套守卫并排放在一个文件里，肉眼就能对照出「控制面多挡了跨站与 method，移动端只
+ * 挡 token」这个刻意的不对称。
+ */
+
+const { sendJson, readJsonBody } = require('../shared/http-util');
+
+// Relay pairing cookies and instance headers are routing credentials only;
+// never allow them to reach the local control plane.
+const remoteRelayRequest = (req) => Boolean(
+  (typeof req.headers['x-dsh-instance'] === 'string' && req.headers['x-dsh-instance'])
+    || /(?:^|;\s*)dsh_(?:pair|lan)=/.test(String(req.headers.cookie || '')),
+)
+
+// Cross-site guard for the control plane.
+//
+// `localOnly` alone only rejected requests that carried relay routing
+// credentials, so a plain cross-site `GET /api/relay/revoke-all` from any page
+// the user had open still executed (the routes had no method check either).
+// Rejecting cross-site fetches and pinning each route to one method closes
+// that: a control-plane call now has to be a same-origin top-level/`same-origin`
+// request, and it has to use the documented verb.
+const crossSiteRequest = (req) => {
+  if (String(req.headers['sec-fetch-site'] || '').toLowerCase() === 'cross-site') return true
+  const origin = req.headers.origin
+  if (typeof origin !== 'string' || !origin) return false
+  const host = req.headers.host
+  if (typeof host !== 'string' || !host) return true
+  try { return new URL(origin).host !== host } catch { return true }
+}
+
+// `method` 可以是单个方法名，也可以是方法名数组（同一个路径上挂 GET+POST，
+// 例如 /api/relay/desktop-view 既读快照又收回传）。单方法时的 405 文案保持不变。
+const localOnly = (method, handler) => async (req, res) => {
+  if (remoteRelayRequest(req)) return sendJson(res, 403, { ok: false, error: { code: 'local_only', message: '控制面仅允许本机访问' } })
+  if (crossSiteRequest(req)) return sendJson(res, 403, { ok: false, error: { code: 'cross_site', message: '控制面拒绝跨站请求' } })
+  const allowed = Array.isArray(method) ? method : [method]
+  const actual = String(req.method || 'GET').toUpperCase()
+  if (!allowed.includes(actual)) {
+    const label = Array.isArray(method) ? method.join(' / ') : method
+    return sendJson(res, 405, { ok: false, error: { code: 'method-not-allowed', message: `仅支持 ${label}` } })
+  }
+  return handler(req, res)
+}
+
+const readJson = (req) => readJsonBody(req, 256 * 1024).then(body => body || {})
+
+/**
+ * 移动端路由守卫：token + 把 handler 抛出的异常统一收成 500 信封。
+ *
+ * 与 localOnly 的不对称是刻意的：移动端请求本来就要从公网进来，跨站不是它的风险；
+ * 它的风险是「没带 token 也能读别人的会话」，所以只校验 token。
+ *
+ * @param {object} ctx 插件 ctx，透传给 handler
+ * @param {(req: object) => boolean} authorized 移动 token 校验，由调用方注入
+ * @returns {(handler: (ctx: object, req: object, res: object) => Promise<unknown>) => (req: object, res: object) => Promise<unknown>}
+ */
+const createGuarded = (ctx, authorized) => (handler) => async (req, res) => {
+  if (!authorized(req)) return sendJson(res, 401, { ok: false, error: { code: 'unauthorized', message: '缺少或无效的移动 token' } })
+  try { await handler(ctx, req, res) } catch (error) {
+    sendJson(res, 500, { ok: false, error: { code: 'internal', message: String(error?.message || error) } })
+  }
+}
+
+module.exports = {
+  remoteRelayRequest,
+  crossSiteRequest,
+  localOnly,
+  readJson,
+  createGuarded,
+  // shared/http-util 重出一次：这个文件里的守卫全都用它写响应，
+  // 让「路由基建」成为一处完整的地基，而不是散在三个文件里各写一半。
+  sendJson,
+};