feat: enhance domain handling and validation in ApiClient and caching mechanisms

Author: kishore7snehil

docs/Caching.md

@@ -71,7 +71,9 @@ api_client = ApiClient(ApiClientOptions(
 ))
 ```
 
-When a custom adapter is provided, both the discovery cache and JWKS cache use it. Cache keys are inherently distinct — discovery keys are normalized issuer URLs (e.g., `https://tenant.auth0.com/`) and JWKS keys are `jwks_uri` values (e.g., `https://tenant.auth0.com/.well-known/jwks.json`).
+When a custom adapter is provided, both the discovery cache and JWKS cache use the same adapter instance. Cache keys are inherently distinct — discovery keys are normalized issuer URLs (e.g., `https://tenant.auth0.com/`) and JWKS keys are `jwks_uri` values (e.g., `https://tenant.auth0.com/.well-known/jwks.json`).
+
+**Note:** Because both caches share one adapter, entries share the same LRU eviction pool. A JWKS entry could evict a discovery entry (or vice versa) under memory pressure. Set `cache_max_entries` accordingly — recommended: `number_of_issuers × 3`. With the default `InMemoryCache`, discovery and JWKS caches are separate and each gets its own `max_entries` budget.
 
 ## Tuning Recommendations
 

src/auth0_api_python/api_client.py

@@ -1,3 +1,4 @@
+import asyncio
 import time
 from collections.abc import Mapping, Sequence
 from typing import Any, Optional, Union
@@ -63,6 +64,10 @@ def __init__(self, options: ApiClientOptions):
                 # Static list validation
                 if len(options.domains) == 0:
                     raise ConfigurationError("domains list cannot be empty")
+                if not all(isinstance(d, str) and d.strip() for d in options.domains):
+                    raise ConfigurationError(
+                        "domains list must contain only non-empty strings"
+                    )
                 # Normalize and store domains
                 self._allowed_domains = [normalize_domain(d) for d in options.domains]
             elif callable(options.domains):
@@ -145,9 +150,11 @@ async def _resolve_allowed_domains(
                 'unverified_iss': unverified_iss
             }
 
-            # Invoke resolver
+            # Invoke resolver (supports both sync and async resolvers)
             try:
                 result = self._allowed_domains(context)
