feat: Add Multiple Custom Domains (MCD) support

[ankita10119]

Description

Implements support for validating JWT tokens from multiple Auth0 tenants or custom domains in a single API deployment. This addresses the need for multi-tenant architectures, domain migrations, and regional deployments without requiring separate API instances.

Implementation

New Configuration Pattern

Introduces auth0MCD configuration object that accepts three validation methods:

Static array:

auth0MCD: {
   issuers: ['https://tenant1.auth0.com', 'https://tenant2.auth0.com']
 }

Config objects:

auth0MCD: {
  issuers: [
    { issuer: 'https://tenant1.auth0.com', alg: 'RS256' },
    { issuer: 'https://tenant2.auth0.com', jwksUri: 'https://...' }
  ]
}

Dynamic resolver:

auth0MCD: {
  issuers: async (context) => {
    const tenantId = context.headers['x-tenant-id'];
    return await getTenantIssuers(tenantId);
  }
}

Changes

packages/access-token-jwt/src/jwt-verifier.ts

• Added MCD types: Auth0MCDOptions, IssuerConfig, IssuerResolverContext
• Implemented issuer validation before JWKS fetch
• Added symmetric algorithm rejection for JWKS-based verification
• Added discovery issuer double-validation
• Support for per-issuer JWKS URI and algorithm configuration

packages/access-token-jwt/src/token-verifier.ts

• Modified to pass request context (URL, headers) to dynamic resolver
• Enables tenant-aware issuer validation

packages/access-token-jwt/src/discovery.ts

• Refactored to support per-issuer discovery caching
• Each issuer's metadata cached independently (10 min TTL)

packages/access-token-jwt/src/get-key-fn.ts

• Updated JWKS caching to support multiple issuers
• Maintains separate cache entries per JWKS URI

Backward Compatibility

Fully backward compatible. Existing configurations work unchanged:

// Still works exactly as before

app.use(auth({
  issuerBaseURL: 'https://tenant.auth0.com',
  audience: 'https://your-api.com'
}));

References

MCD GA requirements
MCD- express-oauth2-jwt-bearer-design-doc

Testing

• Added 22 comprehensive MCD test cases in jwt-verifier.test.ts
• All scenarios covered: static config, dynamic resolver, symmetric/asymmetric, error cases
• 342 tests passing with 100% code coverage
• Created test-mcd-app/ with working examples for all configuration methods

Checklist

• I have added documentation for new/changed functionality in this PR or in auth0.com/docs
• All active GitHub checks for tests, formatting, and security are passing
• The correct base branch is being used, if not the default branch