Linger.AspNetCore.Jwt 1.0.2-preview

Linger.AspNetCore.Jwt

Lightweight helpers for issuing and refreshing JWT access tokens in ASP.NET Core.

Features

• Clean core IJwtService + opt-in refresh via IRefreshableJwtService
• Pluggable refresh token persistence (memory / DB / custom)
• Environment variable SECRET overrides config key
• Short-lived access tokens, long-lived refresh tokens
• Adds jti & iat claims for replay protection & auditing

Platform

.NET 8+.
Install from NuGet (package name placeholder):

dotnet add package Linger.AspNetCore.Jwt

Installation

In Program.cs:

// Read JwtOptions & configure authentication
var jwtOptions = builder.Configuration.GetSection("JwtOptions").Get<JwtOption>()!;
builder.Services.AddSingleton(jwtOptions);

builder.Services.AddAuthentication().AddJwtBearer(jwtOptions);

// Choose ONE registration style
// 1. Basic (no refresh)
builder.Services.AddScoped<IJwtService, JwtService>();

// 2. Custom claims (no refresh)
builder.Services.AddScoped<IJwtService, CustomJwtService>();

// 3. Refresh (memory cache)
builder.Services.AddMemoryCache();
builder.Services.AddScoped<IRefreshableJwtService, MemoryCachedJwtService>();
builder.Services.AddScoped<IJwtService>(sp => sp.GetRequiredService<IRefreshableJwtService>());

appsettings.json (minimal):

{
  "JwtOptions": {
    "SecurityKey": "your-32+chars-secret",
    "Issuer": "your-app",
    "Audience": "your-api",
    "ExpiresInMinutes": 15,
    "RefreshTokenExpiresInMinutes": 10080,
    "EnableRefreshToken": true
  }
}

Environment precedence: SECRET env var > JwtOptions:SecurityKey.

JwtOption

public sealed class JwtOption
{
    public string SecurityKey { get; set; } = null!;  // MUST set in production!
    public string Issuer { get; set; } = "example";
    public string Audience { get; set; } = "example";
    public int ExpiresInMinutes { get; set; } = 30;               // Token expiration (minutes)
    public int RefreshTokenExpiresInMinutes { get; set; } = 10080; // Refresh token expiration (minutes, 7 days)
    public bool EnableRefreshToken { get; set; } = true;
}

Custom Claims

Extend JwtService or override GetClaimsAsync:

sealed class CustomJwtService(AppDbContext db, JwtOption opt, ILogger<CustomJwtService> logger)
    : JwtService(opt, logger)
{
    protected override async Task<List<Claim>> GetClaimsAsync(string userId)
    {
        var claims = new List<Claim> { new(ClaimTypes.Name, userId) };
        var user = await db.Users.FindAsync(userId);
        if (user is not null)
        {
            foreach (var role in user.Roles.Split(','))
            {
                claims.Add(new Claim(ClaimTypes.Role, role));
            }
        }
        return claims;
    }
}

Refresh Token Implementations

Memory cache example:

sealed class MemoryCachedJwtService(JwtOption opt, IMemoryCache cache, ILogger<MemoryCachedJwtService> logger)
    : JwtServiceWithRefresh(opt, logger)
{
    protected override Task HandleRefreshToken(string userId, JwtRefreshToken token)
    {
        cache.Set($"RT_{userId}", token, TimeSpan.FromMinutes(_jwtOptions.RefreshTokenExpiresInMinutes));
        return Task.CompletedTask;
    }
    protected override Task<JwtRefreshToken> GetExistRefreshTokenAsync(string userId)
    {
        if (cache.TryGetValue($"RT_{userId}", out JwtRefreshToken? t) && t is not null)
        {
            return Task.FromResult(t);
        }
        throw new InvalidOperationException("Refresh token missing or expired");
    }
}

Database example sketch (pseudo):

