Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

15.4 KB
Raw Blame
/**
 * SSRF guard for user-supplied provider endpoints.
 *
 * A `provider` machine is reached at a URL the OWNER typed. That is a deliberate product decision and
 * it puts an attacker-controlled string in front of an outbound request from our infrastructure — the
 * classic route to a cloud metadata endpoint or an internal service. This module is the mitigation,
 * and every request to a provider MUST go through `providerFetch`.
 *
 * The rule people usually miss is #3 below. Validating the URL when the machine is created is not
 * enough: DNS can return a public address at save time and a private one at request time (rebinding).
 * So validation happens **inside the socket's `lookup` hook**, on the address actually being dialled —
 * there is no window between the check and the connection.
 *
 * Deliberately built on `node:https` rather than `fetch`: only the raw request API exposes `lookup`,
 * and pinning the resolved address is the whole point. No new dependency either.
 */
import { request as httpRequest, type IncomingMessage } from 'node:http'
import { request as httpsRequest } from 'node:https'
import { isIP, type LookupFunction } from 'node:net'
import { lookup as dnsLookup } from 'node:dns/promises'
import { env } from '../config/env.js'

export class ProviderUrlError extends Error {
  constructor(message: string, readonly code: ProviderUrlErrorCode) {
    super(message)
    this.name = 'ProviderUrlError'
  }
}

export type ProviderUrlErrorCode =
  | 'INVALID_URL'
  | 'INSECURE_SCHEME'
  | 'BLOCKED_ADDRESS'
  | 'DNS_FAILED'
  | 'REDIRECT_REFUSED'
  | 'TIMEOUT'
  | 'RESPONSE_TOO_LARGE'

/** Messages are shown to the owner in the create dialog, so they say what to do about it. */
const REASONS: Record<ProviderUrlErrorCode, string> = {
  INVALID_URL: 'That is not a valid URL',
  INSECURE_SCHEME: 'The provider URL must use https://',
  BLOCKED_ADDRESS: 'That URL points at a private or internal network address',
  DNS_FAILED: 'That hostname could not be resolved',
  REDIRECT_REFUSED: 'The provider redirected the request, which is not allowed',
  TIMEOUT: 'The provider did not respond in time',
  RESPONSE_TOO_LARGE: 'The provider sent more data than allowed',
}

export const reasonFor = (code: ProviderUrlErrorCode): string => REASONS[code]

// ── Address policy ───────────────────────────────────────────────────────────────────────────────

/**
 * True for an address we refuse to dial.
 *
 * `169.254.0.0/16` is the important one and the reason this list is not just "private ranges":
 * `169.254.169.254` is the cloud instance-metadata endpoint on AWS, GCP and Azure, and reaching it
 * from our infrastructure hands over instance credentials.
 */
export function isBlockedAddress(ip: string): boolean {
  const family = isIP(ip)
  if (family === 4) return isBlockedIPv4(ip)
  if (family === 6) return isBlockedIPv6(ip)
  return true // not an address we can reason about → refuse
}

