/**
 * @module @arcis/node/utils/ip
 * Platform-aware client IP detection.
 *
 * Prevents IP spoofing by reading platform-specific headers
 * instead of blindly trusting X-Forwarded-For.
 *
 * @example
 * // Auto-detect platform from environment
 * const ip = detectClientIp(req);
 *
 * // Explicit platform
 * const ip = detectClientIp(req, { platform: 'cloudflare' });
 */
import type { IncomingMessage } from 'http';
export type Platform = 'auto' | 'cloudflare' | 'vercel' | 'flyio' | 'render' | 'firebase' | 'aws-alb' | 'generic';
export interface DetectIpOptions {
    /** Platform to use for header selection. Default: 'auto' */
    platform?: Platform;
    /** Number of trusted proxies (for X-Forwarded-For parsing). Default: 1 */
    trustedProxyCount?: number;
}
interface RequestLike {
    headers: Record<string, string | string[] | undefined>;
    socket?: {
        remoteAddress?: string;
    };
    connection?: {
        remoteAddress?: string;
    };
    ip?: string;
}
/**
 * Detect the real client IP address from a request.
 *
 * Uses platform-specific headers when available to prevent IP spoofing.
 * Falls back to X-Forwarded-For (parsed from the right) and then
 * the socket remote address.
 *
 * @param req - HTTP request object (Express, raw http, etc.)
 * @param options - Detection options
 * @returns Client IP address, or 'unknown' if unresolvable
 *
 * @example
 * // Auto-detect platform
 * app.use((req, res, next) => {
 *   const clientIp = detectClientIp(req);
 *   console.log('Client IP:', clientIp);
 *   next();
 * });
 *
 * @example
 * // Behind Cloudflare
 * const ip = detectClientIp(req, { platform: 'cloudflare' });
 *
 * @example
 * // Behind 2 proxies (e.g. CDN + load balancer)
 * const ip = detectClientIp(req, { trustedProxyCount: 2 });
 */
export declare function detectClientIp(req: RequestLike | IncomingMessage, options?: DetectIpOptions): string;
/**
 * Check if an IP address is a private/internal address.
 *
 * Detects: loopback, private ranges (RFC 1918), link-local, IPv6 equivalents.
 */
export declare function isPrivateIp(ip: string): boolean;
/** Reset cached platform (for testing). */
export declare function _resetPlatformCache(): void;
export {};
//# sourceMappingURL=ip.d.ts.map