feat: upgrade existing sessions to v2 refresh tokens though config value (#2356)

If the refresh token algorithm version is set to 2, only new sessions
would be using these. By setting
`GOTRUE_SECURITY_REFRESH_TOKEN_UPGRADE_PERCENTAGE` to a value between 0
and 100 inclusive, on the next refresh token request a session using a
v1 refresh token will switch to using a v2 refresh token.

The percentage is to allow for gradual rollout, as the upgrade step can
result in some concurrent refreshes to terminate the session early.

Author: hf

internal/conf/configuration.go

@@ -725,6 +725,7 @@ func (c *DatabaseEncryptionConfiguration) Validate() error {
 
 type SecurityConfiguration struct {
 	Captcha                               CaptchaConfiguration `json:"captcha"`
+	RefreshTokenUpgradePercentage         int                  `json:"refresh_token_upgrade_percentage" split_words:"true"`
 	RefreshTokenAlgorithmVersion          int                  `json:"refresh_token_algorithm_version" split_words:"true"`
 	RefreshTokenRotationEnabled           bool                 `json:"refresh_token_rotation_enabled" split_words:"true" default:"true"`
 	RefreshTokenReuseInterval             int                  `json:"refresh_token_reuse_interval" split_words:"true"`
@@ -745,6 +746,14 @@ func (c *SecurityConfiguration) Validate() error {
 		return err
 	}
 
+	if c.RefreshTokenAlgorithmVersion < 0 || c.RefreshTokenAlgorithmVersion > 2 {
+		return fmt.Errorf("refresh token algorithm version must be 0, 1 or 2 but was %v", c.RefreshTokenAlgorithmVersion)
+	}
+
+	if c.RefreshTokenUpgradePercentage < 0 || c.RefreshTokenUpgradePercentage > 100 {
+		return fmt.Errorf("refresh token upgrade percentage must be between 0 and 100, but was %v", c.RefreshTokenUpgradePercentage)
+	}
+
 	return nil
 }
 

internal/models/refresh_token.go

@@ -168,6 +168,10 @@ func (s *Session) SetupRefreshTokenData(dbEncryption conf.DatabaseEncryptionConf
 	return nil
 }
 
+func (s *Session) UpdateRefreshTokenCounterAndHmacKey(tx *storage.Connection) error {
+	return tx.UpdateOnly(s, "refresh_token_hmac_key", "refresh_token_counter")
+}
+
 func createRefreshToken(tx *storage.Connection, user *User, oldToken *RefreshToken, params *GrantParams) (*RefreshToken, error) {
 	token := &RefreshToken{
 		UserID: user.ID,

internal/tokens/service.go

@@ -413,6 +413,47 @@ func (s *Service) RefreshTokenGrant(ctx context.Context, db *storage.Connection,
 					}
 
 					issuedToken = newToken.Token
+
+					shouldUpgrade := config.Security.RefreshTokenAlgorithmVersion == 2 && (config.Security.RefreshTokenUpgradePercentage >= 100 || mathRand.Intn(100) < config.Security.RefreshTokenUpgradePercentage) // #nosec
+
+					if shouldUpgrade {
+						// got v1 refresh token that should be upgraded to v2
+						// so discard the previously generated v1 token, revoke it and issue a v2 token instead
+
+						if session.RefreshTokenHmacKey == nil || session.RefreshTokenCounter == nil {
+							if serr := session.SetupRefreshTokenData(config.Security.DBEncryption); serr != nil {
+								return apierrors.NewInternalServerError("failed to set up refresh token data for session").WithInternalError(serr)
+							}
+						} else if session.RefreshTokenCounter != nil {
+							// session already set up, increment the counter by 1
+							counter := *session.RefreshTokenCounter + 1
+							session.RefreshTokenCounter = &counter
+						}
+
+						signingKey, _, kerr := session.GetRefreshTokenHmacKey(config.Security.DBEncryption)
+						if kerr != nil {
+							return apierrors.NewInternalServerError("failed to load session signing key from database").WithInternalError(kerr)
+						}
+
+						issuedToken = (&crypto.RefreshToken{
+							Version:   0,
+							SessionID: session.ID,
+							Counter:   *session.RefreshTokenCounter,
+						}).Encode(signingKey)
+
+						if terr := session.UpdateRefreshTokenCounterAndHmacKey(tx); terr != nil {
+							return apierrors.NewInternalServerError("failed to set up session with refresh token algorithm v2").WithInternalError(terr)
+						}
+
+						newToken.Revoked = true
+						if terr := tx.UpdateOnly(newToken, "revoked"); terr != nil {
+							return apierrors.NewInternalServerError("failed to mark v1 refresh token as revoked").WithInternalError(terr)
+						}
+
+						responseHeaders.Set("sb-auth-refresh-token-counter", strconv.FormatInt(*session.RefreshTokenCounter, 10))
+					}
+
+					responseHeaders.Set("sb-auth-refresh-token-reuse", "false")
 				}
 
 				responseHeaders.Set("sb-auth-refresh-token-prefix", issuedToken[0:5])

internal/tokens/service_test.go

@@ -1091,6 +1091,72 @@ func TestAMRClaimUnmarshal(t *testing.T) {
 	})
 }
 
+func (ts *RefreshTokenV2Suite) TestRefreshTokenVersionUpgrade() {
+	config := ts.config()
+
+	require.Equal(ts.T(), 2, config.Security.RefreshTokenAlgorithmVersion)
+
+	// start out with version 1, to issue a session with the old refresh tokens
+	// which then will be upgraded to the new one
+	config.Security.RefreshTokenAlgorithmVersion = 1
+	config.Security.RefreshTokenRotationEnabled = false
+	config.Security.RefreshTokenReuseInterval = 1
+	config.Security.RefreshTokenAllowReuse = false
+
+	clock := time.Now()
+
+	srv := NewService(config, &panicHookManager{})
+	srv.SetTimeFunc(func() time.Time {
+		return clock
+	})
+
+	req, err := http.NewRequest("POST", "https://example.com/", nil)
+	require.NoError(ts.T(), err)
+
+	req = req.WithContext(context.Background())
+	responseHeaders := make(http.Header)
+
+	at, err := srv.IssueRefreshToken(
+		req,
+		responseHeaders,
+		ts.Conn,
+		ts.User,
+		models.PasswordGrant,
+		models.GrantParams{},
+	)
+	require.NoError(ts.T(), err)
+	require.NotNil(ts.T(), at)
+
+	refreshTokenToUse := at.RefreshToken
+
+	// now set the algorithm to 2 and start upgrading
+	config.Security.RefreshTokenAlgorithmVersion = 2
+	config.Security.RefreshTokenUpgradePercentage = 100
+
+	clock = clock.Add(time.Duration(config.Security.RefreshTokenReuseInterval)*time.Second + time.Duration(100)*time.Millisecond)
+	responseHeaders = make(http.Header)
+
+	nrt, err := srv.RefreshTokenGrant(context.Background(), ts.Conn, req, responseHeaders, RefreshTokenGrantParams{
+		RefreshToken: refreshTokenToUse,
+	})
+	require.NoError(ts.T(), err)
+
+	pnrt, err := crypto.ParseRefreshToken(nrt.RefreshToken)
+	require.NoError(ts.T(), err)
+	require.NotNil(ts.T(), pnrt)
+	require.Equal(ts.T(), int64(0), pnrt.Counter)
+
+	refreshedSession, err := models.FindSessionByID(ts.Conn, pnrt.SessionID, false)
+	require.NoError(ts.T(), err)
+	require.NotNil(ts.T(), refreshedSession.RefreshTokenCounter)
+	require.NotNil(ts.T(), refreshedSession.RefreshTokenHmacKey)
+	require.Equal(ts.T(), int64(0), *refreshedSession.RefreshTokenCounter)
+
+	require.Equal(ts.T(), refreshedSession.UserID.String(), responseHeaders.Get("sb-auth-user-id"))
+	require.Equal(ts.T(), refreshedSession.ID.String(), responseHeaders.Get("sb-auth-session-id"))
+	require.Equal(ts.T(), "0", responseHeaders.Get("sb-auth-refresh-token-counter"))
+}
+
 // TestAsRedirectURL tests that AsRedirectURL includes the Supabase Auth identifier
 func TestAsRedirectURL(t *testing.T) {
 	response := &AccessTokenResponse{