Implement SMS 2FA with Vonage Verify API in RedwoodJS: Complete OTP Guide

+-------------+       +-----------------+       +-----------------+       +--------+       +-------------+
| User Browser| ----> | Redwood Web     | ----> | Redwood API     | ----> | Vonage | ----> | User's Phone|
| (React UI)  |       | (React, Apollo) |       | (GraphQL, Prisma|       | Verify |       | (SMS)       |
+-------------+       +-----------------+       |  Vonage SDK)    |       | API    |       +-------------+
      |                     |                     +-------+---------+       +--------+
      | Login Form          | GQL Mutation Call           |
      | OTP Form            |                             | Call Vonage API
      |                     |                             | Verify Code
      |                     |                             |
      |                     |                             |
      +---------------------+-----------------------------+
                            | Database (Prisma)
                            +-----------------+

yarn create redwood-app ./redwood-vonage-otp
cd redwood-vonage-otp

yarn rw setup auth dbAuth

// api/db/schema.prisma

model User {
  id                  Int       @id @default(autoincrement())
  email               String    @unique
  hashedPassword      String
  salt                String
  resetToken          String?
  resetTokenExpiresAt DateTime?
  webAuthnChallenge   String?   @unique

  // Add these fields for OTP
  phoneNumber         String?   // Optional: Add @unique if phone numbers must be unique. MUST be E.164 format (+14155551234)
  otpRequestId        String?   // Store the Vonage request ID temporarily
  otpVerifiedAt       DateTime? // Timestamp of the last successful OTP verification
  otpRequired         Boolean   @default(false) // Flag to indicate if OTP is enabled/required for the user

  sessions            UserSession[]
}

// ... rest of the schema (UserSession, UserCredential)

// Install: yarn workspace api add libphonenumber-js
import { parsePhoneNumber } from 'libphonenumber-js'

function normalizePhoneNumber(input: string, defaultCountry: string = 'US'): string {
  try {
    const phoneNumber = parsePhoneNumber(input, defaultCountry)
    if (!phoneNumber || !phoneNumber.isValid()) {
      throw new Error('Invalid phone number')
    }
    return phoneNumber.format('E.164') // Returns +14155551234
  } catch (error) {
    throw new Error(`Phone number normalization failed: ${error.message}`)
  }
}

// Usage in signup service:
const normalizedPhone = normalizePhoneNumber(input.phoneNumber, 'US')

yarn rw prisma migrate dev
# Name the migration (e.g., "add_otp_fields_to_user")

yarn workspace api add @vonage/server-sdk

# ./.env

# Database URL (already generated by Redwood)
DATABASE_URL="file:./dev.db" # Or your PostgreSQL/MySQL URL

# Vonage API Credentials
VONAGE_API_KEY="YOUR_VONAGE_API_KEY"
VONAGE_API_SECRET="YOUR_VONAGE_API_SECRET"

# Optional: Define a brand name for OTP messages
VONAGE_BRAND_NAME="YourAppName"

# Check .gitignore contains:
.env
.env.*
!.env.example

// api/src/lib/vonage.ts
import { Vonage } from '@vonage/server-sdk'
import { logger } from 'src/lib/logger' // Redwood's logger

if (!process.env.VONAGE_API_KEY || !process.env.VONAGE_API_SECRET) {
  const error = new Error(
    'Vonage API Key or Secret not found. Set VONAGE_API_KEY and VONAGE_API_SECRET in your .env file.'
  )
  logger.error({ error }, 'Vonage client initialization failed')
  throw error
}

let vonageInstance: Vonage

try {
  vonageInstance = new Vonage({
    apiKey: process.env.VONAGE_API_KEY,
    apiSecret: process.env.VONAGE_API_SECRET,
  })
  logger.info('Vonage client initialized successfully.')
} catch (error) {
  logger.error({ error }, 'Failed to create Vonage client instance')
  throw new Error('Vonage client initialization failed. Check API credentials.')
}

