CoreFiles by mySites.guru
secrets.php878 lines, 28,462 bytes, from wordpress-7.2-beta5.zip
Raw History Compare with 7.2-beta4
md5
91199a5fc77508701664a11b69166fc1
sha1
5fa5df53328396f37b833692b0a62e6df540c6d7
sha256
6344d75a3564f1e74f6f71afe204799bb59c8c54e907cb0fe115b9223df89740
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878
<?php
/**
 * Secrets API
 *
 * @package WordPress
 * @subpackage Secrets
 * @since 7.2.0
 */

/**
 * The store or key backend is misbehaving.
 *
 * The secret exists and was decrypted, but the backend it came from failed in a way
 * none of the more specific codes below describe.
 *
 * @since 7.2.0
 */
define( 'WP_SECRETS_ERROR_DECRYPTION_FAILED', 'secret_decryption_failed' );

/**
 * The key needed to encrypt or decrypt a secret could not be obtained.
 *
 * The keyring is unreachable, misconfigured, or refusing to answer.
 *
 * @since 7.2.0
 */
define( 'WP_SECRETS_ERROR_KEY_UNAVAILABLE', 'secret_key_unavailable' );

/**
 * The storage back end could not be reached at all.
 *
 * @since 7.2.0
 */
define( 'WP_SECRETS_ERROR_STORE_UNAVAILABLE', 'secret_store_unavailable' );

/**
 * A secret name failed wp_secrets_validate_name().
 *
 * @since 7.2.0
 */
define( 'WP_SECRETS_ERROR_INVALID_NAME', 'secret_invalid_name' );

/**
 * A secret value was not a string.
 *
 * @since 7.2.0
 */
define( 'WP_SECRETS_ERROR_INVALID_VALUE', 'secret_invalid_value' );

/**
 * A caller passed an argument this API cannot act on.
 *
 * 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
 * validation, an unavailable key), while this one only ever means the calling
 * code is wrong. Every site that returns it also calls _doing_it_wrong(), so the
 * mistake is visible in development rather than only in a return value the caller
 * may not be checking.
 *
 * @since 7.2.0
 */
define( 'WP_SECRETS_ERROR_INVALID_ARGUMENT', 'secret_invalid_argument' );

/**
 * The cipher this API depends on is unavailable.
 *
 * Neither libsodium nor its sodium_compat fallback is present in this environment.
 *
 * @since 7.2.0
 */
define( 'WP_SECRETS_ERROR_CRYPTO_UNAVAILABLE', 'secret_crypto_unavailable' );

/**
 * A stored record could not be parsed as a secret record at all.
 *
 * Distinct from decrypting incorrectly, which is WP_SECRETS_ERROR_DECRYPTION_FAILED.
 *
 * @since 7.2.0
 */
define( 'WP_SECRETS_ERROR_RECORD_MALFORMED', 'secret_record_malformed' );

/**
 * A stored record parses, but its format version is not one this API understands.
 *
 * 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
 * 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
 */
define( 'WP_SECRETS_ERROR_RECORD_UNSUPPORTED_VERSION', 'secret_record_unsupported_version' );

/**
 * The active provider does not accept writes.
 *
 * Its credentials are managed by host tooling, a control panel, or a key policy
 * outside WordPress. Distinct from WP_SECRETS_ERROR_STORE_UNAVAILABLE, which means
 * the write could have succeeded and did not. This one means it was never possible.
 *
 * @since 7.2.0
 */
define( 'WP_SECRETS_ERROR_PROVIDER_READ_ONLY', 'secret_provider_read_only' );

/**
 * The current record format version.
 *
 * Bumped only if the record shape in WP_Secrets_Cipher's slot arrays ever changes
 * incompatibly.
 *
 * @since 7.2.0
 */
define( 'WP_SECRETS_RECORD_VERSION', 1 );

/**
 * The longest a secret name may be.
 *
 * The wp_options.option_name column allows 191 characters. The longest prefix this
 * API stores under is '_wp_network_secret_' (19 characters), so 191 - 19 = 172
 * is the longest name any store built on core's options tables can accept
 * without truncation, and every store is held to the same limit for
 * consistency regardless of what a specific backend could technically fit.
 *
 * @since 7.2.0
 */
define( 'WP_SECRETS_MAX_NAME_LENGTH', 172 );

