Implement Node.js Express OTP 2FA with AWS SNS

Two-Factor Authentication (2FA) using One-Time Passwords (OTPs) sent via SMS is a common security layer for applications. This guide provides a step-by-step walkthrough for building an OTP verification system using Node.js, Express, and Amazon Simple Notification Service (AWS SNS).

We will build a simple REST API with two endpoints: one to request an OTP sent to a user's phone number via AWS SNS, and another to verify the OTP submitted by the user. This guide uses a simple in-memory object for storing OTPs for demonstration purposes; this approach is not suitable for production environments, where a persistent and scalable solution like Redis or a database with TTL capabilities should be used. The solution focuses on secure OTP generation, delivery, basic storage, verification logic including expiry and attempt limits, and robust error handling.

Technologies Used:

• Node.js: JavaScript runtime environment.
• Express.js: Minimalist web framework for Node.js, used to build the API.
• AWS SDK for JavaScript v3 (@aws-sdk/client-sns): To interact with AWS SNS for sending SMS messages.
• AWS Simple Notification Service (SNS): A managed messaging service used here to send OTP SMS messages reliably.
• dotenv: To manage environment variables securely.
• crypto: Node.js built-in module for secure random number generation (for OTPs).
• express-rate-limit: Middleware for basic brute-force protection on API endpoints.

System Architecture:

