Skip to content
VPNDetection

Protect a web app

Add VPNDetection middleware to your web framework so every request carries an answer, then block VPN and Tor traffic on the routes where it matters.

The framework packages look up each visitor before your handler runs and attach the answer to the request. This page adds the middleware to your app, makes sure it sees the visitor's real address, and refuses VPN and Tor traffic on the routes where that matters.

By default the middleware blocks nothing. Your code decides what a VPN or Tor visitor means on each route, or you give the middleware a condition and it refuses matching requests with 403. Many sites do both: they block on a few sensitive routes and record the answer everywhere else.

How the middleware works

For each request, the middleware finds the visitor's address, looks it up, and attaches the answer before your handler runs. A few rules keep it fast and safe:

  • Answers are cached for an hour, so a returning visitor costs no lookup. Private addresses, such as 127.0.0.1 on your own machine, are answered locally and never leave your server.
  • A failed lookup lets the request through. The error is recorded beside the answer, so an outage on our side never takes your site down. Each package has an option to fail closed instead.
  • A block condition refuses with 403 before your handler runs. Without one, nothing is refused.

Before you begin

  • A web app built on one of the supported frameworks. This page shows Express, Next.js, Django and Laravel; Framework SDKs lists all fifteen, including Rails, FastAPI, Spring Boot and Go's net/http.
  • An API key is optional. Without one, the middleware uses the free plan, which answers is_vpn, is_tor and is_relay.

1. Install and add the middleware

Install the package for your framework and register it. Each example then reads the answer in a handler:

Express
// npm install vpndetection-express
import express from 'express';
import { vpndetection } from 'vpndetection-express';

const app = express();

app.set('trust proxy', 'loopback'); // the proxy in front of your app
app.use(vpndetection({ apiKey: process.env.VPNDETECTION_API_KEY }));

app.get('/', (req, res) => {
    const { result } = req.vpndetection;
    res.send(result?.isVpn ? 'Hello, VPN user' : 'Hello');
});

In Next.js, read the answer in a page or route handler with readLookup(await headers()); the Next.js page has a complete example.

2. Make sure the middleware sees the visitor's address

If your app runs behind nginx, a load balancer or a CDN, the middleware sees your proxy's address unless the framework knows which proxies to trust. Then every visitor looks like your own server, and nothing is detected. Client IP addresses shows the setting for each framework.

3. Write a block condition

A block condition is written in the shape of an answer. This one refuses VPN and Tor traffic with 403, using fields the free plan includes:

Express
app.use(vpndetection({
    apiKey: process.env.VPNDETECTION_API_KEY,
    blockCondition: [{ isVpn: true }, { isTor: true }],
}));

A list matches when any of its conditions match. A condition can also reach into the detail objects: on a paid plan, { isVpn: true, vpn: { confidence: ['high', 'medium'] } } refuses only the VPN addresses classified with high or medium confidence. A condition that names a field your plan doesn't include never matches, and the middleware logs a warning once.

4. Choose the routes to protect

Apply a block condition to the routes where a VPN or Tor visitor is a risk, such as sign-up, login and checkout, and record the answer everywhere else. In Express, mount the middleware on those paths:

js
app.use(['/signup', '/login', '/checkout'], vpndetection({
    apiKey: process.env.VPNDETECTION_API_KEY,
    blockCondition: [{ isVpn: true }, { isTor: true }],
}));

To show your own page instead of a bare 403, pass onBlocked:

js
app.use('/signup', vpndetection({
    apiKey: process.env.VPNDETECTION_API_KEY,
    blockCondition: [{ isVpn: true }, { isTor: true }],
    onBlocked: (req, res) => res.status(403).render('no-vpn'),
}));

Every package takes a block condition and can fail closed, and most can also skip requests or replace the refusal. Each package's page under Framework SDKs lists its options in that framework's style.

5. Test it

Deploy your app to a test environment and visit it while connected to a VPN. Your handler should see isVpn as true, and a blocked route should answer 403. On your own machine, every request comes from a private address, which the middleware answers locally without a lookup. If every request shows the same public address, revisit step 2.

Next steps

Your app now knows which visitors come through a VPN or Tor, and, on a paid plan, which come through a proxy. To decide what to do with sign-ups, read Screen VPN and proxy sign-ups. Before you launch, review the go-live checklist.