feat: MCD (Multiple Custom Domains) Support

[tusharpandey13]

This change adds support for Multiple Custom Domains using a dynamic DomainResolver in client configuration.

Changes

Note

Take a look at the Review Guide section for an easy review experience.

• Auth0ClientOptions.domain widened to string | DomainResolver where DomainResolver is a callback that returns a domain string.
• AuthClientProvider replaces singleton AuthClient with shared discovery/JWKS caches, AuthClient made domain-aware.
• Domain/issuer session storage and mismatch check logic.
• Callback pins issuer in the transaction cookie.
• Domain normalization logic.
• openid scope enforced in resolver mode for iss claim availability.
• Logout, backchannel, MFA, and proxy are domain-aware via provider delegation.

Usage

export const auth0 = new Auth0Client({
  domain: async ({ headers, url }) => {
    // your code here
    const domain = db.getDomain() || "auth.brand1.com";
    return domain;
  },
});

Full docs: EXAMPLES.md — Multiple Custom Domains

Tests

277 new tests (flow tests and UTs) across 7 files covering:

• Domain normalization
• Error handling
• Shared discovery cache
• AuthClient factory
• Session domain gating
• Auth flows

References

• Multiple Custom Domains - Auth0 Docs

[codecov-commenter]

Codecov Report

❌ Patch coverage is 79.42158% with 185 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.40%. Comparing base (6e9f186) to head (66e2c7b).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
src/server/auth-client.ts	61.57%	93 Missing ⚠️
src/test/mocks.ts	37.20%	27 Missing ⚠️
src/server/client.ts	82.30%	23 Missing ⚠️
src/server/mfa/server-mfa-client.ts	14.28%	18 Missing ⚠️
src/server/next-compat.ts	72.72%	8 Missing and 1 partial ⚠️
src/server/auth-client-provider.ts	92.38%	8 Missing ⚠️
src/utils/pathUtils.ts	66.66%	4 Missing ⚠️
src/utils/token-set-helpers.ts	88.23%	2 Missing ⚠️
src/utils/normalize.ts	98.87%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2545      +/-   ##
==========================================
- Coverage   90.50%   89.40%   -1.10%     
==========================================
  Files          52       59       +7     
  Lines        6632     7331     +699     
  Branches     1380     1527     +147     
==========================================
+ Hits         6002     6554     +552     
- Misses        619      765     +146     
- Partials       11       12       +1     

☔ 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.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[tusharpandey13]

Review guide

Changes can be categorized as:

New MCD logic

These changes add the MCD capability to the SDK, including the new AuthClient factory, caches, types and errors.

• auth-client-provider.ts
• discovery-cache.ts
• types/mcd.ts & errors/mcd.ts
• tests for these files

Core integration

These changes plug MCD into existing logic

• auth-client.ts
• client.ts
• transaction-store.ts
• server-mfa-client.ts
• tests for these & exports

Updates to existing test files

Tests for:
fetcher, get-access-token, with-api-auth-required, with-page-auth-required, mfa-error-bubbling, mfa-server, proxy-handler

Docs

EXAMPLES.md, README.md