guardian-risk-vpn 0.1.1 → 0.2.0

package/README.md

@@ -6,44 +6,52 @@
 npm install guardian-risk guardian-risk-vpn
 ```
 
-> **Stub package** — API may change before `1.0.0`.
+VPN, proxy, hosting, and Tor detection for [guardian-risk](https://www.npmjs.com/package/guardian-risk).
 
-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
+## Signals
 
 | Signal | Description |
 |--------|-------------|
 | `vpn` | VPN exit node detected |
 | `proxy` | Public proxy detected |
 | `tor` | Tor exit node detected |
-| `country` | ISO country code from IP |
+| `hosting` | Datacenter / hosting ASN |
+| `country` | ISO country code from provider |
 | `asn` | Autonomous system number |
 
-## Usage (stub)
+## Production usage
 
 ```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 }),
+import { vpnPlugin, StaticIpProvider } from 'guardian-risk-vpn';
+
+// Use your own IP intelligence — MaxMind, IPinfo, etc.
+const provider = new StaticIpProvider({
+  '203.0.113.10': { vpn: false, proxy: false, tor: false, country: 'US' },
+});
+
+const template = new Guardian().use(
+  vpnPlugin({
+    provider,
+    registerDefaultRules: true,
+    vpnScore: 20,
+  }),
 );
