Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ updates:
microsoft:
patterns: ["Microsoft.*", "System.*"]
tests:
patterns: ["xunit*", "Microsoft.NET.Test.Sdk", "coverlet.*", "AwesomeAssertions"]
patterns: ["xunit*", "AwesomeAssertions"]
ignore:
# Microsoft.* are pinned per TFM (net8 -> 8.x, net9 -> 9.x, net10 -> 10.x); only patch bumps are safe
# Microsoft.* follow the target framework (net10 -> 10.0.x); only patch bumps are safe
- dependency-name: "Microsoft.*"
update-types: ["version-update:semver-major"]
- dependency-name: "System.Security.Cryptography.Xml"
Expand Down
10 changes: 4 additions & 6 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -26,18 +26,15 @@ jobs:
working-directory: src
steps:
- name: Checkout repository
uses: actions/checkout@v4
uses: actions/checkout@v7
with:
fetch-depth: 0
ref: ${{ inputs.version && format('v{0}', inputs.version) || github.sha }}

- name: Setup .NET
uses: actions/setup-dotnet@v4
uses: actions/setup-dotnet@v6
with:
dotnet-version: |
8.0.x
9.0.x
10.0.x
global-json-file: global.json

- name: Restore dependencies
run: dotnet restore
Expand All @@ -57,6 +54,7 @@ jobs:
extra_plugins: |
@semantic-release/changelog@6
@semantic-release/git@10
conventional-changelog-conventionalcommits@8
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Expand Down
9 changes: 3 additions & 6 deletions .github/workflows/pull-request.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,17 +15,14 @@ jobs:
working-directory: src
steps:
- name: Checkout repository
uses: actions/checkout@v4
uses: actions/checkout@v7
with:
fetch-depth: 0

- name: Setup .NET
uses: actions/setup-dotnet@v4
uses: actions/setup-dotnet@v6
with:
dotnet-version: |
8.0.x
9.0.x
10.0.x
global-json-file: global.json

- name: Restore dependencies
run: dotnet restore
Expand Down
41 changes: 26 additions & 15 deletions .releaserc
Original file line number Diff line number Diff line change
@@ -1,17 +1,28 @@
{
"branches": ["master"],

"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
"@semantic-release/changelog",
[
"@semantic-release/github",
{
"successComment": false,
"failTitle": false
}
],
"@semantic-release/git"
]
"branches": [
"master"
],
"plugins": [
[
"@semantic-release/commit-analyzer",
{
"preset": "conventionalcommits"
}
],
[
"@semantic-release/release-notes-generator",
{
"preset": "conventionalcommits"
}
],
"@semantic-release/changelog",
[
"@semantic-release/github",
{
"successComment": false,
"failTitle": false
}
],
"@semantic-release/git"
]
}
6 changes: 3 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
# NetDevPack.Security.Jwt

.NET library (NuGet) that generates, rotates, stores and publishes (JWKS) JWT signing/encryption keys. Targets net8.0/net9.0/net10.0.
.NET library (NuGet) that generates, rotates, stores and publishes (JWKS) JWT signing/encryption keys. Targets net10.0.

**Knowledge base:** `docs/` is an Obsidian vault. Start at `docs/00-Index.md`, then read `docs/Workflows/Agent-Playbook.md` before making changes.

## Commands (run from `src/`)
```bash
dotnet restore && dotnet build -c Release
dotnet test -c Release # add -f net10.0 for a single TFM
dotnet test -c Release
dotnet list NetDevPack.Security.Jwt.sln package --vulnerable --include-transitive
```

## Rules
- Package versions only in `Directory.Packages.props` (Central Package Management). Never add `Version=` to a csproj. Microsoft.* packages are versioned per TFM (8.0.x / 9.0.x / 10.0.x). See `docs/Dependencies/Policy.md`.
- Package versions only in `Directory.Packages.props` (Central Package Management). Never add `Version=` to a csproj. Microsoft.* packages follow the TFM (10.0.x). See `docs/Dependencies/Policy.md`.
- NuGet Audit warnings NU1901-NU1904 are build errors. IdentityServer4 is the only deliberate exception (deprecated, ADR-002).
- Commits: Conventional Commits (no local hook enforces it; semantic-release reads the messages). Use `chore(deps)` for dependency bumps. Breaking change = `feat!:` + `BREAKING CHANGE:` footer. semantic-release owns `CHANGELOG.md` and versions.
- Public API in `src/` is a NuGet contract. Treat changes to it as breaking.
Expand Down
6 changes: 3 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
# NetDevPack.Security.Jwt

