feat: add configurable cooldown to claim usernames (go-gitea#6422)

Add a new option that allows instances to set a cooldown period to claim
old usernames. In the context of public instances this can be used to
prevent old usernames to be claimed after they are free and allow
graceful migration (by making use of the redirect feature) to a new
username. The granularity of this cooldown is a day. By default this
feature is disabled and thus no cooldown period.

The `CreatedUnix` column is added the `user_redirect` table, for
existing redirects the timestamp is simply zero as we simply do not know
when they were created and are likely already over the cooldown period
if the instance configures one.

Users can always reclaim their 'old' user name again within the cooldown
period. Users can also always reclaim 'old' names of organization they
currently own within the cooldown period.

Creating and renaming users as an admin user are not affected by the
cooldown period for moderation and user support reasons.

To avoid abuse of the cooldown feature, such that a user holds a lot of
usernames, a new option is added `MAX_USER_REDIRECTS` which sets a limit
to the amount of user redirects a user may have, by default this is
disabled. If a cooldown period is set then the default is 5. This
feature operates independently of the cooldown period feature.

Added integration and unit testing.

Reviewed-on: https://codeberg.org/forgejo/forgejo/pulls/6422
Reviewed-by: Earl Warren <[email protected]>
Reviewed-by: 0ko <[email protected]>
Reviewed-by: Otto <[email protected]>
Co-authored-by: Gusted <[email protected]>
Co-committed-by: Gusted <[email protected]>

Author: Gusted

models/fixtures/user_redirect.yml

@@ -2,3 +2,4 @@
   id: 1
   lower_name: olduser1
   redirect_user_id: 1
+  created_unix: 1730000000

models/forgejo_migrations/migrate.go

@@ -90,6 +90,8 @@ var migrations = []*Migration{
 	NewMigration("Migrate `secret` column to store keying material", MigrateTwoFactorToKeying),
 	// v26 -> v27
 	NewMigration("Add `hash_blake2b` column to `package_blob` table", AddHashBlake2bToPackageBlob),
+	// v27 -> v28
+	NewMigration("Add `created_unix` column to `user_redirect` table", AddCreatedUnixToRedirect),
 }
 
 // GetCurrentDBVersion returns the current Forgejo database version.

models/forgejo_migrations/v27.go

@@ -0,0 +1,18 @@
+// Copyright 2024 The Forgejo Authors. All rights reserved.
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+package forgejo_migrations //nolint:revive
+
+import (
+	"code.gitea.io/gitea/modules/timeutil"
+
+	"xorm.io/xorm"
+)
+
+func AddCreatedUnixToRedirect(x *xorm.Engine) error {
+	type UserRedirect struct {
+		ID          int64              `xorm:"pk autoincr"`
+		CreatedUnix timeutil.TimeStamp `xorm:"created NOT NULL DEFAULT 0"`
+	}
+	return x.Sync(new(UserRedirect))
+}

models/user/redirect.go

@@ -6,10 +6,17 @@ package user
 import (
 	"context"
 	"fmt"
+	"slices"
+	"strconv"
 	"strings"
+	"time"
 
 	"code.gitea.io/gitea/models/db"
+	"code.gitea.io/gitea/modules/setting"
+	"code.gitea.io/gitea/modules/timeutil"
 	"code.gitea.io/gitea/modules/util"
+
+	"xorm.io/builder"
 )
 
 // ErrUserRedirectNotExist represents a "UserRedirectNotExist" kind of error.
@@ -31,11 +38,25 @@ func (err ErrUserRedirectNotExist) Unwrap() error {
 	return util.ErrNotExist
 }
 
+type ErrCooldownPeriod struct {
+	ExpireTime time.Time
+}
+
+func IsErrCooldownPeriod(err error) bool {
+	_, ok := err.(ErrCooldownPeriod)
+	return ok
+}
+
+func (err ErrCooldownPeriod) Error() string {
+	return fmt.Sprintf("cooldown period for claiming this username has not yet expired: the cooldown period ends at %s", err.ExpireTime)
+}
+
 // Redirect represents that a user name should be redirected to another
 type Redirect struct {
-	ID             int64  `xorm:"pk autoincr"`
-	LowerName      string `xorm:"UNIQUE(s) INDEX NOT NULL"`
-	RedirectUserID int64  // userID to redirect to
+	ID             int64              `xorm:"pk autoincr"`
+	LowerName      string             `xorm:"UNIQUE(s) INDEX NOT NULL"`
+	RedirectUserID int64              // userID to redirect to
+	CreatedUnix    timeutil.TimeStamp `xorm:"created NOT NULL DEFAULT 0"`
 }
 
 // TableName provides the real table name
@@ -47,14 +68,24 @@ func init() {
 	db.RegisterModel(new(Redirect))
 }
 
-// LookupUserRedirect look up userID if a user has a redirect name
-func LookupUserRedirect(ctx context.Context, userName string) (int64, error) {
+// GetUserRedirect returns the redirect for a given username, this is a
+// case-insenstive operation.
+func GetUserRedirect(ctx context.Context, userName string) (*Redirect, error) {
 	userName = strings.ToLower(userName)
 	redirect := &Redirect{LowerName: userName}
 	if has, err := db.GetEngine(ctx).Get(redirect); err != nil {
-		return 0, err
+		return nil, err
 	} else if !has {
-		return 0, ErrUserRedirectNotExist{Name: userName}
+		return nil, ErrUserRedirectNotExist{Name: userName}
+	}
+	return redirect, nil
+}
+
+// LookupUserRedirect look up userID if a user has a redirect name
+func LookupUserRedirect(ctx context.Context, userName string) (int64, error) {
+	redirect, err := GetUserRedirect(ctx, userName)
+	if err != nil {
+		return 0, err
 	}
 	return redirect.RedirectUserID, nil
 }
@@ -78,10 +109,66 @@ func NewUserRedirect(ctx context.Context, ID int64, oldUserName, newUserName str
 	})
 }
 