/**
 * Capability required to manage site-scope secrets at the operator boundary.
 *
 * Checked by WP-CLI and by a future admin screen, never by the function-level API
 * itself. See wp_set_secret() for why.
 *
 * @since 7.2.0
 */
define( 'WP_SECRETS_CAP_MANAGE', 'manage_secrets' );

/**
 * Capability required at the operator boundary to manage network-scope secrets.
 *
 * @since 7.2.0
 */
define( 'WP_SECRETS_CAP_MANAGE_NETWORK', 'manage_network_secrets' );

/**
 * Best-effort clearing of a plaintext value from memory.
 *
 * This is hygiene, not a guarantee. PHP strings are reference-counted and often
 * shared by copy-on-write; sodium_memzero() can only scrub the bytes of a string it
 * exclusively owns; if another reference to the same value exists elsewhere,
 * PHP forces a private copy before zeroing rather than corrupting the shared buffer,
 * and that other reference is left completely untouched. Call this on every plaintext
 * local as soon as it is no longer needed, and do not keep incidental copies around.
 *
 * Under sodium_compat, core's documented fallback when the libsodium extension is
 * unavailable, this scrubs nothing. A userland polyfill cannot reach a PHP string's
 * underlying memory at all. Overwriting the local binding is the only thing available
 * in that case, and it removes the live reference from this scope without touching
 * the memory the string used to occupy.
 *
 * @since 7.2.0
 *
 * @param string $value The value to clear, by reference.
 */
