Release v3.0.0-beta.0

[developerkunal]

BEFORE YOU UPGRADE

• This is a major release that includes breaking changes. Please see MIGRATION_GUIDE.md before upgrading. This release will require changes to your application.

Added

• Pure options pattern for validator, middleware, and JWKS provider (#357, #358, #360)
• DPoP (Demonstrating Proof-of-Possession) support per RFC 9449 (#363)
• Framework-agnostic core package for reusable validation logic (#356)
• Type-safe claims retrieval with generics (GetClaims[T](), MustGetClaims[T](), HasClaims())
• Structured logging support compatible with log/slog
• Support for 14 signature algorithms (HS256/384/512, RS256/384/512, PS256/384/512, ES256/384/512, ES256K, EdDSA)
• Enhanced error responses with RFC 6750 compliance
• Trusted proxy configuration for DPoP behind reverse proxies
• Multiple issuer and audience support with new APIs
• Documentation and linting configuration (#361)

Changed

• Migrated from square/go-jose to lestrrat-go/jwx v3 (#358)
• Module path updated to github.com/auth0/go-jwt-middleware/v3 (#355)
• Minimum Go version updated to 1.24 (#355)
• Update examples for v3 module path and new APIs

Breaking

• Pure options pattern: All constructors (New()) now require functional options instead of positional parameters
• Context key: ContextKey{} is no longer exported - use GetClaims[T]() helper function
• Custom claims now use generics for type safety
• TokenExtractor returns ExtractedToken (with scheme) instead of string
• Type naming: ExclusionUrlHandler renamed to ExclusionURLHandler

Migration Example

v2:

// Validator with positional parameters
jwtValidator, err := validator.New(
    keyFunc,
    validator.RS256,
    "https://issuer.example.com/",
    []string{"my-api"},
)

// Middleware
middleware := jwtmiddleware.New(jwtValidator.ValidateToken)

// Claims access via context key
claims := r.Context().Value(jwtmiddleware.ContextKey{}).(*validator.ValidatedClaims)

v3:

// Validator with pure options
jwtValidator, err := validator.New(
    validator.WithKeyFunc(keyFunc),
    validator.WithAlgorithm(validator.RS256),
    validator.WithIssuer("https://issuer.example.com/"),
    validator.WithAudience("my-api"),
)

// Middleware with options
middleware, err := jwtmiddleware.New(
    jwtmiddleware.WithValidator(jwtValidator),
)

// Type-safe claims with generics
claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())

See MIGRATION_GUIDE.md for complete migration instructions.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (v3@42333f2). Learn more about missing BASE report.

Additional details and impacted files

@@          Coverage Diff          @@
##             v3     #367   +/-   ##
=====================================
  Coverage      ?   96.55%           
=====================================
  Files         ?       18           
  Lines         ?     1508           
  Branches      ?        0           
=====================================
  Hits          ?     1456           
  Misses        ?       34           
  Partials      ?       18           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR prepares the v3.0.0-beta.0 release, updating version metadata and fixing documentation references. The release represents a major version upgrade with breaking changes including a pure options pattern, migration to lestrrat-go/jwx v3, and type-safe claims retrieval with generics.

Key Changes:

• Updated version number from v2.3.1 to v3.0.0-beta.0
• Added comprehensive v3.0.0-beta.0 release notes to CHANGELOG.md
• Fixed incorrect migration guide references from MIGRATION.md to MIGRATION_GUIDE.md

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
.version	Updated version number from v2.3.1 to v3.0.0-beta.0
CHANGELOG.md	Added v3.0.0-beta.0 release entry with detailed breaking changes, additions, and migration examples
README.md	Fixed migration guide reference from incorrect MIGRATION.md to correct MIGRATION_GUIDE.md

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.