feat: implement stateless JWT-based authentication with refresh tokens stored in HTTPOnly Cookies

auth/constants.py

@@ -20,3 +20,20 @@ EMAIL_RATE_LIMITS = {
     "forgot_password": {"limit": 3, "window_seconds": 3600},
     "change_password_confirmation": {"limit": 3, "window_seconds": 3600},
 }
+
+# ── JWT / Access token ────────────────────────────────────────────────────────
+
+# Short-lived JWT lifetime. Stateless: verified via signature only, no DB lookup.
+ACCESS_TOKEN_EXPIRE_MINUTES = 15
+
+# ── Refresh token ─────────────────────────────────────────────────────────────
+
+# Long-lived opaque token lifetime. Stateful: looked up in the DB on every use.
+REFRESH_TOKEN_EXPIRE_DAYS = 30
+
+# ── HttpOnly cookie settings ──────────────────────────────────────────────────
+
+REFRESH_COOKIE_NAME    = "refresh_token"
+# Scope the cookie to the auth sub-path so it is NOT sent to /api/materials etc.
+REFRESH_COOKIE_PATH    = "/api/auth"
+REFRESH_COOKIE_MAX_AGE = REFRESH_TOKEN_EXPIRE_DAYS * 24 * 3600  # seconds

auth/jwt_utils.py

@@ -0,0 +1,70 @@
+"""
+JWT and refresh-token utilities.
+
+Responsibilities:
+  - Sign / verify short-lived access tokens (15 min) with our own secret key.
+  - Generate opaque refresh token strings and produce their SHA-256 hash for
+    safe storage in the database.
+
+No FastAPI or database imports — pure utility module.
+"""
+import hashlib
+import secrets
+from datetime import datetime, timedelta, timezone
+
+import jwt
+
+from src.config import settings
+from src.auth.constants import (
+    ACCESS_TOKEN_EXPIRE_MINUTES,
+    REFRESH_TOKEN_EXPIRE_DAYS,
+)
+
+
+def create_access_token(user_id: str, email: str) -> str:
+    """Return a signed JWT that expires in ACCESS_TOKEN_EXPIRE_MINUTES."""
+    if not settings.jwt_secret_key:
+        raise RuntimeError(
+            "JWT_SECRET_KEY is not configured. "
+            "Add it to config.env (generate with: openssl rand -hex 32)."
+        )
+    now = datetime.now(timezone.utc)
+    payload = {
+        "sub": user_id,
+        "email": email,
+        "iat": now,
+        "exp": now + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES),
+    }
+    return jwt.encode(payload, settings.jwt_secret_key, algorithm=settings.jwt_algorithm)
+
+
+def decode_access_token(token: str) -> dict:
+    """
+    Decode and verify a JWT issued by create_access_token.
+
+    Returns the payload dict on success.
+    Raises jwt.ExpiredSignatureError if the token has expired.
+    Raises jwt.InvalidTokenError (or subclass) for any other problem.
+    """
+    if not settings.jwt_secret_key:
+        raise RuntimeError("JWT_SECRET_KEY is not configured.")
+    return jwt.decode(
+        token,
+        settings.jwt_secret_key,
+        algorithms=[settings.jwt_algorithm],
+    )
+
+
+# ── Refresh token ─────────────────────────────────────────────────────────────
+
+REFRESH_TOKEN_EXPIRE_DAYS = 30
+
+
+def create_refresh_token() -> str:
+    """Return a cryptographically-secure 64-char hex string (32 random bytes)."""
+    return secrets.token_hex(32)
+
+
+def hash_token(raw: str) -> str:
+    """SHA-256 hex digest — safe to store in the DB instead of the raw value."""
+    return hashlib.sha256(raw.encode()).hexdigest()

auth/refresh_token_store.py

