Merge pull request #173 from keycardai/feat/multi-zone-oauth-surface

feat(keycardai-oauth)!: multi-zone convergence (issuer-keyed credentials, zone-aware low-level surface)

Author: Larry-Osakwe

packages/fastmcp/src/keycardai/fastmcp/__init__.py

@@ -70,8 +70,8 @@ async def sync_calendar_to_drive(ctx: Context):
         zone_url="https://keycard.cloud",
         mcp_base_url="https://my-server.com",
         application_credential=ClientSecret({
-            "zone1": ("id1", "secret1"),
-            "zone2": ("id2", "secret2"),
+            "https://zone1.keycard.cloud": ("id1", "secret1"),
+            "https://zone2.keycard.cloud": ("id2", "secret2"),
         })
     )
 """

packages/mcp/src/keycardai/mcp/server/auth/provider.py

@@ -70,8 +70,8 @@ class AuthProvider:
         # Passing a multi-zone ClientSecret enables multi-zone automatically;
         # pass enable_multi_zone=True/False only to override.
         client_secret = ClientSecret({
-            "zone1": ("client_id_1", "client_secret_1"),
-            "zone2": ("client_id_2", "client_secret_2"),
+            "https://zone1.keycard.cloud": ("client_id_1", "client_secret_1"),
+            "https://zone2.keycard.cloud": ("client_id_2", "client_secret_2"),
         })
         provider = AuthProvider(
             zone_url="https://keycard.cloud",
@@ -276,9 +276,12 @@ async def _get_or_create_client(self, auth_info: dict[str, str] | None = None) -
 
                 auth_strategy = self.auth
                 if isinstance(self.auth, MultiZoneBasicAuth) and auth_info['zone_id']:
-                    if not self.auth.has_zone(auth_info['zone_id']):
+                    # Multi-zone credentials are keyed by the zone's issuer
+                    # URL, which is the same zone-scoped URL the client is
+                    # created against.
+                    if not self.auth.has_issuer(base_url):
                         raise AuthProviderConfigurationError()
-                    auth_strategy = self.auth.get_auth_for_zone(auth_info['zone_id'])
+                    auth_strategy = self.auth.get_auth_for_issuer(base_url)
 
                 # Configure dynamic client registration
                 # Priority: explicit config > identity provider defaults

packages/mcp/tests/integration/test_auth_provider.py

@@ -75,8 +75,8 @@ def test_auth_provider_init_with_basic_auth(self, mock_client_factory):
     def test_multi_zone_inferred_from_credential(self, mock_client_factory):
         """A multi-zone ClientSecret turns on multi-zone without an explicit flag."""
         credential = ClientSecret({
-            "zone1": ("client_id_1", "client_secret_1"),
-            "zone2": ("client_id_2", "client_secret_2"),
+            "https://zone1.keycard.cloud": ("client_id_1", "client_secret_1"),
+            "https://zone2.keycard.cloud": ("client_id_2", "client_secret_2"),
         })
         auth_provider = AuthProvider(
             zone_url="https://keycard.cloud",
@@ -101,7 +101,7 @@ def test_single_zone_credential_does_not_infer_multi_zone(self, mock_client_fact
     def test_explicit_enable_multi_zone_overrides_inference(self, mock_client_factory):
         """An explicit enable_multi_zone value is respected over inference."""
         credential = ClientSecret({
-            "zone1": ("client_id_1", "client_secret_1"),
+            "https://zone1.keycard.cloud": ("client_id_1", "client_secret_1"),
         })
         auth_provider = AuthProvider(
             zone_id=mock_zone_id,

packages/oauth/README.md

@@ -278,28 +278,35 @@ with Client("https://oauth.example.com", auth=auth) as client:
 
 ### MultiZoneBasicAuth
 
-For multi-zone deployments with different credentials per zone:
+For multi-zone deployments with different credentials per zone, keyed by
+each zone's issuer URL:
 
 ```python
-from keycardai.oauth import MultiZoneBasicAuth
+from keycardai.oauth import Client, MultiZoneBasicAuth
 
-# Configure credentials for multiple zones
+# Configure credentials per zone issuer
 auth = MultiZoneBasicAuth({
-    "production": ("prod_client_id", "prod_client_secret"),
-    "staging": ("staging_client_id", "staging_client_secret"),
-    "development": ("dev_client_id", "dev_client_secret"),
+    "https://prod.keycard.cloud": ("prod_client_id", "prod_client_secret"),
+    "https://staging.keycard.cloud": ("staging_client_id", "staging_client_secret"),
 })
 
-# Check available zones
-print(auth.get_configured_zones())  # ['production', 'staging', 'development']
+# Check configured issuers
+print(auth.get_configured_issuers())
 
-# Check if a zone exists
-if auth.has_zone("production"):
-    # Get headers for a specific zone
-    headers = auth.get_headers_for_zone("production")
+# Check if an issuer is configured
+if auth.has_issuer("https://prod.keycard.cloud"):
+    # Get headers for a specific issuer
+    headers = auth.apply_headers("https://prod.keycard.cloud")
 
-    # Or get the BasicAuth instance for a zone
-    prod_auth = auth.get_auth_for_zone("production")
+    # Or get the BasicAuth instance for an issuer
+    prod_auth = auth.get_auth_for_issuer("https://prod.keycard.cloud")
+
+# Token operations select credentials per call with issuer=...
+with Client("https://prod.keycard.cloud", auth=auth) as client:
+    response = client.exchange_token(
+        subject_token="token",
+        issuer="https://prod.keycard.cloud",
+    )
 ```
 
 ## Operations

packages/oauth/src/keycardai/oauth/client.py

@@ -364,6 +364,7 @@ async def _ensure_initialized(self) -> None:
                     endpoint=self._discovered_endpoints.register,
                     transport=self.transport,
                     auth=self.auth_strategy,
+                    issuer=self.issuer,
                     user_agent=self.config.user_agent,
                     custom_headers=self.config.custom_headers,
                     timeout=self.config.timeout,
@@ -552,6 +553,7 @@ async def register_client(self, request: ClientRegistrationRequest | None = None
             endpoint=endpoints.register,
             transport=self.transport,
             auth=self.auth_strategy,
+            issuer=self.issuer,
             user_agent=self.config.user_agent,
             custom_headers=self.config.custom_headers,
             timeout=client_registration_args.get("timeout", self.config.timeout),
@@ -618,6 +620,7 @@ async def discover_server_metadata(self, request: ServerMetadataRequest | None =
             endpoint=self.issuer,
             transport=self.transport,
             auth=self.auth_strategy,
+            issuer=self.issuer,
             user_agent=self.config.user_agent,
             custom_headers=self.config.custom_headers,
             timeout=self.config.timeout,
@@ -632,13 +635,16 @@ async def discover_server_metadata(self, request: ServerMetadataRequest | None =
     async def exchange_token(
         self,
         request: TokenExchangeRequest,
+        *,
+        issuer: str | None = None,
     ) -> TokenResponse: ...
 
     @overload
     async def exchange_token(
         self,
         /,
         *,
+        issuer: str | None = None,
         subject_token: str,
         subject_token_type: str = ...,
         grant_type: str | None = None,
@@ -689,6 +695,10 @@ async def exchange_token(self, request: TokenExchangeRequest | None = None, /, *
 
         Args:
             request: TokenExchangeRequest with all exchange parameters
+            issuer: Issuer URL selecting which credentials a zone-aware auth
+                strategy (e.g. MultiZoneBasicAuth) applies for this call.
+                Defaults to the client's issuer. Single-credential strategies
+                ignore it. May be combined with either calling form.
             **token_exchange_args: Alternative to request - provide individual parameters
 
         Returns:
@@ -697,6 +707,7 @@ async def exchange_token(self, request: TokenExchangeRequest | None = None, /, *
         Raises:
             TypeError: If both request and token_exchange_args are provided
         """
