refactor: PR 1.3 Refactor validator to use pure options pattern

[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

Refactors validator.New() from positional parameters to a pure options pattern. Introduces generic type-safe custom claims handling.

Breaking Changes:

// Before
validator.New(keyFunc, algorithm, issuer, audience, opts...)

// After
validator.New(
    validator.WithKeyFunc(keyFunc),
    validator.WithAlgorithm(validator.RS256),
    validator.WithIssuer("https://issuer.example.com/"),
    validator.WithAudience("my-api"),
)

New Options:

Required:

• WithKeyFunc(func) - Key function for token verification
• WithAlgorithm(SignatureAlgorithm) - Signature algorithm
• WithIssuer(string) - Expected issuer claim
• WithAudience(string) / WithAudiences([]string) - Expected audience(s)

Optional:

• WithCustomClaims[T CustomClaims](func() T) - Type-safe custom claims (now generic)
• WithAllowedClockSkew(duration) - Clock skew tolerance

Type-Safe Custom Claims:

// Before
customClaims := func() validator.CustomClaims {
    return &CustomClaimsExample{}
}
validator.WithCustomClaims(customClaims)

// After
validator.WithCustomClaims(func() *CustomClaimsExample {
    return &CustomClaimsExample{}  // No interface cast needed
})

Files Modified:

• validator/option.go - Required options + generic WithCustomClaims
• validator/validator.go - Refactored constructor
• validator/validator_test.go - Updated tests
• validator/security_test.go - Updated CVE test
• middleware_test.go - Updated tests
• All examples updated

📚 References

• Depends on PR 1.2 (Core Logic)
• Required for PR 1.4 (jwx Migration)

🔬 Testing

make test
# validator:     100.0% coverage ✅
# main package:   97.4% coverage ✅
# oidc:          100.0% coverage ✅
# jwks:           95.8% coverage ✅

All examples verified to build successfully.

[codecov-commenter]

Codecov Report

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

Additional details and impacted files

@@            Coverage Diff            @@
##             v3-dev     #357   +/-   ##
=========================================
  Coverage          ?   97.95%           
=========================================
  Files             ?       13           
  Lines             ?      441           
  Branches          ?        0           
=========================================
  Hits              ?      432           
  Misses            ?        6           
  Partials          ?        3           

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