zen-gitsync 2.11.39 → 2.12.3

package/src/ui/server/utils/pathGuard.js

@@ -0,0 +1,155 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+/**
+ * 路径越界检查中间件 / 工具
+ *
+ * 用法：
+ *   // 1. 中间件模式：自动从 req.query.path 提取并校验
+ *   router.get('/api/foo', pathGuard('path'), handler)
+ *
+ *   // 2. 工具函数：在 handler 里手动校验
+ *   const safePath = ensureWithinCwd(userPath, cwd)
+ *
+ * 防护：
+ *   - 解析 `..`、相对路径
+ *   - 拒绝以 `..` 开头或解析后是绝对路径的相对路径
+ *   - Windows 大小写不敏感
+ *   - 真实路径 (realpath) 防符号链接
+ *
+ * @typedef {Object} PathGuardOptions
+ * @property {string} field - 从 req.query / req.body 取的字段名（默认 'path'）
+ * @property {boolean} [allowMissing] - 字段缺失时是否通过（默认 false）
+ * @property {boolean} [realpath] - 是否用 fs.realpath 进一步防符号链接（默认 false）
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+
+const isWindows = process.platform === 'win32'
+
+/**
+ * 把 user 输入路径解析成"在 cwd 内的绝对路径"，越界时返回 null
+ *
+ * @param {string} input - 用户提供的路径（相对 / 绝对 / 含 .. / 符号链接）
+ * @param {string} cwd - 允许的根目录（当前项目目录）
+ * @param {{ realpath?: boolean }} [opts]
+ * @returns {Promise<{ safePath: string, realPath: string | null } | null>}
+ *   - null 表示越界
+ *   - safePath: 用于后续 path.resolve 等操作的绝对路径
+ *   - realPath: realpath 结果（如果 opts.realpath=true 且文件存在）
+ */
+export async function ensureWithinCwd(input, cwd, opts = {}) {
+  if (typeof input !== 'string' || !input) return null
+  if (typeof cwd !== 'string' || !cwd) return null
+
+  let resolved
+  try {
+    resolved = path.resolve(cwd, input)
+  } catch {
+    return null
+  }
+
+  // path.relative 返回以 .. 开头的字符串代表越界（其它平台绝对路径返回绝对路径本身）
+  const rel = path.relative(cwd, resolved)
+  if (rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))) {
+    // 在 cwd 内（相等或子路径）
+  } else {
+    return null
+  }
+
+  // Windows 大小写不敏感：把 cwd 和 resolved 都转小写再比一次，确保 \ 不会绕过
+  if (isWindows) {
+    const lowerCwd = cwd.toLowerCase()
+    const lowerResolved = resolved.toLowerCase()
+    if (!lowerResolved.startsWith(lowerCwd)) {
+      return null
+    }
+  }
+
+  let realPath = null
+  if (opts.realpath) {
+    try {
+      realPath = await fs.realpath(resolved)
+      // realpath 后再校验一次（符号链接可能指向 cwd 之外）
+      const relReal = path.relative(cwd, realPath)
+      const isOutside = relReal === '..' || relReal.startsWith('..' + path.sep) || path.isAbsolute(relReal)
+      if (isOutside) return null
+      if (isWindows && !realPath.toLowerCase().startsWith(cwd.toLowerCase())) return null
+    } catch {
+      // 文件不存在 / 无权限：保持 null，让调用者决定
+    }
+  }
+
+  return { safePath: resolved, realPath }
+}
+
+/**
+ * Express 中间件工厂
+ *
+ * @param {string} cwd - 当前项目根
+ * @param {string | string[]} [fields] - 要校验的字段名（默认 'path'，支持数组多字段）
+ * @param {{ realpath?: boolean }} [opts]
+ */
+export function pathGuard(cwd, fields = 'path', opts = {}) {
+  const fieldList = Array.isArray(fields) ? fields : [fields]
+  return async (req, res, next) => {
+    try {
+      for (const field of fieldList) {
+        const raw = req.query?.[field] ?? req.body?.[field]
+        if (raw === undefined || raw === null || raw === '') {
+          if (opts.allowMissing) continue
+          return res.status(400).json({ success: false, error: `缺少 ${field} 参数` })
+        }
+        const result = await ensureWithinCwd(String(raw), cwd, opts)
+        if (!result) {
+          return res.status(403).json({ success: false, error: `禁止访问工作目录以外的文件: ${raw}` })
+        }
+        // 把校验后的安全路径挂到 res.locals，handler 拿 res.locals.safePath 用
+        res.locals.safePath = result.safePath
+        res.locals.safeRealPath = result.realPath
+      }
+      next()
+    } catch (e) {
+      res.status(500).json({ success: false, error: e.message })
+    }
+  }
+}
+
+/**
+ * 同步版本：只做路径解析校验，不做 realpath。用于不需要 fs 的纯路径场景
+ * @returns {string|null} 安全路径或 null
+ */
+export function ensureWithinCwdSync(input, cwd) {
+  if (typeof input !== 'string' || !input) return null
+  if (typeof cwd !== 'string' || !cwd) return null
+
+  let resolved
+  try {
+    resolved = path.resolve(cwd, input)
+  } catch {
+    return null
+  }
+
+  const rel = path.relative(cwd, resolved)
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return null
+
+  if (isWindows) {
+    const lowerCwd = cwd.toLowerCase()
+    const lowerResolved = resolved.toLowerCase()
+    if (!lowerResolved.startsWith(lowerCwd)) return null
+  }
+
+  return resolved
+}

