diff --git a/docs/Diagrams/Models/ApiModels.puml b/docs/Diagrams/Models/ApiModels.puml index 2019855..bb5d25a 100644 --- a/docs/Diagrams/Models/ApiModels.puml +++ b/docs/Diagrams/Models/ApiModels.puml @@ -13,12 +13,6 @@ namespace HopFrame.Security { } } -namespace HopFrame.Web { - class RegisterData { - +RepeatedPassword: string - } -} - namespace HopFrame.Api { class SingleValueResult { +Value: TValue @@ -29,6 +23,4 @@ namespace HopFrame.Api { } } -UserRegister <|-- RegisterData - @enduml \ No newline at end of file diff --git a/docs/Diagrams/Models/DatabaseModels.puml b/docs/Diagrams/Models/DatabaseModels.puml index fc3a7b9..2e47b5b 100644 --- a/docs/Diagrams/Models/DatabaseModels.puml +++ b/docs/Diagrams/Models/DatabaseModels.puml @@ -11,9 +11,6 @@ namespace HopFrame.Database { } class TokenEntry { - {static} +RefreshTokenType: int = 0 - {static} +AccessTokenType: int = 1 - +Type: int +Token: string +UserId: string diff --git a/docs/Diagrams/Models/img/ApiModels.svg b/docs/Diagrams/Models/img/ApiModels.svg index 82ff3c0..76a19b4 100644 --- a/docs/Diagrams/Models/img/ApiModels.svg +++ b/docs/Diagrams/Models/img/ApiModels.svg @@ -1 +1 @@ -HopFrameSecurityWebApiUserLoginEmail: stringPassword: stringUserRegisterUsername: stringEmail: stringPassword: stringRegisterDataRepeatedPassword: stringSingleValueResultTValueValue: TValueUserPasswordValidationPassword: string \ No newline at end of file +HopFrameSecurityApiUserLoginEmail: stringPassword: stringUserRegisterUsername: stringEmail: stringPassword: stringSingleValueResultTValueValue: TValueUserPasswordValidationPassword: string \ No newline at end of file diff --git a/docs/Diagrams/Models/img/DatabaseModels.svg b/docs/Diagrams/Models/img/DatabaseModels.svg index 06aa882..fedbd56 100644 --- a/docs/Diagrams/Models/img/DatabaseModels.svg +++ b/docs/Diagrams/Models/img/DatabaseModels.svg @@ -1 +1 @@ -HopFrame.DatabaseUserEntryId: stringUsername: stringEmail: stringPassword: stringCreatedAt: DateTimeTokenEntryRefreshTokenType: int = 0AccessTokenType: int = 1 Type: intToken: stringUserId: stringCreatedAt: DateTimePermissionEntryRecordId: longPermissionText: stringUserId: stringGrantedAt: DateTimeGroupEntryName: stringDefault: boolDescription: stringCreatedAt: DateTime \ No newline at end of file +HopFrame.DatabaseUserEntryId: stringUsername: stringEmail: stringPassword: stringCreatedAt: DateTimeTokenEntryType: intToken: stringUserId: stringCreatedAt: DateTimePermissionEntryRecordId: longPermissionText: stringUserId: stringGrantedAt: DateTimeGroupEntryName: stringDefault: boolDescription: stringCreatedAt: DateTime \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..eb4fa47 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,13 @@ +# HopFrame documentation +These sides contain all documentation available for the HopFrame modules + +## Content +| Topic | Description | Document | +|----------|------------------------------------------------|-----------------------| +| Models | All models used by the HopFrame | [link](./models.md) | +| Services | All services provided by the HopFrame | [link](./services.md) | +| Usage | How to properly implement the HopFrame modules | [link](./usage.md) | + +## Dependencies +Both the HopFrame.Api and HopFrame.Web modules are dependent on the HopFrame.Database and HopFrame.Security modules. +So all models and services provided by these modules are available in the other modules as well. diff --git a/docs/Models/README.md b/docs/models.md similarity index 70% rename from docs/Models/README.md rename to docs/models.md index 03273b6..6af77a4 100644 --- a/docs/Models/README.md +++ b/docs/models.md @@ -6,16 +6,16 @@ This page shows all models that HopFrame uses. ## Base Models These are the models used by the various database services. -![](../Diagrams/Models/img/BaseModels.svg) +![](./Diagrams/Models/img/BaseModels.svg) ## API Models These are the models used by the REST API and the Blazor API. -![](../Diagrams/Models/img/ApiModels.svg) +![](./Diagrams/Models/img/ApiModels.svg) ## Database Models These are the models that correspond to the scheme in the Database -![](../Diagrams/Models/img/DatabaseModels.svg) +![](./Diagrams/Models/img/DatabaseModels.svg) diff --git a/docs/services.md b/docs/services.md new file mode 100644 index 0000000..81a7312 --- /dev/null +++ b/docs/services.md @@ -0,0 +1,145 @@ +# HopFrame Services +This page describes all services provided by the HopFrame. +You can use these services by specifying them as a dependency. All of them are scoped dependencies. + +## HopFrame.Security +### ITokenContext +This service provides the information given by the current request + +```csharp +public interface ITokenContext { + bool IsAuthenticated { get; } + + User User { get; } + + Guid AccessToken { get; } +} +``` + +### IUserService +This service simplifies the data access of the user table in the database. + +```csharp +public interface IUserService { + Task> GetUsers(); + + Task GetUser(Guid userId); + + Task GetUserByEmail(string email); + + Task GetUserByUsername(string username); + + Task AddUser(UserRegister user); + + Task UpdateUser(User user); + + Task DeleteUser(User user); + + Task CheckUserPassword(User user, string password); + + Task ChangePassword(User user, string password); +} +``` + +### IPermissionService +This service handles all permission and group interactions with the data source. + +```csharp +public interface IPermissionService { + Task HasPermission(string permission, Guid user); + + Task> GetPermissionGroups(); + + Task GetPermissionGroup(string name); + + Task EditPermissionGroup(PermissionGroup group); + + Task> GetUserPermissionGroups(User user); + + Task RemoveGroupFromUser(User user, PermissionGroup group); + + Task CreatePermissionGroup(string name, bool isDefault = false, string description = null); + + Task DeletePermissionGroup(PermissionGroup group); + + Task GetPermission(string name, IPermissionOwner owner); + + Task AddPermission(IPermissionOwner owner, string permission); + + Task RemovePermission(Permission permission); + + Task GetFullPermissions(string user); +} +``` + +## HopFrame.Api +### LogicResult +Logic result is an extension of the ActionResult for an ApiController. It provides simple Http status results with either a message or data by specifying the generic type. + +```csharp +public class LogicResult : ILogicResult { + public static LogicResult Ok(); + + public static LogicResult BadRequest(); + + public static LogicResult BadRequest(string message); + + public static LogicResult Forbidden(); + + public static LogicResult Forbidden(string message); + + public static LogicResult NotFound(); + + public static LogicResult NotFound(string message); + + public static LogicResult Conflict(); + + public static LogicResult Conflict(string message); + + public static LogicResult Forward(LogicResult result); + + public static LogicResult Forward(ILogicResult result); + + public static implicit operator ActionResult(LogicResult v); +} + +public class LogicResult : ILogicResult { + public static LogicResult Ok(); + + public static LogicResult Ok(T result); + + ... +} +``` + +### IAuthLogic +This service handles all logic needed to provide the authentication endpoints by using the LogicResults. + +```csharp +public interface IAuthLogic { + Task>> Login(UserLogin login); + + Task>> Register(UserRegister register); + + Task>> Authenticate(); + + Task Logout(); + + Task Delete(UserPasswordValidation validation); +} +``` + +## HopFrame.Web +### IAuthService +This service handles all the authentication like login or register. It properly creates all tokens so the user can be identified + +```csharp +public interface IAuthService { + Task Register(UserRegister register); + Task Login(UserLogin login); + Task Logout(); + + Task RefreshLogin(); + Task IsLoggedIn(); +} +``` diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..2023531 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,70 @@ +# HopFrame Usage +There are two different versions of HopFrame, either the Web API version or the full Blazor web version. + +## Ho to use the Web API version + +1. Add the HopFrame.Api library to your project: + + ``` + dotnet add package HopFrame.Api + ``` + +2. Create a DbContext that inherits the ``HopDbContext`` and add a data source + + ```csharp + public class DatabaseContext : HopDbContextBase { + protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) { + base.OnConfiguring(optionsBuilder); + + optionsBuilder.UseSqlite("..."); + } + } + ``` + +3. Add the DbContext and HopFrame to your services + + ```csharp + builder.Services.AddDbContext(); + builder.Services.AddHopFrame(); + ``` + +## How to use the Blazor API + +1. Add the HopFrame.Web library to your project + + ``` + dotnet add package HopFrame.Web + ``` + +2. Create a DbContext that inherits the ``HopDbContext`` and add a data source + + ```csharp + public class DatabaseContext : HopDbContextBase { + protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) { + base.OnConfiguring(optionsBuilder); + + optionsBuilder.UseSqlite("..."); + } + } + ``` + +3. Add the DbContext and HopFrame to your services + + ```csharp + builder.Services.AddDbContext(); + builder.Services.AddHopFrame(); + ``` + +4. Add the authentication middleware to your app + + ```csharp + app.UseMiddleware(); + ``` + +5. Add the HopFrame pages to your Razor components + + ```csharp + app.MapRazorComponents() + .AddHopFrameAdminPages() + .AddInteractiveServerRenderMode(); + ```