webveil 0.0.0 → 0.1.0

package/src/core/egress.ts

@@ -0,0 +1,106 @@
+// egress seam — how outbound HTTP leaves the machine. Yields TWO artifacts off
+// the SAME undici dispatcher: the proxied `http` helper (see http.ts, handed to
+// backends) and an egress-bound WHATWG `fetch` (injected into distilly/fetch).
+//
+// CRITICAL anonymity invariant (docs/adr/0001): egress is fail-loud. A
+// configured proxy that cannot be built MUST throw — it must NEVER silently
+// fall back to un-proxied (direct) transport.
+
+import {Agent, type Dispatcher, ProxyAgent, fetch as undiciFetch} from 'undici';
+import {socksDispatcher} from 'fetch-socks';
+import type {Config, Egress} from './config.js';
+
+/** Thrown when a configured egress proxy cannot be built. Never swallowed. */
+export class EgressError extends Error {
+	constructor(message: string, options?: {cause?: unknown}) {
+		super(message, options);
+		this.name = 'EgressError';
+	}
+}
+
+function socksFromUrl(raw: string): Dispatcher {
+	const url = new URL(raw); // throws on a malformed proxy URL → fail loud
+	const protocol = url.protocol.replace(':', '');
+	if (protocol !== 'socks5' && protocol !== 'socks' && protocol !== 'socks5h')
+		throw new EgressError(
+			`egress socks5: expected a socks5:// proxy url, got ${raw}`,
+		);
+	const port = Number(url.port);
+	if (!url.hostname || !Number.isInteger(port) || port <= 0)
+		throw new EgressError(`egress socks5: invalid host/port in ${raw}`);
+	return socksDispatcher({
+		type: 5,
+		host: url.hostname,
+		port,
+		userId: url.username || undefined,
+		password: url.password || undefined,
+	});
+}
+
+/**
+ * Build the undici Dispatcher for the config's egress mode:
+ *   - direct → undefined (undici uses its default, un-proxied transport)
+ *   - http   → ProxyAgent
+ *   - socks5 → socks dispatcher (undici Agent over a socks connector)
+ *
+ * Throws (fail loud) if a configured http/socks5 proxy cannot be built. It
+ * NEVER returns `undefined` (direct) as a fallback for a broken proxy.
+ */
+export function buildDispatcher(cfg: Config): Dispatcher | undefined {
+	const egress: Egress = cfg.egress;
+	switch (egress.mode) {
+		case 'direct':
+			return undefined;
+		case 'http':
+			try {
+				if (!egress.url) throw new Error('missing proxy url');
+				return new ProxyAgent(egress.url);
+			} catch (cause) {
+				throw new EgressError(
+					`egress http: could not build proxy for ${egress.url}`,
+					{cause},
+				);
+			}
+		case 'socks5':
+			try {
+				if (!egress.url) throw new Error('missing proxy url');
+				return socksFromUrl(egress.url);
+			} catch (cause) {
+				if (cause instanceof EgressError) throw cause;
+				throw new EgressError(
+					`egress socks5: could not build proxy for ${egress.url}`,
+					{cause},
+				);
+			}
+		default: {
+			const exhaustive: never = egress;
+			throw new EgressError(
+				`egress: unknown mode ${JSON.stringify(exhaustive)}`,
+			);
+		}
+	}
+}
+
+/** A WHATWG-compatible fetch bound to a specific egress dispatcher. */
+export type EgressFetch = typeof globalThis.fetch;
+
+/**
+ * Build an egress-bound WHATWG `fetch`: undici's `fetch` closed over the
+ * dispatcher from buildDispatcher(cfg). This is the `fetch` injected into
+ * distilly/fetch so distilly never has egress of its own. Same fail-loud
+ * guarantee: a broken proxy throws HERE (before any I/O), never goes un-proxied.
+ */
+export function createEgressFetch(cfg: Config): EgressFetch {
+	const dispatcher = buildDispatcher(cfg);
+	return ((input: RequestInfo | URL, init?: RequestInit) =>
+		undiciFetch(
+			input as never,
+			{
+				...((init ?? {}) as Record<string, unknown>),
+				dispatcher,
+			} as never,
+		)) as EgressFetch;
+}
+
+export type {Dispatcher};
+export {Agent, ProxyAgent};