graph LR
    A[User Client (Mobile/Web)] -- Request OTP --> B(Express API Server);
    B -- Generate & Store OTP --> C{In-Memory Cache / Redis / DB};
    B -- Send OTP via SNS --> D(AWS SNS Service);
    D -- Send SMS --> E[User's Phone];
    A -- Submit OTP --> B;
    B -- Verify OTP against --> C;
    B -- Respond Success/Failure --> A;

    style D fill:#FF9900,stroke:#333,stroke-width:2px
    style B fill:#6DB33F,stroke:#333,stroke-width:2px

Prerequisites:

• Node.js and npm (or yarn) installed. Download Node.js
• An AWS Account. Create an AWS Account
• Basic understanding of Node.js, Express, REST APIs, and asynchronous JavaScript.
• A text editor or IDE (e.g., VS Code).
• A tool for testing APIs (e.g., cURL, Postman).

Final Outcome:

By the end of this guide, you will have a functional Express API capable of sending OTPs via SMS using AWS SNS and verifying them, incorporating basic security measures like rate limiting, OTP expiry, and attempt tracking. You will also understand the necessary AWS configurations and common pitfalls associated with using an in-memory store for demonstration.

1. Setting up the Project

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

1. Create Project Directory: Open your terminal and create a new directory for the project, then navigate into it.

   bashCopy

   mkdir express-sns-otp
   cd express-sns-otp

2. Initialize npm Project: This creates a package.json file.

   bashCopy

   npm init -y

3. Install Dependencies: We need Express for the server, the AWS SDK v3 for SNS, dotenv for environment variables, and express-rate-limit for security. The crypto module is built into Node.js and does not need to be installed.

   bashCopy

   npm install express @aws-sdk/client-sns dotenv express-rate-limit

   • express: Web framework.
   • @aws-sdk/client-sns: AWS SDK v3 client for SNS.
   • dotenv: Loads environment variables from a .env file.
   • crypto: Built-in Node module for cryptographic functions (used for secure OTP generation).
   • express-rate-limit: Basic rate limiting middleware.

4. Set Up Project Structure: Create the following directories and files for better organization:

   textCopy

   express-sns-otp/
   ├── node_modules/
   ├── .env                # Environment variables (AWS keys, region) - DO NOT COMMIT
   ├── .gitignore          # Specifies intentionally untracked files that Git should ignore
   ├── package.json
   ├── package-lock.json
   ├── server.js           # Main application entry point
   ├── controllers/
   │   └── authController.js # Handles request logic for OTP
   ├── routes/
   │   └── authRoutes.js   # Defines API routes
   ├── services/
   │   └── snsService.js   # Encapsulates AWS SNS interaction
   └── utils/
       └── otpHelper.js    # OTP generation and verification logic

   Create these directories:

   bashCopy

   mkdir controllers routes services utils

   Create the empty JavaScript files:

   bashCopy

   touch server.js controllers/authController.js routes/authRoutes.js services/snsService.js utils/otpHelper.js .env .gitignore

5. Configure .gitignore: Add node_modules and .env to your .gitignore file to prevent committing them to version control.

   textCopy

   # .gitignore
   node_modules
   .env

2. AWS Configuration

Before writing code, we need to configure AWS correctly.

1. Create an IAM User: It's best practice to use dedicated IAM users with specific permissions rather than your root AWS account. Note: The AWS Management Console interface changes periodically; these steps reflect a common flow but exact wording or layout might differ slightly.

   • Navigate to the IAM console in your AWS Management Console.
   • Go to Users and click Create user.
   • Enter a User name (e.g., sns-otp-sender).
   • Optionally, select Provide user access to the AWS Management Console if this user needs login access via the web interface. If selected, configure password settings (custom or auto-generated).
   • Click Next.
   • On the Set permissions page, select Attach policies directly.
   • Search for and select the AmazonSNSFullAccess policy. Note: For production, adhere to the principle of least privilege by creating a custom policy granting only the necessary sns:Publish permission.
   • Click Next.
   • Review the details and click Create user.

2. Get Access Keys:

   • After the user is created, click on the username in the user list.
   • Go to the Security credentials tab.
   • Scroll down to Access keys and click Create access key.
   • Select Application running outside AWS (or similar relevant option like ""Command Line Interface"") as the use case.
   • Click Next.
   • Optional: Add a description tag (e.g., express-sns-otp-app).
   • Click Create access key.
   • Crucial: Copy the Access key ID and Secret access key. The secret key is only shown once. Store them securely (e.g., in your .env file locally, or a secrets manager in production). You can also download the .csv file.

3. Configure Environment Variables: Open the .env file you created earlier and add your AWS credentials and the region you want to use for SNS.

   • Choose an AWS Region that supports SMS: Not all regions support SMS sending. Common choices include us-east-1 (N. Virginia), us-west-2 (Oregon), eu-west-1 (Ireland), ap-southeast-1 (Singapore), ap-southeast-2 (Sydney). Check the AWS documentation for supported regions.
   dotenvCopy

   # .env
   AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY_ID_HERE
   AWS_SECRET_ACCESS_KEY=YOUR_SECRET_ACCESS_KEY_HERE
   AWS_REGION=us-east-1 # Choose a region that supports SMS

   Replace placeholders with your actual credentials and chosen region.

4. Understand AWS SNS Sandbox:

   • By default, your AWS account is in the SNS sandbox. This means you can only send SMS messages to verified phone numbers.
   • To verify a number: Go to the SNS console -> Text messaging (SMS) -> Sandbox destinations -> Add phone number, and follow the verification process. You'll need this for testing initially.
   • To exit the sandbox: To send SMS to any number, you need to request a spending limit increase or move your account out of the sandbox. Go to SNS console -> Text messaging (SMS) -> Production environments (Request) or search for ""Service Quotas"" in the AWS Console, find SNS, and request an increase for ""SMS message spending quota"". This usually requires opening a support case and explaining your use case.

5. Set Default SMS Type (Recommended): For OTPs, you should use ""Transactional"" SMS type, which has higher deliverability and can often bypass Do Not Disturb (DND) settings.

   • Go to the SNS console -> Text messaging (SMS).
   • Under Account-level message settings, click Edit.
   • Ensure the Default SMS type is set to Transactional.
   • Save changes.

3. Implementing Core OTP Logic

We'll handle OTP generation, storage (in-memory for this example), and verification logic.

1. OTP Generation and Storage (utils/otpHelper.js): We'll create functions to generate a secure random OTP and manage an in-memory store.

   • Disclaimer: Using an in-memory object for OTP storage is suitable only for demonstration or very low-traffic scenarios. For production, use a persistent, scalable store like Redis (with TTL) or DynamoDB (with TTL).
   javascriptCopy

   // utils/otpHelper.js
   const crypto = require('crypto');
   
   // In-memory store for OTPs. !! Use Redis or a DB in production !!
   const otpStore = {}; // Structure: { ""phoneNumber"": { otp: ""123456"", expiry: 1678886400000, attempts: 0 } }
   
   const OTP_LENGTH = 6; // Standard OTP length
   const OTP_EXPIRY_MINUTES = 5; // OTP is valid for 5 minutes
   const MAX_VERIFY_ATTEMPTS = 3; // Max attempts to verify OTP
   
   /**
    * Generates a secure random OTP.
    * @returns {string} A numeric OTP string.
    */
   function generateOtp() {
       // Generate a random number and pad with leading zeros if necessary
       const otp = crypto.randomInt(0, Math.pow(10, OTP_LENGTH)).toString();
       return otp.padStart(OTP_LENGTH, '0');
   }
   
   /**
    * Stores the OTP details for a given phone number.
    * @param {string} phoneNumber - The user's phone number (key).
    * @param {string} otp - The generated OTP.
    */
   function storeOtp(phoneNumber, otp) {
       const expiry = Date.now() + OTP_EXPIRY_MINUTES * 60 * 1000; // Expiry time in milliseconds
       otpStore[phoneNumber] = {
           otp: otp,
           expiry: expiry,
           attempts: 0,
       };
       // Avoid logging OTPs in production environments for security.
       // console.log(`DEBUG: OTP for ${phoneNumber} stored. Expires: ${new Date(expiry).toLocaleTimeString()}`);
   }
   
   /**
    * Verifies the submitted OTP against the stored OTP.
    * @param {string} phoneNumber - The user's phone number.
    * @param {string} submittedOtp - The OTP submitted by the user.
    * @returns {{success: boolean, message: string}} Verification result.
    */
   function verifyOtp(phoneNumber, submittedOtp) {
       const record = otpStore[phoneNumber];
   
       if (!record) {
           return { success: false, message: 'OTP not found or expired. Please request a new one.' };
       }
   
       if (Date.now() > record.expiry) {
           delete otpStore[phoneNumber]; // Clean up expired OTP
           return { success: false, message: 'OTP has expired. Please request a new one.' };
       }
   
       if (record.attempts >= MAX_VERIFY_ATTEMPTS) {
           // Optionally lock the account or require a cooldown after too many attempts
           delete otpStore[phoneNumber]; // Invalidate OTP after max attempts
           return { success: false, message: 'Maximum verification attempts reached. Please request a new OTP.' };
       }
   
       if (record.otp === submittedOtp) {
           delete otpStore[phoneNumber]; // OTP is valid and used, remove it
           return { success: true, message: 'OTP verified successfully.' };
       } else {
           // Increment attempts only on incorrect OTP
           record.attempts += 1;
           otpStore[phoneNumber] = record; // Update the store with the new attempt count
           const attemptsLeft = MAX_VERIFY_ATTEMPTS - record.attempts;
           return { success: false, message: `Invalid OTP. ${attemptsLeft} attempts remaining.` };
       }
   }
   
   module.exports = {
       generateOtp,
       storeOtp,
       verifyOtp,
   };

4. Integrating AWS SNS

Now, let's create a service to handle sending SMS messages via AWS SNS.

1. SNS Service (services/snsService.js): This service uses the AWS SDK v3 (@aws-sdk/client-sns) to publish messages.

   javascriptCopy

   // services/snsService.js
   const { SNSClient, PublishCommand } = require('@aws-sdk/client-sns');
   require('dotenv').config(); // Ensure environment variables are loaded
   
   // Validate essential environment variables
   if (!process.env.AWS_ACCESS_KEY_ID || !process.env.AWS_SECRET_ACCESS_KEY || !process.env.AWS_REGION) {
       console.error('Error: AWS Credentials or Region not configured in .env file.');
       process.exit(1); // Stop the application if configuration is missing
   }
   
   // Configure the SNS Client
   const snsClient = new SNSClient({
       region: process.env.AWS_REGION,
       credentials: {
           accessKeyId: process.env.AWS_ACCESS_KEY_ID,
           secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
       }
   });
   
   /**
    * Sends an OTP SMS message using AWS SNS.
    * @param {string} phoneNumber - Destination phone number in E.164 format (e.g., +12223334444).
    * @param {string} otp - The One-Time Password to send.
    * @returns {Promise<object>} - The result from the SNS PublishCommand.
    * @throws {Error} - Throws an error if sending fails or phone number format is invalid.
    */
   async function sendOtpSms(phoneNumber, otp) {
       // --- IMPORTANT: Phone Number Formatting & Validation ---
       // AWS SNS requires phone numbers in E.164 format.
       // Example: +14155552671 (USA), +442071838750 (UK), +917700900077 (India)
       // Stricter validation matching controller: E.164 format with 10-15 digits after '+'
       if (!/^\+\d{10,15}$/.test(phoneNumber)) {
            throw new Error('Invalid phone number format. Use E.164 (e.g., +12223334444) with 10 to 15 digits.');
       }
   
       const message = `Your verification code is: ${otp}`;
   
       const params = {
           Message: message,
           PhoneNumber: phoneNumber,
           MessageAttributes: {
               'AWS.SNS.SMS.SMSType': { // Set SMSType to Transactional for higher deliverability
                   DataType: 'String',
                   StringValue: 'Transactional'
                },
               // 'AWS.SNS.SMS.SenderID': { // Optional: Use a custom Sender ID if registered and supported
               //     DataType: 'String',
               //     StringValue: 'MyAppName'
               // }
           }
       };
   
       try {
           const command = new PublishCommand(params);
           const data = await snsClient.send(command);
           console.log(`SNS Send Success to ${phoneNumber}. Message ID: ${data.MessageId}`);
           return data; // Contains MessageId
       } catch (error) {
           console.error(`Error sending SMS via SNS to ${phoneNumber}:`, error);
           // Rethrow or handle specific errors (e.g., throttling, invalid number)
           throw new Error(`Failed to send OTP SMS: ${error.message}`);
       }
   }
   
   module.exports = { sendOtpSms };

   • Key Point: Ensure the phoneNumber passed to sendOtpSms is strictly validated in E.164 format (e.g., +14155551234, +442071234567). The validation regex has been updated for consistency.

5. Building the API Layer

Let's create the Express routes and controllers to handle OTP requests and verification.

1. API Routes (routes/authRoutes.js): Define the endpoints /request-otp and /verify-otp.

   javascriptCopy

   // routes/authRoutes.js
   const express = require('express');
   const authController = require('../controllers/authController');
   const rateLimit = require('express-rate-limit');
   
   const router = express.Router();
   
   // Apply rate limiting to OTP requests to prevent abuse
   const otpLimiter = rateLimit({
       windowMs: 5 * 60 * 1000, // 5 minutes
       max: 5, // Limit each IP to 5 OTP requests per windowMs
       message: '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 verifyLimiter = rateLimit({
       windowMs: 15 * 60 * 1000, // 15 minutes
       max: 10, // Limit each IP to 10 verify requests per windowMs (higher than OTP req)
       message: 'Too many verification attempts from this IP, please try again after 15 minutes',
       standardHeaders: true,
       legacyHeaders: false,
   });
   
   // POST /api/auth/request-otp
   router.post('/request-otp', otpLimiter, authController.requestOtp);
   
   // POST /api/auth/verify-otp
   router.post('/verify-otp', verifyLimiter, authController.verifyOtp);
   
   module.exports = router;

2. Controller Logic (controllers/authController.js): Implement the functions to handle requests to the defined routes.

   javascriptCopy

   // controllers/authController.js
   const otpHelper = require('../utils/otpHelper');
   const snsService = require('../services/snsService');
   
   /**
    * Handles OTP request: Generates OTP, stores it, and sends via SNS.
    */
   async function requestOtp(req, res) {
       const { phoneNumber } = req.body;
   
       // Input Validation: E.164 format, 10-15 digits after '+'
       if (!phoneNumber || !/^\+\d{10,15}$/.test(phoneNumber)) {
           return res.status(400).json({ message: 'Invalid phone number format. Use E.164 (e.g., +12223334444) with 10 to 15 digits.' });
       }
   
       try {
           const otp = otpHelper.generateOtp();
           otpHelper.storeOtp(phoneNumber, otp); // Store OTP (in-memory in this example)
   
           // Send OTP via SMS using AWS SNS
           await snsService.sendOtpSms(phoneNumber, otp);
   
           // Send success response *after* SNS call succeeds
           res.status(200).json({ message: 'OTP sent successfully.' });
   
       } catch (error) {
           console.error('Error in requestOtp controller:', error);
           // Check for specific errors if needed (e.g., from snsService)
           // Provide a generic error to the client unless it's a specific input validation issue
            if (error.message.includes('Invalid phone number format')) {
                return res.status(400).json({ message: error.message }); // Propagate specific validation error
           }
           res.status(500).json({ message: 'Failed to send OTP due to an internal error. Please try again later.' });
       }
   }
   
   /**
    * Handles OTP verification: Checks submitted OTP against stored record.
    */
   async function verifyOtp(req, res) {
       const { phoneNumber, submittedOtp } = req.body;
   
       // Basic Input Validation
       if (!phoneNumber || !/^\+\d{10,15}$/.test(phoneNumber)) {
           return res.status(400).json({ message: 'Invalid phone number format. Use E.164 with 10 to 15 digits.' });
       }
       if (!submittedOtp || !/^\d{6}$/.test(submittedOtp)) { // Assuming 6-digit OTP
           return res.status(400).json({ message: 'Invalid OTP format. Must be a 6-digit number.' });
       }
   
       try {
           const result = otpHelper.verifyOtp(phoneNumber, submittedOtp);
   
           if (result.success) {
               res.status(200).json({ message: result.message });
           } else {
               // Use 400 Bad Request for client-side errors (invalid OTP, expired, max attempts)
               res.status(400).json({ message: result.message });
           }
       } catch (error) {
           console.error('Error in verifyOtp controller:', error);
           res.status(500).json({ message: 'An internal error occurred during OTP verification.' });
       }
   }
   
   module.exports = {
       requestOtp,
       verifyOtp,
   };

6. Tying it Together (server.js)

Set up the main Express application, load middleware, and mount the routes.

// server.js
const express = require('express');
require('dotenv').config(); // Load environment variables from .env file
const authRoutes = require('./routes/authRoutes');

// Basic Error Handling Middleware (Example)
function errorHandler(err, req, res, next) {
    console.error(""Global Error Handler:"", err.stack);
    // Avoid sending stack traces to the client in production
    res.status(500).json({ message: 'Something went wrong on the server!' });
}

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

// --- Middleware ---
// Parse JSON request bodies
app.use(express.json());

// --- Routes ---
// Mount the authentication routes under /api/auth
app.use('/api/auth', authRoutes);

// Basic Health Check Endpoint
app.get('/health', (req, res) => {
    res.status(200).json({ status: 'UP', timestamp: new Date().toISOString() });
});

// --- Global Error Handler ---
// Must be defined AFTER all other app.use() and routes calls
app.use(errorHandler);

// --- Start Server ---
app.listen(PORT, () => {
    console.log(`Server running on http://localhost:${PORT}`);
});

• We added express.json() middleware to parse incoming JSON requests.
• We mounted our authRoutes under the /api/auth prefix.
• A basic /health endpoint is included for monitoring.
• A simple global error handler is added as a fallback.

7. Adding Security Features

We've already included some security measures:

1. Input Validation: Checks are implemented in the controllers for phone number (E.164, length) and OTP formats (6 digits). For production, consider using a dedicated validation library like express-validator or joi for more complex rules.
2. Rate Limiting: express-rate-limit is applied to both endpoints in routes/authRoutes.js to mitigate brute-force attacks. Adjust the limits based on your expected traffic and risk tolerance.
3. OTP Expiry: OTPs automatically expire after OTP_EXPIRY_MINUTES (defined in utils/otpHelper.js) and are invalidated upon check.
4. Attempt Limiting: Verification attempts are tracked, and the OTP is invalidated after MAX_VERIFY_ATTEMPTS incorrect tries.
5. Secure Credential Handling: AWS credentials are kept out of the code using .env and loaded via dotenv. Ensure the .env file is never committed to version control. Use secrets management systems in production.
6. Transactional SMS: Using the 'Transactional' SMS type helps ensure delivery priority.
7. Security Headers: For a production web application, consider adding security headers using middleware like helmet.

8. (Optional) Database Layer Considerations

As strongly emphasized, the in-memory otpStore is not suitable for production.

Why use a database?

• Persistence: OTP data survives server restarts.
• Scalability: Handles many concurrent users and OTPs without consuming excessive server memory, crucial for stateless applications behind a load balancer.
• State Management: Allows tracking across multiple server instances.
• Reliable Expiry: Database TTL features are more robust than setTimeout.

Recommended Options:

1. Redis: An in-memory data structure store, excellent for caching and short-lived data like OTPs due to its speed and built-in key expiry (TTL) features.
   • Schema: Key: otp:<phoneNumber>, Value: Hash containing otp, attempts. Use Redis EXPIRE or SETEX command for automatic expiry.
2. DynamoDB: A fully managed NoSQL database service from AWS. Scalable and integrates well with the AWS ecosystem.
   • Schema: Table OTPSessions. Partition Key: phoneNumber (String). Attributes: otp (String), expiryTimestamp (Number - Unix epoch seconds), attempts (Number). Use DynamoDB TTL feature for automatic cleanup based on the expiryTimestamp.

Implementing these requires adding the respective database client library (redis, @aws-sdk/client-dynamodb), updating utils/otpHelper.js to interact with the database instead of the otpStore object, and managing database connections.

9. Performance Considerations

For this specific use case, the main performance factors are:

• AWS SNS Latency: SMS delivery times can vary based on carriers and network conditions. This is largely external to the application. Monitor SNS delivery logs if delays are suspected.
• Database Speed (if used): Using Redis or DynamoDB is generally very fast for OTP lookups/writes. Ensure proper indexing if using a relational database.
• OTP Generation: crypto.randomInt is efficient and non-blocking.
• Application Scalability: If using the in-memory store, the application is stateful and cannot be easily scaled horizontally. Using Redis/DB makes the application layer stateless, allowing scaling via multiple instances behind a load balancer.

10. Monitoring and Observability

For production environments:

• Logging: Implement structured logging (e.g., using winston or pino) to log requests, errors, and key events (OTP requested, SNS send status, verification success/failure) in a machine-readable format (JSON). Send logs to a centralized system (e.g., AWS CloudWatch Logs, Datadog, Splunk). Avoid logging sensitive data like OTPs.
• Metrics: Track API request latency (p50, p90, p99), error rates (HTTP 4xx, 5xx), SNS delivery success/failure rates (via CloudWatch Metrics for SNS), and OTP verification success/failure rates. Use tools like Prometheus/Grafana or CloudWatch Metrics dashboards.
• Health Checks: The /health endpoint can be used by load balancers or uptime monitoring services.
• Error Tracking: Integrate an error tracking service (e.g., Sentry, Bugsnag) to capture, aggregate, and alert on unhandled exceptions and significant errors.
• AWS SNS Delivery Status Logging: Configure SNS to log SMS delivery status to CloudWatch Logs for detailed troubleshooting of delivery issues. (SNS Console -> Text messaging (SMS) -> Delivery status logging -> Edit -> Create/use IAM roles -> Enable success/failure logging -> Save changes).

11. Troubleshooting and Caveats

Common issues when implementing AWS SNS for OTPs:

• InvalidParameter: Invalid parameter: PhoneNumber Reason: ... is not valid to publish to
  • Cause: Phone number not in E.164 format (missing +, invalid characters, incorrect length), invalid/blacklisted number, or sometimes non-printable characters copied from other sources.
  • Solution: Ensure strict E.164 validation (/^\+\d{10,15}$/) and sanitization on input. Test the number directly in the AWS SNS console (""Publish text message"").
• SMS Not Received (Sandbox Mode):
  • Cause: Account is in SNS sandbox, and the destination phone number isn't verified.
  • Solution: Verify the number in SNS console (Sandbox destinations) or request production access (see Section 2).
• SMS Not Received (Production Mode):
  • Cause: Incorrect E.164 format, DND active (less common for Transactional but possible), carrier filtering, invalid/inactive number, AWS region/service issues, SNS spending limits exceeded.
  • Solution: Verify format. Check SNS Delivery Status logs in CloudWatch (if enabled). Check AWS Service Health Dashboard. Ensure spending quotas aren't hit. Test with a different number/carrier.
• CredentialsError: Missing credentials in config / AccessDeniedException:
  • Cause: AWS credentials missing/incorrect in environment variables (.env or system env), or the IAM user lacks sns:Publish permission. dotenv might not be loaded early enough.
  • Solution: Verify .env file or environment variable settings. Confirm IAM user permissions. Ensure require('dotenv').config() runs before AWS SDK client initialization. Check AWS Region setting.
• Rate Limiting/Throttling:
  • Cause: Hitting AWS SNS publish rate limits, carrier limits, or triggering express-rate-limit.
  • Solution: Implement exponential backoff for retries on SNS publish errors (if needed). Adjust express-rate-limit settings. Request AWS quota increases if necessary.
• In-Memory Store Limitations: Server restarts clear all pending OTPs. Cannot scale horizontally across multiple instances. Not suitable for production.

12. Deployment Considerations

• Environment Variables: Securely configure production environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, NODE_ENV=production, PORT) on your deployment platform (e.g., AWS Secrets Manager, Systems Manager Parameter Store, platform-specific config). Never commit .env files or hardcode credentials.
• Platform Choices:
  • PaaS (Heroku, Render, AWS Elastic Beanstalk): Simplified deployment and management.
  • Containers (Docker + AWS ECS/EKS/Fargate, Google Cloud Run): Package the app for consistent environments and scaling. Requires Dockerfile setup.
  • Serverless (AWS Lambda + API Gateway): Refactor into Lambda functions. Highly scalable and potentially cost-effective, but requires architectural changes.
  • VMs (AWS EC2, Google Compute Engine): Full control but more setup/management overhead (OS, patching, process management).
