enable the user to set a primary (notification) email address (backend)

- specific getters and setters on IUser and implementation
- new notify_email field in provisioning API

Signed-off-by: Arthur Schiwon <blizzz@arthur-schiwon.de>

5 files changed, 132 insertions, 13 deletions

diff --git a/lib/private/Setup.php b/lib/private/Setup.php
index a4873e63aa9..c24d417f8cf 100644
--- a/lib/private/Setup.php
+++ b/lib/private/Setup.php
@@ -439,7 +439,7 @@ class Setup {
 
 			// Set email for admin
 			if (!empty($options['adminemail'])) {
-				$config->setUserValue($user->getUID(), 'settings', 'email', $options['adminemail']);
+				$user->setSystemEMailAddress($options['adminemail']);
 			}
 		}
 
diff --git a/lib/private/User/Manager.php b/lib/private/User/Manager.php
index 1827be61a7a..3e30861f2a4 100644
--- a/lib/private/User/Manager.php
+++ b/lib/private/User/Manager.php
@@ -700,6 +700,7 @@ class Manager extends PublicEmitter implements IUserManager {
 	 * @since 9.1.0
 	 */
 	public function getByEmail($email) {
+		// looking for 'email' only (and not primary_mail) is intentional
 		$userIds = $this->config->getUsersForUserValueCaseInsensitive('settings', 'email', $email);
 
 		$users = array_map(function ($uid) {
diff --git a/lib/private/User/User.php b/lib/private/User/User.php
index f17824f51b9..5fa1272f95c 100644
--- a/lib/private/User/User.php
+++ b/lib/private/User/User.php
@@ -34,10 +34,12 @@
  */
 namespace OC\User;
 
+use InvalidArgumentException;
 use OC\Accounts\AccountManager;
 use OC\Avatar\AvatarManager;
 use OC\Hooks\Emitter;
 use OC_Helper;
+use OCP\Accounts\IAccountManager;
 use OCP\EventDispatcher\IEventDispatcher;
 use OCP\Group\Events\BeforeUserRemovedEvent;
 use OCP\Group\Events\UserRemovedEvent;
@@ -55,6 +57,8 @@ use Symfony\Component\EventDispatcher\EventDispatcherInterface;
 use Symfony\Component\EventDispatcher\GenericEvent;
 
 class User implements IUser {
+	/** @var IAccountManager */
+	protected $accountManager;
 	/** @var string */
 	private $uid;
 
@@ -165,25 +169,62 @@ class User implements IUser {
 	}
 
 	/**
-	 * set the email address of the user
-	 *
-	 * @param string|null $mailAddress
-	 * @return void
-	 * @since 9.0.0
+	 * @inheritDoc
 	 */
 	public function setEMailAddress($mailAddress) {
-		$oldMailAddress = $this->getEMailAddress();
+		$this->setSystemEMailAddress($mailAddress);
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function setSystemEMailAddress(string $mailAddress): void {
+		$oldMailAddress = $this->getSystemEMailAddress();
+
+		if ($mailAddress === '') {
+			$this->config->deleteUserValue($this->uid, 'settings', 'email');
+		} else {
+			$this->config->setUserValue($this->uid, 'settings', 'email', $mailAddress);
+		}
+
+		$primaryAddress = $this->getPrimaryEMailAddress();
+		if ($primaryAddress === $mailAddress) {
+			// on match no dedicated primary settings is necessary
+			$this->setPrimaryEMailAddress('');
+		}
+
 		if ($oldMailAddress !== $mailAddress) {
-			if ($mailAddress === '') {
-				$this->config->deleteUserValue($this->uid, 'settings', 'email');
-			} else {
-				$this->config->setUserValue($this->uid, 'settings', 'email', $mailAddress);
-			}
 			$this->triggerChange('eMailAddress', $mailAddress, $oldMailAddress);
 		}
 	}
 
 	/**
+	 * @inheritDoc
+	 */
+	public function setPrimaryEMailAddress(string $mailAddress): void {
+		if ($mailAddress === '') {
+			$this->config->deleteUserValue($this->uid, 'settings', 'primary_email');
+			return;
+		}
+
+		$this->ensureAccountManager();
+		$account = $this->accountManager->getAccount($this);
+		$property = $account->getPropertyCollection(IAccountManager::COLLECTION_EMAIL)
+			->getPropertyByValue($mailAddress);
+
+		if ($property === null || $property->getLocallyVerified() !== IAccountManager::VERIFIED) {
+			throw new InvalidArgumentException('Only verified emails can be set as primary');
+		}
+		$this->config->setUserValue($this->uid, 'settings', 'primary_email', $mailAddress);
+	}
+
+	private function ensureAccountManager() {
+		if (!$this->accountManager instanceof IAccountManager) {
+			$this->accountManager = \OC::$server->get(IAccountManager::class);
+		}
+	}
+
+	/**
 	 * returns the timestamp of the user's last login or 0 if the user did never
 	 * login
 	 *
@@ -390,10 +431,24 @@ class User implements IUser {
 	 * @since 9.0.0
 	 */
 	public function getEMailAddress() {
+		return $this->getPrimaryEMailAddress() ?? $this->getSystemEMailAddress();
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function getSystemEMailAddress(): ?string {
 		return $this->config->getUserValue($this->uid, 'settings', 'email', null);
 	}
 
 	/**
+	 * @inheritDoc
+	 */
+	public function getPrimaryEMailAddress(): ?string {
+		return $this->config->getUserValue($this->uid, 'settings', 'primary_email', null);
+	}
+
+	/**
 	 * get the users' quota
 	 *
 	 * @return string
diff --git a/lib/public/IUser.php b/lib/public/IUser.php
index 7e75704ed5b..1a1d1e44d8a 100644
--- a/lib/public/IUser.php
+++ b/lib/public/IUser.php
@@ -27,6 +27,8 @@
  */
 namespace OCP;
 
+use InvalidArgumentException;
+
 /**
  * Interface IUser
  *
@@ -157,7 +159,7 @@ interface IUser {
 	public function setEnabled(bool $enabled = true);
 
 	/**
-	 * get the users email address
+	 * get the user's email address
 	 *
 	 * @return string|null
 	 * @since 9.0.0
@@ -165,6 +167,35 @@ interface IUser {
 	public function getEMailAddress();
 
 	/**
+	 * get the user's system email address
+	 *
+	 * The system mail address may be read only and may be set from different
+	 * sources like LDAP, SAML or simply the admin.
+	 *
+	 * Use this getter only when the system address is needed. For picking the
+	 * proper address to e.g. send a mail to, use getEMailAddress().
+	 *
+	 * @return string|null
+	 * @since 23.0.0
+	 */
+	public function getSystemEMailAddress(): ?string;
+
+	/**
+	 * get the user's preferred email address
+	 *
+	 * The primary mail address may be set be the user to specify a different
+	 * email address where mails by Nextcloud are sent to. It is not necessarily
+	 * set.
+	 *
+	 * Use this getter only when the primary address is needed. For picking the
+	 * proper address to e.g. send a mail to, use getEMailAddress().
+	 *
+	 * @return string|null
+	 * @since 23.0.0
+	 */
+	public function getPrimaryEMailAddress(): ?string;
+
+	/**
 	 * get the avatar image if it exists
 	 *
 	 * @param int $size
@@ -184,13 +215,43 @@ interface IUser {
 	/**
 	 * set the email address of the user
 	 *
+	 * It is an alias to setSystemEMailAddress()
+	 *
 	 * @param string|null $mailAddress
 	 * @return void
 	 * @since 9.0.0
+	 * @deprecated 23.0.0 use setSystemEMailAddress() or setPrimaryEMailAddress()
 	 */
 	public function setEMailAddress($mailAddress);
 
 	/**
+	 * Set the system email address of the user
+	 *
+	 * This is supposed to be used when the email is set from different sources
+	 * (i.e. other user backends, admin).
+	 *
+	 * @since 23.0.0
+	 */
+	public function setSystemEMailAddress(string $mailAddress): void;
+
+	/**
+	 * Set the primary email address of the user.
+	 *
+	 * This method should be typically called when the user is changing their
+	 * own primary address and is not allowed to change their system email.
+	 *
+	 * The mail address provided here must be already registered as an
+	 * additional mail in the user account and also be verified locally. Also
+	 * an empty string is allowed to delete this preference.
+	 *
+	 * @throws InvalidArgumentException when the provided email address does not
+	 *                                  satisfy constraints.
+	 *
+	 * @since 23.0.0
+	 */
+	public function setPrimaryEMailAddress(string $mailAddress): void;
+
+	/**
 	 * get the users' quota in human readable form. If a specific quota is not
 	 * set for the user, the default value is returned. If a default setting
 	 * was not set otherwise, it is return as 'none', i.e. quota is not limited.
diff --git a/lib/public/IUserManager.php b/lib/public/IUserManager.php
index c6cad6f0549..e5c220af40c 100644
--- a/lib/public/IUserManager.php
+++ b/lib/public/IUserManager.php
@@ -196,6 +196,8 @@ interface IUserManager {
 	public function callForSeenUsers(\Closure $callback);
 
 	/**
+	 * returns all users having the provided email set as system email address
+	 *
 	 * @param string $email
 	 * @return IUser[]
 	 * @since 9.1.0