@lock-dev/vpn-detection/dist/index.d.mts

VPN and proxy detection module for lock.dev security framework

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

declare enum VPNDetectionEventType {
    VPN_DETECTED = "vpn.detected",
    NO_VPN_DETECTED = "vpn.not_detected",
    VPN_DETECTION_ERROR = "vpn.error"
}
type VPNDetectionProvider = 'ipqualityscore' | 'ipapi' | 'custom';
type VPNStorage = 'memory' | 'redis' | 'upstash';
interface VPNDetectionResult {
    isVpn: boolean;
    vpnScore: number;
    isProxy: boolean;
    proxyScore: number;
    isTor: boolean;
    torScore: number;
    isDatacenter: boolean;
    datacenterScore: number;
    providerData?: Record<string, any>;
    timestamp: number;
}
interface VPNDetectionProviderInterface {
    init(): Promise<void>;
    checkIp(ip: string): Promise<VPNDetectionResult>;
}
interface VPNDetectionConfig {
    ipHeaders?: string[];
    useRemoteAddress?: boolean;
    blockStatusCode?: number;
    blockMessage?: string;
    provider?: VPNDetectionProvider;
    storage?: VPNStorage;
    cacheTtl?: number;
    cacheSize?: number;
    vpnScoreThreshold?: number;
    proxyScoreThreshold?: number;
    datacenterScoreThreshold?: number;
    torScoreThreshold?: number;
    checkVpn?: boolean;
    checkProxy?: boolean;
    checkDatacenter?: boolean;
    checkTor?: boolean;
    failBehavior?: 'open' | 'closed';
    blockTor?: boolean;
    blockVpn?: boolean;
    blockProxy?: boolean;
    blockDatacenter?: boolean;
    apiKey?: string;
    customProvider?: VPNDetectionProviderInterface;
    customProviderOptions?: Record<string, any>;
    logFunction?: (message: string, data?: any) => void;
    logResults?: boolean;
    redis?: {
        url?: string;
        host?: string;
        port?: number;
        password?: string;
        username?: string;
        database?: number;
        keyPrefix?: string;
    };
    upstash?: {
        url: string;
        token: string;
        keyPrefix?: string;
    };
}

/**
 * Extract client IP address from HTTP request.
 * Checks headers in order of preference and falls back to the remote address if enabled.
 *
 * @param req - HTTP request object.
 * @param ipHeaders - Array of header names to check for IP.
 * @param useRemoteAddress - Whether to use req.connection.remoteAddress as fallback.
 * @returns The client IP address or null if not found.
 */
declare function extractIp(req: any, ipHeaders?: string[], useRemoteAddress?: boolean): string | null;
/**
 * Clean and normalize IP address.
 * Removes IPv6 prefix from IPv4 mapped addresses (::ffff:192.168.1.1 -> 192.168.1.1).
 *
 * @param ip IP address to clean.
 * @returns Cleaned IP address.
 */
declare function cleanIp(ip: string): string;

/**
 * IPQualityScore VPN detection provider.
 */
declare class IPQualityScoreProvider implements VPNDetectionProviderInterface {
    private config;
    private apiKey;
    private baseUrl;
    private strictMode;
    private extraParams;
    constructor(config: VPNDetectionConfig);
    /**
     * Initializes the provider.
     *
     * @returns A promise that resolves when the provider has been initialized.
     */
    init(): Promise<void>;
    /**
     * Checks if an IP address is associated with a VPN, proxy, or Tor.
     *
     * @param ip - The IP address to check.
     * @returns A promise that resolves to the VPN detection result.
     */
    checkIp(ip: string): Promise<VPNDetectionResult>;
}

/**
 * IP-API.com VPN detection provider.
 */
declare class IPAPIProvider implements VPNDetectionProviderInterface {
    private config;
    private baseUrl;
    private proUrl;
    private useProVersion;
    private apiKey;
    private fields;
    constructor(config: VPNDetectionConfig);
    /**
     * Initializes the provider.
     *
     * @returns A promise that resolves when the provider has been initialized.
     */
    init(): Promise<void>;
    /**
     * Checks if an IP address is associated with a VPN, proxy, or Tor.
     *
     * @param ip - The IP address to check.
     * @returns A promise that resolves to the VPN detection result.
     */
    checkIp(ip: string): Promise<VPNDetectionResult>;
}

/**
 * Creates a VPN detection provider based on the given configuration.
 *
 * If a custom provider is specified in the configuration, it is used directly.
 * Otherwise, the function creates a provider instance based on the specified type:
 * - 'ipqualityscore' returns an instance of IPQualityScoreProvider.
 * - 'ipapi' returns an instance of IPAPIProvider.
 * - Any unrecognized provider defaults to IPQualityScoreProvider.
 *
 * @param config - The VPN detection configuration.
 * @returns The VPN detection provider.
 */
declare function createProvider(config: VPNDetectionConfig): VPNDetectionProviderInterface;

declare class MemoryVPNCacheStore implements VPNCacheStore {
    private cache;
    constructor(config: VPNDetectionConfig);
    init(): Promise<void>;
    get(ip: string): Promise<VPNDetectionResult | null>;
    set(ip: string, value: VPNDetectionResult): Promise<void>;
    close(): Promise<void>;
}

declare class RedisVPNCacheStore implements VPNCacheStore {
    private client;
    private keyPrefix;
    private config;
    private ttl;
    constructor(config: VPNDetectionConfig);
    init(): Promise<void>;
    get(ip: string): Promise<VPNDetectionResult | null>;
    set(ip: string, value: VPNDetectionResult): Promise<void>;
    close(): Promise<void>;
}

declare class UpstashVPNCacheStore implements VPNCacheStore {
    private client;
    private keyPrefix;
    private config;
    private ttl;
    constructor(config: VPNDetectionConfig);
    init(): Promise<void>;
    get(ip: string): Promise<VPNDetectionResult | null>;
    set(ip: string, value: VPNDetectionResult): Promise<void>;
    close(): Promise<void>;
}

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

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

export { IPAPIProvider, IPQualityScoreProvider, MemoryVPNCacheStore, RedisVPNCacheStore, UpstashVPNCacheStore, type VPNCacheStore, type VPNDetectionConfig, VPNDetectionEventType, type VPNDetectionProvider, type VPNDetectionProviderInterface, type VPNDetectionResult, type VPNStorage, cleanIp, createCacheStore, createProvider, extractIp, vpnDetector };