fastapi-oauth2-cookie 0.0.1__py3-none-any.whl

fastapi_oauth2_cookie/__init__.py

@@ -0,0 +1,4 @@
+from .oauth2_password_cookie import OAuth2PasswordCookie, Tokens
+from .auth_cookie_manager import AuthCookieManager
+
+__all__ = ["OAuth2PasswordCookie", "AuthCookieManager", "Tokens"]

fastapi_oauth2_cookie/auth_cookie_manager.py

@@ -0,0 +1,66 @@
+from typing import Literal, Optional
+from fastapi import Response
+
+
+class AuthCookieManager:
+    """
+    Basic auth cookie management
+    """
+
+    def __init__(
+        self,
+        access_cookie_name: str = "ACCESS-TOKEN",
+        refresh_cookie_name: str = "REFRESH-TOKEN",
+        refresh_path: str = "/refresh-token",
+        secure: bool = True,
+        samesite: Literal["lax", "strict", "none"] = "lax",
+    ):
+        self.access_cookie_name: str = access_cookie_name
+        self.refresh_cookie_name: str = refresh_cookie_name
+        self.refresh_path = refresh_path
+        self.secure: bool = secure
+        self.samesite: Literal["lax", "strict", "none"] = samesite
+
+    def set_auth_cookies(
+        self,
+        response: Response,
+        access_token: str,
+        refresh_token: Optional[str] = None,
+        max_age_access: int = 900,
+        max_age_refresh: int = 604800,
+    ) -> None:
+        """Sets auth cookies using the manager's global configuration."""
+        response.set_cookie(
+            key=self.access_cookie_name,
+            value=access_token,
+            httponly=True,
+            secure=self.secure,
+            samesite=self.samesite,
+            max_age=max_age_access,
+        )
+        if refresh_token:
+            response.set_cookie(
+                key=self.refresh_cookie_name,
+                value=refresh_token,
+                path=self.refresh_path,
+                httponly=True,
+                secure=self.secure,
+                samesite=self.samesite,
+                max_age=max_age_refresh,
+            )
+
+    def clear_auth_cookies(self, response: Response) -> None:
+        """Clears auth cookies using the manager's global configuration."""
+        response.delete_cookie(
+            key=self.access_cookie_name,
+            secure=self.secure,
+            samesite=self.samesite,
+            httponly=True,
+        )
+        response.delete_cookie(
+            key=self.refresh_cookie_name,
+            secure=self.secure,
+            samesite=self.samesite,
+            httponly=True,
+            path=self.refresh_path,
+        )

fastapi_oauth2_cookie/oauth2_password_cookie.py

@@ -0,0 +1,59 @@
+from typing import Dict, NamedTuple, Optional
+from fastapi import HTTPException, Request, status
+from fastapi.openapi.models import OAuthFlowPassword
+from fastapi.openapi.models import OAuthFlows as OAuthFlowsModel
+from fastapi.security import OAuth2
+
+
+class Tokens(NamedTuple):
+    access_token: str
+    csrf_token: Optional[str]
+
+
+class OAuth2PasswordCookie(OAuth2):
+    """
+    OAuth2 security scheme that extracts the access token from an HttpOnly cookie
+    and the CSRF token from a custom header.
+    """
+
+    def __init__(
+        self,
+        tokenUrl: str,
+        scheme_name: Optional[str] = None,
+        scopes: Optional[Dict[str, str]] = None,
+        auto_error: bool = True,
+        access_cookie_name: str = "ACCESS-TOKEN",
+        csrf_header_name: str = "X-CSRF-TOKEN",
+        require_csrf: bool = True,
+    ):
+        if not scopes:
+            scopes = {}
+
+        flows = OAuthFlowsModel(
+            password=OAuthFlowPassword(tokenUrl=tokenUrl, scopes=scopes)
+        )
+        super().__init__(flows=flows, scheme_name=scheme_name, auto_error=auto_error)
+
+        self.access_cookie_name = access_cookie_name
+        self.csrf_header_name = csrf_header_name
+        self.require_csrf = require_csrf
+
+    async def __call__(  # type: ignore[override]
+        self, request: Request
+    ) -> Optional[Tokens]:
+        access_token = request.cookies.get(self.access_cookie_name)
+        csrf_token = (
+            request.headers.get(self.csrf_header_name) if self.require_csrf else None
+        )
+
+        if not access_token or (self.require_csrf and not csrf_token):
+            if self.auto_error:
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail="Not authenticated",
+                    headers={"WWW-Authenticate": "Bearer"},
+                )
+            else:
+                return None
+
+        return Tokens(access_token=access_token, csrf_token=csrf_token)

