feat(instance): глобальный бан пользователя и поиск в админ-панели

Сервер:
- миграция 00017: таблица instance_bans (причина, автор, дата);
- auth: ErrUserBanned, проверка бана в Login (код user.banned, 403) и в
  ResolveSession — забаненный не получает сессию ни по cookie, ни по Bearer,
  ни в Gateway, а прежняя сессия удаляется;
- store: BannedAt/BanReason в модели пользователя, BanInstanceUser,
  UnbanInstanceUser, IsInstanceBanned, поиск и фильтр в ListUsers,
  CountUsersFiltered; мягкое удаление аккаунта убирает и запись о бане;
- API: POST /instance/users/{id}/ban и /unban со step-up (AGENT.md 7.1),
  отзыв сессий и SESSION_INVALIDATED, аудит instance.user_ban с причиной и
  instance.user_unban; себя и инстанс-админа забанить нельзя;
- GET /instance/users: q (логин и отображаемое имя), banned=true, total.

Клиент:
- панель: поиск, фильтр «только забаненные», бейдж бана с причиной, кнопки
  «Забанить» (с причиной) и «Разбанить» через общий шаг подтверждения
  личности; i18n ru/en, включая текст ошибки user.banned;
- keepPreviousData в списке пользователей: без этого поле поиска
  размонтировалось на первом же символе и набор обрывался.

