Add collection OAuth scope (#226)

* Add collection OAuth scope

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

* Document GitHub PR-first workflow

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

* Document Space OAuth scope checks

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

---------

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

AGENTS.md

@@ -24,11 +24,16 @@ Notes:
 
 - For multiline PR descriptions, prefer `gh pr edit <number> --body-file <file>` over inline `--body` so shell quoting, `$` env-var names, backticks, and newlines are preserved correctly.
 
+## GitHub PRs
+
+- Open code changes as GitHub PRs first. Do not push code changes directly to the Hugging Face Space deployment branch or Space remote before the PR has been opened, reviewed, and merged, unless the user explicitly asks to bypass the PR flow.
+
 ## Hugging Face Space Deploys
 
 - The Space remote is `space` and points to `https://huggingface.co/spaces/smolagents/ml-intern`.
 - Deploy GitHub `main` to the Space from the local `space-main` branch by merging `origin/main` into `space-main` with a single merge commit, then pushing `space-main:main` to the `space` remote.
 - Keep the Space-only README frontmatter on `space-main`; `.gitattributes` should contain `README.md merge=ours` and the local repo config should include `merge.ours.driver=true`.
+- Local dev commonly uses a personal `HF_TOKEN`, but the deployed Space uses HF OAuth tokens. When adding Hub features, make sure the Space README `hf_oauth_scopes` frontmatter and the backend OAuth request in `backend/routes/auth.py` include the scopes required by the Hub APIs being called. A feature can work locally with a broad PAT and still fail in production with 403s if OAuth scopes are missing; after changing scopes, users may need to log out and log in again to receive a fresh token.
 - Recommended deploy flow:
 
 ```bash

backend/routes/auth.py

@@ -20,6 +20,18 @@ router = APIRouter(prefix="/auth", tags=["auth"])
 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",
+)
 
 # In-memory OAuth state store with expiry (5 min TTL)
 _OAUTH_STATE_TTL = 300
@@ -69,7 +81,7 @@ async def oauth_login(request: Request) -> RedirectResponse:
     params = {
         "client_id": OAUTH_CLIENT_ID,
         "redirect_uri": get_redirect_uri(request),
-        "scope": "openid profile read-repos write-repos contribute-repos manage-repos inference-api jobs write-discussions",
+        "scope": " ".join(OAUTH_SCOPES),
         "response_type": "code",
         "state": state,
     }

tests/unit/test_auth_token_propagation.py

@@ -3,6 +3,7 @@
 import sys
 from pathlib import Path
 from types import SimpleNamespace
+from urllib.parse import parse_qs, urlparse
 
 import pytest
 
@@ -59,3 +60,16 @@ async def test_auth_me_does_not_expose_internal_hf_token():
         "username": "alice",
         "authenticated": True,
     }
+
+
+@pytest.mark.asyncio
+async def test_oauth_login_requests_collection_write_scope(monkeypatch):
+    monkeypatch.setattr(auth, "OAUTH_CLIENT_ID", "oauth-client")
+    monkeypatch.setenv("SPACE_HOST", "example.hf.space")
+    auth.oauth_states.clear()
+
+    response = await auth.oauth_login(SimpleNamespace())
+    params = parse_qs(urlparse(response.headers["location"]).query)
+    scopes = set(params["scope"][0].split())
+
+    assert "write-collections" in scopes