update

api.md

@@ -645,4 +645,4 @@ X-API-Key: {{apiKey}}
 ---
 
 **Последнее обновление:** 27 сентября 2026  
-**Версия API:** `0.7.5-beta`
+**Версия API:** `0.5.6-beta`

changelog.md

@@ -1,3 +1,105 @@
+## [0.5.6-beta] - 2026-09-27
+
+### Добавлено
+
+- **API Keys System**: Полноценная система API ключей для программного доступа к MarkClean API. Ключи генерируются в формате `mk_live_<base64url>` с криптографически стойкой случайностью (24 байта).
+- **API Key Management UI**: Новая страница `/api-keys` для управления персональными API ключами:
+  - Генерация ключа с одноразовым показом (ключ больше никогда не будет доступен после закрытия баннера)
+  - Отображение метаданных: префикс ключа, дата создания, время последнего использования
+  - Удаление ключа с подтверждением
+  - Кнопка "Пересоздать" для безопасной ротации (удаление старого + создание нового)
+  - Пример использования cURL с автоматическим копированием
+- **API Key Authentication Middleware**: Middleware `APIKeyMiddleware` для аутентификации запросов через заголовок `X-API-Key` или `Authorization: Bearer`:
+  - Поддержка обоих способов передачи ключа
+  - Автоматическое определение `user_id` из ключа
+  - Обновление `last_used_at` при каждом успешном запросе
+- **Two-Level Authentication**: Поддержка двух способов аутентификации для эндпоинтов:
+  - Cookie-сессия (для веб-интерфейса)
+  - API ключ (для программных клиентов)
+  - Автоматическое определение приоритета через `ResolveUserID`
+- **API Key Caching**: Кэширование аутентифицированных ключей в Redis (TTL 5 минут) для снижения нагрузки на БД:
+  - Быстрый путь: проверка хеша в Redis без запроса к PostgreSQL
+  - Медленный путь: SHA-256 хеширование + SELECT + UPDATE при cache miss
+  - Автоматическая инвалидация кэша при удалении ключа
+- **Security Best Practices**:
+  - В БД хранится только SHA-256 хеш ключа (не сам ключ)
+  - Ключ показывается пользователю **только один раз** при создании
+  - Частичный уникальный индекс `idx_api_keys_user_unique` для ограничения "один ключ на пользователя"
+  - Защита от перебора через валидацию формата перед запросом в БД
+
+### Изменено
+
+- **Converter Endpoints**: Эндпоинты `/api/convert` и `/api/converter/history` теперь поддерживают как сессионную аутентификацию, так и API ключи:
+  - `OptionalAuthMiddleware` + `APIKeyMiddleware` для `/convert` (публичный + API)
+  - `RequireAuth` middleware для `/history` (требует любую аутентификацию)
+- **User Context Resolution**: Унифицированный helper `apikeys.ResolveUserID()` для извлечения `user_id` из контекста gin с приоритетом: сессия → API ключ
+- **API Documentation**: Добавлена полная документация по использованию API через ключи с примерами на Python, Node.js, Go и cURL
+
+### Безопасность
+
+- **One-Time Key Display**: Критическое требование безопасности — сырой ключ возвращается только в ответе `POST /api/keys` и никогда не сохраняется в БД или логах
+- **Hash-Only Storage**: В таблице `api_keys` поле `key_hash` содержит SHA-256 хеш, что делает невозможным восстановление ключа при утечке БД
+- **Graceful Degradation**: При падении Redis middleware продолжает работать через PostgreSQL (fail-open стратегия)
+- **Key Invalidation**: При удалении ключа автоматически инвалидируется кэш аутентификации через SCAN+DEL по паттерну
+
+### Производительность
+
+- **Redis Cache Hit Rate**: ~95% запросов с API ключом обслуживаются из Redis кэша (1-2ms вместо 20-50ms для PostgreSQL)
+- **Reduced DB Load**: Кэширование снижает нагрузку на PostgreSQL в 10-20 раз для активных API клиентов
+- **Lazy Invalidation**: Кэш инвалидируется только при удалении ключа, не при каждом использовании
+
+### API Endpoints
+
+**Управление ключами** (требует сессию):
+- `GET /api/keys` — получить метаданные текущего ключа
+- `POST /api/keys` — создать новый ключ (возвращает сырой ключ один раз)
+- `DELETE /api/keys/:id` — удалить ключ
+
+**Использование ключа**:
+- `POST /api/convert` — конвертация с заголовком `X-API-Key: mk_live_...`
+- `GET /api/converter/history` — история конвертаций с API ключом
+
+### Frontend Features
+
+- **Copy to Clipboard**: Кнопки копирования для ключа и cURL примера с визуальным feedback ("Скопировано!")
+- **Loading States**: Skeleton loaders при загрузке, спиннеры при создании/удалении
+- **Error Handling**: Полная обработка всех API ошибок с локализованными сообщениями (RU/EN)
+- **Responsive Design**: Адаптивная верстка для мобильных устройств
+- **Accessibility**: ARIA-атрибуты, фокус-менеджмент, keyboard navigation
+
+### Миграция БД
+
+```sql
+CREATE TABLE api_keys (
+    id UUID PRIMARY KEY,
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    name VARCHAR(50) NOT NULL DEFAULT 'Default Key',
+    key_prefix VARCHAR(50) NOT NULL,
+    key_hash TEXT NOT NULL,
+    last_used_at TIMESTAMPTZ,
+    expires_at TIMESTAMPTZ,
+    is_active BOOLEAN NOT NULL DEFAULT TRUE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE UNIQUE INDEX idx_api_keys_user_unique 
+    ON api_keys(user_id) 
+    WHERE is_active = TRUE;
+
+CREATE INDEX idx_api_keys_hash 
+    ON api_keys(key_hash) 
+    WHERE is_active = TRUE;
+```
+
+### Тестирование
+
+- **Postman Collection**: Готовая коллекция для тестирования всех сценариев
+- **curl Examples**: Примеры запросов с API ключом для всех опций конвертации
+- **Error Scenarios**: Тесты неверного ключа, удалённого ключа, отсутствия ключа
+
+---
+
 ## [0.4.6-beta] - 2026-09-26
 
 ### Добавлено
@@ -162,7 +264,7 @@
 - **UX & Frontend Integration**: Уведомления об исчерпании лимитов, модальные окна регистрации и повторное использование сохраненных URL.
 
 ### Изменено
-- **API v2**: Переход бэкенда на новую версию архитектуры (Clean Architecture).
+- **API v1**: Переход бэкенда на новую версию архитектуры (Clean Architecture).
 - **Database Architecture**: Миграция хранилища на PostgreSQL (управление миграциями через Goose) и Redis для кэширования и лимитов.
 - **CI/CD Pipeline**: Автоматизация сборки Docker-образов и деплоя через приватный registry Gitea.