@ai-sdk/provider-utils 5.0.13 → 5.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/provider-utils",
-  "version": "5.0.13",
+  "version": "5.0.15",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -35,6 +35,7 @@
     "@standard-schema/spec": "^1.1.0",
     "@workflow/serde": "4.1.0",
     "eventsource-parser": "^3.0.8",
+    "undici": "^7.28.0",
     "@ai-sdk/provider": "4.0.4"
   },
   "devDependencies": {

package/src/connect-to-websocket.ts

@@ -46,7 +46,11 @@ export function connectToWebSocket({
   /** Constructor throws and message decoding/processing failures. */
   onProcessingError: (error: unknown) => void;
   onSocketError?: () => void;
-  onClose?: () => void;
+  /**
+   * Receives the close code and reason when the transport provides them
+   * (native `CloseEvent` / `ws` close event).
+   */
+  onClose?: (info: { code?: number; reason?: string }) => void;
   /** Also called (without opening a socket) when the signal is already aborted. */
   onAbort?: (reason: unknown) => void;
 }): WebSocketConnection {
@@ -108,8 +112,20 @@ export function connectToWebSocket({
   socket.onerror = () => {
     tail = tail.then(() => onSocketError?.()).catch(onProcessingError);
   };
-  socket.onclose = () => {
-    tail = tail.then(() => onClose?.()).catch(onProcessingError);
+  socket.onclose = event => {
+    // Extract close diagnostics when the transport provides them (native
+    // `CloseEvent` and `ws` both carry `code` and `reason`).
+    const closeEvent = event as
+      | { code?: unknown; reason?: unknown }
+      | null
+      | undefined;
+    const code =
+      typeof closeEvent?.code === 'number' ? closeEvent.code : undefined;
+    const reason =
+      typeof closeEvent?.reason === 'string' ? closeEvent.reason : undefined;
+    tail = tail
+      .then(() => onClose?.({ code, reason }))
+      .catch(onProcessingError);
   };
 
   return { socket, close };

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

@@ -3,6 +3,7 @@ import { DownloadError } from './download-error';
 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';
 
@@ -48,13 +49,11 @@ const REDIRECT_STATUS_CODES = new Set([301, 302, 303, 307, 308]);
  * 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.
+ * 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. 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
  * a redirect cannot be validated on a non-browser runtime.
@@ -64,7 +63,7 @@ export async function fetchWithValidatedRedirects({
   headers,
   abortSignal,
   maxRedirects = MAX_DOWNLOAD_REDIRECTS,
-  fetch = globalThis.fetch,
+  fetch: customFetch,
   trustedOrigin,
 }: {
   url: string;
@@ -99,13 +98,17 @@ export async function fetchWithValidatedRedirects({
   for (let redirectCount = 0; redirectCount <= maxRedirects; redirectCount++) {
     // The developer-configured origin is trusted by definition; validating it
     // would reject legitimate self-hosted / localhost deployments.
-    if (
-      trustedOrigin === undefined ||
-      !isSameOrigin(currentUrl, trustedOrigin)
-    ) {
+    const isTrustedHop =
+      trustedOrigin !== undefined && isSameOrigin(currentUrl, trustedOrigin);
+
+    if (!isTrustedHop) {
       validateDownloadUrl(currentUrl);
     }
 
+    const fetch =
+      customFetch ??
+      (isTrustedHop ? globalThis.fetch : await getDefaultDownloadFetch());
+
     const response = await fetch(currentUrl, perHopInit('manual'));
 
     if (response.type === 'opaqueredirect') {

package/src/get-from-api.ts

@@ -19,7 +19,7 @@ export const getFromApi = async <T>({
   successfulResponseHandler,
   failedResponseHandler,
   abortSignal,
-  fetch = getOriginalFetch(),
+  fetch,
   validateUrl,
   credentialedOrigin,
   trustedOrigin,
@@ -65,6 +65,8 @@ export const getFromApi = async <T>({
   trustedOrigin?: string;
 }) => {
   try {
+    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 =
@@ -86,7 +88,7 @@ export const getFromApi = async <T>({
           fetch,
           trustedOrigin,
         })
-      : await fetch(url, {
+      : await requestFetch(url, {
           method: 'GET',
           headers: requestHeaders,
           signal: abortSignal,

package/src/index.ts

@@ -88,6 +88,7 @@ export {
   type ValidationResult,
 } from './schema';
 export { serializeModelOptions } from './serialize-model-options';
+export { SerializationError } from './serialization-error';
 export { secureJsonParse } from './secure-json-parse';
 export {
   StreamingToolCallTracker,

package/src/safe-node-fetch.ts

@@ -0,0 +1,204 @@
+import type * as nodeDnsModule from 'node:dns';
+import type * as nodeModule from 'node:module';
+import type * as undiciModule from 'undici';
+import type { FetchFunction } from './fetch-function';
+import { validateDownloadAddress } from './validate-download-url';
+
+type NodeDns = typeof nodeDnsModule;
+type NodeModule = typeof nodeModule;
+type Undici = typeof undiciModule;
+
+type LookupAddress = {
+  address: string;
+  family: number;
+};
+
+type LookupOptions = {
+  all?: boolean;
+  family?: number;
+  hints?: number;
+  order?: 'ipv4first' | 'ipv6first' | 'verbatim';
+  verbatim?: boolean;
+};
+
+type Lookup = (
+  hostname: string,
+  options: LookupOptions & { all: true },
+  callback: (
+    error: NodeJS.ErrnoException | null,
+    addresses: LookupAddress[],
+  ) => void,
+) => void;
+
+type LookupAllCallback = (
+  error: NodeJS.ErrnoException | null,
+  addresses: LookupAddress[],
+) => void;
+
+type LookupOneCallback = (
+  error: NodeJS.ErrnoException | null,
+  address: string,
+  family: number,
+) => void;
+
+type SafeLookup = {
+  (
+    hostname: string,
+    options: LookupOptions & { all: true },
+    callback: LookupAllCallback,
+  ): void;
+  (
+    hostname: string,
+    options: LookupOptions & { all?: false },
+    callback: LookupOneCallback,
+  ): void;
+};
+
+/**
+ * Creates a DNS lookup hook that validates every returned address before
+ * returning the callback shape requested by the HTTP connector. Because
+ * resolution and validation happen inside the connector, the socket is pinned
+ * to the validated result and DNS rebinding cannot introduce a second lookup.
+ */
+export function createSafeLookup(lookup: Lookup): SafeLookup {
+  return ((
+    hostname: string,
+    options: LookupOptions,
+    callback: LookupAllCallback | LookupOneCallback,
+  ): void => {
+    lookup(hostname, { ...options, all: true }, (error, addresses) => {
+      if (error) {
+        (callback as (error: Error) => void)(error);
+        return;
+      }
+
+      try {
+        const [firstAddress] = addresses;
+
+        if (firstAddress == null) {
+          throw new Error(`Hostname ${hostname} did not resolve to an address`);
+        }
+
+        for (const { address, family } of addresses) {
+          validateDownloadAddress({ address, family, hostname });
+        }
+
+        if (options.all === true) {
+          (callback as LookupAllCallback)(null, addresses);
+        } else {
+          (callback as LookupOneCallback)(
+            null,
+            firstAddress.address,
+            firstAddress.family,
+          );
+        }
+      } catch (error) {
+        (callback as (error: Error) => void)(
+          error instanceof Error ? error : new Error(String(error)),
+        );
+      }
+    });
+  }) as SafeLookup;
+}
+
+let safeNodeFetchPromise: Promise<FetchFunction> | undefined;
+const initialGlobalFetch = globalThis.fetch;
+const initialGlobalFetchIsNodeDefault = isNodeDefaultFetch(initialGlobalFetch);
+
+export function isNodeRuntime(): boolean {
+  const runtimeProcess = globalThis.process as
+    | {
+        release?: { name?: string };
+        versions?: { bun?: string };
+      }
+    | undefined;
+
+  return (
+    runtimeProcess?.release?.name === 'node' &&
+    runtimeProcess.versions?.bun == null
+  );
+}
+
+export async function getDefaultDownloadFetch(): Promise<FetchFunction> {
+  if (
+    !isNodeRuntime() ||
+    !initialGlobalFetchIsNodeDefault ||
+    globalThis.fetch !== initialGlobalFetch
+  ) {
+    return globalThis.fetch;
+  }
+
+  return (safeNodeFetchPromise ??= Promise.resolve().then(createSafeNodeFetch));
+}
+
+function isNodeDefaultFetch(fetch: FetchFunction): boolean {
+  const source = Function.prototype.toString.call(fetch);
+  return (
+    source.includes('internal/deps/undici') ||
+    source.includes('lazy loading of undici')
+  );
+}
+
+function createSafeNodeFetch(): FetchFunction {
+  // Load Node-only modules indirectly so browser bundlers do not pull undici
+  // and Node built-ins into the browser-facing provider-utils entry point.
+  const { createRequire } = loadBuiltinModule<NodeModule>('node:module');
+  const { lookup } = loadBuiltinModule<NodeDns>('node:dns');
+  const { Agent, fetch } = createRequire(getCurrentModulePath())(
+    'undici',
+  ) as Undici;
+
+  const dispatcher = new Agent({
+    connect: {
+      lookup: createSafeLookup(lookup as Lookup) as never,
+    },
+  });
+
+  return ((input, init) =>
+    fetch(
+      input as Parameters<typeof fetch>[0],
+      {
+        ...init,
+        dispatcher,
+      } as Parameters<typeof fetch>[1],
+    ) as unknown as Promise<Response>) satisfies FetchFunction;
+}
+
+function loadBuiltinModule<T>(id: string): T {
+  const processWithBuiltins = globalThis.process as
+    | {
+        getBuiltinModule?: (id: string) => unknown;
+      }
+    | undefined;
+  const builtinModule = processWithBuiltins?.getBuiltinModule?.(id);
+
+  if (builtinModule == null) {
+    throw new Error(`Node.js built-in module ${id} is unavailable`);
+  }
+
+  return builtinModule as T;
+}
+
+function getCurrentModulePath(): string {
+  // `import.meta.url` breaks when provider-utils is rebundled as CommonJS.
+  // The caller frame points at this package when loaded directly and at the
+  // consuming bundle when inlined, giving createRequire the correct base path.
+  const originalPrepareStackTrace = Error.prepareStackTrace;
+
+  try {
+    Error.prepareStackTrace = (_error, callSites) => callSites as never;
+
+    const error = new Error('Capture current module path');
+    Error.captureStackTrace(error, getCurrentModulePath);
+    const [caller] = error.stack as unknown as NodeJS.CallSite[];
+    const fileName = caller?.getFileName();
+
+    if (fileName == null) {
+      throw new Error('Unable to determine the current module path');
+    }
+
+    return fileName;
+  } finally {
+    Error.prepareStackTrace = originalPrepareStackTrace;
+  }
+}

package/src/serialization-error.ts

@@ -0,0 +1,23 @@
+import { AISDKError } from '@ai-sdk/provider';
+
+const name = 'AI_SerializationError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+export class SerializationError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  constructor({
+    message = 'Failed to serialize value.',
+    cause,
+  }: {
+    message?: string;
+    cause?: unknown;
+  } = {}) {
+    super({ name, message, cause });
+  }
+
+  static isInstance(error: unknown): error is SerializationError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/serialize-model-options.ts

@@ -1,6 +1,7 @@
 import type { JSONObject } from '@ai-sdk/provider';
 import { isJSONSerializable } from './is-json-serializable';
 import type { Resolvable } from './resolve';
+import { SerializationError } from './serialization-error';
 
 /**
  * Serializes a model instance for workflow step boundaries.
@@ -53,10 +54,10 @@ function resolveSync<T>(value: Resolvable<T>): T {
     next = (value as () => unknown)();
   }
 
-  // the serialization for workflows currently only supports synchronous values
-  // TODO introduce SerializationError
   if (next instanceof Promise) {
-    throw new Error('Promise returned from resolveSync');
+    throw new SerializationError({
+      message: 'Cannot serialize asynchronous model options.',
+    });
   }
 
   return next as T;

package/src/validate-download-url.ts

@@ -4,9 +4,8 @@ import { DownloadError } from './download-error';
  * Validates that a URL is safe to download from, blocking private/internal addresses
  * to prevent SSRF attacks.
  *
- * Note: this performs string/literal-IP checks only. It does not resolve DNS, so a
- * hostname that resolves to a private address is not blocked here (see callers, which
- * should additionally constrain egress at the network layer when handling untrusted URLs).
+ * Note: this function performs string/literal-IP checks only. The Node.js
+ * download fetch additionally validates and pins DNS results at connect time.
  *
  * @param url - The URL string to validate.
  * @throws DownloadError if the URL is unsafe.
@@ -83,6 +82,34 @@ export function validateDownloadUrl(url: string): void {
   }
 }
 
+/**
+ * Validates an address returned by DNS before it is used to open a socket.
+ * This is intentionally not exported from the package entry point.
+ */
+export function validateDownloadAddress({
+  address,
+  family,
+  hostname,
+}: {
+  address: string;
+  family: number;
+  hostname: string;
+}): void {
+  const isUnsafe =
+    family === 4
+      ? !isIPv4(address) || isPrivateIPv4(address)
+      : family === 6
+        ? isPrivateIPv6(address)
+        : true;
+
+  if (isUnsafe) {
+    throw new DownloadError({
+      url: hostname,
+      message: `Hostname ${hostname} resolved to disallowed IP address ${address}`,
+    });
+  }
+}
+
 function isIPv4(hostname: string): boolean {
   const parts = hostname.split('.');
   if (parts.length !== 4) return false;