export const vonage = vonageInstance
export const vonageBrand = process.env.VONAGE_BRAND_NAME || 'MyApp'

// api/src/services/auth/auth.ts
import type { Prisma } from '@prisma/client'
import { AuthenticationError, ForbiddenError } from '@redwoodjs/graphql-server'
import { generateToken, hashPassword } from '@redwoodjs/auth-dbauth-api'

import { db } from 'src/lib/db'
import { logger } from 'src/lib/logger'
import { vonage, vonageBrand } from 'src/lib/vonage'

// Define custom result types for login to signal OTP requirement
interface LoginSuccessResult {
  __typename: 'CurrentUser'
  id: number
  email: string | null
}

interface OtpRequiredResult {
  __typename: 'OtpRequired'
  otpRequired: true
  userId: number
  message: string
}

type LoginResult = LoginSuccessResult | OtpRequiredResult

export const login = async ({
  username, // dbAuth uses 'username' which maps to email here
  password,
}: Prisma.UserWhereUniqueInput & {
  password?: string
}): Promise<LoginResult> => {
  const user = await db.user.findUnique({ where: { email: username } })

  if (!user) {
    throw new AuthenticationError('User not found.')
  }

  if (!user.hashedPassword || !user.salt) {
    throw new Error('User missing password credential.')
  }

  const passwordsMatch =
    (await hashPassword(password, user.salt)) === user.hashedPassword

  if (!passwordsMatch) {
    throw new AuthenticationError('Invalid password.')
  }

  // --- OTP Logic Start ---
  if (user.otpRequired && user.phoneNumber) {
    logger.info({ userId: user.id }, 'OTP required for user. Initiating Vonage verify request.')

    try {
      const result = await vonage.verify.start({
        number: user.phoneNumber,
        brand: vonageBrand,
        // Customize options: code_length (default 4), pin_expiry (default 300s)
        // code_length: 6,
        // pin_expiry: 180,
      })

      if (result.status === '0' && result.request_id) {
        // Successfully initiated OTP request, store the request ID
        await db.user.update({
          where: { id: user.id },
          data: { otpRequestId: result.request_id },
        })
        logger.info({ userId: user.id, requestId: result.request_id }, 'Vonage verify request initiated successfully.')

        return {
          __typename: 'OtpRequired',
          otpRequired: true,
          userId: user.id,
          message: 'OTP code sent to your phone. Enter the code to continue.',
        }
      } else {
        // Handle Vonage initiation errors
        logger.error({ userId: user.id, vonageError: result }, 'Vonage verify request initiation failed.')
        let errorMessage = `Failed to send OTP code (${result.status}): ${result.error_text || 'Unknown Vonage error'}`
        if (result.status === '3') {
          errorMessage = 'Invalid phone number format. Update your phone number in profile settings.'
        } else if (result.status === '101') {
           errorMessage = 'Verification service configuration error. Contact support.'
        }
        throw new AuthenticationError(errorMessage)
      }
    } catch (error) {
      logger.error({ userId: user.id, error }, 'Error during Vonage verify request initiation.')
       throw new AuthenticationError(
         'An unexpected error occurred while sending the OTP code. Try again later.'
       )
    }
  }
  // --- OTP Logic End ---

  logger.info({ userId: user.id }, 'OTP not required or bypassed. Proceeding with standard login.')

  // Return user data for session creation
  // Do NOT return sensitive info like hashedPassword
  return {
    __typename: 'CurrentUser',
    id: user.id,
    email: user.email,
  }
}

// --- Add verifyOtp Service Function ---
interface VerifyOtpInput {
  userId: number
  code: string
}

