Skip to Content

Link preview security

Understand linkpeek's redirect validation, private-address blocking, credential handling, and DNS-rebinding limits.

A public link preview endpoint fetches whatever URL a user sends it. Without checks, someone can point it at http://169.254.169.254/ and read your cloud credentials. That attack is server-side request forgery (SSRF). linkpeek blocks the direct routes, but your runtime and network stay part of the security boundary.

What is blocked by default

  • Non-HTTP(S) protocols and URLs with embedded credentials

  • localhost and literal private, link-local, multicast, documentation, and other non-global IP ranges, in any IPv4 spelling the URL parser accepts (127.1, 0x7f000001, 2130706433)

  • Internal names: localhost. and *.localhost, *.local, *.internal (including metadata.google.internal), *.localdomain, *.intranet, *.private, *.corp, *.home, *.lan, *.home.arpa, and single-label names such as metadata

  • IPv4 embedded through mapped IPv6, NAT64, and 6to4 forms

  • Common credential-bearing custom request headers

  • Extracted media, canonical, and oEmbed URLs outside HTTP(S)

Redirect validation

Platform fetch runs with redirect: "manual". Each Location target is resolved and validated before another request starts. Custom headers are dropped when a redirect crosses origins. A meta-refresh hop counts against the same maxRedirects budget and timeout deadline. If a custom fetch follows redirects itself, the final response.url it reports is still validated, but the hops in between are not, so honor redirect: "manual".

Cookies and credentials

Never attach user cookies, authorization headers, cloud tokens or internal service credentials to arbitrary preview URLs. linkpeek rejects the common secret-bearing headers, but the worker that runs previews shouldn't have access to internal credentials in the first place.

DNS resolution and rebinding

The runtime resolves hostnames, not linkpeek, and linkpeek does not pin addresses. How well DNS rebinding is covered depends on the runtime and the network path.

resolveHost adds an opt-in DNS check without a dependency. linkpeek calls it with the hostname of the first request and of every redirect hop, skipping IP literals. If any returned address is private, the hop throws PRIVATE_NETWORK_BLOCKED; resolver errors and empty answers throw FETCH_FAILED. Edge runtimes without a DNS API can omit it.

import { lookup } from "node:dns/promises";
import { LinkpeekError, preview } from "linkpeek";

try {
  await preview(url, {
    resolveHost: async (hostname) =>
      (await lookup(hostname, { all: true })).map((entry) => entry.address),
  });
} catch (error) {
  if (error instanceof LinkpeekError && error.code === "PRIVATE_NETWORK_BLOCKED") {
    // The name points at a private address: refuse the URL.
  } else if (error instanceof LinkpeekError && error.code === "FETCH_FAILED") {
    // DNS lookup failed or returned nothing (error.cause holds the resolver error),
    // or the site could not be reached. Show a hostname-only card and retry later.
  } else {
    throw error;
  }
}

Both are LinkpeekErrors with a stable code: a resolver error is wrapped, not rethrown raw. A lookup that outlasts the deadline reports TIMEOUT, and your own signal's abort reason propagates unchanged.

This catches public names that point at internal addresses. It does not close rebinding completely: platform fetch resolves the name again before connecting, and a hostile DNS server can answer differently the second time.

For hostile public input, add outbound firewall or platform egress policy so the worker cannot reach metadata services or internal networks even if DNS changes between validation and connection.

Production checklist

  • Keep allowPrivateIPs false.

  • On Node.js, pass a resolveHost lookup.

  • Rate-limit public endpoints and cap concurrency.

  • Cache successful results; do not cache target errors.

  • Render all returned strings and URLs as untrusted input.

  • Require custom fetch implementations to honor manual redirects and abort signals.

  • Use network-level egress policy for high-risk deployments.