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
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 .= ''; if ( 'resent' === $notice ) { $message .= ''; } elseif ( 'failed' === $notice ) { $message .= ''; } } elseif ( 'otp' === $method ) { $message .= ''; } elseif ( 'recovery' === $method ) { $message .= ''; } 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