@raolin2025/claude-code-node 1.1.0 → 2.0.0

package/src/security/enhanced-permission.js

@@ -1,15 +1,17 @@
 /**
  * 权限系统增强版 — 规则持久化 + 审计日志
- * 对应原版: src/hooks/toolPermission/ + src/utils/permissions/
+ * 对应原版：src/hooks/toolPermission/ + src/utils/permissions/
  */
-import { readFile, writeFile, mkdir } from 'fs/promises'
-import { resolve, join } from 'path'
+import { readFile, writeFile, mkdir, stat, rename } from 'fs/promises'
+import { join } from 'path'
 import { checkBashSafety } from './bash-guard.js'
 import { checkPathSafety, checkWritePathSafety } from './path-guard.js'
 import { checkUrlSafety } from './ssrf-guard.js'
 
 const PERMISSIONS_FILE = '.claude-code/permissions.json'
 const AUDIT_LOG_FILE = '.claude-code/audit.log'
+const AUDIT_LOG_MAX_SIZE = 10 * 1024 * 1024 // 10MB 审计日志上限
+const AUDIT_LOG_MAX_BACKUPS = 3 // 最多保留 3 个轮转备份
 
 /**
  * 权限决策类型
@@ -25,10 +27,10 @@ export const PermissionDecision = {
  */
 export class PermissionRule {
   constructor({ tool, pattern, decision, reason, expiresAt = null }) {
-    this.tool = tool          // 工具名或 '*'（所有工具）
-    this.pattern = pattern    // 匹配模式（glob 或 regex 字符串）
-    this.decision = decision  // allow / deny / ask
-    this.reason = reason      // 规则原因
+    this.tool = tool // 工具名或 '*'（所有工具）
+    this.pattern = pattern // 匹配模式（glob 或 regex 字符串）
+    this.decision = decision // allow / deny / ask
+    this.reason = reason // 规则原因
     this.createdAt = Date.now()
     this.expiresAt = expiresAt // 过期时间（会话级规则）
   }
@@ -41,21 +43,17 @@ export class PermissionRule {
   /** 检查输入是否匹配此规则 */
   matches(input) {
     if (this.isExpired) return false
-
     // 简单 glob 匹配
     const pattern = this.pattern
     if (pattern === '*') return true
-
     // 路径模式
     if (typeof input === 'string' && input.includes('/')) {
       return this._globMatch(pattern, input)
     }
-
     // 命令模式
     if (typeof input === 'string') {
       return input.startsWith(pattern) || this._globMatch(pattern, input)
     }
-
     return false
   }
 
@@ -74,8 +72,8 @@ export class PermissionRule {
 export class EnhancedPermissionChecker {
   constructor(mode = 'ask', options = {}) {
     this.mode = mode
-    this.rules = []            // PermissionRule 列表
-    this.auditLog = []         // 审计日志
+    this.rules = [] // PermissionRule 列表
+    this.auditLog = [] // 审计日志
     this.cwd = options.cwd || process.cwd()
     this.projectDir = options.projectDir || process.cwd()
     this._maxAuditEntries = 1000
@@ -117,7 +115,7 @@ export class EnhancedPermissionChecker {
    * 综合权限检查
    * @param {string} toolName — 工具名
    * @param {object} input — 工具输入参数
-   * @returns {Promise<{allowed: boolean, reason?: string, securityCheck?: object}>}
+   * @returns {Promise<{allowed: boolean, reason?: string, requiresConfirmation?: boolean, securityCheck?: object}>}
    */
   async check(toolName, input = {}) {
     // 1. 模式级检查
@@ -125,6 +123,7 @@ export class EnhancedPermissionChecker {
       this._log(toolName, input, false, '全局拒绝模式')
       return { allowed: false, reason: '全局拒绝模式' }
     }
+
     if (this.mode === 'always-allow') {
       const securityResult = await this._securityCheck(toolName, input)
       if (!securityResult.safe) {
@@ -141,7 +140,7 @@ export class EnhancedPermissionChecker {
       if (rule.tool === toolName || rule.tool === '*') {
         if (rule.matches(this._extractPattern(toolName, input))) {
           if (rule.decision === PermissionDecision.DENY) {
-            this._log(toolName, input, false, `规则拒绝: ${rule.reason}`)
+            this._log(toolName, input, false, `规则拒绝：${rule.reason}`)
             return { allowed: false, reason: rule.reason }
           }
           if (rule.decision === PermissionDecision.ALLOW) {
@@ -151,7 +150,7 @@ export class EnhancedPermissionChecker {
               this._log(toolName, input, false, securityResult.reason)
               return { allowed: false, reason: securityResult.reason, securityCheck: securityResult }
             }
-            this._log(toolName, input, true, `规则允许: ${rule.reason}`)
+            this._log(toolName, input, true, `规则允许：${rule.reason}`)
             return { allowed: true }
           }
         }
@@ -166,9 +165,12 @@ export class EnhancedPermissionChecker {
     }
 
     // 4. ask 模式 — 需要用户确认
+    // 返回 requiresConfirmation=true，让调用方处理确认逻辑
     this._log(toolName, input, true, 'ask 模式 — 等待用户确认')
     return {
-      allowed: true, // 简化版直接允许（完整版应弹出确认对话框）
+      allowed: false, // ask 模式下先拒绝，等待用户确认
+      requiresConfirmation: true, // 标记需要用户确认
+      reason: 'ask 模式需要用户确认',
       securityCheck: securityResult,
     }
   }
@@ -188,7 +190,6 @@ export class EnhancedPermissionChecker {
           detail: result,
         }
       }
-
       case 'Read': {
         const filePath = input.file_path || ''
         if (!filePath) return { safe: true }
@@ -199,7 +200,6 @@ export class EnhancedPermissionChecker {
           detail: result,
         }
       }
-
       case 'Edit':
       case 'Write': {
         const filePath = input.file_path || ''
@@ -212,7 +212,6 @@ export class EnhancedPermissionChecker {
           detail: result,
         }
       }
-
       case 'WebFetch': {
         const url = input.url || ''
         if (!url) return { safe: true }
@@ -222,7 +221,6 @@ export class EnhancedPermissionChecker {
           reason: result.reason,
         }
       }
-
       default:
         return { safe: true }
     }
@@ -231,15 +229,20 @@ export class EnhancedPermissionChecker {
   /** 提取规则匹配用的模式字符串 */
   _extractPattern(toolName, input) {
     switch (toolName) {
-      case 'Bash': return input.command || ''
+      case 'Bash':
+        return input.command || ''
       case 'Read':
       case 'Edit':
-      case 'Write': return input.file_path || ''
+      case 'Write':
+        return input.file_path || ''
       case 'Glob':
-      case 'Grep': return input.path || input.pattern || ''
+      case 'Grep':
+        return input.path || input.pattern || ''
       case 'WebFetch':
-      case 'WebSearch': return input.url || input.query || ''
-      default: return JSON.stringify(input)
+      case 'WebSearch':
+        return input.url || input.query || ''
+      default:
+        return JSON.stringify(input)
     }
   }
 
@@ -252,7 +255,6 @@ export class EnhancedPermissionChecker {
       allowed,
       reason,
     })
-
     // 限制审计日志大小
     if (this.auditLog.length > this._maxAuditEntries) {
       this.auditLog = this.auditLog.slice(-this._maxAuditEntries)
@@ -271,7 +273,11 @@ export class EnhancedPermissionChecker {
         decision: r.decision,
         reason: r.reason,
       }))
-    await writeFile(join(dir, 'permissions.json'), JSON.stringify(data, null, 2), 'utf-8')
+    // v1.1 修复：文件权限 0600（仅所有者可读写），防止其他用户读取权限规则
+    await writeFile(join(dir, 'permissions.json'), JSON.stringify(data, null, 2), {
+      encoding: 'utf-8',
+      mode: 0o600,
+    })
   }
 
   /** 加载权限规则 */
@@ -287,19 +293,51 @@ export class EnhancedPermissionChecker {
     }
   }
 
-  /** 保存审计日志 */
+  /** 保存审计日志（v1.1: 增加轮转，防止磁盘耗尽） */
   async saveAuditLog() {
     const dir = join(this.projectDir, '.claude-code')
     await mkdir(dir, { recursive: true })
-    const lines = this.auditLog.map(e =>
-      `${e.timestamp} | ${e.tool} | ${e.allowed ? 'ALLOW' : 'DENY'} | ${e.reason} | ${e.inputSnippet}`
-    ).join('\n')
-    await writeFile(join(dir, 'audit.log'), lines, 'utf-8')
+    const logPath = join(dir, 'audit.log')
+
+    // 检查现有日志大小，超过上限则轮转
+    try {
+      const logStat = await stat(logPath)
+      if (logStat.size >= AUDIT_LOG_MAX_SIZE) {
+        // 轮转：audit.log → audit.log.1 → audit.log.2 → audit.log.3（最老的删除）
+        for (let i = AUDIT_LOG_MAX_BACKUPS; i >= 1; i--) {
+          const src = i === 1 ? logPath : join(dir, `audit.log.${i - 1}`)
+          const dst = join(dir, `audit.log.${i}`)
+          try {
+            if (i === AUDIT_LOG_MAX_BACKUPS) {
+              // 最老的备份直接删除
+              const { unlink } = await import('fs/promises')
+              await unlink(dst).catch(() => {})
+            }
+            await rename(src, dst).catch(() => {})
+          } catch {
+            /* 忽略轮转错误 */
+          }
+        }
+      }
+    } catch {
+      /* 日志文件不存在，首次写入 */
+    }
+
+    const lines = this.auditLog
+      .map(e => `${e.timestamp} | ${e.tool} | ${e.allowed ? 'ALLOW' : 'DENY'} | ${e.reason} | ${e.inputSnippet}`)
+      .join('\n')
+    // v1.1 修复：文件权限 0600
+    await writeFile(logPath, lines, { encoding: 'utf-8', mode: 0o600 })
   }
 
   /** 获取审计摘要 */
   getAuditSummary() {
-    const summary = { total: this.auditLog.length, allowed: 0, denied: 0, byTool: {} }
+    const summary = {
+      total: this.auditLog.length,
+      allowed: 0,
+      denied: 0,
+      byTool: {},
+    }
     for (const entry of this.auditLog) {
       if (entry.allowed) summary.allowed++
       else summary.denied++

package/src/security/path-guard.js

@@ -1,6 +1,11 @@
 /**
  * 路径安全防护 — 防止路径遍历攻击和敏感文件访问
  * 对应原版: src/utils/permissions/filesystem.ts + 多处路径检查
+ *
+ * v1.1 修复:
+ * - /proc/self/ 加入禁止路径（容器逃逸/内存泄露）
+ * - 新增 URL 编码绕过检测（%2e%2e, %2f, %5c 等）
+ * - 双重编码绕过检测（%252e 等）
  */
 import { resolve, normalize, isAbsolute, relative, sep } from 'path'
 
@@ -16,6 +21,7 @@ const FORBIDDEN_PATHS = [
   '/etc/pam.d/',
   '/boot/',
   '/proc/sys/',
+  '/proc/self/',       // v1.1: 阻止 /proc/self 访问（容器逃逸/内存泄露）
   '/sys/kernel/',
 ]
 
@@ -31,13 +37,21 @@ const SENSITIVE_PREFIXES = [
 
 /**
  * 规范化路径 — 解析 .., ., 符号链接等
+ * v1.1 修复: 增加编码绕过检测（%2e%2e, %252e 等 URL 编码变形）
  * @param {string} filePath — 输入路径
  * @param {string} cwd — 当前工作目录
  * @returns {string} 规范化后的绝对路径
  */
 export function sanitizePath(filePath, cwd = process.cwd()) {
+  // v1.1: 解码 URL 编码绕过（%2e = ., %2f = /, %5c = \）
+  let decoded = filePath
+  // 双重编码先解
+  decoded = decoded.replace(/%252e/gi, '.').replace(/%252f/gi, '/').replace(/%255c/gi, '\\')
+  // 单次编码
+  decoded = decoded.replace(/%2e/gi, '.').replace(/%2f/gi, '/').replace(/%5c/gi, '\\')
+
   // 如果是相对路径，基于 cwd 解析
-  const absPath = isAbsolute(filePath) ? filePath : resolve(cwd, filePath)
+  const absPath = isAbsolute(decoded) ? decoded : resolve(cwd, decoded)
   // 规范化：消除 .. 和 .
   return normalize(absPath)
 }
@@ -52,7 +66,16 @@ export function sanitizePath(filePath, cwd = process.cwd()) {
 export function checkPathTraversal(filePath, cwd = process.cwd(), allowedDirs = []) {
   const resolvedPath = sanitizePath(filePath, cwd)
 
-  // 1. 检查 .. 在原始路径中的使用
+  // 1. v1.1: 检查原始输入中的编码绕过尝试
+  if (/%2e|%2f|%5c|%252e|%252f/i.test(filePath)) {
+    return {
+      safe: false,
+      resolvedPath,
+      reason: `路径编码绕过检测: ${filePath} 包含 URL 编码字符，疑似路径遍历攻击`,
+    }
+  }
+
+  // 2. 检查 .. 在原始路径中的使用
   if (filePath.includes('..')) {
     const normalizedRelative = relative(cwd, resolvedPath)
     if (normalizedRelative.startsWith('..') || resolvedPath.startsWith('/etc/') || resolvedPath.startsWith('/root/')) {
@@ -64,13 +87,12 @@ export function checkPathTraversal(filePath, cwd = process.cwd(), allowedDirs =
     }
   }
 
-  // 2. 检查是否在允许的目录范围内
+  // 3. 检查是否在允许的目录范围内
   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,
@@ -79,7 +101,6 @@ export function checkPathTraversal(filePath, cwd = process.cwd(), allowedDirs =
       }
     }
   }
-
   return { safe: true, resolvedPath }
 }
 
@@ -92,41 +113,26 @@ 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}）`,
-      }
+      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}`,
-      }
+      return { allowed: false, reason: `禁止访问 SSH 密钥文件: ${resolvedPath}` }
     }
-
     if (sshConfigPattern.test(resolvedPath)) {
-      return {
-        allowed: true,
-        reason: `⚠️ 访问 SSH 配置文件: ${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, reason: `⚠️ 访问系统敏感目录: ${resolvedPath}` }
     }
   }
 
@@ -143,7 +149,6 @@ 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
 
@@ -151,7 +156,6 @@ export function checkPathSafety(filePath, options = {}) {
     reasons.push(traversalResult.reason)
   }
 
-  // 禁止路径检查
   if (checkForbidden) {
     const forbiddenResult = checkForbiddenPath(resolvedPath)
     if (!forbiddenResult.allowed) {
@@ -162,7 +166,7 @@ export function checkPathSafety(filePath, options = {}) {
   }
 
   return {
-    safe: !reasons.some(r => r.startsWith('禁止') || r.startsWith('路径遍历')),
+    safe: !reasons.some(r => r.startsWith('禁止') || r.startsWith('路径遍历') || r.startsWith('路径编码绕过')),
     resolvedPath,
     reasons,
   }
@@ -178,13 +182,12 @@ export function checkWritePathSafety(filePath, options = {}) {
   const result = checkPathSafety(filePath, options)
 
   // 写入额外检查：不能写到系统关键目录
-  const systemWriteDirs = ['/etc/', '/boot/', '/usr/bin/', '/usr/lib/', '/sbin/', '/bin/']
+  const systemWriteDirs = ['/etc/', '/boot/', '/usr/bin/', '/usr/lib/', '/sbin/', '/bin/', '/proc/', '/sys/']
   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

@@ -1,99 +1,92 @@
 /**
  * SSRF 防护 — 阻止对内网/云元数据端点的请求
- * 对应原版: src/utils/hooks/ssrfGuard.ts
+ * 对应原版：src/utils/hooks/ssrfGuard.ts
+ * 
+ * v1.2 修复:
+ * - H4: 完整检测 fe80::/10 范围（fe80:: - febf::），而非仅 fe8 前缀
+ * - H3: 导出 dnsLookup 函数供 query-engine 使用自定义 DNS resolver
  */
 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, c, d] = parts
 
-  const [a, b] = parts
-
-  // 回环 — 允许
-  if (a === 127) return false
-
-  // 0.0.0.0/8
+  // 0.0.0.0/8 — "this" 网络
   if (a === 0) return true
-
-  // 10.0.0.0/8
+  // 127.0.0.0/8 — 回环/localhost（SSRF 核心目标，必须阻止）
+  if (a === 127) 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
-
+  // 100.100.100.200 — 阿里云元数据（精确匹配）
+  if (a === 100 && b === 100 && c === 100 && d === 200) 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
-
+  if (a === 192 && b === 0 && c === 2) return true
   // 198.51.100.0/24 — TEST-NET-2
-  if (a === 198 && b === 51 && parts[2] === 100) return true
-
+  if (a === 198 && b === 51 && c === 100) return true
   // 203.0.113.0/24 — TEST-NET-3
-  if (a === 203 && b === 0 && parts[2] === 113) return true
+  if (a === 203 && b === 0 && c === 113) return true
 
   return false
 }
 
 /**
  * 检查 IPv6 地址是否在应被阻止的范围内
- *
- * 阻止:
- * - ::           — 未指定地址
- * - fc00::/7     — 唯一本地地址 (ULA)
- * - fe80::/10    — 链路本地
- * - ::ffff:<被阻止的v4> — IPv4 映射地址
- *
- * 允许:
- * - ::1          — 回环
+ * 
+ * 修复 H4: 完整检测 fe80::/10 范围（fe80:: - febf::）
  */
 function isBlockedV6(address) {
   const normalized = address.toLowerCase()
 
-  // ::1 回环 — 允许
-  if (normalized === '::1') return false
-
+  // ::1 回环 — 阻止（SSRF 核心目标）
+  if (normalized === '::1') return true
   // :: 未指定
   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
+  // fe80::/10 — 链路本地 (fe80:: - febf::)
+  // 修复 H4: 使用数值比较而非前缀匹配
+  const firstTwoBytes = normalized.split(':')[0]
+  if (firstTwoBytes) {
+    const firstByte = parseInt(firstTwoBytes, 16)
+    if (!isNaN(firstByte) && firstByte >= 0xfe80 && firstByte <= 0xfebf) {
+      return true
+    }
+  }
 
-  // ::ffff:<IPv4> — IPv4 映射地址
+  // ::ffff:<IPv4> — 短格式 IPv4 映射地址
   const v4Mapped = normalized.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/)
   if (v4Mapped) {
     return isBlockedV4(v4Mapped[1])
   }
 
+  // 0:0:0:0:0:ffff:<IPv4> — 完整格式 IPv4 映射地址
+  const v4MappedFull = normalized.match(/^0:0:0:0:0:ffff:(\d+\.\d+\.\d+\.\d+)$/)
+  if (v4MappedFull) {
+    return isBlockedV4(v4MappedFull[1])
+  }
+
+  // 64:ff9b::<IPv4> — NAT64 映射地址 (RFC 6052)
+  const nat64Match = normalized.match(/^64:ff9b::(\d+\.\d+\.\d+\.\d+)$/)
+  if (nat64Match) {
+    return isBlockedV4(nat64Match[1])
+  }
+
   return false
 }
 
@@ -126,6 +119,26 @@ export async function checkHostSafety(hostname) {
     }
   }
 
+  // 常见 SSRF 绕过主机名黑名单
+  const blockedHostnames = [
+    'localhost',
+    'localhost.localdomain',
+    'ip6-localhost',
+    'ip6-loopback',
+    'metadata.google.internal', // GCP 元数据
+    'metadata.internal', // AWS 元数据
+    'instance-data', // CloudStack 元数据
+  ]
+  const lowerHost = hostname.toLowerCase()
+  if (blockedHostnames.includes(lowerHost)) {
+    return { allowed: false, addresses: [], reason: `主机名 ${hostname} 为已知 SSRF 目标` }
+  }
+
+  // 阻止 *.internal / *.local / *.localhost 域名模式
+  if (lowerHost.endsWith('.internal') || lowerHost.endsWith('.local') || lowerHost.endsWith('.localhost')) {
+    return { allowed: false, addresses: [], reason: `主机名 ${hostname} 为内网域名` }
+  }
+
   // DNS 解析后检查
   return new Promise((resolve) => {
     dnsLookup(hostname, (err, address) => {
@@ -162,10 +175,10 @@ export async function checkUrlSafety(url) {
 
     // 只允许 HTTP/HTTPS
     if (!['http:', 'https:'].includes(parsed.protocol)) {
-      return { allowed: false, reason: `不支持的协议: ${parsed.protocol}` }
+      return { allowed: false, reason: `不支持的协议：${parsed.protocol}` }
     }
 
-    // 检查主机名
+    // 检查主机名（含主机名黑名单 + DNS 解析）
     const hostResult = await checkHostSafety(parsed.hostname)
     if (!hostResult.allowed) {
       return { allowed: false, reason: hostResult.reason }
@@ -176,3 +189,93 @@ export async function checkUrlSafety(url) {
     return { allowed: false, reason: '无效的 URL' }
   }
 }
+
+/**
+ * 安全 DNS 解析器 — 用于防止 DNS Rebinding 攻击
+ * 返回解析后的 IP 地址列表，可直接用于 fetch 的 DNS 查找
+ * @param {string} hostname — 主机名
+ * @returns {Promise<{addresses: string[], blocked: boolean, reason?: string}>}
+ */
+export async function safeDnsLookup(hostname) {
+  return new Promise((resolve) => {
+    dnsLookup(hostname, (err, address) => {
+      if (err) {
+        resolve({ addresses: [], blocked: false, 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({
+          addresses,
+          blocked: true,
+          reason: `主机 ${hostname} 解析到私有地址 ${blockedAddrs.join(', ')}`,
+        })
+      } else {
+        resolve({ addresses, blocked: false, reason: undefined })
+      }
+    })
+  })
+}
+
+/**
+ * 创建安全 fetch 函数 — 防止 DNS Rebinding
+ * 使用预先解析的 IP 地址，避免二次 DNS 查询
+ * @param {Function} nativeFetch — 原生 fetch
+ * @returns {Function} 安全 fetch
+ */
+export function createSafeFetch(nativeFetch) {
+  return async function safeFetch(url, options = {}) {
+    const parsed = new URL(url)
+    
+    // 只处理 HTTP/HTTPS
+    if (!['http:', 'https:'].includes(parsed.protocol)) {
+      return nativeFetch(url, options)
+    }
+
+    // 检查主机名安全性
+    const hostResult = await checkHostSafety(parsed.hostname)
+    if (!hostResult.allowed) {
+      throw new Error(`SSRF blocked: ${hostResult.reason}`)
+    }
+
+    // 如果主机名是 IP 地址，直接使用
+    if (isIP(parsed.hostname)) {
+      return nativeFetch(url, options)
+    }
+
+    // 对于域名，使用预先解析的 IP 地址
+    // 通过设置 Host header 和直接连接 IP 来防止 DNS Rebinding
+    const lookupResult = await safeDnsLookup(parsed.hostname)
+    if (lookupResult.blocked) {
+      throw new Error(`SSRF blocked: ${lookupResult.reason}`)
+    }
+
+    // 使用第一个非阻止的 IP 地址
+    if (lookupResult.addresses.length > 0) {
+      // 创建一个自定义 Agent 来覆盖 DNS 解析
+      // 注意：这需要 Node.js 的 http/https 模块支持
+      // 简单方案：直接修改 URL 为主机名 + IP
+      const originalHost = parsed.hostname
+      const ip = lookupResult.addresses[0]
+      
+      // 创建新 URL 使用 IP 地址
+      const safeUrl = url.replace(originalHost, ip)
+      
+      // 设置 Host header 为原始主机名
+      const safeOptions = {
+        ...options,
+        headers: {
+          ...options.headers,
+          'Host': originalHost,
+        },
+      }
+      
+      return nativeFetch(safeUrl, safeOptions)
+    }
+
+    return nativeFetch(url, options)
+  }
+}