Auth/PM-5092 - Registration with Email verification - Send Email Verification Endpoint

src/Core/Auth/Models/Api/Request/Accounts/RegisterSendVerificationEmailRequestModel.cs

@@ -0,0 +1,15 @@
+#nullable enable
+using System.ComponentModel.DataAnnotations;
+using Bit.Core.Utilities;
+
+namespace Bit.Core.Auth.Models.Api.Request.Accounts;
+
+public class RegisterSendVerificationEmailRequestModel
+{
+    [StringLength(50)] public string? Name { get; set; }
+    [Required]
+    [StrictEmailAddress]
+    [StringLength(256)]
+    public string Email { get; set; }
+    public bool ReceiveMarketingEmails { get; set; }
+}

src/Core/Auth/Models/Business/Tokenables/RegistrationEmailVerificationTokenable.cs

@@ -0,0 +1,60 @@
+using System.Text.Json.Serialization;
+using Bit.Core.Tokens;
+
+namespace Bit.Core.Auth.Models.Business.Tokenables;
+
+// <summary>
+// This token contains encrypted registration information for new users. The token is sent via email for verification as
+// part of a link to complete the registration process.
+// </summary>
+public class RegistrationEmailVerificationTokenable : ExpiringTokenable
+{
+    public static TimeSpan GetTokenLifetime() => TimeSpan.FromMinutes(15);
+
+    public const string ClearTextPrefix = "BwRegistrationEmailVerificationToken_";
+    public const string DataProtectorPurpose = "RegistrationEmailVerificationTokenDataProtector";
+    public const string TokenIdentifier = "RegistrationEmailVerificationToken";
+
+    public string Identifier { get; set; } = TokenIdentifier;
+
+    public string Name { get; set; }
+    public string Email { get; set; }
+    public bool ReceiveMarketingEmails { get; set; }
+
+    [JsonConstructor]
+    public RegistrationEmailVerificationTokenable()
+    {
+        ExpirationDate = DateTime.UtcNow.Add(GetTokenLifetime());
+    }
+
+    public RegistrationEmailVerificationTokenable(string email, string name = default, bool receiveMarketingEmails = default) : this()
+    {
+        if (string.IsNullOrEmpty(email))
+        {
+            throw new ArgumentNullException(nameof(email));
+        }
+
+        Email = email;
+        Name = name;
+        ReceiveMarketingEmails = receiveMarketingEmails;
+    }
+
+    public bool TokenIsValid(string email, string name = default, bool receiveMarketingEmails = default)
+    {
+        if (Email == default || email == default)
+        {
+            return false;
+        }
+
+        // Note: string.Equals handles nulls without throwing an exception
+        return string.Equals(Name, name, StringComparison.InvariantCultureIgnoreCase) &&
+               Email.Equals(email, StringComparison.InvariantCultureIgnoreCase) &&
+               ReceiveMarketingEmails == receiveMarketingEmails;
+    }
+
+    // Validates deserialized
+    protected override bool TokenIsValid() =>
+        Identifier == TokenIdentifier
+        && !string.IsNullOrWhiteSpace(Email);
+
+}

src/Core/Auth/Models/Mail/RegisterVerifyEmail.cs

@@ -0,0 +1,18 @@
+using Bit.Core.Models.Mail;
+
+namespace Bit.Core.Auth.Models.Mail;
+
+public class RegisterVerifyEmail : BaseMailModel
+{
+    // We must include email in the URL even though it is already in the token so that the
+    // client can use it to create the master key when they set their password.
+    // We also have to include the fromEmail flag so that the client knows the user
+    // is coming to the finish signup page from an email link and not directly from another route in the app.
+    public string Url => string.Format("{0}/finish-signup?token={1}&email={2}&fromEmail=true",
+        WebVaultUrl,
+        Token,
+        Email);
+
+    public string Token { get; set; }
+    public string Email { get; set; }
+}

src/Core/Auth/UserFeatures/Registration/ISendVerificationEmailForRegistrationCommand.cs

@@ -0,0 +1,7 @@
+#nullable enable
+namespace Bit.Core.Auth.UserFeatures.Registration;
+
+public interface ISendVerificationEmailForRegistrationCommand
+{
+    public Task<string?> Run(string email, string? name, bool receiveMarketingEmails);
+}

