summary.md

Auth-System-SMTP — Summary of Important Questions & Concepts

---

1. Project Overview

Q: What is this project? A full-stack authentication system with email verification and password reset using SMTP. Built with FastAPI (backend) + React (frontend).

Q: What is the tech stack?

Layer	Technology
Backend	FastAPI, SQLAlchemy, SQLite, bcrypt, JWT (python-jose)
Frontend	React 18, Vite, Axios, React Router v6
Email	Python smtplib (STARTTLS on port 587)
Auth	Dual JWT tokens (access + refresh), bcrypt hashing, OTP verification

---

2. Authentication Flow

Q: What happens during registration?

1. User submits username, email, password
2. Backend validates password strength (≥8 chars, 1 letter, 1 digit)
3. Password is hashed with bcrypt
4. A 6-digit OTP is generated and stored in verification_code
5. OTP is sent via email (SMTP or console fallback)
6. User is redirected to /verify-email

Q: How does email verification work?

1. User enters email + 6-digit OTP
2. Backend matches OTP against verification_code column
3. On success: is_verified = True, verification_code = None
4. User can now log in

Q: What happens during login?

1. User submits username + password (OAuth2 form body)
2. Backend validates credentials with bcrypt.checkpw()
3. Checks is_active and is_verified flags
4. Issues two JWT tokens:
   • Access token: 30-minute expiry, type "access"
   • Refresh token: 7-day expiry, type "refresh"
5. Frontend stores both in sessionStorage

Q: How does token refresh work?

1. Axios interceptor detects a 401 response
2. Sends refresh token to /auth/refresh
3. Backend validates refresh token (not revoked, valid type, user active)
4. Revokes old refresh token (adds to revoked_tokens table)
5. Issues new access + refresh token pair (token rotation)
6. Original request is retried with new token

Q: How does logout work?

1. Frontend sends refresh token to /auth/logout
2. Backend inserts both tokens into revoked_tokens table
3. Frontend clears sessionStorage and resets user state

---

3. Password Reset Flow

Q: How does forgot password work?

• Step 1: User enters email → backend generates 6-digit OTP → stores in reset_code → sends via email
• Step 2: User enters email + code + new password → backend validates OTP → hashes new password → clears reset_code

---

4. JWT Token Structure

Q: What claims are in the access token?

{
  "sub": "<user_id>",
  "email": "<email>",
  "type": "access",
  "exp": "<datetime>"
}

Q: What claims are in the refresh token?

{
  "sub": "<user_id>",
  "type": "refresh",
  "exp": "<datetime>"
}

Q: Why use two token types?

• Access token: Short-lived, used for API requests
• Refresh token: Long-lived, used only to get new access tokens
• Separation limits exposure if a token is compromised

---

5. Database Schema

Q: What tables exist?

users Table

Column	Type	Purpose
id	Integer (PK)	User ID
username	String (UNIQUE)	Login username
email	String (UNIQUE)	User email
password	String	bcrypt hashed password
is_active	Boolean	Account enabled/disabled
role	String	"user" or "admin"
created_at	DateTime	Registration timestamp
is_verified	Boolean	Email verified flag
verification_code	String (nullable)	Active registration OTP
reset_code	String (nullable)	Active password reset OTP

revoked_tokens Table

Column	Type	Purpose
id	Integer (PK)	Record ID
token	String (UNIQUE)	Revoked JWT string
revoked_at	DateTime	When it was revoked
expires_at	DateTime	Original token expiry

---

6. API Endpoints

Q: What are all the endpoints?

Auth Routes (/auth)

Method	Endpoint	Description
POST	/auth/register	Register new user
POST	/auth/verify-email	Verify email with OTP
POST	/auth/login	Login, returns JWT tokens
POST	/auth/forgot-password	Request password reset OTP
POST	/auth/reset-password	Reset password with OTP
POST	/auth/refresh	Refresh access token
POST	/auth/logout	Revoke tokens

User Routes

Method	Endpoint	Description
GET	/me	Get current user profile
PUT	/me	Update profile
DELETE	/me	Delete own account
GET	/admin/users	List all users (admin only)

---

7. Security Concepts

Q: How are passwords stored?

