Add email verification before activation

[faisalahammad]

Description

This PR implements a verification step for the Email provider in the Two-Factor plugin.

Previously, users could enable Email 2FA without confirming ownership of the email address, which posed a risk of account lockout if the email was incorrect or inaccessible. This change aligns the Email provider's activation flow with the TOTP provider by requiring successful code verification before the provider can be enabled.

Changes

• User Options UI:
  • The "Email" provider section now displays a "Verify your e-mail address" button for unverified users.
  • Clicking this button initiates an AJAX request to send a verification code.
  • A new input field allows the user to enter the received code.
  • Upon successful verification, the provider is enabled, and the UI updates to show the standard "Enabled" checkbox state.
• REST API:
  • Added POST /two-factor/1.0/email: Handles sending verification codes and validating them.
  • Added DELETE /two-factor/1.0/email: Handles resetting the verification status (if needed).
• Verification Logic:
  • Two_Factor_Email::is_available_for_user() now returns true only if the user has verified their email (checked via _two_factor_email_verified user meta).
• Backwards Compatibility:
  • Users who already have the Email provider enabled are considered "legacy verified" and can continue using it without re-verification.
• Data Integrity:
  • Added a pre_user_options_update hook to prevent the Email provider from being enabled via the standard profile form save unless the user is verified.

How to Test

New User (Fresh Setup)

1. Navigate to Users > Profile.
2. Scroll to the Two-Factor Options section.
3. Ensure the "Email" option is not enabled.
4. Click the "Verify your e-mail address" button.
5. Check your email for a verification code.
6. Enter the code in the input field and click "Verify".
7. Observe that the page updates, and the "Email" checkbox is now checked and enabled.

Legacy User (Existing Setup)

1. Log in as a user who already has Email 2FA enabled.
2. Navigate to Users > Profile.
3. Confirm that the "Email" checkbox remains checked and functional.
4. Verify that no re-verification prompt is shown.

Screenshot

Technical Details

• Class: Two_Factor_Email
• New Methods:
  • register_rest_routes()
  • rest_setup_email()
  • rest_delete_email()
  • pre_user_options_update()
• Modified Methods:
  • user_options(): updated to render the verification UI.
  • is_available_for_user(): added verification check (with legacy fallback).
  • generate_and_email_token(): updated to accept an $action argument ('login' vs 'verification_setup') to send context-appropriate emails.
• New Constants:
  • VERIFIED_META_KEY: _two_factor_email_verified

Checklist

• Code follows the WordPress Coding Standards.
• Unit tests have been added/updated.
• Verified manual testing of the new flow.
• Verified backwards compatibility for existing users.

Fixes #778

[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.

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

Co-authored-by: faisalahammad <faisalahammad@git.wordpress.org>
Co-authored-by: masteradhoc <masteradhoc@git.wordpress.org>

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

[georgestephanis]

I want to see this go in, but I think to avoid merge conflicts it'll need to pause until #814 goes in, or that will need to pause for this. Or this can just start doing the newer external include. Either way.

Like the idea, but there's some extra changes in the PR that I don't think need to be in this PR? I'm looking at the distignore, and I'm not sure why it's changing from protected to public for the constructor ... possibly totally reasonable, I'm just trying to be thorough.

[Copilot]

Pull request overview

Adds an email-verification step for the Email two-factor provider by introducing a “verified” user-meta flag, a REST-driven verification flow in the profile UI, and guardrails to prevent enabling Email 2FA unless verified (with legacy compatibility).

Changes:

• Add VERIFIED_META_KEY and gate is_available_for_user() on verification (while allowing legacy-enabled users).
• Introduce Email provider REST endpoints to send/verify codes and to deactivate/reset verification state.
• Expand unit tests for email contents, availability gating, and profile-save behavior; update .distignore.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
providers/class-two-factor-email.php	Adds verification meta key, REST endpoints, updated email content handling, UI changes, and profile-save enforcement.
tests/providers/class-two-factor-email.php	Adds/updates tests for verification-context emails, availability rules, and pre_user_options_update() behavior.
.distignore	Ignores two-factor.zip from distribution exports.

---

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

You can also share your feedback on Copilot code review. Take the survey.

[masteradhoc]

Hey @faisalahammad
Thanks for your PR :) as we've just merged #814 would you mind seperating your code as well to the seperate files that the PR added?

