galeon committed
1 parent
1943996608
commit
f10b654953
34 files changed
+2099
-4576
No files matched your search
+58
-141
@@ -1,170 +1,87 @@
|
||||
# AuthService
|
||||
|
||||
## Обзор класса
|
||||
`authservice.h`, `authservice.cpp`
|
||||
|
||||
`Minecraft_launcher` поддерживает три способа входа: офлайн-профиль без пароля, учётную запись
|
||||
Ely.by и учётную запись Microsoft. `AuthService` закрывает первые два: это Yggdrasil-клиент Ely.by
|
||||
плюс офлайн-режим. За третий отвечает [MsaAuthService](MsaAuthService.md).
|
||||
Вход через Ely.by, офлайн-профиль и загрузка `authlib-injector`. Вход через Microsoft живёт
|
||||
отдельно, в [MsaAuthService](MsaAuthService.md), но отдаёт результат в той же структуре
|
||||
`AuthResult`. Поэтому запуск игры дальше идёт одинаково, как бы игрок ни вошёл.
|
||||
|
||||
Результат любого способа — структура `AuthResult`, объявленная в этом же заголовке. Она содержит
|
||||
ровно то, что подставляется в аргументы запуска вида `${auth_*}`, поэтому дальше запуск игры идёт
|
||||
по общему пути независимо от того, как пользователь вошёл.
|
||||
Экземпляр создаёт и держит [LauncherBackend](LauncherBackend.md). Сервис ничего не пишет на диск,
|
||||
кроме скачанного jar: токены между запусками сохраняет бэкенд в `profiles.json`.
|
||||
|
||||
Класс также умеет скачивать `authlib-injector` — библиотеку, которая перенаправляет обращения игры
|
||||
к серверу авторизации на Ely.by.
|
||||
## AuthResult
|
||||
|
||||
## Место в проекте и зависимости
|
||||
Каждое поле соответствует подстановке в аргументах запуска.
|
||||
|
||||
Экземпляр создаётся и принадлежит [LauncherBackend](LauncherBackend.md); других владельцев нет.
|
||||
Заголовок подключает [MsaAuthService](MsaAuthService.md) — ради общей структуры `AuthResult` — и
|
||||
[GameLauncher](GameLauncher.md) через поля `LaunchOptions`, которые заполняются из результата
|
||||
авторизации.
|
||||
| Поле | Подстановка / смысл |
|
||||
|------|---------------------|
|
||||
| `ok` | вход удался |
|
||||
| `twoFactorRequired` | Ely.by требует одноразовый код |
|
||||
| `licenseMissing` | Microsoft: вход прошёл, но игры на аккаунте нет. Отдельный флаг, потому что повторный вход тут не поможет |
|
||||
| `error` | текст ошибки, если `ok == false` |
|
||||
| `playerName` | `${auth_player_name}` |
|
||||
| `uuid` | `${auth_uuid}`, hex без дефисов |
|
||||
| `accessToken` | `${auth_access_token}` |
|
||||
| `clientToken` | `${clientid}` |
|
||||
| `userType` | `${user_type}`: `legacy` (офлайн), `ELYBY`, `msa` |
|
||||
| `refreshToken` | только Microsoft: продление сессии без пароля |
|
||||
| `xuid` | только Microsoft: `${auth_xuid}` |
|
||||
| `expiresAt` | только Microsoft: когда истекает `accessToken`, UTC |
|
||||
|
||||
Требования сборки: `Qt6::Core` (`QDateTime`, `QJsonObject`, `QString`) и `Qt6::Network`
|
||||
(`QNetworkAccessManager`).
|
||||
## Офлайн
|
||||
|
||||
## Иерархия и роль
|
||||
`static AuthResult offline(nickname)` работает без сети. UUID считается так же, как в самом
|
||||
Minecraft: MD5 от `OfflinePlayer:<ник>`, после чего выставляются биты версии 3 и варианта RFC 4122.
|
||||
Значит, у одного ника всегда один UUID, и на офлайн-сервере игрок не теряет инвентарь. В
|
||||
`accessToken` и `clientToken` записывается `"0"`.
|
||||
|
||||
Наследует `QObject`: даёт мета-объектную систему, сигнал `progress` и владение по родителю.
|
||||
Виртуальных методов базового класса не переопределяет.
|
||||
Пустой ник — ошибка.
|
||||
|
||||
## Публичные структуры
|
||||
## Ely.by
|
||||
|
||||
### AuthResult
|
||||
Сервер — `https://authserver.ely.by`, протокол Yggdrasil, JSON по HTTPS.
|
||||
|
||||
Результат авторизации — то, что подставляется в `${auth_*}` аргументы запуска.
|
||||
`loginElyBy(login, password, clientToken, accessToken, callback)` старается не спрашивать пароль:
|
||||
|
||||
| Поле | Тип | Описание |
|
||||
|------|-----|----------|
|
||||
| `ok` | `bool` | Авторизация удалась |
|
||||
| `twoFactorRequired` | `bool` | Ely.by отклонил пароль с пометкой two factor — нужен одноразовый код |
|
||||
| `licenseMissing` | `bool` | Вход в Microsoft прошёл, но копии игры на аккаунте нет. Обрабатывается отдельно от прочих ошибок, потому что чинится только покупкой |
|
||||
| `error` | `QString` | Текст ошибки, когда `ok` равен `false` |
|
||||
| `playerName` | `QString` | Подставляется в `${auth_player_name}` |
|
||||
| `uuid` | `QString` | Подставляется в `${auth_uuid}`; hex без дефисов |
|
||||
| `accessToken` | `QString` | Подставляется в `${auth_access_token}` |
|
||||
| `clientToken` | `QString` | Подставляется в `${clientid}` |
|
||||
| `userType` | `QString` | Подставляется в `${user_type}`; принимает значения `legacy` (офлайн), `msa` (Microsoft) и `ELYBY` |
|
||||
| `refreshToken` | `QString` | Только для аккаунтов Microsoft: продлевает сессию без ввода пароля |
|
||||
| `xuid` | `QString` | Только для Microsoft; подставляется в `${auth_xuid}` |
|
||||
| `expiresAt` | `QDateTime` | Только для Microsoft: UTC-время, когда протухает `accessToken` |
|
||||
1. Если сохранённого `accessToken` нет, сразу `/auth/authenticate` с паролем.
|
||||
2. Если есть, `/auth/validate`. Ответ 200 — токен рабочий, вход закончен.
|
||||
3. Иначе `/auth/refresh`. Если продлить удалось, приходят новый токен, ник и UUID.
|
||||
4. Если и это не вышло, `/auth/authenticate` с паролем.
|
||||
|
||||
## Псевдонимы типов
|
||||
Если сервер недоступен (статус 0 и сетевая ошибка), цепочка обрывается с ошибкой, без попытки войти
|
||||
по паролю.
|
||||
|
||||
`AuthService::Callback` — `std::function<void(const AuthResult &)>`. Все сетевые методы
|
||||
асинхронные: колбэк вызывается ровно один раз и всегда в потоке GUI.
|
||||
Второй фактор Ely.by не сообщает отдельным кодом. Сервис ищет в тексте ошибки подстроку
|
||||
`two factor` и выставляет `twoFactorRequired`. Тогда бэкенд спрашивает код у игрока и вызывает
|
||||
`loginElyByWithTotp(login, password, totp, clientToken, callback)`, который отправляет пароль в виде
|
||||
`пароль:код`, как требует Ely.by.
|
||||
|
||||
## Публичные методы
|
||||
`clientToken` генерируется один раз на профиль (`generateClientToken()`, случайный UUID) и хранится
|
||||
вместе с ним: Yggdrasil привязывает выданный `accessToken` к этому значению.
|
||||
|
||||
#### explicit AuthService(QObject \*parent = nullptr)
|
||||
По ходу работы испускается `progress(message)`. Бэкенд пересылает его в `launchProgress`.
|
||||
|
||||
Создаёт сервис и его `QNetworkAccessManager`. Конструктор помечен `explicit`.
|
||||
## authlib-injector
|
||||
|
||||
#### static AuthResult offline(const QString &nickname)
|
||||
Без него игра пойдёт проверять сессию на серверы Mojang, и токен Ely.by окажется недействительным.
|
||||
Jar подключается к JVM через `-javaagent` (см. [GameLauncher](GameLauncher.md)).
|
||||
|
||||
Готовит результат для офлайн-профиля без единого сетевого запроса. UUID выводится из ника так же,
|
||||
как это делает сам Minecraft в офлайне: `UUID.nameUUIDFromBytes(("OfflinePlayer:" + name)
|
||||
.getBytes(UTF_8))`. Благодаря этому один и тот же ник всегда даёт один и тот же UUID, и прогресс
|
||||
на сервере не теряется.
|
||||
`ensureAuthlibInjector(targetDir, callback)`:
|
||||
|
||||
#### static QString generateClientToken()
|
||||
- если `<targetDir>/authlib-injector.jar` уже есть, сразу отдаёт путь. Версия не проверяется, и
|
||||
обновить файл можно, только удалив его;
|
||||
- иначе читает `https://authlib-injector.yushi.moe/artifact/latest.json`, скачивает jar по
|
||||
`download_url` и, если в манифесте есть `checksums.sha256`, сверяет хеш.
|
||||
|
||||
Случайный `clientToken` лаунчера. Генерируется один раз на профиль и хранится вместе с ним:
|
||||
Yggdrasil связывает выданный `accessToken` именно с этим значением.
|
||||
Колбэк получает либо путь, либо текст ошибки. `targetDir` — это `<root>/runtime`.
|
||||
|
||||
#### void loginElyBy(const QString &login, const QString &password, const QString &clientToken, const QString &accessToken, Callback callback)
|
||||
## Как вызываются колбэки
|
||||
|
||||
Полный цикл входа в Ely.by: сначала проверка имеющегося токена, затем его продление, и только при
|
||||
неудаче — авторизация по паролю. Пароль можно оставить пустым, если уже есть рабочий
|
||||
`accessToken`, — тогда пользователю не придётся вводить его заново.
|
||||
Все сетевые методы асинхронные, колбэк вызывается один раз в GUI-потоке. Если сервис удалить во
|
||||
время запроса, менеджер сети уйдёт вместе с ним, и колбэк не вызовется вообще. Бэкенд к тому же
|
||||
проверяет в каждом колбэке, не отменили ли запуск, пока шёл запрос.
|
||||
|
||||
По ходу работы испускает `progress` с описанием текущего шага. Результат приходит в `callback`
|
||||
один раз; при ответе с пометкой двухфакторной аутентификации в нём выставлен
|
||||
`twoFactorRequired`, и вызывающий код должен спросить у пользователя код и продолжить через
|
||||
`loginElyByWithTotp()`.
|
||||
|
||||
#### void loginElyByWithTotp(const QString &login, const QString &password, const QString &totp, const QString &clientToken, Callback callback)
|
||||
|
||||
Повтор авторизации с одноразовым кодом двухфакторной аутентификации. Пароль и код объединяются в
|
||||
одно поле в формате «пароль:код», как того требует Ely.by.
|
||||
|
||||
#### void ensureAuthlibInjector(const QString &targetDir, std::function<void(const QString &path, const QString &error)> callback)
|
||||
|
||||
Скачивает `authlib-injector` в `targetDir`, если его там ещё нет. Колбэк получает либо путь к
|
||||
готовому jar, либо текст ошибки — заполнено всегда ровно одно из двух.
|
||||
|
||||
Библиотека нужна только для профилей Ely.by: она подключается к JVM аргументом `-javaagent` и
|
||||
перенаправляет обращения игры к серверу авторизации.
|
||||
|
||||
## Сигналы
|
||||
|
||||
#### progress(const QString &message)
|
||||
|
||||
Описание текущего шага авторизации. Испускается по ходу всех сетевых операций.
|
||||
|
||||
Обработчик показывает сообщение пользователю: в главном окне лаунчера оно попадает в плашку
|
||||
статуса и держится до следующего сообщения, потому что шаг может занять заметное время.
|
||||
|
||||
## Владение и время жизни
|
||||
|
||||
Класс наследует `QObject` и принимает `parent` в конструкторе — родитель его и удалит.
|
||||
`QNetworkAccessManager` создаётся в конструкторе с сервисом в роли родителя и уничтожается вместе
|
||||
с ним.
|
||||
|
||||
Колбэки захватываются по значению и живут до своего единственного вызова. Уничтожение сервиса во
|
||||
время незавершённого запроса отменяет запрос вместе с менеджером сети — колбэк в этом случае не
|
||||
вызывается, поэтому захватывать в него сырые указатели на объекты с меньшим временем жизни, чем у
|
||||
сервиса, нельзя.
|
||||
|
||||
## Потокобезопасность
|
||||
|
||||
Только поток GUI. Все сетевые методы асинхронные, и их колбэки вызываются в том же потоке, в
|
||||
котором создан сервис. Собственной синхронизации в классе нет.
|
||||
|
||||
## Взаимодействие с другими классами
|
||||
|
||||
`LauncherBackend` вызывает методы входа при запуске игры и переправляет сигнал `progress` в
|
||||
интерфейс. Полученный `AuthResult` он раскладывает по полям `LaunchOptions`, которые уходят в
|
||||
[GameLauncher](GameLauncher.md). Путь, возвращённый `ensureAuthlibInjector()`, попадает в поле
|
||||
`authlibInjectorPath` тех же параметров запуска.
|
||||
|
||||
Сохранением токенов между запусками занимается `LauncherBackend`: сам сервис ничего не пишет на
|
||||
диск, кроме скачанного jar.
|
||||
|
||||
## Внешнее взаимодействие
|
||||
|
||||
**Сеть, исходящие запросы.** Класс общается с сервером авторизации Ely.by через
|
||||
`QNetworkAccessManager`. Формат — JSON поверх HTTPS, запросы инициирует всегда лаунчер. Внутренний
|
||||
помощник `postJson()` разделяет три исхода: успешный ответ, ответ с кодом ошибки и транспортную
|
||||
ошибку — последняя отдаётся отдельным параметром, чтобы отличить недоступную сеть от отказа
|
||||
сервера.
|
||||
|
||||
Отдельным каналом идёт загрузка `authlib-injector` — обычная HTTPS-загрузка файла в
|
||||
`targetDir`. Повторных попыток при неудаче класс не делает: решение о повторе принимает вызывающий
|
||||
код.
|
||||
|
||||
Все сигналы и колбэки приходят в поток GUI.
|
||||
|
||||
## Пример использования
|
||||
|
||||
```cpp
|
||||
auto *auth = new AuthService(this);
|
||||
connect(auth, &AuthService::progress, this, &Backend::showStatus);
|
||||
|
||||
auth->loginElyBy(profile.login, profile.password,
|
||||
profile.clientToken, profile.accessToken,
|
||||
[this](const AuthResult &result) {
|
||||
if (result.twoFactorRequired) {
|
||||
emit twoFactorRequired(m_pendingProfileName);
|
||||
return;
|
||||
}
|
||||
if (!result.ok) {
|
||||
emit launchError(result.error);
|
||||
return;
|
||||
}
|
||||
continueLaunch(result);
|
||||
});
|
||||
```
|
||||
Повторных попыток при сетевых ошибках нет.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in new issue
Block a user