fix(auth): bind OAuth state to session + harden review fixes

Address PR #73 review feedback:

- auth: bind state nonce to HttpOnly cookie carrying {nonce, cv, popup_id}
  (HMAC-signed via SESSION_SECRET); reject mismatched/missing state with
  invalid_state. Closes login-CSRF where attacker-crafted state could log
  victim into attacker's account.
- auth: wrap flow.fetch_token in try/except → oauth_exchange_failed so
  popup self-closes instead of returning 500 on replayed/expired codes.
- auth: validate popup_id charset/length ([A-Za-z0-9_-]{1,128}); invalid
  input degrades to non-popup mode.
- SignInModal: split popupUrl (with popup_id) from sameTabUrl (without)
  so popup-blocker fallback redirects locally instead of broadcasting
  into a dead channel.
- SignInModal: don't require data.name on success — /auth/callback
  legitimately broadcasts empty name when /api/auth/me has no display.
- models: tighten model_pref to Optional[Literal["fast","smart"]] so
  garbage input 422s; fix misleading default-comment.
- ModelToggle: static aria-label so screen readers hear the description
  even when the visual tooltip is hidden.
- tests: add 23 unit tests for auth state cookie/nonce/popup_id helpers
  and 6 for _resolve_tutor_model.

Author: AndresL230

backend/models/__init__.py

@@ -1,4 +1,4 @@
-from typing import Optional, Union, List
+from typing import Optional, Union, List, Literal
 from pydantic import BaseModel, Field
 
 
@@ -10,7 +10,7 @@ class StartSessionBody(BaseModel):
     mode: str = "socratic"
     use_shared_context: bool = True
     course_id: Optional[str] = None  # Direct course_id lookup instead of resolving from topic
-    model_pref: Optional[str] = None  # "smart" (default, gemini-2.5-pro) or "fast" (gemini-2.5-flash)
+    model_pref: Optional[Literal["fast", "smart"]] = None  # "fast" (default, gemini-2.5-flash) or "smart" (gemini-2.5-pro)
 
 
 class ChatBody(BaseModel):
@@ -19,7 +19,7 @@ class ChatBody(BaseModel):
     message: str
     mode: str = "socratic"
     use_shared_context: bool = True
-    model_pref: Optional[str] = None
+    model_pref: Optional[Literal["fast", "smart"]] = None  # "fast" (default, gemini-2.5-flash) or "smart" (gemini-2.5-pro)
 
 
 class EndSessionBody(BaseModel):
@@ -33,7 +33,7 @@ class ActionBody(BaseModel):
     action_type: str = "hint"
     mode: str = "socratic"
     use_shared_context: bool = True
-    model_pref: Optional[str] = None
+    model_pref: Optional[Literal["fast", "smart"]] = None  # "fast" (default, gemini-2.5-flash) or "smart" (gemini-2.5-pro)
 
 
 # ── Quiz ──────────────────────────────────────────────────────────────────────

backend/routes/auth.py

@@ -9,6 +9,7 @@
 import base64
 import hashlib
 import hmac as _hmac
+import re
 import secrets
 import time as _time
 from urllib.parse import urlencode
@@ -39,6 +40,14 @@
 
 router = APIRouter()
 
