Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

11.7 KB
Raw Blame
/**
 * SSRF guard shared by every tool that fetches remote content (web pages,
 * skill installs). The model fetches URLs at the instruction of whoever it
 * is talking to — or of content it fetched earlier — so every target must
 * be validated: scheme, literal hosts, DNS-resolved addresses, and every
 * redirect hop (redirect: 'manual' — a public URL must not be able to hop
 * into a private one).
 *
 * Validation and connection are kept on the same address: the hostname is
 * resolved here, any answer containing a non-global address is rejected
 * (fail closed on DNS mixed answers), and the connection is pinned to the
 * exact address that was validated so a hostile resolver cannot swap in a
 * private address between the check and the fetch (TOCTOU / DNS rebinding).
 */

import { lookup } from 'node:dns';
import { isIP } from 'node:net';
import { Agent, fetch as undiciFetch } from 'undici';

const DEFAULT_HEADERS = {
  'User-Agent': 'Mercury-Agent/0.1.0',
  'Accept': 'text/html,application/json,text/plain',
};

const ALLOW_PRIVATE_FETCH = process.env.MERCURY_ALLOW_PRIVATE_FETCH === '1';

export const MAX_REDIRECTS = 5;

function isPrivateIpv4(ip: string): boolean {
  const v4 = ip.split('.').map((p) => parseInt(p, 10));
  if (v4.length !== 4 || v4.some((p) => Number.isNaN(p) || p < 0 || p > 255)) return false;
  const [a, b, c] = v4;
  if (a === 0 || a === 10 || a === 127) return true;
  if (a === 169 && b === 254) return true; // link-local incl. cloud metadata
  if (a === 172 && b >= 16 && b <= 31) return true;
  if (a === 192 && b === 168) return true;
  if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT
  // Special-use / non-global blocks (RFC 6890): benchmarking, IETF protocol
  // assignments and the TEST-NET ranges. Not globally routable, so not valid
  // fetch targets.
  if (a === 198 && (b === 18 || b === 19)) return true; // 198.18.0.0/15 benchmark
  if (a === 192 && b === 0 && (c === 0 || c === 2)) return true; // 192.0.0.0/24, 192.0.2.0/24
  if (a === 198 && b === 51 && c === 100) return true; // 198.51.100.0/24 TEST-NET-2
  if (a === 203 && b === 0 && c === 113) return true; // 203.0.113.0/24 TEST-NET-3
  if (a >= 224) return true; // multicast + reserved
  return false;
}

function isPrivateIpv6(ip: string): boolean {
  const lower = ip.toLowerCase();
  if (lower === '::' || lower === '::1') return true;
  if (lower.startsWith('::ffff:')) {
    const mapped = lower.slice('::ffff:'.length);
    return isIP(mapped) === 4 ? isPrivateIpv4(mapped) : true;
  }
  const head = lower.split(':')[0] ?? '';
  if (/^fe[89ab]/.test(head)) return true; // fe80::/10 link-local
  if (/^fe[c-f]/.test(head)) return true; // fec0::/10 site-local (deprecated)
  if (/^f[cd]/.test(head)) return true; // fc00::/7 unique local
  if (/^ff/.test(head)) return true; // ff00::/8 multicast
  if (lower.startsWith('2001:db8')) return true; // 2001:db8::/32 documentation
  return false;
}

/**
 * Link-local addresses, where cloud metadata services live (169.254.169.254,
 * fd00:ec2::254 is unique-local and stays private). `allowPrivate` opens
 * loopback and the LAN, never these: a metadata endpoint hands out the
 * machine's cloud credentials.
 */
export function isLinkLocalAddress(ip: string): boolean {
  const lower = ip.toLowerCase();
  const v4 = lower.startsWith('::ffff:') ? lower.slice('::ffff:'.length) : lower;
  if (isIP(v4) === 4) return v4.startsWith('169.254.');
  return isIP(lower) === 6 && /^fe[89ab]/.test(lower.split(':')[0] ?? '');
}

const METADATA_HOSTS = new Set(['metadata.google.internal', 'metadata', 'instance-data', 'instance-data.ec2.internal']);

