fix: address pr review comments

Author: kishore7snehil

docs/MultipleCustomDomain.md

@@ -110,6 +110,9 @@ claims = await api_client.verify_request(
 )
 ```
 
+> [!WARNING]
+> If using `Host` or `X-Forwarded-Host` headers in your resolver, do not trust them without validation — these headers can be spoofed by clients. Always validate against a known allowlist of your API hostnames, or use server-determined values from your reverse proxy / API gateway that are not client-controllable.
+
 ### Tenant Lookup
 
 Resolve domains from a database or configuration service:
@@ -126,7 +129,13 @@ def tenant_resolver(context: DomainsResolverContext) -> list[str]:
 ```
 
 > [!NOTE]
-> The resolver runs synchronously. If your lookup requires async I/O (database queries, HTTP calls), wrap it with `asyncio.run()` or pre-load the domain mapping at startup.
+> The resolver can be synchronous or asynchronous. If your resolver is an `async def`, the SDK will automatically `await` the result.
+>
+> ```python
+> async def async_resolver(context: DomainsResolverContext) -> list[str]:
+>     domains = await fetch_domains_from_db(context["unverified_iss"])
+>     return domains
+> ```
 
 ---
 

src/auth0_api_python/api_client.py

@@ -88,8 +88,20 @@ def __init__(self, options: ApiClientOptions):
                 "Use 'domain' for single-domain mode, 'domains' for multi-domain support."
             )
 
+        # Validate that domain is set when client_id is configured
+        if options.client_id and not options.domain:
+            raise ConfigurationError(
+                "The 'domain' parameter is required when 'client_id' is configured."
+            )
         self.options = options
 
+        # Validate cache configuration
+        if not isinstance(options.cache_ttl_seconds, (int, float)) or options.cache_ttl_seconds < 0:
+            raise ConfigurationError("cache_ttl_seconds must be a non-negative number")
+
+        if not isinstance(options.cache_max_entries, int) or options.cache_max_entries < 2:
+            raise ConfigurationError("cache_max_entries must be an integer greater than 1")
+
         if options.cache_adapter:
             self._discovery_cache = options.cache_adapter
             self._jwks_cache = options.cache_adapter
@@ -177,7 +189,12 @@ async def _resolve_allowed_domains(
                 )
 
             # Normalize domains from resolver
-            allowed_domains = [normalize_domain(d) for d in result]
+            try:
+                allowed_domains = [normalize_domain(d) for d in result]
+            except ValueError as e:
+                raise DomainsResolverError(
+                    f"Domains resolver returned invalid domain: {str(e)}"
+                ) from e
         else:
             # Should never happen due to __init__ validation
             raise ConfigurationError("Invalid _allowed_domains type")
