Update CORS configuration and documentation

Author: NinoSkopac

resources/products/token-spy/README.md

@@ -83,6 +83,31 @@ Copy `.env.example` to `.env` and set required values:
 | `DEFAULT_API_KEY` | | API key for upstream (if required) |
 | `TOKEN_SPY_PROXY_PORT` | | Proxy port (default: 8080) |
 | `TOKEN_SPY_DASHBOARD_PORT` | | Dashboard port (default: 3001) |
+| `DASHBOARD_ALLOWED_ORIGINS` | | Dashboard CORS allowlist (CSV or JSON array). Leave empty for secure default (no cross-origin access). |
+| `DASHBOARD_CORS_ALLOW_CREDENTIALS` | | Whether CORS allows credentials (default: `true`; requires explicit origins) |
+
+### Dashboard CORS Security
+
+Token Spy dashboard CORS is environment-driven via `DASHBOARD_ALLOWED_ORIGINS`.
+
+- **Secure default (recommended):** leave `DASHBOARD_ALLOWED_ORIGINS` empty to disable cross-origin browser access.
+- **Production:** set explicit trusted origins only.
+- **Local development override:** set localhost origins as a CSV or JSON array.
+
+Examples:
+
+```bash
+# Production
+DASHBOARD_ALLOWED_ORIGINS=https://dashboard.example.com
+
+# Local development (CSV)
+DASHBOARD_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
+
+# Local development (JSON array)
+DASHBOARD_ALLOWED_ORIGINS=["http://localhost:3000","http://127.0.0.1:3000"]
+```
+
+> ⚠️ Startup validation rejects insecure combinations. If `DASHBOARD_CORS_ALLOW_CREDENTIALS=true`, wildcard `*` is not allowed in `DASHBOARD_ALLOWED_ORIGINS` and the dashboard will fail fast with an error log.
 
 ### Generating a Secure Password
 

resources/products/token-spy/config/.env.example

@@ -45,6 +45,16 @@ DASHBOARD_AUTH_ENABLED=false
 DASHBOARD_USERNAME=admin
 DASHBOARD_PASSWORD=
 
+# Dashboard CORS allowlist (recommended: explicit origins only)
+# Secure default is empty, which disables cross-origin browser requests.
+# Production example: DASHBOARD_ALLOWED_ORIGINS=https://dashboard.example.com
+# Local dev override examples:
+#   DASHBOARD_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
+#   DASHBOARD_ALLOWED_ORIGINS=["http://localhost:3000","http://127.0.0.1:3000"]
+# NOTE: If DASHBOARD_CORS_ALLOW_CREDENTIALS=true, wildcard '*' is rejected at startup.
+DASHBOARD_ALLOWED_ORIGINS=
+DASHBOARD_CORS_ALLOW_CREDENTIALS=true
+
 # ============================================
 # Logging & Performance
 # ============================================

resources/products/token-spy/dashboard/main.py

@@ -19,6 +19,7 @@
 import os
 import asyncio
 import logging
+import json
 from datetime import datetime, timedelta
 from decimal import Decimal
 from typing import Optional, List, Dict, Any, Literal
@@ -51,6 +52,8 @@ class Settings(BaseSettings):
     dashboard_auth_enabled: bool = False
     dashboard_username: str = "admin"
     dashboard_password: Optional[str] = Field(default=None, description="Dashboard password (required when auth enabled)")
+    dashboard_allowed_origins: str = ""
+    dashboard_cors_allow_credentials: bool = True
 
     class Config:
         env_file = ".env"
@@ -98,6 +101,63 @@ def verify_auth(credentials: HTTPBasicCredentials = Depends(security)):
 logger = logging.getLogger("token-spy-dashboard")
 
 
+def parse_allowed_origins(raw_origins: str) -> List[str]:
+    """Parse CORS origins from CSV or JSON array."""
+    value = (raw_origins or "").strip()
+    if not value:
+        return []
+
+    if value.startswith("{"):
+        raise ValueError(
+            "DASHBOARD_ALLOWED_ORIGINS JSON format must be an array, not an object"
+        )
+
+    if value.startswith("["):
+        try:
+            parsed = json.loads(value)
+        except json.JSONDecodeError as exc:
+            raise ValueError(
+                "DASHBOARD_ALLOWED_ORIGINS must be valid CSV or JSON array"
+            ) from exc
+
+        if not isinstance(parsed, list) or not all(isinstance(item, str) for item in parsed):
+            raise ValueError("DASHBOARD_ALLOWED_ORIGINS JSON format must be an array of strings")
+        return [origin.strip() for origin in parsed if origin.strip()]
+
+    return [origin.strip() for origin in value.split(",") if origin.strip()]
+
+
+def get_cors_settings() -> Dict[str, Any]:
+    """Return validated CORS settings from environment configuration."""
+    allow_origins = parse_allowed_origins(settings.dashboard_allowed_origins)
+    allow_credentials = settings.dashboard_cors_allow_credentials
+    has_wildcard = "*" in allow_origins
+
+    if allow_credentials and has_wildcard:
+        logger.error(
+            "Invalid CORS config: DASHBOARD_CORS_ALLOW_CREDENTIALS=true cannot be combined "
+            "with wildcard origin '*' in DASHBOARD_ALLOWED_ORIGINS."
+        )
+        raise ValueError(
+            "Refusing to start with insecure CORS config: credentials + wildcard origin"
+        )
+
+    if has_wildcard:
+        logger.warning(
+            "CORS is configured with wildcard origin '*'. This should only be used in controlled local development."
+        )
+    elif not allow_origins:
+        logger.info(
+            "CORS allowlist is empty; cross-origin browser requests are disabled. "
+            "Set DASHBOARD_ALLOWED_ORIGINS for explicit trusted origins."
+        )
+
+    return {
+        "allow_origins": allow_origins,
+        "allow_credentials": allow_credentials,
+    }
+
+
 def normalize_cost_and_speed_metrics(
     total_tokens: Optional[int],
     total_cost: Optional[float],
@@ -181,10 +241,11 @@ async def lifespan(app: FastAPI):
 )
 
 # CORS for React frontend
