Implementing OTP/2FA with Fastify and AWS SNS

+---------+       (1) Request OTP        +-----------------+      (3) Send SMS via SNS       +--------------+
|  User   | -------------------------> | Fastify Server  | -----------------------------> |   AWS SNS    | --(SMS)--> User's Phone
| Browser/|       (Phone Number)       | (Node.js App)   |      (OTP Code, Phone #)       +--------------+
|  App    |                            +-----------------+
+---------+                                |        ^
    |                                      | (2)    | (5)
    |                                      | Generate & Store OTP
    | (4) Submit OTP                       |        | Verify OTP
    | (Phone Number, OTP Code)             v        |
    |                                  +---------------+
    +------------------------------->  |  OTP Store    |
                                     | (Redis / Mem) |
                                     +---------------+

mkdir fastify-sns-otp
cd fastify-sns-otp
npm init -y

npm install fastify fastify-aws-sns @fastify/env @fastify/sensible @fastify/rate-limit ioredis @fastify/redis

npm install --save-dev pino-pretty tap sinon # tap & sinon for testing

mkdir src
mkdir src/routes
mkdir src/services
mkdir src/config
mkdir test
mkdir test/routes
touch src/server.js
touch src/app.js
touch src/routes/otp.js
touch src/services/otpService.js
touch src/config/environment.js
touch test/setup.js
touch test/routes/otp.test.js
touch .env
touch .env.example
touch .gitignore

# Dependencies
node_modules

# Environment Variables
.env
*.env.local
*.env.*.local

# Logs
*.log
logs
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*

# Build output
dist
build

# OS generated files
.DS_Store
Thumbs.db

// src/config/environment.js
const environmentSchema = {
  type: 'object',
  required: [
    'PORT',
    'HOST',
    'AWS_ACCESS_KEY_ID',
    'AWS_SECRET_ACCESS_KEY',
    'AWS_DEFAULT_REGION',
    // Optional but recommended for production
    // 'REDIS_URL'
  ],
  properties: {
    PORT: { type: 'string', default: '3000' },
    HOST: { type: 'string', default: '0.0.0.0' },
    AWS_ACCESS_KEY_ID: { type: 'string' },
    AWS_SECRET_ACCESS_KEY: { type: 'string' },
    AWS_DEFAULT_REGION: { type: 'string' }, // e.g., 'us-east-1'
    OTP_LENGTH: { type: 'integer', default: 6 }, // Removed from required as it has a default
    OTP_TTL_SECONDS: { type: 'integer', default: 300 }, // 5 minutes, removed from required as it has a default
    REDIS_URL: { type: 'string' }, // e.g., 'redis://localhost:6379'
    LOG_LEVEL: { type: 'string', default: 'info'}, // trace, debug, info, warn, error, fatal
    RATE_LIMIT_MAX_REQUESTS: { type: 'integer', default: 5 }, // Max requests per window
    RATE_LIMIT_WINDOW_MS: { type: 'integer', default: 60000 }, // Window size in milliseconds (1 minute)
    SNS_SMS_SENDER_ID: { type: 'string', default: 'MyApp'}, // Optional custom sender ID (max 11 chars, check regional support)
    SNS_SMS_TYPE: { type: 'string', default: 'Transactional' } // 'Transactional' or 'Promotional'
  }
};

export default environmentSchema;

# .env.example

# Server Configuration
PORT=3000
HOST=0.0.0.0
LOG_LEVEL=info

# AWS SNS Configuration
AWS_ACCESS_KEY_ID=YOUR_AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY=YOUR_AWS_SECRET_ACCESS_KEY
AWS_DEFAULT_REGION=us-east-1 # Change to your desired AWS region
SNS_SMS_SENDER_ID=MyApp # Optional: Custom Sender ID (check AWS docs for regional support & rules)
SNS_SMS_TYPE=Transactional # 'Transactional' for higher reliability, 'Promotional' for lower cost

# OTP Configuration
OTP_LENGTH=6
OTP_TTL_SECONDS=300 # 5 minutes

# Rate Limiting
RATE_LIMIT_MAX_REQUESTS=5
RATE_LIMIT_WINDOW_MS=60000 # 1 minute

# Redis Configuration (Recommended for Production)
# REDIS_URL=redis://localhost:6379

cp .env.example .env
# Now edit .env with your real credentials

// src/services/otpService.js
import crypto from 'node:crypto';

// --- In-Memory Store (Simple Example - Replace with Redis in Section 6) ---
const otpStore = new Map();

/**
 * Stores the OTP associated with a phone number in memory with TTL.
 * IMPORTANT: This is NOT suitable for production due to lack of persistence.
 * @param {import('fastify').FastifyInstance} fastify - Fastify instance for logging.
 * @param {string} phoneNumber - The user's phone number (key).
 * @param {string} otp - The OTP code (value).
 * @param {number} ttlSeconds - Time-to-live in seconds.
 */
async function storeOtpMemory(fastify, phoneNumber, otp, ttlSeconds) {
  const expiry = Date.now() + ttlSeconds * 1000;
  otpStore.set(phoneNumber, { otp, expiry });

  // Simple in-memory cleanup - Prone to issues if server restarts
  setTimeout(() => {
    const stored = otpStore.get(phoneNumber);
    if (stored && stored.otp === otp) { // Ensure we delete the correct OTP if regenerated quickly
        otpStore.delete(phoneNumber);
        fastify.log.info(`Expired OTP for ${phoneNumber} removed from memory.`);
    }
  }, ttlSeconds * 1000);

  fastify.log.info(`OTP ${otp} stored in memory for ${phoneNumber}, expires in ${ttlSeconds}s.`);
}

/**
 * Verifies the submitted OTP against the one stored in memory.
 * @param {import('fastify').FastifyInstance} fastify - Fastify instance for logging.
 * @param {string} phoneNumber - The user's phone number.
 * @param {string} submittedOtp - The OTP submitted by the user.
 * @returns {Promise<boolean>} True if OTP is valid and not expired, false otherwise.
 */
async function verifyOtpMemory(fastify, phoneNumber, submittedOtp) {
  const storedData = otpStore.get(phoneNumber);

  if (!storedData) {
    fastify.log.warn(`Verification failed: No OTP found in memory for ${phoneNumber}.`);
    return false; // No OTP found for this number
  }

  const { otp: storedOtp, expiry } = storedData;

  if (Date.now() > expiry) {
    fastify.log.warn(`Verification failed: OTP expired for ${phoneNumber}.`);
    otpStore.delete(phoneNumber); // Clean up expired OTP
    return false; // OTP expired
  }

  if (storedOtp === submittedOtp) {
    fastify.log.info(`Verification successful for ${phoneNumber}. Removing from memory.`);
    otpStore.delete(phoneNumber); // OTP is valid, remove it to prevent reuse
    return true; // OTP matches
  }

  fastify.log.warn(`Verification failed: Incorrect OTP for ${phoneNumber}.`);
  return false; // OTP does not match
}
// --- End In-Memory Store ---


/**
 * Generates a secure random OTP.
 * @param {number} length - The desired length of the OTP.
 * @returns {string} The generated OTP.
 */
function generateOtp(length) {
  // Ensure length is positive integer
  const otpLength = Math.max(1, Math.floor(length));
  // Calculate the minimum and maximum values for the OTP
  const min = Math.pow(10, otpLength - 1);
  const max = Math.pow(10, otpLength) - 1;
  // Generate a cryptographically secure random number within the range
  return (crypto.randomInt(min, max + 1)).toString().padStart(otpLength, '0');
}


// --- Redis-based Store (See Section 6 for implementation) ---
// Placeholder functions, will be implemented in Section 6
async function storeOtpRedis(fastify, phoneNumber, otp, ttlSeconds) {
    throw new Error('storeOtpRedis not implemented yet');
}
async function verifyOtpRedis(fastify, phoneNumber, submittedOtp) {
    throw new Error('verifyOtpRedis not implemented yet');
}
// --- End Redis Store ---


// Choose which store implementation to use based on Redis availability
// The actual selection logic will be in the route handlers or app setup
export {
    generateOtp,
    storeOtpMemory,
    verifyOtpMemory,
    storeOtpRedis, // Export Redis functions for later use
    verifyOtpRedis
};

// src/routes/otp.js
import {
    generateOtp,
    storeOtpMemory, // Using memory store initially
    verifyOtpMemory, // Using memory store initially
    storeOtpRedis,   // Will use these later
    verifyOtpRedis
} from '../services/otpService.js';

// --- Schemas ---
// Note on OTP pattern: Accessing fastify.config here is difficult as schemas
// are often defined at module load time before config is ready. Using process.env
// is a common workaround, though less ideal than using fastify.config directly.
// Ensure OTP_LENGTH is reliably set in the environment where the app runs.
const otpPattern = `^\\d{${process.env.OTP_LENGTH || 6}}`; // Default to 6 if env var not set *at load time*

const requestOtpSchema = {
  body: {
    type: 'object',
    required: ['phoneNumber'],
    properties: {
      // Basic E.164 format validation (adjust regex as needed for stricter rules)
      phoneNumber: { type: 'string', pattern: '^\\+[1-9]\\d{1,14}' }
    },
    additionalProperties: false
  },
  response: {
    200: {
      type: 'object',
      properties: {
        message: { type: 'string' },
        messageId: { type: 'string' } // From SNS
      }
    }
    // Fastify automatically handles 4xx/5xx based on @fastify/sensible
  }
};

const verifyOtpSchema = {
  body: {
    type: 'object',
    required: ['phoneNumber', 'otp'],
    properties: {
      phoneNumber: { type: 'string', pattern: '^\\+[1-9]\\d{1,14}' },
      otp: { type: 'string', pattern: otpPattern } // Use defined pattern
    },
    additionalProperties: false
  },
  response: {
    200: {
      type: 'object',
      properties: {
        success: { type: 'boolean' },
        message: { type: 'string' }
      }
    },
    400: { // Example explicit error response
        type: 'object',
        properties: {
            statusCode: { type: 'integer' },
            error: { type: 'string' },
            message: { type: 'string' }
        }
    }
    // Fastify automatically handles 4xx/5xx based on @fastify/sensible
  }
};
// --- End Schemas ---


async function otpRoutes(fastify, options) {
  // Apply rate limiting specifically to OTP routes
  const rateLimitOptions = {
    max: fastify.config.RATE_LIMIT_MAX_REQUESTS,
    timeWindow: fastify.config.RATE_LIMIT_WINDOW_MS,
    // Redis store will be added by the rate-limit plugin itself if Redis is available
  };

  // Determine which storage functions to use based on Redis availability
  const useRedis = !!fastify.redis;
  const storeOtp = useRedis ? storeOtpRedis : storeOtpMemory;
  const verifyOtp = useRedis ? verifyOtpRedis : verifyOtpMemory;

  if (useRedis) {
      fastify.log.info('OTP routes will use Redis for storage.');
  } else {
      fastify.log.warn('OTP routes using in-memory storage (NOT FOR PRODUCTION).');
  }

  // === Request OTP Endpoint ===
  fastify.post('/request-otp', { schema: requestOtpSchema, config: { rateLimit: rateLimitOptions } }, async (request, reply) => {
    const { phoneNumber } = request.body;
    const otp = generateOtp(fastify.config.OTP_LENGTH);
    const message = `Your verification code is: ${otp}`;

    // Check if Redis is required but unavailable
    if (!useRedis && fastify.config.REDIS_URL) {
        fastify.log.error(`Cannot request OTP for ${phoneNumber}: Redis configured but unavailable.`);
        throw fastify.httpErrors.serviceUnavailable('OTP service dependency temporarily unavailable. Please try again later.');
    }

    try {
      fastify.log.info(`Requesting OTP for ${phoneNumber}`);

      // Send OTP via AWS SNS using the plugin
      const snsResult = await fastify.snsSMS.publish({
        message: message,
        phoneNumber: phoneNumber,
        messageAttributes: { // Optional: Set message type and sender ID if needed
            'AWS.SNS.SMS.SMSType': {
                DataType: 'String',
                StringValue: fastify.config.SNS_SMS_TYPE // Transactional or Promotional
            },
            'AWS.SNS.SMS.SenderID': {
                DataType: 'String',
                StringValue: fastify.config.SNS_SMS_SENDER_ID // Custom Sender ID
            }
        }
      });

      fastify.log.info(`SNS publish successful for ${phoneNumber}, MessageID: ${snsResult.MessageId}`);

      // Store the OTP using the selected storage method
      await storeOtp(fastify, phoneNumber, otp, fastify.config.OTP_TTL_SECONDS);

      return reply.code(200).send({
          message: 'OTP requested successfully. Check your phone.',
          messageId: snsResult.MessageId
        });

    } catch (error) {
      fastify.log.error({ err: error, phoneNumber }, `Failed to send or store OTP for ${phoneNumber}`);

      // Check for specific known errors
      if (error.message?.includes('unavailable')) { // Check for our Redis unavailable errors
           throw fastify.httpErrors.serviceUnavailable('OTP service temporarily unavailable.');
      }
      if (error.code === 'InvalidParameterException') {
          // Often due to invalid phone number format for SNS region
          throw fastify.httpErrors.badRequest('Invalid phone number format or region unsupported.');
      }
      if (error.code === 'AuthorizationError' || error.code === 'AccessDenied') {
          throw fastify.httpErrors.internalServerError('SNS authorization configuration error.');
      }
       // Let @fastify/sensible handle generic errors
      throw fastify.httpErrors.internalServerError('Failed to process OTP request.');
    }
  });

  // === Verify OTP Endpoint ===
  fastify.post('/verify-otp', { schema: verifyOtpSchema, config: { rateLimit: rateLimitOptions } }, async (request, reply) => {
    const { phoneNumber, otp } = request.body;

    // Check if Redis is required but unavailable
    if (!useRedis && fastify.config.REDIS_URL) {
        fastify.log.error(`Cannot verify OTP for ${phoneNumber}: Redis configured but unavailable.`);
        throw fastify.httpErrors.serviceUnavailable('OTP service dependency temporarily unavailable. Please try again later.');
    }

    fastify.log.info(`Verifying OTP for ${phoneNumber}`);

    try {
      // Verify using the selected storage method
      const isValid = await verifyOtp(fastify, phoneNumber, otp);

      if (isValid) {
        return reply.code(200).send({ success: true, message: 'OTP verified successfully.' });
      } else {
         // Use a standard error response for failed verification
        throw fastify.httpErrors.badRequest('Invalid or expired OTP.');
      }
    } catch (error) {
       // Handle potential errors during verification (e.g., store connection issues)
       fastify.log.error({ err: error, phoneNumber }, `Error during OTP verification for ${phoneNumber}`);
       // Re-throw specific known errors or a generic one
       if (error.message?.includes('unavailable')) { // Check for our Redis unavailable errors
           throw fastify.httpErrors.serviceUnavailable('OTP service temporarily unavailable.');
       }
       if (error.statusCode) { // If it's already an HttpError from verifyOtp or elsewhere
           throw error;
       }
       throw fastify.httpErrors.internalServerError('Failed to verify OTP.');
    }
  });
}

export default otpRoutes;

// src/app.js
import Fastify from 'fastify';
import sensible from '@fastify/sensible';
import env from '@fastify/env';
import rateLimit from '@fastify/rate-limit';
import redisPlugin from '@fastify/redis'; // Renamed import for clarity
import awsSns from 'fastify-aws-sns';
import environmentSchema from './config/environment.js';
import otpRoutes from './routes/otp.js';

async function buildApp(options = {}) {
  const fastify = Fastify({
    logger: {
        level: process.env.LOG_LEVEL || 'info', // Default level before config loaded
        transport: process.env.NODE_ENV !== 'production'
            ? { target: 'pino-pretty' } // Pretty print logs in development
            : undefined,
    },
    ...options // Allow passing test-specific options
  });

  // 1. Register @fastify/env to load and validate environment variables
  await fastify.register(env, {
    dotenv: true, // Load .env file
    schema: environmentSchema,
    confKey: 'config' // Access variables via fastify.config
  });
  // Now fastify.config is available
  fastify.log.level = fastify.config.LOG_LEVEL; // Set final log level
  fastify.log.info(`Log level set to: ${fastify.config.LOG_LEVEL}`);

  // 2. Register @fastify/sensible for practical defaults (HTTP errors, etc.)
  await fastify.register(sensible);

  // 3. Register @fastify/redis *conditionally* BEFORE rate-limit if needed
  // This makes fastify.redis available if connection succeeds.
  let redisClient = null;
  if (fastify.config.REDIS_URL) {
    try {
      await fastify.register(redisPlugin, {
        url: fastify.config.REDIS_URL,
        closeClient: true // Close client when Fastify shuts down
        // Add other ioredis options here if needed
      });
      redisClient = fastify.redis; // Get the client instance
      fastify.log.info(`Redis connection registered: ${fastify.config.REDIS_URL}`);
    } catch (err) {
      fastify.log.error({ err }, 'Failed to connect to Redis. Rate limiting and OTP storage will use in-memory fallback.');
      // redisClient remains null
    }
  } else {
    fastify.log.warn('REDIS_URL not configured. Using in-memory OTP storage and rate limiting.');
  }

  // 4. Register @fastify/rate-limit *ONCE*, conditionally providing the Redis client
  // This registration happens AFTER @fastify/redis attempt.
  const rateLimitConfig = {
      global: false, // Apply limits per-route
      ...(redisClient && { redis: redisClient }) // Conditionally add redis client to config
  };
  await fastify.register(rateLimit, rateLimitConfig);
  if (redisClient) {
      fastify.log.info('Rate limiter configured to use Redis store.');
  } else {
      fastify.log.info('Rate limiter configured to use in-memory store.');
  }

  // 5. Register fastify-aws-sns plugin
  // It automatically picks up credentials from environment variables
  await fastify.register(awsSns);
  fastify.log.info('AWS SNS plugin registered. Using credentials from environment variables.');

  // 6. Register API Routes
  await fastify.register(otpRoutes, { prefix: '/api/v1' }); // Prefix routes with /api/v1

  // Graceful shutdown handler
  fastify.addHook('onClose', (instance, done) => {
    instance.log.info('Server closing. Closing connections...');
    // @fastify/redis handles its own closing via closeClient: true
    // Add other cleanup if needed
    done();
  });

  return fastify;
}

export default buildApp;

// src/server.js
import buildApp from './app.js';

async function start() {
  let app;
  try {
    // Build the app instance, environment variables are loaded within buildApp
    app = await buildApp();

    // Access config AFTER buildApp has run and registered @fastify/env
    const host = app.config.HOST;
    const port = app.config.PORT;

    // Start listening
    await app.listen({ port: parseInt(port, 10), host: host });

    // Log server start AFTER listen() is successful and logger is fully configured
    app.log.info(`Server listening on http://${host}:${port}`);
    app.log.info(`Using AWS Region: ${app.config.AWS_DEFAULT_REGION}`);
    if (app.redis) { // Check if redis client was successfully attached
        app.log.info(`Successfully connected to Redis for OTP Store & Rate Limiting: ${app.config.REDIS_URL}`);
    } else if (app.config.REDIS_URL) { // Redis was configured but failed
         app.log.warn(`Redis connection FAILED (${app.config.REDIS_URL}). Using in-memory storage/rate-limiting.`);
    } else { // Redis was not configured
        app.log.warn(`Redis not configured. Using in-memory storage/rate-limiting (NOT FOR PRODUCTION).`);
    }

  } catch (err) {
    // Log the error even if the full logger wasn't initialized
    console.error('Error starting server:', err);
    if (app && app.log) { // Check if logger exists
        app.log.fatal({ err }, 'Failed to start server');
    }
    process.exit(1);
  }

  // Handle Terminate signals for graceful shutdown
    const K_TERMINATE_SIGNALS = ['SIGINT', 'SIGTERM'];
    K_TERMINATE_SIGNALS.forEach(signal => {
        process.on(signal, async () => {
            try {
                console.log(`Received ${signal}. Shutting down gracefully...`);
                if (app) {
                    await app.close(); // Trigger Fastify's onClose hooks
                    console.log('Server closed.');
                }
                process.exit(0);
            } catch (err) {
                console.error('Error during graceful shutdown:', err);
                if (app && app.log) {
                    app.log.error({ err }, 'Error during shutdown.');
                }
                process.exit(1);
            }
        });
    });
}

start();

// package.json (scripts section excerpt)
  "scripts": {
    "start": "node src/server.js",
    "dev": "node --watch src/server.js | pino-pretty",
    "test": "tap \"test/**/*.test.js\""
  },

// src/services/otpService.js
import crypto from 'node:crypto';

// --- In-Memory Store (For fallback/comparison - see Section 3) ---
// ... (previous in-memory code remains here) ...