Developer Guide: Implementing SMS OTP Verification with Node.js, Express, and Vonage - code-examples -

Developer Guide: Implementing SMS OTP Verification with Node.js, Express, and Vonage

This guide provides a complete walkthrough for building a secure One-Time Password (OTP) verification system via SMS using Node.js, Express, and the Vonage Verify API. We'll cover everything from project setup to deployment and testing, enabling you to add a robust two-factor authentication (2FA) layer to your applications.

Project Overview and Goals

What We'll Build

We will create a simple Node.js web application using the Express framework that serves a JSON API to:

  1. Accept a mobile phone number via an API endpoint.
  2. Use the Vonage Verify API to send an OTP code via SMS to that number.
  3. Accept the received OTP code and a request identifier via a second API endpoint.
  4. Use the Vonage Verify API to check if the submitted code is correct for the given verification request.
  5. Return a success or failure status via the API.

Problem Solved

This implementation adds a layer of security known as two-factor authentication (2FA). It helps verify user identity by requiring not just something they know (like a password, though not implemented in this basic example) but also something they possess (access to the specified mobile phone to receive the SMS OTP). This protects against unauthorized access even if passwords are compromised.

Technologies Used

  • Node.js: A JavaScript runtime environment for building server-side applications.
  • Express: A minimal and flexible Node.js web application framework.
  • Vonage Verify API: A service that handles the generation, delivery (via SMS, voice), and verification of OTP codes. It simplifies the complex logic of OTP management.
  • @vonage/server-sdk: The official Vonage Node.js SDK for interacting with Vonage APIs.
  • dotenv: A module to load environment variables from a .env file, keeping sensitive credentials secure.
  • (Optional) Nunjucks: A templating engine sometimes used for rendering HTML views (mentioned in related research, but this guide focuses on API logic returning JSON).

System Architecture

+-------------+       +---------------------+       +--------------------+       +--------------+
| Client App  | ----> | Express Application | ----> | Vonage Verify API  | ----> | User's Phone |
| (e.g., SPA, |       | (Node.js / API)     |       | (Send & Check OTP) |       | (SMS)        |
| Mobile App) |       +---------------------+       +--------------------+       +--------------+
+-------------+                |                             |
      |  1. POST /request-otp  |  2. Call verify.start()     |  3. Send SMS OTP
      |     (phone number)     |     (number, brand)        |
      |                        |                             |
      |  <---------------------|  <--------------------------|
      |  4. Return request_id  |  5. Return request_id      |
      |                        |                             |
      |  6. POST /verify-otp   |  7. Call verify.check()     |
      |     (request_id_ code) |     (request_id_ code)     |
      |                        |                             |
      |  <---------------------|  <--------------------------|
      |  8. Return Success/Fail|  9. Return result status   |
      |                        |                             |
      +------------------------+-----------------------------+

Prerequisites

  • Node.js and npm (or yarn): Installed on your development machine. Download Node.js
  • Vonage API Account: Free signup available. You'll need your API Key and API Secret. Sign up for Vonage
  • Basic JavaScript and Node.js knowledge.
  • A text editor or IDE (e.g._ VS Code).
  • (Optional) curl or Postman: For testing the API endpoints.
  • (Optional) Ngrok: If you need to expose advanced webhooks for Verify V2 workflows (not needed for this basic V1 example). Get Ngrok

1. Setting up the Project

Let's initialize our Node.js project and install the necessary dependencies.

  1. Create Project Directory: Open your terminal or command prompt and create a new directory for the project_ then navigate into it:

    mkdir vonage-otp-app
cd vonage-otp-app

  2. Initialize npm: Create a package.json file to manage project dependencies and scripts:

    npm init -y

  3. Install Dependencies: Install Express_ the Vonage SDK_ and dotenv:

    npm install express @vonage/server-sdk dotenv
    • express: The web framework.
    • @vonage/server-sdk: To interact with the Vonage API.
    • dotenv: To manage environment variables securely.

  4. Create Project Structure: Create the main application file and a file for environment variables:

    touch index.js .env .gitignore

    Your basic structure should look like this:

    vonage-otp-app/
