.NET 10 / .NET 11 security-header middleware for ASP.NET Core (multi-targeted, C# 15 on the net11.0 target), aiming for
an A+ on securityheaders.com. Libraries in src/ (SafeWebCore, .FraudDetection, .JwtBearer, .Analyzers, .Testing),
xUnit v3 tests in tests/, samples in examples/, BenchmarkDotNet in benchmarks/. Docs index: docs/README.md.
Spec-driven workflow: Spec Kit constitution .specify/memory/constitution.md, commands .clinerules/workflows/,
feature specs specs/, guide docs/development/spec-kit-workflow.md.
- 100% backward compatibility for normal releases: additive, opt-in changes only; never drop, rename or re-mean
public API, existing defaults, presets or configuration paths. Read
docs/development/backward-compatibility-policy.mdbefore changing any of them. - Never remove or rename a symbol listed in
PublicAPI.Shipped.txt(RS0037 is a build error); add intentional new public API toPublicAPI.Unshipped.txt. Baselines exist forSafeWebCore,SafeWebCore.FraudDetectionandSafeWebCore.JwtBeareronly. - New public API ships with XML documentation.
SafeWebCore.FraudDetectionnotifications stay injectable and event-driven so a consumer can plug in its own mail module: never hard-code a mail client, never reduce notifications to logging only.- API endpoints emit only the response headers they need; do not add browser-oriented headers to API routes.
- Contributions land on
masterthrough a pull request (CONTRIBUTING.md); CI (.github/workflows/ci.yml) restores, builds and tests in Release on pushes and pull requests tomaster/main, then packs all five packages. - Publishing is keyless:
.github/workflows/publish-nuget.ymluses nuget.org trusted publishing (GitHub OIDC exchanged for a one-hour API key) on av*tag or a manual dispatch with thepublishinput. There is no API-key secret; onlyNUGET_USERis configured, and the nuget.org policy must namepublish-nuget.ymlexactly. - SonarCloud must stay all-A before anything ships. This is a security library, so
reliability_rating,security_rating,sqale_rating(maintainability) andsecurity_review_rating(security hotspots) are all1.0with 0 open issues — one vulnerability drops security to C, and an unpinned third-party GitHub Action counts as one. The release gate reads the overall ratings, not only the new-code conditions; the verification queries and the scope rules are indocs/development/sonarcloud-triage.md(constitution, principle VII).
- The manual is the book-length documentation: chapters in
docs/manual/src, print stylesheetdocs/manual/manual.css, build tooltools/SafeWebCore.Manual, and the released PDFdocs/SafeWebCore-Manual-<version>.pdf. Rebuild it withdotnet run --project .\tools\SafeWebCore.Manual(needs Chrome or Edge) and update the chapter list indocs/README.mdwhen a chapter is added. A user-visible behaviour change that the manual describes belongs in the same pull request. - Feature docs to keep in step with code changes:
docs/getting-started.md,docs/security-headers.md,docs/csp-configuration.md,docs/presets.md,docs/advanced-configuration.md,docs/projects.md. - Package and publish facts:
docs/nuget-packages.md; release gate:docs/release-readiness.md.
- Toolchain comes from the projects, not your shell: .NET 11 SDK,
LangVersion=preview,NullableandImplicitUsingson,TreatWarningsAsErrors=true(Directory.Build.props), xUnit v3 on the Microsoft.Testing.Platform runner (global.json). Every runtime, test and example project multi-targetsnet10.0;net11.0;SafeWebCore.Analyzersstaysnetstandard2.0because Roslyn loads it into the compiler host. dotnet testruns all three suites on both target frameworks (~380 test runs, seconds); the full run must be green before you call a change done. Both the .NET 10 and the .NET 11 runtime must be installed for that.- Warnings break the build; RS0016/RS0017 are the only downgraded diagnostics, by design during the PublicAPI rollout. Sonar's C# rules can be previewed before pushing with
dotnet build SafeWebCore.slnx -p:SonarProbe=true -p:TreatWarningsAsErrors=false(seedocs/development/sonarcloud-triage.md). - Benchmarks live in
benchmarks/SafeWebCore.Benchmarks— run them explicitly, never inside the normal test loop. The host targetsnet10.0only: the pinned BenchmarkDotNet0.15.8does not recognisenet11.0. - Mutation testing is explicit as well:
dotnet tool restore, thendotnet stryker -O ../../artifacts/stryker/<name>from a test project folder (configs intests/*/stryker-config.json, baseline scores indocs/development/mutation-testing.md). Never wire it intodotnet testor CI. - Adding a target framework is an all-or-nothing change: every runtime, test and example project moves together, and
the README badge,
docs/projects.md,docs/nuget-packages.mdandCHANGELOG.mdmove with it.
- Async methods end in
Async;.editorconfigreports it as a suggestion only, so nothing stops you from forgetting. - Commits are Conventional Commits with a module scope, as in the history:
fix(JwtBearer): ...,docs(README): .... CHANGELOG.md(Keep a Changelog + SemVer) gains an entry for user-visible changes; the PR checklist asks for it but no check fails when it is missing.