+OAUTH_STATE_COOKIE = "sapling_oauth_state"
+_OAUTH_COOKIE_MAX_AGE = 600
+_POPUP_ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+
+# Fallback in-memory store for environments without SESSION_SECRET; entries
+# are keyed by nonce and expire after _OAUTH_COOKIE_MAX_AGE seconds.
+_OAUTH_FALLBACK_STORE: dict[str, tuple[float, dict]] = {}
+
 
 def _google_client_config() -> dict:
     return {
@@ -73,6 +82,68 @@ def _generate_pkce_pair():
     return code_verifier, code_challenge
 
 
+def _clean_popup_id(s: str | None) -> str | None:
+    if not s:
+        return None
+    return s if _POPUP_ID_RE.match(s) else None
+
+
+def _encode_oauth_cookie(payload: dict) -> str:
+    raw = json.dumps(payload, separators=(",", ":")).encode()
+    payload_b64 = base64.urlsafe_b64encode(raw).decode().rstrip("=")
+    if SESSION_SECRET:
+        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}"
+    nonce = payload.get("n", "")
+    if nonce:
+        _OAUTH_FALLBACK_STORE[nonce] = (_time.monotonic() + _OAUTH_COOKIE_MAX_AGE, payload)
+        _prune_fallback_store()
+    return payload_b64
+
+
+def _decode_oauth_cookie(cookie_value: str | None) -> dict | None:
+    if not cookie_value:
+        return None
+    if SESSION_SECRET:
+        if "." not in cookie_value:
+            return None
+        try:
+            payload_b64, sig_b64 = cookie_value.rsplit(".", 1)
+        except ValueError:
+            return None
+        expected = _hmac.new(SESSION_SECRET.encode(), payload_b64.encode(), hashlib.sha256).digest()
+        expected_b64 = base64.urlsafe_b64encode(expected).decode().rstrip("=")
+        if not _hmac.compare_digest(expected_b64, sig_b64):
+            return None
+        try:
+            padded = payload_b64 + "=" * (-len(payload_b64) % 4)
+            payload = json.loads(base64.urlsafe_b64decode(padded.encode()).decode())
+        except Exception:
+            return None
+        return payload if isinstance(payload, dict) else None
+    try:
+        padded = cookie_value + "=" * (-len(cookie_value) % 4)
+        payload = json.loads(base64.urlsafe_b64decode(padded.encode()).decode())
+    except Exception:
+        return None
+    if not isinstance(payload, dict):
+        return None
+    nonce = payload.get("n")
+    _prune_fallback_store()
+    entry = _OAUTH_FALLBACK_STORE.get(nonce or "")
+    if not entry:
+        return None
+    return entry[1]
+
+
+def _prune_fallback_store() -> None:
+    now = _time.monotonic()
+    expired = [k for k, (exp, _) in _OAUTH_FALLBACK_STORE.items() if exp < now]
+    for k in expired:
+        _OAUTH_FALLBACK_STORE.pop(k, None)
+
+
 @router.get("/me")
 def get_me(request: Request):
     """Return approval and onboarding status for a given user_id."""
@@ -142,42 +213,78 @@ def google_login(popup_id: str = Query(None)):
         raise HTTPException(status_code=400, detail="Google OAuth not configured")
 
     code_verifier, code_challenge = _generate_pkce_pair()
+    nonce = secrets.token_urlsafe(32)
+    clean_popup = _clean_popup_id(popup_id)
+
     flow = Flow.from_client_config(_google_client_config(), scopes=AUTH_SCOPES)
     flow.redirect_uri = GOOGLE_AUTH_REDIRECT_URI
-    state_payload = {"action": "signin", "cv": code_verifier}
-    if popup_id:
-        state_payload["popup_id"] = popup_id
     auth_url, _ = flow.authorization_url(
         prompt="consent",
         access_type="offline",
-        state=_encode_state(state_payload),
+        state=_encode_state({"action": "signin", "n": nonce}),
         code_challenge=code_challenge,
         code_challenge_method="S256",
     )
-    return RedirectResponse(auth_url)
+
+    cookie_value = _encode_oauth_cookie({
+        "n": nonce,
+        "cv": code_verifier,
+        "popup_id": clean_popup,
+    })
+    response = RedirectResponse(auth_url)
+    response.set_cookie(
+        key=OAUTH_STATE_COOKIE,
+        value=cookie_value,
+        max_age=_OAUTH_COOKIE_MAX_AGE,
+        httponly=True,
+        secure=True,
+        samesite="lax",
+        path="/",
+    )
+    return response
 
 
 @router.get("/google/callback")
