@pikku/core 0.12.63 → 0.12.64

package/src/utils/safe-fetch.test.ts

@@ -0,0 +1,373 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { assertFetchableUrl, isPrivateHost, safeFetch } from './safe-fetch.js'
+
+describe('isPrivateHost', () => {
+  test('flags loopback, private ranges, and cloud metadata', () => {
+    for (const host of [
+      'localhost',
+      '127.0.0.1',
+      '0.0.0.0',
+      '10.1.2.3',
+      '172.16.0.1',
+      '172.31.255.255',
+      '192.168.1.1',
+      '169.254.169.254',
+      '::1',
+      '[::1]',
+      'fd00::1',
+    ]) {
+      assert.equal(isPrivateHost(host), true, `${host} should be private`)
+    }
+  })
+
+  test('flags alias and encoded forms of internal hosts', () => {
+    for (const host of [
+      'localhost.', // trailing-dot FQDN
+      'foo.localhost', // *.localhost resolves to loopback (RFC 6761)
+      '::', // unspecified address
+      '::ffff:127.0.0.1', // IPv4-mapped IPv6 (dotted)
+      '::ffff:7f00:1', // IPv4-mapped IPv6 (hex, as URL normalizes it)
+      '2130706433', // decimal-encoded 127.0.0.1
+      '0x7f000001', // hex-encoded 127.0.0.1
+      '0177.0.0.1', // octal first octet (127)
+      '0x7f.0.0.1', // hex first octet (127)
+      'fe80::1', // link-local
+      'fea9::1', // link-local within fe80::/10
+      'febf::1', // top of fe80::/10
+    ]) {
+      assert.equal(isPrivateHost(host), true, `${host} should be private`)
+    }
+  })
+
+  test('allows public hosts', () => {
+    for (const host of [
+      'example.com',
+      '8.8.8.8',
+      '172.32.0.1',
+      '11.0.0.1',
+      '134744072', // decimal-encoded 8.8.8.8 — public
+      '2001:db8::1', // documentation range — public
+      'fec0::1', // deprecated site-local, outside fe80::/10 — treated public
+    ]) {
+      assert.equal(isPrivateHost(host), false, `${host} should be public`)
+    }
+  })
+})
+
+describe('assertFetchableUrl', () => {
+  test('rejects non-HTTP(S) schemes', () => {
+    assert.throws(() => assertFetchableUrl('file:///etc/passwd'), /non-HTTP/)
+    assert.throws(() => assertFetchableUrl('ftp://example.com'), /non-HTTP/)
+  })
+
+  test('rejects private hosts by default', () => {
+    assert.throws(
+      () => assertFetchableUrl('http://169.254.169.254/latest/meta-data/'),
+      /private\/internal host/
+    )
+  })
+
+  test('honours an allowlist (and rejects hosts not on it)', () => {
+    assert.doesNotThrow(() =>
+      assertFetchableUrl('http://internal.svc/x', {
+        allowedHosts: ['internal.svc'],
+      })
+    )
+    assert.throws(
+      () =>
+        assertFetchableUrl('https://example.com', {
+          allowedHosts: ['internal.svc'],
+        }),
+      /not in the allowlist/
+    )
+  })
+})
+
+describe('safeFetch', () => {
+  const withStubbedFetch = async (
+    handler: (url: string, init: RequestInit) => Response,
+    run: (calls: string[]) => Promise<void>
+  ) => {
+    const original = globalThis.fetch
+    const calls: string[] = []
+    globalThis.fetch = (async (u: any, init: any) => {
+      calls.push(String(u))
+      return handler(String(u), init)
+    }) as typeof fetch
+    try {
+      await run(calls)
+    } finally {
+      globalThis.fetch = original
+    }
+  }
+
+  test('never issues a request to a private target', async () => {
+    await withStubbedFetch(
+      () => new Response(null, { status: 200 }),
+      async (calls) => {
+        await assert.rejects(
+          safeFetch('http://169.254.169.254/latest/meta-data/'),
+          /private\/internal host/
+        )
+        assert.equal(calls.length, 0, 'must not have called fetch at all')
+      }
+    )
+  })
+
+  test('does not follow a redirect into a private host', async () => {
+    await withStubbedFetch(
+      (url) =>
+        url.includes('example.com')
+          ? new Response(null, {
+              status: 302,
+              headers: { location: 'http://169.254.169.254/' },
+            })
+          : new Response(null, { status: 200 }),
+      async (calls) => {
+        // The redirect target is private, so following it is refused and the
+        // private host is never fetched (only the initial hop was requested).
+        await assert.rejects(
+          safeFetch('https://example.com/hook'),
+          /private\/internal host/
+        )
+        assert.equal(calls.length, 1)
+        assert.ok(calls[0]!.includes('example.com'))
+      }
+    )
+  })
+
+  test('follows a redirect to another public host', async () => {
+    await withStubbedFetch(
+      (url) =>
+        url.includes('start.com')
+          ? new Response(null, {
+              status: 302,
+              headers: { location: 'https://end.com/final' },
+            })
+          : new Response('ok', { status: 200 }),
+      async (calls) => {
+        const res = await safeFetch('https://start.com')
+        assert.equal(res.status, 200)
+        assert.deepEqual(calls, ['https://start.com/', 'https://end.com/final'])
+      }
+    )
+  })
+
+  const withHeaderCapturingFetch = async (
+    handler: (url: string) => Response,
+    run: (
+      headersByUrl: Array<{ url: string; headers: Headers }>
+    ) => Promise<void>
+  ) => {
+    const original = globalThis.fetch
+    const seen: Array<{ url: string; headers: Headers }> = []
+    globalThis.fetch = (async (u: any, init: any) => {
+      seen.push({ url: String(u), headers: new Headers(init?.headers) })
+      return handler(String(u))
+    }) as typeof fetch
+    try {
+      await run(seen)
+    } finally {
+      globalThis.fetch = original
+    }
+  }
+
+  test('strips Authorization and Cookie when a redirect crosses origin', async () => {
+    await withHeaderCapturingFetch(
+      (url) =>
+        url.includes('start.com')
+          ? new Response(null, {
+              status: 302,
+              headers: { location: 'https://other.com/final' },
+            })
+          : new Response('ok', { status: 200 }),
+      async (seen) => {
+        await safeFetch('https://start.com', {
+          headers: {
+            authorization: 'Bearer secret',
+            cookie: 'session=abc',
+            'x-trace': 'keep-me',
+          },
+        })
+        assert.equal(seen.length, 2)
+        assert.equal(seen[0]!.headers.get('authorization'), 'Bearer secret')
+        assert.equal(seen[1]!.url, 'https://other.com/final')
+        assert.equal(seen[1]!.headers.get('authorization'), null)
+        assert.equal(seen[1]!.headers.get('cookie'), null)
+        assert.equal(seen[1]!.headers.get('x-trace'), 'keep-me')
+      }
+    )
+  })
+
+  test('preserves Authorization and Cookie on a same-origin redirect', async () => {
+    await withHeaderCapturingFetch(
+      (url) =>
+        url.endsWith('/a')
+          ? new Response(null, {
+              status: 302,
+              headers: { location: 'https://same.com/b' },
+            })
+          : new Response('ok', { status: 200 }),
+      async (seen) => {
+        await safeFetch('https://same.com/a', {
+          headers: { authorization: 'Bearer secret', cookie: 'session=abc' },
+        })
+        assert.equal(seen.length, 2)
+        assert.equal(seen[1]!.url, 'https://same.com/b')
+        assert.equal(seen[1]!.headers.get('authorization'), 'Bearer secret')
+        assert.equal(seen[1]!.headers.get('cookie'), 'session=abc')
+      }
+    )
+  })
+
+  const withMethodCapturingFetch = async (
+    handler: (url: string) => Response,
+    run: (
+      seen: Array<{ url: string; method: string; body: unknown }>
+    ) => Promise<void>
+  ) => {
+    const original = globalThis.fetch
+    const seen: Array<{ url: string; method: string; body: unknown }> = []
+    globalThis.fetch = (async (u: any, init: any) => {
+      seen.push({
+        url: String(u),
+        method: (init?.method ?? 'GET').toUpperCase(),
+        body: init?.body,
+      })
+      return handler(String(u))
+    }) as typeof fetch
+    try {
+      await run(seen)
+    } finally {
+      globalThis.fetch = original
+    }
+  }
+
+  test('rewrites POST to GET and drops the body on a 303 redirect', async () => {
+    await withMethodCapturingFetch(
+      (url) =>
+        url.endsWith('/submit')
+          ? new Response(null, {
+              status: 303,
+              headers: { location: 'https://start.com/result' },
+            })
+          : new Response('ok', { status: 200 }),
+      async (seen) => {
+        await safeFetch('https://start.com/submit', {
+          method: 'POST',
+          body: 'payload',
+          headers: { 'content-type': 'text/plain' },
+        })
+        assert.equal(seen.length, 2)
+        assert.equal(seen[1]!.method, 'GET')
+        assert.equal(seen[1]!.body, undefined)
+      }
+    )
+  })
+
+  test('rewrites POST to GET on a 302 redirect', async () => {
+    await withMethodCapturingFetch(
+      (url) =>
+        url.endsWith('/submit')
+          ? new Response(null, {
+              status: 302,
+              headers: { location: 'https://start.com/result' },
+            })
+          : new Response('ok', { status: 200 }),
+      async (seen) => {
+        await safeFetch('https://start.com/submit', {
+          method: 'POST',
+          body: 'payload',
+        })
+        assert.equal(seen[1]!.method, 'GET')
+        assert.equal(seen[1]!.body, undefined)
+      }
+    )
+  })
+
+  test('preserves method and body on a 307/308 redirect', async () => {
+    for (const status of [307, 308]) {
+      await withMethodCapturingFetch(
+        (url) =>
+          url.endsWith('/submit')
+            ? new Response(null, {
+                status,
+                headers: { location: 'https://start.com/result' },
+              })
+            : new Response('ok', { status: 200 }),
+        async (seen) => {
+          await safeFetch('https://start.com/submit', {
+            method: 'POST',
+            body: 'payload',
+          })
+          assert.equal(seen[1]!.method, 'POST', `status ${status}`)
+          assert.equal(seen[1]!.body, 'payload', `status ${status}`)
+        }
+      )
+    }
+  })
+
+  test('does not follow non-redirect 3xx statuses even with a Location', async () => {
+    for (const status of [300, 304, 305, 306]) {
+      await withStubbedFetch(
+        () =>
+          new Response(null, {
+            status,
+            headers: { location: 'https://end.com/final' },
+          }),
+        async (calls) => {
+          const res = await safeFetch('https://start.com')
+          assert.equal(res.status, status, `status ${status}`)
+          assert.equal(calls.length, 1, `status ${status} must not follow`)
+        }
+      )
+    }
+  })
+
+  test('cancels the intermediate redirect response body before following', async () => {
+    const original = globalThis.fetch
+    let cancelled = false
+    globalThis.fetch = (async (u: any) => {
+      if (String(u).endsWith('/a')) {
+        const body = new ReadableStream({
+          cancel() {
+            cancelled = true
+          },
+        })
+        return new Response(body, {
+          status: 302,
+          headers: { location: 'https://start.com/b' },
+        })
+      }
+      return new Response('ok', { status: 200 })
+    }) as typeof fetch
+    try {
+      await safeFetch('https://start.com/a')
+    } finally {
+      globalThis.fetch = original
+    }
+    assert.equal(cancelled, true, 'intermediate body should be cancelled')
+  })
+
+  test('forces redirect:manual on the underlying fetch', async () => {
+    await withStubbedFetch(
+      () => new Response('ok', { status: 200 }),
+      async () => {
+        let seenRedirect: RequestRedirect | undefined
+        const original = globalThis.fetch
+        globalThis.fetch = (async (_u: any, init: any) => {
+          seenRedirect = init?.redirect
+          return new Response('ok', { status: 200 })
+        }) as typeof fetch
+        try {
+          await safeFetch('https://example.com', { redirect: 'follow' })
+        } finally {
+          globalThis.fetch = original
+        }
+        assert.equal(seenRedirect, 'manual')
+      }
+    )
+  })
+})

