feat(mfa): add recovery code factor model support

Author: fadymak

internal/models/amr.go

@@ -22,7 +22,7 @@ func (AMRClaim) TableName() string {
 }
 
 func (cl *AMRClaim) IsAAL2Claim() bool {
-	return *cl.AuthenticationMethod == TOTPSignIn.String() || *cl.AuthenticationMethod == MFAPhone.String() || *cl.AuthenticationMethod == MFAWebAuthn.String()
+	return *cl.AuthenticationMethod == TOTPSignIn.String() || *cl.AuthenticationMethod == MFAPhone.String() || *cl.AuthenticationMethod == MFAWebAuthn.String() || *cl.AuthenticationMethod == MFARecoveryCode.String()
 }
 
 func AddClaimToSession(tx *storage.Connection, sessionId uuid.UUID, authenticationMethod AuthenticationMethod) error {

internal/models/amr_test.go

@@ -0,0 +1,23 @@
+package models
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// TestAMRClaimIsAAL2 pins which authentication methods upgrade a session to AAL2.
+func TestAMRClaimIsAAL2(t *testing.T) {
+	for method, want := range map[AuthenticationMethod]bool{
+		TOTPSignIn:      true,
+		MFAPhone:        true,
+		MFAWebAuthn:     true,
+		MFARecoveryCode: true,
+		PasswordGrant:   false,
+		OTP:             false,
+	} {
+		methodString := method.String()
+		claim := AMRClaim{AuthenticationMethod: &methodString}
+		require.Equal(t, want, claim.IsAAL2Claim(), "method %q", methodString)
+	}
+}

internal/models/factor.go

@@ -36,6 +36,9 @@ func (factorState FactorState) String() string {
 const TOTP = "totp"
 const Phone = "phone"
 const WebAuthn = "webauthn"
+const RecoveryCode = "recovery_code"
+
+const DefaultRecoveryCodeFriendlyName = "Recovery codes"
 
 type AuthenticationMethod int
 
@@ -57,6 +60,7 @@ const (
 	Web3
 	OAuthProviderAuthorizationCode
 	PasskeyLogin
+	MFARecoveryCode
 )
 
 func (authMethod AuthenticationMethod) IsRecovery() bool {
@@ -98,6 +102,8 @@ func (authMethod AuthenticationMethod) String() string {
 		return "mfa/phone"
 	case MFAWebAuthn:
 		return "mfa/webauthn"
+	case MFARecoveryCode:
+		return "mfa/recovery_code"
 	case Web3:
 		return "web3"
 	case OAuthProviderAuthorizationCode:
@@ -139,6 +145,8 @@ func ParseAuthenticationMethod(authMethod string) (AuthenticationMethod, error)
 		return MFAPhone, nil
 	case "mfa/webauthn":
 		return MFAWebAuthn, nil
+	case "mfa/recovery_code":
+		return MFARecoveryCode, nil
 	case "web3":
 		return Web3, nil
 	case "oauth_provider/authorization_code":
@@ -268,6 +276,16 @@ func NewWebAuthnFactor(user *User, friendlyName string) *Factor {
 	return factor
 }
 
+// NewRecoveryCodeFactor creates a recovery-code factor directly in the verified
+// state: there is no challenge/verify enrollment round-trip, the codes are handed
+// to an already-AAL2 user.
+func NewRecoveryCodeFactor(user *User, friendlyName string) *Factor {
+	if strings.TrimSpace(friendlyName) == "" {
+		friendlyName = DefaultRecoveryCodeFriendlyName
+	}
+	return NewFactor(user, friendlyName, RecoveryCode, FactorStateVerified)
+}
+
 func (f *Factor) SetSecret(secret string, encrypt bool, encryptionKeyID, encryptionKey string) error {
 	f.Secret = secret
 	if encrypt {
@@ -339,6 +357,20 @@ func FindFactorByFactorID(conn *storage.Connection, factorID uuid.UUID) (*Factor
 	return &factor, nil
 }
 
+// FindRecoveryCodeFactorByUser returns the user's recovery-code factor (only one should exist per user).
+func FindRecoveryCodeFactorByUser(conn *storage.Connection, userID uuid.UUID) (*Factor, error) {
+	var factor Factor
+
+	err := conn.Q().Where("user_id = ? AND factor_type = ?", userID, RecoveryCode).First(&factor)
+	if err != nil && errors.Cause(err) == sql.ErrNoRows {
+		return nil, FactorNotFoundError{}
+	} else if err != nil {
+		return nil, err
+	}
+
+	return &factor, nil
+}
+
 func DeleteUnverifiedFactors(tx *storage.Connection, user *User, factorType string) error {
 	if err := tx.RawQuery("DELETE FROM "+(&pop.Model{Value: Factor{}}).TableName()+" WHERE user_id = ? and status = ? and factor_type = ?", user.ID, FactorStateUnverified.String(), factorType).Exec(); err != nil {
 		return err
@@ -407,6 +439,8 @@ func amrMethodForFactorType(factorType string) (string, error) {
 		return MFAPhone.String(), nil
 	case WebAuthn:
 		return MFAWebAuthn.String(), nil
+	case RecoveryCode:
+		return MFARecoveryCode.String(), nil
 	default:
 		return "", fmt.Errorf("no AMR authentication method mapped for factor type %q", factorType)
 	}
@@ -441,6 +475,10 @@ func (f *Factor) IsPhoneFactor() bool {
 	return f.FactorType == Phone
 }
 
+func (f *Factor) IsRecoveryCodeFactor() bool {
+	return f.FactorType == RecoveryCode
+}
+
 func (f *Factor) FindChallengeByID(conn *storage.Connection, challengeID uuid.UUID) (*Challenge, error) {
 	var challenge Challenge
 	err := conn.Q().Where("id = ? and factor_id = ?", challengeID, f.ID).First(&challenge)

internal/models/factor_test.go

@@ -35,9 +35,10 @@ func TestFactor(t *testing.T) {
 // TestAMRMethodForFactorType pins the factor-type -> AMR method mapping.
 func TestAMRMethodForFactorType(t *testing.T) {
 	for factorType, want := range map[string]AuthenticationMethod{
-		TOTP:     TOTPSignIn,
-		Phone:    MFAPhone,
-		WebAuthn: MFAWebAuthn,
+		TOTP:         TOTPSignIn,
+		Phone:        MFAPhone,
+		WebAuthn:     MFAWebAuthn,
+		RecoveryCode: MFARecoveryCode,
 	} {
 		got, err := amrMethodForFactorType(factorType)
 		require.NoError(t, err, "factor type %q must map", factorType)
@@ -50,7 +51,7 @@ func TestAMRMethodForFactorType(t *testing.T) {
 
 // TestAuthenticationMethodRoundTrip guards the String() <-> ParseAuthenticationMethod symmetry.
 func TestAuthenticationMethodRoundTrip(t *testing.T) {
-	for _, m := range []AuthenticationMethod{TOTPSignIn, MFAPhone, MFAWebAuthn} {
+	for _, m := range []AuthenticationMethod{TOTPSignIn, MFAPhone, MFAWebAuthn, MFARecoveryCode} {
 		parsed, err := ParseAuthenticationMethod(m.String())
 		require.NoError(t, err, "method %q must round-trip", m.String())
 		require.Equal(t, m, parsed)
@@ -78,6 +79,41 @@ func (ts *FactorTestSuite) TestFindFactorByFactorID() {
 	require.EqualError(ts.T(), err, FactorNotFoundError{}.Error())
 }
 
+func (ts *FactorTestSuite) TestNewRecoveryCodeFactor() {
+	user, err := NewUser("", "recoveryfactor@example.com", "secret", "test", nil)
+	require.NoError(ts.T(), err)
+
+	factor := NewRecoveryCodeFactor(user, "my recovery codes")
+	require.Equal(ts.T(), RecoveryCode, factor.FactorType)
+	require.Equal(ts.T(), FactorStateVerified.String(), factor.Status)
+	require.True(ts.T(), factor.IsVerified())
+	require.Equal(ts.T(), "my recovery codes", factor.FriendlyName)
+	require.True(ts.T(), factor.IsRecoveryCodeFactor())
+	require.False(ts.T(), ts.TestFactor.IsRecoveryCodeFactor())
+
+	// blank names fall back to the default
+	require.Equal(ts.T(), DefaultRecoveryCodeFriendlyName, NewRecoveryCodeFactor(user, "").FriendlyName)
+	require.Equal(ts.T(), DefaultRecoveryCodeFriendlyName, NewRecoveryCodeFactor(user, "   ").FriendlyName)
+}
+
+func (ts *FactorTestSuite) TestFindRecoveryCodeFactorByUser() {
+	// the fixture user has only a TOTP factor
+	_, err := FindRecoveryCodeFactorByUser(ts.db, ts.TestFactor.UserID)
+	require.EqualError(ts.T(), err, FactorNotFoundError{}.Error())
+
+	user, err := NewUser("", "findrecovery@example.com", "secret", "test", nil)
+	require.NoError(ts.T(), err)
+	require.NoError(ts.T(), ts.db.Create(user))
+
+	factor := NewRecoveryCodeFactor(user, "")
+	require.NoError(ts.T(), ts.db.Create(factor))
+
+	found, err := FindRecoveryCodeFactorByUser(ts.db, user.ID)
+	require.NoError(ts.T(), err)
+	require.Equal(ts.T(), factor.ID, found.ID)
+	require.True(ts.T(), found.IsRecoveryCodeFactor())
+}
+
 func (ts *FactorTestSuite) TestUpdateStatus() {
 	newFactorStatus := FactorStateVerified
 	require.NoError(ts.T(), ts.TestFactor.UpdateStatus(ts.db, newFactorStatus))
@@ -122,6 +158,11 @@ func (ts *FactorTestSuite) TestDowngradeSessionsToAAL1RemovesAMRClaim() {
 			newFactor:  func(u *User) *Factor { return NewTOTPFactor(u, "totpfactor") },
 			authMethod: TOTPSignIn,
 		},
+		{
+			desc:       "recovery_code",
+			newFactor:  func(u *User) *Factor { return NewRecoveryCodeFactor(u, "") },
+			authMethod: MFARecoveryCode,
+		},
 	}
 
 	for i, c := range cases {