Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,10 +47,10 @@ The plugin follows a provider pattern. `Two_Factor_Core` owns the login intercep

### Core Files

- **`two-factor.php`** — Entry point. Defines `TWO_FACTOR_DIR` and `TWO_FACTOR_VERSION`, loads all core files (including the settings class), instantiates `Two_Factor_Compat`, and calls `Two_Factor_Core::add_hooks()`. Also registers the wp-admin settings page (Settings → Two-Factor) and the filter callbacks that enforce the site-wide enabled-providers option (`two_factor_filter_enabled_providers`, `two_factor_filter_enabled_providers_for_user`).
- **`two-factor.php`** — Entry point. Defines `TWO_FACTOR_DIR` and `TWO_FACTOR_VERSION`, loads all core files (including the settings class), instantiates `Two_Factor_Compat`, and calls `Two_Factor_Core::add_hooks()`. Also registers the settings page (Settings → Two-Factor; Network Admin → Settings → Two-Factor on multisite) and the filter callbacks that enforce the enabled-providers setting (`two_factor_filter_enabled_providers`, `two_factor_filter_enabled_providers_for_user`).
- **`class-two-factor-core.php`** — Central class. Owns the login flow, user meta, nonce management, rate limiting, session tracking, REST API endpoints, and the user profile settings UI.
- **`class-two-factor-compat.php`** — Compatibility shims for third-party plugins (currently: Jetpack SSO). New integrations go here; the goal is to avoid any plugin-specific logic outside this file.
- **`settings/class-two-factor-settings.php`** — `Two_Factor_Settings`, renders the site-wide settings screen (Settings → Two-Factor, requires `manage_options`) where admins choose which providers are available on the site. Saving writes the `two_factor_enabled_providers` option; enforcement happens via the filters registered in `two-factor.php`, not in this class.
- **`settings/class-two-factor-settings.php`** — `Two_Factor_Settings`, renders the settings screen where admins choose which providers are available: Settings → Two-Factor (`manage_options`) on single site, Network Admin → Settings → Two-Factor (`manage_network_options`) on multisite, where the setting applies to every site and each site's Settings → Two-Factor shows it read-only (`render_network_managed_page()`). Reads and writes go through `Two_Factor_Core::get_enabled_providers_policy()` and `update_enabled_providers_policy()`; on multisite the form is saved by `save_network_settings()` on `network_admin_edit_two_factor_settings`, which keeps only registered providers and refuses an empty selection. Enforcement happens via the filters registered in `two-factor.php`, not in this class.
- **`providers/class-two-factor-provider.php`** — Abstract base class all providers extend. Defines the required interface: `get_label()`, `is_available_for_user()`, `authentication_page()`, `validate_authentication()`, and optional hooks for REST routes, settings UI, and uninstall cleanup.
- **`providers/`** — Concrete providers: `class-two-factor-totp.php`, `class-two-factor-email.php`, `class-two-factor-backup-codes.php`, `class-two-factor-dummy.php`.
- **`includes/`** — Custom `login_header()` and `login_footer()` template functions that replace the WordPress core versions with additional filter hooks. Excluded from PHPCS because they intentionally deviate from core function signatures. Do not modify files in includes/ directly. They are intentionally kept close to WordPress core function signatures to ease future merging into Core. Any functional changes should go through the filter hooks they expose instead.
Expand Down Expand Up @@ -102,7 +102,8 @@ New providers should follow this pattern rather than registering hooks from outs

| Constant | Option Key | Purpose |
|---|---|---|
| `ENABLED_PROVIDERS_OPTION_KEY` | `two_factor_enabled_providers` | Provider class names enabled site-wide via the settings page; never saved means all providers are allowed. |
| `ENABLED_PROVIDERS_OPTION_KEY` | `two_factor_enabled_providers` | Provider class names enabled via the settings page; never saved means all providers are allowed. A network option on multisite (per-site values are ignored there), a site option otherwise. |
| `ENABLED_PROVIDERS_MIGRATED_OPTION_KEY` | `two_factor_enabled_providers_migrated` | Multisite network option recording that the main site's per-site value was carried over to the network option, so that happens only once. |

### REST API

Expand Down
25 changes: 25 additions & 0 deletions TESTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@ npm run composer -- test -- --group backup-codes
npm run composer -- test -- --group providers
npm run composer -- test -- --group core
npm run composer -- test -- --group cli
npm run composer -- test -- --group settings

# Run a single file
npm run composer -- test -- tests/providers/class-two-factor-totp.php
Expand Down Expand Up @@ -212,6 +213,30 @@ Tests the `Two_Factor_CLI_Command` WP-CLI command class. The WP-CLI runtime is n
- `backup-codes generate` — default and `--count` code counts, regeneration replaces the set, enables the provider so codes are usable at login, session destruction when first enabled, unknown-action and missing-argument errors
- `unlock` — clears the login throttle for a rate-limited user; no-op message otherwise

