@raolin2025/claude-code-node 1.0.0

package/src/security/path-guard.js

@@ -0,0 +1,190 @@
+/**
+ * 路径安全防护 — 防止路径遍历攻击和敏感文件访问
+ * 对应原版: src/utils/permissions/filesystem.ts + 多处路径检查
+ */
+import { resolve, normalize, isAbsolute, relative, sep } from 'path'
+
+/**
+ * 敏感路径列表 — 禁止读写
+ */
+const FORBIDDEN_PATHS = [
+  '/etc/shadow',
+  '/etc/passwd',
+  '/etc/sudoers',
+  '/etc/ssh/sshd_config',
+  '/etc/gshadow',
+  '/etc/pam.d/',
+  '/boot/',
+  '/proc/sys/',
+  '/sys/kernel/',
+]
+
+/**
+ * 敏感路径前缀 — 需要额外确认
+ */
+const SENSITIVE_PREFIXES = [
+  '/etc/',
+  '/usr/local/',
+  '/var/log/',
+  '/root/',
+]
+
+/**
+ * 规范化路径 — 解析 .., ., 符号链接等
+ * @param {string} filePath — 输入路径
+ * @param {string} cwd — 当前工作目录
+ * @returns {string} 规范化后的绝对路径
+ */
+export function sanitizePath(filePath, cwd = process.cwd()) {
+  // 如果是相对路径，基于 cwd 解析
+  const absPath = isAbsolute(filePath) ? filePath : resolve(cwd, filePath)
+  // 规范化：消除 .. 和 .
+  return normalize(absPath)
+}
+
+/**
+ * 检查路径遍历攻击
+ * @param {string} filePath — 用户输入的路径
+ * @param {string} cwd — 工作目录
+ * @param {string[]} allowedDirs — 允许访问的目录列表
+ * @returns {{safe: boolean, resolvedPath: string, reason?: string}}
+ */
+export function checkPathTraversal(filePath, cwd = process.cwd(), allowedDirs = []) {
+  const resolvedPath = sanitizePath(filePath, cwd)
+
+  // 1. 检查 .. 在原始路径中的使用
+  if (filePath.includes('..')) {
+    const normalizedRelative = relative(cwd, resolvedPath)
+    if (normalizedRelative.startsWith('..') || resolvedPath.startsWith('/etc/') || resolvedPath.startsWith('/root/')) {
+      return {
+        safe: false,
+        resolvedPath,
+        reason: `路径遍历：${filePath} 解析到 ${resolvedPath}，超出工作目录范围`,
+      }
+    }
+  }
+
+  // 2. 检查是否在允许的目录范围内
+  if (allowedDirs.length > 0) {
+    const isInAllowedDir = allowedDirs.some(dir => {
+      const normDir = normalize(isAbsolute(dir) ? dir : resolve(cwd, dir))
+      return resolvedPath.startsWith(normDir + sep) || resolvedPath === normDir
+    })
+
+    if (!isInAllowedDir) {
+      return {
+        safe: false,
+        resolvedPath,
+        reason: `路径 ${resolvedPath} 不在允许的目录范围内`,
+      }
+    }
+  }
+
+  return { safe: true, resolvedPath }
+}
+
+/**
+ * 检查是否为禁止访问的敏感路径
+ * @param {string} resolvedPath — 已规范化的绝对路径
+ * @returns {{allowed: boolean, reason?: string}}
+ */
+export function checkForbiddenPath(resolvedPath) {
+  // 1. 严格匹配禁止路径
+  for (const forbidden of FORBIDDEN_PATHS) {
+    if (resolvedPath === forbidden || resolvedPath.startsWith(forbidden + sep) || resolvedPath.startsWith(forbidden + '/')) {
+      return {
+        allowed: false,
+        reason: `禁止访问敏感路径: ${resolvedPath}（匹配规则: ${forbidden}）`,
+      }
+    }
+  }
+
+  // 2. SSH 目录特殊处理
+  if (resolvedPath.includes('/.ssh/') || resolvedPath.includes('\\.ssh\\')) {
+    // 允许读取 known_hosts 和 config，禁止读取私钥
+    const sshKeyPattern = /\/\.ssh\/id_(rsa|ed25519|ecdsa|dsa)(\.pub)?$/i
+    const sshConfigPattern = /\/\.ssh\/(config|known_hosts|authorized_keys)$/i
+
+    if (sshKeyPattern.test(resolvedPath)) {
+      return {
+        allowed: false,
+        reason: `禁止访问 SSH 密钥文件: ${resolvedPath}`,
+      }
+    }
+
+    if (sshConfigPattern.test(resolvedPath)) {
+      return {
+        allowed: true,
+        reason: `⚠️ 访问 SSH 配置文件: ${resolvedPath}`,
+      }
+    }
+  }
+
+  // 3. 敏感前缀检查 — 允许但提示
+  for (const prefix of SENSITIVE_PREFIXES) {
+    if (resolvedPath.startsWith(prefix)) {
+      return {
+        allowed: true,
+        reason: `⚠️ 访问系统敏感目录: ${resolvedPath}`,
+      }
+    }
+  }
+
+  return { allowed: true }
+}
+
+/**
+ * 综合路径安全检查
+ * @param {string} filePath — 用户输入路径
+ * @param {object} options — { cwd, allowedDirs, checkForbidden }
+ * @returns {{safe: boolean, resolvedPath: string, reasons: string[]}}
+ */
+export function checkPathSafety(filePath, options = {}) {
+  const { cwd = process.cwd(), allowedDirs = [], checkForbidden = true } = options
+  const reasons = []
+
+  // 路径遍历检查
+  const traversalResult = checkPathTraversal(filePath, cwd, allowedDirs)
+  const resolvedPath = traversalResult.resolvedPath
+
+  if (!traversalResult.safe) {
+    reasons.push(traversalResult.reason)
+  }
+
+  // 禁止路径检查
+  if (checkForbidden) {
+    const forbiddenResult = checkForbiddenPath(resolvedPath)
+    if (!forbiddenResult.allowed) {
+      reasons.push(forbiddenResult.reason)
+    } else if (forbiddenResult.reason) {
+      reasons.push(forbiddenResult.reason)
+    }
+  }
+
+  return {
+    safe: !reasons.some(r => r.startsWith('禁止') || r.startsWith('路径遍历')),
+    resolvedPath,
+    reasons,
+  }
+}
+
+/**
+ * 验证写入路径 — 比读取更严格
+ * @param {string} filePath
+ * @param {object} options
+ * @returns {{safe: boolean, resolvedPath: string, reasons: string[]}}
+ */
+export function checkWritePathSafety(filePath, options = {}) {
+  const result = checkPathSafety(filePath, options)
+
+  // 写入额外检查：不能写到系统关键目录
+  const systemWriteDirs = ['/etc/', '/boot/', '/usr/bin/', '/usr/lib/', '/sbin/', '/bin/']
+  for (const dir of systemWriteDirs) {
+    if (result.resolvedPath.startsWith(dir)) {
+      result.safe = false
+      result.reasons.push(`禁止写入系统关键目录: ${dir}`)
+    }
+  }
+
+  return result
+}