+// LimitUserRedirects deletes the oldest entries in user_redirect of the user,
+// such that the amount of user_redirects is at most `n` amount of entries.
+func LimitUserRedirects(ctx context.Context, userID, n int64) error {
+	// NOTE: It's not possible to combine these two queries into one due to a limitation of MySQL.
+	keepIDs := make([]int64, n)
+	if err := db.GetEngine(ctx).SQL("SELECT id FROM user_redirect WHERE redirect_user_id = ? ORDER BY created_unix DESC LIMIT "+strconv.FormatInt(n, 10), userID).Find(&keepIDs); err != nil {
+		return err
+	}
+
+	_, err := db.GetEngine(ctx).Exec(builder.Delete(builder.And(builder.Eq{"redirect_user_id": userID}, builder.NotIn("id", keepIDs))).From("user_redirect"))
+	return err
+}
+
 // DeleteUserRedirect delete any redirect from the specified user name to
 // anything else
 func DeleteUserRedirect(ctx context.Context, userName string) error {
 	userName = strings.ToLower(userName)
 	_, err := db.GetEngine(ctx).Delete(&Redirect{LowerName: userName})
 	return err
 }
+
+// CanClaimUsername returns if its possible to claim the given username,
+// it checks if the cooldown period for claiming an existing username is over.
+// If there's a cooldown period, the second argument returns the time when
+// that cooldown period is over.
+// In the scenario of renaming, the doerID can be specified to allow the original
+// user of the username to reclaim it within the cooldown period.
+func CanClaimUsername(ctx context.Context, username string, doerID int64) (bool, time.Time, error) {
+	// Only check for a cooldown period if UsernameCooldownPeriod is a positive number.
+	if setting.Service.UsernameCooldownPeriod <= 0 {
+		return true, time.Time{}, nil
+	}
+
+	userRedirect, err := GetUserRedirect(ctx, username)
+	if err != nil {
+		if IsErrUserRedirectNotExist(err) {
+			return true, time.Time{}, nil
+		}
+		return false, time.Time{}, err
+	}
+
+	// Allow reclaiming of user's own username.
+	if userRedirect.RedirectUserID == doerID {
+		return true, time.Time{}, nil
+	}
+
+	// We do not know if the redirect user id was for an organization, so
+	// unconditionally execute the following query to retrieve all users that
+	// are part of the "Owner" team. If the redirect user ID is not an organization
+	// the returned list would be empty.
+	ownerTeamUIDs := []int64{}
+	if err := db.GetEngine(ctx).SQL("SELECT uid FROM team_user INNER JOIN team ON team_user.`team_id` = team.`id` WHERE team.`org_id` = ? AND team.`name` = 'Owners'", userRedirect.RedirectUserID).Find(&ownerTeamUIDs); err != nil {
+		return false, time.Time{}, err
+	}
+
+	if slices.Contains(ownerTeamUIDs, doerID) {
+		return true, time.Time{}, nil
+	}
+
+	// Multiply the value of UsernameCooldownPeriod by the amount of seconds in a day.
+	expireTime := userRedirect.CreatedUnix.Add(86400 * setting.Service.UsernameCooldownPeriod).AsLocalTime()
+	return time.Until(expireTime) <= 0, expireTime, nil
+}

