Merge pull request #8 from OSSMafia/chore/bump-packages

chore: package updates and cleanup

Author: mattylight22

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.0.5
+current_version = 0.0.6
 commit = True
 tag = True
 

Makefile

@@ -1,14 +1,35 @@
 format:
-	bash ./scripts/formatter.sh
-
-lint:
-	bash ./scripts/linter.sh
+	docker build --target=format -t package:format -f dockerfile . && \
+	docker run --rm \
+		-v ./fastapi_clerk_auth:/app/fastapi_clerk_auth \
+		-v ./.bumpversion.cfg:/app/.bumpversion.cfg \
+		-v ./pyproject.toml:/app/pyproject.toml \
+		package:format
+	docker rmi package:format || true
 
 version_patch:
-	bash ./scripts/version_patch.sh
+	docker build --target=bump_patch -t package:bumpversion -f dockerfile . && \
+	docker run --rm \
+		-v ./fastapi_clerk_auth:/app/fastapi_clerk_auth \
+		-v ./.bumpversion.cfg:/app/.bumpversion.cfg \
+		-v ./pyproject.toml:/app/pyproject.toml \
+		package:bumpversion
+	docker rmi package:bumpversion || true
 
 version_minor:
-	bash ./scripts/version_minor.sh
+	docker build --target=bump_minor -t package:bumpversion -f dockerfile . && \
+	docker run --rm \
+		-v ./fastapi_clerk_auth:/app/fastapi_clerk_auth \
+		-v ./.bumpversion.cfg:/app/.bumpversion.cfg \
+		-v ./pyproject.toml:/app/pyproject.toml \
+		package:bumpversion
+	docker rmi package:bumpversion || true
 
 version_major:
-	bash ./scripts/version_major.sh
+	docker build --target=bump_major -t package:bumpversion -f dockerfile . && \
+	docker run --rm \
+		-v ./fastapi_clerk_auth:/app/fastapi_clerk_auth \
+		-v ./.bumpversion.cfg:/app/.bumpversion.cfg \
+		-v ./pyproject.toml:/app/pyproject.toml \
+		package:bumpversion
+	docker rmi package:bumpversion || true

README.md

