@fedify/vocab-runtime 2.4.5-dev.2462 → 2.4.5

package/src/pinners/bun.test.ts

@@ -0,0 +1,278 @@
+import { test } from "@fedify/fixture";
+import { deepStrictEqual, ok, rejects } from "node:assert";
+import { readFileSync } from "node:fs";
+import { createServer as createHttpsServer } from "node:https";
+import { issuePinGrant } from "../pin-grant.ts";
+import { createBunPinner } from "./bun.ts";
+import {
+  allowAll,
+  closeServer,
+  getLoopbackSupport,
+  ipv4,
+  ipv6,
+  isBun,
+  listen,
+  resolveTestdata,
+  runChild,
+  startCountingServer,
+  startRecordingProxy,
+  startRecordingServer,
+} from "./testdata/support.ts";
+
+// The behaviors that the Bun pinner shares with the other pinners are tested
+// in pinners.test.ts.
+
+test("createBunPinner() falls back to the next address for GET and HEAD", {
+  ignore: !isBun,
+}, async () => {
+  // Skipped where IPv6 is unavailable:
+  if (!(await getLoopbackSupport()).ipv6) return;
+  // The server listens only on 127.0.0.1, so the first address, ::1, refuses
+  // the connection:
+  const { server, port, requests } = await startRecordingServer();
+  try {
+    const pinner = createBunPinner(allowAll);
+    const url = new URL(`http://pinned-host.invalid:${port}/`);
+    const grant = issuePinGrant(url, [ipv6("::1"), ipv4("127.0.0.1")]);
+    const response = await pinner.fetch(grant, new Request(url));
+    deepStrictEqual(await response.text(), "pinned");
+    const head = await pinner.fetch(
+      grant,
+      new Request(url, { method: "HEAD" }),
+    );
+    deepStrictEqual(head.status, 200);
+    deepStrictEqual(
+      requests.map(({ method, localAddress }) => [method, localAddress]),
+      [["GET", "127.0.0.1"], ["HEAD", "127.0.0.1"]],
+    );
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test("createBunPinner() does not fall back for POST", {
+  ignore: !isBun,
+}, async () => {
+  // Skipped where IPv6 is unavailable:
+  if (!(await getLoopbackSupport()).ipv6) return;
+  // The first address, ::1, refuses the connection, and the second one
+  // would reach the server:
+  const { server, port, requests } = await startRecordingServer();
+  try {
+    const pinner = createBunPinner(allowAll);
+    const url = new URL(`http://pinned-host.invalid:${port}/`);
+    const grant = issuePinGrant(url, [ipv6("::1"), ipv4("127.0.0.1")]);
+    await rejects(() =>
+      pinner.fetch(
+        grant,
+        new Request(url, { method: "POST", body: "payload" }),
+      )
+    );
+    deepStrictEqual(requests, []);
+  } finally {
+    await closeServer(server);
+  }
+});
+
+interface ProxyChildOutput {
+  readonly version: string;
+  readonly http: { status?: number; body?: string; error?: string };
+  readonly https: { status?: number; body?: string; error?: string };
+  readonly control: { status?: number; body?: string; error?: string };
+  readonly warnings: readonly unknown[];
+}
+
+function runProxyChild(
+  proxyEnv: Record<string, string>,
+  httpPort: number,
+  httpsPort: number,
+): Promise<ProxyChildOutput> {
+  return runChild(
+    resolveTestdata("proxy-child.ts", import.meta.url),
+    [String(httpPort), String(httpsPort)],
+    proxyEnv,
+  );
+}
+
+interface BunGlobal {
+  readonly version: string;
+  readonly semver: { satisfies(version: string, range: string): boolean };
+}
+
+function getBun(): BunGlobal {
+  return (globalThis as unknown as { Bun: BunGlobal }).Bun;
+}
+
+/**
+ * Whether the current Bun refuses pinned requests to HTTPS servers on
+ * non-default ports, since it cannot verify their certificates against
+ * the original hostname.
+ */
+function refusesNonDefaultHttpsPorts(): boolean {
+  const bun = getBun();
+  return bun.semver.satisfies(bun.version, "<1.3.11");
+}
+
+test("createBunPinner() bypasses environment proxies", {
+  ignore: !isBun,
+}, async (t) => {
+  const bun = getBun();
+  const honorsProxyFalse = bun.semver.satisfies(bun.version, ">=1.4.3");
+  const refusesHttps = refusesNonDefaultHttpsPorts();
+  for (
+    const names of [
+      ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY"],
+      ["ALL_PROXY"],
+    ] as const
+  ) {
+    await t.step(names.join(", "), async () => {
+      const proxy = await startRecordingProxy();
+      // The HTTP origin server:
+      const origin = await startRecordingServer();
+      // The HTTPS target, which only counts connections since it has no
+      // certificate:
+      const tls = await startCountingServer();
+      try {
+        const proxyUrl = `http://127.0.0.1:${proxy.port}`;
+        const output = await runProxyChild(
+          Object.fromEntries(names.map((name) => [name, proxyUrl])),
+          origin.port,
+          tls.port,
+        );
+        const targets = JSON.stringify(proxy.targets);
+        deepStrictEqual(output.version, bun.version);
+        // The pinned hostname never reaches the proxy as a target:
+        ok(
+          proxy.targets.every((target) => !target.includes("pinned-host")),
+          targets,
+        );
+        // The control request without proxy: false shows whether the proxy
+        // is in effect.  Older Bun versions (e.g., 1.2.22) do not read
+        // ALL_PROXY, so it is not in effect with ALL_PROXY alone there:
+        const proxyInEffect = output.control.body === "via-proxy";
+        if (names.length > 1 || honorsProxyFalse || proxyInEffect) {
+          deepStrictEqual(output.control, { status: 200, body: "via-proxy" });
+          ok(
+            proxy.targets.includes(
+              `GET http://127.0.0.1:${origin.port}/control`,
+            ),
+            targets,
+          );
+        } else {
+          deepStrictEqual(output.control, { status: 200, body: "pinned" });
+        }
+        const pinnedTargets = proxy.targets.filter((target) =>
+          !target.endsWith("/control")
+        );
+        if (honorsProxyFalse || !proxyInEffect) {
+          // Pinned requests connect directly to the pinned address:
+          deepStrictEqual(pinnedTargets, [], targets);
+          deepStrictEqual(output.http, { status: 200, body: "pinned" });
+          deepStrictEqual(
+            origin.requests
+              .filter(({ url }) => url === "/pinned")
+              .map(({ host }) => host),
+            [`pinned-host.invalid:${origin.port}`],
+          );
+          deepStrictEqual(tls.counter.connections, refusesHttps ? 0 : 1);
+        } else {
+          // Older Bun versions ignore proxy: false, so pinned requests go
+          // through the proxy, but with the pinned address as the target:
+          deepStrictEqual(pinnedTargets, [
+            `GET http://127.0.0.1:${origin.port}/pinned`,
+            ...(refusesHttps ? [] : [`CONNECT 127.0.0.1:${tls.port}`]),
+          ]);
+          deepStrictEqual(output.http, { status: 200, body: "via-proxy" });
+          deepStrictEqual(origin.requests, []);
+          deepStrictEqual(tls.counter.connections, 0);
+        }
+        // The HTTPS target has no certificate, and Bun versions before 1.3.11
+        // refuse it before connecting since it is on a non-default port:
+        ok(
+          refusesHttps
+            ? output.https.error?.startsWith("TypeError")
+            : output.https.error != null,
+          JSON.stringify(output.https),
+        );
+        // Older Bun versions warn once whenever a proxy variable is set:
+        deepStrictEqual(output.warnings.length, honorsProxyFalse ? 0 : 1);
+      } finally {
+        await closeServer(proxy.server);
+        await closeServer(origin.server);
+        await closeServer(tls.server);
+      }
+    });
+  }
+});
+
+type TlsChildResult =
+  | { readonly case: string; readonly status: number; readonly body: string }
+  | { readonly case: string; readonly error: string };
+
+interface TlsChildOutput {
+  readonly version: string;
+  readonly results: readonly TlsChildResult[];
+}
+
+test("createBunPinner() verifies certificates on non-default ports", {
+  ignore: !isBun,
+}, async () => {
+  const bun = getBun();
+  // Bun versions before 1.3.11 cannot verify certificates against
+  // the original hostname on non-default ports, so the pinner refuses such
+  // requests there.  (A custom checkServerIdentity fails only after these
+  // versions have sent the whole request, which the server would receive.)
+  const refuses = refusesNonDefaultHttpsPorts();
+  const certPath = resolveTestdata("tls-cert.pem", import.meta.url);
+  const hosts: string[] = [];
+  const server = createHttpsServer({
+    cert: readFileSync(certPath),
+    key: readFileSync(resolveTestdata("tls-key.pem", import.meta.url)),
+  }, (req, res) => {
+    hosts.push(req.headers.host ?? "");
+    res.end(req.headers.host);
+  });
+  const port = await listen(server);
+  try {
+    // tls-cert.pem is self-signed for pinned-host.invalid and
+    // alternate-host.invalid, and is trusted only by the child process:
+    const output = await runChild<TlsChildOutput>(
+      resolveTestdata("tls-child.ts", import.meta.url),
+      [String(port)],
+      { NODE_EXTRA_CA_CERTS: certPath },
+    );
+    deepStrictEqual(output.version, bun.version);
+    const json = JSON.stringify(output.results);
+    if (refuses) {
+      ok(
+        output.results.every((result) =>
+          "error" in result && result.error.startsWith("TypeError")
+        ),
+        json,
+      );
+      deepStrictEqual(hosts, []);
+      return;
+    }
+    deepStrictEqual(output.results, [
+      { case: "pinned", status: 200, body: `pinned-host.invalid:${port}` },
+      // A connection that failed the check must not be reused either:
+      { case: "unlisted", error: "ERR_TLS_CERT_ALTNAME_INVALID" },
+      { case: "unlisted-again", error: "ERR_TLS_CERT_ALTNAME_INVALID" },
+      {
+        case: "alternate",
+        status: 200,
+        body: `alternate-host.invalid:${port}`,
+      },
+      { case: "signals", status: 200, body: `pinned-host.invalid:${port}` },
+    ], json);
+    // No request reached the server for the hostname the certificate does
+    // not cover:
+    deepStrictEqual(hosts, [
+      `pinned-host.invalid:${port}`,
+      `alternate-host.invalid:${port}`,
+      `pinned-host.invalid:${port}`,
+    ]);
+  } finally {
+    await closeServer(server);
+  }
+});

package/src/pinners/bun.ts

@@ -0,0 +1,223 @@
+import { getLogger } from "@logtape/logtape";
+import { isIP } from "node:net";
+import { type PinGrant, redeemPinGrant } from "../pin-grant.ts";
+import type { ResolvedAddress } from "../url.ts";
+import type { ConnectionPinner, ConnectionPinnerOptions } from "./types.ts";
+
+const logger = getLogger(["fedify", "runtime", "fetch"]);
+
+/**
+ * The first Bun version that honors `proxy: false` when proxy environment
+ * variables are set at startup.  Earlier versions send pinned requests
+ * through the proxy, with the validated IP address as the target.
+ */
+const PROXY_FALSE_MIN_VERSION = "1.4.3";
+
+const PROXY_VARIABLES = [
+  "HTTP_PROXY",
+  "http_proxy",
+  "HTTPS_PROXY",
+  "https_proxy",
+  "ALL_PROXY",
+  "all_proxy",
+] as const;
+
+// Transport errors that Bun's fetch() raises before a response arrives.
+// Only GET and HEAD requests fall back to the next address on these.
+const FALLBACK_ERROR_CODES: ReadonlySet<string> = new Set([
+  "ConnectionRefused",
+  "ECONNREFUSED",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ETIMEDOUT",
+]);
+
+/**
+ * Bun versions before 1.3.11 verify the server certificate against the `Host`
+ * header, including a non-default port, instead of `tls.serverName`, so
+ * pinned requests to HTTPS servers on non-default ports always fail the check
+ * there.  A custom `checkServerIdentity` cannot stand in for it: these
+ * versions send the whole request before a failing custom check aborts it
+ * (and 1.3.10 even reuses the connection for the next request), so such
+ * requests are refused instead.
+ */
+const HOST_HEADER_IDENTITY_RANGE = "<1.3.11";
+
+interface BunGlobal {
+  readonly version: string;
+  readonly semver: { satisfies(version: string, range: string): boolean };
+}
+
+interface BunFetchInit extends RequestInit {
+  tls?: { serverName?: string };
+  proxy?: string | false;
+}
+
+/**
+ * Creates a pinner for Bun.  Every request is sent to an IP literal URL with
+ * the original `Host` header, `tls.serverName` set to the original hostname
+ * (so that the certificate is still verified against it), and `proxy: false`.
+ *
+ * GET and HEAD requests fall back to the next address on transport errors
+ * raised before a response arrives.  Other methods use only the first
+ * address, since a transport error does not guarantee that the request did
+ * not reach the server, and retrying it could deliver an activity twice.
+ * Together with the transport retries of `doubleKnock()`, a GET request is
+ * attempted at most twice per address.  Note that Bun 1.4 also reports
+ * a connection reset after the request was sent as a `TypeError`, so GET and
+ * HEAD requests may be repeated against the next address in that case, which
+ * is acceptable for these idempotent methods.
+ *
+ * Bun versions before 1.3.11 verify certificates against the `Host` header,
+ * which includes a non-default port, and cannot safely check them against
+ * the original hostname in any other way, so requests to HTTPS servers on
+ * non-default ports fail there with a `TypeError` before connecting.
+ *
+ * Bun versions before 1.4.3 ignore `proxy: false` when proxy environment
+ * variables are set, so requests go through the proxy with the validated IP
+ * address as the target.  In that case a warning is logged once.
+ * @param options The pinner options.
+ * @returns The pinner.
+ */
+export function createBunPinner(
+  { verifyAddress }: ConnectionPinnerOptions,
+): ConnectionPinner {
+  // Older Bun versions read proxy variables only at startup, so they are
+  // checked once when the pinner is created:
+  let proxyWarningPending = ignoresProxyFalse() && hasProxyVariables();
+  return {
+    supports(url: URL): boolean {
+      return url.protocol === "http:" || url.protocol === "https:";
+    },
+
+    async fetch(
+      grant: PinGrant,
+      request: Request,
+      signal?: AbortSignal,
+    ): Promise<Response> {
+      const url = new URL(request.url);
+      const { hostname, addresses } = redeemPinGrant(grant, url);
+      if (proxyWarningPending) {
+        proxyWarningPending = false;
+        logger.warn(
+          "Bun {version} ignores proxy: false while proxy environment " +
+            "variables are set, so outbound requests go through the proxy " +
+            "instead of connecting directly to the validated addresses.  " +
+            "Upgrade to Bun {minVersion} or later, or unset the proxy " +
+            "environment variables; see {url}.",
+          {
+            version: getBun()?.version,
+            minVersion: PROXY_FALSE_MIN_VERSION,
+            url: "https://fedify.dev/manual/deploy#bun-behind-an-http-proxy",
+          },
+        );
+      }
+      const fallback = request.method === "GET" || request.method === "HEAD";
+      const candidates = fallback ? addresses : addresses.slice(0, 1);
+      const body = request.body == null ? null : await request.arrayBuffer();
+      let lastError: unknown = new TypeError(
+        `No address to connect to for ${url.host}.`,
+      );
+      for (const address of candidates) {
+        throwIfAborted(signal, request.signal);
+        // Never fall back past an address that fails the check:
+        verifyAddress(address);
+        const headers = new Headers(request.headers);
+        headers.set("Host", url.host);
+        const init: BunFetchInit = {
+          method: request.method,
+          headers,
+          body,
+          redirect: "manual",
+          signal: signal == null || signal === request.signal
+            ? request.signal
+            : anySignal(signal, request.signal),
+          proxy: false,
+        };
+        if (url.protocol === "https:") {
+          init.tls = getTlsOptions(url, hostname);
+        }
+        try {
+          return await fetch(toAddressUrl(url, address), init);
+        } catch (error) {
+          throwIfAborted(signal, request.signal);
+          if (!fallback || !isFallbackError(error)) throw error;
+          lastError = error;
+        }
+      }
+      throw lastError;
+    },
+
+    release(): void {
+    },
+  };
+}
+
+function getTlsOptions(url: URL, hostname: string): BunFetchInit["tls"] {
+  const bun = getBun();
+  if (
+    url.port !== "" && bun != null &&
+    bun.semver.satisfies(bun.version, HOST_HEADER_IDENTITY_RANGE)
+  ) {
+    throw new TypeError(
+      `Bun ${bun.version} cannot verify the certificate of ${url.host} ` +
+        "when connecting to a validated address; upgrade to Bun 1.3.11 or " +
+        "later to fetch from HTTPS servers on non-default ports.",
+    );
+  }
+  return isIP(hostname) === 0 ? { serverName: hostname } : {};
+}
+
+/**
+ * Combines two signals without `AbortSignal.any()`, which Bun 1.1.0 lacks.
+ */
+function anySignal(a: AbortSignal, b: AbortSignal): AbortSignal {
+  if (a.aborted) return a;
+  if (b.aborted) return b;
+  const controller = new AbortController();
+  const abort = (event: Event) => {
+    controller.abort((event.target as AbortSignal).reason);
+    a.removeEventListener("abort", abort);
+    b.removeEventListener("abort", abort);
+  };
+  a.addEventListener("abort", abort);
+  b.addEventListener("abort", abort);
+  return controller.signal;
+}
+
+function toAddressUrl(url: URL, address: ResolvedAddress): URL {
+  const result = new URL(url);
+  result.hostname = address.family === 6
+    ? `[${address.address}]`
+    : address.address;
+  return result;
+}
+
+function isFallbackError(error: unknown): boolean {
+  if (error instanceof Error && error.name === "AbortError") return false;
+  if (error instanceof TypeError) return true;
+  const code = (error as { code?: unknown } | null)?.code;
+  return typeof code === "string" && FALLBACK_ERROR_CODES.has(code);
+}
+
+function throwIfAborted(...signals: (AbortSignal | undefined)[]): void {
+  for (const signal of signals) signal?.throwIfAborted();
+}
+
+function getBun(): BunGlobal | undefined {
+  return (globalThis as { Bun?: BunGlobal }).Bun;
+}
+
+function ignoresProxyFalse(): boolean {
+  const bun = getBun();
+  if (bun == null) return false;
+  return !bun.semver.satisfies(bun.version, `>=${PROXY_FALSE_MIN_VERSION}`);
+}
+
+function hasProxyVariables(): boolean {
+  const env = (globalThis as {
+    process?: { env?: Record<string, string | undefined> };
+  }).process?.env;
+  if (env == null) return false;
+  return PROXY_VARIABLES.some((name) => (env[name] ?? "") !== "");
+}

package/src/pinners/mod.ts

@@ -0,0 +1,59 @@
+import { assertPublicAddress } from "../url.ts";
+import { createBunPinner } from "./bun.ts";
+import { createNodePinner } from "./node.ts";
+import type { ConnectionPinner } from "./types.ts";
+
+export type { ConnectionPinner, ConnectionPinnerOptions } from "./types.ts";
+
+/**
+ * The JavaScript runtimes that are told apart for connection pinning.
+ */
+export type Runtime = "cfworkers" | "deno" | "bun" | "node" | "other";
+
+/**
+ * Detects the current runtime.  Cloudflare Workers is checked first, since
+ * `process` can exist there with `nodejs_compat`, and Deno and Bun before
+ * Node.js, since both provide `process.versions.node`.
+ * @returns The current runtime.
+ */
+export function detectRuntime(): Runtime {
+  const g = globalThis as {
+    navigator?: { userAgent?: string };
+    process?: { versions?: { node?: string } };
+  };
+  if (g.navigator?.userAgent === "Cloudflare-Workers") return "cfworkers";
+  if ("Deno" in globalThis) return "deno";
+  if ("Bun" in globalThis) return "bun";
+  if (g.process?.versions?.node != null) return "node";
+  return "other";
+}
+
+let runtimePinner: Promise<ConnectionPinner | null> | undefined;
+
+/**
+ * Gets the production pinner of the current runtime, which rejects
+ * non-public addresses right before connecting.  Deno and Cloudflare Workers
+ * have no pinner.
+ * @returns The pinner, or `null` if the runtime has none.
+ */
+export function getRuntimePinner(): Promise<ConnectionPinner | null> {
+  runtimePinner ??= createRuntimePinner(detectRuntime());
+  return runtimePinner;
+}
+
+async function createRuntimePinner(
+  runtime: Runtime,
+): Promise<ConnectionPinner | null> {
+  switch (runtime) {
+    case "bun":
+      return createBunPinner({ verifyAddress: assertPublicAddress });
+    case "node":
+      // The npm undici package is loaded only on Node.js:
+      return createNodePinner({
+        verifyAddress: assertPublicAddress,
+        undici: await import("undici"),
+      });
+    default:
+      return null;
+  }
+}