11 KiB
JSON WebSocket протокол сервера: список существующих запросов (op)
Общий формат любого запроса (client → server): op - имя операции (строка) requestId - идентификатор запроса для связывания с ответом (строка) payload - объект с параметрами конкретной операции (object)
Общий формат любого ответа (server → client): op - имя операции (строка, совпадает с запросом) requestId - идентификатор запроса (строка, совпадает с запросом) status - статус результата (200 = успех, другое = ошибка) payload - объект с полями ответа (object; при ошибке содержит code/message)
Группа: Авторизация и сессии
Эта группа управляет входом пользователя, созданием/обновлением сессий и безопасным завершением активных подключений.
----- AuthChallenge Одноразовый шаг 1: по логину выдаёт nonce (authNonce), который затем подписывается на шаге 2.
Запрос: op - "AuthChallenge" requestId - id запроса login - логин пользователя, для которого начинается авторизация
Ответ (успех): op - "AuthChallenge" requestId - id запроса status - 200 если успех authNonce - одноразовый nonce, Base64Url(32 bytes) без padding
Ответ (ошибка): op - "AuthChallenge" requestId - id запроса status - код ошибки code - строковый код ошибки message - человекочитаемое описание ошибки
----- CreateAuthSession Шаг 2: проверяет подпись владения ключом, создаёт новую active_session и возвращает sessionId/sessionPwd.
Запрос: 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 solanaKey deviceKey bchLimit
Ответ (успех): op requestId status - 200
Ответ (ошибка): op requestId status code message