<?php
/**
 * Input sanitization helpers.
 *
 * @package Shiftora\Support
 */

declare(strict_types=1);

namespace Shiftora\Support;

// Prevent direct file access.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Sanitization utility for Shiftora inputs.
 */
final class Sanitizer {

	/** Sanitizes a URL for API use; returns '' unless it is an absolute http(s) URL, without a trailing slash. */
	public static function url( string $url ): string {
		$clean = esc_url_raw( trim( $url ) );

		// Must be an absolute HTTP(S) URL.
		if ( '' === $clean || ! in_array( wp_parse_url( $clean, PHP_URL_SCHEME ), [ 'http', 'https' ], true ) ) {
			return '';
		}

		// Strip trailing slash for consistent comparison.
		return rtrim( $clean, '/' );
	}

	/** Sanitizes a short label (connection name, backup label) to 255 characters. */
	public static function label( string $label ): string {
		return substr( sanitize_text_field( $label ), 0, 255 );
	}

	/** Sanitizes a single-line text field. */
	public static function text( string $value ): string {
		return sanitize_text_field( $value );
	}

	/**
	 * Validates that a URL is safe for outbound server-side requests.
	 *
	 * The only hard block is a public site connecting to a local or private
	 * target. IP resolution is unreliable in containerized stacks, and every
	 * request is token-authenticated anyway. SHIFTORA_ALLOW_PRIVATE_IPS overrides.
	 *
	 * @param string $url A URL already passed through self::url().
	 * @return string|null The URL, or null when the request should be blocked.
	 */
	public static function safe_remote_url( string $url ): ?string {
		if ( '' === $url ) {
			return null;
		}

		$parsed = wp_parse_url( $url );
		$host   = isset( $parsed['host'] ) ? strtolower( (string) $parsed['host'] ) : '';

		if ( '' === $host ) {
			return null;
		}

		// Explicit override, for VPN or tunnel setups.
		if ( defined( 'SHIFTORA_ALLOW_PRIVATE_IPS' ) && SHIFTORA_ALLOW_PRIVATE_IPS ) {
			return $url;
		}

		// Same hostname is always allowed; self-connections are rejected elsewhere.
		$local_host = strtolower( (string) wp_parse_url( get_site_url(), PHP_URL_HOST ) );
		if ( $host === $local_host ) {
			return $url;
		}

		// A local site can reach the internet, but not the other way round.
		if ( self::is_local_site() ) {
			return $url;
		}

		// A public server cannot reach a localhost or private target.
		if ( self::is_local_host( $host ) ) {
			return null;
		}

		if ( self::hostname_resolves_to_private_address( $host ) ) {
			return null;
		}

		return $url;
	}

	/** Whether this WordPress site is running in a local or development environment. */
	private static function is_local_site(): bool {
		if ( function_exists( 'wp_get_environment_type' ) ) {
			$env = wp_get_environment_type();
			if ( in_array( $env, [ 'local', 'development' ], true ) ) {
				return true;
			}
		}

		$site_url = get_site_url();
		$host     = strtolower( (string) wp_parse_url( $site_url, PHP_URL_HOST ) );

		// Literal loopback.
		if ( in_array( $host, [ 'localhost', '127.0.0.1', '::1' ], true ) ) {
			return true;
		}

		// Common local-development TLDs.
		$local_tlds = [ '.local', '.test', '.localhost', '.dev', '.ddev.site', '.lndo.site' ];
		foreach ( $local_tlds as $tld ) {
			if ( str_ends_with( $host, $tld ) ) {
				return true;
			}
		}

		// Server interface is loopback.
		$server_addr = ServerVars::server_addr();
		if ( in_array( $server_addr, [ '127.0.0.1', '::1' ], true ) ) {
			return true;
		}

		return false;
	}

	/** String-only check for a local or private host; no DNS, so it behaves the same in Docker and LocalWP. */
	private static function is_local_host( string $host ): bool {
		// Literal loopback names.
		if ( in_array( $host, [ 'localhost', '127.0.0.1', '::1' ], true ) ) {
			return true;
		}

		// Private IPv4 ranges.
		if ( self::is_private_ip( $host ) ) {
			return true;
		}

		// Common local-development TLDs.
		$local_tlds = [ '.local', '.test', '.localhost', '.dev', '.ddev.site', '.lndo.site' ];
		foreach ( $local_tlds as $tld ) {
			if ( str_ends_with( $host, $tld ) ) {
				return true;
			}
		}

		return false;
	}

