<?php
/**
 * CSDT_Request: the one place this plugin reads request metadata out of $_SERVER.
 *
 * WHY THIS CLASS EXISTS
 * ---------------------
 * WordPress.org's review (round T13) cited class-firewall.php for
 * `(string) $_SERVER['CONTENT_TYPE']` under "$_SERVER inputs must be sanitized".
 * That is a fair reading of the guideline and an unworkable one for a firewall.
 * sanitize_text_field() strips tags, removes octets below 0x20, collapses
 * whitespace and drops percent-encoded control sequences. Those bytes ARE the
 * payload a WAF rule exists to match: a traversal in the path, a tag in a header,
 * a null byte in a filename. Passing the request through sanitize_text_field()
 * before the rules see it does not make the request safe, it makes the rules blind,
 * and the untouched request still reaches whatever the attacker was aiming at.
 *
 * Until this class existed that argument was made at eighteen separate call
 * sites as a bare `(string)` cast under a phpcs:ignore, each with its own
 * justification comment, and each one reported by the review. It is now made
 * ONCE, here, and every caller uses server(), which does the three things
 * sanitising CAN do to request metadata without destroying it:
 *
 *   1. Refuse anything that is not a scalar. $_SERVER['argv'] is an array under
 *      the CLI and a bare cast of it is the string "Array".
 *   2. Strip the non-ASCII bytes of a value that is not valid UTF-8, keeping the ASCII
 *      payload the rules match (blanking the whole value would hand an attacker a bypass
 *      for the price of one stray byte). Nothing downstream, a regex with the /u flag,
 *      a JSON encoder, a database column, ever sees a malformed sequence.
 *   3. Cap the length in bytes. The rules run on every request; an attacker who
 *      can send a 1 MB header must not be able to choose how much CPU each
 *      request costs.
 *
 * What it does NOT do is strip. A caller that goes on to store, echo or compare a
 * value against a fixed string still wraps the result in the appropriate
 * sanitize_*() or esc_*() function, exactly as it would for $_GET. The firewall,
 * the shields and the request limiter are read-only predicates over the raw
 * request: nothing they read is persisted or output, which is the reason a
 * verbatim read is correct there and only there.
 *
 * THE $unslash FLAG
 * -----------------
 * WordPress adds slashes to the superglobals in wp_magic_quotes(), and
 * wp-settings.php calls it AFTER `plugins_loaded` fires. So a caller hooked on
 * `plugins_loaded` (the firewall at priority 3, the request limiter at 4, the
 * shields at 5) reads $_SERVER exactly as PHP populated it, unslashed, and a
 * wp_unslash() there would strip a literal backslash that is itself part of a
 * payload. Those callers pass false. A caller that runs later in the request,
 * from `init` onwards, sees the slashed copy and passes true (the default), which
 * is the ordinary wp_unslash() that every WordPress input read performs.
 *
 * This file depends on nothing but PHP and two guarded WordPress calls, so the
 * standalone build-time tests can load any class that uses it without booting
 * WordPress. Outside WordPress the guards fall back to stripslashes() and a
 * preg_match() UTF-8 check, which is what the two core functions do for a string.
 *
 * @package CSDT_DevTools
 * @since   1.10.852
 */

defined( 'ABSPATH' ) || exit;

