buninu-browser 0.0.2

package/lib/log.js

@@ -0,0 +1,85 @@
+/**
+ * Optional diagnostic log file, enabled by the BUNINU_LOG environment
+ * variable, for frontends such as casty that swallow the browser's stderr.
+ *
+ *   BUNINU_LOG=1 (or "true")  append to ./buninu-browser.log in the working directory
+ *   BUNINU_LOG=/some/path     append to that file
+ *
+ * Only the controller writes the file. Renderers have no environment and
+ * cannot open files under seccomp, so their stdout and stderr are piped to
+ * the controller, which copies them into the log.
+ */
+import { appendFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { formatWithOptions } from "node:util";
+
+export const LOG_ENV = "BUNINU_LOG";
+export const DEFAULT_LOG_FILE = "buninu-browser.log";
+/** Tells a renderer that its output is logged, so it also echoes page console messages. */
+export const RENDERER_LOG_FLAG = "--buninu-log";
+
+let logPath = null;
+
+/** The log file BUNINU_LOG asks for, or null when logging is off. */
+export function logFileFromEnv(env = process.env, cwd = process.cwd()) {
+  const value = env[LOG_ENV]?.trim();
+  if (!value || ["0", "false", "off", "no"].includes(value.toLowerCase())) return null;
+  if (["1", "true", "on", "yes"].includes(value.toLowerCase())) return resolve(cwd, DEFAULT_LOG_FILE);
+  return resolve(cwd, value);
+}
+
+/** Starts logging to `path`: console output of this process is copied into the file. */
+export function installLog(path) {
+  if (!path || logPath) return;
+  logPath = path;
+  for (const level of ["log", "info", "warn", "error", "debug", "trace"]) {
+    const original = console[level].bind(console);
+    console[level] = (...args) => {
+      original(...args);
+      writeLog(level, formatWithOptions({ colors: false }, ...args));
+    };
+  }
+  writeLog("log", `started pid ${process.pid}, bun ${Bun.version}, cwd ${process.cwd()}, args ${JSON.stringify(Bun.argv.slice(2))}`);
+}
+
+export function logEnabled() {
+  return logPath !== null;
+}
+
+/** Appends text to the log, one timestamped line per line of text. */
+export function writeLog(source, text) {
+  if (!logPath) return;
+  const stamp = new Date().toISOString();
+  const lines = String(text).replace(/\n+$/, "").split("\n").map((line) => `${stamp} [${source}] ${line}`);
+  try {
+    appendFileSync(logPath, `${lines.join("\n")}\n`);
+  } catch {
+    // Logging must never break the browser.
+  }
+}
+
+/**
+ * Copies a child's output stream to `echo` and into the log, line by line.
+ * @param {ReadableStream<Uint8Array>} stream
+ * @param {string} source
+ * @param {(chunk: Uint8Array) => void} echo
+ */
+export async function pipeToLog(stream, source, echo) {
+  const decoder = new TextDecoder();
+  let pending = "";
+  try {
+    for await (const chunk of stream) {
+      echo(chunk);
+      pending += decoder.decode(chunk, { stream: true });
+      const end = pending.lastIndexOf("\n");
+      if (end >= 0) {
+        writeLog(source, pending.slice(0, end));
+        pending = pending.slice(end + 1);
+      }
+    }
+  } catch {
+    // The child went away mid-read.
+  }
+  pending += decoder.decode();
+  if (pending) writeLog(source, pending);
+}

package/lib/network/cookie-jar.js

@@ -0,0 +1,178 @@
+/**
+ * An RFC 6265 cookie store for the controller.
+ *
+ * Parsing is done here rather than with Bun.Cookie because Bun.Cookie fills
+ * in Path=/ and SameSite=Lax when they are absent, and RFC 6265 needs to know
+ * whether they were given (default-path, §5.1.4). Sites are approximated as
+ * the last two host labels because no Public Suffix List is bundled; IP
+ * addresses and single-label hosts are their own site.
+ */
+export class CookieJar {
+  #cookies = [];
+  #now;
+
+  constructor({ now = () => Date.now() } = {}) {
+    this.#now = now;
+  }
+
+  /** Stores Set-Cookie header values received for `url`. `fromScript` rejects HttpOnly (document.cookie). */
+  store(url, setCookies, { fromScript = false } = {}) {
+    const target = new URL(url);
+    for (const header of setCookies) {
+      const cookie = parseSetCookie(header, target, this.#now());
+      if (!cookie) continue;
+      if (fromScript && cookie.httpOnly) continue;
+      if (cookie.secure && target.protocol !== "https:" && !isLocalhost(target.hostname)) continue;
+      const existing = this.#cookies.findIndex((entry) =>
+        entry.name === cookie.name && entry.domain === cookie.domain && entry.path === cookie.path);
+      if (existing >= 0) {
+        // A script may not overwrite an HttpOnly cookie (RFC 6265bis §5.6).
+        if (fromScript && this.#cookies[existing].httpOnly) continue;
+        cookie.created = this.#cookies[existing].created;
+        this.#cookies.splice(existing, 1);
+      }
+      if (cookie.expires <= this.#now()) continue;
+      this.#cookies.push(cookie);
+    }
+  }
+
+  /**
+   * The Cookie header value for a request.
+   * @param {string} url request URL
+   * @param {{ site?: string | null, topLevelNavigation?: boolean, method?: string, includeHttpOnly?: boolean }} context
+   *   `site` is the site of the document making the request (null for browser-initiated navigations).
+   */
+  header(url, { site = null, topLevelNavigation = false, method = "GET", includeHttpOnly = true } = {}) {
+    const target = new URL(url);
+    const now = this.#now();
+    this.#cookies = this.#cookies.filter((cookie) => cookie.expires > now);
+    const crossSite = site !== null && siteOf(target) !== site;
+    const selected = this.#cookies.filter((cookie) => {
+      if (!domainMatches(cookie, target.hostname)) return false;
+      if (!pathMatches(cookie.path, target.pathname || "/")) return false;
+      if (cookie.secure && target.protocol !== "https:" && !isLocalhost(target.hostname)) return false;
+      if (!includeHttpOnly && cookie.httpOnly) return false;
+      if (crossSite) {
+        if (cookie.sameSite === "strict") return false;
+        const safeMethod = ["GET", "HEAD"].includes(method.toUpperCase());
+        if (cookie.sameSite !== "none" && !(topLevelNavigation && safeMethod)) return false;
+      }
+      return true;
+    });
+    // Longer paths first, then earlier creation (§5.4 step 2).
+    selected.sort((left, right) => right.path.length - left.path.length || left.created - right.created);
+    return selected.map((cookie) => `${cookie.name}=${cookie.value}`).join("; ");
+  }
+
+  /** document.cookie for a document URL: same-site, non-HttpOnly. */
+  documentCookie(url) {
+    return this.header(url, { includeHttpOnly: false });
+  }
+
+  get size() {
+    return this.#cookies.length;
+  }
+}
+
+/** Site of a URL: scheme plus registrable-domain approximation. */
+export function siteOf(url) {
+  const target = typeof url === "string" ? new URL(url) : url;
+  if (target.protocol !== "http:" && target.protocol !== "https:") return `${target.protocol}opaque`;
+  const host = target.hostname;
+  if (/^[\d.]+$/.test(host) || host.includes(":") || !host.includes(".")) return `${target.protocol}//${host}`;
+  return `${target.protocol}//${host.split(".").slice(-2).join(".")}`;
+}
+
+function parseSetCookie(header, url, now) {
+  const [pair, ...attributes] = String(header).split(";");
+  const equals = pair.indexOf("=");
+  if (equals < 0) return null;
+  const name = pair.slice(0, equals).trim();
+  const value = pair.slice(equals + 1).trim();
+  if (!name) return null;
+  const cookie = {
+    name,
+    value,
+    domain: url.hostname.toLowerCase(),
+    hostOnly: true,
+    path: defaultPath(url),
+    expires: Infinity,
+    secure: false,
+    httpOnly: false,
+    sameSite: "lax",
+    created: now,
+  };
+  let maxAge = null;
+  for (const attribute of attributes) {
+    const index = attribute.indexOf("=");
+    const key = (index < 0 ? attribute : attribute.slice(0, index)).trim().toLowerCase();
+    const argument = index < 0 ? "" : attribute.slice(index + 1).trim();
+    switch (key) {
+      case "expires": {
+        const time = Date.parse(argument);
+        if (Number.isFinite(time)) cookie.expires = time;
+        break;
+      }
+      case "max-age":
+        if (/^-?\d+$/.test(argument)) maxAge = Number(argument);
+        break;
+      case "domain": {
+        const domain = argument.replace(/^\./, "").toLowerCase();
+        if (!domain) break;
+        // A cookie may only be set for the request host or a parent domain.
+        if (!hostMatchesDomain(url.hostname.toLowerCase(), domain)) return null;
+        cookie.domain = domain;
+        cookie.hostOnly = false;
+        break;
+      }
+      case "path":
+        if (argument.startsWith("/")) cookie.path = argument;
+        break;
+      case "secure":
+        cookie.secure = true;
+        break;
+      case "httponly":
+        cookie.httpOnly = true;
+        break;
+      case "samesite": {
+        const mode = argument.toLowerCase();
+        if (["strict", "lax", "none"].includes(mode)) cookie.sameSite = mode;
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  if (maxAge !== null) cookie.expires = maxAge <= 0 ? -Infinity : now + maxAge * 1000;
+  // SameSite=None requires Secure.
+  if (cookie.sameSite === "none" && !cookie.secure) cookie.sameSite = "lax";
+  return cookie;
+}
+
+/** RFC 6265 §5.1.4 default-path: the request path up to (not including) its last "/". */
+function defaultPath(url) {
+  const path = url.pathname || "/";
+  if (!path.startsWith("/")) return "/";
+  const last = path.lastIndexOf("/");
+  return last <= 0 ? "/" : path.slice(0, last);
+}
+
+function hostMatchesDomain(host, domain) {
+  return host === domain || (host.endsWith(`.${domain}`) && !/^[\d.]+$/.test(host));
+}
+
+function domainMatches(cookie, host) {
+  const hostname = host.toLowerCase();
+  return cookie.hostOnly ? hostname === cookie.domain : hostMatchesDomain(hostname, cookie.domain);
+}
+
+/** RFC 6265 §5.1.4 path-match. */
+function pathMatches(cookiePath, requestPath) {
+  if (requestPath === cookiePath) return true;
+  if (!requestPath.startsWith(cookiePath)) return false;
+  return cookiePath.endsWith("/") || requestPath[cookiePath.length] === "/";
+}
+
+function isLocalhost(host) {
+  return host === "localhost" || host === "127.0.0.1" || host === "[::1]";
+}

package/lib/network/network-service.js

@@ -0,0 +1,268 @@
+/**
+ * The controller's network service: every request a page causes goes through
+ * here, so cookies, CORS and redirects are decided in the trusted process.
+ *
+ * - Documents: top-level navigations (cookies with SameSite=Lax allowed).
+ * - Subresources: stylesheets, images and classic scripts (no-cors mode).
+ * - Page fetches: fetch()/XMLHttpRequest from page scripts, under the Fetch
+ *   standard's CORS protocol, including preflight requests.
+ *
+ * The requesting document's URL is always the controller's own record, never
+ * something the renderer claims.
+ */
+import { CookieJar, siteOf } from "./cookie-jar.js";
+import { fetchResolved, HostResolver } from "./resolver.js";
+
+const MAX_REDIRECTS = 20;
+const MAX_BODY_BYTES = 64 * 1024 * 1024;
+const SIMPLE_METHODS = new Set(["GET", "HEAD", "POST"]);
+const FORBIDDEN_METHODS = new Set(["CONNECT", "TRACE", "TRACK"]);
+// Fetch §2.2.2 CORS-safelisted request headers (value checks simplified).
+const SAFELISTED_REQUEST_HEADERS = new Set(["accept", "accept-language", "content-language", "content-type", "range"]);
+const SIMPLE_CONTENT_TYPES = new Set(["application/x-www-form-urlencoded", "multipart/form-data", "text/plain"]);
+// Headers a page may not set (Fetch §2.2.2 forbidden request headers).
+const FORBIDDEN_REQUEST_HEADERS = new Set([
+  "accept-charset", "accept-encoding", "access-control-request-headers", "access-control-request-method",
+  "connection", "content-length", "cookie", "cookie2", "date", "dnt", "expect", "host", "keep-alive",
+  "origin", "referer", "set-cookie", "te", "trailer", "transfer-encoding", "upgrade", "via",
+]);
+const SAFELISTED_RESPONSE_HEADERS = new Set([
+  "cache-control", "content-language", "content-length", "content-type", "expires", "last-modified", "pragma",
+]);
+
+export class NetworkService {
+  #fetch;
+  #resolver;
+  #cookies;
+  #userAgent;
+
+  /**
+   * `resolver` looks host names up itself (see resolver.js); it is on for the
+   * real network and off when a test supplies its own `fetch`.
+   */
+  constructor({
+    fetch: fetchImpl = fetch, cookies = new CookieJar(), userAgent = null,
+    resolver = fetchImpl === globalThis.fetch ? new HostResolver() : null,
+  } = {}) {
+    this.#fetch = fetchImpl;
+    this.#resolver = resolver;
+    this.#cookies = cookies;
+    this.#userAgent = userAgent;
+  }
+
+  get cookies() {
+    return this.#cookies;
+  }
+
+  set userAgent(value) {
+    this.#userAgent = typeof value === "string" && value ? value : null;
+  }
+
+  /** A top-level document load. */
+  async navigate(url) {
+    return this.#send({ url, method: "GET", headers: [], body: null }, {
+      credentials: "include", site: null, topLevelNavigation: true,
+    });
+  }
+
+  /** A subresource the renderer needs to render (no-cors, credentials included). */
+  async subresource(url, documentUrl) {
+    return this.#send({ url, method: "GET", headers: [], body: null }, {
+      credentials: "include", site: siteOf(documentUrl),
+    });
+  }
+
+  /**
+   * A WebSocket opened by page script, using Bun's WebSocket: the handshake
+   * carries the document's Origin, the target's cookies (as for an https/http
+   * request to the same host) and the user agent.
+   * @param {string} url ws: or wss:
+   * @param {string[]} protocols
+   * @param {string} documentUrl
+   */
+  webSocket(url, protocols, documentUrl) {
+    const target = new URL(url);
+    if (target.protocol !== "ws:" && target.protocol !== "wss:") throw new TypeError(`blocked WebSocket scheme ${target.protocol}`);
+    // Always an Origin, "null" for opaque ones (data:, about:blank), as
+    // browsers send it: servers such as the CDP endpoint accept handshakes
+    // without one (non-browser clients) and must see that a page is asking.
+    const headers = { Origin: new URL(documentUrl).origin };
+    const http = new URL(target.href.replace(/^ws/, "http"));
+    const cookie = this.#cookies.header(http.href, { site: siteOf(documentUrl) });
+    if (cookie) headers.Cookie = cookie;
+    if (this.#userAgent) headers["User-Agent"] = this.#userAgent;
+    return new WebSocket(target.href, { headers, protocols });
+  }
+
+  /** document.cookie for a document. */
+  documentCookie(documentUrl) {
+    return this.#cookies.documentCookie(documentUrl);
+  }
+
+  /** document.cookie = "..." from a page. */
+  setDocumentCookie(documentUrl, value) {
+    this.#cookies.store(documentUrl, [String(value)], { fromScript: true });
+  }
+
+  /**
+   * fetch()/XMLHttpRequest from page script.
+   * @param {{ url: string, method?: string, headers?: [string, string][], body?: Uint8Array | null,
+   *   mode?: "cors" | "no-cors" | "same-origin", credentials?: "omit" | "same-origin" | "include",
+   *   redirect?: "follow" | "error" | "manual" }} request
+   * @param {string} documentUrl the requesting document (controller's record)
+   */
+  async pageFetch(request, documentUrl) {
+    const origin = new URL(documentUrl).origin;
+    const url = new URL(request.url);
+    const method = String(request.method ?? "GET").toUpperCase();
+    const mode = request.mode ?? "cors";
+    const credentials = request.credentials ?? "same-origin";
+    if (FORBIDDEN_METHODS.has(method)) throw new TypeError(`Forbidden method ${method}`);
+    if (!["http:", "https:"].includes(url.protocol)) throw new TypeError(`Fetch API cannot load ${url.protocol} URLs`);
+    const headers = (request.headers ?? [])
+      .map(([name, value]) => [String(name).toLowerCase(), String(value)])
+      .filter(([name]) => !FORBIDDEN_REQUEST_HEADERS.has(name) && !name.startsWith("proxy-") && !name.startsWith("sec-"));
+    const sameOrigin = url.origin === origin;
+    if (mode === "same-origin" && !sameOrigin) throw new TypeError("Request was blocked: mode is same-origin");
+    if (mode === "no-cors" && !SIMPLE_METHODS.has(method)) throw new TypeError(`${method} is not allowed in no-cors mode`);
+
+    const sendCredentials = credentials === "include" || (credentials === "same-origin" && sameOrigin);
+    const context = { credentials: sendCredentials ? "include" : "omit", site: siteOf(documentUrl), origin };
+
+    if (sameOrigin) {
+      return this.#send({ url: url.href, method, headers, body: request.body ?? null }, context, {
+        redirect: request.redirect ?? "follow", corsOrigin: null,
+      });
+    }
+    if (mode === "no-cors") {
+      const response = await this.#send({ url: url.href, method, headers: headers.filter(isSafelistedHeader), body: request.body ?? null },
+        context, { redirect: "follow", corsOrigin: null });
+      return { ...response, type: "opaque", status: 0, statusText: "", url: "", headers: [], body: new Uint8Array(0), redirected: false };
+    }
+    // CORS: preflight unless the request is "simple" (Fetch §4.8).
+    const needsPreflight = !SIMPLE_METHODS.has(method) || headers.some((header) => !isSafelistedHeader(header));
+    if (needsPreflight) await this.#preflight(url, method, headers, origin, context);
+    const response = await this.#send({ url: url.href, method, headers, body: request.body ?? null }, context, {
+      redirect: request.redirect ?? "follow", corsOrigin: origin,
+    });
+    const allowed = corsAllowed(response.rawHeaders, origin, context.credentials === "include");
+    if (!allowed) throw new TypeError(`CORS: ${url.href} did not allow origin ${origin}`);
+    const exposed = new Set((header(response.rawHeaders, "access-control-expose-headers") ?? "")
+      .split(",").map((name) => name.trim().toLowerCase()).filter(Boolean));
+    const exposeAll = exposed.has("*") && context.credentials !== "include";
+    return {
+      ...response,
+      type: "cors",
+      headers: response.headers.filter(([name]) => SAFELISTED_RESPONSE_HEADERS.has(name) || exposed.has(name) || exposeAll),
+    };
+  }
+
+  async #preflight(url, method, headers, origin, context) {
+    const requestHeaders = headers.filter((entry) => !isSafelistedHeader(entry)).map(([name]) => name).sort();
+    const response = await this.#request(url.href, {
+      method: "OPTIONS",
+      redirect: "manual",
+      headers: {
+        origin,
+        "access-control-request-method": method,
+        ...(requestHeaders.length ? { "access-control-request-headers": requestHeaders.join(",") } : {}),
+        ...(this.#userAgent ? { "user-agent": this.#userAgent } : {}),
+      },
+    });
+    await response.arrayBuffer().catch(() => {});
+    const raw = [...response.headers];
+    if (response.status < 200 || response.status > 299 || !corsAllowed(raw, origin, context.credentials === "include")) {
+      throw new TypeError(`CORS preflight for ${url.href} was rejected`);
+    }
+    const allowMethods = (header(raw, "access-control-allow-methods") ?? "").split(",").map((value) => value.trim().toUpperCase());
+    const allowHeaders = (header(raw, "access-control-allow-headers") ?? "").split(",").map((value) => value.trim().toLowerCase());
+    const wildcard = context.credentials !== "include";
+    if (!SIMPLE_METHODS.has(method) && !allowMethods.includes(method) && !(wildcard && allowMethods.includes("*"))) {
+      throw new TypeError(`CORS preflight for ${url.href} does not allow method ${method}`);
+    }
+    for (const name of requestHeaders) {
+      if (!allowHeaders.includes(name) && !(wildcard && allowHeaders.includes("*"))) {
+        throw new TypeError(`CORS preflight for ${url.href} does not allow header ${name}`);
+      }
+    }
+  }
+
+  #request(url, init) {
+    return this.#resolver ? fetchResolved(this.#fetch, this.#resolver, url, init) : this.#fetch(url, init);
+  }
+
+  /** Sends a request, following redirects by hand so cookies apply to every hop. */
+  async #send(request, context, { redirect = "follow", corsOrigin = null } = {}) {
+    let { url, method, body } = request;
+    const baseHeaders = request.headers;
+    let redirected = false;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+      const headers = new Headers(baseHeaders);
+      if (this.#userAgent) headers.set("user-agent", this.#userAgent);
+      if (corsOrigin) headers.set("origin", corsOrigin);
+      if (context.credentials === "include") {
+        const cookie = this.#cookies.header(url, {
+          site: context.site, topLevelNavigation: Boolean(context.topLevelNavigation), method,
+        });
+        if (cookie) headers.set("cookie", cookie);
+      }
+      const response = await this.#request(url, { method, headers, body, redirect: "manual" });
+      if (context.credentials === "include") this.#cookies.store(url, response.headers.getSetCookie?.() ?? []);
+      const location = response.headers.get("location");
+      if ([301, 302, 303, 307, 308].includes(response.status) && location) {
+        await response.arrayBuffer().catch(() => {});
+        if (redirect === "error") throw new TypeError("Redirect was not allowed");
+        if (redirect === "manual") return this.#result(response, url, redirected, "opaqueredirect");
+        const next = new URL(location, url);
+        if (!["http:", "https:"].includes(next.protocol)) throw new TypeError(`Redirect to ${next.protocol} is not allowed`);
+        if (response.status === 303 || ((response.status === 301 || response.status === 302) && method === "POST")) {
+          method = method === "HEAD" ? "HEAD" : "GET";
+          body = null;
+        }
+        url = next.href;
+        redirected = true;
+        continue;
+      }
+      return this.#result(response, url, redirected, "basic");
+    }
+    throw new TypeError("Too many redirects");
+  }
+
+  async #result(response, url, redirected, type) {
+    const buffer = new Uint8Array(await response.arrayBuffer());
+    if (buffer.byteLength > MAX_BODY_BYTES) throw new TypeError("Response body too large");
+    const rawHeaders = [...response.headers];
+    return {
+      ok: response.status >= 200 && response.status <= 299,
+      status: response.status,
+      statusText: response.statusText,
+      url,
+      redirected,
+      type,
+      rawHeaders,
+      // Set-Cookie never reaches pages (Fetch "forbidden response header name").
+      headers: rawHeaders.filter(([name]) => name !== "set-cookie" && name !== "set-cookie2"),
+      contentType: response.headers.get("content-type") ?? "",
+      body: buffer,
+    };
+  }
+}
+
+function isSafelistedHeader([name, value]) {
+  if (!SAFELISTED_REQUEST_HEADERS.has(name)) return false;
+  if (name === "content-type") return SIMPLE_CONTENT_TYPES.has(value.split(";")[0].trim().toLowerCase());
+  return value.length <= 128;
+}
+
+function header(rawHeaders, name) {
+  return rawHeaders.find(([key]) => key === name)?.[1] ?? null;
+}
+
+/** Fetch §4.9 CORS check. */
+function corsAllowed(rawHeaders, origin, withCredentials) {
+  const allowOrigin = header(rawHeaders, "access-control-allow-origin");
+  if (allowOrigin === null) return false;
+  if (allowOrigin === "*") return !withCredentials;
+  if (allowOrigin !== origin) return false;
+  return !withCredentials || header(rawHeaders, "access-control-allow-credentials") === "true";
+}

