From 2afb37aa6e1c83ce4a58d0a70d4e16369c4ee75d Mon Sep 17 00:00:00 2001 From: gsr Date: Sun, 27 Sep 2026 16:27:57 +0300 Subject: [PATCH] update --- api.md | 2 +- changelog.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 104 insertions(+), 2 deletions(-) diff --git a/api.md b/api.md index 39beaf4..3f66dc1 100644 --- a/api.md +++ b/api.md @@ -645,4 +645,4 @@ X-API-Key: {{apiKey}} --- **Последнее обновление:** 27 сентября 2026 -**Версия API:** `0.7.5-beta` \ No newline at end of file +**Версия API:** `0.5.6-beta` \ No newline at end of file diff --git a/changelog.md b/changelog.md index 190d462..d6f4ad5 100644 --- a/changelog.md +++ b/changelog.md @@ -1,3 +1,105 @@ +## [0.5.6-beta] - 2026-09-27 + +### Добавлено + +- **API Keys System**: Полноценная система API ключей для программного доступа к MarkClean API. Ключи генерируются в формате `mk_live_` с криптографически стойкой случайностью (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.