#906: add early notice for soon exhausting recovery codes

[masteradhoc]

What?

Adds a proactive "running low on Recovery Codes" admin notice that appears before a user exhausts their codes, rather than only warning them once they are completely out. While more than the threshold of codes remain, nothing shows; at or below the threshold (default 2) a dismissible-styled warning appears; at zero the existing error notice still shows.

Fixes #906

Why?

Today Two_Factor_Backup_Codes::admin_notices() only surfaces a notice after the user has used their last Recovery Code (balance = 0). By then the user has already lost their self-service path back into the account. There is no earlier nudge to regenerate, so it is easy to drift down to zero unnoticed and get locked out.

This closes gap #5 in the account-recovery roadmap (account-recovery-future-improvements.md) and is the low-balance-warning half of item C / Phase 1 in that document. It strengthens the one self-service recovery path users already have, without adding any new bypass or attack surface.

Related discussion:

• Account recovery after losing 2fa key #621 — Account recovery after losing 2FA key
• Notify user/admin when sensitive events occur #476 — Notify users on sensitive events

How?

admin_notices() was restructured from a single zero-codes check into three states, keyed on codes_remaining_for_user():

Recovery Codes remaining	Notice	CSS class
more than threshold	none	—
1 – threshold (default 2)	warning — running low	notice notice-warning
0	error — out of codes (existing)	error

• A new LOW_CODES_THRESHOLD constant (default 2) sets the warning point.
• A new two_factor_backup_codes_low_threshold filter lets operators tune it per-site (receives the count and the WP_User). The name follows the existing internal two_factor_backup_code_length convention.
• The warning message is translatable and uses _n() for singular/plural ("1 recovery code" vs "2 recovery codes"), with the count run through number_format_i18n().
• The existing "provider not enabled" early-return guard is unchanged, so notices only show when the Recovery Codes provider is active for the current user.
• All links point to /wp-admin/profile.php#two-factor-backup-codes, matching the existing notice.

Behaviour by state:

• More than two Recovery Codes left — no notice.

• Two Recovery Codes left

• One Recovery Code left

• No Recovery Codes left, permanent error (even when logging in over another method)

Link goes to /wp-admin/profile.php#two-factor-backup-codes.

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 4.8
Used for: Drafting the issue/PR text and the initial implementation of the low-balance notice. Final implementation and wording were reviewed and edited by me.

Testing Instructions

1. Enable the Recovery Codes provider for your user and generate a set of codes.
2. Use Recovery Codes at login until more than 2 remain — confirm no notice appears in wp-admin.
3. Continue until exactly 2 remain — confirm the yellow "running low" warning appears with the correct count and a working "Regenerate your codes" link to profile.php#two-factor-backup-codes.
4. Continue until 1 remains — confirm the warning shows the singular "1 recovery code left".
5. Use the last code so 0 remain — confirm the existing red error notice appears instead.
6. (Optional) Add add_filter( 'two_factor_backup_codes_low_threshold', fn() => 5 ); and confirm the warning now triggers at 5 or fewer codes.
7. Confirm no notice appears for a user who does not have the Recovery Codes provider enabled.

Changelog Entry

Added - Admin notice that warns users when their Recovery Codes are running low, before they run out, with a two_factor_backup_codes_low_threshold filter to tune the threshold.

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