Update AAuth .NET SDK research plan with available security/encryption libraries

[dasiths]

Background

The research plan for the .NET AAuth SDK and samples (see .agent/plans/2026-05-13-dotnet-aauth-sdk/research.md) currently calls for several cryptographic and protocol components to be hand-implemented, including RFC 9421 HTTP Message Signatures, Ed25519 JWT support, JSON canonicalization, JWKS hosting, JWK thumbprints, etc. However, as of mid-2026, several high-quality .NET libraries now cover these key needs and can significantly reduce custom code.

Findings

Key .NET libraries that should update the current plan's implementation approach:

RFC 9421 HTTP Message Signatures

• NSign: Complete, actively maintained RFC 9421 HTTP Message Signature implementation
  • NuGet: NSign.Abstractions, NSign.SignatureProviders, NSign.Client, NSign.AspNetCore, NSign.BouncyCastle
  • Ed25519 (EdDSA) support via BouncyCastle extension
  • DelegatingHandler and ASP.NET middleware ready-to-use
• Only AAuth-specific Signature-Key header extensions need light custom code

Ed25519 (EdDSA) JWT signing

• jose-jwt: Ed25519 JWT support, full JWK/JWS/JWE implementation
• ScottBrady.IdentityModel.EdDsa: Adds EdDSA signature provider wiring to Microsoft.IdentityModel
• (Microsoft.IdentityModel.Tokens does not natively support Ed25519 yet)

JSON Canonicalization (RFC 8785)

• JsonCanonicalizer — reference port by RFC 8785 author

JWK Thumbprint, JWK/JWKS Handling

• Microsoft.IdentityModel.Tokens: built-in support for JWK (RFC 7517), JWK thumbprint (RFC 7638) via ComputeJwkThumbprint()
• NetDevPack.Security.Jwt.AspNetCore and Jwks.Manager: robust JWKS endpoint hosting and rotation

Ed25519 Core Crypto

• NSec.Cryptography and Portable.BouncyCastle: proven, high-performance libraries for Ed25519

What Still Needs Custom Code

• AAuth-specific logic: the Signature-Key header extensions (sig=jwt, sig=hwk, etc), AAuth headers (AAuth-Requirement, etc), protocol mechanics, mission/r3, etc.

Suggested Next Steps

1. Update the research plan:
   • Adjust all sections (esp. 5.2, 6, 10, 12) to recommend leveraging these libraries and eliminating custom RFC 9421/JWT/JSON/JWK/JWKS implementations.
   • Narrow in on only AAuth-specific protocol code for custom work.
2. (Optional) Add issue/prioritized todo items to refactor or stub out planned sections to "wrap/integrate these libraries."

For reference/libraries table:

Functionality	Library
RFC 9421 HTTP signatures	NSign (+NSign.BouncyCastle for Ed25519)
RFC 8785 Canonicalization	JsonCanonicalizer
JWT Ed25519 signing	jose-jwt, ScottBrady.IdentityModel.EdDsa
JWK/JWK Thumbprint	Microsoft.IdentityModel.Tokens
JWKS endpoint/rotation	NetDevPack.Security.Jwt, Jwks.Manager
Ed25519 Core Crypto	NSec.Cryptography, Portable.BouncyCastle

Impact

This will focus development effort on the protocol and application-specific parts of the AAuth .NET SDK/samples and save substantial effort.

---

References:

• NSign: https://github.com/Unisys/NSign
• jose-jwt: https://www.nuget.org/packages/jose-jwt/
• ScottBrady.IdentityModel.EdDsa: https://www.nuget.org/packages/ScottBrady.IdentityModel.EdDsa/
• JsonCanonicalizer: https://www.nuget.org/packages/JsonCanonicalizer/
• NetDevPack.Security.Jwt: https://github.com/NetDevPack/Security.Jwt
• Jwks.Manager: https://www.nuget.org/packages/Jwks.Manager/
• Microsoft.IdentityModel.Tokens: https://learn.microsoft.com/en-us/dotnet/api/microsoft.identitymodel.tokens.jsonwebkey
• NSec.Cryptography: https://www.nuget.org/packages/NSec.Cryptography/
• Portable.BouncyCastle: https://www.nuget.org/packages/Portable.BouncyCastle/

