@open-mercato/shared 0.5.1-develop.2912.8d7b1fef24 → 0.5.1-develop.2924.d13908516e

package/dist/lib/url-safety.js

@@ -1,5 +1,6 @@
 import { lookup } from "node:dns/promises";
 import { isIP } from "node:net";
+import { Agent } from "undici";
 import { isBlockedHostname, isPrivateIpAddress } from "./network.js";
 class UnsafeOutboundUrlError extends Error {
   constructor(reason, message) {
@@ -53,10 +54,13 @@ function assertStaticallySafeOutboundUrl(rawUrl, options = {}) {
   }
 }
 async function assertSafeOutboundUrl(rawUrl, options = {}) {
+  await resolveSafeOutboundUrl(rawUrl, options);
+}
+async function resolveSafeOutboundUrl(rawUrl, options = {}) {
   const subject = options.subject ?? "URL";
   const factory = options.errorFactory ?? defaultErrorFactory;
-  const { hostname } = parseOutboundUrl(rawUrl, options);
-  if (options.allowPrivate) return;
+  const { url, hostname } = parseOutboundUrl(rawUrl, options);
+  if (options.allowPrivate) return { url, hostname, addresses: null };
   if (isBlockedHostname(hostname)) {
     throw factory("blocked_hostname", `${subject} host "${hostname}" is not allowed`);
   }
@@ -67,7 +71,7 @@ async function assertSafeOutboundUrl(rawUrl, options = {}) {
         `${subject} host "${hostname}" resolves to a private or reserved IP range`
       );
     }
-    return;
+    return { url, hostname, addresses: null };
   }
   const resolver = options.lookupHost ?? (async (host) => {
     const records = await lookup(host, { all: true, verbatim: true });
@@ -96,11 +100,54 @@ async function assertSafeOutboundUrl(rawUrl, options = {}) {
       );
     }
   }
+  return { url, hostname, addresses };
+}
+async function safeOutboundFetch(rawUrl, init = {}, options = {}) {
+  const { url, hostname, addresses } = await resolveSafeOutboundUrl(rawUrl, options);
+  void url;
+  const mergedInit = {
+    redirect: "manual",
+    ...init
+  };
+  const fetchImpl = options.fetchImpl;
+  if (fetchImpl) {
+    return fetchImpl(rawUrl, mergedInit);
+  }
+  if (!addresses || addresses.length === 0) {
+    return globalThis.fetch(rawUrl, mergedInit);
+  }
+  const dispatcher = new Agent({
+    connect: {
+      lookup: createPinnedDnsLookup(hostname, addresses[0])
+    }
+  });
+  try {
+    return await globalThis.fetch(rawUrl, { ...mergedInit, dispatcher });
+  } finally {
+    dispatcher.close().catch(() => {
+    });
+  }
+}
+function createPinnedDnsLookup(expectedHostname, pinned) {
+  return (host, _opts, cb) => {
+    if (host !== expectedHostname) {
+      const err = new Error(
+        `Refusing DNS lookup for unexpected host "${host}" (expected "${expectedHostname}")`
+      );
+      err.code = "EREFUSED";
+      cb(err, "", 0);
+      return;
+    }
+    cb(null, pinned.address, pinned.family);
+  };
 }
 export {
   UnsafeOutboundUrlError,
   assertSafeOutboundUrl,
   assertStaticallySafeOutboundUrl,
-  parseOutboundUrl
+  createPinnedDnsLookup,
+  parseOutboundUrl,
+  resolveSafeOutboundUrl,
+  safeOutboundFetch
 };
 //# sourceMappingURL=url-safety.js.map