function wp_secrets_memzero( &$value ): void {
	if ( ! is_string( $value ) ) {
		return;
	}

	if ( function_exists( 'sodium_memzero' ) ) {
		try {
			/*
			 * sodium_memzero() is called through a true reference alias, not
			 * directly on $value, so that a static analyzer's stub for
			 * sodium_memzero() (whose own by-ref parameter is documented as
			 * becoming null) is evaluated against a local variable rather than
			 * against this function's own by-ref parameter. The alias is not a
			 * copy: `=&` shares the identical underlying storage, so this still
			 * zeroes the real buffer the caller holds.
			 */
			$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.
			 */
			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.
	 */
	$value = '';
}

/**
 * Validates a secret's name.
 *
 * Names take the form 'plugin-slug/secret-name': lowercase alphanumerics,
 * hyphens, and underscores in each segment, exactly one '/' separating them,
 * and no segment starting or ending with a hyphen or underscore.
 *
 * Namespacing is a matter of organization, not security. It groups secrets by owner
 * so that listings and admin screens can be sensible. It confers no isolation: any
 * 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: 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.
 *
 * @since 7.2.0
 *
 * @param string $name Candidate secret name.
 * @return true|WP_Error True if $name is usable, including the unnamespaced form.
 *                       Otherwise WP_Error with code WP_SECRETS_ERROR_INVALID_NAME.
 */
function wp_secrets_validate_name( string $name ) {
	if ( '' === $name ) {
		return new WP_Error(
			WP_SECRETS_ERROR_INVALID_NAME,
			__( 'Secret names must not be empty.' )
		);
	}

	if ( strlen( $name ) > WP_SECRETS_MAX_NAME_LENGTH ) {
		return new WP_Error(
			WP_SECRETS_ERROR_INVALID_NAME,
			sprintf(
				/* translators: %d: Maximum allowed length, in characters. */
				__( 'Secret names must be %d characters or fewer.' ),
				WP_SECRETS_MAX_NAME_LENGTH
			)
		);
	}

	$slashes = substr_count( $name, '/' );

	if ( $slashes > 1 ) {
		return new WP_Error(
			WP_SECRETS_ERROR_INVALID_NAME,
			__( 'Secret names may contain at most one "/", separating a namespace from a key.' )
		);
	}

	$segment_pattern = '/^[a-z0-9]([a-z0-9_-]*[a-z0-9])?\z/';

	if ( 0 === $slashes ) {
		if ( ! preg_match( $segment_pattern, $name ) ) {
			return new WP_Error(
				WP_SECRETS_ERROR_INVALID_NAME,
				__( 'Secret names may contain only lowercase letters, numbers, hyphens, and underscores, and must not start or end with a hyphen or underscore.' )
			);
		}

		/*
		 * Reported here rather than at each public entry point: this is the one
		 * place that decides what a name is, so a caller cannot reach the store
		 * with an unnamespaced name without passing through it.
		 */
		_doing_it_wrong(
			__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 existing code using flat names can be ported incrementally.' ),
				$name
			),
			'7.2.0'
		);

		return true;
	}

	$segments  = explode( '/', $name );
	$namespace = $segments[0];
	$key       = $segments[1];

	if ( '' === $namespace || '' === $key ) {
		return new WP_Error(
			WP_SECRETS_ERROR_INVALID_NAME,
			__( 'Both segments of a secret name must be non-empty.' )
		);
	}

	if ( ! preg_match( $segment_pattern, $namespace ) || ! preg_match( $segment_pattern, $key ) ) {
		return new WP_Error(
			WP_SECRETS_ERROR_INVALID_NAME,
			__( 'Secret name segments may contain only lowercase letters, numbers, hyphens, and underscores, and must not start or end with a hyphen or underscore.' )
		);
	}

	return true;
}

/**
 * Returns the active secret store.
 *
 * 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
 * silently using the default: the drop-in's presence signals the operator wants
 * storage other than local options, and falling back to local options anyway would
 * be the exact silent downgrade this API refuses to make.
 *
 * @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 {
	static $store = null;

	if ( $store instanceof WP_Secrets_Store ) {
		return $store;
	}

	if ( ! empty( $GLOBALS['wp_secrets_dropin_broken'] ) ) {
		$store = new WP_Secrets_Broken_Store();

		return $store;
	}

	if ( isset( $GLOBALS['wp_secrets_store'] ) && $GLOBALS['wp_secrets_store'] instanceof WP_Secrets_Store ) {
		$store = $GLOBALS['wp_secrets_store'];

		return $store;
	}

	$store = new WP_Secrets_Option_Store();

	return $store;
}

/**
 * Returns the active key manager.
 *
 * A secrets.php drop-in overrides the keyring by setting
 * $GLOBALS['wp_secrets_keyring'] to an instance before this is first called. See
 * _wp_secrets_get_store() for why an invalid override or a failed drop-in load
 * fails closed (WP_Secrets_Broken_Keyring) rather than falling back to the default.
 *
 * @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 {
	static $key_manager = null;

	if ( $key_manager instanceof WP_Secrets_Key_Manager ) {
		return $key_manager;
	}

	if ( ! empty( $GLOBALS['wp_secrets_dropin_broken'] ) ) {
		$key_manager = new WP_Secrets_Key_Manager( new WP_Secrets_Broken_Keyring() );

		return $key_manager;
	}

	$keyring = null;

	if ( isset( $GLOBALS['wp_secrets_keyring'] ) && $GLOBALS['wp_secrets_keyring'] instanceof WP_Secrets_Keyring ) {
		$keyring = $GLOBALS['wp_secrets_keyring'];
	}

	$key_manager = new WP_Secrets_Key_Manager( $keyring );

	return $key_manager;
}

/**
 * Whether a secrets.php drop-in is present and was loaded.
 *
 * True whether or not the drop-in successfully provided a store or keyring
 * override. It reports presence rather than health; Site Health reports separately
 * on whether a loaded drop-in is actually working.
 *
 * @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.
 *
 * Encryption is unconditional: there is no plaintext mode and no constant to
 * disable it. No capability check is applied here, because this must be callable from
 * cron, REST, and front-end requests where no user is logged in. Enforce
 * capabilities at the operator boundary (CLI, an admin screen) instead.
 *
 * @since 7.2.0
 *
 * @param string $name  The secret's namespaced name ('plugin-slug/secret-name').
 * @param string $value The plaintext value to store.
 * @return true|WP_Error
 */
function wp_set_secret(
	string $name,
	#[\SensitiveParameter]
	$value
) {
	return _wp_secrets_set( $name, $value, false );
}

/**
 * Imports an existing option's value as a secret.
 *
 * 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
 * replication paths that option went through; re-encrypting it here does not undo
 * that, and the flag exists so an operator (or a future admin screen) knows to
 * actually rotate the value rather than considering the migration finished.
 *
 * @since 7.2.0
 *
 * @param string $option The existing option's name.
 * @param string $name   The secret's namespaced name to store it under.
 * @return true|WP_Error
 */
function wp_import_option_as_secret( string $option, string $name ) {
	if ( '' === $option ) {
		return new WP_Error(
			WP_SECRETS_ERROR_INVALID_VALUE,
			__( 'The option name must not be empty.' )
		);
	}

	$value = get_option( $option, null );

	if ( null === $value ) {
		return new WP_Error(
			WP_SECRETS_ERROR_INVALID_VALUE,
			__( 'The option does not exist.' )
		);
	}

	if ( ! is_string( $value ) ) {
		return new WP_Error(
			WP_SECRETS_ERROR_INVALID_VALUE,
			__( 'The option value is not a string and cannot be imported as a secret.' )
		);
	}

	return _wp_secrets_set( $name, $value, false, true, 'imported' );
}

/**
 * Retrieves a secret.
 *
 * Three states, never collapsed: a WP_Secret if it exists and decrypts, null if it
 * does not exist, WP_Error if it exists but could not be retrieved. No capability
 * check is applied here. See wp_set_secret().
 *
 * @since 7.2.0
 *
 * @param string $name    The secret's namespaced name.
 * @param string $version A WP_Secret_Version constant. Default WP_Secret_Version::CURRENT.
 * @return WP_Secret|null|WP_Error
 *
 * @phpstan-param WP_Secret_Version::CURRENT|WP_Secret_Version::PREVIOUS $version
 */
function wp_get_secret( string $name, string $version = WP_Secret_Version::CURRENT ) {
	return _wp_secrets_get( $name, $version, false );
}

/**
 * Deletes a secret.
 *
 * @since 7.2.0
 *
 * @param string $name The secret's namespaced name.
 * @return true|WP_Error
 */
function wp_delete_secret( string $name ) {
	return _wp_secrets_delete( $name, false );
}

/**
 * Clears a secret's previous version, retiring it for good.
 *
 * An explicit operator action, with no timers and no cron. Calling this on a secret
 * that has never been rotated, or that does not exist, is a successful no-op:
 * the previous slot is already absent either way.
 *
 * @since 7.2.0
 *
 * @param string $name The secret's namespaced name.
 * @return true|WP_Error
 */
function wp_retire_secret_version( string $name ) {
	return _wp_secrets_retire( $name, false );
}

/**
 * Lists secrets by name and metadata. Never a value.
 *
 * @since 7.2.0
 *
 * @param string $namespace Only secrets whose name starts with "{$namespace}/" are
 *                          returned. Default '' returns every secret.
 * @return array|WP_Error Array of associative arrays, each with keys 'name',
 *                        'fingerprint', 'created', 'has_previous', and
 *                        'needs_rotation'.
 *
 * @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 public parameter name; renaming it would break named-argument callers.
	return _wp_secrets_list( $namespace, false );
}

/**
 * Encrypts and stores a network-scope secret.
 *
 * 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.
 *
 * @since 7.2.0
 *
 * @param string $name  The secret's namespaced name.
 * @param string $value The plaintext value to store.
 * @return true|WP_Error
 */
function wp_set_network_secret(
	string $name,
	#[\SensitiveParameter]
	$value
) {
	return _wp_secrets_set( $name, $value, true );
}

/**
 * Retrieves a network-scope secret.
 *
 * @since 7.2.0
 *
 * @param string $name    The secret's namespaced name.
 * @param string $version A WP_Secret_Version constant. Default WP_Secret_Version::CURRENT.
 * @return WP_Secret|null|WP_Error
 *
 * @phpstan-param WP_Secret_Version::CURRENT|WP_Secret_Version::PREVIOUS $version
 */
function wp_get_network_secret( string $name, string $version = WP_Secret_Version::CURRENT ) {
	return _wp_secrets_get( $name, $version, true );
}

/**
 * Deletes a network-scope secret.
 *
 * @since 7.2.0
 *
 * @param string $name The secret's namespaced name.
 * @return true|WP_Error
 */
function wp_delete_network_secret( string $name ) {
	return _wp_secrets_delete( $name, true );
}

/**
 * Clears a network-scope secret's previous version.
 *
 * @since 7.2.0
 *
 * @param string $name The secret's namespaced name.
 * @return true|WP_Error
 */
function wp_retire_network_secret_version( string $name ) {
	return _wp_secrets_retire( $name, true );
}

/**
 * Lists network-scope secrets by name and metadata. Never a value.
 *
 * @since 7.2.0
 *
 * @param string $namespace Only secrets whose name starts with "{$namespace}/" are
 *                          returned. Default '' returns every network-scope secret.
 * @return array|WP_Error
 *
 * @phpstan-return list<array{name: string, fingerprint: string, created: int, has_previous: bool, needs_rotation: bool}>|WP_Error
 */
function wp_list_network_secrets( string $namespace = '' ) { // phpcs:ignore Universal.NamingConventions.NoReservedKeywordParameterNames.namespaceFound -- matches wp_list_secrets()'s own signature.
	return _wp_secrets_list( $namespace, true );
}

/**
 * Returns the active provider.
 *
 * The provider is whatever is responsible for holding, protecting, and answering for
 * this site's secrets.
 *
 * A secrets.php drop-in overrides it by setting $GLOBALS['wp_secrets_provider'] to
 * an instance before this is first called. Absent that, the provider WordPress
 * ships is assembled from the active store and keyring, which a drop-in can also
 * replace individually, so wanting host-managed key custody with default storage needs
 * no provider at all.
 *
 * No filter is applied here, or anywhere on the retrieval path. Substitution is by
 * replacement, never by interception: a filter that can observe which provider
 * answers is one step from a filter that can answer instead.
 *
 * Cached for the request. A failed drop-in fails closed, returning WP_Error from
 * every operation, rather than silently reverting to the default, because a
 * misconfigured credential backend must never look like a working one that happens
 * to be empty.
 *
 * @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 {
	static $provider = null;

	if ( $provider instanceof WP_Secrets_Provider ) {
		return $provider;
	}

	if ( ! empty( $GLOBALS['wp_secrets_dropin_broken'] ) ) {
		$provider = new WP_Secrets_Broken_Provider();

		return $provider;
	}

	if ( isset( $GLOBALS['wp_secrets_provider'] ) ) {
		/*
		 * Set, but not a provider. Failing closed here rather than falling through to
		 * the default is the whole point: a platform drop-in that names its class
		 * wrongly would otherwise have every secret served from wp_options, where none
		 * of them exist, and a site whose credentials are held elsewhere would report
		 * them absent rather than unreachable.
		 */
		if ( ! ( $GLOBALS['wp_secrets_provider'] instanceof WP_Secrets_Provider ) ) {
			$provider = new WP_Secrets_Broken_Provider();

			return $provider;
		}

		$provider = $GLOBALS['wp_secrets_provider'];

		return $provider;
	}

	$provider = new WP_Secrets_Libsodium_Provider(
		_wp_secrets_get_store(),
		_wp_secrets_get_key_manager()
	);

	return $provider;
}

