@shendeguize/remote-dsh-center 0.4.0

package/src/lib/bundle.js

@@ -0,0 +1,82 @@
+/**
+ * 发布产物的命名与校验和口径 —— 纯内核，零 import。
+ *
+ * 构建端（scripts/build-bundle.mjs）产出什么名字、消费端（src/updater.js 与
+ * install.sh 的 standalone 通道）去下载什么名字，必须是同一份规则：这类「两边各写一份
+ * 字符串拼接」的地方一旦漂移，表现是 404 而不是报错，最难查。
+ *
+ * 落地形态（解包后）：
+ *   <bundle 名>/bin/dshc            三行 shim，exec 自带 node 跑 app/src/cli.js
+ *   <bundle 名>/runtime/bin/node    官方 Node 发行版二进制
+ *   <bundle 名>/app/                产品本体（内容 = check.mjs 的 PACK_RULES 白名单）
+ *   <bundle 名>/BUNDLE_INFO.json    通道识别标记（版本 / 架构 / 运行时版本 / 来源）
+ */
+
+/** 发布仓库（tag、Release、下载都指向它）。install.sh 有一份同值的默认，用例盯着两处一致。 */
+export const RELEASE_REPO = 'shendeguize/Remote_DSH_Center';
+
+/** 只发 mac：Linux 走 git 通道（本来就要求有 node），Windows 不支持。 */
+export const BUNDLE_PLATFORM = 'darwin';
+
+export const SUPPORTED_ARCHES = Object.freeze(['arm64', 'x64']);
+
+export const SUMS_FILE = 'SHA256SUMS';
+
+export const BUNDLE_INFO_FILE = 'BUNDLE_INFO.json';
+
+/**
+ * `uname -m` / `process.arch` 的各种写法归一到发布口径。
+ * @returns {'arm64'|'x64'|null} 不支持的架构给 null，由调用方给人话提示
+ */
+export function normalizeArch(raw) {
+  const arch = String(raw ?? '').trim().toLowerCase();
+  if (arch === 'arm64' || arch === 'aarch64') return 'arm64';
+  if (arch === 'x64' || arch === 'x86_64' || arch === 'amd64') return 'x64';
+  return null;
+}
+
+/** 解包后的顶层目录名，也是 tar.gz 的主干名。 */
+export function bundleDirName({ version, arch }) {
+  return `dsh-center-v${version}-${BUNDLE_PLATFORM}-${arch}`;
+}
+
+/** Release 附件名。 */
+export function assetName({ version, arch }) {
+  return `${bundleDirName({ version, arch })}.tar.gz`;
+}
+
+/**
+ * `shasum -a 256` 的输出格式：`<64 位十六进制><空白>[*]<文件名>`。
+ * @returns {Map<string,string>} 文件名 → 小写 sha256
+ */
+export function parseSums(text) {
+  const sums = new Map();
+  for (const line of String(text ?? '').split('\n')) {
+    const m = /^([0-9a-fA-F]{64})\s+\*?(\S.*)$/.exec(line.trim());
+    if (m) sums.set(m[2].trim(), m[1].toLowerCase());
+  }
+  return sums;
+}
+
+/**
+ * 反向：写 SHA256SUMS 文件。与 `shasum -a 256 -c` 兼容（两空格分隔）。
+ * @param {Iterable<[string,string]>} entries [文件名, sha]
+ */
+export function formatSums(entries) {
+  return `${[...entries].map(([name, sha]) => `${sha}  ${name}`).join('\n')}\n`;
+}
+
+/** 某个 tag 的 Release 元信息接口。 */
+export function releaseByTagUrl(tag, repo = RELEASE_REPO) {
+  return `https://api.github.com/repos/${repo}/releases/tags/${tag}`;
+}
+
+/** Release 列表接口（挑 latest / 含 pre-release 时用；GitHub 的 /latest 会跳过 pre-release）。 */
+export function releasesUrl(repo = RELEASE_REPO, perPage = 30) {
+  return `https://api.github.com/repos/${repo}/releases?per_page=${perPage}`;
+}
+
+/** 附件下载地址（走 releases/download，不需要鉴权）。 */
+export function assetUrl({ tag, name, repo = RELEASE_REPO }) {
+  return `https://github.com/${repo}/releases/download/${tag}/${name}`;
+}

package/src/lib/bus.js

