MFA API Service

A serverless Multi-Factor Authentication (MFA) service built with SST, supporting both app authenticator (TOTP) and email one-time password (OTP) methods.

Features

• App Authenticator: TOTP-based MFA using apps like Google Authenticator, Authy, etc.
• Email OTP: One-time password sent via email
• API Key Authentication: Secure API access with API key validation
• Device Management: Create, list, update, and delete MFA devices
• Challenge-Response Flow: Secure verification process with expiration and attempt limits
• AWS DynamoDB: Scalable data storage with automatic TTL for expired challenges
• Email Integration: Uses the @xcelsior/email service for sending OTP codes

API Endpoints

All API requests require authentication using an API key in the X-API-Key header.

Device Management

• POST /api/mfa/devices - Create a new MFA device
• GET /api/mfa/devices/{userId} - List all devices for a user
• PUT /api/mfa/devices/{deviceId} - Update device settings
• DELETE /api/mfa/devices/{deviceId} - Delete a device
• POST /api/mfa/devices/{deviceId}/verify-setup - Verify device setup

Challenge & Verification

• POST /api/mfa/challenges - Create a new MFA challenge
• POST /api/mfa/challenges/{challengeId}/verify - Verify a challenge with code

Getting Started

Prerequisites

• Node.js 18+
• AWS CLI configured
• SST CLI installed

Installation

1. Install dependencies:

npm install

2. Start development server:

npm run dev

3. Deploy to AWS:

npm run deploy

Usage Examples

1. Create App Authenticator Device

curl -X POST https://api.example.com/api/mfa/devices \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user123",
    "type": "app",
    "name": "My Phone Authenticator"
  }'

Response includes QR code and secret for setup:

{
  "data": {
    "deviceId": "device-uuid",
    "qrCodeUrl": "data:image/png;base64,...",
    "secret": "JBSWY3DPEHPK3PXP"
  }
}

2. Create Email OTP Device

curl -X POST https://api.example.com/api/mfa/devices \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user123",
    "type": "email",
    "name": "Work Email",
    "email": "[email protected]"
  }'

3. Verify Device Setup

curl -X POST https://api.example.com/api/mfa/devices/device-uuid/verify-setup \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "123456"
  }'

4. Create Challenge

curl -X POST https://api.example.com/api/mfa/challenges \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user123",
    "deviceId": "device-uuid"
  }'

5. Verify Challenge

curl -X POST https://api.example.com/api/mfa/challenges/challenge-uuid/verify \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "123456"
  }'

Configuration

Environment Variables

The service uses the following environment variables:

• POWERTOOLS_SERVICE_NAME: Service name for logging
• POWERTOOLS_METRICS_NAMESPACE: Metrics namespace
• POWERTOOLS_LOGGER_LOG_LEVEL: Log level (INFO, DEBUG, etc.)
• AWS_REGION: AWS region for deployment

Rate Limits

• Device operations: 100 requests per hour per API key
• Challenge operations: 500 requests per hour per API key
• Verification attempts: 3 attempts per challenge

Security Features

• API Key Authentication: All endpoints require valid API key
• Challenge Expiration: Challenges expire after 5 minutes
• Attempt Limiting: Maximum 3 verification attempts per challenge
• Device Activation: Devices must be verified before use
• Automatic Cleanup: Expired challenges are automatically removed via DynamoDB TTL

Development

Scripts

• npm run dev - Start development server
• npm run build - Build the project
• npm run deploy - Deploy to AWS
• npm run remove - Remove from AWS
• npm run console - Open SST console
• npm run typecheck - Run TypeScript checks

Project Structure

services/mfa-api/
├── packages/
│   └── functions/
│       ├── mfa/
│       │   ├── createDevice.ts
│       │   ├── verifySetup.ts
│       │   ├── listDevices.ts
│       │   ├── updateDevice.ts
│       │   ├── deleteDevice.ts
│       │   ├── createChallenge.ts
│       │   └── verifyChallenge.ts
│       ├── middleware/
│       │   └── apiKeyAuth.ts
│       ├── config.ts
│       └── types.ts
├── stacks/
│   └── MfaStack.ts
├── docs/
├── package.json
├── sst.config.ts
└── tsconfig.json

Dependencies

The service uses the following key dependencies:

• SST: Serverless framework
• AWS SDK: DynamoDB operations
• @xcelsior/email: Email service for OTP delivery
• @xcelsior/lambda-http: HTTP utilities and middleware
• speakeasy: TOTP generation and verification
• qrcode: QR code generation for app authenticator setup
• zod: Runtime type validation

Monitoring

The service includes comprehensive logging and tracing:

• AWS X-Ray tracing for request tracking
• CloudWatch metrics and logs
• Structured logging with correlation IDs
• Error tracking and alerting

License

This project is part of the Excelsior packages monorepo.