dotkit 1.1.0

dotkit

A .NET CLI tool that installs and configures JWT Authentication in ASP.NET Core Web API projects with a single command.

Features

• Supports .NET 6 and later: multi-targeted tool (net6.0, net8.0, net10.0) that installs and runs on any .NET 6+ runtime
• Detects the target project's target framework and rejects frameworks older than .NET 6
• Installs Microsoft.AspNetCore.Authentication.JwtBearer NuGet package with the version matched to the project's target framework (resolved from NuGet, e.g. 6.0.x for net6.0)
• Adds Jwt section to appsettings.json with auto-generated secret key
• Creates JwtSettings and JwtService ready-to-use classes (C# 10 compatible, so they compile on net6.0)
• Injects JWT authentication, DI registration, and middleware into Program.cs
• Configures User Secrets for SecretKey, Issuer, and Audience (or writes them to appsettings.json via --no-user-secrets)
• Logs progress to console and rolling files via Serilog

Installation

dotnet tool install --global dotkit

Usage

dotkit install [options]

Options

Examples

# Default: stores values in User Secrets
dotkit install

# Custom values
dotkit install --project ./MyApi --issuer "MyApp" --audience "MyApp"

# Write values directly to appsettings.json (skip User Secrets)
dotkit install --no-user-secrets --secret-key "your-32-char-min-key-here..."

What it does

1. Detects the ASP.NET Core Web API project (must target Microsoft.NET.Sdk.Web and .NET 6.0 or later)
2. Installs Microsoft.AspNetCore.Authentication.JwtBearer NuGet package (version matched to the project's target framework)
3. Merges Jwt section into appsettings.json
4. Creates Configuration/JwtSettings.cs and Services/JwtService.cs
5. Injects into Program.cs:
   • Required using directives
   • builder.Services.AddAuthentication().AddJwtBearer() with TokenValidationParameters
   • builder.Services.Configure<JwtSettings>(...)
   • builder.Services.AddScoped<JwtService>()
   • app.UseAuthentication() and app.UseAuthorization()
6. Configures SecretKey, Issuer, and Audience via User Secrets (or appsettings.json)

After running, inject JwtService in any controller and call GenerateAccessToken() to issue JWTs.

Secret storage modes

Lifecycle

dotkit install [options]
             │
             ▼
    ┌─────────────────────┐
    │  Initialize Serilog   │  → %TEMP%\dotkit\logs\dotkit-YYYYMMDD.log
    └─────────┬───────────┘
              ▼
    ┌─────────────────────┐
    │  ProjectDetector    │  ← Reads .csproj from directory
    │  .Detect()          │
    └─────────┬───────────┘
              ▼
    ┌─────────────────────┐
    │  JwtInstaller       │  ← dotnet add package
    │  .InstallAsync()    │     Microsoft.AspNetCore.Authentication.JwtBearer
    └─────────┬───────────┘
              ▼
    ┌─────────────────────┐
    │  JsonEditor         │  ← Merges Jwt section from template
    │  .UpdateAppSettings │     into existing appsettings.json
    │  (key?,iss?,aud?)  │     (real values if --no-user-secrets,
    └─────────┬───────────┘      placeholder if User Secrets)
              ▼
    ┌─────────────────────┐
    │  TemplateInstaller  │  ← Creates:
    │  .InstallTemplates  │     Configuration/JwtSettings.cs
    │                     │     Services/JwtService.cs
    └─────────┬───────────┘
              ▼
    ┌─────────────────────┐
    │  ProgramEditor      │  ← Injects into Program.cs:
    │  .UpdateProgramAsync│     - usings for .Configuration and .Services
    │                     │     - AddAuthentication + AddJwtBearer
    │                     │     - Configure<JwtSettings>
    │                     │     - AddScoped<JwtService>
    │                     │     - app.UseAuthentication/Authorization
    └─────────┬───────────┘
              ▼
    ┌─────────────────────┐
    │  UserSecretsManager  │  ← (only if NOT --no-user-secrets)
    │  .ConfigureAsync    │     dotnet user-secrets init
    │                     │     set Jwt:SecretKey
    │                     │     set Jwt:Issuer
    │                     │     set Jwt:Audience
    └─────────┬───────────┘
              ▼
    ✓ Installation completed successfully

Possible errors

ProjectDetector

JsonEditor

JwtInstaller

UserSecretsManager

Runtime errors (in the generated project, NOT in the tool)

Exit code

• 0 → success
• 1 → any error (message and exception are logged)

Requirements

• A .NET runtime 6.0 or later to install and run the dotkit tool
• An ASP.NET Core Web API project targeting net6.0 or later (net6.0, net8.0, net10.0, ...)

The tool is multi-targeted (net6.0, net8.0, net10.0) and the installer picks the binary that matches the runtime available on your machine.

Supported target projects

• Target framework: net6.0 or later. Older frameworks (net5.0, netcoreapp3.1, netstandard2.0) are rejected.
• The Microsoft.AspNetCore.Authentication.JwtBearer version is resolved automatically from the target project's framework (e.g. 6.0.x for net6.0, 8.0.x for net8.0), using the latest stable version for that line.
• Generated templates (JwtSettings.cs, JwtService.cs) are compatible with C# 10, so they compile in net6.0 projects.

CI/CD & Releases

The repository uses GitHub Actions with a supply-chain hardened setup:

• .github/workflows/ci.yml — runs on push to main/dev and on PRs: build (all 3 TFMs), unit tests, NuGet vulnerability audit (dotnet list package --vulnerable), pack, and an end-to-end smoke test (scripts/e2e.sh) that installs the packed tool and verifies /token and /protected behavior on net6.0, net8.0, and net10.0 samples.
• .github/workflows/release.yml — publishes to NuGet.org using Trusted Publishing (OIDC): no long-lived API keys. It requests a short-lived API key at push time via NuGet/login@v1 and uses --skip-duplicate.
• Actions are pinned to commit SHAs and kept updated by Dependabot (.github/dependabot.yml).
• global.json pins the .NET SDK (10.0.302) for reproducible builds; ContinuousIntegrationBuild enables deterministic packaging in CI.
• Permissions are least-privilege (contents: read, id-token: write only on the publish job) and persist-credentials: false.

How to publish a release

1. One-time setup:
   • nuget.org → your account → Trusted Publishing → add a policy for owner Gianss19, repository dotkit, workflow file release.yml.
   • GitHub repo → Settings → Secrets and variables → Actions → add NUGET_USER = your nuget.org username (profile name, not email).
2. Trigger a publish:
   • Manually: Actions → Release → Run workflow → enter version (e.g. 1.1.0).
   • Or push a tag: git tag v1.2.0 && git push origin v1.2.0. The version is validated against a SemVer regex before packaging.

Development

Clone the repository and build, test, and pack locally:

git clone https://github.com/Gianss19/dotkit.git
cd dotkit

# Build all target frameworks (net6.0, net8.0, net10.0)
dotnet build

# Run the unit tests
dotnet test tests/dotkit.Tests.csproj

# Audit NuGet packages for known vulnerabilities
dotnet list dotkit.csproj package --vulnerable --include-transitive

# Pack the NuGet tool package
dotnet pack -c Release -o artifacts

# End-to-end smoke test (needs a bash shell; uses the packed nupkg in artifacts/)
bash scripts/e2e.sh

Contributing

Contributions are welcome! To report a bug, request a feature, or open a pull request, use the repository's issue tracker:

• Repository: https://github.com/Gianss19/dotkit
• Issues: https://github.com/Gianss19/dotkit/issues
• Pull requests: https://github.com/Gianss19/dotkit/pulls

License

This project is licensed under the MIT License.