CORS & Auth Hardening + Dev Proxy Improvements (Backend & Frontend)

[DJJones66]

PR: CORS & Auth Hardening + Dev Proxy Improvements (Backend & Frontend)

Summary

This PR addresses persistent CORS inconsistency and sticky/invalid refresh-token issues observed across environments (Mac/Windows/Ubuntu, multiple hostnames/ports). It introduces an environment-aware CORS configuration, robust refresh-token validation & clearing, safer JWT timestamp handling, and frontend proxy + client-side reset logic to eliminate polluted sessions and cache artifacts during development.

---

Problem / Context

• CORS behaved inconsistently across localhost, 127.0.0.1, IPv6, and LAN IPs — especially with varying ports and browsers.
• Refresh token flow was fragile: malformed or stale cookies could persist, and timestamps (iat/exp) were sometimes inconsistent across generators & validators.
• Dev iterations were painful due to proxy targets being hard-coded and cached artifacts surviving rollbacks, giving the illusion of “bad code being present”.

---

What’s Changed (High-Level)

Backend

• .env-dev: Added temporary config for Chat-with-Docs integration (LLMs/Embeddings via Ollama), BM25, and Document Processor.

• Auth (auth.py):

  • Module-level imports for base64/json (avoid shadowing).

  • validate_token_logic(...): sanity-check iat/exp (future-issued, expired-long-ago, iat>exp).

  • clear_refresh_token_systematically(...): attempt all domain/path/cookie-attribute combos to clear persistent cookies.

  • log_token_validation(...): structured logging (source, token length, timestamps).

  • “Nuclear” paths:

    • Block known bad token string immediately.
    • Aggressive cookie clearing + response headers (cache-busting) on invalid tokens.

  • Enhanced /refresh flow: decode payload (without verify) only for logging/logic checks; clear and instruct reset if invalid.

  • Added endpoints:

    • POST /nuclear-clear-cookies & POST /force-logout-clear to force-clear cookie variants + set cache-busting headers.
    • POST /test-cookie-setting to validate cookie set/clear behavior.

• Security (security.py):

  • Store exp as a Unix timestamp and auto-inject iat if missing for consistency across validators.

• Config (config.py):

  • Simplified defaults; switched to typed lists for CORS/hosts (no implicit JSON strings).
  • Added field_validator parsers for list-like env vars and host lists.

• CORS Utilities (cors_utils.py):

  • build_dev_origin_regex(...): allow http(s)://(localhost|127.0.0.1|[::1]|LAN-IP)(:port)? patterns.
  • validate_production_origins(...): parse & validate origins, warn on insecure patterns.
  • log_cors_config(...), get_cors_debug_info(...) helpers.

• main.py:

  • Environment-aware CORS:

    • Dev: allow_origin_regex generated from CORS_DEV_HOSTS.
    • Prod: explicit, validated origin list; constrained methods/headers.

  • Centralized logging of applied CORS mode.

• New utility auth_fix.py:

  • CLI to show / clear all refresh tokens in DB to forcibly reset sessions.

Frontend

• Config (src/config/index.ts):

  • VITE_USE_PROXY toggle; dev defaults to proxy via relative URLs.
  • Fallbacks clarified for dev vs prod.

• Vite (vite.config.ts):

  • Proxy target via VITE_API_TARGET (default http://127.0.0.1:8005).
  • Proxy request logging hook for debugging.

• ApiService:

  • On token errors (STALE_TOKEN_RESET_REQUIRED, INVALID_TOKEN_RESET_REQUIRED*, BLOCKED_TOKEN_DETECTED):

    • Full client reset: clear localStorage/sessionStorage, attempt IndexedDB deletions, and aggressively clear cookies across domain/path variants, then hard-redirect to /login with reason param.

• Plugin Studio / UDR minor additions: Components/utilities created for ongoing integration; unrelated to CORS logic but included in this patch set.

---

Configuration / Env Notes

• New/Used backend envs (see backend/.env-dev):

  • LLM_PROVIDER, EMBEDDING_PROVIDER, ENABLE_CONTEXTUAL_RETRIEVAL,
  • OLLAMA_* endpoints & models,
  • BM25_* vars, DOCUMENT_PROCESSOR_*.

• CORS (backend):

  • APP_ENV=dev|prod controls regex vs explicit origins.
  • CORS_DEV_HOSTS (list) defaults: ["localhost","127.0.0.1","[::1]","10.0.2.149"]
  • CORS_ORIGINS used in prod only (explicit list).

• Frontend:

  • VITE_USE_PROXY=true|false (default true in dev).
  • VITE_API_TARGET for Vite proxy target if needed.

---

Security Considerations

• JWT:

  • exp and iat normalized to timestamps → consistent validation.
  • Additional checks for malformed/implausible tokens.

• Cookies:

  • Multiple clear strategies to avoid cross-host contamination in dev.
  • Nuclear endpoints offer admin-level reset mechanisms (dev-only usage recommended).

• Logging:

  • Token content is previewed only (partial token) + decoded payload for diagnostics without verification; do not enable this verbosity in production logs.

---

Backward Compatibility

• Prod CORS must provide explicit CORS_ORIGINS list (same as before but now validated).
• Token generation remains compatible, but iat/exp normalization may change token bytes; no consumer impact expected.
• Frontend defaults to proxy in dev; set VITE_USE_PROXY=false to direct-call API.