• Process Management: Use a process manager like pm2 to run the Node.js application reliably, manage restarts, handle logs, and utilize multiple CPU cores (cluster mode).
  bashCopy

  # Install globally (or as dev dependency)
  npm install pm2 -g
  # Example pm2 start command (add to package.json scripts or run directly)
  # pm2 start server.js --name sns-otp-api -i max --no-daemon # Foreground for dev
  # pm2 start server.js --name sns-otp-api -i max             # Background for prod

• CI/CD: Implement a pipeline (e.g., GitHub Actions, GitLab CI, Jenkins, AWS CodePipeline) to automate testing, linting, building (if needed), and deploying to different environments (staging, production).

13. Verification and Testing

1. Start the Server:

   bashCopy

   node server.js

   Or using pm2 (foreground for easy stopping with Ctrl+C during dev):

   bashCopy

   pm2 start server.js --name sns-otp-api --no-daemon

2. Manual Testing (using cURL or Postman):

   • Requirement: Ensure the destination phone number is verified in the AWS SNS Sandbox if your account is still sandboxed. Replace +12223334444 with your verified E.164 formatted number.

   • Request OTP:

     bashCopy

     curl -X POST http://localhost:3000/api/auth/request-otp \
          -H ""Content-Type: application/json"" \
          -d '{""phoneNumber"": ""+12223334444""}' # Replace with your verified number
     
     # Expected Response (200 OK):
     # {""message"":""OTP sent successfully.""}

     Check your phone for the SMS. Check server logs for SNS success message (avoid logging OTP itself).

   • Verify OTP (Correct OTP): Replace 123456 with the actual OTP received.

     bashCopy

     curl -X POST http://localhost:3000/api/auth/verify-otp \
          -H ""Content-Type: application/json"" \
          -d '{""phoneNumber"": ""+12223334444"", ""submittedOtp"": ""123456""}' # Use received OTP
     
     # Expected Response (200 OK):
     # {""message"":""OTP verified successfully.""}

   • Verify OTP (Incorrect OTP):

     bashCopy

     curl -X POST http://localhost:3000/api/auth/verify-otp \
          -H ""Content-Type: application/json"" \
          -d '{""phoneNumber"": ""+12223334444"", ""submittedOtp"": ""000000""}'
     
     # Expected Response (400 Bad Request):
     # {""message"":""Invalid OTP. 2 attempts remaining.""}

     Repeat to test attempt limits.