export function isPrivateAddress(ip: string): boolean {
  const family = isIP(ip);
  if (family === 4) return isPrivateIpv4(ip);
  if (family === 6) return isPrivateIpv6(ip);
  return false;
}

function urlHostIsPrivate(hostname: string): boolean {
  // Literal IP in the URL — no DNS needed.
  if (isIP(hostname)) return isPrivateAddress(hostname);
  const lower = hostname.toLowerCase().replace(/\.$/, '');
  if (lower === 'localhost' || lower.endsWith('.localhost') || lower.endsWith('.local') || lower.endsWith('.internal')) return true;
  return false;
}

const DEFAULT_PRIVATE_HINT = 'Set MERCURY_ALLOW_PRIVATE_FETCH=1 to allow fetching internal hosts.';

function privateBlockReason(host: string, hint = DEFAULT_PRIVATE_HINT): Error {
  return new Error(`Blocked: ${host} is a private/internal address (SSRF protection). ${hint}`);
}

function lookupHost(hostname: string): Promise<string[]> {
  return new Promise((resolve) => {
    lookup(hostname, { all: true }, (err, addresses) => {
      if (err) {
        resolve([]);
        return;
      }
      resolve(Array.isArray(addresses) ? addresses.map((a) => a.address) : [String(addresses)]);
    });
  });
}

type PinnedAddress = { address: string; family: number };
type ResolvedTarget = { url: URL; pinned?: PinnedAddress };

async function resolveAndValidate(rawUrl: string, allowPrivate = false, privateHint?: string): Promise<ResolvedTarget> {
  let parsed: URL;
  try {
    parsed = new URL(rawUrl);
  } catch {
    throw new Error('Invalid URL');
  }
  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
    throw new Error(`Blocked scheme: ${parsed.protocol} — only http and https are allowed`);
  }
  if (allowPrivate) {
    // Loopback and the LAN are allowed; link-local (cloud metadata) never is.
    const host = parsed.hostname.replace(/^\[|\]$/g, '').toLowerCase();
    if (METADATA_HOSTS.has(host)) throw new Error(`Blocked: ${host} is a cloud metadata service`);
    const literal = isIP(host);
    if (literal !== 0) {
      if (isLinkLocalAddress(host)) throw new Error(`Blocked: ${host} is link-local (cloud metadata)`);
      return { url: parsed, pinned: { address: host, family: literal } };
    }
    const resolved = await lookupHost(host);
    if (resolved.some(isLinkLocalAddress)) throw new Error(`Blocked: ${host} resolves to a link-local (cloud metadata) address`);
    return { url: parsed, ...(resolved[0] ? { pinned: { address: resolved[0], family: isIP(resolved[0]) } } : {}) };
  }
  if (urlHostIsPrivate(parsed.hostname)) {
    throw privateBlockReason(parsed.hostname, privateHint);
  }
  if (ALLOW_PRIVATE_FETCH) {
    return { url: parsed };
  }
  const literalFamily = isIP(parsed.hostname);
  if (literalFamily !== 0) {
    return { url: parsed, pinned: { address: parsed.hostname, family: literalFamily } };
  }
  const addresses = await lookupHost(parsed.hostname);
  if (addresses.length === 0) {
    // Nothing resolved — let the fetch fail on its own rather than guessing.
    return { url: parsed };
  }
  // Fail closed on DNS mixed answers: one non-global record is enough to
  // refuse the target, because we cannot know which record a re-resolving
  // connection would have picked.
  const offending = addresses.find((ip) => isPrivateAddress(ip));
  if (offending) {
    throw privateBlockReason(parsed.hostname, privateHint);
  }
  const chosen = addresses[0]!;
  return { url: parsed, pinned: { address: chosen, family: isIP(chosen) } };
}

/** Throws with a human-readable reason when the URL must not be fetched. */
export async function assertFetchableTarget(rawUrl: string): Promise<URL> {
  return (await resolveAndValidate(rawUrl)).url;
}

// Pinned lookups for the current in-flight requests, keyed by hostname. The
// guarded agent consults this table so its connection goes to the exact
// address that was validated instead of re-resolving.
const pinnedByHost = new Map<string, PinnedAddress>();

