An open API service indexing awesome lists of open source software.

https://github.com/andcool-systems/mc-session-validator

Клиентский сервис для проверки лицензии Minecraft-аккаунта и подключения к серверу через REST API.
https://github.com/andcool-systems/mc-session-validator

minecraft minecraft-client minecraft-protocol netty rest-api yggdrasil-minecraft-login

Last synced: 3 months ago
JSON representation

Клиентский сервис для проверки лицензии Minecraft-аккаунта и подключения к серверу через REST API.

Awesome Lists containing this project

README

        

# Minecraft Session Validator

## Описание
Minecraft Session Validator — это сервис, предназначенный для прохождения первых этапов входа на Minecraft сервер. Как и [mc-oauth](https://mc-oauth.andcool.ru), он предназначен для использования в сторонних проектах. Однако, в отличие от mc-oauth, он реализует клиентскую часть, а не сервер. Для выполнения запроса необходимо передать `accessToken` сессии Minecraft, никнейм, UUID, а также данные о сервере.

---

## Как это работает?
### Основные функции
Помимо проверки аккаунта на лицензионность, сервис проверяет возможность клиента подключиться к указанному серверу. Это особенно полезно для проектов, где требуется подтверждение нахождения клиента в белом списке сервера.

### Процесс входа
Сервис реализует клиентскую сторону фазы логина Minecraft Protocol:
1. Через REST API создается запрос с данными клиента и сервера.
2. Сервис авторизуется через серверы Mojang, чтобы подтвердить лицензионность сессии.
3. После прохождения необходимых этапов авторизации и подключения к серверу клиент отключается, возвращая в API данные, полученные от сервера.

> Сервис намеренно не реализует пакет `login_acknowledged`, чтобы исключить возможность полного входа на сервер.

Если подключение невозможно (например, из-за невалидной сессии или других ошибок), сервис возвращает подробное описание ошибки.

### Основные сценарии использования
Сервис создавался как часть более крупного проекта, требующего подтверждения нахождения Minecraft-профиля в белом списке сервера при регистрации.

---

## Особенности реализации
Этот сервис не должен быть доступен публично, для предотвращения DoS атак на сервера Minecraft. Вместо этого, он должен быть запущен на локальном интерфейсе, а доступ к нему должен осуществляться через другой API враппер.

Обращения к врапперу должен производить Minecraft мод, который так же будет осуществлять аутентификацию на уровне API враппера. Мод должен получить у клиента accessToken, имя пользователя и его UUID и отправить на промежуточный API. API, в свою очередь должен сделать `POST` запрос на этот сервис с данными, которые он получил от клиента.

> [!WARNING]
> НАШ СЕРВИС НЕ СОБИРАЕТ ВАШИ ЛИЧНЫЕ ДАННЫЕ! ВСЕ ТОКЕНЫ ДОСТУПА УДАЛЯЮТСЯ СРАЗУ ПОСЛЕ ВЫПОЛНЕНИЯ ПОПЫТКИ ПОДКЛЮЧЕНИЯ К СЕРВЕРУ. ТАКЖЕ СЕРВИС НЕ МОЖЕТ ПОДКЛЮЧИТЬСЯ К СЕРВЕРУ ВМЕСТО ВАС, ТАК КАК ЭТО НЕ ВХОДИТ В ЕГО ЗАДАЧИ. ОДНАКО МЫ НЕ НЕСЕМ ОТВЕТСТВЕННОСТИ ЗА ВСЕ СТОРОННИЕ МОДИФИКАЦИИ НАШЕГО СЕРВИСА, СТОРОННИЕ API ИЛИ МОДЫ! ВСЕ ДОВЕРЕННЫЕ ПРОЕКТЫ, КОТОРЫЕ ДОБРОСОВЕСТНО ВЫПОЛНЯЮТ ТРЕБОВАНИЯ КОНФИДЕНЦИАЛЬНОСТИ НАШИХ ПОЛЬЗОВАТЕЛЕЙ БУДУТ ОПУБЛИКОВАНЫ В САМОМ КОНЦЕ ЭТОГО ФАЙЛА.
---

## Работа с API

Для выполнения запроса сделайте `POST` запрос на эндпоинт `/connect` с JSON в теле:

```json
{
"accessToken": "",
"nickname": "AndcoolSystems",
"UUID": "1420c63c-b111-4453-993f-b3479ba1d4c6",
"server": {
"ip": "mycoolserver.net",
"port": 25565,
"protocolVersion": 769
}
}
```

### Поля запроса:
- **`accessToken`** — Токен сессии Minecraft (Можно получить через `MinecraftClient.getInstance().getSession().getAccessToken()` в Fabric).
- **`nickname`** — Никнейм аккаунта, совпадающий с никнеймом в профиле Minecraft.
- **`UUID`** — UUID аккаунта Minecraft (обязательно с тире).
- **`server`** — Объект с информацией о сервере:
- `ip` — IP-адрес или доменное имя сервера.
- `port` — Порт сервера.
- `protocolVersion` — Версия протокола (доступна [здесь](https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Protocol_History)).

> **Примечание:**
> Возможны проблемы с `SRV` записями в DNS. Убедитесь, что порт совпадает с портом в записи.

### Пример успешного ответа
Код ответа `200` указывает на успешную авторизацию и подключение:

```json
{
"nickname": "AndcoolSystems",
"UUID": "1420c63c-b111-4453-993f-b3479ba1d4c6"
}
```

## Ошибки

### Ошибки парсинга JSON Body
- **`422` — Неправильный формат JSON:**
```json
{
"message": "Couldn't parse JSON body"
}
```

- **`400` — Отсутствует обязательное поле:**
```json
{
"message": "Field with key `{key}` not found"
}
```

### Ошибки при входе
- **Ошибка авторизации через Mojang:**
```json
{
"message": "Mojang API error"
}
```

- **Ошибка подключения к серверу:**
- `500` — Истекло время ожидания ответа от сервера или сервер прервал соединение без сообщения:
```json
{
"message": "Server unexpectedly closed the connection"
}
```
- `400` — Хост не может быть разрешен:
```json
{
"message": "Unknown host"
}
```

- **Отключение от сервера:**
Код статуса всегда `403`
```json
{
"cause": "Whitelist",
"raw": "You not whitelisted on this server!"
}
```
> Ключ `raw` содержит сырое сообщение, которое было получено от сервера.
> Ключ `cause` содержит **предполагаемую** причину отключения. Так как сервера могут быть настроены по-разному, причина может отражать неправильную информацию. Если определить причину не получается, он будет иметь значение `Disconnected`.

---

> [!WARNING]
> ЭТОТ ПРОЕКТ НАХОДИТСЯ В РАННЕЙ БЕТЕ И ОШИБКИ БУДУТ ИСПРАВЛЯТЬСЯ В ПРОЦЕССЕ РАЗРАБОТКИ!

---

**by AndcoolSystems with ❤, January 8, 2025**