From 8b0208573736648a74be8aef8d3487ddd2734ab7 Mon Sep 17 00:00:00 2001 From: "Fritz (Fredrick Seitz)" Date: Mon, 24 Jul 2023 13:28:22 -0400 Subject: [PATCH] chore: added more inline documentation --- src/Bulwark.Auth.Core/AccountManager.cs | 1 - src/Bulwark.Auth.Core/DefaultTokenizer.cs | 31 ++++++++++++++ src/Bulwark.Auth.Core/IAccountManager.cs | 1 - src/Bulwark.Auth.Core/TokenStrategyContext.cs | 41 +++++++++++++++++++ src/Bulwark.Auth.Core/VerificationToken.cs | 3 +- .../IAccountRepository.cs | 3 ++ .../IAuthorizationRepository.cs | 3 ++ .../ICertRepository.cs | 4 +- .../IMagicCodeRepository.cs | 4 ++ .../ITokenRepository.cs | 3 ++ .../AuthenticateTest.cs | 2 +- 11 files changed, 91 insertions(+), 5 deletions(-) diff --git a/src/Bulwark.Auth.Core/AccountManager.cs b/src/Bulwark.Auth.Core/AccountManager.cs index 9cfc504..a367820 100644 --- a/src/Bulwark.Auth.Core/AccountManager.cs +++ b/src/Bulwark.Auth.Core/AccountManager.cs @@ -3,7 +3,6 @@ using Bulwark.Auth.Core.Exception; using Bulwark.Auth.Repositories; using Bulwark.Auth.Repositories.Exception; -using Bulwark.Core; namespace Bulwark.Auth.Core; /// diff --git a/src/Bulwark.Auth.Core/DefaultTokenizer.cs b/src/Bulwark.Auth.Core/DefaultTokenizer.cs index ef781e8..efe4d32 100644 --- a/src/Bulwark.Auth.Core/DefaultTokenizer.cs +++ b/src/Bulwark.Auth.Core/DefaultTokenizer.cs @@ -34,6 +34,14 @@ public DefaultTokenizer(string issuer, string audience, Audience = audience; } + /// + /// This will creat an access token for a user with the given roles and permissions. + /// + /// + /// + /// + /// + /// public string CreateAccessToken(string userId, List roles, List permissions) { var cert = GetLatestCertGeneration(); @@ -62,6 +70,13 @@ public string CreateAccessToken(string userId, List roles, List return token; } + /// + /// This will create a refresh token for a user. Refresh tokens are longer lived tokens that can be used to + /// create new access tokens. + /// + /// + /// + /// public string CreateRefreshToken(string userId) { var cert = GetLatestCertGeneration(); @@ -85,6 +100,13 @@ public string CreateRefreshToken(string userId) return token; } + /// + /// This will validate a refresh or access token + /// + /// + /// + /// + /// public string ValidateToken(string userId, string token) { var handler = new JwtSecurityTokenHandler(); @@ -104,6 +126,10 @@ public string ValidateToken(string userId, string token) return json; } + /// + /// Gets the latest cert to generate a token with. + /// + /// private Certificate GetLatestCertGeneration() { if (_certificates.Count == 0) { return null; } @@ -111,6 +137,11 @@ private Certificate GetLatestCertGeneration() return _certificates[max]; } + /// + /// Will pull a cert for a specific generation. + /// + /// + /// private Certificate GetCertGeneration(int generation) { return _certificates[generation]; diff --git a/src/Bulwark.Auth.Core/IAccountManager.cs b/src/Bulwark.Auth.Core/IAccountManager.cs index a9abc75..90d8cc5 100644 --- a/src/Bulwark.Auth.Core/IAccountManager.cs +++ b/src/Bulwark.Auth.Core/IAccountManager.cs @@ -1,5 +1,4 @@ using System.Threading.Tasks; -using Bulwark.Core; namespace Bulwark.Auth.Core; diff --git a/src/Bulwark.Auth.Core/TokenStrategyContext.cs b/src/Bulwark.Auth.Core/TokenStrategyContext.cs index 778291f..cc0f5bf 100644 --- a/src/Bulwark.Auth.Core/TokenStrategyContext.cs +++ b/src/Bulwark.Auth.Core/TokenStrategyContext.cs @@ -4,6 +4,10 @@ namespace Bulwark.Auth.Core; +/// +/// This classes responsibility is to provide a strategy for token creation and validation based off different +/// algs, currently only supports RS256, but can be easily expanded to support more. +/// public class TokenStrategyContext { private readonly Dictionary _tokenizers; @@ -21,16 +25,33 @@ public TokenStrategyContext() _tokenizers = new Dictionary(); } + /// + /// allows the addition of different tokenizers + /// + /// public void Add(ITokenizer tokenizer) { _tokenizers.Add(tokenizer.Name, tokenizer); } + /// + /// will retrieve a specific tokenizer by name can be used to decide which algorithm to sign with + /// + /// + /// public ITokenizer GetTokenizer(string tokenizerName) { return _tokenizers[tokenizerName]; } + /// + /// This is the token that would be checked for proper authorization + /// + /// + /// + /// + /// + /// public string CreateAccessToken(string userId, List roles, List permissions, string name = "default") { @@ -38,6 +59,12 @@ public string CreateAccessToken(string userId, List roles, return tokenizer.CreateAccessToken(userId, roles, permissions); } + /// + /// Creates a refresh token a long lived token that can refresh access tokens + /// + /// + /// + /// public string CreateRefreshToken(string userId, string name = "default") { @@ -45,6 +72,13 @@ public string CreateRefreshToken(string userId, return tokenizer.CreateRefreshToken(userId); } + /// + /// Validates access tokens, this can be done at anytime to ensure an account has proper access + /// + /// + /// + /// + /// public AccessToken ValidateAccessToken(string userId, string token, string name = "default") { var json = _tokenizers[name].ValidateToken(userId,token); @@ -53,6 +87,13 @@ public AccessToken ValidateAccessToken(string userId, string token, string name return accessToken; } + /// + /// validates refresh token, validate refresh tokens before renewing access tokens + /// + /// + /// + /// + /// public RefreshToken ValidateRefreshToken(string userId, string token, string name = "default") { diff --git a/src/Bulwark.Auth.Core/VerificationToken.cs b/src/Bulwark.Auth.Core/VerificationToken.cs index 8f8321e..692b464 100644 --- a/src/Bulwark.Auth.Core/VerificationToken.cs +++ b/src/Bulwark.Auth.Core/VerificationToken.cs @@ -1,5 +1,6 @@ using System; -namespace Bulwark.Core + +namespace Bulwark.Auth.Core { public class VerificationToken { diff --git a/src/Bulwark.Auth.Repositories/IAccountRepository.cs b/src/Bulwark.Auth.Repositories/IAccountRepository.cs index 48eba0a..aa2a97b 100644 --- a/src/Bulwark.Auth.Repositories/IAccountRepository.cs +++ b/src/Bulwark.Auth.Repositories/IAccountRepository.cs @@ -1,6 +1,9 @@ using Bulwark.Auth.Repositories.Model; namespace Bulwark.Auth.Repositories; +/// +/// Data layer for account management. +/// public interface IAccountRepository { Task Create(string email, string password); diff --git a/src/Bulwark.Auth.Repositories/IAuthorizationRepository.cs b/src/Bulwark.Auth.Repositories/IAuthorizationRepository.cs index 7e7a259..93f1592 100644 --- a/src/Bulwark.Auth.Repositories/IAuthorizationRepository.cs +++ b/src/Bulwark.Auth.Repositories/IAuthorizationRepository.cs @@ -1,5 +1,8 @@ namespace Bulwark.Auth.Repositories; +/// +/// Data layer for authorizations. +/// public interface IAuthorizationRepository { Task> ReadAccountPermissions(string userId); diff --git a/src/Bulwark.Auth.Repositories/ICertRepository.cs b/src/Bulwark.Auth.Repositories/ICertRepository.cs index f780707..4f26068 100644 --- a/src/Bulwark.Auth.Repositories/ICertRepository.cs +++ b/src/Bulwark.Auth.Repositories/ICertRepository.cs @@ -1,10 +1,12 @@ using Bulwark.Auth.Repositories.Model; namespace Bulwark.Auth.Repositories; +/// +/// Manages certificates for signing JWTs. +/// public interface ICertRepository { void AddCert(string privateKey, string publicKey); - void DeleteCert(int generation); CertModel GetCert(int generation); CertModel GetLatestCert(); List GetAllCerts(); diff --git a/src/Bulwark.Auth.Repositories/IMagicCodeRepository.cs b/src/Bulwark.Auth.Repositories/IMagicCodeRepository.cs index 18a6908..6b3c441 100644 --- a/src/Bulwark.Auth.Repositories/IMagicCodeRepository.cs +++ b/src/Bulwark.Auth.Repositories/IMagicCodeRepository.cs @@ -1,6 +1,10 @@ using Bulwark.Auth.Repositories.Model; namespace Bulwark.Auth.Repositories; + +/// +/// Used to create and use magic codes +/// public interface IMagicCodeRepository { Task Add(string userId, string code, DateTime expires); diff --git a/src/Bulwark.Auth.Repositories/ITokenRepository.cs b/src/Bulwark.Auth.Repositories/ITokenRepository.cs index d823360..0d1743f 100644 --- a/src/Bulwark.Auth.Repositories/ITokenRepository.cs +++ b/src/Bulwark.Auth.Repositories/ITokenRepository.cs @@ -1,6 +1,9 @@ using Bulwark.Auth.Repositories.Model; namespace Bulwark.Auth.Repositories; +/// +/// Database token management +/// public interface ITokenRepository { Task Delete(string userId, string deviceId); diff --git a/tests/Bulwark.Auth.Core.Tests/AuthenticateTest.cs b/tests/Bulwark.Auth.Core.Tests/AuthenticateTest.cs index e72bc6f..63ed56d 100644 --- a/tests/Bulwark.Auth.Core.Tests/AuthenticateTest.cs +++ b/tests/Bulwark.Auth.Core.Tests/AuthenticateTest.cs @@ -46,7 +46,7 @@ public async void AuthenticateWithWrongPassword() var authenticated = await _authentication.Authenticate(_user, "wrongpassword"); } - catch(BulwarkAuthenticationException exception) + catch(BulwarkAuthenticationException) { Assert.True(true); }