Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

Bound CIMD cache growth (#4852)

Jeremiah Lowin27ffa2c44166
diff --git a/fastmcp_slim/fastmcp/server/auth/cimd.py b/fastmcp_slim/fastmcp/server/auth/cimd.py
index 98297c60a..c55287f49 100644
--- a/fastmcp_slim/fastmcp/server/auth/cimd.py
+++ b/fastmcp_slim/fastmcp/server/auth/cimd.py
@@ -206,6 +206,8 @@ class CIMDFetcher:
# Maximum response size (bytes)
MAX_RESPONSE_SIZE = 5120 # 5KB
+ # Maximum number of distinct client documents retained in the process cache
+ MAX_CACHE_SIZE = 1_000
# Default cache TTL (seconds)
DEFAULT_CACHE_TTL_SECONDS = 3600
@@ -221,6 +223,20 @@ class CIMDFetcher:
self.timeout = timeout
self._cache: dict[str, _CIMDCacheEntry] = {}
+ def _store_cache_entry(
+ self,
+ client_id_url: str,
+ entry: _CIMDCacheEntry,
+ ) -> None:
+ """Store a document in the bounded process-local cache."""
+ self._cache[client_id_url] = entry
+ while len(self._cache) > self.MAX_CACHE_SIZE:
+ del self._cache[next(iter(self._cache))]
+
+ def _remove_cache_entry(self, client_id_url: str) -> None:
+ """Remove a document from the process-local cache."""
+ self._cache.pop(client_id_url, None)
+
def _parse_cache_policy(
self, headers: Mapping[str, str], now: float
) -> _CIMDCachePolicy:
@@ -370,16 +386,19 @@ class CIMDFetcher:
)
if not policy.no_store:
- self._cache[client_id_url] = _CIMDCacheEntry(
- doc=cached.doc,
- etag=policy.etag or cached.etag,
- last_modified=policy.last_modified or cached.last_modified,
- expires_at=policy.expires_at,
- freshness_lifetime=policy.freshness_lifetime,
- must_revalidate=policy.must_revalidate,
+ self._store_cache_entry(
+ client_id_url,
+ _CIMDCacheEntry(
+ doc=cached.doc,
+ etag=policy.etag or cached.etag,
+ last_modified=policy.last_modified or cached.last_modified,
+ expires_at=policy.expires_at,
+ freshness_lifetime=policy.freshness_lifetime,
+ must_revalidate=policy.must_revalidate,
+ ),
)
else:
- self._cache.pop(client_id_url, None)
+ self._remove_cache_entry(client_id_url)
return cached.doc
now = time.time()
@@ -418,16 +437,19 @@ class CIMDFetcher:
)
if not policy.no_store:
- self._cache[client_id_url] = _CIMDCacheEntry(
- doc=doc,
- etag=policy.etag,
- last_modified=policy.last_modified,
- expires_at=policy.expires_at,
- freshness_lifetime=policy.freshness_lifetime,
- must_revalidate=policy.must_revalidate,
+ self._store_cache_entry(
+ client_id_url,
+ _CIMDCacheEntry(
+ doc=doc,
+ etag=policy.etag,
+ last_modified=policy.last_modified,
+ expires_at=policy.expires_at,
+ freshness_lifetime=policy.freshness_lifetime,
+ must_revalidate=policy.must_revalidate,
+ ),
)
else:
- self._cache.pop(client_id_url, None)
+ self._remove_cache_entry(client_id_url)
return doc
@@ -608,21 +630,21 @@ class CIMDAssertionValidator:
# Expired in cache, can be reused (clean it up)
del self._jti_cache[jti]
- # Add to cache with expiration time
- # Use the assertion's exp claim so it stays cached until it would expire anyway
- self._jti_cache[jti] = exp
-
# Emergency size limit (shouldn't hit with proper TTL cleanup)
- if len(self._jti_cache) > self._jti_cache_max_size:
+ if len(self._jti_cache) >= self._jti_cache_max_size:
self._cleanup_expired_jtis()
# If still over limit after cleanup, reject to prevent DoS
- if len(self._jti_cache) > self._jti_cache_max_size:
+ if len(self._jti_cache) >= self._jti_cache_max_size:
self.logger.warning(
"JTI cache at max capacity (%d), possible attack",
self._jti_cache_max_size,
)
raise ValueError("Server overloaded, please retry")
+ # Add to cache with expiration time
+ # Use the assertion's exp claim so it stays cached until it would expire anyway
+ self._jti_cache[jti] = exp
+
self.logger.debug(
"JWT assertion validated successfully for client %s", client_id
)
diff --git a/fastmcp_slim/fastmcp/server/auth/oauth_proxy/proxy.py b/fastmcp_slim/fastmcp/server/auth/oauth_proxy/proxy.py
index 686ac6df3..e9f04559e 100644
--- a/fastmcp_slim/fastmcp/server/auth/oauth_proxy/proxy.py
+++ b/fastmcp_slim/fastmcp/server/auth/oauth_proxy/proxy.py
@@ -921,7 +921,8 @@ class OAuthProxy(OAuthProvider, ConsentMixin):
provided to the DCR client during registration, not the upstream client ID.
For unregistered clients, returns None (which will raise an error in the SDK).
- CIMD clients (URL-based client IDs) are looked up and cached automatically.
+ CIMD clients (URL-based client IDs) are looked up through the bounded
+ in-process document cache rather than persisted in the DCR client store.
"""
# Load from storage
client = await self._client_store.get(key=client_id)
@@ -931,31 +932,22 @@ class OAuthProxy(OAuthProvider, ConsentMixin):
client.allowed_redirect_uri_patterns = (
self._allowed_client_redirect_uris
)
+ if client.cimd_document is None:
+ return client
- # Refresh CIMD clients using HTTP cache-aware fetcher.
- if self._cimd_manager is not None and client.cimd_document is not None:
- try:
- refreshed = await self._cimd_manager.get_client(client_id)
- if refreshed is not None:
- await self._client_store.put(key=client_id, value=refreshed)
- return refreshed
- except Exception as e:
- logger.debug(
- "CIMD refresh failed for %s, using cached client: %s",
- client_id,
- e,
- )
-
- return client
-
- # Client not in storage β€” try CIMD lookup for URL-based client IDs
+ # Resolve URL-derived clients through the bounded CIMD cache. Older
+ # versions persisted them indefinitely, so remove those records only
+ # after a successful refresh and keep them as a fallback until then.
if self._cimd_manager is not None and self._cimd_manager.is_cimd_client_id(
client_id
):
cimd_client = await self._cimd_manager.get_client(client_id)
if cimd_client is not None:
- await self._client_store.put(key=client_id, value=cimd_client)
+ if client is not None:
+ await self._client_store.delete(key=client_id)
return cimd_client
+ if client is not None:
+ return client
# Some MCP clients (e.g. claude.ai) skip Dynamic Client Registration and
# send the upstream OAuth App's client_id directly in the /authorize request.
diff --git a/tests/server/auth/oauth_proxy/test_client_registration.py b/tests/server/auth/oauth_proxy/test_client_registration.py
index f90211349..c426c3f07 100644
--- a/tests/server/auth/oauth_proxy/test_client_registration.py
+++ b/tests/server/auth/oauth_proxy/test_client_registration.py
@@ -1,5 +1,7 @@
"""Tests for OAuth proxy client registration (DCR)."""
+from unittest.mock import AsyncMock
+
import httpx2
import pytest
from mcp.server.auth.provider import RegistrationError
@@ -7,7 +9,11 @@ from mcp.shared.auth import OAuthClientInformationFull
from pydantic import AnyUrl
from starlette.applications import Starlette
-from fastmcp.server.auth.oauth_proxy.models import InvalidRedirectUriError
+from fastmcp.server.auth.cimd import CIMDDocument
+from fastmcp.server.auth.oauth_proxy.models import (
+ InvalidRedirectUriError,
+ ProxyDCRClient,
+)
class TestOAuthProxyClientRegistration:
@@ -101,6 +107,73 @@ class TestOAuthProxyClientRegistration:
client = await oauth_proxy.get_client("unknown-client")
assert client is None
+ async def test_cimd_client_is_not_persisted(self, oauth_proxy):
+ """URL-derived clients should not grow the persistent DCR registry."""
+ client_id = "https://example.com/client.json"
+ document = CIMDDocument(
+ client_id=client_id,
+ redirect_uris=["http://localhost:3000/callback"],
+ )
+ cimd_client = ProxyDCRClient(
+ client_id=client_id,
+ redirect_uris=[AnyUrl("http://localhost:3000/callback")],
+ token_endpoint_auth_method="none",
+ cimd_document=document,
+ )
+ assert oauth_proxy._cimd_manager is not None
+ oauth_proxy._cimd_manager.get_client = AsyncMock(return_value=cimd_client)
+
+ resolved = await oauth_proxy.get_client(client_id)
+
+ assert resolved == cimd_client
+ assert await oauth_proxy._client_store.get(key=client_id) is None
+
+ async def test_legacy_persisted_cimd_client_is_removed(self, oauth_proxy):
+ """Previously persisted CIMD clients are migrated out of the DCR registry."""
+ client_id = "https://example.com/legacy-client.json"
+ document = CIMDDocument(
+ client_id=client_id,
+ redirect_uris=["http://localhost:3000/callback"],
+ )
+ cimd_client = ProxyDCRClient(
+ client_id=client_id,
+ redirect_uris=[AnyUrl("http://localhost:3000/callback")],
+ token_endpoint_auth_method="none",
+ cimd_document=document,
+ )
+ await oauth_proxy._client_store.put(key=client_id, value=cimd_client)
+ assert oauth_proxy._cimd_manager is not None
+ oauth_proxy._cimd_manager.get_client = AsyncMock(return_value=cimd_client)
+
+ resolved = await oauth_proxy.get_client(client_id)
+
+ assert resolved == cimd_client
+ assert await oauth_proxy._client_store.get(key=client_id) is None
+
+ async def test_legacy_persisted_cimd_client_survives_failed_refresh(
+ self, oauth_proxy
+ ):
+ """Legacy clients remain usable until migration can succeed."""
+ client_id = "https://example.com/legacy-client.json"
+ document = CIMDDocument(
+ client_id=client_id,
+ redirect_uris=["http://localhost:3000/callback"],
+ )
+ cimd_client = ProxyDCRClient(
+ client_id=client_id,
+ redirect_uris=[AnyUrl("http://localhost:3000/callback")],
+ token_endpoint_auth_method="none",
+ cimd_document=document,
+ )
+ await oauth_proxy._client_store.put(key=client_id, value=cimd_client)
+ assert oauth_proxy._cimd_manager is not None
+ oauth_proxy._cimd_manager.get_client = AsyncMock(return_value=None)
+
+ resolved = await oauth_proxy.get_client(client_id)
+
+ assert resolved == cimd_client
+ assert await oauth_proxy._client_store.get(key=client_id) == cimd_client
+
async def test_dcr_client_rejects_unregistered_redirect_uri(self, oauth_proxy):
"""DCR clients honor their registered redirect_uris by default."""
client_info = OAuthClientInformationFull(
diff --git a/tests/server/auth/test_cimd.py b/tests/server/auth/test_cimd.py
index bf7013990..b88f23bf6 100644
--- a/tests/server/auth/test_cimd.py
+++ b/tests/server/auth/test_cimd.py
@@ -2,8 +2,9 @@
from __future__ import annotations
+import json
import time
-from unittest.mock import patch
+from unittest.mock import AsyncMock, patch
import pytest
from pydantic import AnyHttpUrl, ValidationError
@@ -14,6 +15,7 @@ from fastmcp.server.auth.cimd import (
CIMDFetchError,
CIMDValidationError,
)
+from fastmcp.server.auth.ssrf import SSRFFetchResponse
# Standard public IP used for DNS mocking in tests
TEST_PUBLIC_IP = "93.184.216.34"
@@ -257,6 +259,31 @@ class TestCIMDFetcherHTTP:
assert first.client_id == second.client_id
assert len(httpx_mock.get_requests()) == 1
+ async def test_fetch_cache_evicts_oldest_document(self, fetcher: CIMDFetcher):
+ """Distinct client URLs cannot grow the document cache without bound."""
+ fetcher.MAX_CACHE_SIZE = 2
+
+ async def fake_fetch(url: str, **kwargs) -> SSRFFetchResponse:
+ document = {
+ "client_id": url,
+ "redirect_uris": ["http://localhost:3000/callback"],
+ }
+ return SSRFFetchResponse(
+ content=json.dumps(document).encode(),
+ status_code=200,
+ headers={"cache-control": "max-age=3600"},
+ )
+
+ urls = [f"https://example.com/client-{index}.json" for index in range(3)]
+ with patch(
+ "fastmcp.server.auth.cimd.ssrf_safe_fetch_response",
+ new=AsyncMock(side_effect=fake_fetch),
+ ):
+ for url in urls:
+ await fetcher.fetch(url)
+
+ assert list(fetcher._cache) == urls[1:]
+
async def test_fetch_cache_control_max_age(
self, fetcher: CIMDFetcher, httpx_mock, mock_dns
):
diff --git a/tests/server/auth/test_cimd_validators.py b/tests/server/auth/test_cimd_validators.py
index f92503f0d..eefabf0bc 100644
--- a/tests/server/auth/test_cimd_validators.py
+++ b/tests/server/auth/test_cimd_validators.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+import time
from unittest.mock import AsyncMock, patch
import pytest
@@ -299,6 +300,38 @@ class TestCIMDAssertionValidator:
)
assert "replay" in str(exc_info.value).lower()
+ async def test_jti_cache_does_not_grow_past_capacity(
+ self, validator, key_pair, cimd_doc_with_inline_jwks
+ ):
+ """Rejected assertions do not remain in a full replay cache."""
+ client_id = "https://example.com/client.json"
+ token_endpoint = "https://oauth.example.com/token"
+ validator._jti_cache_max_size = 2
+ validator._jti_cache = {
+ "filler-a": time.time() + 120,
+ "filler-b": time.time() + 120,
+ }
+
+ for index in range(3):
+ assertion = key_pair.create_token(
+ subject=client_id,
+ issuer=client_id,
+ audience=token_endpoint,
+ additional_claims={"jti": f"fresh-{index}"},
+ expires_in_seconds=60,
+ kid="test-key-1",
+ )
+
+ with pytest.raises(ValueError, match="Server overloaded"):
+ await validator.validate_assertion(
+ assertion,
+ client_id,
+ token_endpoint,
+ cimd_doc_with_inline_jwks,
+ )
+
+ assert len(validator._jti_cache) == 2
+
async def test_rejects_expired_token(
self, validator, key_pair, cimd_doc_with_inline_jwks
):