diff --git a/AutoStack.Application/Common/Interfaces/Auth/IEncryptionService.cs b/AutoStack.Application/Common/Interfaces/Auth/IEncryptionService.cs index 652391f..506a41a 100644 --- a/AutoStack.Application/Common/Interfaces/Auth/IEncryptionService.cs +++ b/AutoStack.Application/Common/Interfaces/Auth/IEncryptionService.cs @@ -1,7 +1,21 @@ namespace AutoStack.Application.Common.Interfaces.Auth; +/// +/// Service for encrypting and decrypting sensitive data +/// public interface IEncryptionService { + /// + /// Encrypts plain text into an encrypted string + /// + /// The plain text to encrypt + /// The encrypted text string Encrypt(string text); + + /// + /// Decrypts an encrypted string back to plain text + /// + /// The encrypted text to decrypt + /// The decrypted plain text string Decrypt(string encryptedText); } \ No newline at end of file diff --git a/AutoStack.Application/Common/Interfaces/Auth/IToken.cs b/AutoStack.Application/Common/Interfaces/Auth/IToken.cs index 2081570..18ccee5 100644 --- a/AutoStack.Application/Common/Interfaces/Auth/IToken.cs +++ b/AutoStack.Application/Common/Interfaces/Auth/IToken.cs @@ -3,6 +3,9 @@ namespace AutoStack.Application.Common.Interfaces.Auth; +/// +/// Service for generating and verifying JWT tokens for authentication +/// public interface IToken { /// @@ -11,25 +14,49 @@ public interface IToken /// The users id /// The users username /// The users email - /// + /// A JWT access token string string GenerateAccessToken(Guid userId, string username, string email); - + /// /// Generates a refresh token /// /// The users id /// Refresh token data RefreshToken GenerateRefreshToken(Guid userId); - + /// /// Verifies a token is valid /// /// The users auth token /// The Claims principal and null if invalid ClaimsPrincipal? VerifyToken(string token); - + + /// + /// Generates a short-lived token for two-factor authentication verification + /// + /// The user's ID + /// A JWT token for 2FA verification string GenerateTwoFactorToken(Guid userId); + + /// + /// Verifies a two-factor authentication token and extracts the user ID + /// + /// The 2FA token to verify + /// The user ID if valid, null otherwise Guid? VerifyTwoFactorToken(string token); + + /// + /// Generates a token for two-factor authentication setup containing the secret key + /// + /// The user's ID + /// The TOTP secret key + /// A JWT token containing the setup information string GenerateSetupToken(Guid userId, string secretKey); + + /// + /// Verifies a setup token and extracts the user ID and secret key + /// + /// The setup token to verify + /// A tuple of (userId, secretKey) if valid, null otherwise (Guid, string)? VerifySetupToken(string token); } \ No newline at end of file diff --git a/AutoStack.Application/Common/Interfaces/Auth/ITotpService.cs b/AutoStack.Application/Common/Interfaces/Auth/ITotpService.cs index 094a88b..ccd82fb 100644 --- a/AutoStack.Application/Common/Interfaces/Auth/ITotpService.cs +++ b/AutoStack.Application/Common/Interfaces/Auth/ITotpService.cs @@ -1,12 +1,37 @@ namespace AutoStack.Application.Common.Interfaces.Auth; +/// +/// Service for Time-based One-Time Password (TOTP) operations for two-factor authentication +/// public interface ITotpService { + /// + /// Generates a new secret key for TOTP setup + /// + /// A base32-encoded secret key string GenerateSecretKey(); + /// + /// Validates a TOTP code against a secret key + /// + /// The user's secret key + /// The TOTP code to validate + /// True if the code is valid, false otherwise bool ValidateCode(string secretKey, string code); + /// + /// Generates a TOTP URI for QR code generation + /// + /// The user's secret key + /// The user's email address + /// The application/issuer name + /// A TOTP URI string string GenerateTotpUri(string secretKey, string email, string issuer); + /// + /// Generates a QR code image as base64-encoded bytes from a TOTP URI + /// + /// The TOTP URI to encode + /// Base64-encoded QR code image bytes byte[] GenerateQrCodeBase64(string totpUri); } \ No newline at end of file diff --git a/AutoStack.Application/Common/Interfaces/IEmailService.cs b/AutoStack.Application/Common/Interfaces/IEmailService.cs index 0a7ecb5..544e5e8 100644 --- a/AutoStack.Application/Common/Interfaces/IEmailService.cs +++ b/AutoStack.Application/Common/Interfaces/IEmailService.cs @@ -1,6 +1,15 @@ namespace AutoStack.Application.Common.Interfaces; +/// +/// Service for sending email messages +/// public interface IEmailService { + /// + /// Sends an email message to the specified recipient + /// + /// The recipient email address + /// The email subject + /// The email message body Task SendEmailAsync(string email, string subject, string message); } \ No newline at end of file diff --git a/AutoStack.Application/Common/Interfaces/IFileStorageService.cs b/AutoStack.Application/Common/Interfaces/IFileStorageService.cs index d2e1630..dd86f29 100644 --- a/AutoStack.Application/Common/Interfaces/IFileStorageService.cs +++ b/AutoStack.Application/Common/Interfaces/IFileStorageService.cs @@ -1,7 +1,24 @@ namespace AutoStack.Application.Common.Interfaces; +/// +/// Service for managing file storage operations (avatars, uploads, etc.) +/// public interface IFileStorageService { + /// + /// Uploads a user avatar to storage and returns the URL + /// + /// The file stream containing the avatar image + /// The name of the file + /// The MIME type of the file + /// Cancellation token + /// The URL of the uploaded avatar Task UploadAvatarAsync(Stream fileStream, string fileName, string contentType, CancellationToken cancellationToken); + + /// + /// Deletes an avatar from storage + /// + /// The URL of the avatar to delete + /// Cancellation token Task DeleteAvatarAsync(string fileUrl, CancellationToken cancellationToken); } diff --git a/AutoStack.Application/DTOs/TwoFactor/BeginTwoFactorSetupResponse.cs b/AutoStack.Application/DTOs/TwoFactor/BeginTwoFactorSetupResponse.cs index 34b3bdc..0c63db0 100644 --- a/AutoStack.Application/DTOs/TwoFactor/BeginTwoFactorSetupResponse.cs +++ b/AutoStack.Application/DTOs/TwoFactor/BeginTwoFactorSetupResponse.cs @@ -1,5 +1,8 @@ namespace AutoStack.Application.DTOs.TwoFactor; +/// +/// Response DTO for initiating two-factor authentication setup containing QR code and secret +/// public class BeginTwoFactorSetupResponse { /// diff --git a/AutoStack.Application/DTOs/TwoFactor/ConfirmTwoFactorSetupResponse.cs b/AutoStack.Application/DTOs/TwoFactor/ConfirmTwoFactorSetupResponse.cs index 9969249..c9d4fd7 100644 --- a/AutoStack.Application/DTOs/TwoFactor/ConfirmTwoFactorSetupResponse.cs +++ b/AutoStack.Application/DTOs/TwoFactor/ConfirmTwoFactorSetupResponse.cs @@ -1,5 +1,8 @@ namespace AutoStack.Application.DTOs.TwoFactor; +/// +/// Response DTO for confirming two-factor authentication setup containing recovery codes +/// public class ConfirmTwoFactorSetupResponse { /// diff --git a/AutoStack.Application/DTOs/TwoFactor/RegenerateRecoveryCodesResponse.cs b/AutoStack.Application/DTOs/TwoFactor/RegenerateRecoveryCodesResponse.cs index dc21b16..7edb9c0 100644 --- a/AutoStack.Application/DTOs/TwoFactor/RegenerateRecoveryCodesResponse.cs +++ b/AutoStack.Application/DTOs/TwoFactor/RegenerateRecoveryCodesResponse.cs @@ -1,5 +1,8 @@ namespace AutoStack.Application.DTOs.TwoFactor; +/// +/// Response DTO containing newly generated recovery codes +/// public class RegenerateRecoveryCodesResponse { /// diff --git a/AutoStack.Application/DTOs/TwoFactor/TwoFactorStatusResponse.cs b/AutoStack.Application/DTOs/TwoFactor/TwoFactorStatusResponse.cs index 870e471..aa0f49a 100644 --- a/AutoStack.Application/DTOs/TwoFactor/TwoFactorStatusResponse.cs +++ b/AutoStack.Application/DTOs/TwoFactor/TwoFactorStatusResponse.cs @@ -1,5 +1,8 @@ namespace AutoStack.Application.DTOs.TwoFactor; +/// +/// Response DTO containing the current two-factor authentication status for a user +/// public class TwoFactorStatusResponse { /// diff --git a/AutoStack.Infrastructure/Options/FileStorageOptions.cs b/AutoStack.Infrastructure/Options/FileStorageOptions.cs index 27c9dc2..3a1d426 100644 --- a/AutoStack.Infrastructure/Options/FileStorageOptions.cs +++ b/AutoStack.Infrastructure/Options/FileStorageOptions.cs @@ -1,11 +1,29 @@ namespace AutoStack.Infrastructure.Options; +/// +/// Configuration options for file storage (avatar uploads) +/// public class FileStorageOptions { public const string SectionName = "FileStorage"; + /// + /// Gets or sets the path where avatars are stored + /// public string AvatarPath { get; set; } = "uploads/avatars"; + + /// + /// Gets or sets the base URL for accessing uploaded files + /// public string BaseUrl { get; set; } = string.Empty; + + /// + /// Gets or sets the maximum file size in bytes (default: 5MB) + /// public long MaxFileSizeBytes { get; set; } = 5242880; // 5MB + + /// + /// Gets or sets the allowed file extensions for uploads + /// public string[] AllowedExtensions { get; set; } = { ".jpg", ".jpeg", ".png", ".webp", ".gif" }; } diff --git a/AutoStack.Infrastructure/Security/CookieManager.cs b/AutoStack.Infrastructure/Security/CookieManager.cs index e154ada..b90687f 100644 --- a/AutoStack.Infrastructure/Security/CookieManager.cs +++ b/AutoStack.Infrastructure/Security/CookieManager.cs @@ -4,15 +4,51 @@ namespace AutoStack.Infrastructure.Security; +/// +/// Service for managing authentication cookies (access and refresh tokens) +/// public interface ICookieManager { + /// + /// Sets the access token cookie in the HTTP response + /// + /// The HTTP context + /// The access token value + /// Time before access token expires void SetAccessTokenCookie(HttpContext httpContext, string accessToken, int expirationMinutes); + + /// + /// Sets the refresh token cookie in the HTTP response + /// + /// The HTTP context + /// The refresh token value + /// Days before refresh token expires void SetRefreshTokenCookie(HttpContext httpContext, string refreshToken, int expirationDays); + + /// + /// Gets the access token from the request cookies + /// + /// The HTTP context + /// The access token if present, null otherwise string? GetAccessTokenFromCookie(HttpContext httpContext); + + /// + /// Gets the refresh token from the request cookies + /// + /// The HTTP context + /// The refresh token if present, null otherwise string? GetRefreshTokenFromCookie(HttpContext httpContext); + + /// + /// Clears the authentication cookies from the response + /// + /// The HTTP context void ClearAuthCookies(HttpContext httpContext); } +/// +/// Implementation of cookie manager for authentication cookies +/// public class CookieManager : ICookieManager { private readonly CookieSettings _cookieSettings; diff --git a/AutoStack.Infrastructure/Security/Models/TwoFactorSettings.cs b/AutoStack.Infrastructure/Security/Models/TwoFactorSettings.cs index 5339f41..6d9bc98 100644 --- a/AutoStack.Infrastructure/Security/Models/TwoFactorSettings.cs +++ b/AutoStack.Infrastructure/Security/Models/TwoFactorSettings.cs @@ -1,6 +1,12 @@ namespace AutoStack.Infrastructure.Security.Models; +/// +/// Configuration settings for two-factor authentication +/// public class TwoFactorSettings { + /// + /// Gets or sets the encryption key used to encrypt TOTP secret keys + /// public string EncryptionKey { get; set; } } \ No newline at end of file diff --git a/AutoStack.Infrastructure/Services/LocalFileStorageService.cs b/AutoStack.Infrastructure/Services/LocalFileStorageService.cs index 52fd861..f526ed8 100644 --- a/AutoStack.Infrastructure/Services/LocalFileStorageService.cs +++ b/AutoStack.Infrastructure/Services/LocalFileStorageService.cs @@ -5,6 +5,9 @@ namespace AutoStack.Infrastructure.Services; +/// +/// Local file system implementation of file storage service for avatar uploads +/// public class LocalFileStorageService : IFileStorageService { private readonly FileStorageOptions _options; diff --git a/AutoStack.Presentation/Middleware/CookieAuthenticationMiddleware.cs b/AutoStack.Presentation/Middleware/CookieAuthenticationMiddleware.cs index 93f1ade..8a00bf6 100644 --- a/AutoStack.Presentation/Middleware/CookieAuthenticationMiddleware.cs +++ b/AutoStack.Presentation/Middleware/CookieAuthenticationMiddleware.cs @@ -2,6 +2,10 @@ namespace AutoStack.Presentation.Middleware; +/// +/// Middleware that extracts access tokens from cookies and adds them to Authorization header +/// Enables browser-based authentication using cookies instead of requiring explicit Bearer token headers +/// public class CookieAuthenticationMiddleware { private readonly RequestDelegate _next; diff --git a/AutoStack.Presentation/Middleware/GlobalExceptionHandlerMiddleware.cs b/AutoStack.Presentation/Middleware/GlobalExceptionHandlerMiddleware.cs index cc32584..5295f66 100644 --- a/AutoStack.Presentation/Middleware/GlobalExceptionHandlerMiddleware.cs +++ b/AutoStack.Presentation/Middleware/GlobalExceptionHandlerMiddleware.cs @@ -7,6 +7,9 @@ namespace AutoStack.Presentation.Middleware; +/// +/// Global exception handler middleware that catches and logs unhandled exceptions +/// public class GlobalExceptionHandlerMiddleware( ILogger logger, IHostEnvironment environment) diff --git a/AutoStack.Presentation/Middleware/SecurityHeadersMiddleware.cs b/AutoStack.Presentation/Middleware/SecurityHeadersMiddleware.cs index 71faeb0..1c4c1fb 100644 --- a/AutoStack.Presentation/Middleware/SecurityHeadersMiddleware.cs +++ b/AutoStack.Presentation/Middleware/SecurityHeadersMiddleware.cs @@ -1,5 +1,8 @@ namespace AutoStack.Presentation.Middleware; +/// +/// Middleware that adds security headers to HTTP responses to protect against common web vulnerabilities +/// public class SecurityHeadersMiddleware { private readonly RequestDelegate _next; diff --git a/AutoStack.Presentation/Models/DisableTwoFactorRequest.cs b/AutoStack.Presentation/Models/DisableTwoFactorRequest.cs index 1ce618b..a4e876a 100644 --- a/AutoStack.Presentation/Models/DisableTwoFactorRequest.cs +++ b/AutoStack.Presentation/Models/DisableTwoFactorRequest.cs @@ -1,5 +1,10 @@ namespace AutoStack.Presentation.Models; +/// +/// Request model for disabling two-factor authentication +/// +/// The user's current password for verification +/// The current TOTP code for verification public record DisableTwoFactorRequest( string Password, string TotpCode diff --git a/AutoStack.Presentation/Models/RegenerateRecoveryCodesRequest.cs b/AutoStack.Presentation/Models/RegenerateRecoveryCodesRequest.cs index 6166c6b..d8cd9f3 100644 --- a/AutoStack.Presentation/Models/RegenerateRecoveryCodesRequest.cs +++ b/AutoStack.Presentation/Models/RegenerateRecoveryCodesRequest.cs @@ -1,5 +1,10 @@ namespace AutoStack.Presentation.Models; +/// +/// Request model for regenerating two-factor authentication recovery codes +/// +/// The user's current password for verification +/// The current TOTP code for verification public record RegenerateRecoveryCodesRequest( string Password, string TotpCode diff --git a/AutoStack.Presentation/Transformers/BearerSecuritySchemeTransformer.cs b/AutoStack.Presentation/Transformers/BearerSecuritySchemeTransformer.cs index 694ff4d..f591d8f 100644 --- a/AutoStack.Presentation/Transformers/BearerSecuritySchemeTransformer.cs +++ b/AutoStack.Presentation/Transformers/BearerSecuritySchemeTransformer.cs @@ -4,6 +4,9 @@ namespace AutoStack.Presentation.Transformers; +/// +/// OpenAPI document transformer that adds Bearer JWT authentication scheme to all endpoints +/// internal sealed class BearerSecuritySchemeTransformer : IOpenApiDocumentTransformer { private readonly IAuthenticationSchemeProvider _authenticationSchemeProvider; diff --git a/AutoStack.Presentation/Transformers/RemoveServerSidePropertiesTransformer.cs b/AutoStack.Presentation/Transformers/RemoveServerSidePropertiesTransformer.cs index b778354..ddca928 100644 --- a/AutoStack.Presentation/Transformers/RemoveServerSidePropertiesTransformer.cs +++ b/AutoStack.Presentation/Transformers/RemoveServerSidePropertiesTransformer.cs @@ -3,6 +3,9 @@ namespace AutoStack.Presentation.Transformers; +/// +/// OpenAPI document transformer that removes server-side properties from request schemas +/// internal sealed class RemoveServerSidePropertiesTransformer : IOpenApiDocumentTransformer { public Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)