package/src/ui/server/utils/pathGuard.test.js

@@ -0,0 +1,138 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// 路径越界检查单元测试（用 node:test 内置）
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { ensureWithinCwd, ensureWithinCwdSync, pathGuard } from '../utils/pathGuard.js'
+
+const cwd = process.platform === 'win32' ? 'E:\\project' : '/tmp/project'
+
+test('合法路径在 cwd 内', async () => {
+  const r = await ensureWithinCwd('src/foo.ts', cwd)
+  assert.ok(r, '应返回结果')
+  assert.match(r.safePath, /[\\/]project[\\/]src[\\/]foo\.ts$/)
+})
+
+test('合法绝对路径在 cwd 内', async () => {
+  const absInCwd = process.platform === 'win32' ? 'E:\\project\\sub' : '/tmp/project/sub'
+  const r = await ensureWithinCwd(absInCwd, cwd)
+  assert.ok(r, '应通过')
+  assert.equal(r.safePath, absInCwd)
+})
+
+test('../ 父目录逃逸被拒绝', async () => {
+  const r = await ensureWithinCwd('../etc/passwd', cwd)
+  assert.equal(r, null, '../ 应该被拒')
+})
+
+test('cwd 的同级目录（startsWith 假阳性）被拒绝', async () => {
+  const evil = process.platform === 'win32' ? 'E:\\project-evil' : '/tmp/project-evil'
+  const r = await ensureWithinCwd(evil, cwd)
+  assert.equal(r, null, '同名前缀目录应该被拒')
+})
+
+test('绝对路径在 cwd 外被拒', async () => {
+  const outside = process.platform === 'win32' ? 'C:\\Windows\\System32' : '/etc/passwd'
+  const r = await ensureWithinCwd(outside, cwd)
+  assert.equal(r, null, '绝对外部路径应该被拒')
+})
+
+test('空字符串 / null / undefined 被拒', async () => {
+  assert.equal(await ensureWithinCwd('', cwd), null)
+  assert.equal(await ensureWithinCwd(null, cwd), null)
+  assert.equal(await ensureWithinCwd(undefined, cwd), null)
+  assert.equal(await ensureWithinCwd(123, cwd), null)
+})
+
+test('多重 ../ 也被拒', async () => {
+  const r = await ensureWithinCwd('../../../../etc/passwd', cwd)
+  assert.equal(r, null)
+})
+
+test('相对 cwd 自身（.）允许', async () => {
+  const r = await ensureWithinCwd('.', cwd)
+  assert.ok(r, '点 应解析为 cwd 本身')
+})
+
+test('Windows 反斜杠与正斜杠混用允许', async () => {
+  if (process.platform !== 'win32') return
+  const r = await ensureWithinCwd('src\\sub/foo.ts', cwd)
+  assert.ok(r)
+})
+
+test('Windows 大小写不敏感', async () => {
+  if (process.platform !== 'win32') return
+  const r = await ensureWithinCwd('SRC/FOO.TS', 'E:\\Project')
+  assert.ok(r, 'Windows 下大小写不敏感应允许')
+})
+
+test('sync 版本对 .. 同样拒绝', () => {
+  assert.equal(ensureWithinCwdSync('../foo', cwd), null)
+  const r = ensureWithinCwdSync('sub/file', cwd)
+  assert.ok(r)
+})
+
+test('中间件: 合法 path 通过 + 挂到 res.locals.safePath', async () => {
+  let nextCalled = false
+  const req = { query: { path: 'src/foo.ts' } }
+  const res = {
+    locals: {},
+    status() { return this },
+    json() { return this },
+  }
+  await pathGuard(cwd)(req, res, () => { nextCalled = true })
+  assert.equal(nextCalled, true)
+  assert.match(res.locals.safePath, /[\\/]src[\\/]foo\.ts$/)
+})
+
+test('中间件: 越界 path 返回 403', async () => {
+  let nextCalled = false
+  let statusCode = 0
+  let body = null
+  const req = { query: { path: '../etc/passwd' } }
+  const res = {
+    locals: {},
+    status(c) { statusCode = c; return this },
+    json(b) { body = b; return this },
+  }
+  await pathGuard(cwd)(req, res, () => { nextCalled = true })
+  assert.equal(nextCalled, false)
+  assert.equal(statusCode, 403)
+  assert.match(body.error, /禁止访问/)
+})
+
+test('中间件: 缺字段返回 400', async () => {
+  let statusCode = 0
+  const req = { query: {} }
+  const res = {
+    locals: {},
+    status(c) { statusCode = c; return this },
+    json() { return this },
+  }
+  await pathGuard(cwd)(req, res, () => {})
+  assert.equal(statusCode, 400)
+})
+
+test('中间件: 多字段校验（rename 用）', async () => {
+  let nextCalled = false
+  const req = { query: { oldPath: 'src/a.ts', newPath: '../b.ts' } }
+  const res = {
+    locals: {},
+    status() { return this },
+    json() { return this },
+  }
+  await pathGuard(cwd, ['oldPath', 'newPath'])(req, res, () => { nextCalled = true })
+  assert.equal(nextCalled, false, 'newPath 越界应拒')
+})