models/user/user.go

@@ -669,6 +669,18 @@ func createUser(ctx context.Context, u *User, createdByAdmin bool, overwriteDefa
 		return err
 	}
 
+	// Check if the new username can be claimed.
+	// Skip this check if done by an admin.
+	if !createdByAdmin {
+		if ok, expireTime, err := CanClaimUsername(ctx, u.Name, -1); err != nil {
+			return err
+		} else if !ok {
+			return ErrCooldownPeriod{
+				ExpireTime: expireTime,
+			}
+		}
+	}
+
 	// set system defaults
 	u.KeepEmailPrivate = setting.Service.DefaultKeepEmailPrivate
 	u.Visibility = setting.Service.DefaultUserVisibilityMode

models/user/user_test.go

@@ -393,6 +393,31 @@ func TestCreateUserWithoutCustomTimestamps(t *testing.T) {
 	assert.LessOrEqual(t, fetched.UpdatedUnix, timestampEnd)
 }
 
+func TestCreateUserClaimingUsername(t *testing.T) {
+	require.NoError(t, unittest.PrepareTestDatabase())
+	defer test.MockVariableValue(&setting.Service.UsernameCooldownPeriod, 1)()
+
+	_, err := db.GetEngine(db.DefaultContext).NoAutoTime().Insert(&user_model.Redirect{RedirectUserID: 1, LowerName: "redirecting", CreatedUnix: timeutil.TimeStampNow()})
+	require.NoError(t, err)
+
+	user := unittest.AssertExistsAndLoadBean(t, &user_model.User{ID: 2})
+
+	user.Name = "redirecting"
+	user.LowerName = strings.ToLower(user.Name)
+	user.ID = 0
+	user.Email = "[email protected]"
+
+	t.Run("Normal creation", func(t *testing.T) {
+		err = user_model.CreateUser(db.DefaultContext, user)
+		assert.True(t, user_model.IsErrCooldownPeriod(err))
+	})
+
+	t.Run("Creation as admin", func(t *testing.T) {
+		err = user_model.AdminCreateUser(db.DefaultContext, user)
+		require.NoError(t, err)
+	})
+}
+
 func TestGetUserIDsByNames(t *testing.T) {
 	require.NoError(t, unittest.PrepareTestDatabase())
 

modules/setting/server_test.go

@@ -9,6 +9,7 @@ import (
 	"code.gitea.io/gitea/modules/test"
 
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func TestDisplayNameDefault(t *testing.T) {
@@ -34,3 +35,41 @@ func TestDisplayNameCustomFormat(t *testing.T) {
 	displayName := generateDisplayName()
 	assert.Equal(t, "Forgejo - Beyond coding. We Forge.", displayName)
 }
+
+func TestMaxUserRedirectsDefault(t *testing.T) {
+	iniStr := ``
+	cfg, err := NewConfigProviderFromData(iniStr)
+	require.NoError(t, err)
+	loadServiceFrom(cfg)
+
+	assert.EqualValues(t, 0, Service.UsernameCooldownPeriod)
+	assert.EqualValues(t, 0, Service.MaxUserRedirects)
+
+	iniStr = `[service]
+MAX_USER_REDIRECTS = 8`
+	cfg, err = NewConfigProviderFromData(iniStr)
+	require.NoError(t, err)
+	loadServiceFrom(cfg)
+
+	assert.EqualValues(t, 0, Service.UsernameCooldownPeriod)
+	assert.EqualValues(t, 8, Service.MaxUserRedirects)
+
+	iniStr = `[service]
+USERNAME_COOLDOWN_PERIOD = 3`
+	cfg, err = NewConfigProviderFromData(iniStr)
+	require.NoError(t, err)
+	loadServiceFrom(cfg)
+
+	assert.EqualValues(t, 3, Service.UsernameCooldownPeriod)
+	assert.EqualValues(t, 5, Service.MaxUserRedirects)
+
+	iniStr = `[service]
+USERNAME_COOLDOWN_PERIOD = 3
+MAX_USER_REDIRECTS = 8`
+	cfg, err = NewConfigProviderFromData(iniStr)
+	require.NoError(t, err)
+	loadServiceFrom(cfg)
+
+	assert.EqualValues(t, 3, Service.UsernameCooldownPeriod)
+	assert.EqualValues(t, 8, Service.MaxUserRedirects)
+}

modules/setting/service.go

@@ -85,6 +85,8 @@ var Service = struct {
 	DefaultOrgMemberVisible                 bool
 	UserDeleteWithCommentsMaxTime           time.Duration
 	ValidSiteURLSchemes                     []string
+	UsernameCooldownPeriod                  int64
+	MaxUserRedirects                        int64
 
 	// OpenID settings
 	EnableOpenIDSignIn bool
@@ -257,6 +259,14 @@ func loadServiceFrom(rootCfg ConfigProvider) {
 		}
 	}
 	Service.ValidSiteURLSchemes = schemes
+	Service.UsernameCooldownPeriod = sec.Key("USERNAME_COOLDOWN_PERIOD").MustInt64(0)
+
+	// Only set a default if USERNAME_COOLDOWN_PERIOD's feature is active.
+	maxUserRedirectsDefault := int64(0)
+	if Service.UsernameCooldownPeriod > 0 {
+		maxUserRedirectsDefault = 5
+	}
+	Service.MaxUserRedirects = sec.Key("MAX_USER_REDIRECTS").MustInt64(maxUserRedirectsDefault)
 
 	mustMapSetting(rootCfg, "service.explore", &Service.Explore)
 

options/locale/locale_en-US.ini

@@ -630,6 +630,7 @@ lang_select_error = Select a language from the list.
 
 username_been_taken = The username is already taken.
 username_change_not_local_user = Non-local users are not allowed to change their username.
+username_claiming_cooldown = The username cannot be claimed, because its cooldown period is not yet over. It can be claimed on %[1]s.
 repo_name_been_taken = The repository name is already used.
 repository_force_private = Force Private is enabled: private repositories cannot be made public.
 repository_files_already_exist = Files already exist for this repository. Contact the system administrator.
@@ -765,6 +766,8 @@ update_profile_success = Your profile has been updated.
 change_username = Your username has been changed.
 change_username_prompt = Note: Changing your username also changes your account URL.
 change_username_redirect_prompt = The old username will redirect until someone claims it.
+change_username_redirect_prompt.with_cooldown.one = The old username will be available to everyone after a cooldown period of %[1]d day, you can still reclaim the old username during the cooldown period.
+change_username_redirect_prompt.with_cooldown.few = The old username will be available to everyone after a cooldown period of %[1]d days, you can still reclaim the old username during the cooldown period.
 continue = Continue
 cancel = Cancel
 language = Language
@@ -2883,6 +2886,8 @@ settings.update_settings = Update settings
 settings.update_setting_success = Organization settings have been updated.
 settings.change_orgname_prompt = Note: Changing the organization name will also change your organization's URL and free the old name.
 settings.change_orgname_redirect_prompt = The old name will redirect until it is claimed.
+settings.change_orgname_redirect_prompt.with_cooldown.one = The old username will be available to everyone after a cooldown period of %[1]d day, you can still reclaim the old username during the cooldown period.
+settings.change_orgname_redirect_prompt.with_cooldown.few = The old username will be available to everyone after a cooldown period of %[1]d days, you can still reclaim the old username during the cooldown period.
 settings.update_avatar_success = The organization's avatar has been updated.
 settings.delete = Delete organization
 settings.delete_account = Delete this organization

routers/api/v1/admin/user.go

@@ -523,7 +523,7 @@ func RenameUser(ctx *context.APIContext) {
 	newName := web.GetForm(ctx).(*api.RenameUserOption).NewName
 
 	// Check if user name has been changed
-	if err := user_service.RenameUser(ctx, ctx.ContextUser, newName); err != nil {
+	if err := user_service.AdminRenameUser(ctx, ctx.ContextUser, newName); err != nil {
 		switch {
 		case user_model.IsErrUserAlreadyExist(err):
 			ctx.Error(http.StatusUnprocessableEntity, "", ctx.Tr("form.username_been_taken"))