286 lines
11 KiB
Markdown
286 lines
11 KiB
Markdown
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 |