[PM-21918] update send api models to support new email field

src/Api/Tools/Models/Request/SendRequestModel.cs

@@ -7,35 +7,114 @@
 using Bit.Core.Tools.Services;
 using Bit.Core.Utilities;
 
+using static System.StringSplitOptions;
+
 namespace Bit.Api.Tools.Models.Request;
 
+/// <summary>
+/// A send request issued by a Bitwarden client
+/// </summary>
 public class SendRequestModel
 {
+    /// <summary>
+    /// Indicates whether the send contains text or file data.
+    /// </summary>
     public SendType Type { get; set; }
+
+    /// <summary>
+    /// Estimated length of the file accompanying the send. <see langword="null"/> when
+    /// <see cref="Type"/> is <see cref="SendType.Text"/>.
+    /// </summary>
     public long? FileLength { get; set; } = null;
+
+    /// <summary>
+    /// Label for the send.
+    /// </summary>
     [EncryptedString]
     [EncryptedStringLength(1000)]
     public string Name { get; set; }
+
+    /// <summary>
+    /// Notes for the send. This is only visible to the owner of the send.
+    /// </summary>
     [EncryptedString]
     [EncryptedStringLength(1000)]
     public string Notes { get; set; }
+
+    /// <summary>
+    /// A base64-encoded byte array containing the Send's encryption key. This key is
+    /// also provided to send recipients in the Send's URL.
+    /// </summary>
     [Required]
     [EncryptedString]
     [EncryptedStringLength(1000)]
     public string Key { get; set; }
+
+    /// <summary>
+    /// The maximum number of times a send can be accessed before it expires.
+    /// When this value is <see langword="null" />, there is no limit.
+    /// </summary>
     [Range(1, int.MaxValue)]
     public int? MaxAccessCount { get; set; }
+
+    /// <summary>
+    /// The date after which a send cannot be accessed. When this value is
+    /// <see langword="null"/>, there is no expiration date.
+    /// </summary>
     public DateTime? ExpirationDate { get; set; }
+
+    /// <summary>
+    /// The date after which a send may be automatically deleted from the server.
+    /// When this is <see langword="null" />, the send may be deleted after it has
+    /// exceeded the global send timeout limit.
+    /// </summary>
     [Required]
     public DateTime? DeletionDate { get; set; }
+
+    /// <summary>
+    /// Contains file metadata uploaded with the send.
+    /// The file content is uploaded separately.
+    /// </summary>
     public SendFileModel File { get; set; }
+
+    /// <summary>
+    /// Contains text data uploaded with the send.
+    /// </summary>
     public SendTextModel Text { get; set; }
+
+    /// <summary>
+    /// Base64-encoded byte array of a password hash that grants access to the send.
+    /// Mutually exclusive with <see cref="Emails"/>.
+    /// </summary>
     [StringLength(1000)]
     public string Password { get; set; }
+
+    /// <summary>
+    /// Comma-separated list of emails that may access the send using OTP
+    /// authentication. Mutually exclusive with <see cref="Password"/>.
+    /// </summary>
+    [StringLength(1024)]
+    public string Emails { get; set; }
+
+    /// <summary>
+    /// When <see langword="true"/>, send access is disabled.
+    /// Defaults to <see langword="false"/>.
+    /// </summary>
     [Required]
     public bool? Disabled { get; set; }
+
+    /// <summary>
+    /// When <see langword="true"/> send access hides the user's email address
+    /// and displays a confirmation message instead. Defaults to <see langword="false"/>.
+    /// </summary>
     public bool? HideEmail { get; set; }
 
+    /// <summary>
+    /// Transforms the request into a send object.
+    /// </summary>
+    /// <param name="userId">The user that owns the send.</param>
+    /// <param name="sendAuthorizationService">Hashes the send password.</param>
+    /// <returns>The send object</returns>
     public Send ToSend(Guid userId, ISendAuthorizationService sendAuthorizationService)
     {
         var send = new Send
@@ -47,8 +126,17 @@
         return send;
     }
 
+    /// <summary>
+    /// Transforms the request into a send object and file data.
+    /// </summary>
+    /// <param name="userId">The user that owns the send.</param>
+    /// <param name="fileName">Name of the file uploaded with the send.</param>
+    /// <param name="sendAuthorizationService">Hashes the send password.</param>
+    /// <returns>The send object and file data.</returns>
     public (Send, SendFileData) ToSend(Guid userId, string fileName, ISendAuthorizationService sendAuthorizationService)
     {
+        // FIXME: This method does two things: creates a send and a send file data.
+        //        It should only do one thing.
         var send = ToSendBase(new Send
         {
             Type = Type,
@@ -58,6 +146,13 @@
         return (send, data);
     }
 
+    /// <summary>
+    /// Update a send object with request content
+    /// </summary>
+    /// <param name="existingSend">The send to update</param>
+    /// <param name="sendAuthorizationService">Hashes the send password.</param>
+    /// <returns>The send object</returns>
+    // FIXME: rename to `UpdateSend`
     public Send ToSend(Send existingSend, ISendAuthorizationService sendAuthorizationService)
     {
         existingSend = ToSendBase(existingSend, sendAuthorizationService);
@@ -78,6 +173,12 @@
         return existingSend;
     }
 
+    /// <summary>
+    /// Validates that the request is internally consistent for send creation.
+    /// </summary>
+    /// <exception cref="BadRequestException">
+    /// Thrown when the send's expiration date has already expired.
+    /// </exception>
     public void ValidateCreation()
     {
         var now = DateTime.UtcNow;
@@ -91,6 +192,13 @@
         ValidateEdit();
     }
 
+    /// <summary>
+    /// Validates that the request is internally consistent for send administration.
+    /// </summary>
+    /// <exception cref="BadRequestException">
+    /// Thrown when the send's deletion date has already expired or when its
+    /// expiration occurs after its deletion.
+    /// </exception>
     public void ValidateEdit()
     {
         var now = DateTime.UtcNow;
@@ -131,12 +239,23 @@
         existingSend.ExpirationDate = ExpirationDate;
         existingSend.DeletionDate = DeletionDate.Value;
         existingSend.MaxAccessCount = MaxAccessCount;
-        if (!string.IsNullOrWhiteSpace(Password))
+
+        if (!string.IsNullOrWhiteSpace(Emails))
+        {
+            // normalize encoding
+            var emails = Emails.Split(',', RemoveEmptyEntries | TrimEntries);
+            existingSend.Emails = string.Join(", ", emails);
+            existingSend.Password = null;
+        }
+        else if (!string.IsNullOrWhiteSpace(Password))
         {
             existingSend.Password = authorizationService.HashPassword(Password);
+            existingSend.Emails = null;
         }
+
         existingSend.Disabled = Disabled.GetValueOrDefault();
         existingSend.HideEmail = HideEmail.GetValueOrDefault();
+
         return existingSend;
     }
 
@@ -146,8 +265,15 @@
     }
 }
 
+/// <summary>
+/// A send request issued by a Bitwarden client
+/// </summary>
 public class SendWithIdRequestModel : SendRequestModel
 {
+    /// <summary>
+    /// Identifies the send. When this is <see langword="null" />, the client is requesting
+    /// a new send.
+    /// </summary>
     [Required]
     public Guid? Id { get; set; }
 }

src/Api/Tools/Models/Response/SendAccessResponseModel.cs

@@ -8,8 +8,25 @@
 
 namespace Bit.Api.Tools.Models.Response;
 
+/// <summary>
+/// A response issued to a Bitwarden client in response to access operations.
+/// </summary>
 public class SendAccessResponseModel : ResponseModel
 {
+    /// <summary>
+    /// Instantiates a send access response model
+    /// </summary>
+    /// <param name="send">Content to transmit to the client.</param>
+    /// <param name="globalSettings">
+    /// Settings that control response generation.
+    /// </param>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown when <paramref name="send"/> is <see langword="null" />
+    /// </exception>
+    /// <exception cref="ArgumentException">
+    /// Thrown when <paramref name="send" /> has an invalid <see cref="Send.Type"/>.
+    /// </exception>
+    // FIXME: remove `globalSettings` variable
     public SendAccessResponseModel(Send send, GlobalSettings globalSettings)
         : base("send-access")
     {
@@ -42,11 +59,47 @@ public SendAccessResponseModel(Send send, GlobalSettings globalSettings)
         ExpirationDate = send.ExpirationDate;
     }
 
+    /// <summary>
+    /// Identifies the send in a send URL
+    /// </summary>
     public string Id { get; set; }
+
+    /// <summary>
+    /// Indicates whether the send contains text or file data.
+    /// </summary>
     public SendType Type { get; set; }
+
+    /// <summary>
+    /// Label for the send. This is only visible to the owner of the send.
+    /// </summary>
+    /// <remarks>
+    /// This field contains a base64-encoded byte array. The array contains
+    /// the E2E-encrypted encrypted content.
+    /// </remarks>
     public string Name { get; set; }
+
+    /// <summary>
+    /// Describes the file attached to the send.
+    /// </summary>
+    /// <remarks>
+    /// File content is downloaded separately using
+    /// <see cref="Bit.Api.Tools.Controllers.SendsController.GetSendFileDownloadData" />
+    /// </remarks>
     public SendFileModel File { get; set; }
+
+    /// <summary>
+    /// Contains text data uploaded with the send.
+    /// </summary>
     public SendTextModel Text { get; set; }
+
+    /// <summary>
+    /// The date after which a send cannot be accessed. When this value is
+    /// <see langword="null"/>, there is no expiration date.
+    /// </summary>
     public DateTime? ExpirationDate { get; set; }
+
+    /// <summary>
+    /// Indicates the person that created the send to the accessor.
+    /// </summary>
     public string CreatorIdentifier { get; set; }
 }