package/dist/lib/url-safety.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/url-safety.ts"],
-  "sourcesContent": ["import { lookup } from 'node:dns/promises'\nimport { isIP } from 'node:net'\nimport { isBlockedHostname, isPrivateIpAddress } from './network'\n\nexport type UrlSafetyReason =\n  | 'invalid_url'\n  | 'forbidden_protocol'\n  | 'credentials_in_url'\n  | 'missing_host'\n  | 'blocked_hostname'\n  | 'private_ip_literal'\n  | 'private_ip_resolved'\n  | 'dns_resolution_failed'\n  | 'dns_resolution_empty'\n\nexport class UnsafeOutboundUrlError extends Error {\n  public readonly reason: UrlSafetyReason\n\n  constructor(reason: UrlSafetyReason, message?: string) {\n    super(message ?? `Outbound URL rejected: ${reason}`)\n    this.name = 'UnsafeOutboundUrlError'\n    this.reason = reason\n  }\n}\n\nconst ALLOWED_PROTOCOLS = new Set(['http:', 'https:'])\n\nexport type ParsedOutboundUrl = {\n  url: URL\n  hostname: string\n}\n\nexport type UrlSafetyErrorFactory = (reason: UrlSafetyReason, message: string) => Error\n\nconst defaultErrorFactory: UrlSafetyErrorFactory = (reason, message) =>\n  new UnsafeOutboundUrlError(reason, message)\n\nexport type ParseOutboundUrlOptions = {\n  errorFactory?: UrlSafetyErrorFactory\n  subject?: string\n}\n\nexport function parseOutboundUrl(\n  rawUrl: string,\n  options: ParseOutboundUrlOptions = {},\n): ParsedOutboundUrl {\n  const subject = options.subject ?? 'URL'\n  const factory = options.errorFactory ?? defaultErrorFactory\n  let url: URL\n  try {\n    url = new URL(rawUrl)\n  } catch {\n    throw factory('invalid_url', `${subject} is not a valid URL`)\n  }\n  if (!ALLOWED_PROTOCOLS.has(url.protocol)) {\n    throw factory(\n      'forbidden_protocol',\n      `${subject} protocol \"${url.protocol.replace(':', '')}\" is not allowed; use http or https`,\n    )\n  }\n  if (url.username || url.password) {\n    throw factory('credentials_in_url', `${subject} must not embed basic-auth credentials`)\n  }\n  let hostname = url.hostname.trim().toLowerCase()\n  if (!hostname) {\n    throw factory('missing_host', `${subject} must include a hostname`)\n  }\n  if (hostname.startsWith('[') && hostname.endsWith(']')) {\n    hostname = hostname.slice(1, -1)\n  }\n  return { url, hostname }\n}\n\nexport type HostLookup = (\n  hostname: string,\n) => Promise<ReadonlyArray<{ address: string; family: number }>>\n\nexport type AssertStaticUrlOptions = ParseOutboundUrlOptions & {\n  allowPrivate?: boolean\n}\n\nexport function assertStaticallySafeOutboundUrl(\n  rawUrl: string,\n  options: AssertStaticUrlOptions = {},\n): void {\n  const subject = options.subject ?? 'URL'\n  const factory = options.errorFactory ?? defaultErrorFactory\n  const { hostname } = parseOutboundUrl(rawUrl, options)\n  if (options.allowPrivate) return\n\n  if (isBlockedHostname(hostname)) {\n    throw factory('blocked_hostname', `${subject} host \"${hostname}\" is not allowed`)\n  }\n  if (isIP(hostname) && isPrivateIpAddress(hostname)) {\n    throw factory(\n      'private_ip_literal',\n      `${subject} host \"${hostname}\" resolves to a private or reserved IP range`,\n    )\n  }\n}\n\nexport type AssertSafeOutboundUrlOptions = AssertStaticUrlOptions & {\n  lookupHost?: HostLookup\n}\n\nexport async function assertSafeOutboundUrl(\n  rawUrl: string,\n  options: AssertSafeOutboundUrlOptions = {},\n): Promise<void> {\n  const subject = options.subject ?? 'URL'\n  const factory = options.errorFactory ?? defaultErrorFactory\n  const { hostname } = parseOutboundUrl(rawUrl, options)\n  if (options.allowPrivate) return\n\n  if (isBlockedHostname(hostname)) {\n    throw factory('blocked_hostname', `${subject} host \"${hostname}\" is not allowed`)\n  }\n\n  if (isIP(hostname)) {\n    if (isPrivateIpAddress(hostname)) {\n      throw factory(\n        'private_ip_literal',\n        `${subject} host \"${hostname}\" resolves to a private or reserved IP range`,\n      )\n    }\n    return\n  }\n\n  const resolver: HostLookup =\n    options.lookupHost ??\n    (async (host) => {\n      const records = await lookup(host, { all: true, verbatim: true })\n      return records\n    })\n\n  let addresses: ReadonlyArray<{ address: string; family: number }>\n  try {\n    addresses = await resolver(hostname)\n  } catch (error) {\n    throw factory(\n      'dns_resolution_failed',\n      `${subject} host \"${hostname}\" could not be resolved: ${\n        error instanceof Error ? error.message : 'lookup failed'\n      }`,\n    )\n  }\n\n  if (!addresses || addresses.length === 0) {\n    throw factory(\n      'dns_resolution_empty',\n      `${subject} host \"${hostname}\" has no DNS A/AAAA records`,\n    )\n  }\n\n  for (const record of addresses) {\n    if (isPrivateIpAddress(record.address)) {\n      throw factory(\n        'private_ip_resolved',\n        `${subject} host \"${hostname}\" resolves to a private or reserved IP address (${record.address})`,\n      )\n    }\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import { lookup } from 'node:dns/promises'\nimport { isIP } from 'node:net'\nimport { Agent, type Dispatcher } from 'undici'\nimport { isBlockedHostname, isPrivateIpAddress } from './network'\n\nexport type UrlSafetyReason =\n  | 'invalid_url'\n  | 'forbidden_protocol'\n  | 'credentials_in_url'\n  | 'missing_host'\n  | 'blocked_hostname'\n  | 'private_ip_literal'\n  | 'private_ip_resolved'\n  | 'dns_resolution_failed'\n  | 'dns_resolution_empty'\n\nexport class UnsafeOutboundUrlError extends Error {\n  public readonly reason: UrlSafetyReason\n\n  constructor(reason: UrlSafetyReason, message?: string) {\n    super(message ?? `Outbound URL rejected: ${reason}`)\n    this.name = 'UnsafeOutboundUrlError'\n    this.reason = reason\n  }\n}\n\nconst ALLOWED_PROTOCOLS = new Set(['http:', 'https:'])\n\nexport type ParsedOutboundUrl = {\n  url: URL\n  hostname: string\n}\n\nexport type UrlSafetyErrorFactory = (reason: UrlSafetyReason, message: string) => Error\n\nconst defaultErrorFactory: UrlSafetyErrorFactory = (reason, message) =>\n  new UnsafeOutboundUrlError(reason, message)\n\nexport type ParseOutboundUrlOptions = {\n  errorFactory?: UrlSafetyErrorFactory\n  subject?: string\n}\n\nexport function parseOutboundUrl(\n  rawUrl: string,\n  options: ParseOutboundUrlOptions = {},\n): ParsedOutboundUrl {\n  const subject = options.subject ?? 'URL'\n  const factory = options.errorFactory ?? defaultErrorFactory\n  let url: URL\n  try {\n    url = new URL(rawUrl)\n  } catch {\n    throw factory('invalid_url', `${subject} is not a valid URL`)\n  }\n  if (!ALLOWED_PROTOCOLS.has(url.protocol)) {\n    throw factory(\n      'forbidden_protocol',\n      `${subject} protocol \"${url.protocol.replace(':', '')}\" is not allowed; use http or https`,\n    )\n  }\n  if (url.username || url.password) {\n    throw factory('credentials_in_url', `${subject} must not embed basic-auth credentials`)\n  }\n  let hostname = url.hostname.trim().toLowerCase()\n  if (!hostname) {\n    throw factory('missing_host', `${subject} must include a hostname`)\n  }\n  if (hostname.startsWith('[') && hostname.endsWith(']')) {\n    hostname = hostname.slice(1, -1)\n  }\n  return { url, hostname }\n}\n\nexport type HostLookup = (\n  hostname: string,\n) => Promise<ReadonlyArray<{ address: string; family: number }>>\n\nexport type AssertStaticUrlOptions = ParseOutboundUrlOptions & {\n  allowPrivate?: boolean\n}\n\nexport function assertStaticallySafeOutboundUrl(\n  rawUrl: string,\n  options: AssertStaticUrlOptions = {},\n): void {\n  const subject = options.subject ?? 'URL'\n  const factory = options.errorFactory ?? defaultErrorFactory\n  const { hostname } = parseOutboundUrl(rawUrl, options)\n  if (options.allowPrivate) return\n\n  if (isBlockedHostname(hostname)) {\n    throw factory('blocked_hostname', `${subject} host \"${hostname}\" is not allowed`)\n  }\n  if (isIP(hostname) && isPrivateIpAddress(hostname)) {\n    throw factory(\n      'private_ip_literal',\n      `${subject} host \"${hostname}\" resolves to a private or reserved IP range`,\n    )\n  }\n}\n\nexport type AssertSafeOutboundUrlOptions = AssertStaticUrlOptions & {\n  lookupHost?: HostLookup\n}\n\nexport async function assertSafeOutboundUrl(\n  rawUrl: string,\n  options: AssertSafeOutboundUrlOptions = {},\n): Promise<void> {\n  await resolveSafeOutboundUrl(rawUrl, options)\n}\n\nexport type ResolvedHostAddress = { address: string; family: number }\n\nexport type ResolveSafeOutboundUrlResult = {\n  url: URL\n  hostname: string\n  /**\n   * The validated DNS records, in lookup order. `null` when the hostname is an IP literal\n   * (no DNS lookup performed) or when `allowPrivate` short-circuited validation.\n   */\n  addresses: ReadonlyArray<ResolvedHostAddress> | null\n}\n\n/**\n * Validates an outbound URL exactly like `assertSafeOutboundUrl()` and additionally returns\n * the resolved DNS records so the caller can pin the subsequent connection to the same\n * address. This is what `safeOutboundFetch()` uses internally to defeat DNS rebinding \u2014\n * call it directly only if you need to drive the fetch yourself.\n */\nexport async function resolveSafeOutboundUrl(\n  rawUrl: string,\n  options: AssertSafeOutboundUrlOptions = {},\n): Promise<ResolveSafeOutboundUrlResult> {\n  const subject = options.subject ?? 'URL'\n  const factory = options.errorFactory ?? defaultErrorFactory\n  const { url, hostname } = parseOutboundUrl(rawUrl, options)\n  if (options.allowPrivate) return { url, hostname, addresses: null }\n\n  if (isBlockedHostname(hostname)) {\n    throw factory('blocked_hostname', `${subject} host \"${hostname}\" is not allowed`)\n  }\n\n  if (isIP(hostname)) {\n    if (isPrivateIpAddress(hostname)) {\n      throw factory(\n        'private_ip_literal',\n        `${subject} host \"${hostname}\" resolves to a private or reserved IP range`,\n      )\n    }\n    return { url, hostname, addresses: null }\n  }\n\n  const resolver: HostLookup =\n    options.lookupHost ??\n    (async (host) => {\n      const records = await lookup(host, { all: true, verbatim: true })\n      return records\n    })\n\n  let addresses: ReadonlyArray<ResolvedHostAddress>\n  try {\n    addresses = await resolver(hostname)\n  } catch (error) {\n    throw factory(\n      'dns_resolution_failed',\n      `${subject} host \"${hostname}\" could not be resolved: ${\n        error instanceof Error ? error.message : 'lookup failed'\n      }`,\n    )\n  }\n\n  if (!addresses || addresses.length === 0) {\n    throw factory(\n      'dns_resolution_empty',\n      `${subject} host \"${hostname}\" has no DNS A/AAAA records`,\n    )\n  }\n\n  for (const record of addresses) {\n    if (isPrivateIpAddress(record.address)) {\n      throw factory(\n        'private_ip_resolved',\n        `${subject} host \"${hostname}\" resolves to a private or reserved IP address (${record.address})`,\n      )\n    }\n  }\n\n  return { url, hostname, addresses }\n}\n\nexport type SafeOutboundFetchOptions = AssertSafeOutboundUrlOptions & {\n  /**\n   * Test/seam injection. When provided, `safeOutboundFetch` calls `fetchImpl(url, init)` after\n   * URL validation instead of using the global `fetch` with a DNS-pinned dispatcher. Tests do\n   * not actually open sockets, so DNS pinning is unnecessary and would just complicate mocking.\n   */\n  fetchImpl?: typeof fetch\n}\n\n/**\n * Validates an outbound URL and performs `fetch()` with the connection pinned to a\n * pre-validated IP address, so DNS cannot be re-resolved between validation and connect\n * (DNS rebinding). Always defaults to `redirect: 'manual'` \u2014 callers MUST decide what to\n * do with 3xx responses (re-validate the redirect target before following).\n *\n * For IP literal hosts and `allowPrivate=true`, no DNS pinning is performed because there\n * is no DNS lookup to defeat.\n */\nexport async function safeOutboundFetch(\n  rawUrl: string,\n  init: RequestInit = {},\n  options: SafeOutboundFetchOptions = {},\n): Promise<Response> {\n  const { url, hostname, addresses } = await resolveSafeOutboundUrl(rawUrl, options)\n  void url\n\n  const mergedInit: RequestInit = {\n    redirect: 'manual',\n    ...init,\n  }\n\n  const fetchImpl = options.fetchImpl\n  if (fetchImpl) {\n    return fetchImpl(rawUrl, mergedInit)\n  }\n\n  if (!addresses || addresses.length === 0) {\n    return globalThis.fetch(rawUrl, mergedInit)\n  }\n\n  const dispatcher: Dispatcher = new Agent({\n    connect: {\n      lookup: createPinnedDnsLookup(hostname, addresses[0]),\n    },\n  })\n\n  try {\n    return await globalThis.fetch(rawUrl, { ...mergedInit, dispatcher } as RequestInit & {\n      dispatcher: Dispatcher\n    })\n  } finally {\n    dispatcher.close().catch(() => {})\n  }\n}\n\nexport type PinnedDnsLookup = (\n  host: string,\n  opts: unknown,\n  cb: (err: NodeJS.ErrnoException | null, address: string, family: number) => void,\n) => void\n\n/**\n * Builds a `dns.lookup`-shaped callback that always returns the supplied pre-validated\n * address for the expected hostname, and refuses to resolve any other hostname. Used as\n * `Agent.connect.lookup` to bind an outbound TCP connect to an IP that has already been\n * validated, so attacker-controlled DNS cannot rebind between validation and connect.\n */\nexport function createPinnedDnsLookup(\n  expectedHostname: string,\n  pinned: ResolvedHostAddress,\n): PinnedDnsLookup {\n  return (host, _opts, cb) => {\n    if (host !== expectedHostname) {\n      const err: NodeJS.ErrnoException = new Error(\n        `Refusing DNS lookup for unexpected host \"${host}\" (expected \"${expectedHostname}\")`,\n      )\n      err.code = 'EREFUSED'\n      cb(err, '', 0)\n      return\n    }\n    cb(null, pinned.address, pinned.family)\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.5.1-develop.2912.8d7b1fef24";
+const APP_VERSION = "0.5.1-develop.2924.d13908516e";
 const appVersion = APP_VERSION;
 export {
   APP_VERSION,

package/dist/lib/version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/version.ts"],
-  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.5.1-develop.2912.8d7b1fef24'\nexport const appVersion = APP_VERSION\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.5.1-develop.2924.d13908516e'\nexport const appVersion = APP_VERSION\n"],
   "mappings": "AACO,MAAM,cAAc;AACpB,MAAM,aAAa;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.5.1-develop.2912.8d7b1fef24",
+  "version": "0.5.1-develop.2924.d13908516e",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -92,11 +92,12 @@
     "@mikro-orm/core": "^7.0.10",
     "@mikro-orm/decorators": "^7.0.10",
     "@mikro-orm/postgresql": "^7.0.10",
-    "@open-mercato/cache": "0.5.1-develop.2912.8d7b1fef24",
+    "@open-mercato/cache": "0.5.1-develop.2924.d13908516e",
     "dotenv": "^17.4.2",
     "rate-limiter-flexible": "^11.0.1",
     "reflect-metadata": "^0.2.2",
-    "sanitize-html": "^2.17.2"
+    "sanitize-html": "^2.17.2",
+    "undici": "^7.24.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",

package/src/lib/__tests__/url-safety.test.ts

@@ -1,7 +1,10 @@
 import {
   assertSafeOutboundUrl,
   assertStaticallySafeOutboundUrl,
+  createPinnedDnsLookup,
   parseOutboundUrl,
+  resolveSafeOutboundUrl,
+  safeOutboundFetch,
   UnsafeOutboundUrlError,
 } from '../url-safety'
 
@@ -174,3 +177,132 @@ describe('url-safety — assertSafeOutboundUrl (DNS rebinding guard)', () => {
     ).rejects.toMatchObject({ reason: 'forbidden_protocol' })
   })
 })
