@ai-sdk/provider-utils 4.0.27 → 4.0.29

package/package.json

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

package/src/download-blob.ts

@@ -1,9 +1,9 @@
 import { DownloadError } from './download-error';
+import { fetchWithValidatedRedirects } from './fetch-with-validated-redirects';
 import {
   readResponseWithSizeLimit,
   DEFAULT_MAX_DOWNLOAD_SIZE,
 } from './read-response-with-size-limit';
-import { validateDownloadUrl } from './validate-download-url';
 
 /**
  * Download a file from a URL and return it as a Blob.
@@ -20,17 +20,12 @@ export async function downloadBlob(
   url: string,
   options?: { maxBytes?: number; abortSignal?: AbortSignal },
 ): Promise<Blob> {
-  validateDownloadUrl(url);
   try {
-    const response = await fetch(url, {
-      signal: options?.abortSignal,
+    const response = await fetchWithValidatedRedirects({
+      url,
+      abortSignal: options?.abortSignal,
     });
 
-    // Validate final URL after redirects to prevent SSRF via open redirect
-    if (response.redirected) {
-      validateDownloadUrl(response.url);
-    }
-
     if (!response.ok) {
       throw new DownloadError({
         url,

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

@@ -0,0 +1,82 @@
+import { DownloadError } from './download-error';
+import { isBrowserRuntime } from './is-browser-runtime';
+import { validateDownloadUrl } from './validate-download-url';
+
+const MAX_DOWNLOAD_REDIRECTS = 10;
+
+/**
+ * Fetches a URL while enforcing the SSRF 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.
+ *
+ * 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.
+ *
+ * The returned response is the final (non-redirect) response. The caller is
+ * responsible for checking `response.ok` and reading the body.
+ *
+ * @throws DownloadError if a hop is unsafe, the redirect limit is exceeded, or
+ * a redirect cannot be validated on a non-browser runtime.
+ */
+export async function fetchWithValidatedRedirects({
+  url,
+  headers,
+  abortSignal,
+  maxRedirects = MAX_DOWNLOAD_REDIRECTS,
+}: {
+  url: string;
+  headers?: HeadersInit;
+  abortSignal?: AbortSignal;
+  maxRedirects?: number;
+}): 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;
+  }
+
+  let currentUrl = url;
+  // The bound also acts as a backstop against an unterminated redirect chain.
+  for (let redirectCount = 0; redirectCount <= maxRedirects; redirectCount++) {
+    validateDownloadUrl(currentUrl);
+
+    const response = await fetch(currentUrl, {
+      ...baseInit,
+      redirect: 'manual',
+    });
+
+    if (response.type === 'opaqueredirect') {
+      if (!isBrowserRuntime()) {
+        throw new DownloadError({
+          url,
+          message: `Redirect from ${currentUrl} could not be validated and was blocked`,
+        });
+      }
+      return await fetch(currentUrl, { ...baseInit, redirect: 'follow' });
+    }
+
+    const location = response.headers.get('location');
+    if (response.status >= 300 && response.status < 400 && location) {
+      currentUrl = new URL(location, currentUrl).toString();
+      continue;
+    }
+
+    return response;
+  }
+
+  throw new DownloadError({
+    url,
+    message: `Too many redirects (max ${maxRedirects})`,
+  });
+}

package/src/index.ts

@@ -15,6 +15,7 @@ export {
   readResponseWithSizeLimit,
   DEFAULT_MAX_DOWNLOAD_SIZE,
 } from './read-response-with-size-limit';
+export { fetchWithValidatedRedirects } from './fetch-with-validated-redirects';
 export * from './fetch-function';
 export { createIdGenerator, generateId, type IdGenerator } from './generate-id';
 export * from './get-error-message';
@@ -22,7 +23,9 @@ export * from './get-from-api';
 export { getRuntimeEnvironmentUserAgent } from './get-runtime-environment-user-agent';
 export { injectJsonInstructionIntoMessages } from './inject-json-instruction';
 export * from './is-abort-error';
+export { isBrowserRuntime } from './is-browser-runtime';
 export { isNonNullable } from './is-non-nullable';
+export { isSameOrigin } from './is-same-origin';
 export { isUrlSupported } from './is-url-supported';
 export * from './load-api-key';
 export { loadOptionalSetting } from './load-optional-setting';

package/src/is-browser-runtime.ts

@@ -0,0 +1,13 @@
+/**
+ * Returns `true` when running in a browser.
+ *
+ * Detection keys on the presence of a global `window`, matching the browser
+ * check used elsewhere in this package (see `getRuntimeEnvironmentUserAgent`)
+ * so the SDK has a single, consistent definition of "browser". Server runtimes
+ * (Node.js, Deno, Bun, edge/workers) do not define `window`.
+ */
+export function isBrowserRuntime(
+  globalThisAny: any = globalThis as any,
+): boolean {
+  return globalThisAny.window != null;
+}

