TgAuth — Minecraft 1.21.1 NeoForge Auth Mod v2

Двухпоточная авторизация через Telegram с поддержкой 12-часовых сессий устройства.

---

🔄 Полная схема работы

Новый игрок (первый вход)

1. Игрок открывает Telegram → пишет боту /start
        │
        ▼
   Бот проверяет вайтлист
   ├─ НЕТ → "Ваш аккаунт не авторизован"
   └─ ДА  →  Бот выдаёт 6-значный код, напр. 847392
             "Введите на сервере: /tgauth link 847392"
        │
        ▼
2. Игрок заходит на сервер → заморожен у спавна
   Видит инструкцию: /tgauth link <code>
        │
        ▼
3. Игрок вводит /tgauth link 847392
        │
   ┌── Код верен + не истёк + TG-аккаунт в вайтлисте?
   ├─ НЕТ  → Сообщение об ошибке
   └─ ДА   → UUID привязан к Telegram ID
             Сессия устройства создана на 12 часов
             ✅ Игрок разморожен и может играть

Верифицированный игрок (повторный вход)

Игрок заходит на сервер
        │
        ▼
Проверка сессии устройства (IP-fingerprint совпадает + не истекла?)
   │
   ├─ ДА → ✅ Автовход, без Telegram
   │       "Session valid — welcome back! (10h remaining)"
   │
   └─ НЕТ → Бот шлёт сообщение в Telegram:
   
             ┌──────────────────────────────────────┐
             │ 🔐 Login request                      │
             │                                       │
             │ Player Steve is logging in to         │
             │ My Minecraft Server.                  │
             │                                       │
             │ [✅ Yes]        [❌ No]                │
             └──────────────────────────────────────┘
             
             Игрок заморожен у спавна
                    │
               Нажал кнопку:
               ├─ ✅ Yes → ✅ Сессия сохранена на 12ч, игрок разморожен
               ├─ ❌ No  → Кик: "Login denied via Telegram"
               └─ Таймаут → Кик: "Confirmation timed out"

---

🚀 Установка

1. Создать бота

1. @BotFather → /newbot → получить токен

2. Узнать Telegram ID игроков

Пусть игроки напишут @userinfobot → получат свой Id.

3. Собрать мод

./gradlew build
# → build/libs/tgauth-2.0.0.jar

4. Установить на сервер

Скопировать JAR в mods/, запустить сервер (создастся конфиг).

5. Настроить config/tgauth-server.toml

[bot]
    botToken = "1234567890:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    botUsername = "MyServerAuthBot"

[whitelist]
    # Telegram ID, которым разрешено регистрироваться
    telegramIds = ["123456789", "987654321", "555000111"]

[codes]
    codeTtlSeconds = 300        # код живёт 5 минут

[login]
    confirmTimeoutSeconds = 60   # 60с на нажатие Yes/No
    kickOnTimeout = true

[session]
    durationHours = 12           # сессия устройства: 12 часов

---

⌨️ Команды

Для игроков

Команда	Описание
/tgauth link <code>	Привязать Telegram (новый игрок)
/tgauth status	Показать статус привязки и сессии

Для операторов (OP 2+)

Команда	Описание
/tgauth admin whitelist list	Список всех Telegram ID в вайтлисте
/tgauth admin whitelist add <tgId>	Добавить TG ID
/tgauth admin whitelist remove <tgId>	Удалить TG ID
/tgauth admin unlink <player>	Отвязать аккаунт
/tgauth admin force <player>	Принудительно авторизовать
/tgauth admin sessions <player>	Показать активные сессии устройств
/tgauth admin clearsessions <player>	Сбросить все сессии (потребует TG-входа)
/tgauth admin reload	Перезагрузить вайтлист из конфига

---

🖥️ Как работает fingerprint устройства

Fingerprint строится из:

• IP-адрес клиента
• UUID игрока

Результат: SHA-256, truncated до 16 символов.

Что считается сменой устройства:

• Другой IP (другая сеть, VPN, переключение WiFi/Mobile)
• Это намеренно — даёт баланс между удобством и безопасностью

---

📁 Структура проекта

src/main/java/com/tgauth/
├── TgAuthMod.java                 Точка входа
├── bot/
│   └── TelegramBot.java           Long-polling, /start, Yes/No кнопки
├── command/
│   └── TgAuthCommand.java         /tgauth link, status, admin
├── config/
│   └── TgAuthConfig.java          TOML конфиг
├── data/
│   ├── LoginSession.java          In-memory сессия входа (ожидание Telegram)
│   ├── LoginSessionStore.java     Хранилище LoginSession + lookup по callback
│   ├── PendingRegistration.java   Запись для кода регистрации
│   ├── PlayerRecord.java          Постоянные данные игрока (TG ID + device sessions)
│   ├── PlayerStore.java           Gson-хранилище PlayerRecord → JSON на диск
│   ├── RegistrationCodeStore.java Выдача и проверка 6-значных кодов
│   └── WhitelistService.java      Загрузка и управление TG-вайтлистом
├── event/
│   └── PlayerEventHandler.java    Join / Tick / Disconnect логика
└── util/
    └── DeviceFingerprint.java     SHA-256 fingerprint из IP + UUID

---

💾 Хранение данных

Файл: <world>/data/tgauth_players.json

[
  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "telegramId": 123456789,
    "sessions": {
      "ab12cd34ef56ab12": 1715043600000
    }
  }
]