@ai-sdk/provider-utils 3.0.24 → 3.0.26

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @ai-sdk/provider-utils
 
+## 3.0.26
+
+### Patch Changes
+
+- 9f67efe: fix: only send provider credentials to same-origin response-supplied URLs
+
+  Several provider clients followed a URL taken from the provider's API response (a polling/status URL or a final media URL such as `polling_url`, `urls.get`, `result_url`, `result.sample`, or `video.uri`) and reused the authenticated headers — or appended `?key=<API_KEY>` — on that request. Because the host of the response-supplied URL was never validated, the long-lived API key was sent to whatever host the response named (a CDN in the benign case, or an attacker-chosen host if the provider response was tampered with), allowing credential exfiltration.
+
+  A new `isSameOrigin` helper is added to `@ai-sdk/provider-utils`, and the affected fetches in `@ai-sdk/black-forest-labs`, `@ai-sdk/fireworks`, `@ai-sdk/replicate`, `@ai-sdk/gladia`, `@ai-sdk/fal`, and `@ai-sdk/google` now attach credentials only when the followed URL is same-origin with the provider's configured API origin. Requests to a foreign origin are made without the credential.
+
+- eea9166: fix: harden download URL SSRF guard against hostname and redirect bypasses
+
+  `validateDownloadUrl` and the file download helpers (`downloadBlob`, `download`) could be bypassed in several ways when handling untrusted URLs:
+
+  - A fully-qualified hostname with a trailing dot (e.g. `localhost.`, `myhost.local.`) skipped the localhost/`.local` blocklist.
+  - IPv6 addresses that embed an IPv4 address in their last 32 bits — IPv4-compatible (`::127.0.0.1`), IPv4-translated (`::ffff:0:127.0.0.1`), and NAT64 (`64:ff9b::127.0.0.1`, including the `64:ff9b:1::/48` local-use prefix) — were not decoded and checked against the private IPv4 ranges.
+  - Redirects were validated only _after_ `fetch` had already followed them, so the request to a redirect target (e.g. an internal/metadata address) had already been issued before the check ran.
+  - Several reserved/internal address ranges were not blocked: CGNAT (`100.64.0.0/10`, used by some cloud providers for internal traffic), benchmarking (`198.18.0.0/15`), IETF protocol assignments (`192.0.0.0/24`), the reserved `240.0.0.0/4` block (including the `255.255.255.255` broadcast address), and IPv6 site-local (`fec0::/10`) and multicast (`ff00::/8`).
+
+  The validator now strips trailing dots before the hostname checks and fully expands IPv6 addresses to detect embedded private IPv4 targets. The download helpers now follow redirects manually (`redirect: 'manual'`), re-validating each hop before requesting it, so an unsafe redirect target is never fetched. When a redirect cannot be inspected because the runtime returns an opaque response, the helpers fail closed (reject the redirect) on the server; only in a real browser — where SSRF is not reachable (fetch is constrained by CORS and cannot reach a server's internal network or cloud-metadata endpoints) — is the redirect followed natively so legitimate redirected downloads keep working.
+
+## 3.0.25
+
+### Patch Changes
+
+- 783fa6c: chore: ensure consistent import handling and avoid import duplicates or cycles
+- Updated dependencies [783fa6c]
+  - @ai-sdk/provider@2.0.3
+
 ## 3.0.24
 
 ### Patch Changes

package/dist/index.d.mts

@@ -72,6 +72,46 @@ declare class DownloadError extends AISDKError {
     static isInstance(error: unknown): error is DownloadError;
 }
 
+/**
+ * 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.
+ */
+declare function fetchWithValidatedRedirects({ url, headers, abortSignal, maxRedirects, }: {
+    url: string;
+    headers?: HeadersInit;
+    abortSignal?: AbortSignal;
+    maxRedirects?: number;
+}): Promise<Response>;
+
+/**
+ * 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`.
+ */
+declare function isBrowserRuntime(globalThisAny?: any): boolean;
+
 /**
  * Default maximum download size: 2 GiB.
  *
@@ -279,6 +319,20 @@ declare function injectJsonInstructionIntoMessages({ messages, schema, schemaPre
 
 declare function isAbortError(error: unknown): error is Error;
 
+/**
+ * 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).
+ */
+declare function isSameOrigin(url: string, baseUrl: string): boolean;
+
 /**
  * Checks if the given URL is supported natively by the model.
  *
@@ -447,7 +501,6 @@ type InferSchema<SCHEMA> = SCHEMA extends z3.Schema ? z3.infer<SCHEMA> : SCHEMA
 declare function jsonSchema<OBJECT = unknown>(jsonSchema: JSONSchema7 | (() => JSONSchema7), { validate, }?: {
     validate?: (value: unknown) => ValidationResult<OBJECT> | PromiseLike<ValidationResult<OBJECT>>;
 }): Schema<OBJECT>;
-declare function asSchema<OBJECT>(schema: FlexibleSchema<OBJECT> | undefined): Schema<OBJECT>;
 
 /**
 Additional provider-specific options.
@@ -868,6 +921,8 @@ type Resolvable<T> = T | Promise<T> | (() => T) | (() => Promise<T>);
  */
 declare function resolve<T>(value: Resolvable<T>): Promise<T>;
 
+declare function asSchema<OBJECT>(schema: FlexibleSchema<OBJECT> | undefined): Schema<OBJECT>;
+
 declare function convertBase64ToUint8Array(base64String: string): Uint8Array<ArrayBuffer>;
 declare function convertUint8ArrayToBase64(array: Uint8Array): string;
 declare function convertToBase64(value: string | Uint8Array): string;
@@ -876,6 +931,10 @@ declare function convertToBase64(value: string | Uint8Array): string;
  * 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.
  */
@@ -1013,4 +1072,4 @@ interface ToolResult<NAME extends string, INPUT, OUTPUT> {
     dynamic?: boolean;
 }
 
-export { type AssistantContent, type AssistantModelMessage, DEFAULT_MAX_DOWNLOAD_SIZE, type DataContent, DelayedPromise, DownloadError, type FetchFunction, type FilePart, type FlexibleSchema, type FlexibleValidator, type IdGenerator, type ImagePart, type InferSchema, type InferToolInput, type InferToolOutput, type InferValidator, type LazySchema, type LazyValidator, type ModelMessage, type ParseResult, type ProviderDefinedToolFactory, type ProviderDefinedToolFactoryWithOutputSchema, type ProviderOptions, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type SystemModelMessage, type TextPart, type Tool, type ToolCall, type ToolCallOptions, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolModelMessage, type ToolResult, type ToolResultPart, type UserContent, type UserModelMessage, VERSION, type ValidationResult, type Validator, asSchema, asValidator, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertToBase64, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createJsonStreamResponseHandler, createProviderDefinedToolFactory, createProviderDefinedToolFactoryWithOutputSchema, createStatusCodeErrorResponseHandler, delay, dynamicTool, executeTool, extractResponseHeaders, generateId, getErrorMessage, getFromApi, getRuntimeEnvironmentUserAgent, injectJsonInstructionIntoMessages, isAbortError, isParsableJson, isUrlSupported, isValidator, jsonSchema, lazySchema, lazyValidator, loadApiKey, loadOptionalSetting, loadSetting, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, readResponseWithSizeLimit, removeUndefinedEntries, resolve, safeParseJSON, safeValidateTypes, standardSchemaValidator, tool, validateDownloadUrl, validateTypes, validator, withUserAgentSuffix, withoutTrailingSlash, zodSchema };
+export { type AssistantContent, type AssistantModelMessage, DEFAULT_MAX_DOWNLOAD_SIZE, type DataContent, DelayedPromise, DownloadError, type FetchFunction, type FilePart, type FlexibleSchema, type FlexibleValidator, type IdGenerator, type ImagePart, type InferSchema, type InferToolInput, type InferToolOutput, type InferValidator, type LazySchema, type LazyValidator, type ModelMessage, type ParseResult, type ProviderDefinedToolFactory, type ProviderDefinedToolFactoryWithOutputSchema, type ProviderOptions, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type SystemModelMessage, type TextPart, type Tool, type ToolCall, type ToolCallOptions, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolModelMessage, type ToolResult, type ToolResultPart, type UserContent, type UserModelMessage, VERSION, type ValidationResult, type Validator, asSchema, asValidator, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertToBase64, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createJsonStreamResponseHandler, createProviderDefinedToolFactory, createProviderDefinedToolFactoryWithOutputSchema, createStatusCodeErrorResponseHandler, delay, dynamicTool, executeTool, extractResponseHeaders, fetchWithValidatedRedirects, generateId, getErrorMessage, getFromApi, getRuntimeEnvironmentUserAgent, injectJsonInstructionIntoMessages, isAbortError, isBrowserRuntime, isParsableJson, isSameOrigin, isUrlSupported, isValidator, jsonSchema, lazySchema, lazyValidator, loadApiKey, loadOptionalSetting, loadSetting, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, readResponseWithSizeLimit, removeUndefinedEntries, resolve, safeParseJSON, safeValidateTypes, standardSchemaValidator, tool, validateDownloadUrl, validateTypes, validator, withUserAgentSuffix, withoutTrailingSlash, zodSchema };

package/dist/index.d.ts

@@ -72,6 +72,46 @@ declare class DownloadError extends AISDKError {
     static isInstance(error: unknown): error is DownloadError;
 }
 
+/**
+ * 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.
+ */
+declare function fetchWithValidatedRedirects({ url, headers, abortSignal, maxRedirects, }: {
+    url: string;
+    headers?: HeadersInit;
+    abortSignal?: AbortSignal;
+    maxRedirects?: number;
+}): Promise<Response>;
+
+/**
+ * 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`.
+ */
+declare function isBrowserRuntime(globalThisAny?: any): boolean;
+
 /**
  * Default maximum download size: 2 GiB.
  *
@@ -279,6 +319,20 @@ declare function injectJsonInstructionIntoMessages({ messages, schema, schemaPre
 
 declare function isAbortError(error: unknown): error is Error;
 
+/**
+ * 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).
+ */
+declare function isSameOrigin(url: string, baseUrl: string): boolean;
+
 /**
  * Checks if the given URL is supported natively by the model.
  *
@@ -447,7 +501,6 @@ type InferSchema<SCHEMA> = SCHEMA extends z3.Schema ? z3.infer<SCHEMA> : SCHEMA
 declare function jsonSchema<OBJECT = unknown>(jsonSchema: JSONSchema7 | (() => JSONSchema7), { validate, }?: {
     validate?: (value: unknown) => ValidationResult<OBJECT> | PromiseLike<ValidationResult<OBJECT>>;
 }): Schema<OBJECT>;
-declare function asSchema<OBJECT>(schema: FlexibleSchema<OBJECT> | undefined): Schema<OBJECT>;
 
 /**
 Additional provider-specific options.
@@ -868,6 +921,8 @@ type Resolvable<T> = T | Promise<T> | (() => T) | (() => Promise<T>);
  */
 declare function resolve<T>(value: Resolvable<T>): Promise<T>;
 
+declare function asSchema<OBJECT>(schema: FlexibleSchema<OBJECT> | undefined): Schema<OBJECT>;
+
 declare function convertBase64ToUint8Array(base64String: string): Uint8Array<ArrayBuffer>;
 declare function convertUint8ArrayToBase64(array: Uint8Array): string;
 declare function convertToBase64(value: string | Uint8Array): string;
@@ -876,6 +931,10 @@ declare function convertToBase64(value: string | Uint8Array): string;
  * 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.
  */
@@ -1013,4 +1072,4 @@ interface ToolResult<NAME extends string, INPUT, OUTPUT> {
     dynamic?: boolean;
 }
 
-export { type AssistantContent, type AssistantModelMessage, DEFAULT_MAX_DOWNLOAD_SIZE, type DataContent, DelayedPromise, DownloadError, type FetchFunction, type FilePart, type FlexibleSchema, type FlexibleValidator, type IdGenerator, type ImagePart, type InferSchema, type InferToolInput, type InferToolOutput, type InferValidator, type LazySchema, type LazyValidator, type ModelMessage, type ParseResult, type ProviderDefinedToolFactory, type ProviderDefinedToolFactoryWithOutputSchema, type ProviderOptions, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type SystemModelMessage, type TextPart, type Tool, type ToolCall, type ToolCallOptions, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolModelMessage, type ToolResult, type ToolResultPart, type UserContent, type UserModelMessage, VERSION, type ValidationResult, type Validator, asSchema, asValidator, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertToBase64, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createJsonStreamResponseHandler, createProviderDefinedToolFactory, createProviderDefinedToolFactoryWithOutputSchema, createStatusCodeErrorResponseHandler, delay, dynamicTool, executeTool, extractResponseHeaders, generateId, getErrorMessage, getFromApi, getRuntimeEnvironmentUserAgent, injectJsonInstructionIntoMessages, isAbortError, isParsableJson, isUrlSupported, isValidator, jsonSchema, lazySchema, lazyValidator, loadApiKey, loadOptionalSetting, loadSetting, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, readResponseWithSizeLimit, removeUndefinedEntries, resolve, safeParseJSON, safeValidateTypes, standardSchemaValidator, tool, validateDownloadUrl, validateTypes, validator, withUserAgentSuffix, withoutTrailingSlash, zodSchema };
+export { type AssistantContent, type AssistantModelMessage, DEFAULT_MAX_DOWNLOAD_SIZE, type DataContent, DelayedPromise, DownloadError, type FetchFunction, type FilePart, type FlexibleSchema, type FlexibleValidator, type IdGenerator, type ImagePart, type InferSchema, type InferToolInput, type InferToolOutput, type InferValidator, type LazySchema, type LazyValidator, type ModelMessage, type ParseResult, type ProviderDefinedToolFactory, type ProviderDefinedToolFactoryWithOutputSchema, type ProviderOptions, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type SystemModelMessage, type TextPart, type Tool, type ToolCall, type ToolCallOptions, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolModelMessage, type ToolResult, type ToolResultPart, type UserContent, type UserModelMessage, VERSION, type ValidationResult, type Validator, asSchema, asValidator, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertToBase64, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createJsonStreamResponseHandler, createProviderDefinedToolFactory, createProviderDefinedToolFactoryWithOutputSchema, createStatusCodeErrorResponseHandler, delay, dynamicTool, executeTool, extractResponseHeaders, fetchWithValidatedRedirects, generateId, getErrorMessage, getFromApi, getRuntimeEnvironmentUserAgent, injectJsonInstructionIntoMessages, isAbortError, isBrowserRuntime, isParsableJson, isSameOrigin, isUrlSupported, isValidator, jsonSchema, lazySchema, lazyValidator, loadApiKey, loadOptionalSetting, loadSetting, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, readResponseWithSizeLimit, removeUndefinedEntries, resolve, safeParseJSON, safeValidateTypes, standardSchemaValidator, tool, validateDownloadUrl, validateTypes, validator, withUserAgentSuffix, withoutTrailingSlash, zodSchema };