Engine: Auth - 2FA SMS OTP

[ollieread]

SMS OTP is a post-launch 2FA method that sends a one-time code to a verified phone number as the second factor. It implements the TwoFactorProvider contract.

Flow

1. When a 2FA challenge is triggered for a user with SMS OTP enabled, a short-lived numeric code is generated, hashed, and stored against the user with an expiry
2. The raw code is sent to the user's verified phone number via a configurable SMS provider
3. The user submits the code at the 2FA validation endpoint
4. The submitted code is verified against the stored hash and checked for expiry — on success the code is consumed and a RawToken is issued

A code that has expired or already been consumed cannot be used.

SMS Provider

SMS dispatch is handled via a SmsProvider contract, allowing different SMS gateway integrations to be swapped in without changing the OTP logic. The specific provider is configurable.

User Storage

The user requires a verified phone number. A phone_number field and a phone_verified_at timestamp are added to the User entity. A pending code table stores the hashed code, expiry, and consumed state per user.

Tasks

• Define SmsProvider contract
• Implement SmsOtpProvider satisfying the TwoFactorProvider contract
• Implement OTP code generation, hashing, and storage with expiry
• Implement SMS dispatch via SmsProvider
• Implement OTP verification including expiry and consumed checks
• Add phone_number and phone_verified_at to User
• Write tests for code generation and hashing
• Write tests for verification including expiry and consumed code rejection