dsh-remote-agent 0.9.7 → 0.9.8

package/lib/node/fs-service.js

@@ -43,6 +43,17 @@ export const TREE_DEFAULT_DEPTH = 3
 export const TREE_MAX_ENTRIES = 2000
 /** ls 单页条目上限。 */
 export const LS_PAGE_MAX = 2000
+/**
+ * 单次 write 的内容上限（2026-10-20）。
+ *
+ * 为什么要有：写操作是本插件第二个主动放宽边界的能力。没有上限的话，
+ * 一次 `remote_write` 就能把副机磁盘写满 —— 而副机是常驻进程，
+ * 磁盘满会让任务、日志、状态文件全部失败。
+ *
+ * 8MB 与 `READABLE_FILE_MAX` 同量级：能覆盖绝大多数配置文件/脚本/文档，
+ * 又不至于一次写爆磁盘。
+ */
+export const WRITE_MAX_BYTES = 8 * 1024 * 1024
 /** 二进制嗅探窗口：前 64 字节出现 NUL 即视为二进制。 */
 const SNIFF_BYTES = 64
 
@@ -55,6 +66,99 @@ export class FsError extends Error {
   }
 }
 
+/**
+ * 解析**待写入**的路径（2026-10-20，写操作专用）。
+ *
+ * 与 `resolveAny` 的关键区别：**目标可以不存在**。
+ *
+ * ── 为什么不能用 resolveAny ─────────────────────────────────────────────
+ *
+ * `resolveAny` 先 `realpathSync(requested)` —— 那要求路径已经存在。
+ * 只读工具这样做是对的（"读一个不存在的文件没有借口"），但写操作的目标
+ * **本来就是要新建的**，用同一套解析会让 `remote_write` 100% 失败。
+ * （第一版就是这么写的，实测立刻暴露：`path not found: .../a.txt`。）
+ *
+ * ── 安全怎么做 ──────────────────────────────────────────────────────────
+ *
+ * 目标不存在 → 从它**向上找到第一个存在的祖先**，对那个祖先做 realpath，
+ * 再校验它在 roots 内。这样：
+ *   · `D:\work\new.txt`（不存在）→ 校验 `D:\work` 在 roots 内 → 允许
+ *   · `D:\work\link\to\outside.txt`（link 指向 roots 外）→ 祖先 realpath
+ *     解析到 roots 外 → 拒绝
+ *   · `D:\etc\passwd` → 祖先 `D:\etc` 不在 roots 内 → 拒绝
+ *
+ * 目标**已存在** → 直接用 realpath（与只读工具同口径，防软链逃逸）。
+ *
+ * @param {string} requested 绝对路径
+ * @param {object} cfg { roots, caseInsensitive, denyPaths }
+ * @returns {string} 规范化后的绝对路径（可能是尚不存在的路径）
+ */
+function resolveWritable(requested, cfg) {
+  const { roots, caseInsensitive } = cfg
+  if (typeof requested !== 'string' || requested === '') {
+    throw new FsError('path is required', ERROR_CODE.WORKSPACE_DENIED)
+  }
+  if (!path.isAbsolute(requested)) {
+    throw new FsError(`path must be absolute: ${requested}`, ERROR_CODE.WORKSPACE_DENIED)
+  }
+  // denyPaths 先查原始形态（防"通过不存在的路径绕过 denyPaths"）
+  if (entryDenied(requested, cfg)) {
+    throw new FsError(`path denied: ${requested}`, ERROR_CODE.WORKSPACE_DENIED)
+  }
+
+  const real = (p) => (fs.realpathSync.native ? fs.realpathSync.native(p) : fs.realpathSync(p))
+
+  let checkPath
+  if (fs.existsSync(requested)) {
+    // 已存在：走 realpath（与只读同口径，能识破软链逃逸）
+    try {
+      checkPath = real(requested)
+    } catch {
+      throw new FsError(`cannot resolve path: ${requested}`, ERROR_CODE.WORKSPACE_DENIED)
+    }
+  } else {
+    // 不存在：向上找第一个存在的祖先，对它 realpath，再把剩余段接回去
+    let probe = path.dirname(requested)
+    const tail = [path.basename(requested)]
+    // 上限 64 层，防止异常深的路径拖慢
+    for (let i = 0; i < 64; i += 1) {
+      if (fs.existsSync(probe)) break
+      const parent = path.dirname(probe)
+      if (parent === probe) {
+        throw new FsError(`no existing ancestor for: ${requested}`, ERROR_CODE.WORKSPACE_DENIED)
+      }
+      tail.unshift(path.basename(probe))
+      probe = parent
+    }
+    let probeReal
+    try {
+      probeReal = real(probe)
+    } catch {
+      throw new FsError(`cannot resolve ancestor: ${probe}`, ERROR_CODE.WORKSPACE_DENIED)
+    }
+    checkPath = path.join(probeReal, ...tail)
+  }
+
+  const allowed = (roots ?? []).map((r) => {
+    let base = r
+    try {
+      base = real(r)
+    } catch {
+      // 与 resolveWorkspace 同口径：不可达的根保持原样，后面照样拒一切子路径
+    }
+    return normalizePath(base, { caseInsensitive })
+  })
+  const norm = normalizePath(checkPath, { caseInsensitive })
+  const ok = allowed.some((r) => norm === r || norm.startsWith(`${r}/`))
+  if (!ok) {
+    throw new FsError(
+      `path outside allowed roots: ${checkPath}`,
+      ERROR_CODE.WORKSPACE_DENIED,
+    )
+  }
+  return checkPath
+}
+
 /**
  * 解析"可以是文件也可以是目录"的路径：realpath + roots 前缀 + denyPaths。
  * 与 resolveWorkspace 的差异只在两点：不要求是目录；不存在时直接拒
@@ -183,7 +287,7 @@ export function createFsService(cfg) {
      * 单次文本量 ≤ READ_TEXT_MAX；二进制模式：只回 sha256/size/头部预览。
      */
     read({ path: p, offset = 0, limit = 500 } = {}) {
-      const file = resolveAny(p, conf)
+      const file = resolveWritable(p, conf)
       let st
       try {
         st = fs.statSync(file)
@@ -518,5 +622,176 @@ export function createFsService(cfg) {
         items,
       }
     },
+
+    /* ═══════════════════════════════════════════════════════════════════════
+     * 写操作（2026-10-20，用户要求"更多工具 = 文件写操作"）
+     * ═══════════════════════════════════════════════════════════════════════
+     *
+     * ⚠⚠ **这是本插件第二个主动放宽边界的能力**（第一个是 SMB 共享）。
+     * 前四个 fs 工具全是只读；从这里开始会**改副机的文件**。
+     *
+     * ── 护栏（每一道都对应一种真实事故）────────────────────────────────
+     *
+     *   1. **路径必须在 roots 内** —— 复用 resolveAny（realpath 展开 8.3 短名
+     *      与符号链接，再比 roots 前缀）。写操作**额外**要求目标父目录也
+     *      在 roots 内（防"roots 内的路径经过软链写到外面"）。
+     *   2. **默认不覆盖** —— write 遇到已存在的文件直接拒绝，要覆盖必须显式
+     *      传 `overwrite: true`。这条防"AI 手滑清空已有文件"。
+     *   3. **单次写入有大小上限** —— 防一次 write 把副机磁盘写满。
+     *   4. **delete 只删文件/空目录** —— 不做递归删除。递归删除太容易造成
+     *      不可逆损失，真有需要让用户用 exec 显式 rm。
+     *   5. **denyPaths 生效** —— 与只读工具同一条规则。
+     */
+
+    /** 写文件（默认不覆盖）。 */
+    write({ path: p, content, encoding = 'utf8', overwrite = false } = {}) {
+      if (typeof content !== 'string') {
+        throw new FsError('content must be a string', ERROR_CODE.WORKSPACE_DENIED)
+      }
+      const bytes = Buffer.byteLength(content, 'utf8')
+      if (bytes > WRITE_MAX_BYTES) {
+        throw new FsError(
+          `content too large: ${bytes} bytes (max ${WRITE_MAX_BYTES})`,
+          ERROR_CODE.ARTIFACT_TOO_LARGE,
+        )
+      }
+      const file = resolveWritable(p, conf)
+      // 目标**父目录**也必须在 roots 内：防"roots 内的路径经软链写到外面"
+      const dir = path.dirname(file)
+      let dirReal
+      try {
+        dirReal = fs.realpathSync.native ? fs.realpathSync.native(dir) : fs.realpathSync(dir)
+      } catch {
+        throw new FsError(`parent directory not found: ${dir}`, ERROR_CODE.ARTIFACT_MISSING)
+      }
+      if (entryDenied(dirReal, conf)) {
+        throw new FsError(`parent directory denied: ${dirReal}`, ERROR_CODE.WORKSPACE_DENIED)
+      }
+      const exists = fs.existsSync(file)
+      if (exists && overwrite !== true) {
+        throw new FsError(
+          `file already exists: ${file}（如需覆盖请显式传 overwrite: true）`,
+          ERROR_CODE.ARTIFACT_DENIED,
+        )
+      }
+      if (exists) {
+        let st
+        try {
+          st = fs.statSync(file)
+        } catch {
+          st = null
+        }
+        if (st && st.isDirectory()) {
+          throw new FsError(`target is a directory: ${file}`, ERROR_CODE.WORKSPACE_DENIED)
+        }
+      }
+      // 原子写：临时文件 + rename（与 templates.js 同款，避免半截文件）
+      const tmp = `${file}.dshra-tmp-${process.pid}-${Date.now().toString(36)}`
+      try {
+        fs.writeFileSync(tmp, content, { encoding, mode: 0o600 })
+        fs.renameSync(tmp, file)
+      } catch (err) {
+        try {
+          fs.rmSync(tmp, { force: true })
+        } catch {
+          /* 清理失败不掩盖原错误 */
+        }
+        throw new FsError(`write failed: ${String(err?.message ?? err)}`, ERROR_CODE.INTERNAL)
+      }
+      return { path: file, bytes, overwritten: exists }
+    },
+
+    /** 建目录（递归）。已存在视为成功（幂等）。 */
+    mkdir({ path: p } = {}) {
+      const dir = resolveWritable(p, conf)
+      const existed = fs.existsSync(dir)
+      try {
+        fs.mkdirSync(dir, { recursive: true })
+      } catch (err) {
+        throw new FsError(`mkdir failed: ${String(err?.message ?? err)}`, ERROR_CODE.INTERNAL)
+      }
+      return { path: dir, created: !existed }
+    },
+
+    /** 移动/重命名（同盘 rename；跨盘明确报错，不做静默复制）。 */
+    move({ from, to, overwrite = false } = {}) {
+      const src = resolveWritable(from, conf)
+      const dst = resolveWritable(to, conf)
+      const dstDir = path.dirname(dst)
+      let dstDirReal
+      try {
+        dstDirReal = fs.realpathSync.native ? fs.realpathSync.native(dstDir) : fs.realpathSync(dstDir)
+      } catch {
+        throw new FsError(`target directory not found: ${dstDir}`, ERROR_CODE.ARTIFACT_MISSING)
+      }
+      if (entryDenied(dstDirReal, conf)) {
+        throw new FsError(`target directory denied: ${dstDirReal}`, ERROR_CODE.WORKSPACE_DENIED)
+      }
+      if (!fs.existsSync(src)) {
+        throw new FsError(`source not found: ${src}`, ERROR_CODE.ARTIFACT_MISSING)
+      }
+      if (fs.existsSync(dst) && overwrite !== true) {
+        throw new FsError(
+          `target already exists: ${dst}（如需覆盖请显式传 overwrite: true）`,
+          ERROR_CODE.ARTIFACT_DENIED,
+        )
+      }
+      try {
+        fs.renameSync(src, dst)
+      } catch (err) {
+        // EXDEV = 跨设备。不做静默复制 —— 大文件会卡住且语义不同
+        if (err?.code === 'EXDEV') {
+          throw new FsError(
+            `cross-device move not supported: ${src} -> ${dst}（请改用 exec 的 cp/mv）`,
+            ERROR_CODE.INTERNAL,
+          )
+        }
+        throw new FsError(`move failed: ${String(err?.message ?? err)}`, ERROR_CODE.INTERNAL)
+      }
+      return { from: src, to: dst }
+    },
+
+    /**
+     * 删除**单个文件或空目录**。
+     *
+     * ⚠ 刻意**不做递归删除** —— 那太容易造成不可逆损失。
+     * 真有需要让用户用 exec 自己跑 rm -rf（那是显式动作，有命令可查）。
+     */
+    delete({ path: p } = {}) {
+      const target = resolveWritable(p, conf)
+      let st
+      try {
+        st = fs.lstatSync(target)
+      } catch {
+        throw new FsError(`path not found: ${target}`, ERROR_CODE.ARTIFACT_MISSING)
+      }
+      // 符号链接只删链接本身（lstat 不跟随）—— 防"删链接把目标删了"
+      if (st.isDirectory()) {
+        let entries
+        try {
+          entries = fs.readdirSync(target)
+        } catch (err) {
+          throw new FsError(`readdir failed: ${String(err?.message ?? err)}`, ERROR_CODE.INTERNAL)
+        }
+        if (entries.length > 0) {
+          throw new FsError(
+            `directory not empty: ${target}（只删空目录；非空目录请用 exec 显式删除）`,
+            ERROR_CODE.ARTIFACT_DENIED,
+          )
+        }
+        try {
+          fs.rmdirSync(target)
+        } catch (err) {
+          throw new FsError(`rmdir failed: ${String(err?.message ?? err)}`, ERROR_CODE.INTERNAL)
+        }
+        return { path: target, kind: 'dir' }
+      }
+      try {
+        fs.unlinkSync(target)
+      } catch (err) {
+        throw new FsError(`unlink failed: ${String(err?.message ?? err)}`, ERROR_CODE.INTERNAL)
+      }
+      return { path: target, kind: st.isSymbolicLink() ? 'link' : 'file' }
+    },
   }
 }

