Implementing Two-Factor Authentication (2FA) with Twilio Verify in RedwoodJS

yarn create redwood-app ./redwood-twilio-2fa
cd redwood-twilio-2fa

// api/db/schema.prisma

datasource db {
  provider = "postgresql" // Or your DB provider
  url      = env("DATABASE_URL")
}

generator client {
  provider      = "prisma-client-js"
  binaryTargets = "native"
}

# .env
DATABASE_URL=postgresql://user:password@host:port/database_name

yarn rw setup auth dbAuth

yarn rw prisma migrate dev --name "initial setup with dbAuth"

yarn workspace api add twilio

# .env

# Database URL (already added)
DATABASE_URL=postgresql://user:password@host:port/database_name

# RedwoodJS Session Secret (added by dbAuth setup)
SESSION_SECRET=your_strong_random_secret_here

# Twilio Credentials
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_VERIFY_SERVICE_SID=VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

yarn rw g service twilioVerify

// api/src/services/twilioVerify/twilioVerify.ts

import type { Prisma } from '@prisma/client'
import { Twilio } from 'twilio'
import { validate } from '@redwoodjs/api'

import { db } from 'src/lib/db' // Prisma client
import { logger } from 'src/lib/logger' // Redwood logger

// Initialize Twilio client (only if SIDs are present)
let twilioClient: Twilio | null = null
if (
  process.env.TWILIO_ACCOUNT_SID &&
  process.env.TWILIO_AUTH_TOKEN &&
  process.env.TWILIO_VERIFY_SERVICE_SID
) {
  twilioClient = new Twilio(
    process.env.TWILIO_ACCOUNT_SID,
    process.env.TWILIO_AUTH_TOKEN
  )
} else {
  logger.warn('Twilio environment variables not fully configured. 2FA features will be disabled.')
}

const TWILIO_VERIFY_SERVICE_SID = process.env.TWILIO_VERIFY_SERVICE_SID

/**
 * Sends an OTP verification code via SMS using Twilio Verify.
 * @param phoneNumber - The phone number in E.164 format (e.g., +15551234567)
 * @returns Promise resolving to the verification status ('pending' on success)
 * @throws Error if Twilio client is not configured or API call fails
 */
export const sendVerificationCode = async (
  phoneNumber: string
): Promise<string&gt; =&gt; {
  validate(phoneNumber, 'Phone Number', {
    presence: true,
    format: {
      pattern: /^\+[1-9]\d{1,14}$/, // Basic E.164 format check
      message: 'Phone number must be in E.164 format (e.g., +15551234567)',
    },
  })

  if (!twilioClient || !TWILIO_VERIFY_SERVICE_SID) {
    logger.error('Twilio client or Service SID is not configured.')
    throw new Error('Twilio configuration error. Cannot send verification code.')
  }

  logger.info(`Sending verification code to ${phoneNumber}`)
  try {
    const verification = await twilioClient.verify.v2
      .services(TWILIO_VERIFY_SERVICE_SID)
      .verifications.create({ to: phoneNumber, channel: 'sms' })

    logger.info(`Verification status for ${phoneNumber}: ${verification.status}`)
    return verification.status // Should be 'pending'
  } catch (error) {
    logger.error(
      { error },
      `Failed to send verification code to ${phoneNumber}`
    )
    // Consider re-throwing a more user-friendly error or handling specific Twilio errors
    throw new Error(`Twilio API error: ${error.message}`)
  }
}

/**
 * Checks the OTP code provided by the user against Twilio Verify.
 * @param phoneNumber - The phone number in E.164 format
 * @param code - The OTP code entered by the user
 * @returns Promise resolving to the verification check status ('approved' on success, 'incorrect' on failure, 'pending' if still processing)
 * @throws Error if Twilio client is not configured or API call fails unexpectedly
 */
