docs: document guarded fetch net helpers

steipete · steipete · commit 53aa5232bc00 · 2026-06-04T16:50:29.000-04:00
diff --git a/src/infra/net/configured-local-origin-bypass.ts b/src/infra/net/configured-local-origin-bypass.ts
@@ -1,3 +1,5 @@
+// Configured local-origin bypass logic decides when managed proxy routing may
+// skip proxying a known loopback provider origin.
 import { isLoopbackIpAddress } from "@openclaw/net-policy/ip";
 import { getActiveManagedProxyLoopbackMode } from "./proxy/active-proxy-state.js";
 import { SsrFBlockedError } from "./ssrf.js";
diff --git a/src/infra/net/fetch-guard.ssrf.test.ts b/src/infra/net/fetch-guard.ssrf.test.ts
@@ -1,3 +1,5 @@
+// Guarded fetch SSRF tests cover redirect hardening, pinned dispatcher setup,
+// trusted proxy modes, and safe header retention.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   fetchConfiguredLocalOriginWithSsrFGuard,
diff --git a/src/infra/net/fetch-guard.ts b/src/infra/net/fetch-guard.ts
@@ -1,3 +1,5 @@
+// Guarded fetch runtime enforces SSRF checks, DNS pinning, redirect policy, and
+// trusted proxy modes around provider/network requests.
 import type { Dispatcher } from "undici";
 import { logWarn } from "../../logger.js";
 import { buildTimeoutAbortSignal } from "../../utils/fetch-timeout.js";
