sentinel-api 1.0.3__py3-none-any.whl

sentinel_api/__init__.py

@@ -0,0 +1,17 @@
+"""SentinelAPI package exports."""
+
+from sentinel_api.sdk_deployer import (
+    deploy_foundation,
+    deploy_full,
+    deploy_stack,
+    teardown_foundation,
+    teardown_stack,
+)
+
+__all__ = [
+    "deploy_foundation",
+    "deploy_full",
+    "deploy_stack",
+    "teardown_foundation",
+    "teardown_stack",
+]

sentinel_api/config.py

@@ -0,0 +1,228 @@
+"""Central application configuration for SentinelAPI.
+
+Environment variables are mapped into a typed settings object and exposed
+through the module-level `settings` singleton.
+"""
+
+import os
+from pathlib import Path
+
+from pydantic import AliasChoices, Field, field_validator, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+_ENV_PREFIX = "SENTINEL_API_"
+
+_PRESET_DEFAULTS: dict[str, dict[str, str]] = {
+    "cost": {
+        "FARGATE_CPU": "256",
+        "FARGATE_MEMORY_MIB": "512",
+        "ECS_DESIRED_COUNT": "1",
+        "LOG_RETENTION_DAYS": "7",
+        "REQUEST_TIMEOUT_SECONDS": "10",
+        "RATE_LIMIT_CAPACITY": "100",
+        "RATE_LIMIT_REFILL_RATE": "1.0",
+        "ANOMALY_THRESHOLD": "8.0",
+        "ANOMALY_MIN_REQUESTS": "40",
+        "ANOMALY_AUTO_BLOCK": "true",
+        "ANOMALY_AUTO_BLOCK_TTL_SECONDS": "3600",
+        "JWT_ALGORITHM": "HS256",
+    },
+    "performance": {
+        "FARGATE_CPU": "1024",
+        "FARGATE_MEMORY_MIB": "2048",
+        "ECS_DESIRED_COUNT": "2",
+        "LOG_RETENTION_DAYS": "30",
+        "REQUEST_TIMEOUT_SECONDS": "8",
+        "RATE_LIMIT_CAPACITY": "300",
+        "RATE_LIMIT_REFILL_RATE": "5.0",
+        "ANOMALY_THRESHOLD": "5.0",
+        "ANOMALY_MIN_REQUESTS": "60",
+        "ANOMALY_AUTO_BLOCK": "true",
+        "ANOMALY_AUTO_BLOCK_TTL_SECONDS": "3600",
+        "JWT_ALGORITHM": "HS256",
+    },
+}
+
+
+def _read_env_file(path: Path) -> dict[str, str]:
+    """Parse a dotenv-style file into key/value pairs."""
+    if not path.exists():
+        return {}
+
+    values: dict[str, str] = {}
+    with path.open(encoding="utf-8") as handle:
+        for raw_line in handle:
+            line = raw_line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, value = line.split("=", 1)
+            values[key.strip()] = value.strip().strip("'").strip('"')
+    return values
+
+
+def _apply_layered_env(project_root: Path | None = None) -> None:
+    """Load `.env` while respecting existing OS env vars."""
+    root = project_root or Path(__file__).resolve().parents[2]
+    external_env_keys = set(os.environ.keys())
+
+    base_values = _read_env_file(root / ".env")
+    for key, value in base_values.items():
+        if key not in external_env_keys:
+            os.environ[key] = value
+
+
+def _normalize_optimize_for(raw_value: str | None) -> str:
+    normalized = (raw_value or "cost").strip().lower()
+    if normalized in _PRESET_DEFAULTS:
+        return normalized
+    return "cost"
+
+
+def _apply_optimization_defaults() -> None:
+    """Apply optimization preset defaults without overriding explicit values."""
+    optimize_for = _normalize_optimize_for(
+        os.environ.get(f"{_ENV_PREFIX}OPTIMIZE_FOR") or os.environ.get("OPTIMIZE_FOR")
+    )
+
+    prefixed_optimize_key = f"{_ENV_PREFIX}OPTIMIZE_FOR"
+    if prefixed_optimize_key not in os.environ and "OPTIMIZE_FOR" not in os.environ:
+        os.environ[prefixed_optimize_key] = optimize_for
+
+    preset_values = _PRESET_DEFAULTS[optimize_for]
+    for key, value in preset_values.items():
+        prefixed_key = f"{_ENV_PREFIX}{key}"
+        # Preserve explicit shell/env/.env values (prefixed or legacy key names).
+        if prefixed_key in os.environ or key in os.environ:
+            continue
+        os.environ[prefixed_key] = value
+
+
+_apply_layered_env()
+_apply_optimization_defaults()
+
+
+def _env_aliases(name: str) -> AliasChoices:
+    """Accept prefixed env var first, with legacy fallback for compatibility."""
+    return AliasChoices(f"{_ENV_PREFIX}{name}", name)
+
+
+class Settings(BaseSettings):
+    """Pydantic settings model for runtime and infrastructure tuning."""
+
+    model_config = SettingsConfigDict(extra="ignore")
+
+    app_name: str = Field(default="SentinelAPI", validation_alias=_env_aliases("APP_NAME"))
+    log_level: str = Field(default="INFO", validation_alias=_env_aliases("LOG_LEVEL"))
+
+    optimize_for: str = Field(default="cost", validation_alias=_env_aliases("OPTIMIZE_FOR"))
+    fargate_cpu: int = Field(default=256, validation_alias=_env_aliases("FARGATE_CPU"))
+
+    @field_validator("optimize_for")
+    @classmethod
+    def _validate_optimize_for(cls, value: str) -> str:
+        normalized = value.strip().lower()
+        if normalized not in _PRESET_DEFAULTS:
+            raise ValueError("SENTINEL_API_OPTIMIZE_FOR must be one of: cost, performance")
+        return normalized
+
+    fargate_memory_mib: int = Field(
+        default=512,
+        validation_alias=_env_aliases("FARGATE_MEMORY_MIB"),
+    )
+    ecs_desired_count: int = Field(default=1, validation_alias=_env_aliases("ECS_DESIRED_COUNT"))
+    log_retention_days: int = Field(default=7, validation_alias=_env_aliases("LOG_RETENTION_DAYS"))
+
+    upstream_base_url: str = Field(
+        default="",
+        validation_alias=_env_aliases("UPSTREAM_BASE_URL"),
+    )
+    request_timeout_seconds: float = Field(
+        default=10.0,
+        validation_alias=_env_aliases("REQUEST_TIMEOUT_SECONDS"),
+    )
+
+    jwt_algorithm: str = Field(default="HS256", validation_alias=_env_aliases("JWT_ALGORITHM"))
+    jwt_issuer: str | None = Field(default=None, validation_alias=_env_aliases("JWT_ISSUER"))
+    jwt_audience: str | None = Field(default=None, validation_alias=_env_aliases("JWT_AUDIENCE"))
+    jwt_jwks_url: str | None = Field(default=None, validation_alias=_env_aliases("JWT_JWKS_URL"))
+    jwt_jwks_cache_ttl_seconds: int = Field(
+        default=300,
+        validation_alias=_env_aliases("JWT_JWKS_CACHE_TTL_SECONDS"),
+    )
+    jwt_secret_key: str | None = Field(
+        default=None,
+        validation_alias=_env_aliases("JWT_SECRET_KEY"),
+    )
+    jwt_public_key: str | None = Field(
+        default=None,
+        validation_alias=_env_aliases("JWT_PUBLIC_KEY"),
+    )
+
+    redis_url: str = Field(
+        default="redis://localhost:6379/0",
+        validation_alias=_env_aliases("REDIS_URL"),
+    )
+    rate_limit_capacity: int = Field(
+        default=100,
+        validation_alias=_env_aliases("RATE_LIMIT_CAPACITY"),
+    )
+    rate_limit_refill_rate: float = Field(
+        default=1.0,
+        validation_alias=_env_aliases("RATE_LIMIT_REFILL_RATE"),
+    )
+    blocklist_prefix: str = Field(
+        default="sentinel:blocklist",
+        validation_alias=_env_aliases("BLOCKLIST_PREFIX"),
+    )
+
+    aws_region: str = Field(default="us-west-2", validation_alias=_env_aliases("AWS_REGION"))
+    ddb_table_name: str = Field(
+        default="sentinel-request-logs",
+        validation_alias=_env_aliases("DDB_TABLE_NAME"),
+    )
+    ddb_aggregate_table_name: str = Field(
+        default="sentinel-traffic-agg",
+        validation_alias=_env_aliases("DDB_AGGREGATE_TABLE_NAME"),
+    )
+    ddb_rate_limit_table_name: str = Field(
+        default="sentinel-rate-limits",
+        validation_alias=_env_aliases("DDB_RATE_LIMIT_TABLE_NAME"),
+    )
+    ddb_blocklist_table_name: str = Field(
+        default="sentinel-blocklist",
+        validation_alias=_env_aliases("DDB_BLOCKLIST_TABLE_NAME"),
+    )
+    sns_topic_arn: str | None = Field(default=None, validation_alias=_env_aliases("SNS_TOPIC_ARN"))
+
+    anomaly_auto_block: bool = Field(
+        default=True,
+        validation_alias=_env_aliases("ANOMALY_AUTO_BLOCK"),
+    )
+    anomaly_auto_block_ttl_seconds: int = Field(
+        default=3600,
+        validation_alias=_env_aliases("ANOMALY_AUTO_BLOCK_TTL_SECONDS"),
+    )
+    anomaly_threshold: float = Field(
+        default=8.0,
+        validation_alias=_env_aliases("ANOMALY_THRESHOLD"),
+    )
+    anomaly_min_requests: int = Field(
+        default=40,
+        validation_alias=_env_aliases("ANOMALY_MIN_REQUESTS"),
+    )
+
+    @model_validator(mode="after")
+    def _validate_auth_configuration(self) -> "Settings":
+        has_secret = bool((self.jwt_secret_key or "").strip())
+        has_public = bool((self.jwt_public_key or "").strip())
+        has_jwks = bool((self.jwt_jwks_url or "").strip())
+        if not (has_secret or has_public or has_jwks):
+            raise ValueError(
+                "JWT verification is not configured. Define at least one of: "
+                "SENTINEL_API_JWT_SECRET_KEY, SENTINEL_API_JWT_PUBLIC_KEY, "
+                "SENTINEL_API_JWT_JWKS_URL."
+            )
+        return self
+
+
+settings = Settings()

