feat: Base MFA support

[tusharpandey13]

Important

This PR is the 1st PR in a PR stack

This PR adds support for handling mfa_required error natively and getting access to mfa_token and mfa_requirements when MFA step-up authentication is required.
These parameters can be used to call MFA API methods for challenge and verify operations, which will be added in a later PR.

Changes

• Added MfaRequiredError and other MFA related errors.
• Documentation and tests

Usage

When accessing a protected resource, catch the MfaRequiredError. It automatically packages the encrypted mfa_token you need.

/* app/api/example/route.ts */
import { MfaRequiredError } from '@auth0/nextjs-auth0/server';

try {
  // Request token for sensitive audience or scope
  await auth0.getAccessToken({ audience: 'https://api/sensitive' });
} catch (error) {
  if (error instanceof MfaRequiredError) {
    // 403 Forbidden: Bubble the token to client
    return NextResponse.json(error.toJSON(), { status: 403 });
  }
}

Testing

Flow tests:

• MFA Error bubbling blow
• Configuration and validation

Unit tests for util methods.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 85.98131% with 30 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.97%. Comparing base (c01f8a9) to head (299ad79).

Files with missing lines	Patch %	Lines
src/server/auth-client.ts	74.60%	16 Missing ⚠️
src/server/client.ts	62.16%	14 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2480      +/-   ##
==========================================
- Coverage   91.20%   90.97%   -0.24%     
==========================================
  Files          39       40       +1     
  Lines        4698     4909     +211     
  Branches      981     1018      +37     
==========================================
+ Hits         4285     4466     +181     
- Misses        407      437      +30     
  Partials        6        6              

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

[gyaneshgouraw-okta]

Currently in which all different flows/scenarios are we throwing MfaRequiredError, we should also update the PR description with this information ?

[tusharpandey13]

Scenarios:

• Token refresh with MFA token (normal flow)
• Token refresh without MFA token (edge case). If this happens, it will be handled and MfaRequiredError will be thrown with empty mfa token