Document SignalR and session key APIs

Add the experimental session-key API notes and reorganize the SignalR FriendsHub docs under docs/signalr/friendshub. The updates include front matter metadata, corrected caveats about current implementation behavior, and links to the relevant source files for verification.
This commit is contained in:
Artemy
2026-10-03 17:49:22 +07:00
3 changed files with 61 additions and 11 deletions
@@ -0,0 +1,33 @@
# Ключи сессий — экспериментальный API
RequireHttps и роль User/Admin обязательны.
| Метод | Маршрут | Назначение |
| ----- | --------------------------------- | ---------------------------------------- |
| POST | /api/session/keys | Привязать публичные ключи текущей сессии |
| GET | /api/session/users/{userId}/keys | Получить ключи друга |
| POST | /api/session/keys/rotate | Пополнить одноразовые ключи |
| GET | /api/session/keys/remaining | { remaining: число } |
| POST | /api/session/keys/{preKeyId}/used | Пометить собственный ключ использованным |
byte\[] в JSON передаются строкой base64. UploadKeysRequest содержит identityKey, signedPreKey, signedPreKeySignature и oneTimePreKeys (массив base64). За запрос допускается максимум 100 одноразовых ключей. Сервис запрещает повторную привязку ключей к сессии и проверяет владельца.
RotateOneTimePreKeysRequest содержит newOneTimePreKeys. В реализации ротация удаляет использованные записи и добавляет новые, не ограничивая общий размер набора.
## Неработающие и небезопасные части
\_oneTimePreKeysRotator не передан в конструктор SessionKeysController: rotate и used падают при обращении к null.
remaining считает все записи, включая IsUsed. Reader выдаёт все OneTimePreKeys и возвращает EF-сущности UserCryptoSession вместо PublicSessionKeysDto. Include(UserSession) может включить внутренние поля, а двусторонние навигации могут привести к циклу сериализации. SignedPreKey не включён явным Include.
Доступ к чужим ключам ограничен дружбой, но Forbid("текст") ошибочно используется как имя authentication scheme. Атомарной выдачи одного неиспользованного prekey потребителю нет: endpoint used относится к текущей сессии владельца.
## Статус E2EE
Это заготовка хранения ключей, не законченный криптографический протокол. Нет доказанной реализации обмена/проверки подписей, одноразового потребления, ratchet и поддержки шифрования на клиенте. Не используйте этот раздел как обещание сквозного шифрования.
***
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
Источник: [Govor.API/Controllers/Authentication/SessionKeysController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/Authentication/SessionKeysController.cs).
@@ -1,12 +1,19 @@
---
description: >-
Description: SignalR hub for managing real-time friend request operations,
including sending, accepting, and rejecting friend requests.
icon: wifi
---
# FriendsHub — заявки
Подключение: /hubs/friends с access token, содержащим userId. Атрибут Authorize у класса отсутствует; HubUserAccessor читает claim и бросает исключение при его отсутствии. Это не следует считать полноценной endpoint-политикой авторизации: её нужно добавить явно.
## Команды
| Команда | Аргумент | Успех |
| --- | --- | --- |
| SendRequest | Guid targetUserId | status 201, result null |
| Команда | Аргумент | Успех |
| ------------- | ----------------- | ----------------------- |
| SendRequest | Guid targetUserId | status 201, result null |
| AcceptRequest | Guid friendshipId | status 200, result null |
| RejectRequest | Guid friendshipId | status 200, result null |
@@ -14,13 +21,13 @@ SendRequest запрещает заявку себе и повтор при Pend
## Все события
| Событие | Кому |
| --- | --- |
| FriendRequestReceived | Адресату новой заявки |
| YourFriendRequestReceived | Отправителю |
| FriendRequestAccepted | Принимающему адресату |
| Событие | Кому |
| ------------------------- | --------------------------- |
| FriendRequestReceived | Адресату новой заявки |
| YourFriendRequestReceived | Отправителю |
| FriendRequestAccepted | Принимающему адресату |
| YourFriendRequestAccepted | Отправителю исходной заявки |
| FriendRequestRejected | Отклоняющему адресату |
| FriendRequestRejected | Отклоняющему адресату |
| YourFriendRequestRejected | Отправителю исходной заявки |
Каждое событие передаёт **FriendshipDto**, не строку Guid:
@@ -37,7 +44,8 @@ Status: Pending=0, Accepted=1, Rejected=2, Blocked=3.
Дружба сохраняется до создания чата/рассылки; сбой может оставить частично завершённый сценарий. На reconnect перечитывайте /api/friends, /requests, /responses и /api/user/private-chats. Клиенту нужны дедупликация и обновление cache по id.
---
***
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; сервер с БД и Firebase в рамках диагностики не запускался.
Источник: [Govor.API/Hubs/FriendsHub.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Hubs/FriendsHub.cs).
@@ -1,3 +1,11 @@
---
description: >-
Description: This sub-documentation provides example Java client code for
interacting with the FriendsHub SignalR hub using the microsoft/signalr
library. It covers connecting to the hub, handling con
icon: java
---
# Клиент SignalR на C# для MAUI
Эта страница заменяет устаревший Java-пример: он принимал FriendshipDto как String и не соответствовал серверу. Ниже минимальный пример подключения C#; это пример интеграции, а не проверенный end-to-end тест.
@@ -52,7 +60,8 @@ baseUrl, jwtProvider, ApplyFriendship, ShowError и targetUserId предост
В текущем Govor.Mobile ChatHub фильтрует ReceiveMessage по непустому encryptedContent, поэтому сообщение только с вложением может игнорироваться. Closed пытается перезапуститься даже после намеренного DisconnectAsync. JwtProviderService очищает токены при любом неуспешном HTTP-refresh, включая временную ошибку сервера: это следует исправить отдельно.
---
***
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; сервер с БД и Firebase в рамках диагностики не запускался.
Источник: [Govor.API/Hubs/FriendsHub.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Hubs/FriendsHub.cs).