feat(otp): handle test OTPs and Twilio Verify on the one_time_tokens path

Restore the phone-provider branches removed from the parent PR. Test OTPs
keep the identifier lookup because they have no stored challenge. Twilio
Verify finds the challenge row by relates_to and asks Twilio to check the
code.

Author: annabkr

internal/api/verify.go

@@ -789,9 +789,20 @@ func (a *API) verifyUserAndToken(conn *storage.Connection, params *VerifyParams,
 // challenge in the one_time_tokens table and derives the user from that row,
 // instead of finding the user by identifier and comparing the users.*_token
 // columns. A lookup miss is rejected as an expired or invalid token; there is
-// no fallback to the users columns. Test OTPs and Twilio Verify are not handled
-// yet on this path; a follow-up PR adds them.
+// no fallback to the users columns.
 func (a *API) verifyUserAndTokenFromOTT(conn *storage.Connection, params *VerifyParams, aud string) (*models.User, error) {
+	config := a.config
+
+	// Twilio Verify and test OTPs are verified without a local challenge
+	if params.Type == smsVerification || params.Type == phoneChangeVerification {
+		if testOTP, ok := config.Sms.GetTestOTP(params.Phone, time.Now()); ok && params.Token == testOTP {
+			return a.findUserForTestOTP(conn, params, aud)
+		}
+		if !config.Hook.SendSMS.Enabled && config.Sms.IsTwilioVerifyProvider() {
+			return a.verifyPhoneWithTwilio(conn, params, aud)
+		}
+	}
+
 	ott, err := a.verifyOneTimeToken(conn, params)
 	if err != nil {
 		return nil, err
@@ -814,6 +825,72 @@ func (a *API) verifyUserAndTokenFromOTT(conn *storage.Connection, params *Verify
 	return user, nil
 }
 
+func (a *API) verifyPhoneWithTwilio(conn *storage.Connection, params *VerifyParams, aud string) (*models.User, error) {
+	tokenType := models.ConfirmationToken
+	if params.Type == phoneChangeVerification {
+		tokenType = models.PhoneChangeToken
+	}
+
+	ott, err := models.FindOneTimeTokenByRelatesTo(conn, params.Phone, tokenType)
+	if models.IsNotFoundError(err) {
+		return nil, apierrors.NewForbiddenError(apierrors.ErrorCodeOTPExpired, "Token has expired or is invalid").WithInternalError(err)
+	} else if err != nil {
+		return nil, apierrors.NewInternalServerError("Database error finding one time token").WithInternalError(err)
+	}
+
+	user, err := models.FindUserByID(conn, ott.UserID)
+	if models.IsNotFoundError(err) {
+		return nil, apierrors.NewForbiddenError(apierrors.ErrorCodeOTPExpired, "Token has expired or is invalid").WithInternalError(err)
+	} else if err != nil {
+		return nil, apierrors.NewInternalServerError("Database error finding user").WithInternalError(err)
+	}
+
+	pendingPhone := user.GetPhone()
+	if params.Type == phoneChangeVerification {
+		pendingPhone = user.PhoneChange
+	}
+	if pendingPhone != params.Phone {
+		return nil, apierrors.NewForbiddenError(apierrors.ErrorCodeOTPExpired, "Token has expired or is invalid").WithInternalMessage("user phone does not match")
+	}
+	if user.Aud != aud {
+		return nil, apierrors.NewForbiddenError(apierrors.ErrorCodeOTPExpired, "Token has expired or is invalid").WithInternalMessage("user audience does not match")
+	}
+	if user.IsBanned() {
+		return nil, apierrors.NewForbiddenError(apierrors.ErrorCodeUserBanned, "User is banned")
+	}
+	if err := a.verifyOTPWithTwilio(params.Phone, params.Token); err != nil {
+		return nil, apierrors.NewForbiddenError(apierrors.ErrorCodeOTPExpired, "Token has expired or is invalid").WithInternalError(err)
+	}
+	return user, nil
+}
+
+// findUserForTestOTP resolves the user for a phone verification whose code
+// matched a configured test OTP. A test OTP has no local challenge.
+func (a *API) findUserForTestOTP(conn *storage.Connection, params *VerifyParams, aud string) (*models.User, error) {
+	var user *models.User
+	var err error
+
+	switch params.Type {
+	case phoneChangeVerification:
+		user, err = models.FindUserByPhoneChangeAndAudience(conn, params.Phone, aud)
+	case smsVerification:
+		user, err = models.FindUserByPhoneAndAudience(conn, params.Phone, aud)
+	default:
+		// The caller only routes phone types here, so in practice this should never happen.
+		return nil, apierrors.NewInternalServerError("Test OTP lookup called for non-phone verification type %q", params.Type)
+	}
+	if models.IsNotFoundError(err) {
+		return nil, apierrors.NewForbiddenError(apierrors.ErrorCodeOTPExpired, "Token has expired or is invalid").WithInternalError(err)
+	} else if err != nil {
+		return nil, apierrors.NewInternalServerError("Database error finding user").WithInternalError(err)
+	}
+
+	if user.IsBanned() {
+		return nil, apierrors.NewForbiddenError(apierrors.ErrorCodeUserBanned, "User is banned")
+	}
+	return user, nil
+}
+
 func (a *API) verifyOneTimeToken(conn *storage.Connection, params *VerifyParams) (*models.OneTimeToken, error) {
 	tokenTypes := verifyTypeToTokenTypes(params.Type)
 	if len(tokenTypes) == 0 {
@@ -844,6 +921,23 @@ func (a *API) verifyOneTimeToken(conn *storage.Connection, params *VerifyParams)
 	return ott, nil
 }
 
+// verifyOTPWithTwilio asks Twilio Verify to check the code. Twilio generates
+// and delivers its own code, so there is no local challenge to compare.
+func (a *API) verifyOTPWithTwilio(phone, code string) error {
+	smsProvider, err := sms_provider.GetSmsProvider(*a.config)
+	if err != nil {
+		return apierrors.NewInternalServerError("Failed to get SMS provider").WithInternalError(err)
+	}
+	twilioVerify, ok := smsProvider.(*sms_provider.TwilioVerifyProvider)
+	if !ok {
+		return apierrors.NewInternalServerError("SMS provider is not Twilio Verify")
+	}
+	if err := twilioVerify.VerifyOTP(phone, code); err != nil {
+		return apierrors.NewForbiddenError(apierrors.ErrorCodeOTPExpired, "Token has expired or is invalid").WithInternalError(err)
+	}
+	return nil
+}
+
 func verifyTypeToTokenTypes(verifyType string) []models.OneTimeTokenType {
 	switch verifyType {
 	case mail.EmailOTPVerification:

internal/api/verify_ott_parity_test.go

@@ -9,8 +9,11 @@ import (
 
 	"github.com/gofrs/uuid"
 	"github.com/stretchr/testify/require"
+	"gopkg.in/h2non/gock.v1"
 
 	"github.com/supabase/auth/internal/api/apierrors"
+	"github.com/supabase/auth/internal/api/sms_provider"
+	"github.com/supabase/auth/internal/conf"
 	"github.com/supabase/auth/internal/crypto"
 	mail "github.com/supabase/auth/internal/mailer"
 	"github.com/supabase/auth/internal/models"
@@ -24,12 +27,13 @@ import (
 // in the fixtures.
 
 const (
-	parityOTP       = "123456"
-	parityEmail     = "test@example.com"
-	parityPhone     = "12345678"
-	parityNewEmail  = "new@example.com"
-	parityNewPhone  = "1234567890"
-	parityForbidden = "Token has expired or is invalid"
+	parityOTP        = "123456"
+	parityEmail      = "test@example.com"
+	parityPhone      = "12345678"
+	parityNewEmail   = "new@example.com"
+	parityNewPhone   = "1234567890"
+	parityForbidden  = "Token has expired or is invalid"
+	twilioServiceSid = "VA-parity-test"
 )
 
 // otpParityOutcome is everything a client or an operator can observe after a
@@ -276,6 +280,53 @@ func (ts *VerifyTestSuite) TestVerifyOTPParityPhoneFlows() {
 			},
 			expected: phoneChanged,
 		},
+		{
+			// A test OTP is accepted without any stored challenge. This is the
+			// path app store reviewers and CI rely on.
+			desc: "sms with a test OTP succeeds with no stored challenge",
+			configure: func() func() {
+				return ts.configureTestOTP(parityPhone, parityOTP)
+			},
+			seed: func(u *models.User) map[string]interface{} {
+				return phoneOTPBody(smsVerification, parityPhone)
+			},
+			expected: phoneSignedUp,
+		},
+		{
+			desc: "sms with a wrong code falls through the test OTP check and is rejected",
+			configure: func() func() {
+				return ts.configureTestOTP(parityPhone, "000000")
+			},
+			seed: func(u *models.User) map[string]interface{} {
+				return phoneOTPBody(smsVerification, parityPhone)
+			},
+			expected: forbidden,
+		},
+		{
+			// Twilio Verify generates and delivers its own code, so the locally
+			// stored hash never matches what the user types. Twilio's answer
+			// is the only thing that counts.
+			desc: "sms with Twilio Verify accepts a code Twilio approves",
+			configure: func() func() {
+				return ts.configureTwilioVerify(map[string]interface{}{"status": "approved", "valid": true})
+			},
+			seed: func(u *models.User) map[string]interface{} {
+				ts.seedChallenge(u, models.ConfirmationToken, parityPhone, crypto.GenerateTokenHash(parityPhone, "999999"), now, time.Hour)
+				return phoneOTPBody(smsVerification, parityPhone)
+			},
+			expected: phoneSignedUp,
+		},
+		{
+			desc: "sms with Twilio Verify rejects a code Twilio does not approve",
+			configure: func() func() {
+				return ts.configureTwilioVerify(map[string]interface{}{"status": "pending", "valid": false})
+			},
+			seed: func(u *models.User) map[string]interface{} {
+				ts.seedChallenge(u, models.ConfirmationToken, parityPhone, phoneHash, now, time.Hour)
+				return phoneOTPBody(smsVerification, parityPhone)
+			},
+			expected: forbidden,
+		},
 	}
 
 	ts.runOTPParityCases(cases)
@@ -330,7 +381,7 @@ func (ts *VerifyTestSuite) runOTPParityCases(cases []otpParityCase) {
 
 // seedChallenge stores hash in the users column and the one_time_tokens row
 // for tokenType, mirroring what the send paths write. relatesTo is the address
-// or number the code was sent to.
+// or number the code was sent to; the Twilio Verify path finds the row by it.
 // Any other pending change on u is persisted at the same time.
 func (ts *VerifyTestSuite) seedChallenge(u *models.User, tokenType models.OneTimeTokenType, relatesTo, hash string, sentAt time.Time, validity time.Duration) {
 	switch tokenType {
@@ -398,6 +449,42 @@ func (ts *VerifyTestSuite) observeOutcome(w *httptest.ResponseRecorder, userID u
 	return outcome
 }
 
+func (ts *VerifyTestSuite) configureTestOTP(phone, otp string) func() {
+	previous := ts.Config.Sms.TestOTP
+	ts.Config.Sms.TestOTP = map[string]string{phone: otp}
+	return func() { ts.Config.Sms.TestOTP = previous }
+}
+
+// configureTwilioVerify switches the SMS provider to Twilio Verify and arms a
+// single mocked VerificationCheck response.
+func (ts *VerifyTestSuite) configureTwilioVerify(response map[string]interface{}) func() {
+	previousProvider := ts.Config.Sms.Provider
+	previousTwilio := ts.Config.Sms.TwilioVerify
+	previousMock := sms_provider.MockProvider
+
+	ts.Config.Sms.Provider = "twilio_verify"
+	ts.Config.Sms.TwilioVerify = conf.TwilioVerifyProviderConfiguration{
+		AccountSid:        "AC-parity-test",
+		AuthToken:         "parity-test-token",
+		MessageServiceSid: twilioServiceSid,
+	}
+	// The mock provider would short-circuit GetSmsProvider and never reach
+	// the Twilio Verify type assertion.
+	sms_provider.MockProvider = nil
+
+	gock.New("https://verify.twilio.com/v2/Services/" + twilioServiceSid + "/VerificationCheck").
+		Post("").
+		Reply(http.StatusOK).
+		JSON(response)
+
+	return func() {
+		gock.OffAll()
+		sms_provider.MockProvider = previousMock
+		ts.Config.Sms.TwilioVerify = previousTwilio
+		ts.Config.Sms.Provider = previousProvider
+	}
+}
+
 func emailOTPBody(verifyType, email string) map[string]interface{} {
 	return map[string]interface{}{
 		"type":  verifyType,