1<?php
  2/**
  3 * Session API: WP_Session_Tokens class
  4 *
  5 * @package WordPress
  6 * @subpackage Session
  7 * @since 4.7.0
  8 */
  9
 10/**
 11 * Abstract class for managing user session tokens.
 12 *
 13 * @since 4.0.0
 14 */
 15#[AllowDynamicProperties]
 16abstract class WP_Session_Tokens {
 17
 18	/**
 19	 * User ID.
 20	 *
 21	 * @since 4.0.0
 22	 * @var int User ID.
 23	 */
 24	protected $user_id;
 25
 26	/**
 27	 * Protected constructor. Use the `get_instance()` method to get the instance.
 28	 *
 29	 * @since 4.0.0
 30	 *
 31	 * @param int $user_id User whose session to manage.
 32	 */
 33	protected function __construct( $user_id ) {
 34		$this->user_id = $user_id;
 35	}
 36
 37	/**
 38	 * Retrieves a session manager instance for a user.
 39	 *
 40	 * This method contains a {@see 'session_token_manager'} filter, allowing a plugin to swap out
 41	 * the session manager for a subclass of `WP_Session_Tokens`.
 42	 *
 43	 * @since 4.0.0
 44	 *
 45	 * @param int $user_id User whose session to manage.
 46	 * @return WP_Session_Tokens The session object, which is by default an instance of
 47	 *                           the `WP_User_Meta_Session_Tokens` class.
 48	 */
 49	final public static function get_instance( $user_id ) {
 50		/**
 51		 * Filters the class name for the session token manager.
 52		 *
 53		 * @since 4.0.0
 54		 *
 55		 * @param string $session Name of class to use as the manager.
 56		 *                        Default 'WP_User_Meta_Session_Tokens'.
 57		 */
 58		$manager = apply_filters( 'session_token_manager', 'WP_User_Meta_Session_Tokens' );
 59		return new $manager( $user_id );
 60	}
 61
 62	/**
 63	 * Hashes the given session token for storage.
 64	 *
 65	 * @since 4.0.0
 66	 *
 67	 * @param string $token Session token to hash.
 68	 * @return string A hash of the session token (a verifier).
 69	 */
 70	private function hash_token( $token ) {
 71		return hash( 'sha256', $token );
 72	}
 73
 74	/**
 75	 * Retrieves a user's session for the given token.
 76	 *
 77	 * @since 4.0.0
 78	 *
 79	 * @param string $token Session token.
 80	 * @return array|null The session, or null if it does not exist.
 81	 */
 82	final public function get( $token ) {
 83		$verifier = $this->hash_token( $token );
 84		return $this->get_session( $verifier );
 85	}
 86
 87	/**
 88	 * Validates the given session token for authenticity and validity.
 89	 *
 90	 * Checks that the given token is present and hasn't expired.
 91	 *
 92	 * @since 4.0.0
 93	 *
 94	 * @param string $token Token to verify.
 95	 * @return bool Whether the token is valid for the user.
 96	 */
 97	final public function verify( $token ) {
 98		$verifier = $this->hash_token( $token );
 99		return (bool) $this->get_session( $verifier );
100	}
101
102	/**
103	 * Generates a session token and attaches session information to it.
104	 *
105	 * A session token is a long, random string. It is used in a cookie
106	 * to link that cookie to an expiration time and to ensure the cookie
107	 * becomes invalidated when the user logs out.
108	 *
109	 * This function generates a token and stores it with the associated
110	 * expiration time (and potentially other session information via the
111	 * {@see 'attach_session_information'} filter).
112	 *
113	 * @since 4.0.0
114	 *
115	 * @param int $expiration Session expiration timestamp.
116	 * @return string Session token.
117	 */
118	final public function create( $expiration ) {
119		/**
120		 * Filters the information attached to the newly created session.
121		 *
122		 * Can be used to attach further information to a session.
123		 *
124		 * @since 4.0.0
125		 *
126		 * @param array $session Array of extra data.
127		 * @param int   $user_id User ID.
128		 */
129		$session               = apply_filters( 'attach_session_information', array(), $this->user_id );
130		$session['expiration'] = $expiration;
131
132		// IP address.
133		if ( ! empty( $_SERVER['REMOTE_ADDR'] ) ) {
134			$session['ip'] = $_SERVER['REMOTE_ADDR'];
135		}
136
137		// User-agent.
138		if ( ! empty( $_SERVER['HTTP_USER_AGENT'] ) ) {
139			$session['ua'] = wp_unslash( $_SERVER['HTTP_USER_AGENT'] );
140		}
141
142		// Timestamp.
143		$session['login'] = time();
144
145		$token = wp_generate_password( 43, false, false );
146
147		$this->update( $token, $session );
148
149		return $token;
150	}
151
152	/**
153	 * Updates the data for the session with the given token.
154	 *
155	 * @since 4.0.0
156	 *
157	 * @param string $token Session token to update.
158	 * @param array  $session Session information.
159	 */
160	final public function update( $token, $session ) {
161		$verifier = $this->hash_token( $token );
162		$this->update_session( $verifier, $session );
163	}
164
165	/**
166	 * Destroys the session with the given token.
167	 *
168	 * @since 4.0.0
169	 *
170	 * @param string $token Session token to destroy.
171	 */
172	final public function destroy( $token ) {
173		$verifier = $this->hash_token( $token );
174		$this->update_session( $verifier, null );
175	}
176
177	/**
178	 * Destroys all sessions for this user except the one with the given token (presumably the one in use).
179	 *
180	 * @since 4.0.0
181	 *
182	 * @param string $token_to_keep Session token to keep.
183	 */
184	final public function destroy_others( $token_to_keep ) {
185		$verifier = $this->hash_token( $token_to_keep );
186		$session  = $this->get_session( $verifier );
187		if ( $session ) {
188			$this->destroy_other_sessions( $verifier );
189		} else {
190			$this->destroy_all_sessions();
191		}
192	}
193
194	/**
195	 * Determines whether a session is still valid, based on its expiration timestamp.
196	 *
197	 * @since 4.0.0
198	 *
199	 * @param array $session Session to check.
200	 * @return bool Whether session is valid.
201	 */
202	final protected function is_still_valid( $session ) {
203		return $session['expiration'] >= time();
204	}
205
206	/**
207	 * Destroys all sessions for a user.
208	 *
209	 * @since 4.0.0
210	 */
211	final public function destroy_all() {
212		$this->destroy_all_sessions();
213	}
214
215	/**
216	 * Destroys all sessions for all users.
217	 *
218	 * @since 4.0.0
219	 */
220	final public static function destroy_all_for_all_users() {
221		/** This filter is documented in wp-includes/class-wp-session-tokens.php */
222		$manager = apply_filters( 'session_token_manager', 'WP_User_Meta_Session_Tokens' );
223		call_user_func( array( $manager, 'drop_sessions' ) );
224	}
225
226	/**
227	 * Retrieves all sessions for a user.
228	 *
229	 * @since 4.0.0
230	 *
231	 * @return array Sessions for a user.
232	 */
233	final public function get_all() {
234		return array_values( $this->get_sessions() );
235	}
236
237	/**
238	 * Retrieves all sessions of the user.
239	 *
240	 * @since 4.0.0
241	 *
242	 * @return array Sessions of the user.
243	 */
244	abstract protected function get_sessions();
245
246	/**
247	 * Retrieves a session based on its verifier (token hash).
248	 *
249	 * @since 4.0.0
250	 *
251	 * @param string $verifier Verifier for the session to retrieve.
252	 * @return array|null The session, or null if it does not exist.
253	 */
254	abstract protected function get_session( $verifier );
255
256	/**
257	 * Updates a session based on its verifier (token hash).
258	 *
259	 * Omitting the second argument destroys the session.
260	 *
261	 * @since 4.0.0
262	 *
263	 * @param string $verifier Verifier for the session to update.
264	 * @param array  $session  Optional. Session. Omitting this argument destroys the session.
265	 */
266	abstract protected function update_session( $verifier, $session = null );
267
268	/**
269	 * Destroys all sessions for this user, except the single session with the given verifier.
270	 *
271	 * @since 4.0.0
272	 *
273	 * @param string $verifier Verifier of the session to keep.
274	 */
275	abstract protected function destroy_other_sessions( $verifier );
276
277	/**
278	 * Destroys all sessions for the user.
279	 *
280	 * @since 4.0.0
281	 */
282	abstract protected function destroy_all_sessions();
283
284	/**
285	 * Destroys all sessions for all users.
286	 *
287	 * @since 4.0.0
288	 */
289	public static function drop_sessions() {}
290}
291