Migrate to client-side OAuth via @huggingface/hub

- Frontend: oauthLoginUrl + oauthHandleRedirectIfPresent for login flow
- Token stored in localStorage, sent via Bearer header + WS query param
- Works in HF Spaces iframes (no third-party cookies needed)
- Backend: user's HF token threaded through Session → tools
- Jobs now run with authenticated user's credentials (not just admin token)
- Fallback to env HF_TOKEN when no user token available

Co-authored-by: Cursor <cursoragent@cursor.com>

agent/core/session.py

@@ -86,6 +86,8 @@ class Session:
         self.is_running = True
         self.current_task: asyncio.Task | None = None
         self.pending_approval: Optional[dict[str, Any]] = None
+        # User's HF OAuth token — set by session_manager after construction
+        self.hf_token: Optional[str] = None
 
         # Session trajectory logging
         self.logged_events: list[dict] = []

agent/tools/jobs_tool.py

@@ -122,8 +122,11 @@ def _filter_uv_install_output(logs: list[str]) -> list[str]:
     return logs
 
 
-def _add_environment_variables(params: Dict[str, Any] | None) -> Dict[str, Any]:
-    token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGINGFACE_HUB_TOKEN") or ""
+def _add_environment_variables(
+    params: Dict[str, Any] | None, user_token: str | None = None
+) -> Dict[str, Any]:
+    # Prefer the authenticated user's OAuth token, fall back to global env var
+    token = user_token or os.environ.get("HF_TOKEN") or os.environ.get("HUGGINGFACE_HUB_TOKEN") or ""
 
     # Start with user-provided env vars, then force-set token last
     result = dict(params or {})
@@ -502,7 +505,7 @@ class HfJobsTool:
                 image=image,
                 command=command,
                 env=args.get("env"),
-                secrets=_add_environment_variables(args.get("secrets")),
+                secrets=_add_environment_variables(args.get("secrets"), self.hf_token),
                 flavor=args.get("hardware_flavor", "cpu-basic"),
                 timeout=args.get("timeout", "30m"),
                 namespace=self.namespace,