export const checkVerificationCode = async (
  phoneNumber: string,
  code: string
): Promise<string&gt; =&gt; {
  validate(phoneNumber, 'Phone Number', {
      presence: true,
      format: {
          pattern: /^\+[1-9]\d{1,14}$/,
          message: 'Phone number must be in E.164 format (e.g., +15551234567)',
      },
  })
  validate(code, 'Verification Code', {
    presence: true,
    length: { min: 4, max: 10, message: 'Invalid code length' }, // Adjust based on your Twilio service settings
  })


  if (!twilioClient || !TWILIO_VERIFY_SERVICE_SID) {
    logger.error('Twilio client or Service SID is not configured.')
    throw new Error('Twilio configuration error. Cannot check verification code.')
  }

  logger.info(`Checking verification code for ${phoneNumber}`)
  try {
    const verificationCheck = await twilioClient.verify.v2
      .services(TWILIO_VERIFY_SERVICE_SID)
      .verificationChecks.create({ to: phoneNumber, code: code })

    logger.info(
      `Verification check status for ${phoneNumber}: ${verificationCheck.status}`
    )
    return verificationCheck.status // 'approved', 'pending', or 'canceled'
  } catch (error) {
    logger.error(
      { error },
      `Failed to check verification code for ${phoneNumber}`
    )
    // Twilio often returns 404 for incorrect/expired codes, resulting in an error here.
    // Check error status to provide clearer feedback than just 'pending'.
    if (error.status === 404) {
        logger.warn(`Verification check failed for ${phoneNumber}: Code likely incorrect or expired.`)
        return 'incorrect' // Return a specific status for wrong/expired code
    }
    // Re-throw other unexpected errors
    throw new Error(`Twilio API error: ${error.message}`)
  }
}

// We'll add GraphQL resolvers here in the next step
// These functions are the core logic; GraphQL resolvers will call them.

// api/src/graphql/twilioVerify.sdl.ts

export const schema = gql`
  type Mutation {
    """Enables 2FA for the currently logged-in user"""
    enableTwoFactor(phoneNumber: String!): User! @requireAuth

    """Disables 2FA for the currently logged-in user"""
    disableTwoFactor: User! @requireAuth

    """[Conceptual] Sends an OTP code (used during login verification)"""
    requestOtpVerification(phoneNumber: String!): String! @requireAuth(roles: ["USER_PENDING_2FA"])

    """[Conceptual] Verifies an OTP code during login"""
    verifyOtpAndLogIn(phoneNumber: String!, code: String!): AuthResult! @requireAuth(roles: ["USER_PENDING_2FA"])

    """Verifies an OTP code during 2FA setup"""
    verifyOtpForSetup(phoneNumber: String!, code: String!): User! @requireAuth
  }

  # We need a custom role or status (like USER_PENDING_2FA) to track users
  # who have passed password auth but are pending 2FA verification during login.
  # This requires modifying dbAuth's core logic in api/src/lib/auth.ts.
  # @requireAuth ensures a user is logged in for setup/disable.

  # The standard AuthResult or User type might need modification
  # if we want to return specific 2FA states.
`

// api/src/services/twilioVerify/twilioVerify.ts

// ... (import statements and previous functions: sendVerificationCode, checkVerificationCode) ...
import { requireAuth } from 'src/lib/auth' // Redwood's auth utilities
import { AuthenticationError, UserInputError } from '@redwoodjs/graphql-server' // Import UserInputError

// --- Mutations for managing 2FA Setup ---

