Log refresh-token misses in OAuthProxy instead of failing silently (#4276)

Author: jlowin

fastmcp_slim/fastmcp/server/auth/oauth_proxy/proxy.py

@@ -1371,6 +1371,13 @@ async def load_refresh_token(
         token_hash = _hash_token(refresh_token)
         metadata = await self._refresh_token_store.get(key=token_hash)
         if not metadata:
+            logger.warning(
+                "Refresh token not found for client=%s (token_hash=%s); it was "
+                "already rotated, expired, or revoked. Rejecting with invalid_grant, "
+                "which forces the client to re-authenticate.",
+                client.client_id,
+                token_hash[:8],
+            )
             return None
         # Verify token belongs to this client (prevents cross-client token usage)
         if metadata.client_id != client.client_id:

tests/server/auth/oauth_proxy/test_tokens.py

@@ -1,5 +1,6 @@
 """Tests for OAuth proxy token endpoint and handling."""
 
+import logging
 import time
 from unittest.mock import AsyncMock, Mock, patch
 
@@ -1883,3 +1884,30 @@ async def test_proactive_refresh_when_validated_but_within_threshold(
         assert result is not None
         assert result.token == "refreshed-upstream-access"
         mock_oauth_client.refresh_token.assert_called_once()
+
+
+class TestRefreshTokenMissLogging:
+    """A refresh-token miss forces a user-visible reconnect, so it must not be silent."""
+
+    async def test_unknown_refresh_token_logs_warning(self, oauth_proxy, caplog):
+        client = OAuthClientInformationFull(
+            client_id="test-client",
+            client_secret="test-secret",
+            redirect_uris=[AnyUrl("http://localhost:12345/callback")],
+        )
+
+        proxy_logger = logging.getLogger("fastmcp.server.auth.oauth_proxy.proxy")
+        caplog.set_level(logging.WARNING)
+        proxy_logger.addHandler(caplog.handler)
+        try:
+            result = await oauth_proxy.load_refresh_token(client, "nonexistent-token")
+        finally:
+            proxy_logger.removeHandler(caplog.handler)
+
+        assert result is None
+        assert any(
+            record.levelno == logging.WARNING
+            and "Refresh token not found" in record.getMessage()
+            and "test-client" in record.getMessage()
+            for record in caplog.records
+        )