package/src/is-same-origin.ts

@@ -0,0 +1,19 @@
+/**
+ * Returns true when `url` has the same origin (scheme + host + port) as
+ * `baseUrl`.
+ *
+ * Used to decide whether provider credentials may be attached to a request to a
+ * URL taken from a provider response (e.g. a polling or media-download URL).
+ * Credentials must only be sent to the provider's own origin; a response that
+ * names a foreign host (a CDN, or an attacker-controlled host if the response
+ * is tampered with) must not receive the API key.
+ *
+ * Returns false if either value is not a valid absolute URL (fail-closed).
+ */
+export function isSameOrigin(url: string, baseUrl: string): boolean {
+  try {
+    return new URL(url).origin === new URL(baseUrl).origin;
+  } catch {
+    return false;
+  }
+}

package/src/types/tool-approval-request.ts

@@ -13,4 +13,10 @@ export type ToolApprovalRequest = {
    * ID of the tool call that the approval request is for.
    */
   toolCallId: string;
+
+  /**
+   * HMAC-SHA256 signature binding this approval to its tool call.
+   * Present only when `experimental_toolApprovalSecret` is configured.
+   */
+  signature?: string;
 };

package/src/validate-download-url.ts

@@ -4,6 +4,10 @@ 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).
+ *
  * @param url - The URL string to validate.
  * @throws DownloadError if the URL is unsafe.
  */
@@ -31,7 +35,9 @@ export function validateDownloadUrl(url: string): void {
     });
   }
 