### Settings Policy — `tests/settings/class-two-factor-settings-policy.php`

**Class:** `Tests_Two_Factor_Settings_Policy` · **Group:** `settings`

Tests the enabled-providers setting in both suites:

- `two_factor_get_enabled_providers_option()` matching `Two_Factor_Core::get_enabled_providers_policy()`, and normalization on save
- Uninstall removing the setting as a site option and as a network option
- Failing closed when the setting leaves none of a user's providers registered
- Single site only (skipped on multisite): `manage_options` capability, plain site option, saving from the settings screen, editors can't save, page registered under Settings

### Network Settings — `tests/settings/class-two-factor-settings-multisite.php`

**Class:** `Tests_Two_Factor_Settings_Multisite` · **Groups:** `settings`, `multisite`

Multisite only (skipped on single site):

- Per-site values are ignored; a sub-site administrator can't change the setting through the per-site form or the network save handler
- The network setting applies on every site; super admins save it from the network admin, with a valid nonce, keeping only registered providers, and never with an empty selection
- Carrying the main site's per-site value over to the network option, once
- Pages registered under Network Admin → Settings (`manage_network_options`) and, read-only, under Settings (`manage_options`); all providers listed on the network screen only
- The read-only site page: no form, nothing saved, a link to the network settings for network admins only
- Plugin action link pointing to the network settings

## Test Helpers