src/Core/Auth/UserFeatures/Registration/Implementations/SendVerificationEmailForRegistrationCommand.cs

@@ -0,0 +1,85 @@
+#nullable enable
+using Bit.Core.Auth.Models.Business.Tokenables;
+using Bit.Core.Exceptions;
+using Bit.Core.Repositories;
+using Bit.Core.Services;
+using Bit.Core.Settings;
+using Bit.Core.Tokens;
+
+namespace Bit.Core.Auth.UserFeatures.Registration.Implementations;
+
+/// <summary>
+/// If email verification is enabled, this command will send a verification email to the user which will
+///  contain a link to complete the registration process.
+/// If email verification is disabled, this command will return a token that can be used to complete the registration process directly.
+/// </summary>
+public class SendVerificationEmailForRegistrationCommand : ISendVerificationEmailForRegistrationCommand
+{
+
+    private readonly IUserRepository _userRepository;
+    private readonly GlobalSettings _globalSettings;
+    private readonly IMailService _mailService;
+    private readonly IDataProtectorTokenFactory<RegistrationEmailVerificationTokenable> _tokenDataFactory;
+
+    public SendVerificationEmailForRegistrationCommand(
+        IUserRepository userRepository,
+        GlobalSettings globalSettings,
+        IMailService mailService,
+        IDataProtectorTokenFactory<RegistrationEmailVerificationTokenable> tokenDataFactory)
+    {
+        _userRepository = userRepository;
+        _globalSettings = globalSettings;
+        _mailService = mailService;
+        _tokenDataFactory = tokenDataFactory;
+    }
+
+    public async Task<string?> Run(string email, string? name, bool receiveMarketingEmails)
+    {
+        if (string.IsNullOrWhiteSpace(email))
+        {
+            throw new ArgumentNullException(nameof(email));
+        }
+
+        // Check to see if the user already exists
+        var user = await _userRepository.GetByEmailAsync(email);
+        var userExists = user != null;
+
+        if (!_globalSettings.EnableEmailVerification)
+        {
+
+            if (userExists)
+            {
+                // Add delay to prevent timing attacks
+                // Note: sub 140 ms feels responsive to users so we are using 130 ms as it should be long enough
+                // to prevent timing attacks but not too long to be noticeable to the user.
+                await Task.Delay(130);
+                throw new BadRequestException($"Email {email} is already taken");
+            }
+
+            // if user doesn't exist, return a EmailVerificationTokenable in the response body.
+            var token = GenerateToken(email, name, receiveMarketingEmails);
+
+            return token;
+        }
+
+        if (!userExists)
+        {
+            // If the user doesn't exist, create a new EmailVerificationTokenable and send the user
+            // an email with a link to verify their email address
+            var token = GenerateToken(email, name, receiveMarketingEmails);
+            await _mailService.SendRegistrationVerificationEmailAsync(email, token);
+        }
+
+        // Add delay to prevent timing attacks
+        await Task.Delay(130);
+        // User exists but we will return a 200 regardless of whether the email was sent or not; so return null
+        return null;
+    }
+
+    private string GenerateToken(string email, string? name, bool receiveMarketingEmails)
+    {
+        var registrationEmailVerificationTokenable = new RegistrationEmailVerificationTokenable(email, name, receiveMarketingEmails);
+        return _tokenDataFactory.Protect(registrationEmailVerificationTokenable);
+    }
+}
+

src/Core/Auth/UserFeatures/UserServiceCollectionExtensions.cs

@@ -1,5 +1,7 @@
 
 
+using Bit.Core.Auth.UserFeatures.Registration;
+using Bit.Core.Auth.UserFeatures.Registration.Implementations;
 using Bit.Core.Auth.UserFeatures.UserKey;
 using Bit.Core.Auth.UserFeatures.UserKey.Implementations;
 using Bit.Core.Auth.UserFeatures.UserMasterPassword;
@@ -18,6 +20,7 @@ public static void AddUserServices(this IServiceCollection services, IGlobalSett
     {
         services.AddScoped<IUserService, UserService>();
         services.AddUserPasswordCommands();
+        services.AddUserRegistrationCommands();
         services.AddWebAuthnLoginCommands();
     }
 
@@ -31,6 +34,11 @@ private static void AddUserPasswordCommands(this IServiceCollection services)
         services.AddScoped<ISetInitialMasterPasswordCommand, SetInitialMasterPasswordCommand>();
     }
 
