@hydraharness/harness-web-fetch-http 0.1.1-rc.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# @hydraharness/harness-web-fetch-http
+
+An anonymous public HTTP(S) `WebFetchProvider` for the harness [web capability seam](../web/README.md) (`ctx.web`). It retrieves a concrete URL and returns a status code plus bounded decoded content.
+
+This is an **implementation** package: it registers a provider into `ctx.web`, it does not own the key and it does not register a model-facing tool. It is a function/namespace plugin (`inject: ['web']`).
+
+## Responsibility split
+
+The provider owns **safe resource retrieval**: URL validation, HTTP transport, redirect policy, a resource-backstop timeout, abort propagation, byte caps, charset decoding, content-type classification, and binary rejection. `@hydraharness/harness-tool-web` owns **presentation** (HTML→markdown, truncation formatting). A non-2xx HTTP response is a *result* (status code + decoded body), not an error; `WebError` is reserved for failures to safely retrieve or represent the resource.
+
+The provider's `timeoutMs` is a resource backstop for direct `ctx.web.fetch()` callers and misconfigured deployments, not the model-facing tool-call budget. [`@hydraharness/harness-tool-call-timeout-policy`](../../guard/timeout-policy/README.md) owns the `web_fetch` tool-call budget by arming `exec.signal`.
+
+A shipping web-tool deployment sets the provider backstop above the tool budget, so model calls normally return `TOOL_TIMEOUT`. If the outer deadline reaches the provider first, the provider reports `WEB_ABORTED` and the outer policy replaces it with `TOOL_TIMEOUT`. `WEB_FETCH_TIMEOUT` therefore identifies a direct service caller whose provider budget elapsed.
+
+## Transport hygiene
+
+Connections use a private direct dispatcher and validate every DNS answer inside socket lookup. Only the validated addresses reach the socket; there is no second DNS lookup between checking and connecting. Literal IP URLs receive the same checks, and each redirect opens a separately checked connection. Private, loopback, link-local, multicast, reserved, and IPv6 transition destinations fail with `WEB_BLOCKED_URL`. Ambient proxies, global dispatchers, browser cookies, and credentials are not used.
+
+`allowedOrigins` grants exact operator-configured HTTP(S) origins access to non-public addresses. It defaults to an empty list and is never a tool argument. Ports are part of the grant; paths, credentials, and wildcards are rejected. Local fixture compositions explicitly grant their test server origin.
+
+- Accepts only `http:` and `https:` URLs; rejects credentials in URLs (`WEB_BLOCKED_URL`) and over-long/malformed URLs (`WEB_INVALID_URL`).
+- Enforces a max URL length, response byte cap (`WEB_FETCH_TOO_LARGE`), decoded body character cap, timeout (`WEB_FETCH_TIMEOUT`), and redirect hop cap.
+- Propagates the caller's abort signal (`WEB_ABORTED`) into the network request and the streaming read.
+- Follows only **same-origin** redirects; a cross-origin redirect fails with `WEB_REDIRECT_BLOCKED`, requiring a fresh tool call (the model of Claude Code's WebFetch).
+- Sends an explicit product `User-Agent`, never a browser disguise.
+- Rejects unsupported (e.g. binary) content types with `WEB_UNSUPPORTED_CONTENT_TYPE`.
+
+## Config
+
+| Key | Default | Meaning |
+|---|---|---|
+| `maxUrlLength` | `2048` | Maximum accepted request URL length. |
+| `maxResponseBytes` | `5_000_000` | Maximum response body size in bytes. |
+| `maxBodyChars` | `100_000` | Maximum decoded body length in characters. |
+| `timeoutMs` | `30_000` | Fetch timeout within Node's timer range — a resource backstop for direct `ctx.web.fetch()` callers, not the model-facing tool-call budget (that is `@hydraharness/harness-tool-call-timeout-policy`). |
+| `maxRedirects` | `5` | Maximum same-origin redirect hops (`0` follows none). |
+| `allowedOrigins` | `[]` | Exact HTTP(S) origins permitted to connect to non-public addresses. |
+| `userAgent` | `hydra-harness/…` | `User-Agent` header. |
+
+The numeric limits are validated at plugin construction: every cap except `maxRedirects` must be a positive finite number, and `maxRedirects` must be a non-negative integer. An invalid value throws rather than silently constructing a provider with nonsensical limits.
+
+## Model Experience
+
+Indirectly, through [`@hydraharness/harness-tool-web`](../tool-web/README.md), which places this provider's `maxBodyChars`-bounded decoded text or markdown-shaped HTML under its fetch-result wrapper and retains provider failures while redirects, headers, and transport mechanics remain hidden.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **Public address policy is conservative** — special-use IPv4 and IPv6 transition/reserved ranges are refused even when a particular address is globally reachable. Network-level routing and explicitly granted private origins remain deployment responsibilities.
+- **Only textual content decodes** — html/xhtml and `text/*`-plus-JSON/XML families; a missing `Content-Type` or any binary type throws `WEB_UNSUPPORTED_CONTENT_TYPE`, and text-extractable PDF decoding is named deferred work.
+- **Charset comes only from the `Content-Type` header** (UTF-8 default) — an HTML `<meta charset>` declaration is ignored, and a declared-but-unrecognized charset label throws rather than falling back.

package/lib/index.js

@@ -0,0 +1,513 @@
+import z from "@hydraharness/schemastery";
+import { WebError } from "@hydraharness/harness-web";
+import { deadline, timeoutOf } from "@hydraharness/harness-timeout";
+import { lookup } from "node:dns";
+import { BlockList, isIP } from "node:net";
+import { Agent } from "undici";
+//#region lib/types/policy.js
+/**
+* URL validation and content-type classification for the local HTTP(S) fetch
+* provider — the pure, network-free half. The provider's `fetch()` composes
+* these with transport (redirect following, byte caps, decoding).
+*
+* @module @hydraharness/harness-web-fetch-http/policy
+*/
+/**
+* Validate a request URL against the basic transport hygiene the provider
+* enforces before any network access: http(s) only, no embedded credentials,
+* bounded length. Returns the parsed `URL`. Throws {@link WebError} otherwise.
+* Destination IP checks additionally run at connection time in the HTTP provider.
+*
+* @param input - the raw URL string from the fetch request.
+* @param maxUrlLength - inclusive upper bound on `input`'s length.
+* @returns the parsed `URL`.
+*/
+function validateFetchUrl(input, maxUrlLength) {
+	if (input.length > maxUrlLength) throw new WebError(`URL exceeds the maximum length of ${maxUrlLength}`, "WEB_INVALID_URL");
+	let url;
+	try {
+		url = new URL(input);
+	} catch (error) {
+		throw new WebError(`invalid URL: ${input}`, "WEB_INVALID_URL", { cause: error });
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new WebError(`unsupported URL scheme "${url.protocol}" (only http and https are allowed)`, "WEB_INVALID_URL");
+	if (url.username.length > 0 || url.password.length > 0) throw new WebError("credentials in URLs are not allowed", "WEB_BLOCKED_URL");
+	return url;
+}
+/**
+* Two URLs are same-origin when scheme, hostname, and port match. A redirect
+* that crosses origins is refused so each new origin requires a fresh tool call
+* (and thus a fresh provider/permission decision).
+*
+* @param a - one of the two URLs to compare.
+* @param b - the other URL to compare.
+* @returns true when `a` and `b` share scheme, hostname, and port.
+*/
+function isSameOrigin(a, b) {
+	return a.protocol === b.protocol && a.hostname === b.hostname && a.port === b.port;
+}
+/**
+* Classify a response `Content-Type` into a decodable body kind, or `undefined`
+* for an unsupported (e.g. binary) type. `text/html` and `application/xhtml+xml`
+* are `html`; other `text/*` plus a few structured text types are `text`.
+*
+* @param contentType - the raw `Content-Type` header, or `null` when the
+*   response carries none (unsupported).
+* @returns the decodable kind, or `undefined` for an unsupported type.
+*/
+function classifyContentType(contentType) {
+	const mime = (contentType ?? "").replace(/;.*$/s, "").trim().toLowerCase();
+	if (mime === "text/html" || mime === "application/xhtml+xml") return "html";
+	if (mime.startsWith("text/")) return "text";
+	if (mime === "application/json" || mime === "application/xml" || mime.endsWith("+json") || mime.endsWith("+xml")) return "text";
+}
+/**
+* Extract the `charset` parameter from a response `Content-Type`, lower-cased,
+* or `undefined` when absent. The provider feeds this label to `TextDecoder`
+* so a non-UTF-8 response is decoded with its declared encoding rather than
+* silently mangled into replacement characters.
+*
+* @param contentType - the raw `Content-Type` header, or `null` when the
+*   response carries none.
+* @returns the lower-cased charset label, or `undefined` when none is declared.
+*/
+function parseCharset(contentType) {
+	return /;\s*charset\s*=\s*"?([^";]+)"?/i.exec(contentType ?? "")?.[1]?.trim().toLowerCase();
+}
+/**
+* Build a `TextDecoder` for the declared charset, falling back to UTF-8 when
+* none is declared. Throws {@link WebError} `WEB_UNSUPPORTED_CONTENT_TYPE` when
+* the label is present but not a charset `TextDecoder` recognizes — better to
+* fail loudly than return mojibake.
+*
+* @param charset - the declared charset label (from {@link parseCharset}), or
+*   `undefined` to default to UTF-8.
+* @returns a decoder for the declared (or defaulted) encoding.
+*/
+function decoderForCharset(charset) {
+	if (charset === void 0) return new TextDecoder("utf-8");
+	try {
+		return new TextDecoder(charset);
+	} catch (error) {
+		throw new WebError(`unsupported charset "${charset}"`, "WEB_UNSUPPORTED_CONTENT_TYPE", { cause: error });
+	}
+}
+//#endregion
+//#region lib/types/network.js
+/** Public-destination enforcement at socket lookup; explicit origins may reach private services. */
+const blocked = new BlockList();
+for (const [address, prefix] of [
+	["0.0.0.0", 8],
+	["10.0.0.0", 8],
+	["100.64.0.0", 10],
+	["127.0.0.0", 8],
+	["169.254.0.0", 16],
+	["172.16.0.0", 12],
+	["192.0.0.0", 24],
+	["192.0.2.0", 24],
+	["192.88.99.0", 24],
+	["192.168.0.0", 16],
+	["198.18.0.0", 15],
+	["198.51.100.0", 24],
+	["203.0.113.0", 24],
+	["224.0.0.0", 4],
+	["240.0.0.0", 4]
+]) blocked.addSubnet(address, prefix, "ipv4");
+for (const [address, prefix] of [
+	["2001::", 23],
+	["2001:db8::", 32],
+	["2002::", 16],
+	["3fff::", 20]
+]) blocked.addSubnet(address, prefix, "ipv6");
+const globalV6 = new BlockList();
+globalV6.addSubnet("2000::", 3, "ipv6");
+/**
+* Reject special-use addresses, including mapped IPv4 and IPv6 transition ranges.
+* @param address - a literal IP address from URL parsing or the system resolver.
+* @throws {WebError} when the address is not public unicast.
+*/
+function assertPublicAddress(address) {
+	const family = isIP(address);
+	if (!(family === 4 ? !blocked.check(address, "ipv4") : family === 6 && globalV6.check(address, "ipv6") && !blocked.check(address, "ipv6"))) throw new WebError("web fetch destination is not a public IP address", "WEB_BLOCKED_URL");
+}
+/**
+* Validate operator-granted exact origins; paths, credentials and wildcards are rejected.
+* @param origins - configured exceptions to public-only destination enforcement.
+* @returns canonical origins used for exact comparison on every redirect.
+*/
+function resolveAllowedOrigins(origins) {
+	return origins.map((origin) => {
+		const url = new URL(origin);
+		if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.pathname !== "/" || url.search || url.hash || url.hostname.includes("*")) throw new Error("web-fetch-http: allowedOrigins must contain exact HTTP(S) origins without credentials, paths, or wildcards");
+		return url.origin;
+	});
+}
+/** Resolve once inside connect and pass only that validated address set to the socket. */
+const publicLookup = (hostname, options, callback) => {
+	lookup(hostname, {
+		all: true,
+		order: "verbatim"
+	}, (error, addresses) => {
+		if (error) {
+			callback(error, [], void 0);
+			return;
+		}
+		try {
+			if (addresses.length === 0) throw new WebError("web fetch DNS returned no addresses", "WEB_PROVIDER_ERROR");
+			for (const entry of addresses) assertPublicAddress(entry.address);
+		} catch (failure) {
+			callback(failure, [], void 0);
+			return;
+		}
+		const first = addresses[0];
+		if (options.all) callback(null, addresses, void 0);
+		else callback(null, first.address, first.family);
+	});
+};
+/**
+* Create a direct dispatcher, independent of ambient proxies or global dispatchers.
+* @param url - validated request URL.
+* @param allowedOrigins - operator-granted exceptions, never model-controlled.
+* @returns dispatcher the caller must destroy after consuming or cancelling the response.
+*/
+function publicDispatcher(url, allowedOrigins) {
+	if (allowedOrigins.includes(url.origin)) return new Agent();
+	const hostname = url.hostname.replace(/^\[|\]$/g, "");
+	if (isIP(hostname)) assertPublicAddress(hostname);
+	return new Agent({ connect: { lookup: publicLookup } });
+}
+//#endregion
+//#region lib/types/provider.js
+/**
+* Safe HTTP(S) retrieval for `ctx.web`: validates URLs, follows only same-origin redirects,
+* enforces time and size limits, classifies and decodes text, and leaves presentation to
+* `@hydraharness/harness-tool-web`. Requests carry no browser cookies or ambient credentials.
+*
+* Connections enforce public IP destinations unless the operator grants an exact origin.
+* @module @hydraharness/harness-web-fetch-http/provider
+*/
+var __addDisposableResource = function(env, value, async) {
+	if (value !== null && value !== void 0) {
+		if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+		var dispose, inner;
+		if (async) {
+			if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+			dispose = value[Symbol.asyncDispose];
+		}
+		if (dispose === void 0) {
+			if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+			dispose = value[Symbol.dispose];
+			if (async) inner = dispose;
+		}
+		if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+		if (inner) dispose = function() {
+			try {
+				inner.call(this);
+			} catch (e) {
+				return Promise.reject(e);
+			}
+		};
+		env.stack.push({
+			value,
+			dispose,
+			async
+		});
+	} else if (async) env.stack.push({ async: true });
+	return value;
+};
+var __disposeResources = (function(SuppressedError) {
+	return function(env) {
+		function fail(e) {
+			env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+			env.hasError = true;
+		}
+		var r, s = 0;
+		function next() {
+			while (r = env.stack.pop()) try {
+				if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+				if (r.dispose) {
+					var result = r.dispose.call(r.value);
+					if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) {
+						fail(e);
+						return next();
+					});
+				} else s |= 1;
+			} catch (e) {
+				fail(e);
+			}
+			if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+			if (env.hasError) throw env.error;
+		}
+		return next();
+	};
+})(typeof SuppressedError === "function" ? SuppressedError : function(error, suppressed, message) {
+	var e = new Error(message);
+	return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+/** Stable id this provider registers under. */
+const LOCAL_FETCH_PROVIDER_ID = "http";
+/** The anonymous public HTTP(S) fetch provider. */
+var HttpFetchProvider = class {
+	limits;
+	id = LOCAL_FETCH_PROVIDER_ID;
+	allowedOrigins;
+	constructor(limits) {
+		this.limits = limits;
+		this.allowedOrigins = resolveAllowedOrigins(limits.allowedOrigins ?? []);
+	}
+	/** No credentials to check — an anonymous public fetcher is always usable. */
+	available() {
+		return true;
+	}
+	async fetch(request, signal) {
+		const env_1 = {
+			stack: [],
+			error: void 0,
+			hasError: false
+		};
+		try {
+			if (signal?.aborted) throw new WebError("web fetch aborted", "WEB_ABORTED");
+			const d = __addDisposableResource(env_1, deadline(signal, this.limits.timeoutMs, "WEB_FETCH_TIMEOUT"), false);
+			return await this.followAndRead(request.url, d.signal);
+		} catch (e_1) {
+			env_1.error = e_1;
+			env_1.hasError = true;
+		} finally {
+			__disposeResources(env_1);
+		}
+	}
+	/** Follow same-origin redirects up to the hop cap, then read the final response. */
+	async followAndRead(initialUrl, signal) {
+		let currentUrl = validateFetchUrl(initialUrl, this.limits.maxUrlLength);
+		let redirectsFollowed = 0;
+		for (;;) {
+			const dispatcher = publicDispatcher(currentUrl, this.allowedOrigins);
+			try {
+				const response = await this.requestOnce(currentUrl, signal, dispatcher);
+				if (isRedirectStatus(response.status)) {
+					if (redirectsFollowed >= this.limits.maxRedirects) {
+						await response.body?.cancel();
+						throw new WebError(`exceeded the maximum of ${this.limits.maxRedirects} redirects`, "WEB_REDIRECT_BLOCKED");
+					}
+					const location = response.headers.get("location");
+					if (location === null) {
+						await response.body?.cancel();
+						throw new WebError(`redirect response (HTTP ${response.status}) without a Location header`, "WEB_PROVIDER_ERROR");
+					}
+					const target = resolveRedirect(location, currentUrl);
+					let validatedTarget;
+					try {
+						validatedTarget = validateFetchUrl(target.toString(), this.limits.maxUrlLength);
+						if (!isSameOrigin(validatedTarget, currentUrl)) throw new WebError(`cross-origin redirect to ${validatedTarget.origin} is not followed automatically; retry against that URL directly`, "WEB_REDIRECT_BLOCKED");
+					} catch (error) {
+						await response.body?.cancel();
+						throw error;
+					}
+					await response.body?.cancel();
+					currentUrl = validatedTarget;
+					redirectsFollowed++;
+					continue;
+				}
+				return await this.readBody(response, currentUrl, signal);
+			} finally {
+				await dispatcher.destroy();
+			}
+		}
+	}
+	async requestOnce(url, signal, dispatcher) {
+		try {
+			const init = {
+				method: "GET",
+				redirect: "manual",
+				headers: {
+					"user-agent": this.limits.userAgent,
+					"accept": "text/html,application/xhtml+xml,text/*;q=0.9,application/json;q=0.8"
+				},
+				signal,
+				dispatcher
+			};
+			return await fetch(url, init);
+		} catch (error) {
+			throw translateAbortOrNetwork(error, signal);
+		}
+	}
+	/** Read, byte-cap, classify, and decode the final response body. */
+	async readBody(response, finalUrl, signal) {
+		const contentType = response.headers.get("content-type");
+		const kind = classifyContentType(contentType);
+		if (kind === void 0) {
+			await response.body?.cancel();
+			throw new WebError(`unsupported content type "${contentType ?? "unknown"}"`, "WEB_UNSUPPORTED_CONTENT_TYPE");
+		}
+		let decoder;
+		try {
+			decoder = decoderForCharset(parseCharset(contentType));
+		} catch (error) {
+			await response.body?.cancel();
+			throw error;
+		}
+		const { bytes, truncatedByBytes } = await this.readCapped(response, signal);
+		const decoded = decoder.decode(bytes);
+		const truncatedByChars = decoded.length > this.limits.maxBodyChars;
+		const content = truncatedByChars ? decoded.slice(0, this.limits.maxBodyChars) : decoded;
+		const body = kind === "html" ? {
+			kind: "html",
+			content
+		} : {
+			kind: "text",
+			content
+		};
+		return {
+			url: finalUrl.toString(),
+			statusCode: response.status,
+			body,
+			truncated: truncatedByBytes || truncatedByChars
+		};
+	}
+	/**
+	* Read the response stream up to `maxResponseBytes`. A `Content-Length` over
+	* the cap rejects immediately with `WEB_FETCH_TOO_LARGE`; a stream that grows
+	* past the cap is cut short (`truncatedByBytes`) rather than rejected, so a
+	* server that under-reports still yields a bounded usable body.
+	*/
+	async readCapped(response, signal) {
+		const declared = response.headers.get("content-length");
+		if (declared !== null) {
+			const length = Number(declared);
+			if (Number.isFinite(length) && length > this.limits.maxResponseBytes) {
+				await response.body?.cancel();
+				throw new WebError(`response exceeds the maximum of ${this.limits.maxResponseBytes} bytes`, "WEB_FETCH_TOO_LARGE");
+			}
+		}
+		/* v8 ignore next -- a 2xx Response from fetch always exposes a body stream; the null guard is defensive. */
+		if (response.body === null) return {
+			bytes: new Uint8Array(0),
+			truncatedByBytes: false
+		};
+		const chunks = [];
+		let total = 0;
+		let truncatedByBytes = false;
+		const reader = response.body.getReader();
+		try {
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				const remaining = this.limits.maxResponseBytes - total;
+				if (value.byteLength > remaining) {
+					chunks.push(value.subarray(0, remaining));
+					total += remaining;
+					truncatedByBytes = true;
+					break;
+				}
+				chunks.push(value);
+				total += value.byteLength;
+			}
+		} catch (error) {
+			/* v8 ignore next -- mid-stream read fault needs a network drop after headers; translate path covered by request-phase tests. */
+			throw translateAbortOrNetwork(error, signal);
+		} finally {
+			/* v8 ignore next 4 -- cancel() after a completed/broken read settles without rejecting; unobserved best-effort cleanup. */
+			await reader.cancel().catch(() => {});
+		}
+		const bytes = new Uint8Array(total);
+		let offset = 0;
+		for (const chunk of chunks) {
+			bytes.set(chunk, offset);
+			offset += chunk.byteLength;
+		}
+		return {
+			bytes,
+			truncatedByBytes
+		};
+	}
+};
+/** HTTP redirect status codes that carry a `Location`. */
+function isRedirectStatus(status) {
+	return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+/** Resolve a (possibly relative) `Location` against the current URL. */
+function resolveRedirect(location, base) {
+	try {
+		return new URL(location, base);
+	} catch (error) {
+		/* v8 ignore next 2 -- URL resolution against a valid absolute base effectively never throws; defensive guard. */
+		throw new WebError(`invalid redirect Location "${location}"`, "WEB_PROVIDER_ERROR", { cause: error });
+	}
+}
+/**
+* Translate a thrown fetch/stream error into a `WebError`, classified by the
+* deadline signal rather than the thrown value (which differs by phase: the
+* request-phase `fetch` rejects with the abort reason, while the read-phase
+* reader surfaces a bare `AbortError`). `timeoutOf(signal, 'WEB_FETCH_TIMEOUT')`
+* recovering OUR reason means our timeout fired (`WEB_FETCH_TIMEOUT`); any other
+* abort — an upstream cancel, or a foreign/outer deadline's timeout under
+* nesting — is `WEB_ABORTED`; a throw with the signal NOT aborted is a
+* transport/network failure (`WEB_PROVIDER_ERROR`).
+*/
+function translateAbortOrNetwork(error, signal) {
+	const timeout = timeoutOf(signal, "WEB_FETCH_TIMEOUT");
+	if (timeout !== void 0) return new WebError("web fetch timed out", "WEB_FETCH_TIMEOUT", { cause: timeout });
+	if (signal.aborted) return new WebError("web fetch aborted", "WEB_ABORTED", { cause: error });
+	if (error instanceof Error && error.cause instanceof WebError) return error.cause;
+	return new WebError(`web fetch failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* `@hydraharness/harness-web-fetch-http`: registers an anonymous public HTTP(S)
+* `WebFetchProvider` with `ctx.web`. A function/namespace plugin (NOT a
+* default-export service): it registers INTO the seam's fetch registry, like the
+* search providers register into the search registry.
+*
+* @module @hydraharness/harness-web-fetch-http
+*/
+const MAX_NODE_TIMER_DELAY_MS = 2147483647;
+/** Default `User-Agent`: an explicit product agent, never a browser disguise. */
+const DEFAULT_USER_AGENT = "hydra-harness/0.0.1 (+https://github.com/MaiHongPhong1902/Hydra-Harness)";
+/** Cordis plugin name used by loader diagnostics. */
+const name = "web-fetch-http";
+/** The web seam this provider registers into. */
+const inject = ["web"];
+const Config = z.object({
+	maxUrlLength: z.number().default(2048),
+	maxResponseBytes: z.number().default(5e6),
+	maxBodyChars: z.number().default(1e5),
+	timeoutMs: z.number().default(3e4),
+	maxRedirects: z.number().default(5),
+	userAgent: z.string().default(DEFAULT_USER_AGENT),
+	allowedOrigins: z.array(z.string()).default([])
+});
+/** A resource limit (byte/char/length/timeout cap) must be a positive finite number. */
+function assertPositiveFinite(name, value) {
+	if (!Number.isFinite(value) || value <= 0) throw new Error(`web-fetch-http: ${name} must be a positive finite number`);
+}
+/** Node coerces larger timer delays to 1 ms, so reject them at configuration time. */
+function assertTimeoutMs(value) {
+	assertPositiveFinite("timeoutMs", value);
+	if (value > MAX_NODE_TIMER_DELAY_MS) throw new Error(`web-fetch-http: timeoutMs must be no greater than ${MAX_NODE_TIMER_DELAY_MS}`);
+}
+/** The redirect hop cap must be a non-negative integer (0 follows no redirects). */
+function assertNonNegativeInteger(name, value) {
+	if (!Number.isInteger(value) || value < 0) throw new Error(`web-fetch-http: ${name} must be a non-negative integer`);
+}
+/** Register the local HTTP(S) fetch provider with `ctx.web`. */
+function apply(ctx, config) {
+	const resolved = config;
+	assertPositiveFinite("maxUrlLength", resolved.maxUrlLength);
+	assertPositiveFinite("maxResponseBytes", resolved.maxResponseBytes);
+	assertPositiveFinite("maxBodyChars", resolved.maxBodyChars);
+	assertTimeoutMs(resolved.timeoutMs);
+	assertNonNegativeInteger("maxRedirects", resolved.maxRedirects);
+	const limits = {
+		maxUrlLength: resolved.maxUrlLength,
+		maxResponseBytes: resolved.maxResponseBytes,
+		maxBodyChars: resolved.maxBodyChars,
+		timeoutMs: resolved.timeoutMs,
+		maxRedirects: resolved.maxRedirects,
+		userAgent: resolved.userAgent,
+		allowedOrigins: resolved.allowedOrigins
+	};
+	ctx.web.registerFetchProvider(new HttpFetchProvider(limits));
+}
+//#endregion
+export { Config, DEFAULT_USER_AGENT, HttpFetchProvider, LOCAL_FETCH_PROVIDER_ID, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-web-fetch-http`.
+* @module @hydraharness/harness-web-fetch-http/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-web-fetch-http";
+/** Cordis companion plugin name. */
+const name = "web-fetch-http-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this package exposes no independent event sequence or mutable data relation
+* beyond contracts enforced at its owning seam.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `@hydraharness/harness-web-fetch-http`: registers an anonymous public HTTP(S)
+ * `WebFetchProvider` with `ctx.web`. A function/namespace plugin (NOT a
+ * default-export service): it registers INTO the seam's fetch registry, like the
+ * search providers register into the search registry.
+ *
+ * @module @hydraharness/harness-web-fetch-http
+ */
+import type { Context } from '@hydraharness/cordis';
+import z from '@hydraharness/schemastery';
+export { LOCAL_FETCH_PROVIDER_ID, HttpFetchProvider, } from './provider.ts';
+export type { HttpFetchLimits } from './provider.ts';
+/** Default `User-Agent`: an explicit product agent, never a browser disguise. */
+export declare const DEFAULT_USER_AGENT = "hydra-harness/0.0.1 (+https://github.com/MaiHongPhong1902/Hydra-Harness)";
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "web-fetch-http";
+/** The web seam this provider registers into. */
+export declare const inject: string[];
+/** Plugin config: the provider's transport and size limits plus its `User-Agent` (all defaulted). */
+export interface Config {
+    /** Maximum accepted request URL length. */
+    maxUrlLength?: number;
+    /** Maximum response body size in bytes. */
+    maxResponseBytes?: number;
+    /** Maximum decoded body length in characters. */
+    maxBodyChars?: number;
+    /** Default fetch timeout in milliseconds, within Node's timer range. */
+    timeoutMs?: number;
+    /** Maximum number of same-origin redirect hops to follow. */
+    maxRedirects?: number;
+    /** `User-Agent` header sent on every request. */
+    userAgent?: string;
+    /** Exact HTTP(S) origins permitted to reach private addresses. Defaults to none. */
+    allowedOrigins?: string[];
+}
+export declare const Config: z<Config>;
+/** Register the local HTTP(S) fetch provider with `ctx.web`. */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-web-fetch-http`.
+ * @module @hydraharness/harness-web-fetch-http/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "web-fetch-http-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/network.d.ts

@@ -0,0 +1,21 @@
+import { Agent } from 'undici';
+/**
+ * Reject special-use addresses, including mapped IPv4 and IPv6 transition ranges.
+ * @param address - a literal IP address from URL parsing or the system resolver.
+ * @throws {WebError} when the address is not public unicast.
+ */
+export declare function assertPublicAddress(address: string): void;
+/**
+ * Validate operator-granted exact origins; paths, credentials and wildcards are rejected.
+ * @param origins - configured exceptions to public-only destination enforcement.
+ * @returns canonical origins used for exact comparison on every redirect.
+ */
+export declare function resolveAllowedOrigins(origins: readonly string[]): readonly string[];
+/**
+ * Create a direct dispatcher, independent of ambient proxies or global dispatchers.
+ * @param url - validated request URL.
+ * @param allowedOrigins - operator-granted exceptions, never model-controlled.
+ * @returns dispatcher the caller must destroy after consuming or cancelling the response.
+ */
+export declare function publicDispatcher(url: URL, allowedOrigins: readonly string[]): Agent;
+//# sourceMappingURL=network.d.ts.map

package/lib/types/policy.d.ts

@@ -0,0 +1,63 @@
+/**
+ * URL validation and content-type classification for the local HTTP(S) fetch
+ * provider — the pure, network-free half. The provider's `fetch()` composes
+ * these with transport (redirect following, byte caps, decoding).
+ *
+ * @module @hydraharness/harness-web-fetch-http/policy
+ */
+/** The body kinds this provider decodes. */
+export type FetchableKind = 'html' | 'text';
+/**
+ * Validate a request URL against the basic transport hygiene the provider
+ * enforces before any network access: http(s) only, no embedded credentials,
+ * bounded length. Returns the parsed `URL`. Throws {@link WebError} otherwise.
+ * Destination IP checks additionally run at connection time in the HTTP provider.
+ *
+ * @param input - the raw URL string from the fetch request.
+ * @param maxUrlLength - inclusive upper bound on `input`'s length.
+ * @returns the parsed `URL`.
+ */
+export declare function validateFetchUrl(input: string, maxUrlLength: number): URL;
+/**
+ * Two URLs are same-origin when scheme, hostname, and port match. A redirect
+ * that crosses origins is refused so each new origin requires a fresh tool call
+ * (and thus a fresh provider/permission decision).
+ *
+ * @param a - one of the two URLs to compare.
+ * @param b - the other URL to compare.
+ * @returns true when `a` and `b` share scheme, hostname, and port.
+ */
+export declare function isSameOrigin(a: URL, b: URL): boolean;
+/**
+ * Classify a response `Content-Type` into a decodable body kind, or `undefined`
+ * for an unsupported (e.g. binary) type. `text/html` and `application/xhtml+xml`
+ * are `html`; other `text/*` plus a few structured text types are `text`.
+ *
+ * @param contentType - the raw `Content-Type` header, or `null` when the
+ *   response carries none (unsupported).
+ * @returns the decodable kind, or `undefined` for an unsupported type.
+ */
+export declare function classifyContentType(contentType: string | null): FetchableKind | undefined;
+/**
+ * Extract the `charset` parameter from a response `Content-Type`, lower-cased,
+ * or `undefined` when absent. The provider feeds this label to `TextDecoder`
+ * so a non-UTF-8 response is decoded with its declared encoding rather than
+ * silently mangled into replacement characters.
+ *
+ * @param contentType - the raw `Content-Type` header, or `null` when the
+ *   response carries none.
+ * @returns the lower-cased charset label, or `undefined` when none is declared.
+ */
+export declare function parseCharset(contentType: string | null): string | undefined;
+/**
+ * Build a `TextDecoder` for the declared charset, falling back to UTF-8 when
+ * none is declared. Throws {@link WebError} `WEB_UNSUPPORTED_CONTENT_TYPE` when
+ * the label is present but not a charset `TextDecoder` recognizes — better to
+ * fail loudly than return mojibake.
+ *
+ * @param charset - the declared charset label (from {@link parseCharset}), or
+ *   `undefined` to default to UTF-8.
+ * @returns a decoder for the declared (or defaulted) encoding.
+ */
+export declare function decoderForCharset(charset: string | undefined): TextDecoder;
+//# sourceMappingURL=policy.d.ts.map

package/lib/types/provider.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Safe HTTP(S) retrieval for `ctx.web`: validates URLs, follows only same-origin redirects,
+ * enforces time and size limits, classifies and decodes text, and leaves presentation to
+ * `@hydraharness/harness-tool-web`. Requests carry no browser cookies or ambient credentials.
+ *
+ * Connections enforce public IP destinations unless the operator grants an exact origin.
+ * @module @hydraharness/harness-web-fetch-http/provider
+ */
+import type { WebFetchProvider, WebFetchRequest, WebFetchResult } from '@hydraharness/harness-web';
+/** Resolved provider limits (the plugin's schemastery Config supplies defaults). */
+export interface HttpFetchLimits {
+    /** Maximum accepted request URL length. */
+    maxUrlLength: number;
+    /** Maximum response body size in bytes (read is aborted past this). */
+    maxResponseBytes: number;
+    /** Maximum decoded body length in characters (truncated past this). */
+    maxBodyChars: number;
+    /** Default fetch timeout in milliseconds. */
+    timeoutMs: number;
+    /** Maximum number of (same-origin) redirect hops to follow. */
+    maxRedirects: number;
+    /** `User-Agent` header sent on every request. */
+    userAgent: string;
+    /** Exact operator-granted origins allowed to reach non-public addresses. Defaults to none. */
+    allowedOrigins?: readonly string[];
+}
+/** Stable id this provider registers under. */
+export declare const LOCAL_FETCH_PROVIDER_ID = "http";
+/** The anonymous public HTTP(S) fetch provider. */
+export declare class HttpFetchProvider implements WebFetchProvider {
+    private readonly limits;
+    readonly id = "http";
+    private readonly allowedOrigins;
+    constructor(limits: HttpFetchLimits);
+    /** No credentials to check — an anonymous public fetcher is always usable. */
+    available(): boolean;
+    fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>;
+    /** Follow same-origin redirects up to the hop cap, then read the final response. */
+    private followAndRead;
+    private requestOnce;
+    /** Read, byte-cap, classify, and decode the final response body. */
+    private readBody;
+    /**
+     * Read the response stream up to `maxResponseBytes`. A `Content-Length` over
+     * the cap rejects immediately with `WEB_FETCH_TOO_LARGE`; a stream that grows
+     * past the cap is cut short (`truncatedByBytes`) rather than rejected, so a
+     * server that under-reports still yields a bounded usable body.
+     */
+    private readCapped;
+}
+//# sourceMappingURL=provider.d.ts.map

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@hydraharness/harness-web-fetch-http",
+  "description": "Anonymous public HTTP(S) fetch provider for the Hydra harness web capability seam (ctx.web)",
+  "hydra": {
+    "plugin": {
+      "application": "Retrieve publicly accessible HTTP or HTTPS pages without account credentials."
+    }
+  },
+  "version": "0.1.1-rc.6",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/web/web-fetch-http"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-timeout": "^0.1.1-rc.6",
+    "@hydraharness/harness-web": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2"
+  },
+  "dependencies": {
+    "undici": "^7.28.0",
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-timeout": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-web": "^0.1.1-rc.6"
+  }
+}