@cruxy/cli 0.21.0 → 0.22.0

package/dist/web/fetch.js

@@ -0,0 +1,174 @@
+import { webBlockedHost, webFetchFailed } from "../errors/index.js";
+import { demarcatePage } from "./demarcate.js";
+import { BlockedHostError, HostUnresolvedError, assertFetchable, createPinnedDispatcher, defaultResolveHost, } from "./ssrf.js";
+import { fetch as undiciFetch } from "undici";
+/** Content types `web_fetch` will read as text; anything else is refused. */
+function isTextualType(contentType) {
+    const t = contentType.toLowerCase();
+    return (t.startsWith("text/") ||
+        t === "application/json" ||
+        t === "application/xml" ||
+        t === "application/xhtml+xml" ||
+        t === "application/javascript" ||
+        t.endsWith("+json") ||
+        t.endsWith("+xml"));
+}
+/** Read a response body up to `maxBytes`, stopping early; reports truncation. */
+async function readCapped(res, maxBytes) {
+    const reader = res.body?.getReader?.();
+    if (!reader) {
+        // No stream (e.g. some test doubles): fall back to a full read, then cap.
+        const buf = new Uint8Array(await res.arrayBuffer());
+        if (buf.byteLength <= maxBytes)
+            return { bytes: buf, truncated: false };
+        return { bytes: buf.subarray(0, maxBytes), truncated: true };
+    }
+    const chunks = [];
+    let total = 0;
+    let truncated = false;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (value) {
+            chunks.push(value);
+            total += value.byteLength;
+            if (total >= maxBytes) {
+                truncated = true;
+                await reader.cancel().catch(() => { });
+                break;
+            }
+        }
+    }
+    const joined = new Uint8Array(total);
+    let off = 0;
+    for (const c of chunks) {
+        joined.set(c, off);
+        off += c.byteLength;
+    }
+    const bytes = joined.byteLength > maxBytes ? joined.subarray(0, maxBytes) : joined;
+    return { bytes, truncated };
+}
+/** Collapse an HTML document to readable text: drop script/style, strip tags. */
+function htmlToText(html) {
+    return html
+        .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, " ")
+        .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, " ")
+        .replace(/<!--[\s\S]*?-->/g, " ")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&nbsp;/gi, " ")
+        .replace(/&amp;/gi, "&")
+        .replace(/&lt;/gi, "<")
+        .replace(/&gt;/gi, ">")
+        .replace(/[ \t\r\f\v]+/g, " ")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+/**
+ * Fetch one URL as text, enforcing every bound. Returns a {@link FetchResult}.
+ * Throws {@link webBlockedHost} for an SSRF-refused URL (never dispatched),
+ * {@link webFetchFailed} for a network error / timeout / non-text or over-redirect
+ * response. A page fetched successfully but empty of text is a valid result with
+ * empty `text` (the tool surfaces it as `ok:true`, not an error).
+ */
+export async function fetchUrl(rawUrl, config, deps = {}) {
+    // Default to undici's OWN fetch, not the global one. The SSRF guard pins the
+    // connection with an undici `Agent` dispatcher (createPinnedDispatcher); that
+    // dispatcher must be driven by the SAME undici that produced it. The global
+    // `fetch` is backed by the undici BUNDLED IN NODE, whose version drifts by Node
+    // release (v6 on Node 20, v8 on Node 24+), and pairing our dep's v6 Agent with a
+    // bundled-v8 fetch handler throws `InvalidArgumentError: invalid onError method`.
+    // Using our dep's fetch keeps dispatcher + handler on one version on every Node.
+    // (Cast: we only touch the shared WHATWG Response surface — status/headers/body.)
+    const fetchImpl = deps.fetchImpl ?? undiciFetch;
+    const resolveHost = deps.resolveHost ?? defaultResolveHost;
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw webFetchFailed(rawUrl, new Error("not a valid absolute URL"));
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), config.timeoutMs);
+    // Dispatchers pin each hop's connection to its validated address; closed at the
+    // end (not per-hop) because the response body is streamed after the loop.
+    const dispatchers = [];
+    try {
+        let hops = 0;
+        for (;;) {
+            // Re-run the SSRF guard on EVERY hop so a redirect can't reach a private IP.
+            let validated;
+            try {
+                validated = await assertFetchable(url, resolveHost, config.allowPrivateHosts);
+            }
+            catch (err) {
+                if (err instanceof BlockedHostError)
+                    throw webBlockedHost(url.toString(), err.message);
+                if (err instanceof HostUnresolvedError)
+                    throw webFetchFailed(url.toString(), err);
+                throw err;
+            }
+            // Pin the connection to the address(es) the guard just validated so a
+            // rebind can't flip the hostname to an internal IP between check and connect.
+            let dispatcher;
+            if (validated.length > 0) {
+                dispatcher = createPinnedDispatcher(validated);
+                dispatchers.push(dispatcher);
+            }
+            let res;
+            try {
+                res = await fetchImpl(url.toString(), {
+                    method: "GET",
+                    redirect: "manual",
+                    signal: controller.signal,
+                    headers: {
+                        accept: "text/html,text/plain,application/json;q=0.9,*/*;q=0.1",
+                    },
+                    ...(dispatcher ? { dispatcher } : {}),
+                });
+            }
+            catch (err) {
+                throw webFetchFailed(url.toString(), err);
+            }
+            // Manual redirect handling — re-validate the next hop through the guard.
+            if (res.status >= 300 && res.status < 400) {
+                const location = res.headers.get("location");
+                if (!location)
+                    throw webFetchFailed(url.toString(), new Error(`redirect ${res.status} with no Location header`));
+                if (hops >= config.maxRedirects)
+                    throw webFetchFailed(rawUrl, new Error(`exceeded ${config.maxRedirects} redirects`));
+                hops += 1;
+                url = new URL(location, url); // resolve relative redirects
+                continue;
+            }
+            if (!res.ok)
+                throw webFetchFailed(url.toString(), new Error(`server responded ${res.status} ${res.statusText}`));
+            const contentType = (res.headers.get("content-type") ?? "")
+                .split(";")[0]
+                .trim()
+                .toLowerCase();
+            if (contentType !== "" && !isTextualType(contentType))
+                throw webFetchFailed(url.toString(), new Error(`unsupported content type "${contentType}" (text only)`));
+            const { bytes, truncated } = await readCapped(res, config.fetchMaxBytes);
+            const decoded = new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+            const text = contentType === "text/html" || contentType === "application/xhtml+xml"
+                ? htmlToText(decoded)
+                : decoded;
+            return { url: url.toString(), contentType, text, truncated };
+        }
+    }
+    finally {
+        clearTimeout(timer);
+        for (const d of dispatchers)
+            void d.close().catch(() => { });
+    }
+}
+/** Fetch a URL and render it as a demarcated, scrubbed, untrusted-data block. */
+export async function runWebFetch(rawUrl, config, deps = {}) {
+    const result = await fetchUrl(rawUrl, config, deps);
+    const note = result.truncated
+        ? `content truncated at ${config.fetchMaxBytes} bytes`
+        : undefined;
+    return demarcatePage(result.url, result.text, note);
+}

