Add Dev_Docs with protocol, blockchain, and API design analysis

2026-03-26 15:27:59 +03:00
parent 18bf5d65d7
commit b23ecdfdf2
6 changed files with 448 additions and 0 deletions
@@ -0,0 +1,65 @@
+# Соединение с сервером и сессии
+
+## 1) Базовый транспорт
+
+- Сервер работает по WebSocket + JSON-протокол (`op`, `requestId`, `payload`).
+- Для каждой операции есть handler в `JsonHandlerRegistry`.
+
+## 2) Схема авторизации (актуальная)
+
+В проекте реализованы **две двухшаговые схемы**:
+
+### A. Создание новой сессии (через device key)
+
+1. `AuthChallenge(login)`
+   - сервер проверяет, что пользователь существует;
+   - кладёт в контекст соединения `authNonce`.
+
+2. `CreateAuthSession(...)`
+   - клиент подписывает строку `AUTH_CREATE_SESSION:{login}:{timeMs}:{authNonce}` приватным **device key**;
+   - сервер валидирует подпись, создаёт запись в `active_sessions`, возвращает `sessionId`;
+   - в сессии хранится `session_key` (публичный ключ сессии), который клиент сгенерировал для дальнейших логинов.
+
+### B. Вход в существующую сессию (через session key)
+
+1. `SessionChallenge(sessionId)`
+   - сервер выдаёт одноразовый nonce с TTL.
+
+2. `SessionLogin(sessionId, timeMs, signature)`
+   - клиент подписывает `SESSION_LOGIN:{sessionId}:{timeMs}:{nonce}` приватным ключом сессии;
+   - сервер проверяет подпись по `active_sessions.session_key`;
+   - при успехе возвращает `storagePwd`.
+
+## 3) Работа со списком сессий
+
+### `ListSessions`
+
+- Доступно только в состоянии `AUTH_STATUS_USER`.
+- Возвращает все активные сессии текущего пользователя:
+  - `sessionId`
+  - информация о клиенте
+  - `lastAuthirificatedAtMs`
+  - гео (по ip, через кэш/lookup).
+
+### `CloseActiveSession`
+
+- В реестре операций присутствует.
+- Используется для закрытия указанной или текущей сессии.
+
+## 4) Важные детали безопасности
+
+- Есть проверка рассинхрона времени клиента (обычно ±30 секунд).
+- Nonce одноразовые, хранятся в контексте конкретного ws-соединения.
+- При ошибках подписи/контекста сервер может закрывать WebSocket.
+
+## 5) Что уже хорошо
+
+- Разделены key-и: `device key` (создание сессии) и `session key` (повторные входы).
+- Не передаётся приватный ключ — только подписи.
+- Авторизация привязана к challenge/nonce.
+
+## 6) Что стоит дополнительно улучшить
+
+1. Добавить централизованный лимит попыток на `SessionLogin`/`CreateAuthSession`.
+2. Логировать причины отказов в метриках (без утечки чувствительных данных).
+3. Явно документировать формат Base64 (URL-safe/standard) для каждого поля, чтобы клиенты не путались.