2FA Authentication Service¶

What is this?¶

A production-ready Two-Factor Authentication service that you can integrate into your applications. Provides enterprise-grade 2FA capabilities via REST API with a showcase frontend for testing.

Key Features¶

• Multiple 2FA Methods: TOTP, SMS, Email, Backup Codes
• Trusted Devices: Skip 2FA on trusted devices for 30 days
• API Key Management: Secure third-party integration
• Webhook Support: Real-time event notifications
• Zero-Budget Option: Deploy for free with TOTP only
• Full Test Coverage: 80%+ test coverage with comprehensive test suite

Quick Links¶

Supported 2FA Methods¶

Architecture Overview¶

graph TB
    subgraph "Client Applications"
        A[Your Application]
        G[Frontend Demo]
    end

    subgraph "API Layer"
        B[2FA Backend<br/>Express.js + TypeScript]
    end

    subgraph "Data Storage"
        C[(PostgreSQL<br/>User & Session Data)]
        D[(Redis<br/>Cache & Rate Limiting)]
    end

    subgraph "External Services"
        E[Twilio SMS]
        F[SMTP Email]
    end

    A -->|REST API| B
    G -.->|Optional Demo| B
    B --> C
    B --> D
    B --> E
    B --> F

    style A fill:#667eea,stroke:#764ba2,stroke-width:3px,color:#fff
    style B fill:#84fab0,stroke:#8fd3f4,stroke-width:3px,color:#333
    style C fill:#fa709a,stroke:#fee140,stroke-width:3px,color:#fff
    style D fill:#fa709a,stroke:#fee140,stroke-width:3px,color:#fff
    style E fill:#30cfd0,stroke:#330867,stroke-width:3px,color:#fff
    style F fill:#30cfd0,stroke:#330867,stroke-width:3px,color:#fff
    style G fill:#667eea,stroke:#764ba2,stroke-width:2px,color:#fff,stroke-dasharray: 5 5

Backend: Express.js + TypeScript + Prisma + Redis Frontend: Next.js 15 + Tailwind CSS Database: PostgreSQL + Redis Security: Argon2 hashing, JWT tokens, rate limiting

Detailed Architecture

Integration Approaches¶

Option 1: Direct API Integration (Recommended)¶

Integrate the 2FA service into your existing application by calling the REST API endpoints.

# Start 2FA service
docker-compose up -d

# Call from your app
curl -X POST http://localhost:3001/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","username":"user","password":"SecurePass123!"}'

API Integration Guide

Option 2: SDK Integration (Coming Soon)¶

Use our SDK to simplify integration (roadmap Phase 8).

import { TwoFactorAuth } from '@Ilia01/2fa-sdk';

const tfa = new TwoFactorAuth({ apiUrl: 'http://localhost:3001/api' });
await tfa.setupTOTP(userId);

Tech Stack¶

Project Status¶

• Phase 1-4: Backend API Service (User auth, TOTP, SMS, Email, Backup codes)
• Phase 5: Showcase Frontend (Next.js with dark theme, 2FA wizard)
• Phase 6: Service Enhancements (API keys, webhooks, health checks, Docker)
• Phase 7: Admin Dashboard (User management, audit logs, analytics)
• Phase 8: Client SDK (NPM package, React hooks, Python client)

Full Roadmap

Security¶

This service implements industry-standard security practices:

• ✅ Argon2id password hashing
• ✅ JWT authentication with refresh tokens
• ✅ Rate limiting on all sensitive endpoints
• ✅ CSRF protection
• ✅ Helmet security headers
• ✅ Input validation and sanitization
• ✅ SQL injection prevention (parameterized queries)
• ✅ Audit logging for security events

Community & Support¶

• Documentation: You're reading it!
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Contributing: Contributing Guide

License¶

This project is licensed under the MIT License - see the LICENSE file for details.