.NET library (NuGet) that generates, rotates, stores and publishes (JWKS) JWT signing/encryption keys. Targets net8.0/net9.0/net10.0.
.NET library (NuGet) that generates, rotates, stores and publishes (JWKS) JWT signing/encryption keys. Targets net10.0.

**Knowledge base:** `docs/` is an Obsidian vault. Start at `docs/00-Index.md`, then read `docs/Workflows/Agent-Playbook.md` before making changes.

## Commands (run from `src/`)
```bash
dotnet restore && dotnet build -c Release
dotnet test -c Release # add -f net10.0 for a single TFM
dotnet test -c Release
dotnet list NetDevPack.Security.Jwt.sln package --vulnerable --include-transitive
```

## Rules
- Package versions only in `Directory.Packages.props` (Central Package Management). Never add `Version=` to a csproj. Microsoft.* packages are versioned per TFM (8.0.x / 9.0.x / 10.0.x). See `docs/Dependencies/Policy.md`.
- Package versions only in `Directory.Packages.props` (Central Package Management). Never add `Version=` to a csproj. Microsoft.* packages follow the TFM (10.0.x). See `docs/Dependencies/Policy.md`.
- NuGet Audit warnings NU1901-NU1904 are build errors. IdentityServer4 is the only deliberate exception (deprecated, ADR-002).
- Commits: Conventional Commits (no local hook enforces it; semantic-release reads the messages). Use `chore(deps)` for dependency bumps. Breaking change = `feat!:` + `BREAKING CHANGE:` footer. semantic-release owns `CHANGELOG.md` and versions.
- Public API in `src/` is a NuGet contract. Treat changes to it as breaking.
Expand Down
51 changes: 3 additions & 48 deletions Directory.Packages.props
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<Project>
<!--
Central Package Management: every version lives here, csproj files only declare <PackageReference Include="..." />.
Microsoft.* packages follow the target framework, so they are versioned per TFM below.
Microsoft.* packages follow the target framework (net10.0 -> 10.0.x).
See docs/Dependencies/Policy.md before changing anything.
-->
<PropertyGroup>
Expand All @@ -10,7 +10,6 @@
<CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
</PropertyGroup>

<!-- TFM independent -->
<ItemGroup>
<PackageVersion Include="System.IdentityModel.Tokens.Jwt" Version="8.23.0" />
<PackageVersion Include="IdentityServer4" Version="4.1.2" />
Expand All @@ -23,53 +22,9 @@

<!-- Tests -->
<PackageVersion Include="AwesomeAssertions" Version="9.6.0" />
<PackageVersion Include="xunit" Version="2.9.3" />
<PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5" />
<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.10.1" />
<PackageVersion Include="coverlet.collector" Version="10.1.0" />
</ItemGroup>

<ItemGroup Condition="'$(TargetFramework)' == 'net8.0'">
<PackageVersion Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="8.0.34" />
<PackageVersion Include="Microsoft.AspNetCore.DataProtection" Version="8.0.34" />
<PackageVersion Include="Microsoft.AspNetCore.DataProtection.EntityFrameworkCore" Version="8.0.34" />
<PackageVersion Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="8.0.34" />
<PackageVersion Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="8.0.34" />
<PackageVersion Include="Microsoft.AspNetCore.Mvc.Testing" Version="8.0.34" />
<PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="8.0.34" />
<PackageVersion Include="Microsoft.EntityFrameworkCore" Version="8.0.34" />
<PackageVersion Include="Microsoft.EntityFrameworkCore.InMemory" Version="8.0.34" />
<PackageVersion Include="Microsoft.EntityFrameworkCore.Sqlite" Version="8.0.34" />
<PackageVersion Include="Microsoft.EntityFrameworkCore.SqlServer" Version="8.0.34" />
<PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="8.0.1" />
<PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="8.0.1" />
<PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="8.0.1" />
<PackageVersion Include="Microsoft.Extensions.Options" Version="8.0.2" />
<PackageVersion Include="System.Security.Cryptography.Pkcs" Version="8.0.2" />
<PackageVersion Include="System.Security.Cryptography.Xml" Version="8.0.5" />
</ItemGroup>

