wp/wp-includes/class-wp-application-passwords.php
changeset 18 be944660c56a
child 19 3d72ae0968f4
equal deleted inserted replaced
17:34716fd837a4 18:be944660c56a
       
     1 <?php
       
     2 /**
       
     3  * WP_Application_Passwords class
       
     4  *
       
     5  * @package WordPress
       
     6  * @since   5.6.0
       
     7  */
       
     8 
       
     9 /**
       
    10  * Class for displaying, modifying, and sanitizing application passwords.
       
    11  *
       
    12  * @package WordPress
       
    13  */
       
    14 class WP_Application_Passwords {
       
    15 
       
    16 	/**
       
    17 	 * The application passwords user meta key.
       
    18 	 *
       
    19 	 * @since 5.6.0
       
    20 	 *
       
    21 	 * @var string
       
    22 	 */
       
    23 	const USERMETA_KEY_APPLICATION_PASSWORDS = '_application_passwords';
       
    24 
       
    25 	/**
       
    26 	 * The option name used to store whether application passwords is in use.
       
    27 	 *
       
    28 	 * @since 5.6.0
       
    29 	 *
       
    30 	 * @var string
       
    31 	 */
       
    32 	const OPTION_KEY_IN_USE = 'using_application_passwords';
       
    33 
       
    34 	/**
       
    35 	 * The generated application password length.
       
    36 	 *
       
    37 	 * @since 5.6.0
       
    38 	 *
       
    39 	 * @var int
       
    40 	 */
       
    41 	const PW_LENGTH = 24;
       
    42 
       
    43 	/**
       
    44 	 * Checks if Application Passwords are being used by the site.
       
    45 	 *
       
    46 	 * This returns true if at least one App Password has ever been created.
       
    47 	 *
       
    48 	 * @since 5.6.0
       
    49 	 *
       
    50 	 * @return bool
       
    51 	 */
       
    52 	public static function is_in_use() {
       
    53 		$network_id = get_main_network_id();
       
    54 		return (bool) get_network_option( $network_id, self::OPTION_KEY_IN_USE );
       
    55 	}
       
    56 
       
    57 	/**
       
    58 	 * Creates a new application password.
       
    59 	 *
       
    60 	 * @since 5.6.0
       
    61 	 * @since 5.7.0 Returns WP_Error if application name already exists.
       
    62 	 *
       
    63 	 * @param int   $user_id  User ID.
       
    64 	 * @param array $args     Information about the application password.
       
    65 	 * @return array|WP_Error The first key in the array is the new password, the second is its detailed information.
       
    66 	 *                        A WP_Error instance is returned on error.
       
    67 	 */
       
    68 	public static function create_new_application_password( $user_id, $args = array() ) {
       
    69 		if ( ! empty( $args['name'] ) ) {
       
    70 			$args['name'] = sanitize_text_field( $args['name'] );
       
    71 		}
       
    72 
       
    73 		if ( empty( $args['name'] ) ) {
       
    74 			return new WP_Error( 'application_password_empty_name', __( 'An application name is required to create an application password.' ), array( 'status' => 400 ) );
       
    75 		}
       
    76 
       
    77 		if ( self::application_name_exists_for_user( $user_id, $args['name'] ) ) {
       
    78 			return new WP_Error( 'application_password_duplicate_name', __( 'Each application name should be unique.' ), array( 'status' => 409 ) );
       
    79 		}
       
    80 
       
    81 		$new_password    = wp_generate_password( static::PW_LENGTH, false );
       
    82 		$hashed_password = wp_hash_password( $new_password );
       
    83 
       
    84 		$new_item = array(
       
    85 			'uuid'      => wp_generate_uuid4(),
       
    86 			'app_id'    => empty( $args['app_id'] ) ? '' : $args['app_id'],
       
    87 			'name'      => $args['name'],
       
    88 			'password'  => $hashed_password,
       
    89 			'created'   => time(),
       
    90 			'last_used' => null,
       
    91 			'last_ip'   => null,
       
    92 		);
       
    93 
       
    94 		$passwords   = static::get_user_application_passwords( $user_id );
       
    95 		$passwords[] = $new_item;
       
    96 		$saved       = static::set_user_application_passwords( $user_id, $passwords );
       
    97 
       
    98 		if ( ! $saved ) {
       
    99 			return new WP_Error( 'db_error', __( 'Could not save application password.' ) );
       
   100 		}
       
   101 
       
   102 		$network_id = get_main_network_id();
       
   103 		if ( ! get_network_option( $network_id, self::OPTION_KEY_IN_USE ) ) {
       
   104 			update_network_option( $network_id, self::OPTION_KEY_IN_USE, true );
       
   105 		}
       
   106 
       
   107 		/**
       
   108 		 * Fires when an application password is created.
       
   109 		 *
       
   110 		 * @since 5.6.0
       
   111 		 *
       
   112 		 * @param int    $user_id      The user ID.
       
   113 		 * @param array  $new_item     The details about the created password.
       
   114 		 * @param string $new_password The unhashed generated app password.
       
   115 		 * @param array  $args         Information used to create the application password.
       
   116 		 */
       
   117 		do_action( 'wp_create_application_password', $user_id, $new_item, $new_password, $args );
       
   118 
       
   119 		return array( $new_password, $new_item );
       
   120 	}
       
   121 
       
   122 	/**
       
   123 	 * Gets a user's application passwords.
       
   124 	 *
       
   125 	 * @since 5.6.0
       
   126 	 *
       
   127 	 * @param int $user_id User ID.
       
   128 	 * @return array The list of app passwords.
       
   129 	 */
       
   130 	public static function get_user_application_passwords( $user_id ) {
       
   131 		$passwords = get_user_meta( $user_id, static::USERMETA_KEY_APPLICATION_PASSWORDS, true );
       
   132 
       
   133 		if ( ! is_array( $passwords ) ) {
       
   134 			return array();
       
   135 		}
       
   136 
       
   137 		$save = false;
       
   138 
       
   139 		foreach ( $passwords as $i => $password ) {
       
   140 			if ( ! isset( $password['uuid'] ) ) {
       
   141 				$passwords[ $i ]['uuid'] = wp_generate_uuid4();
       
   142 				$save                    = true;
       
   143 			}
       
   144 		}
       
   145 
       
   146 		if ( $save ) {
       
   147 			static::set_user_application_passwords( $user_id, $passwords );
       
   148 		}
       
   149 
       
   150 		return $passwords;
       
   151 	}
       
   152 
       
   153 	/**
       
   154 	 * Gets a user's application password with the given uuid.
       
   155 	 *
       
   156 	 * @since 5.6.0
       
   157 	 *
       
   158 	 * @param int    $user_id User ID.
       
   159 	 * @param string $uuid    The password's uuid.
       
   160 	 * @return array|null The application password if found, null otherwise.
       
   161 	 */
       
   162 	public static function get_user_application_password( $user_id, $uuid ) {
       
   163 		$passwords = static::get_user_application_passwords( $user_id );
       
   164 
       
   165 		foreach ( $passwords as $password ) {
       
   166 			if ( $password['uuid'] === $uuid ) {
       
   167 				return $password;
       
   168 			}
       
   169 		}
       
   170 
       
   171 		return null;
       
   172 	}
       
   173 
       
   174 	/**
       
   175 	 * Checks if application name exists for this user.
       
   176 	 *
       
   177 	 * @since 5.7.0
       
   178 	 *
       
   179 	 * @param int    $user_id User ID.
       
   180 	 * @param string $name    Application name.
       
   181 	 * @return bool Whether provided application name exists or not.
       
   182 	 */
       
   183 	public static function application_name_exists_for_user( $user_id, $name ) {
       
   184 		$passwords = static::get_user_application_passwords( $user_id );
       
   185 
       
   186 		foreach ( $passwords as $password ) {
       
   187 			if ( strtolower( $password['name'] ) === strtolower( $name ) ) {
       
   188 				return true;
       
   189 			}
       
   190 		}
       
   191 
       
   192 		return false;
       
   193 	}
       
   194 
       
   195 	/**
       
   196 	 * Updates an application password.
       
   197 	 *
       
   198 	 * @since 5.6.0
       
   199 	 *
       
   200 	 * @param int    $user_id User ID.
       
   201 	 * @param string $uuid    The password's uuid.
       
   202 	 * @param array  $update  Information about the application password to update.
       
   203 	 * @return true|WP_Error True if successful, otherwise a WP_Error instance is returned on error.
       
   204 	 */
       
   205 	public static function update_application_password( $user_id, $uuid, $update = array() ) {
       
   206 		$passwords = static::get_user_application_passwords( $user_id );
       
   207 
       
   208 		foreach ( $passwords as &$item ) {
       
   209 			if ( $item['uuid'] !== $uuid ) {
       
   210 				continue;
       
   211 			}
       
   212 
       
   213 			if ( ! empty( $update['name'] ) ) {
       
   214 				$update['name'] = sanitize_text_field( $update['name'] );
       
   215 			}
       
   216 
       
   217 			$save = false;
       
   218 
       
   219 			if ( ! empty( $update['name'] ) && $item['name'] !== $update['name'] ) {
       
   220 				$item['name'] = $update['name'];
       
   221 				$save         = true;
       
   222 			}
       
   223 
       
   224 			if ( $save ) {
       
   225 				$saved = static::set_user_application_passwords( $user_id, $passwords );
       
   226 
       
   227 				if ( ! $saved ) {
       
   228 					return new WP_Error( 'db_error', __( 'Could not save application password.' ) );
       
   229 				}
       
   230 			}
       
   231 
       
   232 			/**
       
   233 			 * Fires when an application password is updated.
       
   234 			 *
       
   235 			 * @since 5.6.0
       
   236 			 *
       
   237 			 * @param int   $user_id The user ID.
       
   238 			 * @param array $item    The updated app password details.
       
   239 			 * @param array $update  The information to update.
       
   240 			 */
       
   241 			do_action( 'wp_update_application_password', $user_id, $item, $update );
       
   242 
       
   243 			return true;
       
   244 		}
       
   245 
       
   246 		return new WP_Error( 'application_password_not_found', __( 'Could not find an application password with that id.' ) );
       
   247 	}
       
   248 
       
   249 	/**
       
   250 	 * Records that an application password has been used.
       
   251 	 *
       
   252 	 * @since 5.6.0
       
   253 	 *
       
   254 	 * @param int    $user_id User ID.
       
   255 	 * @param string $uuid    The password's uuid.
       
   256 	 * @return true|WP_Error True if the usage was recorded, a WP_Error if an error occurs.
       
   257 	 */
       
   258 	public static function record_application_password_usage( $user_id, $uuid ) {
       
   259 		$passwords = static::get_user_application_passwords( $user_id );
       
   260 
       
   261 		foreach ( $passwords as &$password ) {
       
   262 			if ( $password['uuid'] !== $uuid ) {
       
   263 				continue;
       
   264 			}
       
   265 
       
   266 			// Only record activity once a day.
       
   267 			if ( $password['last_used'] + DAY_IN_SECONDS > time() ) {
       
   268 				return true;
       
   269 			}
       
   270 
       
   271 			$password['last_used'] = time();
       
   272 			$password['last_ip']   = $_SERVER['REMOTE_ADDR'];
       
   273 
       
   274 			$saved = static::set_user_application_passwords( $user_id, $passwords );
       
   275 
       
   276 			if ( ! $saved ) {
       
   277 				return new WP_Error( 'db_error', __( 'Could not save application password.' ) );
       
   278 			}
       
   279 
       
   280 			return true;
       
   281 		}
       
   282 
       
   283 		// Specified Application Password not found!
       
   284 		return new WP_Error( 'application_password_not_found', __( 'Could not find an application password with that id.' ) );
       
   285 	}
       
   286 
       
   287 	/**
       
   288 	 * Deletes an application password.
       
   289 	 *
       
   290 	 * @since 5.6.0
       
   291 	 *
       
   292 	 * @param int    $user_id User ID.
       
   293 	 * @param string $uuid    The password's uuid.
       
   294 	 * @return true|WP_Error Whether the password was successfully found and deleted, a WP_Error otherwise.
       
   295 	 */
       
   296 	public static function delete_application_password( $user_id, $uuid ) {
       
   297 		$passwords = static::get_user_application_passwords( $user_id );
       
   298 
       
   299 		foreach ( $passwords as $key => $item ) {
       
   300 			if ( $item['uuid'] === $uuid ) {
       
   301 				unset( $passwords[ $key ] );
       
   302 				$saved = static::set_user_application_passwords( $user_id, $passwords );
       
   303 
       
   304 				if ( ! $saved ) {
       
   305 					return new WP_Error( 'db_error', __( 'Could not delete application password.' ) );
       
   306 				}
       
   307 
       
   308 				/**
       
   309 				 * Fires when an application password is deleted.
       
   310 				 *
       
   311 				 * @since 5.6.0
       
   312 				 *
       
   313 				 * @param int   $user_id The user ID.
       
   314 				 * @param array $item    The data about the application password.
       
   315 				 */
       
   316 				do_action( 'wp_delete_application_password', $user_id, $item );
       
   317 
       
   318 				return true;
       
   319 			}
       
   320 		}
       
   321 
       
   322 		return new WP_Error( 'application_password_not_found', __( 'Could not find an application password with that id.' ) );
       
   323 	}
       
   324 
       
   325 	/**
       
   326 	 * Deletes all application passwords for the given user.
       
   327 	 *
       
   328 	 * @since 5.6.0
       
   329 	 *
       
   330 	 * @param int $user_id User ID.
       
   331 	 * @return int|WP_Error The number of passwords that were deleted or a WP_Error on failure.
       
   332 	 */
       
   333 	public static function delete_all_application_passwords( $user_id ) {
       
   334 		$passwords = static::get_user_application_passwords( $user_id );
       
   335 
       
   336 		if ( $passwords ) {
       
   337 			$saved = static::set_user_application_passwords( $user_id, array() );
       
   338 
       
   339 			if ( ! $saved ) {
       
   340 				return new WP_Error( 'db_error', __( 'Could not delete application passwords.' ) );
       
   341 			}
       
   342 
       
   343 			foreach ( $passwords as $item ) {
       
   344 				/** This action is documented in wp-includes/class-wp-application-passwords.php */
       
   345 				do_action( 'wp_delete_application_password', $user_id, $item );
       
   346 			}
       
   347 
       
   348 			return count( $passwords );
       
   349 		}
       
   350 
       
   351 		return 0;
       
   352 	}
       
   353 
       
   354 	/**
       
   355 	 * Sets a users application passwords.
       
   356 	 *
       
   357 	 * @since 5.6.0
       
   358 	 *
       
   359 	 * @param int   $user_id   User ID.
       
   360 	 * @param array $passwords Application passwords.
       
   361 	 *
       
   362 	 * @return bool
       
   363 	 */
       
   364 	protected static function set_user_application_passwords( $user_id, $passwords ) {
       
   365 		return update_user_meta( $user_id, static::USERMETA_KEY_APPLICATION_PASSWORDS, $passwords );
       
   366 	}
       
   367 
       
   368 	/**
       
   369 	 * Sanitizes and then splits a password into smaller chunks.
       
   370 	 *
       
   371 	 * @since 5.6.0
       
   372 	 *
       
   373 	 * @param string $raw_password The raw application password.
       
   374 	 * @return string The chunked password.
       
   375 	 */
       
   376 	public static function chunk_password( $raw_password ) {
       
   377 		$raw_password = preg_replace( '/[^a-z\d]/i', '', $raw_password );
       
   378 
       
   379 		return trim( chunk_split( $raw_password, 4, ' ' ) );
       
   380 	}
       
   381 }