+
+describe('url-safety — resolveSafeOutboundUrl', () => {
+  it('returns the validated DNS records for use as pinning input', async () => {
+    const records = [
+      { address: '93.184.216.34', family: 4 },
+      { address: '93.184.216.35', family: 4 },
+    ]
+    const lookupHost = jest.fn(async () => records)
+    const result = await resolveSafeOutboundUrl('https://good.example/', {
+      lookupHost,
+      allowPrivate: false,
+    })
+    expect(result.hostname).toBe('good.example')
+    expect(result.addresses).toEqual(records)
+    expect(lookupHost).toHaveBeenCalledTimes(1)
+  })
+
+  it('returns null addresses for IP literal hosts (no DNS to pin)', async () => {
+    const result = await resolveSafeOutboundUrl('https://1.1.1.1/x', { allowPrivate: false })
+    expect(result.addresses).toBeNull()
+  })
+
+  it('returns null addresses when allowPrivate short-circuits validation', async () => {
+    const lookupHost = jest.fn()
+    const result = await resolveSafeOutboundUrl('http://internal.example/', {
+      lookupHost,
+      allowPrivate: true,
+    })
+    expect(result.addresses).toBeNull()
+    expect(lookupHost).not.toHaveBeenCalled()
+  })
+
+  it('throws on private resolution before returning addresses', async () => {
+    const lookupHost = jest.fn(async () => [{ address: '10.0.0.5', family: 4 }])
+    await expect(
+      resolveSafeOutboundUrl('https://rebind.evil.example/', {
+        lookupHost,
+        allowPrivate: false,
+      }),
+    ).rejects.toMatchObject({ reason: 'private_ip_resolved' })
+  })
+})
+
+describe('url-safety — createPinnedDnsLookup', () => {
+  it('returns the pinned address only for the expected hostname', () => {
+    const lookup = createPinnedDnsLookup('good.example', { address: '93.184.216.34', family: 4 })
+    const cb = jest.fn()
+    lookup('good.example', {}, cb)
+    expect(cb).toHaveBeenCalledWith(null, '93.184.216.34', 4)
+  })
+
+  it('refuses to resolve a different hostname (defeats redirect to private host via Host header)', () => {
+    const lookup = createPinnedDnsLookup('good.example', { address: '93.184.216.34', family: 4 })
+    const cb = jest.fn()
+    lookup('attacker.example', {}, cb)
+    expect(cb).toHaveBeenCalledTimes(1)
+    const [err, address, family] = (cb as jest.Mock).mock.calls[0]
+    expect(err).toBeInstanceOf(Error)
+    expect((err as NodeJS.ErrnoException).code).toBe('EREFUSED')
+    expect(address).toBe('')
+    expect(family).toBe(0)
+  })
+})
+
+describe('url-safety — safeOutboundFetch', () => {
+  it('rejects unsafe URLs before invoking fetchImpl (no socket attempted)', async () => {
+    const fetchImpl = jest.fn() as unknown as typeof fetch
+    await expect(
+      safeOutboundFetch(
+        'http://169.254.169.254/latest/meta-data/',
+        {},
+        { fetchImpl, allowPrivate: false },
+      ),
+    ).rejects.toMatchObject({ reason: 'private_ip_literal' })
+    expect(fetchImpl).not.toHaveBeenCalled()
+  })
+
+  it('rejects DNS-rebinding hosts (lookup returns private) before fetch', async () => {
+    const fetchImpl = jest.fn() as unknown as typeof fetch
+    const lookupHost = jest.fn(async () => [{ address: '10.0.0.5', family: 4 }])
+    await expect(
+      safeOutboundFetch(
+        'https://rebind.evil.example/',
+        {},
+        { fetchImpl, lookupHost, allowPrivate: false },
+      ),
+    ).rejects.toMatchObject({ reason: 'private_ip_resolved' })
+    expect(fetchImpl).not.toHaveBeenCalled()
+  })
+
+  it('invokes fetchImpl with redirect:"manual" by default', async () => {
+    const fetchImpl = jest.fn(async () => new Response('ok', { status: 200 })) as unknown as typeof fetch
+    const lookupHost = jest.fn(async () => [{ address: '93.184.216.34', family: 4 }])
+    const response = await safeOutboundFetch(
+      'https://good.example/hook',
+      { method: 'POST' },
+      { fetchImpl, lookupHost, allowPrivate: false },
+    )
+    expect(response.status).toBe(200)
+    expect(fetchImpl).toHaveBeenCalledTimes(1)
+    const [calledUrl, calledInit] = (fetchImpl as unknown as jest.Mock).mock.calls[0]
+    expect(calledUrl).toBe('https://good.example/hook')
+    expect(calledInit).toEqual(
+      expect.objectContaining({ method: 'POST', redirect: 'manual' }),
+    )
+  })
+
+  it('preserves caller-provided redirect override', async () => {
+    const fetchImpl = jest.fn(async () => new Response('ok', { status: 200 })) as unknown as typeof fetch
+    await safeOutboundFetch(
+      'http://127.0.0.1:3000/dev',
+      { redirect: 'follow' },
+      { fetchImpl, allowPrivate: true },
+    )
+    const [, calledInit] = (fetchImpl as unknown as jest.Mock).mock.calls[0]
+    expect(calledInit.redirect).toBe('follow')
+  })
+
+  it('runs DNS validation exactly once (the same address is pinned for connect)', async () => {
+    const fetchImpl = jest.fn(async () => new Response('ok', { status: 200 })) as unknown as typeof fetch
+    const lookupHost = jest.fn(async () => [{ address: '93.184.216.34', family: 4 }])
+    await safeOutboundFetch(
+      'https://good.example/hook',
+      {},
+      { fetchImpl, lookupHost, allowPrivate: false },
+    )
+    expect(lookupHost).toHaveBeenCalledTimes(1)
+  })
+})

