@ai-sdk/provider-utils 4.0.39 → 4.0.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/provider-utils",
-  "version": "4.0.39",
+  "version": "4.0.41",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -35,6 +35,7 @@
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
     "eventsource-parser": "^3.0.8",
+    "undici": "^5.29.0",
     "@ai-sdk/provider": "3.0.14"
   },
   "devDependencies": {

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

@@ -1,6 +1,7 @@
 import { cancelResponseBody } from './cancel-response-body';
 import { DownloadError } from './download-error';
 import { isBrowserRuntime } from './is-browser-runtime';
+import { getDefaultDownloadFetch } from './safe-node-fetch';
 import { validateDownloadUrl } from './validate-download-url';
 
 const MAX_DOWNLOAD_REDIRECTS = 10;
@@ -25,6 +26,11 @@ const MAX_DOWNLOAD_REDIRECTS = 10;
  * The returned response is the final (non-redirect) response. The caller is
  * responsible for checking `response.ok` and reading the body.
  *
+ * 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
+ * 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.
  */
@@ -52,6 +58,7 @@ export async function fetchWithValidatedRedirects({
   for (let redirectCount = 0; redirectCount <= maxRedirects; redirectCount++) {
     validateDownloadUrl(currentUrl);
 
+    const fetch = await getDefaultDownloadFetch();
     const response = await fetch(currentUrl, {
       ...baseInit,
       redirect: 'manual',

package/src/safe-node-fetch.ts

@@ -0,0 +1,209 @@
+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 ??= 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')
+  );
+}
+
+async function createSafeNodeFetch(): Promise<FetchFunction> {
+  // Node 20.16+ exposes getBuiltinModule; older supported Node versions use an
+  // indirect dynamic import. Keeping the specifier non-literal prevents browser
+  // bundlers from pulling Node built-ins into the provider-utils entry point.
+  const [{ createRequire }, { lookup }] = await Promise.all([
+    loadNodeModule<NodeModule>('node:module'),
+    loadNodeModule<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;
+}
+
+async function loadNodeModule<T>(id: string): Promise<T> {
+  const processWithBuiltins = globalThis.process as
+    | {
+        getBuiltinModule?: (id: string) => unknown;
+      }
+    | undefined;
+  const builtinModule = processWithBuiltins?.getBuiltinModule?.(id);
+
+  return builtinModule == null
+    ? ((await importNodeModule(id)) as T)
+    : (builtinModule as T);
+}
+
+function importNodeModule(id: string): Promise<unknown> {
+  return import(id);
+}
+
+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/types/tool.ts

@@ -171,8 +171,8 @@ export type Tool<
   strict?: boolean;
 
   /**
-   * Optional function that is called when the argument streaming starts.
-   * Only called when the tool is used in a streaming context.
+   * Optional function that is called when the model starts generating the tool input.
+   * In non-streaming contexts, it is called immediately before `onInputAvailable`.
    */
   onInputStart?: (options: ToolExecutionOptions) => void | PromiseLike<void>;
 

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;