export const verifyOtp = async ({
  userId,
  code,
}: VerifyOtpInput): Promise<LoginSuccessResult> => {
  // 1. Fetch user and their pending otpRequestId
  const user = await db.user.findUnique({ where: { id: userId } })

  if (!user || !user.otpRequestId) {
    logger.warn({ userId }, 'Attempt to verify OTP without a pending request ID or user not found.')
    throw new AuthenticationError(
      'No pending OTP verification found or user invalid. Try logging in again.'
    )
  }

  logger.info({ userId, requestId: user.otpRequestId }, 'Attempting to verify OTP code with Vonage.')

  // 2. Call Vonage Verify Check API
  try {
    const result = await vonage.verify.check(user.otpRequestId, code)

    if (result.status === '0') {
      logger.info({ userId, requestId: user.otpRequestId }, 'Vonage OTP verification successful.')

      // Update user record: clear request ID, set verified timestamp
      await db.user.update({
        where: { id: user.id },
        data: {
          otpVerifiedAt: new Date(),
          otpRequestId: null,
        },
      })

      // Return user data to establish session
      return {
        __typename: 'CurrentUser',
        id: user.id,
        email: user.email,
      }
    } else {
      // Handle Vonage verification errors
      logger.warn({ userId, requestId: user.otpRequestId, vonageResult: result }, 'Vonage OTP verification failed.')

      let errorMessage = `OTP verification failed (${result.status}): ${result.error_text || 'Unknown error'}`
      if (result.status === '16') {
        errorMessage = 'The code you entered is incorrect. Try again.'
      } else if (result.status === '17') {
        errorMessage = 'The code has expired or too many attempts were made. Log in again to get a new code.'
      } else if (result.status === '6') {
        errorMessage = 'The verification request could not be found or has expired. Log in again.'
      }

      throw new AuthenticationError(errorMessage)
    }
  } catch (error) {
    logger.error({ userId, requestId: user.otpRequestId, error }, 'Error during Vonage verify check.')
    throw new AuthenticationError(
      'An unexpected error occurred during OTP verification. Try again later.'
    )
  }
}

// --- Keep/Update other functions like signup, getCurrentUser etc. ---
export const getCurrentUser = async (
  session: Record<string, unknown>
): Promise<Prisma.User | null> => {
  if (!session || typeof session.id !== 'number') {
    throw new AuthenticationError('Session invalid')
  }

  const user = await db.user.findUnique({
    where: { id: session.id as number },
    select: { id: true, email: true },
  })

  if (!user) {
     throw new AuthenticationError('User not found based on session')
  }

  return user
}

// Example: Modify signup to collect phone number and set otpRequired
export const signup = async (input: Prisma.UserCreateInput & { phoneNumber?: string, enableOtp?: boolean }) => {
  const { phoneNumber, enableOtp, ...userData } = input
  const hashedPassword = await hashPassword(userData.password)
  const salt = 'some-generated-salt' // Ensure proper salt generation logic exists

  const user = await db.user.create({
    data: {
      ...userData,
      hashedPassword: hashedPassword,
      salt: salt,
      phoneNumber: phoneNumber,
      otpRequired: !!enableOtp,
    },
    select: { id: true, email: true },
  })

  return user
}

// web/src/pages/LoginPage/LoginPage.tsx
const [login] = useMutation(LOGIN_MUTATION)

const onSubmit = async (data) => {
  const response = await login({ variables: data })

  if (response.data.login.__typename === 'OtpRequired') {
    sessionStorage.setItem('otpUserId', response.data.login.userId)
    navigate('/otp-verify')
  } else if (response.data.login.__typename === 'CurrentUser') {
    // Standard login success
    navigate('/dashboard')
  }
}

# api/src/graphql/auth.sdl.ts

# Type returned on successful login (standard or after OTP verification)
type CurrentUser {
  id: Int!
  email: String
}

# Type returned when OTP verification is required after password login
type OtpRequired {
  otpRequired: Boolean!
  userId: Int!
  message: String!
}

# Union type for the login mutation result
union LoginResult = CurrentUser | OtpRequired

