array( user ID, expiry ). Persistent storage instead of a * transient: external object caches can evict transients at any time, * which would kill live verification stages and lock users out with * "We could not determine which account you are trying to access." */ private const PENDING_OPTION = 'robotstxt_2fa_pending_stages'; /** * Maximum concurrent pending-stage tokens kept in the map. * * The map is pruned on every write; the cap bounds its size. */ private const PENDING_MAX_TOKENS = 20; /** * Pending-stage token TTL in seconds — matches WP nonce lifetime (24 h). */ private const PENDING_TTL = DAY_IN_SECONDS; /** * Form field carrying the nonce that validates the verification stage. */ private const FIELD_STAGE_TOKEN = 'robotstxt_2fa_stage_token'; /** * Identifier for the verification stage. */ private const STAGE_VERIFY = 'verify'; /** * Nonce action used to secure verification stage requests. */ private const STAGE_TOKEN_ACTION = 'robotstxt_2fa_stage_token'; /** * Email code sender instance. * * @var Email_Code_Sender */ private Email_Code_Sender $email_code_sender; /** * OTP manager instance. * * @var OTP_Manager */ private OTP_Manager $otp_manager; /** * Recovery codes manager. * * @var Recovery_Codes */ private Recovery_Codes $recovery_codes; /** * User settings repository. * * @var User_Settings_Repository */ private User_Settings_Repository $user_settings_repository; /** * Global two-factor configuration helper. * * @var Two_Factor_Config */ private Two_Factor_Config $config; /** * Trusted devices manager. * * @var Trusted_Devices */ private Trusted_Devices $trusted_devices; /** * Grace period manager. * * @var Grace_Period */ private Grace_Period $grace_period; /** * Constructor. */ public function __construct() { $this->email_code_sender = new Email_Code_Sender(); $this->otp_manager = new OTP_Manager(); $this->recovery_codes = new Recovery_Codes(); $this->user_settings_repository = new User_Settings_Repository(); $this->config = new Two_Factor_Config(); $this->trusted_devices = new Trusted_Devices(); $this->grace_period = new Grace_Period(); } /** * Handle verification method switches requested on the login stage. * * @since 1.0.0 * * @return void */ private function process_method_switch(): void { $method = $this->get_requested_method(); $user = $this->resolve_pending_user(); if ( null === $user ) { return; } $stage_token = $this->get_requested_stage_token(); if ( '' === $stage_token || ! $this->validate_stage_token( $user, $stage_token ) ) { return; } $available_methods = $this->get_enabled_verification_methods( $user ); if ( ! in_array( $method, $available_methods, true ) ) { return; } $redirect_args = array( self::QUERY_METHOD => $method, self::QUERY_NOTICE => null, self::QUERY_RESEND => null, self::QUERY_SWITCH => null, ); if ( 'email' === $method ) { if ( ! $this->email_code_sender->send_code( $user ) ) { $redirect_args[ self::QUERY_NOTICE ] = 'failed'; } else { $redirect_args[ self::QUERY_NOTICE ] = 'resent'; } } $redirect_url = $this->get_stage_url( $redirect_args ); wp_safe_redirect( $redirect_url ); exit; } /** * Register WordPress hooks. * * @return void */ public function register_hooks(): void { add_action( 'login_init', array( $this, 'maybe_process_stage_requests' ) ); add_action( 'login_form', array( $this, 'render_form_fields' ) ); add_action( 'login_head', array( $this, 'render_stage_styles' ) ); add_action( 'login_footer', array( $this, 'render_stage_scripts' ) ); add_filter( 'login_message', array( $this, 'filter_login_message' ) ); add_filter( 'authenticate', array( $this, 'maybe_complete_verification' ), 5, 3 ); add_filter( 'authenticate', array( $this, 'enforce_verification_challenge' ), 30, 3 ); add_action( 'init', array( $this, 'maybe_remove_altcha_interceptor' ), 0 ); } /** * Retrieve the canonical wp-login.php URL used for 2FA stage navigation. * * Builds the URL from the real wp-login.php path instead of wp_login_url(). * The `login_url` filter applied by wp_login_url() can be hijacked by * third-party plugins (for example Restrict Content Pro's "Hijack Login * URL" option) to return a membership page, which would send the user to a * page where the verification form cannot render: core only fires the * login_init hook when wp-login.php itself loads. This mirrors the URL * construction wp_login_url() performs before its filter runs. * * @since 1.6.4 * * @param string $redirect_to Optional redirect_to value to carry over. * * @return string Absolute wp-login.php URL with optional redirect_to parameter. */ public static function get_canonical_login_url( string $redirect_to = '' ): string { $url = site_url( 'wp-login.php', 'login' ); if ( '' !== $redirect_to ) { $url = add_query_arg( 'redirect_to', urlencode( $redirect_to ), $url ); } return $url; } /** * Disable the ALTCHA Spam Protection login interceptor during the 2FA stage. * * ALTCHA's "Protect login" feature rejects any wp-login.php POST that does * not carry a fresh proof-of-work payload (HTTP 403). Its JavaScript only * produces that payload for classic username + password submissions, while * the verification stage intentionally omits the password field, so every * legitimate 2FA submission would otherwise be blocked. Human verification * already happened on the first login step; this stage is protected by the * pending-stage token, the stage nonce, and the failed-attempts lockout. * * @since 1.6.2 * * @return void */ public function maybe_remove_altcha_interceptor(): void { if ( ! $this->is_verification_stage() ) { return; } if ( ! has_action( 'init', 'altcha_interceptor' ) ) { return; } /** * Registered filters and actions. Values are WP_Hook objects, but a * corrupted container from third-party code is tolerated, hence mixed. * * @var array|null $wp_filter */ global $wp_filter; $init_hooks = $wp_filter['init'] ?? null; if ( ! $init_hooks instanceof \WP_Hook ) { return; } foreach ( array_keys( $init_hooks->callbacks ) as $priority ) { if ( isset( $init_hooks->callbacks[ $priority ]['altcha_interceptor'] ) ) { remove_action( 'init', 'altcha_interceptor', (int) $priority ); return; } } } /** * Render custom fields on the login form. * * @since 1.0.0 * * @return void */ public function render_form_fields(): void { if ( ! $this->is_verification_stage() ) { return; } $pending_user = $this->resolve_pending_user(); $pending_token = $this->get_requested_pending_token(); $method = $this->get_requested_method(); $code_length = $this->get_method_code_length( $method ); $alternates = array(); if ( $pending_user instanceof WP_User ) { $alternates = $this->get_alternate_method_links( $pending_user, $method ); } if ( '' !== $pending_token ) { printf( '', esc_attr( self::FIELD_PENDING ), esc_attr( $pending_token ) ); } printf( '', esc_attr( self::FIELD_METHOD ), esc_attr( $method ) ); printf( '', esc_attr( self::FIELD_STAGE ), esc_attr( self::STAGE_VERIFY ) ); $stage_token = $this->get_requested_stage_token(); if ( '' !== $stage_token ) { printf( '', esc_attr( self::FIELD_STAGE_TOKEN ), esc_attr( $stage_token ) ); } wp_nonce_field( self::LOGIN_NONCE_ACTION, self::LOGIN_NONCE_FIELD ); ?>

%s

', esc_html( $instruction ) ); } // Trust-device duration follows the user's profile verification frequency. $trust_days = $pending_user instanceof WP_User ? $this->get_trust_days_for_user( $pending_user ) : 0; if ( $trust_days > 0 ) { ?>

get_requested_redirect() ); ?> is_verification_stage() ) { return; } ?> is_verification_stage() ) { return $message; } $user = $this->resolve_pending_user(); $method = $this->get_requested_method(); if ( ! $user instanceof WP_User ) { return $message; } $notice = $this->get_requested_notice(); if ( 'email' === $method ) { $challenge = $this->user_settings_repository->get_email_challenge( $user->ID ); if ( empty( $challenge['sent_at'] ) ) { return $message; } $message .= '

' . esc_html__( 'We sent a verification code to your email. Enter it below to continue.', 'robotstxt-2fa' ) . '

'; if ( 'resent' === $notice ) { $message .= '

' . esc_html__( 'We sent you a fresh verification code. Check your inbox.', 'robotstxt-2fa' ) . '

'; } elseif ( 'failed' === $notice ) { $message .= '

' . esc_html__( 'We could not send a new verification code. Please try again in a moment.', 'robotstxt-2fa' ) . '

'; } } elseif ( 'otp' === $method ) { $message .= '

' . esc_html__( 'Open your authenticator app and enter the code to continue.', 'robotstxt-2fa' ) . '

'; } elseif ( 'recovery' === $method ) { $message .= '

' . esc_html__( 'Enter one of your unused recovery codes to continue.', 'robotstxt-2fa' ) . '

'; } return $message; } /** * Output helper scripts used during the verification stage. * * @since 1.0.0 * * @return void */ public function render_stage_scripts(): void { if ( ! $this->is_verification_stage() ) { return; } $pending_user = $this->resolve_pending_user(); $method = $this->get_requested_method(); $login = $pending_user instanceof \WP_User ? $pending_user->user_login : ''; $sent_at = 0; if ( 'email' === $method && $pending_user instanceof \WP_User ) { $challenge = $this->user_settings_repository->get_email_challenge( $pending_user->ID ); $sent_at = $challenge['sent_at']; } ?> is_verification_submission() ) { return $user; } unset( $password ); if ( ! isset( $_POST[ self::LOGIN_NONCE_FIELD ] ) || ! is_string( $_POST[ self::LOGIN_NONCE_FIELD ] ) ) { return new \WP_Error( 'robotstxt_2fa_missing_nonce', __( 'The verification form is missing a security token. Please try again.', 'robotstxt-2fa' ) ); } $nonce = sanitize_text_field( wp_unslash( $_POST[ self::LOGIN_NONCE_FIELD ] ) ); if ( ! wp_verify_nonce( $nonce, self::LOGIN_NONCE_ACTION ) ) { return new \WP_Error( 'robotstxt_2fa_invalid_nonce', __( 'The verification request expired. Please sign in again to request a new code.', 'robotstxt-2fa' ) ); } $authenticated_user = $this->resolve_pending_user(); if ( null === $authenticated_user ) { return new \WP_Error( 'robotstxt_2fa_unknown_user', __( 'Your verification session expired or could not be found. Please sign in again.', 'robotstxt-2fa' ) ); } // Brute-force: check if the account is currently locked out. $lock_key = 'robotstxt_2fa_locked_' . $authenticated_user->ID; $locked = get_transient( $lock_key ); if ( false !== $locked ) { $remaining_seconds = max( 0, ( is_numeric( $locked ) ? (int) $locked : 0 ) - time() ); $remaining_minutes = (int) ceil( $remaining_seconds / 60 ); return new \WP_Error( 'robotstxt_2fa_locked', sprintf( /* translators: %d: minutes remaining. */ _n( 'Too many failed attempts. Please try again in %d minute.', 'Too many failed attempts. Please try again in %d minutes.', $remaining_minutes, 'robotstxt-2fa' ), $remaining_minutes ) ); } $stage_token = $this->get_requested_stage_token(); if ( '' === $stage_token || ! $this->validate_stage_token( $authenticated_user, $stage_token ) ) { return new \WP_Error( 'robotstxt_2fa_invalid_stage', __( 'Your verification session expired. Please sign in again.', 'robotstxt-2fa' ) ); } $method = $this->get_requested_method(); $allowed_methods = $this->get_enabled_verification_methods( $authenticated_user ); if ( ! in_array( $method, $allowed_methods, true ) ) { return new \WP_Error( 'robotstxt_2fa_method_unavailable', __( 'The selected verification method is not available right now.', 'robotstxt-2fa' ) ); } $token = ''; if ( isset( $_POST['robotstxt_2fa_token'] ) && is_string( $_POST['robotstxt_2fa_token'] ) ) { $token = sanitize_text_field( wp_unslash( $_POST['robotstxt_2fa_token'] ) ); } if ( '' === $token ) { return new \WP_Error( 'robotstxt_2fa_missing_code', __( 'Enter the verification code to continue.', 'robotstxt-2fa' ) ); } $is_valid = false; switch ( $method ) { case 'email': $is_valid = $this->email_code_sender->verify_code( $authenticated_user, $token ); if ( $is_valid ) { $this->user_settings_repository->delete_email_challenge( $authenticated_user->ID ); } break; case 'recovery': $is_valid = $this->recovery_codes->consume_code( $authenticated_user, $token ); break; case 'otp': $is_valid = $this->otp_manager->verify_code( $authenticated_user, $token ); break; default: return new \WP_Error( 'robotstxt_2fa_method_unavailable', __( 'The selected verification method is not available right now.', 'robotstxt-2fa' ) ); } if ( ! $is_valid ) { /** * Fires when a 2FA verification attempt fails. * * @since 1.0.0 * * @param \WP_User $user User who failed the challenge. * @param string $method Verification method slug that was attempted. */ do_action( 'robotstxt_2fa_verification_failed', $authenticated_user, $method ); // Brute-force: increment attempt counter and lock if threshold reached. $max_attempts = $this->config->get_max_attempts(); if ( $max_attempts > 0 ) { $attempts_key = 'robotstxt_2fa_attempts_' . $authenticated_user->ID; $raw_attempts = get_transient( $attempts_key ); $attempts = ( is_numeric( $raw_attempts ) ? (int) $raw_attempts : 0 ) + 1; set_transient( $attempts_key, $attempts, 30 * MINUTE_IN_SECONDS ); if ( $attempts >= $max_attempts ) { delete_transient( $attempts_key ); $expires_at = time() + $this->config->get_lockout_duration() * MINUTE_IN_SECONDS; set_transient( $lock_key, $expires_at, $this->config->get_lockout_duration() * MINUTE_IN_SECONDS ); } } return new \WP_Error( 'robotstxt_2fa_invalid_code', __( 'The verification code is incorrect or has expired.', 'robotstxt-2fa' ) ); } // Brute-force: clear the attempt counter on success. delete_transient( 'robotstxt_2fa_attempts_' . $authenticated_user->ID ); // Consume the pending token so it cannot be replayed. $pending_token = $this->get_requested_pending_token(); if ( '' !== $pending_token ) { $this->consume_pending_token( $pending_token ); } $this->user_settings_repository->record_last_verification( $authenticated_user->ID, $method, $this->get_login_context_key(), time() ); // Trusted devices: set cookie when user checked "Remember this browser". // Duration complies with the user's profile verification frequency. if ( isset( $_POST['robotstxt_2fa_trust_device'] ) && '1' === $_POST['robotstxt_2fa_trust_device'] ) { // phpcs:ignore WordPress.Security.NonceVerification.Missing -- nonce already verified above. $trust_days = $this->get_trust_days_for_user( $authenticated_user ); if ( $trust_days > 0 ) { $this->trusted_devices->trust_current_device( $authenticated_user, $trust_days ); } } /** * Fires after a successful 2FA verification. * * @since 1.0.0 * * @param \WP_User $user Authenticated user. * @param string $method Verification method slug that succeeded. */ do_action( 'robotstxt_2fa_verification_success', $authenticated_user, $method ); return $authenticated_user; } /** * Enforce the verification step for eligible users. * * @param \WP_User|\WP_Error|null $user Previously authenticated user or error. * @param string|null $username Submitted username. * @param string|null $password Submitted password. * * @return \WP_User|\WP_Error|null */ public function enforce_verification_challenge( $user, ?string $username, ?string $password ) { unset( $username, $password ); if ( $this->is_verification_stage() || $this->is_verification_submission() ) { return $user; } if ( ! $user instanceof \WP_User ) { return $user; } /** * Filter whether to skip the 2FA challenge for the current request. * * Return true to bypass the challenge entirely. Use this for REST API * requests, WP-CLI, Application Passwords, trusted IPs, etc. * * @since 1.0.0 * * @param bool $skip Whether to skip the challenge. Default false. * @param \WP_User $user Authenticated user about to be challenged. */ if ( (bool) apply_filters( 'robotstxt_2fa_skip_challenge', false, $user ) ) { return $user; } // Application Passwords: skip challenge for requests authenticated via Application Passwords. if ( $this->config->is_app_passwords_exempt() && (bool) did_action( 'application_password_did_authenticate' ) ) { return $user; } // Trusted devices: skip challenge when the browser carries a valid trust cookie. if ( $this->config->get_trust_device_days() > 0 && $this->trusted_devices->is_trusted( $user ) ) { return $user; } // Temporary bypass: administrators can grant a time-limited bypass via WP-CLI. $bypass_until = get_transient( 'robotstxt_2fa_bypass_' . $user->ID ); if ( false !== $bypass_until && is_numeric( $bypass_until ) && (int) $bypass_until > time() ) { return $user; } $required_methods = $this->config->get_required_methods_for_user( $user ); // Grace period: if forced but no methods configured yet, check whether the user is within their grace window. if ( ! empty( $required_methods ) ) { $user_settings = $this->user_settings_repository->get_user_settings( $user->ID ); $has_any_method = ! empty( $user_settings['methods'] ); if ( ! $has_any_method ) { $grace_days = $this->config->get_grace_period_days(); if ( $grace_days > 0 && $this->grace_period->is_active( $user, $grace_days ) ) { // Still within grace period — let the user through. $remaining = $this->grace_period->get_days_remaining( $user, $grace_days ); set_transient( 'robotstxt_2fa_grace_notice_' . $user->ID, $remaining, MINUTE_IN_SECONDS ); return $user; } if ( $grace_days > 0 ) { // Grace period has expired. if ( 'wizard' === $this->config->get_grace_period_action() ) { $this->grace_period->set_pending_setup( $user->ID ); return $user; } // Block mode. return new \WP_Error( 'robotstxt_2fa_setup_required', __( 'Your account requires two-factor authentication. Please contact your administrator to complete the setup.', 'robotstxt-2fa' ) ); } } } $method = $this->determine_required_verification_method( $user ); if ( '' === $method ) { return $user; } if ( 'email' === $method && ! $this->email_code_sender->send_code( $user ) ) { return new \WP_Error( 'robotstxt_2fa_email_failed', __( 'We could not send a verification code. Please contact the site administrator.', 'robotstxt-2fa' ) ); } $redirect_to = $this->get_requested_redirect(); $stage_token = wp_create_nonce( self::STAGE_TOKEN_ACTION . '|' . $user->ID ); $query_args = array( self::QUERY_STAGE => self::STAGE_VERIFY, self::QUERY_METHOD => $method, self::QUERY_PENDING => $this->issue_pending_token( $user->ID ), self::QUERY_STAGE_TOKEN => $stage_token, ); $login_url = self::get_canonical_login_url( $redirect_to ); $login_url = add_query_arg( $query_args, $login_url ); wp_safe_redirect( $login_url ); exit; } /** * Process additional verification stage actions triggered from the login screen. * * @return void */ public function maybe_process_stage_requests(): void { if ( ! $this->is_verification_stage() ) { return; } $has_switch = ! empty( $_GET[ self::QUERY_SWITCH ] ); // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Query flag only; nonce/stage-token verified inside process_method_switch(). $has_resend = ! empty( $_GET[ self::QUERY_RESEND ] ); // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Query flag only; stage-token verified before sending. if ( $has_switch ) { $this->process_method_switch(); return; } if ( ! $has_resend ) { return; } $method = $this->get_requested_method(); if ( 'email' !== $method ) { return; } $user = $this->resolve_pending_user(); if ( null === $user ) { return; } $stage_token = $this->get_requested_stage_token(); if ( '' === $stage_token || ! $this->validate_stage_token( $user, $stage_token ) ) { return; } $result = $this->email_code_sender->send_code( $user ); $notice_value = $result ? 'resent' : 'failed'; $redirect_url = remove_query_arg( self::QUERY_RESEND, $this->get_stage_url( array( self::QUERY_NOTICE => $notice_value, ) ) ); wp_safe_redirect( $redirect_url ); exit; } /** * Retrieve the verification method requested by the current stage. * * @return string */ private function get_requested_method(): string { $method = ''; // phpcs:disable WordPress.Security.NonceVerification.Recommended -- Stage helper; nonce verified in calling context. if ( isset( $_REQUEST[ self::FIELD_METHOD ] ) && is_string( $_REQUEST[ self::FIELD_METHOD ] ) ) { $method = sanitize_key( wp_unslash( $_REQUEST[ self::FIELD_METHOD ] ) ); } if ( '' === $method && isset( $_REQUEST[ self::QUERY_METHOD ] ) && is_string( $_REQUEST[ self::QUERY_METHOD ] ) ) { $method = sanitize_key( wp_unslash( $_REQUEST[ self::QUERY_METHOD ] ) ); } // phpcs:enable WordPress.Security.NonceVerification.Recommended if ( '' === $method ) { $method = 'email'; } return $method; } /** * Determine the expected code length for a verification method. * * @param string $method Verification method identifier. * * @return int */ private function get_method_code_length( string $method ): int { switch ( $method ) { case 'otp': return max( 1, (int) $this->otp_manager->get_code_length() ); case 'recovery': return max( 1, (int) $this->recovery_codes->get_code_length() ); case 'email': default: return max( 1, (int) $this->email_code_sender->get_code_length() ); } } /** * Retrieve the verification methods that are active for the provided user. * * Role enforcement is treated as a floor, not a ceiling: when 2FA is * enforced by role, the required methods are guaranteed to be set up on the * profile (enforced at save time), but the user may authenticate with ANY * method they have configured — not only the role-required ones. If the * user has not configured any method yet, the role-required methods that * the system can deliver (e.g. email) are returned so the login can still * be challenged. * * @param \WP_User $user User attempting to authenticate. * @param array{enabled: bool, methods: array, frequency: string, preferred_method: string}|null $user_settings Optional preloaded settings. * * @return array */ private function get_enabled_verification_methods( \WP_User $user, ?array $user_settings = null ): array { if ( null === $user_settings ) { $user_settings = $this->user_settings_repository->get_user_settings( $user->ID ); } $required_methods = $this->config->get_required_methods_for_user( $user ); $is_forced = ! empty( $required_methods ); $enabled = $is_forced ? true : $user_settings['enabled']; if ( ! $enabled ) { return array(); } // Normalize user's profile methods to login-stage slugs. $profile_methods = array(); foreach ( $user_settings['methods'] as $method_key ) { $slug = $this->normalize_method_slug( $method_key ); if ( '' !== $slug ) { $profile_methods[] = $slug; } } $profile_methods = array_values( array_unique( $profile_methods ) ); if ( $is_forced && empty( $profile_methods ) ) { // User has not configured any method yet — fall back to the methods the // system can deliver from the required set so a challenge is still possible. $required_slugs = array(); foreach ( $required_methods as $method ) { $slug = $this->normalize_method_slug( $method ); if ( '' !== $slug ) { $required_slugs[] = $slug; } } $candidate_methods = array_values( array_unique( $required_slugs ) ); } else { // Offer every method the user has configured (role enforcement is a floor). $candidate_methods = $profile_methods; } // Filter to methods the system can actually deliver right now. $available = array(); foreach ( $candidate_methods as $method ) { if ( 'email' === $method ) { if ( '' !== sanitize_email( $user->user_email ) ) { $available[] = 'email'; } } elseif ( 'otp' === $method ) { if ( '' !== $this->otp_manager->get_secret( $user->ID ) ) { $available[] = 'otp'; } } elseif ( 'recovery' === $method ) { if ( $this->recovery_codes->has_active_codes( $user->ID ) ) { $available[] = 'recovery'; } } } // Return methods in canonical priority order: OTP first, email second, recovery last. // The user's preferred method is honored separately in select_preferred_method(). $priority = array( 'otp', 'email', 'recovery' ); $sorted = array(); foreach ( $priority as $p ) { if ( in_array( $p, $available, true ) ) { $sorted[] = $p; } } return $sorted; } /** * Decide which verification method should be enforced for the user. * * @param \WP_User $user User attempting to authenticate. * * @return string */ private function determine_required_verification_method( \WP_User $user ): string { $user_settings = $this->user_settings_repository->get_user_settings( $user->ID ); $methods = $this->get_enabled_verification_methods( $user, $user_settings ); if ( empty( $methods ) ) { return ''; } $frequency = $this->get_effective_frequency( $user, $user_settings ); if ( $this->has_recent_verification( $user, $methods, $frequency ) ) { /** * Filter whether to force a fresh 2FA challenge regardless of the frequency setting. * * Return true to always challenge the user, overriding the frequency-based skip. * Used by GeoIP restrictions to mandate verification from new countries. * * @since 1.5.0 * * @param bool $force Whether to force the challenge. Default false. * @param \WP_User $user User about to be challenged. */ if ( ! (bool) apply_filters( 'robotstxt_2fa_force_challenge', false, $user ) ) { return ''; } } return $this->select_preferred_method( $methods, (string) $user_settings['preferred_method'] ); } /** * Check whether any verification method was recently validated within the configured interval. * * @param \WP_User $user User attempting to authenticate. * @param array $methods Active verification methods. * @param string $frequency Selected frequency slug. * * @return bool */ private function has_recent_verification( \WP_User $user, array $methods, string $frequency ): bool { if ( empty( $methods ) ) { return false; } if ( Frequency_Options::FREQUENCY_SESSION === $frequency ) { return false; } $interval_seconds = Frequency_Options::get_interval_seconds( $frequency ); if ( $interval_seconds <= 0 ) { return false; } $context_key = $this->get_login_context_key(); foreach ( $methods as $method ) { $last_verified = $this->user_settings_repository->get_last_verification_timestamp( $user->ID, $method, $context_key ); if ( $last_verified > 0 && ( $last_verified + $interval_seconds ) > time() ) { return true; } } return false; } /** * Determine which method should be requested when a challenge is required. * * Honors the user's preferred method (set on their profile) when it is part * of the available methods; otherwise falls back to the canonical order. * * @since 1.0.0 * * @param array $methods Active verification methods (stage slugs). * @param string $preferred_method Optional user-chosen preferred method key. * * @return string */ private function select_preferred_method( array $methods, string $preferred_method = '' ): string { if ( empty( $methods ) ) { return ''; } if ( '' !== $preferred_method ) { $preferred_slug = $this->normalize_method_slug( $preferred_method ); if ( '' !== $preferred_slug && in_array( $preferred_slug, $methods, true ) ) { return $preferred_slug; } } // Prefer OTP (most secure), then email, then recovery codes (last resort). foreach ( array( 'otp', 'email' ) as $method ) { if ( in_array( $method, $methods, true ) ) { return $method; } } // Use recovery only when it is the sole option. if ( in_array( 'recovery', $methods, true ) ) { return 'recovery'; } return $methods[0]; } /** * Normalize stored method identifiers to the stage slugs used during verification. * * @param string $method Raw method identifier. * * @return string */ private function normalize_method_slug( string $method ): string { $method = sanitize_key( $method ); if ( '' === $method ) { return ''; } if ( 'recovery_codes' === $method || 'recovery' === $method ) { return 'recovery'; } if ( in_array( $method, array( 'email', 'otp' ), true ) ) { return $method; } return ''; } /** * Build the list of alternate verification method links for the login stage. * * @param \WP_User $user User attempting to authenticate. * @param string $current_method Active verification method slug. * * @return array> */ private function get_alternate_method_links( \WP_User $user, string $current_method ): array { $available_methods = $this->get_enabled_verification_methods( $user ); $available_methods = array_values( array_diff( $available_methods, array( $current_method ) ) ); if ( empty( $available_methods ) ) { return array(); } $labels = array( 'email' => __( 'Use an email code instead', 'robotstxt-2fa' ), 'otp' => __( 'Use your authenticator app instead', 'robotstxt-2fa' ), 'recovery' => __( 'Use a recovery code instead', 'robotstxt-2fa' ), ); $links = array(); foreach ( $available_methods as $method ) { if ( ! isset( $labels[ $method ] ) ) { continue; } $links[] = array( 'url' => $this->get_stage_url( array( self::QUERY_METHOD => $method, self::QUERY_NOTICE => null, self::QUERY_RESEND => null, self::QUERY_SWITCH => '1', ) ), 'label' => $labels[ $method ], ); } return $links; } /** * Determine whether the login request is currently displaying the verification stage. * * @return bool */ private function is_verification_stage(): bool { // phpcs:disable WordPress.Security.NonceVerification.Recommended -- Stage-detection only; nonce verified in calling context. if ( isset( $_REQUEST[ self::FIELD_STAGE ] ) && is_string( $_REQUEST[ self::FIELD_STAGE ] ) ) { $stage = sanitize_key( wp_unslash( $_REQUEST[ self::FIELD_STAGE ] ) ); if ( self::STAGE_VERIFY === $stage ) { return true; } } if ( isset( $_REQUEST[ self::QUERY_STAGE ] ) && is_string( $_REQUEST[ self::QUERY_STAGE ] ) ) { $stage = sanitize_key( wp_unslash( $_REQUEST[ self::QUERY_STAGE ] ) ); if ( self::STAGE_VERIFY === $stage ) { return true; } } // phpcs:enable WordPress.Security.NonceVerification.Recommended return false; } /** * Check whether the login POST submission belongs to the verification stage. * * @return bool */ private function is_verification_submission(): bool { // phpcs:ignore WordPress.Security.NonceVerification.Missing -- Stage flag only; nonce verified in maybe_complete_verification(). if ( ! isset( $_POST[ self::FIELD_STAGE ] ) || ! is_string( $_POST[ self::FIELD_STAGE ] ) ) { return false; } $stage = sanitize_key( wp_unslash( $_POST[ self::FIELD_STAGE ] ) ); // phpcs:ignore WordPress.Security.NonceVerification.Missing return self::STAGE_VERIFY === $stage; } /** * Issue an opaque pending-stage token that maps to a user ID. * * Stores the token in a persistent option map (see PENDING_OPTION) so the * login username is never transmitted in the URL query string and object * cache eviction cannot kill a live stage. * * @since 1.3.0 * @since 1.6.8 Stored in a persistent option map instead of a transient. * * @param int $user_id User identifier. * * @return string 32-character alphanumeric token. */ private function issue_pending_token( int $user_id ): string { $tokens = $this->get_pending_token_map(); $now = time(); foreach ( $tokens as $existing_token => $data ) { if ( $data['e'] <= $now ) { unset( $tokens[ $existing_token ] ); } } $token = wp_generate_password( 32, false, false ); $tokens[ $token ] = array( 'u' => $user_id, 'e' => $now + self::PENDING_TTL, ); if ( count( $tokens ) > self::PENDING_MAX_TOKENS ) { uasort( $tokens, static function ( array $a, array $b ): int { return (int) $a['e'] <=> (int) $b['e']; } ); $tokens = array_slice( $tokens, -self::PENDING_MAX_TOKENS, null, true ); } update_option( self::PENDING_OPTION, $tokens, false ); return $token; } /** * Retrieve the raw pending-stage token map stored in the database. * * @since 1.6.8 * * @return array Token => user ID + expiry. */ private function get_pending_token_map(): array { $raw = get_option( self::PENDING_OPTION, array() ); if ( ! is_array( $raw ) ) { return array(); } $tokens = array(); foreach ( $raw as $token => $data ) { if ( is_string( $token ) && is_array( $data ) && isset( $data['u'], $data['e'] ) && is_numeric( $data['u'] ) && is_numeric( $data['e'] ) ) { $tokens[ $token ] = array( 'u' => (int) $data['u'], 'e' => (int) $data['e'], ); } } return $tokens; } /** * Remove a consumed pending-stage token from the map. * * @since 1.6.8 * * @param string $token Token to consume. * * @return void */ private function consume_pending_token( string $token ): void { $tokens = $this->get_pending_token_map(); if ( ! isset( $tokens[ $token ] ) ) { return; } unset( $tokens[ $token ] ); update_option( self::PENDING_OPTION, $tokens, false ); } /** * Retrieve the raw pending-stage token from the current request. * * @since 1.3.0 * * @return string */ private function get_requested_pending_token(): string { // phpcs:disable WordPress.Security.NonceVerification.Recommended -- Opaque token helper; token-to-user mapping validated in resolve_pending_user(). if ( isset( $_REQUEST[ self::FIELD_PENDING ] ) && is_string( $_REQUEST[ self::FIELD_PENDING ] ) ) { return sanitize_text_field( wp_unslash( $_REQUEST[ self::FIELD_PENDING ] ) ); } if ( isset( $_REQUEST[ self::QUERY_PENDING ] ) && is_string( $_REQUEST[ self::QUERY_PENDING ] ) ) { return sanitize_text_field( wp_unslash( $_REQUEST[ self::QUERY_PENDING ] ) ); } // phpcs:enable WordPress.Security.NonceVerification.Recommended return ''; } /** * Resolve the pending-stage token to its associated WP_User. * * @since 1.3.0 * @since 1.6.8 Reads the persistent token map instead of a transient. * * @return \WP_User|null Null when no valid token is present. */ private function resolve_pending_user(): ?\WP_User { $token = $this->get_requested_pending_token(); if ( '' === $token ) { return null; } $data = $this->get_pending_token_map()[ $token ] ?? null; if ( null === $data || $data['e'] <= time() ) { return null; } $user = get_user_by( 'ID', $data['u'] ); return $user instanceof \WP_User ? $user : null; } /** * Retrieve the stage nonce carried in the current request. * * @return string */ private function get_requested_stage_token(): string { $token = ''; // phpcs:disable WordPress.Security.NonceVerification.Recommended -- Stage-token helper; token itself is the nonce verified in validate_stage_token(). if ( isset( $_REQUEST[ self::FIELD_STAGE_TOKEN ] ) && is_string( $_REQUEST[ self::FIELD_STAGE_TOKEN ] ) ) { $token = sanitize_text_field( wp_unslash( $_REQUEST[ self::FIELD_STAGE_TOKEN ] ) ); } if ( '' === $token && isset( $_REQUEST[ self::QUERY_STAGE_TOKEN ] ) && is_string( $_REQUEST[ self::QUERY_STAGE_TOKEN ] ) ) { $token = sanitize_text_field( wp_unslash( $_REQUEST[ self::QUERY_STAGE_TOKEN ] ) ); } // phpcs:enable WordPress.Security.NonceVerification.Recommended return $token; } /** * Retrieve the notice slug carried in the current request. * * @return string */ private function get_requested_notice(): string { // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Notice slug helper; display-only, not security-sensitive. if ( ! isset( $_REQUEST[ self::QUERY_NOTICE ] ) || ! is_string( $_REQUEST[ self::QUERY_NOTICE ] ) ) { return ''; } return sanitize_key( wp_unslash( $_REQUEST[ self::QUERY_NOTICE ] ) ); // phpcs:ignore WordPress.Security.NonceVerification.Recommended } /** * Validate whether the provided stage token is valid for the given user. * * @param \WP_User $user Authenticated user. * @param string $stage_token Submitted stage token. * * @return bool */ private function validate_stage_token( \WP_User $user, string $stage_token ): bool { return (bool) wp_verify_nonce( $stage_token, self::STAGE_TOKEN_ACTION . '|' . $user->ID ); } /** * Retrieve the sanitized redirect_to parameter from the current request. * * @return string */ private function get_requested_redirect(): string { // phpcs:disable WordPress.Security.NonceVerification.Recommended -- redirect_to is a standard WP login parameter; value is passed through esc_url_raw. if ( ! isset( $_REQUEST['redirect_to'] ) || ! is_string( $_REQUEST['redirect_to'] ) ) { return ''; } return esc_url_raw( wp_unslash( $_REQUEST['redirect_to'] ) ); // phpcs:enable WordPress.Security.NonceVerification.Recommended } /** * Build a URL pointing to the active verification stage. * * @param array $extra_args Optional additional query parameters to merge. * * @return string */ private function get_stage_url( array $extra_args = array() ): string { $redirect_to = $this->get_requested_redirect(); $login_url = self::get_canonical_login_url( $redirect_to ); $args = array( self::QUERY_STAGE => self::STAGE_VERIFY, self::QUERY_METHOD => $this->get_requested_method(), ); $pending_token = $this->get_requested_pending_token(); if ( '' !== $pending_token ) { $args[ self::QUERY_PENDING ] = $pending_token; } $stage_token = $this->get_requested_stage_token(); if ( '' !== $stage_token ) { $args[ self::QUERY_STAGE_TOKEN ] = $stage_token; } foreach ( $extra_args as $key => $value ) { if ( null === $value || '' === $key ) { $login_url = remove_query_arg( $key, $login_url ); continue; } $args[ $key ] = $value; } $args = array_filter( $args, static function ( $value ) { return '' !== $value; } ); return add_query_arg( $args, $login_url ); } /** * Determine the effective verification frequency for the current user. * * @param \WP_User $user Authenticated user object. * @param array{enabled: bool, methods: array, frequency: string} $user_settings Stored per-user preferences. * * @return string */ private function get_effective_frequency( \WP_User $user, array $user_settings ): string { unset( $user ); if ( $this->config->is_frequency_forced() ) { return $this->config->get_frequency(); } if ( '' !== $user_settings['frequency'] ) { return Frequency_Options::sanitize( $user_settings['frequency'] ); } return $this->config->get_frequency(); } /** * Resolve the "Remember this browser" trust duration (in days) for a user. * * The feature must be enabled by the administrator (trust_device_days > 0) * and the user's effective verification frequency must define a non-zero * interval; the duration is taken from that frequency so the checkbox always * complies with the user's profile setting. * * @since 1.5.3 * * @param \WP_User $user User attempting to authenticate. * * @return int Number of days, or 0 when the feature is disabled or the * user's frequency is per-session. */ private function get_trust_days_for_user( \WP_User $user ): int { if ( $this->config->get_trust_device_days() <= 0 ) { return 0; } $user_settings = $this->user_settings_repository->get_user_settings( $user->ID ); return Frequency_Options::get_interval_days( $this->get_effective_frequency( $user, $user_settings ) ); } /** * Build a hashed context key representing the current login environment. * * @return string */ private function get_login_context_key(): string { $ip = ''; if ( isset( $_SERVER['REMOTE_ADDR'] ) ) { // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- Sanitized below. $raw_addr = is_string( $_SERVER['REMOTE_ADDR'] ) ? $_SERVER['REMOTE_ADDR'] : ''; $ip = sanitize_text_field( wp_unslash( $raw_addr ) ); $ip = wp_privacy_anonymize_ip( $ip ); } $user_agent = ''; if ( isset( $_SERVER['HTTP_USER_AGENT'] ) ) { // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- Sanitized below. $raw_ua = is_string( $_SERVER['HTTP_USER_AGENT'] ) ? $_SERVER['HTTP_USER_AGENT'] : ''; $user_agent = sanitize_text_field( wp_unslash( $raw_ua ) ); } $user_agent = strtolower( substr( $user_agent, 0, 255 ) ); if ( '' === $ip && '' === $user_agent ) { return sha1( 'unknown' ); } return sha1( $ip . '|' . $user_agent ); } }