{"id":24085407,"url":"https://github.com/andcool-systems/mc-session-validator","last_synced_at":"2026-04-16T02:31:57.703Z","repository":{"id":271791179,"uuid":"914081093","full_name":"Andcool-Systems/mc-session-validator","owner":"Andcool-Systems","description":"Клиентский сервис для проверки лицензии Minecraft-аккаунта и подключения к серверу через REST API.","archived":false,"fork":false,"pushed_at":"2025-01-11T23:27:00.000Z","size":107,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-27T02:50:25.800Z","etag":null,"topics":["minecraft","minecraft-client","minecraft-protocol","netty","rest-api","yggdrasil-minecraft-login"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Andcool-Systems.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-08T23:04:11.000Z","updated_at":"2025-01-18T17:44:17.000Z","dependencies_parsed_at":"2025-01-09T22:45:45.664Z","dependency_job_id":"4e3d1a19-6bb5-40a6-ac98-93ea2028b126","html_url":"https://github.com/Andcool-Systems/mc-session-validator","commit_stats":null,"previous_names":["andcool-systems/mc-session-validator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Andcool-Systems/mc-session-validator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Andcool-Systems%2Fmc-session-validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Andcool-Systems%2Fmc-session-validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Andcool-Systems%2Fmc-session-validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Andcool-Systems%2Fmc-session-validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Andcool-Systems","download_url":"https://codeload.github.com/Andcool-Systems/mc-session-validator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Andcool-Systems%2Fmc-session-validator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268273048,"owners_count":24223790,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-01T02:00:08.611Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["minecraft","minecraft-client","minecraft-protocol","netty","rest-api","yggdrasil-minecraft-login"],"created_at":"2025-01-10T01:28:13.450Z","updated_at":"2025-10-30T23:16:05.786Z","avatar_url":"https://github.com/Andcool-Systems.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Minecraft Session Validator\n\n## Описание\nMinecraft Session Validator — это сервис, предназначенный для прохождения первых этапов входа на Minecraft сервер. Как и [mc-oauth](https://mc-oauth.andcool.ru), он предназначен для использования в сторонних проектах. Однако, в отличие от mc-oauth, он реализует клиентскую часть, а не сервер. Для выполнения запроса необходимо передать `accessToken` сессии Minecraft, никнейм, UUID, а также данные о сервере.\n\n---\n\n## Как это работает?\n### Основные функции\nПомимо проверки аккаунта на лицензионность, сервис проверяет возможность клиента подключиться к указанному серверу. Это особенно полезно для проектов, где требуется подтверждение нахождения клиента в белом списке сервера.\n\n### Процесс входа\nСервис реализует клиентскую сторону фазы логина Minecraft Protocol:\n1. Через REST API создается запрос с данными клиента и сервера.\n2. Сервис авторизуется через серверы Mojang, чтобы подтвердить лицензионность сессии.\n3. После прохождения необходимых этапов авторизации и подключения к серверу клиент отключается, возвращая в API данные, полученные от сервера.\n\n\u003e Сервис намеренно не реализует пакет `login_acknowledged`, чтобы исключить возможность полного входа на сервер.\n\nЕсли подключение невозможно (например, из-за невалидной сессии или других ошибок), сервис возвращает подробное описание ошибки.\n\n### Основные сценарии использования\nСервис создавался как часть более крупного проекта, требующего подтверждения нахождения Minecraft-профиля в белом списке сервера при регистрации.\n\n---\n\n## Особенности реализации\nЭтот сервис не должен быть доступен публично, для предотвращения DoS атак на сервера Minecraft. Вместо этого, он должен быть запущен на локальном интерфейсе, а доступ к нему должен осуществляться через другой API враппер.    \n\nОбращения к врапперу должен производить Minecraft мод, который так же будет осуществлять аутентификацию на уровне API враппера. Мод должен получить у клиента accessToken, имя пользователя и его UUID и отправить на промежуточный API. API, в свою очередь должен сделать `POST` запрос на этот сервис с данными, которые он получил от клиента.\n\n\u003e [!WARNING]\n\u003e НАШ СЕРВИС НЕ СОБИРАЕТ ВАШИ ЛИЧНЫЕ ДАННЫЕ! ВСЕ ТОКЕНЫ ДОСТУПА УДАЛЯЮТСЯ СРАЗУ ПОСЛЕ ВЫПОЛНЕНИЯ ПОПЫТКИ ПОДКЛЮЧЕНИЯ К СЕРВЕРУ. ТАКЖЕ СЕРВИС НЕ МОЖЕТ ПОДКЛЮЧИТЬСЯ К СЕРВЕРУ ВМЕСТО ВАС, ТАК КАК ЭТО НЕ ВХОДИТ В ЕГО ЗАДАЧИ. ОДНАКО МЫ НЕ НЕСЕМ ОТВЕТСТВЕННОСТИ ЗА ВСЕ СТОРОННИЕ МОДИФИКАЦИИ НАШЕГО СЕРВИСА, СТОРОННИЕ API ИЛИ МОДЫ! ВСЕ ДОВЕРЕННЫЕ ПРОЕКТЫ, КОТОРЫЕ ДОБРОСОВЕСТНО ВЫПОЛНЯЮТ ТРЕБОВАНИЯ КОНФИДЕНЦИАЛЬНОСТИ НАШИХ ПОЛЬЗОВАТЕЛЕЙ БУДУТ ОПУБЛИКОВАНЫ В САМОМ КОНЦЕ ЭТОГО ФАЙЛА.\n---\n\n## Работа с API\n\nДля выполнения запроса сделайте `POST` запрос на эндпоинт `/connect` с JSON в теле:\n\n```json\n{\n    \"accessToken\": \"\u003caccessToken\u003e\",\n    \"nickname\": \"AndcoolSystems\",\n    \"UUID\": \"1420c63c-b111-4453-993f-b3479ba1d4c6\",\n    \"server\": {\n        \"ip\": \"mycoolserver.net\",\n        \"port\": 25565,\n        \"protocolVersion\": 769\n    }\n}\n```\n\n### Поля запроса:\n- **`accessToken`** — Токен сессии Minecraft (Можно получить через `MinecraftClient.getInstance().getSession().getAccessToken()` в Fabric).\n- **`nickname`** — Никнейм аккаунта, совпадающий с никнеймом в профиле Minecraft.\n- **`UUID`** — UUID аккаунта Minecraft (обязательно с тире).\n- **`server`** — Объект с информацией о сервере:\n  - `ip` — IP-адрес или доменное имя сервера.\n  - `port` — Порт сервера.\n  - `protocolVersion` — Версия протокола (доступна [здесь](https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Protocol_History)).\n\n\u003e **Примечание:**\n\u003e Возможны проблемы с `SRV` записями в DNS. Убедитесь, что порт совпадает с портом в записи.\n\n### Пример успешного ответа\nКод ответа `200` указывает на успешную авторизацию и подключение:\n\n```json\n{\n    \"nickname\": \"AndcoolSystems\",\n    \"UUID\": \"1420c63c-b111-4453-993f-b3479ba1d4c6\"\n}\n```\n\n\n## Ошибки\n\n### Ошибки парсинга JSON Body\n- **`422` — Неправильный формат JSON:**\n  ```json\n  {\n      \"message\": \"Couldn't parse JSON body\"\n  }\n  ```\n\n- **`400` — Отсутствует обязательное поле:**\n  ```json\n  {\n      \"message\": \"Field with key `{key}` not found\"\n  }\n  ```\n\n### Ошибки при входе\n- **Ошибка авторизации через Mojang:**\n  ```json\n  {\n      \"message\": \"Mojang API error\"\n  }\n  ```\n\n- **Ошибка подключения к серверу:**\n  - `500` — Истекло время ожидания ответа от сервера или сервер прервал соединение без сообщения:\n    ```json\n    {\n        \"message\": \"Server unexpectedly closed the connection\"\n    }\n    ```\n  - `400` — Хост не может быть разрешен:\n    ```json\n    {\n        \"message\": \"Unknown host\"\n    }\n    ```\n\n- **Отключение от сервера:**\n    Код статуса всегда `403`\n    ```json\n    {\n        \"cause\": \"Whitelist\",\n        \"raw\": \"You not whitelisted on this server!\"\n    }\n    ```\n  \u003e Ключ `raw` содержит сырое сообщение, которое было получено от сервера.  \n  \u003e Ключ `cause` содержит **предполагаемую** причину отключения. Так как сервера могут быть настроены по-разному, причина может отражать неправильную информацию. Если определить причину не получается, он будет иметь значение `Disconnected`.\n\n---\n\n\u003e [!WARNING]\n\u003e ЭТОТ ПРОЕКТ НАХОДИТСЯ В РАННЕЙ БЕТЕ И ОШИБКИ БУДУТ ИСПРАВЛЯТЬСЯ В ПРОЦЕССЕ РАЗРАБОТКИ!\n\n---\n\n**by AndcoolSystems with ❤, January 8, 2025**\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandcool-systems%2Fmc-session-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandcool-systems%2Fmc-session-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandcool-systems%2Fmc-session-validator/lists"}