Implementing AWS SNS OTP for Two-Factor Authentication in RedwoodJS

+-------------+       +-----------------+       +-----------------+       +---------+       +-------------+
| User        | ----> | Redwood Web UI  | ----> | Redwood API     | ----> | dbAuth  | ----> | Database    |
| (Browser)   |       | (React)         |       | (GraphQL/Lambda)|       | (Login) |       | (Prisma)    |
+-------------+       +-----------------+       +-----------------+       +---------+       +-------------+
      |                                               |  |  ^                                     |
      | 1. Login Request (Email/Pass)                 |  |  |                                     |
      |                                               |  |  | 2. Verify Credentials               |
      |                                               |  |  |                                     |
      |                                               |  |  v 3. Check if 2FA Enabled           |
      |                                               |  |--------------------------------------> |
      |                                               |                                         |
      |                                               | 4. If 2FA Enabled:                      |
      |                                               |    a. Generate OTP                      |
      |                                               |    b. Send OTP via AWS SNS              |
      |                                               |    c. Hash OTP & Store Hash/Expiry      |
      |                                               |---------+                               |
      |                                                         |                               |
      |                                                         v                               |
      |                                               +-----------------+                       |
      |                                               | AWS SNS Service |                       |
      |                                               +-----------------+                       |
      |                                                         |                               |
      |                                                         v 5. Send SMS OTP               |
      |                                               +-----------------+                       |
      |<--------------------------------------------- | User's Phone    | <---------------------+
      | 6. User Receives OTP                          +-----------------+
      |
      | 7. User Submits OTP via Web UI
      |
      |------------> Redwood Web UI -------------> Redwood API (Verify OTP) -----> Database (Check OTP Hash/Expiry)
                                                            |
                                                            | 8. If Valid: Grant Full Access
                                                            | 9. If Invalid: Deny Access / Retry

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

yarn rw setup auth dbAuth

// api/db/schema.prisma

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

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

model User {
  id                  Int       @id @default(autoincrement())
  email               String    @unique
  hashedPassword      String
  salt                String
  resetToken          String?
  resetTokenExpiresAt DateTime?
  roles               String?   @default("user") // Optional: For role-based access

  // --- 2FA Fields ---
  phoneNumber         String?   @unique // Store in E.164 format (e.g., +12223334444)
  twoFactorEnabled    Boolean   @default(false)
  otpSecret           String?   // Stores the securely HASHED OTP secret
  otpExpiresAt        DateTime? // Store expiry time for the OTP
  otpAttempts         Int?      @default(0) // Track failed attempts
  // --- End 2FA Fields ---

  // Optional: Add other user profile fields as needed
  name                String?
  createdAt           DateTime  @default(now())
  updatedAt           DateTime  @updatedAt
}

yarn rw prisma migrate dev --name add-2fa-fields

yarn workspace api add @aws-sdk/client-sns bcrypt @types/bcrypt

# .env (at the root of your project)

# Database URL (already present from Redwood setup)
DATABASE_URL="postgresql://user:password@localhost:5432/redwood_sns_otp?schema=public"

# --- AWS SNS Configuration ---
# Replace with your actual AWS credentials and region
AWS_ACCESS_KEY_ID="YOUR_AWS_ACCESS_KEY_ID"
AWS_SECRET_ACCESS_KEY="YOUR_AWS_SECRET_ACCESS_KEY"
AWS_REGION="us-east-1" # e.g., us-east-1, eu-west-2
AWS_SNS_SENDER_ID="MyBrandOTP" # Optional: A custom sender ID (requires registration in some regions)
# --- End AWS SNS Configuration ---

# Optional: Redwood Logger Level
LOG_LEVEL="info"

yarn rw g service otp

// api/src/services/otp/otp.ts

import crypto from 'crypto' // Use Node's crypto module for secure random generation
import bcrypt from 'bcrypt'
import { SNSClient, PublishCommand } from '@aws-sdk/client-sns'
import type { Prisma } from '@prisma/client'
import { db } from 'src/lib/db'
import { requireAuth } from 'src/lib/auth' // Use Redwood's auth checker
import { logger } from 'src/lib/logger' // Use Redwood's logger

const OTP_LENGTH = 6 // Standard OTP length
const OTP_VALIDITY_MINUTES = 5 // How long the OTP is valid
const MAX_OTP_ATTEMPTS = 5 // Max verification attempts
const BCRYPT_SALT_ROUNDS = 10 // Cost factor for bcrypt hashing

// Initialize SNS Client (ensure AWS env vars are set)
const snsClient = new SNSClient({
  region: process.env.AWS_REGION,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  },
})

/**
 * Generates a cryptographically secure random numeric string using Node's crypto module.
 */