@@ -0,0 +1,109 @@
+/**
+ * 事件总线 + 事件环形缓冲（11 §1.4）。
+ * 事件名与 SSE type 一一对应；host-changed 只传主机名，序列化在发送时刻由 api 完成，
+ * 保证客户端拿到的永远是最新视图（天然合并 debounce 窗口内的连续变化）。
+ */
+
+import { EventEmitter } from 'node:events';
+
+export const bus = new EventEmitter();
+bus.setMaxListeners(50);
+
+const LOG_BUFFER_CAPACITY = 200;
+
+/**
+ * 单条日志的字数上限。环形缓冲只按条数限长，不看字节数——「200 条」这个额度对
+ * 「每条 8MB」毫无约束：远端打几条巨行（base64 blob、一整坨 JSON、带 traceback 的堆栈）
+ * 就能把常驻的 manager 顶上去，实测 20 条 8MB 让堆从 9MB 涨到 176MB。SSE 那边还要
+ * 把每条原样推给每个页面、页面再塞进 DOM。
+ *
+ * msg 本来就只是单行摘要，detail 是排障现场——都不需要无限长。
+ */
+const LOG_LINE_MAX_CHARS = 2_000;
+const LOG_DETAIL_MAX_CHARS = 16_384;
+
+/** 给截断标记用的人话长度。 */
+function humanLen(chars) {
+  if (chars >= 1_048_576) return `${(chars / 1_048_576).toFixed(1)}MB`;
+  if (chars >= 1_024) return `${(chars / 1_024).toFixed(1)}KB`;
+  return `${chars} 字`;
+}
+
+/** 超长就切开头，并说清原本多长——读的人得知道后面还有东西。 */
+function clip(text, max) {
+  const s = String(text);
+  if (s.length <= max) return s;
+  return `${s.slice(0, max)}…（已截断，原文 ${humanLen(s.length)}）`;
+}
+
+/** @type {{host:string|null, level:'info'|'warn'|'error', msg:string, ts:string, detail:string|null}[]} */
+const logBuffer = [];
+
+/** 同一微任务内同名 host-changed 去重（11 §1.4 第 1 点）。 */
+let pendingHosts = null;
+
+export function emitHostChanged(name) {
+  if (pendingHosts === null) {
+    pendingHosts = new Set();
+    queueMicrotask(() => {
+      const batch = pendingHosts;
+      pendingHosts = null;
+      for (const host of batch) bus.emit('host-changed', host);
+    });
+  }
+  pendingHosts.add(name);
+}
+
+/**
+ * 事件面板内容。msg 恒为单行摘要；长文本只进 detail（11 §7.2 原则）。
+ * 同时 console 输出一份进 manager.log。
+ */
+export function logEvent(host, level, msg, detail = null) {
+  // 先截断再折行：对一条 8MB 的串跑正则本身就是笔开销，而结果反正只留开头
+  const entry = {
+    host: host ?? null,
+    level,
+    msg: clip(msg, LOG_LINE_MAX_CHARS).replace(/\s*\n\s*/g, ' ').trim(),
+    ts: new Date().toISOString(),
+    detail: detail === null || detail === undefined ? null : clip(detail, LOG_DETAIL_MAX_CHARS),
+  };
+  logBuffer.push(entry);
+  if (logBuffer.length > LOG_BUFFER_CAPACITY) logBuffer.shift();
+
+  const tag = entry.host ? `[${entry.host}]` : '[manager]';
+  // 页面只吃单行 msg，但 manager.log 是事后排障的唯一现场——detail（ssh stderr 等）
+  // 必须落盘，缩进续行以免和下一条日志混淆。
+  const detailLines = entry.detail === null
+    ? ''
+    : `\n${String(entry.detail).replace(/\n+$/, '').split('\n').map((l) => `    | ${l}`).join('\n')}`;
+  const line = `${entry.ts} ${level.toUpperCase()} ${tag} ${entry.msg}${detailLines}`;
+  if (level === 'error') console.error(line);
+  else if (level === 'warn') console.warn(line);
+  else console.log(line);
+
+  bus.emit('log-line', entry);
+  return entry;
+}
+
+/** SSE snapshot 用：最近 n 条，按时间升序。 */
+export function recentLogs(n = 50) {
+  return logBuffer.slice(-n).map((e) => ({ ...e }));
+}
+
+export function emitConfigChanged(changed = []) {
+  bus.emit('config-changed', changed);
+}
+
+/** 202 长动作结束（13 §3.4）。每个 operationId 有且仅有一条。 */
+export function emitOperationDone(payload) {
+  bus.emit('operation-done', payload);
+}
+
+/** 测试用：清空缓冲与待发批次。 */
+export function _resetForTest() {
+  logBuffer.length = 0;
+  pendingHosts = null;
+  bus.removeAllListeners();
+}
+
+export { LOG_BUFFER_CAPACITY, LOG_DETAIL_MAX_CHARS, LOG_LINE_MAX_CHARS };