package/src/security/ssrf-guard.js

@@ -0,0 +1,178 @@
+/**
+ * SSRF 防护 — 阻止对内网/云元数据端点的请求
+ * 对应原版: src/utils/hooks/ssrfGuard.ts
+ */
+import { lookup as dnsLookup } from 'dns'
+import { isIP } from 'net'
+
+/**
+ * 检查 IPv4 地址是否在应被阻止的范围内
+ *
+ * 阻止列表:
+ * - 0.0.0.0/8     — "this" 网络
+ * - 10.0.0.0/8    — 私有网络
+ * - 100.64.0.0/10 — CGNAT 共享地址（阿里云元数据 100.100.100.200）
+ * - 169.254.0.0/16 — 链路本地（AWS/GCP 云元数据）
+ * - 172.16.0.0/12 — 私有网络
+ * - 192.168.0.0/16 — 私有网络
+ * - 192.0.2.0/24  — TEST-NET-1 (RFC 5737)
+ * - 198.51.100.0/24 — TEST-NET-2
+ * - 203.0.113.0/24 — TEST-NET-3
+ *
+ * 允许:
+ * - 127.0.0.0/8   — 回环（本地开发 hook 服务器）
+ */
+function isBlockedV4(address) {
+  const parts = address.split('.').map(Number)
+  if (parts.length !== 4 || parts.some(n => Number.isNaN(n))) return false
+
+  const [a, b] = parts
+
+  // 回环 — 允许
+  if (a === 127) return false
+
+  // 0.0.0.0/8
+  if (a === 0) return true
+
+  // 10.0.0.0/8
+  if (a === 10) return true
+
+  // 100.64.0.0/10 — CGNAT (RFC 6598)
+  if (a === 100 && b >= 64 && b <= 127) return true
+
+  // 169.254.0.0/16 — 链路本地，云元数据
+  if (a === 169 && b === 254) return true
+
+  // 172.16.0.0/12
+  if (a === 172 && b >= 16 && b <= 31) return true
+
+  // 192.168.0.0/16
+  if (a === 192 && b === 168) return true
+
+  // 192.0.2.0/24 — TEST-NET-1
+  if (a === 192 && b === 0 && parts[2] === 2) return true
+
+  // 198.51.100.0/24 — TEST-NET-2
+  if (a === 198 && b === 51 && parts[2] === 100) return true
+
+  // 203.0.113.0/24 — TEST-NET-3
+  if (a === 203 && b === 0 && parts[2] === 113) return true
+
+  return false
+}
+
+/**
+ * 检查 IPv6 地址是否在应被阻止的范围内
+ *
+ * 阻止:
+ * - ::           — 未指定地址
+ * - fc00::/7     — 唯一本地地址 (ULA)
+ * - fe80::/10    — 链路本地
+ * - ::ffff:<被阻止的v4> — IPv4 映射地址
+ *
+ * 允许:
+ * - ::1          — 回环
+ */
+function isBlockedV6(address) {
+  const normalized = address.toLowerCase()
+
+  // ::1 回环 — 允许
+  if (normalized === '::1') return false
+
+  // :: 未指定
+  if (normalized === '::' || normalized === '0:0:0:0:0:0:0:0') return true
+
+  // fc00::/7 — 唯一本地 (fc00:: - fdff::)
+  if (normalized.startsWith('fc') || normalized.startsWith('fd')) return true
+
+  // fe80::/10 — 链路本地
+  if (normalized.startsWith('fe8')) return true
+
+  // ::ffff:<IPv4> — IPv4 映射地址
+  const v4Mapped = normalized.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/)
+  if (v4Mapped) {
+    return isBlockedV4(v4Mapped[1])
+  }
+
+  return false
+}
+
+/**
+ * 检查 IP 地址是否在阻止列表中
+ * @param {string} address — IP 地址字符串
+ * @returns {boolean} true = 应阻止
+ */
+export function isBlockedAddress(address) {
+  const v = isIP(address)
+  if (v === 4) return isBlockedV4(address)
+  if (v === 6) return isBlockedV6(address)
+  // 不是合法 IP 字面量 — 交给 DNS 解析路径处理
+  return false
+}
+
+/**
+ * 解析主机名并检查解析结果是否安全
+ * @param {string} hostname — 主机名
+ * @returns {Promise<{allowed: boolean, addresses: string[], reason?: string}>}
+ */
+export async function checkHostSafety(hostname) {
+  // 如果是 IP 字面量，直接检查
+  if (isIP(hostname)) {
+    const blocked = isBlockedAddress(hostname)
+    return {
+      allowed: !blocked,
+      addresses: [hostname],
+      reason: blocked ? `IP ${hostname} 在私有/保留地址范围内，可能为 SSRF 目标` : undefined,
+    }
+  }
+
+  // DNS 解析后检查
+  return new Promise((resolve) => {
+    dnsLookup(hostname, (err, address) => {
+      if (err) {
+        // DNS 解析失败 — 允许（让 fetch 自己报错）
+        resolve({ allowed: true, addresses: [], reason: undefined })
+        return
+      }
+
+      const addresses = Array.isArray(address) ? address.map(a => a.address) : [address]
+      const blockedAddrs = addresses.filter(a => isBlockedAddress(a))
+
+      if (blockedAddrs.length > 0) {
+        resolve({
+          allowed: false,
+          addresses,
+          reason: `主机 ${hostname} 解析到私有地址 ${blockedAddrs.join(', ')}，可能为 SSRF 目标`,
+        })
+      } else {
+        resolve({ allowed: true, addresses, reason: undefined })
+      }
+    })
+  })
+}
+
+/**
+ * 检查 URL 是否安全（SSRF 防护）
+ * @param {string} url — 完整 URL
+ * @returns {Promise<{allowed: boolean, reason?: string}>}
+ */
+export async function checkUrlSafety(url) {
+  try {
+    const parsed = new URL(url)
+
+    // 只允许 HTTP/HTTPS
+    if (!['http:', 'https:'].includes(parsed.protocol)) {
+      return { allowed: false, reason: `不支持的协议: ${parsed.protocol}` }
+    }
+
+    // 检查主机名
+    const hostResult = await checkHostSafety(parsed.hostname)
+    if (!hostResult.allowed) {
+      return { allowed: false, reason: hostResult.reason }
+    }
+
+    return { allowed: true }
+  } catch {
+    return { allowed: false, reason: '无效的 URL' }
+  }
+}