package/src/ui/server/utils/randomStartPort.js

@@ -1,37 +1,51 @@
-// 随机起点端口选择
-// 默认：避免与系统保留 / 常见服务端口重叠，在较宽的"用户态"范围里随机挑一个起点
-// 然后由 startServerOnAvailablePort 在该起点基础上顺序往上扫描 EADDRINUSE
-// 覆盖：环境变量 PORT 强制使用固定端口（向后兼容 + 便于书签/调试）
-
-const DEFAULT_MIN = 4000;
-const DEFAULT_MAX = 6000; // 2000 端口的池子；配合 maxTries 100 实际能覆盖 (max - min) 区间
-
-function pickRandomInt(min, max) {
-  // 含 min，不含 max（与 Math.random 习惯一致）
-  return Math.floor(Math.random() * (max - min)) + min;
-}
-
-/**
- * 解析本次启动应使用的起始端口
- * @param {object} [opts]
- * @param {number} [opts.min] 随机范围下界（默认 4000）
- * @param {number} [opts.max] 随机范围上界（默认 6000）
- * @returns {{ startPort: number, source: 'env'|'random', min: number, max: number }}
- */
-export function resolveStartPort({ min = DEFAULT_MIN, max = DEFAULT_MAX } = {}) {
-  // 1) 环境变量优先：用户显式指定 > 一切
-  const envPort = Number(process.env.PORT);
-  if (Number.isInteger(envPort) && envPort > 0 && envPort < 65536) {
-    return { startPort: envPort, source: 'env', min, max };
-  }
-
-  // 2) 兜底：参数范围非法就回退到 [4000, 6000)
-  if (!Number.isInteger(min) || !Number.isInteger(max) || min < 1 || max > 65535 || min >= max) {
-    min = DEFAULT_MIN;
-    max = DEFAULT_MAX;
-  }
-
-  // 3) 随机挑一个起点
-  const startPort = pickRandomInt(min, max);
-  return { startPort, source: 'random', min, max };
-}
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// 随机起点端口选择
+// 默认：避免与系统保留 / 常见服务端口重叠，在较宽的"用户态"范围里随机挑一个起点
+// 然后由 startServerOnAvailablePort 在该起点基础上顺序往上扫描 EADDRINUSE
+// 覆盖：环境变量 PORT 强制使用固定端口（向后兼容 + 便于书签/调试）
+
+const DEFAULT_MIN = 4000;
+const DEFAULT_MAX = 6000; // 2000 端口的池子；配合 maxTries 100 实际能覆盖 (max - min) 区间
+
+function pickRandomInt(min, max) {
+  // 含 min，不含 max（与 Math.random 习惯一致）
+  return Math.floor(Math.random() * (max - min)) + min;
+}
+
+/**
+ * 解析本次启动应使用的起始端口
+ * @param {object} [opts]
+ * @param {number} [opts.min] 随机范围下界（默认 4000）
+ * @param {number} [opts.max] 随机范围上界（默认 6000）
+ * @returns {{ startPort: number, source: 'env'|'random', min: number, max: number }}
+ */
+export function resolveStartPort({ min = DEFAULT_MIN, max = DEFAULT_MAX } = {}) {
+  // 1) 环境变量优先：用户显式指定 > 一切
+  const envPort = Number(process.env.PORT);
+  if (Number.isInteger(envPort) && envPort > 0 && envPort < 65536) {
+    return { startPort: envPort, source: 'env', min, max };
+  }
+
+  // 2) 兜底：参数范围非法就回退到 [4000, 6000)
+  if (!Number.isInteger(min) || !Number.isInteger(max) || min < 1 || max > 65535 || min >= max) {
+    min = DEFAULT_MIN;
+    max = DEFAULT_MAX;
+  }
+
+  // 3) 随机挑一个起点
+  const startPort = pickRandomInt(min, max);
+  return { startPort, source: 'random', min, max };
+}

