Vonage Node.js Express OTP/2FA SMS Implementation Guide

mkdir vonage-otp-guide
cd vonage-otp-guide

npm init -y

npm install express @vonage/server-sdk dotenv body-parser

npm install express-rate-limit libphonenumber-js

# .gitignore

node_modules
.env
*.log

# .env

VONAGE_API_KEY=YOUR_API_KEY_HERE
VONAGE_API_SECRET=YOUR_API_SECRET_HERE

# Optional: Set a default port
PORT=3000

// index.js
require('dotenv').config(); // Load environment variables from .env file

const express = require('express');
const bodyParser = require('body-parser');
const { Vonage } = require('@vonage/server-sdk');
const rateLimit = require('express-rate-limit');
const { parsePhoneNumber, isValidPhoneNumber } = require('libphonenumber-js');

// --- Configuration ---
const app = express();
const port = process.env.PORT || 3000; // Use port from .env or default to 3000

// --- Vonage Client Initialization ---
// IMPORTANT: Ensure VONAGE_API_KEY and VONAGE_API_SECRET are set in your .env file
if (!process.env.VONAGE_API_KEY || !process.env.VONAGE_API_SECRET) {
    console.error('⚠️ Error: VONAGE_API_KEY or VONAGE_API_SECRET not found in .env file.');
    console.error('Add them to your .env file.');
    process.exit(1); // Exit if keys are missing
}

const vonage = new Vonage({
    apiKey: process.env.VONAGE_API_KEY,
    apiSecret: process.env.VONAGE_API_SECRET
});

// --- Rate Limiting Configuration ---
// Prevent abuse of OTP requests – max 5 requests per 15 minutes per IP
const otpRequestLimiter = rateLimit({
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 5, // Limit each IP to 5 requests per windowMs
    message: { error: 'Too many OTP requests from this IP. Try again after 15 minutes.' },
    standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
    legacyHeaders: false, // Disable the `X-RateLimit-*` headers
});

// Verification check rate limiter – max 10 attempts per 5 minutes per IP
const otpCheckLimiter = rateLimit({
    windowMs: 5 * 60 * 1000, // 5 minutes
    max: 10, // Allow up to 10 check attempts per windowMs (multiple users per IP)
    message: { error: 'Too many verification attempts. Try again later.' },
    standardHeaders: true,
    legacyHeaders: false,
});

// --- Middleware ---
// Parse JSON bodies (as sent by API clients)
app.use(bodyParser.json());
// Parse URL-encoded bodies (as sent by HTML forms)
app.use(bodyParser.urlencoded({ extended: true }));

// In-memory storage for demo purposes.
// Production apps should use a database or persistent cache (e.g., Redis).
// Structure: { phoneNumber: { requestId: string, attempts: number, lastAttempt: Date } }
const verificationRequests = {};

// --- Helper Functions ---

/**
 * Validates and formats phone number to E.164 format
 * @param {string} phoneNumber – Raw phone number input
 * @returns {object} – { valid: boolean, formatted: string, error: string }
 */
function validateAndFormatPhone(phoneNumber) {
    try {
        // Check if it's a valid phone number
        if (!isValidPhoneNumber(phoneNumber)) {
            return { valid: false, error: 'Invalid phone number format' };
        }

        // Parse and format to E.164
        const parsed = parsePhoneNumber(phoneNumber);
        return {
            valid: true,
            formatted: parsed.format('E.164') // e.g., +14155552671
        };
    } catch (error) {
        return {
            valid: false,
            error: 'Unable to parse phone number. Use international format (e.g., +14155552671).'
        };
    }
}

// --- Routes (will be added below) ---
// ...

// --- Health Check Endpoint ---
app.get('/health', (req, res) => {
    res.status(200).json({ status: 'ok', service: 'vonage-otp-api' });
});

// --- Start Server ---
app.listen(port, () => {
    console.log(`✅ Server running on http://localhost:${port}`);
    console.log(`📋 Health check: http://localhost:${port}/health`);
});

// --- Graceful Shutdown ---
process.on('SIGTERM', () => {
    console.log('SIGTERM signal received: closing HTTP server');
    server.close(() => {
        console.log('HTTP server closed');
        process.exit(0);
    });
});

// index.js (continued)

// --- Routes ---

