fastmcp-auth 0.1.0__py3-none-any.whl

fastmcp_auth/__init__.py

@@ -0,0 +1,7 @@
+"""FastMCP Auth - JWE authentication middleware for FastMCP/Starlette."""
+
+from .middleware import AuthUser, JWKSAuthMiddleware, get_user
+from .verifier import JWETokenVerifier
+
+__version__ = "0.1.0"
+__all__ = ["JWETokenVerifier", "JWKSAuthMiddleware", "get_user", "AuthUser"]

fastmcp_auth/cli.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""FastMCP Auth CLI - Key management for JWE authentication."""
+
+import argparse
+import base64
+import json
+import os
+import secrets
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    from jwcrypto import jwk
+except ImportError:
+    print("Error: 'jwcrypto' library is required.", file=sys.stderr)
+    print("Please run: pip install jwcrypto", file=sys.stderr)
+    sys.exit(1)
+
+KEY_SIZE = 4096
+KEY_FILES = ("mcp-private.json", "mcp-public.json")
+
+
+def generate_keys(output_dir: Path) -> tuple[Path, Path]:
+    """Generate an RSA JWKS key pair and write to output_dir."""
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    key = jwk.JWK.generate(kty="RSA", size=KEY_SIZE)
+    key["kid"] = key.thumbprint()
+
+    private_jwks = {"keys": [json.loads(key.export_private())]}
+    public_jwks = {"keys": [json.loads(key.export_public())]}
+
+    private_key_path = output_dir / "mcp-private.json"
+    public_key_path = output_dir / "mcp-public.json"
+
+    with open(private_key_path, "w") as f:
+        json.dump(private_jwks, f, indent=2)
+
+    try:
+        os.chmod(private_key_path, 0o600)
+    except OSError:
+        pass
+
+    with open(public_key_path, "w") as f:
+        json.dump(public_jwks, f, indent=2)
+
+    return private_key_path, public_key_path
+
+
+def secure_delete(file_path: Path) -> None:
+    """Securely delete a file using shred or overwrite fallback."""
+    if not file_path.exists():
+        return
+
+    if shutil.which("shred"):
+        subprocess.run(
+            ["shred", "--remove", "--zero", "--iterations=3", str(file_path)],
+            check=True,
+        )
+        return
+
+    try:
+        size = file_path.stat().st_size
+        with open(file_path, "r+b") as f:
+            f.write(secrets.token_bytes(size))
+            f.flush()
+            os.fsync(f.fileno())
+    except OSError:
+        pass
+
+    file_path.unlink()
+
+
+def clean_keys(key_dir: Path) -> list[str]:
+    """Remove key files from key_dir. Returns list of removed paths."""
+    removed = []
+    for name in KEY_FILES:
+        key_file = key_dir / name
+        if not key_file.exists():
+            continue
+
+        if "private" in name:
+            secure_delete(key_file)
+        else:
+            key_file.unlink()
+
+        removed.append(str(key_file))
+    return removed
+
+
+def cmd_generate(args: argparse.Namespace) -> None:
+    output_dir = args.output.resolve()
+    private_key, public_key = generate_keys(output_dir)
+
+    print(f"Keys generated (JWKS format):")
+    print(f"  Private: {private_key}")
+    print(f"  Public:  {public_key}")
+    print(f"\nFor local development, add to .env:")
+    print(f"  MCP_KEY_FILE_PATH={private_key}")
+    print(f"\nAdd to .gitignore:")
+    print(f"  .keys/")
+
+
+def cmd_k8s(args: argparse.Namespace) -> None:
+    output_dir = args.output.resolve()
+    private_key, _ = generate_keys(output_dir)
+
+    with open(private_key, "rb") as f:
+        b64_key = base64.b64encode(f.read()).decode("utf-8")
+
+    k8s_yaml = f"""\
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {args.secret_name}
+  namespace: {args.namespace}
+type: Opaque
+data:
+  mcp_jwks: {b64_key}
+"""
+    print(k8s_yaml)
+    print(f"# Apply: fastmcp-auth k8s | kubectl apply -f -", file=sys.stderr)
+    print(f"# Then clean local keys: fastmcp-auth clean", file=sys.stderr)
+
+
+def cmd_clean(args: argparse.Namespace) -> None:
+    removed = clean_keys(args.output.resolve())
+    if removed:
+        print("Removed:\n  " + "\n  ".join(removed))
+    else:
+        print(f"No keys found in {args.output}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="fastmcp-auth", description="FastMCP Auth - Key Management (JWKS)"
+    )
+    subs = parser.add_subparsers(dest="command", required=True)
+
+    commands = [
+        ("generate", "Generate RSA JWKS key pair", cmd_generate),
+        ("k8s", "Generate keys and output Kubernetes secret YAML", cmd_k8s),
+        ("clean", "Remove keys securely", cmd_clean),
+    ]
+
+    for name, help_text, handler in commands:
+        p = subs.add_parser(name, help=help_text)
+        p.add_argument(
+            "-o",
+            "--output",
+            type=Path,
+            default=Path(".keys"),
+            help="Key directory (default: .keys)",
+        )
+        p.set_defaults(func=handler)
+
+    k8s = subs.choices["k8s"]
+    k8s.add_argument(
+        "-n", "--namespace", default="default", help="Kubernetes namespace"
+    )
+    k8s.add_argument(
+        "-s", "--secret-name", default="mcp-server-keys", help="Secret name"
+    )
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

fastmcp_auth/middleware.py

@@ -0,0 +1,61 @@
+"""JWE authentication middleware for Starlette/FastMCP."""
+
+from contextvars import ContextVar
+from typing import Any
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+from .verifier import JWETokenVerifier
+
+_user_context: ContextVar[dict] = ContextVar("user", default={})
+
+
+class AuthUser(dict):
+    """User claims with attribute access. Missing keys return None."""
+
+    def __getattr__(self, name: str) -> Any:
+        return self.get(name)
+
+
+def get_user() -> AuthUser:
+    """Get authenticated user from current request context."""
+    return AuthUser(_user_context.get())
+
+
+class JWKSAuthMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware that decrypts JWE Bearer tokens and serves JWKS endpoint.
+
+    Usage:
+        app = mcp.http_app()
+        app.add_middleware(JWKSAuthMiddleware)
+        uvicorn.run(app, host="0.0.0.0", port=8000)
+    """
+
+    def __init__(
+        self,
+        app,
+        verifier: JWETokenVerifier | None = None,
+        jwks_path: str = "/.well-known/jwks.json",
+    ):
+        super().__init__(app)
+        self.verifier = verifier or JWETokenVerifier()
+        self.jwks_path = jwks_path
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        if request.url.path == self.jwks_path:
+            return JSONResponse(self.verifier.get_jwks())
+
+        claims = {}
+        if (auth := request.headers.get("authorization", "")).lower().startswith(
+            "bearer "
+        ):
+            claims = await self.verifier.verify_token(auth[7:]) or {}
+
+        token = _user_context.set(claims)
+        try:
+            return await call_next(request)
+        finally:
+            _user_context.reset(token)