package/src/lib/capture.js

@@ -0,0 +1,53 @@
+/**
+ * 有界的「留尾」收集器（issue #92）。
+ *
+ * 为什么留尾不留头：这东西收的是远端命令的 stdout/stderr，两种超量场合都指向尾巴——
+ * POLL/VERIFY 的 `KEY=VALUE` 是我们的脚本在**最后**打的，前面刷屏的是远端登录 shell
+ * （.bashrc/motd）；看日志的人要的也是最新几行，不是十万行之前的开头。
+ *
+ * 为什么必须有界：`stdout += chunk` 这种写法等于把 manager 的 RSS 交给远端决定。
+ * 越过 V8 的字符串上限（约 512MB）时抛的 `RangeError: Invalid string length` 落在流的
+ * data 回调里，没人接得住——manager 当场死，所有隧道陪葬。
+ */
+
+/**
+ * @param {number} cap 留在手里的字符数上限；<=0 表示不封顶
+ * @returns {{push(s:string):void, text():string, dropped():number, chunkCount():number}}
+ */
+export function createTailCapture(cap) {
+  /** @type {string[]} */
+  const chunks = [];
+  let size = 0;
+  let dropped = 0;
+
+  return {
+    push(s) {
+      if (s === '') return;
+      chunks.push(s);
+      size += s.length;
+      if (cap <= 0) return;
+      // 先整块地扔，再对边界那块切一刀——这样账本长度只跟 cap 有关，与吐了多少无关
+      while (chunks.length > 1 && size - chunks[0].length >= cap) {
+        size -= chunks[0].length;
+        dropped += chunks[0].length;
+        chunks.shift();
+      }
+      if (size > cap) {
+        const over = size - cap;
+        chunks[0] = chunks[0].slice(over);
+        size -= over;
+        dropped += over;
+      }
+    },
+    text() {
+      return chunks.join('');
+    },
+    dropped() {
+      return dropped;
+    },
+    /** 判据用：账本自身不许随吐出量增长。 */
+    chunkCount() {
+      return chunks.length;
+    },
+  };
+}

package/src/lib/clock.js

@@ -0,0 +1,18 @@
+/**
+ * 单调钟（issue #104）。
+ *
+ * 为什么不能拿 `Date.now()` 算「过了多久 / 还剩多久」：墙钟会跳。休眠唤醒后的 NTP
+ * 步进校时、手动改时间、虚拟机快照恢复、和 Windows 双启动把 RTC 按本地时间写坏，
+ * 都能让它前后跳上几分钟乃至几小时。`deadline = Date.now() + 8000` 遇上一次 60s
+ * 回拨，那个「8s 上界」就变成 68s——超时不再兜底；往前跳则相反，好隧道被判超时。
+ *
+ * 单调钟只随真实流逝前进，与系统时间无关，是所有上界与窗口该用的那把尺。
+ */
+
+/**
+ * 自进程启动起的毫秒数，单调不减。只可用于求差值，绝对值无意义。
+ * @returns {number}
+ */
+export function monotonicMs() {
+  return performance.now();
+}

package/src/lib/entry.js

@@ -0,0 +1,27 @@
+/**
+ * 「这个模块是不是被直接执行的」判定。
+ *
+ * 看似 `process.argv[1] === fileURLToPath(import.meta.url)` 就够，实则不够：
+ * 装到 PATH 的入口是一条软链（`npm link` 与 scripts/install.mjs 都这么干），
+ * 此时 argv[1] 是链接名（如 ~/.local/bin/dshc），而 import.meta.url 已经是
+ * 解引用后的真身（src/cli.js）——只比字面路径会判成「被 import」，于是
+ * 命令什么都不做、还退 0，排查起来极难。故两边都取 realpath 再比。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** @param {string} importMetaUrl 调用方的 import.meta.url */
+export function isMainEntry(importMetaUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+  return realOf(argv1) === realOf(fileURLToPath(importMetaUrl));
+}
+
+function realOf(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}

