05 01 25

Документы: Описание БД и всех запросов актуализировал!
2026-01-05 17:17:39 +03:00
parent a6a5089379
commit 94777c58c6
6 changed files with 714 additions and 152 deletions
@@ -1,52 +1,286 @@
-Протокол использует единый формат JSON-сообщений: клиент всегда отправляет запросы с полями op, requestId и payload, сервер отвечает тем же op и requestId, добавляя status (200 для успеха, любое другое значение — ошибка) и либо payload, либо error. 
+JSON WebSocket протокол сервера: список существующих запросов (op)

-События от сервера приходят без requestId и status, содержат только op и payload и не являются ответами на запросы.
+Общий формат любого запроса (client → server):
+op - имя операции (строка)
+requestId - идентификатор запроса для связывания с ответом (строка)
+payload - объект с параметрами конкретной операции (object)

-# Примеры JSON для SearchUsers (минимальная шпаргалка)
+Общий формат любого ответа (server → client):
+op - имя операции (строка, совпадает с запросом)
+requestId - идентификатор запроса (строка, совпадает с запросом)
+status - статус результата (200 = успех, другое = ошибка)
+payload - объект с полями ответа (object; при ошибке содержит code/message)

-## 🔵 Запрос (client → server)
+Группа: Авторизация и сессии

