Implementing SMS OTP Authentication with Infobip in Node.js and Express

sequenceDiagram
    participant User
    participant Browser/Client
    participant ExpressApp as Node.js/Express App
    participant InfobipAPI as Infobip 2FA API
    participant SMSGateway as SMS Gateway

    User->>Browser/Client: Initiates action requiring OTP (e.g., Login)
    Browser/Client->>+ExpressApp: POST /api/send-otp (phoneNumber)
    ExpressApp->>+InfobipAPI: Send PIN Request (apiKey, appId, msgId, phoneNumber)
    InfobipAPI->>+SMSGateway: Send SMS with OTP
    SMSGateway->>User: Delivers SMS with OTP
    InfobipAPI-->>-ExpressApp: Success Response (pinId)
    Note over ExpressApp: Store pinId securely server-side (e.g., session, temp DB record) associated with user/phone number. DO NOT expose to client.
    ExpressApp-->>-Browser/Client: Success Response ({ message: 'OTP sent successfully.' })
    User->>Browser/Client: Enters received OTP
    Browser/Client->>+ExpressApp: POST /api/verify-otp (phoneNumber, otpCode)
    Note over ExpressApp: Retrieve stored pinId associated with user/phone number from server-side store.
    ExpressApp->>+InfobipAPI: Verify PIN Request (apiKey, pinId, otpCode)
    InfobipAPI-->>-ExpressApp: Verification Response (verified: true/false)
    alt Verification Successful
        ExpressApp->>ExpressApp: Mark user/action as verified
        ExpressApp-->>-Browser/Client: Success Response ({ verified: true, message: 'OTP verified successfully.' })
    else Verification Failed
        ExpressApp-->>-Browser/Client: Failure Response ({ verified: false, error: 'Invalid or expired OTP.' })
    end

mkdir node-infobip-otp
cd node-infobip-otp

npm init -y

npm install express dotenv axios express-rate-limit

# .env - Replace placeholder values with your actual credentials.
# See Section 4 of the guide for details on obtaining these values.

# Infobip Credentials (See Section 4.1)
INFOBIP_BASE_URL=YOUR_INFOBIP_BASE_URL # Found on Infobip portal homepage/API section
INFOBIP_API_KEY=YOUR_INFOBIP_API_KEY   # Generated in Infobip portal API Key management

# Infobip 2FA Configuration (See Section 4.2)
INFOBIP_2FA_APP_ID=YOUR_INFOBIP_2FA_APP_ID # ID from created 2FA Application
INFOBIP_2FA_MSG_ID=YOUR_INFOBIP_2FA_MSG_ID # ID from created 2FA Message Template

# Application Port
PORT=3000

// infobipService.js
const axios = require('axios');

// Ensure environment variables are loaded (usually done in server.js, but safe to re-require)
require('dotenv').config();

const INFOBIP_BASE_URL = process.env.INFOBIP_BASE_URL;
const INFOBIP_API_KEY = process.env.INFOBIP_API_KEY;
const INFOBIP_2FA_APP_ID = process.env.INFOBIP_2FA_APP_ID;
const INFOBIP_2FA_MSG_ID = process.env.INFOBIP_2FA_MSG_ID;

// Configure Axios instance for Infobip API calls
const infobipAxios = axios.create({
    baseURL: INFOBIP_BASE_URL,
    headers: {
        'Authorization': `App ${INFOBIP_API_KEY}`,
        'Content-Type': 'application/json',
        'Accept': 'application/json',
    }
});

/**
 * Sends an OTP PIN via SMS using Infobip 2FA API.
 * @param {string} phoneNumber - The recipient's phone number in E.164 format.
 * @returns {Promise<string>} - A promise that resolves with the pinId.
 * @throws {Error} - Throws an error if the API call fails or configuration is missing.
 */
