authplane-fastmcp 0.1.0__tar.gz

authplane_fastmcp-0.1.0/.gitignore

@@ -0,0 +1,79 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.venv/
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Virtual environments
+venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Python version file
+.python-version

authplane_fastmcp-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: authplane-fastmcp
+Version: 0.1.0
+Summary: Authplane JWT validation adapter for FastMCP
+Project-URL: Homepage, https://github.com/AuthPlane/python-sdk/tree/main/authplane-fastmcp
+Project-URL: Issues, https://github.com/AuthPlane/python-sdk/issues
+Author: Authplane Team
+License-Expression: Apache-2.0
+Keywords: adapter,authplane,fastmcp,jwt,oauth
+Requires-Python: >=3.11
+Requires-Dist: authplane-sdk==0.1.0
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: coverage>=7; extra == 'dev'
+Requires-Dist: cryptography>=42; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# authplane-fastmcp
+
+[![PyPI](https://img.shields.io/pypi/v/authplane-fastmcp?style=flat-square&label=authplane-fastmcp)](https://pypi.org/project/authplane-fastmcp/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square)](https://opensource.org/licenses/Apache-2.0)
+
+Authplane JWT validation for servers built on [FastMCP](https://github.com/PrefectHQ/fastmcp).
+
+## Install
+
+```bash
+pip install authplane-fastmcp
+```
+
+## Quickstart
+
+```python
+import asyncio
+from authplane_fastmcp import authplane_auth
+from fastmcp import FastMCP
+from fastmcp.server.auth import AccessToken, require_scopes
+from fastmcp.dependencies import CurrentAccessToken
+
+
+async def main():
+    mcp = FastMCP(
+        "My MCP Server",
+        **await authplane_auth(
+            issuer="https://auth.company.com",
+            base_url="https://mcp.company.com",
+            scopes=["tools/query", "tools/write"],
+        ),
+    )
+
+    @mcp.tool(auth=require_scopes("tools/query"))
+    async def query_database(
+        query: str, token: AccessToken = CurrentAccessToken()
+    ) -> str:
+        user_id = token.claims.get("sub")
+        return f"Query: {query}, User: {user_id}"
+
+    await mcp.run_async(transport="http", host="0.0.0.0", port=8080)
+
+
+asyncio.run(main())
+```
+
+`authplane_auth()` holds background JWKS and metadata refresh tasks; call `aclose()` on the returned `client` during server shutdown.
+
+## Documentation
+
+PRM behavior, dev mode, revocation checking, manual setup, scope enforcement semantics, claim access, the full `authplane_auth` / `AuthplaneTokenVerifier` API, and error handling: **[User Guide](docs/user-guide.md)**.

authplane_fastmcp-0.1.0/README.md

@@ -0,0 +1,51 @@
+# authplane-fastmcp
+
+[![PyPI](https://img.shields.io/pypi/v/authplane-fastmcp?style=flat-square&label=authplane-fastmcp)](https://pypi.org/project/authplane-fastmcp/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square)](https://opensource.org/licenses/Apache-2.0)
+
+Authplane JWT validation for servers built on [FastMCP](https://github.com/PrefectHQ/fastmcp).
+
+## Install
+
+```bash
+pip install authplane-fastmcp
+```
+
+## Quickstart
+
+```python
+import asyncio
+from authplane_fastmcp import authplane_auth
+from fastmcp import FastMCP
+from fastmcp.server.auth import AccessToken, require_scopes
+from fastmcp.dependencies import CurrentAccessToken
+
+
+async def main():
+    mcp = FastMCP(
+        "My MCP Server",
+        **await authplane_auth(
+            issuer="https://auth.company.com",
+            base_url="https://mcp.company.com",
+            scopes=["tools/query", "tools/write"],
+        ),
+    )
+
+    @mcp.tool(auth=require_scopes("tools/query"))
+    async def query_database(
+        query: str, token: AccessToken = CurrentAccessToken()
+    ) -> str:
+        user_id = token.claims.get("sub")
+        return f"Query: {query}, User: {user_id}"
+
+    await mcp.run_async(transport="http", host="0.0.0.0", port=8080)
+
+
+asyncio.run(main())
+```
+
+`authplane_auth()` holds background JWKS and metadata refresh tasks; call `aclose()` on the returned `client` during server shutdown.
+
+## Documentation
+
+PRM behavior, dev mode, revocation checking, manual setup, scope enforcement semantics, claim access, the full `authplane_auth` / `AuthplaneTokenVerifier` API, and error handling: **[User Guide](docs/user-guide.md)**.

authplane_fastmcp-0.1.0/authplane_fastmcp/__init__.py

@@ -0,0 +1,23 @@
+"""Authplane Python SDK - FastMCP adapter.
+
+This package provides a thin adapter between the Authplane Python SDK and FastMCP,
+enabling FastMCP servers to validate Authplane-issued JWT access tokens.
+
+Core SDK types (``ASCredentials``, ``FetchSettings``, ``IntrospectionRevocation``,
+DPoP types, errors, etc.) are imported from ``authplane`` directly. This package
+exports only the adapter-owned glue.
+"""
+
+__version__ = "0.1.0"
+
+from .auth import AuthplaneAuthResult, authplane_auth
+from .url_elicitation import to_url_elicitation_required_error
+from .verifier import AuthplaneTokenVerifier
+
+__all__ = [
+    "AuthplaneAuthResult",
+    "AuthplaneTokenVerifier",
+    "__version__",
+    "authplane_auth",
+    "to_url_elicitation_required_error",
+]

authplane_fastmcp-0.1.0/authplane_fastmcp/auth.py

@@ -0,0 +1,283 @@
+"""Convenience factory for enabling Authplane auth on FastMCP servers.
+
+Provides ``authplane_auth()``, an async factory function that creates and
+configures all the components needed to add Authplane JWT validation to a
+FastMCP server in a single call.
+"""
+
+from collections.abc import Iterator
+from typing import Any
+
+from authplane import (
+    ASCredentials,
+    AuthplaneClient,
+    DPoPProvider,
+    FetchSettings,
+    InboundDPoPOptions,
+    IntrospectionRevocation,
+    RevocationChecker,
+)
+from authplane.oauth import TokenExchangeOptions, TokenResponse
+from fastmcp.server.auth import RemoteAuthProvider
+from pydantic import AnyHttpUrl
+
+from .url_elicitation import to_url_elicitation_required_error
+from .verifier import AuthplaneTokenVerifier
+
+
+def _wrap_client_for_elicitation(client: AuthplaneClient) -> AuthplaneClient:
+    """Translate ``client.exchange`` consent errors into MCP ``-32042``.
+
+    Wrapping ``exchange()`` (the only method that realistically surfaces
+    ``ConsentRequiredError`` from the AS) means user tool code can call
+    ``result.client.exchange(...)`` without any try/except: a consent error
+    becomes a ``UrlElicitationRequiredError`` transparently, and FastMCP
+    forwards it as a ``-32042`` JSON-RPC error.
+    """
+    original_exchange = client.exchange
+
+    async def exchange(options: TokenExchangeOptions) -> TokenResponse:
+        try:
+            return await original_exchange(options)
+        except Exception as error:
+            mapped = to_url_elicitation_required_error(error)
+            if mapped is not None:
+                raise mapped from error
+            raise
+
+    client.exchange = exchange
+    return client
+
+
+class AuthplaneAuthResult:
+    """Return value of ``authplane_auth()``.
+
+    Supports ``**`` unpacking into ``FastMCP()`` — only the ``auth`` key
+    is included in the mapping view so FastMCP receives exactly what it
+    expects. ``token_verifier`` and ``client`` are exposed as plain
+    attributes for advanced use cases such as RFC 8693 token exchange::
+
+        result = await authplane_auth(issuer=..., base_url=..., ...)
+        mcp = FastMCP("My Server", **result)
+
+        # Inside a tool handler — exchange a user token for a downstream token:
+        downstream = await result.client.exchange(TokenExchangeOptions(
+            subject_token=user_token,
+        ))
+
+    Call ``await result.aclose()`` on server shutdown to release background
+    tasks and HTTP connections held by the underlying ``AuthplaneClient``.
+    """
+
+    def __init__(
+        self,
+        auth: RemoteAuthProvider,
+        token_verifier: AuthplaneTokenVerifier,
+        client: AuthplaneClient,
+    ) -> None:
+        self.auth = auth
+        self.token_verifier = token_verifier
+        self.client = client
+
+    async def aclose(self) -> None:
+        """Release resources held by the underlying ``AuthplaneClient``.
+
+        Cancels the background JWKS refresh task and closes the HTTP
+        connection pool.  Safe to call multiple times.
+        """
+        await self.client.aclose()
+
+    # Mapping protocol — yields only "auth" so FastMCP(**result) works cleanly.
+    def keys(self) -> list[str]:
+        return ["auth"]
+
+    def __getitem__(self, key: str) -> Any:
+        if key == "auth":
+            return self.auth
+        raise KeyError(key)
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self.keys())
+
+
+async def authplane_auth(
+    issuer: str,
+    base_url: str,
+    scopes: list[str] | None = None,
+    *,
+    as_credentials: ASCredentials | None = None,
+    dpop: DPoPProvider | None = None,
+    allowed_algorithms: list[str] | None = None,
+    jwks_refresh_seconds: int | None = None,
+    metadata_refresh_seconds: int | None = None,
+    cache_ttl_buffer_seconds: float | None = None,
+    default_ttl_seconds: float | None = None,
+    circuit_breaker_threshold: int | None = None,
+    circuit_breaker_cooldown_seconds: float | None = None,
+    clock_skew_seconds: int | None = None,
+    dev_mode: bool | None = None,
+    fetch_settings: FetchSettings | None = None,
+    inbound_dpop: InboundDPoPOptions | None = None,
+    mcp_path: str = "/mcp",
+    revocation_checker: IntrospectionRevocation | RevocationChecker | None = None,
+) -> AuthplaneAuthResult:
+    """Build the kwargs to enable Authplane auth on a FastMCP server.
+
+    This async factory performs RFC 8414 metadata discovery, fetches the
+    JWKS, and wires up all components (client, resource, token verifier,
+    auth provider) in a single awaitable call.
+
+    Usage::
+
+        mcp = FastMCP("My Server", **await authplane_auth(
+            issuer="https://auth.company.com",
+            base_url="https://mcp.company.com",
+            scopes=["tools/query", "tools/write"],
+        ))
+
+    After setup:
+
+    - Use ``@mcp.tool(auth=require_scopes(...))`` for scope enforcement.
+    - Use ``CurrentAccessToken()`` or ``get_access_token()`` to access
+      token claims inside tool handlers (both are FastMCP built-ins).
+
+    Args:
+        issuer: Authplane authorization server URL
+            (e.g., ``"https://auth.company.com"``).
+        base_url: Root URL of the FastMCP server
+            (e.g., ``"https://mcp.company.com"``). Same value you would
+            pass to FastMCP for deployment.
+        scopes: All scopes this server supports. Used in AuthSettings
+            and the PRM document. Defaults to an empty list.
+        dpop: Optional DPoP provider used for outbound calls from the
+            underlying SDK client to the authorization server.
+        allowed_algorithms: Algorithms allowed for signature verification.
+            Defaults to SDK defaults (``["RS256", "ES256"]``).
+        jwks_refresh_seconds: JWKS cache TTL in seconds (default ``300``).
+        cache_ttl_buffer_seconds: Buffer subtracted from token TTLs
+            before cache expiry (default ``30.0``).
+        default_ttl_seconds: Fallback token cache TTL used when token
+            responses do not include expiry metadata (default ``3600.0``).
+        circuit_breaker_threshold: Number of transient failures before
+            opening the AS circuit breaker (default ``5``).
+        circuit_breaker_cooldown_seconds: Cooldown before allowing a
+            half-open probe request after the circuit opens
+            (default ``30.0``).
+        clock_skew_seconds: Leeway in seconds for exp/nbf/iat validation
+            (default ``30``).
+        dev_mode: Enable development mode. Relaxes SSRF checks to allow
+            HTTP, localhost, and private networks. Can also be set via
+            ``AUTHPLANE_DEV_MODE=true`` environment variable.
+        metadata_refresh_seconds: AS metadata cache TTL in seconds
+            (default ``3600``).
+        fetch_settings: Full ``FetchSettings`` object applied to both
+            metadata and JWKS fetches. When provided, overrides
+            ``dev_mode`` for those fetches.
+        inbound_dpop: Per-resource inbound DPoP policy
+            (:class:`InboundDPoPOptions`).  Bundles ``required``,
+            ``signing_algs``, ``max_proof_age_seconds``,
+            ``clock_skew_seconds`` and ``replay_store``; see RFC 9728 §2 +
+            RFC 9449 §7.1 for the field semantics.
+        mcp_path: Mount path of the MCP endpoint (default ``"/mcp"``).
+            The JWT audience (resource) is derived as
+            ``base_url + mcp_path``. Only set this if you changed
+            FastMCP's default HTTP mount path.
+        as_credentials: Client credentials for authenticating to the AS.
+            Shared by introspection (RFC 7662) and token exchange (RFC 8693).
+            Required when using ``IntrospectionRevocation`` for authenticated
+            introspection, or when calling ``client.exchange()``.
+        revocation_checker: Controls token revocation checking after
+            signature validation passes.
+
+            - ``None`` (default): disables revocation checking (offline
+              validation only).
+            - ``IntrospectionRevocation()``: calls the AS
+              ``introspection_endpoint`` (RFC 7662) discovered from AS
+              metadata. Raises ``TokenRevokedError`` if ``active=false``.
+              Pass ``as_credentials`` for authenticated introspection.
+              Fails open if the endpoint is unavailable.
+            - async callable: custom checker called with
+              ``(VerifiedClaims, raw_token)``; return ``True`` to reject
+              the token (raises ``TokenRevokedError``).
+
+    Returns:
+        ``AuthplaneAuthResult`` with ``auth`` (``RemoteAuthProvider``),
+        ``token_verifier`` (``AuthplaneTokenVerifier``), and ``client``
+        (``AuthplaneClient``) attributes. Supports ``**`` unpacking into
+        ``FastMCP()`` — only ``auth`` is included in the mapping view.
+        Access ``client`` directly for RFC 8693 token exchange via
+        ``result.client.exchange()``.
+
+    Raises:
+        ValueError: If configuration is invalid (bad algorithms, etc.).
+        JWKSFetchError: If metadata discovery or JWKS fetching fails.
+    """
+    resolved_scopes = scopes or []
+
+    # Derive the canonical resource URL (= JWT audience) from base_url + mcp_path.
+    # This must match exactly what RemoteAuthProvider advertises in the PRM, which
+    # FastMCP computes as base_url + mcp_path via _get_resource_url().
+    resource = base_url.rstrip("/") + "/" + mcp_path.lstrip("/")
+
+    # Prepare client-level kwargs, filtering out None to use SDK defaults
+    client_kwargs_raw: dict[str, Any] = {
+        "dpop": dpop,
+        "dev_mode": dev_mode,
+        "fetch_settings": fetch_settings,
+        "jwks_refresh_seconds": jwks_refresh_seconds,
+        "metadata_refresh_seconds": metadata_refresh_seconds,
+        "cache_ttl_buffer_seconds": cache_ttl_buffer_seconds,
+        "default_ttl_seconds": default_ttl_seconds,
+        "circuit_breaker_threshold": circuit_breaker_threshold,
+        "circuit_breaker_cooldown_seconds": circuit_breaker_cooldown_seconds,
+    }
+    client_kwargs: dict[str, Any] = {k: v for k, v in client_kwargs_raw.items() if v is not None}
+
+    # Prepare resource-level kwargs, filtering out None to use SDK defaults
+    verifier_kwargs_raw: dict[str, Any] = {
+        "allowed_algorithms": allowed_algorithms,
+        "clock_skew_seconds": clock_skew_seconds,
+        "inbound_dpop": inbound_dpop,
+    }
+    verifier_kwargs: dict[str, Any] = {
+        k: v for k, v in verifier_kwargs_raw.items() if v is not None
+    }
+
+    # Create the AuthplaneClient (handles metadata discovery, JWKS fetching, caching)
+    client = await AuthplaneClient.create(
+        issuer=issuer,
+        auth=as_credentials,
+        **client_kwargs,
+    )
+
+    # Translate ConsentRequiredError → MCP UrlElicitationRequiredError at the
+    # client boundary, before user tool code sees it.  Tool authors don't need
+    # to wrap handlers or import elicitation primitives — the MCP wire-format
+    # mapping is owned by the adapter that constructs the client.
+    client = _wrap_client_for_elicitation(client)
+
+    # Create the resource from the client
+    verifier = client.resource(
+        resource=resource,
+        scopes=resolved_scopes,
+        revocation_checker=revocation_checker,
+        **verifier_kwargs,
+    )
+
+    # Wrap in AuthplaneTokenVerifier
+    # Note: FastMCP 3.0.0 uses token_verifier.base_url for PRM generation if provided
+    token_verifier = AuthplaneTokenVerifier(verifier, base_url=base_url)
+
+    # Wrap in RemoteAuthProvider to get PRM routes
+    auth_provider = RemoteAuthProvider(
+        token_verifier=token_verifier,
+        authorization_servers=[AnyHttpUrl(issuer)],
+        base_url=AnyHttpUrl(base_url),
+        scopes_supported=resolved_scopes,
+    )
+
+    return AuthplaneAuthResult(
+        auth=auth_provider,
+        token_verifier=token_verifier,
+        client=client,
+    )

authplane_fastmcp-0.1.0/authplane_fastmcp/url_elicitation.py

@@ -0,0 +1,42 @@
+"""URL elicitation primitive for the FastMCP adapter.
+
+The factory function :func:`authplane_fastmcp.authplane_auth` wraps the
+``AuthplaneClient`` it returns so that ``client.exchange()`` consent errors
+auto-translate into MCP ``-32042`` (URL elicitation required) before user
+tool code sees them.  This module exposes the underlying conversion as a
+small primitive for unusual flows where users build a consent error outside
+the wrapped client and want to raise the MCP-shaped error themselves.
+"""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+from authplane.errors import ConsentRequiredError
+from mcp.shared.exceptions import UrlElicitationRequiredError
+from mcp.types import ElicitRequestURLParams
+
+
+def to_url_elicitation_required_error(
+    error: BaseException,
+) -> UrlElicitationRequiredError | None:
+    """Map a :class:`ConsentRequiredError` with a ``consent_url`` to MCP -32042.
+
+    Returns ``None`` for any other input — non-consent errors and consent
+    errors without a ``consent_url`` are not translatable.  Callers then
+    re-raise the original exception unchanged.
+    """
+    if not isinstance(error, ConsentRequiredError) or not error.consent_url:
+        return None
+
+    return UrlElicitationRequiredError(
+        elicitations=[
+            ElicitRequestURLParams(
+                mode="url",
+                url=error.consent_url,
+                elicitationId=str(uuid4()),
+                message=error.describe(),
+            )
+        ],
+        message=str(error),
+    )

authplane_fastmcp-0.1.0/authplane_fastmcp/verifier.py

@@ -0,0 +1,95 @@
+"""AuthplaneTokenVerifier - FastMCP TokenVerifier backed by AuthplaneResource.
+
+Bridges the Authplane core SDK with FastMCP's ``TokenVerifier`` interface,
+delegating all JWT validation to ``AuthplaneResource`` and mapping results
+to FastMCP's ``AccessToken`` with the full JWT payload in ``claims``.
+"""
+
+from typing import Any, cast
+
+from authplane import AuthplaneError, AuthplaneResource
+from fastmcp.server.auth import AccessToken, TokenVerifier
+
+
+class AuthplaneTokenVerifier(TokenVerifier):
+    """FastMCP TokenVerifier backed by AuthplaneResource.
+
+    Validates JWTs once per request via the core Authplane SDK and returns
+    a FastMCP ``AccessToken`` with ``claims`` populated from the full JWT
+    payload (``VerifiedClaims.raw``). Token claims are then available in
+    tool handlers via FastMCP's native ``CurrentAccessToken()`` dependency
+    or ``get_access_token()`` function.
+
+    All security-critical logic (signature verification, claim validation,
+    JWKS caching, SSRF protection) is handled by the core SDK. This class
+    is a thin adapter that maps between the two interfaces.
+
+    Scope enforcement is FastMCP's responsibility via
+    ``@mcp.tool(auth=require_scopes(...))``.
+    """
+
+    def __init__(
+        self,
+        verifier: AuthplaneResource,
+        base_url: str | None = None,
+        required_scopes: list[str] | None = None,
+    ) -> None:
+        """Initialize the token verifier.
+
+        Args:
+            verifier: A fully initialized ``AuthplaneResource`` instance,
+                typically created via ``AuthplaneClient.create()`` and
+                ``client.resource()``.
+            base_url: The base URL of this server. Passed to the parent
+                ``TokenVerifier`` for PRM generation.
+            required_scopes: Scopes required for all requests. Passed to
+                the parent ``TokenVerifier``.
+        """
+        super().__init__(base_url=base_url, required_scopes=required_scopes)
+        self._verifier = verifier
+
+    @property
+    def verifier(self) -> AuthplaneResource:
+        """The underlying ``AuthplaneResource`` instance."""
+        return self._verifier
+
+    @property
+    def scopes_supported(self) -> list[str]:
+        """Return scopes supported by this verifier.
+
+        Returns the scopes configured in the ``AuthplaneResource``, which
+        are used by FastMCP for PRM metadata generation at
+        ``/.well-known/oauth-protected-resource``.
+        """
+        return list(self._verifier.scopes)
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Validate a JWT and return a FastMCP AccessToken.
+
+        Called by FastMCP once per authenticated request. Delegates to
+        ``AuthplaneResource.verify()`` for all validation, then maps the
+        resulting ``VerifiedClaims`` to a FastMCP ``AccessToken`` with the
+        full JWT payload in ``claims``.
+
+        Args:
+            token: The raw JWT string (FastMCP strips ``'Bearer '``
+                before calling this method).
+
+        Returns:
+            ``AccessToken`` on successful validation with ``token``,
+            ``client_id``, ``scopes``, ``expires_at``, and ``claims``
+            (full JWT payload dict) fields populated. Returns ``None``
+            on any validation failure (FastMCP responds with 401).
+        """
+        try:
+            claims = await self._verifier.verify(token)
+        except AuthplaneError:
+            return None
+
+        return AccessToken(
+            token=token,
+            client_id=claims.client_id,
+            scopes=list(claims.scopes),
+            expires_at=claims.expires_at,
+            claims=cast("dict[str, Any]", claims.raw),  # full JWT payload
+        )