feat(MCD): implement multiple custom domains support

[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 implements multi-issuer/multi-tenant support for applications that need to validate JWTs from multiple OIDC issuers (Multiple Custom Domains).

New Components

MultiIssuerProvider:

• NewMultiIssuerProvider(opts ...MultiIssuerProviderOption) - Creates multi-issuer JWKS provider
• KeyFunc(ctx context.Context) (any, error) - Automatically routes JWKS requests per issuer
• ProviderCount() int - Returns number of cached providers

New JWKS Options:

• WithMultiIssuerCacheTTL(ttl time.Duration) - Configure cache refresh interval (default: 15 min)
• WithMultiIssuerHTTPClient(client *http.Client) - Custom HTTP client (default: 30s timeout)
• WithMultiIssuerCache(cache Cache) - Custom cache implementation for Redis
• WithMaxProviders(maxProviders int) - LRU eviction limit for memory control (default: unlimited)

Validator Options:

• WithIssuers(issuers []string) - Accept tokens from multiple static issuers
• WithIssuersResolver(resolver func(context.Context) ([]string, error)) - Dynamic issuer resolution

Context Helpers:

• IssuerFromContext(ctx context.Context) (string, bool) - Extract validated issuer
• SetIssuerInContext(ctx context.Context, issuer string) - Store issuer in context

Features

• Automatic per-issuer JWKS routing based on validated issuer from JWT
• Lazy provider creation with double-checked locking for thread safety
• LRU eviction for memory management in high-tenant scenarios
• Custom cache support (Redis) for distributed JWKS caching
• Proactive background refresh at 80% TTL

Usage

Static Multiple Issuers:

provider, _ := jwks.NewMultiIssuerProvider(
    jwks.WithMultiIssuerCacheTTL(5*time.Minute),
)

validator.New(
    validator.WithKeyFunc(provider.KeyFunc),
    validator.WithIssuers([]string{
        "https://tenant1.auth0.com/",
        "https://tenant2.auth0.com/",
    }),
)

Large-Scale with Redis + LRU:

provider, _ := jwks.NewMultiIssuerProvider(
    jwks.WithMultiIssuerCache(redisCache),
    jwks.WithMaxProviders(1000),
)

Dynamic Issuer Resolution:

validator.New(
    validator.WithKeyFunc(provider.KeyFunc),
    validator.WithIssuersResolver(func(ctx context.Context) ([]string, error) {
        tenant := ctx.Value("tenant").(string)
        return db.GetIssuersForTenant(ctx, tenant)
    }),
)

📚 References

Use Cases:

• Multi-tenant SaaS applications where each tenant has their own Auth0 domain
• Domain migrations supporting both old and new domains simultaneously
• Enterprise deployments with multiple Auth0 tenants

Scaling Recommendations:

• < 10 issuers: Default in-memory cache
• 10-100 issuers: In-memory with monitoring
• 100-1000 issuers: Redis + WithMaxProviders(500)
• 1000+ issuers: Redis + WithMaxProviders(1000)

🔬 Testing

Test Coverage: 96.8%

Unit Tests:

• MultiIssuerProvider with all configuration options
• Provider creation, caching, and LRU eviction
• Concurrent access and thread safety
• Custom cache integration
• Error handling

Integration Tests:

• examples/http-multi-issuer-example - Static issuer list with 3 tenants
• examples/http-dynamic-issuer-example - Dynamic issuer resolution
• examples/http-multi-issuer-redis-example - Redis cache with LRU eviction

CI/CD:

• All examples tested in GitHub Actions workflow
• New make test-examples target
• Tests pass on ubuntu-latest, macos-latest, windows-latest

Manual Testing:

cd examples/http-multi-issuer-example
go run main.go

# Test with different tenant tokens
curl -H "Authorization: Bearer <tenant1-jwt>" http://localhost:3000
curl -H "Authorization: Bearer <tenant2-jwt>" http://localhost:3000

Documentation:

• README with multi-tenant setup guide
• Package docs with usage examples and performance benchmarks
• Example READMEs with detailed instructions

[Copilot]

Pull request overview

This PR implements multi-issuer/multi-tenant support for applications that need to validate JWTs from multiple OIDC issuers (Multiple Custom Domains).

Changes:

• Adds MultiIssuerProvider for automatic per-issuer JWKS routing with lazy provider creation, LRU eviction, and custom cache support
• Migrates from go-jose/go-jose.v2 to lestrrat-go/jwx/v3 for JWKS handling
• Introduces DPoP (Demonstrating Proof-of-Possession) support with trusted proxy configuration and multiple operation modes

Reviewed changes

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

Show a summary per file

File	Description
jwks/provider.go	Refactored JWKS provider to use jwx library, added caching layer with background refresh
jwks/option.go	New options for provider configuration supporting multi-issuer and caching customization
jwks/multi_issuer_provider_test.go	Comprehensive tests for multi-issuer provider including concurrency and LRU eviction
jwks/multi_issuer_provider.go	Core implementation of multi-issuer provider with double-checked locking and LRU cache
jwks/doc.go	Package documentation explaining provider types, usage patterns, and performance guidance
internal/oidc/oidc.go	Minor change to defer function for response body close
internal/oidc/doc.go	New documentation for OIDC discovery functionality
go.mod	Updated to v3 module path and migrated to jwx library
extractor_test.go	Enhanced tests for token extraction including DPoP scheme support
extractor.go	Extended token extractor to support DPoP scheme and return scheme information
examples/*	Multiple new examples demonstrating multi-issuer, dynamic issuer resolution, Redis caching, DPoP modes, and trusted proxy configuration
Makefile	Added test-examples target and updated golangci-lint version

Comments suppressed due to low confidence (1)

jwks/provider.go:1

• The comment mentions 'single-flight fetching' behavior, but this is implemented through the fetchMu mutex which blocks all concurrent fetches rather than allowing one to proceed while others wait for the result. This is not true single-flight behavior (like sync.Singleflight). Consider clarifying the comment to say 'serialized fetching' or 'mutex-protected fetching' to accurately describe the implementation.

package jwks

---

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

[codecov-commenter]

Codecov Report

❌ Patch coverage is 95.75290% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.35%. Comparing base (f643eb3) to head (78b1e09).

Files with missing lines	Patch %	Lines
jwks/multi_issuer_provider.go	88.31%	6 Missing and 3 partials ⚠️
jwks/provider.go	97.29%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #368      +/-   ##
==========================================
- Coverage   96.55%   96.35%   -0.20%     
==========================================
  Files          18       20       +2     
  Lines        1508     1727     +219     
==========================================
+ Hits         1456     1664     +208     
- Misses         34       41       +7     
- Partials       18       22       +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.