package/dist/web/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./provider.js";
+export * from "./search.js";
+export * from "./fetch.js";
+export * from "./ssrf.js";
+export * from "./demarcate.js";
+export * from "./tools.js";

package/dist/web/index.js

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./provider.js";
+export * from "./search.js";
+export * from "./fetch.js";
+export * from "./ssrf.js";
+export * from "./demarcate.js";
+export * from "./tools.js";

package/dist/web/provider.d.ts

@@ -0,0 +1,29 @@
+import type { SearchProvider, SearchResult, WebConfig, WebDeps } from "./types.js";
+/**
+ * Search-provider seam (C.20). `createSearchProvider` resolves the configured
+ * backend and its API key. There is no gateway search endpoint today (the SDK
+ * Provider only streams chat), so the direct Tavily provider sits behind the seam;
+ * a gateway-backed provider would slot in here with no change to the tools.
+ *
+ * A missing key or unknown provider throws {@link webUnavailable} — a coded,
+ * actionable failure, NEVER a silent empty result (the honesty rule: "no provider"
+ * must not read as "no results").
+ */
+export declare function createSearchProvider(config: WebConfig, deps?: WebDeps): SearchProvider;
+/**
+ * Tavily direct provider. The API key travels ONLY in the `Authorization` header
+ * (never in the query text or URL, never logged), so the outbound query carries no
+ * secret. Any non-2xx / network / timeout outcome becomes a thrown
+ * {@link webSearchFailed}; an empty `results` array is a legitimate zero-result
+ * outcome and is returned as `[]` (the tool renders "no results" as `ok:true`).
+ */
+export declare class TavilyProvider implements SearchProvider {
+    private readonly apiKey;
+    private readonly fetchImpl;
+    readonly name = "tavily";
+    constructor(apiKey: string, fetchImpl: typeof fetch);
+    search(query: string, opts: {
+        maxResults: number;
+        signal: AbortSignal;
+    }): Promise<SearchResult[]>;
+}

