Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
00a0b2d
Remove excess white-space.
peterwilsoncc Nov 4, 2026
40e877b
Add ticket and covers annotations to secrets tests.
peterwilsoncc Nov 4, 2026
7eeda63
Add summaries to each and every test.
peterwilsoncc Nov 4, 2026
03f777c
Tests: Remove dupes, clarify test names, add missing documented item.
peterwilsoncc Nov 4, 2026
69eb344
Remove stale reference to plugin.
peterwilsoncc Nov 4, 2026
c21efa6
Tests: fuirther fixes.
peterwilsoncc Nov 4, 2026
3442d7c
Use consistent subpackage name in source and test suites.
peterwilsoncc Nov 4, 2026
7a29f46
Add messsages to each assertion.
peterwilsoncc Nov 4, 2026
6b03ba0
Fix multi-line comment formatting.
peterwilsoncc Nov 4, 2026
4d6c65e
Rewrite docblocks as statements.
peterwilsoncc Nov 4, 2026
b0b6183
Add global annotations.
peterwilsoncc Nov 4, 2026
8fbf69e
Remove stale references to feature plgun.
peterwilsoncc Nov 4, 2026
9a396da
Docs: id -> ID.
peterwilsoncc Nov 4, 2026
aca1284
Remove stale plugin reference.
peterwilsoncc Nov 4, 2026
396db98
Use should consistently.
peterwilsoncc Nov 4, 2026
afaa809
Assert writes succeed.
peterwilsoncc Nov 4, 2026
8681f94
Further test hardening.
peterwilsoncc Nov 4, 2026
3362294
Rename data providers for their test when used by a single test only.
peterwilsoncc Nov 5, 2026
f0c4ef3
Remove stale plugin/docs reference.
peterwilsoncc Nov 5, 2026
def4dbe
Test roles individually.
peterwilsoncc Nov 5, 2026
09f2a64
Remove redundent test (same implies notsame).
peterwilsoncc Nov 5, 2026
7f20c90
Clarify message.
peterwilsoncc Nov 5, 2026
9988bc9
Modify/split test.
peterwilsoncc Nov 5, 2026
e7b36f4
Replace skipped tests with group annotations.
peterwilsoncc Nov 5, 2026
9803bce
Add tests with ms-required to multisite group.
peterwilsoncc Nov 5, 2026
3866ccd
Use skipWith(Out)Multisite helpers in conjunction with groups.
peterwilsoncc Nov 5, 2026
52222df
Remove interfaces from covers annotations.
peterwilsoncc Nov 5, 2026
a361440
Clarify docbloxk/.
peterwilsoncc Nov 5, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion src/wp-admin/includes/class-wp-site-health.php
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,6 @@
* @since 5.2.0
*/


require_once __DIR__ . '/secrets-site-health.php';

#[AllowDynamicProperties]
Expand Down
11 changes: 5 additions & 6 deletions src/wp-admin/includes/secrets-site-health.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
*
Expand Down Expand Up @@ -74,7 +73,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
*
Expand Down Expand Up @@ -130,7 +129,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.
Expand Down Expand Up @@ -218,7 +217,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
*
Expand Down
6 changes: 6 additions & 0 deletions src/wp-includes/load.php
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
87 changes: 37 additions & 50 deletions src/wp-includes/secrets.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
*/
Expand Down Expand Up @@ -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 = '';
}

Expand All @@ -208,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.
Expand Down Expand Up @@ -268,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'
Expand Down Expand Up @@ -301,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
Expand All @@ -314,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 {
Expand Down Expand Up @@ -350,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 {
Expand Down Expand Up @@ -385,30 +395,14 @@ 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 {
return ! empty( $GLOBALS['wp_secrets_dropin_loaded'] );
}



















/**
* Encrypts and stores a secret.
*
Expand All @@ -430,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
Expand Down Expand Up @@ -474,8 +467,6 @@ function wp_import_option_as_secret( string $option, string $name ) {
return _wp_secrets_set( $name, $value, false, true, 'imported' );
}



/**
* Retrieves a secret.
*
Expand Down Expand Up @@ -514,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.
Expand All @@ -528,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
Expand All @@ -542,7 +527,7 @@ function wp_retire_secret_version( string $name ) {
*
* @phpstan-return list<array{name: string, fingerprint: string, created: int, has_previous: bool, needs_rotation: bool}>|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 );
}

Expand All @@ -551,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
*
Expand Down Expand Up @@ -641,6 +625,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 {
Expand Down
15 changes: 7 additions & 8 deletions src/wp-includes/secrets/class-wp-secret.php
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand Down Expand Up @@ -224,13 +224,12 @@ 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() 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
*
Expand Down Expand Up @@ -314,7 +313,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.
*
Expand Down
1 change: 0 additions & 1 deletion src/wp-includes/secrets/class-wp-secrets-broken-store.php
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,6 @@ public function list_names( bool $network = false ): WP_Error {
return $this->error();
}


/**
* Builds the error every method returns.
*
Expand Down
4 changes: 2 additions & 2 deletions src/wp-includes/secrets/class-wp-secrets-cipher.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
10 changes: 5 additions & 5 deletions src/wp-includes/secrets/class-wp-secrets-key-manager.php
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading
Loading