package/src/ui/server/utils/startServerOnAvailablePort.js

@@ -1,87 +1,101 @@
-export async function startServerOnAvailablePort({
-  httpServer,
-  startPort,
-  chalk,
-  open,
-  noOpen,
-  isGitRepo,
-  savePortToFile,
-  maxTries = 100,
-  callbackExecutedRef
-}) {
-  let currentPort = startPort;
-  const maxPort = startPort + maxTries;
-  const getCallbackExecuted = () => {
-    if (callbackExecutedRef && typeof callbackExecutedRef === 'object' && 'value' in callbackExecutedRef) {
-      return Boolean(callbackExecutedRef.value);
-    }
-    return false;
-  };
-
-  const setCallbackExecuted = (value) => {
-    if (callbackExecutedRef && typeof callbackExecutedRef === 'object' && 'value' in callbackExecutedRef) {
-      callbackExecutedRef.value = Boolean(value);
-    }
-  };
-
-  while (currentPort < maxPort) {
-    try {
-      if (currentPort > startPort) {
-        await new Promise(resolve => setTimeout(resolve, 800));
-        console.log(`尝试端口 ${currentPort}...`);
-      }
-
-      await new Promise((resolve, reject) => {
-        const errorHandler = (err) => {
-          httpServer.removeListener('error', errorHandler);
-          reject(err);
-        };
-
-        httpServer.once('error', errorHandler);
-
-        httpServer.listen(currentPort, () => {
-          if (getCallbackExecuted()) return;
-          setCallbackExecuted(true);
-
-          httpServer.removeListener('error', errorHandler);
-
-          console.log(chalk.green('======================================'));
-          console.log(chalk.green(`  Zen GitSync 服务器已启动`));
-          console.log(chalk.green(`  访问地址: http://localhost:${currentPort}`));
-          console.log(chalk.green(`  启动时间: ${new Date().toLocaleString()}`));
-
-          if (isGitRepo) {
-            console.log(chalk.green(`  当前目录是Git仓库`));
-          } else {
-            console.log(chalk.yellow(`  当前目录不是Git仓库，文件监控未启动`));
-          }
-
-          console.log(chalk.green('======================================'));
-
-          savePortToFile(currentPort);
-
-          if (!noOpen) {
-            setTimeout(() => {
-              open(`http://localhost:${currentPort}`);
-            }, 0);
-          }
-
-          resolve();
-        });
-      });
-
-      return currentPort;
-    } catch (err) {
-      if (err.code === 'EADDRINUSE') {
-        console.log(`端口 ${currentPort} 被占用，尝试下一个端口...`);
-        currentPort++;
-      } else {
-        console.error('启动服务器失败:', err);
-        process.exit(1);
-      }
-    }
-  }
-
-  console.error(`无法找到可用端口 (尝试范围: ${startPort}-${maxPort - 1})`);
-  process.exit(1);
-}
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+export async function startServerOnAvailablePort({
+  httpServer,
+  startPort,
+  chalk,
+  open,
+  noOpen,
+  isGitRepo,
+  savePortToFile,
+  maxTries = 100,
+  callbackExecutedRef
+}) {
+  let currentPort = startPort;
+  const maxPort = startPort + maxTries;
+  const getCallbackExecuted = () => {
+    if (callbackExecutedRef && typeof callbackExecutedRef === 'object' && 'value' in callbackExecutedRef) {
+      return Boolean(callbackExecutedRef.value);
+    }
+    return false;
+  };
+
+  const setCallbackExecuted = (value) => {
+    if (callbackExecutedRef && typeof callbackExecutedRef === 'object' && 'value' in callbackExecutedRef) {
+      callbackExecutedRef.value = Boolean(value);
+    }
+  };
+
+  while (currentPort < maxPort) {
+    try {
+      if (currentPort > startPort) {
+        await new Promise(resolve => setTimeout(resolve, 800));
+        console.log(`尝试端口 ${currentPort}...`);
+      }
+
+      await new Promise((resolve, reject) => {
+        const errorHandler = (err) => {
+          httpServer.removeListener('error', errorHandler);
+          reject(err);
+        };
+
+        httpServer.once('error', errorHandler);
+
+        httpServer.listen(currentPort, () => {
+          if (getCallbackExecuted()) return;
+          setCallbackExecuted(true);
+
+          httpServer.removeListener('error', errorHandler);
+
+          console.log(chalk.green('======================================'));
+          console.log(chalk.green(`  Zen GitSync 服务器已启动`));
+          console.log(chalk.green(`  访问地址: http://localhost:${currentPort}`));
+          console.log(chalk.green(`  启动时间: ${new Date().toLocaleString()}`));
+
+          if (isGitRepo) {
+            console.log(chalk.green(`  当前目录是Git仓库`));
+          } else {
+            console.log(chalk.yellow(`  当前目录不是Git仓库，文件监控未启动`));
+          }
+
+          console.log(chalk.green('======================================'));
+
+          savePortToFile(currentPort);
+
+          if (!noOpen) {
+            setTimeout(() => {
+              open(`http://localhost:${currentPort}`);
+            }, 0);
+          }
+
+          resolve();
+        });
+      });
+
+      return currentPort;
+    } catch (err) {
+      if (err.code === 'EADDRINUSE') {
+        console.log(`端口 ${currentPort} 被占用，尝试下一个端口...`);
+        currentPort++;
+      } else {
+        console.error('启动服务器失败:', err);
+        process.exit(1);
+      }
+    }
+  }
+
+  console.error(`无法找到可用端口 (尝试范围: ${startPort}-${maxPort - 1})`);
+  process.exit(1);
+}