@ai-sdk/provider-utils 4.0.60 → 4.0.61

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @ai-sdk/provider-utils
 
+## 4.0.61
+
+### Patch Changes
+
+- 5aa3086: feat(openai-compatible): support URL-based image responses
+
+  Add opt-in URL validation and credential origin handling to `getFromApi` for URL-based image responses. Validate redirect targets, strip unsafe request headers, and drop credentials on cross-origin redirects while preserving existing unvalidated requests.
+
 ## 4.0.60
 
 ### Patch Changes

package/dist/index.d.mts

@@ -250,24 +250,34 @@ declare function fetchWithValidatedEndpoint({ url, init, fetch: customFetch, tru
     redirect?: 'error' | 'manual';
 }): Promise<Response>;
 /**
- * Fetches a URL while enforcing the SSRF download guard on every hop.
+ * Fetches a URL while enforcing the 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.
+ * guard.
+ *
+ * Request headers are also protected: {@link sanitizeRequestHeaders} strips
+ * proxy/metadata/cookie/hop-by-hop headers before the first request, and all
+ * caller headers except `User-Agent` are dropped on a cross-origin redirect.
+ * Credentials and custom headers are preserved on the first hop for backwards
+ * compatibility. The caller must ensure that the initial URL may receive them.
+ * The fetch spec only strips `Authorization` on cross-origin redirects because
+ * in a browser, CORS preflighting protects custom headers; there is no CORS on
+ * the server, so provider API keys carried in custom headers (e.g. `x-key`)
+ * must be dropped here as well.
  *
  * 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.
+ * natively because reaching an internal network is not possible (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 guard.
  *
  * A hop that is same-origin with `trustedOrigin` (the developer-configured
- * endpoint) skips target validation: that origin is exactly what an
+ * provider endpoint) skips target validation: that origin is exactly what an
  * unvalidated, config-derived request would fetch anyway, and validating it
  * would break legitimate self-hosted / localhost deployments whose response
  * URLs point back at the configured host. Hops on any other origin are always
@@ -278,7 +288,8 @@ declare function fetchWithValidatedEndpoint({ url, init, fetch: customFetch, tru
  *
  * 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
+ * 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
@@ -291,8 +302,8 @@ declare function fetchWithValidatedRedirects({ url, headers, abortSignal, maxRed
     maxRedirects?: number;
     fetch?: FetchFunction;
     /**
-     * A developer-configured origin whose hops skip target validation. Must
-     * never be derived from response data.
+     * A developer-configured origin (e.g. the provider's `baseURL`) whose hops
+     * skip target validation. Must never be derived from response data.
      */
     trustedOrigin?: string;
 }): Promise<Response>;
@@ -467,13 +478,44 @@ declare const createJsonResponseHandler: <T>(responseSchema: FlexibleSchema<T>)
 declare const createBinaryResponseHandler: () => ResponseHandler<Uint8Array>;
 declare const createStatusCodeErrorResponseHandler: () => ResponseHandler<APICallError>;
 
