mcp-authkit 0.1.0__py3-none-any.whl

mcp_authkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: mcp-authkit
+Version: 0.1.0
+Summary: Pluggable OAuth 2.0 + credentials elicitation library for FastMCP servers
+License: MIT
+Project-URL: Homepage, https://github.com/masterela/mcp-authkit
+Project-URL: Documentation, https://masterela.github.io/mcp-authkit/
+Project-URL: Repository, https://github.com/masterela/mcp-authkit
+Project-URL: Changelog, https://github.com/masterela/mcp-authkit/blob/main/CHANGELOG.md
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: python-jose[cryptography]>=3.3
+Requires-Dist: mcp>=1.6
+Requires-Dist: jinja2>=3.1
+Requires-Dist: cryptography>=42
+Provides-Extra: redis
+Requires-Dist: redis>=5; extra == "redis"
+Provides-Extra: experimental
+Requires-Dist: uvicorn[standard]>=0.30; extra == "experimental"
+Requires-Dist: pydantic-settings>=2.6; extra == "experimental"
+Requires-Dist: python-dotenv>=1.0; extra == "experimental"
+Dynamic: license-file
+
+# mcp-authkit
+
+[![CI](https://github.com/masterela/mcp-authkit/actions/workflows/ci.yml/badge.svg)](https://github.com/masterela/mcp-authkit/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/masterela/mcp-authkit/branch/main/graph/badge.svg)](https://codecov.io/gh/masterela/mcp-authkit)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://masterela.github.io/mcp-authkit/)
+[![PyPI version](https://img.shields.io/pypi/v/mcp-authkit)](https://pypi.org/project/mcp-authkit/)
+[![Python](https://img.shields.io/pypi/pyversions/mcp-authkit)](https://pypi.org/project/mcp-authkit/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Pluggable authentication library for [FastMCP](https://github.com/modelcontextprotocol/python-sdk) servers built on FastAPI / Starlette.
+
+Supports two independent auth legs:
+
+1. **Primary leg** — every MCP session is gated behind a standard OIDC provider (Keycloak, Okta, Entra ID, Duende, Auth0, …) using JWT bearer tokens. The MCP client (e.g. VS Code Copilot) handles the PKCE flow automatically.
+2. **Secondary leg** — individual MCP tools can additionally require a third-party OAuth token or a PAT / API key, collected on demand via MCP elicitation.
+
+---
+
+## Installation
+
+```bash
+pip install mcp-authkit
+
+# Optional Redis storage backend
+pip install "mcp-authkit[redis]"
+```
+
+---
+
+## Package layout
+
+```
+mcpauthkit/
+├── __init__.py                 # Public exports: OAuthProvider, CredentialsProvider, …
+├── auth_middleware.py          # JwtAuthMiddleware (BaseHTTPMiddleware)
+├── auth_routes.py              # oauth_meta_router() — well-known + DCR façade
+├── jwt_validator.py            # OIDC JWKS-based JWT validation (provider-agnostic)
+├── providers/
+│   ├── oauth_provider.py       # OAuthProvider — third-party OAuth 2.0 leg
+│   ├── credentials_provider.py # CredentialsProvider — PAT / API-key form
+│   └── templates/              # Jinja2 HTML templates (no external CDN)
+└── store/
+    ├── base.py                 # Abstract store interfaces
+    ├── memory.py               # In-process store (dev / testing)
+    ├── file_store.py           # Fernet-encrypted file store
+    ├── redis_store.py          # Async Redis store (requires redis extra)
+    ├── encryption.py           # Fernet key derivation helpers
+    └── factory.py              # create_stores() — env-driven backend selection
+```
+
+The repository also contains `server.py` (a complete example server using GitHub OAuth and Confluence credentials) and a `docker-compose.yml` / `keycloak-realm.json` for running a local Keycloak instance. See the [quickstart repo](https://github.com/masterela/mcp-authkit-quickstart) for a guided walkthrough.
+
+---
+
+## Primary auth leg — OIDC JWT validation
+
+Every request to the MCP server must carry a valid `Authorization: Bearer <token>` issued by the configured OIDC provider. The middleware performs JWKS discovery automatically and caches keys for 10 minutes.
+
+```python
+from mcpauthkit.auth_middleware import JwtAuthMiddleware
+from mcpauthkit.auth_routes import oauth_meta_router
+
+ISSUER_URL    = "https://sso.example.com/realms/my-realm"
+SERVER_URL    = "https://my-mcp-server.example.com"
+CLIENT_ID     = "my-mcp-public-client"   # pre-registered public client
+
+# Publish RFC 8414 / MCP-spec well-known endpoints + DCR façade
+app.include_router(oauth_meta_router(
+    server_base_url=SERVER_URL,
+    issuer_url=ISSUER_URL,
+    client_id=CLIENT_ID,
+))
+
+# Validate JWT on every request; populate current_user ContextVar
+app.add_middleware(
+    JwtAuthMiddleware,
+    issuer_url=ISSUER_URL,
+    current_user=current_user,
+    server_base_url=SERVER_URL,
+    open_paths=(
+        "/.well-known", "/health", "/register",
+        github_oauth.callback_path,
+        *confluence_creds.open_paths,
+    ),
+)
+```
+
+### `oauth_meta_router`
+
+Returns a FastAPI `APIRouter` with:
+
+| Route | Purpose |
+|---|---|
+| `GET /.well-known/oauth-protected-resource` | RFC 9728 resource metadata |
+| `GET /.well-known/oauth-protected-resource/{path}` | Wildcard variant (some clients append the resource path) |
+| `GET /.well-known/oauth-authorization-server` | RFC 8414 authorization server metadata (proxied from the real OIDC provider) |
+| `POST /register` | Dynamic Client Registration façade — always returns the pre-registered public client ID |
+
+### `JwtAuthMiddleware`
+
+`BaseHTTPMiddleware` subclass. Parameters passed via `app.add_middleware(...)`:
+
+| Parameter | Type | Description |
+|---|---|---|
+| `issuer_url` | `str` | OIDC issuer base URL (e.g. Keycloak realm URL) |
+| `current_user` | `ContextVar` | Populated with verified claims on each authenticated request |
+| `server_base_url` | `str` | Used in `WWW-Authenticate` realm / resource-metadata URIs |
+| `open_paths` | `tuple[str, ...]` | Path prefixes that bypass authentication |
+
+Returns `401` with a standards-compliant `WWW-Authenticate: Bearer …` header when authentication fails, triggering the PKCE flow in the MCP client automatically.
+
+### `jwt_validator`
+
+Provider-agnostic OIDC JWT validation. Supports RS256/384/512, PS256/384/512, ES256/384/512, EdDSA. Discovers `jwks_uri` automatically via `{issuer_url}/.well-known/openid-configuration`. OIDC config and JWKS are cached for 10 minutes.
+
+---
+
+## Secondary auth leg — tool-level credential acquisition
+
+Individual tools can be gated behind additional credentials collected on demand via [MCP elicitation](https://spec.modelcontextprotocol.io/specification/2025-11-25/client/elicitation/).
+
+### `OAuthProvider` — third-party OAuth 2.0
+
+Gates a tool behind a full Authorization Code + PKCE flow with a third-party provider. The MCP client opens the provider's login page; the tool call suspends until the callback fires.
+
+```python
+from mcpauthkit import OAuthProvider
+
+github_oauth = OAuthProvider.from_standard_oauth2(
+    name="github",
+    authorization_url="https://github.com/login/oauth/authorize",
+    token_url="https://github.com/login/oauth/access_token",
+    client_id=os.environ["GITHUB_CLIENT_ID"],
+    client_secret=os.environ["GITHUB_CLIENT_SECRET"],
+    scope="read:user repo",
+    redirect_uri=f"{SERVER_URL}/github/callback",
+    user_context=current_user,
+)
+github_oauth.register(app)   # registers GET /github/callback on the FastAPI app
+
+@mcp.tool(description="List open PRs")
+@github_oauth.require_token()
+async def list_prs(ctx: Context, repo: str) -> str:
+    token = github_oauth.get_token()    # guaranteed non-None inside the decorator
+    ...
+```
+
+Key methods:
+
+| Method | Description |
+|---|---|
+| `from_standard_oauth2(...)` | Factory for any standard OAuth 2.0 provider |
+| `register(app)` | Register the callback route on the FastAPI app |
+| `require_token(*, fail_fast=False)` | Decorator — elicits token if not cached, or raises immediately |
+| `get_token()` | Return the cached access token for the current user (or `None`) |
+| `invalidate_token(sub)` | Evict a user's cached token |
+| `.callback_path` | The redirect URI path (add to `open_paths`) |
+
+### `CredentialsProvider` — PAT / API key form
+
+Serves a self-hosted HTML form where the user enters credentials (PATs, API keys, etc.). Values are stored server-side, keyed by the primary OIDC `sub`. The form optionally renders a Markdown how-to guide (client-side via [marked.js](https://marked.js.org/)).
+
+```python
+from mcpauthkit import CredentialsProvider
+
+confluence_creds = CredentialsProvider(
+    name="confluence",
+    variables={
+        "pat": {
+            "label": "Personal Access Token",
+            "type": "password",
+            "placeholder": "Your Confluence PAT",
+        },
+    },
+    user_context=current_user,
+    server_base_url=SERVER_URL,
+    doc="docs/confluence_token_how.md",   # optional — rendered above the form
+)
+confluence_creds.register(app)
+
+@mcp.tool(description="List Confluence pages")
+@confluence_creds.require_credentials()
+async def list_pages(ctx: Context, space: str) -> str:
+    creds = confluence_creds.get_credentials()   # {"pat": "..."}
+    ...
+```
+
+Key methods / properties:
+
+| Member | Description |
+|---|---|
+| `register(app)` | Register entry + submit routes on the FastAPI app |
+| `require_credentials(*, fail_fast=False)` | Decorator — elicits credentials if not cached |
+| `get_credentials()` | Return the cached credentials dict for the current user |
+| `invalidate_credentials(sub)` | Evict a user's cached credentials |
+| `.open_paths` | Tuple of paths to add to `JwtAuthMiddleware` `open_paths` |
+
+---
+
+## MCP mount
+
+The FastMCP sub-app must be mounted at `/` **after** all routes are registered. Its internal Starlette router exposes the MCP endpoint at `/mcp`:
+
+```python
+# All routes (include_router, register, @app.get) must come before this line
+app.mount("/", app=mcp.streamable_http_app())
+```
+
+The MCP client connects to `http://<host>:<port>/mcp`.
+
+---
+
+## HTML templates
+
+All browser-facing pages use Jinja2 templates in `mcpauthkit/providers/templates/`. Every page extends `base.html` which provides:
+
+- A blue "MCP Authentication 🔒" top bar
+- A centered card layout
+- Minimal inline CSS (no external CDN dependencies except `marked.js` on the credentials entry page)
+
+---
+
+## Getting started
+
+A full working example (Docker Compose with Redis + Keycloak, a GitHub OAuth tool, and a Confluence credentials tool) lives in the companion repo:
+
+**[mcp-authkit-quickstart](https://github.com/masterela/mcp-authkit-quickstart)**
+
+---
+
+## Storage backends
+
+| Mode | Class | Notes |
+|---|---|---|
+| `memory` (default) | `MemoryTokenStore` / `MemoryPendingStore` | In-process. Tokens lost on restart. Suitable for development. |
+| `file` | `FileTokenStore` / `FilePendingStore` | Fernet-encrypted JSON files. Good for single-instance deployments. |
+| `redis` | `RedisTokenStore` / `RedisPendingStore` | Async Redis. Requires `pip install "mcp-authkit[redis]"`. Use for multi-replica deployments. |
+
+Select a backend via the `TOKEN_STORAGE_MODE` environment variable (`memory` / `file` / `redis`), or call `create_stores()` directly.
+
+---
+
+## Dependencies
+
+| Package | Purpose |
+|---|---|
+| `fastapi` | HTTP framework |
+| `mcp>=1.6` | MCP server SDK (FastMCP) |
+| `starlette` | ASGI primitives, `BaseHTTPMiddleware` |
+| `python-jose[cryptography]` | JWT decoding and JWKS validation |
+| `httpx` | Async HTTP client (token exchange, OIDC discovery) |
+| `jinja2` | HTML template rendering |
+| `cryptography` | Fernet encryption for file and Redis stores |
+
+---
+
+## Contributing
+
+```bash
+# Install dev dependencies
+uv sync --group dev
+
+# Lint + type-check
+uv run ruff check mcpauthkit/ tests/
+uv run mypy mcpauthkit/
+
+# Tests with coverage
+uv run pytest --cov=mcpauthkit --cov-report=term-missing -q
+```
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.

mcp_authkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+mcp_authkit-0.1.0.dist-info/licenses/LICENSE,sha256=cLo2tx65aSsi1RZJ8-ueSKnnXtV_wM5rhFl2_3ErIsQ,1066
+mcpauthkit/__init__.py,sha256=Ynh57kMTXjXYPF8KtE_4Ie8redEqT46iQJT1PrlW5l4,2947
+mcpauthkit/auth_middleware.py,sha256=zDYVomQRtnpUimyVCwVPjxPyW0aRBXrGPb_3S_w5Rv0,6428
+mcpauthkit/auth_routes.py,sha256=HRvrwigc-Y7r3Kf9qCYvKkt0UWKiTBKktgiQpRrB7TY,4632
+mcpauthkit/jwt_validator.py,sha256=oBLfI7yzIsAR9zr5hma0bgRZQiywIyItYBudwkIWOGw,4819
+mcpauthkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcpauthkit/providers/__init__.py,sha256=IkrzmtGCx8V_n8ZM1zE6uLfPU5JbXc3ZF3EBgp9pfBA,148
+mcpauthkit/providers/credentials_provider.py,sha256=_4PQwbyKYlDBDiEudEdYb3ovnCbuucGA4nehKjFq2yY,20909
+mcpauthkit/providers/oauth_provider.py,sha256=m8zvX5rjzsChfQoYUGnmDMYh3ViYFhhKZLeAsLlL56g,28855
+mcpauthkit/providers/templates/base.html,sha256=3rebGrrpNVqUJS7HXBJdScl6w1cUOECjopl2OgPQfh4,3410
+mcpauthkit/providers/templates/credentials_entry.html,sha256=c0ZuDDas7ZwVmOBSHsUFdeyxjWmgBKx_A5LbbBvokeQ,4281
+mcpauthkit/providers/templates/credentials_error.html,sha256=SW3UG7X9Pl0xp6ZMq3fZ7gwHtMPf5c2gxYvTPltF9nY,229
+mcpauthkit/providers/templates/credentials_success.html,sha256=dUW_6Q_-z9eEwos_GBnJ0LbhJPixaUr5k7beK2NrdIM,301
+mcpauthkit/providers/templates/oauth_error.html,sha256=Gu3sYvjyYOM0Nt9HJFes1DInxlL97YlsaiyZIGyBetY,378
+mcpauthkit/providers/templates/oauth_success.html,sha256=hdDlSpVKmiZSUaDVpbsrLXqm-VB_kN04D2Y4GUtQ8Dg,391
+mcpauthkit/store/__init__.py,sha256=Fy3KPhzIjReE97ilwY8FW0gO1dI3keYJi6P6dm1yuLI,1337
+mcpauthkit/store/base.py,sha256=QkXxaxOxn2p9a4lMYPc3X90BbmeYUYY8l24rsh5KE24,2972
+mcpauthkit/store/encryption.py,sha256=y6ugmzYqAGI2W90tO8Pzkyzr5T_d-Esa2xRQPsbpz3E,3252
+mcpauthkit/store/factory.py,sha256=RhrRHJRn8crFs5jVPgIJcp2VcK9xVOcbfAhkV8IbaSY,4644
+mcpauthkit/store/file_store.py,sha256=-awzOvNz22zGWvJNHwqyuRd29l6GX_V7K6ffqqr_NSg,6855
+mcpauthkit/store/memory.py,sha256=64dAN0Cb5uV3abIDVOG-4Rsoy7L-dOhQ4PJwZwLeCmk,4144
+mcpauthkit/store/redis_store.py,sha256=KexRoJG68DZo_5mPUykdEMW0I2b7L5zW5YYy77fUNOk,6271
+mcp_authkit-0.1.0.dist-info/METADATA,sha256=n330q1pe1enq3wHMzFKcsxF4B0bW3PQXXJ9_sjOX_kI,11877
+mcp_authkit-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mcp_authkit-0.1.0.dist-info/top_level.txt,sha256=HNdSkM4LlUsTFTFZOewB2XFKc4H19B6rtasId0cGTYQ,11
+mcp_authkit-0.1.0.dist-info/RECORD,,

mcp_authkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mcp_authkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 masterela
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_authkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mcpauthkit

mcpauthkit/__init__.py

@@ -0,0 +1,81 @@
+"""
+mcpauthkit — MCP authentication elicitation library
+=====================================================
+
+Provides two providers for gating MCP tools behind credential acquisition:
+
+OAuthProvider
+    Gates tools behind a third-party OAuth 2.0 Authorization Code flow
+    (GitHub, Google, Jira, Entra, etc.).  Uses URL mode elicitation so
+    the client opens the provider's login page; the tool call stays open
+    until the callback fires (or raises immediately in fail-fast mode).
+
+    Quick start::
+
+        from mcpauthkit import OAuthProvider
+
+        github = OAuthProvider.from_standard_oauth2(
+            name="github",
+            authorization_url="https://github.com/login/oauth/authorize",
+            token_url="https://github.com/login/oauth/access_token",
+            client_id=..., client_secret=..., scope="read:user repo",
+            redirect_uri="http://localhost:8005/github/callback",
+            user_context=current_user,
+        )
+        github.register(app)                 # register callback route
+        _OPEN_PATHS = (..., github.callback_path)
+
+        @mcp.tool(description="...")
+        @github.require_token()
+        async def my_tool(ctx: Context, ...) -> str:
+            token = github.get_token()       # guaranteed non-None here
+
+CredentialsProvider
+    Gates tools behind a PAT / API-key form served by the MCP server
+    itself.  The client opens an internal URL where the user fills in
+    credentials; values are stored server-side and never passed through
+    the AI assistant.
+
+    Quick start::
+
+        from mcpauthkit import CredentialsProvider
+
+        creds = CredentialsProvider(
+            name="confluence",
+            variables={"pat": {"label": "PAT", "type": "password", ...}},
+            user_context=current_user,
+            server_base_url="http://localhost:8005",
+            doc="/path/to/how-to.md",        # optional Markdown guide
+        )
+        creds.register(app)
+        _OPEN_PATHS = (..., *creds.open_paths)
+
+        @mcp.tool(description="...")
+        @creds.require_credentials()
+        async def my_tool(ctx: Context, ...) -> str:
+            c = creds.get_credentials()      # {"pat": "...", ...}
+
+auth_routes
+    Generic well-known OAuth metadata endpoints and a DCR façade::
+
+        from mcpauthkit.auth_routes import register_oauth_meta_routes
+        register_oauth_meta_routes(app, server_base_url=..., keycloak_url=..., ...)
+
+store
+    Pluggable encrypted storage backends::
+
+        from mcpauthkit.store import create_stores
+        token_store, pending_store = create_stores()   # reads TOKEN_STORAGE_MODE env var
+        # pass token_store / pending_store into OAuthProvider / CredentialsProvider
+"""
+
+from .providers import CredentialsProvider, OAuthProvider
+from .store import PendingStore, TokenStore, create_stores
+
+__all__ = [
+    "CredentialsProvider",
+    "OAuthProvider",
+    "PendingStore",
+    "TokenStore",
+    "create_stores",
+]

mcpauthkit/auth_middleware.py

@@ -0,0 +1,176 @@
+"""
+mcpauthkit.auth_middleware — JWT bearer middleware for FastAPI / MCP servers.
+
+Validates every incoming request against an OIDC provider's JWKS endpoint
+and populates a ``current_user`` ContextVar so tools can read the caller's
+claims.
+
+Usage
+-----
+    from mcpauthkit.auth_middleware import JwtAuthMiddleware
+
+    app.add_middleware(
+        JwtAuthMiddleware,
+        issuer_url=settings.keycloak_url,
+        current_user=current_user,
+        server_base_url="http://localhost:8005",
+        open_paths=(
+            "/.well-known", "/health", "/register",
+            github_oauth.callback_path,
+            *confluence_creds.open_paths,
+        ),
+    )
+"""
+
+from __future__ import annotations
+
+import logging
+from contextvars import ContextVar
+from typing import cast
+
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+from .jwt_validator import JwtFailReason, validate_jwt
+
+logger = logging.getLogger(__name__)
+
+
+class JwtAuthMiddleware(BaseHTTPMiddleware):
+    """
+    JWT bearer middleware compatible with ``app.add_middleware()``.
+
+    Validates the ``Authorization: Bearer <token>`` header on every
+    non-open request using OIDC JWKS discovery.  Works with any standard
+    OIDC provider (Keycloak, Okta, Entra ID, Duende, Auth0, …).
+
+    Parameters
+    ----------
+    issuer_url
+        Base URL of the OIDC issuer,
+        e.g. ``"http://localhost:8889/realms/mcp-poc5"`` or
+        ``"https://login.microsoftonline.com/{tenant}/v2.0"``.
+    current_user
+        ContextVar populated with the verified JWT claims dict on each
+        authenticated request.
+    server_base_url
+        Used to build the ``WWW-Authenticate`` realm / resource-metadata URIs.
+    open_paths
+        Tuple of path prefixes that bypass authentication (browser redirects,
+        health checks, well-known endpoints, provider callbacks, etc.).
+    """
+
+    def __init__(
+        self,
+        app,
+        *,
+        issuer_url: str,
+        current_user: ContextVar[dict | None],
+        server_base_url: str,
+        open_paths: tuple[str, ...] = (),
+    ) -> None:
+        """Initialise the middleware; see class docstring for parameter descriptions."""
+        super().__init__(app)
+        self._issuer_url = issuer_url
+        self._current_user = current_user
+        self._base = server_base_url.rstrip("/")
+        self._open_paths = open_paths
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        """Process a single request: validate the Bearer token or pass through open paths.
+
+        Returns a ``401 Unauthorized`` JSON response (with a standards-compliant
+        ``WWW-Authenticate: Bearer`` header) when the token is absent, malformed,
+        has the wrong issuer, or carries an invalid signature.  Returns a
+        ``401`` with ``error=invalid_token`` when the token has expired, so
+        the client can use its refresh token.
+
+        Parameters
+        ----------
+        request
+            The incoming Starlette / FastAPI request.
+        call_next
+            The next ASGI handler in the middleware chain.
+        """
+        logger.debug(
+            "→ %s %s  auth=%s  open=%s",
+            request.method,
+            request.url.path,
+            bool(request.headers.get("Authorization")),
+            self._is_open(request.url.path),
+        )
+
+        if request.method == "OPTIONS" or self._is_open(request.url.path):
+            return cast(Response, await call_next(request))
+
+        auth_header = request.headers.get("Authorization", "")
+        if not auth_header.startswith("Bearer "):
+            logger.debug("→ no/bad Bearer → 401")
+            return self._unauthorized()
+
+        token = auth_header[len("Bearer ") :]
+        claims, fail_reason = await validate_jwt(token, self._issuer_url)
+        if claims is None:
+            logger.debug("→ JWT invalid (reason=%s) → 401", fail_reason)
+            return (
+                self._token_expired()
+                if fail_reason is JwtFailReason.EXPIRED
+                else self._unauthorized()
+            )
+
+        sub = claims.get("sub") or claims.get("preferred_username", "unknown")
+        logger.info(
+            "Authenticated: sub=%s preferred_username=%s",
+            sub,
+            claims.get("preferred_username"),
+        )
+        self._current_user.set(
+            {
+                "sub": sub,
+                "preferred_username": claims.get("preferred_username"),
+                "email": claims.get("email"),
+                "name": claims.get("name"),
+                "iss": claims.get("iss"),
+                "exp": claims.get("exp"),
+            }
+        )
+        return cast(Response, await call_next(request))
+
+    # ── Internal ─────────────────────────────────────────────────────────────────
+
+    def _is_open(self, path: str) -> bool:
+        """Return True if *path* starts with any of the configured open path prefixes."""
+        return any(path.startswith(p) for p in self._open_paths)
+
+    def _unauthorized(self) -> JSONResponse:
+        """No token — client must start a fresh PKCE flow (RFC 6750 §3.1)."""
+        return JSONResponse(
+            status_code=401,
+            headers={
+                "WWW-Authenticate": (
+                    f'Bearer realm="{self._base}/mcp",'
+                    f' resource_metadata="{self._base}/.well-known/oauth-protected-resource"'
+                )
+            },
+            content={"error": "unauthorized"},
+        )
+
+    def _token_expired(self) -> JSONResponse:
+        """Token present but expired — client should refresh (RFC 6750 §3.1)."""
+        return JSONResponse(
+            status_code=401,
+            headers={
+                "WWW-Authenticate": (
+                    f'Bearer realm="{self._base}/mcp",'
+                    f' resource_metadata="{self._base}/.well-known/oauth-protected-resource",'
+                    f' error="invalid_token",'
+                    f' error_description="The access token has expired"'
+                )
+            },
+            content={
+                "error": "invalid_token",
+                "error_description": "The access token has expired",
+            },
+        )