@@ -1,16 +1,28 @@
 # FastAPI Clerk Auth Middleware
 
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-clerk-auth.svg)](https://pypi.org/project/fastapi-clerk-auth/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/fastapi-clerk-auth.svg)](https://pypi.org/project/fastapi-clerk-auth/)
+[![License](https://img.shields.io/github/license/OSSMafia/fastapi-clerk-middleware)](https://github.com/OSSMafia/fastapi-clerk-middleware/blob/main/LICENSE)
 
-FastAPI Auth Middleware for [Clerk](https://clerk.com)
+A lightweight, easy-to-use authentication middleware for [FastAPI](https://fastapi.tiangolo.com/) that integrates with [Clerk](https://clerk.com) authentication services.
 
-Easily setup authentication on your API routes using your Clerk JWKS endpoint.
+This middleware allows you to secure your FastAPI routes by validating JWT tokens against your Clerk JWKS endpoint, making it simple to implement authentication in your API.
+
+## Features
+
+- 🔒 Secure API routes with Clerk JWT validation
+- 🚀 Simple integration with FastAPI's dependency injection system
+- ⚙️ Flexible configuration options (auto error responses, request state access)
+- 📝 Decoded token payload accessible in your route handlers
+
+## Installation
 
-## Install
 ```bash
 pip install fastapi-clerk-auth
 ```
 
 ## Basic Usage
+
 ```python
 from fastapi import FastAPI, Depends
 from fastapi_clerk_auth import ClerkConfig, ClerkHTTPBearer, HTTPAuthorizationCredentials
@@ -19,7 +31,8 @@ from fastapi.encoders import jsonable_encoder
 
 app = FastAPI()
 
-clerk_config = ClerkConfig(jwks_url="https://example.com/.well-known/jwks.json") # Use your Clerk JWKS endpoint
+# Use your Clerk JWKS endpoint
+clerk_config = ClerkConfig(jwks_url="https://your-clerk-frontend-api.clerk.accounts.dev/.well-known/jwks.json") 
 
 clerk_auth_guard = ClerkHTTPBearer(config=clerk_config)
 
@@ -28,17 +41,99 @@ async def read_root(credentials: HTTPAuthorizationCredentials | None = Depends(c
     return JSONResponse(content=jsonable_encoder(credentials))
 ```
 
-The returned `credentials` model will either be of type `None` or `HTTPAuthorizationCredentials`. If the model is populated it will have the following properties:
-- scheme
-    - Indicates the scheme of the Authorization header (Bearer) 
-- credentials
-    - Raw token received from the Authorization header
-- decoded
-    - The payload of the decoded token
+The returned `credentials` model will be either `None` or an `HTTPAuthorizationCredentials` object with these properties:
+
+- `scheme`: Indicates the scheme of the Authorization header (Bearer) 
+- `credentials`: Raw token received from the Authorization header
+- `decoded`: The payload of the decoded token
+
+## Configuration Options
+
+### Disabling Auto Errors
+
+By default, the middleware automatically returns 403 errors if the token is missing or invalid. You can disable this behavior:
 
-## Auto Errors
-By default the middleware automatically returns 403 errors if the token is missing or invalid. You can disable that behavior by setting the following:
 ```python
-clerk_config = ClerkConfig(jwks_url="https://example.com/.well-known/jwks.json", auto_error=False)
+clerk_config = ClerkConfig(
+    jwks_url="https://your-clerk-frontend-api.clerk.accounts.dev/.well-known/jwks.json", 
+    auto_error=False
+)
 ```
-This will allow requests to reach the endpoint for additional logic or error handling.
+
+This allows requests to reach the endpoint for additional logic or custom error handling:
+
+```python
+@app.get("/protected")
+async def protected_endpoint(credentials: HTTPAuthorizationCredentials | None = Depends(clerk_auth_guard)):
+    if not credentials:
+        return {"message": "You're not authenticated, but you can still see this limited data"}
+    
+    # Full access for authenticated users
+    return {"message": "Full access granted", "user_data": credentials.decoded}
+```
+
+### Adding Auth Data to Request State
+
+You can have the `HTTPAuthorizationCredentials` added to the request state for easier access:
+
+```python
+from fastapi import Depends, Request, APIRouter
+from fastapi_clerk_auth import ClerkConfig, ClerkHTTPBearer, HTTPAuthorizationCredentials
+from fastapi.responses import JSONResponse
+from fastapi.encoders import jsonable_encoder
+
+clerk_config = ClerkConfig(
+    jwks_url="https://your-clerk-frontend-api.clerk.accounts.dev/.well-known/jwks.json",
+    add_state=True
+) 
+
+clerk_auth_guard = ClerkHTTPBearer(config=clerk_config)
+
+router = APIRouter(prefix="/todo", dependencies=[Depends(clerk_auth_guard)])
+
+@router.get("/")
+async def read_todo_list(request: Request):
+    auth_data: HTTPAuthorizationCredentials = request.state.clerk_auth
+    user_id = auth_data.decoded.get("sub")
+    
+    # Use user_id to fetch the user's todo items
+    return {"message": f"Todo items for user {user_id}"}
+```
+
+## Advanced Usage
+
+### Role-Based Access Control
+
+You can implement role-based access control by checking the JWT claims:
+
+```python
+from fastapi import Depends, HTTPException, status
+
+def admin_required(credentials: HTTPAuthorizationCredentials = Depends(clerk_auth_guard)):
+    if not credentials:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authenticated"
+        )
+    
+    user_roles = credentials.decoded.get("roles", [])
+    if "admin" not in user_roles:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Admin permission required"
+        )
+    
+    return credentials
+
+@app.get("/admin", dependencies=[Depends(admin_required)])
+async def admin_only():
+    return {"message": "Welcome, admin!"}
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

dockerfile

@@ -0,0 +1,28 @@
+FROM python:3.11-slim AS base
+WORKDIR /app
+COPY ./fastapi_clerk_auth ./fastapi_clerk_auth
+COPY ./pyproject.toml ./pyproject.toml
+COPY .bumpversion.cfg .bumpversion.cfg
+
+
+FROM base AS format
+COPY ./ruff.toml ./ruff.toml
+RUN pip install -e .[dev]
+WORKDIR /app/fastapi_clerk_auth
+CMD ruff check ./ --fix --config ../ruff.toml && ruff format ./ --config ../ruff.toml
+
+
+FROM base AS bumpversion
+RUN pip install bumpversion
+
+
+FROM bumpversion AS bump_patch
+RUN bump2version patch
+
+
+FROM bumpversion AS bump_minor
+RUN bump2version minor
+
+
+FROM bumpversion AS bump_major
+RUN bump2version major

fastapi_clerk_auth/__init__.py

@@ -3,6 +3,7 @@
 
 from fastapi import HTTPException
 from fastapi import Request
+from fastapi.encoders import jsonable_encoder
 from fastapi.openapi.models import HTTPBearer as HTTPBearerModel
 from fastapi.security import HTTPAuthorizationCredentials as FastAPIHTTPAuthorizationCredentials
 from fastapi.security import HTTPBearer
@@ -79,12 +80,30 @@ def __init__(
                     """
             ),
         ] = True,
+        add_state: Annotated[
+            bool,
+            Doc(
+                """
+                    By default, the decoded authentication data is returned from the `Depends`
+                    on the route function. If you'd like to have the decoded authentication data
+                    available in the request state, set this to `True`. This is useful when you
+                    want to have the decoded authentication data available in the request state
+                    while applying the middleware to multiple routes via a router dependency.
+                """
+            ),
+        ] = False,
         debug_mode: bool = False,
     ):
-        super().__init__(bearerFormat=bearerFormat, scheme_name=scheme_name, description=description, auto_error=auto_error)
+        super().__init__(
+            bearerFormat=bearerFormat,
+            scheme_name=scheme_name,
+            description=description,
+            auto_error=auto_error,
+        )
         self.model = HTTPBearerModel(bearerFormat=bearerFormat, description=description)
         self.scheme_name = scheme_name or self.__class__.__name__
         self.auto_error = auto_error
+        self.add_state = add_state
         self.config = config
         self._check_config()
         self.jwks_url: str = config.jwks_url
@@ -99,6 +118,7 @@ def __init__(
             headers=config.jwks_headers,
             timeout=config.jwks_client_timeout,
         )
+        self.add_state = add_state
         self.debug_mode = debug_mode
 
     def _check_config(self) -> None:
@@ -110,7 +130,7 @@ def _check_config(self) -> None:
     def _decode_token(self, token: str) -> dict | None:
         try:
             signing_key = self.jwks_client.get_signing_key_from_jwt(token)
-            return jwt.decode(
+            decoded_token = jwt.decode(
                 token,
                 key=signing_key.key,
                 audience=self.audience,
@@ -122,6 +142,7 @@ def _decode_token(self, token: str) -> dict | None:
                     "verify_iss": self.config.verify_iss,
                 },
             )
+            return dict(jsonable_encoder(decoded_token))
         except Exception as e:
             if self.debug_mode:
                 raise e
@@ -132,23 +153,23 @@ async def __call__(self, request: Request) -> Optional[HTTPAuthorizationCredenti
         scheme, credentials = get_authorization_scheme_param(authorization)
         if not (authorization and scheme and credentials):
             if self.auto_error:
-                raise HTTPException(status_code=HTTP_403_FORBIDDEN, detail="Not authenticated")
-            else:
-                return None
+                raise HTTPException(status_code=HTTP_403_FORBIDDEN, detail="Not Authenticated")
+            return None
         if scheme.lower() != "bearer":
             if self.auto_error:
                 raise HTTPException(
                     status_code=HTTP_403_FORBIDDEN,
-                    detail="Invalid authentication credentials",
+                    detail="Invalid Authentication Credentials",
                 )
-            else:
-                return None
+            return None
 
         decoded_token: dict | None = self._decode_token(token=credentials)
         if not decoded_token and self.auto_error:
             raise HTTPException(
                 status_code=HTTP_403_FORBIDDEN,
-                detail="Invalid authentication credentials",
+                detail="Invalid Authentication Credentials",
             )
-
-        return HTTPAuthorizationCredentials(scheme=scheme, credentials=credentials, decoded=decoded_token)
+        response = HTTPAuthorizationCredentials(scheme=scheme, credentials=credentials, decoded=decoded_token)
+        if self.add_state:
+            request.state.clerk_auth = response
+        return response

pyproject.toml

@@ -1,16 +1,36 @@
 [project]
 name = "fastapi_clerk_auth"
-version = "0.0.5"
+version = "0.0.6"
 description = "FastAPI Auth Middleware for Clerk (https://clerk.com)"
 readme = "README.md"
 requires-python = ">=3.9"
 authors = [
     { name = "OSS Mafia", email = "dev@oss-mafia.com" },
 ]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+keywords = ["fastapi", "clerk", "authentication", "jwt"]
 dependencies = [
     "fastapi>=0.95.0",
     "PyJWT>=2.0.0",
-    "cryptography==43.0.1",
+    "cryptography>=43.0.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff==0.2.0",
+    "pytest",
+    "pytest-asyncio",
+    "pytest-mock",
+    "bump2version",
 ]
 
 [project.urls]