@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

package/dist/net/proxy.d.ts

@@ -0,0 +1,44 @@
+import { Agent } from "undici";
+/**
+ * Tunneling untrusted downloads through an HTTP(S) egress proxy with `CONNECT` (`net.httpsProxy`).
+ *
+ * Behind a proxy the kernel does not resolve the target: the proxy does, and the kernel's own DNS
+ * may answer fake or internal addresses (e.g. a fake-IP resolver answering 198.18.0.0/15) that say
+ * nothing about where the proxy connects. `safeFetch` therefore checks only the hostname rules
+ * (IP-literal targets against the private ranges and `allowPrivateHosts`; `allowedHosts` is checked
+ * by the callers on the hostname) and leaves SSRF protection for resolved addresses to the proxy.
+ *
+ * The proxy URL may carry credentials (`http://user:pass@proxy:3128`, sent as Basic
+ * `Proxy-Authorization`); they never appear in errors or logs: messages name the proxy by host and
+ * port only ({@link proxyLabel}).
+ */
+/** The egress proxy part of a `NetPolicy`. */
+export type NetProxy = {
+    /** `http://` or `https://` proxy URL, optionally with `user:password@`. */
+    url: string;
+    /** Hostnames that bypass the proxy (an entry also matches its subdomains). */
+    noProxy: string[];
+};
+/** Why a `net.httpsProxy` value is refused (English, never echoing the value), or undefined. */
+export declare function proxyUrlProblem(value: string): string | undefined;
+/** Why a `net.noProxy` entry is refused, or undefined: a hostname (optionally `.`-prefixed) or IP. */
+export declare function noProxyEntryProblem(entry: string): string | undefined;
+/** Whether `host` bypasses the proxy: equal to a `noProxy` entry or a subdomain of one. */
+export declare function bypassesProxy(host: string, noProxy: readonly string[]): boolean;
+/** The proxy as `host:port`, for messages: never its credentials. */
+export declare function proxyLabel(proxy: URL): string;
+/**
+ * TLS trust overrides (tests): `ca` for the target, `proxyCa` for an https proxy; and the tunnel
+ * deadline (tests; default 10 s).
+ */
+export type ProxyTls = {
+    ca?: string | string[];
+    proxyCa?: string | string[];
+    tunnelTimeoutMs?: number;
+};
+/**
+ * An undici dispatcher that reaches every https origin through a `CONNECT` tunnel on `proxyUrl`,
+ * then speaks TLS to the target over it (SNI and certificate checks for the target's hostname).
+ * The target is never resolved locally. One agent per download, like `pinnedAgent`.
+ */
+export declare function proxyAgent(proxyUrl: string, tls?: ProxyTls): Agent;

package/dist/net/proxy.js

