Skip to content

Почта и восстановление доступа

VideoGrace Server содержит один общий SMTP transport. Он работает в отдельном worker-потоке и не блокирует control, chat или media loop. Очередь ограничена Mail.MaxQueueSize; при переполнении API возвращает ошибку, а не создает неограниченную аллокацию.

flowchart LR
    UI[Web client] -->|HTTPS API| API[Server API]
    API -->|bounded queue| Mail[MailSender]
    Mail -->|SMTP TLS / STARTTLS| Relay[SMTP relay]
    Relay --> Inbox[Получатель]
    API --> DB[(main.db)]

Приглашение по email

POST /api/v1.0/mail/invite
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "email": "student@example.com",
  "link": "https://vc.example.com/conferences/lesson-42",
  "title": "Урок фортепиано",
  "kind": "conference"
}

kind принимает conference или platform. API доступен авторизованному пользователю. Чтобы сервер нельзя было использовать как phishing relay, link обязан вести на текущий публичный адрес VideoGrace. Ограничения: не более 30 приглашений в час на отправителя и 5 писем в час одному адресу. В журнале rate-limit хранится SHA-256 email, а не исходный адрес.

Успешный ответ означает, что письмо принято ограниченной очередью, но не является гарантией доставки внешним SMTP relay:

{"ok": true, "message": "Email queued"}

Запрос восстановления пароля

Публичный endpoint всегда возвращает нейтральный ответ для существующего и неизвестного адреса:

POST /api/v1.0/password_reset/request
Content-Type: application/json

{"email": "user@example.com"}

При существующем активном пользователе сервер создает 256-битный random token, сохраняет только его SHA-256 и отправляет ссылку /login?reset_token=.... Новый запрос инвалидирует предыдущую активную ссылку. Лимит составляет 3 запроса в час на email и 200 запросов в час на сервер.

Подтверждение нового пароля

POST /api/v1.0/password_reset/confirm
Content-Type: application/json

{
  "token": "<token-from-email>",
  "password": "new-password"
}

Пароль должен содержать от 8 до 128 символов. Токен одноразовый и действует Mail.ResetTokenTtlSec. После успешной транзакции сервер помечает все reset token пользователя использованными, удаляет refresh token, обновляет runtime user cache и закрывает активные сессии.

Проверка SMTP

Администратор может проверить сохраненную конфигурацию синхронным запросом:

POST /api/v1.0/mail/test
Authorization: Bearer <admin_access_token>
Content-Type: application/json

{"email": "admin@example.com"}

В отличие от фоновой отправки, endpoint возвращает фактическую ошибку DNS, TLS handshake, SMTP AUTH или SMTP response с HTTP 502. SMTP password никогда не возвращается административным API.

Эксплуатационные свойства

  • SMTP transport поддерживает TLS на подключении (tls), STARTTLS (starttls) и незашифрованный trusted relay (none).
  • При VerifyTls=1 проверяются CA-цепочка и hostname SMTP-сервера.
  • Старые rate-limit события и использованные/истекшие reset token очищаются при последующих почтовых запросах.
  • Тело письма формируется сервером; web-клиент не передает произвольный subject или HTML.
  • Переменные VG_MAIL_* и полный список параметров описаны в руководстве администратора.