feat(api): account lockout

We're implementing an "account lockout" feature in the login route to
manage repeated failed login attempts due to incorrect passwords for the
same user.

Account lockout is the system's ability to automatically restrict source
access based on the number of login attempts. The system permits sources
two login attempts before initiating a lockout. Upon a third attempt
with an incorrect password, the API will block further attempts.

Consumers trying to log in must inspect the `X-Account-Lockout` header,
which indicates the end of the lockout period in UTC seconds. When no
lockout is active, the header value will be 0. Importantly, a lockout
only affects login attempts from the same source. Logins from other
sources using the same user credentials will proceed without
encountering a lockout.

The lockout duration is calculated based on the number of attempts made,
increasing exponentially by a factor of 4 after the third attempt.
Attempts must last for half of the double lockout duration.

This means that a user who was locked out for 4 minutes must have the
attempts stored for 10 minutes (or 6 minutes after the timeout). Any
wrong attempt within this time will increase the lockout once again.
After this, the attempts will be reset, and new wrong attempts will
start the attempt counter from 0.

The following equations are used to calculate both lockout and attempt
duration, with 'x' representing the lockout duration and 'y' the attempt
duration:

```
F(x) = min(4^(a - 3), M)
F(y) = min((x) * 2.5, M)
```

Where:

```
x is the lockout duration in minutes.
y is the attempt duration in minutes.
a is the attempt number.
M is the maximum duration value.
```

Examples for M = 32768 (15 days) and a = n:

```
n    = 3   | 4  | 5  | 8    | 11
_________________________________
F(x) = 1   | 4  | 16 | 1024 | 32768
F(y) = 2.5 | 10 | 40 | 2560 | 32768
```

The M value is controlled with the "MAXIMUM_ACCOUNT_LOCKOUT" environment
variable. When it equals 0, this feature is disabled. The default value
is 60, representing 1 hour.

Author: heiytor

.env

@@ -127,3 +127,6 @@ SHELLHUB_NETWORK=shellhub_network
 # This variable controls the pool size of connections available for Redis cache.
 # If not specified or set to 0, it will use the default value defined by the Redis Client.
 SHELLHUB_REDIS_CACHE_POOL_SIZE=0
+
+# Specifies the maximum duration in minutes for which a source can be blocked from login attempts. Set it to 0 to disable.
+SHELLHUB_MAXIMUM_ACCOUNT_LOCKOUT=60

api/routes/auth.go

@@ -207,7 +207,13 @@ func (h *Handler) AuthUser(c gateway.Context) error {
 		return err
 	}
 
-	res, err := h.service.AuthUser(c.Ctx(), req)
+	res, timeout, err := h.service.AuthUser(c.Ctx(), req, c.RealIP())
+	c.Response().Header().Set("X-Account-Lockout", strconv.FormatInt(timeout, 10))
+
+	if timeout > 0 {
+		return c.NoContent(http.StatusTooManyRequests)
+	}
+
 	if err != nil {
 		switch {
 		case errors.Is(err, svc.ErrUserNotFound):

api/routes/auth_test.go

@@ -218,8 +218,8 @@ func TestAuthUser(t *testing.T) {
 					On("AuthUser", gomock.Anything, &requests.UserAuth{
 						Identifier: "john_doe",
 						Password:   "wrong_password",
-					}).
-					Return(nil, svc.ErrUserNotFound).
+					}, gomock.Anything).
+					Return(nil, int64(0), svc.ErrUserNotFound).
 					Once()
 			},
 			expected: Expected{
@@ -238,15 +238,35 @@ func TestAuthUser(t *testing.T) {
 					On("AuthUser", gomock.Anything, &requests.UserAuth{
 						Identifier: "john_doe",
 						Password:   "wrong_password",
-					}).
-					Return(nil, svc.ErrAuthUnathorized).
+					}, gomock.Anything).
+					Return(nil, int64(0), svc.ErrAuthUnathorized).
 					Once()
 			},
 			expected: Expected{
 				body:   nil,
 				status: http.StatusUnauthorized,
 			},
 		},