├── node_modules/
├── index.js         # Main application logic
├── package.json
├── package-lock.json
├── .env             # Environment variables (API keys_ etc.) - DO NOT COMMIT
└── .gitignore       # Specifies files git should ignore

  5. Configure .gitignore: It's crucial not to commit sensitive information like API keys or the node_modules directory. Add the following to your .gitignore file:

    # Dependencies
node_modules/

# Environment Variables
.env
*.env

# Logs
logs/
*.log

# OS generated files
.DS_Store
Thumbs.db

  6. Set up Environment Variables (.env): Open the .env file and add placeholders for your Vonage API credentials. You must replace these placeholders with your actual credentials obtained from the Vonage dashboard for the application to function.

    # Vonage API Credentials
# Get these from your Vonage Dashboard: https://dashboard.nexmo.com/settings
VONAGE_API_KEY=YOUR_API_KEY
VONAGE_API_SECRET=YOUR_API_SECRET

# Application Settings
PORT=3000
BRAND_NAME=""YourAppName"" # Name shown in the OTP message (keep it short). Customize this!
    • VONAGE_API_KEY / VONAGE_API_SECRET: Essential for authenticating with Vonage. Find them on your Vonage Dashboard. Replace YOUR_API_KEY and YOUR_API_SECRET with your actual values.
    • PORT: The port your Express application will listen on.
    • BRAND_NAME: A short name representing your application_ included in the SMS message template by Vonage Verify. Customize YourAppName to match your application.

2. Implementing Core Functionality

Now_ let's write the core logic in index.js to handle OTP requests and verification. We will structure it slightly to allow exporting the app for testing.

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

const express = require('express');
const { Vonage } = require('@vonage/server-sdk');

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

// Initialize Vonage Client
// Ensure VONAGE_API_KEY and VONAGE_API_SECRET are set in your .env file
let vonage;
if (process.env.VONAGE_API_KEY && process.env.VONAGE_API_SECRET) {
  vonage = new Vonage({
    apiKey: process.env.VONAGE_API_KEY_
    apiSecret: process.env.VONAGE_API_SECRET
  });
} else {
  console.warn('\n*** WARNING: Vonage API Key or Secret not found in environment variables. API calls will likely fail. Please check your .env file. ***\n');
  // In a real app_ you might throw an error or prevent startup here.
  // For testing/demo purposes_ we allow it to continue but Vonage calls will fail.
}

// --- Middleware ---
app.use(express.json()); // Enable Express to parse JSON request bodies
app.use(express.urlencoded({ extended: true })); // Enable Express to parse URL-encoded request bodies

// --- Core OTP Logic ---

/**
 * Initiates the OTP verification process.
 * Sends an OTP code to the provided phone number via SMS.
 *
 * POST /request-otp
 * Body: { ""phoneNumber"": ""YOUR_PHONE_NUMBER_WITH_COUNTRY_CODE"" } // e.g._ ""14155552671""
 *
 * Success Response (200 OK): { ""requestId"": ""VONAGE_REQUEST_ID"" }
 * Error Response (400/500): { ""error"": ""Error message"" }
 */
