Fix API regressions and refresh project docs

app/api/deps.py

@@ -2,10 +2,9 @@ import os
 import hmac
 import logging
 from dataclasses import dataclass
-from typing import Optional
 from fastapi import Depends, HTTPException
 from fastapi.security import APIKeyHeader
-from starlette.status import HTTP_403_FORBIDDEN
+from starlette.status import HTTP_403_FORBIDDEN, HTTP_503_SERVICE_UNAVAILABLE
 from dotenv import load_dotenv
 from sqlalchemy import select
 
@@ -16,10 +15,6 @@ load_dotenv()
 
 logger = logging.getLogger(__name__)
 
-MASTER_KEY = os.getenv("IGNIS_API_KEY")
-if not MASTER_KEY:
-    logger.warning("IGNIS_API_KEY не задан -- авторизация отключена!")
-
 API_KEY_NAME = "X-API-Key"
 api_key_header = APIKeyHeader(name=API_KEY_NAME, auto_error=False)
 
@@ -33,17 +28,26 @@ class AuthContext:
     key_name: str  # имя ключа (для логов)
 
 
+def get_master_key() -> str | None:
+    value = os.getenv("IGNIS_API_KEY", "").strip()
+    return value or None
+
+
 async def verify_token(header_value: str = Depends(api_key_header)) -> AuthContext:
     """
     Проверка API-ключа:
-    1. Если IGNIS_API_KEY не задан -- авторизация отключена, полный доступ
+    1. IGNIS_API_KEY должен быть задан, иначе сервер закрыт (fail-closed)
     2. Мастер-ключ из .env -- полный доступ
     3. Ключ из БД (api_keys) -- проверяем active и is_admin
     4. Иначе -- 403
     """
-    # Авторизация отключена
-    if not MASTER_KEY:
-        return AuthContext(is_master=True, is_admin=True, key_name="no-auth")
+    master_key = get_master_key()
+    if not master_key:
+        logger.error("IGNIS_API_KEY не задан: защищённые API закрыты до настройки")
+        raise HTTPException(
+            status_code=HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Сервер не настроен: задайте IGNIS_API_KEY",
+        )
 
     if not header_value:
         raise HTTPException(
@@ -51,7 +55,7 @@ async def verify_token(header_value: str = Depends(api_key_header)) -> AuthConte
         )
 
     # Мастер-ключ (timing-safe сравнение)
-    if hmac.compare_digest(header_value, MASTER_KEY):
+    if hmac.compare_digest(header_value, master_key):
         return AuthContext(is_master=True, is_admin=True, key_name="master")
 
     # Ищем в БД
@@ -78,3 +82,13 @@ def require_admin(auth: AuthContext = Depends(verify_token)) -> AuthContext:
     if not auth.is_admin:
         raise HTTPException(status_code=HTTP_403_FORBIDDEN, detail="Недостаточно прав")
     return auth
+
+
+def require_master(auth: AuthContext = Depends(verify_token)) -> AuthContext:
+    """Dependency для роутов, доступных только мастер-ключу."""
+    if not auth.is_master:
+        raise HTTPException(
+            status_code=HTTP_403_FORBIDDEN,
+            detail="Требуется мастер-ключ",
+        )
+    return auth