ai 7.0.23 → 7.0.25

package/dist/internal/index.js

@@ -85,7 +85,7 @@ import {
 } from "@ai-sdk/provider-utils";
 
 // src/version.ts
-var VERSION = true ? "7.0.23" : "0.0.0-test";
+var VERSION = true ? "7.0.25" : "0.0.0-test";
 
 // src/util/download/download.ts
 var download = async ({

package/docs/03-ai-sdk-core/36-transcription.mdx

@@ -83,10 +83,13 @@ const durationInSeconds = await result.durationInSeconds; // duration in seconds
 The `audio` stream must contain raw audio chunks. `Uint8Array` chunks are raw bytes; `string` chunks are base64-encoded raw bytes. Always set `inputAudioFormat` to match the chunks you send.
 
 <Note>
-  Streaming transcription requires a provider model instance (e.g.
-  `openai.transcription('gpt-realtime-whisper')`). String model IDs resolve
-  through the global provider (AI Gateway by default), which does not support
-  streaming transcription yet.
+  String model IDs resolve through the global provider (AI Gateway by
+  default). AI Gateway supports streaming transcription for supported models
+  (e.g. `openai/gpt-realtime-whisper`, `xai/grok-stt`), so string IDs work:
+  `experimental_streamTranscribe({ model: 'openai/gpt-realtime-whisper', ...
+  })`. You can also pass a provider model instance (e.g.
+  `openai.transcription('gpt-realtime-whisper')`) to stream directly against
+  the provider.
 </Note>
 
 OpenAI streaming transcription uses `openai.transcription('gpt-realtime-whisper')`. xAI uses the same `xai.transcription()` model for request/response and streaming transcription; `experimental_streamTranscribe` uses xAI's WebSocket STT transport under the hood.

package/docs/06-advanced/11-secure-url-fetching.mdx

@@ -0,0 +1,117 @@
+---
+title: Secure URL Fetching
+description: How the AI SDK protects server-side fetches of URLs returned by model providers, and how to harden your deployment further.
+---
+
+# Secure URL Fetching
+
+Many providers return a **URL in their response body** — a generated image,
+audio, or video to download, or a polling URL to check job status. The AI SDK
+fetches these server-side and returns the result to your code. Because that URL
+comes from an external service, a malicious or compromised provider (or anyone
+able to tamper with the response) could point it at an internal address such as
+a cloud-metadata endpoint (`http://169.254.169.254/…`), a private host
+(`http://10.0.0.5/…`), or `localhost`.
+
+To prevent that, the SDK validates every response-supplied URL before fetching
+it. This happens automatically inside the provider packages — you don't need to
+configure anything.
+
+## What the SDK protects against
+
+When the SDK fetches a URL taken from a provider response, it:
+
+- **Rejects private, loopback, and link-local targets** — IPv4 (`10/8`,
+  `172.16/12`, `192.168/16`, `127/8`, `169.254/16`, CGNAT, multicast, …) and the
+  equivalent IPv6 ranges, plus `localhost` and `.local`. Non-`http(s)` schemes
+  are rejected too.
+- **Re-validates every redirect hop** — a URL that passes but then redirects to
+  an internal address is blocked; the redirect is never followed blindly.
+- **Strips risky request headers** — proxy-forwarding, cloud-metadata, and
+  cookie headers are removed before the request.
+- **Drops credentials across origins** — caller headers (`Authorization`,
+  `Cookie`, and provider-specific API-key headers alike) are not sent to a host
+  on a different origin than the provider's; a redirect that crosses origin
+  drops all of them except the user-agent.
+
+A blocked URL surfaces as a `DownloadError`.
+
+## Self-hosted and local endpoints
+
+URLs that are same-origin with the provider endpoint **you configured** (e.g. a
+custom `baseURL` pointing at a self-hosted or `localhost` deployment) are
+exempt from these checks — they target exactly the host you told the SDK to
+talk to. Any redirect off that origin is still validated.
+
+## Limitation: DNS resolution and DNS rebinding
+
+The built-in guard inspects the URL **as a string**. It deliberately does
+**not resolve DNS**, so two attacks remain out of scope at this layer:
+
+1. **Hostname that resolves to a private IP** — a literal host that looks public
+   but whose DNS record points at an internal address.
+2. **DNS rebinding** — a host that resolves to a public IP when validated and a
+   private IP a moment later when the socket actually connects (a
+   time-of-check/time-of-use window).
+
+### Why this isn't built in
+
+Closing these requires resolving DNS and pinning the resolved IP **at connect
+time** — Node-only capabilities (`node:dns`, a custom `undici` dispatcher). The
+SDK's provider utilities are **cross-runtime**: they run on the edge, in the
+browser, and on Bun/Deno, with no Node-only dependencies, so those APIs aren't
+available there. The threat is also specifically a **server-side** one — on the
+edge and in the browser, outbound `fetch` cannot reach a host's internal network
+or metadata endpoint in the first place. So connect-time IP pinning is only
+meaningful, and only available, on a Node server — which is exactly where you
+can add it yourself.
+
+## Hardening your deployment
+
+If your server fetches provider-supplied URLs and you want to close the DNS
+gaps, use one (ideally both) of these:
+
+### 1. Restrict outbound egress at the network layer
+
+Deny your server's network egress to `169.254.0.0/16`, RFC-1918 ranges, and
+loopback. This is the most robust control and is independent of application
+code.
+
+### 2. Inject a hardened `fetch`
+
+Every provider accepts a custom `fetch`. On Node, back it with an `undici`
+`Agent` whose `connect.lookup` validates the resolved IP and lets the socket
+connect only to a safe address — closing both the hostname-to-private and the
+DNS-rebinding windows:
+
+```ts
+import { Agent, fetch as undiciFetch } from 'undici';
+import { lookup } from 'node:dns';
+
+// Your own check that returns true for private/loopback/link-local addresses.
+declare function isUnsafeAddress(ip: string): boolean;
+
+const safeLookup: typeof lookup = (hostname, options, callback) => {
+  lookup(hostname, options as any, (err, address, family) => {
+    if (!err && typeof address === 'string' && isUnsafeAddress(address)) {
+      callback(new Error(`Refusing to connect to ${address}`), '', 0);
+      return;
+    }
+    (callback as any)(err, address, family);
+  });
+};
+
+const safeDispatcher = new Agent({ connect: { lookup: safeLookup } });
+
+const safeFetch: typeof fetch = (input, init) =>
+  undiciFetch(input, { ...init, dispatcher: safeDispatcher }) as any;
+```
+
+```ts
+import { createFal } from '@ai-sdk/fal';
+
+const fal = createFal({ fetch: safeFetch });
+```
+
+The SDK's built-in validation and your connect-time pinning are complementary —
+keep both.

package/docs/07-reference/01-ai-sdk-core/11-stream-transcribe.mdx

@@ -48,7 +48,7 @@ console.log(await result.text);
       name: 'model',
       type: 'TranscriptionModelV4',
       description:
-        'The transcription model to use. The model must support streaming (`doStream`). String model IDs resolve through the global provider (AI Gateway by default), which does not support streaming transcription yet.',
+        "The transcription model to use. The model must support streaming (`doStream`). String model IDs resolve through the global provider (AI Gateway by default), which supports streaming transcription for supported models (e.g. `openai/gpt-realtime-whisper`, `xai/grok-stt`): `experimental_streamTranscribe({ model: 'openai/gpt-realtime-whisper', ... })`.",
     },
     {
       name: 'audio',
@@ -147,3 +147,15 @@ console.log(await result.text);
   `fullStream` early (e.g. `break` out of the loop), the underlying provider
   connection is closed and pending result promises reject.
 </Note>
+
+## Wire format (experimental)
+
+Streaming transcription over WebSocket is serialized with the experimental
+transcription-stream envelope defined in `@ai-sdk/provider-utils`
+(`experimental_parseTranscriptionStreamClientFrame`,
+`experimental_serializeTranscriptionStreamPart`,
+`experimental_parseTranscriptionStreamPart`): the client sends one
+`transcription-stream.start` TEXT frame, audio as BINARY frames, and a
+`transcription-stream.audio-done` TEXT frame; each server TEXT frame is one
+JSON-serialized transcription stream part. AI Gateway implements the server
+side of this envelope.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "7.0.23",
+  "version": "7.0.25",
   "type": "module",
   "description": "AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.",
   "license": "Apache-2.0",
@@ -42,9 +42,9 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/gateway": "4.0.17",
+    "@ai-sdk/gateway": "4.0.19",
     "@ai-sdk/provider": "4.0.3",
-    "@ai-sdk/provider-utils": "5.0.7"
+    "@ai-sdk/provider-utils": "5.0.9"
   },
   "devDependencies": {
     "@edge-runtime/vm": "^5.0.0",

package/src/transcribe/stream-transcribe.ts

@@ -15,6 +15,7 @@ import type { TranscriptionModel } from '../types/transcription-model';
 import type { TranscriptionModelResponseMetadata } from '../types/transcription-model-response-metadata';
 import type { Warning } from '../types/warning';
 import { asAsyncIterableStream } from '../util/async-iterable-stream';
+import { mergeAbortSignals } from '../util/merge-abort-signals';
 import { VERSION } from '../version';
 import type {
   StreamTranscriptionResult,
@@ -113,9 +114,10 @@ export function streamTranscribe({
       message:
         `The ${resolvedModel.provider} model "${resolvedModel.modelId}" does not support streaming transcription.` +
         (typeof model === 'string'
-          ? ' String model IDs resolve through the global provider (AI Gateway by default),' +
-            ' which does not support streaming transcription yet.' +
-            " Pass a provider model instance instead, e.g. openai.transcription('gpt-realtime-whisper')."
+          ? ' String model IDs resolve through the global provider (AI Gateway by default).' +
+            ' If that provider does not support streaming transcription, pass a provider model' +
+            " instance instead (e.g. openai.transcription('gpt-realtime-whisper'))" +
+            ' or upgrade @ai-sdk/gateway to a version with streaming transcription support.'
           : ''),
     });
   }
@@ -253,7 +255,8 @@ export function streamTranscribe({
       audio,
       inputAudioFormat,
       providerOptions,
-      abortSignal,
+      // merged so cancelling fullStream also aborts a still-pending doStream
+      abortSignal: mergeAbortSignals(abortSignal, pipeAbortController.signal),
       headers: headersWithUserAgent,
       includeRawChunks,
     });
@@ -271,6 +274,12 @@ export function streamTranscribe({
     const reason =
       error ?? new Error('Transcription stream was cancelled or errored.');
     rejectPendingPromises(reason);
+    // When `doStream` rejects before the model stream exists (e.g. auth or
+    // header resolution failure), nothing has taken ownership of `audio` yet,
+    // so cancel it directly — otherwise an upstream producer piping into it
+    // hangs forever. When the model did take a reader, `audio` is locked and
+    // the cancel rejects, which is fine: the model's cleanup owns it then.
+    audio.cancel(reason).catch(() => {});
     transform.writable.abort(reason).catch(() => {
       // the writable is already errored when the model stream failed mid-pipe
     });