How to Use

To use this component, open Manage Dependencies (Ctrl+Q) in your application, search for VpnDetectorLib, and reference the necessary Client Actions and Structures.

This component exposes 4 distinct Client Actions, allowing you to choose between a full security scan or lightweight individual checks. All actions return clearly mapped, easy-to-read OutSystems Structures.

1. CheckVpnRisk (The "Strong Check")

This is the recommended, all-in-one action. It runs all tests asynchronously and calculates a consolidated risk report based on weighted scoring.

• Best For: Complete session validation upon user login or sensitive transactions.
• Outputs:
  • Result.Level: Returns an immediate LOW, MEDIUM, or HIGH risk rating.
  • Result.Score: A numeric risk score from 0 to 100.
  • Result.IsSuspicious: A simple True/False boolean for quick logic checks.
• Bonus: It also extracts rich network data, allowing you to easily access the user's ISP name, City, Country, and ASN via Result.ipInfo.raw.

2. CheckGeoIpDistance

Want to verify physical location without running the full suite? This action calculates the physical distance between the device's hardware GPS and the IP routing location.

• Best For: Food delivery apps, attendance tracking, or geo-restricted content.
• Inputs: DistanceThresholdKm (Integer, Default: 500). Sets the maximum acceptable distance between the GPS and IP before flagging the user.
• Outputs: Returns a Suspicious boolean, the calculated DistanceKm, and the exact GPS/IP coordinate mapping.

3. CheckTimezoneMismatch

A lightning-fast, silent check to see if the user's hardware device clock matches the geographic routing of their IP address.

• Best For: Background checks that don't require prompting the user for GPS permissions.
• Outputs: Returns the BrowserTimezone (e.g., Asia/Riyadh), the IpTimezone, and a Suspicious boolean if they do not match.

4. GetCanvasFingerprint

Synchronously draws a hidden graphic in the browser to generate a unique device fingerprint fragment.

• Best For: Identifying repeat devices, even if the user clears their cookies or uses Incognito/Private mode.
• Outputs: The full Base64 Image URL and a convenient 100-character Fragment string that is easy to store in your database.

Important Notes & Limitations

• Browser Permissions: The Geo/IP distance calculation relies on the native navigator.geolocation HTML5 API. The end-user must accept the location tracking prompt in their browser. If the user denies permission, the check gracefully handles the error and defaults to a "GeoUnavailable" fallback score, rather than breaking your application flow.

The underlying JavaScript logic and detection methodologies used in this component were heavily inspired by and reference concepts detailed in the following HackerNoon article:

Yes, Your Browser is Snitching: JavaScript Can Detect VPNs and Incognito Mode

How to Use

This component exposes 4 distinct Client Actions that you can use depending on your needs. All actions return clearly mapped OutSystems Structures.

1. CheckVpnRisk (The "Strong Check")

The easiest way to check a user. It runs all tests asynchronously and returns a consolidated risk report.

Outputs: Result.Level (LOW/MEDIUM/HIGH), Result.Score, Result.IsSuspicious.

Also returns raw IP details like ISP name, City, Country, and ASN (Result.ipInfo.raw).

2. CheckGeoIpDistance

Only want to verify physical location? Use this action.

Inputs: DistanceThresholdKm (Default: 500).

Outputs: Suspicious (Boolean), DistanceKm, and the raw GPS coordinates vs IP coordinates.

3. CheckTimezoneMismatch

A lightning-fast check to see if the user's device clock matches their IP routing location.

Outputs: BrowserTimezone, IpTimezone, and a Suspicious boolean.

4. GetCanvasFingerprint

Synchronously generates a unique browser fingerprint fragment.

Outputs: Base64 Image URL and a 100-character string fragment.

Important Notes

Browser Permissions: The Geo/IP distance check relies on the browser's native navigator.geolocation API. The end-user must accept the location tracking prompt in their browser. If they deny the permission, the check will default to a "GeoUnavailable" fallback score.

The underlying JavaScript logic and detection methodologies used in this component were inspired by and reference concepts detailed in the following HackerNoon article:

Your Browser is Snitching: JavaScript Can Detect VPNs and Incognito Mode