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,
@@ -114,7 +115,8 @@ class AnalyticsResponse(BaseModel):
     period_days: int
 
 
-# Job counter for generating unique IDs (the actual state is in PostgreSQL)
+# In-memory job storage (for demo; production would use Redis/DB)
+_jobs: dict[str, JobStatus] = {}
 _job_counter = 0
 
 
@@ -147,19 +149,10 @@ _analyzer: CompanyAnalyzer | None = None
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    """Initialize resources on startup, clean up on shutdown."""
+    """Initialize resources on startup."""
     global _analyzer
+    check_jwt_secret()
     _analyzer = CompanyAnalyzer()
-    # Mark any jobs that were running/pending before the restart as failed
-    from SPARC.database import DatabaseClient
-    _db = DatabaseClient(config.database_url)
-    _db.connect()
-    _db.initialize_schema()
-    stale = _db.mark_stale_jobs_failed()
-    if stale:
-        import logging
-        logging.getLogger(__name__).warning("Marked %d stale jobs as failed on startup", stale)
-    _db.close()
     yield
     # Cleanup if needed
     _analyzer = None
@@ -176,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=["*"],
@@ -431,52 +424,20 @@ async def analyze_companies_batch(
     return _convert_batch_result(result)
 
 
-def _get_job_db() -> "DatabaseClient":
-    """Get a DatabaseClient for job persistence."""
-    from SPARC.database import DatabaseClient
-    db = DatabaseClient(config.database_url)
-    return db
-
-
-def _job_row_to_status(row: dict) -> JobStatus:
-    """Convert a database job row to a JobStatus model."""
-    import json as _json
-    result = None
-    if row.get("result_json"):
-        result_data = row["result_json"]
-        if isinstance(result_data, str):
-            result_data = _json.loads(result_data)
-        result = BatchAnalysisResponse(**result_data)
-    return JobStatus(
-        job_id=row["job_id"],
-        status=row["status"],
-        progress=row["progress"],
-        total_companies=row["total_companies"],
-        completed_companies=row["completed_companies"],
-        result=result,
-        error=row.get("error"),
-    )
-
-
 def _run_batch_job(job_id: str, companies: list[str], max_workers: int):
     """Background task for batch analysis."""
-    import json as _json
+    global _jobs, _analyzer
-    global _analyzer
-
-    db = _get_job_db()
 
     if not _analyzer:
-        db.update_job(job_id, status="failed", error="Analyzer not initialized")
+        _jobs[job_id].status = "failed"
+        _jobs[job_id].error = "Analyzer not initialized"
         return
 
-    db.update_job(job_id, status="running")
+    _jobs[job_id].status = "running"
 
     def progress_callback(company: str, completed: int, total: int):
-        db.update_job(
+        _jobs[job_id].completed_companies = completed
-            job_id,
+        _jobs[job_id].progress = int((completed / total) * 100)
-            completed_companies=completed,
-            progress=int((completed / total) * 100),
-        )
 
     try:
         result = _analyzer.analyze_companies(
@@ -484,15 +445,12 @@ def _run_batch_job(job_id: str, companies: list[str], max_workers: int):
             max_workers=max_workers,
             progress_callback=progress_callback,
         )
-        batch_response = _convert_batch_result(result)
+        _jobs[job_id].status = "completed"
-        db.update_job(
+        _jobs[job_id].progress = 100
-            job_id,
+        _jobs[job_id].result = _convert_batch_result(result)
-            status="completed",
-            progress=100,
-            result_json=_json.dumps(batch_response.model_dump(), default=str),
-        )
     except Exception as e:
-        db.update_job(job_id, status="failed", error=str(e))
+        _jobs[job_id].status = "failed"
+        _jobs[job_id].error = str(e)
 
 
 @app.post("/analyze/batch/async", response_model=JobStatus, tags=["Analysis"])
@@ -517,14 +475,19 @@ async def analyze_companies_async(
     _job_counter += 1
     job_id = f"job_{_job_counter}_{datetime.now().strftime('%Y%m%d%H%M%S')}"
 
-    db = _get_job_db()
+    _jobs[job_id] = JobStatus(
-    job_row = db.create_job(job_id=job_id, total_companies=len(request.companies))
+        job_id=job_id,
+        status="pending",
+        progress=0,
+        total_companies=len(request.companies),
+        completed_companies=0,
+    )
 
     background_tasks.add_task(
         _run_batch_job, job_id, request.companies, request.max_workers
     )
 
-    return _job_row_to_status(job_row)
+    return _jobs[job_id]
 
 
 @app.get("/jobs/{job_id}", response_model=JobStatus, tags=["Jobs"])
@@ -540,13 +503,10 @@ async def get_job_status(
     Returns:
         Current job status including progress and results when complete
     """
-    db = _get_job_db()
+    if job_id not in _jobs:
-    job_row = db.get_job(job_id)
-
-    if not job_row:
         raise HTTPException(status_code=404, detail=f"Job {job_id} not found")
 
-    return _job_row_to_status(job_row)
+    return _jobs[job_id]
 
 
 @app.get("/jobs", response_model=list[JobStatus], tags=["Jobs"])
@@ -567,6 +527,12 @@ async def list_jobs(
     Returns:
         List of job statuses
     """
-    db = _get_job_db()
+    jobs = list(_jobs.values())
-    job_rows = db.list_jobs(status=status, limit=limit)
+
-    return [_job_row_to_status(row) for row in job_rows]
+    if status:
+        jobs = [j for j in jobs if j.status == status]
+
+    # Return most recent first
+    jobs.sort(key=lambda j: j.job_id, reverse=True)
+
+    return jobs[:limit]

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"]
+)

SPARC/database.py

@@ -171,26 +171,6 @@ class DatabaseClient:
                 ON serp_queries(query_hash)
             """)
 
-            # Create jobs table for persisting async batch job state
-            cursor.execute("""
-                CREATE TABLE IF NOT EXISTS jobs (
-                    job_id VARCHAR(128) PRIMARY KEY,
-                    status VARCHAR(20) NOT NULL DEFAULT 'pending',
-                    progress INTEGER NOT NULL DEFAULT 0,
-                    total_companies INTEGER NOT NULL DEFAULT 0,
-                    completed_companies INTEGER NOT NULL DEFAULT 0,
-                    result_json JSONB,
-                    error TEXT,
-                    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-                    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-                )
-            """)
-
-            cursor.execute("""
-                CREATE INDEX IF NOT EXISTS idx_jobs_status
-                ON jobs(status)
-            """)
-
             self.conn.commit()
 
     @staticmethod
@@ -482,131 +462,6 @@ class DatabaseClient:
                 )
             conn.commit()
 
-    # Job Persistence Methods
-
-    def create_job(
-        self,
-        job_id: str,
-        total_companies: int,
-    ) -> Dict:
-        """Create a new job record.
-
-        Args:
-            job_id: Unique job identifier
-            total_companies: Number of companies in the batch
-
-        Returns:
-            Job dict
-        """
-        with self.get_conn() as conn:
-            with conn.cursor(cursor_factory=RealDictCursor) as cursor:
-                cursor.execute(
-                    """
-                    INSERT INTO jobs (job_id, status, progress, total_companies, completed_companies)
-                    VALUES (%s, 'pending', 0, %s, 0)
-                    RETURNING *
-                    """,
-                    (job_id, total_companies),
-                )
-                job = cursor.fetchone()
-            conn.commit()
-            return dict(job)
-
-    def update_job(
-        self,
-        job_id: str,
-        status: Optional[str] = None,
-        progress: Optional[int] = None,
-        completed_companies: Optional[int] = None,
-        result_json: Optional[str] = None,
-        error: Optional[str] = None,
-    ) -> Optional[Dict]:
-        """Update a job's state.
-
-        Only non-None fields are updated.
-        """
-        updates = []
-        params = []
-        if status is not None:
-            updates.append("status = %s")
-            params.append(status)
-        if progress is not None:
-            updates.append("progress = %s")
-            params.append(progress)
-        if completed_companies is not None:
-            updates.append("completed_companies = %s")
-            params.append(completed_companies)
-        if result_json is not None:
-            updates.append("result_json = %s")
-            params.append(result_json)
-        if error is not None:
-            updates.append("error = %s")
-            params.append(error)
-
-        if not updates:
-            return self.get_job(job_id)
-
-        updates.append("updated_at = CURRENT_TIMESTAMP")
-        params.append(job_id)
-
-        with self.get_conn() as conn:
-            with conn.cursor(cursor_factory=RealDictCursor) as cursor:
-                cursor.execute(
-                    f"UPDATE jobs SET {', '.join(updates)} WHERE job_id = %s RETURNING *",
-                    params,
-                )
-                job = cursor.fetchone()
-            conn.commit()
-            return dict(job) if job else None
-
-    def get_job(self, job_id: str) -> Optional[Dict]:
-        """Get a job by ID."""
-        with self.get_conn() as conn:
-            with conn.cursor(cursor_factory=RealDictCursor) as cursor:
-                cursor.execute("SELECT * FROM jobs WHERE job_id = %s", (job_id,))
-                job = cursor.fetchone()
-                return dict(job) if job else None
-
-    def list_jobs(
-        self,
-        status: Optional[str] = None,
-        limit: int = 10,
-    ) -> List[Dict]:
-        """List jobs, optionally filtered by status."""
-        query = "SELECT * FROM jobs"
-        params: list = []
-        if status:
-            query += " WHERE status = %s"
-            params.append(status)
-        query += " ORDER BY created_at DESC LIMIT %s"
-        params.append(limit)
-
-        with self.get_conn() as conn:
-            with conn.cursor(cursor_factory=RealDictCursor) as cursor:
-                cursor.execute(query, params)
-                return [dict(row) for row in cursor.fetchall()]
-
-    def mark_stale_jobs_failed(self) -> int:
-        """Mark any jobs in 'running' or 'pending' state as 'failed'.
-
-        Called at startup to clean up jobs that were interrupted by a restart.
-
-        Returns:
-            Number of jobs marked as failed.
-        """
-        with self.get_conn() as conn:
-            with conn.cursor() as cursor:
-                cursor.execute(
-                    """
-                    UPDATE jobs SET status = 'failed', error = 'Interrupted by server restart',
-                    updated_at = CURRENT_TIMESTAMP
-                    WHERE status IN ('running', 'pending')
-                    """
-                )
-                count = cursor.rowcount
-            conn.commit()
-            return count
-
     # User Authentication Methods
 
     @staticmethod

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"

scripts/init_database.py

@@ -40,9 +40,6 @@ def main():
         print("\nTables created:")
         print("  - llm_messages: Stores all LLM prompts and responses")
         print("  - users: Stores user accounts")
-        print("  - jobs: Stores async batch job state")
-        print("  - patents: Patent PDF cache")
-        print("  - serp_queries: SERP query result cache")
         print("\nIndexes created:")
         print("  - idx_messages_timestamp: For time-based queries")
         print("  - idx_messages_company: For company-specific queries")

tests/test_api.py

@@ -5,7 +5,7 @@ from datetime import datetime
 from unittest.mock import Mock, patch
 from fastapi.testclient import TestClient
 
-from SPARC.api import app
+from SPARC.api import app, _analyzer, _jobs
 from SPARC.types import CompanyAnalysisResult, BatchAnalysisResult
 
 

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)