-def google_callback(code: str = Query(...), state: str = Query(None)):
+def google_callback(request: Request, code: str = Query(...), state: str = Query(None)):
     """Exchange auth code for tokens, validate @bu.edu, upsert user."""
-    state_data = _decode_state(state) if state else {}
-    code_verifier = state_data.get("cv")
-    popup_id = state_data.get("popup_id")
+    cookie_payload = _decode_oauth_cookie(request.cookies.get(OAUTH_STATE_COOKIE))
+    code_verifier = cookie_payload.get("cv") if cookie_payload else None
+    popup_id = _clean_popup_id(cookie_payload.get("popup_id")) if cookie_payload else None
+    cookie_nonce = cookie_payload.get("n") if cookie_payload else None
 
     def _fail_redirect(error_code: str, fallback_path: str = "/auth") -> RedirectResponse:
         # In popup mode, route failures through /auth/callback so the popup
         # can broadcast the error and self-close instead of stranding the opener.
         if popup_id:
             params = urlencode({"error": error_code, "popup_id": popup_id})
-            return RedirectResponse(f"{FRONTEND_URL}/auth/callback?{params}")
-        return RedirectResponse(f"{FRONTEND_URL}{fallback_path}?error={error_code}")
+            resp = RedirectResponse(f"{FRONTEND_URL}/auth/callback?{params}")
+        else:
+            resp = RedirectResponse(f"{FRONTEND_URL}{fallback_path}?error={error_code}")
+        resp.set_cookie(
+            key=OAUTH_STATE_COOKIE,
+            value="",
+            max_age=0,
+            httponly=True,
+            secure=True,
+            samesite="lax",
+            path="/",
+        )
+        return resp
 
     if not GOOGLE_AVAILABLE:
         return _fail_redirect("google_not_configured")
 
+    state_data = _decode_state(state) if state else {}
+    state_nonce = state_data.get("n")
+    if not cookie_payload or not cookie_nonce or not state_nonce or not _hmac.compare_digest(str(state_nonce), str(cookie_nonce)):
+        return _fail_redirect("invalid_state")
+
     flow = Flow.from_client_config(_google_client_config(), scopes=AUTH_SCOPES)
     flow.redirect_uri = GOOGLE_AUTH_REDIRECT_URI
-    flow.fetch_token(code=code, code_verifier=code_verifier)
+    try:
+        flow.fetch_token(code=code, code_verifier=code_verifier)
+    except Exception:
+        return _fail_redirect("oauth_exchange_failed")
     creds = flow.credentials
 
     # Fetch user info from Google
@@ -245,7 +352,17 @@ def _fail_redirect(error_code: str, fallback_path: str = "/auth") -> RedirectRes
     if not is_approved:
         if popup_id:
             return _fail_redirect("not_approved")
-        return RedirectResponse(f"{FRONTEND_URL}/pending")
+        resp = RedirectResponse(f"{FRONTEND_URL}/pending")
+        resp.set_cookie(
+            key=OAUTH_STATE_COOKIE,
+            value="",
+            max_age=0,
+            httponly=True,
+            secure=True,
+            samesite="lax",
+            path="/",
+        )
+        return resp
 
     # Build a short-lived HMAC token so the frontend can verify this redirect
     # without a second round-trip to the backend.
@@ -264,4 +381,14 @@ def _fail_redirect(error_code: str, fallback_path: str = "/auth") -> RedirectRes
         **({"auth_token": auth_token} if auth_token else {}),
         **({"popup_id": popup_id} if popup_id else {}),
     })
-    return RedirectResponse(f"{FRONTEND_URL}/auth/callback?{params}")
+    resp = RedirectResponse(f"{FRONTEND_URL}/auth/callback?{params}")
+    resp.set_cookie(
+        key=OAUTH_STATE_COOKIE,
+        value="",
+        max_age=0,
+        httponly=True,
+        secure=True,
+        samesite="lax",
+        path="/",
+    )
+    return resp