sealed class DbJwtService(JwtOption opt, IUserRepository repo, ILogger<DbJwtService> logger)
    : JwtServiceWithRefresh(opt, logger)
{
    protected override Task HandleRefreshToken(string userId, JwtRefreshToken token)
        => repo.UpdateRefreshTokenAsync(userId, token.RefreshToken, token.ExpiryTime);

    protected override async Task<JwtRefreshToken> GetExistRefreshTokenAsync(string userId)
    {
        var user = await repo.GetUserAsync(userId) ?? throw new InvalidOperationException("User not found");
        if (string.IsNullOrWhiteSpace(user.RefreshToken)) throw new InvalidOperationException("No stored refresh token");
        return new JwtRefreshToken { RefreshToken = user.RefreshToken, ExpiryTime = user.RefreshTokenExpiryTime };
    }
}

Controller Example

## Controller Example

### Recommended Approach (using TryRefreshTokenAsync)
```csharp
public class AuthController(IJwtService jwt) : ControllerBase
{
    [HttpPost("login")]
    public async Task<IActionResult> Login(LoginDto dto)
    {
        // validate credentials -> userId
        var userId = dto.UserName; // placeholder
        var token = await jwt.CreateTokenAsync(userId);
        return Ok(token);
    }

    [HttpPost("refresh")]
    public async Task<IActionResult> Refresh(TokenEnvelope dto)
    {
        var result = await jwt.TryRefreshTokenAsync(dto);
        if (result.Success) 
            return Ok(result.Token);
        
        return Unauthorized(result.ErrorMessage);
    }
}

Alternative Approach (using exception handling)

[HttpPost("refresh")]
public async Task<IActionResult> Refresh(TokenEnvelope dto)
{
    if (!jwt.SupportsRefreshToken()) 
        return Unauthorized("Refresh token not supported");
    
    try 
    {
        return Ok(await jwt.RefreshTokenAsync(dto));
    }
    catch (NotSupportedException)
    {
        return Unauthorized("Refresh token not supported");
    }
    catch (SecurityTokenException ex)
    {
        _logger.LogWarning(ex, "Refresh token validation failed");
        return Unauthorized("Invalid or expired refresh token");
    }
}

💡 Tip: The TryRefreshTokenAsync method follows C#'s Try-pattern convention, offering better performance and cleaner code.

## Client Refresh (Concept)
Use retry/resilience pipeline to intercept 401, refresh once (semaphore guarded), retry original request. See legacy guide for full client examples (Blazor, WinForms, simple HttpClient wrapper).

Workflow:
1. Login -> access + refresh
2. Use access until 401
3. Refresh endpoint with pair
4. Issue new pair (rotate refresh)
5. Deny if refresh invalid/expired -> re-login

## Security
- Store production secret in environment: `SECRET`
- Rotate secrets & refresh tokens on each refresh
- Include `jti` (unique id) & `iat` (issued at)
- Keep access tokens short-lived (minutes)
- Persist refresh tokens server-side; treat as confidential credentials

## Advanced
- Add custom claim sources (roles, permissions)
- Central revoke list keyed by `jti`
- Multi-tenant: include `tenant_id` claim
- Pairwise rotation: invalidate previous refresh token on use

## Troubleshooting
| Symptom | Cause | Fix |
|---------|-------|-----|
| 401 immediately | Clock skew | Sync server time / allow small skew |
| Refresh succeeds but old token still works | Not rotating | Ensure refresh rotates and revoke old jti |
| Memory implementation loses tokens | App recycled | Use persistent store |
| Env SECRET ignored | Name mismatch | Ensure variable EXACT name SECRET |

## FAQ
Q: Why extension + interface for refresh?  
A: Keeps core minimal; refresh optional.

Q: Can I disable refresh?  
A: Set EnableRefreshToken = false and only register IJwtService.

Q: How to revoke a single token?  
A: Track `jti` in a deny list until natural expiry.