@reckona/mreact-router 0.0.203 → 0.0.205

package/src/metadata.ts

@@ -4,10 +4,10 @@ import {
 } from "@reckona/mreact-shared/html-escape";
 import {
   isDangerousHtmlAttribute,
+  isUnsafeMetaRefreshContent,
   isUnsafeUrlAttribute,
 } from "@reckona/mreact-shared/url-safety";
 import { contentSecurityPolicy } from "./csp.js";
-import type { AppFileConvention } from "./file-conventions.js";
 import type { AppRoute } from "./routes.js";
 import { routeSecurityHeaders } from "./security-headers.js";
 import type {
@@ -28,6 +28,13 @@ const DEFAULT_HTML_RESPONSE_HEADERS = Object.freeze({
   "content-type": "text/html; charset=utf-8",
 });
 
+export interface FileConventionMetadataTemplate {
+  appleIconPath?: string | undefined;
+  iconPath?: string | undefined;
+  openGraphImageFallbackPath?: string | undefined;
+  openGraphImageRoutePath?: string | undefined;
+}
+
 export function mergeRouteMetadata(metadata: readonly RouteMetadata[]): RouteMetadata | undefined {
   if (metadata.length === 0) {
     return undefined;
@@ -67,23 +74,64 @@ export function applyFileConventionMetadata(
   filename: string,
   params: RouteParams,
 ): RouteMetadata | undefined {
-  const next: RouteMetadata = metadata === undefined ? {} : { ...metadata };
+  return applyFileConventionMetadataTemplate(
+    metadata,
+    fileConventionMetadataTemplate(routes, filename),
+    params,
+  );
+}
+
+export function fileConventionMetadataTemplate(
+  routes: readonly AppRoute[],
+  filename: string,
+): FileConventionMetadataTemplate {
+  const pageRoute = routes.find((route) => route.kind === "page" && route.file === filename);
   const iconRoute = routes.find((route) => route.kind === "asset" && route.convention === "icon");
   const appleIconRoute = routes.find(
     (route) => route.kind === "asset" && route.convention === "apple-icon",
   );
-  const openGraphImagePath = fileConventionMetadataRoutePath(
-    routes,
-    filename,
-    params,
-    "opengraph-image",
+  const openGraphImageRoutes = routes.filter(
+    (route) =>
+      (route.kind === "asset" || route.kind === "metadata") &&
+      route.convention === "opengraph-image",
   );
+  const expectedOpenGraphImagePath =
+    pageRoute === undefined
+      ? undefined
+      : pageRoute.path === "/"
+        ? "/opengraph-image"
+        : `${pageRoute.path}/opengraph-image`;
 
-  if (iconRoute !== undefined && next.icons?.icon === undefined) {
-    next.icons = { ...next.icons, icon: iconRoute.path };
+  return {
+    ...(appleIconRoute === undefined ? {} : { appleIconPath: appleIconRoute.path }),
+    ...(iconRoute === undefined ? {} : { iconPath: iconRoute.path }),
+    ...(openGraphImageRoutes.find((route) => route.path === "/opengraph-image") === undefined
+      ? {}
+      : { openGraphImageFallbackPath: "/opengraph-image" }),
+    ...(expectedOpenGraphImagePath === undefined ||
+    openGraphImageRoutes.find((route) => route.path === expectedOpenGraphImagePath) === undefined
+      ? {}
+      : { openGraphImageRoutePath: expectedOpenGraphImagePath }),
+  };
+}
+
+export function applyFileConventionMetadataTemplate(
+  metadata: RouteMetadata | undefined,
+  template: FileConventionMetadataTemplate,
+  params: RouteParams,
+): RouteMetadata | undefined {
+  const next: RouteMetadata = metadata === undefined ? {} : { ...metadata };
+  const openGraphImagePath =
+    (template.openGraphImageRoutePath === undefined
+      ? undefined
+      : concreteRoutePath(template.openGraphImageRoutePath, params)) ??
+    template.openGraphImageFallbackPath;
+
+  if (template.iconPath !== undefined && next.icons?.icon === undefined) {
+    next.icons = { ...next.icons, icon: template.iconPath };
   }
-  if (appleIconRoute !== undefined && next.icons?.apple === undefined) {
-    next.icons = { ...next.icons, apple: appleIconRoute.path };
+  if (template.appleIconPath !== undefined && next.icons?.apple === undefined) {
+    next.icons = { ...next.icons, apple: template.appleIconPath };
   }
   if (
     openGraphImagePath !== undefined &&
@@ -268,33 +316,6 @@ export function serializeSitemap(entries: readonly SitemapEntry[]): string {
   return `<?xml version="1.0" encoding="UTF-8"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${urls}</urlset>`;
 }
 
-function fileConventionMetadataRoutePath(
-  routes: readonly AppRoute[],
-  filename: string,
-  params: RouteParams,
-  convention: AppFileConvention,
-): string | undefined {
-  const pageRoute = routes.find((route) => route.kind === "page" && route.file === filename);
-  const candidateRoutes = routes.filter(
-    (route) =>
-      (route.kind === "asset" || route.kind === "metadata") &&
-      route.convention === convention,
-  );
-
-  if (pageRoute !== undefined) {
-    const expectedPath = pageRoute.path === "/" ? `/${convention}` : `${pageRoute.path}/${convention}`;
-    const routeLocal = candidateRoutes.find((route) => route.path === expectedPath);
-    const routeLocalPath =
-      routeLocal === undefined ? undefined : concreteRoutePath(routeLocal.path, params);
-
-    if (routeLocalPath !== undefined) {
-      return routeLocalPath;
-    }
-  }
-
-  return candidateRoutes.find((route) => route.path === `/${convention}`)?.path;
-}
-
 function concreteRoutePath(path: string, params: RouteParams): string | undefined {
   const segments = path === "/" ? [] : path.slice(1).split("/");
   const concrete: string[] = [];
@@ -695,7 +716,9 @@ function validateOptionalHeadMetadata(value: unknown, path: string): void {
       typeof head.nonce !== "boolean" &&
       typeof head.nonce !== "string"
     ) {
-      throw new Error(`Invalid metadata field ${descriptorPath}.nonce: expected string or boolean.`);
+      throw new Error(
+        `Invalid metadata field ${descriptorPath}.nonce: expected string or boolean.`,
+      );
     }
     if (head.attrs !== undefined) {
       assertPlainMetadataObject(head.attrs, `${descriptorPath}.attrs`);
@@ -713,6 +736,7 @@ function validateOptionalHeadMetadata(value: unknown, path: string): void {
         }
       }
     }
+    validateMetaRefreshHeadDescriptor(head, descriptorPath);
     validateUnknownJsonMetadataFields(
       descriptor as Record<string, unknown>,
       descriptorPath,
@@ -721,6 +745,36 @@ function validateOptionalHeadMetadata(value: unknown, path: string): void {
   });
 }
 
+function validateMetaRefreshHeadDescriptor(head: RouteHeadDescriptor, path: string): void {
+  if (head.tag !== "meta" || head.attrs === undefined) {
+    return;
+  }
+
+  const attrs = Object.entries(head.attrs);
+  const hasRefresh = attrs.some(([name, value]) => {
+    const canonicalName = name.toLowerCase();
+    return (
+      (canonicalName === "http-equiv" || canonicalName === "httpequiv") &&
+      typeof value === "string" &&
+      value.toLowerCase() === "refresh"
+    );
+  });
+
+  if (!hasRefresh) {
+    return;
+  }
+
+  for (const [name, value] of attrs) {
+    if (
+      name.toLowerCase() === "content" &&
+      typeof value === "string" &&
+      isUnsafeMetaRefreshContent("refresh", value)
+    ) {
+      throw new Error(`Invalid metadata field ${path}.attrs.${name}: unsafe refresh URL value.`);
+    }
+  }
+}
+
 function validateHeadAttribute(name: string, value: unknown, path: string): void {
   if (!isSafeHeadAttributeName(name)) {
     throw new Error(`Invalid metadata field ${path}: expected safe HTML attribute name.`);
@@ -728,7 +782,9 @@ function validateHeadAttribute(name: string, value: unknown, path: string): void
 
   const canonicalName = name.toLowerCase();
   if (canonicalName.startsWith("on") || isDangerousHtmlAttribute(canonicalName)) {
-    throw new Error(`Invalid metadata field ${path}: event and dangerous attributes are not allowed.`);
+    throw new Error(
+      `Invalid metadata field ${path}: event and dangerous attributes are not allowed.`,
+    );
   }
 
   if (typeof value === "string" && isUnsafeUrlAttribute(canonicalName, value)) {
@@ -866,20 +922,24 @@ function validateOptionalViewportMetadata(value: unknown, path: string): void {
 }
 
 function validateUnknownMetadataFields(metadata: RouteMetadata, path: string): void {
-  validateUnknownJsonMetadataFields(metadata as Record<string, unknown>, path, new Set([
-    "alternates",
-    "csp",
-    "description",
-    "head",
-    "icons",
-    "lang",
-    "openGraph",
-    "robots",
-    "security",
-    "themeColor",
-    "title",
-    "viewport",
-  ]));
+  validateUnknownJsonMetadataFields(
+    metadata as Record<string, unknown>,
+    path,
+    new Set([
+      "alternates",
+      "csp",
+      "description",
+      "head",
+      "icons",
+      "lang",
+      "openGraph",
+      "robots",
+      "security",
+      "themeColor",
+      "title",
+      "viewport",
+    ]),
+  );
 }
 
 function validateUnknownJsonMetadataFields(
@@ -911,12 +971,13 @@ function validateJsonSerializableMetadata(value: unknown, path: string): void {
     return;
   }
 
-  throw new Error(
-    `Invalid metadata field ${path}: expected a JSON-serializable value.`,
-  );
+  throw new Error(`Invalid metadata field ${path}: expected a JSON-serializable value.`);
 }
 
-function assertPlainMetadataObject(value: unknown, path: string): asserts value is Record<string, unknown> {
+function assertPlainMetadataObject(
+  value: unknown,
+  path: string,
+): asserts value is Record<string, unknown> {
   if (!isPlainMetadataObject(value)) {
     throw new Error(`Invalid metadata field ${path}: expected object.`);
   }
@@ -938,7 +999,9 @@ function openGraphImages(openGraph: RouteMetadata["openGraph"]): readonly string
     );
   }
 
-  return openGraph?.image === undefined ? [] : [metadataImageUrl(openGraph.image, "openGraph.image")];
+  return openGraph?.image === undefined
+    ? []
+    : [metadataImageUrl(openGraph.image, "openGraph.image")];
 }
 
 function metadataImageUrl(value: MetadataImage | MetadataScalar, path: string): string {
@@ -950,7 +1013,9 @@ function metadataImageUrl(value: MetadataImage | MetadataScalar, path: string):
     return metadataString(value.url, `${path}.url`);
   }
 
-  throw new Error(`Invalid metadata field ${path}: expected string, number, boolean, or object with url.`);
+  throw new Error(
+    `Invalid metadata field ${path}: expected string, number, boolean, or object with url.`,
+  );
 }
 
 function robotsContent(robots: NonNullable<RouteMetadata["robots"]>): string {

package/src/navigation-marker.ts

@@ -16,10 +16,13 @@ interface ParsedStartTag {
   end: number;
   hasMarker: boolean;
   name: string;
+  selfClosing: boolean;
 }
 
 export function hasNavigationRouteMarker(html: string): boolean {
   let cursor = 0;
+  let foreignContentDepth = 0;
+  let templateDepth = 0;
 
   while (cursor < html.length) {
     const openingBracket = html.indexOf("<", cursor);
@@ -33,12 +36,28 @@ export function hasNavigationRouteMarker(html: string): boolean {
     }
 
     if (html.startsWith("<![CDATA[", openingBracket)) {
-      cursor = skipCdataSection(html, openingBracket + 9);
+      cursor =
+        foreignContentDepth > 0
+          ? skipCdataSection(html, openingBracket + 9)
+          : skipBogusComment(html, openingBracket + 2);
       continue;
     }
 
     const discriminator = html[openingBracket + 1];
-    if (discriminator === "!" || discriminator === "?" || discriminator === "/") {
+    if (discriminator === "/") {
+      const endTag = parseEndTag(html, openingBracket);
+      if (endTag.name === "template" && templateDepth > 0) {
+        templateDepth -= 1;
+      } else if (
+        (endTag.name === "svg" || endTag.name === "math") &&
+        foreignContentDepth > 0
+      ) {
+        foreignContentDepth -= 1;
+      }
+      cursor = endTag.end;
+      continue;
+    }
+    if (discriminator === "!" || discriminator === "?") {
       cursor = skipTagTail(html, openingBracket + 2);
       continue;
     }
@@ -52,7 +71,14 @@ export function hasNavigationRouteMarker(html: string): boolean {
       cursor = openingBracket + 1;
       continue;
     }
-    if (tag.hasMarker) {
+    if (
+      tag.hasMarker &&
+      templateDepth === 0 &&
+      tag.name !== "html" &&
+      tag.name !== "head" &&
+      tag.name !== "body" &&
+      tag.name !== "frameset"
+    ) {
       return true;
     }
 
@@ -60,10 +86,16 @@ export function hasNavigationRouteMarker(html: string): boolean {
       return false;
     }
 
+    if (!tag.selfClosing && tag.name === "template") {
+      templateDepth += 1;
+    } else if (!tag.selfClosing && (tag.name === "svg" || tag.name === "math")) {
+      foreignContentDepth += 1;
+    }
+
     cursor =
       tag.name === "script"
         ? skipScriptElement(html, tag.end)
-        : rawTextElementNames.has(tag.name)
+        : foreignContentDepth === 0 && rawTextElementNames.has(tag.name)
           ? skipRawTextElement(html, tag.end, tag.name)
           : tag.end;
   }
@@ -92,13 +124,23 @@ function parseStartTag(html: string, openingBracket: number): ParsedStartTag | u
   for (;;) {
     cursor = skipAsciiWhitespace(html, cursor);
     if (cursor >= html.length) {
-      return { end: html.length, hasMarker: false, name };
+      return { end: html.length, hasMarker: false, name, selfClosing: false };
     }
     if (html[cursor] === ">") {
-      return { end: cursor + 1, hasMarker: markerValueIsNonEmpty === true, name };
+      return {
+        end: cursor + 1,
+        hasMarker: markerValueIsNonEmpty === true,
+        name,
+        selfClosing: false,
+      };
     }
     if (html[cursor] === "/" && html[cursor + 1] === ">") {
-      return { end: cursor + 2, hasMarker: markerValueIsNonEmpty === true, name };
+      return {
+        end: cursor + 2,
+        hasMarker: markerValueIsNonEmpty === true,
+        name,
+        selfClosing: true,
+      };
     }
     if (html[cursor] === "/") {
       return invalidStartTag(html, cursor, name);
@@ -127,7 +169,7 @@ function parseStartTag(html: string, openingBracket: number): ParsedStartTag | u
         const valueStart = cursor + 1;
         const valueEnd = html.indexOf(quote, valueStart);
         if (valueEnd < 0) {
-          return { end: html.length, hasMarker: false, name };
+          return { end: html.length, hasMarker: false, name, selfClosing: false };
         }
         valueIsNonEmpty = valueEnd > valueStart;
         cursor = valueEnd + 1;
@@ -153,10 +195,16 @@ function parseStartTag(html: string, openingBracket: number): ParsedStartTag | u
 }
 
 function invalidStartTag(html: string, cursor: number, name: string): ParsedStartTag {
-  return { end: skipTagTail(html, cursor), hasMarker: false, name };
+  return { end: skipMalformedTagTail(html, cursor), hasMarker: false, name, selfClosing: false };
 }
 
 function skipComment(html: string, cursor: number): number {
+  if (html[cursor] === ">") {
+    return cursor + 1;
+  }
+  if (html.startsWith("->", cursor)) {
+    return cursor + 2;
+  }
   const standardEnd = html.indexOf("-->", cursor);
   const abruptEnd = html.indexOf("--!>", cursor);
   const end =
@@ -164,6 +212,28 @@ function skipComment(html: string, cursor: number): number {
   return end < 0 ? html.length : end + (end === abruptEnd ? 4 : 3);
 }
 
+function skipBogusComment(html: string, cursor: number): number {
+  const end = html.indexOf(">", cursor);
+  return end < 0 ? html.length : end + 1;
+}
+
+function parseEndTag(html: string, openingBracket: number): { end: number; name: string } {
+  let cursor = openingBracket + 2;
+  const nameStart = cursor;
+  while (isAsciiLetter(html[cursor])) {
+    cursor += 1;
+  }
+  return {
+    end: skipTagTail(html, cursor),
+    name: html.slice(nameStart, cursor).toLowerCase(),
+  };
+}
+
+function skipMalformedTagTail(html: string, cursor: number): number {
+  const end = html.indexOf(">", cursor);
+  return end < 0 ? html.length : end + 1;
+}
+
 function skipCdataSection(html: string, cursor: number): number {
   const end = html.indexOf("]]>", cursor);
   return end < 0 ? html.length : end + 3;

package/src/navigation.ts

@@ -46,7 +46,7 @@ function containsControlCharacter(value: string): boolean {
 // Allowed: path-absolute (`/foo`), query-only (`?x=1`), hash-only (`#x`),
 // relative (`foo`). Rejected: protocol-relative (`//evil`), backslash variants
 // (`/\evil`, `\\evil`), and anything with a scheme like `javascript:`.
-function isSafeInternalRedirect(location: string): boolean {
+export function isSafeInternalRedirect(location: string): boolean {
   if (containsControlCharacter(location)) return false;
   const trimmed = stripLeadingControlOrWhitespace(location);
   if (trimmed === "") return false;

package/src/node-server.ts

@@ -9,28 +9,43 @@ import {
   requestLogFields,
   type AppRouterLogger,
 } from "./logger.js";
-import type { HttpUpgradeHandler } from "./upgrade.js";
+import {
+  assertValidHttpUpgradeOriginPolicy,
+  closeServerWithUpgrades,
+  createManagedHttpUpgradeLifecycle,
+  validateHttpUpgradeOrigin,
+  type HttpUpgradeOriginPolicy,
+  type HttpUpgradeOriginValidation,
+  type ManagedHttpUpgradeHandler,
+} from "./upgrade.js";
 
 export interface StartNodeRequestServerOptions {
   allowedHosts?: readonly string[] | undefined;
-  errorHandler?: ((error: unknown) => {
-    body: string;
-    status: number;
-    headers?: Record<string, string>;
-  }) | undefined;
+  errorHandler?:
+    | ((error: unknown) => {
+        body: string;
+        status: number;
+        headers?: Record<string, string>;
+      })
+    | undefined;
   hostname?: string | undefined;
   hostPolicy?: "strict" | "trusted-proxy" | undefined;
   logger?: AppRouterLogger | undefined;
-  onUpgrade?: HttpUpgradeHandler | undefined;
+  onUpgrade?: ManagedHttpUpgradeHandler | undefined;
   port: number;
   render(request: Request): Promise<Response>;
-  resolveHost?: ((options: {
-    allowedHosts?: readonly string[] | undefined;
-    fallbackHost: string;
-    hostPolicy?: "strict" | "trusted-proxy" | undefined;
-    rawHost: string | undefined;
-  }) => string) | undefined;
+  resolveHost?:
+    | ((options: {
+        allowedHosts?: readonly string[] | undefined;
+        fallbackHost: string;
+        hostPolicy?: "strict" | "trusted-proxy" | undefined;
+        rawHost: string | undefined;
+      }) => string)
+    | undefined;
   trustForwardedProto?: boolean | undefined;
+  upgradeCloseTimeoutMs?: number | undefined;
+  upgradeDecisionTimeoutMs?: number | undefined;
+  upgradeOriginPolicy?: HttpUpgradeOriginPolicy | undefined;
 }
 
 export function resolveNodeRequestProtocol(options: {
@@ -56,6 +71,18 @@ export function resolveNodeRequestProtocol(options: {
 export async function startNodeRequestServer(
   options: StartNodeRequestServerOptions,
 ): Promise<{ close(): Promise<void>; server: Server; url: string }> {
+  const upgradeCloseTimeoutMs = finiteNonNegativeTimeout(
+    options.upgradeCloseTimeoutMs,
+    1_000,
+    "upgradeCloseTimeoutMs",
+  );
+  const upgradeDecisionTimeoutMs = finiteNonNegativeTimeout(
+    options.upgradeDecisionTimeoutMs,
+    1_000,
+    "upgradeDecisionTimeoutMs",
+  );
+  assertValidHttpUpgradeOriginPolicy(options.upgradeOriginPolicy);
+  let listeningPort = options.port;
   const server = createServer(async (incoming, outgoing) => {
     const startedAt = logNow();
     const fallbackRequestFields = {
@@ -65,7 +92,7 @@ export async function startNodeRequestServer(
     };
 
     try {
-      const fallbackHost = `${options.hostname ?? "127.0.0.1"}:${options.port}`;
+      const fallbackHost = formatNodeAuthority(options.hostname ?? "127.0.0.1", options.port);
       const host = (options.resolveHost ?? defaultResolveRequestHost)({
         allowedHosts: options.allowedHosts,
         fallbackHost,
@@ -77,7 +104,7 @@ export async function startNodeRequestServer(
         forwardedProto: incoming.headers["x-forwarded-proto"],
         trustForwardedProto: options.trustForwardedProto,
       });
-      const request = nodeRequestToWebRequest(incoming, `${protocol}://${host}`);
+      const request = nodeRequestToWebRequest(incoming, `${protocol}://${host}`, outgoing);
       const logFields = requestLogFields(request, "node");
       emitRouterLog(options.logger, "info", {
         ...logFields,
@@ -120,8 +147,21 @@ export async function startNodeRequestServer(
     }
   });
 
-  if (options.onUpgrade !== undefined) {
-    server.on("upgrade", options.onUpgrade);
+  const upgradeLifecycle =
+    options.onUpgrade === undefined
+      ? undefined
+      : createManagedHttpUpgradeLifecycle({
+          decisionTimeoutMs: upgradeDecisionTimeoutMs,
+          handler: options.onUpgrade,
+          isOriginAllowed: (request) =>
+            validateNodeUpgradeOrigin(request, {
+              ...options,
+              listeningPort,
+            }),
+          logger: options.logger,
+        });
+  if (upgradeLifecycle !== undefined) {
+    server.on("upgrade", upgradeLifecycle.handle);
   }
 
   await new Promise<void>((resolve) =>
@@ -129,17 +169,83 @@ export async function startNodeRequestServer(
   );
   const address = server.address();
   const port = typeof address === "object" && address !== null ? address.port : options.port;
+  listeningPort = port;
+  let closePromise: Promise<void> | undefined;
 
   return {
     server,
-    url: `http://${options.hostname ?? "127.0.0.1"}:${port}`,
-    close: () =>
-      new Promise<void>((resolve, reject) =>
-        server.close((error) => (error ? reject(error) : resolve())),
-      ),
+    url: `http://${formatNodeAuthority(options.hostname ?? "127.0.0.1", port)}`,
+    close: () => {
+      closePromise ??=
+        upgradeLifecycle === undefined
+          ? new Promise<void>((resolve, reject) =>
+              server.close((error) => (error ? reject(error) : resolve())),
+            )
+          : closeServerWithUpgrades({
+              lifecycle: upgradeLifecycle,
+              server,
+              timeoutMs: upgradeCloseTimeoutMs,
+            });
+      return closePromise;
+    },
   };
 }
 
+function validateNodeUpgradeOrigin(
+  request: import("node:http").IncomingMessage,
+  options: StartNodeRequestServerOptions & { listeningPort: number },
+): HttpUpgradeOriginValidation {
+  const policy = options.upgradeOriginPolicy ?? "same-origin";
+  if (policy === "unchecked") {
+    return { ok: true, origin: request.headers.origin };
+  }
+  if (typeof policy === "object") {
+    return validateHttpUpgradeOrigin(request, policy);
+  }
+
+  const fallbackHost = formatNodeAuthority(options.hostname ?? "127.0.0.1", options.listeningPort);
+  const host = (options.resolveHost ?? defaultResolveRequestHost)({
+    allowedHosts: options.allowedHosts,
+    fallbackHost,
+    hostPolicy: options.hostPolicy,
+    rawHost: request.headers.host,
+  });
+  const protocol = resolveNodeRequestProtocol({
+    encrypted: (request.socket as { encrypted?: boolean }).encrypted === true,
+    forwardedProto: request.headers["x-forwarded-proto"],
+    trustForwardedProto: options.trustForwardedProto,
+  });
+  try {
+    return validateHttpUpgradeOrigin(request, { allowedOrigins: [`${protocol}://${host}`] });
+  } catch {
+    return { ok: false, reason: "malformed-origin" };
+  }
+}
+
+function formatNodeAuthority(hostname: string, port: number): string {
+  const host = hostname.includes(":") && !hostname.startsWith("[") ? `[${hostname}]` : hostname;
+  return `${host}:${port}`;
+}
+
+function finiteNonNegativeTimeout(
+  value: number | undefined,
+  fallback: number,
+  name: string,
+): number {
+  const timeout = value ?? fallback;
+  if (
+    !Number.isFinite(timeout) ||
+    timeout < 0 ||
+    !Number.isSafeInteger(timeout) ||
+    timeout > 2_147_483_647
+  ) {
+    throw new TypeError(
+      `${name} must be a finite non-negative safe integer no greater than 2147483647.`,
+    );
+  }
+  return timeout;
+}
+
 function defaultResolveRequestHost(options: {
   allowedHosts?: readonly string[] | undefined;
   fallbackHost: string;