const guardedAgent = new Agent({
  connect: {
    // undici types this hook against its internal LookupFunction; the shape
    // below matches what it invokes at connect time.
    lookup: ((hostname: string, options: { all?: boolean } | undefined, callback: (...args: unknown[]) => void) => {
      const pinned = pinnedByHost.get(hostname);
      if (!pinned) {
        (lookup as unknown as (host: string, opts: unknown, cb: unknown) => void)(hostname, options, callback);
        return;
      }
      if (options?.all) callback(null, [{ address: pinned.address, family: pinned.family }]);
      else callback(null, pinned.address, pinned.family);
    }) as never,
  },
});

type FetchInitWithDispatcher = RequestInit & { dispatcher: Agent };

// A dispatcher and fetch must speak the same Undici protocol. Node's bundled
// fetch can be newer than our dependency (Node 26 uses the new handler API),
// so passing this package's Agent to global fetch fails before any request.
// Keep the existing web Fetch API types at the boundary: the package and Node
// ship separately versioned declarations for the same request/response APIs.
const fetchWithDispatcher = undiciFetch as unknown as (
  input: URL,
  init: FetchInitWithDispatcher,
) => Promise<Response>;

/** Fetch with SSRF validation on the initial URL AND every redirect hop. */
export async function guardedFetch(rawUrl: string, signal: AbortSignal, headers?: Record<string, string>): Promise<Response> {
  let target = rawUrl;
  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
    const { url, pinned } = await resolveAndValidate(target);
    const host = url.hostname;
    if (pinned) pinnedByHost.set(host, pinned);
    try {
      const init: FetchInitWithDispatcher = {
        signal,
        redirect: 'manual',
        headers: headers ?? DEFAULT_HEADERS,
        dispatcher: guardedAgent,
      };
      const resp = await fetchWithDispatcher(url, init);
      if (resp.status >= 300 && resp.status < 400) {
        const location = resp.headers.get('location');
        if (location) {
          try { void resp.body?.cancel(); } catch { /* best effort */ }
          target = new URL(location, url).href;
          continue;
        }
      }
      return resp;
    } finally {
      if (pinned && pinnedByHost.get(host)?.address === pinned.address) {
        pinnedByHost.delete(host);
      }
    }
  }
  throw new Error('Blocked: too many redirects');
}

export type GuardedFetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>;

export class PinTable {
  private readonly pins = new Map<string, { pin: { address: string; family: number }; count: number }>();

  acquire(host: string, pin: { address: string; family: number }): void {
    const entry = this.pins.get(host);
    this.pins.set(host, { pin, count: (entry?.count ?? 0) + 1 });
  }

  release(host: string): void {
    const entry = this.pins.get(host);
    if (!entry) return;
    if (entry.count <= 1) this.pins.delete(host);
    else entry.count -= 1;
  }

  get(host: string): { address: string; family: number } | undefined {
    return this.pins.get(host)?.pin;
  }
}

const guardedFetchPins = new PinTable();

const guardedFetchAgent = new Agent({
  connect: {
    lookup: ((hostname: string, options: { all?: boolean } | undefined, callback: (...args: unknown[]) => void) => {
      const pinned = guardedFetchPins.get(hostname);
      if (!pinned) {
        (lookup as unknown as (host: string, opts: unknown, cb: unknown) => void)(hostname, options, callback);
        return;
      }
      if (options?.all) callback(null, [{ address: pinned.address, family: pinned.family }]);
      else callback(null, pinned.address, pinned.family);
    }) as never,
  },
});

export function createGuardedFetch(options: { allowPrivate?: boolean; privateHint?: string } = {}): GuardedFetchLike {
  return async (input, init = {}) => {
    const href = typeof input === 'string' ? input : input.href;
    const { url, pinned } = await resolveAndValidate(href, options.allowPrivate === true, options.privateHint);
    const host = url.hostname;
    if (pinned) guardedFetchPins.acquire(host, pinned);
    try {
      const guardedInit: FetchInitWithDispatcher = { ...init, redirect: 'manual', dispatcher: guardedFetchAgent };
      return await fetchWithDispatcher(url, guardedInit);
    } finally {
      if (pinned) guardedFetchPins.release(host);
    }
  };
}