Fail safely in role checks when invalid input has been supplied

README.md

@@ -114,7 +114,7 @@ Migrating from an earlier version of this project? See our [upgrade guide](Migra
 $auth = new \Delight\Auth\Auth($db);
 ```
 
-If you have an open `PDO` connection already, just re-use it.
+If you have an open `PDO` connection already, just re-use it. The database user (e.g. `my-username`) needs at least the privileges `SELECT`, `INSERT`, `UPDATE` and `DELETE` for the tables used by this library (or their parent database).
 
 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.
 
@@ -403,6 +403,8 @@ $url = 'https://www.example.com/verify_email?selector=' . \urlencode($selector)
 
 After the request to change the email address has been made, or even better, after the change has been confirmed by the user, you should send an email to their account’s *previous* email address as an out-of-band notification informing the account owner about this critical change.
 
+**Note:** Changes to a user’s email address take effect in the local session immediately, as expected. In other sessions (e.g. on other devices), the changes may need up to five minutes to take effect, though. This increases performance and usually poses no problem. If you want to change this behavior, nevertheless, simply decrease (or perhaps increase) the value that you pass to the [`Auth` constructor](#creating-a-new-instance) as the argument named `$sessionResyncInterval`.
+
 ### Re-sending confirmation requests
 
 If an earlier confirmation request could not be delivered to the user, or if the user missed that request, or if they just don’t want to wait any longer, you may re-send an earlier request like this:
@@ -477,6 +479,8 @@ Additionally, if you store custom information in the session as well, and if you
 $auth->destroySession();
 ```
 
+**Note:** Global logouts take effect in the local session immediately, as expected. In other sessions (e.g. on other devices), the changes may need up to five minutes to take effect, though. This increases performance and usually poses no problem. If you want to change this behavior, nevertheless, simply decrease (or perhaps increase) the value that you pass to the [`Auth` constructor](#creating-a-new-instance) as the argument named `$sessionResyncInterval`.
+
 ### Accessing user information
 
 #### Login state
@@ -927,6 +931,8 @@ catch (\Delight\Auth\AmbiguousUsernameException $e) {
 }
 ```
 
+**Note:** Changes to a user’s set of roles take effect in the local session immediately, as expected. In other sessions (e.g. on other devices), the changes may need up to five minutes to take effect, though. This increases performance and usually poses no problem. If you want to change this behavior, nevertheless, simply decrease (or perhaps increase) the value that you pass to the [`Auth` constructor](#creating-a-new-instance) as the argument named `$sessionResyncInterval`.
+
 #### Taking roles away from users
 
 ```php
@@ -959,6 +965,8 @@ catch (\Delight\Auth\AmbiguousUsernameException $e) {
 }
 ```
 
+**Note:** Changes to a user’s set of roles take effect in the local session immediately, as expected. In other sessions (e.g. on other devices), the changes may need up to five minutes to take effect, though. This increases performance and usually poses no problem. If you want to change this behavior, nevertheless, simply decrease (or perhaps increase) the value that you pass to the [`Auth` constructor](#creating-a-new-instance) as the argument named `$sessionResyncInterval`.
+
 #### Checking roles
 
 ```php

src/Administration.php

@@ -270,8 +270,11 @@ final class Administration extends UserManager {
 	 * @see Role
 	 */
 	public function doesUserHaveRole($userId, $role) {
+		if (empty($role) || !\is_numeric($role)) {
+			return false;
+		}
+
 		$userId = (int) $userId;
-		$role = (int) $role;
 
 		$rolesBitmask = $this->db->selectValue(
 			'SELECT roles_mask FROM ' . $this->dbTablePrefix . 'users WHERE id = ?',
@@ -282,6 +285,8 @@ final class Administration extends UserManager {
 			throw new UnknownIdException();
 		}
 
+		$role = (int) $role;
+
 		return ($rolesBitmask & $role) === $role;
 	}
 
@@ -432,7 +437,7 @@ final class Administration extends UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 	}
 
@@ -457,7 +462,7 @@ final class Administration extends UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 
 		if ($userData === null) {
@@ -478,7 +483,7 @@ final class Administration extends UserManager {
 			return true;
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 	}
 
@@ -549,7 +554,7 @@ final class Administration extends UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 
 		$numberOfMatchingUsers = ($users !== null) ? \count($users) : 0;

src/Auth.php

@@ -119,7 +119,7 @@ final class Auth extends UserManager {
 						);
 					}
 					catch (Error $e) {
-						throw new DatabaseError();
+						throw new DatabaseError($e->getMessage());
 					}
 
 					if (!empty($rememberData)) {
@@ -161,7 +161,7 @@ final class Auth extends UserManager {
 					);
 				}
 				catch (Error $e) {
-					throw new DatabaseError();
+					throw new DatabaseError($e->getMessage());
 				}
 
 				// if the user's data has been found
@@ -358,7 +358,7 @@ final class Auth extends UserManager {
 				);
 			}
 			catch (Error $e) {
-				throw new DatabaseError();
+				throw new DatabaseError($e->getMessage());
 			}
 
 			if (!empty($expectedHash)) {
@@ -506,7 +506,7 @@ final class Auth extends UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 
 		$this->setRememberCookie($selector, $token, $expires);
@@ -572,7 +572,7 @@ final class Auth extends UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 
 		parent::onLoginSuccessful($userId, $email, $username, $status, $roles, $forceLogout, $remembered);
@@ -625,7 +625,7 @@ final class Auth extends UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 
 		if (!empty($confirmationData)) {
@@ -639,7 +639,7 @@ final class Auth extends UserManager {
 						);
 					}
 					catch (Error $e) {
-						throw new DatabaseError();
+						throw new DatabaseError($e->getMessage());
 					}
 
 					// mark the email address as verified (and possibly update it to the new address given)
@@ -657,7 +657,7 @@ final class Auth extends UserManager {
 						throw new UserAlreadyExistsException();
 					}
 					catch (Error $e) {
-						throw new DatabaseError();
+						throw new DatabaseError($e->getMessage());
 					}
 
 					// if the user is currently signed in
@@ -677,7 +677,7 @@ final class Auth extends UserManager {
 						);
 					}
 					catch (Error $e) {
-						throw new DatabaseError();
+						throw new DatabaseError($e->getMessage());
 					}
 
 					// if the email address has not been changed but simply been verified
@@ -822,7 +822,7 @@ final class Auth extends UserManager {
 				);
 			}
 			catch (Error $e) {
-				throw new DatabaseError();
+				throw new DatabaseError($e->getMessage());
 			}
 
 			if ((int) $existingUsersWithNewEmail !== 0) {
@@ -836,7 +836,7 @@ final class Auth extends UserManager {
 				);
 			}
 			catch (Error $e) {
-				throw new DatabaseError();
+				throw new DatabaseError($e->getMessage());
 			}
 
 			// ensure that at least the current (old) email address has been verified before proceeding
@@ -924,7 +924,7 @@ final class Auth extends UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 
 		if ($latestAttempt === null) {
@@ -1137,7 +1137,7 @@ final class Auth extends UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 
 		if (!empty($userData)) {
@@ -1173,7 +1173,7 @@ final class Auth extends UserManager {
 			}
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 	}
 
@@ -1211,7 +1211,7 @@ final class Auth extends UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 
 		if (\is_callable($callback)) {
@@ -1249,7 +1249,7 @@ final class Auth extends UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 
 		if (!empty($resetData)) {
@@ -1267,7 +1267,7 @@ final class Auth extends UserManager {
 							);
 						}
 						catch (Error $e) {
-							throw new DatabaseError();
+							throw new DatabaseError($e->getMessage());
 						}
 					}
 					else {
@@ -1365,7 +1365,7 @@ final class Auth extends UserManager {
 				);
 			}
 			catch (Error $e) {
-				throw new DatabaseError();
+				throw new DatabaseError($e->getMessage());
 			}
 		}
 		else {
@@ -1391,7 +1391,7 @@ final class Auth extends UserManager {
 				return (int) $enabled === 1;
 			}
 			catch (Error $e) {
-				throw new DatabaseError();
+				throw new DatabaseError($e->getMessage());
 			}
 		}
 		else {
@@ -1563,9 +1563,13 @@ final class Auth extends UserManager {
 	 * @see Role
 	 */
 	public function hasRole($role) {
-		$role = (int) $role;
+		if (empty($role) || !\is_numeric($role)) {
+			return false;
+		}
 
 		if (isset($_SESSION) && isset($_SESSION[self::SESSION_FIELD_ROLES])) {
+			$role = (int) $role;
+
 			return (((int) $_SESSION[self::SESSION_FIELD_ROLES]) & $role) === $role;
 		}
 		else {
@@ -1692,7 +1696,7 @@ final class Auth extends UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 
 		if ($bucket === null) {
@@ -1730,7 +1734,7 @@ final class Auth extends UserManager {
 				);
 			}
 			catch (Error $e) {
-				throw new DatabaseError();
+				throw new DatabaseError($e->getMessage());
 			}
 
 			if ($affected === 0) {
@@ -1744,7 +1748,7 @@ final class Auth extends UserManager {
 				}
 				catch (IntegrityConstraintViolationException $ignored) {}
 				catch (Error $e) {
-					throw new DatabaseError();
+					throw new DatabaseError($e->getMessage());
 				}
 			}
 		}

src/UserManager.php

@@ -172,7 +172,7 @@ abstract class UserManager {
 			throw new UserAlreadyExistsException();
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 
 		$newUserId = (int) $this->db->getLastInsertId();
@@ -207,7 +207,7 @@ abstract class UserManager {
 			}
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 	}
 
@@ -263,7 +263,7 @@ abstract class UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 
 		if (empty($users)) {
@@ -356,7 +356,7 @@ abstract class UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 
 		if (\is_callable($callback)) {
@@ -390,7 +390,7 @@ abstract class UserManager {
 			);
 		}
 		catch (Error $e) {
-			throw new DatabaseError();
+			throw new DatabaseError($e->getMessage());
 		}
 	}