faisalahammad · faisalahammad · Jul 11, 2024 · Jul 11, 2024 · Jul 12, 2024 · Sep 23, 2024
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -15,16 +15,16 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
 
       - name: Setup Node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
         with:
           cache: 'npm'
           node-version-file: '.nvmrc'
 
       - name: Setup PHP and Composer
-        uses: shivammathur/setup-php@v2
+        uses: shivammathur/setup-php@accd6127cb78bee3e8082180cb391013d204ef9f # v2.37.0
         with:
           php-version: '5.6'
           tools: composer:v2
@@ -36,7 +36,7 @@ jobs:
         run: npm run build
 
       - name: WordPress.org asset and readme update
-        uses: 10up/action-wordpress-plugin-asset-update@stable
+        uses: 10up/action-wordpress-plugin-asset-update@2480306f6f693672726d08b5917ea114cb2825f7 # v2.2.0
         if: github.ref_name == 'trunk'
         env:
           # Note: this action doesn't support BUILD_DIR so it pushes the raw readme.txt
@@ -46,7 +46,7 @@ jobs:
 
       - name: WordPress.org deploy
         id: deploy
-        uses: 10up/action-wordpress-plugin-deploy@stable
+        uses: 10up/action-wordpress-plugin-asset-update@2480306f6f693672726d08b5917ea114cb2825f7 # v2.2.0
         if: startsWith( github.ref, 'refs/tags/' )
         with:
           generate-zip: true
@@ -57,7 +57,7 @@ jobs:
 
 
       - name: Upload release asset
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2.6.1
         if: startsWith( github.ref, 'refs/tags/' )
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

diff --git a/.github/workflows/props-bot.yml b/.github/workflows/props-bot.yml
@@ -71,7 +71,7 @@ jobs:
 
     steps:
       - name: Gather a list of contributors
-        uses: WordPress/props-bot-action@trunk
+        uses: WordPress/props-bot-action@992186595bc18334988a431c317237c48b7711a5 # v1.0.0
         with:
           format: 'git'
 

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -15,10 +15,10 @@ jobs:
         runs-on: ubuntu-24.04
         steps:
             - name: Checkout
-              uses: actions/checkout@v4
+              uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
 
             - name: Setup Node
-              uses: actions/setup-node@v4
+              uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
               with:
                 cache: 'npm'
                 node-version-file: '.nvmrc'
@@ -37,15 +37,15 @@ jobs:
         runs-on: ubuntu-24.04
         steps:
             - name: Checkout
-              uses: actions/checkout@v4
+              uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
 
             - name: Setup PHP and Composer
-              uses: shivammathur/setup-php@v2
+              uses: shivammathur/setup-php@accd6127cb78bee3e8082180cb391013d204ef9f # v2.37.0
               with:
                 php-version: '8.3'
 
             - name: Setup Node
-              uses: actions/setup-node@v4
+              uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
               with:
                 cache: 'npm'
                 node-version-file: '.nvmrc'
@@ -94,15 +94,15 @@ jobs:
 
         steps:
             - name: Checkout
-              uses: actions/checkout@v4
+              uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
 
             - name: Setup PHP
-              uses: shivammathur/setup-php@v2
+              uses: shivammathur/setup-php@accd6127cb78bee3e8082180cb391013d204ef9f # v2.37.0
               with:
                 php-version: '8.3'
 
             - name: Setup Node
-              uses: actions/setup-node@v4
+              uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
               with:
                 cache: 'npm'
                 node-version-file: '.nvmrc'
@@ -111,7 +111,7 @@ jobs:
               run: npm install
 
             - name: Start the Docker testing environment
-              uses: nick-fields/retry@v3
+              uses: nick-fields/retry@ce71cc2ab81d554ebbe88c79ab5975992d79ba08 # v3.0.2
               with:
                 timeout_minutes: 10
                 max_attempts: 3
@@ -135,15 +135,15 @@ jobs:
         runs-on: ubuntu-24.04
         steps:
             - name: Checkout
-              uses: actions/checkout@v4
+              uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
 
             - name: Setup PHP
-              uses: shivammathur/setup-php@v2
+              uses: shivammathur/setup-php@accd6127cb78bee3e8082180cb391013d204ef9f # v2.37.0
               with:
                 php-version: '8.3'
 
             - name: Setup Node
-              uses: actions/setup-node@v4
+              uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
               with:
                 cache: 'npm'
                 node-version-file: '.nvmrc'