fastapi_oauth2_cookie-0.0.1.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: fastapi-oauth2-cookie
+Version: 0.0.1
+Summary: A lightweight FastAPI library for OAuth2 via HttpOnly Cookies and CSRF headers.
+Project-URL: Homepage, https://github.com/D1918/fastapi-oauth2-cookie.git
+Author-email: Denis Lyovin <DOS1918@proton.me>
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.95.0
+Description-Content-Type: text/markdown
+
+# FastAPI OAuth2 Cookie Authentication
+
+A lightweight, production-ready FastAPI library for handling OAuth2 authentication using **HttpOnly Cookies** and **CSRF headers**.
+
+## Features
+
+* 🔒 **HttpOnly Cookies**: Keeps JWT access and refresh tokens out of `localStorage` to prevent XSS attacks.
+* ⚡️ **Swagger UI Compatible**: Extends FastAPI's native `OAuth2` class to keep your OpenAPI docs working.
+* 🛡️ **CSRF Defense**: Native support for extracting and requiring CSRF tokens via headers (`X-CSRF-TOKEN`).
+* 🪶 **Zero Overhead**: No third-party dependencies outside of FastAPI.
+
+## Installation
+
+```bash
+pip install fastapi-oauth2-cookie
+# or using uv:
+uv add fastapi-oauth2-cookie
+
+```
+
+## Quickstart
+
+Here is everything you need to set up login, logout, and a protected route.
+
+```python
+from typing import Annotated
+from fastapi import Depends, FastAPI, HTTPException, Response, status
+from fastapi.security import OAuth2PasswordRequestForm
+from fastapi_oauth2_cookie import AuthCookieManager, OAuth2PasswordCookie, Tokens
+
+app = FastAPI()
+
+cookie_manager = AuthCookieManager(secure=False) # set True in production
+
+oauth2_scheme = OAuth2PasswordCookie(
+    tokenUrl="token",
+    access_cookie_name=cookie_manager.access_cookie_name,
+    require_csrf=False # set to True in production to avoid CSRF attacks 
+)
+
+FAKE_USERS_DB = {
+    "johndoe": {
+        "username": "johndoe",
+        "hashed_password": "fakehashedsecretpassword",
+    }
+}
+
+def fake_hash_password(password: str):
+    return "fakehashed" + password
+
+def fake_decode_token(token: str):
+    return FAKE_USERS_DB.get(token)
+
+async def get_current_user(tokens: Tokens = Depends(oauth2_scheme)):
+    user = fake_decode_token(tokens.access_token)
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid authentication credentials",
+        )
+    return user
+
+@app.post("/token")
+async def login(
+    response: Response, 
+    form_data: Annotated[OAuth2PasswordRequestForm, Depends()]
+):
+    user = FAKE_USERS_DB.get(form_data.username)
+    if not user or fake_hash_password(form_data.password) != user["hashed_password"]:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST, 
+            detail="Incorrect username or password"
+        )
+
+    # 1. Set the HttpOnly cookie for the browser
+    cookie_manager.set_auth_cookies(response, access_token=user["username"])
+    
+    # 2. Return standard OAuth2 JSON so Swagger UI works correctly
+    return {"access_token": user["username"], "token_type": "bearer"}
+
+@app.get("/users/me")
+async def read_users_me(current_user: dict = Depends(get_current_user)):
+    return {"username": current_user["username"]}
+
+@app.post("/logout")
+def logout(response: Response):
+    cookie_manager.clear_auth_cookies(response)
+    return {"message": "Successfully logged out"}
+
+```
+
+## Core API
+
+### `AuthCookieManager`
+
+Handles the configuration and application of cookies
+
+* `set_auth_cookies(response, access_token, refresh_token=None, ...)`: Attaches `HttpOnly` cookies to the response.
+* `clear_auth_cookies(response)`: Clears the authentication cookies.
+
+### `OAuth2PasswordCookie`
+
+The FastAPI dependency you inject into your routes.
+
+* Extracts the token from the configured `access_cookie_name`.
+* Optionally enforces and extracts a CSRF token from the `csrf_header_name` (defaults to `X-CSRF-TOKEN`).
+* Returns a named tuple `Tokens`: `(access_token, csrf_token)`. Raises `401 Unauthorized` if tokens are missing or invalid.
+
+## Development
+
+### Run dev server
+```bash
+uv run fastapi dev dev/main.py
+```
+
+### Run tests
+```bash
+uv run pytest
+```
+
+## License
+
+MIT

fastapi_oauth2_cookie-0.0.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+fastapi_oauth2_cookie/__init__.py,sha256=mGFvGrJEWHo0ss3G4fUdZmcqsxgQqOmtZ1cQmwt_q5k,183
+fastapi_oauth2_cookie/auth_cookie_manager.py,sha256=PFj6w_dEmxxbNQwNc8Plr_ZpM6G8t3amQuR4xBJxkt0,2103
+fastapi_oauth2_cookie/oauth2_password_cookie.py,sha256=1xa2K_b-APK2IsW6g-sQN6IPqw_tZYtO5FgcmCx90Do,1971
+fastapi_oauth2_cookie/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_oauth2_cookie-0.0.1.dist-info/METADATA,sha256=7XVkQPRWDHlGw9IBWmDuLxREQ7svxm4rtH0p7OifduU,4066
+fastapi_oauth2_cookie-0.0.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+fastapi_oauth2_cookie-0.0.1.dist-info/RECORD,,

fastapi_oauth2_cookie-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any