@cdxgen/cdxgen 13.3.0 → 13.4.0

package/lib/cli/nativeBom.js

@@ -1,7 +1,7 @@
 import { Buffer } from "node:buffer";
 import { readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import process from "node:process";
 
 import { build } from "@cdxgen/cdx-purl";
@@ -28,6 +28,7 @@ import {
 } from "../core/fs.js";
 import { thoughtLog } from "../core/logger.js";
 import { dirNameStr, isMac } from "../core/paths.js";
+import { readCrateArchiveValues } from "../ecosystems/cargoCache.js";
 import {
   buildDependentPurl,
   collapseCmakeVersions,
@@ -35,7 +36,11 @@ import {
   resolveCmakeContext,
   withoutScrapedFetchDependency,
 } from "../ecosystems/cmakeResolver.js";
-import { getCppModules } from "../ecosystems/cppEvidence.js";
+import {
+  emptyCppBuildContext,
+  resolveCppBuildContext,
+} from "../ecosystems/cppBuildContext.js";
+import { getCppModules, hasCppSources } from "../ecosystems/cppEvidence.js";
 import {
   getCratesMetadata,
   getSwiftPackageMetadata,
@@ -58,6 +63,7 @@ import {
   parseGoModWhy,
   parseGopkgData,
   parseGosumData,
+  parseGosumHashes,
 } from "../ecosystems/parsers-go.js";
 import { parseJuliaProject } from "../ecosystems/parsers-julia.js";
 import {
@@ -115,7 +121,9 @@ import {
 } from "../ecosystems/parsers-rust.js";
 import { parseSpackLock } from "../ecosystems/parsers-spack.js";
 import { parseStackProject } from "../ecosystems/parsers-stack.js";
+import { findVendoredCode } from "../ecosystems/vendoredCode.js";
 import { resolveZigGraph } from "../ecosystems/zigResolver.js";
+import { cmakeBuildDirCandidates } from "../inventory/cmakeBuildDirs.js";
 import { mergeDependencies, trimComponents } from "../inventory/depsUtils.js";
 import { convertOSQueryResults } from "../inventory/evidenceUtils.js";
 import { applyPurl, nixBomRef, tryBuildPurl } from "../inventory/purl.js";
@@ -339,12 +347,9 @@ export async function createGoBom(path, options) {
         console.log(`Parsing ${f}`);
       }
       const gosumData = readFileSync(f, { encoding: "utf-8" });
-      const dlist = await parseGosumData(gosumData);
-      if (dlist?.length) {
-        dlist.forEach((pkg) => {
-          gosumMap[`${pkg.name}@${pkg.version}`] = pkg._integrity;
-        });
-      }
+      // Only the hashes are needed here; reading them costs no registry
+      // round trip. The components come from go.mod and the go list output.
+      Object.assign(gosumMap, parseGosumHashes(gosumData));
     }
   }
 
@@ -1163,7 +1168,9 @@ export function buildCargoCacheComponent(crateFile) {
 
 /**
  * Enriches a cargo cache component with a SHA-256 hash and filename-based
- * identity evidence (confidence 0.5). Hash computation failures are ignored.
+ * identity evidence (confidence 0.5), and with what the archive's own manifest
+ * says: its licence, description and repository, read from the archive without
+ * extracting it anywhere. Hash computation failures are ignored.
  *
  * @param {string} crateFile Absolute path to the `.crate` archive
  * @param {object} [component] Component produced by `buildCargoCacheComponent`
@@ -1183,6 +1190,33 @@ export async function enrichCargoCacheComponent(crateFile, component) {
   } catch {
     // continue without hashes
   }
+  const archive = await readCrateArchiveValues(
+    crateFile,
+    component.name,
+    component.version,
+  );
+  if (archive) {
+    if (archive.values.license && !component.license) {
+      component.license = archive.values.license;
+    }
+    if (archive.values.licenses && !component.licenses) {
+      component.licenses = archive.values.licenses;
+    }
+    if (archive.values.description && !component.description) {
+      component.description = archive.values.description;
+    }
+    if (archive.values.repository && !component.repository) {
+      component.repository = { url: archive.values.repository };
+    }
+    if (archive.values.homepage && !component.homepage) {
+      component.homepage = { url: archive.values.homepage };
+    }
+    component.properties = component.properties || [];
+    component.properties.push({
+      name: "cdx:cargo:metadataSource",
+      value: "local-registry",
+    });
+  }
   component.evidence = {
     identity: {
       field: "purl",
@@ -1365,6 +1399,7 @@ export function createCppBom(path, options) {
   }
   let pkgList = [];
   let parentComponentDependencies = [];
+  const subProjects = [];
   if (conanLockFiles.length) {
     for (const f of conanLockFiles) {
       if (DEBUG_MODE) {
@@ -1477,8 +1512,17 @@ export function createCppBom(path, options) {
         Object.keys(retMap.parentComponent).length &&
         !addedParentComponentsMap[retMap.parentComponent.name]
       ) {
+        // a project() below the scan root is a part of this project, not a
+        // dependency of it
         retMap.parentComponent.type = "library";
-        pkgList.push(retMap.parentComponent);
+        const subprojectDir = relative(scanRoot, resolve(dirname(f)))
+          .split(sep)
+          .join("/");
+        retMap.parentComponent.properties = [
+          ...(retMap.parentComponent.properties || []),
+          { name: "cdx:cmake:subprojectDir", value: subprojectDir || "." },
+        ];
+        subProjects.push(retMap.parentComponent);
         addedParentComponentsMap[retMap.parentComponent.name] = true;
       }
       // Retain the dependency tree from cmake
@@ -1522,6 +1566,29 @@ export function createCppBom(path, options) {
         boundaries: new Map(),
       }
     : resolveCmakeContext(path, options);
+  // How the project is built: its presets and compilers (formulation), its
+  // hardening options (project properties) and its own include directories.
+  const isImageScan = hasAnyProjectType(
+    ["docker", "oci", "container", "os"],
+    options,
+    false,
+  );
+  // Code carried in the tree under a license of its own, outside the sources
+  // of the dependencies CMake already knows and the build trees
+  const vendored = isImageScan
+    ? { components: [], dirs: [] }
+    : findVendoredCode(path, options, [
+        ...[...(cmakeContext.boundaries || new Map())]
+          .filter(([, e]) => e?.kind === "fetch" || e?.kind === "submodule")
+          .map(([dir]) => resolve(path, dir)),
+        ...cmakeBuildDirCandidates(path, options),
+      ]);
+  if (vendored.components.length) {
+    pkgList = pkgList.concat(vendored.components);
+  }
+  const buildContext = isImageScan
+    ? emptyCppBuildContext()
+    : resolveCppBuildContext(path, options, cmakeContext, vendored.dirs);
   if (cmakeContext.rootProject?.version && parentComponent) {
     const resolvedVersion = cmakeContext.rootProject.version;
     const scrapedVersion = parentComponent.version;
@@ -1651,30 +1718,44 @@ export function createCppBom(path, options) {
     // We collect OS packages with the word dev in the name using osquery here
     // rpm, deb and ebuild are supported
     // TODO: For archlinux and alpine users we need a different mechanism to collect this information
-    for (const queryCategory of Object.keys(cosDbQueries)) {
-      const queryObj = cosDbQueries[queryCategory];
-      const results = executeOsQuery(queryObj.query);
-      const dlist = convertOSQueryResults(
-        queryCategory,
-        queryObj,
-        results,
-        true,
-        {
-          deb: executeDpkgList,
-          rpm: executeRpmList,
-          apk: executeApkList,
-          ebuild: executeEqueryList,
-          alpm: executeAlpmList,
-        },
-      );
-      if (dlist?.length) {
-        osPkgsList = osPkgsList.concat(dlist);
+    // The packages only resolve the headers named by the usages slice, so
+    // they are not queried when there is neither a slice to reuse nor a C or
+    // C++ source for atom to read.
+    if (
+      (options.usagesSlicesFile && safeExistsSync(options.usagesSlicesFile)) ||
+      hasCppSources(path, options)
+    ) {
+      for (const queryCategory of Object.keys(cosDbQueries)) {
+        const queryObj = cosDbQueries[queryCategory];
+        const results = executeOsQuery(queryObj.query);
+        const dlist = convertOSQueryResults(
+          queryCategory,
+          queryObj,
+          results,
+          true,
+          {
+            deb: executeDpkgList,
+            rpm: executeRpmList,
+            apk: executeApkList,
+            ebuild: executeEqueryList,
+            alpm: executeAlpmList,
+          },
+        );
+        if (dlist?.length) {
+          osPkgsList = osPkgsList.concat(dlist);
+        }
       }
     }
     // Now we check with atom and attempt to detect all external modules via usages
     // We pass the current list of packages so that we enhance the current list and replace
     // components inadvertently. For example, we might resolved a name, version and url information already via cmake
-    const retMap = getCppModules(path, options, osPkgsList, pkgList);
+    const retMap = getCppModules(
+      path,
+      options,
+      osPkgsList,
+      pkgList,
+      buildContext.isFirstPartyHeader,
+    );
     if (retMap.pkgList?.length) {
       pkgList = pkgList.concat(retMap.pkgList);
     }
@@ -1718,6 +1799,33 @@ export function createCppBom(path, options) {
     ]);
   }
 
+  if (subProjects.length) {
+    if (parentComponent) {
+      parentComponent.components = parentComponent.components || [];
+      for (const sub of subProjects) {
+        if (
+          !parentComponent.components.some(
+            (c) => c["bom-ref"] === sub["bom-ref"],
+          ) &&
+          sub["bom-ref"] !== parentComponent["bom-ref"]
+        ) {
+          parentComponent.components.push(sub);
+        }
+      }
+    } else {
+      // with no project at the scan root there is nothing to nest them under
+      pkgList = pkgList.concat(subProjects);
+    }
+  }
+  if (parentComponent && buildContext.parentProperties.length) {
+    parentComponent.properties = (parentComponent.properties || []).filter(
+      (p) =>
+        !buildContext.parentProperties.some(
+          (bp) => bp.name === p.name && bp.value === p.value,
+        ),
+    );
+    parentComponent.properties.push(...buildContext.parentProperties);
+  }
   if (parentComponent) {
     sanitizeUnresolvedPurl(parentComponent);
     if (parentComponent.components) {
@@ -1734,6 +1842,7 @@ export function createCppBom(path, options) {
     src: path,
     parentComponent,
     dependencies,
+    formulationList: buildContext.formulationComponents,
   });
 }
 
@@ -2328,7 +2437,7 @@ export async function createCocoaBom(path, options) {
       "application",
     );
     const podfileLock = loadYaml(readFileSync(lockFile, "utf-8"));
-    const pods = await parsePodfileLock(podfileLock, projectPath);
+    const pods = await parsePodfileLock(podfileLock, projectPath, path);
     const allObjects = new Map();
     if (options) {
       // Every remote podspec the scan below reads is known from the lockfile,

package/lib/core/activity.js

@@ -285,6 +285,18 @@ const MANIFEST_ACTIVITY_HINTS = new Map([
   ],
 ]);
 const SENSITIVE_CONFIG_ACTIVITY_HINTS = [
+  {
+    matcher: (_lowerPath, baseName) =>
+      baseName === ".terraformrc" ||
+      baseName === "terraform.rc" ||
+      baseName === "credentials.tfrc.json",
+    metadata: {
+      classification: "credential",
+      ecosystem: "terraform",
+      label: "Terraform CLI configuration",
+      sensitive: true,
+    },
+  },
   {
     matcher: (lowerPath, _baseName) =>
       lowerPath.includes("/.cargo/config.toml") ||

package/lib/core/env.js

@@ -111,19 +111,27 @@ export function shouldFetchLicense() {
   );
 }
 
+/**
+ * Determines whether registry provenance, such as publish times, publishers
+ * and trusted-publishing signals, is wanted. `--bom-audit` turns it on through
+ * CDXGEN_FETCH_PKG_METADATA. Local data cannot answer these questions, so a
+ * package whose licence and description are known locally is still looked up.
+ *
+ * @returns {boolean} True if CDXGEN_FETCH_PKG_METADATA is "true" or "1"
+ */
+export function shouldFetchRegistryProvenance() {
+  return ["true", "1"].includes(
+    readEnvironmentVariable("CDXGEN_FETCH_PKG_METADATA"),
+  );
+}
+
 /**
  * Determines whether remote package metadata should be fetched for enrichment.
  *
  * @returns {boolean} True when registry metadata enrichment is enabled.
  */
 export function shouldFetchPackageMetadata() {
-  return (
-    shouldFetchLicense() ||
-    (readEnvironmentVariable("CDXGEN_FETCH_PKG_METADATA") &&
-      ["true", "1"].includes(
-        readEnvironmentVariable("CDXGEN_FETCH_PKG_METADATA"),
-      ))
-  );
+  return shouldFetchLicense() || shouldFetchRegistryProvenance();
 }
 
 /**
@@ -457,7 +465,7 @@ export const PROJECT_TYPE_ALIASES = {
   perl: ["perl", "cpan", "carton", "cpanfile"],
   spack: ["spack"],
   terraform: ["terraform", "opentofu", "tf"],
-  c: ["c", "cpp", "c++", "conan", "collider"],
+  c: ["c", "cpp", "c++", "conan", "collider", "cmake", "meson", "vcpkg"],
   clojure: ["clojure", "edn", "clj", "leiningen"],
   github: ["github", "actions"],
   hbom: ["hbom", "hardware"],
@@ -493,7 +501,7 @@ export const PROJECT_TYPE_ALIASES = {
   binary: ["binary", "blint"],
   oci: ["docker", "image", "oci", "container", "podman", "rootfs", "oci-dir"],
   cocoa: ["cocoa", "cocoapods", "objective-c", "swift", "ios"],
-  scala: ["scala", "scala3", "sbt", "mill"],
+  scala: ["scala", "scala3", "sbt", "mill", "scala-cli"],
   nix: ["nix", "nixos", "flake"],
   zig: ["zig", "zon"],
   gleam: ["gleam"],

package/lib/core/fs.js

@@ -577,7 +577,7 @@ export function shellQuoteArgument(arg, forWindows = isWin) {
         backslashes++;
         quoted += ch;
       } else if (ch === '"') {
-        quoted += "\\".repeat(backslashes) + '\\"';
+        quoted += `${"\\".repeat(backslashes)}\\"`;
         backslashes = 0;
       } else {
         quoted += ch;
@@ -1025,7 +1025,8 @@ export const MAX_BUFFER =
 export function getAllFiles(dirPath, pattern, options = {}) {
   let ignoreList = [];
   if (!options.noIgnore) {
-    ignoreList.push("**/.hg/**", "**/.git/**");
+    // .chen holds chen's AST cache, which atom writes into a C/C++ source tree
+    ignoreList.push("**/.hg/**", "**/.git/**", "**/.chen/**");
     // Only ignore node_modules if the caller is not looking for package.json
     if (!pattern.includes("package.json") && !options.includeNodeModulesDir) {
       ignoreList.push("**/node_modules/**");

package/lib/core/httpClient.js

@@ -1,4 +1,5 @@
 import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
 import process from "node:process";
 import { brotliDecompressSync, gunzipSync, inflateSync } from "node:zlib";
 
@@ -9,6 +10,8 @@ import {
   request as undiciRequest,
 } from "undici";
 
+import { registerRunReset } from "./runState.js";
+
 // Environment variables here are read with raw `process.env` rather than
 // `readEnvironmentVariable`: that helper lives in activity.js, which imports
 // this module, so routing these through it would form an import cycle.
@@ -41,9 +44,8 @@ import {
  *   `Content-Encoding` header, matching `got`'s transparent decoding.
  * - Proxy support via the standard `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY`
  *   environment variables (through undici's `EnvHttpProxyAgent`).
- * - An in-memory GET response cache (enabled by default, disabled by setting
- *   the `CDXGEN_NO_CACHE` environment variable) that replaces the got + Keyv
- *   cache cdxgen previously relied on.
+ * - An in-memory GET response cache that replaces the got + Keyv cache cdxgen
+ *   previously relied on. A request opts out with `cache: false`.
  * - Response objects exposing `statusCode`, `headers`, `body`, `rawBody`,
  *   `url` and `request.options`.
  * - A lazily-resolved `.json()` method on the returned promise, mirroring
@@ -137,7 +139,12 @@ function mergeHeaders(base = {}, override = {}) {
  *   `beforeError` arrays.
  */
 function mergeHooks(base = {}, override = {}) {
-  const hookNames = ["beforeRequest", "afterResponse", "beforeError"];
+  const hookNames = [
+    "beforeRequest",
+    "beforeNetwork",
+    "afterResponse",
+    "beforeError",
+  ];
   const merged = {};
   for (const name of hookNames) {
     merged[name] = [...(base?.[name] || []), ...(override?.[name] || [])];
@@ -253,6 +260,11 @@ function decompressBody(rawBody, contentEncoding) {
  * Read and decode an undici response body according to the requested
  * `responseType`.
  *
+ * An error response often carries a body in another format than the one asked
+ * for, such as the HTML page a CDN sends with a 429. Its JSON body is decoded
+ * when it parses and kept as text otherwise, so the caller sees the status
+ * rather than a parse error.
+ *
  * @param {Object} undiciResponse Response returned by `undici.request`.
  * @param {string} [responseType] One of `"json"`, `"buffer"` or `"text"`.
  * @returns {Promise<{body: any, rawBody: Buffer}>} Decoded body and raw bytes.
@@ -272,7 +284,17 @@ async function readBody(undiciResponse, responseType) {
     body = rawBody;
   } else if (responseType === "json") {
     const text = rawBody.toString("utf-8");
-    body = text.length ? JSON.parse(text) : undefined;
+    if (!text.length) {
+      body = undefined;
+    } else if (undiciResponse.statusCode >= 400) {
+      try {
+        body = JSON.parse(text);
+      } catch (_err) {
+        body = text;
+      }
+    } else {
+      body = JSON.parse(text);
+    }
   } else {
     body = rawBody.toString("utf-8");
   }
@@ -304,20 +326,100 @@ function resolveRequestBody(options) {
 
 // In-memory cache of successful GET responses, mirroring the HTTP cache cdxgen
 // historically kept via got + Keyv. Repeated metadata/license lookups during a
-// scan are served from here instead of hitting the network again. Set the
-// CDXGEN_NO_CACHE environment variable to "true" or "1" to disable it.
+// scan are served from here instead of hitting the network again. It lasts for
+// one run; `CDXGEN_NO_CACHE` and `--no-cache` turn off only the on-disk caches,
+// because nothing gains from asking a registry the same question twice in one
+// scan.
+//
+// Entries expire after an hour and the cache is bounded in size, least
+// recently used first, so a long-running server neither serves stale registry
+// documents nor grows without limit.
 const responseCache = new Map();
+const RESPONSE_CACHE_TTL_MS = 60 * 60 * 1000;
+const RESPONSE_CACHE_MAX_BYTES = 512 * 1024 * 1024;
+let responseCacheLimits = {
+  ttlMs: RESPONSE_CACHE_TTL_MS,
+  maxBytes: RESPONSE_CACHE_MAX_BYTES,
+};
+let responseCacheBytes = 0;
+
+/**
+ * Approximate the memory a cached response holds. The raw bytes are kept,
+ * plus the decoded body for text and JSON responses.
+ *
+ * @param {Object} response Response object.
+ * @returns {number} Size in bytes.
+ */
+function cachedResponseBytes(response) {
+  const raw = response?.rawBody?.length || 0;
+  return response?.body === response?.rawBody ? raw : raw * 3;
+}
 
 /**
- * Determine whether the in-memory HTTP response cache is disabled via the
- * CDXGEN_NO_CACHE environment variable. Evaluated per request so tests and
- * callers can toggle it at runtime.
+ * Read a cached response, dropping it when it has expired and marking it as
+ * recently used otherwise.
  *
- * @returns {boolean} True when caching should be skipped.
+ * @param {string} key Cache key.
+ * @returns {Object|undefined} The cached response.
  */
-export function isCacheDisabled() {
-  const value = process.env.CDXGEN_NO_CACHE;
-  return value === "true" || value === "1";
+function cacheGet(key) {
+  const entry = responseCache.get(key);
+  if (!entry) {
+    return undefined;
+  }
+  responseCache.delete(key);
+  if (entry.expiresAt <= Date.now()) {
+    responseCacheBytes -= entry.bytes;
+    return undefined;
+  }
+  responseCache.set(key, entry);
+  return entry.response;
+}
+
+/**
+ * Store a response, evicting the least recently used entries beyond the size
+ * bound.
+ *
+ * @param {string} key Cache key.
+ * @param {Object} response Response object.
+ * @returns {void}
+ */
+function cacheSet(key, response) {
+  const bytes = cachedResponseBytes(response);
+  if (bytes > responseCacheLimits.maxBytes) {
+    return;
+  }
+  const previous = responseCache.get(key);
+  if (previous) {
+    responseCache.delete(key);
+    responseCacheBytes -= previous.bytes;
+  }
+  responseCache.set(key, {
+    response,
+    bytes,
+    expiresAt: Date.now() + responseCacheLimits.ttlMs,
+  });
+  responseCacheBytes += bytes;
+  for (const [oldestKey, oldest] of responseCache) {
+    if (responseCacheBytes <= responseCacheLimits.maxBytes) {
+      break;
+    }
+    responseCache.delete(oldestKey);
+    responseCacheBytes -= oldest.bytes;
+  }
+}
+
+/**
+ * Override the response cache bounds. Returns the previous bounds so tests can
+ * restore them. Not part of the public API.
+ *
+ * @param {{ttlMs?: number, maxBytes?: number}} limits New bounds.
+ * @returns {{ttlMs: number, maxBytes: number}} Previous bounds.
+ */
+export function _setHttpCacheLimits(limits) {
+  const previous = responseCacheLimits;
+  responseCacheLimits = { ...responseCacheLimits, ...limits };
+  return previous;
 }
 
 /**
@@ -327,8 +429,11 @@ export function isCacheDisabled() {
  */
 export function clearHttpCache() {
   responseCache.clear();
+  responseCacheBytes = 0;
 }
 
+registerRunReset("http:responses", clearHttpCache);
+
 // ---------------------------------------------------------------------------
 // Test cassette interceptor — the single network seam.
 //
@@ -397,15 +502,33 @@ export function clearHttpInterceptor() {
 }
 
 /**
- * Build the cache key for a request. Only the method and normalized URL are
- * used, matching got's default cache key behaviour.
+ * Build the cache key for a request.
+ *
+ * Besides the method and URL, the key carries the response type, which
+ * changes how the same bytes are decoded, and a digest of every request
+ * header. A response fetched with one credential is therefore never served to
+ * a request made with another credential or with none, and a JSON request
+ * never receives a text body. Header values only enter the key as a SHA-256
+ * digest, so no credential is held in it.
  *
  * @param {string} method Uppercased HTTP method.
  * @param {URL} url Request URL.
+ * @param {Object} [headers] Request headers as sent.
+ * @param {string} [responseType] Requested body decoding.
  * @returns {string} Cache key.
  */
-function cacheKeyFor(method, url) {
-  return `${method}:${url.toString()}`;
+function cacheKeyFor(method, url, headers = {}, responseType = undefined) {
+  const headerEntries = Object.entries(headers || {})
+    .filter(([, value]) => value !== undefined && value !== null)
+    .map(([name, value]) => [
+      name.toLowerCase(),
+      Array.isArray(value) ? value.join(", ") : String(value),
+    ])
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  const headerDigest = headerEntries.length
+    ? createHash("sha256").update(JSON.stringify(headerEntries)).digest("hex")
+    : "";
+  return `${method}:${responseType || "text"}:${url.toString()}:${headerDigest}`;
 }
 
 // The maximum number of redirects to follow when `followRedirect` is enabled.
@@ -587,11 +710,23 @@ async function doRequest(mergedOptions) {
   const { body, headers } = resolveRequestBody(options);
   const method = (options.method || "GET").toUpperCase();
 
-  // Serve cacheable GET requests from the in-memory cache when enabled.
-  const cacheable = method === "GET" && !isCacheDisabled();
-  const cacheKey = cacheable ? cacheKeyFor(method, url) : undefined;
-  if (cacheable && responseCache.has(cacheKey)) {
-    return responseCache.get(cacheKey);
+  // Serve cacheable GET requests from the in-memory cache when enabled. A
+  // request opts out with `cache: false`, as token exchanges do.
+  const cacheable = method === "GET" && options.cache !== false;
+  const cacheKey = cacheable
+    ? cacheKeyFor(method, url, headers, options.responseType)
+    : undefined;
+  if (cacheable) {
+    const cached = cacheGet(cacheKey);
+    if (cached) {
+      return cached;
+    }
+  }
+
+  // Runs only when the request is about to reach the network, so a caller
+  // that rate-limits a host does not wait for a response already cached.
+  for (const hook of options.hooks?.beforeNetwork || []) {
+    await hook(options);
   }
 
   const timeoutMs = resolveTimeout(options.timeout);
@@ -652,7 +787,7 @@ async function doRequest(mergedOptions) {
 
   // Only successful responses are cached, matching HTTP cache semantics.
   if (cacheable && finalResponse.statusCode < 400) {
-    responseCache.set(cacheKey, finalResponse);
+    cacheSet(cacheKey, finalResponse);
   }
   return finalResponse;
 }