package/dist/web/provider.js

@@ -0,0 +1,77 @@
+import { webSearchFailed, webUnavailable } from "../errors/index.js";
+/**
+ * Search-provider seam (C.20). `createSearchProvider` resolves the configured
+ * backend and its API key. There is no gateway search endpoint today (the SDK
+ * Provider only streams chat), so the direct Tavily provider sits behind the seam;
+ * a gateway-backed provider would slot in here with no change to the tools.
+ *
+ * A missing key or unknown provider throws {@link webUnavailable} — a coded,
+ * actionable failure, NEVER a silent empty result (the honesty rule: "no provider"
+ * must not read as "no results").
+ */
+export function createSearchProvider(config, deps = {}) {
+    const env = deps.env ?? process.env;
+    const apiKey = env[config.apiKeyEnv];
+    if (!apiKey || apiKey.trim() === "") {
+        throw webUnavailable(config.provider, config.apiKeyEnv);
+    }
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    switch (config.provider) {
+        case "tavily":
+            return new TavilyProvider(apiKey, fetchImpl);
+        default:
+            // Exhaustive today (the enum has one member); keeps the seam honest if a
+            // provider is added to the schema but not wired here.
+            throw webUnavailable(config.provider, config.apiKeyEnv);
+    }
+}
+const TAVILY_ENDPOINT = "https://api.tavily.com/search";
+/**
+ * Tavily direct provider. The API key travels ONLY in the `Authorization` header
+ * (never in the query text or URL, never logged), so the outbound query carries no
+ * secret. Any non-2xx / network / timeout outcome becomes a thrown
+ * {@link webSearchFailed}; an empty `results` array is a legitimate zero-result
+ * outcome and is returned as `[]` (the tool renders "no results" as `ok:true`).
+ */
+export class TavilyProvider {
+    apiKey;
+    fetchImpl;
+    name = "tavily";
+    constructor(apiKey, fetchImpl) {
+        this.apiKey = apiKey;
+        this.fetchImpl = fetchImpl;
+    }
+    async search(query, opts) {
+        let res;
+        try {
+            res = await this.fetchImpl(TAVILY_ENDPOINT, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify({ query, max_results: opts.maxResults }),
+                signal: opts.signal,
+            });
+        }
+        catch (err) {
+            throw webSearchFailed(err);
+        }
+        if (!res.ok) {
+            throw webSearchFailed(new Error(`provider responded ${res.status} ${res.statusText}`));
+        }
+        let data;
+        try {
+            data = (await res.json());
+        }
+        catch (err) {
+            throw webSearchFailed(err);
+        }
+        const results = Array.isArray(data.results) ? data.results : [];
+        return results.map((r) => ({
+            title: typeof r.title === "string" ? r.title : "",
+            url: typeof r.url === "string" ? r.url : "",
+            snippet: typeof r.content === "string" ? r.content : "",
+        }));
+    }
+}

package/dist/web/search.d.ts

