fastmcp 2.13.0rc2__py3-none-any.whl → 2.13.0.1__py3-none-any.whl

fastmcp/server/auth/oauth_proxy.py

@@ -31,9 +31,11 @@ from urllib.parse import urlencode, urlparse
 import httpx
 from authlib.common.security import generate_token
 from authlib.integrations.httpx_client import AsyncOAuth2Client
+from cryptography.fernet import Fernet
 from key_value.aio.adapters.pydantic import PydanticAdapter
 from key_value.aio.protocols import AsyncKeyValue
-from key_value.aio.stores.memory import MemoryStore
+from key_value.aio.stores.disk import DiskStore
+from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
 from mcp.server.auth.handlers.token import TokenErrorResponse, TokenSuccessResponse
 from mcp.server.auth.handlers.token import TokenHandler as _SDKTokenHandler
 from mcp.server.auth.json_response import PydanticJSONResponse
@@ -55,11 +57,14 @@ from pydantic import AnyHttpUrl, AnyUrl, BaseModel, Field, SecretStr
 from starlette.requests import Request
 from starlette.responses import HTMLResponse, RedirectResponse
 from starlette.routing import Route
+from typing_extensions import override
 
+from fastmcp import settings
 from fastmcp.server.auth.auth import OAuthProvider, TokenVerifier
