What?

Emails users when they are running low on, or have run out of, recovery codes. After a user logs in with their last code, they are sent straight to the recovery codes section of their profile.

Follow-up to #907.

Why?

#907 added admin notices that warn users when they are running low on recovery codes, and when they have none left. Those notices only appear in wp-admin. An email reaches users wherever they are. Redirecting to the recovery codes section after the last code saves them the extra step.

How?

• Email: Two_Factor_Backup_Codes::validate_code() now calls the new notify_user_codes_running_low() after a code is used.
  • It sends when the remaining count is at or below the threshold (default 2), and always when no codes are left. This matches the existing notices.
  • It only sends if recovery codes are enabled for the user.
• Shared threshold: The two_factor_backup_codes_low_threshold filter moved into a private get_low_codes_threshold() helper, so the notice and the email always use the same value. Name, default and arguments are unchanged.
• Redirect: The new maybe_redirect_to_regenerate_codes() runs on two_factor_user_authenticated and two_factor_user_revalidated.
  • If the user just authenticated with a recovery code and has none left, it adds a login_redirect filter at PHP_INT_MAX pointing to get_edit_profile_url() . '#two-factor-backup-codes'.
  • It uses get_edit_profile_url() because get_edit_user_link() returns an empty string during login, before the current user is set.
  • Interim (modal) logins don't redirect, so they behave as before.
• Docs: Both filters are added to the hook list in readme.txt. The threshold filter shipped in 0.17.0 but wasn't documented yet. The new tests are listed in TESTS.md.
• Tests: 7 new tests in tests/providers/class-two-factor-backup-codes.php, plus an end-to-end login test in tests/class-two-factor-core.php.

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5.5
Used for: Implementation, tests, documentation updates and this description. I reviewed and tested the changes before opening the PR.

Testing Instructions

1. Log in as a user with the Authenticator App or Email method enabled.
2. Generate 4 recovery codes: wp two-factor backup-codes generate <user> --count=4 --yes.
3. To see the emails, use a mail catcher such as Mailpit, or a mail logging plugin.
4. Log out, log in, and choose "Use a recovery code" at the two-factor prompt. Repeat once for each code:
   • 1st code (3 left): no email.
   • 2nd code (2 left): email "[Site] You are running low on recovery codes", saying 2 codes are left.
   • 3rd code (1 left): the same email, saying 1 code is left.
   • 4th code (none left): email "[Site] You are out of recovery codes". You are redirected to Profile → Recovery Codes instead of the dashboard.
5. Log in again with your other method. You are not redirected.
6. Optional: add add_filter( 'two_factor_backup_codes_low_threshold', '__return_zero' ); to an mu-plugin and repeat. Only the "out of recovery codes" email is sent.

Changelog Entry

Added - Email users when they are running low on, or have run out of, recovery codes, and redirect them to regenerate their codes after they use the last one.