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

VPN and proxy detection module for Lock security framework

import * as _lock_sdk_core from '@lock-sdk/core';

declare enum VPNDetectionEventType {
    VPN_DETECTED = "vpn.detected",
    NO_VPN_DETECTED = "vpn.not.detected",
    VPN_DETECTION_ERROR = "vpn.error"
}
type VPNDetectionProvider = 'ipqualityscore' | 'ipapi';
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;
    };
}

declare function extractIp(req: any, ipHeaders?: string[], useRemoteAddress?: boolean): string | null;
declare function cleanIp(ip: string): string;

declare class IPQualityScoreProvider implements VPNDetectionProviderInterface {
    private config;
    private apiKey;
    private baseUrl;
    private strictMode;
    private extraParams;
    constructor(config: VPNDetectionConfig);
    init(): Promise<void>;
    checkIp(ip: string): Promise<VPNDetectionResult>;
}

declare class IPAPIProvider implements VPNDetectionProviderInterface {
    private config;
    private baseUrl;
    private proUrl;
    private useProVersion;
    private apiKey;
    private fields;
    constructor(config: VPNDetectionConfig);
    init(): Promise<void>;
    checkIp(ip: string): Promise<VPNDetectionResult>;
}

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_sdk_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 };