Metadata-Version: 2.4
Name: assem
Version: 0.3.0
Summary: A flexible and secure JWT authentication framework for FastAPI applications
Home-page: https://github.com/BagzhanKarl/assem-auth
Author: Bagzhan Karl
Author-email: bagzhankarl@gmail.com
Project-URL: Bug Tracker, https://github.com/BagzhanKarl/assem-auth/issues
Project-URL: Documentation, https://github.com/BagzhanKarl/assem-auth
Project-URL: Source Code, https://github.com/BagzhanKarl/assem-auth
Keywords: auth,authentication,FastAPI,OAuth2,JWT,security,Fastapi jwt
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.68.0
Requires-Dist: pydantic>=1.8.0
Requires-Dist: pyjwt
Requires-Dist: starlette>=0.14.2
Provides-Extra: dev
Requires-Dist: pytest>=6.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.15.0; extra == "dev"
Requires-Dist: black>=21.5b2; extra == "dev"
Requires-Dist: isort>=5.9.1; extra == "dev"
Requires-Dist: mypy>=0.910; extra == "dev"
Requires-Dist: flake8>=3.9.2; extra == "dev"
Requires-Dist: uvicorn>=0.14.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Assem

[![PyPI version](https://img.shields.io/pypi/v/assem.svg)](https://pypi.org/project/assem/)
[![Python versions](https://img.shields.io/pypi/pyversions/assem.svg)](https://pypi.org/project/assem/)
[![License](https://img.shields.io/github/license/BagzhanKarl/assem-auth.svg)](https://github.com/BagzhanKarl/assem-auth/blob/master/LICENSE)

A flexible and secure JWT authentication framework for FastAPI applications.

## Features

- 🔒 JWT-based authentication with refresh tokens
- 🛡️ CSRF protection
- 🍪 Secure cookie handling
- 🔄 Token refresh mechanism
- ⏲️ Configurable token expiration
- 🔍 Easy token validation and user identification
- 📦 Simple integration with FastAPI

## Installation

```bash
pip install assem
```

## Quick Start

```python
from fastapi import FastAPI, Depends, Request, Response
from assem import AssemAUTH

app = FastAPI()

# Initialize authentication with default settings
auth = AssemAUTH(secret_key="your-secret-key")

# Login endpoint
@app.post("/login")
async def login(username: str, password: str, response: Response):
    # Validate user credentials (replace with your authentication logic)
    if username == "demo" and password == "password":
        user_id = "user123"
        
        # Create tokens (access, refresh, csrf)
        access_token, refresh_token, csrf_token = auth.create_tokens(
            user_id, 
            additional_data={"role": "admin", "name": "Demo User"}
        )
        
        # Set tokens in cookies
        auth.set_tokens_in_cookies(response, access_token, refresh_token, csrf_token)
        
        return {"message": "Login successful"}
    else:
        return {"message": "Invalid credentials"}

# Protected endpoint using dependency
@app.get("/me")
async def get_current_user(user_data = Depends(auth.get_user_data_dependency())):
    return {
        "user_id": user_data["sub"],
        "role": user_data.get("role"),
        "name": user_data.get("name")
    }

# Refresh token endpoint
@app.post("/refresh")
async def refresh_token(request: Request, response: Response):
    result = auth.refresh_access_token(request, response)
    return result

# Logout endpoint
@app.post("/logout")
async def logout(request: Request, response: Response):
    result = auth.logout(request, response)
    return result
```

## Advanced Usage

### Custom Token Configuration

```python
auth = AssemAUTH(
    secret_key="your-secret-key",
    algo="HS256",
    access_token_expire_minutes=15,
    refresh_token_expire_days=7,
    token_issuer="your-api",
    token_audience=["your-frontend"],
    secure_cookies=True,
    cookie_domain="yourdomain.com",
    enable_csrf_protection=True,
    enable_jti=True
)
```

### Verification-Only Mode

You can create an instance that only verifies tokens (useful for microservices):

```python
from assem import AssemAUTH, ServiceMode

auth_verifier = AssemAUTH(
    secret_key="your-secret-key",
    service_mode=ServiceMode.VERIFY_ONLY
)
```

### Working with User Data

The framework provides multiple ways to access user data:

```python
# Get just the user ID
@app.get("/user-id")
async def get_user_id(request: Request):
    user_id = auth.get_current_user(request)
    return {"user_id": user_id}

# Get a specific field from the token
@app.get("/user-role")
async def get_user_role(request: Request):
    role = auth.get_user_data(request, key="role")
    return {"role": role}

# Get all user data from token
@app.get("/user-all")
async def get_all_user_data(request: Request):
    all_data = auth.get_user_data(request)
    return all_data
```

## License

[MIT License](LICENSE)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.