type Mutation {
  # Update login return type to the Union
  login(username: String!, password: String!): LoginResult! @skipAuth

  # Add the new verifyOtp mutation
  verifyOtp(userId: Int!, code: String!): CurrentUser! @skipAuth

  logout: Boolean @requireAuth

  signup(input: SignupInput!): CurrentUser! @skipAuth
}

# Define input type for signup
input SignupInput {
  email: String!
  password: String!
  phoneNumber: String
  enableOtp: Boolean
}

yarn rw generate types

// api/src/lib/logger.ts
import * as Sentry from '@sentry/node'

if (process.env.NODE_ENV === 'production') {
  Sentry.init({
    dsn: process.env.SENTRY_DSN,
    environment: process.env.NODE_ENV,
  })
}

// Wrap critical functions
export const withErrorMonitoring = (fn) => {
  return async (...args) => {
    try {
      return await fn(...args)
    } catch (error) {
      Sentry.captureException(error)
      throw error
    }
  }
}

yarn workspace api add async-retry @types/async-retry

// Example within login service
import retry from 'async-retry';
import { vonage, vonageBrand } from 'src/lib/vonage';
import { logger } from 'src/lib/logger';
import { AuthenticationError } from '@redwoodjs/graphql-server';

try {
  const result = await retry(
    async (bail) => {
      logger.info('Attempting Vonage verify start...');
      const response = await vonage.verify.start({
         number: user.phoneNumber,
         brand: vonageBrand
      });

      // Don't retry on certain errors (e.g., invalid number format)
      if (response.status === '3') {
        bail(new Error(`Vonage non-retryable error status ${response.status}: ${response.error_text || 'Invalid number'}`));
        return;
      }
      if (response.status === '0') {
        return response;
      }
      // Throw error to trigger retry for other statuses
      throw new Error(`Vonage temporary error status ${response.status}: ${response.error_text || 'Unknown temporary error'}`);
    },
    {
      retries: 3,
      factor: 2,
      minTimeout: 1000,
      onRetry: (error, attempt) => {
        logger.warn(`Vonage verify start attempt ${attempt} failed: ${error.message}. Retrying...`);
      },
    }
  );
  // Handle successful result
  await db.user.update({
    where: { id: user.id },
    data: { otpRequestId: result.request_id },
  })

} catch (error) {
  logger.error({ userId: user.id, error }, 'Vonage verify start failed after retries or bailed.');
  const message = error instanceof Error ? error.message : 'Failed to initiate OTP verification.';
  throw new AuthenticationError(message);
}

// api/src/functions/cleanupExpiredOtp.ts
import { db } from 'src/lib/db'
import { logger } from 'src/lib/logger'

export const handler = async () => {
  const tenMinutesAgo = new Date(Date.now() - 10 * 60 * 1000)

  const result = await db.user.updateMany({
    where: {
      otpRequestId: { not: null },
      updatedAt: { lt: tenMinutesAgo },
    },
    data: {
      otpRequestId: null,
    },
  })

  logger.info({ count: result.count }, 'Cleaned up expired OTP request IDs')
  return { statusCode: 200, body: JSON.stringify({ cleaned: result.count }) }
}

import { z } from 'zod'

const phoneNumberSchema = z.string().regex(/^\+[1-9]\d{10,14}$/, 'Invalid E.164 phone number format')
const otpCodeSchema = z.string().regex(/^\d{4,6}$/, 'OTP code must be 4-6 digits')

// In service function:
phoneNumberSchema.parse(input.phoneNumber) // Throws if invalid
otpCodeSchema.parse(code)

yarn workspace api add redis ioredis

// api/src/lib/rateLimit.ts
import Redis from 'ioredis'
import { logger } from 'src/lib/logger'

const redis = new Redis(process.env.REDIS_URL)

