<?php
/**
 * WordPress Coding Standard.
 *
 * @package WPCS\WordPressCodingStandards
 * @link    https://github.com/WordPress/WordPress-Coding-Standards
 * @license https://opensource.org/licenses/MIT MIT
 */

namespace WordPressCS\WordPress\Sniffs\Security;

use PHPCSUtils\Tokens\Collections;
use PHPCSUtils\Utils\Conditions;
use PHPCSUtils\Utils\Context;
use PHPCSUtils\Utils\Lists;
use PHPCSUtils\Utils\MessageHelper;
use PHPCSUtils\Utils\Scopes;
use WordPressCS\WordPress\Helpers\ContextHelper;
use WordPressCS\WordPress\Helpers\RulesetPropertyHelper;
use WordPressCS\WordPress\Helpers\SanitizationHelperTrait;
use WordPressCS\WordPress\Helpers\UnslashingFunctionsHelper;
use WordPressCS\WordPress\Helpers\VariableHelper;
use WordPressCS\WordPress\Sniff;

/**
 * Checks that nonce verification accompanies form processing.
 *
 * @link https://developer.wordpress.org/plugins/security/nonces/ Nonces on Plugin Developer Handbook
 *
 * @since 0.5.0
 * @since 0.13.0 Class name changed: this class is now namespaced.
 * @since 1.0.0  This sniff has been moved from the `CSRF` category to the `Security` category.
 * @since 3.0.0  This sniff has received significant updates to its logic and structure.
 *
 * @uses \WordPressCS\WordPress\Helpers\SanitizationHelperTrait::$customSanitizingFunctions
 * @uses \WordPressCS\WordPress\Helpers\SanitizationHelperTrait::$customUnslashingSanitizingFunctions
 */
class NonceVerificationSniff extends Sniff {

	use SanitizationHelperTrait;

	/**
	 * Superglobals to notify about when not accompanied by an nonce check.
	 *
	 * A value of `true` results in an error. A value of `false` in a warning.
	 *
	 * @since 0.12.0
	 *
	 * @var array
	 */
	protected $superglobals = array(
		'$_POST'    => true,
		'$_FILES'   => true,
		'$_GET'     => false,
		'$_REQUEST' => false,
	);

	/**
	 * Custom list of functions which verify nonces.
	 *
	 * @since 0.5.0
	 *
	 * @var string[]
	 */
	public $customNonceVerificationFunctions = array();

	/**
	 * List of the functions which verify nonces.
	 *
	 * @since 0.5.0
	 * @since 0.11.0 Changed from public static to protected non-static.
	 * @since 3.0.0  - Moved from the generic `Sniff` class to this class.
	 *               - Visibility changed from `protected` to `private.
	 *
	 * @var array
	 */
	private $nonceVerificationFunctions = array(
		'wp_verify_nonce'     => true,
		'check_admin_referer' => true,
		'check_ajax_referer'  => true,
	);

	/**
	 * Cache of previously added custom functions.
	 *
	 * Prevents having to do the same merges over and over again.
	 *
	 * @since 0.5.0
	 * @since 0.11.0 - Changed from public static to protected non-static.
	 *               - Changed the format from simple bool to array.
	 * @since 3.0.0  - Property rename from `$addedCustomFunctions` to `$addedCustomNonceFunctions`.
	 *               - Visibility changed from `protected` to `private.
	 *               - Format changed from a multi-dimensional array to a single-dimensional array.
	 *
	 * @var array
	 */
	private $addedCustomNonceFunctions = array();

	/**
	 * Information on the all scopes that were checked to find a nonce verification in a particular file.
	 *
	 * The array will be in the following format:
	 * ```
	 * array(
	 *   'file'  => (string) The name of the file.
	 *   'cache' => (array) array(
	 *     # => array(             The key is the token pointer to the "start" position.
	 *       'end'   => (int)      The token pointer to the "end" position.
	 *       'nonce' => (int|bool) The token pointer where n nonce check
	 *                             was found, or false if none was found.
	 *     )
	 *   )
	 * )
	 * ```
	 *
	 * @since 3.0.0
	 *
	 * @var array<string, mixed>
	 */
	private $cached_results;

	/**
	 * Returns an array of tokens this test wants to listen for.
	 *
	 * @return array
	 */
	public function register() {
		$targets  = array( \T_VARIABLE => \T_VARIABLE );
		$targets += Collections::listOpenTokensBC(); // We need to skip over lists.

		return $targets;
	}

