@ai-sdk/provider-utils 5.0.6 → 5.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/provider-utils",
-  "version": "5.0.6",
+  "version": "5.0.9",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -35,7 +35,7 @@
     "@standard-schema/spec": "^1.1.0",
     "@workflow/serde": "4.1.0",
     "eventsource-parser": "^3.0.8",
-    "@ai-sdk/provider": "4.0.2"
+    "@ai-sdk/provider": "4.0.3"
   },
   "devDependencies": {
     "@types/node": "22.19.19",

package/src/connect-to-websocket.ts

@@ -0,0 +1,116 @@
+import { removeUndefinedEntries } from './remove-undefined-entries';
+import {
+  getWebSocketConstructor,
+  readWebSocketMessageText,
+  type WebSocketConstructor,
+  type WebSocketLike,
+} from './websocket';
+
+export interface WebSocketConnection {
+  /** Undefined when the constructor threw or the signal was already aborted. */
+  socket: WebSocketLike | undefined;
+  /**
+   * Unregisters the abort listener and closes the socket. Never throws.
+   * Handlers stay attached; callers guard their own terminal state.
+   */
+  close: (code?: number) => void;
+}
+
+/**
+ * Opens a WebSocket for a provider model, owning the transport-generic layer
+ * (analogous to `postToApi` for HTTP): constructor resolution, header hygiene,
+ * abort wiring, and message decoding. Callers own the URL, the auth channel
+ * (subprotocols vs headers), and the wire protocol.
+ */
+export function connectToWebSocket({
+  url,
+  protocols,
+  headers,
+  webSocket,
+  abortSignal,
+  onOpen,
+  onMessageText,
+  onProcessingError,
+  onSocketError,
+  onClose,
+  onAbort,
+}: {
+  url: string | URL;
+  protocols?: string | string[];
+  headers?: Record<string, string | undefined>;
+  webSocket?: WebSocketConstructor;
+  abortSignal?: AbortSignal;
+  onOpen?: (socket: WebSocketLike) => void;
+  /** One decoded message. Throws and rejections go to `onProcessingError`. */
+  onMessageText: (text: string) => void | PromiseLike<void>;
+  /** Constructor throws and message decoding/processing failures. */
+  onProcessingError: (error: unknown) => void;
+  onSocketError?: () => void;
+  onClose?: () => void;
+  /** Also called (without opening a socket) when the signal is already aborted. */
+  onAbort?: (reason: unknown) => void;
+}): WebSocketConnection {
+  let socket: WebSocketLike | undefined;
+  let abortListener: (() => void) | undefined;
+
+  const close = (code?: number) => {
+    if (abortListener != null) {
+      abortSignal?.removeEventListener('abort', abortListener);
+      abortListener = undefined;
+    }
+    try {
+      socket?.close(code);
+    } catch {
+      // socket may already be closed
+    }
+  };
+
+  if (abortSignal?.aborted) {
+    onAbort?.(abortSignal.reason ?? new Error('Aborted'));
+    return { socket: undefined, close };
+  }
+
+  try {
+    const WebSocketConstructor = getWebSocketConstructor(webSocket);
+    // native `WebSocket` ignores the headers option; header-capable
+    // implementations like `ws` forward it and throw on undefined values:
+    socket = new WebSocketConstructor(url, protocols, {
+      headers: removeUndefinedEntries(headers ?? {}),
+    });
+  } catch (error) {
+    onProcessingError(error);
+    return { socket: undefined, close };
+  }
+
+  if (abortSignal != null && onAbort != null) {
+    abortListener = () => onAbort(abortSignal.reason ?? new Error('Aborted'));
+    abortSignal.addEventListener('abort', abortListener, { once: true });
+  }
+
+  const openedSocket = socket;
+  socket.onopen = () => {
+    try {
+      onOpen?.(openedSocket);
+    } catch (error) {
+      onProcessingError(error);
+    }
+  };
+  // Messages are processed through a promise tail so async decoding (e.g.
+  // Blob frames) cannot reorder them, and error/close handling cannot
+  // overtake a still-decoding terminal frame.
+  let tail: Promise<void> = Promise.resolve();
+  socket.onmessage = event => {
+    tail = tail
+      .then(() => readWebSocketMessageText(event.data))
+      .then(text => onMessageText(text))
+      .catch(onProcessingError);
+  };
+  socket.onerror = () => {
+    tail = tail.then(() => onSocketError?.()).catch(onProcessingError);
+  };
+  socket.onclose = () => {
+    tail = tail.then(() => onClose?.()).catch(onProcessingError);
+  };
+
+  return { socket, close };
+}

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

@@ -1,30 +1,61 @@
 import { cancelResponseBody } from './cancel-response-body';
 import { DownloadError } from './download-error';
+import type { FetchFunction } from './fetch-function';
 import { isBrowserRuntime } from './is-browser-runtime';
+import { isSameOrigin } from './is-same-origin';
+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]);
+
 /**
- * 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.
+ * 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
+ * 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
+ * validated.
  *
  * The returned response is the final (non-redirect) response. The caller is
  * responsible for checking `response.ok` and reading the body.
  *
+ * Not solved here: this does string/literal checks only and does not resolve
+ * DNS, so a hostname that *resolves* to a private address, and DNS rebinding
+ * (the resolved IP flipping between validation and connect), are not blocked.
+ * Server deployments fetching untrusted URLs should constrain egress at the
+ * network layer or inject a Node `fetch` that pins the resolved IP at connect
+ * time — those need DNS/socket APIs not available on all target runtimes
+ * (edge, browser, Bun), so they are intentionally not built in.
+ *
  * @throws DownloadError if a hop is unsafe, the redirect limit is exceeded, or
  * a redirect cannot be validated on a non-browser runtime.
  */
