[AC-2084] Include Collection permissions for admin endpoints (#3793)

* [AC-2084] Add documentation to existing collection repository getters

* [AC-2084] Add new CollectionAdminDetails model

* [AC-2084] Add SQL and migration scripts

* [AC-2084] Introduce new repository methods to include permission details for collections

* [AC-2084] Add EF repository methods and integration tests

* [AC-2084] Update CollectionsController and response models

* [AC-2084] Fix failing SqlServer test

* [AC-2084] Clean up admin endpoint response models
- vNext endpoints should now always return CollectionDetailsResponse models
- Update constructors in CollectionDetailsResponseModel to be more explicit and add named static constructors for additional clarity

* [AC-2084] Fix failing tests

* [AC-2084] Fix potential provider/member bug

* [AC-2084] Fix broken collections controller

* [AC-2084] Cleanup collection response model types and constructors

* [AC-2084] Remove redundant authorization check

* [AC-2084] Cleanup ambiguous model name

* [AC-2084] Add GroupBy clause to sprocs

* [AC-2084] Add GroupBy logic to EF repository

* [AC-2084] Update collection repository tests

* [AC-2084] Update migration script date

* Update migration script date

---------

Co-authored-by: Thomas Rittson <31796059+eliykat@users.noreply.github.com>
Co-authored-by: kejaeger <138028972+kejaeger@users.noreply.github.com>

src/Core/Repositories/ICollectionRepository.cs

@@ -6,14 +6,64 @@ namespace Bit.Core.Repositories;
 public interface ICollectionRepository : IRepository<Collection, Guid>
 {
     Task<int> GetCountByOrganizationIdAsync(Guid organizationId);
+
+    /// <summary>
+    /// Returns a collection and fetches group/user associations for the collection.
+    /// </summary>
     Task<Tuple<Collection, CollectionAccessDetails>> GetByIdWithAccessAsync(Guid id);
+
+    /// <summary>
+    /// Returns a collection with permission details for the provided userId and fetches group/user associations for
+    /// the collection.
+    /// If the user does not have a relationship with the collection, nothing is returned.
+    /// </summary>
     Task<Tuple<CollectionDetails, CollectionAccessDetails>> GetByIdWithAccessAsync(Guid id, Guid userId, bool useFlexibleCollections);
+
+    /// <summary>
+    /// Return all collections that belong to the organization. Does not include any permission details or group/user
+    /// access relationships.
+    /// </summary>
     Task<ICollection<Collection>> GetManyByOrganizationIdAsync(Guid organizationId);
+
+    /// <summary>
+    /// Return all collections that belong to the organization. Includes group/user access relationships for each collection.
+    /// </summary>
     Task<ICollection<Tuple<Collection, CollectionAccessDetails>>> GetManyByOrganizationIdWithAccessAsync(Guid organizationId);
+
+    /// <summary>
+    /// Returns collections that both, belong to the organization AND have an access relationship with the provided user.
+    /// Includes permission details for the provided user and group/user access relationships for each collection.
+    /// </summary>
     Task<ICollection<Tuple<CollectionDetails, CollectionAccessDetails>>> GetManyByUserIdWithAccessAsync(Guid userId, Guid organizationId, bool useFlexibleCollections);
+
+    /// <summary>
+    /// Returns a collection with permission details for the provided userId. Does not include group/user access
+    /// relationships.
+    /// If the user does not have a relationship with the collection, nothing is returned.
+    /// </summary>
     Task<CollectionDetails> GetByIdAsync(Guid id, Guid userId, bool useFlexibleCollections);
     Task<ICollection<Collection>> GetManyByManyIdsAsync(IEnumerable<Guid> collectionIds);
+
+    /// <summary>
+    /// Return all collections a user has access to across all of the organization they're a member of. Includes permission
+    /// details for each collection.
+    /// </summary>
     Task<ICollection<CollectionDetails>> GetManyByUserIdAsync(Guid userId, bool useFlexibleCollections);
+
+    /// <summary>
+    /// Returns all collections for an organization, including permission info for the specified user.
+    /// This does not perform any authorization checks internally!
+    /// Optionally, you can include access relationships for other Groups/Users and the collections.
+    /// </summary>
+    Task<ICollection<CollectionAdminDetails>> GetManyByOrganizationIdWithPermissionsAsync(Guid organizationId, Guid userId, bool includeAccessRelationships);
+
+    /// <summary>
+    /// Returns the collection by Id, including permission info for the specified user.
+    /// This does not perform any authorization checks internally!
+    /// Optionally, you can include access relationships for other Groups/Users and the collection.
+    /// </summary>
+    Task<CollectionAdminDetails> GetByIdWithPermissionsAsync(Guid collectionId, Guid? userId, bool includeAccessRelationships);
+
     Task CreateAsync(Collection obj, IEnumerable<CollectionAccessSelection> groups, IEnumerable<CollectionAccessSelection> users);
     Task ReplaceAsync(Collection obj, IEnumerable<CollectionAccessSelection> groups, IEnumerable<CollectionAccessSelection> users);
     Task DeleteUserAsync(Guid collectionId, Guid organizationUserId);