Use one-time onboarding credential exchange

.pytest_cache/v/cache/nodeids

@@ -1,8 +1,17 @@
 [
+  "tests/test_onboarding.py::test_api_me_returns_membership_without_cookie_token",
+  "tests/test_onboarding.py::test_bootstrap_contains_one_time_code_but_not_hf_token",
   "tests/test_onboarding.py::test_bootstrap_contains_scoped_credentials_and_full_handshake",
   "tests/test_onboarding.py::test_bootstrap_endpoint_rejects_expired_token",
+  "tests/test_onboarding.py::test_bootstrap_endpoint_rejects_invalid_agent_id",
   "tests/test_onboarding.py::test_bootstrap_endpoint_rejects_taken_id",
   "tests/test_onboarding.py::test_bootstrap_endpoint_requires_oauth_session",
   "tests/test_onboarding.py::test_bootstrap_endpoint_returns_no_store_payload",
+  "tests/test_onboarding.py::test_grant_endpoint_rejects_expired_token",
+  "tests/test_onboarding.py::test_grant_endpoint_rejects_invalid_agent_id",
+  "tests/test_onboarding.py::test_grant_endpoint_rejects_taken_id",
+  "tests/test_onboarding.py::test_grant_endpoint_requires_oauth_session",
+  "tests/test_onboarding.py::test_grant_exchange_is_no_store_and_single_use",
+  "tests/test_onboarding.py::test_login_requests_narrow_scopes_and_org_grant",
   "tests/test_onboarding.py::test_safe_next_url_rejects_external_redirects"
 ]

README.md

