IPWhitelist

IPWL — белый список по IP для Minecraft (Fabric)

Minecraft: 1.21.1-26.3  |  Загрузчик: Fabric  |  Java: 25  |  Лицензия: GPL

Серверный мод, добавляющий второй уровень защиты поверх аутентификации Mojang. Каждый игрок привязан к одному или нескольким одобренным IP-адресам: даже если у кого-то есть действующий аккаунт, он не сможет зайти, если подключается не с заранее одобренного IP. Соединения блокируются ещё до завершения аутентификации, так что отклонённые игроки почти не расходуют ресурсы сервера.

Установка

1. Закинь .jar в папку mods/ на сервере.
2. Запусти сервер. Мод сам создаст config/ipwl.json.
3. Добавь себя в админы IPWL (см. ниже) и начинай управлять игроками.

OP не нужен. У IPWL свой список админов — статус OP полностью отдельный.

Настройка админов

У IPWL своя система прав. Только игроки из списка админов IPWL могут выполнять команды /ipwl, /lockdown, /seen и /connections. Консоль сервера всегда имеет полный доступ.

/ipwl admin add <player>     — Выдать доступ к IPWL (сразу сохраняется в конфиг)
/ipwl admin remove <player>  — Мгновенно отозвать доступ, обновляет дерево команд игрока
/ipwl admin list             — Показать всех текущих админов IPWL

При снятии админа игрок сразу теряет автодополнение и возможность выполнять команды — перезаходить не нужно.

Команды белого списка

/ipwl add <player>           — Разрешить игроку заходить с любого IP
/ipwl add <player> <ip>      — Разрешить игроку заходить с конкретного IP
/ipwl addip <player> <ip>    — Добавить второй разрешённый IP существующему игроку
/ipwl removeip <player> <ip> — Убрать один конкретный IP у игрока
/ipwl remove <player>        — Полностью удалить игрока и кикнуть его, если он онлайн
/ipwl list                   — Показать всех игроков в белом списке и их IP
/ipwl reload                 — Перезагрузить конфиг и белый список с диска

Поддерживаемые форматы IP:

• Точный: 192.168.1.5
• С суффиксом-шаблоном: 192.168.1.* (совпадает с любым IP, начинающимся с этого префикса)
• CIDR-нотация: 192.168.1.0/24 (работает и для IPv4, и для IPv6)
• Любой IP: * (игрок может заходить откуда угодно)

Временный доступ

/ipwl tempadd <player> <ip> <duration>

Даёт доступ на ограниченное время, не меняя постоянный белый список. Примеры длительности: 30m, 2h, 1d, 3600s. Когда время истекает, все онлайн-админы получают уведомление автоматически.

Бан по IP

/ipwl banip <ip>       — Навсегда забанить IP (блокирует все аккаунты с него)
/ipwl unbanip <ip>     — Снять постоянный бан
/ipwl banip list       — Показать все навсегда забаненные IP

Постоянные баны сохраняются в config/ipwl.json и переживают перезапуск сервера.

Инструменты безопасности

/lockdown on     — Немедленно заблокировать все новые подключения (админы всё равно могут зайти)
/lockdown off    — Вернуться к обычной работе
/seen <player>   — Показать последний известный IP и время для игрока
/connections     — Список всех активных подключений
/security status — Показать живую статистику безопасности (заблокировано, разрешено, временные баны и т. д.)

Оповещения о неизвестных игроках

Когда кто-то пытается зайти и его нет в белом списке, каждый онлайн-админ получает в чат сообщение с двумя кликабельными кнопками:

• [Accept] — мгновенно выполняет `/ipwl add `
• [Ban IP] — мгновенно выполняет `/ipwl banip `

Одновременно консоль сервера выводит хорошо заметный блок:

[IPWL] ====================================================
[IPWL]   !! UNKNOWN CONNECTION ATTEMPT !!
[IPWL] ====================================================
[IPWL]   Name   : Steve
[IPWL]   IP     : 192.168.1.100
[IPWL]   To add : /ipwl add Steve 192.168.1.100
[IPWL]   To ban : /ipwl banip 192.168.1.100
[IPWL] ====================================================