package/src/utils/safe-fetch.ts

@@ -0,0 +1,213 @@
+/**
+ * SSRF-aware fetch helpers.
+ *
+ * `@pikku/core` runs in edge runtimes (Cloudflare Workers) with no Node `dns`,
+ * so we cannot resolve hostnames to check for private targets. We reject the
+ * obvious internal literals and, crucially, re-validate every redirect hop —
+ * a public URL that 302s to `169.254.169.254` is the common bypass. This does
+ * NOT defend against a public hostname that itself resolves to a private IP
+ * (DNS rebinding), which is out of reach without DNS resolution.
+ */
+
+/**
+ * Parse the many textual encodings of an IPv4 address that `fetch`/`undici`
+ * (and `inet_aton`-style parsers) accept — a dotted quad whose octets may be
+ * decimal, octal (`0177`) or hex (`0x7f`), or the whole address as a single
+ * 32-bit integer (decimal `2130706433`, hex `0x7f000001`). Returns the four
+ * octets, or `null` when the host is not a numeric IPv4 literal.
+ */
+function parseIPv4Octets(
+  host: string
+): [number, number, number, number] | null {
+  const toInt = (part: string): number | null => {
+    let n: number
+    if (/^0x[0-9a-f]+$/.test(part)) n = parseInt(part, 16)
+    else if (/^0[0-7]+$/.test(part)) n = parseInt(part, 8)
+    else if (/^\d+$/.test(part)) n = parseInt(part, 10)
+    else return null
+    return Number.isInteger(n) ? n : null
+  }
+
+  if (!host.includes('.')) {
+    const n = toInt(host)
+    if (n === null || n < 0 || n > 0xffffffff) return null
+    return [(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff]
+  }
+
+  const parts = host.split('.')
+  if (parts.length !== 4) return null
+  const octets: number[] = []
+  for (const part of parts) {
+    const n = toInt(part)
+    if (n === null || n < 0 || n > 0xff) return null
+    octets.push(n)
+  }
+  return octets as [number, number, number, number]
+}
+
+/**
+ * Whether a hostname is an obvious internal/private target (loopback, private
+ * IPv4 ranges, link-local incl. the cloud metadata endpoint, or private IPv6).
+ *
+ * Alias/encoded forms that resolve to the same targets are also rejected: a
+ * trailing-dot FQDN (`localhost.`), the `*.localhost` reserved name, IPv4-mapped
+ * IPv6 (`::ffff:127.0.0.1`), and octal/decimal/hex-encoded IPv4. This is
+ * best-effort literal matching only — it cannot catch a public hostname that
+ * *resolves* to a private IP (DNS rebinding), which needs DNS resolution
+ * unavailable in edge runtimes.
+ */
+export function isPrivateHost(hostname: string): boolean {
+  const host = hostname
+    .replace(/^\[|\]$/g, '')
+    .replace(/\.$/, '')
+    .toLowerCase()
+  if (host === '' || host === 'localhost' || host.endsWith('.localhost'))
+    return true
+
+  if (host.includes(':')) {
+    if (host === '::' || host === '::1') return true
+    const mappedV4 = host.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/)
+    if (mappedV4) return isPrivateHost(mappedV4[1]!)
+    const mappedHex = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/)
+    if (mappedHex) {
+      const hi = parseInt(mappedHex[1]!, 16)
+      const lo = parseInt(mappedHex[2]!, 16)
+      return isPrivateHost(
+        `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`
+      )
+    }
+    if (/^fe[89ab]/.test(host)) return true // link-local fe80::/10
+    if (host.startsWith('fc') || host.startsWith('fd')) return true // unique-local fc00::/7
+    return false
+  }
+
+  const v4 = parseIPv4Octets(host)
+  if (v4) {
+    const [a, b] = v4
+    if (a === 127 || a === 10 || a === 0) return true
+    if (a === 169 && b === 254) return true // link-local incl. cloud metadata
+    if (a === 172 && b >= 16 && b <= 31) return true
+    if (a === 192 && b === 168) return true
+  }
+  return false
+}
+
+export interface SafeFetchOptions {
+  /**
+   * When set, the host of every hop must appear in this allowlist. When omitted,
+   * any host that is not {@link isPrivateHost} is permitted.
+   */
+  allowedHosts?: string[]
+  /** Maximum redirect hops to follow (each re-validated). Defaults to 3. */
+  maxRedirects?: number
+}
+
+/**
+ * Parse and validate a URL for outbound fetching: only http(s), and — unless an
+ * `allowedHosts` allowlist is supplied — not an obvious private/internal host.
+ * Returns the parsed URL or throws.
+ */
+export function assertFetchableUrl(
+  url: string,
+  options: SafeFetchOptions = {}
+): URL {
+  const parsed = new URL(url)
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new Error(`Refusing to fetch non-HTTP(S) URL: ${parsed.protocol}`)
+  }
+  if (options.allowedHosts) {
+    if (!options.allowedHosts.includes(parsed.hostname)) {
+      throw new Error(`URL host is not in the allowlist: ${parsed.hostname}`)
+    }
+  } else if (isPrivateHost(parsed.hostname)) {
+    throw new Error(
+      `Refusing to fetch from a private/internal host: ${parsed.hostname}`
+    )
+  }
+  return parsed
+}
+
+/**
+ * The only 3xx statuses that request a redirect be followed. `300` (Multiple
+ * Choices), `304` (Not Modified), `305` (Use Proxy) and `306` are returned to
+ * the caller as-is rather than followed.
+ */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308])
+
+/**
+ * Drop credential-bearing headers (`Authorization`, `Cookie`) so they are not
+ * replayed to a different origin across a redirect.
+ */
+function stripCredentialHeaders(init: RequestInit): RequestInit {
+  if (!init.headers) return init
+  const headers = new Headers(init.headers)
+  headers.delete('authorization')
+  headers.delete('cookie')
+  return { ...init, headers }
+}
+
+/**
+ * Apply the WHATWG-fetch method/body transform for a redirect: a `303` (and a
+ * `301`/`302` on a `POST`) becomes a bodyless `GET`; `307`/`308` preserve the
+ * original method and body. When the method changes to `GET` the request body
+ * and its `Content-*` headers are dropped.
+ */
+function redirectInit(status: number, init: RequestInit): RequestInit {
+  const method = (init.method ?? 'GET').toUpperCase()
+  const toGet =
+    (status === 303 && method !== 'GET' && method !== 'HEAD') ||
+    ((status === 301 || status === 302) && method === 'POST')
+  if (!toGet) return init
+  const headers = new Headers(init.headers)
+  headers.delete('content-length')
+  headers.delete('content-type')
+  return { ...init, method: 'GET', body: undefined, headers }
+}
+
+/**
+ * `fetch` with SSRF protection. The initial URL and every redirect target are
+ * validated with {@link assertFetchableUrl}. Redirects are followed manually
+ * (`redirect: 'manual'`) so an unsafe `Location` can never be followed into the
+ * internal network; only the redirect statuses in {@link REDIRECT_STATUSES} are
+ * followed, and the method/body are transformed per {@link redirectInit}. Each
+ * intermediate redirect response body is cancelled before the next hop so it is
+ * not left dangling. When a redirect cannot or should not be followed (no
+ * `Location`, or the hop budget is exhausted) the raw redirect response is
+ * returned for the caller to handle by status. Credential headers
+ * (`Authorization`, `Cookie`) are stripped whenever a redirect crosses origin,
+ * so they never leak to a redirected host.
+ */
+export async function safeFetch(
+  url: string,
+  init: RequestInit = {},
+  options: SafeFetchOptions = {}
+): Promise<Response> {
+  const maxRedirects = options.maxRedirects ?? 3
+  let currentUrl = assertFetchableUrl(url, options).toString()
+  let currentInit = init
+
+  for (let hop = 0; ; hop++) {
+    const response = await fetch(currentUrl, {
+      ...currentInit,
+      redirect: 'manual',
+    })
+    if (!REDIRECT_STATUSES.has(response.status)) {
+      return response
+    }
+    const location = response.headers.get('location')
+    if (!location || hop >= maxRedirects) {
+      return response
+    }
+    const nextUrl = assertFetchableUrl(
+      new URL(location, currentUrl).toString(),
+      options
+    ).toString()
+    await response.body?.cancel()
+    let nextInit = redirectInit(response.status, currentInit)
+    if (new URL(nextUrl).origin !== new URL(currentUrl).origin) {
+      nextInit = stripCredentialHeaders(nextInit)
+    }
+    currentInit = nextInit
+    currentUrl = nextUrl
+  }
+}