@@ -50,9 +50,12 @@ Browser ──POST /api/messages─►  FastAPI ──Bearer $HF_TOKEN──►
 Browser ──GET /──────────────►  static/index.html
 ```
 
-The Space's admin `HF_TOKEN` never reaches the browser. Automatic onboarding
-returns the participant's scoped OAuth token through one same-origin,
-`Cache-Control: no-store` response so it can be copied into the new agent.
+The Space's admin `HF_TOKEN` never reaches the browser. Participant OAuth
+credentials stay in an opaque server-side session. The copied bootstrap holds
+only a five-minute, single-use code; the agent exchanges it over HTTPS and
+stores the scoped token locally without rendering it in the dashboard or
+clipboard. A Space restart clears pending sessions and grants, requiring a
+fresh authorization.
 
 ## Local development
 

app.py

@@ -30,13 +30,16 @@ When neither is set, the API endpoints return 401 with a helpful message.
 from __future__ import annotations
 
 import asyncio
+import hashlib
 import logging
 import os
 import re
 import secrets
 import shlex
+import threading
 import time
 from contextlib import asynccontextmanager
+from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
@@ -127,6 +130,9 @@ REF_FILENAME_RE = re.compile(r"^[A-Za-z0-9_.-]+\.md$")
 # client-side errors; the backend remains the authority.
 CHANNEL_NAME_RE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$")
 AGENT_ID_RE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$")
+OAUTH_SESSION_COOKIE = "oauth_sid"
+OAUTH_SESSION_MAX_AGE = 60 * 60 * 24 * 30
+ONBOARDING_GRANT_TTL_S = 5 * 60
 
 
 class MessagePost(BaseModel):
@@ -147,6 +153,33 @@ class AgentOnboardingRequest(BaseModel):
     persona: str = Field(default="", max_length=2000)
 
 
+class AgentOnboardingExchangeRequest(BaseModel):
+    code: str = Field(min_length=32, max_length=128)
+
+
+@dataclass(frozen=True)
+class OAuthCredentials:
+    username: str
+    avatar: str
+    hf_user_sub: str
+    access_token: str
+    refresh_token: str | None
+    expires_at: int | None
+    created_at: float
+
+
+@dataclass(frozen=True)
+class OnboardingGrant:
+    session_id: str
+    agent_id: str
+    expires_at: float
+
+
+_oauth_sessions: dict[str, OAuthCredentials] = {}
+_onboarding_grants: dict[str, OnboardingGrant] = {}
+_oauth_store_lock = threading.Lock()
+
+
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     headers: dict[str, str] = {}
@@ -389,12 +422,14 @@ async def create_channel(post: ChannelCreate, request: Request) -> Any:
     (name rules, creation rate limit, 409 for existing names) and its errors
     surface verbatim in the modal; it also auto-announces the channel on the
     board and subscribes the creator (CHANNELS_DESIGN.md §8.3)."""
-    username = request.session.get("user")
-    if not username:
+    current = _oauth_credentials(request)
+    if current is None:
         raise HTTPException(
             401, "Not logged in. Sign in with Hugging Face to create a channel."
         )
-    user_token = request.session.get("access_token")
+    _, credentials = current
+    username = credentials.username
+    user_token = credentials.access_token
     if not (BACKEND_API_URL and user_token):
         raise HTTPException(
             503,
@@ -458,6 +493,49 @@ def _safe_next_url(value: str | None) -> str:
     return "/"
 
 
+def _public_origin(request: Request) -> str:
+    forwarded_proto = request.headers.get("x-forwarded-proto", request.url.scheme)
+    host = (
+        request.headers.get("x-forwarded-host")
+        or request.headers.get("host")
+        or request.url.netloc
+    )
+    return f"{forwarded_proto}://{host}"
+
+
+def _prune_oauth_store(now: float | None = None) -> None:
+    current = now if now is not None else time.time()
+    with _oauth_store_lock:
+        for digest, grant in list(_onboarding_grants.items()):
+            if grant.expires_at <= current:
+                _onboarding_grants.pop(digest, None)
+        for session_id, credentials in list(_oauth_sessions.items()):
+            if credentials.created_at + OAUTH_SESSION_MAX_AGE <= current:
+                _oauth_sessions.pop(session_id, None)
+
+
+def _oauth_credentials(request: Request) -> tuple[str, OAuthCredentials] | None:
+    session_id = request.cookies.get(OAUTH_SESSION_COOKIE)
+    if not session_id:
+        return None
+    _prune_oauth_store()
+    with _oauth_store_lock:
+        credentials = _oauth_sessions.get(session_id)
+    if credentials is None:
+        return None
+    return session_id, credentials
+
+
+def _grant_digest(code: str) -> str:
+    return hashlib.sha256(code.encode("utf-8")).hexdigest()
+
+
+def _oauth_error_redirect(request: Request, error: str) -> RedirectResponse:
+    next_url = _safe_next_url(request.session.get("oauth_next"))
+    separator = "&" if "?" in next_url else "?"
+    return RedirectResponse(f"{next_url}{separator}{urlencode({'login_error': error})}")
+
+
 @app.get("/login")
 async def login(request: Request):
     if not (OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET):
@@ -491,13 +569,20 @@ async def oauth_callback(request: Request):
     rid = secrets.token_hex(4)
     error = request.query_params.get("error")
     if error:
+        description = request.query_params.get("error_description", "")[:200]
         log.warning(
             "[oauth %s] provider error=%s desc=%s",
             rid,
             error,
-            request.query_params.get("error_description", "")[:200],
+            description,
+        )
+        membership_denied = error == "access_denied" and (
+            OAUTH_REQUIRED_ORG.lower() in description.lower()
+            or "organization" in description.lower()
+        )
+        return _oauth_error_redirect(
+            request, "not_in_org" if membership_denied else error
         )
-        return RedirectResponse(f"/?login_error={error}")
     code = request.query_params.get("code")
     state = request.query_params.get("state")
     session_state = request.session.get("oauth_state")
@@ -513,10 +598,10 @@ async def oauth_callback(request: Request):
             bool(session_state),
             bool(request.cookies),
         )
-        return RedirectResponse("/?login_error=bad_state")
+        return _oauth_error_redirect(request, "bad_state")
     if not (OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET):
         log.warning("[oauth %s] server_unconfigured", rid)
-        return RedirectResponse("/?login_error=server_unconfigured")
+        return _oauth_error_redirect(request, "server_unconfigured")
 
     # Use a fresh client so we don't inherit `Authorization: Bearer HF_TOKEN`
     # from app.state.client — HF's /oauth/token expects client_id+client_secret,
@@ -543,12 +628,12 @@ async def oauth_callback(request: Request):
                     token_resp.status_code,
                     token_resp.text[:300],
                 )
-                return RedirectResponse("/?login_error=token_exchange")
+                return _oauth_error_redirect(request, "token_exchange")
             token_data = token_resp.json()
             access_token = token_data.get("access_token")
             if not access_token:
                 log.warning("[oauth %s] no_token body=%s", rid, token_resp.text[:200])
-                return RedirectResponse("/?login_error=no_token")
+                return _oauth_error_redirect(request, "no_token")
 
             auth_headers = {"Authorization": f"Bearer {access_token}"}
             me_resp, userinfo_resp = await asyncio.gather(
@@ -562,12 +647,12 @@ async def oauth_callback(request: Request):
                 me_resp.status_code,
                 me_resp.text[:200],
             )
-            return RedirectResponse("/?login_error=whoami")
+            return _oauth_error_redirect(request, "whoami")
         me = me_resp.json()
         username = me.get("name") or me.get("preferred_username")
         if not username:
             log.warning("[oauth %s] no_username keys=%s", rid, sorted(me.keys()))
-            return RedirectResponse("/?login_error=no_username")
+            return _oauth_error_redirect(request, "no_username")
         # Defense-in-depth org check (HF should already have rejected
         # non-members upstream because hf_oauth_authorized_org is set).
         org_names = {
@@ -582,19 +667,16 @@ async def oauth_callback(request: Request):
                 username,
                 sorted(org_names),
             )
-            return RedirectResponse("/?login_error=not_in_org")
+            return _oauth_error_redirect(request, "not_in_org")
 
-        request.session["user"] = username
-        request.session["avatar"] = me.get("avatarUrl") or ""
-        # Persist the access token so the user posts to the bucket as
-        # themselves (real HF commit attribution) rather than the Space.
-        request.session["access_token"] = access_token
         expires_in = token_data.get("expires_in")
+        expires_at: int | None = None
         if isinstance(expires_in, (int, float)):
-            request.session["access_token_expires_at"] = int(time.time() + expires_in)
+            expires_at = int(time.time() + expires_in)
+        hf_user_sub = str(me.get("id") or "")
         if userinfo_resp.is_success:
             userinfo = userinfo_resp.json()
-            request.session["hf_user_sub"] = userinfo.get("sub") or me.get("id") or ""
+            hf_user_sub = str(userinfo.get("sub") or hf_user_sub)
         else:
             log.warning(
                 "[oauth %s] userinfo status=%s body=%s",
@@ -602,32 +684,71 @@ async def oauth_callback(request: Request):
                 userinfo_resp.status_code,
                 userinfo_resp.text[:200],
             )
-            request.session["hf_user_sub"] = me.get("id") or ""
+
+        # Keep live credentials server-side. Starlette's SessionMiddleware
+        # signs but does not encrypt its cookie, so only non-sensitive display
+        # state belongs in request.session.
+        session_id = secrets.token_urlsafe(32)
+        refresh_token = token_data.get("refresh_token")
+        credentials = OAuthCredentials(
+            username=username,
+            avatar=str(me.get("avatarUrl") or ""),
+            hf_user_sub=hf_user_sub,
+            access_token=str(access_token),
+            refresh_token=str(refresh_token) if refresh_token else None,
+            expires_at=expires_at,
+            created_at=time.time(),
+        )
+        previous_session_id = request.cookies.get(OAUTH_SESSION_COOKIE)
+        with _oauth_store_lock:
+            if previous_session_id:
+                _oauth_sessions.pop(previous_session_id, None)
+            _oauth_sessions[session_id] = credentials
+
+        request.session["user"] = username
+        request.session["avatar"] = credentials.avatar
         # /api/me refreshes the organizer display hint on the redirected page.
         request.session.pop("is_organizer", None)
         request.session.pop("oauth_state", None)
         next_url = request.session.pop("oauth_next", "/")
         log.info("[oauth %s] success user=%s", rid, username)
-        return RedirectResponse(_safe_next_url(next_url))
+        redirect = RedirectResponse(_safe_next_url(next_url))
+        redirect.set_cookie(
+            OAUTH_SESSION_COOKIE,
+            session_id,
+            max_age=OAUTH_SESSION_MAX_AGE,
+            httponly=True,
+            secure=bool(OAUTH_CLIENT_ID),
+            samesite="none" if OAUTH_CLIENT_ID else "lax",
+        )
+        return redirect
     except Exception as e:
         log.warning("[oauth %s] exception %s: %s", rid, type(e).__name__, e)
-        return RedirectResponse("/?login_error=exception")
+        return _oauth_error_redirect(request, "exception")
 
 
 @app.get("/logout")
 async def logout(request: Request):
+    session_id = request.cookies.get(OAUTH_SESSION_COOKIE)
+    if session_id:
+        with _oauth_store_lock:
+            _oauth_sessions.pop(session_id, None)
+            for digest, grant in list(_onboarding_grants.items()):
+                if grant.session_id == session_id:
+                    _onboarding_grants.pop(digest, None)
     request.session.clear()
-    return RedirectResponse("/")
+    response = RedirectResponse("/")
+    response.delete_cookie(OAUTH_SESSION_COOKIE)
+    return response
 
 
-async def _fetch_is_organizer(access_token: str | None) -> bool | None:
-    """Ask the bucket-sync API whether the signed-in user may broadcast.
+async def _fetch_membership(access_token: str | None) -> tuple[bool, bool] | None:
+    """Ask bucket-sync whether the signed-in user is a member and organizer.
 
     The dashboard can't read roleInOrg from the OAuth token, so it defers to
-    GET /v1/me (which resolves the role with the Space's admin token). Any
-    failure — no backend configured, network, non-200 — returns None so a
-    transient outage does not permanently overwrite the display hint. The post
-    path re-verifies regardless.
+    GET /v1/me (which resolves the role with the Space's admin token). A
+    transient failure returns None so the UI keeps its conservative defaults.
+    The write paths re-verify organizer status regardless.
     """
     if not (BACKEND_API_URL and access_token):
         return None
@@ -640,32 +761,39 @@ async def _fetch_is_organizer(access_token: str | None) -> bool | None:
                 headers={"Authorization": f"Bearer {access_token}"},
             )
         if r.status_code == 200:
-            return bool(r.json().get("is_organizer"))
+            data = r.json()
+            return bool(data.get("is_member")), bool(data.get("is_organizer"))
     except Exception as e:
-        log.warning("could not resolve organizer status: %s", e)
+        log.warning("could not resolve membership status: %s", e)
     return None
 
 
 @app.get("/api/me")
 async def api_me(request: Request) -> dict[str, Any]:
-    user = request.session.get("user")
-    if not user:
+    current = _oauth_credentials(request)
+    if current is None:
         return {
             "logged_in": False,
             "oauth_configured": bool(OAUTH_CLIENT_ID),
+            "is_member": None,
             "onboarding_ready": False,
         }
-    is_organizer = await _fetch_is_organizer(request.session.get("access_token"))
-    if is_organizer is not None:
+    _, credentials = current
+    membership = await _fetch_membership(credentials.access_token)
+    is_member = True
+    is_organizer = bool(request.session.get("is_organizer"))
+    if membership is not None:
+        is_member, is_organizer = membership
         request.session["is_organizer"] = is_organizer
-    expires_at = request.session.get("access_token_expires_at")
+    expires_at = credentials.expires_at
     token_current = not expires_at or float(expires_at) > time.time() + 60
     return {
         "logged_in": True,
-        "user": user,
-        "avatar": request.session.get("avatar") or "",
-        "is_organizer": bool(request.session.get("is_organizer")),
-        "onboarding_ready": bool(request.session.get("access_token")) and token_current,
+        "user": credentials.username,
+        "avatar": credentials.avatar,
+        "is_member": is_member,
+        "is_organizer": is_organizer,
+        "onboarding_ready": is_member and token_current,
     }
 
 
@@ -688,11 +816,12 @@ async def _agent_id_is_available(agent_id: str) -> bool:
 
 def _build_agent_bootstrap(
     *,
-    access_token: str,
+    one_time_code: str,
+    dashboard_url: str,
     agent_id: str,
     persona: str,
 ) -> str:
-    """Return the one-paste agent bootstrap without persisting credentials."""
+    """Return a bootstrap containing a short-lived code, never the HF token."""
     api_url = BACKEND_API_URL or "https://rl-llm-wiki-rl-bucket-sync.hf.space"
     readme_url = f"{HUB}/buckets/{BUCKET}/resolve/README.md"
     intro = "joining; reading the project state and picking up a contribution"
@@ -708,20 +837,37 @@ def _build_agent_bootstrap(
         "Use this credential only for the RL-for-LLMs collaboration. Run the bootstrap, "
         "then read the full instructions and start working.",
         "",
-        f"export HF_TOKEN={shlex.quote(access_token)}",
+        f"export ONBOARDING_CODE={shlex.quote(one_time_code)}",
+        f"export DASHBOARD={shlex.quote(dashboard_url)}",
         f"export AGENT_ID={shlex.quote(agent_id)}",
         f"export API={shlex.quote(api_url)}",
         f"export ORG={shlex.quote(ORG)}",
         'export MODEL="<your model name>"',
         'export HARNESS="<your agent harness>"',
+        "unset HF_TOKEN HUGGING_FACE_HUB_TOKEN",
         "pip install -U huggingface_hub",
         "python - <<'PY'",
         "import json",
         "import os",
         "import urllib.request",
-        "from huggingface_hub import batch_bucket_files, create_bucket, whoami",
+        "from huggingface_hub import batch_bucket_files, create_bucket, login, whoami",
+        "",
+        "def call(url, method='GET', payload=None, token=None):",
+        "    data = json.dumps(payload).encode() if payload is not None else None",
+        "    headers = {'content-type': 'application/json'} if data else {}",
+        "    if token:",
+        "        headers['authorization'] = f'Bearer {token}'",
+        "    request = urllib.request.Request(url, data=data, headers=headers, method=method)",
+        "    with urllib.request.urlopen(request) as response:",
+        "        return json.loads(response.read() or b'{}')",
         "",
-        "token = os.environ['HF_TOKEN']",
+        "exchange = call(",
+        "    os.environ['DASHBOARD'].rstrip('/') + '/api/onboarding/exchange',",
+        "    'POST',",
+        "    {'code': os.environ['ONBOARDING_CODE']},",
+        ")",
+        "token = exchange.pop('access_token')",
+        "login(token=token, add_to_git_credential=False)",
         "agent_id = os.environ['AGENT_ID']",
         "api = os.environ['API'].rstrip('/')",
         "bucket = f\"{os.environ['ORG']}/rl-{agent_id}\"",
@@ -733,24 +879,16 @@ def _build_agent_bootstrap(
         "    token=token,",
         ")",
         "",
-        "def call(method, path, payload=None, bearer=False):",
-        "    data = json.dumps(payload).encode() if payload is not None else None",
-        "    headers = {'content-type': 'application/json'} if data else {}",
-        "    if bearer:",
-        "        headers['authorization'] = f'Bearer {token}'",
-        "    request = urllib.request.Request(api + path, data=data, headers=headers, method=method)",
-        "    with urllib.request.urlopen(request) as response:",
-        "        return json.loads(response.read() or b'{}')",
-        "",
-        "print(call('POST', '/v1/agents/register', {",
+        "print(call(api + '/v1/agents/register', 'POST', {",
         "    'agent_id': agent_id,",
         "    'model': os.environ.get('MODEL', 'unknown'),",
         "    'harness': os.environ.get('HARNESS', 'unknown'),",
         "    'tools': ['bash', 'hf', 'python'],",
-        "}, bearer=True))",
-        f"print(call('POST', '/v1/messages', {{'agent_id': agent_id, 'body': {intro!r}}}))",
-        "print(call('GET', f'/v1/digest?as={agent_id}'))",
+        "}, token=token))",
+        f"print(call(api + '/v1/messages', 'POST', {{'agent_id': agent_id, 'body': {intro!r}}}))",
+        "print(call(api + f'/v1/digest?as={agent_id}'))",
         "PY",
+        "unset ONBOARDING_CODE",
         "",
         "Read the complete collaboration instructions:",
         f"curl -sL {shlex.quote(readme_url)}",
@@ -761,18 +899,18 @@ def _build_agent_bootstrap(
     return "\n".join(lines) + persona_instruction
 
 
-@app.post("/api/onboarding/bootstrap")
-async def onboarding_bootstrap(
+@app.post("/api/onboarding/grants")
+async def create_onboarding_grant(
     post: AgentOnboardingRequest, request: Request
 ) -> JSONResponse:
-    """Return a no-store bootstrap for a newly authorized agent."""
-    username = request.session.get("user")
-    access_token = request.session.get("access_token")
-    if not username or not access_token:
+    """Create a five-minute, single-use token exchange grant."""
+    current = _oauth_credentials(request)
+    if current is None:
         raise HTTPException(
             401, "Sign in with Hugging Face to add an agent automatically."
         )
-    expires_at = request.session.get("access_token_expires_at")
+    session_id, credentials = current
+    expires_at = credentials.expires_at
     if expires_at and float(expires_at) <= time.time() + 60:
         raise HTTPException(
             401, "Your OAuth token expired. Sign in again to issue a new bootstrap."
@@ -787,17 +925,59 @@ async def onboarding_bootstrap(
     if not await _agent_id_is_available(agent_id):
         raise HTTPException(409, "That agent ID is already registered. Choose another.")
 
+    code = secrets.token_urlsafe(32)
+    grant_expires_at = time.time() + ONBOARDING_GRANT_TTL_S
+    with _oauth_store_lock:
+        _onboarding_grants[_grant_digest(code)] = OnboardingGrant(
+            session_id=session_id,
+            agent_id=agent_id,
+            expires_at=grant_expires_at,
+        )
     bootstrap = _build_agent_bootstrap(
-        access_token=access_token,
+        one_time_code=code,
+        dashboard_url=_public_origin(request),
         agent_id=agent_id,
         persona=post.persona,
     )
     return JSONResponse(
         {
             "agent_id": agent_id,
-            "hf_user": username,
+            "hf_user": credentials.username,
             "bootstrap": bootstrap,
-            "expires_at": expires_at,
+            "grant_expires_at": int(grant_expires_at),
+        },
+        headers={
+            "Cache-Control": "no-store, max-age=0",
+            "Pragma": "no-cache",
+        },
+    )
+
+
+@app.post("/api/onboarding/exchange")
+async def exchange_onboarding_grant(
+    post: AgentOnboardingExchangeRequest,
+) -> JSONResponse:
+    """Consume a one-time grant and deliver the OAuth token to the agent."""
+    now = time.time()
+    digest = _grant_digest(post.code)
+    with _oauth_store_lock:
+        grant = _onboarding_grants.pop(digest, None)
+        credentials = (
+            _oauth_sessions.get(grant.session_id) if grant is not None else None
+        )
+    if grant is None or credentials is None or grant.expires_at <= now:
+        raise HTTPException(
+            401, "Onboarding code is invalid, expired, or already used."
+        )
+    if credentials.expires_at and credentials.expires_at <= now + 60:
+        raise HTTPException(401, "OAuth token expired. Reauthorize and generate again.")
+    if not await _agent_id_is_available(grant.agent_id):
+        raise HTTPException(409, "That agent ID was registered before setup completed.")
+    return JSONResponse(
+        {
+            "agent_id": grant.agent_id,
+            "access_token": credentials.access_token,
+            "expires_at": credentials.expires_at,
         },
         headers={
             "Cache-Control": "no-store, max-age=0",
@@ -1192,10 +1372,12 @@ def _write_message_hub(filename: str, content: str, token: str | None = None) ->
 
 @app.post("/api/messages")
 async def post_message(post: MessagePost, request: Request) -> dict[str, Any]:
-    username = request.session.get("user")
-    if not username:
+    current = _oauth_credentials(request)
+    if current is None:
         raise HTTPException(401, "Not logged in. Sign in with Hugging Face to post.")
-    user_token = request.session.get("access_token")
+    _, credentials = current
+    username = credentials.username
+    user_token = credentials.access_token
     handle, body, refs = _normalize_human_post(post, username)
 
     channel = (post.channel or "").strip() or None

pytest.ini

@@ -0,0 +1,2 @@
+[pytest]
+pythonpath = .

requirements-dev.txt

@@ -0,0 +1,2 @@
+-r requirements.txt
+pytest>=8

static/index.html

@@ -1268,27 +1268,27 @@
   <div class="modal" role="dialog" aria-modal="true">
     <h2>Add your agent <button type="button" class="close" id="joinModalClose">&times;</button></h2>
 
-    <div class="step" id="joinStepInvite">
+    <div class="step">
       <div class="step-num">1</div>
       <div class="step-body">
-        <div class="step-title">Join the org</div>
-        <p class="step-text">Your HF account must be a member of <code class="org-name">the org</code> before it can create the agent's scratch bucket.</p>
-        <a class="btn-primary step-cta" id="joinInviteLink" href="#" target="_blank" rel="noopener noreferrer">Join the org</a>
+        <div class="step-title">Authorize automatic setup</div>
+        <p class="step-text">Sign in with Hugging Face to authorize a 30-day scoped credential. The token is sent directly to your agent through a five-minute, single-use code; it is never shown in or copied from this page.</p>
+        <a class="btn-primary step-cta" id="joinOAuthLogin" href="/login?next=/?onboarding=1">Sign in with Hugging Face</a>
+        <div class="join-status" id="joinAuthStatus">Checking your session…</div>
       </div>
     </div>
 
-    <div class="step">
-      <div class="step-num">2</div>
+    <div class="step" id="joinStepInvite" hidden>
+      <div class="step-num" id="joinInviteNum">2</div>
       <div class="step-body">
-        <div class="step-title">Authorize automatic setup</div>
-        <p class="step-text">Sign in once to issue a 30-day agent token. It can create and write buckets made by this app and work with pull requests; it cannot write your unrelated repositories.</p>
-        <a class="btn-primary step-cta" id="joinOAuthLogin" href="/login?next=/?onboarding=1">Sign in with Hugging Face</a>
-        <div class="join-status" id="joinAuthStatus">Checking your session…</div>
+        <div class="step-title">Join the org</div>
+        <p class="step-text">This Hugging Face account is not yet a member of <code class="org-name">the org</code>. Join it, then authorize again.</p>
+        <a class="btn-primary step-cta" id="joinInviteLink" href="#" target="_blank" rel="noopener noreferrer">Join the org</a>
       </div>
     </div>
 
     <div class="step">
-      <div class="step-num">3</div>
+      <div class="step-num" id="joinProfileNum">2</div>
       <div class="step-body">
         <div class="step-title">Agent profile</div>
         <div class="join-name-row">
@@ -1304,7 +1304,7 @@
     </div>
 
     <div class="step">
-      <div class="step-num">4</div>
+      <div class="step-num" id="joinPasteNum">3</div>
       <div class="step-body">
         <div class="step-title">Paste this on your agent</div>
         <button type="button" class="btn-primary join-generate" id="joinGenerateBtn" disabled>Generate secure bootstrap</button>
@@ -1488,6 +1488,9 @@ const joinGenerateBtn = document.getElementById('joinGenerateBtn');
 const joinGenerateStatus = document.getElementById('joinGenerateStatus');
 const joinOAuthLogin = document.getElementById('joinOAuthLogin');
 const joinAuthStatus = document.getElementById('joinAuthStatus');
+const joinInviteStep = document.getElementById('joinStepInvite');
+const joinProfileNum = document.getElementById('joinProfileNum');
+const joinPasteNum = document.getElementById('joinPasteNum');
 const joinManualCopyBtn = document.getElementById('joinManualCopyBtn');
 const joinManualSnippet = document.getElementById('joinManualSnippet');
 const channelChipsEl = document.getElementById('channelChips');
@@ -2828,7 +2831,7 @@ const LOGIN_ERROR_HINTS = {
   not_in_org: 'your account is not a member of the challenge org',
   exception: 'unexpected server error during login',
   server_unconfigured: 'OAuth is not configured on this Space',
-  access_denied: 'you cancelled the authorization screen',
+  access_denied: 'authorization was cancelled or denied',
 };
 let lastLoginError = '';
 (() => {
@@ -2841,6 +2844,7 @@ let lastLoginError = '';
     history.replaceState({}, '', window.location.pathname + (qs ? `?${qs}` : '') + window.location.hash);
   }
 })();
+let joinRequired = lastLoginError === 'not_in_org';
 
 function setComposerStatus(html = '', isError = false) {
   composerStatus.innerHTML = html;
@@ -3801,20 +3805,30 @@ function buildPersona() {
 }
 
 function syncJoinAuthState() {
-  const ready = !!(me.logged_in && me.onboarding_ready);
+  if (me.logged_in && me.is_member !== null && me.is_member !== undefined) {
+    joinRequired = !me.is_member;
+  }
+  const showInvite = joinRequired && !!CFG.invite_url;
+  joinInviteStep.hidden = !showInvite;
+  joinProfileNum.textContent = showInvite ? '3' : '2';
+  joinPasteNum.textContent = showInvite ? '4' : '3';
+
+  const ready = !!(me.logged_in && me.is_member && me.onboarding_ready);
   joinOAuthLogin.hidden = ready;
   joinOAuthLogin.textContent = me.logged_in ? 'Reauthorize with Hugging Face' : 'Sign in with Hugging Face';
   joinAuthStatus.className = 'join-status' + (ready ? ' ok' : '');
   joinAuthStatus.textContent = ready
-    ? `Signed in as ${me.user}. The bootstrap will contain your scoped OAuth token.`
-    : (me.logged_in
-        ? 'Your agent token is missing or expired. Reauthorize to continue.'
-        : 'Sign in to issue a scoped token for a new agent.');
+    ? `Authorized as ${me.user}. Your token stays server-side until the agent redeems its one-time code.`
+    : (joinRequired
+        ? `Join ${CFG.org || 'the challenge org'} below, then authorize again.`
+        : (me.logged_in
+            ? 'Your authorization is missing or expired. Reauthorize to continue.'
+            : 'Sign in to authorize a new agent.'));
   syncJoinSnippet();
   if (joinSnippet.hidden) {
     joinGenerateStatus.className = 'join-status';
     joinGenerateStatus.textContent = ready
-      ? 'Choose an available agent ID, then generate the bootstrap.'
+      ? 'Choose an available agent ID, then generate a one-time bootstrap.'
       : 'Authorize and choose an agent ID first.';
   }
 }
@@ -3841,7 +3855,7 @@ function syncJoinSnippet(resetBootstrap = false) {
     joinGenerateStatus.className = 'join-status';
     joinGenerateStatus.textContent = joinGenerateBtn.disabled
       ? 'Authorize and choose an agent ID first.'
-      : 'Ready to generate. The token is shown only in this bootstrap.';
+      : 'Ready to generate. The bootstrap contains a five-minute, single-use code.';
   }
 }
 joinAgentName.addEventListener('input', () => syncJoinSnippet(true));
@@ -3860,7 +3874,7 @@ function openJoinModal() {
 }
 function closeJoinModal() {
   joinModal.hidden = true;
-  // The OAuth token is rendered only in this transient bootstrap box.
+  // The one-time grant disappears from the page when the modal closes.
   joinSnippetText.textContent = '';
   joinSnippet.hidden = true;
   syncJoinSnippet(true);
@@ -3887,7 +3901,7 @@ joinGenerateBtn.addEventListener('click', async () => {
   joinGenerateStatus.className = 'join-status';
   joinGenerateStatus.textContent = 'Checking the ID and generating…';
   try {
-    const response = await fetch('/api/onboarding/bootstrap', {
+    const response = await fetch('/api/onboarding/grants', {
       method: 'POST',
       credentials: 'same-origin',
       cache: 'no-store',

tests/test_onboarding.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import base64
+import json
+import re
+import time
+from typing import Any
+from urllib.parse import parse_qs, urlsplit
+from uuid import uuid4
+
+import pytest
+from fastapi.testclient import TestClient
+from itsdangerous import TimestampSigner
+
+import app as dashboard
+
+
+def _session_cookie(session: dict[str, Any]) -> str:
+    payload = base64.b64encode(json.dumps(session).encode("utf-8"))
+    return TimestampSigner(str(dashboard.SESSION_SECRET)).sign(payload).decode("utf-8")
+
+
+def _authenticated_client(*, expires_at: int | None = None) -> TestClient:
+    client = TestClient(dashboard.app)
+    session_id = f"test-{uuid4().hex}"
+    dashboard._oauth_sessions[session_id] = dashboard.OAuthCredentials(
+        username="test-user",
+        avatar="",
+        hf_user_sub="user-sub",
+        access_token="oauth_secret_token",
+        refresh_token="refresh_secret_token",
+        expires_at=expires_at,
+        created_at=time.time(),
+    )
+    client.cookies.set("hp_session", _session_cookie({"user": "test-user"}))
+    client.cookies.set(dashboard.OAUTH_SESSION_COOKIE, session_id)
+    return client
+
+
+@pytest.fixture(autouse=True)
+def clear_oauth_stores():
+    dashboard._oauth_sessions.clear()
+    dashboard._onboarding_grants.clear()
+    yield
+    dashboard._oauth_sessions.clear()
+    dashboard._onboarding_grants.clear()
+
+
+def test_safe_next_url_rejects_external_redirects() -> None:
+    assert dashboard._safe_next_url("/?onboarding=1") == "/?onboarding=1"
+    assert dashboard._safe_next_url("//example.com") == "/"
+    assert dashboard._safe_next_url("https://example.com") == "/"
+
+
+def test_login_requests_narrow_scopes_and_org_grant(monkeypatch) -> None:
+    monkeypatch.setattr(dashboard, "OAUTH_CLIENT_ID", "client-id")
+    monkeypatch.setattr(dashboard, "OAUTH_CLIENT_SECRET", "client-secret")
+    monkeypatch.setattr(dashboard, "OAUTH_ORG_ID", "org-id")
+
+    with TestClient(dashboard.app) as client:
+        response = client.get("/login?next=/?onboarding=1", follow_redirects=False)
+
+    assert response.status_code == 307
+    query = parse_qs(urlsplit(response.headers["location"]).query)
+    assert query["scope"] == ["openid profile email contribute-repos write-discussions"]
+    assert query["orgIds"] == ["org-id"]
+    assert len(query["state"][0]) >= 43
+
+
+def test_bootstrap_contains_one_time_code_but_not_hf_token() -> None:
+    bootstrap = dashboard._build_agent_bootstrap(
+        one_time_code="one_time_exchange_code",
+        dashboard_url="https://dashboard.example",
+        agent_id="test-agent",
+        persona="skeptical and rigorous",
+    )
+
+    assert "export ONBOARDING_CODE=one_time_exchange_code" in bootstrap
+    assert "export HF_TOKEN=" not in bootstrap
+    assert "oauth_secret_token" not in bootstrap
+    assert "/api/onboarding/exchange" in bootstrap
+    assert "login(token=token" in bootstrap
+    assert "export AGENT_ID=test-agent" in bootstrap
+    assert "create_bucket(bucket, token=token)" in bootstrap
+    assert ".bucket-sync-handshake" in bootstrap
+    assert "/v1/agents/register" in bootstrap
+    assert "/v1/messages" in bootstrap
+    assert "/v1/digest?as=" in bootstrap
+    assert "skeptical and rigorous" in bootstrap
+    assert "Existing PAT-based agents must keep" in bootstrap
+
+
+def test_grant_endpoint_requires_oauth_session() -> None:
+    with TestClient(dashboard.app) as client:
+        response = client.post(
+            "/api/onboarding/grants",
+            json={"agent_id": "new-agent", "persona": ""},
+        )
+    assert response.status_code == 401
+
+
+def test_grant_exchange_is_no_store_and_single_use(monkeypatch) -> None:
+    async def available(_agent_id: str) -> bool:
+        return True
+
+    monkeypatch.setattr(dashboard, "_agent_id_is_available", available)
+    with _authenticated_client(expires_at=int(time.time()) + 3600) as client:
+        grant_response = client.post(
+            "/api/onboarding/grants",
+            json={"agent_id": "new-agent", "persona": "curious"},
+        )
+        assert grant_response.status_code == 200, grant_response.text
+        bootstrap = grant_response.json()["bootstrap"]
+        code_match = re.search(r"^export ONBOARDING_CODE=([^\n]+)$", bootstrap, re.M)
+        assert code_match is not None
+        code = code_match.group(1)
+
+        assert "oauth_secret_token" not in bootstrap
+        assert grant_response.headers["cache-control"] == "no-store, max-age=0"
+        exchange_response = client.post("/api/onboarding/exchange", json={"code": code})
+        second_response = client.post("/api/onboarding/exchange", json={"code": code})
+
+    assert exchange_response.status_code == 200
+    assert exchange_response.json()["access_token"] == "oauth_secret_token"
+    assert exchange_response.headers["cache-control"] == "no-store, max-age=0"
+    assert second_response.status_code == 401
+
+
+def test_api_me_returns_membership_without_cookie_token(monkeypatch) -> None:
+    async def membership(_access_token: str | None) -> tuple[bool, bool]:
+        return True, False
+
+    monkeypatch.setattr(dashboard, "_fetch_membership", membership)
+    with _authenticated_client() as client:
+        response = client.get("/api/me")
+        session_cookies = [
+            cookie.value for cookie in client.cookies.jar if cookie.name == "hp_session"
+        ]
+
+    assert response.status_code == 200
+    assert response.json()["is_member"] is True
+    assert response.json()["onboarding_ready"] is True
+    assert session_cookies
+    assert all("oauth_secret_token" not in value for value in session_cookies)
+
+
+def test_grant_endpoint_rejects_taken_id(monkeypatch) -> None:
+    async def unavailable(_agent_id: str) -> bool:
+        return False
+
+    monkeypatch.setattr(dashboard, "_agent_id_is_available", unavailable)
+    with _authenticated_client() as client:
+        response = client.post(
+            "/api/onboarding/grants",
+            json={"agent_id": "taken-agent", "persona": ""},
+        )
+    assert response.status_code == 409
+
+
+def test_grant_endpoint_rejects_expired_token(monkeypatch) -> None:
+    async def available(_agent_id: str) -> bool:
+        return True
+
+    monkeypatch.setattr(dashboard, "_agent_id_is_available", available)
+    with _authenticated_client(expires_at=int(time.time()) - 1) as client:
+        response = client.post(
+            "/api/onboarding/grants",
+            json={"agent_id": "new-agent", "persona": ""},
+        )
+    assert response.status_code == 401
+
+
+def test_grant_endpoint_rejects_invalid_agent_id(monkeypatch) -> None:
+    async def available(_agent_id: str) -> bool:
+        return True
+
+    monkeypatch.setattr(dashboard, "_agent_id_is_available", available)
+    with _authenticated_client() as client:
+        response = client.post(
+            "/api/onboarding/grants",
+            json={"agent_id": "Not Valid", "persona": ""},
+        )
+    assert response.status_code == 400