mirror of
https://github.com/Govor-team/Govor.git
synced 2026-11-18 13:24:59 +00:00
Add forwarding, friend controls, and benefits
Add message forwarding and reply lookup, friend removal and blocking endpoints, and database-backed Govor+ privileges with customizable profile tags. Include migrations, integration tests, and updated API and operations documentation.
This commit is contained in:
@@ -1,10 +1,11 @@
|
||||
# Администрирование сервера
|
||||
|
||||
Серверные административные маршруты требуют роль Admin и активную access-сессию. Администратор сервера и админ группы — разные права: роль в группе не открывает маршруты `/api/admin`.
|
||||
Обычные административные маршруты требуют роль Admin и активную access-сессию. Исключение — InvitationWithKey, проверяющий отдельный runtime-секрет вместо JWT. Администратор сервера и админ группы — разные права: роль в группе не открывает маршруты `/api/admin`.
|
||||
|
||||
| Метод | Маршрут | Назначение |
|
||||
| --- | --- | --- |
|
||||
| POST | `/api/admin/InviteUser/Invitation` | Приглашение регистрации: endDate, maxParticipants, isAdmin, description |
|
||||
| POST | `/api/admin/InviteUser/InvitationWithKey` | Без JWT, с секретом adminKey; первоначальное приглашение |
|
||||
| GET | `/api/admin/InviteUser` | Список приглашений |
|
||||
| GET | `/api/admin/InviteUser/GetAllActiveInvitations` | Активные приглашения |
|
||||
| GET | `/api/admin/InviteUser/{id}` | Приглашение по ID |
|
||||
@@ -15,6 +16,28 @@
|
||||
|
||||
UserResponse не содержит passwordHash. Старый GET смены пароля с паролем в URL удалён. JWT роль Admin формируется по Invitation.IsAdmin пользователя. Настройки обязательного канала и изменения паков реакций дополнительно проверяют это право в БД.
|
||||
|
||||
Паки: [административный API реакций](reactions.md). Обязательный канал, владелец/админы, приглашения и модерация: [группы и каналы](groups.md).
|
||||
Паки: [административный API реакций](reactions.md). Обязательный канал, владелец/админы, приглашения и модерация: [группы и каналы](../groups.md).
|
||||
|
||||
Создание административных приглашений выдаёт возможность зарегистрировать серверного администратора, поэтому этот API предназначен только для доверенных администраторов сервера. Административный FriendshipsController и пустой GroupsHub остаются неиспользуемыми заготовками.
|
||||
|
||||
## Первый администратор и InvitationWithKey
|
||||
|
||||
Оператор задаёт `InvitationAdmin__Key` в runtime и перезапускает API. Метод `POST /api/admin/InviteUser/InvitationWithKey` помечен AllowAnonymous: это альтернативная авторизация по секрету, а не открытая выдача ролей. Он принимает `adminKey`, `endDate`, `maxParticipants`, `isAdmin`, `description`. Без настроенного ключа возвращает 503, с неверным — 401, при успешной генерации — 200 со строкой кода. Для административного приглашения задайте isAdmin=true, небольшой срок и maxParticipants=1.
|
||||
|
||||
```powershell
|
||||
# Секрет задайте отдельно; не сохраняйте его в репозитории.
|
||||
$invitation = @{
|
||||
adminKey = $env:InvitationAdmin__Key
|
||||
endDate = [DateTime]::UtcNow.AddHours(1).ToString("o")
|
||||
maxParticipants = 1
|
||||
isAdmin = $true
|
||||
description = "Initial administrator"
|
||||
} | ConvertTo-Json
|
||||
$code = Invoke-RestMethod -Method Post -Uri "https://YOUR_API/api/admin/InviteUser/InvitationWithKey" -ContentType "application/json" -Body $invitation
|
||||
```
|
||||
|
||||
Зарегистрируйтесь с inviteLink=$code через обычный `/api/auth/register` (SRP-параметры вычисляет клиент). Роль берётся из приглашения. После создания администратора уберите runtime-ключ и перезапустите API, если этот способ больше не нужен. Этот endpoint не использует password-auth rate limiter; ограничьте доступ к нему на инфраструктуре. Никогда не встраивайте adminKey в мобильное приложение.
|
||||
|
||||
## Сброс пароля пользователю
|
||||
|
||||
POST `/api/admin/Users/user/{id}/password` меняет доступ и отзывает сессии/FCM-токены. Сброс очищает SRP/парольную копию восстановления, но сохраняет основной зашифрованный архив. Администратор не получает ключи истории. Пользователь после входа задаёт новый пароль и восстанавливает архив резервным кодом либо с доверенного устройства. [Полный сценарий](../password-recovery.md).
|
||||
|
||||
@@ -2,25 +2,26 @@
|
||||
|
||||
## Последовательность
|
||||
|
||||
1. `POST /api/auth/register` либо `POST /api/auth/login` возвращает `{ refreshToken, accessToken }`.
|
||||
2. HTTP-запросы передают `Authorization: Bearer <accessToken>`.
|
||||
3. Для SignalR задайте AccessTokenProvider, который возвращает актуальный access token. Program.cs также принимает query `access_token` на путях /hubs.
|
||||
4. `POST /api/auth/token/refresh` возвращает новую пару; клиент сохраняет новый refresh token.
|
||||
5. Отзыв сессий выполняется методами /api/Session/close.
|
||||
1. Новый клиент регистрирует SRP-параметры через `POST /api/auth/register`. Для входа использует `POST /api/auth/password/challenge`, затем `/password/login` с доказательством.
|
||||
2. Проверяет серверное доказательство и сохраняет пару access/refresh. Точный формат — [регистрация и вход](authcontroller.md).
|
||||
3. HTTP передаёт `Authorization: Bearer <accessToken>`. Для SignalR задаётся `AccessTokenProvider`; query `access_token` принимается только на путях `/hubs`.
|
||||
4. [Refresh](refreshcontroller.md) последовательно заменяет оба токена. [Сессии](../sessioncontroller.md) позволяют отозвать отдельное устройство или все сеансы.
|
||||
5. [Восстановление](../../password-recovery.md) открывает зашифрованный архив истории. Успешный вход и наличие ключей старой истории — разные состояния.
|
||||
|
||||
Access token содержит `userId`, `sid` и роль User/Admin. Подпись HS256 проверяется, срок проверяется, issuer и audience не проверяются. Токены возвращаются JSON; сервер не устанавливает HttpOnly-cookie.
|
||||
## Токены и отзыв
|
||||
|
||||
## Ограничения реализации
|
||||
Access JWT содержит `userId`, `sid`, `tokenType: access` и роль `User`/`Admin`. Подпись HS256 и срок проверяются; issuer/audience не проверяются. JSON-ответы не устанавливают HttpOnly-cookie. Значения по умолчанию: access 10 минут, refresh-сессия 30 дней.
|
||||
|
||||
Отзыв сессии блокирует refresh, но Program.cs не проверяет IsRevoked при каждом использовании access token. Уже открытые SignalR-соединения явно не разрываются. Немедленный logout на всех устройствах не гарантирован.
|
||||
Bearer middleware проверяет по БД владельца `sid`, срок и отсутствие отзыва. Refresh JWT не принимается как access. SignalR-фильтр заново проверяет сессию при каждой команде и прерывает соединение при отказе. Отзыв не следует трактовать как гарантированное мгновенное физическое закрытие всех соединений: у разных хабов разная маршрутизация событий. ChatsHub направляет события активным сессиям.
|
||||
|
||||
Refresh JWT содержит userId и tokenType, но не случайный jti или sid. При выпуске одному пользователю в одну секунду возможны одинаковые токены, конфликтующие с уникальным RefreshTokenHash. Ротация не защищена атомарным compare-and-swap от параллельных запросов.
|
||||
Refresh содержит случайный `jti`; замена хеша выполняется условным атомарным обновлением. Из двух конкурирующих запросов со старым refresh только один может заменить хеш. Это не долговременный журнал replay и не отзыв всей семьи токенов.
|
||||
|
||||
Не используйте refresh token как access token. В bearer-валидации нет явного требования tokenType=access; методы с одним Authorize требуют исправления разделения типов токенов.
|
||||
## Старые аккаунты
|
||||
|
||||
На MAUI рекомендовано хранить refresh token в SecureStorage и выполнять обновление последовательно. Это рекомендация клиенту, а не свойство сервера.
|
||||
`POST /api/auth/login` с открытым паролем оставлен для bcrypt-аккаунтов. После настройки SRP он возвращает `401 Auth.PasswordProofRequired`. Новый клиент не должен автоматически откатываться на старый вход; [процедура перехода](../../password-recovery.md) требует явной смены пароля.
|
||||
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
## Ограничения и хранение
|
||||
|
||||
Источник: [Govor.Application/Authentication/JWT/JwtService.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.Application/Authentication/JWT/JwtService.cs).
|
||||
Регистрация, старый login, SRP challenge/login и challenge/authorize действий имеют общий лимит `30 запросов/минуту` на `RemoteIpAddress`, без очереди; превышение — `429`. Challenge одноразовый и действует две минуты. Хранилище challenge находится в памяти процесса, поэтому несколько инстансов требуют отдельной схемы маршрутизации/общего хранилища.
|
||||
|
||||
На клиенте храните секреты в защищённом хранилище, сериализуйте refresh и сохраняйте новую пару до следующего запроса. Временная сеть/`5xx` не означает необходимость стирать ключи истории. На внешней сети обязателен HTTPS; [параметры proxy](../../configuration.md).
|
||||
|
||||
@@ -1,45 +1,61 @@
|
||||
# Регистрация и вход
|
||||
|
||||
Оба метода доступны анонимно, Content-Type: application/json.
|
||||
`Content-Type: application/json`. Регистрация и методы входа анонимные, но ограничены политикой `password-auth`. Смена пароля, миграция и восстановление описаны в [отдельном руководстве](../../password-recovery.md).
|
||||
|
||||
## POST /api/auth/register
|
||||
|
||||
Для нового клиента передайте `name`, `inviteLink`, `deviceInfo` и **все три** поля `srpSalt`, `srpIdentity`, `srpVerifier`, без `password`. Параметры вычисляются клиентом по `PasswordProtocol`: SRP-6a, группа 4096 бит, SHA-512; сериализация должна точно соответствовать реализации. Не подставляйте произвольные Base64-строки вместо verifier.
|
||||
|
||||
Совместимый старый формат принимает `password` (минимум 8 символов) без SRP-полей. Смешанный или неполный SRP-запрос отклоняется. Новая интеграция должна реализовывать доказательство пароля, а не строиться на старом формате.
|
||||
|
||||
Имя: 4–44 символа, кириллица и цифры, начинается с буквы. Модерация проверяет зарезервированные имена, запрещённые совпадения/подстроки и пять одинаковых символов подряд. `deviceInfo` описывает устройство, в БД до 256 символов.
|
||||
|
||||
`inviteLink` — код приглашения, не URL. Генератор использует GUID в формате `N` (32 символа без дефисов). При регистрации проверяются активность, срок и лимит приглашения. Резервирование места, аккаунт, административная роль и членство в обязательном канале сохраняются транзакционно.
|
||||
|
||||
Успех `200`:
|
||||
|
||||
```json
|
||||
{"refreshToken":"<refresh>","accessToken":"<access>"}
|
||||
```
|
||||
|
||||
Открытие сессии выполняется после регистрации. Если оно не удалось, аккаунт уже мог быть создан: сначала попробуйте вход, не повторяйте регистрацию бесконечно. Конфликт имени — `409`, отсутствующее приглашение — `404`, ошибка валидации/недоступное приглашение — `400`. Ошибки сервиса используют [ProblemDetails](../../code-docs/hubresult-less-than-t-greater-than.md).
|
||||
|
||||
## Контракт SRP-обмена
|
||||
|
||||
| Шаг | JSON-поля запроса | Поля успешного ответа |
|
||||
| --- | --- | --- |
|
||||
| `password/challenge` | name, publicEphemeral, deviceInfo | challengeId, salt, identity, publicEphemeral, credentialVersion, legacy |
|
||||
| `password/login` | challengeId, proof | refreshToken, accessToken, serverProof, credentialVersion |
|
||||
|
||||
publicEphemeral/proof создаёт SRP-библиотека с параметрами PasswordProtocol. salt/identity/verifier регистрации создаются PasswordProtocol.Create на стороне клиента; salt и identity — случайные значения в hex. `legacy=true` требует явного сценария перехода старого аккаунта, не автоматической отправки открытого пароля.
|
||||
|
||||
Пример формы новой регистрации (значения SRP нужно вычислить):
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Артём",
|
||||
"password": "example-password",
|
||||
"srpSalt": "<salt из PasswordProtocol.Create>",
|
||||
"srpIdentity": "<identity из PasswordProtocol.Create>",
|
||||
"srpVerifier": "<verifier из PasswordProtocol.Create>",
|
||||
"inviteLink": "<код приглашения>",
|
||||
"deviceInfo": "Android test device"
|
||||
}
|
||||
```
|
||||
|
||||
Имя: 4–44 символа, только кириллица и цифры, первый символ — буква. Модерация запрещает зарезервированные имена, совпадения/подстроки из конфигурации и пять одинаковых символов подряд. Пароль: минимум 8 символов. DeviceInfo необязателен в запросе, но в БД ограничен 256 символами.
|
||||
## Вход SRP
|
||||
|
||||
Код создаётся как Guid.ToString("N"): 32 символа без дефисов. Поиск кода — по строковому равенству. InviteLink — код, а не URL.
|
||||
1. `POST /api/auth/password/challenge` начинает обмен и возвращает серверные параметры/challenge.
|
||||
2. Клиент вычисляет доказательство и отправляет `POST /api/auth/password/login`.
|
||||
3. Ответ содержит токены и серверное доказательство. Клиент проверяет доказательство до принятия результата.
|
||||
|
||||
Проверяется существование приглашения, срок и число участников. Проверка IsActive отсутствует, лимит участников не защищён от конкурентной регистрации.
|
||||
Challenge действует две минуты и расходуется один раз. Неверное/истёкшее доказательство — `401`, некорректные протокольные данные — `400`, конфликт состояния — `409`, превышение лимита — `429`. Для повторной попытки начните новый обмен.
|
||||
|
||||
Успех 200:
|
||||
Точные DTO, правила кодирования и криптографические операции заданы в [PasswordProtocol.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.Application/Authentication/PasswordProtocol.cs) и [PasswordAccountService.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.Application/Authentication/PasswordAccountService.cs). Их следует переносить согласованно с клиентом, не реализовывать обмен по одному схематическому JSON-примеру.
|
||||
|
||||
```json
|
||||
{"refreshToken":"<token>","accessToken":"<token>"}
|
||||
```
|
||||
|
||||
Конфликт имени — 409; ошибки валидации — 400; отсутствующее приглашение — 404. Тело сервисных ошибок — ProblemDetails с errorCode. Регистрация и открытие сессии — отдельные сохранения: ошибка открытия сессии не откатывает созданного пользователя.
|
||||
|
||||
## POST /api/auth/login
|
||||
## POST /api/auth/login — совместимость
|
||||
|
||||
```json
|
||||
{"name":"Артём","password":"example-password","deviceInfo":"Android test device"}
|
||||
```
|
||||
|
||||
Успех 200 с той же парой токенов. Пользователь не найден — 404 (UserNotRegisteredException); неверный пароль — 400 (InvalidOperationException). Это текущее поведение, а не рекомендуемая политика ошибок входа: разные ответы раскрывают существование аккаунта.
|
||||
|
||||
## Ограничения
|
||||
|
||||
Rate limiting и блокировка перебора в Program.cs не настроены. Для публичного запуска нужны единая ошибка входа, ограничение частоты и защита административных приглашений.
|
||||
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
Источник: [Govor.API/Controllers/Authentication/AuthController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/Authentication/AuthController.cs).
|
||||
Для bcrypt-аккаунта успех — та же пара токенов. Неизвестное имя — `404`, неверный пароль — `400`, SRP-аккаунт — `401 Auth.PasswordProofRequired`. Различающиеся ответы старого входа позволяют определить существование имени; не переносите это поведение в пользовательские тексты ошибок.
|
||||
|
||||
@@ -8,29 +8,24 @@
|
||||
{"refreshToken":"<последний сохранённый refresh token>"}
|
||||
```
|
||||
|
||||
Сервис хеширует переданную строку и ищет UserSession по RefreshTokenHash. Проверяет IsRevoked и ExpiresAt, выпускает новую пару, заменяет хеш и продлевает ExpiresAt. CreatedAt также перезаписывается, поэтому после refresh это не исходная дата открытия сессии.
|
||||
Сервис ищет сессию по хешу строки, проверяет отзыв и срок, создаёт новую пару и условно заменяет хеш только если старый ещё актуален. `ExpiresAt` продлевается, `CreatedAt` сохраняет исходную дату открытия сессии.
|
||||
|
||||
Успех 200:
|
||||
Успех `200`:
|
||||
|
||||
```json
|
||||
{"refreshToken":"<new token>","accessToken":"<new token>"}
|
||||
{"refreshToken":"<new refresh>","accessToken":"<new access>"}
|
||||
```
|
||||
|
||||
| Случай | Текущий ответ |
|
||||
| Случай | Ответ |
|
||||
| --- | --- |
|
||||
| Пустая строка | 400, errorCode Auth.EmptyToken |
|
||||
| Хеш не найден | 400, errorCode Auth.InvalidToken |
|
||||
| Истекшая/отозванная сессия | 400, errorCode Auth.InvalidToken |
|
||||
| Пустая строка | 400, `Auth.EmptyToken` |
|
||||
| Неизвестный, истёкший или отозванный refresh | 400, `Auth.InvalidToken` |
|
||||
| Сессия изменилась между чтением и условной заменой | 401, `Auth.InvalidToken` |
|
||||
|
||||
Не документируйте неверный refresh как гарантированный 401: текущий Error.Failure преобразуется в 400.
|
||||
Повтор старого токена после успешной ротации не является штатным способом повторить запрос. Различие 400/401 зависит от момента обнаружения конфликта; не привязывайте восстановление клиента только к одному из статусов.
|
||||
|
||||
## Клиент
|
||||
## Поведение клиента
|
||||
|
||||
Сохраните оба новых токена и сериализуйте refresh-запросы. Ошибка сети не должна автоматически удалять авторизацию пользователя. При подтверждённо недействительном refresh требуется повторный вход.
|
||||
Выполняйте один refresh за раз для всех параллельных HTTP-запросов и хабов. Сохраняйте оба новых токена вместе. Если ответ потерялся после серверного сохранения, старая строка уже может быть недействительна и потребуется новый вход.
|
||||
|
||||
Ротация сейчас не имеет защиты от конкурентного использования и истории повторного применения. Детали — в разделе «Аутентификация».
|
||||
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
Источник: [Govor.Application/Users/UserSessions/UserSessionRefresher.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.Application/Users/UserSessions/UserSessionRefresher.cs).
|
||||
Сетевой сбой или `5xx` не подтверждает недействительность токена. Повторный вход не должен удалять приватные ключи истории. [Пароль и восстановление](../../password-recovery.md).
|
||||
|
||||
@@ -1,33 +1,3 @@
|
||||
# Ключи сессий — экспериментальный API
|
||||
# Старый API prekeys
|
||||
|
||||
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).
|
||||
Актуальное описание: [совместимый API prekeys](../session-keys.md). Для нового клиента используйте [E2EE API](../e2ee.md).
|
||||
|
||||
@@ -26,19 +26,18 @@ Query: StartMessageId (Guid?, необязателен), Before=20, After=2. Bef
|
||||
"replyToMessageId":null,
|
||||
"mediaAttachments":[],
|
||||
"reactions":[],
|
||||
"reactionsVersion":0,
|
||||
"messageViews":[]
|
||||
}]
|
||||
```
|
||||
|
||||
У HTTP-ответа поле id; у SignalR UserMessageResponse — messageId. Вложения HTTP имеют id, messageId, mediaFileId.
|
||||
|
||||
## Известные проблемы
|
||||
## Доступ и пагинация
|
||||
|
||||
Личный загрузчик принимает currentUser, но не проверяет участие в указанном чате. Это критичная ошибка доступа. Для группы участие проверяется; неучастнику возвращается [].
|
||||
Оба загрузчика проверяют доступ к конкретному чату: неучастник/заблокированный участник получает 403. Реакции, прочтения и вложения загружаются явно. Порядок стабилен по паре (SentAt, Id), включая одинаковое время отправки.
|
||||
|
||||
Пагинация сравнивает только SentAt: сообщения с одинаковой датой могут выпадать вокруг якоря. Reactions и MessageViews не включаются явным Include, поэтому эти массивы не являются надёжным источником состояния. Нужны проверки доступа и стабильный курсор (SentAt, Id).
|
||||
Якорь включается в результат; при объединении страниц удаляйте дубли по id. Пустой массив может означать пустую историю или неизвестный якорь. encryptedContent возвращается как сохранённый конверт и расшифровывается клиентом.
|
||||
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
Источник: [Govor.Application/Messages/MessagesLoader.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.Application/Messages/MessagesLoader.cs).
|
||||
Источник: [Govor.Application/Messages/MessagesLoader.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.Application/Messages/MessagesLoader.cs).
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
# Устройства, ключи и архивы — HTTP API
|
||||
|
||||
Все маршруты `/api/e2ee` требуют access token, роль User/Admin и активную сессию. `type`: `0` — PrivateChat, `1` — ChatGroup. Приватные ключи устройства, пароль и резервный код серверу не передаются. [Модель доверия и жизненный цикл](../e2ee.md).
|
||||
|
||||
## Маршруты
|
||||
|
||||
| Метод | Маршрут | Результат |
|
||||
| --- | --- | --- |
|
||||
| PUT | `/api/e2ee/device` | Регистрация/ротация ключа текущей сессии; `{ registered: true }` |
|
||||
| GET | `/api/e2ee/devices` | Собственные устройства |
|
||||
| PUT | `/api/e2ee/devices/certificate` | Сертификация исторического устройства; `{ certified: true }` |
|
||||
| GET | `/api/e2ee/conversations/{type}/{conversationId}/keys` | `ConversationKeys` для доступного чата |
|
||||
| GET | `/api/e2ee/conversations/{type}/{conversationId}/signers/{deviceSession}?identityKey=...` | Исторический подписант; `404`, если не найден |
|
||||
| GET | `/api/e2ee/recovery` | `RecoveryState`: `{ vault: ... }`, без архива `vault: null` |
|
||||
| PUT | `/api/e2ee/recovery` | Сохранение подписанного архива с ожидаемой ревизией |
|
||||
| GET | `/api/e2ee/identities/{userId}/changes` | Журнал явной смены корневого ключа |
|
||||
|
||||
## Контракты
|
||||
|
||||
`DeviceKey`: `userId`, `sessionId`, `identityKey`, `encryptionKey`, `signature`, `accountIdentityKey`, `accountSignature`, `generation`, `previousFingerprint`. `fingerprint` вычисляется из публичных ключей. Идентификаторы обязаны совпасть с владельцем JWT и текущей сессией.
|
||||
|
||||
`ConversationKeys`: `conversationId`, `recipientType`, `members` (ID пользователей), `devices` (DeviceKey). Не путайте список участников с устройствами: у одного пользователя может быть несколько устройств. Лимит — 500 устройств на чат. Истёкшая, но не отозванная сертифицированная сессия может оставаться получателем офлайн-сообщений; для авторизации команд срок сессии всё равно проверяется.
|
||||
|
||||
`SaveRecoveryVault`: `expectedRevision`, `identityKey`, `ciphertext`, `signature`. `RecoveryVault`: `userId`, `revision`, `identityKey`, `ciphertext`, `signature`. Предел ciphertext архива — 4 000 000 символов, HTTP-запроса сохранения — 4 100 000 байт.
|
||||
|
||||
При конфликте ревизии перечитайте архив, расшифруйте и объедините ключи локально, затем подпишите следующую версию. Простая замена expectedRevision без объединения может потерять историю другого устройства.
|
||||
|
||||
## Ошибки и повторы
|
||||
|
||||
- `400`: неверный тип/контекст, ключи, подпись или данные архива.
|
||||
- `403`: нет доступа к чату, чужая сессия/устройство или неподходящий ключ аккаунта.
|
||||
- `404`: не найден исторический подписант.
|
||||
- `409`: изменилось поколение/ревизия либо не у всех участников есть подходящие ключи.
|
||||
|
||||
Перед отправкой получите каталог устройств, зашифруйте сообщение всем получателям и подпишите. При `E2EE_DEVICES_CHANGED` перечитайте каталог и создайте согласованный конверт; не переходите на plaintext. Для личных и приватных чатов сервер требует E2EE; публичные группы допускают старый формат, хотя актуальный клиент шифрует и их.
|
||||
|
||||
Точный формат JOSE, подписи и кодирование заданы в [E2eeProtocol.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.Application/E2ee/E2eeProtocol.cs) и [E2eeRecoveryProtocol.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.Application/E2ee/E2eeRecoveryProtocol.cs). HTTP camelCase не означает, что можно переименовывать поля внутри подписанного JOSE-содержимого.
|
||||
@@ -24,7 +24,5 @@ Bearer token обязателен; отдельная роль в атрибут
|
||||
|
||||
Статус isOnline зависит от состояния процесса и подключения к presence. Он не является гарантией доставки сообщений или фоновой доступности устройства.
|
||||
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
Источник: [Govor.API/Controllers/Friends/FriendshipController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/Friends/FriendshipController.cs).
|
||||
Источник: [Govor.API/Controllers/Friends/FriendshipController.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/Friends/FriendshipController.cs).
|
||||
|
||||
@@ -20,7 +20,5 @@ FriendshipStatus сериализуется числом: Pending=0, Accepted=1,
|
||||
|
||||
При отсутствии записей — пустой массив. Ошибки контроллера — 500 с {"error":"Internal server error."}. Для восстановления после reconnect перечитайте списки: события не являются журналом гарантированной доставки.
|
||||
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
Источник: [Govor.API/Controllers/Friends/FriendsRequestQueryController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/Friends/FriendsRequestQueryController.cs).
|
||||
Источник: [Govor.API/Controllers/Friends/FriendsRequestQueryController.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/Friends/FriendsRequestQueryController.cs).
|
||||
|
||||
+1
-154
@@ -1,156 +1,3 @@
|
||||
# Группы и каналы
|
||||
|
||||
Рабочий серверный API от 04.10.2026. Все маршруты требуют access token и активную сессию. Группа — чат с публикацией для всех активных участников; канал — группа с IsChannel=true, где публиковать и редактировать свои публикации могут только владелец и админы. Тип сообщества задаётся при создании и не меняется через профиль.
|
||||
|
||||
Публичные сообщества доступны поиску Govor и вступлению по ID. Приватные сообщества не появляются в поиске: вступление выполняется по действующей ссылке. История, участники, закрытые аватары и команды сообщений доступны только незаблокированным участникам, даже если само сообщество публично.
|
||||
|
||||
## Создание, поиск и профиль
|
||||
|
||||
| Метод | Маршрут | Тело / результат |
|
||||
| --- | --- | --- |
|
||||
| POST | `/api/groups` | name, description, isPrivate, isChannel; GroupResponse |
|
||||
| GET | `/api/groups/search?q=...&skip=0&take=50` | Публичные группы и каналы, поиск по имени/описанию |
|
||||
| GET | `/api/groups/mine?skip=0&take=50` | Сообщества текущего пользователя без банов |
|
||||
| GET | `/api/groups/{groupId}` | Профиль; приватный профиль только участникам |
|
||||
| PUT | `/api/groups/{groupId}` | name, description, isPrivate; только владелец |
|
||||
| POST | `/api/groups/{groupId}/join` | Вступить в публичное сообщество |
|
||||
| DELETE | `/api/groups/{groupId}/members/me` | Выйти; HTTP 204 |
|
||||
| POST | `/api/groups/{groupId}/avatar` | multipart/form-data с file; только владелец |
|
||||
| DELETE | `/api/groups/{groupId}/avatar` | Убрать текущий аватар; только владелец, 204 |
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Новости Govor",
|
||||
"description": "Обновления проекта",
|
||||
"isPrivate": false,
|
||||
"isChannel": true
|
||||
}
|
||||
```
|
||||
|
||||
POST/PUT/Join возвращают 200, остальные успешные команды без DTO — 204. name — 1–100 символов, description — до 500; q — до 100. skip >= 0, take — 1–100. По умолчанию новое сообщество приватное; создатель автоматически становится участником и владельцем.
|
||||
|
||||
GroupResponse: id, name, description, imageId, imageUrl, isPrivate, isChannel, ownerUserId, createdAt, memberCount, myRole, isRequiredChannel, canLeave. myRole: Member=0, Admin=1, Owner=2, null — не участник. memberCount не включает заблокированных. canLeave учитывает владение и запрет выхода из обязательного канала.
|
||||
|
||||
Аватар: статичный PNG/JPEG/WebP, исходный файл до 2 МиБ и сторон до 2048 px; после обработки PNG до 128×128 и 256 КиБ. GIF не принимается. Загрузка возвращает imageId и mediaUrl. Скачать можно через `/api/media/download/{imageId}` с Bearer token. Текущий публичный аватар доступен всем авторизованным незаблокированным пользователям; приватный — только активным участникам. Старые файлы не удаляются автоматически, но не выдаются посторонним как публичный аватар.
|
||||
|
||||
## Роли и модерация
|
||||
|
||||
| Возможность | Владелец | Админ | Участник |
|
||||
| --- | --- | --- | --- |
|
||||
| Читать и реагировать | Да | Да | Да |
|
||||
| Писать в обычную группу | Да | Да | Да |
|
||||
| Публиковать/редактировать свои сообщения канала | Да | Да | Нет |
|
||||
| Менять имя, описание, приватность, аватар | Да | Нет | Нет |
|
||||
| Назначать/снимать админов | Да | Нет | Нет |
|
||||
| Выпускать/отзывать ссылки | Да | Да | Нет |
|
||||
| Банить/разбанивать участников | Да | Да | Нет |
|
||||
| Банить других админов | Да | Нет | Нет |
|
||||
| Удалять сообщения других участников | Да | Да | Нет |
|
||||
| Выбирать реакции канала | Да | Да | Нет |
|
||||
| Передавать владение | Да | Нет | Нет |
|
||||
|
||||
Глобальная роль серверного Admin не заменяет роль в группе. Владельца и самого себя банить нельзя. Назначение админа требует активного участника. Бан админа владельцем снимает его административную роль; после разбана он возвращается как участник. При выходе роль админа снимается.
|
||||
|
||||
| Метод | Маршрут | Назначение |
|
||||
| --- | --- | --- |
|
||||
| GET | `/api/groups/{groupId}/members?bannedOnly=false&skip=0&take=50` | Активные участники; список bannedOnly=true только модераторам |
|
||||
| PUT | `/api/groups/{groupId}/members/{userId}/administrator` | Назначить админа, только владелец |
|
||||
| DELETE | `/api/groups/{groupId}/members/{userId}/administrator` | Снять админа, только владелец |
|
||||
| PUT | `/api/groups/{groupId}/members/{userId}/ban` | Заблокировать |
|
||||
| DELETE | `/api/groups/{groupId}/members/{userId}/ban` | Разблокировать |
|
||||
| DELETE | `/api/groups/{groupId}/messages/{messageId}` | Удалить сообщение для всех; автор либо модератор |
|
||||
| POST | `/api/groups/{groupId}/ownership/{userId}` | Передать владение активному участнику |
|
||||
|
||||
Участник в списке: userId, username, role, isBanned, memberSince. Пароли/токены и сущности User не возвращаются. Удаление сообщения проверяет его принадлежность именно указанной группе и отправляет существующее событие MessageRemoved.
|
||||
|
||||
Бан сохраняет запись участника, поэтому повторное вступление через поиск или другую ссылку его не обходит. Он блокирует историю, чтение, отправку, редактуру, реакции и файлы сообщества. События и push фильтруются по действующим участникам. Разбан возвращает членство; автоматического удаления старых сообщений при бане нет — модератор удаляет их отдельными командами.
|
||||
|
||||
Владелец не может выйти, пока не передаст владение. При передаче прежний владелец становится админом и затем может выйти. Владение всегда у одного пользователя.
|
||||
|
||||
## Приглашение по ссылке
|
||||
|
||||
```http
|
||||
POST /api/groups/{groupId}/invitations
|
||||
Authorization: Bearer <access-token>
|
||||
Content-Type: application/json
|
||||
|
||||
{ "validForDays": 7, "maxParticipants": 100, "description": "Приглашение" }
|
||||
```
|
||||
|
||||
Ответ GroupInvitationResponse содержит id, groupId, invitationCode, sharePath, previewPath, joinPath, description, endDate, maxParticipants, usedCount, isRevoked. sharePath имеет вид `/invite/{code}`; добавьте доверенный API base URL, чтобы передать полную ссылку. Клиент, открывший ссылку, извлекает code, показывает preview и выполняет POST join после действия пользователя. Все запросы используют его access token; ссылка не является токеном авторизации аккаунта.
|
||||
|
||||
| Метод | Маршрут | Назначение |
|
||||
| --- | --- | --- |
|
||||
| GET | `/api/groups/{groupId}/invitations` | До 100 последних ссылок, только модераторы |
|
||||
| DELETE | `/api/groups/{groupId}/invitations/{invitationId}` | Отозвать ссылку, 204 |
|
||||
| GET | `/api/group-invites/{code}` | Превью профиля по действующему коду, без вступления |
|
||||
| POST | `/api/group-invites/{code}/join` | Вступление, GroupResponse |
|
||||
|
||||
Совместимые пути: GET `/invite/{code}` — только превью, POST `/invite/{code}/join` — вступление. Старый побочный эффект вступления через GET устранён: сканеры ссылок и предварительная загрузка не добавляют участников.
|
||||
|
||||
validForDays — 1–365 (по умолчанию 7), maxParticipants — 0–1 000 000; 0 означает без лимита. usedCount — число успешных вступлений по ссылке, а не текущий размер группы. Повтор POST уже вступившего пользователя не расходует лимит; выход не освобождает использованный слот. Просроченная или отозванная ссылка не работает. Отзыв не удаляет ранее вступивших участников.
|
||||
|
||||
## Сообщения и реакции
|
||||
|
||||
Используйте `/hubs/chats`: Send с recipientType=1 и recipientId=groupId. История — GET `/api/groups/{groupId}/messages`; прочтение — [существующий API](message-read.md). Публичность сообщества не даёт доступ к его истории без вступления.
|
||||
|
||||
В канале владелец/админ задаёт политику через PUT `/api/groups/{groupId}/reactions`: All=0, None=1, Selected=2 с reactionIds. GET возвращает текущую политику; изменения приходят как ChannelReactionPolicyChanged. Эмодзи, изображения/GIF, HTTP/SignalR установка реакции описаны в [реакциях](reactions.md). Бан и снятие админа применяются к этим же сервисам.
|
||||
|
||||
## Обновления группы через SignalR
|
||||
|
||||
С 04.10.2026 изменения сообщества приходят через тот же `/hubs/chats`. Нужны Bearer access token и активная сессия. Дополнительная подписка на группу не требуется: сервер доставляет события всем активным сессиям действующих участников, включая другие устройства автора команды. Старый пустой GroupsHub не используется; команды управления остаются HTTP API и подходят будущему боту.
|
||||
|
||||
| Событие | Payload | Когда отправляется |
|
||||
| --- | --- | --- |
|
||||
| GroupProfileChanged | `{ groupId }` | Имя, описание, приватность, загрузка/удаление аватара, передача владения, настройка обязательного канала |
|
||||
| GroupMemberChanged | `{ groupId, userId, status, role }` | Создание группы, вступление через поиск/ссылку, выход, назначение/снятие админа, бан/разбан, передача владения, автоматическое добавление нового аккаунта в обязательный канал |
|
||||
|
||||
status: Active=0, Banned=1, Left=2. role: Member=0, Admin=1, Owner=2; null для заблокированного или вышедшего. Статус/роль читаются из БД после завершения команды. При передаче владения отправляются GroupProfileChanged и два GroupMemberChanged: прежний владелец становится Admin, новый — Owner.
|
||||
|
||||
Заблокированный или вышедший пользователь получает GroupMemberChanged о **себе** на свои активные сессии вместе с оставшимися участниками. После этого ему не направляются изменения профиля, чужого членства и события сообщений. Остальные заблокированные, посторонние пользователи, отозванные и истёкшие сессии исключены. При разбане статус Active с ролью Member; автоматическое вступление при регистрации уведомляет уже подключённых участников обязательного канала.
|
||||
|
||||
GroupProfileChanged — сигнал перечитать GET `/api/groups/{groupId}`. Он не содержит общий GroupResponse: myRole и canLeave зависят от конкретного пользователя. Клиент обновляет имя/описание, аватар, приватность, владельца, свои права и возможность выхода из полученного HTTP ответа. Смена обязательного канала уведомляет участников прежнего и нового канала; смена allowLeave — участников текущего.
|
||||
|
||||
При GroupMemberChanged перечитайте профиль и видимую страницу участников; это обновляет memberCount и myRole. Если событие касается текущего пользователя, пересчитайте доступность кнопок отправки и модерации. Если профиль публичного сообщества вернул myRole=null, членство уже потеряно, даже при HTTP 200. Ответ 403/404 также означает потерю доступа: закройте экран сообщества, уберите его из локального списка и перечитайте `/api/groups/mine`. Обновляйте UI MAUI на главном потоке. Все серверные команды независимо проверяют действующие права в БД.
|
||||
|
||||
Пример регистрации обработчиков в .NET-клиенте (Reload — методы приложения, выполняющие описанные HTTP запросы):
|
||||
|
||||
```csharp
|
||||
hub.On<GroupProfileChangedResponse>("GroupProfileChanged",
|
||||
change => ReloadGroupAsync(change.GroupId));
|
||||
hub.On<GroupMemberChangedResponse>("GroupMemberChanged",
|
||||
change => ReloadGroupAndMembersAsync(change.GroupId));
|
||||
```
|
||||
|
||||
Событие отправляется только после успешного сохранения, отказ в правах/валидации не создаёт события. Повтор успешной идемпотентной команды может повторить уведомление: обработчики должны быть идемпотентными. SignalR не хранит очередь и не гарантирует порядок между параллельными HTTP командами; payload членства — подсказка, актуальный HTTP ответ является источником прав. После reconnect перечитайте mine, открытый профиль и участников. Ошибка доставки логируется, но не отменяет уже сохранённое изменение и не превращает успешную команду в ошибку. Для этих событий push не отправляется.
|
||||
|
||||
## Обязательный канал сервера
|
||||
|
||||
Требуется серверная роль Admin; сервис дополнительно проверяет Invite.IsAdmin пользователя в БД.
|
||||
|
||||
```http
|
||||
PUT /api/admin/required-channel
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer <admin-access-token>
|
||||
|
||||
{ "channelId": "<GUID канала>", "allowLeave": false }
|
||||
```
|
||||
|
||||
GET `/api/admin/required-channel` возвращает channelId и allowLeave. PUT принимает существующий канал с владельцем; обычная группа не подходит. Канал может быть приватным. `{ "channelId": null, "allowLeave": true }` отключает автоматическое добавление.
|
||||
|
||||
После включения все новые зарегистрированные пользователи становятся обычными участниками выбранного канала, без расходования приглашения группы. Создание аккаунта, расходование приглашения регистрации и членство сохраняются одной транзакцией; сбой записи не оставляет частичную регистрацию. allowLeave=false запрещает выход из текущего обязательного канала, true разрешает выход обычным участникам/админам. Владелец сначала передаёт владение независимо от этой настройки.
|
||||
|
||||
Существующие пользователи автоматически не добавляются. Настройка выхода действует на всех текущих участников выбранного канала. Смена канала не удаляет старое членство, а ограничение выхода относится только к новому выбранному каналу. Статус обязательного канала не выдаёт административных прав и не отменяет модерацию.
|
||||
|
||||
## Миграция и проверка
|
||||
|
||||
```powershell
|
||||
dotnet ef database update --project Govor.Domain --startup-project Govor.API
|
||||
dotnet test tests/Govor.Server.Tests/Govor.Server.Tests.csproj -c Release
|
||||
```
|
||||
|
||||
Миграция `20261003131521_PrimitiveGroupsAndRequiredChannel` добавляет владельца, время создания, настройки сервера, лимиты/отзыв ссылок и уникальные индексы членства/админов/кодов. Старые дубли членства объединяются с сохранением бана; удаляются ссылки на отсутствующих пользователей и роли неактивных участников. Неоднозначные старые коды приглашений отзываются. Известное использование старых ссылок восстанавливается по сохранённым членствам; сведения о ранее вышедших пользователях в старой модели отсутствовали.
|
||||
|
||||
Для существующей группы владельцем выбирается самый ранний активный админ, а при его отсутствии — самый ранний активный участник. Пустые сообщества без активных участников остаются без владельца; для них миграция не назначает владельца произвольно. Новые сообщества всегда создаются с владельцем. Исправляется лишняя связь членства с теневым ChatGroupId; основной GroupId сохраняется.
|
||||
|
||||
Удаление сообщества, заявки на вступление, тонкие разрешения админов и UI MAUI в этот примитивный серверный сценарий не входят. Миграция подготовлена, но к рабочей пользовательской БД автоматически не применялась. Локально проверяются SQLite, реальные HTTP/JWT запросы и обработка файлов; PostgreSQL тестируется в существующем CI при его запуске.
|
||||
Единый актуальный контракт: [группы и каналы](../groups.md).
|
||||
|
||||
@@ -1,42 +1,37 @@
|
||||
# Медиа
|
||||
# Медиа и вложения
|
||||
|
||||
Требуется роль User/Admin.
|
||||
Требуются access token и роль User/Admin. Загрузка файла и отправка сообщения — отдельные операции.
|
||||
|
||||
## POST /api/media/upload
|
||||
|
||||
Content-Type: multipart/form-data. Поля:
|
||||
`multipart/form-data`:
|
||||
|
||||
| Поле | Тип | Назначение |
|
||||
| --- | --- | --- |
|
||||
| FromFile | файл | Непустое содержимое |
|
||||
| Type | число | Image=0, Video=1, Audio=2, File=3, Voice=4 |
|
||||
| MimeType | строка ≤255 | MIME типа файла |
|
||||
| EncryptedKey | строка | Обязательное поле запроса; сохранение ключа не реализовано |
|
||||
| OwnerType | число | Message=0, Avatar=1, GroupAvatar=2, System=3 |
|
||||
| Поле | Назначение |
|
||||
| --- | --- |
|
||||
| `FromFile` | Непустой бинарный файл |
|
||||
| `Type` | Число: Image=0, Video=1, Audio=2, File=3, Voice=4 |
|
||||
| `MimeType` | Обязательная строка до 128 символов |
|
||||
| `OwnerType` | Здесь разрешены только Message=0 и Avatar=1 |
|
||||
| `EncryptedKey` | Для сообщения отсутствует или пустая строка; ключ расшифровки передавать нельзя |
|
||||
|
||||
Ограничение запроса — 20 000 000 байт, включая multipart; проверка файла также ≤20 000 000. Не следует обещать загрузку файла ровно этого размера: overhead тоже входит в лимит.
|
||||
Для `OwnerType=Message` клиент **сначала шифрует файл**. `MimeType` должен совпадать с `E2eeProtocol.EncryptedMimeType`; сервер сохраняет случайное имя `.bin` и тип File. Оригинальные имя, MIME и ключ содержатся внутри зашифрованного сообщения, не в открытых полях upload.
|
||||
|
||||
Успех 200:
|
||||
Лимит всего запроса и multipart — `20 000 000` байт; такой же предел проверяется для файла. Overhead формы и шифрования тоже занимает место: нельзя обещать загрузку исходного файла ровно 20 MB. Аватары не являются E2EE-вложениями; доступ к ним и профильный upload описаны отдельно.
|
||||
|
||||
Успех `200`:
|
||||
|
||||
```json
|
||||
{"mediaId":"11111111-1111-1111-1111-111111111111","url":"2026/10/<имя файла>"}
|
||||
{"mediaId":"11111111-1111-1111-1111-111111111111","url":"<путь в хранилище>"}
|
||||
```
|
||||
|
||||
url — относительный путь хранилища, не публичный URL. Для скачивания используйте endpoint.
|
||||
`url` — внутренний путь, не публичная ссылка. Для сообщения используйте `mediaId` в списке вложений и метаданных зашифрованного конверта. Send проверяет загрузчика, тип владения, уникальность ID и соответствие вложений подписанному конверту. Чужой файл прикрепить нельзя.
|
||||
|
||||
## GET /api/media/download/{id}
|
||||
|
||||
Проверяет HasAccessAsync, затем возвращает бинарный файл с MIME и Content-Disposition. Если доступа нет или запись не найдена — 403, потому что проверка доступа выполняется первой. Сервисные ошибки — через ResultExtensions.
|
||||
Возвращает бинарный файл после проверки доступа. Для вложений учитывается участие в личном чате/группе и бан; непривязанная к сообщению загрузка не получает доступ к download только по признаку uploader. Отсутствие доступа или неизвестный ID могут дать `403`, поскольку доступ проверяется до чтения.
|
||||
|
||||
Ответ имеет `Cache-Control: no-store` и `X-Content-Type-Options: nosniff`. Клиент расшифровывает содержимое и проверяет целостность перед отображением. Не используйте серверное имя/MIME зашифрованного файла как оригинальные пользовательские метаданные.
|
||||
|
||||
## Ограничения
|
||||
|
||||
Для личного сообщения accesser сравнивает Message.RecipientId с userId, хотя там ID чата: получатель может получить 403. При Send принадлежность вложения загрузившему пользователю не проверяется. OwnerType задаёт клиент, включая публично доступный System, — нужна серверная политика владения.
|
||||
|
||||
EncryptedKey не хранится ни в MediaFile, ни в MediaAttachments. Нельзя обещать восстановление ключа из истории.
|
||||
|
||||
Файлы целиком буферизуются в памяти, MIME принимается от клиента. Запись файла и БД не атомарна: возможны файлы без записи. Очистка неиспользуемых загрузок и stream-based выдача требуют реализации.
|
||||
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
Источник: [Govor.API/Controllers/MediaController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/MediaController.cs).
|
||||
Файлы буферизуются в памяти; запись в файловую систему и БД не образует единую транзакцию. Возможны неиспользованные файлы после сбоя/отмены отправки. Не удаляйте их по одному признаку возраста без проверки ссылок. [Хранение и резервные копии](../operations.md).
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Прочтение сообщений
|
||||
|
||||
Контракт реализован в рабочей копии сервера от 03.10.2026. Требуются access token, роль User/Admin и участие именно в запрошенном чате. `chatId` — ID PrivateChat либо ChatGroup, а не ID собеседника. `recipientType`: 0 — личный чат, 1 — группа.
|
||||
Контракт текущей серверной ревизии из обзора. Требуются access token, роль User/Admin и участие именно в запрошенном чате. `chatId` — ID PrivateChat либо ChatGroup, а не ID собеседника. `recipientType`: 0 — личный чат, 1 — группа.
|
||||
|
||||
## POST /api/chats/{chatId}/read
|
||||
|
||||
|
||||
@@ -1,19 +1,12 @@
|
||||
# HTTP-присутствие — ограничения
|
||||
# Присутствие через HTTP
|
||||
|
||||
Требуется роль User/Admin.
|
||||
Требуются access token и роль User/Admin. Историческое имя файла сохранено для совместимости ссылок; endpoint status работает в текущей версии.
|
||||
|
||||
| Метод | Маршрут | Текущее поведение |
|
||||
| Метод | Маршрут | Ответ |
|
||||
| --- | --- | --- |
|
||||
| PATCH | /api/online/ping | Вызывает PingHandlerService, успех 200 без тела |
|
||||
| GET | /api/online/status/{userId} | Неработоспособен: 500 |
|
||||
| PATCH | `/api/online/ping` | Обновить lastSeen текущего пользователя; 200 без тела |
|
||||
| GET | `/api/online/status/{userId}` | 200, `{ isOnline, lastSeen }` |
|
||||
|
||||
В конструкторе не присваиваются _userOnlineStore и _presenceReader. GetStatus обращается к null; catch возвращает 500 "Internal server error.".
|
||||
isOnline определяется OnlineUserStore, lastSeen читается из сохранённого пользовательского состояния. Отсутствующие ранее зависимости конструктора исправлены. Исключение сервиса даёт 500, это не штатный ответ status.
|
||||
|
||||
Задуманное тело status — { isOnline, lastSeen }, но сейчас его нельзя считать рабочим контрактом.
|
||||
|
||||
Для событий online/offline подключайтесь к /hubs/presence. Ping и наличие SignalR-подключения — разные механизмы; требуется единая политика lastSeen/TTL. Не считайте HTTP ping подтверждением активного presence-соединения.
|
||||
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
Источник: [Govor.API/Controllers/OnlinePingingController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/OnlinePingingController.cs).
|
||||
Для событий подключайтесь к [PresenceHub](../signalr/presencehub.md). HTTP ping и наличие presence-соединения — разные механизмы: ping не создаёт SignalR online. OnlineUserStore находится в памяти одного процесса; после перезапуска и на нескольких экземплярах состояние не является общим.
|
||||
|
||||
@@ -16,14 +16,12 @@
|
||||
}]
|
||||
```
|
||||
|
||||
При принятии заявки FriendRequestCommandService также создаёт личный чат и добавляет текущие соединения участников в SignalR-группу.
|
||||
При принятии заявки FriendRequestCommandService также создаёт личный чат. ChatsHub использует группы сессий; ручная подписка клиента на чат не требуется.
|
||||
|
||||
Используйте chatId в Send.recipientId и в /api/user/{userId}/messages. Несмотря на имя параметра userId, загрузчик ожидает ID PrivateChat.
|
||||
|
||||
Ошибки дружбы передаются через Forbid(ex.Message), что ошибочно трактует сообщение как имя схемы аутентификации и может дать 500. Параллельное создание и повторное присоединение после частичного сбоя требуют отдельной проверки.
|
||||
Отсутствие дружбы/доступа возвращает 403 без обещания тела ProblemDetails. Некорректный аргумент — 400. При последовательном вызове существующий чат возвращается повторно. Сервис сначала ищет пару, затем создаёт запись; полную гарантию идемпотентности при конкурентном создании этот маршрут не обещает.
|
||||
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
Источник: [Govor.API/Controllers/PrivateChatController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/PrivateChatController.cs).
|
||||
Источник: [Govor.API/Controllers/PrivateChatController.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/PrivateChatController.cs).
|
||||
|
||||
|
||||
@@ -16,14 +16,12 @@ UserProfileDto: id, username, description (nullable), iconId (nullable), isOnlin
|
||||
|
||||
## Ограничения
|
||||
|
||||
REST UploadAvatar не рассылает AvatarUpdated. Клиентам может потребоваться отдельное обновление данных. В ProfileHub.SetAvatar проверяется существование файла, но не его загрузчик/тип/владелец.
|
||||
REST UploadAvatar не рассылает AvatarUpdated. Клиентам может потребоваться отдельное обновление данных. ProfileHub.SetAvatar и ProfileService проверяют, что файл загружен текущим пользователем с OwnerType.Avatar. Чужое вложение нельзя назначить аватаром.
|
||||
|
||||
Хаб игнорирует Result от SetDescription и SetNewIcon, поэтому успех true не всегда подтверждает изменение. MappingProfile дважды регистрирует UserProfile → UserProfileDto; это нужно устранить и проверить isOnline.
|
||||
Хаб проверяет Result от SetDescription и SetNewIcon: при сервисной ошибке возвращает ошибку HubResult и не рассылает успешное изменение.
|
||||
|
||||
Чтение чужого профиля не применяет PrivacyUserSettings. Наличие моделей приватности не означает действующую политику доступа.
|
||||
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
|
||||
Источник: [Govor.API/Controllers/ProfileController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/ProfileController.cs).
|
||||
Источник: [Govor.API/Controllers/ProfileController.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/ProfileController.cs).
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Реакции, паки и настройки каналов
|
||||
|
||||
Контракт рабочей версии сервера от 03.10.2026. Все маршруты требуют Bearer **access** token и активную сессию. JSON использует camelCase, перечисления передаются числами. HTTP и SignalR вызывают один сервис с одинаковыми проверками доступа.
|
||||
Контракт текущей серверной ревизии из обзора. Все маршруты требуют Bearer **access** token и активную сессию. JSON использует camelCase, перечисления передаются числами. HTTP и SignalR вызывают один сервис с одинаковыми проверками доступа.
|
||||
|
||||
## Реакции сообщения
|
||||
|
||||
@@ -130,4 +130,4 @@ dotnet ef database update --project Govor.Domain --startup-project Govor.API
|
||||
dotnet test tests/Govor.Server.Tests/Govor.Server.Tests.csproj -c Release
|
||||
```
|
||||
|
||||
Миграция `20261003101700_ReactionPacksAndChannelPolicies` создаёт каталог, установки, разрешения канала, версии и базовый пак; старые реакции сохраняются. Она подготовлена, но к вашей рабочей БД автоматически не применялась. Локальные тесты используют SQLite и HTTP pipeline с JWT; SignalR-доставка проверяется через mock транспорта. CI также настроен на PostgreSQL. Реальные устройства/сокеты и PostgreSQL локально не проверены.
|
||||
Миграция `20261003101700_ReactionPacksAndChannelPolicies` создаёт каталог, установки, разрешения канала, версии и базовый пак; старые реакции сохраняются. Применение к конкретной установке проверяется отдельно через миграции и /server/ready. [Тестирование и границы проверки](../testing.md).
|
||||
|
||||
@@ -1,33 +1,19 @@
|
||||
# Ключи сессий — экспериментальный API
|
||||
# Старый API prekeys
|
||||
|
||||
RequireHttps и роль User/Admin обязательны.
|
||||
Эти маршруты сохранены для совместимости и отличаются от действующего [API E2EE устройств](e2ee.md). Они сами по себе не реализуют Signal Protocol, ratchet или архив истории.
|
||||
|
||||
Требуются HTTPS, access token и роль 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 | Пометить собственный ключ использованным |
|
||||
| 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 одноразовых ключей. Сервис запрещает повторную привязку ключей к сессии и проверяет владельца.
|
||||
`byte[]` передаются в JSON как Base64. `UploadKeysRequest`: `identityKey`, `signedPreKey`, `signedPreKeySignature`, `oneTimePreKeys`. За upload или rotate допускается до 100 новых prekeys. Rotate получает `newOneTimePreKeys`.
|
||||
|
||||
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).
|
||||
Сервис проверяет владельца сессии; повторная привязка запрещена. Reader возвращает публичные DTO со `signedPreKey` и неиспользованными `oneTimePreKeys`, без внутренних данных UserSession. Конструктор rotator исправлен; прежняя ошибка null больше не описывает текущий сервер.
|
||||
|
||||
`used` относится к сессии владельца, а не к атомарной выдаче ключа произвольному собеседнику. Не стройте новый E2EE-клиент на предположении, что это законченный протокол одноразового обмена. За reverse proxy учитывайте [RequireHttps и forwarded headers](../configuration.md).
|
||||
|
||||
@@ -19,17 +19,17 @@
|
||||
}]
|
||||
```
|
||||
|
||||
Список фильтруется по UserId и !IsRevoked, но не по ExpiresAt; истекшие сессии могут присутствовать. CreatedAt меняется при refresh.
|
||||
Список фильтруется по UserId и !IsRevoked, но не по ExpiresAt; истекшие сессии могут присутствовать. CreatedAt сохраняет дату первоначального открытия сессии.
|
||||
|
||||
Закрытие чужой, неизвестной или уже отозванной сессии возвращает 404 с errorCode UserSession.NotFoundOrUnauthorized. Guid.Empty возвращает 400. CloseAll без активных сессий тоже успешен.
|
||||
|
||||
Отзыв деактивирует связанные push-токены. Успех Unit преобразуется в 204, а не в 200.
|
||||
|
||||
## Ограничение logout
|
||||
## Действие отзыва
|
||||
|
||||
IsRevoked проверяется при refresh; bearer middleware не сверяет текущий sid с БД. Access token может работать до окончания срока, а существующее соединение SignalR не закрывается этим контроллером.
|
||||
Bearer middleware проверяет sid, владельца, срок и отзыв по БД. SignalR-фильтр повторяет проверку перед каждой командой и прерывает соединение при отказе. ChatsHub исключает отозванные сессии из маршрутизации. Контроллер не гарантирует мгновенное физическое закрытие всех соединений других хабов; клиент останавливает reconnect и закрывает соединения при logout.
|
||||
|
||||
---
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
|
||||
Отзыв исключает устройство из новых E2EE-получателей, но не удаляет уже имеющиеся на нём ключи, кэш и прочитанную историю.
|
||||
|
||||
Источник: [Govor.API/Controllers/SessionController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/SessionController.cs).
|
||||
|
||||
Источник: [Govor.API/Controllers/SessionController.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/SessionController.cs).
|
||||
|
||||
Reference in New Issue
Block a user