@ai-sdk/provider-utils 5.0.14 → 5.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/provider-utils",
-  "version": "5.0.14",
+  "version": "5.0.16",
   "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/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

@@ -39,6 +39,7 @@ export { isBuffer } from './is-buffer';
 export { isSameOrigin } from './is-same-origin';
 export { isNonNullable } from './is-non-nullable';
 export { isProviderReference } from './is-provider-reference';
+export { isRecord } from './is-record';
 export { isUrlSupported } from './is-url-supported';
 export * from './load-api-key';
 export { loadOptionalSetting } from './load-optional-setting';

package/src/is-record.ts

@@ -0,0 +1,6 @@
+/**
+ * Checks whether a value is a non-null, non-array object.
+ */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}

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/transcription-stream-envelope.ts

@@ -2,6 +2,7 @@ import type {
   Experimental_TranscriptionModelV4StreamPart as TranscriptionModelV4StreamPart,
   JSONObject,
 } from '@ai-sdk/provider';
+import { isRecord } from './is-record';
 import { secureJsonParse } from './secure-json-parse';
 
 /**
@@ -240,7 +241,7 @@ export function parseTranscriptionStreamPart(
     case 'transcript-delta':
       return isString(part.delta) &&
         isOptional(part.id, isString) &&
-        isOptional(part.providerMetadata, isPlainObject)
+        isOptional(part.providerMetadata, isRecord)
         ? part
         : undefined;
 
@@ -250,7 +251,7 @@ export function parseTranscriptionStreamPart(
         isOptional(part.startSecond, isNumber) &&
         isOptional(part.durationInSeconds, isNumber) &&
         isOptional(part.channelIndex, isNumber) &&
-        isOptional(part.providerMetadata, isPlainObject)
+        isOptional(part.providerMetadata, isRecord)
         ? part
         : undefined;
 
@@ -260,7 +261,7 @@ export function parseTranscriptionStreamPart(
         isOptional(part.startSecond, isNumber) &&
         isOptional(part.endSecond, isNumber) &&
         isOptional(part.channelIndex, isNumber) &&
-        isOptional(part.providerMetadata, isPlainObject)
+        isOptional(part.providerMetadata, isRecord)
         ? part
         : undefined;
 
@@ -270,7 +271,7 @@ export function parseTranscriptionStreamPart(
         part.segments.every(isSegment) &&
         isOptional(part.language, isString) &&
         isOptional(part.durationInSeconds, isNumber) &&
-        isOptional(part.providerMetadata, isPlainObject)
+        isOptional(part.providerMetadata, isRecord)
         ? part
         : undefined;
 
@@ -278,7 +279,7 @@ export function parseTranscriptionStreamPart(
       if (
         !(
           isOptional(part.modelId, isString) &&
-          isOptional(part.headers, isPlainObject)
+          isOptional(part.headers, isRecord)
         )
       ) {
         return undefined;
@@ -323,19 +324,15 @@ function isOptional(
   return value === undefined || check(value);
 }
 
-function isPlainObject(value: unknown): boolean {
-  return typeof value === 'object' && value != null && !Array.isArray(value);
-}
-
 function isWarning(value: unknown): boolean {
-  return isPlainObject(value) && isString((value as { type?: unknown }).type);
+  return isRecord(value) && isString(value.type);
 }
 
 function isSegment(value: unknown): boolean {
   return (
-    isPlainObject(value) &&
-    isString((value as { text?: unknown }).text) &&
-    isNumber((value as { startSecond?: unknown }).startSecond) &&
-    isNumber((value as { endSecond?: unknown }).endSecond)
+    isRecord(value) &&
+    isString(value.text) &&
+    isNumber(value.startSecond) &&
+    isNumber(value.endSecond)
   );
 }

package/src/types/index.ts

@@ -48,6 +48,12 @@ export {
 export type { ToolApprovalRequest } from './tool-approval-request';
 export type { ToolApprovalResponse } from './tool-approval-response';
 export type { ToolCall } from './tool-call';
+export {
+  getToolCaller as experimental_getToolCaller,
+  toolCaller as experimental_toolCaller,
+  type ToolCallerDefinition as Experimental_ToolCallerDefinition,
+  type ToolCallerTool as Experimental_ToolCallerTool,
+} from './tool-caller';
 export type {
   ToolExecuteFunction,
   ToolExecutionOptions,

package/src/types/tool-caller.ts

@@ -0,0 +1,36 @@
+import type { ProviderOptions } from './provider-options';
+import type { Tool } from './tool';
+import type { ToolSet } from './tool-set';
+
+const toolCallerSymbol = Symbol.for('vercel.ai.experimental.toolCaller');
+
+export type ToolCallerDefinition =
+  | {
+      type: 'local';
+      bind: (tools: ToolSet) => Tool;
+    }
+  | {
+      type: 'provider';
+      prepareProviderOptions: (
+        providerOptions: ProviderOptions | undefined,
+      ) => ProviderOptions;
+    };
+
+export type ToolCallerTool<TOOL extends Tool = Tool> = TOOL & {
+  readonly [toolCallerSymbol]: ToolCallerDefinition;
+};
+
+export function toolCaller<TOOL extends Tool>(
+  tool: TOOL,
+  definition: ToolCallerDefinition,
+): ToolCallerTool<TOOL> {
+  return Object.defineProperty({ ...tool }, toolCallerSymbol, {
+    value: definition,
+  }) as ToolCallerTool<TOOL>;
+}
+
+export function getToolCaller(
+  tool: Tool | undefined,
+): ToolCallerDefinition | undefined {
+  return (tool as ToolCallerTool | undefined)?.[toolCallerSymbol];
+}

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;