package/src/lib/errors.js

@@ -0,0 +1,88 @@
+/**
+ * 统一错误形状（11 §7.1）。零依赖叶子模块：全库可 import，自身不 import 任何本地模块，
+ * 故不参与依赖环（ENG-24 的防环 lint 对本文件豁免 lib 互不 import 规则）。
+ */
+
+/** 错误码 → 默认 HTTP 状态（11 §7.2）。 */
+export const ERROR_HTTP_STATUS = Object.freeze({
+  VALIDATION: 400,
+  NOT_FOUND: 404,
+  SETUP_REQUIRED: 409,
+  PHASE_CONFLICT: 409,
+  NOT_ALLOWED: 409,
+  // 跨站防线（src/lib/origin-guard.js）：都是 403，且都在路由之前判掉
+  FORBIDDEN_ORIGIN: 403,
+  FORBIDDEN_HOST: 403,
+  PORT_EXHAUSTED: 409,
+  SSH_UNREACHABLE: 502,
+  SSH_TIMEOUT: 504,
+  LOCAL_TIMEOUT: 504,
+  LOCAL_EXEC_FAILED: 500,
+  LOCAL_COPY_FAILED: 500,
+  LOCAL_HOST_EXISTS: 409,
+  LOCAL_NAME_CONFLICT: 409,
+  PROTO_PARSE: 500,
+  SETTINGS_TOO_LARGE: 413,
+  SETTINGS_BUSY: 409,
+  SETTINGS_STALE: 409,
+  SETTINGS_WRITE_FAILED: 500,
+  SETTINGS_READ_FAILED: 500,
+  SETTINGS_UNSUPPORTED: 501,
+  SETTINGS_INVALID_UTF8: 422,
+  WORKSPACE_BUSY: 409,
+  WORKSPACE_WORKDIR_REQUIRED: 400,
+  WORKSPACE_CWD_UNAVAILABLE: 409,
+  WORKSPACE_INVALID_PATH: 422,
+  WORKSPACE_REGISTER_FAILED: 502,
+  WORKSPACE_REGISTER_TIMEOUT: 504,
+  LAUNCH_FAILED: 500,
+  KILL_REFUSED: 409,
+  TUNNEL_FORWARD_DISABLED: 500,
+  TUNNEL_PORT_BUSY: 500,
+  STATE_ILLEGAL_TRANSITION: 500,
+  // 配置落盘失败（目录只读 / 磁盘满 / 卷被卸载）：改动整份放弃，内存不动
+  CONFIG_WRITE_FAILED: 500,
+  // config.json 被外部手改，内存那份已过期：拒写而不是拿旧值盖掉（冲突，非故障）
+  CONFIG_STALE: 409,
+  // pidfile 写不进（同上三种成因）：没有它谁也找不到这个 manager，只能硬失败
+  PIDFILE_WRITE_FAILED: 500,
+  // manager.log 开不出来：后台进程的 stdout/stderr 就指它，没有它等于没有现场
+  LOGFILE_OPEN_FAILED: 500,
+  INTERNAL: 500,
+});
+
+export class DshError extends Error {
+  /**
+   * @param {keyof typeof ERROR_HTTP_STATUS | string} code
+   * @param {string} message 一句话摘要（用户可读，单行）
+   * @param {{host?:string|null, detail?:string|null, cause?:Error}} [extra]
+   */
+  constructor(code, message, extra = {}) {
+    super(message, extra.cause ? { cause: extra.cause } : undefined);
+    this.name = 'DshError';
+    this.code = code;
+    this.host = extra.host ?? null;
+    this.detail = extra.detail ?? null;
+  }
+
+  get httpStatus() {
+    return ERROR_HTTP_STATUS[this.code] ?? 500;
+  }
+
+  /** HTTP 响应体形状（13 §1.1）。 */
+  toBody() {
+    const body = { error: this.message, code: this.code };
+    if (this.detail) body.detail = this.detail;
+    return body;
+  }
+}
+
+/** 把任意异常规整为 DshError（api/queue 边界用，11 §7.1）。 */
+export function asDshError(err, fallbackCode = 'INTERNAL') {
+  if (err instanceof DshError) return err;
+  const message = err instanceof Error ? err.message : String(err);
+  return new DshError(fallbackCode, message, {
+    cause: err instanceof Error ? err : undefined,
+    detail: err instanceof Error && err.stack ? err.stack : null,
+  });
+}