<ItemGroup Condition="'$(TargetFramework)' == 'net9.0'">
<PackageVersion Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="9.0.23" />
<PackageVersion Include="Microsoft.AspNetCore.DataProtection" Version="9.0.23" />
<PackageVersion Include="Microsoft.AspNetCore.DataProtection.EntityFrameworkCore" Version="9.0.23" />
<PackageVersion Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="9.0.23" />
<PackageVersion Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="9.0.23" />
<PackageVersion Include="Microsoft.AspNetCore.Mvc.Testing" Version="9.0.23" />
<PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="9.0.23" />
<PackageVersion Include="Microsoft.EntityFrameworkCore" Version="9.0.23" />
<PackageVersion Include="Microsoft.EntityFrameworkCore.InMemory" Version="9.0.23" />
<PackageVersion Include="Microsoft.EntityFrameworkCore.Sqlite" Version="9.0.23" />
<PackageVersion Include="Microsoft.EntityFrameworkCore.SqlServer" Version="9.0.23" />
<PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="9.0.23" />
<PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="9.0.23" />
<PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="9.0.23" />
<PackageVersion Include="Microsoft.Extensions.Options" Version="9.0.23" />
<PackageVersion Include="System.Security.Cryptography.Pkcs" Version="9.0.23" />
<PackageVersion Include="System.Security.Cryptography.Xml" Version="9.0.23" />
</ItemGroup>
<PackageVersion Include="xunit.v3" Version="4.0.3" />

<ItemGroup Condition="'$(TargetFramework)' == 'net10.0'">
<!-- Ship with .NET 10 -->
<PackageVersion Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.15" />
<PackageVersion Include="Microsoft.AspNetCore.DataProtection" Version="10.0.15" />
<PackageVersion Include="Microsoft.AspNetCore.DataProtection.EntityFrameworkCore" Version="10.0.15" />
Expand Down
10 changes: 9 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,16 @@ It generates keys with RSA and ECDsa algorithms, which are the most recommended

### Supported frameworks

All packages target **.NET 8, .NET 9 and .NET 10**.
All packages target **.NET 10** (LTS).

| Version | Target frameworks |
| ------- | ----------------- |
| 11.x | .NET 10 |
| 10.x | .NET 8, .NET 9, .NET 10 |
| 9.x | .NET Standard 2.1, .NET 8, .NET 9, .NET 10 |

> **Breaking change in v11:** .NET 8 and .NET 9 are out of support since 2026-11-10 and are no longer targeted. If you need them, stay on v10.x.
>
> **Breaking change in v10:** `netstandard2.1` is no longer supported (it pulled EF Core 3.1, which is out of support). If you need it, stay on v9.x.

## Token Validation
Expand Down
5 changes: 3 additions & 2 deletions docs/00-Index.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
tags: [moc, index]
updated: 2026-10-01
updated: 2026-11-17
---
# NetDevPack.Security.Jwt — Knowledge Base

Expand All @@ -21,11 +21,12 @@ Open the `docs/` folder as an Obsidian vault, or just read the Markdown on GitHu
- [[Samples]]

## Dependencies
- [[Policy]]: Central Package Management, per-TFM versions, how to update
- [[Policy]]: Central Package Management, .NET package versions, how to update
- [[Known-Issues]]: tech debt and pending migrations

## Decisions (ADRs)
- [[ADR-001-drop-netstandard21]]
- [[ADR-002-identityserver4-deprecated]]
- [[ADR-003-central-package-management]]
- [[ADR-004-remove-legacy-asymmetric-sample]]
- [[ADR-005-net10-only]]
4 changes: 2 additions & 2 deletions docs/Architecture/Overview.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
tags: [architecture]
updated: 2026-10-01
updated: 2026-11-17
---
# Overview

Library that **generates, stores, rotates and publishes** the keys used to sign (JWS) and encrypt (JWE) JWTs, so apps don't hardcode symmetric secrets. See [[Key-Lifecycle]].

## Packages (all `net8.0;net9.0;net10.0`)
## Packages (all `net10.0`, see [[ADR-005-net10-only]])