async function requestOtp(req_ res) {
  const { phoneNumber } = req.body;
  const brandName = process.env.BRAND_NAME || 'MyApp'; // Use brand from .env or default

  // Basic input validation
  if (!phoneNumber) {
    return res.status(400).json({ error: 'Phone number is required.' });
  }
  // Add more robust phone number validation here (e.g._ using libphonenumber-js)

  // Check if Vonage client was initialized
  if (!vonage) {
     console.error('Vonage client not initialized due to missing credentials.');
     return res.status(500).json({ error: 'Server configuration error: Vonage client not available.' });
  }

  console.log(`Requesting OTP for number: ${phoneNumber} with brand: ${brandName}`);

  try {
    // Start the Vonage Verify request
    const result = await vonage.verify.start({
      number: phoneNumber_
      brand: brandName
      // You can add other options here like workflow_id_ code_length_ etc.
      // See Vonage docs: https://developer.vonage.com/api/verify#startVerification
    });

    // Vonage Verify API v1 returns status 0 on success
    // For Verify v2_ you'd check HTTP status codes (e.g._ 202 Accepted)
    if (result.status === '0') {
      console.log(`Verification request sent successfully. Request ID: ${result.request_id}`);
      // IMPORTANT: Send the request_id back to the client.
      // The client needs this ID to verify the code later.
      res.status(200).json({ requestId: result.request_id });
    } else {
      // Handle Vonage API errors
      console.error(`Vonage verification request failed: Status ${result.status} - ${result.error_text}`);
      res.status(400).json({ error: result.error_text || 'Failed to send OTP.' });
    }
  } catch (error) {
    // Handle network or unexpected errors
    console.error('Error requesting OTP:'_ error);
    res.status(500).json({ error: 'An internal server error occurred.' });
  }
}

/**
 * Verifies the OTP code submitted by the user.
 *
 * POST /verify-otp
 * Body: { ""requestId"": ""VONAGE_REQUEST_ID_FROM_PREVIOUS_STEP""_ ""code"": ""USER_ENTERED_CODE"" }
 *
 * Success Response (200 OK): { ""message"": ""Verification successful."" }
 * Error Response (400/410/500): { ""error"": ""Error message"" }
 */
async function verifyOtp(req_ res) {
  const { requestId_ code } = req.body;

  // Basic input validation
  if (!requestId || !code) {
    return res.status(400).json({ error: 'Request ID and code are required.' });
  }
  // Add code format validation if needed (e.g._ 4-6 digits)

  // Check if Vonage client was initialized
  if (!vonage) {
     console.error('Vonage client not initialized due to missing credentials.');
     return res.status(500).json({ error: 'Server configuration error: Vonage client not available.' });
  }

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

  try {
    // Check the code using the Vonage Verify API
    const result = await vonage.verify.check(requestId_ code);
    // For Verify v2 use: await vonage.verify.check(requestId_ { code: code });

    // Status '0' indicates successful verification
    if (result.status === '0') {
      console.log(`Verification successful for Request ID: ${requestId}`);
      // Verification successful - In a real app_ you'd now mark the user/session as verified.
      res.status(200).json({ message: 'Verification successful.' });
    } else {
      // Handle specific Vonage verification errors
      console.warn(`Verification failed for Request ID ${requestId}: Status ${result.status} - ${result.error_text}`);
      // Status 16: The code provided was incorrect.
      // Status 6: The request is not found or has expired.
      // Other statuses indicate different issues (see Vonage docs)
      const statusCode = (result.status === '6') ? 410 : 400; // 410 Gone if expired/not found
      res.status(statusCode).json({ error: result.error_text || 'Verification failed.' });
    }
  } catch (error) {
    // Handle network or unexpected errors
    console.error('Error verifying OTP:'_ error);
    res.status(500).json({ error: 'An internal server error occurred.' });
  }
}


// --- API Routes ---
app.post('/request-otp'_ requestOtp);
app.post('/verify-otp'_ verifyOtp);

// Basic root route for health check or info
app.get('/'_ (req_ res) => {
  res.status(200).send(`Vonage OTP Service running on port ${port}. API is active. Last updated: ${new Date().toISOString()}`);
});


// --- Start Server ---
// We only run the server if this file is executed directly (e.g., `node index.js`)
// This allows exporting the `app` instance for testing without starting the server.
if (require.main === module) {
  app.listen(port, () => {
    console.log(`Server listening at http://localhost:${port}`);
    // Initial check already happened during Vonage client init
    if (!vonage) {
       console.log(""Reminder: Server started, but Vonage API calls will fail due to missing credentials."");
    }
  });
}

