Force OAuth refresh after scope changes (#227)

* Force OAuth refresh after scope changes

Co-authored-by: OpenAI Codex <codex@openai.com>

* Address OAuth scope review comments

Co-authored-by: OpenAI Codex <codex@openai.com>

---------

Co-authored-by: OpenAI Codex <codex@openai.com>

backend/dependencies.py

@@ -7,6 +7,8 @@
 import logging
 import os
 import time
+from collections.abc import Iterable
+from hashlib import sha256
 from typing import Any
 
 import httpx
@@ -37,12 +39,60 @@ DEV_USER: dict[str, Any] = {
 }
 
 INTERNAL_HF_TOKEN_KEY = "_hf_token"
+OAUTH_SCOPE_COOKIE = "hf_oauth_scope_hash"
+REQUIRED_OAUTH_SCOPES: tuple[str, ...] = (
+    "openid",
+    "profile",
+    "read-repos",
+    "write-repos",
+    "contribute-repos",
+    "manage-repos",
+    "write-collections",
+    "inference-api",
+    "jobs",
+    "write-discussions",
+)
 
 # Plan field discovery — log the whoami-v2 shape once at DEBUG so we can
 # confirm the actual key in production without hammering the HF API.
 _WHOAMI_SHAPE_LOGGED = False
 
 
+def normalize_oauth_scopes(scopes: Iterable[str]) -> tuple[str, ...]:
+    """Return stable, de-duplicated OAuth scopes preserving declaration order."""
+    seen: set[str] = set()
+    normalized: list[str] = []
+    for scope in scopes:
+        value = str(scope).strip()
+        if not value or value in seen:
+            continue
+        seen.add(value)
+        normalized.append(value)
+    return tuple(normalized)
+
+
+def configured_oauth_scopes() -> tuple[str, ...]:
+    """Return the scopes this backend should request from HF OAuth.
+
+    Spaces expose README ``hf_oauth_scopes`` through ``OAUTH_SCOPES``. Unioning
+    that value with the app-required scopes keeps the local request and Space
+    metadata in sync while ensuring new required scopes are never omitted.
+    """
+    env_scopes = os.environ.get("OAUTH_SCOPES", "").split()
+    return normalize_oauth_scopes((*env_scopes, *REQUIRED_OAUTH_SCOPES))
+
+
+def oauth_scope_fingerprint(scopes: Iterable[str] | None = None) -> str:
+    """Return a non-secret fingerprint for the current OAuth scope contract."""
+    scope_list = configured_oauth_scopes() if scopes is None else scopes
+    payload = " ".join(sorted(normalize_oauth_scopes(scope_list)))
+    return sha256(payload.encode("utf-8")).hexdigest()[:16]
+
+
+def _cookie_has_current_oauth_scope_marker(request: Request) -> bool:
+    return request.cookies.get(OAUTH_SCOPE_COOKIE) == oauth_scope_fingerprint()
+
+
 async def _validate_token(token: str) -> dict[str, Any] | None:
     """Validate a token against HF OAuth userinfo endpoint.
 
@@ -213,7 +263,8 @@ async def get_current_user(request: Request) -> dict[str, Any]:
     if not AUTH_ENABLED:
         return await _dev_user_from_env()
 
-    # Try Authorization header
+    # Bearer callers manage token lifecycle themselves; only browser cookie
+    # auth is forced through the scope-freshness marker below.
     token = bearer_token_from_header(request.headers.get("Authorization", ""))
     if token:
         user = await _extract_user_from_token(token)
@@ -223,6 +274,15 @@ async def get_current_user(request: Request) -> dict[str, Any]:
     # Try cookie
     token = request.cookies.get("hf_access_token")
     if token:
+        if not _cookie_has_current_oauth_scope_marker(request):
+            logger.info(
+                "Rejecting stale HF OAuth cookie; current scopes require refresh."
+            )
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Authentication scopes changed. Please log in again.",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
         user = await _extract_user_from_token(token)
         if user:
             return user

backend/routes/auth.py

@@ -4,40 +4,47 @@ Handles the OAuth 2.0 authorization code flow with HF as provider.
 After successful auth, sets an HttpOnly cookie with the access token.
 """
 
+import logging
 import os
 import secrets
 import time
 from urllib.parse import urlencode
 
 import httpx
-from dependencies import AUTH_ENABLED, get_current_user
+from dependencies import (
+    AUTH_ENABLED,
+    OAUTH_SCOPE_COOKIE,
+    REQUIRED_OAUTH_SCOPES,
+    configured_oauth_scopes,
+    get_current_user,
+    oauth_scope_fingerprint,
+)
 from fastapi import APIRouter, Depends, HTTPException, Request
 from fastapi.responses import RedirectResponse
 
 router = APIRouter(prefix="/auth", tags=["auth"])
+logger = logging.getLogger(__name__)
 
 # OAuth configuration from environment
 OAUTH_CLIENT_ID = os.environ.get("OAUTH_CLIENT_ID", "")
 OAUTH_CLIENT_SECRET = os.environ.get("OAUTH_CLIENT_SECRET", "")
 OPENID_PROVIDER_URL = os.environ.get("OPENID_PROVIDER_URL", "https://huggingface.co")
-OAUTH_SCOPES = (
-    "openid",
-    "profile",
-    "read-repos",
-    "write-repos",
-    "contribute-repos",
-    "manage-repos",
-    "write-collections",
-    "inference-api",
-    "jobs",
-    "write-discussions",
-)
+OAUTH_SCOPES = configured_oauth_scopes()
 
 # In-memory OAuth state store with expiry (5 min TTL)
 _OAUTH_STATE_TTL = 300
 oauth_states: dict[str, dict] = {}
 
 
+def _missing_required_scopes(token_data: dict) -> set[str]:
+    raw_scopes = token_data.get("scope")
+    if not isinstance(raw_scopes, str) or not raw_scopes.strip():
+        logger.debug("OAuth token response omitted a usable scope field")
+        return set()
+    granted = set(raw_scopes.split())
+    return set(REQUIRED_OAUTH_SCOPES) - granted
+
+
 def _cleanup_expired_states() -> None:
     """Remove expired OAuth states to prevent memory growth."""
     now = time.time()
@@ -131,6 +138,15 @@ async def oauth_callback(
             status_code=500,
             detail="Token exchange succeeded but no access_token was returned.",
         )
+    missing_scopes = _missing_required_scopes(token_data)
+    if missing_scopes:
+        raise HTTPException(
+            status_code=403,
+            detail=(
+                "OAuth token is missing required scopes: "
+                + ", ".join(sorted(missing_scopes))
+            ),
+        )
 
     # Fetch user info (optional — failure is not fatal)
     async with httpx.AsyncClient() as client:
@@ -156,6 +172,15 @@ async def oauth_callback(
         max_age=3600 * 24 * 7,  # 7 days
         path="/",
     )
+    response.set_cookie(
+        key=OAUTH_SCOPE_COOKIE,
+        value=oauth_scope_fingerprint(OAUTH_SCOPES),
+        httponly=True,
+        secure=is_production,
+        samesite="lax",
+        max_age=3600 * 24 * 7,
+        path="/",
+    )
     return response
 
 
@@ -164,6 +189,7 @@ async def logout() -> RedirectResponse:
     """Log out the user by clearing the auth cookie."""
     response = RedirectResponse(url="/")
     response.delete_cookie(key="hf_access_token", path="/")
+    response.delete_cookie(key=OAUTH_SCOPE_COOKIE, path="/")
     return response
 
 

tests/unit/test_auth_token_propagation.py

@@ -6,6 +6,7 @@ from types import SimpleNamespace
 from urllib.parse import parse_qs, urlparse
 
 import pytest
+from fastapi import HTTPException
 
 _BACKEND_DIR = Path(__file__).resolve().parent.parent.parent / "backend"
 if str(_BACKEND_DIR) not in sys.path:
@@ -44,6 +45,52 @@ async def test_current_user_carries_internal_hf_token(monkeypatch):
     assert user[dependencies.INTERNAL_HF_TOKEN_KEY] == "hf-user-token"
 
 
+@pytest.mark.asyncio
+async def test_cookie_auth_requires_current_oauth_scope_marker(monkeypatch):
+    monkeypatch.setattr(dependencies, "AUTH_ENABLED", True)
+
+    request = SimpleNamespace(
+        headers={},
+        cookies={"hf_access_token": "hf-user-token"},
+    )
+
+    with pytest.raises(HTTPException) as exc_info:
+        await dependencies.get_current_user(request)
+
+    assert exc_info.value.status_code == 401
+    assert "scopes changed" in exc_info.value.detail
+
+
+@pytest.mark.asyncio
+async def test_cookie_auth_accepts_current_oauth_scope_marker(monkeypatch):
+    monkeypatch.setattr(dependencies, "AUTH_ENABLED", True)
+    dependencies._token_cache.clear()
+
+    async def fake_validate_token(token):
+        assert token == "hf-user-token"
+        return {"sub": "user-id", "preferred_username": "alice"}
+
+    async def fake_fetch_user_plan(token):
+        assert token == "hf-user-token"
+        return "pro"
+
+    monkeypatch.setattr(dependencies, "_validate_token", fake_validate_token)
+    monkeypatch.setattr(dependencies, "_fetch_user_plan", fake_fetch_user_plan)
+
+    request = SimpleNamespace(
+        headers={},
+        cookies={
+            "hf_access_token": "hf-user-token",
+            dependencies.OAUTH_SCOPE_COOKIE: dependencies.oauth_scope_fingerprint(),
+        },
+    )
+
+    user = await dependencies.get_current_user(request)
+
+    assert user["user_id"] == "user-id"
+    assert user[dependencies.INTERNAL_HF_TOKEN_KEY] == "hf-user-token"
+
+
 @pytest.mark.asyncio
 async def test_auth_me_does_not_expose_internal_hf_token():
     user = {
@@ -73,3 +120,71 @@ async def test_oauth_login_requests_collection_write_scope(monkeypatch):
     scopes = set(params["scope"][0].split())
 
     assert "write-collections" in scopes
+
+
+def test_oauth_callback_detects_missing_required_collection_scope():
+    granted = [scope for scope in auth.OAUTH_SCOPES if scope != "write-collections"]
+
+    assert auth._missing_required_scopes({"scope": " ".join(granted)}) == {
+        "write-collections"
+    }
+
+
+def test_oauth_callback_treats_absent_scope_as_full_grant():
+    assert auth._missing_required_scopes({}) == set()
+
+
+@pytest.mark.asyncio
+async def test_oauth_callback_sets_scope_marker_cookie(monkeypatch):
+    monkeypatch.setenv("SPACE_HOST", "example.hf.space")
+    auth.oauth_states.clear()
+    auth.oauth_states["state"] = {
+        "redirect_uri": "https://example.hf.space/auth/callback",
+        "expires_at": 9999999999,
+    }
+
+    class FakeResponse:
+        def __init__(self, payload):
+            self._payload = payload
+
+        def raise_for_status(self):
+            return None
+
+        def json(self):
+            return self._payload
+
+    class FakeAsyncClient:
+        def __init__(self, *args, **kwargs):
+            pass
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *args):
+            return None
+
+        async def post(self, *args, **kwargs):
+            return FakeResponse(
+                {
+                    "access_token": "hf-user-token",
+                    "scope": " ".join(auth.OAUTH_SCOPES),
+                }
+            )
+
+        async def get(self, *args, **kwargs):
+            return FakeResponse({})
+
+    monkeypatch.setattr(auth.httpx, "AsyncClient", FakeAsyncClient)
+
+    response = await auth.oauth_callback(SimpleNamespace(), code="code", state="state")
+    set_cookies = [
+        value.decode("latin-1")
+        for key, value in response.raw_headers
+        if key == b"set-cookie"
+    ]
+
+    expected = (
+        f"{dependencies.OAUTH_SCOPE_COOKIE}="
+        f"{dependencies.oauth_scope_fingerprint(auth.OAUTH_SCOPES)}"
+    )
+    assert any(cookie.startswith(expected) for cookie in set_cookies)