@@ -0,0 +1,123 @@
+"""
+Stateful refresh-token store.
+
+Wraps the `refresh_tokens` Supabase table with simple CRUD helpers.
+All functions are synchronous and use the existing `_table_supabase`
+helper from `store.py`, so they get the same dev-mode fallback behaviour.
+
+Table DDL (run once in the Supabase SQL editor):
+
+    CREATE TABLE IF NOT EXISTS refresh_tokens (
+      id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+      user_id     UUID NOT NULL REFERENCES profiles(id) ON DELETE CASCADE,
+      token_hash  TEXT NOT NULL UNIQUE,
+      expires_at  TIMESTAMPTZ NOT NULL,
+      revoked     BOOLEAN NOT NULL DEFAULT FALSE,
+      created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+    );
+    CREATE INDEX ON refresh_tokens(token_hash);
+    CREATE INDEX ON refresh_tokens(user_id);
+"""
+
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+from src.store import _table_supabase, _robust_execute
+from src.auth.constants import REFRESH_TOKEN_EXPIRE_DAYS
+
+logger = logging.getLogger(__name__)
+
+
+def _now_utc() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def save_refresh_token(user_id: str, token_hash: str) -> None:
+    """Persist a new (un-revoked) refresh token row for *user_id*."""
+    expires_at = _now_utc() + timedelta(days=REFRESH_TOKEN_EXPIRE_DAYS)
+    try:
+        _robust_execute(
+            _table_supabase("refresh_tokens").insert({
+                "user_id": user_id,
+                "token_hash": token_hash,
+                "expires_at": expires_at.isoformat(),
+                "revoked": False,
+            })
+        )
+    except Exception as e:
+        logger.error("save_refresh_token failed: %s", e)
+        raise
+
+
+def get_refresh_token(token_hash: str) -> Optional[dict]:
+    """
+    Look up a refresh token row by its hash.
+
+    Returns the raw DB row dict, or None if not found.
+    """
+    try:
+        result = _robust_execute(
+            _table_supabase("refresh_tokens")
+            .select("*")
+            .eq("token_hash", token_hash)
+        )
+        rows = result.data
+        if isinstance(rows, list):
+            return rows[0] if rows else None
+        return rows or None
+    except Exception as e:
+        logger.error("get_refresh_token failed: %s", e)
+        return None
+
+
+def revoke_refresh_token(token_hash: str) -> None:
+    """Mark a single token as revoked."""
+    try:
+        _robust_execute(
+            _table_supabase("refresh_tokens")
+            .update({"revoked": True})
+            .eq("token_hash", token_hash)
+        )
+    except Exception as e:
+        logger.error("revoke_refresh_token failed: %s", e)
+
+
+def revoke_all_user_tokens(user_id: str) -> None:
+    """Revoke every active refresh token for *user_id* (logout-everywhere)."""
+    try:
+        _robust_execute(
+            _table_supabase("refresh_tokens")
+            .update({"revoked": True})
+            .eq("user_id", user_id)
+        )
+    except Exception as e:
+        logger.error("revoke_all_user_tokens failed for %s: %s", user_id, e)
+
+
+def is_token_valid(row: dict) -> bool:
+    """
+    Return True if the DB row represents a currently-valid refresh token.
+
+    Checks: row exists, not revoked, not expired.
+    """
+    if not row:
+        return False
+    if row.get("revoked"):
+        return False
+    expires_at_raw = row.get("expires_at")
+    if not expires_at_raw:
+        return False
+    # Supabase returns ISO-8601 strings; parse and compare.
+    try:
+        if isinstance(expires_at_raw, str):
+            # Handle both 'Z' suffix and '+00:00' offset
+            expires_at_raw = expires_at_raw.replace("Z", "+00:00")
+            expires_at = datetime.fromisoformat(expires_at_raw)
+        else:
+            expires_at = expires_at_raw
+        if expires_at.tzinfo is None:
+            expires_at = expires_at.replace(tzinfo=timezone.utc)
+        return _now_utc() < expires_at
+    except Exception:
+        return False

auth/routes.py

@@ -1,14 +1,26 @@
 import uuid
 import cloudinary
 import cloudinary.uploader
