Documentation modifications

2026-06-27 15:23:26 -07:00
parent a633fe6c06
commit a19fb90902
218 changed files with 2882 additions and 0 deletions
@@ -5,6 +5,14 @@ using Microsoft.AspNetCore.Mvc.Filters;

 namespace adas_core.Authentication.Attributes;

+/// <summary>
+/// Specifies an authorization filter attribute that restricts access to decorated methods based on a required role of type <see cref="PermissionEnum.RolesType"/>.
+/// Inherits from <see cref="Attribute"/> and implements <see cref="IAuthorizationFilter"/> to participate in the authorization pipeline.
+/// </summary>
+/// <remarks>
+/// Constrained by <see cref="System.AttributeUsageAttribute"/> to <see cref="AttributeTargets.Method"/>, the attribute is configured at construction with the required <paramref name="type"/>.
+/// </remarks>
+/// <!-- aidoc:v1 sig=b5093e9 -->
 [AttributeUsage(AttributeTargets.Method)]
 public class AuthorizeRolesAttribute(PermissionEnum.RolesType type) : Attribute, IAuthorizationFilter
 {
@@ -4,6 +4,13 @@ using Microsoft.AspNetCore.Mvc.Filters;

 namespace adas_core.Authentication.Attributes;

+/// <summary>
+/// Represents an authorization attribute that enforces permission-based access control using the injected <see cref="IUserService"/>.
+/// </summary>
+/// <remarks>
+/// Inherits from <see cref="Attribute"/> and implements <see cref="IAuthorizationFilter"/>, allowing it to be applied to controllers or actions and integrated into the request filtering pipeline.
+/// </remarks>
+/// <!-- aidoc:v1 sig=28ee847 -->
 public class AuthorizePermissionsAttribute(
    IUserService userService)
    : Attribute, IAuthorizationFilter
@@ -9,6 +9,14 @@ using Microsoft.Extensions.DependencyInjection;

 namespace adas_core.Authentication.Attributes;

+/// <summary>
+/// Represents an authorization attribute that evaluates permissions using a configured source and an optional resource identifier header.
+/// </summary>
+/// <remarks>
+/// Extends <see cref="AuthorizeAttribute"/> and implements <see cref="IAsyncAuthorizationFilter"/> to support asynchronous authorization filtering.
+/// The primary constructor parameter <paramref name="source"/> specifies the permission source, while the optional <paramref name="resourceIdHeader"/> identifies the header that carries the resource identifier.
+/// </remarks>
+/// <!-- aidoc:v1 sig=e97022a -->
 public class PermissionAuthorizeAttribute(string source, string? resourceIdHeader = null)
    : AuthorizeAttribute, IAsyncAuthorizationFilter
 {
@@ -8,6 +8,12 @@ using Serilog;

 namespace adas_core.Authentication;

+/// <summary>
+/// Implements <see cref="IAuthorityService"/>, coordinating authority-related operations through
+/// <see cref="IAuthorityRepository"/> for data access, <see cref="IHttpContextAccessor"/> for
+/// HTTP context access, and <see cref="ILocalAuditService"/> for local auditing.
+/// </summary>
+/// <!-- aidoc:v1 sig=5aafd48 -->
 public class AuthorityService(
    IAuthorityRepository authorityRepository,
    IHttpContextAccessor httpContextAccessor,
@@ -6,10 +6,20 @@
 /// <typeparam name="T">The type of the response payload.</typeparam>
 public class UciResponse<T>
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UciResponse"/> class with default values.
+    /// This protected parameterless constructor enables the <see cref="UciResponse"/> type to be instantiated by derived classes.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=bc935a2 body=4448e1d -->
    protected UciResponse()
    {
    }

+    /// <summary>
+    /// Initializes a successful instance of the <see cref="UciResponse{T}"/> class, which wraps an entity as a response payload. The constructor assigns <paramref name="entity"/> to <see cref="UciResponse{T}.Data"/>, sets <see cref="UciResponse{T}.Success"/> to <c>true</c>, and clears <see cref="UciResponse{T}.Message"/> and <see cref="UciResponse{T}.Error"/>.
+    /// </summary>
+    /// <param name="entity">The payload to encapsulate in the response, stored in the <see cref="UciResponse{T}.Data"/> property.</param>
+    /// <!-- aidoc:v1 sig=5205995 body=dd7f9e7 -->
    protected UciResponse(T entity)
    {
        Success = true;
@@ -47,6 +47,25 @@ public class UserService : IUserService
    private readonly ISubscribersService _subscribersService;
    private readonly IClientMessageService _clientMessageService;
    private readonly Lazy<IPermissionService> _permissionService;
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UserService"/> class, capturing the supplied authentication, authorization, user data and logging collaborators for use by subsequent operations.
+    /// </summary>
+    /// <param name="loginServices">The collection of <see cref="ILoginService"/> implementations used to enumerate available login methods.</param>
+    /// <param name="configuration">The <see cref="IOptions{AuthSettings}"/> wrapper whose <see cref="AuthSettings.LoginMethods"/> define the supported login methods.</param>
+    /// <param name="validGroups">The <see cref="IOptions{ValidGroupsConfig}"/> wrapper providing the configured valid user groups.</param>
+    /// <param name="usersWhiteList">The <see cref="IOptions{AuthSettings}"/> wrapper whose <see cref="AuthSettings.UsersWhiteListConfig"/> supplies the users white list.</param>
+    /// <param name="jwt">The <see cref="IOptions{AuthSettings}"/> wrapper whose <see cref="AuthSettings.JwtConfig"/> supplies the JWT configuration.</param>
+    /// <param name="httpContextAccessor">The <see cref="IHttpContextAccessor"/> used to access the current HTTP context.</param>
+    /// <param name="userRepository">The <see cref="IUserRepository"/> used to read and persist user data.</param>
+    /// <param name="authorityService">The <see cref="IAuthorityService"/> used to perform authority and authorization operations.</param>
+    /// <param name="auditService">The <see cref="ILocalAuditService"/> used to record local audit entries.</param>
+    /// <param name="displayService">A <see cref="Lazy{IDisplayService}"/> wrapper providing deferred access to display services.</param>
+    /// <param name="logger">The <see cref="ILogger{UserService}"/> used to log diagnostics for the <see cref="UserService"/>.</param>
+    /// <param name="subscribersService">The <see cref="ISubscribersService"/> used to manage subscribers.</param>
+    /// <param name="clientMessageService">The <see cref="IClientMessageService"/> used to send messages to clients.</param>
+    /// <param name="permissionService">A <see cref="Lazy{IPermissionService}"/> wrapper providing deferred access to permission checks.</param>
+    /// <exception cref="System.Exception">Thrown when the JWT configuration provided by <paramref name="jwt"/> is not configured.</exception>
+    /// <!-- aidoc:v1 sig=8c3130e body=79f6643 -->
    public UserService(
        IEnumerable<ILoginService> loginServices,
        IOptions<AuthSettings> configuration,
@@ -150,6 +169,13 @@ public class UserService : IUserService
            }
        }

+    /// <summary>
+    /// Retrieves a <see cref="User"/> based on the username extracted from the provided <paramref name="jwtToken"/>.
+    /// Returns <see langword="null"/> when the token is null or the user cannot be found, clears the retrieved user's password before returning, and lazily loads authorization data from the authority service when it is not already populated.
+    /// </summary>
+    /// <param name="jwtToken">The <see cref="JwtSecurityToken"/> containing the user identity claims, or <see langword="null"/> to indicate no token was supplied.</param>
+    /// <returns>A <see cref="Task{User}"/> that resolves to the matching <see cref="User"/> with its password cleared and authorization loaded if required, or <see langword="null"/> when the token is missing or no user matches the extracted username.</returns>
+    /// <!-- aidoc:v1 sig=29f6fec body=a7970c3 -->
    public async Task<User?> GetUserByToken(JwtSecurityToken? jwtToken)
    {
        User? user = null;