diff --git a/src/Api/Tools/Models/Request/SendRequestModel.cs b/src/Api/Tools/Models/Request/SendRequestModel.cs index 5b3fd7ba31..b8057571ab 100644 --- a/src/Api/Tools/Models/Request/SendRequestModel.cs +++ b/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; +/// +/// A send request issued by a Bitwarden client +/// public class SendRequestModel { + /// + /// Indicates whether the send contains text or file data. + /// public SendType Type { get; set; } + + /// + /// Estimated length of the file accompanying the send. when + /// is . + /// public long? FileLength { get; set; } = null; + + /// + /// Label for the send. + /// [EncryptedString] [EncryptedStringLength(1000)] public string Name { get; set; } + + /// + /// Notes for the send. This is only visible to the owner of the send. + /// [EncryptedString] [EncryptedStringLength(1000)] public string Notes { get; set; } + + /// + /// A base64-encoded byte array containing the Send's encryption key. This key is + /// also provided to send recipients in the Send's URL. + /// [Required] [EncryptedString] [EncryptedStringLength(1000)] public string Key { get; set; } + + /// + /// The maximum number of times a send can be accessed before it expires. + /// When this value is , there is no limit. + /// [Range(1, int.MaxValue)] public int? MaxAccessCount { get; set; } + + /// + /// The date after which a send cannot be accessed. When this value is + /// , there is no expiration date. + /// public DateTime? ExpirationDate { get; set; } + + /// + /// The date after which a send may be automatically deleted from the server. + /// When this is , the send may be deleted after it has + /// exceeded the global send timeout limit. + /// [Required] public DateTime? DeletionDate { get; set; } + + /// + /// Contains file metadata uploaded with the send. + /// The file content is uploaded separately. + /// public SendFileModel File { get; set; } + + /// + /// Contains text data uploaded with the send. + /// public SendTextModel Text { get; set; } + + /// + /// Base64-encoded byte array of a password hash that grants access to the send. + /// Mutually exclusive with . + /// [StringLength(1000)] public string Password { get; set; } + + /// + /// Comma-separated list of emails that may access the send using OTP + /// authentication. Mutually exclusive with . + /// + [StringLength(1024)] + public string Emails { get; set; } + + /// + /// When , send access is disabled. + /// Defaults to . + /// [Required] public bool? Disabled { get; set; } + + /// + /// When send access hides the user's email address + /// and displays a confirmation message instead. Defaults to . + /// public bool? HideEmail { get; set; } public Send ToSend(Guid userId, ISendAuthorizationService sendAuthorizationService) @@ -78,6 +151,12 @@ public class SendRequestModel return existingSend; } + /// + /// Validates that the request is internally consistent for send creation. + /// + /// + /// Thrown when the send's expiration date has already expired. + /// public void ValidateCreation() { var now = DateTime.UtcNow; @@ -91,6 +170,13 @@ public class SendRequestModel ValidateEdit(); } + /// + /// Validates that the request is internally consistent for send administration. + /// + /// + /// Thrown when the send's deletion date has already expired or when its + /// expiration occurs after its deletion. + /// 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 } } +/// +/// A send request issued by a Bitwarden client +/// public class SendWithIdRequestModel : SendRequestModel { + /// + /// Identifies the send. When this is , the client is requesting + /// a new send. + /// [Required] public Guid? Id { get; set; } } diff --git a/src/Api/Tools/Models/Response/SendAccessResponseModel.cs b/src/Api/Tools/Models/Response/SendAccessResponseModel.cs index a3bb0f8bc0..cb70f2249a 100644 --- a/src/Api/Tools/Models/Response/SendAccessResponseModel.cs +++ b/src/Api/Tools/Models/Response/SendAccessResponseModel.cs @@ -8,8 +8,24 @@ using Bit.Core.Utilities; namespace Bit.Api.Tools.Models.Response; +/// +/// A response issued to a Bitwarden client in response to access operations. +/// public class SendAccessResponseModel : ResponseModel { + /// + /// Instantiates a send access response model + /// + /// Content to transmit to the client. + /// + /// Settings that control response generation. + /// + /// + /// Thrown when is + /// + /// + /// Thrown when has an invalid . + /// public SendAccessResponseModel(Send send, GlobalSettings globalSettings) : base("send-access") { @@ -42,11 +58,47 @@ public class SendAccessResponseModel : ResponseModel ExpirationDate = send.ExpirationDate; } + /// + /// Identifies the send in a send URL + /// public string Id { get; set; } + + /// + /// Indicates whether the send contains text or file data. + /// public SendType Type { get; set; } + + /// + /// Label for the send. This is only visible to the owner of the send. + /// + /// + /// This field contains a base64-encoded byte array. The array contains + /// the E2E-encrypted encrypted content. + /// public string Name { get; set; } + + /// + /// Describes the file attached to the send. + /// + /// + /// File content is downloaded separately using + /// + /// public SendFileModel File { get; set; } + + /// + /// Contains text data uploaded with the send. + /// public SendTextModel Text { get; set; } + + /// + /// The date after which a send cannot be accessed. When this value is + /// , there is no expiration date. + /// public DateTime? ExpirationDate { get; set; } + + /// + /// Indicates the person that created the send to the accessor. + /// public string CreatorIdentifier { get; set; } } diff --git a/src/Api/Tools/Models/Response/SendResponseModel.cs b/src/Api/Tools/Models/Response/SendResponseModel.cs index 2ea217fd67..763d555bc5 100644 --- a/src/Api/Tools/Models/Response/SendResponseModel.cs +++ b/src/Api/Tools/Models/Response/SendResponseModel.cs @@ -8,8 +8,25 @@ using Bit.Core.Utilities; namespace Bit.Api.Tools.Models.Response; +/// +/// A response issued to a Bitwarden client in response to ownership operations. +/// +/// public class SendResponseModel : ResponseModel { + /// + /// Instantiates a send response model + /// + /// Content to transmit to the client. + /// + /// Settings that control response generation. + /// + /// + /// Thrown when is + /// + /// + /// Thrown when has an invalid . + /// 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; } + /// + /// Identifies the send to its owner + /// public Guid Id { get; set; } + + /// + /// Identifies the send in a send URL + /// public string AccessId { get; set; } + + /// + /// Indicates whether the send contains text or file data. + /// public SendType Type { get; set; } + + /// + /// Label for the send. + /// + /// + /// This field contains a base64-encoded byte array. The array contains + /// the E2E-encrypted encrypted content. + /// public string Name { get; set; } + + /// + /// Notes for the send. This is only visible to the owner of the send. + /// This field is encrypted. + /// + /// + /// This field contains a base64-encoded byte array. The array contains + /// the E2E-encrypted encrypted content. + /// public string Notes { get; set; } + + /// + /// Contains file metadata uploaded with the send. + /// The file content is uploaded separately. + /// public SendFileModel File { get; set; } + + /// + /// Contains text data uploaded with the send. + /// public SendTextModel Text { get; set; } + + /// + /// A base64-encoded byte array containing the Send's encryption key. + /// It's also provided to send recipients in the Send's URL. + /// + /// + /// This field contains a base64-encoded byte array. The array contains + /// the E2E-encrypted content. + /// public string Key { get; set; } + + /// + /// The maximum number of times a send can be accessed before it expires. + /// When this value is , there is no limit. + /// public int? MaxAccessCount { get; set; } + + /// + /// The number of times a send has been accessed since it was created. + /// public int AccessCount { get; set; } + + /// + /// Base64-encoded byte array of a password hash that grants access to the send. + /// Mutually exclusive with . + /// public string Password { get; set; } + + /// + /// Comma-separated list of emails that may access the send using OTP + /// authentication. Mutually exclusive with . + /// + public string Emails { get; set; } + + /// + /// When , send access is disabled. + /// public bool Disabled { get; set; } + + /// + /// The last time this send's data changed. + /// public DateTime RevisionDate { get; set; } + + /// + /// The date after which a send cannot be accessed. When this value is + /// , there is no expiration date. + /// public DateTime? ExpirationDate { get; set; } + + /// + /// The date after which a send may be automatically deleted from the server. + /// public DateTime DeletionDate { get; set; } + + /// + /// When send access hides the user's email address + /// and displays a confirmation message instead. + /// public bool HideEmail { get; set; } }