export async function checkRateLimit(
  key: string,
  limit: number,
  windowSeconds: number
): Promise<{ allowed: boolean; remaining: number }> {
  const current = await redis.incr(key)

  if (current === 1) {
    await redis.expire(key, windowSeconds)
  }

  const allowed = current <= limit
  const remaining = Math.max(0, limit - current)

  if (!allowed) {
    logger.warn({ key, current, limit }, 'Rate limit exceeded')
  }

  return { allowed, remaining }
}

// Usage in login service:
const rateLimitKey = `otp:${user.phoneNumber}`
const { allowed } = await checkRateLimit(rateLimitKey, 3, 3600) // 3 requests per hour

if (!allowed) {
  throw new AuthenticationError('Too many OTP requests. Try again in 1 hour.')
}

# Generate strong session secret:
openssl rand -base64 32

yarn upgrade-interactive
yarn audit
yarn audit fix

const result = await vonage.verify.start({
  number: user.phoneNumber,
  brand: vonageBrand,
  pin_expiry: 180, // 3 minutes
});

yarn workspace api add otpauth qrcode

// api/src/services/auth/auth.ts
import { TOTP } from 'otpauth'

export const setupTOTP = async (userId: number) => {
  const user = await db.user.findUnique({ where: { id: userId } })

  const totp = new TOTP({
    issuer: 'YourAppName',
    label: user.email,
    algorithm: 'SHA1',
    digits: 6,
    period: 30,
  })

  // Store secret in database
  await db.user.update({
    where: { id: userId },
    data: { totpSecret: totp.secret.base32 },
  })

  // Return QR code URL for user to scan with authenticator app
  return totp.toString() // otpauth://totp/...
}

export const verifyTOTP = async (userId: number, token: string) => {
  const user = await db.user.findUnique({ where: { id: userId } })

  const totp = TOTP.fromSecret(user.totpSecret)
  const isValid = totp.validate({ token, window: 1 }) !== null

  if (!isValid) {
    throw new AuthenticationError('Invalid authenticator code')
  }

  return { success: true }
}

if (result.status === '3') {
  throw new AuthenticationError('Invalid phone number format. Use E.164 format.');
} else if (result.status === '16') {
  throw new AuthenticationError('Incorrect code. Try again.');
} else if (result.status === '17') {
  throw new AuthenticationError('Code expired. Request a new code.');
}

// api/src/services/auth/auth.test.ts
jest.mock('src/lib/vonage', () => ({
  vonage: {
    verify: {
      start: jest.fn().mockResolvedValue({
        status: '0',
        request_id: 'test-request-id-123',
      }),
      check: jest.fn().mockResolvedValue({
        status: '0',
      }),
    },
  },
  vonageBrand: 'TestApp',
}))

describe('verifyOtp', () => {
  it('successfully verifies correct OTP code', async () => {
    const result = await verifyOtp({
      userId: 1,
      code: '1234',
    })

    expect(result.__typename).toBe('CurrentUser')
    expect(result.id).toBe(1)
  })
})

// api/src/lib/vonage.ts
export const isDevelopmentBypass = process.env.NODE_ENV === 'development' &&
  process.env.VONAGE_BYPASS === 'true'

// In login service:
if (isDevelopmentBypass) {
  // Skip actual Vonage call, return mock success
  return {
    __typename: 'OtpRequired',
    otpRequired: true,
    userId: user.id,
    message: 'DEV MODE: Use code 1234',
  }
}

// api/src/services/auth/auth.scenarios.ts
export const standard = defineScenario({
  user: {
    one: {
      data: {
        email: 'test@example.com',
        hashedPassword: 'hashed',
        salt: 'salt',
        phoneNumber: '+14155551234',
        otpRequired: true,
      },
    },
  },
})

// api/src/services/auth/auth.test.ts
import { login, verifyOtp } from './auth'
import { standard } from './auth.scenarios'

scenario('login with OTP required', async (scenario) => {
  const result = await login({
    username: scenario.user.one.email,
    password: 'password123',
  })

  expect(result.__typename).toBe('OtpRequired')
  expect(result.userId).toBe(scenario.user.one.id)
})