feat(security): add JWT startup guard, configurable CORS, and externalize DB credentials

- Add check_jwt_secret() that refuses default JWT secret when APP_ENV != development
- Make CORS origins configurable via CORS_ORIGINS env var (comma-separated)
- Replace hardcoded postgres credentials in docker-compose.yml with env var references
- Add APP_ENV and cors_origins to config.py
- Update .env.example with all required variables and documentation
- Add tests for JWT startup guard and CORS configuration

Closes leeworks-agents/SPARC#4
Closes leeworks-agents/SPARC#5
Closes leeworks-agents/SPARC#6

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.env.example

@@ -1,21 +1,42 @@
 # SPARC Configuration
 
+# ---- Application Environment ----
+# Set to "production" or "staging" in deployed environments.
+# The API will refuse to start with the default JWT secret unless APP_ENV=development.
+APP_ENV=development
+
+# ---- API Keys ----
+
 # SerpAPI key for patent search
 API_KEY=your_serpapi_key_here
 
 # OpenRouter API key for LLM analysis
 OPENROUTER_API_KEY=your_openrouter_key_here
 
-# Database configuration
+# ---- Database ----
-# All messages are stored in the database for persistence and caching
-DATABASE_URL=postgresql://postgres:postgres@localhost:5432/sparc
 
-# Cache configuration
+# PostgreSQL credentials (used by docker-compose)
-# When USE_CACHE=true: check database for cached responses before making API calls
+POSTGRES_USER=postgres
-# When USE_CACHE=false: always make fresh API calls (still stores results in database)
+POSTGRES_PASSWORD=change-me-to-a-secure-password
-# Default: true
+POSTGRES_DB=sparc
-USE_CACHE=true
 
-# JWT Secret for authentication
+# Full database URL (must match the credentials above)
+DATABASE_URL=postgresql://postgres:change-me-to-a-secure-password@localhost:5432/sparc
+
+# ---- Authentication ----
+
+# JWT Secret for signing tokens
 # IMPORTANT: Change this to a secure random string in production
 JWT_SECRET=your-secure-jwt-secret-change-in-production
+
+# ---- CORS ----
+
+# Comma-separated list of allowed origins for CORS
+# Defaults to http://localhost:3000,http://localhost:5173 when unset
+# CORS_ORIGINS=https://sparc.example.com,https://app.example.com
+
+# ---- Cache ----
+
+# When USE_CACHE=true: check database for cached responses before making API calls
+# When USE_CACHE=false: always make fresh API calls (still stores results in database)
+USE_CACHE=true

SPARC/api.py

