@lukethegenius/safe-fetch

SSRF-safe URL validation/reachability check, plus honest fetch error helpers.

Install

npm install @lukethegenius/safe-fetch

Usage

import { isSafePublicUrl, checkUrlReachable, ApiError, apiErrorMessage } from '@lukethegenius/safe-fetch'

// Reject loopback/private/link-local/metadata hosts before you fetch a user-supplied URL
if (!isSafePublicUrl(userUrl)) throw new Error('unsafe url')

const result = await checkUrlReachable(userUrl) // { status: 'ok' | 'broken' | 'unknown', httpStatus?, reason? }

// Client-side fetch that throws instead of silently returning empty data
const res = await fetch('/api/thing')
if (!res.ok) throw new ApiError(await apiErrorMessage(res, 'Request failed'), res.status)

isSafePublicUrl blocks non-http(s) schemes and loopback/private/link-local/CGNAT/metadata/IPv6-literal hosts. checkUrlReachable uses it as a guard before issuing a HEAD (falling back to a ranged GET) with a 4s timeout.