metona-ai-desktop/electron/harness/tools/built-in/ssrf-guard.ts

/**
 * SSRF 防护共享模块（v0.6.4 P2-2）
 *
 * 背景：此前完整的 SSRF 校验只存在于 http_request 工具内部 —— web_fetch /
 * 浏览器回退完全没有校验且 requiresPermission:false，LLM 可直接抓取
 * 127.0.0.1、169.254.169.254 等内网/云元数据地址，属于工具层最大的安全不对称。
 *
 * 本模块把校验逻辑抽为单一事实来源：
 * - isPrivateIP(ip)          IPv4/IPv6 私有段判定（含 ::ffff: 映射递归）
 * - validateSSRF(url)        校验失败时抛错（原 http_request 契约）
 * - safeValidateSSRF(url)    不抛错的便捷包装（工具内 return-style 使用）
 *
 * 已知限制（与 M7 审查结论一致）：DNS rebinding 在 Node fetch 下无法彻底关闭
 * （不可自定义 lookup/SNI），缓解措施为"解析全部 IP、任一私有即拒 + 重定向终态复检"。
 */

import { lookup } from 'node:dns/promises';
import { isIP } from 'node:net';

/**
 * 检查 IP 是否为私有/内网/回环/元数据地址
 *
 * 覆盖：
 * - IPv4: 127.0.0.0/8 (回环)、10.0.0.0/8、192.168.0.0/16、172.16.0.0/12、
 *         169.254.0.0/16 (链路本地，含云元数据 169.254.169.254)、0.0.0.0/8、
 *         224.0.0.0/4 (组播)、240.0.0.0/4 (保留)
 * - IPv6: ::1 (回环)、fe80::/10 (链路本地)、fc00::/7 (唯一本地)、::ffff: 映射的 IPv4
 */
export function isPrivateIP(ip: string): boolean {
  // IPv4 直接检测
  if (isIP(ip) === 4) {
    const parts = ip.split('.').map(Number);
    if (parts[0] === 127) return true; // 回环
    if (parts[0] === 10) return true; // 内网
    if (parts[0] === 192 && parts[1] === 168) return true; // 内网
    if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) return true; // 内网
    if (parts[0] === 169 && parts[1] === 254) return true; // 链路本地（含云元数据）
    if (parts[0] === 0) return true; // 0.0.0.0/8
    if (parts[0] >= 224) return true; // 组播 + 保留
    return false;
  }

  // IPv6 检测
  if (isIP(ip) === 6) {
    const lower = ip.toLowerCase();
    if (lower === '::1') return true; // 回环
    if (lower.startsWith('fe80:')) return true; // 链路本地
    if (lower.startsWith('fc') || lower.startsWith('fd')) return true; // 唯一本地
    // ::ffff: 映射的 IPv4 — 提取 IPv4 部分递归检测
    const v4MappedMatch = lower.match(/::ffff:(\d+\.\d+\.\d+\.\d+)$/);
    if (v4MappedMatch) return isPrivateIP(v4MappedMatch[1]);
    return false;
  }

  // 非 IP 格式（域名等），由调用方 DNS 解析后再检测
  return false;
}

/**
 * SSRF 校验 + 公网地址解析（单一事实来源）
 *
 * v0.7.3 P2-1 重构：resolvePublicAddresses 承载全部校验逻辑并返回解析出的
 * 公网 IP 集合；validateSSRF 成为它的"只要不抛错"薄包装。这样 pinning 层
 * （ssrf-dispatcher）能拿到与校验完全同一批 IP，避免"校验一次解析、连接
 * 再解析一次"的双解析不一致。
 *
 * 1. 协议白名单：仅允许 http/https
 * 2. hostname 为 IP 时直接检测
 * 3. 域名 — DNS 解析后检测所有 IP；任意一个 IP 为私有即拒绝
 *    （防止 DNS rebinding 中只校验第一个 IP 的绕过）
 *
 * @returns 校验通过的全部公网 IP（供 DNS pinning 使用）
 * @throws 如果 URL 指向私有/内网/回环地址或协议不被允许
 */
export async function resolvePublicAddresses(url: string): Promise<string[]> {
  let parsed: URL;
  try {
    parsed = new URL(url);
  } catch {
    throw new Error(`Invalid URL: ${url}`);
  }

  // 协议白名单
  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
    throw new Error(`Blocked SSRF: protocol "${parsed.protocol}" not allowed (only http/https)`);
  }

  const hostname = parsed.hostname;

  // 如果 hostname 本身就是 IP，直接检测
  if (isIP(hostname)) {
    if (isPrivateIP(hostname)) {
      throw new Error(`Blocked SSRF: ${hostname} is a private/loopback address`);
    }
    return [hostname];
  }

  // 域名 — DNS 解析后检测所有 IP
  let addresses: Array<{ address: string }>;
  try {
    addresses = await lookup(hostname, { all: true });
  } catch (err) {
    throw new Error(
      `Blocked SSRF: DNS resolution failed for ${hostname}: ${(err as Error).message}`,
    );
  }

  if (addresses.length === 0) {
    throw new Error(`Blocked SSRF: no DNS records for ${hostname}`);
  }

  const publicIps: string[] = [];
  for (const { address } of addresses) {
    if (isPrivateIP(address)) {
      throw new Error(`Blocked SSRF: ${hostname} resolves to private IP ${address}`);
    }
    publicIps.push(address);
  }
  return publicIps;
}

/**
 * SSRF 校验 — 解析 URL 域名并校验 IP（v0.7.3 起为 resolvePublicAddresses 的
 * "仅校验不取值"包装，校验逻辑单一来源在后者）
 *
 * @throws 如果 URL 指向私有/内网/回环地址或协议不被允许
 */
export async function validateSSRF(url: string): Promise<void> {
  await resolvePublicAddresses(url);
}

/** validateSSRF 的不抛错包装：返回结构化结果供工具 execute 直接 return */
export async function safeValidateSSRF(
  url: string,
): Promise<{ ok: true } | { ok: false; error: string }> {
  try {
    await validateSSRF(url);
    return { ok: true };
  } catch (err) {
    return { ok: false, error: (err as Error).message };
  }
}