@@ -0,0 +1,17 @@
+import type { SearchResult, WebConfig, WebDeps } from "./types.js";
+/**
+ * Apply the top-N and per-snippet caps. The provider is asked for `maxResults`,
+ * but we re-cap defensively (a provider may over-return) and truncate each snippet
+ * with a visible marker so a long body can't blow the context budget.
+ */
+export declare function boundResults(results: SearchResult[], config: WebConfig): SearchResult[];
+/**
+ * Run one web search and return the demarcated, bounded, scrubbed result block.
+ *
+ * Throws coded errors for the two failure modes the caller must NOT collapse into
+ * an empty result: {@link webUnavailable} (no provider/key — via
+ * `createSearchProvider`) and {@link webSearchFailed} (the search errored — via the
+ * provider). A search that runs and finds nothing returns a demarcated "(no
+ * results)" block — an ordinary success the tool surfaces as `ok:true`.
+ */
+export declare function runWebSearch(query: string, config: WebConfig, deps?: WebDeps): Promise<string>;

package/dist/web/search.js

@@ -0,0 +1,42 @@
+import { createSearchProvider } from "./provider.js";
+import { demarcateSearchResults } from "./demarcate.js";
+/**
+ * Apply the top-N and per-snippet caps. The provider is asked for `maxResults`,
+ * but we re-cap defensively (a provider may over-return) and truncate each snippet
+ * with a visible marker so a long body can't blow the context budget.
+ */
+export function boundResults(results, config) {
+    return results.slice(0, config.maxResults).map((r) => {
+        if (r.snippet.length <= config.snippetMaxChars)
+            return r;
+        return {
+            ...r,
+            snippet: r.snippet.slice(0, config.snippetMaxChars) + " …[snippet truncated]",
+        };
+    });
+}
+/**
+ * Run one web search and return the demarcated, bounded, scrubbed result block.
+ *
+ * Throws coded errors for the two failure modes the caller must NOT collapse into
+ * an empty result: {@link webUnavailable} (no provider/key — via
+ * `createSearchProvider`) and {@link webSearchFailed} (the search errored — via the
+ * provider). A search that runs and finds nothing returns a demarcated "(no
+ * results)" block — an ordinary success the tool surfaces as `ok:true`.
+ */
+export async function runWebSearch(query, config, deps = {}) {
+    const provider = createSearchProvider(config, deps);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), config.timeoutMs);
+    try {
+        const raw = await provider.search(query, {
+            maxResults: config.maxResults,
+            signal: controller.signal,
+        });
+        const bounded = boundResults(raw, config);
+        return demarcateSearchResults(query, bounded);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/web/ssrf.d.ts

@@ -0,0 +1,55 @@
+import { type Dispatcher } from "undici";
+import type { HostResolver } from "./types.js";
+/**
+ * SSRF guard (C.20). A URL the MODEL chose must not be able to reach the user's
+ * internal network, cloud metadata service, or loopback interface. Three layers:
+ *
+ * 1. Scheme allowlist — only `http`/`https` (blocks `file:`, `data:`, `gopher:`…).
+ * 2. Address check — the hostname is RESOLVED and every returned address is
+ *    checked against private/loopback/link-local/reserved ranges (v4 and v6,
+ *    including IPv4-mapped and alternate IP encodings).
+ * 3. Connection pinning — the connection is pinned to the exact address the check
+ *    validated (see {@link createPinnedDispatcher}). Without this, resolving-then-
+ *    fetching re-resolves the hostname at connect time, so a DNS-rebind attacker
+ *    can pass the check with a public IP and have the socket land on 127.0.0.1
+ *    (a TOCTOU hole). Pinning closes it: the connection can only reach a validated
+ *    address, and the host header / TLS SNI still carry the original hostname.
+ *
+ * The check runs BEFORE any request is dispatched, and again on every redirect hop
+ * (see fetch.ts). A block is a security refusal, distinct from a network failure.
+ */
+/** Default resolver: node's `dns.lookup` returning ALL addresses. */
+export declare const defaultResolveHost: HostResolver;
+/** Thrown when a URL is refused pre-dispatch; carries a human reason. */
+export declare class BlockedHostError extends Error {
+}
+/** Thrown when the host could not be resolved (a network failure, not a block). */
+export declare class HostUnresolvedError extends Error {
+}
+/** True if an address (v4 or v6) is in a range `web_fetch` must never reach. */
+export declare function isBlockedAddress(addr: string): boolean;
+/**
+ * A `dns.lookup`-compatible function that ignores the hostname and always hands
+ * back one of the pre-validated `addresses`. This is what pins a connection to the
+ * address the SSRF check already approved, defeating DNS rebinding: the socket can
+ * only reach a validated IP, never a value re-resolved at connect time.
+ */
+export declare function pinnedLookup(addresses: string[]): (_hostname: string, options: unknown, callback: (err: NodeJS.ErrnoException | null, address: string | {
+    address: string;
+    family: number;
+}[], family?: number) => void) => void;
+/** An undici dispatcher whose connections are pinned to `addresses`. */
+export declare function createPinnedDispatcher(addresses: string[]): Dispatcher;
+/**
+ * Assert that `url` may be fetched and return the validated addresses to pin the
+ * connection to. Throws {@link BlockedHostError} for a bad scheme or a host
+ * resolving into a blocked range, or {@link HostUnresolvedError} if the host cannot
+ * be resolved.
+ *
+ * The returned list is the exact set of addresses the caller must restrict the
+ * connection to (via {@link createPinnedDispatcher}). An empty list means "do not
+ * pin" — only returned under `allowPrivate`, the deliberate internal-network escape
+ * hatch (from `web.allowPrivateHosts`), which bypasses the address check and lets
+ * the transport resolve normally. The scheme check always applies.
+ */
+export declare function assertFetchable(url: URL, resolveHost: HostResolver, allowPrivate: boolean): Promise<string[]>;

package/dist/web/ssrf.js

@@ -0,0 +1,223 @@
+import { lookup } from "node:dns";
+import { Agent } from "undici";
+/**
+ * SSRF guard (C.20). A URL the MODEL chose must not be able to reach the user's
+ * internal network, cloud metadata service, or loopback interface. Three layers:
+ *
+ * 1. Scheme allowlist — only `http`/`https` (blocks `file:`, `data:`, `gopher:`…).
+ * 2. Address check — the hostname is RESOLVED and every returned address is
+ *    checked against private/loopback/link-local/reserved ranges (v4 and v6,
+ *    including IPv4-mapped and alternate IP encodings).
+ * 3. Connection pinning — the connection is pinned to the exact address the check
+ *    validated (see {@link createPinnedDispatcher}). Without this, resolving-then-
+ *    fetching re-resolves the hostname at connect time, so a DNS-rebind attacker
+ *    can pass the check with a public IP and have the socket land on 127.0.0.1
+ *    (a TOCTOU hole). Pinning closes it: the connection can only reach a validated
+ *    address, and the host header / TLS SNI still carry the original hostname.
+ *
+ * The check runs BEFORE any request is dispatched, and again on every redirect hop
+ * (see fetch.ts). A block is a security refusal, distinct from a network failure.
+ */
+/** Default resolver: node's `dns.lookup` returning ALL addresses. */
+export const defaultResolveHost = (host) => new Promise((resolve, reject) => {
+    lookup(host, { all: true }, (err, addresses) => {
+        if (err)
+            reject(err);
+        else
+            resolve(addresses.map((a) => a.address));
+    });
+});
+/** Thrown when a URL is refused pre-dispatch; carries a human reason. */
+export class BlockedHostError extends Error {
+}
+/** Thrown when the host could not be resolved (a network failure, not a block). */
+export class HostUnresolvedError extends Error {
+}
+/** Parse a dotted-quad IPv4 string into its four octets, or null. */
+function parseIpv4(ip) {
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(ip);
+    if (!m)
+        return null;
+    const octets = m.slice(1, 5).map((s) => Number(s));
+    if (octets.some((o) => o > 255))
+        return null;
+    return octets;
+}
+/** True if an IPv4 address falls in a private/loopback/link-local/reserved range. */
+function isBlockedIpv4(ip) {
+    const octets = parseIpv4(ip);
+    if (!octets)
+        return false;
+    const [a, b] = octets;
+    if (a === 0)
+        return true; // 0.0.0.0/8 "this network" / unspecified
+    if (a === 10)
+        return true; // 10.0.0.0/8 private
+    if (a === 127)
+        return true; // 127.0.0.0/8 loopback
+    if (a === 169 && b === 254)
+        return true; // 169.254.0.0/16 link-local (incl. 169.254.169.254 metadata)
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // 172.16.0.0/12 private
+    if (a === 192 && b === 168)
+        return true; // 192.168.0.0/16 private
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // 100.64.0.0/10 CGNAT
+    if (a === 198 && (b === 18 || b === 19))
+        return true; // 198.18.0.0/15 benchmarking
+    if (a === 255 && b === 255)
+        return true; // broadcast-ish
+    return false;
+}
+/**
+ * Expand an IPv6 literal into its 8 sixteen-bit groups, or null if unparseable.
+ * Handles `::` compression and an embedded IPv4 tail (`::ffff:127.0.0.1`).
+ */
+function parseIpv6(input) {
+    let s = input;
+    const tail = [];
+    // Peel off a trailing dotted-quad (IPv4-mapped/-compatible forms).
+    const v4 = /(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(s);
+    if (v4) {
+        const o = parseIpv4(v4[1]);
+        if (!o)
+            return null;
+        tail.push((o[0] << 8) | o[1], (o[2] << 8) | o[3]);
+        s = s.slice(0, v4.index); // leaves a trailing ':' before the compression split
+    }
+    const halves = s.split("::");
+    if (halves.length > 2)
+        return null; // more than one "::" is illegal
+    const head = halves[0] ? halves[0].split(":").filter(Boolean) : [];
+    const rest = halves[1] ? halves[1].split(":").filter(Boolean) : [];
+    const toNums = (groups) => {
+        const out = [];
+        for (const g of groups) {
+            if (!/^[0-9a-f]{1,4}$/.test(g))
+                return null;
+            out.push(parseInt(g, 16));
+        }
+        return out;
+    };
+    const headNums = toNums(head);
+    const restNums = toNums(rest);
+    if (!headNums || !restNums)
+        return null;
+    let groups;
+    if (halves.length === 2) {
+        const fill = 8 - (headNums.length + restNums.length + tail.length);
+        if (fill < 0)
+            return null;
+        groups = [
+            ...headNums,
+            ...Array(fill).fill(0),
+            ...restNums,
+            ...tail,
+        ];
+    }
+    else {
+        groups = [...headNums, ...tail];
+    }
+    return groups.length === 8 ? groups : null;
+}
+/** True if an expanded IPv6 address is in a range `web_fetch` must never reach. */
+function isBlockedIpv6(g) {
+    // IPv4-mapped (::ffff:a.b.c.d) and IPv4-compatible (::a.b.c.d): check the v4 part.
+    const firstFiveZero = g.slice(0, 5).every((x) => x === 0);
+    const firstSixZero = firstFiveZero && g[5] === 0;
+    const embedded = `${g[6] >> 8}.${g[6] & 0xff}.${g[7] >> 8}.${g[7] & 0xff}`;
+    if (firstFiveZero && g[5] === 0xffff)
+        return isBlockedIpv4(embedded); // ::ffff:x
+    if (firstSixZero &&
+        !(g[6] === 0 && g[7] === 0) &&
+        !(g[6] === 0 && g[7] === 1))
+        return isBlockedIpv4(embedded); // ::x.y.z.w (IPv4-compatible, deprecated)
+    if (g.every((x) => x === 0))
+        return true; // :: unspecified
+    if (firstSixZero && g[6] === 0 && g[7] === 1)
+        return true; // ::1 loopback
+    if ((g[0] & 0xffc0) === 0xfe80)
+        return true; // fe80::/10 link-local (fe80–febf)
+    if ((g[0] & 0xfe00) === 0xfc00)
+        return true; // fc00::/7 unique-local (fc00–fdff)
+    if ((g[0] & 0xff00) === 0xff00)
+        return true; // ff00::/8 multicast
+    return false;
+}
+/** True if an address (v4 or v6) is in a range `web_fetch` must never reach. */
+export function isBlockedAddress(addr) {
+    // Strip IPv6 brackets and a scope/zone id (e.g. fe80::1%eth0).
+    const ip = addr
+        .trim()
+        .toLowerCase()
+        .replace(/^\[|\]$/g, "")
+        .split("%")[0];
+    if (ip.includes(":")) {
+        const groups = parseIpv6(ip);
+        if (!groups)
+            return true; // fail closed: an unparseable colon-address is refused
+        return isBlockedIpv6(groups);
+    }
+    return isBlockedIpv4(ip);
+}
+/**
+ * A `dns.lookup`-compatible function that ignores the hostname and always hands
+ * back one of the pre-validated `addresses`. This is what pins a connection to the
+ * address the SSRF check already approved, defeating DNS rebinding: the socket can
+ * only reach a validated IP, never a value re-resolved at connect time.
+ */
+export function pinnedLookup(addresses) {
+    const resolved = addresses.map((address) => ({
+        address,
+        family: address.includes(":") ? 6 : 4,
+    }));
+    return (_hostname, options, callback) => {
+        const all = typeof options === "object" && options !== null && "all" in options
+            ? options.all
+            : false;
+        if (all)
+            callback(null, resolved);
+        else
+            callback(null, resolved[0].address, resolved[0].family);
+    };
+}
+/** An undici dispatcher whose connections are pinned to `addresses`. */
+export function createPinnedDispatcher(addresses) {
+    return new Agent({ connect: { lookup: pinnedLookup(addresses) } });
+}
+/**
+ * Assert that `url` may be fetched and return the validated addresses to pin the
+ * connection to. Throws {@link BlockedHostError} for a bad scheme or a host
+ * resolving into a blocked range, or {@link HostUnresolvedError} if the host cannot
+ * be resolved.
+ *
+ * The returned list is the exact set of addresses the caller must restrict the
+ * connection to (via {@link createPinnedDispatcher}). An empty list means "do not
+ * pin" — only returned under `allowPrivate`, the deliberate internal-network escape
+ * hatch (from `web.allowPrivateHosts`), which bypasses the address check and lets
+ * the transport resolve normally. The scheme check always applies.
+ */
+export async function assertFetchable(url, resolveHost, allowPrivate) {
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new BlockedHostError(`only http(s) URLs may be fetched (got "${url.protocol.replace(/:$/, "")}")`);
+    }
+    if (allowPrivate)
+        return [];
+    const host = url.hostname.replace(/^\[|\]$/g, ""); // strip IPv6 brackets
+    let addresses;
+    try {
+        addresses = await resolveHost(host);
+    }
+    catch (err) {
+        throw new HostUnresolvedError(`could not resolve host "${host}": ${err.message}`);
+    }
+    if (addresses.length === 0) {
+        throw new HostUnresolvedError(`host "${host}" resolved to no addresses`);
+    }
+    for (const addr of addresses) {
+        if (isBlockedAddress(addr)) {
+            throw new BlockedHostError(`host "${host}" resolves to ${addr}, a private/loopback/link-local address`);
+        }
+    }
+    return addresses;
+}

package/dist/web/tools.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import type { Tool } from "../tools/types.js";
+import type { WebDeps } from "./types.js";
+declare const searchParams: z.ZodObject<{
+    query: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+}, {
+    query: string;
+}>;
+export declare function createWebSearchTool(deps?: WebDeps): Tool<typeof searchParams>;
+declare const fetchParams: z.ZodObject<{
+    url: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+}, {
+    url: string;
+}>;
+export declare function createWebFetchTool(deps?: WebDeps): Tool<typeof fetchParams>;
+export {};