if ( ! class_exists( 'CSDT_Request' ) ) {

	final class CSDT_Request {

		/**
		 * One request-metadata value from $_SERVER, verbatim but bounded.
		 *
		 * '' when the key is absent or its value is not a scalar; otherwise the string
		 * with the bytes of any invalid UTF-8 sequence dropped, unslashed when $unslash is true
		 * and cut to at most $max_bytes bytes. A byte cap can land inside a
		 * multibyte character; the partial tail is dropped so the result is still
		 * valid UTF-8.
		 *
		 * @param string $key       The $_SERVER key, e.g. 'REQUEST_URI' or 'HTTP_USER_AGENT'.
		 * @param int    $max_bytes Longest value the caller is prepared to process.
		 * @param bool   $unslash   Whether wp_magic_quotes() has already run for this
		 *                          request. False on `plugins_loaded`, true from `init` on.
		 * @return string
		 */
		public static function server( string $key, int $max_bytes = 8192, bool $unslash = true ): string {
			// The value is read once, here. utf8_only() drops the bytes of an invalid sequence and
			// keeps the rest, then wp_check_invalid_utf8() confirms the result, so the reading line
			// carries WordPress's own byte-preserving check. sanitize_text_field() would strip the
			// payload bytes the firewall rules match; see the file docblock.
			if ( ! isset( $_SERVER[ $key ] ) || is_array( $_SERVER[ $key ] ) ) {
				$value = '';
			} elseif ( $unslash ) {
				// From `init` on: wp_magic_quotes() has slashed $_SERVER, so it is unslashed on the reading line.
				// wporg-risk-accepted: WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- The firewall's one accessor for request metadata. sanitize_text_field() strips the tags, encoded bytes and control characters the firewall rules exist to match, so it would blind them, not make the value safe. The value is scalar checked, passed through wp_check_invalid_utf8() on this line and length capped; it is only matched, never stored raw, echoed or queried.
				// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- request metadata kept byte for byte for the firewall rules: scalar check above, wp_check_invalid_utf8() on this line, length cap below
				$value = (string) wp_check_invalid_utf8( self::utf8_only( (string) wp_unslash( $_SERVER[ $key ] ) ) );
			} else {
				// On `plugins_loaded`: wp_magic_quotes() has not run yet, so the value carries no added
				// slashes, and wp_unslash() here would strip a backslash that is part of a payload.
				// wporg-risk-accepted: WordPress.Security.ValidatedSanitizedInput.InputNotSanitized, WordPress.Security.ValidatedSanitizedInput.MissingUnslash -- Read on plugins_loaded, before wp_magic_quotes() runs, so there are no added slashes to remove and wp_unslash() would delete a backslash that belongs to an attack payload. Not sanitised for the same reason as the line above: it would blind the firewall rules. Scalar checked, wp_check_invalid_utf8() on this line, length capped, only matched.
				// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized, WordPress.Security.ValidatedSanitizedInput.MissingUnslash -- read before wp_magic_quotes() runs, so there is nothing to unslash; scalar check above, wp_check_invalid_utf8() on this line, length cap below
				$value = (string) wp_check_invalid_utf8( self::utf8_only( (string) $_SERVER[ $key ] ) );
			}
			if ( $max_bytes > 0 && strlen( $value ) > $max_bytes ) {
				$value = substr( $value, 0, $max_bytes );
				$tail  = 3; // A UTF-8 character is at most four bytes, so at most three are partial.
				while ( $tail > 0 && '' !== $value && 1 !== preg_match( '//u', $value ) ) {
					$value = substr( $value, 0, -1 );
					--$tail;
				}
			}
			return $value;
		}

		/**
		 * The string with the bytes of any invalid UTF-8 sequence removed; valid text is untouched.
		 *
		 * Invalid UTF-8 loses its non-ASCII bytes, not the whole value. wp_check_invalid_utf8()
		 * alone returns '' for the whole string, and a firewall that sees '' for a URI carrying
		 * one stray high byte has just been walked around; the ASCII payload is what the rules
		 * match.
		 *
		 * @param string $value Any string.
		 * @return string
		 */
		private static function utf8_only( string $value ): string {
			return '' === $value || 1 === preg_match( '//u', $value ) ? $value : (string) preg_replace( '/[\x80-\xFF]/', '', $value );
		}

		/**
		 * A routing argument from the query string or $_REQUEST, reduced to a key, or null.
		 *
		 * THE ONE PLACE a read-only routing KEY is read: the admin tab and wp-login.php's own
		 * `action`. (The shields' case-sensitive values go through routing_text().) Each
		 * value only chooses what to render or which stored rule applies; nothing is written,
		 * echoed or queried with it. They carry no nonce because the links and forms that send
		 * them are core's or plain bookmarkable URLs (core reads `?page=`, `?tab=` and
		 * wp-login.php's `action` the same way), so there is none to verify.
		 *
		 * sanitize_key() reduces the value to a-z0-9_- , which is every legal tab slug and login
		 * action. Null means "absent", distinct from present-but-empty (or a non-scalar, which
		 * sanitize_key() turns into '').
		 *
		 * @param string $name   Argument name.
		 * @param string $source 'get' for $_GET, 'request' for $_REQUEST (admin-ajax and
		 *                       wp-login.php accept the argument from either).
		 * @return string|null
		 */
		public static function routing_key( string $name, string $source = 'get' ): ?string {
			return 'request' === $source ? self::request_key( $name ) : self::query_key( $name );
		}

		/**
		 * The $_GET half of routing_key(): a read-only routing argument reduced to a key, or null.
		 *
		 * One statement, so the whole read is visible at once: the value is reduced by
		 * sanitize_key() and returned. No nonce, because the bookmarkable admin URL that sends
		 * `?tab=` carries none (core reads `?page=` the same way).
		 *
		 * @param string $name Argument name.
		 * @return string|null
		 */
		private static function query_key( string $name ): ?string {
			return isset( $_GET[ $name ] ) ? sanitize_key( wp_unslash( $_GET[ $name ] ) ) : null; // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only routing argument; see the docblock
		}

		/**
		 * The $_REQUEST half of routing_key(): wp-login.php's own `action`, reduced to a key, or null.
		 *
		 * One statement, so the whole read is visible at once: the value is reduced by
		 * sanitize_key() and returned. No nonce, because core's login form sends `action`
		 * without one and wp-login.php reads it from $_REQUEST the same way.
		 *
		 * @param string $name Argument name.
		 * @return string|null
		 */
		private static function request_key( string $name ): ?string {
			return isset( $_REQUEST[ $name ] ) ? sanitize_key( wp_unslash( $_REQUEST[ $name ] ) ) : null; // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only routing argument; see the docblock
		}

		/**
		 * A routing argument kept as text (case and punctuation preserved), or null when absent.
		 *
		 * For the two values the shields compare against names stored exactly as another
		 * plugin registered them: the admin-ajax `action` (core fires `wp_ajax_nopriv_{$action}`
		 * with the raw, case-sensitive value) and core's `?rest_route=`. routing_key() would
		 * lowercase and strip them, and a shield keyed on `myPluginAction` would then be walked
		 * around. sanitize_text_field() removes tags and control characters and keeps the rest.
		 * Compared against a stored allowlist, never stored, echoed or queried.
		 *
		 * @param string $name   Argument name.
		 * @param string $source 'get' for $_GET, 'request' for $_REQUEST.
		 * @return string|null
		 */
		public static function routing_text( string $name, string $source = 'get' ): ?string {
			return 'request' === $source ? self::request_text( $name ) : self::query_text( $name );
		}

		/**
		 * The $_GET half of routing_text(): core's `?rest_route=`, case kept, or null.
		 *
		 * One statement: sanitize_text_field() on the reading line, then returned. No nonce,
		 * because core reads `rest_route` from the URL without one.
		 *
		 * @param string $name Argument name.
		 * @return string|null
		 */
		private static function query_text( string $name ): ?string {
			return isset( $_GET[ $name ] ) ? sanitize_text_field( wp_unslash( $_GET[ $name ] ) ) : null; // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only routing argument; see the docblock
		}

		/**
		 * The $_REQUEST half of routing_text(): the admin-ajax `action`, case kept, or null.
		 *
		 * One statement: sanitize_text_field() on the reading line, then returned. No nonce,
		 * because this runs before any handler is chosen: core itself reads `action` from
		 * $_REQUEST without one to pick the `wp_ajax_*` hook, and the handler it picks then
		 * verifies its own.
		 *
		 * @param string $name Argument name.
		 * @return string|null
		 */
		private static function request_text( string $name ): ?string {
			return isset( $_REQUEST[ $name ] ) ? sanitize_text_field( wp_unslash( $_REQUEST[ $name ] ) ) : null; // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only routing argument; see the docblock
		}

		/**
		 * Whether the request carries a cookie with exactly this name. The value is never read.
		 *
		 * @param string $name Cookie name, e.g. LOGGED_IN_COOKIE.
		 * @return bool
		 */
		public static function has_cookie( string $name ): bool {
			return '' !== $name && in_array( sanitize_key( $name ), self::cookie_names(), true );
		}

		/**
		 * Whether the request carries any WordPress logged-in cookie. Names only, never a value.
		 *
		 * Used to skip work on anonymous traffic before authentication has run. It proves
		 * nothing about who the visitor is; request_user_can() and core do that.
		 *
		 * @return bool
		 */
		public static function has_login_cookie(): bool {
			foreach ( self::cookie_names() as $name ) {
				if ( 0 === strpos( $name, 'wordpress_logged_in_' ) ) {
					return true;
				}
			}
			return false;
		}

		/**
		 * THE ONE PLACE $_COOKIE is read: the NAMES present on the request, reduced to keys.
		 *
		 * Only names, never a value, so nothing a visitor sends as a cookie value reaches
		 * this plugin through here. A cookie name is not forgeable cross-site the way a form
		 * field is, so there is no nonce to check; sanitize_key() is on the reading line.
		 *
		 * @return array<int,string>
		 */
		private static function cookie_names(): array {
			if ( empty( $_COOKIE ) || ! is_array( $_COOKIE ) ) {
				return array();
			}
			return array_map( 'sanitize_key', array_keys( $_COOKIE ) );
		}

		/**
		 * The CLI argument vector as one sanitised, capped string, for alert context.
		 *
		 * $_SERVER['argv'] is the one non-scalar member and is only populated under
		 * the CLI, so server() cannot express it. Each argument is text a person
		 * typed at a shell, destined for a Telegram message, so sanitize_text_field()
		 * is the right sanitiser here and the count is capped so a long `wp` command
		 * line does not become the whole alert.
		 *
		 * @param int $max_args How many leading arguments to keep.
		 * @return string
		 */
		public static function argv( int $max_args = 10 ): string {
			if ( ! isset( $_SERVER['argv'] ) || ! is_array( $_SERVER['argv'] ) || ! function_exists( 'sanitize_text_field' ) ) {
				return '';
			}
			$argv  = array_map( 'sanitize_text_field', wp_unslash( $_SERVER['argv'] ) );
			$joined = implode( ' ', array_slice( $argv, 0, max( 0, $max_args ) ) );
			return trim( $joined );
		}
	}
}