Metadata-Version: 2.4
Name: fastapi-lightauth
Version: 0.1.0
Summary: A lightweight JWT authentication library for FastAPI and SQLAlchemy.
Author: Bowlstalls
License-Expression: MIT
Project-URL: Repository, https://github.com/Bowlstalls/fastapi-lightauth
Project-URL: Issues, https://github.com/Bowlstalls/fastapi-lightauth/issues
Keywords: fastapi,authentication,jwt,sqlalchemy,asyncio
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: pydantic>=2
Requires-Dist: PyJWT>=2.8.0
Requires-Dist: bcrypt>=4.1.0
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Provides-Extra: example
Requires-Dist: aiosqlite>=0.20; extra == "example"
Dynamic: license-file

# fastapi-lightauth

A lightweight JWT authentication library for FastAPI and SQLAlchemy.
Built with simplicity in mind for small and medium FastAPI projects.

Features:
* JWT authentication
* Secure password hashing with bcrypt
* User registration and login endpoints
* Current-user dependency injection
* Extendable SQLAlchemy user models
* Extendable Pydantic schemas
* Async SQLAlchemy support

## Installation

```bash
pip install fastapi-lightauth
```

---

## Quick start

### 1. Define your user model

LightAuth requires 'UserMixin', but everything else is completely up to you

```python
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from lightauth import UserMixin


class Base(DeclarativeBase):
  pass


class User(UserMixin, Base):
  __tablename__ = "users"

  extra_stuff: Mapped[str] = mapped_column(default="no extra stuff here")
```

---

### 2. Optional: extend your response schema

You can add fields that you want returned in API responses:

```python
from lightauth.schemas import UserReadBase


class UserReadSchema(UserReadBase):
  extra_stuff: str
```

---

### 3. Create a session dependency

```python
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
from typing import AsyncGenerator, Any

engine = create_async_engine("sqlite+aiosqlite:///:memory:")
session_maker = async_sessionmaker(engine)


async def get_session() -> AsyncGenerator[AsyncSession, Any]:
    async with session_maker() as session:
        yield session
```

---

### 4. Set up LightAuth

```python
from lightauth import LightAuth

auth = LightAuth[User](
  secret="your-secret-key",
  model=User,
  get_session=get_session,
)
```
Optionally configure token lifespan via `token_lifespan_days`

---

### 5. Add the router

```python
from lightauth import get_auth_router
from lightauth.schemas import UserCreateBase

app.include_router(
  get_auth_router(
    auth,
    UserReadSchema,
    UserCreateBase,
  )
)
```

---

## Using authentication in routes

You protect routes using a FastAPI dependency:

```python
from fastapi import Depends

@app.get("/hello")
async def hello(user: User = Depends(auth.current_user)):
    return f"Hello, {user.username}"
```

That dependency will:

* read the Bearer token
* validate the JWT
* load the user from the database
* inject the full SQLAlchemy user object

---

## Endpoints

### Register

```
POST /auth/register
```

```json
{
  "username": "...",
  "password": "..."
}
```

Returns the created user.

---

### Login

```
POST /auth/login
```

```json
{
  "username": "...",
  "password": "..."
}
```

Returns:

```json
{
  "access_token": "eyJ...",
  "token_type": "Bearer"
}
```

---

### Current user

```
GET /auth/me
```

Requires:

```
Authorization: Bearer <token>
```

Returns the current user.

---

## Security notes

* Passwords are hashed using bcrypt
* JWT tokens include:
  * `sub` → user ID
  * `exp` → expiration timestamp
* Default token lifetime: 30 days

---

## License

MIT
