From 00a0b2d324b180095dd23d42d0185e7349a1daa5 Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 08:29:08 +1100 Subject: [PATCH 01/28] Remove excess white-space. --- .../includes/class-wp-site-health.php | 1 - src/wp-includes/secrets.php | 20 ------------------- .../secrets/class-wp-secrets-broken-store.php | 1 - .../secrets/class-wp-secrets-option-store.php | 1 - .../tests/secrets/brokenDropinFallbacks.php | 1 - .../phpunit/tests/secrets/extensionPoints.php | 1 - 6 files changed, 25 deletions(-) diff --git a/src/wp-admin/includes/class-wp-site-health.php b/src/wp-admin/includes/class-wp-site-health.php index b9ce4f472834f..6b7b8907d5938 100644 --- a/src/wp-admin/includes/class-wp-site-health.php +++ b/src/wp-admin/includes/class-wp-site-health.php @@ -7,7 +7,6 @@ * @since 5.2.0 */ - require_once __DIR__ . '/secrets-site-health.php'; #[AllowDynamicProperties] diff --git a/src/wp-includes/secrets.php b/src/wp-includes/secrets.php index 99d87ed0d7413..7df4409c895d5 100644 --- a/src/wp-includes/secrets.php +++ b/src/wp-includes/secrets.php @@ -391,24 +391,6 @@ function wp_using_secrets_dropin(): bool { return ! empty( $GLOBALS['wp_secrets_dropin_loaded'] ); } - - - - - - - - - - - - - - - - - - /** * Encrypts and stores a secret. * @@ -474,8 +456,6 @@ function wp_import_option_as_secret( string $option, string $name ) { return _wp_secrets_set( $name, $value, false, true, 'imported' ); } - - /** * Retrieves a secret. * diff --git a/src/wp-includes/secrets/class-wp-secrets-broken-store.php b/src/wp-includes/secrets/class-wp-secrets-broken-store.php index 31e64d8e5c7fc..bdb24327f3021 100644 --- a/src/wp-includes/secrets/class-wp-secrets-broken-store.php +++ b/src/wp-includes/secrets/class-wp-secrets-broken-store.php @@ -75,7 +75,6 @@ public function list_names( bool $network = false ): WP_Error { return $this->error(); } - /** * Builds the error every method returns. * diff --git a/src/wp-includes/secrets/class-wp-secrets-option-store.php b/src/wp-includes/secrets/class-wp-secrets-option-store.php index 7ffc1496528d6..52b10466849cf 100644 --- a/src/wp-includes/secrets/class-wp-secrets-option-store.php +++ b/src/wp-includes/secrets/class-wp-secrets-option-store.php @@ -191,7 +191,6 @@ public function list_names( bool $network = false ) { return $names; } - /** * Builds the option name a secret is stored under. * diff --git a/tests/phpunit/tests/secrets/brokenDropinFallbacks.php b/tests/phpunit/tests/secrets/brokenDropinFallbacks.php index 77b2875d79149..9e60e0aa64671 100644 --- a/tests/phpunit/tests/secrets/brokenDropinFallbacks.php +++ b/tests/phpunit/tests/secrets/brokenDropinFallbacks.php @@ -37,7 +37,6 @@ public function test_broken_store_list_names_fails(): void { $this->assertWPError( $result ); } - public function test_broken_keyring_implements_the_interface(): void { $this->assertInstanceOf( WP_Secrets_Keyring::class, new WP_Secrets_Broken_Keyring() ); // @phpstan-ignore method.alreadyNarrowedType (Intentionally checking the class against its interface at runtime.) } diff --git a/tests/phpunit/tests/secrets/extensionPoints.php b/tests/phpunit/tests/secrets/extensionPoints.php index 565b6fc7fadd9..ebd1ebfb636ad 100644 --- a/tests/phpunit/tests/secrets/extensionPoints.php +++ b/tests/phpunit/tests/secrets/extensionPoints.php @@ -99,7 +99,6 @@ public function test_read_succeeds_while_write_fails(): void { $this->assertSame( 'seeded-before-write-broke', $read_result->reveal() ); } - /** * A store that refuses writes must still serve reads. This previously configured * a capability flag that nothing consulted, so it passed regardless of behavior. From 40e877ba8704aafbeb130430f5c5b5320ba1d219 Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 09:18:43 +1100 Subject: [PATCH 02/28] Add ticket and covers annotations to secrets tests. --- .../class-wp-secrets-keyring-conformance.php | 13 ++++ .../class-wp-secrets-provider-conformance.php | 58 ++++++++++++++ .../tests/secrets/brokenDropinFallbacks.php | 34 ++++++++ tests/phpunit/tests/secrets/capabilities.php | 26 +++++++ .../secrets/configKeyringConformance.php | 2 + tests/phpunit/tests/secrets/errorCodes.php | 10 +++ .../phpunit/tests/secrets/extensionPoints.php | 33 ++++++++ .../tests/secrets/mockKeyringConformance.php | 2 + tests/phpunit/tests/secrets/networkScope.php | 46 +++++++++++ tests/phpunit/tests/secrets/provider.php | 39 ++++++++++ .../tests/secrets/providerConformance.php | 2 + .../secrets/readonlyProviderConformance.php | 2 + tests/phpunit/tests/secrets/siteHealth.php | 49 ++++++++++++ .../tests/secrets/threeStateContract.php | 31 ++++++++ tests/phpunit/tests/secrets/versionSlots.php | 66 ++++++++++++++++ .../phpunit/tests/secrets/wpDeleteSecret.php | 22 ++++++ .../tests/secrets/wpImportOptionAsSecret.php | 30 +++++++ tests/phpunit/tests/secrets/wpListSecrets.php | 33 ++++++++ tests/phpunit/tests/secrets/wpSecret.php | 78 +++++++++++++++++++ .../phpunit/tests/secrets/wpSecretVersion.php | 14 ++++ .../phpunit/tests/secrets/wpSecretsCipher.php | 67 ++++++++++++++++ .../secrets/wpSecretsConfigKeyProvider.php | 56 +++++++++++++ .../tests/secrets/wpSecretsKeyManager.php | 77 ++++++++++++++++++ .../tests/secrets/wpSecretsMemzero.php | 14 ++++ .../tests/secrets/wpSecretsOptionStore.php | 42 ++++++++++ .../tests/secrets/wpSecretsValidateName.php | 10 +++ .../secrets/wpSetSecretAndWpGetSecret.php | 53 +++++++++++++ 27 files changed, 909 insertions(+) diff --git a/tests/phpunit/includes/secrets/class-wp-secrets-keyring-conformance.php b/tests/phpunit/includes/secrets/class-wp-secrets-keyring-conformance.php index e893a9a127b93..a078e432d2226 100644 --- a/tests/phpunit/includes/secrets/class-wp-secrets-keyring-conformance.php +++ b/tests/phpunit/includes/secrets/class-wp-secrets-keyring-conformance.php @@ -25,6 +25,9 @@ abstract protected function keyring(); * Wrap() followed by unwrap() has to return exactly the bytes that went in – * WP_Secrets_Key_Manager derives the root key from this round trip, so any * corruption here is a corrupted root key for every secret on the site. + * + * @covers WP_Secrets_Keyring::wrap + * @covers WP_Secrets_Keyring::unwrap */ public function test_wrap_returns_a_non_empty_string_that_unwraps_to_the_same_bytes(): void { $keyring = $this->keyring(); @@ -45,6 +48,8 @@ public function test_wrap_returns_a_non_empty_string_that_unwraps_to_the_same_by * values protect the same key material – something nothing outside the * keyring is entitled to learn. A fresh nonce (or equivalent) per call is what * WP_Secrets_Key_Manager relies on to keep that comparison unavailable. + * + * @covers WP_Secrets_Keyring::wrap */ public function test_two_wraps_of_the_same_bytes_return_different_strings(): void { $keyring = $this->keyring(); @@ -61,6 +66,8 @@ public function test_two_wraps_of_the_same_bytes_return_different_strings(): voi * it did not produce – WP_Secrets_Key_Manager treats anything other than * WP_Error as usable key material, so a keyring that returns garbage bytes on * garbage input hands a wrong root key downstream instead of failing. + * + * @covers WP_Secrets_Keyring::unwrap */ public function test_unwrap_of_garbage_is_a_wp_error(): void { $keyring = $this->keyring(); @@ -73,6 +80,8 @@ public function test_unwrap_of_garbage_is_a_wp_error(): void { * A truncated wrapped value must fail closed rather than decode to a short, * wrong key – WP_Secrets_Key_Manager has no way to tell a merely-short key * from a correctly-derived one except by trusting unwrap()'s success. + * + * @covers WP_Secrets_Keyring::unwrap */ public function test_unwrap_of_a_truncated_value_is_a_wp_error(): void { $keyring = $this->keyring(); @@ -89,6 +98,8 @@ public function test_unwrap_of_a_truncated_value_is_a_wp_error(): void { * A single flipped bit anywhere in the wrapped value has to be caught – * that is the entire point of authenticated wrapping. Silently accepting it * would let a corrupted or tampered wrapped root key through as genuine. + * + * @covers WP_Secrets_Keyring::unwrap */ public function test_unwrap_of_a_value_with_one_flipped_byte_is_a_wp_error(): void { $keyring = $this->keyring(); @@ -106,6 +117,8 @@ public function test_unwrap_of_a_value_with_one_flipped_byte_is_a_wp_error(): vo /** * Site Health renders get_key_source() directly; an empty or non-string value * there is a blank line on a diagnostics page an operator is depending on. + * + * @covers WP_Secrets_Keyring::get_key_source */ public function test_get_key_source_returns_a_non_empty_string(): void { $source = $this->keyring()->get_key_source(); diff --git a/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php b/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php index 98feab7729383..62aa105959c12 100644 --- a/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php +++ b/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php @@ -102,6 +102,9 @@ private function has_previous_version( WP_Secrets_Provider $provider, $name ) { // – declarations must be coherent ---------------------------------------- + /** + * @covers WP_Secrets_Provider::get_label + */ public function test_reports_a_non_empty_label(): void { $label = $this->provider()->get_label(); @@ -109,6 +112,9 @@ public function test_reports_a_non_empty_label(): void { $this->assertNotSame( '', trim( $label ) ); } + /** + * @covers WP_Secrets_Provider::get_protection_boundary + */ public function test_reports_a_known_protection_boundary(): void { $this->assertContains( $this->provider()->get_protection_boundary(), @@ -117,6 +123,9 @@ public function test_reports_a_known_protection_boundary(): void { ); } + /** + * @covers WP_Secrets_Provider::is_writable + */ public function test_is_writable_returns_a_bool(): void { $this->assertIsBool( $this->provider()->is_writable() ); } @@ -124,6 +133,9 @@ public function test_is_writable_returns_a_bool(): void { /** * The declaration has to match the behaviour, or a settings screen that trusts * is_writable() will offer a save control that cannot work. + * + * @covers WP_Secrets_Provider::is_writable + * @covers WP_Secrets_Provider::set */ public function test_a_read_only_provider_actually_refuses_writes(): void { $provider = $this->provider(); @@ -149,6 +161,8 @@ public function test_a_read_only_provider_actually_refuses_writes(): void { * set is null – not false, not an empty WP_Secret, not a WP_Error. Reporting * absence as an error makes every caller treat a missing optional credential * as an outage; reporting an outage as absence makes them treat it as deleted. + * + * @covers WP_Secrets_Provider::get */ public function test_a_name_that_was_never_set_is_null(): void { $result = $this->provider()->get( 'conformance/never-set-' . uniqid(), WP_Secret_Version::CURRENT ); @@ -160,6 +174,8 @@ public function test_a_name_that_was_never_set_is_null(): void { * A provider with no version history reports absence for PREVIOUS, because * that is what it is: there is no previous value. It is not an error, and it * is not an excuse to return the current one. + * + * @covers WP_Secrets_Provider::get */ public function test_previous_on_a_provider_or_secret_without_history_is_null_not_error(): void { $provider = $this->provider(); @@ -174,6 +190,9 @@ public function test_previous_on_a_provider_or_secret_without_history_is_null_no $this->assertNull( $previous ); } + /** + * @covers WP_Secrets_Provider::delete + */ public function test_deleting_something_absent_is_success(): void { $provider = $this->provider(); $this->require_writable( $provider ); @@ -184,6 +203,9 @@ public function test_deleting_something_absent_is_success(): void { ); } + /** + * @covers WP_Secrets_Provider::retire_previous + */ public function test_retiring_with_no_previous_version_is_success(): void { $provider = $this->provider(); $this->require_writable( $provider ); @@ -196,6 +218,10 @@ public function test_retiring_with_no_previous_version_is_success(): void { // – the round trip -------------------------------------------------------- + /** + * @covers WP_Secrets_Provider::set + * @covers WP_Secrets_Provider::get + */ public function test_a_stored_value_comes_back_intact(): void { $provider = $this->provider(); $this->require_writable( $provider ); @@ -214,6 +240,8 @@ public function test_a_stored_value_comes_back_intact(): void { * Fingerprints are how callers compare secrets without revealing them, so the * same value must fingerprint the same way twice. A provider that returns a * random or timestamped fingerprint breaks every comparison built on it. + * + * @covers WP_Secrets_Provider::get */ public function test_a_fingerprint_is_stable_for_the_same_value(): void { $provider = $this->provider(); @@ -246,6 +274,8 @@ public function test_a_fingerprint_is_stable_for_the_same_value(): void { * version; one with no history has nothing to lose. * * @ticket 66353 + * + * @covers WP_Secrets_Provider::set */ public function test_writing_an_unchanged_value_keeps_the_previous_version(): void { $provider = $this->provider(); @@ -269,6 +299,10 @@ public function test_writing_an_unchanged_value_keeps_the_previous_version(): vo $this->assertSame( $previous->fingerprint(), $kept->fingerprint(), 'Writing an unchanged value must not replace the previous version.' ); } + /** + * @covers WP_Secrets_Provider::delete + * @covers WP_Secrets_Provider::get + */ public function test_a_deleted_secret_reads_as_absent(): void { $provider = $this->provider(); $this->require_writable( $provider ); @@ -286,6 +320,8 @@ public function test_a_deleted_secret_reads_as_absent(): void { * The API does not fire `wp_secret_changed` on a provider's behalf, so a * provider that forgets to is a site whose audit log went quiet the day the * host installed it. Nothing else would notice. + * + * @covers WP_Secrets_Provider::set */ public function test_a_successful_write_reports_a_change(): void { $provider = $this->provider(); @@ -311,6 +347,9 @@ public function test_a_successful_write_reports_a_change(): void { $this->assertNotContains( 'UNIQUE-CONFORMANCE-CANARY-7c1d', $change, 'wp_secret_changed must never be passed a value.' ); } + /** + * @covers WP_Secrets_Provider::set + */ public function test_an_action_override_is_reported_as_given(): void { $provider = $this->provider(); $this->require_writable( $provider ); @@ -326,6 +365,9 @@ public function test_an_action_override_is_reported_as_given(): void { /** * A listener cannot otherwise tell a network secret from a site secret of the * same name, and on a network those are different credentials. + * + * @covers WP_Secrets_Provider::set + * @covers WP_Secrets_Provider::delete */ public function test_a_network_scope_change_reports_its_scope(): void { $provider = $this->provider(); @@ -342,6 +384,9 @@ public function test_a_network_scope_change_reports_its_scope(): void { $this->assertTrue( $this->recorded_changes[1][6], 'A network-scope delete must report $network as true.' ); } + /** + * @covers WP_Secrets_Provider::delete + */ public function test_deleting_a_secret_reports_a_change(): void { $provider = $this->provider(); $this->require_writable( $provider ); @@ -362,6 +407,8 @@ public function test_deleting_a_secret_reports_a_change(): void { * Only asked of a provider that keeps a previous version and clears it on * request. One with no history, or whose backend manages its own, has nothing * to report. + * + * @covers WP_Secrets_Provider::retire_previous */ public function test_retiring_a_previous_version_reports_a_change(): void { $provider = $this->provider(); @@ -388,6 +435,9 @@ public function test_retiring_a_previous_version_reports_a_change(): void { $this->assertSame( 'retired', $this->recorded_changes[0][1] ); } + /** + * @covers WP_Secrets_Provider::set + */ public function test_a_refused_write_reports_no_change(): void { $provider = $this->provider(); @@ -403,6 +453,9 @@ public function test_a_refused_write_reports_no_change(): void { // – listing never leaks --------------------------------------------------- + /** + * @covers WP_Secrets_Provider::list_secrets + */ public function test_listing_returns_an_array_or_an_error_and_never_a_value(): void { $provider = $this->provider(); $this->require_writable( $provider ); @@ -424,6 +477,9 @@ public function test_listing_returns_an_array_or_an_error_and_never_a_value(): v ); } + /** + * @covers WP_Secrets_Provider::list_secrets + */ public function test_listing_includes_a_stored_secret(): void { $provider = $this->provider(); $this->require_writable( $provider ); @@ -441,6 +497,8 @@ public function test_listing_includes_a_stored_secret(): void { * A prefix filter that matched loosely would hand a caller names it did not * ask about, which for a listing keyed by owner is exactly the wrong direction * to be wrong in. + * + * @covers WP_Secrets_Provider::list_secrets */ public function test_listing_respects_a_name_prefix(): void { $provider = $this->provider(); diff --git a/tests/phpunit/tests/secrets/brokenDropinFallbacks.php b/tests/phpunit/tests/secrets/brokenDropinFallbacks.php index 9e60e0aa64671..8d73e77646f85 100644 --- a/tests/phpunit/tests/secrets/brokenDropinFallbacks.php +++ b/tests/phpunit/tests/secrets/brokenDropinFallbacks.php @@ -4,14 +4,22 @@ * sentinels _wp_secrets_get_store()/_wp_secrets_get_key_manager() fall back to when * a secrets.php drop-in exists but left an invalid override. * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_BrokenDropinFallbacks extends WP_UnitTestCase { + /** + * @coversNothing + */ public function test_broken_store_implements_the_interface(): void { $this->assertInstanceOf( WP_Secrets_Store::class, new WP_Secrets_Broken_Store() ); // @phpstan-ignore method.alreadyNarrowedType (Intentionally checking the class against its interface at runtime.) } + /** + * @covers WP_Secrets_Broken_Store::get + */ public function test_broken_store_get_fails(): void { $result = ( new WP_Secrets_Broken_Store() )->get( 'myplugin/api-key' ); @@ -19,28 +27,43 @@ public function test_broken_store_get_fails(): void { $this->assertSame( WP_SECRETS_ERROR_STORE_UNAVAILABLE, $result->get_error_code() ); } + /** + * @covers WP_Secrets_Broken_Store::set + */ public function test_broken_store_set_fails(): void { $result = ( new WP_Secrets_Broken_Store() )->set( 'myplugin/api-key', array() ); $this->assertWPError( $result ); } + /** + * @covers WP_Secrets_Broken_Store::delete + */ public function test_broken_store_delete_fails(): void { $result = ( new WP_Secrets_Broken_Store() )->delete( 'myplugin/api-key' ); $this->assertWPError( $result ); } + /** + * @covers WP_Secrets_Broken_Store::list_names + */ public function test_broken_store_list_names_fails(): void { $result = ( new WP_Secrets_Broken_Store() )->list_names(); $this->assertWPError( $result ); } + /** + * @coversNothing + */ public function test_broken_keyring_implements_the_interface(): void { $this->assertInstanceOf( WP_Secrets_Keyring::class, new WP_Secrets_Broken_Keyring() ); // @phpstan-ignore method.alreadyNarrowedType (Intentionally checking the class against its interface at runtime.) } + /** + * @covers WP_Secrets_Broken_Keyring::wrap + */ public function test_broken_keyring_wrap_fails(): void { $result = ( new WP_Secrets_Broken_Keyring() )->wrap( 'material' ); @@ -48,21 +71,32 @@ public function test_broken_keyring_wrap_fails(): void { $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code() ); } + /** + * @covers WP_Secrets_Broken_Keyring::unwrap + */ public function test_broken_keyring_unwrap_fails(): void { $result = ( new WP_Secrets_Broken_Keyring() )->unwrap( 'wrapped' ); $this->assertWPError( $result ); } + /** + * @covers WP_Secrets_Broken_Keyring::get_key_source + */ public function test_broken_keyring_reports_a_key_source(): void { $this->assertIsString( ( new WP_Secrets_Broken_Keyring() )->get_key_source() ); } + /** + * @covers ::wp_using_secrets_dropin + */ public function test_wp_using_secrets_dropin_is_false_by_default(): void { $this->assertFalse( wp_using_secrets_dropin() ); } /** + * @covers ::wp_using_secrets_dropin + * * @runInSeparateProcess * @preserveGlobalState disabled */ diff --git a/tests/phpunit/tests/secrets/capabilities.php b/tests/phpunit/tests/secrets/capabilities.php index 5298809144594..547a17deb0718 100644 --- a/tests/phpunit/tests/secrets/capabilities.php +++ b/tests/phpunit/tests/secrets/capabilities.php @@ -4,6 +4,8 @@ * administrators by populate_roles() and upgrade_720(), and manage_network_secrets, * held only by super admins. * + * @ticket 66187 + * * @group secrets * @group capabilities */ @@ -40,21 +42,33 @@ private function role( $role ) { return $role_object; } + /** + * @coversNothing + */ public function test_capability_constant_values(): void { $this->assertSame( 'manage_secrets', WP_SECRETS_CAP_MANAGE ); // @phpstan-ignore method.alreadyNarrowedType (Intentionally pinning the value of a public constant.) $this->assertSame( 'manage_network_secrets', WP_SECRETS_CAP_MANAGE_NETWORK ); // @phpstan-ignore method.alreadyNarrowedType (Intentionally pinning the value of a public constant.) } + /** + * @covers ::populate_roles_720 + */ public function test_a_fresh_install_grants_manage_secrets_to_administrator(): void { $this->assertTrue( $this->role( 'administrator' )->has_cap( WP_SECRETS_CAP_MANAGE ) ); } + /** + * @covers ::populate_roles_720 + */ public function test_no_other_role_is_granted_manage_secrets(): void { foreach ( array( 'editor', 'author', 'contributor', 'subscriber' ) as $role ) { $this->assertFalse( $this->role( $role )->has_cap( WP_SECRETS_CAP_MANAGE ), $role ); } } + /** + * @covers ::populate_roles_720 + */ public function test_populate_roles_720_grants_manage_secrets_to_administrator(): void { $this->role( 'administrator' )->remove_cap( WP_SECRETS_CAP_MANAGE ); @@ -64,6 +78,8 @@ public function test_populate_roles_720_grants_manage_secrets_to_administrator() } /** + * @covers ::upgrade_720 + * * @dataProvider data_upgrade_720_gate * * @param int $db_version The database version being upgraded from. @@ -98,12 +114,18 @@ public static function data_upgrade_720_gate() { ); } + /** + * @covers ::populate_roles_720 + */ public function test_administrator_user_has_manage_secrets(): void { $user_id = self::factory()->user->create( array( 'role' => 'administrator' ) ); $this->assertTrue( user_can( $user_id, WP_SECRETS_CAP_MANAGE ) ); } + /** + * @covers ::populate_roles_720 + */ public function test_subscriber_does_not_have_manage_secrets(): void { $user_id = self::factory()->user->create( array( 'role' => 'subscriber' ) ); @@ -112,6 +134,8 @@ public function test_subscriber_does_not_have_manage_secrets(): void { /** * @group ms-excluded + * + * @covers ::map_meta_cap */ public function test_single_site_administrator_does_not_have_manage_network_secrets(): void { $user_id = self::factory()->user->create( array( 'role' => 'administrator' ) ); @@ -121,6 +145,8 @@ public function test_single_site_administrator_does_not_have_manage_network_secr /** * @group ms-required + * + * @covers ::map_meta_cap */ public function test_only_super_admins_have_manage_network_secrets(): void { $administrator = self::factory()->user->create( array( 'role' => 'administrator' ) ); diff --git a/tests/phpunit/tests/secrets/configKeyringConformance.php b/tests/phpunit/tests/secrets/configKeyringConformance.php index 51f486fecb72d..8451c6af2b1df 100644 --- a/tests/phpunit/tests/secrets/configKeyringConformance.php +++ b/tests/phpunit/tests/secrets/configKeyringConformance.php @@ -7,6 +7,8 @@ * known-good subject a host writing a KMS- or HSM-backed keyring can compare * their own failures against. * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_ConfigKeyringConformance extends WP_Secrets_Keyring_Conformance { diff --git a/tests/phpunit/tests/secrets/errorCodes.php b/tests/phpunit/tests/secrets/errorCodes.php index c2ad48c597b09..1cd0e8aee4fa1 100644 --- a/tests/phpunit/tests/secrets/errorCodes.php +++ b/tests/phpunit/tests/secrets/errorCodes.php @@ -3,11 +3,15 @@ * Pins the exact error-code strings so a later commit can't accidentally rename * one – these are part of the API's public error contract. * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_ErrorCodes extends WP_UnitTestCase { /** + * @coversNothing + * * @dataProvider data_published_error_codes * * @param string $constant Name of the error-code constant. @@ -32,6 +36,9 @@ public static function data_published_error_codes() { ); } + /** + * @coversNothing + */ public function test_all_error_codes_are_distinct(): void { $codes = array( WP_SECRETS_ERROR_DECRYPTION_FAILED, @@ -46,6 +53,9 @@ public function test_all_error_codes_are_distinct(): void { $this->assertSame( count( $codes ), count( array_unique( $codes ) ) ); } + /** + * @coversNothing + */ public function test_max_name_length_matches_the_options_column_budget(): void { // wp_options.option_name is VARCHAR(191); '_wp_network_secret_' (19 // characters) is the longest prefix any store here uses. diff --git a/tests/phpunit/tests/secrets/extensionPoints.php b/tests/phpunit/tests/secrets/extensionPoints.php index ebd1ebfb636ad..2d89d6ad0fe73 100644 --- a/tests/phpunit/tests/secrets/extensionPoints.php +++ b/tests/phpunit/tests/secrets/extensionPoints.php @@ -18,6 +18,8 @@ * see docs/journal/test-coverage-gaps.md for what this does not cover (the drop-in's own file * loading, which cannot be driven the same way). * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_ExtensionPoints extends WP_UnitTestCase { @@ -25,6 +27,8 @@ class Tests_Secrets_ExtensionPoints extends WP_UnitTestCase { use WP_Secrets_Assertions; /** + * @covers ::_wp_secrets_get_store + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -43,6 +47,8 @@ public function test_mock_store_with_the_default_keyring_round_trips(): void { } /** + * @covers ::_wp_secrets_get_key_manager + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -58,6 +64,9 @@ public function test_mock_keyring_with_the_default_store_round_trips(): void { } /** + * @covers ::_wp_secrets_get_store + * @covers ::_wp_secrets_get_key_manager + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -77,6 +86,9 @@ public function test_mock_store_and_mock_keyring_together_round_trip(): void { * A store that can read but not write: an existing value seeded before write * support is turned off must remain readable, while a new write is rejected. * + * @covers ::wp_set_secret + * @covers ::wp_get_secret + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -104,6 +116,9 @@ public function test_read_succeeds_while_write_fails(): void { * a capability flag that nothing consulted, so it passed regardless of behavior. * It now makes set() actually fail, and checks both halves. * + * @covers ::wp_set_secret + * @covers ::wp_get_secret + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -126,6 +141,10 @@ public function test_a_store_that_refuses_writes_still_serves_reads(): void { } /** + * @covers ::_wp_secrets_get_store + * @covers ::wp_set_secret + * @covers ::wp_get_secret + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -145,6 +164,9 @@ public function test_unreachable_store_fails_closed_with_no_local_fallback(): vo } /** + * @covers ::_wp_secrets_get_key_manager + * @covers ::wp_set_secret + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -162,6 +184,9 @@ public function test_unreachable_keyring_fails_closed_with_no_local_fallback(): * the whole point of the envelope. Mock_Store records every record it is * given; this asserts the plaintext appears nowhere in any of them. * + * @covers ::wp_set_secret + * @covers WP_Secrets_Libsodium_Provider::set + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -186,6 +211,14 @@ public function test_the_store_is_never_handed_a_plaintext(): void { * confirms every operation fails closed with WP_Error rather than a fatal error * or a silent fallback to local storage. * + * @covers ::_wp_secrets_get_provider + * @covers WP_Secrets_Broken_Provider::set + * @covers WP_Secrets_Broken_Provider::get + * @covers WP_Secrets_Broken_Provider::delete + * @covers WP_Secrets_Broken_Provider::list_secrets + * @covers WP_Secrets_Broken_Provider::retire_previous + * @covers WP_Secrets_Broken_Provider::is_writable + * * @runInSeparateProcess * @preserveGlobalState disabled */ diff --git a/tests/phpunit/tests/secrets/mockKeyringConformance.php b/tests/phpunit/tests/secrets/mockKeyringConformance.php index 2c9911e649a94..6d073a96b367d 100644 --- a/tests/phpunit/tests/secrets/mockKeyringConformance.php +++ b/tests/phpunit/tests/secrets/mockKeyringConformance.php @@ -7,6 +7,8 @@ * substitutes for, so a test that passes with Mock_Keyring in place is a test * that would also have to reckon with a conforming real keyring. * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_MockKeyringConformance extends WP_Secrets_Keyring_Conformance { diff --git a/tests/phpunit/tests/secrets/networkScope.php b/tests/phpunit/tests/secrets/networkScope.php index 6875bec0e19fd..105bb3b5c94b2 100644 --- a/tests/phpunit/tests/secrets/networkScope.php +++ b/tests/phpunit/tests/secrets/networkScope.php @@ -2,12 +2,18 @@ /** * Tests for the network-scope public functions. * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_NetworkScope extends WP_UnitTestCase { use WP_Secrets_Assertions; + /** + * @covers ::wp_set_network_secret + * @covers ::wp_get_network_secret + */ public function test_set_then_get_round_trips(): void { $this->assertTrue( wp_set_network_secret( 'myplugin/api-key', 'value' ) ); @@ -17,10 +23,17 @@ public function test_set_then_get_round_trips(): void { $this->assertSame( 'value', $secret->reveal() ); } + /** + * @covers ::wp_get_network_secret + */ public function test_get_returns_null_for_an_absent_secret(): void { $this->assertNull( wp_get_network_secret( 'myplugin/never-set' ) ); } + /** + * @covers ::wp_set_network_secret + * @covers ::wp_get_network_secret + */ public function test_site_and_network_scope_are_independent_under_the_same_name(): void { wp_set_secret( 'myplugin/api-key', 'site-value' ); wp_set_network_secret( 'myplugin/api-key', 'network-value' ); @@ -34,6 +47,9 @@ public function test_site_and_network_scope_are_independent_under_the_same_name( $this->assertSame( 'network-value', $network_secret->reveal() ); } + /** + * @covers ::wp_delete_network_secret + */ public function test_delete_removes_a_network_secret(): void { wp_set_network_secret( 'myplugin/api-key', 'value' ); @@ -41,6 +57,9 @@ public function test_delete_removes_a_network_secret(): void { $this->assertNull( wp_get_network_secret( 'myplugin/api-key' ) ); } + /** + * @covers ::wp_delete_network_secret + */ public function test_delete_does_not_touch_the_site_scope_secret_of_the_same_name(): void { wp_set_secret( 'myplugin/api-key', 'site-value' ); wp_set_network_secret( 'myplugin/api-key', 'network-value' ); @@ -53,6 +72,9 @@ public function test_delete_does_not_touch_the_site_scope_secret_of_the_same_nam $this->assertSame( 'site-value', $site_secret->reveal() ); } + /** + * @covers ::wp_set_network_secret + */ public function test_previous_version_and_demotion_work_the_same_as_site_scope(): void { wp_set_network_secret( 'myplugin/api-key', 'first-value' ); wp_set_network_secret( 'myplugin/api-key', 'second-value' ); @@ -61,6 +83,9 @@ public function test_previous_version_and_demotion_work_the_same_as_site_scope() $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::CURRENT, 'second-value', true ); } + /** + * @covers ::wp_retire_network_secret_version + */ public function test_retire_clears_the_previous_slot(): void { wp_set_network_secret( 'myplugin/api-key', 'first-value' ); wp_set_network_secret( 'myplugin/api-key', 'second-value' ); @@ -72,6 +97,11 @@ public function test_retire_clears_the_previous_slot(): void { /** * A listener is told which scope changed. Without it, a network secret and a * site secret of the same name are indistinguishable in an audit log. + * + * @covers ::wp_set_network_secret + * @covers ::wp_retire_network_secret_version + * @covers ::wp_delete_network_secret + * @covers ::wp_set_secret */ public function test_change_hook_reports_network_scope(): void { $scopes = array(); @@ -102,6 +132,9 @@ function ( ...$args ) use ( &$scopes ) { ); } + /** + * @covers ::wp_list_network_secrets + */ public function test_list_returns_network_secrets_only(): void { wp_set_secret( 'myplugin/site-only', 'value' ); wp_set_network_secret( 'myplugin/network-only', 'value' ); @@ -112,6 +145,10 @@ public function test_list_returns_network_secrets_only(): void { $this->assertSame( array( 'myplugin/network-only' ), wp_list_pluck( $entries, 'name' ) ); } + /** + * @covers ::wp_get_network_secret + * @covers ::_wp_secrets_get + */ public function test_an_invalid_version_is_a_wp_error_same_as_site_scope(): void { $this->setExpectedIncorrectUsage( '_wp_secrets_get' ); @@ -121,6 +158,9 @@ public function test_an_invalid_version_is_a_wp_error_same_as_site_scope(): void $this->assertSame( WP_SECRETS_ERROR_INVALID_ARGUMENT, $result->get_error_code() ); } + /** + * @covers ::wp_set_network_secret + */ public function test_set_rejects_an_invalid_name(): void { $result = wp_set_network_secret( 'Not A Valid Name', 'value' ); @@ -131,6 +171,9 @@ public function test_set_rejects_an_invalid_name(): void { /** * The entire point of network scope: a secret written from one blog's context * must read back identically from another blog's context. Requires multisite. + * + * @covers ::wp_set_network_secret + * @covers ::wp_get_network_secret */ public function test_network_secret_is_readable_from_any_blog(): void { if ( ! is_multisite() ) { @@ -151,6 +194,9 @@ public function test_network_secret_is_readable_from_any_blog(): void { * The mirror image: a site-scope secret must NOT be readable from another blog, * proving there is no implicit fallback between scopes and no accidental sharing * across blogs for site-scope secrets. + * + * @covers ::wp_set_secret + * @covers ::wp_get_secret */ public function test_site_secret_is_not_readable_from_a_different_blog(): void { if ( ! is_multisite() ) { diff --git a/tests/phpunit/tests/secrets/provider.php b/tests/phpunit/tests/secrets/provider.php index 2f4e19006f6ce..8c208708129c0 100644 --- a/tests/phpunit/tests/secrets/provider.php +++ b/tests/phpunit/tests/secrets/provider.php @@ -3,6 +3,8 @@ * Tests for the provider seam: the outermost extension point, and what replaced * the store's old supports() flag. * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_Provider extends WP_UnitTestCase { @@ -94,10 +96,16 @@ public function is_writable(): bool { // – the shipped provider ------------------------------------------------- + /** + * @covers ::_wp_secrets_get_provider + */ public function test_the_default_provider_is_the_libsodium_one(): void { $this->assertInstanceOf( 'WP_Secrets_Libsodium_Provider', _wp_secrets_get_provider() ); } + /** + * @covers WP_Secrets_Libsodium_Provider::get_protection_boundary + */ public function test_the_default_provider_protects_inside_wordpress(): void { $this->assertSame( WP_Secrets_Provider::BOUNDARY_WORDPRESS, @@ -105,6 +113,9 @@ public function test_the_default_provider_protects_inside_wordpress(): void { ); } + /** + * @covers ::wp_secrets_provider_is_writable + */ public function test_the_default_provider_accepts_writes(): void { $this->assertTrue( wp_secrets_provider_is_writable() ); } @@ -113,6 +124,8 @@ public function test_the_default_provider_accepts_writes(): void { * The label is what Site Health shows an operator. It must name the key source, * because "libsodium" alone does not tell anyone whether their root key is * derived from wp-config.php salts or held in a KMS. + * + * @covers ::wp_secrets_provider_label */ public function test_the_default_provider_label_names_the_key_source(): void { $label = wp_secrets_provider_label(); @@ -127,6 +140,9 @@ public function test_the_default_provider_label_names_the_key_source(): void { // – a platform provider, which is what the seam exists for ---------------- /** + * @covers ::_wp_secrets_get_provider + * @covers ::wp_secrets_provider_label + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -145,6 +161,9 @@ public function test_a_drop_in_provider_replaces_the_default_entirely(): void { * refuses writes, declaring it up front so a settings screen can disable its * save control rather than discovering the refusal after the fact. * + * @covers ::wp_secrets_provider_is_writable + * @covers ::wp_set_secret + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -163,6 +182,8 @@ public function test_a_read_only_provider_refuses_writes_and_declares_it(): void * Reads still work on a read-only provider – "read-only" is about writes, not * about being broken. Absence is still absence. * + * @covers ::wp_get_secret + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -178,6 +199,9 @@ public function test_a_read_only_provider_still_serves_reads(): void { * A broken drop-in must not quietly revert to the default provider: that would * downgrade a site's protection at the exact moment nobody is watching. * + * @covers ::_wp_secrets_get_provider + * @covers WP_Secrets_Broken_Provider::is_writable + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -192,6 +216,12 @@ public function test_a_broken_dropin_fails_closed_rather_than_reverting_to_the_d } /** + * @covers ::wp_set_secret + * @covers ::wp_get_secret + * @covers ::wp_delete_secret + * @covers ::wp_list_secrets + * @covers ::wp_retire_secret_version + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -209,6 +239,8 @@ public function test_a_broken_dropin_makes_every_operation_a_wp_error(): void { * Specifically not null: a misconfigured credential backend must never look * like a working site that happens to have no secrets in it yet. * + * @covers ::wp_get_secret + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -229,6 +261,8 @@ public function test_a_broken_dropin_read_is_an_error_not_an_absence(): void { * served from wp_options, find nothing there, and report a site's credentials * absent when they are merely unreachable. * + * @covers ::_wp_secrets_get_provider + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -242,6 +276,9 @@ public function test_a_non_provider_global_fails_closed(): void { * And it is an error rather than an absence, which is the property that * actually protects the operator. * + * @covers ::_wp_secrets_get_provider + * @covers ::wp_get_secret + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -260,6 +297,8 @@ public function test_a_non_provider_global_reads_as_an_error_not_an_absence(): v * supported arrangement rather than a broken one. It gets the shipped libsodium * provider, composed with the keyring it did supply. * + * @covers ::_wp_secrets_get_provider + * * @runInSeparateProcess * @preserveGlobalState disabled */ diff --git a/tests/phpunit/tests/secrets/providerConformance.php b/tests/phpunit/tests/secrets/providerConformance.php index dafcb49763baa..ed1b099e63a5a 100644 --- a/tests/phpunit/tests/secrets/providerConformance.php +++ b/tests/phpunit/tests/secrets/providerConformance.php @@ -6,6 +6,8 @@ * kit nobody has run against a working implementation is a wish list. It also * means a host can compare their own failures against a known-good subject. * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_LibsodiumProviderConformance extends WP_Secrets_Provider_Conformance { diff --git a/tests/phpunit/tests/secrets/readonlyProviderConformance.php b/tests/phpunit/tests/secrets/readonlyProviderConformance.php index c93464ccea92b..5877aa8d2f96e 100644 --- a/tests/phpunit/tests/secrets/readonlyProviderConformance.php +++ b/tests/phpunit/tests/secrets/readonlyProviderConformance.php @@ -7,6 +7,8 @@ * A conformance kit that has only ever run against a writable provider would not * have proven that its own skips work. * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_ReadOnlyProviderConformance extends WP_Secrets_Provider_Conformance { diff --git a/tests/phpunit/tests/secrets/siteHealth.php b/tests/phpunit/tests/secrets/siteHealth.php index d0eee49ceb421..81103c3ae2f07 100644 --- a/tests/phpunit/tests/secrets/siteHealth.php +++ b/tests/phpunit/tests/secrets/siteHealth.php @@ -2,6 +2,8 @@ /** * Tests for the Site Health integration in src/wp-admin/includes/secrets-site-health.php. * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_SiteHealth extends WP_UnitTestCase { @@ -30,6 +32,9 @@ private function debug_fields( array $info ): array { return $fields; } + /** + * @covers ::wp_secrets_site_health_tests + */ public function test_registers_three_tests_under_direct(): void { $tests = wp_secrets_site_health_tests( array() ); @@ -44,12 +49,18 @@ public function test_registers_three_tests_under_direct(): void { } } + /** + * @covers ::wp_secrets_site_health_tests + */ public function test_preserves_existing_tests(): void { $tests = wp_secrets_site_health_tests( array( 'direct' => array( 'existing_test' => array( 'label' => 'x' ) ) ) ); $this->assertArrayHasKey( 'existing_test', $tests['direct'] ); } + /** + * @covers ::wp_secrets_site_health_test_key_source + */ public function test_key_source_test_recommends_a_dedicated_key_by_default(): void { if ( 'put your unique phrase here' === LOGGED_IN_KEY || 'put your unique phrase here' === LOGGED_IN_SALT ) { $this->markTestSkipped( 'Needs real LOGGED_IN_KEY and LOGGED_IN_SALT values; wp-tests-config-sample.php ships placeholders.' ); @@ -62,6 +73,8 @@ public function test_key_source_test_recommends_a_dedicated_key_by_default(): vo } /** + * @covers ::wp_secrets_site_health_test_key_source + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -75,6 +88,8 @@ public function test_key_source_test_recommends_regeneration_for_a_legacy_key(): } /** + * @covers ::wp_secrets_site_health_test_key_source + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -87,6 +102,8 @@ public function test_key_source_test_is_good_for_a_dedicated_base64_key(): void } /** + * @covers ::wp_secrets_site_health_test_key_source + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -98,6 +115,9 @@ public function test_key_source_test_is_critical_when_the_keyring_is_broken(): v $this->assertSame( 'critical', $result['status'] ); } + /** + * @covers ::wp_secrets_site_health_test_undecryptable + */ public function test_undecryptable_test_is_good_when_nothing_is_broken(): void { wp_set_secret( 'myplugin/api-key', 'value' ); @@ -106,12 +126,18 @@ public function test_undecryptable_test_is_good_when_nothing_is_broken(): void { $this->assertSame( 'good', $result['status'] ); } + /** + * @covers ::wp_secrets_site_health_test_undecryptable + */ public function test_undecryptable_test_is_good_with_no_secrets_at_all(): void { $result = wp_secrets_site_health_test_undecryptable(); $this->assertSame( 'good', $result['status'] ); } + /** + * @covers ::wp_secrets_site_health_test_undecryptable + */ public function test_undecryptable_test_is_critical_and_lists_the_broken_secret(): void { wp_set_secret( 'myplugin/api-key', 'value' ); $secret = wp_get_secret( 'myplugin/api-key' ); @@ -135,6 +161,9 @@ public function test_undecryptable_test_is_critical_and_lists_the_broken_secret( $this->assertStringContainsString( $fingerprint, $result['description'] ); } + /** + * @covers ::wp_secrets_site_health_test_undecryptable + */ public function test_undecryptable_test_never_contains_a_plaintext(): void { wp_set_secret( 'myplugin/api-key', 'UNIQUE-PLAINTEXT-CANARY-9f3a' ); @@ -152,6 +181,9 @@ public function test_undecryptable_test_never_contains_a_plaintext(): void { $this->assertStringNotContainsString( 'UNIQUE-PLAINTEXT-CANARY-9f3a', $result['description'] ); } + /** + * @covers ::wp_secrets_site_health_test_needs_rotation + */ public function test_needs_rotation_test_is_good_by_default(): void { wp_set_secret( 'myplugin/api-key', 'value' ); @@ -160,6 +192,9 @@ public function test_needs_rotation_test_is_good_by_default(): void { $this->assertSame( 'good', $result['status'] ); } + /** + * @covers ::wp_secrets_site_health_test_needs_rotation + */ public function test_needs_rotation_test_is_recommended_after_an_import(): void { update_option( 'my_plugin_api_key', 'value' ); wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ); @@ -170,6 +205,9 @@ public function test_needs_rotation_test_is_recommended_after_an_import(): void $this->assertStringContainsString( '1', $result['description'] ); } + /** + * @covers ::wp_secrets_site_health_debug_info + */ public function test_debug_info_reports_expected_fields(): void { wp_set_secret( 'myplugin/api-key', 'value' ); @@ -191,6 +229,9 @@ public function test_debug_info_reports_expected_fields(): void { $this->assertSame( '1', $fields['site_secret_count']['value'] ); } + /** + * @covers ::wp_secrets_site_health_debug_info + */ public function test_debug_info_reports_no_dropin_by_default(): void { $info = wp_secrets_site_health_debug_info( array() ); @@ -200,6 +241,9 @@ public function test_debug_info_reports_no_dropin_by_default(): void { $this->assertSame( 'No', $fields['dropin_active']['value'] ); } + /** + * @covers ::wp_secrets_site_health_debug_info + */ public function test_debug_info_never_contains_a_plaintext(): void { wp_set_secret( 'myplugin/api-key', 'UNIQUE-PLAINTEXT-CANARY-9f3a' ); @@ -211,6 +255,9 @@ public function test_debug_info_never_contains_a_plaintext(): void { $this->assertStringNotContainsString( 'UNIQUE-PLAINTEXT-CANARY-9f3a', $dump ); } + /** + * @covers ::wp_secrets_site_health_debug_info + */ public function test_debug_info_omits_network_fields_on_single_site(): void { $info = wp_secrets_site_health_debug_info( array() ); @@ -220,6 +267,8 @@ public function test_debug_info_omits_network_fields_on_single_site(): void { /** * Network secret counts appear only for a super admin on a multisite install – * never for a site administrator who is not one. + * + * @covers ::wp_secrets_site_health_debug_info */ public function test_debug_info_includes_network_fields_only_for_a_super_admin(): void { if ( ! is_multisite() ) { diff --git a/tests/phpunit/tests/secrets/threeStateContract.php b/tests/phpunit/tests/secrets/threeStateContract.php index acf2666ecb54f..bb28c81204b5c 100644 --- a/tests/phpunit/tests/secrets/threeStateContract.php +++ b/tests/phpunit/tests/secrets/threeStateContract.php @@ -5,16 +5,24 @@ * could not be retrieved. The whole design rests on never collapsing these, so every * broken case here explicitly asserts `null !== $result` as well as WP_Error. * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_ThreeStateContract extends WP_UnitTestCase { + /** + * @covers ::wp_get_secret + */ public function test_absent_is_null(): void { $result = wp_get_secret( 'myplugin/never-set' ); $this->assertNull( $result ); } + /** + * @covers ::wp_get_secret + */ public function test_previous_slot_absent_on_an_existing_secret_is_also_null(): void { wp_set_secret( 'myplugin/api-key', 'value' ); @@ -23,6 +31,9 @@ public function test_previous_slot_absent_on_an_existing_secret_is_also_null(): $this->assertNull( $result ); } + /** + * @covers ::wp_get_secret + */ public function test_malformed_record_is_wp_error_not_null(): void { update_option( '_wp_secret_myplugin/api-key', 'this is a string, not a record array', false ); @@ -33,6 +44,9 @@ public function test_malformed_record_is_wp_error_not_null(): void { $this->assertSame( WP_SECRETS_ERROR_RECORD_MALFORMED, $result->get_error_code() ); } + /** + * @covers ::wp_get_secret + */ public function test_record_missing_the_current_slot_is_wp_error_not_null(): void { update_option( '_wp_secret_myplugin/api-key', array( 'v' => 1 ), false ); @@ -43,6 +57,9 @@ public function test_record_missing_the_current_slot_is_wp_error_not_null(): voi $this->assertSame( WP_SECRETS_ERROR_RECORD_MALFORMED, $result->get_error_code() ); } + /** + * @covers ::wp_get_secret + */ public function test_unsupported_record_version_is_wp_error_not_null(): void { update_option( '_wp_secret_myplugin/api-key', @@ -71,6 +88,8 @@ public function test_unsupported_record_version_is_wp_error_not_null(): void { * legitimately-encrypted record under a different name's option row – as if it * had been copied or corrupted – must fail decryption, not silently succeed * under the wrong context or crash. + * + * @covers ::wp_get_secret */ public function test_aad_mismatch_from_a_copied_record_is_wp_error_not_null(): void { wp_set_secret( 'myplugin/original-name', 'value' ); @@ -96,6 +115,8 @@ public function test_aad_mismatch_from_a_copied_record_is_wp_error_not_null(): v * request-scoped root-key cache (ADR 0009) would otherwise keep serving the * already-unwrapped key and mask the misconfiguration this test defines below. * + * @covers ::wp_get_secret + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -124,6 +145,9 @@ public function test_key_unavailable_is_wp_error_not_null(): void { * wrapped root key has been corrupted – simulating the option row being * damaged after secrets already exist. get_master_key() must fail before * decryption is ever attempted, since a usable root key was never obtained. + * + * @covers ::wp_get_secret + * @covers WP_Secrets_Key_Manager::get_master_key */ public function test_a_corrupted_wrapped_root_key_is_wp_error_not_null(): void { wp_set_secret( 'myplugin/api-key', 'value' ); @@ -144,6 +168,8 @@ public function test_a_corrupted_wrapped_root_key_is_wp_error_not_null(): void { * empty fingerprint to WP_Secret's constructor, which rejects one, producing an * uncaught InvalidArgumentException – a fatal, and a fourth state the contract * does not allow. + * + * @covers ::wp_get_secret */ public function test_record_missing_its_fingerprint_field_still_returns_a_secret(): void { wp_set_secret( 'myplugin/api-key', 'value' ); @@ -168,6 +194,8 @@ public function test_record_missing_its_fingerprint_field_still_returns_a_secret * The 'fingerprint' field is outside the AAD, so anyone who can write to the * store can change it freely. WP_Secret::fingerprint() must report the value * recomputed from the decrypted plaintext, not whatever the record claims. + * + * @covers ::wp_get_secret */ public function test_fingerprint_is_recomputed_not_read_from_the_record(): void { wp_set_secret( 'myplugin/api-key', 'value' ); @@ -191,6 +219,9 @@ public function test_fingerprint_is_recomputed_not_read_from_the_record(): void $this->assertSame( $genuine, $after->fingerprint() ); } + /** + * @covers ::wp_get_secret + */ public function test_exists_and_decrypts_is_a_wp_secret(): void { wp_set_secret( 'myplugin/api-key', 'value' ); diff --git a/tests/phpunit/tests/secrets/versionSlots.php b/tests/phpunit/tests/secrets/versionSlots.php index b4262ab7d0de5..02022d77b027a 100644 --- a/tests/phpunit/tests/secrets/versionSlots.php +++ b/tests/phpunit/tests/secrets/versionSlots.php @@ -5,6 +5,8 @@ * "the single most important new test in the suite" – the prior proof-of-concept * could not do this at all. * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_VersionSlots extends WP_UnitTestCase { @@ -28,6 +30,10 @@ private function stored_slot( string $slot ): array { return $record[ $slot ]; } + /** + * @covers ::wp_set_secret + * @covers ::wp_get_secret + */ public function test_first_write_leaves_no_previous_slot(): void { wp_set_secret( 'myplugin/api-key', 'first-value' ); @@ -36,6 +42,9 @@ public function test_first_write_leaves_no_previous_slot(): void { /** * The headline case: PREVIOUS must actually decrypt back to the prior value. + * + * @covers ::wp_set_secret + * @covers ::wp_get_secret */ public function test_previous_returns_the_actual_prior_value(): void { wp_set_secret( 'myplugin/api-key', 'first-value' ); @@ -45,6 +54,10 @@ public function test_previous_returns_the_actual_prior_value(): void { $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::CURRENT, 'second-value' ); } + /** + * @covers ::wp_set_secret + * @covers WP_Secrets_Libsodium_Provider::set + */ public function test_third_write_discards_the_oldest_value(): void { wp_set_secret( 'myplugin/api-key', 'value-a' ); wp_set_secret( 'myplugin/api-key', 'value-b' ); @@ -62,6 +75,9 @@ public function test_third_write_discards_the_oldest_value(): void { * the previous value a rotation still depends on. * * @ticket 66353 + * + * @covers ::wp_set_secret + * @covers ::wp_get_secret */ public function test_rewriting_the_current_value_keeps_the_previous_slot(): void { wp_set_secret( 'myplugin/api-key', 'first-value' ); @@ -74,6 +90,9 @@ public function test_rewriting_the_current_value_keeps_the_previous_slot(): void /** * @ticket 66353 + * + * @covers ::wp_set_secret + * @covers WP_Secrets_Libsodium_Provider::set */ public function test_rewriting_the_current_value_leaves_the_stored_record_untouched(): void { wp_set_secret( 'myplugin/api-key', 'first-value' ); @@ -87,6 +106,8 @@ public function test_rewriting_the_current_value_leaves_the_stored_record_untouc /** * @ticket 66353 + * + * @covers ::wp_set_secret */ public function test_rewriting_the_current_value_does_not_fire_the_change_hook(): void { wp_set_secret( 'myplugin/api-key', 'value' ); @@ -108,6 +129,9 @@ function () use ( &$fired ) { * Re-saving an imported value through a settings form has not rotated it. * * @ticket 66353 + * + * @covers ::wp_set_secret + * @covers WP_Secrets_Libsodium_Provider::set */ public function test_rewriting_the_current_value_keeps_its_needs_rotation_flag(): void { update_option( 'my_plugin_api_key', 'imported-value' ); @@ -124,6 +148,9 @@ public function test_rewriting_the_current_value_keeps_its_needs_rotation_flag() * version. * * @ticket 66353 + * + * @covers ::wp_import_option_as_secret + * @covers WP_Secrets_Libsodium_Provider::set */ public function test_importing_the_current_value_flags_it_and_keeps_the_previous_slot(): void { wp_set_secret( 'myplugin/api-key', 'first-value' ); @@ -137,6 +164,10 @@ public function test_importing_the_current_value_flags_it_and_keeps_the_previous $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::CURRENT, 'second-value' ); } + /** + * @covers ::wp_set_secret + * @covers ::wp_get_secret + */ public function test_previous_preserves_its_original_fingerprint(): void { wp_set_secret( 'myplugin/api-key', 'first-value' ); $original = wp_get_secret( 'myplugin/api-key' ); @@ -150,6 +181,10 @@ public function test_previous_preserves_its_original_fingerprint(): void { $this->assertSame( $original_fingerprint, $previous->fingerprint() ); } + /** + * @covers ::wp_set_secret + * @covers WP_Secrets_Libsodium_Provider::set + */ public function test_previous_preserves_its_original_created_timestamp(): void { wp_set_secret( 'myplugin/api-key', 'first-value' ); $original_created = $this->stored_slot( WP_Secret_Version::CURRENT )['created']; @@ -161,6 +196,10 @@ public function test_previous_preserves_its_original_created_timestamp(): void { $this->assertSame( $original_created, $demoted_created ); } + /** + * @covers ::wp_set_secret + * @covers WP_Secrets_Libsodium_Provider::set + */ public function test_previous_preserves_its_needs_rotation_flag(): void { wp_set_secret( 'myplugin/api-key', 'first-value' ); @@ -184,6 +223,9 @@ public function test_previous_preserves_its_needs_rotation_flag(): void { * slot's stored bytes into 'previous' would leave it permanently undecryptable * there. Demoting must re-encrypt, which means the stored ciphertext actually * changes even though the plaintext does not. + * + * @covers ::wp_set_secret + * @covers WP_Secrets_Libsodium_Provider::set */ public function test_demotion_actually_reencrypts_rather_than_copying_ciphertext(): void { wp_set_secret( 'myplugin/api-key', 'first-value' ); @@ -200,6 +242,9 @@ public function test_demotion_actually_reencrypts_rather_than_copying_ciphertext $this->assertSame( 'first-value', $previous->reveal() ); } + /** + * @covers ::wp_get_secret + */ public function test_previous_on_a_secret_with_no_previous_slot_is_null(): void { wp_set_secret( 'myplugin/api-key', 'value' ); @@ -211,6 +256,9 @@ public function test_previous_on_a_secret_with_no_previous_slot_is_null(): void * orphaned by a botched rotation), the write must still succeed rather than * inheriting the old corruption – refusing here would be the exact * corrupted-record-blocks-everything failure this API is built to avoid. + * + * @covers ::wp_set_secret + * @covers ::wp_get_secret */ public function test_a_write_succeeds_even_if_the_outgoing_current_slot_cannot_be_decrypted(): void { wp_set_secret( 'myplugin/api-key', 'value' ); @@ -230,6 +278,9 @@ public function test_a_write_succeeds_even_if_the_outgoing_current_slot_cannot_b $this->assertNull( wp_get_secret( 'myplugin/api-key', WP_Secret_Version::PREVIOUS ) ); } + /** + * @covers ::wp_retire_secret_version + */ public function test_retire_clears_previous_and_leaves_current_intact(): void { wp_set_secret( 'myplugin/api-key', 'first-value' ); wp_set_secret( 'myplugin/api-key', 'second-value' ); @@ -242,16 +293,25 @@ public function test_retire_clears_previous_and_leaves_current_intact(): void { $this->assertSame( 'second-value', $current->reveal() ); } + /** + * @covers ::wp_retire_secret_version + */ public function test_retire_on_a_secret_with_no_previous_slot_is_a_successful_noop(): void { wp_set_secret( 'myplugin/api-key', 'value' ); $this->assertTrue( wp_retire_secret_version( 'myplugin/api-key' ) ); } + /** + * @covers ::wp_retire_secret_version + */ public function test_retire_on_a_never_set_secret_is_a_successful_noop(): void { $this->assertTrue( wp_retire_secret_version( 'myplugin/never-set' ) ); } + /** + * @covers ::wp_retire_secret_version + */ public function test_retire_rejects_an_invalid_name(): void { $result = wp_retire_secret_version( 'Not A Valid Name' ); @@ -259,6 +319,9 @@ public function test_retire_rejects_an_invalid_name(): void { $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code() ); } + /** + * @covers ::wp_retire_secret_version + */ public function test_retire_fires_the_change_hook_with_the_retired_action(): void { wp_set_secret( 'myplugin/api-key', 'first-value' ); $original = wp_get_secret( 'myplugin/api-key' ); @@ -289,6 +352,9 @@ function ( ...$args ) use ( &$captured ) { $this->assertSame( '', $new_fingerprint ); } + /** + * @covers ::wp_retire_secret_version + */ public function test_retire_does_not_fire_the_change_hook_on_a_noop(): void { wp_set_secret( 'myplugin/api-key', 'value' ); diff --git a/tests/phpunit/tests/secrets/wpDeleteSecret.php b/tests/phpunit/tests/secrets/wpDeleteSecret.php index 83b9bb3fc9f13..d652b422c9778 100644 --- a/tests/phpunit/tests/secrets/wpDeleteSecret.php +++ b/tests/phpunit/tests/secrets/wpDeleteSecret.php @@ -2,10 +2,15 @@ /** * Tests for wp_delete_secret(). * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_WpDeleteSecret extends WP_UnitTestCase { + /** + * @covers ::wp_delete_secret + */ public function test_deletes_an_existing_secret(): void { wp_set_secret( 'myplugin/api-key', 'value' ); @@ -13,10 +18,16 @@ public function test_deletes_an_existing_secret(): void { $this->assertNull( wp_get_secret( 'myplugin/api-key' ) ); } + /** + * @covers ::wp_delete_secret + */ public function test_deleting_an_absent_secret_is_not_an_error(): void { $this->assertTrue( wp_delete_secret( 'myplugin/never-set' ) ); } + /** + * @covers ::wp_delete_secret + */ public function test_rejects_an_invalid_name(): void { $result = wp_delete_secret( 'Not A Valid Name' ); @@ -24,6 +35,9 @@ public function test_rejects_an_invalid_name(): void { $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code() ); } + /** + * @covers ::wp_delete_secret + */ public function test_change_hook_fires_with_deleted_action(): void { wp_set_secret( 'myplugin/api-key', 'value' ); $secret = wp_get_secret( 'myplugin/api-key' ); @@ -54,6 +68,9 @@ function ( ...$args ) use ( &$captured ) { $this->assertSame( '', $new_fingerprint ); } + /** + * @covers ::wp_delete_secret + */ public function test_change_hook_does_not_fire_when_nothing_was_deleted(): void { $fired = false; add_action( @@ -72,6 +89,8 @@ function () use ( &$fired ) { * A corrupted record must still be removable. Refusing here would leave a secret * permanently stuck – unreadable, unrepairable, and undeletable without editing * the database by hand. + * + * @covers ::wp_delete_secret */ public function test_a_corrupt_record_is_still_deletable(): void { update_option( '_wp_secret_myplugin/corrupt', 'not a record at all', false ); @@ -80,6 +99,9 @@ public function test_a_corrupt_record_is_still_deletable(): void { $this->assertNull( wp_get_secret( 'myplugin/corrupt' ) ); } + /** + * @covers ::wp_delete_secret + */ public function test_no_capability_check_is_applied(): void { wp_set_secret( 'myplugin/api-key', 'value' ); wp_set_current_user( 0 ); diff --git a/tests/phpunit/tests/secrets/wpImportOptionAsSecret.php b/tests/phpunit/tests/secrets/wpImportOptionAsSecret.php index a6051be7f9524..9e992cadbe16d 100644 --- a/tests/phpunit/tests/secrets/wpImportOptionAsSecret.php +++ b/tests/phpunit/tests/secrets/wpImportOptionAsSecret.php @@ -2,10 +2,15 @@ /** * Tests for wp_import_option_as_secret(). * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_WpImportOptionAsSecret extends WP_UnitTestCase { + /** + * @covers ::wp_import_option_as_secret + */ public function test_imports_an_existing_option_value(): void { update_option( 'my_plugin_api_key', 'sk_live_from_an_option' ); @@ -17,6 +22,9 @@ public function test_imports_an_existing_option_value(): void { $this->assertSame( 'sk_live_from_an_option', $secret->reveal() ); } + /** + * @covers ::wp_import_option_as_secret + */ public function test_leaves_the_source_option_untouched(): void { update_option( 'my_plugin_api_key', 'sk_live_from_an_option' ); @@ -25,6 +33,10 @@ public function test_leaves_the_source_option_untouched(): void { $this->assertSame( 'sk_live_from_an_option', get_option( 'my_plugin_api_key' ) ); } + /** + * @covers ::wp_import_option_as_secret + * @covers WP_Secrets_Libsodium_Provider::set + */ public function test_flags_the_imported_secret_for_rotation(): void { update_option( 'my_plugin_api_key', 'value' ); wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ); @@ -37,6 +49,10 @@ public function test_flags_the_imported_secret_for_rotation(): void { $this->assertTrue( $record['current']['needs_rotation'] ); } + /** + * @covers ::wp_set_secret + * @covers WP_Secrets_Libsodium_Provider::set + */ public function test_an_ordinary_write_does_not_flag_needs_rotation(): void { wp_set_secret( 'myplugin/api-key', 'value' ); @@ -48,6 +64,9 @@ public function test_an_ordinary_write_does_not_flag_needs_rotation(): void { $this->assertFalse( $record['current']['needs_rotation'] ); } + /** + * @covers ::wp_import_option_as_secret + */ public function test_rejects_a_nonexistent_option(): void { $result = wp_import_option_as_secret( 'this_option_was_never_set', 'myplugin/api-key' ); @@ -55,6 +74,9 @@ public function test_rejects_a_nonexistent_option(): void { $this->assertSame( WP_SECRETS_ERROR_INVALID_VALUE, $result->get_error_code() ); } + /** + * @covers ::wp_import_option_as_secret + */ public function test_rejects_a_non_string_option_value(): void { update_option( 'my_plugin_settings', array( 'not' => 'a string' ) ); @@ -64,6 +86,9 @@ public function test_rejects_a_non_string_option_value(): void { $this->assertSame( WP_SECRETS_ERROR_INVALID_VALUE, $result->get_error_code() ); } + /** + * @covers ::wp_import_option_as_secret + */ public function test_rejects_an_invalid_destination_name(): void { update_option( 'my_plugin_api_key', 'value' ); @@ -73,6 +98,9 @@ public function test_rejects_an_invalid_destination_name(): void { $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code() ); } + /** + * @covers ::wp_import_option_as_secret + */ public function test_fires_the_change_hook_with_the_imported_action(): void { update_option( 'my_plugin_api_key', 'value' ); @@ -99,6 +127,8 @@ function ( ...$args ) use ( &$captured ) { * An import onto an existing secret behaves like any other write, including * demotion – there is nothing special about the destination just because the * new value's source happens to be an option. + * + * @covers ::wp_import_option_as_secret */ public function test_importing_over_an_existing_secret_demotes_it_like_any_write(): void { wp_set_secret( 'myplugin/api-key', 'original-value' ); diff --git a/tests/phpunit/tests/secrets/wpListSecrets.php b/tests/phpunit/tests/secrets/wpListSecrets.php index a088eb3156a0c..b32fa89be85a8 100644 --- a/tests/phpunit/tests/secrets/wpListSecrets.php +++ b/tests/phpunit/tests/secrets/wpListSecrets.php @@ -2,14 +2,22 @@ /** * Tests for wp_list_secrets(). * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_WpListSecrets extends WP_UnitTestCase { + /** + * @covers ::wp_list_secrets + */ public function test_returns_an_empty_array_when_nothing_is_set(): void { $this->assertSame( array(), wp_list_secrets() ); } + /** + * @covers ::wp_list_secrets + */ public function test_lists_every_secret_with_the_expected_keys(): void { wp_set_secret( 'myplugin/api-key', 'value' ); @@ -27,6 +35,8 @@ public function test_lists_every_secret_with_the_expected_keys(): void { /** * Never a value, under any circumstance – the entire justification for this * function existing depends on it. + * + * @covers ::wp_list_secrets */ public function test_never_returns_a_value(): void { wp_set_secret( 'myplugin/api-key', 'a-plaintext-value-that-must-not-leak' ); @@ -37,6 +47,9 @@ public function test_never_returns_a_value(): void { $this->assertStringNotContainsString( 'a-plaintext-value-that-must-not-leak', $dump ); } + /** + * @covers ::wp_list_secrets + */ public function test_fingerprint_matches_the_secrets_own_fingerprint(): void { wp_set_secret( 'myplugin/api-key', 'value' ); @@ -48,6 +61,9 @@ public function test_fingerprint_matches_the_secrets_own_fingerprint(): void { $this->assertSame( $secret->fingerprint(), $entries[0]['fingerprint'] ); } + /** + * @covers ::wp_list_secrets + */ public function test_has_previous_is_false_before_a_rotation_and_true_after(): void { wp_set_secret( 'myplugin/api-key', 'first-value' ); @@ -64,6 +80,9 @@ public function test_has_previous_is_false_before_a_rotation_and_true_after(): v $this->assertTrue( $after[0]['has_previous'] ); } + /** + * @covers ::wp_list_secrets + */ public function test_needs_rotation_reflects_the_current_slots_flag(): void { wp_set_secret( 'myplugin/api-key', 'value' ); @@ -82,6 +101,9 @@ public function test_needs_rotation_reflects_the_current_slots_flag(): void { $this->assertTrue( $entries[0]['needs_rotation'] ); } + /** + * @covers ::wp_list_secrets + */ public function test_filters_by_namespace(): void { wp_set_secret( 'pluginone/key', 'value' ); wp_set_secret( 'plugintwo/key', 'value' ); @@ -92,6 +114,9 @@ public function test_filters_by_namespace(): void { $this->assertSame( array( 'pluginone/key' ), wp_list_pluck( $entries, 'name' ) ); } + /** + * @covers ::wp_list_secrets + */ public function test_empty_namespace_returns_everything(): void { wp_set_secret( 'pluginone/key', 'value' ); wp_set_secret( 'plugintwo/key', 'value' ); @@ -102,6 +127,9 @@ public function test_empty_namespace_returns_everything(): void { $this->assertCount( 2, $entries ); } + /** + * @covers ::wp_list_secrets + */ public function test_namespace_does_not_match_a_prefix_of_a_different_namespace(): void { // 'plugin' must not match 'pluginone/key' – only a full "namespace/" prefix. wp_set_secret( 'pluginone/key', 'value' ); @@ -112,6 +140,8 @@ public function test_namespace_does_not_match_a_prefix_of_a_different_namespace( /** * A corrupted record must still appear in the list – Site Health's * undecryptable-secrets check depends on being able to see it exists. + * + * @covers ::wp_list_secrets */ public function test_a_corrupt_record_is_still_listed_with_blank_metadata(): void { update_option( '_wp_secret_myplugin/corrupt', 'not a record at all', false ); @@ -125,6 +155,9 @@ public function test_a_corrupt_record_is_still_listed_with_blank_metadata(): voi $this->assertFalse( $entries[0]['has_previous'] ); } + /** + * @covers ::wp_list_secrets + */ public function test_does_not_list_network_scope_secrets(): void { wp_set_secret( 'myplugin/site-only', 'value' ); _wp_secrets_set( 'myplugin/network-only', 'value', true ); diff --git a/tests/phpunit/tests/secrets/wpSecret.php b/tests/phpunit/tests/secrets/wpSecret.php index 68c84441ebfa2..f8846aaa6a97d 100644 --- a/tests/phpunit/tests/secrets/wpSecret.php +++ b/tests/phpunit/tests/secrets/wpSecret.php @@ -8,6 +8,8 @@ /** * Masking, serialization refusal, and vault lifecycle for WP_Secret. * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_WPSecret extends WP_UnitTestCase { @@ -25,46 +27,70 @@ private function make_secret() { return new WP_Secret( self::NAME, self::PLAINTEXT, self::FINGERPRINT ); } + /** + * @coversNothing + */ public function test_class_is_final(): void { $reflection = new ReflectionClass( WP_Secret::class ); $this->assertTrue( $reflection->isFinal() ); } + /** + * @coversNothing + */ public function test_implements_json_serializable(): void { $this->assertInstanceOf( JsonSerializable::class, $this->make_secret() ); } + /** + * @covers WP_Secret::reveal + */ public function test_reveal_returns_the_exact_plaintext(): void { $secret = $this->make_secret(); $this->assertSame( self::PLAINTEXT, $secret->reveal() ); } + /** + * @covers WP_Secret::fingerprint + */ public function test_fingerprint_returns_the_exact_fingerprint(): void { $secret = $this->make_secret(); $this->assertSame( self::FINGERPRINT, $secret->fingerprint() ); } + /** + * @covers WP_Secret::get_name + */ public function test_get_name_returns_the_exact_name(): void { $secret = $this->make_secret(); $this->assertSame( self::NAME, $secret->get_name() ); } + /** + * @covers WP_Secret::__construct + */ public function test_constructor_rejects_a_non_string_value(): void { $this->expectException( InvalidArgumentException::class ); new WP_Secret( self::NAME, 12345, self::FINGERPRINT ); // @phpstan-ignore argument.type (Intentionally passing a non-string value.) } + /** + * @covers WP_Secret::__construct + */ public function test_constructor_rejects_an_empty_name(): void { $this->expectException( InvalidArgumentException::class ); new WP_Secret( '', self::PLAINTEXT, self::FINGERPRINT ); } + /** + * @covers WP_Secret::__construct + */ public function test_constructor_rejects_an_empty_fingerprint(): void { $this->expectException( InvalidArgumentException::class ); @@ -74,6 +100,10 @@ public function test_constructor_rejects_an_empty_fingerprint(): void { /** * Every representation short of reveal() must exclude the plaintext. * + * @covers WP_Secret::__toString + * @covers WP_Secret::jsonSerialize + * @covers WP_Secret::__debugInfo + * * @dataProvider data_masking_surfaces * * @param callable( WP_Secret ): ( string|false ) $callback Renders the secret through one surface. @@ -138,12 +168,18 @@ function ( WP_Secret $secret ) { ); } + /** + * @covers WP_Secret::__toString + */ public function test_to_string_yields_the_masked_placeholder(): void { $secret = $this->make_secret(); $this->assertSame( '[secret:' . self::NAME . ']', (string) $secret ); } + /** + * @covers WP_Secret::jsonSerialize + */ public function test_json_encode_yields_the_masked_placeholder(): void { $secret = $this->make_secret(); @@ -154,6 +190,9 @@ public function test_json_encode_yields_the_masked_placeholder(): void { $this->assertSame( '[secret:' . self::NAME . ']', json_decode( $json ) ); } + /** + * @covers WP_Secret::__debugInfo + */ public function test_var_dump_yields_the_masked_placeholder(): void { $secret = $this->make_secret(); @@ -164,6 +203,9 @@ public function test_var_dump_yields_the_masked_placeholder(): void { $this->assertStringContainsString( '[secret:' . self::NAME . ']', $output ); } + /** + * @covers WP_Secret::__serialize + */ public function test_serialize_throws(): void { $secret = $this->make_secret(); @@ -172,6 +214,9 @@ public function test_serialize_throws(): void { serialize( $secret ); } + /** + * @covers WP_Secret::__clone + */ public function test_clone_throws(): void { $secret = $this->make_secret(); @@ -185,6 +230,11 @@ public function test_clone_throws(): void { * because __serialize() alone shadows __sleep() and vice versa depending on which * pair PHP's engine prefers – this proves each of the four refuses independently. * + * @covers WP_Secret::__sleep + * @covers WP_Secret::__wakeup + * @covers WP_Secret::__serialize + * @covers WP_Secret::__unserialize + * * @dataProvider data_refusing_magic_methods * * @param string $method Magic method name. @@ -214,6 +264,10 @@ public static function data_refusing_magic_methods() { ); } + /** + * @covers WP_Secret::__construct + * @covers WP_Secret::__destruct + */ public function test_destructing_the_last_reference_removes_it_from_the_vault(): void { $secret = $this->make_secret(); $id = spl_object_id( $secret ); @@ -244,6 +298,9 @@ public function test_destructing_the_last_reference_removes_it_from_the_vault(): * while a persistent backend (Redis, Memcached) serializes instead, which * __serialize() refuses. Both are LogicException, so both are covered here * without the test having to know which cache is installed. + * + * @covers WP_Secret::__clone + * @covers WP_Secret::__serialize */ public function test_wp_cache_set_of_a_secret_is_refused(): void { $secret = $this->make_secret(); @@ -263,6 +320,8 @@ public function test_wp_cache_set_of_a_secret_is_refused(): void { * regression guard against a future change that moves the plaintext back into a * declared property, which would defeat the masking design without breaking any * of the magic-method tests. + * + * @covers WP_Secret::__construct */ public function test_nothing_plaintext_survives_a_refused_cache_write(): void { $secret = $this->make_secret(); @@ -278,6 +337,11 @@ public function test_nothing_plaintext_survives_a_refused_cache_write(): void { $this->assertNeverContainsPlaintext( self::PLAINTEXT, $cached ); } + /** + * @covers WP_Secret::__construct + * @covers WP_Secret::reveal + * @covers WP_Secret::__destruct + */ public function test_two_instances_do_not_share_a_vault_slot(): void { $a = new WP_Secret( 'plugin/a', 'value-a', 'fp-a' ); $b = new WP_Secret( 'plugin/b', 'value-b', 'fp-b' ); @@ -297,6 +361,9 @@ public function test_two_instances_do_not_share_a_vault_slot(): void { * HSM signing key, a brokered credential. Everything except reveal() behaves * normally, which is the point – it still lists, still fingerprints, and * still masks itself everywhere. + * + * @covers WP_Secret::withheld + * @covers WP_Secret::reveal */ public function test_withheld_reveal_returns_the_providers_reason(): void { $reason = new WP_Error( 'provider_withholds_value', 'This key never leaves the HSM.' ); @@ -308,6 +375,11 @@ public function test_withheld_reveal_returns_the_providers_reason(): void { $this->assertSame( 'provider_withholds_value', $revealed->get_error_code() ); } + /** + * @covers WP_Secret::withheld + * @covers WP_Secret::get_name + * @covers WP_Secret::fingerprint + */ public function test_withheld_still_reports_name_and_fingerprint(): void { $secret = WP_Secret::withheld( 'myplugin/signing-key', @@ -322,6 +394,10 @@ public function test_withheld_still_reports_name_and_fingerprint(): void { /** * The masking guarantees are not weakened by the withheld path: there is no * plaintext to leak, and the error reason must not leak either. + * + * @covers WP_Secret::withheld + * @covers WP_Secret::__debugInfo + * @covers WP_Secret::__toString */ public function test_withheld_masks_like_any_other_secret(): void { $secret = WP_Secret::withheld( @@ -339,6 +415,8 @@ public function test_withheld_masks_like_any_other_secret(): void { /** * An ordinary secret is unaffected: reveal() still returns the plaintext, and * the widened return type is not a behaviour change for the shipped provider. + * + * @covers WP_Secret::reveal */ public function test_an_ordinary_secret_still_reveals_a_plain_string(): void { $secret = new WP_Secret( 'myplugin/api-key', 'sk_live_value', 'fingerprint' ); diff --git a/tests/phpunit/tests/secrets/wpSecretVersion.php b/tests/phpunit/tests/secrets/wpSecretVersion.php index c972472bb4c91..16b825d35d499 100644 --- a/tests/phpunit/tests/secrets/wpSecretVersion.php +++ b/tests/phpunit/tests/secrets/wpSecretVersion.php @@ -1,27 +1,41 @@ assertIsString( WP_Secret_Version::CURRENT ); $this->assertIsString( WP_Secret_Version::PREVIOUS ); $this->assertNotSame( WP_Secret_Version::CURRENT, WP_Secret_Version::PREVIOUS ); } + /** + * @coversNothing + */ public function test_class_is_final(): void { $reflection = new ReflectionClass( WP_Secret_Version::class ); $this->assertTrue( $reflection->isFinal() ); } + /** + * @coversNothing + */ public function test_class_declares_no_constructor(): void { $reflection = new ReflectionClass( WP_Secret_Version::class ); $this->assertNull( $reflection->getConstructor() ); } + /** + * @coversNothing + */ public function test_class_declares_exactly_two_constants(): void { $reflection = new ReflectionClass( WP_Secret_Version::class ); diff --git a/tests/phpunit/tests/secrets/wpSecretsCipher.php b/tests/phpunit/tests/secrets/wpSecretsCipher.php index ec7b1f9d7e28d..7894b01354267 100644 --- a/tests/phpunit/tests/secrets/wpSecretsCipher.php +++ b/tests/phpunit/tests/secrets/wpSecretsCipher.php @@ -2,6 +2,8 @@ /** * Tests for WP_Secrets_Cipher. * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_WPSecretsCipher extends WP_UnitTestCase { @@ -35,6 +37,10 @@ private function master_key( $byte = 0x11 ) { return str_repeat( chr( $byte ), 32 ); } + /** + * @covers WP_Secrets_Cipher::encrypt_value + * @covers WP_Secrets_Cipher::decrypt_value + */ public function test_round_trips_a_value(): void { $cipher = new WP_Secrets_Cipher(); $record = $cipher->encrypt_value( $this->master_key(), 'site', 1, self::NAME, WP_Secret_Version::CURRENT, 'sk_live_secret' ); @@ -46,6 +52,10 @@ public function test_round_trips_a_value(): void { $this->assertSame( 'sk_live_secret', $plaintext ); } + /** + * @covers WP_Secrets_Cipher::encrypt_value + * @covers WP_Secrets_Cipher::decrypt_value + */ public function test_round_trips_an_empty_string_value(): void { $cipher = new WP_Secrets_Cipher(); $record = $cipher->encrypt_value( $this->master_key(), 'site', 1, self::NAME, WP_Secret_Version::CURRENT, '' ); @@ -55,6 +65,10 @@ public function test_round_trips_an_empty_string_value(): void { $this->assertSame( '', $plaintext ); } + /** + * @covers WP_Secrets_Cipher::encrypt_value + * @covers WP_Secrets_Cipher::decrypt_value + */ public function test_round_trips_under_network_scope(): void { $cipher = new WP_Secrets_Cipher(); $record = $cipher->encrypt_value( $this->master_key(), 'network', 0, self::NAME, WP_Secret_Version::CURRENT, 'network-secret' ); @@ -64,6 +78,9 @@ public function test_round_trips_under_network_scope(): void { $this->assertSame( 'network-secret', $plaintext ); } + /** + * @covers WP_Secrets_Cipher::encrypt_value + */ public function test_encrypt_rejects_a_non_string_value(): void { $cipher = new WP_Secrets_Cipher(); @@ -74,6 +91,8 @@ public function test_encrypt_rejects_a_non_string_value(): void { } /** + * @covers WP_Secrets_Cipher::encrypt_value + * * @dataProvider data_bad_master_keys * * @param string $bad_key Master key the cipher must refuse. @@ -98,6 +117,9 @@ public static function data_bad_master_keys() { ); } + /** + * @covers WP_Secrets_Cipher::encrypt_value + */ public function test_encrypt_propagates_an_invalid_name(): void { $cipher = new WP_Secrets_Cipher(); @@ -107,6 +129,9 @@ public function test_encrypt_propagates_an_invalid_name(): void { $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code() ); } + /** + * @covers WP_Secrets_Cipher::encrypt_value + */ public function test_encrypt_reports_an_invalid_scope_as_a_wp_error(): void { $cipher = new WP_Secrets_Cipher(); @@ -118,6 +143,9 @@ public function test_encrypt_reports_an_invalid_scope_as_a_wp_error(): void { $this->assertSame( WP_SECRETS_ERROR_INVALID_ARGUMENT, $result->get_error_code() ); } + /** + * @covers WP_Secrets_Cipher::encrypt_value + */ public function test_encrypt_reports_a_negative_site_id_as_a_wp_error(): void { $cipher = new WP_Secrets_Cipher(); @@ -129,6 +157,9 @@ public function test_encrypt_reports_a_negative_site_id_as_a_wp_error(): void { $this->assertSame( WP_SECRETS_ERROR_INVALID_ARGUMENT, $result->get_error_code() ); } + /** + * @covers WP_Secrets_Cipher::encrypt_value + */ public function test_encrypt_reports_an_invalid_slot_as_a_wp_error(): void { $cipher = new WP_Secrets_Cipher(); @@ -144,6 +175,8 @@ public function test_encrypt_reports_an_invalid_slot_as_a_wp_error(): void { * AAD binding: a record encrypted under one context must not decrypt under a * different one, for any single component of that context. * + * @covers WP_Secrets_Cipher::decrypt_value + * * @dataProvider data_mismatched_context * * @param string $scope Scope to decrypt under. @@ -176,6 +209,9 @@ public static function data_mismatched_context() { ); } + /** + * @covers WP_Secrets_Cipher::decrypt_value + */ public function test_decrypt_fails_under_a_different_master_key(): void { $cipher = new WP_Secrets_Cipher(); $record = $cipher->encrypt_value( $this->master_key( 0x11 ), 'site', 1, self::NAME, WP_Secret_Version::CURRENT, 'value' ); @@ -187,6 +223,8 @@ public function test_decrypt_fails_under_a_different_master_key(): void { } /** + * @covers WP_Secrets_Cipher::decrypt_value + * * @dataProvider data_tamperable_fields * * @param string $field Record field to corrupt. @@ -224,6 +262,8 @@ public static function data_tamperable_fields() { } /** + * @covers WP_Secrets_Cipher::decrypt_value + * * @dataProvider data_malformed_records * * @param mixed $record Stored record the cipher must refuse. @@ -269,6 +309,9 @@ public static function data_malformed_records() { ); } + /** + * @covers WP_Secrets_Cipher::encrypt_value + */ public function test_data_key_independence(): void { $cipher = new WP_Secrets_Cipher(); @@ -282,6 +325,9 @@ public function test_data_key_independence(): void { $this->assertNotSame( $a['ct'], $b['ct'] ); } + /** + * @covers WP_Secrets_Cipher::encrypt_value + */ public function test_nonce_uniqueness_across_many_writes(): void { $cipher = new WP_Secrets_Cipher(); $nonces = array(); @@ -298,6 +344,9 @@ public function test_nonce_uniqueness_across_many_writes(): void { $this->assertSame( count( $nonces ), count( array_unique( $nonces ) ) ); } + /** + * @covers WP_Secrets_Cipher::fingerprint + */ public function test_fingerprint_is_stable_for_the_same_inputs(): void { $cipher = new WP_Secrets_Cipher(); @@ -307,6 +356,9 @@ public function test_fingerprint_is_stable_for_the_same_inputs(): void { ); } + /** + * @covers WP_Secrets_Cipher::fingerprint + */ public function test_fingerprint_differs_across_master_keys(): void { $cipher = new WP_Secrets_Cipher(); @@ -316,6 +368,9 @@ public function test_fingerprint_differs_across_master_keys(): void { ); } + /** + * @covers WP_Secrets_Cipher::fingerprint + */ public function test_fingerprint_differs_across_plaintexts(): void { $cipher = new WP_Secrets_Cipher(); @@ -325,6 +380,9 @@ public function test_fingerprint_differs_across_plaintexts(): void { ); } + /** + * @covers WP_Secrets_Cipher::fingerprint + */ public function test_fingerprint_rejects_a_bad_master_key(): void { $cipher = new WP_Secrets_Cipher(); @@ -334,6 +392,9 @@ public function test_fingerprint_rejects_a_bad_master_key(): void { $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code() ); } + /** + * @covers WP_Secrets_Cipher::fingerprint + */ public function test_fingerprint_rejects_a_non_string_value(): void { $cipher = new WP_Secrets_Cipher(); @@ -349,6 +410,8 @@ public function test_fingerprint_rejects_a_non_string_value(): void { * both PHP 7.4 and 8.5 and pinned here so an accidental change to either * primitive, the KDF subkey id, the context string, or the output length is * caught rather than silently changing every existing fingerprint. + * + * @covers WP_Secrets_Cipher::fingerprint */ public function test_fingerprint_known_answer_vector(): void { $cipher = new WP_Secrets_Cipher(); @@ -362,6 +425,8 @@ public function test_fingerprint_known_answer_vector(): void { * Pins the exact AAD format. A reviewer reordering these fields, or a future * commit accidentally dropping the site id or slot, silently weakens the binding * this whole design leans on – this test makes that change loud instead. + * + * @covers WP_Secrets_Cipher::build_aad */ public function test_aad_format_known_answer(): void { $cipher = new WP_Secrets_Cipher(); @@ -383,6 +448,8 @@ public function test_aad_format_known_answer(): void { * exists purely to catch a libsodium/sodium_compat behavior change or version * mismatch that our own round-trip tests, which always encrypt and decrypt with * the same implementation, would never surface. + * + * @coversNothing */ public function test_raw_aead_primitive_known_answer(): void { $key = str_repeat( chr( 0x22 ), 32 ); diff --git a/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php b/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php index b14d19549cb0e..4e6b9a002e765 100644 --- a/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php +++ b/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php @@ -9,6 +9,8 @@ * process including an isolated one, so the salt-fallback path is exercised against * whatever the ambient harness defines them as rather than a value this suite picks. * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_WPSecretsConfigKeyProvider extends WP_UnitTestCase { @@ -30,10 +32,17 @@ private function invoke_private( object $instance, string $method, array $args = return $reflection->invokeArgs( $instance, $args ); } + /** + * @coversNothing + */ public function test_implements_the_keyring_interface(): void { $this->assertInstanceOf( WP_Secrets_Keyring::class, new WP_Secrets_Config_Key_Provider() ); // @phpstan-ignore method.alreadyNarrowedType (Pins the interface the class declares, so removing it fails a test.) } + /** + * @covers WP_Secrets_Config_Key_Provider::wrap + * @covers WP_Secrets_Config_Key_Provider::unwrap + */ public function test_wrap_then_unwrap_round_trips(): void { $provider = new WP_Secrets_Config_Key_Provider(); $material = random_bytes( 32 ); @@ -45,6 +54,9 @@ public function test_wrap_then_unwrap_round_trips(): void { $this->assertSame( $material, $unwrapped ); } + /** + * @covers WP_Secrets_Config_Key_Provider::wrap + */ public function test_wrap_rejects_an_empty_string(): void { $provider = new WP_Secrets_Config_Key_Provider(); @@ -54,6 +66,9 @@ public function test_wrap_rejects_an_empty_string(): void { $this->assertSame( WP_SECRETS_ERROR_INVALID_VALUE, $result->get_error_code() ); } + /** + * @covers WP_Secrets_Config_Key_Provider::wrap + */ public function test_two_wraps_of_the_same_material_produce_different_output(): void { $provider = new WP_Secrets_Config_Key_Provider(); $material = random_bytes( 32 ); @@ -61,6 +76,9 @@ public function test_two_wraps_of_the_same_material_produce_different_output(): $this->assertNotSame( $provider->wrap( $material ), $provider->wrap( $material ) ); } + /** + * @covers WP_Secrets_Config_Key_Provider::unwrap + */ public function test_unwrap_rejects_an_empty_string(): void { $provider = new WP_Secrets_Config_Key_Provider(); @@ -70,6 +88,9 @@ public function test_unwrap_rejects_an_empty_string(): void { $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code() ); } + /** + * @covers WP_Secrets_Config_Key_Provider::unwrap + */ public function test_unwrap_rejects_garbage_base64(): void { $provider = new WP_Secrets_Config_Key_Provider(); @@ -79,6 +100,9 @@ public function test_unwrap_rejects_garbage_base64(): void { $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code() ); } + /** + * @covers WP_Secrets_Config_Key_Provider::unwrap + */ public function test_unwrap_rejects_data_too_short_to_contain_a_nonce(): void { $provider = new WP_Secrets_Config_Key_Provider(); @@ -88,6 +112,9 @@ public function test_unwrap_rejects_data_too_short_to_contain_a_nonce(): void { $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code() ); } + /** + * @covers WP_Secrets_Config_Key_Provider::unwrap + */ public function test_unwrap_rejects_a_tampered_ciphertext(): void { $provider = new WP_Secrets_Config_Key_Provider(); $wrapped = $provider->wrap( random_bytes( 32 ) ); @@ -106,6 +133,9 @@ public function test_unwrap_rejects_a_tampered_ciphertext(): void { $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code() ); } + /** + * @covers WP_Secrets_Config_Key_Provider::get_key_source + */ public function test_get_key_source_reports_the_salt_fallback_when_wp_secrets_key_is_unset(): void { if ( 'put your unique phrase here' === LOGGED_IN_KEY || 'put your unique phrase here' === LOGGED_IN_SALT ) { $this->markTestSkipped( 'Needs real LOGGED_IN_KEY and LOGGED_IN_SALT values; wp-tests-config-sample.php ships placeholders.' ); @@ -117,6 +147,8 @@ public function test_get_key_source_reports_the_salt_fallback_when_wp_secrets_ke } /** + * @covers WP_Secrets_Config_Key_Provider::is_canonical_base64_32 + * * @dataProvider data_canonical_base64_32 * * @param string|int $value Candidate value. @@ -144,6 +176,8 @@ public static function data_canonical_base64_32(): array { } /** + * @covers WP_Secrets_Config_Key_Provider::are_usable_salt_values + * * @dataProvider data_usable_salt_values * * @param string|int|null $key Candidate LOGGED_IN_KEY value. @@ -171,6 +205,8 @@ public static function data_usable_salt_values(): array { } /** + * @covers WP_Secrets_Config_Key_Provider::get_site_key + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -189,6 +225,8 @@ public function test_derives_raw_bytes_when_wp_secrets_key_is_canonical_base64_3 * algorithm, its output length, or its inputs is caught rather than silently * changing what key every existing secret is wrapped under. * + * @covers WP_Secrets_Config_Key_Provider::get_site_key + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -210,6 +248,8 @@ public function test_derives_a_known_answer_via_the_legacy_interpretation(): voi * the legacy (hashed) interpretation rather than being treated as raw key * material of the wrong length. * + * @covers WP_Secrets_Config_Key_Provider::get_site_key + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -227,6 +267,8 @@ public function test_wrong_length_base64_falls_through_to_legacy_interpretation( } /** + * @covers WP_Secrets_Config_Key_Provider::get_site_key + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -241,6 +283,8 @@ public function test_non_string_wp_secrets_key_is_unavailable(): void { } /** + * @covers WP_Secrets_Config_Key_Provider::get_key_source + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -253,6 +297,8 @@ public function test_get_key_source_reports_base64_form(): void { } /** + * @covers WP_Secrets_Config_Key_Provider::get_key_source + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -265,6 +311,9 @@ public function test_get_key_source_reports_legacy_form(): void { } /** + * @covers WP_Secrets_Config_Key_Provider::__construct + * @covers WP_Secrets_Config_Key_Provider::get_site_key + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -280,6 +329,8 @@ public function test_use_previous_key_reads_the_previous_constant(): void { * Defining only the previous-key constant must not affect the current-key * provider: it should still fall through to the salt fallback. * + * @covers WP_Secrets_Config_Key_Provider::get_site_key + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -298,6 +349,8 @@ public function test_previous_key_constant_does_not_leak_into_the_current_key_pa } /** + * @covers WP_Secrets_Config_Key_Provider::get_site_key + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -313,6 +366,9 @@ public function test_use_previous_key_without_the_constant_defined_is_unavailabl * A key rotation unwraps under the outgoing key and wraps under the incoming * one. This proves the two providers actually disagree when they should. * + * @covers WP_Secrets_Config_Key_Provider::wrap + * @covers WP_Secrets_Config_Key_Provider::unwrap + * * @runInSeparateProcess * @preserveGlobalState disabled */ diff --git a/tests/phpunit/tests/secrets/wpSecretsKeyManager.php b/tests/phpunit/tests/secrets/wpSecretsKeyManager.php index 501cba32c0d83..5214ec26df238 100644 --- a/tests/phpunit/tests/secrets/wpSecretsKeyManager.php +++ b/tests/phpunit/tests/secrets/wpSecretsKeyManager.php @@ -2,10 +2,15 @@ /** * Tests for WP_Secrets_Key_Manager. * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_WPSecretsKeyManager extends WP_UnitTestCase { + /** + * @covers WP_Secrets_Key_Manager::get_root_key + */ public function test_get_root_key_generates_and_persists_one(): void { $manager = new WP_Secrets_Key_Manager(); @@ -18,12 +23,18 @@ public function test_get_root_key_generates_and_persists_one(): void { $this->assertNotFalse( get_site_option( WP_Secrets_Key_Manager::ROOT_KEY_OPTION ) ); } + /** + * @covers WP_Secrets_Key_Manager::get_root_key + */ public function test_get_root_key_is_stable_on_the_same_instance(): void { $manager = new WP_Secrets_Key_Manager(); $this->assertSame( $manager->get_root_key(), $manager->get_root_key() ); } + /** + * @covers WP_Secrets_Key_Manager::get_root_key + */ public function test_get_root_key_persists_across_instances(): void { $first = new WP_Secrets_Key_Manager(); $root_a = $first->get_root_key(); @@ -34,6 +45,9 @@ public function test_get_root_key_persists_across_instances(): void { $this->assertSame( $root_a, $root_b ); } + /** + * @covers WP_Secrets_Key_Manager::get_root_key + */ public function test_get_root_key_uses_an_existing_value_rather_than_regenerating(): void { $keyring = new WP_Secrets_Config_Key_Provider(); $known = str_repeat( 'R', 32 ); @@ -45,6 +59,9 @@ public function test_get_root_key_uses_an_existing_value_rather_than_regeneratin $this->assertSame( $known, $manager->get_root_key() ); } + /** + * @covers WP_Secrets_Key_Manager::get_master_key + */ public function test_get_master_key_matches_manual_derivation(): void { $manager = new WP_Secrets_Key_Manager(); $root_key = $manager->get_root_key(); @@ -55,6 +72,9 @@ public function test_get_master_key_matches_manual_derivation(): void { $this->assertSame( $expected, $manager->get_master_key( 'site' ) ); } + /** + * @covers WP_Secrets_Key_Manager::get_master_key + */ public function test_get_master_key_differs_per_site_id(): void { $manager = new WP_Secrets_Key_Manager(); @@ -64,6 +84,9 @@ public function test_get_master_key_differs_per_site_id(): void { ); } + /** + * @covers WP_Secrets_Key_Manager::get_master_key + */ public function test_get_master_key_site_and_network_scope_differ(): void { $manager = new WP_Secrets_Key_Manager(); @@ -73,6 +96,9 @@ public function test_get_master_key_site_and_network_scope_differ(): void { ); } + /** + * @covers WP_Secrets_Key_Manager::get_master_key + */ public function test_get_master_key_network_scope_is_stable(): void { $manager = new WP_Secrets_Key_Manager(); @@ -82,6 +108,9 @@ public function test_get_master_key_network_scope_is_stable(): void { ); } + /** + * @covers WP_Secrets_Key_Manager::get_master_key + */ public function test_get_master_key_defaults_site_id_to_the_current_blog(): void { $manager = new WP_Secrets_Key_Manager(); @@ -91,6 +120,9 @@ public function test_get_master_key_defaults_site_id_to_the_current_blog(): void ); } + /** + * @covers WP_Secrets_Key_Manager::get_master_key + */ public function test_get_master_key_reports_an_invalid_scope_as_a_wp_error(): void { $manager = new WP_Secrets_Key_Manager(); @@ -103,6 +135,8 @@ public function test_get_master_key_reports_an_invalid_scope_as_a_wp_error(): vo } /** + * @covers WP_Secrets_Key_Manager::get_master_key + * * @dataProvider data_invalid_site_ids * * @param int $site_id A value that is not a usable blog id. @@ -134,6 +168,8 @@ public static function data_invalid_site_ids(): array { * this is the entire reason network secrets can be read from any blog. Requires * the multisite suite; skips under single-site since there is only one blog to * compare against. + * + * @covers WP_Secrets_Key_Manager::get_master_key */ public function test_network_scope_master_key_is_identical_across_blogs(): void { if ( ! is_multisite() ) { @@ -155,6 +191,8 @@ public function test_network_scope_master_key_is_identical_across_blogs(): void /** * Site-scope master keys, by contrast, must differ per blog even though every * blog derives from the same shared root key. + * + * @covers WP_Secrets_Key_Manager::get_master_key */ public function test_site_scope_master_key_differs_across_blogs(): void { if ( ! is_multisite() ) { @@ -180,6 +218,8 @@ public function test_site_scope_master_key_differs_across_blogs(): void { * * Requires the multisite suite; skips under single-site since sitemeta and * the main site's options are the same table there. + * + * @covers WP_Secrets_Key_Manager::get_root_key */ public function test_get_root_key_adopts_a_pre_conversion_root_key(): void { if ( ! is_multisite() ) { @@ -208,6 +248,9 @@ public function test_get_root_key_adopts_a_pre_conversion_root_key(): void { /** * Requires the multisite suite; skips under single-site for the same reason * as the adoption test above. + * + * @covers WP_Secrets_Key_Manager::get_root_key + * @covers ::wp_get_secret */ public function test_secret_written_before_conversion_still_decrypts(): void { if ( ! is_multisite() ) { @@ -232,6 +275,8 @@ public function test_secret_written_before_conversion_still_decrypts(): void { /** * Requires the multisite suite; skips under single-site for the same reason * as the adoption test above. + * + * @covers WP_Secrets_Key_Manager::rotate_site_key */ public function test_rotate_site_key_works_after_conversion_before_any_read(): void { if ( ! is_multisite() ) { @@ -260,6 +305,9 @@ public function test_rotate_site_key_works_after_conversion_before_any_read(): v $this->assertSame( $master_before, $master_after ); } + /** + * @covers WP_Secrets_Key_Manager::rotate_site_key + */ public function test_rotate_fails_when_no_root_key_exists(): void { $manager = new WP_Secrets_Key_Manager(); $keyring = new WP_Secrets_Config_Key_Provider(); @@ -270,6 +318,9 @@ public function test_rotate_fails_when_no_root_key_exists(): void { $this->assertSame( WP_SECRETS_ERROR_STORE_UNAVAILABLE, $result->get_error_code() ); } + /** + * @covers WP_Secrets_Key_Manager::rotate_site_key + */ public function test_rotate_fails_when_the_old_keyring_is_wrong(): void { $right_keyring = new WP_Secrets_Config_Key_Provider(); $manager = new WP_Secrets_Key_Manager( $right_keyring ); @@ -311,6 +362,9 @@ public function get_key_source(): string { * This is the whole point of the envelope design, so it gets an end-to-end proof * rather than just testing rotate_site_key() in isolation. * + * @covers WP_Secrets_Key_Manager::rotate_site_key + * @covers WP_Secrets_Key_Manager::get_master_key + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -342,6 +396,10 @@ public function test_rotation_does_not_change_any_derived_master_key(): void { $this->assertWPError( $fresh_manager_under_old_key->get_root_key() ); } + /** + * @covers WP_Secrets_Key_Manager::get_master_key + * @covers WP_Secrets_Key_Manager::get_root_key + */ public function test_unwrap_is_called_once_across_repeated_master_key_derivations(): void { $mock = new Mock_Keyring(); $root = random_bytes( 32 ); @@ -363,6 +421,8 @@ public function test_unwrap_is_called_once_across_repeated_master_key_derivation } /** + * @covers WP_Secrets_Key_Manager::get_root_key + * * @runInSeparateProcess * @preserveGlobalState disabled */ @@ -384,6 +444,10 @@ public function test_unwrap_is_called_once_across_many_secret_reads(): void { $this->assertSame( 1, $mock->unwrap_call_count() ); } + /** + * @covers WP_Secrets_Key_Manager::rotate_site_key + * @covers WP_Secrets_Key_Manager::get_root_key + */ public function test_rotate_site_key_updates_the_cache_without_another_unwrap(): void { $mock = new Mock_Keyring(); $second_mock = new Mock_Keyring(); @@ -400,6 +464,9 @@ public function test_rotate_site_key_updates_the_cache_without_another_unwrap(): $this->assertSame( 0, $second_mock->unwrap_call_count() ); } + /** + * @covers WP_Secrets_Key_Manager::get_root_key + */ public function test_a_changed_wrapped_value_is_unwrapped_again_rather_than_served_from_cache(): void { $mock = new Mock_Keyring(); $root = random_bytes( 32 ); @@ -415,6 +482,9 @@ public function test_a_changed_wrapped_value_is_unwrapped_again_rather_than_serv $this->assertSame( 2, $mock->unwrap_call_count() ); } + /** + * @covers WP_Secrets_Key_Manager::get_root_key + */ public function test_an_unwrap_error_is_not_cached(): void { $mock = new Mock_Keyring(); $root = random_bytes( 32 ); @@ -438,6 +508,10 @@ public function test_an_unwrap_error_is_not_cached(): void { $this->assertSame( 2, $mock->unwrap_call_count() ); } + /** + * @covers WP_Secrets_Key_Manager::get_root_key + * @covers WP_Secrets_Key_Manager::generate_root_key + */ public function test_generate_root_key_primes_the_cache(): void { $mock = new Mock_Keyring(); @@ -449,6 +523,9 @@ public function test_generate_root_key_primes_the_cache(): void { $this->assertSame( 1, $mock->wrap_call_count() ); } + /** + * @covers WP_Secrets_Key_Manager::get_root_key + */ public function test_the_returned_root_key_is_a_copy_the_caller_can_zero(): void { $mock = new Mock_Keyring(); $root = random_bytes( 32 ); diff --git a/tests/phpunit/tests/secrets/wpSecretsMemzero.php b/tests/phpunit/tests/secrets/wpSecretsMemzero.php index 350a3fc6cf7ff..95b35b42b0d59 100644 --- a/tests/phpunit/tests/secrets/wpSecretsMemzero.php +++ b/tests/phpunit/tests/secrets/wpSecretsMemzero.php @@ -1,9 +1,14 @@ assertSame( '', $value ); } + /** + * @covers ::wp_secrets_memzero + */ public function test_leaves_non_string_values_untouched(): void { $value = 42; @@ -21,6 +29,9 @@ public function test_leaves_non_string_values_untouched(): void { $this->assertSame( 42, $value ); } + /** + * @covers ::wp_secrets_memzero + */ public function test_leaves_an_empty_string_untouched(): void { $value = ''; @@ -29,6 +40,9 @@ public function test_leaves_an_empty_string_untouched(): void { $this->assertSame( '', $value ); } + /** + * @covers ::wp_secrets_memzero + */ public function test_does_not_throw_when_the_value_is_shared(): void { $value = 'shared plaintext'; $copy = $value; diff --git a/tests/phpunit/tests/secrets/wpSecretsOptionStore.php b/tests/phpunit/tests/secrets/wpSecretsOptionStore.php index 2c612624a8798..e83c283290d5f 100644 --- a/tests/phpunit/tests/secrets/wpSecretsOptionStore.php +++ b/tests/phpunit/tests/secrets/wpSecretsOptionStore.php @@ -2,6 +2,8 @@ /** * Tests for WP_Secrets_Option_Store. * + * @ticket 66187 + * * @group secrets */ class Tests_Secrets_WPSecretsOptionStore extends WP_UnitTestCase { @@ -25,16 +27,26 @@ private function sample_record(): array { ); } + /** + * @coversNothing + */ public function test_implements_the_store_interface(): void { $this->assertInstanceOf( WP_Secrets_Store::class, new WP_Secrets_Option_Store() ); // @phpstan-ignore method.alreadyNarrowedType (Pins the interface the class declares, so removing it fails a test.) } + /** + * @covers WP_Secrets_Option_Store::get + */ public function test_get_returns_null_for_an_absent_secret(): void { $store = new WP_Secrets_Option_Store(); $this->assertNull( $store->get( 'myplugin/absent' ) ); } + /** + * @covers WP_Secrets_Option_Store::set + * @covers WP_Secrets_Option_Store::get + */ public function test_set_then_get_round_trips_a_record_site_scope(): void { $store = new WP_Secrets_Option_Store(); $record = $this->sample_record(); @@ -43,6 +55,10 @@ public function test_set_then_get_round_trips_a_record_site_scope(): void { $this->assertSame( $record, $store->get( 'myplugin/key' ) ); } + /** + * @covers WP_Secrets_Option_Store::set + * @covers WP_Secrets_Option_Store::get + */ public function test_set_then_get_round_trips_a_record_network_scope(): void { $store = new WP_Secrets_Option_Store(); $record = $this->sample_record(); @@ -51,6 +67,10 @@ public function test_set_then_get_round_trips_a_record_network_scope(): void { $this->assertSame( $record, $store->get( 'myplugin/key', true ) ); } + /** + * @covers WP_Secrets_Option_Store::set + * @covers WP_Secrets_Option_Store::get + */ public function test_site_and_network_scope_do_not_collide(): void { $store = new WP_Secrets_Option_Store(); $site_record = $this->sample_record(); @@ -63,6 +83,9 @@ public function test_site_and_network_scope_do_not_collide(): void { $this->assertSame( $network_record, $store->get( 'myplugin/key', true ) ); } + /** + * @covers WP_Secrets_Option_Store::get + */ public function test_get_returns_an_error_when_the_stored_value_is_not_an_array(): void { update_option( '_wp_secret_myplugin/key', 'not an array', false ); @@ -74,6 +97,9 @@ public function test_get_returns_an_error_when_the_stored_value_is_not_an_array( $this->assertSame( WP_SECRETS_ERROR_RECORD_MALFORMED, $result->get_error_code() ); } + /** + * @covers WP_Secrets_Option_Store::delete + */ public function test_delete_removes_an_existing_record(): void { $store = new WP_Secrets_Option_Store(); $store->set( 'myplugin/key', $this->sample_record() ); @@ -82,6 +108,9 @@ public function test_delete_removes_an_existing_record(): void { $this->assertNull( $store->get( 'myplugin/key' ) ); } + /** + * @covers WP_Secrets_Option_Store::delete + */ public function test_delete_on_an_absent_record_is_not_an_error(): void { $store = new WP_Secrets_Option_Store(); @@ -89,6 +118,8 @@ public function test_delete_on_an_absent_record_is_not_an_error(): void { } /** + * @covers WP_Secrets_Option_Store::set + * * @global wpdb $wpdb WordPress database abstraction object. */ public function test_site_scope_records_are_not_autoloaded(): void { @@ -107,6 +138,9 @@ public function test_site_scope_records_are_not_autoloaded(): void { $this->assertContains( $autoload, array( 'no', 'off' ) ); } + /** + * @covers WP_Secrets_Option_Store::list_names + */ public function test_list_names_returns_stored_names_without_the_prefix(): void { $store = new WP_Secrets_Option_Store(); $store->set( 'myplugin/one', $this->sample_record() ); @@ -119,6 +153,9 @@ public function test_list_names_returns_stored_names_without_the_prefix(): void $this->assertContains( 'myplugin/two', $names ); } + /** + * @covers WP_Secrets_Option_Store::list_names + */ public function test_list_names_does_not_include_unrelated_options(): void { update_option( 'completely_unrelated_option', 'value' ); @@ -131,6 +168,9 @@ public function test_list_names_does_not_include_unrelated_options(): void { $this->assertNotContains( 'completely_unrelated_option', $names ); } + /** + * @covers WP_Secrets_Option_Store::list_names + */ public function test_list_names_does_not_include_network_scope_names(): void { $store = new WP_Secrets_Option_Store(); $store->set( 'myplugin/site-only', $this->sample_record(), false ); @@ -151,6 +191,8 @@ public function test_list_names_does_not_include_network_scope_names(): void { * '_' is a single-character wildcard in SQL LIKE. An option name with any other * character where the prefix's underscore falls must not match unless the prefix * is properly escaped before the query is built. + * + * @covers WP_Secrets_Option_Store::list_names */ public function test_list_names_escapes_the_underscore_wildcard(): void { // Would match "_wp_secret_%" under an *unescaped* LIKE, since '_' matches diff --git a/tests/phpunit/tests/secrets/wpSecretsValidateName.php b/tests/phpunit/tests/secrets/wpSecretsValidateName.php index 7555552d39674..6b4b01c667b20 100644 --- a/tests/phpunit/tests/secrets/wpSecretsValidateName.php +++ b/tests/phpunit/tests/secrets/wpSecretsValidateName.php @@ -1,10 +1,14 @@ assertTrue( wp_set_secret( 'myplugin/api-key', 'sk_live_secret' ) ); @@ -19,10 +25,16 @@ public function test_set_then_get_round_trips(): void { $this->assertNotSame( '', $secret->fingerprint() ); } + /** + * @covers ::wp_get_secret + */ public function test_get_returns_null_for_an_absent_secret(): void { $this->assertNull( wp_get_secret( 'myplugin/never-set' ) ); } + /** + * @covers ::wp_get_secret + */ public function test_get_defaults_to_the_current_version(): void { wp_set_secret( 'myplugin/api-key', 'value' ); @@ -34,6 +46,9 @@ public function test_get_defaults_to_the_current_version(): void { $this->assertSame( $default->reveal(), $current->reveal() ); } + /** + * @covers ::wp_get_secret + */ public function test_get_previous_on_a_never_rotated_secret_is_null_not_error(): void { wp_set_secret( 'myplugin/api-key', 'value' ); @@ -45,6 +60,8 @@ public function test_get_previous_on_a_never_rotated_secret_is_null_not_error(): * WP_Error plus a _doing_it_wrong() notice rather than by throwing. The * WP_Error branch of the three-state contract already covers it, so this adds * no fourth state. + * + * @covers ::wp_get_secret */ public function test_an_invalid_version_is_a_wp_error_not_an_exception(): void { $this->setExpectedIncorrectUsage( '_wp_secrets_get' ); @@ -55,6 +72,9 @@ public function test_an_invalid_version_is_a_wp_error_not_an_exception(): void { $this->assertSame( WP_SECRETS_ERROR_INVALID_ARGUMENT, $result->get_error_code() ); } + /** + * @covers ::wp_set_secret + */ public function test_set_rejects_an_invalid_name(): void { $result = wp_set_secret( 'Not A Valid Name', 'value' ); @@ -62,6 +82,9 @@ public function test_set_rejects_an_invalid_name(): void { $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code() ); } + /** + * @covers ::wp_get_secret + */ public function test_get_rejects_an_invalid_name(): void { $result = wp_get_secret( 'Not A Valid Name' ); @@ -69,6 +92,9 @@ public function test_get_rejects_an_invalid_name(): void { $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code() ); } + /** + * @covers ::wp_set_secret + */ public function test_set_rejects_a_non_string_value(): void { $result = wp_set_secret( 'myplugin/api-key', array( 'not', 'a', 'string' ) ); // @phpstan-ignore argument.type (Intentionally passing an invalid value.) @@ -76,6 +102,10 @@ public function test_set_rejects_a_non_string_value(): void { $this->assertSame( WP_SECRETS_ERROR_INVALID_VALUE, $result->get_error_code() ); } + /** + * @covers ::wp_set_secret + * @covers ::wp_get_secret + */ public function test_set_accepts_an_empty_string_value(): void { $this->assertTrue( wp_set_secret( 'myplugin/api-key', '' ) ); @@ -88,6 +118,8 @@ public function test_set_accepts_an_empty_string_value(): void { /** * Overwriting is the only repair path an operator has through this API, so a * corrupted existing record must not block a write. + * + * @covers ::wp_set_secret */ public function test_a_corrupt_record_can_be_overwritten(): void { update_option( '_wp_secret_myplugin/corrupt', 'not a record at all', false ); @@ -104,6 +136,9 @@ public function test_a_corrupt_record_can_be_overwritten(): void { * Nothing plaintext reaches the database. Scans every option row rather than just * the secret's own, since the failure this guards against is a plaintext landing * somewhere unexpected. + * + * @covers ::wp_set_secret + * @covers WP_Secrets_Libsodium_Provider::set */ public function test_the_options_table_contains_no_plaintext_after_a_write(): void { global $wpdb; @@ -125,6 +160,8 @@ public function test_the_options_table_contains_no_plaintext_after_a_write(): vo * The retrieval path clears its own local copy once the WP_Secret owns the value; * that only leaves the vault intact because PHP's copy-on-write splits the two * references first. + * + * @covers ::wp_get_secret */ public function test_reveal_still_works_after_the_internal_memzero(): void { wp_set_secret( 'myplugin/api-key', 'must-survive-memzero' ); @@ -135,6 +172,10 @@ public function test_reveal_still_works_after_the_internal_memzero(): void { $this->assertSame( 'must-survive-memzero', $secret->reveal() ); } + /** + * @covers ::wp_set_secret + * @covers ::wp_get_secret + */ public function test_no_capability_check_is_applied(): void { wp_set_current_user( 0 ); // No logged-in user, no capabilities at all. @@ -142,6 +183,9 @@ public function test_no_capability_check_is_applied(): void { $this->assertInstanceOf( WP_Secret::class, wp_get_secret( 'myplugin/api-key' ) ); } + /** + * @covers ::wp_set_secret + */ public function test_change_hook_fires_on_create_with_created_action(): void { $captured = null; add_action( @@ -165,6 +209,9 @@ function ( ...$args ) use ( &$captured ) { $this->assertFalse( $network ); } + /** + * @covers ::wp_set_secret + */ public function test_change_hook_fires_on_overwrite_with_updated_action(): void { wp_set_secret( 'myplugin/api-key', 'first-value' ); $first = wp_get_secret( 'myplugin/api-key' ); @@ -192,6 +239,9 @@ function ( ...$args ) use ( &$captured ) { $this->assertNotSame( $old_fingerprint, $new_fingerprint ); } + /** + * @covers ::wp_set_secret + */ public function test_change_hook_reports_the_current_user_as_actor(): void { $user_id = self::factory()->user->create(); wp_set_current_user( $user_id ); @@ -211,6 +261,9 @@ function ( $name, $action, $actor_id ) use ( &$captured_actor ) { $this->assertSame( $user_id, $captured_actor ); } + /** + * @covers ::wp_set_secret + */ public function test_change_hook_never_receives_a_value(): void { $captured_args = null; add_action( From 7eeda63d1d3cc14ddd23271121e8b8a95affdcb3 Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 09:46:42 +1100 Subject: [PATCH 03/28] Add summaries to each and every test. --- .../class-wp-secrets-provider-conformance.php | 27 ++++++++++ .../tests/secrets/brokenDropinFallbacks.php | 22 ++++++++ tests/phpunit/tests/secrets/capabilities.php | 28 ++++++++++ tests/phpunit/tests/secrets/errorCodes.php | 6 +++ .../phpunit/tests/secrets/extensionPoints.php | 10 ++++ tests/phpunit/tests/secrets/networkScope.php | 20 +++++++ tests/phpunit/tests/secrets/provider.php | 13 +++++ tests/phpunit/tests/secrets/siteHealth.php | 43 +++++++++++++++ .../tests/secrets/threeStateContract.php | 12 +++++ tests/phpunit/tests/secrets/versionSlots.php | 28 ++++++++++ .../phpunit/tests/secrets/wpDeleteSecret.php | 15 ++++++ .../tests/secrets/wpImportOptionAsSecret.php | 19 +++++++ tests/phpunit/tests/secrets/wpListSecrets.php | 21 ++++++++ tests/phpunit/tests/secrets/wpSecret.php | 35 +++++++++++++ .../phpunit/tests/secrets/wpSecretVersion.php | 11 ++++ .../phpunit/tests/secrets/wpSecretsCipher.php | 50 ++++++++++++++++++ .../secrets/wpSecretsConfigKeyProvider.php | 37 +++++++++++++ .../tests/secrets/wpSecretsKeyManager.php | 52 +++++++++++++++++++ .../tests/secrets/wpSecretsMemzero.php | 8 +++ .../tests/secrets/wpSecretsOptionStore.php | 27 ++++++++++ .../tests/secrets/wpSecretsValidateName.php | 4 ++ .../secrets/wpSetSecretAndWpGetSecret.php | 32 ++++++++++++ 22 files changed, 520 insertions(+) diff --git a/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php b/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php index 62aa105959c12..ad0dbdaf4a3f3 100644 --- a/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php +++ b/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php @@ -103,6 +103,8 @@ private function has_previous_version( WP_Secrets_Provider $provider, $name ) { // – declarations must be coherent ---------------------------------------- /** + * Ensure that the provider reports a label that is neither empty nor only whitespace. + * * @covers WP_Secrets_Provider::get_label */ public function test_reports_a_non_empty_label(): void { @@ -113,6 +115,8 @@ public function test_reports_a_non_empty_label(): void { } /** + * Ensure that the provider reports one of the BOUNDARY_* constants as its protection boundary. + * * @covers WP_Secrets_Provider::get_protection_boundary */ public function test_reports_a_known_protection_boundary(): void { @@ -124,6 +128,8 @@ public function test_reports_a_known_protection_boundary(): void { } /** + * Ensure that the provider declares whether it accepts writes as a boolean. + * * @covers WP_Secrets_Provider::is_writable */ public function test_is_writable_returns_a_bool(): void { @@ -191,6 +197,8 @@ public function test_previous_on_a_provider_or_secret_without_history_is_null_no } /** + * Ensure that the provider treats deleting a secret that was never set as success. + * * @covers WP_Secrets_Provider::delete */ public function test_deleting_something_absent_is_success(): void { @@ -204,6 +212,8 @@ public function test_deleting_something_absent_is_success(): void { } /** + * Ensure that the provider treats retiring a secret that has no previous version as success. + * * @covers WP_Secrets_Provider::retire_previous */ public function test_retiring_with_no_previous_version_is_success(): void { @@ -219,6 +229,8 @@ public function test_retiring_with_no_previous_version_is_success(): void { // – the round trip -------------------------------------------------------- /** + * Ensure that the provider returns a stored value unchanged, under the name it was stored as. + * * @covers WP_Secrets_Provider::set * @covers WP_Secrets_Provider::get */ @@ -300,6 +312,8 @@ public function test_writing_an_unchanged_value_keeps_the_previous_version(): vo } /** + * Ensure that the provider reports a deleted secret as absent. + * * @covers WP_Secrets_Provider::delete * @covers WP_Secrets_Provider::get */ @@ -348,6 +362,8 @@ public function test_a_successful_write_reports_a_change(): void { } /** + * Ensure that the provider reports an action override passed to set() to wp_secret_changed unchanged. + * * @covers WP_Secrets_Provider::set */ public function test_an_action_override_is_reported_as_given(): void { @@ -385,6 +401,8 @@ public function test_a_network_scope_change_reports_its_scope(): void { } /** + * Ensure that the provider fires wp_secret_changed once, as deleted, when a secret is deleted. + * * @covers WP_Secrets_Provider::delete */ public function test_deleting_a_secret_reports_a_change(): void { @@ -436,6 +454,8 @@ public function test_retiring_a_previous_version_reports_a_change(): void { } /** + * Ensure that a read-only provider does not fire wp_secret_changed for a write it refused. + * * @covers WP_Secrets_Provider::set */ public function test_a_refused_write_reports_no_change(): void { @@ -454,6 +474,11 @@ public function test_a_refused_write_reports_no_change(): void { // – listing never leaks --------------------------------------------------- /** + * Ensure that the provider's listing of secrets never contains a stored plaintext value. + * + * The whole listing is encoded and searched rather than checked field by field, so a + * value leaked under any key, including one the contract does not define, is caught. + * * @covers WP_Secrets_Provider::list_secrets */ public function test_listing_returns_an_array_or_an_error_and_never_a_value(): void { @@ -478,6 +503,8 @@ public function test_listing_returns_an_array_or_an_error_and_never_a_value(): v } /** + * Ensure that the provider includes the name of a stored secret in its listing. + * * @covers WP_Secrets_Provider::list_secrets */ public function test_listing_includes_a_stored_secret(): void { diff --git a/tests/phpunit/tests/secrets/brokenDropinFallbacks.php b/tests/phpunit/tests/secrets/brokenDropinFallbacks.php index 8d73e77646f85..49bfdd28dae2d 100644 --- a/tests/phpunit/tests/secrets/brokenDropinFallbacks.php +++ b/tests/phpunit/tests/secrets/brokenDropinFallbacks.php @@ -11,6 +11,8 @@ class Tests_Secrets_BrokenDropinFallbacks extends WP_UnitTestCase { /** + * Ensure that WP_Secrets_Broken_Store implements the WP_Secrets_Store interface. + * * @coversNothing */ public function test_broken_store_implements_the_interface(): void { @@ -18,6 +20,8 @@ public function test_broken_store_implements_the_interface(): void { } /** + * Ensure that WP_Secrets_Broken_Store::get() fails with a store-unavailable error. + * * @covers WP_Secrets_Broken_Store::get */ public function test_broken_store_get_fails(): void { @@ -28,6 +32,8 @@ public function test_broken_store_get_fails(): void { } /** + * Ensure that WP_Secrets_Broken_Store::set() returns a WP_Error rather than storing a record. + * * @covers WP_Secrets_Broken_Store::set */ public function test_broken_store_set_fails(): void { @@ -37,6 +43,8 @@ public function test_broken_store_set_fails(): void { } /** + * Ensure that WP_Secrets_Broken_Store::delete() returns a WP_Error. + * * @covers WP_Secrets_Broken_Store::delete */ public function test_broken_store_delete_fails(): void { @@ -46,6 +54,8 @@ public function test_broken_store_delete_fails(): void { } /** + * Ensure that WP_Secrets_Broken_Store::list_names() returns a WP_Error rather than a list. + * * @covers WP_Secrets_Broken_Store::list_names */ public function test_broken_store_list_names_fails(): void { @@ -55,6 +65,8 @@ public function test_broken_store_list_names_fails(): void { } /** + * Ensure that WP_Secrets_Broken_Keyring implements the WP_Secrets_Keyring interface. + * * @coversNothing */ public function test_broken_keyring_implements_the_interface(): void { @@ -62,6 +74,8 @@ public function test_broken_keyring_implements_the_interface(): void { } /** + * Ensure that WP_Secrets_Broken_Keyring::wrap() fails with a key-unavailable error. + * * @covers WP_Secrets_Broken_Keyring::wrap */ public function test_broken_keyring_wrap_fails(): void { @@ -72,6 +86,8 @@ public function test_broken_keyring_wrap_fails(): void { } /** + * Ensure that WP_Secrets_Broken_Keyring::unwrap() returns a WP_Error. + * * @covers WP_Secrets_Broken_Keyring::unwrap */ public function test_broken_keyring_unwrap_fails(): void { @@ -81,6 +97,8 @@ public function test_broken_keyring_unwrap_fails(): void { } /** + * Ensure that WP_Secrets_Broken_Keyring::get_key_source() returns a description for Site Health. + * * @covers WP_Secrets_Broken_Keyring::get_key_source */ public function test_broken_keyring_reports_a_key_source(): void { @@ -88,6 +106,8 @@ public function test_broken_keyring_reports_a_key_source(): void { } /** + * Ensure that wp_using_secrets_dropin() returns false when no drop-in has been loaded. + * * @covers ::wp_using_secrets_dropin */ public function test_wp_using_secrets_dropin_is_false_by_default(): void { @@ -95,6 +115,8 @@ public function test_wp_using_secrets_dropin_is_false_by_default(): void { } /** + * Ensure that wp_using_secrets_dropin() returns true once the drop-in loader flag is set. + * * @covers ::wp_using_secrets_dropin * * @runInSeparateProcess diff --git a/tests/phpunit/tests/secrets/capabilities.php b/tests/phpunit/tests/secrets/capabilities.php index 547a17deb0718..634a7afde6596 100644 --- a/tests/phpunit/tests/secrets/capabilities.php +++ b/tests/phpunit/tests/secrets/capabilities.php @@ -43,6 +43,11 @@ private function role( $role ) { } /** + * Ensure that the capability constants hold the manage_secrets and manage_network_secrets names. + * + * The capability names are a public contract: plugins and role editors check the + * strings directly, so the constants must not drift from them. + * * @coversNothing */ public function test_capability_constant_values(): void { @@ -51,6 +56,11 @@ public function test_capability_constant_values(): void { } /** + * Ensure that the administrator role has manage_secrets on a fresh install. + * + * The test suite's install runs populate_roles(), so no setup is needed to observe + * the state a new site starts in. + * * @covers ::populate_roles_720 */ public function test_a_fresh_install_grants_manage_secrets_to_administrator(): void { @@ -58,6 +68,8 @@ public function test_a_fresh_install_grants_manage_secrets_to_administrator(): v } /** + * Ensure that no default role other than administrator is granted manage_secrets. + * * @covers ::populate_roles_720 */ public function test_no_other_role_is_granted_manage_secrets(): void { @@ -67,6 +79,8 @@ public function test_no_other_role_is_granted_manage_secrets(): void { } /** + * Ensure that populate_roles_720() grants manage_secrets to the administrator role. + * * @covers ::populate_roles_720 */ public function test_populate_roles_720_grants_manage_secrets_to_administrator(): void { @@ -78,6 +92,12 @@ public function test_populate_roles_720_grants_manage_secrets_to_administrator() } /** + * Ensure that upgrade_720() grants manage_secrets only to sites below database version 64337. + * + * Simulates upgrades from several database versions by overriding $wp_current_db_version. + * Sites already at or past the gate must not have the capability re-added, so an + * administrator's deliberate removal of it survives later upgrades. + * * @covers ::upgrade_720 * * @dataProvider data_upgrade_720_gate @@ -115,6 +135,8 @@ public static function data_upgrade_720_gate() { } /** + * Ensure that a user with the administrator role can manage secrets. + * * @covers ::populate_roles_720 */ public function test_administrator_user_has_manage_secrets(): void { @@ -124,6 +146,8 @@ public function test_administrator_user_has_manage_secrets(): void { } /** + * Ensure that a user with the subscriber role cannot manage secrets. + * * @covers ::populate_roles_720 */ public function test_subscriber_does_not_have_manage_secrets(): void { @@ -133,6 +157,8 @@ public function test_subscriber_does_not_have_manage_secrets(): void { } /** + * Ensure that an administrator on a single site install does not have manage_network_secrets. + * * @group ms-excluded * * @covers ::map_meta_cap @@ -144,6 +170,8 @@ public function test_single_site_administrator_does_not_have_manage_network_secr } /** + * Ensure that only super admins have the manage_network_secrets capability. + * * @group ms-required * * @covers ::map_meta_cap diff --git a/tests/phpunit/tests/secrets/errorCodes.php b/tests/phpunit/tests/secrets/errorCodes.php index 1cd0e8aee4fa1..ba266dcd33e2d 100644 --- a/tests/phpunit/tests/secrets/errorCodes.php +++ b/tests/phpunit/tests/secrets/errorCodes.php @@ -10,6 +10,8 @@ class Tests_Secrets_ErrorCodes extends WP_UnitTestCase { /** + * Ensure that each error code constant holds its published string value. + * * @coversNothing * * @dataProvider data_published_error_codes @@ -37,6 +39,8 @@ public static function data_published_error_codes() { } /** + * Ensure that no two error code constants share a value. + * * @coversNothing */ public function test_all_error_codes_are_distinct(): void { @@ -54,6 +58,8 @@ public function test_all_error_codes_are_distinct(): void { } /** + * Ensure that WP_SECRETS_MAX_NAME_LENGTH fits the longest prefixed name in option_name. + * * @coversNothing */ public function test_max_name_length_matches_the_options_column_budget(): void { diff --git a/tests/phpunit/tests/secrets/extensionPoints.php b/tests/phpunit/tests/secrets/extensionPoints.php index 2d89d6ad0fe73..5d950bf21f960 100644 --- a/tests/phpunit/tests/secrets/extensionPoints.php +++ b/tests/phpunit/tests/secrets/extensionPoints.php @@ -27,6 +27,8 @@ class Tests_Secrets_ExtensionPoints extends WP_UnitTestCase { use WP_Secrets_Assertions; /** + * Ensure that a secret round-trips through a plugin-supplied store paired with the default keyring. + * * @covers ::_wp_secrets_get_store * * @runInSeparateProcess @@ -47,6 +49,8 @@ public function test_mock_store_with_the_default_keyring_round_trips(): void { } /** + * Ensure that a secret round-trips through a plugin-supplied keyring paired with the default store. + * * @covers ::_wp_secrets_get_key_manager * * @runInSeparateProcess @@ -64,6 +68,8 @@ public function test_mock_keyring_with_the_default_store_round_trips(): void { } /** + * Ensure that a secret round-trips when both the store and the keyring are plugin-supplied. + * * @covers ::_wp_secrets_get_store * @covers ::_wp_secrets_get_key_manager * @@ -141,6 +147,8 @@ public function test_a_store_that_refuses_writes_still_serves_reads(): void { } /** + * Ensure that an unreachable plugin-supplied store fails reads and writes without a local fallback. + * * @covers ::_wp_secrets_get_store * @covers ::wp_set_secret * @covers ::wp_get_secret @@ -164,6 +172,8 @@ public function test_unreachable_store_fails_closed_with_no_local_fallback(): vo } /** + * Ensure that a keyring that cannot wrap keys fails the write and stores nothing locally. + * * @covers ::_wp_secrets_get_key_manager * @covers ::wp_set_secret * diff --git a/tests/phpunit/tests/secrets/networkScope.php b/tests/phpunit/tests/secrets/networkScope.php index 105bb3b5c94b2..1c9e1a6a395ab 100644 --- a/tests/phpunit/tests/secrets/networkScope.php +++ b/tests/phpunit/tests/secrets/networkScope.php @@ -11,6 +11,8 @@ class Tests_Secrets_NetworkScope extends WP_UnitTestCase { use WP_Secrets_Assertions; /** + * Ensure that a value stored by wp_set_network_secret() is returned by wp_get_network_secret(). + * * @covers ::wp_set_network_secret * @covers ::wp_get_network_secret */ @@ -24,6 +26,8 @@ public function test_set_then_get_round_trips(): void { } /** + * Ensure that wp_get_network_secret() returns null for a network secret that was never set. + * * @covers ::wp_get_network_secret */ public function test_get_returns_null_for_an_absent_secret(): void { @@ -31,6 +35,8 @@ public function test_get_returns_null_for_an_absent_secret(): void { } /** + * Ensure that a site secret and a network secret with the same name hold separate values. + * * @covers ::wp_set_network_secret * @covers ::wp_get_network_secret */ @@ -48,6 +54,8 @@ public function test_site_and_network_scope_are_independent_under_the_same_name( } /** + * Ensure that wp_delete_network_secret() removes a network secret so it can no longer be read. + * * @covers ::wp_delete_network_secret */ public function test_delete_removes_a_network_secret(): void { @@ -58,6 +66,8 @@ public function test_delete_removes_a_network_secret(): void { } /** + * Ensure that wp_delete_network_secret() leaves a site secret of the same name in place. + * * @covers ::wp_delete_network_secret */ public function test_delete_does_not_touch_the_site_scope_secret_of_the_same_name(): void { @@ -73,6 +83,8 @@ public function test_delete_does_not_touch_the_site_scope_secret_of_the_same_nam } /** + * Ensure that overwriting a network secret demotes the old value to the previous slot. + * * @covers ::wp_set_network_secret */ public function test_previous_version_and_demotion_work_the_same_as_site_scope(): void { @@ -84,6 +96,8 @@ public function test_previous_version_and_demotion_work_the_same_as_site_scope() } /** + * Ensure that wp_retire_network_secret_version() clears the previous version of a network secret. + * * @covers ::wp_retire_network_secret_version */ public function test_retire_clears_the_previous_slot(): void { @@ -133,6 +147,8 @@ function ( ...$args ) use ( &$scopes ) { } /** + * Ensure that wp_list_network_secrets() lists network secrets and omits site secrets. + * * @covers ::wp_list_network_secrets */ public function test_list_returns_network_secrets_only(): void { @@ -146,6 +162,8 @@ public function test_list_returns_network_secrets_only(): void { } /** + * Ensure that wp_get_network_secret() returns a WP_Error for an unrecognized version. + * * @covers ::wp_get_network_secret * @covers ::_wp_secrets_get */ @@ -159,6 +177,8 @@ public function test_an_invalid_version_is_a_wp_error_same_as_site_scope(): void } /** + * Ensure that wp_set_network_secret() rejects a name that fails validation. + * * @covers ::wp_set_network_secret */ public function test_set_rejects_an_invalid_name(): void { diff --git a/tests/phpunit/tests/secrets/provider.php b/tests/phpunit/tests/secrets/provider.php index 8c208708129c0..d278e85b19fd9 100644 --- a/tests/phpunit/tests/secrets/provider.php +++ b/tests/phpunit/tests/secrets/provider.php @@ -97,6 +97,8 @@ public function is_writable(): bool { // – the shipped provider ------------------------------------------------- /** + * Ensure that WP_Secrets_Libsodium_Provider is used when no drop-in supplies a provider. + * * @covers ::_wp_secrets_get_provider */ public function test_the_default_provider_is_the_libsodium_one(): void { @@ -104,6 +106,8 @@ public function test_the_default_provider_is_the_libsodium_one(): void { } /** + * Ensure that the default provider declares BOUNDARY_WORDPRESS as its protection boundary. + * * @covers WP_Secrets_Libsodium_Provider::get_protection_boundary */ public function test_the_default_provider_protects_inside_wordpress(): void { @@ -114,6 +118,8 @@ public function test_the_default_provider_protects_inside_wordpress(): void { } /** + * Ensure that wp_secrets_provider_is_writable() reports the default provider as writable. + * * @covers ::wp_secrets_provider_is_writable */ public function test_the_default_provider_accepts_writes(): void { @@ -140,6 +146,11 @@ public function test_the_default_provider_label_names_the_key_source(): void { // – a platform provider, which is what the seam exists for ---------------- /** + * Ensure that a provider set in the wp_secrets_provider global is used in place of the default. + * + * Runs in a separate process because _wp_secrets_get_provider() caches the provider it + * resolves on first use, so the global has to be set before anything asks for one. + * * @covers ::_wp_secrets_get_provider * @covers ::wp_secrets_provider_label * @@ -216,6 +227,8 @@ public function test_a_broken_dropin_fails_closed_rather_than_reverting_to_the_d } /** + * Ensure that every secrets operation returns a WP_Error once the drop-in is marked broken. + * * @covers ::wp_set_secret * @covers ::wp_get_secret * @covers ::wp_delete_secret diff --git a/tests/phpunit/tests/secrets/siteHealth.php b/tests/phpunit/tests/secrets/siteHealth.php index 81103c3ae2f07..ae922c550614f 100644 --- a/tests/phpunit/tests/secrets/siteHealth.php +++ b/tests/phpunit/tests/secrets/siteHealth.php @@ -33,6 +33,8 @@ private function debug_fields( array $info ): array { } /** + * Ensure that the three Secrets API checks are registered as direct tests with existing callbacks. + * * @covers ::wp_secrets_site_health_tests */ public function test_registers_three_tests_under_direct(): void { @@ -50,6 +52,8 @@ public function test_registers_three_tests_under_direct(): void { } /** + * Ensure that wp_secrets_site_health_tests() keeps tests that were already registered. + * * @covers ::wp_secrets_site_health_tests */ public function test_preserves_existing_tests(): void { @@ -59,6 +63,8 @@ public function test_preserves_existing_tests(): void { } /** + * Ensure that the key source check recommends defining WP_SECRETS_KEY when it is not set. + * * @covers ::wp_secrets_site_health_test_key_source */ public function test_key_source_test_recommends_a_dedicated_key_by_default(): void { @@ -73,6 +79,11 @@ public function test_key_source_test_recommends_a_dedicated_key_by_default(): vo } /** + * Ensure that the key source check recommends regenerating a WP_SECRETS_KEY not in base64 form. + * + * Runs in a separate process because WP_SECRETS_KEY is a constant and cannot be + * undefined for later tests. + * * @covers ::wp_secrets_site_health_test_key_source * * @runInSeparateProcess @@ -88,6 +99,11 @@ public function test_key_source_test_recommends_regeneration_for_a_legacy_key(): } /** + * Ensure that the key source check passes for a base64-encoded 32-byte WP_SECRETS_KEY. + * + * Runs in a separate process because WP_SECRETS_KEY is a constant and cannot be + * undefined for later tests. + * * @covers ::wp_secrets_site_health_test_key_source * * @runInSeparateProcess @@ -102,6 +118,11 @@ public function test_key_source_test_is_good_for_a_dedicated_base64_key(): void } /** + * Ensure that the key source check is critical when the secrets drop-in failed to load. + * + * Runs in a separate process because the key manager is cached in a static variable + * the first time it is requested, so the broken flag must be set before then. + * * @covers ::wp_secrets_site_health_test_key_source * * @runInSeparateProcess @@ -116,6 +137,8 @@ public function test_key_source_test_is_critical_when_the_keyring_is_broken(): v } /** + * Ensure that the undecryptable check passes when every stored secret decrypts. + * * @covers ::wp_secrets_site_health_test_undecryptable */ public function test_undecryptable_test_is_good_when_nothing_is_broken(): void { @@ -127,6 +150,8 @@ public function test_undecryptable_test_is_good_when_nothing_is_broken(): void { } /** + * Ensure that the undecryptable check passes when no secrets are stored. + * * @covers ::wp_secrets_site_health_test_undecryptable */ public function test_undecryptable_test_is_good_with_no_secrets_at_all(): void { @@ -136,6 +161,10 @@ public function test_undecryptable_test_is_good_with_no_secrets_at_all(): void { } /** + * Ensure that the undecryptable check is critical and names the failing secret and its fingerprint. + * + * The stored ciphertext is overwritten to simulate a record that no longer decrypts. + * * @covers ::wp_secrets_site_health_test_undecryptable */ public function test_undecryptable_test_is_critical_and_lists_the_broken_secret(): void { @@ -162,6 +191,8 @@ public function test_undecryptable_test_is_critical_and_lists_the_broken_secret( } /** + * Ensure that the undecryptable check's description never includes a secret's plaintext value. + * * @covers ::wp_secrets_site_health_test_undecryptable */ public function test_undecryptable_test_never_contains_a_plaintext(): void { @@ -182,6 +213,8 @@ public function test_undecryptable_test_never_contains_a_plaintext(): void { } /** + * Ensure that the rotation check passes for a secret stored directly with wp_set_secret(). + * * @covers ::wp_secrets_site_health_test_needs_rotation */ public function test_needs_rotation_test_is_good_by_default(): void { @@ -193,6 +226,8 @@ public function test_needs_rotation_test_is_good_by_default(): void { } /** + * Ensure that the rotation check recommends rotating a secret imported from a plain option. + * * @covers ::wp_secrets_site_health_test_needs_rotation */ public function test_needs_rotation_test_is_recommended_after_an_import(): void { @@ -206,6 +241,8 @@ public function test_needs_rotation_test_is_recommended_after_an_import(): void } /** + * Ensure that the debug information reports the provider, keyring, record version and secret count. + * * @covers ::wp_secrets_site_health_debug_info */ public function test_debug_info_reports_expected_fields(): void { @@ -230,6 +267,8 @@ public function test_debug_info_reports_expected_fields(): void { } /** + * Ensure that the debug information reports no active drop-in when none is installed. + * * @covers ::wp_secrets_site_health_debug_info */ public function test_debug_info_reports_no_dropin_by_default(): void { @@ -242,6 +281,8 @@ public function test_debug_info_reports_no_dropin_by_default(): void { } /** + * Ensure that the debug information never includes a secret's plaintext value. + * * @covers ::wp_secrets_site_health_debug_info */ public function test_debug_info_never_contains_a_plaintext(): void { @@ -256,6 +297,8 @@ public function test_debug_info_never_contains_a_plaintext(): void { } /** + * Ensure that the debug information omits network secret counts on a single site install. + * * @covers ::wp_secrets_site_health_debug_info */ public function test_debug_info_omits_network_fields_on_single_site(): void { diff --git a/tests/phpunit/tests/secrets/threeStateContract.php b/tests/phpunit/tests/secrets/threeStateContract.php index bb28c81204b5c..9e0b920464e7a 100644 --- a/tests/phpunit/tests/secrets/threeStateContract.php +++ b/tests/phpunit/tests/secrets/threeStateContract.php @@ -12,6 +12,8 @@ class Tests_Secrets_ThreeStateContract extends WP_UnitTestCase { /** + * Ensure that wp_get_secret() returns null for a secret that was never set. + * * @covers ::wp_get_secret */ public function test_absent_is_null(): void { @@ -21,6 +23,8 @@ public function test_absent_is_null(): void { } /** + * Ensure that wp_get_secret() returns null, not an error, for a missing previous version. + * * @covers ::wp_get_secret */ public function test_previous_slot_absent_on_an_existing_secret_is_also_null(): void { @@ -32,6 +36,8 @@ public function test_previous_slot_absent_on_an_existing_secret_is_also_null(): } /** + * Ensure that wp_get_secret() returns a WP_Error, not null, when the stored record is not an array. + * * @covers ::wp_get_secret */ public function test_malformed_record_is_wp_error_not_null(): void { @@ -45,6 +51,8 @@ public function test_malformed_record_is_wp_error_not_null(): void { } /** + * Ensure that wp_get_secret() returns a WP_Error, not null, for a record with no current slot. + * * @covers ::wp_get_secret */ public function test_record_missing_the_current_slot_is_wp_error_not_null(): void { @@ -58,6 +66,8 @@ public function test_record_missing_the_current_slot_is_wp_error_not_null(): voi } /** + * Ensure that wp_get_secret() returns a WP_Error, not null, for a record of an unknown format version. + * * @covers ::wp_get_secret */ public function test_unsupported_record_version_is_wp_error_not_null(): void { @@ -220,6 +230,8 @@ public function test_fingerprint_is_recomputed_not_read_from_the_record(): void } /** + * Ensure that wp_get_secret() returns a WP_Secret for a secret that exists and decrypts. + * * @covers ::wp_get_secret */ public function test_exists_and_decrypts_is_a_wp_secret(): void { diff --git a/tests/phpunit/tests/secrets/versionSlots.php b/tests/phpunit/tests/secrets/versionSlots.php index 02022d77b027a..869ea81ec8584 100644 --- a/tests/phpunit/tests/secrets/versionSlots.php +++ b/tests/phpunit/tests/secrets/versionSlots.php @@ -31,6 +31,8 @@ private function stored_slot( string $slot ): array { } /** + * Ensure that the first write of a secret leaves no previous version to retrieve. + * * @covers ::wp_set_secret * @covers ::wp_get_secret */ @@ -55,6 +57,8 @@ public function test_previous_returns_the_actual_prior_value(): void { } /** + * Ensure that a third write discards the oldest value from the stored record. + * * @covers ::wp_set_secret * @covers WP_Secrets_Libsodium_Provider::set */ @@ -89,6 +93,8 @@ public function test_rewriting_the_current_value_keeps_the_previous_slot(): void } /** + * Ensure that writing the value a secret already holds succeeds without changing the stored record. + * * @ticket 66353 * * @covers ::wp_set_secret @@ -105,6 +111,8 @@ public function test_rewriting_the_current_value_leaves_the_stored_record_untouc } /** + * Ensure that writing the value a secret already holds does not fire wp_secret_changed. + * * @ticket 66353 * * @covers ::wp_set_secret @@ -165,6 +173,8 @@ public function test_importing_the_current_value_flags_it_and_keeps_the_previous } /** + * Ensure that a demoted value keeps the fingerprint it had as the current version. + * * @covers ::wp_set_secret * @covers ::wp_get_secret */ @@ -182,6 +192,8 @@ public function test_previous_preserves_its_original_fingerprint(): void { } /** + * Ensure that a demoted value keeps the created timestamp from its original write. + * * @covers ::wp_set_secret * @covers WP_Secrets_Libsodium_Provider::set */ @@ -197,6 +209,8 @@ public function test_previous_preserves_its_original_created_timestamp(): void { } /** + * Ensure that a demoted value carries its needs-rotation flag into the previous slot. + * * @covers ::wp_set_secret * @covers WP_Secrets_Libsodium_Provider::set */ @@ -243,6 +257,8 @@ public function test_demotion_actually_reencrypts_rather_than_copying_ciphertext } /** + * Ensure that wp_get_secret() returns null for the previous version of a secret written once. + * * @covers ::wp_get_secret */ public function test_previous_on_a_secret_with_no_previous_slot_is_null(): void { @@ -279,6 +295,8 @@ public function test_a_write_succeeds_even_if_the_outgoing_current_slot_cannot_b } /** + * Ensure that wp_retire_secret_version() removes the previous version and keeps the current one. + * * @covers ::wp_retire_secret_version */ public function test_retire_clears_previous_and_leaves_current_intact(): void { @@ -294,6 +312,8 @@ public function test_retire_clears_previous_and_leaves_current_intact(): void { } /** + * Ensure that wp_retire_secret_version() returns true for a secret with no previous version. + * * @covers ::wp_retire_secret_version */ public function test_retire_on_a_secret_with_no_previous_slot_is_a_successful_noop(): void { @@ -303,6 +323,8 @@ public function test_retire_on_a_secret_with_no_previous_slot_is_a_successful_no } /** + * Ensure that wp_retire_secret_version() returns true for a secret that was never set. + * * @covers ::wp_retire_secret_version */ public function test_retire_on_a_never_set_secret_is_a_successful_noop(): void { @@ -310,6 +332,8 @@ public function test_retire_on_a_never_set_secret_is_a_successful_noop(): void { } /** + * Ensure that wp_retire_secret_version() rejects an invalid secret name. + * * @covers ::wp_retire_secret_version */ public function test_retire_rejects_an_invalid_name(): void { @@ -320,6 +344,8 @@ public function test_retire_rejects_an_invalid_name(): void { } /** + * Ensure that wp_retire_secret_version() fires wp_secret_changed as retired, with the old fingerprint. + * * @covers ::wp_retire_secret_version */ public function test_retire_fires_the_change_hook_with_the_retired_action(): void { @@ -353,6 +379,8 @@ function ( ...$args ) use ( &$captured ) { } /** + * Ensure that wp_retire_secret_version() does not fire wp_secret_changed when nothing is retired. + * * @covers ::wp_retire_secret_version */ public function test_retire_does_not_fire_the_change_hook_on_a_noop(): void { diff --git a/tests/phpunit/tests/secrets/wpDeleteSecret.php b/tests/phpunit/tests/secrets/wpDeleteSecret.php index d652b422c9778..b5a56fe41eea2 100644 --- a/tests/phpunit/tests/secrets/wpDeleteSecret.php +++ b/tests/phpunit/tests/secrets/wpDeleteSecret.php @@ -9,6 +9,8 @@ class Tests_Secrets_WpDeleteSecret extends WP_UnitTestCase { /** + * Ensure that wp_delete_secret() removes a stored secret so it can no longer be retrieved. + * * @covers ::wp_delete_secret */ public function test_deletes_an_existing_secret(): void { @@ -19,6 +21,8 @@ public function test_deletes_an_existing_secret(): void { } /** + * Ensure that wp_delete_secret() returns true for a secret that was never stored. + * * @covers ::wp_delete_secret */ public function test_deleting_an_absent_secret_is_not_an_error(): void { @@ -26,6 +30,8 @@ public function test_deleting_an_absent_secret_is_not_an_error(): void { } /** + * Ensure that wp_delete_secret() returns an invalid name error for a malformed name. + * * @covers ::wp_delete_secret */ public function test_rejects_an_invalid_name(): void { @@ -36,6 +42,8 @@ public function test_rejects_an_invalid_name(): void { } /** + * Ensure that deleting a secret fires wp_secret_changed with the deleted action and old fingerprint. + * * @covers ::wp_delete_secret */ public function test_change_hook_fires_with_deleted_action(): void { @@ -69,6 +77,8 @@ function ( ...$args ) use ( &$captured ) { } /** + * Ensure that wp_secret_changed does not fire when deleting a secret that does not exist. + * * @covers ::wp_delete_secret */ public function test_change_hook_does_not_fire_when_nothing_was_deleted(): void { @@ -100,6 +110,11 @@ public function test_a_corrupt_record_is_still_deletable(): void { } /** + * Ensure that wp_delete_secret() succeeds without a logged-in user. + * + * Capability checks belong at the operator boundary (CLI, admin screens), not in the + * API itself, so plugins can manage their own secrets from any context. + * * @covers ::wp_delete_secret */ public function test_no_capability_check_is_applied(): void { diff --git a/tests/phpunit/tests/secrets/wpImportOptionAsSecret.php b/tests/phpunit/tests/secrets/wpImportOptionAsSecret.php index 9e992cadbe16d..067d095e211e7 100644 --- a/tests/phpunit/tests/secrets/wpImportOptionAsSecret.php +++ b/tests/phpunit/tests/secrets/wpImportOptionAsSecret.php @@ -9,6 +9,8 @@ class Tests_Secrets_WpImportOptionAsSecret extends WP_UnitTestCase { /** + * Ensure that wp_import_option_as_secret() stores the option's value as a secret. + * * @covers ::wp_import_option_as_secret */ public function test_imports_an_existing_option_value(): void { @@ -23,6 +25,8 @@ public function test_imports_an_existing_option_value(): void { } /** + * Ensure that wp_import_option_as_secret() does not modify or delete the source option. + * * @covers ::wp_import_option_as_secret */ public function test_leaves_the_source_option_untouched(): void { @@ -34,6 +38,8 @@ public function test_leaves_the_source_option_untouched(): void { } /** + * Ensure that a secret imported from an option is flagged as needing rotation. + * * @covers ::wp_import_option_as_secret * @covers WP_Secrets_Libsodium_Provider::set */ @@ -50,6 +56,11 @@ public function test_flags_the_imported_secret_for_rotation(): void { } /** + * Ensure that a secret written by wp_set_secret() is not flagged as needing rotation. + * + * The counterpart to the import test above: it proves the flag comes from the import, + * not from a default applied to every write. + * * @covers ::wp_set_secret * @covers WP_Secrets_Libsodium_Provider::set */ @@ -65,6 +76,8 @@ public function test_an_ordinary_write_does_not_flag_needs_rotation(): void { } /** + * Ensure that wp_import_option_as_secret() rejects an option that does not exist. + * * @covers ::wp_import_option_as_secret */ public function test_rejects_a_nonexistent_option(): void { @@ -75,6 +88,8 @@ public function test_rejects_a_nonexistent_option(): void { } /** + * Ensure that wp_import_option_as_secret() rejects an option whose value is not a string. + * * @covers ::wp_import_option_as_secret */ public function test_rejects_a_non_string_option_value(): void { @@ -87,6 +102,8 @@ public function test_rejects_a_non_string_option_value(): void { } /** + * Ensure that wp_import_option_as_secret() rejects an invalid destination secret name. + * * @covers ::wp_import_option_as_secret */ public function test_rejects_an_invalid_destination_name(): void { @@ -99,6 +116,8 @@ public function test_rejects_an_invalid_destination_name(): void { } /** + * Ensure that importing an option fires wp_secret_changed with the imported action. + * * @covers ::wp_import_option_as_secret */ public function test_fires_the_change_hook_with_the_imported_action(): void { diff --git a/tests/phpunit/tests/secrets/wpListSecrets.php b/tests/phpunit/tests/secrets/wpListSecrets.php index b32fa89be85a8..f8b3ed13471dc 100644 --- a/tests/phpunit/tests/secrets/wpListSecrets.php +++ b/tests/phpunit/tests/secrets/wpListSecrets.php @@ -9,6 +9,8 @@ class Tests_Secrets_WpListSecrets extends WP_UnitTestCase { /** + * Ensure that wp_list_secrets() returns an empty array when no secrets are stored. + * * @covers ::wp_list_secrets */ public function test_returns_an_empty_array_when_nothing_is_set(): void { @@ -16,6 +18,8 @@ public function test_returns_an_empty_array_when_nothing_is_set(): void { } /** + * Ensure that each wp_list_secrets() entry has exactly the documented metadata keys, in order. + * * @covers ::wp_list_secrets */ public function test_lists_every_secret_with_the_expected_keys(): void { @@ -48,6 +52,8 @@ public function test_never_returns_a_value(): void { } /** + * Ensure that a listed fingerprint matches WP_Secret::fingerprint() for the same secret. + * * @covers ::wp_list_secrets */ public function test_fingerprint_matches_the_secrets_own_fingerprint(): void { @@ -62,6 +68,8 @@ public function test_fingerprint_matches_the_secrets_own_fingerprint(): void { } /** + * Ensure that has_previous is false for a new secret and true once it has been overwritten. + * * @covers ::wp_list_secrets */ public function test_has_previous_is_false_before_a_rotation_and_true_after(): void { @@ -81,6 +89,11 @@ public function test_has_previous_is_false_before_a_rotation_and_true_after(): v } /** + * Ensure that the needs_rotation entry reflects the flag stored on the current version. + * + * The stored record is edited directly to set the flag, so the test exercises + * wp_list_secrets() without depending on wp_import_option_as_secret(). + * * @covers ::wp_list_secrets */ public function test_needs_rotation_reflects_the_current_slots_flag(): void { @@ -102,6 +115,8 @@ public function test_needs_rotation_reflects_the_current_slots_flag(): void { } /** + * Ensure that wp_list_secrets() returns only the secrets in the requested namespace. + * * @covers ::wp_list_secrets */ public function test_filters_by_namespace(): void { @@ -115,6 +130,8 @@ public function test_filters_by_namespace(): void { } /** + * Ensure that wp_list_secrets() with an empty namespace returns secrets from every namespace. + * * @covers ::wp_list_secrets */ public function test_empty_namespace_returns_everything(): void { @@ -128,6 +145,8 @@ public function test_empty_namespace_returns_everything(): void { } /** + * Ensure that a namespace filter matches whole namespaces, not partial prefixes of them. + * * @covers ::wp_list_secrets */ public function test_namespace_does_not_match_a_prefix_of_a_different_namespace(): void { @@ -156,6 +175,8 @@ public function test_a_corrupt_record_is_still_listed_with_blank_metadata(): voi } /** + * Ensure that wp_list_secrets() excludes network secrets. + * * @covers ::wp_list_secrets */ public function test_does_not_list_network_scope_secrets(): void { diff --git a/tests/phpunit/tests/secrets/wpSecret.php b/tests/phpunit/tests/secrets/wpSecret.php index f8846aaa6a97d..3fd59c077479d 100644 --- a/tests/phpunit/tests/secrets/wpSecret.php +++ b/tests/phpunit/tests/secrets/wpSecret.php @@ -28,6 +28,11 @@ private function make_secret() { } /** + * Ensure that WP_Secret cannot be extended. + * + * A subclass could declare a property or magic method that exposes the plaintext, + * bypassing the masking guarantees this class makes. + * * @coversNothing */ public function test_class_is_final(): void { @@ -37,6 +42,8 @@ public function test_class_is_final(): void { } /** + * Ensure that WP_Secret implements JsonSerializable so json_encode() goes through the mask. + * * @coversNothing */ public function test_implements_json_serializable(): void { @@ -44,6 +51,8 @@ public function test_implements_json_serializable(): void { } /** + * Ensure that WP_Secret::reveal() returns the plaintext the secret was constructed with. + * * @covers WP_Secret::reveal */ public function test_reveal_returns_the_exact_plaintext(): void { @@ -53,6 +62,8 @@ public function test_reveal_returns_the_exact_plaintext(): void { } /** + * Ensure that WP_Secret::fingerprint() returns the fingerprint the secret was constructed with. + * * @covers WP_Secret::fingerprint */ public function test_fingerprint_returns_the_exact_fingerprint(): void { @@ -62,6 +73,8 @@ public function test_fingerprint_returns_the_exact_fingerprint(): void { } /** + * Ensure that WP_Secret::get_name() returns the name the secret was constructed with. + * * @covers WP_Secret::get_name */ public function test_get_name_returns_the_exact_name(): void { @@ -71,6 +84,8 @@ public function test_get_name_returns_the_exact_name(): void { } /** + * Ensure that constructing a WP_Secret with a non-string value throws InvalidArgumentException. + * * @covers WP_Secret::__construct */ public function test_constructor_rejects_a_non_string_value(): void { @@ -80,6 +95,8 @@ public function test_constructor_rejects_a_non_string_value(): void { } /** + * Ensure that constructing a WP_Secret with an empty name throws InvalidArgumentException. + * * @covers WP_Secret::__construct */ public function test_constructor_rejects_an_empty_name(): void { @@ -89,6 +106,8 @@ public function test_constructor_rejects_an_empty_name(): void { } /** + * Ensure that constructing a WP_Secret with an empty fingerprint throws InvalidArgumentException. + * * @covers WP_Secret::__construct */ public function test_constructor_rejects_an_empty_fingerprint(): void { @@ -169,6 +188,8 @@ function ( WP_Secret $secret ) { } /** + * Ensure that casting a WP_Secret to string yields the [secret:{name}] placeholder. + * * @covers WP_Secret::__toString */ public function test_to_string_yields_the_masked_placeholder(): void { @@ -178,6 +199,8 @@ public function test_to_string_yields_the_masked_placeholder(): void { } /** + * Ensure that json_encode() renders a WP_Secret as the [secret:{name}] placeholder. + * * @covers WP_Secret::jsonSerialize */ public function test_json_encode_yields_the_masked_placeholder(): void { @@ -191,6 +214,8 @@ public function test_json_encode_yields_the_masked_placeholder(): void { } /** + * Ensure that var_dump() of a WP_Secret shows the [secret:{name}] placeholder. + * * @covers WP_Secret::__debugInfo */ public function test_var_dump_yields_the_masked_placeholder(): void { @@ -204,6 +229,8 @@ public function test_var_dump_yields_the_masked_placeholder(): void { } /** + * Ensure that serializing a WP_Secret throws LogicException. + * * @covers WP_Secret::__serialize */ public function test_serialize_throws(): void { @@ -215,6 +242,8 @@ public function test_serialize_throws(): void { } /** + * Ensure that cloning a WP_Secret throws LogicException. + * * @covers WP_Secret::__clone */ public function test_clone_throws(): void { @@ -265,6 +294,8 @@ public static function data_refusing_magic_methods() { } /** + * Ensure that a secret's plaintext is removed from the vault once its last reference is released. + * * @covers WP_Secret::__construct * @covers WP_Secret::__destruct */ @@ -338,6 +369,8 @@ public function test_nothing_plaintext_survives_a_refused_cache_write(): void { } /** + * Ensure that each WP_Secret holds its own plaintext and destroying one leaves the other intact. + * * @covers WP_Secret::__construct * @covers WP_Secret::reveal * @covers WP_Secret::__destruct @@ -376,6 +409,8 @@ public function test_withheld_reveal_returns_the_providers_reason(): void { } /** + * Ensure that a withheld secret still reports its name and fingerprint. + * * @covers WP_Secret::withheld * @covers WP_Secret::get_name * @covers WP_Secret::fingerprint diff --git a/tests/phpunit/tests/secrets/wpSecretVersion.php b/tests/phpunit/tests/secrets/wpSecretVersion.php index 16b825d35d499..67832c63a5f34 100644 --- a/tests/phpunit/tests/secrets/wpSecretVersion.php +++ b/tests/phpunit/tests/secrets/wpSecretVersion.php @@ -7,6 +7,8 @@ class Tests_Secrets_WPSecretVersion extends WP_UnitTestCase { /** + * Ensure that WP_Secret_Version::CURRENT and WP_Secret_Version::PREVIOUS are distinct strings. + * * @coversNothing */ public function test_current_and_previous_are_distinct_strings(): void { @@ -16,6 +18,8 @@ public function test_current_and_previous_are_distinct_strings(): void { } /** + * Ensure that WP_Secret_Version cannot be extended. + * * @coversNothing */ public function test_class_is_final(): void { @@ -25,6 +29,8 @@ public function test_class_is_final(): void { } /** + * Ensure that WP_Secret_Version is a pure constants holder with no constructor. + * * @coversNothing */ public function test_class_declares_no_constructor(): void { @@ -34,6 +40,11 @@ public function test_class_declares_no_constructor(): void { } /** + * Ensure that WP_Secret_Version defines only the current and previous slots. + * + * Records hold exactly two slots and the cipher accepts only these two values, so a + * new constant would need matching support elsewhere before it could be used. + * * @coversNothing */ public function test_class_declares_exactly_two_constants(): void { diff --git a/tests/phpunit/tests/secrets/wpSecretsCipher.php b/tests/phpunit/tests/secrets/wpSecretsCipher.php index 7894b01354267..400c1cd995eac 100644 --- a/tests/phpunit/tests/secrets/wpSecretsCipher.php +++ b/tests/phpunit/tests/secrets/wpSecretsCipher.php @@ -38,6 +38,8 @@ private function master_key( $byte = 0x11 ) { } /** + * Ensure that a value encrypted by WP_Secrets_Cipher::encrypt_value() decrypts back unchanged. + * * @covers WP_Secrets_Cipher::encrypt_value * @covers WP_Secrets_Cipher::decrypt_value */ @@ -53,6 +55,8 @@ public function test_round_trips_a_value(): void { } /** + * Ensure that an empty string encrypts and decrypts back to an empty string. + * * @covers WP_Secrets_Cipher::encrypt_value * @covers WP_Secrets_Cipher::decrypt_value */ @@ -66,6 +70,8 @@ public function test_round_trips_an_empty_string_value(): void { } /** + * Ensure that a value encrypted under network scope with site ID 0 decrypts back unchanged. + * * @covers WP_Secrets_Cipher::encrypt_value * @covers WP_Secrets_Cipher::decrypt_value */ @@ -79,6 +85,8 @@ public function test_round_trips_under_network_scope(): void { } /** + * Ensure that WP_Secrets_Cipher::encrypt_value() refuses to encrypt a non-string plaintext. + * * @covers WP_Secrets_Cipher::encrypt_value */ public function test_encrypt_rejects_a_non_string_value(): void { @@ -91,6 +99,8 @@ public function test_encrypt_rejects_a_non_string_value(): void { } /** + * Ensure that WP_Secrets_Cipher::encrypt_value() refuses a master key that is not 32 bytes. + * * @covers WP_Secrets_Cipher::encrypt_value * * @dataProvider data_bad_master_keys @@ -118,6 +128,8 @@ public static function data_bad_master_keys() { } /** + * Ensure that WP_Secrets_Cipher::encrypt_value() returns the name validation error for a bad name. + * * @covers WP_Secrets_Cipher::encrypt_value */ public function test_encrypt_propagates_an_invalid_name(): void { @@ -130,6 +142,12 @@ public function test_encrypt_propagates_an_invalid_name(): void { } /** + * Ensure that an unknown scope triggers a _doing_it_wrong() notice and returns a WP_Error. + * + * Scope, site ID and slot are only ever supplied by core itself, so a bad value is a + * programming error: it is flagged to the developer but still reported as a WP_Error + * rather than thrown. + * * @covers WP_Secrets_Cipher::encrypt_value */ public function test_encrypt_reports_an_invalid_scope_as_a_wp_error(): void { @@ -144,6 +162,8 @@ public function test_encrypt_reports_an_invalid_scope_as_a_wp_error(): void { } /** + * Ensure that a negative site ID triggers a _doing_it_wrong() notice and returns a WP_Error. + * * @covers WP_Secrets_Cipher::encrypt_value */ public function test_encrypt_reports_a_negative_site_id_as_a_wp_error(): void { @@ -158,6 +178,8 @@ public function test_encrypt_reports_a_negative_site_id_as_a_wp_error(): void { } /** + * Ensure that a slot other than a WP_Secret_Version constant is reported as a caller error. + * * @covers WP_Secrets_Cipher::encrypt_value */ public function test_encrypt_reports_an_invalid_slot_as_a_wp_error(): void { @@ -210,6 +232,8 @@ public static function data_mismatched_context() { } /** + * Ensure that a record cannot be decrypted with a master key other than the one that encrypted it. + * * @covers WP_Secrets_Cipher::decrypt_value */ public function test_decrypt_fails_under_a_different_master_key(): void { @@ -223,6 +247,11 @@ public function test_decrypt_fails_under_a_different_master_key(): void { } /** + * Ensure that decryption fails when a single byte of any encrypted field is altered. + * + * Every field feeds an authenticated decryption, so corrupting one must be reported + * as an error rather than yielding different plaintext. + * * @covers WP_Secrets_Cipher::decrypt_value * * @dataProvider data_tamperable_fields @@ -262,6 +291,8 @@ public static function data_tamperable_fields() { } /** + * Ensure that a record with a missing, non-base64 or wrongly sized field is reported as malformed. + * * @covers WP_Secrets_Cipher::decrypt_value * * @dataProvider data_malformed_records @@ -310,6 +341,11 @@ public static function data_malformed_records() { } /** + * Ensure that encrypting the same value twice produces a different data key and ciphertext. + * + * Each write must generate a fresh data key, so identical plaintexts are never + * recognizable from their stored records. + * * @covers WP_Secrets_Cipher::encrypt_value */ public function test_data_key_independence(): void { @@ -326,6 +362,8 @@ public function test_data_key_independence(): void { } /** + * Ensure that no value or data key nonce is reused across repeated encryptions. + * * @covers WP_Secrets_Cipher::encrypt_value */ public function test_nonce_uniqueness_across_many_writes(): void { @@ -345,6 +383,8 @@ public function test_nonce_uniqueness_across_many_writes(): void { } /** + * Ensure that the same master key and plaintext always produce the same fingerprint. + * * @covers WP_Secrets_Cipher::fingerprint */ public function test_fingerprint_is_stable_for_the_same_inputs(): void { @@ -357,6 +397,10 @@ public function test_fingerprint_is_stable_for_the_same_inputs(): void { } /** + * Ensure that the same plaintext fingerprints differently under a different master key. + * + * Keying the fingerprint stops it acting as a cross-site lookup oracle for a known value. + * * @covers WP_Secrets_Cipher::fingerprint */ public function test_fingerprint_differs_across_master_keys(): void { @@ -369,6 +413,8 @@ public function test_fingerprint_differs_across_master_keys(): void { } /** + * Ensure that different plaintexts produce different fingerprints under the same master key. + * * @covers WP_Secrets_Cipher::fingerprint */ public function test_fingerprint_differs_across_plaintexts(): void { @@ -381,6 +427,8 @@ public function test_fingerprint_differs_across_plaintexts(): void { } /** + * Ensure that WP_Secrets_Cipher::fingerprint() refuses a master key that is not 32 bytes. + * * @covers WP_Secrets_Cipher::fingerprint */ public function test_fingerprint_rejects_a_bad_master_key(): void { @@ -393,6 +441,8 @@ public function test_fingerprint_rejects_a_bad_master_key(): void { } /** + * Ensure that WP_Secrets_Cipher::fingerprint() refuses a non-string plaintext. + * * @covers WP_Secrets_Cipher::fingerprint */ public function test_fingerprint_rejects_a_non_string_value(): void { diff --git a/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php b/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php index 4e6b9a002e765..0ac1f107af28a 100644 --- a/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php +++ b/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php @@ -33,6 +33,8 @@ private function invoke_private( object $instance, string $method, array $args = } /** + * Ensure that WP_Secrets_Config_Key_Provider implements WP_Secrets_Keyring. + * * @coversNothing */ public function test_implements_the_keyring_interface(): void { @@ -40,6 +42,8 @@ public function test_implements_the_keyring_interface(): void { } /** + * Ensure that unwrapping a wrapped value returns the original key material. + * * @covers WP_Secrets_Config_Key_Provider::wrap * @covers WP_Secrets_Config_Key_Provider::unwrap */ @@ -55,6 +59,8 @@ public function test_wrap_then_unwrap_round_trips(): void { } /** + * Ensure that wrapping empty key material returns an invalid value error. + * * @covers WP_Secrets_Config_Key_Provider::wrap */ public function test_wrap_rejects_an_empty_string(): void { @@ -67,6 +73,8 @@ public function test_wrap_rejects_an_empty_string(): void { } /** + * Ensure that wrapping the same key material twice uses a fresh nonce each time. + * * @covers WP_Secrets_Config_Key_Provider::wrap */ public function test_two_wraps_of_the_same_material_produce_different_output(): void { @@ -77,6 +85,8 @@ public function test_two_wraps_of_the_same_material_produce_different_output(): } /** + * Ensure that unwrapping an empty string returns a key unavailable error. + * * @covers WP_Secrets_Config_Key_Provider::unwrap */ public function test_unwrap_rejects_an_empty_string(): void { @@ -89,6 +99,8 @@ public function test_unwrap_rejects_an_empty_string(): void { } /** + * Ensure that unwrapping a value that is not strict base64 returns a key unavailable error. + * * @covers WP_Secrets_Config_Key_Provider::unwrap */ public function test_unwrap_rejects_garbage_base64(): void { @@ -101,6 +113,8 @@ public function test_unwrap_rejects_garbage_base64(): void { } /** + * Ensure that unwrapping data no longer than a nonce returns a key unavailable error. + * * @covers WP_Secrets_Config_Key_Provider::unwrap */ public function test_unwrap_rejects_data_too_short_to_contain_a_nonce(): void { @@ -113,6 +127,8 @@ public function test_unwrap_rejects_data_too_short_to_contain_a_nonce(): void { } /** + * Ensure that unwrapping a ciphertext with a modified byte fails authentication. + * * @covers WP_Secrets_Config_Key_Provider::unwrap */ public function test_unwrap_rejects_a_tampered_ciphertext(): void { @@ -134,6 +150,8 @@ public function test_unwrap_rejects_a_tampered_ciphertext(): void { } /** + * Ensure that the key source names LOGGED_IN_KEY when WP_SECRETS_KEY is not defined. + * * @covers WP_Secrets_Config_Key_Provider::get_key_source */ public function test_get_key_source_reports_the_salt_fallback_when_wp_secrets_key_is_unset(): void { @@ -147,6 +165,8 @@ public function test_get_key_source_reports_the_salt_fallback_when_wp_secrets_ke } /** + * Ensure that only the canonical base64 encoding of exactly 32 bytes is recognized. + * * @covers WP_Secrets_Config_Key_Provider::is_canonical_base64_32 * * @dataProvider data_canonical_base64_32 @@ -176,6 +196,8 @@ public static function data_canonical_base64_32(): array { } /** + * Ensure that salt values are rejected when missing, empty, non-string or the sample placeholder. + * * @covers WP_Secrets_Config_Key_Provider::are_usable_salt_values * * @dataProvider data_usable_salt_values @@ -205,6 +227,8 @@ public static function data_usable_salt_values(): array { } /** + * Ensure that a canonical base64 WP_SECRETS_KEY is used as the decoded raw bytes. + * * @covers WP_Secrets_Config_Key_Provider::get_site_key * * @runInSeparateProcess @@ -267,6 +291,8 @@ public function test_wrong_length_base64_falls_through_to_legacy_interpretation( } /** + * Ensure that a non-string WP_SECRETS_KEY fails closed with a key unavailable error. + * * @covers WP_Secrets_Config_Key_Provider::get_site_key * * @runInSeparateProcess @@ -283,6 +309,8 @@ public function test_non_string_wp_secrets_key_is_unavailable(): void { } /** + * Ensure that the key source identifies a canonical base64 WP_SECRETS_KEY. + * * @covers WP_Secrets_Config_Key_Provider::get_key_source * * @runInSeparateProcess @@ -297,6 +325,8 @@ public function test_get_key_source_reports_base64_form(): void { } /** + * Ensure that the key source identifies a WP_SECRETS_KEY using the legacy interpretation. + * * @covers WP_Secrets_Config_Key_Provider::get_key_source * * @runInSeparateProcess @@ -311,6 +341,8 @@ public function test_get_key_source_reports_legacy_form(): void { } /** + * Ensure that a previous-key provider derives its site key from WP_SECRETS_KEY_PREVIOUS. + * * @covers WP_Secrets_Config_Key_Provider::__construct * @covers WP_Secrets_Config_Key_Provider::get_site_key * @@ -349,6 +381,11 @@ public function test_previous_key_constant_does_not_leak_into_the_current_key_pa } /** + * Ensure that a previous-key provider fails when WP_SECRETS_KEY_PREVIOUS is not defined. + * + * The previous-key provider must fail closed rather than fall back to the salts, or + * a rotation could unwrap under a key the site never configured as the old one. + * * @covers WP_Secrets_Config_Key_Provider::get_site_key * * @runInSeparateProcess diff --git a/tests/phpunit/tests/secrets/wpSecretsKeyManager.php b/tests/phpunit/tests/secrets/wpSecretsKeyManager.php index 5214ec26df238..cacff47d0c17d 100644 --- a/tests/phpunit/tests/secrets/wpSecretsKeyManager.php +++ b/tests/phpunit/tests/secrets/wpSecretsKeyManager.php @@ -9,6 +9,8 @@ class Tests_Secrets_WPSecretsKeyManager extends WP_UnitTestCase { /** + * Ensure that the first call to get a root key generates 32 bytes and stores the wrapped value. + * * @covers WP_Secrets_Key_Manager::get_root_key */ public function test_get_root_key_generates_and_persists_one(): void { @@ -24,6 +26,8 @@ public function test_get_root_key_generates_and_persists_one(): void { } /** + * Ensure that repeated root key reads on one key manager return the same bytes. + * * @covers WP_Secrets_Key_Manager::get_root_key */ public function test_get_root_key_is_stable_on_the_same_instance(): void { @@ -33,6 +37,8 @@ public function test_get_root_key_is_stable_on_the_same_instance(): void { } /** + * Ensure that a new key manager reads the stored root key rather than generating another. + * * @covers WP_Secrets_Key_Manager::get_root_key */ public function test_get_root_key_persists_across_instances(): void { @@ -46,6 +52,8 @@ public function test_get_root_key_persists_across_instances(): void { } /** + * Ensure that a pre-existing wrapped root key is unwrapped and returned as is. + * * @covers WP_Secrets_Key_Manager::get_root_key */ public function test_get_root_key_uses_an_existing_value_rather_than_regenerating(): void { @@ -60,6 +68,8 @@ public function test_get_root_key_uses_an_existing_value_rather_than_regeneratin } /** + * Ensure that the site master key is the KDF subkey of the root key for the current blog. + * * @covers WP_Secrets_Key_Manager::get_master_key */ public function test_get_master_key_matches_manual_derivation(): void { @@ -73,6 +83,8 @@ public function test_get_master_key_matches_manual_derivation(): void { } /** + * Ensure that site-scope master keys differ between site IDs. + * * @covers WP_Secrets_Key_Manager::get_master_key */ public function test_get_master_key_differs_per_site_id(): void { @@ -85,6 +97,8 @@ public function test_get_master_key_differs_per_site_id(): void { } /** + * Ensure that the network master key differs from the master key for site ID 1. + * * @covers WP_Secrets_Key_Manager::get_master_key */ public function test_get_master_key_site_and_network_scope_differ(): void { @@ -97,6 +111,8 @@ public function test_get_master_key_site_and_network_scope_differ(): void { } /** + * Ensure that the network master key is identical across repeated derivations. + * * @covers WP_Secrets_Key_Manager::get_master_key */ public function test_get_master_key_network_scope_is_stable(): void { @@ -109,6 +125,8 @@ public function test_get_master_key_network_scope_is_stable(): void { } /** + * Ensure that a site-scope master key without a site ID is derived for the current blog. + * * @covers WP_Secrets_Key_Manager::get_master_key */ public function test_get_master_key_defaults_site_id_to_the_current_blog(): void { @@ -121,6 +139,8 @@ public function test_get_master_key_defaults_site_id_to_the_current_blog(): void } /** + * Ensure that an unknown scope triggers _doing_it_wrong() and returns an invalid argument error. + * * @covers WP_Secrets_Key_Manager::get_master_key */ public function test_get_master_key_reports_an_invalid_scope_as_a_wp_error(): void { @@ -135,6 +155,8 @@ public function test_get_master_key_reports_an_invalid_scope_as_a_wp_error(): vo } /** + * Ensure that a site ID below 1 triggers _doing_it_wrong() and returns an invalid argument error. + * * @covers WP_Secrets_Key_Manager::get_master_key * * @dataProvider data_invalid_site_ids @@ -306,6 +328,8 @@ public function test_rotate_site_key_works_after_conversion_before_any_read(): v } /** + * Ensure that rotating the site key before any root key exists returns a store error. + * * @covers WP_Secrets_Key_Manager::rotate_site_key */ public function test_rotate_fails_when_no_root_key_exists(): void { @@ -319,6 +343,8 @@ public function test_rotate_fails_when_no_root_key_exists(): void { } /** + * Ensure that rotation fails when the old keyring cannot unwrap the stored root key. + * * @covers WP_Secrets_Key_Manager::rotate_site_key */ public function test_rotate_fails_when_the_old_keyring_is_wrong(): void { @@ -397,6 +423,11 @@ public function test_rotation_does_not_change_any_derived_master_key(): void { } /** + * Ensure that deriving many master keys unwraps the root key only once per key manager. + * + * Guards the per-request root key cache, which keeps a remote keyring such as a KMS + * or HSM to a single call per request rather than one per derivation. + * * @covers WP_Secrets_Key_Manager::get_master_key * @covers WP_Secrets_Key_Manager::get_root_key */ @@ -421,6 +452,11 @@ public function test_unwrap_is_called_once_across_repeated_master_key_derivation } /** + * Ensure that repeated wp_get_secret() calls unwrap the root key only once. + * + * Runs in a separate process because _wp_secrets_get_key_manager() memoizes the key + * manager in a static, so the mock keyring global is only picked up on first use. + * * @covers WP_Secrets_Key_Manager::get_root_key * * @runInSeparateProcess @@ -445,6 +481,8 @@ public function test_unwrap_is_called_once_across_many_secret_reads(): void { } /** + * Ensure that rotation reuses the cached root key and leaves the cache valid afterward. + * * @covers WP_Secrets_Key_Manager::rotate_site_key * @covers WP_Secrets_Key_Manager::get_root_key */ @@ -465,6 +503,11 @@ public function test_rotate_site_key_updates_the_cache_without_another_unwrap(): } /** + * Ensure that the cached root key is discarded when the stored wrapped value changes. + * + * Overwrites the stored option directly to simulate another request restoring or + * re-wrapping the root key mid-request. + * * @covers WP_Secrets_Key_Manager::get_root_key */ public function test_a_changed_wrapped_value_is_unwrapped_again_rather_than_served_from_cache(): void { @@ -483,6 +526,8 @@ public function test_a_changed_wrapped_value_is_unwrapped_again_rather_than_serv } /** + * Ensure that a failed unwrap is retried on the next call and a later success is cached. + * * @covers WP_Secrets_Key_Manager::get_root_key */ public function test_an_unwrap_error_is_not_cached(): void { @@ -509,6 +554,8 @@ public function test_an_unwrap_error_is_not_cached(): void { } /** + * Ensure that a newly generated root key is cached so deriving a master key needs no unwrap. + * * @covers WP_Secrets_Key_Manager::get_root_key * @covers WP_Secrets_Key_Manager::generate_root_key */ @@ -524,6 +571,11 @@ public function test_generate_root_key_primes_the_cache(): void { } /** + * Ensure that zeroing the returned root key does not wipe the key manager's cached copy. + * + * Callers are required to zero the root key they receive, so the copy handed out must + * never share storage with the cache. + * * @covers WP_Secrets_Key_Manager::get_root_key */ public function test_the_returned_root_key_is_a_copy_the_caller_can_zero(): void { diff --git a/tests/phpunit/tests/secrets/wpSecretsMemzero.php b/tests/phpunit/tests/secrets/wpSecretsMemzero.php index 95b35b42b0d59..a40be78b547de 100644 --- a/tests/phpunit/tests/secrets/wpSecretsMemzero.php +++ b/tests/phpunit/tests/secrets/wpSecretsMemzero.php @@ -7,6 +7,8 @@ class Tests_Secrets_WpSecretsMemzero extends WP_UnitTestCase { /** + * Ensure that wp_secrets_memzero() replaces a string value with an empty string. + * * @covers ::wp_secrets_memzero */ public function test_clears_a_plaintext_string(): void { @@ -19,6 +21,8 @@ public function test_clears_a_plaintext_string(): void { } /** + * Ensure that wp_secrets_memzero() does not modify a non-string value. + * * @covers ::wp_secrets_memzero */ public function test_leaves_non_string_values_untouched(): void { @@ -30,6 +34,8 @@ public function test_leaves_non_string_values_untouched(): void { } /** + * Ensure that wp_secrets_memzero() leaves an empty string as an empty string. + * * @covers ::wp_secrets_memzero */ public function test_leaves_an_empty_string_untouched(): void { @@ -41,6 +47,8 @@ public function test_leaves_an_empty_string_untouched(): void { } /** + * Ensure that wp_secrets_memzero() clears a copy-on-write string without throwing. + * * @covers ::wp_secrets_memzero */ public function test_does_not_throw_when_the_value_is_shared(): void { diff --git a/tests/phpunit/tests/secrets/wpSecretsOptionStore.php b/tests/phpunit/tests/secrets/wpSecretsOptionStore.php index e83c283290d5f..cf7d1f15e63cf 100644 --- a/tests/phpunit/tests/secrets/wpSecretsOptionStore.php +++ b/tests/phpunit/tests/secrets/wpSecretsOptionStore.php @@ -28,6 +28,8 @@ private function sample_record(): array { } /** + * Ensure that WP_Secrets_Option_Store implements the WP_Secrets_Store interface. + * * @coversNothing */ public function test_implements_the_store_interface(): void { @@ -35,6 +37,8 @@ public function test_implements_the_store_interface(): void { } /** + * Ensure that WP_Secrets_Option_Store::get() returns null when no record is stored. + * * @covers WP_Secrets_Option_Store::get */ public function test_get_returns_null_for_an_absent_secret(): void { @@ -44,6 +48,8 @@ public function test_get_returns_null_for_an_absent_secret(): void { } /** + * Ensure that a site-scope record is returned unchanged after being stored. + * * @covers WP_Secrets_Option_Store::set * @covers WP_Secrets_Option_Store::get */ @@ -56,6 +62,8 @@ public function test_set_then_get_round_trips_a_record_site_scope(): void { } /** + * Ensure that a network-scope record is returned unchanged after being stored. + * * @covers WP_Secrets_Option_Store::set * @covers WP_Secrets_Option_Store::get */ @@ -68,6 +76,8 @@ public function test_set_then_get_round_trips_a_record_network_scope(): void { } /** + * Ensure that site and network records with the same name are stored independently. + * * @covers WP_Secrets_Option_Store::set * @covers WP_Secrets_Option_Store::get */ @@ -84,6 +94,8 @@ public function test_site_and_network_scope_do_not_collide(): void { } /** + * Ensure that WP_Secrets_Option_Store::get() returns a malformed record error for a non-array value. + * * @covers WP_Secrets_Option_Store::get */ public function test_get_returns_an_error_when_the_stored_value_is_not_an_array(): void { @@ -98,6 +110,8 @@ public function test_get_returns_an_error_when_the_stored_value_is_not_an_array( } /** + * Ensure that WP_Secrets_Option_Store::delete() removes a stored record. + * * @covers WP_Secrets_Option_Store::delete */ public function test_delete_removes_an_existing_record(): void { @@ -109,6 +123,8 @@ public function test_delete_removes_an_existing_record(): void { } /** + * Ensure that WP_Secrets_Option_Store::delete() returns true when no record is stored. + * * @covers WP_Secrets_Option_Store::delete */ public function test_delete_on_an_absent_record_is_not_an_error(): void { @@ -118,6 +134,11 @@ public function test_delete_on_an_absent_record_is_not_an_error(): void { } /** + * Ensure that site-scope secret records are stored with autoloading disabled. + * + * Autoloaded options are loaded into memory on every request, so keeping secrets + * out of the autoload set limits where their ciphertext travels. + * * @covers WP_Secrets_Option_Store::set * * @global wpdb $wpdb WordPress database abstraction object. @@ -139,6 +160,8 @@ public function test_site_scope_records_are_not_autoloaded(): void { } /** + * Ensure that WP_Secrets_Option_Store::list_names() returns names without the option prefix. + * * @covers WP_Secrets_Option_Store::list_names */ public function test_list_names_returns_stored_names_without_the_prefix(): void { @@ -154,6 +177,8 @@ public function test_list_names_returns_stored_names_without_the_prefix(): void } /** + * Ensure that WP_Secrets_Option_Store::list_names() excludes options that are not secret records. + * * @covers WP_Secrets_Option_Store::list_names */ public function test_list_names_does_not_include_unrelated_options(): void { @@ -169,6 +194,8 @@ public function test_list_names_does_not_include_unrelated_options(): void { } /** + * Ensure that WP_Secrets_Option_Store::list_names() returns only the names from the requested scope. + * * @covers WP_Secrets_Option_Store::list_names */ public function test_list_names_does_not_include_network_scope_names(): void { diff --git a/tests/phpunit/tests/secrets/wpSecretsValidateName.php b/tests/phpunit/tests/secrets/wpSecretsValidateName.php index 6b4b01c667b20..f008b10872b16 100644 --- a/tests/phpunit/tests/secrets/wpSecretsValidateName.php +++ b/tests/phpunit/tests/secrets/wpSecretsValidateName.php @@ -7,6 +7,8 @@ class Tests_Secrets_WpSecretsValidateName extends WP_UnitTestCase { /** + * Ensure that wp_secrets_validate_name() accepts well-formed namespaced names up to the max length. + * * @covers ::wp_secrets_validate_name * * @dataProvider data_valid_names @@ -34,6 +36,8 @@ public static function data_valid_names(): array { } /** + * Ensure that wp_secrets_validate_name() rejects malformed, overlong and wrongly cased names. + * * @covers ::wp_secrets_validate_name * * @dataProvider data_invalid_names diff --git a/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php b/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php index a7e90fa2554a9..3e88e7c7344d7 100644 --- a/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php +++ b/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php @@ -11,6 +11,8 @@ class Tests_Secrets_WpSetSecretAndWpGetSecret extends WP_UnitTestCase { use WP_Secrets_Assertions; /** + * Ensure that a stored secret is retrieved with its original value, name and a fingerprint. + * * @covers ::wp_set_secret * @covers ::wp_get_secret */ @@ -26,6 +28,8 @@ public function test_set_then_get_round_trips(): void { } /** + * Ensure that wp_get_secret() returns null for a secret that was never stored. + * * @covers ::wp_get_secret */ public function test_get_returns_null_for_an_absent_secret(): void { @@ -33,6 +37,8 @@ public function test_get_returns_null_for_an_absent_secret(): void { } /** + * Ensure that wp_get_secret() returns the current version when no version is requested. + * * @covers ::wp_get_secret */ public function test_get_defaults_to_the_current_version(): void { @@ -47,6 +53,8 @@ public function test_get_defaults_to_the_current_version(): void { } /** + * Ensure that requesting the previous version of a never-rotated secret returns null, not an error. + * * @covers ::wp_get_secret */ public function test_get_previous_on_a_never_rotated_secret_is_null_not_error(): void { @@ -73,6 +81,8 @@ public function test_an_invalid_version_is_a_wp_error_not_an_exception(): void { } /** + * Ensure that wp_set_secret() returns an invalid name error for a malformed name. + * * @covers ::wp_set_secret */ public function test_set_rejects_an_invalid_name(): void { @@ -83,6 +93,8 @@ public function test_set_rejects_an_invalid_name(): void { } /** + * Ensure that wp_get_secret() returns an invalid name error for a malformed name. + * * @covers ::wp_get_secret */ public function test_get_rejects_an_invalid_name(): void { @@ -93,6 +105,8 @@ public function test_get_rejects_an_invalid_name(): void { } /** + * Ensure that wp_set_secret() returns an invalid value error for a non-string value. + * * @covers ::wp_set_secret */ public function test_set_rejects_a_non_string_value(): void { @@ -103,6 +117,8 @@ public function test_set_rejects_a_non_string_value(): void { } /** + * Ensure that an empty string can be stored and retrieved as a secret value. + * * @covers ::wp_set_secret * @covers ::wp_get_secret */ @@ -173,6 +189,11 @@ public function test_reveal_still_works_after_the_internal_memzero(): void { } /** + * Ensure that wp_set_secret() and wp_get_secret() succeed without a logged-in user. + * + * Capability checks belong at the operator boundary (CLI, admin screens), not in the + * API itself, so plugins can use their own secrets from any context, such as cron. + * * @covers ::wp_set_secret * @covers ::wp_get_secret */ @@ -184,6 +205,8 @@ public function test_no_capability_check_is_applied(): void { } /** + * Ensure that storing a new secret fires wp_secret_changed with the created action. + * * @covers ::wp_set_secret */ public function test_change_hook_fires_on_create_with_created_action(): void { @@ -210,6 +233,8 @@ function ( ...$args ) use ( &$captured ) { } /** + * Ensure that overwriting a secret fires wp_secret_changed as updated, with a new fingerprint. + * * @covers ::wp_set_secret */ public function test_change_hook_fires_on_overwrite_with_updated_action(): void { @@ -240,6 +265,8 @@ function ( ...$args ) use ( &$captured ) { } /** + * Ensure that wp_secret_changed reports the current user's ID as the actor. + * * @covers ::wp_set_secret */ public function test_change_hook_reports_the_current_user_as_actor(): void { @@ -262,6 +289,11 @@ function ( $name, $action, $actor_id ) use ( &$captured_actor ) { } /** + * Ensure that wp_secret_changed never receives the secret's plaintext value. + * + * Any callback can listen to this hook, including logging and auditing plugins, so + * every argument passed to it must be safe to record. + * * @covers ::wp_set_secret */ public function test_change_hook_never_receives_a_value(): void { From 03f777c2b2eb7a70f1962111c102f394f58ae0c2 Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 10:01:13 +1100 Subject: [PATCH 04/28] Tests: Remove dupes, clarify test names, add missing documented item. --- .../class-wp-secrets-provider-conformance.php | 2 +- .../phpunit/tests/secrets/extensionPoints.php | 55 +++++++++---------- tests/phpunit/tests/secrets/networkScope.php | 2 +- tests/phpunit/tests/secrets/provider.php | 22 -------- tests/phpunit/tests/secrets/versionSlots.php | 23 -------- tests/phpunit/tests/secrets/wpSecret.php | 12 ---- .../tests/secrets/wpSecretsMemzero.php | 4 +- .../tests/secrets/wpSecretsOptionStore.php | 2 +- .../secrets/wpSetSecretAndWpGetSecret.php | 20 ------- 9 files changed, 32 insertions(+), 110 deletions(-) diff --git a/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php b/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php index ad0dbdaf4a3f3..72d55ede04d09 100644 --- a/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php +++ b/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php @@ -481,7 +481,7 @@ public function test_a_refused_write_reports_no_change(): void { * * @covers WP_Secrets_Provider::list_secrets */ - public function test_listing_returns_an_array_or_an_error_and_never_a_value(): void { + public function test_listing_never_contains_a_stored_value(): void { $provider = $this->provider(); $this->require_writable( $provider ); diff --git a/tests/phpunit/tests/secrets/extensionPoints.php b/tests/phpunit/tests/secrets/extensionPoints.php index 5d950bf21f960..8245381ba67f1 100644 --- a/tests/phpunit/tests/secrets/extensionPoints.php +++ b/tests/phpunit/tests/secrets/extensionPoints.php @@ -118,57 +118,56 @@ public function test_read_succeeds_while_write_fails(): void { } /** - * A store that refuses writes must still serve reads. This previously configured - * a capability flag that nothing consulted, so it passed regardless of behavior. - * It now makes set() actually fail, and checks both halves. + * Ensure that an unreachable plugin-supplied store fails reads and writes without a local fallback. * + * @covers ::_wp_secrets_get_store * @covers ::wp_set_secret * @covers ::wp_get_secret * * @runInSeparateProcess * @preserveGlobalState disabled */ - public function test_a_store_that_refuses_writes_still_serves_reads(): void { - // Isolated, so this test supplies the site key rather than relying on the test config's salts. - define( 'WP_SECRETS_KEY', base64_encode( str_repeat( 'k', 32 ) ) ); - + public function test_unreachable_store_fails_closed_with_no_local_fallback(): void { $store = new Mock_Store(); - $GLOBALS['wp_secrets_store'] = $store; - - wp_set_secret( 'myplugin/api-key', 'value' ); - $store->configure_fail( 'set', true ); + $GLOBALS['wp_secrets_store'] = $store->configure_fail( 'get', true )->configure_fail( 'set', true ); - $this->assertWPError( wp_set_secret( 'myplugin/api-key', 'another' ) ); + $set_result = wp_set_secret( 'myplugin/api-key', 'value' ); + $get_result = wp_get_secret( 'myplugin/api-key' ); - $secret = wp_get_secret( 'myplugin/api-key' ); + $this->assertWPError( $set_result ); + $this->assertWPError( $get_result ); - $this->assertInstanceOf( WP_Secret::class, $secret ); - $this->assertSame( 'value', $secret->reveal() ); + // Fails closed, not merely differently: nothing was written to the real + // default store either, which a silent fallback would have done. + $this->assertFalse( get_option( '_wp_secret_myplugin/api-key' ) ); } /** - * Ensure that an unreachable plugin-supplied store fails reads and writes without a local fallback. + * Ensure that wp_list_secrets() returns a WP_Error when the store cannot list its secrets. * - * @covers ::_wp_secrets_get_store - * @covers ::wp_set_secret - * @covers ::wp_get_secret + * An unreachable store must not be reported as an empty listing, which would read + * as "no secrets exist", and the error passed back must not carry a stored value. + * + * @covers ::wp_list_secrets * * @runInSeparateProcess * @preserveGlobalState disabled */ - public function test_unreachable_store_fails_closed_with_no_local_fallback(): void { + public function test_listing_fails_closed_when_the_store_cannot_list(): void { + // Isolated, so this test supplies the site key rather than relying on the test config's salts. + define( 'WP_SECRETS_KEY', base64_encode( str_repeat( 'k', 32 ) ) ); + $store = new Mock_Store(); - $GLOBALS['wp_secrets_store'] = $store->configure_fail( 'get', true )->configure_fail( 'set', true ); + $GLOBALS['wp_secrets_store'] = $store; - $set_result = wp_set_secret( 'myplugin/api-key', 'value' ); - $get_result = wp_get_secret( 'myplugin/api-key' ); + wp_set_secret( 'myplugin/api-key', 'UNIQUE-PLAINTEXT-CANARY-5c1e' ); + $store->configure_fail( 'list', true ); - $this->assertWPError( $set_result ); - $this->assertWPError( $get_result ); + $result = wp_list_secrets(); - // Fails closed, not merely differently: nothing was written to the real - // default store either, which a silent fallback would have done. - $this->assertFalse( get_option( '_wp_secret_myplugin/api-key' ) ); + $this->assertWPError( $result, 'A store that cannot list must be reported as an error, not an empty list.' ); + $this->assertSame( WP_SECRETS_ERROR_STORE_UNAVAILABLE, $result->get_error_code(), 'The store error should be passed through unchanged.' ); + $this->assertNeverContainsPlaintext( 'UNIQUE-PLAINTEXT-CANARY-5c1e', $result, 'A listing error must never carry a stored value.' ); } /** diff --git a/tests/phpunit/tests/secrets/networkScope.php b/tests/phpunit/tests/secrets/networkScope.php index 1c9e1a6a395ab..508a60abad0f1 100644 --- a/tests/phpunit/tests/secrets/networkScope.php +++ b/tests/phpunit/tests/secrets/networkScope.php @@ -87,7 +87,7 @@ public function test_delete_does_not_touch_the_site_scope_secret_of_the_same_nam * * @covers ::wp_set_network_secret */ - public function test_previous_version_and_demotion_work_the_same_as_site_scope(): void { + public function test_overwriting_a_network_secret_demotes_the_old_value(): void { wp_set_network_secret( 'myplugin/api-key', 'first-value' ); wp_set_network_secret( 'myplugin/api-key', 'second-value' ); diff --git a/tests/phpunit/tests/secrets/provider.php b/tests/phpunit/tests/secrets/provider.php index d278e85b19fd9..83aa5b89dc177 100644 --- a/tests/phpunit/tests/secrets/provider.php +++ b/tests/phpunit/tests/secrets/provider.php @@ -226,28 +226,6 @@ public function test_a_broken_dropin_fails_closed_rather_than_reverting_to_the_d $this->assertFalse( $provider->is_writable() ); } - /** - * Ensure that every secrets operation returns a WP_Error once the drop-in is marked broken. - * - * @covers ::wp_set_secret - * @covers ::wp_get_secret - * @covers ::wp_delete_secret - * @covers ::wp_list_secrets - * @covers ::wp_retire_secret_version - * - * @runInSeparateProcess - * @preserveGlobalState disabled - */ - public function test_a_broken_dropin_makes_every_operation_a_wp_error(): void { - $GLOBALS['wp_secrets_dropin_broken'] = true; - - $this->assertWPError( wp_set_secret( 'myplugin/api-key', 'value' ) ); - $this->assertWPError( wp_get_secret( 'myplugin/api-key' ) ); - $this->assertWPError( wp_delete_secret( 'myplugin/api-key' ) ); - $this->assertWPError( wp_list_secrets() ); - $this->assertWPError( wp_retire_secret_version( 'myplugin/api-key' ) ); - } - /** * Specifically not null: a misconfigured credential backend must never look * like a working site that happens to have no secrets in it yet. diff --git a/tests/phpunit/tests/secrets/versionSlots.php b/tests/phpunit/tests/secrets/versionSlots.php index 869ea81ec8584..2404ec07c1d89 100644 --- a/tests/phpunit/tests/secrets/versionSlots.php +++ b/tests/phpunit/tests/secrets/versionSlots.php @@ -30,18 +30,6 @@ private function stored_slot( string $slot ): array { return $record[ $slot ]; } - /** - * Ensure that the first write of a secret leaves no previous version to retrieve. - * - * @covers ::wp_set_secret - * @covers ::wp_get_secret - */ - public function test_first_write_leaves_no_previous_slot(): void { - wp_set_secret( 'myplugin/api-key', 'first-value' ); - - $this->assertNull( wp_get_secret( 'myplugin/api-key', WP_Secret_Version::PREVIOUS ) ); - } - /** * The headline case: PREVIOUS must actually decrypt back to the prior value. * @@ -256,17 +244,6 @@ public function test_demotion_actually_reencrypts_rather_than_copying_ciphertext $this->assertSame( 'first-value', $previous->reveal() ); } - /** - * Ensure that wp_get_secret() returns null for the previous version of a secret written once. - * - * @covers ::wp_get_secret - */ - public function test_previous_on_a_secret_with_no_previous_slot_is_null(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); - - $this->assertNull( wp_get_secret( 'myplugin/api-key', WP_Secret_Version::PREVIOUS ) ); - } - /** * If the outgoing current slot is already undecryptable (corrupted, or * orphaned by a botched rotation), the write must still succeed rather than diff --git a/tests/phpunit/tests/secrets/wpSecret.php b/tests/phpunit/tests/secrets/wpSecret.php index 3fd59c077479d..52b5ef83436a6 100644 --- a/tests/phpunit/tests/secrets/wpSecret.php +++ b/tests/phpunit/tests/secrets/wpSecret.php @@ -446,16 +446,4 @@ public function test_withheld_masks_like_any_other_secret(): void { $this->assertStringNotContainsString( 'UNIQUE-REASON-CANARY-4b1c', $printed ); $this->assertStringContainsString( '[secret:myplugin/signing-key]', (string) $secret ); } - - /** - * An ordinary secret is unaffected: reveal() still returns the plaintext, and - * the widened return type is not a behaviour change for the shipped provider. - * - * @covers WP_Secret::reveal - */ - public function test_an_ordinary_secret_still_reveals_a_plain_string(): void { - $secret = new WP_Secret( 'myplugin/api-key', 'sk_live_value', 'fingerprint' ); - - $this->assertSame( 'sk_live_value', $secret->reveal() ); - } } diff --git a/tests/phpunit/tests/secrets/wpSecretsMemzero.php b/tests/phpunit/tests/secrets/wpSecretsMemzero.php index a40be78b547de..afa2d2f822aef 100644 --- a/tests/phpunit/tests/secrets/wpSecretsMemzero.php +++ b/tests/phpunit/tests/secrets/wpSecretsMemzero.php @@ -47,11 +47,11 @@ public function test_leaves_an_empty_string_untouched(): void { } /** - * Ensure that wp_secrets_memzero() clears a copy-on-write string without throwing. + * Ensure that wp_secrets_memzero() clears the variable passed and leaves a shared copy untouched. * * @covers ::wp_secrets_memzero */ - public function test_does_not_throw_when_the_value_is_shared(): void { + public function test_clears_the_variable_and_leaves_a_shared_copy_untouched(): void { $value = 'shared plaintext'; $copy = $value; diff --git a/tests/phpunit/tests/secrets/wpSecretsOptionStore.php b/tests/phpunit/tests/secrets/wpSecretsOptionStore.php index cf7d1f15e63cf..3e42c815c206c 100644 --- a/tests/phpunit/tests/secrets/wpSecretsOptionStore.php +++ b/tests/phpunit/tests/secrets/wpSecretsOptionStore.php @@ -198,7 +198,7 @@ public function test_list_names_does_not_include_unrelated_options(): void { * * @covers WP_Secrets_Option_Store::list_names */ - public function test_list_names_does_not_include_network_scope_names(): void { + public function test_list_names_returns_only_the_requested_scope(): void { $store = new WP_Secrets_Option_Store(); $store->set( 'myplugin/site-only', $this->sample_record(), false ); $store->set( 'myplugin/network-only', $this->sample_record(), true ); diff --git a/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php b/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php index 3e88e7c7344d7..9b8d9c99c62f2 100644 --- a/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php +++ b/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php @@ -27,15 +27,6 @@ public function test_set_then_get_round_trips(): void { $this->assertNotSame( '', $secret->fingerprint() ); } - /** - * Ensure that wp_get_secret() returns null for a secret that was never stored. - * - * @covers ::wp_get_secret - */ - public function test_get_returns_null_for_an_absent_secret(): void { - $this->assertNull( wp_get_secret( 'myplugin/never-set' ) ); - } - /** * Ensure that wp_get_secret() returns the current version when no version is requested. * @@ -52,17 +43,6 @@ public function test_get_defaults_to_the_current_version(): void { $this->assertSame( $default->reveal(), $current->reveal() ); } - /** - * Ensure that requesting the previous version of a never-rotated secret returns null, not an error. - * - * @covers ::wp_get_secret - */ - public function test_get_previous_on_a_never_rotated_secret_is_null_not_error(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); - - $this->assertNull( wp_get_secret( 'myplugin/api-key', WP_Secret_Version::PREVIOUS ) ); - } - /** * An unrecognised version is a caller mistake, and WordPress reports those as * WP_Error plus a _doing_it_wrong() notice rather than by throwing. The From 69eb344e2a77851f669dfd4f37b80e7745ca848a Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 10:04:37 +1100 Subject: [PATCH 05/28] Remove stale reference to plugin. --- src/wp-includes/secrets/class-wp-secret.php | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/src/wp-includes/secrets/class-wp-secret.php b/src/wp-includes/secrets/class-wp-secret.php index 260990c3a65ed..7ecb1d703e4f7 100644 --- a/src/wp-includes/secrets/class-wp-secret.php +++ b/src/wp-includes/secrets/class-wp-secret.php @@ -224,13 +224,11 @@ public function __toString(): string { } /** - * Masks the instance for var_dump(). + * Masks the instance for var_dump() and print_r(). * - * Note that print_r() and var_export() have no equivalent hook. They are safe - * regardless, because the plaintext is never a declared property for them to - * enumerate; they will surface the (non-sensitive) name and fingerprint rather - * than this placeholder. See docs/journal/open-questions.md for the documented - * var_export() limitation. + * Note that var_export() has no equivalent hook. It is safe regardless, because + * the plaintext is never a declared property for it to enumerate; it will surface + * the (non-sensitive) name and fingerprint rather than this placeholder. * * @since 7.2.0 * From c21efa684bc822e75f8ce10fe6985e0af5b9da5f Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 10:04:56 +1100 Subject: [PATCH 06/28] Tests: fuirther fixes. --- .../class-wp-secrets-provider-conformance.php | 2 +- .../tests/secrets/brokenDropinFallbacks.php | 20 +++++--- tests/phpunit/tests/secrets/errorCodes.php | 46 ++++++++++++------- .../phpunit/tests/secrets/extensionPoints.php | 15 +++--- tests/phpunit/tests/secrets/siteHealth.php | 8 ++-- tests/phpunit/tests/secrets/versionSlots.php | 12 ++--- tests/phpunit/tests/secrets/wpListSecrets.php | 2 +- .../secrets/wpSecretsConfigKeyProvider.php | 6 ++- .../secrets/wpSetSecretAndWpGetSecret.php | 7 ++- 9 files changed, 73 insertions(+), 45 deletions(-) diff --git a/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php b/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php index 72d55ede04d09..0a3d0a973dc1a 100644 --- a/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php +++ b/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php @@ -137,7 +137,7 @@ public function test_is_writable_returns_a_bool(): void { } /** - * The declaration has to match the behaviour, or a settings screen that trusts + * The declaration has to match the behavior, or a settings screen that trusts * is_writable() will offer a save control that cannot work. * * @covers WP_Secrets_Provider::is_writable diff --git a/tests/phpunit/tests/secrets/brokenDropinFallbacks.php b/tests/phpunit/tests/secrets/brokenDropinFallbacks.php index 49bfdd28dae2d..718957e630434 100644 --- a/tests/phpunit/tests/secrets/brokenDropinFallbacks.php +++ b/tests/phpunit/tests/secrets/brokenDropinFallbacks.php @@ -32,7 +32,7 @@ public function test_broken_store_get_fails(): void { } /** - * Ensure that WP_Secrets_Broken_Store::set() returns a WP_Error rather than storing a record. + * Ensure that WP_Secrets_Broken_Store::set() fails with a store-unavailable error. * * @covers WP_Secrets_Broken_Store::set */ @@ -40,10 +40,11 @@ public function test_broken_store_set_fails(): void { $result = ( new WP_Secrets_Broken_Store() )->set( 'myplugin/api-key', array() ); $this->assertWPError( $result ); + $this->assertSame( WP_SECRETS_ERROR_STORE_UNAVAILABLE, $result->get_error_code() ); } /** - * Ensure that WP_Secrets_Broken_Store::delete() returns a WP_Error. + * Ensure that WP_Secrets_Broken_Store::delete() fails with a store-unavailable error. * * @covers WP_Secrets_Broken_Store::delete */ @@ -51,10 +52,11 @@ public function test_broken_store_delete_fails(): void { $result = ( new WP_Secrets_Broken_Store() )->delete( 'myplugin/api-key' ); $this->assertWPError( $result ); + $this->assertSame( WP_SECRETS_ERROR_STORE_UNAVAILABLE, $result->get_error_code() ); } /** - * Ensure that WP_Secrets_Broken_Store::list_names() returns a WP_Error rather than a list. + * Ensure that WP_Secrets_Broken_Store::list_names() fails with a store-unavailable error. * * @covers WP_Secrets_Broken_Store::list_names */ @@ -62,6 +64,7 @@ public function test_broken_store_list_names_fails(): void { $result = ( new WP_Secrets_Broken_Store() )->list_names(); $this->assertWPError( $result ); + $this->assertSame( WP_SECRETS_ERROR_STORE_UNAVAILABLE, $result->get_error_code() ); } /** @@ -86,7 +89,7 @@ public function test_broken_keyring_wrap_fails(): void { } /** - * Ensure that WP_Secrets_Broken_Keyring::unwrap() returns a WP_Error. + * Ensure that WP_Secrets_Broken_Keyring::unwrap() fails with a key-unavailable error. * * @covers WP_Secrets_Broken_Keyring::unwrap */ @@ -94,6 +97,7 @@ public function test_broken_keyring_unwrap_fails(): void { $result = ( new WP_Secrets_Broken_Keyring() )->unwrap( 'wrapped' ); $this->assertWPError( $result ); + $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code() ); } /** @@ -123,9 +127,11 @@ public function test_wp_using_secrets_dropin_is_false_by_default(): void { * @preserveGlobalState disabled */ public function test_wp_using_secrets_dropin_reports_true_once_the_loader_flag_is_set(): void { - // Simulates what wp_load_secrets_dropin() sets when a drop-in file is - // found, without depending on an actual file on disk – see - // tests/phpunit/test-secrets-extension-points.php for why. + /* + * Simulates what wp_load_secrets_dropin() sets when a drop-in file is found. + * The loader runs once per request, before any test, so it cannot be driven + * against a real file here. + */ $GLOBALS['wp_secrets_dropin_loaded'] = true; $this->assertTrue( wp_using_secrets_dropin() ); diff --git a/tests/phpunit/tests/secrets/errorCodes.php b/tests/phpunit/tests/secrets/errorCodes.php index ba266dcd33e2d..03d10e672edd5 100644 --- a/tests/phpunit/tests/secrets/errorCodes.php +++ b/tests/phpunit/tests/secrets/errorCodes.php @@ -28,13 +28,16 @@ public function test_error_code_values_match_the_published_contract( $constant, */ public static function data_published_error_codes() { return array( - 'decryption failed' => array( 'WP_SECRETS_ERROR_DECRYPTION_FAILED', 'secret_decryption_failed' ), - 'key unavailable' => array( 'WP_SECRETS_ERROR_KEY_UNAVAILABLE', 'secret_key_unavailable' ), - 'store unavailable' => array( 'WP_SECRETS_ERROR_STORE_UNAVAILABLE', 'secret_store_unavailable' ), - 'invalid name' => array( 'WP_SECRETS_ERROR_INVALID_NAME', 'secret_invalid_name' ), - 'invalid value' => array( 'WP_SECRETS_ERROR_INVALID_VALUE', 'secret_invalid_value' ), - 'crypto unavailable' => array( 'WP_SECRETS_ERROR_CRYPTO_UNAVAILABLE', 'secret_crypto_unavailable' ), - 'record malformed' => array( 'WP_SECRETS_ERROR_RECORD_MALFORMED', 'secret_record_malformed' ), + 'decryption failed' => array( 'WP_SECRETS_ERROR_DECRYPTION_FAILED', 'secret_decryption_failed' ), + 'key unavailable' => array( 'WP_SECRETS_ERROR_KEY_UNAVAILABLE', 'secret_key_unavailable' ), + 'store unavailable' => array( 'WP_SECRETS_ERROR_STORE_UNAVAILABLE', 'secret_store_unavailable' ), + 'invalid name' => array( 'WP_SECRETS_ERROR_INVALID_NAME', 'secret_invalid_name' ), + 'invalid value' => array( 'WP_SECRETS_ERROR_INVALID_VALUE', 'secret_invalid_value' ), + 'invalid argument' => array( 'WP_SECRETS_ERROR_INVALID_ARGUMENT', 'secret_invalid_argument' ), + 'crypto unavailable' => array( 'WP_SECRETS_ERROR_CRYPTO_UNAVAILABLE', 'secret_crypto_unavailable' ), + 'record malformed' => array( 'WP_SECRETS_ERROR_RECORD_MALFORMED', 'secret_record_malformed' ), + 'record unsupported version' => array( 'WP_SECRETS_ERROR_RECORD_UNSUPPORTED_VERSION', 'secret_record_unsupported_version' ), + 'provider read only' => array( 'WP_SECRETS_ERROR_PROVIDER_READ_ONLY', 'secret_provider_read_only' ), ); } @@ -44,19 +47,30 @@ public static function data_published_error_codes() { * @coversNothing */ public function test_all_error_codes_are_distinct(): void { - $codes = array( - WP_SECRETS_ERROR_DECRYPTION_FAILED, - WP_SECRETS_ERROR_KEY_UNAVAILABLE, - WP_SECRETS_ERROR_STORE_UNAVAILABLE, - WP_SECRETS_ERROR_INVALID_NAME, - WP_SECRETS_ERROR_INVALID_VALUE, - WP_SECRETS_ERROR_CRYPTO_UNAVAILABLE, - WP_SECRETS_ERROR_RECORD_MALFORMED, - ); + $codes = array_map( 'constant', array_column( self::data_published_error_codes(), 0 ) ); $this->assertSame( count( $codes ), count( array_unique( $codes ) ) ); } + /** + * Ensure that every WP_SECRETS_ERROR_* constant is pinned by the published contract. + * + * Fails when a new error code is added without being added to the data provider + * above, so the contract cannot silently fall behind the codes the API returns. + * + * @coversNothing + */ + public function test_every_error_code_constant_is_pinned(): void { + $defined = array_filter( + array_keys( get_defined_constants() ), + static function ( $name ) { + return str_starts_with( $name, 'WP_SECRETS_ERROR_' ); + } + ); + + $this->assertSameSets( array_column( self::data_published_error_codes(), 0 ), $defined ); + } + /** * Ensure that WP_SECRETS_MAX_NAME_LENGTH fits the longest prefixed name in option_name. * diff --git a/tests/phpunit/tests/secrets/extensionPoints.php b/tests/phpunit/tests/secrets/extensionPoints.php index 8245381ba67f1..ec384eff7bcba 100644 --- a/tests/phpunit/tests/secrets/extensionPoints.php +++ b/tests/phpunit/tests/secrets/extensionPoints.php @@ -12,11 +12,11 @@ * first time either is called in a process, and by the time any test method runs, * dozens of earlier tests have already triggered that caching with the defaults. * - * @runInSeparateProcess gives each test a fresh process with nothing cached yet, so - * setting the global before the first call actually takes effect. This tests the - * real consumption logic in _wp_secrets_get_store()/_wp_secrets_get_key_manager(); - * see docs/journal/test-coverage-gaps.md for what this does not cover (the drop-in's own file - * loading, which cannot be driven the same way). + * Running each test in a separate process gives it a fresh process with nothing + * cached yet, so setting the global before the first call actually takes effect. + * This tests the real consumption logic in _wp_secrets_get_store() and + * _wp_secrets_get_key_manager(). It does not cover wp_load_secrets_dropin() loading + * a drop-in file from disk, which cannot be driven the same way. * * @ticket 66187 * @@ -214,9 +214,8 @@ public function test_the_store_is_never_handed_a_plaintext(): void { /** * Simulates the state a broken secrets.php drop-in leaves behind - * ($GLOBALS['wp_secrets_dropin_broken'] set by wp_load_secrets_dropin() – - * see that function's docblock in secrets-api.php for why the drop-in's own file - * loading cannot be driven the same way this simulates its aftermath) and + * ($GLOBALS['wp_secrets_dropin_broken'], set by wp_load_secrets_dropin(), which + * runs once per request before any test and so cannot be driven directly) and * confirms every operation fails closed with WP_Error rather than a fatal error * or a silent fallback to local storage. * diff --git a/tests/phpunit/tests/secrets/siteHealth.php b/tests/phpunit/tests/secrets/siteHealth.php index ae922c550614f..e3b74cfa13e97 100644 --- a/tests/phpunit/tests/secrets/siteHealth.php +++ b/tests/phpunit/tests/secrets/siteHealth.php @@ -237,7 +237,7 @@ public function test_needs_rotation_test_is_recommended_after_an_import(): void $result = wp_secrets_site_health_test_needs_rotation(); $this->assertSame( 'recommended', $result['status'] ); - $this->assertStringContainsString( '1', $result['description'] ); + $this->assertStringContainsString( '1 secret was imported', $result['description'], 'The description should report the number of secrets flagged for rotation.' ); } /** @@ -248,9 +248,7 @@ public function test_needs_rotation_test_is_recommended_after_an_import(): void public function test_debug_info_reports_expected_fields(): void { wp_set_secret( 'myplugin/api-key', 'value' ); - $info = wp_secrets_site_health_debug_info( array() ); - - $this->assertArrayHasKey( 'secrets-api', $info ); + $info = wp_secrets_site_health_debug_info( array() ); $fields = $this->debug_fields( $info ); $this->assertArrayHasKey( 'dropin_active', $fields ); @@ -260,8 +258,10 @@ public function test_debug_info_reports_expected_fields(): void { $this->assertArrayHasKey( 'record_version', $fields ); $this->assertArrayHasKey( 'site_secret_count', $fields ); + $this->assertSame( 'No', $fields['dropin_active']['value'], 'No drop-in is installed in the test environment.' ); $this->assertSame( 'WP_Secrets_Libsodium_Provider', $fields['provider_class']['value'] ); $this->assertSame( 'WP_Secrets_Config_Key_Provider', $fields['keyring_class']['value'] ); + $this->assertSame( ( new WP_Secrets_Config_Key_Provider() )->get_key_source(), $fields['key_source']['value'], 'The key source should be reported from the keyring in use.' ); $this->assertSame( '1', $fields['record_version']['value'] ); $this->assertSame( '1', $fields['site_secret_count']['value'] ); } diff --git a/tests/phpunit/tests/secrets/versionSlots.php b/tests/phpunit/tests/secrets/versionSlots.php index 2404ec07c1d89..69823ad4224e1 100644 --- a/tests/phpunit/tests/secrets/versionSlots.php +++ b/tests/phpunit/tests/secrets/versionSlots.php @@ -1,9 +1,7 @@ assertIsArray( $record ); $this->assertArrayHasKey( 'current', $record ); diff --git a/tests/phpunit/tests/secrets/wpListSecrets.php b/tests/phpunit/tests/secrets/wpListSecrets.php index f8b3ed13471dc..04123dc4f9f30 100644 --- a/tests/phpunit/tests/secrets/wpListSecrets.php +++ b/tests/phpunit/tests/secrets/wpListSecrets.php @@ -181,7 +181,7 @@ public function test_a_corrupt_record_is_still_listed_with_blank_metadata(): voi */ public function test_does_not_list_network_scope_secrets(): void { wp_set_secret( 'myplugin/site-only', 'value' ); - _wp_secrets_set( 'myplugin/network-only', 'value', true ); + wp_set_network_secret( 'myplugin/network-only', 'value' ); $entries = wp_list_secrets(); diff --git a/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php b/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php index 0ac1f107af28a..74217662cf7ec 100644 --- a/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php +++ b/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php @@ -4,7 +4,7 @@ * * Constants (WP_SECRETS_KEY, WP_SECRETS_KEY_PREVIOUS) that this class reads can only * be defined once per PHP process, so any test that needs a specific value for them - * runs @runInSeparateProcess. LOGGED_IN_KEY/LOGGED_IN_SALT are already defined by the + * runs in a separate process. LOGGED_IN_KEY/LOGGED_IN_SALT are already defined by the * WordPress test suite's own bootstrap before any test of ours can run, in every * process including an isolated one, so the salt-fallback path is exercised against * whatever the ambient harness defines them as rather than a value this suite picks. @@ -159,6 +159,10 @@ public function test_get_key_source_reports_the_salt_fallback_when_wp_secrets_ke $this->markTestSkipped( 'Needs real LOGGED_IN_KEY and LOGGED_IN_SALT values; wp-tests-config-sample.php ships placeholders.' ); } + if ( defined( 'WP_SECRETS_KEY' ) ) { + $this->markTestSkipped( 'Needs WP_SECRETS_KEY to be undefined; it is defined in this process.' ); + } + $provider = new WP_Secrets_Config_Key_Provider(); $this->assertStringContainsString( 'LOGGED_IN_KEY', $provider->get_key_source() ); diff --git a/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php b/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php index 9b8d9c99c62f2..10414cb833032 100644 --- a/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php +++ b/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php @@ -185,7 +185,7 @@ public function test_no_capability_check_is_applied(): void { } /** - * Ensure that storing a new secret fires wp_secret_changed with the created action. + * Ensure that storing a new secret fires wp_secret_changed as created, with its actor and time. * * @covers ::wp_set_secret */ @@ -200,13 +200,18 @@ function ( ...$args ) use ( &$captured ) { 7 ); + $before = time(); wp_set_secret( 'myplugin/api-key', 'value' ); + $after = time(); $this->assertNotNull( $captured ); list( $name, $action, $actor_id, $timestamp, $old_fingerprint, $new_fingerprint, $network ) = $captured; $this->assertSame( 'myplugin/api-key', $name ); $this->assertSame( 'created', $action ); + $this->assertSame( 0, $actor_id, 'With no user logged in, the actor should be reported as 0.' ); + $this->assertGreaterThanOrEqual( $before, $timestamp, 'The timestamp should not predate the write.' ); + $this->assertLessThanOrEqual( $after, $timestamp, 'The timestamp should not postdate the write.' ); $this->assertSame( '', $old_fingerprint ); $this->assertNotSame( '', $new_fingerprint ); $this->assertFalse( $network ); From 3442d7c6dcf9972d4a5ddb362e9debf823e01e13 Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 10:11:14 +1100 Subject: [PATCH 07/28] Use consistent subpackage name in source and test suites. --- .../includes/secrets/class-wp-secrets-keyring-conformance.php | 3 ++- .../includes/secrets/class-wp-secrets-provider-conformance.php | 3 ++- tests/phpunit/includes/secrets/trait-wp-secrets-assertions.php | 3 ++- tests/phpunit/tests/secrets/wpSecret.php | 3 ++- 4 files changed, 8 insertions(+), 4 deletions(-) diff --git a/tests/phpunit/includes/secrets/class-wp-secrets-keyring-conformance.php b/tests/phpunit/includes/secrets/class-wp-secrets-keyring-conformance.php index a078e432d2226..e8fbf264d9265 100644 --- a/tests/phpunit/includes/secrets/class-wp-secrets-keyring-conformance.php +++ b/tests/phpunit/includes/secrets/class-wp-secrets-keyring-conformance.php @@ -10,7 +10,8 @@ * rather than an exception or a falsy string. Those are the properties that * actually matter to WP_Secrets_Key_Manager, the only caller of a keyring. * - * @package SecretsAPI + * @package WordPress + * @subpackage Secrets */ abstract class WP_Secrets_Keyring_Conformance extends WP_UnitTestCase { diff --git a/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php b/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php index 0a3d0a973dc1a..2d4f2d92d58a0 100644 --- a/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php +++ b/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php @@ -19,7 +19,8 @@ * version history is not asked to produce a previous one. What does not vary is * checked for everyone. * - * @package SecretsAPI + * @package WordPress + * @subpackage Secrets */ abstract class WP_Secrets_Provider_Conformance extends WP_UnitTestCase { diff --git a/tests/phpunit/includes/secrets/trait-wp-secrets-assertions.php b/tests/phpunit/includes/secrets/trait-wp-secrets-assertions.php index 504d6dde591f1..707ef222de066 100644 --- a/tests/phpunit/includes/secrets/trait-wp-secrets-assertions.php +++ b/tests/phpunit/includes/secrets/trait-wp-secrets-assertions.php @@ -5,7 +5,8 @@ * Kept in one place so a change to what "never contains plaintext" means is a single * edit rather than a search across the suite. * - * @package SecretsAPI + * @package WordPress + * @subpackage Secrets */ /** diff --git a/tests/phpunit/tests/secrets/wpSecret.php b/tests/phpunit/tests/secrets/wpSecret.php index 52b5ef83436a6..7a13ae4f4278a 100644 --- a/tests/phpunit/tests/secrets/wpSecret.php +++ b/tests/phpunit/tests/secrets/wpSecret.php @@ -2,7 +2,8 @@ /** * Tests for WP_Secret. * - * @package SecretsAPI + * @package WordPress + * @subpackage Secrets */ /** From 7a29f46a4d1ec3c732dbe97fbfbdf83f02cefec2 Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 10:26:26 +1100 Subject: [PATCH 08/28] Add messsages to each assertion. --- .../class-wp-secrets-keyring-conformance.php | 22 +-- .../class-wp-secrets-provider-conformance.php | 84 ++++++------ .../secrets/trait-wp-secrets-assertions.php | 8 +- .../tests/secrets/brokenDropinFallbacks.php | 34 ++--- tests/phpunit/tests/secrets/capabilities.php | 20 +-- tests/phpunit/tests/secrets/errorCodes.php | 8 +- .../phpunit/tests/secrets/extensionPoints.php | 46 +++---- tests/phpunit/tests/secrets/networkScope.php | 49 +++---- tests/phpunit/tests/secrets/provider.php | 41 +++--- tests/phpunit/tests/secrets/siteHealth.php | 96 ++++++------- .../tests/secrets/threeStateContract.php | 70 +++++----- tests/phpunit/tests/secrets/versionSlots.php | 102 +++++++------- .../phpunit/tests/secrets/wpDeleteSecret.php | 30 ++-- .../tests/secrets/wpImportOptionAsSecret.php | 50 +++---- tests/phpunit/tests/secrets/wpListSecrets.php | 63 ++++----- tests/phpunit/tests/secrets/wpSecret.php | 50 +++---- .../phpunit/tests/secrets/wpSecretVersion.php | 12 +- .../phpunit/tests/secrets/wpSecretsCipher.php | 87 ++++++------ .../secrets/wpSecretsConfigKeyProvider.php | 72 +++++----- .../tests/secrets/wpSecretsKeyManager.php | 128 +++++++++--------- .../tests/secrets/wpSecretsMemzero.php | 12 +- .../tests/secrets/wpSecretsOptionStore.php | 56 ++++---- .../tests/secrets/wpSecretsValidateName.php | 12 +- .../secrets/wpSetSecretAndWpGetSecret.php | 84 ++++++------ 24 files changed, 626 insertions(+), 610 deletions(-) diff --git a/tests/phpunit/includes/secrets/class-wp-secrets-keyring-conformance.php b/tests/phpunit/includes/secrets/class-wp-secrets-keyring-conformance.php index e8fbf264d9265..f1c9596325ea0 100644 --- a/tests/phpunit/includes/secrets/class-wp-secrets-keyring-conformance.php +++ b/tests/phpunit/includes/secrets/class-wp-secrets-keyring-conformance.php @@ -36,12 +36,12 @@ public function test_wrap_returns_a_non_empty_string_that_unwraps_to_the_same_by $wrapped = $keyring->wrap( $key_material ); - $this->assertIsString( $wrapped ); - $this->assertNotSame( '', $wrapped ); + $this->assertIsString( $wrapped, 'wrap() should return a string.' ); + $this->assertNotSame( '', $wrapped, 'wrap() should not return an empty string.' ); $unwrapped = $keyring->unwrap( $wrapped ); - $this->assertSame( $key_material, $unwrapped ); + $this->assertSame( $key_material, $unwrapped, 'unwrap() should return the original key material.' ); } /** @@ -59,7 +59,7 @@ public function test_two_wraps_of_the_same_bytes_return_different_strings(): voi $first = $keyring->wrap( $key_material ); $second = $keyring->wrap( $key_material ); - $this->assertNotSame( $first, $second ); + $this->assertNotSame( $first, $second, 'Two wraps of the same key material should return different strings.' ); } /** @@ -74,7 +74,7 @@ public function test_unwrap_of_garbage_is_a_wp_error(): void { $keyring = $this->keyring(); $garbage = 'garbage-' . bin2hex( random_bytes( 16 ) ); - $this->assertWPError( $keyring->unwrap( $garbage ) ); + $this->assertWPError( $keyring->unwrap( $garbage ), 'Unwrapping garbage should return a WP_Error.' ); } /** @@ -88,11 +88,11 @@ public function test_unwrap_of_a_truncated_value_is_a_wp_error(): void { $keyring = $this->keyring(); $wrapped = $keyring->wrap( random_bytes( 32 ) ); - $this->assertIsString( $wrapped ); + $this->assertIsString( $wrapped, 'wrap() should return a string.' ); $truncated = substr( $wrapped, 0, intdiv( strlen( $wrapped ), 2 ) ); - $this->assertWPError( $keyring->unwrap( $truncated ) ); + $this->assertWPError( $keyring->unwrap( $truncated ), 'Unwrapping a truncated value should return a WP_Error.' ); } /** @@ -106,13 +106,13 @@ public function test_unwrap_of_a_value_with_one_flipped_byte_is_a_wp_error(): vo $keyring = $this->keyring(); $wrapped = $keyring->wrap( random_bytes( 32 ) ); - $this->assertIsString( $wrapped ); + $this->assertIsString( $wrapped, 'wrap() should return a string.' ); $flip_at = intdiv( strlen( $wrapped ), 2 ); $flipped = $wrapped; $flipped[ $flip_at ] = chr( ord( $wrapped[ $flip_at ] ) ^ 0x01 ); - $this->assertWPError( $keyring->unwrap( $flipped ) ); + $this->assertWPError( $keyring->unwrap( $flipped ), 'Unwrapping a value with one flipped byte should return a WP_Error.' ); } /** @@ -124,7 +124,7 @@ public function test_unwrap_of_a_value_with_one_flipped_byte_is_a_wp_error(): vo public function test_get_key_source_returns_a_non_empty_string(): void { $source = $this->keyring()->get_key_source(); - $this->assertIsString( $source ); - $this->assertNotSame( '', trim( $source ) ); + $this->assertIsString( $source, 'get_key_source() should return a string.' ); + $this->assertNotSame( '', trim( $source ), 'get_key_source() should not return an empty or whitespace-only string.' ); } } diff --git a/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php b/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php index 2d4f2d92d58a0..1d542893632be 100644 --- a/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php +++ b/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php @@ -111,8 +111,8 @@ private function has_previous_version( WP_Secrets_Provider $provider, $name ) { public function test_reports_a_non_empty_label(): void { $label = $this->provider()->get_label(); - $this->assertIsString( $label ); - $this->assertNotSame( '', trim( $label ) ); + $this->assertIsString( $label, 'The provider label should be a string.' ); + $this->assertNotSame( '', trim( $label ), 'The provider label should not be empty or only whitespace.' ); } /** @@ -134,7 +134,7 @@ public function test_reports_a_known_protection_boundary(): void { * @covers WP_Secrets_Provider::is_writable */ public function test_is_writable_returns_a_bool(): void { - $this->assertIsBool( $this->provider()->is_writable() ); + $this->assertIsBool( $this->provider()->is_writable(), 'The provider should report is_writable() as a bool.' ); } /** @@ -153,7 +153,7 @@ public function test_a_read_only_provider_actually_refuses_writes(): void { $result = $provider->set( $this->conformance_name(), 'value' ); - $this->assertWPError( $result ); + $this->assertWPError( $result, 'The provider should refuse a write with a WP_Error when read-only.' ); $this->assertSame( WP_SECRETS_ERROR_PROVIDER_READ_ONLY, $result->get_error_code(), @@ -174,7 +174,7 @@ public function test_a_read_only_provider_actually_refuses_writes(): void { public function test_a_name_that_was_never_set_is_null(): void { $result = $this->provider()->get( 'conformance/never-set-' . uniqid(), WP_Secret_Version::CURRENT ); - $this->assertNull( $result ); + $this->assertNull( $result, 'The provider should return null for a name that was never set.' ); } /** @@ -189,12 +189,12 @@ public function test_previous_on_a_provider_or_secret_without_history_is_null_no $this->require_writable( $provider ); $name = $this->conformance_name(); - $this->assertNotWPError( $provider->set( $name, 'only-ever-one-value' ) ); + $this->assertNotWPError( $provider->set( $name, 'only-ever-one-value' ), 'The provider should accept the initial write.' ); $previous = $provider->get( $name, WP_Secret_Version::PREVIOUS ); $this->assertNotWPError( $previous, 'PREVIOUS with no previous value is absence, not an error.' ); - $this->assertNull( $previous ); + $this->assertNull( $previous, 'The provider should return null for a PREVIOUS version that does not exist.' ); } /** @@ -224,7 +224,7 @@ public function test_retiring_with_no_previous_version_is_success(): void { $name = $this->conformance_name(); $provider->set( $name, 'value' ); - $this->assertNotWPError( $provider->retire_previous( $name ) ); + $this->assertNotWPError( $provider->retire_previous( $name ), 'The provider should treat retiring with no previous version as success.' ); } // – the round trip -------------------------------------------------------- @@ -240,13 +240,13 @@ public function test_a_stored_value_comes_back_intact(): void { $this->require_writable( $provider ); $name = $this->conformance_name(); - $this->assertNotWPError( $provider->set( $name, 'sk_live_conformance_value' ) ); + $this->assertNotWPError( $provider->set( $name, 'sk_live_conformance_value' ), 'The provider should accept the write.' ); $secret = $provider->get( $name, WP_Secret_Version::CURRENT ); - $this->assertInstanceOf( 'WP_Secret', $secret ); - $this->assertSame( 'sk_live_conformance_value', $secret->reveal() ); - $this->assertSame( $name, $secret->get_name() ); + $this->assertInstanceOf( 'WP_Secret', $secret, 'The provider should return the stored value as a WP_Secret.' ); + $this->assertSame( 'sk_live_conformance_value', $secret->reveal(), 'The provider should return the stored value unchanged.' ); + $this->assertSame( $name, $secret->get_name(), 'The provider should return the secret under the name it was stored as.' ); } /** @@ -266,15 +266,15 @@ public function test_a_fingerprint_is_stable_for_the_same_value(): void { $first_read = $provider->get( $name, WP_Secret_Version::CURRENT ); $second_read = $provider->get( $name, WP_Secret_Version::CURRENT ); - $this->assertInstanceOf( 'WP_Secret', $first_read ); - $this->assertInstanceOf( 'WP_Secret', $second_read ); + $this->assertInstanceOf( 'WP_Secret', $first_read, 'The provider should return the first read as a WP_Secret.' ); + $this->assertInstanceOf( 'WP_Secret', $second_read, 'The provider should return the second read as a WP_Secret.' ); $first = $first_read->fingerprint(); $second = $second_read->fingerprint(); - $this->assertIsString( $first ); - $this->assertNotSame( '', $first ); - $this->assertSame( $first, $second ); + $this->assertIsString( $first, 'The provider should return the fingerprint as a string.' ); + $this->assertNotSame( '', $first, 'The provider should return a non-empty fingerprint.' ); + $this->assertSame( $first, $second, 'The provider should return the same fingerprint for the same value.' ); } /** @@ -304,7 +304,7 @@ public function test_writing_an_unchanged_value_keeps_the_previous_version(): vo $this->markTestSkipped( 'Provider keeps no previous version; there is nothing to keep.' ); } - $this->assertNotWPError( $provider->set( $name, 'second-value' ) ); + $this->assertNotWPError( $provider->set( $name, 'second-value' ), 'The provider should accept a write of the unchanged value.' ); $kept = $provider->get( $name, WP_Secret_Version::PREVIOUS ); @@ -324,9 +324,9 @@ public function test_a_deleted_secret_reads_as_absent(): void { $name = $this->conformance_name(); $provider->set( $name, 'value' ); - $this->assertNotWPError( $provider->delete( $name ) ); + $this->assertNotWPError( $provider->delete( $name ), 'The provider should accept the delete.' ); - $this->assertNull( $provider->get( $name, WP_Secret_Version::CURRENT ) ); + $this->assertNull( $provider->get( $name, WP_Secret_Version::CURRENT ), 'The provider should report a deleted secret as null.' ); } // – every change is reported ---------------------------------------------- @@ -345,15 +345,15 @@ public function test_a_successful_write_reports_a_change(): void { $name = $this->conformance_name(); $this->record_changes(); - $this->assertNotWPError( $provider->set( $name, 'UNIQUE-CONFORMANCE-CANARY-7c1d' ) ); + $this->assertNotWPError( $provider->set( $name, 'UNIQUE-CONFORMANCE-CANARY-7c1d' ), 'The provider should accept the write.' ); $this->assertCount( 1, $this->recorded_changes, 'set() must fire wp_secret_changed exactly once.' ); $change = $this->recorded_changes[0]; $this->assertCount( 7, $change, 'wp_secret_changed takes seven arguments, ending with $network.' ); - $this->assertSame( $name, $change[0] ); - $this->assertContains( $change[1], array( 'created', 'updated' ) ); + $this->assertSame( $name, $change[0], 'The provider should report the name of the written secret.' ); + $this->assertContains( $change[1], array( 'created', 'updated' ), 'The provider should report a write as created or updated.' ); $this->assertIsInt( $change[2], 'The actor is a user id, or 0.' ); $this->assertIsInt( $change[3], 'The timestamp is a Unix timestamp.' ); $this->assertIsString( $change[4], "The old fingerprint is a string, '' when there is none." ); @@ -373,10 +373,10 @@ public function test_an_action_override_is_reported_as_given(): void { $this->record_changes(); - $this->assertNotWPError( $provider->set( $this->conformance_name(), 'value', false, false, 'imported' ) ); + $this->assertNotWPError( $provider->set( $this->conformance_name(), 'value', false, false, 'imported' ), 'The provider should accept a write with an action override.' ); - $this->assertCount( 1, $this->recorded_changes ); - $this->assertSame( 'imported', $this->recorded_changes[0][1] ); + $this->assertCount( 1, $this->recorded_changes, 'The provider should fire wp_secret_changed exactly once for the write.' ); + $this->assertSame( 'imported', $this->recorded_changes[0][1], 'The provider should report the action override as given.' ); } /** @@ -393,10 +393,10 @@ public function test_a_network_scope_change_reports_its_scope(): void { $name = $this->conformance_name(); $this->record_changes(); - $this->assertNotWPError( $provider->set( $name, 'value', true ) ); - $this->assertNotWPError( $provider->delete( $name, true ) ); + $this->assertNotWPError( $provider->set( $name, 'value', true ), 'The provider should accept a network-scope write.' ); + $this->assertNotWPError( $provider->delete( $name, true ), 'The provider should accept a network-scope delete.' ); - $this->assertCount( 2, $this->recorded_changes ); + $this->assertCount( 2, $this->recorded_changes, 'The provider should fire wp_secret_changed once for each network-scope change.' ); $this->assertTrue( $this->recorded_changes[0][6], 'A network-scope write must report $network as true.' ); $this->assertTrue( $this->recorded_changes[1][6], 'A network-scope delete must report $network as true.' ); } @@ -415,11 +415,11 @@ public function test_deleting_a_secret_reports_a_change(): void { $this->record_changes(); - $this->assertNotWPError( $provider->delete( $name ) ); + $this->assertNotWPError( $provider->delete( $name ), 'The provider should accept the delete.' ); $this->assertCount( 1, $this->recorded_changes, 'delete() must fire wp_secret_changed exactly once.' ); - $this->assertSame( $name, $this->recorded_changes[0][0] ); - $this->assertSame( 'deleted', $this->recorded_changes[0][1] ); + $this->assertSame( $name, $this->recorded_changes[0][0], 'The provider should report the name of the deleted secret.' ); + $this->assertSame( 'deleted', $this->recorded_changes[0][1], 'The provider should report a delete as deleted.' ); } /** @@ -443,15 +443,15 @@ public function test_retiring_a_previous_version_reports_a_change(): void { $this->record_changes(); - $this->assertNotWPError( $provider->retire_previous( $name ) ); + $this->assertNotWPError( $provider->retire_previous( $name ), 'The provider should accept retiring the previous version.' ); if ( $this->has_previous_version( $provider, $name ) ) { $this->markTestSkipped( 'Provider leaves version history to its backend; nothing was cleared.' ); } $this->assertCount( 1, $this->recorded_changes, 'retire_previous() must fire wp_secret_changed exactly once.' ); - $this->assertSame( $name, $this->recorded_changes[0][0] ); - $this->assertSame( 'retired', $this->recorded_changes[0][1] ); + $this->assertSame( $name, $this->recorded_changes[0][0], 'The provider should report the name of the retired secret.' ); + $this->assertSame( 'retired', $this->recorded_changes[0][1], 'The provider should report a retire as retired.' ); } /** @@ -468,7 +468,7 @@ public function test_a_refused_write_reports_no_change(): void { $this->record_changes(); - $this->assertWPError( $provider->set( $this->conformance_name(), 'value' ) ); + $this->assertWPError( $provider->set( $this->conformance_name(), 'value' ), 'The provider should refuse a write with a WP_Error when read-only.' ); $this->assertCount( 0, $this->recorded_changes, 'A write that did not happen must not be reported as a change.' ); } @@ -491,7 +491,7 @@ public function test_listing_never_contains_a_stored_value(): void { $entries = $provider->list_secrets(); - $this->assertIsArray( $entries ); + $this->assertIsArray( $entries, 'The provider should return the listing as an array.' ); $dump = wp_json_encode( $entries ); @@ -517,8 +517,8 @@ public function test_listing_includes_a_stored_secret(): void { $entries = $provider->list_secrets(); - $this->assertNotWPError( $entries ); - $this->assertContains( $name, wp_list_pluck( $entries, 'name' ) ); + $this->assertNotWPError( $entries, 'The provider should return the listing without a WP_Error.' ); + $this->assertContains( $name, wp_list_pluck( $entries, 'name' ), 'The provider should include a stored secret in the listing.' ); } /** @@ -537,11 +537,11 @@ public function test_listing_respects_a_name_prefix(): void { $entries = $provider->list_secrets( 'conformance-a' ); - $this->assertNotWPError( $entries ); + $this->assertNotWPError( $entries, 'The provider should return the prefixed listing without a WP_Error.' ); $names = wp_list_pluck( $entries, 'name' ); - $this->assertContains( 'conformance-a/one', $names ); - $this->assertNotContains( 'conformance-b/two', $names ); + $this->assertContains( 'conformance-a/one', $names, 'The provider should include a secret matching the prefix.' ); + $this->assertNotContains( 'conformance-b/two', $names, 'The provider should omit a secret not matching the prefix.' ); } } diff --git a/tests/phpunit/includes/secrets/trait-wp-secrets-assertions.php b/tests/phpunit/includes/secrets/trait-wp-secrets-assertions.php index 707ef222de066..6ab28d5f587b8 100644 --- a/tests/phpunit/includes/secrets/trait-wp-secrets-assertions.php +++ b/tests/phpunit/includes/secrets/trait-wp-secrets-assertions.php @@ -51,13 +51,15 @@ public function assertIsSecret( $maybe_secret, $expected = null, $message = '' ) * @param string $slot A WP_Secret_Version constant. * @param string $expected Expected plaintext. * @param bool $network Whether this is a network-scope secret. + * @param string $message Optional failure message. * * @phpstan-param WP_Secret_Version::CURRENT|WP_Secret_Version::PREVIOUS $slot */ - public function assertRecordSlotDecryptsTo( $name, $slot, $expected, $network = false ): void { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid -- PHPUnit assertion naming, like assertWPError(). - $secret = $network ? wp_get_network_secret( $name, $slot ) : wp_get_secret( $name, $slot ); + public function assertRecordSlotDecryptsTo( $name, $slot, $expected, $network = false, $message = '' ): void { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid -- PHPUnit assertion naming, like assertWPError(). + $secret = $network ? wp_get_network_secret( $name, $slot ) : wp_get_secret( $name, $slot ); + $context = '' !== $message ? $message . ' ' : ''; - $this->assertIsSecret( $secret, $expected, sprintf( 'Slot "%s" of "%s":', $slot, $name ) ); + $this->assertIsSecret( $secret, $expected, $context . sprintf( 'Slot "%s" of "%s":', $slot, $name ) ); } /** diff --git a/tests/phpunit/tests/secrets/brokenDropinFallbacks.php b/tests/phpunit/tests/secrets/brokenDropinFallbacks.php index 718957e630434..0d49cfc568c80 100644 --- a/tests/phpunit/tests/secrets/brokenDropinFallbacks.php +++ b/tests/phpunit/tests/secrets/brokenDropinFallbacks.php @@ -16,7 +16,7 @@ class Tests_Secrets_BrokenDropinFallbacks extends WP_UnitTestCase { * @coversNothing */ public function test_broken_store_implements_the_interface(): void { - $this->assertInstanceOf( WP_Secrets_Store::class, new WP_Secrets_Broken_Store() ); // @phpstan-ignore method.alreadyNarrowedType (Intentionally checking the class against its interface at runtime.) + $this->assertInstanceOf( WP_Secrets_Store::class, new WP_Secrets_Broken_Store(), 'WP_Secrets_Broken_Store should implement WP_Secrets_Store.' ); // @phpstan-ignore method.alreadyNarrowedType (Intentionally checking the class against its interface at runtime.) } /** @@ -27,8 +27,8 @@ public function test_broken_store_implements_the_interface(): void { public function test_broken_store_get_fails(): void { $result = ( new WP_Secrets_Broken_Store() )->get( 'myplugin/api-key' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_STORE_UNAVAILABLE, $result->get_error_code() ); + $this->assertWPError( $result, 'get() on the broken store should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_STORE_UNAVAILABLE, $result->get_error_code(), 'get() on the broken store should report the store as unavailable.' ); } /** @@ -39,8 +39,8 @@ public function test_broken_store_get_fails(): void { public function test_broken_store_set_fails(): void { $result = ( new WP_Secrets_Broken_Store() )->set( 'myplugin/api-key', array() ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_STORE_UNAVAILABLE, $result->get_error_code() ); + $this->assertWPError( $result, 'set() on the broken store should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_STORE_UNAVAILABLE, $result->get_error_code(), 'set() on the broken store should report the store as unavailable.' ); } /** @@ -51,8 +51,8 @@ public function test_broken_store_set_fails(): void { public function test_broken_store_delete_fails(): void { $result = ( new WP_Secrets_Broken_Store() )->delete( 'myplugin/api-key' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_STORE_UNAVAILABLE, $result->get_error_code() ); + $this->assertWPError( $result, 'delete() on the broken store should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_STORE_UNAVAILABLE, $result->get_error_code(), 'delete() on the broken store should report the store as unavailable.' ); } /** @@ -63,8 +63,8 @@ public function test_broken_store_delete_fails(): void { public function test_broken_store_list_names_fails(): void { $result = ( new WP_Secrets_Broken_Store() )->list_names(); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_STORE_UNAVAILABLE, $result->get_error_code() ); + $this->assertWPError( $result, 'list_names() on the broken store should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_STORE_UNAVAILABLE, $result->get_error_code(), 'list_names() on the broken store should report the store as unavailable.' ); } /** @@ -73,7 +73,7 @@ public function test_broken_store_list_names_fails(): void { * @coversNothing */ public function test_broken_keyring_implements_the_interface(): void { - $this->assertInstanceOf( WP_Secrets_Keyring::class, new WP_Secrets_Broken_Keyring() ); // @phpstan-ignore method.alreadyNarrowedType (Intentionally checking the class against its interface at runtime.) + $this->assertInstanceOf( WP_Secrets_Keyring::class, new WP_Secrets_Broken_Keyring(), 'WP_Secrets_Broken_Keyring should implement WP_Secrets_Keyring.' ); // @phpstan-ignore method.alreadyNarrowedType (Intentionally checking the class against its interface at runtime.) } /** @@ -84,8 +84,8 @@ public function test_broken_keyring_implements_the_interface(): void { public function test_broken_keyring_wrap_fails(): void { $result = ( new WP_Secrets_Broken_Keyring() )->wrap( 'material' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code() ); + $this->assertWPError( $result, 'wrap() on the broken keyring should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code(), 'wrap() on the broken keyring should report the key as unavailable.' ); } /** @@ -96,8 +96,8 @@ public function test_broken_keyring_wrap_fails(): void { public function test_broken_keyring_unwrap_fails(): void { $result = ( new WP_Secrets_Broken_Keyring() )->unwrap( 'wrapped' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code() ); + $this->assertWPError( $result, 'unwrap() on the broken keyring should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code(), 'unwrap() on the broken keyring should report the key as unavailable.' ); } /** @@ -106,7 +106,7 @@ public function test_broken_keyring_unwrap_fails(): void { * @covers WP_Secrets_Broken_Keyring::get_key_source */ public function test_broken_keyring_reports_a_key_source(): void { - $this->assertIsString( ( new WP_Secrets_Broken_Keyring() )->get_key_source() ); + $this->assertIsString( ( new WP_Secrets_Broken_Keyring() )->get_key_source(), 'The broken keyring should report its key source as a string.' ); } /** @@ -115,7 +115,7 @@ public function test_broken_keyring_reports_a_key_source(): void { * @covers ::wp_using_secrets_dropin */ public function test_wp_using_secrets_dropin_is_false_by_default(): void { - $this->assertFalse( wp_using_secrets_dropin() ); + $this->assertFalse( wp_using_secrets_dropin(), 'wp_using_secrets_dropin() should be false when no drop-in is loaded.' ); } /** @@ -134,6 +134,6 @@ public function test_wp_using_secrets_dropin_reports_true_once_the_loader_flag_i */ $GLOBALS['wp_secrets_dropin_loaded'] = true; - $this->assertTrue( wp_using_secrets_dropin() ); + $this->assertTrue( wp_using_secrets_dropin(), 'wp_using_secrets_dropin() should be true once the loader flag is set.' ); } } diff --git a/tests/phpunit/tests/secrets/capabilities.php b/tests/phpunit/tests/secrets/capabilities.php index 634a7afde6596..ce46d393ac08c 100644 --- a/tests/phpunit/tests/secrets/capabilities.php +++ b/tests/phpunit/tests/secrets/capabilities.php @@ -51,8 +51,8 @@ private function role( $role ) { * @coversNothing */ public function test_capability_constant_values(): void { - $this->assertSame( 'manage_secrets', WP_SECRETS_CAP_MANAGE ); // @phpstan-ignore method.alreadyNarrowedType (Intentionally pinning the value of a public constant.) - $this->assertSame( 'manage_network_secrets', WP_SECRETS_CAP_MANAGE_NETWORK ); // @phpstan-ignore method.alreadyNarrowedType (Intentionally pinning the value of a public constant.) + $this->assertSame( 'manage_secrets', WP_SECRETS_CAP_MANAGE, 'WP_SECRETS_CAP_MANAGE should be manage_secrets.' ); // @phpstan-ignore method.alreadyNarrowedType (Intentionally pinning the value of a public constant.) + $this->assertSame( 'manage_network_secrets', WP_SECRETS_CAP_MANAGE_NETWORK, 'WP_SECRETS_CAP_MANAGE_NETWORK should be manage_network_secrets.' ); // @phpstan-ignore method.alreadyNarrowedType (Intentionally pinning the value of a public constant.) } /** @@ -64,7 +64,7 @@ public function test_capability_constant_values(): void { * @covers ::populate_roles_720 */ public function test_a_fresh_install_grants_manage_secrets_to_administrator(): void { - $this->assertTrue( $this->role( 'administrator' )->has_cap( WP_SECRETS_CAP_MANAGE ) ); + $this->assertTrue( $this->role( 'administrator' )->has_cap( WP_SECRETS_CAP_MANAGE ), 'The administrator role should have manage_secrets on a fresh install.' ); } /** @@ -88,7 +88,7 @@ public function test_populate_roles_720_grants_manage_secrets_to_administrator() populate_roles_720(); - $this->assertTrue( $this->role( 'administrator' )->has_cap( WP_SECRETS_CAP_MANAGE ) ); + $this->assertTrue( $this->role( 'administrator' )->has_cap( WP_SECRETS_CAP_MANAGE ), 'populate_roles_720() should grant manage_secrets to the administrator role.' ); } /** @@ -117,7 +117,7 @@ public function test_upgrade_720_grants_manage_secrets_below_its_db_version( $db $wp_current_db_version = $saved; - $this->assertSame( $expect_granted, $this->role( 'administrator' )->has_cap( WP_SECRETS_CAP_MANAGE ) ); + $this->assertSame( $expect_granted, $this->role( 'administrator' )->has_cap( WP_SECRETS_CAP_MANAGE ), 'The administrator role should have manage_secrets only when upgrading from below 64337.' ); } /** @@ -142,7 +142,7 @@ public static function data_upgrade_720_gate() { public function test_administrator_user_has_manage_secrets(): void { $user_id = self::factory()->user->create( array( 'role' => 'administrator' ) ); - $this->assertTrue( user_can( $user_id, WP_SECRETS_CAP_MANAGE ) ); + $this->assertTrue( user_can( $user_id, WP_SECRETS_CAP_MANAGE ), 'An administrator user should have manage_secrets.' ); } /** @@ -153,7 +153,7 @@ public function test_administrator_user_has_manage_secrets(): void { public function test_subscriber_does_not_have_manage_secrets(): void { $user_id = self::factory()->user->create( array( 'role' => 'subscriber' ) ); - $this->assertFalse( user_can( $user_id, WP_SECRETS_CAP_MANAGE ) ); + $this->assertFalse( user_can( $user_id, WP_SECRETS_CAP_MANAGE ), 'A subscriber user should not have manage_secrets.' ); } /** @@ -166,7 +166,7 @@ public function test_subscriber_does_not_have_manage_secrets(): void { public function test_single_site_administrator_does_not_have_manage_network_secrets(): void { $user_id = self::factory()->user->create( array( 'role' => 'administrator' ) ); - $this->assertFalse( user_can( $user_id, WP_SECRETS_CAP_MANAGE_NETWORK ) ); + $this->assertFalse( user_can( $user_id, WP_SECRETS_CAP_MANAGE_NETWORK ), 'A single site administrator should not have manage_network_secrets.' ); } /** @@ -181,7 +181,7 @@ public function test_only_super_admins_have_manage_network_secrets(): void { $super_admin = self::factory()->user->create( array( 'role' => 'administrator' ) ); grant_super_admin( $super_admin ); - $this->assertFalse( user_can( $administrator, WP_SECRETS_CAP_MANAGE_NETWORK ) ); - $this->assertTrue( user_can( $super_admin, WP_SECRETS_CAP_MANAGE_NETWORK ) ); + $this->assertFalse( user_can( $administrator, WP_SECRETS_CAP_MANAGE_NETWORK ), 'An administrator who is not a super admin should not have manage_network_secrets.' ); + $this->assertTrue( user_can( $super_admin, WP_SECRETS_CAP_MANAGE_NETWORK ), 'A super admin should have manage_network_secrets.' ); } } diff --git a/tests/phpunit/tests/secrets/errorCodes.php b/tests/phpunit/tests/secrets/errorCodes.php index 03d10e672edd5..cf4d763fbedc6 100644 --- a/tests/phpunit/tests/secrets/errorCodes.php +++ b/tests/phpunit/tests/secrets/errorCodes.php @@ -20,7 +20,7 @@ class Tests_Secrets_ErrorCodes extends WP_UnitTestCase { * @param string $expected Value the published contract assigns to it. */ public function test_error_code_values_match_the_published_contract( $constant, $expected ): void { - $this->assertSame( $expected, constant( $constant ) ); + $this->assertSame( $expected, constant( $constant ), sprintf( '%s should hold its published error code string.', $constant ) ); } /** @@ -49,7 +49,7 @@ public static function data_published_error_codes() { public function test_all_error_codes_are_distinct(): void { $codes = array_map( 'constant', array_column( self::data_published_error_codes(), 0 ) ); - $this->assertSame( count( $codes ), count( array_unique( $codes ) ) ); + $this->assertSame( count( $codes ), count( array_unique( $codes ) ), 'Every error code constant should have a distinct value.' ); } /** @@ -68,7 +68,7 @@ static function ( $name ) { } ); - $this->assertSameSets( array_column( self::data_published_error_codes(), 0 ), $defined ); + $this->assertSameSets( array_column( self::data_published_error_codes(), 0 ), $defined, 'Every WP_SECRETS_ERROR_* constant should be listed in the published contract.' ); } /** @@ -79,6 +79,6 @@ static function ( $name ) { public function test_max_name_length_matches_the_options_column_budget(): void { // wp_options.option_name is VARCHAR(191); '_wp_network_secret_' (19 // characters) is the longest prefix any store here uses. - $this->assertSame( 191 - strlen( '_wp_network_secret_' ), WP_SECRETS_MAX_NAME_LENGTH ); + $this->assertSame( 191 - strlen( '_wp_network_secret_' ), WP_SECRETS_MAX_NAME_LENGTH, 'WP_SECRETS_MAX_NAME_LENGTH should fit the longest prefixed name in option_name.' ); } } diff --git a/tests/phpunit/tests/secrets/extensionPoints.php b/tests/phpunit/tests/secrets/extensionPoints.php index ec384eff7bcba..cfd9ca00c331a 100644 --- a/tests/phpunit/tests/secrets/extensionPoints.php +++ b/tests/phpunit/tests/secrets/extensionPoints.php @@ -40,12 +40,12 @@ public function test_mock_store_with_the_default_keyring_round_trips(): void { $GLOBALS['wp_secrets_store'] = new Mock_Store(); - $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ) ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Writing through the mock store should succeed.' ); $secret = wp_get_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $secret ); - $this->assertSame( 'value', $secret->reveal() ); + $this->assertInstanceOf( WP_Secret::class, $secret, 'Reading through the mock store should return a WP_Secret.' ); + $this->assertSame( 'value', $secret->reveal(), 'The secret should reveal the value written through the mock store.' ); } /** @@ -59,12 +59,12 @@ public function test_mock_store_with_the_default_keyring_round_trips(): void { public function test_mock_keyring_with_the_default_store_round_trips(): void { $GLOBALS['wp_secrets_keyring'] = new Mock_Keyring(); - $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ) ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Writing through the mock keyring should succeed.' ); $secret = wp_get_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $secret ); - $this->assertSame( 'value', $secret->reveal() ); + $this->assertInstanceOf( WP_Secret::class, $secret, 'Reading through the mock keyring should return a WP_Secret.' ); + $this->assertSame( 'value', $secret->reveal(), 'The secret should reveal the value written through the mock keyring.' ); } /** @@ -80,12 +80,12 @@ public function test_mock_store_and_mock_keyring_together_round_trip(): void { $GLOBALS['wp_secrets_store'] = new Mock_Store(); $GLOBALS['wp_secrets_keyring'] = new Mock_Keyring(); - $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ) ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Writing through the mock store and keyring should succeed.' ); $secret = wp_get_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $secret ); - $this->assertSame( 'value', $secret->reveal() ); + $this->assertInstanceOf( WP_Secret::class, $secret, 'Reading through the mock store and keyring should return a WP_Secret.' ); + $this->assertSame( 'value', $secret->reveal(), 'The secret should reveal the value written through the mock store and keyring.' ); } /** @@ -112,9 +112,9 @@ public function test_read_succeeds_while_write_fails(): void { $write_result = wp_set_secret( 'myplugin/api-key', 'new-value' ); $read_result = wp_get_secret( 'myplugin/api-key' ); - $this->assertWPError( $write_result ); - $this->assertInstanceOf( WP_Secret::class, $read_result ); - $this->assertSame( 'seeded-before-write-broke', $read_result->reveal() ); + $this->assertWPError( $write_result, 'A write to a store that cannot write should return a WP_Error.' ); + $this->assertInstanceOf( WP_Secret::class, $read_result, 'A read from a store that cannot write should still return a WP_Secret.' ); + $this->assertSame( 'seeded-before-write-broke', $read_result->reveal(), 'The secret should reveal the value seeded before writes were disabled.' ); } /** @@ -134,12 +134,12 @@ public function test_unreachable_store_fails_closed_with_no_local_fallback(): vo $set_result = wp_set_secret( 'myplugin/api-key', 'value' ); $get_result = wp_get_secret( 'myplugin/api-key' ); - $this->assertWPError( $set_result ); - $this->assertWPError( $get_result ); + $this->assertWPError( $set_result, 'A write to an unreachable store should return a WP_Error.' ); + $this->assertWPError( $get_result, 'A read from an unreachable store should return a WP_Error.' ); // Fails closed, not merely differently: nothing was written to the real // default store either, which a silent fallback would have done. - $this->assertFalse( get_option( '_wp_secret_myplugin/api-key' ) ); + $this->assertFalse( get_option( '_wp_secret_myplugin/api-key' ), 'Nothing should be written to the default options store as a fallback.' ); } /** @@ -184,8 +184,8 @@ public function test_unreachable_keyring_fails_closed_with_no_local_fallback(): $result = wp_set_secret( 'myplugin/api-key', 'value' ); - $this->assertWPError( $result ); - $this->assertFalse( get_option( '_wp_secret_myplugin/api-key' ) ); + $this->assertWPError( $result, 'A write through a keyring that cannot wrap should return a WP_Error.' ); + $this->assertFalse( get_option( '_wp_secret_myplugin/api-key' ), 'Nothing should be written to the default options store as a fallback.' ); } /** @@ -233,11 +233,11 @@ public function test_the_store_is_never_handed_a_plaintext(): void { public function test_a_broken_dropin_state_fails_every_operation_closed(): void { $GLOBALS['wp_secrets_dropin_broken'] = true; - $this->assertWPError( wp_set_secret( 'myplugin/api-key', 'value' ) ); - $this->assertWPError( wp_get_secret( 'myplugin/api-key' ) ); - $this->assertWPError( wp_delete_secret( 'myplugin/api-key' ) ); - $this->assertWPError( wp_list_secrets() ); - $this->assertWPError( wp_retire_secret_version( 'myplugin/api-key' ) ); - $this->assertFalse( wp_secrets_provider_is_writable() ); + $this->assertWPError( wp_set_secret( 'myplugin/api-key', 'value' ), 'wp_set_secret() should return a WP_Error when the drop-in is broken.' ); + $this->assertWPError( wp_get_secret( 'myplugin/api-key' ), 'wp_get_secret() should return a WP_Error when the drop-in is broken.' ); + $this->assertWPError( wp_delete_secret( 'myplugin/api-key' ), 'wp_delete_secret() should return a WP_Error when the drop-in is broken.' ); + $this->assertWPError( wp_list_secrets(), 'wp_list_secrets() should return a WP_Error when the drop-in is broken.' ); + $this->assertWPError( wp_retire_secret_version( 'myplugin/api-key' ), 'wp_retire_secret_version() should return a WP_Error when the drop-in is broken.' ); + $this->assertFalse( wp_secrets_provider_is_writable(), 'The provider should not report as writable when the drop-in is broken.' ); } } diff --git a/tests/phpunit/tests/secrets/networkScope.php b/tests/phpunit/tests/secrets/networkScope.php index 508a60abad0f1..ef46a003995ec 100644 --- a/tests/phpunit/tests/secrets/networkScope.php +++ b/tests/phpunit/tests/secrets/networkScope.php @@ -17,12 +17,12 @@ class Tests_Secrets_NetworkScope extends WP_UnitTestCase { * @covers ::wp_get_network_secret */ public function test_set_then_get_round_trips(): void { - $this->assertTrue( wp_set_network_secret( 'myplugin/api-key', 'value' ) ); + $this->assertTrue( wp_set_network_secret( 'myplugin/api-key', 'value' ), 'Setting a network secret should succeed.' ); $secret = wp_get_network_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $secret ); - $this->assertSame( 'value', $secret->reveal() ); + $this->assertInstanceOf( WP_Secret::class, $secret, 'The network secret should be readable as a WP_Secret.' ); + $this->assertSame( 'value', $secret->reveal(), 'The network secret should return the value it was set to.' ); } /** @@ -31,7 +31,7 @@ public function test_set_then_get_round_trips(): void { * @covers ::wp_get_network_secret */ public function test_get_returns_null_for_an_absent_secret(): void { - $this->assertNull( wp_get_network_secret( 'myplugin/never-set' ) ); + $this->assertNull( wp_get_network_secret( 'myplugin/never-set' ), 'A network secret that was never set should be null.' ); } /** @@ -47,10 +47,10 @@ public function test_site_and_network_scope_are_independent_under_the_same_name( $site_secret = wp_get_secret( 'myplugin/api-key' ); $network_secret = wp_get_network_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $site_secret ); - $this->assertInstanceOf( WP_Secret::class, $network_secret ); - $this->assertSame( 'site-value', $site_secret->reveal() ); - $this->assertSame( 'network-value', $network_secret->reveal() ); + $this->assertInstanceOf( WP_Secret::class, $site_secret, 'The site secret should be readable as a WP_Secret.' ); + $this->assertInstanceOf( WP_Secret::class, $network_secret, 'The network secret should be readable as a WP_Secret.' ); + $this->assertSame( 'site-value', $site_secret->reveal(), 'The site secret should keep its own value.' ); + $this->assertSame( 'network-value', $network_secret->reveal(), 'The network secret should keep its own value.' ); } /** @@ -61,8 +61,8 @@ public function test_site_and_network_scope_are_independent_under_the_same_name( public function test_delete_removes_a_network_secret(): void { wp_set_network_secret( 'myplugin/api-key', 'value' ); - $this->assertTrue( wp_delete_network_secret( 'myplugin/api-key' ) ); - $this->assertNull( wp_get_network_secret( 'myplugin/api-key' ) ); + $this->assertTrue( wp_delete_network_secret( 'myplugin/api-key' ), 'Deleting a network secret should succeed.' ); + $this->assertNull( wp_get_network_secret( 'myplugin/api-key' ), 'A deleted network secret should be null.' ); } /** @@ -78,8 +78,8 @@ public function test_delete_does_not_touch_the_site_scope_secret_of_the_same_nam $site_secret = wp_get_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $site_secret ); - $this->assertSame( 'site-value', $site_secret->reveal() ); + $this->assertInstanceOf( WP_Secret::class, $site_secret, 'The site secret should still be readable as a WP_Secret.' ); + $this->assertSame( 'site-value', $site_secret->reveal(), 'The site secret should keep its value after the network secret is deleted.' ); } /** @@ -91,8 +91,8 @@ public function test_overwriting_a_network_secret_demotes_the_old_value(): void wp_set_network_secret( 'myplugin/api-key', 'first-value' ); wp_set_network_secret( 'myplugin/api-key', 'second-value' ); - $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::PREVIOUS, 'first-value', true ); - $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::CURRENT, 'second-value', true ); + $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::PREVIOUS, 'first-value', true, 'The previous slot should decrypt to the first network value.' ); + $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::CURRENT, 'second-value', true, 'The current slot should decrypt to the second network value.' ); } /** @@ -104,8 +104,8 @@ public function test_retire_clears_the_previous_slot(): void { wp_set_network_secret( 'myplugin/api-key', 'first-value' ); wp_set_network_secret( 'myplugin/api-key', 'second-value' ); - $this->assertTrue( wp_retire_network_secret_version( 'myplugin/api-key' ) ); - $this->assertNull( wp_get_network_secret( 'myplugin/api-key', WP_Secret_Version::PREVIOUS ) ); + $this->assertTrue( wp_retire_network_secret_version( 'myplugin/api-key' ), 'Retiring the previous network version should succeed.' ); + $this->assertNull( wp_get_network_secret( 'myplugin/api-key', WP_Secret_Version::PREVIOUS ), 'The previous network version should be gone after retiring it.' ); } /** @@ -142,7 +142,8 @@ function ( ...$args ) use ( &$scopes ) { array( 'deleted', true ), array( 'created', false ), ), - $scopes + $scopes, + 'wp_secret_changed should report each action with its network scope flag.' ); } @@ -157,8 +158,8 @@ public function test_list_returns_network_secrets_only(): void { $entries = wp_list_network_secrets(); - $this->assertIsArray( $entries ); - $this->assertSame( array( 'myplugin/network-only' ), wp_list_pluck( $entries, 'name' ) ); + $this->assertIsArray( $entries, 'wp_list_network_secrets() should return an array.' ); + $this->assertSame( array( 'myplugin/network-only' ), wp_list_pluck( $entries, 'name' ), 'The network listing should contain only the network secret.' ); } /** @@ -172,8 +173,8 @@ public function test_an_invalid_version_is_a_wp_error_same_as_site_scope(): void $result = wp_get_network_secret( 'myplugin/api-key', 'not-a-real-version' ); // @phpstan-ignore argument.type (Intentionally passing an invalid value.) - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_ARGUMENT, $result->get_error_code() ); + $this->assertWPError( $result, 'An invalid version should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_ARGUMENT, $result->get_error_code(), 'An invalid version should be rejected with WP_SECRETS_ERROR_INVALID_ARGUMENT.' ); } /** @@ -184,8 +185,8 @@ public function test_an_invalid_version_is_a_wp_error_same_as_site_scope(): void public function test_set_rejects_an_invalid_name(): void { $result = wp_set_network_secret( 'Not A Valid Name', 'value' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code() ); + $this->assertWPError( $result, 'An invalid name should be rejected with a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code(), 'An invalid name should be rejected with WP_SECRETS_ERROR_INVALID_NAME.' ); } /** @@ -230,6 +231,6 @@ public function test_site_secret_is_not_readable_from_a_different_blog(): void { $result = wp_get_secret( 'myplugin/api-key' ); restore_current_blog(); - $this->assertNull( $result ); + $this->assertNull( $result, 'A site secret should not be readable from a different blog.' ); } } diff --git a/tests/phpunit/tests/secrets/provider.php b/tests/phpunit/tests/secrets/provider.php index 83aa5b89dc177..febea51d3b580 100644 --- a/tests/phpunit/tests/secrets/provider.php +++ b/tests/phpunit/tests/secrets/provider.php @@ -102,7 +102,7 @@ public function is_writable(): bool { * @covers ::_wp_secrets_get_provider */ public function test_the_default_provider_is_the_libsodium_one(): void { - $this->assertInstanceOf( 'WP_Secrets_Libsodium_Provider', _wp_secrets_get_provider() ); + $this->assertInstanceOf( 'WP_Secrets_Libsodium_Provider', _wp_secrets_get_provider(), 'The default provider should be WP_Secrets_Libsodium_Provider.' ); } /** @@ -113,7 +113,8 @@ public function test_the_default_provider_is_the_libsodium_one(): void { public function test_the_default_provider_protects_inside_wordpress(): void { $this->assertSame( WP_Secrets_Provider::BOUNDARY_WORDPRESS, - _wp_secrets_get_provider()->get_protection_boundary() + _wp_secrets_get_provider()->get_protection_boundary(), + 'The default provider should declare BOUNDARY_WORDPRESS.' ); } @@ -123,7 +124,7 @@ public function test_the_default_provider_protects_inside_wordpress(): void { * @covers ::wp_secrets_provider_is_writable */ public function test_the_default_provider_accepts_writes(): void { - $this->assertTrue( wp_secrets_provider_is_writable() ); + $this->assertTrue( wp_secrets_provider_is_writable(), 'The default provider should be writable.' ); } /** @@ -136,10 +137,11 @@ public function test_the_default_provider_accepts_writes(): void { public function test_the_default_provider_label_names_the_key_source(): void { $label = wp_secrets_provider_label(); - $this->assertStringContainsString( 'libsodium', $label ); + $this->assertStringContainsString( 'libsodium', $label, 'The provider label should mention libsodium.' ); $this->assertStringContainsString( _wp_secrets_get_key_manager()->get_keyring()->get_key_source(), - $label + $label, + 'The provider label should name the key source.' ); } @@ -160,10 +162,11 @@ public function test_the_default_provider_label_names_the_key_source(): void { public function test_a_drop_in_provider_replaces_the_default_entirely(): void { $GLOBALS['wp_secrets_provider'] = $this->read_only_provider(); - $this->assertSame( 'Example Platform (KMS)', wp_secrets_provider_label() ); + $this->assertSame( 'Example Platform (KMS)', wp_secrets_provider_label(), 'The label should come from the drop-in provider.' ); $this->assertSame( WP_Secrets_Provider::BOUNDARY_PROVIDER, - _wp_secrets_get_provider()->get_protection_boundary() + _wp_secrets_get_provider()->get_protection_boundary(), + 'The protection boundary should come from the drop-in provider.' ); } @@ -181,12 +184,12 @@ public function test_a_drop_in_provider_replaces_the_default_entirely(): void { public function test_a_read_only_provider_refuses_writes_and_declares_it(): void { $GLOBALS['wp_secrets_provider'] = $this->read_only_provider(); - $this->assertFalse( wp_secrets_provider_is_writable() ); + $this->assertFalse( wp_secrets_provider_is_writable(), 'A read-only provider should report as not writable.' ); $result = wp_set_secret( 'myplugin/api-key', 'value' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_PROVIDER_READ_ONLY, $result->get_error_code() ); + $this->assertWPError( $result, 'A write to a read-only provider should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_PROVIDER_READ_ONLY, $result->get_error_code(), 'A write to a read-only provider should be reported as provider read-only.' ); } /** @@ -201,7 +204,7 @@ public function test_a_read_only_provider_refuses_writes_and_declares_it(): void public function test_a_read_only_provider_still_serves_reads(): void { $GLOBALS['wp_secrets_provider'] = $this->read_only_provider(); - $this->assertNull( wp_get_secret( 'myplugin/api-key' ) ); + $this->assertNull( wp_get_secret( 'myplugin/api-key' ), 'A read-only provider should report a missing secret as null.' ); } // – fail closed ----------------------------------------------------------- @@ -221,9 +224,9 @@ public function test_a_broken_dropin_fails_closed_rather_than_reverting_to_the_d $provider = _wp_secrets_get_provider(); - $this->assertNotInstanceOf( 'WP_Secrets_Libsodium_Provider', $provider ); - $this->assertInstanceOf( 'WP_Secrets_Broken_Provider', $provider ); - $this->assertFalse( $provider->is_writable() ); + $this->assertNotInstanceOf( 'WP_Secrets_Libsodium_Provider', $provider, 'A broken drop-in should not fall back to WP_Secrets_Libsodium_Provider.' ); + $this->assertInstanceOf( 'WP_Secrets_Broken_Provider', $provider, 'A broken drop-in should resolve to WP_Secrets_Broken_Provider.' ); + $this->assertFalse( $provider->is_writable(), 'A broken drop-in provider should report as not writable.' ); } /** @@ -238,7 +241,7 @@ public function test_a_broken_dropin_fails_closed_rather_than_reverting_to_the_d public function test_a_broken_dropin_read_is_an_error_not_an_absence(): void { $GLOBALS['wp_secrets_dropin_broken'] = true; - $this->assertNotNull( wp_get_secret( 'myplugin/api-key' ) ); + $this->assertNotNull( wp_get_secret( 'myplugin/api-key' ), 'A read under a broken drop-in should not be reported as an absence.' ); } /** @@ -260,7 +263,7 @@ public function test_a_broken_dropin_read_is_an_error_not_an_absence(): void { public function test_a_non_provider_global_fails_closed(): void { $GLOBALS['wp_secrets_provider'] = new stdClass(); - $this->assertInstanceOf( 'WP_Secrets_Broken_Provider', _wp_secrets_get_provider() ); + $this->assertInstanceOf( 'WP_Secrets_Broken_Provider', _wp_secrets_get_provider(), 'A non-provider global should resolve to WP_Secrets_Broken_Provider.' ); } /** @@ -278,8 +281,8 @@ public function test_a_non_provider_global_reads_as_an_error_not_an_absence(): v $result = wp_get_secret( 'myplugin/api-key' ); - $this->assertNotNull( $result ); - $this->assertWPError( $result ); + $this->assertNotNull( $result, 'A read under a non-provider global should not be reported as an absence.' ); + $this->assertWPError( $result, 'A read under a non-provider global should return a WP_Error.' ); } /** @@ -296,6 +299,6 @@ public function test_a_non_provider_global_reads_as_an_error_not_an_absence(): v public function test_a_keyring_only_dropin_still_gets_the_default_provider(): void { $GLOBALS['wp_secrets_keyring'] = new Mock_Keyring(); - $this->assertInstanceOf( 'WP_Secrets_Libsodium_Provider', _wp_secrets_get_provider() ); + $this->assertInstanceOf( 'WP_Secrets_Libsodium_Provider', _wp_secrets_get_provider(), 'A keyring-only drop-in should still get WP_Secrets_Libsodium_Provider.' ); } } diff --git a/tests/phpunit/tests/secrets/siteHealth.php b/tests/phpunit/tests/secrets/siteHealth.php index e3b74cfa13e97..62176fa504fce 100644 --- a/tests/phpunit/tests/secrets/siteHealth.php +++ b/tests/phpunit/tests/secrets/siteHealth.php @@ -16,15 +16,15 @@ class Tests_Secrets_SiteHealth extends WP_UnitTestCase { * @return array> The section's fields, keyed by field name. */ private function debug_fields( array $info ): array { - $this->assertArrayHasKey( 'secrets-api', $info ); - $this->assertArrayHasKey( 'fields', $info['secrets-api'] ); - $this->assertIsArray( $info['secrets-api']['fields'] ); + $this->assertArrayHasKey( 'secrets-api', $info, 'The debug information should include a secrets-api section.' ); + $this->assertArrayHasKey( 'fields', $info['secrets-api'], 'The secrets-api section should include a fields entry.' ); + $this->assertIsArray( $info['secrets-api']['fields'], 'The secrets-api fields entry should be an array.' ); $fields = array(); foreach ( $info['secrets-api']['fields'] as $key => $field ) { - $this->assertIsString( $key ); - $this->assertIsArray( $field ); + $this->assertIsString( $key, 'Each debug field key should be a string.' ); + $this->assertIsArray( $field, 'Each debug field should be an array.' ); $fields[ $key ] = $field; } @@ -40,13 +40,13 @@ private function debug_fields( array $info ): array { public function test_registers_three_tests_under_direct(): void { $tests = wp_secrets_site_health_tests( array() ); - $this->assertArrayHasKey( 'direct', $tests ); - $this->assertArrayHasKey( 'secrets_api_key_source', $tests['direct'] ); - $this->assertArrayHasKey( 'secrets_api_undecryptable', $tests['direct'] ); - $this->assertArrayHasKey( 'secrets_api_needs_rotation', $tests['direct'] ); + $this->assertArrayHasKey( 'direct', $tests, 'The registered tests should include a direct group.' ); + $this->assertArrayHasKey( 'secrets_api_key_source', $tests['direct'], 'The key source test should be registered as a direct test.' ); + $this->assertArrayHasKey( 'secrets_api_undecryptable', $tests['direct'], 'The undecryptable test should be registered as a direct test.' ); + $this->assertArrayHasKey( 'secrets_api_needs_rotation', $tests['direct'], 'The needs rotation test should be registered as a direct test.' ); foreach ( $tests['direct'] as $key => $test ) { - $this->assertIsString( $test['test'] ); + $this->assertIsString( $test['test'], 'Each registered test callback should be a function name string.' ); $this->assertTrue( function_exists( $test['test'] ), "Registered test callback \"{$test['test']}\" for \"{$key}\" does not exist." ); } } @@ -59,7 +59,7 @@ public function test_registers_three_tests_under_direct(): void { public function test_preserves_existing_tests(): void { $tests = wp_secrets_site_health_tests( array( 'direct' => array( 'existing_test' => array( 'label' => 'x' ) ) ) ); - $this->assertArrayHasKey( 'existing_test', $tests['direct'] ); + $this->assertArrayHasKey( 'existing_test', $tests['direct'], 'A previously registered test should be preserved.' ); } /** @@ -74,8 +74,8 @@ public function test_key_source_test_recommends_a_dedicated_key_by_default(): vo $result = wp_secrets_site_health_test_key_source(); - $this->assertSame( 'recommended', $result['status'] ); - $this->assertStringContainsString( 'WP_SECRETS_KEY', $result['description'] ); + $this->assertSame( 'recommended', $result['status'], 'The key source status should be recommended without WP_SECRETS_KEY.' ); + $this->assertStringContainsString( 'WP_SECRETS_KEY', $result['description'], 'The description should recommend defining WP_SECRETS_KEY.' ); } /** @@ -94,8 +94,8 @@ public function test_key_source_test_recommends_regeneration_for_a_legacy_key(): $result = wp_secrets_site_health_test_key_source(); - $this->assertSame( 'recommended', $result['status'] ); - $this->assertStringContainsString( 'generate-key', $result['description'] ); + $this->assertSame( 'recommended', $result['status'], 'A legacy WP_SECRETS_KEY should produce a recommended status.' ); + $this->assertStringContainsString( 'generate-key', $result['description'], 'The description should mention generate-key for regenerating the key.' ); } /** @@ -114,7 +114,7 @@ public function test_key_source_test_is_good_for_a_dedicated_base64_key(): void $result = wp_secrets_site_health_test_key_source(); - $this->assertSame( 'good', $result['status'] ); + $this->assertSame( 'good', $result['status'], 'A base64-encoded 32-byte WP_SECRETS_KEY should produce a good status.' ); } /** @@ -133,7 +133,7 @@ public function test_key_source_test_is_critical_when_the_keyring_is_broken(): v $result = wp_secrets_site_health_test_key_source(); - $this->assertSame( 'critical', $result['status'] ); + $this->assertSame( 'critical', $result['status'], 'A broken secrets drop-in should produce a critical status.' ); } /** @@ -146,7 +146,7 @@ public function test_undecryptable_test_is_good_when_nothing_is_broken(): void { $result = wp_secrets_site_health_test_undecryptable(); - $this->assertSame( 'good', $result['status'] ); + $this->assertSame( 'good', $result['status'], 'The status should be good when every secret decrypts.' ); } /** @@ -157,7 +157,7 @@ public function test_undecryptable_test_is_good_when_nothing_is_broken(): void { public function test_undecryptable_test_is_good_with_no_secrets_at_all(): void { $result = wp_secrets_site_health_test_undecryptable(); - $this->assertSame( 'good', $result['status'] ); + $this->assertSame( 'good', $result['status'], 'The status should be good when no secrets are stored.' ); } /** @@ -171,23 +171,23 @@ public function test_undecryptable_test_is_critical_and_lists_the_broken_secret( wp_set_secret( 'myplugin/api-key', 'value' ); $secret = wp_get_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $secret ); + $this->assertInstanceOf( WP_Secret::class, $secret, 'The stored secret should be retrievable as a WP_Secret.' ); $fingerprint = $secret->fingerprint(); $record = get_option( '_wp_secret_myplugin/api-key' ); - $this->assertIsArray( $record ); - $this->assertArrayHasKey( 'current', $record ); - $this->assertIsArray( $record['current'] ); + $this->assertIsArray( $record, 'The stored record should be an array.' ); + $this->assertArrayHasKey( 'current', $record, 'The stored record should have a current slot.' ); + $this->assertIsArray( $record['current'], 'The current slot should be an array.' ); $record['current']['ct'] = base64_encode( 'not decryptable' ); update_option( '_wp_secret_myplugin/api-key', $record, false ); $result = wp_secrets_site_health_test_undecryptable(); - $this->assertSame( 'critical', $result['status'] ); - $this->assertStringContainsString( 'myplugin/api-key', $result['description'] ); - $this->assertStringContainsString( $fingerprint, $result['description'] ); + $this->assertSame( 'critical', $result['status'], 'An undecryptable secret should produce a critical status.' ); + $this->assertStringContainsString( 'myplugin/api-key', $result['description'], 'The description should name the undecryptable secret.' ); + $this->assertStringContainsString( $fingerprint, $result['description'], 'The description should include the fingerprint of the undecryptable secret.' ); } /** @@ -200,16 +200,16 @@ public function test_undecryptable_test_never_contains_a_plaintext(): void { $record = get_option( '_wp_secret_myplugin/api-key' ); - $this->assertIsArray( $record ); - $this->assertArrayHasKey( 'current', $record ); - $this->assertIsArray( $record['current'] ); + $this->assertIsArray( $record, 'The stored record should be an array.' ); + $this->assertArrayHasKey( 'current', $record, 'The stored record should have a current slot.' ); + $this->assertIsArray( $record['current'], 'The current slot should be an array.' ); $record['current']['ct'] = base64_encode( 'not decryptable' ); update_option( '_wp_secret_myplugin/api-key', $record, false ); $result = wp_secrets_site_health_test_undecryptable(); - $this->assertStringNotContainsString( 'UNIQUE-PLAINTEXT-CANARY-9f3a', $result['description'] ); + $this->assertStringNotContainsString( 'UNIQUE-PLAINTEXT-CANARY-9f3a', $result['description'], 'The description should never contain the plaintext value.' ); } /** @@ -222,7 +222,7 @@ public function test_needs_rotation_test_is_good_by_default(): void { $result = wp_secrets_site_health_test_needs_rotation(); - $this->assertSame( 'good', $result['status'] ); + $this->assertSame( 'good', $result['status'], 'A directly stored secret should not need rotation.' ); } /** @@ -236,7 +236,7 @@ public function test_needs_rotation_test_is_recommended_after_an_import(): void $result = wp_secrets_site_health_test_needs_rotation(); - $this->assertSame( 'recommended', $result['status'] ); + $this->assertSame( 'recommended', $result['status'], 'An imported secret should produce a recommended status.' ); $this->assertStringContainsString( '1 secret was imported', $result['description'], 'The description should report the number of secrets flagged for rotation.' ); } @@ -251,19 +251,19 @@ public function test_debug_info_reports_expected_fields(): void { $info = wp_secrets_site_health_debug_info( array() ); $fields = $this->debug_fields( $info ); - $this->assertArrayHasKey( 'dropin_active', $fields ); - $this->assertArrayHasKey( 'provider_class', $fields ); - $this->assertArrayHasKey( 'keyring_class', $fields ); - $this->assertArrayHasKey( 'key_source', $fields ); - $this->assertArrayHasKey( 'record_version', $fields ); - $this->assertArrayHasKey( 'site_secret_count', $fields ); + $this->assertArrayHasKey( 'dropin_active', $fields, 'The debug fields should include dropin_active.' ); + $this->assertArrayHasKey( 'provider_class', $fields, 'The debug fields should include provider_class.' ); + $this->assertArrayHasKey( 'keyring_class', $fields, 'The debug fields should include keyring_class.' ); + $this->assertArrayHasKey( 'key_source', $fields, 'The debug fields should include key_source.' ); + $this->assertArrayHasKey( 'record_version', $fields, 'The debug fields should include record_version.' ); + $this->assertArrayHasKey( 'site_secret_count', $fields, 'The debug fields should include site_secret_count.' ); $this->assertSame( 'No', $fields['dropin_active']['value'], 'No drop-in is installed in the test environment.' ); - $this->assertSame( 'WP_Secrets_Libsodium_Provider', $fields['provider_class']['value'] ); - $this->assertSame( 'WP_Secrets_Config_Key_Provider', $fields['keyring_class']['value'] ); + $this->assertSame( 'WP_Secrets_Libsodium_Provider', $fields['provider_class']['value'], 'The provider class should be WP_Secrets_Libsodium_Provider.' ); + $this->assertSame( 'WP_Secrets_Config_Key_Provider', $fields['keyring_class']['value'], 'The keyring class should be WP_Secrets_Config_Key_Provider.' ); $this->assertSame( ( new WP_Secrets_Config_Key_Provider() )->get_key_source(), $fields['key_source']['value'], 'The key source should be reported from the keyring in use.' ); - $this->assertSame( '1', $fields['record_version']['value'] ); - $this->assertSame( '1', $fields['site_secret_count']['value'] ); + $this->assertSame( '1', $fields['record_version']['value'], 'The record version should be reported as 1.' ); + $this->assertSame( '1', $fields['site_secret_count']['value'], 'The site secret count should be 1.' ); } /** @@ -276,8 +276,8 @@ public function test_debug_info_reports_no_dropin_by_default(): void { $fields = $this->debug_fields( $info ); - $this->assertArrayHasKey( 'dropin_active', $fields ); - $this->assertSame( 'No', $fields['dropin_active']['value'] ); + $this->assertArrayHasKey( 'dropin_active', $fields, 'The debug fields should include dropin_active.' ); + $this->assertSame( 'No', $fields['dropin_active']['value'], 'The drop-in should be reported as inactive by default.' ); } /** @@ -292,8 +292,8 @@ public function test_debug_info_never_contains_a_plaintext(): void { $dump = wp_json_encode( $info['secrets-api'] ); - $this->assertIsString( $dump ); - $this->assertStringNotContainsString( 'UNIQUE-PLAINTEXT-CANARY-9f3a', $dump ); + $this->assertIsString( $dump, 'The secrets-api section should encode to a JSON string.' ); + $this->assertStringNotContainsString( 'UNIQUE-PLAINTEXT-CANARY-9f3a', $dump, 'The debug information should never contain the plaintext value.' ); } /** @@ -304,7 +304,7 @@ public function test_debug_info_never_contains_a_plaintext(): void { public function test_debug_info_omits_network_fields_on_single_site(): void { $info = wp_secrets_site_health_debug_info( array() ); - $this->assertArrayNotHasKey( 'network_secret_count', $this->debug_fields( $info ) ); + $this->assertArrayNotHasKey( 'network_secret_count', $this->debug_fields( $info ), 'Network secret counts should be omitted on a single site install.' ); } /** @@ -327,6 +327,6 @@ public function test_debug_info_includes_network_fields_only_for_a_super_admin() grant_super_admin( $user_id ); $info = wp_secrets_site_health_debug_info( array() ); - $this->assertArrayHasKey( 'network_secret_count', $this->debug_fields( $info ) ); + $this->assertArrayHasKey( 'network_secret_count', $this->debug_fields( $info ), 'A super admin should see network secret counts.' ); } } diff --git a/tests/phpunit/tests/secrets/threeStateContract.php b/tests/phpunit/tests/secrets/threeStateContract.php index 9e0b920464e7a..cbef8e6219125 100644 --- a/tests/phpunit/tests/secrets/threeStateContract.php +++ b/tests/phpunit/tests/secrets/threeStateContract.php @@ -19,7 +19,7 @@ class Tests_Secrets_ThreeStateContract extends WP_UnitTestCase { public function test_absent_is_null(): void { $result = wp_get_secret( 'myplugin/never-set' ); - $this->assertNull( $result ); + $this->assertNull( $result, 'A secret that was never set should be null.' ); } /** @@ -32,7 +32,7 @@ public function test_previous_slot_absent_on_an_existing_secret_is_also_null(): $result = wp_get_secret( 'myplugin/api-key', WP_Secret_Version::PREVIOUS ); - $this->assertNull( $result ); + $this->assertNull( $result, 'A missing previous version should be null.' ); } /** @@ -45,9 +45,9 @@ public function test_malformed_record_is_wp_error_not_null(): void { $result = wp_get_secret( 'myplugin/api-key' ); - $this->assertNotNull( $result ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_RECORD_MALFORMED, $result->get_error_code() ); + $this->assertNotNull( $result, 'A malformed record should not be reported as null.' ); + $this->assertWPError( $result, 'A malformed record should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_RECORD_MALFORMED, $result->get_error_code(), 'A non-array record should produce the malformed record error code.' ); } /** @@ -60,9 +60,9 @@ public function test_record_missing_the_current_slot_is_wp_error_not_null(): voi $result = wp_get_secret( 'myplugin/api-key' ); - $this->assertNotNull( $result ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_RECORD_MALFORMED, $result->get_error_code() ); + $this->assertNotNull( $result, 'A record without a current slot should not be reported as null.' ); + $this->assertWPError( $result, 'A record without a current slot should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_RECORD_MALFORMED, $result->get_error_code(), 'A record without a current slot should produce the malformed record error code.' ); } /** @@ -88,9 +88,9 @@ public function test_unsupported_record_version_is_wp_error_not_null(): void { $result = wp_get_secret( 'myplugin/api-key' ); - $this->assertNotNull( $result ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_RECORD_UNSUPPORTED_VERSION, $result->get_error_code() ); + $this->assertNotNull( $result, 'An unsupported record version should not be reported as null.' ); + $this->assertWPError( $result, 'An unsupported record version should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_RECORD_UNSUPPORTED_VERSION, $result->get_error_code(), 'An unsupported record version should produce the unsupported version error code.' ); } /** @@ -109,9 +109,9 @@ public function test_aad_mismatch_from_a_copied_record_is_wp_error_not_null(): v $result = wp_get_secret( 'myplugin/different-name' ); - $this->assertNotNull( $result ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_DECRYPTION_FAILED, $result->get_error_code() ); + $this->assertNotNull( $result, 'A record copied under another name should not be reported as null.' ); + $this->assertWPError( $result, 'A record copied under another name should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_DECRYPTION_FAILED, $result->get_error_code(), 'A record copied under another name should fail decryption.' ); } /** @@ -145,9 +145,9 @@ public function test_key_unavailable_is_wp_error_not_null(): void { $result = wp_get_secret( 'myplugin/api-key' ); - $this->assertNotNull( $result ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code() ); + $this->assertNotNull( $result, 'A secret with an unusable WP_SECRETS_KEY should not be reported as null.' ); + $this->assertWPError( $result, 'A secret with an unusable WP_SECRETS_KEY should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code(), 'An unusable WP_SECRETS_KEY should produce the key unavailable error code.' ); } /** @@ -166,9 +166,9 @@ public function test_a_corrupted_wrapped_root_key_is_wp_error_not_null(): void { $result = wp_get_secret( 'myplugin/api-key' ); - $this->assertNotNull( $result ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code() ); + $this->assertNotNull( $result, 'A corrupted wrapped root key should not be reported as null.' ); + $this->assertWPError( $result, 'A corrupted wrapped root key should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code(), 'A corrupted wrapped root key should produce the key unavailable error code.' ); } /** @@ -186,18 +186,18 @@ public function test_record_missing_its_fingerprint_field_still_returns_a_secret $record = get_option( '_wp_secret_myplugin/api-key' ); - $this->assertIsArray( $record ); - $this->assertArrayHasKey( 'current', $record ); - $this->assertIsArray( $record['current'] ); + $this->assertIsArray( $record, 'The stored record should be an array.' ); + $this->assertArrayHasKey( 'current', $record, 'The stored record should have a current slot.' ); + $this->assertIsArray( $record['current'], 'The current slot should be an array.' ); unset( $record['current']['fingerprint'] ); update_option( '_wp_secret_myplugin/api-key', $record, false ); $result = wp_get_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $result ); - $this->assertSame( 'value', $result->reveal() ); - $this->assertNotSame( '', $result->fingerprint() ); + $this->assertInstanceOf( WP_Secret::class, $result, 'A record without a fingerprint field should still return a WP_Secret.' ); + $this->assertSame( 'value', $result->reveal(), 'A record without a fingerprint field should still decrypt to the stored value.' ); + $this->assertNotSame( '', $result->fingerprint(), 'The fingerprint should be recomputed when the record has none.' ); } /** @@ -211,22 +211,22 @@ public function test_fingerprint_is_recomputed_not_read_from_the_record(): void wp_set_secret( 'myplugin/api-key', 'value' ); $before = wp_get_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $before ); + $this->assertInstanceOf( WP_Secret::class, $before, 'The secret should be a WP_Secret before the fingerprint is tampered with.' ); $genuine = $before->fingerprint(); $record = get_option( '_wp_secret_myplugin/api-key' ); - $this->assertIsArray( $record ); - $this->assertArrayHasKey( 'current', $record ); - $this->assertIsArray( $record['current'] ); + $this->assertIsArray( $record, 'The stored record should be an array.' ); + $this->assertArrayHasKey( 'current', $record, 'The stored record should have a current slot.' ); + $this->assertIsArray( $record['current'], 'The current slot should be an array.' ); $record['current']['fingerprint'] = 'deadbeefdeadbeefdeadbeefdeadbeef'; update_option( '_wp_secret_myplugin/api-key', $record, false ); $after = wp_get_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $after ); - $this->assertSame( $genuine, $after->fingerprint() ); + $this->assertInstanceOf( WP_Secret::class, $after, 'The secret should be a WP_Secret after the fingerprint is tampered with.' ); + $this->assertSame( $genuine, $after->fingerprint(), 'The fingerprint should be recomputed rather than read from the record.' ); } /** @@ -239,8 +239,8 @@ public function test_exists_and_decrypts_is_a_wp_secret(): void { $result = wp_get_secret( 'myplugin/api-key' ); - $this->assertNotNull( $result ); - $this->assertNotWPError( $result ); - $this->assertInstanceOf( WP_Secret::class, $result ); + $this->assertNotNull( $result, 'An existing secret should not be reported as null.' ); + $this->assertNotWPError( $result, 'An existing secret should not be reported as a WP_Error.' ); + $this->assertInstanceOf( WP_Secret::class, $result, 'An existing secret should be returned as a WP_Secret.' ); } } diff --git a/tests/phpunit/tests/secrets/versionSlots.php b/tests/phpunit/tests/secrets/versionSlots.php index 69823ad4224e1..e62901468cd2c 100644 --- a/tests/phpunit/tests/secrets/versionSlots.php +++ b/tests/phpunit/tests/secrets/versionSlots.php @@ -21,9 +21,9 @@ class Tests_Secrets_VersionSlots extends WP_UnitTestCase { private function stored_slot( string $slot ): array { $record = get_option( '_wp_secret_myplugin/api-key' ); - $this->assertIsArray( $record ); - $this->assertArrayHasKey( $slot, $record ); - $this->assertIsArray( $record[ $slot ] ); + $this->assertIsArray( $record, 'The stored record should be an array.' ); + $this->assertArrayHasKey( $slot, $record, 'The stored record should contain the requested slot.' ); + $this->assertIsArray( $record[ $slot ], 'The requested slot of the stored record should be an array.' ); return $record[ $slot ]; } @@ -38,8 +38,8 @@ public function test_previous_returns_the_actual_prior_value(): void { wp_set_secret( 'myplugin/api-key', 'first-value' ); wp_set_secret( 'myplugin/api-key', 'second-value' ); - $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::PREVIOUS, 'first-value' ); - $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::CURRENT, 'second-value' ); + $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::PREVIOUS, 'first-value', false, 'The previous slot should decrypt to the first value.' ); + $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::CURRENT, 'second-value', false, 'The current slot should decrypt to the second value.' ); } /** @@ -53,11 +53,11 @@ public function test_third_write_discards_the_oldest_value(): void { wp_set_secret( 'myplugin/api-key', 'value-b' ); wp_set_secret( 'myplugin/api-key', 'value-c' ); - $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::PREVIOUS, 'value-b' ); + $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::PREVIOUS, 'value-b', false, 'The previous slot should decrypt to the second of three values.' ); // value-a is gone from the stored record entirely, not merely unreachable // through the two named slots. - $this->assertNeverContainsPlaintext( 'value-a', get_option( '_wp_secret_myplugin/api-key' ) ); + $this->assertNeverContainsPlaintext( 'value-a', get_option( '_wp_secret_myplugin/api-key' ), 'The stored record should no longer contain the oldest value.' ); } /** @@ -74,8 +74,8 @@ public function test_rewriting_the_current_value_keeps_the_previous_slot(): void wp_set_secret( 'myplugin/api-key', 'second-value' ); wp_set_secret( 'myplugin/api-key', 'second-value' ); - $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::PREVIOUS, 'first-value' ); - $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::CURRENT, 'second-value' ); + $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::PREVIOUS, 'first-value', false, 'Rewriting the current value should leave the previous slot holding the first value.' ); + $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::CURRENT, 'second-value', false, 'The current slot should still decrypt to the rewritten value.' ); } /** @@ -91,9 +91,9 @@ public function test_rewriting_the_current_value_leaves_the_stored_record_untouc wp_set_secret( 'myplugin/api-key', 'second-value' ); $before = get_option( '_wp_secret_myplugin/api-key' ); - $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'second-value' ) ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'second-value' ), 'Rewriting the current value should report success.' ); - $this->assertSame( $before, get_option( '_wp_secret_myplugin/api-key' ) ); + $this->assertSame( $before, get_option( '_wp_secret_myplugin/api-key' ), 'Rewriting the current value should leave the stored record unchanged.' ); } /** @@ -116,7 +116,7 @@ function () use ( &$fired ) { wp_set_secret( 'myplugin/api-key', 'value' ); - $this->assertFalse( $fired ); + $this->assertFalse( $fired, 'Rewriting the current value should not fire wp_secret_changed.' ); } /** @@ -133,7 +133,7 @@ public function test_rewriting_the_current_value_keeps_its_needs_rotation_flag() wp_set_secret( 'myplugin/api-key', 'imported-value' ); - $this->assertTrue( $this->stored_slot( WP_Secret_Version::CURRENT )['needs_rotation'] ); + $this->assertTrue( $this->stored_slot( WP_Secret_Version::CURRENT )['needs_rotation'], 'Rewriting an imported value should keep its needs_rotation flag.' ); } /** @@ -151,11 +151,11 @@ public function test_importing_the_current_value_flags_it_and_keeps_the_previous wp_set_secret( 'myplugin/api-key', 'second-value' ); update_option( 'my_plugin_api_key', 'second-value' ); - $this->assertTrue( wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ) ); + $this->assertTrue( wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ), 'Importing an option holding the current value should succeed.' ); - $this->assertTrue( $this->stored_slot( WP_Secret_Version::CURRENT )['needs_rotation'] ); - $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::PREVIOUS, 'first-value' ); - $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::CURRENT, 'second-value' ); + $this->assertTrue( $this->stored_slot( WP_Secret_Version::CURRENT )['needs_rotation'], 'The imported current value should be flagged as needing rotation.' ); + $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::PREVIOUS, 'first-value', false, 'Importing the current value should leave the previous slot holding the first value.' ); + $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::CURRENT, 'second-value', false, 'The current slot should still decrypt to the imported value.' ); } /** @@ -167,14 +167,14 @@ public function test_importing_the_current_value_flags_it_and_keeps_the_previous public function test_previous_preserves_its_original_fingerprint(): void { wp_set_secret( 'myplugin/api-key', 'first-value' ); $original = wp_get_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $original ); + $this->assertInstanceOf( WP_Secret::class, $original, 'The first value should be readable as a WP_Secret.' ); $original_fingerprint = $original->fingerprint(); wp_set_secret( 'myplugin/api-key', 'second-value' ); $previous = wp_get_secret( 'myplugin/api-key', WP_Secret_Version::PREVIOUS ); - $this->assertInstanceOf( WP_Secret::class, $previous ); - $this->assertSame( $original_fingerprint, $previous->fingerprint() ); + $this->assertInstanceOf( WP_Secret::class, $previous, 'The demoted value should be readable as a WP_Secret.' ); + $this->assertSame( $original_fingerprint, $previous->fingerprint(), 'The demoted value should keep its original fingerprint.' ); } /** @@ -191,7 +191,7 @@ public function test_previous_preserves_its_original_created_timestamp(): void { $demoted_created = $this->stored_slot( WP_Secret_Version::PREVIOUS )['created']; - $this->assertSame( $original_created, $demoted_created ); + $this->assertSame( $original_created, $demoted_created, 'The demoted value should keep its original created timestamp.' ); } /** @@ -208,15 +208,15 @@ public function test_previous_preserves_its_needs_rotation_flag(): void { * this test depends only on demotion carrying the flag forward. */ $record = get_option( '_wp_secret_myplugin/api-key' ); - $this->assertIsArray( $record ); - $this->assertArrayHasKey( 'current', $record ); - $this->assertIsArray( $record['current'] ); + $this->assertIsArray( $record, 'The stored record should be an array.' ); + $this->assertArrayHasKey( 'current', $record, 'The stored record should have a current slot.' ); + $this->assertIsArray( $record['current'], 'The current slot of the stored record should be an array.' ); $record['current']['needs_rotation'] = true; update_option( '_wp_secret_myplugin/api-key', $record, false ); wp_set_secret( 'myplugin/api-key', 'second-value' ); - $this->assertTrue( $this->stored_slot( WP_Secret_Version::PREVIOUS )['needs_rotation'] ); + $this->assertTrue( $this->stored_slot( WP_Secret_Version::PREVIOUS )['needs_rotation'], 'The demoted value should keep its needs_rotation flag.' ); } /** @@ -237,11 +237,11 @@ public function test_demotion_actually_reencrypts_rather_than_copying_ciphertext $demoted_ciphertext = $this->stored_slot( WP_Secret_Version::PREVIOUS )['ct']; - $this->assertNotSame( $original_ciphertext, $demoted_ciphertext ); + $this->assertNotSame( $original_ciphertext, $demoted_ciphertext, 'Demotion should re-encrypt the value rather than copy its ciphertext.' ); // And it must still actually decrypt to the original plaintext. $previous = wp_get_secret( 'myplugin/api-key', WP_Secret_Version::PREVIOUS ); - $this->assertInstanceOf( WP_Secret::class, $previous ); - $this->assertSame( 'first-value', $previous->reveal() ); + $this->assertInstanceOf( WP_Secret::class, $previous, 'The demoted value should be readable as a WP_Secret.' ); + $this->assertSame( 'first-value', $previous->reveal(), 'The demoted value should decrypt to the original plaintext.' ); } /** @@ -257,18 +257,18 @@ public function test_a_write_succeeds_even_if_the_outgoing_current_slot_cannot_b wp_set_secret( 'myplugin/api-key', 'value' ); $record = get_option( '_wp_secret_myplugin/api-key' ); - $this->assertIsArray( $record ); - $this->assertArrayHasKey( 'current', $record ); - $this->assertIsArray( $record['current'] ); + $this->assertIsArray( $record, 'The stored record should be an array.' ); + $this->assertArrayHasKey( 'current', $record, 'The stored record should have a current slot.' ); + $this->assertIsArray( $record['current'], 'The current slot of the stored record should be an array.' ); $record['current']['ct'] = base64_encode( 'not decryptable under any key' ); update_option( '_wp_secret_myplugin/api-key', $record, false ); - $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'new-value' ) ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'new-value' ), 'A write over an undecryptable current slot should succeed.' ); $current = wp_get_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $current ); - $this->assertSame( 'new-value', $current->reveal() ); + $this->assertInstanceOf( WP_Secret::class, $current, 'The new current value should be readable as a WP_Secret.' ); + $this->assertSame( 'new-value', $current->reveal(), 'The new current value should decrypt to the value just written.' ); // The undecryptable slot could not be demoted, so it is simply gone. - $this->assertNull( wp_get_secret( 'myplugin/api-key', WP_Secret_Version::PREVIOUS ) ); + $this->assertNull( wp_get_secret( 'myplugin/api-key', WP_Secret_Version::PREVIOUS ), 'An undecryptable current slot should not be demoted to the previous slot.' ); } /** @@ -280,12 +280,12 @@ public function test_retire_clears_previous_and_leaves_current_intact(): void { wp_set_secret( 'myplugin/api-key', 'first-value' ); wp_set_secret( 'myplugin/api-key', 'second-value' ); - $this->assertTrue( wp_retire_secret_version( 'myplugin/api-key' ) ); + $this->assertTrue( wp_retire_secret_version( 'myplugin/api-key' ), 'Retiring the previous version should succeed.' ); - $this->assertNull( wp_get_secret( 'myplugin/api-key', WP_Secret_Version::PREVIOUS ) ); + $this->assertNull( wp_get_secret( 'myplugin/api-key', WP_Secret_Version::PREVIOUS ), 'The previous version should be gone after retiring it.' ); $current = wp_get_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $current ); - $this->assertSame( 'second-value', $current->reveal() ); + $this->assertInstanceOf( WP_Secret::class, $current, 'The current version should still be readable as a WP_Secret.' ); + $this->assertSame( 'second-value', $current->reveal(), 'The current version should be unchanged by retiring the previous one.' ); } /** @@ -296,7 +296,7 @@ public function test_retire_clears_previous_and_leaves_current_intact(): void { public function test_retire_on_a_secret_with_no_previous_slot_is_a_successful_noop(): void { wp_set_secret( 'myplugin/api-key', 'value' ); - $this->assertTrue( wp_retire_secret_version( 'myplugin/api-key' ) ); + $this->assertTrue( wp_retire_secret_version( 'myplugin/api-key' ), 'Retiring with no previous version should report success.' ); } /** @@ -305,7 +305,7 @@ public function test_retire_on_a_secret_with_no_previous_slot_is_a_successful_no * @covers ::wp_retire_secret_version */ public function test_retire_on_a_never_set_secret_is_a_successful_noop(): void { - $this->assertTrue( wp_retire_secret_version( 'myplugin/never-set' ) ); + $this->assertTrue( wp_retire_secret_version( 'myplugin/never-set' ), 'Retiring a secret that was never set should report success.' ); } /** @@ -316,8 +316,8 @@ public function test_retire_on_a_never_set_secret_is_a_successful_noop(): void { public function test_retire_rejects_an_invalid_name(): void { $result = wp_retire_secret_version( 'Not A Valid Name' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code() ); + $this->assertWPError( $result, 'An invalid name should be rejected with a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code(), 'An invalid name should be rejected with WP_SECRETS_ERROR_INVALID_NAME.' ); } /** @@ -328,7 +328,7 @@ public function test_retire_rejects_an_invalid_name(): void { public function test_retire_fires_the_change_hook_with_the_retired_action(): void { wp_set_secret( 'myplugin/api-key', 'first-value' ); $original = wp_get_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $original ); + $this->assertInstanceOf( WP_Secret::class, $original, 'The first value should be readable as a WP_Secret.' ); $fingerprint_being_retired = $original->fingerprint(); wp_set_secret( 'myplugin/api-key', 'second-value' ); @@ -344,15 +344,15 @@ function ( ...$args ) use ( &$captured ) { wp_retire_secret_version( 'myplugin/api-key' ); - $this->assertIsArray( $captured ); - $this->assertCount( 7, $captured ); + $this->assertIsArray( $captured, 'wp_secret_changed should fire when the previous version is retired.' ); + $this->assertCount( 7, $captured, 'wp_secret_changed should be passed seven arguments.' ); list( $name, $action, , , $old_fingerprint, $new_fingerprint ) = $captured; - $this->assertSame( 'myplugin/api-key', $name ); - $this->assertSame( 'retired', $action ); - $this->assertSame( $fingerprint_being_retired, $old_fingerprint ); - $this->assertSame( '', $new_fingerprint ); + $this->assertSame( 'myplugin/api-key', $name, 'The change hook should report the name of the secret.' ); + $this->assertSame( 'retired', $action, 'The change hook should report the retired action.' ); + $this->assertSame( $fingerprint_being_retired, $old_fingerprint, 'The change hook should report the retired fingerprint as the old fingerprint.' ); + $this->assertSame( '', $new_fingerprint, 'The change hook should report an empty new fingerprint.' ); } /** @@ -373,6 +373,6 @@ function () use ( &$fired ) { wp_retire_secret_version( 'myplugin/api-key' ); - $this->assertFalse( $fired ); + $this->assertFalse( $fired, 'A no-op retire should not fire wp_secret_changed.' ); } } diff --git a/tests/phpunit/tests/secrets/wpDeleteSecret.php b/tests/phpunit/tests/secrets/wpDeleteSecret.php index b5a56fe41eea2..cbd280008af6a 100644 --- a/tests/phpunit/tests/secrets/wpDeleteSecret.php +++ b/tests/phpunit/tests/secrets/wpDeleteSecret.php @@ -16,8 +16,8 @@ class Tests_Secrets_WpDeleteSecret extends WP_UnitTestCase { public function test_deletes_an_existing_secret(): void { wp_set_secret( 'myplugin/api-key', 'value' ); - $this->assertTrue( wp_delete_secret( 'myplugin/api-key' ) ); - $this->assertNull( wp_get_secret( 'myplugin/api-key' ) ); + $this->assertTrue( wp_delete_secret( 'myplugin/api-key' ), 'Deleting an existing secret should return true.' ); + $this->assertNull( wp_get_secret( 'myplugin/api-key' ), 'A deleted secret should no longer be retrievable.' ); } /** @@ -26,7 +26,7 @@ public function test_deletes_an_existing_secret(): void { * @covers ::wp_delete_secret */ public function test_deleting_an_absent_secret_is_not_an_error(): void { - $this->assertTrue( wp_delete_secret( 'myplugin/never-set' ) ); + $this->assertTrue( wp_delete_secret( 'myplugin/never-set' ), 'Deleting an absent secret should return true.' ); } /** @@ -37,8 +37,8 @@ public function test_deleting_an_absent_secret_is_not_an_error(): void { public function test_rejects_an_invalid_name(): void { $result = wp_delete_secret( 'Not A Valid Name' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code() ); + $this->assertWPError( $result, 'An invalid name should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code(), 'An invalid name should use the invalid name error code.' ); } /** @@ -50,7 +50,7 @@ public function test_change_hook_fires_with_deleted_action(): void { wp_set_secret( 'myplugin/api-key', 'value' ); $secret = wp_get_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $secret ); + $this->assertInstanceOf( WP_Secret::class, $secret, 'The stored secret should be retrievable as a WP_Secret.' ); $fingerprint = $secret->fingerprint(); @@ -66,14 +66,14 @@ function ( ...$args ) use ( &$captured ) { wp_delete_secret( 'myplugin/api-key' ); - $this->assertIsArray( $captured ); + $this->assertIsArray( $captured, 'The wp_secret_changed hook should fire.' ); list( $name, $action, , , $old_fingerprint, $new_fingerprint ) = $captured; - $this->assertSame( 'myplugin/api-key', $name ); - $this->assertSame( 'deleted', $action ); - $this->assertSame( $fingerprint, $old_fingerprint ); - $this->assertSame( '', $new_fingerprint ); + $this->assertSame( 'myplugin/api-key', $name, 'The hook should receive the secret name.' ); + $this->assertSame( 'deleted', $action, 'The hook action should be deleted.' ); + $this->assertSame( $fingerprint, $old_fingerprint, 'The old fingerprint should match the deleted secret.' ); + $this->assertSame( '', $new_fingerprint, 'The new fingerprint should be empty after deletion.' ); } /** @@ -92,7 +92,7 @@ function () use ( &$fired ) { wp_delete_secret( 'myplugin/never-set' ); - $this->assertFalse( $fired ); + $this->assertFalse( $fired, 'The hook should not fire when nothing was deleted.' ); } /** @@ -105,8 +105,8 @@ function () use ( &$fired ) { public function test_a_corrupt_record_is_still_deletable(): void { update_option( '_wp_secret_myplugin/corrupt', 'not a record at all', false ); - $this->assertTrue( wp_delete_secret( 'myplugin/corrupt' ) ); - $this->assertNull( wp_get_secret( 'myplugin/corrupt' ) ); + $this->assertTrue( wp_delete_secret( 'myplugin/corrupt' ), 'Deleting a corrupt record should return true.' ); + $this->assertNull( wp_get_secret( 'myplugin/corrupt' ), 'A deleted corrupt record should no longer be retrievable.' ); } /** @@ -121,6 +121,6 @@ public function test_no_capability_check_is_applied(): void { wp_set_secret( 'myplugin/api-key', 'value' ); wp_set_current_user( 0 ); - $this->assertTrue( wp_delete_secret( 'myplugin/api-key' ) ); + $this->assertTrue( wp_delete_secret( 'myplugin/api-key' ), 'Deleting a secret without a logged-in user should succeed.' ); } } diff --git a/tests/phpunit/tests/secrets/wpImportOptionAsSecret.php b/tests/phpunit/tests/secrets/wpImportOptionAsSecret.php index 067d095e211e7..64cc2fc7694b6 100644 --- a/tests/phpunit/tests/secrets/wpImportOptionAsSecret.php +++ b/tests/phpunit/tests/secrets/wpImportOptionAsSecret.php @@ -16,12 +16,12 @@ class Tests_Secrets_WpImportOptionAsSecret extends WP_UnitTestCase { public function test_imports_an_existing_option_value(): void { update_option( 'my_plugin_api_key', 'sk_live_from_an_option' ); - $this->assertTrue( wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ) ); + $this->assertTrue( wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ), 'Importing an existing option should succeed.' ); $secret = wp_get_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $secret ); - $this->assertSame( 'sk_live_from_an_option', $secret->reveal() ); + $this->assertInstanceOf( WP_Secret::class, $secret, 'The imported secret should be a WP_Secret.' ); + $this->assertSame( 'sk_live_from_an_option', $secret->reveal(), 'The imported secret should decrypt to the option value.' ); } /** @@ -34,7 +34,7 @@ public function test_leaves_the_source_option_untouched(): void { wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ); - $this->assertSame( 'sk_live_from_an_option', get_option( 'my_plugin_api_key' ) ); + $this->assertSame( 'sk_live_from_an_option', get_option( 'my_plugin_api_key' ), 'The source option should be left unchanged.' ); } /** @@ -49,10 +49,10 @@ public function test_flags_the_imported_secret_for_rotation(): void { $record = get_option( '_wp_secret_myplugin/api-key' ); - $this->assertIsArray( $record ); - $this->assertArrayHasKey( 'current', $record ); - $this->assertIsArray( $record['current'] ); - $this->assertTrue( $record['current']['needs_rotation'] ); + $this->assertIsArray( $record, 'The stored record should be an array.' ); + $this->assertArrayHasKey( 'current', $record, 'The stored record should have a current slot.' ); + $this->assertIsArray( $record['current'], 'The current slot should be an array.' ); + $this->assertTrue( $record['current']['needs_rotation'], 'An imported secret should be flagged as needing rotation.' ); } /** @@ -69,10 +69,10 @@ public function test_an_ordinary_write_does_not_flag_needs_rotation(): void { $record = get_option( '_wp_secret_myplugin/api-key' ); - $this->assertIsArray( $record ); - $this->assertArrayHasKey( 'current', $record ); - $this->assertIsArray( $record['current'] ); - $this->assertFalse( $record['current']['needs_rotation'] ); + $this->assertIsArray( $record, 'The stored record should be an array.' ); + $this->assertArrayHasKey( 'current', $record, 'The stored record should have a current slot.' ); + $this->assertIsArray( $record['current'], 'The current slot should be an array.' ); + $this->assertFalse( $record['current']['needs_rotation'], 'An ordinary write should not be flagged as needing rotation.' ); } /** @@ -83,8 +83,8 @@ public function test_an_ordinary_write_does_not_flag_needs_rotation(): void { public function test_rejects_a_nonexistent_option(): void { $result = wp_import_option_as_secret( 'this_option_was_never_set', 'myplugin/api-key' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_VALUE, $result->get_error_code() ); + $this->assertWPError( $result, 'A nonexistent option should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_VALUE, $result->get_error_code(), 'A nonexistent option should produce the invalid value error code.' ); } /** @@ -97,8 +97,8 @@ public function test_rejects_a_non_string_option_value(): void { $result = wp_import_option_as_secret( 'my_plugin_settings', 'myplugin/api-key' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_VALUE, $result->get_error_code() ); + $this->assertWPError( $result, 'A non-string option value should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_VALUE, $result->get_error_code(), 'A non-string option value should produce the invalid value error code.' ); } /** @@ -111,8 +111,8 @@ public function test_rejects_an_invalid_destination_name(): void { $result = wp_import_option_as_secret( 'my_plugin_api_key', 'Not A Valid Name' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code() ); + $this->assertWPError( $result, 'An invalid destination name should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code(), 'An invalid destination name should produce the invalid name error code.' ); } /** @@ -135,11 +135,11 @@ function ( ...$args ) use ( &$captured ) { wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ); - $this->assertIsArray( $captured ); + $this->assertIsArray( $captured, 'The wp_secret_changed action should have fired.' ); list( $name, $action ) = $captured; - $this->assertSame( 'myplugin/api-key', $name ); - $this->assertSame( 'imported', $action ); + $this->assertSame( 'myplugin/api-key', $name, 'The hook should receive the destination secret name.' ); + $this->assertSame( 'imported', $action, 'The hook should receive the imported action.' ); } /** @@ -158,9 +158,9 @@ public function test_importing_over_an_existing_secret_demotes_it_like_any_write $current = wp_get_secret( 'myplugin/api-key' ); $previous = wp_get_secret( 'myplugin/api-key', WP_Secret_Version::PREVIOUS ); - $this->assertInstanceOf( WP_Secret::class, $current ); - $this->assertInstanceOf( WP_Secret::class, $previous ); - $this->assertSame( 'imported-value', $current->reveal() ); - $this->assertSame( 'original-value', $previous->reveal() ); + $this->assertInstanceOf( WP_Secret::class, $current, 'The current version should be a WP_Secret.' ); + $this->assertInstanceOf( WP_Secret::class, $previous, 'The previous version should be a WP_Secret.' ); + $this->assertSame( 'imported-value', $current->reveal(), 'The current version should decrypt to the imported value.' ); + $this->assertSame( 'original-value', $previous->reveal(), 'The previous version should decrypt to the original value.' ); } } diff --git a/tests/phpunit/tests/secrets/wpListSecrets.php b/tests/phpunit/tests/secrets/wpListSecrets.php index 04123dc4f9f30..0953d8a889cbb 100644 --- a/tests/phpunit/tests/secrets/wpListSecrets.php +++ b/tests/phpunit/tests/secrets/wpListSecrets.php @@ -14,7 +14,7 @@ class Tests_Secrets_WpListSecrets extends WP_UnitTestCase { * @covers ::wp_list_secrets */ public function test_returns_an_empty_array_when_nothing_is_set(): void { - $this->assertSame( array(), wp_list_secrets() ); + $this->assertSame( array(), wp_list_secrets(), 'An empty store should list no secrets.' ); } /** @@ -27,13 +27,14 @@ public function test_lists_every_secret_with_the_expected_keys(): void { $entries = wp_list_secrets(); - $this->assertIsArray( $entries ); - $this->assertCount( 1, $entries ); + $this->assertIsArray( $entries, 'wp_list_secrets() should return an array.' ); + $this->assertCount( 1, $entries, 'Exactly one secret should be listed.' ); $this->assertSame( array( 'name', 'fingerprint', 'created', 'has_previous', 'needs_rotation' ), - array_keys( $entries[0] ) + array_keys( $entries[0] ), + 'The entry should have exactly the documented metadata keys, in order.' ); - $this->assertSame( 'myplugin/api-key', $entries[0]['name'] ); + $this->assertSame( 'myplugin/api-key', $entries[0]['name'], 'The entry should carry the secret name.' ); } /** @@ -47,8 +48,8 @@ public function test_never_returns_a_value(): void { $dump = wp_json_encode( wp_list_secrets() ); - $this->assertIsString( $dump ); - $this->assertStringNotContainsString( 'a-plaintext-value-that-must-not-leak', $dump ); + $this->assertIsString( $dump, 'The listing should encode to a JSON string.' ); + $this->assertStringNotContainsString( 'a-plaintext-value-that-must-not-leak', $dump, 'The listing should never contain the plaintext value.' ); } /** @@ -62,9 +63,9 @@ public function test_fingerprint_matches_the_secrets_own_fingerprint(): void { $secret = wp_get_secret( 'myplugin/api-key' ); $entries = wp_list_secrets(); - $this->assertInstanceOf( WP_Secret::class, $secret ); - $this->assertIsArray( $entries ); - $this->assertSame( $secret->fingerprint(), $entries[0]['fingerprint'] ); + $this->assertInstanceOf( WP_Secret::class, $secret, 'The secret should be a WP_Secret.' ); + $this->assertIsArray( $entries, 'wp_list_secrets() should return an array.' ); + $this->assertSame( $secret->fingerprint(), $entries[0]['fingerprint'], 'The listed fingerprint should match the fingerprint of the secret.' ); } /** @@ -77,15 +78,15 @@ public function test_has_previous_is_false_before_a_rotation_and_true_after(): v $before = wp_list_secrets(); - $this->assertIsArray( $before ); - $this->assertFalse( $before[0]['has_previous'] ); + $this->assertIsArray( $before, 'wp_list_secrets() should return an array before the overwrite.' ); + $this->assertFalse( $before[0]['has_previous'], 'has_previous should be false before the secret is overwritten.' ); wp_set_secret( 'myplugin/api-key', 'second-value' ); $after = wp_list_secrets(); - $this->assertIsArray( $after ); - $this->assertTrue( $after[0]['has_previous'] ); + $this->assertIsArray( $after, 'wp_list_secrets() should return an array after the overwrite.' ); + $this->assertTrue( $after[0]['has_previous'], 'has_previous should be true after the secret is overwritten.' ); } /** @@ -101,17 +102,17 @@ public function test_needs_rotation_reflects_the_current_slots_flag(): void { $record = get_option( '_wp_secret_myplugin/api-key' ); - $this->assertIsArray( $record ); - $this->assertArrayHasKey( 'current', $record ); - $this->assertIsArray( $record['current'] ); + $this->assertIsArray( $record, 'The stored record should be an array.' ); + $this->assertArrayHasKey( 'current', $record, 'The stored record should have a current slot.' ); + $this->assertIsArray( $record['current'], 'The current slot should be an array.' ); $record['current']['needs_rotation'] = true; update_option( '_wp_secret_myplugin/api-key', $record, false ); $entries = wp_list_secrets(); - $this->assertIsArray( $entries ); - $this->assertTrue( $entries[0]['needs_rotation'] ); + $this->assertIsArray( $entries, 'wp_list_secrets() should return an array.' ); + $this->assertTrue( $entries[0]['needs_rotation'], 'needs_rotation should reflect the flag stored on the current slot.' ); } /** @@ -125,8 +126,8 @@ public function test_filters_by_namespace(): void { $entries = wp_list_secrets( 'pluginone' ); - $this->assertIsArray( $entries ); - $this->assertSame( array( 'pluginone/key' ), wp_list_pluck( $entries, 'name' ) ); + $this->assertIsArray( $entries, 'wp_list_secrets() should return an array.' ); + $this->assertSame( array( 'pluginone/key' ), wp_list_pluck( $entries, 'name' ), 'Only secrets in the requested namespace should be listed.' ); } /** @@ -140,8 +141,8 @@ public function test_empty_namespace_returns_everything(): void { $entries = wp_list_secrets( '' ); - $this->assertIsArray( $entries ); - $this->assertCount( 2, $entries ); + $this->assertIsArray( $entries, 'wp_list_secrets() should return an array.' ); + $this->assertCount( 2, $entries, 'An empty namespace should list secrets from every namespace.' ); } /** @@ -153,7 +154,7 @@ public function test_namespace_does_not_match_a_prefix_of_a_different_namespace( // 'plugin' must not match 'pluginone/key' – only a full "namespace/" prefix. wp_set_secret( 'pluginone/key', 'value' ); - $this->assertSame( array(), wp_list_secrets( 'plugin' ) ); + $this->assertSame( array(), wp_list_secrets( 'plugin' ), 'A namespace should not match a prefix of a different namespace.' ); } /** @@ -167,11 +168,11 @@ public function test_a_corrupt_record_is_still_listed_with_blank_metadata(): voi $entries = wp_list_secrets(); - $this->assertIsArray( $entries ); - $this->assertCount( 1, $entries ); - $this->assertSame( 'myplugin/corrupt', $entries[0]['name'] ); - $this->assertSame( '', $entries[0]['fingerprint'] ); - $this->assertFalse( $entries[0]['has_previous'] ); + $this->assertIsArray( $entries, 'wp_list_secrets() should return an array.' ); + $this->assertCount( 1, $entries, 'The corrupt record should still be listed.' ); + $this->assertSame( 'myplugin/corrupt', $entries[0]['name'], 'The corrupt record entry should carry its name.' ); + $this->assertSame( '', $entries[0]['fingerprint'], 'The corrupt record entry should have a blank fingerprint.' ); + $this->assertFalse( $entries[0]['has_previous'], 'The corrupt record entry should report no previous version.' ); } /** @@ -185,7 +186,7 @@ public function test_does_not_list_network_scope_secrets(): void { $entries = wp_list_secrets(); - $this->assertIsArray( $entries ); - $this->assertSame( array( 'myplugin/site-only' ), wp_list_pluck( $entries, 'name' ) ); + $this->assertIsArray( $entries, 'wp_list_secrets() should return an array.' ); + $this->assertSame( array( 'myplugin/site-only' ), wp_list_pluck( $entries, 'name' ), 'Only site-scope secrets should be listed.' ); } } diff --git a/tests/phpunit/tests/secrets/wpSecret.php b/tests/phpunit/tests/secrets/wpSecret.php index 7a13ae4f4278a..7263b972eae93 100644 --- a/tests/phpunit/tests/secrets/wpSecret.php +++ b/tests/phpunit/tests/secrets/wpSecret.php @@ -39,7 +39,7 @@ private function make_secret() { public function test_class_is_final(): void { $reflection = new ReflectionClass( WP_Secret::class ); - $this->assertTrue( $reflection->isFinal() ); + $this->assertTrue( $reflection->isFinal(), 'WP_Secret should be declared final.' ); } /** @@ -48,7 +48,7 @@ public function test_class_is_final(): void { * @coversNothing */ public function test_implements_json_serializable(): void { - $this->assertInstanceOf( JsonSerializable::class, $this->make_secret() ); + $this->assertInstanceOf( JsonSerializable::class, $this->make_secret(), 'WP_Secret should implement JsonSerializable.' ); } /** @@ -59,7 +59,7 @@ public function test_implements_json_serializable(): void { public function test_reveal_returns_the_exact_plaintext(): void { $secret = $this->make_secret(); - $this->assertSame( self::PLAINTEXT, $secret->reveal() ); + $this->assertSame( self::PLAINTEXT, $secret->reveal(), 'reveal() should return the plaintext the secret was constructed with.' ); } /** @@ -70,7 +70,7 @@ public function test_reveal_returns_the_exact_plaintext(): void { public function test_fingerprint_returns_the_exact_fingerprint(): void { $secret = $this->make_secret(); - $this->assertSame( self::FINGERPRINT, $secret->fingerprint() ); + $this->assertSame( self::FINGERPRINT, $secret->fingerprint(), 'fingerprint() should return the fingerprint the secret was constructed with.' ); } /** @@ -81,7 +81,7 @@ public function test_fingerprint_returns_the_exact_fingerprint(): void { public function test_get_name_returns_the_exact_name(): void { $secret = $this->make_secret(); - $this->assertSame( self::NAME, $secret->get_name() ); + $this->assertSame( self::NAME, $secret->get_name(), 'get_name() should return the name the secret was constructed with.' ); } /** @@ -133,8 +133,8 @@ public function test_masking_surfaces_never_contain_the_plaintext( $callback ): $output = $callback( $secret ); - $this->assertIsString( $output ); - $this->assertStringNotContainsString( self::PLAINTEXT, $output ); + $this->assertIsString( $output, 'The masking surface should render the secret as a string.' ); + $this->assertStringNotContainsString( self::PLAINTEXT, $output, 'The masking surface output should not contain the plaintext.' ); } /** @@ -196,7 +196,7 @@ function ( WP_Secret $secret ) { public function test_to_string_yields_the_masked_placeholder(): void { $secret = $this->make_secret(); - $this->assertSame( '[secret:' . self::NAME . ']', (string) $secret ); + $this->assertSame( '[secret:' . self::NAME . ']', (string) $secret, 'Casting to string should yield the masked placeholder.' ); } /** @@ -210,8 +210,8 @@ public function test_json_encode_yields_the_masked_placeholder(): void { // json_encode() escapes '/' by default; decode rather than compare raw JSON. $json = json_encode( $secret ); - $this->assertIsString( $json ); - $this->assertSame( '[secret:' . self::NAME . ']', json_decode( $json ) ); + $this->assertIsString( $json, 'json_encode() should return a JSON string.' ); + $this->assertSame( '[secret:' . self::NAME . ']', json_decode( $json ), 'The decoded JSON should be the masked placeholder.' ); } /** @@ -226,7 +226,7 @@ public function test_var_dump_yields_the_masked_placeholder(): void { var_dump( $secret ); $output = ob_get_clean(); - $this->assertStringContainsString( '[secret:' . self::NAME . ']', $output ); + $this->assertStringContainsString( '[secret:' . self::NAME . ']', $output, 'var_dump() output should contain the masked placeholder.' ); } /** @@ -311,15 +311,15 @@ public function test_destructing_the_last_reference_removes_it_from_the_vault(): $vault = $vault_property->getValue(); - $this->assertIsArray( $vault ); - $this->assertArrayHasKey( $id, $vault ); + $this->assertIsArray( $vault, 'The vault should be an array while the secret is referenced.' ); + $this->assertArrayHasKey( $id, $vault, 'The vault should hold the secret while it is referenced.' ); unset( $secret ); $vault = $vault_property->getValue(); - $this->assertIsArray( $vault ); - $this->assertArrayNotHasKey( $id, $vault ); + $this->assertIsArray( $vault, 'The vault should be an array after the secret is destroyed.' ); + $this->assertArrayNotHasKey( $id, $vault, 'The vault should not hold the secret after its last reference is released.' ); } /** @@ -366,7 +366,7 @@ public function test_nothing_plaintext_survives_a_refused_cache_write(): void { $cached = wp_cache_get( 'secret', 'secrets-test' ); - $this->assertNeverContainsPlaintext( self::PLAINTEXT, $cached ); + $this->assertNeverContainsPlaintext( self::PLAINTEXT, $cached, 'The cache should never hold the plaintext after a refused write.' ); } /** @@ -380,12 +380,12 @@ public function test_two_instances_do_not_share_a_vault_slot(): void { $a = new WP_Secret( 'plugin/a', 'value-a', 'fp-a' ); $b = new WP_Secret( 'plugin/b', 'value-b', 'fp-b' ); - $this->assertSame( 'value-a', $a->reveal() ); - $this->assertSame( 'value-b', $b->reveal() ); + $this->assertSame( 'value-a', $a->reveal(), 'The first secret should reveal its own plaintext.' ); + $this->assertSame( 'value-b', $b->reveal(), 'The second secret should reveal its own plaintext.' ); unset( $a ); - $this->assertSame( 'value-b', $b->reveal() ); + $this->assertSame( 'value-b', $b->reveal(), 'The second secret should still reveal its plaintext after the first is destroyed.' ); } // – withheld secrets (provider does not release the value) --------------- @@ -405,8 +405,8 @@ public function test_withheld_reveal_returns_the_providers_reason(): void { $revealed = $secret->reveal(); - $this->assertWPError( $revealed ); - $this->assertSame( 'provider_withholds_value', $revealed->get_error_code() ); + $this->assertWPError( $revealed, 'reveal() on a withheld secret should return a WP_Error.' ); + $this->assertSame( 'provider_withholds_value', $revealed->get_error_code(), 'reveal() should return the error code the provider gave.' ); } /** @@ -423,8 +423,8 @@ public function test_withheld_still_reports_name_and_fingerprint(): void { new WP_Error( 'provider_withholds_value', 'nope' ) ); - $this->assertSame( 'myplugin/signing-key', $secret->get_name() ); - $this->assertSame( 'abc123', $secret->fingerprint() ); + $this->assertSame( 'myplugin/signing-key', $secret->get_name(), 'A withheld secret should still report its name.' ); + $this->assertSame( 'abc123', $secret->fingerprint(), 'A withheld secret should still report its fingerprint.' ); } /** @@ -444,7 +444,7 @@ public function test_withheld_masks_like_any_other_secret(): void { $printed = print_r( $secret, true ); - $this->assertStringNotContainsString( 'UNIQUE-REASON-CANARY-4b1c', $printed ); - $this->assertStringContainsString( '[secret:myplugin/signing-key]', (string) $secret ); + $this->assertStringNotContainsString( 'UNIQUE-REASON-CANARY-4b1c', $printed, 'print_r() output should not contain the withheld reason.' ); + $this->assertStringContainsString( '[secret:myplugin/signing-key]', (string) $secret, 'Casting a withheld secret to string should yield the masked placeholder.' ); } } diff --git a/tests/phpunit/tests/secrets/wpSecretVersion.php b/tests/phpunit/tests/secrets/wpSecretVersion.php index 67832c63a5f34..e7e236cfe4ad7 100644 --- a/tests/phpunit/tests/secrets/wpSecretVersion.php +++ b/tests/phpunit/tests/secrets/wpSecretVersion.php @@ -12,9 +12,9 @@ class Tests_Secrets_WPSecretVersion extends WP_UnitTestCase { * @coversNothing */ public function test_current_and_previous_are_distinct_strings(): void { - $this->assertIsString( WP_Secret_Version::CURRENT ); - $this->assertIsString( WP_Secret_Version::PREVIOUS ); - $this->assertNotSame( WP_Secret_Version::CURRENT, WP_Secret_Version::PREVIOUS ); + $this->assertIsString( WP_Secret_Version::CURRENT, 'WP_Secret_Version::CURRENT should be a string.' ); + $this->assertIsString( WP_Secret_Version::PREVIOUS, 'WP_Secret_Version::PREVIOUS should be a string.' ); + $this->assertNotSame( WP_Secret_Version::CURRENT, WP_Secret_Version::PREVIOUS, 'CURRENT and PREVIOUS should hold different values.' ); } /** @@ -25,7 +25,7 @@ public function test_current_and_previous_are_distinct_strings(): void { public function test_class_is_final(): void { $reflection = new ReflectionClass( WP_Secret_Version::class ); - $this->assertTrue( $reflection->isFinal() ); + $this->assertTrue( $reflection->isFinal(), 'WP_Secret_Version should be declared final.' ); } /** @@ -36,7 +36,7 @@ public function test_class_is_final(): void { public function test_class_declares_no_constructor(): void { $reflection = new ReflectionClass( WP_Secret_Version::class ); - $this->assertNull( $reflection->getConstructor() ); + $this->assertNull( $reflection->getConstructor(), 'WP_Secret_Version should not declare a constructor.' ); } /** @@ -50,6 +50,6 @@ public function test_class_declares_no_constructor(): void { public function test_class_declares_exactly_two_constants(): void { $reflection = new ReflectionClass( WP_Secret_Version::class ); - $this->assertCount( 2, $reflection->getConstants() ); + $this->assertCount( 2, $reflection->getConstants(), 'WP_Secret_Version should declare exactly two constants.' ); } } diff --git a/tests/phpunit/tests/secrets/wpSecretsCipher.php b/tests/phpunit/tests/secrets/wpSecretsCipher.php index 400c1cd995eac..a91e7eecd29ea 100644 --- a/tests/phpunit/tests/secrets/wpSecretsCipher.php +++ b/tests/phpunit/tests/secrets/wpSecretsCipher.php @@ -47,11 +47,11 @@ public function test_round_trips_a_value(): void { $cipher = new WP_Secrets_Cipher(); $record = $cipher->encrypt_value( $this->master_key(), 'site', 1, self::NAME, WP_Secret_Version::CURRENT, 'sk_live_secret' ); - $this->assertIsArray( $record ); + $this->assertIsArray( $record, 'Encrypting a value should return a record array.' ); $plaintext = $cipher->decrypt_value( $this->master_key(), 'site', 1, self::NAME, WP_Secret_Version::CURRENT, $record ); - $this->assertSame( 'sk_live_secret', $plaintext ); + $this->assertSame( 'sk_live_secret', $plaintext, 'The record should decrypt to the original plaintext.' ); } /** @@ -66,7 +66,7 @@ public function test_round_trips_an_empty_string_value(): void { $plaintext = $cipher->decrypt_value( $this->master_key(), 'site', 1, self::NAME, WP_Secret_Version::CURRENT, $record ); - $this->assertSame( '', $plaintext ); + $this->assertSame( '', $plaintext, 'An empty string should round-trip to an empty string.' ); } /** @@ -81,7 +81,7 @@ public function test_round_trips_under_network_scope(): void { $plaintext = $cipher->decrypt_value( $this->master_key(), 'network', 0, self::NAME, WP_Secret_Version::CURRENT, $record ); - $this->assertSame( 'network-secret', $plaintext ); + $this->assertSame( 'network-secret', $plaintext, 'A network-scope record should decrypt to the original plaintext.' ); } /** @@ -94,8 +94,8 @@ public function test_encrypt_rejects_a_non_string_value(): void { $result = $cipher->encrypt_value( $this->master_key(), 'site', 1, self::NAME, WP_Secret_Version::CURRENT, array() ); // @phpstan-ignore argument.type (Intentionally passing a non-string plaintext.) - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_VALUE, $result->get_error_code() ); + $this->assertWPError( $result, 'Encrypting a non-string value should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_VALUE, $result->get_error_code(), 'A non-string value should be reported as an invalid value.' ); } /** @@ -112,8 +112,8 @@ public function test_encrypt_rejects_a_bad_master_key( $bad_key ): void { $result = $cipher->encrypt_value( $bad_key, 'site', 1, self::NAME, WP_Secret_Version::CURRENT, 'value' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code() ); + $this->assertWPError( $result, 'Encrypting with a bad master key should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code(), 'A bad master key should be reported as key unavailable.' ); } /** @@ -137,8 +137,8 @@ public function test_encrypt_propagates_an_invalid_name(): void { $result = $cipher->encrypt_value( $this->master_key(), 'site', 1, 'Not A Valid Name', WP_Secret_Version::CURRENT, 'value' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code() ); + $this->assertWPError( $result, 'Encrypting under an invalid name should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code(), 'An invalid name should be reported with the invalid name error code.' ); } /** @@ -157,8 +157,8 @@ public function test_encrypt_reports_an_invalid_scope_as_a_wp_error(): void { $result = $cipher->encrypt_value( $this->master_key(), 'bogus-scope', 1, self::NAME, WP_Secret_Version::CURRENT, 'value' ); // @phpstan-ignore argument.type (Intentionally passing an invalid value.) - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_ARGUMENT, $result->get_error_code() ); + $this->assertWPError( $result, 'An invalid scope should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_ARGUMENT, $result->get_error_code(), 'An invalid scope should be reported as an invalid argument.' ); } /** @@ -173,8 +173,8 @@ public function test_encrypt_reports_a_negative_site_id_as_a_wp_error(): void { $result = $cipher->encrypt_value( $this->master_key(), 'site', -1, self::NAME, WP_Secret_Version::CURRENT, 'value' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_ARGUMENT, $result->get_error_code() ); + $this->assertWPError( $result, 'A negative site ID should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_ARGUMENT, $result->get_error_code(), 'A negative site ID should be reported as an invalid argument.' ); } /** @@ -189,8 +189,8 @@ public function test_encrypt_reports_an_invalid_slot_as_a_wp_error(): void { $result = $cipher->encrypt_value( $this->master_key(), 'site', 1, self::NAME, 'not-a-real-slot', 'value' ); // @phpstan-ignore argument.type (Intentionally passing an invalid value.) - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_ARGUMENT, $result->get_error_code() ); + $this->assertWPError( $result, 'An invalid slot should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_ARGUMENT, $result->get_error_code(), 'An invalid slot should be reported as an invalid argument.' ); } /** @@ -215,8 +215,8 @@ public function test_decrypt_fails_when_context_does_not_match( $scope, $site_id $result = $cipher->decrypt_value( $this->master_key(), $scope, $site_id, $name, $slot, $record ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_DECRYPTION_FAILED, $result->get_error_code() ); + $this->assertWPError( $result, 'Decrypting under a mismatched context should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_DECRYPTION_FAILED, $result->get_error_code(), 'A mismatched context should be reported as a decryption failure.' ); } /** @@ -242,8 +242,8 @@ public function test_decrypt_fails_under_a_different_master_key(): void { $result = $cipher->decrypt_value( $this->master_key( 0x22 ), 'site', 1, self::NAME, WP_Secret_Version::CURRENT, $record ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_DECRYPTION_FAILED, $result->get_error_code() ); + $this->assertWPError( $result, 'Decrypting under a different master key should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_DECRYPTION_FAILED, $result->get_error_code(), 'A different master key should be reported as a decryption failure.' ); } /** @@ -262,12 +262,12 @@ public function test_decrypt_fails_when_a_field_is_tampered( $field ): void { $cipher = new WP_Secrets_Cipher(); $record = $cipher->encrypt_value( $this->master_key(), 'site', 1, self::NAME, WP_Secret_Version::CURRENT, 'value' ); - $this->assertIsArray( $record ); - $this->assertArrayHasKey( $field, $record ); + $this->assertIsArray( $record, 'Encrypting a value should return a record array.' ); + $this->assertArrayHasKey( $field, $record, 'The record should contain the field being tampered with.' ); $raw = base64_decode( $record[ $field ], true ); - $this->assertIsString( $raw ); + $this->assertIsString( $raw, 'The record field should be valid base64.' ); $last = strlen( $raw ) - 1; $raw[ $last ] = chr( ( ord( $raw[ $last ] ) + 1 ) % 256 ); @@ -275,7 +275,7 @@ public function test_decrypt_fails_when_a_field_is_tampered( $field ): void { $result = $cipher->decrypt_value( $this->master_key(), 'site', 1, self::NAME, WP_Secret_Version::CURRENT, $record ); - $this->assertWPError( $result ); + $this->assertWPError( $result, 'Decrypting a tampered record should return a WP_Error.' ); } /** @@ -304,8 +304,8 @@ public function test_decrypt_rejects_a_malformed_record( $record ): void { $result = $cipher->decrypt_value( $this->master_key(), 'site', 1, self::NAME, WP_Secret_Version::CURRENT, $record ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_RECORD_MALFORMED, $result->get_error_code() ); + $this->assertWPError( $result, 'Decrypting a malformed record should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_RECORD_MALFORMED, $result->get_error_code(), 'A malformed record should be reported as record malformed.' ); } /** @@ -354,11 +354,11 @@ public function test_data_key_independence(): void { $a = $cipher->encrypt_value( $this->master_key(), 'site', 1, self::NAME, WP_Secret_Version::CURRENT, 'same-value' ); $b = $cipher->encrypt_value( $this->master_key(), 'site', 1, self::NAME, WP_Secret_Version::CURRENT, 'same-value' ); - $this->assertIsArray( $a ); - $this->assertIsArray( $b ); + $this->assertIsArray( $a, 'The first encryption should return a record array.' ); + $this->assertIsArray( $b, 'The second encryption should return a record array.' ); - $this->assertNotSame( $a['dk'], $b['dk'] ); - $this->assertNotSame( $a['ct'], $b['ct'] ); + $this->assertNotSame( $a['dk'], $b['dk'], 'Each encryption should use a freshly wrapped data key.' ); + $this->assertNotSame( $a['ct'], $b['ct'], 'Encrypting the same value twice should produce different ciphertexts.' ); } /** @@ -373,13 +373,13 @@ public function test_nonce_uniqueness_across_many_writes(): void { for ( $i = 0; $i < 50; $i++ ) { $record = $cipher->encrypt_value( $this->master_key(), 'site', 1, self::NAME, WP_Secret_Version::CURRENT, 'value' ); - $this->assertIsArray( $record ); + $this->assertIsArray( $record, 'Each encryption should return a record array.' ); $nonces[] = $record['nonce']; $nonces[] = $record['dk_nonce']; } - $this->assertSame( count( $nonces ), count( array_unique( $nonces ) ) ); + $this->assertSame( count( $nonces ), count( array_unique( $nonces ) ), 'No value or data key nonce should be reused across writes.' ); } /** @@ -392,7 +392,8 @@ public function test_fingerprint_is_stable_for_the_same_inputs(): void { $this->assertSame( $cipher->fingerprint( $this->master_key(), 'same-value' ), - $cipher->fingerprint( $this->master_key(), 'same-value' ) + $cipher->fingerprint( $this->master_key(), 'same-value' ), + 'The same master key and plaintext should produce the same fingerprint.' ); } @@ -408,7 +409,8 @@ public function test_fingerprint_differs_across_master_keys(): void { $this->assertNotSame( $cipher->fingerprint( $this->master_key( 0x11 ), 'same-value' ), - $cipher->fingerprint( $this->master_key( 0x22 ), 'same-value' ) + $cipher->fingerprint( $this->master_key( 0x22 ), 'same-value' ), + 'The same plaintext should fingerprint differently under different master keys.' ); } @@ -422,7 +424,8 @@ public function test_fingerprint_differs_across_plaintexts(): void { $this->assertNotSame( $cipher->fingerprint( $this->master_key(), 'value-a' ), - $cipher->fingerprint( $this->master_key(), 'value-b' ) + $cipher->fingerprint( $this->master_key(), 'value-b' ), + 'Different plaintexts should produce different fingerprints.' ); } @@ -436,8 +439,8 @@ public function test_fingerprint_rejects_a_bad_master_key(): void { $result = $cipher->fingerprint( 'too-short', 'value' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code() ); + $this->assertWPError( $result, 'Fingerprinting with a bad master key should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code(), 'A bad master key should be reported as key unavailable.' ); } /** @@ -450,8 +453,8 @@ public function test_fingerprint_rejects_a_non_string_value(): void { $result = $cipher->fingerprint( $this->master_key(), array() ); // @phpstan-ignore argument.type (Intentionally passing a non-string plaintext.) - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_VALUE, $result->get_error_code() ); + $this->assertWPError( $result, 'Fingerprinting a non-string value should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_VALUE, $result->get_error_code(), 'A non-string value should be reported as an invalid value.' ); } /** @@ -468,7 +471,7 @@ public function test_fingerprint_known_answer_vector(): void { $fingerprint = $cipher->fingerprint( str_repeat( chr( 0x11 ), 32 ), 'sk_live_example_value' ); - $this->assertSame( '62d94d88bf417f09171e8efb7eb30297', $fingerprint ); + $this->assertSame( '62d94d88bf417f09171e8efb7eb30297', $fingerprint, 'The fingerprint should match the pinned known-answer vector.' ); } /** @@ -487,7 +490,7 @@ public function test_aad_format_known_answer(): void { array( WP_Secrets_Cipher::AAD_VALUE, 'site', 1, self::NAME, WP_Secret_Version::CURRENT ) ); - $this->assertSame( 'wp-secrets-value-v1|site|1|myplugin/api-key|current', $aad ); + $this->assertSame( 'wp-secrets-value-v1|site|1|myplugin/api-key|current', $aad, 'The AAD should match the pinned format.' ); } /** @@ -507,6 +510,6 @@ public function test_raw_aead_primitive_known_answer(): void { $aad = 'wp-secrets-value-v1|site|1|plugin/key|current'; $cipher = sodium_crypto_aead_xchacha20poly1305_ietf_encrypt( 'hello world', $aad, $nonce, $key ); - $this->assertSame( 'fa9f4801aae412e9d2746dddc65d7b3d5a689f4e89461caf54975b', bin2hex( $cipher ) ); + $this->assertSame( 'fa9f4801aae412e9d2746dddc65d7b3d5a689f4e89461caf54975b', bin2hex( $cipher ), 'The raw AEAD ciphertext should match the pinned known-answer vector.' ); } } diff --git a/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php b/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php index 74217662cf7ec..0763811b7ff7a 100644 --- a/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php +++ b/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php @@ -38,7 +38,7 @@ private function invoke_private( object $instance, string $method, array $args = * @coversNothing */ public function test_implements_the_keyring_interface(): void { - $this->assertInstanceOf( WP_Secrets_Keyring::class, new WP_Secrets_Config_Key_Provider() ); // @phpstan-ignore method.alreadyNarrowedType (Pins the interface the class declares, so removing it fails a test.) + $this->assertInstanceOf( WP_Secrets_Keyring::class, new WP_Secrets_Config_Key_Provider(), 'WP_Secrets_Config_Key_Provider should implement WP_Secrets_Keyring.' ); // @phpstan-ignore method.alreadyNarrowedType (Pins the interface the class declares, so removing it fails a test.) } /** @@ -52,10 +52,10 @@ public function test_wrap_then_unwrap_round_trips(): void { $material = random_bytes( 32 ); $wrapped = $provider->wrap( $material ); - $this->assertIsString( $wrapped ); + $this->assertIsString( $wrapped, 'wrap() should return a string.' ); $unwrapped = $provider->unwrap( $wrapped ); - $this->assertSame( $material, $unwrapped ); + $this->assertSame( $material, $unwrapped, 'unwrap() should return the original key material.' ); } /** @@ -68,8 +68,8 @@ public function test_wrap_rejects_an_empty_string(): void { $result = $provider->wrap( '' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_VALUE, $result->get_error_code() ); + $this->assertWPError( $result, 'Wrapping an empty string should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_VALUE, $result->get_error_code(), 'Wrapping an empty string should return the invalid value error code.' ); } /** @@ -81,7 +81,7 @@ public function test_two_wraps_of_the_same_material_produce_different_output(): $provider = new WP_Secrets_Config_Key_Provider(); $material = random_bytes( 32 ); - $this->assertNotSame( $provider->wrap( $material ), $provider->wrap( $material ) ); + $this->assertNotSame( $provider->wrap( $material ), $provider->wrap( $material ), 'Two wraps of the same key material should produce different output.' ); } /** @@ -94,8 +94,8 @@ public function test_unwrap_rejects_an_empty_string(): void { $result = $provider->unwrap( '' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code() ); + $this->assertWPError( $result, 'Unwrapping an empty string should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code(), 'Unwrapping an empty string should return the key unavailable error code.' ); } /** @@ -108,8 +108,8 @@ public function test_unwrap_rejects_garbage_base64(): void { $result = $provider->unwrap( 'not valid base64 at all!!!' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code() ); + $this->assertWPError( $result, 'Unwrapping invalid base64 should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code(), 'Unwrapping invalid base64 should return the key unavailable error code.' ); } /** @@ -122,8 +122,8 @@ public function test_unwrap_rejects_data_too_short_to_contain_a_nonce(): void { $result = $provider->unwrap( base64_encode( 'x' ) ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code() ); + $this->assertWPError( $result, 'Unwrapping data shorter than a nonce should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code(), 'Unwrapping data shorter than a nonce should return the key unavailable error code.' ); } /** @@ -134,10 +134,10 @@ public function test_unwrap_rejects_data_too_short_to_contain_a_nonce(): void { public function test_unwrap_rejects_a_tampered_ciphertext(): void { $provider = new WP_Secrets_Config_Key_Provider(); $wrapped = $provider->wrap( random_bytes( 32 ) ); - $this->assertIsString( $wrapped ); + $this->assertIsString( $wrapped, 'wrap() should return a string.' ); $raw = base64_decode( $wrapped, true ); - $this->assertIsString( $raw ); + $this->assertIsString( $raw, 'The wrapped value should be valid strict base64.' ); $tampered_raw = $raw; $last_byte = strlen( $tampered_raw ) - 1; @@ -145,8 +145,8 @@ public function test_unwrap_rejects_a_tampered_ciphertext(): void { $result = $provider->unwrap( base64_encode( $tampered_raw ) ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code() ); + $this->assertWPError( $result, 'Unwrapping a tampered ciphertext should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code(), 'Unwrapping a tampered ciphertext should return the key unavailable error code.' ); } /** @@ -165,7 +165,7 @@ public function test_get_key_source_reports_the_salt_fallback_when_wp_secrets_ke $provider = new WP_Secrets_Config_Key_Provider(); - $this->assertStringContainsString( 'LOGGED_IN_KEY', $provider->get_key_source() ); + $this->assertStringContainsString( 'LOGGED_IN_KEY', $provider->get_key_source(), 'The key source should name LOGGED_IN_KEY when WP_SECRETS_KEY is unset.' ); } /** @@ -181,7 +181,7 @@ public function test_get_key_source_reports_the_salt_fallback_when_wp_secrets_ke public function test_is_canonical_base64_32( $value, $expected ): void { $provider = new WP_Secrets_Config_Key_Provider(); - $this->assertSame( $expected, $this->invoke_private( $provider, 'is_canonical_base64_32', array( $value ) ) ); + $this->assertSame( $expected, $this->invoke_private( $provider, 'is_canonical_base64_32', array( $value ) ), 'is_canonical_base64_32() should return the expected result for this value.' ); } /** @@ -213,7 +213,7 @@ public static function data_canonical_base64_32(): array { public function test_are_usable_salt_values( $key, $salt, $expected ): void { $provider = new WP_Secrets_Config_Key_Provider(); - $this->assertSame( $expected, $this->invoke_private( $provider, 'are_usable_salt_values', array( $key, $salt ) ) ); + $this->assertSame( $expected, $this->invoke_private( $provider, 'are_usable_salt_values', array( $key, $salt ) ), 'are_usable_salt_values() should return the expected result for this pair.' ); } /** @@ -244,7 +244,7 @@ public function test_derives_raw_bytes_when_wp_secrets_key_is_canonical_base64_3 $provider = new WP_Secrets_Config_Key_Provider(); - $this->assertSame( $raw, $this->invoke_private( $provider, 'get_site_key' ) ); + $this->assertSame( $raw, $this->invoke_private( $provider, 'get_site_key' ), 'A canonical base64 WP_SECRETS_KEY should be used as the decoded raw bytes.' ); } /** @@ -264,10 +264,11 @@ public function test_derives_a_known_answer_via_the_legacy_interpretation(): voi $provider = new WP_Secrets_Config_Key_Provider(); $key = $this->invoke_private( $provider, 'get_site_key' ); - $this->assertIsString( $key ); + $this->assertIsString( $key, 'get_site_key() should return a string for a legacy WP_SECRETS_KEY.' ); $this->assertSame( 'db0aa0426b1dfaecc1878c103914462b0066eca0cdd050654a179588fed74b21', - bin2hex( $key ) + bin2hex( $key ), + 'The legacy site key should match the pinned known-answer vector.' ); } @@ -290,7 +291,8 @@ public function test_wrong_length_base64_falls_through_to_legacy_interpretation( $this->assertSame( sodium_crypto_generichash( $sixteen_bytes, '', 32 ), - $key + $key, + 'A wrong-length base64 WP_SECRETS_KEY should be hashed via the legacy interpretation.' ); } @@ -308,8 +310,8 @@ public function test_non_string_wp_secrets_key_is_unavailable(): void { $provider = new WP_Secrets_Config_Key_Provider(); $result = $this->invoke_private( $provider, 'get_site_key' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code() ); + $this->assertWPError( $result, 'A non-string WP_SECRETS_KEY should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code(), 'A non-string WP_SECRETS_KEY should return the key unavailable error code.' ); } /** @@ -325,7 +327,7 @@ public function test_get_key_source_reports_base64_form(): void { $provider = new WP_Secrets_Config_Key_Provider(); - $this->assertStringContainsString( 'base64', $provider->get_key_source() ); + $this->assertStringContainsString( 'base64', $provider->get_key_source(), 'The key source should identify a canonical base64 WP_SECRETS_KEY.' ); } /** @@ -341,7 +343,7 @@ public function test_get_key_source_reports_legacy_form(): void { $provider = new WP_Secrets_Config_Key_Provider(); - $this->assertStringContainsString( 'legacy', $provider->get_key_source() ); + $this->assertStringContainsString( 'legacy', $provider->get_key_source(), 'The key source should identify a legacy WP_SECRETS_KEY.' ); } /** @@ -358,7 +360,7 @@ public function test_use_previous_key_reads_the_previous_constant(): void { $provider = new WP_Secrets_Config_Key_Provider( true ); - $this->assertSame( str_repeat( 'C', 32 ), $this->invoke_private( $provider, 'get_site_key' ) ); + $this->assertSame( str_repeat( 'C', 32 ), $this->invoke_private( $provider, 'get_site_key' ), 'A previous-key provider should use the bytes from WP_SECRETS_KEY_PREVIOUS.' ); } /** @@ -380,8 +382,8 @@ public function test_previous_key_constant_does_not_leak_into_the_current_key_pa $provider = new WP_Secrets_Config_Key_Provider( false ); $key = $this->invoke_private( $provider, 'get_site_key' ); - $this->assertNotWPError( $key ); - $this->assertNotSame( str_repeat( 'C', 32 ), $key ); + $this->assertNotWPError( $key, 'The current-key provider should derive a site key from the salts.' ); + $this->assertNotSame( str_repeat( 'C', 32 ), $key, 'The current-key provider should not use WP_SECRETS_KEY_PREVIOUS.' ); } /** @@ -399,8 +401,8 @@ public function test_use_previous_key_without_the_constant_defined_is_unavailabl $provider = new WP_Secrets_Config_Key_Provider( true ); $result = $this->invoke_private( $provider, 'get_site_key' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code() ); + $this->assertWPError( $result, 'A previous-key provider without WP_SECRETS_KEY_PREVIOUS should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code(), 'Without WP_SECRETS_KEY_PREVIOUS, the previous-key provider should return key unavailable.' ); } /** @@ -421,9 +423,9 @@ public function test_old_and_new_key_providers_are_not_interchangeable(): void { $new_provider = new WP_Secrets_Config_Key_Provider( false ); $wrapped_under_old = $old_provider->wrap( random_bytes( 32 ) ); - $this->assertIsString( $wrapped_under_old ); + $this->assertIsString( $wrapped_under_old, 'The old provider should wrap to a string.' ); - $this->assertWPError( $new_provider->unwrap( $wrapped_under_old ) ); - $this->assertIsString( $old_provider->unwrap( $wrapped_under_old ) ); + $this->assertWPError( $new_provider->unwrap( $wrapped_under_old ), 'The new provider should not unwrap a value wrapped by the old provider.' ); + $this->assertIsString( $old_provider->unwrap( $wrapped_under_old ), 'The old provider should unwrap its own wrapped value.' ); } } diff --git a/tests/phpunit/tests/secrets/wpSecretsKeyManager.php b/tests/phpunit/tests/secrets/wpSecretsKeyManager.php index cacff47d0c17d..d0a72a8d7529f 100644 --- a/tests/phpunit/tests/secrets/wpSecretsKeyManager.php +++ b/tests/phpunit/tests/secrets/wpSecretsKeyManager.php @@ -16,13 +16,13 @@ class Tests_Secrets_WPSecretsKeyManager extends WP_UnitTestCase { public function test_get_root_key_generates_and_persists_one(): void { $manager = new WP_Secrets_Key_Manager(); - $this->assertFalse( get_site_option( WP_Secrets_Key_Manager::ROOT_KEY_OPTION ) ); + $this->assertFalse( get_site_option( WP_Secrets_Key_Manager::ROOT_KEY_OPTION ), 'No root key should be stored before the first get_root_key() call.' ); $root_key = $manager->get_root_key(); - $this->assertIsString( $root_key ); - $this->assertSame( 32, strlen( $root_key ) ); - $this->assertNotFalse( get_site_option( WP_Secrets_Key_Manager::ROOT_KEY_OPTION ) ); + $this->assertIsString( $root_key, 'get_root_key() should return a string.' ); + $this->assertSame( 32, strlen( $root_key ), 'The generated root key should be 32 bytes long.' ); + $this->assertNotFalse( get_site_option( WP_Secrets_Key_Manager::ROOT_KEY_OPTION ), 'The wrapped root key should be stored after the first get_root_key() call.' ); } /** @@ -33,7 +33,7 @@ public function test_get_root_key_generates_and_persists_one(): void { public function test_get_root_key_is_stable_on_the_same_instance(): void { $manager = new WP_Secrets_Key_Manager(); - $this->assertSame( $manager->get_root_key(), $manager->get_root_key() ); + $this->assertSame( $manager->get_root_key(), $manager->get_root_key(), 'Repeated get_root_key() calls on one instance should return the same bytes.' ); } /** @@ -48,7 +48,7 @@ public function test_get_root_key_persists_across_instances(): void { $second = new WP_Secrets_Key_Manager(); $root_b = $second->get_root_key(); - $this->assertSame( $root_a, $root_b ); + $this->assertSame( $root_a, $root_b, 'A second key manager should return the same root key as the first.' ); } /** @@ -64,7 +64,7 @@ public function test_get_root_key_uses_an_existing_value_rather_than_regeneratin $manager = new WP_Secrets_Key_Manager( $keyring ); - $this->assertSame( $known, $manager->get_root_key() ); + $this->assertSame( $known, $manager->get_root_key(), 'get_root_key() should return the pre-existing root key unchanged.' ); } /** @@ -75,11 +75,11 @@ public function test_get_root_key_uses_an_existing_value_rather_than_regeneratin public function test_get_master_key_matches_manual_derivation(): void { $manager = new WP_Secrets_Key_Manager(); $root_key = $manager->get_root_key(); - $this->assertIsString( $root_key ); + $this->assertIsString( $root_key, 'get_root_key() should return a string.' ); $expected = sodium_crypto_kdf_derive_from_key( 32, get_current_blog_id(), 'wpsecsit', $root_key ); - $this->assertSame( $expected, $manager->get_master_key( 'site' ) ); + $this->assertSame( $expected, $manager->get_master_key( 'site' ), 'The site master key should match a manual KDF derivation from the root key.' ); } /** @@ -92,7 +92,8 @@ public function test_get_master_key_differs_per_site_id(): void { $this->assertNotSame( $manager->get_master_key( 'site', 5 ), - $manager->get_master_key( 'site', 6 ) + $manager->get_master_key( 'site', 6 ), + 'Site-scope master keys for different site IDs should differ.' ); } @@ -106,7 +107,8 @@ public function test_get_master_key_site_and_network_scope_differ(): void { $this->assertNotSame( $manager->get_master_key( 'site', 1 ), - $manager->get_master_key( 'network' ) + $manager->get_master_key( 'network' ), + 'The network master key should differ from the site master key for site ID 1.' ); } @@ -120,7 +122,8 @@ public function test_get_master_key_network_scope_is_stable(): void { $this->assertSame( $manager->get_master_key( 'network' ), - $manager->get_master_key( 'network' ) + $manager->get_master_key( 'network' ), + 'Repeated network master key derivations should return the same bytes.' ); } @@ -134,7 +137,8 @@ public function test_get_master_key_defaults_site_id_to_the_current_blog(): void $this->assertSame( $manager->get_master_key( 'site' ), - $manager->get_master_key( 'site', get_current_blog_id() ) + $manager->get_master_key( 'site', get_current_blog_id() ), + 'A site master key without a site ID should match the one for the current blog.' ); } @@ -150,8 +154,8 @@ public function test_get_master_key_reports_an_invalid_scope_as_a_wp_error(): vo $result = $manager->get_master_key( 'bogus' ); // @phpstan-ignore argument.type (Intentionally passing an invalid value.) - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_ARGUMENT, $result->get_error_code() ); + $this->assertWPError( $result, 'An invalid scope should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_ARGUMENT, $result->get_error_code(), 'An invalid scope should return the invalid argument error code.' ); } /** @@ -170,8 +174,8 @@ public function test_get_master_key_reports_an_invalid_site_id_as_a_wp_error( $s $result = $manager->get_master_key( 'site', $site_id ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_ARGUMENT, $result->get_error_code() ); + $this->assertWPError( $result, 'An invalid site ID should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_ARGUMENT, $result->get_error_code(), 'An invalid site ID should return the invalid argument error code.' ); } /** @@ -207,7 +211,7 @@ public function test_network_scope_master_key_is_identical_across_blogs(): void $network_key_on_blog_2 = ( new WP_Secrets_Key_Manager() )->get_master_key( 'network' ); restore_current_blog(); - $this->assertSame( $network_key_on_blog_1, $network_key_on_blog_2 ); + $this->assertSame( $network_key_on_blog_1, $network_key_on_blog_2, 'The network master key should be identical on both blogs.' ); } /** @@ -230,7 +234,7 @@ public function test_site_scope_master_key_differs_across_blogs(): void { $site_key_on_blog_2 = ( new WP_Secrets_Key_Manager() )->get_master_key( 'site' ); restore_current_blog(); - $this->assertNotSame( $site_key_on_blog_1, $site_key_on_blog_2 ); + $this->assertNotSame( $site_key_on_blog_1, $site_key_on_blog_2, 'The site master key should differ between blogs.' ); } /** @@ -260,11 +264,11 @@ public function test_get_root_key_adopts_a_pre_conversion_root_key(): void { $fresh_manager = new WP_Secrets_Key_Manager(); $adopted_key = $fresh_manager->get_root_key(); - $this->assertIsString( $root_key ); - $this->assertIsString( $adopted_key ); - $this->assertTrue( hash_equals( $root_key, $adopted_key ) ); - $this->assertNotFalse( get_site_option( WP_Secrets_Key_Manager::ROOT_KEY_OPTION ) ); - $this->assertFalse( get_blog_option( $main_site_id, WP_Secrets_Key_Manager::ROOT_KEY_OPTION ) ); + $this->assertIsString( $root_key, 'The original root key should be a string.' ); + $this->assertIsString( $adopted_key, 'The adopted root key should be a string.' ); + $this->assertTrue( hash_equals( $root_key, $adopted_key ), 'The adopted root key should match the pre-conversion root key.' ); + $this->assertNotFalse( get_site_option( WP_Secrets_Key_Manager::ROOT_KEY_OPTION ), 'The adopted root key should be stored in sitemeta.' ); + $this->assertFalse( get_blog_option( $main_site_id, WP_Secrets_Key_Manager::ROOT_KEY_OPTION ), 'The main-site option row should be removed after adoption.' ); } /** @@ -281,7 +285,7 @@ public function test_secret_written_before_conversion_still_decrypts(): void { $main_site_id = get_main_site_id(); - $this->assertTrue( wp_set_secret( 'secrets-api/pre-conversion', 'shh' ) ); + $this->assertTrue( wp_set_secret( 'secrets-api/pre-conversion', 'shh' ), 'Storing the secret before conversion should succeed.' ); $wrapped = get_site_option( WP_Secrets_Key_Manager::ROOT_KEY_OPTION ); delete_site_option( WP_Secrets_Key_Manager::ROOT_KEY_OPTION ); @@ -289,9 +293,9 @@ public function test_secret_written_before_conversion_still_decrypts(): void { $secret = wp_get_secret( 'secrets-api/pre-conversion' ); - $this->assertNotWPError( $secret ); - $this->assertInstanceOf( WP_Secret::class, $secret ); - $this->assertSame( 'shh', $secret->reveal() ); + $this->assertNotWPError( $secret, 'Reading the secret after conversion should not return a WP_Error.' ); + $this->assertInstanceOf( WP_Secret::class, $secret, 'The secret read after conversion should be a WP_Secret.' ); + $this->assertSame( 'shh', $secret->reveal(), 'The secret should reveal its original value after conversion.' ); } /** @@ -319,12 +323,12 @@ public function test_rotate_site_key_works_after_conversion_before_any_read(): v $fresh_manager = new WP_Secrets_Key_Manager( $right_keyring ); $rotated = $fresh_manager->rotate_site_key( $right_keyring, $right_keyring ); - $this->assertNotWPError( $rotated ); - $this->assertTrue( $rotated ); + $this->assertNotWPError( $rotated, 'Rotating after conversion should not return a WP_Error.' ); + $this->assertTrue( $rotated, 'Rotating after conversion should return true.' ); $master_after = $fresh_manager->get_master_key( 'site' ); - $this->assertSame( $master_before, $master_after ); + $this->assertSame( $master_before, $master_after, 'The site master key should be unchanged by rotation after conversion.' ); } /** @@ -338,8 +342,8 @@ public function test_rotate_fails_when_no_root_key_exists(): void { $result = $manager->rotate_site_key( $keyring, $keyring ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_STORE_UNAVAILABLE, $result->get_error_code() ); + $this->assertWPError( $result, 'Rotating without a stored root key should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_STORE_UNAVAILABLE, $result->get_error_code(), 'Rotating without a stored root key should return the store unavailable error code.' ); } /** @@ -379,7 +383,7 @@ public function get_key_source(): string { $result = $manager->rotate_site_key( $wrong_keyring, $right_keyring ); - $this->assertWPError( $result ); + $this->assertWPError( $result, 'Rotating with an old keyring that cannot unwrap should return a WP_Error.' ); } /** @@ -407,19 +411,19 @@ public function test_rotation_does_not_change_any_derived_master_key(): void { $master_before = $manager_under_old_key->get_master_key( 'site', 7 ); $rotated = $manager_under_old_key->rotate_site_key( $old_keyring, $new_keyring ); - $this->assertNotWPError( $rotated ); + $this->assertNotWPError( $rotated, 'Rotating from the old keyring to the new one should not return a WP_Error.' ); $manager_under_new_key = new WP_Secrets_Key_Manager( $new_keyring ); $master_after = $manager_under_new_key->get_master_key( 'site', 7 ); - $this->assertSame( $master_before, $master_after ); + $this->assertSame( $master_before, $master_after, 'The derived master key should be unchanged by rotation.' ); // The old keyring alone is no longer sufficient: the stored root key is now // wrapped under the new key. Checked with a fresh manager instance, since // $manager_under_old_key's own cache was correctly primed by the rotation // it just performed and is not the thing under test here. $fresh_manager_under_old_key = new WP_Secrets_Key_Manager( $old_keyring ); - $this->assertWPError( $fresh_manager_under_old_key->get_root_key() ); + $this->assertWPError( $fresh_manager_under_old_key->get_root_key(), 'The old keyring alone should no longer unwrap the rotated root key.' ); } /** @@ -440,15 +444,15 @@ public function test_unwrap_is_called_once_across_repeated_master_key_derivation for ( $i = 0; $i < 5; $i++ ) { $site_key = $manager->get_master_key( 'site', $i + 1 ); - $this->assertIsString( $site_key ); - $this->assertSame( 32, strlen( $site_key ) ); + $this->assertIsString( $site_key, 'Each site master key should be a string.' ); + $this->assertSame( 32, strlen( $site_key ), 'Each site master key should be 32 bytes long.' ); $network_key = $manager->get_master_key( 'network' ); - $this->assertIsString( $network_key ); - $this->assertSame( 32, strlen( $network_key ) ); + $this->assertIsString( $network_key, 'Each network master key should be a string.' ); + $this->assertSame( 32, strlen( $network_key ), 'Each network master key should be 32 bytes long.' ); } - $this->assertSame( 1, $mock->unwrap_call_count() ); + $this->assertSame( 1, $mock->unwrap_call_count(), 'The root key should be unwrapped only once across all derivations.' ); } /** @@ -469,15 +473,15 @@ public function test_unwrap_is_called_once_across_many_secret_reads(): void { $GLOBALS['wp_secrets_keyring'] = $mock; - $this->assertNotWPError( wp_set_secret( 'conformance/root-key-cache', 'the-value' ) ); + $this->assertNotWPError( wp_set_secret( 'conformance/root-key-cache', 'the-value' ), 'Storing the secret should not return a WP_Error.' ); for ( $i = 0; $i < 10; $i++ ) { $secret = wp_get_secret( 'conformance/root-key-cache' ); - $this->assertInstanceOf( 'WP_Secret', $secret ); - $this->assertSame( 'the-value', $secret->reveal() ); + $this->assertInstanceOf( 'WP_Secret', $secret, 'Each read should return a WP_Secret.' ); + $this->assertSame( 'the-value', $secret->reveal(), 'Each read should reveal the stored value.' ); } - $this->assertSame( 1, $mock->unwrap_call_count() ); + $this->assertSame( 1, $mock->unwrap_call_count(), 'The root key should be unwrapped only once across all secret reads.' ); } /** @@ -495,11 +499,11 @@ public function test_rotate_site_key_updates_the_cache_without_another_unwrap(): $manager = new WP_Secrets_Key_Manager( $mock ); $root_key = $manager->get_root_key(); - $this->assertNotWPError( $manager->rotate_site_key( $mock, $second_mock ) ); + $this->assertNotWPError( $manager->rotate_site_key( $mock, $second_mock ), 'Rotating the site key should not return a WP_Error.' ); - $this->assertSame( $root_key, $manager->get_root_key() ); - $this->assertSame( 1, $mock->unwrap_call_count() ); - $this->assertSame( 0, $second_mock->unwrap_call_count() ); + $this->assertSame( $root_key, $manager->get_root_key(), 'The cached root key should be unchanged after rotation.' ); + $this->assertSame( 1, $mock->unwrap_call_count(), 'The original keyring should have unwrapped only once.' ); + $this->assertSame( 0, $second_mock->unwrap_call_count(), 'The new keyring should not have been asked to unwrap.' ); } /** @@ -517,12 +521,12 @@ public function test_a_changed_wrapped_value_is_unwrapped_again_rather_than_serv update_site_option( WP_Secrets_Key_Manager::ROOT_KEY_OPTION, $mock->wrap( $root ) ); $manager = new WP_Secrets_Key_Manager( $mock ); - $this->assertSame( $root, $manager->get_root_key() ); + $this->assertSame( $root, $manager->get_root_key(), 'get_root_key() should return the initially stored root key.' ); update_site_option( WP_Secrets_Key_Manager::ROOT_KEY_OPTION, $mock->wrap( $other_root ) ); - $this->assertSame( $other_root, $manager->get_root_key() ); - $this->assertSame( 2, $mock->unwrap_call_count() ); + $this->assertSame( $other_root, $manager->get_root_key(), 'get_root_key() should return the new root key after the stored value changes.' ); + $this->assertSame( 2, $mock->unwrap_call_count(), 'The changed wrapped value should trigger a second unwrap.' ); } /** @@ -542,15 +546,15 @@ public function test_an_unwrap_error_is_not_cached(): void { // same expression as far as a reader (or an analyzer) should assume. $mock->configure_fail_unwrap( true ); $while_failing = $manager->get_root_key(); - $this->assertWPError( $while_failing ); + $this->assertWPError( $while_failing, 'get_root_key() should return a WP_Error while unwrap fails.' ); $mock->configure_fail_unwrap( false ); $after_recovery = $manager->get_root_key(); - $this->assertSame( $root, $after_recovery ); + $this->assertSame( $root, $after_recovery, 'get_root_key() should return the root key once unwrap recovers.' ); $from_cache = $manager->get_root_key(); - $this->assertSame( $root, $from_cache ); - $this->assertSame( 2, $mock->unwrap_call_count() ); + $this->assertSame( $root, $from_cache, 'get_root_key() should return the root key from cache after recovery.' ); + $this->assertSame( 2, $mock->unwrap_call_count(), 'The root key should be unwrapped once for the failure and once for the recovery.' ); } /** @@ -566,8 +570,8 @@ public function test_generate_root_key_primes_the_cache(): void { $manager->get_root_key(); $manager->get_master_key( 'site' ); - $this->assertSame( 0, $mock->unwrap_call_count() ); - $this->assertSame( 1, $mock->wrap_call_count() ); + $this->assertSame( 0, $mock->unwrap_call_count(), 'A newly generated root key should not need unwrapping.' ); + $this->assertSame( 1, $mock->wrap_call_count(), 'The newly generated root key should be wrapped exactly once.' ); } /** @@ -586,10 +590,10 @@ public function test_the_returned_root_key_is_a_copy_the_caller_can_zero(): void $manager = new WP_Secrets_Key_Manager( $mock ); $copy = $manager->get_root_key(); - $this->assertIsString( $copy ); + $this->assertIsString( $copy, 'get_root_key() should return a string.' ); wp_secrets_memzero( $copy ); - $this->assertSame( $root, $manager->get_root_key() ); - $this->assertSame( 1, $mock->unwrap_call_count() ); + $this->assertSame( $root, $manager->get_root_key(), 'Zeroing the returned copy should not wipe the cached root key.' ); + $this->assertSame( 1, $mock->unwrap_call_count(), 'The cached root key should be served without another unwrap.' ); } } diff --git a/tests/phpunit/tests/secrets/wpSecretsMemzero.php b/tests/phpunit/tests/secrets/wpSecretsMemzero.php index afa2d2f822aef..8da51bdad50ec 100644 --- a/tests/phpunit/tests/secrets/wpSecretsMemzero.php +++ b/tests/phpunit/tests/secrets/wpSecretsMemzero.php @@ -16,8 +16,8 @@ public function test_clears_a_plaintext_string(): void { wp_secrets_memzero( $value ); - $this->assertNotSame( 'a plaintext value', $value ); - $this->assertSame( '', $value ); + $this->assertNotSame( 'a plaintext value', $value, 'The original plaintext should no longer be in the variable.' ); + $this->assertSame( '', $value, 'The variable should be an empty string after zeroing.' ); } /** @@ -30,7 +30,7 @@ public function test_leaves_non_string_values_untouched(): void { wp_secrets_memzero( $value ); // @phpstan-ignore argument.type (Intentionally passing a non-string value.) - $this->assertSame( 42, $value ); + $this->assertSame( 42, $value, 'A non-string value should be left unchanged.' ); } /** @@ -43,7 +43,7 @@ public function test_leaves_an_empty_string_untouched(): void { wp_secrets_memzero( $value ); - $this->assertSame( '', $value ); + $this->assertSame( '', $value, 'An empty string should remain an empty string.' ); } /** @@ -57,9 +57,9 @@ public function test_clears_the_variable_and_leaves_a_shared_copy_untouched(): v wp_secrets_memzero( $value ); - $this->assertSame( '', $value ); + $this->assertSame( '', $value, 'The zeroed variable should be an empty string.' ); // The shared copy is unaffected – see the docblock on wp_secrets_memzero(): // this is hygiene, not a guarantee, for exactly this reason. - $this->assertSame( 'shared plaintext', $copy ); // @phpstan-ignore method.alreadyNarrowedType (Whether the copy survives the scrub is decided by the engine at runtime, not by the types.) + $this->assertSame( 'shared plaintext', $copy, 'The shared copy should keep its original value.' ); // @phpstan-ignore method.alreadyNarrowedType (Whether the copy survives the scrub is decided by the engine at runtime, not by the types.) } } diff --git a/tests/phpunit/tests/secrets/wpSecretsOptionStore.php b/tests/phpunit/tests/secrets/wpSecretsOptionStore.php index 3e42c815c206c..c8a74dda8ab65 100644 --- a/tests/phpunit/tests/secrets/wpSecretsOptionStore.php +++ b/tests/phpunit/tests/secrets/wpSecretsOptionStore.php @@ -33,7 +33,7 @@ private function sample_record(): array { * @coversNothing */ public function test_implements_the_store_interface(): void { - $this->assertInstanceOf( WP_Secrets_Store::class, new WP_Secrets_Option_Store() ); // @phpstan-ignore method.alreadyNarrowedType (Pins the interface the class declares, so removing it fails a test.) + $this->assertInstanceOf( WP_Secrets_Store::class, new WP_Secrets_Option_Store(), 'WP_Secrets_Option_Store should implement WP_Secrets_Store.' ); // @phpstan-ignore method.alreadyNarrowedType (Pins the interface the class declares, so removing it fails a test.) } /** @@ -44,7 +44,7 @@ public function test_implements_the_store_interface(): void { public function test_get_returns_null_for_an_absent_secret(): void { $store = new WP_Secrets_Option_Store(); - $this->assertNull( $store->get( 'myplugin/absent' ) ); + $this->assertNull( $store->get( 'myplugin/absent' ), 'An absent secret should be returned as null.' ); } /** @@ -57,8 +57,8 @@ public function test_set_then_get_round_trips_a_record_site_scope(): void { $store = new WP_Secrets_Option_Store(); $record = $this->sample_record(); - $this->assertTrue( $store->set( 'myplugin/key', $record ) ); - $this->assertSame( $record, $store->get( 'myplugin/key' ) ); + $this->assertTrue( $store->set( 'myplugin/key', $record ), 'Storing a site-scope record should succeed.' ); + $this->assertSame( $record, $store->get( 'myplugin/key' ), 'The site-scope record should be returned unchanged.' ); } /** @@ -71,8 +71,8 @@ public function test_set_then_get_round_trips_a_record_network_scope(): void { $store = new WP_Secrets_Option_Store(); $record = $this->sample_record(); - $this->assertTrue( $store->set( 'myplugin/key', $record, true ) ); - $this->assertSame( $record, $store->get( 'myplugin/key', true ) ); + $this->assertTrue( $store->set( 'myplugin/key', $record, true ), 'Storing a network-scope record should succeed.' ); + $this->assertSame( $record, $store->get( 'myplugin/key', true ), 'The network-scope record should be returned unchanged.' ); } /** @@ -89,8 +89,8 @@ public function test_site_and_network_scope_do_not_collide(): void { $store->set( 'myplugin/key', $site_record, false ); $store->set( 'myplugin/key', $network_record, true ); - $this->assertSame( $site_record, $store->get( 'myplugin/key', false ) ); - $this->assertSame( $network_record, $store->get( 'myplugin/key', true ) ); + $this->assertSame( $site_record, $store->get( 'myplugin/key', false ), 'The site-scope record should not be overwritten by the network-scope record.' ); + $this->assertSame( $network_record, $store->get( 'myplugin/key', true ), 'The network-scope record should be stored separately from the site-scope record.' ); } /** @@ -105,8 +105,8 @@ public function test_get_returns_an_error_when_the_stored_value_is_not_an_array( $result = $store->get( 'myplugin/key' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_RECORD_MALFORMED, $result->get_error_code() ); + $this->assertWPError( $result, 'A non-array stored value should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_RECORD_MALFORMED, $result->get_error_code(), 'A non-array stored value should produce the malformed record error code.' ); } /** @@ -118,8 +118,8 @@ public function test_delete_removes_an_existing_record(): void { $store = new WP_Secrets_Option_Store(); $store->set( 'myplugin/key', $this->sample_record() ); - $this->assertTrue( $store->delete( 'myplugin/key' ) ); - $this->assertNull( $store->get( 'myplugin/key' ) ); + $this->assertTrue( $store->delete( 'myplugin/key' ), 'Deleting an existing record should succeed.' ); + $this->assertNull( $store->get( 'myplugin/key' ), 'A deleted record should no longer be returned.' ); } /** @@ -130,7 +130,7 @@ public function test_delete_removes_an_existing_record(): void { public function test_delete_on_an_absent_record_is_not_an_error(): void { $store = new WP_Secrets_Option_Store(); - $this->assertTrue( $store->delete( 'myplugin/never-existed' ) ); + $this->assertTrue( $store->delete( 'myplugin/never-existed' ), 'Deleting an absent record should report success.' ); } /** @@ -156,7 +156,7 @@ public function test_site_scope_records_are_not_autoloaded(): void { ) ); - $this->assertContains( $autoload, array( 'no', 'off' ) ); + $this->assertContains( $autoload, array( 'no', 'off' ), 'Site-scope secret records should not be autoloaded.' ); } /** @@ -171,9 +171,9 @@ public function test_list_names_returns_stored_names_without_the_prefix(): void $names = $store->list_names(); - $this->assertIsArray( $names ); - $this->assertContains( 'myplugin/one', $names ); - $this->assertContains( 'myplugin/two', $names ); + $this->assertIsArray( $names, 'list_names() should return an array.' ); + $this->assertContains( 'myplugin/one', $names, 'The first stored name should be listed without the prefix.' ); + $this->assertContains( 'myplugin/two', $names, 'The second stored name should be listed without the prefix.' ); } /** @@ -189,8 +189,8 @@ public function test_list_names_does_not_include_unrelated_options(): void { $names = $store->list_names(); - $this->assertIsArray( $names ); - $this->assertNotContains( 'completely_unrelated_option', $names ); + $this->assertIsArray( $names, 'list_names() should return an array.' ); + $this->assertNotContains( 'completely_unrelated_option', $names, 'Options that are not secret records should not be listed.' ); } /** @@ -206,12 +206,12 @@ public function test_list_names_returns_only_the_requested_scope(): void { $site_names = $store->list_names( false ); $network_names = $store->list_names( true ); - $this->assertIsArray( $site_names ); - $this->assertIsArray( $network_names ); - $this->assertContains( 'myplugin/site-only', $site_names ); - $this->assertNotContains( 'myplugin/network-only', $site_names ); - $this->assertContains( 'myplugin/network-only', $network_names ); - $this->assertNotContains( 'myplugin/site-only', $network_names ); + $this->assertIsArray( $site_names, 'list_names() should return an array for the site scope.' ); + $this->assertIsArray( $network_names, 'list_names() should return an array for the network scope.' ); + $this->assertContains( 'myplugin/site-only', $site_names, 'The site-scope name should be listed in the site scope.' ); + $this->assertNotContains( 'myplugin/network-only', $site_names, 'The network-scope name should not be listed in the site scope.' ); + $this->assertContains( 'myplugin/network-only', $network_names, 'The network-scope name should be listed in the network scope.' ); + $this->assertNotContains( 'myplugin/site-only', $network_names, 'The site-scope name should not be listed in the network scope.' ); } /** @@ -231,8 +231,8 @@ public function test_list_names_escapes_the_underscore_wildcard(): void { $names = $store->list_names(); - $this->assertIsArray( $names ); - $this->assertContains( 'myplugin/real', $names ); - $this->assertNotContains( 'decoy/name', $names ); + $this->assertIsArray( $names, 'list_names() should return an array.' ); + $this->assertContains( 'myplugin/real', $names, 'The real secret name should be listed.' ); + $this->assertNotContains( 'decoy/name', $names, 'An option matching only via an unescaped underscore wildcard should not be listed.' ); } } diff --git a/tests/phpunit/tests/secrets/wpSecretsValidateName.php b/tests/phpunit/tests/secrets/wpSecretsValidateName.php index f008b10872b16..aea41f1d6d60d 100644 --- a/tests/phpunit/tests/secrets/wpSecretsValidateName.php +++ b/tests/phpunit/tests/secrets/wpSecretsValidateName.php @@ -16,7 +16,7 @@ class Tests_Secrets_WpSecretsValidateName extends WP_UnitTestCase { * @param string $name A name that must be accepted. */ public function test_accepts_valid_names( $name ): void { - $this->assertTrue( wp_secrets_validate_name( $name ) ); + $this->assertTrue( wp_secrets_validate_name( $name ), 'A well-formed namespaced name should be accepted.' ); } /** @@ -47,8 +47,8 @@ public static function data_valid_names(): array { public function test_rejects_invalid_names( $name ): void { $result = wp_secrets_validate_name( $name ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code() ); + $this->assertWPError( $result, 'An invalid name should be rejected with a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code(), 'An invalid name should be reported with the invalid name error code.' ); } /** @@ -66,7 +66,7 @@ public function test_rejects_invalid_names( $name ): void { public function test_accepts_an_unnamespaced_name_but_reports_it( $name ): void { $this->setExpectedIncorrectUsage( 'wp_secrets_validate_name' ); - $this->assertTrue( wp_secrets_validate_name( $name ) ); + $this->assertTrue( wp_secrets_validate_name( $name ), 'An unnamespaced name should be accepted.' ); } /** @@ -91,8 +91,8 @@ public static function data_unnamespaced_names(): array { public function test_an_unnamespaced_name_still_obeys_the_character_rules(): void { $result = wp_secrets_validate_name( 'Not_A_Valid_Name' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code() ); + $this->assertWPError( $result, 'An unnamespaced name with invalid characters should be rejected with a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code(), 'An unnamespaced name with invalid characters should be reported as an invalid name.' ); } /** diff --git a/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php b/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php index 10414cb833032..aca749bbace59 100644 --- a/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php +++ b/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php @@ -17,14 +17,14 @@ class Tests_Secrets_WpSetSecretAndWpGetSecret extends WP_UnitTestCase { * @covers ::wp_get_secret */ public function test_set_then_get_round_trips(): void { - $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'sk_live_secret' ) ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'sk_live_secret' ), 'wp_set_secret() should return true on success.' ); $secret = wp_get_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $secret ); - $this->assertSame( 'sk_live_secret', $secret->reveal() ); - $this->assertSame( 'myplugin/api-key', $secret->get_name() ); - $this->assertNotSame( '', $secret->fingerprint() ); + $this->assertInstanceOf( WP_Secret::class, $secret, 'wp_get_secret() should return a WP_Secret.' ); + $this->assertSame( 'sk_live_secret', $secret->reveal(), 'The secret should reveal its original value.' ); + $this->assertSame( 'myplugin/api-key', $secret->get_name(), 'The secret should report its name.' ); + $this->assertNotSame( '', $secret->fingerprint(), 'The secret fingerprint should not be empty.' ); } /** @@ -38,9 +38,9 @@ public function test_get_defaults_to_the_current_version(): void { $default = wp_get_secret( 'myplugin/api-key' ); $current = wp_get_secret( 'myplugin/api-key', WP_Secret_Version::CURRENT ); - $this->assertInstanceOf( WP_Secret::class, $default ); - $this->assertInstanceOf( WP_Secret::class, $current ); - $this->assertSame( $default->reveal(), $current->reveal() ); + $this->assertInstanceOf( WP_Secret::class, $default, 'The default lookup should return a WP_Secret.' ); + $this->assertInstanceOf( WP_Secret::class, $current, 'The current version lookup should return a WP_Secret.' ); + $this->assertSame( $default->reveal(), $current->reveal(), 'The default lookup should reveal the same value as the current version.' ); } /** @@ -56,8 +56,8 @@ public function test_an_invalid_version_is_a_wp_error_not_an_exception(): void { $result = wp_get_secret( 'myplugin/api-key', 'not-a-real-version' ); // @phpstan-ignore argument.type (Intentionally passing an invalid value.) - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_ARGUMENT, $result->get_error_code() ); + $this->assertWPError( $result, 'An invalid version should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_ARGUMENT, $result->get_error_code(), 'An invalid version should use the invalid argument error code.' ); } /** @@ -68,8 +68,8 @@ public function test_an_invalid_version_is_a_wp_error_not_an_exception(): void { public function test_set_rejects_an_invalid_name(): void { $result = wp_set_secret( 'Not A Valid Name', 'value' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code() ); + $this->assertWPError( $result, 'An invalid name should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code(), 'An invalid name should use the invalid name error code.' ); } /** @@ -80,8 +80,8 @@ public function test_set_rejects_an_invalid_name(): void { public function test_get_rejects_an_invalid_name(): void { $result = wp_get_secret( 'Not A Valid Name' ); - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code() ); + $this->assertWPError( $result, 'An invalid name should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code(), 'An invalid name should use the invalid name error code.' ); } /** @@ -92,8 +92,8 @@ public function test_get_rejects_an_invalid_name(): void { public function test_set_rejects_a_non_string_value(): void { $result = wp_set_secret( 'myplugin/api-key', array( 'not', 'a', 'string' ) ); // @phpstan-ignore argument.type (Intentionally passing an invalid value.) - $this->assertWPError( $result ); - $this->assertSame( WP_SECRETS_ERROR_INVALID_VALUE, $result->get_error_code() ); + $this->assertWPError( $result, 'A non-string value should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_INVALID_VALUE, $result->get_error_code(), 'A non-string value should use the invalid value error code.' ); } /** @@ -103,12 +103,12 @@ public function test_set_rejects_a_non_string_value(): void { * @covers ::wp_get_secret */ public function test_set_accepts_an_empty_string_value(): void { - $this->assertTrue( wp_set_secret( 'myplugin/api-key', '' ) ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', '' ), 'Storing an empty string should succeed.' ); $secret = wp_get_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $secret ); - $this->assertSame( '', $secret->reveal() ); + $this->assertInstanceOf( WP_Secret::class, $secret, 'The empty secret should be retrievable as a WP_Secret.' ); + $this->assertSame( '', $secret->reveal(), 'The secret should reveal an empty string.' ); } /** @@ -120,12 +120,12 @@ public function test_set_accepts_an_empty_string_value(): void { public function test_a_corrupt_record_can_be_overwritten(): void { update_option( '_wp_secret_myplugin/corrupt', 'not a record at all', false ); - $this->assertTrue( wp_set_secret( 'myplugin/corrupt', 'a fresh value' ) ); + $this->assertTrue( wp_set_secret( 'myplugin/corrupt', 'a fresh value' ), 'Overwriting a corrupt record should succeed.' ); $secret = wp_get_secret( 'myplugin/corrupt' ); - $this->assertInstanceOf( WP_Secret::class, $secret ); - $this->assertSame( 'a fresh value', $secret->reveal() ); + $this->assertInstanceOf( WP_Secret::class, $secret, 'The overwritten secret should be retrievable as a WP_Secret.' ); + $this->assertSame( 'a fresh value', $secret->reveal(), 'The secret should reveal the fresh value.' ); } /** @@ -139,7 +139,7 @@ public function test_a_corrupt_record_can_be_overwritten(): void { public function test_the_options_table_contains_no_plaintext_after_a_write(): void { global $wpdb; - $this->assertInstanceOf( wpdb::class, $wpdb ); + $this->assertInstanceOf( wpdb::class, $wpdb, 'The global $wpdb should be a wpdb instance.' ); wp_set_secret( 'myplugin/api-key', 'UNIQUE-PLAINTEXT-CANARY-9f3a' ); @@ -164,8 +164,8 @@ public function test_reveal_still_works_after_the_internal_memzero(): void { $secret = wp_get_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $secret ); - $this->assertSame( 'must-survive-memzero', $secret->reveal() ); + $this->assertInstanceOf( WP_Secret::class, $secret, 'The stored secret should be retrievable as a WP_Secret.' ); + $this->assertSame( 'must-survive-memzero', $secret->reveal(), 'The secret should reveal its value after the internal memzero.' ); } /** @@ -180,8 +180,8 @@ public function test_reveal_still_works_after_the_internal_memzero(): void { public function test_no_capability_check_is_applied(): void { wp_set_current_user( 0 ); // No logged-in user, no capabilities at all. - $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ) ); - $this->assertInstanceOf( WP_Secret::class, wp_get_secret( 'myplugin/api-key' ) ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Storing a secret without a logged-in user should succeed.' ); + $this->assertInstanceOf( WP_Secret::class, wp_get_secret( 'myplugin/api-key' ), 'Retrieving a secret without a logged-in user should return a WP_Secret.' ); } /** @@ -204,17 +204,17 @@ function ( ...$args ) use ( &$captured ) { wp_set_secret( 'myplugin/api-key', 'value' ); $after = time(); - $this->assertNotNull( $captured ); + $this->assertNotNull( $captured, 'The wp_secret_changed hook should fire.' ); list( $name, $action, $actor_id, $timestamp, $old_fingerprint, $new_fingerprint, $network ) = $captured; - $this->assertSame( 'myplugin/api-key', $name ); - $this->assertSame( 'created', $action ); + $this->assertSame( 'myplugin/api-key', $name, 'The hook should receive the secret name.' ); + $this->assertSame( 'created', $action, 'The hook action should be created.' ); $this->assertSame( 0, $actor_id, 'With no user logged in, the actor should be reported as 0.' ); $this->assertGreaterThanOrEqual( $before, $timestamp, 'The timestamp should not predate the write.' ); $this->assertLessThanOrEqual( $after, $timestamp, 'The timestamp should not postdate the write.' ); - $this->assertSame( '', $old_fingerprint ); - $this->assertNotSame( '', $new_fingerprint ); - $this->assertFalse( $network ); + $this->assertSame( '', $old_fingerprint, 'The old fingerprint should be empty for a new secret.' ); + $this->assertNotSame( '', $new_fingerprint, 'The new fingerprint should not be empty.' ); + $this->assertFalse( $network, 'The network flag should be false for a site secret.' ); } /** @@ -226,7 +226,7 @@ public function test_change_hook_fires_on_overwrite_with_updated_action(): void wp_set_secret( 'myplugin/api-key', 'first-value' ); $first = wp_get_secret( 'myplugin/api-key' ); - $this->assertInstanceOf( WP_Secret::class, $first ); + $this->assertInstanceOf( WP_Secret::class, $first, 'The first secret should be retrievable as a WP_Secret.' ); $first_fingerprint = $first->fingerprint(); $captured = null; @@ -241,12 +241,12 @@ function ( ...$args ) use ( &$captured ) { wp_set_secret( 'myplugin/api-key', 'second-value' ); - $this->assertIsArray( $captured ); + $this->assertIsArray( $captured, 'The wp_secret_changed hook should fire.' ); list( , $action, , , $old_fingerprint, $new_fingerprint ) = $captured; - $this->assertSame( 'updated', $action ); - $this->assertSame( $first_fingerprint, $old_fingerprint ); - $this->assertNotSame( $old_fingerprint, $new_fingerprint ); + $this->assertSame( 'updated', $action, 'The hook action should be updated.' ); + $this->assertSame( $first_fingerprint, $old_fingerprint, 'The old fingerprint should match the first value.' ); + $this->assertNotSame( $old_fingerprint, $new_fingerprint, 'The new fingerprint should differ from the old one.' ); } /** @@ -270,7 +270,7 @@ function ( $name, $action, $actor_id ) use ( &$captured_actor ) { wp_set_secret( 'myplugin/api-key', 'value' ); - $this->assertSame( $user_id, $captured_actor ); + $this->assertSame( $user_id, $captured_actor, 'The hook should report the current user as the actor.' ); } /** @@ -294,11 +294,11 @@ function ( ...$args ) use ( &$captured_args ) { wp_set_secret( 'myplugin/api-key', 'a-plaintext-value-that-must-not-leak' ); - $this->assertIsArray( $captured_args ); + $this->assertIsArray( $captured_args, 'The wp_secret_changed hook should fire.' ); foreach ( $captured_args as $arg ) { - $this->assertIsScalar( $arg ); - $this->assertStringNotContainsString( 'a-plaintext-value-that-must-not-leak', (string) $arg ); + $this->assertIsScalar( $arg, 'Each hook argument should be scalar.' ); + $this->assertStringNotContainsString( 'a-plaintext-value-that-must-not-leak', (string) $arg, 'No hook argument should contain the plaintext value.' ); } } } From 6b03ba01c251618e153656ec48c58b724a84f9db Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 10:29:31 +1100 Subject: [PATCH 09/28] Fix multi-line comment formatting. --- src/wp-includes/secrets.php | 14 +++++++++----- .../class-wp-secrets-libsodium-provider.php | 6 ++++-- .../secrets/class-wp-secrets-option-store.php | 6 ++++-- tests/phpunit/tests/secrets/errorCodes.php | 6 ++++-- .../phpunit/tests/secrets/extensionPoints.php | 6 ++++-- tests/phpunit/tests/secrets/versionSlots.php | 6 ++++-- .../tests/secrets/wpSecretsKeyManager.php | 18 +++++++++++------- .../phpunit/tests/secrets/wpSecretsMemzero.php | 6 ++++-- .../tests/secrets/wpSecretsOptionStore.php | 6 ++++-- 9 files changed, 48 insertions(+), 26 deletions(-) diff --git a/src/wp-includes/secrets.php b/src/wp-includes/secrets.php index 7df4409c895d5..782a975239200 100644 --- a/src/wp-includes/secrets.php +++ b/src/wp-includes/secrets.php @@ -184,15 +184,19 @@ function wp_secrets_memzero( &$value ): void { $alias =& $value; sodium_memzero( $alias ); } catch ( \Throwable $e ) { - // A value this function doesn't exclusively own (a shared, - // copy-on-write buffer) can legitimately refuse. The unconditional - // reassignment below still runs regardless of what happened here. + /* + * A value this function doesn't exclusively own (a shared, + * copy-on-write buffer) can legitimately refuse. The unconditional + * reassignment below still runs regardless of what happened here. + */ unset( $e ); } } - // Reached on every path, including sodium_memzero() success (it leaves the - // variable null, not an empty string) so callers see one consistent contract. + /* + * Reached on every path, including sodium_memzero() success (it leaves the + * variable null, not an empty string) so callers see one consistent contract. + */ $value = ''; } diff --git a/src/wp-includes/secrets/class-wp-secrets-libsodium-provider.php b/src/wp-includes/secrets/class-wp-secrets-libsodium-provider.php index 0c21195c64de4..cf4dcfa11fd82 100644 --- a/src/wp-includes/secrets/class-wp-secrets-libsodium-provider.php +++ b/src/wp-includes/secrets/class-wp-secrets-libsodium-provider.php @@ -485,8 +485,10 @@ public function get( string $name, string $version, bool $network = false ) { } if ( ! isset( $record[ $version ] ) || ! is_array( $record[ $version ] ) ) { - // The secret exists, but this slot does not. Absence, not an error – - // this matters most for PREVIOUS on a secret that has never been rotated. + /* + * The secret exists, but this slot does not. Absence, not an error – + * this matters most for PREVIOUS on a secret that has never been rotated. + */ return null; } diff --git a/src/wp-includes/secrets/class-wp-secrets-option-store.php b/src/wp-includes/secrets/class-wp-secrets-option-store.php index 52b10466849cf..5519d7d69f574 100644 --- a/src/wp-includes/secrets/class-wp-secrets-option-store.php +++ b/src/wp-includes/secrets/class-wp-secrets-option-store.php @@ -124,8 +124,10 @@ public function delete( string $name, bool $network = false ) { return true; } - // delete_*_option() also returns false when the option never existed. - // Deleting something already absent is not a failure. + /* + * delete_*_option() also returns false when the option never existed. + * Deleting something already absent is not a failure. + */ $still_exists = null !== ( $network ? get_site_option( $option_name, null ) : get_option( $option_name, null ) ); if ( ! $still_exists ) { diff --git a/tests/phpunit/tests/secrets/errorCodes.php b/tests/phpunit/tests/secrets/errorCodes.php index cf4d763fbedc6..8be7202086ec5 100644 --- a/tests/phpunit/tests/secrets/errorCodes.php +++ b/tests/phpunit/tests/secrets/errorCodes.php @@ -77,8 +77,10 @@ static function ( $name ) { * @coversNothing */ public function test_max_name_length_matches_the_options_column_budget(): void { - // wp_options.option_name is VARCHAR(191); '_wp_network_secret_' (19 - // characters) is the longest prefix any store here uses. + /* + * wp_options.option_name is VARCHAR(191); '_wp_network_secret_' (19 + * characters) is the longest prefix any store here uses. + */ $this->assertSame( 191 - strlen( '_wp_network_secret_' ), WP_SECRETS_MAX_NAME_LENGTH, 'WP_SECRETS_MAX_NAME_LENGTH should fit the longest prefixed name in option_name.' ); } } diff --git a/tests/phpunit/tests/secrets/extensionPoints.php b/tests/phpunit/tests/secrets/extensionPoints.php index cfd9ca00c331a..8a4502d90b6b9 100644 --- a/tests/phpunit/tests/secrets/extensionPoints.php +++ b/tests/phpunit/tests/secrets/extensionPoints.php @@ -137,8 +137,10 @@ public function test_unreachable_store_fails_closed_with_no_local_fallback(): vo $this->assertWPError( $set_result, 'A write to an unreachable store should return a WP_Error.' ); $this->assertWPError( $get_result, 'A read from an unreachable store should return a WP_Error.' ); - // Fails closed, not merely differently: nothing was written to the real - // default store either, which a silent fallback would have done. + /* + * Fails closed, not merely differently: nothing was written to the real + * default store either, which a silent fallback would have done. + */ $this->assertFalse( get_option( '_wp_secret_myplugin/api-key' ), 'Nothing should be written to the default options store as a fallback.' ); } diff --git a/tests/phpunit/tests/secrets/versionSlots.php b/tests/phpunit/tests/secrets/versionSlots.php index e62901468cd2c..d65540d5c3997 100644 --- a/tests/phpunit/tests/secrets/versionSlots.php +++ b/tests/phpunit/tests/secrets/versionSlots.php @@ -55,8 +55,10 @@ public function test_third_write_discards_the_oldest_value(): void { $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::PREVIOUS, 'value-b', false, 'The previous slot should decrypt to the second of three values.' ); - // value-a is gone from the stored record entirely, not merely unreachable - // through the two named slots. + /* + * value-a is gone from the stored record entirely, not merely unreachable + * through the two named slots. + */ $this->assertNeverContainsPlaintext( 'value-a', get_option( '_wp_secret_myplugin/api-key' ), 'The stored record should no longer contain the oldest value.' ); } diff --git a/tests/phpunit/tests/secrets/wpSecretsKeyManager.php b/tests/phpunit/tests/secrets/wpSecretsKeyManager.php index d0a72a8d7529f..960f75d863005 100644 --- a/tests/phpunit/tests/secrets/wpSecretsKeyManager.php +++ b/tests/phpunit/tests/secrets/wpSecretsKeyManager.php @@ -418,10 +418,12 @@ public function test_rotation_does_not_change_any_derived_master_key(): void { $this->assertSame( $master_before, $master_after, 'The derived master key should be unchanged by rotation.' ); - // The old keyring alone is no longer sufficient: the stored root key is now - // wrapped under the new key. Checked with a fresh manager instance, since - // $manager_under_old_key's own cache was correctly primed by the rotation - // it just performed and is not the thing under test here. + /* + * The old keyring alone is no longer sufficient: the stored root key is now + * wrapped under the new key. Checked with a fresh manager instance, since + * $manager_under_old_key's own cache was correctly primed by the rotation + * it just performed and is not the thing under test here. + */ $fresh_manager_under_old_key = new WP_Secrets_Key_Manager( $old_keyring ); $this->assertWPError( $fresh_manager_under_old_key->get_root_key(), 'The old keyring alone should no longer unwrap the rotated root key.' ); } @@ -541,9 +543,11 @@ public function test_an_unwrap_error_is_not_cached(): void { $manager = new WP_Secrets_Key_Manager( $mock ); - // Each call is assigned before it is asserted on: get_root_key() answers - // differently as the keyring's state changes, so no two calls are the - // same expression as far as a reader (or an analyzer) should assume. + /* + * Each call is assigned before it is asserted on: get_root_key() answers + * differently as the keyring's state changes, so no two calls are the + * same expression as far as a reader (or an analyzer) should assume. + */ $mock->configure_fail_unwrap( true ); $while_failing = $manager->get_root_key(); $this->assertWPError( $while_failing, 'get_root_key() should return a WP_Error while unwrap fails.' ); diff --git a/tests/phpunit/tests/secrets/wpSecretsMemzero.php b/tests/phpunit/tests/secrets/wpSecretsMemzero.php index 8da51bdad50ec..b7194b476c12e 100644 --- a/tests/phpunit/tests/secrets/wpSecretsMemzero.php +++ b/tests/phpunit/tests/secrets/wpSecretsMemzero.php @@ -58,8 +58,10 @@ public function test_clears_the_variable_and_leaves_a_shared_copy_untouched(): v wp_secrets_memzero( $value ); $this->assertSame( '', $value, 'The zeroed variable should be an empty string.' ); - // The shared copy is unaffected – see the docblock on wp_secrets_memzero(): - // this is hygiene, not a guarantee, for exactly this reason. + /* + * The shared copy is unaffected – see the docblock on wp_secrets_memzero(): + * this is hygiene, not a guarantee, for exactly this reason. + */ $this->assertSame( 'shared plaintext', $copy, 'The shared copy should keep its original value.' ); // @phpstan-ignore method.alreadyNarrowedType (Whether the copy survives the scrub is decided by the engine at runtime, not by the types.) } } diff --git a/tests/phpunit/tests/secrets/wpSecretsOptionStore.php b/tests/phpunit/tests/secrets/wpSecretsOptionStore.php index c8a74dda8ab65..0b7ccee8342d1 100644 --- a/tests/phpunit/tests/secrets/wpSecretsOptionStore.php +++ b/tests/phpunit/tests/secrets/wpSecretsOptionStore.php @@ -222,8 +222,10 @@ public function test_list_names_returns_only_the_requested_scope(): void { * @covers WP_Secrets_Option_Store::list_names */ public function test_list_names_escapes_the_underscore_wildcard(): void { - // Would match "_wp_secret_%" under an *unescaped* LIKE, since '_' matches - // any single character – proving esc_like() is actually applied. + /* + * Would match "_wp_secret_%" under an *unescaped* LIKE, since '_' matches + * any single character – proving esc_like() is actually applied. + */ update_option( '_wpXsecret_decoy/name', 'irrelevant value', false ); $store = new WP_Secrets_Option_Store(); From 4d6c65e467278d157b630febd71dd193eda5b81c Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 10:30:47 +1100 Subject: [PATCH 10/28] Rewrite docblocks as statements. --- src/wp-admin/includes/secrets-site-health.php | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/wp-admin/includes/secrets-site-health.php b/src/wp-admin/includes/secrets-site-health.php index d6a19b4920d82..c8fae1aaf49e6 100644 --- a/src/wp-admin/includes/secrets-site-health.php +++ b/src/wp-admin/includes/secrets-site-health.php @@ -74,7 +74,7 @@ function wp_secrets_site_health_result( string $test, string $label, string $sta } /** - * Site Health test: is the site key a dedicated constant, or a weaker fallback? + * Tests whether the site key comes from a dedicated constant or a weaker fallback. * * @since 7.2.0 * @@ -130,7 +130,7 @@ function wp_secrets_site_health_test_key_source(): array { } /** - * Site Health test: does every stored secret still decrypt? + * Tests whether every stored secret still decrypts. * * Network secrets are included only for a super admin on a multisite install – * never shown to a site administrator who is not one. @@ -218,7 +218,7 @@ function wp_secrets_site_health_find_undecryptable( bool $network ): array { } /** - * Site Health test: are any secrets flagged as needing rotation? + * Tests whether any secrets are flagged as needing rotation. * * @since 7.2.0 * From b0b618398a87ef996c73c6680e9358a654645e92 Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 10:34:00 +1100 Subject: [PATCH 11/28] Add global annotations. --- src/wp-includes/load.php | 6 ++++++ src/wp-includes/secrets.php | 11 +++++++++++ 2 files changed, 17 insertions(+) diff --git a/src/wp-includes/load.php b/src/wp-includes/load.php index ecd4220e5adff..31f82524bab85 100644 --- a/src/wp-includes/load.php +++ b/src/wp-includes/load.php @@ -849,6 +849,12 @@ function wp_using_ext_object_cache( $using = null ) { * * @since 7.2.0 * @access private + * + * @global bool $wp_secrets_dropin_loaded Whether a secrets.php drop-in file was found. + * @global bool $wp_secrets_dropin_broken Whether the drop-in failed to load or left an invalid override. + * @global WP_Secrets_Provider $wp_secrets_provider Optional. Provider override set by the drop-in. + * @global WP_Secrets_Store $wp_secrets_store Optional. Store override set by the drop-in. + * @global WP_Secrets_Keyring $wp_secrets_keyring Optional. Keyring override set by the drop-in. */ function wp_load_secrets_dropin(): void { static $loaded = false; diff --git a/src/wp-includes/secrets.php b/src/wp-includes/secrets.php index 782a975239200..2852a5b84049c 100644 --- a/src/wp-includes/secrets.php +++ b/src/wp-includes/secrets.php @@ -318,6 +318,9 @@ function wp_secrets_validate_name( string $name ) { * * @since 7.2.0 * + * @global bool $wp_secrets_dropin_broken Whether the secrets.php drop-in failed to load cleanly. + * @global WP_Secrets_Store $wp_secrets_store Optional. Store override set by the drop-in. + * * @return WP_Secrets_Store */ function _wp_secrets_get_store(): WP_Secrets_Store { @@ -354,6 +357,9 @@ function _wp_secrets_get_store(): WP_Secrets_Store { * * @since 7.2.0 * + * @global bool $wp_secrets_dropin_broken Whether the secrets.php drop-in failed to load cleanly. + * @global WP_Secrets_Keyring $wp_secrets_keyring Optional. Keyring override set by the drop-in. + * * @return WP_Secrets_Key_Manager */ function _wp_secrets_get_key_manager(): WP_Secrets_Key_Manager { @@ -389,6 +395,8 @@ function _wp_secrets_get_key_manager(): WP_Secrets_Key_Manager { * * @since 7.2.0 * + * @global bool $wp_secrets_dropin_loaded Whether a secrets.php drop-in file was found. + * * @return bool */ function wp_using_secrets_dropin(): bool { @@ -625,6 +633,9 @@ function wp_list_network_secrets( string $namespace = '' ) { // phpcs:ignore Uni * * @since 7.2.0 * + * @global bool $wp_secrets_dropin_broken Whether the secrets.php drop-in failed to load cleanly. + * @global WP_Secrets_Provider $wp_secrets_provider Optional. Provider override set by the drop-in. + * * @return WP_Secrets_Provider */ function _wp_secrets_get_provider(): WP_Secrets_Provider { From 8fbf69e54f04407820276edf4bd8e1c7dd44ce9e Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 10:34:16 +1100 Subject: [PATCH 12/28] Remove stale references to feature plgun. --- src/wp-includes/secrets.php | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/wp-includes/secrets.php b/src/wp-includes/secrets.php index 2852a5b84049c..4139e77e12d18 100644 --- a/src/wp-includes/secrets.php +++ b/src/wp-includes/secrets.php @@ -86,9 +86,9 @@ * * Distinct from WP_SECRETS_ERROR_RECORD_MALFORMED so that an operator, or Site * Health, can tell a corrupt record apart from one written by a newer version of - * this plugin than is currently active. See - * docs/decisions/0006-record-format-v2-not-read-compatible.md. The upgrade path for a future v2 is not - * designed, so an unrecognized version is rejected outright rather than guessed at. + * WordPress than is currently running. The upgrade path for a future record format + * is not designed, so an unrecognized version is rejected outright rather than + * guessed at. * * @since 7.2.0 */ @@ -305,10 +305,10 @@ function wp_secrets_validate_name( string $name ) { /** * Returns the active secret store. * - * No filter is applied here, or anywhere on the retrieval path. See - * docs/spec/extension-points.md. A secrets.php drop-in overrides the store by setting - * $GLOBALS['wp_secrets_store'] to an instance before this is first called, and - * that global is checked here directly, not through a hook. + * No filter is applied here, or anywhere on the retrieval path. A secrets.php + * drop-in overrides the store by setting $GLOBALS['wp_secrets_store'] to an + * instance before this is first called, and that global is checked here directly, + * not through a hook. * * If the global was set but is not a valid WP_Secrets_Store, or if the drop-in * itself failed to load cleanly, this returns WP_Secrets_Broken_Store rather than From 9a396da54788f13d7fddd8bf967a2d6a01d4e7a5 Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 10:38:33 +1100 Subject: [PATCH 13/28] Docs: id -> ID. --- src/wp-includes/secrets.php | 2 +- src/wp-includes/secrets/class-wp-secret.php | 4 ++-- src/wp-includes/secrets/class-wp-secrets-cipher.php | 4 ++-- .../secrets/class-wp-secrets-key-manager.php | 10 +++++----- .../secrets/class-wp-secrets-libsodium-provider.php | 4 ++-- 5 files changed, 12 insertions(+), 12 deletions(-) diff --git a/src/wp-includes/secrets.php b/src/wp-includes/secrets.php index 4139e77e12d18..2277ff2ab3927 100644 --- a/src/wp-includes/secrets.php +++ b/src/wp-includes/secrets.php @@ -50,7 +50,7 @@ /** * A caller passed an argument this API cannot act on. * - * An unrecognized version constant, or an invalid scope, slot, or site id. + * An unrecognized version constant, or an invalid scope, slot, or site ID. * * Distinct from the codes above in cause rather than in severity: those describe * a runtime condition a correct caller can still hit (a name that failed diff --git a/src/wp-includes/secrets/class-wp-secret.php b/src/wp-includes/secrets/class-wp-secret.php index 7ecb1d703e4f7..26343f8b7c7dd 100644 --- a/src/wp-includes/secrets/class-wp-secret.php +++ b/src/wp-includes/secrets/class-wp-secret.php @@ -31,7 +31,7 @@ final class WP_Secret implements JsonSerializable { * Deliberately not an SplObjectStorage keyed by the instance itself: that holds a * strong reference to its keys, which would keep every WP_Secret ever constructed * alive – and its plaintext un-zeroed – for the life of the request. Keying by - * the integer id instead leaves an instance's own reference count to govern its + * the integer ID instead leaves an instance's own reference count to govern its * lifetime normally, so __destruct() fires and zeroes the value the moment nothing * else references the instance. * @@ -312,7 +312,7 @@ public function __unserialize( array $data ): void { * Refuses cloning outright. * * A clone would be a second, unaudited reference to the same plaintext with an - * independent lifetime – and, since the vault is keyed by object id rather than + * independent lifetime – and, since the vault is keyed by object ID rather than * copied, a bare `clone` would otherwise leave the clone's reveal() silently * reading nothing. * diff --git a/src/wp-includes/secrets/class-wp-secrets-cipher.php b/src/wp-includes/secrets/class-wp-secrets-cipher.php index 4dc631597ca3b..5cb12848d302b 100644 --- a/src/wp-includes/secrets/class-wp-secrets-cipher.php +++ b/src/wp-includes/secrets/class-wp-secrets-cipher.php @@ -256,7 +256,7 @@ public function fingerprint( string $master_key, $plaintext ) { * * @param string $purpose One of the AAD_* class constants. * @param string $scope 'site' or 'network'. - * @param int $site_id Blog id for site scope, 0 for network scope. + * @param int $site_id Blog ID for site scope, 0 for network scope. * @param string $name Validated secret name. * @param string $slot A WP_Secret_Version constant. * @return string @@ -284,7 +284,7 @@ private function build_aad( string $purpose, string $scope, int $site_id, string * * @param string $master_key Candidate master key. * @param string $scope Candidate scope. - * @param int $site_id Candidate site id. + * @param int $site_id Candidate site ID. * @param string $name Candidate secret name. * @param string $slot Candidate slot. * @return true|WP_Error diff --git a/src/wp-includes/secrets/class-wp-secrets-key-manager.php b/src/wp-includes/secrets/class-wp-secrets-key-manager.php index 91740370d8ecb..de2e7302a4f58 100644 --- a/src/wp-includes/secrets/class-wp-secrets-key-manager.php +++ b/src/wp-includes/secrets/class-wp-secrets-key-manager.php @@ -22,7 +22,7 @@ * - Site scope, blog N: sodium_crypto_kdf_derive_from_key( 32, N, 'wpsecsit', $root ). * Distinct per blog, which shared network-wide salts otherwise cannot provide. * - Network scope: sodium_crypto_kdf_derive_from_key( 32, 0, 'wpsecnet', $root ). - * Subkey id 0 is reserved for this (blog ids start at 1) and the context string + * Subkey ID 0 is reserved for this (blog IDs start at 1) and the context string * differs from the site path, so there is no collision between the two. Identical * on every blog, so a network secret written on one blog reads on every other. * @@ -66,9 +66,9 @@ final class WP_Secrets_Key_Manager { const NETWORK_KDF_CONTEXT = 'wpsecnet'; /** - * Reserved KDF subkey id for network scope. + * Reserved KDF subkey ID for network scope. * - * Blog ids start at 1, so this can never collide with a site-scope subkey id. + * Blog IDs start at 1, so this can never collide with a site-scope subkey ID. * * @since 7.2.0 * @var int @@ -136,11 +136,11 @@ public function get_keyring(): WP_Secrets_Keyring { * @since 7.2.0 * * @param string $scope 'site' or 'network'. - * @param int|null $site_id Blog id for site scope. Defaults to the current blog. + * @param int|null $site_id Blog ID for site scope. Defaults to the current blog. * Ignored for network scope. * @return string|WP_Error 32-byte master key on success. WP_Error on failure, * including when a caller passes an invalid scope or - * site id – see WP_Secrets_Cipher::validate_common() + * site ID – see WP_Secrets_Cipher::validate_common() * for why that is a WP_Error and not an exception. * * @phpstan-param 'site'|'network' $scope diff --git a/src/wp-includes/secrets/class-wp-secrets-libsodium-provider.php b/src/wp-includes/secrets/class-wp-secrets-libsodium-provider.php index cf4dcfa11fd82..5491aa250d1c4 100644 --- a/src/wp-includes/secrets/class-wp-secrets-libsodium-provider.php +++ b/src/wp-includes/secrets/class-wp-secrets-libsodium-provider.php @@ -233,7 +233,7 @@ private function slot_fingerprint( $slot ): string { * @param WP_Secrets_Cipher $cipher A cipher instance. * @param string $master_key 32-byte master key. * @param string $scope 'site' or 'network'. - * @param int $site_id Blog id for site scope, 0 for network scope. + * @param int $site_id Blog ID for site scope, 0 for network scope. * @param string $name The secret's namespaced name. * @param array $current_slot The outgoing current slot, as stored. * @return array|WP_Error The same value, re-encrypted and bound to @@ -427,7 +427,7 @@ public function set( string $name, $value, bool $network = false, bool $needs_ro * @param string $name The secret's namespaced name. * @param string $action One of 'created', 'updated', 'deleted', * 'imported', 'retired'. - * @param int $actor_id The current user id, or 0. + * @param int $actor_id The current user ID, or 0. * @param int $timestamp Unix timestamp of the change. * @param string $old_fingerprint The previous fingerprint, or '' if none. * @param string $new_fingerprint The new fingerprint, or '' if the secret was deleted. From aca1284ef24f568d81b9ffd94c3ebe06f611d283 Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 10:38:43 +1100 Subject: [PATCH 14/28] Remove stale plugin reference. --- .../secrets/class-wp-secrets-libsodium-provider.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/wp-includes/secrets/class-wp-secrets-libsodium-provider.php b/src/wp-includes/secrets/class-wp-secrets-libsodium-provider.php index 5491aa250d1c4..5b6a2a97b3252 100644 --- a/src/wp-includes/secrets/class-wp-secrets-libsodium-provider.php +++ b/src/wp-includes/secrets/class-wp-secrets-libsodium-provider.php @@ -419,8 +419,8 @@ public function set( string $name, $value, bool $network = false, bool $needs_ro /** * Fires whenever a secret is created, updated, deleted, imported, or retired. * - * The only hook in the core-bound Secrets API code, and it does not fire on the - * retrieval path. Fingerprints are readable; values are never passed. + * This hook does not fire on the retrieval path. Fingerprints are passed; + * values never are. * * @since 7.2.0 * From 396db98646bad04324cc717ce147320bc7aac3b0 Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 10:41:53 +1100 Subject: [PATCH 15/28] Use should consistently. --- .../class-wp-secrets-provider-conformance.php | 28 +++++++++---------- .../secrets/trait-wp-secrets-assertions.php | 2 +- .../phpunit/tests/secrets/extensionPoints.php | 4 +-- tests/phpunit/tests/secrets/siteHealth.php | 2 +- .../secrets/wpSetSecretAndWpGetSecret.php | 2 +- 5 files changed, 19 insertions(+), 19 deletions(-) diff --git a/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php b/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php index 1d542893632be..dc18cb2fd74da 100644 --- a/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php +++ b/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php @@ -124,7 +124,7 @@ public function test_reports_a_known_protection_boundary(): void { $this->assertContains( $this->provider()->get_protection_boundary(), array( WP_Secrets_Provider::BOUNDARY_WORDPRESS, WP_Secrets_Provider::BOUNDARY_PROVIDER ), - 'get_protection_boundary() must return one of the BOUNDARY_* constants.' + 'get_protection_boundary() should return one of the BOUNDARY_* constants.' ); } @@ -157,7 +157,7 @@ public function test_a_read_only_provider_actually_refuses_writes(): void { $this->assertSame( WP_SECRETS_ERROR_PROVIDER_READ_ONLY, $result->get_error_code(), - 'A provider that declares itself read-only must refuse with secret_provider_read_only.' + 'A provider that declares itself read-only should refuse with secret_provider_read_only.' ); } @@ -308,8 +308,8 @@ public function test_writing_an_unchanged_value_keeps_the_previous_version(): vo $kept = $provider->get( $name, WP_Secret_Version::PREVIOUS ); - $this->assertInstanceOf( 'WP_Secret', $kept, 'Writing an unchanged value must not discard the previous version.' ); - $this->assertSame( $previous->fingerprint(), $kept->fingerprint(), 'Writing an unchanged value must not replace the previous version.' ); + $this->assertInstanceOf( 'WP_Secret', $kept, 'Writing an unchanged value should not discard the previous version.' ); + $this->assertSame( $previous->fingerprint(), $kept->fingerprint(), 'Writing an unchanged value should not replace the previous version.' ); } /** @@ -347,7 +347,7 @@ public function test_a_successful_write_reports_a_change(): void { $this->assertNotWPError( $provider->set( $name, 'UNIQUE-CONFORMANCE-CANARY-7c1d' ), 'The provider should accept the write.' ); - $this->assertCount( 1, $this->recorded_changes, 'set() must fire wp_secret_changed exactly once.' ); + $this->assertCount( 1, $this->recorded_changes, 'set() should fire wp_secret_changed exactly once.' ); $change = $this->recorded_changes[0]; @@ -358,8 +358,8 @@ public function test_a_successful_write_reports_a_change(): void { $this->assertIsInt( $change[3], 'The timestamp is a Unix timestamp.' ); $this->assertIsString( $change[4], "The old fingerprint is a string, '' when there is none." ); $this->assertIsString( $change[5], "The new fingerprint is a string, '' when there is none." ); - $this->assertFalse( $change[6], 'A site-scope write must report $network as false.' ); - $this->assertNotContains( 'UNIQUE-CONFORMANCE-CANARY-7c1d', $change, 'wp_secret_changed must never be passed a value.' ); + $this->assertFalse( $change[6], 'A site-scope write should report $network as false.' ); + $this->assertNotContains( 'UNIQUE-CONFORMANCE-CANARY-7c1d', $change, 'wp_secret_changed should never be passed a value.' ); } /** @@ -397,8 +397,8 @@ public function test_a_network_scope_change_reports_its_scope(): void { $this->assertNotWPError( $provider->delete( $name, true ), 'The provider should accept a network-scope delete.' ); $this->assertCount( 2, $this->recorded_changes, 'The provider should fire wp_secret_changed once for each network-scope change.' ); - $this->assertTrue( $this->recorded_changes[0][6], 'A network-scope write must report $network as true.' ); - $this->assertTrue( $this->recorded_changes[1][6], 'A network-scope delete must report $network as true.' ); + $this->assertTrue( $this->recorded_changes[0][6], 'A network-scope write should report $network as true.' ); + $this->assertTrue( $this->recorded_changes[1][6], 'A network-scope delete should report $network as true.' ); } /** @@ -417,7 +417,7 @@ public function test_deleting_a_secret_reports_a_change(): void { $this->assertNotWPError( $provider->delete( $name ), 'The provider should accept the delete.' ); - $this->assertCount( 1, $this->recorded_changes, 'delete() must fire wp_secret_changed exactly once.' ); + $this->assertCount( 1, $this->recorded_changes, 'delete() should fire wp_secret_changed exactly once.' ); $this->assertSame( $name, $this->recorded_changes[0][0], 'The provider should report the name of the deleted secret.' ); $this->assertSame( 'deleted', $this->recorded_changes[0][1], 'The provider should report a delete as deleted.' ); } @@ -449,7 +449,7 @@ public function test_retiring_a_previous_version_reports_a_change(): void { $this->markTestSkipped( 'Provider leaves version history to its backend; nothing was cleared.' ); } - $this->assertCount( 1, $this->recorded_changes, 'retire_previous() must fire wp_secret_changed exactly once.' ); + $this->assertCount( 1, $this->recorded_changes, 'retire_previous() should fire wp_secret_changed exactly once.' ); $this->assertSame( $name, $this->recorded_changes[0][0], 'The provider should report the name of the retired secret.' ); $this->assertSame( 'retired', $this->recorded_changes[0][1], 'The provider should report a retire as retired.' ); } @@ -469,7 +469,7 @@ public function test_a_refused_write_reports_no_change(): void { $this->record_changes(); $this->assertWPError( $provider->set( $this->conformance_name(), 'value' ), 'The provider should refuse a write with a WP_Error when read-only.' ); - $this->assertCount( 0, $this->recorded_changes, 'A write that did not happen must not be reported as a change.' ); + $this->assertCount( 0, $this->recorded_changes, 'A write that did not happen should not be reported as a change.' ); } // – listing never leaks --------------------------------------------------- @@ -495,11 +495,11 @@ public function test_listing_never_contains_a_stored_value(): void { $dump = wp_json_encode( $entries ); - $this->assertIsString( $dump, 'list_secrets() must return something that can be encoded and inspected.' ); + $this->assertIsString( $dump, 'list_secrets() should return something that can be encoded and inspected.' ); $this->assertStringNotContainsString( 'UNIQUE-CONFORMANCE-CANARY-3f9b', $dump, - 'list_secrets() must never expose a plaintext.' + 'list_secrets() should never expose a plaintext.' ); } diff --git a/tests/phpunit/includes/secrets/trait-wp-secrets-assertions.php b/tests/phpunit/includes/secrets/trait-wp-secrets-assertions.php index 6ab28d5f587b8..7958940923406 100644 --- a/tests/phpunit/includes/secrets/trait-wp-secrets-assertions.php +++ b/tests/phpunit/includes/secrets/trait-wp-secrets-assertions.php @@ -82,7 +82,7 @@ public function assertNeverContainsPlaintext( $plaintext, $haystack, $message = $this->assertStringNotContainsString( $plaintext, $flattened, - '' !== $message ? $message : 'Plaintext leaked into a structure that must never contain it.' + '' !== $message ? $message : 'Plaintext leaked into a structure that should never contain it.' ); } } diff --git a/tests/phpunit/tests/secrets/extensionPoints.php b/tests/phpunit/tests/secrets/extensionPoints.php index 8a4502d90b6b9..95ceb8a22f6bd 100644 --- a/tests/phpunit/tests/secrets/extensionPoints.php +++ b/tests/phpunit/tests/secrets/extensionPoints.php @@ -167,9 +167,9 @@ public function test_listing_fails_closed_when_the_store_cannot_list(): void { $result = wp_list_secrets(); - $this->assertWPError( $result, 'A store that cannot list must be reported as an error, not an empty list.' ); + $this->assertWPError( $result, 'A store that cannot list should be reported as an error, not an empty list.' ); $this->assertSame( WP_SECRETS_ERROR_STORE_UNAVAILABLE, $result->get_error_code(), 'The store error should be passed through unchanged.' ); - $this->assertNeverContainsPlaintext( 'UNIQUE-PLAINTEXT-CANARY-5c1e', $result, 'A listing error must never carry a stored value.' ); + $this->assertNeverContainsPlaintext( 'UNIQUE-PLAINTEXT-CANARY-5c1e', $result, 'A listing error should never carry a stored value.' ); } /** diff --git a/tests/phpunit/tests/secrets/siteHealth.php b/tests/phpunit/tests/secrets/siteHealth.php index 62176fa504fce..c0db84bd632db 100644 --- a/tests/phpunit/tests/secrets/siteHealth.php +++ b/tests/phpunit/tests/secrets/siteHealth.php @@ -322,7 +322,7 @@ public function test_debug_info_includes_network_fields_only_for_a_super_admin() wp_set_current_user( $user_id ); $info = wp_secrets_site_health_debug_info( array() ); - $this->assertArrayNotHasKey( 'network_secret_count', $this->debug_fields( $info ), 'A non-super-admin must not see network secret counts.' ); + $this->assertArrayNotHasKey( 'network_secret_count', $this->debug_fields( $info ), 'A non-super-admin should not see network secret counts.' ); grant_super_admin( $user_id ); diff --git a/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php b/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php index aca749bbace59..9d0d51173d3e1 100644 --- a/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php +++ b/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php @@ -146,7 +146,7 @@ public function test_the_options_table_contains_no_plaintext_after_a_write(): vo $this->assertNeverContainsPlaintext( 'UNIQUE-PLAINTEXT-CANARY-9f3a', $wpdb->get_results( "SELECT option_name, option_value FROM {$wpdb->options}", ARRAY_A ), - 'The options table must never contain a plaintext secret.' + 'The options table should never contain a plaintext secret.' ); } From afaa80922aa84ca7681a870589695137704290ec Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 10:51:24 +1100 Subject: [PATCH 16/28] Assert writes succeed. --- .../class-wp-secrets-provider-conformance.php | 24 +++---- .../phpunit/tests/secrets/extensionPoints.php | 15 ++++- tests/phpunit/tests/secrets/networkScope.php | 38 +++++------ tests/phpunit/tests/secrets/siteHealth.php | 14 ++-- .../tests/secrets/threeStateContract.php | 14 ++-- tests/phpunit/tests/secrets/versionSlots.php | 66 +++++++++---------- .../phpunit/tests/secrets/wpDeleteSecret.php | 10 +-- .../tests/secrets/wpImportOptionAsSecret.php | 12 ++-- tests/phpunit/tests/secrets/wpListSecrets.php | 26 ++++---- .../tests/secrets/wpSecretsOptionStore.php | 20 +++--- .../secrets/wpSetSecretAndWpGetSecret.php | 16 ++--- 11 files changed, 132 insertions(+), 123 deletions(-) diff --git a/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php b/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php index dc18cb2fd74da..e9760571c2af5 100644 --- a/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php +++ b/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php @@ -222,7 +222,7 @@ public function test_retiring_with_no_previous_version_is_success(): void { $this->require_writable( $provider ); $name = $this->conformance_name(); - $provider->set( $name, 'value' ); + $this->assertTrue( $provider->set( $name, 'value' ), 'Setting the secret to value should succeed.' ); $this->assertNotWPError( $provider->retire_previous( $name ), 'The provider should treat retiring with no previous version as success.' ); } @@ -261,7 +261,7 @@ public function test_a_fingerprint_is_stable_for_the_same_value(): void { $this->require_writable( $provider ); $name = $this->conformance_name(); - $provider->set( $name, 'stable-value' ); + $this->assertTrue( $provider->set( $name, 'stable-value' ), 'Setting the secret to stable-value should succeed.' ); $first_read = $provider->get( $name, WP_Secret_Version::CURRENT ); $second_read = $provider->get( $name, WP_Secret_Version::CURRENT ); @@ -295,8 +295,8 @@ public function test_writing_an_unchanged_value_keeps_the_previous_version(): vo $this->require_writable( $provider ); $name = $this->conformance_name(); - $provider->set( $name, 'first-value' ); - $provider->set( $name, 'second-value' ); + $this->assertTrue( $provider->set( $name, 'first-value' ), 'Setting the secret to first-value should succeed.' ); + $this->assertTrue( $provider->set( $name, 'second-value' ), 'Setting the secret to second-value should succeed.' ); $previous = $provider->get( $name, WP_Secret_Version::PREVIOUS ); @@ -323,7 +323,7 @@ public function test_a_deleted_secret_reads_as_absent(): void { $this->require_writable( $provider ); $name = $this->conformance_name(); - $provider->set( $name, 'value' ); + $this->assertTrue( $provider->set( $name, 'value' ), 'Setting the secret to value should succeed.' ); $this->assertNotWPError( $provider->delete( $name ), 'The provider should accept the delete.' ); $this->assertNull( $provider->get( $name, WP_Secret_Version::CURRENT ), 'The provider should report a deleted secret as null.' ); @@ -411,7 +411,7 @@ public function test_deleting_a_secret_reports_a_change(): void { $this->require_writable( $provider ); $name = $this->conformance_name(); - $provider->set( $name, 'value' ); + $this->assertTrue( $provider->set( $name, 'value' ), 'Setting the secret to value should succeed.' ); $this->record_changes(); @@ -434,8 +434,8 @@ public function test_retiring_a_previous_version_reports_a_change(): void { $this->require_writable( $provider ); $name = $this->conformance_name(); - $provider->set( $name, 'first-value' ); - $provider->set( $name, 'second-value' ); + $this->assertTrue( $provider->set( $name, 'first-value' ), 'Setting the secret to first-value should succeed.' ); + $this->assertTrue( $provider->set( $name, 'second-value' ), 'Setting the secret to second-value should succeed.' ); if ( ! $this->has_previous_version( $provider, $name ) ) { $this->markTestSkipped( 'Provider keeps no previous version; there is nothing to retire.' ); @@ -487,7 +487,7 @@ public function test_listing_never_contains_a_stored_value(): void { $this->require_writable( $provider ); $name = $this->conformance_name(); - $provider->set( $name, 'UNIQUE-CONFORMANCE-CANARY-3f9b' ); + $this->assertTrue( $provider->set( $name, 'UNIQUE-CONFORMANCE-CANARY-3f9b' ), 'Setting the secret to UNIQUE-CONFORMANCE-CANARY-3f9b should succeed.' ); $entries = $provider->list_secrets(); @@ -513,7 +513,7 @@ public function test_listing_includes_a_stored_secret(): void { $this->require_writable( $provider ); $name = $this->conformance_name(); - $provider->set( $name, 'value' ); + $this->assertTrue( $provider->set( $name, 'value' ), 'Setting the secret to value should succeed.' ); $entries = $provider->list_secrets(); @@ -532,8 +532,8 @@ public function test_listing_respects_a_name_prefix(): void { $provider = $this->provider(); $this->require_writable( $provider ); - $provider->set( 'conformance-a/one', 'value' ); - $provider->set( 'conformance-b/two', 'value' ); + $this->assertTrue( $provider->set( 'conformance-a/one', 'value' ), 'Setting conformance-a/one to value should succeed.' ); + $this->assertTrue( $provider->set( 'conformance-b/two', 'value' ), 'Setting conformance-b/two to value should succeed.' ); $entries = $provider->list_secrets( 'conformance-a' ); diff --git a/tests/phpunit/tests/secrets/extensionPoints.php b/tests/phpunit/tests/secrets/extensionPoints.php index 95ceb8a22f6bd..c516a51548f0c 100644 --- a/tests/phpunit/tests/secrets/extensionPoints.php +++ b/tests/phpunit/tests/secrets/extensionPoints.php @@ -105,7 +105,7 @@ public function test_read_succeeds_while_write_fails(): void { $store = new Mock_Store(); $GLOBALS['wp_secrets_store'] = $store; - wp_set_secret( 'myplugin/api-key', 'seeded-before-write-broke' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'seeded-before-write-broke' ), 'Setting myplugin/api-key to seeded-before-write-broke should succeed.' ); $store->configure_fail( 'set', true ); @@ -128,6 +128,9 @@ public function test_read_succeeds_while_write_fails(): void { * @preserveGlobalState disabled */ public function test_unreachable_store_fails_closed_with_no_local_fallback(): void { + // Isolated, so this test supplies the site key rather than relying on the test config's salts. + define( 'WP_SECRETS_KEY', base64_encode( str_repeat( 'k', 32 ) ) ); + $store = new Mock_Store(); $GLOBALS['wp_secrets_store'] = $store->configure_fail( 'get', true )->configure_fail( 'set', true ); @@ -135,7 +138,9 @@ public function test_unreachable_store_fails_closed_with_no_local_fallback(): vo $get_result = wp_get_secret( 'myplugin/api-key' ); $this->assertWPError( $set_result, 'A write to an unreachable store should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_STORE_UNAVAILABLE, $set_result->get_error_code(), 'A write to an unreachable store should report the store as unavailable.' ); $this->assertWPError( $get_result, 'A read from an unreachable store should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_STORE_UNAVAILABLE, $get_result->get_error_code(), 'A read from an unreachable store should report the store as unavailable.' ); /* * Fails closed, not merely differently: nothing was written to the real @@ -162,7 +167,7 @@ public function test_listing_fails_closed_when_the_store_cannot_list(): void { $store = new Mock_Store(); $GLOBALS['wp_secrets_store'] = $store; - wp_set_secret( 'myplugin/api-key', 'UNIQUE-PLAINTEXT-CANARY-5c1e' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'UNIQUE-PLAINTEXT-CANARY-5c1e' ), 'Setting myplugin/api-key to UNIQUE-PLAINTEXT-CANARY-5c1e should succeed.' ); $store->configure_fail( 'list', true ); $result = wp_list_secrets(); @@ -202,11 +207,15 @@ public function test_unreachable_keyring_fails_closed_with_no_local_fallback(): * @preserveGlobalState disabled */ public function test_the_store_is_never_handed_a_plaintext(): void { + // Isolated, so this test supplies the site key rather than relying on the test config's salts. + define( 'WP_SECRETS_KEY', base64_encode( str_repeat( 'k', 32 ) ) ); + $store = new Mock_Store(); $GLOBALS['wp_secrets_store'] = $store; - wp_set_secret( 'myplugin/api-key', 'UNIQUE-PLAINTEXT-CANARY-9f3a' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'UNIQUE-PLAINTEXT-CANARY-9f3a' ), 'Setting myplugin/api-key to UNIQUE-PLAINTEXT-CANARY-9f3a should succeed.' ); + $this->assertNotEmpty( $store->get_received_records(), 'The store should have been handed the encrypted record.' ); $this->assertNeverContainsPlaintext( 'UNIQUE-PLAINTEXT-CANARY-9f3a', $store->get_received_records(), diff --git a/tests/phpunit/tests/secrets/networkScope.php b/tests/phpunit/tests/secrets/networkScope.php index ef46a003995ec..65fe608ee9e59 100644 --- a/tests/phpunit/tests/secrets/networkScope.php +++ b/tests/phpunit/tests/secrets/networkScope.php @@ -41,8 +41,8 @@ public function test_get_returns_null_for_an_absent_secret(): void { * @covers ::wp_get_network_secret */ public function test_site_and_network_scope_are_independent_under_the_same_name(): void { - wp_set_secret( 'myplugin/api-key', 'site-value' ); - wp_set_network_secret( 'myplugin/api-key', 'network-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'site-value' ), 'Setting myplugin/api-key to site-value should succeed.' ); + $this->assertTrue( wp_set_network_secret( 'myplugin/api-key', 'network-value' ), 'Setting network secret myplugin/api-key to network-value should succeed.' ); $site_secret = wp_get_secret( 'myplugin/api-key' ); $network_secret = wp_get_network_secret( 'myplugin/api-key' ); @@ -59,7 +59,7 @@ public function test_site_and_network_scope_are_independent_under_the_same_name( * @covers ::wp_delete_network_secret */ public function test_delete_removes_a_network_secret(): void { - wp_set_network_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_network_secret( 'myplugin/api-key', 'value' ), 'Setting network secret myplugin/api-key to value should succeed.' ); $this->assertTrue( wp_delete_network_secret( 'myplugin/api-key' ), 'Deleting a network secret should succeed.' ); $this->assertNull( wp_get_network_secret( 'myplugin/api-key' ), 'A deleted network secret should be null.' ); @@ -71,10 +71,10 @@ public function test_delete_removes_a_network_secret(): void { * @covers ::wp_delete_network_secret */ public function test_delete_does_not_touch_the_site_scope_secret_of_the_same_name(): void { - wp_set_secret( 'myplugin/api-key', 'site-value' ); - wp_set_network_secret( 'myplugin/api-key', 'network-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'site-value' ), 'Setting myplugin/api-key to site-value should succeed.' ); + $this->assertTrue( wp_set_network_secret( 'myplugin/api-key', 'network-value' ), 'Setting network secret myplugin/api-key to network-value should succeed.' ); - wp_delete_network_secret( 'myplugin/api-key' ); + $this->assertTrue( wp_delete_network_secret( 'myplugin/api-key' ), 'Deleting network secret myplugin/api-key should succeed.' ); $site_secret = wp_get_secret( 'myplugin/api-key' ); @@ -88,8 +88,8 @@ public function test_delete_does_not_touch_the_site_scope_secret_of_the_same_nam * @covers ::wp_set_network_secret */ public function test_overwriting_a_network_secret_demotes_the_old_value(): void { - wp_set_network_secret( 'myplugin/api-key', 'first-value' ); - wp_set_network_secret( 'myplugin/api-key', 'second-value' ); + $this->assertTrue( wp_set_network_secret( 'myplugin/api-key', 'first-value' ), 'Setting network secret myplugin/api-key to first-value should succeed.' ); + $this->assertTrue( wp_set_network_secret( 'myplugin/api-key', 'second-value' ), 'Setting network secret myplugin/api-key to second-value should succeed.' ); $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::PREVIOUS, 'first-value', true, 'The previous slot should decrypt to the first network value.' ); $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::CURRENT, 'second-value', true, 'The current slot should decrypt to the second network value.' ); @@ -101,8 +101,8 @@ public function test_overwriting_a_network_secret_demotes_the_old_value(): void * @covers ::wp_retire_network_secret_version */ public function test_retire_clears_the_previous_slot(): void { - wp_set_network_secret( 'myplugin/api-key', 'first-value' ); - wp_set_network_secret( 'myplugin/api-key', 'second-value' ); + $this->assertTrue( wp_set_network_secret( 'myplugin/api-key', 'first-value' ), 'Setting network secret myplugin/api-key to first-value should succeed.' ); + $this->assertTrue( wp_set_network_secret( 'myplugin/api-key', 'second-value' ), 'Setting network secret myplugin/api-key to second-value should succeed.' ); $this->assertTrue( wp_retire_network_secret_version( 'myplugin/api-key' ), 'Retiring the previous network version should succeed.' ); $this->assertNull( wp_get_network_secret( 'myplugin/api-key', WP_Secret_Version::PREVIOUS ), 'The previous network version should be gone after retiring it.' ); @@ -128,11 +128,11 @@ function ( ...$args ) use ( &$scopes ) { 7 ); - wp_set_network_secret( 'myplugin/api-key', 'first-value' ); - wp_set_network_secret( 'myplugin/api-key', 'second-value' ); - wp_retire_network_secret_version( 'myplugin/api-key' ); - wp_delete_network_secret( 'myplugin/api-key' ); - wp_set_secret( 'myplugin/api-key', 'site-value' ); + $this->assertTrue( wp_set_network_secret( 'myplugin/api-key', 'first-value' ), 'Setting network secret myplugin/api-key to first-value should succeed.' ); + $this->assertTrue( wp_set_network_secret( 'myplugin/api-key', 'second-value' ), 'Setting network secret myplugin/api-key to second-value should succeed.' ); + $this->assertTrue( wp_retire_network_secret_version( 'myplugin/api-key' ), 'Retiring the previous version of network secret myplugin/api-key should succeed.' ); + $this->assertTrue( wp_delete_network_secret( 'myplugin/api-key' ), 'Deleting network secret myplugin/api-key should succeed.' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'site-value' ), 'Setting myplugin/api-key to site-value should succeed.' ); $this->assertSame( array( @@ -153,8 +153,8 @@ function ( ...$args ) use ( &$scopes ) { * @covers ::wp_list_network_secrets */ public function test_list_returns_network_secrets_only(): void { - wp_set_secret( 'myplugin/site-only', 'value' ); - wp_set_network_secret( 'myplugin/network-only', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/site-only', 'value' ), 'Setting myplugin/site-only to value should succeed.' ); + $this->assertTrue( wp_set_network_secret( 'myplugin/network-only', 'value' ), 'Setting network secret myplugin/network-only to value should succeed.' ); $entries = wp_list_network_secrets(); @@ -201,7 +201,7 @@ public function test_network_secret_is_readable_from_any_blog(): void { $this->markTestSkipped( 'Requires multisite: proves network secrets are not bound to the blog that wrote them.' ); } - wp_set_network_secret( 'myplugin/api-key', 'cross-blog-value' ); + $this->assertTrue( wp_set_network_secret( 'myplugin/api-key', 'cross-blog-value' ), 'Setting network secret myplugin/api-key to cross-blog-value should succeed.' ); $second_blog_id = self::factory()->blog->create(); switch_to_blog( $second_blog_id ); @@ -224,7 +224,7 @@ public function test_site_secret_is_not_readable_from_a_different_blog(): void { $this->markTestSkipped( 'Requires multisite: proves site secrets do not leak across blogs.' ); } - wp_set_secret( 'myplugin/api-key', 'blog-one-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'blog-one-value' ), 'Setting myplugin/api-key to blog-one-value should succeed.' ); $second_blog_id = self::factory()->blog->create(); switch_to_blog( $second_blog_id ); diff --git a/tests/phpunit/tests/secrets/siteHealth.php b/tests/phpunit/tests/secrets/siteHealth.php index c0db84bd632db..a5da1d1ec4895 100644 --- a/tests/phpunit/tests/secrets/siteHealth.php +++ b/tests/phpunit/tests/secrets/siteHealth.php @@ -142,7 +142,7 @@ public function test_key_source_test_is_critical_when_the_keyring_is_broken(): v * @covers ::wp_secrets_site_health_test_undecryptable */ public function test_undecryptable_test_is_good_when_nothing_is_broken(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $result = wp_secrets_site_health_test_undecryptable(); @@ -168,7 +168,7 @@ public function test_undecryptable_test_is_good_with_no_secrets_at_all(): void { * @covers ::wp_secrets_site_health_test_undecryptable */ public function test_undecryptable_test_is_critical_and_lists_the_broken_secret(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $secret = wp_get_secret( 'myplugin/api-key' ); $this->assertInstanceOf( WP_Secret::class, $secret, 'The stored secret should be retrievable as a WP_Secret.' ); @@ -196,7 +196,7 @@ public function test_undecryptable_test_is_critical_and_lists_the_broken_secret( * @covers ::wp_secrets_site_health_test_undecryptable */ public function test_undecryptable_test_never_contains_a_plaintext(): void { - wp_set_secret( 'myplugin/api-key', 'UNIQUE-PLAINTEXT-CANARY-9f3a' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'UNIQUE-PLAINTEXT-CANARY-9f3a' ), 'Setting myplugin/api-key to UNIQUE-PLAINTEXT-CANARY-9f3a should succeed.' ); $record = get_option( '_wp_secret_myplugin/api-key' ); @@ -218,7 +218,7 @@ public function test_undecryptable_test_never_contains_a_plaintext(): void { * @covers ::wp_secrets_site_health_test_needs_rotation */ public function test_needs_rotation_test_is_good_by_default(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $result = wp_secrets_site_health_test_needs_rotation(); @@ -232,7 +232,7 @@ public function test_needs_rotation_test_is_good_by_default(): void { */ public function test_needs_rotation_test_is_recommended_after_an_import(): void { update_option( 'my_plugin_api_key', 'value' ); - wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ); + $this->assertTrue( wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ), 'Importing my_plugin_api_key as myplugin/api-key should succeed.' ); $result = wp_secrets_site_health_test_needs_rotation(); @@ -246,7 +246,7 @@ public function test_needs_rotation_test_is_recommended_after_an_import(): void * @covers ::wp_secrets_site_health_debug_info */ public function test_debug_info_reports_expected_fields(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $info = wp_secrets_site_health_debug_info( array() ); $fields = $this->debug_fields( $info ); @@ -286,7 +286,7 @@ public function test_debug_info_reports_no_dropin_by_default(): void { * @covers ::wp_secrets_site_health_debug_info */ public function test_debug_info_never_contains_a_plaintext(): void { - wp_set_secret( 'myplugin/api-key', 'UNIQUE-PLAINTEXT-CANARY-9f3a' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'UNIQUE-PLAINTEXT-CANARY-9f3a' ), 'Setting myplugin/api-key to UNIQUE-PLAINTEXT-CANARY-9f3a should succeed.' ); $info = wp_secrets_site_health_debug_info( array() ); diff --git a/tests/phpunit/tests/secrets/threeStateContract.php b/tests/phpunit/tests/secrets/threeStateContract.php index cbef8e6219125..3e2092e84ac85 100644 --- a/tests/phpunit/tests/secrets/threeStateContract.php +++ b/tests/phpunit/tests/secrets/threeStateContract.php @@ -28,7 +28,7 @@ public function test_absent_is_null(): void { * @covers ::wp_get_secret */ public function test_previous_slot_absent_on_an_existing_secret_is_also_null(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $result = wp_get_secret( 'myplugin/api-key', WP_Secret_Version::PREVIOUS ); @@ -102,7 +102,7 @@ public function test_unsupported_record_version_is_wp_error_not_null(): void { * @covers ::wp_get_secret */ public function test_aad_mismatch_from_a_copied_record_is_wp_error_not_null(): void { - wp_set_secret( 'myplugin/original-name', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/original-name', 'value' ), 'Setting myplugin/original-name to value should succeed.' ); $copied_record = get_option( '_wp_secret_myplugin/original-name' ); update_option( '_wp_secret_myplugin/different-name', $copied_record, false ); @@ -139,7 +139,7 @@ public function test_key_unavailable_is_wp_error_not_null(): void { new WP_Secrets_Option_Store(), new WP_Secrets_Key_Manager( new WP_Secrets_Config_Key_Provider() ) ); - $provider->set( 'myplugin/api-key', 'value' ); + $this->assertTrue( $provider->set( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); define( 'WP_SECRETS_KEY', 424242 ); @@ -160,7 +160,7 @@ public function test_key_unavailable_is_wp_error_not_null(): void { * @covers WP_Secrets_Key_Manager::get_master_key */ public function test_a_corrupted_wrapped_root_key_is_wp_error_not_null(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); update_site_option( WP_Secrets_Key_Manager::ROOT_KEY_OPTION, 'not-a-valid-wrapped-value' ); @@ -182,7 +182,7 @@ public function test_a_corrupted_wrapped_root_key_is_wp_error_not_null(): void { * @covers ::wp_get_secret */ public function test_record_missing_its_fingerprint_field_still_returns_a_secret(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $record = get_option( '_wp_secret_myplugin/api-key' ); @@ -208,7 +208,7 @@ public function test_record_missing_its_fingerprint_field_still_returns_a_secret * @covers ::wp_get_secret */ public function test_fingerprint_is_recomputed_not_read_from_the_record(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $before = wp_get_secret( 'myplugin/api-key' ); $this->assertInstanceOf( WP_Secret::class, $before, 'The secret should be a WP_Secret before the fingerprint is tampered with.' ); @@ -235,7 +235,7 @@ public function test_fingerprint_is_recomputed_not_read_from_the_record(): void * @covers ::wp_get_secret */ public function test_exists_and_decrypts_is_a_wp_secret(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $result = wp_get_secret( 'myplugin/api-key' ); diff --git a/tests/phpunit/tests/secrets/versionSlots.php b/tests/phpunit/tests/secrets/versionSlots.php index d65540d5c3997..8e1ee5b27b345 100644 --- a/tests/phpunit/tests/secrets/versionSlots.php +++ b/tests/phpunit/tests/secrets/versionSlots.php @@ -35,8 +35,8 @@ private function stored_slot( string $slot ): array { * @covers ::wp_get_secret */ public function test_previous_returns_the_actual_prior_value(): void { - wp_set_secret( 'myplugin/api-key', 'first-value' ); - wp_set_secret( 'myplugin/api-key', 'second-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'first-value' ), 'Setting myplugin/api-key to first-value should succeed.' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'second-value' ), 'Setting myplugin/api-key to second-value should succeed.' ); $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::PREVIOUS, 'first-value', false, 'The previous slot should decrypt to the first value.' ); $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::CURRENT, 'second-value', false, 'The current slot should decrypt to the second value.' ); @@ -49,9 +49,9 @@ public function test_previous_returns_the_actual_prior_value(): void { * @covers WP_Secrets_Libsodium_Provider::set */ public function test_third_write_discards_the_oldest_value(): void { - wp_set_secret( 'myplugin/api-key', 'value-a' ); - wp_set_secret( 'myplugin/api-key', 'value-b' ); - wp_set_secret( 'myplugin/api-key', 'value-c' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value-a' ), 'Setting myplugin/api-key to value-a should succeed.' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value-b' ), 'Setting myplugin/api-key to value-b should succeed.' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value-c' ), 'Setting myplugin/api-key to value-c should succeed.' ); $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::PREVIOUS, 'value-b', false, 'The previous slot should decrypt to the second of three values.' ); @@ -72,9 +72,9 @@ public function test_third_write_discards_the_oldest_value(): void { * @covers ::wp_get_secret */ public function test_rewriting_the_current_value_keeps_the_previous_slot(): void { - wp_set_secret( 'myplugin/api-key', 'first-value' ); - wp_set_secret( 'myplugin/api-key', 'second-value' ); - wp_set_secret( 'myplugin/api-key', 'second-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'first-value' ), 'Setting myplugin/api-key to first-value should succeed.' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'second-value' ), 'Setting myplugin/api-key to second-value should succeed.' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'second-value' ), 'Setting myplugin/api-key to second-value again should succeed.' ); $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::PREVIOUS, 'first-value', false, 'Rewriting the current value should leave the previous slot holding the first value.' ); $this->assertRecordSlotDecryptsTo( 'myplugin/api-key', WP_Secret_Version::CURRENT, 'second-value', false, 'The current slot should still decrypt to the rewritten value.' ); @@ -89,8 +89,8 @@ public function test_rewriting_the_current_value_keeps_the_previous_slot(): void * @covers WP_Secrets_Libsodium_Provider::set */ public function test_rewriting_the_current_value_leaves_the_stored_record_untouched(): void { - wp_set_secret( 'myplugin/api-key', 'first-value' ); - wp_set_secret( 'myplugin/api-key', 'second-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'first-value' ), 'Setting myplugin/api-key to first-value should succeed.' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'second-value' ), 'Setting myplugin/api-key to second-value should succeed.' ); $before = get_option( '_wp_secret_myplugin/api-key' ); $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'second-value' ), 'Rewriting the current value should report success.' ); @@ -106,7 +106,7 @@ public function test_rewriting_the_current_value_leaves_the_stored_record_untouc * @covers ::wp_set_secret */ public function test_rewriting_the_current_value_does_not_fire_the_change_hook(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $fired = false; add_action( @@ -116,7 +116,7 @@ function () use ( &$fired ) { } ); - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value again should succeed.' ); $this->assertFalse( $fired, 'Rewriting the current value should not fire wp_secret_changed.' ); } @@ -131,9 +131,9 @@ function () use ( &$fired ) { */ public function test_rewriting_the_current_value_keeps_its_needs_rotation_flag(): void { update_option( 'my_plugin_api_key', 'imported-value' ); - wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ); + $this->assertTrue( wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ), 'Importing my_plugin_api_key as myplugin/api-key should succeed.' ); - wp_set_secret( 'myplugin/api-key', 'imported-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'imported-value' ), 'Setting myplugin/api-key to imported-value should succeed.' ); $this->assertTrue( $this->stored_slot( WP_Secret_Version::CURRENT )['needs_rotation'], 'Rewriting an imported value should keep its needs_rotation flag.' ); } @@ -149,8 +149,8 @@ public function test_rewriting_the_current_value_keeps_its_needs_rotation_flag() * @covers WP_Secrets_Libsodium_Provider::set */ public function test_importing_the_current_value_flags_it_and_keeps_the_previous_slot(): void { - wp_set_secret( 'myplugin/api-key', 'first-value' ); - wp_set_secret( 'myplugin/api-key', 'second-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'first-value' ), 'Setting myplugin/api-key to first-value should succeed.' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'second-value' ), 'Setting myplugin/api-key to second-value should succeed.' ); update_option( 'my_plugin_api_key', 'second-value' ); $this->assertTrue( wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ), 'Importing an option holding the current value should succeed.' ); @@ -167,12 +167,12 @@ public function test_importing_the_current_value_flags_it_and_keeps_the_previous * @covers ::wp_get_secret */ public function test_previous_preserves_its_original_fingerprint(): void { - wp_set_secret( 'myplugin/api-key', 'first-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'first-value' ), 'Setting myplugin/api-key to first-value should succeed.' ); $original = wp_get_secret( 'myplugin/api-key' ); $this->assertInstanceOf( WP_Secret::class, $original, 'The first value should be readable as a WP_Secret.' ); $original_fingerprint = $original->fingerprint(); - wp_set_secret( 'myplugin/api-key', 'second-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'second-value' ), 'Setting myplugin/api-key to second-value should succeed.' ); $previous = wp_get_secret( 'myplugin/api-key', WP_Secret_Version::PREVIOUS ); $this->assertInstanceOf( WP_Secret::class, $previous, 'The demoted value should be readable as a WP_Secret.' ); @@ -186,10 +186,10 @@ public function test_previous_preserves_its_original_fingerprint(): void { * @covers WP_Secrets_Libsodium_Provider::set */ public function test_previous_preserves_its_original_created_timestamp(): void { - wp_set_secret( 'myplugin/api-key', 'first-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'first-value' ), 'Setting myplugin/api-key to first-value should succeed.' ); $original_created = $this->stored_slot( WP_Secret_Version::CURRENT )['created']; - wp_set_secret( 'myplugin/api-key', 'second-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'second-value' ), 'Setting myplugin/api-key to second-value should succeed.' ); $demoted_created = $this->stored_slot( WP_Secret_Version::PREVIOUS )['created']; @@ -203,7 +203,7 @@ public function test_previous_preserves_its_original_created_timestamp(): void { * @covers WP_Secrets_Libsodium_Provider::set */ public function test_previous_preserves_its_needs_rotation_flag(): void { - wp_set_secret( 'myplugin/api-key', 'first-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'first-value' ), 'Setting myplugin/api-key to first-value should succeed.' ); /* * Set the flag directly rather than through wp_import_option_as_secret(), so @@ -216,7 +216,7 @@ public function test_previous_preserves_its_needs_rotation_flag(): void { $record['current']['needs_rotation'] = true; update_option( '_wp_secret_myplugin/api-key', $record, false ); - wp_set_secret( 'myplugin/api-key', 'second-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'second-value' ), 'Setting myplugin/api-key to second-value should succeed.' ); $this->assertTrue( $this->stored_slot( WP_Secret_Version::PREVIOUS )['needs_rotation'], 'The demoted value should keep its needs_rotation flag.' ); } @@ -232,10 +232,10 @@ public function test_previous_preserves_its_needs_rotation_flag(): void { * @covers WP_Secrets_Libsodium_Provider::set */ public function test_demotion_actually_reencrypts_rather_than_copying_ciphertext(): void { - wp_set_secret( 'myplugin/api-key', 'first-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'first-value' ), 'Setting myplugin/api-key to first-value should succeed.' ); $original_ciphertext = $this->stored_slot( WP_Secret_Version::CURRENT )['ct']; - wp_set_secret( 'myplugin/api-key', 'second-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'second-value' ), 'Setting myplugin/api-key to second-value should succeed.' ); $demoted_ciphertext = $this->stored_slot( WP_Secret_Version::PREVIOUS )['ct']; @@ -256,7 +256,7 @@ public function test_demotion_actually_reencrypts_rather_than_copying_ciphertext * @covers ::wp_get_secret */ public function test_a_write_succeeds_even_if_the_outgoing_current_slot_cannot_be_decrypted(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $record = get_option( '_wp_secret_myplugin/api-key' ); $this->assertIsArray( $record, 'The stored record should be an array.' ); @@ -279,8 +279,8 @@ public function test_a_write_succeeds_even_if_the_outgoing_current_slot_cannot_b * @covers ::wp_retire_secret_version */ public function test_retire_clears_previous_and_leaves_current_intact(): void { - wp_set_secret( 'myplugin/api-key', 'first-value' ); - wp_set_secret( 'myplugin/api-key', 'second-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'first-value' ), 'Setting myplugin/api-key to first-value should succeed.' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'second-value' ), 'Setting myplugin/api-key to second-value should succeed.' ); $this->assertTrue( wp_retire_secret_version( 'myplugin/api-key' ), 'Retiring the previous version should succeed.' ); @@ -296,7 +296,7 @@ public function test_retire_clears_previous_and_leaves_current_intact(): void { * @covers ::wp_retire_secret_version */ public function test_retire_on_a_secret_with_no_previous_slot_is_a_successful_noop(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $this->assertTrue( wp_retire_secret_version( 'myplugin/api-key' ), 'Retiring with no previous version should report success.' ); } @@ -328,11 +328,11 @@ public function test_retire_rejects_an_invalid_name(): void { * @covers ::wp_retire_secret_version */ public function test_retire_fires_the_change_hook_with_the_retired_action(): void { - wp_set_secret( 'myplugin/api-key', 'first-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'first-value' ), 'Setting myplugin/api-key to first-value should succeed.' ); $original = wp_get_secret( 'myplugin/api-key' ); $this->assertInstanceOf( WP_Secret::class, $original, 'The first value should be readable as a WP_Secret.' ); $fingerprint_being_retired = $original->fingerprint(); - wp_set_secret( 'myplugin/api-key', 'second-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'second-value' ), 'Setting myplugin/api-key to second-value should succeed.' ); $captured = null; add_action( @@ -344,7 +344,7 @@ function ( ...$args ) use ( &$captured ) { 7 ); - wp_retire_secret_version( 'myplugin/api-key' ); + $this->assertTrue( wp_retire_secret_version( 'myplugin/api-key' ), 'Retiring the previous version of myplugin/api-key should succeed.' ); $this->assertIsArray( $captured, 'wp_secret_changed should fire when the previous version is retired.' ); $this->assertCount( 7, $captured, 'wp_secret_changed should be passed seven arguments.' ); @@ -363,7 +363,7 @@ function ( ...$args ) use ( &$captured ) { * @covers ::wp_retire_secret_version */ public function test_retire_does_not_fire_the_change_hook_on_a_noop(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $fired = false; add_action( @@ -373,7 +373,7 @@ function () use ( &$fired ) { } ); - wp_retire_secret_version( 'myplugin/api-key' ); + $this->assertTrue( wp_retire_secret_version( 'myplugin/api-key' ), 'Retiring the previous version of myplugin/api-key should succeed.' ); $this->assertFalse( $fired, 'A no-op retire should not fire wp_secret_changed.' ); } diff --git a/tests/phpunit/tests/secrets/wpDeleteSecret.php b/tests/phpunit/tests/secrets/wpDeleteSecret.php index cbd280008af6a..02e1647735a7a 100644 --- a/tests/phpunit/tests/secrets/wpDeleteSecret.php +++ b/tests/phpunit/tests/secrets/wpDeleteSecret.php @@ -14,7 +14,7 @@ class Tests_Secrets_WpDeleteSecret extends WP_UnitTestCase { * @covers ::wp_delete_secret */ public function test_deletes_an_existing_secret(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $this->assertTrue( wp_delete_secret( 'myplugin/api-key' ), 'Deleting an existing secret should return true.' ); $this->assertNull( wp_get_secret( 'myplugin/api-key' ), 'A deleted secret should no longer be retrievable.' ); @@ -47,7 +47,7 @@ public function test_rejects_an_invalid_name(): void { * @covers ::wp_delete_secret */ public function test_change_hook_fires_with_deleted_action(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $secret = wp_get_secret( 'myplugin/api-key' ); $this->assertInstanceOf( WP_Secret::class, $secret, 'The stored secret should be retrievable as a WP_Secret.' ); @@ -64,7 +64,7 @@ function ( ...$args ) use ( &$captured ) { 7 ); - wp_delete_secret( 'myplugin/api-key' ); + $this->assertTrue( wp_delete_secret( 'myplugin/api-key' ), 'Deleting myplugin/api-key should succeed.' ); $this->assertIsArray( $captured, 'The wp_secret_changed hook should fire.' ); @@ -90,7 +90,7 @@ function () use ( &$fired ) { } ); - wp_delete_secret( 'myplugin/never-set' ); + $this->assertTrue( wp_delete_secret( 'myplugin/never-set' ), 'Deleting myplugin/never-set should succeed.' ); $this->assertFalse( $fired, 'The hook should not fire when nothing was deleted.' ); } @@ -118,7 +118,7 @@ public function test_a_corrupt_record_is_still_deletable(): void { * @covers ::wp_delete_secret */ public function test_no_capability_check_is_applied(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); wp_set_current_user( 0 ); $this->assertTrue( wp_delete_secret( 'myplugin/api-key' ), 'Deleting a secret without a logged-in user should succeed.' ); diff --git a/tests/phpunit/tests/secrets/wpImportOptionAsSecret.php b/tests/phpunit/tests/secrets/wpImportOptionAsSecret.php index 64cc2fc7694b6..a06f71e9acb29 100644 --- a/tests/phpunit/tests/secrets/wpImportOptionAsSecret.php +++ b/tests/phpunit/tests/secrets/wpImportOptionAsSecret.php @@ -32,7 +32,7 @@ public function test_imports_an_existing_option_value(): void { public function test_leaves_the_source_option_untouched(): void { update_option( 'my_plugin_api_key', 'sk_live_from_an_option' ); - wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ); + $this->assertTrue( wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ), 'Importing my_plugin_api_key as myplugin/api-key should succeed.' ); $this->assertSame( 'sk_live_from_an_option', get_option( 'my_plugin_api_key' ), 'The source option should be left unchanged.' ); } @@ -45,7 +45,7 @@ public function test_leaves_the_source_option_untouched(): void { */ public function test_flags_the_imported_secret_for_rotation(): void { update_option( 'my_plugin_api_key', 'value' ); - wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ); + $this->assertTrue( wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ), 'Importing my_plugin_api_key as myplugin/api-key should succeed.' ); $record = get_option( '_wp_secret_myplugin/api-key' ); @@ -65,7 +65,7 @@ public function test_flags_the_imported_secret_for_rotation(): void { * @covers WP_Secrets_Libsodium_Provider::set */ public function test_an_ordinary_write_does_not_flag_needs_rotation(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $record = get_option( '_wp_secret_myplugin/api-key' ); @@ -133,7 +133,7 @@ function ( ...$args ) use ( &$captured ) { 7 ); - wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ); + $this->assertTrue( wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ), 'Importing my_plugin_api_key as myplugin/api-key should succeed.' ); $this->assertIsArray( $captured, 'The wp_secret_changed action should have fired.' ); list( $name, $action ) = $captured; @@ -150,10 +150,10 @@ function ( ...$args ) use ( &$captured ) { * @covers ::wp_import_option_as_secret */ public function test_importing_over_an_existing_secret_demotes_it_like_any_write(): void { - wp_set_secret( 'myplugin/api-key', 'original-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'original-value' ), 'Setting myplugin/api-key to original-value should succeed.' ); update_option( 'my_plugin_api_key', 'imported-value' ); - wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ); + $this->assertTrue( wp_import_option_as_secret( 'my_plugin_api_key', 'myplugin/api-key' ), 'Importing my_plugin_api_key as myplugin/api-key should succeed.' ); $current = wp_get_secret( 'myplugin/api-key' ); $previous = wp_get_secret( 'myplugin/api-key', WP_Secret_Version::PREVIOUS ); diff --git a/tests/phpunit/tests/secrets/wpListSecrets.php b/tests/phpunit/tests/secrets/wpListSecrets.php index 0953d8a889cbb..99116e6afeb21 100644 --- a/tests/phpunit/tests/secrets/wpListSecrets.php +++ b/tests/phpunit/tests/secrets/wpListSecrets.php @@ -23,7 +23,7 @@ public function test_returns_an_empty_array_when_nothing_is_set(): void { * @covers ::wp_list_secrets */ public function test_lists_every_secret_with_the_expected_keys(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $entries = wp_list_secrets(); @@ -44,7 +44,7 @@ public function test_lists_every_secret_with_the_expected_keys(): void { * @covers ::wp_list_secrets */ public function test_never_returns_a_value(): void { - wp_set_secret( 'myplugin/api-key', 'a-plaintext-value-that-must-not-leak' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'a-plaintext-value-that-must-not-leak' ), 'Setting myplugin/api-key to a-plaintext-value-that-must-not-leak should succeed.' ); $dump = wp_json_encode( wp_list_secrets() ); @@ -58,7 +58,7 @@ public function test_never_returns_a_value(): void { * @covers ::wp_list_secrets */ public function test_fingerprint_matches_the_secrets_own_fingerprint(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $secret = wp_get_secret( 'myplugin/api-key' ); $entries = wp_list_secrets(); @@ -74,14 +74,14 @@ public function test_fingerprint_matches_the_secrets_own_fingerprint(): void { * @covers ::wp_list_secrets */ public function test_has_previous_is_false_before_a_rotation_and_true_after(): void { - wp_set_secret( 'myplugin/api-key', 'first-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'first-value' ), 'Setting myplugin/api-key to first-value should succeed.' ); $before = wp_list_secrets(); $this->assertIsArray( $before, 'wp_list_secrets() should return an array before the overwrite.' ); $this->assertFalse( $before[0]['has_previous'], 'has_previous should be false before the secret is overwritten.' ); - wp_set_secret( 'myplugin/api-key', 'second-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'second-value' ), 'Setting myplugin/api-key to second-value should succeed.' ); $after = wp_list_secrets(); @@ -98,7 +98,7 @@ public function test_has_previous_is_false_before_a_rotation_and_true_after(): v * @covers ::wp_list_secrets */ public function test_needs_rotation_reflects_the_current_slots_flag(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $record = get_option( '_wp_secret_myplugin/api-key' ); @@ -121,8 +121,8 @@ public function test_needs_rotation_reflects_the_current_slots_flag(): void { * @covers ::wp_list_secrets */ public function test_filters_by_namespace(): void { - wp_set_secret( 'pluginone/key', 'value' ); - wp_set_secret( 'plugintwo/key', 'value' ); + $this->assertTrue( wp_set_secret( 'pluginone/key', 'value' ), 'Setting pluginone/key to value should succeed.' ); + $this->assertTrue( wp_set_secret( 'plugintwo/key', 'value' ), 'Setting plugintwo/key to value should succeed.' ); $entries = wp_list_secrets( 'pluginone' ); @@ -136,8 +136,8 @@ public function test_filters_by_namespace(): void { * @covers ::wp_list_secrets */ public function test_empty_namespace_returns_everything(): void { - wp_set_secret( 'pluginone/key', 'value' ); - wp_set_secret( 'plugintwo/key', 'value' ); + $this->assertTrue( wp_set_secret( 'pluginone/key', 'value' ), 'Setting pluginone/key to value should succeed.' ); + $this->assertTrue( wp_set_secret( 'plugintwo/key', 'value' ), 'Setting plugintwo/key to value should succeed.' ); $entries = wp_list_secrets( '' ); @@ -152,7 +152,7 @@ public function test_empty_namespace_returns_everything(): void { */ public function test_namespace_does_not_match_a_prefix_of_a_different_namespace(): void { // 'plugin' must not match 'pluginone/key' – only a full "namespace/" prefix. - wp_set_secret( 'pluginone/key', 'value' ); + $this->assertTrue( wp_set_secret( 'pluginone/key', 'value' ), 'Setting pluginone/key to value should succeed.' ); $this->assertSame( array(), wp_list_secrets( 'plugin' ), 'A namespace should not match a prefix of a different namespace.' ); } @@ -181,8 +181,8 @@ public function test_a_corrupt_record_is_still_listed_with_blank_metadata(): voi * @covers ::wp_list_secrets */ public function test_does_not_list_network_scope_secrets(): void { - wp_set_secret( 'myplugin/site-only', 'value' ); - wp_set_network_secret( 'myplugin/network-only', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/site-only', 'value' ), 'Setting myplugin/site-only to value should succeed.' ); + $this->assertTrue( wp_set_network_secret( 'myplugin/network-only', 'value' ), 'Setting network secret myplugin/network-only to value should succeed.' ); $entries = wp_list_secrets(); diff --git a/tests/phpunit/tests/secrets/wpSecretsOptionStore.php b/tests/phpunit/tests/secrets/wpSecretsOptionStore.php index 0b7ccee8342d1..01c472e92b20a 100644 --- a/tests/phpunit/tests/secrets/wpSecretsOptionStore.php +++ b/tests/phpunit/tests/secrets/wpSecretsOptionStore.php @@ -86,8 +86,8 @@ public function test_site_and_network_scope_do_not_collide(): void { $site_record = $this->sample_record(); $network_record = array_merge( $this->sample_record(), array( 'marker' => 'network' ) ); - $store->set( 'myplugin/key', $site_record, false ); - $store->set( 'myplugin/key', $network_record, true ); + $this->assertTrue( $store->set( 'myplugin/key', $site_record, false ), 'Storing the record for myplugin/key in site scope should succeed.' ); + $this->assertTrue( $store->set( 'myplugin/key', $network_record, true ), 'Storing the record for myplugin/key in network scope should succeed.' ); $this->assertSame( $site_record, $store->get( 'myplugin/key', false ), 'The site-scope record should not be overwritten by the network-scope record.' ); $this->assertSame( $network_record, $store->get( 'myplugin/key', true ), 'The network-scope record should be stored separately from the site-scope record.' ); @@ -116,7 +116,7 @@ public function test_get_returns_an_error_when_the_stored_value_is_not_an_array( */ public function test_delete_removes_an_existing_record(): void { $store = new WP_Secrets_Option_Store(); - $store->set( 'myplugin/key', $this->sample_record() ); + $this->assertTrue( $store->set( 'myplugin/key', $this->sample_record() ), 'Storing the record for myplugin/key should succeed.' ); $this->assertTrue( $store->delete( 'myplugin/key' ), 'Deleting an existing record should succeed.' ); $this->assertNull( $store->get( 'myplugin/key' ), 'A deleted record should no longer be returned.' ); @@ -147,7 +147,7 @@ public function test_site_scope_records_are_not_autoloaded(): void { global $wpdb; $store = new WP_Secrets_Option_Store(); - $store->set( 'myplugin/key', $this->sample_record() ); + $this->assertTrue( $store->set( 'myplugin/key', $this->sample_record() ), 'Storing the record for myplugin/key should succeed.' ); $autoload = $wpdb->get_var( $wpdb->prepare( @@ -166,8 +166,8 @@ public function test_site_scope_records_are_not_autoloaded(): void { */ public function test_list_names_returns_stored_names_without_the_prefix(): void { $store = new WP_Secrets_Option_Store(); - $store->set( 'myplugin/one', $this->sample_record() ); - $store->set( 'myplugin/two', $this->sample_record() ); + $this->assertTrue( $store->set( 'myplugin/one', $this->sample_record() ), 'Storing the record for myplugin/one should succeed.' ); + $this->assertTrue( $store->set( 'myplugin/two', $this->sample_record() ), 'Storing the record for myplugin/two should succeed.' ); $names = $store->list_names(); @@ -185,7 +185,7 @@ public function test_list_names_does_not_include_unrelated_options(): void { update_option( 'completely_unrelated_option', 'value' ); $store = new WP_Secrets_Option_Store(); - $store->set( 'myplugin/one', $this->sample_record() ); + $this->assertTrue( $store->set( 'myplugin/one', $this->sample_record() ), 'Storing the record for myplugin/one should succeed.' ); $names = $store->list_names(); @@ -200,8 +200,8 @@ public function test_list_names_does_not_include_unrelated_options(): void { */ public function test_list_names_returns_only_the_requested_scope(): void { $store = new WP_Secrets_Option_Store(); - $store->set( 'myplugin/site-only', $this->sample_record(), false ); - $store->set( 'myplugin/network-only', $this->sample_record(), true ); + $this->assertTrue( $store->set( 'myplugin/site-only', $this->sample_record(), false ), 'Storing the record for myplugin/site-only in site scope should succeed.' ); + $this->assertTrue( $store->set( 'myplugin/network-only', $this->sample_record(), true ), 'Storing the record for myplugin/network-only in network scope should succeed.' ); $site_names = $store->list_names( false ); $network_names = $store->list_names( true ); @@ -229,7 +229,7 @@ public function test_list_names_escapes_the_underscore_wildcard(): void { update_option( '_wpXsecret_decoy/name', 'irrelevant value', false ); $store = new WP_Secrets_Option_Store(); - $store->set( 'myplugin/real', $this->sample_record() ); + $this->assertTrue( $store->set( 'myplugin/real', $this->sample_record() ), 'Storing the record for myplugin/real should succeed.' ); $names = $store->list_names(); diff --git a/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php b/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php index 9d0d51173d3e1..f1ad1e59d4f8c 100644 --- a/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php +++ b/tests/phpunit/tests/secrets/wpSetSecretAndWpGetSecret.php @@ -33,7 +33,7 @@ public function test_set_then_get_round_trips(): void { * @covers ::wp_get_secret */ public function test_get_defaults_to_the_current_version(): void { - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $default = wp_get_secret( 'myplugin/api-key' ); $current = wp_get_secret( 'myplugin/api-key', WP_Secret_Version::CURRENT ); @@ -141,7 +141,7 @@ public function test_the_options_table_contains_no_plaintext_after_a_write(): vo $this->assertInstanceOf( wpdb::class, $wpdb, 'The global $wpdb should be a wpdb instance.' ); - wp_set_secret( 'myplugin/api-key', 'UNIQUE-PLAINTEXT-CANARY-9f3a' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'UNIQUE-PLAINTEXT-CANARY-9f3a' ), 'Setting myplugin/api-key to UNIQUE-PLAINTEXT-CANARY-9f3a should succeed.' ); $this->assertNeverContainsPlaintext( 'UNIQUE-PLAINTEXT-CANARY-9f3a', @@ -160,7 +160,7 @@ public function test_the_options_table_contains_no_plaintext_after_a_write(): vo * @covers ::wp_get_secret */ public function test_reveal_still_works_after_the_internal_memzero(): void { - wp_set_secret( 'myplugin/api-key', 'must-survive-memzero' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'must-survive-memzero' ), 'Setting myplugin/api-key to must-survive-memzero should succeed.' ); $secret = wp_get_secret( 'myplugin/api-key' ); @@ -201,7 +201,7 @@ function ( ...$args ) use ( &$captured ) { ); $before = time(); - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $after = time(); $this->assertNotNull( $captured, 'The wp_secret_changed hook should fire.' ); @@ -223,7 +223,7 @@ function ( ...$args ) use ( &$captured ) { * @covers ::wp_set_secret */ public function test_change_hook_fires_on_overwrite_with_updated_action(): void { - wp_set_secret( 'myplugin/api-key', 'first-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'first-value' ), 'Setting myplugin/api-key to first-value should succeed.' ); $first = wp_get_secret( 'myplugin/api-key' ); $this->assertInstanceOf( WP_Secret::class, $first, 'The first secret should be retrievable as a WP_Secret.' ); @@ -239,7 +239,7 @@ function ( ...$args ) use ( &$captured ) { 7 ); - wp_set_secret( 'myplugin/api-key', 'second-value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'second-value' ), 'Setting myplugin/api-key to second-value should succeed.' ); $this->assertIsArray( $captured, 'The wp_secret_changed hook should fire.' ); list( , $action, , , $old_fingerprint, $new_fingerprint ) = $captured; @@ -268,7 +268,7 @@ function ( $name, $action, $actor_id ) use ( &$captured_actor ) { 3 ); - wp_set_secret( 'myplugin/api-key', 'value' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'value' ), 'Setting myplugin/api-key to value should succeed.' ); $this->assertSame( $user_id, $captured_actor, 'The hook should report the current user as the actor.' ); } @@ -292,7 +292,7 @@ function ( ...$args ) use ( &$captured_args ) { 7 ); - wp_set_secret( 'myplugin/api-key', 'a-plaintext-value-that-must-not-leak' ); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'a-plaintext-value-that-must-not-leak' ), 'Setting myplugin/api-key to a-plaintext-value-that-must-not-leak should succeed.' ); $this->assertIsArray( $captured_args, 'The wp_secret_changed hook should fire.' ); From 8681f9456d6d8dab9d5570fe1c03345e2db594dc Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 10:58:33 +1100 Subject: [PATCH 17/28] Further test hardening. --- tests/phpunit/tests/secrets/extensionPoints.php | 2 ++ tests/phpunit/tests/secrets/siteHealth.php | 1 + tests/phpunit/tests/secrets/wpListSecrets.php | 2 ++ tests/phpunit/tests/secrets/wpSecretsCipher.php | 1 + tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php | 5 +++++ tests/phpunit/tests/secrets/wpSecretsKeyManager.php | 3 ++- 6 files changed, 13 insertions(+), 1 deletion(-) diff --git a/tests/phpunit/tests/secrets/extensionPoints.php b/tests/phpunit/tests/secrets/extensionPoints.php index c516a51548f0c..9d532ef2c95a4 100644 --- a/tests/phpunit/tests/secrets/extensionPoints.php +++ b/tests/phpunit/tests/secrets/extensionPoints.php @@ -147,6 +147,7 @@ public function test_unreachable_store_fails_closed_with_no_local_fallback(): vo * default store either, which a silent fallback would have done. */ $this->assertFalse( get_option( '_wp_secret_myplugin/api-key' ), 'Nothing should be written to the default options store as a fallback.' ); + $this->assertFalse( get_site_option( '_wp_network_secret_myplugin/api-key' ), 'Nothing should be written to the default network store as a fallback.' ); } /** @@ -193,6 +194,7 @@ public function test_unreachable_keyring_fails_closed_with_no_local_fallback(): $this->assertWPError( $result, 'A write through a keyring that cannot wrap should return a WP_Error.' ); $this->assertFalse( get_option( '_wp_secret_myplugin/api-key' ), 'Nothing should be written to the default options store as a fallback.' ); + $this->assertFalse( get_site_option( '_wp_network_secret_myplugin/api-key' ), 'Nothing should be written to the default network store as a fallback.' ); } /** diff --git a/tests/phpunit/tests/secrets/siteHealth.php b/tests/phpunit/tests/secrets/siteHealth.php index a5da1d1ec4895..9212dfdf37759 100644 --- a/tests/phpunit/tests/secrets/siteHealth.php +++ b/tests/phpunit/tests/secrets/siteHealth.php @@ -41,6 +41,7 @@ public function test_registers_three_tests_under_direct(): void { $tests = wp_secrets_site_health_tests( array() ); $this->assertArrayHasKey( 'direct', $tests, 'The registered tests should include a direct group.' ); + $this->assertCount( 3, $tests['direct'], 'Exactly three Secrets API tests should be registered as direct tests.' ); $this->assertArrayHasKey( 'secrets_api_key_source', $tests['direct'], 'The key source test should be registered as a direct test.' ); $this->assertArrayHasKey( 'secrets_api_undecryptable', $tests['direct'], 'The undecryptable test should be registered as a direct test.' ); $this->assertArrayHasKey( 'secrets_api_needs_rotation', $tests['direct'], 'The needs rotation test should be registered as a direct test.' ); diff --git a/tests/phpunit/tests/secrets/wpListSecrets.php b/tests/phpunit/tests/secrets/wpListSecrets.php index 99116e6afeb21..94059c2adbfd9 100644 --- a/tests/phpunit/tests/secrets/wpListSecrets.php +++ b/tests/phpunit/tests/secrets/wpListSecrets.php @@ -65,6 +65,7 @@ public function test_fingerprint_matches_the_secrets_own_fingerprint(): void { $this->assertInstanceOf( WP_Secret::class, $secret, 'The secret should be a WP_Secret.' ); $this->assertIsArray( $entries, 'wp_list_secrets() should return an array.' ); + $this->assertCount( 1, $entries, 'Exactly one secret should be listed.' ); $this->assertSame( $secret->fingerprint(), $entries[0]['fingerprint'], 'The listed fingerprint should match the fingerprint of the secret.' ); } @@ -112,6 +113,7 @@ public function test_needs_rotation_reflects_the_current_slots_flag(): void { $entries = wp_list_secrets(); $this->assertIsArray( $entries, 'wp_list_secrets() should return an array.' ); + $this->assertCount( 1, $entries, 'Exactly one secret should be listed.' ); $this->assertTrue( $entries[0]['needs_rotation'], 'needs_rotation should reflect the flag stored on the current slot.' ); } diff --git a/tests/phpunit/tests/secrets/wpSecretsCipher.php b/tests/phpunit/tests/secrets/wpSecretsCipher.php index a91e7eecd29ea..e0e0626333037 100644 --- a/tests/phpunit/tests/secrets/wpSecretsCipher.php +++ b/tests/phpunit/tests/secrets/wpSecretsCipher.php @@ -276,6 +276,7 @@ public function test_decrypt_fails_when_a_field_is_tampered( $field ): void { $result = $cipher->decrypt_value( $this->master_key(), 'site', 1, self::NAME, WP_Secret_Version::CURRENT, $record ); $this->assertWPError( $result, 'Decrypting a tampered record should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_DECRYPTION_FAILED, $result->get_error_code(), 'A tampered field should be reported as a decryption failure.' ); } /** diff --git a/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php b/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php index 0763811b7ff7a..c064ed1d35df3 100644 --- a/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php +++ b/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php @@ -384,6 +384,11 @@ public function test_previous_key_constant_does_not_leak_into_the_current_key_pa $this->assertNotWPError( $key, 'The current-key provider should derive a site key from the salts.' ); $this->assertNotSame( str_repeat( 'C', 32 ), $key, 'The current-key provider should not use WP_SECRETS_KEY_PREVIOUS.' ); + $this->assertSame( + sodium_crypto_generichash( LOGGED_IN_KEY . LOGGED_IN_SALT, '', SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_KEYBYTES ), + $key, + 'The current-key provider should use the key derived from LOGGED_IN_KEY and LOGGED_IN_SALT.' + ); } /** diff --git a/tests/phpunit/tests/secrets/wpSecretsKeyManager.php b/tests/phpunit/tests/secrets/wpSecretsKeyManager.php index 960f75d863005..dba0b88e915ae 100644 --- a/tests/phpunit/tests/secrets/wpSecretsKeyManager.php +++ b/tests/phpunit/tests/secrets/wpSecretsKeyManager.php @@ -384,6 +384,7 @@ public function get_key_source(): string { $result = $manager->rotate_site_key( $wrong_keyring, $right_keyring ); $this->assertWPError( $result, 'Rotating with an old keyring that cannot unwrap should return a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code(), 'The old keyring\'s unwrap error should be passed through.' ); } /** @@ -475,7 +476,7 @@ public function test_unwrap_is_called_once_across_many_secret_reads(): void { $GLOBALS['wp_secrets_keyring'] = $mock; - $this->assertNotWPError( wp_set_secret( 'conformance/root-key-cache', 'the-value' ), 'Storing the secret should not return a WP_Error.' ); + $this->assertTrue( wp_set_secret( 'conformance/root-key-cache', 'the-value' ), 'Storing the secret should succeed.' ); for ( $i = 0; $i < 10; $i++ ) { $secret = wp_get_secret( 'conformance/root-key-cache' ); From 336229408d62508c9c44316705648d0b341a07bc Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 11:03:35 +1100 Subject: [PATCH 18/28] Rename data providers for their test when used by a single test only. --- tests/phpunit/tests/secrets/capabilities.php | 4 +- tests/phpunit/tests/secrets/wpSecret.php | 8 +-- .../phpunit/tests/secrets/wpSecretsCipher.php | 16 ++--- .../secrets/wpSecretsConfigKeyProvider.php | 8 +-- .../tests/secrets/wpSecretsKeyManager.php | 4 +- .../tests/secrets/wpSecretsValidateName.php | 58 +++++++++---------- 6 files changed, 49 insertions(+), 49 deletions(-) diff --git a/tests/phpunit/tests/secrets/capabilities.php b/tests/phpunit/tests/secrets/capabilities.php index ce46d393ac08c..2133bccd64b1f 100644 --- a/tests/phpunit/tests/secrets/capabilities.php +++ b/tests/phpunit/tests/secrets/capabilities.php @@ -100,7 +100,7 @@ public function test_populate_roles_720_grants_manage_secrets_to_administrator() * * @covers ::upgrade_720 * - * @dataProvider data_upgrade_720_gate + * @dataProvider data_upgrade_720_grants_manage_secrets_below_its_db_version * * @param int $db_version The database version being upgraded from. * @param bool $expect_granted Whether the upgrade should grant the capability. @@ -125,7 +125,7 @@ public function test_upgrade_720_grants_manage_secrets_below_its_db_version( $db * * @return array */ - public static function data_upgrade_720_gate() { + public static function data_upgrade_720_grants_manage_secrets_below_its_db_version() { return array( 'upgrading from 7.0' => array( 61644, true ), 'upgrading from just below 7.2' => array( 64336, true ), diff --git a/tests/phpunit/tests/secrets/wpSecret.php b/tests/phpunit/tests/secrets/wpSecret.php index 7263b972eae93..c001bfd4e1b0b 100644 --- a/tests/phpunit/tests/secrets/wpSecret.php +++ b/tests/phpunit/tests/secrets/wpSecret.php @@ -124,7 +124,7 @@ public function test_constructor_rejects_an_empty_fingerprint(): void { * @covers WP_Secret::jsonSerialize * @covers WP_Secret::__debugInfo * - * @dataProvider data_masking_surfaces + * @dataProvider data_masking_surfaces_never_contain_the_plaintext * * @param callable( WP_Secret ): ( string|false ) $callback Renders the secret through one surface. */ @@ -140,7 +140,7 @@ public function test_masking_surfaces_never_contain_the_plaintext( $callback ): /** * @return array */ - public static function data_masking_surfaces() { + public static function data_masking_surfaces_never_contain_the_plaintext() { return array( '(string) cast' => array( function ( WP_Secret $secret ) { @@ -265,7 +265,7 @@ public function test_clone_throws(): void { * @covers WP_Secret::__serialize * @covers WP_Secret::__unserialize * - * @dataProvider data_refusing_magic_methods + * @dataProvider data_serialization_magic_methods_throw_directly * * @param string $method Magic method name. * @param array $args Arguments to invoke it with. @@ -285,7 +285,7 @@ public function test_serialization_magic_methods_throw_directly( $method, $args /** * @return array}> */ - public static function data_refusing_magic_methods() { + public static function data_serialization_magic_methods_throw_directly() { return array( '__sleep' => array( '__sleep', array() ), '__wakeup' => array( '__wakeup', array() ), diff --git a/tests/phpunit/tests/secrets/wpSecretsCipher.php b/tests/phpunit/tests/secrets/wpSecretsCipher.php index e0e0626333037..fc2a4ea9d693c 100644 --- a/tests/phpunit/tests/secrets/wpSecretsCipher.php +++ b/tests/phpunit/tests/secrets/wpSecretsCipher.php @@ -103,7 +103,7 @@ public function test_encrypt_rejects_a_non_string_value(): void { * * @covers WP_Secrets_Cipher::encrypt_value * - * @dataProvider data_bad_master_keys + * @dataProvider data_encrypt_rejects_a_bad_master_key * * @param string $bad_key Master key the cipher must refuse. */ @@ -119,7 +119,7 @@ public function test_encrypt_rejects_a_bad_master_key( $bad_key ): void { /** * @return array */ - public static function data_bad_master_keys() { + public static function data_encrypt_rejects_a_bad_master_key() { return array( 'too short' => array( str_repeat( 'a', 31 ) ), 'too long' => array( str_repeat( 'a', 33 ) ), @@ -199,7 +199,7 @@ public function test_encrypt_reports_an_invalid_slot_as_a_wp_error(): void { * * @covers WP_Secrets_Cipher::decrypt_value * - * @dataProvider data_mismatched_context + * @dataProvider data_decrypt_fails_when_context_does_not_match * * @param string $scope Scope to decrypt under. * @param int $site_id Site id to decrypt under. @@ -222,7 +222,7 @@ public function test_decrypt_fails_when_context_does_not_match( $scope, $site_id /** * @return array */ - public static function data_mismatched_context() { + public static function data_decrypt_fails_when_context_does_not_match() { return array( 'different scope' => array( 'network', 1, self::NAME, WP_Secret_Version::CURRENT ), 'different site id' => array( 'site', 2, self::NAME, WP_Secret_Version::CURRENT ), @@ -254,7 +254,7 @@ public function test_decrypt_fails_under_a_different_master_key(): void { * * @covers WP_Secrets_Cipher::decrypt_value * - * @dataProvider data_tamperable_fields + * @dataProvider data_decrypt_fails_when_a_field_is_tampered * * @param string $field Record field to corrupt. */ @@ -282,7 +282,7 @@ public function test_decrypt_fails_when_a_field_is_tampered( $field ): void { /** * @return array */ - public static function data_tamperable_fields() { + public static function data_decrypt_fails_when_a_field_is_tampered() { return array( 'ciphertext' => array( 'ct' ), 'value nonce' => array( 'nonce' ), @@ -296,7 +296,7 @@ public static function data_tamperable_fields() { * * @covers WP_Secrets_Cipher::decrypt_value * - * @dataProvider data_malformed_records + * @dataProvider data_decrypt_rejects_a_malformed_record * * @param mixed $record Stored record the cipher must refuse. */ @@ -312,7 +312,7 @@ public function test_decrypt_rejects_a_malformed_record( $record ): void { /** * @return array */ - public static function data_malformed_records() { + public static function data_decrypt_rejects_a_malformed_record() { return array( 'not an array' => array( 'just a string' ), 'missing ct' => array( diff --git a/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php b/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php index c064ed1d35df3..bbc96a8f4a99c 100644 --- a/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php +++ b/tests/phpunit/tests/secrets/wpSecretsConfigKeyProvider.php @@ -173,7 +173,7 @@ public function test_get_key_source_reports_the_salt_fallback_when_wp_secrets_ke * * @covers WP_Secrets_Config_Key_Provider::is_canonical_base64_32 * - * @dataProvider data_canonical_base64_32 + * @dataProvider data_is_canonical_base64_32 * * @param string|int $value Candidate value. * @param bool $expected Whether it is the canonical base64 encoding of 32 bytes. @@ -187,7 +187,7 @@ public function test_is_canonical_base64_32( $value, $expected ): void { /** * @return array */ - public static function data_canonical_base64_32(): array { + public static function data_is_canonical_base64_32(): array { return array( 'exactly 32 bytes, canonical encoding' => array( base64_encode( str_repeat( 'A', 32 ) ), true ), '31 bytes' => array( base64_encode( str_repeat( 'A', 31 ) ), false ), @@ -204,7 +204,7 @@ public static function data_canonical_base64_32(): array { * * @covers WP_Secrets_Config_Key_Provider::are_usable_salt_values * - * @dataProvider data_usable_salt_values + * @dataProvider data_are_usable_salt_values * * @param string|int|null $key Candidate LOGGED_IN_KEY value. * @param string $salt Candidate LOGGED_IN_SALT value. @@ -219,7 +219,7 @@ public function test_are_usable_salt_values( $key, $salt, $expected ): void { /** * @return array */ - public static function data_usable_salt_values(): array { + public static function data_are_usable_salt_values(): array { return array( 'both usable' => array( 'a real key', 'a real salt', true ), 'key is the placeholder' => array( 'put your unique phrase here', 'a real salt', false ), diff --git a/tests/phpunit/tests/secrets/wpSecretsKeyManager.php b/tests/phpunit/tests/secrets/wpSecretsKeyManager.php index dba0b88e915ae..f18d81588a9b5 100644 --- a/tests/phpunit/tests/secrets/wpSecretsKeyManager.php +++ b/tests/phpunit/tests/secrets/wpSecretsKeyManager.php @@ -163,7 +163,7 @@ public function test_get_master_key_reports_an_invalid_scope_as_a_wp_error(): vo * * @covers WP_Secrets_Key_Manager::get_master_key * - * @dataProvider data_invalid_site_ids + * @dataProvider data_get_master_key_reports_an_invalid_site_id_as_a_wp_error * * @param int $site_id A value that is not a usable blog id. */ @@ -181,7 +181,7 @@ public function test_get_master_key_reports_an_invalid_site_id_as_a_wp_error( $s /** * @return array */ - public static function data_invalid_site_ids(): array { + public static function data_get_master_key_reports_an_invalid_site_id_as_a_wp_error(): array { return array( 'zero' => array( 0 ), 'negative' => array( -1 ), diff --git a/tests/phpunit/tests/secrets/wpSecretsValidateName.php b/tests/phpunit/tests/secrets/wpSecretsValidateName.php index aea41f1d6d60d..ad68eae90e416 100644 --- a/tests/phpunit/tests/secrets/wpSecretsValidateName.php +++ b/tests/phpunit/tests/secrets/wpSecretsValidateName.php @@ -11,7 +11,7 @@ class Tests_Secrets_WpSecretsValidateName extends WP_UnitTestCase { * * @covers ::wp_secrets_validate_name * - * @dataProvider data_valid_names + * @dataProvider data_accepts_valid_names * * @param string $name A name that must be accepted. */ @@ -22,7 +22,7 @@ public function test_accepts_valid_names( $name ): void { /** * @return array */ - public static function data_valid_names(): array { + public static function data_accepts_valid_names(): array { return array( 'simple' => array( 'myplugin/api-key' ), 'single character segments' => array( 'a/b' ), @@ -40,7 +40,7 @@ public static function data_valid_names(): array { * * @covers ::wp_secrets_validate_name * - * @dataProvider data_invalid_names + * @dataProvider data_rejects_invalid_names * * @param string $name A name that must be rejected. */ @@ -51,6 +51,30 @@ public function test_rejects_invalid_names( $name ): void { $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code(), 'An invalid name should be reported with the invalid name error code.' ); } + /** + * @return array + */ + public static function data_rejects_invalid_names(): array { + return array( + 'empty string' => array( '' ), + 'two slashes' => array( 'too/many/slashes' ), + 'uppercase, unnamespaced' => array( 'NotAValidName' ), + 'space, unnamespaced' => array( 'not a valid name' ), + 'empty namespace' => array( '/key' ), + 'empty key' => array( 'namespace/' ), + 'uppercase namespace' => array( 'MyPlugin/key' ), + 'uppercase key' => array( 'plugin/MyKey' ), + 'leading hyphen in namespace' => array( '-plugin/key' ), + 'trailing hyphen in namespace' => array( 'plugin-/key' ), + 'leading underscore in key' => array( 'plugin/_key' ), + 'trailing underscore in key' => array( 'plugin/key_' ), + 'space in key' => array( 'plugin/key with space' ), + 'dot in key' => array( 'plugin/key.name' ), + 'non-ascii' => array( 'plügin/key' ), + 'one character over the max' => array( str_repeat( 'a', 85 ) . '/' . str_repeat( 'b', 87 ) ), + ); + } + /** * An unnamespaced name is accepted, but reports through _doing_it_wrong(). * It exists so code written against the Displace prototype – whose keyspace @@ -59,7 +83,7 @@ public function test_rejects_invalid_names( $name ): void { * * @covers ::wp_secrets_validate_name * - * @dataProvider data_unnamespaced_names + * @dataProvider data_accepts_an_unnamespaced_name_but_reports_it * * @param string $name An unnamespaced name that must be accepted. */ @@ -72,7 +96,7 @@ public function test_accepts_an_unnamespaced_name_but_reports_it( $name ): void /** * @return array */ - public static function data_unnamespaced_names(): array { + public static function data_accepts_an_unnamespaced_name_but_reports_it(): array { return array( 'simple' => array( 'api_key' ), 'with hyphen' => array( 'api-key' ), @@ -94,28 +118,4 @@ public function test_an_unnamespaced_name_still_obeys_the_character_rules(): voi $this->assertWPError( $result, 'An unnamespaced name with invalid characters should be rejected with a WP_Error.' ); $this->assertSame( WP_SECRETS_ERROR_INVALID_NAME, $result->get_error_code(), 'An unnamespaced name with invalid characters should be reported as an invalid name.' ); } - - /** - * @return array - */ - public static function data_invalid_names(): array { - return array( - 'empty string' => array( '' ), - 'two slashes' => array( 'too/many/slashes' ), - 'uppercase, unnamespaced' => array( 'NotAValidName' ), - 'space, unnamespaced' => array( 'not a valid name' ), - 'empty namespace' => array( '/key' ), - 'empty key' => array( 'namespace/' ), - 'uppercase namespace' => array( 'MyPlugin/key' ), - 'uppercase key' => array( 'plugin/MyKey' ), - 'leading hyphen in namespace' => array( '-plugin/key' ), - 'trailing hyphen in namespace' => array( 'plugin-/key' ), - 'leading underscore in key' => array( 'plugin/_key' ), - 'trailing underscore in key' => array( 'plugin/key_' ), - 'space in key' => array( 'plugin/key with space' ), - 'dot in key' => array( 'plugin/key.name' ), - 'non-ascii' => array( 'plügin/key' ), - 'one character over the max' => array( str_repeat( 'a', 85 ) . '/' . str_repeat( 'b', 87 ) ), - ); - } } From f0c4ef393a43512bf6cf26f00fe0f470bfcce2f4 Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 11:09:26 +1100 Subject: [PATCH 19/28] Remove stale plugin/docs reference. --- src/wp-admin/includes/secrets-site-health.php | 5 ++-- src/wp-includes/secrets.php | 26 +++++++------------ .../class-wp-secrets-libsodium-provider.php | 8 ------ .../tests/secrets/threeStateContract.php | 2 +- .../tests/secrets/wpSecretsValidateName.php | 5 ++-- 5 files changed, 14 insertions(+), 32 deletions(-) diff --git a/src/wp-admin/includes/secrets-site-health.php b/src/wp-admin/includes/secrets-site-health.php index c8fae1aaf49e6..646bc4a918bf5 100644 --- a/src/wp-admin/includes/secrets-site-health.php +++ b/src/wp-admin/includes/secrets-site-health.php @@ -10,9 +10,8 @@ /** * Registers the Secrets API's Site Health tests. * - * No settings screen – the proposal defers that to 7.3 – but the health signal an - * operator needs to notice a broken key, a weak key source, or a pending rotation is - * in scope now. + * There is no settings screen for secrets, so these tests are how an operator + * notices a broken key, a weak key source, or a pending rotation. * * @since 7.2.0 * diff --git a/src/wp-includes/secrets.php b/src/wp-includes/secrets.php index 2277ff2ab3927..826eb41b883b5 100644 --- a/src/wp-includes/secrets.php +++ b/src/wp-includes/secrets.php @@ -212,9 +212,9 @@ function wp_secrets_memzero( &$value ): void { * plugin that can run PHP can read any secret, namespaced or not. * * An unnamespaced name ('secret-name', no '/') is accepted, but reports through - * _doing_it_wrong(). It exists for one reason: code written against the earlier - * prototype used a flat keyspace, and refusing those names outright would mean - * every such call site has to be rewritten before it can be ported at all. + * _doing_it_wrong(). It exists for one reason: existing code may already use a flat + * keyspace, and refusing those names outright would mean every such call site has + * to be rewritten before it can be ported at all. * Accepting them keeps that migration incremental. Nothing else should use one. * Two plugins that both choose 'api-key' collide silently, which is a real problem * even though it is not a security one. @@ -272,7 +272,7 @@ function wp_secrets_validate_name( string $name ) { __FUNCTION__, sprintf( /* translators: %s: The unnamespaced secret name. */ - __( 'The secret name "%s" has no namespace. Namespaced names ("plugin-slug/secret-name") group secrets by owner so that listings and admin screens can be organized; unnamespaced names are supported only so that code written against the Displace prototype can be ported incrementally.' ), + __( 'The secret name "%s" has no namespace. Namespaced names ("plugin-slug/secret-name") group secrets by owner so that listings and admin screens can be organized; unnamespaced names are supported only so that existing code using flat names can be ported incrementally.' ), $name ), '7.2.0' @@ -424,10 +424,9 @@ function wp_set_secret( string $name, $value ) { /** * Imports an existing option's value as a secret. * - * For an explicit migration, "on their own explicit upgrade schedule," - * in the proposal's words, because "core cannot reliably tell which options are - * credentials, and guessing would break sites." The source option is left - * untouched: this reads it, it does not move or delete it. + * For an explicit migration on the caller's own schedule, because core cannot + * reliably tell which options are credentials, and guessing would break sites. The + * source option is left untouched: this reads it, it does not move or delete it. * * The imported secret is flagged needs_rotation, unconditionally. A credential that * sat in a plain option has already been through however many backups and @@ -506,8 +505,6 @@ function wp_delete_secret( string $name ) { * that has never been rotated, or that does not exist, is a successful no-op: * the previous slot is already absent either way. * - * Beyond the API surface the proposal names. - * * @since 7.2.0 * * @param string $name The secret's namespaced name. @@ -520,10 +517,6 @@ function wp_retire_secret_version( string $name ) { /** * Lists secrets by name and metadata. Never a value. * - * Beyond the API surface the proposal names, and justified by its statement that - * the hooks and accessors a future admin screen needs are in scope now, even though - * the screen itself is not. - * * @since 7.2.0 * * @param string $namespace Only secrets whose name starts with "{$namespace}/" are @@ -534,7 +527,7 @@ function wp_retire_secret_version( string $name ) { * * @phpstan-return list|WP_Error */ -function wp_list_secrets( string $namespace = '' ) { // phpcs:ignore Universal.NamingConventions.NoReservedKeywordParameterNames.namespaceFound -- $namespace is the parameter name the proposal specifies. +function wp_list_secrets( string $namespace = '' ) { // phpcs:ignore Universal.NamingConventions.NoReservedKeywordParameterNames.namespaceFound -- $namespace is the public parameter name; renaming it would break named-argument callers. return _wp_secrets_list( $namespace, false ); } @@ -543,8 +536,7 @@ function wp_list_secrets( string $namespace = '' ) { // phpcs:ignore Universal.N * * Site secrets and network secrets are separate functions with separate * capabilities and separate storage prefixes, with no implicit fallback from one - * scope to the other. The proposal describes network scope but does not name these - * functions; these are this implementation's names for them. + * scope to the other. * * @since 7.2.0 * diff --git a/src/wp-includes/secrets/class-wp-secrets-libsodium-provider.php b/src/wp-includes/secrets/class-wp-secrets-libsodium-provider.php index 5b6a2a97b3252..7fdf1e5374e0c 100644 --- a/src/wp-includes/secrets/class-wp-secrets-libsodium-provider.php +++ b/src/wp-includes/secrets/class-wp-secrets-libsodium-provider.php @@ -589,10 +589,6 @@ public function delete( string $name, bool $network = false ) { * * Backs wp_retire_secret_version() and wp_retire_network_secret_version(). * - * Beyond the API surface the proposal names. It states that retirement is "an - * explicit operator action" but names no function; this is this implementation's - * name for it, pending confirmation in the comments thread. - * * @since 7.2.0 * * @param string $name The secret's namespaced name. @@ -653,10 +649,6 @@ public function retire_previous( string $name, bool $network = false ) { /** * Shared implementation behind wp_list_secrets() and wp_list_network_secrets(). * - * Beyond the API surface the proposal names, and justified by its statement that - * "the hooks and accessors an admin screen would need are in scope now; the screen - * itself is not." - * * Fingerprints returned here come directly from the stored record field, not * recomputed by decrypting each secret. That is a deliberate difference from * WP_Secret::fingerprint(), which always recomputes – recomputing here would mean diff --git a/tests/phpunit/tests/secrets/threeStateContract.php b/tests/phpunit/tests/secrets/threeStateContract.php index 3e2092e84ac85..971bc4f202a66 100644 --- a/tests/phpunit/tests/secrets/threeStateContract.php +++ b/tests/phpunit/tests/secrets/threeStateContract.php @@ -122,7 +122,7 @@ public function test_aad_mismatch_from_a_copied_record_is_wp_error_not_null(): v * * The write goes through a hand-built WP_Secrets_Libsodium_Provider rather than * wp_set_secret() so it bypasses the static _wp_secrets_get_key_manager(), whose - * request-scoped root-key cache (ADR 0009) would otherwise keep serving the + * request-scoped root-key cache would otherwise keep serving the * already-unwrapped key and mask the misconfiguration this test defines below. * * @covers ::wp_get_secret diff --git a/tests/phpunit/tests/secrets/wpSecretsValidateName.php b/tests/phpunit/tests/secrets/wpSecretsValidateName.php index ad68eae90e416..9440ed209a18e 100644 --- a/tests/phpunit/tests/secrets/wpSecretsValidateName.php +++ b/tests/phpunit/tests/secrets/wpSecretsValidateName.php @@ -77,9 +77,8 @@ public static function data_rejects_invalid_names(): array { /** * An unnamespaced name is accepted, but reports through _doing_it_wrong(). - * It exists so code written against the Displace prototype – whose keyspace - * was flat – can be ported one call site at a time rather than all at once. - * See docs/decisions/0005-namespaces-are-not-access-control.md for the consequence. + * It exists so existing code that uses flat names can be ported one call site + * at a time rather than all at once. * * @covers ::wp_secrets_validate_name * From def4dbe56a504e0bcd293881c8ec5cdff8d95b9c Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 11:09:35 +1100 Subject: [PATCH 20/28] Test roles individually. --- tests/phpunit/tests/secrets/capabilities.php | 24 ++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/tests/phpunit/tests/secrets/capabilities.php b/tests/phpunit/tests/secrets/capabilities.php index 2133bccd64b1f..e2d0925c74f1e 100644 --- a/tests/phpunit/tests/secrets/capabilities.php +++ b/tests/phpunit/tests/secrets/capabilities.php @@ -71,11 +71,27 @@ public function test_a_fresh_install_grants_manage_secrets_to_administrator(): v * Ensure that no default role other than administrator is granted manage_secrets. * * @covers ::populate_roles_720 + * + * @dataProvider data_no_other_role_is_granted_manage_secrets + * + * @param string $role A default role other than administrator. */ - public function test_no_other_role_is_granted_manage_secrets(): void { - foreach ( array( 'editor', 'author', 'contributor', 'subscriber' ) as $role ) { - $this->assertFalse( $this->role( $role )->has_cap( WP_SECRETS_CAP_MANAGE ), $role ); - } + public function test_no_other_role_is_granted_manage_secrets( $role ): void { + $this->assertFalse( $this->role( $role )->has_cap( WP_SECRETS_CAP_MANAGE ), 'Role should not be granted capability' ); + } + + /** + * Data provider. + * + * @return array + */ + public static function data_no_other_role_is_granted_manage_secrets() { + return array( + 'editor' => array( 'editor' ), + 'author' => array( 'author' ), + 'contributor' => array( 'contributor' ), + 'subscriber' => array( 'subscriber' ), + ); } /** From 09f2a6466eb2b1a103b1f25c401d7970321338e1 Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 11:11:08 +1100 Subject: [PATCH 21/28] Remove redundent test (same implies notsame). --- tests/phpunit/tests/secrets/wpSecretsMemzero.php | 1 - 1 file changed, 1 deletion(-) diff --git a/tests/phpunit/tests/secrets/wpSecretsMemzero.php b/tests/phpunit/tests/secrets/wpSecretsMemzero.php index b7194b476c12e..50be2d722bbeb 100644 --- a/tests/phpunit/tests/secrets/wpSecretsMemzero.php +++ b/tests/phpunit/tests/secrets/wpSecretsMemzero.php @@ -16,7 +16,6 @@ public function test_clears_a_plaintext_string(): void { wp_secrets_memzero( $value ); - $this->assertNotSame( 'a plaintext value', $value, 'The original plaintext should no longer be in the variable.' ); $this->assertSame( '', $value, 'The variable should be an empty string after zeroing.' ); } From 7f20c90129ebd60b1df9d42f110b6d0a5e55f330 Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 11:12:37 +1100 Subject: [PATCH 22/28] Clarify message. --- tests/phpunit/tests/secrets/networkScope.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/phpunit/tests/secrets/networkScope.php b/tests/phpunit/tests/secrets/networkScope.php index 65fe608ee9e59..a3deeb8cc623a 100644 --- a/tests/phpunit/tests/secrets/networkScope.php +++ b/tests/phpunit/tests/secrets/networkScope.php @@ -208,7 +208,7 @@ public function test_network_secret_is_readable_from_any_blog(): void { $secret = wp_get_network_secret( 'myplugin/api-key' ); restore_current_blog(); - $this->assertIsSecret( $secret, 'cross-blog-value', 'Read from a second blog:' ); + $this->assertIsSecret( $secret, 'cross-blog-value', 'The network secret should be readable from a second blog.' ); } /** From 9988bc94ef2a7bfb1f8eb17afbce4900de405012 Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 11:26:20 +1100 Subject: [PATCH 23/28] Modify/split test. --- .../tests/secrets/threeStateContract.php | 39 +++++++++++++++++-- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/tests/phpunit/tests/secrets/threeStateContract.php b/tests/phpunit/tests/secrets/threeStateContract.php index 971bc4f202a66..8fc1adadac3db 100644 --- a/tests/phpunit/tests/secrets/threeStateContract.php +++ b/tests/phpunit/tests/secrets/threeStateContract.php @@ -115,9 +115,9 @@ public function test_aad_mismatch_from_a_copied_record_is_wp_error_not_null(): v } /** - * An operator sets the constant wrong after secrets exist: WP_SECRETS_KEY is - * defined with a value that cannot serve as a usable key once secrets already - * exist under the site's real key. wp_get_secret() must fail with WP_Error, not + * An operator defines WP_SECRETS_KEY with a value that is not a usable string, + * here an integer, after secrets already exist. The key is rejected as unavailable + * before it is ever tried, and wp_get_secret() must report that as a WP_Error, not * silently return null as if the secret never existed. * * The write goes through a hand-built WP_Secrets_Libsodium_Provider rather than @@ -150,6 +150,39 @@ public function test_key_unavailable_is_wp_error_not_null(): void { $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code(), 'An unusable WP_SECRETS_KEY should produce the key unavailable error code.' ); } + /** + * Ensure that a different valid WP_SECRETS_KEY makes wp_get_secret() return a WP_Error, not null. + * + * This is the realistic misconfiguration: a well-formed key that is not the one the + * stored root key was wrapped under, such as a regenerated key or one copied from + * another site. The secret is written through a keyring that reads + * WP_SECRETS_KEY_PREVIOUS, so this process can then define a different + * WP_SECRETS_KEY for the read. + * + * @covers ::wp_get_secret + * + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function test_a_different_valid_key_is_wp_error_not_null(): void { + define( 'WP_SECRETS_KEY_PREVIOUS', base64_encode( str_repeat( 'a', 32 ) ) ); + + $provider = new WP_Secrets_Libsodium_Provider( + new WP_Secrets_Option_Store(), + new WP_Secrets_Key_Manager( new WP_Secrets_Config_Key_Provider( true ) ) + ); + $this->assertTrue( $provider->set( 'myplugin/api-key', 'value' ), 'Writing the secret under the original key should succeed.' ); + + define( 'WP_SECRETS_KEY', base64_encode( str_repeat( 'b', 32 ) ) ); + + $result = wp_get_secret( 'myplugin/api-key' ); + + $this->assertNotNull( $result, 'A secret read under a different valid WP_SECRETS_KEY should not be reported as null.' ); + $this->assertWPError( $result, 'A secret read under a different valid WP_SECRETS_KEY should be reported as a WP_Error.' ); + $this->assertSame( WP_SECRETS_ERROR_KEY_UNAVAILABLE, $result->get_error_code(), 'A different valid WP_SECRETS_KEY should produce the key unavailable error code.' ); + $this->assertStringContainsString( 'could not be decrypted', $result->get_error_message(), 'The error should come from failing to decrypt the root key, not from rejecting the key format.' ); + } + /** * Written under the ambient salt-fallback key, then read back after the stored * wrapped root key has been corrupted – simulating the option row being From e7b36f4aab72c45a6acabb4a41c93f3dae4d7268 Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 11:44:04 +1100 Subject: [PATCH 24/28] Replace skipped tests with group annotations. --- tests/phpunit/tests/secrets/networkScope.php | 12 +++----- tests/phpunit/tests/secrets/siteHealth.php | 6 ++-- .../tests/secrets/wpSecretsKeyManager.php | 30 +++++++------------ 3 files changed, 16 insertions(+), 32 deletions(-) diff --git a/tests/phpunit/tests/secrets/networkScope.php b/tests/phpunit/tests/secrets/networkScope.php index a3deeb8cc623a..42c8a51afbde9 100644 --- a/tests/phpunit/tests/secrets/networkScope.php +++ b/tests/phpunit/tests/secrets/networkScope.php @@ -193,14 +193,12 @@ public function test_set_rejects_an_invalid_name(): void { * The entire point of network scope: a secret written from one blog's context * must read back identically from another blog's context. Requires multisite. * + * @group ms-required + * * @covers ::wp_set_network_secret * @covers ::wp_get_network_secret */ public function test_network_secret_is_readable_from_any_blog(): void { - if ( ! is_multisite() ) { - $this->markTestSkipped( 'Requires multisite: proves network secrets are not bound to the blog that wrote them.' ); - } - $this->assertTrue( wp_set_network_secret( 'myplugin/api-key', 'cross-blog-value' ), 'Setting network secret myplugin/api-key to cross-blog-value should succeed.' ); $second_blog_id = self::factory()->blog->create(); @@ -216,14 +214,12 @@ public function test_network_secret_is_readable_from_any_blog(): void { * proving there is no implicit fallback between scopes and no accidental sharing * across blogs for site-scope secrets. * + * @group ms-required + * * @covers ::wp_set_secret * @covers ::wp_get_secret */ public function test_site_secret_is_not_readable_from_a_different_blog(): void { - if ( ! is_multisite() ) { - $this->markTestSkipped( 'Requires multisite: proves site secrets do not leak across blogs.' ); - } - $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'blog-one-value' ), 'Setting myplugin/api-key to blog-one-value should succeed.' ); $second_blog_id = self::factory()->blog->create(); diff --git a/tests/phpunit/tests/secrets/siteHealth.php b/tests/phpunit/tests/secrets/siteHealth.php index 9212dfdf37759..df32d94e37f72 100644 --- a/tests/phpunit/tests/secrets/siteHealth.php +++ b/tests/phpunit/tests/secrets/siteHealth.php @@ -312,13 +312,11 @@ public function test_debug_info_omits_network_fields_on_single_site(): void { * Network secret counts appear only for a super admin on a multisite install – * never for a site administrator who is not one. * + * @group ms-required + * * @covers ::wp_secrets_site_health_debug_info */ public function test_debug_info_includes_network_fields_only_for_a_super_admin(): void { - if ( ! is_multisite() ) { - $this->markTestSkipped( 'Requires multisite.' ); - } - $user_id = self::factory()->user->create(); wp_set_current_user( $user_id ); diff --git a/tests/phpunit/tests/secrets/wpSecretsKeyManager.php b/tests/phpunit/tests/secrets/wpSecretsKeyManager.php index f18d81588a9b5..d478162cf72bf 100644 --- a/tests/phpunit/tests/secrets/wpSecretsKeyManager.php +++ b/tests/phpunit/tests/secrets/wpSecretsKeyManager.php @@ -195,13 +195,11 @@ public static function data_get_master_key_reports_an_invalid_site_id_as_a_wp_er * the multisite suite; skips under single-site since there is only one blog to * compare against. * + * @group ms-required + * * @covers WP_Secrets_Key_Manager::get_master_key */ public function test_network_scope_master_key_is_identical_across_blogs(): void { - if ( ! is_multisite() ) { - $this->markTestSkipped( 'Requires multisite: proves the root key is shared network-wide.' ); - } - $second_blog_id = self::factory()->blog->create(); $manager = new WP_Secrets_Key_Manager(); @@ -218,13 +216,11 @@ public function test_network_scope_master_key_is_identical_across_blogs(): void * Site-scope master keys, by contrast, must differ per blog even though every * blog derives from the same shared root key. * + * @group ms-required + * * @covers WP_Secrets_Key_Manager::get_master_key */ public function test_site_scope_master_key_differs_across_blogs(): void { - if ( ! is_multisite() ) { - $this->markTestSkipped( 'Requires multisite: proves per-blog cryptographic separation.' ); - } - $second_blog_id = self::factory()->blog->create(); $manager = new WP_Secrets_Key_Manager(); @@ -245,13 +241,11 @@ public function test_site_scope_master_key_differs_across_blogs(): void { * Requires the multisite suite; skips under single-site since sitemeta and * the main site's options are the same table there. * + * @group ms-required + * * @covers WP_Secrets_Key_Manager::get_root_key */ public function test_get_root_key_adopts_a_pre_conversion_root_key(): void { - if ( ! is_multisite() ) { - $this->markTestSkipped( 'Requires multisite: proves the main-site option row is adopted.' ); - } - $manager = new WP_Secrets_Key_Manager(); $root_key = $manager->get_root_key(); @@ -275,14 +269,12 @@ public function test_get_root_key_adopts_a_pre_conversion_root_key(): void { * Requires the multisite suite; skips under single-site for the same reason * as the adoption test above. * + * @group ms-required + * * @covers WP_Secrets_Key_Manager::get_root_key * @covers ::wp_get_secret */ public function test_secret_written_before_conversion_still_decrypts(): void { - if ( ! is_multisite() ) { - $this->markTestSkipped( 'Requires multisite: proves secrets survive conversion.' ); - } - $main_site_id = get_main_site_id(); $this->assertTrue( wp_set_secret( 'secrets-api/pre-conversion', 'shh' ), 'Storing the secret before conversion should succeed.' ); @@ -302,13 +294,11 @@ public function test_secret_written_before_conversion_still_decrypts(): void { * Requires the multisite suite; skips under single-site for the same reason * as the adoption test above. * + * @group ms-required + * * @covers WP_Secrets_Key_Manager::rotate_site_key */ public function test_rotate_site_key_works_after_conversion_before_any_read(): void { - if ( ! is_multisite() ) { - $this->markTestSkipped( 'Requires multisite: proves rotation adopts a pre-conversion key too.' ); - } - $main_site_id = get_main_site_id(); $right_keyring = new WP_Secrets_Config_Key_Provider(); $manager = new WP_Secrets_Key_Manager( $right_keyring ); From 9803bceefddbefbbfc9faa0508a6a9b0a668b4e1 Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 11:47:21 +1100 Subject: [PATCH 25/28] Add tests with ms-required to multisite group. --- tests/phpunit/tests/secrets/networkScope.php | 2 ++ tests/phpunit/tests/secrets/siteHealth.php | 1 + tests/phpunit/tests/secrets/wpSecretsKeyManager.php | 5 +++++ 3 files changed, 8 insertions(+) diff --git a/tests/phpunit/tests/secrets/networkScope.php b/tests/phpunit/tests/secrets/networkScope.php index 42c8a51afbde9..731b18d1d5500 100644 --- a/tests/phpunit/tests/secrets/networkScope.php +++ b/tests/phpunit/tests/secrets/networkScope.php @@ -193,6 +193,7 @@ public function test_set_rejects_an_invalid_name(): void { * The entire point of network scope: a secret written from one blog's context * must read back identically from another blog's context. Requires multisite. * + * @group multisite * @group ms-required * * @covers ::wp_set_network_secret @@ -214,6 +215,7 @@ public function test_network_secret_is_readable_from_any_blog(): void { * proving there is no implicit fallback between scopes and no accidental sharing * across blogs for site-scope secrets. * + * @group multisite * @group ms-required * * @covers ::wp_set_secret diff --git a/tests/phpunit/tests/secrets/siteHealth.php b/tests/phpunit/tests/secrets/siteHealth.php index df32d94e37f72..226fd411c558f 100644 --- a/tests/phpunit/tests/secrets/siteHealth.php +++ b/tests/phpunit/tests/secrets/siteHealth.php @@ -312,6 +312,7 @@ public function test_debug_info_omits_network_fields_on_single_site(): void { * Network secret counts appear only for a super admin on a multisite install – * never for a site administrator who is not one. * + * @group multisite * @group ms-required * * @covers ::wp_secrets_site_health_debug_info diff --git a/tests/phpunit/tests/secrets/wpSecretsKeyManager.php b/tests/phpunit/tests/secrets/wpSecretsKeyManager.php index d478162cf72bf..62633d10eac76 100644 --- a/tests/phpunit/tests/secrets/wpSecretsKeyManager.php +++ b/tests/phpunit/tests/secrets/wpSecretsKeyManager.php @@ -195,6 +195,7 @@ public static function data_get_master_key_reports_an_invalid_site_id_as_a_wp_er * the multisite suite; skips under single-site since there is only one blog to * compare against. * + * @group multisite * @group ms-required * * @covers WP_Secrets_Key_Manager::get_master_key @@ -216,6 +217,7 @@ public function test_network_scope_master_key_is_identical_across_blogs(): void * Site-scope master keys, by contrast, must differ per blog even though every * blog derives from the same shared root key. * + * @group multisite * @group ms-required * * @covers WP_Secrets_Key_Manager::get_master_key @@ -241,6 +243,7 @@ public function test_site_scope_master_key_differs_across_blogs(): void { * Requires the multisite suite; skips under single-site since sitemeta and * the main site's options are the same table there. * + * @group multisite * @group ms-required * * @covers WP_Secrets_Key_Manager::get_root_key @@ -269,6 +272,7 @@ public function test_get_root_key_adopts_a_pre_conversion_root_key(): void { * Requires the multisite suite; skips under single-site for the same reason * as the adoption test above. * + * @group multisite * @group ms-required * * @covers WP_Secrets_Key_Manager::get_root_key @@ -294,6 +298,7 @@ public function test_secret_written_before_conversion_still_decrypts(): void { * Requires the multisite suite; skips under single-site for the same reason * as the adoption test above. * + * @group multisite * @group ms-required * * @covers WP_Secrets_Key_Manager::rotate_site_key From 3866ccd79d1f114463e54fd8a145bf085ce35598 Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 13:14:56 +1100 Subject: [PATCH 26/28] Use skipWith(Out)Multisite helpers in conjunction with groups. --- tests/phpunit/tests/secrets/capabilities.php | 4 ++++ tests/phpunit/tests/secrets/networkScope.php | 4 ++++ tests/phpunit/tests/secrets/siteHealth.php | 2 ++ tests/phpunit/tests/secrets/wpSecretsKeyManager.php | 10 ++++++++++ 4 files changed, 20 insertions(+) diff --git a/tests/phpunit/tests/secrets/capabilities.php b/tests/phpunit/tests/secrets/capabilities.php index e2d0925c74f1e..2caef42ea10f1 100644 --- a/tests/phpunit/tests/secrets/capabilities.php +++ b/tests/phpunit/tests/secrets/capabilities.php @@ -180,6 +180,8 @@ public function test_subscriber_does_not_have_manage_secrets(): void { * @covers ::map_meta_cap */ public function test_single_site_administrator_does_not_have_manage_network_secrets(): void { + $this->skipWithMultisite(); + $user_id = self::factory()->user->create( array( 'role' => 'administrator' ) ); $this->assertFalse( user_can( $user_id, WP_SECRETS_CAP_MANAGE_NETWORK ), 'A single site administrator should not have manage_network_secrets.' ); @@ -193,6 +195,8 @@ public function test_single_site_administrator_does_not_have_manage_network_secr * @covers ::map_meta_cap */ public function test_only_super_admins_have_manage_network_secrets(): void { + $this->skipWithoutMultisite(); + $administrator = self::factory()->user->create( array( 'role' => 'administrator' ) ); $super_admin = self::factory()->user->create( array( 'role' => 'administrator' ) ); grant_super_admin( $super_admin ); diff --git a/tests/phpunit/tests/secrets/networkScope.php b/tests/phpunit/tests/secrets/networkScope.php index 731b18d1d5500..2f9764473948b 100644 --- a/tests/phpunit/tests/secrets/networkScope.php +++ b/tests/phpunit/tests/secrets/networkScope.php @@ -200,6 +200,8 @@ public function test_set_rejects_an_invalid_name(): void { * @covers ::wp_get_network_secret */ public function test_network_secret_is_readable_from_any_blog(): void { + $this->skipWithoutMultisite(); + $this->assertTrue( wp_set_network_secret( 'myplugin/api-key', 'cross-blog-value' ), 'Setting network secret myplugin/api-key to cross-blog-value should succeed.' ); $second_blog_id = self::factory()->blog->create(); @@ -222,6 +224,8 @@ public function test_network_secret_is_readable_from_any_blog(): void { * @covers ::wp_get_secret */ public function test_site_secret_is_not_readable_from_a_different_blog(): void { + $this->skipWithoutMultisite(); + $this->assertTrue( wp_set_secret( 'myplugin/api-key', 'blog-one-value' ), 'Setting myplugin/api-key to blog-one-value should succeed.' ); $second_blog_id = self::factory()->blog->create(); diff --git a/tests/phpunit/tests/secrets/siteHealth.php b/tests/phpunit/tests/secrets/siteHealth.php index 226fd411c558f..cde45645bd347 100644 --- a/tests/phpunit/tests/secrets/siteHealth.php +++ b/tests/phpunit/tests/secrets/siteHealth.php @@ -318,6 +318,8 @@ public function test_debug_info_omits_network_fields_on_single_site(): void { * @covers ::wp_secrets_site_health_debug_info */ public function test_debug_info_includes_network_fields_only_for_a_super_admin(): void { + $this->skipWithoutMultisite(); + $user_id = self::factory()->user->create(); wp_set_current_user( $user_id ); diff --git a/tests/phpunit/tests/secrets/wpSecretsKeyManager.php b/tests/phpunit/tests/secrets/wpSecretsKeyManager.php index 62633d10eac76..b6bf4d0d1391a 100644 --- a/tests/phpunit/tests/secrets/wpSecretsKeyManager.php +++ b/tests/phpunit/tests/secrets/wpSecretsKeyManager.php @@ -201,6 +201,8 @@ public static function data_get_master_key_reports_an_invalid_site_id_as_a_wp_er * @covers WP_Secrets_Key_Manager::get_master_key */ public function test_network_scope_master_key_is_identical_across_blogs(): void { + $this->skipWithoutMultisite(); + $second_blog_id = self::factory()->blog->create(); $manager = new WP_Secrets_Key_Manager(); @@ -223,6 +225,8 @@ public function test_network_scope_master_key_is_identical_across_blogs(): void * @covers WP_Secrets_Key_Manager::get_master_key */ public function test_site_scope_master_key_differs_across_blogs(): void { + $this->skipWithoutMultisite(); + $second_blog_id = self::factory()->blog->create(); $manager = new WP_Secrets_Key_Manager(); @@ -249,6 +253,8 @@ public function test_site_scope_master_key_differs_across_blogs(): void { * @covers WP_Secrets_Key_Manager::get_root_key */ public function test_get_root_key_adopts_a_pre_conversion_root_key(): void { + $this->skipWithoutMultisite(); + $manager = new WP_Secrets_Key_Manager(); $root_key = $manager->get_root_key(); @@ -279,6 +285,8 @@ public function test_get_root_key_adopts_a_pre_conversion_root_key(): void { * @covers ::wp_get_secret */ public function test_secret_written_before_conversion_still_decrypts(): void { + $this->skipWithoutMultisite(); + $main_site_id = get_main_site_id(); $this->assertTrue( wp_set_secret( 'secrets-api/pre-conversion', 'shh' ), 'Storing the secret before conversion should succeed.' ); @@ -304,6 +312,8 @@ public function test_secret_written_before_conversion_still_decrypts(): void { * @covers WP_Secrets_Key_Manager::rotate_site_key */ public function test_rotate_site_key_works_after_conversion_before_any_read(): void { + $this->skipWithoutMultisite(); + $main_site_id = get_main_site_id(); $right_keyring = new WP_Secrets_Config_Key_Provider(); $manager = new WP_Secrets_Key_Manager( $right_keyring ); From 52222dfc3919b688e35cf044a3d510b6bbcb377d Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 13:21:07 +1100 Subject: [PATCH 27/28] Remove interfaces from covers annotations. --- .../class-wp-secrets-keyring-conformance.php | 13 ------ .../class-wp-secrets-provider-conformance.php | 46 ------------------- .../secrets/configKeyringConformance.php | 4 ++ .../tests/secrets/mockKeyringConformance.php | 2 + .../tests/secrets/providerConformance.php | 9 ++++ .../secrets/readonlyProviderConformance.php | 2 + 6 files changed, 17 insertions(+), 59 deletions(-) diff --git a/tests/phpunit/includes/secrets/class-wp-secrets-keyring-conformance.php b/tests/phpunit/includes/secrets/class-wp-secrets-keyring-conformance.php index f1c9596325ea0..be4a87af4aca2 100644 --- a/tests/phpunit/includes/secrets/class-wp-secrets-keyring-conformance.php +++ b/tests/phpunit/includes/secrets/class-wp-secrets-keyring-conformance.php @@ -26,9 +26,6 @@ abstract protected function keyring(); * Wrap() followed by unwrap() has to return exactly the bytes that went in – * WP_Secrets_Key_Manager derives the root key from this round trip, so any * corruption here is a corrupted root key for every secret on the site. - * - * @covers WP_Secrets_Keyring::wrap - * @covers WP_Secrets_Keyring::unwrap */ public function test_wrap_returns_a_non_empty_string_that_unwraps_to_the_same_bytes(): void { $keyring = $this->keyring(); @@ -49,8 +46,6 @@ public function test_wrap_returns_a_non_empty_string_that_unwraps_to_the_same_by * values protect the same key material – something nothing outside the * keyring is entitled to learn. A fresh nonce (or equivalent) per call is what * WP_Secrets_Key_Manager relies on to keep that comparison unavailable. - * - * @covers WP_Secrets_Keyring::wrap */ public function test_two_wraps_of_the_same_bytes_return_different_strings(): void { $keyring = $this->keyring(); @@ -67,8 +62,6 @@ public function test_two_wraps_of_the_same_bytes_return_different_strings(): voi * it did not produce – WP_Secrets_Key_Manager treats anything other than * WP_Error as usable key material, so a keyring that returns garbage bytes on * garbage input hands a wrong root key downstream instead of failing. - * - * @covers WP_Secrets_Keyring::unwrap */ public function test_unwrap_of_garbage_is_a_wp_error(): void { $keyring = $this->keyring(); @@ -81,8 +74,6 @@ public function test_unwrap_of_garbage_is_a_wp_error(): void { * A truncated wrapped value must fail closed rather than decode to a short, * wrong key – WP_Secrets_Key_Manager has no way to tell a merely-short key * from a correctly-derived one except by trusting unwrap()'s success. - * - * @covers WP_Secrets_Keyring::unwrap */ public function test_unwrap_of_a_truncated_value_is_a_wp_error(): void { $keyring = $this->keyring(); @@ -99,8 +90,6 @@ public function test_unwrap_of_a_truncated_value_is_a_wp_error(): void { * A single flipped bit anywhere in the wrapped value has to be caught – * that is the entire point of authenticated wrapping. Silently accepting it * would let a corrupted or tampered wrapped root key through as genuine. - * - * @covers WP_Secrets_Keyring::unwrap */ public function test_unwrap_of_a_value_with_one_flipped_byte_is_a_wp_error(): void { $keyring = $this->keyring(); @@ -118,8 +107,6 @@ public function test_unwrap_of_a_value_with_one_flipped_byte_is_a_wp_error(): vo /** * Site Health renders get_key_source() directly; an empty or non-string value * there is a blank line on a diagnostics page an operator is depending on. - * - * @covers WP_Secrets_Keyring::get_key_source */ public function test_get_key_source_returns_a_non_empty_string(): void { $source = $this->keyring()->get_key_source(); diff --git a/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php b/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php index e9760571c2af5..8e09a6ebdfb3b 100644 --- a/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php +++ b/tests/phpunit/includes/secrets/class-wp-secrets-provider-conformance.php @@ -105,8 +105,6 @@ private function has_previous_version( WP_Secrets_Provider $provider, $name ) { /** * Ensure that the provider reports a label that is neither empty nor only whitespace. - * - * @covers WP_Secrets_Provider::get_label */ public function test_reports_a_non_empty_label(): void { $label = $this->provider()->get_label(); @@ -117,8 +115,6 @@ public function test_reports_a_non_empty_label(): void { /** * Ensure that the provider reports one of the BOUNDARY_* constants as its protection boundary. - * - * @covers WP_Secrets_Provider::get_protection_boundary */ public function test_reports_a_known_protection_boundary(): void { $this->assertContains( @@ -130,8 +126,6 @@ public function test_reports_a_known_protection_boundary(): void { /** * Ensure that the provider declares whether it accepts writes as a boolean. - * - * @covers WP_Secrets_Provider::is_writable */ public function test_is_writable_returns_a_bool(): void { $this->assertIsBool( $this->provider()->is_writable(), 'The provider should report is_writable() as a bool.' ); @@ -140,9 +134,6 @@ public function test_is_writable_returns_a_bool(): void { /** * The declaration has to match the behavior, or a settings screen that trusts * is_writable() will offer a save control that cannot work. - * - * @covers WP_Secrets_Provider::is_writable - * @covers WP_Secrets_Provider::set */ public function test_a_read_only_provider_actually_refuses_writes(): void { $provider = $this->provider(); @@ -168,8 +159,6 @@ public function test_a_read_only_provider_actually_refuses_writes(): void { * set is null – not false, not an empty WP_Secret, not a WP_Error. Reporting * absence as an error makes every caller treat a missing optional credential * as an outage; reporting an outage as absence makes them treat it as deleted. - * - * @covers WP_Secrets_Provider::get */ public function test_a_name_that_was_never_set_is_null(): void { $result = $this->provider()->get( 'conformance/never-set-' . uniqid(), WP_Secret_Version::CURRENT ); @@ -181,8 +170,6 @@ public function test_a_name_that_was_never_set_is_null(): void { * A provider with no version history reports absence for PREVIOUS, because * that is what it is: there is no previous value. It is not an error, and it * is not an excuse to return the current one. - * - * @covers WP_Secrets_Provider::get */ public function test_previous_on_a_provider_or_secret_without_history_is_null_not_error(): void { $provider = $this->provider(); @@ -199,8 +186,6 @@ public function test_previous_on_a_provider_or_secret_without_history_is_null_no /** * Ensure that the provider treats deleting a secret that was never set as success. - * - * @covers WP_Secrets_Provider::delete */ public function test_deleting_something_absent_is_success(): void { $provider = $this->provider(); @@ -214,8 +199,6 @@ public function test_deleting_something_absent_is_success(): void { /** * Ensure that the provider treats retiring a secret that has no previous version as success. - * - * @covers WP_Secrets_Provider::retire_previous */ public function test_retiring_with_no_previous_version_is_success(): void { $provider = $this->provider(); @@ -231,9 +214,6 @@ public function test_retiring_with_no_previous_version_is_success(): void { /** * Ensure that the provider returns a stored value unchanged, under the name it was stored as. - * - * @covers WP_Secrets_Provider::set - * @covers WP_Secrets_Provider::get */ public function test_a_stored_value_comes_back_intact(): void { $provider = $this->provider(); @@ -253,8 +233,6 @@ public function test_a_stored_value_comes_back_intact(): void { * Fingerprints are how callers compare secrets without revealing them, so the * same value must fingerprint the same way twice. A provider that returns a * random or timestamped fingerprint breaks every comparison built on it. - * - * @covers WP_Secrets_Provider::get */ public function test_a_fingerprint_is_stable_for_the_same_value(): void { $provider = $this->provider(); @@ -287,8 +265,6 @@ public function test_a_fingerprint_is_stable_for_the_same_value(): void { * version; one with no history has nothing to lose. * * @ticket 66353 - * - * @covers WP_Secrets_Provider::set */ public function test_writing_an_unchanged_value_keeps_the_previous_version(): void { $provider = $this->provider(); @@ -314,9 +290,6 @@ public function test_writing_an_unchanged_value_keeps_the_previous_version(): vo /** * Ensure that the provider reports a deleted secret as absent. - * - * @covers WP_Secrets_Provider::delete - * @covers WP_Secrets_Provider::get */ public function test_a_deleted_secret_reads_as_absent(): void { $provider = $this->provider(); @@ -335,8 +308,6 @@ public function test_a_deleted_secret_reads_as_absent(): void { * The API does not fire `wp_secret_changed` on a provider's behalf, so a * provider that forgets to is a site whose audit log went quiet the day the * host installed it. Nothing else would notice. - * - * @covers WP_Secrets_Provider::set */ public function test_a_successful_write_reports_a_change(): void { $provider = $this->provider(); @@ -364,8 +335,6 @@ public function test_a_successful_write_reports_a_change(): void { /** * Ensure that the provider reports an action override passed to set() to wp_secret_changed unchanged. - * - * @covers WP_Secrets_Provider::set */ public function test_an_action_override_is_reported_as_given(): void { $provider = $this->provider(); @@ -382,9 +351,6 @@ public function test_an_action_override_is_reported_as_given(): void { /** * A listener cannot otherwise tell a network secret from a site secret of the * same name, and on a network those are different credentials. - * - * @covers WP_Secrets_Provider::set - * @covers WP_Secrets_Provider::delete */ public function test_a_network_scope_change_reports_its_scope(): void { $provider = $this->provider(); @@ -403,8 +369,6 @@ public function test_a_network_scope_change_reports_its_scope(): void { /** * Ensure that the provider fires wp_secret_changed once, as deleted, when a secret is deleted. - * - * @covers WP_Secrets_Provider::delete */ public function test_deleting_a_secret_reports_a_change(): void { $provider = $this->provider(); @@ -426,8 +390,6 @@ public function test_deleting_a_secret_reports_a_change(): void { * Only asked of a provider that keeps a previous version and clears it on * request. One with no history, or whose backend manages its own, has nothing * to report. - * - * @covers WP_Secrets_Provider::retire_previous */ public function test_retiring_a_previous_version_reports_a_change(): void { $provider = $this->provider(); @@ -456,8 +418,6 @@ public function test_retiring_a_previous_version_reports_a_change(): void { /** * Ensure that a read-only provider does not fire wp_secret_changed for a write it refused. - * - * @covers WP_Secrets_Provider::set */ public function test_a_refused_write_reports_no_change(): void { $provider = $this->provider(); @@ -479,8 +439,6 @@ public function test_a_refused_write_reports_no_change(): void { * * The whole listing is encoded and searched rather than checked field by field, so a * value leaked under any key, including one the contract does not define, is caught. - * - * @covers WP_Secrets_Provider::list_secrets */ public function test_listing_never_contains_a_stored_value(): void { $provider = $this->provider(); @@ -505,8 +463,6 @@ public function test_listing_never_contains_a_stored_value(): void { /** * Ensure that the provider includes the name of a stored secret in its listing. - * - * @covers WP_Secrets_Provider::list_secrets */ public function test_listing_includes_a_stored_secret(): void { $provider = $this->provider(); @@ -525,8 +481,6 @@ public function test_listing_includes_a_stored_secret(): void { * A prefix filter that matched loosely would hand a caller names it did not * ask about, which for a listing keyed by owner is exactly the wrong direction * to be wrong in. - * - * @covers WP_Secrets_Provider::list_secrets */ public function test_listing_respects_a_name_prefix(): void { $provider = $this->provider(); diff --git a/tests/phpunit/tests/secrets/configKeyringConformance.php b/tests/phpunit/tests/secrets/configKeyringConformance.php index 8451c6af2b1df..ea6601337e8d3 100644 --- a/tests/phpunit/tests/secrets/configKeyringConformance.php +++ b/tests/phpunit/tests/secrets/configKeyringConformance.php @@ -10,6 +10,10 @@ * @ticket 66187 * * @group secrets + * + * @covers WP_Secrets_Config_Key_Provider::wrap + * @covers WP_Secrets_Config_Key_Provider::unwrap + * @covers WP_Secrets_Config_Key_Provider::get_key_source */ class Tests_Secrets_ConfigKeyringConformance extends WP_Secrets_Keyring_Conformance { diff --git a/tests/phpunit/tests/secrets/mockKeyringConformance.php b/tests/phpunit/tests/secrets/mockKeyringConformance.php index 6d073a96b367d..05029eab949e7 100644 --- a/tests/phpunit/tests/secrets/mockKeyringConformance.php +++ b/tests/phpunit/tests/secrets/mockKeyringConformance.php @@ -10,6 +10,8 @@ * @ticket 66187 * * @group secrets + * + * @coversNothing */ class Tests_Secrets_MockKeyringConformance extends WP_Secrets_Keyring_Conformance { diff --git a/tests/phpunit/tests/secrets/providerConformance.php b/tests/phpunit/tests/secrets/providerConformance.php index ed1b099e63a5a..120a7907cae04 100644 --- a/tests/phpunit/tests/secrets/providerConformance.php +++ b/tests/phpunit/tests/secrets/providerConformance.php @@ -9,6 +9,15 @@ * @ticket 66187 * * @group secrets + * + * @covers WP_Secrets_Libsodium_Provider::get + * @covers WP_Secrets_Libsodium_Provider::set + * @covers WP_Secrets_Libsodium_Provider::delete + * @covers WP_Secrets_Libsodium_Provider::retire_previous + * @covers WP_Secrets_Libsodium_Provider::list_secrets + * @covers WP_Secrets_Libsodium_Provider::is_writable + * @covers WP_Secrets_Libsodium_Provider::get_label + * @covers WP_Secrets_Libsodium_Provider::get_protection_boundary */ class Tests_Secrets_LibsodiumProviderConformance extends WP_Secrets_Provider_Conformance { diff --git a/tests/phpunit/tests/secrets/readonlyProviderConformance.php b/tests/phpunit/tests/secrets/readonlyProviderConformance.php index 5877aa8d2f96e..f64b6f3dd7b32 100644 --- a/tests/phpunit/tests/secrets/readonlyProviderConformance.php +++ b/tests/phpunit/tests/secrets/readonlyProviderConformance.php @@ -10,6 +10,8 @@ * @ticket 66187 * * @group secrets + * + * @coversNothing */ class Tests_Secrets_ReadOnlyProviderConformance extends WP_Secrets_Provider_Conformance { From a3614405e1aa02fe24ea8fbb884b1624aee8baf7 Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Thu, 5 Nov 2026 13:22:58 +1100 Subject: [PATCH 28/28] Clarify docbloxk/. --- src/wp-includes/secrets/class-wp-secret.php | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/wp-includes/secrets/class-wp-secret.php b/src/wp-includes/secrets/class-wp-secret.php index 26343f8b7c7dd..d8db880ef3c8d 100644 --- a/src/wp-includes/secrets/class-wp-secret.php +++ b/src/wp-includes/secrets/class-wp-secret.php @@ -226,9 +226,10 @@ public function __toString(): string { /** * Masks the instance for var_dump() and print_r(). * - * Note that var_export() has no equivalent hook. It is safe regardless, because - * the plaintext is never a declared property for it to enumerate; it will surface - * the (non-sensitive) name and fingerprint rather than this placeholder. + * Note that var_export() does not use this hook. It does not expose plaintext + * from the vault, but it enumerates all instance properties, including the + * unmasked WP_Error reason on a withheld secret. Use a masked output path + * instead when the reason must remain private. * * @since 7.2.0 *