function isBlockedIPv4(ip: string): boolean {
  const parts = ip.split('.').map((p) => Number(p))
  if (parts.length !== 4 || parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return true
  const [a, b] = parts as [number, number, number, number]
  if (a === 0) return true                        // 0.0.0.0/8 "this network"
  if (a === 10) return true                       // private
  if (a === 127) return true                      // loopback
  if (a === 169 && b === 254) return true         // link-local — cloud metadata
  if (a === 172 && b >= 16 && b <= 31) return true // private
  if (a === 192 && b === 168) return true         // private
  if (a === 100 && b >= 64 && b <= 127) return true // CGNAT
  if (a === 192 && b === 0) return true           // IETF protocol assignments / 192.0.2.0 TEST-NET
  if (a >= 224) return true                       // multicast + reserved + broadcast
  return false
}

/** The 16 bytes of an IPv6 address in any spelling — hex groups, `::`, an embedded dotted IPv4 —
 *  or null when it is not one. Judging bytes, not text, is what makes every spelling of one address
 *  get one answer: `new URL` and `dns.lookup` both print mapped IPv4 as hex (`::ffff:a9fe:a9fe`). */
function ipv6Bytes(raw: string): Uint8Array | null {
  let ip = raw.toLowerCase().replace(/^\[|\]$/g, '')
  const zone = ip.indexOf('%')
  if (zone >= 0) ip = ip.slice(0, zone)
  // A trailing dotted IPv4 stands for the last two groups.
  const v4 = /^(.*:)(\d+\.\d+\.\d+\.\d+)$/.exec(ip)
  if (v4) {
    const parts = v4[2]!.split('.').map(Number)
    if (parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return null
    ip = `${v4[1]}${((parts[0]! << 8) | parts[1]!).toString(16)}:${((parts[2]! << 8) | parts[3]!).toString(16)}`
  }
  const halves = ip.split('::')
  if (halves.length > 2) return null
  const head = halves[0] ? halves[0].split(':') : []
  const tail = halves.length === 2 && halves[1] ? halves[1].split(':') : []
  const missing = 8 - head.length - tail.length
  if (halves.length === 1 ? head.length !== 8 : missing < 1) return null
  const groups = [...head, ...Array<string>(halves.length === 2 ? missing : 0).fill('0'), ...tail]
  const bytes = new Uint8Array(16)
  for (let i = 0; i < 8; i++) {
    if (!/^[0-9a-f]{1,4}$/.test(groups[i]!)) return null
    const n = parseInt(groups[i]!, 16)
    bytes[2 * i] = n >> 8
    bytes[2 * i + 1] = n & 0xff
  }
  return bytes
}

const startsWith = (bytes: Uint8Array, prefix: number[]): boolean => prefix.every((b, i) => bytes[i] === b)
const v4At = (bytes: Uint8Array, at: number): string => [...bytes.slice(at, at + 4)].join('.')

function isBlockedIPv6(raw: string): boolean {
  const b = ipv6Bytes(raw)
  if (!b) return true                                         // not an address we can reason about → refuse
  const zeros = (n: number) => Array<number>(n).fill(0)
  // Every form that carries an IPv4 address is judged as that IPv4, or each rule above is bypassed.
  if (startsWith(b, [...zeros(10), 0xff, 0xff])) return isBlockedIPv4(v4At(b, 12))       // ::ffff:0:0/96 mapped
  if (startsWith(b, [...zeros(8), 0xff, 0xff, 0, 0])) return isBlockedIPv4(v4At(b, 12))  // ::ffff:0:0:0/96 translated
  if (startsWith(b, zeros(12))) return true                    // ::/96: ::, ::1 and the deprecated IPv4-compatible
  if (startsWith(b, [0x00, 0x64, 0xff, 0x9b, ...zeros(8)])) return isBlockedIPv4(v4At(b, 12)) // 64:ff9b::/96 NAT64
  if (startsWith(b, [0x00, 0x64, 0xff, 0x9b, 0x00, 0x01])) return true                 // 64:ff9b:1::/48 local NAT64
  if (startsWith(b, [0x20, 0x02])) return isBlockedIPv4(v4At(b, 2))                     // 2002::/16 6to4
  if (startsWith(b, [0x01, 0x00, ...zeros(6)])) return true    // 100::/64 discard-only
  if (startsWith(b, [0x20, 0x01, 0x0d, 0xb8])) return true     // 2001:db8::/32 documentation
  if (startsWith(b, [0x20, 0x01, 0x00, 0x00])) return true     // 2001::/32 Teredo (carries an obfuscated IPv4)
  if ((b[0]! & 0xfe) === 0xfc) return true                     // fc00::/7 unique-local
  if (b[0] === 0xfe && (b[1]! & 0xc0) === 0x80) return true    // fe80::/10 link-local
  if (b[0] === 0xfe && (b[1]! & 0xc0) === 0xc0) return true    // fec0::/10 site-local (deprecated, still routed internally)
  if (b[0] === 0xff) return true                               // multicast
  return false
}

// ── URL policy ───────────────────────────────────────────────────────────────────────────────────

export interface CheckedTarget {
  /** Normalised absolute URL. */
  url: string
  hostname: string
  port: number
  /** The address it resolved to at check time — informational; the connection re-checks. */
  ip: string
}

function allowInsecure(): boolean {
  return env.PROVIDER_ALLOW_INSECURE_URLS === true
}

/**
 * The address policy, with the dev escape hatch applied.
 *
 * `isBlockedAddress` is the pure policy and stays that way so it can be asserted directly. This is
 * the enforcement point, and it has to honour the dev flag for the same reason the flag exists: a
 * local `example-provider` (autonomous-ai/openharness) lives at `http://127.0.0.1:4502`, which
 * is refused on BOTH counts —
 * plain http AND loopback. Lifting only the scheme left the flag unable to do the one job it was
 * added for, which is exactly what happened until someone tried to test locally.
 */
function refuseAddress(ip: string): boolean {
  return isBlockedAddress(ip) && !allowInsecure()
}

/**
 * Parse and vet a user-supplied URL. Throws `ProviderUrlError` with a code the UI can map.
 *
 * Passing this does NOT make the URL permanently safe — `providerFetch` re-checks at connect time.
 * This exists to reject obvious mistakes at the moment the owner types them, with a useful message.
 */
export async function checkProviderUrl(raw: string): Promise<CheckedTarget> {
  let url: URL
  try {
    url = new URL(raw.trim())
  } catch {
    throw new ProviderUrlError(REASONS.INVALID_URL, 'INVALID_URL')
  }

  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && allowInsecure())) {
    throw new ProviderUrlError(
      url.protocol === 'http:' ? REASONS.INSECURE_SCHEME : REASONS.INVALID_URL,
      url.protocol === 'http:' ? 'INSECURE_SCHEME' : 'INVALID_URL',
    )
  }
  if (url.username || url.password) throw new ProviderUrlError(REASONS.INVALID_URL, 'INVALID_URL')

  const hostname = url.hostname.replace(/^\[|\]$/g, '')
  const port = Number(url.port || (url.protocol === 'https:' ? 443 : 80))

  // A literal address skips DNS but not the policy.
  if (isIP(hostname)) {
    if (refuseAddress(hostname)) throw new ProviderUrlError(REASONS.BLOCKED_ADDRESS, 'BLOCKED_ADDRESS')
    return { url: url.toString(), hostname, port, ip: hostname }
  }

  const resolved = await resolveAll(hostname)
  // EVERY address must pass: a hostname with one public and one private A record is not safe just
  // because the resolver happened to return the public one first.
  for (const addr of resolved) {
    if (refuseAddress(addr)) throw new ProviderUrlError(REASONS.BLOCKED_ADDRESS, 'BLOCKED_ADDRESS')
  }
  return { url: url.toString(), hostname, port, ip: resolved[0]! }
}