diff --git a/.wordpress-org/blueprints/blueprint.json b/.wordpress-org/blueprints/blueprint.json
@@ -1,6 +1,6 @@
 {
 	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
-	"landingPage": "/wp-admin/profile.php#application-passwords-section",
+	"landingPage": "/wp-admin/profile.php#two-factor-options",
 	"preferredVersions": {
 		"php": "7.4",
 		"wp": "latest"

diff --git a/.wordpress-org/screenshot-1.png b/.wordpress-org/screenshot-1.png
diff --git a/.wordpress-org/screenshot-2.png b/.wordpress-org/screenshot-2.png
diff --git a/.wordpress-org/screenshot-3.png b/.wordpress-org/screenshot-3.png
diff --git a/.wordpress-org/screenshot-4.png b/.wordpress-org/screenshot-4.png
diff --git a/.wordpress-org/screenshot-5.png b/.wordpress-org/screenshot-5.png
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,109 @@
+# AI Instructions
+
+Two-Factor is a WordPress plugin, potentially eventually merging into WordPress Core, that provides Multi-Factor Authentication for WordPress interactive logins. It is network-enabled and can be activated across a WordPress multisite network.
+
+## Development Environment
+
+Requires Docker. Uses `@wordpress/env` to run a local WordPress install in containers.
+
+```bash
+npm install
+npm run build
+npm run env start
+```
+
+For code coverage support: `npm run env start -- --xdebug=coverage`
+
+`npm test` and `npm run composer` are wrappers that execute commands inside the `tests-cli` wp-env container at the plugin path. Tests must be run through these wrappers, not directly with `phpunit`.
+
+## Commands
+
+### Testing
+
+@TESTS.md
+
+### Linting & Static Analysis
+
+```bash
+npm run lint            # all linters (PHP, CSS, JS)
+npm run lint:php        # PHPCS with WordPress + VIP-Go standards
+npm run lint:phpstan    # PHPStan static analysis (level 0)
+npm run lint:css        # wp-scripts lint-style
+npm run lint:js         # wp-scripts lint-js
+npm run format          # auto-fix PHPCS and JS/CSS issues
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+The Grunt build copies all distributable files to `dist/` (respecting `.distignore`) and copies `node_modules/qrcode-generator/qrcode.js` into `dist/includes/`. The `qrcode-generator` package is a **runtime JS dependency** — it is not present in `includes/` in the source tree and must be built before the plugin is usable in a browser context. Always run `npm run build` after a fresh checkout.
+
+## Architecture
+
+The plugin follows a provider pattern. `Two_Factor_Core` owns the login interception and orchestration; individual providers handle their own credential prompts and validation.
+
+### Core Files
+
+- **`two-factor.php`** — Entry point. Defines `TWO_FACTOR_DIR` and `TWO_FACTOR_VERSION`, loads all core files, instantiates `Two_Factor_Compat`, and calls `Two_Factor_Core::add_hooks()`.
+- **`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.
+- **`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.
+- **`tests/`** — PHPUnit tests. See [TESTS.md](TESTS.md).
+
+### Login Flow
+
+1. User submits username/password.
+2. `Two_Factor_Core::filter_authenticate()` runs at priority **31** on the `authenticate` filter (one above WP core's 30). If 2FA is required, it intercepts the `WP_User` object to prevent WP from issuing auth cookies.
+3. `Two_Factor_Core::wp_login()` runs at priority `PHP_INT_MAX` on `wp_login`, renders the 2FA prompt, and exits.
+4. On 2FA form submission, `login_form_validate_2fa` action handles validation and issues the final auth cookie only if the second factor passes.
+
+Auth cookies set during the password phase are tracked via `collect_auth_cookie_tokens` and invalidated before the 2FA step.
+
+### Provider Registration
+
+Providers are registered via the `two_factor_providers` filter, which receives and returns an array of the form:
+
+```php
+array( 'Class_Name' => '/absolute/path/to/class-file.php' )
+```
+
+The key (class name) is what gets stored in user meta. A per-provider `two_factor_provider_classname_{$provider_key}` filter allows swapping a provider's implementing class without changing its key. Use `two_factor_providers_for_user` to control which providers are available to a specific user.
+
+**The `Two_Factor_Dummy` provider is only available when `WP_DEBUG` is `true`.** It is removed at runtime by `enable_dummy_method_for_debug()` in all other environments. If a dummy provider isn't appearing, check `WP_DEBUG`.
+
+### Provider Self-Registration Pattern
+
+Each concrete provider registers its own hooks in its constructor:
+
+- REST routes → `rest_api_init`
+- Assets → `admin_enqueue_scripts`, `wp_enqueue_scripts`
+- User profile UI section → `two_factor_user_options_{ClassName}` action
+
+New providers should follow this pattern rather than registering hooks from outside the class.
+
+### Key User Meta (constants on `Two_Factor_Core`)
+
+| Constant | Meta Key | Purpose |
+|---|---|---|
+| `PROVIDER_USER_META_KEY` | `_two_factor_provider` | Active provider class name |
+| `ENABLED_PROVIDERS_USER_META_KEY` | `_two_factor_enabled_providers` | Array of enabled provider class names |
+| `USER_META_NONCE_KEY` | `_two_factor_nonce` | Login nonce |
+| `USER_RATE_LIMIT_KEY` | `_two_factor_last_login_failure` | Rate limiting timestamp |
+| `USER_FAILED_LOGIN_ATTEMPTS_KEY` | `_two_factor_failed_login_attempts` | Failed attempt count |
+| `USER_PASSWORD_WAS_RESET_KEY` | `_two_factor_password_was_reset` | Flags compromised-password reset |
+
+### REST API
+
+Namespace: `two-factor/1.0` (constant `Two_Factor_Core::REST_NAMESPACE`). Each provider that exposes REST endpoints registers its own routes in `register_rest_routes()` called from its constructor.
+
+## Code Standards
+
+- PHP 7.2+ compatibility required; enforced by PHPCompatibilityWP.
+- Follows WordPress coding standards (WPCS) and WordPress-VIP-Go rules.
+- `includes/` is excluded from PHPCS — those files intentionally override core functions.
+- The codebase does not fully pass all PHPCS checks (known issue [#437](https://github.com/WordPress/two-factor/issues/437)). Do not treat existing violations as license to introduce new ones.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,7 +2,62 @@
 
 All notable changes to this project will be documented in this file, per [the Keep a Changelog standard](http://keepachangelog.com/), and will adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased] - TBD
+## [0.15.0] - 2026-02-13
+
+### Breaking Changes
+
+- Trigger two-factor flow only when expected by @kasparsd in [#660](https://github.com/WordPress/two-factor/pull/660) and [#793](https://github.com/WordPress/two-factor/pull/793).
+
+### New Features
+
+- Include user IP address and contextual warning in two-factor code emails by @todeveni in [#728](https://github.com/WordPress/two-factor/pull/728)
+- Consistent user experience for TOTP setup by @kasparsd in [#792](https://github.com/WordPress/two-factor/pull/792)
+- Optimize email text for TOTP by @masteradhoc in [#789](https://github.com/WordPress/two-factor/pull/789)
+- Add "Settings" action link to plugin list for quick access to profile by @hardikRathi in [#740](https://github.com/WordPress/two-factor/pull/740)
+- Additional form hooks by @eric-michel in [#742](https://github.com/WordPress/two-factor/pull/742)
+- Full RFC6238 Compatibility by @ericmann in [#656](https://github.com/WordPress/two-factor/pull/656)
+
+### Documentation
+
+- `@since` docs by @masteradhoc in [#781](https://github.com/WordPress/two-factor/pull/781)
+- Update user and admin docs, prepare for more screenshots by @jeffpaul in [#701](https://github.com/WordPress/two-factor/pull/701)
+- Add changelog & credits, update release notes by @jeffpaul in [#696](https://github.com/WordPress/two-factor/pull/696)
+- Clear readme.txt by @masteradhoc in [#785](https://github.com/WordPress/two-factor/pull/785)
+- Add date and time information above TOTP setup instructions by @masteradhoc in [#772](https://github.com/WordPress/two-factor/pull/772)
+- Clarify TOTP setup instructions by @masteradhoc in [#763](https://github.com/WordPress/two-factor/pull/763)
+- Update RELEASING.md by @jeffpaul in [#787](https://github.com/WordPress/two-factor/pull/787)
+
+### Development Updates
+
+- Pause deploys to SVN trunk for merges to `master` by @kasparsd in [#738](https://github.com/WordPress/two-factor/pull/738)
+- Fix CI checks for PHP compatability by @kasparsd in [#739](https://github.com/WordPress/two-factor/pull/739)
+- Fix Playground refs by @kasparsd in [#744](https://github.com/WordPress/two-factor/pull/744)
+- Persist existing translations when introducing new helper text in emails by @kasparsd in [#745](https://github.com/WordPress/two-factor/pull/745)
+- Fix `missing_direct_file_access_protection` by @masteradhoc in [#760](https://github.com/WordPress/two-factor/pull/760)
+- Fix `mismatched_plugin_name` by @masteradhoc in [#754](https://github.com/WordPress/two-factor/pull/754)
+- Introduce Props Bot workflow by @jeffpaul in [#749](https://github.com/WordPress/two-factor/pull/749)
+- Plugin Check: Fix Missing $domain parameter by @masteradhoc in [#753](https://github.com/WordPress/two-factor/pull/753)
+- Tests: Update to supported WP version 6.8 by @masteradhoc in [#770](https://github.com/WordPress/two-factor/pull/770)
+- Fix PHP 8.5 deprecated message by @masteradhoc in [#762](https://github.com/WordPress/two-factor/pull/762)
+- Exclude 7.2 and 7.3 checks against trunk by @masteradhoc in [#769](https://github.com/WordPress/two-factor/pull/769)
+- Fix Plugin Check errors: `MissingTranslatorsComment` & `MissingSingularPlaceholder` by @masteradhoc in [#758](https://github.com/WordPress/two-factor/pull/758)
+- Add PHP 8.5 tests for latest and trunk version of WP by @masteradhoc in [#771](https://github.com/WordPress/two-factor/pull/771)
+- Add `phpcs:ignore` for falsepositives by @masteradhoc in [#777](https://github.com/WordPress/two-factor/pull/777)
+- Fix(totp): `otpauth` link in QR code URL by @sjinks in [#784](https://github.com/WordPress/two-factor/pull/784)
+- Update deploy.yml by @masteradhoc in [#773](https://github.com/WordPress/two-factor/pull/773)
+- Update required WordPress Version by @masteradhoc in [#765](https://github.com/WordPress/two-factor/pull/765)
+- Fix: ensure execution stops after redirects by @sjinks in [#786](https://github.com/WordPress/two-factor/pull/786)
+- Fix `WordPress.Security.EscapeOutput.OutputNotEscaped` errors by @masteradhoc in [#776](https://github.com/WordPress/two-factor/pull/776)
+
+### Dependency Updates
+
+- Bump qs and express by @dependabot[bot] in [#746](https://github.com/WordPress/two-factor/pull/746)
+- Bump lodash from 4.17.21 to 4.17.23 by @dependabot[bot] in [#750](https://github.com/WordPress/two-factor/pull/750)
+- Bump lodash-es from 4.17.21 to 4.17.23 by @dependabot[bot] in [#748](https://github.com/WordPress/two-factor/pull/748)
+- Bump phpunit/phpunit from 8.5.44 to 8.5.52 by @dependabot[bot] in [#755](https://github.com/WordPress/two-factor/pull/755)
+- Bump symfony/process from 5.4.47 to 5.4.51 by @dependabot[bot] in [#756](https://github.com/WordPress/two-factor/pull/756)
+- Bump qs and body-parser by @dependabot[bot] in [#782](https://github.com/WordPress/two-factor/pull/782)
+- Bump webpack from 5.101.3 to 5.105.0 by @dependabot[bot] in [#780](https://github.com/WordPress/two-factor/pull/780)
 
 ## [0.14.2] - 2025-12-11
 ### New Features
@@ -220,9 +275,9 @@ All notable changes to this project will be documented in this file, per [the Ke
 ## [0.2.0] - 2018-10-16
 - Add developer tools for deploying to WP.org manually.
 
-[Unreleased]: https://github.com/WordPress/two-factor/compare/master...develop
-[0.14.0]: https://github.com/WordPress/two-factor/compare/0.14.1...0.14.2
-[0.14.0]: https://github.com/WordPress/two-factor/compare/0.14.0...0.14.1
+[0.15.0]: https://github.com/WordPress/two-factor/compare/0.14.1...0.15.0
+[0.14.2]: https://github.com/WordPress/two-factor/compare/0.14.1...0.14.2
+[0.14.1]: https://github.com/WordPress/two-factor/compare/0.14.0...0.14.1
 [0.14.0]: https://github.com/WordPress/two-factor/compare/0.13.0...0.14.0
 [0.13.0]: https://github.com/WordPress/two-factor/compare/0.12.0...0.13.0
 [0.12.0]: https://github.com/WordPress/two-factor/compare/0.11.0...0.12.0

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md