/**
 * Whether the active provider accepts writes.
 *
 * Exists so a settings screen can disable its own save control before an operator
 * types a credential into a field that will only reject it. A provider whose
 * credentials are managed by host tooling or a control panel reports false.
 *
 * @since 7.2.0
 *
 * @return bool
 */
function wp_secrets_provider_is_writable(): bool {
	return _wp_secrets_get_provider()->is_writable();
}

/**
 * Whether the Secrets API can store and read secrets on this site.
 *
 * A plugin can check this before it moves a credential into the Secrets API, and
 * keep its existing storage while it returns false:
 *
 *     if ( wp_is_secrets_api_available() ) {
 *         // Move the credential, then use wp_set_secret() and wp_get_secret().
 *     } else {
 *         // Keep using the existing storage.
 *     }
 *
 * Returns false when the secrets.php drop-in failed to load, when the default
 * keyring has no usable WP_SECRETS_KEY, or when WP_SECRETS_KEY cannot unwrap the
 * stored root key. The last happens when a site that already stored secrets adds
 * or changes the key without re-wrapping the root key.
 *
 * A provider or keyring from a working drop-in manages its own keys, so it is
 * reported as available. Its backend can still be unreachable on a given request,
 * which each call reports as a WP_Error.
 *
 * Whether the provider accepts writes is a separate question. See
 * wp_secrets_provider_is_writable().
 *
 * @since 7.2.0
 *
 * @global WP_Secrets_Provider $wp_secrets_provider Optional. Provider override set by the drop-in.
 *
 * @return bool
 */
function wp_is_secrets_api_available(): bool {
	if ( _wp_secrets_get_provider() instanceof WP_Secrets_Broken_Provider ) {
		return false;
	}

	if ( isset( $GLOBALS['wp_secrets_provider'] ) ) {
		return true;
	}

	$keyring = _wp_secrets_get_key_manager()->get_keyring();

	if ( $keyring instanceof WP_Secrets_Broken_Keyring ) {
		return false;
	}

	if ( $keyring instanceof WP_Secrets_Config_Key_Provider ) {
		$is_usable = in_array(
			$keyring->get_key_status(),
			array( WP_Secrets_Config_Key_Provider::KEY_STATUS_BASE64, WP_Secrets_Config_Key_Provider::KEY_STATUS_LEGACY ),
			true
		);

		if ( ! $is_usable ) {
			return false;
		}

		$root_key = _wp_secrets_get_key_manager()->get_root_key( false );

		if ( ! is_wp_error( $root_key ) ) {
			wp_secrets_memzero( $root_key );

			return true;
		}

		// With no root key stored yet, the first write creates one under this key.
		return false === get_site_option( WP_Secrets_Key_Manager::ROOT_KEY_OPTION );
	}

	return true;
}

/**
 * A human-readable description of what is protecting this site's secrets.
 *
 * For Site Health and a future admin screen. Never key material, never a value.
 *
 * @since 7.2.0
 *
 * @return string
 */
