chore: added more inline documentation

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;
 /// <summary>

src/Bulwark.Auth.Core/DefaultTokenizer.cs

@@ -34,6 +34,14 @@ public DefaultTokenizer(string issuer, string audience,
  Audience = audience;
  }
 
+ /// <summary>
+ /// This will creat an access token for a user with the given roles and permissions.
+ /// </summary>
+ /// <param name="userId"></param>
+ /// <param name="roles"></param>
+ /// <param name="permissions"></param>
+ /// <returns></returns>
+ /// <exception cref="BulwarkTokenException"></exception>
  public string CreateAccessToken(string userId, List<string> roles, List<string> permissions)
  {
  var cert = GetLatestCertGeneration();
@@ -62,6 +70,13 @@ public string CreateAccessToken(string userId, List<string> roles, List<string>
  return token;
  }
 
+ /// <summary>
+ /// This will create a refresh token for a user. Refresh tokens are longer lived tokens that can be used to
+ /// create new access tokens.
+ /// </summary>
+ /// <param name="userId"></param>
+ /// <returns></returns>
+ /// <exception cref="BulwarkTokenException"></exception>
  public string CreateRefreshToken(string userId)
  {
  var cert = GetLatestCertGeneration();
@@ -85,6 +100,13 @@ public string CreateRefreshToken(string userId)
  return token;
  }
 
+ /// <summary>
+ /// This will validate a refresh or access token 
+ /// </summary>
+ /// <param name="userId"></param>
+ /// <param name="token"></param>
+ /// <returns></returns>
+ /// <exception cref="BulwarkTokenException"></exception>
  public string ValidateToken(string userId, string token)
  {
  var handler = new JwtSecurityTokenHandler();
@@ -104,13 +126,22 @@ public string ValidateToken(string userId, string token)
 
  return json;
  }
+ /// <summary>
+ /// Gets the latest cert to generate a token with.
+ /// </summary>
+ /// <returns></returns>
  private Certificate GetLatestCertGeneration()
  {
  if (_certificates.Count == 0) { return null; }
  var max = _certificates.Keys.Max();
  return _certificates[max];
  }
 
+ /// <summary>
+ /// Will pull a cert for a specific generation.
+ /// </summary>
+ /// <param name="generation"></param>
+ /// <returns></returns>
  private Certificate GetCertGeneration(int generation)
  {
  return _certificates[generation];

src/Bulwark.Auth.Core/IAccountManager.cs

@@ -1,5 +1,4 @@
 using System.Threading.Tasks;
-using Bulwark.Core;
 
 namespace Bulwark.Auth.Core;
 

src/Bulwark.Auth.Core/TokenStrategyContext.cs

@@ -4,6 +4,10 @@
 
 namespace Bulwark.Auth.Core;
 
+/// <summary>
+/// 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.
+/// </summary>
 public class TokenStrategyContext
 {
  private readonly Dictionary<string, ITokenizer> _tokenizers;
@@ -21,30 +25,60 @@ public TokenStrategyContext()
  _tokenizers = new Dictionary<string, ITokenizer>();
  }
 
+ /// <summary>
+ /// allows the addition of different tokenizers
+ /// </summary>
+ /// <param name="tokenizer"></param>
  public void Add(ITokenizer tokenizer)
  {
  _tokenizers.Add(tokenizer.Name, tokenizer);
  }
 
+ /// <summary>
+ /// will retrieve a specific tokenizer by name can be used to decide which algorithm to sign with
+ /// </summary>
+ /// <param name="tokenizerName"></param>
+ /// <returns></returns>
  public ITokenizer GetTokenizer(string tokenizerName)
  {
  return _tokenizers[tokenizerName];
  }
 
+ /// <summary>
+ /// This is the token that would be checked for proper authorization
+ /// </summary>
+ /// <param name="userId"></param>
+ /// <param name="roles"></param>
+ /// <param name="permissions"></param>
+ /// <param name="name"></param>
+ /// <returns></returns>
  public string CreateAccessToken(string userId, List<string> roles, 
  List<string> permissions, string name = "default")
  {
  var tokenizer = _tokenizers[name];
  return tokenizer.CreateAccessToken(userId, roles, permissions);
  }
 
+ /// <summary>
+ /// Creates a refresh token a long lived token that can refresh access tokens
+ /// </summary>
+ /// <param name="userId"></param>
+ /// <param name="name"></param>
+ /// <returns></returns>
  public string CreateRefreshToken(string userId,
  string name = "default")
  {
  var tokenizer = _tokenizers[name];
  return tokenizer.CreateRefreshToken(userId);
  }
 
+ /// <summary>
+ /// Validates access tokens, this can be done at anytime to ensure an account has proper access
+ /// </summary>
+ /// <param name="userId"></param>
+ /// <param name="token"></param>
+ /// <param name="name"></param>
+ /// <returns></returns>
  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;
  }
 
+ /// <summary>
+ /// validates refresh token, validate refresh tokens before renewing access tokens
+ /// </summary>
+ /// <param name="userId"></param>
+ /// <param name="token"></param>
+ /// <param name="name"></param>
+ /// <returns></returns>
  public RefreshToken ValidateRefreshToken(string userId, string token,
  string name = "default")
  {

src/Bulwark.Auth.Core/VerificationToken.cs

@@ -1,5 +1,6 @@
 using System;
-namespace Bulwark.Core
+
+namespace Bulwark.Auth.Core
 {
  public class VerificationToken
  {

src/Bulwark.Auth.Repositories/IAccountRepository.cs

@@ -1,6 +1,9 @@
 using Bulwark.Auth.Repositories.Model;
 
 namespace Bulwark.Auth.Repositories;
+/// <summary>
+/// Data layer for account management.
+/// </summary>
 public interface IAccountRepository
 {
  Task<VerificationModel> Create(string email, string password);

src/Bulwark.Auth.Repositories/IAuthorizationRepository.cs

@@ -1,5 +1,8 @@
 namespace Bulwark.Auth.Repositories;
 
+/// <summary>
+/// Data layer for authorizations.
+/// </summary>
 public interface IAuthorizationRepository
 {
  Task<List<string>> ReadAccountPermissions(string userId);

src/Bulwark.Auth.Repositories/ICertRepository.cs

@@ -1,10 +1,12 @@
 using Bulwark.Auth.Repositories.Model;
 
 namespace Bulwark.Auth.Repositories;
+/// <summary>
+/// Manages certificates for signing JWTs.
+/// </summary>
 public interface ICertRepository
 {
  void AddCert(string privateKey, string publicKey);
- void DeleteCert(int generation);
  CertModel GetCert(int generation);
  CertModel GetLatestCert();
  List<CertModel> GetAllCerts();

src/Bulwark.Auth.Repositories/IMagicCodeRepository.cs

@@ -1,6 +1,10 @@
 using Bulwark.Auth.Repositories.Model;
 
 namespace Bulwark.Auth.Repositories;
+
+/// <summary>
+/// Used to create and use magic codes
+/// </summary>
 public interface IMagicCodeRepository
 {
  Task Add(string userId, string code, DateTime expires);

src/Bulwark.Auth.Repositories/ITokenRepository.cs

@@ -1,6 +1,9 @@
 using Bulwark.Auth.Repositories.Model;
 
 namespace Bulwark.Auth.Repositories;
+/// <summary>
+/// Database token management
+/// </summary>
 public interface ITokenRepository
 {
  Task Delete(string userId, string deviceId);

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);
  }