+        issuer = token_exchange_args.pop("issuer", None)
         if request is not None and token_exchange_args:
             raise TypeError("Pass either `request` or keyword arguments, not both.")
 
@@ -709,6 +720,7 @@ async def exchange_token(self, request: TokenExchangeRequest | None = None, /, *
             endpoint=endpoints.token,
             transport=self.transport,
             auth=self.auth_strategy,
+            issuer=issuer if issuer is not None else self.issuer,
             user_agent=self.config.user_agent,
             custom_headers=self.config.custom_headers,
             timeout=token_exchange_args.get("timeout", self.config.timeout),
@@ -720,13 +732,16 @@ async def exchange_token(self, request: TokenExchangeRequest | None = None, /, *
     async def client_credentials_grant(
         self,
         request: ClientCredentialsRequest,
+        *,
+        issuer: str | None = None,
     ) -> TokenResponse: ...
 
     @overload
     async def client_credentials_grant(
         self,
         /,
         *,
+        issuer: str | None = None,
         resource: str | None = None,
         scope: str | None = None,
         client_assertion: str | None = None,
@@ -755,6 +770,10 @@ async def client_credentials_grant(self, request: ClientCredentialsRequest | Non
 
         Args:
             request: ClientCredentialsRequest with all grant parameters
+            issuer: Issuer URL selecting which credentials a zone-aware auth
+                strategy (e.g. MultiZoneBasicAuth) applies for this call.
+                Defaults to the client's issuer. Single-credential strategies
+                ignore it. May be combined with either calling form.
             **client_credentials_args: Alternative to request - provide individual parameters
 
         Returns:
@@ -763,6 +782,7 @@ async def client_credentials_grant(self, request: ClientCredentialsRequest | Non
         Raises:
             TypeError: If both request and client_credentials_args are provided
         """
+        issuer = client_credentials_args.pop("issuer", None)
         if request is not None and client_credentials_args:
             raise TypeError("Pass either `request` or keyword arguments, not both.")
 
@@ -775,6 +795,7 @@ async def client_credentials_grant(self, request: ClientCredentialsRequest | Non
             endpoint=endpoints.token,
             transport=self.transport,
             auth=self.auth_strategy,
+            issuer=issuer if issuer is not None else self.issuer,
             user_agent=self.config.user_agent,
             custom_headers=self.config.custom_headers,
             timeout=client_credentials_args.get("timeout", self.config.timeout),
@@ -821,6 +842,7 @@ async def exchange_authorization_code(
             endpoint=endpoints.token,
             transport=self.transport,
             auth=self.auth_strategy,
+            issuer=self.issuer,
             user_agent=self.config.user_agent,
             custom_headers=self.config.custom_headers,
             timeout=timeout or self.config.timeout,
@@ -889,6 +911,7 @@ async def impersonate(
             endpoint=endpoints.token,
             transport=self.transport,
             auth=self.auth_strategy,
+            issuer=self.issuer,
             user_agent=self.config.user_agent,
             custom_headers=self.config.custom_headers,
             timeout=timeout or self.config.timeout,
@@ -1048,6 +1071,7 @@ def _ensure_initialized(self) -> None:
                     endpoint=self._discovered_endpoints.register,
                     transport=self.transport,
                     auth=self.auth_strategy,
+                    issuer=self.issuer,
                     user_agent=self.config.user_agent,
                     custom_headers=self.config.custom_headers,
                     timeout=self.config.timeout,
@@ -1199,6 +1223,7 @@ def register_client(self, request: ClientRegistrationRequest | None = None, /, *
             endpoint=endpoints.register,
             transport=self.transport,
             auth=self.auth_strategy,
+            issuer=self.issuer,
             user_agent=self.config.user_agent,
             custom_headers=self.config.custom_headers,
             timeout=client_registration_args.get("timeout", self.config.timeout),
@@ -1264,6 +1289,7 @@ def discover_server_metadata(self, request: ServerMetadataRequest | None = None,
             endpoint=self.issuer,
             transport=self.transport,
             auth=self.auth_strategy,
+            issuer=self.issuer,
             user_agent=self.config.user_agent,
             custom_headers=self.config.custom_headers,
             timeout=self.config.timeout,
@@ -1278,13 +1304,16 @@ def discover_server_metadata(self, request: ServerMetadataRequest | None = None,
     def exchange_token(
         self,
         request: TokenExchangeRequest,
+        *,
+        issuer: str | None = None,
     ) -> TokenResponse: ...
 
     @overload
     def exchange_token(
         self,
         /,
         *,
+        issuer: str | None = None,
         subject_token: str,
         subject_token_type: str = ...,
         grant_type: str | None = None,
@@ -1335,6 +1364,10 @@ def exchange_token(self, request: TokenExchangeRequest | None = None, /, **token
 
         Args:
             request: TokenExchangeRequest with all exchange parameters
+            issuer: Issuer URL selecting which credentials a zone-aware auth
+                strategy (e.g. MultiZoneBasicAuth) applies for this call.
+                Defaults to the client's issuer. Single-credential strategies
+                ignore it. May be combined with either calling form.
             **token_exchange_args: Alternative to request - provide individual parameters
 
         Returns:
@@ -1343,6 +1376,7 @@ def exchange_token(self, request: TokenExchangeRequest | None = None, /, **token
         Raises:
             TypeError: If both request and token_exchange_args are provided
         """
+        issuer = token_exchange_args.pop("issuer", None)
         if request is not None and token_exchange_args:
             raise TypeError("Pass either `request` or keyword arguments, not both.")
 
@@ -1355,6 +1389,7 @@ def exchange_token(self, request: TokenExchangeRequest | None = None, /, **token
             endpoint=endpoints.token,
             transport=self.transport,
             auth=self.auth_strategy,
+            issuer=issuer if issuer is not None else self.issuer,
             user_agent=self.config.user_agent,
             custom_headers=self.config.custom_headers,
             timeout=token_exchange_args.get("timeout", self.config.timeout),
@@ -1366,13 +1401,16 @@ def exchange_token(self, request: TokenExchangeRequest | None = None, /, **token
     def client_credentials_grant(
         self,
         request: ClientCredentialsRequest,
+        *,
+        issuer: str | None = None,
     ) -> TokenResponse: ...
 
     @overload
     def client_credentials_grant(
         self,
         /,
         *,
+        issuer: str | None = None,
         resource: str | None = None,
         scope: str | None = None,
         client_assertion: str | None = None,
@@ -1401,6 +1439,10 @@ def client_credentials_grant(self, request: ClientCredentialsRequest | None = No
 
         Args:
             request: ClientCredentialsRequest with all grant parameters
+            issuer: Issuer URL selecting which credentials a zone-aware auth
+                strategy (e.g. MultiZoneBasicAuth) applies for this call.
+                Defaults to the client's issuer. Single-credential strategies
+                ignore it. May be combined with either calling form.
             **client_credentials_args: Alternative to request - provide individual parameters
 
         Returns:
@@ -1409,6 +1451,7 @@ def client_credentials_grant(self, request: ClientCredentialsRequest | None = No
         Raises:
             TypeError: If both request and client_credentials_args are provided
         """
+        issuer = client_credentials_args.pop("issuer", None)
         if request is not None and client_credentials_args:
             raise TypeError("Pass either `request` or keyword arguments, not both.")
 
@@ -1421,6 +1464,7 @@ def client_credentials_grant(self, request: ClientCredentialsRequest | None = No
             endpoint=endpoints.token,
             transport=self.transport,
             auth=self.auth_strategy,
+            issuer=issuer if issuer is not None else self.issuer,
             user_agent=self.config.user_agent,
             custom_headers=self.config.custom_headers,
             timeout=client_credentials_args.get("timeout", self.config.timeout),
@@ -1467,6 +1511,7 @@ def exchange_authorization_code(
             endpoint=endpoints.token,
             transport=self.transport,
             auth=self.auth_strategy,
+            issuer=self.issuer,
             user_agent=self.config.user_agent,
             custom_headers=self.config.custom_headers,
             timeout=timeout or self.config.timeout,
@@ -1535,6 +1580,7 @@ def impersonate(
             endpoint=endpoints.token,
             transport=self.transport,
             auth=self.auth_strategy,
+            issuer=self.issuer,
             user_agent=self.config.user_agent,
             custom_headers=self.config.custom_headers,
             timeout=timeout or self.config.timeout,

packages/oauth/src/keycardai/oauth/http/_context.py

@@ -39,6 +39,7 @@ class HTTPContext:
     timeout: float | None = None
     retries: int = 0
     headers: dict[str, str] | None = None
+    issuer: str | None = None
 
 
 def build_http_context(
@@ -49,6 +50,7 @@ def build_http_context(
     custom_headers: dict[str, str] | None = None,
     timeout: float | None = None,
     additional_headers: dict[str, str] | None = None,
+    issuer: str | None = None,
 ) -> HTTPContext:
     """Build HTTPContext with headers from configuration.
 
@@ -63,6 +65,8 @@ def build_http_context(
         custom_headers: Custom headers from configuration (optional)
         timeout: Optional timeout override
         additional_headers: Optional additional headers to merge
+        issuer: Optional issuer URL selecting which credentials a zone-aware
+            auth strategy applies for this operation
 
     Returns:
         HTTPContext configured with headers from config
@@ -94,4 +98,5 @@ def build_http_context(
         auth=auth,
         timeout=timeout,
         headers=headers,
+        issuer=issuer,
     )