// --- Exports ---
// Export the Express app instance for testing purposes
module.exports = { app, requestOtp, verifyOtp };

Explanation of Changes:

  1. Vonage Client Initialization: Added a check to see if API keys exist before creating the vonage client. Logs a warning if they are missing. Added checks within requestOtp and verifyOtp to return a 500 error if vonage is not initialized, preventing crashes.
  2. Server Start Condition: Wrapped app.listen in if (require.main === module). This standard Node.js pattern ensures the server only starts when the script is run directly, not when it's required by another module (like a test runner).
  3. Exports: Added module.exports = { app, requestOtp, verifyOtp }; at the end, making the Express app instance and handler functions available for import in test files.

3. Building a Complete API Layer

The code in the previous section defines our API endpoints. Here's the detailed documentation and testing examples.

API Endpoints

  1. POST /request-otp

    • Description: Initiates an SMS OTP verification request.
    • Request Body (JSON): 
      {
  ""phoneNumber"": ""YOUR_E164_PHONE_NUMBER""
}
      Example: { ""phoneNumber"": ""14155552671"" } (Use E.164 format: country code + number, no spaces or symbols)
    • Success Response (200 OK, JSON): 
      {
  ""requestId"": ""VONAGE_GENERATED_REQUEST_ID""
}
      Example: { ""requestId"": ""a1b2c3d4e5f67890abcdef1234567890"" }
    • Error Response (400 Bad Request, 500 Internal Server Error, JSON): 
      {
  ""error"": ""Descriptive error message from Vonage or server.""
}
      Example (Invalid Number): { ""error"": ""Invalid number format"" } Example (Missing Number): { ""error"": ""Phone number is required."" } Example (Config Error): { ""error"": ""Server configuration error: Vonage client not available."" }

  2. POST /verify-otp

    • Description: Verifies the OTP code submitted by the user against a specific request ID.
    • Request Body (JSON): 
      {
  ""requestId"": ""VONAGE_REQUEST_ID_FROM_REQUEST_STEP"",
  ""code"": ""USER_ENTERED_OTP_CODE""
}
      Example: { ""requestId"": ""a1b2c3d4e5f67890abcdef1234567890"", ""code"": ""123456"" }
    • Success Response (200 OK, JSON): 
      {
  ""message"": ""Verification successful.""
}
    • Error Response (400 Bad Request, 410 Gone, 500 Internal Server Error, JSON): 
      {
  ""error"": ""Descriptive error message (e.g., incorrect code, expired request).""
}
      Example (Incorrect Code): { ""error"": ""The code provided does not match the expected value."" } Example (Expired/Invalid Request): { ""error"": ""The specified request_id was not found or has already been verified."" } (Returns 410 Gone) Example (Missing Fields): { ""error"": ""Request ID and code are required."" }

Testing with curl

Make sure your server is running (node index.js). Note: Replace the ALL_CAPS placeholders below with your actual phone number (in E.164 format), the requestId returned by the first call, and the code you receive via SMS.

  1. Request OTP:

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

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

    Note the requestId returned in the JSON response.

  2. Verify OTP: Wait for the SMS, then use the requestId from the previous step and the received code:

    curl -X POST http://localhost:3000/verify-otp \