package/src/lib/logfile.js

@@ -0,0 +1,65 @@
+/**
+ * manager.log 的自我封顶（issue #81）。
+ *
+ * manager 在 launchd 下是 7×24 的常驻进程，日志只追加、从不回收。健康态几乎不写，
+ * 但链路不稳的一台主机（断联 → 退避 → 重连，每一拍都记）实测约 8MB/天——放一年
+ * 就是几个 G 躺在 `~/.dsh_center/` 里，没人会去看一眼。
+ *
+ * 必须**原地**截断：日志是被继承的 O_APPEND fd 在写（`launchDetached` 把 stdout/stderr
+ * 都指到这个文件），改名换文件的话进程还往原来那个 inode 里写，新文件永远是空的，
+ * 老文件继续长。
+ */
+
+import fs from 'node:fs';
+
+/** 到这个大小就动手。 */
+export const LOG_FILE_CAP_BYTES = 8 * 1024 * 1024;
+
+/** 截完留这么多尾巴——排障看的都是最近发生的事。 */
+export const LOG_FILE_KEEP_BYTES = 1024 * 1024;
+
+/**
+ * 要不要截、从哪儿开始留。
+ * @param {number} size 当前字节数
+ * @returns {{trim:boolean, from:number}} from = 从这个偏移读到末尾
+ */
+export function planTrim(size, { capBytes = LOG_FILE_CAP_BYTES, keepBytes = LOG_FILE_KEEP_BYTES } = {}) {
+  if (!(size > capBytes)) return { trim: false, from: 0 };
+  const keep = Math.min(keepBytes, capBytes);
+  return { trim: true, from: Math.max(0, size - keep) };
+}
+
+/**
+ * 超了就原地截断，只留尾巴，并在最前面补一行说明丢了多少。
+ * 任何 IO 失败都吞掉：日志封顶失败不该把调用它的主流程（启动、巡检）带下去。
+ * @returns {{trimmed:boolean, dropped:number}} dropped = 丢掉的字节数
+ */
+export function trimLogFile(file, { capBytes = LOG_FILE_CAP_BYTES, keepBytes = LOG_FILE_KEEP_BYTES } = {}) {
+  try {
+    const { size } = fs.statSync(file);
+    const plan = planTrim(size, { capBytes, keepBytes });
+    if (!plan.trim) return { trimmed: false, dropped: 0 };
+
+    const fd = fs.openSync(file, 'r');
+    let tail;
+    try {
+      const buf = Buffer.alloc(size - plan.from);
+      fs.readSync(fd, buf, 0, buf.length, plan.from);
+      tail = buf.toString('utf8');
+    } finally {
+      fs.closeSync(fd);
+    }
+
+    // 从块中间切进来的首行是残行，丢掉它：留半行只会让人怀疑自己看错了
+    const cut = tail.indexOf('\n');
+    const body = cut === -1 ? '' : tail.slice(cut + 1);
+    const dropped = size - Buffer.byteLength(body, 'utf8');
+    const head = `${new Date().toISOString()} INFO [manager] 日志已原地截断，丢掉较早的 ${dropped} 字节`
+      + `（上限 ${capBytes} 字节）\n`;
+    // 同一个 inode 上覆盖写：换文件的话那个 O_APPEND fd 就写进孤立文件里了
+    fs.writeFileSync(file, body.endsWith('\n') || body === '' ? `${head}${body}` : `${head}${body}\n`);
+    return { trimmed: true, dropped };
+  } catch {
+    return { trimmed: false, dropped: 0 };
+  }
+}

package/src/lib/machine.js

