From ea7b1208ad84ae6e136e326faf29ba5292f30c8b Mon Sep 17 00:00:00 2001
From: Marco <marco@delight.im>
Date: Thu, 4 Apr 2024 19:39:54 +0200
Subject: [PATCH] Implement 'prepareTwoFactorViaSms' using 'prepareTwoFactor'

---
 src/Auth.php                        | 28 ++++++++++++++++++++++++++++
 src/InvalidPhoneNumberException.php | 11 +++++++++++
 2 files changed, 39 insertions(+)
 create mode 100644 src/InvalidPhoneNumberException.php

diff --git a/src/Auth.php b/src/Auth.php
index bf0b715..cdeaa70 100644
--- a/src/Auth.php
+++ b/src/Auth.php
@@ -1766,6 +1766,34 @@ final class Auth extends UserManager {
 		return $this->prepareTwoFactor(self::TWO_FACTOR_MECHANISM_TOTP, $serviceName, null);
 	}
 
+	/**
+	 * Prepares the setup of two-factor authentification with one-time passwords sent via SMS
+	 *
+	 * After performing this step, a one-time password will have to be delivered to the user via SMS and then be requested from the user for verification
+	 *
+	 * When the user has entered the one-time password from the text message afterwards, call {@see enableTwoFactorViaSms} with that one-time password
+	 *
+	 * @param string $phoneNumber the phone number to send the one-time passwords to
+	 * @return string[] an array with the phone number at index zero and the one-time password to be sent (but not otherwise displayed to the user) at index one
+	 * @throws InvalidPhoneNumberException if no valid phone number has been provided
+	 * @throws TwoFactorMechanismAlreadyEnabledException if this method of two-factor authentification has already been enabled
+	 * @throws NotLoggedInException if the user is not currently signed in
+	 * @throws TooManyRequestsException if the number of allowed attempts/requests has been exceeded
+	 * @throws AuthError if an internal problem occurred (do *not* catch)
+	 */
+	public function prepareTwoFactorViaSms($phoneNumber) {
+		$phoneNumber = !empty($phoneNumber) ? \trim((string) $phoneNumber) : '';
+
+		if (\strlen($phoneNumber) < 3) {
+			throw new InvalidPhoneNumberException();
+		}
+
+		$this->prepareTwoFactor(self::TWO_FACTOR_MECHANISM_SMS, null, $phoneNumber);
+		$otpValue = $this->generateAndStoreRandomOneTimePassword($this->getUserId(), self::TWO_FACTOR_MECHANISM_SMS);
+
+		return [ $phoneNumber, $otpValue ];
+	}
+
 	/**
 	 * Prepares the setup of two-factor authentification via a specified mechanism
 	 *
diff --git a/src/InvalidPhoneNumberException.php b/src/InvalidPhoneNumberException.php
new file mode 100644
index 0000000..6b4d516
--- /dev/null
+++ b/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 {}