async function resolveAll(hostname: string): Promise<string[]> {
  try {
    const entries = await dnsLookup(hostname, { all: true, verbatim: true })
    if (!entries.length) throw new Error('no addresses')
    return entries.map((e) => e.address)
  } catch {
    throw new ProviderUrlError(REASONS.DNS_FAILED, 'DNS_FAILED')
  }
}

// ── The guarded request ──────────────────────────────────────────────────────────────────────────

export interface ProviderRequestInit {
  method?: string
  headers?: Record<string, string>
  body?: string
  /** Whole-request budget. Streaming callers pass a large value. */
  timeoutMs?: number
  signal?: AbortSignal
}

export interface ProviderResponse {
  status: number
  headers: Record<string, string | string[] | undefined>
  /** Raw stream — SSE callers read it incrementally. */
  stream: IncomingMessage
}

export const DEFAULT_TIMEOUT_MS = 10_000
export const MAX_BODY_BYTES = 5 * 1024 * 1024

/**
 * Make a request to a provider with the address policy enforced **at connect time**.
 *
 * The `lookup` hook is the load-bearing part: it runs when the socket is about to connect, resolves
 * the name itself, and refuses to hand back a blocked address. There is no gap between validating an
 * address and connecting to it, which is what defeats DNS rebinding.
 */
