@warlock.js/ai-tools 4.15.0 → 5.0.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to `@warlock.js/ai-tools` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.0.0 - 2026-08-25
+
+### Changed
+
+- This package is unchanged in 5.0.0; its version moved only because the Warlock family releases in lockstep.
+
+## 4.16.0 - 2026-08-18
+
+### Security
+
+- **`fetch_url` and `http_request` now deny private-network targets by default and route through `@warlock.js/ai`'s hardened `guardedFetch` instead of a local host check.** Previously `allowHosts` was the *only* SSRF guardrail and it was opt-in — a bare `ai.tools.fetchUrl()` / `ai.tools.http()` would fetch any `http(s)` URL the model supplied, including `http://169.254.169.254/latest/meta-data/...`, `localhost`, and RFC1918 addresses, and neither tool re-validated redirect targets, so even a configured allowlist could be 302'd into an internal endpoint. Both tools now issue every request through the core outbound policy, which by default refuses private / loopback / link-local / CGNAT / cloud-metadata addresses — resolving hostnames through DNS and checking every returned address, failing closed on resolution failure — and re-validates every redirect `Location` (scheme, allowlist, private-IP deny) before following it, with a hop cap and cross-origin credential-header stripping. Blocks surface as the existing typed errors (`WebToolError` `type: "denied-host"`, `HttpPolicyError` `type: "host-not-allowed"`), so agents still read them as `{ error }` data
+- **New `allowPrivateNetwork` option (default `false`) on both tools** for the deliberate case of a tool that must call an internal service (e.g. a local dev server); `allowHosts` still works and now also constrains redirect targets
+
 ## 4.12.0
 
 ### Changed

package/cjs/index.cjs

@@ -370,8 +370,16 @@ function isJsonContentType(contentType) {
 * - **Method allowlist** — `allowMethods` (default `["GET"]`). A method
 *   outside the list is rejected with a typed
 *   {@link HttpPolicyError} (`type: "method-not-allowed"`).
+* - **Private-network deny (default).** The request — and every redirect
+*   hop — goes through the framework's `guardedFetch` outbound policy,
+*   which refuses private / loopback / link-local / cloud-metadata
+*   addresses (and hostnames resolving to them) unless
+*   `allowPrivateNetwork: true` is set. This applies even when
+*   `allowHosts` is not configured, so a bare `ai.tools.http()` is not
+*   an SSRF primitive (`type: "host-not-allowed"`).
 * - **Host allowlist** — when `allowHosts` is set, any other host is
-*   rejected (`type: "host-not-allowed"`), an SSRF guardrail.
+*   rejected (`type: "host-not-allowed"`), an SSRF guardrail; redirect
+*   targets are held to the same allowlist.
 * - **`baseUrl` join** — when configured, the model passes a path that
 *   is resolved against `baseUrl`; otherwise it must pass an absolute
 *   `http(s)` URL. An unresolvable URL is rejected
@@ -413,6 +421,7 @@ function httpRequestTool(options = {}) {
 	const allowMethods = options.allowMethods ?? ["GET"];
 	const allowedMethodSet = new Set(allowMethods);
 	const allowHostSet = options.allowHosts ? new Set(options.allowHosts) : void 0;
+	const allowPrivateNetwork = options.allowPrivateNetwork ?? false;
 	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS$1;
 	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES$1;
 	const staticHeaders = options.headers;
@@ -436,22 +445,25 @@ function httpRequestTool(options = {}) {
 				body = JSON.stringify(input.body);
 				if (!Object.keys(headers).some((key) => key.toLowerCase() === "content-type")) headers["content-type"] = "application/json";
 			}
-			const controller = new AbortController();
-			const timer = setTimeout(() => controller.abort(), timeoutMs);
-			const onAbort = () => controller.abort();
-			if (ctx?.signal) if (ctx.signal.aborted) controller.abort();
-			else ctx.signal.addEventListener("abort", onAbort, { once: true });
 			let response;
 			try {
-				response = await fetch(url, {
+				response = await (0, _warlock_js_ai.guardedFetch)(url.toString(), {
+					allowedSchemes: ["http", "https"],
+					hostAllowlist: options.allowHosts,
+					denyPrivateIPsAfterDNS: !allowPrivateNetwork,
+					timeoutMs,
+					signal: ctx?.signal
+				}, {
 					method,
 					headers,
-					body,
-					signal: controller.signal
+					body
+				});
+			} catch (cause) {
+				if (cause instanceof _warlock_js_ai.OutboundPolicyError) throw new HttpPolicyError(`http_request blocked: ${cause.message}`, {
+					type: "host-not-allowed",
+					cause
 				});
-			} finally {
-				clearTimeout(timer);
-				ctx?.signal?.removeEventListener("abort", onAbort);
+				throw cause;
 			}
 			const responseHeaders = {};
 			response.headers.forEach((value, key) => {
@@ -2267,8 +2279,16 @@ function stripTags(html) {
 * `fetch` (Node 18+) and hand the model back rendered `content`.
 *
 * Guardrails, applied in order before/around the network call:
+* - **Private-network deny (default).** Every request — and every
+*   redirect hop — goes through the framework's `guardedFetch` outbound
+*   policy, which refuses private / loopback / link-local /
+*   cloud-metadata addresses (and hostnames resolving to them) unless
+*   `allowPrivateNetwork: true` is set. This applies even when
+*   `allowHosts` is not configured, so a bare `ai.tools.fetchUrl()` is
+*   not an SSRF primitive.
 * - **`allowHosts`** — when set, a request to any host not in the list is
-*   rejected before the fetch (an SSRF guardrail).
+*   rejected before the fetch, and redirect targets are held to the same
+*   allowlist.
 * - **`timeoutMs`** — the request is aborted via `AbortSignal.timeout`
 *   (default {@link DEFAULT_TIMEOUT_MS}).
 * - **`maxBytes`** — the response body is read up to this cap and the
@@ -2298,6 +2318,7 @@ function fetchUrlTool(options) {
 	const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
 	const extract = options?.extract ?? DEFAULT_EXTRACT;
 	const allowHosts = options?.allowHosts;
+	const allowPrivateNetwork = options?.allowPrivateNetwork ?? false;
 	if (extract !== "html") loadReadability();
 	return (0, _warlock_js_ai.tool)({
 		name: options?.name ?? DEFAULT_NAME$1,
@@ -2308,8 +2329,17 @@ function fetchUrlTool(options) {
 			assertHostAllowed(url, allowHosts);
 			let response;
 			try {
-				response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+				response = await (0, _warlock_js_ai.guardedFetch)(url.toString(), {
+					allowedSchemes: ["http", "https"],
+					hostAllowlist: allowHosts,
+					denyPrivateIPsAfterDNS: !allowPrivateNetwork,
+					timeoutMs
+				});
 			} catch (cause) {
+				if (cause instanceof _warlock_js_ai.OutboundPolicyError) throw new WebToolError(`fetch_url blocked: ${cause.message}`, {
+					type: "denied-host",
+					cause
+				});
 				throw new WebToolError(`fetch_url request failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
 					type: "request-failed",
 					cause