<?php
/**
 * @package PlugixaCrm
 */

declare( strict_types = 1 );

namespace PlugixaCrm\Core\Http;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Where this site is allowed to send an outbound request.
 *
 * AN OUTBOUND REQUEST THE ADMINISTRATOR CONFIGURED IS SERVER-SIDE REQUEST FORGERY WITH PERMISSION.
 * That is unremarkable when the destination is a partner's API and much less so when it is
 * `http://169.254.169.254/latest/meta-data/` — the cloud metadata endpoint that hands out instance
 * credentials to anything on the box that asks. The site's own network position is the asset: the
 * CRM can reach things the administrator's browser cannot, and any configurable destination is a way
 * to borrow that reach.
 *
 * IT IS ITS OWN CLASS BECAUSE SEVERAL CALLERS NEED THE SAME ANSWER AT DIFFERENT TIMES. A service
 * asks when the URL is typed, so the administrator gets a refusal they can act on; the sender asks
 * again before every request, because DNS is not a promise — a hostname that resolved publicly on
 * Monday can resolve to 127.0.0.1 on Tuesday, and only the check at send time sees that.
 *
 * IT LIVES IN CORE because `Core\Integrations\HttpClient` needs exactly this answer, and
 * `CoreIndependenceTest` forbids Core from naming a module — correctly, because Core is
 * infrastructure a module depends on, never the reverse. Its own guidance for this case is the one
 * followed here: *"If Core needs something a module has, the something belongs in Core."* Duplicating
 * it would have left two SSRF guards free to drift apart, which is the worst of the options.
 */
final class DestinationGuard {

	/**
	 * Whether a URL may be posted to.
	 *
	 * The check is on the RESOLVED ADDRESS, not on the hostname. A name its owner controls can point
	 * anywhere, so `internal.example.com` and `127.0.0.1` are the same destination wearing different
	 * spellings, and a string comparison sees only one of them.
	 *
	 * @param string $url The destination.
	 */
	public function allows( string $url ): bool {
		$parts = wp_parse_url( $url );

		$scheme = strtolower( (string) ( $parts['scheme'] ?? '' ) );
		$host   = (string) ( $parts['host'] ?? '' );

		if ( ! in_array( $scheme, array( 'http', 'https' ), true ) || '' === $host ) {
			return $this->filtered( false, $url, '' );
		}

		$literal = false !== filter_var( $host, FILTER_VALIDATE_IP );
		$ip      = $literal ? $host : gethostbyname( $host );

		// gethostbyname() hands the hostname back unchanged when it cannot resolve. A destination that
		// does not resolve is not one to post a signed payload to.
		if ( ! $literal && $ip === $host ) {
			return $this->filtered( false, $url, '' );
		}

		$public = filter_var(
			$ip,
			FILTER_VALIDATE_IP,
			FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE
		);

		return $this->filtered( false !== $public, $url, (string) $ip );
	}

	/**
	 * @param bool   $allowed What the checks decided.
	 * @param string $url     The destination.
	 * @param string $ip      What the host resolved to, empty when it did not.
	 */
	private function filtered( bool $allowed, string $url, string $ip ): bool {
		/**
		 * Filters whether an outbound destination is allowed.
		 *
		 * The escape hatch for a site whose integration genuinely lives on the same private network —
		 * a staging box, an internal queue, a container on the same host. It is a filter rather than a
		 * setting because a setting is a checkbox somebody ticks to make an error message go away,
		 * without ever reading what the check was for.
		 *
		 * @param bool   $allowed Whether the destination passed the checks.
		 * @param string $url     The destination.
		 * @param string $ip      What the host resolved to, empty when it did not resolve.
		 */
		$allowed = (bool) apply_filters( 'plugixa_crm_outbound_destination_allowed', $allowed, $url, $ip );

		/**
		 * Legacy name, kept because it is a public seam a site may already be using.
		 *
		 * Until this class moved into Core it guarded webhooks and nothing else, so this filter was
		 * global in practice — a site that hooked it to reach a staging box was allowing every
		 * outbound request the CRM made. Applying it last preserves that exactly, rather than
		 * silently narrowing a hatch somebody is relying on. New code should hook the filter above.
		 *
		 * @param bool   $allowed Whether the destination passed the checks.
		 * @param string $url     The destination.
		 * @param string $ip      What the host resolved to, empty when it did not resolve.
		 */
		return (bool) apply_filters( 'plugixa_crm_webhook_destination_allowed', $allowed, $url, $ip );
	}
}