	/**
	 * Processes this test, when one of its tokens is encountered.
	 *
	 * @param int $stackPtr The position of the current token in the stack.
	 *
	 * @return int|void Integer stack pointer to skip forward or void to continue
	 *                  normal file processing.
	 */
	public function process_token( $stackPtr ) {
		// Skip over lists as whatever is in those will always be assignments.
		if ( isset( Collections::listOpenTokensBC()[ $this->tokens[ $stackPtr ]['code'] ] ) ) {
			$open_close = Lists::getOpenClose( $this->phpcsFile, $stackPtr );
			$skip_to    = $stackPtr;
			if ( false !== $open_close ) {
				$skip_to = $open_close['closer'];
			}

			return $skip_to;
		}

		if ( ! isset( $this->superglobals[ $this->tokens[ $stackPtr ]['content'] ] ) ) {
			return;
		}

		if ( Scopes::isOOProperty( $this->phpcsFile, $stackPtr ) ) {
			// Property with the same name as a superglobal. Not our target.
			return;
		}

		// Determine the cache keys for this item.
		$cache_keys = array(
			'file'  => $this->phpcsFile->getFilename(),
			'start' => 0,
			'end'   => $stackPtr,
		);

		// If we're in a function, only look inside of it.
		// This doesn't take arrow functions into account as those are "open".
		$functionPtr = Conditions::getLastCondition( $this->phpcsFile, $stackPtr, array( \T_FUNCTION, \T_CLOSURE ) );
		if ( false !== $functionPtr ) {
			$cache_keys['start'] = $this->tokens[ $functionPtr ]['scope_opener'];
		}

		$this->mergeFunctionLists();

		$needs_nonce = $this->needs_nonce_check( $stackPtr, $cache_keys );
		if ( false === $needs_nonce ) {
			return;
		}

		if ( $this->has_nonce_check( $stackPtr, $cache_keys, ( 'after' === $needs_nonce ) ) ) {
			return;
		}

		// If we're still here, no nonce-verification function was found.
		$error_code = 'Missing';
		if ( false === $this->superglobals[ $this->tokens[ $stackPtr ]['content'] ] ) {
			$error_code = 'Recommended';
		}

		MessageHelper::addMessage(
			$this->phpcsFile,
			'Processing form data without nonce verification.',
			$stackPtr,
			$this->superglobals[ $this->tokens[ $stackPtr ]['content'] ],
			$error_code
		);
	}

	/**
	 * Determine whether or not a nonce check is needed for the current superglobal.
	 *
	 * @since 3.0.0
	 *
	 * @param int   $stackPtr   The position of the current token in the stack of tokens.
	 * @param array $cache_keys The keys for the applicable cache (to potentially set).
	 *
	 * @return string|false String "before" or "after" if a nonce check is needed.
	 *                      FALSE when no nonce check is needed.
	 */
	protected function needs_nonce_check( $stackPtr, array $cache_keys ) {
		$in_nonce_check = ContextHelper::is_in_function_call( $this->phpcsFile, $stackPtr, $this->nonceVerificationFunctions );
		if ( false !== $in_nonce_check ) {
			// This *is* the nonce check, so bow out, but do store to cache.
			// @todo Change to use arg unpacking once PHP < 5.6 has been dropped.
			$this->set_cache( $cache_keys['file'], $cache_keys['start'], $cache_keys['end'], $in_nonce_check );
			return false;
		}

		if ( Context::inUnset( $this->phpcsFile, $stackPtr ) ) {
			// Variable is only being unset, no nonce check needed.
			return false;
		}

		if ( VariableHelper::is_assignment( $this->phpcsFile, $stackPtr, false ) ) {
			// Overwriting the value of a superglobal.
			return false;
		}

		$needs_nonce = 'before';
		if ( ContextHelper::is_in_isset_or_empty( $this->phpcsFile, $stackPtr )
			|| ContextHelper::is_in_type_test( $this->phpcsFile, $stackPtr )
			|| VariableHelper::is_comparison( $this->phpcsFile, $stackPtr )
			|| VariableHelper::is_assignment( $this->phpcsFile, $stackPtr, true )
			|| ContextHelper::is_in_array_comparison( $this->phpcsFile, $stackPtr )
			|| ContextHelper::is_in_function_call( $this->phpcsFile, $stackPtr, UnslashingFunctionsHelper::get_functions() ) !== false
			|| $this->is_only_sanitized( $this->phpcsFile, $stackPtr )
		) {
			$needs_nonce = 'after';
		}

		return $needs_nonce;
	}

