webrtc-leak-check

Zero-dependency WebRTC IP leak detector for the browser. It reveals the local and public IP addresses your browser exposes through WebRTC — even when you're behind a VPN or proxy.

🔎 Want to just run the check without writing code? Use the hosted, no-signup version at whatismytools.com/vpn-leak — part of a free suite of 15 browser/network diagnostic tools.

Why WebRTC leaks matter

WebRTC needs to know your IP addresses to establish peer-to-peer connections. To do that, the browser queries a STUN server and collects ICE candidates — and those candidates can contain your real public IP, bypassing a VPN tunnel entirely. A web page can read them silently with no permission prompt. This is the classic "VPN IP leak."

This library does exactly that lookup, then classifies what it finds.

Install

npm install webrtc-leak-check

Usage

import { detectWebRTCLeak } from "webrtc-leak-check";

const result = await detectWebRTCLeak();

console.log(result);
// {
//   publicIPs:      ["203.0.113.42"],       // from srflx candidates — the leak
//   localIPs:       ["192.168.1.20"],       // from host candidates
//   mdnsHostnames:  ["a1b2c3d4-....local"], // browser-masked local IPs
//   publicIPv6:     [],                     // public IPv6 subset of publicIPs
//   candidates:     [ /* every parsed ICE candidate, with type */ ],
//   leak:           true
// }

if (result.leak) {
  console.warn("⚠️ WebRTC exposed a public IP:", result.publicIPs);
}

How the leak is determined

WebRTC produces ICE candidates of different types. This library parses each candidate by field position (per RFC 8445) and classifies it:

| Candidate type | What its address means | |----------------|------------------------| | host | Your local/private IP (or an *.local mDNS mask) | | srflx (server-reflexive) | Your public IP as seen from outside — the real leak | | prflx (peer-reflexive) | Also a public-facing address | | relay | The TURN server's address — not you; excluded from publicIPs |

Comparing publicIPs against your expected VPN exit IP is how you tell whether your real address is leaking through the tunnel.

Options

await detectWebRTCLeak({
  stunServers: ["stun:stun.cloudflare.com:3478"], // override STUN servers
  iceServers: [{ urls: "turn:...", username: "u", credential: "p" }], // optional TURN
  timeoutMs: 5000,                                 // gathering timeout
});

By default it queries multiple STUN servers across providers (Cloudflare, Google, Twilio) rather than relying on any single vendor — more servers means more reliable candidate gathering.

API

detectWebRTCLeak(options?): Promise<WebRTCLeakResult>

| Field | Type | Description | |-------|------|-------------| | publicIPs | string[] | Routable public IPv4/IPv6 exposed (srflx/prflx/public host) — the leak risk. | | localIPs | string[] | Private/local addresses (RFC1918, link-local, loopback, ULA). | | mdnsHostnames | string[] | *.local mDNS hostnames modern browsers use to mask local IPs. | | publicIPv6 | string[] | Public IPv6 addresses exposed (subset of publicIPs). | | candidates | ParsedCandidate[] | Every parsed ICE candidate (address, type, kind, isPrivate, …). | | leak | boolean | true if any public IP was exposed. |

options.stunServers?: string[] — STUN servers (defaults to DEFAULT_STUN_SERVERS). options.iceServers?: RTCIceServer[] — extra ICE servers, e.g. TURN with credentials. options.timeoutMs?: number — abort gathering after N ms (default 5000).

The pure helpers parseIceCandidate(str) and classifyAddress(addr) are also exported (and unit-tested) if you want to parse candidates yourself.

Accuracy, scope & limitations

Be clear-eyed about what a WebRTC leak check can and cannot do:

• Browser-only. Requires RTCPeerConnection; throws in Node/SSR. Guard with typeof window !== "undefined".
• STUN reveals the public IP, that's the point. A srflx candidate is your address as seen by the STUN server. To judge a VPN leak, compare publicIPs to your expected VPN exit IP — a match to your real ISP IP is the leak.
• mDNS masking. Recent Chrome/Firefox replace local IPs with *.local hostnames, so localIPs may be empty while mdnsHostnames is populated. Expected — it's a privacy improvement, and this library reports it distinctly.
• IPv6 & compressed forms are parsed and classified (link-local fe80::/10, ULA fc00::/7, loopback, IPv4-mapped).
• No public IP ≠ guaranteed safe. A browser/VPN combo that blocks WebRTC entirely reports no leak, but absence of evidence isn't proof.
• Scope: this is a focused STUN-based detector, not a full network-security audit. It does not perform TURN relay allocation on its own (pass your own TURN server via iceServers if you need relay candidates). For DNS leaks, IPv6 leaks and fingerprinting, use the hosted suite.

Tests

npm test   # builds, then runs the node:test suite (candidate parsing + classification)

Demo

Open demo/index.html in a browser (after npm run build) to see a live readout.

License

MIT © CodeWithEhtisham. Built alongside whatismytools.com.