@lock-dev/ip-filter/dist/index.d.mts

IP filtering module for lock.dev security framework

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

declare enum IPFilterEventType {
    IP_BLOCKED = "ip.blocked",
    IP_ALLOWED = "ip.allowed",
    IP_FILTER_ERROR = "ip.error"
}
type IPStorage = 'memory' | 'redis' | 'upstash';
interface IPFilterConfig {
    mode: 'blacklist' | 'whitelist';
    ipAddresses: string[];
    storage?: IPStorage;
    ipHeaders?: string[];
    useRemoteAddress?: boolean;
    blockStatusCode?: number;
    blockMessage?: string;
    cacheTtl?: number;
    cacheSize?: number;
    failBehavior?: 'open' | 'closed';
    logFunction?: (message: string, data?: any) => void;
    logAllowed?: boolean;
    logBlocked?: boolean;
    redis?: {
        url?: string;
        host?: string;
        port?: number;
        username?: string;
        password?: 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, falls back to 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 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;

/**
 * Check if an IP address is in a CIDR range
 * @param ip The IP address to check
 * @param cidr The CIDR range to check against
 * @returns True if the IP is in the CIDR range, false otherwise
 */
declare function ipInCidr(ip: string, cidr: string): boolean;
/**
 * Check if an IP address matches another IP address
 * @param ip1 The first IP address
 * @param ip2 The second IP address
 * @returns True if the IPs match, false otherwise
 */
declare function ipEquals(ip1: string, ip2: string): boolean;
/**
 * Check if an IP address is in a list of IPs or CIDR ranges
 * @param ip The IP address to check
 * @param list Array of IP addresses or CIDR ranges
 * @returns True if the IP is in the list, false otherwise
 */
declare function isIpInList(ip: string, list: string[]): boolean;
/**
 * Normalizes an IP address string
 * @param ip The IP address to normalize
 * @returns Normalized IP address string or null if invalid
 */
declare function normalizeIp(ip: string): string | null;
/**
 * Validates an IP address or CIDR range
 * @param input IP address or CIDR range to validate
 * @returns True if valid, false otherwise
 */
declare function isValidIpOrCidr(input: string): boolean;

declare class MemoryIPCacheStore implements IPCacheStore {
    private cache;
    constructor(config: IPFilterConfig);
    init(): Promise<void>;
    get(key: string): Promise<boolean | null>;
    set(key: string, value: boolean): Promise<void>;
    close(): Promise<void>;
}

declare class RedisIPCacheStore implements IPCacheStore {
    private client;
    private keyPrefix;
    private config;
    private ttl;
    constructor(config: IPFilterConfig);
    init(): Promise<void>;
    get(key: string): Promise<boolean | null>;
    set(key: string, value: boolean): Promise<void>;
    close(): Promise<void>;
}

declare class UpstashIPCacheStore implements IPCacheStore {
    private client;
    private keyPrefix;
    private config;
    private ttl;
    constructor(config: IPFilterConfig);
    init(): Promise<void>;
    get(key: string): Promise<boolean | null>;
    set(key: string, value: boolean): Promise<void>;
    close(): Promise<void>;
}

interface IPCacheStore {
    init(): Promise<void>;
    get(key: string): Promise<boolean | null>;
    set(key: string, value: boolean): Promise<void>;
    close(): Promise<void>;
}
declare function createCacheStore(config: IPFilterConfig): Promise<IPCacheStore>;

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

export { type IPCacheStore, type IPFilterConfig, IPFilterEventType, type IPStorage, MemoryIPCacheStore, RedisIPCacheStore, UpstashIPCacheStore, cleanIp, createCacheStore, extractIp, ipEquals, ipFilter, ipInCidr, isIpInList, isValidIpOrCidr, normalizeIp };