fix(security): validate required config at startup; fail-closed unsigned-session fallback (#174)

config.py read every required secret with an empty-string default and validated
none, so the app booted with all secrets unset and failed opaquely later —
malformed REST URL on first DB call, mid-request Gemini errors, and worst, an
empty SESSION_SECRET silently switched OAuth state to an unsigned in-memory
fallback (insecure degradation).

- Add validate_config(), called from the FastAPI lifespan: raises one clear
  error naming every missing key (SUPABASE_URL, SUPABASE_SERVICE_KEY,
  GEMINI_API_KEY always; SESSION_SECRET outside local).
- Add APP_ENV (defaults to production → fail-closed) / IS_LOCAL. The unsigned
  OAuth-state fallback now raises outside local dev (defense in depth at the
  use site), so it is unreachable in production.

Tests: validate_config names all missing keys and relaxes SESSION_SECRET only
in local; the unsigned fallback raises in production (fails pre-fix, which
silently used it). Updated the two pre-existing fallback round-trip tests to
declare local mode.

Author: Jose-Gael-Cruz-Lopez

backend/config.py

@@ -16,6 +16,12 @@
 FRONTEND_URL = os.getenv("FRONTEND_URL", "http://localhost:3000")
 SESSION_SECRET = os.getenv("SESSION_SECRET", "")
 
+# Deployment mode (#174). Defaults to "production" so the config is fail-closed:
+# a deployment that sets nothing gets the strict checks. Set APP_ENV=local (or
+# development/dev/test) to relax SESSION_SECRET for local dev.
+APP_ENV = os.getenv("APP_ENV", "production").strip().lower()
+IS_LOCAL = APP_ENV in {"local", "development", "dev", "test"}
+
 GOOGLE_SCOPES = [
     "https://www.googleapis.com/auth/calendar.events",
     "https://www.googleapis.com/auth/calendar.readonly",
@@ -35,6 +41,36 @@
 MAX_AVATAR_SIZE: int = 5 * 1024 * 1024  # 5 MB
 
 
+def validate_config() -> None:
+    """Fail loudly at startup if required configuration is missing (#174).
+
+    Without this the app boots with empty secrets and fails opaquely later:
+    a "" SUPABASE_URL builds a malformed REST URL on the first DB call, a
+    missing GEMINI_API_KEY surfaces only mid-request, and — worst — an empty
+    SESSION_SECRET silently disables HMAC signing and drops session/OAuth
+    state into an unsigned in-memory fallback. Raise one clear error naming
+    every missing key instead.
+
+    SESSION_SECRET is required outside local dev (IS_LOCAL). The other three
+    are always required (CI/tests supply dummy values).
+    """
+    missing = []
+    if not SUPABASE_URL:
+        missing.append("SUPABASE_URL")
+    if not SUPABASE_SERVICE_KEY:
+        missing.append("SUPABASE_SERVICE_KEY")
+    if not GEMINI_API_KEY:
+        missing.append("GEMINI_API_KEY")
+    if not SESSION_SECRET and not IS_LOCAL:
+        missing.append("SESSION_SECRET")
+    if missing:
+        raise RuntimeError(
+            "Missing required configuration: "
+            + ", ".join(missing)
+            + f". (APP_ENV={APP_ENV!r}; set APP_ENV=local to relax SESSION_SECRET for local dev.)"
+        )
+
+
 def get_mastery_tier(score: float) -> str:
     if score >= 0.75:
         return "mastered"

backend/main.py

@@ -11,7 +11,7 @@
 from fastapi.responses import JSONResponse
 from starlette.exceptions import HTTPException as StarletteHTTPException
 
-from config import FRONTEND_URL, MAX_AVATAR_SIZE, PORT, STORAGE_BUCKET
+from config import FRONTEND_URL, MAX_AVATAR_SIZE, PORT, STORAGE_BUCKET, validate_config
 
 # App-wide log format. Per-request log lines (with request_id, duration,
 # status) are emitted from RequestIDMiddleware; this just sets the
@@ -71,6 +71,9 @@
 # that no migration ever made" bugs.
 @asynccontextmanager
 async def _lifespan(_app: FastAPI):
+    # #174: fail loudly at startup if required secrets are missing, before
+    # serving any request, rather than booting and failing opaquely later.
+    validate_config()
     await ensure_bucket_exists(
         STORAGE_BUCKET,
         public=True,  # required for unauthenticated <img src> reads

backend/routes/auth.py

@@ -24,6 +24,7 @@
     AUTH_SCOPES,
     FRONTEND_URL,
     SESSION_SECRET,
+    IS_LOCAL,
 )
 from db.connection import table
 from services.encryption import encrypt, encrypt_if_present, decrypt_if_present
@@ -106,6 +107,15 @@ def _encode_oauth_cookie(payload: dict) -> str:
         sig_bytes = _hmac.new(SESSION_SECRET.encode(), payload_b64.encode(), hashlib.sha256).digest()
         sig_b64 = base64.urlsafe_b64encode(sig_bytes).decode().rstrip("=")
         return f"{payload_b64}.{sig_b64}"
+    # #174: the unsigned in-memory fallback is local-dev only. Outside local it
+    # is a silent, insecure degradation (unsigned OAuth state) — fail closed.
+    # (validate_config already blocks startup without SESSION_SECRET in prod;
+    # this is defense in depth at the use site.)
+    if not IS_LOCAL:
+        raise RuntimeError(
+            "SESSION_SECRET is required outside local dev; refusing to issue "
+            "unsigned OAuth state."
+        )
     nonce = payload.get("n", "")
     if nonce:
         _OAUTH_FALLBACK_STORE[nonce] = (_time.monotonic() + _OAUTH_COOKIE_MAX_AGE, payload)
@@ -133,6 +143,11 @@ def _decode_oauth_cookie(cookie_value: str | None) -> dict | None:
         except Exception:
             return None
         return payload if isinstance(payload, dict) else None
+    # #174: the unsigned in-memory path is local-dev only. Outside local,
+    # refuse to accept unsigned OAuth state (symmetric with the encode-side
+    # guard) so no unsigned cookie is ever honored in production.
+    if not IS_LOCAL:
+        return None
     try:
         padded = cookie_value + "=" * (-len(cookie_value) % 4)
         payload = json.loads(base64.urlsafe_b64decode(padded.encode()).decode())

backend/tests/test_auth_state.py

@@ -71,8 +71,10 @@ def test_malformed_cookie_returns_none(self, monkeypatch):
 
     def test_fallback_in_memory_store_round_trip(self, monkeypatch):
         # Without SESSION_SECRET, encode stashes the payload in an in-memory
-        # dict keyed by nonce. Decode retrieves it.
+        # dict keyed by nonce. Decode retrieves it. #174: this unsigned
+        # fallback is local-dev only, so the test must declare local mode.
         monkeypatch.setattr(auth_module, "SESSION_SECRET", "")
+        monkeypatch.setattr(auth_module, "IS_LOCAL", True)
         auth_module._OAUTH_FALLBACK_STORE.clear()
         payload = {"n": "fallback-nonce", "cv": "verifier", "popup_id": "p"}
         cookie = auth_module._encode_oauth_cookie(payload)
@@ -81,6 +83,7 @@ def test_fallback_in_memory_store_round_trip(self, monkeypatch):
 
     def test_fallback_unknown_nonce_returns_none(self, monkeypatch):
         monkeypatch.setattr(auth_module, "SESSION_SECRET", "")
+        monkeypatch.setattr(auth_module, "IS_LOCAL", True)
         auth_module._OAUTH_FALLBACK_STORE.clear()
         # Build a cookie payload whose nonce was never registered
         bogus = base64.urlsafe_b64encode(

backend/tests/test_config_validation_failclosed.py

@@ -0,0 +1,93 @@
+"""
+Regression tests for #174:
+- validate_config() fails loudly at startup, naming every missing required key.
+- the unsigned in-memory OAuth-state fallback is unreachable outside local dev.
+
+The fail-closed test fails on pre-fix code, where _encode_oauth_cookie silently
+fell back to the unsigned in-memory store whenever SESSION_SECRET was empty,
+regardless of environment.
+"""
+import pytest
+
+import config
+from routes import auth as auth_mod
+
+
+def _set_required(monkeypatch, **overrides):
+    base = {
+        "SUPABASE_URL": "https://x.supabase.co",
+        "SUPABASE_SERVICE_KEY": "service-key",
+        "GEMINI_API_KEY": "gemini-key",
+        "SESSION_SECRET": "session-secret",
+        "IS_LOCAL": False,
+    }
+    base.update(overrides)
+    for k, v in base.items():
+        monkeypatch.setattr(config, k, v)
+
+
+class TestValidateConfig:
+    def test_passes_when_all_present(self, monkeypatch):
+        _set_required(monkeypatch)
+        config.validate_config()  # no raise
+
+    def test_raises_naming_every_missing_key(self, monkeypatch):
+        _set_required(
+            monkeypatch,
+            SUPABASE_URL="",
+            SUPABASE_SERVICE_KEY="",
+            GEMINI_API_KEY="",
+            SESSION_SECRET="",
+            IS_LOCAL=False,
+        )
+        with pytest.raises(RuntimeError) as exc:
+            config.validate_config()
+        msg = str(exc.value)
+        for key in ("SUPABASE_URL", "SUPABASE_SERVICE_KEY", "GEMINI_API_KEY", "SESSION_SECRET"):
+            assert key in msg
+
+    def test_session_secret_required_outside_local(self, monkeypatch):
+        _set_required(monkeypatch, SESSION_SECRET="", IS_LOCAL=False)
+        with pytest.raises(RuntimeError) as exc:
+            config.validate_config()
+        assert "SESSION_SECRET" in str(exc.value)
+
+    def test_session_secret_relaxed_in_local(self, monkeypatch):
+        _set_required(monkeypatch, SESSION_SECRET="", IS_LOCAL=True)
+        config.validate_config()  # no raise — relaxed for local dev
+
+
+class TestUnsignedOAuthFallbackFailsClosed:
+    def test_fails_closed_in_production(self, monkeypatch):
+        # No SESSION_SECRET + not local → must refuse (pre-fix: silently used
+        # the unsigned in-memory store).
+        monkeypatch.setattr(auth_mod, "SESSION_SECRET", "")
+        monkeypatch.setattr(auth_mod, "IS_LOCAL", False)
+        with pytest.raises(RuntimeError):
+            auth_mod._encode_oauth_cookie({"n": "nonce-123", "v": "verifier"})
+
+    def test_allowed_in_local(self, monkeypatch):
+        monkeypatch.setattr(auth_mod, "SESSION_SECRET", "")
+        monkeypatch.setattr(auth_mod, "IS_LOCAL", True)
+        out = auth_mod._encode_oauth_cookie({"n": "nonce-123", "v": "verifier"})
+        # Unsigned payload (no "." separator) is permitted only in local dev.
+        assert isinstance(out, str) and "." not in out
+
+    def test_signed_when_secret_present(self, monkeypatch):
+        monkeypatch.setattr(auth_mod, "SESSION_SECRET", "supersecret-value")
+        out = auth_mod._encode_oauth_cookie({"n": "nonce-123", "v": "verifier"})
+        assert "." in out  # payload_b64.sig_b64
+
+    def test_decode_refuses_unsigned_cookie_in_production(self, monkeypatch):
+        # Symmetric decode-side guard: even a hand-built unsigned cookie must
+        # not be honored outside local dev.
+        import base64
+        import json
+
+        unsigned = base64.urlsafe_b64encode(
+            json.dumps({"n": "x", "v": "y"}).encode()
+        ).decode().rstrip("=")
+        # Force the unsigned path (empty secret) in production mode.
+        monkeypatch.setattr(auth_mod, "SESSION_SECRET", "")
+        monkeypatch.setattr(auth_mod, "IS_LOCAL", False)
+        assert auth_mod._decode_oauth_cookie(unsigned) is None