@@ -432,7 +449,10 @@ async def verify_access_token(
             raise VerifyAccessTokenError("Token missing 'iss' claim")
 
         # Normalize issuer for validation
-        normalized_iss = normalize_domain(unverified_iss)
+        try:
+            normalized_iss = normalize_domain(unverified_iss)
+        except ValueError as e:
+            raise VerifyAccessTokenError(f"Invalid token issuer format: {str(e)}") from e
 
         # Validate issuer against allowed domains (MCD)
         if self._allowed_domains is not None:
@@ -461,7 +481,10 @@ async def verify_access_token(
             raise VerifyAccessTokenError("Discovery metadata missing 'issuer' field")
 
         # Normalize discovery issuer for comparison
-        normalized_discovery_issuer = normalize_domain(discovery_issuer)
+        try:
+            normalized_discovery_issuer = normalize_domain(discovery_issuer)
+        except ValueError as e:
+            raise VerifyAccessTokenError(f"Invalid discovery issuer format: {str(e)}") from e
 
         if normalized_iss != normalized_discovery_issuer:
             raise VerifyAccessTokenError(

tests/test_api_client.py

@@ -2904,6 +2904,76 @@ async def test_mcd_init_with_non_string_domains_list():
         ))
 
 
+@pytest.mark.asyncio
+async def test_mcd_init_client_id_requires_domain():
+    """Test that client_id requires domain to be set (needed for token endpoint operations)."""
+    with pytest.raises(ConfigurationError, match="'domain' parameter is required when 'client_id'"):
+        ApiClient(ApiClientOptions(
+            domains=["tenant.auth0.com"],
+            client_id="my-client",
+            client_secret="my-secret",
+            audience="my-audience"
+        ))
+
+    # Should work with both domain and domains
+    client = ApiClient(ApiClientOptions(
+        domain="tenant.auth0.com",
+        domains=["tenant.auth0.com", "custom.example.com"],
+        client_id="my-client",
+        client_secret="my-secret",
+        audience="my-audience"
+    ))
+    assert client.options.client_id == "my-client"
+
+    # Should work with domains only (no client_id)
+    client = ApiClient(ApiClientOptions(
+        domains=["tenant.auth0.com"],
+        audience="my-audience"
+    ))
+    assert client._allowed_domains is not None
+
+
+@pytest.mark.asyncio
+async def test_cache_config_validation():
+    """Test that cache_max_entries and cache_ttl_seconds are validated at init."""
+    with pytest.raises(ConfigurationError, match="cache_ttl_seconds must be a non-negative number"):
+        ApiClient(ApiClientOptions(
+            domain="tenant.auth0.com",
+            audience="my-audience",
+            cache_ttl_seconds=-1
+        ))
+
+    with pytest.raises(ConfigurationError, match="cache_max_entries must be an integer greater than 1"):
+        ApiClient(ApiClientOptions(
+            domain="tenant.auth0.com",
+            audience="my-audience",
+            cache_max_entries=0
+        ))
+
+    with pytest.raises(ConfigurationError, match="cache_max_entries must be an integer greater than 1"):
+        ApiClient(ApiClientOptions(
+            domain="tenant.auth0.com",
+            audience="my-audience",
+            cache_max_entries=1
+        ))
+
+    with pytest.raises(ConfigurationError, match="cache_max_entries must be an integer greater than 1"):
+        ApiClient(ApiClientOptions(
+            domain="tenant.auth0.com",
+            audience="my-audience",
+            cache_max_entries=-5
+        ))
+
+    # cache_ttl_seconds=0 is valid (always refetch), cache_max_entries=2 is minimum
+    client = ApiClient(ApiClientOptions(
+        domain="tenant.auth0.com",
+        audience="my-audience",
+        cache_ttl_seconds=0,
+        cache_max_entries=2
+    ))
+    assert client._cache_ttl == 0
+
+
 @pytest.mark.asyncio
 async def test_mcd_resolve_allowed_domains_static_list():
     """Test _resolve_allowed_domains with static list."""
@@ -3111,6 +3181,21 @@ def bad_resolver(context):
         await api_client._resolve_allowed_domains("https://tenant1.auth0.com/")
 
 
+@pytest.mark.asyncio
+async def test_mcd_resolver_returns_invalid_domain_format():
+    """Test that resolver returning domains with invalid format raises DomainsResolverError."""
+    def resolver_with_http(context):
+        return ["tenant1.auth0.com", "http://invalid.com"]
+
+    api_client = ApiClient(ApiClientOptions(
+        domains=resolver_with_http,
+        audience="my-audience"
+    ))
+
+    with pytest.raises(DomainsResolverError, match="Domains resolver returned invalid domain"):
+        await api_client._resolve_allowed_domains("https://tenant1.auth0.com/")
+
+
 @pytest.mark.asyncio
 async def test_mcd_verify_rejects_symmetric_algorithm():
     """Test that verify_access_token rejects tokens with symmetric algorithms (HS256)."""
@@ -3319,6 +3404,55 @@ async def test_mcd_second_issuer_validation(httpx_mock):
     assert "verified token issuer does not match the discovery issuer" in str(err.value).lower()
 
 
+@pytest.mark.asyncio
+async def test_mcd_malformed_token_issuer_format(httpx_mock):
+    """Test that a token with malformed iss claim raises VerifyAccessTokenError."""
+    # Generate token with http:// issuer (rejected by normalize_domain)
+    token = await generate_token(
+        domain="evil.com",
+        user_id="user123",
+        audience="my-audience",
+        issuer="http://evil.com"
+    )
+
+    api_client = ApiClient(ApiClientOptions(
+        domain="tenant1.auth0.com",
+        audience="my-audience"
+    ))
+
+    with pytest.raises(VerifyAccessTokenError, match="Invalid token issuer format"):
+        await api_client.verify_access_token(token)
+
+
+@pytest.mark.asyncio
+async def test_mcd_malformed_discovery_issuer_format(httpx_mock):
+    """Test that malformed issuer in discovery metadata raises VerifyAccessTokenError."""
+    token = await generate_token(
+        domain="tenant1.auth0.com",
+        user_id="user123",
+        audience="my-audience",
+        issuer="https://tenant1.auth0.com/"
+    )
+
+    # Mock discovery returning malformed issuer with http://
+    httpx_mock.add_response(
+        method="GET",
+        url="https://tenant1.auth0.com/.well-known/openid-configuration",
+        json={
+            "issuer": "http://tenant1.auth0.com/",
+            "jwks_uri": "https://tenant1.auth0.com/.well-known/jwks.json"
+        }
+    )
+
+    api_client = ApiClient(ApiClientOptions(
+        domain="tenant1.auth0.com",
+        audience="my-audience"
+    ))
+
+    with pytest.raises(VerifyAccessTokenError, match="Invalid discovery issuer format"):
+        await api_client.verify_access_token(token)
+
+
 @pytest.mark.asyncio
 async def test_mcd_discovery_missing_issuer_field(httpx_mock):
     """Test that missing issuer field in discovery causes clear error."""