const generateOtpCode = (length: number): string => {
  let otp = ''
  for (let i = 0; i < length; i++) {
    // crypto.randomInt is preferred over Math.random() for security-sensitive numbers
    otp += crypto.randomInt(0, 10).toString()
  }
  return otp
}

/**
 * Sends an OTP code via AWS SNS.
 */
const sendOtpSms = async (phoneNumber: string, otpCode: string) => {
  // Ensure E.164 format for SNS
  if (!phoneNumber || !phoneNumber.match(/^\+[1-9]\d{1,14}$/)) {
    logger.error({ custom: { phoneNumber } }, 'Invalid or missing phone number for SNS. Must be E.164.')
    throw new Error('Invalid phone number format. Must start with +countrycode.')
  }

  const brandName = process.env.AWS_SNS_SENDER_ID || 'YourApp' // Use sender ID or fallback
  const message = `Your ${brandName} verification code is: ${otpCode}. It expires in ${OTP_VALIDITY_MINUTES} minutes.`

  const params = {
    Message: message,
    PhoneNumber: phoneNumber,
    // Optional: Add MessageAttributes for SenderID if registered and required
    // MessageAttributes: {
    //   'AWS.SNS.SMS.SenderID': {
    //     'DataType': 'String',
    //     'StringValue': process.env.AWS_SNS_SENDER_ID
    //   },
    //   'AWS.SNS.SMS.SMSType': {
    //      'DataType': 'String',
    //      'StringValue': 'Transactional' // Or 'Promotional'
    //   }
    // }
  }

  try {
    logger.info({ custom: { phoneNumber } }, 'Attempting to send OTP via SNS')
    const command = new PublishCommand(params)
    const data = await snsClient.send(command)
    logger.info({ custom: { messageId: data.MessageId, phoneNumber } }, 'Successfully sent OTP via SNS')
    return data
  } catch (error) {
    logger.error({ err: error, custom: { phoneNumber } }, 'Failed to send OTP via SNS')
    // Handle specific SNS errors if needed (e.g., throttling, invalid number)
    throw new Error('Failed to send verification code. Please try again later.')
  }
}

/**
 * Mutation: Initiates the OTP request process for the logged-in user.
 * Requires the user to have 2FA enabled and a phone number set.
 */
export const requestOtp = async () => {
  requireAuth() // Ensure user is logged in
  const userId = context.currentUser.id

  const user = await db.user.findUnique({ where: { id: userId } })

  if (!user) {
    throw new Error('User not found.') // Should not happen if requireAuth passes
  }

  if (!user.twoFactorEnabled || !user.phoneNumber) {
    throw new Error('Two-factor authentication is not enabled or phone number is missing.')
  }

  // --- Basic Rate Limiting Check (Example) ---
  // Production systems *must* implement more robust IP-based and user-based rate limiting
  // (e.g., using Redis with leaky/token bucket algorithms, or platform-specific middleware)
  // to prevent SMS toll fraud and abuse. This example only checks expiry.
  if (user.otpExpiresAt && user.otpExpiresAt > new Date()) {
     const secondsRemaining = Math.ceil((user.otpExpiresAt.getTime() - Date.now()) / 1000);
     logger.warn({ custom: { userId } }, `OTP request denied. Previous OTP still valid for ${secondsRemaining} seconds.`);
     throw new Error(`Please wait ${secondsRemaining} seconds before requesting a new code.`);
  }
  // --- End Rate Limiting Check ---


  const otpCode = generateOtpCode(OTP_LENGTH)
  const expiresAt = new Date(Date.now() + OTP_VALIDITY_MINUTES * 60 * 1000)

  try {
    // 1. Send the plain OTP via SMS first
    await sendOtpSms(user.phoneNumber, otpCode)

    // 2. Hash the OTP for secure storage
    const hashedOtp = await bcrypt.hash(otpCode, BCRYPT_SALT_ROUNDS)

    // 3. Store the HASHED OTP and expiry in the database
    await db.user.update({
      where: { id: userId },
      data: {
        otpSecret: hashedOtp, // Store the hash, not the plain code
        otpExpiresAt: expiresAt,
        otpAttempts: 0, // Reset attempts on new code generation
      },
    })

    logger.info({ custom: { userId } }, 'OTP requested successfully.')
    // Return limited info to the client
    return { success: true, message: `Verification code sent to ${user.phoneNumber.slice(0, -4)}****.` }

  } catch (error) {
    logger.error({ err: error, custom: { userId } }, 'Error during OTP request process.')
    // Avoid clearing DB fields here, as the user might still need to retry.
    // Let expiry handle cleanup eventually.
    throw new Error('Failed to request verification code. Please try again.')
  }
}

/**
 * Mutation: Verifies the OTP code submitted by the user.
 */
interface VerifyOtpInput {
  otpCode: string
}