package/lib/node/index.js

@@ -57,6 +57,8 @@ import { TaskStore } from './task-store.js'
 // 远程文件工具集（提案 #25）：ls/read/grep/tree 只读实现，与任务链路共用
 // roots / denyPaths / caseInsensitive 三个配置（同一个安全边界，两处入口）。
 import { createFsService } from './fs-service.js'
+// 进程与端口诊断（2026-10-20）：ps/port 只读，kill 不可逆（自带三道护栏）。
+import { createProcessService } from './process-service.js'
 // 工作区 SMB 共享（2026-10-17）：只探测 + 生成命令，不执行（需管理员）。
 import {
   SHARE_ACCESS,
@@ -578,6 +580,18 @@ function startWorker(ctx, config) {
   // 安全边界，两处入口。只读实现，见 lib/node/fs-service.js 头注释。
   const fsService = createFsService({ roots, denyPaths, caseInsensitive })
 
+  /**
+   * 进程与端口诊断（2026-10-20）。
+   *
+   * 与 fsService 分开：进程操作**没有路径概念**，所以 roots/denyPaths
+   * 那套护栏不适用。它自己的护栏全在 `lib/node/process-service.js` 里
+   * （kill 的 confirm + 拒杀自身/父进程/系统关键进程）。
+   *
+   * 为什么不带 cfg：这里不需要任何用户配置 —— 少一个配置面就少一类
+   * 配置错误。若将来要加白名单，再引入 cfg。
+   */
+  const processService = createProcessService()
+
   /* 3) 任务仓库 ------------------------------------------------------- */
   let store
   try {
@@ -1003,7 +1017,17 @@ function startWorker(ctx, config) {
    */
   function handleFsReq(frame, d) {
     const op = typeof d.op === 'string' ? d.op : ''
-    const ops = { ls: 'ls', read: 'read', grep: 'grep', tree: 'tree' }
+    // 只读四项 + 写操作四项（2026-10-20）。
+    // ⚠ 写操作由 hub 工具层要求 `confirm: 'yes'`，副机侧只做路径与内容护栏。
+    const ops = {
+      ls: 'ls', read: 'read', grep: 'grep', tree: 'tree',
+      write: 'write', mkdir: 'mkdir', move: 'move', delete: 'delete',
+      // 进程与端口诊断（2026-10-20）：只读的 list/port 与不可逆的 kill。
+      // ⚠ 它们**不受 roots 约束**（进程没有"路径"概念），
+      // 所以护栏全部落在 `lib/node/process-service.js` 内部
+      // （kill 的 confirm + 拒杀自身/父进程/系统进程）。
+      ps: 'ps', port: 'port', kill: 'kill',
+    }
     const fn = ops[op]
     if (!fn) {
       send(NODE_TO_HUB.FS_RES, { replyTo: frame.id, ok: false, code: ERROR_CODE.WORKSPACE_DENIED, message: `unknown fs op: ${op || '(empty)'}` })
@@ -1011,7 +1035,10 @@ function startWorker(ctx, config) {
     }
     const started = Date.now()
     swallow(Promise.resolve().then(() => {
-      const result = fsService[fn](d)
+      // 进程诊断走独立的 processService；文件操作走 fsService。
+      // 分开是因为两者的安全模型完全不同（路径护栏 vs 进程护栏）。
+      const svc = (op === 'ps' || op === 'port' || op === 'kill') ? processService : fsService
+      const result = svc[fn](d)
       logger.debug('fs op done', { op, ms: Date.now() - started, nodeId })
       send(NODE_TO_HUB.FS_RES, { replyTo: frame.id, ok: true, result })
     }).catch((err) => {