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.

$3

- 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

$3

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

Getting Started

$3

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

$3

1. Install dependencies:
``bash
npm install
`

2. Start development server:
`bash
npm run dev
`

3. Deploy to AWS:
`bash
npm run deploy
`

Usage Examples

$3

`bash
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:
`json
{
"data": {
"deviceId": "device-uuid",
"qrCodeUrl": "data:image/png;base64,...",
"secret": "JBSWY3DPEHPK3PXP"
}
}
`

$3

`bash
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": "user@example.com"
}'
`

$3

`bash
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"
}'
`

$3

`bash
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"
}'
`

$3

`bash
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

$3

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

$3

- 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

$3

- 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

$3

`
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.