export const verifyOtp = async ({ otpCode }: VerifyOtpInput) => {
  requireAuth()
  const userId = context.currentUser.id

  if (!otpCode || otpCode.length !== OTP_LENGTH || !/^\d+$/.test(otpCode)) {
      throw new Error('Invalid OTP format.');
  }

  const user = await db.user.findUnique({ where: { id: userId } })

  if (!user || !user.twoFactorEnabled) {
    throw new Error('User not found or 2FA not enabled.')
  }

  // otpSecret now holds the HASH
  if (!user.otpSecret || !user.otpExpiresAt) {
    throw new Error('No active OTP request found. Please request a new code.')
  }

  // --- Attempt Limiting ---
  if (user.otpAttempts >= MAX_OTP_ATTEMPTS) {
    logger.warn({ custom: { userId } }, 'Max OTP attempts exceeded.');
    // Clear the current OTP to force requesting a new one after too many failures
    await db.user.update({
      where: { id: userId },
      data: { otpSecret: null, otpExpiresAt: null, otpAttempts: null },
    });
    throw new Error('Maximum verification attempts exceeded. Please request a new code.');
  }

  // --- Check Expiry ---
  if (new Date() > user.otpExpiresAt) {
    logger.warn({ custom: { userId } }, 'OTP expired attempt.');
     await db.user.update({
      where: { id: userId },
      data: {
          otpSecret: null, // Clear expired OTP hash
          otpExpiresAt: null,
          otpAttempts: (user.otpAttempts || 0) + 1, // Still count as an attempt
        },
    });
    throw new Error('Verification code has expired. Please request a new one.')
  }

  // --- Verify Code using bcrypt ---
  const isValid = await bcrypt.compare(otpCode, user.otpSecret)

  if (isValid) {
    // Success! Clear OTP fields
    await db.user.update({
      where: { id: userId },
      data: {
        otpSecret: null,
        otpExpiresAt: null,
        otpAttempts: null, // Reset attempts on success
      },
    })
    logger.info({ custom: { userId } }, 'OTP verified successfully.')
    // Note: Redwood's default dbAuth session cookie isn't typically modified
    // by this 2FA verification step. Application access control after login
    // relies on the frontend flow (redirecting to OTP page, then away upon success).
    // If persistent 2FA status within the session is needed, session handling
    // would need customization (more advanced).
    return { success: true, message: 'Verification successful.' }
  } else {
    // Invalid code
    await db.user.update({
      where: { id: userId },
      data: {
        otpAttempts: (user.otpAttempts || 0) + 1,
      },
    })
    logger.warn({ custom: { userId, attempts: (user.otpAttempts || 0) + 1 } }, 'Invalid OTP code entered.')
    throw new Error('Invalid verification code.')
  }
}

// Add other potential functions like disableTwoFactorAuth if needed

// api/src/graphql/otp.sdl.ts

export const schema = gql`
  type OtpResponse {
    success: Boolean!
    message: String
  }

  type Mutation {
    """
    Requests an OTP code to be sent via SMS to the user's registered phone number.
    Requires user to be authenticated and have 2FA enabled.
    """
    requestOtp: OtpResponse! @requireAuth

    """
    Verifies the OTP code submitted by the user against the stored hash.
    Requires user to be authenticated.
    """
    verifyOtp(otpCode: String!): OtpResponse! @requireAuth
  }
`

// api/src/functions/graphql.ts
// ... other imports
import services from 'src/services/**/*.{js,ts}' // Ensure this line includes your service

export const handler = createGraphQLHandler({
  // ... other config
  loggerConfig: { logger, options: {} },
  directives,
  sdls,
  services, // Make sure 'services' is passed here
  // ... onException
})

// web/src/components/TwoFactorSettingsCell/TwoFactorSettingsCell.tsx
// Generate this with `yarn rw g cell TwoFactorSettings`

import type { FindTwoFactorSettingsQuery, FindTwoFactorSettingsQueryVariables } from 'types/graphql'
import type { CellSuccessProps, CellFailureProps } from '@redwoodjs/web'
import { Form, TextField, Submit, FieldError, Label, useForm } from '@redwoodjs/forms'
import { useMutation } from '@redwoodjs/web'
import { toast } from '@redwoodjs/web/toast'
import { useState } from 'react'

// GraphQL Query to fetch user's current 2FA status
// NOTE: Assumes you have a query named `getCurrentUserSettings` in your SDL/Service.
export const QUERY = gql`
  query FindTwoFactorSettingsQuery {
    twoFactorSettings: getCurrentUserSettings {
      id
      phoneNumber
      twoFactorEnabled
    }
  }
`

// --- Mutations ---
// NOTE: Assumes you create these mutations in your SDL and Service (see example snippets below).
const ENABLE_2FA_MUTATION = gql`
  mutation EnableTwoFactorAuthMutation($phoneNumber: String!) {
    enableTwoFactorAuth(phoneNumber: $phoneNumber) {
      success
      message
      user { # Return updated user data
        id
        phoneNumber
        twoFactorEnabled
      }
    }
  }
`