- **`tests/bootstrap.php`** — Locates the WordPress test library (via `WP_TESTS_DIR` env var, relative path, or `/tmp/wordpress-tests-lib`), loads the plugin via `muplugins_loaded`, then boots the WP test environment.
Expand Down
117 changes: 114 additions & 3 deletions class-two-factor-core.php
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,16 @@ class Two_Factor_Core {
*/
const ENABLED_PROVIDERS_OPTION_KEY = 'two_factor_enabled_providers';

/**
* The network option key recording that the enabled providers were carried over from
* the main site to the network-wide setting on multisite.
*
* @since 0.18.0
*
* @type string
*/
const ENABLED_PROVIDERS_MIGRATED_OPTION_KEY = 'two_factor_enabled_providers_migrated';

/**
* The user meta nonce key.
*
Expand Down Expand Up @@ -160,7 +170,9 @@ public static function add_hooks( $compat ) {
add_filter( 'two_factor_providers', array( __CLASS__, 'enable_dummy_method_for_debug' ) );

// Add Settings link to plugin action links.
add_filter( 'plugin_action_links_' . plugin_basename( TWO_FACTOR_DIR . 'two-factor.php' ), array( __CLASS__, 'add_settings_action_link' ) );
$plugin_basename = plugin_basename( TWO_FACTOR_DIR . 'two-factor.php' );
add_filter( 'plugin_action_links_' . $plugin_basename, array( __CLASS__, 'add_settings_action_link' ) );
add_filter( 'network_admin_plugin_action_links_' . $plugin_basename, array( __CLASS__, 'add_settings_action_link' ) );

$compat->init();
}
Expand Down Expand Up @@ -254,6 +266,10 @@ public static function uninstall() {
delete_option( $option_key );
}

// The enabled providers are a network option on multisite; on single site this deletes the same option again.
delete_network_option( null, self::ENABLED_PROVIDERS_OPTION_KEY );
delete_network_option( null, self::ENABLED_PROVIDERS_MIGRATED_OPTION_KEY );

foreach ( $user_meta_keys as $meta_key ) {
delete_metadata( 'user', 0, $meta_key, '', true );
}
Expand Down Expand Up @@ -399,6 +415,99 @@ public static function enable_dummy_method_for_debug( $methods ) {
return $methods;
}

/**
* Get the providers enabled in the plugin settings.
*
* On multisite this is a network-wide setting, stored as a network option; values saved
* per site are ignored. On single site installs it is a regular option.
*
* @since 0.18.0
*
* @return array|null Enabled provider keys, possibly empty, or null when the setting has never
* been saved, meaning all providers are allowed.
*/
public static function get_enabled_providers_policy() {
if ( is_multisite() ) {
$enabled = get_network_option( null, self::ENABLED_PROVIDERS_OPTION_KEY, null );

if ( null === $enabled && self::maybe_migrate_enabled_providers_policy() ) {
$enabled = get_network_option( null, self::ENABLED_PROVIDERS_OPTION_KEY, null );
}
} else {
$enabled = get_option( self::ENABLED_PROVIDERS_OPTION_KEY, null );
}

if ( null === $enabled ) {
return null; // Never saved — allow everything.
}

return is_array( $enabled ) ? $enabled : array();
}

/**
* Save the providers enabled in the plugin settings.
*
* @since 0.18.0
*
* @param array $providers Provider keys to enable.
* @return bool True if the value was updated, false otherwise.
*/
public static function update_enabled_providers_policy( array $providers ) {
$providers = array_values( array_unique( array_filter( $providers, 'is_string' ) ) );

if ( ! is_multisite() ) {
return update_option( self::ENABLED_PROVIDERS_OPTION_KEY, $providers );
}

// A saved network setting takes precedence over anything left to carry over from the main site.
update_network_option( null, self::ENABLED_PROVIDERS_MIGRATED_OPTION_KEY, 1 );

return update_network_option( null, self::ENABLED_PROVIDERS_OPTION_KEY, $providers );
}

/**
* Get the capability required to view and change the plugin settings.
*
* @since 0.18.0
*
* @return string
*/
public static function policy_capability() {
return is_multisite() ? 'manage_network_options' : 'manage_options';
}

/**
* Carry the main site's enabled providers over to the network-wide setting, once.
*
* Before 0.18.0 the enabled providers were saved per site on multisite, too. Only the main
* site's value is carried over; values saved on other sites are ignored.
*
* @since 0.18.0
*
* @return bool True if the network setting was saved from the main site's value.
*/
private static function maybe_migrate_enabled_providers_policy() {
if ( get_network_option( null, self::ENABLED_PROVIDERS_MIGRATED_OPTION_KEY ) ) {
return false;
}

update_network_option( null, self::ENABLED_PROVIDERS_MIGRATED_OPTION_KEY, 1 );

// Without a main site, get_blog_option() would read the current site's value instead.
$main_site_id = get_main_site_id();
if ( ! $main_site_id ) {
return false;
}

$main_site_enabled = get_blog_option( $main_site_id, self::ENABLED_PROVIDERS_OPTION_KEY, null );

if ( ! is_array( $main_site_enabled ) ) {
return false;
}

return self::update_enabled_providers_policy( $main_site_enabled );
}

/**
* Add Plugin and User Settings link to the plugin action links on the Plugins screen.
*
Expand All @@ -408,7 +517,9 @@ public static function enable_dummy_method_for_debug( $methods ) {
* @return string[] Modified array with the User Settings link added.
*/
public static function add_settings_action_link( $links ) {
$plugin_settings_url = admin_url( 'options-general.php?page=two-factor-settings' );
$plugin_settings_url = is_multisite()
? network_admin_url( 'settings.php?page=two-factor-settings' )
: admin_url( 'options-general.php?page=two-factor-settings' );
$plugin_settings_link = sprintf(
'<a href="%s">%s</a>',
esc_url( $plugin_settings_url ),
Expand All @@ -425,7 +536,7 @@ public static function add_settings_action_link( $links ) {
// Show plugin settings first, then user settings.
array_unshift( $links, $user_settings_link );

if ( current_user_can( 'manage_options' ) ) {
if ( current_user_can( self::policy_capability() ) ) {
array_unshift( $links, $plugin_settings_link );
}

Expand Down
4 changes: 2 additions & 2 deletions readme.txt
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ The Two-Factor plugin adds an extra layer of security to your WordPress login by

### For Site Administrators

- **Plugin settings**: The plugin provides a settings page under "Settings → Two-Factor" to configure which providers should be disabled site-wide.
- **Plugin settings**: The plugin provides a settings page under "Settings → Two-Factor" to configure which providers should be disabled site-wide. On Multisite, super admins find it under "Network Admin → Settings → Two-Factor", and it applies to every site in the network; "Settings → Two-Factor" on each site shows it read-only.
- **User management**: Administrators can configure 2FA for other users by editing their profiles
- **Security recommendations**: Encourage users to enable backup methods to prevent account lockouts

Expand Down Expand Up @@ -170,7 +170,7 @@ Yes. For passkeys and hardware security keys, you can install the [Two-Factor Pr

= Does this plugin work on WordPress Multisite? =

Yes. The Two-Factor plugin is compatible with WordPress Multisite. Each user configures their own 2FA settings via their profile, and because authentication codes are stored in WordPress user meta, the configuration is tied to the user account and valid across all sites in the network. However, there are no network-wide settings — a super admin cannot enforce or configure 2FA globally from the Network Admin dashboard. To manage 2FA for a specific user, edit their profile on any site where they have an account.
Yes. The Two-Factor plugin is compatible with WordPress Multisite. Each user configures their own 2FA settings via their profile, and because authentication codes are stored in WordPress user meta, the configuration is tied to the user account and valid across all sites in the network. Which two-factor providers are available is a network-wide setting as well: super admins choose them under Network Admin → Settings → Two-Factor, and the choice applies to every site. There is no network-wide setting to enforce 2FA for users. To manage 2FA for a specific user, edit their profile on any site where they have an account.

= How do I disable 2FA for a user who is locked out? =

Expand Down
Loading