package/src/core/extract.ts

@@ -0,0 +1,82 @@
+// Extractor seam — turn a URL into clean, size-bounded markdown by calling
+// distilly's NETWORKED `urlToMarkdown` (the `distilly/fetch` entrypoint),
+// INJECTING webveil's egress-bound `fetch` as the only transport. distilly's
+// network Rules (github/mdn/react.dev/vuejs.org) rewrite a matching URL to its
+// raw `.md`/API source and fetch THAT over our egress — shorter, cleaner output;
+// non-matching URLs run through distilly's pure core. See docs/adr/0001.
+//
+// THE HARD INVARIANT (load-bearing for anonymity): webveil ALWAYS injects its
+// egress-bound `fetch` here and NEVER lets distilly use a global/default fetch.
+// distilly throws if none is injected — the desired fail-loud. And the egress
+// fetch itself throws (before any I/O) when a configured proxy is unbuildable
+// (egress.ts), so a broken proxy can never become an un-proxied request.
+//
+// This is the DEFAULT extractor; a backend's own `/extract` (tavily-compat) may
+// override it (wired in the core-fetch task).
+
+import {urlToMarkdown as distillyUrlToMarkdown} from 'distilly/fetch';
+import type {Config, FetchSize} from './config.js';
+import {createEgressFetch, type EgressFetch} from './egress.js';
+import type {FetchResult} from './backends/types.js';
+
+/** The shape distilly's `urlToMarkdown` returns (the bits we surface). */
+interface UrlToMarkdownResult {
+	markdown: string;
+	truncated: boolean;
+}
+
+/** distilly's networked entrypoint, narrowed to what the seam injects/uses. */
+type UrlToMarkdown = (
+	url: string | URL,
+	options: {fetch: EgressFetch; size?: FetchSize},
+) => Promise<UrlToMarkdownResult>;
+
+/** Per-call extractor options. */
+export interface ExtractOptions {
+	/**
+	 * Page-size budget for THIS call. Overrides the config's `fetchSize` when
+	 * given. webveil's `s`/`m`/`l`/`f` preset maps STRAIGHT to distilly's `size`
+	 * (the two enums are identical), so this is passed through verbatim.
+	 */
+	size?: FetchSize;
+}
+
+/**
+ * Seams the extractor's collaborators so it is testable WITHOUT real network or
+ * undici: tests inject a spy `urlToMarkdown` and/or a spy egress fetch to assert
+ * distilly is called with the egress fetch (never a global). Defaults wire the
+ * real `distilly/fetch` + `createEgressFetch`.
+ */
+export interface ExtractDeps {
+	/** distilly's networked `urlToMarkdown` (default: the real `distilly/fetch`). */
+	urlToMarkdown?: UrlToMarkdown;
+	/** Builds the egress-bound fetch from config (default: createEgressFetch). */
+	createEgressFetch?: (config: Config) => EgressFetch;
+}
+
+/**
+ * Extract a URL to clean, budget-bounded markdown via distilly over webveil's
+ * egress. Builds the egress-bound `fetch` (fail-loud on an unbuildable proxy),
+ * injects it into distilly's `urlToMarkdown`, maps the `s`/`m`/`l`/`f` preset to
+ * distilly's `size`, and surfaces distilly's `truncated`.
+ *
+ * @returns `{ url, markdown, truncated }` (a `FetchResult` without a `title`).
+ */
+export async function extract(
+	url: string,
+	config: Config,
+	options: ExtractOptions = {},
+	deps: ExtractDeps = {},
+): Promise<FetchResult> {
+	const urlToMarkdown = deps.urlToMarkdown ?? distillyUrlToMarkdown;
+	const buildFetch = deps.createEgressFetch ?? createEgressFetch;
+
+	// Build the egress-bound fetch FIRST: a configured-but-unbuildable proxy
+	// throws here, before any network access (never an un-proxied request).
+	const fetch = buildFetch(config);
+
+	const size = options.size ?? config.fetchSize;
+
+	const {markdown, truncated} = await urlToMarkdown(url, {fetch, size});
+	return {url, markdown, truncated};
+}