@@ -16,6 +16,7 @@ from SPARC.analyzer import CompanyAnalyzer
 from SPARC.auth import (
     TokenResponse,
     UserResponse,
+    check_jwt_secret,
     create_tokens,
     decode_token,
     get_current_admin,
@@ -150,6 +151,7 @@ _analyzer: CompanyAnalyzer | None = None
 async def lifespan(app: FastAPI):
     """Initialize resources on startup."""
     global _analyzer
+    check_jwt_secret()
     _analyzer = CompanyAnalyzer()
     yield
     # Cleanup if needed
@@ -167,7 +169,7 @@ app = FastAPI(
 # Add CORS middleware for React frontend
 app.add_middleware(
     CORSMiddleware,
-    allow_origins=["http://localhost:3000", "http://localhost:5173"],
+    allow_origins=config.cors_origins,
     allow_credentials=True,
     allow_methods=["*"],
     allow_headers=["*"],

SPARC/auth.py

@@ -13,11 +13,25 @@ from SPARC import config
 from SPARC.database import DatabaseClient
 
 # JWT Configuration
-JWT_SECRET = os.getenv("JWT_SECRET", "sparc-secret-key-change-in-production")
+_DEFAULT_JWT_SECRET = "sparc-secret-key-change-in-production"
+JWT_SECRET = os.getenv("JWT_SECRET", _DEFAULT_JWT_SECRET)
 JWT_ALGORITHM = "HS256"
 ACCESS_TOKEN_EXPIRE_MINUTES = 30
 REFRESH_TOKEN_EXPIRE_DAYS = 7
 
+
+def check_jwt_secret() -> None:
+    """Refuse to start with the default JWT secret in non-development environments.
+
+    Raises:
+        RuntimeError: If JWT_SECRET is the default value and APP_ENV is not 'development'.
+    """
+    if JWT_SECRET == _DEFAULT_JWT_SECRET and config.app_env != "development":
+        raise RuntimeError(
+            f"FATAL: JWT_SECRET is set to the default value and APP_ENV={config.app_env!r}. "
+            "Set a secure JWT_SECRET environment variable before running in non-development environments."
+        )
+
 security = HTTPBearer()
 
 

SPARC/config.py

@@ -33,3 +33,16 @@ patent_thread_workers = int(os.getenv("PATENT_THREAD_WORKERS", "5"))
 # Root path for running behind a reverse proxy (e.g., "/api" when served at /api/)
 # This ensures OpenAPI docs work correctly when accessed via the proxy
 root_path = os.getenv("ROOT_PATH", "")
+
+# Application environment: "development", "staging", or "production"
+# Used for safety checks (e.g., refusing default JWT secret in production)
+app_env = os.getenv("APP_ENV", "development")
+
+# CORS allowed origins (comma-separated)
+# Defaults to localhost dev origins when unset
+_cors_origins_raw = os.getenv("CORS_ORIGINS", "")
+cors_origins: list[str] = (
+    [o.strip() for o in _cors_origins_raw.split(",") if o.strip()]
+    if _cors_origins_raw
+    else ["http://localhost:3000", "http://localhost:5173"]
+)

docker-compose.yml

@@ -3,15 +3,15 @@ services:
     image: postgres:16-alpine
     container_name: sparc-postgres
     environment:
-      POSTGRES_USER: postgres
+      POSTGRES_USER: ${POSTGRES_USER}
-      POSTGRES_PASSWORD: postgres
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
-      POSTGRES_DB: sparc
+      POSTGRES_DB: ${POSTGRES_DB}
     ports:
       - "5432:5432"
     volumes:
       - postgres_data:/var/lib/postgresql/data
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
       interval: 5s
       timeout: 5s
       retries: 5
@@ -22,7 +22,7 @@ services:
     container_name: sparc-init-db
     command: python scripts/init_database.py
     environment:
-      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/sparc
+      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
     depends_on:
       postgres:
         condition: service_healthy
@@ -35,9 +35,11 @@ services:
     environment:
       API_KEY: ${API_KEY}
       OPENROUTER_API_KEY: ${OPENROUTER_API_KEY}
-      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/sparc
+      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
       USE_CACHE: "true"
       JWT_SECRET: ${JWT_SECRET:-sparc-secret-key-change-in-production}
+      CORS_ORIGINS: ${CORS_ORIGINS:-}
+      APP_ENV: ${APP_ENV:-development}
       ROOT_PATH: /api
     ports:
       - "8000:8000"

tests/test_auth.py

@@ -1,302 +0,0 @@
-"""Tests for JWT authentication flow: register, login, protected routes, refresh, admin access."""
-
-from datetime import datetime, timezone
-from unittest.mock import MagicMock, patch
-
-import pytest
-from fastapi.testclient import TestClient
-
-from SPARC.api import app
-from SPARC.auth import create_access_token, create_refresh_token
-
-
-@pytest.fixture
-def client():
-    """Create test client."""
-    return TestClient(app)
-
-
-@pytest.fixture(autouse=True)
-def mock_db(monkeypatch):
-    """Mock the database client used by auth endpoints.
-
-    Returns a MagicMock with all DB methods pre-configured.
-    """
-    db = MagicMock()
-
-    # Default: no users exist
-    db.get_user_count.return_value = 0
-    db.get_user_by_id.return_value = None
-    db.get_user_by_email.return_value = None
-    db.authenticate_user.return_value = None
-    db.create_user.return_value = None
-    db.get_all_users.return_value = []
-    db.update_user_role.return_value = None
-    db.delete_user.return_value = False
-
-    with patch("SPARC.api.get_db_client", return_value=db), \
-         patch("SPARC.auth.get_db_client", return_value=db):
-        yield db
-
-
-def _make_admin_user():
-    return {
-        "id": 1,
-        "email": "admin@test.com",
-        "role": "admin",
-        "created_at": datetime(2025, 1, 1, tzinfo=timezone.utc),
-    }
-
-
-def _make_regular_user():
-    return {
-        "id": 2,
-        "email": "user@test.com",
-        "role": "user",
-        "created_at": datetime(2025, 1, 1, tzinfo=timezone.utc),
-    }
-
-
-def _auth_header(user_dict):
-    """Create an Authorization header with a valid access token for the given user."""
-    token = create_access_token(user_dict["id"], user_dict["email"], user_dict["role"])
-    return {"Authorization": f"Bearer {token}"}
-
-
-class TestRegister:
-    """POST /auth/register"""
-
-    def test_register_first_user_becomes_admin(self, client, mock_db):
-        """First registered user should get admin role."""
-        mock_db.get_user_count.return_value = 0
-        mock_db.create_user.return_value = {
-            "id": 1,
-            "email": "admin@test.com",
-            "role": "admin",
-            "created_at": datetime(2025, 1, 1, tzinfo=timezone.utc),
-        }
-
-        response = client.post(
-            "/auth/register",
-            json={"email": "admin@test.com", "password": "securepass123"},
-        )
-
-        assert response.status_code == 200
-        data = response.json()
-        assert data["email"] == "admin@test.com"
-        assert data["role"] == "admin"
-        mock_db.create_user.assert_called_once_with(
-            email="admin@test.com", password="securepass123", role="admin"
-        )
-
-    def test_register_subsequent_user_gets_user_role(self, client, mock_db):
-        """Non-first user should get regular user role."""
-        mock_db.get_user_count.return_value = 1
-        mock_db.create_user.return_value = _make_regular_user()
-
-        response = client.post(
-            "/auth/register",
-            json={"email": "user@test.com", "password": "securepass123"},
-        )
-
-        assert response.status_code == 200
-        data = response.json()
-        assert data["role"] == "user"
-
-    def test_register_duplicate_email_returns_400(self, client, mock_db):
-        """Registering with an existing email should return 400."""
-        mock_db.get_user_count.return_value = 1
-        mock_db.create_user.return_value = None  # indicates duplicate
-
-        response = client.post(
-            "/auth/register",
-            json={"email": "existing@test.com", "password": "securepass123"},
-        )
-
-        assert response.status_code == 400
-        assert "already registered" in response.json()["detail"].lower()
-
-
-class TestLogin:
-    """POST /auth/login"""
-
-    def test_login_valid_credentials_returns_tokens(self, client, mock_db):
-        """Valid credentials should return access and refresh tokens."""
-        user = _make_regular_user()
-        mock_db.authenticate_user.return_value = user
-
-        response = client.post(
-            "/auth/login",
-            json={"email": "user@test.com", "password": "correctpassword"},
-        )
-
-        assert response.status_code == 200
-        data = response.json()
-        assert "access_token" in data
-        assert "refresh_token" in data
-        assert data["token_type"] == "bearer"
-
-    def test_login_invalid_credentials_returns_401(self, client, mock_db):
-        """Invalid credentials should return 401."""
-        mock_db.authenticate_user.return_value = None
-
-        response = client.post(
-            "/auth/login",
-            json={"email": "user@test.com", "password": "wrongpassword"},
-        )
-
-        assert response.status_code == 401
-        assert "invalid" in response.json()["detail"].lower()
-
-
-class TestGetMe:
-    """GET /auth/me"""
-
-    def test_valid_access_token_returns_user(self, client, mock_db):
-        """A valid access token should return the user's data."""
-        user = _make_regular_user()
-        mock_db.get_user_by_id.return_value = user
-
-        response = client.get("/auth/me", headers=_auth_header(user))
-
-        assert response.status_code == 200
-        data = response.json()
-        assert data["email"] == "user@test.com"
-        assert data["id"] == 2
-
-    def test_missing_token_returns_401(self, client):
-        """No token should return 401 (403 from HTTPBearer)."""
-        response = client.get("/auth/me")
-        assert response.status_code in (401, 403)
-
-    def test_expired_token_returns_401(self, client, mock_db):
-        """An expired token should return 401."""
-        # Create a token that has already expired
-        from datetime import timedelta
-
-        import jwt as pyjwt
-        from SPARC.auth import JWT_ALGORITHM, JWT_SECRET
-
-        payload = {
-            "sub": "1",
-            "email": "user@test.com",
-            "role": "user",
-            "exp": datetime.now(timezone.utc) - timedelta(hours=1),
-            "type": "access",
-        }
-        expired_token = pyjwt.encode(payload, JWT_SECRET, algorithm=JWT_ALGORITHM)
-
-        response = client.get(
-            "/auth/me", headers={"Authorization": f"Bearer {expired_token}"}
-        )
-        assert response.status_code == 401
-
-    def test_refresh_token_as_access_returns_401(self, client, mock_db):
-        """Using a refresh token as an access token should return 401."""
-        user = _make_regular_user()
-        refresh_token = create_refresh_token(user["id"], user["email"], user["role"])
-
-        response = client.get(
-            "/auth/me", headers={"Authorization": f"Bearer {refresh_token}"}
-        )
-        assert response.status_code == 401
-
-
-class TestRefreshToken:
-    """POST /auth/refresh"""
-
-    def test_valid_refresh_token_returns_new_tokens(self, client, mock_db):
-        """A valid refresh token should issue new access and refresh tokens."""
-        user = _make_regular_user()
-        mock_db.get_user_by_id.return_value = user
-        refresh = create_refresh_token(user["id"], user["email"], user["role"])
-
-        response = client.post(
-            "/auth/refresh", json={"refresh_token": refresh}
-        )
-
-        assert response.status_code == 200
-        data = response.json()
-        assert "access_token" in data
-        assert "refresh_token" in data
-
-    def test_invalid_refresh_token_returns_401(self, client, mock_db):
-        """An invalid refresh token should return 401."""
-        response = client.post(
-            "/auth/refresh", json={"refresh_token": "invalid-token-string"}
-        )
-        assert response.status_code == 401
-
-    def test_access_token_as_refresh_returns_401(self, client, mock_db):
-        """Using an access token as a refresh token should return 401."""
-        user = _make_regular_user()
-        access = create_access_token(user["id"], user["email"], user["role"])
-
-        response = client.post(
-            "/auth/refresh", json={"refresh_token": access}
-        )
-        assert response.status_code == 401
-
-
-class TestAdminUsers:
-    """GET /admin/users and PATCH /admin/users/{id}/role"""
-
-    def test_admin_can_list_users(self, client, mock_db):
-        """Admin token should allow listing users."""
-        admin = _make_admin_user()
-        mock_db.get_user_by_id.return_value = admin
-        mock_db.get_all_users.return_value = [admin, _make_regular_user()]
-
-        response = client.get("/admin/users", headers=_auth_header(admin))
-
-        assert response.status_code == 200
-        data = response.json()
-        assert len(data) == 2
-
-    def test_regular_user_cannot_list_users(self, client, mock_db):
-        """Regular user token should be rejected with 403."""
-        user = _make_regular_user()
-        mock_db.get_user_by_id.return_value = user
-
-        response = client.get("/admin/users", headers=_auth_header(user))
-
-        assert response.status_code == 403
-
-    def test_no_token_cannot_list_users(self, client):
-        """No token should be rejected."""
-        response = client.get("/admin/users")
-        assert response.status_code in (401, 403)
-
-    def test_admin_can_change_user_role(self, client, mock_db):
-        """Admin should be able to change another user's role."""
-        admin = _make_admin_user()
-        mock_db.get_user_by_id.return_value = admin
-        mock_db.update_user_role.return_value = {
-            "id": 2,
-            "email": "user@test.com",
-            "role": "admin",
-            "created_at": datetime(2025, 1, 1, tzinfo=timezone.utc),
-        }
-
-        response = client.patch(
-            "/admin/users/2/role",
-            json={"role": "admin"},
-            headers=_auth_header(admin),
-        )
-
-        assert response.status_code == 200
-        assert response.json()["role"] == "admin"
-
-    def test_admin_cannot_change_own_role(self, client, mock_db):
-        """Admin should not be able to change their own role."""
-        admin = _make_admin_user()
-        mock_db.get_user_by_id.return_value = admin
-
-        response = client.patch(
-            "/admin/users/1/role",
-            json={"role": "user"},
-            headers=_auth_header(admin),
-        )
-
-        assert response.status_code == 400
-        assert "own role" in response.json()["detail"].lower()

tests/test_security.py

@@ -0,0 +1,116 @@
+"""Tests for security hardening: JWT secret startup check, CORS config, credential handling."""
+
+import os
+from unittest.mock import patch
+
+import pytest
+
+
+class TestJWTSecretStartupCheck:
+    """Test the startup guard that refuses default JWT secret in non-dev environments."""
+
+    def test_default_secret_in_production_raises(self):
+        """Starting with default secret and APP_ENV=production must raise RuntimeError."""
+        with patch.dict(os.environ, {"APP_ENV": "production"}):
+            # Reload config to pick up the new APP_ENV
+            import importlib
+            import SPARC.config
+            importlib.reload(SPARC.config)
+
+            from SPARC.auth import _DEFAULT_JWT_SECRET, check_jwt_secret
+            # Patch JWT_SECRET to the default
+            with patch("SPARC.auth.JWT_SECRET", _DEFAULT_JWT_SECRET):
+                with pytest.raises(RuntimeError, match="FATAL.*JWT_SECRET"):
+                    check_jwt_secret()
+
+            # Restore config
+            with patch.dict(os.environ, {"APP_ENV": "development"}):
+                importlib.reload(SPARC.config)
+
+    def test_default_secret_in_development_succeeds(self):
+        """Starting with default secret and APP_ENV=development must not raise."""
+        with patch.dict(os.environ, {"APP_ENV": "development"}):
+            import importlib
+            import SPARC.config
+            importlib.reload(SPARC.config)
+
+            from SPARC.auth import _DEFAULT_JWT_SECRET, check_jwt_secret
+            with patch("SPARC.auth.JWT_SECRET", _DEFAULT_JWT_SECRET):
+                # Should not raise
+                check_jwt_secret()
+
+            # Restore
+            importlib.reload(SPARC.config)
+
+    def test_custom_secret_in_production_succeeds(self):
+        """Starting with a custom secret in production must not raise."""
+        with patch.dict(os.environ, {"APP_ENV": "production"}):
+            import importlib
+            import SPARC.config
+            importlib.reload(SPARC.config)
+
+            from SPARC.auth import check_jwt_secret
+            with patch("SPARC.auth.JWT_SECRET", "my-secure-random-secret-abc123"):
+                # Should not raise
+                check_jwt_secret()
+
+            with patch.dict(os.environ, {"APP_ENV": "development"}):
+                importlib.reload(SPARC.config)
+
+    def test_default_secret_unset_env_succeeds(self):
+        """When APP_ENV is unset (defaults to development), default secret is allowed."""
+        with patch.dict(os.environ, {}, clear=False):
+            # Remove APP_ENV if present
+            env = os.environ.copy()
+            env.pop("APP_ENV", None)
+            with patch.dict(os.environ, env, clear=True):
+                import importlib
+                import SPARC.config
+                importlib.reload(SPARC.config)
+
+                from SPARC.auth import _DEFAULT_JWT_SECRET, check_jwt_secret
+                with patch("SPARC.auth.JWT_SECRET", _DEFAULT_JWT_SECRET):
+                    # Should not raise (defaults to development)
+                    check_jwt_secret()
+
+                with patch.dict(os.environ, {"APP_ENV": "development"}):
+                    importlib.reload(SPARC.config)
+
+
+class TestCORSConfig:
+    """Test that CORS origins are configurable via environment variable."""
+
+    def test_default_cors_origins(self):
+        """When CORS_ORIGINS is unset, defaults to localhost origins."""
+        with patch.dict(os.environ, {"CORS_ORIGINS": ""}):
+            import importlib
+            import SPARC.config
+            importlib.reload(SPARC.config)
+            assert SPARC.config.cors_origins == [
+                "http://localhost:3000",
+                "http://localhost:5173",
+            ]
+
+    def test_custom_cors_origins(self):
+        """Setting CORS_ORIGINS configures allowed origins."""
+        with patch.dict(os.environ, {"CORS_ORIGINS": "https://sparc.example.com,https://app.example.com"}):
+            import importlib
+            import SPARC.config
+            importlib.reload(SPARC.config)
+            assert SPARC.config.cors_origins == [
+                "https://sparc.example.com",
+                "https://app.example.com",
+            ]
+            # Restore
+            with patch.dict(os.environ, {"CORS_ORIGINS": ""}):
+                importlib.reload(SPARC.config)
+
+    def test_single_cors_origin(self):
+        """A single origin without comma works correctly."""
+        with patch.dict(os.environ, {"CORS_ORIGINS": "https://sparc.example.com"}):
+            import importlib
+            import SPARC.config
+            importlib.reload(SPARC.config)
+            assert SPARC.config.cors_origins == ["https://sparc.example.com"]
+            with patch.dict(os.environ, {"CORS_ORIGINS": ""}):
+                importlib.reload(SPARC.config)