-declare const getFromApi: <T>({ url, headers, successfulResponseHandler, failedResponseHandler, abortSignal, fetch, }: {
+declare const getFromApi: <T>({ url, headers, successfulResponseHandler, failedResponseHandler, abortSignal, fetch, validateUrl, credentialedOrigin, trustedOrigin, }: {
     url: string;
     headers?: Record<string, string | undefined>;
     failedResponseHandler: ResponseHandler<Error>;
     successfulResponseHandler: ResponseHandler<T>;
     abortSignal?: AbortSignal;
     fetch?: FetchFunction;
+    /**
+     * Set `true` when `url` is untrusted (e.g. taken from a provider response
+     * body): it is routed through {@link fetchWithValidatedRedirects}, which
+     * rejects private/loopback/link-local targets and re-validates redirect
+     * hops; blocked URLs throw `DownloadError`. Set `false` only for URLs built
+     * from a developer-configured endpoint.
+     *
+     * Optional for backwards compatibility with existing callers; omitting it
+     * behaves like `false` (no validation).
+     */
+    validateUrl?: boolean;
+    /**
+     * When set, `headers` are sent only if `url` is same-origin with this origin
+     * (the user-agent suffix is always kept). Pass the provider's configured
+     * base URL alongside `validateUrl: true` so credentials never ride a request
+     * to a response-supplied host on a different origin (e.g. a CDN). Redirects
+     * that later cross origin drop all caller headers regardless (see
+     * {@link fetchWithValidatedRedirects}).
+     */
+    credentialedOrigin?: string;
+    /**
+     * A developer-configured origin (e.g. the provider's `baseURL`) that is
+     * exempt from URL validation when `validateUrl` is `true`. A response URL
+     * (or redirect hop) that is same-origin with it is fetched without target
+     * validation — it points at exactly the host a config-derived
+     * `validateUrl: false` request would fetch anyway, so blocking it would
+     * only break legitimate self-hosted / localhost deployments whose response
+     * URLs point back at the configured host. Hops on any other origin are
+     * still validated. Must never be derived from response data.
+     */
+    trustedOrigin?: string;
 }) => Promise<{
     value: T;
     rawValue?: unknown;

package/dist/index.d.ts

@@ -250,24 +250,34 @@ declare function fetchWithValidatedEndpoint({ url, init, fetch: customFetch, tru
     redirect?: 'error' | 'manual';
 }): Promise<Response>;
 /**
- * Fetches a URL while enforcing the SSRF download guard on every hop.
+ * Fetches a URL while enforcing the 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.
+ * guard.
+ *
+ * Request headers are also protected: {@link sanitizeRequestHeaders} strips
+ * proxy/metadata/cookie/hop-by-hop headers before the first request, and all
+ * caller headers except `User-Agent` are dropped on a cross-origin redirect.
+ * Credentials and custom headers are preserved on the first hop for backwards
+ * compatibility. The caller must ensure that the initial URL may receive them.
+ * The fetch spec only strips `Authorization` on cross-origin redirects because
+ * in a browser, CORS preflighting protects custom headers; there is no CORS on
+ * the server, so provider API keys carried in custom headers (e.g. `x-key`)
+ * must be dropped here as well.
  *
  * 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.
+ * natively because reaching an internal network is not possible (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 guard.
  *
  * A hop that is same-origin with `trustedOrigin` (the developer-configured
- * endpoint) skips target validation: that origin is exactly what an
+ * provider endpoint) skips target validation: that origin is exactly what an
  * unvalidated, config-derived request would fetch anyway, and validating it
  * would break legitimate self-hosted / localhost deployments whose response
  * URLs point back at the configured host. Hops on any other origin are always
@@ -278,7 +288,8 @@ declare function fetchWithValidatedEndpoint({ url, init, fetch: customFetch, tru
  *
  * 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
+ * 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
@@ -291,8 +302,8 @@ declare function fetchWithValidatedRedirects({ url, headers, abortSignal, maxRed
     maxRedirects?: number;
     fetch?: FetchFunction;
     /**
-     * A developer-configured origin whose hops skip target validation. Must
-     * never be derived from response data.
+     * A developer-configured origin (e.g. the provider's `baseURL`) whose hops
+     * skip target validation. Must never be derived from response data.
      */
     trustedOrigin?: string;
 }): Promise<Response>;
@@ -467,13 +478,44 @@ declare const createJsonResponseHandler: <T>(responseSchema: FlexibleSchema<T>)
 declare const createBinaryResponseHandler: () => ResponseHandler<Uint8Array>;
 declare const createStatusCodeErrorResponseHandler: () => ResponseHandler<APICallError>;
 
-declare const getFromApi: <T>({ url, headers, successfulResponseHandler, failedResponseHandler, abortSignal, fetch, }: {
+declare const getFromApi: <T>({ url, headers, successfulResponseHandler, failedResponseHandler, abortSignal, fetch, validateUrl, credentialedOrigin, trustedOrigin, }: {
     url: string;
     headers?: Record<string, string | undefined>;
     failedResponseHandler: ResponseHandler<Error>;
     successfulResponseHandler: ResponseHandler<T>;
     abortSignal?: AbortSignal;
     fetch?: FetchFunction;
+    /**
+     * Set `true` when `url` is untrusted (e.g. taken from a provider response
+     * body): it is routed through {@link fetchWithValidatedRedirects}, which
+     * rejects private/loopback/link-local targets and re-validates redirect
+     * hops; blocked URLs throw `DownloadError`. Set `false` only for URLs built
+     * from a developer-configured endpoint.
+     *
+     * Optional for backwards compatibility with existing callers; omitting it
+     * behaves like `false` (no validation).
+     */
+    validateUrl?: boolean;
+    /**
+     * When set, `headers` are sent only if `url` is same-origin with this origin
+     * (the user-agent suffix is always kept). Pass the provider's configured
+     * base URL alongside `validateUrl: true` so credentials never ride a request
+     * to a response-supplied host on a different origin (e.g. a CDN). Redirects
+     * that later cross origin drop all caller headers regardless (see
+     * {@link fetchWithValidatedRedirects}).
+     */
+    credentialedOrigin?: string;
+    /**
+     * A developer-configured origin (e.g. the provider's `baseURL`) that is
+     * exempt from URL validation when `validateUrl` is `true`. A response URL
+     * (or redirect hop) that is same-origin with it is fetched without target
+     * validation — it points at exactly the host a config-derived
+     * `validateUrl: false` request would fetch anyway, so blocking it would
+     * only break legitimate self-hosted / localhost deployments whose response
+     * URLs point back at the configured host. Hops on any other origin are
+     * still validated. Must never be derived from response data.
+     */
+    trustedOrigin?: string;
 }) => Promise<{
     value: T;
     rawValue?: unknown;

package/dist/index.js

@@ -605,8 +605,45 @@ function getCurrentModulePath() {
   }
 }
 
+// src/sanitize-request-headers.ts
+var BLOCKED_REQUEST_HEADERS = [
+  // Hop-by-hop / transport (RFC 7230 §6.1)
+  "connection",
+  "keep-alive",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+  // Host / virtual-host routing
+  "host",
+  // Proxy / origin spoofing
+  "forwarded",
+  "proxy-authorization",
+  "via",
+  "x-forwarded-for",
+  "x-forwarded-host",
+  "x-forwarded-proto",
+  "x-real-ip",
+  // Cloud metadata (GCP, AWS IMDSv1/v2, Azure, Alibaba, DigitalOcean)
+  "metadata",
+  "metadata-flavor",
+  "x-aws-ec2-metadata-token",
+  "x-metadata-token",
+  // Session / cookie
+  "cookie",
+  "set-cookie"
+];
+function sanitizeRequestHeaders(input) {
+  const headers = new Headers(input);
+  for (const name2 of BLOCKED_REQUEST_HEADERS) {
+    headers.delete(name2);
+  }
+  return headers;
+}
+
 // src/fetch-with-validated-redirects.ts
 var MAX_DOWNLOAD_REDIRECTS = 10;
+var REDIRECT_STATUS_CODES = /* @__PURE__ */ new Set([301, 302, 303, 307, 308]);
 async function getValidatedFetch(customFetch) {
   return customFetch == null || customFetch === globalThis.fetch ? await getDefaultDownloadFetch() : customFetch;
 }
@@ -637,10 +674,14 @@ async function fetchWithValidatedRedirects({
   trustedOrigin
 }) {
   var _a2;
-  const baseInit = { signal: abortSignal };
-  if (headers !== void 0) {
-    baseInit.headers = headers;
-  }
+  let currentHeaders = headers === void 0 ? void 0 : sanitizeRequestHeaders(headers);
+  const perHopInit = (redirect) => {
+    const init = { signal: abortSignal, redirect };
+    if (currentHeaders !== void 0) {
+      init.headers = new Headers(currentHeaders);
+    }
+    return init;
+  };
   let currentUrl = url;
   for (let redirectCount = 0; redirectCount <= maxRedirects; redirectCount++) {
     const isTrustedHop = trustedOrigin !== void 0 && isSameOrigin(currentUrl, trustedOrigin);
@@ -648,10 +689,7 @@ async function fetchWithValidatedRedirects({
       validateDownloadUrl(currentUrl);
     }
     const fetch = isTrustedHop && customFetch != null ? customFetch : isTrustedHop ? globalThis.fetch : await getValidatedFetch(customFetch);
-    const response = await fetch(currentUrl, {
-      ...baseInit,
-      redirect: "manual"
-    });
+    const response = await fetch(currentUrl, perHopInit("manual"));
     if (response.type === "opaqueredirect") {
       if (!isBrowserRuntime()) {
         throw new DownloadError({
@@ -659,12 +697,19 @@ async function fetchWithValidatedRedirects({
           message: `Redirect from ${currentUrl} could not be validated and was blocked`
         });
       }
-      return await fetch(currentUrl, { ...baseInit, redirect: "follow" });
+      return await fetch(currentUrl, perHopInit("follow"));
     }
     const location = (_a2 = response.headers) == null ? void 0 : _a2.get("location");
-    if (response.status >= 300 && response.status < 400 && location) {
-      await cancelResponseBody(response);
-      currentUrl = new URL(location, currentUrl).toString();
+    if (REDIRECT_STATUS_CODES.has(response.status) && location) {
+      void cancelResponseBody(response);
+      const nextUrl = new URL(location, currentUrl).toString();
+      if (currentHeaders !== void 0 && !isSameOrigin(nextUrl, currentUrl)) {
+        const userAgent = currentHeaders.get("user-agent");
+        currentHeaders = new Headers(
+          userAgent == null ? void 0 : { "user-agent": userAgent }
+        );
+      }
+      currentUrl = nextUrl;
       continue;
     }
     return response;
@@ -954,7 +999,7 @@ function withUserAgentSuffix(headers, ...userAgentSuffixParts) {
 }
 
 // src/version.ts
-var VERSION = true ? "4.0.60" : "0.0.0-test";
+var VERSION = true ? "4.0.61" : "0.0.0-test";
 
 // src/get-from-api.ts
 var getOriginalFetch = () => globalThis.fetch;
@@ -964,16 +1009,28 @@ var getFromApi = async ({
   successfulResponseHandler,
   failedResponseHandler,
   abortSignal,
-  fetch = getOriginalFetch()
+  fetch,
+  validateUrl,
+  credentialedOrigin,
+  trustedOrigin
 }) => {
   try {
-    const response = await fetch(url, {
+    const requestFetch = fetch != null ? fetch : getOriginalFetch();
+    const outgoingHeaders = credentialedOrigin !== void 0 && !isSameOrigin(url, credentialedOrigin) ? {} : headers;
+    const requestHeaders = withUserAgentSuffix(
+      outgoingHeaders,
+      `ai-sdk/provider-utils/${VERSION}`,
+      getRuntimeEnvironmentUserAgent()
+    );
+    const response = validateUrl ? await fetchWithValidatedRedirects({
+      url,
+      headers: requestHeaders,
+      abortSignal,
+      fetch,
+      trustedOrigin
+    }) : await requestFetch(url, {
       method: "GET",
-      headers: withUserAgentSuffix(
-        headers,
-        `ai-sdk/provider-utils/${VERSION}`,
-        getRuntimeEnvironmentUserAgent()
-      ),
+      headers: requestHeaders,
       signal: abortSignal
     });
     const responseHeaders = extractResponseHeaders(response);