Improve documentation on password reset by dividing it into steps

Migration.md

@@ -10,21 +10,11 @@
 
 ## General
 
-Update your version of this library via Composer [[?]](https://github.com/delight-im/Knowledge/blob/master/Composer%20(PHP).md):
-
-```
-$ composer update delight-im/auth
-```
-
-If you want to perform a major version upgrade (e.g. from version `1.x.x` to version `2.x.x`), the version constraints defined in your `composer.json` [[?]](https://github.com/delight-im/Knowledge/blob/master/Composer%20(PHP).md) may not allow this. In that case, just add the dependency again to overwrite it with the latest version (or optionally with a specified version):
-
-```
-$ composer require delight-im/auth
-```
+Update your version of this library using Composer and its `composer update` or `composer require` commands [[?]](https://github.com/delight-im/Knowledge/blob/master/Composer%20(PHP).md#how-do-i-update-libraries-or-modules-within-my-application).
 
 ## From `v6.x.x` to `v7.x.x`
 
- * The method `logOutButKeepSession` from class `Auth` is now simply called `logOut`. Therefore, the former method `logout` is now called `logOutAndDestroySession`. With both methods, mind the capitalization of the letter “O”.
+ * The method `logOutButKeepSession` from class `Auth` is now simply called `logOut`. Therefore, the former method `logout` is now called `logOutAndDestroySession`.
 
  * The second argument of the `Auth` constructor, which was named `$useHttps`, has been removed. If you previously had it set to `true`, make sure to set the value of the `session.cookie_secure` directive to `1` now. You may do so either directly in your [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`), via the `\ini_set` method or via the `\session_set_cookie_params` method. Otherwise, make sure that directive is set to `0`.
 

README.md

@@ -79,6 +79,7 @@ Migrating from an earlier version of this project? See our [upgrade guide](Migra
    * [Assigning roles to users](#assigning-roles-to-users)
    * [Taking roles away from users](#taking-roles-away-from-users)
    * [Checking roles](#checking-roles-1)
+   * [Impersonating users (logging in as user)](#impersonating-users-logging-in-as-user)
  * [Cookies](#cookies)
    * [Renaming the library’s cookies](#renaming-the-librarys-cookies)
    * [Defining the domain scope for cookies](#defining-the-domain-scope-for-cookies)
@@ -108,10 +109,12 @@ $auth = new \Delight\Auth\Auth($db);
 
 If you have an open `PDO` connection already, just re-use it.
 
-If your web server is behind a proxy server and `$_SERVER['REMOTE_ADDR']` only contains the proxy’s IP address, you must pass the user’s real IP address to the constructor in the second argument, which is named `$ipAddress`. The default is `null`.
+If your web server is behind a proxy server and `$_SERVER['REMOTE_ADDR']` only contains the proxy’s IP address, you must pass the user’s real IP address to the constructor in the second argument, which is named `$ipAddress`. The default is the usual remote IP address received by PHP.
 
 Should your database tables for this library need a common prefix, e.g. `my_users` instead of `users` (and likewise for the other tables), pass the prefix (e.g. `my_`) as the third parameter to the constructor, which is named `$dbTablePrefix`. This is optional and the prefix is empty by default.
 
+During development, you may want to disable the request limiting or throttling performed by this library. To do so, pass `false` to the constructor as the fourth argument, which is named `$throttling`. The feature is enabled by default.
+
 ### Registration (sign up)
 
 ```php
@@ -225,6 +228,8 @@ Omit the third parameter or set it to `null` to disable the feature. Otherwise,
 
 ### Password reset (“forgot password”)
 
+#### Step 1 of 3: Initiating the request
+
 ```php
 try {
     $auth->forgotPassword($_POST['email'], function ($selector, $token) {
@@ -253,12 +258,39 @@ You should build an URL with the selector and token and send it to the user, e.g
 $url = 'https://www.example.com/reset_password?selector=' . \urlencode($selector) . '&token=' . \urlencode($token);
 ```
 
+#### Step 2 of 3: Verifying an attempt
+
 As the next step, users will click on the link that they received. Extract the selector and token from the URL.
 
 If the selector/token pair is valid, let the user choose a new password:
 
 ```php
-if ($auth->canResetPassword($_POST['selector'], $_POST['token'])) {
+try {
+    $auth->canResetPasswordOrThrow($_GET['selector'], $_GET['token']);
+
+    // put the selector into a `hidden` field (or keep it in the URL)
+    // put the token into a `hidden` field (or keep it in the URL)
+
+    // ask the user for their new password
+}
+catch (\Delight\Auth\InvalidSelectorTokenPairException $e) {
+    // invalid token
+}
+catch (\Delight\Auth\TokenExpiredException $e) {
+    // token expired
+}
+catch (\Delight\Auth\ResetDisabledException $e) {
+    // password reset is disabled
+}
+catch (\Delight\Auth\TooManyRequestsException $e) {
+    // too many requests
+}
+```
+
+Alternatively, if you don’t need any error messages but only want to check the validity, you can use the slightly simpler version:
+
+```php
+if ($auth->canResetPassword($_GET['selector'], $_GET['token'])) {
     // put the selector into a `hidden` field (or keep it in the URL)
     // put the token into a `hidden` field (or keep it in the URL)
 
@@ -266,6 +298,8 @@ if ($auth->canResetPassword($_POST['selector'], $_POST['token'])) {
 }
 ```
 
+#### Step 3 of 3: Updating the password
+
 Now when you have the new password for the user (and still have the other two pieces of information), you can reset the password:
 
 ```php
@@ -580,6 +614,12 @@ if ($auth->hasAllRoles(\Delight\Auth\Role::DEVELOPER, \Delight\Auth\Role::MANAGE
 
 While the method `hasRole` takes exactly one role as its argument, the two methods `hasAnyRole` and `hasAllRoles` can take any number of roles that you would like to check for.
 
+Alternatively, you can get a list of all the roles that have been assigned to the user:
+
+```php
+$auth->getRoles();
+```
+
 #### Available roles
 
 ```php
@@ -607,7 +647,15 @@ While the method `hasRole` takes exactly one role as its argument, the two metho
 \Delight\Auth\Role::TRANSLATOR;
 ```
 
-You can use any of these roles and ignore those that you don’t need.
+You can use any of these roles and ignore those that you don’t need. The list above can also be retrieved programmatically, in one of three formats:
+
+```php
+\Delight\Auth\Role::getMap();
+// or
+\Delight\Auth\Role::getNames();
+// or
+\Delight\Auth\Role::getValues();
+```
 
 #### Permissions (or access rights, privileges or capabilities)
 
@@ -898,6 +946,53 @@ catch (\Delight\Auth\UnknownIdException $e) {
 }
 ```
 
+Alternatively, you can get a list of all the roles that have been assigned to the user:
+
+```php
+$auth->admin()->getRolesForUserById($userId);
+```
+
+#### Impersonating users (logging in as user)
+
+```php
+try {
+    $auth->admin()->logInAsUserById($_POST['id']);
+}
+catch (\Delight\Auth\UnknownIdException $e) {
+    // unknown ID
+}
+catch (\Delight\Auth\EmailNotVerifiedException $e) {
+    // email address not verified
+}
+
+// or
+
+try {
+    $auth->admin()->logInAsUserByEmail($_POST['email']);
+}
+catch (\Delight\Auth\InvalidEmailException $e) {
+    // unknown email address
+}
+catch (\Delight\Auth\EmailNotVerifiedException $e) {
+    // email address not verified
+}
+
+// or
+
+try {
+    $auth->admin()->logInAsUserByUsername($_POST['username']);
+}
+catch (\Delight\Auth\UnknownUsernameException $e) {
+    // unknown username
+}
+catch (\Delight\Auth\AmbiguousUsernameException $e) {
+    // ambiguous username
+}
+catch (\Delight\Auth\EmailNotVerifiedException $e) {
+    // email address not verified
+}
+```
+
 ### Cookies
 
 This library uses two cookies to keep state on the client: The first, whose name you can retrieve using

src/Administration.php

@@ -286,6 +286,90 @@ final class Administration extends UserManager {
 		return ($rolesBitmask & $role) === $role;
 	}
 
+	/**
+	 * Returns the roles of the user with the given ID, mapping the numerical values to their descriptive names
+	 *
+	 * @param int $userId the ID of the user to return the roles for
+	 * @return array
+	 * @throws UnknownIdException if no user with the specified ID has been found
+	 *
+	 * @see Role
+	 */
+	public function getRolesForUserById($userId) {
+		$userId = (int) $userId;
+
+		$rolesBitmask = $this->db->selectValue(
+			'SELECT roles_mask FROM ' . $this->dbTablePrefix . 'users WHERE id = ?',
+			[ $userId ]
+		);
+
+		if ($rolesBitmask === null) {
+			throw new UnknownIdException();
+		}
+
+		return \array_filter(
+			Role::getMap(),
+			function ($each) use ($rolesBitmask) {
+				return ($rolesBitmask & $each) === $each;
+			},
+			\ARRAY_FILTER_USE_KEY
+		);
+	}
+
+	/**
+	 * Signs in as the user with the specified ID
+	 *
+	 * @param int $id the ID of the user to sign in as
+	 * @throws UnknownIdException if no user with the specified ID has been found
+	 * @throws EmailNotVerifiedException if the user has not verified their email address via a confirmation method yet
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	public function logInAsUserById($id) {
+		$numberOfMatchedUsers = $this->logInAsUserByColumnValue('id', (int) $id);
+
+		if ($numberOfMatchedUsers === 0) {
+			throw new UnknownIdException();
+		}
+	}
+
+	/**
+	 * Signs in as the user with the specified email address
+	 *
+	 * @param string $email the email address of the user to sign in as
+	 * @throws InvalidEmailException if no user with the specified email address has been found
+	 * @throws EmailNotVerifiedException if the user has not verified their email address via a confirmation method yet
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	public function logInAsUserByEmail($email) {
+		$email = self::validateEmailAddress($email);
+
+		$numberOfMatchedUsers = $this->logInAsUserByColumnValue('email', $email);
+
+		if ($numberOfMatchedUsers === 0) {
+			throw new InvalidEmailException();
+		}
+	}
+
+	/**
+	 * Signs in as the user with the specified display name
+	 *
+	 * @param string $username the display name of the user to sign in as
+	 * @throws UnknownUsernameException if no user with the specified username has been found
+	 * @throws AmbiguousUsernameException if multiple users with the specified username have been found
+	 * @throws EmailNotVerifiedException if the user has not verified their email address via a confirmation method yet
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	public function logInAsUserByUsername($username) {
+		$numberOfMatchedUsers = $this->logInAsUserByColumnValue('username', \trim($username));
+
+		if ($numberOfMatchedUsers === 0) {
+			throw new UnknownUsernameException();
+		}
+		elseif ($numberOfMatchedUsers > 1) {
+			throw new AmbiguousUsernameException();
+		}
+	}
+
 	/**
 	 * Deletes all existing users where the column with the specified name has the given value
 	 *
@@ -404,4 +488,42 @@ final class Administration extends UserManager {
 		);
 	}
 
+	/**
+	 * Signs in as the user for which the column with the specified name has the given value
+	 *
+	 * You must never pass untrusted input to the parameter that takes the column name
+	 *
+	 * @param string $columnName the name of the column to filter by
+	 * @param mixed $columnValue the value to look for in the selected column
+	 * @return int the number of matched users (where only a value of one means that the login may have been successful)
+	 * @throws EmailNotVerifiedException if the user has not verified their email address via a confirmation method yet
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	private function logInAsUserByColumnValue($columnName, $columnValue) {
+		try {
+			$users = $this->db->select(
+				'SELECT verified, id, email, username, status, roles_mask FROM ' . $this->dbTablePrefix . 'users WHERE ' . $columnName . ' = ? LIMIT 2 OFFSET 0',
+				[ $columnValue ]
+			);
+		}
+		catch (Error $e) {
+			throw new DatabaseError();
+		}
+
+		$numberOfMatchingUsers = \count($users);
+
+		if ($numberOfMatchingUsers === 1) {
+			$user = $users[0];
+
+			if ((int) $user['verified'] === 1) {
+				$this->onLoginSuccessful($user['id'], $user['email'], $user['username'], $user['status'], $user['roles_mask'], false);
+			}
+			else {
+				throw new EmailNotVerifiedException();
+			}
+		}
+
+		return $numberOfMatchingUsers;
+	}
+
 }

src/Auth.php

@@ -21,18 +21,13 @@ require_once __DIR__ . '/Exceptions.php';
 /** Component that provides all features and utilities for secure authentication of individual users */
 final class Auth extends UserManager {
 
-	const SESSION_FIELD_LOGGED_IN = 'auth_logged_in';
-	const SESSION_FIELD_USER_ID = 'auth_user_id';
-	const SESSION_FIELD_EMAIL = 'auth_email';
-	const SESSION_FIELD_USERNAME = 'auth_username';
-	const SESSION_FIELD_STATUS = 'auth_status';
-	const SESSION_FIELD_ROLES = 'auth_roles';
-	const SESSION_FIELD_REMEMBERED = 'auth_remembered';
 	const COOKIE_PREFIXES = [ Cookie::PREFIX_SECURE, Cookie::PREFIX_HOST ];
 	const COOKIE_CONTENT_SEPARATOR = '~';
 
 	/** @var string the user's current IP address */
 	private $ipAddress;
+	/** @var bool whether throttling should be enabled (e.g. in production) or disabled (e.g. during development) */
+	private $throttling;
 	/** @var string the name of the cookie used for the 'remember me' feature */
 	private $rememberCookieName;
 
@@ -40,11 +35,13 @@ final class Auth extends UserManager {
 	 * @param PdoDatabase|PdoDsn|\PDO $databaseConnection the database connection to operate on
 	 * @param string $ipAddress the IP address that should be used instead of the default setting (if any), e.g. when behind a proxy
 	 * @param string|null $dbTablePrefix (optional) the prefix for the names of all database tables used by this component
+	 * @param bool|null $throttling (optional) whether throttling should be enabled (e.g. in production) or disabled (e.g. during development)
 	 */
-	public function __construct($databaseConnection, $ipAddress = null, $dbTablePrefix = null) {
+	public function __construct($databaseConnection, $ipAddress = null, $dbTablePrefix = null, $throttling = null) {
 		parent::__construct($databaseConnection, $dbTablePrefix);
 
 		$this->ipAddress = !empty($ipAddress) ? $ipAddress : (isset($_SERVER['REMOTE_ADDR']) ? $_SERVER['REMOTE_ADDR'] : null);
+		$this->throttling = isset($throttling) ? (bool) $throttling : true;
 		$this->rememberCookieName = self::createRememberCookieName();
 
 		$this->initSession();
@@ -458,18 +455,8 @@ final class Auth extends UserManager {
 		}
 	}
 
-	/**
-	 * Called when the user has successfully logged in (via standard login or "remember me")
-	 *
-	 * @param int $userId the ID of the user who has just logged in
-	 * @param string $email the email address of the user who has just logged in
-	 * @param string $username the username (if any)
-	 * @param int $status the status as one of the constants from the {@see Status} class
-	 * @param int $roles the bitmask containing the roles of the user
-	 * @param bool $remembered whether the user was remembered ("remember me") or logged in actively
-	 * @throws AuthError if an internal problem occurred (do *not* catch)
-	 */
-	private function onLoginSuccessful($userId, $email, $username, $status, $roles, $remembered) {
+	protected function onLoginSuccessful($userId, $email, $username, $status, $roles, $remembered) {
+		// update the timestamp of the user's last login
 		try {
 			$this->db->update(
 				$this->dbTablePrefix . 'users',
@@ -481,17 +468,7 @@ final class Auth extends UserManager {
 			throw new DatabaseError();
 		}
 
-		// re-generate the session ID to prevent session fixation attacks (requests a cookie to be written on the client)
-		Session::regenerate(true);
-
-		// save the user data in the session
-		$this->setLoggedIn(true);
-		$this->setUserId($userId);
-		$this->setEmail($email);
-		$this->setUsername($username);
-		$this->setStatus($status);
-		$this->setRoles($roles);
-		$this->setRemembered($remembered);
+		parent::onLoginSuccessful($userId, $email, $username, $status, $roles, $remembered);
 	}
 
 	/**
@@ -591,10 +568,11 @@ final class Auth extends UserManager {
 						// if the user has just confirmed an email address for their own account
 						if ($this->getUserId() === $confirmationData['user_id']) {
 							// immediately update the email address in the current session as well
-							$this->setEmail($confirmationData['email']);
+							$_SESSION[self::SESSION_FIELD_EMAIL] = $confirmationData['email'];
 						}
 					}
 
+					// consume the token just being used for confirmation
 					try {
 						$this->db->delete(
 							$this->dbTablePrefix . 'users_confirmations',
@@ -779,8 +757,8 @@ final class Auth extends UserManager {
 				throw new EmailNotVerifiedException();
 			}
 
+			$this->throttle([ 'requestEmailChange', 'userId', $this->getUserId() ], 1, (60 * 60 * 24));
 			$this->throttle([ 'requestEmailChange', $this->getIpAddress() ], 1, (60 * 60 * 24), 3);
-			$this->throttle([ 'requestEmailChange', 'user', $this->getUserId() ], 1, (60 * 60 * 24), 3);
 
 			$this->createConfirmationRequest($this->getUserId(), $newEmail, $callback);
 		}
@@ -854,7 +832,7 @@ final class Auth extends UserManager {
 	private function resendConfirmationForColumnValue($columnName, $columnValue, callable $callback) {
 		try {
 			$latestAttempt = $this->db->selectRow(
-				'SELECT user_id, email, expires FROM ' . $this->dbTablePrefix . 'users_confirmations WHERE ' . $columnName . ' = ? ORDER BY id DESC LIMIT 1 OFFSET 0',
+				'SELECT user_id, email FROM ' . $this->dbTablePrefix . 'users_confirmations WHERE ' . $columnName . ' = ? ORDER BY id DESC LIMIT 1 OFFSET 0',
 				[ $columnValue ]
 			);
 		}
@@ -866,14 +844,8 @@ final class Auth extends UserManager {
 			throw new ConfirmationRequestNotFound();
 		}
 
-		$retryAt = $latestAttempt['expires'] - 0.75 * self::CONFIRMATION_REQUESTS_TTL_IN_SECONDS;
-
-		if ($retryAt > \time()) {
-			throw new TooManyRequestsException('', $retryAt - \time());
-		}
-
+		$this->throttle([ 'resendConfirmation', 'userId', $latestAttempt['user_id'] ], 1, (60 * 60 * 6));
 		$this->throttle([ 'resendConfirmation', $this->getIpAddress() ], 4, (60 * 60 * 24 * 7), 2);
-		$this->throttle([ 'resendConfirmation', 'user', $latestAttempt['user_id'] ], 4, (60 * 60 * 24 * 7), 2);
 
 		$this->createConfirmationRequest(
 			$latestAttempt['user_id'],
@@ -1232,6 +1204,40 @@ final class Auth extends UserManager {
 		}
 	}
 
+	/**
+	 * Check if the supplied selector/token pair can be used to reset a password
+	 *
+	 * The password can be reset using the supplied information if this method does *not* throw any exception
+	 *
+	 * The selector/token pair must have been generated previously by calling `Auth#forgotPassword(...)`
+	 *
+	 * @param string $selector the selector from the selector/token pair
+	 * @param string $token the token from the selector/token pair
+	 * @throws InvalidSelectorTokenPairException if either the selector or the token was not correct
+	 * @throws TokenExpiredException if the token has already expired
+	 * @throws ResetDisabledException if the user has explicitly disabled password resets for their account
+	 * @throws TooManyRequestsException if the number of allowed attempts/requests has been exceeded
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	public function canResetPasswordOrThrow($selector, $token) {
+		try {
+			// pass an invalid password intentionally to force an expected error
+			$this->resetPassword($selector, $token, null);
+
+			// we should already be in one of the `catch` blocks now so this is not expected
+			throw new AuthError();
+		}
+		// if the password is the only thing that's invalid
+		catch (InvalidPasswordException $ignored) {
+			// the password can be reset
+		}
+		// if some other things failed (as well)
+		catch (AuthException $e) {
+			// re-throw the exception
+			throw $e;
+		}
+	}
+
 	/**
 	 * Check if the supplied selector/token pair can be used to reset a password
 	 *
@@ -1244,18 +1250,10 @@ final class Auth extends UserManager {
 	 */
 	public function canResetPassword($selector, $token) {
 		try {
-			// pass an invalid password intentionally to force an expected error
-			$this->resetPassword($selector, $token, null);
+			$this->canResetPasswordOrThrow($selector, $token);
 
-			// we should already be in the `catch` block now so this is not expected
-			throw new AuthError();
-		}
-		// if the password is the only thing that's invalid
-		catch (InvalidPasswordException $e) {
-			// the password can be reset
 			return true;
 		}
-		// if some other things failed (as well)
 		catch (AuthException $e) {
 			return false;
 		}
@@ -1318,15 +1316,6 @@ final class Auth extends UserManager {
 		}
 	}
 
-	/**
-	 * Sets whether the user is currently logged in and updates the session
-	 *
-	 * @param bool $loggedIn whether the user is logged in or not
-	 */
-	private function setLoggedIn($loggedIn) {
-		$_SESSION[self::SESSION_FIELD_LOGGED_IN] = $loggedIn;
-	}
-
 	/**
 	 * Returns whether the user is currently logged in by reading from the session
 	 *
@@ -1345,15 +1334,6 @@ final class Auth extends UserManager {
 		return $this->isLoggedIn();
 	}
 
-	/**
-	 * Sets the currently signed-in user's ID and updates the session
-	 *
-	 * @param int $userId the user's ID
-	 */
-	private function setUserId($userId) {
-		$_SESSION[self::SESSION_FIELD_USER_ID] = (int) $userId;
-	}
-
 	/**
 	 * Returns the currently signed-in user's ID by reading from the session
 	 *
@@ -1377,15 +1357,6 @@ final class Auth extends UserManager {
 		return $this->getUserId();
 	}
 
-	/**
-	 * Sets the currently signed-in user's email address and updates the session
-	 *
-	 * @param string $email the email address
-	 */
-	private function setEmail($email) {
-		$_SESSION[self::SESSION_FIELD_EMAIL] = $email;
-	}
-
 	/**
 	 * Returns the currently signed-in user's email address by reading from the session
 	 *
@@ -1400,15 +1371,6 @@ final class Auth extends UserManager {
 		}
 	}
 
-	/**
-	 * Sets the currently signed-in user's display name and updates the session
-	 *
-	 * @param string $username the display name
-	 */
-	private function setUsername($username) {
-		$_SESSION[self::SESSION_FIELD_USERNAME] = $username;
-	}
-
 	/**
 	 * Returns the currently signed-in user's display name by reading from the session
 	 *
@@ -1423,24 +1385,6 @@ final class Auth extends UserManager {
 		}
 	}
 
-	/**
-	 * Sets the currently signed-in user's status and updates the session
-	 *
-	 * @param int $status the status as one of the constants from the {@see Status} class
-	 */
-	private function setStatus($status) {
-		$_SESSION[self::SESSION_FIELD_STATUS] = (int) $status;
-	}
-
-	/**
-	 * Sets the currently signed-in user's roles and updates the session
-	 *
-	 * @param int $roles the bitmask containing the roles
-	 */
-	private function setRoles($roles) {
-		$_SESSION[self::SESSION_FIELD_ROLES] = (int) $roles;
-	}
-
 	/**
 	 * Returns the currently signed-in user's status by reading from the session
 	 *
@@ -1583,12 +1527,16 @@ final class Auth extends UserManager {
 	}
 
 	/**
-	 * Sets whether the currently signed-in user has been remembered by a long-lived cookie
+	 * Returns an array of the user's roles, mapping the numerical values to their descriptive names
 	 *
-	 * @param bool $remembered whether the user was remembered
+	 * @return array
 	 */
-	private function setRemembered($remembered) {
-		$_SESSION[self::SESSION_FIELD_REMEMBERED] = $remembered;
+	public function getRoles() {
+		return \array_filter(
+			Role::getMap(),
+			[ $this, 'hasRole' ],
+			\ARRAY_FILTER_USE_KEY
+		);
 	}
 
 	/**
@@ -1628,6 +1576,10 @@ final class Auth extends UserManager {
 	 * @throws AuthError if an internal problem occurred (do *not* catch)
 	 */
 	public function throttle(array $criteria, $supply, $interval, $burstiness = null, $simulated = null, $cost = null) {
+		if (!$this->throttling) {
+			return $supply;
+		}
+
 		// generate a unique key for the bucket (consisting of 44 or fewer ASCII characters)
 		$key = Base64::encodeUrlSafeWithoutPadding(
 			\hash(

src/Role.php

@@ -32,14 +32,47 @@ final class Role {
 	const SUPER_EDITOR = 524288;
 	const SUPER_MODERATOR = 1048576;
 	const TRANSLATOR = 2097152;
-	// const XXX = 4194304;
-	// const XXX = 8388608;
-	// const XXX = 16777216;
-	// const XXX = 33554432;
-	// const XXX = 67108864;
-	// const XXX = 134217728;
-	// const XXX = 268435456;
-	// const XXX = 536870912;
+	// const XYZ = 4194304;
+	// const XYZ = 8388608;
+	// const XYZ = 16777216;
+	// const XYZ = 33554432;
+	// const XYZ = 67108864;
+	// const XYZ = 134217728;
+	// const XYZ = 268435456;
+	// const XYZ = 536870912;
+
+	/**
+	 * Returns an array mapping the numerical role values to their descriptive names
+	 *
+	 * @return array
+	 */
+	public static function getMap() {
+		$reflectionClass = new \ReflectionClass(static::class);
+
+		return \array_flip($reflectionClass->getConstants());
+	}
+
+	/**
+	 * Returns the descriptive role names
+	 *
+	 * @return string[]
+	 */
+	public static function getNames() {
+		$reflectionClass = new \ReflectionClass(static::class);
+
+		return \array_keys($reflectionClass->getConstants());
+	}
+
+	/**
+	 * Returns the numerical role values
+	 *
+	 * @return int[]
+	 */
+	public static function getValues() {
+		$reflectionClass = new \ReflectionClass(static::class);
+
+		return \array_values($reflectionClass->getConstants());
+	}
 
 	private function __construct() {}
 

src/UserManager.php

@@ -9,6 +9,7 @@
 namespace Delight\Auth;
 
 use Delight\Base64\Base64;
+use Delight\Cookie\Session;
 use Delight\Db\PdoDatabase;
 use Delight\Db\PdoDsn;
 use Delight\Db\Throwable\Error;
@@ -23,7 +24,20 @@ require_once __DIR__ . '/Exceptions.php';
  */
 abstract class UserManager {
 
-	const CONFIRMATION_REQUESTS_TTL_IN_SECONDS = 60 * 60 * 24;
+	/** @var string session field for whether the client is currently signed in */
+	const SESSION_FIELD_LOGGED_IN = 'auth_logged_in';
+	/** @var string session field for the ID of the user who is currently signed in (if any) */
+	const SESSION_FIELD_USER_ID = 'auth_user_id';
+	/** @var string session field for the email address of the user who is currently signed in (if any) */
+	const SESSION_FIELD_EMAIL = 'auth_email';
+	/** @var string session field for the display name (if any) of the user who is currently signed in (if any) */
+	const SESSION_FIELD_USERNAME = 'auth_username';
+	/** @var string session field for the status of the user who is currently signed in (if any) as one of the constants from the {@see Status} class */
+	const SESSION_FIELD_STATUS = 'auth_status';
+	/** @var string session field for the roles of the user who is currently signed in (if any) as a bitmask using constants from the {@see Role} class */
+	const SESSION_FIELD_ROLES = 'auth_roles';
+	/** @var string session field for whether the user who is currently signed in (if any) has been remembered (instead of them having authenticated actively) */
+	const SESSION_FIELD_REMEMBERED = 'auth_remembered';
 
 	/** @var PdoDatabase the database connection to operate on */
 	protected $db;
@@ -166,6 +180,33 @@ abstract class UserManager {
 		return $newUserId;
 	}
 
+	/**
+	 * Called when a user has successfully logged in
+	 *
+	 * This may happen via the standard login, via the "remember me" feature, or due to impersonation by administrators
+	 *
+	 * @param int $userId the ID of the user
+	 * @param string $email the email address of the user
+	 * @param string $username the display name (if any) of the user
+	 * @param int $status the status of the user as one of the constants from the {@see Status} class
+	 * @param int $roles the roles of the user as a bitmask using constants from the {@see Role} class
+	 * @param bool $remembered whether the user has been remembered (instead of them having authenticated actively)
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	protected function onLoginSuccessful($userId, $email, $username, $status, $roles, $remembered) {
+		// re-generate the session ID to prevent session fixation attacks (requests a cookie to be written on the client)
+		Session::regenerate(true);
+
+		// save the user data in the session variables maintained by this library
+		$_SESSION[self::SESSION_FIELD_LOGGED_IN] = true;
+		$_SESSION[self::SESSION_FIELD_USER_ID] = (int) $userId;
+		$_SESSION[self::SESSION_FIELD_EMAIL] = $email;
+		$_SESSION[self::SESSION_FIELD_USERNAME] = $username;
+		$_SESSION[self::SESSION_FIELD_STATUS] = (int) $status;
+		$_SESSION[self::SESSION_FIELD_ROLES] = (int) $roles;
+		$_SESSION[self::SESSION_FIELD_REMEMBERED] = $remembered;
+	}
+
 	/**
 	 * Returns the requested user data for the account with the specified username (if any)
 	 *
@@ -266,9 +307,7 @@ abstract class UserManager {
 		$selector = self::createRandomString(16);
 		$token = self::createRandomString(16);
 		$tokenHashed = \password_hash($token, \PASSWORD_DEFAULT);
-
-		// the request shall be valid for one day
-		$expires = \time() + self::CONFIRMATION_REQUESTS_TTL_IN_SECONDS;
+		$expires = \time() + 60 * 60 * 24;
 
 		try {
 			$this->db->insert(

tests/index.php

@@ -84,7 +84,7 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 					return 'wrong password';
 				}
 				catch (\Delight\Auth\EmailNotVerifiedException $e) {
-					return 'email not verified';
+					return 'email address not verified';
 				}
 				catch (\Delight\Auth\TooManyRequestsException $e) {
 					return 'too many requests';
@@ -242,10 +242,10 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 					return 'invalid email address';
 				}
 				catch (\Delight\Auth\EmailNotVerifiedException $e) {
-					return 'email not verified';
+					return 'email address not verified';
 				}
 				catch (\Delight\Auth\ResetDisabledException $e) {
-					return 'password reset disabled';
+					return 'password reset is disabled';
 				}
 				catch (\Delight\Auth\TooManyRequestsException $e) {
 					return 'too many requests';
@@ -264,7 +264,7 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 					return 'token expired';
 				}
 				catch (\Delight\Auth\ResetDisabledException $e) {
-					return 'password reset disabled';
+					return 'password reset is disabled';
 				}
 				catch (\Delight\Auth\InvalidPasswordException $e) {
 					return 'invalid password';
@@ -273,6 +273,25 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 					return 'too many requests';
 				}
 			}
+			else if ($_POST['action'] === 'canResetPassword') {
+				try {
+					$auth->canResetPasswordOrThrow($_POST['selector'], $_POST['token']);
+
+					return 'yes';
+				}
+				catch (\Delight\Auth\InvalidSelectorTokenPairException $e) {
+					return 'invalid token';
+				}
+				catch (\Delight\Auth\TokenExpiredException $e) {
+					return 'token expired';
+				}
+				catch (\Delight\Auth\ResetDisabledException $e) {
+					return 'password reset is disabled';
+				}
+				catch (\Delight\Auth\TooManyRequestsException $e) {
+					return 'too many requests';
+				}
+			}
 			else if ($_POST['action'] === 'reconfirmPassword') {
 				try {
 					return $auth->reconfirmPassword($_POST['password']) ? 'correct' : 'wrong';
@@ -422,7 +441,7 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 					}
 				}
 				else {
-					return 'either ID, email or username required';
+					return 'either ID, email address or username required';
 				}
 
 				return 'ok';
@@ -457,7 +476,7 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 						}
 					}
 					else {
-						return 'either ID, email or username required';
+						return 'either ID, email address or username required';
 					}
 				}
 				else {
@@ -496,7 +515,7 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 						}
 					}
 					else {
-						return 'either ID, email or username required';
+						return 'either ID, email address or username required';
 					}
 				}
 				else {
@@ -523,6 +542,76 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 					return 'ID required';
 				}
 			}
+			else if ($_POST['action'] === 'admin.getRoles') {
+				if (isset($_POST['id'])) {
+					try {
+						return $auth->admin()->getRolesForUserById($_POST['id']);
+					}
+					catch (\Delight\Auth\UnknownIdException $e) {
+						return 'unknown ID';
+					}
+				}
+				else {
+					return 'ID required';
+				}
+			}
+			else if ($_POST['action'] === 'admin.logInAsUserById') {
+				if (isset($_POST['id'])) {
+					try {
+						$auth->admin()->logInAsUserById($_POST['id']);
+
+						return 'ok';
+					}
+					catch (\Delight\Auth\UnknownIdException $e) {
+						return 'unknown ID';
+					}
+					catch (\Delight\Auth\EmailNotVerifiedException $e) {
+						return 'email address not verified';
+					}
+				}
+				else {
+					return 'ID required';
+				}
+			}
+			else if ($_POST['action'] === 'admin.logInAsUserByEmail') {
+				if (isset($_POST['email'])) {
+					try {
+						$auth->admin()->logInAsUserByEmail($_POST['email']);
+
+						return 'ok';
+					}
+					catch (\Delight\Auth\InvalidEmailException $e) {
+						return 'unknown email address';
+					}
+					catch (\Delight\Auth\EmailNotVerifiedException $e) {
+						return 'email address not verified';
+					}
+				}
+				else {
+					return 'Email address required';
+				}
+			}
+			else if ($_POST['action'] === 'admin.logInAsUserByUsername') {
+				if (isset($_POST['username'])) {
+					try {
+						$auth->admin()->logInAsUserByUsername($_POST['username']);
+
+						return 'ok';
+					}
+					catch (\Delight\Auth\UnknownUsernameException $e) {
+						return 'unknown username';
+					}
+					catch (\Delight\Auth\AmbiguousUsernameException $e) {
+						return 'ambiguous username';
+					}
+					catch (\Delight\Auth\EmailNotVerifiedException $e) {
+						return 'email address not verified';
+					}
+				}
+				else {
+					return 'Username required';
+				}
+			}
 			else {
 				throw new Exception('Unexpected action: ' . $_POST['action']);
 			}
@@ -574,6 +663,9 @@ function showDebugData(\Delight\Auth\Auth $auth, $result) {
 	echo 'Roles (developer *and* manager)' . "\t\t";
 	\var_dump($auth->hasAllRoles(\Delight\Auth\Role::DEVELOPER, \Delight\Auth\Role::MANAGER));
 
+	echo 'Roles' . "\t\t\t\t\t";
+	echo \json_encode($auth->getRoles()) . "\n";
+
 	echo "\n";
 
 	echo '$auth->isRemembered()' . "\t\t\t";
@@ -687,7 +779,7 @@ function showGuestUserForm() {
 
 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="login" />';
-	echo '<input type="text" name="email" placeholder="Email" /> ';
+	echo '<input type="text" name="email" placeholder="Email address" /> ';
 	echo '<input type="text" name="password" placeholder="Password" /> ';
 	echo '<select name="remember" size="1">';
 	echo '<option value="0">Remember (keep logged in)? — No</option>';
@@ -709,7 +801,7 @@ function showGuestUserForm() {
 
 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="register" />';
-	echo '<input type="text" name="email" placeholder="Email" /> ';
+	echo '<input type="text" name="email" placeholder="Email address" /> ';
 	echo '<input type="text" name="password" placeholder="Password" /> ';
 	echo '<input type="text" name="username" placeholder="Username (optional)" /> ';
 	echo '<select name="require_verification" size="1">';
@@ -727,7 +819,7 @@ function showGuestUserForm() {
 
 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="forgotPassword" />';
-	echo '<input type="text" name="email" placeholder="Email" /> ';
+	echo '<input type="text" name="email" placeholder="Email address" /> ';
 	echo '<button type="submit">Forgot password</button>';
 	echo '</form>';
 
@@ -739,11 +831,18 @@ function showGuestUserForm() {
 	echo '<button type="submit">Reset password</button>';
 	echo '</form>';
 
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="canResetPassword" />';
+	echo '<input type="text" name="selector" placeholder="Selector" /> ';
+	echo '<input type="text" name="token" placeholder="Token" /> ';
+	echo '<button type="submit">Can reset password?</button>';
+	echo '</form>';
+
 	echo '<h1>Administration</h1>';
 
 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="admin.createUser" />';
-	echo '<input type="text" name="email" placeholder="Email" /> ';
+	echo '<input type="text" name="email" placeholder="Email address" /> ';
 	echo '<input type="text" name="password" placeholder="Password" /> ';
 	echo '<input type="text" name="username" placeholder="Username (optional)" /> ';
 	echo '<select name="require_unique_username" size="1">';
@@ -761,7 +860,7 @@ function showGuestUserForm() {
 
 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="admin.deleteUser" />';
-	echo '<input type="text" name="email" placeholder="Email" /> ';
+	echo '<input type="text" name="email" placeholder="Email address" /> ';
 	echo '<button type="submit">Delete user by email</button>';
 	echo '</form>';
 
@@ -780,7 +879,7 @@ function showGuestUserForm() {
 
 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="admin.addRole" />';
-	echo '<input type="text" name="email" placeholder="Email" /> ';
+	echo '<input type="text" name="email" placeholder="Email address" /> ';
 	echo '<select name="role">' . \createRolesOptions() . '</select>';
 	echo '<button type="submit">Add role for user by email</button>';
 	echo '</form>';
@@ -801,7 +900,7 @@ function showGuestUserForm() {
 
 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="admin.removeRole" />';
-	echo '<input type="text" name="email" placeholder="Email" /> ';
+	echo '<input type="text" name="email" placeholder="Email address" /> ';
 	echo '<select name="role">' . \createRolesOptions() . '</select>';
 	echo '<button type="submit">Remove role for user by email</button>';
 	echo '</form>';
@@ -819,6 +918,30 @@ function showGuestUserForm() {
 	echo '<select name="role">' . \createRolesOptions() . '</select>';
 	echo '<button type="submit">Does user have role?</button>';
 	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="admin.getRoles" />';
+	echo '<input type="text" name="id" placeholder="ID" /> ';
+	echo '<button type="submit">Get user\'s roles</button>';
+	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="admin.logInAsUserById" />';
+	echo '<input type="text" name="id" placeholder="ID" /> ';
+	echo '<button type="submit">Log in as user by ID</button>';
+	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="admin.logInAsUserByEmail" />';
+	echo '<input type="text" name="email" placeholder="Email address" /> ';
+	echo '<button type="submit">Log in as user by email address</button>';
+	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="admin.logInAsUserByUsername" />';
+	echo '<input type="text" name="username" placeholder="Username" /> ';
+	echo '<button type="submit">Log in as user by username</button>';
+	echo '</form>';
 }
 
 function showConfirmEmailForm() {
@@ -836,7 +959,7 @@ function showConfirmEmailForm() {
 
 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="resendConfirmationForEmail" />';
-	echo '<input type="text" name="email" placeholder="Email" /> ';
+	echo '<input type="text" name="email" placeholder="Email address" /> ';
 	echo '<button type="submit">Re-send confirmation</button>';
 	echo '</form>';
 
@@ -848,11 +971,9 @@ function showConfirmEmailForm() {
 }
 
 function createRolesOptions() {
-	$roleReflection = new ReflectionClass(\Delight\Auth\Role::class);
-
 	$out = '';
 
-	foreach ($roleReflection->getConstants() as $roleName => $roleValue) {
+	foreach (\Delight\Auth\Role::getMap() as $roleValue => $roleName) {
 		$out .= '<option value="' . $roleValue . '">' . $roleName . '</option>';
 	}