Spaces:
Running
Running
| 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. | |