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.

Studio: load a single .safetensors DiT from any Hugging Face repo (#12879)

Daniel Hanebb079b8126a
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 2728692e350..bc2180769cd 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -8,7 +8,9 @@ GGUF transformer dequantised on-device via ``GGUFQuantizationConfig``, a single-
transformer (e.g. fp8), or a full diffusers pipeline via ``from_pretrained`` (which re-applies an
embedded quant config such as bnb-4bit). The single-file kinds pull the rest of the pipeline (VAE,
text encoders, scheduler) from the matching base repo; the pipeline kind pulls everything from the
-repo itself. Non-GGUF kinds are gated to the ``unsloth/*`` org (or a local path) for safety.
+repo itself. Pipeline loads are gated to the ``unsloth/*`` org, the official bases, or a local path
+for safety; a single ``.safetensors`` file is trusted per file from any repo (see
+``diffusion_single_file_trust``).
torch/diffusers are imported lazily so this stays importable in a no-torch runtime. ``begin_load``
runs on a background thread; poll ``load_progress`` for the download bar. GPU-handoff policy lives
@@ -283,6 +285,7 @@ from .diffusion_comfy_quant import (
load_comfy_quant_transformer,
refuse_comfy_quant,
)
+from .diffusion_single_file_trust import assert_safetensors_file, single_file_load_allowed
from .diffusion_prequant import (
hosted_fast_accum_conflict,
load_prequantized_transformer,
@@ -842,7 +845,9 @@ def _is_trusted_diffusion_repo(repo_id: str) -> bool:
arbitrary repo, which fetches and deserialises third-party weights. So the non-GGUF paths are
gated to the ``unsloth/*`` org, a short allowlist of official safetensors-only base repos
(``_TRUSTED_NON_GGUF_REPOS``), and local paths the user explicitly pointed at. The GGUF path
- stays open to any repo.
+ stays open to any repo, and so does a single ``.safetensors`` file, which is trusted per file
+ instead (``diffusion_single_file_trust.single_file_load_allowed``); this predicate still decides
+ pipeline loads and every ``base_repo``.
A bare ``owner/name`` HF id is never a real filesystem path, and an id with invalid characters
makes ``Path.exists()`` raise OSError; treat any such failure as not a local path so the trust
@@ -3027,11 +3032,15 @@ class DiffusionBackend:
f"multiple transformers), not from a single-file or GGUF checkpoint; "
f"select the pipeline repo."
)
- # Non-GGUF loads fetch + deserialise weights, so gate to unsloth/ or a local path.
- if kind != "gguf" and not _is_trusted_diffusion_repo(repo_id):
+ # Non-GGUF loads deserialise weights: repo-gated, except a lone .safetensors file (diffusion_single_file_trust).
+ if kind != "gguf" and not single_file_load_allowed(
+ _is_trusted_diffusion_repo(repo_id), kind, gguf_filename
+ ):
raise ValueError(
- f"Non-GGUF diffusion loads are restricted to unsloth/* repos (or a local "
- f"path); got '{repo_id}'. Pass a gguf_filename to load a GGUF instead."
+ f"Non-GGUF diffusion loads from '{repo_id}' are limited to a single .safetensors "
+ f"checkpoint; full pipelines and other weight formats load only from unsloth/* "
+ f"repos, the official base repos, or a local path. Pass a gguf_filename to load "
+ f"a GGUF instead."
)
# The companion base repo also loads via from_pretrained, so it must clear the same trust bar
if base_repo and base_repo.strip() and not _is_trusted_diffusion_repo(base_repo):
@@ -5611,6 +5620,9 @@ class DiffusionBackend:
# A renamed or hand-picked FLUX.2 GGUF can still land on a different-size base, and no name-based rule
# catches that. Say so here, naming the file and the repo, rather than letting the GGUF quantizer
# raise a bare shape mismatch.
+ if kind == "single_file" and not _is_trusted_diffusion_repo(repo_id):
+ # Admitted per file: prove it is a safetensors container before any probe or loader opens it.
+ assert_safetensors_file(single_file_path)
assert_flux2_gguf_matches_base(fam, base, single_file_path)
# A ComfyUI-quantized file loads through its own path below; a format it cannot run is refused here,
# from the header, before planning or reading a weight, rather than loaded with its scales dropped.
diff --git a/studio/backend/core/inference/diffusion_comfy_quant.py b/studio/backend/core/inference/diffusion_comfy_quant.py
index a03decda104..bd0c7383499 100644
--- a/studio/backend/core/inference/diffusion_comfy_quant.py
+++ b/studio/backend/core/inference/diffusion_comfy_quant.py
@@ -103,8 +103,14 @@ def _read_header(path: str) -> tuple[dict, int]:
return json.loads(handle.read(size)), 8 + size
+# A comfy_quant declaration is a few hundred bytes of JSON; a file can claim any span, so never read a large one.
+_MAX_COMFY_QUANT_BYTES = 1 << 20
+
+
def _read_json_tensor(path: str, entry: dict, base: int) -> Any:
start, end = entry["data_offsets"]
+ if not 0 <= int(end) - int(start) <= _MAX_COMFY_QUANT_BYTES:
+ raise ValueError(f"comfy_quant declaration spans {int(end) - int(start)} bytes")
with open(path, "rb") as handle:
handle.seek(base + int(start))
return json.loads(handle.read(int(end) - int(start)).decode("utf-8"))
diff --git a/studio/backend/core/inference/diffusion_single_file_trust.py b/studio/backend/core/inference/diffusion_single_file_trust.py
new file mode 100644
index 00000000000..d9fdaaa7eff
--- /dev/null
+++ b/studio/backend/core/inference/diffusion_single_file_trust.py
@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Per-file trust for single-file diffusion checkpoints from any Hugging Face repo.
+
+The repo allowlists guard ``from_pretrained`` (pickled weights, ``trust_remote_code``). A lone
+``.safetensors`` file has neither risk: only that file is downloaded, it is parsed without
+unpickling, and every config and companion still comes from the family's trusted base repo.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import struct
+from pathlib import Path
+from typing import Optional, Union
+
+SAFETENSORS_SUFFIX = ".safetensors"
+
+# Same cap as the safetensors reference parser: a crafted length prefix cannot force a huge read.
+_MAX_HEADER_BYTES = 100 * 1024 * 1024
+
+
+def is_hub_safetensors_single_file(filename: Optional[str]) -> bool:
+ """A repo-relative ``.safetensors`` name: no absolute path, ``..``, backslash or NUL, and the final
+ suffix is ``.safetensors`` (``x.safetensors.pt`` never qualifies)."""
+ if not isinstance(filename, str):
+ return False
+ name = filename.strip()
+ if not name or name != filename or "\\" in name or "\x00" in name:
+ return False
+ if name.startswith("/") or ":" in name:
+ return False
+ parts = name.split("/")
+ if any(part in ("", ".", "..") for part in parts):
+ return False
+ leaf = parts[-1]
+ # Case-sensitive like diffusers' load_state_dict: x.SafeTensors would fall through to torch.load.
+ return leaf.endswith(SAFETENSORS_SUFFIX) and len(leaf) > len(SAFETENSORS_SUFFIX)
+
+
+def single_file_load_allowed(repo_trusted: bool, kind: str, filename: Optional[str]) -> bool:
+ """Non-GGUF trust decision: a trusted repo keeps every kind; an untrusted one gains only a
+ ``single_file`` load of a ``.safetensors`` name."""
+ if repo_trusted:
+ return True
+ return kind == "single_file" and is_hub_safetensors_single_file(filename)
+
+
+def assert_safetensors_file(path: Union[str, os.PathLike]) -> None:
+ """Raise ValueError unless ``path`` is a well-formed safetensors container (header only: length,
+ JSON object, every ``data_offsets`` inside the data section). Runs before any loader opens it."""
+ p = Path(path)
+ label = p.name
+ try:
+ size = p.stat().st_size
+ with open(p, "rb") as handle:
+ prefix = handle.read(8)
+ if len(prefix) != 8:
+ raise ValueError("file is shorter than a safetensors header")
+ (header_len,) = struct.unpack("<Q", prefix)
+ if header_len < 2 or header_len > _MAX_HEADER_BYTES or 8 + header_len > size:
+ raise ValueError("header length is out of range")
+ raw = handle.read(header_len)
+ except OSError as exc:
+ raise ValueError(f"'{label}' could not be read as a safetensors checkpoint: {exc}") from exc
+ except ValueError as exc:
+ raise ValueError(f"'{label}' is not a valid safetensors checkpoint: {exc}") from exc
+ try:
+ header = json.loads(raw.decode("utf-8"))
+ except (UnicodeDecodeError, ValueError) as exc:
+ raise ValueError(
+ f"'{label}' is not a valid safetensors checkpoint: the header is not JSON"
+ ) from exc
+ if not isinstance(header, dict):
+ raise ValueError(
+ f"'{label}' is not a valid safetensors checkpoint: the header is not an object"
+ )
+ data_len = size - 8 - header_len
+ tensors = 0
+ for name, entry in header.items():
+ if name == "__metadata__":
+ if entry is not None and not isinstance(entry, dict):
+ raise ValueError(
+ f"'{label}' is not a valid safetensors checkpoint: bad __metadata__"
+ )
+ continue
+ offsets = entry.get("data_offsets") if isinstance(entry, dict) else None
+ if (
+ not isinstance(entry, dict)
+ or not isinstance(entry.get("dtype"), str)
+ or not isinstance(entry.get("shape"), list)
+ or not isinstance(offsets, list)
+ or len(offsets) != 2
+ or not all(isinstance(x, int) and not isinstance(x, bool) for x in offsets)
+ or not 0 <= offsets[0] <= offsets[1] <= data_len
+ ):
+ raise ValueError(
+ f"'{label}' is not a valid safetensors checkpoint: tensor '{name}' has a malformed entry"
+ )
+ tensors += 1
+ if tensors == 0:
+ raise ValueError(f"'{label}' is not a valid safetensors checkpoint: it holds no tensors")
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index 2c1b86b3346..429c78cc231 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -63,6 +63,7 @@ from .diffusion_comfy_quant import (
load_comfy_quant_transformer,
refuse_comfy_quant,
)
+from .diffusion_single_file_trust import assert_safetensors_file, single_file_load_allowed
from .diffusion_prequant import scoped_local_files_only
from .video_moe_pair import moe_expert_of, moe_partner_filename, moe_pick_pairs
from .diffusion_cache import (
@@ -2809,10 +2810,14 @@ class VideoBackend:
"MiniMax-H3 needs the Diffusers revision bundled with this Unsloth "
"version. Reinstall Unsloth dependencies and retry."
)
- if kind != "gguf" and not _is_trusted_video_repo(repo_id):
+ # A lone .safetensors file is trusted per file, from any repo (diffusion_single_file_trust).
+ if kind != "gguf" and not single_file_load_allowed(
+ _is_trusted_video_repo(repo_id), kind, gguf_filename
+ ):
raise ValueError(
- f"Non-GGUF video loads are limited to unsloth/* repos, the official "
- f"family base repos, and local paths; '{repo_id}' is neither."
+ f"Non-GGUF video loads from '{repo_id}' are limited to a single .safetensors "
+ f"checkpoint; full pipelines and other weight formats load only from unsloth/* "
+ f"repos, the official family base repos, and local paths."
)
# Companions load with from_pretrained, so a base repo is held to the non-GGUF bar: a GGUF pick must not smuggle
# in a remote base.
@@ -5857,6 +5862,8 @@ class VideoBackend:
repo_id, gguf_filename, hf_token, local_files_only = local_files_only
)
)
+ if not _is_trusted_video_repo(repo_id):
+ assert_safetensors_file(comfy_checkpoint)
return self._load_h3_modular_pipeline(
diffusers = diffusers,
torch = torch,
@@ -5935,6 +5942,10 @@ class VideoBackend:
checkpoint_path = self._resolve_checkpoint_path(
repo_id, gguf_filename, hf_token, local_files_only = local_files_only
)
+ # Admitted per file from an untrusted repo: prove each file is a safetensors container before any probe.
+ untrusted_single_file = kind == "single_file" and not _is_trusted_video_repo(repo_id)
+ if untrusted_single_file:
+ assert_safetensors_file(checkpoint_path)
if fam.name == "ltx-2":
from .video_ltx2 import ltx23_variant_identifier
variant_id = ltx23_variant_identifier(checkpoint_path)
@@ -5951,6 +5962,8 @@ class VideoBackend:
"""Resident MiB of one checkpoint file's DiT and its ComfyUI quant scan (None: a plain file)."""
scan = None
mib: Optional[int] = None
+ if untrusted_single_file:
+ assert_safetensors_file(path)
size_mib = file_size_mib(str(path))
if kind == "single_file":
scan = refuse_comfy_quant(str(path))
diff --git a/studio/backend/hub/services/models/catalog_classification.py b/studio/backend/hub/services/models/catalog_classification.py
index 17abda009d2..2014e5c5d94 100644
--- a/studio/backend/hub/services/models/catalog_classification.py
+++ b/studio/backend/hub/services/models/catalog_classification.py
@@ -669,6 +669,22 @@ def _is_sd_cpp_companion_repo(repo_id: str) -> bool:
return False
+def _untrusted_repo_single_files_loadable(repo_info, selected: Optional[Path] = None) -> bool:
+ """An untrusted cached repo of single ``.safetensors`` files (no pipeline index) still loads per
+ file; mirrors ``single_file_load_allowed``."""
+ try:
+ if _repo_has_pipeline_index(repo_info, selected):
+ return False
+ from core.inference.diffusion_single_file_trust import SAFETENSORS_SUFFIX
+ for revision in getattr(repo_info, "revisions", None) or ():
+ for cached in getattr(revision, "files", None) or ():
+ if str(getattr(cached, "file_name", "")).endswith(SAFETENSORS_SUFFIX):
+ return True
+ except Exception: # noqa: BLE001 -- a classification failure keeps the row untrusted
+ return False
+ return False
+
+
def _cached_repo_task(repo_info, selected: Optional[Path] = None) -> Optional[str]:
repo_id = getattr(repo_info, "repo_id", "") or ""
try:
@@ -677,7 +693,10 @@ def _cached_repo_task(repo_info, selected: Optional[Path] = None) -> Optional[st
family = detect_video_family(repo_id)
if family is not None:
- if not _is_trusted_video_repo(repo_id) or not _video_family_buildable(family):
+ trusted = _is_trusted_video_repo(repo_id) or _untrusted_repo_single_files_loadable(
+ repo_info, selected
+ )
+ if not trusted or not _video_family_buildable(family):
return None
return _VIDEO_GEN_TASK
except Exception:
@@ -691,7 +710,10 @@ def _cached_repo_task(repo_info, selected: Optional[Path] = None) -> Optional[st
if _is_sd_cpp_companion_repo(repo_id):
return None
family = detect_family(repo_id)
- if not _is_trusted_diffusion_repo(repo_id) or family is None:
+ trusted = _is_trusted_diffusion_repo(repo_id) or _untrusted_repo_single_files_loadable(
+ repo_info, selected
+ )
+ if not trusted or family is None:
return None
if not family_pipeline_available(family):
return None
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index dfea78225f0..ce58c47f78d 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -4269,8 +4269,9 @@ class DiffusionLoadRequest(BaseModel):
description = "How to load the model (null = auto-detect from gguf_filename): gguf "
"(single-file GGUF transformer, dequantised on-device), single_file (single-file "
"safetensors transformer, e.g. fp8), or pipeline (a full diffusers repo via "
- "from_pretrained, embedded quant auto-applied). Non-GGUF kinds are restricted to "
- "unsloth/* repos (or a local path).",
+ "from_pretrained, embedded quant auto-applied). A single_file .safetensors loads from "
+ "any repo; pipeline loads are restricted to unsloth/* repos, the official base repos, "
+ "or a local path.",
)
base_repo: Optional[str] = Field(
None, description = "Companion diffusers repo for VAE/text-encoders (default: family base)"
@@ -5772,8 +5773,8 @@ class VideoLoadRequest(BaseModel):
description = "How to load the model (null = auto-detect from gguf_filename): gguf "
"(single-file GGUF transformer, dequantised on-device), single_file (single-file "
"safetensors transformer, e.g. fp8), or pipeline (a full diffusers repo via "
- "from_pretrained). Non-GGUF kinds are restricted to unsloth/* repos, the official "
- "family base repos, or a local path.",
+ "from_pretrained). A single_file .safetensors loads from any repo; pipeline loads are "
+ "restricted to unsloth/* repos, the official family base repos, or a local path.",
)
base_repo: Optional[str] = Field(
None,
diff --git a/studio/backend/tests/test_diffusion_backend.py b/studio/backend/tests/test_diffusion_backend.py
index ebafc8edb4c..890d006396b 100644
--- a/studio/backend/tests/test_diffusion_backend.py
+++ b/studio/backend/tests/test_diffusion_backend.py
@@ -4220,9 +4220,15 @@ def test_validate_load_request(tmp_path):
backend.validate_load_request(
"unsloth/Z-Image-Turbo-bnb-4bit", gguf_filename = "q.gguf", model_kind = "pipeline"
)
- # A single-file safetensors load is also gated to unsloth/* repos.
+ # A single .safetensors file is trusted per file, from any repo; any other weight format there is still refused.
+ assert (
+ backend.validate_load_request("some-org/Z-Image", gguf_filename = "model.safetensors").name
+ == "z-image"
+ )
with pytest.raises(ValueError, match = "unsloth"):
- backend.validate_load_request("some-org/Z-Image", gguf_filename = "model.safetensors")
+ backend.validate_load_request(
+ "some-org/Z-Image", gguf_filename = "model.ckpt", model_kind = "single_file"
+ )
with pytest.raises(ValueError, match = "family"):
backend.validate_load_request("meta/Llama-3", gguf_filename = "q.gguf")
# A family-looking repo with a non-GGUF single-file name is rejected before the route evicts chat.
@@ -14985,3 +14991,92 @@ def test_qwen_load_samples_at_comfy_static_shift(fake_runtime, tmp_path, monkeyp
backend = _loaded_backend(tmp_path, family_override = "qwen-image")
cfg = backend._state.pipe.scheduler.config
assert (cfg["shift"], cfg["use_dynamic_shifting"], cfg["shift_terminal"]) == (3.1, False, None)
+
+
+def _write_min_safetensors(path):
+ """A real, minimal safetensors container (one F32 scalar) written by hand: ``torch`` is faked here."""
+ header = json.dumps({"w": {"dtype": "F32", "shape": [1], "data_offsets": [0, 4]}}).encode()
+ path.write_bytes(len(header).to_bytes(8, "little") + header + b"\x00\x00\x80\x3f")
+ return path
+
+
+def _hub_single_file_load(monkeypatch, tmp_path, file_bytes_writer, *, card_tag):
+ """``load_pipeline`` on an UNTRUSTED Hub repo + .safetensors name, with the download stubbed to a local file and
+ the repo's base_model card tag pointing back at the untrusted repo itself."""
+ checkpoint = tmp_path / "dit.safetensors"
+ file_bytes_writer(checkpoint)
+ downloads = []
+
+ def _fake_download(
+ self,
+ repo_id,
+ filename,
+ hf_token,
+ local_files_only = False,
+ ):
+ downloads.append((repo_id, filename))
+ return str(checkpoint)
+
+ monkeypatch.setattr(DiffusionBackend, "_resolve_gguf_path", _fake_download)
+ monkeypatch.setattr("core.inference.diffusion._hf_base_model", lambda repo_id, token: card_tag)
+ backend = DiffusionBackend()
+ status = backend.load_pipeline(
+ "evil-org/z-image-comfy",
+ gguf_filename = "split_files/diffusion_models/dit.safetensors",
+ model_kind = "single_file",
+ family_override = "z-image",
+ )
+ return status, downloads
+
+
+def test_untrusted_hub_safetensors_single_file_takes_config_only_from_the_family_base(
+ fake_runtime, tmp_path, monkeypatch
+):
+ """The per-file trust path: the one named file is fetched from the untrusted repo, but config, companions and the
+ pipeline assembly all come from the family's trusted base, even when the repo's card tag names itself."""
+ status, downloads = _hub_single_file_load(
+ monkeypatch, tmp_path, _write_min_safetensors, card_tag = "evil-org/z-image-comfy"
+ )
+ assert status["loaded"] is True
+ assert downloads == [("evil-org/z-image-comfy", "split_files/diffusion_models/dit.safetensors")]
+ assert _FakeTransformer.last["path"] == str(tmp_path / "dit.safetensors")
+ for value in (_FakeTransformer.last["config"], _FakePipeline.last["base"], status["base_repo"]):
+ assert "evil-org" not in str(value).lower()
+ # The family base, or its byte-identical unsloth mirror (the fetch-site swap).
+ assert _FakeTransformer.last["config"] in ("Tongyi-MAI/Z-Image-Turbo", "unsloth/Z-Image-Turbo")
+ assert status["base_repo"] == "Tongyi-MAI/Z-Image-Turbo"
+ assert "trust_remote_code" not in _FakeTransformer.last
+ assert "trust_remote_code" not in _FakePipeline.last
+ assert "original_config" not in _FakeTransformer.last
+
+
+def test_untrusted_hub_single_file_with_a_malformed_header_is_refused_before_any_loader(
+ fake_runtime, tmp_path, monkeypatch
+):
+ """A .safetensors NAME over pickle bytes never reaches from_single_file or the comfy scan."""
+ pickle_bytes = (
+ b"\x80\x04\x95" + b"\x00" * 64
+ ) # a pickle protocol-4 prefix, not a safetensors header
+
+ with pytest.raises(ValueError, match = "not a valid safetensors checkpoint"):
+ _hub_single_file_load(
+ monkeypatch, tmp_path, lambda p: p.write_bytes(pickle_bytes), card_tag = None
+ )
+ assert _FakeTransformer.last == {}
+ assert _FakePipeline.last == {}
+
+
+def test_untrusted_hub_single_file_header_is_checked_before_the_flux2_gguf_probe(
+ fake_runtime, tmp_path, monkeypatch
+):
+ """The FLUX.2 probe parses the file as GGUF, so an untrusted file must clear the safetensors check first."""
+ probed = []
+ monkeypatch.setattr(
+ "core.inference.diffusion.assert_flux2_gguf_matches_base",
+ lambda fam, base, path: probed.append(path),
+ )
+ with pytest.raises(ValueError, match = "not a valid safetensors checkpoint"):
+ _hub_single_file_load(
+ monkeypatch, tmp_path, lambda p: p.write_bytes(b"GGUF" + b"\x00" * 64), card_tag = None
+ )
+ assert probed == []
diff --git a/studio/backend/tests/test_hub_safetensors_single_file.py b/studio/backend/tests/test_hub_safetensors_single_file.py
new file mode 100644
index 00000000000..97e88103c98
--- /dev/null
+++ b/studio/backend/tests/test_hub_safetensors_single_file.py
@@ -0,0 +1,308 @@
+# 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 single ``.safetensors`` checkpoint loads from ANY Hub repo (ComfyUI repacks, Kijai, community fp8
+files), while everything that could unpickle or execute repo content stays repo-gated: other weight
+suffixes, full pipelines, and ``base_repo``."""
+
+import json
+import pickle
+import types
+
+import pytest
+
+from core.inference.diffusion import DiffusionBackend, _resolve_base_repo
+from core.inference.diffusion_families import detect_family
+from core.inference.diffusion_single_file_trust import (
+ assert_safetensors_file,
+ is_hub_safetensors_single_file,
+ single_file_load_allowed,
+)
+from core.inference.video import VideoBackend
+from core.inference.video_families import resolve_video_base_repo
+
+UNTRUSTED_IMAGE_REPO = "Comfy-Org/z_image_turbo"
+IMAGE_FILE = "split_files/diffusion_models/z_image_turbo_int8_convrot.safetensors"
+UNTRUSTED_VIDEO_REPO = "Comfy-Org/Wan_2.2_ComfyUI_Repackaged"
+VIDEO_FILE = "split_files/diffusion_models/wan2.2_ti2v_5B_fp16.safetensors"
+VIDEO_FAMILY = "wan2.2-ti2v-5b"
+PICKLE_NAMES = (
+ "split_files/diffusion_models/dit.pt",
+ "split_files/diffusion_models/dit.pth",
+ "split_files/diffusion_models/dit.bin",
+ "split_files/diffusion_models/dit.ckpt",
+ "split_files/diffusion_models/dit.pkl",
+ "dit.safetensors.pt",
+ "dit.npz",
+)
+
+
+def _write_safetensors(
+ path,
+ header = None,
+ data = b"\x00\x00\x80\x3f",
+):
+ header = (
+ header
+ if header is not None
+ else {"w": {"dtype": "F32", "shape": [1], "data_offsets": [0, 4]}}
+ )
+ raw = json.dumps(header).encode()
+ path.write_bytes(len(raw).to_bytes(8, "little") + raw + data)
+ return path
+
+
+# -- filename rule ---------------------------------------------------------------------------------
+
+
+ "name",
+ [IMAGE_FILE, VIDEO_FILE, "model.safetensors", "a/b/MODEL.safetensors"],
+)
+def test_safetensors_repo_relative_names_qualify(name):
+ assert is_hub_safetensors_single_file(name)
+
+
+ "name",
+ [
+ *PICKLE_NAMES,
+ None,
+ "",
+ ".safetensors",
+ "../outside.safetensors",
+ "a/../../outside.safetensors",
+ "/abs/path.safetensors",
+ "C:/x.safetensors",
+ "a\\b.safetensors",
+ " model.safetensors",
+ "a//b.safetensors",
+ "model.gguf",
+ # diffusers matches the suffix case-sensitively and sends anything else to torch.load.
+ "a/b/MODEL.SafeTensors",
+ "model.SAFETENSORS",
+ "model_index.json",
+ "pipeline.py",
+ ],
+)
+def test_other_names_do_not_qualify(name):
+ assert not is_hub_safetensors_single_file(name)
+
+
+def test_trust_decision_only_widens_single_file_kind():
+ assert single_file_load_allowed(False, "single_file", IMAGE_FILE)
+ assert not single_file_load_allowed(False, "pipeline", None)
+ assert not single_file_load_allowed(False, "pipeline", IMAGE_FILE)
+ assert not single_file_load_allowed(False, "single_file", "dit.pt")
+ # A trusted repo keeps every kind it had.
+ assert single_file_load_allowed(True, "pipeline", None)
+
+
+# -- image validator ---------------------------------------------------------------------------------
+
+
+def test_image_untrusted_repo_safetensors_single_file_is_accepted():
+ fam = DiffusionBackend().validate_load_request(UNTRUSTED_IMAGE_REPO, gguf_filename = IMAGE_FILE)
+ assert fam.name == "z-image"
+
+
[email protected]("name", PICKLE_NAMES)
+def test_image_untrusted_repo_pickle_formats_are_refused(name):
+ with pytest.raises(ValueError, match = "single .safetensors checkpoint"):
+ DiffusionBackend().validate_load_request(
+ UNTRUSTED_IMAGE_REPO, gguf_filename = name, model_kind = "single_file"
+ )
+
+
+def test_image_untrusted_repo_traversal_name_is_refused():
+ with pytest.raises(ValueError, match = "single .safetensors checkpoint"):
+ DiffusionBackend().validate_load_request(
+ UNTRUSTED_IMAGE_REPO, gguf_filename = "../../etc/x.safetensors"
+ )
+
+
+def test_image_untrusted_repo_pipeline_load_is_still_refused():
+ with pytest.raises(ValueError, match = "full pipelines"):
+ DiffusionBackend().validate_load_request(UNTRUSTED_IMAGE_REPO)
+ with pytest.raises(ValueError, match = "full pipelines"):
+ DiffusionBackend().validate_load_request(UNTRUSTED_IMAGE_REPO, model_kind = "pipeline")
+
+
+def test_image_untrusted_base_repo_is_still_refused():
+ """The base supplies configs and companions through from_pretrained, so it stays repo-gated even beside an admitted
+ single file (including the untrusted repo naming itself as base)."""
+ for base in ("evil/companions", UNTRUSTED_IMAGE_REPO):
+ with pytest.raises(ValueError, match = "base_repo"):
+ DiffusionBackend().validate_load_request(
+ UNTRUSTED_IMAGE_REPO, gguf_filename = IMAGE_FILE, base_repo = base
+ )
+
+
+def test_image_untrusted_card_tag_never_becomes_the_base(monkeypatch):
+ """No request passes the untrusted repo as config/base: its own base_model card tag is dropped for the family base."""
+ monkeypatch.setattr(
+ "core.inference.diffusion._hf_base_model", lambda repo_id, token: UNTRUSTED_IMAGE_REPO
+ )
+ fam = detect_family("z-image-turbo")
+ assert _resolve_base_repo(UNTRUSTED_IMAGE_REPO, None, fam, None) == fam.base_repo
+ assert fam.base_repo.lower() != UNTRUSTED_IMAGE_REPO.lower()
+
+
+# -- video validator ---------------------------------------------------------------------------------
+
+
+def test_video_untrusted_repo_safetensors_single_file_is_accepted():
+ fam = VideoBackend().validate_load_request(
+ UNTRUSTED_VIDEO_REPO, gguf_filename = VIDEO_FILE, family_override = VIDEO_FAMILY
+ )
+ assert fam.name == VIDEO_FAMILY
+ # Base resolution for a single-file pick never yields the pick's own repo.
+ assert resolve_video_base_repo(fam, None) == fam.base_repo
+ assert fam.base_repo.lower() != UNTRUSTED_VIDEO_REPO.lower()
+
+
[email protected]("name", PICKLE_NAMES)
+def test_video_untrusted_repo_pickle_formats_are_refused(name):
+ with pytest.raises(ValueError, match = "single .safetensors checkpoint"):
+ VideoBackend().validate_load_request(
+ UNTRUSTED_VIDEO_REPO,
+ gguf_filename = name,
+ model_kind = "single_file",
+ family_override = VIDEO_FAMILY,
+ )
+
+
+def test_video_untrusted_repo_pipeline_load_is_still_refused():
+ with pytest.raises(ValueError, match = "full pipelines"):
+ VideoBackend().validate_load_request(
+ UNTRUSTED_VIDEO_REPO, model_kind = "pipeline", family_override = VIDEO_FAMILY
+ )
+
+
+def test_video_untrusted_base_repo_is_still_refused():
+ for base in ("evil/companions", UNTRUSTED_VIDEO_REPO):
+ with pytest.raises(ValueError, match = "base_repo"):
+ VideoBackend().validate_load_request(
+ UNTRUSTED_VIDEO_REPO,
+ gguf_filename = VIDEO_FILE,
+ family_override = VIDEO_FAMILY,
+ base_repo = base,
+ )
+
+
+# -- header check ------------------------------------------------------------------------------------
+
+
+def test_header_check_accepts_a_real_safetensors_file(tmp_path):
+ safetensors_torch = pytest.importorskip("safetensors.torch")
+ torch = pytest.importorskip("torch")
+ path = tmp_path / "real.safetensors"
+ safetensors_torch.save_file({"a": torch.zeros(2, 3), "b": torch.ones(4)}, str(path))
+ assert_safetensors_file(path)
+ assert_safetensors_file(_write_safetensors(tmp_path / "min.safetensors"))
+
+
+def test_header_check_refuses_a_pickle_named_safetensors(tmp_path):
+ path = tmp_path / "evil.safetensors"
+ path.write_bytes(pickle.dumps({"w": [1.0]}))
+ with pytest.raises(ValueError, match = "not a valid safetensors checkpoint"):
+ assert_safetensors_file(path)
+
+
+def test_header_check_refuses_a_torch_save_named_safetensors(tmp_path):
+ torch = pytest.importorskip("torch")
+ path = tmp_path / "evil.safetensors"
+ torch.save({"w": torch.zeros(2)}, str(path))
+ with pytest.raises(ValueError, match = "not a valid safetensors checkpoint"):
+ assert_safetensors_file(path)
+
+
+ "writer",
+ [
+ lambda p: p.write_bytes(b""),
+ lambda p: p.write_bytes(b"\x01\x02"),
+ # Length prefix far past the end of the file.
+ lambda p: p.write_bytes((1 << 40).to_bytes(8, "little") + b"{}"),
+ # Not JSON.
+ lambda p: p.write_bytes((4).to_bytes(8, "little") + b"\xff\xfe\x00{"),
+ # JSON but not an object.
+ lambda p: p.write_bytes((2).to_bytes(8, "little") + b"[]"),
+ # Tensor data past the end of the data section.
+ lambda p: _write_safetensors(
+ p, {"w": {"dtype": "F32", "shape": [4], "data_offsets": [0, 16]}}
+ ),
+ # Missing dtype.
+ lambda p: _write_safetensors(p, {"w": {"shape": [1], "data_offsets": [0, 4]}}),
+ # Only metadata, no tensors.
+ lambda p: _write_safetensors(p, {"__metadata__": {"format": "pt"}}, data = b""),
+ ],
+)
+def test_header_check_refuses_malformed_files(tmp_path, writer):
+ path = tmp_path / "bad.safetensors"
+ writer(path)
+ with pytest.raises(ValueError, match = "safetensors checkpoint"):
+ assert_safetensors_file(path)
+
+
+# -- catalog classification ---------------------------------------------------------------------------
+
+
+def _repo_info(repo_id, names):
+ files = [types.SimpleNamespace(file_name = n) for n in names]
+ return types.SimpleNamespace(repo_id = repo_id, revisions = [types.SimpleNamespace(files = files)])
+
+
+def test_cached_untrusted_single_file_repo_is_listed_but_untrusted_pipeline_is_not(monkeypatch):
+ from hub.services.models import catalog_classification as cc
+
+ single = _repo_info(UNTRUSTED_IMAGE_REPO, [IMAGE_FILE])
+ monkeypatch.setattr(cc, "_repo_has_pipeline_index", lambda info, selected = None: False)
+ assert cc._untrusted_repo_single_files_loadable(single)
+ assert cc._cached_repo_task(single) == "text-to-image"
+
+ pickles_only = _repo_info(UNTRUSTED_IMAGE_REPO, ["split_files/diffusion_models/dit.ckpt"])
+ assert not cc._untrusted_repo_single_files_loadable(pickles_only)
+ assert cc._cached_repo_task(pickles_only) is None
+
+ # An untrusted PIPELINE repo still has no task: the loader refuses it.
+ monkeypatch.setattr(cc, "_repo_has_pipeline_index", lambda info, selected = None: True)
+ assert not cc._untrusted_repo_single_files_loadable(single)
+ assert cc._cached_repo_task(single) is None
+
+
+def test_an_oversized_comfy_quant_declaration_is_refused_without_reading_it(tmp_path, monkeypatch):
+ """A comfy_quant entry is small JSON; a file claiming a huge span is refused, not read into memory."""
+ import builtins
+
+ import core.inference.diffusion_comfy_quant as cq
+
+ span = 4 << 20
+ path = _write_safetensors(
+ tmp_path / "dit.safetensors",
+ header = {
+ "w": {"dtype": "F32", "shape": [1], "data_offsets": [0, 4]},
+ "w.comfy_quant": {"dtype": "U8", "shape": [span], "data_offsets": [4, 4 + span]},
+ },
+ data = b"\x00\x00\x80\x3f" + b"{" * span,
+ )
+ assert_safetensors_file(path)
+ reads = []
+ real_open = builtins.open
+
+ def _open(
+ file,
+ mode = "r",
+ *args,
+ **kwargs,
+ ):
+ handle = real_open(file, mode, *args, **kwargs)
+ if str(file) == str(path) and "b" in mode:
+ real_read = handle.read
+ handle.read = lambda n = -1: reads.append(n) or real_read(n)
+ return handle
+
+ monkeypatch.setattr(builtins, "open", _open)
+ scan = cq.scan_comfy_quant(str(path))
+ assert scan is not None and scan.problems
+ assert reads and max(reads) <= 1 << 20
diff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.py
index c3a30ccab66..b4d1b3a5b5a 100644
--- a/studio/backend/tests/test_video_backend.py
+++ b/studio/backend/tests/test_video_backend.py
@@ -13048,3 +13048,56 @@ def test_previewer_is_finished_when_the_render_fails_before_its_loop(fake_runtim
with pytest.raises(RuntimeError, match = "protect refused"):
backend.generate(prompt = "a fox", steps = 3, num_frames = 9, fps = 24)
assert all(p.finished for p in started)
+
+
+def test_h3_modular_single_file_from_an_untrusted_repo_checks_the_header_first(
+ fake_runtime, tmp_path, monkeypatch
+):
+ # The modular H3 branch returns before the generic single-file check, so it validates the header itself.
+ import pickle
+
+ bogus = tmp_path / "minimax_h3_fp8.safetensors"
+ bogus.write_bytes(pickle.dumps({"weights": 1}))
+ reached = []
+ diffusers = sys.modules["diffusers"]
+ monkeypatch.setattr(diffusers, "ModularPipeline", _FakeModularPipeline, raising = False)
+ monkeypatch.setattr(diffusers, "ComponentsManager", _FakeComponentsManager, raising = False)
+ monkeypatch.setattr(diffusers, "MiniMaxH3Transformer3DModel", _FakeTransformer, raising = False)
+ monkeypatch.setattr(
+ VideoBackend, "_resolve_checkpoint_path", lambda self, *args, **kwargs: bogus
+ )
+ monkeypatch.setattr(
+ VideoBackend,
+ "_load_h3_modular_pipeline",
+ lambda self, **kwargs: reached.append(kwargs["comfy_checkpoint"]),
+ )
+ with pytest.raises(ValueError, match = "not a valid safetensors checkpoint"):
+ VideoBackend().load_pipeline(
+ "someone/minimax-h3-repack",
+ gguf_filename = bogus.name,
+ family_override = "minimax-h3",
+ )
+ assert reached == []
+
+
+def test_untrusted_a14b_pair_checks_the_partner_files_header_too(
+ fake_runtime, tmp_path, monkeypatch
+):
+ # Both experts come from the untrusted repo, so the partner is validated like the picked file.
+ import json
+ import pickle
+
+ high = tmp_path / "wan2.2_t2v_high_noise_14B_fp8_scaled.safetensors"
+ low = tmp_path / "wan2.2_t2v_low_noise_14B_fp8_scaled.safetensors"
+ raw = json.dumps({"w": {"dtype": "F32", "shape": [1], "data_offsets": [0, 4]}}).encode()
+ high.write_bytes(len(raw).to_bytes(8, "little") + raw + b"\x00\x00\x80\x3f")
+ low.write_bytes(pickle.dumps({"weights": 1}))
+ monkeypatch.setattr(VideoBackend, "_resolve_checkpoint_path", lambda self, *a, **k: high)
+ monkeypatch.setattr(VideoBackend, "_resolve_moe_partner_path", lambda self, *a, **k: low)
+ with pytest.raises(ValueError, match = "not a valid safetensors checkpoint"):
+ VideoBackend().load_pipeline(
+ "someone/wan-a14b-repack",
+ gguf_filename = high.name,
+ base_repo = "Wan-AI/Wan2.2-T2V-A14B-Diffusers",
+ family_override = "wan2.2-t2v-a14b",
+ )
diff --git a/studio/frontend/src/features/images/api.ts b/studio/frontend/src/features/images/api.ts
index 1b621b4cff6..2eab812ff50 100644
--- a/studio/frontend/src/features/images/api.ts
+++ b/studio/frontend/src/features/images/api.ts
@@ -120,7 +120,8 @@ export interface DiffusionLoadRequest {
display_repo_id?: string;
// Optional now: required for the gguf / single_file kinds, omitted for a full pipeline loaded via from_pretrained.
gguf_filename?: string;
- // How to load the model (omit to auto-detect from gguf_filename). Non-GGUF kinds are restricted to unsloth/* repos.
+ // How to load the model (omit to auto-detect from gguf_filename). A single_file .safetensors loads from any repo;
+ // pipeline loads are restricted to unsloth/* repos, the official bases, or a local path.
model_kind?: "gguf" | "single_file" | "pipeline";
base_repo?: string;
family_override?: string;
diff --git a/studio/frontend/src/features/video/api.ts b/studio/frontend/src/features/video/api.ts
index 35623c11491..31e6f2ba631 100644
--- a/studio/frontend/src/features/video/api.ts
+++ b/studio/frontend/src/features/video/api.ts
@@ -136,8 +136,8 @@ export interface VideoLoadRequest {
// from_pretrained.
gguf_filename?: string;
// How to load the model (omit to auto-detect from gguf_filename): "gguf", "single_file"
- // (safetensors transformer) or "pipeline". Non-GGUF kinds are restricted to unsloth/* or
- // family bases.
+ // (safetensors transformer) or "pipeline". A single_file .safetensors loads from any repo;
+ // pipeline loads are restricted to unsloth/* or family bases.
model_kind?: "gguf" | "single_file" | "pipeline";
base_repo?: string;
family_override?: string;