guardian-risk-vpn 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guardian Contributors
+
+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,49 @@
+# guardian-risk-vpn
+
+> **Requires:** [`guardian-risk`](https://www.npmjs.com/package/guardian-risk) (core)
+
+```bash
+npm install guardian-risk guardian-risk-vpn
+```
+
+> **Stub package** — API may change before `1.0.0`.
+
+VPN, proxy, and Tor detection for [guardian-risk](https://www.npmjs.com/package/guardian-risk). Resolves client IP and adds network risk signals.
+
+## Planned signals
+
+| Signal | Description |
+|--------|-------------|
+| `vpn` | VPN exit node detected |
+| `proxy` | Public proxy detected |
+| `tor` | Tor exit node detected |
+| `country` | ISO country code from IP |
+| `asn` | Autonomous system number |
+
+## Usage (stub)
+
+```typescript
+import { Guardian } from 'guardian-risk';
+import { vpnPlugin, checkIp } from 'guardian-risk-vpn';
+
+const guardian = new Guardian().use(
+  vpnPlugin({ provider: 'maxmind', vpnScore: 20, registerDefaultRules: true }),
+);
+
+await checkIp('203.0.113.10', guardian);
+const report = guardian.analyze();
+```
+
+## Default rules (optional)
+
+When `registerDefaultRules: true`, the plugin registers:
+
+| Rule | Condition | Default score |
+|------|-----------|---------------|
+| VpnDetected | `vpn === true` | `vpnScore` (20) |
+| ProxyDetected | `proxy === true` | `vpnScore` (20) |
+| TorDetected | `tor === true` | `vpnScore + 10` (30) |
+
+## Status
+
+Not yet published. Implementation in progress.

package/dist/index.cjs

@@ -0,0 +1,44 @@
+'use strict';
+
+// src/index.ts
+function vpnPlugin(options = {}) {
+  const {
+    provider = "maxmind",
+    vpnScore = 20,
+    registerDefaultRules = true
+  } = options;
+  return {
+    name: "guardian-risk-vpn",
+    install(guardian) {
+      if (!registerDefaultRules) {
+        return;
+      }
+      guardian.rule({
+        name: "VpnDetected",
+        reason: "Connection appears to use a VPN",
+        when: (s) => s.vpn === true,
+        score: vpnScore
+      });
+      guardian.rule({
+        name: "ProxyDetected",
+        reason: "Connection appears to use a proxy",
+        when: (s) => s.proxy === true,
+        score: vpnScore
+      });
+      guardian.rule({
+        name: "TorDetected",
+        reason: "Connection appears to use Tor",
+        when: (s) => s.tor === true,
+        score: vpnScore + 10
+      });
+    }
+  };
+}
+async function checkIp(_ip, guardian) {
+  return guardian.signal("signalSource", "vpn").signal("vpn", false).signal("proxy", false).signal("tor", false).signal("country", "unknown");
+}
+
+exports.checkIp = checkIp;
+exports.vpnPlugin = vpnPlugin;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;AAqBO,SAAS,SAAA,CAAU,OAAA,GAA4B,EAAC,EAAW;AAChE,EAAA,MAAM;AAAA,IACJ,QAAA,GAAW,SAAA;AAAA,IACX,QAAA,GAAW,EAAA;AAAA,IACX,oBAAA,GAAuB;AAAA,GACzB,GAAI,OAAA;AAEJ,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,mBAAA;AAAA,IACN,QAAQ,QAAA,EAAU;AAGhB,MAAA,IAAI,CAAC,oBAAA,EAAsB;AACzB,QAAA;AAAA,MACF;AAEA,MAAA,QAAA,CAAS,IAAA,CAAK;AAAA,QACZ,IAAA,EAAM,aAAA;AAAA,QACN,MAAA,EAAQ,iCAAA;AAAA,QACR,IAAA,EAAM,CAAC,CAAA,KAAM,CAAA,CAAE,GAAA,KAAQ,IAAA;AAAA,QACvB,KAAA,EAAO;AAAA,OACR,CAAA;AAED,MAAA,QAAA,CAAS,IAAA,CAAK;AAAA,QACZ,IAAA,EAAM,eAAA;AAAA,QACN,MAAA,EAAQ,mCAAA;AAAA,QACR,IAAA,EAAM,CAAC,CAAA,KAAM,CAAA,CAAE,KAAA,KAAU,IAAA;AAAA,QACzB,KAAA,EAAO;AAAA,OACR,CAAA;AAED,MAAA,QAAA,CAAS,IAAA,CAAK;AAAA,QACZ,IAAA,EAAM,aAAA;AAAA,QACN,MAAA,EAAQ,+BAAA;AAAA,QACR,IAAA,EAAM,CAAC,CAAA,KAAM,CAAA,CAAE,GAAA,KAAQ,IAAA;AAAA,QACvB,OAAO,QAAA,GAAW;AAAA,OACnB,CAAA;AAAA,IACH;AAAA,GACF;AACF;AAKA,eAAsB,OAAA,CACpB,KACA,QAAA,EAC2C;AAC3C,EAAA,OAAO,SACJ,MAAA,CAAO,cAAA,EAAgB,KAAK,CAAA,CAC5B,MAAA,CAAO,OAAO,KAAK,CAAA,CACnB,OAAO,OAAA,EAAS,KAAK,EACrB,MAAA,CAAO,KAAA,EAAO,KAAK,CAAA,CACnB,MAAA,CAAO,WAAW,SAAS,CAAA;AAChC","file":"index.cjs","sourcesContent":["import type { Plugin } from 'guardian-risk';\n\n/** IP intelligence provider (stub). */\nexport type VpnProvider = 'maxmind' | 'ipinfo' | 'custom';\n\n/** Options for the VPN plugin (stub). */\nexport interface VpnPluginOptions {\n  /** Provider used to classify IP addresses. */\n  readonly provider?: VpnProvider;\n  /** Default risk score added when VPN rules are registered by the plugin. */\n  readonly vpnScore?: number;\n  /** Register default VPN/proxy/Tor rules on install. */\n  readonly registerDefaultRules?: boolean;\n}\n\n/**\n * VPN / proxy detection plugin for guardian-risk.\n *\n * @stub Future versions will resolve client IP via MaxMind, IPinfo, or a custom\n * provider and add signals such as `vpn`, `proxy`, `tor`, and `country`.\n */\nexport function vpnPlugin(options: VpnPluginOptions = {}): Plugin {\n  const {\n    provider = 'maxmind',\n    vpnScore = 20,\n    registerDefaultRules = true,\n  } = options;\n\n  return {\n    name: 'guardian-risk-vpn',\n    install(guardian) {\n      void provider;\n\n      if (!registerDefaultRules) {\n        return;\n      }\n\n      guardian.rule({\n        name: 'VpnDetected',\n        reason: 'Connection appears to use a VPN',\n        when: (s) => s.vpn === true,\n        score: vpnScore,\n      });\n\n      guardian.rule({\n        name: 'ProxyDetected',\n        reason: 'Connection appears to use a proxy',\n        when: (s) => s.proxy === true,\n        score: vpnScore,\n      });\n\n      guardian.rule({\n        name: 'TorDetected',\n        reason: 'Connection appears to use Tor',\n        when: (s) => s.tor === true,\n        score: vpnScore + 10,\n      });\n    },\n  };\n}\n\n/**\n * @stub Future helper to resolve an IP and add VPN-related signals.\n */\nexport async function checkIp(\n  _ip: string,\n  guardian: import('guardian-risk').Guardian,\n): Promise<import('guardian-risk').Guardian> {\n  return guardian\n    .signal('signalSource', 'vpn')\n    .signal('vpn', false)\n    .signal('proxy', false)\n    .signal('tor', false)\n    .signal('country', 'unknown');\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,27 @@
+import * as guardian_risk from 'guardian-risk';
+import { Plugin } from 'guardian-risk';
+
+/** IP intelligence provider (stub). */
+type VpnProvider = 'maxmind' | 'ipinfo' | 'custom';
+/** Options for the VPN plugin (stub). */
+interface VpnPluginOptions {
+    /** Provider used to classify IP addresses. */
+    readonly provider?: VpnProvider;
+    /** Default risk score added when VPN rules are registered by the plugin. */
+    readonly vpnScore?: number;
+    /** Register default VPN/proxy/Tor rules on install. */
+    readonly registerDefaultRules?: boolean;
+}
+/**
+ * VPN / proxy detection plugin for guardian-risk.
+ *
+ * @stub Future versions will resolve client IP via MaxMind, IPinfo, or a custom
+ * provider and add signals such as `vpn`, `proxy`, `tor`, and `country`.
+ */
+declare function vpnPlugin(options?: VpnPluginOptions): Plugin;
+/**
+ * @stub Future helper to resolve an IP and add VPN-related signals.
+ */
+declare function checkIp(_ip: string, guardian: guardian_risk.Guardian): Promise<guardian_risk.Guardian>;
+
+export { type VpnPluginOptions, type VpnProvider, checkIp, vpnPlugin };

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import * as guardian_risk from 'guardian-risk';
+import { Plugin } from 'guardian-risk';
+
+/** IP intelligence provider (stub). */
+type VpnProvider = 'maxmind' | 'ipinfo' | 'custom';
+/** Options for the VPN plugin (stub). */
+interface VpnPluginOptions {
+    /** Provider used to classify IP addresses. */
+    readonly provider?: VpnProvider;
+    /** Default risk score added when VPN rules are registered by the plugin. */
+    readonly vpnScore?: number;
+    /** Register default VPN/proxy/Tor rules on install. */
+    readonly registerDefaultRules?: boolean;
+}
+/**
+ * VPN / proxy detection plugin for guardian-risk.
+ *
+ * @stub Future versions will resolve client IP via MaxMind, IPinfo, or a custom
+ * provider and add signals such as `vpn`, `proxy`, `tor`, and `country`.
+ */
+declare function vpnPlugin(options?: VpnPluginOptions): Plugin;
+/**
+ * @stub Future helper to resolve an IP and add VPN-related signals.
+ */
+declare function checkIp(_ip: string, guardian: guardian_risk.Guardian): Promise<guardian_risk.Guardian>;
+
+export { type VpnPluginOptions, type VpnProvider, checkIp, vpnPlugin };

package/dist/index.js

@@ -0,0 +1,41 @@
+// src/index.ts
+function vpnPlugin(options = {}) {
+  const {
+    provider = "maxmind",
+    vpnScore = 20,
+    registerDefaultRules = true
+  } = options;
+  return {
+    name: "guardian-risk-vpn",
+    install(guardian) {
+      if (!registerDefaultRules) {
+        return;
+      }
+      guardian.rule({
+        name: "VpnDetected",
+        reason: "Connection appears to use a VPN",
+        when: (s) => s.vpn === true,
+        score: vpnScore
+      });
+      guardian.rule({
+        name: "ProxyDetected",
+        reason: "Connection appears to use a proxy",
+        when: (s) => s.proxy === true,
+        score: vpnScore
+      });
+      guardian.rule({
+        name: "TorDetected",
+        reason: "Connection appears to use Tor",
+        when: (s) => s.tor === true,
+        score: vpnScore + 10
+      });
+    }
+  };
+}
+async function checkIp(_ip, guardian) {
+  return guardian.signal("signalSource", "vpn").signal("vpn", false).signal("proxy", false).signal("tor", false).signal("country", "unknown");
+}
+
+export { checkIp, vpnPlugin };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";AAqBO,SAAS,SAAA,CAAU,OAAA,GAA4B,EAAC,EAAW;AAChE,EAAA,MAAM;AAAA,IACJ,QAAA,GAAW,SAAA;AAAA,IACX,QAAA,GAAW,EAAA;AAAA,IACX,oBAAA,GAAuB;AAAA,GACzB,GAAI,OAAA;AAEJ,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,mBAAA;AAAA,IACN,QAAQ,QAAA,EAAU;AAGhB,MAAA,IAAI,CAAC,oBAAA,EAAsB;AACzB,QAAA;AAAA,MACF;AAEA,MAAA,QAAA,CAAS,IAAA,CAAK;AAAA,QACZ,IAAA,EAAM,aAAA;AAAA,QACN,MAAA,EAAQ,iCAAA;AAAA,QACR,IAAA,EAAM,CAAC,CAAA,KAAM,CAAA,CAAE,GAAA,KAAQ,IAAA;AAAA,QACvB,KAAA,EAAO;AAAA,OACR,CAAA;AAED,MAAA,QAAA,CAAS,IAAA,CAAK;AAAA,QACZ,IAAA,EAAM,eAAA;AAAA,QACN,MAAA,EAAQ,mCAAA;AAAA,QACR,IAAA,EAAM,CAAC,CAAA,KAAM,CAAA,CAAE,KAAA,KAAU,IAAA;AAAA,QACzB,KAAA,EAAO;AAAA,OACR,CAAA;AAED,MAAA,QAAA,CAAS,IAAA,CAAK;AAAA,QACZ,IAAA,EAAM,aAAA;AAAA,QACN,MAAA,EAAQ,+BAAA;AAAA,QACR,IAAA,EAAM,CAAC,CAAA,KAAM,CAAA,CAAE,GAAA,KAAQ,IAAA;AAAA,QACvB,OAAO,QAAA,GAAW;AAAA,OACnB,CAAA;AAAA,IACH;AAAA,GACF;AACF;AAKA,eAAsB,OAAA,CACpB,KACA,QAAA,EAC2C;AAC3C,EAAA,OAAO,SACJ,MAAA,CAAO,cAAA,EAAgB,KAAK,CAAA,CAC5B,MAAA,CAAO,OAAO,KAAK,CAAA,CACnB,OAAO,OAAA,EAAS,KAAK,EACrB,MAAA,CAAO,KAAA,EAAO,KAAK,CAAA,CACnB,MAAA,CAAO,WAAW,SAAS,CAAA;AAChC","file":"index.js","sourcesContent":["import type { Plugin } from 'guardian-risk';\n\n/** IP intelligence provider (stub). */\nexport type VpnProvider = 'maxmind' | 'ipinfo' | 'custom';\n\n/** Options for the VPN plugin (stub). */\nexport interface VpnPluginOptions {\n  /** Provider used to classify IP addresses. */\n  readonly provider?: VpnProvider;\n  /** Default risk score added when VPN rules are registered by the plugin. */\n  readonly vpnScore?: number;\n  /** Register default VPN/proxy/Tor rules on install. */\n  readonly registerDefaultRules?: boolean;\n}\n\n/**\n * VPN / proxy detection plugin for guardian-risk.\n *\n * @stub Future versions will resolve client IP via MaxMind, IPinfo, or a custom\n * provider and add signals such as `vpn`, `proxy`, `tor`, and `country`.\n */\nexport function vpnPlugin(options: VpnPluginOptions = {}): Plugin {\n  const {\n    provider = 'maxmind',\n    vpnScore = 20,\n    registerDefaultRules = true,\n  } = options;\n\n  return {\n    name: 'guardian-risk-vpn',\n    install(guardian) {\n      void provider;\n\n      if (!registerDefaultRules) {\n        return;\n      }\n\n      guardian.rule({\n        name: 'VpnDetected',\n        reason: 'Connection appears to use a VPN',\n        when: (s) => s.vpn === true,\n        score: vpnScore,\n      });\n\n      guardian.rule({\n        name: 'ProxyDetected',\n        reason: 'Connection appears to use a proxy',\n        when: (s) => s.proxy === true,\n        score: vpnScore,\n      });\n\n      guardian.rule({\n        name: 'TorDetected',\n        reason: 'Connection appears to use Tor',\n        when: (s) => s.tor === true,\n        score: vpnScore + 10,\n      });\n    },\n  };\n}\n\n/**\n * @stub Future helper to resolve an IP and add VPN-related signals.\n */\nexport async function checkIp(\n  _ip: string,\n  guardian: import('guardian-risk').Guardian,\n): Promise<import('guardian-risk').Guardian> {\n  return guardian\n    .signal('signalSource', 'vpn')\n    .signal('vpn', false)\n    .signal('proxy', false)\n    .signal('tor', false)\n    .signal('country', 'unknown');\n}\n"]}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "guardian-risk-vpn",
+  "version": "0.1.0",
+  "description": "VPN and proxy detection plugin for guardian-risk — adds network risk signals",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "guardian-risk",
+    "guardian-risk-vpn",
+    "vpn",
+    "proxy",
+    "tor",
+    "ip",
+    "fraud",
+    "risk"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/himanshu6306singh/guardian-risk.git",
+    "directory": "packages/vpn"
+  },
+  "homepage": "https://github.com/himanshu6306singh/guardian-risk/tree/main/packages/vpn#readme",
+  "bugs": {
+    "url": "https://github.com/himanshu6306singh/guardian-risk/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "guardian-risk": "^0.2.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "guardian-risk": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}