@@ -0,0 +1,162 @@
+import { isIP } from "node:net";
+import { Agent, buildConnector } from "undici";
+import { NetDeniedError, normalizeHost } from "./public-address.js";
+/**
+ * How long opening the tunnel may take in total: connecting to the proxy plus its whole `CONNECT`
+ * answer. One deadline, not an idle timeout, so a proxy trickling bytes cannot hold a download open.
+ */
+const TUNNEL_TIMEOUT_MS = 10_000;
+/** The largest `CONNECT` response head accepted from the proxy. */
+const MAX_RESPONSE_HEAD = 16 * 1024;
+/** Why a `net.httpsProxy` value is refused (English, never echoing the value), or undefined. */
+export function proxyUrlProblem(value) {
+    let u;
+    try {
+        u = new URL(value);
+    }
+    catch {
+        return "must be an http:// or https:// URL such as http://proxy.internal:3128";
+    }
+    if (u.protocol !== "http:" && u.protocol !== "https:") {
+        return "must be an http:// or https:// URL (other proxy protocols are not supported)";
+    }
+    if ((u.pathname !== "" && u.pathname !== "/") || u.search !== "" || u.hash !== "") {
+        return "must not have a path, query or fragment";
+    }
+    try {
+        // proxyAgent decodes them for Basic auth; a bad escape (`%zz`) would throw on every download
+        decodeURIComponent(u.username);
+        decodeURIComponent(u.password);
+    }
+    catch {
+        return "the user name or password is not valid percent-encoding";
+    }
+    return undefined;
+}
+const HOSTNAME_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/i;
+/** Why a `net.noProxy` entry is refused, or undefined: a hostname (optionally `.`-prefixed) or IP. */
+export function noProxyEntryProblem(entry) {
+    const e = entry.startsWith(".") ? entry.slice(1) : entry;
+    if (isIP(e) !== 0 || HOSTNAME_RE.test(e))
+        return undefined;
+    return `"${entry}" is not a hostname or an IP address (no scheme, port, path or wildcard)`;
+}
+/** Whether `host` bypasses the proxy: equal to a `noProxy` entry or a subdomain of one. */
+export function bypassesProxy(host, noProxy) {
+    const h = normalizeHost(host);
+    return noProxy.some((entry) => {
+        const e = normalizeHost(entry.startsWith(".") ? entry.slice(1) : entry);
+        return e !== "" && (h === e || (isIP(h) === 0 && h.endsWith(`.${e}`)));
+    });
+}
+/** The proxy as `host:port`, for messages: never its credentials. */
+export function proxyLabel(proxy) {
+    return `${proxy.hostname}:${proxy.port || (proxy.protocol === "https:" ? "443" : "80")}`;
+}
+/** Reads the proxy's answer to `CONNECT` and resolves its status once the head is complete. */
+function readConnectResponse(socket) {
+    return new Promise((resolve, reject) => {
+        let head = Buffer.alloc(0);
+        const done = (err, status) => {
+            socket.off("data", onData);
+            socket.off("error", onError);
+            socket.off("close", onClose);
+            if (err)
+                reject(err);
+            else
+                resolve(status);
+        };
+        const onData = (chunk) => {
+            head = Buffer.concat([head, chunk]);
+            // Checked before looking for the terminator, so a large chunk that holds it is refused too
+            if (head.length > MAX_RESPONSE_HEAD) {
+                done(new Error("the proxy response head is too large"));
+                return;
+            }
+            const end = head.indexOf("\r\n\r\n");
+            if (end < 0)
+                return;
+            socket.pause();
+            const rest = head.subarray(end + 4);
+            // Bytes after the head belong to the TLS stream: the socket is paused, so tls.connect over
+            // it (targetConnect with httpSocket) reads them first
+            if (rest.length > 0)
+                socket.unshift(rest);
+            const m = /^HTTP\/1\.[01] (\d{3})/.exec(head.subarray(0, end).toString("latin1"));
+            if (!m)
+                done(new Error("the proxy sent an invalid response to CONNECT"));
+            else
+                done(null, Number(m[1]));
+        };
+        const onError = (e) => done(e);
+        const onClose = () => done(new Error("the proxy closed the connection during CONNECT"));
+        socket.on("data", onData);
+        socket.on("error", onError);
+        socket.on("close", onClose);
+    });
+}
+/**
+ * An undici dispatcher that reaches every https origin through a `CONNECT` tunnel on `proxyUrl`,
+ * then speaks TLS to the target over it (SNI and certificate checks for the target's hostname).
+ * The target is never resolved locally. One agent per download, like `pinnedAgent`.
+ */
+export function proxyAgent(proxyUrl, tls = {}) {
+    const proxy = new URL(proxyUrl);
+    const label = proxyLabel(proxy);
+    const auth = proxy.username !== "" || proxy.password !== ""
+        ? `Basic ${Buffer.from(`${decodeURIComponent(proxy.username)}:${decodeURIComponent(proxy.password)}`).toString("base64")}`
+        : undefined;
+    const tunnelTimeoutMs = tls.tunnelTimeoutMs ?? TUNNEL_TIMEOUT_MS;
+    const proxyConnect = buildConnector({
+        timeout: tunnelTimeoutMs,
+        ...(tls.proxyCa !== undefined && { ca: tls.proxyCa }),
+    });
+    const targetConnect = buildConnector({
+        ...(tls.ca !== undefined && { ca: tls.ca }),
+    });
+    const proxyPort = proxy.port || (proxy.protocol === "https:" ? "443" : "80");
+    const proxyHost = normalizeHost(proxy.hostname);
+    const connect = (opts, callback) => {
+        const target = normalizeHost(opts.hostname);
+        const port = opts.port || "443";
+        const authority = `${isIP(target) === 6 ? `[${target}]` : target}:${port}`;
+        const fail = (e) => callback(e, null);
+        if (opts.protocol !== "https:") {
+            fail(new Error("only https targets are sent through the egress proxy"));
+            return;
+        }
+        const deadline = Date.now() + tunnelTimeoutMs;
+        proxyConnect({
+            protocol: proxy.protocol,
+            hostname: proxyHost,
+            host: `${proxy.hostname}:${proxyPort}`,
+            port: proxyPort,
+        }, (err, socket) => {
+            if (err || socket === null) {
+                fail(new Error(`cannot connect to the egress proxy ${label}: ${err?.message ?? ""}`));
+                return;
+            }
+            const s = socket;
+            // What is left of the one deadline that started before connecting to the proxy
+            const timer = setTimeout(() => s.destroy(new Error("the proxy did not answer CONNECT in time")), Math.max(0, deadline - Date.now()));
+            const lines = [`CONNECT ${authority} HTTP/1.1`, `Host: ${authority}`];
+            if (auth !== undefined)
+                lines.push(`Proxy-Authorization: ${auth}`);
+            s.write(`${lines.join("\r\n")}\r\n\r\n`);
+            readConnectResponse(s).then((status) => {
+                clearTimeout(timer);
+                if (status < 200 || status > 299) {
+                    s.destroy();
+                    fail(new NetDeniedError("net.proxy_refused", target, `The egress proxy ${label} refused the connection to ${authority} (HTTP ${status}).`));
+                    return;
+                }
+                targetConnect({ ...opts, httpSocket: s }, callback);
+            }, (e) => {
+                clearTimeout(timer);
+                s.destroy();
+                fail(new Error(`egress proxy ${label}: ${e.message}`));
+            });
+        });
+    };
+    return new Agent({ connect: connect });
+}

