<?php
/**
 * Real visitor IP resolution (build brief correction #1).
 *
 * Pure logic, no WordPress dependency, so it is unit-testable on its own.
 *
 * The rule: use the DIRECT connecting address (REMOTE_ADDR) by default. Only
 * trust a provider forwarding header when the request DEMONSTRABLY came through
 * that configured trusted proxy -- i.e. REMOTE_ADDR is inside the proxy's own
 * published ranges. Never blindly trust X-Forwarded-For, because any client can
 * set it and spoof a crawler IP.
 *
 * @package AIMention_Visibility
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Resolves the real visitor IP from proxy headers, resistant to spoofing.
 */
class AIMention_IP_Resolver {

	/**
	 * Resolve the real client IP.
	 *
	 * @param array $server  $_SERVER-like map (REMOTE_ADDR + any proxy headers).
	 * @param array $config Proxy config: proxy (none|cloudflare|custom), header, and trusted_ranges (CIDR list).
	 * @return string|null The real IP, or null if none could be determined.
	 */
	public static function resolve( array $server, array $config ) {
		$remote = isset( $server['REMOTE_ADDR'] ) ? trim( $server['REMOTE_ADDR'] ) : '';
		if ( '' === $remote || ! self::is_ip( $remote ) ) {
			return null;
		}

		$proxy = isset( $config['proxy'] ) ? $config['proxy'] : 'none';
		if ( 'none' === $proxy ) {
			// Not behind a proxy: the direct connection is the truth. Any
			// forwarding header present here is attacker-controlled -> ignored.
			return $remote;
		}

		$trusted_ranges = isset( $config['trusted_ranges'] ) ? (array) $config['trusted_ranges'] : array();
		if ( 'cloudflare' === $proxy && empty( $trusted_ranges ) ) {
			$trusted_ranges = self::cloudflare_ranges();
		}

		// The header we would read is trustworthy ONLY if the request actually
		// arrived from a trusted-proxy address. Otherwise fall back to REMOTE_ADDR.
		if ( ! self::ip_in_any_range( $remote, $trusted_ranges ) ) {
			return $remote;
		}

		$header = isset( $config['header'] ) ? $config['header'] : ( 'cloudflare' === $proxy ? 'CF-Connecting-IP' : '' );
		$key    = self::header_to_server_key( $header );
		if ( '' === $key || empty( $server[ $key ] ) ) {
			return $remote;
		}

		$candidate = self::last_untrusted_ip( $server[ $key ], $trusted_ranges );
		return $candidate ? $candidate : $remote;
	}

	/**
	 * Reduce a raw IP to the prefix we send/store (privacy). /24 for IPv4,
	 * /48 for IPv6 -- coarse enough to be non-identifying, precise enough for a
	 * bot-range sanity read. The plugin does the authoritative verification with
	 * the FULL IP before calling this; only the reduced form ever leaves the site.
	 *
	 * @param string $ip Raw IP address.
	 * @return string Reduced CIDR prefix, or '' if the input is not an IP.
	 */
	public static function reduce( $ip ) {
		if ( ! self::is_ip( $ip ) ) {
			return '';
		}
		if ( false !== strpos( $ip, ':' ) ) {
			return self::mask_v6( $ip, 48 );
		}
		$parts = explode( '.', $ip );
		if ( 4 !== count( $parts ) ) {
			return '';
		}
		return $parts[0] . '.' . $parts[1] . '.' . $parts[2] . '.0/24';
	}

	/**
	 * Non-reversible, site-salted token for the crawler IP. This is what leaves
	 * the site as `ip_prefix_or_hash`; the raw IP is verified locally first, then
	 * dropped. Salted with the site key so the same crawler IP is not
	 * correlatable across unrelated sites.
	 *
	 * @param string $ip   Raw IP address.
	 * @param string $salt Per-site salt (the collection key).
	 * @return string Prefixed non-reversible token, or '' if the input is not an IP.
	 */
	public static function hash( $ip, $salt ) {
		if ( ! self::is_ip( $ip ) ) {
			return '';
		}
		return 'h:' . substr( hash( 'sha256', $salt . ':' . $ip ), 0, 24 );
	}

	/**
	 * Whether a string is a syntactically valid IP address.
	 *
	 * @param string $ip Candidate value.
	 * @return bool True if valid.
	 */
	public static function is_ip( $ip ) {
		return false !== filter_var( $ip, FILTER_VALIDATE_IP );
	}

	/**
	 * First syntactically valid IP in a header value (handles a comma list).
	 *
	 * @param string $value Header value, possibly a comma-separated list.
	 * @return string|null The first valid IP, or null if none.
	 */
	public static function first_valid_ip( $value ) {
		foreach ( explode( ',', (string) $value ) as $part ) {
			$part = trim( $part );
			if ( self::is_ip( $part ) ) {
				return $part;
			}
		}
		return null;
	}