/**
 * @route POST /request-otp
 * @description Initiates an OTP verification request via SMS.
 * @param {string} phoneNumber – The user's phone number in E.164 format (e.g., +14155552671).
 * @returns {object} 200 – Success message (OTP sent).
 * @returns {object} 400 – Bad request (e.g., missing phone number).
 * @returns {object} 429 – Too many requests (rate limit exceeded).
 * @returns {object} 500 – Server error or Vonage API error.
 */
app.post('/request-otp', otpRequestLimiter, async (req, res) => {
    const { phoneNumber } = req.body;

    // Input validation
    if (!phoneNumber) {
        return res.status(400).json({ error: 'Phone number is required.' });
    }

    // Validate and format phone number to E.164
    const phoneValidation = validateAndFormatPhone(phoneNumber);
    if (!phoneValidation.valid) {
        return res.status(400).json({ error: phoneValidation.error });
    }

    const formattedNumber = phoneValidation.formatted;
    console.log(`📱 Requesting OTP for: ${formattedNumber}`);

    // Check for duplicate concurrent requests
    if (verificationRequests[formattedNumber]) {
        const existingRequest = verificationRequests[formattedNumber];
        const timeSinceLastRequest = Date.now() - existingRequest.lastAttempt.getTime();

        // Prevent requests within 60 seconds of previous request
        if (timeSinceLastRequest < 60000) {
            return res.status(429).json({
                error: 'Wait before requesting a new code.',
                retryAfter: Math.ceil((60000 - timeSinceLastRequest) / 1000)
            });
        }
    }

    try {
        const result = await vonage.verify.start({
            number: formattedNumber,
            brand: 'YourAppName', // IMPORTANT: Customize this! Appears in the SMS message.
            code_length: 6, // 6-digit code (options: 4 or 6)
            workflow_id: 6 // SMS only, no voice fallback (see workflow section)
            // See Vonage Docs: https://developer.vonage.com/api/verify#startVerification
        });

        if (result.status === '0') { // Status '0' indicates success
            // Store the request_id temporarily, associated with the phone number
            verificationRequests[formattedNumber] = {
                requestId: result.request_id,
                attempts: 0,
                lastAttempt: new Date()
            };
            console.log(`✅ OTP request successful. Request ID: ${result.request_id}`);

            // IMPORTANT: Do NOT send the request_id to the client-side
            res.status(200).json({
                message: 'OTP requested successfully. Check your phone.',
                expiresIn: 300 // Code expires in 300 seconds (5 minutes)
            });
        } else {
            // Handle Vonage API errors
            console.error(`❌ Vonage Verify API Error: Status ${result.status} – ${result.error_text}`);

            // Map specific Vonage status codes to user-friendly messages
            const errorMessages = {
                '1': 'Service temporarily unavailable. Try again.',
                '3': 'Invalid phone number format.',
                '4': 'Authentication failed. Contact support.',
                '7': 'This number is blocked from verification.',
                '9': 'Verification quota exceeded. Contact support.',
                '10': 'A verification request is already in progress for this number.',
                '15': 'This destination is not supported.'
            };

            const userMessage = errorMessages[result.status] || `Failed to request OTP: ${result.error_text}`;
            res.status(result.status === '9' ? 402 : 500).json({ error: userMessage });
        }
    } catch (error) {
        // Handle errors thrown by the SDK or network issues
        console.error('❌ Server Error requesting OTP:', error);
        res.status(500).json({ error: 'An unexpected server error occurred while requesting the OTP.' });
    }
});

// ... (other routes and server start)

// index.js (continued)

/**
 * @route POST /check-otp
 * @description Verifies the OTP code submitted by the user.
 * @param {string} phoneNumber – The user's phone number (used to retrieve request_id).
 * @param {string} code – The OTP code entered by the user.
 * @returns {object} 200 – Verification successful.
 * @returns {object} 400 – Bad request (e.g., missing fields, invalid code format).
 * @returns {object} 401 – Unauthorized (verification failed – wrong code, expired, etc.).
 * @returns {object} 404 – Not Found (request ID not found for the phone number).
 * @returns {object} 429 – Too many verification attempts.
 * @returns {object} 500 – Server error or Vonage API error.
 */
