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

Implements Multiple Custom Domains (MCD) support — enabling multi-tenant applications to validate JWTs from multiple OIDC issuers, with symmetric key support and algorithm policy enforcement.

Types and Methods Added

JWKS Package — MultiIssuerProvider:

• NewMultiIssuerProvider(opts...) — Creates multi-issuer JWKS provider with dynamic per-issuer routing
• MultiIssuerProvider.KeyFunc(ctx) — Routes JWKS requests to correct issuer based on context
• MultiIssuerProvider.ProviderCount() — Total managed issuers (OIDC + symmetric)
• MultiIssuerProvider.Stats() — Per-issuer observability (type, algorithm, last-used time)
• IssuerKeyConfig — Per-issuer symmetric key configuration (Secret, Algorithm, KeyID)
• ProviderStats, IssuerInfo, IssuerType — Observability types

JWKS Package — New Options:

• WithMultiIssuerCacheTTL(ttl) — Cache refresh interval (default: 15 min)
• WithMultiIssuerHTTPClient(client) — Custom HTTP client
• WithMultiIssuerCache(cache) — Custom cache implementation (e.g., Redis)
• WithMaxProviders(max) — LRU eviction limit (default: 100)
• WithIssuerKeyConfig(issuer, config) — Per-issuer symmetric key
• WithIssuerKeyConfigs(configs) — Batch symmetric key configuration

Validator Package — New Options:

• WithIssuers(issuers) — Accept tokens from multiple static issuers
• WithIssuersResolver(resolver) — Dynamic issuer resolution at request time
• WithAlgorithms(algorithms) — Multiple allowed signature algorithms

Validator Package — Context Helpers:

• IssuerFromContext(ctx) — Extract validated issuer from context
• SetIssuerInContext(ctx, issuer) — Store issuer in context

Types and Methods Changed

• Validator.ValidateToken — Now uses jws.Parse for single-pass header extraction; validates token alg against allowed list before JWKS fetch
• Validator.parseToken — Uses jws.WithUseDefault(true) for jwk.Set to support symmetric keys without kid; returns clear error when multiple algorithms configured with raw key
• Validator.validate() — Checks allowedAlgorithms slice instead of single signatureAlgorithm
• WithAlgorithm — Now writes to allowedAlgorithms slice; mutually exclusive with WithAlgorithms

Internal Field Changed (Non-Breaking)

• Validator.signatureAlgorithm (unexported) → Validator.allowedAlgorithms (unexported slice)

Summary of Usage

Static Multiple Issuers:

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

v, _ := validator.New(
    validator.WithKeyFunc(provider.KeyFunc),
    validator.WithAlgorithm(validator.RS256),
    validator.WithIssuers([]string{
        "https://tenant1.auth0.com/",
        "https://tenant2.auth0.com/",
    }),
    validator.WithAudience("my-api"),
)

Mixed Symmetric + Asymmetric MCD:

provider, _ := jwks.NewMultiIssuerProvider(
    jwks.WithIssuerKeyConfig("https://symmetric.example.com/", jwks.IssuerKeyConfig{
        Secret:    []byte("shared-secret"),
        Algorithm: validator.HS256,
    }),
)

v, _ := validator.New(
    validator.WithKeyFunc(provider.KeyFunc),
    validator.WithAlgorithms([]validator.SignatureAlgorithm{validator.RS256, validator.HS256}),
    validator.WithIssuers([]string{
        "https://tenant1.auth0.com/",        // RS256 via OIDC
        "https://symmetric.example.com/",     // HS256 via pre-shared secret
    }),
    validator.WithAudience("my-api"),
)

Using IssuerFromContext in Request Handlers:

After token validation, the validated issuer is available in the request context. This lets handlers implement per-tenant logic:

func handler(w http.ResponseWriter, r *http.Request) {
    // Extract the validated issuer set by ValidateToken
    issuer, ok := validator.IssuerFromContext(r.Context())
    if !ok {
        http.Error(w, "issuer not found", http.StatusUnauthorized)
        return
    }

    // Route logic based on which tenant issued the token
    switch issuer {
    case "https://tenant1.auth0.com/":
        // tenant1-specific logic
    case "https://tenant2.auth0.com/":
        // tenant2-specific logic
    }

    // Or use it for logging / metrics
    log.Printf("Request authenticated via issuer: %s", issuer)
}

