StillWorking commited on
Commit
19d3a8d
Β·
verified Β·
1 Parent(s): 6d546ec

Upload backend/core/security.py with huggingface_hub

Browse files
Files changed (1) hide show
  1. 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
+ )