fastmcp_auth/verifier.py

@@ -0,0 +1,52 @@
+"""JWE token verification and JWKS support."""
+
+import json
+import logging
+import os
+from typing import Any
+
+from jose import jwe
+
+logger = logging.getLogger(__name__)
+
+
+class JWETokenVerifier:
+    """Verifies JWE tokens and exposes public key as JWKS."""
+
+    def __init__(self) -> None:
+        self._jwk = self._load_key_from_env()
+
+    @staticmethod
+    def _load_key_from_env() -> dict | None:
+        path = os.environ.get("MCP_KEY_FILE_PATH")
+        if not path:
+            return None
+
+        try:
+            with open(path) as f:
+                data = json.load(f)
+
+            if "keys" in data and isinstance(data["keys"], list):
+                return data["keys"][0]
+            return data
+
+        except (FileNotFoundError, json.JSONDecodeError) as e:
+            logger.error(f"Key loading error: {e}")
+            return None
+
+    async def verify_token(self, token: str) -> dict[str, Any] | None:
+        if not self._jwk:
+            return None
+        try:
+            payload = json.loads(jwe.decrypt(token, self._jwk))
+            return payload.get("data", payload)
+        except Exception as e:
+            logger.debug(f"Token verification failed: {e}")
+            return None
+
+    def get_jwks(self) -> dict[str, Any]:
+        if not self._jwk:
+            return {"keys": []}
+        public_fields = {"kty", "kid", "alg", "use", "n", "e"}
+        public_jwk = {k: v for k, v in self._jwk.items() if k in public_fields}
+        return {"keys": [public_jwk]}

fastmcp_auth-0.1.0.dist-info/METADATA

