/**
 * IP Address Extractor
 *
 * Reads a client IP from proxy/CDN forwarding headers (`X-Forwarded-For`, `CF-Connecting-IP`,
 * `X-Real-IP`, …), falling back to `req.ip` / `req.socket.remoteAddress`.
 *
 * !!! SECURITY WARNING — DO NOT use the result for security decisions !!!
 *
 * Every forwarding header this reads is **client-settable**. Unless `trustedProxies` is set
 * AND enforced, this returns whatever the caller put in the header, so it CANNOT be trusted
 * for anything an attacker benefits from forging: IP-based account lockout, rate limiting,
 * geolocation trust, or audit provenance. (Note: `trustedProxies` is accepted for forward
 * compatibility but is **not currently enforced** by this function — see below.)
 *
 * For a spoof-resistant client IP, use the framework-resolved `req.ip` with a correctly
 * configured `trust proxy` (Express) / `trustProxy` (Fastify), which only honours forwarding
 * headers for hops the operator has explicitly trusted and otherwise falls back to the socket
 * peer. That is what the toolkit's own request handlers and guards do.
 *
 * This helper remains only for callers that must read a *best-effort, untrusted* forwarded IP
 * for non-security purposes (e.g. display/logging behind a proxy you already trust at the
 * network layer).
 *
 * @example
 * ```typescript
 * // NON-SECURITY, best-effort only:
 * const forwardedIp = extractClientIp(req);
 * logger.debug('Reported client IP (untrusted):', forwardedIp);
 * ```
 */
/**
 * 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.
     *
     * NOTE: currently accepted for forward compatibility but **not enforced** by
     * {@link extractClientIp}. Do not rely on this to restrict which peers may set
     * forwarding headers — configure your framework's `trust proxy` / `trustProxy` and read
     * `req.ip` instead.
     */
    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