@@ -143,6 +145,8 @@ export function withTrustedExplicitProxyGuardedFetchMode(
 }
 
 function resolveGuardedFetchMode(params: GuardedFetchOptions): GuardedFetchMode {
+  // Legacy proxy flags map to the explicit trusted env-proxy mode; strict is the
+  // default for user-influenced URLs.
   if (params.mode) {
     return params.mode;
   }
@@ -212,6 +216,8 @@ async function assertExplicitProxyAllowed(
   lookupFn: LookupFn | undefined,
   policy: SsrFPolicy | undefined,
 ): Promise<void> {
+  // Explicit proxies are operator-configured, but the proxy host still needs
+  // basic URL and private-network validation before target validation proceeds.
   if (!dispatcherPolicy || dispatcherPolicy.mode !== "explicit-proxy") {
     return;
   }
diff --git a/src/infra/net/hostname.test.ts b/src/infra/net/hostname.test.ts
@@ -1,3 +1,5 @@
+// Hostname normalization tests cover DNS trailing dots, empty input, and
+// bracketed IPv6 literal handling.
 import { describe, expect, it } from "vitest";
 import { normalizeHostname } from "./hostname.js";
 
diff --git a/src/infra/net/hostname.ts b/src/infra/net/hostname.ts
@@ -1,7 +1,7 @@
+// Hostname normalization helpers keep SSRF and proxy policy comparisons stable
+// across case, trailing dots, and bracketed IPv6 literals.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
-// Hostname normalization is intentionally display/compare-oriented: lowercase,
-// trim brackets for IPv6 literals, and remove trailing DNS dots.
 /** Normalize a hostname for policy comparisons. */
 export function normalizeHostname(hostname: string): string {
   const normalized = normalizeLowercaseStringOrEmpty(hostname).replace(/\.+$/, "");
diff --git a/src/infra/net/runtime-fetch.test.ts b/src/infra/net/runtime-fetch.test.ts
@@ -1,3 +1,5 @@
+// Runtime fetch tests cover header normalization and FormData conversion before
+// calls reach undici's dispatcher-aware fetch.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { fetchWithRuntimeDispatcher } from "./runtime-fetch.js";
 import { TEST_UNDICI_RUNTIME_DEPS_KEY } from "./undici-runtime.js";
diff --git a/src/infra/net/runtime-fetch.ts b/src/infra/net/runtime-fetch.ts
@@ -1,3 +1,5 @@
+// Runtime fetch adapter preserves undici dispatcher support and normalizes
+// headers/FormData before calling the runtime fetch implementation.
 import type { Dispatcher } from "undici";
 import { normalizeHeadersInitForFetch } from "../fetch-headers.js";
 import { loadUndiciRuntimeDeps, type UndiciRuntimeDeps } from "./undici-runtime.js";
@@ -23,6 +25,8 @@ function normalizeRuntimeFormData(
   body: unknown,
   RuntimeFormData: RuntimeFormDataCtor | undefined,
 ): BodyInit | null | undefined {
+  // Node global FormData and undici runtime FormData can differ; rebuild into
+  // the runtime constructor so multipart uploads stream correctly.
   if (!isFormDataLike(body) || typeof RuntimeFormData !== "function") {
     return body as BodyInit | null | undefined;
   }
diff --git a/src/infra/net/ssrf.dispatcher.test.ts b/src/infra/net/ssrf.dispatcher.test.ts
@@ -1,3 +1,5 @@
+// Pinned dispatcher tests cover undici family policy, pinned lookup injection,
+// timeout propagation, and proxy dispatcher construction.
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { TEST_UNDICI_RUNTIME_DEPS_KEY } from "./undici-runtime.js";
 
diff --git a/src/infra/net/ssrf.pinning.test.ts b/src/infra/net/ssrf.pinning.test.ts
@@ -1,3 +1,5 @@
+// SSRF pinning tests cover DNS pinning behavior, blocked DNS results, hostname
+// allowlists, and IPv4/IPv6 address ordering.
 import { describe, expect, it, vi } from "vitest";
 import {
   createPinnedLookup,
diff --git a/src/infra/net/ssrf.test.ts b/src/infra/net/ssrf.test.ts
@@ -1,3 +1,4 @@
+// SSRF tests cover IP privacy classification and HTTP base URL policy builders.
 import { describe, expect, it } from "vitest";
 import { blockedIpv6MulticastLiterals } from "../../../packages/net-policy/src/ip-test-fixtures.js";
 import {
diff --git a/src/infra/net/ssrf.ts b/src/infra/net/ssrf.ts
@@ -1,3 +1,5 @@
+// SSRF policy helpers validate hostnames/IP literals, build pinned DNS lookups,
+// and create dispatcher policies for guarded network fetches.
 import { lookup as dnsLookupCb, type LookupAddress } from "node:dns";
 import { lookup as dnsLookup } from "node:dns/promises";
 import {
@@ -71,6 +73,8 @@ function normalizePolicyHostnames(values?: string[]): string[] {
 }
 
 function normalizeSsrFPolicyForComparison(policy?: SsrFPolicy) {
+  // Policy equality needs deterministic set ordering and normalized host/origin
+  // forms so equivalent operator config compares equal.
   if (!policy) {
     return null;
   }
@@ -230,6 +234,8 @@ function shouldSkipPrivateNetworkChecks(hostname: string, policy?: SsrFPolicy):
 }
 
 export function resolveSsrFPolicyForUrl(url: URL, policy?: SsrFPolicy): SsrFPolicy | undefined {
+  // allowedOrigins trust only the current request hostname for the matching
+  // origin; redirects must re-evaluate against their own URL.
   if (!policy?.allowedOrigins?.length) {
     return policy;
   }

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Configured local-origin bypass logic decides when managed proxy routing may`
	`2`	`+// skip proxying a known loopback provider origin.`
`1`	`3`	`import { isLoopbackIpAddress } from "@openclaw/net-policy/ip";`
`2`	`4`	`import { getActiveManagedProxyLoopbackMode } from "./proxy/active-proxy-state.js";`
`3`	`5`	`import { SsrFBlockedError } from "./ssrf.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Guarded fetch SSRF tests cover redirect hardening, pinned dispatcher setup,`
	`2`	`+// trusted proxy modes, and safe header retention.`
`1`	`3`	`import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";`
`2`	`4`	`import {`
`3`	`5`	`fetchConfiguredLocalOriginWithSsrFGuard,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Hostname normalization tests cover DNS trailing dots, empty input, and`
	`2`	`+// bracketed IPv6 literal handling.`
`1`	`3`	`import { describe, expect, it } from "vitest";`
`2`	`4`	`import { normalizeHostname } from "./hostname.js";`
`3`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Runtime fetch tests cover header normalization and FormData conversion before`
	`2`	`+// calls reach undici's dispatcher-aware fetch.`
`1`	`3`	`import { afterEach, describe, expect, it, vi } from "vitest";`
`2`	`4`	`import { fetchWithRuntimeDispatcher } from "./runtime-fetch.js";`
`3`	`5`	`import { TEST_UNDICI_RUNTIME_DEPS_KEY } from "./undici-runtime.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Pinned dispatcher tests cover undici family policy, pinned lookup injection,`
	`2`	`+// timeout propagation, and proxy dispatcher construction.`
`1`	`3`	`import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";`
`2`	`4`	`import { TEST_UNDICI_RUNTIME_DEPS_KEY } from "./undici-runtime.js";`
`3`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// SSRF pinning tests cover DNS pinning behavior, blocked DNS results, hostname`
	`2`	`+// allowlists, and IPv4/IPv6 address ordering.`
`1`	`3`	`import { describe, expect, it, vi } from "vitest";`
`2`	`4`	`import {`
`3`	`5`	`createPinnedLookup,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// SSRF tests cover IP privacy classification and HTTP base URL policy builders.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import { blockedIpv6MulticastLiterals } from "../../../packages/net-policy/src/ip-test-fixtures.js";`
`3`	`4`	`import {`