🌍 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