• Hashed with bcrypt using bcrypt.gensalt() + bcrypt.hashpw()
• Verified with bcrypt.checkpw() (constant-time comparison)

Q: What is token revocation?

• Tokens are inserted into revoked_tokens table
• Every authenticated request checks this table
• If token is found → 401 Unauthorized

Q: What is token rotation?

• On each refresh, the old refresh token is revoked
• A new access + refresh token pair is issued
• Prevents long-lived refresh token abuse

Q: How is rate limiting implemented?

• Custom HTTP middleware in FastAPI
• Max 60 requests per 60-second window per client IP
• Returns HTTP 429 when exceeded

Q: How is CORS configured?

• Allows only http://localhost:5173 and http://localhost:3000
• Allows credentials, all methods, all headers

Q: What is the SMTP fallback mechanism?

• If SMTP credentials are empty/missing → prints OTP to console
• If SMTP sending fails → falls back to console printing
• Allows development without a real mail server

---

8. Frontend Architecture

Q: How does the frontend manage auth state?

• AuthContext (React Context) holds user state
• On mount, checks sessionStorage for access_token
• Calls GET /me to validate and hydrate user state
• If validation fails → clears session

Q: How does the axios interceptor work?

• Request interceptor: Attaches Authorization: Bearer <token> from sessionStorage
• Response interceptor: On 401 → attempts refresh → retries request → on failure redirects to /login

Q: What is the ProtectedRoute component?

• Wraps routes that require authentication
• Checks user from AuthContext
• Redirects to /login if not authenticated
• Shows loading spinner while checking

---

9. Environment Variables

Variable	Default	Purpose
SECRET_KEY	super_secret_dev_key_change_me_123456789	JWT signing key
ALGORITHM	HS256	JWT algorithm
ACCESS_TOKEN_EXPIRE_MINUTES	30	Access token TTL
REFRESH_TOKEN_EXPIRE_DAYS	7	Refresh token TTL
DATABASE_URL	sqlite:///./users.db	Database connection
SMTP_SERVER	""	SMTP host (empty = simulation)
SMTP_PORT	587	SMTP port
SMTP_USER	""	SMTP login (empty = simulation)
SMTP_PASSWORD	""	SMTP password (empty = simulation)

---

10. Important Security Notes & Weaknesses

Q: What security concerns exist?

1. .env contains real Gmail credentials — must not be committed to version control
2. SECRET_KEY is a weak dev key — must be changed in production
3. OTP generated with random.choices (non-cryptographic PRNG) — should use secrets module
4. forgot_password endpoint may expose whether an email exists (different error responses)
5. No per-account brute-force protection — only global rate limiter
6. No .gitignore file — secrets could be accidentally committed

Q: What should be improved for production?

1. Use a production database (PostgreSQL, MySQL) instead of SQLite
2. Add .gitignore to exclude .env, users.db, __pycache__, node_modules
3. Use secrets module for OTP generation
4. Implement account lockout after failed login attempts
5. Add email rate limiting (prevent OTP spam)
6. Use asymmetric JWT signing (RS256) for microservice architectures
7. Add HTTPS enforcement
8. Implement CSRF protection
9. Add comprehensive logging and monitoring

---

11. Key Files Reference

File	Purpose
backend/main.py	FastAPI app entry, CORS, rate limiting, middleware
backend/auth.py	Password hashing, JWT creation, SMTP email sending
backend/models.py	SQLAlchemy ORM models (User, RevokedToken)
backend/schemas.py	Pydantic request/response schemas
backend/config.py	Centralized config from .env
backend/database.py	SQLAlchemy engine, session, Base
backend/routes/auth_routes.py	Auth endpoints
backend/routes/user_routes.py	User profile + admin endpoints
frontend/src/context/AuthContext.jsx	Auth state management
frontend/src/api/axios.js	Axios instance with interceptors
frontend/src/components/ProtectedRoute.jsx	Route guard
frontend/src/pages/Login.jsx	Login form
frontend/src/pages/Register.jsx	Registration form
frontend/src/pages/VerifyEmail.jsx	OTP verification form
frontend/src/pages/Dashboard.jsx	User dashboard + admin panel