-from fastapi import APIRouter, HTTPException, UploadFile, File
+from datetime import timezone, datetime
+from fastapi import APIRouter, HTTPException, UploadFile, File, Response, Request
 from fastapi import Depends
 from typing import Optional
 
 from src.config import settings
 from src.database import get_auth_supabase, get_supabase
 from src.store import create_user, get_user_by_email, delete_user_data, update_user_profile, get_user_by_id
-from src.dependencies import get_current_user_id, get_current_user
+from src.dependencies import get_current_user_id, get_current_user, _verify_token_cached
+from src.auth.jwt_utils import (
+    create_access_token,
+    create_refresh_token,
+    hash_token,
+)
+from src.auth.refresh_token_store import (
+    save_refresh_token,
+    get_refresh_token,
+    revoke_refresh_token,
+    is_token_valid,
+)
 from .schemas import ProfileUpdateRequest, EmailRateLimitRequest
 from .constants import (
     ALLOWED_MIME_TYPES,
@@ -16,6 +28,9 @@ from .constants import (
     AVATAR_BUCKET,
     PLACEHOLDER_DOMAINS,
     EMAIL_RATE_LIMITS,
+    REFRESH_COOKIE_NAME,
+    REFRESH_COOKIE_PATH,
+    REFRESH_COOKIE_MAX_AGE,
 )
 from .rate_limiter import (
     enforce_email_rate_limit,
@@ -26,6 +41,33 @@ from .rate_limiter import (
 router = APIRouter(prefix="/api/auth", tags=["Auth"])
 
 
+# ── Cookie helper ─────────────────────────────────────────────────────────────
+# Constants are defined in src/auth/constants.py
+
+
+def _set_refresh_cookie(response: Response, raw_token: str) -> None:
+    """Attach the refresh token as an HttpOnly cookie on *response*."""
+    response.set_cookie(
+        key=REFRESH_COOKIE_NAME,
+        value=raw_token,
+        httponly=True,
+        secure=(settings.environment != "development"),
+        samesite="none",   # required for cross-origin Vercel ↔ HF Space
+        max_age=REFRESH_COOKIE_MAX_AGE,
+        path=REFRESH_COOKIE_PATH,
+    )
+
+
+def _clear_refresh_cookie(response: Response) -> None:
+    """Remove the refresh token cookie."""
+    response.delete_cookie(
+        key=REFRESH_COOKIE_NAME,
+        path=REFRESH_COOKIE_PATH,
+        samesite="none",
+        secure=(settings.environment != "development"),
+    )
+
+
 @router.post("/upload-avatar")
 async def upload_avatar(
     file: UploadFile = File(...),
@@ -262,3 +304,159 @@ async def email_limit_status(action: str, email: str):
     return {"status": "success", "action": action, "email": email, **status_info}
 
 
+# ── Token Exchange & Refresh ───────────────────────────────────────────────────
+
+@router.post("/session")
+async def exchange_session(request: Request, response: Response):
+    """
+    Token exchange endpoint.
+
+    Accepts a Supabase JWT in the Authorization header, validates it once
+    against Supabase, then issues:
+      • A short-lived (15 min) JWT in the response body
+      • A long-lived (30 day) opaque refresh token as an HttpOnly cookie
+
+    The frontend should call this right after any Supabase sign-in event
+    (onAuthStateChange fires with a session).
+    """
+    # 1. Extract the Supabase token from the request
+    headers = {k.lower(): v for k, v in request.headers.items()}
+    auth = headers.get("authorization", "")
+    x_auth = headers.get("x-auth-token", "")
+    raw_supabase_token = x_auth or (auth[len("Bearer "):].strip() if auth.startswith("Bearer ") else None)
+
+    if not raw_supabase_token:
+        raise HTTPException(401, "Authorization header with Supabase token required")
+
+    # 2. Validate the Supabase token once
+    client = get_auth_supabase() or get_supabase()
+    if not client:
+        raise HTTPException(503, "Auth service unavailable")
+
+    try:
+        sb_user = _verify_token_cached(client, raw_supabase_token)
+        user_id  = str(sb_user.id)
+        email    = getattr(sb_user, "email", "") or ""
+    except Exception:
+        raise HTTPException(401, "Invalid or expired Supabase token")
+
+    # 3. Ensure a profile row exists (first login race-safe)
+    profile = get_user_by_id(user_id)
+    if not profile:
+        meta  = getattr(sb_user, "user_metadata", {}) or {}
+        name  = meta.get("full_name") or meta.get("name") or email.split("@")[0] or "User"
+        profile = create_user(name=name, email=email, password="", user_id=user_id)
+
+    # 4. Issue our tokens
+    access_token  = create_access_token(user_id, email)
+    raw_refresh   = create_refresh_token()
+    refresh_hash  = hash_token(raw_refresh)
+    save_refresh_token(user_id, refresh_hash)
+
+    _set_refresh_cookie(response, raw_refresh)
+
+    return {
+        "access_token": access_token,
+        "token_type": "bearer",
+        "user": profile,
+    }
+
+
+@router.post("/refresh")
+async def refresh_session(request: Request, response: Response):
+    """
+    Silently re-issue a new access token using the HttpOnly refresh token cookie.
+
+    Rotates the refresh token on every use (old token is revoked, new one is issued)
+    so a stolen token can only be used once before it's invalidated.
+    """
+    raw = request.cookies.get(REFRESH_COOKIE_NAME)
+    if not raw:
+        raise HTTPException(401, "No refresh token cookie found")
+
+    token_hash = hash_token(raw)
+    row = get_refresh_token(token_hash)
+
+    if not row or not is_token_valid(row):
+        _clear_refresh_cookie(response)
+        raise HTTPException(401, "Refresh token is invalid, expired, or revoked")
+
+    user_id = str(row["user_id"])
+
+    # Fetch the user's email for the new access token payload
+    profile = get_user_by_id(user_id)
+    email = (profile or {}).get("email", "")
+
+    # Rotate: revoke old, issue new refresh token
+    revoke_refresh_token(token_hash)
+    new_raw_refresh = create_refresh_token()
+    new_hash        = hash_token(new_raw_refresh)
+    save_refresh_token(user_id, new_hash)
+
+    access_token = create_access_token(user_id, email)
+
+    _set_refresh_cookie(response, new_raw_refresh)
+
+    return {
+        "access_token": access_token,
+        "token_type": "bearer",
+    }
+
+
+@router.post("/logout")
+async def logout(request: Request, response: Response):
+    """
+    Revoke the refresh token in the database and clear the cookie.
+
+    This is the only true logout — do not rely on JWT expiry alone.
+    The short-lived access token will expire naturally within 15 minutes.
+    """
+    raw = request.cookies.get(REFRESH_COOKIE_NAME)
+    if raw:
+        token_hash = hash_token(raw)
+        revoke_refresh_token(token_hash)
+
+    _clear_refresh_cookie(response)
+    return {"status": "ok", "message": "Logged out successfully"}
+
+
+@router.get("/me")
+async def get_me(
+    user_id: str = Depends(get_current_user_id),
+    current_user=Depends(get_current_user),
+):
+    """
+    Return the authenticated user's profile.
+
+    Protected route — requires a valid JWT in Authorization: Bearer header.
+    This is a thin wrapper over the existing get_profile logic so both
+    /api/auth/profile and /api/auth/me return the same shape.
+    """
+    user = get_user_by_id(user_id)
+    if not user:
+        # Fallback: build minimal profile from JWT payload
+        uid = (
+            getattr(current_user, "id", None)
+            or (current_user.get("id") if isinstance(current_user, dict) else None)
+        )
+        if uid:
+            from src.store import _map_profile, get_usage
+            email = (
+                getattr(current_user, "email", "") or
+                (current_user.get("email") if isinstance(current_user, dict) else "") or ""
+            )
+            real_usage = get_usage(uid)
+            user = _map_profile({
+                "id": uid,
+                "display_name": email.split("@")[0] or "User",
+                "email": email,
+                "avatar_url": "",
+                "daily_requests": real_usage.get("used", 0),
+                "last_request_date": (
+                    datetime.now(timezone.utc).date().isoformat()
+                ),
+            })
+
+    if not user:
+        raise HTTPException(404, "Profile not found")
+    return {"status": "success", "user": user}

config.py

@@ -55,6 +55,12 @@ class Settings:
         if w.strip()
     ]
 
+    # ── JWT / Refresh-Token Auth ───────────────────────────────────────────────
+    jwt_secret_key: str = os.getenv("JWT_SECRET_KEY", "")
+    jwt_algorithm: str  = os.getenv("JWT_ALGORITHM", "HS256")
+    # Set to 'development' locally so Secure cookie flag is not required over HTTP
+    environment: str    = os.getenv("ENVIRONMENT", "production")
+
 
 @lru_cache()
 def get_settings() -> Settings:

dependencies.py

@@ -1,5 +1,5 @@
 import time
-from fastapi import Depends, HTTPException, Header, status, Request
+from fastapi import HTTPException, status, Request
 from fastapi.security import OAuth2PasswordBearer
 from typing import Any, Optional
 
@@ -41,8 +41,8 @@ def _verify_token_cached(client, token: str) -> Any:
 
 def _extract_token(request: Request) -> Optional[str]:
     """
-    Extract Supabase JWT from headers — case-insensitive.
-    Priority: X-Auth-Token → Authorization (skip HF tokens)
+    Extract JWT from headers — case-insensitive.
+    Priority: X-Auth-Token → Authorization (skip HF space tokens)
     """
     headers = {k.lower(): v for k, v in request.headers.items()}
 
@@ -64,10 +64,9 @@ def _extract_token(request: Request) -> Optional[str]:
 
 
 async def get_current_user_id(request: Request) -> str:
-    # Use a single cached client — prefer the auth client, fall back to service client
     client = get_auth_supabase() or get_supabase()
 
-    # Dev mode
+    # Dev mode — no Supabase configured
     if client is None:
         return DEV_USER_ID
 
@@ -76,6 +75,17 @@ async def get_current_user_id(request: Request) -> str:
     if not token:
         raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Not authenticated")
 
+    # ── Mode 1: our own stateless JWT (fast — no network call) ───────────────
+    try:
+        from src.auth.jwt_utils import decode_access_token
+        payload = decode_access_token(token)
+        user_id = payload.get("sub")
+        if user_id:
+            return str(user_id)
+    except Exception:
+        pass  # Fall through to Supabase validation
+
+    # ── Mode 2: Supabase token (backwards-compat for Google OAuth sessions) ──
     try:
         user = _verify_token_cached(client, token)
         return str(user.id)
@@ -85,7 +95,6 @@ async def get_current_user_id(request: Request) -> str:
 
 
 async def get_current_user(request: Request) -> Any:
-    # Use a single cached client — prefer the auth client, fall back to service client
     client = get_auth_supabase() or get_supabase()
 
     # Dev mode
@@ -94,13 +103,25 @@ async def get_current_user(request: Request) -> Any:
 
     token = _extract_token(request)
 
-    if token:
-        try:
-            user = _verify_token_cached(client, token)
-            if user:
-                return user
-        except Exception as e:
-            print(f"Token validation error: {e}")
-            pass
+    if not token:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Not authenticated")
+
+    # ── Mode 1: our own stateless JWT ────────────────────────────────────────
+    try:
+        from src.auth.jwt_utils import decode_access_token
+        payload = decode_access_token(token)
+        user_id = payload.get("sub")
+        if user_id:
+            return {"id": user_id, "email": payload.get("email", "")}
+    except Exception:
+        pass
+
+    # ── Mode 2: Supabase token (backwards compat) ────────────────────────────
+    try:
+        user = _verify_token_cached(client, token)
+        if user:
+            return user
+    except Exception as e:
+        print(f"Token validation error: {e}")
 
     raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Not authenticated")

requirements.txt

@@ -29,6 +29,8 @@ python-multipart
 pydantic
 httpx
 cloudinary
+PyJWT>=2.8.0
+passlib[bcrypt]>=1.7.4
 
 supabase
 transformers