wpbridge/includes/Security/Validator.php

<?php
/**
 * 输入校验
 *
 * @package WPBridge
 */

namespace WPBridge\Security;

// 防止直接访问
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

/**
 * 输入校验类
 */
class Validator {

    /**
     * 校验 URL
     *
     * @param string $url URL
     * @return bool
     */
    public static function is_valid_url( string $url ): bool {
        if ( empty( $url ) ) {
            return false;
        }

        // 基本格式校验
        if ( ! filter_var( $url, FILTER_VALIDATE_URL ) ) {
            return false;
        }

        // 只允许 http 和 https
        $scheme = parse_url( $url, PHP_URL_SCHEME );
        if ( ! in_array( $scheme, [ 'http', 'https' ], true ) ) {
            return false;
        }

        // 检查是否有主机名
        $host = parse_url( $url, PHP_URL_HOST );
        if ( empty( $host ) ) {
            return false;
        }

        // 禁止本地地址（安全考虑）
        if ( self::is_local_address( $host ) ) {
            return false;
        }

        return true;
    }

    /**
     * 检查是否是本地地址
     *
     * @param string $host 主机名
     * @return bool
     */
    private static function is_local_address( string $host ): bool {
        // 本地主机名
        $local_hosts = [ 'localhost', '127.0.0.1', '::1' ];

        if ( in_array( $host, $local_hosts, true ) ) {
            return true;
        }

        // 私有 IP 范围
        $ip = gethostbyname( $host );

        if ( $ip === $host ) {
            // 无法解析，为安全起见视为本地地址
            return true;
        }

        // 检查私有 IP 范围（IPv4）
        $private_ranges = [
            '10.0.0.0/8',
            '172.16.0.0/12',
            '192.168.0.0/16',
            '127.0.0.0/8',
        ];

        foreach ( $private_ranges as $range ) {
            if ( self::ip_in_range( $ip, $range ) ) {
                return true;
            }
        }

        // 检查 IPv6 私有地址
        if ( filter_var( $ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6 ) ) {
            // fc00::/7 (Unique Local Addresses)
            // fe80::/10 (Link-Local Addresses)
            if ( preg_match( '/^(fc|fd|fe80)/i', $ip ) ) {
                return true;
            }
        }

        return false;
    }

    /**
     * 检查 IP 是否在范围内
     *
     * @param string $ip    IP 地址
     * @param string $range CIDR 范围
     * @return bool
     */
    private static function ip_in_range( string $ip, string $range ): bool {
        list( $subnet, $bits ) = explode( '/', $range );

        $ip_long     = ip2long( $ip );
        $subnet_long = ip2long( $subnet );
        $mask        = -1 << ( 32 - (int) $bits );

        return ( $ip_long & $mask ) === ( $subnet_long & $mask );
    }

    /**
     * 校验版本号
     *
     * @param string $version 版本号
     * @return bool
     */
    public static function is_valid_version( string $version ): bool {
        if ( empty( $version ) ) {
            return false;
        }

        // 支持语义化版本和 WordPress 风格版本
        // 例如: 1.0.0, 1.0, 1.0.0-beta, 1.0.0-rc.1
        $pattern = '/^[0-9]+(\.[0-9]+)*(-[a-zA-Z0-9]+(\.[a-zA-Z0-9]+)*)?$/';

        return (bool) preg_match( $pattern, $version );
    }

    /**
     * 校验 slug
     *
     * @param string $slug Slug
     * @return bool
     */
    public static function is_valid_slug( string $slug ): bool {
        if ( empty( $slug ) ) {
            return true; // 空 slug 是允许的（表示匹配所有）
        }

        // 只允许小写字母、数字、连字符
        $pattern = '/^[a-z0-9-]+$/';

        return (bool) preg_match( $pattern, $slug );
    }

    /**
     * 校验 JSON 响应结构
     *
     * @param array $data     数据
     * @param array $required 必需字段
     * @return array 错误数组
     */
    public static function validate_json_structure( array $data, array $required ): array {
        $errors = [];

        foreach ( $required as $field ) {
            if ( ! isset( $data[ $field ] ) ) {
                $errors[] = sprintf( __( '缺少必需字段: %s', 'wpbridge' ), $field );
            }
        }

        return $errors;
    }

    /**
     * 校验更新信息 JSON
     *
     * @param array $data 数据
     * @return array 错误数组
     */
    public static function validate_update_info( array $data ): array {
        $errors = [];

        // 必需字段
        if ( empty( $data['version'] ) ) {
            $errors[] = __( '缺少版本号', 'wpbridge' );
        } elseif ( ! self::is_valid_version( $data['version'] ) ) {
            $errors[] = __( '无效的版本号格式', 'wpbridge' );
        }

        // 下载 URL
        $download_url = $data['download_url'] ?? $data['package'] ?? '';
        if ( ! empty( $download_url ) && ! self::is_valid_url( $download_url ) ) {
            $errors[] = __( '无效的下载 URL', 'wpbridge' );
        }

        return $errors;
    }

    /**
     * 清理 HTML
     *
     * @param string $html HTML 内容
     * @return string
     */
    public static function sanitize_html( string $html ): string {
        return wp_kses_post( $html );
    }

    /**
     * 清理文本
     *
     * @param string $text 文本
     * @return string
     */
    public static function sanitize_text( string $text ): string {
        return sanitize_text_field( $text );
    }

    /**
     * 清理 URL
     *
     * @param string $url URL
     * @return string
     */
    public static function sanitize_url( string $url ): string {
        return esc_url_raw( $url );
    }
}