@@ -0,0 +1,63 @@
+/**
+ * 主机状态机（11 §2）。README 状态机图为子集，02 行为要求的补全迁移已在
+ * README「契约疑议」第 2 条报备并裁决采纳。
+ */
+
+import { DshError } from './errors.js';
+
+export const PHASES = Object.freeze([
+  'unknown',
+  'unreachable',
+  'no_dsh',
+  'ready',
+  'starting',
+  'running',
+  'degraded',
+  'crashed',
+]);
+
+/** 探测的三分类结果。 */
+export const PROBE_OUT = Object.freeze(['unreachable', 'no_dsh', 'ready']);
+
+/**
+ * from → 允许的 to。不含 from===to 的自环：自环恒许可（只刷新数据，不算迁移）。
+ * @type {Readonly<Record<string, readonly string[]>>}
+ */
+export const TRANSITIONS = Object.freeze({
+  unknown: PROBE_OUT,
+  unreachable: PROBE_OUT,
+  no_dsh: PROBE_OUT,
+  ready: Object.freeze([...PROBE_OUT, 'starting']),
+  crashed: Object.freeze([...PROBE_OUT, 'starting']),
+  starting: Object.freeze(['running', 'ready']),
+  running: Object.freeze(['degraded', 'crashed', 'ready']),
+  degraded: Object.freeze(['running', 'crashed', 'ready']),
+});
+
+/** 探测不得改写这三态的 phase（11 §2.2 说明）：只刷新 manualInstances。 */
+export const PROBE_PROTECTED_PHASES = Object.freeze(['starting', 'running', 'degraded']);
+
+export function isPhase(p) {
+  return PHASES.includes(p);
+}
+
+export function canTransition(from, to) {
+  if (!isPhase(from) || !isPhase(to)) return false;
+  if (from === to) return true;
+  return (TRANSITIONS[from] ?? []).includes(to);
+}
+
+/**
+ * 终审守卫（11 §2.3 第三层）。走到这里还非法 = 代码 bug。
+ * @throws {DshError} STATE_ILLEGAL_TRANSITION
+ */
+export function assertTransition(from, to, cause = 'unknown') {
+  if (!canTransition(from, to)) {
+    throw new DshError(
+      'STATE_ILLEGAL_TRANSITION',
+      `非法状态迁移 ${from} → ${to}（触发：${cause}）`,
+      { detail: `合法目标：${(TRANSITIONS[from] ?? []).join(', ') || '(无)'}` },
+    );
+  }
+  return to;
+}

package/src/lib/origin-guard.js

@@ -0,0 +1,64 @@
+/**
+ * 本机 HTTP 面的跨站防线（纯函数，便于逐条判定）。
+ *
+ * manager 只监听 127.0.0.1，但「只听本机」挡不住**浏览器**替别人发请求：用户随便打开
+ * 一个网页，那个网页就能 `fetch('http://127.0.0.1:<port>/api/hosts/x/start')`。这种简单
+ * 请求不触发预检，浏览器照发；攻击者读不到响应，可副作用照样发生——实测里一个陌生
+ * origin 的页面真把远端会话拉起来了。
+ *
+ * 两道闸：
+ *
+ * 1. `Origin` 在场就必须是 manager 自己的 origin。命令行工具不带这个头，一律放行；
+ *    浏览器发跨站请求时必带，于是被挡。
+ * 2. `Host` 必须是环回名。DNS rebinding 的落地形态就是「攻击者域名解析到 127.0.0.1」，
+ *    那时浏览器认为同源，第 1 道闸失效，只有这道拦得住。
+ */
+
+/** 允许出现在 Host / Origin 里的主机名。 */
+const LOOPBACK_NAMES = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+
+/** Host 头里取主机名：去掉端口，IPv6 的方括号一并留着比对。 */
+export function hostnameOf(hostHeader) {
+  const raw = String(hostHeader ?? '').trim();
+  if (raw === '') return '';
+  if (raw.startsWith('[')) return raw.slice(0, raw.indexOf(']') + 1).toLowerCase();
+  const i = raw.lastIndexOf(':');
+  return (i === -1 ? raw : raw.slice(0, i)).toLowerCase();
+}
+
+export function isLoopbackHost(hostHeader) {
+  return LOOPBACK_NAMES.has(hostnameOf(hostHeader));
+}
+
+/**
+ * @param {{headers:Record<string,string|undefined>, port:number}} req
+ * @returns {{ok:true}|{ok:false, status:number, code:string, message:string}}
+ */
+export function checkRequestOrigin({ headers = {}, port }) {
+  const host = headers.host ?? headers.Host;
+  if (!isLoopbackHost(host)) {
+    return {
+      ok: false,
+      status: 403,
+      code: 'FORBIDDEN_HOST',
+      // 不回显攻击者给的域名：这段文本会原样出现在响应体里
+      message: 'manager 只接受来自本机的请求（Host 必须是 127.0.0.1 或 localhost）。',
+    };
+  }
+
+  const origin = headers.origin ?? headers.Origin;
+  if (origin === undefined || origin === '') return { ok: true };
+  // 'null' 是 file:// 与沙箱 iframe 的 origin，同样不是自己
+  let parsed;
+  try {
+    parsed = new URL(origin);
+  } catch {
+    return { ok: false, status: 403, code: 'FORBIDDEN_ORIGIN', message: 'manager 拒绝跨站请求。' };
+  }
+  const sameOrigin = parsed.protocol === 'http:'
+    && LOOPBACK_NAMES.has(parsed.hostname.toLowerCase())
+    && parsed.port === String(port);
+  return sameOrigin
+    ? { ok: true }
+    : { ok: false, status: 403, code: 'FORBIDDEN_ORIGIN', message: 'manager 拒绝跨站请求。' };
+}

