feat: add On-Behalf-Of token exchange support

[kishore7snehil]

📋 Changes

This PR adds On-Behalf-Of (OBO) token exchange support to auth0-fastapi-api, enabling MCP servers and intermediary FastAPI APIs to exchange an incoming Auth0 access token for a new access token targeting a downstream API while preserving the original user identity (RFC 8693). The exchange itself is performed by the underlying auth0-api-python client (auth0.api_client.get_token_on_behalf_of()), consistent with how the SDK already surfaces get_access_token_for_connection(). This PR exposes the OBO surface through the plugin and documents it.

✨ Features

• On-Behalf-Of Token Exchange: Exchange an incoming access token for a downstream audience via auth0.api_client.get_token_on_behalf_of(access_token, audience, scope?), returning access-token-oriented fields only (no id_token or refresh_token). Requires a confidential client (client_id and client_secret).
• Actor Claim Helpers: get_current_actor() and get_delegation_chain() re-exported from fastapi_plugin for inspecting the act claim on verified tokens - the current actor (outermost act.sub) for authorization and the full delegation chain for audit or attribution.

🔧 API Changes

• New re-exports from fastapi_plugin: get_current_actor, get_delegation_chain, OnBehalfOfTokenResult, GetTokenByExchangeProfileError, and ApiError

📖 Documentation

• Updated README.md with an On-Behalf-Of Token Exchange section
• Updated EXAMPLES.md with the end-to-end flow (verify -> exchange -> call downstream), return value, error handling, and delegation inspection, plus production and DPoP notes

🧪 Testing

• This change adds test coverage
• This change has been tested on the latest version of the platform/language

Manual Testing

Requires an Auth0 tenant with an On-Behalf-Of / token-exchange profile configured: an API for the intermediary's own audience, a second API for the downstream audience, and a confidential client authorized for the downstream API.

import asyncio
from fastapi_plugin import Auth0FastAPI, get_current_actor, get_delegation_chain

async def main():
    auth0 = Auth0FastAPI(
        domain="<AUTH0_DOMAIN>",
        audience="<AUTH0_AUDIENCE>",
        client_id="<AUTH0_CLIENT_ID>",
        client_secret="<AUTH0_CLIENT_SECRET>",
    )
    incoming_access_token = "<ACCESS_TOKEN_FOR_AUDIENCE>"

    result = await auth0.api_client.get_token_on_behalf_of(
        access_token=incoming_access_token,
        audience="<DOWNSTREAM_AUDIENCE>",
        scope="read:data",
    )
    print("exchanged:", result["access_token"])

    claims = await auth0.api_client.verify_access_token(access_token=result["access_token"])
    print("current actor:", get_current_actor(claims))
    print("delegation chain:", get_delegation_chain(claims))

asyncio.run(main())

Expected: the exchange returns a downstream-scoped access token whose act.sub identifies the exchanging client, and the delegation helpers resolve the current actor and full chain.

Contributor Checklist

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