GITBOOK-14: Govor.API: документация по текущему коду и диагностика 03.10.2026

This commit is contained in:
stalcke2288969
2026-10-03 06:20:45 +00:00
committed by gitbook-bot
parent 4603be9f71
commit 6c8abb23e3
27 changed files with 827 additions and 1901 deletions
+19 -32
View File
@@ -3,43 +3,30 @@ description: How to work with jwt tokens
icon: user
---
# Authentication
# Аутентификация
### <mark style="color:$info;">Components</mark>
## Последовательность
* **AuthController**: Handles registration and login.
* **Route**: `/api/auth`
* **RefreshController**: Manages token refresh.
* **Route**: `/api/auth/token`
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.
### <mark style="color:$info;">Authentication Process</mark>
Access token содержит `userId`, `sid` и роль User/Admin. Подпись HS256 проверяется, срок проверяется, issuer и audience не проверяются. Токены возвращаются JSON; сервер не устанавливает HttpOnly-cookie.
* **Registration**:
* **Endpoint**: `POST /api/auth/register`
* **Input**: `RegistrationRequest` (name, password, inviteLink, deviceInfo)
* **Output**: Access token
* **Action**: Validates invite, registers user, opens session.
* **Login**:
* **Endpoint**: `POST /api/auth/login`
* **Input**: `LoginRequest` (name, password, deviceInfo)
* **Output**: Access token
* **Action**: Authenticates user, opens session.
* **Token Refresh**:
* **Endpoint**: `POST /api/auth/token/refresh`
* **Input**: `RefreshTokenRequest` (refreshToken)
* **Output**: `RefreshTokenResponse` (accessToken, refreshToken)
* **Action**: Refreshes expired access token.
## Ограничения реализации
### <mark style="color:$info;">Token Usage</mark>
Отзыв сессии блокирует refresh, но Program.cs не проверяет IsRevoked при каждом использовании access token. Уже открытые SignalR-соединения явно не разрываются. Немедленный logout на всех устройствах не гарантирован.
* **Access Token**:
* **Request**: Obtain during registration or login.
* **Refresh**: Request via `/api/auth/token/refresh` when expired (e.g., 02:12 PM CEST, July 21, 2025).
* **Refresh Token**:
* **Request**: Received during registration or login.
* **Refresh**: Use to obtain new access token when current one expires.
Refresh JWT содержит userId и tokenType, но не случайный jti или sid. При выпуске одному пользователю в одну секунду возможны одинаковые токены, конфликтующие с уникальным RefreshTokenHash. Ротация не защищена атомарным compare-and-swap от параллельных запросов.
### Security
Не используйте refresh token как access token. В bearer-валидации нет явного требования tokenType=access; методы с одним Authorize требуют исправления разделения типов токенов.
* **Protocol**: Requires HTTPS.
* **Storage**: Store refresh token in HTTP-only cookie with `Secure` and `SameSite=Strict`.
На MAUI рекомендовано хранить refresh token в SecureStorage и выполнять обновление последовательно. Это рекомендация клиенту, а не свойство сервера.
***
Проверено по исходникам на 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).
+29 -118
View File
@@ -4,138 +4,49 @@ description: >-
and login, with session management and invite-based registration.
---
# AuthController
# Регистрация и вход
### Controller Description
Оба метода доступны анонимно, Content-Type: application/json.
* **Route**: `api/auth`
* **Authorize**: Allows anonymous access (`[AllowAnonymous]`).
## POST /api/auth/register
### Endpoints
```json
{
"name": "Артём",
"password": "example-password",
"inviteLink": "<код приглашения>",
"deviceInfo": "Android test device"
}
```
#### <mark style="color:$info;">Register</mark>
Имя: 4–44 символа, только кириллица и цифры, первый символ — буква. Модерация запрещает зарезервированные имена, совпадения/подстроки из конфигурации и пять одинаковых символов подряд. Пароль: минимум 8 символов. DeviceInfo необязателен в запросе, но в БД ограничен 256 символами.
* **Description**: Registers a new user using a valid invite link and opens a user session, returning an authentication token.
* **Route**: `[POST] api/auth/register`
* **HTTP Method**: `POST`
* **Request**:
* **Content-Type**: `application/json`
* **Request Body**: `RegistrationRequest` object with the following structure:
Код создаётся как Guid.ToString("N"): 32 символа без дефисов. Поиск кода — по строковому равенству. InviteLink — код, а не URL.
```json
{
"name": "string",
"password": "string",
"inviteLink": "string",
"deviceInfo": "string"
}
```
* **Responses**:
* <mark style="color:$success;">**200 OK**</mark>: Returns the authentication token upon successful registration and session creation.
Проверяется существование приглашения, срок и число участников. Проверка IsActive отсутствует, лимит участников не защищён от конкурентной регистрации.
```json
{
"refreshToken": "string",
"accessToken": "string"
}
```
* <mark style="color:$danger;">**400 Bad Request**</mark>:
* If model validation fails.
* If the user already exists: `"Registration failed: user already exists."`
* If the invite link is invalid: `"Invite link invalid."`
* If the username is invalid: `"Invalid username: <error_message>"`
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
Успех 200:
```json
"An unexpected error occurred. Please try again later."
```
```json
{"refreshToken":"<token>","accessToken":"<token>"}
```
#### <mark style="color:$info;">Login</mark>
Конфликт имени — 409; ошибки валидации — 400; отсутствующее приглашение — 404. Тело сервисных ошибок — ProblemDetails с errorCode. Регистрация и открытие сессии — отдельные сохранения: ошибка открытия сессии не откатывает созданного пользователя.
* **Description**: Authenticates an existing user and opens a session, returning an authentication token.
* **Route**: `[POST] api/auth/login`
* **HTTP Method**: `POST`
* **Request**:
* **Content-Type**: `application/json`
* **Request Body**: `LoginRequest` object with the following structure:
## POST /api/auth/login
```json
{
"name": "string",
"password": "string",
"deviceInfo": "string"
}
```
* **Responses**:
* <mark style="color:$success;">**200 OK**</mark>: Returns the authentication token upon successful login and session creation.
```json
{"name":"Артём","password":"example-password","deviceInfo":"Android test device"}
```
```json
{
"refreshToken": "string",
"accessToken": "string"
}
```
* <mark style="color:$danger;">**400 Bad Request**</mark>:
* If model validation fails.
* If the user does not exist: `"Login failed: user does not exist."`
* If the username or password is incorrect: `"Login failed: username or password is incorrect."`
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
Успех 200 с той же парой токенов. Пользователь не найден — 404 (UserNotRegisteredException); неверный пароль — 400 (InvalidOperationException). Это текущее поведение, а не рекомендуемая политика ошибок входа: разные ответы раскрывают существование аккаунта.
```json
"An unexpected error occurred. Please try again later."
```
## Ограничения
### Data Models
Rate limiting и блокировка перебора в Program.cs не настроены. Для публичного запуска нужны единая ошибка входа, ограничение частоты и защита административных приглашений.
#### RegistrationRequest
***
* **Description**: Model for registration request data.
* **Structure**:
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
```json
{
"name": "string",
"password": "string",
"inviteLink": "string",
"deviceInfo": "string"
}
```
#### LoginRequest
* **Description**: Model for login request data.
* **Structure**:
```json
{
"name": "string",
"password": "string",
"deviceInfo": "string"
}
```
#### RefreshResult
* **Description**: Model for refresh token response data.
* **Structure**:
```json
{
"refreshToken": "string",
"accessToken": "string"
}
```
### Error Handling
* **Invalid User ID**: Not applicable (handled by session service).
* **Invalid Operations**: Registration fails if the user already exists, invite link is invalid, or username is invalid, returning `400 Bad Request`.
* **Unauthorized Access**: Not applicable (endpoint is `[AllowAnonymous]`).
* **Unexpected Errors**: General exceptions are caught, logged, and returned as `500 Internal Server Error`.
### Logging
* Logs successful registration and login events with username and user ID.
* Logs session opening events with username and user ID.
* Logs warnings for specific exceptions (e.g., user already exists, invalid invite link, login failures).
* Logs errors for unexpected exceptions during registration and login.
Источник: [Govor.API/Controllers/Authentication/AuthController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/Authentication/AuthController.cs).
@@ -4,87 +4,40 @@ description: >-
their access tokens using a valid refresh token.
---
# RefreshController
# Обновление токенов
### Controller Description
## POST /api/auth/token/refresh
* **Route**: `api/auth/token`
* **Authorize**: Allows anonymous access (`[AllowAnonymous]`).
Доступ анонимный. JSON:
### Endpoints
```json
{"refreshToken":"<последний сохранённый refresh token>"}
```
#### <mark style="color:$info;">Refresh</mark>
Сервис хеширует переданную строку и ищет UserSession по RefreshTokenHash. Проверяет IsRevoked и ExpiresAt, выпускает новую пару, заменяет хеш и продлевает ExpiresAt. CreatedAt также перезаписывается, поэтому после refresh это не исходная дата открытия сессии.
* **Description**: Refreshes an access token using a provided refresh token and returns a new access token and refresh token pair.
* **Route**: `[POST] api/auth/token/refresh`
* **HTTP Method**: `POST`
* **Request**:
* **Content-Type**: `application/json`
* **Request Body**: `RefreshTokenRequest` object with the following structure:
Успех 200:
```json
{
"refreshToken": "string"
}
```
* **Responses**:
* <mark style="color:$success;">**200 OK**</mark>: Returns a new access token and refresh token upon successful refresh.
```json
{"refreshToken":"<new token>","accessToken":"<new token>"}
```
```json
{
"accessToken": "string",
"refreshToken": "string"
}
```
* <mark style="color:$warning;">**400 Bad Request**</mark>: If model validation fails or the refresh token is empty.
| Случай | Текущий ответ |
| -------------------------- | -------------------------------- |
| Пустая строка | 400, errorCode Auth.EmptyToken |
| Хеш не найден | 400, errorCode Auth.InvalidToken |
| Истекшая/отозванная сессия | 400, errorCode Auth.InvalidToken |
```json
"Refresh token cant be empty."
```
* <mark style="color:$warning;">**401 Unauthorized**</mark>: If the refresh token is invalid or authorization fails.
Не документируйте неверный refresh как гарантированный 401: текущий Error.Failure преобразуется в 400.
```json
"Invalid refresh token"
```
* <mark style="color:$danger;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
## Клиент
```json
"An unexpected error occurred."
```
Сохраните оба новых токена и сериализуйте refresh-запросы. Ошибка сети не должна автоматически удалять авторизацию пользователя. При подтверждённо недействительном refresh требуется повторный вход.
### Data Models
Ротация сейчас не имеет защиты от конкурентного использования и истории повторного применения. Детали — в разделе «Аутентификация».
#### RefreshTokenRequest
***
* **Description**: Model for refresh token request data.
* **Structure**:
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
```json
{
"refreshToken": "string"
}
```
#### RefreshTokenResponse
* **Description**: Model for refresh token response data.
* **Structure**:
```json
{
"accessToken": "string",
"refreshToken": "string"
}
```
### Error Handling
* **Invalid User ID**: Not applicable (handled by session service).
* **Invalid Operations**: Returns `400 Bad Request` if the refresh token is empty or invalid.
* **Unauthorized Access**: Returns `401 Unauthorized` if the refresh token fails authorization.
* **Unexpected Errors**: General exceptions are caught, logged, and returned as `500 Internal Server Error`.
### Logging
* Logs warnings for invalid or failed refresh token attempts.
* Logs errors for unexpected exceptions during token refresh.
Источник: [Govor.Application/Users/UserSessions/UserSessionRefresher.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.Application/Users/UserSessions/UserSessionRefresher.cs).
@@ -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).