app.post('/check-otp', otpCheckLimiter, async (req, res) => {
    const { phoneNumber, code } = req.body;

    // Input validation
    if (!phoneNumber || !code) {
        return res.status(400).json({ error: 'Phone number and code are required.' });
    }

    // Validate code format (4 or 6 digits)
    if (!/^[0-9]{4,6}$/.test(code)) {
        return res.status(400).json({ error: 'Code must be 4-6 digits.' });
    }

    // Format phone number
    const phoneValidation = validateAndFormatPhone(phoneNumber);
    if (!phoneValidation.valid) {
        return res.status(400).json({ error: phoneValidation.error });
    }

    const formattedNumber = phoneValidation.formatted;

    // Retrieve the verification request
    const verificationData = verificationRequests[formattedNumber];

    if (!verificationData) {
        console.warn(`⚠️ No pending verification found for: ${formattedNumber}`);
        return res.status(404).json({
            error: 'No pending verification found for this number, or it has expired. Request a new code.'
        });
    }

    // Check attempt limit (Vonage allows 3 attempts per request)
    if (verificationData.attempts >= 3) {
        delete verificationRequests[formattedNumber];
        return res.status(429).json({
            error: 'Too many failed attempts. Request a new code.'
        });
    }

    console.log(`🔍 Verifying OTP for: ${formattedNumber} with code: ${code} (Request ID: ${verificationData.requestId})`);

    try {
        const result = await vonage.verify.check(verificationData.requestId, code);

        if (result.status === '0') { // Status '0' indicates successful verification
            console.log(`✅ Verification successful for: ${formattedNumber}`);
            // Verification successful – clear the stored request ID
            delete verificationRequests[formattedNumber];

            // In production: Update user status to verified, grant access, etc.
            res.status(200).json({
                message: 'Verification successful!',
                verified: true
            });
        } else {
            // Increment attempt counter
            verificationRequests[formattedNumber].attempts += 1;

            // Handle Vonage verification failures
            console.warn(`⚠️ Verification failed for ${formattedNumber}: Status ${result.status} – ${result.error_text}`);

            // Map error codes to user-friendly messages
            const errorMessages = {
                '16': 'Code has expired. Request a new code.',
                '17': 'Too many incorrect attempts. Request a new code.',
                '6': 'Invalid code. Try again.',
                '101': 'No matching verification request found.'
            };

            const userMessage = errorMessages[result.status] || `Verification failed: ${result.error_text}`;
            const remainingAttempts = 3 - verificationRequests[formattedNumber].attempts;

            // Clear request if expired or too many attempts
            if (['16', '17', '101'].includes(result.status)) {
                delete verificationRequests[formattedNumber];
                return res.status(401).json({ error: userMessage });
            }

            res.status(401).json({
                error: userMessage,
                remainingAttempts: remainingAttempts
            });
        }
    } catch (error) {
        // Handle errors thrown by the SDK
        console.error('❌ Server Error checking OTP:', error.message || error);

        // Check for structured error from Vonage SDK
        if (error.body && error.body.error_text) {
             console.error(`❌ Vonage Check API Error Detail: ${error.statusCode} – ${error.body.error_text}`);
             res.status(error.statusCode || 500).json({
                 error: `Verification check failed: ${error.body.error_text}`
             });
        } else {
            // Generic server error
            res.status(500).json({ error: 'An unexpected server error occurred during verification.' });
        }
    }
});

// ... (server start)

curl http://localhost:3000/health

{
  "status": "ok",
  "service": "vonage-otp-api"
}

curl -X POST http://localhost:3000/request-otp \
     -H "Content-Type: application/json" \
     -d '{"phoneNumber": "+14155552671"}'

{
  "message": "OTP requested successfully. Check your phone.",
  "expiresIn": 300
}

curl -X POST http://localhost:3000/request-otp \
     -H "Content-Type: application/json" \
     -d '{"phoneNumber": "555-1234"}'

{
  "error": "Invalid phone number format"
}

curl -X POST http://localhost:3000/check-otp \
     -H "Content-Type: application/json" \
     -d '{"phoneNumber": "+14155552671", "code": "123456"}' # Replace with actual code

{
  "message": "Verification successful!",
  "verified": true
}

{
  "error": "Invalid code. Try again.",
  "remainingAttempts": 2
}

{
  "error": "Too many OTP requests from this IP. Try again after 15 minutes."
}

const redis = require('redis');
const client = redis.createClient({
    url: process.env.REDIS_URL || 'redis://localhost:6379'
});

await client.connect();

// Store verification request
await client.setEx(
    `verify:${userId}`, // Key: verify:<user_id>
    600, // TTL: 10 minutes
    JSON.stringify({
        requestId: result.request_id,
        phoneNumber: formattedNumber,
        attempts: 0,
        createdAt: new Date().toISOString()
    })
);

// Retrieve verification request
const verifyData = await client.get(`verify:${userId}`);
const data = JSON.parse(verifyData);