+    private static void AddUserRegistrationCommands(this IServiceCollection services)
+    {
+        services.AddScoped<ISendVerificationEmailForRegistrationCommand, SendVerificationEmailForRegistrationCommand>();
+    }
+
     private static void AddWebAuthnLoginCommands(this IServiceCollection services)
     {
         services.AddScoped<IGetWebAuthnLoginCredentialCreateOptionsCommand, GetWebAuthnLoginCredentialCreateOptionsCommand>();

src/Core/MailTemplates/Handlebars/Auth/RegistrationVerifyEmail.html.hbs

@@ -0,0 +1,24 @@
+{{#>FullHtmlLayout}}
+<table width="100%" cellpadding="0" cellspacing="0" style="margin: 0; box-sizing: border-box; color: #333; line-height: 25px; -webkit-font-smoothing: antialiased; -webkit-text-size-adjust: none;">
+    <tr style="margin: 0; box-sizing: border-box; color: #333; line-height: 25px; -webkit-font-smoothing: antialiased; -webkit-text-size-adjust: none;">
+        <td class="content-block" style="font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; box-sizing: border-box; font-size: 16px; color: #333; line-height: 25px; margin: 0; -webkit-font-smoothing: antialiased; padding: 0 0 10px; -webkit-text-size-adjust: none; text-align: left;" valign="top" align="center">
+            Verify your email address below to finish creating your account.
+        </td>
+    </tr>
+    <tr style="margin: 0; box-sizing: border-box; color: #333; line-height: 25px; -webkit-font-smoothing: antialiased; -webkit-text-size-adjust: none;">
+        <td class="content-block last" style="font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; box-sizing: border-box; font-size: 16px; color: #333; line-height: 25px; margin: 0; -webkit-font-smoothing: antialiased; padding: 0; -webkit-text-size-adjust: none; text-align: left;" valign="top" align="center">
+            If you did not request this email from Bitwarden, you can safely ignore it.
+            <br style="margin: 0; box-sizing: border-box; color: #333; line-height: 25px; -webkit-font-smoothing: antialiased; -webkit-text-size-adjust: none;" />
+            <br style="margin: 0; box-sizing: border-box; color: #333; line-height: 25px; -webkit-font-smoothing: antialiased; -webkit-text-size-adjust: none;" />
+        </td>
+    </tr>
+    <tr style="margin: 0; box-sizing: border-box; color: #333; line-height: 25px; -webkit-font-smoothing: antialiased; -webkit-text-size-adjust: none;">
+        <td class="content-block" style="font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; box-sizing: border-box; font-size: 16px; color: #333; line-height: 25px; margin: 0; -webkit-font-smoothing: antialiased; padding: 0 0 10px; -webkit-text-size-adjust: none; text-align: center;" valign="top" align="center">
+            <a href="{{{Url}}}" clicktracking=off target="_blank" style="color: #ffffff; text-decoration: none; text-align: center; cursor: pointer; display: inline-block; border-radius: 5px; background-color: #175DDC; border-color: #175DDC; border-style: solid; border-width: 10px 20px; margin: 0; font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; box-sizing: border-box; font-size: 16px; line-height: 25px; -webkit-font-smoothing: antialiased; -webkit-text-size-adjust: none;">
+                Verify email
+            </a>
+            <br style="margin: 0; box-sizing: border-box; color: #333; line-height: 25px; -webkit-font-smoothing: antialiased; -webkit-text-size-adjust: none;" />
+        </td>
+    </tr>
+</table>
+{{/FullHtmlLayout}}

src/Core/MailTemplates/Handlebars/Auth/RegistrationVerifyEmail.text.hbs

@@ -0,0 +1,8 @@
+{{#>BasicTextLayout}}
+Verify your email address below to finish creating your account.
+
+If you did not request this email from Bitwarden, you can safely ignore it.
+
+{{{Url}}}
+
+{{/BasicTextLayout}}

src/Core/Services/IMailService.cs

@@ -10,6 +10,7 @@ public interface IMailService
 {
     Task SendWelcomeEmailAsync(User user);
     Task SendVerifyEmailEmailAsync(string email, Guid userId, string token);
+    Task SendRegistrationVerificationEmailAsync(string email, string token);
     Task SendVerifyDeleteEmailAsync(string email, Guid userId, string token);
     Task SendChangeEmailAlreadyExistsEmailAsync(string fromEmail, string toEmail);
     Task SendChangeEmailEmailAsync(string newEmailAddress, string token);

src/Core/Services/Implementations/HandlebarsMailService.cs

@@ -53,6 +53,23 @@ public async Task SendVerifyEmailEmailAsync(string email, Guid userId, string to
         await _mailDeliveryService.SendEmailAsync(message);
     }
 
+    public async Task SendRegistrationVerificationEmailAsync(string email, string token)
+    {
+        var message = CreateDefaultMessage("Verify Your Email", email);
+        var model = new RegisterVerifyEmail
+        {
+            Token = WebUtility.UrlEncode(token),
+            Email = email,
+            WebVaultUrl = _globalSettings.BaseServiceUri.VaultWithHash,
+            SiteName = _globalSettings.SiteName
+        };
+        await AddMessageContentAsync(message, "Auth.RegistrationVerifyEmail", model);
+        message.MetaData.Add("SendGridBypassListManagement", true);
+        message.Category = "VerifyEmail";
+        await _mailDeliveryService.SendEmailAsync(message);
+    }
+
+
     public async Task SendVerifyDeleteEmailAsync(string email, Guid userId, string token)
     {
         var message = CreateDefaultMessage("Delete Your Account", email);

src/Core/Services/NoopImplementations/NoopMailService.cs

@@ -18,6 +18,11 @@
         return Task.FromResult(0);
     }
 
+    public Task SendRegistrationVerificationEmailAsync(string email, string hint)
+    {
+        return Task.FromResult(0);
+    }
+
     public Task SendChangeEmailEmailAsync(string newEmailAddress, string token)
     {
         return Task.FromResult(0);

src/Core/Settings/GlobalSettings.cs

@@ -82,6 +82,8 @@ public virtual string LicenseDirectory
     public virtual ILaunchDarklySettings LaunchDarkly { get; set; } = new LaunchDarklySettings();
     public virtual string DevelopmentDirectory { get; set; }
 
+    public virtual bool EnableEmailVerification { get; set; }
+
     public string BuildExternalUri(string explicitValue, string name)
     {
         if (!string.IsNullOrWhiteSpace(explicitValue))
@@ -147,6 +149,7 @@ public BaseServiceUriSettings(GlobalSettings globalSettings)
         public string CloudRegion { get; set; }
         public string Vault { get; set; }
         public string VaultWithHash => $"{Vault}/#";
+
         public string VaultWithHashAndSecretManagerProduct => $"{Vault}/#/sm";
 
         public string Api

src/Core/Tools/Enums/ReferenceEventSource.cs

@@ -10,4 +10,6 @@ public enum ReferenceEventSource
     User,
     [EnumMember(Value = "provider")]
     Provider,
+    [EnumMember(Value = "registrationStart")]
+    RegistrationStart,
 }

src/Core/Tools/Enums/ReferenceEventType.cs

@@ -4,6 +4,8 @@ namespace Bit.Core.Tools.Enums;
 
 public enum ReferenceEventType
 {
+    [EnumMember(Value = "signup-email-submit")]
+    SignupEmailSubmit,
     [EnumMember(Value = "signup")]
     Signup,
     [EnumMember(Value = "upgrade-plan")]

src/Core/Tools/Models/Business/ReferenceEvent.cs

@@ -242,7 +242,7 @@ public ReferenceEvent(ReferenceEventType type, IReferenceable source, ICurrentCo
     /// This value should only be populated when the <see cref="ReferenceEventType"/> is <see cref="ReferenceEventType.Signup"/>. Otherwise,
     /// the value should be <see langword="null" />.
     /// </value>
-    public string SignupInitiationPath { get; set; }
+    public string? SignupInitiationPath { get; set; }
 
     /// <summary>
     /// The upgrade applied to an account. The current plan is listed first,
@@ -253,5 +253,5 @@ public ReferenceEvent(ReferenceEventType type, IReferenceable source, ICurrentCo
     /// <see langword="null"/> when the event was not originated by an application,
     /// or when a downgrade occurred.
     /// </value>
-    public string PlanUpgradePath { get; set; }
+    public string? PlanUpgradePath { get; set; }
 }