package/src/lib/pool.js

@@ -0,0 +1,88 @@
+/**
+ * 有界并发（扇出闸）。
+ *
+ * 为什么需要：一台 manager 管 N 台远端时，探测/恢复/自启这类「对每台各来一次 ssh」的
+ * 动作，无闸就是 N 条 ssh 同时握手。远端 sshd 的 `MaxStartups` 出厂值是 `10:30:100`——
+ * 未完成认证的连接超过 10 条起就按比例随机丢，到 100 条全丢；多台远端共用一台跳板机
+ * （ProxyJump）时这个额度是**所有主机合起来**算的。被丢的那几台会以
+ * `kex_exchange_identification: Connection closed by remote host` 收场，页面上表现为
+ * 「随机几台不可达」，而它们其实好端端的。
+ *
+ * 语义与 `Promise.allSettled` 对齐：不短路、结果按入参顺序、单个任务抛错不影响其余。
+ */
+
+/**
+ * 长期在那儿的那道闸（issue #100）。
+ *
+ * `mapPool` 管的是「一把任务一次发完」，隧道重连环不是那个形状：每台主机各有一个退避
+ * 定时器，各自到点各自敲门，谁也不知道此刻还有几台也在敲。网络整体回来的那一瞬
+ * （合盖睡醒、Wi-Fi 切换、跳板机抖一下），这些定时器会挤在同一刻——那正是跳板机
+ * 最忙的时候，而它们全都绕过了 `mapPool` 那道闸。
+ *
+ * 排队是 FIFO：先到的先走，不许后来的插队饿死前面的。
+ * @param {number} limit 同时在里面的上限；<=0 表示不限
+ */
+export function createGate(limit) {
+  let inFlight = 0;
+  /** @type {(() => void)[]} */
+  const waiting = [];
+
+  const release = () => {
+    inFlight -= 1;
+    waiting.shift()?.();
+  };
+
+  return {
+    /**
+     * @template R
+     * @param {() => Promise<R>} fn
+     * @returns {Promise<R>}
+     */
+    async run(fn) {
+      if (limit > 0) {
+        if (inFlight >= limit) await new Promise((resolve) => { waiting.push(resolve); });
+        inFlight += 1;
+      }
+      try {
+        return await fn();
+      } finally {
+        if (limit > 0) release();
+      }
+    },
+    /** 判据用。 */
+    stats() {
+      return { inFlight, waiting: waiting.length };
+    },
+  };
+}
+
+/**
+ * @template T, R
+ * @param {T[]} items
+ * @param {(item:T, index:number)=>Promise<R>} fn
+ * @param {number} limit 同时在飞的上限；<=0 或 >= items.length 时等价于全并发
+ * @returns {Promise<PromiseSettledResult<R>[]>}
+ */
+export async function mapPool(items, fn, limit) {
+  const results = new Array(items.length);
+  if (items.length === 0) return results;
+
+  const width = limit > 0 ? Math.min(limit, items.length) : items.length;
+  let next = 0;
+
+  const worker = async () => {
+    for (;;) {
+      const i = next;
+      next += 1;
+      if (i >= items.length) return;
+      try {
+        results[i] = { status: 'fulfilled', value: await fn(items[i], i) };
+      } catch (reason) {
+        results[i] = { status: 'rejected', reason };
+      }
+    }
+  };
+
+  await Promise.all(Array.from({ length: width }, worker));
+  return results;
+}