async function sendOtp(phoneNumber) {
    if (!INFOBIP_BASE_URL || !INFOBIP_API_KEY || !INFOBIP_2FA_APP_ID || !INFOBIP_2FA_MSG_ID) {
         console.error('Infobip configuration is missing or incomplete in .env file.');
         throw new Error('Server configuration error: Infobip details missing.');
         // In a real app, you might have more robust config validation on startup.
         // See Section 4 for obtaining these values.
    }

    try {
        console.log(`Sending OTP to ${phoneNumber} via Infobip...`);
        const response = await infobipAxios.post(`/2fa/2/pin`, {
            applicationId: INFOBIP_2FA_APP_ID,
            messageId: INFOBIP_2FA_MSG_ID,
            to: phoneNumber,
            // 'from' can often be omitted if set in the message template or app config
            // from: 'YourAppName'
        });

        if (response.data && response.data.pinId) {
            console.log(`OTP sent successfully. Pin ID: ${response.data.pinId}`); // Log pinId server-side for debugging
            return response.data.pinId; // Return pinId for server-side use
        } else {
            console.error('Infobip send OTP response missing pinId:', response.data);
            throw new Error('Failed to send OTP: Invalid response from Infobip.');
        }
    } catch (error) {
        const errorMessage = error.response?.data?.requestError?.serviceException?.text || error.message || 'Failed to send OTP via Infobip.';
        console.error(`Error sending Infobip OTP to ${phoneNumber}:`, errorMessage, error.response?.data || '');
        // Re-throw a more generic error or the specific Infobip text
        throw new Error(error.response?.data?.requestError?.serviceException?.text || 'Failed to send OTP via Infobip.');
    }
}

/**
 * Verifies an OTP PIN using Infobip 2FA API.
 * @param {string} pinId - The ID of the PIN received when sending the OTP (kept server-side).
 * @param {string} otpCode - The OTP code entered by the user.
 * @returns {Promise<boolean>} - A promise that resolves with true if verified, false otherwise.
 * @throws {Error} - Throws an error if the API call fails unexpectedly (not for standard verification failures like wrong pin).
 */
async function verifyOtp(pinId, otpCode) {
    if (!pinId || !otpCode) {
        throw new Error('Missing pinId or otpCode for verification.');
    }
     if (!INFOBIP_BASE_URL || !INFOBIP_API_KEY) {
         console.error('Infobip configuration is missing or incomplete in .env file.');
         throw new Error('Server configuration error: Infobip details missing.');
     }

    try {
        console.log(`Verifying OTP for Pin ID: ${pinId}`);
        const response = await infobipAxios.post(`/2fa/2/pin/${pinId}/verify`, {
            pin: otpCode
        });

        // Check if 'verified' field exists in the response data
        if (response.data && typeof response.data.verified !== 'undefined') {
            console.log(`OTP Verification result for ${pinId}: ${response.data.verified}`);
            return response.data.verified; // Returns true or false based on Infobip's check
        } else {
            // Handle cases where verification fails gracefully (e.g., wrong PIN)
            // Infobip API should return verified: false in the response data for known failures.
            // If the structure is unexpected, log an error.
            console.error('Infobip verify OTP response missing expected structure:', response.data);
            throw new Error('Failed to verify OTP: Invalid response structure from Infobip.');
        }
    } catch (error) {
        // Check if the error is an expected verification failure (like WRONG_PIN, TOO_MANY_ATTEMPTS)
        const serviceException = error.response?.data?.requestError?.serviceException;
        if (serviceException && (serviceException.messageId === 'WRONG_PIN' || serviceException.messageId === 'PIN_EXPIRED' || serviceException.messageId === 'TOO_MANY_ATTEMPTS')) {
             console.warn(`Verification failed for ${pinId}: ${serviceException.text}`);
            return false; // Return false for these expected verification failures
        }

        // For other unexpected errors (network, config, other Infobip errors), log and throw
        const errorMessage = serviceException?.text || error.message || 'Failed to verify OTP via Infobip.';
        console.error(`Error verifying Infobip OTP for pinId ${pinId}:`, errorMessage, error.response?.data || '');
        throw new Error(serviceException?.text || 'Failed to verify OTP via Infobip.');
    }
}

module.exports = {
    sendOtp,
    verifyOtp
};

// server.js
require('dotenv').config(); // Load environment variables from .env file
const express = require('express');
const rateLimit = require('express-rate-limit');
const helmet = require('helmet'); // Basic security headers
const { sendOtp, verifyOtp } = require('./infobipService');