@@ -720,7 +723,7 @@ To verify, call this tool with `{{"operation": "inspect", "job_id": "{job_id}"}}
                 command=command,
                 schedule=schedule,
                 env=args.get("env"),
-                secrets=_add_environment_variables(args.get("secrets")),
+                secrets=_add_environment_variables(args.get("secrets"), self.hf_token),
                 flavor=args.get("hardware_flavor", "cpu-basic"),
                 timeout=args.get("timeout", "30m"),
                 namespace=self.namespace,
@@ -1019,8 +1022,12 @@ async def hf_jobs_handler(
                     Event(event_type="tool_log", data={"tool": "hf_jobs", "log": log})
                 )
 
-        # Get token and namespace from HF token
-        hf_token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGINGFACE_HUB_TOKEN")
+        # Prefer the authenticated user's OAuth token, fall back to global env
+        hf_token = (
+            (getattr(session, "hf_token", None) if session else None)
+            or os.environ.get("HF_TOKEN")
+            or os.environ.get("HUGGINGFACE_HUB_TOKEN")
+        )
         namespace = HfApi(token=hf_token).whoami().get("name") if hf_token else None
 
         tool = HfJobsTool(

backend/routes/agent.py

@@ -7,7 +7,7 @@ dependency. In dev mode (no OAUTH_CLIENT_ID), auth is bypassed automatically.
 import logging
 from typing import Any
 
-from fastapi import APIRouter, Depends, HTTPException, WebSocket, WebSocketDisconnect
+from fastapi import APIRouter, Depends, HTTPException, Request, WebSocket, WebSocketDisconnect
 
 from dependencies import get_current_user, get_ws_user
 from litellm import acompletion
@@ -126,13 +126,27 @@ async def generate_title(
 
 
 @router.post("/session", response_model=SessionResponse)
-async def create_session(user: dict = Depends(get_current_user)) -> SessionResponse:
+async def create_session(
+    request: Request, user: dict = Depends(get_current_user)
+) -> SessionResponse:
     """Create a new agent session bound to the authenticated user.
 
+    The user's HF access token is extracted from the Authorization header
+    and stored in the session so that tools (e.g. hf_jobs) can act on
+    behalf of the user.
+
     Returns 503 if the server or user has reached the session limit.
     """
+    # Extract the user's HF token from the Bearer header
+    hf_token = None
+    auth_header = request.headers.get("Authorization", "")
+    if auth_header.startswith("Bearer "):
+        hf_token = auth_header[7:]
+
     try:
-        session_id = await session_manager.create_session(user_id=user["user_id"])
+        session_id = await session_manager.create_session(
+            user_id=user["user_id"], hf_token=hf_token
+        )
     except SessionCapacityError as e:
         raise HTTPException(status_code=503, detail=str(e))
     return SessionResponse(session_id=session_id, ready=True)

backend/session_manager.py

@@ -49,6 +49,7 @@ class AgentSession:
     tool_router: ToolRouter
     submission_queue: asyncio.Queue
     user_id: str = "dev"  # Owner of this session
+    hf_token: str | None = None  # User's HF OAuth token for tool execution
     task: asyncio.Task | None = None
     created_at: datetime = field(default_factory=datetime.utcnow)
     is_active: bool = True
@@ -85,7 +86,7 @@ class SessionManager:
             if s.user_id == user_id and s.is_active
         )
 
-    async def create_session(self, user_id: str = "dev") -> str:
+    async def create_session(self, user_id: str = "dev", hf_token: str | None = None) -> str:
         """Create a new agent session and return its ID.
 
         Session() and ToolRouter() constructors contain blocking I/O
@@ -138,6 +139,9 @@ class SessionManager:
 
         tool_router, session = await asyncio.to_thread(_create_session_sync)
 
+        # Store user's HF token on the session so tools can use it
+        session.hf_token = hf_token
+
         # Create wrapper
         agent_session = AgentSession(
             session_id=session_id,
@@ -145,6 +149,7 @@ class SessionManager:
             tool_router=tool_router,
             submission_queue=submission_queue,
             user_id=user_id,
+            hf_token=hf_token,
         )
 
         async with self._lock:

frontend/package-lock.json

@@ -10,6 +10,7 @@
       "dependencies": {
         "@emotion/react": "^11.13.0",
         "@emotion/styled": "^11.13.0",
+        "@huggingface/hub": "^2.8.1",
         "@mui/icons-material": "^6.1.0",
         "@mui/material": "^6.1.0",
         "react": "^18.3.1",
@@ -1019,6 +1020,30 @@
         "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
       }
     },
+    "node_modules/@huggingface/hub": {
+      "version": "2.8.1",
+      "resolved": "https://registry.npmjs.org/@huggingface/hub/-/hub-2.8.1.tgz",
+      "integrity": "sha512-VAsXdMiIHPteXQJhrwaBEiePTWiJ0zBSymHdnX4J+AijjNN0h3RzGfkKemXcu75gu/TmRLFY9l8+2Tkdmpis0w==",
+      "license": "MIT",
+      "dependencies": {
+        "@huggingface/tasks": "^0.19.82"
+      },
+      "bin": {
+        "hfjs": "dist/cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "cli-progress": "^3.12.0"
+      }
+    },
+    "node_modules/@huggingface/tasks": {
+      "version": "0.19.84",
+      "resolved": "https://registry.npmjs.org/@huggingface/tasks/-/tasks-0.19.84.tgz",
+      "integrity": "sha512-nn8DtUW7EZb4QcV+AdNbggPDbvaN32+FldkJakDVml0Aa18fSWjxePdxaRejfTlJYX9oGanOjQKj++NDVRYFXw==",
+      "license": "MIT"
+    },
     "node_modules/@humanfs/core": {
       "version": "0.19.1",
       "resolved": "https://registry.npmjs.org/@humanfs/core/-/core-0.19.1.tgz",
@@ -2217,6 +2242,16 @@
         "url": "https://github.com/sponsors/epoberezkin"
       }
     },
+    "node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/ansi-styles": {
       "version": "4.3.0",
       "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
@@ -2425,6 +2460,19 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/cli-progress": {
+      "version": "3.12.0",
+      "resolved": "https://registry.npmjs.org/cli-progress/-/cli-progress-3.12.0.tgz",
+      "integrity": "sha512-tRkV3HJ1ASwm19THiiLIXLO7Im7wlTuKnvkYaTkyoAPefqjNg7W7DHKUlGRxy9vxDvbyCYQkQozvptuMkGCg8A==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "string-width": "^4.2.3"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
     "node_modules/clsx": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/clsx/-/clsx-2.1.1.tgz",
@@ -2590,6 +2638,13 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/error-ex": {
       "version": "1.3.4",
       "resolved": "https://registry.npmjs.org/error-ex/-/error-ex-1.3.4.tgz",
@@ -3270,6 +3325,16 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/is-fullwidth-code-point": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
+      "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/is-glob": {
       "version": "4.0.3",
       "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz",
@@ -4976,6 +5041,21 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/stringify-entities": {
       "version": "4.0.4",
       "resolved": "https://registry.npmjs.org/stringify-entities/-/stringify-entities-4.0.4.tgz",
@@ -4990,6 +5070,19 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/strip-json-comments": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz",

frontend/package.json

@@ -12,6 +12,7 @@
   "dependencies": {
     "@emotion/react": "^11.13.0",
     "@emotion/styled": "^11.13.0",
+    "@huggingface/hub": "^2.8.1",
     "@mui/icons-material": "^6.1.0",
     "@mui/material": "^6.1.0",
     "react": "^18.3.1",

frontend/src/hooks/useAuth.ts

@@ -1,31 +1,89 @@
 /**
- * Authentication hook — non-blocking, lazy.
+ * Client-side OAuth using @huggingface/hub.
  *
- * On mount: checks if the user is already authenticated (cookie/dev mode).
- * Does NOT redirect to login automatically — the welcome screen handles that.
- *
- * Exports `triggerLogin()` for components that need to start the OAuth flow
- * (e.g. the "Start Session" button on the welcome screen).
+ * Works inside HF Spaces iframes (no third-party cookies needed).
+ * Token is stored in localStorage and sent via Authorization header.
  */
 
 import { useEffect } from 'react';
+import { oauthLoginUrl, oauthHandleRedirectIfPresent } from '@huggingface/hub';
 import { useAgentStore } from '@/store/agentStore';
+import { logger } from '@/utils/logger';
+
+const TOKEN_KEY = 'hf_oauth_token';
+
+/** Get the stored HF access token (or null). */
+export function getStoredToken(): string | null {
+  try {
+    return localStorage.getItem(TOKEN_KEY);
+  } catch {
+    return null;
+  }
+}
+
+/** Clear the stored token (logout). */
+export function clearStoredToken(): void {
+  try {
+    localStorage.removeItem(TOKEN_KEY);
+  } catch {
+    // Ignore
+  }
+}
 
-/** Redirect to the OAuth login page. */
-export function triggerLogin() {
-  window.location.href = '/auth/login';
+/** Redirect to HF OAuth login. */
+export async function triggerLogin(): Promise<void> {
+  const url = await oauthLoginUrl({
+    scopes: 'openid profile read-repos write-repos manage-repos inference-api jobs',
+  });
+  window.location.href = url;
 }
 
+/**
+ * Hook: on mount, check for OAuth redirect result or existing token.
+ * Sets the user in the agent store when authenticated.
+ */
 export function useAuth() {
   const setUser = useAgentStore((s) => s.setUser);
 
   useEffect(() => {
-    async function checkAuth() {
+    let cancelled = false;
+
+    async function init() {
+      // 1. Check if we're returning from an OAuth redirect
+      const oauthResult = await oauthHandleRedirectIfPresent();
+
+      if (oauthResult) {
+        // Store the access token
+        localStorage.setItem(TOKEN_KEY, oauthResult.accessToken);
+        logger.log('OAuth login successful:', oauthResult.userInfo?.name);
+
+        if (!cancelled) {
+          setUser({
+            authenticated: true,
+            username: oauthResult.userInfo?.name || oauthResult.userInfo?.preferred_username || 'user',
+            name: oauthResult.userInfo?.name,
+            picture: oauthResult.userInfo?.picture,
+          });
+        }
+        return;
+      }
+
+      // 2. Check for existing token in localStorage
+      const token = getStoredToken();
+      if (!token) {
+        // Not logged in — welcome screen will handle login trigger
+        if (!cancelled) setUser(null);
+        return;
+      }
+
+      // 3. Validate the stored token
       try {
-        const response = await fetch('/auth/me', { credentials: 'include' });
-        if (response.ok) {
-          const data = await response.json();
-          if (data.authenticated) {
+        const res = await fetch('/auth/me', {
+          headers: { Authorization: `Bearer ${token}` },
+        });
+        if (res.ok) {
+          const data = await res.json();
+          if (!cancelled && data.authenticated) {
             setUser({
               authenticated: true,
               username: data.username,
@@ -35,28 +93,16 @@ export function useAuth() {
             return;
           }
         }
-
-        // Not authenticated — check if auth is even enabled
-        const statusRes = await fetch('/auth/status', { credentials: 'include' });
-        const statusData = await statusRes.json();
-        if (!statusData.auth_enabled) {
-          // Dev mode — set dev user so the app is usable
-          setUser({ authenticated: true, username: 'dev' });
-          return;
-        }
-
-        // Auth is enabled but user is not logged in.
-        // Don't redirect — let the welcome screen show first.
-        // The user will be prompted to log in when they click "Start Session".
-        setUser(null);
+        // Token invalid — clear it
+        clearStoredToken();
+        if (!cancelled) setUser(null);
       } catch {
-        // Backend not ready — set dev user so the app is usable
-        setUser({ authenticated: true, username: 'dev' });
+        // Backend unreachable in dev — set dev user
+        if (!cancelled) setUser({ authenticated: true, username: 'dev' });
       }
     }
 
-    checkAuth();
+    init();
+    return () => { cancelled = true; };
   }, [setUser]);
-
-  return { triggerLogin };
 }

frontend/src/utils/api.ts

@@ -1,58 +1,62 @@
 /**
- * Centralized API utilities with automatic auth header injection.
+ * Centralized API utilities.
  *
- * In production (OAuth enabled):
- *   - REST calls include the HttpOnly cookie automatically (same-origin)
- *   - WebSocket passes token via query parameter
- *
- * In development (no OAuth):
- *   - Auth is bypassed on the backend, no token needed
+ * Reads the HF OAuth token from localStorage and injects it as
+ * an Authorization: Bearer header on every request.
+ * WebSocket URLs include the token as a query parameter.
  */
 
-/** Get the base URL for API calls (handles dev proxy vs production) */
-function getApiBase(): string {
-  // In development, Vite proxies /api and /auth to the backend
-  // In production, same origin
-  return '';
-}
+import { getStoredToken, triggerLogin } from '@/hooks/useAuth';
 
-/** Wrapper around fetch that includes credentials (cookies) and common headers. */
+/** Wrapper around fetch that includes auth and common headers. */
 export async function apiFetch(
   path: string,
   options: RequestInit = {}
 ): Promise<Response> {
-  const url = `${getApiBase()}${path}`;
-
   const headers: Record<string, string> = {
     'Content-Type': 'application/json',
     ...(options.headers as Record<string, string>),
   };
 
-  const response = await fetch(url, {
+  // Inject Bearer token if available
+  const token = getStoredToken();
+  if (token) {
+    headers['Authorization'] = `Bearer ${token}`;
+  }
+
+  const response = await fetch(path, {
     ...options,
     headers,
-    credentials: 'include', // Send cookies (hf_access_token) with every request
+    credentials: 'include', // Still send cookies for backward compat
   });
 
-  // Handle 401 - redirect to login if auth is required
+  // Handle 401 — trigger login if auth is required
   if (response.status === 401) {
-    const authStatus = await fetch(`${getApiBase()}/auth/status`, {
-      credentials: 'include',
-    });
-    const data = await authStatus.json();
-    if (data.auth_enabled) {
-      window.location.href = '/auth/login';
-      throw new Error('Authentication required — redirecting to login.');
+    try {
+      const authStatus = await fetch('/auth/status');
+      const data = await authStatus.json();
+      if (data.auth_enabled) {
+        await triggerLogin();
+        throw new Error('Authentication required — redirecting to login.');
+      }
+    } catch (e) {
+      if (e instanceof Error && e.message.includes('redirecting')) throw e;
+      // auth/status failed — ignore
     }
   }
 
   return response;
 }
 
-/** Build the WebSocket URL for a session, including auth token if available. */
+/** Build the WebSocket URL for a session, including auth token. */
 export function getWebSocketUrl(sessionId: string): string {
   const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
-  // Always use same origin — Vite proxy (ws: true) handles dev,
-  // same origin works directly in production. No cross-origin issues.
-  return `${protocol}//${window.location.host}/api/ws/${sessionId}`;
+  const base = `${protocol}//${window.location.host}/api/ws/${sessionId}`;
+
+  // Pass token as query param (WebSocket can't set custom headers from browser)
+  const token = getStoredToken();
+  if (token) {
+    return `${base}?token=${encodeURIComponent(token)}`;
+  }
+  return base;
 }