<?php
/**
 * Core: Centralized Security and Privacy Helpers
 *
 * This file contains static utility methods used throughout the plugin 
 * to enforce strict data sanitization, request verification, and privacy 
 * compliance (such as GDPR IP anonymization).
 *
 * @package    24TT_Unrestricted_Forms
 * @subpackage 24TT_Unrestricted_Forms/includes
 * @since      1.0.0
 * Contributors: 24techtime, johniouspatriot
 */

// SECURITY FIRST: Prevent Direct Access
// If a malicious bot attempts to access this file directly via the URL, abort.
if ( ! defined( 'ABSPATH' ) ) {
    exit( 'Direct script access denied.' );
}

/**
 * TT24_Security Class
 * A collection of static methods. Because they are static, we don't need to 
 * instantiate the class (e.g., new TT24_Security()), we can just call them 
 * directly anywhere in our plugin via TT24_Security::method_name().
 */
class TT24_Security {

    /**
     * Deep Array Sanitization
     * WordPress's default sanitize functions only handle strings. When saving 
     * complex JSON layout data or multi-select checkboxes, we need a function 
     * that can dive deep into arrays and clean every single value.
     *
     * @since 1.0.0
     * @param mixed $data The string or array to be sanitized.
     * @return mixed The fully sanitized string or array.
     */
    public static function sanitize_deep( $data ) {
        if ( is_array( $data ) ) {
            // If it's an array, map this exact function to every item inside it (Recursion)
            return array_map( array( __CLASS__, 'sanitize_deep' ), $data );
        } elseif ( is_scalar( $data ) ) {
            // If it's a standard string or number, sanitize it cleanly.
            // wp_unslash removes any escape quotes added by WordPress automatically, 
            // and sanitize_textarea_field cleans out malicious HTML/scripts while preserving line breaks.
            return sanitize_textarea_field( wp_unslash( $data ) );
        }
        
        // If it's neither (e.g., null), return an empty string safely.
        return '';
    }

    /**
     * IP Address Anonymizer (GDPR Compliance)
     * To truly respect the user and their website visitors, we should offer 
     * a way to anonymize IP addresses so they cannot be tracked to a specific household.
     * This function masks the last digits of an IPv4 or IPv6 address.
     *
     * @since 1.0.0
     * @param string $ip The raw IP address.
     * @return string The anonymized IP address.
     */
    public static function anonymize_ip( $ip ) {
        // Ensure the IP is a valid format first
        $ip = sanitize_text_field( wp_unslash( $ip ) );
        
        if ( empty( $ip ) || $ip === 'Unknown' ) {
            return 'Unknown';
        }

        // Anonymize IPv4 (e.g., 192.168.1.123 becomes 192.168.1.0)
        if ( filter_var( $ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4 ) ) {
            return preg_replace( '/(?<=\.)[^.]*$/', '0', $ip );
        }

        // Anonymize IPv6 (e.g., 2001:0db8:85a3:0000:0000:8a2e:0370:7334 becomes 2001:0db8:85a3:0000::)
        if ( filter_var( $ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6 ) ) {
            $ipv6_parts = explode( ':', $ip );
            if ( count( $ipv6_parts ) > 3 ) {
                // Keep the first 4 blocks, mask the rest
                $ip = implode( ':', array_slice( $ipv6_parts, 0, 4 ) ) . '::';
            }
        }

        return $ip;
    }

    /**
     * Unified Request Verifier
     * A handy wrapper that checks both the Nonce AND the User Capability 
     * at the same time, reducing code duplication in our AJAX endpoints.
     *
     * @since 1.0.0
     * @param string $nonce_action The name of the nonce action to verify.
     * @param string $nonce_name   (Optional) The key in $_REQUEST where the nonce is stored. Default is 'security'.
     * @param string $capability   (Optional) The capability required. Default is 'manage_tt24_forms'.
     * @return bool|void Returns true if secure, or automatically calls wp_send_json_error() if it fails.
     */
    public static function verify_admin_ajax( $nonce_action, $nonce_name = 'security', $capability = 'manage_tt24_forms' ) {
        // 1. Verify Nonce
        // FIX: Added sanitize_text_field( wp_unslash() ) around the nonce value per WP Review Team.
        if ( ! isset( $_REQUEST[ $nonce_name ] ) || ! wp_verify_nonce( sanitize_text_field( wp_unslash( $_REQUEST[ $nonce_name ] ) ), $nonce_action ) ) {
            wp_send_json_error( array( 'message' => esc_html__( 'Security token expired. Please refresh the page.', '24tt-unrestricted-forms' ) ) );
            exit; // Stop execution immediately
        }

        // 2. Verify Role/Capability
        if ( ! current_user_can( $capability ) ) {
            wp_send_json_error( array( 'message' => esc_html__( 'Insufficient permissions.', '24tt-unrestricted-forms' ) ) );
            exit; // Stop execution immediately
        }

        return true;
    }
}