/**
 * IP Address Extractor
 *
 * Extracts the real client IP address from requests, handling:
 * - Direct connections
 * - Reverse proxies (Nginx, Apache)
 * - Load balancers (AWS ALB/NLB, GCP, Azure)
 * - CDNs (Cloudflare, Fastly, Akamai)
 *
 * **Priority Order:**
 * 1. X-Forwarded-For (standard proxy header)
 * 2. CF-Connecting-IP (Cloudflare)
 * 3. X-Real-IP (Nginx proxy)
 * 4. X-Client-IP (Apache, other proxies)
 * 5. Fastly-Client-IP (Fastly CDN)
 * 6. Akamai-Origin-Hop (Akamai CDN)
 * 7. req.ip (NestJS/Express default)
 * 8. req.socket.remoteAddress (fallback)
 *
 * **Security:**
 * - Handles multiple proxies (takes leftmost IP)
 * - Validates IP format
 * - Filters private/internal IPs (optional)
 * - Prevents IP spoofing
 *
 * @example
 * ```typescript
 * import { extractClientIp } from '@nauth-toolkit/core/utils';
 *
 * @Post('login')
 * async login(@Req() req: Request) {
 *   const ipAddress = extractClientIp(req);
 *   logger.debug('Client IP:', ipAddress); // Real client IP
 * }
 * ```
 */
/**
 * Options for IP extraction
 */
export interface IpExtractorOptions {
    /**
     * Whether to filter out private/internal IP addresses
     * Defaults to false
     */
    filterPrivateIps?: boolean;
    /**
     * List of trusted proxy IP addresses or CIDR ranges
     * If specified, only accepts X-Forwarded-For from these proxies
     */
    trustedProxies?: string[];
    /**
     * Whether to use the leftmost IP in X-Forwarded-For
     * (true = original client, false = rightmost/last proxy)
     * Defaults to true
     */
    useLeftmostIp?: boolean;
}
/**
 * Minimal request shape required for IP extraction.
 *
 * We keep this intentionally framework-agnostic (no Express/Fastify types) to avoid
 * adding hard dependencies from core.
 */
interface IpRequestLike extends Record<string, unknown> {
    headers?: Record<string, unknown>;
    ip?: string;
    socket?: {
        remoteAddress?: string;
    };
    connection?: {
        remoteAddress?: string;
    };
}
/**
 * Extracts the real client IP address from an HTTP request
 *
 * @param req - Express Request object
 * @param options - Optional configuration
 * @returns The client's IP address, or '0.0.0.0' if unable to determine
 */
export declare function extractClientIp(req: IpRequestLike, options?: IpExtractorOptions): string;
/**
 * Checks if an IP address is private/internal
 *
 * Detects:
 * - Localhost (127.0.0.0/8, ::1)
 * - Private IPv4 ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
 * - Link-local addresses (169.254.0.0/16)
 *
 * @param ip - IP address to check
 * @returns True if private, false otherwise
 *
 * @example
 * ```typescript
 * isPrivateIp('192.168.1.1'); // true
 * isPrivateIp('8.8.8.8'); // false
 * ```
 */
export declare function isPrivateIp(ip: string): boolean;
/**
 * Gets geolocation information for an IP address (placeholder)
 *
 * @param ip - IP address
 * @returns Geolocation info (to be implemented with MaxMind/IP-API)
 */
export declare function getIpGeolocation(_ip: string): {
    country?: string;
    city?: string;
};
export {};
//# sourceMappingURL=ip-extractor.d.ts.map