Dynamic Issuer Resolution with WithIssuersResolver:

For applications where the allowed issuers are not known at startup — e.g., multi-tenant SaaS where tenants are stored in a database:

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

v, _ := validator.New(
    validator.WithKeyFunc(provider.KeyFunc),
    validator.WithAlgorithm(validator.RS256),
    validator.WithIssuersResolver(func(ctx context.Context) ([]string, error) {
        // The unverified issuer from the token is available in context.
        // Use it to scope your database lookup instead of loading all issuers.
        tokenIssuer, _ := validator.IssuerFromContext(ctx)

        // Verify this issuer exists in your tenant database
        tenant, err := db.GetTenantByIssuer(ctx, tokenIssuer)
        if err != nil {
            return nil, fmt.Errorf("unknown tenant: %w", err)
        }

        // Return the allowed issuers for this tenant
        return tenant.AllowedIssuers, nil
    }),
    validator.WithAudience("my-api"),
)

The resolver is called on every request with the token's unverified issuer already in context. This means you can do a targeted database lookup (WHERE issuer = ?) instead of loading all issuers. The resolver must be:

• Thread-safe (called concurrently)
• Fast (< 5ms recommended — cache if needed)
• Secure (the issuer from context is unverified at this point)

Tenant Monitoring:

stats := provider.Stats()
log.Printf("Managing %d issuers (%d OIDC, %d symmetric)",
    stats.Total, stats.OIDC, stats.Symmetric)
for _, info := range stats.Issuers {
    log.Printf("  %s: type=%s alg=%s lastUsed=%v",
        info.Issuer, info.Type, info.Algorithm, info.LastUsed)
}

📚 References

• Fixes Feature request: explicit algorithm allow/deny policy enforcement for JWKS (jwk.Set) validation #379 — WithAlgorithm(RS256) silently ignored when keyFunc returns jwk.Set
• Enables symmetric (HS256) issuers in MCD scenarios where OIDC discovery is not available
• Adds WithAlgorithms for mixed-algorithm MCD (RS256 + HS256 issuers)

🔬 Testing

Coverage: validator 97.1%, jwks 96.2%

Algorithm enforcement (#379):

• Tokens with disallowed alg header rejected before JWKS fetch
• WithAlgorithms accepts multiple algorithms; mutual exclusivity with WithAlgorithm tested
• Multi-alg + raw key returns clear error

Symmetric MCD:

• WithIssuerKeyConfig returns static jwk.Set, bypasses OIDC discovery
• Mixed mode: symmetric + asymmetric issuers in same provider
• Config validation: empty config, missing secret, asymmetric alg + secret
• Cross-issuer secret attack rejected
• 20+ concurrent symmetric requests

Observability:

• ProviderCount includes symmetric issuers
• Stats() returns correct per-issuer breakdown (type, algorithm, last-used)

No regressions: All existing tests pass across all packages and all 12 example test suites.

Manual testing:

go test ./validator/... -v -count=1
go test ./jwks/... -v -count=1
go test ./... -v -count=1

[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 91.05145% with 40 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.10%. Comparing base (f643eb3) to head (649ed03).
⚠️ Report is 5 commits behind head on master.

Files with missing lines	Patch %	Lines
jwks/multi_issuer_provider.go	86.23%	11 Missing and 8 partials ⚠️
error_handler.go	50.00%	10 Missing ⚠️
validator/validator.go	92.68%	5 Missing and 1 partial ⚠️
jwks/provider.go	93.82%	2 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #368      +/-   ##
==========================================
- Coverage   96.55%   95.10%   -1.46%     
==========================================
  Files          18       20       +2     
  Lines        1508     1878     +370     
==========================================
+ Hits         1456     1786     +330     
- Misses         34       62      +28     
- Partials       18       30      +12     

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