@ai-sdk/provider-utils 4.0.60 → 4.0.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/provider-utils",
-  "version": "4.0.60",
+  "version": "4.0.62",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",

package/src/encode-path-segment.ts

@@ -0,0 +1,15 @@
+/**
+ * Encodes a raw identifier as one URL path segment, including standalone dot
+ * segments that URL parsers would otherwise normalize. Pass unencoded values;
+ * for resource paths with intentional slashes, encode each segment separately.
+ */
+export function encodePathSegment(value: string): string {
+  const encodedValue = encodeURIComponent(value);
+
+  // URL parsing normalizes both literal and percent-encoded dot segments.
+  return encodedValue === '.'
+    ? '%252E'
+    : encodedValue === '..'
+      ? '%252E%252E'
+      : encodedValue;
+}

package/src/fetch-with-validated-redirects.ts

@@ -4,10 +4,16 @@ import type { FetchFunction } from './fetch-function';
 import { isBrowserRuntime } from './is-browser-runtime';
 import { isSameOrigin } from './is-same-origin';
 import { getDefaultDownloadFetch } from './safe-node-fetch';
+import { sanitizeRequestHeaders } from './sanitize-request-headers';
 import { validateDownloadUrl } from './validate-download-url';
 
 const MAX_DOWNLOAD_REDIRECTS = 10;
 