-  const hostname = parsed.hostname;
+  // Strip a trailing dot so a fully-qualified name like `localhost.` (which resolves
+  // identically to `localhost`) cannot bypass the hostname blocklist below.
+  const hostname = parsed.hostname.toLowerCase().replace(/\.+$/, '');
 
   // Block empty hostname
   if (!hostname) {
@@ -90,59 +96,135 @@ function isIPv4(hostname: string): boolean {
 
 function isPrivateIPv4(ip: string): boolean {
   const parts = ip.split('.').map(Number);
-  const [a, b] = parts;
+  const [a, b, c] = parts;
 
   // 0.0.0.0/8
   if (a === 0) return true;
   // 10.0.0.0/8
   if (a === 10) return true;
+  // 100.64.0.0/10 (CGNAT, used by some cloud providers for internal traffic)
+  if (a === 100 && b >= 64 && b <= 127) return true;
   // 127.0.0.0/8
   if (a === 127) return true;
   // 169.254.0.0/16
   if (a === 169 && b === 254) return true;
   // 172.16.0.0/12
   if (a === 172 && b >= 16 && b <= 31) return true;
+  // 192.0.0.0/24 (IETF protocol assignments)
+  if (a === 192 && b === 0 && c === 0) return true;
   // 192.168.0.0/16
   if (a === 192 && b === 168) return true;
+  // 198.18.0.0/15 (benchmarking)
+  if (a === 198 && (b === 18 || b === 19)) return true;
+  // 240.0.0.0/4 (reserved, includes 255.255.255.255 broadcast)
+  if (a >= 240) return true;
 
   return false;
 }
 
-function isPrivateIPv6(ip: string): boolean {
-  const normalized = ip.toLowerCase();
-
-  // ::1 (loopback)
-  if (normalized === '::1') return true;
-  // :: (unspecified)
-  if (normalized === '::') return true;
-
-  // Check for IPv4-mapped addresses (::ffff:x.x.x.x or ::ffff:HHHH:HHHH)
-  if (normalized.startsWith('::ffff:')) {
-    const mappedPart = normalized.slice(7);
-    // Dotted-decimal form: ::ffff:127.0.0.1
-    if (isIPv4(mappedPart)) {
-      return isPrivateIPv4(mappedPart);
-    }
-    // Hex form: ::ffff:7f00:1 (URL parser normalizes to this)
-    const hexParts = mappedPart.split(':');
-    if (hexParts.length === 2) {
-      const high = parseInt(hexParts[0], 16);
-      const low = parseInt(hexParts[1], 16);
-      if (!isNaN(high) && !isNaN(low)) {
-        const a = (high >> 8) & 0xff;
-        const b = high & 0xff;
-        const c = (low >> 8) & 0xff;
-        const d = low & 0xff;
-        return isPrivateIPv4(`${a}.${b}.${c}.${d}`);
+/**
+ * Expands an IPv6 address string into its 8 16-bit groups, handling `::`
+ * compression and an optional dotted-decimal IPv4 tail (e.g. `::ffff:127.0.0.1`).
+ *
+ * @returns the 8 groups, or null if the input is not a parseable IPv6 address.
+ */
+function parseIPv6(ip: string): number[] | null {
+  // Strip an optional zone id (e.g. `fe80::1%eth0`).
+  let address = ip.toLowerCase();
+  const zoneIndex = address.indexOf('%');
+  if (zoneIndex !== -1) {
+    address = address.slice(0, zoneIndex);
+  }
+
+  // At most one `::` compression marker is allowed.
+  const halves = address.split('::');
+  if (halves.length > 2) return null;
+
+  const toGroups = (segment: string): number[] | null => {
+    if (segment === '') return [];
+    const groups: number[] = [];
+    const parts = segment.split(':');
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      // A dotted-decimal IPv4 tail is only valid as the final part.
+      if (part.includes('.')) {
+        if (i !== parts.length - 1 || !isIPv4(part)) return null;
+        const [a, b, c, d] = part.split('.').map(Number);
+        groups.push((a << 8) | b, (c << 8) | d);
+        continue;
       }
+      if (!/^[0-9a-f]{1,4}$/.test(part)) return null;
+      groups.push(parseInt(part, 16));
     }
+    return groups;
+  };
+
+  const head = toGroups(halves[0]);
+  if (head === null) return null;
+
+  if (halves.length === 2) {
+    const tail = toGroups(halves[1]);
+    if (tail === null) return null;
+    const fill = 8 - head.length - tail.length;
+    if (fill < 0) return null;
+    return [...head, ...new Array<number>(fill).fill(0), ...tail];
   }
 
-  // fc00::/7 (unique local addresses - fc00:: and fd00::)
-  if (normalized.startsWith('fc') || normalized.startsWith('fd')) return true;
+  // No `::` compression: the address must contain exactly 8 groups.
+  return head.length === 8 ? head : null;
+}
+
+function isPrivateIPv6(ip: string): boolean {
+  const groups = parseIPv6(ip);
+
+  // Fail closed: if the address cannot be parsed, treat it as unsafe.
+  if (groups === null) return true;
+
+  const topZero = (count: number) =>
+    groups.slice(0, count).every(group => group === 0);
+
+  // ::1 (loopback) and :: (unspecified)
+  if (topZero(7) && (groups[7] === 0 || groups[7] === 1)) return true;
+
+  // fc00::/7 (unique local addresses)
+  if ((groups[0] & 0xfe00) === 0xfc00) return true;
 
   // fe80::/10 (link-local)
-  if (normalized.startsWith('fe80')) return true;
+  if ((groups[0] & 0xffc0) === 0xfe80) return true;
+
+  // fec0::/10 (site-local, deprecated but still routable internally)
+  if ((groups[0] & 0xffc0) === 0xfec0) return true;
+
+  // ff00::/8 (multicast)
+  if ((groups[0] & 0xff00) === 0xff00) return true;
+
+  // Addresses that embed an IPv4 address in their last 32 bits. For these we
+  // extract the embedded IPv4 and reuse the IPv4 private-range checks, so that
+  // e.g. ::ffff:127.0.0.1 or 64:ff9b::169.254.169.254 are blocked.
+  const embedsIPv4 =
+    // ::/96 — IPv4-compatible (deprecated)
+    topZero(6) ||
+    // ::ffff:0:0/96 — IPv4-mapped (ffff in group 5)
+    (topZero(5) && groups[5] === 0xffff) ||
+    // ::ffff:0:0/96 — IPv4-translated form (ffff in group 4, group 5 zero)
+    (topZero(4) && groups[4] === 0xffff && groups[5] === 0) ||
+    // 64:ff9b::/96 — NAT64 well-known prefix
+    (groups[0] === 0x0064 &&
+      groups[1] === 0xff9b &&
+      groups[2] === 0 &&
+      groups[3] === 0 &&
+      groups[4] === 0 &&
+      groups[5] === 0) ||
+    // 64:ff9b:1::/48 — NAT64 local-use prefix
+    (groups[0] === 0x0064 && groups[1] === 0xff9b && groups[2] === 0x0001);
+
+  if (embedsIPv4) {
+    const a = (groups[6] >> 8) & 0xff;
+    const b = groups[6] & 0xff;
+    const c = (groups[7] >> 8) & 0xff;
+    const d = groups[7] & 0xff;
+    return isPrivateIPv4(`${a}.${b}.${c}.${d}`);
+  }
 
   return false;
 }