SMS OTP Recipe

Send one-time passwords via SMS for phone number verification or two-factor authentication.

---

SMS OTP flow

Bearer mode

For native/mobile clients add X-Auth-Strategy: bearer to /auth/sms/verify to receive tokens in the JSON body.

---

Step 1: Configure SmsStrategy

Twilio

import { SmsStrategy } from '@nik2208/node-auth';

const smsStrategy = new SmsStrategy({
  sendSms: async (phoneNumber, code) => {
    await twilioClient.messages.create({
      to: phoneNumber,
      from: process.env.TWILIO_PHONE!,
      body: `Your verification code: ${code}`,
    });
  },
});

AWS SNS

import { SmsStrategy } from '@nik2208/node-auth';
import { SNSClient, PublishCommand } from '@aws-sdk/client-sns';

const sns = new SNSClient({ region: 'us-east-1' });

const smsStrategy = new SmsStrategy({
  sendSms: async (phoneNumber, code) => {
    await sns.send(new PublishCommand({
      PhoneNumber: phoneNumber,
      Message: `Your code: ${code}`,
    }));
  },
});

Built-in HTTP service

If you already have an HTTP SMS gateway, configure it directly in AuthConfig instead of implementing a strategy callback:

const auth = new AuthConfigurator({
  accessTokenSecret: '…',
  refreshTokenSecret: '…',
  sms: {
    endpoint:             'https://sms.yourprovider.com/send',
    apiKey:               process.env.SMS_API_KEY!,
    username:             process.env.SMS_USERNAME!,
    password:             process.env.SMS_PASSWORD!,
    codeExpiresInMinutes: 10,   // default: 10
  },
}, userStore);

The built-in SmsService makes a GET request to {endpoint}?username=…&password=…&phone=…&message=… with X-API-Key header. See SmsService below.

---

Step 2: Mount the router

app.use('/auth', auth.router({ smsStrategy }));

---

Step 3: Implement IUserStore methods

SMS OTP requires:

async updateSmsCode(userId: string, code: string | null, expiry: Date | null): Promise<void>

The user record must also have phoneNumber set.

---

Step 4: Test the flow

# Send OTP to user's phone
curl -X POST http://localhost:3000/auth/sms/send \
  -H 'Content-Type: application/json' \
  -d '{"userId":"123"}'

# Verify OTP code
curl -X POST http://localhost:3000/auth/sms/verify \
  -H 'Content-Type: application/json' \
  -d '{"userId":"123","code":"123456"}'

---

SmsService

The SmsService is exported and can be used directly in your own code:

import { SmsService } from '@nik2208/node-auth';

const smsService = new SmsService({
  endpoint:  'https://sms.yourprovider.com/send',
  apiKey:    process.env.SMS_API_KEY!,
  username:  process.env.SMS_USERNAME!,
  password:  process.env.SMS_PASSWORD!,
  codeExpiresInMinutes: 10,
});

// Send a custom SMS
await smsService.sendSms('+39123456789', 'Your verification code: 847261');

// Generate a random OTP code
const code = smsService.generateCode(6);  // '847261'

The service makes a GET request to {endpoint}?username={u}&password={p}&phone={phone}&message={msg} with an X-API-Key header.

---

SMS Endpoints

Method	Path	Description
POST	/auth/sms/send	Generate OTP + send to user's phoneNumber
POST	/auth/sms/verify	Verify OTP → issue session tokens