feat(auth0-fastify-api): Add MCD support

[nandan-bhat]

This PR adds Multiple Custom Domains (MCD) support to @auth0/auth0-fastify-api by forwarding domains, algorithms, request URL, and headers to the underlying @auth0/auth0-api-js SDK. It also introduces optional discoveryCache pass‑through, tightens option typing, and updates docs/examples to align with how domains are configured in the Auth0 Dashboard.

Changes

• Added MCD options to the Fastify plugin (domains, algorithms) and passed request context into verifyAccessToken.
• Introduced verification‑only option shape (use domains without domain) and enforced correct config for client flows.
• Added discoveryCache pass‑through for non‑MCD users as well.
• Re‑exported DomainsResolver and DomainsResolverContext types for convenient typing in user code.
• Expanded tests to cover resolver errors, invalid domain formats, issuer mismatch, missing iss, algorithm restrictions, and forwarded‑header URL building.

Usage Examples

Static allowlist

import fastifyAuth0, { type Auth0FastifyApiOptions } from '@auth0/auth0-fastify-api';

const options: Auth0FastifyApiOptions = {
  audience: '<AUTH0_AUDIENCE>',
  domains: ['your-tenant.auth0.com', 'custom.example.com'],
};

fastify.register(fastifyAuth0, options);

Dynamic resolver:

import fastifyAuth0, {
  type DomainsResolver,
  type DomainsResolverContext,
} from '@auth0/auth0-fastify-api';

const domainsResolver: DomainsResolver = ({ url, headers }: DomainsResolverContext) => {
  const host =
    headers?.['x-forwarded-host'] ??
    headers?.['host'] ??
    (url ? new URL(url).host : undefined);

  if (host === 'api.example.com') return ['custom.example.com'];
  return ['your-tenant.auth0.com'];
};

fastify.register(fastifyAuth0, {
  audience: '<AUTH0_AUDIENCE>',
  domain: '<AUTH0_DOMAIN>', // required for client flows
  domains: domainsResolver,
  algorithms: ['RS256'],
});

Risks

• Host header injection risk: DomainsResolver often uses Host/X-Forwarded-Host. These are spoofable unless your app is behind trusted proxies. Always enforce a strict host allowlist and only trust forwarded headers from controlled infrastructure.

Expecting pipeline failure

• The test pipeline will fail in CI because @auth0/auth0-api-js is not yet published to NPM.

[kishore7snehil]

LGTM!