Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

fix(studio): enforce Hub token caller boundary (#10076)

Lee Jacksonc7f977124f6b
diff --git a/studio/backend/core/inference/diffusion_compat.py b/studio/backend/core/inference/diffusion_compat.py
index 3d2130f0f5a..f373a4d59b3 100644
--- a/studio/backend/core/inference/diffusion_compat.py
+++ b/studio/backend/core/inference/diffusion_compat.py
@@ -32,6 +32,12 @@ import time
from pathlib import Path
from typing import Any, Optional
+from hub.utils.hf_tokens import (
+ ANONYMOUS_CACHE_IDENTITY,
+ HfTokenArg,
+ is_anonymous,
+ normalize_token,
+)
from core.inference.diffusion_families import (
flux2_base_inner_dim,
flux2_mismatch_reason,
@@ -68,9 +74,14 @@ _INNER_DIM_CACHE_MAX = 256
_CACHE_LOCK = threading.Lock()
-def _token_fingerprint(token: Optional[str]) -> str:
+def _token_fingerprint(token: HfTokenArg) -> str:
"""A stable, non-reversible tag for a token, or "" for none. Never the token itself: this
- lands in a process-global dict that a traceback or a heap dump would render."""
+ lands in a process-global dict that a traceback or a heap dump would render.
+
+ A caller forced anonymous tags apart from one that may still use the ambient token,
+ so neither reads back the other's verdict."""
+ if is_anonymous(token):
+ return ANONYMOUS_CACHE_IDENTITY
if not token:
return ""
return hashlib.sha256(token.encode("utf-8", "replace")).hexdigest()[:16]
@@ -323,7 +334,7 @@ def flux2_inner_dim_for_pick(
# spending a range request to learn that on every such load is pure waste.
if not repo_id or not gguf_filename or not gguf_filename.lower().endswith(".gguf"):
return None
- token = (hf_token or "").strip() or None
+ token = normalize_token(hf_token)
# Resolved BEFORE the memo is consulted, because the file's identity is part of the key. Two
# stats, against a probe that is otherwise an HTTP round trip.
local = _local_gguf_path(repo_id, gguf_filename)
@@ -371,7 +382,7 @@ def _revalidated_inner_dim(
cached = _snapshot_revision(_local_gguf_path(repo_id, gguf_filename))
if cached is None:
return got
- token = (hf_token or "").strip() or None
+ token = normalize_token(hf_token)
live = _hub_revision(repo_id, gguf_filename, token)
if live is None or live == cached:
return got
@@ -533,7 +544,7 @@ def _speech_probe_architecture(
because a probe that failed on an expired credential caches "no verdict" and the retry with a
working one would read that back and let the speech file through to the download; the file
identity, because a checkpoint replaced under the same name is a different checkpoint."""
- token = (hf_token or "").strip() or None
+ token = normalize_token(hf_token)
# Resolved BEFORE the memo is consulted, because the file's identity is part of the key.
local = _local_gguf_path(repo_id, gguf_filename)
key = (repo_id, gguf_filename, _token_fingerprint(token), _file_identity(local))
diff --git a/studio/backend/core/inference/stt_download_worker.py b/studio/backend/core/inference/stt_download_worker.py
index 4832a68818d..41756667b52 100644
--- a/studio/backend/core/inference/stt_download_worker.py
+++ b/studio/backend/core/inference/stt_download_worker.py
@@ -22,6 +22,7 @@ from pathlib import Path
from typing import Optional, Sequence
# Fresh spawned interpreter: re-apply the OS-trust-store injection.
+from hub.utils.hf_tokens import apply_token_to_child_env
from utils.native_tls import activate_native_tls
activate_native_tls()
@@ -58,20 +59,9 @@ def spawn_download(
# Parallel Range chunks leave sparse partials a resumed sequential writer
# cannot reuse, which defeats the point of cancelling.
env["HF_HUB_ENABLE_HF_TRANSFER"] = "0"
- # Replace the inherited credentials only when the caller supplied one. With
- # no token, leave the ambient login alone: the parent plans the download
- # with it, so scrubbing here would fail gated repos that used to work.
- if hf_token:
- env["HF_HUB_DISABLE_IMPLICIT_TOKEN"] = "0"
- for token_key in (
- "HF_TOKEN",
- "HF_HUB_TOKEN",
- "HUGGING_FACE_HUB_TOKEN",
- "HUGGINGFACE_HUB_TOKEN",
- "HUGGINGFACEHUB_API_TOKEN",
- ):
- env.pop(token_key, None)
- env["HF_TOKEN"] = hf_token
+ # `None` keeps the ambient login (the parent planned the download with it); `False`
+ # must be scrubbed, or the child downloads a repo the caller only had to name.
+ apply_token_to_child_env(env, hf_token)
existing_path = env.get("PYTHONPATH", "")
env["PYTHONPATH"] = f"{cwd}{os.pathsep}{existing_path}" if existing_path else str(cwd)
from utils.process_lifetime import adopt_pid, child_popen_kwargs
diff --git a/studio/backend/core/inference/stt_ggml_sidecar.py b/studio/backend/core/inference/stt_ggml_sidecar.py
index 38bf8fc8b0d..42cca6cdd37 100644
--- a/studio/backend/core/inference/stt_ggml_sidecar.py
+++ b/studio/backend/core/inference/stt_ggml_sidecar.py
@@ -43,6 +43,7 @@ from typing import Iterator, Optional
from loggers import get_logger
+from hub.utils.hf_tokens import normalize_token
from core.inference.stt_sidecar import (
STT_KEEP_ALIVE_SECONDS,
SttAudioDecodeError,
@@ -585,7 +586,9 @@ class _GgmlDownloadState:
from huggingface_hub import get_hf_file_metadata, hf_hub_url
try:
- meta = get_hf_file_metadata(hf_hub_url(repo_id, filename), token = hf_token or None)
+ meta = get_hf_file_metadata(
+ hf_hub_url(repo_id, filename), token = normalize_token(hf_token)
+ )
total_bytes = int(meta.size or 0)
except (AttributeError, TypeError, ValueError) as exc:
raise RuntimeError("could not resolve GGML download metadata") from exc
@@ -629,7 +632,7 @@ class _GgmlDownloadState:
]
process = spawn_download(
args,
- hf_token = hf_token or None,
+ hf_token = normalize_token(hf_token),
hub_cache = hub_cache,
)
with self._lock:
diff --git a/studio/backend/core/inference/stt_mtmd_sidecar.py b/studio/backend/core/inference/stt_mtmd_sidecar.py
index 11972f1b29a..aed614b9523 100644
--- a/studio/backend/core/inference/stt_mtmd_sidecar.py
+++ b/studio/backend/core/inference/stt_mtmd_sidecar.py
@@ -29,6 +29,7 @@ from typing import Iterator, Optional
from loggers import get_logger
+from hub.utils.hf_tokens import normalize_token
from utils.process_lifetime import adopt_pid, child_popen_kwargs, forget_pid
from core.inference.stt_ggml_sidecar import _pcm_to_wav_bytes
@@ -444,7 +445,7 @@ class _MtmdDownloadState:
for filename in (spec.model_file, spec.mmproj_file):
meta = get_hf_file_metadata(
hf_hub_url(spec.repo, filename, revision = revision),
- token = hf_token or None,
+ token = normalize_token(hf_token),
)
if revision is None:
revision = meta.commit_hash
@@ -483,7 +484,7 @@ class _MtmdDownloadState:
args = ["--repo-id", spec.repo, "--revision", revision]
for item in selected:
args.extend(("--filename", item.path))
- process = spawn_download(args, hf_token = hf_token or None, hub_cache = hub_cache)
+ process = spawn_download(args, hf_token = normalize_token(hf_token), hub_cache = hub_cache)
with self._lock:
if self._cancelled:
terminate_download(process)
diff --git a/studio/backend/core/inference/stt_sidecar.py b/studio/backend/core/inference/stt_sidecar.py
index 922afcec5b5..a5aa3d00807 100644
--- a/studio/backend/core/inference/stt_sidecar.py
+++ b/studio/backend/core/inference/stt_sidecar.py
@@ -19,6 +19,8 @@ must not be the process that takes one.
from __future__ import annotations
+from hub.utils.hf_tokens import normalize_token
+
import gc
import hashlib
import io
@@ -764,7 +766,7 @@ class _SnapshotDownloadState:
terminate_download,
)
- process = spawn_download(args, hf_token = hf_token or None, hub_cache = hub_cache)
+ process = spawn_download(args, hf_token = normalize_token(hf_token), hub_cache = hub_cache)
with self._lock:
if self._cancelled:
terminate_download(process)
@@ -835,7 +837,7 @@ class _SnapshotDownloadState:
try:
from huggingface_hub import HfApi, hf_hub_download
- info = HfApi(token = hf_token or None).model_info(
+ info = HfApi(token = normalize_token(hf_token)).model_info(
repo,
revision = revision,
files_metadata = True,
diff --git a/studio/backend/hub/dependencies.py b/studio/backend/hub/dependencies.py
index ff78dce8f6b..bd0b716d143 100644
--- a/studio/backend/hub/dependencies.py
+++ b/studio/backend/hub/dependencies.py
@@ -7,7 +7,10 @@ from __future__ import annotations
from typing import Optional
-from fastapi import Header
+from fastapi import Depends, Header
+
+from auth.authentication import allow_ambient_hf_token
+from hub.utils.hf_tokens import HfTokenArg, hf_token_arg
HUB_HF_TOKEN_HEADER = "X-Unsloth-HF-Token"
HUB_HF_TOKEN_MAX_LENGTH = 512
@@ -22,3 +25,14 @@ def get_hf_token(
) -> Optional[str]:
token = (hf_token or "").strip()
return token or None
+
+
+def get_request_hf_token(
+ hf_token: Optional[str] = Depends(get_hf_token),
+ allow_ambient_token: bool = Depends(allow_ambient_hf_token),
+) -> HfTokenArg:
+ """Resolve the Hub token under the caller boundary established by authentication."""
+ return hf_token_arg(
+ hf_token,
+ allow_ambient_token = allow_ambient_token,
+ )
diff --git a/studio/backend/hub/routes/datasets.py b/studio/backend/hub/routes/datasets.py
index 7bfa1af9f81..361ab0f7fce 100644
--- a/studio/backend/hub/routes/datasets.py
+++ b/studio/backend/hub/routes/datasets.py
@@ -10,7 +10,7 @@ from typing import Optional
from fastapi import APIRouter, Body, Depends, File, Form, Query, UploadFile
from auth.authentication import allow_ambient_hf_token, get_current_subject
-from hub.dependencies import get_hf_token
+from hub.dependencies import get_hf_token, get_request_hf_token
from hub.schemas.datasets import (
AiAssistMappingRequest,
AiAssistMappingResponse,
@@ -23,6 +23,7 @@ from hub.schemas.datasets import (
LocalDatasetsResponse,
UploadDatasetResponse,
)
+from hub.utils.hf_tokens import HfTokenArg
from hub.schemas.downloads import (
ActiveDownloadsResponse,
CancelDatasetDownloadRequest,
@@ -83,7 +84,7 @@ async def delete_cached_dataset(
async def get_dataset_download_progress(
repo_id: str = Query(..., description = "HuggingFace dataset repo ID, e.g. 'unsloth/LaTeX_OCR'"),
expected_bytes: int = Query(0, description = "Expected total download size in bytes"),
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
current_subject: str = Depends(get_current_subject),
):
return await downloads.get_dataset_download_progress_response(
@@ -141,7 +142,7 @@ async def get_dataset_transport_status(
@router.post("/check-format", response_model = CheckFormatResponse)
def check_format(
request: CheckFormatRequest,
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
current_subject: str = Depends(get_current_subject),
):
return formatting.check_format_response(request, hf_token)
@@ -150,7 +151,7 @@ def check_format(
@router.post("/ai-assist-mapping", response_model = AiAssistMappingResponse)
def ai_assist_mapping(
request: AiAssistMappingRequest,
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
current_subject: str = Depends(get_current_subject),
):
return formatting.ai_assist_mapping_response(request, hf_token)
diff --git a/studio/backend/hub/routes/inventory.py b/studio/backend/hub/routes/inventory.py
index 083832ab85a..1a779cd918b 100644
--- a/studio/backend/hub/routes/inventory.py
+++ b/studio/backend/hub/routes/inventory.py
@@ -10,7 +10,7 @@ from typing import Optional
from fastapi import APIRouter, Body, Depends, Query
from auth.authentication import allow_ambient_hf_token, get_current_subject
-from hub.dependencies import get_hf_token
+from hub.dependencies import get_hf_token, get_request_hf_token
from hub.schemas.downloads import (
ActiveDownloadsResponse,
CancelDownloadResponse,
@@ -21,6 +21,7 @@ from hub.schemas.downloads import (
DownloadStartResponse,
TransportStatusResponse,
)
+from hub.utils.hf_tokens import HfTokenArg
from hub.schemas.inventory import (
AddScanFolderRequest,
CachedGgufResponse,
@@ -92,7 +93,7 @@ async def get_gguf_variants(
prefer_local_cache: bool = Query(False),
offline: bool = Query(False),
local_path: Optional[str] = Query(None),
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
current_subject: str = Depends(get_current_subject),
):
return await gguf_variants.get_gguf_variants_response(
@@ -146,7 +147,7 @@ async def get_active_downloads(
async def get_model_transport_status(
repo_id: str = Query(..., description = "HuggingFace repo ID"),
gguf_variant: str = Query("", description = "Quantization variant (empty for safetensors)"),
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
current_subject: str = Depends(get_current_subject),
):
return await downloads.get_model_transport_status_response(
@@ -165,7 +166,7 @@ async def get_gguf_download_progress(
repo_id: str = Query(..., description = "HuggingFace repo ID"),
variant: str = Query("", description = "Quantization variant (e.g. UD-TQ1_0)"),
expected_bytes: int = Query(0, description = "Expected total download size in bytes"),
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
current_subject: str = Depends(get_current_subject),
):
return await downloads.get_gguf_download_progress_response(
@@ -180,7 +181,7 @@ async def get_gguf_download_progress(
async def get_download_progress(
repo_id: str = Query(..., description = "HuggingFace repo ID"),
expected_bytes: int = Query(0, description = "Expected total download size in bytes"),
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
current_subject: str = Depends(get_current_subject),
):
return await downloads.get_download_progress_response(
@@ -192,7 +193,7 @@ async def get_download_progress(
@router.get("/cached-gguf", response_model = CachedGgufResponse)
async def list_cached_gguf(
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
current_subject: str = Depends(get_current_subject),
):
return await cache_inventory.list_cached_gguf_response(hf_token)
@@ -200,7 +201,7 @@ async def list_cached_gguf(
@router.get("/cached-models", response_model = CachedModelsResponse)
async def list_cached_models(
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
current_subject: str = Depends(get_current_subject),
):
return await cache_inventory.list_cached_models_response(hf_token)
@@ -248,7 +249,7 @@ async def delete_cached_model(
cache_path: Optional[str] = Body(None),
# Free up space's precondition: refuse with 409 if the repo is no longer an unused asset.
only_if_orphan: bool = Body(False),
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
current_subject: str = Depends(get_current_subject),
):
return await deletion.delete_cached_model_response(
diff --git a/studio/backend/hub/services/datasets/formatting.py b/studio/backend/hub/services/datasets/formatting.py
index 8f52f9b4306..a4944d2f3de 100644
--- a/studio/backend/hub/services/datasets/formatting.py
+++ b/studio/backend/hub/services/datasets/formatting.py
@@ -43,6 +43,8 @@ from hub.utils.paths import (
normalize_path,
resolve_dataset_path,
)
+from hub.utils.hf_tokens import is_anonymous
+from utils.utils import anonymous_and_offline
from utils.datasets.audio_decode import ensure_audio_decoding
from utils.paths.path_utils import drop_shadowed_appledouble_names
@@ -308,6 +310,11 @@ def _load_any_cached_hf_preview_slice(
preview_size: int,
hf_token: Optional[str] = None,
):
+ # Both paths return real rows off disk without asking the Hub: the raw slice reads the
+ # snapshot, the processed one loads with local_files_only=True and drops the falsy
+ # sentinel. Refuse the whole disk route here; the handler then answers 404.
+ if is_anonymous(hf_token):
+ return None
cached_preview = _load_cached_hf_preview_slice(request, preview_size)
if cached_preview is not None:
return cached_preview
@@ -359,6 +366,13 @@ def check_format_response(
if not dataset_exists and _is_local_dataset_ref(request.dataset_name):
raise HTTPException(status_code = 404, detail = _MISSING_DATASET_DETAIL)
+ # Offline `datasets` answers a streaming load from its cache without authorizing,
+ # and Tier 2 runs on the default prefer_local_cache=false, ahead of that guard.
+ if anonymous_and_offline(hf_token) and not dataset_exists:
+ raise HTTPException(
+ status_code = 404,
+ detail = "This request cannot be authorized without network access.",
+ )
if dataset_exists:
train_split = request.train_split or "train"
preview_slice, total_rows = _load_local_preview_slice(
@@ -391,11 +405,13 @@ def check_format_response(
try:
from huggingface_hub import HfApi
+ # No token on the constructor: list_repo_files is given it explicitly
+ # and that argument wins.
api = HfApi()
repo_files = api.list_repo_files(
request.dataset_name,
repo_type = "dataset",
- token = hf_token or None,
+ token = hf_token,
)
train_split = request.train_split or "train"
first_file = _select_tier1_repo_file(
@@ -411,9 +427,8 @@ def check_format_response(
"data_files": {train_split: [first_file]},
"split": train_split,
"streaming": True,
+ "token": hf_token,
}
- if hf_token:
- load_kwargs["token"] = hf_token
streamed_ds = load_dataset(**load_kwargs)
rows = list(islice(streamed_ds, PREVIEW_SIZE))
@@ -433,11 +448,10 @@ def check_format_response(
"path": request.dataset_name,
"split": request.train_split or "train",
"streaming": True,
+ "token": hf_token,
}
if request.subset:
load_kwargs["name"] = request.subset
- if hf_token:
- load_kwargs["token"] = hf_token
streamed_ds = load_dataset(**load_kwargs)
diff --git a/studio/backend/hub/services/models/gguf_variants.py b/studio/backend/hub/services/models/gguf_variants.py
index 89f8cf3d9e7..36905580584 100644
--- a/studio/backend/hub/services/models/gguf_variants.py
+++ b/studio/backend/hub/services/models/gguf_variants.py
@@ -23,6 +23,7 @@ from hub.utils import download_manifest
from hub.utils import download_registry
from hub.utils import inventory_scan as hf_cache_scan
from hub.utils.hf_errors import hf_error_status
+from hub.utils.hf_tokens import is_anonymous
from hub.utils.hf_cache_state import (
incomplete_blob_hash,
iter_destructive_repo_cache_dirs,
@@ -1287,9 +1288,14 @@ async def get_gguf_variants_answer(
if not _is_valid_repo_id(repo_id):
raise HTTPException(status_code = 400, detail = f"Invalid repo_id: {repo_id!r}")
+ # The HF cache answers from disk without authorizing, so a denied caller could name
+ # a cached private repo and read back its filenames, sizes and vision flag. A
+ # local_path the caller named itself is not the Hub cache and stays available.
+ cache_reads_authorized = not is_anonymous(hf_token)
+
def _scoped_local_response():
"""The pinned snapshot's own answer, or None when it holds nothing."""
- if snapshot_scope is None:
+ if snapshot_scope is None or not cache_reads_authorized:
return None
variants, has_vision = list_local_gguf_variants(str(snapshot_scope))
if not (variants or has_vision):
@@ -1306,7 +1312,11 @@ async def get_gguf_variants_answer(
scoped_response = _scoped_local_response()
if scoped_response is not None:
return scoped_response
- cached = select_gguf_cache_snapshot(repo_id, root = hub_cache)
+ cached = (
+ select_gguf_cache_snapshot(repo_id, root = hub_cache)
+ if cache_reads_authorized
+ else None
+ )
if cached is not None:
variants, has_vision, complete, snapshot = _merge_when_the_repo_id_loads(
repo_id, cached, hub_cache
@@ -1326,7 +1336,7 @@ async def get_gguf_variants_answer(
return _local_response(
repo_id, variants, has_vision, _complete_quants_under(local_path)
)
- partial = _quants_from_state(repo_id, hub_cache)
+ partial = _quants_from_state(repo_id, hub_cache) if cache_reads_authorized else None
if partial is not None:
variants, has_vision = partial
return _partial_local_response(repo_id, variants, has_vision)
@@ -1349,6 +1359,10 @@ async def get_gguf_variants_answer(
The lister's own cache read is repo-wide, so redoing it here pins the listing and,
through ``answered_from``, its context metadata to the named copy.
"""
+ if not cache_reads_authorized:
+ # An unauthorized caller whose hub call failed gets that failure, not the
+ # cache's answer to it.
+ return None
scoped_response = _scoped_local_response()
if scoped_response is not None:
return scoped_response
@@ -1372,6 +1386,7 @@ async def get_gguf_variants_answer(
try:
variants, has_vision, siblings = list_gguf_variants(repo_id, hf_token = hf_token)
except Exception:
+ # Ungated: _cache_fallback_response already refuses an unauthorized caller.
fallback = _cache_fallback_response()
if fallback is not None:
return fallback
@@ -1380,6 +1395,13 @@ async def get_gguf_variants_answer(
# siblings is None only when the lister answered from its own repo-wide cache. Falling
# through is deliberate: readiness below still counts against this request's own cache.
if siblings is None:
+ if not cache_reads_authorized:
+ # `variants` is already the cache's answer, so declining a second one is
+ # not enough; falling through would serialize the first.
+ raise HTTPException(
+ status_code = 404,
+ detail = "No GGUF variants available without Hub authorization.",
+ )
fallback = _cache_fallback_response()
if fallback is not None:
return fallback
diff --git a/studio/backend/hub/utils/hf_tokens.py b/studio/backend/hub/utils/hf_tokens.py
new file mode 100644
index 00000000000..d5388b034fa
--- /dev/null
+++ b/studio/backend/hub/utils/hf_tokens.py
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Request-scoped Hugging Face token helpers."""
+
+from __future__ import annotations
+
+from typing import Literal, MutableMapping, Optional, Union
+
+HfTokenArg = Optional[Union[str, Literal[False]]]
+
+# Anonymous-sentinel cache identity, kept apart from ``None``'s: a slot filled under the
+# ambient token must not be served to an API key denied it. Not hex, so no digest collides.
+ANONYMOUS_CACHE_IDENTITY = "anon"
+
+
+def hf_token_arg(hf_token: Optional[str], *, allow_ambient_token: bool) -> HfTokenArg:
+ """Return the explicit token, or choose ambient versus anonymous access."""
+ token = (hf_token or "").strip()
+ if token:
+ return token
+ return None if allow_ambient_token else False
+
+
+# Mirrors the list hub/services/download_lifecycle.py scrubs for download workers.
+_HF_TOKEN_ENV_KEYS = (
+ "HF_TOKEN",
+ "HF_HUB_TOKEN",
+ "HUGGING_FACE_HUB_TOKEN",
+ "HUGGINGFACE_HUB_TOKEN",
+ "HUGGINGFACEHUB_API_TOKEN",
+)
+
+
+def apply_token_to_child_env(env: MutableMapping[str, str], hf_token: HfTokenArg) -> None:
+ """Grant a spawned probe exactly its caller's credential.
+
+ A child env is seeded from the parent's, so not *setting* a token is not denying one.
+ Only the sentinel scrubs; ``None`` keeps the inherited env on purpose.
+ """
+ if isinstance(hf_token, str) and hf_token:
+ # Scrub before granting: setting HF_TOKEN alone leaves an operator credential
+ # sitting in HF_HUB_TOKEN or a legacy alias, so the child holds two.
+ for key in _HF_TOKEN_ENV_KEYS:
+ env.pop(key, None)
+ env["HF_TOKEN"] = hf_token
+ # An inherited HF_HUB_DISABLE_IMPLICIT_TOKEN=1 would otherwise 401 a gated repo.
+ env["HF_HUB_DISABLE_IMPLICIT_TOKEN"] = "0"
+ return
+ if is_anonymous(hf_token):
+ for key in _HF_TOKEN_ENV_KEYS:
+ env.pop(key, None)
+ env["HF_HUB_DISABLE_IMPLICIT_TOKEN"] = "1"
+
+
+def normalize_token(hf_token: HfTokenArg) -> HfTokenArg:
+ """Trim an explicit token without laundering ``False`` into ``None`` (= ambient)."""
+ if is_anonymous(hf_token):
+ return False
+ return (hf_token or "").strip() or None
+
+
+def is_anonymous(hf_token: HfTokenArg) -> bool:
+ """Named because a bare ``is False`` invites a ``not hf_token`` "simplification"."""
+ return hf_token is False
diff --git a/studio/backend/hub/utils/inventory_scan.py b/studio/backend/hub/utils/inventory_scan.py
index 7e30586ffdc..e0fca5a9a1b 100644
--- a/studio/backend/hub/utils/inventory_scan.py
+++ b/studio/backend/hub/utils/inventory_scan.py
@@ -36,6 +36,7 @@ from hub.utils.gguf import (
is_mmproj_filename,
is_mtp_drafter_path,
)
+from hub.utils.hf_tokens import ANONYMOUS_CACHE_IDENTITY, HfTokenArg, is_anonymous
from hub.utils.state_dir import RepoType
from hub.utils.hf_cache_state import (
@@ -441,13 +442,18 @@ def default_ref_snapshot(repo_dir: Path) -> Optional[Path]:
return None
-def token_fingerprint(hf_token: Optional[str]) -> str:
+def token_fingerprint(hf_token: HfTokenArg) -> str:
"""16-char SHA256 prefix used as a cache-key qualifier for gated repos.
Lets per-token size/snapshot caches refuse to serve a previously
fetched value back to a different token (a private/gated repo's
metadata is only valid for the credential that fetched it).
+
+ A forced-anonymous caller is a different credential from one that may still fall
+ back to the ambient token, so it takes its own identity.
"""
+ if is_anonymous(hf_token):
+ return ANONYMOUS_CACHE_IDENTITY
if not hf_token:
return ""
return hashlib.sha256(hf_token.encode()).hexdigest()[:16]
diff --git a/studio/backend/picker/routes/templates.py b/studio/backend/picker/routes/templates.py
index 628cc038412..8ca20e23798 100644
--- a/studio/backend/picker/routes/templates.py
+++ b/studio/backend/picker/routes/templates.py
@@ -9,7 +9,8 @@ from typing import Optional
from fastapi import APIRouter, Body, Depends, Query
from auth.authentication import get_current_subject
-from hub.dependencies import get_hf_token
+from hub.dependencies import get_request_hf_token
+from hub.utils.hf_tokens import HfTokenArg
from ..schemas import (
MAX_CHAT_TEMPLATE_BYTES,
@@ -34,7 +35,7 @@ async def validate_chat_template_route(
async def get_default_chat_template_route(
model_name: str,
gguf_variant: Optional[str] = Query(None),
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
current_subject: str = Depends(get_current_subject),
) -> ModelTemplateResponse:
# Cached repos resolve from disk, but a cache miss falls through to the hub and
diff --git a/studio/backend/picker/service.py b/studio/backend/picker/service.py
index ac1642ef0db..079710fd89d 100644
--- a/studio/backend/picker/service.py
+++ b/studio/backend/picker/service.py
@@ -10,6 +10,7 @@ import re
from pathlib import Path
from typing import Optional
+from hub.utils.hf_tokens import is_anonymous
from hub.services.models.folder_browser import (
_build_browse_allowlist,
_is_path_inside_allowlist,
@@ -26,6 +27,7 @@ from utils.models.model_config import (
_is_mtp_drafter,
)
from utils.hf_cache_settings import active_hf_hub_cache
+from utils.utils import hf_env_offline
from utils.paths.path_utils import (
is_local_path,
normalize_path,
@@ -363,21 +365,30 @@ def read_default_chat_template(
resolved = resolve_cached_repo_id_case(name)
- try:
- # Resolve within each cached revision, newest first. A revision's sidecar
- # supersedes its own embedded GGUF copy, but must not override a newer
- # revision, so precedence stays per-snapshot rather than global.
- for snapshot in iter_snapshots_preferring_whole(resolved, gguf_variant):
- template = _chat_template_from_dir(snapshot, gguf_variant)
- if template:
- return template
- except Exception as exc:
- logger.debug("Could not read cached chat template for %s: %s", resolved, exc)
+ # The walk returns a private repo's raw template without asking the Hub, so a denied
+ # caller goes to the Hub and is refused there. A UI session keeps the cache.
+ if not is_anonymous(hf_token):
+ try:
+ # Resolve within each cached revision, newest first. A revision's sidecar
+ # supersedes its own embedded GGUF copy, but must not override a newer
+ # revision, so precedence stays per-snapshot rather than global.
+ for snapshot in iter_snapshots_preferring_whole(resolved, gguf_variant):
+ template = _chat_template_from_dir(snapshot, gguf_variant)
+ if template:
+ return template
+ except Exception as exc:
+ logger.debug("Could not read cached chat template for %s: %s", resolved, exc)
+
+ if is_anonymous(hf_token) and hf_env_offline():
+ # Offline, hf_hub_download serves the cached copy without checking the credential,
+ # so the fallback would hand back the template the walk just refused. The route
+ # forces offline whenever the Hub looks unreachable.
+ return None
try:
from huggingface_hub import HfApi, hf_hub_download
- _api = HfApi()
+ _api = HfApi(token = hf_token)
def _remote_worth_downloading(rel: str) -> bool:
# Reuse the size lookup to skip absent or oversized files.
diff --git a/studio/backend/routes/data_recipe/seed.py b/studio/backend/routes/data_recipe/seed.py
index 9c32b38945f..6c7c224687f 100644
--- a/studio/backend/routes/data_recipe/seed.py
+++ b/studio/backend/routes/data_recipe/seed.py
@@ -16,9 +16,12 @@ from pathlib import Path
from typing import Any
from uuid import uuid4
-from fastapi import APIRouter, HTTPException, UploadFile, File as FastAPIFile, Form
+from fastapi import APIRouter, Depends, HTTPException, UploadFile, File as FastAPIFile, Form
+from auth.authentication import allow_ambient_hf_token
from core.data_recipe.jsonable import to_preview_jsonable
+from hub.utils.hf_tokens import HfTokenArg, hf_token_arg, is_anonymous
+from utils.utils import hf_env_offline
from loggers import get_logger
from utils.paths import ensure_dir, seed_uploads_root, unstructured_uploads_root
from utils.utils import log_and_http_error
@@ -95,14 +98,14 @@ def _normalize_optional_text(value: str | None) -> str | None:
return trimmed if trimmed else None
-def _list_hf_data_files(*, dataset_name: str, token: str | None) -> list[str]:
+def _list_hf_data_files(*, dataset_name: str, token: HfTokenArg) -> list[str]:
try:
from huggingface_hub import HfApi
from huggingface_hub.utils import HfHubHTTPError
except ImportError:
return []
try:
- api = HfApi()
+ api = HfApi(token = token)
repo_files = api.list_repo_files(dataset_name, repo_type = "dataset", token = token)
return [file for file in repo_files if file.lower().endswith(DATA_EXTS)]
except (HfHubHTTPError, OSError, ValueError):
@@ -155,7 +158,7 @@ def _build_stream_load_kwargs(
dataset_name: str,
split: str,
subset: str | None,
- token: str | None,
+ token: HfTokenArg,
data_file: str | None = None,
) -> dict[str, Any]:
kwargs: dict[str, Any] = {
@@ -163,13 +166,12 @@ def _build_stream_load_kwargs(
"split": split,
"streaming": True,
"trust_remote_code": False,
+ "token": token,
}
if data_file:
kwargs["data_files"] = [data_file]
if subset:
kwargs["name"] = subset
- if token:
- kwargs["token"] = token
return kwargs
@@ -317,7 +319,9 @@ def _read_preview_rows_from_multi_files(
@router.post("/seed/inspect", response_model = SeedInspectResponse)
-def inspect_seed_dataset(payload: SeedInspectRequest) -> SeedInspectResponse:
+def inspect_seed_dataset(
+ payload: SeedInspectRequest, allow_ambient_token: bool = Depends(allow_ambient_hf_token)
+) -> SeedInspectResponse:
dataset_name = payload.dataset_name.strip()
if not dataset_name or dataset_name.count("/") < 1:
raise HTTPException(
@@ -338,8 +342,21 @@ def inspect_seed_dataset(payload: SeedInspectRequest) -> SeedInspectResponse:
split = _normalize_optional_text(payload.split) or DEFAULT_SPLIT
subset = _normalize_optional_text(payload.subset)
- token = _normalize_optional_text(payload.hf_token)
+ # From the caller, like every other Hub-reaching route: a hardcoded False would take
+ # the ambient fallback from UI sessions too.
+ token = hf_token_arg(
+ _normalize_optional_text(payload.hf_token),
+ allow_ambient_token = allow_ambient_token,
+ )
preview_size = int(payload.preview_size)
+ if is_anonymous(token) and hf_env_offline():
+ # Offline, `datasets` satisfies a streaming load from its own cache and the sentinel
+ # never reaches an authorization check, so a previously cached private dataset would
+ # come back as rows. The check-format path refuses the same way.
+ raise HTTPException(
+ status_code = 404,
+ detail = "Dataset preview is not available without Hub authorization.",
+ )
preview_rows: list[dict[str, Any]] = []
data_files = _list_hf_data_files(dataset_name = dataset_name, token = token)
diff --git a/studio/backend/routes/datasets.py b/studio/backend/routes/datasets.py
index 51efa14f830..c643c4f4c78 100644
--- a/studio/backend/routes/datasets.py
+++ b/studio/backend/routes/datasets.py
@@ -14,11 +14,12 @@ if str(backend_path) not in sys.path:
sys.path.insert(0, str(backend_path))
from auth.authentication import get_current_subject
-from hub.dependencies import get_hf_token
+from hub.dependencies import get_request_hf_token
from hub.schemas.datasets import (
AiAssistMappingRequest as HubAiAssistMappingRequest,
CheckFormatRequest as HubCheckFormatRequest,
)
+from hub.utils.hf_tokens import HfTokenArg
from hub.services.datasets import downloads, formatting, local
from models.datasets import (
AiAssistMappingRequest,
@@ -60,7 +61,7 @@ def list_local_datasets(
@router.get("/download-progress", deprecated = True)
async def get_dataset_download_progress(
repo_id: str = Query(..., description = "HuggingFace dataset repo ID, e.g. 'unsloth/LaTeX_OCR'"),
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
current_subject: str = Depends(get_current_subject),
):
return await downloads.get_dataset_download_progress_response(
@@ -72,7 +73,7 @@ async def get_dataset_download_progress(
@router.post("/check-format", response_model = CheckFormatResponse, deprecated = True)
def check_format(
request: CheckFormatRequest,
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
current_subject: str = Depends(get_current_subject),
) -> CheckFormatResponse:
hub_request = HubCheckFormatRequest.model_validate(request.model_dump(exclude = {"hf_token"}))
@@ -90,7 +91,7 @@ def check_format(
)
def ai_assist_mapping(
request: AiAssistMappingRequest,
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
current_subject: str = Depends(get_current_subject),
) -> AiAssistMappingResponse:
hub_request = HubAiAssistMappingRequest.model_validate(request.model_dump(exclude = {"hf_token"}))
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index d1e687761f9..ce279de99c4 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -50,7 +50,8 @@ from utils.models import extract_model_size_b as _extract_model_size_b
from utils.api_errors import openai_error_body, anthropic_error_body, error_body_for_path
from utils.upload_limits import STT_AUDIO_B64_MAX_CHARS, STT_AUDIO_RAW_MAX_BYTES
-from hub.dependencies import get_hf_token
+from hub.dependencies import get_hf_token, get_request_hf_token
+from hub.utils.hf_tokens import HfTokenArg
from hub.services.models.ollama import (
acquire_ollama_model_ref,
is_ollama_manifest_ref,
@@ -17258,7 +17259,7 @@ async def stt_status(
async def stt_download(
payload: SttLoadRequest,
current_subject: str = Depends(get_current_subject),
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
):
"""Start a background download of a dictation model.
@@ -17375,7 +17376,7 @@ async def stt_load(
async def stt_validate(
payload: SttLoadRequest,
current_subject: str = Depends(get_current_subject),
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
):
"""Verify a Hub repository is a Whisper checkpoint before downloading it."""
from core.inference.stt_sidecar import (
diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.py
index c708de7a807..f588465eb7e 100644
--- a/studio/backend/routes/models.py
+++ b/studio/backend/routes/models.py
@@ -192,8 +192,31 @@ backend_path = Path(__file__).parent.parent.parent
if str(backend_path) not in sys.path:
sys.path.insert(0, str(backend_path))
-from auth.authentication import get_current_subject
-from hub.dependencies import get_hf_token
+from auth.authentication import allow_ambient_hf_token, get_current_subject
+from hub.dependencies import get_hf_token, get_request_hf_token
+from hub.utils.hf_tokens import HfTokenArg, hf_token_arg, is_anonymous
+from utils.utils import anonymous_and_offline
+
+
+_UNAUTHORIZED_OFFLINE = "This request cannot be authorized without network access."
+
+
+def _resolve_hub_token(header_token: HfTokenArg, query_token: Optional[str]) -> HfTokenArg:
+ """Pick the credential for a route that still accepts the legacy ``?hf_token=``.
+
+ Header first, as it was before these routes resolved their token through a
+ dependency: the header is the caller's real credential and a stale query parameter
+ must not displace it. With neither explicit token present the sentinel is rebuilt
+ rather than the header handed back as-is: an ``or`` chain ending on the query value
+ would fall through ``False`` to ``None`` and restore the ambient token, while
+ returning ``header_token`` itself would return whatever a caller that bypassed
+ FastAPI's injection left in the parameter -- an unresolved ``Depends`` object.
+ """
+ explicit = _normalize_hf_token(header_token) or _normalize_hf_token(query_token)
+ if explicit:
+ return explicit
+ return False if is_anonymous(header_token) else None
+
try:
from utils.models import (
@@ -2263,7 +2286,7 @@ def _get_max_position_embeddings(config) -> Optional[int]:
_MODEL_WEIGHT_EXTENSIONS = (".safetensors", ".bin", ".pt", ".pth", ".gguf")
-def _get_model_size_bytes(model_name: str, hf_token: Optional[str] = None) -> Optional[int]:
+def _get_model_size_bytes(model_name: str, hf_token: HfTokenArg = None) -> Optional[int]:
"""Total size of model weight files from HF Hub."""
try:
from huggingface_hub import HfApi
@@ -2332,10 +2355,17 @@ def _get_snapshot_model_size_bytes(snapshot_path: str) -> Optional[int]:
def _model_config_inspection_target(
- model_name: str, prefer_local_cache: bool, local_path: Optional[str]
+ model_name: str,
+ prefer_local_cache: bool,
+ local_path: Optional[str],
+ hf_token: HfTokenArg = None,
) -> str:
if not prefer_local_cache or is_local_path(model_name):
return model_name
+ # The cached snapshot answers from disk without consulting the token, so a caller
+ # denied the ambient credential is sent to the Hub, which refuses a private repo.
+ if is_anonymous(hf_token):
+ return model_name
from hub.utils.hf_cache_state import (
latest_snapshot_from_cache_path,
with_load_subdirs,
@@ -2362,16 +2392,24 @@ async def get_model_config(
prefer_local_cache: bool = False,
local_path: Optional[str] = None,
header_hf_token: Optional[str] = Depends(get_hf_token),
+ allow_ambient_token: bool = Depends(allow_ambient_hf_token),
current_subject: str = Depends(get_current_subject),
):
"""Get configuration for a specific model (wraps load_model_defaults)."""
- hf_token = _normalize_hf_token(header_hf_token) or _normalize_hf_token(hf_token)
+ hf_token = hf_token_arg(
+ _normalize_hf_token(header_hf_token) or _normalize_hf_token(hf_token),
+ allow_ambient_token = allow_ambient_token,
+ )
from core.inference.llama_cpp import _hf_offline_if_unreachable_for
def _resolve(model_name: str) -> ModelDetails:
# Each probe below can reach the hub, so the guard wraps the whole handler: offline they
# must all resolve from the HF cache. Local paths stay on disk and skip the probe.
with _hf_offline_if_unreachable_for(model_name):
+ # Inside the context, not before: the guard forces offline itself when the hub
+ # is unreachable, and every probe below then resolves from disk.
+ if anonymous_and_offline(hf_token) and not is_local_path(model_name):
+ raise HTTPException(status_code = 404, detail = _UNAUTHORIZED_OFFLINE)
if not is_local_path(model_name):
resolved = resolve_cached_repo_id_case(model_name)
if resolved != model_name:
@@ -2389,19 +2427,23 @@ async def get_model_config(
model_name,
prefer_local_cache,
local_path,
+ hf_token,
)
config_dict = load_model_defaults(model_name)
+ # The bare repo id above only helps if the probes then go over the wire:
+ # local_files_only resolves config.json out of the cache, unauthorized.
+ probe_local_only = prefer_local_cache and not is_anonymous(hf_token)
is_vision = is_vision_model(
inspection_target,
hf_token = hf_token,
- local_files_only = prefer_local_cache,
+ local_files_only = probe_local_only,
)
is_embedding = is_embedding_model(inspection_target, hf_token = hf_token)
audio_type, audio_type_definitive = detect_audio_type_checked(
_audio_probe_target(inspection_target),
hf_token = hf_token,
- local_files_only = prefer_local_cache,
+ local_files_only = probe_local_only,
)
is_lora = False
@@ -2453,9 +2495,11 @@ async def get_model_config(
model_type = derive_model_type(is_vision, audio_type, is_embedding),
base_model = base_model,
max_position_embeddings = max_position_embeddings,
+ # Keyed on the target, not the flag: the bare repo id an anonymous caller
+ # gets sizes as a relative path and returns None, public repos included.
model_size_bytes = (
_get_snapshot_model_size_bytes(inspection_target)
- if prefer_local_cache
+ if prefer_local_cache and inspection_target != model_name
else _get_model_size_bytes(model_name, hf_token)
),
)
@@ -2501,6 +2545,7 @@ async def scan_model_remote_code(
model_local_path: Optional[str] = Body(None, embed = True),
model_snapshot_path: Optional[str] = Body(None, embed = True),
model_snapshot_repo_id: Optional[str] = Body(None, embed = True),
+ allow_ambient_token: bool = Depends(allow_ambient_hf_token),
current_subject: str = Depends(get_current_subject),
):
"""Scan a model's ``auto_map`` custom code so the UI can show findings before
@@ -2511,6 +2556,13 @@ async def scan_model_remote_code(
POST (not GET) so the ``hf_token`` for gated repos travels in the body and
never lands in a URL, browser history, or access log.
"""
+ # Without this an absent body token reads as None, i.e. ambient-authorized, and the
+ # scan returns source snippets from a cached private repo.
+ hf_token = hf_token_arg(hf_token, allow_ambient_token = allow_ambient_token)
+ # Offline the scanner's hf_hub_download calls resolve config.json and the repo's
+ # Python out of the cache, and the response carries source snippets.
+ if anonymous_and_offline(hf_token) and not is_local_path(model_name):
+ raise HTTPException(status_code = 404, detail = _UNAUTHORIZED_OFFLINE)
try:
from utils.security import (
load_scan_target,
@@ -2552,8 +2604,11 @@ async def scan_model_remote_code(
exact_snapshot_repo_id,
True,
normalize_path(exact_snapshot_path),
+ hf_token,
)
- elif prefer_local_cache is True and not local_model:
+ elif prefer_local_cache is True and not local_model and not is_anonymous(hf_token):
+ # Same guard as the exact_snapshot branch: resolving to a cached snapshot
+ # hands the scanner a private repo's Python, unauthorized.
from core.training.training import _resolve_model_snapshot
local_path = normalize_path(model_local_path) if model_local_path else None
scan_target = _resolve_model_snapshot(model_name, local_path) or model_name
@@ -2835,7 +2890,7 @@ async def scan_loras(
exports_dir: str = Query(
default = str(exports_root()), description = "Directory to scan for exported models"
),
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
current_subject: str = Depends(get_current_subject),
):
"""Scan for trained LoRA adapters and exported models.
@@ -3458,6 +3513,7 @@ async def check_vision_model(
model_name: str,
hf_token: Optional[str] = Query(None),
header_hf_token: Optional[str] = Depends(get_hf_token),
+ allow_ambient_token: bool = Depends(allow_ambient_hf_token),
current_subject: str = Depends(get_current_subject),
):
"""
@@ -3465,7 +3521,10 @@ async def check_vision_model(
This endpoint wraps the backend is_vision_model function.
"""
- hf_token = _normalize_hf_token(header_hf_token) or _normalize_hf_token(hf_token)
+ hf_token = hf_token_arg(
+ _normalize_hf_token(header_hf_token) or _normalize_hf_token(hf_token),
+ allow_ambient_token = allow_ambient_token,
+ )
try:
logger.info(f"Checking if vision model: {model_name}")
# Authenticate so a gated/private VLM classifies correctly (else 404 -> non-vision). Offline
@@ -3500,6 +3559,7 @@ async def check_embedding_model(
model_name: str,
hf_token: Optional[str] = Query(None),
header_hf_token: Optional[str] = Depends(get_hf_token),
+ allow_ambient_token: bool = Depends(allow_ambient_hf_token),
current_subject: str = Depends(get_current_subject),
):
"""
@@ -3507,7 +3567,10 @@ async def check_embedding_model(
This endpoint wraps the backend is_embedding_model function.
"""
- hf_token = _normalize_hf_token(header_hf_token) or _normalize_hf_token(hf_token)
+ hf_token = hf_token_arg(
+ _normalize_hf_token(header_hf_token) or _normalize_hf_token(hf_token),
+ allow_ambient_token = allow_ambient_token,
+ )
try:
logger.info(f"Checking if embedding model: {model_name}")
# Same guard as /check-vision: is_embedding_model hits the hub with a 15s timeout.
@@ -4444,12 +4507,12 @@ async def get_gguf_variants(
offline: bool = False,
local_path: Optional[str] = None,
hf_token: Optional[str] = Query(None, description = "HuggingFace token for private repos"),
- hf_token_header: Optional[str] = Depends(get_hf_token),
+ hf_token_header: HfTokenArg = Depends(get_request_hf_token),
current_subject: str = Depends(get_current_subject),
):
"""List GGUF quantization variants for a HF repo or local directory."""
try:
- hf_token = _normalize_hf_token(hf_token_header) or _normalize_hf_token(hf_token)
+ hf_token = _resolve_hub_token(hf_token_header, hf_token)
from hub.services.models import gguf_variants as hub_gguf_variants
answer = await hub_gguf_variants.get_gguf_variants_answer(
@@ -4511,7 +4574,7 @@ async def get_gguf_download_progress(
repo_id: str = Query(..., description = "HuggingFace repo ID"),
variant: str = Query("", description = "Quantization variant (e.g. UD-TQ1_0)"),
expected_bytes: int = Query(0, description = "Expected total download size in bytes"),
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
current_subject: str = Depends(get_current_subject),
):
"""Compatibility route backed by the shared multi-cache progress service."""
@@ -4538,7 +4601,7 @@ def _resolve_hf_cache_realpath(repo_dir: Path) -> Optional[str]:
@router.get("/download-progress")
async def get_download_progress(
repo_id: str = Query(..., description = "HuggingFace repo ID"),
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
current_subject: str = Depends(get_current_subject),
):
"""Compatibility route backed by the shared multi-cache progress service."""
@@ -5037,7 +5100,7 @@ def _cached_repo_partial(
@router.get("/cached-models", response_model = CachedModelsResponse)
async def list_cached_models(
current_subject: str = Depends(get_current_subject),
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
):
"""List non-GGUF model repos downloaded to HF cache, legacy Unsloth cache, and HF default cache."""
try:
@@ -5327,7 +5390,7 @@ async def delete_cached_model(
repo_id: str = Body(...),
variant: Optional[str] = Body(None),
cache_path: Optional[str] = Body(None),
- hf_token: Optional[str] = Depends(get_hf_token),
+ hf_token: HfTokenArg = Depends(get_request_hf_token),
current_subject: str = Depends(get_current_subject),
):
"""Compatibility route backed by the shared multi-cache deletion service."""
diff --git a/studio/backend/tests/test_consent_gate.py b/studio/backend/tests/test_consent_gate.py
index 24c44aea11e..00b58fb7156 100644
--- a/studio/backend/tests/test_consent_gate.py
+++ b/studio/backend/tests/test_consent_gate.py
@@ -882,7 +882,11 @@ class TestStructuredFindingsForDialog:
monkeypatch.setattr(
models_route,
"_model_config_inspection_target",
- lambda name, prefer_local, path: inspection_calls.append((name, prefer_local, path))
+ # Takes the caller's token too now: an anonymous caller is sent back to the
+ # bare repo id rather than a cached snapshot it never authorized.
+ lambda name, prefer_local, path, hf_token = None: inspection_calls.append(
+ (name, prefer_local, path)
+ )
or snapshot,
)
monkeypatch.setattr(
diff --git a/studio/backend/tests/test_export_absolute_paths.py b/studio/backend/tests/test_export_absolute_paths.py
index d65b7dedc12..71de56542fa 100644
--- a/studio/backend/tests/test_export_absolute_paths.py
+++ b/studio/backend/tests/test_export_absolute_paths.py
@@ -98,6 +98,9 @@ def _install_lightweight_backend_stubs(monkeypatch):
auth_pkg = types.ModuleType("auth")
auth_mod = types.ModuleType("auth.authentication")
auth_mod.get_current_subject = lambda: None
+ # routes/models.py imports this alongside get_current_subject; a stub missing it
+ # fails the import with "unknown location", which reads like a path problem.
+ auth_mod.allow_ambient_hf_token = lambda: True
monkeypatch.setitem(sys.modules, "auth", auth_pkg)
monkeypatch.setitem(sys.modules, "auth.authentication", auth_mod)
@@ -142,6 +145,9 @@ def _install_lightweight_backend_stubs(monkeypatch):
_HTTPException(kwargs.get("status_code", 500), kwargs.get("detail"))
)
utils_utils.canonical_model_repo_id = lambda value: value
+ # routes/models.py refuses a forced-anonymous caller offline through this; the stub
+ # answers False so the export paths under test take their ordinary route.
+ utils_utils.anonymous_and_offline = lambda _hf_token: False
utils_utils.safe_error_detail = lambda value: str(value)
monkeypatch.setitem(sys.modules, "utils.utils", utils_utils)
diff --git a/studio/backend/tests/test_hub_download_ambient_token.py b/studio/backend/tests/test_hub_download_ambient_token.py
index c53e11ec39c..63fcddc894a 100644
--- a/studio/backend/tests/test_hub_download_ambient_token.py
+++ b/studio/backend/tests/test_hub_download_ambient_token.py
@@ -25,10 +25,12 @@ from auth.authentication import (
)
from hub.routes import datasets as datasets_routes
from hub.routes import inventory as inventory_routes
+from hub.dependencies import get_request_hf_token
from hub.services import download_lifecycle
from hub.services.datasets import downloads as dataset_downloads
from hub.services.models import downloads as model_downloads
from hub.utils import download_registry, state_dir
+from routes import models as models_routes
class _Proc:
@@ -71,11 +73,98 @@ def _client(via_api_key: bool) -> TestClient:
return TestClient(app)
+def _models_client(via_api_key: bool) -> TestClient:
+ app = FastAPI()
+ app.include_router(models_routes.router, prefix = "/api/models")
+ app.dependency_overrides[get_current_subject] = lambda: "alice"
+ app.dependency_overrides[authenticated_via_api_key] = lambda: via_api_key
+ return TestClient(app)
+
+
@pytest.mark.parametrize("via_api_key, expected", [(True, False), (False, True)])
def test_only_a_ui_session_may_borrow_the_backend_token(via_api_key, expected):
assert asyncio.run(allow_ambient_hf_token(via_api_key = via_api_key)) is expected
+ "hf_token, allow_ambient, expected",
+ [
+ (None, False, False),
+ (None, True, None),
+ ("request-token", False, "request-token"),
+ (" request-token ", True, "request-token"),
+ ],
+)
+def test_request_metadata_token_keeps_the_caller_boundary(hf_token, allow_ambient, expected):
+ resolved = get_request_hf_token(
+ hf_token = hf_token,
+ allow_ambient_token = allow_ambient,
+ )
+ assert resolved == expected
+ if expected in (None, False):
+ assert resolved is expected
+
+
[email protected]("via_api_key, expected", [(True, False), (False, None)])
+def test_gguf_metadata_route_does_not_lend_api_keys_the_backend_token(
+ monkeypatch, via_api_key, expected
+):
+ seen = {}
+
+ async def _fake(repo_id, **kwargs):
+ seen["repo_id"] = repo_id
+ seen["hf_token"] = kwargs["hf_token"]
+ return {"repo_id": repo_id, "variants": []}
+
+ monkeypatch.setattr(inventory_routes.gguf_variants, "get_gguf_variants_response", _fake)
+ response = _client(via_api_key).get(
+ "/api/hub/gguf-variants?repo_id=attacker/private-model",
+ headers = {"Authorization": "Bearer token"},
+ )
+
+ assert response.status_code == 200, response.text
+ assert seen == {"repo_id": "attacker/private-model", "hf_token": expected}
+
+
+def test_explicit_metadata_token_wins_for_an_api_key(monkeypatch):
+ seen = {}
+
+ async def _fake(repo_id, **kwargs):
+ seen["hf_token"] = kwargs["hf_token"]
+ return {"repo_id": repo_id, "variants": []}
+
+ monkeypatch.setattr(inventory_routes.gguf_variants, "get_gguf_variants_response", _fake)
+ response = _client(True).get(
+ "/api/hub/gguf-variants?repo_id=owner/private-model",
+ headers = {
+ "Authorization": "Bearer token",
+ "X-Unsloth-HF-Token": "request-token",
+ },
+ )
+
+ assert response.status_code == 200, response.text
+ assert seen["hf_token"] == "request-token"
+
+
[email protected]("via_api_key, expected", [(True, False), (False, None)])
+def test_compatibility_progress_route_keeps_the_caller_boundary(monkeypatch, via_api_key, expected):
+ seen = {}
+
+ async def _fake(repo_id, **kwargs):
+ seen["repo_id"] = repo_id
+ seen["hf_token"] = kwargs["hf_token"]
+ return {"repo_id": repo_id, "progress": 0.0}
+
+ monkeypatch.setattr(model_downloads, "get_download_progress_response", _fake)
+ response = _models_client(via_api_key).get(
+ "/api/models/download-progress?repo_id=attacker/private-model",
+ headers = {"Authorization": "Bearer token"},
+ )
+
+ assert response.status_code == 200, response.text
+ assert seen == {"repo_id": "attacker/private-model", "hf_token": expected}
+
+
@pytest.mark.parametrize("via_api_key, expected", [(True, False), (False, True)])
def test_model_download_route_gates_the_ambient_token(monkeypatch, via_api_key, expected):
seen = {}
diff --git a/studio/backend/tests/test_hub_token_cache_isolation.py b/studio/backend/tests/test_hub_token_cache_isolation.py
new file mode 100644
index 00000000000..7c895c5e9d2
--- /dev/null
+++ b/studio/backend/tests/test_hub_token_cache_isolation.py
@@ -0,0 +1,204 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""A per-token cache is only a boundary if the two callers hash to different tokens.
+
+``token_fingerprint`` folded every falsy token into ``""``, so ``False`` shared an identity
+with ``None`` and the caches leaked both ways: a UI session's private-repo metadata read
+back by an API key, and an API key's 403 blanking the UI's next lookup. The dataset cache
+is sharpest -- its own ``not restricted or cached_fp == token_fp`` guard became ``"" == ""``.
+These drive the real cache, not the fingerprint in isolation.
+"""
+
+import asyncio
+import time
+from types import SimpleNamespace
+
+import pytest
+
+from hub.services.datasets import downloads as dataset_downloads
+from hub.services.models import gguf_variants
+from hub.utils.inventory_scan import token_fingerprint
+
+
+def _sibling(name: str, size: int, sha: str):
+ return SimpleNamespace(rfilename = name, size = size, lfs = SimpleNamespace(sha256 = sha))
+
+
+def _clear_dataset_caches():
+ with dataset_downloads._dataset_size_cache_lock:
+ dataset_downloads._dataset_size_cache.clear()
+ dataset_downloads._dataset_size_neg_cache.clear()
+
+
[email protected](autouse = True)
+def _isolated_caches():
+ _clear_dataset_caches()
+ yield
+ _clear_dataset_caches()
+
+
+def _stub_dataset_info(monkeypatch, *, private: bool, calls: list):
+ """Answer dataset_info only for a token that is actually allowed to see the repo."""
+
+ def _api(*_args, **kwargs):
+ token = kwargs.get("token")
+ calls.append(token)
+
+ def _dataset_info(repo_id, **_kw):
+ if private and not isinstance(token, str):
+ # Anonymous or ambient-less: the Hub 404s a private repo.
+ raise RuntimeError("401 Unauthorized")
+ return SimpleNamespace(
+ siblings = [_sibling("data/train.parquet", 4096, "sha-private")],
+ private = private,
+ gated = False,
+ )
+
+ return SimpleNamespace(dataset_info = _dataset_info)
+
+ import huggingface_hub
+
+ monkeypatch.setattr(huggingface_hub, "HfApi", _api)
+
+
+def test_a_ui_session_private_dataset_is_not_served_to_an_anonymous_caller(monkeypatch):
+ calls: list = []
+ _stub_dataset_info(monkeypatch, private = True, calls = calls)
+
+ size, hashes = dataset_downloads.get_dataset_snapshot_metadata_cached(
+ "org/private-set", "hf_operator_token"
+ )
+ assert size == 4096 and "sha-private" in hashes
+
+ anon_size, anon_hashes = dataset_downloads.get_dataset_snapshot_metadata_cached(
+ "org/private-set", False
+ )
+
+ assert (anon_size, anon_hashes) == (0, frozenset()), (
+ "the anonymous caller was served a private dataset's size and blob hashes "
+ "out of the cache the UI session filled"
+ )
+ assert calls[-1] is False
+
+
+def test_an_ambient_ui_entry_is_not_served_to_an_anonymous_caller(monkeypatch):
+ """``None`` (ambient install) and ``False`` shared one identity: the exact disclosure."""
+ calls: list = []
+
+ def _api(*_args, **kwargs):
+ token = kwargs.get("token")
+ calls.append(token)
+
+ def _dataset_info(repo_id, **_kw):
+ # `None` carries the ambient HF_TOKEN and succeeds; `False` sends none.
+ if token is False:
+ raise RuntimeError("401 Unauthorized")
+ return SimpleNamespace(
+ siblings = [_sibling("data/train.parquet", 4096, "sha-private")],
+ private = True,
+ gated = False,
+ )
+
+ return SimpleNamespace(dataset_info = _dataset_info)
+
+ import huggingface_hub
+
+ monkeypatch.setattr(huggingface_hub, "HfApi", _api)
+
+ size, hashes = dataset_downloads.get_dataset_snapshot_metadata_cached("org/private-set", None)
+ assert size == 4096 and "sha-private" in hashes
+
+ anon = dataset_downloads.get_dataset_snapshot_metadata_cached("org/private-set", False)
+
+ assert anon == (0, frozenset()), (
+ "an API key read a private dataset's metadata out of the slot a UI session "
+ "filled with the backend's ambient credential"
+ )
+ assert calls == [None, False]
+
+
+def test_an_anonymous_denial_does_not_blank_a_later_ui_lookup(monkeypatch):
+ """The negative direction: denial-of-service rather than disclosure."""
+ calls: list = []
+ _stub_dataset_info(monkeypatch, private = True, calls = calls)
+
+ refused = dataset_downloads.get_dataset_snapshot_metadata_cached("org/private-set", False)
+ assert refused == (0, frozenset())
+
+ size, hashes = dataset_downloads.get_dataset_snapshot_metadata_cached(
+ "org/private-set", "hf_operator_token"
+ )
+
+ assert size == 4096 and "sha-private" in hashes, (
+ "an API key's anonymous denial poisoned the UI session's cache slot"
+ )
+
+
+def test_the_same_caller_still_gets_a_cache_hit(monkeypatch):
+ """The fix must not turn every lookup into a miss."""
+ calls: list = []
+ _stub_dataset_info(monkeypatch, private = True, calls = calls)
+
+ first = dataset_downloads.get_dataset_snapshot_metadata_cached(
+ "org/private-set", "hf_operator_token"
+ )
+ second = dataset_downloads.get_dataset_snapshot_metadata_cached(
+ "org/private-set", "hf_operator_token"
+ )
+
+ assert first == second
+ assert len(calls) == 1, "the second identical lookup should have been a cache hit"
+
+
+def test_concurrent_callers_of_different_credentials_do_not_share_one_scan():
+ """Not TTL-bounded: whichever credential started the shared task decided both answers."""
+ computed: list = []
+
+ def _key(token):
+ return ("org/repo", False, False, "", token_fingerprint(token), "cache")
+
+ async def _drive():
+ def _compute(token):
+ # Sync: _shared_variants_scan runs it in a thread. The sleep holds it in flight.
+ computed.append(token)
+ time.sleep(0.05)
+ return f"result-for-{token}"
+
+ async def _run(token):
+ return await gguf_variants._shared_variants_scan(_key(token), lambda: _compute(token))
+
+ return await asyncio.gather(_run(None), _run(False))
+
+ ambient_result, anon_result = asyncio.run(_drive())
+
+ assert ambient_result == "result-for-None"
+ assert anon_result == "result-for-False", (
+ "the anonymous caller received the scan computed under the ambient credential"
+ )
+ assert sorted(map(str, computed)) == [
+ "False",
+ "None",
+ ], "both credentials must run their own scan"
+
+
+def test_concurrent_callers_of_the_same_credential_still_dedupe():
+ """The fix must not defeat the deduplication the in-flight map exists for."""
+ computed: list = []
+
+ async def _drive():
+ def _compute():
+ computed.append(1)
+ time.sleep(0.05)
+ return "shared"
+
+ key = ("org/repo", False, False, "", token_fingerprint(False), "cache")
+ return await asyncio.gather(
+ gguf_variants._shared_variants_scan(key, _compute),
+ gguf_variants._shared_variants_scan(key, _compute),
+ )
+
+ first, second = asyncio.run(_drive())
+
+ assert first == second == "shared"
+ assert len(computed) == 1, "two identical-scope requests should share one scan"
diff --git a/studio/backend/tests/test_hub_token_caller_identity.py b/studio/backend/tests/test_hub_token_caller_identity.py
new file mode 100644
index 00000000000..728f5d5cab7
--- /dev/null
+++ b/studio/backend/tests/test_hub_token_caller_identity.py
@@ -0,0 +1,926 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The forced-anonymous sentinel is a credential of its own, not the absence of one.
+
+``hf_token_arg`` returns three values where everything downstream expects ``Optional[str]``,
+so ``False`` breaks four ways: a truthiness test reaches for the ambient token anyway, an
+identity test hits ``.encode()`` on a bool, a shared cache fingerprint crosses the boundary,
+and a child env inherits what it was never granted. ``is`` throughout: ``False == 0 == ""``.
+"""
+
+import hashlib
+import os
+from types import SimpleNamespace
+from pathlib import Path
+from typing import Optional
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from auth.authentication import authenticated_via_api_key, get_current_subject
+from core.inference import diffusion_compat
+from hub.dependencies import get_request_hf_token
+from hub.utils.hf_tokens import (
+ ANONYMOUS_CACHE_IDENTITY,
+ apply_token_to_child_env,
+ hf_token_arg,
+ is_anonymous,
+ normalize_token,
+)
+from hub.utils.inventory_scan import token_fingerprint
+from routes import models as models_routes
+from utils.models.model_config import _token_fingerprint as capability_fingerprint
+from utils.transformers_version import _token_cache_key
+
+
+def _models_client(via_api_key: bool) -> TestClient:
+ app = FastAPI()
+ app.include_router(models_routes.router, prefix = "/api/models")
+ app.dependency_overrides[get_current_subject] = lambda: "alice"
+ app.dependency_overrides[authenticated_via_api_key] = lambda: via_api_key
+ return TestClient(app, raise_server_exceptions = False)
+
+
+ "hf_token, allow_ambient, expected",
+ [
+ (None, False, False),
+ (None, True, None),
+ (" request-token ", False, "request-token"),
+ (" request-token ", True, "request-token"),
+ ("", False, False),
+ (" ", True, None),
+ ],
+)
+def test_the_resolver_returns_one_of_exactly_three_values(hf_token, allow_ambient, expected):
+ resolved = hf_token_arg(hf_token, allow_ambient_token = allow_ambient)
+ assert resolved is expected if expected in (None, False) else resolved == expected
+
+
+def test_only_the_sentinel_reads_as_anonymous():
+ assert is_anonymous(False) is True
+ # The three values a "simplification" to `not hf_token` would wrongly sweep in.
+ for absent in (None, "", 0):
+ assert is_anonymous(absent) is False
+
+
+def test_normalizing_a_token_does_not_launder_the_sentinel():
+ # `(hf_token or "").strip() or None` turns "stay anonymous" into "use the backend's".
+ assert normalize_token(False) is False
+ assert normalize_token(None) is None
+ assert normalize_token(" tok ") == "tok"
+ assert normalize_token("") is None
+
+
+ "fingerprint, absent",
+ [
+ (token_fingerprint, ""),
+ (capability_fingerprint, None),
+ (diffusion_compat._token_fingerprint, ""),
+ ],
+ ids = ["inventory_scan", "model_capability", "diffusion_compat"],
+)
+def test_every_fingerprint_separates_anonymous_from_ambient(fingerprint, absent):
+ anonymous = fingerprint(False)
+ ambient = fingerprint(None)
+
+ assert ambient == absent
+ assert anonymous == ANONYMOUS_CACHE_IDENTITY
+ assert anonymous != ambient, (
+ "an anonymous caller sharing the ambient cache slot reads back metadata "
+ "fetched with the operator's credential"
+ )
+ assert fingerprint("hf_realtoken") not in (anonymous, ambient)
+
+
+def test_the_anonymous_identity_cannot_collide_with_a_token_digest():
+ assert not all(character in "0123456789abcdef" for character in ANONYMOUS_CACHE_IDENTITY)
+
+
+def test_a_fingerprint_never_carries_the_token():
+ secret = "hf_supersecretvalue123"
+ for fingerprint in (
+ token_fingerprint,
+ capability_fingerprint,
+ diffusion_compat._token_fingerprint,
+ ):
+ assert secret not in str(fingerprint(secret))
+
+
+def test_config_metadata_cache_keys_separate_anonymous_from_ambient():
+ # These carry a private repo's config.json / tokenizer_config.json.
+ assert _token_cache_key("org/private", False) != _token_cache_key("org/private", None)
+ assert _token_cache_key("org/private", False) == ("org/private", ANONYMOUS_CACHE_IDENTITY)
+
+
+def test_capability_fingerprint_does_not_raise_on_the_sentinel():
+ # `if token is None` let False through to `.encode()`: /check-vision and /config 500d.
+ assert capability_fingerprint(False) == ANONYMOUS_CACHE_IDENTITY
+ assert hashlib.sha256(b"x").hexdigest() != capability_fingerprint(False)
+
+
+def _child_env(hf_token):
+ env = {
+ "HF_TOKEN": "ambient-operator-token",
+ "HUGGING_FACE_HUB_TOKEN": "ambient-legacy-alias",
+ "HUGGINGFACEHUB_API_TOKEN": "ambient-other-alias",
+ "PATH": "/usr/bin",
+ }
+ apply_token_to_child_env(env, hf_token)
+ return env
+
+
+def test_an_anonymous_probe_child_cannot_inherit_the_ambient_token():
+ env = _child_env(False)
+
+ for key in ("HF_TOKEN", "HUGGING_FACE_HUB_TOKEN", "HUGGINGFACEHUB_API_TOKEN"):
+ assert key not in env, f"{key} survived into an anonymous child"
+ # get_token() still answers from a cached login file otherwise.
+ assert env["HF_HUB_DISABLE_IMPLICIT_TOKEN"] == "1"
+ assert env["PATH"] == "/usr/bin"
+
+
+def test_a_ui_session_probe_child_keeps_the_ambient_token():
+ # Scrubbing here would break gated repos on installs whose token is in the env.
+ env = _child_env(None)
+
+ assert env["HF_TOKEN"] == "ambient-operator-token"
+ assert "HF_HUB_DISABLE_IMPLICIT_TOKEN" not in env
+
+
+def test_an_explicit_token_replaces_the_ambient_one_in_the_child():
+ env = _child_env("hf_caller_token")
+
+ assert env["HF_TOKEN"] == "hf_caller_token"
+ # An inherited "1" would 401 a gated repo the caller does have access to.
+ assert env["HF_HUB_DISABLE_IMPLICIT_TOKEN"] == "0"
+
+
[email protected]("via_api_key", [True, False])
+def test_capability_routes_answer_both_callers_without_a_server_error(monkeypatch, via_api_key):
+ """The blocker this file was written for: /check-vision 500ed for an API-key caller."""
+ seen = {}
+
+ def _fake_is_vision_model(
+ model_name,
+ hf_token = None,
+ **_kwargs,
+ ):
+ seen["hf_token"] = hf_token
+ return False
+
+ monkeypatch.setattr(models_routes, "is_vision_model", _fake_is_vision_model)
+ response = _models_client(via_api_key).get(
+ "/api/models/check-vision/org/some-model",
+ headers = {"Authorization": "Bearer token"},
+ )
+
+ assert response.status_code == 200, response.text
+ assert seen["hf_token"] is (False if via_api_key else None)
+
+
+ "header, query, expected",
+ [
+ # An `or` chain ending on the query value would turn False into None here.
+ (False, None, False),
+ (None, None, None),
+ (False, "", False),
+ ("header-token", "query-token", "header-token"),
+ ("header-token", None, "header-token"),
+ (None, "query-token", "query-token"),
+ (False, "query-token", "query-token"),
+ (" header-token ", None, "header-token"),
+ ],
+)
+def test_gguf_variants_token_precedence_survives_the_conversion(header, query, expected):
+ resolved = models_routes._resolve_hub_token(header, query)
+
+ if expected in (None, False):
+ assert resolved is expected
+ else:
+ assert resolved == expected
+
+
+def test_seed_inspection_derives_its_policy_from_the_caller(monkeypatch):
+ """A UI session on an ambient-token install keeps gated seed inspection."""
+ from routes.data_recipe import seed as seed_routes
+
+ seen = {}
+
+ def _fake_list(*, dataset_name, token):
+ seen["token"] = token
+ return []
+
+ monkeypatch.setattr(seed_routes, "_list_hf_data_files", _fake_list)
+
+ for via_api_key in (True, False):
+ app = FastAPI()
+ app.include_router(seed_routes.router, prefix = "/api/data-recipe")
+ app.dependency_overrides[get_current_subject] = lambda: "alice"
+ app.dependency_overrides[authenticated_via_api_key] = lambda: via_api_key
+ client = TestClient(app, raise_server_exceptions = False)
+
+ client.post(
+ "/api/data-recipe/seed/inspect",
+ json = {"dataset_name": "org/private-seed"},
+ headers = {"Authorization": "Bearer token"},
+ )
+ assert seen["token"] is (False if via_api_key else None), (
+ "hardcoding allow_ambient_token=False takes the fallback away from the UI too"
+ )
+
+
+def test_an_explicit_seed_token_wins_for_either_caller(monkeypatch):
+ from routes.data_recipe import seed as seed_routes
+
+ seen = {}
+ monkeypatch.setattr(
+ seed_routes,
+ "_list_hf_data_files",
+ lambda *, dataset_name, token: seen.update(token = token) or [],
+ )
+
+ for via_api_key in (True, False):
+ app = FastAPI()
+ app.include_router(seed_routes.router, prefix = "/api/data-recipe")
+ app.dependency_overrides[get_current_subject] = lambda: "alice"
+ app.dependency_overrides[authenticated_via_api_key] = lambda: via_api_key
+ TestClient(app, raise_server_exceptions = False).post(
+ "/api/data-recipe/seed/inspect",
+ json = {"dataset_name": "org/private-seed", "hf_token": " caller-token "},
+ headers = {"Authorization": "Bearer token"},
+ )
+ assert seen["token"] == "caller-token"
+
+
+ "hf_token, allow_ambient, expected",
+ [
+ (None, False, False),
+ (None, True, None),
+ ("request-token", False, "request-token"),
+ (" request-token ", True, "request-token"),
+ ],
+)
+def test_the_request_dependency_keeps_the_caller_boundary(hf_token, allow_ambient, expected):
+ resolved = get_request_hf_token(hf_token = hf_token, allow_ambient_token = allow_ambient)
+
+ assert resolved == expected
+ if expected in (None, False):
+ assert resolved is expected
+
+
+def test_the_media_load_models_still_reject_the_sentinel():
+ """Why /v1/images/generations, /v1/videos and /video/generate keep the old dependency.
+
+ All three reach maybe_auto_switch_media_model, whose _start_load builds a
+ DiffusionLoadRequest / VideoLoadRequest. Both declare ``hf_token: Optional[str]``, so the
+ sentinel is a ValidationError that kills the switch. Threading HfTokenArg through the load
+ path means auditing ~30 `request.hf_token` consumers in routes/inference.py, which is a
+ change of its own; until then those routes stay on get_hf_token and this test says so.
+ """
+ import pydantic
+ from models.inference import DiffusionLoadRequest, VideoLoadRequest
+
+ for model in (DiffusionLoadRequest, VideoLoadRequest):
+ assert model.model_fields["hf_token"].annotation == Optional[str]
+ with pytest.raises(pydantic.ValidationError):
+ model(model_path = "org/repo", hf_token = False)
+
+
+ "route_line, expected",
+ [("audio/stt/download", True), ("audio/stt/validate", True)],
+)
+def test_the_stt_routes_keep_the_caller_boundary(route_line, expected):
+ """The STT pair is converted: it downloads a whole repo and has no pydantic sink."""
+ source = (Path(__file__).resolve().parent.parent / "routes" / "inference.py").read_text(
+ encoding = "utf-8"
+ )
+ marker = source.index(f'"/{route_line}"')
+ signature = source[marker : marker + 400]
+ assert ("Depends(get_request_hf_token)" in signature) is expected
+
+
+def test_an_explicit_token_evicts_the_ambient_aliases_too():
+ """Granting HF_TOKEN alone leaves the operator's credential in a legacy alias."""
+ env = _child_env("hf_caller_token")
+
+ assert env["HF_TOKEN"] == "hf_caller_token"
+ for alias in ("HUGGING_FACE_HUB_TOKEN", "HUGGINGFACEHUB_API_TOKEN"):
+ assert alias not in env, f"{alias} still carried the operator credential"
+
+
+def test_the_audio_tokenizer_fallback_does_not_reach_for_the_ambient_token(monkeypatch):
+ """`hf_token or os.environ.get("HF_TOKEN")` reads past the sentinel to the operator's."""
+ import utils.models.model_config as mc
+
+ monkeypatch.setenv("HF_TOKEN", "ambient-operator-token")
+ seen = {}
+
+ class _Resp:
+ status_code = 404
+ text = ""
+
+ def json(self):
+ return {}
+
+ def _get(
+ url,
+ headers = None,
+ timeout = None,
+ **_kw,
+ ):
+ seen.setdefault("headers", headers)
+ return _Resp()
+
+ import requests
+
+ monkeypatch.setattr(requests, "get", _get)
+ mc._detect_audio_from_tokenizer("org/private", hf_token = False, revision = None)
+
+ assert "Authorization" not in (seen.get("headers") or {}), (
+ "an anonymous caller's tokenizer probe carried the operator's bearer"
+ )
+
+
+def test_the_stt_sidecars_pass_the_sentinel_through_unchanged():
+ """`hf_token or None` before spawn_download makes the child-env scrub unreachable."""
+ from pathlib import Path as _Path
+
+ root = _Path(__file__).resolve().parent.parent / "core" / "inference"
+ for name in ("stt_sidecar.py", "stt_ggml_sidecar.py", "stt_mtmd_sidecar.py"):
+ source = (root / name).read_text()
+ assert "hf_token or None" not in source, (
+ f"{name} launders the sentinel into ambient access before the worker"
+ )
+
+
+def test_an_anonymous_caller_does_not_get_the_unauthenticated_preview_cache(monkeypatch):
+ """The disk fast path returns real rows without asking the Hub anything."""
+ from hub.services.datasets import formatting
+
+ called = {"cache": 0, "processed": 0}
+ monkeypatch.setattr(
+ formatting,
+ "_load_cached_hf_preview_slice",
+ lambda *_a, **_k: called.__setitem__("cache", called["cache"] + 1) or "ROWS",
+ )
+ # The processed path is the second disk read: it loads through
+ # DownloadConfig(local_files_only=True) and drops the sentinel, so it never authorizes.
+ monkeypatch.setattr(
+ formatting,
+ "_load_processed_hf_preview_slice",
+ lambda *_a, **_k: (
+ called.__setitem__("processed", called["processed"] + 1) or "PROCESSED_ROWS"
+ ),
+ )
+ request = SimpleNamespace(
+ dataset_name = "org/private", local_path = None, subset = None, train_split = "train"
+ )
+
+ assert formatting._load_any_cached_hf_preview_slice(request, 5, None) == "ROWS"
+ assert called["cache"] == 1
+
+ assert formatting._load_any_cached_hf_preview_slice(request, 5, False) is None
+ assert called["cache"] == 1, "the anonymous caller reached the unauthenticated cache"
+ assert called["processed"] == 0, "the anonymous caller reached the processed cache"
+
+
+def test_an_anonymous_caller_does_not_read_a_cached_chat_template(monkeypatch):
+ """The snapshot walk returns a private repo's raw template with no Hub call."""
+ from picker import service as picker_service
+
+ walked = {"n": 0}
+
+ def _snapshots(*_a, **_k):
+ walked["n"] += 1
+ return [Path("/nonexistent-snapshot")]
+
+ monkeypatch.setattr(picker_service, "iter_snapshots_preferring_whole", _snapshots)
+ monkeypatch.setattr(picker_service, "_chat_template_from_dir", lambda *_a, **_k: "TEMPLATE")
+
+ assert picker_service.read_default_chat_template("org/private", None) == "TEMPLATE"
+ assert walked["n"] == 1
+
+ picker_service.read_default_chat_template("org/private", False)
+ assert walked["n"] == 1, "the anonymous caller walked the cached snapshots"
+
+
[email protected]("hf_token", [None, "hf_tok"])
+def test_the_config_inspection_target_still_uses_the_cache_for_the_ambient_caller(hf_token):
+ """A caller allowed the ambient credential keeps the prefer_local_cache fast path.
+
+ With no snapshot on disk the resolver raises its own 404; reaching that proves the
+ cache branch ran rather than short-circuiting back to the bare repo id.
+ """
+ import fastapi
+ with pytest.raises(fastapi.HTTPException):
+ models_routes._model_config_inspection_target("org/private", True, None, hf_token)
+
+
+def test_the_config_inspection_target_skips_the_cache_for_anonymous():
+ """The snapshot read returns private metadata without consulting the token."""
+ target = models_routes._model_config_inspection_target("org/private", True, None, False)
+
+ assert target == "org/private", "the anonymous caller was pointed at the cache"
+
+
+def test_resolving_the_hub_token_never_returns_an_unresolved_dependency():
+ """Callers that invoke the route function directly leave a ``Depends`` in the slot.
+
+ The backend's own tests do exactly that, so returning ``header_token`` unchanged put
+ a ``Depends`` object into the cache fingerprint and 500ed the whole variants route.
+ """
+ from fastapi import Depends
+
+ unresolved = Depends(lambda: None)
+
+ resolved = models_routes._resolve_hub_token(unresolved, None)
+
+ assert resolved is None, "an unresolved dependency reached the Hub call"
+
+
+def test_resolving_the_hub_token_keeps_the_anonymous_sentinel():
+ """Rebuilding the sentinel must not quietly restore ambient access."""
+ assert models_routes._resolve_hub_token(False, None) is False
+ assert models_routes._resolve_hub_token(False, " ") is False
+ assert models_routes._resolve_hub_token(None, None) is None
+ assert models_routes._resolve_hub_token(False, "hf_query") == "hf_query"
+ assert models_routes._resolve_hub_token("hf_header", "hf_query") == "hf_header"
+
+
+def test_an_anonymous_caller_gets_no_template_from_the_offline_fallback(monkeypatch):
+ """Offline, hf_hub_download answers from disk and never checks the credential.
+
+ The chat-template route forces offline whenever the Hub looks unreachable, so
+ without this the Hub fallback hands back the template the cache walk just refused.
+ """
+ from picker import service as picker_service
+
+ monkeypatch.setattr(picker_service, "hf_env_offline", lambda: True)
+ monkeypatch.setattr(picker_service, "resolve_cached_repo_id_case", lambda name: name)
+
+ def _exploded(*args, **kwargs):
+ raise AssertionError("the anonymous caller reached the hub fallback")
+
+ monkeypatch.setattr(picker_service, "iter_snapshots_preferring_whole", _exploded)
+
+ assert picker_service.read_default_chat_template("org/private", False) is None
+
+
+def test_an_anonymous_config_read_does_not_strip_the_process_credential(monkeypatch):
+ """The sentinel goes to the hub as `token=False`, not via without_hf_auth().
+
+ That context deletes HF_TOKEN and moves the login token files process-wide, so a
+ concurrent download in another worker thread would lose the operator's credential.
+ """
+ import utils.models.model_config as model_config_module
+
+ monkeypatch.setenv("HF_TOKEN", "ambient-operator-token")
+ seen = {}
+
+ class _Config:
+ pass
+
+ def _from_pretrained(model_name, **kwargs):
+ seen["token"] = kwargs.get("token", "<absent>")
+ seen["ambient"] = os.environ.get("HF_TOKEN")
+ return _Config()
+
+ import transformers
+
+ monkeypatch.setattr(transformers.AutoConfig, "from_pretrained", staticmethod(_from_pretrained))
+ monkeypatch.setattr(model_config_module, "active_hf_hub_cache", lambda: None, raising = False)
+
+ model_config_module.load_model_config("org/private", token = False)
+
+ assert seen["token"] is False, "the sentinel was not passed through to the hub"
+ assert seen["ambient"] == "ambient-operator-token", (
+ "the anonymous probe removed a credential another thread was still using"
+ )
+
+
+ "hf_token, expected_local_only",
+ [(None, True), ("hf_tok", True), (False, False)],
+)
+def test_the_config_probes_do_not_go_local_only_for_an_anonymous_caller(
+ monkeypatch, hf_token, expected_local_only
+):
+ """local_files_only resolves config.json out of the cache without any authorization.
+
+ Sending the anonymous caller back to the bare repo id only helps if the probe then
+ goes over the wire, where `token=False` is refused for a private repo.
+ """
+ seen = {}
+
+ def _is_vision(
+ target,
+ hf_token = None,
+ local_files_only = False,
+ **kwargs,
+ ):
+ seen["local_files_only"] = local_files_only
+ return False
+
+ monkeypatch.setattr(models_routes, "is_vision_model", _is_vision)
+ monkeypatch.setattr(models_routes, "is_embedding_model", lambda *_a, **_k: False)
+ monkeypatch.setattr(models_routes, "load_model_defaults", lambda *_a, **_k: {}, raising = False)
+ monkeypatch.setattr(models_routes, "resolve_cached_repo_id_case", lambda name: name)
+ monkeypatch.setattr(
+ models_routes,
+ "_model_config_inspection_target",
+ lambda *_a, **_k: "org/private",
+ )
+
+ import asyncio
+
+ try:
+ asyncio.run(
+ models_routes.get_model_config(
+ "org/private",
+ hf_token = None,
+ prefer_local_cache = True,
+ local_path = None,
+ header_hf_token = hf_token if isinstance(hf_token, str) else None,
+ allow_ambient_token = hf_token is not False,
+ current_subject = "tester",
+ )
+ )
+ except Exception:
+ # The handler continues past the probe into machinery this test does not stand up;
+ # the probe argument is what is being pinned.
+ pass
+
+ assert seen.get("local_files_only") is expected_local_only
+
+
+def test_offline_embedding_detection_does_not_read_the_cache_anonymously(monkeypatch):
+ """The marker read answers for a private repo without ever authorizing."""
+ import utils.models.model_config as model_config_module
+
+ monkeypatch.setattr(model_config_module, "is_local_path", lambda _n: False)
+ monkeypatch.setattr("utils.utils.hf_env_offline", lambda: True, raising = False)
+
+ def _marker(_name):
+ raise AssertionError("the anonymous caller read the embedding cache marker")
+
+ monkeypatch.setattr(model_config_module, "_embedding_marker_in_hf_cache", _marker)
+
+ assert model_config_module.is_embedding_model("org/private", hf_token = False) is False
+
+
[email protected]("hf_token", [None, "hf_tok", False])
+def test_gguf_variants_serve_the_hf_cache_only_to_an_authorized_caller(monkeypatch, hf_token):
+ """prefer_local_cache answers off disk with the credential never consulted.
+
+ The listing carries variant filenames, sizes and the vision flag, so a caller denied
+ the ambient token could name a private repo the UI had cached and read it back.
+ """
+ import asyncio
+
+ from hub.services.models import gguf_variants
+
+ reads = {"snapshot": 0, "state": 0}
+
+ def _snapshot(*_a, **_k):
+ reads["snapshot"] += 1
+ return None
+
+ def _state(*_a, **_k):
+ reads["state"] += 1
+ return None
+
+ monkeypatch.setattr(gguf_variants, "select_gguf_cache_snapshot", _snapshot)
+ monkeypatch.setattr(gguf_variants, "_quants_from_state", _state)
+
+ try:
+ asyncio.run(
+ gguf_variants.get_gguf_variants_answer(
+ "org/private",
+ prefer_local_cache = True,
+ offline = True,
+ local_path = None,
+ hf_token = hf_token,
+ )
+ )
+ except Exception:
+ # Offline with nothing cached is a 404 either way; the reads are the point.
+ pass
+
+ if is_anonymous(hf_token):
+ assert reads == {
+ "snapshot": 0,
+ "state": 0,
+ }, "the anonymous caller was served from the hub cache"
+ else:
+ assert reads["snapshot"] > 0, "the authorized caller lost its cache fast path"
+
+
[email protected]("hf_token", [None, "hf_tok", False])
+def test_offline_capability_probes_do_not_read_the_cache_anonymously(monkeypatch, hf_token):
+ """Offline, is_vision_model derives local_files_only from the environment.
+
+ So passing local_files_only=False does not put the anonymous caller back on the wire:
+ the probe reads the cached config.json off disk and never authorizes.
+ """
+ import utils.models.model_config as model_config_module
+
+ monkeypatch.setattr(model_config_module, "_env_offline", lambda: True)
+ reached = {"vision": 0, "audio": 0}
+
+ def _vision(*_a, **_k):
+ reached["vision"] += 1
+ return True
+
+ def _audio(*_a, **_k):
+ reached["audio"] += 1
+ return "stt", True
+
+ monkeypatch.setattr(model_config_module, "_is_vision_model_uncached", _vision)
+ monkeypatch.setattr(model_config_module, "_detect_audio_type_uncached", _audio, raising = False)
+ # A fresh probe every time, so a warm entry cannot stand in for the guard.
+ monkeypatch.setattr(model_config_module, "_vision_detection_cache", {})
+ monkeypatch.setattr(model_config_module, "_audio_detection_cache", {})
+ monkeypatch.setattr(model_config_module, "_audio_offline_miss_cache", {})
+
+ is_vision = model_config_module.is_vision_model(
+ "org/private", hf_token = hf_token, local_files_only = False
+ )
+
+ if is_anonymous(hf_token):
+ assert is_vision is False
+ assert reached["vision"] == 0, "the anonymous caller probed the offline cache"
+ else:
+ assert reached["vision"] == 1, "the authorized caller lost its offline probe"
+
+
[email protected]("hf_token", [None, "hf_tok", False])
+def test_the_config_json_fallbacks_do_not_reach_the_cache_anonymously(monkeypatch, hf_token):
+ """Keying the memo apart is not enough when the value came off disk to begin with."""
+ import utils.transformers_version as tv
+
+ monkeypatch.setattr(tv, "_env_offline", lambda: True)
+ monkeypatch.setattr(tv, "_safe_is_file", lambda _p: False)
+ monkeypatch.setattr(tv, "_safe_is_dir", lambda _p: False)
+ monkeypatch.setattr(tv, "_config_json_cache", {})
+ reads = {"n": 0}
+
+ def _from_cache(_name):
+ reads["n"] += 1
+ return {"max_position_embeddings": 4096}
+
+ monkeypatch.setattr(tv, "_config_json_from_hf_cache", _from_cache)
+
+ cfg = tv._load_config_json("org/private", hf_token = hf_token)
+
+ if is_anonymous(hf_token):
+ assert cfg is None
+ assert reads["n"] == 0, "the anonymous caller read the offline config cache"
+ else:
+ assert cfg == {"max_position_embeddings": 4096}
+
+
+def test_a_cache_only_gguf_listing_is_refused_for_an_anonymous_caller(monkeypatch):
+ """siblings is None means the lister already answered from its own cache.
+
+ Declining to build a second cached response is not enough: falling through would
+ serialize the first one.
+ """
+ import asyncio
+
+ import fastapi
+
+ from hub.services.models import gguf_variants
+
+ monkeypatch.setattr(
+ gguf_variants,
+ "list_gguf_variants",
+ lambda *_a, **_k: ([SimpleNamespace(filename = "m-Q4.gguf")], False, None),
+ )
+ monkeypatch.setattr(gguf_variants, "select_gguf_cache_snapshot", lambda *_a, **_k: None)
+ monkeypatch.setattr(gguf_variants, "_quants_from_state", lambda *_a, **_k: None)
+
+ with pytest.raises(fastapi.HTTPException) as excinfo:
+ asyncio.run(gguf_variants.get_gguf_variants_answer("org/private", hf_token = False))
+
+ assert excinfo.value.status_code == 404
+
+
+def test_the_scan_route_derives_its_caller_rather_than_trusting_an_absent_body_token():
+ """An absent body token must not read as ambient-authorized."""
+ import inspect
+
+ signature = inspect.signature(models_routes.scan_model_remote_code)
+
+ assert "allow_ambient_token" in signature.parameters, (
+ "the scan route cannot tell an api key from a ui session"
+ )
+ source = inspect.getsource(models_routes.scan_model_remote_code)
+ assert "hf_token_arg(hf_token" in source, (
+ "the body token reaches the cache-backed scan target unresolved"
+ )
+
+
+def test_an_anonymous_seed_preview_is_refused_while_offline(monkeypatch):
+ """Offline, `datasets` satisfies a streaming load from its own cache.
+
+ The sentinel never reaches an authorization check there, so a previously cached
+ private dataset would come back as rows.
+ """
+ import asyncio
+
+ import fastapi
+
+ from routes.data_recipe import seed as seed_routes
+
+ monkeypatch.setattr(seed_routes, "hf_env_offline", lambda: True)
+
+ def _never(*_a, **_k):
+ raise AssertionError("the anonymous caller reached the dataset load")
+
+ monkeypatch.setattr(seed_routes, "_list_hf_data_files", _never)
+
+ payload = SimpleNamespace(
+ dataset_name = "org/private",
+ split = None,
+ subset = None,
+ hf_token = None,
+ preview_size = 5,
+ )
+
+ with pytest.raises(fastapi.HTTPException) as excinfo:
+ asyncio.run(seed_routes.inspect_seed_dataset(payload, allow_ambient_token = False))
+
+ assert excinfo.value.status_code == 404
+
+
[email protected]("hf_token", [None, "hf_tok", False])
+def test_the_lora_resolver_does_not_launder_the_sentinel(monkeypatch, hf_token):
+ """`hf_token if hf_token else None` turned the sentinel back into ambient access."""
+ import utils.models.model_config as model_config_module
+
+ seen = {}
+
+ def _absent(
+ _identifier,
+ _filename,
+ token = None,
+ ):
+ seen["token"] = token
+ return True
+
+ monkeypatch.setattr("utils.hf_probe.hf_file_definitely_absent", _absent, raising = False)
+
+ model_config_module.get_base_model_from_lora_identifier(
+ "org/private-adapter", hf_token = hf_token
+ )
+
+ if is_anonymous(hf_token):
+ assert seen["token"] is False, "the scan pipeline restored the ambient token"
+ else:
+ assert seen["token"] == (hf_token or None)
+
+
[email protected]("hf_token", [None, "hf_tok", False])
+def test_the_audio_tokenizer_probe_does_not_read_the_cache_anonymously(monkeypatch, hf_token):
+ """The cache root is walked before any network branch, online as well as offline."""
+ import utils.models.model_config as model_config_module
+
+ reads = {"n": 0}
+
+ def _cache_path(_name):
+ reads["n"] += 1
+ return None
+
+ monkeypatch.setattr(model_config_module, "get_cache_path", _cache_path)
+ monkeypatch.setattr(model_config_module, "is_local_path", lambda _n: False)
+
+ try:
+ model_config_module._detect_audio_from_tokenizer("org/private", hf_token = hf_token)
+ except Exception:
+ pass
+
+ if is_anonymous(hf_token):
+ assert reads["n"] == 0, "the anonymous caller walked the hub cache"
+ else:
+ assert reads["n"] > 0, "the authorized caller lost its cache fast path"
+
+
+def test_the_embedding_transient_fallback_is_denied_to_an_anonymous_caller(monkeypatch):
+ """The anonymous 404 for a private repo lands in the same except branch."""
+ import utils.models.model_config as model_config_module
+
+ monkeypatch.setattr(model_config_module, "is_local_path", lambda _n: False)
+ monkeypatch.setattr("utils.utils.hf_env_offline", lambda: False, raising = False)
+ monkeypatch.setattr(model_config_module, "_embedding_detection_cache", {})
+
+ def _boom(*_a, **_k):
+ raise RuntimeError("404")
+
+ monkeypatch.setattr(model_config_module, "model_info", _boom, raising = False)
+
+ def _marker(_name):
+ raise AssertionError("the anonymous caller read the embedding cache marker")
+
+ monkeypatch.setattr(model_config_module, "_embedding_marker_in_hf_cache", _marker)
+
+ assert model_config_module.is_embedding_model("org/private", hf_token = False) is False
+
+
+def test_a_public_model_keeps_its_size_when_the_cache_is_bypassed():
+ """The anonymous short-circuit returns the bare repo id, which is not a path.
+
+ Sizing it as one returns None, so public models lost model_size_bytes entirely.
+ """
+ import inspect
+
+ source = inspect.getsource(models_routes.get_model_config)
+
+ assert "inspection_target != model_name" in source, (
+ "snapshot sizing is still chosen from the flag rather than the target"
+ )
+
+
[email protected]("hf_token", [None, "hf_tok", False])
+def test_the_offline_autoconfig_read_is_denied_to_an_anonymous_caller(monkeypatch, hf_token):
+ """token=False disables authentication but not the local cache."""
+ import transformers
+
+ import utils.models.model_config as model_config_module
+
+ monkeypatch.setattr(model_config_module, "_env_offline", lambda: True)
+ monkeypatch.setattr(model_config_module, "active_hf_hub_cache", lambda: None, raising = False)
+ reached = {"n": 0}
+
+ def _from_pretrained(_name, **_kwargs):
+ reached["n"] += 1
+ return object()
+
+ monkeypatch.setattr(transformers.AutoConfig, "from_pretrained", staticmethod(_from_pretrained))
+
+ if is_anonymous(hf_token):
+ with pytest.raises(OSError):
+ model_config_module.load_model_config("org/private", token = hf_token)
+ assert reached["n"] == 0, "the anonymous caller read the offline config cache"
+ else:
+ model_config_module.load_model_config("org/private", token = hf_token)
+ assert reached["n"] == 1
+
+
+def test_the_prefer_local_scan_branch_carries_the_anonymous_guard():
+ """Only the exact-snapshot branch was gated; the sibling resolved the cache anyway."""
+ import inspect
+
+ source = inspect.getsource(models_routes.scan_model_remote_code)
+ marker = source.index("elif prefer_local_cache is True")
+ branch = source[marker : marker + 200]
+
+ assert "not is_anonymous(hf_token)" in branch, (
+ "the prefer-local scan branch still resolves a cached snapshot for any caller"
+ )
+
+
+ "hf_token, offline, denied",
+ [
+ (False, True, True),
+ (False, False, False),
+ (None, True, False),
+ ("hf_tok", True, False),
+ ],
+)
+def test_the_offline_anonymous_rule_is_stated_once(hf_token, offline, denied, monkeypatch):
+ """One precondition, not one guard per reader.
+
+ Six separate readers were fixed in turn -- the snapshot walk, the config probes, the
+ embedding marker, the GGUF listing, the preview slices, AutoConfig -- and each fix
+ only moved the boundary to the next one. This pins the shared rule itself.
+ """
+ import utils.utils as utils_module
+
+ monkeypatch.setattr(utils_module, "hf_env_offline", lambda: offline)
+
+ assert utils_module.anonymous_and_offline(hf_token) is denied
+
+
+def test_every_offline_reachable_route_refuses_before_it_reads(monkeypatch):
+ """The three routes that reach disk offline all consult the shared rule."""
+ import inspect
+
+ from hub.services.datasets import formatting
+
+ for owner, name in (
+ (models_routes.get_model_config, "/config"),
+ (models_routes.scan_model_remote_code, "scan-remote-code"),
+ (formatting.check_format_response, "check-format"),
+ ):
+ source = inspect.getsource(owner)
+ assert "anonymous_and_offline" in source, (
+ f"{name} can still be answered from disk for a denied caller"
+ )
diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.py
index e25853ce588..a1ecbe69059 100644
--- a/studio/backend/utils/models/model_config.py
+++ b/studio/backend/utils/models/model_config.py
@@ -16,6 +16,13 @@ from utils.paths import (
resolve_output_dir,
resolve_export_dir,
)
+from hub.utils.hf_tokens import (
+ ANONYMOUS_CACHE_IDENTITY,
+ HfTokenArg,
+ apply_token_to_child_env,
+ is_anonymous,
+ normalize_token,
+)
from utils.utils import without_hf_auth
from utils.training_runs import (
base_model_from_run_dir_name as _base_model_from_dir_name,
@@ -546,6 +553,25 @@ def load_model_config(
revision_kwargs = {"revision": revision} if revision is not None else {}
+ if is_anonymous(token):
+ # `False` is falsy: without this it falls past both branches to the ambient call.
+ # Passed as the sentinel rather than via without_hf_auth(), which mutates HF_TOKEN
+ # process-wide and would strip a concurrent download's credential.
+ # token=False denies auth, not the cache, so offline it would read a cached private
+ # config.json anyway; with no network this caller gets nothing instead.
+ if local_files_only or _env_offline():
+ raise OSError(
+ f"config.json for {model_name} is not available to an unauthorized caller"
+ )
+ return AutoConfig.from_pretrained(
+ model_name,
+ trust_remote_code = trust_remote_code,
+ token = False,
+ local_files_only = local_files_only,
+ cache_dir = active_hf_hub_cache(),
+ **revision_kwargs,
+ )
+
if token:
return AutoConfig.from_pretrained(
model_name,
@@ -874,6 +900,13 @@ def __getattr__(name: str) -> Any:
return _lazy_module_attr(name)
+def _vision_check_child_env(hf_token: HfTokenArg) -> Dict[str, str]:
+ """Child environment for the vision-check probe, carrying the caller's credential."""
+ env = utf8_child_env(get_hf_cache_paths().child_env(child_env_without_native_path_secret()))
+ apply_token_to_child_env(env, hf_token)
+ return env
+
+
def _is_vision_model_subprocess(
model_name: str,
hf_token: Optional[str] = None,
@@ -886,7 +919,8 @@ def _is_vision_model_subprocess(
or None for transient failures (timeouts, subprocess errors), which are not
cached so they can be retried.
"""
- token_arg = hf_token or ""
+ # Only an explicit token travels in argv; the env below enforces the boundary.
+ token_arg = hf_token if isinstance(hf_token, str) else ""
# Latest-only architectures need the latest sidecar for AutoConfig; other tiers keep 5.5.
sidecar_dir = _VENV_T5_DIR
@@ -916,9 +950,7 @@ def _is_vision_model_subprocess(
encoding = "utf-8",
errors = "replace",
timeout = 60,
- env = utf8_child_env(
- get_hf_cache_paths().child_env(child_env_without_native_path_secret())
- ),
+ env = _vision_check_child_env(hf_token),
**_windows_hidden_subprocess_kwargs(),
)
@@ -959,9 +991,14 @@ def _is_vision_model_subprocess(
return None
-def _token_fingerprint(token: Optional[str]) -> Optional[str]:
- """SHA256 digest of the token for use as a cache key (avoids storing the
- raw bearer token in process memory)."""
+def _token_fingerprint(token: HfTokenArg) -> Optional[str]:
+ """SHA256 digest of the token as a cache key (never the raw bearer in memory).
+
+ The sentinel takes its own identity: sharing ``None``'s slot would serve a caller
+ denied the ambient token a result fetched with it.
+ """
+ if is_anonymous(token):
+ return ANONYMOUS_CACHE_IDENTITY
if token is None:
return None
return hashlib.sha256(token.encode("utf-8")).hexdigest()
@@ -1031,6 +1068,10 @@ def is_vision_model(
resolved_name = model_name
# Key on effective offline (kwarg OR env) so an offline probe can't poison a later lookup.
effective_offline = bool(local_files_only or _env_offline())
+ # Offline the probe reads the cache and never authorizes, so local_files_only=False
+ # does not put an anonymous caller back on the wire. It gets the default instead.
+ if effective_offline and is_anonymous(hf_token) and not is_local_path(model_name):
+ return False
cache_key: _CapabilityCacheKey = (
resolved_name,
_token_fingerprint(hf_token),
@@ -1220,6 +1261,10 @@ def detect_audio_type_checked(
# Key on effective offline (kwarg OR env) so an offline negative can't poison a later probe.
effective_offline = bool(local_files_only or _env_offline())
+ # Offline the probe reads the cache and never authorizes, so local_files_only=False
+ # does not put an anonymous caller back on the wire. Inconclusive for it instead.
+ if effective_offline and is_anonymous(hf_token) and not is_local_path(model_name):
+ return None, False
# Checked on the RAW name, before the casing resolution below, because resolving a
# repo id that is not in the cache walks every cache directory, and that walk is the
# cost this cache exists to avoid. A casing variant just takes its own entry, which
@@ -1343,7 +1388,9 @@ def _detect_audio_from_tokenizer(
if local_path.is_dir():
roots.append(local_path)
else:
- repo_dir = get_cache_path(model_name)
+ # Read before any network branch and never authorizes, so it would serve a
+ # cached private repo's audio tokens online as well as offline.
+ repo_dir = None if is_anonymous(hf_token) else get_cache_path(model_name)
if repo_dir is not None and repo_dir.is_dir():
snapshots_dir = repo_dir / "snapshots"
if snapshots_dir.is_dir() and revision is None:
@@ -1404,7 +1451,8 @@ def _detect_audio_from_tokenizer(
except Exception:
return None, read_any
- token = hf_token or os.environ.get("HF_TOKEN")
+ # `False` is falsy, so `or` would reach past it to the ambient credential.
+ token = None if is_anonymous(hf_token) else (hf_token or os.environ.get("HF_TOKEN"))
headers = {"Authorization": f"Bearer {token}"} if token else {}
transient = False # a fetch failed for a non-404 reason (network/5xx)
@@ -3096,6 +3144,10 @@ def is_embedding_model(model_name: str, hf_token: Optional[str] = None) -> bool:
# online lookup can memoize True from tags with no weights cached, and a cached negative can
# be invalidated by later materialization. The cache probe is local-only, so it's cheap.
if not is_local_path(model_name) and hf_env_offline():
+ # The marker is read off the HF cache and never authorizes. Offline this caller
+ # cannot establish access, so it reports the default rather than the cache.
+ if is_anonymous(hf_token):
+ return False
return _embedding_marker_in_hf_cache(model_name)
cache_key = (model_name, hf_token)
@@ -3135,6 +3187,9 @@ def is_embedding_model(model_name: str, hf_token: Optional[str] = None) -> bool:
except Exception as e:
# Timeout or transient network error: fall back to the local cache marker, don't hard-fail.
logger.warning(f"Could not determine if {model_name} is embedding model: {e}")
+ if is_anonymous(hf_token):
+ # The anonymous 404 lands here too, and the marker read never authorizes.
+ return False
is_emb = _embedding_marker_in_hf_cache(model_name)
_embedding_detection_cache[cache_key] = is_emb
return is_emb
@@ -3470,7 +3525,7 @@ def get_base_model_from_lora_identifier(
if hf_file_definitely_absent(
identifier,
"adapter_config.json",
- token = hf_token if hf_token else None,
+ token = normalize_token(hf_token),
):
return None
@@ -3480,7 +3535,7 @@ def get_base_model_from_lora_identifier(
cfg_path = hf_hub_download(
identifier,
"adapter_config.json",
- token = hf_token if hf_token else None,
+ token = normalize_token(hf_token),
cache_dir = active_hf_hub_cache(),
)
except (EntryNotFoundError, RepositoryNotFoundError):
diff --git a/studio/backend/utils/transformers_version.py b/studio/backend/utils/transformers_version.py
index 4b3358b6fa0..21ee684e750 100644
--- a/studio/backend/utils/transformers_version.py
+++ b/studio/backend/utils/transformers_version.py
@@ -45,6 +45,12 @@ import threading
import time
from pathlib import Path
+from hub.utils.hf_tokens import (
+ ANONYMOUS_CACHE_IDENTITY,
+ HfTokenArg,
+ apply_token_to_child_env,
+ is_anonymous,
+)
from utils.native_path_leases import child_env_without_native_path_secret
from utils.native_tls import inline_gate_source, vendor_dir
from utils.child_stdio import utf8_child_env
@@ -665,11 +671,16 @@ def _resolve_base_model(model_name: str) -> str:
return model_name
-def _token_cache_key(model_name: str, hf_token: str | None) -> tuple[str, str | None]:
+def _token_cache_key(model_name: str, hf_token: HfTokenArg) -> tuple[str, str | None]:
"""Cache key that keeps authenticated and unauthenticated reads separate, so an
- unauthenticated miss on a gated/private repo never poisons a later authed lookup."""
+ unauthenticated miss on a gated/private repo never poisons a later authed lookup.
+
+ Forced-anonymous is its own credential, so it takes its own slot too.
+ """
import hashlib
+ if is_anonymous(hf_token):
+ return (model_name, ANONYMOUS_CACHE_IDENTITY)
tok = hashlib.sha256(hf_token.encode()).hexdigest()[:16] if hf_token else None
return (model_name, tok)
@@ -890,10 +901,7 @@ def _load_config_json(model_name: str, hf_token: str | None = None) -> dict | No
authenticated read. The HF hub cache is consulted only offline or after a failed
network fetch, so an online read never serves stale metadata.
"""
- import hashlib
-
- tok = hashlib.sha256(hf_token.encode()).hexdigest()[:16] if hf_token else None
- cache_key = (model_name, tok)
+ cache_key = _token_cache_key(model_name, hf_token)
if cache_key in _config_json_cache:
return _config_json_cache[cache_key]
@@ -913,9 +921,19 @@ def _load_config_json(model_name: str, hf_token: str | None = None) -> dict | No
if _safe_is_dir(Path(model_name)):
return None
+ # Every route to the hub cache below reads it without authorizing, so a caller denied
+ # the ambient credential is refused them all: keying the memo apart is not enough when
+ # the value it memoizes came off disk in the first place.
+ if is_anonymous(hf_token):
+ cache_denied = True
+ else:
+ cache_denied = False
+
if _env_offline():
# No network: a downloaded repo can still tier from the hub cache. Cache a real hit,
# never the miss, so a later online read still fetches the config.
+ if cache_denied:
+ return None
cfg = _config_json_from_hf_cache(model_name)
if cfg is not None:
_config_json_cache[cache_key] = cfg
@@ -940,11 +958,11 @@ def _load_config_json(model_name: str, hf_token: str | None = None) -> dict | No
logger.debug("config.json access denied for '%s': %s", model_name, exc)
return None
logger.debug("Could not fetch config.json for '%s': %s", model_name, exc)
- return _config_json_from_hf_cache(model_name)
+ return None if cache_denied else _config_json_from_hf_cache(model_name)
except Exception as exc:
logger.debug("Could not fetch config.json for '%s': %s", model_name, exc)
# Transient: serve the hub cache uncached so the next call retries the network.
- return _config_json_from_hf_cache(model_name)
+ return None if cache_denied else _config_json_from_hf_cache(model_name)
def _config_json_is_definitive(model_name: str, hf_token: str | None = None) -> bool:
@@ -1504,11 +1522,8 @@ def _probe_autoconfig(target_dir: str, model_name: str, hf_token: str | None) ->
(auth/network/offline/spawn) so the caller fails safe and does not cache.
"""
env = get_hf_cache_paths().child_env(child_env_without_native_path_secret())
- if hf_token:
- env["HF_TOKEN"] = hf_token
- # The probe relies on the implicit HF_TOKEN env; clear any inherited
- # HF_HUB_DISABLE_IMPLICIT_TOKEN=1 so a gated repo authenticates instead of 401ing.
- env["HF_HUB_DISABLE_IMPLICIT_TOKEN"] = "0"
+ # The probe reads the implicit HF_TOKEN env, so grant or scrub here, not via argv.
+ apply_token_to_child_env(env, hf_token)
if _env_offline():
env["HF_HUB_OFFLINE"] = "1"
env["TRANSFORMERS_OFFLINE"] = "1"
diff --git a/studio/backend/utils/utils.py b/studio/backend/utils/utils.py
index af374f193de..318c65774b2 100644
--- a/studio/backend/utils/utils.py
+++ b/studio/backend/utils/utils.py
@@ -40,6 +40,25 @@ def hf_env_offline() -> bool:
return False
+
+def anonymous_and_offline(hf_token) -> bool:
+ """The one condition under which a Hub-reaching request can only be answered by disk.
+
+ ``token=False`` denies authentication, not the cache: offline, huggingface_hub and
+ datasets both resolve a previously downloaded private repo without ever authorizing.
+ A caller holding the anonymous sentinel has no network to establish access over, so
+ every downstream read is a disk read it never earned.
+
+ Guarding this at the route entry rather than at each call site is deliberate. The
+ per-site version was fixed six times -- the snapshot walk, the config probes, the
+ embedding marker, the GGUF listing, the preview slices, AutoConfig -- and each fix
+ only moved the boundary to the next reader. This states the rule once, before any of
+ them run, so a path nobody has enumerated is covered too.
+ """
+ from hub.utils.hf_tokens import is_anonymous
+
+ return is_anonymous(hf_token) and hf_env_offline()
+
def canonical_model_repo_id(model_name: str) -> str:
"""Normalize a Hugging Face model repository ID selected in Unsloth."""
return model_name.strip()
diff --git a/studio/frontend/src/features/chat/api/chat-api.ts b/studio/frontend/src/features/chat/api/chat-api.ts
index c5b61c45ead..7f6956af277 100644
--- a/studio/frontend/src/features/chat/api/chat-api.ts
+++ b/studio/frontend/src/features/chat/api/chat-api.ts
@@ -519,6 +519,7 @@ export async function getGgufDownloadProgress(
repoId: string,
variant: string,
expectedBytes: number,
+ hfToken?: string | null,
): Promise<{
downloaded_bytes: number;
expected_bytes: number;
@@ -531,6 +532,7 @@ export async function getGgufDownloadProgress(
});
const response = await authFetch(
`/api/models/gguf-download-progress?${params}`,
+ { headers: hubTokenHeader(hfToken) },
);
return parseJsonOrThrow(response);
}
@@ -555,18 +557,23 @@ export interface DownloadProgressResponse {
export async function getDownloadProgress(
repoId: string,
+ hfToken?: string | null,
): Promise<DownloadProgressResponse> {
const params = new URLSearchParams({ repo_id: repoId });
- const response = await authFetch(`/api/models/download-progress?${params}`);
+ const response = await authFetch(`/api/models/download-progress?${params}`, {
+ headers: hubTokenHeader(hfToken),
+ });
return parseJsonOrThrow(response);
}
export async function getDatasetDownloadProgress(
repoId: string,
+ hfToken?: string | null,
): Promise<DownloadProgressResponse> {
const params = new URLSearchParams({ repo_id: repoId });
const response = await authFetch(
`/api/hub/datasets/download-progress?${params}`,
+ { headers: hubTokenHeader(hfToken) },
);
return parseJsonOrThrow(response);
}
diff --git a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
index 850ce3923cc..496d19fb216 100644
--- a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
+++ b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
@@ -32,7 +32,10 @@ import {
} from "@/features/transformers-upgrade";
import { consumeNativePathToken } from "@/features/native-intents/api";
// eslint-disable-next-line no-restricted-imports -- Avoid the hub barrel's React and download-manager exports.
-import { modelDisplayName } from "@/features/hub/lib/model-identity";
+import {
+ isOllamaLinkPath,
+ modelDisplayName,
+} from "@/features/hub/lib/model-identity";
// eslint-disable-next-line no-restricted-imports -- Avoid the hub barrel's React and download-manager exports.
import { subscribeResidentStatusRefresh } from "@/features/hub/lib/resident-status-refresh";
// eslint-disable-next-line no-restricted-imports -- The hub barrel imports chat; this lifecycle leaf does not.
@@ -1160,10 +1163,29 @@ export function useChatModelRuntime() {
loadingModelRef.current = loadInfo;
const abortCtrl = new AbortController();
loadAbortRef.current = abortCtrl;
+ let hfToken = useChatRuntimeStore.getState().hfToken || null;
const postLoadRefresh = { needed: false };
let cpuFallbackReason: CpuFallbackReason | null = null;
let mmprojFallbackReason: MmprojFallbackReason | null = null;
try {
+ // Hoisted out of performLoad's GGUF branch for the progress pollers, but kept off
+ // loads that never reach the Hub: it validates over the network and can block on a
+ // dialog, and a stale Settings token must not gate a local or cached-LoRA load.
+ // An Ollama row's id is an opaque `ollama-manifest:` reference rather than a
+ // path, so isLocalModelPath does not recognise it even though the backend
+ // materialises the load entirely from the local Ollama store.
+ const mayReachHub =
+ !isLocal && !isOllamaLinkPath(modelId) && nativePathToken == null;
+ if (mayReachHub) {
+ const preparedToken = await prepareHfTokenForUse(hfToken);
+ if (!preparedToken.proceed) {
+ // Lands in the outer catch (banner only); no load toast exists yet.
+ toast.error("Model load cancelled.");
+ throw new Error("Model load cancelled.");
+ }
+ hfToken = preparedToken.token;
+ }
+
async function performLoad(): Promise<void> {
if (abortCtrl.signal.aborted) throw new Error("Cancelled");
let previousWasUnloaded = false;
@@ -1204,17 +1226,11 @@ export function useChatModelRuntime() {
// header with 401 even for a public repo, so sending the raw stored
// token here would abort the load before the existing "continue
// anonymously / replace token" recovery flow could run.
- const preparedToken = await prepareHfTokenForUse(
- useChatRuntimeStore.getState().hfToken || null,
- );
- if (!preparedToken.proceed) {
- throw new Error("Model load cancelled.");
- }
isDiffusion = (
await fetchGgufStagedMetadata({
model_path: loadPath,
gguf_variant: ggufVariant ?? null,
- hf_token: preparedToken.token,
+ hf_token: hfToken,
nativePathToken: nativePathToken ?? null,
})
).isDiffusion;
@@ -1281,7 +1297,10 @@ export function useChatModelRuntime() {
)
: (previousPin ??
unpinnedLoadContext(false, previousIsMlx, previousMaxSeqLength));
- const hfToken = stateBeforeUnload.hfToken || null;
+ // main's `const hfToken = stateBeforeUnload.hfToken` is deliberately not
+ // carried over: this branch prepares the credential once in the enclosing
+ // scope, and re-reading the raw stored token here would shadow it and undo
+ // the preparation for every load below.
const previousModelRequiresTrustRemoteCode =
stateBeforeUnload.modelRequiresTrustRemoteCode;
const previousActiveNativePathExpiresAtMs =
@@ -2307,8 +2326,13 @@ export function useChatModelRuntime() {
try {
const prog =
ggufVariant && expectedBytes > 0
- ? await getGgufDownloadProgress(modelId, ggufVariant, expectedBytes)
- : await getDownloadProgress(modelId);
+ ? await getGgufDownloadProgress(
+ modelId,
+ ggufVariant,
+ expectedBytes,
+ hfToken,
+ )
+ : await getDownloadProgress(modelId, hfToken);
if (!loadingModelRef.current) return;
if (prog.progress > 0 && prog.progress < 1) {
diff --git a/studio/frontend/src/features/hf-auth/confirm-token.ts b/studio/frontend/src/features/hf-auth/confirm-token.ts
index 8bc650892f2..e90f370d3ed 100644
--- a/studio/frontend/src/features/hf-auth/confirm-token.ts
+++ b/studio/frontend/src/features/hf-auth/confirm-token.ts
@@ -3,6 +3,8 @@
// These stores are used outside React and are not part of their features' public barrels.
// eslint-disable-next-line no-restricted-imports
+import { AUTH_SESSION_CLEARED_EVENT } from "@/features/auth/session-events";
+// eslint-disable-next-line no-restricted-imports
import { useHfTokenStore } from "@/features/hub/stores/hf-token-store";
// eslint-disable-next-line no-restricted-imports
import { useSettingsDialogStore } from "@/features/settings/stores/settings-dialog-store";
@@ -22,10 +24,109 @@ interface PrepareHfTokenOptions {
// one-session choice so a follow-up /load does not prompt again after an anonymous /validate.
const anonymousForSession = new Set<string>();
+// One load prepares the same token three times (pollers, validateModel, loadModel), so a
+// burst collapses to one call rather than threading a prepared credential through every
+// signature. Short and positive-only: "invalid" is never cached, so the dialog still
+// appears and an expiring token is re-checked once the window lapses.
+const VALIDATION_REUSE_MS = 15_000;
+// Bumped on every clear, so an in-flight request cannot repopulate the cache afterwards.
+let cacheGeneration = 0;
+const recentlyValid = new Map<string, number>();
+const inFlight = new Map<string, Promise<HfTokenValidationResult>>();
+
+// Entries hold the raw bearer token, so they go as soon as they stop being useful.
+function dropExpiredValidations(now: number): void {
+ for (const [cached, validAt] of recentlyValid) {
+ if (now - validAt >= VALIDATION_REUSE_MS) {
+ recentlyValid.delete(cached);
+ }
+ }
+}
+
+function validateOncePerBurst(token: string): Promise<HfTokenValidationResult> {
+ const now = Date.now();
+ dropExpiredValidations(now);
+ const validAt = recentlyValid.get(token);
+ if (validAt != null && now - validAt < VALIDATION_REUSE_MS) {
+ return Promise.resolve({ status: "valid", retryAfterSeconds: null });
+ }
+ const pending = inFlight.get(token);
+ if (pending) {
+ return pending;
+ }
+ // Clearing cannot cancel an in-flight request, so a logout mid-validation would have
+ // the late resolution write the raw token back, and expiry only runs on the next
+ // preparation. The generation makes a stale resolution non-cacheable.
+ const generation = cacheGeneration;
+ const request = validateHfToken(token)
+ .then((result) => {
+ // Only a definitive pass is reusable: "unavailable" says nothing, and reusing it
+ // would suppress the dialog for a token that is genuinely bad.
+ if (result.status === "valid" && generation === cacheGeneration) {
+ recentlyValid.set(token, Date.now());
+ }
+ return result;
+ })
+ .finally(() => {
+ // Only if still ours: a forget-then-prepare can put a live replacement in this
+ // slot, and an unconditional delete would evict it.
+ if (inFlight.get(token) === request) {
+ inFlight.delete(token);
+ }
+ });
+ inFlight.set(token, request);
+ return request;
+}
+
+// Called with no argument the whole cache goes; with one, just that credential.
+export function forgetHfTokenValidation(token?: string): void {
+ cacheGeneration += 1;
+ if (token == null) {
+ recentlyValid.clear();
+ inFlight.clear();
+ return;
+ }
+ recentlyValid.delete(token);
+ inFlight.delete(token);
+}
+
+// A logout must not leave a bearer token in module memory, the same reason
+// hf-token-store.ts resets on this event. Replacing it drops the superseded key too.
+if (typeof window !== "undefined") {
+ window.addEventListener(AUTH_SESSION_CLEARED_EVENT, () => {
+ forgetHfTokenValidation();
+ // anonymousForSession is deliberately left alone: it predates this cache and records a
+ // user's choice rather than a Hub verdict.
+ });
+}
+
+let lastKnownStoredToken: string | null = null;
+let tokenChangeSubscribed = false;
+
+// Subscribed on first use, not at module scope: reading a barrel-imported value while
+// this module loads throws if the import cycle re-enters (module-scope-cycle-safety).
+function ensureTokenChangeSubscription(): void {
+ if (tokenChangeSubscribed || typeof useHfTokenStore.subscribe !== "function") {
+ return;
+ }
+ tokenChangeSubscribed = true;
+ // Seeded, not left null: zustand does not fire subscribe on install, so replacing an
+ // already-stored token would read as initialization and keep its window.
+ lastKnownStoredToken = useHfTokenStore.getState().token?.trim() ?? "";
+ useHfTokenStore.subscribe((state) => {
+ const next = state.token?.trim() ?? "";
+ if (lastKnownStoredToken != null && lastKnownStoredToken !== next) {
+ forgetHfTokenValidation(lastKnownStoredToken);
+ }
+ lastKnownStoredToken = next;
+ });
+}
+
export async function prepareHfTokenForUse(
token: string | null | undefined,
options: PrepareHfTokenOptions = {},
): Promise<PreparedHfToken> {
+ ensureTokenChangeSubscription();
const normalized = token?.trim() ?? "";
if (!normalized) {
return { proceed: true, token: null };
@@ -37,7 +138,7 @@ export async function prepareHfTokenForUse(
let validation: HfTokenValidationResult;
try {
- validation = await validateHfToken(normalized);
+ validation = await validateOncePerBurst(normalized);
} catch {
// Validation is advisory. Let the real operation retain its own error.
return { proceed: true, token: normalized };
@@ -56,6 +157,7 @@ export async function prepareHfTokenForUse(
if (tokenStore.token === normalized) {
tokenStore.clearToken();
}
+ forgetHfTokenValidation(normalized);
return { proceed: true, token: null };
}
if (decision === "replace") {
diff --git a/studio/frontend/src/features/studio/training-start-overlay.tsx b/studio/frontend/src/features/studio/training-start-overlay.tsx
index 12616b3536e..ca962ae4d1e 100644
--- a/studio/frontend/src/features/studio/training-start-overlay.tsx
+++ b/studio/frontend/src/features/studio/training-start-overlay.tsx
@@ -26,6 +26,7 @@ import {
} from "@/features/chat/api/chat-api";
import { useTransferStats } from "@/features/chat/hooks/use-transfer-stats";
import { formatEta, formatRate } from "@/features/chat/utils/format-transfer";
+import { useHfTokenStore } from "@/features/hub/stores/hf-token-store";
import {
EMPTY_DOWNLOAD_STATE,
coerceCachedStateReady,
@@ -45,7 +46,7 @@ import {
} from "@/features/training";
import { Cancel01Icon } from "@hugeicons/core-free-icons";
import { HugeiconsIcon } from "@hugeicons/react";
-import { useEffect, useState, type ReactElement } from "react";
+import { useCallback, useEffect, useState, type ReactElement } from "react";
import { useT } from "@/i18n";
const HF_REPO_REGEX = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
@@ -146,12 +147,26 @@ function useHfDownloadProgress(
return state;
}
-function useModelDownloadProgress(modelName: string | null): DownloadState {
- return useHfDownloadProgress(modelName, getDownloadProgress);
+function useModelDownloadProgress(
+ modelName: string | null,
+ hfToken: string | null,
+): DownloadState {
+ const fetchProgress = useCallback(
+ (repoId: string) => getDownloadProgress(repoId, hfToken),
+ [hfToken],
+ );
+ return useHfDownloadProgress(modelName, fetchProgress);
}
-function useDatasetDownloadProgress(datasetName: string | null): DownloadState {
- return useHfDownloadProgress(datasetName, getDatasetDownloadProgress);
+function useDatasetDownloadProgress(
+ datasetName: string | null,
+ hfToken: string | null,
+): DownloadState {
+ const fetchProgress = useCallback(
+ (repoId: string) => getDatasetDownloadProgress(repoId, hfToken),
+ [hfToken],
+ );
+ return useHfDownloadProgress(datasetName, fetchProgress);
}
const PROGRESS_INDICATOR_CLASS =
@@ -292,8 +307,10 @@ export function TrainingStartOverlay({
const jobId = useTrainingRuntimeStore((s) => s.jobId);
const startModelName = useTrainingRuntimeStore((s) => s.startModelName);
const startDatasetName = useTrainingRuntimeStore((s) => s.startDatasetName);
+ const startHfToken = useTrainingRuntimeStore((s) => s.startHfToken);
const startFromResume = useTrainingRuntimeStore((s) => s.startFromResume);
const configuredModel = useTrainingConfigStore((s) => s.selectedModel);
+ const configuredHfToken = useHfTokenStore((s) => s.token);
const datasetSource = useTrainingConfigStore((s) => s.datasetSource);
const dataset = useTrainingConfigStore((s) => s.dataset);
// Streaming runs never fully download the dataset (only small metadata lands
@@ -315,12 +332,13 @@ export function TrainingStartOverlay({
: useConfiguredResources
? hfDatasetName
: null;
+ const hfToken = hasStartResources ? startHfToken : configuredHfToken;
const displayMessage =
startFromResume && /^download/i.test(message)
? t("studio.trainingStart.resumingTraining")
: message || t("studio.trainingStart.startingTraining");
- const rawModelDownload = useModelDownloadProgress(modelName);
- const rawDatasetDownload = useDatasetDownloadProgress(datasetName);
+ const rawModelDownload = useModelDownloadProgress(modelName, hfToken);
+ const rawDatasetDownload = useDatasetDownloadProgress(datasetName, hfToken);
const modelDownload = coerceCachedStateReady(rawModelDownload);
const datasetDownload = coerceCachedStateReady(rawDatasetDownload);
// the raw message, not displayMessage: a resumed run rewrites its download statuses to
diff --git a/studio/frontend/src/features/training/lib/resume-training-run.ts b/studio/frontend/src/features/training/lib/resume-training-run.ts
index 4c4b820a205..33d30952818 100644
--- a/studio/frontend/src/features/training/lib/resume-training-run.ts
+++ b/studio/frontend/src/features/training/lib/resume-training-run.ts
@@ -54,6 +54,7 @@ export async function resumeTrainingRun(runId: string): Promise<boolean> {
payload.hf_dataset,
true,
payload.project_name ?? "",
+ payload.hf_token,
);
// Upgrade consent first, then the custom-code gate, like a fresh start: a resume
diff --git a/studio/frontend/src/features/training/lib/start-fresh-training-run.ts b/studio/frontend/src/features/training/lib/start-fresh-training-run.ts
index 099f69a6577..ae1fedf1b7b 100644
--- a/studio/frontend/src/features/training/lib/start-fresh-training-run.ts
+++ b/studio/frontend/src/features/training/lib/start-fresh-training-run.ts
@@ -540,6 +540,7 @@ async function submitFreshTrainingRun(
payload.hf_dataset,
false,
payload.project_name ?? "",
+ payload.hf_token,
);
const response = await startTraining(payload, attempt.startRequestId);
if (response.status === "error") {
diff --git a/studio/frontend/src/features/training/stores/training-runtime-store.ts b/studio/frontend/src/features/training/stores/training-runtime-store.ts
index 75789fe0b84..7106f0bec95 100644
--- a/studio/frontend/src/features/training/stores/training-runtime-store.ts
+++ b/studio/frontend/src/features/training/stores/training-runtime-store.ts
@@ -2,6 +2,10 @@
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
import { create } from "zustand";
+// Module state outlives a logout, so this store clears with the session. Relative and
+// extensioned like the sibling below: the store's test runs under
+// `node --experimental-strip-types`, which cannot resolve the `@/` alias.
+import { AUTH_SESSION_CLEARED_EVENT } from "../../auth/session-events.ts";
import { isTrainingProgressForJob } from "../lib/training-stream-scope.ts";
import type {
TrainingMetricsResponse,
@@ -61,6 +65,7 @@ const initialState: TrainingRuntimeState = {
startError: null,
startModelName: null,
startDatasetName: null,
+ startHfToken: null,
startProjectName: null,
startFromResume: false,
sseConnected: false,
@@ -263,10 +268,12 @@ export const useTrainingRuntimeStore = create<TrainingRuntimeStore>()(
startDatasetName,
startFromResume = false,
startProjectName = null,
+ startHfToken = null,
) =>
set({
startModelName,
startDatasetName,
+ startHfToken,
startProjectName,
startFromResume,
}),
@@ -603,6 +610,21 @@ export const useTrainingRuntimeStore = create<TrainingRuntimeStore>()(
}),
);
+// startHfToken holds a raw Hub credential in module state that outlives a logout:
+// reconcile() in __root remounts rather than reloading, so the next account in the tab
+// would poll with the previous one's token. useHfTokenStore already clears on this event.
+if (typeof window !== "undefined") {
+ window.addEventListener(AUTH_SESSION_CLEARED_EVENT, () => {
+ useTrainingRuntimeStore.getState().resetRuntime();
+ useTrainingRuntimeStore.setState({
+ startHfToken: null,
+ startModelName: null,
+ startDatasetName: null,
+ startProjectName: null,
+ });
+ });
+}
+
export function shouldShowTrainingView(state: TrainingRuntimeStore): boolean {
return (
state.phase !== "idle" ||
diff --git a/studio/frontend/src/features/training/types/runtime.ts b/studio/frontend/src/features/training/types/runtime.ts
index 5c0505b33d8..8b122aa3a9f 100644
--- a/studio/frontend/src/features/training/types/runtime.ts
+++ b/studio/frontend/src/features/training/types/runtime.ts
@@ -92,6 +92,7 @@ export interface TrainingRuntimeState {
startError: string | null;
startModelName: string | null;
startDatasetName: string | null;
+ startHfToken: string | null;
startProjectName: string | null;
startFromResume: boolean;
sseConnected: boolean;
@@ -132,6 +133,7 @@ export interface TrainingRuntimeActions {
datasetName: string | null,
fromResume?: boolean,
projectName?: string | null,
+ hfToken?: string | null,
) => void;
setSseConnected: (value: boolean) => void;
setLastEventId: (value: number | null) => void;
diff --git a/studio/frontend/tests/chat-load-hub-token-reach.test.ts b/studio/frontend/tests/chat-load-hub-token-reach.test.ts
new file mode 100644
index 00000000000..b88a6de3daf
--- /dev/null
+++ b/studio/frontend/tests/chat-load-hub-token-reach.test.ts
@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// A load served entirely from disk must not prepare a Hub credential: preparing one
+// validates over the network and can open a blocking dialog that cancels the load, so a
+// stale Settings token would break loads that never needed it. isLocalModelPath covers
+// real paths; an Ollama row's id is an opaque `ollama-manifest:` reference, which is
+// neither a path nor a repo id.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { isLocalModelPath } from "../src/features/chat/utils/model-download-staging.ts";
+import { isOllamaLinkPath } from "../src/features/hub/lib/model-identity.ts";
+
+// The predicate as the load path composes it; nativePathToken is the file-lease case.
+function mayReachHub(modelId: string, nativePathToken: string | null): boolean {
+ const servedFromDisk = isLocalModelPath(modelId) || isOllamaLinkPath(modelId);
+ return !servedFromDisk && nativePathToken == null;
+}
+
+test("an opaque Ollama manifest reference prepares no Hub token", () => {
+ // The gap: it is local, but it does not look like a path.
+ assert.equal(isLocalModelPath("ollama-manifest:llama3:8b"), false);
+ assert.equal(mayReachHub("ollama-manifest:llama3:8b", null), false);
+});
+
+test("an Ollama link path prepares no Hub token", () => {
+ assert.equal(
+ mayReachHub("/home/u/.unsloth/ollama_links/model.gguf", null),
+ false,
+ );
+});
+
+test("a local path or a native lease prepares no Hub token", () => {
+ assert.equal(mayReachHub("/models/llama.gguf", null), false);
+ assert.equal(mayReachHub("C:\\models\\llama.gguf", null), false);
+ assert.equal(mayReachHub("unsloth/Llama-3.2-1B-Instruct", "lease-abc"), false);
+});
+
+test("a plain Hub repo id still prepares its token", () => {
+ assert.equal(mayReachHub("unsloth/Llama-3.2-1B-Instruct", null), true);
+ assert.equal(mayReachHub("unsloth/gemma-3-4b-it-GGUF", null), true);
+});
diff --git a/studio/frontend/tests/hf-token-preparation-bursts.test.ts b/studio/frontend/tests/hf-token-preparation-bursts.test.ts
new file mode 100644
index 00000000000..d05e87abc41
--- /dev/null
+++ b/studio/frontend/tests/hf-token-preparation-bursts.test.ts
@@ -0,0 +1,260 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// One model load prepares the same token three times: the progress pollers, validateModel
+// and loadModel. Each preparation used to be its own POST /api/hub/token/validate, three
+// sequential round trips on the load's critical path. Drive the real module and count.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { installLocalStorageFake } from "./helpers/kit.ts";
+import { loadWithStubs } from "./helpers/module-stubs.ts";
+
+// The module registers its logout listener at import time, so the window has to exist
+// before loadWithStubs runs and has to keep the registration for the test to fire it.
+const { fireWindowEvent } = installLocalStorageFake();
+
+type ValidationStatus = "valid" | "invalid" | "unavailable" | "missing";
+
+type Prepared = { proceed: boolean; token: string | null };
+
+type ConfirmToken = {
+ prepareHfTokenForUse: (token: string | null) => Promise<Prepared>;
+ forgetHfTokenValidation: (token?: string) => void;
+};
+
+const SESSION_CLEARED = "unsloth:auth-session-cleared";
+
+// The store the module subscribes to, so a test can drive a Settings token change.
+function tokenStoreStub(initial: string | null = null) {
+ let listener: ((state: { token: string }) => void) | null = null;
+ let current = initial;
+ return {
+ store: {
+ getState: () => ({ token: current, clearToken: () => {} }),
+ subscribe: (fn: (state: { token: string }) => void) => {
+ listener = fn;
+ return () => {
+ listener = null;
+ };
+ },
+ },
+ change(token: string) {
+ current = token;
+ listener?.({ token });
+ },
+ };
+}
+
+type Gate = { promise: Promise<void>; open: () => void };
+
+function makeGate(): Gate {
+ let open: () => void = () => {};
+ const promise = new Promise<void>((resolve) => {
+ open = () => resolve();
+ });
+ return { promise, open };
+}
+
+function load(
+ status: ValidationStatus,
+ calls: { n: number },
+ tokenStore = tokenStoreStub(),
+ gate: Gate | null = null,
+ gates: Gate[] | null = null,
+): ConfirmToken {
+ const noopStore = {
+ getState: () => ({
+ token: null,
+ clearToken: () => {},
+ openDialog: () => {},
+ requestDecision: async () => "cancel",
+ }),
+ };
+ return loadWithStubs<ConfirmToken>(
+ new URL("../src/features/hf-auth/confirm-token.ts", import.meta.url),
+ {
+ "@/features/auth/session-events": {
+ AUTH_SESSION_CLEARED_EVENT: SESSION_CLEARED,
+ },
+ "@/features/hub/stores/hf-token-store": {
+ useHfTokenStore: tokenStore.store,
+ },
+ "@/features/settings/stores/settings-dialog-store": {
+ useSettingsDialogStore: noopStore,
+ },
+ "./api": {
+ validateHfToken: async () => {
+ calls.n += 1;
+ // A per-call gate when a queue is supplied, so one request can settle while
+ // another is still pending; otherwise the single shared gate, or none.
+ const own = gates ? gates[calls.n - 1] : gate;
+ if (own) {
+ await own.promise;
+ }
+ return { status, retryAfterSeconds: null };
+ },
+ },
+ "./store": { useHfTokenWarningStore: noopStore },
+ },
+ );
+}
+
+test("a burst of preparations for one valid token validates once", async () => {
+ const calls = { n: 0 };
+ const mod = load("valid", calls);
+
+ const results = await Promise.all([
+ mod.prepareHfTokenForUse("hf_valid"),
+ mod.prepareHfTokenForUse("hf_valid"),
+ mod.prepareHfTokenForUse("hf_valid"),
+ ]);
+
+ assert.equal(calls.n, 1, "one load issued more than one validation round trip");
+ for (const result of results) {
+ assert.deepEqual(result, { proceed: true, token: "hf_valid" });
+ }
+
+ // The sequential case is the real one: pollers, then validateModel, then loadModel.
+ await mod.prepareHfTokenForUse("hf_valid");
+ assert.equal(calls.n, 1);
+});
+
+test("distinct tokens are validated separately", async () => {
+ const calls = { n: 0 };
+ const mod = load("valid", calls);
+
+ await mod.prepareHfTokenForUse("hf_one");
+ await mod.prepareHfTokenForUse("hf_two");
+
+ assert.equal(calls.n, 2, "two different credentials shared one verdict");
+});
+
+test("a non-definitive verdict is never reused", async () => {
+ // "unavailable" proves nothing, so caching it would suppress the warning dialog for a
+ // token that is in fact bad.
+ const calls = { n: 0 };
+ const mod = load("unavailable", calls);
+
+ await mod.prepareHfTokenForUse("hf_maybe");
+ await mod.prepareHfTokenForUse("hf_maybe");
+
+ assert.equal(calls.n, 2, "an inconclusive verdict was cached");
+});
+
+test("an invalid verdict is re-checked rather than remembered", async () => {
+ const calls = { n: 0 };
+ const mod = load("invalid", calls);
+
+ const first = await mod.prepareHfTokenForUse("hf_bad");
+ const second = await mod.prepareHfTokenForUse("hf_bad");
+
+ assert.equal(first.proceed, false);
+ assert.equal(second.proceed, false);
+ assert.equal(calls.n, 2, "an invalid verdict was cached and the dialog skipped");
+});
+
+test("forgetting a token drops an unexpired window", async () => {
+ const calls = { n: 0 };
+ const mod = load("valid", calls);
+
+ await mod.prepareHfTokenForUse("hf_valid");
+ mod.forgetHfTokenValidation("hf_valid");
+ await mod.prepareHfTokenForUse("hf_valid");
+
+ assert.equal(calls.n, 2, "a replaced credential rode the previous window");
+});
+
+
+test("a logout drops the cached bearer token", async () => {
+ // The cache holds the raw credential, so it must not outlive the session that made it.
+ const calls = { n: 0 };
+ const mod = load("valid", calls);
+
+ await mod.prepareHfTokenForUse("hf_valid");
+ assert.equal(calls.n, 1);
+
+ const delivered = fireWindowEvent(SESSION_CLEARED, {});
+ assert.ok(delivered > 0, "the module registered no logout listener");
+
+ await mod.prepareHfTokenForUse("hf_valid");
+ assert.equal(calls.n, 2, "a previous session's credential survived the logout");
+});
+
+test("replacing the stored credential drops the superseded key", async () => {
+ const calls = { n: 0 };
+ const tokenStore = tokenStoreStub();
+ const mod = load("valid", calls, tokenStore);
+
+ // The subscription is installed on first use, so prepare before staging the change.
+ await mod.prepareHfTokenForUse("hf_old");
+ assert.equal(calls.n, 1);
+ tokenStore.change("hf_old");
+
+ tokenStore.change("hf_new");
+
+ await mod.prepareHfTokenForUse("hf_old");
+ assert.equal(calls.n, 2, "the replaced credential kept its window");
+});
+
+
+test("a logout mid-validation does not let the reply repopulate the cache", async () => {
+ // Clearing the maps cannot cancel a request already in flight; without a generation
+ // the late resolution writes the raw token back and expiry never runs to remove it.
+ const calls = { n: 0 };
+ const gate = makeGate();
+ const mod = load("valid", calls, tokenStoreStub(), gate);
+
+ const pending = mod.prepareHfTokenForUse("hf_valid");
+ mod.forgetHfTokenValidation();
+ gate.open();
+ await pending;
+ assert.equal(calls.n, 1);
+
+ await mod.prepareHfTokenForUse("hf_valid");
+ assert.equal(calls.n, 2, "the in-flight reply repopulated the cleared cache");
+});
+
+
+test("replacing the token that was already stored drops its window", async () => {
+ // zustand does not fire subscribe on install, so without seeding lastKnownStoredToken
+ // the first replacement reads as initialization and the old credential keeps its slot.
+ const calls = { n: 0 };
+ const tokenStore = tokenStoreStub("hf_old");
+ const mod = load("valid", calls, tokenStore);
+
+ await mod.prepareHfTokenForUse("hf_old");
+ assert.equal(calls.n, 1);
+
+ tokenStore.change("hf_new");
+
+ await mod.prepareHfTokenForUse("hf_old");
+ assert.equal(calls.n, 2, "the superseded credential kept its window");
+});
+
+
+test("a replacement request is not evicted by the old one settling", async () => {
+ // forget() drops the in-flight entry, a new preparation takes the slot, and the old
+ // promise's finally must not then delete that live replacement.
+ // "unavailable" is never cached, so sharing is observable purely through the count.
+ const calls = { n: 0 };
+ const gates = [makeGate(), makeGate(), makeGate()];
+ const mod = load("unavailable", calls, tokenStoreStub(), null, gates);
+
+ const stale = mod.prepareHfTokenForUse("hf_a");
+ mod.forgetHfTokenValidation("hf_a");
+
+ const replacement = mod.prepareHfTokenForUse("hf_a");
+ assert.equal(calls.n, 2, "the replacement did not start its own request");
+
+ // Only the first settles; the replacement is still in flight.
+ gates[0].open();
+ await stale;
+
+ const shared = mod.prepareHfTokenForUse("hf_a");
+ assert.equal(calls.n, 2, "the settling request evicted its live replacement");
+
+ gates[1].open();
+ await Promise.all([replacement, shared]);
+});
diff --git a/studio/frontend/tests/hub-progress-token-boundary.test.ts b/studio/frontend/tests/hub-progress-token-boundary.test.ts
new file mode 100644
index 00000000000..5f578c47bef
--- /dev/null
+++ b/studio/frontend/tests/hub-progress-token-boundary.test.ts
@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// Assert on the request the browser emits, not the shape of the source: these still fail
+// if the header is dropped, blanked, or eaten by authFetch's own merge.
+
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+
+import { hubTokenHeader } from "../src/features/hub/lib/hub-token-header.ts";
+import { loadWithStubs } from "./helpers/module-stubs.ts";
+
+type AuthApi = {
+ authFetch: (input: string, init?: RequestInit) => Promise<Response>;
+};
+
+const read = (relativePath: string): string =>
+ readFileSync(new URL(relativePath, import.meta.url), "utf8");
+
+async function emittedHeaders(init?: RequestInit): Promise<Headers> {
+ const originalFetch = globalThis.fetch;
+ let received = new Headers();
+ globalThis.fetch = async (_input, fetchInit) => {
+ received = new Headers(fetchInit?.headers);
+ return new Response(null, { status: 200 });
+ };
+ try {
+ const authApi = loadWithStubs<AuthApi>(
+ new URL("../src/features/auth/api.ts", import.meta.url),
+ {
+ "@/lib/api-base": { apiUrl: (path: string) => path, isTauri: false },
+ "./session": {
+ clearAuthTokens: () => {},
+ getAuthToken: () => "access-token",
+ getRefreshToken: () => null,
+ mustChangePassword: () => false,
+ setMustChangePassword: () => {},
+ storeAuthTokens: () => {},
+ },
+ },
+ );
+ await authApi.authFetch("/api/models/download-progress?repo_id=org/repo", init);
+ return received;
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+}
+
+test("a progress request with a token carries it, alongside the session credential", async () => {
+ const headers = await emittedHeaders({ headers: hubTokenHeader("hf_secret") });
+
+ assert.equal(headers.get("X-Unsloth-HF-Token"), "hf_secret");
+ // authFetch seeds Headers from init: a caller passing `headers` must not displace these.
+ assert.equal(headers.get("Authorization"), "Bearer access-token");
+ assert.ok(headers.get("X-Unsloth-Timezone"));
+});
+
+test("a tokenless progress request omits the header rather than blanking it", async () => {
+ for (const token of [null, undefined, ""]) {
+ const headers = await emittedHeaders({ headers: hubTokenHeader(token) });
+
+ // An empty-string header is not equivalent: the backend reads it as present.
+ assert.equal(
+ headers.has("X-Unsloth-HF-Token"),
+ false,
+ `token ${JSON.stringify(token)} must not emit the header at all`,
+ );
+ assert.equal(headers.get("Authorization"), "Bearer access-token");
+ }
+});
+
+test("hubTokenHeader never leaks the token anywhere but its own header", async () => {
+ const headers = await emittedHeaders({ headers: hubTokenHeader("hf_secret") });
+
+ for (const [name, value] of headers.entries()) {
+ if (name.toLowerCase() === "x-unsloth-hf-token") continue;
+ assert.equal(
+ value.includes("hf_secret"),
+ false,
+ `header ${name} must not carry the Hub token`,
+ );
+ }
+});
+
+test("the progress callers accept and forward a request-scoped token", () => {
+ // Whitespace-insensitive: the transport tests cannot prove these callers send one.
+ const api = read("../src/features/chat/api/chat-api.ts");
+ for (const name of [
+ "getGgufDownloadProgress",
+ "getDownloadProgress",
+ "getDatasetDownloadProgress",
+ ]) {
+ const start = api.indexOf(`export async function ${name}`);
+ assert.notEqual(start, -1, `${name} is missing`);
+ const next = api.indexOf("\nexport ", start + 1);
+ const body = api.slice(start, next === -1 ? undefined : next);
+ assert.match(body, /hfToken\?:\s*string\s*\|\s*null/, `${name} takes no token`);
+ assert.match(
+ body,
+ /headers:\s*hubTokenHeader\(\s*hfToken\s*,?\s*\)/,
+ `${name} does not send the token`,
+ );
+ }
+});
+
+test("a local load is not gated behind Hub token preparation", () => {
+ // prepareHfTokenForUse validates over the network and can block on a dialog.
+ const chatRuntime = read(
+ "../src/features/chat/hooks/use-chat-model-runtime.ts",
+ );
+ const start = chatRuntime.indexOf("const mayReachHub");
+ assert.notEqual(start, -1, "the local-load guard is missing");
+ const guarded = chatRuntime.slice(start, start + 600);
+ assert.match(guarded, /!isLocal/);
+ // An Ollama row is local too, but its id is an opaque reference rather than a path,
+ // so isLocalModelPath alone lets it through. chat-load-hub-token-reach.test.ts pins
+ // what the predicate itself classifies.
+ assert.match(guarded, /!isOllamaLinkPath\(modelId\)/);
+ assert.match(guarded, /nativePathToken\s*==\s*null/);
+ assert.match(guarded, /if\s*\(mayReachHub\)\s*\{[\s\S]*prepareHfTokenForUse\(hfToken\)/);
+});
diff --git a/tests/studio/test_model_picker_contracts.py b/tests/studio/test_model_picker_contracts.py
index 1d38a68d511..6b700735c86 100644
--- a/tests/studio/test_model_picker_contracts.py
+++ b/tests/studio/test_model_picker_contracts.py
@@ -1287,8 +1287,13 @@ def test_chat_load_prepares_hf_token_before_gguf_metadata_preflight():
prepare = runtime.index("prepareHfTokenForUse(")
metadata = runtime.index("fetchGgufStagedMetadata({", prepare)
assert prepare < metadata
- # The raw store token must not be handed to the preflight.
- assert "hf_token: preparedToken.token" in runtime
+ # The raw store token must not be handed to the preflight. The prepared value now
+ # reaches it through the hoisted `hfToken` binding rather than inline, so pin both
+ # halves: the assignment, and that the preflight reads that binding.
+ assert "hfToken = preparedToken.token" in runtime
+ preflight = runtime.index("fetchGgufStagedMetadata({", prepare)
+ assert "hf_token: hfToken" in runtime[preflight : preflight + 400]
+ assert runtime.index("hfToken = preparedToken.token") < preflight
assert (
"hf_token: useChatRuntimeStore.getState().hfToken" not in runtime
), "GGUF metadata preflight must not send the unprepared stored token"