@@ -33,29 +64,49 @@ export async function fetchWithValidatedRedirects({
   headers,
   abortSignal,
   maxRedirects = MAX_DOWNLOAD_REDIRECTS,
+  fetch = globalThis.fetch,
+  trustedOrigin,
 }: {
   url: string;
   headers?: HeadersInit;
   abortSignal?: AbortSignal;
   maxRedirects?: number;
+  fetch?: FetchFunction;
+  /**
+   * 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.
   for (let redirectCount = 0; redirectCount <= maxRedirects; redirectCount++) {
-    validateDownloadUrl(currentUrl);
+    // The developer-configured origin is trusted by definition; validating it
+    // would reject legitimate self-hosted / localhost deployments.
+    if (
+      trustedOrigin === undefined ||
+      !isSameOrigin(currentUrl, trustedOrigin)
+    ) {
+      validateDownloadUrl(currentUrl);
+    }
 
-    const response = await fetch(currentUrl, {
-      ...baseInit,
-      redirect: 'manual',
-    });
+    const response = await fetch(currentUrl, perHopInit('manual'));
 
     if (response.type === 'opaqueredirect') {
       if (!isBrowserRuntime()) {
@@ -64,16 +115,30 @@ 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) {
+    if (REDIRECT_STATUS_CODES.has(response.status) && 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
+      // hop. Whether that hop is followed or rejected by the guard, an
       // unconsumed 3xx body would leak the underlying socket.
       await cancelResponseBody(response);
-      currentUrl = new URL(location, currentUrl).toString();
+      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';
@@ -18,6 +20,9 @@ export const getFromApi = async <T>({
   failedResponseHandler,
   abortSignal,
   fetch = getOriginalFetch(),
+  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). Provider code in this repository
+   * must always pass it explicitly so every call site makes a visible trust
+   * decision — see `contributing/secure-url-handling.md`.
+   */
+  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,
-    });
+    // 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 fetch(url, {
+          method: 'GET',
+          headers: requestHeaders,
+          signal: abortSignal,
+        });
 
     const responseHeaders = extractResponseHeaders(response);
 

package/src/index.ts

@@ -1,6 +1,10 @@
 export { asArray } from './as-array';
 export type { Arrayable } from './as-array';
 export * from './combine-headers';
+export {
+  connectToWebSocket,
+  type WebSocketConnection,
+} from './connect-to-websocket';
 export { convertAsyncIteratorToReadableStream } from './convert-async-iterator-to-readable-stream';
 export { convertInlineFileDataToUint8Array } from './convert-inline-file-data-to-uint8-array';
 export { convertImageModelFileToDataUri } from './convert-image-model-file-to-data-uri';
@@ -91,7 +95,17 @@ export {
   type StreamingToolCallTrackerOptions,
 } from './streaming-tool-call-tracker';
 export { stripFileExtension } from './strip-file-extension';
+export {
+  TRANSCRIPTION_STREAM_AUDIO_DONE_FRAME_TYPE as EXPERIMENTAL_TRANSCRIPTION_STREAM_AUDIO_DONE_FRAME_TYPE,
+  TRANSCRIPTION_STREAM_START_FRAME_TYPE as EXPERIMENTAL_TRANSCRIPTION_STREAM_START_FRAME_TYPE,
+  parseTranscriptionStreamClientFrame as experimental_parseTranscriptionStreamClientFrame,
+  parseTranscriptionStreamPart as experimental_parseTranscriptionStreamPart,
+  serializeTranscriptionStreamPart as experimental_serializeTranscriptionStreamPart,
+  type TranscriptionStreamClientFrame as Experimental_TranscriptionStreamClientFrame,
+  type TranscriptionStreamStartFrame as Experimental_TranscriptionStreamStartFrame,
+} from './transcription-stream-envelope';
 export * from './uint8-utils';
+export { validateBaseURL } from './validate-base-url';
 export { validateDownloadUrl } from './validate-download-url';
 export * from './validate-types';
 export { VERSION } from './version';
@@ -99,6 +113,7 @@ export {
   getWebSocketConstructor,
   readWebSocketMessageText,
   toWebSocketUrl,
+  waitForWebSocketBufferDrain,
   type WebSocketConstructor,
   type WebSocketLike,
 } from './websocket';

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 — they're needed on the first hop of some
+ * provider polling calls. Instead, all caller headers except the user-agent are
+ * dropped on a cross-origin redirect (see `fetch-with-validated-redirects`).
+ */
+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;
+}