Multi-Factor Authentication (MFA) Implementation in Node.js (TypeScript) - GraphQL & REST API

This project provides an open-source Node.js implementation of multi-factor authentication (MFA) in both GraphQL and REST APIs using TypeScript. It includes a variety of common MFA methods such as SMS-based OTP, Authenticator Apps, FIDO2/U2F, push notifications, biometric authentication, backup codes, and email-based authentication.

Features

1. SMS-Based Authentication (OTP): Implements one-time password generation and verification via SMS.
2. Authenticator Apps: Supports time-based one-time passwords (TOTP) through apps like Google Authenticator and Authy.
3. Hardware Security Keys (FIDO2/U2F): Provides hardware-based authentication using security keys like YubiKey.
4. Biometric Authentication: Integrates platform-level biometric authentication using Face ID or Touch ID.
5. Push Notification-Based MFA: Utilizes push notifications for approval-based authentication.
6. Backup Codes: Allows users to generate backup codes in case they lose access to primary MFA methods.
7. Email-Based MFA: Sends a one-time password via email for secondary authentication.
8. Platform-Specific MFA: GitHub-like MFA via mobile or desktop notifications.

Table of Contents

1. Installation
2. Configuration
3. Endpoints
   • SMS-Based OTP
   • Authenticator Apps
   • Hardware Security Keys
   • Biometric Authentication
   • Push Notification-Based MFA
   • Backup Codes
   • Email-Based MFA
4. GraphQL API
5. REST API
6. Error Handling
7. License

Installation

Prerequisites

• Node.js v14+ (LTS)
• TypeScript v4+
• PostgreSQL (or any supported database)
• Redis (optional, for caching or sessions)
• Twilio (or another SMS gateway) for SMS-based OTP
• Authy or similar service for authenticator app - functionality
• WebAuthn/FIDO2 libraries for hardware key support

Steps

1. Clone the Repository:

   git clone https://github.com/your-repo/mfa-implementation-nodejs.git
   cd mfa-implementation-nodejs

2. Install Dependencies:

   npm install

3. Setup Environment Variables: Create a .env file at the root of your project with the following:

   DATABASE_URL=your_postgresql_database_url
   TWILIO_ACCOUNT_SID=your_twilio_account_sid
   TWILIO_AUTH_TOKEN=your_twilio_auth_token
   TWILIO_PHONE_NUMBER=your_twilio_phone_number
   AUTHY_API_KEY=your_authy_api_key
   FIDO2_RP_ID=your_fido2_rp_id
   FIDO2_RP_NAME=your_fido2_rp_name
   PUSH_NOTIFICATION_API_KEY=your_push_notification_key
   EMAIL_SERVICE_API_KEY=your_email_service_key
   

4. Database Migration:

    npx prisma migrate dev

5. Start the Server:

    npm run dev

Configuration

Environment Variables

The application relies on the following environment variables:

• DATABASE_URL: Connection string for PostgreSQL or any other relational database.
• TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER: Required for sending SMS-based OTPs.
• AUTHY_API_KEY: For integrating authenticator apps like Authy.
• FIDO2_RP_ID and FIDO2_RP_NAME: Relying party information for WebAuthn-based hardware security keys.
• PUSH_NOTIFICATION_API_KEY: Used for sending push notifications.
• EMAIL_SERVICE_API_KEY: Email service credentials to send OTPs for email-based MFA.

Endpoints

SMS-Based OTP

REST API

• Endpoint: /api/v1/mfa/sms/send
• Method: POST
• Payload:

{
  "phone": "+1234567890"
}

• Response:

{
  "message": "OTP sent successfully"
}

• Endpoint: /api/v1/mfa/sms/verify
• Method: POST
• Payload:

{
  "phone": "+1234567890",
  "otp": "123456"
}

• Response:

{
  "message": "OTP verified successfully"
}

Authenticator Apps

REST API

• Endpoint: /api/v1/mfa/authenticator/generate
• Method: GET
• Response:

{
  "secret": "YOUR_SECRET",
  "qrCode": "BASE64_ENCODED_QR_CODE"
}

• Endpoint: /api/v1/mfa/authenticator/verify
• Method: POST
• Payload:

{
  "token": "123456"
}

• Response:

{
  "message": "Authenticator token verified successfully"
}

Hardware Security Keys (FIDO2/U2F)

REST API

• Endpoint: /api/v1/mfa/webauthn/register

• Method: POST

• Payload:

{
  "userId": "your_user_id"
}

• Response:

{
  "publicKeyCredentialOptions": { /* FIDO2 options for registration */ }
}

• Endpoint: /api/v1/mfa/webauthn/verify
• __Method: POST
• Payload:

{
  "userId": "your_user_id",
  "authenticatorResponse": {/* WebAuthn response */}
}

Biometric Authentication

GraphQL API

• Mutation:

mutation BiometricLogin($input: BiometricLoginInput!) {
  biometricLogin(input: $input) {
    token
    user {
      id
      email
    }
  }
}

• Payload:

{
  "input": {
    "fingerprint": "base64_fingerprint_data"
  }
}

Push Notification-Based MFA

REST API

• Endpoint: /api/v1/mfa/push
• Method: POST
• Payload:

{
  "userId": "your_user_id"
}

• Response:

{
  "message": "Push notification sent"
}

Backup Codes

REST API

• Endpoint: /api/v1/mfa/backup/generate

• Method: GET

• Response:

{
  "backupCodes": ["code1", "code2", "code3"]
}

• Endpoint: /api/v1/mfa/backup/verify

• Method: POST

• Payload:

{
  "code": "backup_code"
}

• Response:

{
  "message": "Backup code verified successfully"
}

Email-Based MFA

REST API

• Endpoint: /api/v1/mfa/email/send

• Method: POST

• Payload:

{
  "email": "user@example.com"
}

• Response:

{
  "message": "Email OTP sent successfully"
}

• Endpoint: /api/v1/mfa/email/verify
• Method: POST
• Payload:

{
  "email": "user@example.com",
  "otp": "123456"
}

• Response:

{
  "message": "Email OTP verified successfully"
}

GraphQL API

This project supports GraphQL for seamless integration.

Example Query

mutation SendOTP($input: SendOTPInput!) {
  sendOTP(input: $input) {
    success
    message
  }
}

Example Query

mutation VerifyOTP($input: VerifyOTPInput!) {
  verifyOTP(input: $input) {
    success
    message
  }
}

REST API

This project also supports a fully functional RESTful API for easier integration into various services.

Error Handling

All requests return standardized error codes and messages to ensure consistent handling on the client side.

License

This project is licensed under the MIT License.