package/src/core/fetch.ts

@@ -0,0 +1,132 @@
+// core fetch: the plain, framework-agnostic `fetch()` BOTH frontends (the incur
+// CLI/MCP and the pi extension) call. Returns clean, size-bounded markdown with
+// distilly's `truncated` flag.
+//
+// Flow (per URL): pick the content source (a backend's own `/extract`
+// (tavily-compat) when the configured backend provides one, OTHERWISE the
+// default distilly Extractor seam, urlToMarkdown over webveil's egress). The
+// SSRF guard lives INSIDE the egress-bound fetch injected into distilly, so it
+// covers distilly's rule-rewritten requests too (docs/adr/0001).
+//
+// LIST-READY INTERNALS (story 12): the work happens in `fetchAll(urls, …)`, a
+// list-processing internal, so a future `web_batch_fetch` tool is a trivial add
+// with no redesign. The public `fetch()` is a thin single-URL wrapper over it.
+
+import {resolveConfig as defaultResolveConfig} from './config.js';
+import type {Config, ResolveOptions} from './config.js';
+import {createEgressFetch as defaultCreateEgressFetch} from './egress.js';
+import type {EgressFetch} from './egress.js';
+import {guardEgressFetch as defaultGuardEgressFetch} from './security.js';
+import {createHttp as defaultCreateHttp} from './http.js';
+import {buildDispatcher as defaultBuildDispatcher} from './egress.js';
+import type {Dispatcher} from './egress.js';
+import {extract as defaultExtract} from './extract.js';
+import type {ExtractDeps} from './extract.js';
+import {getBackend as defaultGetBackend} from './backends/registry.js';
+import type {
+	Backend,
+	FetchOptions,
+	FetchResult,
+	Http,
+} from './backends/types.js';
+
+/**
+ * Collaborators, seamed so the core is testable WITHOUT real config files,
+ * undici, network, or distilly: a test injects fakes to assert the
+ * backend-`/extract`-vs-distilly branch, the list path, and that the guarded
+ * egress fetch (never a global) is what reaches distilly. Defaults wire the real
+ * modules.
+ */
+export interface FetchDeps {
+	resolveConfig?: (options?: ResolveOptions) => Config;
+	getBackend?: (name: string, config: Config) => Backend;
+	buildDispatcher?: (config: Config) => Dispatcher | undefined;
+	createHttp?: (dispatcher: Dispatcher | undefined) => Http;
+	createEgressFetch?: (config: Config) => EgressFetch;
+	guardEgressFetch?: (fetch: EgressFetch, config: Config) => EgressFetch;
+	extract?: (
+		url: string,
+		config: Config,
+		options: {size?: Config['fetchSize']},
+		deps: ExtractDeps,
+	) => Promise<FetchResult>;
+}
+
+/** Per-call fetch options plus the config-resolution knobs (cwd/env/global). */
+export interface FetchCoreOptions extends FetchOptions, ResolveOptions {}
+
+/**
+ * Fetch a LIST of urls to clean, size-bounded markdown, in order. This is the
+ * list-ready internal (story 12): the single-URL `fetch()` below is a thin
+ * wrapper over it, so a future `web_batch_fetch` reuses this directly.
+ *
+ * Each url goes through the SAME content-source choice: a backend's own
+ * `/extract` (if the configured backend implements `fetch`) OR the default
+ * distilly Extractor with the GUARDED egress fetch injected.
+ */
+export async function fetchAll(
+	urls: string[],
+	options: FetchCoreOptions = {},
+	deps: FetchDeps = {},
+): Promise<FetchResult[]> {
+	const resolveConfig = deps.resolveConfig ?? defaultResolveConfig;
+	const getBackend = deps.getBackend ?? defaultGetBackend;
+	const buildDispatcher = deps.buildDispatcher ?? defaultBuildDispatcher;
+	const createHttp = deps.createHttp ?? defaultCreateHttp;
+	const createEgressFetch = deps.createEgressFetch ?? defaultCreateEgressFetch;
+	const guardEgressFetch = deps.guardEgressFetch ?? defaultGuardEgressFetch;
+	const extract = deps.extract ?? defaultExtract;
+
+	const config = resolveConfig({
+		cwd: options.cwd,
+		env: options.env,
+		globalPath: options.globalPath,
+	});
+
+	const backend = getBackend(config.backend, config);
+
+	// A backend that provides its own `/extract` (tavily-compat) OVERRIDES the
+	// distilly Extractor; it is handed only the proxied http helper (built from
+	// the SAME dispatcher as the egress fetch), so it cannot bypass egress.
+	if (backend.fetch) {
+		const http = createHttp(buildDispatcher(config));
+		const backendFetch = backend.fetch.bind(backend);
+		return runAll(urls, (url) =>
+			backendFetch(url, http, {size: options.size, signal: options.signal}),
+		);
+	}
+
+	// Default path: distilly Extractor over webveil's egress. Build the
+	// egress-bound fetch ONCE, wrap it with the SSRF guard, and inject THAT into
+	// distilly (never a global fetch). The guard covers distilly's rule-rewritten
+	// requests too. A configured-but-unbuildable proxy throws at build time
+	// (fail-loud), before any I/O.
+	const guardedFetch = guardEgressFetch(createEgressFetch(config), config);
+	const extractDeps: ExtractDeps = {createEgressFetch: () => guardedFetch};
+	return runAll(urls, (url) =>
+		extract(url, config, {size: options.size}, extractDeps),
+	);
+}
+
+/** Run a per-url worker over the list in order, collecting the results. */
+async function runAll(
+	urls: string[],
+	work: (url: string) => Promise<FetchResult>,
+): Promise<FetchResult[]> {
+	const out: FetchResult[] = [];
+	for (const url of urls) out.push(await work(url));
+	return out;
+}
+
+/**
+ * Fetch ONE url to clean, size-bounded markdown (`{ markdown, truncated, … }`).
+ * A thin single-URL wrapper over the list-ready `fetchAll` (story 12).
+ */
+export async function fetch(
+	url: string,
+	options: FetchCoreOptions = {},
+	deps: FetchDeps = {},
+): Promise<FetchResult> {
+	const [result] = await fetchAll([url], options, deps);
+	return result!;
+}