-
-await checkIp('203.0.113.10', guardian);
-const report = guardian.analyze();
 ```
 
-## Default rules (optional)
+For development only, `IpApiProvider` is available (HTTPS, 5s timeout) — **not recommended in production**.
+
+## Security notes
 
-When `registerDefaultRules: true`, the plugin registers:
+- **No external provider by default** — you must supply `provider` for lookups.
+- Reads **`clientIp` from guardian signals first** (set by express plugin).
+- Only **validated public IPs** are looked up; private/reserved ranges are skipped.
+- VPN signals are **hints** — use your own threat intel feed in production.
 
-| Rule | Condition | Default score |
-|------|-----------|---------------|
-| VpnDetected | `vpn === true` | `vpnScore` (20) |
-| ProxyDetected | `proxy === true` | `vpnScore` (20) |
-| TorDetected | `tor === true` | `vpnScore + 10` (30) |
+## API
 
-## Status
+- `vpnPlugin(options)` — `beforeAnalyze` hook + optional default rules
+- `checkIp(ip, guardian, options?)` — manual lookup
+- `StaticIpProvider`, `IpApiProvider` — built-in providers
 
-Not yet published. Implementation in progress.
+See [SECURITY.md](../../SECURITY.md).

package/dist/index.cjs

@@ -1,42 +1,166 @@
 'use strict';
 
+var guardianRisk = require('guardian-risk');
+
+// src/index.ts
+var DEFAULT_TIMEOUT_MS = 5e3;
+var LOOKUP_URL = "https://ip-api.com/json";
+var IpApiProvider = class {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  options;
+  async lookup(ip) {
+    const parsed = guardianRisk.parseIpAddress(ip);
+    if (!parsed || guardianRisk.isPrivateIp(parsed)) {
+      return localResult();
+    }
+    const controller = new AbortController();
+    const timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetch(
+        `${LOOKUP_URL}/${encodeURIComponent(parsed)}?fields=status,country,proxy,hosting`,
+        { signal: controller.signal }
+      );
+      if (!response.ok) {
+        throw new Error(`IP lookup failed with status ${response.status}`);
+      }
+      const data = await response.json();
+      if (data.status !== "success") {
+        return unknownResult();
+      }
+      return {
+        vpn: false,
+        proxy: data.proxy === true,
+        tor: false,
+        country: data.country ?? "unknown",
+        hosting: data.hosting === true
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+var StaticIpProvider = class {
+  constructor(results) {
+    this.results = results;
+  }
+  results;
+  async lookup(ip) {
+    const parsed = guardianRisk.parseIpAddress(ip);
+    if (!parsed) {
+      return unknownResult();
+    }
+    return this.results[parsed] ?? unknownResult();
+  }
+};
+function localResult() {
+  return { vpn: false, proxy: false, tor: false, country: "local", hosting: false };
+}
+function unknownResult() {
+  return { vpn: false, proxy: false, tor: false, country: "unknown", hosting: false };
+}
+
 // src/index.ts
+var EMPTY_PROVIDER = new StaticIpProvider({});
 function vpnPlugin(options = {}) {
   const {
-    provider = "maxmind",
+    provider = EMPTY_PROVIDER,
     vpnScore = 20,
     registerDefaultRules = true
   } = options;
   return {
     name: "guardian-risk-vpn",
     install(guardian) {
-      if (!registerDefaultRules) {
-        return;
+      if (registerDefaultRules) {
+        registerVpnRules(guardian, vpnScore);
       }
-      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
+      guardian.beforeAnalyze(async ({ data, guardian: g }) => {
+        const ip = resolveIpForLookup(g, data);
+        if (!ip) {
+          return;
+        }
+        await applyIpSignals(ip, g, provider);
       });
     }
   };
 }
-async function checkIp(_ip, guardian) {
-  return guardian.signal("signalSource", "vpn").signal("vpn", false).signal("proxy", false).signal("tor", false).signal("country", "unknown");
+async function checkIp(ip, guardian, provider = EMPTY_PROVIDER) {
+  const parsed = guardianRisk.parseIpAddress(ip);
+  if (!parsed) {
+    throw new TypeError("Invalid IP address");
+  }
+  await applyIpSignals(parsed, guardian, provider);
+  return guardian;
+}
+function registerVpnRules(guardian, vpnScore) {
+  guardian.rule({
+    name: "VpnDetected",
+    reason: "Connection appears to use a VPN or datacenter",
+    when: (s) => s.vpn === true || s.hosting === true,
+    score: vpnScore
+  }).rule({
+    name: "ProxyDetected",
+    reason: "Connection appears to use a proxy",
+    when: (s) => s.proxy === true,
+    score: vpnScore
+  }).rule({
+    name: "TorDetected",
+    reason: "Connection appears to use Tor",
+    when: (s) => s.tor === true,
+    score: vpnScore + 10
+  });
+}
+async function applyIpSignals(ip, guardian, provider) {
+  const intel = guardianRisk.isPrivateIp(ip) ? localIntel() : await provider.lookup(ip);
+  guardian.signal("clientIp", ip).signal("vpn", intel.vpn).signal("proxy", intel.proxy).signal("tor", intel.tor).signal("country", intel.country).signal("hosting", intel.hosting).signal("signalSource", "vpn");
+}
+function localIntel() {
+  return { vpn: false, proxy: false, tor: false, country: "local", hosting: false };
+}
+function resolveIpForLookup(guardian, data) {
+  const fromSignal = guardian.getSignal("clientIp");
+  if (typeof fromSignal === "string") {
+    const parsed = guardianRisk.parseIpAddress(fromSignal);
+    if (parsed) {
+      return parsed;
+    }
+  }
+  if (data !== null && typeof data === "object" && "clientIp" in data) {
+    const ip = data.clientIp;
+    const parsed = typeof ip === "string" ? guardianRisk.parseIpAddress(ip) : null;
+    if (parsed) {
+      return parsed;
+    }
+  }
+  if (data !== null && typeof data === "object" && "headers" in data) {
+    const req = data;
+    if (req.ips) {
+      for (const candidate of req.ips) {
+        const parsed = guardianRisk.parseIpAddress(candidate);
+        if (parsed) {
+          return parsed;
+        }
+      }
+    }
+    if (req.ip) {
+      const parsed = guardianRisk.parseIpAddress(req.ip);
+      if (parsed) {
+        return parsed;
+      }
+    }
+    if (req.socket?.remoteAddress) {
+      return guardianRisk.parseIpAddress(req.socket.remoteAddress);
+    }
+  }
+  if (typeof data === "string") {
+    return guardianRisk.parseIpAddress(data);
+  }
+  return null;
 }
 
+exports.IpApiProvider = IpApiProvider;
+exports.StaticIpProvider = StaticIpProvider;
 exports.checkIp = checkIp;
 exports.vpnPlugin = vpnPlugin;

package/dist/index.d.cts

@@ -1,27 +1,50 @@
 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). */
+/** IP intelligence result used for VPN/proxy/Tor signals. */
+interface IpIntelligence {
+    readonly vpn: boolean;
+    readonly proxy: boolean;
+    readonly tor: boolean;
+    readonly country: string;
+    readonly hosting: boolean;
+}
+/** Pluggable IP lookup for VPN detection. */
+interface IpProvider {
+    lookup(ip: string): Promise<IpIntelligence>;
+}
+interface IpApiProviderOptions {
+    readonly timeoutMs?: number;
+}
+/**
+ * ip-api.com provider (rate-limited). For production use MaxMind or IPinfo.
+ */
+declare class IpApiProvider implements IpProvider {
+    private readonly options;
+    constructor(options?: IpApiProviderOptions);
+    lookup(ip: string): Promise<IpIntelligence>;
+}
+/** Static provider for tests and offline use. */
+declare class StaticIpProvider implements IpProvider {
+    private readonly results;
+    constructor(results: Readonly<Record<string, IpIntelligence>>);
+    lookup(ip: string): Promise<IpIntelligence>;
+}
+
+/** Options for the VPN plugin. */
 interface VpnPluginOptions {
-    /** Provider used to classify IP addresses. */
-    readonly provider?: VpnProvider;
-    /** Default risk score added when VPN rules are registered by the plugin. */
+    /** Required for production. Defaults to empty static provider (no external calls). */
+    readonly provider?: IpProvider;
     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>;
+interface IpContext {
+    readonly clientIp: string;
+}
+declare function checkIp(ip: string, guardian: guardian_risk.Guardian, provider?: IpProvider): Promise<guardian_risk.Guardian>;
 
-export { type VpnPluginOptions, type VpnProvider, checkIp, vpnPlugin };
+export { IpApiProvider, type IpContext, type IpIntelligence, type IpProvider, StaticIpProvider, type VpnPluginOptions, checkIp, vpnPlugin };

package/dist/index.d.ts

@@ -1,27 +1,50 @@
 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). */
+/** IP intelligence result used for VPN/proxy/Tor signals. */
+interface IpIntelligence {
+    readonly vpn: boolean;
+    readonly proxy: boolean;
+    readonly tor: boolean;
+    readonly country: string;
+    readonly hosting: boolean;
+}
+/** Pluggable IP lookup for VPN detection. */
+interface IpProvider {
+    lookup(ip: string): Promise<IpIntelligence>;
+}
+interface IpApiProviderOptions {
+    readonly timeoutMs?: number;
+}
+/**
+ * ip-api.com provider (rate-limited). For production use MaxMind or IPinfo.
+ */
+declare class IpApiProvider implements IpProvider {
+    private readonly options;
+    constructor(options?: IpApiProviderOptions);
+    lookup(ip: string): Promise<IpIntelligence>;
+}
+/** Static provider for tests and offline use. */
+declare class StaticIpProvider implements IpProvider {
+    private readonly results;
+    constructor(results: Readonly<Record<string, IpIntelligence>>);
+    lookup(ip: string): Promise<IpIntelligence>;
+}
+
+/** Options for the VPN plugin. */
 interface VpnPluginOptions {
-    /** Provider used to classify IP addresses. */
-    readonly provider?: VpnProvider;
-    /** Default risk score added when VPN rules are registered by the plugin. */
+    /** Required for production. Defaults to empty static provider (no external calls). */
+    readonly provider?: IpProvider;
     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>;
+interface IpContext {
+    readonly clientIp: string;
+}
+declare function checkIp(ip: string, guardian: guardian_risk.Guardian, provider?: IpProvider): Promise<guardian_risk.Guardian>;
 
-export { type VpnPluginOptions, type VpnProvider, checkIp, vpnPlugin };
+export { IpApiProvider, type IpContext, type IpIntelligence, type IpProvider, StaticIpProvider, type VpnPluginOptions, checkIp, vpnPlugin };

package/dist/index.js

@@ -1,39 +1,161 @@
+import { parseIpAddress, isPrivateIp } from 'guardian-risk';
+
+// src/index.ts
+var DEFAULT_TIMEOUT_MS = 5e3;
+var LOOKUP_URL = "https://ip-api.com/json";
+var IpApiProvider = class {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  options;
+  async lookup(ip) {
+    const parsed = parseIpAddress(ip);
+    if (!parsed || isPrivateIp(parsed)) {
+      return localResult();
+    }
+    const controller = new AbortController();
+    const timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetch(
+        `${LOOKUP_URL}/${encodeURIComponent(parsed)}?fields=status,country,proxy,hosting`,
+        { signal: controller.signal }
+      );
+      if (!response.ok) {
+        throw new Error(`IP lookup failed with status ${response.status}`);
+      }
+      const data = await response.json();
+      if (data.status !== "success") {
+        return unknownResult();
+      }
+      return {
+        vpn: false,
+        proxy: data.proxy === true,
+        tor: false,
+        country: data.country ?? "unknown",
+        hosting: data.hosting === true
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+var StaticIpProvider = class {
+  constructor(results) {
+    this.results = results;
+  }
+  results;
+  async lookup(ip) {
+    const parsed = parseIpAddress(ip);
+    if (!parsed) {
+      return unknownResult();
+    }
+    return this.results[parsed] ?? unknownResult();
+  }
+};
+function localResult() {
+  return { vpn: false, proxy: false, tor: false, country: "local", hosting: false };
+}
+function unknownResult() {
+  return { vpn: false, proxy: false, tor: false, country: "unknown", hosting: false };
+}
+
 // src/index.ts
+var EMPTY_PROVIDER = new StaticIpProvider({});
 function vpnPlugin(options = {}) {
   const {
-    provider = "maxmind",
+    provider = EMPTY_PROVIDER,
     vpnScore = 20,
     registerDefaultRules = true
   } = options;
   return {
     name: "guardian-risk-vpn",
     install(guardian) {
-      if (!registerDefaultRules) {
-        return;
+      if (registerDefaultRules) {
+        registerVpnRules(guardian, vpnScore);
       }
-      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
+      guardian.beforeAnalyze(async ({ data, guardian: g }) => {
+        const ip = resolveIpForLookup(g, data);
+        if (!ip) {
+          return;
+        }
+        await applyIpSignals(ip, g, provider);
       });
     }
   };
 }
-async function checkIp(_ip, guardian) {
-  return guardian.signal("signalSource", "vpn").signal("vpn", false).signal("proxy", false).signal("tor", false).signal("country", "unknown");
+async function checkIp(ip, guardian, provider = EMPTY_PROVIDER) {
+  const parsed = parseIpAddress(ip);
+  if (!parsed) {
+    throw new TypeError("Invalid IP address");
+  }
+  await applyIpSignals(parsed, guardian, provider);
+  return guardian;
+}
+function registerVpnRules(guardian, vpnScore) {
+  guardian.rule({
+    name: "VpnDetected",
+    reason: "Connection appears to use a VPN or datacenter",
+    when: (s) => s.vpn === true || s.hosting === true,
+    score: vpnScore
+  }).rule({
+    name: "ProxyDetected",
+    reason: "Connection appears to use a proxy",
+    when: (s) => s.proxy === true,
+    score: vpnScore
+  }).rule({
+    name: "TorDetected",
+    reason: "Connection appears to use Tor",
+    when: (s) => s.tor === true,
+    score: vpnScore + 10
+  });
+}
+async function applyIpSignals(ip, guardian, provider) {
+  const intel = isPrivateIp(ip) ? localIntel() : await provider.lookup(ip);
+  guardian.signal("clientIp", ip).signal("vpn", intel.vpn).signal("proxy", intel.proxy).signal("tor", intel.tor).signal("country", intel.country).signal("hosting", intel.hosting).signal("signalSource", "vpn");
+}
+function localIntel() {
+  return { vpn: false, proxy: false, tor: false, country: "local", hosting: false };
+}
+function resolveIpForLookup(guardian, data) {
+  const fromSignal = guardian.getSignal("clientIp");
+  if (typeof fromSignal === "string") {
+    const parsed = parseIpAddress(fromSignal);
+    if (parsed) {
+      return parsed;
+    }
+  }
+  if (data !== null && typeof data === "object" && "clientIp" in data) {
+    const ip = data.clientIp;
+    const parsed = typeof ip === "string" ? parseIpAddress(ip) : null;
+    if (parsed) {
+      return parsed;
+    }
+  }
+  if (data !== null && typeof data === "object" && "headers" in data) {
+    const req = data;
+    if (req.ips) {
+      for (const candidate of req.ips) {
+        const parsed = parseIpAddress(candidate);
+        if (parsed) {
+          return parsed;
+        }
+      }
+    }
+    if (req.ip) {
+      const parsed = parseIpAddress(req.ip);
+      if (parsed) {
+        return parsed;
+      }
+    }
+    if (req.socket?.remoteAddress) {
+      return parseIpAddress(req.socket.remoteAddress);
+    }
+  }
+  if (typeof data === "string") {
+    return parseIpAddress(data);
+  }
+  return null;
 }
 
-export { checkIp, vpnPlugin };
+export { IpApiProvider, StaticIpProvider, checkIp, vpnPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guardian-risk-vpn",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "VPN and proxy detection plugin for guardian-risk — adds network risk signals",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -56,15 +56,17 @@
     "access": "public"
   },
   "peerDependencies": {
-    "guardian-risk": "^0.2.0"
+    "guardian-risk": "^0.3.0"
   },
   "devDependencies": {
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
-    "guardian-risk": "0.2.1"
+    "vitest": "^4.1.9",
+    "guardian-risk": "0.3.0"
   },
   "scripts": {
     "build": "tsup",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }
 }