-H ""Content-Type: application/json"" \
-d '{""requestId"": ""THE_REQUEST_ID_YOU_RECEIVED"", ""code"": ""THE_CODE_FROM_SMS""}'

    (Example: curl -X POST http://localhost:3000/verify-otp -H ""Content-Type: application/json"" -d '{""requestId"": ""a1b2c3d4e5f67890abcdef1234567890"", ""code"": ""123456""}')

4. Integrating with Vonage (Credentials)

This step involves securely configuring your application with your Vonage API credentials.

  1. Locate Credentials:

  2. Update .env File: Open the .env file in your project root directory. Replace the placeholder values with your actual Vonage API Key and Secret. Ensure you also customize the BRAND_NAME.

    # Vonage API Credentials
# Get these from your Vonage Dashboard: https://dashboard.nexmo.com/settings
VONAGE_API_KEY=YOUR_ACTUAL_API_KEY_HERE # Replace this
VONAGE_API_SECRET=YOUR_ACTUAL_API_SECRET_HERE # Replace this

# Application Settings
PORT=3000
BRAND_NAME=""YourProdApp"" # Replace with your actual app name for user clarity in SMS

  3. Secure Credentials:

    • NEVER commit your .env file or hardcode your API Key/Secret directly into your source code (index.js).
    • Ensure .env is listed in your .gitignore file (we did this in Step 1).
    • When deploying, use your hosting provider's mechanism for setting environment variables securely (e.g., Heroku Config Vars, AWS Secrets Manager, Docker environment variables).

Explanation of Environment Variables:

  • VONAGE_API_KEY: Your public identifier for using the Vonage API.
  • VONAGE_API_SECRET: Your private key for authenticating requests. Keep this absolutely confidential.
  • BRAND_NAME: Used by the Vonage Verify API within the SMS message template (e.g., ""Your YourProdApp verification code is: 123456""). It helps users identify the source of the OTP. Max length is typically 11 alphanumeric characters or 18 characters total. Ensure you customize this value.

5. Implementing Error Handling and Logging

Our current code has basic error handling using try...catch and checks Vonage's result.status. Let's enhance the logging.

Current Approach:

  • try...catch blocks wrap Vonage API calls to catch network or unexpected errors.
  • result.status from Vonage is checked to determine success ('0') or specific API errors.
  • console.log, console.warn, and console.error are used for basic logging.
  • Checks for Vonage client initialization prevent errors if keys are missing.

Enhancements (Conceptual - Add Libraries for Production):

For production, you'd typically use a more robust logging library like pino or winston and an error tracking service like Sentry or Datadog.

  1. Structured Logging: Use a library like pino for JSON-based logging, which is easier to parse and analyze.

    npm install pino pino-http

    // index.js (Top)
const pino = require('pino');
const pinoHttp = require('pino-http');

const logger = pino({ level: process.env.LOG_LEVEL || 'info' });
const httpLogger = pinoHttp({ logger });

// ... inside Express setup, before routes...
app.use(httpLogger); // Log HTTP requests/responses automatically

// ... replace console.log/warn/error with logger calls ...
// Example in requestOtp:
// logger.info({ phoneNumber, brandName }, `Requesting OTP`); // Structured log
// logger.error({ err: error, phoneNumber }, 'Error requesting OTP');
// logger.warn({ result, phoneNumber }, `Vonage verification request failed`);
// logger.info({ requestId: result.request_id }, 'Verification request sent successfully');

    (Note: This guide retains console.* for simplicity, but pino is recommended for production)

  2. Consistent Error Responses: Ensure all error paths return a consistent JSON structure like { ""error"": ""message"" }. (The current code mostly follows this).

  3. Specific Vonage Error Handling: The code already handles status 0 (success), 6 (expired/not found -> 410 Gone), and other errors as 400 Bad Request. You could add more specific handling for other Vonage status codes if needed, based on the Vonage Verify API documentation.

  4. Retry Mechanisms: For transient network errors when calling Vonage, you could implement a simple retry strategy (e.g., using axios-retry if using Axios, or a custom loop). However, for OTP, retrying a failed verify.start might result in multiple SMS messages, which is usually undesirable. Retrying verify.check might be acceptable for temporary network issues. Be cautious with retries in OTP flows.

Testing Error Scenarios:

  • Invalid Phone Number: Send a request to /request-otp with an incorrectly formatted number.
  • Missing Fields: Send requests missing phoneNumber, requestId, or code.
  • Incorrect Code: Send a request to /verify-otp with the correct requestId but a wrong code.
  • Expired Request: Wait longer than the Vonage timeout (default is 5 minutes) after requesting an OTP, then try to verify it. Vonage should return status 6, resulting in a 410 Gone.
  • Invalid API Keys: Temporarily change your keys in .env to invalid values and restart the server. API calls should fail (likely caught by try/catch or result in Vonage auth errors). The server should warn about missing keys on startup.

6. Creating a Database Schema (Conceptual)

While the Vonage Verify API manages the OTP state itself (code, expiry, attempts), a real-world application using OTP would integrate this into a user management system. You would typically store user information, including their phone number and verification status.

Why No DB Needed for This Example: The Verify API abstracts the need to:

  • Generate cryptographically secure codes.
  • Store the code securely with an expiry time.
  • Track verification attempts.
  • Handle code delivery via SMS/Voice.

Real-World Scenario:

Imagine a user registration flow:

  1. User signs up with email, password, and phone number.
  2. Your application stores this preliminary user data in a database (e.g., PostgreSQL, MongoDB). Mark the phone number as unverified. 
    -- Example PostgreSQL User Table
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL, -- Store hashed passwords only!
    phone_number VARCHAR(20) UNIQUE,
    is_phone_verified BOOLEAN DEFAULT FALSE NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
  3. Your app calls POST /request-otp with the user's phone_number.
  4. User submits the code, your app calls POST /verify-otp.
  5. If verification is successful (200 OK from /verify-otp): Your application updates the user's record in the database: 
    UPDATE users
SET is_phone_verified = TRUE, updated_at = CURRENT_TIMESTAMP
WHERE phone_number = 'USER_PHONE_NUMBER';
-- Or use the user's ID if you associated the requestId with the user ID
  6. The user can now proceed, potentially gaining access to features requiring a verified phone number.

Data Layer Implementation (Using an ORM like Prisma or Sequelize):

You would typically use an Object-Relational Mapper (ORM) like Prisma or Sequelize in Node.js to manage database interactions.

  • Schema Definition: Define your user model/schema in the ORM's syntax.
  • Migrations: Use the ORM's migration tools (prisma migrate dev, sequelize db:migrate) to create and update your database tables safely.
  • Data Access: Use ORM methods (prisma.user.create, sequelize.User.update) to interact with the database instead of writing raw SQL.

This guide focuses solely on the Vonage integration, so we won't implement a full database layer here.

7. Adding Security Features

Security is paramount, especially when dealing with authentication.

  1. Input Validation & Sanitization:

    • Phone Numbers: Use a library like libphonenumber-js to validate and format phone numbers strictly into E.164 format before sending them to Vonage. 
      npm install libphonenumber-js

      // Example usage (enhance requestOtp function)
const { parsePhoneNumberFromString } = require('libphonenumber-js');

// Inside requestOtp, after getting phoneNumber from req.body:
if (!phoneNumber) {
    return res.status(400).json({ error: 'Phone number is required.' });
}
const phoneNumberParsed = parsePhoneNumberFromString(phoneNumber);
if (!phoneNumberParsed || !phoneNumberParsed.isValid()) {
  // logger.warn({ phoneNumber }, 'Invalid phone number format received.'); // If using logger
  console.warn(`Invalid phone number format received: ${phoneNumber}`);
  return res.status(400).json({ error: 'Invalid phone number format.' });
}
const formattedNumber = phoneNumberParsed.format('E.164'); // e.g., +14155552671

// Use formattedNumber when calling vonage.verify.start:
// await vonage.verify.start({ number: formattedNumber, brand: brandName });
    • OTP Codes: Ensure the code received from the client matches the expected format (e.g., 4-10 digits, as per Vonage docs). 
      // Example usage (add to verifyOtp function, after checking for presence)
if (!/^\d{4,10}$/.test(code)) { // Vonage codes are 4-10 digits
     // logger.warn({ requestId, code }, 'Invalid OTP code format received.'); // If using logger
     console.warn(`Invalid OTP code format received for Request ID ${requestId}: ${code}`);
     return res.status(400).json({ error: 'Invalid code format. Must be 4-10 digits.' });
}
    • Request IDs: Validate the format if possible (they are typically alphanumeric strings, potentially UUIDs depending on Vonage version/config). A basic check for non-empty string might suffice initially.

  2. Rate Limiting: Prevent brute-force attacks on both requesting OTPs and verifying them. Use a library like express-rate-limit.

    npm install express-rate-limit

    // index.js (Top)
const rateLimit = require('express-rate-limit');

// Apply rate limiting to OTP routes
const otpLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 5, // Limit each IP to 5 requests per windowMs for /request-otp
  message: { error: 'Too many OTP requests from this IP, please try again after 15 minutes' },
  standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
  legacyHeaders: false, // Disable the `X-RateLimit-*` headers
  keyGenerator: (req, res) => req.ip // Default IP-based limiting
});

