=== 2FA (by ROBOTSTXT) ===
Contributors: robotstxt
Tags: security, two-factor authentication, login, otp
Requires at least: 6.4
Tested up to: 7.0
Requires PHP: 8.0
Stable tag: 1.4.0
License: GPLv3 or later
License URI: https://www.gnu.org/licenses/gpl-3.0.html

Security plugin that adds per-role two-factor authentication to the WordPress login flow.

== Description ==

2FA (by ROBOTSTXT) enforces two-factor authentication on the WordPress login screen. Administrators configure a per-role matrix that specifies exactly which verification methods are required for each role: email codes, authenticator apps (TOTP), or recovery codes.

After the username and password are validated, the login screen redirects to a dedicated verification step. The screen hides the username and password controls, prioritises authenticator apps when enabled, and offers links to switch between methods without restarting the login. Email users can request a fresh code from the same screen.

Users manage their preferences from their profile page. Every method starts unchecked until explicitly confirmed. Activating the authenticator app requires scanning the QR code and entering a valid six-digit code. Recovery codes must be saved and confirmed with one code before activation. Codes are shown in a two-column grid and automatically refresh when the batch is exhausted.

Administrators can remember successful verifications for a configurable duration — per login, daily, weekly, or every 28 days — and lock the schedule so all users follow the global setting. Device and IP fingerprints are stored securely to decide when a fresh challenge is needed.

Multisite is fully supported: network administrators can set and lock enforcement settings across all sites.

== Installation ==

1. Upload the `robotstxt-2fa` directory to `/wp-content/plugins/`.
2. Activate the plugin through the "Plugins" menu in WordPress (or network-activate it for multisite).
3. Open the **2FA** top-level menu in the dashboard and configure which methods are required per role.
4. Users can set up their preferred methods from their profile page.

== Frequently Asked Questions ==

= Is this plugin production ready? =

Yes. Email codes, authenticator apps with on-site QR codes, and recovery codes are all available and tested.

= How do I enable the authenticator QR code? =

Install the optional QR library inside this plugin directory with `composer require bacon/bacon-qr-code:^3.0`. The plugin loads the Composer autoloader automatically when present.

= Can I enforce 2FA for specific roles only? =

Yes. The admin settings page shows a matrix of roles × methods. Check the methods you want to require for each role. Roles with no methods checked leave the choice to the user.

= What happens if a user loses all their verification methods? =

An administrator can edit the user's profile and generate a fresh batch of recovery codes, or disable the role enforcement temporarily while the user regains access.

= Is multisite supported? =

Yes. Activate the plugin at the network level. Network administrators can set and lock enforcement settings; per-site settings are overridden when network settings exist.

== Compatibility ==

* WordPress: 6.4 – 7.0
* PHP: 8.0 – 8.5
* MariaDB: 11.4 or newer

== Changelog ==

= 1.4.0 =

_Release date: 2026-06-05_

**Added**

* Audit Dashboard — top-level admin page with three summary cards (total users, 2FA-enabled count, recent failed attempts), a recent failed attempts table, and a 2FA status column in the Users list.
* Email notifications — four configurable event types: admin-enabled 2FA, login from unrecognised browser/IP, recovery code used (with optional admin copy), and a weekly or monthly activity digest for administrators.
* Application Passwords exemption — REST API and WP-CLI clients authenticated via Application Passwords skip the 2FA browser challenge by default. Configurable in Settings → Access control.
* IP allow list — IPs and CIDR ranges that bypass the 2FA challenge entirely (e.g. office networks).
* IP deny list — IPs and CIDR ranges that are blocked from logging in altogether.
* All IP matching supports both IPv4 and IPv6 CIDR notation.

= 1.3.0 =

_Release date: 2026-06-05_

**Security**

* TOTP codes are now protected against replay attacks within the same 30-second time window. An accepted counter step is recorded in a transient for 90 seconds; a second submission of the same code is rejected.
* The login username is no longer exposed in the `robotstxt-2fa-login` URL query parameter during the verification stage. It is replaced by an opaque 32-character token that resolves to the user server-side. All redirect URLs, hidden form fields, and method-switch links use this token.

**Added**

* WP-CLI command family registered as `wp 2fa`:
  * `wp 2fa status <user_id>` — show 2FA configuration for a user.
  * `wp 2fa enable <user_id> [--method=<method>]` — enable 2FA, optionally specifying the active method.
  * `wp 2fa disable <user_id>` — disable 2FA while preserving stored secrets and codes.
  * `wp 2fa reset-recovery <user_id>` — regenerate recovery codes and display them once.
  * `wp 2fa list [--role=<role>] [--without-2fa] [--format=<format>]` — list users and 2FA status.
  * `wp 2fa force-setup [<user_id>] [--role=<role>] [--method=<method>]` — enforce 2FA for a user or role.
  * `wp 2fa bypass <user_id> [--days=<n>]` — grant a temporary bypass for a locked-out user.
* WP-CLI commands are only loaded when the `WP_CLI` constant is defined and truthy.

= 1.2.1 =

_Release date: 2026-06-05_

**Fixed**

* Recovery code confirmation without checking the method checkbox now correctly activates the method and enables 2FA.
* Fatal error on admin profile pages in multisite — `maybe_handle_frontend_save()` now returns early when `is_admin()` is true.
* OTP and recovery confirmation text inputs were disabled by JS when the Enable toggle was off, preventing values from reaching the server.
* "Regenerate codes" now removes recovery codes from active methods and requires re-confirmation before reactivating.
* Entering a valid OTP code or recovery confirmation code activates the method even without checking the Enable checkbox.

**Security**

* `RECOVERY_REGENERATE_FIELD` POST value now validated with strict `=== '1'` check.

= Previous versions =

For the full changelog see the [changelog.txt](https://git.robotstxt.es/ROBOTSTXT/robotstxt-2fa/raw/branch/main/changelog.txt) file.

== Compliance ==

This plugin adheres to the following security measures and review protocols for each version:

* [WordPress Plugin Handbook](https://developer.wordpress.org/plugins/)
* [WordPress Plugin Security](https://developer.wordpress.org/plugins/wordpress-org/plugin-security/)
* [WordPress APIs Security](https://developer.wordpress.org/apis/security/)
* [WordPress Coding Standards](https://github.com/WordPress/WordPress-Coding-Standards)
* [Plugin Check (PCP)](https://wordpress.org/plugins/plugin-check/)