+		{
+			description: "fails when reaching the attempt limits",
+			req: &requests.UserAuth{
+				Identifier: "john_doe",
+				Password:   "wrong_password",
+			},
+			mocks: func() {
+				mock.
+					On("AuthUser", gomock.Anything, &requests.UserAuth{
+						Identifier: "john_doe",
+						Password:   "wrong_password",
+					}, gomock.Anything).
+					Return(nil, int64(1711176851), svc.ErrAuthUnathorized).
+					Once()
+			},
+			expected: Expected{
+				body:   nil,
+				status: http.StatusTooManyRequests,
+			},
+		},
 		{
 			description: "success when try to auth a user",
 			req: &requests.UserAuth{
@@ -258,7 +278,7 @@ func TestAuthUser(t *testing.T) {
 					On("AuthUser", gomock.Anything, &requests.UserAuth{
 						Identifier: "john_doe",
 						Password:   "secret",
-					}).
+					}, gomock.Anything).
 					Return(&models.UserAuthResponse{
 						ID:     "65fdd16b5f62f93184ec8a39",
 						Name:   "john doe",
@@ -271,7 +291,7 @@ func TestAuthUser(t *testing.T) {
 							Enable:   false,
 							Validate: false,
 						},
-					}, nil).
+					}, int64(0), nil).
 					Once()
 			},
 			expected: Expected{

api/routes/routes.go

@@ -13,6 +13,7 @@ func NewRouter(service services.Service) *echo.Echo {
 	e.Binder = handlers.NewBinder()
 	e.Validator = handlers.NewValidator()
 	e.HTTPErrorHandler = handlers.NewErrors(nil)
+	e.IPExtractor = echo.ExtractIPFromRealIPHeader()
 
 	e.Use(func(next echo.HandlerFunc) echo.HandlerFunc {
 		return func(c echo.Context) error {

api/services/auth.go

@@ -28,7 +28,11 @@ type AuthService interface {
 	AuthIsCacheToken(ctx context.Context, tenant, id string) (bool, error)
 	AuthUncacheToken(ctx context.Context, tenant, id string) error
 	AuthDevice(ctx context.Context, req requests.DeviceAuth, remoteAddr string) (*models.DeviceAuthResponse, error)
-	AuthUser(ctx context.Context, req *requests.UserAuth) (*models.UserAuthResponse, error)
+
+	// AuthUser is responsible for authenticating a user and returning its credentials. It can block a sourceIP
+	// from logging in a user for up to M minutes when exceeding the attempts limit.
+	AuthUser(ctx context.Context, req *requests.UserAuth, sourceIP string) (*models.UserAuthResponse, int64, error)
+
 	AuthGetToken(ctx context.Context, id string, mfa bool) (*models.UserAuthResponse, error)
 	AuthPublicKey(ctx context.Context, req requests.PublicKeyAuth) (*models.PublicKeyAuthResponse, error)
 	AuthSwapToken(ctx context.Context, ID, tenant string) (*models.UserAuthResponse, error)
@@ -149,7 +153,7 @@ func (s *service) AuthDevice(ctx context.Context, req requests.DeviceAuth, remot
 	}, nil
 }
 
-func (s *service) AuthUser(ctx context.Context, req *requests.UserAuth) (*models.UserAuthResponse, error) {
+func (s *service) AuthUser(ctx context.Context, req *requests.UserAuth, sourceIP string) (*models.UserAuthResponse, int64, error) {
 	var err error
 	var user *models.User
 
@@ -160,20 +164,50 @@ func (s *service) AuthUser(ctx context.Context, req *requests.UserAuth) (*models
 	}
 
 	if err != nil {
-		return nil, NewErrAuthUnathorized(nil)
+		return nil, 0, NewErrAuthUnathorized(nil)
 	}
 
 	if !user.Confirmed {
-		return nil, NewErrUserNotConfirmed(nil)
+		return nil, 0, NewErrUserNotConfirmed(nil)
+	}
+
+	// Checks whether the user is currently blocked from new login attempts
+	if lockout, attempt, _ := s.cache.HasAccountLockout(ctx, sourceIP, user.ID); lockout > 0 {
+		log.
+			WithFields(log.Fields{
+				"lockout":   lockout,
+				"attempt":   attempt,
+				"source_ip": sourceIP,
+				"user_id":   user.ID,
+			}).
+			Warn("attempt to login blocked")
+
+		return nil, lockout, NewErrAuthUnathorized(nil)
 	}
 
 	if !user.Password.Compare(req.Password) {
-		return nil, NewErrAuthUnathorized(nil)
+		lockout, _, err := s.cache.StoreLoginAttempt(ctx, sourceIP, user.ID)
+		if err != nil {
+			log.WithError(err).
+				WithField("source_ip", sourceIP).
+				WithField("user_id", user.ID).
+				Warn("unable to store login attempt")
+		}
+
+		return nil, lockout, NewErrAuthUnathorized(nil)
+	}
+
+	// Reset the attempt and timeout values when succeeds
+	if err := s.cache.ResetLoginAttempts(ctx, sourceIP, user.ID); err != nil {
+		log.WithError(err).
+			WithField("source_ip", sourceIP).
+			WithField("user_id", user.ID).
+			Warn("unable to reset authentication attempts")
 	}
 
 	hasMFA, err := s.AuthMFA(ctx, user.ID)
 	if err != nil {
-		return nil, err // TODO: handle this error
+		return nil, 0, err // TODO: handle this error
 	}
 
 	claims := &models.UserAuthClaims{
@@ -205,12 +239,12 @@ func (s *service) AuthUser(ctx context.Context, req *requests.UserAuth) (*models
 		WithPrivateKey(s.privKey).
 		Sign()
 	if err != nil {
-		return nil, NewErrTokenSigned(err)
+		return nil, 0, NewErrTokenSigned(err)
 	}
 
 	user.LastLogin = clock.Now()
 	if err := s.store.UserUpdateData(ctx, user.ID, *user); err != nil {
-		return nil, NewErrUserUpdate(user, err)
+		return nil, 0, NewErrUserUpdate(user, err)
 	}
 
 	if err := s.AuthCacheToken(ctx, claims.Tenant, user.ID, token.String()); err != nil {
@@ -238,7 +272,7 @@ func (s *service) AuthUser(ctx context.Context, req *requests.UserAuth) (*models
 			Enable:   hasMFA,
 			Validate: false,
 		},
-	}, nil
+	}, 0, nil
 }
 
 func (s *service) AuthGetToken(ctx context.Context, id string, mfa bool) (*models.UserAuthResponse, error) {