--- 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.