README.md

---
title: Secure Auth System
emoji: 🛡️
colorFrom: gray
colorTo: gray
sdk: docker
app_port: 7860
pinned: false
---

# Secure Authentication System with SMTP OTP Verification

A professional, modular authentication system built with **FastAPI** (Python) and **React** (Vite + JavaScript). This version implements secure signup and recovery flows using **Email OTP (One-Time Password) Verification** via Python's built-in SMTP protocols.

---

## 🚀 Key Features

* **SMTP Email Verification**: Creates inactive users on signup, sends a 6-digit OTP to their email, and locks login attempts until the account is verified.
* **Console Fallback Mode**: If SMTP parameters are not set in `.env`, the server outputs verification codes to the console so you can test the system completely offline!
* **Secure Forgot Password Recovery**: A 2-step password recovery flow sending OTP codes to users before allowing a credential reset.
* **Modular Backend Architecture**: Clean separation of models, routes, database, schemas, configs, and helpers.
* **JWT Access & Refresh Token System**: Implements short-lived access tokens (30 minutes) and long-lived refresh tokens (7 days).
* **Automatic Token Rotation**: Refreshing your session issues a new access/refresh pair and revokes the old refresh token.
* **Server-Side Token Revocation (Logout)**: Invalides active tokens immediately on logout by storing them in a SQLite database blacklist.
* **Bcrypt Password Hashing**: Clean hashing using Python's direct `bcrypt` package to prevent dictionary attacks.
* **Request Logger & Rate Limiter**: Logs API logs to `requests.log` and restricts traffic per IP address in-memory.
* **Premium Glassmorphic UI**: Beautiful dark-mode dashboard styled with vanilla CSS and subtle micro-animations.

---

## 🛠️ Technology Stack

* **Backend**: FastAPI, SQLite (Database), SQLAlchemy (ORM), Pydantic (Data Validation), PyJWT/Jose (JWT tokens), Bcrypt, built-in Smtplib.
* **Frontend**: React, React Router Dom (Routing), Axios (Interceptors for token injection & auto-refresh).

---

## 📁 Project Structure

```
├── backend/
│   ├── config.py           # Loads .env configurations
│   ├── database.py         # SQLAlchemy engine & SQLite session setup
│   ├── models.py           # User and RevokedToken database models
│   ├── schemas.py          # Pydantic input/output validation models
│   ├── auth.py             # Password hashing, JWT dependencies & SMTP mailers
│   ├── routes/             # Authentication & user routing endpoints
│   ├── .env                # Secret configurations & SMTP details
│   ├── requirements.txt    # Python requirements
│   └── main.py             # FastAPI entry point, logger, & rate-limiting
└── frontend/
    ├── package.json        # Frontend dependencies
    ├── vite.config.js      # Vite dev server configuration
    ├── index.html          # HTML template
    └── src/
        ├── main.jsx        # Renders React root
        ├── App.jsx         # App router & AuthProvider integration
        ├── index.css       # Gorgeous dark-glass UI styling
        ├── api/axios.js    # Axios client with interceptors
        ├── components/     # Reusable components (Navbar, Guards)
        ├── context/        # Auth Context provider managing global states
        └── pages/          # Login, Register, VerifyEmail, and Dashboard views
```

---

## ⚙️ Setup and Installation

### Option 1: Running with Docker Compose (Recommended)
You can start the entire stack (React + FastAPI + SQLite) with a single command. Docker Compose will automatically read your SMTP settings from `./backend/.env`.

In the root project folder, run:
```bash
docker compose up --build
```
* **React Frontend URL**: [http://localhost:5173](http://localhost:5173)
* **FastAPI Docs URL**: [http://localhost:8000/docs](http://localhost:8000/docs)

To stop the containers:
```bash
docker compose down
```

---

### Option 2: Running Locally

#### 1. Backend Setup
1. Navigate to the backend directory:
   ```bash
   cd backend
   ```
2. Create and activate a Python virtual environment:
   ```bash
   python3 -m venv .venv
   source .venv/bin/activate
   ```
3. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```
4. Copy/create a `.env` file and fill in your SMTP credentials (or leave them blank to use console simulation logs):
   ```bash
   uvicorn main:app --reload
   ```

#### 2. Frontend Setup
1. In a new terminal, navigate to the frontend directory:
   ```bash
   cd frontend
   ```
2. Install npm packages:
   ```bash
   npm install
   ```
3. Run the development server:
   ```bash
   npm run dev
   ```

---

## 📧 Configuring SMTP Server for Real Emails

To make the app send actual emails to your users, edit the `backend/.env` file:
```env
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your_email@gmail.com
SMTP_PASSWORD=your_google_app_password
```
*Note: For security reasons, do not use your primary password. Instead, generate a secure 16-character **App Password** from your Google Account settings.*

---

## 🤗 Deploying to Hugging Face Spaces

You can easily deploy this full-stack application to Hugging Face Spaces using the **Docker** SDK! Since we set up a multi-stage Dockerfile, Hugging Face will compile your React files and run your Python API together on a single port automatically.

### Step-by-Step Deployment Guide:
1. **Create a Hugging Face Account**: Sign up at [huggingface.co](https://huggingface.co/).
2. **Create a New Space**:
   * Click your profile icon -> **New Space**.
   * Choose a **Space name** (e.g. `secure-auth-smtp`).
   * Select **Docker** as the SDK.
   * Choose the **Blank** template.
   * Click **Create Space**.
3. **Configure Secret Variables**:
   * Go to the **Settings** tab of your new Space.
   * Scroll down to **Variables and secrets**.
   * Add a new secret for each of the following:
     * `SECRET_KEY`: (Any secure random text)
     * `DATABASE_URL`: `sqlite:////app/users.db`
     * `SMTP_SERVER`: `smtp.gmail.com`
     * `SMTP_PORT`: `587`
     * `SMTP_USER`: `your_email@gmail.com`
     * `SMTP_PASSWORD`: `your_google_app_password_token`
4. **Push your Repository**:
   * Clone the Hugging Face space using git, copy all the files from this folder into it, and push:
     ```bash
     git add .
     git commit -m "Initial commit"
     git push
     ```
5. **Ready!**: The space will build automatically and show **Running** once deployed.

---

## 🛡️ License

Distributed under the MIT License. See `LICENSE` for more information.