package/dist/net/public-address.d.ts

@@ -0,0 +1,60 @@
+/** Whether connecting to this (resolved) IP is forbidden: private, loopback, reserved, or unparseable. */
+export declare function isForbiddenAddress(ip: string): boolean;
+/** Link-local (incl. cloud metadata 169.254.169.254) or unparseable: forbidden whatever the exemptions. */
+export declare function isLinkLocalAddress(ip: string): boolean;
+/** A hostname normalized for comparison: lower case, no IPv6 brackets, no trailing dots. */
+export declare function normalizeHost(host: string): string;
+/** `localhost`, `127.0.0.0/8` or `::1` (as written in a URL). */
+export declare function isLoopbackHost(host: string): boolean;
+/** Where downloads may go besides public addresses. */
+export type NetPolicy = {
+    /** Testing only: plain http and loopback addresses for loopback hosts. */
+    allowInsecureLoopback: boolean;
+    /**
+     * `marketplaces.allowPrivateHosts`: a hostname entry (exact, case-insensitive) exempts that host's
+     * resolved addresses; an IP or CIDR entry exempts IP-literal URL hosts inside it only, never a DNS
+     * name that resolves there (an attacker's name could point into the range).
+     */
+    allowPrivateHosts: string[];
+    /** Origins configured by the admin (the npm registry): their hosts may resolve to private addresses. */
+    trustedOrigins: string[];
+    /**
+     * `net.httpsProxy` / `net.noProxy`: https downloads tunnel through this proxy (see `proxy.ts`);
+     * the target is then resolved by the proxy, not checked here, except IP-literal hosts.
+     */
+    proxy?: {
+        url: string;
+        noProxy: string[];
+    };
+};
+export type LookupFn = (host: string) => Promise<{
+    address: string;
+    family: number;
+}[]>;
+export type NetDeniedCode = "net.private_address" | "net.dns_failed" | "net.redirect" | "net.insecure_url" | "net.proxy_refused";
+/** A download refused by the network rules. English message, safe to show. */
+export declare class NetDeniedError extends Error {
+    readonly code: NetDeniedCode;
+    readonly host: string;
+    constructor(code: NetDeniedCode, host: string, message: string);
+}
+/** The shortest prefix an `allowPrivateHosts` CIDR may have, per family. */
+export declare const MIN_CIDR_PREFIX: {
+    readonly ipv4: 8;
+    readonly ipv6: 16;
+};
+/** A syntactically valid `addr/prefix` CIDR as [address, prefix, family], else undefined. */
+export declare function parseCidr(s: string): [string, number, "ipv4" | "ipv6"] | undefined;
+/**
+ * Why a `marketplaces.allowPrivateHosts` entry is invalid (English), or null when it is a hostname,
+ * an IP address or a CIDR no broader than /8 (IPv4) or /16 (IPv6).
+ */
+export declare function privateHostEntryProblem(entry: string): string | null;
+/** A valid `marketplaces.allowPrivateHosts` entry (see {@link privateHostEntryProblem}). */
+export declare function isPrivateHostEntry(entry: string): boolean;
+/**
+ * Resolves `host` (an IP literal is taken as is) and returns every address, in resolution order,
+ * after checking that each is public or exempt by `policy`. Throws {@link NetDeniedError}
+ * `net.dns_failed` (no answer) or `net.private_address` (some address is private and not exempt).
+ */
+export declare function resolvePublic(host: string, policy: NetPolicy, lookup?: LookupFn): Promise<string[]>;

