fastmcp 2.13.0.2__py3-none-any.whl → 2.13.1__py3-none-any.whl

fastmcp/server/auth/handlers/authorize.py

@@ -13,6 +13,7 @@ The enhancement adds:
 
 from __future__ import annotations
 
+import json
 from typing import TYPE_CHECKING
 
 from mcp.server.auth.handlers.authorize import (
@@ -211,12 +212,15 @@ class AuthorizationHandler(SDKAuthorizationHandler):
         # Check if this is a client not found error
         if response.status_code == 400:
             # Try to extract client_id from request for enhanced error
-            client_id = None
+            client_id: str | None = None
             if request.method == "GET":
                 client_id = request.query_params.get("client_id")
             else:
                 form = await request.form()
-                client_id = form.get("client_id")
+                client_id_value = form.get("client_id")
+                # Ensure client_id is a string, not UploadFile
+                if isinstance(client_id_value, str):
+                    client_id = client_id_value
 
             # If we have a client_id and the error is about it not being found,
             # enhance the response
@@ -224,9 +228,7 @@ class AuthorizationHandler(SDKAuthorizationHandler):
                 try:
                     # Check if response body contains "not found" error
                     if hasattr(response, "body"):
-                        import json
-
-                        body = json.loads(response.body)
+                        body = json.loads(bytes(response.body))
                         if (
                             body.get("error") == "invalid_request"
                             and "not found" in body.get("error_description", "").lower()

fastmcp/server/auth/oauth_proxy.py

@@ -44,6 +44,7 @@ from mcp.server.auth.provider import (
     AccessToken,
     AuthorizationCode,
     AuthorizationParams,
+    AuthorizeError,
     RefreshToken,
     TokenError,
 )
@@ -309,10 +310,13 @@ def create_consent_html(
     """
 
     # Build form with buttons
+    # Use empty action to submit to current URL (/consent or /mcp/consent)
+    # The POST handler is registered at the same path as GET
     form = f"""
-        <form id="consentForm" method="POST" action="/consent/submit">
+        <form id="consentForm" method="POST" action="">
             <input type="hidden" name="txn_id" value="{txn_id}" />
             <input type="hidden" name="csrf_token" value="{csrf_token}" />
+            <input type="hidden" name="submit" value="true" />
             <div class="button-group">
                 <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>
@@ -365,7 +369,19 @@ def create_consent_html(
     )
 
     # Need to allow form-action for form submission
-    csp_policy = "default-src 'none'; style-src 'unsafe-inline'; img-src https:; base-uri 'none'; form-action *"
+    # Chrome requires explicit scheme declarations in CSP form-action when redirect chains
+    # end in custom protocol schemes (e.g., cursor://). Parse redirect_uri to include its scheme.
+    parsed_redirect = urlparse(redirect_uri)
+    redirect_scheme = parsed_redirect.scheme.lower()
+
+    # Build form-action directive with standard schemes plus custom protocol if present
+    form_action_schemes = ["https:", "http:"]
+    if redirect_scheme and redirect_scheme not in ("http", "https"):
+        # Custom protocol scheme (e.g., cursor:, vscode:, etc.)
+        form_action_schemes.append(f"{redirect_scheme}:")
+
+    form_action_directive = " ".join(form_action_schemes)
+    csp_policy = f"default-src 'none'; style-src 'unsafe-inline'; img-src https: data:; base-uri 'none'; form-action {form_action_directive}"
 
     return create_page(
         content=content,
@@ -375,6 +391,94 @@ def create_consent_html(
     )
 
 
+def create_error_html(
+    error_title: str,
+    error_message: str,
+    error_details: dict[str, str] | None = None,
+    server_name: str | None = None,
+    server_icon_url: str | None = None,
+) -> str:
+    """Create a styled HTML error page for OAuth errors.
+
+    Args:
+        error_title: The error title (e.g., "OAuth Error", "Authorization Failed")
+        error_message: The main error message to display
+        error_details: Optional dictionary of error details to show (e.g., {"Error Code": "invalid_client"})
+        server_name: Optional server name to display
+        server_icon_url: Optional URL to server icon/logo
+
+    Returns:
+        Complete HTML page as a string
+    """
+    import html as html_module
+
+    error_message_escaped = html_module.escape(error_message)
+
+    # Build error message box
+    error_box = f"""
+        <div class="info-box error">
+            <p>{error_message_escaped}</p>
+        </div>
+    """
+
+    # Build error details section if provided
+    details_section = ""
+    if error_details:
+        detail_rows_html = "\n".join(
+            [
+                f"""
+            <div class="detail-row">
+                <div class="detail-label">{html_module.escape(label)}:</div>
+                <div class="detail-value">{html_module.escape(value)}</div>
+            </div>
+            """
+                for label, value in error_details.items()
+            ]
+        )
+
+        details_section = f"""
+            <details>
+                <summary>Error Details</summary>
+                <div class="detail-box">
+                    {detail_rows_html}
+                </div>
+            </details>
+        """
+
+    # Build the page content
+    content = f"""
+        <div class="container">
+            {create_logo(icon_url=server_icon_url, alt_text=server_name or "FastMCP")}
+            <h1>{html_module.escape(error_title)}</h1>
+            {error_box}
+            {details_section}
+        </div>
+    """
+
+    # Additional styles needed for this page
+    # Override .info-box.error to use normal text color instead of red
+    additional_styles = (
+        INFO_BOX_STYLES
+        + DETAILS_STYLES
+        + DETAIL_BOX_STYLES
+        + """
+        .info-box.error {
+            color: #111827;
+        }
+        """
+    )
+
+    # Simple CSP policy for error pages (no forms needed)
+    csp_policy = "default-src 'none'; style-src 'unsafe-inline'; img-src https: data:; base-uri 'none'"
+
+    return create_page(
+        content=content,
+        title=error_title,
+        additional_styles=additional_styles,
+        csp_policy=csp_policy,
+    )
+
+
 # -------------------------------------------------------------------------
 # Handler Classes
 # -------------------------------------------------------------------------
@@ -836,6 +940,8 @@ class OAuthProxy(OAuthProvider):
         """
 
         # Create a ProxyDCRClient with configured redirect URI validation
+        if client_info.client_id is None:
+            raise ValueError("client_id is required for client registration")
         proxy_client: ProxyDCRClient = ProxyDCRClient(
             client_id=client_info.client_id,
             client_secret=client_info.client_secret,
@@ -865,7 +971,7 @@ class OAuthProxy(OAuthProvider):
         logger.debug(
             "Registered client %s with %d redirect URIs",
             client_info.client_id,
-            len(proxy_client.redirect_uris),
+            len(proxy_client.redirect_uris) if proxy_client.redirect_uris else 0,
         )
 
     # -------------------------------------------------------------------------
@@ -902,6 +1008,10 @@ class OAuthProxy(OAuthProvider):
             )
 
         # Store transaction data for IdP callback processing
+        if client.client_id is None:
+            raise AuthorizeError(
+                error="invalid_client", error_description="Client ID is required"
+            )
         transaction = OAuthTransaction(
             txn_id=txn_id,
             client_id=client.client_id,
@@ -980,6 +1090,10 @@ class OAuthProxy(OAuthProvider):
             return None
 
         # Create authorization code object with PKCE challenge
+        if client.client_id is None:
+            raise AuthorizeError(
+                error="invalid_client", error_description="Client ID is required"
+            )
         return AuthorizationCode(
             code=authorization_code,
             client_id=client.client_id,
@@ -1065,18 +1179,21 @@ class OAuthProxy(OAuthProvider):
             expires_at=time.time() + expires_in,
             token_type=idp_tokens.get("token_type", "Bearer"),
             scope=" ".join(authorization_code.scopes),
-            client_id=client.client_id,
+            client_id=client.client_id or "",
             created_at=time.time(),
             raw_token_data=idp_tokens,
         )
         await self._upstream_token_store.put(
             key=upstream_token_id,
             value=upstream_token_set,
-            ttl=expires_in,  # Auto-expire when access token expires
+            ttl=refresh_expires_in
+            or expires_in,  # Auto-expire when refresh token, or access token expires
         )
         logger.debug("Stored encrypted upstream tokens (jti=%s)", access_jti[:8])
 
         # Issue minimal FastMCP access token (just a reference via JTI)
+        if client.client_id is None:
+            raise TokenError("invalid_client", "Client ID is required")
         fastmcp_access_token = self._jwt_issuer.issue_access_token(
             client_id=client.client_id,
             scopes=authorization_code.scopes,
@@ -1222,6 +1339,7 @@ class OAuthProxy(OAuthProvider):
                 url=self._upstream_token_endpoint,
                 refresh_token=upstream_token_set.refresh_token,
                 scope=" ".join(scopes) if scopes else None,
+                **self._extra_token_params,
             )
             logger.debug("Successfully refreshed upstream token")
         except Exception as e:
@@ -1268,10 +1386,17 @@ class OAuthProxy(OAuthProvider):
         await self._upstream_token_store.put(
             key=upstream_token_set.upstream_token_id,
             value=upstream_token_set,
-            ttl=new_expires_in,  # Auto-expire when refreshed access token expires
+            ttl=new_refresh_expires_in
+            or (
+                int(upstream_token_set.refresh_token_expires_at - time.time())
+                if upstream_token_set.refresh_token_expires_at
+                else 60 * 60 * 24 * 30  # Default to 30 days if unknown
+            ),  # Auto-expire when refresh token expires
         )
 
         # Issue new minimal FastMCP access token (just a reference via JTI)
+        if client.client_id is None:
+            raise TokenError("invalid_client", "Client ID is required")
         new_access_jti = secrets.token_urlsafe(32)
         new_fastmcp_access = self._jwt_issuer.issue_access_token(
             client_id=client.client_id,
@@ -1503,9 +1628,10 @@ class OAuthProxy(OAuthProvider):
             ):
                 authorize_route_found = True
                 # Replace with our enhanced authorization handler
+                # Note: self.base_url is guaranteed to be set in parent __init__
                 authorize_handler = AuthorizationHandler(
                     provider=self,
-                    base_url=self.base_url,
+                    base_url=self.base_url,  # ty: ignore[invalid-argument-type]
                     server_name=None,  # Could be extended to pass server metadata
                     server_icon_url=None,
                 )
@@ -1551,12 +1677,10 @@ class OAuthProxy(OAuthProvider):
         )
 
         # Add consent endpoints
-        custom_routes.append(
-            Route(path="/consent", endpoint=self._show_consent_page, methods=["GET"])
-        )
+        # Handle both GET (show page) and POST (submit) at /consent
         custom_routes.append(
             Route(
-                path="/consent/submit", endpoint=self._submit_consent, methods=["POST"]
+                path="/consent", endpoint=self._handle_consent, methods=["GET", "POST"]
             )
         )
 
@@ -1569,7 +1693,9 @@ class OAuthProxy(OAuthProvider):
     # IdP Callback Forwarding
     # -------------------------------------------------------------------------
 
-    async def _handle_idp_callback(self, request: Request) -> RedirectResponse:
+    async def _handle_idp_callback(
+        self, request: Request
+    ) -> HTMLResponse | RedirectResponse:
         """Handle callback from upstream IdP and forward to client.
 
         This implements the DCR-compliant callback forwarding:
@@ -1584,32 +1710,37 @@ class OAuthProxy(OAuthProvider):
             error = request.query_params.get("error")
 
             if error:
+                error_description = request.query_params.get("error_description")
                 logger.error(
                     "IdP callback error: %s - %s",
                     error,
-                    request.query_params.get("error_description"),
+                    error_description,
                 )
-                # TODO: Forward error to client callback
-                return RedirectResponse(
-                    url=f"data:text/html,<h1>OAuth Error</h1><p>{error}: {request.query_params.get('error_description', 'Unknown error')}</p>",
-                    status_code=302,
+                # Show error page to user
+                html_content = create_error_html(
+                    error_title="OAuth Error",
+                    error_message=f"Authentication failed: {error_description or 'Unknown error'}",
+                    error_details={"Error Code": error} if error else None,
                 )
+                return HTMLResponse(content=html_content, status_code=400)
 
             if not idp_code or not txn_id:
                 logger.error("IdP callback missing code or transaction ID")
-                return RedirectResponse(
-                    url="data:text/html,<h1>OAuth Error</h1><p>Missing authorization code or transaction ID</p>",
-                    status_code=302,
+                html_content = create_error_html(
+                    error_title="OAuth Error",
+                    error_message="Missing authorization code or transaction ID from the identity provider.",
                 )
+                return HTMLResponse(content=html_content, status_code=400)
 
             # Look up transaction data
             transaction_model = await self._transaction_store.get(key=txn_id)
             if not transaction_model:
                 logger.error("IdP callback with invalid transaction ID: %s", txn_id)
-                return RedirectResponse(
-                    url="data:text/html,<h1>OAuth Error</h1><p>Invalid or expired transaction</p>",
-                    status_code=302,
+                html_content = create_error_html(
+                    error_title="OAuth Error",
+                    error_message="Invalid or expired authorization transaction. Please try authenticating again.",
                 )
+                return HTMLResponse(content=html_content, status_code=400)
             transaction = transaction_model.model_dump()
 
             # Exchange IdP code for tokens (server-side)
@@ -1663,11 +1794,11 @@ class OAuthProxy(OAuthProvider):
 
             except Exception as e:
                 logger.error("IdP token exchange failed: %s", e)
-                # TODO: Forward error to client callback
-                return RedirectResponse(
-                    url=f"data:text/html,<h1>OAuth Error</h1><p>Token exchange failed: {e}</p>",
-                    status_code=302,
+                html_content = create_error_html(
+                    error_title="OAuth Error",
+                    error_message=f"Token exchange with identity provider failed: {e}",
                 )
+                return HTMLResponse(content=html_content, status_code=500)
 
             # Generate our own authorization code for the client
             client_code = secrets.token_urlsafe(32)
@@ -1714,10 +1845,11 @@ class OAuthProxy(OAuthProvider):
 
         except Exception as e:
             logger.error("Error in IdP callback handler: %s", e, exc_info=True)
-            return RedirectResponse(
-                url="data:text/html,<h1>OAuth Error</h1><p>Internal server error during IdP callback</p>",
-                status_code=302,
+            html_content = create_error_html(
+                error_title="OAuth Error",
+                error_message="Internal server error during OAuth callback processing. Please try again.",
             )
+            return HTMLResponse(content=html_content, status_code=500)
 
     # -------------------------------------------------------------------------
     # Consent Interstitial
@@ -1863,6 +1995,14 @@ class OAuthProxy(OAuthProvider):
         separator = "&" if "?" in self._upstream_authorization_endpoint else "?"
         return f"{self._upstream_authorization_endpoint}{separator}{urlencode(query_params)}"
 
+    async def _handle_consent(
+        self, request: Request
+    ) -> HTMLResponse | RedirectResponse:
+        """Handle consent page - dispatch to GET or POST handler based on method."""
+        if request.method == "POST":
+            return await self._submit_consent(request)
+        return await self._show_consent_page(request)
+
     async def _show_consent_page(
         self, request: Request
     ) -> HTMLResponse | RedirectResponse:

fastmcp/server/auth/oidc_proxy.py

@@ -206,6 +206,7 @@ class OIDCProxy(OAuthProxy):
         audience: str | None = None,
         timeout_seconds: int | None = None,
         # Token verifier
+        token_verifier: TokenVerifier | None = None,
         algorithm: str | None = None,
         required_scopes: list[str] | None = None,
         # FastMCP server configuration
@@ -231,8 +232,11 @@ class OIDCProxy(OAuthProxy):
             client_secret: Client secret for upstream server
             audience: Audience for upstream server
             timeout_seconds: HTTP request timeout in seconds
-            algorithm: Token verifier algorithm
-            required_scopes: Required OAuth scopes
+            token_verifier: Optional custom token verifier (e.g., IntrospectionTokenVerifier for opaque tokens).
+                If not provided, a JWTVerifier will be created using the OIDC configuration.
+                Cannot be used with algorithm or required_scopes parameters (configure these on your verifier instead).
+            algorithm: Token verifier algorithm (only used if token_verifier is not provided)
+            required_scopes: Required scopes for token validation (only used if token_verifier is not provided)
             base_url: Public URL where OAuth endpoints will be accessible (includes any mount path)
             issuer_url: Issuer URL for OAuth metadata (defaults to base_url). Use root-level URL
                 to avoid 404s during discovery when mounting under a path.
@@ -268,6 +272,19 @@ class OIDCProxy(OAuthProxy):
         if not base_url:
             raise ValueError("Missing required base URL")
 
+        # Validate that verifier-specific parameters are not used with custom verifier
+        if token_verifier is not None:
+            if algorithm is not None:
+                raise ValueError(
+                    "Cannot specify 'algorithm' when providing a custom token_verifier. "
+                    "Configure the algorithm on your token verifier instead."
+                )
+            if required_scopes is not None:
+                raise ValueError(
+                    "Cannot specify 'required_scopes' when providing a custom token_verifier. "
+                    "Configure required scopes on your token verifier instead."
+                )
+
         if isinstance(config_url, str):
             config_url = AnyHttpUrl(config_url)
 
@@ -287,12 +304,14 @@ class OIDCProxy(OAuthProxy):
             else None
         )
 
-        token_verifier = self.get_token_verifier(
-            algorithm=algorithm,
-            audience=audience,
-            required_scopes=required_scopes,
-            timeout_seconds=timeout_seconds,
-        )
+        # Use custom verifier if provided, otherwise create default JWTVerifier
+        if token_verifier is None:
+            token_verifier = self.get_token_verifier(
+                algorithm=algorithm,
+                audience=audience,
+                required_scopes=required_scopes,
+                timeout_seconds=timeout_seconds,
+            )
 
         init_kwargs = {
             "upstream_authorization_endpoint": str(
@@ -321,7 +340,7 @@ class OIDCProxy(OAuthProxy):
             init_kwargs["extra_authorize_params"] = extra_params
             init_kwargs["extra_token_params"] = extra_params
 
-        super().__init__(**init_kwargs)
+        super().__init__(**init_kwargs)  # ty: ignore[invalid-argument-type]
 
     def get_oidc_configuration(
         self,

fastmcp/server/auth/providers/azure.py

@@ -46,6 +46,7 @@ class AzureProviderSettings(BaseSettings):
     additional_authorize_scopes: list[str] | None = None
     allowed_client_redirect_uris: list[str] | None = None
     jwt_signing_key: str | None = None
+    base_authority: str = "login.microsoftonline.com"
 
     @field_validator("required_scopes", mode="before")
     @classmethod
@@ -93,6 +94,7 @@ class AzureProvider(OAuthProxy):
         from fastmcp import FastMCP
         from fastmcp.server.auth.providers.azure import AzureProvider
 
+        # Standard Azure (Public Cloud)
         auth = AzureProvider(
             client_id="your-client-id",
             client_secret="your-client-secret",
@@ -103,6 +105,16 @@ class AzureProvider(OAuthProxy):
             # identifier_uri defaults to api://{client_id}
         )
 
+        # Azure Government
+        auth_gov = AzureProvider(
+            client_id="your-client-id",
+            client_secret="your-client-secret",
+            tenant_id="your-tenant-id",
+            required_scopes=["read", "write"],
+            base_authority="login.microsoftonline.us",  # Override for Azure Gov
+            base_url="http://localhost:8000",
+        )
+
         mcp = FastMCP("My App", auth=auth)
         ```
     """
@@ -123,6 +135,7 @@ class AzureProvider(OAuthProxy):
         client_storage: AsyncKeyValue | None = None,
         jwt_signing_key: str | bytes | NotSetT = NotSet,
         require_authorization_consent: bool = True,
+        base_authority: str | NotSetT = NotSet,
     ) -> None:
         """Initialize Azure OAuth provider.
 
@@ -138,6 +151,8 @@ class AzureProvider(OAuthProxy):
             issuer_url: Issuer URL for OAuth metadata (defaults to base_url). Use root-level URL
                 to avoid 404s during discovery when mounting under a path.
             redirect_path: Redirect path configured in Azure App registration (defaults to "/auth/callback")
+            base_authority: Azure authority base URL (defaults to "login.microsoftonline.com").
+                For Azure Government, use "login.microsoftonline.us".
             required_scopes: Custom API scope names WITHOUT prefix (e.g., ["read", "write"]).
                 - Automatically prefixed with identifier_uri during initialization
                 - Validated on all tokens
@@ -180,6 +195,7 @@ class AzureProvider(OAuthProxy):
                     "additional_authorize_scopes": additional_authorize_scopes,
                     "allowed_client_redirect_uris": allowed_client_redirect_uris,
                     "jwt_signing_key": jwt_signing_key,
+                    "base_authority": base_authority,
                 }.items()
                 if v is not NotSet
             }
@@ -218,9 +234,10 @@ class AzureProvider(OAuthProxy):
         tenant_id_final = settings.tenant_id
 
         # Always validate tokens against the app's API client ID using JWT
-        issuer = f"https://login.microsoftonline.com/{tenant_id_final}/v2.0"
+        base_authority_final = settings.base_authority
+        issuer = f"https://{base_authority_final}/{tenant_id_final}/v2.0"
         jwks_uri = (
-            f"https://login.microsoftonline.com/{tenant_id_final}/discovery/v2.0/keys"
+            f"https://{base_authority_final}/{tenant_id_final}/discovery/v2.0/keys"
         )
 
         # Azure returns unprefixed scopes in JWT tokens, so validate against unprefixed scopes
@@ -239,10 +256,10 @@ class AzureProvider(OAuthProxy):
 
         # Build Azure OAuth endpoints with tenant
         authorization_endpoint = (
-            f"https://login.microsoftonline.com/{tenant_id_final}/oauth2/v2.0/authorize"
+            f"https://{base_authority_final}/{tenant_id_final}/oauth2/v2.0/authorize"
         )
         token_endpoint = (
-            f"https://login.microsoftonline.com/{tenant_id_final}/oauth2/v2.0/token"
+            f"https://{base_authority_final}/{tenant_id_final}/oauth2/v2.0/token"
         )
 
         # Initialize OAuth proxy with Azure endpoints
@@ -262,11 +279,15 @@ class AzureProvider(OAuthProxy):
             require_authorization_consent=require_authorization_consent,
         )
 
+        authority_info = ""
+        if base_authority_final != "login.microsoftonline.com":
+            authority_info = f" using authority {base_authority_final}"
         logger.info(
-            "Initialized Azure OAuth provider for client %s with tenant %s%s",
+            "Initialized Azure OAuth provider for client %s with tenant %s%s%s",
             settings.client_id,
             tenant_id_final,
             f" and identifier_uri {self.identifier_uri}" if self.identifier_uri else "",
+            authority_info,
         )
 
     async def authorize(

fastmcp/server/auth/providers/debug.py

@@ -0,0 +1,114 @@
+"""Debug token verifier for testing and special cases.
+
+This module provides a flexible token verifier that delegates validation
+to a custom callable. Useful for testing, development, or scenarios where
+standard verification isn't possible (like opaque tokens without introspection).
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.auth.providers.debug import DebugTokenVerifier
+
+    # Accept all tokens (default - useful for testing)
+    auth = DebugTokenVerifier()
+
+    # Custom sync validation logic
+    auth = DebugTokenVerifier(validate=lambda token: token.startswith("valid-"))
+
+    # Custom async validation logic
+    async def check_cache(token: str) -> bool:
+        return await redis.exists(f"token:{token}")
+
+    auth = DebugTokenVerifier(validate=check_cache)
+
+    mcp = FastMCP("My Server", auth=auth)
+    ```
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable
+
+from fastmcp.server.auth import TokenVerifier
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class DebugTokenVerifier(TokenVerifier):
+    """Token verifier with custom validation logic.
+
+    This verifier delegates token validation to a user-provided callable.
+    By default, it accepts all non-empty tokens (useful for testing).
+
+    Use cases:
+    - Testing: Accept any token without real verification
+    - Development: Custom validation logic for prototyping
+    - Opaque tokens: When you have tokens with no introspection endpoint
+
+    WARNING: This bypasses standard security checks. Only use in controlled
+    environments or when you understand the security implications.
+    """
+
+    def __init__(
+        self,
+        validate: Callable[[str], bool]
+        | Callable[[str], Awaitable[bool]] = lambda token: True,
+        client_id: str = "debug-client",
+        scopes: list[str] | None = None,
+        required_scopes: list[str] | None = None,
+    ):
+        """Initialize the debug token verifier.
+
+        Args:
+            validate: Callable that takes a token string and returns True if valid.
+                Can be sync or async. Default accepts all tokens.
+            client_id: Client ID to assign to validated tokens
+            scopes: Scopes to assign to validated tokens
+            required_scopes: Required scopes (inherited from TokenVerifier base class)
+        """
+        super().__init__(required_scopes=required_scopes)
+        self.validate = validate
+        self.client_id = client_id
+        self.scopes = scopes or []
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify token using custom validation logic.
+
+        Args:
+            token: The token string to validate
+
+        Returns:
+            AccessToken if validation succeeds, None otherwise
+        """
+        # Reject empty tokens
+        if not token or not token.strip():
+            logger.debug("Rejecting empty token")
+            return None
+
+        try:
+            # Call validation function and await if result is awaitable
+            result = self.validate(token)
+            if inspect.isawaitable(result):
+                is_valid = await result
+            else:
+                is_valid = result
+
+            if not is_valid:
+                logger.debug("Token validation failed: callable returned False")
+                return None
+
+            # Return valid AccessToken
+            return AccessToken(
+                token=token,
+                client_id=self.client_id,
+                scopes=self.scopes,
+                expires_at=None,  # No expiration
+                claims={"token": token},  # Store original token in claims
+            )
+
+        except Exception as e:
+            logger.debug("Token validation error: %s", e, exc_info=True)
+            return None