[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Secrets API: WP_Secrets_Broken_Provider class
   4   *
   5   * @package WordPress
   6   * @subpackage Secrets
   7   * @since 7.2.0
   8   */
   9  
  10  /**
  11   * The provider installed when a secrets.php drop-in did not load correctly.
  12   *
  13   * Every operation returns WP_Error. It exists so that a broken drop-in cannot be
  14   * mistaken for a working site with no secrets in it yet – which is the failure
  15   * mode that turns "my credential backend is misconfigured" into "my credentials
  16   * appear to have been deleted," and is precisely what this API's three-state return
  17   * exists to prevent.
  18   *
  19   * Deliberately not a fallback to the default provider. Reverting to local storage
  20   * because a host's KMS drop-in failed would quietly downgrade a site's protection
  21   * at the exact moment nobody is watching.
  22   *
  23   * @since 7.2.0
  24   */
  25  final class WP_Secrets_Broken_Provider implements WP_Secrets_Provider {
  26  
  27      /**
  28       * The single error every operation reports.
  29       *
  30       * @since 7.2.0
  31       *
  32       * @return WP_Error
  33       */
  34  	private function error(): WP_Error {
  35          return new WP_Error(
  36              WP_SECRETS_ERROR_STORE_UNAVAILABLE,
  37              __( 'The secrets.php drop-in did not load correctly, so no secret can be read or written. Fix or remove the drop-in.' )
  38          );
  39      }
  40  
  41      /**
  42       * Always an error.
  43       *
  44       * @since 7.2.0
  45       *
  46       * @param string $name    The secret's name.
  47       * @param string $version A WP_Secret_Version constant.
  48       * @param bool   $network Whether this is a network-scope secret.
  49       * @return WP_Error
  50       *
  51       * @phpstan-param WP_Secret_Version::CURRENT|WP_Secret_Version::PREVIOUS $version
  52       */
  53  	public function get( string $name, string $version, bool $network = false ): WP_Error {
  54          return $this->error();
  55      }
  56  
  57      /**
  58       * Always an error.
  59       *
  60       * @since 7.2.0
  61       *
  62       * @param string      $name           The secret's name.
  63       * @param string      $value          The plaintext value.
  64       * @param bool        $network        Whether this is a network-scope secret.
  65       * @param bool        $needs_rotation Ignored.
  66       * @param string|null $action         Ignored.
  67       * @return WP_Error
  68       */
  69  	public function set( string $name, $value, bool $network = false, bool $needs_rotation = false, ?string $action = null ): WP_Error {
  70          return $this->error();
  71      }
  72  
  73      /**
  74       * Always an error.
  75       *
  76       * @since 7.2.0
  77       *
  78       * @param string $name    The secret's name.
  79       * @param bool   $network Whether this is a network-scope secret.
  80       * @return WP_Error
  81       */
  82  	public function delete( string $name, bool $network = false ): WP_Error {
  83          return $this->error();
  84      }
  85  
  86      /**
  87       * Always an error.
  88       *
  89       * @since 7.2.0
  90       *
  91       * @param string $name    The secret's name.
  92       * @param bool   $network Whether this is a network-scope secret.
  93       * @return WP_Error
  94       */
  95  	public function retire_previous( string $name, bool $network = false ): WP_Error {
  96          return $this->error();
  97      }
  98  
  99      /**
 100       * Always an error.
 101       *
 102       * @since 7.2.0
 103       *
 104       * @param string $name_prefix Restrict to names beginning with this prefix.
 105       * @param bool   $network     Whether to list network-scope secrets.
 106       * @return WP_Error
 107       */
 108  	public function list_secrets( string $name_prefix = '', bool $network = false ): WP_Error {
 109          return $this->error();
 110      }
 111  
 112      /**
 113       * Says plainly that the drop-in is the problem.
 114       *
 115       * @since 7.2.0
 116       *
 117       * @return string
 118       */
 119  	public function get_label(): string {
 120          return __( 'Unavailable: the secrets.php drop-in did not load correctly' );
 121      }
 122  
 123      /**
 124       * Reports the provider boundary.
 125       *
 126       * Whatever was meant to protect these secrets is not WordPress, and is not
 127       * working.
 128       *
 129       * @since 7.2.0
 130       *
 131       * @return string
 132       *
 133       * @phpstan-return self::BOUNDARY_*
 134       */
 135  	public function get_protection_boundary(): string {
 136          return self::BOUNDARY_PROVIDER;
 137      }
 138  
 139      /**
 140       * Nothing is writable while the drop-in is broken.
 141       *
 142       * @since 7.2.0
 143       *
 144       * @return bool
 145       */
 146  	public function is_writable(): bool {
 147          return false;
 148      }
 149  }