package/src/lib/url-safety.ts

@@ -1,5 +1,6 @@
 import { lookup } from 'node:dns/promises'
 import { isIP } from 'node:net'
+import { Agent, type Dispatcher } from 'undici'
 import { isBlockedHostname, isPrivateIpAddress } from './network'
 
 export type UrlSafetyReason =
@@ -107,10 +108,35 @@ export async function assertSafeOutboundUrl(
   rawUrl: string,
   options: AssertSafeOutboundUrlOptions = {},
 ): Promise<void> {
+  await resolveSafeOutboundUrl(rawUrl, options)
+}
+
+export type ResolvedHostAddress = { address: string; family: number }
+
+export type ResolveSafeOutboundUrlResult = {
+  url: URL
+  hostname: string
+  /**
+   * The validated DNS records, in lookup order. `null` when the hostname is an IP literal
+   * (no DNS lookup performed) or when `allowPrivate` short-circuited validation.
+   */
+  addresses: ReadonlyArray<ResolvedHostAddress> | null
+}
+
+/**
+ * Validates an outbound URL exactly like `assertSafeOutboundUrl()` and additionally returns
+ * the resolved DNS records so the caller can pin the subsequent connection to the same
+ * address. This is what `safeOutboundFetch()` uses internally to defeat DNS rebinding —
+ * call it directly only if you need to drive the fetch yourself.
+ */
+export async function resolveSafeOutboundUrl(
+  rawUrl: string,
+  options: AssertSafeOutboundUrlOptions = {},
+): Promise<ResolveSafeOutboundUrlResult> {
   const subject = options.subject ?? 'URL'
   const factory = options.errorFactory ?? defaultErrorFactory
-  const { hostname } = parseOutboundUrl(rawUrl, options)
-  if (options.allowPrivate) return
+  const { url, hostname } = parseOutboundUrl(rawUrl, options)
+  if (options.allowPrivate) return { url, hostname, addresses: null }
 
   if (isBlockedHostname(hostname)) {
     throw factory('blocked_hostname', `${subject} host "${hostname}" is not allowed`)
@@ -123,7 +149,7 @@ export async function assertSafeOutboundUrl(
         `${subject} host "${hostname}" resolves to a private or reserved IP range`,
       )
     }
-    return
+    return { url, hostname, addresses: null }
   }
 
   const resolver: HostLookup =