package/src/core/http.ts

@@ -0,0 +1,62 @@
+// http helper — the proxied `http` handed to backends. fetchJson / fetchText
+// apply the egress dispatcher + a per-request timeout + abort. Distinct from the
+// egress-bound WHATWG `fetch` (egress.ts), but bound to the SAME dispatcher, so
+// a backend physically cannot bypass the configured egress.
+
+import {type Dispatcher, fetch as undiciFetch} from 'undici';
+import type {Http, HttpRequestOptions} from './backends/types.js';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+async function request(
+	dispatcher: Dispatcher | undefined,
+	url: string,
+	options: HttpRequestOptions = {},
+): Promise<Response> {
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	if (options.signal)
+		options.signal.addEventListener('abort', () => controller.abort(), {
+			once: true,
+		});
+	try {
+		const res = await undiciFetch(url, {
+			method: options.method,
+			headers: options.headers,
+			body: options.body,
+			signal: controller.signal,
+			dispatcher,
+		} as never);
+		return res as unknown as Response;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/**
+ * Build the proxied http helper over a given dispatcher. Both methods throw on a
+ * non-2xx response so a backend never silently consumes an error body.
+ */
+export function createHttp(dispatcher: Dispatcher | undefined): Http {
+	return {
+		async fetchJson<T = unknown>(
+			url: string,
+			options?: HttpRequestOptions,
+		): Promise<T> {
+			const res = await request(dispatcher, url, options);
+			if (!res.ok)
+				throw new Error(`http ${res.status} ${res.statusText} for ${url}`);
+			return (await res.json()) as T;
+		},
+		async fetchText(
+			url: string,
+			options?: HttpRequestOptions,
+		): Promise<string> {
+			const res = await request(dispatcher, url, options);
+			if (!res.ok)
+				throw new Error(`http ${res.status} ${res.statusText} for ${url}`);
+			return await res.text();
+		},
+	};
+}

package/src/core/search.ts

@@ -0,0 +1,104 @@
+// core search — the plain, framework-agnostic `search()` BOTH frontends (the
+// incur CLI/MCP and the pi extension) call. It owns the wiring and the
+// caller-facing post-processing; the per-source parsing lives in the backend.
+//
+// Flow: resolve config → build the egress dispatcher → bind the proxied `http`
+// helper to it → select the backend from the registry → call the backend with
+// ONLY that proxied helper → normalize (dedup + clamp) the SearchResult[].
+//
+// The egress invariant (docs/adr/0001): the backend is handed only the
+// dispatcher-bound `http` helper, so it physically cannot reach a global fetch
+// and bypass the configured egress. A configured-but-unbuildable proxy throws at
+// buildDispatcher (fail-loud), never silently un-proxied.
+
+import {resolveConfig as defaultResolveConfig} from './config.js';
+import type {Config, ResolveOptions} from './config.js';
+import {buildDispatcher as defaultBuildDispatcher} from './egress.js';
+import type {Dispatcher} from './egress.js';
+import {createHttp as defaultCreateHttp} from './http.js';
+import {getBackend as defaultGetBackend} from './backends/registry.js';
+import type {Http, SearchOptions, SearchResult} from './backends/types.js';
+
+/**
+ * Default cap on returned results when the caller does not pass `maxResults`.
+ * Keeps an agent's context small by default; a caller can raise/lower it per
+ * call. (Recorded decision: there is no configured default, so the core sets
+ * one; see the task's Decisions block.)
+ */
+const DEFAULT_MAX_RESULTS = 10;
+
+/**
+ * Collaborators, seamed so the core is testable WITHOUT real config files,
+ * undici, or network: a test injects a fake `getBackend`/`createHttp` to assert
+ * the backend is handed only the proxied helper, and a fake backend returning
+ * duplicate/over-limit hits to assert dedup + clamp. Defaults wire the real
+ * config/egress/http/registry modules.
+ */
+export interface SearchDeps {
+	resolveConfig?: (options?: ResolveOptions) => Config;
+	buildDispatcher?: (config: Config) => Dispatcher | undefined;
+	createHttp?: (dispatcher: Dispatcher | undefined) => Http;
+	getBackend?: (
+		name: string,
+		config: Config,
+	) => {
+		search: (
+			query: string,
+			http: Http,
+			options?: SearchOptions,
+		) => Promise<SearchResult[]>;
+	};
+}
+
+/** Per-call search options plus the config-resolution knobs (cwd/env/global). */
+export interface SearchCoreOptions extends SearchOptions, ResolveOptions {}
+
+/** Dedup by url (the hit's identity), preserving first-seen order. */
+function dedup(results: SearchResult[]): SearchResult[] {
+	const seen = new Set<string>();
+	const out: SearchResult[] = [];
+	for (const r of results) {
+		if (seen.has(r.url)) continue;
+		seen.add(r.url);
+		out.push(r);
+	}
+	return out;
+}
+
+/**
+ * Search the configured backend over the configured egress and return
+ * normalized `SearchResult[]` (deduped by url, then clamped to `maxResults`).
+ *
+ * Dedup runs BEFORE the clamp so the caller gets up to `maxResults` UNIQUE hits,
+ * not a window that duplicates eat into; for the same reason the backend is NOT
+ * asked to pre-clamp (only the abort signal is forwarded).
+ */
+export async function search(
+	query: string,
+	options: SearchCoreOptions = {},
+	deps: SearchDeps = {},
+): Promise<SearchResult[]> {
+	const resolveConfig = deps.resolveConfig ?? defaultResolveConfig;
+	const buildDispatcher = deps.buildDispatcher ?? defaultBuildDispatcher;
+	const createHttp = deps.createHttp ?? defaultCreateHttp;
+	const getBackend = deps.getBackend ?? defaultGetBackend;
+
+	const config = resolveConfig({
+		cwd: options.cwd,
+		env: options.env,
+		globalPath: options.globalPath,
+	});
+
+	// Build the dispatcher FIRST: a configured-but-unbuildable proxy throws here,
+	// before any network access (never an un-proxied request).
+	const dispatcher = buildDispatcher(config);
+	const http = createHttp(dispatcher);
+
+	const backend = getBackend(config.backend, config);
+	// Hand the backend ONLY the proxied helper (no maxResults: dedup happens
+	// here, over the full set, so the clamp below is over UNIQUE results).
+	const raw = await backend.search(query, http, {signal: options.signal});
+
+	const maxResults = options.maxResults ?? DEFAULT_MAX_RESULTS;
+	return dedup(raw).slice(0, maxResults);
+}

package/src/core/security.ts

@@ -0,0 +1,141 @@
+// SSRF guard: the security seam wrapped AROUND the egress-bound `fetch`, so it
+// covers BOTH webveil's own GETs AND distilly's rule-rewritten requests (see
+// docs/adr/0001: the guard lives inside the egress fetch). Adapts the range
+// classification + DNS-resolve approach of leing2021/pi-search's `security.ts`.
+//
+// THE RELAXATION RULE (load-bearing, recorded in the task's Decisions): the
+// guard BLOCKS private/loopback/link-local/etc. addresses on DIRECT egress, and
+// RELAXES ENTIRELY under a proxy egress (`http` | `socks5`). Tor/Mullvad
+// legitimately reach private-looking addresses (e.g. `10.64.0.1`), AND a local
+// DNS lookup for a proxied request would itself be a deanonymizing leak, so
+// under a proxy we neither block nor resolve locally; the proxy owns egress.
+
+import {lookup} from 'node:dns/promises';
+import {isIP} from 'node:net';
+import type {Config} from './config.js';
+import type {EgressFetch} from './egress.js';
+
+/** Thrown when the SSRF guard refuses a request to a private/blocked address. */
+export class SsrfError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'SsrfError';
+	}
+}
+
+/** A proxy egress owns egress + DNS, so the local SSRF guard relaxes for it. */
+function egressIsProxy(config: Config): boolean {
+	return config.egress.mode === 'http' || config.egress.mode === 'socks5';
+}
+
+/**
+ * Is this LITERAL IP private / non-public? Covers the ranges that must never be
+ * reachable from a direct-egress web fetch:
+ *   IPv4: 0.0.0.0/8, 10/8 (RFC1918), 127/8 (loopback), 169.254/16 (link-local,
+ *     incl. the 169.254.169.254 cloud metadata endpoint), 172.16/12 (RFC1918),
+ *     192.168/16 (RFC1918), 100.64/10 (CGNAT), 192.0.0/24, 192.0.2/24,
+ *     198.18/15, 198.51.100/24, 203.0.113/24, 224/4 (multicast), 240/4
+ *     (reserved).
+ *   IPv6: ::1 (loopback), :: (unspecified), fc00::/7 (ULA), fe80::/10
+ *     (link-local), ff00::/8 (multicast), plus IPv4-mapped (::ffff:a.b.c.d,
+ *     re-checked as IPv4). Default-deny: anything outside global unicast
+ *     (2000::/3) is treated as non-public.
+ */
+export function isPrivateIp(ip: string): boolean {
+	const kind = isIP(ip);
+	if (kind === 4) return isPrivateIpv4(ip);
+	if (kind === 6) return isPrivateIpv6(ip);
+	return false; // not a literal IP; hostname handling resolves it first
+}
+
+function isPrivateIpv4(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; // malformed → treat as non-public (fail closed)
+	const [a, b] = parts as [number, number, number, number];
+	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; // 172.16/12
+	if (a === 192 && b === 168) return true; // 192.168/16
+	if (a === 100 && b >= 64 && b <= 127) return true; // 100.64/10 CGNAT
+	if (a === 192 && b === 0) return true; // 192.0.0/24 + 192.0.2/24
+	if (a === 198 && (b === 18 || b === 19)) return true; // 198.18/15 benchmark
+	if (a === 198 && b === 51) return true; // 198.51.100/24 TEST-NET-2
+	if (a === 203 && b === 0) return true; // 203.0.113/24 TEST-NET-3
+	if (a >= 224) return true; // 224/4 multicast + 240/4 reserved
+	return false;
+}
+
+function isPrivateIpv6(ip: string): boolean {
+	const lower = ip.toLowerCase();
+	if (lower === '::1' || lower === '::') return true; // loopback / unspecified
+	// IPv4-mapped (::ffff:a.b.c.d): re-check the embedded IPv4.
+	const mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+	if (mapped) return isPrivateIpv4(mapped[1]!);
+	const head = lower.split(':')[0] ?? '';
+	const first = parseInt(head || '0', 16);
+	if (Number.isNaN(first)) return true; // fail closed on anything unparseable
+	if ((first & 0xfe00) === 0xfc00) return true; // fc00::/7 ULA
+	if ((first & 0xffc0) === 0xfe80) return true; // fe80::/10 link-local
+	if ((first & 0xff00) === 0xff00) return true; // ff00::/8 multicast
+	// Default-deny: only global unicast 2000::/3 is public.
+	return (first & 0xe000) !== 0x2000;
+}
+
+/**
+ * Assert a URL is safe to fetch under THIS config's egress. Under a proxy egress
+ * it always passes (the proxy owns egress + DNS). Under direct egress it rejects
+ * a literal private IP and, for a hostname, resolves it locally and rejects if it
+ * maps to a private IP (so a name pointing at 127.0.0.1 / metadata is caught).
+ */
+export async function assertPublicUrl(
+	url: string,
+	config: Config,
+): Promise<void> {
+	if (egressIsProxy(config)) return; // proxy owns egress + DNS; relax entirely
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new SsrfError(`webveil SSRF: malformed url ${url}`);
+	}
+	const host = parsed.hostname.replace(/^\[|\]$/g, ''); // strip IPv6 brackets
+	if (isIP(host)) {
+		if (isPrivateIp(host))
+			throw new SsrfError(`webveil SSRF: blocked private address ${host}`);
+		return;
+	}
+	// A hostname: resolve it locally (safe on direct egress) and check every
+	// address it maps to, so a name pointing at a private IP is also blocked.
+	const addrs = await lookup(host, {all: true});
+	for (const {address} of addrs)
+		if (isPrivateIp(address))
+			throw new SsrfError(
+				`webveil SSRF: ${host} resolves to private address ${address}`,
+			);
+}
+
+/**
+ * Wrap an egress-bound `fetch` with the SSRF guard. The returned fetch checks
+ * EVERY request URL (so it covers distilly's rule-rewritten requests too, not
+ * only webveil's own GET) before delegating to the underlying egress fetch.
+ * This is what `core.fetch()` injects into distilly. See docs/adr/0001.
+ */
+export function guardEgressFetch(
+	fetch: EgressFetch,
+	config: Config,
+): EgressFetch {
+	return (async (input: RequestInfo | URL, init?: RequestInit) => {
+		const url =
+			typeof input === 'string'
+				? input
+				: input instanceof URL
+					? input.href
+					: input.url;
+		await assertPublicUrl(url, config);
+		return fetch(input as never, init as never);
+	}) as EgressFetch;
+}