Перенести документацию в docs и добавить социальный граф

2026-07-13 12:58:41 +04:00
parent c9cfb394d7
commit af12d7b954
91 changed files with 653 additions and 2 deletions
@@ -0,0 +1,235 @@
+# API для разработчиков: DM, push и сигналы звонков
+
+Документ описывает публичные операции, связанные с личными сообщениями, WebPush и сигналами звонков.
+
+Подробная логика DM и бинарного формата:
+
+- `Dev_Docs/Personal_Messages/Протокол_DM_v1.md`
+- `Dev_Docs/Personal_Messages/Формат_DM_v1.md`
+
+Важно:
+
+- legacy-операция `SendDirectMessage` отключена и не зарегистрирована в публичном API;
+- для DM v1 нужно использовать только `SendMessagePair`, `ReceiveOutcomingMessage`, `ReceiveIncomingMessage`, `DeleteMessage`, `DeleteConversation`.
+
+## 1. `UpsertPushToken`
+
+Требует авторизации.
+
+### Запрос
+
+```json
+{
+  "op": "UpsertPushToken",
+  "requestId": "push-upsert-001",
+  "payload": {
+    "sessionId": "SESSION_ID",
+    "endpoint": "https://push.example/...",
+    "p256dhKey": "BASE64",
+    "authKey": "BASE64",
+    "platform": "web",
+    "userAgent": "Mozilla/5.0 ..."
+  }
+}
+```
+
+### Успешный ответ
+
+```json
+{
+  "op": "UpsertPushToken",
+  "requestId": "push-upsert-001",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "tokenId": "token-1",
+    "updatedAtMs": 1774700000123
+  }
+}
+```
+
+## 2. `SendTestWebPush`
+
+Требует авторизации.
+
+### Запрос
+
+```json
+{
+  "op": "SendTestWebPush",
+  "requestId": "push-test-001",
+  "payload": {
+    "login": "alice",
+    "sessionId": "SESSION_ID",
+    "title": "Test",
+    "text": "Push body"
+  }
+}
+```
+
+## 3. `SendMessagePair` и `ReceiveOutcomingMessage`
+
+`ReceiveOutcomingMessage` — алиас `SendMessagePair`.
+
+### Назначение
+
+Передаёт пару signed DM-блоков:
+
+- `incomingBlobB64` — блок `type=1` или `type=3`
+- `outgoingBlobB64` — блок `type=2` или `type=4`
+
+Все типы в этой паре используют бинарный формат `SHiNE_DM`.
+
+### Запрос
+
+```json
+{
+  "op": "SendMessagePair",
+  "requestId": "dm-pair-001",
+  "payload": {
+    "incomingBlobB64": "BASE64_INCOMING_SIGNED_BLOCK",
+    "outgoingBlobB64": "BASE64_OUTGOING_SIGNED_BLOCK"
+  }
+}
+```
+
+### Успешный ответ
+
+```json
+{
+  "op": "SendMessagePair",
+  "requestId": "dm-pair-001",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "baseKey": "from|to|time|nonce",
+    "incomingKey": "from|to|time|nonce|1",
+    "outgoingKey": "from|to|time|nonce|2",
+    "deliveredWsSessions": 1,
+    "deliveredWebPushSessions": 0
+  }
+}
+```
+
+### Ошибки
+
+- `400 / BAD_FIELDS` — пустой `incomingBlobB64` или `outgoingBlobB64`
+- `400 / BAD_BLOCK_FORMAT` — base64 или бинарный контейнер повреждён
+- `400 / BAD_CRYPTO_METHOD` — неподдерживаемый метод шифрования контейнера `EncryptedBody_v1_0`
+- `404 / USER_NOT_FOUND` — один из логинов не найден даже после попытки lazy-import из Solana PDA
+- `460 / BAD_SIGNATURE` — подпись блока не прошла проверку
+
+## 4. `ReceiveIncomingMessage`
+
+Принимает только один входящий signed DM-блок.
+
+### Назначение
+
+Используется там, где нужно принять только incoming-вариант сообщения.
+
+Принимаемые типы:
+
+- `type=1` — входящая копия сообщения
+- `type=3` — входящий read-receipt
+
+### Запрос
+
+```json
+{
+  "op": "ReceiveIncomingMessage",
+  "requestId": "dm-in-001",
+  "payload": {
+    "incomingBlobB64": "BASE64_INCOMING_SIGNED_BLOCK"
+  }
+}
+```
+
+## 5. `DeleteMessage`
+
+Принимает один signed DM-блок `type=5` или `type=6`.
+
+### Запрос
+
+```json
+{
+  "op": "DeleteMessage",
+  "requestId": "dm-del-001",
+  "payload": {
+    "blobB64": "BASE64_DELETE_BLOCK"
+  }
+}
+```
+
+## 6. `DeleteConversation`
+
+Принимает один signed DM-блок `type=7` или `type=8`.
+
+### Запрос
+
+```json
+{
+  "op": "DeleteConversation",
+  "requestId": "dm-del-all-001",
+  "payload": {
+    "blobB64": "BASE64_DELETE_CONVERSATION_BLOCK"
+  }
+}
+```
+
+## 7. `AckSessionDelivery`
+
+Требует авторизации. Подтверждает доставку в текущую сессию.
+
+### Запрос
+
+```json
+{
+  "op": "AckSessionDelivery",
+  "requestId": "ack-001",
+  "payload": {
+    "messageKey": "from|to|time|nonce|1"
+  }
+}
+```
+
+## 8. Событие `SignedMessageArrived`
+
+Сервер присылает его по WebSocket в активные сессии адресата.
+
+### Payload события
+
+```json
+{
+  "messageKey": "from|to|time|nonce|1",
+  "baseKey": "from|to|time|nonce",
+  "fromLogin": "alice",
+  "toLogin": "bob",
+  "targetLogin": "bob",
+  "messageType": 1,
+  "timeMs": 1774700000123,
+  "nonce": 123456789,
+  "blobB64": "BASE64_SIGNED_BLOCK",
+  "backlog": false
+}
+```
+
+Если это новая ревизия того же письма, `messageKey` остаётся тем же, а `revisionTimeMs` меняется внутри бинарного блока.
+
+Для типов `5/6/7/8` событие тоже приходит в таком же конверте, но логика применения определяется `messageType` и бинарным `blobB64`.
+
+## 9. `CallInviteBroadcast`
+
+Требует авторизации. Шлёт приглашение к звонку в активные сессии `toLogin`.
+
+## 10. `CallSignalToSession`
+
+Требует авторизации. Шлёт сигнал звонка в конкретную сессию.
+
+## 11. Замечания
+
+- все DM-типы `1..8` используют `SHiNE_DM`
+- `GetUser` может lazy-import пользователя из Solana PDA, поэтому именно через него клиент обычно получает `clientKey` адресата для E2EE
+- сервер не расшифровывает DM и не использует ciphertext как preview текста
+- сервер хранит последнюю применённую версию контентного сообщения по правилу `revisionTimeMs`, а при равенстве — по `reencryptedAtMs`
+- если сервер уже знает tombstone удаления переписки и получает старое сообщение до этой границы, он перерассылает известный `DeleteConversation` на `access_servers` обеих сторон
+- HTTP endpoints для DM-файлов сейчас отсутствуют