1.0.0 • Published 8 months ago
@lock-sdk/geo-block v1.0.0
🌍 Geo Block
A geo-based access control module for the Lock Security Framework. Block or allow traffic based on a user's country, with support for providers like MaxMind, IPAPI, plus caching, failovers, and distributed storage.
🚀 Features
- 🌎 Country-based access rules (whitelist / blacklist modes)
- 📡 Supports IPAPI, MaxMind DB
- 💾 In-memory or distributed caching (Redis / Upstash)
- 🔁 Built-in fallback and fail-safe logic
- 🧠 Smart IP extraction from headers or remote address
🛠 Usage
Example: Block Requests from Specific Countries
import { secure, geoBlock } from '@lock-sdk/main';
const middleware = secure()(
geoBlock({
mode: 'blacklist',
countries: ['RU', 'CN', 'IR'],
provider: 'ipapi',
})
);Example: Allow Only US and CA
geoBlock({
mode: 'whitelist',
countries: ['US', 'CA'],
provider: 'maxmind',
maxmindDbPath: './GeoLite2-Country.mmdb',
});⚙️ Configuration
| Option | Type | Default | Description |
|---|---|---|---|
mode | 'blacklist' | 'whitelist' | 'blacklist' | Block or allow traffic based on country list |
countries | string[] | [] | List of country ISO codes (e.g. 'US', 'IN') |
provider | 'ipapi' | 'maxmind' | 'ipapi' | Geo location service provider |
maxmindDbPath | string | – | Path to .mmdb file if using MaxMind |
apiKey | string | – | API key for IPAPI/IPStack |
ipHeaders | string[] | ['cf-connecting-ip', 'x-forwarded-for', 'x-real-ip'] | Headers to check for client IP |
useRemoteAddress | boolean | true | Use req.socket.remoteAddress if header missing |
blockStatusCode | number | 403 | HTTP status on geo block |
blockMessage | string | 'Access denied based on your location' | Error message sent to client |
failBehavior | 'open' | 'closed' | 'open' | Whether to allow traffic if provider fails |
customLookup | (ip: string) => Promise<GeoInfo> | – | Override provider with your own lookup function |
storage | 'memory' | 'redis' | 'upstash' | 'memory' | Backend used for caching lookups |
cacheTtl | number (ms) | 3600000 | Duration for which geo result is cached |
cacheSize | number | 10000 | Max entries for memory cache |
redis | object | – | Redis connection config |
upstash | object | – | Upstash Redis config |
🛡 Maintained By
Lock Team