SMS Verification Implementation: Engineering Guide for Developers & QA

// ❌ WRONG - Predictable, biased distribution
$code = rand(100000, 999999);

// ✅ CORRECT - Cryptographically secure, uniform distribution
use random_int; // PHP example
$code = random_int(100000, 999999);

// ✅ BETTER - Avoids leading zeros confusion
$code = str_pad(random_int(0, 999999), 6, '0', STR_PAD_LEFT);

// ✅ BEST - Separate generation and formatting
$bytes = random_bytes(3); // 24 bits
$number = unpack('N', "\x00" . $bytes)[1] & 0xFFFFFF;
$code = sprintf('%06d', $number);

CREATE TABLE sms_verifications (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
phone_number VARCHAR(20) NOT NULL, -- E.164 format
code_hash VARCHAR(255) NOT NULL, -- bcrypt/scrypt hash
purpose VARCHAR(50) NOT NULL, -- 'registration', 'password_reset', 'transaction'
session_id VARCHAR(255), -- Link to user session
ip_address INET, -- For rate limiting
user_agent TEXT, -- For fraud detection
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
expires_at TIMESTAMPTZ NOT NULL,
verified_at TIMESTAMPTZ,
attempts SMALLINT DEFAULT 0,
last_attempt_at TIMESTAMPTZ,
delivered_at TIMESTAMPTZ, -- From DLR webhook
carrier_status VARCHAR(50), -- Delivery status
provider_message_id VARCHAR(255), -- For tracking
INDEX idx_phone_created (phone_number, created_at),
INDEX idx_expires (expires_at) WHERE verified_at IS NULL
);

# Python/Redis example
import redis
from datetime import timedelta

class SMSRateLimiter:
def __init__(self):
self.redis = redis.Redis()

def check_rate_limit(self, phone_number, ip_address):
# Level 1: Per phone number (24h window)
phone_key = f"sms:phone:{phone_number}"
phone_count = self.redis.incr(phone_key)
if phone_count == 1:
self.redis.expire(phone_key, 86400) # 24 hours
if phone_count > 10: # Max 10/day per number
return False

# Level 2: Per IP address (1h window)
ip_key = f"sms:ip:{ip_address}"
ip_count = self.redis.incr(ip_key)
if ip_count == 1:
self.redis.expire(ip_key, 3600) # 1 hour
if ip_count > 5: # Max 5/hour per IP
return False

# Level 3: Global burst protection (1 minute)
global_key = "sms:global:minute"
global_count = self.redis.incr(global_key)
if global_count == 1:
self.redis.expire(global_key, 60)
if global_count > 100: # Max 100/minute globally
return False

return True

// Node.js/Express example
app.post('/verify', async (req, res) => {
const { phoneNumber, code } = req.body;
const ip = req.ip;

// 1. Input validation
if (!isValidE164(phoneNumber) || !/^\d{6}$/.test(code)) {
return res.status(400).json({ error: 'Invalid input' });
}

// 2. Find active verification
const verification = await db.sms_verifications.findOne({
phone_number: phoneNumber,
verified_at: null,
expires_at: { $gt: new Date() }
}).sort({ created_at: -1 });

if (!verification) {
// Always return same error to prevent enumeration
await new Promise(resolve => setTimeout(resolve, 500)); // Constant time
return res.status(400).json({ error: 'Invalid or expired code' });
}

// 3. Check attempt limits
if (verification.attempts >= 5) {
return res.status(429).json({ error: 'Too many attempts' });
}

// 4. Verify code (constant-time comparison)
const isValid = await bcrypt.compare(code, verification.code_hash);

// 5. Update attempts (even on success for audit)
await db.sms_verifications.updateOne(
{ _id: verification._id },
{
$inc: { attempts: 1 },
$set: { last_attempt_at: new Date() }
}
);

if (!isValid) {
await new Promise(resolve => setTimeout(resolve, 500)); // Constant time
return res.status(400).json({ error: 'Invalid or expired code' });
}

// 6. Mark as verified
await db.sms_verifications.updateOne(
{ _id: verification._id },
{ $set: { verified_at: new Date() } }
);

res.json({ success: true });
});

import { PhoneInput } from 'react-phone-input-2';
import 'react-phone-input-2/lib/style.css';

const SMSVerificationForm = () => {
const [phone, setPhone] = useState('');
const [code, setCode] = useState('');
const [countdown, setCountdown] = useState(0);

const validatePhone = (value) => {
// E.164 format validation
const regex = /^\+[1-9]\d{1,14}$/;
return regex.test(value);
};

const handleSendCode = async () => {
if (!validatePhone(phone)) {
alert('Please enter a valid phone number');
return;
}

// Start countdown (60 seconds)
setCountdown(60);
const interval = setInterval(() => {
setCountdown(prev => {
if (prev <= 1) {
clearInterval(interval);
return 0;
}
return prev - 1;
});
}, 1000);

// API call
try {
await fetch('/api/send-code', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ phoneNumber: phone })
});
} catch (error) {
setCountdown(0); // Reset on error
}
};

return (
<div>
<PhoneInput
country={'us'}
value={phone}
onChange={setPhone}
inputProps={{ required: true }}
/>
<button
onClick={handleSendCode}
disabled={countdown > 0}
>
{countdown > 0 ? `Resend in ${countdown}s` : 'Send Code'}
</button>
<input
type="text"
value={code}
onChange={(e) => setCode(e.target.value.replace(/\D/g, '').slice(0, 6))}
placeholder="Enter 6-digit code"
maxLength={6}
/>
</div>
);
};

# Pytest example for security testing
import pytest
import time
from security_test_utils import measure_time_variation

def test_brute_force_protection():
"""Test that 5 failed attempts block further attempts"""
phone = "+1234567890"

# Send 5 wrong codes
for i in range(5):
response = verify_code(phone, "000000")
assert response.status_code == 400

# 6th attempt should be blocked
response = verify_code(phone, "000000")
assert response.status_code == 429 # Too Many Requests

def test_time_based_attack():
"""Verify constant-time comparison"""
valid_code = "123456"
invalid_code = "000000"

# Measure response times
valid_times = []
invalid_times = []

for _ in range(100):
start = time.perf_counter_ns()
verify_code("+1234567890", valid_code)
valid_times.append(time.perf_counter_ns() - start)

start = time.perf_counter_ns()
verify_code("+1234567890", invalid_code)
invalid_times.append(time.perf_counter_ns() - start)

# Statistical test for timing difference
variation = measure_time_variation(valid_times, invalid_times)
assert variation < 0.1 # Less than 10% variation

def test_code_predictability():
"""Test that codes are not predictable"""
codes = []
for _ in range(10000):
codes.append(generate_code())

# Check distribution uniformity
digit_distribution = analyze_digit_distribution(codes)
for digit in range(10):
assert 0.09 < digit_distribution[digit] < 0.11 # ~10% each