Улучшен вход пользователя в аккаунт

2026-08-28 16:51:14 +04:00
parent f2fdb8195c
commit 357a05f7ec
25 changed files with 821 additions and 270 deletions
@@ -4,6 +4,7 @@

 Здесь четыре базовых метода обычной авторизации:

+- `ResolveLoginForAuth`
 - `AuthChallenge`
 - `CreateAuthSession`
 - `SessionChallenge`
@@ -67,6 +68,57 @@ ed25519/BASE64_PUBLIC_KEY

 ---

+## 1.1. `ResolveLoginForAuth`
+
+Первый шаг интерактивного входа. Операция не заменяет `GetUser` и не меняет его семантику.
+Она предназначена только для выбора правильного access server перед вводом пароля
+или запуском входа через доверенное устройство.
+
+Запрос:
+
+```json
+{
+  "op": "ResolveLoginForAuth",
+  "requestId": "login-route-1",
+  "payload": {
+    "login": "alice"
+  }
+}
+```
+
+Успешный ответ всегда имеет `status=200`, а `payload.resolution` принимает одно из значений:
+
+- `LOCAL` — пользователь существует, и `access_servers[0]` указывает на этот сервер;
+- `REMOTE` — пользователь существует, но его первый access server другой;
+- `NOT_FOUND` — пользователя нет в локально синхронизированном Solana PDA snapshot;
+- `NO_ACCESS_SERVER` — пользователь существует, но корректный первый access server не найден.
+
+Для `LOCAL` и `REMOTE` сервер возвращает канонический `login`. Для `REMOTE`
+также возвращаются `accessServerLogin` и `accessServerUrl`, чтобы UI сразу мог
+перенаправить пользователя на правильную точку входа.
+
+Пример `REMOTE`:
+
+```json
+{
+  "op": "ResolveLoginForAuth",
+  "requestId": "login-route-1",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "resolution": "REMOTE",
+    "login": "Alice",
+    "accessServerLogin": "shine-node-2",
+    "accessServerUrl": "wss://node2.example.org/ws"
+  }
+}
+```
+
+Важно: это UX-проверка, а не security boundary. `AuthChallenge/CreateAuthSession`
+повторно определяют отношение пользователя к текущему серверу. Пользователь другого
+access server может криптографически авторизоваться напрямую, но получает
+`connectionScope=REMOTE`.
+
 ## 2. `AuthChallenge`

 ### Запрос
@@ -339,3 +391,33 @@ SESSION_LOGIN:{sessionId}:{timeMs}:{nonce}
  }
 }
 ```
+
+### LOCAL/REMOTE scope успешной авторизации
+
+`CreateAuthSession` и `SessionLogin` дополнительно возвращают:
+
+```json
+{
+  "connectionScope": "LOCAL"
+}
+```
+
+или:
+
+```json
+{
+  "connectionScope": "REMOTE"
+}
+```
+
+`REMOTE` означает, что пользователь успешно доказал владение ключом/сессией, но
+текущий сервер не является его `access_servers[0]`. Такой WebSocket регистрируется
+как активное соединение и может использоваться для realtime звонков, однако
+центральная политика сервера разрешает ему только технические и call-signaling
+операции. Обычные homeserver-операции отвечают `403 / USER_NOT_LOCAL`.
+
+Разрешённый минимальный набор для `REMOTE`: `Ping`, `GetServerInfo`,
+`GetCallIceConfig`, `CallInviteBroadcast`, `CallSignalToSession`, `SendSignal`,
+`CallDeliveryReport`, `ClientErrorLog`, `ClientDebugLog`, `CloseActiveSession`
+и `ResolveLoginForAuth`.
+
@@ -313,9 +313,14 @@ TTL заявки фиксирован на сервере и сейчас все
 - `400 / BAD_PAYLOAD_TYPE`
 - `422 / PAIRING_NOT_AVAILABLE`
 - `422 / PAIRING_PASSWORD_INVALID` — pairing-пароль не подходит. Та же ошибка возвращается и если новое устройство ввело пароль, а у пользователя режим pairing включён без пароля.
- `422 / PAIRING_NO_TRUSTED_SESSION_ONLINE` — сейчас нет ни одной онлайн доверённой сессии пользователя, поэтому код не создаётся.
+Код создаётся даже если сейчас нет ни одной онлайн доверённой сессии пользователя.
+В таком случае `trustedSessionOnline=false`, а pairing-заявка остаётся в состоянии
+`created` до подтверждения, отмены или истечения TTL.
 - `429 / PAIRING_RATE_LIMITED`

+Также `StartTrustedDeviceLogin` разрешён только на первом access server пользователя.
+На другом сервере операция возвращает `409 / USER_NOT_LOCAL`.
+
 ### 5.4. `ListTrustedDeviceLoginRequests`

 Доступно для любой уже авторизованной доверенной сессии пользователя.
@@ -16,6 +16,7 @@
 | `SearchUsers` | `01_User_Registration_API.md` | поиск логинов по префиксу |
 | `TestGetFreeAvatarQuota` | `14_Test_Free_Avatar_Upload_API.md` | временный тестовый просмотр остатка бесплатных загрузок аватара |
 | `TestUploadFreeAvatar` | `14_Test_Free_Avatar_Upload_API.md` | временная тестовая бесплатная загрузка маленького аватара в Arweave |
+| `ResolveLoginForAuth` | `02_Authentication_API.md` | проверка login перед входом: LOCAL / REMOTE / NOT_FOUND / NO_ACCESS_SERVER + URL правильного access server |
 | `AuthChallenge` | `02_Authentication_API.md` | challenge для создания новой сессии |
 | `CreateAuthSession` | `02_Authentication_API.md` | создание новой авторизованной сессии |
 | `SessionChallenge` | `02_Authentication_API.md` | challenge для входа в существующую сессию |