Metadata-Version: 2.4
Name: fastauth_iq
Version: 0.1.2
Summary: A comprehensive authentication library for FastAPI with JWT and cookie support
Home-page: https://github.com/hu55ain3laa/fastauth
Author: Hussein Ghadhban
Author-email: ala.1995@yahoo.com
Keywords: fastapi,authentication,jwt,oauth2,sqlmodel,token
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Framework :: FastAPI
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Session
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.104.0
Requires-Dist: sqlmodel>=0.0.8
Requires-Dist: pydantic>=2.5.2
Requires-Dist: passlib[bcrypt]>=1.7.4
Requires-Dist: python-jose[cryptography]>=3.3.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: pyjwt>=2.6.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# FastAuth

A comprehensive authentication library for FastAPI applications with JWT-based authentication and SQLModel integration.

## Features

- **OAuth2 and JWT authentication** built-in
- **Cookie-based authentication** option
- **Token refresh mechanism** for extended sessions
- **SQLModel integration** for easy database operations
- **Ready-to-use authentication routes** with minimal setup
- **Password hashing** with bcrypt

## Installation

```bash
pip install fastauth_iq
```

Or install from source:

```bash
git clone https://github.com/hu55ain3laa/fastauth.git
cd fastauth
pip install -e .
```

## Quick Start

### 1. Create a User Model

FastAuth works with SQLModel's user model. You can use the built-in User model or create your own:

```python
from sqlmodel import SQLModel, Field

class User(SQLModel, table=True):
    id: int = Field(primary_key=True)
    username: str = Field(unique=True)
    email: str = Field(unique=True)
    hashed_password: str
    disabled: bool = Field(default=False)
```

### 2. Initialize FastAuth in Your Application

```python
from fastapi import FastAPI, Depends
from sqlmodel import create_engine, Session, SQLModel
# Import FastAuth directly - the package is installed as fastauth_iq but imported as fastauth
from fastauth import FastAuth
from myapp.models import User

# Create FastAPI app
app = FastAPI()

# Setup database
engine = create_engine("sqlite:///./app.db")

# Session dependency
def get_session():
    with Session(engine) as session:
        yield session

# Initialize FastAuth with your configuration
auth = FastAuth(
    secret_key="your-secure-secret-key",  # Use strong secret in production
    algorithm="HS256",
    user_model=User,
    engine=engine,
    use_cookie=True,  # Enable cookie-based auth (optional)
    token_url="/token",
    access_token_expires_in=30,  # minutes
    refresh_token_expires_in=7   # days
)

# Add all authentication routes automatically
auth_router = auth.get_auth_router(get_session)
app.include_router(auth_router, tags=["authentication"])
```

### 3. Protect Your Routes

```python
@app.get("/protected")
def protected_route(current_user = Depends(auth.get_current_active_user_dependency())):
    return {"message": f"Hello, {current_user.username}!"}
```

## Available Authentication Endpoints

The `get_auth_router()` method automatically adds these endpoints to your application:

- **POST /token** - Get access and refresh tokens with username/password
- **POST /token/refresh** - Get a new access token using a refresh token
- **POST /users** - Register a new user
- **GET /users/me** - Get the current authenticated user's information

## Customization Options

### Cookie-Based Authentication

Enable cookie-based authentication by setting `use_cookie=True`:

```python
auth = FastAuth(
    # ... other parameters
    use_cookie=True
)
```

### Custom Token Expiration

Set custom expiration times for tokens:

```python
auth = FastAuth(
    # ... other parameters
    access_token_expires_in=60,  # 60 minutes
    refresh_token_expires_in=30  # 30 days
)
```

### Advanced Usage: Custom Authentication Routes

You can create your own authentication routes instead of using the built-in router:

```python
@app.post("/custom-login")
async def custom_login(
    username: str, 
    password: str, 
    session: Session = Depends(get_session)
):
    user = auth.authenticate_user(username, password)
    if not user:
        raise HTTPException(status_code=401, detail="Invalid credentials")
    
    access_token = auth.create_access_token(data={"sub": user.username})
    return {"access_token": access_token, "token_type": "bearer"}
```

## Security Best Practices

1. **Always use HTTPS** in production
2. **Use a strong secret key** and keep it secure
3. **Set appropriate token expiration times**
4. **Enable httpOnly and secure flags** for cookies
5. **Consider implementing rate limiting** for authentication endpoints

## License

MIT

## Contributing

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