export const twilioVerifyMutations = {
  /**
   * Enables 2FA: Sends verification code to user's phone for setup.
   * Stores phone number temporarily until verified.
   */
  enableTwoFactor: async ({ phoneNumber }: { phoneNumber: string }) => {
    requireAuth() // Ensure user is logged in
    const userId = context.currentUser.id

    // Basic E.164 format validation (consider libphonenumber-js for robustness)
    validate(phoneNumber, 'Phone Number', {
        presence: true,
        format: {
            pattern: /^\+[1-9]\d{1,14}$/,
            message: 'Phone number must be in E.164 format (e.g., +15551234567)',
        },
    })

    try {
      // Send the verification code first
      const status = await sendVerificationCode(phoneNumber)

      if (status !== 'pending') {
        throw new Error('Failed to initiate verification from Twilio.')
      }

      // Temporarily store phone number. Keep twoFactorEnabled false until verified.
      const user = await db.user.update({
        where: { id: userId },
        data: {
          phoneNumber: phoneNumber, // Store number for verification step
          twoFactorEnabled: false, // Not enabled yet
        },
      })

      logger.info(`Sent 2FA setup code to user ${userId} at ${phoneNumber}`)
      // Return user data, frontend will now prompt for code
      return user

    } catch (error) {
      logger.error({ error }, `Error enabling 2FA for user ${userId}`)
      // Use UserInputError for validation issues, AuthenticationError for others
      if (error.message.includes('E.164 format')) {
        throw new UserInputError(error.message)
      }
      throw new AuthenticationError(`Failed to enable 2FA: ${error.message}`)
    }
  },

  /**
   * Verifies the OTP code during the setup process.
   * If successful, marks 2FA as enabled for the user.
   */
  verifyOtpForSetup: async ({ phoneNumber, code }: { phoneNumber: string; code: string }) => {
    requireAuth()
    const userId = context.currentUser.id

    // Validate inputs
    validate(phoneNumber, 'Phone Number', { presence: true }) // Basic check
    validate(code, 'Verification Code', { presence: true })

    try {
        // Retrieve the user to ensure the phone number matches what we have stored
        const user = await db.user.findUnique({ where: { id: userId }})
        if (!user || user.phoneNumber !== phoneNumber) {
            // Don't reveal if user exists, just state the problem
            throw new AuthenticationError('Cannot verify OTP for this phone number at this time.')
        }
        if (user.twoFactorEnabled) {
            // Already enabled, maybe an accidental double-click?
            logger.warn(`User ${userId} attempted to verify setup but 2FA is already enabled.`)
            return user; // Return current state
        }

      const status = await checkVerificationCode(phoneNumber, code)

      if (status === 'approved') {
        // Verification successful! Mark 2FA as enabled.
        const updatedUser = await db.user.update({
          where: { id: userId },
          data: {
            twoFactorEnabled: true,
          },
        })
        logger.info(`Successfully enabled 2FA for user ${userId}`)
        return updatedUser
      } else if (status === 'incorrect') {
         logger.warn(`Failed 2FA setup verification for user ${userId} (Status: ${status})`)
         throw new UserInputError('Invalid or expired verification code.')
      } else {
        // Handle other statuses ('pending', 'canceled', or errors from checkVerificationCode)
        logger.warn(`Failed 2FA setup verification for user ${userId} (Status: ${status})`)
        throw new AuthenticationError('Could not verify code. Please try again.')
      }
    } catch (error) {
      logger.error({ error }, `Error verifying 2FA setup code for user ${userId}`)
      // Avoid leaking specific Twilio errors to the client if possible
      if (error instanceof UserInputError) { throw error } // Re-throw validation errors
      throw new AuthenticationError(error.message || 'Failed to verify code.')
    }
  },

  /**
   * Disables 2FA for the currently logged-in user.
   */
  disableTwoFactor: async () => {
    requireAuth()
    const userId = context.currentUser.id

    try {
      const updatedUser = await db.user.update({
        where: { id: userId },
        data: {
          twoFactorEnabled: false,
          phoneNumber: null, // Clear phone number when disabling
        },
      })
      logger.info(`Disabled 2FA for user ${userId}`)
      return updatedUser
    } catch (error) {
      logger.error({ error }, `Error disabling 2FA for user ${userId}`)
      throw new Error('Failed to disable 2FA.') // Use generic Error or AuthenticationError
    }
  },

  // --- Mutations for Login Flow (Conceptual - Requires dbAuth modification) ---

  /**
   * [Conceptual] Sends OTP after successful password login IF 2FA is enabled.
   * This would likely be called *internally* by a modified dbAuth authenticate function.
   * Requires careful security implementation.
   */
   requestOtpVerification: async ({ phoneNumber }: { phoneNumber: string }) => {
    // IMPORTANT: This mutation requires significant security considerations and
    // modification of the core dbAuth flow (api/src/lib/auth.ts).
    // It should ONLY be callable when the user is in a specific 'pending 2FA' state
    // after successful password auth. The conceptual role check represents this.
    requireAuth({ roles: ["USER_PENDING_2FA"] }) // Conceptual role check
    const userId = context.currentUser.id // User should be partially authenticated

    validate(phoneNumber, 'Phone Number', { presence: true, format: { pattern: /^\+[1-9]\d{1,14}$/ } })

    const user = await db.user.findUnique({ where: { id: userId } });
    if (!user || !user.twoFactorEnabled || user.phoneNumber !== phoneNumber) {
        logger.error(`Attempt to request OTP for user ${userId} with invalid state or phone number.`);
        throw new AuthenticationError('Cannot request OTP verification at this time.');
    }

    logger.info(`Requesting OTP for login verification for user ${userId}`);
    try {
        const status = await sendVerificationCode(phoneNumber);
        if (status !== 'pending') {
            throw new Error('Failed to send verification code via Twilio.');
        }
        return status; // Return 'pending'
    } catch (error) {
        logger.error({ error }, `Error sending OTP during login for user ${userId}`);
        throw new AuthenticationError('Failed to send verification code.');
    }
  },

  /**
   * [Conceptual] Verifies OTP during login and completes the session.
   * Requires the 'pending 2FA' state and deep integration with dbAuth session management.
   */
  verifyOtpAndLogIn: async ({ phoneNumber, code }: { phoneNumber: string; code: string }) => {
    // IMPORTANT: Similar security considerations and dbAuth modification requirements
    // as requestOtpVerification apply here.
    requireAuth({ roles: ["USER_PENDING_2FA"] }) // Conceptual role check
    const userId = context.currentUser.id

    validate(phoneNumber, 'Phone Number', { presence: true })
    validate(code, 'Verification Code', { presence: true })

    const user = await db.user.findUnique({ where: { id: userId } });
    if (!user || !user.twoFactorEnabled || user.phoneNumber !== phoneNumber) {
        logger.error(`Attempt to verify OTP for user ${userId} with invalid state or phone number.`);
        throw new AuthenticationError('Cannot verify OTP at this time.');
    }

    logger.info(`Verifying OTP during login for user ${userId}`);
    try {
        const status = await checkVerificationCode(phoneNumber, code);

        if (status === 'approved') {
            logger.info(`User ${userId} successfully verified OTP for login.`);
            // CRITICAL TODO: Integrate with dbAuth session management.
            // This involves updating the session state to fully authenticated,
            // clearing the 'pending 2FA' status, and returning the expected
            // AuthResult structure defined by dbAuth's `auth.ts`.
            // The exact implementation depends heavily on how dbAuth is modified.
            return {
                // This structure MUST match dbAuth's expected return type upon
                // successful authentication. It likely includes user id, email, roles etc.
                // Omitting sensitive data like hashedPassword is crucial.
                id: user.id,
                email: user.email,
                roles: context.currentUser?.roles, // Pass existing roles if needed
                // Potentially add other fields expected by dbAuth
            } as any; // Cast as 'any' is TEMPORARY - Needs proper typing matching dbAuth.

        } else if (status === 'incorrect') {
            logger.warn(`Failed OTP login verification for user ${userId} (Status: ${status})`);
            throw new UserInputError('Invalid or expired verification code.');
        } else {
             logger.warn(`Failed OTP login verification for user ${userId} (Status: ${status})`);
             throw new AuthenticationError('Could not verify code. Please try again.');
        }
    } catch (error) {
        logger.error({ error }, `Error verifying OTP during login for user ${userId}`);
        if (error instanceof UserInputError) { throw error }
        throw new AuthenticationError(error.message || 'Failed to verify code.');
    }
  }
}

// Export the mutations for Redwood's GraphQL handler
export const twilioVerify = { ...twilioVerifyMutations }

// api/db/schema.prisma

model User {
  id               Int       @id @default(autoincrement())
  email            String    @unique
  hashedPassword   String? // Made optional by dbAuth setup
  salt             String? // Made optional by dbAuth setup
  resetToken       String?
  resetTokenExpiresAt DateTime?

  // Add these fields for 2FA
  twoFactorEnabled Boolean   @default(false)
  phoneNumber      String?   @unique // Store in E.164 format, make unique
                                     // Nullable: only set when 2FA is enabled/pending.
  // Optional: Add fields for recovery codes if implementing that feature
  // recoveryCodes    String[]

  createdAt        DateTime  @default(now())
  updatedAt        DateTime  @updatedAt
}

# Create the migration file
yarn rw prisma migrate dev --name ""add 2fa fields to user""

# Review the generated SQL in the migrations folder (optional but recommended)
# Apply the migration (if not done automatically by the previous command)
# yarn rw prisma migrate deploy