+from fastmcp.server.auth.handlers.authorize import AuthorizationHandler
 from fastmcp.server.auth.jwt_issuer import (
     JWTIssuer,
-    TokenEncryption,
+    derive_jwt_key,
 )
 from fastmcp.server.auth.redirect_validation import (
     validate_redirect_uri,
@@ -68,9 +73,10 @@ from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.ui import (
     BUTTON_STYLES,
     DETAIL_BOX_STYLES,
+    DETAILS_STYLES,
     INFO_BOX_STYLES,
+    REDIRECT_SECTION_STYLES,
     TOOLTIP_STYLES,
-    create_detail_box,
     create_logo,
     create_page,
     create_secure_html_response,
@@ -142,12 +148,13 @@ class UpstreamTokenSet(BaseModel):
     """Stored upstream OAuth tokens from identity provider.
 
     These tokens are obtained from the upstream provider (Google, GitHub, etc.)
-    and are stored encrypted at rest. They are never exposed to MCP clients.
+    and stored in plaintext within this model. Encryption is handled transparently
+    at the storage layer via FernetEncryptionWrapper. Tokens are never exposed to MCP clients.
     """
 
     upstream_token_id: str  # Unique ID for this token set
-    access_token: bytes  # Encrypted upstream access token
-    refresh_token: bytes | None  # Encrypted upstream refresh token
+    access_token: str  # Upstream access token
+    refresh_token: str | None  # Upstream refresh token
     refresh_token_expires_at: (
         float | None
     )  # Unix timestamp when refresh token expires (if known)
@@ -233,16 +240,13 @@ def create_consent_html(
     txn_id: str,
     csrf_token: str,
     client_name: str | None = None,
-    title: str = "Authorization Consent",
+    title: str = "Application Access Request",
     server_name: str | None = None,
     server_icon_url: str | None = None,
     server_website_url: str | None = None,
+    client_website_url: str | None = None,
 ) -> str:
     """Create a styled HTML consent page for OAuth authorization requests."""
-    # Format scopes for display
-    scopes_display = ", ".join(scopes) if scopes else "None"
-
-    # Build warning box with client name if available
     import html as html_module
 
     client_display = html_module.escape(client_name or client_id)
@@ -251,29 +255,58 @@ def create_consent_html(
     # Make server name a hyperlink if website URL is available
     if server_website_url:
         website_url_escaped = html_module.escape(server_website_url)
-        server_display = f'<a href="{website_url_escaped}" target="_blank" rel="noopener noreferrer">{server_name_escaped}</a>'
+        server_display = f'<a href="{website_url_escaped}" target="_blank" rel="noopener noreferrer" class="server-name-link">{server_name_escaped}</a>'
     else:
         server_display = server_name_escaped
 
-    warning_box = f"""
-        <div class="warning-box">
-            <p><strong>{client_display}</strong> is requesting access to <strong>{server_display}</strong>.</p>
-            <p>Review the details below before approving.</p>
+    # Build intro box with call-to-action
+    intro_box = f"""
+        <div class="info-box">
+            <p>The application <strong>{client_display}</strong> wants to access the MCP server <strong>{server_display}</strong>. Please ensure you recognize the callback address below.</p>
+        </div>
+    """
+
+    # Build redirect URI section (yellow box, centered)
+    redirect_uri_escaped = html_module.escape(redirect_uri)
+    redirect_section = f"""
+        <div class="redirect-section">
+            <span class="label">Credentials will be sent to:</span>
+            <div class="value">{redirect_uri_escaped}</div>
         </div>
     """
 
-    # Build detail box with client information
-    detail_rows = []
-    if client_name:
-        detail_rows.append(("Client Name", client_name))
-    detail_rows.extend(
+    # Build advanced details with collapsible section
+    detail_rows = [
+        ("Application Name", html_module.escape(client_name or client_id)),
+        ("Application Website", html_module.escape(client_website_url or "N/A")),
+        ("Application ID", client_id),
+        ("Redirect URI", redirect_uri_escaped),
+        (
+            "Requested Scopes",
+            ", ".join(html_module.escape(s) for s in scopes) if scopes else "None",
+        ),
+    ]
+
+    detail_rows_html = "\n".join(
         [
-            ("Client ID", client_id),
-            ("Redirect URI", redirect_uri),
-            ("Requested Scopes", scopes_display),
+            f"""
+        <div class="detail-row">
+            <div class="detail-label">{label}:</div>
+            <div class="detail-value">{value}</div>
+        </div>
+        """
+            for label, value in detail_rows
         ]
     )
-    detail_box = create_detail_box(detail_rows)
+
+    advanced_details = f"""
+        <details>
+            <summary>Advanced Details</summary>
+            <div class="detail-box">
+                {detail_rows_html}
+            </div>
+        </details>
+    """
 
     # Build form with buttons
     form = f"""
@@ -281,13 +314,13 @@ def create_consent_html(
             <input type="hidden" name="txn_id" value="{txn_id}" />
             <input type="hidden" name="csrf_token" value="{csrf_token}" />
             <div class="button-group">
-                <button type="submit" name="action" value="approve" class="btn-approve">Approve</button>
+                <button type="submit" name="action" value="approve" class="btn-approve">Allow Access</button>
                 <button type="submit" name="action" value="deny" class="btn-deny">Deny</button>
             </div>
         </form>
     """
 
-    # Build help link with tooltip
+    # Build help link with tooltip (identical to current implementation)
     help_link = """
         <div class="help-link-container">
             <span class="help-link">
@@ -312,9 +345,10 @@ def create_consent_html(
     content = f"""
         <div class="container">
             {create_logo(icon_url=server_icon_url, alt_text=server_name or "FastMCP")}
-            <h1>Authorization Consent</h1>
-            {warning_box}
-            {detail_box}
+            <h1>Application Access Request</h1>
+            {intro_box}
+            {redirect_section}
+            {advanced_details}
             {form}
         </div>
         {help_link}
@@ -322,7 +356,12 @@ def create_consent_html(
 
     # Additional styles needed for this page
     additional_styles = (
-        INFO_BOX_STYLES + DETAIL_BOX_STYLES + BUTTON_STYLES + TOOLTIP_STYLES
+        INFO_BOX_STYLES
+        + REDIRECT_SECTION_STYLES
+        + DETAILS_STYLES
+        + DETAIL_BOX_STYLES
+        + BUTTON_STYLES
+        + TOOLTIP_STYLES
     )
 
     # Need to allow form-action for form submission
@@ -525,10 +564,10 @@ class OAuthProxy(OAuthProvider):
         extra_token_params: dict[str, str] | None = None,
         # Client storage
         client_storage: AsyncKeyValue | None = None,
-        # JWT signing key (optional, ephemeral if not provided)
+        # JWT signing key
         jwt_signing_key: str | bytes | None = None,
-        # Token encryption key (optional, ephemeral if not provided)
-        token_encryption_key: str | bytes | None = None,
+        # Consent screen configuration
+        require_authorization_consent: bool = True,
     ):
         """Initialize the OAuth proxy provider.
 
@@ -562,14 +601,18 @@ class OAuthProxy(OAuthProvider):
                 Example: {"audience": "https://api.example.com"}
             extra_token_params: Additional parameters to forward to the upstream token endpoint.
                 Useful for provider-specific parameters during token exchange.
-            client_storage: An AsyncKeyValue-compatible store for client registrations, registrations are stored in memory if not provided
-            jwt_signing_key: Optional secret for signing FastMCP JWT tokens (accepts any string or bytes).
-                Default: ephemeral (random salt at startup, won't survive restart).
-                Production: provide explicit key from environment variable.
-            token_encryption_key: Optional secret for encrypting upstream tokens at rest (accepts any string or bytes).
-                Default: ephemeral (random salt at startup, won't survive restart).
-                Production: provide explicit key from environment variable.
+            client_storage: Storage backend for OAuth state (client registrations, tokens).
+                If None, an encrypted DiskStore will be created in the data directory.
+            jwt_signing_key: Secret for signing FastMCP JWT tokens (any string or bytes).
+                If bytes are provided, they will be used as-is.
+                If a string is provided, it will be derived into a 32-byte key using PBKDF2 (1.2M iterations).
+                If not provided, it will be derived from the upstream client secret using HKDF.
+            require_authorization_consent: Whether to require user consent before authorizing clients (default True).
+                When True, users see a consent screen before being redirected to the upstream IdP.
+                When False, authorization proceeds directly without user confirmation.
+                SECURITY WARNING: Only disable for local development or testing environments.
         """
+
         # Always enable DCR since we implement it locally for MCP clients
         client_registration_options = ClientRegistrationOptions(
             enabled=True,
@@ -591,12 +634,14 @@ class OAuthProxy(OAuthProvider):
         )
 
         # Store upstream configuration
-        self._upstream_authorization_endpoint = upstream_authorization_endpoint
-        self._upstream_token_endpoint = upstream_token_endpoint
-        self._upstream_client_id = upstream_client_id
-        self._upstream_client_secret = SecretStr(upstream_client_secret)
-        self._upstream_revocation_endpoint = upstream_revocation_endpoint
-        self._default_scope_str = " ".join(self.required_scopes or [])
+        self._upstream_authorization_endpoint: str = upstream_authorization_endpoint
+        self._upstream_token_endpoint: str = upstream_token_endpoint
+        self._upstream_client_id: str = upstream_client_id
+        self._upstream_client_secret: SecretStr = SecretStr(
+            secret_value=upstream_client_secret
+        )
+        self._upstream_revocation_endpoint: str | None = upstream_revocation_endpoint
+        self._default_scope_str: str = " ".join(self.required_scopes or [])
 
         # Store redirect configuration
         if not redirect_path:
@@ -612,39 +657,85 @@ class OAuthProxy(OAuthProvider):
         ):
             logger.warning(
                 "allowed_client_redirect_uris is empty list; no redirect URIs will be accepted. "
-                "This will block all OAuth clients."
+                + "This will block all OAuth clients."
             )
-        self._allowed_client_redirect_uris = allowed_client_redirect_uris
+        self._allowed_client_redirect_uris: list[str] | None = (
+            allowed_client_redirect_uris
+        )
 
         # PKCE configuration
-        self._forward_pkce = forward_pkce
+        self._forward_pkce: bool = forward_pkce
 
         # Token endpoint authentication
-        self._token_endpoint_auth_method = token_endpoint_auth_method
+        self._token_endpoint_auth_method: str | None = token_endpoint_auth_method
+
+        # Consent screen configuration
+        self._require_authorization_consent: bool = require_authorization_consent
+        if not require_authorization_consent:
+            logger.warning(
+                "Authorization consent screen disabled - only use for local development or testing. "
+                + "In production, this screen protects against confused deputy attacks."
+            )
 
         # Extra parameters for authorization and token endpoints
-        self._extra_authorize_params = extra_authorize_params or {}
-        self._extra_token_params = extra_token_params or {}
+        self._extra_authorize_params: dict[str, str] = extra_authorize_params or {}
+        self._extra_token_params: dict[str, str] = extra_token_params or {}
 
-        self._client_storage: AsyncKeyValue = client_storage or MemoryStore()
+        if jwt_signing_key is None:
+            jwt_signing_key = derive_jwt_key(
+                high_entropy_material=upstream_client_secret,
+                salt="fastmcp-jwt-signing-key",
+            )
 
-        # Warn if using MemoryStore in production
-        if isinstance(client_storage, MemoryStore):
-            logger.warning(
-                "Using in-memory storage - all OAuth state (clients, tokens) will be lost on restart. "
-                "Additionally, without explicit jwt_signing_key and token_encryption_key, "
-                "keys are ephemeral and tokens won't survive restart even with persistent storage. "
-                "For production, configure persistent storage AND explicit keys."
+        if isinstance(jwt_signing_key, str):
+            if len(jwt_signing_key) < 12:
+                logger.warning(
+                    "jwt_signing_key is less than 12 characters; it is recommended to use a longer. "
+                    + "string for the key derivation."
+                )
+            jwt_signing_key = derive_jwt_key(
+                low_entropy_material=jwt_signing_key,
+                salt="fastmcp-jwt-signing-key",
             )
 
+        self._jwt_issuer: JWTIssuer = JWTIssuer(
+            issuer=str(self.base_url),
+            audience=f"{str(self.base_url).rstrip('/')}/mcp",
+            signing_key=jwt_signing_key,
+        )
+
+        # If the user does not provide a store, we will provide an encrypted disk store
+        if client_storage is None:
+            storage_encryption_key = derive_jwt_key(
+                high_entropy_material=jwt_signing_key.decode(),
+                salt="fastmcp-storage-encryption-key",
+            )
+            client_storage = FernetEncryptionWrapper(
+                key_value=DiskStore(directory=settings.home / "oauth-proxy"),
+                fernet=Fernet(key=storage_encryption_key),
+            )
+
+        self._client_storage: AsyncKeyValue = client_storage
+
         # Cache HTTPS check to avoid repeated logging
-        self._is_https = str(self.base_url).startswith("https://")
+        self._is_https: bool = str(self.base_url).startswith("https://")
         if not self._is_https:
             logger.warning(
                 "Using non-secure cookies for development; deploy with HTTPS for production."
             )
 
-        self._client_store = PydanticAdapter[ProxyDCRClient](
+        self._upstream_token_store: PydanticAdapter[UpstreamTokenSet] = PydanticAdapter[
+            UpstreamTokenSet
+        ](
+            key_value=self._client_storage,
+            pydantic_model=UpstreamTokenSet,
+            default_collection="mcp-upstream-tokens",
+            raise_on_validation_error=True,
+        )
+
+        self._client_store: PydanticAdapter[ProxyDCRClient] = PydanticAdapter[
+            ProxyDCRClient
+        ](
             key_value=self._client_storage,
             pydantic_model=ProxyDCRClient,
             default_collection="mcp-oauth-proxy-clients",
@@ -653,43 +744,32 @@ class OAuthProxy(OAuthProvider):
 
         # OAuth transaction storage for IdP callback forwarding
         # Reuse client_storage with different collections for state management
-        self._transaction_store = PydanticAdapter[OAuthTransaction](
+        self._transaction_store: PydanticAdapter[OAuthTransaction] = PydanticAdapter[
+            OAuthTransaction
+        ](
             key_value=self._client_storage,
             pydantic_model=OAuthTransaction,
             default_collection="mcp-oauth-transactions",
             raise_on_validation_error=True,
         )
 
-        self._code_store = PydanticAdapter[ClientCode](
+        self._code_store: PydanticAdapter[ClientCode] = PydanticAdapter[ClientCode](
             key_value=self._client_storage,
             pydantic_model=ClientCode,
             default_collection="mcp-authorization-codes",
             raise_on_validation_error=True,
         )
 
-        # Storage for upstream tokens (encrypted at rest)
-        self._upstream_token_store = PydanticAdapter[UpstreamTokenSet](
-            key_value=self._client_storage,
-            pydantic_model=UpstreamTokenSet,
-            default_collection="mcp-upstream-tokens",
-            raise_on_validation_error=True,
-        )
-
         # Storage for JTI mappings (FastMCP token -> upstream token)
-        self._jti_mapping_store = PydanticAdapter[JTIMapping](
+        self._jti_mapping_store: PydanticAdapter[JTIMapping] = PydanticAdapter[
+            JTIMapping
+        ](
             key_value=self._client_storage,
             pydantic_model=JTIMapping,
             default_collection="mcp-jti-mappings",
             raise_on_validation_error=True,
         )
 
-        # JWT issuer and encryption (initialized lazily on first use)
-        self._custom_jwt_key = jwt_signing_key
-        self._custom_encryption_key = token_encryption_key
-        self._jwt_issuer: JWTIssuer | None = None
-        self._token_encryption: TokenEncryption | None = None
-        self._jwt_initialized = False
-
         # Local state for token bookkeeping only (no client caching)
         self._access_tokens: dict[str, AccessToken] = {}
         self._refresh_tokens: dict[str, RefreshToken] = {}
@@ -699,7 +779,7 @@ class OAuthProxy(OAuthProvider):
         self._refresh_to_access: dict[str, str] = {}
 
         # Use the provided token validator
-        self._token_validator = token_verifier
+        self._token_validator: TokenVerifier = token_verifier
 
         logger.debug(
             "Initialized OAuth proxy provider with upstream server %s",
@@ -725,91 +805,11 @@ class OAuthProxy(OAuthProvider):
 
         return code_verifier, code_challenge
 
-    # -------------------------------------------------------------------------
-    # JWT Token Factory Initialization
-    # -------------------------------------------------------------------------
-
-    async def _ensure_jwt_initialized(self) -> None:
-        """Initialize JWT issuer and token encryption (lazy initialization).
-
-        Key derivation strategy:
-        - Default: Generate random salt at startup, derive ephemeral keys
-          → Keys change on restart, all tokens become invalid
-          → Perfect for development/testing where re-auth is acceptable
-
-        - Production: User provides explicit keys via parameters
-          → Keys stable across restarts when combined with persistent storage
-          → Tokens survive restart, seamless client reconnection
-        """
-        if self._jwt_initialized:
-            return
-
-        # Generate random salt for this server instance (NOT persisted)
-        server_salt = secrets.token_urlsafe(32)
-
-        # Derive or use custom JWT signing key
-        from fastmcp.server.auth.jwt_issuer import derive_key_from_secret
-
-        if self._custom_jwt_key:
-            jwt_key = derive_key_from_secret(
-                secret=self._custom_jwt_key,
-                salt="fastmcp-jwt-signing-v1",
-                info=b"HS256",
-            )
-            logger.info("Using explicit JWT signing key (will survive restarts)")
-        else:
-            # Ephemeral key from random salt + upstream secret
-            upstream_secret = self._upstream_client_secret.get_secret_value()
-            jwt_key = derive_key_from_secret(
-                secret=upstream_secret,
-                salt=f"fastmcp-jwt-signing-v1-{server_salt}",
-                info=b"HS256",
-            )
-            logger.info(
-                "Using ephemeral JWT signing key - tokens will NOT survive server restart. "
-                "For production, provide explicit jwt_signing_key parameter and use persistent storage."
-            )
-
-        # Initialize JWT issuer
-        issuer = str(self.base_url)
-        audience = f"{str(self.base_url).rstrip('/')}/mcp"
-        self._jwt_issuer = JWTIssuer(
-            issuer=issuer,
-            audience=audience,
-            signing_key=jwt_key,
-        )
-
-        # Derive or use custom encryption key
-        if self._custom_encryption_key:
-            encryption_key = derive_key_from_secret(
-                secret=self._custom_encryption_key,
-                salt="fastmcp-token-encryption-v1",
-                info=b"Fernet",
-            )
-            # Fernet needs base64url-encoded key
-            encryption_key = base64.urlsafe_b64encode(encryption_key)
-            logger.info("Using explicit token encryption key (will survive restarts)")
-        else:
-            # Ephemeral key from random salt + upstream secret
-            upstream_secret = self._upstream_client_secret.get_secret_value()
-            key_material = derive_key_from_secret(
-                secret=upstream_secret,
-                salt=f"fastmcp-token-encryption-v1-{server_salt}",
-                info=b"Fernet",
-            )
-            encryption_key = base64.urlsafe_b64encode(key_material)
-            logger.info(
-                "Using ephemeral token encryption key - encrypted tokens will NOT survive server restart. "
-                "For production, provide explicit token_encryption_key parameter and use persistent storage."
-            )
-
-        self._token_encryption = TokenEncryption(encryption_key)
-        self._jwt_initialized = True
-
     # -------------------------------------------------------------------------
     # Client Registration (Local Implementation)
     # -------------------------------------------------------------------------
 
+    @override
     async def get_client(self, client_id: str) -> OAuthClientInformationFull | None:
         """Get client information by ID. This is generally the random ID
         provided to the DCR client during registration, not the upstream client ID.
@@ -825,6 +825,7 @@ class OAuthProxy(OAuthProvider):
 
         return client
 
+    @override
     async def register_client(self, client_info: OAuthClientInformationFull) -> None:
         """Register a client locally
 
@@ -871,6 +872,7 @@ class OAuthProxy(OAuthProvider):
     # Authorization Flow (Proxy to Upstream)
     # -------------------------------------------------------------------------
 
+    @override
     async def authorize(
         self,
         client: OAuthClientInformationFull,
@@ -882,6 +884,9 @@ class OAuthProxy(OAuthProvider):
         1. Store transaction with client details and PKCE (if forwarding)
         2. Return local /consent URL; browser visits consent first
         3. Consent handler redirects to upstream IdP if approved/already approved
+
+        If consent is disabled (require_authorization_consent=False), skip the consent screen
+        and redirect directly to the upstream IdP.
         """
         # Generate transaction ID for this authorization request
         txn_id = secrets.token_urlsafe(32)
@@ -897,23 +902,37 @@ class OAuthProxy(OAuthProvider):
             )
 
         # Store transaction data for IdP callback processing
+        transaction = OAuthTransaction(
+            txn_id=txn_id,
+            client_id=client.client_id,
+            client_redirect_uri=str(params.redirect_uri),
+            client_state=params.state or "",
+            code_challenge=params.code_challenge,
+            code_challenge_method=getattr(params, "code_challenge_method", "S256"),
+            scopes=params.scopes or [],
+            created_at=time.time(),
+            resource=getattr(params, "resource", None),
+            proxy_code_verifier=proxy_code_verifier,
+        )
         await self._transaction_store.put(
             key=txn_id,
-            value=OAuthTransaction(
-                txn_id=txn_id,
-                client_id=client.client_id,
-                client_redirect_uri=str(params.redirect_uri),
-                client_state=params.state or "",
-                code_challenge=params.code_challenge,
-                code_challenge_method=getattr(params, "code_challenge_method", "S256"),
-                scopes=params.scopes or [],
-                created_at=time.time(),
-                resource=getattr(params, "resource", None),
-                proxy_code_verifier=proxy_code_verifier,
-            ),
+            value=transaction,
             ttl=15 * 60,  # Auto-expire after 15 minutes
         )
 
+        # If consent is disabled, skip consent screen and go directly to upstream IdP
+        if not self._require_authorization_consent:
+            upstream_url = self._build_upstream_authorize_url(
+                txn_id, transaction.model_dump()
+            )
+            logger.debug(
+                "Starting OAuth transaction %s for client %s, redirecting directly to upstream IdP (consent disabled, PKCE forwarding: %s)",
+                txn_id,
+                client.client_id,
+                "enabled" if proxy_code_challenge else "disabled",
+            )
+            return upstream_url
+
         consent_url = f"{str(self.base_url).rstrip('/')}/consent?txn_id={txn_id}"
 
         logger.debug(
@@ -928,6 +947,7 @@ class OAuthProxy(OAuthProvider):
     # Authorization Code Handling
     # -------------------------------------------------------------------------
 
+    @override
     async def load_authorization_code(
         self,
         client: OAuthClientInformationFull,
@@ -947,7 +967,7 @@ class OAuthProxy(OAuthProvider):
         # Check if code expired
         if time.time() > code_model.expires_at:
             logger.debug("Authorization code expired: %s", authorization_code)
-            await self._code_store.delete(key=authorization_code)
+            _ = await self._code_store.delete(key=authorization_code)
             return None
 
         # Verify client ID matches
@@ -963,13 +983,14 @@ class OAuthProxy(OAuthProvider):
         return AuthorizationCode(
             code=authorization_code,
             client_id=client.client_id,
-            redirect_uri=code_model.redirect_uri,
+            redirect_uri=AnyUrl(url=code_model.redirect_uri),
             redirect_uri_provided_explicitly=True,
             scopes=code_model.scopes,
             expires_at=code_model.expires_at,
             code_challenge=code_model.code_challenge or "",
         )
 
+    @override
     async def exchange_authorization_code(
         self,
         client: OAuthClientInformationFull,
@@ -986,11 +1007,6 @@ class OAuthProxy(OAuthProvider):
 
         PKCE validation is handled by the MCP framework before this method is called.
         """
-        # Ensure JWT issuer is initialized
-        await self._ensure_jwt_initialized()
-        assert self._jwt_issuer is not None
-        assert self._token_encryption is not None
-
         # Look up stored code data
         code_model = await self._code_store.get(key=authorization_code.code)
         if not code_model:
@@ -1041,8 +1057,8 @@ class OAuthProxy(OAuthProvider):
         # Encrypt and store upstream tokens
         upstream_token_set = UpstreamTokenSet(
             upstream_token_id=upstream_token_id,
-            access_token=self._token_encryption.encrypt(idp_tokens["access_token"]),
-            refresh_token=self._token_encryption.encrypt(idp_tokens["refresh_token"])
+            access_token=idp_tokens["access_token"],
+            refresh_token=idp_tokens["refresh_token"]
             if idp_tokens.get("refresh_token")
             else None,
             refresh_token_expires_at=refresh_token_expires_at,
@@ -1164,11 +1180,6 @@ class OAuthProxy(OAuthProvider):
         5. Issue new FastMCP access token
         6. Keep same FastMCP refresh token (unless upstream rotates)
         """
-        # Ensure JWT issuer is initialized
-        await self._ensure_jwt_initialized()
-        assert self._jwt_issuer is not None
-        assert self._token_encryption is not None
-
         # Verify FastMCP refresh token
         try:
             refresh_payload = self._jwt_issuer.verify_token(refresh_token.token)
@@ -1197,10 +1208,6 @@ class OAuthProxy(OAuthProvider):
             logger.error("No upstream refresh token available")
             raise TokenError("invalid_grant", "Refresh not supported for this token")
 
-        upstream_refresh_token = self._token_encryption.decrypt(
-            upstream_token_set.refresh_token
-        )
-
         # Refresh upstream token using authlib
         oauth_client = AsyncOAuth2Client(
             client_id=self._upstream_client_id,
@@ -1213,7 +1220,7 @@ class OAuthProxy(OAuthProvider):
             logger.debug("Refreshing upstream token (jti=%s)", refresh_jti[:8])
             token_response: dict[str, Any] = await oauth_client.refresh_token(  # type: ignore[misc]
                 url=self._upstream_token_endpoint,
-                refresh_token=upstream_refresh_token,
+                refresh_token=upstream_token_set.refresh_token,
                 scope=" ".join(scopes) if scopes else None,
             )
             logger.debug("Successfully refreshed upstream token")
@@ -1225,18 +1232,14 @@ class OAuthProxy(OAuthProvider):
         new_expires_in = int(
             token_response.get("expires_in", DEFAULT_ACCESS_TOKEN_EXPIRY_SECONDS)
         )
-        upstream_token_set.access_token = self._token_encryption.encrypt(
-            token_response["access_token"]
-        )
+        upstream_token_set.access_token = token_response["access_token"]
         upstream_token_set.expires_at = time.time() + new_expires_in
 
         # Handle upstream refresh token rotation and expiry
         new_refresh_expires_in = None
         if new_upstream_refresh := token_response.get("refresh_token"):
-            if new_upstream_refresh != upstream_refresh_token:
-                upstream_token_set.refresh_token = self._token_encryption.encrypt(
-                    new_upstream_refresh
-                )
+            if new_upstream_refresh != upstream_token_set.refresh_token:
+                upstream_token_set.refresh_token = new_upstream_refresh
                 logger.debug("Upstream refresh token rotated")
 
             # Update refresh token expiry if provided
@@ -1375,11 +1378,6 @@ class OAuthProxy(OAuthProvider):
         The FastMCP JWT is a reference token - all authorization data comes
         from validating the upstream token via the TokenVerifier.
         """
-        # Ensure JWT issuer and encryption are initialized
-        await self._ensure_jwt_initialized()
-        assert self._jwt_issuer is not None
-        assert self._token_encryption is not None
-
         try:
             # 1. Verify FastMCP JWT signature and claims
             payload = self._jwt_issuer.verify_token(token)
@@ -1400,15 +1398,12 @@ class OAuthProxy(OAuthProvider):
                 )
                 return None
 
-            # 3. Decrypt upstream token
-            upstream_token = self._token_encryption.decrypt(
+            # 3. Validate with upstream provider (delegated to TokenVerifier)
+            # This calls the real token validator (GitHub API, JWKS, etc.)
+            validated = await self._token_validator.verify_token(
                 upstream_token_set.access_token
             )
 
-            # 4. Validate with upstream provider (delegated to TokenVerifier)
-            # This calls the real token validator (GitHub API, JWKS, etc.)
-            validated = await self._token_validator.verify_token(upstream_token)
-
             if not validated:
                 logger.debug("Upstream token validation failed")
                 return None
@@ -1474,10 +1469,11 @@ class OAuthProxy(OAuthProvider):
         self,
         mcp_path: str | None = None,
     ) -> list[Route]:
-        """Get OAuth routes with custom proxy token handler.
+        """Get OAuth routes with custom handlers for better error UX.
 
-        This method creates standard OAuth routes and replaces the token endpoint
-        with our proxy handler that forwards requests to the upstream OAuth server.
+        This method creates standard OAuth routes and replaces:
+        - /authorize endpoint: Enhanced error responses for unregistered clients
+        - /token endpoint: OAuth 2.1 compliant error codes
 
         Args:
             mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")
@@ -1487,6 +1483,7 @@ class OAuthProxy(OAuthProvider):
         routes = super().get_routes(mcp_path)
         custom_routes = []
         token_route_found = False
+        authorize_route_found = False
 
         logger.debug(
             f"get_routes called - configuring OAuth routes in {len(routes)} routes"
@@ -1497,8 +1494,30 @@ class OAuthProxy(OAuthProvider):
                 f"Route {i}: {route} - path: {getattr(route, 'path', 'N/A')}, methods: {getattr(route, 'methods', 'N/A')}"
             )
 
-            # Replace the token endpoint with our custom handler that returns proper OAuth 2.1 error codes
+            # Replace the authorize endpoint with our enhanced handler for better error UX
             if (
+                isinstance(route, Route)
+                and route.path == "/authorize"
+                and route.methods is not None
+                and ("GET" in route.methods or "POST" in route.methods)
+            ):
+                authorize_route_found = True
+                # Replace with our enhanced authorization handler
+                authorize_handler = AuthorizationHandler(
+                    provider=self,
+                    base_url=self.base_url,
+                    server_name=None,  # Could be extended to pass server metadata
+                    server_icon_url=None,
+                )
+                custom_routes.append(
+                    Route(
+                        path="/authorize",
+                        endpoint=authorize_handler.handle,
+                        methods=["GET", "POST"],
+                    )
+                )
+            # Replace the token endpoint with our custom handler that returns proper OAuth 2.1 error codes
+            elif (
                 isinstance(route, Route)
                 and route.path == "/token"
                 and route.methods is not None
@@ -1542,7 +1561,7 @@ class OAuthProxy(OAuthProvider):
         )
 
         logger.debug(
-            f"✅ OAuth routes configured: token_endpoint={token_route_found}, total routes={len(custom_routes)} (includes OAuth callback + consent)"
+            f"✅ OAuth routes configured: authorize_endpoint={authorize_route_found}, token_endpoint={token_route_found}, total routes={len(custom_routes)} (includes OAuth callback + consent)"
         )
         return custom_routes