geo-fence-guard

Geolocation-based access control for websites. Only allow devices physically located inside a GPS zone to access your site.

Features

• Server-validated geolocation (not just a client-side overlay)
• RSA-encrypted bounds (zone coordinates never visible in network traffic)
• Automatic local GPS re-check (no extra server requests)
• Access revoked when user leaves the zone
• Cookie-based session (no re-check on page reload)
• Zero dependencies

How it works

1. Page content is hidden immediately on load
2. Browser requests GPS permission
3. Coordinates are sent to your server endpoint along with an ephemeral RSA public key
4. Server validates the position is inside the allowed zone
5. Server encrypts the zone bounds with the client's public key and returns a signed token
6. Client decrypts bounds locally and restores the page content
7. GPS is re-checked locally every 5 minutes (zero server requests)
8. If the user leaves the zone, access is revoked instantly

Installation

npm install geo-fence-guard

Client usage

import { GeoFenceGuard } from 'geo-fence-guard';

const guard = new GeoFenceGuard({
  endpoint: 'https://your-server.com/geo-check.php',
  recheckInterval: 300000, // re-check every 5 min (default)
  onGranted: () => console.log('Access granted'),
  onDenied: (reason) => console.log('Denied:', reason.type),
  onExitedZone: () => console.log('User left the zone'),
});

guard.check();

Server endpoint

A PHP example is included in examples/geo-check.php. Copy it to your server and configure:

define('SECRET_KEY', 'your-secret-key');
define('BOUNDS_NORTH', 48.90);
define('BOUNDS_SOUTH', 48.80);
define('BOUNDS_EAST',   2.40);
define('BOUNDS_WEST',   2.30);
define('TOKEN_DURATION', 14400); // 4 hours

The endpoint must handle two types of POST requests:

• { lat, lng, publicKey } — validate position, return { token, expiresIn, encryptedBounds }
• { token, publicKey } — validate existing token, return { valid, encryptedBounds }

You can implement this in any language (Node.js, Python, Go...) as long as it follows this API contract.

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | endpoint | string | required | URL of your server validation endpoint | | cookieName | string | 'geo_fence_token' | Cookie name for storing the token | | recheckInterval | number | 300000 | Local GPS re-check interval in ms (0 to disable) | | highAccuracy | boolean | true | Use high accuracy GPS | | timeout | number | 10000 | Geolocation request timeout in ms | | message | string | auto | Custom message on block screen | | blockScreenStyles | object | — | Custom styles: backgroundColor, textColor, fontSize | | onGranted | function | — | Callback when access is granted | | onDenied | function | — | Callback when access is denied | | onExitedZone | function | — | Callback when user leaves the zone |

Security

• GPS coordinates are validated server-side (not just client-side)
• Zone bounds are RSA-encrypted in transit (never visible in DevTools network tab)
• RSA key pair is ephemeral (generated in memory per session, never stored)
• Page content is removed from DOM until validated (not just hidden with an overlay)
• Token is signed with HMAC-SHA256

License

MIT