refactor: PR 1.5 implement pure options pattern for middleware with core integration

[developerkunal]

📝 Checklist

• All new/changed/fixed functionality is covered by tests (or N/A)
• I have added documentation for all new/changed functionality (or N/A)

🔧 Changes

This PR refactors the middleware to use a pure options pattern and integrates it with the new core package.

Types and Functions Changed:

Constructor:

• New(validateToken ValidateToken, opts ...Option) → New(opts ...Option) (*JWTMiddleware, error)
• All options now return errors for validation: type Option func(*JWTMiddleware) error

New Functions:

• WithValidateToken(ValidateToken) Option - Required option for token validation
• WithLogger(Logger) Option - Optional logger for debugging JWT flow
• GetClaims[T any](context.Context) (T, error) - Generic type-safe claims retrieval
• MustGetClaims[T any](context.Context) T - Panicking variant of GetClaims
• HasClaims(context.Context) bool - Check if claims exist in context

Types Added:

• Logger interface - Logging interface compatible with log/slog
• ErrorResponse struct - Structured JSON error response
• validatorAdapter struct - Bridge between ValidateToken and core.TokenValidator

Error Handling:

• DefaultErrorHandler - Rewritten for RFC 6750 OAuth 2.0 Bearer Token compliance
• Structured error responses with error/error_description/error_code fields
• WWW-Authenticate headers for all error responses
• Extensible for future DPoP (RFC 9449) support

Token Extractors:

• CookieTokenExtractor(string) TokenExtractor - Now validates empty cookie names
• ParameterTokenExtractor(string) TokenExtractor - Now validates empty parameter names
• Fixed cookie error handling to propagate all errors (not just ErrNoCookie)

Context Key:

• Changed from exported type ContextKey struct{} to unexported type contextKey int
• Prevents context key collisions following Go best practices

Usage Summary:

Before:

middleware := jwtmiddleware.New(
    jwtValidator.ValidateToken,
)
claims := r.Context().Value(jwtmiddleware.ContextKey{}).(*validator.ValidatedClaims)

After:

middleware, err := jwtmiddleware.New(
    jwtmiddleware.WithValidateToken(jwtValidator.ValidateToken),
    jwtmiddleware.WithLogger(slog.Default()), // Optional
)
claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())

Test Coverage:

• Main middleware: 98.2%
• Core: 100.0%
• Validator: 100.0%
• JWKS: 100.0%
• OIDC: 100.0%
• Total: 99.4%

📚 References

• Depends on chore: PR 1.2 Add framework-agnostic core package for v3 #356 (Core Package)
• Depends on refactor: PR 1.3 Refactor validator to use pure options pattern #357 (Validator Options)
• Depends on refactor: PR 1.4 migrate to jwx v3 and implement pure options for JWKS provider #358 (JWX Migration)
• Part of v3 Phase 1 implementation plan

🔬 Testing

Automated Tests:

• All existing tests updated for new API
• Added option_test.go with comprehensive option validation tests
• Added logger integration tests covering all CheckJWT code paths
• Added extractor edge case tests (case-insensitive Bearer, empty names, etc.)
• Added Test_invalidError for error wrapper methods

Manual Testing:
All examples have been updated and build successfully:

cd examples/http-example && go build        # ✅ OK
cd examples/http-jwks-example && go build   # ✅ OK
cd examples/gin-example && go build         # ✅ OK
cd examples/echo-example && go build        # ✅ OK
cd examples/iris-example && go build        # ✅ OK

Testing Steps:

1. Run make test - All tests pass with 99.4% coverage
2. Run make lint - Zero linting issues
3. Build all examples - All build successfully
4. Test with actual JWT tokens using examples

[codecov-commenter]

Codecov Report

❌ Patch coverage is 95.69892% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 98.88%. Comparing base (1da96e0) to head (54615e2).

Files with missing lines	Patch %	Lines
middleware.go	91.66%	3 Missing and 3 partials ⚠️
extractor.go	66.66%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@                       Coverage Diff                       @@
##           v3-phase1-pr4-jwx-migration     #360      +/-   ##
===============================================================
- Coverage                        99.46%   98.88%   -0.59%     
===============================================================
  Files                               13       13              
  Lines                              562      718     +156     
===============================================================
+ Hits                               559      710     +151     
- Misses                               3        4       +1     
- Partials                             0        4       +4     

☔ 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.