@@ -133,7 +159,7 @@ export async function assertSafeOutboundUrl(
       return records
     })
 
-  let addresses: ReadonlyArray<{ address: string; family: number }>
+  let addresses: ReadonlyArray<ResolvedHostAddress>
   try {
     addresses = await resolver(hostname)
   } catch (error) {
@@ -160,4 +186,90 @@ export async function assertSafeOutboundUrl(
       )
     }
   }
+
+  return { url, hostname, addresses }
+}
+
+export type SafeOutboundFetchOptions = AssertSafeOutboundUrlOptions & {
+  /**
+   * Test/seam injection. When provided, `safeOutboundFetch` calls `fetchImpl(url, init)` after
+   * URL validation instead of using the global `fetch` with a DNS-pinned dispatcher. Tests do
+   * not actually open sockets, so DNS pinning is unnecessary and would just complicate mocking.
+   */
+  fetchImpl?: typeof fetch
+}
+
+/**
+ * Validates an outbound URL and performs `fetch()` with the connection pinned to a
+ * pre-validated IP address, so DNS cannot be re-resolved between validation and connect
+ * (DNS rebinding). Always defaults to `redirect: 'manual'` — callers MUST decide what to
+ * do with 3xx responses (re-validate the redirect target before following).
+ *
+ * For IP literal hosts and `allowPrivate=true`, no DNS pinning is performed because there
+ * is no DNS lookup to defeat.
+ */
+export async function safeOutboundFetch(
+  rawUrl: string,
+  init: RequestInit = {},
+  options: SafeOutboundFetchOptions = {},
+): Promise<Response> {
+  const { url, hostname, addresses } = await resolveSafeOutboundUrl(rawUrl, options)
+  void url
+
+  const mergedInit: RequestInit = {
+    redirect: 'manual',
+    ...init,
+  }
+
+  const fetchImpl = options.fetchImpl
+  if (fetchImpl) {
+    return fetchImpl(rawUrl, mergedInit)
+  }
+
+  if (!addresses || addresses.length === 0) {
+    return globalThis.fetch(rawUrl, mergedInit)
+  }
+
+  const dispatcher: Dispatcher = new Agent({
+    connect: {
+      lookup: createPinnedDnsLookup(hostname, addresses[0]),
+    },
+  })
+
+  try {
+    return await globalThis.fetch(rawUrl, { ...mergedInit, dispatcher } as RequestInit & {
+      dispatcher: Dispatcher
+    })
+  } finally {
+    dispatcher.close().catch(() => {})
+  }
+}
+
+export type PinnedDnsLookup = (
+  host: string,
+  opts: unknown,
+  cb: (err: NodeJS.ErrnoException | null, address: string, family: number) => void,
+) => void
+
+/**
+ * Builds a `dns.lookup`-shaped callback that always returns the supplied pre-validated
+ * address for the expected hostname, and refuses to resolve any other hostname. Used as
+ * `Agent.connect.lookup` to bind an outbound TCP connect to an IP that has already been
+ * validated, so attacker-controlled DNS cannot rebind between validation and connect.
+ */
+export function createPinnedDnsLookup(
+  expectedHostname: string,
+  pinned: ResolvedHostAddress,
+): PinnedDnsLookup {
+  return (host, _opts, cb) => {
+    if (host !== expectedHostname) {
+      const err: NodeJS.ErrnoException = new Error(
+        `Refusing DNS lookup for unexpected host "${host}" (expected "${expectedHostname}")`,
+      )
+      err.code = 'EREFUSED'
+      cb(err, '', 0)
+      return
+    }
+    cb(null, pinned.address, pinned.family)
+  }
 }