export function providerFetch(target: string, init: ProviderRequestInit = {}): Promise<ProviderResponse> {
  return new Promise((resolve, reject) => {
    let url: URL
    try {
      url = new URL(target)
    } catch {
      reject(new ProviderUrlError(REASONS.INVALID_URL, 'INVALID_URL'))
      return
    }
    const secure = url.protocol === 'https:'
    if (!secure && !(url.protocol === 'http:' && allowInsecure())) {
      reject(new ProviderUrlError(REASONS.INSECURE_SCHEME, 'INSECURE_SCHEME'))
      return
    }

    const timeoutMs = init.timeoutMs ?? DEFAULT_TIMEOUT_MS
    const req = (secure ? httpsRequest : httpRequest)(
      {
        protocol: url.protocol,
        hostname: url.hostname.replace(/^\[|\]$/g, ''),
        port: url.port || (secure ? '443' : '80'),
        path: `${url.pathname}${url.search}`,
        method: init.method ?? 'GET',
        headers: init.headers,
        // THE guard. Called by the socket layer with the host it is about to connect to.
        lookup: guardedLookup,
        timeout: timeoutMs,
      },
      (res) => {
        // No redirects. Following one would re-open every check on a URL the owner never typed.
        if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
          res.destroy()
          reject(new ProviderUrlError(REASONS.REDIRECT_REFUSED, 'REDIRECT_REFUSED'))
          return
        }
        resolve({ status: res.statusCode ?? 0, headers: res.headers, stream: res })
      },
    )

    req.on('timeout', () => {
      req.destroy(new ProviderUrlError(REASONS.TIMEOUT, 'TIMEOUT'))
    })
    req.on('error', (err) => reject(err))
    init.signal?.addEventListener('abort', () => req.destroy(), { once: true })
    if (init.body) req.write(init.body)
    req.end()
  })
}

/**
 * `dns.lookup`-shaped hook that refuses blocked addresses.
 *
 * Node calls this with the hostname at connect time; whatever it returns is what the socket dials.
 * Refusing here means a rebinding attack has nothing to rebind to.
 */
const guardedLookup: LookupFunction = (hostname, options, callback) => {
  if (isIP(hostname)) {
    if (refuseAddress(hostname)) {
      callback(new ProviderUrlError(REASONS.BLOCKED_ADDRESS, 'BLOCKED_ADDRESS') as NodeJS.ErrnoException, '', 0)
      return
    }
    if (options.all) callback(null, [{ address: hostname, family: isIP(hostname) }])
    else callback(null, hostname, isIP(hostname))
    return
  }
  dnsLookup(hostname, { all: true, verbatim: true })
    .then((entries) => {
      const usable = entries.find((e) => !refuseAddress(e.address))
      const blocked = entries.some((e) => refuseAddress(e.address))
      // Any blocked address in the answer set disqualifies the host outright — picking the "good"
      // one would let an attacker keep a public A record purely to pass the check.
      if (blocked || !usable) {
        callback(new ProviderUrlError(REASONS.BLOCKED_ADDRESS, 'BLOCKED_ADDRESS') as NodeJS.ErrnoException, '', 0)
        return
      }
      // Node's family autoselection asks for all addresses, not the scalar lookup result.
      if (options.all) callback(null, entries)
      else callback(null, usable.address, usable.family)
    })
    .catch(() => callback(new ProviderUrlError(REASONS.DNS_FAILED, 'DNS_FAILED') as NodeJS.ErrnoException, '', 0))
}

/** Read a guarded response as text, refusing anything over the cap. */
export async function readBodyCapped(res: ProviderResponse, max = MAX_BODY_BYTES): Promise<string> {
  const chunks: Buffer[] = []
  let size = 0
  for await (const chunk of res.stream) {
    size += (chunk as Buffer).length
    if (size > max) {
      res.stream.destroy()
      throw new ProviderUrlError(REASONS.RESPONSE_TOO_LARGE, 'RESPONSE_TOO_LARGE')
    }
    chunks.push(chunk as Buffer)
  }
  return Buffer.concat(chunks).toString('utf8')
}