feat(auth): Add Hugging Face OAuth Login (#168)

.env.example

@@ -69,13 +69,20 @@ ALLOWED_ORIGINS=http://localhost:3000,http://localhost:7860
 # Optional — defaults to "pdf,docx,txt,md"
 # ALLOWED_EXTENSIONS=pdf,docx,txt,md
 
-# ── HuggingFace (Required for LLM inference) ────────────────
+# ── HuggingFace (Required for LLM inference and OAuth) ───────
 
 # HuggingFace API token. Used to call the Inference API for LLM responses.
 # Get yours: https://huggingface.co/settings/tokens (free tier available)
 # Required (app won't generate answers without it)
 HF_TOKEN=your_huggingface_token_here
 
+# HuggingFace OAuth variables for native login support
+# Optional — required only for Hugging Face sign-in
+HF_CLIENT_ID=your_hf_oauth_client_id
+HF_CLIENT_SECRET=your_hf_oauth_client_secret
+HF_REDIRECT_URI=http://localhost:8000/api/v1/auth/callback/huggingface
+FRONTEND_URL=http://localhost:3000
+
 # ── LLM Configuration ───────────────────────────────────────
 
 # HuggingFace model ID used for answer generation.

README.md

@@ -469,6 +469,10 @@ docker compose up --build
 |---|---|---|---|---|
 | `SECRET_KEY` | ✅ | — | JWT signing & session secret. Use a strong random string. | Generate: `python -c "import secrets; print(secrets.token_urlsafe(32))"` |
 | `HF_TOKEN` | ✅ | — | HuggingFace API token for LLM inference via Inference API. | [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) (free) |
+| `HF_CLIENT_ID` | ❌ | — | HuggingFace OAuth client ID. Required only for Hugging Face sign-in. | [HuggingFace Developer Settings](https://huggingface.co/settings/connected-applications) |
+| `HF_CLIENT_SECRET` | ❌ | — | HuggingFace OAuth client secret. Required only for Hugging Face sign-in. | [HuggingFace Developer Settings](https://huggingface.co/settings/connected-applications) |
+| `HF_REDIRECT_URI` | ❌ | `http://localhost:8000/api/v1/auth/callback/huggingface` | HuggingFace OAuth callback redirect URI. | — |
+| `FRONTEND_URL` | ❌ | `http://localhost:3000` | Frontend URL to redirect to after OAuth callback finishes. | — |
 | `ENVIRONMENT` | ❌ | `development` | Runtime mode. Set to `production` for deployment to lock CORS. | — |
 | `DEBUG` | ❌ | `False` | Enable debug mode with detailed error pages. Never enable in production. | — |
 | `ALLOWED_ORIGINS` | ❌ | `http://localhost:3000,http://localhost:7860` | Comma-separated CORS origins (only enforced in production). | Your deployed domain(s) |

backend/app/auth.py

@@ -6,7 +6,7 @@ from typing import Optional
 
 import jwt
 import bcrypt
-from fastapi import Depends, HTTPException, status
+from fastapi import Depends, HTTPException, status, Cookie
 from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
 from sqlalchemy.orm import Session
 
@@ -15,7 +15,7 @@ from app.database import get_db
 from app.models import User
 
 settings = get_settings()
-security = HTTPBearer()
+security = HTTPBearer(auto_error=False)
 
 
 # ── Password Hashing ─────────────────────────────────
@@ -70,11 +70,23 @@ def decode_token(token: str, token_type: str = "access") -> Optional[str]:
 import hashlib
 
 def get_current_user(
-    credentials: HTTPAuthorizationCredentials = Depends(security),
+    credentials: Optional[HTTPAuthorizationCredentials] = Depends(security),
+    access_token: Optional[str] = Cookie(None),
     db: Session = Depends(get_db),
 ) -> User:
-    """Dependency: extract and validate user from JWT bearer token or API key."""
-    token = credentials.credentials
+    """Dependency: extract and validate user from JWT bearer token, API key, or secure cookie."""
+    token = None
+    if credentials:
+        token = credentials.credentials
+    elif access_token:
+        token = access_token
+
+    if not token:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or expired token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
 
     # Check if token is an API key
     if token.startswith("rag_"):

backend/app/config.py

@@ -23,6 +23,10 @@ class Settings(BaseSettings):
     JWT_ACCESS_EXPIRY_MINUTES: int = 15
     JWT_REFRESH_EXPIRY_DAYS: int = 7
     GOOGLE_CLIENT_ID: str = ""
+    HF_CLIENT_ID: str = ""
+    HF_CLIENT_SECRET: str = ""
+    HF_REDIRECT_URI: str = ""
+    FRONTEND_URL: str = "http://localhost:3000"
 
     # ── File Upload ──────────────────────────────────────
     UPLOAD_DIR: str = "./data/uploads"

backend/app/routes/auth.py

@@ -3,8 +3,11 @@ Auth API routes — register, login, and user profile.
 """
 import re
 import secrets
+from typing import Optional
 from datetime import datetime, timezone
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, status, Cookie, Response
+from fastapi.responses import RedirectResponse
+import httpx
 from langsmith import expect
 from sqlalchemy.exc import SQLAlchemyError
 from sqlalchemy.orm import Session
@@ -456,3 +459,205 @@ def get_auth_config():
     return {
         "google_client_id": settings.GOOGLE_CLIENT_ID
     }
+
+
+def _unique_google_username(email: str, db: Session) -> str:
+    """
+    Generate a unique username based on the email.
+    """
+    base = email.split("@")[0]
+    base = re.sub(r"[^a-zA-Z0-9_-]", "", base)
+    base = base[:70]
+    candidate = base
+    suffix = 1
+
+    while db.query(User).filter(User.username == candidate).first():
+        suffix += 1
+        suffix_text = f"-{suffix}"
+        candidate = f"{base[:80 - len(suffix_text)]}{suffix_text}"
+
+    return candidate
+
+
+@router.get("/login/huggingface")
+def huggingface_login(response: Response):
+    """
+    Generates a secure state, stores it in an HttpOnly cookie,
+    and returns the Hugging Face OAuth authorization URL.
+    """
+    if not settings.HF_CLIENT_ID or not settings.HF_REDIRECT_URI:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Hugging Face OAuth is not configured",
+        )
+
+    # Generate CSRF state
+    state = secrets.token_urlsafe(32)
+
+    # Store state in cookie (valid for 10 minutes)
+    response.set_cookie(
+        key="oauth_state",
+        value=state,
+        httponly=True,
+        secure=settings.ENVIRONMENT == "production",
+        samesite="lax",
+        max_age=600,  # 10 minutes
+    )
+
+    # Build Hugging Face authorize URL
+    scope = "openid profile email"
+    auth_url = (
+        f"https://huggingface.co/oauth/authorize?"
+        f"client_id={settings.HF_CLIENT_ID}&"
+        f"redirect_uri={settings.HF_REDIRECT_URI}&"
+        f"scope={scope}&"
+        f"state={state}&"
+        f"response_type=code"
+    )
+
+    return {"url": auth_url}
+
+
+@router.get("/callback/huggingface")
+async def huggingface_callback(
+    code: str,
+    state: str,
+    response: Response,
+    oauth_state: Optional[str] = Cookie(None),
+    db: Session = Depends(get_db),
+):
+    """
+    Verifies state, exchanges code for access token,
+    gets user info, upserts user, sets HttpOnly JWT cookies,
+    and redirects to the frontend dashboard.
+    """
+    # 1. Verify CSRF State
+    if not oauth_state or state != oauth_state:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="State verification failed. Possible CSRF attack.",
+        )
+
+    # 2. Exchange code for access_token via Hugging Face API
+    token_url = "https://huggingface.co/oauth/token"
+    headers = {"Content-Type": "application/x-www-form-urlencoded"}
+    data = {
+        "grant_type": "authorization_code",
+        "code": code,
+        "redirect_uri": settings.HF_REDIRECT_URI,
+        "client_id": settings.HF_CLIENT_ID,
+        "client_secret": settings.HF_CLIENT_SECRET,
+    }
+
+    async with httpx.AsyncClient() as client:
+        try:
+            token_response = await client.post(token_url, headers=headers, data=data)
+            token_response.raise_for_status()
+            token_data = token_response.json()
+        except httpx.HTTPStatusError as e:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail=f"Failed to exchange code: {e.response.text}",
+            )
+        except Exception as e:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=f"Token exchange error: {str(e)}",
+            )
+
+    hf_access_token = token_data.get("access_token")
+    if not hf_access_token:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="No access token returned from Hugging Face",
+        )
+
+    # 3. Fetch user profile data via /oauth/userinfo
+    userinfo_url = "https://huggingface.co/oauth/userinfo"
+    userinfo_headers = {"Authorization": f"Bearer {hf_access_token}"}
+
+    async with httpx.AsyncClient() as client:
+        try:
+            userinfo_response = await client.get(userinfo_url, headers=userinfo_headers)
+            userinfo_response.raise_for_status()
+            user_data = userinfo_response.json()
+        except Exception as e:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=f"Failed to retrieve Hugging Face user info: {str(e)}",
+            )
+
+    email = user_data.get("email")
+    username = user_data.get("preferred_username") or user_data.get("username") or user_data.get("name")
+
+    if not email:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Hugging Face account email is required but not provided",
+        )
+
+    email = email.lower()
+    if not username:
+        username = email.split("@")[0]
+
+    # 4. Upsert user in the DB
+    user = db.query(User).filter(User.email == email).first()
+    if not user:
+        # Check if username is already taken
+        username = _unique_google_username(email, db)
+        user = User(
+            username=username,
+            email=email,
+            hashed_password=hash_password(secrets.token_urlsafe(32)),
+        )
+        db.add(user)
+        db.commit()
+        db.refresh(user)
+
+    user.last_login = datetime.now(timezone.utc)
+    db.commit()
+    db.refresh(user)
+
+    # 5. Generate secure session JWT tokens for our app
+    access_token = create_access_token(user.id)
+    refresh_token = create_refresh_token(user.id)
+
+    # 6. Set tokens as HttpOnly cookies and Redirect
+    redirect_dest = f"{settings.FRONTEND_URL}/dashboard" if settings.ENVIRONMENT == "development" else "/dashboard"
+    response = RedirectResponse(
+        url=redirect_dest,
+        status_code=status.HTTP_307_TEMPORARY_REDIRECT,
+    )
+
+    response.set_cookie(
+        key="access_token",
+        value=access_token,
+        httponly=True,
+        secure=settings.ENVIRONMENT == "production",
+        samesite="lax",
+        max_age=settings.JWT_ACCESS_EXPIRY_MINUTES * 60,
+    )
+
+    response.set_cookie(
+        key="refresh_token",
+        value=refresh_token,
+        httponly=True,
+        secure=settings.ENVIRONMENT == "production",
+        samesite="lax",
+        max_age=settings.JWT_REFRESH_EXPIRY_DAYS * 24 * 60 * 60,
+    )
+
+    # Delete the oauth_state cookie
+    response.delete_cookie(key="oauth_state")
+
+    return response
+
+
+@router.post("/logout")
+def logout(response: Response):
+    """
+    Logs out the user by clearing the secure session cookies.
+    """
+    response.delete_cookie(key="access_token")
+    response.delete_cookie(key="refresh_token")
+    return {"message": "Successfully logged out"}

backend/tests/test_auth.py

@@ -122,3 +122,80 @@ def test_hf_token_appears_in_user_response(client, auth_headers, user, db_sessio
     stored_token = row[0]
     assert stored_token is not None
     assert stored_token != "hf_persist_token"
+
+
+from unittest.mock import patch, AsyncMock, MagicMock
+import urllib.parse
+
+def test_huggingface_login(client):
+    from app.config import get_settings
+    settings = get_settings()
+    settings.HF_CLIENT_ID = "test-client-id"
+    settings.HF_REDIRECT_URI = "http://localhost:8000/api/v1/auth/callback/huggingface"
+
+    response = client.get("/api/v1/auth/login/huggingface")
+    assert response.status_code == 200
+    data = response.json()
+    assert "url" in data
+    assert "test-client-id" in data["url"]
+    assert "oauth_state" in response.cookies
+
+
+@patch("httpx.AsyncClient.post")
+@patch("httpx.AsyncClient.get")
+def test_huggingface_callback_success(mock_get, mock_post, client):
+    from app.config import get_settings
+    settings = get_settings()
+    settings.HF_CLIENT_ID = "test-client-id"
+    settings.HF_CLIENT_SECRET = "test-client-secret"
+    settings.HF_REDIRECT_URI = "http://localhost:8000/api/v1/auth/callback/huggingface"
+
+    mock_post_resp = MagicMock()
+    mock_post_resp.status_code = 200
+    mock_post_resp.json.return_value = {"access_token": "hf-access-token"}
+    mock_post.return_value = mock_post_resp
+
+    mock_get_resp = MagicMock()
+    mock_get_resp.status_code = 200
+    mock_get_resp.json.return_value = {
+        "email": "hfuser@example.com",
+        "preferred_username": "hfuser"
+    }
+    mock_get.return_value = mock_get_resp
+
+    login_response = client.get("/api/v1/auth/login/huggingface")
+    state_cookie = login_response.cookies["oauth_state"]
+    url = login_response.json()["url"]
+    parsed = urllib.parse.urlparse(url)
+    queries = urllib.parse.parse_qs(parsed.query)
+    state_param = queries["state"][0]
+
+    client.cookies.set("oauth_state", state_cookie)
+    callback_response = client.get(
+        f"/api/v1/auth/callback/huggingface?code=hf-code&state={state_param}",
+        follow_redirects=False
+    )
+
+    assert callback_response.status_code == 307
+    assert "/dashboard" in callback_response.headers["location"]
+    assert "access_token" in callback_response.cookies
+    assert "refresh_token" in callback_response.cookies
+
+
+def test_huggingface_callback_invalid_state(client):
+    response = client.get(
+        "/api/v1/auth/callback/huggingface?code=hf-code&state=invalid-state",
+        cookies={"oauth_state": "actual-state"}
+    )
+    assert response.status_code == 400
+    assert "State verification failed" in response.json()["detail"]
+
+
+def test_huggingface_logout(client):
+    response = client.post(
+        "/api/v1/auth/logout",
+        cookies={"access_token": "token-value", "refresh_token": "refresh-value"}
+    )
+    assert response.status_code == 200
+    assert response.cookies.get("access_token") in (None, "")
+    assert response.cookies.get("refresh_token") in (None, "")

frontend/package-lock.json

@@ -83,7 +83,6 @@
       "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.29.0.tgz",
       "integrity": "sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@babel/code-frame": "^7.29.0",
         "@babel/generator": "^7.29.0",
@@ -677,7 +676,6 @@
       "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
       "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -2112,7 +2110,6 @@
       "resolved": "https://registry.npmjs.org/@noble/ciphers/-/ciphers-1.3.0.tgz",
       "integrity": "sha512-2I0gnIVPtfnMw9ee9h1dJG7tp81+8Ob3OJb3Mv37rx5L40/b0i7djjCVvGOVqc9AEIQyvyu1i6ypKdFw8R8gQw==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": "^14.21.3 || >=16"
       },
@@ -2220,7 +2217,6 @@
       "integrity": "sha512-O71yZIbAh/PxDMNGns37GHBIfrVkEVyn+AXyIa5dOTfb4/xNvRWV+Vv/NMbNCtODB/pO7vLlF2OTmMVLhmr7Ag==",
       "devOptional": true,
       "license": "Apache-2.0",
-      "peer": true,
       "dependencies": {
         "playwright": "1.60.0"
       },
@@ -2689,7 +2685,6 @@
       "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.39.tgz",
       "integrity": "sha512-orrrD74MBUyK8jOAD/r0+lfa1I2MO6I+vAkmAWzMYbCcgrN4lCrmK52gRFQq/JRxfYPfonkr4b0jcY7Olqdqbw==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "undici-types": "~6.21.0"
       }
@@ -2699,7 +2694,6 @@
       "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.14.tgz",
       "integrity": "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "csstype": "^3.2.2"
       }
@@ -2786,7 +2780,6 @@
       "integrity": "sha512-TI1XGwKbDpo9tRW8UDIXCOeLk55qe9ZFGs8MTKU6/M08HWTw52DD/IYhfQtOEhEdPhLMT26Ka/x7p70nd3dzDg==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@typescript-eslint/scope-manager": "8.59.0",
         "@typescript-eslint/types": "8.59.0",
@@ -3331,7 +3324,6 @@
       "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -3786,7 +3778,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "baseline-browser-mapping": "^2.10.12",
         "caniuse-lite": "^1.0.30001782",
@@ -4838,7 +4829,6 @@
       "integrity": "sha512-XoMjdBOwe/esVgEvLmNsD3IRHkm7fbKIUGvrleloJXUZgDHig2IPWNniv+GwjyJXzuNqVjlr5+4yVUZjycJwfQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.8.0",
         "@eslint-community/regexpp": "^4.12.1",
@@ -5024,7 +5014,6 @@
       "integrity": "sha512-whOE1HFo/qJDyX4SnXzP4N6zOWn79WhnCUY/iDR0mPfQZO8wcYE4JClzI2oZrhBnnMUCBCHZhO6VQyoBU95mZA==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@rtsao/scc": "^1.1.0",
         "array-includes": "^3.1.9",
@@ -5324,7 +5313,6 @@
       "resolved": "https://registry.npmjs.org/express/-/express-5.2.1.tgz",
       "integrity": "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "accepts": "^2.0.0",
         "body-parser": "^2.2.1",
@@ -6149,7 +6137,6 @@
       "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.14.tgz",
       "integrity": "sha512-am5zfg3yu6sqn5yjKBNqhnTX7Cv+m00ox+7jbaKkrLMRJ4rAdldd1xPd/JzbBWspqaQv6RSTrgFN95EsfhC+7w==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=16.9.0"
       }
@@ -6234,7 +6221,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "peerDependencies": {
         "typescript": "^5 || ^6"
       },
@@ -9591,7 +9577,6 @@
       "resolved": "https://registry.npmjs.org/react/-/react-19.2.4.tgz",
       "integrity": "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=0.10.0"
       }
@@ -9601,7 +9586,6 @@
       "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.4.tgz",
       "integrity": "sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "scheduler": "^0.27.0"
       },
@@ -10926,7 +10910,6 @@
       "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -11195,7 +11178,6 @@
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "devOptional": true,
       "license": "Apache-2.0",
-      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -11878,7 +11860,6 @@
       "resolved": "https://registry.npmjs.org/zod/-/zod-4.3.6.tgz",
       "integrity": "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==",
       "license": "MIT",
-      "peer": true,
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"
       }

frontend/src/app/dashboard/page.tsx

@@ -53,7 +53,7 @@ export interface DocInfo {
 }
 
 export default function DashboardPage() {
-  const { user, loading } = useAuth();
+  const { user, loading, initialized } = useAuth();
   const router = useRouter();
 
   const [documents, setDocuments] = useState<DocInfo[]>([]);
@@ -63,10 +63,10 @@ export default function DashboardPage() {
   const [viewerOpen, setViewerOpen] = useState(true);
   const [connectionError, setConnectionError] = useState("");
 
-    // Auth guard
+  // Auth guard
   useEffect(() => {
-    if (!loading && !user) router.replace("/login");
-  }, [user, loading, router]);
+    if (initialized && !user) router.replace("/login");
+  }, [user, initialized, router]);
 
   // Intercept dashboard if Hugging Face token configuration is missing
   useEffect(() => {
@@ -116,7 +116,7 @@ export default function DashboardPage() {
     return () => clearInterval(interval);
   }, [documents, loadDocuments]);
 
-  if (loading || !user) {
+  if (!initialized || !user) {
     return (
       <div className="min-h-screen flex items-center justify-center">
         <div className="animate-pulse-glow w-12 h-12 rounded-full bg-primary/20" />

frontend/src/app/login/page.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useState } from "react";
+import { useCallback, useState, useEffect } from "react";
 import { useRouter } from "next/navigation";
 import { useAuth } from "@/lib/auth";
 import { useTranslation } from "react-i18next";
@@ -10,9 +10,10 @@ import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/com
 import { Brain, Eye, EyeOff } from "lucide-react";
 import Link from "next/link";
 import GoogleSignInButton from "@/components/auth/GoogleSignInButton";
+import HuggingFaceSignInButton from "@/components/auth/HuggingFaceSignInButton";
 
 export default function LoginPage() {
-  const { login } = useAuth();
+  const { login, user, initialized } = useAuth();
   const { t } = useTranslation();
   const router = useRouter();
   const [email, setEmail] = useState("");
@@ -21,6 +22,13 @@ export default function LoginPage() {
   const [error, setError] = useState("");
   const [loading, setLoading] = useState(false);
 
+  // Redirect if already logged in
+  useEffect(() => {
+    if (initialized && user) {
+      router.replace("/dashboard");
+    }
+  }, [user, initialized, router]);
+
   const handleGoogleSuccess = useCallback(() => {
     router.replace("/dashboard");
   }, [router]);
@@ -58,13 +66,25 @@ export default function LoginPage() {
         </CardHeader>
 
         <CardContent>
-          <div className="mb-4">
+          <div className="flex flex-col gap-2.5 mb-4">
+            <HuggingFaceSignInButton onError={setError} />
             <GoogleSignInButton
               onError={setError}
               onSuccess={handleGoogleSuccess}
             />
           </div>
 
+          <div className="relative my-5">
+            <div className="absolute inset-0 flex items-center">
+              <span className="w-full border-t border-border/40" />
+            </div>
+            <div className="relative flex justify-center text-xs uppercase">
+              <span className="bg-card px-2.5 text-muted-foreground text-[10px] tracking-wider font-semibold">
+                Or continue with
+              </span>
+            </div>
+          </div>
+
           <form onSubmit={handleSubmit} className="space-y-4">
             {error && (
               <div className="p-3 rounded-lg bg-destructive/10 border border-destructive/30 text-sm text-destructive">

frontend/src/app/register/page.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useState } from "react";
+import { useCallback, useState, useEffect } from "react";
 import { useRouter } from "next/navigation";
 import { useAuth } from "@/lib/auth";
 import { useTranslation } from "react-i18next";
@@ -10,9 +10,10 @@ import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/com
 import { Brain, Eye, EyeOff } from "lucide-react";
 import Link from "next/link";
 import GoogleSignInButton from "@/components/auth/GoogleSignInButton";
+import HuggingFaceSignInButton from "@/components/auth/HuggingFaceSignInButton";
 
 export default function RegisterPage() {
-  const { register } = useAuth();
+  const { register, user, initialized } = useAuth();
   const { t } = useTranslation();
   const router = useRouter();
   const [username, setUsername] = useState("");
@@ -22,6 +23,13 @@ export default function RegisterPage() {
   const [error, setError] = useState("");
   const [loading, setLoading] = useState(false);
 
+  // Redirect if already logged in
+  useEffect(() => {
+    if (initialized && user) {
+      router.replace("/dashboard");
+    }
+  }, [user, initialized, router]);
+
   const handleGoogleSuccess = useCallback(() => {
     router.replace("/dashboard");
   }, [router]);
@@ -58,7 +66,8 @@ export default function RegisterPage() {
         </CardHeader>
 
         <CardContent>
-          <div className="mb-4">
+          <div className="flex flex-col gap-2.5 mb-4">
+            <HuggingFaceSignInButton onError={setError} />
             <GoogleSignInButton
               onError={setError}
               onSuccess={handleGoogleSuccess}

frontend/src/components/auth/HuggingFaceSignInButton.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import { useState } from "react";
+import { Button } from "@/components/ui/button";
+import { api } from "@/lib/api";
+
+type HuggingFaceSignInButtonProps = {
+  onError: (message: string) => void;
+};
+
+export default function HuggingFaceSignInButton({ onError }: HuggingFaceSignInButtonProps) {
+  const [loading, setLoading] = useState(false);
+
+  const handleLogin = async () => {
+    setLoading(true);
+    try {
+      // 1. Fetch the Hugging Face OAuth authorization URL from backend
+      const data = await api.get<{ url: string }>("/api/v1/auth/login/huggingface");
+      if (data.url) {
+        // 2. Redirect the user's browser to Hugging Face
+        window.location.href = data.url;
+      } else {
+        onError("Could not retrieve authorization URL from backend.");
+        setLoading(false);
+      }
+    } catch (error) {
+      onError(
+        error instanceof Error
+          ? error.message
+          : "An error occurred while connecting to Hugging Face OAuth."
+      );
+      setLoading(false);
+    }
+  };
+
+  return (
+    <Button
+      onClick={handleLogin}
+      disabled={loading}
+      variant="outline"
+      className="w-full h-11 bg-card/45 backdrop-blur-md border border-border/60 hover:border-[#FFD21E]/60 hover:bg-[#FFD21E]/5 hover:shadow-[0_0_15px_-3px_rgba(255,210,30,0.18)] text-foreground hover:text-[#FFD21E] transition-all duration-300 shadow-sm relative group flex items-center justify-center gap-2.5 font-semibold rounded-xl overflow-hidden active:scale-[0.98] cursor-pointer"
+    >
+      {loading ? (
+        <span className="w-5 h-5 border-2 border-[#FFD21E]/30 border-t-[#FFD21E] rounded-full animate-spin mr-1" />
+      ) : (
+        <svg
+          className="w-5 h-5 transition-transform duration-300 group-hover:scale-110 fill-current text-[#FFD21E]"
+          viewBox="0 0 24 24"
+          xmlns="http://www.w3.org/2000/svg"
+        >
+          <title>Hugging Face</title>
+          <path d="M12.025 1.13c-5.77 0-10.449 4.647-10.449 10.378 0 1.112.178 2.181.503 3.185.064-.222.203-.444.416-.577a.96.96 0 0 1 .524-.15c.293 0 .584.124.84.284.278.173.48.408.71.694.226.282.458.611.684.951v-.014c.017-.324.106-.622.264-.874s.403-.487.762-.543c.3-.047.596.06.787.203s.31.313.4.467c.15.257.212.468.233.542.01.026.653 1.552 1.657 2.54.616.605 1.01 1.223 1.082 1.912.055.537-.096 1.059-.38 1.572.637.121 1.294.187 1.967.187.657 0 1.298-.063 1.921-.178-.287-.517-.44-1.041-.384-1.581.07-.69.465-1.307 1.081-1.913 1.004-.987 1.647-2.513 1.657-2.539.021-.074.083-.285.233-.542.09-.154.208-.323.4-.467a1.08 1.08 0 0 1 .787-.203c.359.056.604.29.762.543s.247.55.265.874v.015c.225-.34.457-.67.683-.952.23-.286.432-.52.71-.694.257-.16.547-.284.84-.285a.97.97 0 0 1 .524.151c.228.143.373.388.43.625l.006.04a10.3 10.3 0 0 0 .534-3.273c0-5.731-4.678-10.378-10.449-10.378M8.327 6.583a1.5 1.5 0 0 1 .713.174 1.487 1.487 0 0 1 .617 2.013c-.183.343-.762-.214-1.102-.094-.38.134-.532.914-.917.71a1.487 1.487 0 0 1 .69-2.803m7.486 0a1.487 1.487 0 0 1 .689 2.803c-.385.204-.536-.576-.916-.71-.34-.12-.92.437-1.103.094a1.487 1.487 0 0 1 .617-2.013 1.5 1.5 0 0 1 .713-.174m-10.68 1.55a.96.96 0 1 1 0 1.921.96.96 0 0 1 0-1.92m13.838 0a.96.96 0 1 1 0 1.92.96.96 0 0 1 0-1.92M8.489 11.458c.588.01 1.965 1.157 3.572 1.164 1.607-.007 2.984-1.155 3.572-1.164.196-.003.305.12.305.454 0 .886-.424 2.328-1.563 3.202-.22-.756-1.396-1.366-1.63-1.32q-.011.001-.02.006l-.044.026-.01.008-.03.024q-.018.017-.035.036l-.032.04a1 1 0 0 0-.058.09l-.014.025q-.049.088-.11.19a1 1 0 0 1-.083.116 1.2 1.2 0 0 1-.173.18q-.035.029-.075.058a1.3 1.3 0 0 1-.251-.243 1 1 0 0 1-.076-.107c-.124-.193-.177-.363-.337-.444-.034-.016-.104-.008-.2.022q-.094.03-.216.087-.06.028-.125.063l-.13.074q-.067.04-.136.086a3 3 0 0 0-.135.096 3 3 0 0 0-.26.219 2 2 0 0 0-.12.121 2 2 0 0 0-.106.128l-.002.002a2 2 0 0 0-.09.132l-.001.001a1.2 1.2 0 0 0-.105.212q-.013.036-.024.073c-1.139-.875-1.563-2.317-1.563-3.203 0-.334.109-.457.305-.454m.836 10.354c.824-1.19.766-2.082-.365-3.194-1.13-1.112-1.789-2.738-1.789-2.738s-.246-.945-.806-.858-.97 1.499.202 2.362c1.173.864-.233 1.45-.685.64-.45-.812-1.683-2.896-2.322-3.295s-1.089-.175-.938.647 2.822 2.813 2.562 3.244-1.176-.506-1.176-.506-2.866-2.567-3.49-1.898.473 1.23 2.037 2.16c1.564.932 1.686 1.178 1.464 1.53s-3.675-2.511-4-1.297c-.323 1.214 3.524 1.567 3.287 2.405-.238.839-2.71-1.587-3.216-.642-.506.946 3.49 2.056 3.522 2.064 1.29.33 4.568 1.028 5.713-.624m5.349 0c-.824-1.19-.766-2.082.365-3.194 1.13-1.112 1.789-2.738 1.789-2.738s.246-.945.806-.858.97 1.499-.202 2.362c-1.173.864.233 1.45.685.64.451-.812 1.683-2.896 2.322-3.295s1.089-.175.938.647-2.822 2.813-2.562 3.244 1.176-.506 1.176-.506 2.866-2.567 3.49-1.898-.473 1.23-2.037 2.16c-1.564.932-1.686 1.178-1.464 1.53s3.675-2.511 4-1.297c.323 1.214-3.524 1.567-3.287 2.405.238.839 2.71-1.587 3.216-.642.506.946-3.49 2.056-3.522 2.064-1.29.33-4.568 1.028-5.713-.624" />
+        </svg>
+      )}
+      <span className="truncate">Sign in with Hugging Face</span>
+    </Button>
+  );
+}

frontend/src/lib/api.ts

@@ -39,7 +39,7 @@ class ApiClient {
     };
 
     const authToken = token || this.getToken();
-    if (authToken) {
+    if (authToken && authToken !== "cookie") {
       headers["Authorization"] = `Bearer ${authToken}`;
     }
 
@@ -48,7 +48,11 @@ class ApiClient {
 
   private async fetchWithConnectionError(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
     try {
-      return await fetch(input, init);
+      const mergedInit = {
+        credentials: "include" as const,
+        ...init,
+      };
+      return await fetch(input, mergedInit);
     } catch (error) {
       if (error instanceof TypeError) {
         throw new Error(CONNECTION_ERROR_MESSAGE);
@@ -201,29 +205,6 @@ class ApiClient {
     return res.json();
   }
 
-  async put<T>(path: string, body?: unknown, options?: FetchOptions): Promise<T> {
-    const res = await this.fetchWithConnectionError(`${this.baseUrl}${path}`, {
-      method: "PUT",
-      headers: this.getHeaders(options?.token),
-      body: body ? JSON.stringify(body) : undefined,
-      ...options,
-    });
-
-    // Auto-refresh on 401
-    if (res.status === 401 && !options?._skipRefresh) {
-      const newToken = await this.tryRefreshToken();
-      if (newToken) {
-        return this.put<T>(path, body, { ...options, token: newToken, _skipRefresh: true });
-      }
-    }
-
-    if (!res.ok) {
-      throw new Error(await this.getErrorMessage(res, res.statusText || "Request failed"));
-    }
-
-    return res.json();
-  }
-
   async postForm<T>(path: string, formData: FormData, options?: FetchOptions): Promise<T> {
     const token = options?.token || this.getToken();
     const headers: HeadersInit = {};

frontend/src/store/auth-store.ts

@@ -8,7 +8,6 @@ export interface AuthUser {
   username: string;
   email: string;
   is_admin: boolean;
-  hf_token?: string;
   created_at: string;
 }
 
@@ -24,7 +23,6 @@ interface AuthStore {
   initializeAuth: () => Promise<void>;
   syncTokensRefreshed: (detail?: { accessToken?: string; user?: AuthUser | null }) => void;
   syncLoggedOut: () => void;
-  setHfToken: (hfToken: string) => Promise<void>;
 }
 
 const getStoredToken = () =>
@@ -90,7 +88,12 @@ export const useAuthStore = create<AuthStore>((set, get) => ({
     });
   },
 
-  logout() {
+  async logout() {
+    try {
+      await api.post("/api/v1/auth/logout");
+    } catch {
+      // Ignore network errors on logout
+    }
     clearStoredTokens();
     set({
       token: null,
@@ -105,16 +108,19 @@ export const useAuthStore = create<AuthStore>((set, get) => ({
     if (initialized) return;
 
     const storedToken = token ?? getStoredToken();
-    if (!storedToken) {
-      set({ token: null, user: null, loading: false, initialized: true });
-      return;
-    }
-
-    set({ token: storedToken, loading: true });
+    set({ loading: true });
 
     try {
-      const user = await api.get<AuthUser>("/api/v1/auth/me", { token: storedToken });
-      set({ user, token: storedToken, loading: false, initialized: true });
+      const user = await api.get<AuthUser>(
+        "/api/v1/auth/me",
+        storedToken ? { token: storedToken } : undefined
+      );
+      set({
+        user,
+        token: storedToken || "cookie",
+        loading: false,
+        initialized: true,
+      });
     } catch {
       clearStoredTokens();
       set({ user: null, token: null, loading: false, initialized: true });
@@ -140,9 +146,4 @@ export const useAuthStore = create<AuthStore>((set, get) => ({
       initialized: true,
     });
   },
-
-  async setHfToken(hfToken: string) {
-    const response = await api.put<AuthUser>("/api/v1/auth/hf-token", { hf_token: hfToken });
-    set({ user: response });
-  },
 }));