Skip to content

Releases: jamesgober/dotnet-auth-kit

v1.0.0 — Initial Release

25 Feb 09:34
@jamesgober jamesgober
v1.0.0
1963280

Choose a tag to compare

View all tags
v1.0.0 — Initial Release Latest
Latest

dotnet-auth-kit v1.0.0 Release

February 25, 2026

Welcome to v1.0.0!

We're excited to announce the official v1.0.0 release of dotnet-auth-kit, a production-ready JWT authentication and authorization library for .NET. Built for performance, security, and extensibility — this is a stable foundation you can deploy with confidence in enterprise systems.

What is dotnet-auth-kit?

dotnet-auth-kit is a high-performance JWT authentication library built for modern .NET APIs. It provides a clean, extensible API for:

  • Issuing and validating JWT access tokens with configurable claims, expiry, and signing algorithms
  • Refresh token rotation with one-time-use enforcement and family-based cascade revocation
  • Token blacklisting for pre-expiry revocation
  • Role-based and claim-based authorization
  • Key rotation with zero-downtime transitions
  • ASP.NET Core middleware integration

Whether you're building microservices, enterprise APIs, or cloud-native systems, dotnet-auth-kit has you covered.

Key Features

Multi-Algorithm JWT Signing

Sign tokens with any of 9 algorithms out of the box:

  • HMAC — HS256, HS384, HS512
  • RSA — RS256, RS384, RS512
  • ECDSA — ES256, ES384, ES512

Refresh Token Rotation

Secure refresh token lifecycle with:

  • One-time-use enforcement — each refresh token can only be used once
  • Family-based cascade revocation — if a consumed token is reused, the entire family is revoked
  • SHA-256 hashed storage — raw tokens are never persisted
  • Cryptographically secure token generation via RandomNumberGenerator

Token Blacklisting

Revoke tokens before their natural expiry:

  • JTI-based blacklist with automatic expiry tracking
  • Integrated into the authentication handler — no extra middleware needed
  • Optional standalone middleware for custom auth setups

Key Rotation

Zero-downtime key rotation via SigningKeyDescriptor:

  • Time-based activation windows (ActiveFrom / ActiveUntil)
  • New tokens use the current key; old tokens validate against all keys
  • Supports mixing algorithm families during rotation

Authorization

Policy-based role and claim authorization:

  • RoleRequirement — check if the user has any of the specified roles
  • ClaimRequirement — check for claim existence or specific values
  • Case-insensitive role matching, ordinal claim value matching

ASP.NET Core Integration

Single-call setup:

  • services.AddAuthKit(...) — registers all services, stores, handlers, and background cleanup
  • app.UseAuthKit() — adds authentication and authorization middleware
  • Options validation at startup — fail fast on misconfiguration
  • IOptionsMonitor<T> for hot-reload safe configuration access

Production-Ready Features

Performance

  • JsonWebTokenHandler (high-performance, not the legacy JwtSecurityTokenHandler)
  • ValueTask<T> on all async interfaces
  • ArrayPool<byte> and stackalloc for token generation and hashing
  • Pre-sized collections, manual loops on hot paths (no LINQ)
  • LoggerMessage source generators for zero-allocation logging
  • Lock-free ConcurrentDictionary stores
  • Cached signing credentials with change-token invalidation

Security

  • SHA-256 hashed refresh token storage
  • Cryptographic randomness via RandomNumberGenerator
  • No secrets in logs, exceptions, or error messages
  • Input validation on every public API boundary
  • clearArray: true on all ArrayPool returns

Reliability

  • Background cleanup service for expired blacklist and refresh token entries
  • Graceful degradation when optional stores are not registered
  • ConfigureAwait(false) throughout the library
  • CancellationToken support on every async method
  • Full TimeProvider integration for deterministic testing

Extensibility

  • IClaimTransformer pipeline for enriching claims during issuance
  • Replaceable ITokenBlacklistStore and IRefreshTokenStore (register before AddAuthKit)
  • Custom SecurityKey and algorithm support via SigningKeyDescriptor

Installation

Install via NuGet:

dotnet add package JG.AuthKit

