Build: build/2026-09-28

.foundry/feedback.jsonl

@@ -0,0 +1 @@
+{"at":"2026-09-28T19:44:52.482Z","stage":"controller","round":0,"category":"halt","message":"Run halted: P0-01 blocked at operator level. (1) The permission classifier denied twice (Untrusted Code Integration) the commands that add the third-party GitHub plugin ericmann/secrets-api#v0.2.1 to .wp-env.json and start wp-env. (2) Verify commands cannot start: node_modules is missing (npm-run-all, wp-env, phpcs not found; exit 127), so nothing can be tested. Needed: allow this dependency (or add a Bash permission rule), and run npm install and composer install. No source changes were made.","source":"auto"}

.foundry/state.json

@@ -0,0 +1,33 @@
+{
+  "round": 1,
+  "implemented": true,
+  "reviewed": true,
+  "verdict": "APPROVED",
+  "summarized": true,
+  "halted": null,
+  "preexistingUntracked": [],
+  "policies": {
+    "signing": "auto",
+    "push": true,
+    "pr": "draft",
+    "feedback": true
+  },
+  "signing": "on",
+  "rounds": [
+    {
+      "round": 1,
+      "fixTasks": 1,
+      "unblocked": 0,
+      "verdict": "CHANGES REQUESTED",
+      "nonConverging": false,
+      "at": "2026-09-28T20:18:21.733Z"
+    },
+    {
+      "round": 2,
+      "fixTasks": 0,
+      "unblocked": 0,
+      "verdict": "APPROVED",
+      "at": "2026-09-28T20:23:47.438Z"
+    }
+  ]
+}

.gitignore

@@ -9,3 +9,4 @@
 /npm-debug.log
 .phpunit.result.cache*
 phpstan.neon
+.foundry/implement.lock

.wp-env.json

@@ -8,8 +8,13 @@
         "WP_TESTS_EMAIL": "admin@example.org",
         "WP_TESTS_DOMAIN": "example.org",
         "WP_SITEURL": "https://example.org",
-        "WP_HOME": "https://example.org"
-      }
+        "WP_HOME": "https://example.org",
+        "WP_SECRETS_KEY": "AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE="
+      },
+      "plugins": [
+        ".",
+        "ericmann/secrets-api#v0.2.1"
+      ]
     }
   }
 }

AGENTS.md

@@ -27,7 +27,7 @@ For code coverage support: `npm run env start -- --xdebug=coverage`
 ```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 2)
+npm run lint:phpstan    # PHPStan static analysis (level 5)
 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
@@ -50,8 +50,9 @@ The plugin follows a provider pattern. `Two_Factor_Core` owns the login intercep
 - **`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`).
 - **`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.
+- **`class-two-factor-secrets.php`** — `Two_Factor_Secrets`, a static adapter and the only place Two-Factor calls the WordPress Secrets API (`wp_get_network_secret()` and friends). Secrets are always network scope, on single site and multisite alike. A per-user marker in user meta records which network holds the secret. New writes and migration are gated by the `two_factor_use_secrets_api` filter; reads of already-migrated users are not.
 - **`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.
-- **`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/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. It also defines `is_enrolled_but_unavailable_for_user()` (a provider the user enrolled whose credential cannot currently be used; core then forces the fallback provider instead of dropping to single factor) and `uninstall_user_data()` (delete per-user data held outside user meta during uninstall).
 - **`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).
@@ -87,6 +88,8 @@ Each concrete provider registers its own hooks in its constructor:
 
 New providers should follow this pattern rather than registering hooks from outside the class.
 
+The one exception is data that outlives the provider being enabled. `Two_Factor_Totp::register_secret_lifecycle_hooks()` registers user-deletion cleanup, the unreachable-secrets admin notice and the Site Health test statically, and `two-factor.php` always loads the TOTP class and calls it, so these keep working when an admin turns TOTP off in Settings → Two-Factor.
+
 ### Key User Meta (constants on `Two_Factor_Core`)
 
 | Constant | Meta Key | Purpose |
@@ -97,13 +100,28 @@ New providers should follow this pattern rather than registering hooks from outs
 | `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 |
