SecureAuth+ TOTP Authentication System

A complete implementation of a secure TOTP (Time-based One-Time Password) authentication system with Flutter mobile app and Go backend.

📋 Features

• ✅ Offline TOTP generation (5-minute intervals)
• 🔐 Secure secret storage with flutter_secure_storage
• 🔄 Secret rotation on demand
• 📱 QR code setup for authenticator apps
• 🛡️ JWT-based authentication
• 📊 SQLite database storage
• 🔍 Audit logging
• ⏱️ Time drift tolerance (±5 minutes)

🚀 Quick Start

Prerequisites

• Go 1.21 or higher
• Flutter 3.0 or higher
• SQLite3

Backend Setup (Go)

1. Create project directory:

mkdir totp-auth-backend
cd totp-auth-backend

2. Initialize Go module:

go mod init totp-auth-backend

3. Copy the go.mod content and main.go files from the artifacts above

4. Install dependencies:

go mod tidy

5. Run the server:

go run main.go

The server will start on http://localhost:8080

Flutter App Setup

1. Create Flutter project:

flutter create totp_auth_app
cd totp_auth_app

2. Replace pubspec.yaml with the provided content

3. Get dependencies:

flutter pub get

4. Create the directory structure:

mkdir -p lib/models lib/services lib/screens

5. Copy all the Flutter files:

   • lib/main.dart
   • lib/models/user.dart
   • lib/services/auth_service.dart
   • lib/services/totp_service.dart
   • lib/screens/auth_screen.dart
   • lib/screens/home_screen.dart

6. Run the app:

# For Android
flutter run

# For iOS
flutter run -d ios

# For web (development)
flutter run -d chrome

Android Permissions

Add to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.USE_FINGERPRINT" />
<uses-permission android:name="android.permission.USE_BIOMETRIC" />

iOS Permissions

Add to ios/Runner/Info.plist:

<key>NSFaceIDUsageDescription</key>
<string>Use Face ID to authenticate</string>
<key>NSCameraUsageDescription</key>
<string>Camera access for QR code scanning</string>

🧪 Testing with Postman

1. Import the Postman collection using the JSON file provided above
2. Set the base URL to http://localhost:8080
3. Test the API endpoints in order:

Testing Flow:

1. Health Check - Verify server is running
2. Register User - Create a new user account
3. Login User - Get authentication token
4. Get TOTP Setup - Retrieve QR code and secret
5. Generate TOTP Code - Get current valid code
6. Verify TOTP Code - Test code validation
7. Rotate TOTP Secret - Update secret key

📱 Using the Mobile App

Registration Flow:

1. Open the app
2. Switch to "Register" tab
3. Enter username and password
4. Scan the QR code with your preferred authenticator app
5. Continue to the main app

Login Flow:

1. Switch to "Login" tab
2. Enter your credentials
3. Access the TOTP dashboard

Main Features:

• Current TOTP Code: View and copy current 6-digit code
• Auto-refresh: Code automatically updates every 5 minutes
• Manual verification: Test codes against the server
• QR Code display: View setup QR code anytime
• Secret rotation: Generate new secret key
• Secure logout: Clear all stored data

🔧 Configuration

Backend Configuration:

• JWT Secret: Change jwtSecret in main.go for production
• Database: SQLite file created as totp_auth.db
• TOTP Interval: 300 seconds (5 minutes)
• Port: 8080 (configurable)

Flutter Configuration:

• API Base URL: Update in auth_service.dart for production
• Storage: Uses flutter_secure_storage for encrypted storage
• Biometrics: Optional local authentication

🛡️ Security Features

Backend Security:

• Password hashing with bcrypt
• JWT token-based authentication
• HMAC-SHA1 for TOTP generation
• Input validation and sanitization
• Rate limiting ready (Redis integration)
• Audit logging for all auth attempts

Mobile Security:

• Encrypted secret storage
• Secure HTTP communications
• Local authentication (biometrics)
• No sensitive data in app logs
• Memory protection for secrets

📊 Database Schema

Users Table:

CREATE TABLE users (
    id TEXT PRIMARY KEY,
    username TEXT UNIQUE NOT NULL,
    password_hash TEXT NOT NULL,
    secret TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Auth Logs Table:

CREATE TABLE auth_logs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id TEXT,
    action TEXT,
    success BOOLEAN,
    ip_address TEXT,
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users (id)
);

🔍 API Endpoints

Public Endpoints:

• GET /health - Health check
• POST /api/register - User registration
• POST /api/login - User authentication

Protected Endpoints:

• GET /api/auth/totp/setup - Get TOTP setup data
• POST /api/auth/totp/verify - Verify TOTP code
• POST /api/auth/totp/rotate - Rotate secret key
• GET /api/auth/totp/generate - Generate current code

🚀 Production Deployment

Backend:

1. Environment Variables:

export JWT_SECRET="your-256-bit-secret-key"
export DB_PATH="/path/to/production.db"
export PORT="8080"

2. Build and deploy:

go build -o totp-auth-server main.go
./totp-auth-server

Flutter:

1. Build for release:

# Android
flutter build apk --release
flutter build appbundle --release

# iOS
flutter build ios --release

2. Update API URLs in production builds

🐛 Troubleshooting

Common Issues:

1. CORS errors: Check CORS configuration in main.go
2. Database permission: Ensure write permissions for SQLite file
3. Time sync: Verify system time is synchronized
4. Token expiry: Tokens expire after 24 hours
5. Secret storage: Clear app data if storage issues occur

Debug Mode:

• Enable verbose logging in both Go and Flutter
• Check network connectivity
• Verify API endpoint accessibility
• Test with curl commands

📝 License

This project is for educational and demonstration purposes. Please review and modify security settings before production use.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

---

Note: This implementation uses a 5-minute TOTP interval for demonstration. Standard TOTP uses 30-second intervals. Adjust the interval value in both backend and frontend for different requirements.