A comprehensive implementation of 5 mini-projects that teach TOTP (Time-based One-Time Password) authentication from scratch, culminating in a full-featured Google Authenticator clone.

This project implements all 5 educational mini-projects:

1. TOTP Generator - Generate 6-digit codes from Base32 secrets
2. TOTP Verifier - Backend validation with time window tolerance
3. Login System - Full authentication with 2FA support
4. QR Cloner - Decode and extract secrets from QR codes
5. Clock Sync Detector - Detect and compensate for time drift

CopyGoogleAuth/
├── backend/           # FastAPI Python backend
│   ├── app/
│   │   ├── api/      # API routes
│   │   ├── core/     # Security, config, exceptions
│   │   ├── models/   # Database models
│   │   ├── schemas/  # Pydantic schemas
│   │   └── services/ # Business logic
│   └── tests/        # Unit & integration tests
├── frontend/          # React + TypeScript + Tailwind
│   ├── src/
│   │   ├── components/  # React components
│   │   ├── pages/       # Page components
│   │   └── hooks/       # Custom React hooks
└── docker-compose.yml

• Docker & Docker Compose
• Node.js 20+ (for local frontend development)
• Python 3.11+ (for local backend development)

# Clone and start everything
cd CopyGoogleAuth
docker-compose up

# Access:
# - Frontend: http://localhost:3000
# - Backend API: http://localhost:8000
# - API Docs: http://localhost:8000/docs

Backend:

cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload

Frontend:

cd frontend
npm install
npm run dev

• Endpoint: GET /api/v1/totp/generate
• Input: Base32 secret
• Output: 6-digit code, expiration timestamp
• Learning: RFC 6238 TOTP implementation

• Endpoint: POST /api/v1/totp/verify
• Input: Code, secret, window tolerance
• Output: Valid/Invalid, window used
• Learning: Time window validation (-1, 0, +1 steps)

• Features: Registration, JWT auth, 2FA setup/verify
• Endpoints:
  • POST /api/v1/auth/register
  • POST /api/v1/auth/login
  • GET /api/v1/auth/2fa/setup
  • POST /api/v1/auth/2fa/verify
• Learning: Complete auth flow with QR provisioning

• Endpoint: POST /api/v1/qr/decode
• Input: QR image or provisioning URI
• Output: Extracted secret, issuer, account info
• Learning: Why QR codes must be kept secret

• Endpoint: POST /api/v1/totp/sync
• Input: 2+ consecutive codes, secret
• Output: Drift detected, offset, adjusted window
• Learning: Real-world clock synchronization

1. Password Hashing: bcrypt with salt
2. JWT Tokens: Short-lived access tokens + refresh tokens
3. 2FA Secrets: Encrypted at rest
4. Rate Limiting: Should be added for production
5. HTTPS: Required for production deployment

# Backend tests
cd backend
pytest

# Run with coverage
pytest --cov=app tests/

See docs/DEPLOYMENT.md for detailed production deployment instructions.

• ARCHITECTURE.md - System design and data flow
• API.md - Complete API reference
• DEPLOYMENT.md - Production deployment guide
• TESTING.md - Testing procedures

• RFC 6238 - TOTP
• RFC 4226 - HOTP
• Google Authenticator Wiki

MIT License - Educational Use