@lock-dev/geo-block/dist/index.d.cts

Geographic blocking module for lock.dev security framework

import * as _lock_dev_core from '@lock-dev/core';

declare enum GeoBlockEventType {
    GEO_BLOCKED = "geo_blocked"
}
/**
 * Configuration for geo-blocking
 */
interface GeoBlockConfig {
    /**
     * Mode of operation - allow only specified countries or block specified countries
     * @default 'blocklist'
     */
    mode: 'allowlist' | 'blocklist';
    /**
     * List of country codes to allow or block (ISO 3166-1 alpha-2)
     * @example ['US', 'CA', 'GB']
     */
    countries: string[];
    /**
     * Provider for IP-to-location lookup
     * @default 'maxmind'
     */
    provider: 'maxmind' | 'ipapi' | 'ipstack' | 'custom';
    /**
     * Path to MaxMind database file if using 'maxmind' provider
     */
    maxmindDbPath?: string;
    /**
     * API key for providers that require authentication
     */
    apiKey?: string;
    /**
     * Custom implementation for IP lookup
     */
    customLookup?: (ip: string) => Promise<GeoInfo>;
    /**
     * Headers to check for client IP address, in order of preference
     * @default ['cf-connecting-ip', 'x-forwarded-for', 'x-real-ip']
     */
    ipHeaders?: string[];
    /**
     * Use fallback to remote address if headers aren't present
     * @default true
     */
    useRemoteAddress?: boolean;
    /**
     * HTTP status code to return when blocked
     * @default 403
     */
    blockStatusCode?: number;
    /**
     * Message to return when blocked
     * @default 'Access denied based on your location'
     */
    blockMessage?: string;
    /**
     * Whether to include the country code in the block response
     * @default true
     */
    includeCountryInResponse?: boolean;
    /**
     * Time in milliseconds to cache IP lookups
     * @default 3600000 (1 hour)
     */
    cacheTtl?: number;
    /**
     * Maximum number of IP addresses to cache
     * @default 10000
     */
    cacheSize?: number;
    /**
     * How to handle provider failures
     * - 'open': Allow requests when geo lookup fails (default)
     * - 'closed': Block requests when geo lookup fails
     * @default open
     */
    failBehavior?: 'open' | 'closed';
}
/**
 * Geographic information for an IP address
 */
interface GeoInfo {
    /**
     * ISO 3166-1 alpha-2 country code
     * @example 'US'
     */
    country?: string;
    /**
     * Region or state
     * @example 'CA'
     */
    region?: string;
    /**
     * City name
     * @example 'San Francisco'
     */
    city?: string;
    /**
     * Latitude coordinate
     */
    latitude?: number;
    /**
     * Longitude coordinate
     */
    longitude?: number;
}
/**
 * Provider interface for geo lookups
 */
interface GeoLookupProvider {
    /**
     * Initialize the provider
     */
    init(): Promise<void>;
    /**
     * Look up geographic information for an IP address
     * @param ip IP address to look up
     */
    lookup(ip: string): Promise<GeoInfo>;
}

/**
 * Extract client IP address from request
 * @param request HTTP request object
 * @param ipHeaders Headers to check for IP address
 * @param useRemoteAddress Whether to fall back to remote address
 */
declare function extractIp(request: any, ipHeaders?: string[], useRemoteAddress?: boolean): string | null;

/**
 * Create a geo-blocking security module
 * @param config Module configuration
 */
declare const geoBlock: (config?: Partial<GeoBlockConfig> | undefined) => _lock_dev_core.SecurityModule;

export { type GeoBlockConfig, GeoBlockEventType, type GeoInfo, type GeoLookupProvider, extractIp, geoBlock };