const app = express();
const port = process.env.PORT || 3000;

// --- Middleware ---

// Basic security headers
app.use(helmet());

// Enable JSON body parsing
app.use(express.json());

// --- Rate Limiting ---
// Apply rate limiting to OTP endpoints to prevent abuse
const otpSendLimiter = rateLimit({
    windowMs: 5 * 60 * 1000, // 5 minutes
    max: 5, // Limit each IP to 5 OTP send requests per windowMs
    message: { error: 'Too many OTP requests from this IP, please try again after 5 minutes' },
    standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
    legacyHeaders: false, // Disable the `X-RateLimit-*` headers
});

const otpVerifyLimiter = rateLimit({
	windowMs: 15 * 60 * 1000, // 15 minutes
	max: 10, // Limit each IP to 10 verification attempts per windowMs
	message: { error: 'Too many verification attempts from this IP, please try again after 15 minutes' },
	standardHeaders: true,
	legacyHeaders: false,
});

// --- Temporary Storage (Replace with Database/Session in Production) ---
// WARNING: In-memory storage is NOT suitable for production. It's not scalable
// and data is lost on restart. Use a database (like Redis, PostgreSQL, MongoDB)
// or proper session management (e.g., express-session with a persistent store).
const otpStore = {}; // Store { phoneNumber: { pinId: '...', timestamp: ... } }

// --- Secure Storage Association (Conceptual - using express-session) ---
/*
// If using express-session:
const session = require('express-session');
// Configure session middleware with a secure secret and persistent store (e.g., connect-redis)
app.use(session({
  secret: process.env.SESSION_SECRET, // MUST be a strong, random secret stored in .env
  resave: false,
  saveUninitialized: false,
  // store: new RedisStore({ client: redisClient }), // Example using Redis
  cookie: { secure: process.env.NODE_ENV === 'production', httpOnly: true, maxAge: 15 * 60 * 1000 } // 15 min
}));

// Inside /api/send-otp, after getting pinId:
// req.session.otpPinId = pinId;
// req.session.otpPhoneNumber = phoneNumber; // Store phone number for association
// req.session.otpTimestamp = Date.now();

// Inside /api/verify-otp:
// const pinId = req.session.otpPinId;
// const associatedPhoneNumber = req.session.otpPhoneNumber;
// const timestamp = req.session.otpTimestamp;
// // Validate timestamp, ensure associatedPhoneNumber matches req.body.phoneNumber
// // ... proceed with verifyOtp(pinId, otpCode) ...
// delete req.session.otpPinId; // Clean up session on success/failure/expiry
// delete req.session.otpPhoneNumber;
// delete req.session.otpTimestamp;
*/


// --- API Routes ---

// Endpoint to request an OTP
app.post('/api/send-otp', otpSendLimiter, async (req, res) => {
    const { phoneNumber } = req.body;

    // Input validation (Essential!)
    // Use a robust library like libphonenumber-js for production (See Section 8)
    if (!phoneNumber || !/^\+?[1-9]\d{1,14}$/.test(phoneNumber)) { // Basic E.164-like format check
        return res.status(400).json({ error: 'Valid phone number in E.164 format (e.g., +14155552671) is required.' });
    }

    try {
        const pinId = await sendOtp(phoneNumber);

        // Securely store the pinId server-side, associated with the phone number/user session.
        // DO NOT send pinId back to the client.
        // Using temporary in-memory store for demonstration ONLY:
        otpStore[phoneNumber] = { pinId: pinId, timestamp: Date.now() };
        console.log(`Stored OTP info for ${phoneNumber}:`, otpStore[phoneNumber]); // For debugging

        // Consider using req.session as described above for a more robust approach.

        res.status(200).json({ message: 'OTP sent successfully.' }); // Do NOT return pinId

    } catch (error) {
        console.error(`Error in /api/send-otp route for ${phoneNumber}:`, error.message);
        // Return a generic error message to the client
        res.status(500).json({ error: error.message || 'Failed to send OTP. Please try again later.' });
    }
});