+| `Two_Factor_Totp::SECRET_NETWORK_META_KEY` | `_two_factor_totp_key_network` | Marker that the TOTP secret lives in the Secrets API; holds the network ID. A constant on `Two_Factor_Totp`, not `Two_Factor_Core`. |
 
 ### Key Site Options (constants on `Two_Factor_Core`)
 
 | 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. |
 
+### Secrets API hooks
+
+- `two_factor_use_secrets_api` filter (`$enabled`, `$user_id`) controls writes and migration only; already-migrated users are still read from the Secrets API while it is present. `$user_id` may be `0`.
+- `two_factor_secrets_api_present` filter is an internal test seam. It can only force "absent" and is not a public extension point.
+- `two_factor_secrets_migrated` action (`$user_id`, `$slug`) after a secret was moved into the Secrets API.
+- `two_factor_secrets_migration_failed` action (`$user_id`, `$slug`, `$error`) when a migration failed and the plaintext copy was kept.
+- `two_factor_secret_unavailable` action (`$user_id`, `$slug`, `$error`) when a stored secret cannot be read.
+
+No hook ever receives a plaintext secret.
+
+### WP-CLI
+
+`CLI/class-two-factor-cli-command.php` registers the `wp two-factor` commands. `status` includes a `totp_storage` field (`plaintext`, `secrets-api`, `unavailable` or `none`). The `secrets` subcommand has `status`, `migrate` and `export` actions.
+
 ### 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.

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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]
+
+### New Features
+
+- Store authenticator app (TOTP) secrets encrypted with the WordPress Secrets API when it is available, with lazy migration, `wp two-factor secrets` commands and a Site Health check by @ericmann in [#TBD](https://github.com/WordPress/two-factor/pull/TBD)
+
 ## [0.17.0] - 2026-09-25
 
 ### Security Fixes

CLAUDE.md

@@ -1 +1,67 @@
 @AGENTS.md
+
+<!-- foundry:begin -->
+# Build guidance: TOTP secrets via the WordPress Secrets API
+
+Everything below is scoped to the build described in `docs/SPEC.md` and `docs/PLAN.md`. Strip this block before upstreaming.
+
+## Principles
+- Fail closed. An unreadable secret (`WP_Error`) never validates, is never treated as "not configured", never re-enrols the user, and never drops a user to single-factor login. Other providers keep working.
+- Two-Factor owns no cryptography. All storage goes through `Two_Factor_Secrets`; never call `wp_*_secret()` elsewhere.
+- Feature-detect at call time (`function_exists( 'wp_get_network_secret' )`), never at include time. Sites without the API behave exactly as today.
+- Three read states are sacred: `null` (absent), `WP_Error` (unreadable), string (value). Never collapse them.
+- Plaintext user meta (`_two_factor_totp_key`) beats the marker; marker (`_two_factor_totp_key_network`, holds the network ID) beats nothing; else no secret.
+- Migration is lazy, verified by read-back with `hash_equals()`, idempotent, and safe under concurrent requests. `is_available_for_user()` never migrates and never decrypts.
+- Revealed values go only to the immediate caller; `Two_Factor_Secrets::memzero()` after use. No hook ever receives plaintext.
+- `two_factor_use_secrets_api` (default `true`) gates writes and migration only; migrated users are still read while the API is present.
+- Every task ships its tests. Existing tests must pass unchanged with and without the API.
+- PHP 7.4 syntax, WPCS + VIP-Go clean, PHPStan level 5 clean via stubs (no baseline ignores), `two-factor` text domain, `@since 0.18.0`.
+
+## Commands
+- `npm run env start` (once; restart after editing `.wp-env.json`)
+- `npm run lint` (PHPCS, PHPStan, CSS, JS) and `composer lint-compat`
+- `npm test` (single site then multisite; run sequentially, never concurrently)
+- `npm run composer -- test -- --group secrets|totp|cli|core` for a subset
+- `npm run env run tests-cli wp plugin list` to confirm `secrets-api` is mapped
+
+## Module map
+- `two-factor.php` — loads core, compat, `class-two-factor-secrets.php`, settings; registers CLI and uninstall.
+- `class-two-factor-secrets.php` — `Two_Factor_Secrets`, static adapter: `is_api_present`, `is_provider_writable`, `can_write`, `get_secret_name`, `get_marker_meta_key`, `get_user_secret`, `set_user_secret`, `delete_user_secret`, `provider_label`, `memzero`; `@internal` seams `two_factor_secrets_api_present` filter and `$test_overrides`.
+- `class-two-factor-core.php` — login orchestration; `get_available_providers_for_user()` forces the fallback provider when every enabled provider is unregistered or enrolled-but-unavailable; `uninstall()` calls each provider's `uninstall_user_data()` before deleting meta.
+- `providers/class-two-factor-provider.php` — base class; new `is_enrolled_but_unavailable_for_user()` (default `false`) and static `uninstall_user_data()` (no-op).
+- `providers/class-two-factor-totp.php` — `get_user_totp_key_state()`, `get_user_totp_key()`, `set_user_totp_key()`, `delete_user_totp_key()`, `migrate_user_totp_key()`, `export_user_totp_key()`, `get_user_totp_key_storage()`, `count_users_by_storage()`, `has_affected_users()`, `has_plaintext_users()`, admin notice, Site Health test `two_factor_totp_secret_storage`, deletion hooks (`delete_user` single site, `wpmu_delete_user` multisite).
+- `CLI/class-two-factor-cli-command.php` — `status` gains `totp_storage`; `secrets status|migrate|export`.
+- `includes/` — never modified.
+- `tests/class-two-factor-secrets-test-case.php` — `Two_Factor_Secrets_UnitTestCase` (`require_secrets_api()`, `simulate_api_absent()`, override reset). `tests/phpstan/` — stubs, excluded from PHPUnit.
+
+## Constraints
+Rules marked (pattern) are enforced by `docs/foundry.json` `constraints`; the rest the reviewer checks by reading.
+- (pattern) No `wp_*_secret()` / `wp_secrets_*()` call outside `class-two-factor-secrets.php`.
+- (pattern) No site-scope `wp_get_secret`/`wp_set_secret`/`wp_delete_secret`/`wp_list_secrets` anywhere; network scope only.
+- (pattern) The `two-factor/{slug}-{id}` prefix appears only in the adapter.
+- (pattern) `_two_factor_totp_key` and `_two_factor_totp_key_network` are referenced via constants outside their definitions.
+- (pattern) No `error_log`/`var_dump`/`print_r`/`var_export` in the adapter, the TOTP provider or the CLI.
+- (pattern) Every `__()`-family call uses the `two-factor` domain.
+- (pattern) `Requires at least: 7.0` is not bumped; no composer/npm dependency on `secrets-api`.
+- (pattern, single-line only) `two_factor_secret*` hooks never receive `$plaintext|$secret|$key|$value|$readback|$state`.
+- (pattern) CLI batch size and the affected-users transient TTL come from constants.
+- (reading) No diff under `includes/`: `git diff --stat feature/secrets-api-totp -- includes/` must be empty.
+- (reading) `is_available_for_user()` and `is_enrolled_but_unavailable_for_user()` never call `get_user_secret()`, `migrate_user_totp_key()` or `reveal()`.
+- (reading) Every `get_users()`/`WP_User_Query` over TOTP meta passes `'blog_id' => 0`.
+- (reading) `WP_Error` messages or codes from the Secrets API are never echoed to end users; only the translated "unavailable" text is.
+- (reading) No `gh pr`/`gh issue` command targets `WordPress/two-factor`; always `--repo ericmann/two-factor`.
+- (reading) Multi-line `do_action( 'two_factor_secret…' )` calls carry no plaintext argument.
+
+## Commit template
+```
+<ID>: <title>
+
+Goal: <one sentence>
+Tests: <test files and names added or changed>
+Interpretation: <any reading chosen where SPEC allowed two, or "none">
+Measurement: <tuning tasks only; otherwise omit>
+Manual check: <what a human must verify, or "none">
+```
+
+SPEC.md wins over PLAN.md, which wins over code comments.
+<!-- foundry:end -->