-```json
-{
-  "op": "SearchUsers",
-  "requestId": "req-1",
-  "payload": {
-    "query": "ai"
-  }
-}
+Эта группа управляет входом пользователя, созданием/обновлением сессий и безопасным завершением активных подключений.

-🟢 Успешный ответ (server → client)
+----- AuthChallenge
+Одноразовый шаг 1: по логину выдаёт nonce (authNonce), который затем подписывается на шаге 2.

-{
-  "op": "SearchUsers",
-  "requestId": "req-1",
-  "status": 200,
-  "payload": {
-    "users": [
-      { "login": "aidar" },
-      { "login": "anya" }
-    ]
-  }
-}
+Запрос:
+op - "AuthChallenge"
+requestId - id запроса
+login - логин пользователя, для которого начинается авторизация

-🔴 Ошибочный ответ (server → client)
+Ответ (успех):
+op - "AuthChallenge"
+requestId - id запроса
+status - 200 если успех
+authNonce - одноразовый nonce, Base64Url(32 bytes) без padding

-{
-  "op": "SearchUsers",
-  "requestId": "req-1",
-  "status": 403,
-  "error": {
-    "code": "SESSION_EXPIRED",
-    "message": "Сессия истекла"
-  }
-}
+Ответ (ошибка):
+op - "AuthChallenge"
+requestId - id запроса
+status - код ошибки
+code - строковый код ошибки
+message - человекочитаемое описание ошибки

-🟣 Событие (server → client, не ответ)
+----- CreateAuthSession
+Шаг 2: проверяет подпись владения ключом, создаёт новую active_session и возвращает sessionId/sessionPwd.

-{
-  "op": "NewBlockEvent",
-  "payload": {
-    "blockchainId": 42,
-    "blockNumber": 101
-  }
-}
+Запрос:
+op - "CreateAuthSession"
+requestId - id запроса
+storagePwd - ключ/пароль хранилища клиента, base64(32 bytes)
+timeMs - время на клиенте в мс (для защиты от повторов и проверки рассинхрона)
+signatureB64 - подпись Ed25519 над строкой "AUTHORIFICATED:" + timeMs + authNonce (base64)
+clientInfo - короткая строка о клиенте/устройстве (до 50 символов), опционально
+
+Ответ (успех):
+op - "CreateAuthSession"
+requestId - id запроса
+status - 200 если успех
+sessionId - идентификатор сессии, Base64Url(32 bytes)
+sessionPwd - секрет сессии, Base64Url(32 bytes)
+
+Ответ (ошибка):
+op - "CreateAuthSession"
+requestId - id запроса
+status - код ошибки
+code - строковый код ошибки
+message - человекочитаемое описание ошибки
+
+----- RefreshSession
+Повторный вход без подписи: проверяет sessionId+sessionPwd, обновляет метаданные сессии и возвращает storagePwd.
+
+Запрос:
+op - "RefreshSession"
+requestId - id запроса
+sessionId - идентификатор ранее выданной сессии (base64/url-safe строка)
+sessionPwd - секрет ранее выданной сессии (base64/url-safe строка)
+clientInfo - короткая строка о клиенте/устройстве (до 50 символов), опционально
+
+Ответ (успех):
+op - "RefreshSession"
+requestId - id запроса
+status - 200 если успех
+storagePwd - пароль хранилища, сохранённый в сессии (base64(32 bytes))
+
+Ответ (ошибка):
+op - "RefreshSession"
+requestId - id запроса
+status - код ошибки
+code - строковый код ошибки
+message - человекочитаемое описание ошибки
+
+----- ListSessions
+Возвращает список всех активных сессий текущего пользователя (для управления устройствами/входами).
+
+Запрос:
+op - "ListSessions"
+requestId - id запроса
+timeMs - время на клиенте в мс (нужно только если статус AUTH_IN_PROGRESS)
+signatureB64 - подпись Ed25519 над строкой "AUTHORIFICATED:" + timeMs + authNonce (нужно только если статус AUTH_IN_PROGRESS)
+
+Ответ (успех):
+op - "ListSessions"
+requestId - id запроса
+status - 200 если успех
+sessions - массив активных сессий пользователя
+
+Поля элемента sessions[i]:
+sessionId - идентификатор сессии, Base64Url(32 bytes)
+clientInfoFromClient - что прислал клиент в clientInfo
+clientInfoFromRequest - что собрал сервер из окружения (UA/платформа и т.п.)
+geo - строка "Country, City" или "unknown"
+lastAuthirificatedAtMs - время последней успешной авторизации/refresh (мс)
+
+Ответ (ошибка):
+op - "ListSessions"
+requestId - id запроса
+status - код ошибки
+code - строковый код ошибки
+message - человекочитаемое описание ошибки
+
+----- CloseActiveSession
+Закрывает одну активную сессию пользователя (указанную или текущую), при необходимости подтверждая владение ключом подписью.
+
+Запрос:
+op - "CloseActiveSession"
+requestId - id запроса
+sessionId - идентификатор сессии для закрытия (если пусто, закрывается текущая)
+timeMs - время на клиенте в мс (нужно только если статус AUTH_IN_PROGRESS)
+signatureB64 - подпись Ed25519 над строкой "AUTHORIFICATED:" + timeMs + authNonce (нужно только если статус AUTH_IN_PROGRESS)
+
+Ответ (успех):
+op - "CloseActiveSession"
+requestId - id запроса
+status - 200 если успех
+
+Ответ (ошибка):
+op - "CloseActiveSession"
+requestId - id запроса
+status - код ошибки
+code - строковый код ошибки
+message - человекочитаемое описание ошибки
+
+Группа: Блокчейн (загрузка блоков)
+
+Эта группа отвечает за приём и валидацию блоков (цепочка, линии, подпись/хэш) и атомарную запись в БД+файл.
+
+----- AddBlock
+Добавляет следующий блок в конкретный blockchainName, строго проверяя номера, prev-хэши, линии, подпись и лимит размера.
+
+Запрос:
+op - "AddBlock"
+requestId - id запроса
+blockchainName - имя цепочки (по нему вычисляется login)
+globalNumber - глобальный номер добавляемого блока (должен быть serverLastGlobalNumber+1)
+prevGlobalHash - HEX(64) предыдущего глобального хэша (или "" только там, где это допускается правилами)
+blockBytesB64 - полный блок (raw+signature+hash) в Base64
+
+Ответ (успех):
+op - "AddBlock"
+requestId - id запроса
+status - 200 если успех
+reasonCode - null при успехе
+serverLastGlobalNumber - последний глобальный номер, который сервер считает актуальным после обработки
+serverLastGlobalHash - последний глобальный хэш (HEX(64)) после обработки
+
+Ответ (ошибка):
+op - "AddBlock"
+requestId - id запроса
+status - код ошибки (например 400/404/413/500)
+reasonCode - строка причины (например bad_block_base64, bad_global_number, limit_exceeded и т.п.)
+serverLastGlobalNumber - текущий серверный lastGlobalNumber
+serverLastGlobalHash - текущий серверный lastGlobalHash (HEX(64), если известен)
+
+Группа: Параметры пользователя (UserParams)
+
+Эта группа хранит и отдаёт подписанные клиентом параметры (ключ-значение) для синхронизации и состояния.
+
+----- UpsertUserParam
+Добавляет или обновляет параметр пользователя, проверяя подпись Ed25519 и применяя запись только если time_ms новее.
+
+Запрос:
+op - "UpsertUserParam"
+requestId - id запроса
+login - логин пользователя
+param - имя параметра
+time_ms - метка времени значения в мс
+value - значение параметра
+device_key - публичный ключ устройства, base64(32 bytes)
+signature - подпись Ed25519 от строки USER_PARAMETER_PREFIX + login + param + time_ms + value
+
+Ответ (успех):
+op - "UpsertUserParam"
+requestId - id запроса
+status - 200 если успех
+
+Ответ (ошибка):
+op - "UpsertUserParam"
+requestId - id запроса
+status - код ошибки
+code - строковый код ошибки
+message - человекочитаемое описание ошибки
+
+----- GetUserParam
+Возвращает один сохранённый параметр пользователя.
+
+Запрос:
+op - "GetUserParam"
+requestId - id запроса
+login - логин пользователя
+param - имя параметра
+
+Ответ (успех):
+op - "GetUserParam"
+requestId - id запроса
+status - 200
+login
+param
+time_ms
+value
+device_key
+signature
+
+Ответ (не найдено):
+op - "GetUserParam"
+requestId
+status - 404
+
+Ответ (ошибка):
+op
+requestId
+status
+code
+message
+
+----- ListUserParams
+Возвращает все сохранённые параметры пользователя.
+
+Запрос:
+op - "ListUserParams"
+requestId
+login
+
+Ответ (успех):
+op
+requestId
+status - 200
+login
+params - массив параметров
+
+Поля params[i]:
+login
+param
+time_ms
+value
+device_key
+signature
+
+Ответ (ошибка):
+op
+requestId
+status
+code
+message
+
+Группа: Тестовые/временные операции
+
+Эта группа предназначена для отладки и первичного наполнения БД.
+
+----- AddUser
+Тестовая регистрация локального пользователя.
+
+Запрос:
+op - "AddUser"
+requestId
+login
+blockchainName
+loginKey
+deviceKey
+bchLimit
+
+Ответ (успех):
+op
+requestId
+status - 200
+
+Ответ (ошибка):
+op
+requestId
+status
+code
+message