Upload backend/core/security.py with huggingface_hub
Browse files- backend/core/security.py +296 -0
backend/core/security.py
ADDED
|
@@ -0,0 +1,296 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""
|
| 2 |
+
core/security.py β Sentinel-AI
|
| 3 |
+
=================================
|
| 4 |
+
Optional authentication and rate limiting for shared deployments.
|
| 5 |
+
|
| 6 |
+
The local demo is intentionally open: when ``SENTINEL_API_KEY`` is unset the
|
| 7 |
+
API behaves exactly as before. Set the variable (and the matching
|
| 8 |
+
``VITE_API_KEY`` in the dashboard) to require a Bearer token on every
|
| 9 |
+
non-health request.
|
| 10 |
+
|
| 11 |
+
Rate limiting is a per-client token bucket. It is in-process and therefore
|
| 12 |
+
per-worker; put a shared limiter (nginx, API gateway, Redis) in front of a
|
| 13 |
+
multi-worker deployment. Both features are deliberately dependency-free.
|
| 14 |
+
|
| 15 |
+
Middleware ordering
|
| 16 |
+
-------------------
|
| 17 |
+
Starlette builds its middleware stack in reverse insertion order, so the
|
| 18 |
+
middleware added **last** is the outermost one. ``install_security(app)`` is
|
| 19 |
+
therefore called *before* ``app.add_middleware(CORSMiddleware, ...)`` in
|
| 20 |
+
``main.py``: CORS must stay outermost so preflight ``OPTIONS`` requests are
|
| 21 |
+
answered before authentication runs.
|
| 22 |
+
"""
|
| 23 |
+
|
| 24 |
+
from __future__ import annotations
|
| 25 |
+
|
| 26 |
+
import hashlib
|
| 27 |
+
import hmac
|
| 28 |
+
import math
|
| 29 |
+
import os
|
| 30 |
+
import threading
|
| 31 |
+
import time
|
| 32 |
+
|
| 33 |
+
from fastapi import FastAPI
|
| 34 |
+
from starlette.middleware.base import BaseHTTPMiddleware
|
| 35 |
+
from starlette.requests import Request
|
| 36 |
+
from starlette.responses import JSONResponse, Response
|
| 37 |
+
|
| 38 |
+
# Paths that must remain reachable without a token: liveness probes and the
|
| 39 |
+
# generated API documentation. Everything under /api/v1 is protected.
|
| 40 |
+
_EXEMPT_PATHS = frozenset({
|
| 41 |
+
"/health",
|
| 42 |
+
"/docs",
|
| 43 |
+
"/redoc",
|
| 44 |
+
"/openapi.json",
|
| 45 |
+
"/docs/oauth2-redirect",
|
| 46 |
+
})
|
| 47 |
+
|
| 48 |
+
# Security headers applied to every response. The API only serves JSON and
|
| 49 |
+
# images, so a restrictive policy is safe and cheap.
|
| 50 |
+
_SECURITY_HEADERS = {
|
| 51 |
+
"X-Content-Type-Options": "nosniff",
|
| 52 |
+
"X-Frame-Options": "DENY",
|
| 53 |
+
"Referrer-Policy": "no-referrer",
|
| 54 |
+
"Cache-Control": "no-store",
|
| 55 |
+
}
|
| 56 |
+
|
| 57 |
+
|
| 58 |
+
def _env_bool(name: str, default: bool = False) -> bool:
|
| 59 |
+
raw = os.getenv(name)
|
| 60 |
+
if raw is None:
|
| 61 |
+
return default
|
| 62 |
+
return raw.strip().lower() in {"1", "true", "yes", "on"}
|
| 63 |
+
|
| 64 |
+
|
| 65 |
+
def _env_int(name: str, default: int) -> int:
|
| 66 |
+
try:
|
| 67 |
+
return int(os.getenv(name, str(default)))
|
| 68 |
+
except (TypeError, ValueError):
|
| 69 |
+
return default
|
| 70 |
+
|
| 71 |
+
|
| 72 |
+
# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 73 |
+
# Token bucket
|
| 74 |
+
# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 75 |
+
|
| 76 |
+
class _TokenBucket:
|
| 77 |
+
"""A single client's token bucket (not thread-safe on its own)."""
|
| 78 |
+
|
| 79 |
+
__slots__ = ("capacity", "refill_per_sec", "tokens", "updated")
|
| 80 |
+
|
| 81 |
+
def __init__(self, capacity: int, refill_per_sec: float) -> None:
|
| 82 |
+
self.capacity = float(max(1, capacity))
|
| 83 |
+
self.refill_per_sec = max(refill_per_sec, 0.0)
|
| 84 |
+
self.tokens = self.capacity
|
| 85 |
+
self.updated = time.monotonic()
|
| 86 |
+
|
| 87 |
+
def consume(self, now: float) -> tuple[bool, int]:
|
| 88 |
+
"""Consume one token; return ``(allowed, retry_after_seconds)``."""
|
| 89 |
+
elapsed = now - self.updated
|
| 90 |
+
if elapsed > 0.0:
|
| 91 |
+
self.tokens = min(
|
| 92 |
+
self.capacity,
|
| 93 |
+
self.tokens + elapsed * self.refill_per_sec,
|
| 94 |
+
)
|
| 95 |
+
self.updated = now
|
| 96 |
+
|
| 97 |
+
if self.tokens >= 1.0:
|
| 98 |
+
self.tokens -= 1.0
|
| 99 |
+
return True, 0
|
| 100 |
+
|
| 101 |
+
if self.refill_per_sec <= 0.0:
|
| 102 |
+
return False, 3600
|
| 103 |
+
|
| 104 |
+
wait = (1.0 - self.tokens) / self.refill_per_sec
|
| 105 |
+
return False, max(1, math.ceil(wait))
|
| 106 |
+
|
| 107 |
+
|
| 108 |
+
class RateLimiter:
|
| 109 |
+
"""
|
| 110 |
+
Per-client token bucket.
|
| 111 |
+
|
| 112 |
+
``per_minute`` is the sustained rate; ``burst`` is the bucket size (how
|
| 113 |
+
many requests may arrive back-to-back). A non-positive ``per_minute``
|
| 114 |
+
disables the limiter.
|
| 115 |
+
"""
|
| 116 |
+
|
| 117 |
+
def __init__(
|
| 118 |
+
self,
|
| 119 |
+
per_minute: int,
|
| 120 |
+
burst: int | None = None,
|
| 121 |
+
max_clients: int = 10_000,
|
| 122 |
+
) -> None:
|
| 123 |
+
self.per_minute = int(per_minute)
|
| 124 |
+
self.burst = int(burst) if burst and burst > 0 else max(1, self.per_minute)
|
| 125 |
+
self.refill_per_sec = max(self.per_minute, 0) / 60.0
|
| 126 |
+
self.max_clients = max(1, int(max_clients))
|
| 127 |
+
self._buckets: dict[str, _TokenBucket] = {}
|
| 128 |
+
self._lock = threading.Lock()
|
| 129 |
+
|
| 130 |
+
@property
|
| 131 |
+
def enabled(self) -> bool:
|
| 132 |
+
return self.per_minute > 0
|
| 133 |
+
|
| 134 |
+
def check(self, key: str) -> tuple[bool, int]:
|
| 135 |
+
"""Return ``(allowed, retry_after_seconds)`` for ``key``."""
|
| 136 |
+
if not self.enabled:
|
| 137 |
+
return True, 0
|
| 138 |
+
|
| 139 |
+
now = time.monotonic()
|
| 140 |
+
with self._lock:
|
| 141 |
+
bucket = self._buckets.get(key)
|
| 142 |
+
if bucket is None:
|
| 143 |
+
if len(self._buckets) >= self.max_clients:
|
| 144 |
+
self._prune(now)
|
| 145 |
+
bucket = _TokenBucket(self.burst, self.refill_per_sec)
|
| 146 |
+
self._buckets[key] = bucket
|
| 147 |
+
return bucket.consume(now)
|
| 148 |
+
|
| 149 |
+
def _prune(self, now: float) -> None:
|
| 150 |
+
"""Drop full, idle buckets; clear everything if still at capacity."""
|
| 151 |
+
stale = [
|
| 152 |
+
key for key, bucket in self._buckets.items()
|
| 153 |
+
if now - bucket.updated > 300.0 and bucket.tokens >= bucket.capacity
|
| 154 |
+
]
|
| 155 |
+
for key in stale:
|
| 156 |
+
self._buckets.pop(key, None)
|
| 157 |
+
|
| 158 |
+
if len(self._buckets) >= self.max_clients:
|
| 159 |
+
# Pathological churn (e.g. spoofed X-Forwarded-For). Resetting is
|
| 160 |
+
# safer than growing without bound; normal clients refill normally.
|
| 161 |
+
self._buckets.clear()
|
| 162 |
+
|
| 163 |
+
|
| 164 |
+
# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 165 |
+
# Middleware
|
| 166 |
+
# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 167 |
+
|
| 168 |
+
def _extract_api_key(request: Request) -> str:
|
| 169 |
+
"""Read a Bearer token or X-API-Key header (Bearer wins)."""
|
| 170 |
+
authorization = request.headers.get("authorization", "")
|
| 171 |
+
if authorization.lower().startswith("bearer "):
|
| 172 |
+
return authorization[7:].strip()
|
| 173 |
+
return request.headers.get("x-api-key", "").strip()
|
| 174 |
+
|
| 175 |
+
|
| 176 |
+
def _client_key(request: Request, api_key: str) -> str:
|
| 177 |
+
"""
|
| 178 |
+
Identify a rate-limit bucket.
|
| 179 |
+
|
| 180 |
+
Authenticated callers are bucketed by a hash of their key so NATed clients
|
| 181 |
+
do not share a quota. Anonymous callers are bucketed by IP. Proxy headers
|
| 182 |
+
are only trusted when explicitly enabled, because they are trivially
|
| 183 |
+
spoofable otherwise.
|
| 184 |
+
"""
|
| 185 |
+
if api_key:
|
| 186 |
+
return "key:" + hashlib.sha256(api_key.encode("utf-8")).hexdigest()
|
| 187 |
+
|
| 188 |
+
if _env_bool("TRUST_PROXY_HEADERS", False):
|
| 189 |
+
forwarded = request.headers.get("x-forwarded-for", "")
|
| 190 |
+
if forwarded:
|
| 191 |
+
return "ip:" + forwarded.split(",", 1)[0].strip()
|
| 192 |
+
|
| 193 |
+
client = getattr(request, "client", None)
|
| 194 |
+
host = getattr(client, "host", None) if client is not None else None
|
| 195 |
+
return "ip:" + (host or "unknown")
|
| 196 |
+
|
| 197 |
+
|
| 198 |
+
def _is_exempt(path: str) -> bool:
|
| 199 |
+
return (
|
| 200 |
+
path in _EXEMPT_PATHS
|
| 201 |
+
or path.startswith("/docs/")
|
| 202 |
+
or path.startswith("/redoc/")
|
| 203 |
+
)
|
| 204 |
+
|
| 205 |
+
|
| 206 |
+
def _apply_headers(response: Response) -> Response:
|
| 207 |
+
for name, value in _SECURITY_HEADERS.items():
|
| 208 |
+
# setdefault preserves deliberate values such as the image cache header.
|
| 209 |
+
response.headers.setdefault(name, value)
|
| 210 |
+
return response
|
| 211 |
+
|
| 212 |
+
|
| 213 |
+
class SecurityMiddleware(BaseHTTPMiddleware):
|
| 214 |
+
"""Optional Bearer auth + per-client rate limiting + security headers."""
|
| 215 |
+
|
| 216 |
+
def __init__(
|
| 217 |
+
self,
|
| 218 |
+
app,
|
| 219 |
+
api_key: str = "",
|
| 220 |
+
rate_limiter: RateLimiter | None = None,
|
| 221 |
+
) -> None:
|
| 222 |
+
super().__init__(app)
|
| 223 |
+
self.api_key = api_key
|
| 224 |
+
self.rate_limiter = rate_limiter
|
| 225 |
+
|
| 226 |
+
async def dispatch(self, request: Request, call_next):
|
| 227 |
+
path = request.url.path
|
| 228 |
+
|
| 229 |
+
# CORS preflight must reach CORSMiddleware, and probes/docs stay open.
|
| 230 |
+
if request.method == "OPTIONS" or _is_exempt(path):
|
| 231 |
+
return _apply_headers(await call_next(request))
|
| 232 |
+
|
| 233 |
+
provided_key = _extract_api_key(request)
|
| 234 |
+
|
| 235 |
+
if self.api_key:
|
| 236 |
+
if not provided_key or not hmac.compare_digest(
|
| 237 |
+
provided_key.encode("utf-8"),
|
| 238 |
+
self.api_key.encode("utf-8"),
|
| 239 |
+
):
|
| 240 |
+
return _apply_headers(JSONResponse(
|
| 241 |
+
status_code=401,
|
| 242 |
+
content={"detail": "Invalid or missing API key."},
|
| 243 |
+
headers={"WWW-Authenticate": "Bearer"},
|
| 244 |
+
))
|
| 245 |
+
|
| 246 |
+
if self.rate_limiter is not None:
|
| 247 |
+
# When auth is disabled, ignore client-supplied key headers for
|
| 248 |
+
# bucketing: otherwise rotating a fake key bypasses the limit.
|
| 249 |
+
bucket_identity = provided_key if self.api_key else ""
|
| 250 |
+
allowed, retry_after = self.rate_limiter.check(
|
| 251 |
+
_client_key(request, bucket_identity)
|
| 252 |
+
)
|
| 253 |
+
if not allowed:
|
| 254 |
+
return _apply_headers(JSONResponse(
|
| 255 |
+
status_code=429,
|
| 256 |
+
content={"detail": "Rate limit exceeded. Retry later."},
|
| 257 |
+
headers={"Retry-After": str(retry_after)},
|
| 258 |
+
))
|
| 259 |
+
|
| 260 |
+
return _apply_headers(await call_next(request))
|
| 261 |
+
|
| 262 |
+
|
| 263 |
+
def install_security(
|
| 264 |
+
app: FastAPI,
|
| 265 |
+
*,
|
| 266 |
+
api_key: str | None = None,
|
| 267 |
+
rate_limit_per_minute: int | None = None,
|
| 268 |
+
rate_limit_burst: int | None = None,
|
| 269 |
+
) -> None:
|
| 270 |
+
"""
|
| 271 |
+
Attach :class:`SecurityMiddleware` to ``app``.
|
| 272 |
+
|
| 273 |
+
Values default to the environment at call time (not import time) so tests
|
| 274 |
+
and one-off deployments can override them. Call this **before**
|
| 275 |
+
``app.add_middleware(CORSMiddleware, ...)`` so CORS remains outermost.
|
| 276 |
+
"""
|
| 277 |
+
if api_key is None:
|
| 278 |
+
api_key = os.getenv("SENTINEL_API_KEY", "").strip()
|
| 279 |
+
|
| 280 |
+
if rate_limit_per_minute is None:
|
| 281 |
+
rate_limit_per_minute = _env_int("RATE_LIMIT_PER_MINUTE", 60)
|
| 282 |
+
|
| 283 |
+
if rate_limit_burst is None:
|
| 284 |
+
rate_limit_burst = _env_int("RATE_LIMIT_BURST", 20)
|
| 285 |
+
|
| 286 |
+
limiter = (
|
| 287 |
+
RateLimiter(rate_limit_per_minute, rate_limit_burst)
|
| 288 |
+
if rate_limit_per_minute > 0
|
| 289 |
+
else None
|
| 290 |
+
)
|
| 291 |
+
|
| 292 |
+
app.add_middleware(
|
| 293 |
+
SecurityMiddleware,
|
| 294 |
+
api_key=api_key,
|
| 295 |
+
rate_limiter=limiter,
|
| 296 |
+
)
|