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

Geographic blocking module for lock.dev security framework

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

declare enum GeoBlockEventType {
    GEO_BLOCKED = "geo_blocked"
}
type GeoStorage = 'memory' | 'redis' | 'upstash';
/**
 * Configuration for geo-blocking
 */
interface GeoBlockConfig {
    /**
     * Mode of operation - allow only specified countries or block specified countries
     * @default 'blacklist'
     */
    mode: 'whitelist' | 'blacklist';
    /**
     * 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';
    /**
     * Storage type for caching geo results
     * @default 'memory'
     */
    storage?: GeoStorage;
    /**
     * 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;
    /**
     * 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';
    /**
     * Redis configuration when using Redis storage
     */
    redis?: {
        url?: string;
        host?: string;
        port?: number;
        username?: string;
        password?: string;
        database?: number;
        keyPrefix?: string;
    };
    /**
     * Upstash configuration when using Upstash storage
     */
    upstash?: {
        url: string;
        token: string;
        keyPrefix?: string;
    };
}
/**
 * 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>;
}

/**
 * Extracts the client IP address from an HTTP request object.
 *
 * The function checks the specified headers for an IP address, handling comma-separated
 * lists typically found in forwarded headers. If none of the headers contain an IP address,
 * and if allowed, it falls back to using the remote address from the connection or socket.
 *
 * @param request - The HTTP request object.
 * @param ipHeaders - An array of header names to check for the IP address.
 * @param useRemoteAddress - Whether to use the remote address if headers do not contain an IP.
 * @returns The extracted IP address as a string, or null if not found.
 */
declare function extractIp(request: any, ipHeaders?: string[], useRemoteAddress?: boolean): string | null;

declare class MemoryGeoCacheStore implements GeoCacheStore {
    private cache;
    constructor(config: GeoBlockConfig);
    init(): Promise<void>;
    get(ip: string): Promise<GeoInfo | null>;
    set(ip: string, value: GeoInfo): Promise<void>;
    close(): Promise<void>;
}

declare class RedisGeoCacheStore implements GeoCacheStore {
    private client;
    private keyPrefix;
    private config;
    private ttl;
    constructor(config: GeoBlockConfig);
    init(): Promise<void>;
    get(ip: string): Promise<GeoInfo | null>;
    set(ip: string, value: GeoInfo): Promise<void>;
    close(): Promise<void>;
}

declare class UpstashGeoCacheStore implements GeoCacheStore {
    private client;
    private keyPrefix;
    private config;
    private ttl;
    constructor(config: GeoBlockConfig);
    init(): Promise<void>;
    get(ip: string): Promise<GeoInfo | null>;
    set(ip: string, value: GeoInfo): Promise<void>;
    close(): Promise<void>;
}

interface GeoCacheStore {
    init(): Promise<void>;
    get(ip: string): Promise<GeoInfo | null>;
    set(ip: string, value: GeoInfo): Promise<void>;
    close(): Promise<void>;
}
declare function createCacheStore(config: GeoBlockConfig): Promise<GeoCacheStore>;

declare const geoBlock: (config?: Partial<GeoBlockConfig> | undefined) => _lock_dev_core.SecurityModule;

export { type GeoBlockConfig, GeoBlockEventType, type GeoCacheStore, type GeoInfo, type GeoLookupProvider, type GeoStorage, MemoryGeoCacheStore, RedisGeoCacheStore, UpstashGeoCacheStore, createCacheStore, extractIp, geoBlock };