const DISABLE_2FA_MUTATION = gql`
  mutation DisableTwoFactorAuthMutation {
    disableTwoFactorAuth {
      success
      message
       user {
        id
        phoneNumber
        twoFactorEnabled
      }
    }
  }
`
// --- End Mutations ---


export const Loading = () => <div>Loading...</div>

export const Empty = () => <div>User settings not found.</div>

export const Failure = ({ error }: CellFailureProps<FindTwoFactorSettingsQueryVariables>) => (
  <div style={{ color: 'red' }}>Error: {error?.message}</div>
)

export const Success = ({ twoFactorSettings }: CellSuccessProps<FindTwoFactorSettingsQuery, FindTwoFactorSettingsQueryVariables>) => {
  const [phoneNumber, setPhoneNumber] = useState(twoFactorSettings.phoneNumber || '')
  const formMethods = useForm()

  const [enable2FA, { loading: enableLoading }] = useMutation(ENABLE_2FA_MUTATION, {
    onCompleted: (data) => {
      if (data.enableTwoFactorAuth.success) {
        toast.success(data.enableTwoFactorAuth.message || '2FA Enabled!')
        setPhoneNumber(data.enableTwoFactorAuth.user.phoneNumber) // Update local state
        // QUERY refetch will update the cell state automatically
      } else {
        toast.error(data.enableTwoFactorAuth.message || 'Failed to enable 2FA.')
      }
    },
    onError: (error) => {
      toast.error(error.message)
    },
    // Refetch the user settings after mutation
    refetchQueries: [{ query: QUERY }],
    awaitRefetchQueries: true,
  })

 const [disable2FA, { loading: disableLoading }] = useMutation(DISABLE_2FA_MUTATION, {
    onCompleted: (data) => {
       if (data.disableTwoFactorAuth.success) {
        toast.success(data.disableTwoFactorAuth.message || '2FA Disabled!')
         setPhoneNumber('') // Clear local state
      } else {
        toast.error(data.disableTwoFactorAuth.message || 'Failed to disable 2FA.')
      }
    },
     onError: (error) => {
      toast.error(error.message)
    },
     refetchQueries: [{ query: QUERY }],
     awaitRefetchQueries: true,
  })


  const onEnableSubmit = (data) => {
    // Basic client-side format check (more robust validation server-side)
    if (!data.phoneNumber || !data.phoneNumber.match(/^\+[1-9]\d{1,14}$/)) {
       toast.error('Please enter a valid phone number in E.164 format (e.g., +15551234567).')
      return;
    }
    enable2FA({ variables: { phoneNumber: data.phoneNumber } })
  }

  const onDisableClick = () => {
     if(confirm('Are you sure you want to disable Two-Factor Authentication?')) {
        disable2FA()
     }
  }

  return (
    <div>
      <h2>Two-Factor Authentication (2FA)</h2>
      {twoFactorSettings.twoFactorEnabled ? (
        <div>
          <p>Status: <strong style={{color: 'green'}}>Enabled</strong></p>
          <p>Registered Phone: {twoFactorSettings.phoneNumber}</p>
          <button onClick={onDisableClick} disabled={disableLoading}>
             {disableLoading ? 'Disabling...' : 'Disable 2FA'}
          </button>
        </div>
      ) : (
        <div>
          <p>Status: <strong style={{color: 'red'}}>Disabled</strong></p>
          <p>Enable 2FA by adding your phone number below. A verification code will be sent via SMS for login confirmation.</p>
           <Form onSubmit={onEnableSubmit} formMethods={formMethods}>
             <Label name=""phoneNumber"" errorClassName=""error"">Phone Number (E.164 format: +1...)</Label>
             <TextField
                name=""phoneNumber""
                placeholder=""+15551234567""
                validation={{ required: true, pattern: { value: /^\+[1-9]\d{1,14}$/, message: ""Invalid E.164 format""} }}
                errorClassName=""error""
                defaultValue={phoneNumber} // Use state for controlled component if preferred
             />
             <FieldError name=""phoneNumber"" className=""error"" />

             <Submit disabled={enableLoading}>
               {enableLoading ? 'Enabling...' : 'Enable 2FA'}
             </Submit>
           </Form>
        </div>
      )}
    </div>
  )
}

// --- IMPORTANT: Backend Implementation Required ---
/*
  The above frontend component relies on GraphQL queries and mutations
  (`getCurrentUserSettings`, `enableTwoFactorAuth`, `disableTwoFactorAuth`)
  that you need to implement on the backend (API side).
  Follow the same pattern used for the OTP service/SDL. Here are example snippets:

// api/src/graphql/users.sdl.ts (o