<?php
if (!defined('ABSPATH')) exit;

/**
 * Small security helpers for AI Webmaster Studio admin screens.
 *
 * This class is intentionally lightweight: it centralizes repetitive WordPress
 * request handling rules without changing existing module behavior.
 */
class AIWEST_Security {
    // Request accessors are deliberately nonce-agnostic. Mutating callers must verify their action nonce first.
    // phpcs:disable WordPress.Security.NonceVerification.Missing, WordPress.Security.NonceVerification.Recommended
    public static function is_post_request() {
        $method = isset($_SERVER['REQUEST_METHOD']) ? sanitize_key(wp_unslash($_SERVER['REQUEST_METHOD'])) : '';
        return $method === 'post';
    }

    public static function current_user_can_manage() {
        return is_admin() && current_user_can('manage_options');
    }

    public static function get_key($key, $default = '') {
        if (!isset($_GET[$key])) return $default;
        return sanitize_key(wp_unslash($_GET[$key]));
    }

    public static function get_text($key, $default = '') {
        if (!isset($_GET[$key])) return $default;
        return sanitize_text_field(wp_unslash($_GET[$key]));
    }

    public static function request_uri() {
        return isset($_SERVER['REQUEST_URI']) ? esc_url_raw(wp_unslash($_SERVER['REQUEST_URI'])) : '';
    }

    public static function remote_address() {
        $address = isset($_SERVER['REMOTE_ADDR']) ? sanitize_text_field(wp_unslash($_SERVER['REMOTE_ADDR'])) : '';
        return filter_var($address, FILTER_VALIDATE_IP) ? $address : '0.0.0.0';
    }

    public static function post_key($key, $default = '') {
        if (!isset($_POST[$key])) return $default;
        return sanitize_key(wp_unslash($_POST[$key]));
    }

    public static function post_text($key, $default = '') {
        if (!isset($_POST[$key])) return $default;
        return sanitize_text_field(wp_unslash($_POST[$key]));
    }

    public static function post_textarea($key, $default = '') {
        if (!isset($_POST[$key])) return $default;
        return sanitize_textarea_field(wp_unslash($_POST[$key]));
    }

    public static function post_html($key, $default = '') {
        if (!isset($_POST[$key])) return $default;
        return wp_kses_post(wp_unslash($_POST[$key]));
    }

    public static function post_url($key, $default = '') {
        if (!isset($_POST[$key])) return esc_url_raw($default);
        return esc_url_raw(wp_unslash($_POST[$key]));
    }

    public static function post_float($key, $default = 0.0) {
        if (!isset($_POST[$key])) return (float) $default;
        return (float) sanitize_text_field(wp_unslash($_POST[$key]));
    }

    public static function post_int($key, $default = 0) {
        if (!isset($_POST[$key])) return absint($default);
        return absint(wp_unslash($_POST[$key]));
    }

    public static function post_bool($key) {
        return !empty($_POST[$key]);
    }

    public static function post_has($key) {
        return isset($_POST[$key]);
    }

    public static function post_array($key) {
        if (!isset($_POST[$key]) || !is_array($_POST[$key])) return [];
        // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- Typed callers sanitize each array element for its destination context.
        return wp_unslash($_POST[$key]);
    }

    /**
     * Return the five upload fields expected by wp_handle_upload().
     * The calling admin action remains responsible for capability and nonce checks.
     */
    public static function uploaded_file($key) {
        // phpcs:ignore WordPress.Security.NonceVerification.Missing -- Generic accessor; callers verify the action nonce before invoking it.
        if (!isset($_FILES[$key]) || !is_array($_FILES[$key])) return [];
        // phpcs:ignore WordPress.Security.NonceVerification.Missing, WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- Upload metadata is sanitized field by field below; tmp_name must remain usable by wp_handle_upload().
        $file = wp_unslash($_FILES[$key]);

        return [
            'name'     => sanitize_file_name($file['name'] ?? ''),
            'type'     => sanitize_mime_type($file['type'] ?? ''),
            'tmp_name' => sanitize_text_field($file['tmp_name'] ?? ''),
            'error'    => absint($file['error'] ?? UPLOAD_ERR_NO_FILE),
            'size'     => absint($file['size'] ?? 0),
        ];
    }

    public static function allowed_post_status($value, $default = 'draft', $allow_publish = true) {
        $value = sanitize_key($value);
        $allowed = $allow_publish ? ['draft', 'pending', 'private', 'publish'] : ['draft', 'pending', 'private'];
        return in_array($value, $allowed, true) ? $value : $default;
    }

    public static function aiwest_admin_page_slug($default = 'aiwest-dashboard') {
        $page = self::get_key('page', $default);
        return strpos($page, 'aiwest-') === 0 ? $page : $default;
    }

    public static function safe_referer_or_admin_page($fallback_page = 'aiwest-dashboard') {
        $referer = wp_get_referer();
        if ($referer && wp_validate_redirect($referer, false)) {
            return $referer;
        }
        return admin_url('admin.php?page=' . self::aiwest_admin_page_slug($fallback_page));
    }

    // phpcs:enable WordPress.Security.NonceVerification.Missing, WordPress.Security.NonceVerification.Recommended
}