update send api models to support new email field

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

@@ -7,33 +7,106 @@ using Bit.Core.Tools.Models.Data;
 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; }
 
     public Send ToSend(Guid userId, ISendAuthorizationService sendAuthorizationService)
@@ -78,6 +151,12 @@ public class SendRequestModel
         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 +170,13 @@ public class SendRequestModel
         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;
@@ -135,6 +221,13 @@ public class SendRequestModel
         {
             existingSend.Password = authorizationService.HashPassword(Password);
         }
+        else if (!string.IsNullOrWhiteSpace(Emails))
+        {
+            // normalize encoding
+            var emails = Emails.Split(',', RemoveEmptyEntries | TrimEntries);
+            existingSend.Emails = string.Join(", ", emails);
+        }
+
         existingSend.Disabled = Disabled.GetValueOrDefault();
         existingSend.HideEmail = HideEmail.GetValueOrDefault();
         return existingSend;
@@ -146,8 +239,15 @@ public class SendRequestModel
     }
 }
 
+/// <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,24 @@ using Bit.Core.Utilities;
 
 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>
     public SendAccessResponseModel(Send send, GlobalSettings globalSettings)
         : base("send-access")
     {
@@ -42,11 +58,47 @@ public class SendAccessResponseModel : ResponseModel
         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; }
 }

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

@@ -8,8 +8,25 @@ using Bit.Core.Utilities;
 
 namespace Bit.Api.Tools.Models.Response;
 
+/// <summary>
+/// A response issued to a Bitwarden client in response to ownership operations.
+/// </summary>
+/// <seealso cref="SendAccessResponseModel" />
 public class SendResponseModel : ResponseModel
 {
+    /// <summary>
+    /// Instantiates a send 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>
     public SendResponseModel(Send send, GlobalSettings globalSettings)
         : base("send")
     {
@@ -28,6 +45,7 @@ public class SendResponseModel : ResponseModel
         ExpirationDate = send.ExpirationDate;
         DeletionDate = send.DeletionDate;
         Password = send.Password;
+        Emails = send.Emails;
         Disabled = send.Disabled;
         HideEmail = send.HideEmail.GetValueOrDefault();
 
@@ -52,20 +70,108 @@ public class SendResponseModel : ResponseModel
         Notes = sendData.Notes;
     }
 
+    /// <summary>
+    /// Identifies the send to its owner
+    /// </summary>
     public Guid Id { get; set; }
+
+    /// <summary>
+    /// Identifies the send in a send URL
+    /// </summary>
     public string AccessId { get; set; }
+
+    /// <summary>
+    /// Indicates whether the send contains text or file data.
+    /// </summary>
     public SendType Type { get; set; }
+
+    /// <summary>
+    /// Label for 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>
+    /// Notes for the send. This is only visible to the owner of the send.
+    /// This field is encrypted.
+    /// </summary>
+    /// <remarks>
+    /// This field contains a base64-encoded byte array. The array contains
+    /// the E2E-encrypted  encrypted content.
+    /// </remarks>
     public string Notes { 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>
+    /// A base64-encoded byte array containing the Send's encryption key.
+    /// It's also provided to send recipients in the Send's URL.
+    /// </summary>
+    /// <remarks>
+    /// This field contains a base64-encoded byte array. The array contains
+    /// the E2E-encrypted content.
+    /// </remarks>
     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>
     public int? MaxAccessCount { get; set; }
+
+    /// <summary>
+    /// The number of times a send has been accessed since it was created.
+    /// </summary>
     public int AccessCount { get; set; }
+
+    /// <summary>
+    /// Base64-encoded byte array of a password hash that grants access to the send.
+    /// Mutually exclusive with <see cref="Emails"/>.
+    /// </summary>
     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>
+    public string Emails { get; set; }
+
+    /// <summary>
+    /// When <see langword="true"/>, send access is disabled.
+    /// </summary>
     public bool Disabled { get; set; }
+
+    /// <summary>
+    /// The last time this send's data changed.
+    /// </summary>
     public DateTime RevisionDate { 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.
+    /// </summary>
     public DateTime DeletionDate { get; set; }
+
+    /// <summary>
+    /// When <see langword="true"/> send access hides the user's email address
+    /// and displays a confirmation message instead.
+    /// </summary>
     public bool HideEmail { get; set; }
 }