[dasiths]

Perplexity based research: GPT 5.4

Title: Update research.md to reference existing .NET libraries (NSign, StructuredFieldValues, etc.)

Summary

The .agent/plans/2026-05-13-dotnet-aauth-sdk/research.md document currently assumes several protocol pieces must be implemented from scratch in .NET (especially RFC 9421 HTTP Message Signatures and RFC 8941 Structured Fields). Since that plan was written, a number of .NET libraries have matured that can significantly reduce the amount of custom code needed for the AAuth .NET SDK and samples.

This issue proposes updating the plan to reference these libraries explicitly and to clarify which parts of the implementation are still AAuth‑specific versus standard protocol plumbing.

---

1. RFC 9421 HTTP Message Signatures

Current text

No existing .NET library implements RFC 9421. Key implementation concerns: …

Proposed update

Add a note that there is now a general‑purpose HTTP Message Signatures implementation for .NET:

• NSign
  • NSign.Client – HttpClient handler/middleware for signing outgoing requests and verifying responses (RFC 9421).
  • NSign.AspNetCore – ASP.NET Core middleware for verifying signatures on incoming requests and signing responses.

Clarify that AAuth still needs a thin protocol‑specific layer (e.g., Signature-Key semantics and AAuth‑specific covered components) but that NSign can provide the core RFC 9421 parsing, base‑string construction, and signing/verification logic.

Suggested changes to plan:

• In §4.1 Core Library and §6 (HTTP Message Signatures), change “no existing .NET library” to “use NSign for base RFC 9421 support, plus AAuth‑specific glue code”.
• In §4.2 Agent Library and §7.2 HttpClient Integration, note that AAuthSigningHandler can be built on top of NSign’s HttpClient handler.
• In §4.3 Server Library and §7.3 ASP.NET Middleware Integration, note that AAuthMiddleware can use NSign.AspNetCore for the core signature verification.

---

2. RFC 8941 Structured Field Values (AAuth-* headers)

Current text

The plan treats AAuth-Requirement, AAuth-Access, AAuth-Mission, and Signature-Key as RFC 8941 structured fields but assumes custom parsing/serialization.

Proposed update

Reference StructuredFieldValues (NuGet) as an RFC 8941‑compliant parser/serializer:

• Use StructuredFieldValues for:
  • AAuth-Requirement parsing/formatting
  • AAuth-Access, AAuth-Mission
  • Signature-Key header parameters

Update §4.1 Core Library (“AAuth headers” and “Signature-Key header”) to say “implemented using StructuredFieldValues” instead of “Custom, RFC 8941 structured fields”.

---

3. JSON Canonicalization (missions, hashes)

Current text

JSON Canonicalization (RFC 8785)… No standard .NET library; need custom implementation or port.

Proposed update

Mention that while there is no “official” JCS implementation, there are usable building blocks:

• Stratumn.CanonicalJson – .NET library for canonical JSON output that can be used or adapted for JCS‑style canonicalization.

Update §5.1 / §5.2 to:

• Call out Stratumn.CanonicalJson as a candidate for mission hash/R3 hash canonicalization.
• Clarify that for strict RFC 8785 compliance you may still wrap or extend it, but it reduces the amount of bespoke canonicalization code required.

---

4. Crypto primitives and Ed25519 fallback

Current text

The plan already mentions NSec.Cryptography as a fallback for Ed25519 on < .NET 9.

Proposed refinement

• In §5.2 .NET Crypto Availability, explicitly call out that NSec is the recommended Ed25519 fallback target:
  • Ed25519 via NSec.Cryptography for runtimes without System.Security.Cryptography.EdDSA.
• Keep the existing mapping but add a short note that NSec is mature/libsodium‑based and suitable for production.

---

