qq-bot-roost 0.8.8 → 0.8.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qq-bot-roost",
-  "version": "0.8.8",
+  "version": "0.8.9",
   "type": "module",
   "description": "栖 Roost：零依赖的 QQ 官方机器人框架，填 AppID/AppSecret 即连，插件可写任意语言",
   "license": "SEE LICENSE IN LICENSE",
@@ -36,7 +36,10 @@
     "create": "node scripts/create-plugin.mjs",
     "test:plugin": "node scripts/test-plugin.mjs",
     "live": "node scripts/live-test.mjs",
-    "market:index": "node scripts/build-market-index.mjs"
+    "market:index": "node scripts/build-market-index.mjs",
+    "sums": "node scripts/build-sums.mjs",
+    "sums:check": "node scripts/build-sums.mjs --check",
+    "sums:verify": "node scripts/build-sums.mjs --verify"
   },
   "author": {
     "name": "倦飞之鸟"

package/src/fsutil.js

@@ -23,7 +23,20 @@ export async function writeJsonAtomic(file, data) {
   const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
   const text = `${JSON.stringify(data, null, 2)}\n`;
   try {
-    await fs.writeFile(tmp, text, 'utf8');
+    /**
+     * `mode: 0o600` —— 只有属主能读写。
+     *
+     * 这些 JSON 里有 `config/bot.json`、`config/bots/<id>.json`，都带明文
+     * AppSecret；还有权限表、群档案。Linux 默认 umask 022 下新建文件是 644，
+     * 同机其他用户直接 `cat` 就能拿到机器人凭证。
+     *
+     * 注意两点：
+     *   - mode 只在**创建**时生效，而这里的 tmp 每次都是新文件，所以一定吃到
+     *   - rename 会保留临时文件的权限，覆盖掉旧文件原来的 644 —— 也就是说
+     *     用户只要保存过一次配置，老文件的权限就被修正了，不需要单独做迁移
+     *   - Windows 上 mode 被忽略，不影响运行
+     */
+    await fs.writeFile(tmp, text, { encoding: 'utf8', mode: 0o600 });
     await fs.rename(tmp, file);
   } catch (e) {
     await fs.rm(tmp, { force: true }).catch(() => {});

package/src/hashdir.js

@@ -77,16 +77,24 @@ async function collect(root) {
 }
 
 /**
- * 算目录的内容指纹。
+ * 按给定的相对路径清单算指纹。
  *
- * @param {string} dir 插件目录
+ * 为什么要单独一个入口：仓库根目录里有 `data/`、`logs/`、`config/`、`plugins/`
+ * 这些**不会被 tarball 打包**的东西，直接 `hashDir(ROOT)` 会把它们算进去，
+ * 跟「解包后的 tarball」永远对不上。
+ *
+ * 所以发布流程用 `git ls-files` 拿到「真正会被打进包的文件」，再喂给这里；
+ * 更新校验则用 `hashDir(解包目录)`。两边必须用同一套拼接方式，否则校验必失败。
+ *
+ * @param {string} root 根目录
+ * @param {string[]} rels 相对路径（`/` 分隔）；内部会去重并排序，顺序无关
  * @returns {Promise<string>} 64 位十六进制
  */
-export async function hashDir(dir) {
-  const files = await collect(dir);
+export async function hashFileList(root, rels) {
+  const files = [...new Set(rels)].sort();
   const h = crypto.createHash('sha256');
   for (const rel of files) {
-    const buf = normalize(await fs.readFile(path.join(dir, rel)));
+    const buf = normalize(await fs.readFile(path.join(root, rel)));
     h.update(rel);
     h.update('\0');
     h.update(String(buf.length));
@@ -96,3 +104,38 @@ export async function hashDir(dir) {
   }
   return h.digest('hex');
 }
+
+/**
+ * 算目录的内容指纹。
+ *
+ * @param {string} dir 插件目录
+ * @param {{exclude?: string[], only?: string[]}} [opts]
+ *   - `exclude`：精确匹配要跳过的相对路径（如 `SHA256SUMS` 这种会自引用的文件）
+ *   - `only`：只算这些路径（`src` 这类目录前缀，或 `package.json` 这类文件名）。
+ *     用途：GitHub 的 tarball 是**全量**（含 .github、scripts、sdk），
+ *     而 Gitee 源只拉会被更新覆盖的那几个条目，两边目录内容天生不同。
+ *     用 `only` 把范围收窄到「真正会被替换的代码」，两边才算得出同一个值。
+ * @returns {Promise<string>} 64 位十六进制
+ */
+export async function hashDir(dir, opts = {}) {
+  /**
+   * 根目录不存在时必须报错，**不能静默返回空哈希**。
+   *
+   * `collect()` 里对每个目录都有 try/catch（遍历时子目录读不到要跳过），
+   * 但连根目录都不存在时它也会安静地返回空数组，算出来就是
+   * `e3b0c442…`（空字符串的 sha256）—— 那是一个**合法值**，会像真指纹一样
+   * 参与比对，现象是「内容全变了」而不是「路径写错了」，排查时非常误导。
+   */
+  const st = await fs.stat(dir).catch(() => null);
+  if (!st?.isDirectory()) throw new Error(`算指纹失败：目录不存在或不是目录 —— ${dir}`);
+
+  const skip = new Set(opts.exclude ?? []);
+  const only = (opts.only ?? []).map((p) => String(p));
+  let files = (await collect(dir)).filter((rel) => !skip.has(rel));
+  if (only.length) {
+    files = files.filter((rel) =>
+      only.some((p) => rel === p || rel.startsWith(p.endsWith('/') ? p : `${p}/`)),
+    );
+  }
+  return hashFileList(dir, files);
+}

package/src/mirror.js

@@ -86,9 +86,36 @@ const AUTO_TTL = 10 * 60_000;
 export function configureMirror(globalCfg) {
   const n = globalCfg?.network ?? {};
   const id = String(n.mirror ?? 'auto').trim() || 'auto';
+
+  /**
+   * 自定义下载前缀必须是 https。
+   *
+   * 这个值会被直接拼在 tarball 地址前面（见 applyMirror），而这个项目**更新包
+   * 没有内容校验**（updater.js 的 expectSha256 恒为 null）。也就是说：
+   * 填一个 http 地址，等于让链路上的任何人决定你下一版跑什么代码。
+   *
+   * 不合法就退回默认（不用它），而不是抛错 —— 配置文件写错了不该让整个框架起不来。
+   */
+  let custom = String(n.mirrorCustom ?? '').trim();
+  if (custom) {
+    let u = null;
+    try {
+      u = new URL(custom.includes('://') ? custom : `https://${custom}`);
+    } catch {
+      u = null;
+    }
+    if (!u || u.protocol !== 'https:') {
+      log.warn(
+        `network.mirrorCustom 必须是 https:// 开头，已忽略：${custom}\n` +
+          '  （自定义下载源会决定你下一版跑什么代码，明文 http 等于把它交给链路上的任何人）',
+      );
+      custom = '';
+    }
+  }
+
   current = {
     id: PRESETS.some((p) => p.id === id) ? id : 'auto',
-    custom: String(n.mirrorCustom ?? '').trim(),
+    custom,
     // Gitee 私人令牌：选填。公开仓库匿名也能用，填了只是把 API 配额提上去
     giteeToken: String(n.giteeToken ?? '').trim(),
   };
@@ -160,6 +187,17 @@ export function applyMirror(url, preset, custom = current.custom) {
     // 允许用户只填域名，自动补协议和结尾斜杠
     let b = base.trim();
     if (!/^https?:\/\//i.test(b)) b = `https://${b}`;
+    /**
+     * 自定义前缀必须是 https —— 这里再挡一道。
+     *
+     * configureMirror 已经校验过配置里的值，但 `probeMirrors` 的 custom 是
+     * 面板请求体直接传进来的（「测速」按钮），不经过 configureMirror。
+     * 不合法就**退回原始地址**，不要拼一个 http 前缀上去。
+     */
+    if (preset.kind === 'custom' && !/^https:\/\//i.test(b)) {
+      log.warn(`自定义下载源必须是 https，已忽略：${base}`);
+      return url;
+    }
     if (!b.endsWith('/')) b += '/';
     // 已经是这个前缀了就别套第二次
     if (url.startsWith(b)) return url;

package/src/update-scope.js

@@ -0,0 +1,28 @@
+/**
+ * 更新会替换的代码条目（单一来源）
+ * ================================
+ *
+ * 三处共用：
+ *   1. `updater.js` 备份与替换（rsync 式覆盖，绝不碰 config/data/logs/plugins）
+ *   2. `gitee.js` 的前缀过滤（Gitee 没有 archive 直链，只能按清单逐个拉）
+ *   3. `scripts/build-sums.mjs` 算内容指纹的范围
+ *
+ * 为什么指纹也按这个范围算：GitHub 的 tarball 是**全量**（还带 .github、
+ * scripts、sdk、types），而 Gitee 源只拉下面这几个条目。如果指纹按「包里的
+ * 全部文件」算，两条下载路径永远对不上 —— 一边写死校验失败，一边等于没校验。
+ *
+ * 改这个清单要连带重跑 `npm run sums`，否则已发布的指纹会全部失配。
+ */
+export const CODE_ENTRIES = [
+  'src',
+  'web',
+  'test',
+  'docs',
+  'package.json',
+  'README.md',
+  'LICENSE',
+  'start.bat',
+];
+
+/** 绝对不能删/覆盖的目录（双保险） */
+export const PROTECTED_ENTRIES = new Set(['config', 'data', 'logs', 'plugins', 'node_modules', '.git']);

package/src/updater.js

@@ -20,6 +20,8 @@ import { createLogger } from './logger.js';
 import { fetchAndExtract } from './tarball.js';
 import { fetchViaMirror, currentMirror } from './mirror.js';
 import { fetchGiteeTree, detectGiteeRef, giteeRawUrl } from './gitee.js';
+import { hashDir } from './hashdir.js';
+import { CODE_ENTRIES, PROTECTED_ENTRIES as PROTECTED } from './update-scope.js';
 import { ROOT } from './config.js';
 
 const log = createLogger('update');
@@ -27,11 +29,11 @@ const log = createLogger('update');
 /** 仓库信息。换成自己的 fork 就改这里 */
 const REPO = 'tdcq9594/qq-bot-roost';
 
-/** 允许被更新覆盖的顶层条目。**用户数据一个都不在里面** */
-const CODE_ENTRIES = ['src', 'web', 'test', 'docs', 'package.json', 'README.md', 'LICENSE', 'start.bat'];
-
-/** 绝对不能删的目录，双保险 */
-const PROTECTED = new Set(['config', 'data', 'logs', 'plugins', 'node_modules', '.git']);
+/**
+ * 允许被更新覆盖的顶层条目、以及绝对不能碰的目录，都在 ./update-scope.js。
+ * 内容指纹用的是**同一份清单**——GitHub tarball 是全量、Gitee 只拉这几个条目，
+ * 范围不一致的话两条下载路径算出来的指纹永远对不上。
+ */
 
 /**
  * Gitee 源下拉取的文件范围：只拉会被更新覆盖的代码条目。
@@ -100,9 +102,58 @@ async function updatedButNotRestarted() {
  * 包一层而不是往 checkUpdate 里塞：里面有好几个返回分支（Gitee /
  * 主站 302 / API 兜底 / 404 / 失败），每个都手写一遍 needsRestart 迟早漏一个。
  */
+/**
+ * 拉 SHA256SUMS，得到「版本 → 内容指纹」的映射。
+ *
+ * 两个源都试：GitHub raw（经下载源改写）和 Gitee raw。任何一边拿到都行，
+ * 因为指纹是「代码内容」的，与从哪个源下载无关。
+ *
+ * @returns {Promise<Map<string,string>>} 版本号 → 64 位十六进制
+ */
+async function fetchSumsMap() {
+  const urls = [
+    `https://raw.githubusercontent.com/${REPO}/master/SHA256SUMS`,
+    `https://gitee.com/${REPO}/raw/master/SHA256SUMS`,
+  ];
+  for (const u of urls) {
+    try {
+      const res = await fetchViaMirror(u, {
+        headers: { 'User-Agent': 'qq-bot-roost-updater' },
+        signal: AbortSignal.timeout(8000),
+      });
+      if (!res.ok) continue;
+      const text = await res.text();
+      const map = new Map();
+      for (const line of text.split(/\r?\n/)) {
+        const m = /^([a-f0-9]{64})\s+v?([0-9][\w.+-]*)$/i.exec(line.trim());
+        if (m) map.set(m[2].replace(/^v/i, ''), m[1].toLowerCase());
+      }
+      if (map.size) return map;
+    } catch {
+      // 换下一个源
+    }
+  }
+  return new Map();
+}
+
+/**
+ * 查某个版本的内容指纹。拿不到返回 null —— 真正的拒绝发生在 applyUpdate，
+ * 因为「只检查不安装」时面板仍应正常显示有新版本，只是点更新会失败。
+ */
+async function fetchTreeSha256(version) {
+  try {
+    const map = await fetchSumsMap();
+    return map.get(String(version).replace(/^v/, '')) ?? null;
+  } catch {
+    return null;
+  }
+}
+
 export async function checkUpdate() {
   const needsRestart = await updatedButNotRestarted();
   const r = await checkUpdateCore();
+  // 有新版本才值得多跑一次网络请求
+  if (r?.ok && r.hasUpdate) r.treeSha256 = await fetchTreeSha256(r.latest);
   return { ...r, needsRestart };
 }
 
@@ -442,6 +493,37 @@ async function applyUpdateOnce(info) {
       throw new Error('下载的包里没有 src/main.js，不是合法的框架包，已中止');
     });
 
+    /**
+     * 内容指纹校验 —— **必须放在备份和替换之前**。
+     *
+     * 这一步失败就等于什么都没发生过：文件没动、备份也没建。
+     *
+     * 为什么必须严格：更新会直接覆盖 `src/`、`web/` 这些要执行的代码。
+     * 只要能改掉下载地址（自定义镜像、上游仓库被入侵、链路劫持），
+     * 就能决定用户下一版跑什么。指纹对不上就说明「下载到的东西不是作者发的」。
+     *
+     * 为什么没有指纹也要拒绝：留一个「没指纹就放行」的口子，攻击者只要把
+     * SHA256SUMS 里那条删掉或让仓库回到没有该文件的形态就能绕过。
+     * 代价是发布流程必须每版都带指纹 —— 这由 CI 的 `npm run sums:check` 守着。
+     */
+    if (!rel.treeSha256) {
+      throw new Error(
+        `v${rel.latest} 没有发布内容指纹（SHA256SUMS 里查不到），已拒绝自动更新。\n` +
+          '这不是你的网络问题：作者这一版可能漏了生成指纹。\n' +
+          '可以手动到 GitHub Releases 下载安装，或等下一版。你的代码没有任何改动。',
+      );
+    }
+    const gotHash = await hashDir(workDir, { only: CODE_ENTRIES });
+    if (gotHash !== rel.treeSha256) {
+      throw new Error(
+        `更新内容校验失败，已中止（你的代码没有任何改动）。\n` +
+          `  期望 ${rel.treeSha256}\n` +
+          `  实际 ${gotHash}\n` +
+          '可能是下载源被篡改，或者发布时改了代码却忘了重跑 npm run sums。',
+      );
+    }
+    log.info(`内容指纹校验通过（${gotHash.slice(0, 12)}…）`);
+
     // 备份现有代码
     await fs.mkdir(backupDir, { recursive: true });
     for (const name of CODE_ENTRIES) {

package/src/web/server.js

@@ -43,6 +43,19 @@ import {
 const log = createLogger('webui');
 const WEB_ROOT = path.join(ROOT, 'web');
 
+/**
+ * 进程实例标识。
+ *
+ * 面板用它判断「服务是不是重启过」。重启意味着两件事同时发生：
+ *   - 页面令牌全部重新生成 → 已打开的插件页 iframe 手里拿的全是废牌，
+ *     之后每个请求都会被判成跨站（403）
+ *   - 会话 Cookie 全部失效
+ *
+ * 前端拿到这个值一变化，就可以立刻重载 iframe，而不是干等兜底轮询
+ * （用户会看到一条红色报错闪过，体验很差）。
+ */
+const PROCESS_STARTED_AT = Date.now();
+
 /**
  * 主面板的 CSP。
  *
@@ -433,6 +446,11 @@ export async function startWebServer({
             : people.find((p) => p.openid === c.id)?.name ?? '',
       }));
     }
+    /**
+     * 进程实例标识：前端一看到它变了就知道服务重启过，
+     * 页面令牌和会话都已作废，需要立刻重载插件页而不是等下轮轮询。
+     */
+    snap.instanceId = `${process.pid}-${PROCESS_STARTED_AT}`;
     return snap;
   };
 
@@ -884,11 +902,25 @@ export async function startWebServer({
          */
         if (req.method === 'OPTIONS') {
           const origin = String(req.headers.origin || '');
+          /**
+           * 允许的头**回显浏览器要的那个**，不写死。
+           *
+           * 踩过的坑：原来写死 `Content-Type`，看着没错，但浏览器报的是
+           * 「Request header field content-type is not allowed by
+           * Access-Control-Allow-Headers in preflight response」。
+           * 回显 `Access-Control-Request-Headers` 就永远不会对不上 ——
+           * 它问什么我给什么，反正是插件页自己的只读请求。
+           *
+           * **不要加 `Access-Control-Max-Age`**：加了浏览器会把这次预检结果
+           * 缓存好几分钟，一旦某次响应是错的（或者服务端刚改过逻辑），
+           * 后面再改代码都没用 —— 浏览器压根不会重新来问，只会一直报同一个错，
+           * 排查时会以为是代码没生效。本地面板的预检几乎没有开销，不值得缓存。
+           */
+          const wantHeaders = String(req.headers['access-control-request-headers'] || '');
           res.writeHead(204, {
             ...(origin === 'null' ? { 'Access-Control-Allow-Origin': 'null', Vary: 'Origin' } : {}),
             'Access-Control-Allow-Methods': 'GET, POST, PATCH, PUT, DELETE, OPTIONS',
-            'Access-Control-Allow-Headers': 'Content-Type, X-Access-Key, X-Token',
-            'Access-Control-Max-Age': '600',
+            'Access-Control-Allow-Headers': wantHeaders || 'Content-Type, X-Access-Key, X-Token',
           });
           return res.end();
         }
@@ -910,9 +942,41 @@ export async function startWebServer({
          * 完全不受保护——跨站页面一个 text/plain 表单就能把它们打出去。
          */
         if (req.method !== 'GET' && req.method !== 'HEAD' && !isJsonRequest(req)) {
+          /**
+           * 这里以前完全静默 —— 而它恰恰是「插件页一片空白」最可能的入口：
+           * CORS 预检（OPTIONS）没有 body，如果哪天 OPTIONS 分支漏了或顺序错了，
+           * 预检就会掉进这里拿 415，浏览器判定预检失败，页面只看到
+           * `TypeError: Failed to fetch`，服务端一条日志都没有，排查全靠猜。
+           */
+          log.warn(
+            `拒绝写操作：${req.method} ${pathname}` +
+              `（Content-Type: ${req.headers['content-type'] || '无'}，需要 application/json）`,
+          );
           return json(res, 415, { error: '写操作需要 Content-Type: application/json' });
         }
         if (!isSameOrigin(req, ptPage)) {
+          /**
+           * 这里踩过一个很隐蔽的坑：插件页是 opaque origin，请求 `Origin` 恒为
+           * 字符串 `null`。它发的请求如果没带有效 `pt`（比如面板重启后 iframe
+           * 还拿着旧令牌），就会落到这个分支。
+           *
+           * 两个后果叠加，导致排查极其困难：
+           *   1. 403 响应没带 CORS 头 → 浏览器不给页面读状态码，页面只看到
+           *      `TypeError: Failed to fetch`，看起来像网络断了或服务没起
+           *   2. 这里不写日志 → 服务端一条记录都没有，像是请求根本没到
+           *
+           * 所以：给 opaque origin 补上 CORS 头（让它能读到 403 和错误文案），
+           * 并且**一定要留一条 warn**。没带令牌的情况单独说清楚，否则下次
+           * 还是得靠猜。
+           */
+          if (String(req.headers.origin || '') === 'null') {
+            res.setHeader('Access-Control-Allow-Origin', 'null');
+            res.setHeader('Vary', 'Origin');
+          }
+          log.warn(
+            `拒绝跨站请求：${req.method} ${pathname}` +
+              `（Origin: ${req.headers.origin || '无'}${ptPage ? '，页面令牌有效' : '，无有效页面令牌'}）`,
+          );
           return json(res, 403, { error: '跨站请求被拒绝' });
         }
 
@@ -1146,7 +1210,36 @@ export async function startWebServer({
           if (typeof body.appSecret === 'string' && body.appSecret && body.appSecret !== '********') {
             cfg.appSecret = body.appSecret.trim();
           }
-          if (body.baseUrl) cfg.baseUrl = body.baseUrl.trim();
+          /**
+           * baseUrl 必须校验，否则这里等于「把 access_token 送人」的开关。
+           *
+           * `api.js` 用这个 baseUrl 拼请求，并带上 `Authorization: QQBot <token>`。
+           * 面板一旦被改成第三方地址，下一次 API 调用就把机器人令牌发到那台机器，
+           * 拿到令牌就能冒充机器人在它所在的任何群里发消息 —— 面板弱口令会因此
+           * 直接升级成「机器人身份被完全接管」。
+           *
+           * 用 `*.qq.com` 而不是写死 `api.sgroup.qq.com`：官方历史上用过
+           * `api.bot.qq.com` 这类别名（现有配置里就有），写死会把用户自己的
+           * 合法配置挡回去。qq.com 是腾讯的域，第三方拿不到子域。
+           */
+          if (body.baseUrl !== undefined && body.baseUrl !== '') {
+            let u = null;
+            try {
+              u = new URL(String(body.baseUrl).trim());
+            } catch {
+              return json(res, 400, { error: 'baseUrl 不是合法 URL' });
+            }
+            const host = u.hostname.toLowerCase();
+            const official = host === 'qq.com' || host.endsWith('.qq.com');
+            if (u.protocol !== 'https:' || !official) {
+              return json(res, 400, {
+                error:
+                  'baseUrl 只允许 https 的腾讯官方域名（如 https://api.sgroup.qq.com）。\n' +
+                  '改成第三方地址会把 access_token 发过去，等于交出机器人身份。',
+              });
+            }
+            cfg.baseUrl = u.origin;
+          }
           if (body.intents !== undefined) {
             const n = Number(body.intents);
             if (!Number.isInteger(n) || n < 0 || n > 0x7fffffff) {
@@ -1269,7 +1362,12 @@ export async function startWebServer({
          * 面板据此显示「统计不可用」而不是画一堆 0。
          */
         if (pathname === '/api/stats' && req.method === 'GET') {
-          const days = Number(url.searchParams.get('days')) || 7;
+          /**
+           * `days` 必须夹紧。同文件下面的 `/api/stats/export` 早就 clamp 到
+           * 1~365 了，这里漏了 —— 传个极大值就能让 SQLite 扫全表，
+           * 面板上一次点击就变成一次自伤式 DoS。
+           */
+          const days = Math.max(1, Math.min(365, Number(url.searchParams.get('days')) || 7));
           try {
             return json(res, 200, rt.stats?.overview(days) ?? { available: false });
           } catch (e) {

package/src/webhook.js

@@ -14,7 +14,16 @@
  * 这点和官方示例一致——一个回调地址服务多个机器人，省得每个机器人开一个端口。
  */
 import http from 'node:http';
+import fs from 'node:fs';
+/**
+ * 这里**必须具名导入** `join` / `dirname`，不能 `import path from 'node:path'`。
+ * constructor 有个参数就叫 `path`（回调路径），会把模块级的 `path` 遮蔽掉，
+ * 于是 `path.join(...)` 变成「字符串.join」→ `TypeError: path.join is not a function`，
+ * 整个 Webhook 服务直接起不来。这个坑是靠实测抓到的，不是看代码能看出来的。
+ */
+import { join, dirname } from 'node:path';
 import { createLogger } from './logger.js';
+import { DIRS } from './paths.js';
 import { verifyRequest, verifyEventSignature } from './sign.js';
 
 const log = createLogger('webhook');
@@ -43,6 +52,63 @@ export class WebhookServer {
     this.running = false;
     /** 收到过多少事件，面板显示用 */
     this.counters = { received: 0, rejected: 0, verify: 0 };
+    /**
+     * 回调验证（op=13）的状态，按 appId 记：`{ okAt: 时间戳, hits: [最近一分钟的尝试] }`。
+     *
+     * 为什么需要它，见 #handle 里 op=13 那段长注释。简单说：这个接口会用
+     * AppSecret 给「任意提交内容」签名，而事件验签用的是同一把密钥、同一种
+     * 拼接方式 —— 放开了就等于对外提供签名服务。
+     */
+    this.verifyState = new Map();
+    this.verifyFile = join(DIRS.data, 'webhook-verified.json');
+    this.#loadVerifyState();
+  }
+
+  /** 读回落盘的回调验证记录：重启不该让平台被迫重新验证一次 */
+  #loadVerifyState() {
+    try {
+      const obj = JSON.parse(fs.readFileSync(this.verifyFile, 'utf8'));
+      for (const [id, at] of Object.entries(obj)) {
+        const t = Number(at);
+        if (Number.isFinite(t) && t > 0) this.verifyState.set(id, { okAt: t, hits: [] });
+      }
+    } catch (e) {
+      // 文件不存在是正常的（第一次跑），其它错误才值得说一句
+      if (e.code !== 'ENOENT') log.warn(`回调验证记录读不出来（忽略）：${e.message}`);
+    }
+  }
+
+  #saveVerifyState() {
+    try {
+      fs.mkdirSync(dirname(this.verifyFile), { recursive: true });
+      const obj = {};
+      for (const [id, s] of this.verifyState) if (s.okAt) obj[id] = s.okAt;
+      const tmp = `${this.verifyFile}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(obj, null, 2));
+      fs.renameSync(tmp, this.verifyFile); // 原子替换，避免写一半断电
+    } catch (e) {
+      log.warn(`回调验证记录写不进去（不影响运行）：${e.message}`);
+    }
+  }
+
+  /**
+   * 重置某个机器人的回调验证状态。
+   *
+   * 用途：平台那边改了回调地址 / 换了域名，需要重新走一次 op=13 验证。
+   * 面板可以挂一个「重新验证回调」按钮调它，也可以直接删
+   * `data/webhook-verified.json` 里对应的那条。
+   *
+   * @returns {boolean} 是否真的重置了（原来有记录才返回 true）
+   */
+  resetVerify(appId) {
+    const id = String(appId ?? '').trim();
+    if (!id) return false;
+    const s = this.verifyState.get(id);
+    if (!s) return false;
+    this.verifyState.set(id, { okAt: 0, hits: [] });
+    this.#saveVerifyState();
+    log.info(`[${id}] 已重置回调验证状态，等待平台重新验证`);
+    return true;
   }
 
   /**
@@ -173,14 +239,68 @@ export class WebhookServer {
 
     // op=13：平台验证回调地址，用 AppSecret 签名后原样返回
     if (payload?.op === 13) {
+      /**
+       * ⚠️ 整段 Webhook 里最危险的就是这里，改之前把这段读完。
+       *
+       * op=13 的签名内容是 `${event_ts}${plain_token}`，事件验签是
+       * `${timestamp}${rawBody}` —— **同一把密钥、同一种拼接、没有域分离**。
+       * 而 op=13 在验签之前、也不需要任何认证，只要 appId 在册就回签。
+       *
+       * 于是它可以被当成「任意内容签名服务」：把要伪造的事件体当 plain_token
+       * 提交，拿回来的签名直接能过事件验签 —— 冒充任意 openid 触发管理命令。
+       * 也就是说 `verifySignature: true` 在攻击者面前是形同虚设的。
+       *
+       * 签名内容由官方协议规定，应用层改不了（改了平台就不认）。所以只能
+       * 收紧「谁能调、能调几次」：
+       *
+       *   1. **plain_token 形态校验**：事件体必然是 JSON，一定含 { } " \ 或空白；
+       *      合法 token 是平台生成的随机串。这条零成本、不影响正常流程，是主防线。
+       *   2. **24 小时内只回签一次**：平台只在配置回调地址时验证。
+       *      不做成「永久一次」是因为换域名/端口要重新验证，永久锁死会让用户
+       *      卡在「回调地址验证失败」上，反而制造新的排查成本。
+       *   3. **每分钟最多 3 次尝试**，把爆破与滥用压到没有价值。
+       */
+      const st = this.verifyState.get(appId) ?? { okAt: 0, hits: [] };
+      const now = Date.now();
+      st.hits = st.hits.filter((t) => now - t < 60_000);
+
+      if (st.okAt && now - st.okAt < 24 * 3600_000) {
+        this.counters.rejected += 1;
+        log.warn(
+          `[${appId}] 拒绝重复的 op=13：该 appId 24 小时内已通过验证。` +
+            `如果确实要重新验证（换回调地址等），调 resetVerify() 或删掉 ` +
+            `data/webhook-verified.json 里这一条`,
+        );
+        return this.#json(res, 403, { error: 'already verified' });
+      }
+      if (st.hits.length >= 3) {
+        this.counters.rejected += 1;
+        log.warn(`[${appId}] op=13 尝试过频（每分钟上限 3 次），已限速`);
+        return this.#json(res, 429, { error: 'too many validation attempts' });
+      }
+      st.hits.push(now);
+      this.verifyState.set(appId, st);
+
+      const tok = String(payload?.d?.plain_token ?? '');
+      if (!tok || tok.length > 128 || /[\s{}"\\]/.test(tok)) {
+        this.counters.rejected += 1;
+        log.warn(
+          `[${appId}] op=13 的 plain_token 形态异常，已拒绝（疑似把事件体当 token 提交）`,
+        );
+        return this.#json(res, 400, { error: 'invalid validation' });
+      }
+
       const signed = verifyRequest(bot.secret, payload);
       if (!signed) {
         this.counters.rejected += 1;
         log.warn(`[${appId}] 回调验证缺少 plain_token / event_ts`);
         return this.#json(res, 400, { error: 'invalid validation' });
       }
+      st.okAt = now;
+      this.verifyState.set(appId, st);
+      this.#saveVerifyState();
       this.counters.verify += 1;
-      log.info(`[${appId}] Webhook 回调验证通过`);
+      log.info(`[${appId}] Webhook 回调验证通过（24 小时内不再重复回签）`);
       return this.#json(res, 200, signed);
     }
 

package/web/app.js

@@ -725,9 +725,25 @@ function renderStatus(s) {
   }
 }
 
+/** 上一次看到的进程实例标识，用来判断服务是不是重启过 */
+let lastInstanceId = '';
+
 async function pollStatus() {
   try {
-    renderStatus(await api('/api/status'));
+    const d = await api('/api/status');
+    /**
+     * 进程重启 ⇒ 页面令牌全部重新生成、会话也全失效。
+     * 已打开的插件页 iframe 手里还是旧令牌，接下来每个请求都会被判成跨站（403），
+     * 用户看到的就是「切过去先红一下，等一会儿才好」。
+     *
+     * 这里一发现实例换了就立刻刷新令牌并重载 iframe，不必等兜底轮询。
+     */
+    const iid = String(d?.instanceId || '');
+    if (lastInstanceId && iid && iid !== lastInstanceId) {
+      refreshPageTokens();
+    }
+    lastInstanceId = iid;
+    renderStatus(d);
   } catch (e) {
     $('#connText').textContent = '面板断开';
     $('#connPill').className = 'status-pill offline';
@@ -1351,6 +1367,17 @@ async function loadPluginPages() {
     frame.dataset.key = p.key;
     // 页面令牌：不是面板密钥，只对这一个插件自己的接口有效
     frame.dataset.token = p.token || '';
+    /**
+     * **直接设上地址（预加载），不再等用户点开。**
+     *
+     * 以前这里是懒加载：注释写「地址在点开的时候才算」，好处是不点就不请求。
+     * 但代价是第一次点插件标签要走完「下载 35KB HTML → 解析几百行内联脚本 →
+     * 拉数据 → 渲染」，主观上就是卡一下，用户容易以为坏了。
+     *
+     * 现在建标签时就开始加载，点过去就是现成的。切换机器人时这个函数会重跑，
+     * 地址里带上了新的 bot 参数，所以也不会串台。
+     */
+    frame.src = pluginPageUrl(p.key, p.token || '');
     sec.appendChild(frame);
     main.appendChild(sec);
   }
@@ -1385,6 +1412,64 @@ function pluginPageUrl(key, token) {
   return `/api/pages/${encodeURIComponent(key)}/html${s ? `?${s}` : ''}`;
 }
 
+/**
+ * 跟着进程重启自动换令牌。
+ *
+ * 页面令牌只存在服务端内存里，进程重启就全部重新生成。而面板页如果是在重启
+ * **之前**打开的，iframe 里还挂着旧令牌，插件页的所有请求都会被判成跨站
+ * （403），表现为「数据空白」或者直接 `Failed to fetch` —— 用户完全看不出
+ * 是重启导致的，只会觉得面板坏了。
+ *
+ * 这里定期问一次页面列表：令牌变了就更新 iframe 的地址并重载它。
+ * 只在令牌真的变化时才重载（也就是重启过），平时不会打断用户操作。
+ */
+async function refreshPageTokens() {
+  let list = null;
+  try {
+    list = await api('/api/pages');
+  } catch {
+    return 0;
+  }
+  if (!Array.isArray(list)) return 0;
+
+  let reloaded = 0;
+  for (const p of list) {
+    for (const f of $$('.plugin-page')) {
+      if (f.dataset.key !== p.key) continue;
+      if (f.dataset.token === (p.token || '')) continue;
+      f.dataset.token = p.token || '';
+      // 只重载已经打开过的（没加载过的不去碰，免得白跑一次请求）
+      if (f.getAttribute('src')) {
+        f.src = pluginPageUrl(f.dataset.key, f.dataset.token);
+        reloaded += 1;
+      }
+    }
+  }
+  return reloaded;
+}
+
+// 15 秒足够快，又不会给面板添负担；令牌不变时这里什么都不做
+setInterval(() => {
+  refreshPageTokens();
+}, 15000);
+
+/**
+ * 切回面板时立刻补一次。
+ *
+ * 两个真实场景：
+ *   1. 浏览器会把后台标签页的定时器降频（Chrome 最长到 1 分钟一次），
+ *      所以「去改个配置再切回来」最容易撞上旧令牌
+ *   2. 保存配置会触发 config-watch 热加载，插件被卸载重载 → 页面令牌
+ *      跟着重新生成 → 已打开的 iframe 立刻变无效
+ * 回来这一下立刻修，比等定时器体感好得多。
+ */
+window.addEventListener('focus', () => {
+  refreshPageTokens();
+});
+document.addEventListener('visibilitychange', () => {
+  if (!document.hidden) refreshPageTokens();
+});
+
 /* ---------------- 统计 ---------------- */
 
 /** 每天一根柱子，纯 CSS 不用图表库——多引一个库就破了零依赖 */