docs: API - JWT 1 month + refresh, bot service token, decisions

docs/tech-design/02-api.md

@@ -67,14 +67,30 @@
 // request
 { "token": "...", "messenger_type": "telegram", "messenger_id": "123456" }
 // response 200
-{ "access_token": "jwt", "expires_at": "...", "user": { "id": 1, "full_name": "..." } }
+{
+  "access_token": "jwt",
+  "refresh_token": "opaque",
+  "expires_at": "...",
+  "user": { "id": 1, "full_name": "..." }
+}
 ```
 
 **Ошибки:** `409 link_already_used` → «Ссылка уже была использована. Запросите новую у координатора».
 
-### 2.3. `POST /auth/logout` — завершить сессию
+### 2.3. `POST /auth/refresh` — обновить access-токен
 
-### 2.4. `GET /auth/me` — текущий пользователь
+```json
+// request
+{ "refresh_token": "opaque" }
+// response 200
+{ "access_token": "jwt", "refresh_token": "opaque", "expires_at": "..." }
+```
+
+**Правило:** refresh-токен ротируемый (при обновлении выдаётся новый, старый инвалидируется).
+
+### 2.4. `POST /auth/logout` — завершить сессию
+
+### 2.5. `GET /auth/me` — текущий пользователь
 
 ```json
 {
@@ -334,12 +350,18 @@
 
 ---
 
-## 17. Открытые вопросы
+## 17. Принятые решения и открытые вопросы
 
-1. **Формат JWT** — срок жизни access-токена и нужен ли refresh.
+**Принято:**
-2. **Сервисный токен бота** — отдельный тип или роль `system`.
+
-3. **Presigned URL** — срок жизни ссылок на скачивание артефактов.
+1. **JWT** — access-токен сроком **1 месяц** + **refresh-токен** (ротируемый). Эндпоинт `POST /auth/refresh`.
-4. **Вебхуки MAX** — уточнить после проверки MAX Bot API.
+   - *Рекомендация по безопасности:* для продакшена желательно сократить access-токен (например, до 1 часа) и держать длинным refresh; при текущем решении компромисс — короткий срок хранения сессий и журналирование.
+2. **Сервисный токен бота** — отдельный тип токена (системный актор), не роль пользователя.
+3. **Вебхуки MAX** — проверяем после подтверждения возможностей MAX Bot API.
+
+**Открыто:**
+
+4. **Presigned URL** — срок жизни ссылок на скачивание артефактов (предложение: 15 минут).
 
 ---