const verifyLimiter = rateLimit({
  windowMs: 5 * 60 * 1000, // 5 minutes
  max: 10, // Limit each IP to 10 verification attempts per windowMs for /verify-otp
  message: { error: 'Too many verification attempts from this IP, please try again after 5 minutes' },
  standardHeaders: true,
  legacyHeaders: false,
  keyGenerator: (req, res) => req.ip // Default IP-based limiting
});

// Apply middleware BEFORE the route handlers
app.post('/request-otp', otpLimiter, requestOtp);
app.post('/verify-otp', verifyLimiter, verifyOtp);

    Adjust windowMs and max based on your expected usage and security posture. Consider more sophisticated key generation (e.g., based on user ID if authenticated) for logged-in scenarios.

  3. HTTPS: Always use HTTPS in production to encrypt communication between the client and your server. Use a reverse proxy like Nginx or Caddy, or platform services (Heroku, Render) to handle TLS termination.

  4. Helmet: Use the helmet middleware for setting various security-related HTTP headers.

    npm install helmet

    // index.js (Top)
const helmet = require('helmet');

// ... inside Express setup, before routes ...
app.use(helmet()); // Set security headers (Content-Security-Policy, X-Frame-Options, etc.)

  5. Dependency Security: Regularly audit your dependencies for known vulnerabilities using npm audit and update them.

    npm audit