function wp_secrets_provider_label(): string {
	return _wp_secrets_get_provider()->get_label();
}

/**
 * Shared implementation behind wp_set_secret() and wp_set_network_secret().
 *
 * @since 7.2.0
 *
 * @param string      $name            The secret's name.
 * @param string      $value           The plaintext value.
 * @param bool        $network         Whether this is a network-scope secret.
 * @param bool        $needs_rotation  Flag the stored secret as needing rotation.
 * @param string|null $action_override Overrides the $action reported to
 *                                     wp_secret_changed.
 * @return true|WP_Error
 */
function _wp_secrets_set(
	string $name,
	#[\SensitiveParameter]
	$value,
	bool $network,
	bool $needs_rotation = false,
	?string $action_override = null
) {
	return _wp_secrets_get_provider()->set( $name, $value, $network, $needs_rotation, $action_override );
}

/**
 * Shared implementation behind wp_get_secret() and wp_get_network_secret().
 *
 * @since 7.2.0
 *
 * @param string $name    The secret's name.
 * @param string $version A WP_Secret_Version constant.
 * @param bool   $network Whether this is a network-scope secret.
 * @return WP_Secret|null|WP_Error
 *
 * @phpstan-param WP_Secret_Version::CURRENT|WP_Secret_Version::PREVIOUS $version
 */
function _wp_secrets_get( string $name, string $version, bool $network ) {
	/*
	 * Checked here rather than inside the provider: this is a contract between
	 * the API and its caller, and asking every provider to re-validate a core
	 * constant would be duplicated work that a third-party provider could
	 * silently skip.
	 */
	if ( ! in_array( $version, array( WP_Secret_Version::CURRENT, WP_Secret_Version::PREVIOUS ), true ) ) {
		_doing_it_wrong(
			__FUNCTION__,
			__( 'The version must be WP_Secret_Version::CURRENT or WP_Secret_Version::PREVIOUS.' ),
			'7.2.0'
		);

		return new WP_Error(
			WP_SECRETS_ERROR_INVALID_ARGUMENT,
			__( 'The version must be WP_Secret_Version::CURRENT or WP_Secret_Version::PREVIOUS.' )
		);
	}

	return _wp_secrets_get_provider()->get( $name, $version, $network );
}

/**
 * Shared implementation behind wp_delete_secret() and wp_delete_network_secret().
 *
 * @since 7.2.0
 *
 * @param string $name    The secret's name.
 * @param bool   $network Whether this is a network-scope secret.
 * @return true|WP_Error
 */
function _wp_secrets_delete( string $name, bool $network ) {
	return _wp_secrets_get_provider()->delete( $name, $network );
}

/**
 * Shared implementation behind wp_retire_secret_version() and its network twin.
 *
 * @since 7.2.0
 *
 * @param string $name    The secret's name.
 * @param bool   $network Whether this is a network-scope secret.
 * @return true|WP_Error
 */
function _wp_secrets_retire( string $name, bool $network ) {
	return _wp_secrets_get_provider()->retire_previous( $name, $network );
}

/**
 * Shared implementation behind wp_list_secrets() and wp_list_network_secrets().
 *
 * @since 7.2.0
 *
 * @param string $name_prefix Restrict to names beginning with this prefix.
 * @param bool   $network     Whether to list network-scope secrets.
 * @return array|WP_Error
 *
 * @phpstan-return list<array{name: string, fingerprint: string, created: int, has_previous: bool, needs_rotation: bool}>|WP_Error
 */
function _wp_secrets_list( string $name_prefix, bool $network ) {
	return _wp_secrets_get_provider()->list_secrets( $name_prefix, $network );
}

No other release has this exact content. See every version of this file.