fix: require SECRET_TOKEN at startup to prevent auth bypass (#476)

* fix: require SECRET_TOKEN at startup to prevent auth bypass

The original verify_token() allowed None == None when SECRET_TOKEN was
unset, silently disabling authentication.  The server now refuses to
start without SECRET_TOKEN configured, and validate_user() accepts the
static token via constant-time comparison (hmac.compare_digest) as an
alternative to DB-backed OAuth tokens.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: add pylint disable for wrong-import-position in conftest.py

The imports must come after os.environ.setdefault() for SECRET_TOKEN,
which is intentionally non-standard. Suppress the C0413 warning.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: add SECRET_TOKEN to Playwright CI workflow env

The 'Start FastAPI application' step was missing SECRET_TOKEN, causing
the app to crash at startup with RuntimeError since the PR made it
required.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

.env.example

@@ -42,10 +42,11 @@ FALKORDB_URL=redis://localhost:6379/0  # REQUIRED - change to your FalkorDB URL
 # FALKORDB_PORT=6379
 
 # -----------------------------
-# Optional API / secret tokens
+# API / secret tokens
 # -----------------------------
-# API token for internal API access (optional)
-# SECRET_TOKEN=your_secret_token
+# REQUIRED: static bearer token for internal / programmatic API access.
+# The server refuses to start when this is missing.
+SECRET_TOKEN=your_secret_token
 # SECRET_TOKEN_ERP=your_erp_token
 
 # -----------------------------

.github/workflows/playwright.yml

@@ -136,6 +136,7 @@ jobs:
       env:
         PYTHONUNBUFFERED: 1
         FASTAPI_SECRET_KEY: test-secret-key-for-ci
+        SECRET_TOKEN: test-secret-token-for-ci
         APP_ENV: development
         FASTAPI_DEBUG: False
         FALKORDB_URL: redis://localhost:6379

api/auth/user_management.py

@@ -1,6 +1,7 @@
 """User management and authentication functions for text2sql API."""
 
 import base64
+import hmac
 import logging
 import os
 import secrets
@@ -19,6 +20,16 @@
         "FASTAPI_SECRET_KEY not set, using generated key. Set this in production!"
     )
 
+# Static API token for internal / programmatic access.
+# REQUIRED: the server refuses to start when this is missing so that
+# an unconfigured deployment never silently disables authentication.
+SECRET_TOKEN: str = os.environ.get("SECRET_TOKEN", "")
+if not SECRET_TOKEN:
+    raise RuntimeError(
+        "SECRET_TOKEN environment variable is required but not set. "
+        "Set it to a strong, random value before starting the server."
+    )
+
 
 class IdentityInfo(BaseModel):
     """
@@ -235,11 +246,22 @@ async def validate_user(request: Request) -> Tuple[Optional[Dict[str, Any]], boo
     try:
         api_token = get_token(request)
 
-        if api_token:
-            db_info = await _get_user_info(api_token)
+        if not api_token:
+            return None, False
+
+        # Accept the static SECRET_TOKEN for internal / programmatic access.
+        # Uses constant-time comparison to prevent timing attacks.
+        if hmac.compare_digest(api_token, SECRET_TOKEN):
+            return {
+                "email": "api@internal",
+                "name": "API",
+                "picture": None,
+            }, True
+
+        db_info = await _get_user_info(api_token)
 
-            if db_info:
-                return db_info, True
+        if db_info:
+            return db_info, True
 
         return None, False
 

tests/conftest.py

@@ -4,8 +4,12 @@
 import subprocess
 import time
 
-import pytest
-import requests
+# SECRET_TOKEN must be set before any test imports api.index (which triggers
+# app creation and the startup SECRET_TOKEN requirement check).
+os.environ.setdefault("SECRET_TOKEN", "test-secret-token")
+
+import pytest  # pylint: disable=wrong-import-position
+import requests  # pylint: disable=wrong-import-position
 
 
 def pytest_configure(config):
@@ -27,6 +31,7 @@ def fastapi_app():
         'GOOGLE_CLIENT_SECRET': 'test-google-client-secret',
         'GITHUB_CLIENT_ID': 'test-github-client-id',
         'GITHUB_CLIENT_SECRET': 'test-github-client-secret',
+        'SECRET_TOKEN': 'test-secret-token',
         'ENABLE_TEST_AUTH': 'true',  # Enable test auth bypass for E2E tests
     }
     for var, default in env_defaults.items():