@subashgautam/vpn-guard

Block visitors who use a VPN, proxy, or Tor. Works in two layers:

• Server side (backend) — the reliable layer. Runs on your server, can't be bypassed.
• Browser side (frontend) — a backup layer, plus a timezone-mismatch check that catches foreign VPNs the IP database misses.

⚠️ Frontend checks alone can be bypassed. For real enforcement, use the server side.

Install

npm install @subashgautam/vpn-guard

Server side (Express) — the strong block

import express from "express";
import { vpnBlock } from "@subashgautam/vpn-guard";

const app = express();

// Block VPN/proxy/Tor visitors before any route runs
app.use(vpnBlock());

app.get("/", (req, res) => res.send("Welcome — no VPN detected!"));
app.listen(3000);

Manual check (any backend)

import { checkIp, getClientIp } from "@subashgautam/vpn-guard";

const ip = getClientIp(req);            // read the real client IP
const verdict = await checkIp(ip);      // { flagged, reason, data }
if (verdict.flagged) {
  // refuse to serve — reason is "vpn" | "proxy" | "tor" | "datacenter" | "risk_score"
}

Browser side (frontend) — backup layer

import { vpnGuard } from "@subashgautam/vpn-guard/browser";

vpnGuard();                       // hides the page, shows a block screen if VPN
// or stricter:
vpnGuard({ blockOnError: true });

Options

| Option | Default | Meaning | |---|---|---| | block.vpn | true | Block detected VPNs | | block.proxy | true | Block proxies | | block.tor | true | Block Tor | | block.datacenter | true | Block datacenter/hosting IPs (most commercial VPNs) | | riskScoreBlock | 75 | Block when risk score ≥ this (0–100) | | blockOnError | false | If detection fails: false = allow, true = block | | blockOnTzMismatch | true | (browser only) block when IP timezone ≠ device timezone |

How detection works

Uses the free, keyless ipquery.io service. For higher accuracy (Netflix-level), point apiBase / apiUrl at a paid provider (IPQualityScore, proxycheck.io, MaxMind, IP2Proxy) and adapt the response mapping.

License

MIT