Fail fast on Router-ineligible API tokens

backend/routes/v1_responses.py

@@ -14,11 +14,13 @@ pauses with ``status="incomplete"`` until /approvals is called.
 """
 
 import asyncio
+import hashlib
 import logging
 import time
 from datetime import UTC, datetime
 from typing import Any
 
+import httpx
 from dependencies import get_api_user
 from fastapi import APIRouter, Depends, Request
 from fastapi.responses import JSONResponse, StreamingResponse
@@ -49,6 +51,7 @@ from session_manager import (
 from usage import build_usage_response
 
 from agent.core.hf_tokens import resolve_hf_request_token
+from agent.core.model_ids import HF_ROUTER_BASE_URL, strip_huggingface_model_prefix
 
 logger = logging.getLogger(__name__)
 
@@ -56,7 +59,10 @@ router = APIRouter(prefix="/v1", tags=["v1"])
 
 _SSE_KEEPALIVE_SECONDS = 15
 _COLLECTION_FETCH_TIMEOUT_SECONDS = 10.0
+_ROUTER_PREFLIGHT_TIMEOUT_SECONDS = 20.0
+_ROUTER_PREFLIGHT_CACHE_TTL_SECONDS = 300.0
 _background_v1_tasks: set[asyncio.Task] = set()
+_router_preflight_cache: dict[tuple[str, str], float] = {}
 
 
 def _spawn(coro) -> None:
@@ -73,6 +79,105 @@ def _now() -> datetime:
     return datetime.now(UTC)
 
 
+def _token_fingerprint(token: str) -> str:
+    return hashlib.sha256(token.encode("utf-8")).hexdigest()[:16]
+
+
+def _router_preflight_cache_key(token: str, model: str) -> tuple[str, str]:
+    normalized_model = strip_huggingface_model_prefix(model) or model
+    return (_token_fingerprint(token), normalized_model)
+
+
+async def _preflight_hf_router_access(model: str, hf_token: str | None) -> None:
+    """Fail fast when a /v1 Bearer token cannot call HF Router.
+
+    ``whoami-v2`` accepts plain user access tokens, but tokens without the
+    Inference Providers permission still fail later inside the agent loop with
+    a generic auth message. A one-token probe gives API clients an immediate,
+    actionable 403 before we create a response/session.
+    """
+    if not hf_token:
+        raise V1APIError(
+            401,
+            "Missing Hugging Face token. Pass 'Authorization: Bearer hf_...'.",
+            code="invalid_api_key",
+            error_type="authentication_error",
+        )
+
+    cache_key = _router_preflight_cache_key(hf_token, model)
+    now = time.monotonic()
+    cached_until = _router_preflight_cache.get(cache_key)
+    if cached_until and cached_until > now:
+        return
+    if cached_until:
+        _router_preflight_cache.pop(cache_key, None)
+
+    normalized_model = cache_key[1]
+    payload = {
+        "model": f"openai/{normalized_model}",
+        "messages": [{"role": "user", "content": "Reply with OK."}],
+        "max_tokens": 1,
+    }
+    try:
+        async with httpx.AsyncClient(
+            timeout=_ROUTER_PREFLIGHT_TIMEOUT_SECONDS
+        ) as client:
+            response = await client.post(
+                f"{HF_ROUTER_BASE_URL.rstrip('/')}/chat/completions",
+                headers={"Authorization": f"Bearer {hf_token}"},
+                json=payload,
+            )
+    except httpx.HTTPError as e:
+        logger.warning("HF Router preflight skipped for %s: %s", normalized_model, e)
+        return
+
+    if response.status_code < 400:
+        _router_preflight_cache[cache_key] = (
+            time.monotonic() + _ROUTER_PREFLIGHT_CACHE_TTL_SECONDS
+        )
+        return
+
+    try:
+        error_body = response.json()
+    except ValueError:
+        error_body = {}
+    raw_message = str(
+        error_body.get("error")
+        or error_body.get("message")
+        or response.text
+        or "HF Router rejected the token."
+    )
+    err_lower = raw_message.lower()
+    if response.status_code in {401, 403} and (
+        "insufficient permissions" in err_lower
+        or "authentication" in err_lower
+        or "unauthorized" in err_lower
+    ):
+        raise V1APIError(
+            403,
+            (
+                "Your Hugging Face token is valid, but it cannot call "
+                "Inference Providers through HF Router. Create or use a user "
+                "access token with Inference Providers permission, then retry."
+            ),
+            code="inference_provider_permission_required",
+            error_type="authentication_error",
+        )
+    if response.status_code in {401, 403}:
+        raise V1APIError(
+            response.status_code,
+            raw_message,
+            code="router_auth_failed",
+            error_type="authentication_error",
+        )
+    if 400 <= response.status_code < 500:
+        raise V1APIError(
+            response.status_code,
+            raw_message,
+            code="router_preflight_failed",
+        )
+
+
 # ---------------------------------------------------------------------------
 # Shared helpers
 # ---------------------------------------------------------------------------
@@ -487,6 +592,7 @@ async def _resolve_session_for_create(
     except Exception:
         raise V1APIError(400, f"Unknown model: {body.model}", code="model_not_found")
     model = body.model or _default_model_for_user(user)
+    await _preflight_hf_router_access(model, hf_token)
     try:
         session_id = await session_manager.create_session(
             user_id=user["user_id"],