<?php
/**
 * Identifies a shopper across requests with a first-party cookie.
 *
 * @package Fitzaro
 */

namespace Fitzaro\Api;

defined( 'ABSPATH' ) || exit;

/**
 * Decision 2026-10-28: guests are recognised by an HttpOnly, SameSite=Lax session cookie holding a
 * random secret. The database stores only an HMAC of it, so a leaked table cannot be replayed as
 * cookies. The cookie is set only when the shopper uploads a photo, i.e. when they use the feature.
 */
final class Visitor {

	public const COOKIE = 'fitzaro_visitor';

	/**
	 * A fresh random cookie value.
	 */
	public static function new_value(): string {
		return bin2hex( random_bytes( 32 ) );
	}

	/**
	 * Whether a cookie value has the shape new_value() produces.
	 *
	 * @param string $value Cookie value.
	 */
	public static function is_valid_value( string $value ): bool {
		return 1 === preg_match( '/\A[a-f0-9]{64}\z/', $value );
	}

	/**
	 * Keyed hash of a cookie value, as stored in visitor_hash.
	 *
	 * @param string $value Cookie value.
	 * @param string $key   Site secret.
	 */
	public static function hash( string $value, string $key ): string {
		return hash_hmac( 'sha256', $value, $key );
	}

	/**
	 * What limits are counted by for an IP: the address for IPv4, the /64 network for IPv6.
	 * '' for anything that is not a valid address.
	 *
	 * @param string $ip IP address.
	 */
	public static function ip_key( string $ip ): string {
		if ( false !== filter_var( $ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4 ) ) {
			return $ip;
		}

		if ( false === filter_var( $ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6 ) ) {
			return '';
		}

		$packed = inet_pton( $ip );

		return false === $packed ? '' : bin2hex( substr( $packed, 0, 8 ) ) . '::/64';
	}

	/**
	 * Keyed hash of the client's IP (or network), or '' when unknown. Only the hash is stored.
	 *
	 * Uses REMOTE_ADDR: forwarding headers can be forged by anyone. Sites behind a proxy or CDN
	 * pass the real client address through the `fitzaro/client_ip` filter.
	 */
	public static function ip_hash(): string {
		$remote = isset( $_SERVER['REMOTE_ADDR'] ) ? sanitize_text_field( wp_unslash( $_SERVER['REMOTE_ADDR'] ) ) : '';

		/**
		 * Filters the client IP address used for try-on limits.
		 *
		 * @since 1.0.0
		 *
		 * @param string $remote REMOTE_ADDR.
		 */
		$key = self::ip_key( self::text( apply_filters( 'fitzaro/client_ip', $remote ) ) );

		return '' === $key ? '' : self::hash( 'ip|' . $key, self::key() );
	}

	/**
	 * Hash of the current visitor, or '' when they have no valid cookie.
	 */
	public static function current(): string {
		$value = isset( $_COOKIE[ self::COOKIE ] ) ? sanitize_text_field( wp_unslash( $_COOKIE[ self::COOKIE ] ) ) : '';

		return self::is_valid_value( $value ) ? self::hash( $value, self::key() ) : '';
	}

	/**
	 * Hash of the current visitor, setting the cookie first when there is none.
	 */
	public static function ensure(): string {
		$current = self::current();
		if ( '' !== $current ) {
			return $current;
		}

		$value = self::new_value();
		setcookie(
			self::COOKIE,
			$value,
			array(
				'expires'  => 0,
				'path'     => defined( 'COOKIEPATH' ) && constant( 'COOKIEPATH' ) ? (string) constant( 'COOKIEPATH' ) : '/',
				'domain'   => defined( 'COOKIE_DOMAIN' ) && constant( 'COOKIE_DOMAIN' ) ? (string) constant( 'COOKIE_DOMAIN' ) : '',
				'secure'   => is_ssl(),
				'httponly' => true,
				'samesite' => 'Lax',
			)
		);
		$_COOKIE[ self::COOKIE ] = $value;

		return self::hash( $value, self::key() );
	}

	/**
	 * A filter result as trimmed text; anything else is ''. Filters can return any type.
	 *
	 * @param mixed $value Filter result.
	 */
	private static function text( $value ): string {
		return is_string( $value ) ? trim( $value ) : '';
	}

	/**
	 * Hash key, derived from the site's auth salt.
	 */
	private static function key(): string {
		return hash_hmac( 'sha256', 'fitzaro-visitor', wp_salt( 'auth' ) );
	}
}