feat: Add DPoP authentication support

[kishore7snehil]

📋 Changes

This PR implements DPoP (RFC 9449) support for auth0-api-python, enabling sender-constrained OAuth 2.0 access tokens using cryptographic proof of possession for enhanced API security.

Note

DPoP is currently in Early Access. Contact Auth0 support to enable it for your tenant.

✨ Features

• DPoP Protocol Implementation: Complete RFC 9449 compliant implementation with ES256 signature verification, JWT proof validation, and comprehensive claim checking
• Dual Authentication Scheme Support: Seamless handling of both Bearer and DPoP authentication schemes in a single API
• Unified Entry Point: New verify_request() method automatically detects and validates Bearer or DPoP schemes
• Flexible Configuration Modes: Support for "Allowed Mode" (mixed Bearer/DPoP) and "Required Mode" (DPoP-only enforcement)
• Comprehensive Validation: Full claim validation including htm, htu, ath, jti with timing checks
• URL Normalization: RFC-compliant URL matching for DPoP htu claims with proper scheme and port handling

🔧 API Changes

• Added verify_request() method to ApiClient for unified authentication scheme detection
• Added verify_dpop_proof() method for direct DPoP proof verification
• Extended ApiClientOptions with DPoP configuration parameters (dpop_enabled, dpop_required, dpop_iat_leeway, dpop_iat_offset)
• New DPoP-specific error classes: InvalidDpopProofError, InvalidAuthSchemeError
• Enhanced error handling with proper HTTP status codes and WWW-Authenticate headers

📚 Core Components

• JWT Dual Support: Separate JsonWebToken handlers for RS256 (Bearer) and ES256 (DPoP) validation
• Cryptographic Utilities: SHA-256 hashing, Base64URL encoding, JWK thumbprint calculation
• URL Processing: DPoP-compliant URL normalization and comparison
• Error Response System: HTTP-aware error hierarchy with OAuth error codes and WWW-Authenticate headers
• Test Infrastructure: Comprehensive utilities for generating DPoP proofs and bound tokens

📖 Documentation

• Updated README.md with comprehensive features overview and DPoP authentication section
• Added detailed configuration examples for both "Allowed" and "Required" modes
• Created EXAMPLES.md with authentication scheme examples

📎 References

• SDK-6030
• RFC 9449

🧪 Testing

• This change adds test coverage

• This change has been tested on the latest version of the platform/language or why not

Contributor Checklist

• I agree to adhere to the Auth0 General Contribution Guidelines.
• I agree to uphold the Auth0 Code of Conduct.

[Widcket]

How is the library handling the case when the Authorization header contains a malformed access token (e.g. "Authorization: Bearer invalid-format")? It should be an invalid token error (status 401, invalid_token code).

[Widcket]

How is the library handling the case where more than one DPoP headers are included in a request? It should be an invalid request error (status 400, invalid_request code).

[Widcket]

How is the library handling the case when the the DPoP proof contains extra claims in the payload, and extra properties in the header? These should be ignored.

[kishore7snehil]

@Widcket

How is the library handling the case when the Authorization header contains a malformed access token (e.g. "Authorization: Bearer invalid-format")? It should be an invalid token error (status 401, invalid_token code).

Please check the following out :

For Neither of the Mode

• Bearer Request

• DPoP Request

For Allowed Mode:

• Bearer Request

• DPoP Request

For Required Mode:

• Bearer Request

• DPoP Request

[Widcket]

Thanks. Seems that there is an instance where the WWW-Authenticate header is just Bearer, and is missing the error and error_description.