// Delete after successful verification
await client.del(`verify:${userId}`);

-- Users table with 2FA fields
CREATE TABLE users (
    user_id SERIAL PRIMARY KEY,
    username VARCHAR(255) UNIQUE NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    phone_number VARCHAR(20), -- Verified phone in E.164
    phone_verified BOOLEAN DEFAULT FALSE,
    two_factor_enabled BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Separate table for verification requests
CREATE TABLE verification_requests (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(user_id) ON DELETE CASCADE,
    request_id VARCHAR(50) NOT NULL, -- Vonage request_id
    phone_number VARCHAR(20) NOT NULL,
    attempts INTEGER DEFAULT 0,
    status VARCHAR(20) DEFAULT 'pending', -- pending, verified, expired, failed
    expires_at TIMESTAMPTZ NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    verified_at TIMESTAMPTZ,

    -- Performance indexes
    INDEX idx_user_id (user_id),
    INDEX idx_request_id (request_id),
    INDEX idx_expires_at (expires_at)
);

-- Auto-delete expired records (PostgreSQL with pg_cron extension)
CREATE EXTENSION IF NOT EXISTS pg_cron;
SELECT cron.schedule(
    'delete-expired-verifications',
    '0 * * * *', -- Every hour
    'DELETE FROM verification_requests WHERE expires_at < NOW()'
);

// Using pg (PostgreSQL client)
const { Pool } = require('pg');
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

// Store verification request
app.post('/request-otp', otpRequestLimiter, async (req, res) => {
    // ... validation code ...

    const result = await vonage.verify.start({ /* ... */ });

    if (result.status === '0') {
        // Store in database instead of memory
        await pool.query(
            `INSERT INTO verification_requests
             (user_id, request_id, phone_number, expires_at)
             VALUES ($1, $2, $3, NOW() + INTERVAL '10 minutes')`,
            [req.session.userId, result.request_id, formattedNumber]
        );

        res.status(200).json({ message: 'OTP sent successfully' });
    }
});

// Verify OTP
app.post('/check-otp', otpCheckLimiter, async (req, res) => {
    // ... validation code ...

    // Retrieve from database
    const { rows } = await pool.query(
        `SELECT request_id, attempts, expires_at
         FROM verification_requests
         WHERE user_id = $1 AND status = 'pending'
         ORDER BY created_at DESC LIMIT 1`,
        [req.session.userId]
    );

    if (rows.length === 0) {
        return res.status(404).json({ error: 'No pending verification' });
    }

    const verifyData = rows[0];

    // Check expiration
    if (new Date() > new Date(verifyData.expires_at)) {
        await pool.query(
            `UPDATE verification_requests SET status = 'expired' WHERE user_id = $1`,
            [req.session.userId]
        );
        return res.status(401).json({ error: 'Code expired' });
    }

    // Check attempts
    if (verifyData.attempts >= 3) {
        await pool.query(
            `UPDATE verification_requests SET status = 'failed' WHERE user_id = $1`,
            [req.session.userId]
        );
        return res.status(429).json({ error: 'Too many attempts' });
    }

    // Verify with Vonage
    const result = await vonage.verify.check(verifyData.request_id, code);

    if (result.status === '0') {
        // Success – update database
        await pool.query(
            `UPDATE verification_requests
             SET status = 'verified', verified_at = NOW()
             WHERE user_id = $1`,
            [req.session.userId]
        );

        // Update user's phone_verified status
        await pool.query(
            `UPDATE users SET phone_verified = TRUE, two_factor_enabled = TRUE
             WHERE user_id = $1`,
            [req.session.userId]
        );

        res.status(200).json({ message: 'Verification successful' });
    } else {
        // Increment attempts
        await pool.query(
            `UPDATE verification_requests
             SET attempts = attempts + 1
             WHERE user_id = $1`,
            [req.session.userId]
        );

        res.status(401).json({ error: 'Invalid code', remainingAttempts: 3 - (verifyData.attempts + 1) });
    }
});

# Dockerfile
FROM node:18-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci --only=production

# Copy application code
COPY . .

# Run as non-root user
RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
USER nodejs

EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD node -e "require('http').get('http://localhost:3000/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"

CMD ["node", "index.js"]

version: '3.8'

services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - VONAGE_API_KEY=${VONAGE_API_KEY}
      - VONAGE_API_SECRET=${VONAGE_API_SECRET}
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    restart: unless-stopped

volumes:
  redis-data: