[AAD token revocation]: Adds logic for handling emergency token revocation and CAE token revocation.

[aavasthy]

Pull Request Template

Description

AAD CAE Token Revocation and Emergency Token Revocation:
When a request fails with a 401 Unauthorized status, the SDK examines the WWW-Authenticate response header for a claims challenge indicator (such as "insufficient_claims" or "claims="). If detected, it extracts the base64-encoded claims string and merges it with the client capability "cp1" (indicating CAE support). The SDK then requests a new token from Azure AD using this merged claims object and automatically retries the original request with the refreshed token. To prevent infinite retry loops, a retry threshold of one attempt is enforced, meaning the SDK will retry once after token refresh but fail if the second attempt also returns 401. The service can signal token revocation in two ways: CAE (Continuous Access Evaluation) revocation or emergency token revocation, but the SDK handles both scenarios identically by extracting claims, requesting a new token, and retrying the request.

Where revocation is enforced

Revocation rules are evaluated by the routing gateway (compute gateway) on every HTTP request it receives. Any call that goes over HTTP to the gateway endpoint can get a 401/5013 + WWW-Authenticate
response.

RNTBD (direct TCP to replicas) does NOT go through the routing gateway — so direct-mode document CRUD is not subject to revocation at the gateway level.

---

Gateway Mode

Operation	Example	Path	Retry?	Mechanism
Data-plane (doc CRUD, queries)	CreateItemAsync, ReadItemAsync, QueryItemsAsync	GatewayStoreModel → GatewayStoreClient	✅	ClientRetryPolicy.HandleUnauthorizedResponse
Control-plane (DB/container CRUD)	CreateDatabaseAsync, DeleteContainerAsync	GatewayStoreModel (always gateway)	✅	Same ClientRetryPolicy
Account read (GET /)	Client init	GatewayAccountReader	✅	catch when TryHandleRevocationException
Collection metadata (GET /colls/)	Container resolution	ClientCollectionCache → GatewayStoreModel	✅	TaskHelper + ClientRetryPolicy
Partition key ranges (GET /pkranges)	Routing map	PartitionKeyRangeCache → GatewayStoreModel	✅	ClientRetryPolicy

Direct Mode

Operation	Example	Goes through gateway?	Retry?	Why
Data-plane (doc CRUD)	CreateItemAsync	❌ RNTBD to replicas	N/A	Not subject to gateway revocation
Control-plane (DB/container CRUD)	CreateDatabaseAsync	✅ Always gateway	✅	ClientRetryPolicy
Account read (GET /)	Client init	✅ HTTP to gateway	✅	GatewayAccountReader retry
Address resolution (GET /addresses/)	Resolve replica endpoints	✅ HTTP to gateway	✅	GatewayAddressCache catch when retry
Collection metadata (GET /colls/)	Container resolution	✅ HTTP to gateway	✅	ClientCollectionCache + ClientRetryPolicy
Partition key ranges (GET /pkranges)	Routing map	✅ HTTP to gateway	✅	ClientRetryPolicy

---

Retry Flow (all 9 steps verified in code)

1. Request fails — Server returns HTTP 401 + WWW-Authenticate: Bearer error="insufficient_claims", claims="<base64>"
2. SDK detects — ClientRetryPolicy.ShouldRetryInternalAsync checks for 401 + substatus 5013 OR presence of WWW-Authenticate header
3. Claims extracted — ExtractClaimsFromWwwAuthenticate parses claims="<base64>" from the header
4. Cache reset — TokenCredentialCache.ResetCachedToken(claims) clears cached token and stores the claims challenge
5. Claims merged — MergeClaimsWithClientCapabilities merges the server's nbf claim with the SDK's xms_cc/cp1 capability
6. New token requested — tokenCredential.GetTokenAsync(new TokenRequestContext(claims: mergedClaims)) sent to Entra
7. Entra responds — Returns a new token satisfying the claims challenge
8. Request retried — SDK retries the original request with the fresh token
9. Max once — MaxCaeRevocationRetryCount = 1 — if the retry also gets 401, the SDK throws to the caller

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)

Closing issues

To automatically close an issue: closes #IssueNumber

[github-actions]

All good!