sentinel_api/main.py

@@ -0,0 +1,137 @@
+"""FastAPI application entrypoint for SentinelAPI.
+
+This module wires auth, rate limiting, proxying, and request logging into a
+single API-edge service with one architecture and tunable runtime knobs.
+"""
+
+import logging
+import time
+
+import httpx
+from fastapi import Depends, FastAPI, HTTPException, Request, Response
+from redis.asyncio import Redis
+
+from sentinel_api.config import settings
+from sentinel_api.models.security import AuthContext
+from sentinel_api.services.auth import AuthError, JWTAuthenticator
+from sentinel_api.services.proxy import forward_request
+from sentinel_api.services.rate_limiter import RateLimiter as RedisRateLimiter
+from sentinel_api.services.rate_limiter_base import RateLimiterProtocol
+from sentinel_api.services.request_logger import build_request_logger
+
+logging.basicConfig(level=getattr(logging, settings.log_level.upper(), logging.INFO))
+logger = logging.getLogger(__name__)
+
+app = FastAPI(title=settings.app_name)
+
+
+async def _build_rate_limiter() -> tuple[RateLimiterProtocol, Redis | None]:
+    """Instantiate Redis-backed rate limiter."""
+    redis_client = Redis.from_url(settings.redis_url, decode_responses=True)
+    rate_limiter = RedisRateLimiter(redis_client=redis_client, settings=settings)
+    return rate_limiter, redis_client
+
+
+@app.on_event("startup")
+async def startup() -> None:
+    """Initialize shared clients/services and store them on app state."""
+    rate_limiter, redis_client = await _build_rate_limiter()
+    app.state.http_client = httpx.AsyncClient(timeout=settings.request_timeout_seconds)
+    app.state.redis_client = redis_client
+    app.state.rate_limiter = rate_limiter
+    app.state.request_logger = build_request_logger(settings=settings)
+    app.state.authenticator = JWTAuthenticator(settings=settings)
+
+    logger.info(
+        "SentinelAPI startup rate_limit_backend=redis request_log_backend=dynamodb",
+    )
+
+
+@app.on_event("shutdown")
+async def shutdown() -> None:
+    """Close network clients gracefully on process shutdown."""
+    await app.state.http_client.aclose()
+    if app.state.redis_client is not None:
+        await app.state.redis_client.aclose()
+
+
+def extract_bearer_token(request: Request) -> str:
+    """Extract Bearer token from Authorization header or raise 401."""
+    header = request.headers.get("authorization", "")
+    if not header.lower().startswith("bearer "):
+        raise HTTPException(status_code=401, detail="Missing Bearer token")
+    return header[7:].strip()
+
+
+async def authenticate(request: Request) -> AuthContext:
+    """Validate JWT and return authenticated user context."""
+    token = extract_bearer_token(request)
+    try:
+        return app.state.authenticator.decode_token(token)
+    except AuthError as exc:
+        raise HTTPException(status_code=401, detail=str(exc)) from exc
+
+
+@app.get("/health")
+async def health() -> dict[str, str]:
+    """Liveness endpoint that also returns active backend wiring info."""
+    return {
+        "status": "ok",
+        "rateLimitBackend": "redis",
+        "requestLogBackend": "dynamodb",
+    }
+
+
+@app.get("/auth/verify")
+async def auth_verify(auth: AuthContext = Depends(authenticate)) -> dict[str, str | bool | None]:
+    """Return auth context for quick JWT verification testing."""
+    return {
+        "authenticated": True,
+        "userId": auth.user_id,
+        "tokenId": auth.token_id,
+    }
+
+
+@app.api_route("/proxy/{full_path:path}", methods=["GET", "POST", "PUT", "PATCH", "DELETE"])
+async def proxy(
+    full_path: str,
+    request: Request,
+    auth: AuthContext = Depends(authenticate),
+) -> Response:
+    """Authenticate, rate-limit, proxy upstream call, and persist request telemetry."""
+    start = time.perf_counter()
+    allowed, tokens_remaining = await app.state.rate_limiter.allow_request(auth.user_id)
+
+    if not allowed:
+        detail = "User blocked" if tokens_remaining is None else "Rate limit exceeded"
+        raise HTTPException(status_code=429, detail=detail)
+
+    response = await forward_request(
+        request=request,
+        client=app.state.http_client,
+        upstream_base_url=settings.upstream_base_url,
+    )
+
+    latency_ms = (time.perf_counter() - start) * 1000
+    client_host = request.client.host if request.client else "unknown"
+    user_agent = request.headers.get("user-agent", "unknown")
+
+    try:
+        await app.state.request_logger.log_request(
+            user_id=auth.user_id,
+            endpoint=f"/{full_path}",
+            latency_ms=latency_ms,
+            status_code=response.status_code,
+            ip_address=client_host,
+            user_agent=user_agent,
+        )
+    except Exception as exc:  # noqa: BLE001
+        logger.warning(
+            "Request logging failed for user=%s endpoint=/%s: %s",
+            auth.user_id,
+            full_path,
+            exc,
+        )
+
+    response.headers["x-rate-limit-remaining"] = str(int(tokens_remaining or 0))
+    return response

sentinel_api/models/security.py

@@ -0,0 +1,7 @@
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class AuthContext:
+    user_id: str
+    token_id: str | None