feat: add Multiple Custom Domains (MCD) support and fix JWT verification

[kishore7snehil]

Multiple Custom Domains (MCD) Support with JWT Verification

🎯 Overview

This PR adds Multiple Custom Domains (MCD) support to auth0-server-python, enabling applications to serve multiple tenants from different hostnames, each mapping to a separate Auth0 tenant. Additionally, this PR includes critical security fixes for JWT verification and token refresh in MCD scenarios.

✨ Features

1. Multiple Custom Domains Support

• Dynamic Domain Resolution: Accept Callable as domain parameter for runtime resolution
• Type-Safe Context: New DomainResolverContext with request_url and request_headers
• Backward Compatible: Static string domains continue to work unchanged
• Framework-Agnostic: Works with FastAPI, Flask, Django, or any Python framework

Example:

async def domain_resolver(context: DomainResolverContext) -> str:
    host = context.request_headers.get('host', '').split(':')[0]
    return DOMAIN_MAP.get(host, DEFAULT_DOMAIN)

client = ServerClient(domain=domain_resolver, ...)  # MCD enabled

2. OIDC Metadata & JWKS Caching

• Per-Domain Caching: Separate cache entries for each Auth0 domain
• 1-Hour TTL: Configurable cache lifetime with automatic expiration
• Smart Eviction: FIFO eviction when max 100 domains reached
• Performance: Reduces API calls by ~99% for frequently used domains

3. JWT Signature Verification with Issuer Validation

• JWKS-Based Verification: Proper signature validation using PyJWT
• Issuer Matching: Validates token iss claim matches origin domain
• Key Extraction: Correctly extracts signing key from JWKS using kid
• Security: Prevents token substitution and cross-tenant replay attacks

4. Domain-Specific Session Management

• Automatic Isolation: Sessions bound to their origin domain
• Cross-Domain Protection: Sessions from domain A rejected on domain B
• Token Refresh Fix: Uses session's stored domain (not current request domain)
• Migration Support: Sessions coexist during domain migrations

🔄 Compatibility

✅ 100% Backward Compatible - No breaking changes for existing users.

Existing Usage (Unchanged)

# Static domain - works exactly as before
client = ServerClient(domain="tenant.auth0.com", ...)

New Usage (Optional)

# Dynamic MCD - new opt-in feature
async def domain_resolver(context: DomainResolverContext) -> str:
    return "tenant.auth0.com"

client = ServerClient(domain=domain_resolver, ...)

What Changed Internally

• JWT verification now correctly extracts signing key from JWKS (bug fix)
• Token refresh uses session domain instead of request domain (bug fix)
• Domain parameter now accepts callables for dynamic resolution (new feature)

Impact: Existing applications require zero code changes to upgrade.

🔒 Security Enhancements

1. Domain Isolation - Prevents session hijacking across tenants
2. Issuer Validation - Validates all ID tokens against origin issuer
3. JWKS Per Domain - Each tenant uses correct signing keys
4. Session Domain Binding - Token refresh uses correct Auth0 tenant

📊 Testing

• Test Coverage: 88 passing tests
• New Tests: 30+ tests for MCD scenarios in test_server_client.py
• Integration Test: Live MCD test verified with real Auth0 tenants
• Coverage: 81% overall, 100% for critical paths

Test Scenarios Covered:

• ✅ Domain resolution and validation
• ✅ Session isolation across domains
• ✅ Token refresh with session domain
• ✅ Domain-specific logout
• ✅ Issuer validation (success and failure)
• ✅ OIDC/JWKS caching
• ✅ Migration scenarios

📚 Documentation

• examples/MCD.md - New quick reference guide

To fix an unused import, you remove the corresponding import statement so that the test module no longer declares a dependency it does not use. This improves readability and satisfies the static analysis rule without changing runtime behavior.

Concretely, in src/auth0_server_python/tests/test_server_client.py, delete the line import jwt (line 6). No other changes are required, and no additional methods, imports, or definitions are needed. All remaining imports are left untouched to avoid impacting existing functionality.