// Endpoint to verify an OTP
app.post('/api/verify-otp', otpVerifyLimiter, async (req, res) => {
    const { phoneNumber, otpCode } = req.body;

    // Basic validation
    if (!phoneNumber || !otpCode || !/^\d{4,8}$/.test(otpCode)) { // Adjust regex based on your PIN length
        return res.status(400).json({ error: 'Phone number and a valid numeric OTP code are required.' });
    }
    // Re-validate phone number format if needed
    if (!/^\+?[1-9]\d{1,14}$/.test(phoneNumber)) {
         return res.status(400).json({ error: 'Valid phone number in E.164 format is required.' });
    }


    // Retrieve the stored pinId securely from server-side storage
    // Using temporary in-memory store for demonstration ONLY:
    const storedOtpData = otpStore[phoneNumber];

    // If using sessions: const pinId = req.session.otpPinId; (plus other checks)

    if (!storedOtpData) {
        return res.status(400).json({ verified: false, error: 'No OTP request found for this number or it may have expired. Please request a new OTP.' });
    }

    // Optional: Check timestamp for expiry (Infobip handles expiry too via pinTimeToLive)
    const otpRequestTime = storedOtpData.timestamp;
    const fifteenMinutes = 15 * 60 * 1000; // Example: 15 minute validity window on our side
    if (Date.now() - otpRequestTime > fifteenMinutes) {
         delete otpStore[phoneNumber]; // Clean up expired entry
         return res.status(400).json({ verified: false, error: 'OTP has expired. Please request a new one.' });
    }

    const pinId = storedOtpData.pinId; // Get pinId from storage

    try {
        const isVerified = await verifyOtp(pinId, otpCode);

        if (isVerified) {
            // OTP is correct - Proceed with user action (e.g., complete login, grant access)
            delete otpStore[phoneNumber]; // Clean up storage after successful verification
            // If using sessions: delete req.session.otpPinId; etc.

            // In a real app: Mark user as verified in your DB/session, complete login, etc.
            res.status(200).json({ verified: true, message: 'OTP verified successfully.' });
        } else {
            // OTP is incorrect or expired on Infobip's side (verifyOtp returns false for these)
             // Optional: Implement attempt counting here or rely on Infobip's limits configured in the Application
            res.status(400).json({ verified: false, error: 'Invalid or expired OTP code.' });
            // Consider deleting from otpStore here too, or after max attempts are reached
        }
    } catch (error) {
        // This catch block handles unexpected errors from verifyOtp (e.g., network, config errors)
        console.error(`Error in /api/verify-otp route for ${phoneNumber} (PinID: ${pinId}):`, error.message);
        // Don't expose detailed internal errors unless necessary
        res.status(500).json({ verified: false, error: 'Failed to verify OTP due to a server error. Please try again later.' });
    }
});

// Basic root route
app.get('/', (req, res) => {
    res.send('Infobip OTP Service is running!');
});

// Global error handler (optional basic example)
app.use((err, req, res, next) => {
  console.error('Unhandled error:', err.stack);
  res.status(500).send({ error: 'Something went wrong!' });
});


// --- Start Server ---
const server = app.listen(port, () => {
    console.log(`Server listening on port ${port}`);
    console.log(`Ensure your .env file is configured correctly (see Section 1.6 & 4).`);
    if (!process.env.INFOBIP_BASE_URL || !process.env.INFOBIP_API_KEY || !process.env.INFOBIP_2FA_APP_ID || !process.env.INFOBIP_2FA_MSG_ID) {
        console.warn('WARNING: Infobip environment variables are not fully set! OTP functionality will likely fail.');
    }
});

// Export app for testing purposes (See Section 13)
module.exports = app;

# .env (Update these lines)
INFOBIP_BASE_URL=YOUR_COPIED_BASE_URL
INFOBIP_API_KEY=YOUR_COPIED_API_KEY

# Infobip 2FA Configuration (Obtained in Section 4.2)
INFOBIP_2FA_APP_ID=YOUR_COPIED_APPLICATION_ID # From step 4.2a response
INFOBIP_2FA_MSG_ID=YOUR_COPIED_MESSAGE_ID   # From step 4.2b response

# Application Port
PORT=3000