| Project (`src/`) | NuGet id | Role |
| --- | --- | --- |
Expand Down
17 changes: 17 additions & 0 deletions docs/Decisions/ADR-005-net10-only.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
---
tags: [adr]
status: accepted
date: 2026-11-17
---
# ADR-005 — Target net10.0 only

**Context.** .NET 8 (LTS) and .NET 9 (STS) reached end of support on 2026-11-10. They no longer get servicing updates, so a new advisory on an `8.0.x`/`9.0.x` package could never be fixed. Because NuGet Audit fails the build ([[Policy]]), that would block every release. Keeping them also meant three versions of each `Microsoft.*` package in `Directory.Packages.props` and three test runs in CI.

**Decision.** All packages, tests and samples target `net10.0` (current LTS, supported until 2028-11). `Directory.Packages.props` has a single version line for packages that ship with .NET (`10.0.x`). The same move was applied to all NetDevPack repos in this round.

**Consequences.**
- Breaking change, shipped as **v11.0.0**. Consumers on .NET 8/9 stay on v10.x.
- CI installs only the SDK from `global.json`. Tests run once.
- Tests moved to `xunit.v3` on Microsoft.Testing.Platform. `global.json` opts in with `"test": { "runner": "Microsoft.Testing.Platform" }`, and `Microsoft.NET.Test.Sdk`, `xunit.runner.visualstudio` and `coverlet.collector` were removed.

Related: [[ADR-001-drop-netstandard21]], [[Known-Issues]].
9 changes: 4 additions & 5 deletions docs/Dependencies/Known-Issues.md
Original file line number Diff line number Diff line change
@@ -1,26 +1,25 @@
---
tags: [dependencies, tech-debt]
updated: 2026-10-01
updated: 2026-11-17
---
# Known Issues / Tech Debt

## Dependencies
- **IdentityServer4 4.1.2**: EOL, moderate vulnerabilities (GHSA-55p7-v223-x366, GHSA-ff4q-64jc-gx98). `NU1902` is suppressed only in `NetDevPack.Security.Jwt.IdentityServer4` and `samples/3_IdentityServer4`. See [[ADR-002-identityserver4-deprecated]].
- **xunit v2** (2.9.3) is still in use. v3 (`xunit.v3`) is a separate migration: new package, `OutputType=Exe`, API changes. `xunit.runner.visualstudio` 3.x already supports both.
- `Microsoft.NET.Test.Sdk` 18.x.

## Code
- `JwtServiceValidationHandler` extends the legacy `JwtSecurityTokenHandler` and blocks on `Task.WaitAll(jwtService.GetLastKeys())`. Better: a `JsonWebTokenHandler` + async `IssuerSigningKeyResolver`, or set the keys in `OnMessageReceived`.
- Some tests use the obsolete sync `JsonWebTokenHandler.ValidateToken` (CS0618). Migrate them to `ValidateTokenAsync`.
- Many nullable warnings (CS86xx) and missing XML docs (CS1591) on public APIs (about 700 warnings in a clean build).
- Many nullable warnings (CS86xx) and missing XML docs (CS1591) on public APIs (about 450 warnings in a clean build).
- `IJsonWebKeySetService` is `[Obsolete]`. Remove it in the next major.
- Model file names are swapped: `Model/Key.cs` holds `KeyMaterial`, `Model/KeyMaterial.cs` holds `CryptographicKey`.
- The `DataProtectionStore` fallback exception message still mentions the old `JwtSigningCredentials` package names.

## Resolved
- 2026-11-17: dropped net8.0/net9.0 ([[ADR-005-net10-only]]). Migrated xunit 2 → **xunit.v3** on Microsoft.Testing.Platform; `Microsoft.NET.Test.Sdk`, `xunit.runner.visualstudio` and `coverlet.collector` removed. Fixed the xUnit1051 warnings in `AspNetCoreTests`.
- 2026-10-01: migrated FluentAssertions 8.11 (Xceed commercial license) → **AwesomeAssertions 9.6** (Apache-2.0 fork, same API, namespace `AwesomeAssertions`). Do not reintroduce FluentAssertions.
- 2026-10-01: 6 `.cs` files in UTF-16 LE (`CryptoService`, `IdentityServer4KeyStore`, `IdentityServerBuilderKeysExtensions`, `EFCoreServiceExtensions`, `ISecurityKeyContext`, `KeyMaterialMap`) were converted to UTF-8 BOM + CRLF. `.editorconfig` now enforces the encoding.