+cors_settings = get_cors_settings()
 app.add_middleware(
     CORSMiddleware,
-    allow_origins=["*"],
-    allow_credentials=True,
+    allow_origins=cors_settings["allow_origins"],
+    allow_credentials=cors_settings["allow_credentials"],
     allow_methods=["*"],
     allow_headers=["*"],
 )

resources/products/token-spy/tests/test_dashboard_api_metrics.py

@@ -281,3 +281,99 @@ def test_dashboard_and_sidecar_normalization_are_in_parity(
             avg_ttft_ms=avg_ttft_ms,
         )
         assert dashboard_result == sidecar_result
+
+
+@pytest.mark.parametrize(
+    "raw_origins, expected",
+    [
+        ("", []),
+        ("   ", []),
+        ("http://localhost:3000", ["http://localhost:3000"]),
+        (
+            "http://localhost:3000, http://127.0.0.1:3000",
+            ["http://localhost:3000", "http://127.0.0.1:3000"],
+        ),
+        (
+            '["http://localhost:3000", "http://127.0.0.1:3000"]',
+            ["http://localhost:3000", "http://127.0.0.1:3000"],
+        ),
+    ],
+)
+def test_parse_allowed_origins_accepts_csv_and_json(
+    dashboard_main_module,
+    raw_origins,
+    expected,
+):
+    assert dashboard_main_module.parse_allowed_origins(raw_origins) == expected
+
+
+@pytest.mark.parametrize(
+    "raw_origins",
+    [
+        '["http://localhost:3000",]',
+        '{"origin": "http://localhost:3000"}',
+        "[1, 2]",
+    ],
+)
+def test_parse_allowed_origins_rejects_invalid_json(dashboard_main_module, raw_origins):
+    with pytest.raises(ValueError):
+        dashboard_main_module.parse_allowed_origins(raw_origins)
+
+
+def test_get_cors_settings_rejects_credentials_with_wildcard(
+    dashboard_main_module,
+    monkeypatch,
+    caplog,
+):
+    monkeypatch.setattr(dashboard_main_module.settings, "dashboard_allowed_origins", "*")
+    monkeypatch.setattr(
+        dashboard_main_module.settings,
+        "dashboard_cors_allow_credentials",
+        True,
+    )
+
+    with caplog.at_level("ERROR"):
+        with pytest.raises(ValueError, match="insecure CORS config"):
+            dashboard_main_module.get_cors_settings()
+
+    assert "cannot be combined with wildcard origin '*'" in caplog.text
+
+
+def test_get_cors_settings_allows_wildcard_without_credentials(
+    dashboard_main_module,
+    monkeypatch,
+    caplog,
+):
+    monkeypatch.setattr(dashboard_main_module.settings, "dashboard_allowed_origins", "*")
+    monkeypatch.setattr(
+        dashboard_main_module.settings,
+        "dashboard_cors_allow_credentials",
+        False,
+    )
+
+    with caplog.at_level("WARNING"):
+        cors_settings = dashboard_main_module.get_cors_settings()
+
+    assert cors_settings["allow_origins"] == ["*"]
+    assert cors_settings["allow_credentials"] is False
+    assert "wildcard origin '*'" in caplog.text
+
+
+def test_get_cors_settings_logs_empty_allowlist_info(
+    dashboard_main_module,
+    monkeypatch,
+    caplog,
+):
+    monkeypatch.setattr(dashboard_main_module.settings, "dashboard_allowed_origins", "")
+    monkeypatch.setattr(
+        dashboard_main_module.settings,
+        "dashboard_cors_allow_credentials",
+        True,
+    )
+
+    with caplog.at_level("INFO"):
+        cors_settings = dashboard_main_module.get_cors_settings()
+
+    assert cors_settings["allow_origins"] == []
+    assert cors_settings["allow_credentials"] is True
+    assert "CORS allowlist is empty" in caplog.text