SHA256
Добавить SendSignal и remote AddBlock через homeserver
This commit is contained in:
AidarKC
@@ -2,12 +2,13 @@
|
||||
|
||||
Этот файл описывает технические WebSocket-запросы, которые нужны для служебной работы клиента с сервером. Часть операций доступна без авторизации, часть требует успешной авторизованной сессии.
|
||||
|
||||
Сейчас здесь восемь методов:
|
||||
Сейчас здесь девять методов:
|
||||
|
||||
- `Ping` — keep-alive запрос для поддержания живого WebSocket-соединения;
|
||||
- `GetServerInfo` — запрос базовой публичной информации о сервере для выбора узла в децентрализованной сети;
|
||||
- `ListBlockchainHeads` — краткая сводка по всем локальным блокчейнам сервера для межсерверной синхронизации;
|
||||
- `GetSyncUserProfile` — межсерверный профиль пользователя для создания локальной цепочки без Solana RPC;
|
||||
- `SendSignal` — общий межсессионный технический сигнал в одну конкретную сессию или сразу во все активные сессии пользователя;
|
||||
- `GetCallIceConfig` — выдача STUN/TURN конфигурации для звонков;
|
||||
- `ClientErrorLog` — отправка клиентской ошибки в серверный лог;
|
||||
- `ClientDebugLog` — отправка клиентского debug-события в серверный буфер;
|
||||
@@ -19,6 +20,7 @@
|
||||
- `GetServerInfo` нужен до авторизации и до работы с данными, чтобы клиент понял, что сервер доступен, и показал пользователю краткую карточку этого узла.
|
||||
- `ListBlockchainHeads` нужен для сервер-сервер сверки: партнёр получает список heads по всем цепочкам, сравнивает его со своим состоянием и затем добирает недостающие блоки по диапазону.
|
||||
- `GetSyncUserProfile` нужен для server-to-server режима, когда принимающий сервер хочет создать у себя локальные `solana_users + blockchain_state` без прямого обращения в Solana. Это используется как временный обход ограничений внешнего Solana RPC.
|
||||
- `SendSignal` нужен для доверенных межсессионных команд одного пользователя. Первое практическое применение — `remote AddBlock via homeserver session`, но формат задуман как общий transport на вырост.
|
||||
|
||||
Ниже сначала описаны назначение методов, затем точные форматы запросов и ответов.
|
||||
|
||||
@@ -282,7 +284,134 @@
|
||||
|
||||
---
|
||||
|
||||
## 5. `GetCallIceConfig`
|
||||
## 5. `SendSignal`
|
||||
|
||||
Доступно только после успешной авторизации.
|
||||
|
||||
### Назначение
|
||||
|
||||
Общий межсессионный технический сигнал.
|
||||
|
||||
Этот метод нужен для случаев, когда одна активная сессия пользователя должна быстро передать служебную команду другой сессии того же пользователя или сразу всем его активным сессиям.
|
||||
|
||||
Первый целевой сценарий:
|
||||
|
||||
- `remote AddBlock via homeserver session`
|
||||
|
||||
То есть телефон без локального `blockchain.key` может:
|
||||
|
||||
- подготовить unsigned preimage блока;
|
||||
- подписать сам `SendSignal` своим `session key`;
|
||||
- дополнительно подписать его `client key`, чтобы homeserver/ESP32 точно видел, что запрос пришёл от доверенного клиента этого же логина;
|
||||
- отправить запрос в выбранную `homeserver`-сессию;
|
||||
- получить от неё ответ после настоящего `AddBlock`.
|
||||
|
||||
### Режимы доставки
|
||||
|
||||
- `targetMode = "single_session"` — доставка в одну конкретную `targetSessionId`.
|
||||
- `targetMode = "all_sessions"` — доставка во все активные сессии указанного логина.
|
||||
|
||||
### Важное правило подписи
|
||||
|
||||
Сам `SendSignal` не подписывает поле `data` отдельной вложенной подписью. Вместо этого сервер проверяет подписи по общему preimage сигнала, в который входит:
|
||||
|
||||
- `fromLogin`
|
||||
- `fromSessionId`
|
||||
- `toLogin`
|
||||
- `targetMode`
|
||||
- `targetSessionId`
|
||||
- `signalType`
|
||||
- `signalRequestId`
|
||||
- `timeMs`
|
||||
- `sha256(data)`
|
||||
|
||||
Поддерживаются две подписи:
|
||||
|
||||
- `sessionSignatureB64` — обязательная подпись текущей авторизованной `session key`;
|
||||
- `clientSignatureB64` — необязательная подпись `client key`.
|
||||
|
||||
Для сценария `remote AddBlock via homeserver` текущая договорённость такая:
|
||||
|
||||
- запрос должен идти только своему же логину;
|
||||
- запрос должен быть подписан и `session key`, и `client key`;
|
||||
- в будущем для отдельных wallet-сценариев `clientSignatureB64` может быть пустой.
|
||||
|
||||
### Запрос в одну сессию
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "SendSignal",
|
||||
"requestId": "ws-req-001",
|
||||
"payload": {
|
||||
"toLogin": "alice",
|
||||
"targetMode": "single_session",
|
||||
"targetSessionId": "sess-hs-001",
|
||||
"signalType": "remote_addblock_request",
|
||||
"signalRequestId": "remote-addblock-001",
|
||||
"data": "{\"operation\":\"remote_addblock_request\",\"login\":\"alice\",\"blockchainName\":\"alice_main\",\"blockNumber\":152,\"prevBlockHash\":\"abc...\",\"blockPreimageB64\":\"...\"}",
|
||||
"timeMs": 1774700000123,
|
||||
"sessionSignatureB64": "BASE64_64",
|
||||
"clientSignatureB64": "BASE64_64"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "SendSignal",
|
||||
"requestId": "ws-req-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"deliveredCount": 1,
|
||||
"deliveredSessionIds": ["sess-hs-001"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Событие на принимающей стороне
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "IncomingSignal",
|
||||
"eventId": "evt-001",
|
||||
"payload": {
|
||||
"fromLogin": "alice",
|
||||
"fromSessionId": "sess-phone-001",
|
||||
"toLogin": "alice",
|
||||
"targetMode": "single_session",
|
||||
"targetSessionId": "sess-hs-001",
|
||||
"signalType": "remote_addblock_request",
|
||||
"signalRequestId": "remote-addblock-001",
|
||||
"data": "{\"operation\":\"remote_addblock_request\",\"login\":\"alice\",\"blockchainName\":\"alice_main\",\"blockNumber\":152,\"prevBlockHash\":\"abc...\",\"blockPreimageB64\":\"...\"}",
|
||||
"timeMs": 1774700000123,
|
||||
"sessionSignatureB64": "BASE64_64",
|
||||
"clientSignatureB64": "BASE64_64",
|
||||
"dataSha256B64": "BASE64_32"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Специфические коды ошибок `SendSignal`
|
||||
|
||||
- `422 / NOT_AUTHENTICATED` — требуется авторизация.
|
||||
- `400 / BAD_FIELDS` — не хватает обязательных полей или нарушено правило `single_session/all_sessions`.
|
||||
- `400 / BAD_TARGET_MODE` — передан неизвестный `targetMode`.
|
||||
- `400 / TIME_SKEW` — `timeMs` отличается от серверного более чем на 30 секунд.
|
||||
- `500 / NO_CLIENT_KEY` — для текущего пользователя не найден `client key`.
|
||||
- `404 / USER_NOT_FOUND` — логин адресата не найден.
|
||||
- `400 / BAD_DATA` — сервер не смог обработать `data`.
|
||||
- `400 / BAD_SESSION_SIGNATURE` — некорректная подпись `session key`.
|
||||
- `400 / BAD_CLIENT_SIGNATURE` — некорректная подпись `client key`.
|
||||
- `404 / SESSION_NOT_FOUND` — при `single_session` целевая сессия не найдена или не онлайн.
|
||||
- `404 / NO_TARGET_SESSIONS` — при `all_sessions` у пользователя сейчас нет активных онлайн-сессий.
|
||||
- `404 / DELIVERY_FAILED` — сервер не смог отправить событие ни в одну из целевых сессий.
|
||||
|
||||
---
|
||||
|
||||
## 6. `GetCallIceConfig`
|
||||
|
||||
Доступно только после успешной авторизации.
|
||||
|
||||
@@ -332,7 +461,7 @@
|
||||
|
||||
---
|
||||
|
||||
## 6. `ClientErrorLog`
|
||||
## 7. `ClientErrorLog`
|
||||
|
||||
### Запрос
|
||||
|
||||
@@ -379,7 +508,7 @@
|
||||
|
||||
---
|
||||
|
||||
## 7. `ClientDebugLog`
|
||||
## 8. `ClientDebugLog`
|
||||
|
||||
### Запрос
|
||||
|
||||
@@ -417,7 +546,7 @@
|
||||
|
||||
---
|
||||
|
||||
## 8. `CallDeliveryReport`
|
||||
## 9. `CallDeliveryReport`
|
||||
|
||||
### Запрос
|
||||
|
||||
@@ -453,29 +582,10 @@
|
||||
|
||||
---
|
||||
|
||||
## 7. Короткое резюме
|
||||
## 10. Короткое резюме
|
||||
|
||||
- `Ping` нужен для keep-alive и проверки, что WebSocket-соединение живо.
|
||||
- `GetServerInfo` нужен для выбора сервера в сети и показа публичной информации об узле.
|
||||
- `SendSignal` нужен для доверенных межсессионных сигналов одного пользователя, включая `remote AddBlock via homeserver session`.
|
||||
- `GetCallIceConfig` нужен для WebRTC-звонков и требует авторизации.
|
||||
- `ClientErrorLog`, `ClientDebugLog`, `CallDeliveryReport` используются для диагностики клиента и звонков.
|
||||
|
||||
|
||||
## 8. Прямое техническое сообщение в конкретную сессию
|
||||
|
||||
На текущий момент в публичном JSON API этого документа **нет отдельного RPC** для отправки произвольного технического сообщения в конкретную сессию пользователя (по `sessionId`).
|
||||
|
||||
Что уже есть в системе:
|
||||
|
||||
- сервер хранит `sessionId` активной сессии;
|
||||
- есть `ListSessions`, чтобы клиент получил список sessionId своего пользователя;
|
||||
- у сервера есть внутренний реестр активных WS-подключений по `sessionId`.
|
||||
|
||||
Чего не хватает для полноценной фичи «direct tech message by sessionId»:
|
||||
|
||||
1. отдельная API-операция (например, `SendSessionTechMessage`);
|
||||
2. правило авторизации (кто имеет право писать в чужую/свою сессию);
|
||||
3. унифицированный формат payload и события доставки;
|
||||
4. коды ошибок (`SESSION_OFFLINE`, `SESSION_NOT_FOUND`, `FORBIDDEN` и т.п.).
|
||||
|
||||
Итог: как инфраструктурная база это почти готово, но нужен отдельный RPC-слой и политика доступа.
|
||||
|
||||
@@ -37,6 +37,7 @@
|
||||
| `GetServerInfo` | `05_Technical_Requests_API.md` | публичная информация о сервере |
|
||||
| `ListBlockchainHeads` | `05_Technical_Requests_API.md` | список heads всех локальных блокчейнов |
|
||||
| `GetSyncUserProfile` | `05_Technical_Requests_API.md` | межсерверный профиль пользователя для синхронизации |
|
||||
| `SendSignal` | `05_Technical_Requests_API.md` | общий межсессионный технический сигнал в одну или все сессии пользователя |
|
||||
| `GetCallIceConfig` | `05_Technical_Requests_API.md` | STUN/TURN конфигурация звонков |
|
||||
| `ClientErrorLog` | `05_Technical_Requests_API.md` | логирование клиентской ошибки |
|
||||
| `ClientDebugLog` | `05_Technical_Requests_API.md` | клиентский debug-лог |
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
# Remote AddBlock через homeserver
|
||||
|
||||
- Статус: `pending`
|
||||
- Дата: `2026-06-28 13:30`
|
||||
|
||||
## Что сделано
|
||||
|
||||
Добавлен общий серверный API `SendSignal` и первый сценарий его использования:
|
||||
|
||||
- клиент без локального `blockchain.key` выбирает `homeserver`-сессию (`sessionType = 100`);
|
||||
- клиент отправляет в неё `remote_addblock_request` через `SendSignal`;
|
||||
- запрос подписывается `session key` и `client key`;
|
||||
- ESP32/homeserver автоматически подписывает настоящий `AddBlock` своим `blockchain key` и сам отправляет его на сервер;
|
||||
- результат возвращается назад сигналом `remote_addblock_result`.
|
||||
|
||||
## Что проверить вручную
|
||||
|
||||
1. На клиенте без локального `blockchain.key` открыть настройки и выбрать активную `homeserver`-сессию для remote AddBlock.
|
||||
2. Выполнить любое действие UI, которое приводит к `AddBlock`.
|
||||
3. Убедиться, что клиент не падает в ошибку отсутствия `blockchain.key`, а отправляет `SendSignal`.
|
||||
4. Убедиться, что ESP32/homeserver получает `IncomingSignal` с `remote_addblock_request`.
|
||||
5. Убедиться, что homeserver отправляет обычный `AddBlock` на сервер.
|
||||
6. Убедиться, что клиент получает `remote_addblock_result` и завершает исходную операцию как успешную.
|
||||
7. Проверить негативный сценарий:
|
||||
- homeserver-сессия не выбрана;
|
||||
- homeserver офлайн;
|
||||
- homeserver возвращает ошибку `AddBlock`.
|
||||
|
||||
## Ожидаемый результат
|
||||
|
||||
- При наличии локального `blockchain.key` клиент продолжает работать по старому локальному пути.
|
||||
- При отсутствии локального `blockchain.key` и выбранной `homeserver`-сессии `AddBlock` проходит через удалённую подпись и удалённую отправку.
|
||||
- В ошибочных сценариях пользователь получает понятную ошибку без скрытого fallback.
|
||||
@@ -1,6 +1,6 @@
|
||||
# ESP Pairing и режимы подключения
|
||||
|
||||
Этот документ фиксирует текущие и новые режимы входа/подключения в SHiNE без клиентской UI-реализации. Он нужен как отдельная точка входа по сценариям подключения, чтобы не смешивать обычную авторизацию и серверный pairing через доверенное уже авторизованное устройство пользователя.
|
||||
Этот документ фиксирует актуальные режимы входа/подключения в SHiNE. Он нужен как отдельная точка входа по сценариям подключения, чтобы не смешивать обычную авторизацию и серверный pairing через доверенное уже авторизованное устройство пользователя.
|
||||
|
||||
## 1. Текущие режимы
|
||||
|
||||
@@ -30,7 +30,7 @@
|
||||
- соединение снова входит в существующую сессию;
|
||||
- этот поток тоже остаётся без изменений.
|
||||
|
||||
## 2. Новый режим: добавление сессии через доверенное устройство пользователя
|
||||
## 2. Добавление сессии через доверенное устройство пользователя
|
||||
|
||||
Новый поток не заменяет обычный логин, а живёт рядом с ним.
|
||||
|
||||
@@ -41,7 +41,7 @@
|
||||
- реальное доверие даёт любая уже онлайн доверенная сессия пользователя;
|
||||
- сервер не выдаёт приватные ключи сам от себя.
|
||||
|
||||
Поток версии `v1`:
|
||||
Текущий поток:
|
||||
|
||||
1. Любая доверенная сессия пользователя создаёт на сервере pairing-настройку:
|
||||
`UpsertEspPairingSettings`
|
||||
@@ -65,7 +65,7 @@
|
||||
- уведомляет онлайн доверенные сессии событием `IncomingEspPairingRequest`, если такие сессии подключены;
|
||||
- хранит переданный `encryptedPayload` как непрозрачную строку и не анализирует его содержимое.
|
||||
|
||||
## 4. Чего сервер в этой версии не делает
|
||||
## 4. Чего сервер в этом режиме не делает
|
||||
|
||||
- не передаёт приватный `clientKey`;
|
||||
- не расшифровывает `encryptedPayload`;
|
||||
@@ -73,7 +73,7 @@
|
||||
- не делает клиентский UI;
|
||||
- не навязывает конкретную схему `Ed25519 -> X25519` в коде сервера.
|
||||
|
||||
Это намеренно: серверная версия `v1` подготавливает безопасный каркас маршрутизации и состояния, а настоящая E2E-логика упаковки ключей будет жить на клиентах и ESP-устройствах.
|
||||
Это намеренно: сервер остаётся безопасным каркасом маршрутизации и состояния, а E2E-логика упаковки ключей живёт на клиентах и ESP-устройствах.
|
||||
|
||||
## 5. Роли и ограничения
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Формат взаимодействия внешнего кошелька и ESP32
|
||||
|
||||
Этот документ фиксирует первый этап формата взаимодействия между внешним браузерным wallet-расширением SHiNE и устройством `ESP32-S3-Touch-AMOLED-2.16`.
|
||||
Этот документ фиксирует актуальный формат взаимодействия между внешним браузерным wallet-расширением SHiNE и устройством `ESP32-S3-Touch-AMOLED-2.16`.
|
||||
|
||||
Документ описывает:
|
||||
|
||||
@@ -39,13 +39,13 @@ ESP32 возвращает:
|
||||
|
||||
## 2. Транспорт и маршрут
|
||||
|
||||
Первая версия формата использует уже существующую `wallet-session` браузерного расширения.
|
||||
Текущий формат использует уже существующую `wallet-session` браузерного расширения.
|
||||
|
||||
Схема маршрута:
|
||||
|
||||
`browser extension -> SHiNE server -> homeserver session on ESP32 -> SHiNE server -> browser extension`
|
||||
|
||||
В первой версии:
|
||||
В текущем формате:
|
||||
|
||||
- отдельная цифровая подпись payload не добавляется;
|
||||
- отдельное E2E-шифрование для wallet RPC не добавляется;
|
||||
@@ -90,7 +90,7 @@ ESP32 возвращает:
|
||||
- `customName`;
|
||||
- `targetSessionName`.
|
||||
|
||||
Они намеренно не входят в первую версию этого запроса.
|
||||
Они намеренно не входят в текущий формат этого запроса.
|
||||
|
||||
## 4. Формат ответа
|
||||
|
||||
@@ -121,9 +121,9 @@ ESP32 возвращает:
|
||||
- `wallet.publicKeyBase58` — публичный ключ активного кошелька в `Base58`.
|
||||
- `timeMs` — время формирования ответа на стороне ESP32 в миллисекундах.
|
||||
|
||||
## 6. Ошибки первой версии
|
||||
## 6. Ошибки текущего формата
|
||||
|
||||
Минимальный формат ошибки в первой версии допускается таким:
|
||||
Минимальный формат ошибки допускается таким:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -136,7 +136,7 @@ ESP32 возвращает:
|
||||
}
|
||||
```
|
||||
|
||||
Рекомендуемые коды ошибок первой версии:
|
||||
Рекомендуемые коды ошибок:
|
||||
|
||||
- `wallet_unavailable` — на устройстве нельзя получить текущий кошелёк;
|
||||
- `secret_not_configured` — на устройстве ещё нет корректно сохранённого секрета;
|
||||
@@ -158,7 +158,7 @@ ESP32 возвращает:
|
||||
|
||||
- если `wallet.type = client.key`, то `publicKeyBase58` должен совпасть с `clientKey`, прочитанным из PDA;
|
||||
- если `wallet.type = root.key`, то `publicKeyBase58` должен совпасть с `rootKey`, прочитанным из PDA;
|
||||
- если `wallet.type = custom`, такой проверки по PDA в первой версии нет.
|
||||
- если `wallet.type = custom`, такой проверки по PDA пока нет.
|
||||
|
||||
При несовпадении для `client.key` или `root.key` расширение должно показать пользователю предупреждение, что возвращённый ключ не совпал с ожидаемым ключом из PDA.
|
||||
|
||||
@@ -308,4 +308,4 @@ ESP32:
|
||||
- выбор типа кошелька делается только на самом ESP32;
|
||||
- отдельная цифровая подпись ответа пока не используется;
|
||||
- отдельное E2E-шифрование wallet RPC пока не используется;
|
||||
- `custom`-кошельки в первой версии не сверяются с PDA.
|
||||
- `custom`-кошельки пока не сверяются с PDA.
|
||||
|
||||
Reference in New Issue
Block a user