@demigodmode/pi-web-agent 1.10.0 → 1.12.0

package/dist/fetch/headless-fetch.js

@@ -1,13 +1,52 @@
 import { chromium } from 'playwright';
 import { extractReadableContentSafely } from '../extract/readability.js';
 import { resolveBrowserExecutable } from './browser-resolution.js';
+import { BLOCKED_HEADER } from './guard-proxy.js';
+import { BLOCKED_PRIVATE_ADDRESS, BlockedAddressError, UPSTREAM_PROXY_REFUSED } from './network-guard.js';
 function cleanupRenderedText(text) {
     let cleaned = text.replace(/(Show more)(\s+\1){1,}/gi, '$1');
     cleaned = cleaned.replace(/(Privacy Terms)(\s+\1){1,}/gi, '$1');
     cleaned = cleaned.replace(/\s+/g, ' ').trim();
     return cleaned;
 }
-export async function headlessFetch(url, { configuredPath, resolveBrowser = (options) => resolveBrowserExecutable({ configuredPath: options?.configuredPath }), launchBrowser = ({ executablePath, headless }) => chromium.launch(executablePath ? { executablePath, headless } : { headless }), now = () => Date.now() } = {}) {
+function errorResult(url, code, message) {
+    const guard = code === BLOCKED_PRIVATE_ADDRESS || code === UPSTREAM_PROXY_REFUSED;
+    return {
+        status: 'error',
+        url,
+        metadata: { method: 'headless', cacheHit: false },
+        error: { code, message, ...(guard ? { failure: { kind: 'guard_refused' } } : {}) }
+    };
+}
+function hostnameOf(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Same normalization the guard applies, so refusal hosts and navigation hosts compare equal. */
+function normalizeHost(host) {
+    return host.replace(/^\[|\]$/g, '').toLowerCase().replace(/\.+$/, '');
+}
+export async function headlessFetch(url, { configuredPath, proxy, guard, guardProxy, resolveBrowser = (options) => resolveBrowserExecutable({ configuredPath: options?.configuredPath }), launchBrowser = ({ executablePath, headless, proxy }) => chromium.launch(executablePath ? { executablePath, headless, ...(proxy ? { proxy } : {}) } : { headless, ...(proxy ? { proxy } : {}) }), now = () => Date.now() } = {}) {
+    if (guard) {
+        const hostname = hostnameOf(url);
+        if (!guardProxy) {
+            // Enforcement lives in the guard proxy. Without it, loading the page would be unguarded.
+            return errorResult(url, BLOCKED_PRIVATE_ADDRESS, `Blocked ${hostname ?? url}: the browser could not enforce the private address guard.`);
+        }
+        if (hostname) {
+            // Early, clearer refusal for an obviously blocked main url. The guard
+            // proxy is what actually enforces the policy for every connection.
+            const verdict = await guard.checkHost(hostname);
+            if (!verdict.allowed) {
+                const error = new BlockedAddressError(verdict.host, verdict.address);
+                return errorResult(url, error.code, error.message);
+            }
+        }
+    }
     const resolved = await resolveBrowser({ configuredPath });
     if (!resolved.ok && resolved.error.code === 'CONFIGURED_BROWSER_NOT_FOUND') {
         return {
@@ -17,23 +56,149 @@ export async function headlessFetch(url, { configuredPath, resolveBrowser = (opt
             error: resolved.error
         };
     }
+    let enforcement;
+    if (guard && guardProxy) {
+        let activeProxy;
+        try {
+            activeProxy = await guardProxy();
+        }
+        catch {
+            // The guard proxy could not start (backend set closed, or the listener
+            // failed). Enforcement lives there, so the browser must not launch.
+            return errorResult(url, BLOCKED_PRIVATE_ADDRESS, `Blocked ${hostnameOf(url) ?? url}: the private address guard is not available, so the browser was not started.`);
+        }
+        const client = activeProxy.client('headless');
+        enforcement = {
+            proxy: activeProxy,
+            username: client.username,
+            since: activeProxy.sequence(),
+            // `<-loopback>` removes Chromium's implicit loopback bypass, so localhost
+            // and link-local connections go through the guard proxy too.
+            launchProxy: { server: client.server, username: client.username, password: client.password, bypass: '<-loopback>' }
+        };
+    }
+    const effectiveProxy = enforcement ? enforcement.launchProxy : proxy;
     const browserName = resolved.ok ? resolved.browser : 'chromium';
     const launchOptions = resolved.ok
-        ? { executablePath: resolved.executablePath, headless: true }
-        : { headless: true };
+        ? { executablePath: resolved.executablePath, headless: true, ...(effectiveProxy ? { proxy: effectiveProxy } : {}) }
+        : { headless: true, ...(effectiveProxy ? { proxy: effectiveProxy } : {}) };
+    // Browser requests that failed or were refused by the proxy, from passive
+    // page events only. Navigation hosts decide whether a refusal caused the
+    // navigation error; subresource failures are counted one per request.
+    const failedNavigationHosts = new Set();
+    const failedSubresourceHosts = [];
+    const seenRequests = new WeakSet();
+    const refusals = () => (enforcement ? enforcement.proxy.refusalsSince(enforcement.username, enforcement.since) : []);
+    const navigationRefusal = () => refusals().find((entry) => failedNavigationHosts.has(entry.host));
+    const subresourceRefusals = () => {
+        const refusedHosts = new Set(refusals().map((entry) => entry.host));
+        return failedSubresourceHosts.filter((host) => refusedHosts.has(host)).length;
+    };
     let browser;
     let context;
     let page;
     try {
         browser = await launchBrowser(launchOptions);
-        context = await browser.newContext();
-        page = await context.newPage();
+        // Service workers can fetch on a page's behalf; blocking them keeps the page's traffic simple to account for.
+        context = await browser.newContext(enforcement ? { serviceWorkers: 'block' } : undefined);
+        if (enforcement) {
+            // Watch every page in the context: popups opened by the page can hit blocked
+            // hosts too. Only the primary page's main-frame navigation is "the navigation".
+            let primaryPage;
+            const recordRequest = (request) => {
+                try {
+                    if (!request || seenRequests.has(request))
+                        return;
+                    seenRequests.add(request);
+                    const host = normalizeHost(new URL(request.url()).hostname);
+                    if (primaryPage && request.isNavigationRequest() && request.frame() === primaryPage.mainFrame()) {
+                        failedNavigationHosts.add(host);
+                    }
+                    else {
+                        failedSubresourceHosts.push(host);
+                    }
+                }
+                catch {
+                    // Unparseable URL or a detached frame: nothing to attribute.
+                }
+            };
+            const watchPage = (watched) => {
+                watched?.on?.('requestfailed', recordRequest);
+                watched?.on?.('response', (response) => {
+                    try {
+                        if (response.headers()[BLOCKED_HEADER])
+                            recordRequest(response.request());
+                    }
+                    catch {
+                        // ignore
+                    }
+                });
+                // Best effort: Playwright doesn't say why a WebSocket died, so an error or a
+                // close before any frame counts as failed. Only refused hosts get counted.
+                watched?.on?.('websocket', (ws) => {
+                    let host;
+                    try {
+                        host = normalizeHost(new URL(ws.url()).hostname);
+                    }
+                    catch {
+                        return;
+                    }
+                    let framed = false;
+                    let recorded = false;
+                    const fail = () => {
+                        if (recorded)
+                            return;
+                        recorded = true;
+                        failedSubresourceHosts.push(host);
+                    };
+                    ws.on?.('framereceived', () => (framed = true));
+                    ws.on?.('framesent', () => (framed = true));
+                    ws.on?.('socketerror', fail);
+                    ws.on?.('close', () => {
+                        if (!framed)
+                            fail();
+                    });
+                });
+            };
+            const watchedPages = new WeakSet();
+            const watchOnce = (candidate) => {
+                if (!candidate || watchedPages.has(candidate))
+                    return;
+                watchedPages.add(candidate);
+                watchPage(candidate);
+            };
+            // Registered before newPage(), so the primary page's own 'page' event is covered too.
+            context.on?.('page', watchOnce);
+            page = await context.newPage();
+            primaryPage = page;
+            watchOnce(page);
+        }
+        else {
+            page = await context.newPage();
+        }
         const startedAt = now();
-        await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 20000 });
+        const response = await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 20000 });
+        if (enforcement && response?.headers?.()[BLOCKED_HEADER]) {
+            // Normally already recorded by the 'response' event; this covers it if not.
+            try {
+                const request = response.request?.();
+                if (request && !seenRequests.has(request)) {
+                    seenRequests.add(request);
+                    failedNavigationHosts.add(normalizeHost(new URL(request.url()).hostname));
+                }
+            }
+            catch {
+                // ignore
+            }
+            const cause = navigationRefusal();
+            if (cause)
+                return errorResult(url, cause.error.code, cause.error.message);
+        }
         await page.waitForLoadState('load', { timeout: 10000 });
         await page.waitForLoadState('networkidle', { timeout: 5000 }).catch(() => undefined);
         const html = await page.content();
         const finishedAt = now();
+        const blockedSubresources = subresourceRefusals();
         const extraction = extractReadableContentSafely(html);
         const cleanedContent = {
             ...extraction.content,
@@ -47,7 +212,8 @@ export async function headlessFetch(url, { configuredPath, resolveBrowser = (opt
                     method: 'headless',
                     cacheHit: false,
                     browser: browserName,
-                    navigationMs: finishedAt - startedAt
+                    navigationMs: finishedAt - startedAt,
+                    ...(blockedSubresources > 0 ? { blockedSubresources } : {})
                 },
                 error: {
                     code: 'HEADLESS_EXTRACTION_WEAK',
@@ -64,18 +230,24 @@ export async function headlessFetch(url, { configuredPath, resolveBrowser = (opt
                 cacheHit: false,
                 browser: browserName,
                 navigationMs: finishedAt - startedAt,
-                truncated: cleanedContent.text.length >= 4000
+                truncated: cleanedContent.text.length >= 4000,
+                ...(blockedSubresources > 0 ? { blockedSubresources } : {})
             }
         };
     }
     catch (error) {
+        const cause = navigationRefusal();
+        if (cause)
+            return errorResult(url, cause.error.code, cause.error.message);
+        const blockedSubresources = subresourceRefusals();
         return {
             status: 'error',
             url,
             metadata: {
                 method: 'headless',
                 cacheHit: false,
-                browser: browserName
+                browser: browserName,
+                ...(blockedSubresources > 0 ? { blockedSubresources } : {})
             },
             error: {
                 code: 'HEADLESS_NAVIGATION_FAILED',

package/dist/fetch/http-fetch.js

@@ -1,4 +1,5 @@
 import { extractReadableContentSafely } from '../extract/readability.js';
+import { findGuardError } from './network-guard.js';
 function looksLikeScriptShell(html) {
     const lower = html.toLowerCase();
     return lower.includes('<script') && (lower.includes('id="app"') || lower.includes('id="root"'));
@@ -15,7 +16,21 @@ function isWeakHttpContent(options) {
 }
 export function createHttpFetcher({ fetchImpl = fetch } = {}) {
     return async function httpFetch(url) {
-        const response = await fetchImpl(url);
+        let response;
+        try {
+            response = await fetchImpl(url);
+        }
+        catch (error) {
+            const blocked = findGuardError(error);
+            if (!blocked)
+                throw error;
+            return {
+                status: 'error',
+                url,
+                metadata: { method: 'http', cacheHit: false },
+                error: { code: blocked.code, message: blocked.message, failure: { kind: 'guard_refused' } }
+            };
+        }
         const contentType = response.headers.get('content-type') ?? '';
         if (!contentType.includes('text/html')) {
             return {

package/dist/fetch/network-guard.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Decides whether a destination the *model* chose is safe to fetch (#53).
+ *
+ * web_explore fetches URLs the model picks, partly from pages it just read, so
+ * a hostile page can point it at cloud metadata (169.254.169.254), services on
+ * localhost, or the user's LAN. This module only answers "is this address
+ * allowed"; guarded-fetch.ts and headless-fetch.ts enforce it. User-configured
+ * endpoints (search APIs, SearXNG, Firecrawl, the proxy) never go through it.
+ */
+export type Cidr = {
+    family: 4 | 6;
+    network: bigint;
+    prefix: number;
+};
+export type LookupFn = (host: string) => Promise<Array<{
+    address: string;
+    family: number;
+}>>;
+export type NetworkGuardConfig = {
+    allowRanges?: string[];
+};
+export type GuardVerdict = {
+    allowed: true;
+    unresolved?: true;
+} | {
+    allowed: false;
+    host: string;
+    address: string;
+};
+export type HostResolution = {
+    status: 'allowed';
+    host: string;
+    addresses: string[];
+} | {
+    status: 'blocked';
+    host: string;
+    address: string;
+} | {
+    status: 'unresolved';
+    host: string;
+};
+export type NetworkGuard = {
+    isBlockedAddress(address: string): boolean;
+    /** Resolves once and checks every answer. The guard proxy connects to one of `addresses`, never re-resolving. */
+    resolveHost(host: string): Promise<HostResolution>;
+    checkHost(host: string): Promise<GuardVerdict>;
+    assertUrlAllowed(url: string): Promise<void>;
+};
+export declare const BLOCKED_PRIVATE_ADDRESS = "BLOCKED_PRIVATE_ADDRESS";
+export declare class BlockedAddressError extends Error {
+    readonly host: string;
+    readonly address: string;
+    readonly code = "BLOCKED_PRIVATE_ADDRESS";
+    constructor(host: string, address: string);
+}
+/** No address could be verified, so we refuse rather than let something else resolve it. */
+export declare class UnverifiedDestinationError extends Error {
+    readonly host: string;
+    readonly code = "BLOCKED_PRIVATE_ADDRESS";
+    constructor(host: string);
+}
+export declare const UPSTREAM_PROXY_REFUSED = "UPSTREAM_PROXY_REFUSED";
+/** The user's upstream proxy would not accept the approved IP. We never retry by hostname. */
+export declare class UpstreamProxyRefusedError extends Error {
+    readonly host: string;
+    readonly target: string;
+    readonly status: number | string;
+    readonly code = "UPSTREAM_PROXY_REFUSED";
+    constructor(host: string, target: string, status: number | string);
+}
+export type GuardError = BlockedAddressError | UnverifiedDestinationError | UpstreamProxyRefusedError;
+export declare function findGuardError(error: unknown): GuardError | undefined;
+/** undici wraps connect errors as `TypeError: fetch failed` with the real error in `cause`. */
+export declare function findBlockedAddressError(error: unknown): BlockedAddressError | undefined;
+export declare function parseCidr(text: string): Cidr | undefined;
+/** Parses an allow list, dropping invalid entries and anything that allows every address. */
+export declare function usableAllowRanges(allowRanges?: string[]): Cidr[];
+export declare function createNetworkGuard(config?: NetworkGuardConfig, { lookup, lookupTimeoutMs }?: {
+    lookup?: LookupFn;
+    /** A lookup that hasn't answered by then counts as unresolved, so no caller waits on DNS forever. */
+    lookupTimeoutMs?: number;
+}): NetworkGuard;

package/dist/fetch/network-guard.js

@@ -0,0 +1,275 @@
+import { lookup as dnsLookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+export const BLOCKED_PRIVATE_ADDRESS = 'BLOCKED_PRIVATE_ADDRESS';
+export class BlockedAddressError extends Error {
+    host;
+    address;
+    code = BLOCKED_PRIVATE_ADDRESS;
+    constructor(host, address) {
+        super(`Blocked ${host}: resolves to private address ${address}. ` +
+            'Add it to backends.network.allowRanges if this is intended.');
+        this.host = host;
+        this.address = address;
+        this.name = 'BlockedAddressError';
+    }
+}
+/** No address could be verified, so we refuse rather than let something else resolve it. */
+export class UnverifiedDestinationError extends Error {
+    host;
+    code = BLOCKED_PRIVATE_ADDRESS;
+    constructor(host) {
+        super(`Blocked ${host}: could not verify its address before connecting.`);
+        this.host = host;
+        this.name = 'UnverifiedDestinationError';
+    }
+}
+export const UPSTREAM_PROXY_REFUSED = 'UPSTREAM_PROXY_REFUSED';
+/** The user's upstream proxy would not accept the approved IP. We never retry by hostname. */
+export class UpstreamProxyRefusedError extends Error {
+    host;
+    target;
+    status;
+    code = UPSTREAM_PROXY_REFUSED;
+    constructor(host, target, status) {
+        super(`Upstream proxy refused ${target} for ${host} (HTTP ${status}). ` +
+            'If it only accepts hostnames, set backends.network.trustProxyDns to trust it to enforce private-address restrictions.');
+        this.host = host;
+        this.target = target;
+        this.status = status;
+        this.name = 'UpstreamProxyRefusedError';
+    }
+}
+export function findGuardError(error) {
+    let current = error;
+    for (let depth = 0; depth < 5 && current; depth += 1) {
+        if (current instanceof BlockedAddressError ||
+            current instanceof UnverifiedDestinationError ||
+            current instanceof UpstreamProxyRefusedError) {
+            return current;
+        }
+        current = current.cause;
+    }
+    return undefined;
+}
+/** undici wraps connect errors as `TypeError: fetch failed` with the real error in `cause`. */
+export function findBlockedAddressError(error) {
+    let current = error;
+    for (let depth = 0; depth < 5 && current; depth += 1) {
+        if (current instanceof BlockedAddressError)
+            return current;
+        current = current.cause;
+    }
+    return undefined;
+}
+const IPV4_WIDTH = 32;
+const IPV6_WIDTH = 128;
+function ipv4ToBigInt(address) {
+    const parts = address.split('.');
+    if (parts.length !== 4)
+        return undefined;
+    let value = 0n;
+    for (const part of parts) {
+        if (!/^\d{1,3}$/.test(part))
+            return undefined;
+        const octet = Number(part);
+        if (octet > 255)
+            return undefined;
+        value = (value << 8n) | BigInt(octet);
+    }
+    return value;
+}
+function ipv6ToBigInt(address) {
+    let text = address.split('%')[0];
+    // Embedded IPv4 tail, e.g. ::ffff:127.0.0.1
+    if (text.includes('.')) {
+        const lastColon = text.lastIndexOf(':');
+        const v4 = ipv4ToBigInt(text.slice(lastColon + 1));
+        if (v4 === undefined)
+            return undefined;
+        const high = ((v4 >> 16n) & 0xffffn).toString(16);
+        const low = (v4 & 0xffffn).toString(16);
+        text = `${text.slice(0, lastColon + 1)}${high}:${low}`;
+    }
+    const halves = text.split('::');
+    if (halves.length > 2)
+        return undefined;
+    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 && missing !== 0)
+        return undefined;
+    if (halves.length === 2 && missing < 1)
+        return undefined;
+    const groups = [...head, ...new Array(halves.length === 2 ? missing : 0).fill('0'), ...tail];
+    let value = 0n;
+    for (const group of groups) {
+        if (!/^[0-9a-f]{1,4}$/i.test(group))
+            return undefined;
+        value = (value << 16n) | BigInt(parseInt(group, 16));
+    }
+    return value;
+}
+const NAT64_WELL_KNOWN_NET = ipv6ToBigInt('64:ff9b::') >> 32n;
+const NAT64_LOCAL_NET = ipv6ToBigInt('64:ff9b:1::') >> 80n;
+const SIXTOFOUR_NET = ipv6ToBigInt('2002::') >> 112n;
+function parseAddress(address) {
+    const family = isIP(address.split('%')[0]);
+    if (family === 4) {
+        const value = ipv4ToBigInt(address);
+        return value === undefined ? undefined : { family: 4, value };
+    }
+    if (family === 6) {
+        const value = ipv6ToBigInt(address);
+        if (value === undefined)
+            return undefined;
+        // IPv4-mapped (::ffff:a.b.c.d): judge it as the IPv4 address it really is.
+        if (value >> 32n === 0xffffn)
+            return { family: 4, value: value & 0xffffffffn };
+        // IPv4-compatible (deprecated ::a.b.c.d), but not the special addresses :: and ::1.
+        if (value >> 32n === 0n && value > 1n)
+            return { family: 4, value };
+        // NAT64 (64:ff9b::/96 well-known, 64:ff9b:1::/48 local-use): IPv4 is the low 32 bits.
+        // DNS64 networks translate every IPv4-only host into these prefixes, so we cannot
+        // block the prefix outright -- judge the embedded address on its own merits instead.
+        if (value >> 32n === NAT64_WELL_KNOWN_NET)
+            return { family: 4, value: value & 0xffffffffn };
+        // Local-use NAT64 lets the operator pick a prefix shorter than /96; only the /96
+        // case has the IPv4 address in the low 32 bits, so only unwrap when bits 48-95
+        // (between the /48 prefix and the embedded address) are all zero.
+        if (value >> 80n === NAT64_LOCAL_NET && ((value >> 32n) & 0xffffffffffffn) === 0n) {
+            return { family: 4, value: value & 0xffffffffn };
+        }
+        // 6to4 (2002::/16): IPv4 is bits 16-48 from the top.
+        if (value >> 112n === SIXTOFOUR_NET)
+            return { family: 4, value: (value >> 80n) & 0xffffffffn };
+        return { family: 6, value };
+    }
+    return undefined;
+}
+export function parseCidr(text) {
+    const trimmed = text.trim();
+    const slash = trimmed.indexOf('/');
+    if (slash <= 0)
+        return undefined;
+    const prefixText = trimmed.slice(slash + 1);
+    if (!/^\d{1,3}$/.test(prefixText))
+        return undefined;
+    const prefix = Number(prefixText);
+    const address = parseAddress(trimmed.slice(0, slash));
+    if (!address)
+        return undefined;
+    // A mapped IPv6 CIDR would be ambiguous; require the plain family.
+    const family = isIP(trimmed.slice(0, slash));
+    const width = family === 4 ? IPV4_WIDTH : IPV6_WIDTH;
+    if (prefix > width)
+        return undefined;
+    const value = family === 4 ? ipv4ToBigInt(trimmed.slice(0, slash)) : ipv6ToBigInt(trimmed.slice(0, slash));
+    const shift = BigInt(width - prefix);
+    return { family, network: (value >> shift) << shift, prefix };
+}
+function cidrContains(cidr, address) {
+    if (cidr.family !== address.family)
+        return false;
+    const width = cidr.family === 4 ? IPV4_WIDTH : IPV6_WIDTH;
+    const shift = BigInt(width - cidr.prefix);
+    return address.value >> shift === cidr.network >> shift;
+}
+const BLOCKED_RANGES = [
+    '0.0.0.0/8',
+    '10.0.0.0/8',
+    '100.64.0.0/10',
+    '127.0.0.0/8',
+    '169.254.0.0/16',
+    '172.16.0.0/12',
+    '192.0.0.0/24',
+    '192.168.0.0/16',
+    '198.18.0.0/15',
+    '224.0.0.0/4',
+    '240.0.0.0/4',
+    '::1/128',
+    '::/128',
+    '64:ff9b:1::/48',
+    'fc00::/7',
+    'fe80::/10',
+    'fec0::/10',
+    'ff00::/8'
+].map((range) => parseCidr(range));
+/** Parses an allow list, dropping invalid entries and anything that allows every address. */
+export function usableAllowRanges(allowRanges = []) {
+    return allowRanges
+        .map((range) => parseCidr(range))
+        .filter((cidr) => cidr !== undefined && cidr.prefix > 0);
+}
+const DEFAULT_LOOKUP_TIMEOUT_MS = 10_000;
+const defaultLookup = (host) => dnsLookup(host, { all: true, verbatim: true });
+function stripBrackets(host) {
+    return host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+}
+export function createNetworkGuard(config = {}, { lookup = defaultLookup, lookupTimeoutMs = DEFAULT_LOOKUP_TIMEOUT_MS } = {}) {
+    const allow = usableAllowRanges(config.allowRanges);
+    function isBlockedAddress(address) {
+        const parsed = parseAddress(address);
+        if (!parsed)
+            return true; // fail closed
+        if (allow.some((cidr) => cidrContains(cidr, parsed)))
+            return false;
+        return BLOCKED_RANGES.some((cidr) => cidrContains(cidr, parsed));
+    }
+    async function resolveHost(rawHost) {
+        const host = stripBrackets(rawHost.toLowerCase()).replace(/\.+$/, '');
+        if (host === 'localhost' || host.endsWith('.localhost')) {
+            return isBlockedAddress('127.0.0.1')
+                ? { status: 'blocked', host, address: '127.0.0.1' }
+                : { status: 'allowed', host, addresses: ['127.0.0.1'] };
+        }
+        if (isIP(host)) {
+            return isBlockedAddress(host)
+                ? { status: 'blocked', host, address: host }
+                : { status: 'allowed', host, addresses: [host] };
+        }
+        let answers;
+        let timer;
+        try {
+            answers = await Promise.race([
+                lookup(host),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(undefined), lookupTimeoutMs);
+                    timer.unref?.();
+                })
+            ]);
+        }
+        catch {
+            return { status: 'unresolved', host };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!answers || answers.length === 0)
+            return { status: 'unresolved', host };
+        // Any private answer blocks: which address a connection would pick is not ours to control.
+        const blocked = answers.find((entry) => isBlockedAddress(entry.address));
+        if (blocked)
+            return { status: 'blocked', host, address: blocked.address };
+        return { status: 'allowed', host, addresses: answers.map((entry) => entry.address) };
+    }
+    async function checkHost(rawHost) {
+        const resolution = await resolveHost(rawHost);
+        if (resolution.status === 'blocked') {
+            return { allowed: false, host: resolution.host, address: resolution.address };
+        }
+        return resolution.status === 'unresolved' ? { allowed: true, unresolved: true } : { allowed: true };
+    }
+    async function assertUrlAllowed(url) {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            return; // not a URL; the tools reject it with UNSUPPORTED_URL
+        }
+        const verdict = await checkHost(parsed.hostname);
+        if (!verdict.allowed)
+            throw new BlockedAddressError(verdict.host, verdict.address);
+    }
+    return { isBlockedAddress, resolveHost, checkHost, assertUrlAllowed };
+}

package/dist/fetch/proxy-fetch.d.ts

@@ -0,0 +1,22 @@
+import { type ProxyConfig } from '../backends/config.js';
+export type ProxyCredentials = {
+    username?: string;
+    password?: string;
+};
+export type ProxyFetchOptions = {
+    /** TLS options for the tunneled connection to the origin (https targets). */
+    tls?: {
+        rejectUnauthorized?: boolean;
+    };
+};
+/**
+ * Resolve proxy credentials from the config, falling back to environment
+ * variables so secrets can stay out of config files (same policy as API keys).
+ */
+export declare function resolveProxyCredentials(proxy: ProxyConfig, env?: NodeJS.ProcessEnv): ProxyCredentials;
+/**
+ * Build a fetch implementation that routes all traffic through the configured
+ * HTTP/HTTPS proxy. Uses undici (the engine behind Node's global fetch) with a
+ * ProxyAgent dispatcher while keeping the standard fetch API surface.
+ */
+export declare function createProxyFetch(proxy: ProxyConfig, options?: ProxyFetchOptions): typeof fetch;