## Tests
- A flaky test in `NetDevPack.Security.Jwt.Tests` on net10 failed 1 of 4 local runs (2026-10-01). It is probably a race in a store test that shares the filesystem/DataProtection folder. Not investigated yet.
- A flaky test in `NetDevPack.Security.Jwt.Tests` on net10 failed 1 of 4 local runs on net10 (2026-10-01). It is probably a race in a store test that shares the filesystem/DataProtection folder. Not investigated yet.
- The local machine may not have the .NET 8 runtime. CI installs 8/9/10.
14 changes: 7 additions & 7 deletions docs/Dependencies/Policy.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
tags: [dependencies, policy]
updated: 2026-10-01
updated: 2026-11-17
---
# Dependency Policy

## Where versions live
- **`Directory.Packages.props`** (repo root) — Central Package Management (CPM). csproj files only have `<PackageReference Include="X" />`. **Never add `Version=` in a csproj.**
- `Microsoft.*` / `System.*` packages that ship with .NET are versioned **per TFM** (`ItemGroup Condition="'$(TargetFramework)' == 'net8.0'"`): net8 → 8.0.x, net9 → 9.0.x, net10 → 10.0.x. Never put a 10.x package in the net8 group.
- `Microsoft.*` / `System.*` packages that ship with .NET follow the target framework: net10 → **10.0.x**. Never move them to 11.x while the TFM is net10.0.
- TFM-independent packages (IdentityModel, Swashbuckle, test libs) are in the unconditional group.
- `CentralPackageTransitivePinningEnabled=true`: a `PackageVersion` also pins the **transitive** version. Used for `System.Security.Cryptography.Xml`, which comes in through DataProtection. It ends up as a direct dependency of the Core nuspec, so consumers get the patched version too.
- `Directory.Build.props` (root): `LangVersion`, NuGet Audit (`NU1901-NU1904` = **errors**).
Expand All @@ -18,17 +18,17 @@ cd src
dotnet list NetDevPack.Security.Jwt.sln package --outdated
dotnet list NetDevPack.Security.Jwt.sln package --vulnerable --include-transitive
```
1. Bump only **patch** versions inside each TFM line (`8.0.x`, `9.0.x`, `10.0.x`).
1. Bump only **patch** versions of the .NET packages (`10.0.x`).
2. Bump TFM-independent packages freely, but read the release notes for majors.
3. `dotnet build -c Release` + `dotnet test -c Release` (see [[Build-Test]]).
4. Commit as `chore(deps): ...` (see [[Release]]).

Dependabot (`.github/dependabot.yml`) runs weekly and ignores majors for `Microsoft.*` and also ignores `IdentityServer4`. Dependabot handles the per-TFM groups poorly. If a PR changes the wrong TFM line, fix it by hand.
Dependabot (`.github/dependabot.yml`) runs weekly and ignores majors for `Microsoft.*` and also ignores `IdentityServer4`.

## Adding a new TFM (e.g. net11.0)
1. `src/Directory.Build.props` `TargetFrameworks` + every test/sample csproj.
2. Add a `net11.0` `ItemGroup` in `Directory.Packages.props` mirroring the others.
3. Add `11.0.x` to `actions/setup-dotnet` in both workflows.
1. `src/Directory.Build.props` `TargetFramework` → `TargetFrameworks` + every test/sample csproj.
2. Move the .NET packages in `Directory.Packages.props` into per-TFM `ItemGroup Condition="'$(TargetFramework)' == 'net10.0'"` groups (10.0.x / 11.0.x).
3. Make sure the SDK in `global.json` can build every TFM (CI reads it through `setup-dotnet` `global-json-file`).
4. Write an ADR in `Decisions/`.

Snapshot of the 2026-10-01 update: [[Known-Issues]].
4 changes: 2 additions & 2 deletions docs/Samples.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
tags: [samples]
updated: 2026-10-01
updated: 2026-11-17
---
# Samples (`samples/`)

All samples are in `src/NetDevPack.Security.Jwt.sln`, target net8/9/10 and use project references (except `Api.Sample`).
All samples are in `src/NetDevPack.Security.Jwt.sln`, target net10.0 and use project references (except `Api.Sample`).

| Sample | Shows |
| --- | --- |
Expand Down
Loading
Loading