vpndetection-express 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mslm Dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# [<img src="https://s3.vpndetection.io/vpndetection-public/brand/mark.svg" alt="VPNDetection" width="24"/>](https://vpndetection.io/) VPNDetection Express Middleware
+
+[![npm](https://img.shields.io/npm/v/vpndetection-express.svg)](https://www.npmjs.com/package/vpndetection-express)
+[![license](https://img.shields.io/npm/l/vpndetection-express.svg)](LICENSE)
+
+The official [Express](https://expressjs.com) middleware for the [VPNDetection](https://vpndetection.io) API.
+
+It classifies the visitor behind each request — VPN, residential proxy, Tor, hosting, CDN, relay — and hands the answer to your handlers. Blocking is opt-in.
+
+## Getting Started
+
+```bash
+npm install vpndetection-express
+```
+
+Requires Node.js 22 or newer and Express 4.18 or newer. TypeScript types are included.
+
+You need an API key. Create one in the [console](https://app.vpndetection.io); the free tier's allowance is counted per source address, and a server is a single source address, so a key is what makes this usable in production rather than optional.
+
+```js
+import express from 'express';
+import { vpndetection } from 'vpndetection-express';
+
+const app = express();
+
+app.set('trust proxy', true);  // see "Where the client address comes from" below
+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');
+});
+```
+
+By default nothing is blocked. Every request gets a `req.vpndetection` and your own code decides what that means — which is usually what you want, because whether a VPN visitor is a problem depends entirely on what they are doing.
+
+## Blocking
+
+Pass a `blockCondition` and a matching request is answered with `403` and never reaches your handlers.
+
+```js
+app.use(vpndetection({
+    apiKey: process.env.VPNDETECTION_API_KEY,
+    blockCondition: { isVpn: true },
+}));
+```
+
+A condition is written in the shape of a result, and only the members you name are considered. That lets it reach the evidence, not just the flags:
+
+```js
+blockCondition: { isVpn: true, vpn: { provider: 'nordvpn' } }         // one provider
+blockCondition: { isResproxy: true, resproxy: { hits: { gte: 5 } } }  // a numeric threshold
+blockCondition: { vpn: { confidence: ['high', 'medium'] } }           // any of these
+blockCondition: [{ isTor: true }, { isResproxy: true }]               // a list is OR
+```
+
+Values are matched by equality, strings without regard to case. An array means any-of. `{ gte, gt, lte, lt }` compares numbers, and every bound you give must hold, so two of them are a range. Members you set to `false` or `null` are ignored, so a condition states the signals you act on; one that constrains nothing would match every request, and is refused when the middleware is created rather than silently blocking all your traffic.
+
+Replace the refusal with `onBlocked`:
+
+```js
+app.use(vpndetection({
+    apiKey: process.env.VPNDETECTION_API_KEY,
+    blockCondition: { isVpn: true },
+    onBlocked: (req, res) => res.status(403).render('no-vpn'),
+}));
+```
+
+## Where the client address comes from
+
+This is the setting that decides whether any of the above works, and it is the one thing only you can get right.
+
+By default the middleware uses `req.ip`, which is Express's own accessor. **Express resolves `req.ip` to the socket peer unless you set `trust proxy`.** So if your app sits behind nginx, a load balancer, or a CDN and you have not set it, every visitor arrives wearing your proxy's address — which is a datacenter address, so a hosting rule would block all of them.
+
+If you are behind a proxy you control, setting Express's own option is the right fix and everything else here follows from it:
+
+```js
+app.set('trust proxy', true);
+```
+
+For an edge that writes the address into its own header, name the header:
+
+```js
+import { headerIpSelector } from 'vpndetection-express';
+
+app.use(vpndetection({
+    apiKey: process.env.VPNDETECTION_API_KEY,
+    ipSelector: headerIpSelector('CF-Connecting-IP'),  // or True-Client-IP, or your own
+}));
+```
+
+`xffIpSelector()` reads `X-Forwarded-For` directly. Be aware that the left-most entry is whatever the caller sent, because proxies append to that header — it is only trustworthy when an edge you control overwrites it. If you know how many proxies sit in front, count from the right instead: `xffIpSelector({ depth: 1 })` is the address your nearest proxy saw.
+
+Anything else, pass your own function. It receives the Express request and returns an address:
+
+```js
+ipSelector: (req) => req.headers['x-real-ip'] ?? req.ip,
+```
+
+If the address resolves to a private one, the middleware says so once on `console.warn`. That is expected on localhost and is the signal to fix your configuration anywhere else.
+
+## When a lookup fails
+
+The request is let through, and the reason is recorded on `req.vpndetection.error`. Our outage should not become yours, so a network failure, an exhausted quota or a rejected key all fail open.
+
+```js
+app.get('/', (req, res) => {
+    const { result, error } = req.vpndetection;
+    if (error) {
+        req.log.warn({ kind: error.kind }, 'vpndetection unavailable');
+    }
+    res.send(result?.isVpn ? 'Hello, VPN user' : 'Hello');
+});
+```
+
+Pass `failClosed: true` to block instead. Private addresses are answered locally and never fail, so this will not lock you out in development.
+
+## Cost and latency
+
+Answers are cached per middleware for an hour, so a returning visitor costs nothing, and private addresses never leave the process. A cache miss is one request to our API, bounded at 2500 ms by default and not retried — on a request path, failing open quickly beats holding a visitor while we try again. Both are adjustable, along with the cache itself:
+
+```js
+vpndetection({ apiKey: KEY, timeoutMs: 1000, retries: 1, cache: { max: 50000, ttlMs: 600000 } })
+```
+
+Mount it on the routes that matter rather than the whole app, or skip what you do not care about:
+
+```js
+app.use(vpndetection({ apiKey: KEY, skip: (req) => req.path.startsWith('/static') }));
+```
+
+If you already hold a `VPNDetection` client, pass it as `client` and the middleware will share it rather than building a second cache.
+
+Beyond a few million distinct visitors a day, stop calling the API per request: [download the dataset](https://vpndetection.io/databases) and look addresses up locally instead.
+
+## Absent is not false
+
+Only `ip` and `isVpn` come back on every plan. A field your plan does not include is `undefined`, which means "not in your plan" rather than "checked, and no".
+
+```js
+req.vpndetection.result.isHosting ?? false   // when you only want the flag
+```
+
+A `blockCondition` naming a member your plan does not serve can never match, so the middleware warns once instead of failing silently. Set `onMissingField: 'throw'` to make it an error.
+
+## Other Libraries
+
+There are official VPNDetection client libraries available for many languages including PHP, Python, Go, Java, Ruby, and many popular frameworks such as Django, Rails, and Laravel. See our GitHub at https://github.com/vpndetection-io for more.
+
+## About VPNDetection
+
+VPN Detection API: Accurate anonymity detection identifying VPNs, residential proxies, hosting servers, Tor nodes, CDNs, relays and more.
+
+[<img src="https://s3.vpndetection.io/vpndetection-public/brand/mark.svg" alt="VPNDetection" width="96"/>](https://vpndetection.io/)
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import type { IpSelector, Lookup, MiddlewareOptions } from 'vpndetection/middleware';
+import type { Request, RequestHandler, Response } from 'express';
+export type { BlockCondition, IpSelector, Lookup, NumericBound } from 'vpndetection/middleware';
+declare global {
+    namespace Express {
+        interface Request {
+            /**
+             * What the middleware found out about this visitor. Absent when the
+             * middleware has not run for this route, or when `skip` claimed it.
+             */
+            vpndetection?: Lookup;
+        }
+    }
+}
+export interface Options extends MiddlewareOptions<Request> {
+    /**
+     * How a blocked request is answered. Defaults to `403` with a short JSON
+     * body. Whatever you pass must end the response.
+     */
+    onBlocked?: (req: Request, res: Response, lookup: Lookup) => void;
+}
+/**
+ * Classify the visitor and hang the answer off `req.vpndetection`.
+ *
+ * Without a `blockCondition` this only enriches the request and never refuses
+ * one, leaving the decision to your own handlers. With one, a matching request
+ * is answered by `onBlocked` and never reaches them.
+ *
+ * A lookup that fails - network, quota, an outage of ours - lets the request
+ * through and records why on `req.vpndetection.error`, unless you set
+ * `failClosed`.
+ */
+export declare function vpndetection(options?: Options): RequestHandler;
+/**
+ * `req.ip`, which is the socket peer unless you have set Express's `trust
+ * proxy`. Behind a load balancer without it, every visitor looks like the load
+ * balancer - so if you are behind one, set it or pick another selector.
+ */
+export declare const defaultIpSelector: IpSelector<Request>;
+/**
+ * An address from `X-Forwarded-For`.
+ *
+ * **The left-most entry is whatever the caller sent**, since proxies append, so
+ * this is only trustworthy when an edge you control overwrites the header. When
+ * you know how many proxies sit in front, count from the right instead:
+ * `xffIpSelector({ depth: 1 })` is the address your nearest proxy saw.
+ */
+export declare const xffIpSelector: (options?: {
+    depth?: number;
+}) => IpSelector<Request>;
+/**
+ * An address from a single-value header your edge writes -
+ * `headerIpSelector('CF-Connecting-IP')` behind Cloudflare,
+ * `headerIpSelector('True-Client-IP')` behind Akamai. Falls back to `req.ip`
+ * when the header is absent.
+ */
+export declare const headerIpSelector: (name: string) => IpSelector<Request>;

package/dist/index.js

@@ -0,0 +1,67 @@
+import { bindSelectors, createCore } from 'vpndetection/middleware';
+/**
+ * Classify the visitor and hang the answer off `req.vpndetection`.
+ *
+ * Without a `blockCondition` this only enriches the request and never refuses
+ * one, leaving the decision to your own handlers. With one, a matching request
+ * is answered by `onBlocked` and never reaches them.
+ *
+ * A lookup that fails - network, quota, an outage of ours - lets the request
+ * through and records why on `req.vpndetection.error`, unless you set
+ * `failClosed`.
+ */
+export function vpndetection(options = {}) {
+    const core = createCore(options, defaultIpSelector);
+    const onBlocked = options.onBlocked ?? refuse;
+    return (req, res, next) => {
+        core.evaluate(req).then((lookup) => {
+            if (lookup === undefined) {
+                next();
+                return;
+            }
+            req.vpndetection = lookup;
+            if (lookup.blocked) {
+                onBlocked(req, res, lookup);
+                return;
+            }
+            next();
+        }, next);
+    };
+}
+const view = (req) => ({
+    header: (name) => {
+        const value = req.headers[name.toLowerCase()];
+        return Array.isArray(value) ? value[0] : value;
+    },
+    frameworkIp: () => req.ip,
+});
+// Each of these is annotated rather than inferred: the inferred shape reaches
+// through `@types/express` into its own transitive types, which TypeScript
+// refuses to name in a declaration file a consumer would have to resolve.
+const selectors = bindSelectors(view);
+/**
+ * `req.ip`, which is the socket peer unless you have set Express's `trust
+ * proxy`. Behind a load balancer without it, every visitor looks like the load
+ * balancer - so if you are behind one, set it or pick another selector.
+ */
+export const defaultIpSelector = selectors.defaultIpSelector;
+/**
+ * An address from `X-Forwarded-For`.
+ *
+ * **The left-most entry is whatever the caller sent**, since proxies append, so
+ * this is only trustworthy when an edge you control overwrites the header. When
+ * you know how many proxies sit in front, count from the right instead:
+ * `xffIpSelector({ depth: 1 })` is the address your nearest proxy saw.
+ */
+export const xffIpSelector = selectors.xffIpSelector;
+/**
+ * An address from a single-value header your edge writes -
+ * `headerIpSelector('CF-Connecting-IP')` behind Cloudflare,
+ * `headerIpSelector('True-Client-IP')` behind Akamai. Falls back to `req.ip`
+ * when the header is absent.
+ */
+export const headerIpSelector = selectors.headerIpSelector;
+function refuse(_req, res) {
+    res.status(403).json({ error: 'access denied' });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AA2BpE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,UAAmB,EAAE;IAC9C,MAAM,IAAI,GAAG,UAAU,CAAU,OAAO,EAAE,iBAAiB,CAAC,CAAC;IAC7D,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC;IAC9C,OAAO,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;QACvD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;YAC/B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACvB,IAAI,EAAE,CAAC;gBACP,OAAO;YACX,CAAC;YACD,GAAG,CAAC,YAAY,GAAG,MAAM,CAAC;YAC1B,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBACjB,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;gBAC5B,OAAO;YACX,CAAC;YACD,IAAI,EAAE,CAAC;QACX,CAAC,EAAE,IAAI,CAAC,CAAC;IACb,CAAC,CAAC;AACN,CAAC;AAED,MAAM,IAAI,GAAG,CAAC,GAAY,EAAE,EAAE,CAAC,CAAC;IAC5B,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;QACrB,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;QAC9C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACnD,CAAC;IACD,WAAW,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE;CAC5B,CAAC,CAAC;AAEH,8EAA8E;AAC9E,2EAA2E;AAC3E,0EAA0E;AAC1E,MAAM,SAAS,GAAG,aAAa,CAAU,IAAI,CAAC,CAAC;AAE/C;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAwB,SAAS,CAAC,iBAAiB,CAAC;AAElF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GACpB,SAAS,CAAC,aAAa,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GACvB,SAAS,CAAC,gBAAgB,CAAC;AAEjC,SAAS,MAAM,CAAC,IAAa,EAAE,GAAa;IACxC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC,CAAC;AACrD,CAAC"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "vpndetection-express",
+  "version": "1.0.0",
+  "description": "Official Express middleware for the VPNDetection API. Detect VPNs, proxies, Tor, hosting and CDN visitors on every request.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://vpndetection.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vpndetection-io/sdk-nodejs-expressjs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vpndetection-io/sdk-nodejs-expressjs/issues"
+  },
+  "keywords": [
+    "express",
+    "express-middleware",
+    "middleware",
+    "vpn",
+    "vpn-detection",
+    "proxy-detection",
+    "tor",
+    "ip-intelligence",
+    "fraud-prevention",
+    "bot-detection",
+    "residential-proxy",
+    "hosting"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "vpndetection": "^1.8.0"
+  },
+  "peerDependencies": {
+    "express": ">=4.18"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^26.2.0",
+    "express": "^5.2.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "test": "pnpm run build && node --test test/*.test.mjs"
+  }
+}