SHA256
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
|
|
loginKey
|
|
deviceKey
|
|
bchLimit
|
|
|
|
Ответ (успех):
|
|
op
|
|
requestId
|
|
status - 200
|
|
|
|
Ответ (ошибка):
|
|
op
|
|
requestId
|
|
status
|
|
code
|
|
message |