Metadata-Version: 2.4
Name: fastapi-login-shield
Version: 0.1.9
Summary: Protect FastAPI login endpoints from brute-force attacks using middleware
Project-URL: Homepage, https://mrmrprogrammer.ir
Project-URL: Documentation, https://github.com/MrMrProgrammer/fastapi-login-shield#readme
Project-URL: Repository, https://github.com/MrMrProgrammer/fastapi-login-shield
Project-URL: Issues, https://github.com/MrMrProgrammer/fastapi-login-shield/issues
Author-email: Seyed Mohammadreza Hashemi <mrmrprogrammer@gmail.com>
Maintainer-email: MrMrProgrammer <mrmrprogrammer@gmail.com>
License: MIT
Keywords: brute-force,fastapi,login-protection,middleware,rate-limiter,security
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Security
Requires-Python: >=3.7
Requires-Dist: fastapi>=0.95.0
Requires-Dist: starlette>=0.27.0
Description-Content-Type: text/markdown

# fastapi-login-shield

A simple and lightweight middleware to protect your FastAPI login endpoints from brute-force attacks using per-IP rate limiting with exponential backoff.

## Features

- Per-IP login attempt tracking
- Exponential backoff for repeated failed attempts
- Auto-expiry of old IP data (default: 15 minutes)
- Non-intrusive integration via Starlette middleware
- Customizable login path and expiration timeout

## Installation

```bash
pip install fastapi-login-shield
```

## Usage

### 1. Add the middleware to your FastAPI app

```python
from fastapi import FastAPI
from fastapi_login_shield.middleware import LoginShieldMiddleware

app = FastAPI()

# Add the middleware
app.add_middleware(LoginShieldMiddleware, login_path="/login")
```

### 2. Example login endpoint

```python
from fastapi import HTTPException, Request

@app.post("/login")
async def login(request: Request):
    # Simulate authentication logic
    form = await request.json()
    username = form.get("username")
    password = form.get("password")

    if username != "admin" or password != "secret":
        raise HTTPException(status_code=401, detail="Invalid credentials")

    return {"message": "Login successful!"}
```

## How It Works

- The middleware intercepts all requests to the specified login path.
- If the response is a failed login (`401` or `403`), it increments the attempt counter for the client IP.
- If the count exceeds a threshold (e.g., 3), it applies an exponential delay (`2^count` seconds, up to 10 minutes).
- If a login succeeds (`2xx` response), the counter for that IP is reset.
- IPs are automatically cleaned from memory if inactive for a configurable duration (default: 900 seconds).

## Configuration

You can customize the login path and expiration time like this:

```python
app.add_middleware(
    LoginShieldMiddleware,
    login_path="/auth/login",
    expire_seconds=600  # expire IP data after 10 minutes
)
```

## Security Notes

- This middleware does not block login attempts permanently, it only applies temporary delays.

## License

MIT License

## Author

[Developed by MrMrProgrammer (Seyed Mohammadreza Hashemi)](https://mrmrprogrammer.ir)
