fix: expand SSRF guard coverage

src/media-understanding/providers/deepgram/audio.test.ts

@@ -1,6 +1,13 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import * as ssrf from "../../../infra/net/ssrf.js";
 import { transcribeDeepgramAudio } from "./audio.js";
 
+const resolvePinnedHostname = ssrf.resolvePinnedHostname;
+const resolvePinnedHostnameWithPolicy = ssrf.resolvePinnedHostnameWithPolicy;
+const lookupMock = vi.fn();
+let resolvePinnedHostnameSpy: ReturnType<typeof vi.spyOn> | null = null;
+let resolvePinnedHostnameWithPolicySpy: ReturnType<typeof vi.spyOn> | null = null;
+
 const resolveRequestUrl = (input: RequestInfo | URL) => {
   if (typeof input === "string") {
     return input;
@@ -12,6 +19,26 @@ const resolveRequestUrl = (input: RequestInfo | URL) => {
 };
 
 describe("transcribeDeepgramAudio", () => {
+  beforeEach(() => {
+    lookupMock.mockResolvedValue([{ address: "93.184.216.34", family: 4 }]);
+    resolvePinnedHostnameSpy = vi
+      .spyOn(ssrf, "resolvePinnedHostname")
+      .mockImplementation((hostname) => resolvePinnedHostname(hostname, lookupMock));
+    resolvePinnedHostnameWithPolicySpy = vi
+      .spyOn(ssrf, "resolvePinnedHostnameWithPolicy")
+      .mockImplementation((hostname, params) =>
+        resolvePinnedHostnameWithPolicy(hostname, { ...params, lookupFn: lookupMock }),
+      );
+  });
+
+  afterEach(() => {
+    lookupMock.mockReset();
+    resolvePinnedHostnameSpy?.mockRestore();
+    resolvePinnedHostnameWithPolicySpy?.mockRestore();
+    resolvePinnedHostnameSpy = null;
+    resolvePinnedHostnameWithPolicySpy = null;
+  });
+
   it("respects lowercase authorization header overrides", async () => {
     let seenAuth: string | null = null;
     const fetchFn = async (_input: RequestInfo | URL, init?: RequestInit) => {

src/media-understanding/providers/deepgram/audio.ts

@@ -1,5 +1,5 @@
 import type { AudioTranscriptionRequest, AudioTranscriptionResult } from "../../types.js";
-import { fetchWithTimeout, normalizeBaseUrl, readErrorResponse } from "../shared.js";
+import { fetchWithTimeoutGuarded, normalizeBaseUrl, readErrorResponse } from "../shared.js";
 
 export const DEFAULT_DEEPGRAM_AUDIO_BASE_URL = "https://api.deepgram.com/v1";
 export const DEFAULT_DEEPGRAM_AUDIO_MODEL = "nova-3";
@@ -24,6 +24,7 @@ export async function transcribeDeepgramAudio(
 ): Promise<AudioTranscriptionResult> {
   const fetchFn = params.fetchFn ?? fetch;
   const baseUrl = normalizeBaseUrl(params.baseUrl, DEFAULT_DEEPGRAM_AUDIO_BASE_URL);
+  const allowPrivate = Boolean(params.baseUrl?.trim());
   const model = resolveModel(params.model);
 
   const url = new URL(`${baseUrl}/listen`);
@@ -49,7 +50,7 @@ export async function transcribeDeepgramAudio(
   }
 
   const body = new Uint8Array(params.buffer);
-  const res = await fetchWithTimeout(
+  const { response: res, release } = await fetchWithTimeoutGuarded(
     url.toString(),
     {
       method: "POST",
@@ -58,18 +59,23 @@ export async function transcribeDeepgramAudio(
     },
     params.timeoutMs,
     fetchFn,
+    allowPrivate ? { ssrfPolicy: { allowPrivateNetwork: true } } : undefined,
   );
 
-  if (!res.ok) {
-    const detail = await readErrorResponse(res);
-    const suffix = detail ? `: ${detail}` : "";
-    throw new Error(`Audio transcription failed (HTTP ${res.status})${suffix}`);
-  }
+  try {
+    if (!res.ok) {
+      const detail = await readErrorResponse(res);
+      const suffix = detail ? `: ${detail}` : "";
+      throw new Error(`Audio transcription failed (HTTP ${res.status})${suffix}`);
+    }
 
-  const payload = (await res.json()) as DeepgramTranscriptResponse;
-  const transcript = payload.results?.channels?.[0]?.alternatives?.[0]?.transcript?.trim();
-  if (!transcript) {
-    throw new Error("Audio transcription response missing transcript");
+    const payload = (await res.json()) as DeepgramTranscriptResponse;
+    const transcript = payload.results?.channels?.[0]?.alternatives?.[0]?.transcript?.trim();
+    if (!transcript) {
+      throw new Error("Audio transcription response missing transcript");
+    }
+    return { text: transcript, model };
+  } finally {
+    await release();
   }
-  return { text: transcript, model };
 }

src/media-understanding/providers/google/audio.ts

@@ -1,6 +1,6 @@
 import type { AudioTranscriptionRequest, AudioTranscriptionResult } from "../../types.js";
 import { normalizeGoogleModelId } from "../../../agents/models-config.providers.js";
-import { fetchWithTimeout, normalizeBaseUrl, readErrorResponse } from "../shared.js";
+import { fetchWithTimeoutGuarded, normalizeBaseUrl, readErrorResponse } from "../shared.js";
 
 export const DEFAULT_GOOGLE_AUDIO_BASE_URL = "https://generativelanguage.googleapis.com/v1beta";
 const DEFAULT_GOOGLE_AUDIO_MODEL = "gemini-3-flash-preview";
@@ -24,6 +24,7 @@ export async function transcribeGeminiAudio(
 ): Promise<AudioTranscriptionResult> {
   const fetchFn = params.fetchFn ?? fetch;
   const baseUrl = normalizeBaseUrl(params.baseUrl, DEFAULT_GOOGLE_AUDIO_BASE_URL);
+  const allowPrivate = Boolean(params.baseUrl?.trim());
   const model = resolveModel(params.model);
   const url = `${baseUrl}/models/${model}:generateContent`;
 
@@ -52,7 +53,7 @@ export async function transcribeGeminiAudio(
     ],
   };
 
-  const res = await fetchWithTimeout(
+  const { response: res, release } = await fetchWithTimeoutGuarded(
     url,
     {
       method: "POST",
@@ -61,26 +62,31 @@ export async function transcribeGeminiAudio(
     },
     params.timeoutMs,
     fetchFn,
+    allowPrivate ? { ssrfPolicy: { allowPrivateNetwork: true } } : undefined,
   );
 
-  if (!res.ok) {
-    const detail = await readErrorResponse(res);
-    const suffix = detail ? `: ${detail}` : "";
-    throw new Error(`Audio transcription failed (HTTP ${res.status})${suffix}`);
-  }
+  try {
+    if (!res.ok) {
+      const detail = await readErrorResponse(res);
+      const suffix = detail ? `: ${detail}` : "";
+      throw new Error(`Audio transcription failed (HTTP ${res.status})${suffix}`);
+    }
 
-  const payload = (await res.json()) as {
-    candidates?: Array<{
-      content?: { parts?: Array<{ text?: string }> };
-    }>;
-  };
-  const parts = payload.candidates?.[0]?.content?.parts ?? [];
-  const text = parts
-    .map((part) => part?.text?.trim())
-    .filter(Boolean)
-    .join("\n");
-  if (!text) {
-    throw new Error("Audio transcription response missing text");
+    const payload = (await res.json()) as {
+      candidates?: Array<{
+        content?: { parts?: Array<{ text?: string }> };
+      }>;
+    };
+    const parts = payload.candidates?.[0]?.content?.parts ?? [];
+    const text = parts
+      .map((part) => part?.text?.trim())
+      .filter(Boolean)
+      .join("\n");
+    if (!text) {
+      throw new Error("Audio transcription response missing text");
+    }
+    return { text, model };
+  } finally {
+    await release();
   }
-  return { text, model };
 }

src/media-understanding/providers/google/video.ts

@@ -1,6 +1,6 @@
 import type { VideoDescriptionRequest, VideoDescriptionResult } from "../../types.js";
 import { normalizeGoogleModelId } from "../../../agents/models-config.providers.js";
-import { fetchWithTimeout, normalizeBaseUrl, readErrorResponse } from "../shared.js";
+import { fetchWithTimeoutGuarded, normalizeBaseUrl, readErrorResponse } from "../shared.js";
 
 export const DEFAULT_GOOGLE_VIDEO_BASE_URL = "https://generativelanguage.googleapis.com/v1beta";
 const DEFAULT_GOOGLE_VIDEO_MODEL = "gemini-3-flash-preview";
@@ -24,6 +24,7 @@ export async function describeGeminiVideo(
 ): Promise<VideoDescriptionResult> {
   const fetchFn = params.fetchFn ?? fetch;
   const baseUrl = normalizeBaseUrl(params.baseUrl, DEFAULT_GOOGLE_VIDEO_BASE_URL);
+  const allowPrivate = Boolean(params.baseUrl?.trim());
   const model = resolveModel(params.model);
   const url = `${baseUrl}/models/${model}:generateContent`;
 
@@ -52,7 +53,7 @@ export async function describeGeminiVideo(
     ],
   };
 
-  const res = await fetchWithTimeout(
+  const { response: res, release } = await fetchWithTimeoutGuarded(
     url,
     {
       method: "POST",
@@ -61,26 +62,31 @@ export async function describeGeminiVideo(
     },
     params.timeoutMs,
     fetchFn,
+    allowPrivate ? { ssrfPolicy: { allowPrivateNetwork: true } } : undefined,
   );
 
-  if (!res.ok) {
-    const detail = await readErrorResponse(res);
-    const suffix = detail ? `: ${detail}` : "";
-    throw new Error(`Video description failed (HTTP ${res.status})${suffix}`);
-  }
+  try {
+    if (!res.ok) {
+      const detail = await readErrorResponse(res);
+      const suffix = detail ? `: ${detail}` : "";
+      throw new Error(`Video description failed (HTTP ${res.status})${suffix}`);
+    }
 
-  const payload = (await res.json()) as {
-    candidates?: Array<{
-      content?: { parts?: Array<{ text?: string }> };
-    }>;
-  };
-  const parts = payload.candidates?.[0]?.content?.parts ?? [];
-  const text = parts
-    .map((part) => part?.text?.trim())
-    .filter(Boolean)
-    .join("\n");
-  if (!text) {
-    throw new Error("Video description response missing text");
+    const payload = (await res.json()) as {
+      candidates?: Array<{
+        content?: { parts?: Array<{ text?: string }> };
+      }>;
+    };
+    const parts = payload.candidates?.[0]?.content?.parts ?? [];
+    const text = parts
+      .map((part) => part?.text?.trim())
+      .filter(Boolean)
+      .join("\n");
+    if (!text) {
+      throw new Error("Video description response missing text");
+    }
+    return { text, model };
+  } finally {
+    await release();
   }
-  return { text, model };
 }

src/media-understanding/providers/openai/audio.test.ts

@@ -1,6 +1,13 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import * as ssrf from "../../../infra/net/ssrf.js";
 import { transcribeOpenAiCompatibleAudio } from "./audio.js";
 
+const resolvePinnedHostname = ssrf.resolvePinnedHostname;
+const resolvePinnedHostnameWithPolicy = ssrf.resolvePinnedHostnameWithPolicy;
+const lookupMock = vi.fn();
+let resolvePinnedHostnameSpy: ReturnType<typeof vi.spyOn> | null = null;
+let resolvePinnedHostnameWithPolicySpy: ReturnType<typeof vi.spyOn> | null = null;
+
 const resolveRequestUrl = (input: RequestInfo | URL) => {
   if (typeof input === "string") {
     return input;
@@ -12,6 +19,26 @@ const resolveRequestUrl = (input: RequestInfo | URL) => {
 };
 
 describe("transcribeOpenAiCompatibleAudio", () => {
+  beforeEach(() => {
+    lookupMock.mockResolvedValue([{ address: "93.184.216.34", family: 4 }]);
+    resolvePinnedHostnameSpy = vi
+      .spyOn(ssrf, "resolvePinnedHostname")
+      .mockImplementation((hostname) => resolvePinnedHostname(hostname, lookupMock));
+    resolvePinnedHostnameWithPolicySpy = vi
+      .spyOn(ssrf, "resolvePinnedHostnameWithPolicy")
+      .mockImplementation((hostname, params) =>
+        resolvePinnedHostnameWithPolicy(hostname, { ...params, lookupFn: lookupMock }),
+      );
+  });
+
+  afterEach(() => {
+    lookupMock.mockReset();
+    resolvePinnedHostnameSpy?.mockRestore();
+    resolvePinnedHostnameWithPolicySpy?.mockRestore();
+    resolvePinnedHostnameSpy = null;
+    resolvePinnedHostnameWithPolicySpy = null;
+  });
+
   it("respects lowercase authorization header overrides", async () => {
     let seenAuth: string | null = null;
     const fetchFn = async (_input: RequestInfo | URL, init?: RequestInit) => {

src/media-understanding/providers/openai/audio.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 import type { AudioTranscriptionRequest, AudioTranscriptionResult } from "../../types.js";
-import { fetchWithTimeout, normalizeBaseUrl, readErrorResponse } from "../shared.js";
+import { fetchWithTimeoutGuarded, normalizeBaseUrl, readErrorResponse } from "../shared.js";
 
 export const DEFAULT_OPENAI_AUDIO_BASE_URL = "https://api.openai.com/v1";
 const DEFAULT_OPENAI_AUDIO_MODEL = "gpt-4o-mini-transcribe";
@@ -15,6 +15,7 @@ export async function transcribeOpenAiCompatibleAudio(
 ): Promise<AudioTranscriptionResult> {
   const fetchFn = params.fetchFn ?? fetch;
   const baseUrl = normalizeBaseUrl(params.baseUrl, DEFAULT_OPENAI_AUDIO_BASE_URL);
+  const allowPrivate = Boolean(params.baseUrl?.trim());
   const url = `${baseUrl}/audio/transcriptions`;
 
   const model = resolveModel(params.model);
@@ -38,7 +39,7 @@ export async function transcribeOpenAiCompatibleAudio(
     headers.set("authorization", `Bearer ${params.apiKey}`);
   }
 
-  const res = await fetchWithTimeout(
+  const { response: res, release } = await fetchWithTimeoutGuarded(
     url,
     {
       method: "POST",
@@ -47,18 +48,23 @@ export async function transcribeOpenAiCompatibleAudio(
     },
     params.timeoutMs,
     fetchFn,
+    allowPrivate ? { ssrfPolicy: { allowPrivateNetwork: true } } : undefined,
   );
 
-  if (!res.ok) {
-    const detail = await readErrorResponse(res);
-    const suffix = detail ? `: ${detail}` : "";
-    throw new Error(`Audio transcription failed (HTTP ${res.status})${suffix}`);
-  }
+  try {
+    if (!res.ok) {
+      const detail = await readErrorResponse(res);
+      const suffix = detail ? `: ${detail}` : "";
+      throw new Error(`Audio transcription failed (HTTP ${res.status})${suffix}`);
+    }
 
-  const payload = (await res.json()) as { text?: string };
-  const text = payload.text?.trim();
-  if (!text) {
-    throw new Error("Audio transcription response missing text");
+    const payload = (await res.json()) as { text?: string };
+    const text = payload.text?.trim();
+    if (!text) {
+      throw new Error("Audio transcription response missing text");
+    }
+    return { text, model };
+  } finally {
+    await release();
   }
-  return { text, model };
 }

src/media-understanding/providers/shared.ts

@@ -1,3 +1,7 @@
+import type { GuardedFetchResult } from "../../infra/net/fetch-guard.js";
+import type { LookupFn, SsrFPolicy } from "../../infra/net/ssrf.js";
+import { fetchWithSsrFGuard } from "../../infra/net/fetch-guard.js";
+
 const MAX_ERROR_CHARS = 300;
 
 export function normalizeBaseUrl(baseUrl: string | undefined, fallback: string): string {
@@ -20,6 +24,28 @@ export async function fetchWithTimeout(
   }
 }
 
+export async function fetchWithTimeoutGuarded(
+  url: string,
+  init: RequestInit,
+  timeoutMs: number,
+  fetchFn: typeof fetch,
+  options?: {
+    ssrfPolicy?: SsrFPolicy;
+    lookupFn?: LookupFn;
+    pinDns?: boolean;
+  },
+): Promise<GuardedFetchResult> {
+  return await fetchWithSsrFGuard({
+    url,
+    fetchImpl: fetchFn,
+    init,
+    timeoutMs,
+    policy: options?.ssrfPolicy,
+    lookupFn: options?.lookupFn,
+    pinDns: options?.pinDns,
+  });
+}
+
 export async function readErrorResponse(res: Response): Promise<string | undefined> {
   try {
     const text = await res.text();