From 463dc1232d8097ac17b328259697c85c4a9fa038 Mon Sep 17 00:00:00 2001
From: Thomas Rittson <31796059+eliykat@users.noreply.github.com>
Date: Thu, 12 Jun 2025 10:47:41 +1000
Subject: [PATCH] Add xmldoc for OrganizationUser (#5949)

---
 .../AdminConsole/Entities/OrganizationUser.cs | 55 ++++++++++++++++++-
 .../Enums/OrganizationUserStatusType.cs       | 27 ++++++++-
 2 files changed, 80 insertions(+), 2 deletions(-)

diff --git a/src/Core/AdminConsole/Entities/OrganizationUser.cs b/src/Core/AdminConsole/Entities/OrganizationUser.cs
index 9828482a7e..3166ebf3a8 100644
--- a/src/Core/AdminConsole/Entities/OrganizationUser.cs
+++ b/src/Core/AdminConsole/Entities/OrganizationUser.cs
@@ -1,4 +1,5 @@
 using System.ComponentModel.DataAnnotations;
+using Bit.Core.AdminConsole.Entities;
 using Bit.Core.AdminConsole.Interfaces;
 using Bit.Core.Enums;
 using Bit.Core.Models;
@@ -9,23 +10,75 @@ using Bit.Core.Utilities;
 
 namespace Bit.Core.Entities;
 
+/// <summary>
+/// An association table between one <see cref="User"/> and one <see cref="Organization"/>, representing that user's
+/// membership in the organization. "Member" refers to the OrganizationUser object.
+/// </summary>
 public class OrganizationUser : ITableObject<Guid>, IExternal, IOrganizationUser
 {
+    /// <summary>
+    /// A unique random identifier.
+    /// </summary>
     public Guid Id { get; set; }
+    /// <summary>
+    /// The ID of the Organization that the user is a member of.
+    /// </summary>
     public Guid OrganizationId { get; set; }
+    /// <summary>
+    /// The ID of the User that is the member. This is NULL if the Status is Invited (or Invited and then Revoked), because
+    /// it is not linked to a specific User yet.
+    /// </summary>
     public Guid? UserId { get; set; }
+    /// <summary>
+    /// The email address of the user invited to the organization. This is NULL if the Status is not Invited (or
+    /// Invited and then Revoked), because in that case the OrganizationUser is linked to a User
+    /// and the email is stored on the User object.
+    /// </summary>
     [MaxLength(256)]
     public string? Email { get; set; }
+    /// <summary>
+    /// The Organization symmetric key encrypted with the User's public key. NULL if the user is not in a Confirmed
+    /// (or Confirmed and then Revoked) status.
+    /// </summary>
     public string? Key { get; set; }
+    /// <summary>
+    /// The User's symmetric key encrypted with the Organization's public key. NULL if the OrganizationUser
+    /// is not enrolled in account recovery.
+    /// </summary>
     public string? ResetPasswordKey { get; set; }
+    /// <inheritdoc cref="OrganizationUserStatusType"/>
     public OrganizationUserStatusType Status { get; set; }
+    /// <summary>
+    /// The User's role in the Organization.
+    /// </summary>
     public OrganizationUserType Type { get; set; }
-
+    /// <summary>
+    /// An ID used to identify the OrganizationUser with an external directory service. Used by Directory Connector
+    /// and SCIM.
+    /// </summary>
     [MaxLength(300)]
     public string? ExternalId { get; set; }
+    /// <summary>
+    /// The date the OrganizationUser was created, i.e. when the User was first invited to the Organization.
+    /// </summary>
     public DateTime CreationDate { get; internal set; } = DateTime.UtcNow;
+    /// <summary>
+    /// The last date the OrganizationUser entry was updated.
+    /// </summary>
     public DateTime RevisionDate { get; internal set; } = DateTime.UtcNow;
+    /// <summary>
+    /// A json blob representing the <see cref="Bit.Core.Models.Data.Permissions"/> of the OrganizationUser if they
+    /// are a Custom user role (i.e. the <see cref="OrganizationUserType"/> is Custom). MAY be NULL if they are not
+    /// a custom user, but this is not guaranteed; do not use this to determine their role.
+    /// </summary>
+    /// <remarks>
+    /// Avoid using this property directly - instead use the <see cref="GetPermissions"/> and <see cref="SetPermissions"/>
+    /// helper methods.
+    /// </remarks>
     public string? Permissions { get; set; }
+    /// <summary>
+    /// True if the User has access to Secrets Manager for this Organization, false otherwise.
+    /// </summary>
     public bool AccessSecretsManager { get; set; }
 
     public void SetNewId()
diff --git a/src/Core/AdminConsole/Enums/OrganizationUserStatusType.cs b/src/Core/AdminConsole/Enums/OrganizationUserStatusType.cs
index 576e98ea74..3b4098715d 100644
--- a/src/Core/AdminConsole/Enums/OrganizationUserStatusType.cs
+++ b/src/Core/AdminConsole/Enums/OrganizationUserStatusType.cs
@@ -1,9 +1,34 @@
-namespace Bit.Core.Enums;
+using Bit.Core.Entities;
 
+namespace Bit.Core.Enums;
+
+/// <summary>
+/// Represents the different stages of a member's lifecycle in an organization.
+/// The <see cref="OrganizationUser"/> object is populated differently depending on their Status.
+/// </summary>
 public enum OrganizationUserStatusType : short
 {
+    /// <summary>
+    /// The OrganizationUser entry only represents an invitation to join the organization. It is not linked to a
+    /// specific User yet.
+    /// </summary>
     Invited = 0,
+    /// <summary>
+    /// The User has accepted the invitation and linked their User account to the OrganizationUser entry.
+    /// </summary>
     Accepted = 1,
+    /// <summary>
+    /// An administrator has granted the User access to the organization. This is the final step in the User becoming
+    /// a "full" member of the organization, including a key exchange so that they can decrypt organization data.
+    /// </summary>
     Confirmed = 2,
+    /// <summary>
+    /// The OrganizationUser has been revoked from the organization and cannot access organization data while in this state.
+    /// </summary>
+    /// <remarks>
+    /// An OrganizationUser may move into this status from any other status, and will move back to their original status
+    /// if restored. This allows an administrator to easily suspend and restore access without going through the
+    /// Invite flow again.
+    /// </remarks>
     Revoked = -1,
 }