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.
✅ Project coverage is 97.95%. Comparing base (ce89f57) to head (7cf5d00).

Additional details and impacted files

@@                      Coverage Diff                       @@
##           v3-phase1-pr2-core-package     #357      +/-   ##
==============================================================
+ Coverage                       97.72%   97.95%   +0.23%     
==============================================================
  Files                              13       13              
  Lines                             396      441      +45     
==============================================================
+ Hits                              387      432      +45     
  Misses                              6        6              
  Partials                            3        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.