Update migration guide

This enables support for passwords with more than 72 bytes (or more
than 18-72 characters) and for passwords containing null bytes

Database/MySQL.sql

@@ -7,62 +7,101 @@
 /*!40101 SET @OLD_COLLATION_CONNECTION=@@COLLATION_CONNECTION */;
 /*!40101 SET NAMES utf8mb4 */;
 
-CREATE TABLE IF NOT EXISTS `users` (
-  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
+CREATE TABLE `users` (
+  `id` int unsigned NOT NULL AUTO_INCREMENT,
   `email` varchar(249) COLLATE utf8mb4_unicode_ci NOT NULL,
   `password` varchar(255) CHARACTER SET latin1 COLLATE latin1_general_cs NOT NULL,
   `username` varchar(100) COLLATE utf8mb4_unicode_ci DEFAULT NULL,
-  `status` tinyint(2) unsigned NOT NULL DEFAULT '0',
-  `verified` tinyint(1) unsigned NOT NULL DEFAULT '0',
-  `resettable` tinyint(1) unsigned NOT NULL DEFAULT '1',
-  `roles_mask` int(10) unsigned NOT NULL DEFAULT '0',
-  `registered` int(10) unsigned NOT NULL,
-  `last_login` int(10) unsigned DEFAULT NULL,
-  `force_logout` mediumint(7) unsigned NOT NULL DEFAULT '0',
+  `status` tinyint unsigned NOT NULL DEFAULT '0',
+  `verified` tinyint unsigned NOT NULL DEFAULT '0',
+  `resettable` tinyint unsigned NOT NULL DEFAULT '1',
+  `roles_mask` int unsigned NOT NULL DEFAULT '0',
+  `registered` int unsigned NOT NULL,
+  `last_login` int unsigned DEFAULT NULL,
+  `force_logout` mediumint unsigned NOT NULL DEFAULT '0',
   PRIMARY KEY (`id`),
   UNIQUE KEY `email` (`email`)
 ) ENGINE=MyISAM DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
 
-CREATE TABLE IF NOT EXISTS `users_confirmations` (
-  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
-  `user_id` int(10) unsigned NOT NULL,
+CREATE TABLE `users_2fa` (
+  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
+  `user_id` int unsigned NOT NULL,
+  `mechanism` tinyint unsigned NOT NULL,
+  `seed` varchar(255) COLLATE utf8mb4_unicode_ci DEFAULT NULL,
+  `created_at` int unsigned NOT NULL,
+  `expires_at` int unsigned DEFAULT NULL,
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `user_id_mechanism` (`user_id`,`mechanism`)
+) ENGINE=MyISAM DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+CREATE TABLE `users_audit_log` (
+  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
+  `user_id` int unsigned DEFAULT NULL,
+  `event_at` int unsigned NOT NULL,
+  `event_type` varchar(128) CHARACTER SET ascii COLLATE ascii_general_ci NOT NULL,
+  `admin_id` int unsigned DEFAULT NULL,
+  `ip_address` varchar(49) CHARACTER SET ascii COLLATE ascii_general_ci DEFAULT NULL,
+  `user_agent` text COLLATE utf8mb4_unicode_ci DEFAULT NULL,
+  `details_json` text COLLATE utf8mb4_unicode_ci DEFAULT NULL,
+  PRIMARY KEY (`id`),
+  KEY `event_at` (`event_at`),
+  KEY `user_id_event_at` (`user_id`,`event_at`),
+  KEY `user_id_event_type_event_at` (`user_id`,`event_type`,`event_at`)
+) ENGINE=MyISAM DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+CREATE TABLE `users_confirmations` (
+  `id` int unsigned NOT NULL AUTO_INCREMENT,
+  `user_id` int unsigned NOT NULL,
   `email` varchar(249) COLLATE utf8mb4_unicode_ci NOT NULL,
   `selector` varchar(16) CHARACTER SET latin1 COLLATE latin1_general_cs NOT NULL,
   `token` varchar(255) CHARACTER SET latin1 COLLATE latin1_general_cs NOT NULL,
-  `expires` int(10) unsigned NOT NULL,
+  `expires` int unsigned NOT NULL,
   PRIMARY KEY (`id`),
   UNIQUE KEY `selector` (`selector`),
   KEY `email_expires` (`email`,`expires`),
   KEY `user_id` (`user_id`)
 ) ENGINE=MyISAM DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
 
-CREATE TABLE IF NOT EXISTS `users_remembered` (
-  `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
-  `user` int(10) unsigned NOT NULL,
+CREATE TABLE `users_otps` (
+  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
+  `user_id` int unsigned NOT NULL,
+  `mechanism` tinyint unsigned NOT NULL,
+  `single_factor` tinyint unsigned NOT NULL DEFAULT '0',
   `selector` varchar(24) CHARACTER SET latin1 COLLATE latin1_general_cs NOT NULL,
   `token` varchar(255) CHARACTER SET latin1 COLLATE latin1_general_cs NOT NULL,
-  `expires` int(10) unsigned NOT NULL,
+  `expires_at` int unsigned DEFAULT NULL,
+  PRIMARY KEY (`id`),
+  KEY `user_id_mechanism` (`user_id`,`mechanism`),
+  KEY `selector_user_id` (`selector`,`user_id`)
+) ENGINE=MyISAM DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+CREATE TABLE `users_remembered` (
+  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
+  `user` int unsigned NOT NULL,
+  `selector` varchar(24) CHARACTER SET latin1 COLLATE latin1_general_cs NOT NULL,
+  `token` varchar(255) CHARACTER SET latin1 COLLATE latin1_general_cs NOT NULL,
+  `expires` int unsigned NOT NULL,
   PRIMARY KEY (`id`),
   UNIQUE KEY `selector` (`selector`),
   KEY `user` (`user`)
 ) ENGINE=MyISAM DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
 
-CREATE TABLE IF NOT EXISTS `users_resets` (
-  `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
-  `user` int(10) unsigned NOT NULL,
+CREATE TABLE `users_resets` (
+  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
+  `user` int unsigned NOT NULL,
   `selector` varchar(20) CHARACTER SET latin1 COLLATE latin1_general_cs NOT NULL,
   `token` varchar(255) CHARACTER SET latin1 COLLATE latin1_general_cs NOT NULL,
-  `expires` int(10) unsigned NOT NULL,
+  `expires` int unsigned NOT NULL,
   PRIMARY KEY (`id`),
   UNIQUE KEY `selector` (`selector`),
   KEY `user_expires` (`user`,`expires`)
 ) ENGINE=MyISAM DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
 
-CREATE TABLE IF NOT EXISTS `users_throttling` (
+CREATE TABLE `users_throttling` (
   `bucket` varchar(44) CHARACTER SET latin1 COLLATE latin1_general_cs NOT NULL,
-  `tokens` float unsigned NOT NULL,
-  `replenished_at` int(10) unsigned NOT NULL,
-  `expires_at` int(10) unsigned NOT NULL,
+  `tokens` float NOT NULL,
+  `replenished_at` int unsigned NOT NULL,
+  `expires_at` int unsigned NOT NULL,
   PRIMARY KEY (`bucket`),
   KEY `expires_at` (`expires_at`)
 ) ENGINE=MyISAM DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Database/PostgreSQL.sql

@@ -4,55 +4,91 @@
 
 BEGIN;
 
-CREATE TABLE IF NOT EXISTS "users" (
-	"id" SERIAL PRIMARY KEY CHECK ("id" >= 0),
+CREATE TABLE "users" (
+	"id" SERIAL PRIMARY KEY,
 	"email" VARCHAR(249) UNIQUE NOT NULL,
-	"password" VARCHAR(255) NOT NULL,
+	"password" VARCHAR(255) NOT NULL COLLATE "C",
 	"username" VARCHAR(100) DEFAULT NULL,
-	"status" SMALLINT NOT NULL DEFAULT '0' CHECK ("status" >= 0),
-	"verified" SMALLINT NOT NULL DEFAULT '0' CHECK ("verified" >= 0),
-	"resettable" SMALLINT NOT NULL DEFAULT '1' CHECK ("resettable" >= 0),
-	"roles_mask" INTEGER NOT NULL DEFAULT '0' CHECK ("roles_mask" >= 0),
+	"status" SMALLINT NOT NULL DEFAULT 0 CHECK ("status" >= 0),
+	"verified" SMALLINT NOT NULL DEFAULT 0 CHECK ("verified" >= 0 AND "verified" <= 1),
+	"resettable" SMALLINT NOT NULL DEFAULT 1 CHECK ("resettable" >= 0 AND "resettable" <= 1),
+	"roles_mask" INTEGER NOT NULL DEFAULT 0 CHECK ("roles_mask" >= 0),
 	"registered" INTEGER NOT NULL CHECK ("registered" >= 0),
 	"last_login" INTEGER DEFAULT NULL CHECK ("last_login" >= 0),
-	"force_logout" INTEGER NOT NULL DEFAULT '0' CHECK ("force_logout" >= 0)
+	"force_logout" INTEGER NOT NULL DEFAULT 0 CHECK ("force_logout" >= 0)
 );
 
-CREATE TABLE IF NOT EXISTS "users_confirmations" (
-	"id" SERIAL PRIMARY KEY CHECK ("id" >= 0),
+CREATE TABLE "users_2fa" (
+	"id" BIGSERIAL PRIMARY KEY,
+	"user_id" INTEGER NOT NULL CHECK ("user_id" >= 0),
+	"mechanism" SMALLINT NOT NULL CHECK ("mechanism" >= 0),
+	"seed" VARCHAR(255) DEFAULT NULL COLLATE "C",
+	"created_at" INTEGER NOT NULL CHECK ("created_at" >= 0),
+	"expires_at" INTEGER DEFAULT NULL CHECK ("expires_at" >= 0)
+);
+CREATE UNIQUE INDEX "users_2fa_user_id_mechanism_uq" ON "users_2fa" ("user_id", "mechanism");
+
+CREATE TABLE "users_audit_log" (
+	"id" BIGSERIAL PRIMARY KEY,
+	"user_id" INTEGER DEFAULT NULL CHECK ("user_id" >= 0),
+	"event_at" INTEGER NOT NULL CHECK ("event_at" >= 0),
+	"event_type" VARCHAR(128) NOT NULL COLLATE "C",
+	"admin_id" INTEGER DEFAULT NULL CHECK ("admin_id" >= 0),
+	"ip_address" INET DEFAULT NULL,
+	"user_agent" TEXT DEFAULT NULL,
+	"details_json" JSONB DEFAULT NULL
+);
+CREATE INDEX "users_audit_log_event_at_ix" ON "users_audit_log" ("event_at");
+CREATE INDEX "users_audit_log_user_id_event_at_ix" ON "users_audit_log" ("user_id", "event_at");
+CREATE INDEX "users_audit_log_user_id_event_type_event_at_ix" ON "users_audit_log" ("user_id", "event_type", "event_at");
+
+CREATE TABLE "users_confirmations" (
+	"id" SERIAL PRIMARY KEY,
 	"user_id" INTEGER NOT NULL CHECK ("user_id" >= 0),
 	"email" VARCHAR(249) NOT NULL,
-	"selector" VARCHAR(16) UNIQUE NOT NULL,
-	"token" VARCHAR(255) NOT NULL,
+	"selector" VARCHAR(16) UNIQUE NOT NULL COLLATE "C",
+	"token" VARCHAR(255) NOT NULL COLLATE "C",
 	"expires" INTEGER NOT NULL CHECK ("expires" >= 0)
 );
-CREATE INDEX IF NOT EXISTS "email_expires" ON "users_confirmations" ("email", "expires");
-CREATE INDEX IF NOT EXISTS "user_id" ON "users_confirmations" ("user_id");
+CREATE INDEX "users_confirmations_email_expires_ix" ON "users_confirmations" ("email", "expires");
+CREATE INDEX "users_confirmations_user_id_ix" ON "users_confirmations" ("user_id");
 
-CREATE TABLE IF NOT EXISTS "users_remembered" (
-	"id" BIGSERIAL PRIMARY KEY CHECK ("id" >= 0),
+CREATE TABLE "users_otps" (
+	"id" BIGSERIAL PRIMARY KEY,
+	"user_id" INTEGER NOT NULL CHECK ("user_id" >= 0),
+	"mechanism" SMALLINT NOT NULL CHECK ("mechanism" >= 0),
+	"single_factor" SMALLINT NOT NULL DEFAULT 0 CHECK ("single_factor" >= 0 AND "single_factor" <= 1),
+	"selector" VARCHAR(24) NOT NULL COLLATE "C",
+	"token" VARCHAR(255) NOT NULL COLLATE "C",
+	"expires_at" INTEGER DEFAULT NULL CHECK ("expires_at" >= 0)
+);
+CREATE INDEX "users_otps_user_id_mechanism_ix" ON "users_otps" ("user_id", "mechanism");
+CREATE INDEX "users_otps_selector_user_id_ix" ON "users_otps" ("selector", "user_id");
+
+CREATE TABLE "users_remembered" (
+	"id" BIGSERIAL PRIMARY KEY,
 	"user" INTEGER NOT NULL CHECK ("user" >= 0),
-	"selector" VARCHAR(24) UNIQUE NOT NULL,
-	"token" VARCHAR(255) NOT NULL,
+	"selector" VARCHAR(24) UNIQUE NOT NULL COLLATE "C",
+	"token" VARCHAR(255) NOT NULL COLLATE "C",
 	"expires" INTEGER NOT NULL CHECK ("expires" >= 0)
 );
-CREATE INDEX IF NOT EXISTS "user" ON "users_remembered" ("user");
+CREATE INDEX "users_remembered_user_ix" ON "users_remembered" ("user");
 
-CREATE TABLE IF NOT EXISTS "users_resets" (
-	"id" BIGSERIAL PRIMARY KEY CHECK ("id" >= 0),
+CREATE TABLE "users_resets" (
+	"id" BIGSERIAL PRIMARY KEY,
 	"user" INTEGER NOT NULL CHECK ("user" >= 0),
-	"selector" VARCHAR(20) UNIQUE NOT NULL,
-	"token" VARCHAR(255) NOT NULL,
+	"selector" VARCHAR(20) UNIQUE NOT NULL COLLATE "C",
+	"token" VARCHAR(255) NOT NULL COLLATE "C",
 	"expires" INTEGER NOT NULL CHECK ("expires" >= 0)
 );
-CREATE INDEX IF NOT EXISTS "user_expires" ON "users_resets" ("user", "expires");
+CREATE INDEX "users_resets_user_expires_ix" ON "users_resets" ("user", "expires");
 
-CREATE TABLE IF NOT EXISTS "users_throttling" (
-	"bucket" VARCHAR(44) PRIMARY KEY,
+CREATE TABLE "users_throttling" (
+	"bucket" VARCHAR(44) PRIMARY KEY COLLATE "C",
 	"tokens" REAL NOT NULL CHECK ("tokens" >= 0),
 	"replenished_at" INTEGER NOT NULL CHECK ("replenished_at" >= 0),
 	"expires_at" INTEGER NOT NULL CHECK ("expires_at" >= 0)
 );
-CREATE INDEX IF NOT EXISTS "expires_at" ON "users_throttling" ("expires_at");
+CREATE INDEX "users_throttling_expires_at_ix" ON "users_throttling" ("expires_at");
 
 COMMIT;

Database/SQLite.sql

@@ -5,56 +5,92 @@
 PRAGMA foreign_keys = OFF;
 
 CREATE TABLE "users" (
-	"id" INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL CHECK ("id" >= 0),
-	"email" VARCHAR(249) NOT NULL,
-	"password" VARCHAR(255) NOT NULL,
-	"username" VARCHAR(100) DEFAULT NULL,
-	"status" INTEGER NOT NULL CHECK ("status" >= 0) DEFAULT "0",
-	"verified" INTEGER NOT NULL CHECK ("verified" >= 0) DEFAULT "0",
-	"resettable" INTEGER NOT NULL CHECK ("resettable" >= 0) DEFAULT "1",
-	"roles_mask" INTEGER NOT NULL CHECK ("roles_mask" >= 0) DEFAULT "0",
+	"id" INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
+	"email" TEXT NOT NULL COLLATE NOCASE CHECK (LENGTH("email") <= 249),
+	"password" TEXT NOT NULL COLLATE BINARY CHECK (LENGTH("password") <= 255),
+	"username" TEXT DEFAULT NULL COLLATE NOCASE CHECK (LENGTH("username") <= 100),
+	"status" INTEGER NOT NULL CHECK ("status" >= 0) DEFAULT 0,
+	"verified" INTEGER NOT NULL CHECK ("verified" >= 0 AND "verified" <= 1) DEFAULT 0,
+	"resettable" INTEGER NOT NULL CHECK ("resettable" >= 0 AND "resettable" <= 1) DEFAULT 1,
+	"roles_mask" INTEGER NOT NULL CHECK ("roles_mask" >= 0) DEFAULT 0,
 	"registered" INTEGER NOT NULL CHECK ("registered" >= 0),
 	"last_login" INTEGER CHECK ("last_login" >= 0) DEFAULT NULL,
-	"force_logout" INTEGER NOT NULL CHECK ("force_logout" >= 0) DEFAULT "0",
-	CONSTRAINT "email" UNIQUE ("email")
+	"force_logout" INTEGER NOT NULL CHECK ("force_logout" >= 0) DEFAULT 0,
+	CONSTRAINT "users_email_uq" UNIQUE ("email")
 );
 
+CREATE TABLE "users_2fa" (
+	"id" INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
+	"user_id" INTEGER NOT NULL CHECK ("user_id" >= 0),
+	"mechanism" INTEGER NOT NULL CHECK ("mechanism" >= 0),
+	"seed" TEXT DEFAULT NULL COLLATE BINARY CHECK (LENGTH("seed") <= 255),
+	"created_at" INTEGER NOT NULL CHECK ("created_at" >= 0),
+	"expires_at" INTEGER CHECK ("expires_at" >= 0) DEFAULT NULL,
+	CONSTRAINT "users_2fa_user_id_mechanism_uq" UNIQUE ("user_id", "mechanism")
+);
+
+CREATE TABLE "users_audit_log" (
+	"id" INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
+	"user_id" INTEGER DEFAULT NULL CHECK ("user_id" >= 0),
+	"event_at" INTEGER NOT NULL CHECK ("event_at" >= 0),
+	"event_type" TEXT NOT NULL COLLATE NOCASE CHECK (LENGTH("event_type") <= 128),
+	"admin_id" INTEGER DEFAULT NULL CHECK ("admin_id" >= 0),
+	"ip_address" TEXT DEFAULT NULL COLLATE NOCASE CHECK (LENGTH("ip_address") <= 49),
+	"user_agent" TEXT DEFAULT NULL,
+	"details_json" TEXT DEFAULT NULL
+);
+CREATE INDEX "users_audit_log_event_at_ix" ON "users_audit_log" ("event_at");
+CREATE INDEX "users_audit_log_user_id_event_at_ix" ON "users_audit_log" ("user_id", "event_at");
+CREATE INDEX "users_audit_log_user_id_event_type_event_at_ix" ON "users_audit_log" ("user_id", "event_type", "event_at");
+
 CREATE TABLE "users_confirmations" (
-	"id" INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL CHECK ("id" >= 0),
+	"id" INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
 	"user_id" INTEGER NOT NULL CHECK ("user_id" >= 0),
-	"email" VARCHAR(249) NOT NULL,
-	"selector" VARCHAR(16) NOT NULL,
-	"token" VARCHAR(255) NOT NULL,
+	"email" TEXT NOT NULL COLLATE NOCASE CHECK (LENGTH("email") <= 249),
+	"selector" TEXT NOT NULL COLLATE BINARY CHECK (LENGTH("selector") <= 16),
+	"token" TEXT NOT NULL COLLATE BINARY CHECK (LENGTH("token") <= 255),
 	"expires" INTEGER NOT NULL CHECK ("expires" >= 0),
-	CONSTRAINT "selector" UNIQUE ("selector")
+	CONSTRAINT "users_confirmations_selector_uq" UNIQUE ("selector")
 );
-CREATE INDEX "users_confirmations.email_expires" ON "users_confirmations" ("email", "expires");
-CREATE INDEX "users_confirmations.user_id" ON "users_confirmations" ("user_id");
+CREATE INDEX "users_confirmations_email_expires_ix" ON "users_confirmations" ("email", "expires");
+CREATE INDEX "users_confirmations_user_id_ix" ON "users_confirmations" ("user_id");
+
+CREATE TABLE "users_otps" (
+	"id" INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
+	"user_id" INTEGER NOT NULL CHECK ("user_id" >= 0),
+	"mechanism" INTEGER NOT NULL CHECK ("mechanism" >= 0),
+	"single_factor" INTEGER NOT NULL CHECK ("single_factor" >= 0 AND "single_factor" <= 1) DEFAULT 0,
+	"selector" TEXT NOT NULL COLLATE BINARY CHECK (LENGTH("selector") <= 24),
+	"token" TEXT NOT NULL COLLATE BINARY CHECK (LENGTH("token") <= 255),
+	"expires_at" INTEGER CHECK ("expires_at" >= 0) DEFAULT NULL
+);
+CREATE INDEX "users_otps_user_id_mechanism_ix" ON "users_otps" ("user_id", "mechanism");
+CREATE INDEX "users_otps_selector_user_id_ix" ON "users_otps" ("selector", "user_id");
 
 CREATE TABLE "users_remembered" (
-	"id" INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL CHECK ("id" >= 0),
+	"id" INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
 	"user" INTEGER NOT NULL CHECK ("user" >= 0),
-	"selector" VARCHAR(24) NOT NULL,
-	"token" VARCHAR(255) NOT NULL,
+	"selector" TEXT NOT NULL COLLATE BINARY CHECK (LENGTH("selector") <= 24),
+	"token" TEXT NOT NULL COLLATE BINARY CHECK (LENGTH("token") <= 255),
 	"expires" INTEGER NOT NULL CHECK ("expires" >= 0),
-	CONSTRAINT "selector" UNIQUE ("selector")
+	CONSTRAINT "users_remembered_selector_uq" UNIQUE ("selector")
 );
-CREATE INDEX "users_remembered.user" ON "users_remembered" ("user");
+CREATE INDEX "users_remembered_user_ix" ON "users_remembered" ("user");
 
 CREATE TABLE "users_resets" (
-	"id" INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL CHECK ("id" >= 0),
+	"id" INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
 	"user" INTEGER NOT NULL CHECK ("user" >= 0),
-	"selector" VARCHAR(20) NOT NULL,
-	"token" VARCHAR(255) NOT NULL,
+	"selector" TEXT NOT NULL COLLATE BINARY CHECK (LENGTH("selector") <= 20),
+	"token" TEXT NOT NULL COLLATE BINARY CHECK (LENGTH("token") <= 255),
 	"expires" INTEGER NOT NULL CHECK ("expires" >= 0),
-	CONSTRAINT "selector" UNIQUE ("selector")
+	CONSTRAINT "users_resets_selector_uq" UNIQUE ("selector")
 );
-CREATE INDEX "users_resets.user_expires" ON "users_resets" ("user", "expires");
+CREATE INDEX "users_resets_user_expires_ix" ON "users_resets" ("user", "expires");
 
 CREATE TABLE "users_throttling" (
-	"bucket" VARCHAR(44) PRIMARY KEY NOT NULL,
+	"bucket" TEXT PRIMARY KEY NOT NULL COLLATE BINARY CHECK (LENGTH("bucket") <= 44),
 	"tokens" REAL NOT NULL CHECK ("tokens" >= 0),
 	"replenished_at" INTEGER NOT NULL CHECK ("replenished_at" >= 0),
 	"expires_at" INTEGER NOT NULL CHECK ("expires_at" >= 0)
 );
-CREATE INDEX "users_throttling.expires_at" ON "users_throttling" ("expires_at");
+CREATE INDEX "users_throttling_expires_at_ix" ON "users_throttling" ("expires_at");

Migration.md

@@ -1,6 +1,7 @@
 # Migration
 
  * [General](#general)
+ * [From `v8.x.x` to `v9.x.x`](#from-v8xx-to-v9xx)
  * [From `v7.x.x` to `v8.x.x`](#from-v7xx-to-v8xx)
  * [From `v6.x.x` to `v7.x.x`](#from-v6xx-to-v7xx)
  * [From `v5.x.x` to `v6.x.x`](#from-v5xx-to-v6xx)
@@ -13,6 +14,10 @@
 
 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 `v8.x.x` to `v9.x.x`
+
+ * The database schema has changed. Create the three new tables `users_2fa`, `users_otps` and `users_audit_log` in your [MySQL](Database/MySQL.sql), [PostgreSQL](Database/PostgreSQL.sql) or [SQLite](Database/SQLite.sql) schema to update your database.
+
 ## From `v7.x.x` to `v8.x.x`
 
  * The database schema has changed.

README.md

@@ -8,7 +8,7 @@ Completely framework-agnostic and database-agnostic.
 
 ## Why do I need this?
 
- * There are [tons](http://www.troyhunt.com/2011/01/whos-who-of-bad-password-practices.html) [of](http://www.jeremytunnell.com/posts/swab-password-policies-and-two-factor-authentication-a-comedy-of-errors) [websites](http://badpasswordpolicies.tumblr.com/) with weak authentication systems. Don’t build such a site.
+ * There are [tons](https://www.troyhunt.com/whos-who-of-bad-password-practices/) [of](https://blog.codinghorror.com/password-rules-are-bullshit/) [websites](https://badpasswordpolicies.tumblr.com/) with weak authentication systems. Don’t build such a site.
  * Re-implementing a new authentication system for every PHP project is *not* a good idea.
  * Building your own authentication classes piece by piece, and copying it to every project, is *not* recommended, either.
  * A secure authentication system with an easy-to-use API should be thoroughly designed and planned.
@@ -47,6 +47,10 @@ Completely framework-agnostic and database-agnostic.
 
 Migrating from an earlier version of this project? See our [upgrade guide](Migration.md) for help.
 
+## Commercial support
+
+Commercial support, paid features and development services for this library are available upon request: gh@delight.im
+
 ## Usage
 
  * [Creating a new instance](#creating-a-new-instance)
@@ -60,6 +64,7 @@ Migrating from an earlier version of this project? See our [upgrade guide](Migra
    * [Updating the password](#step-3-of-3-updating-the-password)
  * [Changing the current user’s password](#changing-the-current-users-password)
  * [Changing the current user’s email address](#changing-the-current-users-email-address)
+ * [Changing the current user’s username](#changing-the-current-users-username)
  * [Re-sending confirmation requests](#re-sending-confirmation-requests)
  * [Logout](#logout)
  * [Accessing user information](#accessing-user-information)
@@ -77,6 +82,7 @@ Migrating from an earlier version of this project? See our [upgrade guide](Migra
    * [Available roles](#available-roles)
    * [Permissions (or access rights, privileges or capabilities)](#permissions-or-access-rights-privileges-or-capabilities)
    * [Custom role names](#custom-role-names)
+ * [Two-factor authentication (2FA)](#two-factor-authentication-2fa)
  * [Enabling or disabling password resets](#enabling-or-disabling-password-resets)
  * [Throttling or rate limiting](#throttling-or-rate-limiting)
  * [Administration (managing users)](#administration-managing-users)
@@ -109,11 +115,11 @@ Migrating from an earlier version of this project? See our [upgrade guide](Migra
 
 // or
 
-// $db = new \Delight\Db\PdoDsn('mysql:dbname=my-database;host=localhost;charset=utf8mb4', 'my-username', 'my-password');
+// $db = \Delight\Db\PdoDatabase::fromDsn(new \Delight\Db\PdoDsn('mysql:dbname=my-database;host=localhost;charset=utf8mb4', 'my-username', 'my-password'));
 // or
-// $db = new \Delight\Db\PdoDsn('pgsql:dbname=my-database;host=localhost;port=5432', 'my-username', 'my-password');
+// $db = \Delight\Db\PdoDatabase::fromDsn(new \Delight\Db\PdoDsn('pgsql:dbname=my-database;host=localhost;port=5432', 'my-username', 'my-password'));
 // or
-// $db = new \Delight\Db\PdoDsn('sqlite:../Databases/my-database.sqlite');
+// $db = \Delight\Db\PdoDatabase::fromDsn(new \Delight\Db\PdoDsn('sqlite:../Databases/my-database.sqlite'));
 
 $auth = new \Delight\Auth\Auth($db);
 ```
@@ -130,12 +136,16 @@ During the lifetime of a session, some user data may be changed remotely, either
 
 If all your database tables need a common database name, schema name, or other qualifier that must be specified explicitly, you can optionally pass that qualifier to the constructor as the sixth parameter, which is named `$dbSchema`.
 
+If you want to use a `PdoDatabase` instance (e.g. `$db`) independently as well, please refer to the [documentation of the database library](https://github.com/delight-im/PHP-DB).
+
 ### Registration (sign up)
 
 ```php
 try {
     $userId = $auth->register($_POST['email'], $_POST['password'], $_POST['username'], function ($selector, $token) {
         echo 'Send ' . $selector . ' and ' . $token . ' to the user (e.g. via email)';
+        echo '  For emails, consider using the mail(...) function, Symfony Mailer, Swiftmailer, PHPMailer, etc.';
+        echo '  For SMS, consider using a third-party service and a compatible SDK';
     });
 
     echo 'We have signed up a new user with the ID ' . $userId;
@@ -154,22 +164,32 @@ catch (\Delight\Auth\TooManyRequestsException $e) {
 }
 ```
 
-**Note:** The anonymous callback function is a [closure](http://php.net/manual/en/functions.anonymous.php). Thus, besides its own parameters, only [superglobals](http://php.net/manual/en/language.variables.superglobals.php) like `$_GET`, `$_POST`, `$_COOKIE` and `$_SERVER` are available inside. For any other variable from the parent scope, you need to explicitly make a copy available inside by adding a `use` clause after the parameter list.
+**Note:** The anonymous callback function is a [closure](https://www.php.net/manual/functions.anonymous.php). Thus, besides its own parameters, only [superglobals](https://www.php.net/manual/language.variables.superglobals.php) like `$_GET`, `$_POST`, `$_COOKIE` and `$_SERVER` are available inside. For any other variable from the parent scope, you need to explicitly make a copy available inside by adding a `use` clause after the parameter list.
 
 The username in the third parameter is optional. You can pass `null` there if you don’t want to manage usernames.
 
 If you want to enforce unique usernames, on the other hand, simply call `registerWithUniqueUsername` instead of `register`, and be prepared to catch the `DuplicateUsernameException`.
 
+**Note:** When accepting and managing usernames, you may want to exclude non-printing control characters and certain printable special characters, as in the character class `[\x00-\x1f\x7f\/:@\\]`. In order to do so, you could wrap the call to `Auth#register` or `Auth#registerWithUniqueUsername` inside a conditional branch, for example by only accepting usernames when the following condition is satisfied:
+
+```php
+if (\preg_match('/[\x00-\x1f\x7f\/:@\\\\]/', $_POST['username']) === 0) {
+    // ...
+}
+```
+
 For email verification, you should build an URL with the selector and token and send it to the user, e.g.:
 
 ```php
 $url = 'https://www.example.com/verify_email?selector=' . \urlencode($selector) . '&token=' . \urlencode($token);
 ```
 
-If you don’t want to perform email verification, just omit the last parameter to `Auth#register`. The new user will be active immediately, then.
+If you don’t want to perform email verification, just omit the last parameter to `Auth#register`, i.e. the [anonymous function or closure](https://www.php.net/manual/functions.anonymous.php). The new user will be active immediately, then.
 
 Need to store additional user information? Read on [here](#additional-user-information).
 
+**Note:** When sending an email to the user, please note that the (optional) username, at this point, has not yet been confirmed as acceptable to the owner of the (new) email address. It could contain offensive or misleading language chosen by someone who is not actually the owner of the address.
+
 ### Login (sign in)
 
 ```php
@@ -255,6 +275,8 @@ Omit the third parameter or set it to `null` to disable the feature. Otherwise,
 try {
     $auth->forgotPassword($_POST['email'], function ($selector, $token) {
         echo 'Send ' . $selector . ' and ' . $token . ' to the user (e.g. via email)';
+        echo '  For emails, consider using the mail(...) function, Symfony Mailer, Swiftmailer, PHPMailer, etc.';
+        echo '  For SMS, consider using a third-party service and a compatible SDK';
     });
 
     echo 'Request has been generated';
@@ -273,7 +295,7 @@ catch (\Delight\Auth\TooManyRequestsException $e) {
 }
 ```
 
-**Note:** The anonymous callback function is a [closure](http://php.net/manual/en/functions.anonymous.php). Thus, besides its own parameters, only [superglobals](http://php.net/manual/en/language.variables.superglobals.php) like `$_GET`, `$_POST`, `$_COOKIE` and `$_SERVER` are available inside. For any other variable from the parent scope, you need to explicitly make a copy available inside by adding a `use` clause after the parameter list.
+**Note:** The anonymous callback function is a [closure](https://www.php.net/manual/functions.anonymous.php). Thus, besides its own parameters, only [superglobals](https://www.php.net/manual/language.variables.superglobals.php) like `$_GET`, `$_POST`, `$_COOKIE` and `$_SERVER` are available inside. For any other variable from the parent scope, you need to explicitly make a copy available inside by adding a `use` clause after the parameter list.
 
 You should build an URL with the selector and token and send it to the user, e.g.:
 
@@ -390,6 +412,8 @@ try {
     if ($auth->reconfirmPassword($_POST['password'])) {
         $auth->changeEmail($_POST['newEmail'], function ($selector, $token) {
             echo 'Send ' . $selector . ' and ' . $token . ' to the user (e.g. via email to the *new* address)';
+            echo '  For emails, consider using the mail(...) function, Symfony Mailer, Swiftmailer, PHPMailer, etc.';
+            echo '  For SMS, consider using a third-party service and a compatible SDK';
         });
 
         echo 'The change will take effect as soon as the new email address has been confirmed';
@@ -415,7 +439,7 @@ catch (\Delight\Auth\TooManyRequestsException $e) {
 }
 ```
 
-**Note:** The anonymous callback function is a [closure](http://php.net/manual/en/functions.anonymous.php). Thus, besides its own parameters, only [superglobals](http://php.net/manual/en/language.variables.superglobals.php) like `$_GET`, `$_POST`, `$_COOKIE` and `$_SERVER` are available inside. For any other variable from the parent scope, you need to explicitly make a copy available inside by adding a `use` clause after the parameter list.
+**Note:** The anonymous callback function is a [closure](https://www.php.net/manual/functions.anonymous.php). Thus, besides its own parameters, only [superglobals](https://www.php.net/manual/language.variables.superglobals.php) like `$_GET`, `$_POST`, `$_COOKIE` and `$_SERVER` are available inside. For any other variable from the parent scope, you need to explicitly make a copy available inside by adding a `use` clause after the parameter list.
 
 For email verification, you should build an URL with the selector and token and send it to the user, e.g.:
 
@@ -423,10 +447,42 @@ For email verification, you should build an URL with the selector and token and
 $url = 'https://www.example.com/verify_email?selector=' . \urlencode($selector) . '&token=' . \urlencode($token);
 ```
 
+**Note:** When sending an email to the user, please note that the (optional) username, at this point, has not yet been confirmed as acceptable to the owner of the (new) email address. It could contain offensive or misleading language chosen by someone who is not actually the owner of the address.
+
 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`.
 
+**Note:** When a user has set up two-factor authentication via email, changing the email address on their account does not automatically change the email address used for delivery of one-time passwords. You should disable 2FA via email for the user in that case, inform the user about this change, and ask them to set up 2FA via email again afterwards, perhaps even automatically by calling `Auth#prepareTwoFactorViaEmail` immediately after the successful change of the user’s email address.
+
+### Changing the current user’s username
+
+If a user is currently logged in, they may change their username.
+
+```php
+try {
+    $auth->changeUsername($_POST['newUsername']);
+
+    echo 'Username has been changed';
+}
+catch (\Delight\Auth\NotLoggedInException $e) {
+    die('Not logged in');
+}
+catch (\Delight\Auth\TooManyRequestsException $e) {
+    die('Too many requests');
+}
+```
+
+If you want to enforce unique usernames, simply pass `true` as the second argument to `Auth#changeUsername`, and be prepared to catch the `DuplicateUsernameException`.
+
+**Note:** When accepting and managing usernames, you may want to exclude non-printing control characters and certain printable special characters, as in the character class `[\x00-\x1f\x7f\/:@\\]`. In order to do so, you could wrap the call to `Auth#changeUsername` inside a conditional branch, for example by only accepting usernames when the following condition is satisfied:
+
+```php
+if (\preg_match('/[\x00-\x1f\x7f\/:@\\\\]/', $_POST['newUsername']) === 0) {
+    // ...
+}
+```
+
 ### 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:
@@ -435,6 +491,8 @@ If an earlier confirmation request could not be delivered to the user, or if the
 try {
     $auth->resendConfirmationForEmail($_POST['email'], function ($selector, $token) {
         echo 'Send ' . $selector . ' and ' . $token . ' to the user (e.g. via email)';
+        echo '  For emails, consider using the mail(...) function, Symfony Mailer, Swiftmailer, PHPMailer, etc.';
+        echo '  For SMS, consider using a third-party service and a compatible SDK';
     });
 
     echo 'The user may now respond to the confirmation request (usually by clicking a link)';
@@ -453,6 +511,8 @@ If you want to specify the user by their ID instead of by their email address, t
 try {
     $auth->resendConfirmationForUserId($_POST['userId'], function ($selector, $token) {
         echo 'Send ' . $selector . ' and ' . $token . ' to the user (e.g. via email)';
+        echo '  For emails, consider using the mail(...) function, Symfony Mailer, Swiftmailer, PHPMailer, etc.';
+        echo '  For SMS, consider using a third-party service and a compatible SDK';
     });
 
     echo 'The user may now respond to the confirmation request (usually by clicking a link)';
@@ -465,7 +525,7 @@ catch (\Delight\Auth\TooManyRequestsException $e) {
 }
 ```
 
-**Note:** The anonymous callback function is a [closure](http://php.net/manual/en/functions.anonymous.php). Thus, besides its own parameters, only [superglobals](http://php.net/manual/en/language.variables.superglobals.php) like `$_GET`, `$_POST`, `$_COOKIE` and `$_SERVER` are available inside. For any other variable from the parent scope, you need to explicitly make a copy available inside by adding a `use` clause after the parameter list.
+**Note:** The anonymous callback function is a [closure](https://www.php.net/manual/functions.anonymous.php). Thus, besides its own parameters, only [superglobals](https://www.php.net/manual/language.variables.superglobals.php) like `$_GET`, `$_POST`, `$_COOKIE` and `$_SERVER` are available inside. For any other variable from the parent scope, you need to explicitly make a copy available inside by adding a `use` clause after the parameter list.
 
 Usually, you should build an URL with the selector and token and send it to the user, e.g. as follows:
 
@@ -473,6 +533,8 @@ Usually, you should build an URL with the selector and token and send it to the
 $url = 'https://www.example.com/verify_email?selector=' . \urlencode($selector) . '&token=' . \urlencode($token);
 ```
 
+**Note:** When sending an email to the user, please note that the (optional) username, at this point, has not yet been confirmed as acceptable to the owner of the (new) email address. It could contain offensive or misleading language chosen by someone who is not actually the owner of the address.
+
 ### Logout
 
 ```php
@@ -612,7 +674,7 @@ Here’s how to use this library with your own tables for custom user informatio
         }
 
         if (!isset($_SESSION['_internal_user_info'])) {
-            // TODO: load your custom user information and assign it to the session variable below
+            // To do: load your custom user information and assign it to the session variable below
             // $_SESSION['_internal_user_info'] = ...
         }
 
@@ -790,6 +852,185 @@ instead of
 
 Just remember *not* to alias a *single* included role to *multiple* roles with custom names.
 
+### Two-factor authentication (2FA)
+
+ 1. This library supports three modes of two-factor authentication (2FA), or multi-factor authentication (MFA), which represent different sources or delivery mechanisms for one-time passwords (OTPs):
+
+    * time-based one-time passwords (TOTP)
+    * one-time passwords sent via SMS
+    * one-time passwords sent via email
+
+    Choose any combination of these modes that you want to support. You can start with just one, if you want, and add others later quite easily.
+
+ 1. For users who are signed in, you can check if they have set up two-factor authentication using `Auth#hasTwoFactor`. This checks if 2FA is set up using *any* mode, i.e. one or more of the mechanisms described before, and is useful if you want to advertise 2FA in general. Additionally, you will usually check if an individual mode of 2FA is set up using `Auth#hasTwoFactorViaTotp`, `Auth#hasTwoFactorViaSms` or `Auth#hasTwoFactorViaEmail`. Use those methods to check if the user should be presented with a way to enable or disable the specific mode of 2FA in their settings.
+
+ 1. In order to let users set up two-factor authentication via TOTP, i.e. with an authenticator application such as Google Authenticator, Ente Auth or Aegis Authenticator, call `Auth#prepareTwoFactorViaTotp` and provide the user-visible name of your application as the single argument. The result will be an array with the key URI for the QR code (that you will afterwards display to the user) at index zero, and the secret for manual input (that you can show to the user as an alternative) at index one. Wrap that call in `Auth#reconfirmPassword`.
+
+    ```php
+    try {
+        if ($auth->reconfirmPassword($_POST['password'])) {
+            $keyUriAndSecret = $auth->prepareTwoFactorViaTotp('Example.com');
+
+            // To do: encode the key URI '$keyUriAndSecret[0]' as a QR code (preferably on the client side) and display the QR code to the user
+            //   and, additionally, show the secret string '$keyUriAndSecret[1]' to the user as a fallback for manual input
+        }
+        else {
+            echo 'Please re-confirm your correct password';
+        }
+    }
+    catch (\Delight\Auth\TwoFactorMechanismAlreadyEnabledException $e) {
+        echo 'Two-factor authentication via TOTP has already been enabled';
+    }
+    catch (\Delight\Auth\NotLoggedInException $e) {
+        echo 'Please sign in first';
+    }
+    catch (\Delight\Auth\TooManyRequestsException $e) {
+        echo 'Please try again later';
+    }
+    ```
+
+    Now ask the user to set up your service in their authenticator application, either with the QR code or with the secret for manual input, and let them generate an initial one-time password that they need to enter within your application next.
+
+ 1. Alternatively, to let the user set up two-factor authentication via SMS, ask the user for their phone number and provide it as the single argument to `Auth#prepareTwoFactorViaSms`. The result will be an array with the (still unverified) phone number again at index zero, and the one-time password that you need to send to the user at index one. Wrap that call in `Auth#reconfirmPassword`.
+
+    ```php
+    try {
+        if ($auth->reconfirmPassword($_POST['password'])) {
+            $phoneNumberAndOtpValue = $auth->prepareTwoFactorViaSms($_POST['phoneNumber']);
+
+            // To do: send the one-time password '$phoneNumberAndOtpValue[1]' to (still unverified) phone number '$phoneNumberAndOtpValue[0]'
+            //   Consider using a third-party service and a compatible SDK to send the text message
+
+            echo 'Please enter the initial one-time password that has been sent to you via text message';
+        }
+        else {
+            echo 'Please re-confirm your correct password';
+        }
+    }
+    catch (\Delight\Auth\InvalidPhoneNumberException $e) {
+        echo 'Please provide a valid phone number';
+    }
+    catch (\Delight\Auth\TwoFactorMechanismAlreadyEnabledException $e) {
+        echo 'Two-factor authentication via SMS has already been enabled';
+    }
+    catch (\Delight\Auth\NotLoggedInException $e) {
+        echo 'Please sign in first';
+    }
+    catch (\Delight\Auth\TooManyRequestsException $e) {
+        echo 'Please try again later';
+    }
+    ```
+
+ 1. Finally, if you want to let the user set up two-factor authentication via email, simply call `Auth#prepareTwoFactorViaEmail`. The result will be an array with the user’s email address at index zero, and the one-time password that you need to send to the user at index one. Wrap that call in `Auth#reconfirmPassword`.
+
+    ```php
+    try {
+        if ($auth->reconfirmPassword($_POST['password'])) {
+            $emailAddressAndOtpValue = $auth->prepareTwoFactorViaEmail();
+
+            // To do: send the one-time password '$emailAddressAndOtpValue[1]' to email address '$emailAddressAndOtpValue[0]'
+            //   Consider using the 'mail' function, Symfony Mailer, Swiftmailer, PHPMailer, etc., to send the email
+
+            echo 'Please enter the initial one-time password that has been sent to you via email';
+        }
+        else {
+            echo 'Please re-confirm your correct password';
+        }
+    }
+    catch (\Delight\Auth\TwoFactorMechanismAlreadyEnabledException $e) {
+        echo 'Two-factor authentication via email has already been enabled';
+    }
+    catch (\Delight\Auth\NotLoggedInException $e) {
+        echo 'Please sign in first';
+    }
+    catch (\Delight\Auth\TooManyRequestsException $e) {
+        echo 'Please try again later';
+    }
+    ```
+
+    **Note:** When a user changes their email address, and they have set up two-factor authentication via email, this does not automatically change the email address used for delivery of one-time passwords. You should disable 2FA via email for the user in that case, inform the user about this change, and ask them to set up 2FA via email again afterwards, perhaps even automatically by calling `Auth#prepareTwoFactorViaEmail` immediately after the successful change of the user’s email address.
+
+ 1. As soon as the user has entered a one-time password in your application, which they generated or received in the steps before, pass this value to `Auth#enableTwoFactorViaTotp`, `Auth#enableTwoFactorViaSms` or `Auth#enableTwoFactorViaEmail` to complete the setup. If successful, a few recovery codes will be generated and returned to you, which you will show to the user and ask them to print or put somewhere safely – this is important!
+
+    ```php
+    try {
+        $recoveryCodes = $auth->enableTwoFactorViaTotp($_POST['oneTimePassword']);
+        // or $recoveryCodes = $auth->enableTwoFactorViaSms($_POST['oneTimePassword']);
+        // or $recoveryCodes = $auth->enableTwoFactorViaEmail($_POST['oneTimePassword']);
+
+        echo 'Here are a few recovery codes that can help you if you ever lose access to your authenticator application. Please print them and keep them safe for the future:' . "\n";
+        echo \implode("\n", $recoveryCodes);
+    }
+    catch (\Delight\Auth\InvalidOneTimePasswordException $e) {
+        echo 'Your one-time password has not been correct';
+    }
+    catch (\Delight\Auth\TwoFactorMechanismNotInitializedException $e) {
+        echo 'Please prepare the setup of two-factor authentication first';
+    }
+    catch (\Delight\Auth\TwoFactorMechanismAlreadyEnabledException $e) {
+        echo 'You have already enabled this mode of two-factor authentication';
+    }
+    catch (\Delight\Auth\NotLoggedInException $e) {
+        echo 'Please sign in first';
+    }
+    catch (\Delight\Auth\TooManyRequestsException $e) {
+        echo 'Please try again later';
+    }
+    ```
+
+    **Note:** You should notify the user whenever a new 2FA mode has been enabled, for example via email, or even on multiple separate communication channels.
+
+ 1. With the four methods `Auth#login`, `Auth#loginWithUsername`, `Auth#confirmEmailAndSignIn` and `Auth#resetPasswordAndSignIn`, where used in your application, you need to catch an additional `\Delight\Auth\SecondFactorRequiredException`. Whenever that exception occurs, you need to ask the user to enter a one-time password. The exception instance (e.g. `$e`) has all the information you need to request the one-time password from the user:
+
+    ```php
+    catch (\Delight\Auth\SecondFactorRequiredException $e) {
+        if ($e->hasTotpOption()) {
+            echo 'Please open your authenticator application and enter the code that is shown';
+        }
+
+        if ($e->hasSmsOption()) {
+            // To do: send '$e->getSmsOtpValue()' to '$e->getSmsRecipient()' via text message
+            //   Consider using a third-party service and a compatible SDK to send the text message
+
+            echo 'Please enter the one-time password that has been sent to you via text message at ' . $e->getSmsRecipientMasked();
+        }
+
+        if ($e->hasEmailOption()) {
+            // To do: send '$e->getEmailOtpValue()' to '$e->getEmailRecipient()' via email
+            //   Consider using the 'mail' function, Symfony Mailer, Swiftmailer, PHPMailer, etc., to send the email
+
+            echo 'Please enter the one-time password that has been sent to you via email at ' . $e->getEmailRecipientMasked();
+        }
+    }
+    ```
+
+    You can also check if the user is in the middle of completing two-factor authentification at any time by calling `Auth#isWaitingForSecondFactor`, for example to determine if you need to show an input field for the one-time password (instead of showing the normal login screen again). In this second step of signing in, the user doesn’t need to provide any other information, just the one-time password.
+
+ 1. Call `Auth#provideOneTimePasswordAsSecondFactor` with the one-time password entered by the user to complete the authentification process:
+
+    ```php
+    try {
+        $auth->provideOneTimePasswordAsSecondFactor($_POST['oneTimePassword']);
+
+        echo 'You are now signed in';
+    }
+    catch (\Delight\Auth\InvalidOneTimePasswordException $e) {
+        echo 'Your one-time password has not been correct';
+    }
+    catch (\Delight\Auth\NotLoggedInException $e) {
+        echo 'Please sign in first';
+    }
+    catch (\Delight\Auth\TooManyRequestsException $e) {
+        echo 'Please try again later';
+    }
+    ```
+
+ 1. If the user wants to disable two-factor authentication again, call `Auth#disableTwoFactorViaTotp`, `Auth#disableTwoFactorViaSms` or `Auth#disableTwoFactorViaEmail` to disable it for a specific mode, or `Auth#disableTwoFactor` to disable it for all three modes at once.
+
+    **Note:** You should notify the user whenever a 2FA mode has been disabled, for example via email, or even on multiple separate communication channels.
+
+**Warning:** Two-factor authentication increases the risk that users lock themselves out of their accounts, especially if they forget to properly store their backup codes.
+
 ### Enabling or disabling password resets
 
 While password resets via email are a convenient feature that most users find helpful from time to time, the availability of this feature implies that accounts on your service are only ever as secure as the user’s associated email account.
@@ -825,7 +1066,7 @@ for the correct default option in your user interface. You don’t need to check
 
 ### Throttling or rate limiting
 
-All methods provided by this library are *automatically* protected against excessive numbers of requests from clients.
+All methods provided by this library are *automatically* protected against excessive numbers of requests from clients. If the need arises, you can (temporarily) disable this protection using the [`$throttling` parameter](#creating-a-new-instance) passed to the constructor.
 
 If you would like to throttle or rate limit *external* features or methods as well, e.g. those in your own code, you can make use of the built-in helper method for throttling and rate limiting:
 
@@ -856,6 +1097,8 @@ Allowing short bursts of activity during peak demand is possible by specifying a
 
 In some cases, you may just want to *simulate* the throttling or rate limiting. This lets you check whether an action would be permitted without actually modifying the activity tracker. To do so, simply pass `true` as the fifth argument.
 
+**Note:** When you disable throttling on the instance (using the [`$throttling` parameter](#creating-a-new-instance) passed to the constructor), this turns off both the automatic internal protection and the effect of any calls to `Auth#throttle` in your own application code – unless you also set the optional `$force` parameter to `true` in specific `Auth#throttle` calls.
+
 ### Administration (managing users)
 
 The administrative interface is available via `$auth->admin()`. You can call various method on this interface, as documented below.
@@ -1111,7 +1354,7 @@ is the general (mandatory) session cookie. The second (optional) cookie is only
 
 You can rename the session cookie used by this library through one of the following means, in order of recommendation:
 
- * In the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`), find the line with the `session.name` directive and change its value to something like `session_v1`, as in:
+ * In the [PHP configuration](https://www.php.net/manual/configuration.file.php) (`php.ini`), find the line with the `session.name` directive and change its value to something like `session_v1`, as in:
 
    ```
    session.name = session_v1
@@ -1123,7 +1366,7 @@ You can rename the session cookie used by this library through one of the follow
    \ini_set('session.name', 'session_v1');
    ```
 
-   For this to work, `session.auto_start` must be set to `0` in the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`).
+   For this to work, `session.auto_start` must be set to `0` in the [PHP configuration](https://www.php.net/manual/configuration.file.php) (`php.ini`).
 
  * As early as possible in your application, and before you create the `Auth` instance, call `\session_name` with an argument like `session_v1`, as in:
 
@@ -1131,7 +1374,7 @@ You can rename the session cookie used by this library through one of the follow
    \session_name('session_v1');
    ```
 
-   For this to work, `session.auto_start` must be set to `0` in the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`).
+   For this to work, `session.auto_start` must be set to `0` in the [PHP configuration](https://www.php.net/manual/configuration.file.php) (`php.ini`).
 
 The name of the cookie for [persistent logins](#keeping-the-user-logged-in) will change as well – automatically – following your change of the session cookie’s name.
 
@@ -1145,7 +1388,7 @@ Whatever set of subdomains you choose, you should set the cookie’s attribute t
 
 You can change the attribute through one of the following means, in order of recommendation:
 
- * In the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`), find the line with the `session.cookie_domain` directive and change its value as desired, e.g.:
+ * In the [PHP configuration](https://www.php.net/manual/configuration.file.php) (`php.ini`), find the line with the `session.cookie_domain` directive and change its value as desired, e.g.:
 
    ```
    session.cookie_domain = example.com
@@ -1157,7 +1400,7 @@ You can change the attribute through one of the following means, in order of rec
    \ini_set('session.cookie_domain', 'example.com');
    ```
 
-   For this to work, `session.auto_start` must be set to `0` in the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`).
+   For this to work, `session.auto_start` must be set to `0` in the [PHP configuration](https://www.php.net/manual/configuration.file.php) (`php.ini`).
 
 #### Restricting the path where cookies are available
 
@@ -1167,7 +1410,7 @@ In most cases, you’ll want to make cookies available for all paths, i.e. any d
 
 You can change the attribute through one of the following means, in order of recommendation:
 
- * In the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`), find the line with the `session.cookie_path` directive and change its value as desired, e.g.:
+ * In the [PHP configuration](https://www.php.net/manual/configuration.file.php) (`php.ini`), find the line with the `session.cookie_path` directive and change its value as desired, e.g.:
 
    ```
    session.cookie_path = /
@@ -1179,7 +1422,7 @@ You can change the attribute through one of the following means, in order of rec
    \ini_set('session.cookie_path', '/');
    ```
 
-   For this to work, `session.auto_start` must be set to `0` in the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`).
+   For this to work, `session.auto_start` must be set to `0` in the [PHP configuration](https://www.php.net/manual/configuration.file.php) (`php.ini`).
 
 #### Controlling client-side script access to cookies
 
@@ -1189,7 +1432,7 @@ Thus, you should always set `httponly` to `1`, except for the rare cases where y
 
 You can change the attribute through one of the following means, in order of recommendation:
 
- * In the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`), find the line with the `session.cookie_httponly` directive and change its value as desired, e.g.:
+ * In the [PHP configuration](https://www.php.net/manual/configuration.file.php) (`php.ini`), find the line with the `session.cookie_httponly` directive and change its value as desired, e.g.:
 
    ```
    session.cookie_httponly = 1
@@ -1201,7 +1444,7 @@ You can change the attribute through one of the following means, in order of rec
    \ini_set('session.cookie_httponly', 1);
    ```
 
-   For this to work, `session.auto_start` must be set to `0` in the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`).
+   For this to work, `session.auto_start` must be set to `0` in the [PHP configuration](https://www.php.net/manual/configuration.file.php) (`php.ini`).
 
 #### Configuring transport security for cookies
 
@@ -1211,7 +1454,7 @@ Obviously, this solely depends on whether you are able to serve *all* pages excl
 
 You can change the attribute through one of the following means, in order of recommendation:
 
- * In the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`), find the line with the `session.cookie_secure` directive and change its value as desired, e.g.:
+ * In the [PHP configuration](https://www.php.net/manual/configuration.file.php) (`php.ini`), find the line with the `session.cookie_secure` directive and change its value as desired, e.g.:
 
    ```
    session.cookie_secure = 1
@@ -1223,7 +1466,7 @@ You can change the attribute through one of the following means, in order of rec
    \ini_set('session.cookie_secure', 1);
    ```
 
-   For this to work, `session.auto_start` must be set to `0` in the [PHP configuration](http://php.net/manual/en/configuration.file.php) (`php.ini`).
+   For this to work, `session.auto_start` must be set to `0` in the [PHP configuration](https://www.php.net/manual/configuration.file.php) (`php.ini`).
 
 ### Utilities
 
@@ -1248,11 +1491,15 @@ For detailed information on how to read and write session data conveniently, ple
 
 ### What about password hashing?
 
-Any password or authentication token is automatically hashed using the [“bcrypt”](https://en.wikipedia.org/wiki/Bcrypt) function, which is based on the [“Blowfish” cipher](https://en.wikipedia.org/wiki/Blowfish_(cipher)) and (still) considered one of the strongest password hash functions today. “bcrypt” is used with 1,024 iterations, i.e. a “cost” factor of 10. A random [“salt”](https://en.wikipedia.org/wiki/Salt_(cryptography)) is applied automatically as well.
+Any password or authentication token is automatically hashed using a computationally expensive hash such as the [“bcrypt”](https://en.wikipedia.org/wiki/Bcrypt) function, which is based on the [“Blowfish” cipher](https://en.wikipedia.org/wiki/Blowfish_(cipher)), or newer hash functions that are considered to be even stronger, as available. A random [“salt”](https://en.wikipedia.org/wiki/Salt_(cryptography)) is applied automatically as well.
 
-You can verify this configuration by looking at the hashes in your database table `users`. If the above is true with your setup, all password hashes in your `users` table should start with the prefix `$2$10$`, `$2a$10$` or `$2y$10$`.
+When new algorithms (such as [Argon2](https://en.wikipedia.org/wiki/Argon2)) are introduced, this library automatically takes care of “upgrading” your existing password hashes whenever a user signs in or changes their password.
 
-When new algorithms (such as [Argon2](https://en.wikipedia.org/wiki/Argon2)) may be introduced in the future, this library will automatically take care of “upgrading” your existing password hashes whenever a user signs in or changes their password.
+### Are there any limitations for passwords?
+
+ * Passwords must *not* be empty.
+ * Passwords can have a *maximum length* of 2048 bytes, i.e. 2048 ASCII characters or 512–2048 UTF-8 characters.
+ * Any text, with arbitrary bytes, including null bytes, can be used in a password.
 
 ### How can I implement custom password requirements?
 

composer.json

@@ -6,7 +6,8 @@
 		"ext-openssl": "*",
 		"delight-im/base64": "^1.0",
 		"delight-im/cookie": "^3.1",
-		"delight-im/db": "^1.3"
+		"delight-im/db": "^1.5",
+		"delight-im/otp": "^1.0"
 	},
 	"type": "library",
 	"keywords": [ "auth", "authentication", "login", "security" ],

composer.lock

@@ -1,10 +1,10 @@
 {
     "_readme": [
         "This file locks the dependencies of your project to a known state",
-        "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file",
+        "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "e4acd9e4ba13c4d0692f07a03a454859",
+    "content-hash": "2467e7d9c74e16240dd81cd23d33a880",
     "packages": [
         {
             "name": "delight-im/base64",
@@ -49,16 +49,16 @@
         },
         {
             "name": "delight-im/cookie",
-            "version": "v3.1.0",
+            "version": "v3.4.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/delight-im/PHP-Cookie.git",
-                "reference": "76ef2a21817cf7a034f85fc3f4d4bfc60f873947"
+                "reference": "67065d34272377d63bab0bd58f984f9b228c803f"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/delight-im/PHP-Cookie/zipball/76ef2a21817cf7a034f85fc3f4d4bfc60f873947",
-                "reference": "76ef2a21817cf7a034f85fc3f4d4bfc60f873947",
+                "url": "https://api.github.com/repos/delight-im/PHP-Cookie/zipball/67065d34272377d63bab0bd58f984f9b228c803f",
+                "reference": "67065d34272377d63bab0bd58f984f9b228c803f",
                 "shasum": ""
             },
             "require": {
@@ -86,20 +86,24 @@
                 "samesite",
                 "xss"
             ],
-            "time": "2017-10-18T19:48:59+00:00"
+            "support": {
+                "issues": "https://github.com/delight-im/PHP-Cookie/issues",
+                "source": "https://github.com/delight-im/PHP-Cookie/tree/v3.4.0"
+            },
+            "time": "2020-04-16T11:01:26+00:00"
         },
         {
             "name": "delight-im/db",
-            "version": "v1.3.0",
+            "version": "v1.5.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/delight-im/PHP-DB.git",
-                "reference": "7a03da20b5592fa445c10cd6c7245d51037292c4"
+                "reference": "c613571382fa76359abc6de71d19738d7b7f1d13"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/delight-im/PHP-DB/zipball/7a03da20b5592fa445c10cd6c7245d51037292c4",
-                "reference": "7a03da20b5592fa445c10cd6c7245d51037292c4",
+                "url": "https://api.github.com/repos/delight-im/PHP-DB/zipball/c613571382fa76359abc6de71d19738d7b7f1d13",
+                "reference": "c613571382fa76359abc6de71d19738d7b7f1d13",
                 "shasum": ""
             },
             "require": {
@@ -127,20 +131,24 @@
                 "sql",
                 "sqlite"
             ],
-            "time": "2018-08-28T18:23:01+00:00"
+            "support": {
+                "issues": "https://github.com/delight-im/PHP-DB/issues",
+                "source": "https://github.com/delight-im/PHP-DB/tree/v1.5.0"
+            },
+            "time": "2025-05-26T16:39:50+00:00"
         },
         {
             "name": "delight-im/http",
-            "version": "v2.0.0",
+            "version": "v2.1.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/delight-im/PHP-HTTP.git",
-                "reference": "0a19a72a7eac8b1301aa972fb20cff494ac43e09"
+                "reference": "a5c2c4eae1dd3207f797984e8f64f2d71ed889dd"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/delight-im/PHP-HTTP/zipball/0a19a72a7eac8b1301aa972fb20cff494ac43e09",
-                "reference": "0a19a72a7eac8b1301aa972fb20cff494ac43e09",
+                "url": "https://api.github.com/repos/delight-im/PHP-HTTP/zipball/a5c2c4eae1dd3207f797984e8f64f2d71ed889dd",
+                "reference": "a5c2c4eae1dd3207f797984e8f64f2d71ed889dd",
                 "shasum": ""
             },
             "require": {
@@ -163,7 +171,129 @@
                 "http",
                 "https"
             ],
-            "time": "2016-07-21T15:05:01+00:00"
+            "support": {
+                "issues": "https://github.com/delight-im/PHP-HTTP/issues",
+                "source": "https://github.com/delight-im/PHP-HTTP/tree/v2.1.0"
+            },
+            "time": "2021-10-12T18:52:29+00:00"
+        },
+        {
+            "name": "delight-im/otp",
+            "version": "v1.0.1",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/delight-im/PHP-OTP.git",
+                "reference": "d012342f5ee3430394b568b46a00c412c24f4f4a"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/delight-im/PHP-OTP/zipball/d012342f5ee3430394b568b46a00c412c24f4f4a",
+                "reference": "d012342f5ee3430394b568b46a00c412c24f4f4a",
+                "shasum": ""
+            },
+            "require": {
+                "ext-openssl": "*",
+                "paragonie/constant_time_encoding": "~1.1.0",
+                "php": ">=5.6.0"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "Delight\\Otp\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "description": "One-time password (OTP) implementation for two-factor authentication with TOTP in accordance with RFC 6238 and RFC 4226",
+            "homepage": "https://github.com/delight-im/PHP-OTP",
+            "keywords": [
+                "2fa",
+                "google-authenticator",
+                "hotp",
+                "otp",
+                "rfc-4226",
+                "rfc-6238",
+                "rfc4226",
+                "rfc6238",
+                "tfa",
+                "totp",
+                "two-factor",
+                "two-factor-authentication"
+            ],
+            "support": {
+                "issues": "https://github.com/delight-im/PHP-OTP/issues",
+                "source": "https://github.com/delight-im/PHP-OTP/tree/v1.0.1"
+            },
+            "time": "2023-07-03T08:13:03+00:00"
+        },
+        {
+            "name": "paragonie/constant_time_encoding",
+            "version": "v1.1.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/paragonie/constant_time_encoding.git",
+                "reference": "317718fb438e60151f72b20404f040cb5ae1d494"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/paragonie/constant_time_encoding/zipball/317718fb438e60151f72b20404f040cb5ae1d494",
+                "reference": "317718fb438e60151f72b20404f040cb5ae1d494",
+                "shasum": ""
+            },
+            "require": {
+                "php": "^5.3|^7|^8"
+            },
+            "require-dev": {
+                "paragonie/random_compat": "^1.4|^2",
+                "phpunit/phpunit": ">= 4"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "ParagonIE\\ConstantTime\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Paragon Initiative Enterprises",
+                    "email": "security@paragonie.com",
+                    "homepage": "https://paragonie.com",
+                    "role": "Maintainer"
+                },
+                {
+                    "name": "Steve 'Sc00bz' Thomas",
+                    "email": "steve@tobtu.com",
+                    "homepage": "https://www.tobtu.com",
+                    "role": "Original Developer"
+                }
+            ],
+            "description": "Constant-time Implementations of RFC 4648 Encoding (Base-64, Base-32, Base-16)",
+            "keywords": [
+                "base16",
+                "base32",
+                "base32_decode",
+                "base32_encode",
+                "base64",
+                "base64_decode",
+                "base64_encode",
+                "bin2hex",
+                "encoding",
+                "hex",
+                "hex2bin",
+                "rfc4648"
+            ],
+            "support": {
+                "email": "info@paragonie.com",
+                "issues": "https://github.com/paragonie/constant_time_encoding/issues",
+                "source": "https://github.com/paragonie/constant_time_encoding"
+            },
+            "time": "2022-01-17T05:23:46+00:00"
         }
     ],
     "packages-dev": [],
@@ -176,5 +306,6 @@
         "php": ">=5.6.0",
         "ext-openssl": "*"
     },
-    "platform-dev": []
+    "platform-dev": [],
+    "plugin-api-version": "2.1.0"
 }

src/Administration.php

@@ -12,8 +12,6 @@ use Delight\Db\PdoDatabase;
 use Delight\Db\PdoDsn;
 use Delight\Db\Throwable\Error;
 
-require_once __DIR__ . '/Exceptions.php';
-
 /** Component that can be used for administrative tasks by privileged and authorized users */
 final class Administration extends UserManager {
 
@@ -386,7 +384,7 @@ final class Administration extends UserManager {
 	 */
 	public function changePasswordForUserById($userId, $newPassword) {
 		$userId = (int) $userId;
-		$newPassword = self::validatePassword($newPassword);
+		$newPassword = self::validatePassword($newPassword, true);
 
 		$this->updatePasswordInternal(
 			$userId,

src/AmbiguousUsernameException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class AmbiguousUsernameException extends AuthException {}

src/AttemptCancelledException.php

@@ -0,0 +1,12 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+/** @deprecated */
+class AttemptCancelledException extends AuthException {}

src/AuthError.php

@@ -0,0 +1,12 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+/** Base class for all (unchecked) errors */
+class AuthError extends \Exception {}

src/AuthException.php

@@ -0,0 +1,12 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+/** Base class for all (checked) exceptions */
+class AuthException extends \Exception {}

src/ConfirmationRequestNotFound.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class ConfirmationRequestNotFound extends AuthException {}

src/DatabaseError.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class DatabaseError extends AuthError {}

src/DuplicateUsernameException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class DuplicateUsernameException extends AuthException {}

src/EmailAddress.php

@@ -0,0 +1,59 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+final class EmailAddress {
+
+	/**
+	 * Returns a masked version of the given email address that can be used for privacy reasons and data safety reasons
+	 *
+	 * @param string $emailAddress
+	 * @return string
+	 */
+	public static function mask($emailAddress) {
+		if (empty($emailAddress)) {
+			return $emailAddress;
+		}
+
+		// split the email address into local part and domain part and then split the domain part into individual segments
+		$emailAddress = \trim((string) $emailAddress);
+		$partsSeparatedByAtSymbol = \explode('@', $emailAddress);
+		$domainPart = \array_pop($partsSeparatedByAtSymbol);
+		$localPart = \implode('@', $partsSeparatedByAtSymbol);
+		$localPart = \str_replace('"', '', $localPart);
+		$localPart = \str_replace("'", "", $localPart);
+		$parts = \explode('.', $domainPart);
+		\array_unshift($parts, $localPart);
+
+		// mask the individual parts of the address one by one
+		for ($i = 0; $i < \count($parts); $i++) {
+			$parts[$i] = \trim($parts[$i]);
+
+			if (\mb_strlen($parts[$i]) >= 5) {
+				$parts[$i] = \mb_substr($parts[$i], 0, 1) . '***' . \mb_substr($parts[$i], -1);
+			}
+			elseif (\mb_strlen($parts[$i]) === 4) {
+				$parts[$i] = \mb_substr($parts[$i], 0, 1) . '**' . \mb_substr($parts[$i], -1);
+			}
+			elseif (\mb_strlen($parts[$i]) === 3 && $i <= 1) {
+				$parts[$i] = \mb_substr($parts[$i], 0, 1) . '*' . \mb_substr($parts[$i], -1);
+			}
+			elseif (\mb_strlen($parts[$i]) === 2 && $i <= 1) {
+				$parts[$i] = \mb_substr($parts[$i], 0, 1) . '*';
+			}
+			elseif (\mb_strlen($parts[$i]) === 1 && $i <= 1) {
+				$parts[$i] = '*';
+			}
+		}
+
+		// join the individual parts back together
+		return \array_shift($parts) . '@' . \implode('.', $parts);
+	}
+
+}

src/EmailNotVerifiedException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class EmailNotVerifiedException extends AuthException {}

src/EmailOrUsernameRequiredError.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class EmailOrUsernameRequiredError extends AuthError {}

src/Exceptions.php

@@ -1,51 +0,0 @@
-<?php
-
-/*
- * PHP-Auth (https://github.com/delight-im/PHP-Auth)
- * Copyright (c) delight.im (https://www.delight.im/)
- * Licensed under the MIT License (https://opensource.org/licenses/MIT)
- */
-
-namespace Delight\Auth;
-
-class AuthException extends \Exception {}
-
-class UnknownIdException extends AuthException {}
-
-class InvalidEmailException extends AuthException {}
-
-class UnknownUsernameException extends AuthException {}
-
-class InvalidPasswordException extends AuthException {}
-
-class EmailNotVerifiedException extends AuthException {}
-
-class UserAlreadyExistsException extends AuthException {}
-
-class NotLoggedInException extends AuthException {}
-
-class InvalidSelectorTokenPairException extends AuthException {}
-
-class TokenExpiredException extends AuthException {}
-
-class TooManyRequestsException extends AuthException {}
-
-class DuplicateUsernameException extends AuthException {}
-
-class AmbiguousUsernameException extends AuthException {}
-
-class AttemptCancelledException extends AuthException {}
-
-class ResetDisabledException extends AuthException {}
-
-class ConfirmationRequestNotFound extends AuthException {}
-
-class AuthError extends \Exception {}
-
-class DatabaseError extends AuthError {}
-
-class MissingCallbackError extends AuthError {}
-
-class HeadersAlreadySentError extends AuthError {}
-
-class EmailOrUsernameRequiredError extends AuthError {}

src/HeadersAlreadySentError.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class HeadersAlreadySentError extends AuthError {}

src/InvalidEmailException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class InvalidEmailException extends AuthException {}

src/InvalidOneTimePasswordException.php

@@ -0,0 +1,12 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+/** Exception that is thrown when a one-time password (OTP) provided by the user is not valid */
+class InvalidOneTimePasswordException extends AuthException {}

src/InvalidPasswordException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class InvalidPasswordException extends AuthException {}

src/InvalidPhoneNumberException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class InvalidPhoneNumberException extends AuthException {}

src/InvalidSelectorTokenPairException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class InvalidSelectorTokenPairException extends AuthException {}

src/InvalidStateError.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class InvalidStateError extends AuthError {}

src/IpAddress.php

@@ -0,0 +1,111 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+final class IpAddress {
+
+	const IPV4_LENGTH_BITS = 32;
+	const IPV4_LENGTH_BYTES = 4;
+	const IPV6_LENGTH_BITS = 128;
+	const IPV6_LENGTH_BYTES = 16;
+
+	/**
+	 * Returns a masked version of the given IP address (IPv4 or IPv6) that can be used for privacy reasons and data safety reasons
+	 *
+	 * For IPv4-mapped IPv6 addresses, only the embedded IPv4 portion is masked (like an IPv4 address) and returned as IPv6 again
+	 *
+	 * @param string $ip the IP address (IPv4 or IPv6), e.g. '192.0.2.128' or '2001:db8:be4d:fbe0:c0af:b298:1242:33e4'
+	 * @param int|null $maskBitsIpv4 (optional) the number of bits to zero out from the right in IPv4 addresses
+	 * @param int|null $maskBitsIpv6 (optional) the number of bits to zero out from the right in IPv6 addresses
+	 * @param bool|null $includePrefixLength (optional) whether to include the prefix length (e.g. '/24' at the end) or not
+	 * @return string|null
+	 */
+	public static function mask($ip, $maskBitsIpv4 = null, $maskBitsIpv6 = null, $includePrefixLength = null) {
+		$maskBitsIpv4 = isset($maskBitsIpv4) ? \max(0, \min(self::IPV4_LENGTH_BITS, (int) $maskBitsIpv4)) : 8;
+		$maskBitsIpv6 = isset($maskBitsIpv6) ? \max(0, \min(self::IPV6_LENGTH_BITS, (int) $maskBitsIpv6)) : 80;
+		$packedIp = @\inet_pton($ip);
+
+		if ($packedIp === false) {
+			return null;
+		}
+
+		$ipLengthInBytes = \strlen($packedIp);
+
+		// for IPv4 addresses
+		if ($ipLengthInBytes === self::IPV4_LENGTH_BYTES) {
+			if ($maskBitsIpv4 === 0) {
+				return $ip;
+			}
+			elseif ($maskBitsIpv4 === self::IPV4_LENGTH_BITS) {
+				return '0.0.0.0';
+			}
+
+			// unpack to a 32-bit unsigned integer in network byte order
+			$ipInt32 = unpack('N', $packedIp)[1];
+
+			// create a bitmask (like 0xFFFFFF00 to mask 8 bits or 0xFFFF0000 to mask 16 bits) using a bitwise right shift and then left shift
+			$mask = (0xFFFFFFFF >> $maskBitsIpv4) << $maskBitsIpv4;
+
+			$packedIp = \pack('N', $ipInt32 & $mask);
+
+			$prefixLength = self::IPV4_LENGTH_BITS - $maskBitsIpv4;
+		}
+		// for IPv6 addresses
+		elseif ($ipLengthInBytes === self::IPV6_LENGTH_BYTES) {
+			// if the IP address is an IPv4-mapped IPv6 address
+			if (\substr($packedIp, 0, 12) === "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff") {
+				// the last 4 bytes are the IPv4 address, so mask bits as per IPv4 option
+				$maskBitsIpv6 = $maskBitsIpv4;
+			}
+
+			if ($maskBitsIpv6 === 0) {
+				return $ip;
+			}
+			elseif ($maskBitsIpv6 === self::IPV6_LENGTH_BITS) {
+				return '::';
+			}
+
+			$maskBytesIpv6 = (int) \ceil($maskBitsIpv6 / 8);
+			$maskBitsInFirstByteIpv6 = $maskBitsIpv6 % 8;
+
+			// work byte by byte for IPv6 due to lack of 128-bit integers
+
+			for ($i = 0; $i < $maskBytesIpv6; $i++) {
+				// start from the rightmost byte
+				$byteIndex = $ipLengthInBytes - $i - 1;
+
+				// if we are at the first byte and it should only be masked partially (i.e. masking 1-7 bits there)
+				if ($i === ($maskBytesIpv6 - 1) && $maskBitsInFirstByteIpv6 !== 0) {
+					$firstByteMask = (0xFF >> $maskBitsInFirstByteIpv6) << $maskBitsInFirstByteIpv6;
+					$packedIp[$byteIndex] = \chr(\ord($packedIp[$byteIndex]) & $firstByteMask);
+				}
+				// when masking a full first byte or any byte after the first byte
+				else {
+					 $packedIp[$byteIndex] = "\x00";
+				}
+			}
+
+			$prefixLength = self::IPV6_LENGTH_BITS - $maskBitsIpv6;
+		}
+		// for addresses with invalid lengths in bytes
+		else {
+			return null;
+		}
+
+		$ip = \inet_ntop($packedIp);
+
+		if ($includePrefixLength) {
+			return $ip . '/' . $prefixLength;
+		}
+		else {
+			return $ip;
+		}
+	}
+
+}

src/MissingCallbackError.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class MissingCallbackError extends AuthError {}

src/NotLoggedInException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class NotLoggedInException extends AuthException {}

src/PasswordHash.php

@@ -0,0 +1,96 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+final class PasswordHash {
+
+	const HASH_ALGORITHM_IDENTIFIER = \PASSWORD_DEFAULT;
+	const PEPPER_HMAC_SHA_512_PREHASH = 'bec95beffb3afd078df7cbfd4c4617ba214ac4641a157c1ca64106e7544c9fb4cef6e99b0a8f0b63e96328c09943ce96b9b8899ff54fa7ea57b622675442dbbf';
+	const PREFIX_BCRYPT_WITH_HMAC_SHA_512_PREHASH = '$pa01';
+	const PREFIX_LENGTH = 5;
+
+	/**
+	 * Creates a computationally expensive hash from a password
+	 *
+	 * @param string $passwordText
+	 * @return string|bool
+	 */
+	public static function from($passwordText) {
+		// if the bcrypt algorithm will be used for computationally expensive hashing
+		if (self::HASH_ALGORITHM_IDENTIFIER === \PASSWORD_BCRYPT || self::HASH_ALGORITHM_IDENTIFIER === null) {
+			// pre-hash the password to support passwords with more than 72 bytes (i.e. more than 18-72 characters) and passwords containing null bytes
+			$passwordText = self::prehash($passwordText);
+			// use 72 out of the ~88 bytes from the prehash in bcrypt later and denote this in a custom hash prefix
+			$outputPrefix = self::PREFIX_BCRYPT_WITH_HMAC_SHA_512_PREHASH;
+		}
+		else {
+			$outputPrefix = '';
+		}
+
+		return $outputPrefix . \password_hash($passwordText, self::HASH_ALGORITHM_IDENTIFIER);
+	}
+
+	/**
+	 * Verifies whether a password matches a computationally expensive hash
+	 *
+	 * @param string $passwordText
+	 * @param string $expectedHash
+	 * @return bool
+	 */
+	public static function verify($passwordText, $expectedHash) {
+		// if the expected hash has a custom prefix that indicates a prehash has been used
+		if (\substr($expectedHash, 0, self::PREFIX_LENGTH) === self::PREFIX_BCRYPT_WITH_HMAC_SHA_512_PREHASH) {
+			// pre-hash the password here as well to allow for a possible match
+			$passwordText = self::prehash($passwordText);
+			// and drop the custom prefix from the expected hash
+			$expectedHash = \substr($expectedHash, self::PREFIX_LENGTH);
+		}
+
+		return \password_verify($passwordText, $expectedHash);
+	}
+
+	/**
+	 * Checks whether a computationally expensive hash needs to be updated to match a desired algorithm and set of options
+	 *
+	 * @param string $existingHash
+	 * @return bool
+	 */
+	public static function needsRehash($existingHash) {
+		// if the existing hash has a custom prefix indicating that a prehash has been used
+		if (\substr($existingHash, 0, self::PREFIX_LENGTH) === self::PREFIX_BCRYPT_WITH_HMAC_SHA_512_PREHASH) {
+			// drop that custom prefix from the existing hash
+			$existingHash = \substr($existingHash, self::PREFIX_LENGTH);
+		}
+		/*// if the existing hash has no custom prefix denoting a prehash
+		else {
+			// if the existing hash used the bcrypt algorithm
+			if (\preg_match('/^\$2[abxy]?\$/', $existingHash) === 1) {
+				// the prehash needs to be applied
+				return true;
+			}
+		}*/
+
+		return \password_needs_rehash($existingHash, self::HASH_ALGORITHM_IDENTIFIER);
+	}
+
+	private static function prehash($passwordText) {
+		$pepperBinary = \hex2bin(self::PEPPER_HMAC_SHA_512_PREHASH);
+
+		// do not just use SHA-512 but apply an HMAC with a (semi-public) pepper to avoid breach correlation or "password shucking"
+		$hmacBinary = \hash_hmac('sha512', $passwordText, $pepperBinary, true);
+
+		if (empty($hmacBinary)) {
+			throw new AuthError('Could not generate HMAC');
+		}
+
+		// encode the prehash using Base64 to avoid passing null bytes to the main hash function later (which could truncate the input)
+		return \base64_encode($hmacBinary);
+	}
+
+}

src/PhoneNumber.php

@@ -0,0 +1,67 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+final class PhoneNumber {
+
+	/**
+	 * Returns a masked version of the given phone number that can be used for privacy reasons and data safety reasons
+	 *
+	 * @param string $phoneNumber
+	 * @return string
+	 */
+	public static function mask($phoneNumber) {
+		if (empty($phoneNumber)) {
+			return '';
+		}
+
+		$phoneNumber = \preg_replace('/[^0-9A-Za-z+]+/', '', $phoneNumber);
+
+		if (empty($phoneNumber)) {
+			return '';
+		}
+
+		$hasLeadingPlus = \mb_substr($phoneNumber, 0, 1) === '+';
+
+		if ($hasLeadingPlus) {
+			$phoneNumber = \mb_substr($phoneNumber, 1);
+		}
+
+		$significantCharsLength = \mb_strlen($phoneNumber);
+
+		if ($significantCharsLength >= 7) {
+			$phoneNumber = \mb_substr($phoneNumber, 0, 2) . '***' . \mb_substr($phoneNumber, -2);
+		}
+		elseif ($significantCharsLength === 6) {
+			$phoneNumber = \mb_substr($phoneNumber, 0, 2) . '**' . \mb_substr($phoneNumber, -2);
+		}
+		elseif ($significantCharsLength === 5) {
+			$phoneNumber = \mb_substr($phoneNumber, 0, 1) . '**' . \mb_substr($phoneNumber, -2);
+		}
+		elseif ($significantCharsLength === 4) {
+			$phoneNumber = \mb_substr($phoneNumber, 0, 1) . '**' . \mb_substr($phoneNumber, -1);
+		}
+		elseif ($significantCharsLength === 3) {
+			$phoneNumber = '**' . \mb_substr($phoneNumber, -1);
+		}
+		elseif ($significantCharsLength === 2) {
+			$phoneNumber = '**';
+		}
+		else {
+			$phoneNumber = '*';
+		}
+
+		if ($hasLeadingPlus) {
+			$phoneNumber = '+' . $phoneNumber;
+		}
+
+		return $phoneNumber;
+	}
+
+}

src/ResetDisabledException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class ResetDisabledException extends AuthException {}

src/SecondFactorRequiredException.php

@@ -0,0 +1,74 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+/** Exception that is thrown when a first factor has been successfully provided for authentification but a second one is still required */
+class SecondFactorRequiredException extends AuthException {
+
+	protected $totp;
+	protected $smsRecipient;
+	protected $smsRecipientMasked;
+	protected $smsOtpValue;
+	protected $emailRecipient;
+	protected $emailRecipientMasked;
+	protected $emailOtpValue;
+
+	public function hasTotpOption() {
+		return !empty($this->totp);
+	}
+
+	public function hasSmsOption() {
+		return !empty($this->smsRecipient) && !empty($this->smsOtpValue);
+	}
+
+	public function getSmsRecipient() {
+		return $this->smsRecipient;
+	}
+
+	public function getSmsRecipientMasked() {
+		return $this->smsRecipientMasked;
+	}
+
+	public function getSmsOtpValue() {
+		return $this->smsOtpValue;
+	}
+
+	public function hasEmailOption() {
+		return !empty($this->emailRecipient) && !empty($this->emailOtpValue);
+	}
+
+	public function getEmailRecipient() {
+		return $this->emailRecipient;
+	}
+
+	public function getEmailRecipientMasked() {
+		return $this->emailRecipientMasked;
+	}
+
+	public function getEmailOtpValue() {
+		return $this->emailOtpValue;
+	}
+
+	public function addTotpOption() {
+		$this->totp = true;
+	}
+
+	public function addSmsOption($otpValue, $recipient, $recipientMasked = null) {
+		$this->smsOtpValue = !empty($otpValue) ? (string) $otpValue : null;
+		$this->smsRecipient = !empty($recipient) ? (string) $recipient : null;
+		$this->smsRecipientMasked = !empty($recipientMasked) ? (string) $recipientMasked : null;
+	}
+
+	public function addEmailOption($otpValue, $recipient, $recipientMasked = null) {
+		$this->emailOtpValue = !empty($otpValue) ? (string) $otpValue : null;
+		$this->emailRecipient = !empty($recipient) ? (string) $recipient : null;
+		$this->emailRecipientMasked = !empty($recipientMasked) ? (string) $recipientMasked : null;
+	}
+
+}

src/TokenExpiredException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class TokenExpiredException extends AuthException {}

src/TokenHash.php

@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+final class TokenHash {
+
+	const HASH_ALGORITHM_IDENTIFIER = \PASSWORD_DEFAULT;
+
+	/**
+	 * Creates a computationally expensive hash from a token
+	 *
+	 * @param string $tokenText
+	 * @return string|bool
+	 */
+	public static function from($tokenText) {
+		return \password_hash($tokenText, self::HASH_ALGORITHM_IDENTIFIER);
+	}
+
+	/**
+	 * Verifies whether a token matches a computationally expensive hash
+	 *
+	 * @param string $tokenText
+	 * @param string $expectedHash
+	 * @return bool
+	 */
+	public static function verify($tokenText, $expectedHash) {
+		return \password_verify($tokenText, $expectedHash);
+	}
+
+	/**
+	 * Checks whether a computationally expensive hash needs to be updated to match a desired algorithm and set of options
+	 *
+	 * @param string $existingHash
+	 * @return bool
+	 */
+	public static function needsRehash($existingHash) {
+		return \password_needs_rehash($existingHash, self::HASH_ALGORITHM_IDENTIFIER);
+	}
+
+}

src/TooManyRequestsException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class TooManyRequestsException extends AuthException {}

src/TwoFactorMechanismAlreadyEnabledException.php

@@ -0,0 +1,12 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+/** Exception that is thrown when a given mechanism for two-factor authentification has already been enabled */
+class TwoFactorMechanismAlreadyEnabledException extends AuthException {}

src/TwoFactorMechanismNotInitializedException.php

@@ -0,0 +1,12 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+/** Exception that is thrown when a given mechanism for two-factor authentification has not been initialized yet or the prior initialization is not valid anymore */
+class TwoFactorMechanismNotInitializedException extends AuthException {}

src/UnknownIdException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class UnknownIdException extends AuthException {}

src/UnknownUsernameException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class UnknownUsernameException extends AuthException {}

src/UserAlreadyExistsException.php

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * PHP-Auth (https://github.com/delight-im/PHP-Auth)
+ * Copyright (c) delight.im (https://www.delight.im/)
+ * Licensed under the MIT License (https://opensource.org/licenses/MIT)
+ */
+
+namespace Delight\Auth;
+
+class UserAlreadyExistsException extends AuthException {}

src/UserManager.php

@@ -15,8 +15,6 @@ use Delight\Db\PdoDsn;
 use Delight\Db\Throwable\Error;
 use Delight\Db\Throwable\IntegrityConstraintViolationException;
 
-require_once __DIR__ . '/Exceptions.php';
-
 /**
  * Abstract base class for components implementing user management
  *
@@ -42,6 +40,12 @@ abstract class UserManager {
 	const SESSION_FIELD_LAST_RESYNC = 'auth_last_resync';
 	/** @var string session field for the counter that keeps track of forced logouts that need to be performed in the current session */
 	const SESSION_FIELD_FORCE_LOGOUT = 'auth_force_logout';
+	/** @var string session field for the UNIX timestamp in seconds until which the first factor of authentication is considered to be completed and valid */
+	const SESSION_FIELD_AWAITING_2FA_UNTIL = 'auth_awaiting_2fa_until';
+	/** @var string session field for the ID of the user for whom the first factor of authentication has already been completed */
+	const SESSION_FIELD_AWAITING_2FA_USER_ID = 'auth_awaiting_2fa_user_id';
+	/** @var string session field for the desired "remember me" duration that the user originally requested when attempting to sign in */
+	const SESSION_FIELD_AWAITING_2FA_REMEMBER_DURATION = 'auth_awaiting_2fa_remember_duration';
 
 	/** @var PdoDatabase the database connection to operate on */
 	protected $db;
@@ -128,7 +132,7 @@ abstract class UserManager {
 		\ignore_user_abort(true);
 
 		$email = self::validateEmailAddress($email);
-		$password = self::validatePassword($password);
+		$password = self::validatePassword($password, true);
 
 		$username = isset($username) ? \trim($username) : null;
 
@@ -156,7 +160,7 @@ abstract class UserManager {
 			}
 		}
 
-		$password = \password_hash($password, \PASSWORD_DEFAULT);
+		$password = PasswordHash::from($password);
 		$verified = \is_callable($callback) ? 0 : 1;
 
 		try {
@@ -197,7 +201,7 @@ abstract class UserManager {
 	 * @throws AuthError if an internal problem occurred (do *not* catch)
 	 */
 	protected function updatePasswordInternal($userId, $newPassword) {
-		$newPassword = \password_hash($newPassword, \PASSWORD_DEFAULT);
+		$newPassword = PasswordHash::from($newPassword);
 
 		try {
 			$affected = $this->db->update(
@@ -243,6 +247,9 @@ abstract class UserManager {
 		$_SESSION[self::SESSION_FIELD_FORCE_LOGOUT] = (int) $forceLogout;
 		$_SESSION[self::SESSION_FIELD_REMEMBERED] = $remembered;
 		$_SESSION[self::SESSION_FIELD_LAST_RESYNC] = \time();
+		$_SESSION[self::SESSION_FIELD_AWAITING_2FA_UNTIL] = null;
+		$_SESSION[self::SESSION_FIELD_AWAITING_2FA_USER_ID] = null;
+		$_SESSION[self::SESSION_FIELD_AWAITING_2FA_REMEMBER_DURATION] = null;
 	}
 
 	/**
@@ -308,20 +315,28 @@ abstract class UserManager {
 	 * Validates a password
 	 *
 	 * @param string $password the password to validate
+	 * @param bool|null $isNewPassword (optional) whether the password is a new password that the user wants to use
 	 * @return string the sanitized password
 	 * @throws InvalidPasswordException if the password has been invalid
 	 */
-	protected static function validatePassword($password) {
+	protected static function validatePassword($password, $isNewPassword = null) {
 		if (empty($password)) {
 			throw new InvalidPasswordException();
 		}
 
 		$password = \trim($password);
+		$isNewPassword = ($isNewPassword !== null) ? (bool) $isNewPassword : false;
 
 		if (\strlen($password) < 1) {
 			throw new InvalidPasswordException();
 		}
 
+		if ($isNewPassword) {
+			if (\strlen($password) > 2048) {
+				throw new InvalidPasswordException();
+			}
+		}
+
 		return $password;
 	}
 
@@ -344,7 +359,7 @@ abstract class UserManager {
 	protected function createConfirmationRequest($userId, $email, callable $callback) {
 		$selector = self::createRandomString(16);
 		$token = self::createRandomString(16);
-		$tokenHashed = \password_hash($token, \PASSWORD_DEFAULT);
+		$tokenHashed = TokenHash::from($token);
 		$expires = \time() + 60 * 60 * 24;
 
 		try {

tests/index.php

@@ -35,6 +35,14 @@ $db = new \PDO('mysql:dbname=php_auth;host=127.0.0.1;charset=utf8mb4', 'root', '
 
 $auth = new \Delight\Auth\Auth($db);
 
+echo '<!DOCTYPE html>';
+echo '<html>';
+echo '<head>';
+echo '<meta charset="utf-8">';
+echo '<title></title>';
+echo '</head>';
+echo '<body>';
+
 $result = \processRequestData($auth);
 
 \showGeneralForm();
@@ -88,6 +96,37 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 				catch (\Delight\Auth\EmailNotVerifiedException $e) {
 					return 'email address not verified';
 				}
+				catch (\Delight\Auth\SecondFactorRequiredException $e) {
+					$secondFactorOptions = [];
+
+					if ($e->hasTotpOption()) {
+						$secondFactorOptions[] = 'TOTP';
+					}
+					if ($e->hasSmsOption()) {
+						$secondFactorOptions[] = 'SMS (' . $e->getSmsRecipient() . ' / ' . $e->getSmsRecipientMasked() . ') with ' . $e->getSmsOtpValue();
+					}
+					if ($e->hasEmailOption()) {
+						$secondFactorOptions[] = 'email (' . $e->getEmailRecipient() . ' / ' . $e->getEmailRecipientMasked() . ') with ' . $e->getEmailOtpValue();
+					}
+
+					return 'second factor required: ' . \implode(' / ', $secondFactorOptions);
+				}
+				catch (\Delight\Auth\TooManyRequestsException $e) {
+					return 'too many requests';
+				}
+			}
+			else if ($_POST['action'] === 'provideOneTimePasswordAsSecondFactor') {
+				try {
+					$auth->provideOneTimePasswordAsSecondFactor($_POST['otpValue']);
+
+					return 'ok';
+				}
+				catch (\Delight\Auth\InvalidOneTimePasswordException $e) {
+					return 'invalid OTP';
+				}
+				catch (\Delight\Auth\NotLoggedInException $e) {
+					return 'first factor not completed';
+				}
 				catch (\Delight\Auth\TooManyRequestsException $e) {
 					return 'too many requests';
 				}
@@ -167,6 +206,21 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 				catch (\Delight\Auth\UserAlreadyExistsException $e) {
 					return 'email address already exists';
 				}
+				catch (\Delight\Auth\SecondFactorRequiredException $e) {
+					$secondFactorOptions = [];
+
+					if ($e->hasTotpOption()) {
+						$secondFactorOptions[] = 'TOTP';
+					}
+					if ($e->hasSmsOption()) {
+						$secondFactorOptions[] = 'SMS (' . $e->getSmsRecipient() . ' / ' . $e->getSmsRecipientMasked() . ') with ' . $e->getSmsOtpValue();
+					}
+					if ($e->hasEmailOption()) {
+						$secondFactorOptions[] = 'email (' . $e->getEmailRecipient() . ' / ' . $e->getEmailRecipientMasked() . ') with ' . $e->getEmailOtpValue();
+					}
+
+					return 'second factor required: ' . \implode(' / ', $secondFactorOptions);
+				}
 				catch (\Delight\Auth\TooManyRequestsException $e) {
 					return 'too many requests';
 				}
@@ -282,6 +336,21 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 				catch (\Delight\Auth\InvalidPasswordException $e) {
 					return 'invalid password';
 				}
+				catch (\Delight\Auth\SecondFactorRequiredException $e) {
+					$secondFactorOptions = [];
+
+					if ($e->hasTotpOption()) {
+						$secondFactorOptions[] = 'TOTP';
+					}
+					if ($e->hasSmsOption()) {
+						$secondFactorOptions[] = 'SMS (' . $e->getSmsRecipient() . ' / ' . $e->getSmsRecipientMasked() . ') with ' . $e->getSmsOtpValue();
+					}
+					if ($e->hasEmailOption()) {
+						$secondFactorOptions[] = 'email (' . $e->getEmailRecipient() . ' / ' . $e->getEmailRecipientMasked() . ') with ' . $e->getEmailOtpValue();
+					}
+
+					return 'second factor required: ' . \implode(' / ', $secondFactorOptions);
+				}
 				catch (\Delight\Auth\TooManyRequestsException $e) {
 					return 'too many requests';
 				}
@@ -305,6 +374,175 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 					return 'too many requests';
 				}
 			}
+			else if ($_POST['action'] === 'prepareTwoFactorViaTotp') {
+				try {
+					$keyUriAndSecret = $auth->prepareTwoFactorViaTotp($_POST['serviceName']);
+
+					return \implode(' | ', $keyUriAndSecret);
+				}
+				catch (\Delight\Auth\TwoFactorMechanismAlreadyEnabledException $e) {
+					return 'already enabled';
+				}
+				catch (\Delight\Auth\NotLoggedInException $e) {
+					return 'not logged in';
+				}
+				catch (\Delight\Auth\TooManyRequestsException $e) {
+					return 'too many requests';
+				}
+			}
+			else if ($_POST['action'] === 'prepareTwoFactorViaSms') {
+				try {
+					$phoneNumberAndOtpValue = $auth->prepareTwoFactorViaSms($_POST['phoneNumber']);
+
+					return $phoneNumberAndOtpValue[1] . ' -> ' . $phoneNumberAndOtpValue[0];
+				}
+				catch (\Delight\Auth\InvalidPhoneNumberException $e) {
+					return 'invalid phone number';
+				}
+				catch (\Delight\Auth\TwoFactorMechanismAlreadyEnabledException $e) {
+					return 'already enabled';
+				}
+				catch (\Delight\Auth\NotLoggedInException $e) {
+					return 'not logged in';
+				}
+				catch (\Delight\Auth\TooManyRequestsException $e) {
+					return 'too many requests';
+				}
+			}
+			else if ($_POST['action'] === 'prepareTwoFactorViaEmail') {
+				try {
+					$emailAddressAndOtpValue = $auth->prepareTwoFactorViaEmail();
+
+					return $emailAddressAndOtpValue[1] . ' -> ' . $emailAddressAndOtpValue[0];
+				}
+				catch (\Delight\Auth\TwoFactorMechanismAlreadyEnabledException $e) {
+					return 'already enabled';
+				}
+				catch (\Delight\Auth\NotLoggedInException $e) {
+					return 'not logged in';
+				}
+				catch (\Delight\Auth\TooManyRequestsException $e) {
+					return 'too many requests';
+				}
+			}
+			else if ($_POST['action'] === 'enableTwoFactorViaTotp') {
+				try {
+					$recoveryCodes = $auth->enableTwoFactorViaTotp($_POST['otpValue']);
+
+					return \implode(' | ', $recoveryCodes);
+				}
+				catch (\Delight\Auth\InvalidOneTimePasswordException $e) {
+					return 'invalid OTP';
+				}
+				catch (\Delight\Auth\TwoFactorMechanismNotInitializedException $e) {
+					return 'not initialized';
+				}
+				catch (\Delight\Auth\TwoFactorMechanismAlreadyEnabledException $e) {
+					return 'already enabled';
+				}
+				catch (\Delight\Auth\NotLoggedInException $e) {
+					return 'not logged in';
+				}
+				catch (\Delight\Auth\TooManyRequestsException $e) {
+					return 'too many requests';
+				}
+			}
+			else if ($_POST['action'] === 'enableTwoFactorViaSms') {
+				try {
+					$recoveryCodes = $auth->enableTwoFactorViaSms($_POST['otpValue']);
+
+					return \implode(' | ', $recoveryCodes);
+				}
+				catch (\Delight\Auth\InvalidOneTimePasswordException $e) {
+					return 'invalid OTP';
+				}
+				catch (\Delight\Auth\TwoFactorMechanismNotInitializedException $e) {
+					return 'not initialized';
+				}
+				catch (\Delight\Auth\TwoFactorMechanismAlreadyEnabledException $e) {
+					return 'already enabled';
+				}
+				catch (\Delight\Auth\NotLoggedInException $e) {
+					return 'not logged in';
+				}
+				catch (\Delight\Auth\TooManyRequestsException $e) {
+					return 'too many requests';
+				}
+			}
+			else if ($_POST['action'] === 'enableTwoFactorViaEmail') {
+				try {
+					$recoveryCodes = $auth->enableTwoFactorViaEmail($_POST['otpValue']);
+
+					return \implode(' | ', $recoveryCodes);
+				}
+				catch (\Delight\Auth\InvalidOneTimePasswordException $e) {
+					return 'invalid OTP';
+				}
+				catch (\Delight\Auth\TwoFactorMechanismNotInitializedException $e) {
+					return 'not initialized';
+				}
+				catch (\Delight\Auth\TwoFactorMechanismAlreadyEnabledException $e) {
+					return 'already enabled';
+				}
+				catch (\Delight\Auth\NotLoggedInException $e) {
+					return 'not logged in';
+				}
+				catch (\Delight\Auth\TooManyRequestsException $e) {
+					return 'too many requests';
+				}
+			}
+			else if ($_POST['action'] === 'disableTwoFactorViaTotp') {
+				try {
+					$auth->disableTwoFactorViaTotp();
+
+					return 'ok';
+				}
+				catch (\Delight\Auth\NotLoggedInException $e) {
+					return 'not logged in';
+				}
+				catch (\Delight\Auth\TooManyRequestsException $e) {
+					return 'too many requests';
+				}
+			}
+			else if ($_POST['action'] === 'disableTwoFactorViaSms') {
+				try {
+					$auth->disableTwoFactorViaSms();
+
+					return 'ok';
+				}
+				catch (\Delight\Auth\NotLoggedInException $e) {
+					return 'not logged in';
+				}
+				catch (\Delight\Auth\TooManyRequestsException $e) {
+					return 'too many requests';
+				}
+			}
+			else if ($_POST['action'] === 'disableTwoFactorViaEmail') {
+				try {
+					$auth->disableTwoFactorViaEmail();
+
+					return 'ok';
+				}
+				catch (\Delight\Auth\NotLoggedInException $e) {
+					return 'not logged in';
+				}
+				catch (\Delight\Auth\TooManyRequestsException $e) {
+					return 'too many requests';
+				}
+			}
+			else if ($_POST['action'] === 'disableTwoFactor') {
+				try {
+					$auth->disableTwoFactor();
+
+					return 'ok';
+				}
+				catch (\Delight\Auth\NotLoggedInException $e) {
+					return 'not logged in';
+				}
+				catch (\Delight\Auth\TooManyRequestsException $e) {
+					return 'too many requests';
+				}
+			}
 			else if ($_POST['action'] === 'reconfirmPassword') {
 				try {
 					return $auth->reconfirmPassword($_POST['password']) ? 'correct' : 'wrong';
@@ -379,6 +617,22 @@ function processRequestData(\Delight\Auth\Auth $auth) {
 					return 'too many requests';
 				}
 			}
+			else if ($_POST['action'] === 'changeUsername') {
+				try {
+					$auth->changeUsername($_POST['newUsername'], $_POST['requireUnique']);
+
+					return 'ok';
+				}
+				catch (\Delight\Auth\DuplicateUsernameException $e) {
+					return 'username already exists';
+				}
+				catch (\Delight\Auth\NotLoggedInException $e) {
+					return 'not logged in';
+				}
+				catch (\Delight\Auth\TooManyRequestsException $e) {
+					return 'too many requests';
+				}
+			}
 			else if ($_POST['action'] === 'setPasswordResetEnabled') {
 				try {
 					$auth->setPasswordResetEnabled($_POST['enabled'] == 1);
@@ -742,7 +996,22 @@ function showDebugData(\Delight\Auth\Auth $auth, $result) {
 	\var_dump($auth->isRemembered());
 	echo '$auth->getIpAddress()' . "\t\t\t";
 	\var_dump($auth->getIpAddress());
-	echo "\n";
+	echo '$auth->hasTwoFactor()' . "\t\t\t";
+	\var_dump($auth->hasTwoFactor());
+	echo '$auth->hasTwoFactorViaTotp()' . "\t\t";
+	\var_dump($auth->hasTwoFactorViaTotp());
+	echo '$auth->hasTwoFactorViaSms()' . "\t\t";
+	\var_dump($auth->hasTwoFactorViaSms());
+	echo '$auth->hasTwoFactorViaEmail()' . "\t\t";
+	\var_dump($auth->hasTwoFactorViaEmail());
+	echo 'Waiting for 2FA' . "\t\t\t\t";
+	if ($auth->isWaitingForSecondFactor()) {
+		echo 'User #' . ((int) $_SESSION[\Delight\Auth\Auth::SESSION_FIELD_AWAITING_2FA_USER_ID]) . ' (' . ($_SESSION[\Delight\Auth\Auth::SESSION_FIELD_AWAITING_2FA_UNTIL] - \time()) . ' seconds)';
+	}
+	else {
+		echo 'No';
+	}
+	echo "\n\n";
 
 	echo 'Session name' . "\t\t\t\t";
 	\var_dump(\session_name());
@@ -822,6 +1091,16 @@ function showAuthenticatedUserForm(\Delight\Auth\Auth $auth) {
 	echo '<button type="submit">Change email address</button>';
 	echo '</form>';
 
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="changeUsername" />';
+	echo '<input type="text" name="newUsername" placeholder="New username" /> ';
+	echo '<select name="requireUnique" size="1">';
+	echo '<option value="0">Any</option>';
+	echo '<option value="1">Unique</option>';
+	echo '</select> ';
+	echo '<button type="submit">Change username</button>';
+	echo '</form>';
+
 	\showConfirmEmailForm();
 
 	echo '<form action="" method="post" accept-charset="utf-8">';
@@ -833,6 +1112,61 @@ function showAuthenticatedUserForm(\Delight\Auth\Auth $auth) {
 	echo '<button type="submit">Control password resets</button>';
 	echo '</form>';
 
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="prepareTwoFactorViaTotp" />';
+	echo '<input type="text" name="serviceName" placeholder="Service name" value="' . \htmlspecialchars(!empty($_SERVER['SERVER_NAME']) ? (string) $_SERVER['SERVER_NAME'] : (!empty($_SERVER['SERVER_ADDR']) ? (string) $_SERVER['SERVER_ADDR'] : '')) . '" /> ';
+	echo '<button type="submit">Prepare 2FA via TOTP</button>';
+	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="prepareTwoFactorViaSms" />';
+	echo '<input type="text" name="phoneNumber" placeholder="Phone number" /> ';
+	echo '<button type="submit">Prepare 2FA via SMS</button>';
+	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="prepareTwoFactorViaEmail" />';
+	echo '<button type="submit">Prepare 2FA via email</button>';
+	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="enableTwoFactorViaTotp" />';
+	echo '<input type="text" name="otpValue" placeholder="OTP value" /> ';
+	echo '<button type="submit">Enable 2FA via TOTP</button>';
+	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="enableTwoFactorViaSms" />';
+	echo '<input type="text" name="otpValue" placeholder="OTP value" /> ';
+	echo '<button type="submit">Enable 2FA via SMS</button>';
+	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="enableTwoFactorViaEmail" />';
+	echo '<input type="text" name="otpValue" placeholder="OTP value" /> ';
+	echo '<button type="submit">Enable 2FA via email</button>';
+	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="disableTwoFactorViaTotp" />';
+	echo '<button type="submit">Disable 2FA via TOTP</button>';
+	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="disableTwoFactorViaSms" />';
+	echo '<button type="submit">Disable 2FA via SMS</button>';
+	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="disableTwoFactorViaEmail" />';
+	echo '<button type="submit">Disable 2FA via email</button>';
+	echo '</form>';
+
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="disableTwoFactor" />';
+	echo '<button type="submit">Disable 2FA</button>';
+	echo '</form>';
+
 	echo '<form action="" method="post" accept-charset="utf-8">';
 	echo '<input type="hidden" name="action" value="logOut" />';
 	echo '<button type="submit">Log out</button>';
@@ -876,6 +1210,12 @@ function showGuestUserForm() {
 	echo '<button type="submit">Log in with username</button>';
 	echo '</form>';
 
+	echo '<form action="" method="post" accept-charset="utf-8">';
+	echo '<input type="hidden" name="action" value="provideOneTimePasswordAsSecondFactor" />';
+	echo '<input type="text" name="otpValue" placeholder="OTP value" /> ';
+	echo '<button type="submit">Provide OTP</button>';
+	echo '</form>';
+
 	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 address" /> ';
@@ -1084,3 +1424,6 @@ function createRolesOptions() {
 
 	return $out;
 }
+
+echo '</body>';
+echo '</html>';