	/**
	 * The real client IP from a forwarding header, resistant to spoofing.
	 *
	 * A reverse proxy APPENDS the connecting IP to X-Forwarded-For, so the header
	 * arrives as `spoofed_by_client, ..., real_client`. Taking the FIRST token
	 * therefore trusts a value the visitor fully controls (they can prepend any
	 * IP, e.g. a Googlebot address, to be stamped "verified"). Instead walk
	 * right-to-left and return the first valid IP that is NOT one of our own
	 * trusted proxies: that is the address the trusted edge actually saw connect,
	 * which the client cannot forge.
	 *
	 * @param string $value          Forwarding-header value (comma-separated list).
	 * @param array  $trusted_ranges CIDR strings for our own trusted proxies.
	 * @return string|null The real client IP, or null if none found.
	 */
	public static function last_untrusted_ip( $value, array $trusted_ranges ) {
		$parts = array_map( 'trim', explode( ',', (string) $value ) );
		for ( $i = count( $parts ) - 1; $i >= 0; $i-- ) {
			$ip = $parts[ $i ];
			if ( ! self::is_ip( $ip ) ) {
				continue;
			}
			if ( self::ip_in_any_range( $ip, $trusted_ranges ) ) {
				continue; // One of our own proxies -> keep walking left.
			}
			return $ip;
		}
		return null;
	}

	/**
	 * Whether an IP falls inside any of the given CIDR ranges.
	 *
	 * @param string $ip     IP address.
	 * @param array  $ranges CIDR strings.
	 * @return bool True if the IP is in any range.
	 */
	public static function ip_in_any_range( $ip, array $ranges ) {
		foreach ( $ranges as $range ) {
			if ( self::ip_in_range( $ip, $range ) ) {
				return true;
			}
		}
		return false;
	}

	/**
	 * CIDR membership for IPv4 and IPv6.
	 *
	 * @param string $ip   IP address.
	 * @param string $cidr CIDR range (or a bare IP for an exact match).
	 * @return bool True if the IP is within the range.
	 */
	public static function ip_in_range( $ip, $cidr ) {
		if ( false === strpos( $cidr, '/' ) ) {
			return $ip === $cidr;
		}
		list( $subnet, $bits ) = explode( '/', $cidr, 2 );
		$bits                  = (int) $bits;

		$ip_bin     = @inet_pton( $ip ); // phpcs:ignore WordPress.PHP.NoSilencedErrors -- malformed input returns false, which is checked below.
		$subnet_bin = @inet_pton( $subnet ); // phpcs:ignore WordPress.PHP.NoSilencedErrors -- malformed input returns false, which is checked below.
		if ( false === $ip_bin || false === $subnet_bin || strlen( $ip_bin ) !== strlen( $subnet_bin ) ) {
			return false; // Mixed families or malformed.
		}

		$bytes = intdiv( $bits, 8 );
		$rem   = $bits % 8;
		if ( $bytes > 0 && 0 !== substr_compare( $ip_bin, $subnet_bin, 0, $bytes ) ) {
			return false;
		}
		if ( 0 === $rem ) {
			return true;
		}
		$mask = 0xff << ( 8 - $rem ) & 0xff;
		return ( ord( $ip_bin[ $bytes ] ) & $mask ) === ( ord( $subnet_bin[ $bytes ] ) & $mask );
	}

	/**
	 * Mask an IPv6 address to the given prefix length.
	 *
	 * @param string $ip   IPv6 address.
	 * @param int    $bits Prefix length to keep.
	 * @return string Masked address as CIDR, or '' if the input is invalid.
	 */
	private static function mask_v6( $ip, $bits ) {
		$bin = @inet_pton( $ip ); // phpcs:ignore WordPress.PHP.NoSilencedErrors -- malformed input returns false, which is checked below.
		if ( false === $bin ) {
			return '';
		}
		$bytes  = intdiv( $bits, 8 );
		$masked = substr( $bin, 0, $bytes ) . str_repeat( "\0", 16 - $bytes );
		return inet_ntop( $masked ) . '/' . $bits;
	}

	/**
	 * Map an HTTP header name to its $_SERVER key (e.g. CF-Connecting-IP -> HTTP_CF_CONNECTING_IP).
	 *
	 * @param string $header Header name.
	 * @return string The $_SERVER key, or '' if the header name is empty.
	 */
	private static function header_to_server_key( $header ) {
		$header = trim( (string) $header );
		if ( '' === $header ) {
			return '';
		}
		return 'HTTP_' . strtoupper( str_replace( '-', '_', $header ) );
	}

	/**
	 * Cloudflare's published edge ranges (v4 + v6). Bundled because they change
	 * rarely; the plugin can refresh them, but a stale list only ever causes a
	 * safe fallback to REMOTE_ADDR, never a spoof.
	 *
	 * @return array List of Cloudflare edge CIDR ranges (IPv4 + IPv6).
	 */
	public static function cloudflare_ranges() {
		return array(
			'173.245.48.0/20',
			'103.21.244.0/22',
			'103.22.200.0/22',
			'103.31.4.0/22',
			'141.101.64.0/18',
			'108.162.192.0/18',
			'190.93.240.0/20',
			'188.114.96.0/20',
			'197.234.240.0/22',
			'198.41.128.0/17',
			'162.158.0.0/15',
			'104.16.0.0/13',
			'104.24.0.0/14',
			'172.64.0.0/13',
			'131.0.72.0/22',
			'2400:cb00::/32',
			'2606:4700::/32',
			'2803:f800::/32',
			'2405:b500::/32',
			'2405:8100::/32',
			'2a06:98c0::/29',
			'2c0f:f248::/32',
		);
	}
}