Skip to content

Fix fatal error when the stored TOTP secret is not base32 - #1038

Open
faisalahammad wants to merge 1 commit into
WordPress:masterfrom
faisalahammad:fix/totp-invalid-stored-secret
Open

faisalahammad wants to merge 1 commit into
WordPress:masterfrom
faisalahammad:fix/totp-invalid-stored-secret

Conversation

@faisalahammad

@faisalahammad faisalahammad commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

What?

Stops a fatal error when a user's stored TOTP secret is not valid base32. validate_code_for_user() now rejects the code instead of letting base32_decode() throw.

Addresses #747 (closed as "not planned", but the fatal error is in Two-Factor and still happens on 0.17.0).

Why?

Solid Security (now Kadence Security) is a fork of this plugin and uses the same meta keys. Since 8.1.7 it encrypts the TOTP secret before saving it to _two_factor_totp_key, so the stored value looks like $t1$....

When a site turns off Kadence Security and turns on Two-Factor:

  1. _two_factor_enabled_providers already contains Two_Factor_Totp, so the user counts as having 2FA. The Profile page asks them to revalidate.
  2. is_available_for_user() only checks that the secret is not empty, so the TOTP prompt is shown.
  3. Entering any code calls calc_totp() → base32_decode(), which throws Exception: Invalid characters in the base32 string. Nothing catches it, so wp-login.php?action=revalidate_2fa (and normal 2FA login) shows a critical error.

Real report, WordPress 7.1.4, PHP 8.5, Two-Factor 0.17.0:

Uncaught Exception: Invalid characters in the base32 string. in .../providers/class-two-factor-totp.php:850
#0 class-two-factor-totp.php(715): Two_Factor_Totp::base32_decode()
#1 class-two-factor-totp.php(626): Two_Factor_Totp::calc_totp()
#2 class-two-factor-totp.php(540): Two_Factor_Totp::get_authcode_valid_ticktime()
#3 class-two-factor-totp.php(526): Two_Factor_Totp->validate_code_for_user()
#4 class-two-factor-core.php(2143): Two_Factor_Totp->validate_authentication()
#5 class-two-factor-core.php(2023): Two_Factor_Core::process_provider()
#6 class-two-factor-core.php(1979): Two_Factor_Core::revalidate_login_form_2fa()

How?

validate_code_for_user() checks the stored secret with the existing is_valid_key_format() before computing codes, and returns false if the check fails. The secret is uppercased first because base32_decode() accepts lowercase, so lowercase secrets keep working.

is_available_for_user() is deliberately unchanged. If an unreadable secret made TOTP "unavailable", a user whose only method is TOTP would fall back to password-only login. With this change the check fails closed: the user sees "Invalid verification code." and can use another enabled method, or an admin can reset TOTP (for example with wp two-factor disable).

Tests added:

  • A non-base32 stored secret: TOTP stays available, and validate_code_for_user() returns false without throwing.
  • A lowercase base32 stored secret still validates.

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus
Used for: Tracing the root cause, writing the fix and tests, and reproducing the bug in wp-env. I reviewed and tested the change.

Testing Instructions

  1. Log in as an admin with 2FA off.
  2. Simulate data left behind by Kadence Security:
    wp user meta update 1 _two_factor_enabled_providers '["Two_Factor_Totp"]' --format=json
    wp user meta update 1 _two_factor_provider Two_Factor_Totp
    wp user meta update 1 _two_factor_totp_key '$t1$c2VjcmV0K2NpcGhlcnRleHQ='
    
  3. Go to Users → Profile → Revalidate now, and enter any 6-digit code.
  4. Before this change: critical error (Invalid characters in the base32 string). After: "Invalid verification code." is shown on the login form.

Automated: npm test passes on both single site and multisite (355 tests). PHPStan and PHPCS report no errors on the changed files.

Screenshots or screencast

Before After
Fatal error: Uncaught Exception: Invalid characters in the base32 string. ERROR: Invalid verification code.

Changelog Entry

Fixed - Fatal error when entering a TOTP code for a user whose stored secret is not base32, such as an encrypted secret left by Solid / Kadence Security.

Open WordPress Playground Preview

…ling

Solid / Kadence Security store an encrypted TOTP secret under the same
_two_factor_totp_key meta key. After switching to Two-Factor, entering a
code at login or revalidation threw an uncaught base32_decode() exception.

validate_code_for_user() now returns false when the stored secret is not
base32. TOTP stays available, so the user does not drop to one factor.
@github-actions

github-actions Bot commented Nov 9, 2026

Copy link
Copy Markdown

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>

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

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are reported for the change addressing fatal errors from invalid stored TOTP secrets.

No open issues 🎉

What changed in this PR

Prevents fatal errors during TOTP verification when a stored secret is not valid base32, addressing the migration scenario reported in #747.

Changes:

  • Validates stored secrets before calculating codes, returning false for invalid secrets while preserving lowercase-secret support.
  • Keeps TOTP available so invalid secrets do not bypass two-factor authentication, with regression tests for both cases.
File Description
tests/​providers/​class-two-factor-totp.php Adds tests for invalid stored secrets, continued TOTP availability, and lowercase secrets.
providers/​class-two-factor-totp.php Rejects invalid stored secrets before TOTP calculation can throw.

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants