@chill-sharp/ui-core 1.1.12

package/doc/AuthenticationModel/README.md

@@ -0,0 +1,213 @@
+# ChillSharp Authentication And Authorization
+
+Versione italiana: [Italiano](../it/AuthenticationModel/README.md)
+
+This document covers the auth module at a reference level. For a guided setup, keep using [doc/HowTo/03-authentication.md](../HowTo/03-authentication.md).
+
+## Module Split
+
+`ChillSharp.Auth` exposes two related but distinct concerns:
+
+- account authentication
+  ASP.NET Core Identity-backed register, login, refresh, password-change, and password-reset flows
+
+- authorization management
+  auth users, roles, role assignments, permission rules, and permission evaluation
+
+## Account Endpoints
+
+Registered through:
+
+```csharp
+builder.Services.AddChillAuthIdentityApi<AppDbContext, IdentityUser>();
+```
+
+Typical routes:
+
+- `/api/chill-auth/account/register`
+- `/api/chill-auth/account/login`
+- `/api/chill-auth/account/refresh`
+- `/api/chill-auth/account/change-password`
+- `/api/chill-auth/account/request-password-reset`
+- `/api/chill-auth/account/reset-password`
+
+These are the routes used internally by `ChillSharpClient`.
+
+`RegisterAuthIdentityRequest` also supports:
+
+- `DisplayName`
+- `DisplayCultureName`
+- `CreateChillAuthUser`
+
+When `CreateChillAuthUser` is enabled and `DisplayCultureName` is provided, the linked `AuthUser` is automatically preset with:
+
+- `DisplayCultureName`
+- `DisplayTimeZone`
+- `DisplayDateFormat`
+- `DisplayNumberFormat`
+
+The server resolves those defaults from the selected culture by using a best-effort time-zone mapping plus the culture date and number separators.
+
+## Authorization Management Endpoints
+
+Registered through:
+
+```csharp
+builder.Services.AddChillAuthApi<AppDbContext>();
+```
+
+Typical route groups:
+
+- `/api/chill-auth/users`
+- `/api/chill-auth/roles`
+- `/api/chill-auth/permissions`
+
+These endpoints manage:
+
+- `AuthUser`
+- `AuthRole`
+- `AuthUserRole`
+- `AuthPermissionRule`
+- permission evaluation results
+
+`AuthUser` now also carries optional UI display preferences:
+
+- `DisplayCultureName`
+- `DisplayTimeZone`
+- `DisplayDateFormat`
+- `DisplayNumberFormat`
+
+`AuthUser` and `AuthRole` also carry:
+
+- `MenuHierarchy`
+
+`MenuHierarchy` is used by the schema menu endpoints to filter which menu nodes are visible to the current user.
+
+- values can be single codes or comma-separated lists
+- user and active role values are merged before filtering
+- `*` means full menu access
+- any other value works as a prefix match, for example `SECTION-A` allows nodes whose menu hierarchy starts with `SECTION-A`
+- an empty merged menu hierarchy set means no menu access
+
+For the full menu-tree model and endpoint behavior, see [MenuGuide/README.md](../MenuGuide/README.md).
+
+## Token Lifetimes
+
+ChillSharp auth account endpoints issue protected bearer access tokens and refresh tokens. These access tokens are not JWTs, but they are used in the same `Authorization: Bearer ...` header shape.
+
+Default lifetimes:
+
+- access token: 20 minutes
+- refresh token: 14 days
+
+Built-in environment variables:
+
+- `CHILLSHARP_AUTH_ACCESS_TOKEN_MINUTES`
+  Positive integer number of minutes before an access token expires.
+- `CHILLSHARP_AUTH_REFRESH_TOKEN_DAYS`
+  Positive integer number of days before a refresh token expires.
+
+These variables are read by `ChillAuthIdentityApiOptions` and `ChillIdentityApiOptions` when the options object is created. Explicit code configuration still wins:
+
+```csharp
+builder.Services.AddChillAuthIdentityApi<AppDbContext, IdentityUser>(options =>
+{
+    options.AccessTokenLifetime = TimeSpan.FromMinutes(30);
+    options.RefreshTokenLifetime = TimeSpan.FromDays(7);
+});
+```
+
+## Context Requirements
+
+The host context must:
+
+- implement `IChillAuthDbContext`
+- include `modelBuilder.AddChillAuthModel()`
+
+For Identity-backed accounts, the context must also be a valid EF store for ASP.NET Core Identity, typically:
+
+```csharp
+public class AppDbContext : IdentityDbContext<IdentityUser>, IChillContext, IChillAuthDbContext
+{
+}
+```
+
+## Root User Bootstrap
+
+`AddChillAuthIdentityApi(...)` can bootstrap a root account on startup.
+
+Supported configuration:
+
+- direct options in code
+- environment variables
+
+Default environment variables:
+
+- `CHILLSHARP_AUTH_ROOT_USERNAME`
+- `CHILLSHARP_AUTH_ROOT_PASSWORD`
+- `CHILLSHARP_AUTH_ROOT_EMAIL`
+- `CHILLSHARP_AUTH_ROOT_DISPLAY_NAME`
+
+When enabled, the bootstrap flow can also create the linked ChillSharp `AuthUser` with permission-management access.
+
+## Permission Management Access
+
+Being authenticated is not enough to manage the auth module.
+
+Auth-management endpoints require a ChillSharp auth user with permission-management rights, typically:
+
+- `CanManagePermissions = true`
+
+This is the critical bootstrap problem for a clean database:
+
+- the first registered Identity user may exist
+- the linked `AuthUser` may exist
+- but no one may yet have rights to manage roles and permissions
+
+That is why root-user bootstrap or another trusted setup path matters.
+
+## Client Usage
+
+Use the normal Chill base URL:
+
+```csharp
+var client = new ChillSharpClient("http://localhost:5000/api/chill");
+```
+
+`ChillSharpClient` automatically switches to `/api/chill-auth/...` for auth methods.
+
+Examples:
+
+- `RegisterAuthAccount`
+- `LoginAuthAccount`
+- `RefreshAuthAccount`
+- `ChangeAuthPassword`
+- `CreateAuthRole`
+- `CreateAuthPermissionRule`
+- `EvaluateAuthEntityPermission`
+
+User list and user detail payloads also expose:
+
+- `DisplayCultureName`
+- `DisplayTimeZone`
+- `DisplayDateFormat`
+- `DisplayNumberFormat`
+
+## Token Handling
+
+`ChillSharpClient` stores:
+
+- access token
+- refresh token
+
+If a refresh token is present, the client can renew the access token automatically during later authenticated calls.
+
+## Relationship With The Permission Model
+
+The exact permission-resolution rules are documented separately in:
+
+- [PermissionModel/README.md](../PermissionModel/README.md)
+
+Use that document for the precedence and scope model. Use this one for registration and runtime auth flow.
+
+

package/doc/AuthenticationModel/how-to-integreate-auth-minimal-api.md

@@ -0,0 +1,293 @@
+Versione italiana: [Italiano](../it/AuthenticationModel/how-to-integreate-auth-minimal-api.md)
+
+Sure. Here’s the updated, correct, modern version of the setup using **Microsoft.IdentityModel.JsonWebTokens**, because Microsoft decided the old JWT library needed to be “legacy” for fun.
+
+This is the clean way to do:
+
+✅ Identity user store
+✅ Minimal API login/register
+✅ JWT Bearer tokens
+✅ No cookies
+✅ No UI
+✅ No outdated JwtSecurityTokenHandler
+
+---
+
+# ✅ ASP.NET Core Minimal Identity API + JWT (Modern JsonWebTokenHandler)
+
+---
+
+# ✅ 1. Install Packages
+
+Run:
+
+```bash
+dotnet add package Microsoft.AspNetCore.Identity.EntityFrameworkCore
+dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
+dotnet add package Microsoft.EntityFrameworkCore.SqlServer
+dotnet add package Microsoft.IdentityModel.JsonWebTokens
+```
+
+No `System.IdentityModel.Tokens.Jwt`. We are enlightened now.
+
+---
+
+# ✅ 2. Create Identity DbContext
+
+```csharp
+using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore;
+
+public class AppDbContext : IdentityDbContext
+{
+    public AppDbContext(DbContextOptions<AppDbContext> options)
+        : base(options) { }
+}
+```
+
+---
+
+# ✅ 3. Configure Database + IdentityCore
+
+In `Program.cs`:
+
+```csharp
+builder.Services.AddDbContext<AppDbContext>(options =>
+    options.UseSqlServer(builder.Configuration.GetConnectionString("Default")));
+```
+
+Now add Identity:
+
+```csharp
+builder.Services.AddIdentityCore<IdentityUser>()
+    .AddEntityFrameworkStores<AppDbContext>()
+    .AddDefaultTokenProviders();
+```
+
+✅ No UI
+✅ No Razor
+✅ No cookie circus
+
+---
+
+# ✅ 4. Configure JWT Authentication (Bearer)
+
+Add imports:
+
+```csharp
+using Microsoft.AspNetCore.Authentication.JwtBearer;
+using Microsoft.IdentityModel.Tokens;
+using System.Text;
+```
+
+Then:
+
+```csharp
+var jwtKey = builder.Configuration["Jwt:Key"]!;
+var jwtIssuer = builder.Configuration["Jwt:Issuer"]!;
+```
+
+Now configure:
+
+```csharp
+builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
+    .AddJwtBearer(options =>
+    {
+        options.TokenValidationParameters = new TokenValidationParameters
+        {
+            ValidateIssuer = true,
+            ValidIssuer = jwtIssuer,
+
+            ValidateAudience = false,
+
+            ValidateIssuerSigningKey = true,
+            IssuerSigningKey = new SymmetricSecurityKey(
+                Encoding.UTF8.GetBytes(jwtKey)),
+
+            ValidateLifetime = true
+        };
+    });
+```
+
+---
+
+# ✅ 5. Enable Authorization
+
+```csharp
+builder.Services.AddAuthorization();
+```
+
+---
+
+# ✅ 6. Add Middleware
+
+After `var app = builder.Build();`
+
+```csharp
+app.UseAuthentication();
+app.UseAuthorization();
+```
+
+If you skip this, nothing works and you’ll blame yourself, incorrectly.
+
+---
+
+# ✅ 7. Generate JWT Token (Modern JsonWebTokenHandler)
+
+Add imports:
+
+```csharp
+using Microsoft.IdentityModel.JsonWebTokens;
+using System.Security.Claims;
+```
+
+Now define:
+
+```csharp
+string GenerateJwtToken(IdentityUser user)
+{
+    var claims = new List<Claim>
+    {
+        new Claim(JwtRegisteredClaimNames.Sub, user.Id),
+        new Claim(JwtRegisteredClaimNames.Email, user.Email!)
+    };
+
+    var key = new SymmetricSecurityKey(
+        Encoding.UTF8.GetBytes(jwtKey));
+
+    var creds = new SigningCredentials(
+        key,
+        SecurityAlgorithms.HmacSha256);
+
+    var tokenDescriptor = new SecurityTokenDescriptor
+    {
+        Subject = new ClaimsIdentity(claims),
+        Expires = DateTime.UtcNow.AddHours(2),
+        Issuer = jwtIssuer,
+        SigningCredentials = creds
+    };
+
+    var handler = new JsonWebTokenHandler();
+
+    return handler.CreateToken(tokenDescriptor);
+}
+```
+
+✅ This is the replacement for the old JwtSecurityTokenHandler.
+
+---
+
+# ✅ 8. Register Endpoint (Minimal API)
+
+```csharp
+app.MapPost("/register", async (
+    UserManager<IdentityUser> userManager,
+    RegisterRequest request) =>
+{
+    var user = new IdentityUser
+    {
+        UserName = request.Email,
+        Email = request.Email
+    };
+
+    var result = await userManager.CreateAsync(user, request.Password);
+
+    if (!result.Succeeded)
+        return Results.BadRequest(result.Errors);
+
+    return Results.Ok("User registered");
+});
+```
+
+---
+
+# ✅ 9. Login Endpoint (Returns JWT)
+
+```csharp
+app.MapPost("/login", async (
+    UserManager<IdentityUser> userManager,
+    LoginRequest request) =>
+{
+    var user = await userManager.FindByEmailAsync(request.Email);
+
+    if (user == null)
+        return Results.Unauthorized();
+
+    var valid = await userManager.CheckPasswordAsync(user, request.Password);
+
+    if (!valid)
+        return Results.Unauthorized();
+
+    var token = GenerateJwtToken(user);
+
+    return Results.Ok(new { token });
+});
+```
+
+---
+
+# ✅ 10. Protect an Endpoint
+
+```csharp
+app.MapGet("/me", (ClaimsPrincipal user) =>
+{
+    var email = user.FindFirst(ClaimTypes.Email)?.Value;
+
+    return Results.Ok(new { email });
+})
+.RequireAuthorization();
+```
+
+---
+
+# ✅ 11. Add Request Models
+
+```csharp
+public record RegisterRequest(string Email, string Password);
+
+public record LoginRequest(string Email, string Password);
+```
+
+---
+
+# ✅ 12. Configure appsettings.json
+
+```json
+"Jwt": {
+  "Key": "REPLACE_WITH_A_REAL_SECRET_32+_CHARS",
+  "Issuer": "MyApiAuthServer"
+}
+```
+
+Make the key long and random, unless you want attackers logging in as you for sport.
+
+---
+
+# ✅ Result
+
+Now you have:
+
+✅ `/register`
+✅ `/login` → returns JWT
+✅ Protected endpoints with Bearer token
+✅ Identity user store in SQL
+✅ No cookies
+✅ No UI
+✅ No legacy JWT handler
+
+---
+
+# If You Want Next Steps
+
+The moment you want:
+
+* Refresh tokens
+* Roles + claims
+* Password reset endpoints
+* Email confirmation
+* `/logout` with JWT invalidation (annoying)
+
+Then authentication becomes a *real* system, not a demo.
+
+Still, this setup is the clean foundation Microsoft should’ve shipped by default.
+