dsh-remote-agent 0.9.3 → 0.9.4

package/lib/instance-config.js

@@ -55,6 +55,11 @@ export const INSTANCE_FILE_NAME = 'instance.json'
  * 为什么不直接存整个 config：config 里可能有 DSH 注入的东西（未知字段会
  * 被 schemastery passthrough 保留），把它们写回磁盘等于把 loader 的中间态
  * 固化下来。只存我们**真正需要跨重启保留**的。
+ *
+ * ⚠ 2026-10-20 补齐（v0.9.3 审查 H2/M2）：此前少了 `listenHost` /
+ * `listenPort` / `relay` —— 于是架构承诺"配置不会再被 DSH 冲掉"，
+ * 而 0.9.3 新增的两个关键字段恰好不在保护范围内，`relay`（跨 NAT 必需）
+ * 更是从来没有落过盘。用户配了它们，一次重启就静默回默认。
  */
 const PERSISTED_KEYS = Object.freeze([
   'role',
@@ -67,8 +72,18 @@ const PERSISTED_KEYS = Object.freeze([
   'uiPullRoot',
   'agentMode',
   'pair',
+  // 0.9.3 独立监听的绑定意图（自动选地址会挑 Tailscale，用户可能想钉死局域网）
+  'listenHost',
+  'listenPort',
+  // hub 侧中继凭证（跨 NAT 场景的唯一通路）
+  'relay',
 ])
 
+/** 值是对象的白名单字段（当前只有 relay：{ url, token }）。 */
+const OBJECT_KEYS = Object.freeze({
+  relay: ['url', 'token'],
+})
+
 /**
  * 解析 stateDir（与 lib/node/index.js 的 resolveStateDir 同口径）。
  * @param {object} [config]
@@ -96,6 +111,55 @@ export function instanceFilePath(config) {
   return path.join(resolveStateDir(config), INSTANCE_FILE_NAME)
 }
 
+/**
+ * 字段级清洗（读与写共用，保证两侧对称）。
+ *
+ * 2026-10-20 扩展：支持 number（listenPort）与白名单对象（relay）。
+ * 早先只接受 string，于是 `listenPort: 19388` 这种合法配置会被静默丢弃。
+ *
+ * @param {Map<string, unknown>} src
+ * @returns {object|null} 清洗后的对象；没有任何有效字段时返回 null
+ */
+function sanitizeFields(src) {
+  const out = {}
+  for (const k of PERSISTED_KEYS) {
+    if (!src.has(k)) continue
+    const v = src.get(k)
+    if (v === null || v === undefined) continue
+
+    // roots：数组，去空去重前的简单清洗（真正的规范化在 normalizeRoots）
+    if (k === 'roots') {
+      if (Array.isArray(v)) {
+        const arr = v.filter((x) => typeof x === 'string' && x.trim() !== '').map((x) => x.trim())
+        if (arr.length > 0) out.roots = arr
+      }
+      continue
+    }
+
+    // relay：{ url, token } —— 只取白名单子键，且至少有一个非空
+    if (OBJECT_KEYS[k]) {
+      if (!v || typeof v !== 'object' || Array.isArray(v)) continue
+      const sub = {}
+      for (const sk of OBJECT_KEYS[k]) {
+        const sv = v[sk]
+        if (typeof sv === 'string' && sv.trim() !== '') sub[sk] = sv.trim()
+      }
+      if (Object.keys(sub).length > 0) out[k] = sub
+      continue
+    }
+
+    // listenPort：数字（0 合法 —— 表示显式关闭独立监听）
+    if (k === 'listenPort') {
+      const n = typeof v === 'number' ? v : (typeof v === 'string' && /^\d+$/.test(v.trim()) ? Number(v.trim()) : NaN)
+      if (Number.isInteger(n) && n >= 0 && n < 65536) out.listenPort = n
+      continue
+    }
+
+    if (typeof v === 'string' && v.trim() !== '') out[k] = v.trim()
+  }
+  return Object.keys(out).length > 0 ? out : null
+}
+
 /**
  * 读独立配置。
  *
@@ -119,50 +183,22 @@ export function readInstanceConfig(config) {
     return null
   }
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
-  // 字段级清洗（只取白名单，且去掉明显非法值）
-  const out = {}
-  for (const k of PERSISTED_KEYS) {
-    if (!(k in parsed)) continue
-    const v = parsed[k]
-    if (v === null || v === undefined) continue
-    // roots 是数组，单独清洗
-    if (k === 'roots') {
-      if (Array.isArray(v)) {
-        const arr = v.filter((x) => typeof x === 'string' && x.trim() !== '').map((x) => x.trim())
-        if (arr.length > 0) out.roots = arr
-      }
-      continue
-    }
-    if (typeof v === 'string' && v.trim() !== '') out[k] = v.trim()
-  }
-  return Object.keys(out).length > 0 ? out : null
+  return sanitizeFields(new Map(Object.entries(parsed)))
 }
 
 /**
  * 写独立配置（原子写 + 0600）。
  *
  * @param {object} values 要写的字段（按白名单过滤）
- * @param {object} [config] 用于解析 stateDir
+ * @param {object} [config] 用于解析 stateDir —— **必须传**，否则写默认目录、
+ *   而读的一方按 `config.stateDir` 找，两边对不上（v0.9.3 审查 M1 的成因）
  * @returns {{ok:boolean, file:string, error?:string}}
  */
 export function writeInstanceConfig(values, config) {
   const dir = resolveStateDir(config)
   const file = path.join(dir, INSTANCE_FILE_NAME)
   const src = values && typeof values === 'object' ? values : {}
-  const out = {}
-  for (const k of PERSISTED_KEYS) {
-    if (!(k in src)) continue
-    const v = src[k]
-    if (v === null || v === undefined) continue
-    if (k === 'roots') {
-      if (Array.isArray(v)) {
-        const arr = v.filter((x) => typeof x === 'string' && x.trim() !== '').map((x) => x.trim())
-        if (arr.length > 0) out.roots = arr
-      }
-      continue
-    }
-    if (typeof v === 'string' && v.trim() !== '') out[k] = v.trim()
-  }
+  const out = sanitizeFields(new Map(Object.entries(src))) ?? {}
 
   const tmp = `${file}.tmp-${process.pid}-${Date.now().toString(36)}`
   try {
@@ -193,15 +229,33 @@ export function writeInstanceConfig(values, config) {
  *
  * 例外：如果独立配置里**没有**某个字段，就用 loader config 的值。
  *
+ * ⚠ 这个优先级有一个副作用（v0.9.3 审查 M3）：用户手改 `cordis.patch.yml`
+ * 或 DSH 插件 UI 之后，**同名字段永远不生效**，而且没有任何提示 ——
+ * 与项目反复强调的"面板说 A、插件实际做 B 是最难排查的撕裂"同型。
+ * 所以这里把"被覆盖了哪些字段"回报给调用方，由它记日志/在面板展示。
+ *
  * @param {object} loaderConfig
  * @param {object} [opts]
- * @param {boolean} [opts.overlay] 读到的独立配置（避免重复读盘）
- * @returns {{config:object, source:object|null}}
+ * @param {object} [opts.overlay] 读到的独立配置（避免重复读盘）
+ * @returns {{config:object, source:object|null, shadowed:string[]}}
+ *   `shadowed` = 独立配置压住 loader 值的字段名（值本身不回报，避免日志泄密）
  */
 export function mergeInstanceConfig(loaderConfig, { overlay } = {}) {
   const base = loaderConfig && typeof loaderConfig === 'object' ? loaderConfig : {}
   let saved = overlay
   if (saved === undefined) saved = readInstanceConfig(base)
-  if (!saved) return { config: base, source: null }
-  return { config: { ...base, ...saved }, source: saved }
+  if (!saved) return { config: base, source: null, shadowed: [] }
+
+  const shadowed = []
+  for (const k of Object.keys(saved)) {
+    if (!(k in base)) continue // loader 没有 → 不算"覆盖"，是补全
+    const a = base[k]
+    const b = saved[k]
+    // 只在**值真的不同**时记 —— 否则每次启动都刷一堆无意义的"覆盖"
+    const differ = (typeof a === 'object' || typeof b === 'object')
+      ? JSON.stringify(a) !== JSON.stringify(b)
+      : a !== b
+    if (differ) shadowed.push(k)
+  }
+  return { config: { ...base, ...saved }, source: saved, shadowed }
 }

package/lib/listen-server.js

@@ -80,6 +80,30 @@ function isPrivateIp(ip) {
   )
 }
 
+/**
+ * 判定一个主机名/字面量地址是不是回环。
+ *
+ * ⚠ 这是**唯一的**回环判据（2026-10-20 收口）。此前 `lib/env-check.js` 的
+ * `isLoopbackOrigin`、`lib/hub/index.js` 的内联判断、`lib/client.js` 的前端
+ * 判断各写一份 —— 三份判据迟早分叉（C2 就是"两套地址分类"分叉的直接后果）。
+ * 新增调用方一律用这个，别再内联。
+ *
+ * @param {string} host 形如 `127.0.0.1` / `localhost` / `::1` / `[::1]`
+ * @returns {boolean}
+ */
+export function isLoopbackHost(host) {
+  if (typeof host !== 'string') return false
+  const h = host.trim().toLowerCase()
+  return h === '127.0.0.1' || h === 'localhost' || h === '::1' || h === '[::1]'
+}
+
+/** 一个地址的"可信程度"（0 最高）：Tailscale > RFC1918 > 其它。 */
+function scoreOf(address) {
+  if (isTailscaleIp(address)) return 0
+  if (isPrivateIp(address)) return 1
+  return 2
+}
+
 /**
  * 列出本机所有非内网回环的 IPv4（按优先级排序）。
  *
@@ -102,11 +126,15 @@ export function listCandidateAddresses() {
       const address = typeof info.address === 'string' ? info.address : ''
       if (address === '' || address.startsWith('169.254.')) continue // APIPA
       // 优先级：Tailscale(0) > 私网(1) > 其它(2)
-      const score = isTailscaleIp(address) ? 0 : isPrivateIp(address) ? 1 : 2
-      out.push({ address, family, iface, score })
+      out.push({ address, family, iface, score: scoreOf(address) })
     }
   }
-  out.sort((a, b) => a.score - b.score)
+  // 稳定排序（L6，2026-10-20）：同 score 时不能依赖 `os.networkInterfaces()`
+  // 的返回顺序 —— 那是平台相关的，同一台机器两次启动可能不同 → 绑定地址漂移。
+  // 用「接口名 → 地址」做次级键，保证同一台机器每次选出同一个地址。
+  out.sort((a, b) => (a.score - b.score)
+    || String(a.iface).localeCompare(String(b.iface))
+    || String(a.address).localeCompare(String(b.address)))
   return out
 }
 
@@ -159,7 +187,8 @@ export function resolveListenHost({ listenHost, candidates } = {}) {
  * @param {string} o.path WS 升级路径（必须精确匹配）
  * @param {(conn:import('./ws.js').WSConnection, req:import('node:http').IncomingMessage)=>void} o.onUpgrade
  * @param {string} [o.healthPath] 健康检查路径
- * @param {object} [o.healthBody] 健康检查返回体
+ * @param {object|((req:import('node:http').IncomingMessage)=>object)} [o.healthBody]
+ *   健康检查返回体；传函数可按调用者身份分级（匿名只回 `{ ok: true }`）
  * @param {(level:string,msg:string,extra?:object)=>void} [o.log]
  * @returns {Promise<{server:import('node:http').Server, host:string, port:number, close:()=>Promise<void>}>}
  */
@@ -180,8 +209,22 @@ export function startListenServer({
       try {
         const url = new URL(req.url || '/', 'http://localhost')
         if (req.method === 'GET' && url.pathname === healthPath) {
+          // healthBody 可以是对象，也可以是 `(req) => object`。
+          // 后者用于**按调用者身份分级**：匿名只回 `{ ok: true }`，
+          // 带正确口令才给插件名/角色/计数（v0.9.3 审查 L4 —— 这个端点
+          // 本来是无鉴权的，回 "plugin: dsh-remote-agent, role: hub"
+          // 等于给扫描器送指纹）。
+          let payload = healthBody
+          if (typeof healthBody === 'function') {
+            try {
+              payload = healthBody(req)
+            } catch (err) {
+              log('warn', 'health body threw', { error: String(err?.message ?? err) })
+              payload = { ok: false }
+            }
+          }
           res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
-          res.end(JSON.stringify(healthBody))
+          res.end(JSON.stringify(payload === undefined ? { ok: true } : payload))
           return
         }
       } catch {
@@ -225,13 +268,29 @@ export function startListenServer({
       }
     })
 
+    // listen 失败要 reject（调用方会 log 并降级）；listen **之后**的错误则
+    // 只能用日志 —— 那个 Promise 早已 resolve，再 reject 是空操作。
+    // 2026-10-20 修（L1）：原实现无条件 reject，导致运行期 socket 错误全被吞掉。
+    let settled = false
+
     server.on('error', (err) => {
       // listen 失败（端口占用 / 地址不可用）要**明确报出来** ——
       // 静默失败会让"副机连不上"变成又一个无头案。
-      reject(err)
+      if (!settled) {
+        settled = true
+        reject(err)
+        return
+      }
+      log('error', 'listen server error (runtime)', {
+        host,
+        port,
+        error: String(err?.message ?? err),
+        code: String(err?.code ?? ''),
+      })
     })
 
     server.listen(port, host, () => {
+      settled = true
       const addr = server.address()
       const actualPort = addr && typeof addr === 'object' ? addr.port : port
       log('info', 'node endpoint listening', { host, port: actualPort, path: upgradePath })

package/lib/setup-routes.js

@@ -31,7 +31,14 @@ import fs from 'node:fs'
 import path from 'node:path'
 import os from 'node:os'
 import { ERROR_CODE, RemoteAgentError } from './protocol.js'
-import { writePatchBlock } from './setup.js'
+import {
+  FORM_OWNED_KEYS,
+  extractPreservedConfig,
+  newNodeToken,
+  readManagedBlockBody,
+  upsertTokenInBlock,
+  writePatchBlock,
+} from './setup.js'
 // 角色解析必须**只有一份实现** —— 面板说"未配置"而插件实际在跑 hub，
 // 是最难排查的撕裂（v0.7.0 踩过）。所以这里直接复用 lib/index.js 的解析器。
 import { resolveRoleDetail } from './index.js'
@@ -39,6 +46,16 @@ import { resolveRoleDetail } from './index.js'
 // 所以每次写配置时也在 <stateDir>/instance.json 存一份（插件加载时合并回来）。
 import { writeInstanceConfig, readInstanceConfig } from './instance-config.js'
 
+/**
+ * 面板表单**管辖**的顶层 config 键由 `lib/setup.js` 的 `FORM_OWNED_KEYS` 定义
+ * （CLI 向导与测试共用同一份，避免两处各写一份再分叉 —— 本版审查的 C2/L2
+ * 就是这么来的）。所以这里直接用那份常量，不再本地复制。
+ *
+ * 其余的一切（nodeToken / uiPullRoot / relay / listenHost / listenPort /
+ * agentMode…）在重写托管块时必须**原样保留** —— 否则用户在面板点一次保存，
+ * 凭证与设置就被静默抹掉（已实证）。
+ */
+
 /** 引导路由的前缀。与 hub 的 `/api/remote-agent/ui` 分开 —— 未配置时后者不存在。 */
 export const SETUP_API_PREFIX = '/api/remote-agent/setup'
 
@@ -249,6 +266,10 @@ export function registerSetupRoutes(ctx, config = {}, log = () => {}) {
         hubUrl: typeof config.hubUrl === 'string' ? config.hubUrl : '',
         relayUrl: typeof config.relayUrl === 'string' ? config.relayUrl : '',
         roots: Array.isArray(config.roots) ? config.roots : [],
+        // H3（2026-10-20）：面板必须知道"有没有口令"。此前完全不回显 → 用户
+        // 走面板配完 hub 永远是空口令，而独立监听因此只能绑回环、副机连不上。
+        // ⚠ 只回布尔，绝不回 token 本身（与 /config 的披露边界一致）。
+        tokenSet: typeof config.nodeToken === 'string' && config.nodeToken.trim() !== '',
       },
       // 写入目标（让用户知道改的是哪个文件）
       patchFile: currentPatchFile(),
@@ -349,7 +370,28 @@ export function registerSetupRoutes(ctx, config = {}, log = () => {}) {
 
     const blockYaml = `${lines.join('\n')}\n`
     const file = currentPatchFile()
-    const result = writePatchBlock({ file, blockYaml, force: body.force === true })
+
+    // ── 保留本次表单不管辖的字段（H2，2026-10-20）────────────────────
+    //
+    // 托管块是**整体替换**的：新块进来，旧块整段消失。而本表单只提交
+    // role/nodeId/transportMode/hubUrl/relayUrl/roots —— 于是用户在面板点一次
+    // 「保存」，托管块里的 nodeToken / uiPullRoot / relay / listenHost /
+    // listenPort 全部被静默删掉（已实证）。
+    //
+    // 这里把旧块里"不归表单管"的行原样搬到新块末尾（文本级搬运，保留用户的
+    // 格式与顺序；不解析 YAML，避免零依赖被打破）。
+    let preservedLines = []
+    try {
+      const existing = readManagedBlockBody(fs.readFileSync(file, 'utf8'))
+      preservedLines = extractPreservedConfig(existing, FORM_OWNED_KEYS)
+    } catch {
+      // 首次写入（文件不存在）—— 没有可保留的
+    }
+    const blockWithPreserved = preservedLines.length > 0
+      ? `${blockYaml.replace(/\s+$/, '')}\n${preservedLines.join('\n')}\n`
+      : blockYaml
+
+    const result = writePatchBlock({ file, blockYaml: blockWithPreserved, force: body.force === true })
     if (result.ok !== true) {
       // 冲突（有手写条目）是可预期的用户可修复状态，单独给个 code 让面板
       // 能显示"替换手写配置"按钮，而不是把整段错误文案丢给用户。
@@ -371,15 +413,24 @@ export function registerSetupRoutes(ctx, config = {}, log = () => {}) {
     // `<stateDir>/instance.json`。插件 `apply()` 时会把它合并回来
     // （独立配置优先）。这样 DSH 怎么重写 patch 文件都不影响角色配置。
     //
-    // 失败不阻塞：独立配置写不进去时，patch 文件那层仍然生效（只是不抗冲掉）。
+    // ⚠ 2026-10-20 修两处：
+    //   · **必须传 config**（第二个参数）。此前漏了 → 写默认目录、读自定义
+    //     stateDir → 配了 stateDir 的机器持久化完全失效（M1，已复现）。
+    //   · 先铺上已有值再覆盖表单字段，否则每次保存都会把 nodeToken / relay /
+    //     listenHost 这类"表单不管辖"的字段从 instance.json 里抹掉（H2 的另一半）。
+    const prev = readInstanceConfig(config) ?? {}
+    const nextPersist = { ...prev }
+    // 表单管辖的键以本次提交为准（这样"清空"也能真正生效）
+    for (const k of FORM_OWNED_KEYS) delete nextPersist[k]
     const persisted = writeInstanceConfig({
+      ...nextPersist,
       role,
       nodeId: str(body.nodeId),
       transportMode: str(body.transportMode) || undefined,
       hubUrl: str(body.hubUrl) || undefined,
       relayUrl: str(body.relayUrl) || undefined,
       roots,
-    })
+    }, config)
     if (persisted.ok !== true) {
       applyWarnings.push(`独立配置写入失败（${persisted.error}）—— 角色配置仍写进了 patch 文件，`
         + '但下次 DSH 重写该文件时可能丢失，建议重启后到面板确认一次。')
@@ -403,5 +454,90 @@ export function registerSetupRoutes(ctx, config = {}, log = () => {}) {
     })
   })
 
+  // ── 生成 / 轮换入网口令（nodeToken）──────────────────────────────
+  //
+  // ═══════════════════════════════════════════════════════════════════════════
+  // 为什么必须有这条（v0.9.3 审查 H3，2026-10-20）
+  // ═══════════════════════════════════════════════════════════════════════════
+  //
+  // CLI 向导（`dsh-remote-setup --role hub`）会生成 `nt_` 开头的口令，
+  // **面板这条路却完全没有** —— YAML 里不写 nodeToken、instance.json 里也不写。
+  //
+  // 后果链（实测）：
+  //   面板配 hub → nodeToken 空 → 独立监听按安全策略只能绑回环
+  //   → 副机连不上 → 体检报"需要口令" → 而面板没有任何生成入口
+  //   → 用户只能去手改 patch → 被 DSH 重写冲掉 → 死循环
+  //
+  // 安全边界：
+  //   · 只对**回环请求**生成并回显明文（与 pair-info 的 token 披露边界一致）
+  //   · 明文只回这一次，之后任何接口都不再吐 token（`/state` 只给 tokenSet）
+  //   · 走的是同一套 patch 写盘（备份 / 校验 / 回滚）
+  route(`${SETUP_API_PREFIX}/rotate-token`, async (req, res) => {
+    if (req.method !== 'POST') return writeJson(res, 405, { error: 'method' })
+
+    const ra = String(req.socket?.remoteAddress ?? '')
+    const loopback = ra === '127.0.0.1' || ra === '::1' || ra === '::ffff:127.0.0.1'
+    if (!loopback) {
+      return writeJson(res, 403, {
+        error: 'loopback-only',
+        message: '生成口令只能在主机本机打开的面板里操作（避免局域网内其他人拿到凭证）',
+      })
+    }
+
+    const token = newNodeToken()
+    const file = currentPatchFile()
+
+    // 只改 nodeToken 这一行，其余字段（roots / uiPullRoot / relay / listen*）原样不动
+    let blockBody = ''
+    try {
+      blockBody = readManagedBlockBody(fs.readFileSync(file, 'utf8'))
+    } catch {
+      // 还没有 patch 文件：生成一个最小的托管块，role 取当前生效角色
+    }
+    if (blockBody.trim() === '') {
+      const detail = resolveRoleDetail(config)
+      const r = detail.role === 'worker' ? 'worker' : 'hub'
+      const inject = r === 'worker'
+        ? "['tools', 'agentLoop', 'sessions']"
+        : "['webServer', 'tools', 'systemPrompt']"
+      blockBody = `- id: remote-agent\n  name: dsh-remote-agent\n  inject: ${inject}\n  config:\n    role: ${r}\n`
+    }
+
+    const result = writePatchBlock({
+      file,
+      blockYaml: upsertTokenInBlock(blockBody, token),
+      force: false,
+    })
+    if (result.ok !== true) {
+      const conflict = /手写的 remote-agent 条目/.test(String(result.error ?? ''))
+      return writeJson(res, conflict ? 409 : 400, {
+        error: conflict ? 'handwritten-conflict' : 'write-failed',
+        message: result.error,
+        file: result.file,
+      })
+    }
+
+    // instance.json 也存一份（这一层 DSH 冲不掉）—— 同样保留已有字段
+    const prev = readInstanceConfig(config) ?? {}
+    const persisted = writeInstanceConfig({ ...prev, nodeToken: token }, config)
+
+    log('info', 'node token rotated', {
+      file: result.file,
+      instance: persisted.ok === true ? persisted.file : null,
+      instanceError: persisted.ok === true ? undefined : persisted.error,
+    })
+
+    writeJson(res, 200, {
+      ok: true,
+      // 明文只此一次：面板要提示用户"复制保存"，之后不再回显
+      token,
+      file: result.file,
+      backup: result.backup,
+      instanceFile: persisted.ok === true ? persisted.file : null,
+      note: '口令已写入。**重启 DSH 后生效**；副机需要用新口令重新配对。'
+        + '这串口令只显示这一次，请立即复制保存。',
+    })
+  })
+
   return disposers
 }