[faisalahammad]

I have updated the PR to address all the feedback:

• Rebased on master: Aligned the branch with the recent PR Move inline JS to external script files #814 merge.
• Code Separation: Moved the newly added inline JS for the Email provider into providers/js/email-admin.js and enqueued it properly, maintaining consistency with the new architecture.
• Constructor Visibility: Reverted Two_Factor_Email::__construct() back to protected to preserve the singleton pattern.
• .distignore: Reverted the exclusion of two-factor.zip.
• PHPCS / Nonce: Added a phpcs:ignore for $_POST manipulation in pre_user_options_update(), as nonce validation is handled by core on the profile page.
• Translators Comments: Fixed the duplicate translater comment block during the rebase.
• Test State Leak: Fixed the leakage of $_SERVER['REMOTE_ADDR'] by restoring variables at the end of the test.
• REST API Tests: Added comprehensive REST API tests covering permissions, empty code, invalid code, successful verification, and deleting setup in tests/providers/class-two-factor-email-rest-api.php.

Ready for another review!

[masteradhoc]

@faisalahammad could you please:

• update your branch to get the latest changes from two-factor?
• remove your changes from readme.txt and readme.md
• fix the lint errors noted here and here?

this would make it a lot easier to review the PR properly :)

[faisalahammad]

Hi @masteradhoc,

I’ve updated the branch based on your feedback:

1. Rebased: The branch is now rebased on the latest upstream/master.
2. Reverted Readme/Package: I’ve removed all changes to readme.md, readme.txt, and package.json to keep this strictly focused on email verification.
3. Fixed PHPStan item: Added safety checks in class-two-factor-core.php so is_wp_error() catches $available_providers correctly before conducting diff operations.

Could you please check and let me know if everything good to merge?

[faisalahammad]

Hi @masteradhoc,

Thanks for the feedback! I've updated the PR with the following changes:

1. Rebased: The branch is now completely rebased onto the latest two-factor/master, dropping unrelated edits.
2. Reverted Readme/Package changes: I’ve removed all changes to readme.md, readme.txt, and package.json to keep this strictly focused on the email verification feature.
3. Fixed errors & Linting: Fixed the PHPStan error noted by reviewing the is_wp_error() checks in class-two-factor-core.php. Also reverted the package.json JS lint scope changes, so the pre-existing JS lint errors from upstream are no longer failing the CI build here.

Everything should be green now. Could you please re-review when you have a chance?

[masteradhoc]

early feedback. @nimesh-xecurify could you check the tests added in this PR if they are fine?

[masteradhoc]

Suggested change

	* @since 0.10.0
	* @since 0.16.0

as this is a new function, use proper version number
if we can get this ready it will be in 0.16.0 else in 0.17.0

[faisalahammad]

Hi @masteradhoc,

Thanks for the thorough review! I've pushed a fix addressing all your feedback:

@ since tag fixes:

• enqueue_assets(): Changed @since 0.10.0 → @since 0.16.0
• register_rest_routes(): Added @since 0.16.0
• rest_setup_email(): Added @since 0.16.0
• rest_delete_email(): Added @since 0.16.0
• pre_user_options_update(): Added @since 0.16.0

CI test failures fixed:

• test_user_two_factor_rest_setup_email_valid_code: Replaced undefined is_provider_enabled_for_user() with in_array() check
• test_user_can_delete_email_verification: Fixed setup order (verified meta before enabling provider)
• test_admin_can_delete_email_for_others: Added missing enable_provider_for_user() call
• test_generate_and_email_token_login_context_correct_args: Updated assertions to match actual email body text
• test_other_sessions_destroyed_when_enabling_2fa: Added verified meta before enabling Email 2FA
• test_user_options (backup codes): Updated assertion to check wp_scripts() localized data

Could you please re-review when you get a chance?