Interface: WP_Secrets_Provider  - X-Ref

Interface for a secrets provider.

A provider is responsible for a secret: storing it, protecting it, and returning
it to a caller. It is the outermost extension point in the Secrets API, and the
one a hosting platform implements.

WordPress ships WP_Secrets_Libsodium_Provider, which encrypts with libsodium and
stores ciphertext in the options tables. That provider is the default rather than
a privileged case: a platform that protects credentials in a key management
service, a hardware security module, or its own control panel implements this
same interface.

A provider must be stronger than the default, never weaker. Storing a plaintext
where the default would have stored ciphertext is what this interface exists to
prevent. Receiving a value over an authenticated channel and holding it in a
hardware security module satisfies that requirement.

WordPress cannot verify any of this. A provider is loaded from a drop-in, which is
fully trusted code: it runs before plugins, and could already read every secret by
implementing the keyring. get_protection_boundary() and is_writable() are
declarations rather than enforcement. They exist so that a developer reviewing a
drop-in can see what it claims, Site Health can report where credentials are
protected, and a settings screen can determine that a write will be refused before
an operator enters a credential. They are not a security boundary.

Every implementation shares these contracts:

- Three states, never collapsed. get() returns a WP_Secret, null when the secret
does not exist, or WP_Error when it exists but cannot be produced. Reporting an
unreachable backend as absent turns an outage into an apparently deleted
credential.
- Fail closed. A provider that cannot answer returns WP_Error. It never
substitutes a weaker source, and never returns a partial or placeholder value.
- No filter on the retrieval path. A provider replaces a component; it is not a
hook. Nothing is given the opportunity to observe or alter a value in transit.
- Never persist a value more weakly than the provider protects it. A provider that
fetches over the network must not write the plaintext into the persistent object
cache. WP_Secret cannot round-trip a plaintext through wp_cache_set(), and
caching the raw value alongside it would undo that. Memoize within the request
only.