package/src/tools/ask-user.js

@@ -0,0 +1,34 @@
+/**
+ * AskUserQuestion 工具 — 向用户提问
+ * 对应原版: src/tools/AskUserQuestionTool/
+ */
+import { ToolDef } from '../types/index.js'
+
+export const askUserTool = new ToolDef(
+  'AskUserQuestion',
+  `Ask the user a question and wait for their response.
+Use this when you need clarification or user input to proceed.`,
+  {
+    type: 'object',
+    properties: {
+      question: {
+        type: 'string',
+        description: 'The question to ask the user',
+      },
+    },
+    required: ['question'],
+  },
+  async (input, ctx) => {
+    // 在 CLI 模式下，通过 ctx 的 readline 接口提问
+    if (ctx?.readline) {
+      return new Promise((resolve) => {
+        ctx.readline.question(`\n❓ ${input.question}\n> `, (answer) => {
+          resolve(answer.trim())
+        })
+      })
+    }
+    // 非 CLI 模式 — 返回提示信息
+    return `[AskUserQuestion: ${input.question} (no interactive terminal available)]`
+  },
+  'always-allow'
+)

package/src/tools/bash.js

@@ -0,0 +1,101 @@
+/**
+ * Bash 工具 — 执行 shell 命令
+ * 对应原版: src/tools/BashTool/
+ */
+import { spawn } from 'child_process'
+import { ToolDef } from '../types/index.js'
+import { checkBashSafety } from '../security/bash-guard.js'
+
+export const bashTool = new ToolDef(
+  'Bash',
+  `Execute a bash command. The command will run in a shell subprocess.
+Usage:
+- Provide the command as the value of the 'command' key
+- Optionally specify a working directory with 'cwd'
+- Optionally set a timeout in seconds with 'timeout' (default 120)
+- The output will be returned as stdout+stderr combined
+- If the command exits with non-zero, the result will be marked as an error`,
+  {
+    type: 'object',
+    properties: {
+      command: {
+        type: 'string',
+        description: 'The bash command to execute',
+      },
+      cwd: {
+        type: 'string',
+        description: 'Working directory for the command (default: process.cwd())',
+      },
+      timeout: {
+        type: 'number',
+        description: 'Timeout in seconds (default: 120)',
+      },
+      env: {
+        type: 'object',
+        description: 'Additional environment variables',
+        additionalProperties: { type: 'string' },
+      },
+    },
+    required: ['command'],
+  },
+  async (input, ctx) => {
+    const command = input.command
+    const cwd = input.cwd || ctx.cwd || process.cwd()
+    const timeoutSec = input.timeout || 120
+    const extraEnv = input.env || {}
+
+    // 安全检查
+    const safetyResult = checkBashSafety(command)
+    if (!safetyResult.allowed) {
+      return `[🚫 命令被安全策略阻止]\n${safetyResult.reasons.join('\n')}\n\n如果确认需要执行，请使用 /allow Bash 命令`
+    }
+
+    return new Promise((resolve, reject) => {
+      const shell = process.env.SHELL || '/bin/bash'
+      const proc = spawn(shell, ['-c', command], {
+        cwd,
+        env: { ...process.env, ...extraEnv },
+        stdio: ['pipe', 'pipe', 'pipe'],
+      })
+
+      let stdout = ''
+      let stderr = ''
+
+      proc.stdout.on('data', (data) => {
+        stdout += data.toString()
+      })
+
+      proc.stderr.on('data', (data) => {
+        stderr += data.toString()
+      })
+
+      const timer = setTimeout(() => {
+        proc.kill('SIGTERM')
+        // 给进程 5 秒优雅退出
+        setTimeout(() => {
+          try { proc.kill('SIGKILL') } catch {}
+        }, 5000)
+        resolve(`[Timeout after ${timeoutSec}s]\n${stdout}${stderr ? '\n--- stderr ---\n' + stderr : ''}`)
+      }, timeoutSec * 1000)
+
+      proc.on('close', (code) => {
+        clearTimeout(timer)
+        const output = stdout + (stderr ? '\n--- stderr ---\n' + stderr : '')
+        if (code === 0) {
+          resolve(output || '(no output)')
+        } else {
+          resolve(`[Exit code: ${code}]\n${output}`)
+        }
+      })
+
+      proc.on('error', (err) => {
+        clearTimeout(timer)
+        resolve(`[Error: ${err.message}]`)
+      })
+
+      // 关闭 stdin
+      proc.stdin.end()
+    })
+  },
+  'ask'
+)

