README.md

metadata

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:

docker compose up --build

• React Frontend URL: http://localhost:5173
• FastAPI Docs URL: http://localhost:8000/docs

To stop the containers:

docker compose down

---

Option 2: Running Locally

1. Backend Setup

1. Navigate to the backend directory:

   cd backend
   

2. Create and activate a Python virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate
   

3. Install dependencies:

   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):

   uvicorn main:app --reload
   

2. Frontend Setup

1. In a new terminal, navigate to the frontend directory:

   cd frontend
   

2. Install npm packages:

   npm install
   

3. Run the development server:

   npm run dev
   

---

📧 Configuring SMTP Server for Real Emails

To make the app send actual emails to your users, edit the backend/.env file:

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

     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.