Тесты: 4 Go-теста (бан блокирует вход и сессии, защита админов, поиск,
уборка бана при удалении), web-тест панели, живая проверка на стенде 19/19.
This commit is contained in:
2026-09-22 18:59:53 +03:00
parent d2712c4c99
commit 787f822dc0
15 changed files with 850 additions and 55 deletions
+146 -15
View File
@@ -59,14 +59,41 @@ type instanceUserPayload struct {
IsInstanceAdmin bool `json:"is_instance_admin"`
Badges []string `json:"badges"`
CreatedAt string `json:"created_at"`
// Глобальный бан инстанса (AGENT.md 7.18).
Banned bool `json:"banned"`
BannedAt string `json:"banned_at,omitempty"`
BanReason string `json:"ban_reason,omitempty"`
}
type instanceUserListOutput struct {
Body struct {
Users []instanceUserPayload `json:"users"`
Total int `json:"total"`
}
}
// instanceUserPayloadFrom собирает ответ панели по модели пользователя.
func instanceUserPayloadFrom(user store.User) instanceUserPayload {
badges := user.Badges
if badges == nil {
badges = []string{}
}
payload := instanceUserPayload{
ID: formatSnowflake(user.ID),
Username: user.Username,
DisplayName: user.DisplayName,
IsInstanceAdmin: user.IsInstanceAdmin,
Badges: badges,
CreatedAt: user.CreatedAt.UTC().Format(time.RFC3339),
Banned: user.BannedAt != nil,
BanReason: user.BanReason,
}
if user.BannedAt != nil {
payload.BannedAt = user.BannedAt.UTC().Format(time.RFC3339)
}
return payload
}
type instanceSettingsPayload struct {
RegistrationEnabled bool `json:"registration_enabled"`
AllowGuildCreation bool `json:"allow_guild_creation"`
@@ -345,33 +372,30 @@ func (s *Server) registerInstanceRoutes(api huma.API) {
Tags: []string{"Instance"},
Security: []map[string][]string{{"sessionCookie": {}}, {"bearerAuth": {}}},
}, func(ctx context.Context, input *struct {
Limit int `query:"limit" default:"50" minimum:"1" maximum:"200"`
Offset int `query:"offset" default:"0" minimum:"0"`
Query string `query:"q" maxLength:"64"`
// Banned — показать только забаненных (AGENT.md 7.18).
Banned bool `query:"banned"`
Limit int `query:"limit" default:"50" minimum:"1" maximum:"200"`
Offset int `query:"offset" default:"0" minimum:"0"`
},
) (*instanceUserListOutput, error) {
if _, err := requireInstanceAdmin(ctx); err != nil {
return nil, err
}
users, err := s.store.ListUsers(ctx, input.Limit, input.Offset)
users, err := s.store.ListUsers(ctx, input.Query, input.Banned, input.Limit, input.Offset)
if err != nil {
return nil, humaError(err)
}
total, err := s.store.CountUsersFiltered(ctx, input.Query, input.Banned)
if err != nil {
return nil, humaError(err)
}
output := &instanceUserListOutput{}
output.Body.Users = make([]instanceUserPayload, 0, len(users))
for _, user := range users {
badges := user.Badges
if badges == nil {
badges = []string{}
}
output.Body.Users = append(output.Body.Users, instanceUserPayload{
ID: formatSnowflake(user.ID),
Username: user.Username,
DisplayName: user.DisplayName,
IsInstanceAdmin: user.IsInstanceAdmin,
Badges: badges,
CreatedAt: user.CreatedAt.UTC().Format(time.RFC3339),
})
output.Body.Users = append(output.Body.Users, instanceUserPayloadFrom(user))
}
output.Body.Total = total
return output, nil
})
@@ -501,6 +525,113 @@ func (s *Server) registerInstanceRoutes(api huma.API) {
return newOKOutput(), nil
})
huma.Register(api, huma.Operation{
OperationID: "adminBanUser",
Method: http.MethodPost,
Path: "/instance/users/{user_id}/ban",
Summary: "Забанить пользователя на инстансе",
Tags: []string{"Instance"},
Security: []map[string][]string{{"sessionCookie": {}}, {"bearerAuth": {}}},
}, func(ctx context.Context, input *struct {
UserID string `path:"user_id"`
Body struct {
Reason string `json:"reason,omitempty" maxLength:"400"`
// Бан — действие инстанс-админа: нужна свежая проверка (AGENT.md 7.1).
StepUpPassword string `json:"step_up_password,omitempty"`
StepUpTOTP string `json:"step_up_totp,omitempty"`
}
},
) (*userOutput, error) {
admin, session, err := requireUser(ctx)
if err != nil {
return nil, err
}
if !admin.IsInstanceAdmin {
return nil, humaErrorStatus(http.StatusForbidden, "instance.admin_required", "instance administrator rights required")
}
targetID, err := parseID("user_id", input.UserID)
if err != nil {
return nil, err
}
if targetID == admin.ID {
return nil, humaErrorStatus(http.StatusUnprocessableEntity, "validation.failed", "you cannot ban yourself")
}
target, err := s.store.GetUser(ctx, targetID)
if err != nil {
return nil, humaError(err)
}
// Администратора инстанса забанить нельзя (AGENT.md 7.19).
if target.IsInstanceAdmin {
return nil, humaErrorStatus(http.StatusForbidden, "instance.admin_protected", "instance administrator cannot be banned")
}
if err := s.auth.RequireStepUp(ctx, admin, session, input.Body.StepUpPassword, input.Body.StepUpTOTP); err != nil {
return nil, humaError(err)
}
reason := strings.TrimSpace(input.Body.Reason)
if err := s.store.BanInstanceUser(ctx, target.ID, admin.ID, reason); err != nil {
return nil, humaError(err)
}
if _, err := s.store.RevokeUserSessions(ctx, target.ID); err != nil {
return nil, humaError(err)
}
if s.gateway != nil {
s.gateway.SendToUser(target.ID, "SESSION_INVALIDATED", map[string]any{"reason": "user_banned"})
}
s.recordAudit(ctx, admin, 0, "instance.user_ban", "user", &target.ID, reason)
updated, err := s.store.GetUser(ctx, target.ID)
if err != nil {
return nil, humaError(err)
}
output := &userOutput{}
output.Body.User = s.profileFromUser(ctx, updated, false)
return output, nil
})
huma.Register(api, huma.Operation{
OperationID: "adminUnbanUser",
Method: http.MethodPost,
Path: "/instance/users/{user_id}/unban",
Summary: "Снять бан инстанса",
Tags: []string{"Instance"},
Security: []map[string][]string{{"sessionCookie": {}}, {"bearerAuth": {}}},
}, func(ctx context.Context, input *struct {
UserID string `path:"user_id"`
Body struct {
StepUpPassword string `json:"step_up_password,omitempty"`
StepUpTOTP string `json:"step_up_totp,omitempty"`
}
},
) (*userOutput, error) {
admin, session, err := requireUser(ctx)
if err != nil {
return nil, err
}
if !admin.IsInstanceAdmin {
return nil, humaErrorStatus(http.StatusForbidden, "instance.admin_required", "instance administrator rights required")
}
targetID, err := parseID("user_id", input.UserID)
if err != nil {
return nil, err
}
if _, err := s.store.GetUser(ctx, targetID); err != nil {
return nil, humaError(err)
}
if err := s.auth.RequireStepUp(ctx, admin, session, input.Body.StepUpPassword, input.Body.StepUpTOTP); err != nil {
return nil, humaError(err)
}
if _, err := s.store.UnbanInstanceUser(ctx, targetID); err != nil {
return nil, humaError(err)
}
s.recordAudit(ctx, admin, 0, "instance.user_unban", "user", &targetID, "")
updated, err := s.store.GetUser(ctx, targetID)
if err != nil {
return nil, humaError(err)
}
output := &userOutput{}
output.Body.User = s.profileFromUser(ctx, updated, false)
return output, nil
})
huma.Register(api, huma.Operation{
OperationID: "adminDeleteUser",
Method: http.MethodDelete,
+3
View File
@@ -35,6 +35,9 @@ func newAPIError(err error) apiError {
case errors.Is(err, auth.ErrInstanceAdminTOTP):
candidate.Status, candidate.Code = http.StatusForbidden, "auth.2fa_enrollment_required"
candidate.Message = "instance administrator must enable two-factor authentication: run `glchat totp-setup --email <admin>` on the server"
case errors.Is(err, auth.ErrUserBanned):
candidate.Status, candidate.Code = http.StatusForbidden, "user.banned"
candidate.Message = "account is banned on this instance"
case errors.Is(err, auth.ErrSessionExpired):
candidate.Status, candidate.Code, candidate.Message = http.StatusUnauthorized, "auth.session_expired", "session expired"
case errors.Is(err, auth.ErrStepUpRequired):
+230
View File
@@ -0,0 +1,230 @@
package server
import (
"net/http"
"testing"
"glchat/internal/crypto"
)
// instanceUsers вызывается администратором: список пользователей панели.
func instanceUsers(t *testing.T, srv *Server, cookie *http.Cookie, query string) struct {
Users []struct {
ID string `json:"id"`
Username string `json:"username"`
Banned bool `json:"banned"`
Reason string `json:"ban_reason"`
} `json:"users"`
Total int `json:"total"`
} {
t.Helper()
path := "/api/v1/instance/users"
if query != "" {
path += "?" + query
}
rec := doJSON(t, srv, http.MethodGet, path, "", cookie)
if rec.Code != http.StatusOK {
t.Fatalf("GET %s = %d, body = %s", path, rec.Code, rec.Body.String())
}
return decodeResponse[struct {
Users []struct {
ID string `json:"id"`
Username string `json:"username"`
Banned bool `json:"banned"`
Reason string `json:"ban_reason"`
} `json:"users"`
Total int `json:"total"`
}](t, rec)
}
func TestInstanceBanBlocksLoginAndSessions(t *testing.T) {
srv, _ := newTestServer(t)
adminCookie := registerAndLogin(t, srv, "ban_admin", "ban-admin@example.com")
promoteAdmin(t, srv, "ban-admin@example.com")
userCookie := registerAndLogin(t, srv, "ban_target", "ban-target@example.com")
target, err := srv.auth.UserByEmail(t.Context(), "ban-target@example.com")
if err != nil {
t.Fatalf("UserByEmail: %v", err)
}
targetPath := "/api/v1/instance/users/" + formatSnowflake(target.ID)
// Бан без step-up отклоняется: действие чувствительное (AGENT.md 7.1).
noStepUp := doJSON(t, srv, http.MethodPost, targetPath+"/ban", `{"reason":"спам"}`, adminCookie)
if noStepUp.Code != http.StatusForbidden {
t.Fatalf("ban without step-up = %d, want 403", noStepUp.Code)
}
if code := errorCodeOf(t, noStepUp); code != "auth.step_up_required" {
t.Fatalf("ban without step-up code = %q", code)
}
banned := doJSON(t, srv, http.MethodPost, targetPath+"/ban",
`{"reason":"спам в общем канале","step_up_password":"correct-horse-battery"}`, adminCookie)
if banned.Code != http.StatusOK {
t.Fatalf("ban = %d, body = %s", banned.Code, banned.Body.String())
}
// Список панели показывает бан и причину, фильтр «только забаненные» работает.
list := instanceUsers(t, srv, adminCookie, "banned=true")
if len(list.Users) != 1 || list.Users[0].Username != "ban_target" || !list.Users[0].Banned {
t.Fatalf("banned filter = %+v", list.Users)
}
if list.Users[0].Reason != "спам в общем канале" {
t.Fatalf("ban reason = %q", list.Users[0].Reason)
}
// Вход запрещён с отдельным кодом, а не «неверный пароль».
login := doJSON(t, srv, http.MethodPost, "/api/v1/auth/login",
`{"email":"ban-target@example.com","password":"correct-horse-battery"}`)
if login.Code != http.StatusForbidden {
t.Fatalf("login as banned = %d, want 403, body = %s", login.Code, login.Body.String())
}
if code := errorCodeOf(t, login); code != "user.banned" {
t.Fatalf("login as banned code = %q", code)
}
// Выданная ранее сессия перестаёт работать и отозвана в базе.
me := doJSON(t, srv, http.MethodGet, "/api/v1/auth/sessions", "", userCookie)
if me.Code != http.StatusUnauthorized && me.Code != http.StatusForbidden {
t.Fatalf("banned session still works: %d, body = %s", me.Code, me.Body.String())
}
if _, err := srv.store.GetSessionByTokenHash(t.Context(), crypto.HashToken(userCookie.Value)); err == nil {
t.Fatal("session of banned user must be revoked")
}
// Разбан возвращает доступ: сессии не восстанавливаются, но вход снова работает.
unban := doJSON(t, srv, http.MethodPost, targetPath+"/unban",
`{"step_up_password":"correct-horse-battery"}`, adminCookie)
if unban.Code != http.StatusOK {
t.Fatalf("unban = %d, body = %s", unban.Code, unban.Body.String())
}
loginAgain := doJSON(t, srv, http.MethodPost, "/api/v1/auth/login",
`{"email":"ban-target@example.com","password":"correct-horse-battery"}`)
if loginAgain.Code != http.StatusOK {
t.Fatalf("login after unban = %d, body = %s", loginAgain.Code, loginAgain.Body.String())
}
if list := instanceUsers(t, srv, adminCookie, ""); len(list.Users) != 2 || list.Total != 2 {
t.Fatalf("users after unban = %+v (total %d)", list.Users, list.Total)
}
// Действия попали в аудит инстанса.
audit := doJSON(t, srv, http.MethodGet, "/api/v1/instance/audit", "", adminCookie)
entries := decodeResponse[struct {
Entries []struct {
Action string `json:"action"`
Reason string `json:"reason"`
ActorInstanceAdmin bool `json:"actor_instance_admin"`
} `json:"entries"`
}](t, audit)
if !hasAction(entries.Entries, "instance.user_ban") || !hasAction(entries.Entries, "instance.user_unban") {
t.Fatalf("audit has no ban entries: %+v", entries.Entries)
}
for _, entry := range entries.Entries {
if entry.Action == "instance.user_ban" && entry.Reason != "спам в общем канале" {
t.Fatalf("audit ban reason = %q", entry.Reason)
}
}
}
func TestInstanceBanProtectsAdmins(t *testing.T) {
srv, _ := newTestServer(t)
adminCookie := registerAndLogin(t, srv, "protect_admin", "protect-admin@example.com")
promoteAdmin(t, srv, "protect-admin@example.com")
registerAndLogin(t, srv, "protect_admin2", "protect-admin2@example.com")
promoteAdmin(t, srv, "protect-admin2@example.com")
admin, err := srv.auth.UserByEmail(t.Context(), "protect-admin@example.com")
if err != nil {
t.Fatalf("UserByEmail: %v", err)
}
other, err := srv.auth.UserByEmail(t.Context(), "protect-admin2@example.com")
if err != nil {
t.Fatalf("UserByEmail: %v", err)
}
// Инстанс-админа забанить нельзя (AGENT.md 7.19) — даже другому админу.
rec := doJSON(t, srv, http.MethodPost,
"/api/v1/instance/users/"+formatSnowflake(other.ID)+"/ban",
`{"step_up_password":"correct-horse-battery"}`, adminCookie)
if rec.Code != http.StatusForbidden {
t.Fatalf("ban another admin = %d, want 403, body = %s", rec.Code, rec.Body.String())
}
if code := errorCodeOf(t, rec); code != "instance.admin_protected" {
t.Fatalf("ban another admin code = %q", code)
}
// Себя банить тоже нельзя.
self := doJSON(t, srv, http.MethodPost,
"/api/v1/instance/users/"+formatSnowflake(admin.ID)+"/ban",
`{"step_up_password":"correct-horse-battery"}`, adminCookie)
if self.Code != http.StatusUnprocessableEntity {
t.Fatalf("self ban = %d, want 422", self.Code)
}
// Обычный пользователь не может банить вообще.
userCookie := registerAndLogin(t, srv, "protect_user", "protect-user@example.com")
denied := doJSON(t, srv, http.MethodPost,
"/api/v1/instance/users/"+formatSnowflake(other.ID)+"/ban",
`{"step_up_password":"correct-horse-battery"}`, userCookie)
if denied.Code != http.StatusForbidden {
t.Fatalf("ban as user = %d, want 403", denied.Code)
}
if code := errorCodeOf(t, denied); code != "instance.admin_required" {
t.Fatalf("ban as user code = %q", code)
}
}
func TestInstanceUserSearch(t *testing.T) {
srv, _ := newTestServer(t)
adminCookie := registerAndLogin(t, srv, "search_admin", "search-admin@example.com")
promoteAdmin(t, srv, "search-admin@example.com")
registerAndLogin(t, srv, "search_alpha", "search-alpha@example.com")
registerAndLogin(t, srv, "search_beta", "search-beta@example.com")
found := instanceUsers(t, srv, adminCookie, "q=alpha")
if len(found.Users) != 1 || found.Users[0].Username != "search_alpha" {
t.Fatalf("search by username = %+v", found.Users)
}
if found.Total != 1 {
t.Fatalf("search total = %d, want 1", found.Total)
}
// Поиск идёт и по отображаемому имени (оно равно логину при регистрации).
byDisplay := instanceUsers(t, srv, adminCookie, "q=BETA")
if len(byDisplay.Users) != 1 || byDisplay.Users[0].Username != "search_beta" {
t.Fatalf("search is case-insensitive by display name = %+v", byDisplay.Users)
}
empty := instanceUsers(t, srv, adminCookie, "q=nobody-here")
if len(empty.Users) != 0 || empty.Total != 0 {
t.Fatalf("search with no matches = %+v (total %d)", empty.Users, empty.Total)
}
}
func TestInstanceDeleteClearsBan(t *testing.T) {
srv, _ := newTestServer(t)
adminCookie := registerAndLogin(t, srv, "clear_admin", "clear-admin@example.com")
promoteAdmin(t, srv, "clear-admin@example.com")
registerAndLogin(t, srv, "clear_target", "clear-target@example.com")
target, err := srv.auth.UserByEmail(t.Context(), "clear-target@example.com")
if err != nil {
t.Fatalf("UserByEmail: %v", err)
}
targetPath := "/api/v1/instance/users/" + formatSnowflake(target.ID)
if rec := doJSON(t, srv, http.MethodPost, targetPath+"/ban",
`{"reason":"мусор","step_up_password":"correct-horse-battery"}`, adminCookie); rec.Code != http.StatusOK {
t.Fatalf("ban = %d, body = %s", rec.Code, rec.Body.String())
}
if banned, err := srv.store.IsInstanceBanned(t.Context(), target.ID); err != nil || !banned {
t.Fatalf("IsInstanceBanned = %v, %v; want true", banned, err)
}
// Мягкое удаление убирает и запись о бане: аккаунта больше нет.
if rec := doJSON(t, srv, http.MethodDelete, targetPath, "", adminCookie); rec.Code != http.StatusOK {
t.Fatalf("delete = %d, body = %s", rec.Code, rec.Body.String())
}
if banned, err := srv.store.IsInstanceBanned(t.Context(), target.ID); err != nil || banned {
t.Fatalf("IsInstanceBanned after delete = %v, %v; want false", banned, err)
}
}