fastapi-oauth2-cookie 0.0.1__tar.gz

fastapi_oauth2_cookie-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/fastapi-oauth2-cookie
+    permissions:
+      id-token: write    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fastapi_oauth2_cookie-0.0.1/.gitignore

@@ -0,0 +1,70 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+
+# Virtual environments
+env/
+venv/
+.venv/
+env3.*
+*venv*
+
+# Packaging / builds
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Testing / coverage
+.pytest_cache/
+.mypy_cache/
+.pyre/
+.pytype/
+.ruff_cache/
+.hypothesis/
+htmlcov/
+.coverage*
+coverage.xml
+
+# Documentation builds
+docs/_build/
+site/
+site_build/
+docs_build/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# IDEs
+.idea/
+.vscode/
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# Local files
+test.db
+log.txt
+.cache/
+
+# Deployment / tooling
+.netlify/
+.codspeed/
+
+# Archives / generated files
+docs.zip
+archive.zip
+
+# Vim / editor temporary files
+*~
+*.swp
+*.swo
+
+# macOS
+.DS_Store
+
+# Emacs
+.projectile

fastapi_oauth2_cookie-0.0.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,123 @@
+# 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/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-0.0.1/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-0.0.1/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/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fastapi-oauth2-cookie"
+version = "0.0.1"
+description = "A lightweight FastAPI library for OAuth2 via HttpOnly Cookies and CSRF headers."
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Denis Lyovin", email = "DOS1918@proton.me" },
+]
+dependencies = [
+    "fastapi>=0.95.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "httpx2>=2.12.0",
+    "fastapi[standard]>=0.141.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/D1918/fastapi-oauth2-cookie.git"
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "1.md",
+    "uv.lock",
+    ".gitignore",
+    "tests/",
+    "dev/"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["fastapi_oauth2_cookie"]