Add sovereign cloud support (GCCH, DoD, China)

[corinagum]

Summary

• Introduces CloudEnvironment frozen dataclass with predefined presets (PUBLIC, US_GOV, US_GOV_DOD, CHINA) bundling all cloud-specific service endpoints
• Threads cloud environment through App, TokenManager, BotTokenClient, TokenValidator, ApiClient, and ApiClientSettings
• Supports CLOUD environment variable and programmatic AppOptions.cloud configuration
• Adds graph_scope to CloudEnvironment for cloud-aware Microsoft Graph token acquisition
• Simplifies merge_api_client_settings with cloud default to PUBLIC, removes DEFAULT_API_CLIENT_SETTINGS
• Fixes cloud propagation through ApiClient -> BotClient -> BotTokenClient

Note

graph_base_url (Graph API endpoint per cloud) is intentionally deferred. This PR focuses on auth/token acquisition. Graph API routing is a separate concern.

Sources

• Bot Framework GCCH/DoD endpoints: https://learn.microsoft.com/en-us/azure/bot-service/how-to-deploy-gov-cloud-high
• Bot Framework China endpoints: https://learn.microsoft.com/en-us/azure/bot-service/how-to-deploy-china-cloud
• Graph national cloud deployments: https://learn.microsoft.com/en-us/graph/deployments

Test plan

• pytest packages/api/tests/ -- 168 tests pass
• pytest packages/apps/tests/ -- 389 tests pass (1 pre-existing failure unrelated)
• E2E: Echo bot with CLOUD=USGov against real GCCH tenant -- message received, echo reply sent
• Copilot review feedback addressed

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a first-class cloud environment abstraction to support sovereign clouds (GCCH, DoD, China) by centralizing cloud-specific endpoints and plumbing a CloudEnvironment option through key authentication/token-validation paths.

Changes:

• Introduces CloudEnvironment (frozen dataclass) with presets (PUBLIC, US_GOV, US_GOV_DOD, CHINA) plus helpers (from_name, with_overrides).
• Threads cloud configuration into apps auth/token flows (App, TokenManager, TokenValidator, HttpServer, JWT middleware), including CLOUD env var resolution.
• Updates API client pieces to accept cloud-aware defaults and adds unit coverage for cloud presets/helpers.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/api/src/microsoft_teams/api/auth/cloud_environment.py	New cloud endpoint bundle + presets + name/override helpers.
packages/api/tests/unit/test_cloud_environment.py	Unit tests for presets, name resolution, overrides, immutability.
packages/api/src/microsoft_teams/api/auth/init.py	Exposes CloudEnvironment and presets/helpers from the auth package.
packages/api/src/microsoft_teams/api/clients/api_client_settings.py	Adds cloud-aware defaulting behavior for token service (oauth_url).
packages/api/src/microsoft_teams/api/clients/init.py	Adjusts exports for client settings helpers.
packages/api/src/microsoft_teams/api/clients/bot/token_client.py	Adds optional cloud parameter and uses cloud endpoints/scope.
packages/apps/src/microsoft_teams/apps/options.py	Adds cloud option typing for app configuration.
packages/apps/src/microsoft_teams/apps/app.py	Resolves cloud from options/CLOUD env var and passes into auth components.
packages/apps/src/microsoft_teams/apps/token_manager.py	Uses cloud-specific authority, scope, and default tenant for bot tokens.
packages/apps/src/microsoft_teams/apps/auth/token_validator.py	Makes JWKS/issuer/login endpoints cloud-aware for service + Entra validation.
packages/apps/src/microsoft_teams/apps/auth/jwt_middleware.py	Adds cloud option and passes it through to service token validator.
packages/apps/src/microsoft_teams/apps/http/http_server.py	Passes cloud into service token validator for request auth.

[heyitsaamir]

Hm, it looks like cloud simply overrides a number of application-level settings. Can we localize its spread to just app, and maybe the token-validator?? Basically if CLOUD is set, then we set many of those values up and log it?

[rajan-chari]

Review note: Graph token scope needs to vary per cloud

Great work on sovereign cloud support! One gap I noticed: get_graph_token() in token_manager.py still hardcodes the public cloud Graph scope:

GRAPH_TOKEN_SCOPE = 'https://graph.microsoft.com/.default'

This will fail for sovereign clouds — the Graph API endpoint domain differs per cloud, and using the wrong audience returns AADSTS500011 or AADSTS650001.

Correct Graph scopes per cloud

Cloud	Graph Scope
Public	https://graph.microsoft.com/.default
US Gov (GCC High)	https://graph.microsoft.us/.default
US Gov (DoD)	https://dod-graph.microsoft.us/.default
China (21Vianet)	https://microsoftgraph.chinacloudapi.cn/.default

Note: DoD uses dod-graph.microsoft.us, not graph.microsoft.us — the two US Gov presets need different graph scopes.

Reference: Microsoft Graph national cloud deployments

Suggested fix

1. Add a graph_scope field to CloudEnvironment
2. Set it correctly in all 4 cloud presets
3. TokenManager.get_graph_token() reads cloud.graph_scope instead of the hardcoded constant

Small change — one new field on the dataclass, one line update in token_manager.py.

[heyitsaamir]

Looks good. Some minor nits. Also, looks like not all the fields are actually used. Is that intentional?