Fix: is_user_using_two_factor(): respect intentional bypass via new filter — currently unreachable due to leftover early return

[masteradhoc]

What?

Partially Resolves #871

This PR was split off from the original #882 approach following George's review, which pointed out that routing a bypass through two_factor_enabled_providers_for_user plus a new email-fallback filter was solving the wrong problem — and proposed instead a direct, composable two_factor_is_required_for_user filter on is_user_using_two_factor() itself, so a site can express e.g. "skip 2FA for trusted IPs" without touching the provider-list or fail-safe mechanics at all. The original fail-safe bug from #871 is now being addressed separately in #927; this PR is scoped only to adding the filter George proposed.

Related: #927 (companion PR reworking the underlying fail-safe logic)

Use of AI Tools

AI assistance: Yes
Tool(s): Claude (claude.ai)
Model(s): Claude Sonnet 4.6
Used for: Identifying the root cause, drafting the implementation.

Testing Instructions

1. Install the plugin and configure a user with Two_Factor_Email enabled.
2. Add the following to your theme's functions.php:

add_filter( 'two_factor_is_required_for_user', function( $required, $user ) {
    return false; // simulate trusted IP bypass
}, 10, 2 );

3. Before this fix: log in as that user — you are still prompted for an email 2FA code, since the filter is never reached (broken behaviour).
4. Apply this fix (remove the leftover early return).
5. After this fix: log in as that user — 2FA is skipped entirely as intended ✅
6. Remove the filter and verify normal behaviour is unchanged: the same user is prompted for their email code again ✅
7. Additionally verify the force-require direction, since the same filter covers both:

add_filter( 'two_factor_is_required_for_user', function( $required, $user ) {
    return true;
}, 10, 2 );

Log in as a user with no provider configured — login should now be blocked as 2FA-required, rather than succeeding with a single factor.

Screenshots or screencast

N/A — no UI changes.

Changelog Entry

Fixed - two_factor_is_required_for_user filter on is_user_using_two_factor() now actually takes effect, allowing sites to intentionally bypass or force 2FA for a given user (e.g. trusted IP addresses) without touching the provider list.

[Copilot]

Pull request overview

Adds a new hook to let integrators intentionally bypass the “email fallback” behavior when two_factor_enabled_providers_for_user clears a user’s enabled provider list, while preserving the existing fail-safe when providers genuinely disappear.

Changes:

• Updates Two_Factor_Core::get_available_providers_for_user() to distinguish “providers missing” vs “providers intentionally cleared” and introduces the two_factor_email_fallback_enabled filter.
• Documents the new filter in readme.txt.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
class-two-factor-core.php	Adds logic + a new filter to optionally disable the email fallback when enabled providers are intentionally cleared.
readme.txt	Documents the new two_factor_email_fallback_enabled filter and its purpose.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The new two_factor_email_fallback_enabled behavior changes the outcome of get_available_providers_for_user() when a valid provider list is intentionally cleared via two_factor_enabled_providers_for_user, but there’s no unit test coverage validating (1) fallback remains enabled by default and (2) the fallback can be disabled via the new filter while still preserving the existing fail-safe when providers are genuinely missing. Please add/extend tests (likely in tests/class-two-factor-core.php, near test_deprecated_provider_for_user) to cover these cases so regressions are caught.

[masteradhoc]

@nimesh-xecurify would you be able to support on unit test extension here?

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @abovowebdevelopment, @lennarthendriksma-abovo, @sirolf.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: abovowebdevelopment, lennarthendriksma-abovo, sirolf.

Co-authored-by: masteradhoc <masteradhoc@git.wordpress.org>
Co-authored-by: nimesh-xecurify <nimeshatxecurify@git.wordpress.org>
Co-authored-by: georgestephanis <georgestephanis@git.wordpress.org>
Co-authored-by: alexclst <alexclst@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[georgestephanis]

If someone wants to intentionally disable 2fa for a given user, surely we have a better way than zeroing out the providers?

It feels like the PR is working around the wrong thing.

Here's the call chain that matters:

• filter_authenticate() and wp_login() both call is_user_using_two_factor()
• is_user_using_two_factor() calls get_primary_provider_for_user()
• get_primary_provider_for_user() exposes a two_factor_primary_provider_for_user filter

So there's actually already an indirect bypass: return null from two_factor_primary_provider_for_user and is_user_using_two_factor() returns false, skipping the whole 2FA flow. But that's a hack — it's not what that filter is for and the semantics are wrong.

What's missing is a clean, direct filter on is_user_using_two_factor() itself. Something like:

return (bool) apply_filters( 'two_factor_is_required_for_user', ! empty( $provider ), $user );

Then the trusted-IP bypass use case that #882 is trying to solve becomes:

add_filter( 'two_factor_is_required_for_user', function( $required, $user ) {
    return is_trusted_ip() ? false : $required;
}, 10, 2 );

That's one filter, clear intent, no interaction with the provider list at all, and it doesn't require understanding the email fallback mechanics.

The PR's approach requires two filters working in concert (two_factor_enabled_providers_for_user + the new two_factor_email_fallback_enabled), plus understanding the subtle distinction between "providers missing" and "providers intentionally cleared." That's a lot of cognitive load for what should be a simple bypass.

My take is that we should instead open a focused PR that adds a two_factor_is_required_for_user filter to is_user_using_two_factor(). It's a smaller change, more composable, and covers the use case cleanly without touching the email fallback logic at all. The underlying issue (#871) would still be worth fixing separately as a bug — the fail-safe shouldn't fight against two_factor_enabled_providers_for_user when providers genuinely exist in meta — but that's orthogonal to the bypass use case.

[masteradhoc]

Thanks for the review @georgestephanis! I've updated the PR and will split the second part in a new PR - as you've suggested.

One small addition to your sketch: the method now resolves the user via fetch_user() first and returns false early when no user resolves, so filter callbacks always receive a WP_User as the second argument (previously the parameter could be an ID, an object, or null).

For everyone following from #871 — the IP-based bypass becomes one filter instead of the two-filter combo proposed here:

add_filter(
	'two_factor_is_required_for_user',
	function ( $is_required, $user ) {
		$trusted_ips = array( '203.0.113.10' ); // Replace with your trusted IP(s).

		if ( in_array( $_SERVER['REMOTE_ADDR'] ?? '', $trusted_ips, true ) ) {
			return false; // Skip 2FA entirely for this request.
		}

		return $is_required;
	},
	10,
	2
);

⚠️ Only rely on REMOTE_ADDR if PHP sees the real client IP. Behind a proxy or CDN, make sure the real IP is restored at the web-server level — never read X-Forwarded-For for this, as it's client-controlled and spoofable.

[georgestephanis]

Good to ship, but may want to rename the pr as its on a new filter.