Or via Package Manager Console:

Install-Package JG.AuthKit

Quick Start

Configure services:

builder.Services.AddAuthKit(options =>
{
    options.Secret = builder.Configuration["Jwt:Secret"]!;
    options.Issuer = "my-api";
    options.Audience = "my-app";
    options.AccessTokenExpiry = TimeSpan.FromMinutes(15);
    options.RefreshTokenExpiry = TimeSpan.FromDays(30);
});

Add middleware:

var app = builder.Build();
app.UseAuthKit();
app.MapControllers();
app.Run();

Issue tokens:

app.MapPost("/auth/login", async (LoginRequest login, ITokenService tokenService) =>
{
    var user = await userService.ValidateAsync(login.Email, login.Password);
    if (user is null) return Results.Unauthorized();

    var result = await tokenService.IssueTokenAsync(new TokenRequest
    {
        Subject = user.Id,
        Roles = user.Roles.ToList(),
    });

    return Results.Ok(new
    {
        result.AccessToken,
        result.RefreshToken,
        result.ExpiresAt,
        result.TokenType,
    });
});

That's it! See the API reference for full documentation.

Quality Metrics

Metric Value
Test Count 156 tests (unit, integration, concurrency)
Pass Rate 100%
Compiler Warnings 0
Known Issues 0
Public API Documentation 100% (120 XML-documented members)
Benchmarks 13 (BenchmarkDotNet across 3 suites)
CI Platforms Ubuntu, Windows, macOS

Testing

Testing framework: xUnit with FluentAssertions and NSubstitute.

Test categories:

  • Token issuance — subject, JTI, roles, custom claims, audience override, custom expiry
  • Token validation — valid, tampered, expired, garbage, wrong issuer, blacklisted
  • Token revocation — single token, malformed token, null/empty guards, idempotent revocation
  • Refresh rotation — valid refresh, chained refreshes, expired, revoked, consumed (reuse detection), family revocation, additional claims propagation
  • Authorization — role matching, claim matching, multiple values, missing claims
  • Middleware — full pipeline via TestServer (9 scenarios), standalone blacklist middleware
  • Storage — in-memory stores, 1000-entry concurrent stress tests, cleanup during lookup
  • Background service — cleanup with FakeTimeProvider, disabled interval
  • DI registration — service resolution, singleton lifetime, custom store override, options validation
  • Edge cases — null inputs, empty strings, concurrent 50-thread issuance, claim transformer pipeline

Benchmarks

Run performance benchmarks with BenchmarkDotNet:

# List all benchmarks
dotnet run --project tests/dotnet-auth-kit.Benchmarks -c Release -- --list flat

# Run all benchmarks
dotnet run --project tests/dotnet-auth-kit.Benchmarks -c Release -- --filter *

# Run token service benchmarks only
dotnet run --project tests/dotnet-auth-kit.Benchmarks -c Release -- --filter *TokenService*

Benchmark suites:

  • TokenServiceBenchmarks — issuance (plain, with roles), validation (valid, garbage)
  • RefreshTokenBenchmarks — token pair issuance, full refresh cycle
  • InternalsBenchmarks — JTI generation, refresh token generation, SHA-256 hashing, blacklist lookups (hit/miss at 10K entries)

Dependencies

  • Microsoft.IdentityModel.JsonWebTokens 8.16.0 — JWT creation and validation
  • Microsoft.AspNetCore.App — Framework reference (no additional runtime packages)

Documentation

Complete documentation is available:

  • README.md — Feature overview, quick start, and configuration reference
  • docs/API.md — Complete API reference with code examples
  • CHANGELOG.md — Version history

Community & Support

License

Licensed under the Apache License 2.0. See LICENSE for details.

Ready to get started? Install from NuGet and check out the API reference.

Installation

Install via NuGet:

dotnet add package JG.NameKit

Or via Package Manager Console:

Install-Package JG.NameKit

Quick Start

// Example code snippets and usage instructions go here.

For deeper examples, see the getting started guide.

Documentation

Community & Support

License

Licensed under the Apache License 2.0. See LICENSE for details.

**Ful...

Read more
Assets 2
Loading