Matios.Security 0.1.3

Matios.Security

Dependency-free JOSE + JWT for .NET — built only on the BCL.

JWE (RFC 7516) · JWS (RFC 7515) · JWT (RFC 7519) · Nested JWT

What is JOSE?

JOSE — JSON Object Signing and Encryption — is the IETF standards family behind modern web tokens:

Why Matios.Security

• Zero dependencies. Built only on System.Security.Cryptography and System.Text.Json — nothing else, ever.
• It encrypts what Microsoft's stack cannot. Microsoft.IdentityModel.* can decrypt JWE A256GCM but cannot issue it (IDX10715), and cannot decrypt it at all on Linux/macOS. This library issues and consumes dir+A256GCM on every platform — and interops with Microsoft.IdentityModel for validation (covered by tests).
• Strict by design. Closed algorithm enums (no magic strings, no alg:"none"), caller-side algorithm whitelists — the token header never decides on its own. zip rejected, unknown crit rejected, duplicate header/claim names rejected.
• Anti-oracle errors. One generic exception; the fine-grained failure code is for server-side logging only.

Quick start

using Matios.Security.Jose;
using Matios.Security.Jwt;

// Use DIFFERENT keys for signing and encryption. Minimum 256 bits.
SymmetricJoseKey signingKey = SymmetricJoseKey.FromBase64Url(signingKeyB64, "sig-2026");
SymmetricJoseKey encryptionKey = SymmetricJoseKey.FromBase64Url(encryptionKeyB64, "enc-2026");

// Signed JWT (JWS) — add ONE line to make it encrypted (Nested JWT)
string token = new JwtBuilder()
    .Issuer("my-platform")
    .Audience("my-api")
    .Subject(userId)
    .IdAuto()
    .Lifetime(TimeSpan.FromMinutes(30))
    .Claim("RoleId", 7)                     // private claims: any JSON-serializable value
    .SignWith(signingKey)
    .EncryptWith(encryptionKey)             // JWE dir+A256GCM outside, signature inside
    .Create();

// Validation
JwtClaims claims = JwtValidator.Validate(token, new JwtValidationParameters
{
    SigningKey = signingKey,
    DecryptionKey = encryptionKey,   // set => token MUST be JWE (no silent downgrade)
    ValidIssuer = "my-platform",
    ValidAudience = "my-api"
});

long roleId = claims.GetClaim<long>("RoleId");

Error handling

Validate throws JoseException on any invalid token — the claims variable is never assigned. The message is fixed and generic ("JOSE operation failed.", anti-oracle); the real reason lives in JoseException.FailureCode (TokenExpired, SignatureInvalid, IssuerMismatch, …) and is meant for server-side logging only. There is also a non-throwing TryValidate:

if (!JwtValidator.TryValidate(token, parameters, out var claims, out var failure))
{
    _logger.LogWarning("Token rejected: {Code}", failure);  // detail goes to the log
    return Unauthorized();                                   // generic answer to the client
}

Rule of thumb: the FailureCode goes to your log; clients always get the same generic answer.

Scope — deliberately minimal

Everything implemented is conformant and covered by tests; everything outside the profile is cleanly rejected.

Conformance evidence

• Official RFC 7515 Appendix A.1 HS256 vector (accept + tampered-reject).
• Bidirectional interop against Microsoft.IdentityModel.JsonWebTokens (an independent implementation), with canary tests pinning its two A256GCM limitations.
• Strict negative suite: zip, crit, algorithm confusion, none, tampered AAD/tag, duplicate names, oversized tokens, undersized keys.
• 49 tests, all green on Ubuntu and Windows, on every CI run.

Links

• Repository, full docs and usage guide: https://github.com/MatiosSpa/matios-security
• License: MIT © Matios SpA