"""VFS storage helpers.""" from __future__ import annotations import shutil from dataclasses import dataclass from datetime import datetime, timezone from pathlib import Path from typing import Any from backend.dto.common import ApiError, ErrorCode from core.config_service import ConfigService, ImageStudioConfig from core.runtime_paths import ( EXTERNAL_ROOTS_ENV_VAR, external_storage_roots_allowed, resolve_data_path, ) @dataclass(frozen=True) class VfsEntry: root: str uri_prefix: str exists: bool writable: bool bytes: int def to_dict(self) -> dict[str, Any]: return { "root": self.root, "uri_prefix": self.uri_prefix, "exists": self.exists, "writable": self.writable, "bytes": self.bytes, } class VfsStorage: def __init__(self, config_service: ConfigService | None = None): self.config_service = config_service or ConfigService() def status(self) -> dict[str, Any]: roots = [self._entry(root, path) for root, path in self._root_paths().items()] return { "roots": [entry.to_dict() for entry in roots], "total_bytes": sum(entry.bytes for entry in roots), } def migration_plan( self, source_uri: str, target_uri: str, *, dry_run: bool = True, allow_overwrite: bool = False, ) -> dict[str, Any]: source_path = self.resolve_uri(source_uri) target_path = self.resolve_uri(target_uri) if not source_path.exists(): raise ApiError(ErrorCode.MEDIA_NOT_FOUND, "source media not found", {"uri": source_uri}) files, total_bytes = _path_file_stats(source_path) will_overwrite = target_path.exists() if not dry_run: # ``will_overwrite`` used to be reported and then ignored, so a # non-dry-run migrate silently clobbered whatever sat at the target # (``shutil.copy2`` overwrites without asking). Require the caller # to acknowledge the overwrite explicitly. if will_overwrite and not allow_overwrite: raise ApiError( ErrorCode.VALIDATION_FAILED, "target already exists; retry with allow_overwrite=true to replace it", {"target_uri": target_uri, "will_overwrite": True}, ) _copy_path(source_path, target_path) return { "dry_run": dry_run, "status": "planned" if dry_run else "completed", "source_uri": source_uri, "target_uri": target_uri, "files": files, "bytes": total_bytes, "will_overwrite": will_overwrite, "execution_enabled": True, } def index_files(self, *, root: str | None = None, limit: int = 500) -> dict[str, Any]: roots = self._root_paths() if root and root not in roots: raise ApiError(ErrorCode.MEDIA_NOT_FOUND, "unknown storage root", {"root": root}) selected_roots = [root] if root else sorted(roots) normalized_limit = min(max(int(limit or 500), 1), 5000) items: list[dict[str, Any]] = [] total = 0 for root_name in selected_roots: root_path = resolve_data_path(roots[root_name]).resolve() if not root_path.exists(): continue for path in sorted(root_path.rglob("*")): if not path.is_file(): continue total += 1 if len(items) >= normalized_limit: continue relative = path.relative_to(root_path).as_posix() items.append( { "root": root_name, "uri": f"storage://{root_name}/{relative}", "bytes": path.stat().st_size, "modified_at": datetime.fromtimestamp(path.stat().st_mtime, timezone.utc).isoformat(), } ) return { "root": root, "limit": normalized_limit, "total": total, "truncated": total > len(items), "items": items, } def resolve_uri(self, uri: str) -> Path: root, relative = self.split_uri(uri) root_path = self._root_paths().get(root) if root_path is None: raise ApiError(ErrorCode.MEDIA_NOT_FOUND, "unknown storage root", {"uri": uri, "root": root}) resolved_root = resolve_data_path(root_path).resolve() resolved_path = (resolved_root / relative).resolve() if resolved_path != resolved_root and resolved_root not in resolved_path.parents: raise ApiError(ErrorCode.FORBIDDEN, "storage uri escapes its root", {"uri": uri}) return resolved_path def ensure_file(self, uri: str) -> Path: path = self.resolve_uri(uri) if not path.exists() or not path.is_file(): raise ApiError(ErrorCode.MEDIA_NOT_FOUND, "media file not found", {"uri": uri}) return path def split_uri(self, uri: str) -> tuple[str, Path]: if not uri.startswith("storage://"): raise ApiError(ErrorCode.VALIDATION_FAILED, "uri must use storage://", {"field": "uri"}) rest = uri[len("storage://") :] if "/" not in rest: raise ApiError(ErrorCode.VALIDATION_FAILED, "storage uri must include a root and path", {"uri": uri}) root, relative = rest.split("/", 1) if not root or not relative: raise ApiError(ErrorCode.VALIDATION_FAILED, "storage uri must include a root and path", {"uri": uri}) relative_path = Path(relative) if relative_path.is_absolute() or ".." in relative_path.parts: raise ApiError(ErrorCode.FORBIDDEN, "storage uri contains an unsafe path", {"uri": uri}) return root, relative_path def _entry(self, root: str, path: str) -> VfsEntry: resolved = resolve_data_path(path) return VfsEntry( root=root, uri_prefix=f"storage://{root}/", exists=resolved.exists(), writable=_is_writable(resolved), bytes=_directory_size(resolved), ) def _root_paths(self) -> dict[str, str]: config = self.config_service.load() roots = _storage_roots(config) assert_storage_roots_contained(roots) return roots def assert_storage_roots_contained(roots: dict[str, str]) -> None: """Refuse storage roots that are too broad to be a sandbox boundary. ``VfsStorage.resolve_uri`` guarantees a URI cannot escape *its own root* — which is worth nothing when the root itself is ``/`` or ``C:\\``. Pointing a root at a filesystem anchor or a system directory turns ``media/index`` and ``media/sign`` into a host-wide file browser. Deliberately narrower than "must live under the data root": mounting storage on a dedicated external volume is a legitimate deployment (and how the test-suite isolates fixtures). The write path (``SettingsService.validate``) is where containment is enforced, because that is the attacker-reachable surface; this is defence in depth against a config that arrived some other way. """ if external_storage_roots_allowed(): return unsafe = sorted(name for name, path in roots.items() if _is_overbroad_root(path)) if unsafe: raise ApiError( ErrorCode.FORBIDDEN, "storage root escapes the runtime data root", { "roots": unsafe, "hint": ( "point the root at a dedicated directory, or set " f"{EXTERNAL_ROOTS_ENV_VAR}=1 to allow an external mount" ), }, ) # Directories that can never be a dedicated media root. Matching is done on the # resolved path so ``data/../..`` style traversal collapses first. _SYSTEM_ROOTS = ( "/etc", "/root", "/boot", "/proc", "/sys", "/dev", "/var", "/usr", "/bin", "/sbin", "c:/windows", "c:/program files", "c:/program files (x86)", ) def _is_overbroad_root(path: str) -> bool: try: resolved = resolve_data_path(path).resolve() except OSError: return False # A filesystem anchor ("/", "C:\\") is its own parent. if resolved.parent == resolved: return True normalized = resolved.as_posix().rstrip("/").lower() return any( normalized == system or normalized.startswith(f"{system}/") for system in _SYSTEM_ROOTS ) def _storage_roots(config: ImageStudioConfig) -> dict[str, str]: return { "images": config.storage.images_path, "thumbnails": config.storage.thumbnails_path, "materials": config.storage.materials_path, "advanced_materials": config.storage.advanced_materials_path, "styles": config.storage.styles_path, "archives": config.storage.archives_path, "temp": config.storage.temp_path, } def _directory_size(path: Path) -> int: if not path.exists(): return 0 total = 0 for child in path.rglob("*"): if child.is_file(): total += child.stat().st_size return total def _path_file_stats(path: Path) -> tuple[int, int]: if path.is_file(): return 1, path.stat().st_size if path.is_dir(): files = 0 total = 0 for child in path.rglob("*"): if child.is_file(): files += 1 total += child.stat().st_size return files, total return 0, 0 def _copy_path(source_path: Path, target_path: Path) -> None: if source_path.is_file(): target_path.parent.mkdir(parents=True, exist_ok=True) shutil.copy2(source_path, target_path) return source_root = source_path.resolve() target_root = target_path.resolve() if target_root == source_root or source_root in target_root.parents: raise ApiError(ErrorCode.FORBIDDEN, "target path cannot be inside source directory") target_root.mkdir(parents=True, exist_ok=True) for child in source_root.rglob("*"): if not child.is_file(): continue relative = child.relative_to(source_root) destination = target_root / relative destination.parent.mkdir(parents=True, exist_ok=True) shutil.copy2(child, destination) def _is_writable(path: Path) -> bool: target = path if path.exists() else path.parent return target.exists() and target.is_dir()