<?php
/**
 * Nonce creation and verification helpers.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Security;

/**
 * Thin wrappers around WordPress nonce APIs with consistent failure handling.
 *
 * Use `verify()` from AJAX handlers to enforce nonce checks with a uniform
 * 403 response on failure. Use `is_valid()` from contexts that need to keep
 * processing after a failure (e.g. REST permission callbacks).
 *
 * @since 1.0.0
 */
final class Nonce {

	/**
	 * Creates a nonce for the given action.
	 *
	 * @since 1.0.0
	 *
	 * @param string $action The action key the nonce is bound to.
	 *
	 * @return string The nonce value.
	 */
	public static function create( string $action ): string {
		return wp_create_nonce( $action );
	}

	/**
	 * Verifies a nonce from an AJAX/admin-post request and exits with 403 on failure.
	 *
	 * Reads the nonce from `$_REQUEST` so it works for both POST and GET.
	 * On failure sends a JSON error response and exits — callers may assume
	 * a successful return means the nonce is valid.
	 *
	 * @since 1.0.0
	 *
	 * @param string $action The action key the nonce was created for.
	 * @param string $field  Optional. Request field name. Default `_wpnonce`.
	 *
	 * @return void
	 */
	public static function verify( string $action, string $field = '_wpnonce' ): void {
		if ( ! self::is_valid( $action, $field ) ) {
			wp_send_json_error(
				array( 'message' => __( 'Invalid or expired nonce.', 'postlinkly' ) ),
				403
			);
		}
	}

	/**
	 * Returns whether the request carries a valid nonce for the given action.
	 *
	 * Does not exit on failure. Use this when the caller needs to handle
	 * the failure case itself.
	 *
	 * @since 1.0.0
	 *
	 * @param string $action The action key the nonce was created for.
	 * @param string $field  Optional. Request field name. Default `_wpnonce`.
	 *
	 * @return bool True when the nonce verifies.
	 */
	public static function is_valid( string $action, string $field = '_wpnonce' ): bool {
		// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- we are the verifier.
		$value = isset( $_REQUEST[ $field ] )
			? sanitize_text_field( wp_unslash( (string) $_REQUEST[ $field ] ) )
			: '';

		if ( '' === $value ) {
			return false;
		}

		return (bool) wp_verify_nonce( $value, $action );
	}
}