package/src/tools/file-edit.js

@@ -0,0 +1,112 @@
+/**
+ * FileEdit 工具 — 精确文本替换编辑文件
+ * 对应原版: src/tools/FileEditTool/
+ */
+import { readFile, writeFile } from 'fs/promises'
+import { resolve, isAbsolute } from 'path'
+import { ToolDef } from '../types/index.js'
+import { checkWritePathSafety } from '../security/path-guard.js'
+
+export const fileEditTool = new ToolDef(
+  'Edit',
+  `Perform exact string replacements in a file.
+Usage:
+- file_path must be an absolute path
+- old_string must match EXACTLY (including whitespace/indentation)
+- new_string is the replacement text
+- Use replace_all=true to replace all occurrences (default: false)
+- The tool will fail if old_string is not found or appears multiple times without replace_all`,
+  {
+    type: 'object',
+    properties: {
+      file_path: {
+        type: 'string',
+        description: 'The absolute path to the file to modify',
+      },
+      old_string: {
+        type: 'string',
+        description: 'The text to replace',
+      },
+      new_string: {
+        type: 'string',
+        description: 'The text to replace it with (must be different from old_string)',
+      },
+      replace_all: {
+        type: 'boolean',
+        description: 'Replace all occurrences of old_string (default false)',
+        default: false,
+      },
+    },
+    required: ['file_path', 'old_string', 'new_string'],
+  },
+  async (input, ctx) => {
+    let filePath = input.file_path
+    if (!isAbsolute(filePath)) {
+      filePath = resolve(ctx.cwd || process.cwd(), filePath)
+    }
+
+    const { old_string, new_string, replace_all = false } = input
+
+    // 写入路径安全检查
+    const pathResult = checkWritePathSafety(filePath, { cwd: ctx.cwd || process.cwd() })
+    if (!pathResult.safe) {
+      return `[🚫 路径被安全策略阻止]\n${pathResult.reasons.join('\n')}`
+    }
+
+    if (old_string === new_string) {
+      return '[Error: old_string and new_string are identical. No change needed.]'
+    }
+
+    try {
+      const content = await readFile(filePath, 'utf-8')
+
+      // 检查 old_string 是否存在
+      if (!content.includes(old_string)) {
+        // 尝试提供有用的错误信息
+        const lines = content.split('\n')
+        const snippet = old_string.split('\n')[0].slice(0, 80)
+        const suggestions = []
+        for (let i = 0; i < lines.length; i++) {
+          if (lines[i].includes(snippet) || lines[i].trim() === snippet.trim()) {
+            suggestions.push(`  Line ${i + 1}: ${lines[i].slice(0, 80)}`)
+          }
+        }
+        let msg = `[Error: old_string not found in ${filePath}]`
+        if (suggestions.length > 0) {
+          msg += `\nPossible matches:\n${suggestions.join('\n')}`
+        }
+        return msg
+      }
+
+      // 检查多次出现
+      const count = content.split(old_string).length - 1
+      if (count > 1 && !replace_all) {
+        return `[Error: old_string appears ${count} times in the file. Use replace_all=true to replace all occurrences, or provide more context to make the match unique.]`
+      }
+
+      // 执行替换
+      let newContent
+      if (replace_all) {
+        newContent = content.split(old_string).join(new_string)
+      } else {
+        const idx = content.indexOf(old_string)
+        newContent = content.slice(0, idx) + new_string + content.slice(idx + old_string.length)
+      }
+
+      await writeFile(filePath, newContent, 'utf-8')
+
+      // 计算变更行数
+      const oldLines = old_string.split('\n').length
+      const newLines = new_string.split('\n').length
+      const diff = newLines - oldLines
+
+      return `Successfully edited ${filePath} (${count > 1 ? count + ' occurrences' : '1 occurrence'} replaced, ${diff >= 0 ? '+' : ''}${diff} lines)`
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        return `[Error: File not found: ${filePath}]`
+      }
+      return `[Error editing file: ${err.message}]`
+    }
+  },
+  'ask'
+)