+// Redirect status codes per the fetch spec (https://fetch.spec.whatwg.org/#redirect-status).
+// Notably 300 (Multiple Choices) and 304 (Not Modified) are NOT redirects,
+// even when a server attaches a Location header.
+const REDIRECT_STATUS_CODES = new Set([301, 302, 303, 307, 308]);
+
 async function getValidatedFetch(
   customFetch: FetchFunction | undefined,
 ): Promise<FetchFunction> {
@@ -66,24 +72,34 @@ export async function fetchWithValidatedEndpoint({
 }
 
 /**
- * Fetches a URL while enforcing the SSRF download guard on every hop.
+ * Fetches a URL while enforcing the download guard on every hop.
  *
  * Redirects are followed manually (`redirect: 'manual'`) so each hop is
  * validated with {@link validateDownloadUrl} *before* it is requested. Relying
  * on the default `redirect: 'follow'` would issue the request to a redirect
  * target (e.g. an internal address) before we ever see its URL, defeating the
- * SSRF guard.
+ * guard.
+ *
+ * Request headers are also protected: {@link sanitizeRequestHeaders} strips
+ * proxy/metadata/cookie/hop-by-hop headers before the first request, and all
+ * caller headers except `User-Agent` are dropped on a cross-origin redirect.
+ * Credentials and custom headers are preserved on the first hop for backwards
+ * compatibility. The caller must ensure that the initial URL may receive them.
+ * The fetch spec only strips `Authorization` on cross-origin redirects because
+ * in a browser, CORS preflighting protects custom headers; there is no CORS on
+ * the server, so provider API keys carried in custom headers (e.g. `x-key`)
+ * must be dropped here as well.
  *
  * A `redirect: 'manual'` request yields an unreadable opaque response in the
  * browser (and in other spec-compliant fetch implementations), so the redirect
  * target cannot be validated here. In a real browser this is safe to follow
- * natively because SSRF is not reachable (fetch is constrained by CORS and
- * cannot reach a server's internal network or cloud-metadata). On any other
- * runtime we cannot validate the hop, so we fail closed rather than follow it
- * blindly and bypass the SSRF guard.
+ * natively because reaching an internal network is not possible (fetch is
+ * constrained by CORS and cannot reach a server's internal network or
+ * cloud-metadata). On any other runtime we cannot validate the hop, so we fail
+ * closed rather than follow it blindly and bypass the guard.
  *
  * A hop that is same-origin with `trustedOrigin` (the developer-configured
- * endpoint) skips target validation: that origin is exactly what an
+ * provider endpoint) skips target validation: that origin is exactly what an
  * unvalidated, config-derived request would fetch anyway, and validating it
  * would break legitimate self-hosted / localhost deployments whose response
  * URLs point back at the configured host. Hops on any other origin are always
@@ -94,7 +110,8 @@ export async function fetchWithValidatedEndpoint({
  *
  * On Node.js, the default fetch resolves every hostname through a validating
  * lookup hook and passes those exact addresses to the connector, preventing
- * hostname-to-private-IP and DNS-rebinding bypasses. Other runtimes should
+ * hostname-to-private-IP and DNS-rebinding bypasses. An injected fetch is
+ * responsible for equivalent connect-time validation. Other runtimes should
  * constrain egress at the network layer when handling untrusted URLs.
  *
  * @throws DownloadError if a hop is unsafe, the redirect limit is exceeded, or
@@ -114,18 +131,26 @@ export async function fetchWithValidatedRedirects({
   maxRedirects?: number;
   fetch?: FetchFunction;
   /**
-   * A developer-configured origin whose hops skip target validation. Must
-   * never be derived from response data.
+   * A developer-configured origin (e.g. the provider's `baseURL`) whose hops
+   * skip target validation. Must never be derived from response data.
    */
   trustedOrigin?: string;
 }): Promise<Response> {
-  // Per-hop request options. Only the `redirect` mode varies between hops, so
-  // the rest is assembled once. `headers` is omitted entirely when not provided
-  // so callers that send none issue a bare request.
-  const baseInit: RequestInit = { signal: abortSignal };
-  if (headers !== undefined) {
-    baseInit.headers = headers;
-  }
+  // Left undefined when no headers are provided (bare request); otherwise
+  // sanitized once and replaced on a cross-origin hop (credential drop below).
+  let currentHeaders =
+    headers === undefined ? undefined : sanitizeRequestHeaders(headers);
+
+  const perHopInit = (redirect: RequestRedirect): RequestInit => {
+    const init: RequestInit = { signal: abortSignal, redirect };
+    if (currentHeaders !== undefined) {
+      // Snapshot per hop: the platform fetch reads headers synchronously, but
+      // an injected fetch may defer, and hops between credential drops would
+      // otherwise share one instance.
+      init.headers = new Headers(currentHeaders);
+    }
+    return init;
+  };
 
   let currentUrl = url;
   // The bound also acts as a backstop against an unterminated redirect chain.
@@ -146,10 +171,7 @@ export async function fetchWithValidatedRedirects({
           ? globalThis.fetch
           : await getValidatedFetch(customFetch);
 
-    const response = await fetch(currentUrl, {
-      ...baseInit,
-      redirect: 'manual',
-    });
+    const response = await fetch(currentUrl, perHopInit('manual'));
 
     if (response.type === 'opaqueredirect') {
       if (!isBrowserRuntime()) {
@@ -158,16 +180,31 @@ export async function fetchWithValidatedRedirects({
           message: `Redirect from ${currentUrl} could not be validated and was blocked`,
         });
       }
-      return await fetch(currentUrl, { ...baseInit, redirect: 'follow' });
+      return await fetch(currentUrl, perHopInit('follow'));
     }
 
     const location = response.headers?.get('location');
-    if (response.status >= 300 && response.status < 400 && location) {
-      // Release the redirect response's connection before moving to the next
-      // hop. Whether that hop is followed or rejected by the SSRF guard, an
-      // unconsumed 3xx body would leak the underlying socket.
-      await cancelResponseBody(response);
-      currentUrl = new URL(location, currentUrl).toString();
+    if (REDIRECT_STATUS_CODES.has(response.status) && location) {
+      // Start releasing the redirect response's connection before moving to
+      // the next hop. Do not wait for cancellation: when a fetch wrapper keeps
+      // an unread response clone, tee cancellation can remain pending until
+      // the cloned branch is consumed.
+      void cancelResponseBody(response);
+      const nextUrl = new URL(location, currentUrl).toString();
+
+      // Drop all caller headers except the user-agent before following a
+      // redirect that crosses origin. Only stripping Authorization (as the
+      // fetch spec does) is not enough on the server: providers authenticate
+      // with custom headers too (e.g. `x-key`), and without CORS there is
+      // nothing else stopping them from riding to a foreign host.
+      if (currentHeaders !== undefined && !isSameOrigin(nextUrl, currentUrl)) {
+        const userAgent = currentHeaders.get('user-agent');
+        currentHeaders = new Headers(
+          userAgent == null ? undefined : { 'user-agent': userAgent },
+        );
+      }
+
+      currentUrl = nextUrl;
       continue;
     }
 

package/src/get-from-api.ts

@@ -1,8 +1,10 @@
 import { APICallError } from '@ai-sdk/provider';
 import { extractResponseHeaders } from './extract-response-headers';
+import { fetchWithValidatedRedirects } from './fetch-with-validated-redirects';
 import type { FetchFunction } from './fetch-function';
 import { handleFetchError } from './handle-fetch-error';
 import { isAbortError } from './is-abort-error';
+import { isSameOrigin } from './is-same-origin';
 import type { ResponseHandler } from './response-handler';
 import { getRuntimeEnvironmentUserAgent } from './get-runtime-environment-user-agent';
 import { withUserAgentSuffix } from './with-user-agent-suffix';
@@ -17,7 +19,10 @@ export const getFromApi = async <T>({
   successfulResponseHandler,
   failedResponseHandler,
   abortSignal,
-  fetch = getOriginalFetch(),
+  fetch,
+  validateUrl,
+  credentialedOrigin,
+  trustedOrigin,
 }: {
   url: string;
   headers?: Record<string, string | undefined>;
@@ -25,17 +30,67 @@ export const getFromApi = async <T>({
   successfulResponseHandler: ResponseHandler<T>;
   abortSignal?: AbortSignal;
   fetch?: FetchFunction;
+  /**
+   * Set `true` when `url` is untrusted (e.g. taken from a provider response
+   * body): it is routed through {@link fetchWithValidatedRedirects}, which
+   * rejects private/loopback/link-local targets and re-validates redirect
+   * hops; blocked URLs throw `DownloadError`. Set `false` only for URLs built
+   * from a developer-configured endpoint.
+   *
+   * Optional for backwards compatibility with existing callers; omitting it
+   * behaves like `false` (no validation).
+   */
+  validateUrl?: boolean;
+  /**
+   * When set, `headers` are sent only if `url` is same-origin with this origin
+   * (the user-agent suffix is always kept). Pass the provider's configured
+   * base URL alongside `validateUrl: true` so credentials never ride a request
+   * to a response-supplied host on a different origin (e.g. a CDN). Redirects
+   * that later cross origin drop all caller headers regardless (see
+   * {@link fetchWithValidatedRedirects}).
+   */
+  credentialedOrigin?: string;
+  /**
+   * A developer-configured origin (e.g. the provider's `baseURL`) that is
+   * exempt from URL validation when `validateUrl` is `true`. A response URL
+   * (or redirect hop) that is same-origin with it is fetched without target
+   * validation — it points at exactly the host a config-derived
+   * `validateUrl: false` request would fetch anyway, so blocking it would
+   * only break legitimate self-hosted / localhost deployments whose response
+   * URLs point back at the configured host. Hops on any other origin are
+   * still validated. Must never be derived from response data.
+   */
+  trustedOrigin?: string;
 }) => {
   try {
-    const response = await fetch(url, {
-      method: 'GET',
-      headers: withUserAgentSuffix(
-        headers,
-        `ai-sdk/provider-utils/${VERSION}`,
-        getRuntimeEnvironmentUserAgent(),
-      ),
-      signal: abortSignal,
-    });
+    const requestFetch = fetch ?? getOriginalFetch();
+
+    // Withhold caller headers when the URL is not same-origin with the origin
+    // allowed to receive credentials; the user-agent suffix is still applied.
+    const outgoingHeaders =
+      credentialedOrigin !== undefined && !isSameOrigin(url, credentialedOrigin)
+        ? {}
+        : headers;
+
+    const requestHeaders = withUserAgentSuffix(
+      outgoingHeaders,
+      `ai-sdk/provider-utils/${VERSION}`,
+      getRuntimeEnvironmentUserAgent(),
+    );
+
+    const response = validateUrl
+      ? await fetchWithValidatedRedirects({
+          url,
+          headers: requestHeaders,
+          abortSignal,
+          fetch,
+          trustedOrigin,
+        })
+      : await requestFetch(url, {
+          method: 'GET',
+          headers: requestHeaders,
+          signal: abortSignal,
+        });
 
     const responseHeaders = extractResponseHeaders(response);
 

package/src/index.ts

@@ -26,6 +26,7 @@ export {
 } from './fetch-with-validated-redirects';
 export * from './fetch-function';
 export { createIdGenerator, generateId, type IdGenerator } from './generate-id';
+export { encodePathSegment } from './encode-path-segment';
 export * from './get-error-message';
 export * from './get-from-api';
 export { getRuntimeEnvironmentUserAgent } from './get-runtime-environment-user-agent';

package/src/sanitize-request-headers.ts

@@ -0,0 +1,53 @@
+/**
+ * Request headers stripped before fetching an untrusted URL: host/virtual-host
+ * routing, proxy/origin spoofing, cloud-metadata, cookies, and hop-by-hop
+ * transport headers (RFC 7230 §6.1).
+ *
+ * `Authorization` and other credential-bearing caller headers (e.g. `x-key`)
+ * are intentionally not listed because trusted provider requests may need
+ * them. `fetchWithValidatedRedirects` drops all caller headers except the
+ * user-agent on a cross-origin redirect.
+ */
+const BLOCKED_REQUEST_HEADERS: readonly string[] = [
+  // Hop-by-hop / transport (RFC 7230 §6.1)
+  'connection',
+  'keep-alive',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+
+  // Host / virtual-host routing
+  'host',
+
+  // Proxy / origin spoofing
+  'forwarded',
+  'proxy-authorization',
+  'via',
+  'x-forwarded-for',
+  'x-forwarded-host',
+  'x-forwarded-proto',
+  'x-real-ip',
+
+  // Cloud metadata (GCP, AWS IMDSv1/v2, Azure, Alibaba, DigitalOcean)
+  'metadata',
+  'metadata-flavor',
+  'x-aws-ec2-metadata-token',
+  'x-metadata-token',
+
+  // Session / cookie
+  'cookie',
+  'set-cookie',
+];
+
+/**
+ * Returns a fresh `Headers` built from `input` with {@link BLOCKED_REQUEST_HEADERS}
+ * removed. The input is never mutated.
+ */
+export function sanitizeRequestHeaders(input: HeadersInit): Headers {
+  const headers = new Headers(input);
+  for (const name of BLOCKED_REQUEST_HEADERS) {
+    headers.delete(name);
+  }
+  return headers;
+}

package/src/validate-download-url.ts

@@ -46,11 +46,12 @@ export function validateDownloadUrl(url: string): void {
     });
   }
 
-  // Block localhost and .local domains
+  // Block localhost and domains reserved for local/private use.
   if (
     hostname === 'localhost' ||
     hostname.endsWith('.local') ||
-    hostname.endsWith('.localhost')
+    hostname.endsWith('.localhost') ||
+    hostname.endsWith('.internal')
   ) {
     throw new DownloadError({
       url,