package/lib/network/resolver.js

@@ -0,0 +1,97 @@
+/**
+ * Host resolution for the controller's network service.
+ *
+ * glibc's getaddrinfo() for an unspecified family sends the A and AAAA
+ * queries at the same moment from one UDP socket. Some network paths (NAT
+ * and connection tracking, as on phones and in containers) drop one of two
+ * such packets, and the resolver then waits its full timeout, 5 seconds by
+ * default, before retrying. The usual cure is `options single-request-reopen`
+ * in /etc/resolv.conf, which a browser cannot count on.
+ *
+ * So each family is looked up on its own (one query per getaddrinfo call,
+ * each with its own socket), and requests connect to an address directly
+ * while keeping the host name for the Host header and for TLS (SNI and
+ * certificate verification). This also covers musl, which has no such option.
+ */
+import { lookup as systemLookup } from "node:dns/promises";
+import { isIP } from "node:net";
+
+const DEFAULT_TTL_MS = 60_000;
+// Errors that mean "this address did not answer": try the next one.
+const CONNECT_ERRORS = new Set([
+  "ECONNREFUSED", "ETIMEDOUT", "EHOSTUNREACH", "ENETUNREACH", "EADDRNOTAVAIL",
+  "ConnectionRefused", "FailedToOpenSocket", "NetworkUnreachable", "HostUnreachable", "ConnectionTimedOut",
+]);
+
+export class HostResolver {
+  #cache = new Map();
+  #lookup;
+  #ttl;
+  #now;
+
+  /**
+   * @param {{ lookup?: typeof systemLookup, ttl?: number, now?: () => number }} options
+   */
+  constructor({ lookup = systemLookup, ttl = DEFAULT_TTL_MS, now = () => Date.now() } = {}) {
+    this.#lookup = lookup;
+    this.#ttl = ttl;
+    this.#now = now;
+  }
+
+  /** Addresses for a host name, IPv4 first, then IPv6. */
+  addresses(hostname) {
+    const name = hostname.toLowerCase();
+    const cached = this.#cache.get(name);
+    if (cached && cached.expires > this.#now()) return cached.addresses;
+    const addresses = this.#resolve(name);
+    this.#cache.set(name, { addresses, expires: this.#now() + this.#ttl });
+    // A failed lookup is not remembered.
+    addresses.catch(() => {
+      if (this.#cache.get(name)?.addresses === addresses) this.#cache.delete(name);
+    });
+    return addresses;
+  }
+
+  async #resolve(name) {
+    const [v4, v6] = await Promise.allSettled([
+      this.#lookup(name, { family: 4, all: true }),
+      this.#lookup(name, { family: 6, all: true }),
+    ]);
+    const addresses = [
+      ...(v4.status === "fulfilled" ? v4.value : []),
+      ...(v6.status === "fulfilled" ? v6.value : []),
+    ].map(({ address, family }) => ({ address, family }));
+    if (!addresses.length) {
+      const error = new TypeError(`Unable to resolve ${name}`);
+      error.code = "ENOTFOUND";
+      throw error;
+    }
+    return addresses;
+  }
+}
+
+/**
+ * fetch() that connects to a resolved address, keeping the host name for the
+ * Host header and TLS. IP literals and non-HTTP URLs go to `fetchImpl` as is.
+ */
+export async function fetchResolved(fetchImpl, resolver, url, init = {}) {
+  const target = new URL(url);
+  const hostname = target.hostname.replace(/^\[(.*)\]$/, "$1");
+  if (!["http:", "https:"].includes(target.protocol) || isIP(hostname)) return fetchImpl(url, init);
+  const addresses = await resolver.addresses(hostname);
+  let lastError;
+  for (const { address, family } of addresses) {
+    const direct = new URL(target.href);
+    direct.hostname = family === 6 ? `[${address}]` : address;
+    const headers = new Headers(init.headers);
+    headers.set("host", target.host);
+    const tls = target.protocol === "https:" ? { ...init.tls, serverName: hostname } : init.tls;
+    try {
+      return await fetchImpl(direct.href, { ...init, headers, ...(tls ? { tls } : {}) });
+    } catch (error) {
+      if (!CONNECT_ERRORS.has(error?.code)) throw error;
+      lastError = error;
+    }
+  }
+  throw lastError;
+}