npm audit fix # Attempts to fix found vulnerabilities

  6. Vonage Security Features: Vonage Verify itself has built-in fraud detection and throttling mechanisms. You can configure fraud rules in the Vonage dashboard.

Testing Security:

  • Use tools like curl or scripts to send rapid requests to /request-otp and /verify-otp to test the rate limiter. Check for 429 Too Many Requests responses.
  • Attempt to send invalid data (malformed phone numbers, non-digit codes, invalid JSON) to test input validation and error handling.
  • Use npm audit regularly.
  • Inspect HTTP response headers to ensure helmet is setting headers like X-Content-Type-Options: nosniff, X-Frame-Options: SAMEORIGIN, etc.

8. Handling Special Cases

  • International Phone Numbers: Always require and validate numbers in E.164 format (+ followed by country code and number). The libphonenumber-js library (shown in Security section) helps significantly here. Inform users clearly about the required format in your client application.
  • Vonage Verify Limitations:
    • Delivery Issues: SMS delivery isn't always 100% guaranteed (carrier issues, spam filters, number type). Vonage Verify has built-in retries (e.g., voice call fallback if SMS fails and the workflow allows), but you might need to inform users or offer alternative verification methods if problems persist for a specific number. Check delivery logs in the Vonage dashboard.
    • Shared Numbers/VoIP: Some VoIP or shared SMS numbers might be blocked or have issues receiving OTPs. Consider using Vonage Number Insight API beforehand to check number validity and type if this is a major concern, although this adds cost and complexity.
    • Rate Limits: Be aware of Vonage's own rate limits on the Verify API to avoid being throttled (Status 1 or 9). Your own rate limiting should help prevent hitting these under normal conditions.
  • User Experience:
    • Provide clear feedback to the user in the client application (e.g., ""Sending OTP to +1 XXX-XXX-XX12"", ""Invalid code, please try again"", ""Code expired, request a new one"").