	/** Whether a string is a private or reserved IPv4 or IPv6 address. */
	private static function is_private_ip( string $host ): bool {
		if ( ! filter_var( $host, FILTER_VALIDATE_IP ) ) {
			return false;
		}

		// 10.0.0.0/8
		if ( str_starts_with( $host, '10.' ) ) {
			return true;
		}

		// 172.16.0.0/12
		if ( str_starts_with( $host, '172.' ) ) {
			$parts = explode( '.', $host );
			$second = (int) ( $parts[1] ?? 0 );
			if ( $second >= 16 && $second <= 31 ) {
				return true;
			}
		}

		// 192.168.0.0/16
		if ( str_starts_with( $host, '192.168.' ) ) {
			return true;
		}

		// 127.0.0.0/8
		if ( str_starts_with( $host, '127.' ) ) {
			return true;
		}

		// ::1
		if ( $host === '::1' ) {
			return true;
		}

		// fc00::/7 (unique local addresses)
		if ( str_starts_with( $host, 'fc' ) || str_starts_with( $host, 'fd' ) ) {
			return true;
		}

		// Let filter_var catch any other private/reserved ranges.
		return filter_var( $host, FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE ) === false;
	}

	private static function hostname_resolves_to_private_address( string $host ): bool {
		if ( filter_var( $host, FILTER_VALIDATE_IP ) ) {
			return self::is_private_ip( $host );
		}

		$addresses = [];
		if ( function_exists( 'dns_get_record' ) ) {
			$records = @dns_get_record( $host, DNS_A + DNS_AAAA ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- Resolves the host for the SSRF guard; a failed lookup returns false and is handled below.
			if ( is_array( $records ) ) {
				foreach ( $records as $record ) {
					if ( ! empty( $record['ip'] ) ) {
						$addresses[] = (string) $record['ip'];
					}
					if ( ! empty( $record['ipv6'] ) ) {
						$addresses[] = (string) $record['ipv6'];
					}
				}
			}
		}

		if ( empty( $addresses ) && function_exists( 'gethostbynamel' ) ) {
			$resolved = @gethostbynamel( $host ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- Fallback resolver for the same SSRF guard; a failed lookup returns false and is handled below.
			if ( is_array( $resolved ) ) {
				$addresses = array_merge( $addresses, $resolved );
			}
		}

		foreach ( array_unique( $addresses ) as $address ) {
			if ( self::is_private_ip( strtolower( $address ) ) ) {
				return true;
			}
		}

		return false;
	}

	/**
	 * Normalizes a URL for self-connection comparison: ignores scheme and a www.
	 * prefix, drops default ports, lowercases the host and trims the trailing slash.
	 */
	public static function normalize_url_for_comparison( string $url ): string {
		$parsed = wp_parse_url( rtrim( $url, '/' ) );
		if ( ! is_array( $parsed ) ) {
			return strtolower( rtrim( $url, '/' ) );
		}

		$scheme = isset( $parsed['scheme'] ) ? strtolower( $parsed['scheme'] ) : 'https';
		$host   = isset( $parsed['host'] ) ? strtolower( $parsed['host'] ) : '';

		// Strip leading www.
		if ( str_starts_with( $host, 'www.' ) ) {
			$host = substr( $host, 4 );
		}

		$port    = isset( $parsed['port'] ) ? (int) $parsed['port'] : null;
		$default = ( 'https' === $scheme ) ? 443 : 80;
		if ( $port === $default ) {
			$port = null;
		}

		$path  = isset( $parsed['path'] ) ? rtrim( $parsed['path'], '/' ) : '';
		$query = isset( $parsed['query'] ) ? '?' . $parsed['query'] : '';

		$host_part = $host . ( null !== $port ? ':' . $port : '' );

		return $host_part . $path . $query;
	}

	/** Sanitizes a non-negative integer. */
	public static function int( mixed $value ): int {
		return absint( $value );
	}

	/** Sanitizes a boolean-ish value from user input. */
	public static function bool( mixed $value ): bool {
		return filter_var( $value, FILTER_VALIDATE_BOOLEAN );
	}

	/**
	 * Sanitizes a list of table names.
	 *
	 * @return array<int, string>
	 */
	public static function table_names( array $tables ): array {
		$clean = [];

		foreach ( $tables as $table ) {
			$sanitized = sanitize_key( (string) $table );
			if ( '' !== $sanitized ) {
				$clean[] = $sanitized;
			}
		}

		return array_unique( $clean );
	}
}