package/dist/net/public-address.js

@@ -0,0 +1,272 @@
+import { lookup as dnsLookup } from "node:dns/promises";
+import { BlockList, isIP } from "node:net";
+/**
+ * Public-address checks for downloads whose URL comes from a marketplace or an admin (spec §5.1).
+ * A host is resolved once, every resolved address must be public, and the caller connects to the
+ * checked addresses only (see `safe-fetch.ts`), so a DNS answer that changes between check and
+ * connect (DNS rebinding, e.g. `10.0.0.1.nip.io`) cannot reach a private address.
+ *
+ * The blocked ranges are those of the sandbox-docker plugin's egress proxy
+ * (`plugins/sandbox-docker/egress-proxy/proxy.mjs` in capybara-hq/plugins), ported here because the
+ * kernel must not import from a plugin. IPv6 addresses that embed an IPv4 address
+ * (v4-mapped `::ffff:0:0/96`, v4-compatible `::/96`, NAT64 `64:ff9b::/96`, 6to4 `2002::/16`) are
+ * judged by the embedded IPv4 address; anything unparseable is refused. One addition over proxy.mjs:
+ * SIIT IPv4-translated addresses (`::ffff:0:a.b.c.d`, `::ffff:0:0:0/96`, RFC 2765) are also judged by
+ * the embedded IPv4 address (proxy.mjs falls through to the IPv6 table, where they are not blocked);
+ * a host behind a SIIT translator could otherwise reach a private IPv4 address.
+ *
+ * Link-local addresses (`169.254.0.0/16`, including cloud metadata, and `fe80::/10`) stay forbidden
+ * whatever the exemptions: no internal mirror lives there.
+ */
+const BLOCKED_V4 = [
+    ["0.0.0.0", 8], // unspecified / this network
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10], // CGNAT
+    ["127.0.0.0", 8],
+    ["169.254.0.0", 16], // link-local, including cloud metadata 169.254.169.254
+    ["172.16.0.0", 12],
+    ["192.0.0.0", 24],
+    ["192.0.2.0", 24],
+    ["192.88.99.0", 24],
+    ["192.168.0.0", 16],
+    ["198.18.0.0", 15],
+    ["198.51.100.0", 24],
+    ["203.0.113.0", 24],
+    ["224.0.0.0", 4], // multicast
+    ["240.0.0.0", 4], // reserved and broadcast
+];
+const BLOCKED_V6 = [
+    ["::", 128],
+    ["::1", 128],
+    ["100::", 64],
+    ["2001:db8::", 32],
+    ["fc00::", 7], // ULA
+    ["fe80::", 10], // link-local
+    ["fec0::", 10],
+    ["ff00::", 8], // multicast
+];
+// Read-only after construction: address tables, not shared mutable state.
+const blocked = new BlockList();
+for (const [a, p] of BLOCKED_V4)
+    blocked.addSubnet(a, p, "ipv4");
+for (const [a, p] of BLOCKED_V6)
+    blocked.addSubnet(a, p, "ipv6");
+const linkLocal = new BlockList();
+linkLocal.addSubnet("169.254.0.0", 16, "ipv4");
+linkLocal.addSubnet("fe80::", 10, "ipv6");
+/** An IPv6 address as its 8 16-bit groups; null when it cannot be parsed. */
+function v6Groups(ip) {
+    let s = ip.toLowerCase();
+    const zone = s.indexOf("%");
+    if (zone >= 0)
+        s = s.slice(0, zone);
+    // a trailing dotted IPv4 (::ffff:1.2.3.4)
+    const m = /^(.*:)(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(s);
+    if (m) {
+        const [a = 0, b = 0, c = 0, d = 0] = m.slice(2).map(Number);
+        if ([a, b, c, d].some((x) => x > 255))
+            return null;
+        s = `${m[1]}${((a << 8) | b).toString(16)}:${((c << 8) | d).toString(16)}`;
+    }
+    const halves = s.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 fill = halves.length === 2 ? 8 - head.length - tail.length : 0;
+    if (fill < 0)
+        return null;
+    const parts = [...head, ...Array(fill).fill("0"), ...tail];
+    if (!parts.every((g) => /^[0-9a-f]{1,4}$/.test(g)))
+        return null;
+    const groups = parts.map((g) => Number.parseInt(g, 16));
+    return groups.length === 8 ? groups : null;
+}
+const v4Of = (hi, lo) => `${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`;
+/**
+ * Whether `ip` falls in `table`, judging an IPv6 address that embeds an IPv4 address by the
+ * embedded one. Anything unparseable (including an IPv4 address with a `%` zone) counts as inside.
+ */
+function inTable(ip, table) {
+    if (isIP(ip) === 4)
+        return table.check(ip, "ipv4");
+    if (isIP(ip.split("%")[0] ?? "") !== 6)
+        return true;
+    const g = v6Groups(ip);
+    if (g === null)
+        return true;
+    const zeros = (from, to) => g.slice(from, to).every((x) => x === 0);
+    const [g0, g1, g2, , g4, g5, g6 = 0, g7 = 0] = g;
+    // v4-mapped ::ffff:a.b.c.d
+    if (zeros(0, 5) && g5 === 0xffff)
+        return inTable(v4Of(g6, g7), table);
+    // SIIT ::ffff:0:a.b.c.d (not unwrapped by proxy.mjs; see the file header)
+    if (zeros(0, 4) && g4 === 0xffff && g5 === 0)
+        return inTable(v4Of(g6, g7), table);
+    // v4-compatible ::a.b.c.d (:: and ::1 are left to the IPv6 table)
+    if (zeros(0, 6) && (g6 !== 0 || g7 > 1))
+        return inTable(v4Of(g6, g7), table);
+    // NAT64 64:ff9b::a.b.c.d
+    if (g0 === 0x64 && g1 === 0xff9b)
+        return inTable(v4Of(g6, g7), table);
+    // 6to4 2002:AABB:CCDD::
+    if (g0 === 0x2002)
+        return inTable(v4Of(g1 ?? 0, g2 ?? 0), table);
+    return table.check(g.map((x) => x.toString(16)).join(":"), "ipv6");
+}
+/** Whether connecting to this (resolved) IP is forbidden: private, loopback, reserved, or unparseable. */
+export function isForbiddenAddress(ip) {
+    return inTable(ip, blocked);
+}
+/** Link-local (incl. cloud metadata 169.254.169.254) or unparseable: forbidden whatever the exemptions. */
+export function isLinkLocalAddress(ip) {
+    return inTable(ip, linkLocal);
+}
+/** A hostname normalized for comparison: lower case, no IPv6 brackets, no trailing dots. */
+export function normalizeHost(host) {
+    let h = host.trim().toLowerCase();
+    if (h.startsWith("[") && h.endsWith("]"))
+        h = h.slice(1, -1);
+    while (h.endsWith("."))
+        h = h.slice(0, -1);
+    return h;
+}
+/** `localhost`, `127.0.0.0/8` or `::1` (as written in a URL). */
+export function isLoopbackHost(host) {
+    const h = normalizeHost(host);
+    return h === "localhost" || h === "::1" || (isIP(h) === 4 && h.startsWith("127."));
+}
+/** A download refused by the network rules. English message, safe to show. */
+export class NetDeniedError extends Error {
+    code;
+    host;
+    constructor(code, host, message) {
+        super(message);
+        this.code = code;
+        this.host = host;
+        this.name = "NetDeniedError";
+    }
+}
+const defaultLookup = (host) => dnsLookup(host, { all: true, verbatim: true });
+/** The shortest prefix an `allowPrivateHosts` CIDR may have, per family. */
+export const MIN_CIDR_PREFIX = { ipv4: 8, ipv6: 16 };
+/** A syntactically valid `addr/prefix` CIDR as [address, prefix, family], else undefined. */
+export function parseCidr(s) {
+    const m = /^([^/]+)\/(\d{1,3})$/.exec(s.trim());
+    if (!m)
+        return undefined;
+    const addr = m[1].toLowerCase();
+    const prefix = Number(m[2]);
+    const family = isIP(addr);
+    if (family === 4 && prefix <= 32)
+        return [addr, prefix, "ipv4"];
+    if (family === 6 && prefix <= 128)
+        return [addr, prefix, "ipv6"];
+    return undefined;
+}
+const HOSTNAME = /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/;
+/**
+ * Why a `marketplaces.allowPrivateHosts` entry is invalid (English), or null when it is a hostname,
+ * an IP address or a CIDR no broader than /8 (IPv4) or /16 (IPv6).
+ */
+export function privateHostEntryProblem(entry) {
+    const cidr = parseCidr(entry);
+    if (cidr) {
+        const [, prefix, family] = cidr;
+        const min = MIN_CIDR_PREFIX[family];
+        return prefix < min
+            ? `the CIDR ${entry.trim()} is too broad: use a prefix of at least /${min} for ${family === "ipv4" ? "IPv4" : "IPv6"}`
+            : null;
+    }
+    const h = normalizeHost(entry);
+    if (isIP(h) !== 0 || HOSTNAME.test(h))
+        return null;
+    return "must be a hostname, an IP address or a CIDR such as 10.1.0.0/16";
+}
+/** A valid `marketplaces.allowPrivateHosts` entry (see {@link privateHostEntryProblem}). */
+export function isPrivateHostEntry(entry) {
+    return privateHostEntryProblem(entry) === null;
+}
+function exemptions(host, policy) {
+    const cidrs = new BlockList();
+    let all = false;
+    const literal = isIP(host) !== 0;
+    // a loopback host under allowInsecureLoopback may resolve to loopback addresses only
+    if (policy.allowInsecureLoopback && isLoopbackHost(host)) {
+        cidrs.addSubnet("127.0.0.0", 8, "ipv4");
+        cidrs.addAddress("::1", "ipv6");
+    }
+    for (const entry of policy.allowPrivateHosts) {
+        if (!isPrivateHostEntry(entry))
+            continue;
+        const cidr = parseCidr(entry);
+        const name = normalizeHost(entry);
+        if (cidr) {
+            // IP and CIDR entries match IP-literal hosts only
+            if (literal)
+                cidrs.addSubnet(...cidr);
+        }
+        else if (isIP(name) !== 0) {
+            if (literal)
+                cidrs.addAddress(name, isIP(name) === 4 ? "ipv4" : "ipv6");
+        }
+        else if (name === host) {
+            all = true;
+        }
+    }
+    for (const origin of policy.trustedOrigins) {
+        try {
+            if (normalizeHost(new URL(origin).hostname) === host)
+                all = true;
+        }
+        catch {
+            // an unparseable origin trusts nothing
+        }
+    }
+    return { all, cidrs };
+}
+function allowedBy(cidrs, ip) {
+    const family = isIP(ip);
+    if (family === 4)
+        return cidrs.check(ip, "ipv4");
+    if (family === 6) {
+        if (cidrs.check(ip, "ipv6"))
+            return true;
+        // a v4-mapped answer also matches an IPv4 CIDR
+        const g = v6Groups(ip);
+        if (g?.slice(0, 5).every((x) => x === 0) && g[5] === 0xffff) {
+            return cidrs.check(v4Of(g[6] ?? 0, g[7] ?? 0), "ipv4");
+        }
+    }
+    return false;
+}
+/**
+ * Resolves `host` (an IP literal is taken as is) and returns every address, in resolution order,
+ * after checking that each is public or exempt by `policy`. Throws {@link NetDeniedError}
+ * `net.dns_failed` (no answer) or `net.private_address` (some address is private and not exempt).
+ */
+export async function resolvePublic(host, policy, lookup = defaultLookup) {
+    const h = normalizeHost(host);
+    let addrs;
+    if (isIP(h) !== 0) {
+        addrs = [h];
+    }
+    else {
+        try {
+            addrs = (await lookup(h)).map((a) => a.address);
+        }
+        catch {
+            throw new NetDeniedError("net.dns_failed", h, `Cannot resolve ${h}.`);
+        }
+        if (addrs.length === 0)
+            throw new NetDeniedError("net.dns_failed", h, `Cannot resolve ${h}.`);
+    }
+    const ex = exemptions(h, policy);
+    const refused = (a) => isForbiddenAddress(a) && (isLinkLocalAddress(a) || (!ex.all && !allowedBy(ex.cidrs, a)));
+    if (addrs.some(refused)) {
+        throw new NetDeniedError("net.private_address", h, addrs.some(isLinkLocalAddress)
+            ? `Access to ${h} is refused: it resolves to a link-local address, which is never allowed.`
+            : `Access to ${h} is refused: it resolves to a private or reserved address (add the hostname to marketplaces.allowPrivateHosts to allow an internal host).`);
+    }
+    return addrs;
+}

package/dist/net/safe-fetch.d.ts

@@ -0,0 +1,38 @@
+import { Agent } from "undici";
+import { type LookupFn, type NetPolicy } from "./public-address.js";
+/**
+ * `fetch` for URLs that come from a marketplace or an admin (spec §5.1):
+ * - https only; plain http only for a loopback host under `allowInsecureLoopback` (testing);
+ * - the host is resolved once by {@link resolvePublic} and the connection goes to the checked
+ *   addresses: a per-request undici `Agent` whose `connect.lookup` answers only those addresses,
+ *   so there is no second DNS lookup (no rebinding), while the Host header and TLS SNI keep the
+ *   original hostname;
+ * - with `policy.proxy` (`net.httpsProxy`), an https URL whose host is not loopback and not in
+ *   `noProxy` tunnels through the proxy (`proxy.ts`) instead: the host is not resolved locally
+ *   (the proxy resolves it and owns SSRF protection for the resolved address), but an IP-literal
+ *   host is still checked against the private ranges and `allowPrivateHosts`;
+ * - redirects are never followed: a 3xx (other than 304) is {@link NetDeniedError} `net.redirect`;
+ * - with `maxBytes`, a declared or streamed body over the limit is {@link NetBodyTooLargeError}.
+ */
+/** The response body is larger than `maxBytes`. */
+export declare class NetBodyTooLargeError extends Error {
+    readonly maxBytes: number;
+    constructor(maxBytes: number);
+}
+/**
+ * An undici dispatcher whose connections go only to `ips` (already checked), whatever the URL's
+ * hostname; the hostname still names the Host header and TLS SNI. One agent per download.
+ */
+export declare function pinnedAgent(ips: string[], tls?: {
+    ca?: string | string[];
+}): Agent;
+export declare function safeFetch(url: string, init: RequestInit & {
+    signal: AbortSignal;
+}, policy: NetPolicy, opts?: {
+    lookup?: LookupFn;
+    maxBytes?: number;
+    /** Tests only: wraps the pinned dispatcher (defaults to {@link pinnedAgent}). */
+    dispatcherFor?: (ips: string[]) => Agent;
+    /** Tests only: builds the proxy dispatcher (defaults to {@link proxyAgent}). */
+    proxyDispatcherFor?: (proxyUrl: string) => Agent;
+}): Promise<Response>;