5. JWT, JWK, JWKS, and JWK thumbprints

Current text

The plan lists Microsoft.IdentityModel.JsonWebTokens and Microsoft.IdentityModel.Tokens as dependencies but still describes a custom JWK thumbprint implementation.

Proposed update

Clarify that:

• JsonWebTokenHandler from Microsoft.IdentityModel.JsonWebTokens should be used for creating and validating aa-agent+jwt, aa-resource+jwt, and aa-auth+jwt.
• JsonWebKey and JsonWebKeySet from Microsoft.IdentityModel.Tokens can handle JWK/JWKS parsing and include support for computing JWK thumbprints per RFC 7638.

Update:

• §4.1 Core Library – “JWK thumbprint (RFC 7638)” to note that this can be implemented using JsonWebKey’s built‑in thumbprint support rather than hand‑rolled canonical JSON + SHA‑256.
• §4.1 Discovery/JwksClient – emphasize using JsonWebKeySet for JWKS handling.

---

6. CLI tooling (dotnet-aauth)

Current text

The plan specifies commands for the dotnet-aauth tool but not how to implement the CLI.

Proposed update

Reference the official System.CommandLine library for the CLI:

• Use System.CommandLine for:
  • Subcommands: discover, generate, sign-token, public-key, add-agent, fetch, config, etc.
  • Argument parsing, validation, help text, and completion.

Update §4.5 CLI Tool and §8 Project Structure → tools/AAuth.Cli to say “implemented using System.CommandLine”.

---

7. Test infrastructure and HTTP mocking

Current text

The plan mentions mock HTTP servers and WebApplicationFactory<T> but doesn’t reference specific HTTP mocking libraries.

Proposed update

Suggest WireMock.Net as an option for simulating AP/PS/Resource/AS endpoints:

• Use WireMock.Net in AAuth.IntegrationTests to:
  • Serve well‑known metadata and JWKS.
  • Return canned tokens and challenge responses.
  • Simulate 401/202 challenge flows end‑to‑end.

Add a short note in §11 Test Strategy → Test Infrastructure mentioning WireMock.Net alongside WebApplicationFactory<T> and HttpMessageHandler‑based mocks.

---

8. MCP and R3 integration

Current text

The ModelContextProtocol .NET SDK exists. Integrating AAuth signing with MCP transports is a Phase 5 concern.

Proposed update

Make this more concrete by naming the MCP packages:

• ModelContextProtocol.Core / ModelContextProtocol.NET.Core – core MCP abstractions.
• ModelContextProtocol.AspNetCore – ASP.NET Core integration for MCP servers.

Update §5.2 and §5 (Phase 5 – Advanced) to:

• Explicitly recommend using the MCP C# SDK for MCP server/client plumbing and layering AAuth signing on top of its HTTP transport, especially for the R3 and MCP transport work (AAuth.Mcp.Stdio, OpenClaw integration).

---

9. Suggested edits to “Gaps and Open Questions”

In §12 Gaps and Open Questions, consider:

1. RFC 9421 in .NET

   • Update from “No existing library” to “NSign provides a general RFC 9421 implementation; AAuth still needs protocol‑specific configuration and Signature-Key handling on top.”

2. JSON Canonicalization (RFC 8785)

   • Note that Stratumn.CanonicalJson can be used or adapted for JCS, even though there is no official JCS package.

3. Ed25519

   • Explicitly recommend NSec.Cryptography as the fallback library on runtimes without EdDSA.

Everything else in §12 remains valid (gateway choice, PS design, MCP scope, “samples vs SDK” scope), but updating these bullets would keep the research plan aligned with the current .NET ecosystem.

---

Motivation

Updating research.md with these library references should:

• Reduce perceived implementation risk (especially around HTTP Message Signatures and Structured Fields).
• Shorten the path from “research plan” to working prototypes by reusing well‑tested RFC implementations.
• Clarify which parts of the AAuth .NET work are protocol plumbing and which are truly AAuth‑specific logic that the project needs to own.