Все действия администраторов (принятие, бан, удаление) транслируются всем онлайн-администраторам, чтобы никто не действовал на основе устаревшей информации.

---

## Брутфорс и ограничение частоты

Мод автоматически обнаруживает и блокирует подозрительные схемы подключений:

| Схема | Действие |
|---|---|
| Один IP пробует 3+ разных имени пользователя за 60 секунд | **Бан на 1 час** (бот / credential stuffing) |
| Один IP слишком часто долбит сервер (порог ограничения частоты) | **Бан на 5 минут** (настраивается) |
| Постоянный бан в конфиге | Блокировка навсегда |

Оба типа бана применяются до завершения аутентификации.

---

## Логирование

/ipwl logs verbose — Логировать все попытки, повторы и отладочную информацию /ipwl logs silent — Логировать только кики и критичные события безопасности (по умолчанию)

Консоль всегда показывает оповещения о неизвестных игроках и обнаружения брутфорса независимо от уровня логирования.

---

## Конфигурация

Находится в `config/ipwl.json`. Создаётся автоматически при первом запуске.

| Поле | По умолчанию | Описание |
|---|---|---|
| `maxConnectionsPerIp` | `2` | Максимум одновременных сессий с одного IP |
| `rateLimitWindowMs` | `1000` | Минимум мс между подключениями с одного IP |
| `maxFailuresBeforeTempBan` | `5` | Провалов ограничения частоты до временного бана на 5 минут |
| `tempBanDurationMs` | `300000` | Длительность временного бана для одного имени (мс) |
| `enableRateLimit` | `true` | Включить ограничение частоты |
| `enableDuplicateCheck` | `true` | Блокировать повторные входы под одним именем пользователя |
| `enableJoinAlerts` | `true` | Отправлять админам оповещения о неизвестных игроках |
| `alertCooldownMs` | `30000` | Минимум мс между оповещениями для одного IP |
| `verboseLogging` | `false` | Дублирует `/ipwl logs verbose` |
| `allowWildcardIps` | `true` | Разрешить `*` как шаблон IP |
| `allowSubnetPatterns` | `true` | Разрешить шаблоны вида `192.168.1.*` |
| `admins` | `[]` | Список имён администраторов IPWL |
| `bannedIps` | `[]` | Навсегда забаненные IP |

---

## Файлы данных

| Файл | Содержимое |
|---|---|
| `config/ipwl.json` | Все настройки, список админов, постоянные баны IP |
| `config/ipwl_whitelist.json` | Привязки игрок → IP |
| `config/ipwl-stats.json` | Постоянная статистика подключений (переживает перезапуски) |
| `config/ipwl-seen.json` | Данные последнего входа для команды `/seen` |
| `config/ipwl-lang.json` | Необязательные переопределения сообщений (пересборка не нужна) |

Чтобы изменить любое игровое сообщение, создайте `config/ipwl-lang.json` на сервере и добавьте только те ключи, которые хотите изменить. Этот файл имеет приоритет над встроенными строками.

---

## Как это работает (кратко)

Каждая попытка входа перехватывается на `ServerboundHelloPacket` — самом первом пакете, который отправляет клиент — до начала аутентификации Mojang. Проверки выполняются в таком порядке:

1. Режим блокировки → блокировать не-админов
2. Постоянный бан IP → блокировать
3. Временный бан (ограничение частоты или эскалация брутфорса) → блокировать
4. Обнаружение брутфорса (3+ имени с одного IP за 60 с) → бан на 1 час
5. Ограничение частоты (слишком быстро) → блокировать, эскалация до временного бана после порога
6. Проверка повторного входа → блокировать
7. Проверка IP по вайтлисту → блокировать + оповестить админов, если не в списке
8. Максимум подключений на IP → блокировать
9. Разрешить вторичную асинхронную перепроверку после входа как страховку