+                if asyncio.iscoroutine(result) or asyncio.isfuture(result):
+                    result = await result
             except Exception as e:
                 raise DomainsResolverError(
                     f"Domains resolver function failed: {str(e)}"
@@ -164,6 +171,11 @@ async def _resolve_allowed_domains(
                     "Domains resolver returned an empty list"
                 )
 
+            if not all(isinstance(d, str) and d.strip() for d in result):
+                raise DomainsResolverError(
+                    "Domains resolver must return a list of non-empty strings"
+                )
+
             # Normalize domains from resolver
             allowed_domains = [normalize_domain(d) for d in result]
         else:
@@ -984,11 +996,11 @@ async def _discover(self, issuer: Optional[str] = None) -> dict[str, Any]:
             OIDC discovery metadata dictionary
         """
         if issuer:
+            cache_key = issuer  # Already normalized by caller
             domain = issuer.replace('https://', '').replace('http://', '').rstrip('/')
         else:
             domain = self.options.domain
-
-        cache_key = normalize_domain(f"https://{domain}")
+            cache_key = normalize_domain(f"https://{domain}")
 
         cached = self._discovery_cache.get(cache_key)
         if cached:

src/auth0_api_python/cache.py

@@ -1,5 +1,5 @@
+import time
 from abc import ABC, abstractmethod
-from datetime import datetime, timedelta
 from typing import Any, Optional
 
 
@@ -74,8 +74,12 @@ class InMemoryCache(CacheAdapter):
     """
     Default in-memory cache implementation with LRU eviction.
 
+    Designed for asyncio (single-threaded).
+    For multi-threaded environments, implement a custom CacheAdapter
+    with appropriate locking.
+
     Features:
-    - TTL (time-to-live) support per entry
+    - TTL (time-to-live) support per entry using monotonic clock
     - LRU (Least Recently Used) eviction when max_entries reached
     - No external dependencies
 
@@ -96,7 +100,7 @@ def __init__(self, max_entries: int = 100):
         Args:
             max_entries: Maximum number of cache entries (default: 100)
         """
-        self._cache: dict[str, tuple[Any, Optional[datetime]]] = {}
+        self._cache: dict[str, tuple[Any, Optional[float]]] = {}
         self._max_entries = max_entries
 
     def get(self, key: str) -> Optional[Any]:
@@ -116,7 +120,7 @@ def get(self, key: str) -> Optional[Any]:
 
         value, expiry = self._cache[key]
 
-        if expiry and datetime.now() > expiry:
+        if expiry is not None and time.monotonic() > expiry:
             del self._cache[key]
             return None
 
@@ -145,8 +149,8 @@ def set(self, key: str, value: Any, ttl_seconds: Optional[int] = None) -> None:
             del self._cache[oldest_key]
 
         expiry = None
-        if ttl_seconds:
-            expiry = datetime.now() + timedelta(seconds=ttl_seconds)
+        if ttl_seconds is not None:
+            expiry = time.monotonic() + ttl_seconds
 
         self._cache[key] = (value, expiry)
 

src/auth0_api_python/types.py

@@ -2,7 +2,8 @@
 Type definitions for auth0-api-python SDK
 """
 
-from typing import Callable, Optional, TypedDict
+from collections.abc import Awaitable, Callable
+from typing import Optional, TypedDict, Union
 
 
 class DomainsResolverContext(TypedDict, total=False):
@@ -12,19 +13,20 @@ class DomainsResolverContext(TypedDict, total=False):
     Attributes:
         request_url: The URL the API request was made to (optional)
         request_headers: Request headers dict (e.g., Host, X-Forwarded-Host) (optional)
-        unverified_iss: The issuer claim from the unverified token (required)
+        unverified_iss: The issuer claim from the unverified token
     """
     request_url: Optional[str]
     request_headers: Optional[dict]
-    unverified_iss: str  # This is required, others are optional
+    unverified_iss: str
 
-
-DomainsResolver = Callable[[DomainsResolverContext], list[str]]
+DomainsResolver = Callable[
+    [DomainsResolverContext], Union[list[str], Awaitable[list[str]]]
+]
 """
 Type alias for domains resolver function.
 
-A DomainsResolver is a function that receives a DomainsResolverContext and returns
-a list of allowed domain strings.
+A DomainsResolver is a sync or async function that receives a DomainsResolverContext
+and returns a list of allowed domain strings.
 
 Args:
     context (DomainsResolverContext): Dictionary containing:
@@ -35,14 +37,17 @@ class DomainsResolverContext(TypedDict, total=False):
 Returns:
     list[str]: List of allowed domain strings (e.g., ['tenant.auth0.com'])
 
-Example:
+Example (sync):
     from auth0_api_python import DomainsResolverContext
 
     def my_resolver(context: DomainsResolverContext) -> list[str]:
-        unverified_iss = context['unverified_iss']
-        request_url = context.get('request_url')
-        request_headers = context.get('request_headers')
-
-        # Fetch allowed domains based on context
-        return ['tenant1.auth0.com', 'tenant2.auth0.com']
+        host = (context.get('request_headers') or {}).get('host')
+        if host == 'api.brand.com':
+            return ['brand.custom-domain.com']
+        return ['tenant.auth0.com']
+
+Example (async):
+    async def my_async_resolver(context: DomainsResolverContext) -> list[str]:
+        domains = await db.lookup_domains(context['unverified_iss'])
+        return domains
 """

src/auth0_api_python/utils.py

@@ -53,10 +53,33 @@ def normalize_domain(domain: str) -> str:
         Normalized issuer URL (e.g., "https://tenant.auth0.com/")
 
     """
+    if not isinstance(domain, str) or not domain.strip():
+        raise ValueError("domain must be a non-empty string")
+
     domain = domain.strip().lower()
-    domain = domain.replace('http://', '').replace('https://', '')
-    domain = domain.rstrip('/')
-    return f"https://{domain}/"
+
+    # Reject http:// explicitly
+    if domain.startswith('http://'):
+        raise ValueError("invalid domain URL (https required)")
+
+    # Strip https:// prefix
+    domain = domain.replace('https://', '')
+
+    # Split host from any path/query/fragment
+    host = domain.split('/')[0].split('?')[0].split('#')[0]
+
+    # Reject credentials
+    if '@' in host:
+        raise ValueError("invalid domain URL (credentials are not allowed)")
+
+    # Check for path segments, query, or fragment
+    bare = domain.rstrip('/')
+    if bare != host:
+        raise ValueError(
+            "invalid domain URL (path/query/fragment are not allowed)"
+        )
+
+    return f"https://{host}/"
 
 
 async def fetch_oidc_metadata(