@@ -0,0 +1,280 @@
+Metadata-Version: 2.4
+Name: fastmcp-auth
+Version: 0.1.0
+Summary: JWE authentication middleware for FastMCP/Starlette applications
+Author: Aurel Bartmann
+License: MIT
+Project-URL: Homepage, https://github.com/fhswf/fastmcp-auth
+Project-URL: Documentation, https://github.com/fhswf/fastmcp-auth#readme
+Project-URL: Repository, https://github.com/fhswf/fastmcp-auth
+Project-URL: Issues, https://github.com/fhswf/fastmcp-auth/issues
+Keywords: mcp,fastmcp,jwe,jwks,authentication,middleware,starlette
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Security
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-jose[cryptography]>=3.5.0
+Requires-Dist: starlette>=0.52.1
+Requires-Dist: jwcrypto>=1.5.6
+Dynamic: license-file
+
+# fastmcp-auth
+
+JWE authentication middleware for [FastMCP](https://github.com/jlowin/fastmcp) / Starlette servers. Encrypt user data end-to-end so that only your MCP server can read it.
+
+## What it does
+
+`fastmcp-auth` gives your FastMCP server two things:
+
+1. **A middleware** that intercepts incoming requests, decrypts a JWE Bearer token, and makes the authenticated user's claims available via `get_user()`.
+2. **A CLI** (`fastmcp-auth`) that generates RSA key pairs in JWKS format, outputs Kubernetes Secret YAML, and securely deletes local keys when you're done.
+
+---
+
+## Installation
+
+```bash
+pip install fastmcp-auth
+```
+
+This installs the library **and** the `fastmcp-auth` CLI.
+
+---
+
+## Quick start (local development)
+
+### 1. Generate keys
+
+```bash
+fastmcp-auth generate
+```
+
+Output:
+
+```
+Keys generated (JWKS format):
+  Private: .keys/mcp-private.json
+  Public:  .keys/mcp-public.json
+```
+
+Add `.keys/` to your `.gitignore` immediately.
+
+### 2. Set the environment variable
+
+Create a `.env` file (or export directly):
+
+```bash
+MCP_KEY_FILE_PATH=.keys/mcp-private.json
+```
+
+### 3. Add the middleware to your FastMCP server
+
+```python
+from fastmcp import FastMCP
+from fastmcp_auth import JWKSAuthMiddleware, get_user
+import uvicorn
+
+mcp = FastMCP("My Server")
+
+# Register your tools on `mcp` as usual …
+
+app = mcp.http_app()
+app.add_middleware(JWKSAuthMiddleware)
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+### 4. Access user claims inside any tool
+
+```python
+@mcp.tool()
+def whoami() -> str:
+    user = get_user()
+    return f"Hello, {user.name or 'anonymous'}!"
+```
+
+`get_user()` returns an `AuthUser` dict. Access claims as attributes — missing keys return `None` instead of raising.
+
+---
+
+## Kubernetes deployment
+
+### 1. Generate keys and pipe straight into kubectl
+
+```bash
+fastmcp-auth k8s | kubectl apply -f -
+```
+
+This creates a Kubernetes `Secret` named `mcp-server-keys` in the `default` namespace. Customise with flags:
+
+```bash
+fastmcp-auth k8s --namespace my-ns --secret-name my-mcp-keys | kubectl apply -f -
+```
+
+### 2. Clean up local key material
+
+```bash
+fastmcp-auth clean
+```
+
+Uses `shred` (Linux) for secure deletion when available; falls back to overwrite-then-delete.
+
+### 3. Mount the secret in your deployment
+
+Add the following snippets to your existing Deployment YAML.
+
+**Volume definition** (under `spec.template.spec.volumes`):
+
+```yaml
+- name: mcp-secret-volume
+  secret:
+    secretName: mcp-server-keys   # must match --secret-name
+    defaultMode: 0400
+    items:
+      - key: mcp_jwks
+        path: key.json
+```
+
+**Volume mount** (under your container's `volumeMounts`):
+
+```yaml
+- mountPath: /etc/mcp/secrets
+  name: mcp-secret-volume
+  readOnly: true
+```
+
+**Environment variable** (under `env`):
+
+```yaml
+- name: MCP_KEY_FILE_PATH
+  value: "/etc/mcp/secrets/key.json"
+```
+
+A full example Deployment + Service is in [`examples/k8s-deployment.yaml`](examples/k8s-deployment.yaml).
+
+---
+
+## CLI reference
+
+All commands accept `-o / --output <dir>` to change the key directory (default: `.keys`).
+
+| Command | Description |
+|---|---|
+| `fastmcp-auth generate` | Generate an RSA-4096 JWKS key pair |
+| `fastmcp-auth k8s` | Generate keys and print a Kubernetes Secret YAML to stdout |
+| `fastmcp-auth clean` | Securely delete keys from the output directory |
+
+### `fastmcp-auth k8s` flags
+
+| Flag | Default | Description |
+|---|---|---|
+| `-n, --namespace` | `default` | Kubernetes namespace |
+| `-s, --secret-name` | `mcp-server-keys` | Name of the K8s Secret |
+
+---
+
+## API reference
+
+### `JWKSAuthMiddleware`
+
+Starlette middleware. Attach it to your FastMCP HTTP app:
+
+```python
+app.add_middleware(
+    JWKSAuthMiddleware,
+    verifier=None,        # optional: provide your own JWETokenVerifier
+    jwks_path="/.well-known/jwks.json",  # public-key endpoint path
+)
+```
+
+The middleware automatically serves your server's **public** JWKS at the configured path so that token producers can discover your encryption key.
+
+### `get_user() -> AuthUser`
+
+Returns the authenticated user's claims for the current request. Safe to call from any async context (tools, routes, dependencies) during request handling.
+
+```python
+user = get_user()
+user.email   # claim value or None
+user["role"]  # also works as a regular dict
+```
+
+### `JWETokenVerifier`
+
+Lower-level class if you need to verify tokens outside the middleware:
+
+```python
+from fastmcp_auth import JWETokenVerifier
+
+verifier = JWETokenVerifier()          # reads MCP_KEY_FILE_PATH
+claims = await verifier.verify_token(token_string)
+public_jwks = verifier.get_jwks()       # for publishing
+```
+
+---
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `MCP_KEY_FILE_PATH` | Yes | Path to the private JWKS JSON file |
+
+---
+
+## How the token flow works
+
+```
+Producer (client/gateway)             MCP Server
+―――――――――――――――――――――――――             ――――――――――
+                                      GET /.well-known/jwks.json
+                              ◄────   { public RSA key }
+Encrypt claims with public key
+POST /mcp/tool  ──────────────────►
+  Authorization: Bearer <JWE>
+                                      Middleware decrypts JWE
+                                      with private key
+                                      ─► get_user() returns claims
+```
+
+1. The token producer fetches the server's public key from `/.well-known/jwks.json`.
+2. It encrypts a JSON payload (user claims) into a JWE token using that public key.
+3. The token is sent as a `Bearer` token in the `Authorization` header.
+4. The middleware decrypts it with the private key and exposes claims via `get_user()`.
+
+---
+
+## Project structure
+
+```
+fastmcp-auth/
+├── pyproject.toml
+├── README.md
+├── LICENSE
+├── CHANGELOG.md
+├── requirements.txt
+├── requirements-dev.txt
+├── MANIFEST.in
+├── .gitignore
+├── fastmcp_auth/
+│   ├── __init__.py
+│   ├── py.typed
+│   ├── cli.py
+│   ├── middleware.py
+│   └── verifier.py
+├── tests/
+└── examples/
+    ├── server.py
+    └── k8s-deployment.yaml
+```
+
+---
+## License
+
+MIT

fastmcp_auth-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+fastmcp_auth/__init__.py,sha256=blsHk0reNnRt9LNy4gmMSTh5gtONDxJTiLUpeAmMJCA,277
+fastmcp_auth/cli.py,sha256=3yAzLge3XyM5ScCas_2sJ31tnFI1HtsChohj9XM8IiA,4624
+fastmcp_auth/middleware.py,sha256=BSIL49eid-TQwt-G9vMYBd8DYxOziRGRRCZzSBo2Sik,1771
+fastmcp_auth/verifier.py,sha256=jj-30ivr_KnHitp8gKVy_XtIONTlcDc16MsXEC2xMLE,1493
+fastmcp_auth-0.1.0.dist-info/licenses/LICENSE,sha256=BD0bvGFuIMtkoA_GGht8ks9SrJke-X2JiWfowiG0VNA,1084
+fastmcp_auth-0.1.0.dist-info/METADATA,sha256=YzbpXxIdb753VuQhUeToBwZAIeFN8ACuDMjOAxHV9JI,7303
+fastmcp_auth-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+fastmcp_auth-0.1.0.dist-info/entry_points.txt,sha256=2ay8xbtcCEWgeZJYOPIhIbQbwg4pqFUIRJqckI5N84s,55
+fastmcp_auth-0.1.0.dist-info/top_level.txt,sha256=Eox9oXs3M9sJMiZn9uDnelrMvZG01QyXKN5Uf5C-8fA,13
+fastmcp_auth-0.1.0.dist-info/RECORD,,

fastmcp_auth-0.1.0.dist-info/WHEEL

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

fastmcp_auth-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fastmcp-auth = fastmcp_auth.cli:main

fastmcp_auth-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fachhochschule Südwestfalen
+
+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.

fastmcp_auth-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fastmcp_auth