	/**
	 * Check if this token has an associated nonce check.
	 *
	 * @since 0.5.0
	 * @since 3.0.0 - Moved from the generic `Sniff` class to this class.
	 *              - Visibility changed from `protected` to `private.
	 *              - New `$cache_keys` parameter.
	 *              - New `$allow_nonce_after` parameter.
	 *
	 * @param int   $stackPtr          The position of the current token in the stack of tokens.
	 * @param array $cache_keys        The keys for the applicable cache.
	 * @param bool  $allow_nonce_after Whether the nonce check _must_ be before the $stackPtr or
	 *                                 is allowed _after_ the $stackPtr.
	 *
	 * @return bool
	 */
	private function has_nonce_check( $stackPtr, array $cache_keys, $allow_nonce_after = false ) {
		$start = $cache_keys['start'];
		$end   = $cache_keys['end'];

		// We allow for certain actions, such as an isset() check to come before the nonce check.
		// If this superglobal is inside such a check, look for the nonce after it as well,
		// all the way to the end of the scope.
		if ( true === $allow_nonce_after ) {
			$end = ( 0 === $start ) ? $this->phpcsFile->numTokens : $this->tokens[ $start ]['scope_closer'];
		}

		// Check against the cache.
		$current_cache = $this->get_cache( $cache_keys['file'], $start );
		if ( false !== $current_cache['nonce'] ) {
			// If we have already found a nonce check in this scope, we just
			// need to check whether it comes before this token. It is OK if the
			// check is after the token though, if this was only an isset() check.
			return ( true === $allow_nonce_after || $current_cache['nonce'] < $stackPtr );
		} elseif ( $end <= $current_cache['end'] ) {
			// If not, we can still go ahead and return false if we've already
			// checked to the end of the search area.
			return false;
		}

		$search_start = $start;
		if ( $current_cache['end'] > $start ) {
			// We haven't checked this far yet, but we can still save work by
			// skipping over the part we've already checked.
			$search_start = $this->cached_results['cache'][ $start ]['end'];
		}

		// Loop through the tokens looking for nonce verification functions.
		for ( $i = $search_start; $i < $end; $i++ ) {
			// Skip over nested closed scope constructs.
			if ( isset( Collections::closedScopes()[ $this->tokens[ $i ]['code'] ] )
				|| \T_FN === $this->tokens[ $i ]['code']
			) {
				if ( isset( $this->tokens[ $i ]['scope_closer'] ) ) {
					$i = $this->tokens[ $i ]['scope_closer'];
				}
				continue;
			}

			// If this isn't a function name, skip it.
			if ( \T_STRING !== $this->tokens[ $i ]['code'] ) {
				continue;
			}

			// If this is one of the nonce verification functions, we can bail out.
			if ( isset( $this->nonceVerificationFunctions[ $this->tokens[ $i ]['content'] ] ) ) {
				/*
				 * Now, make sure it is a call to a global function.
				 */
				if ( ContextHelper::has_object_operator_before( $this->phpcsFile, $i ) === true ) {
					continue;
				}

				if ( ContextHelper::is_token_namespaced( $this->phpcsFile, $i ) === true ) {
					continue;
				}

				$this->set_cache( $cache_keys['file'], $start, $end, $i );
				return true;
			}
		}

		// We're still here, so no luck.
		$this->set_cache( $cache_keys['file'], $start, $end, false );

		return false;
	}

	/**
	 * Helper function to retrieve results from the cache.
	 *
	 * @since 3.0.0
	 *
	 * @param string $filename The name of the current file.
	 * @param int    $start    The stack pointer searches started from.
	 *
	 * @return array<string, mixed>
	 */
	private function get_cache( $filename, $start ) {
		if ( is_array( $this->cached_results )
			&& $filename === $this->cached_results['file']
			&& isset( $this->cached_results['cache'][ $start ] )
		) {
			return $this->cached_results['cache'][ $start ];
		}

		return array(
			'end'   => 0,
			'nonce' => false,
		);
	}

	/**
	 * Helper function to store results to the cache.
	 *
	 * @since 3.0.0
	 *
	 * @param string   $filename The name of the current file.
	 * @param int      $start    The stack pointer searches started from.
	 * @param int      $end      The stack pointer searched stopped at.
	 * @param int|bool $nonce    Stack pointer to the nonce verification function call or false if none was found.
	 *
	 * @return void
	 */
	private function set_cache( $filename, $start, $end, $nonce ) {
		if ( is_array( $this->cached_results ) === false
			|| $filename !== $this->cached_results['file']
		) {
			$this->cached_results = array(
				'file'  => $filename,
				'cache' => array(
					$start => array(
						'end'   => $end,
						'nonce' => $nonce,
					),
				),
			);
			return;
		}

		// Okay, so we know the current cache is for the current file. Check if we've seen this start pointer before.
		if ( isset( $this->cached_results['cache'][ $start ] ) === false ) {
			$this->cached_results['cache'][ $start ] = array(
				'end'   => $end,
				'nonce' => $nonce,
			);
			return;
		}

		// Update existing entry.
		if ( $end > $this->cached_results['cache'][ $start ]['end'] ) {
			$this->cached_results['cache'][ $start ]['end'] = $end;
		}

		$this->cached_results['cache'][ $start ]['nonce'] = $nonce;
	}

	/**
	 * Merge custom functions provided via a custom ruleset with the defaults, if we haven't already.
	 *
	 * @since 0.11.0 Split out from the `process()` method.
	 *
	 * @return void
	 */
	protected function mergeFunctionLists() {
		if ( $this->customNonceVerificationFunctions !== $this->addedCustomNonceFunctions ) {
			$this->nonceVerificationFunctions = RulesetPropertyHelper::merge_custom_array(
				$this->customNonceVerificationFunctions,
				$this->nonceVerificationFunctions
			);

			$this->addedCustomNonceFunctions = $this->customNonceVerificationFunctions;
		}
	}
}