From 082af7546a1007e13846ae36a76eceeb71c56ec3 Mon Sep 17 00:00:00 2001 From: DeadlyVirusIn Date: Fri, 13 Nov 2026 16:51:32 -0500 Subject: [PATCH 1/5] fix(passport): pin the export output directory so a swap cannot redirect the write (R4-F1) export -o validated the path, then created the temp file and published it by path, leaving a window in which the directory or an ancestor could be swapped (for example for a link to a network share). snapstudio_core/safe_publish.py now opens the directory once and publishes through that pin: dir_fd-relative create + no-replace link on POSIX (real path checked from the descriptor); on Windows a directory handle without FILE_SHARE_DELETE, final path read from the handle and checked, then create + no-replace rename. Tests: tests/passport/test_export_publication.py swaps the directory at the moment of first file creation and fails on the previous write path (passport lands in the swapped-in directory); the legacy appears-before-publication test now targets the new primitive on each platform. Full backend suite: 5241 passed expected (one test updated), run before the test edit 5240 passed + that test. Only the Windows pin was exercised locally; POSIX is covered by Linux CI. Co-Authored-By: Claude Sonnet 5.5 --- backend/snapstudio_core/passport_cli.py | 36 ++--- backend/snapstudio_core/safe_publish.py | 145 ++++++++++++++++++ .../tests/passport/test_export_publication.py | 129 ++++++++++++++++ backend/tests/test_review_fixes.py | 24 ++- docs/internal/PASSPORT.md | 12 +- 5 files changed, 303 insertions(+), 43 deletions(-) create mode 100644 backend/snapstudio_core/safe_publish.py create mode 100644 backend/tests/passport/test_export_publication.py diff --git a/backend/snapstudio_core/passport_cli.py b/backend/snapstudio_core/passport_cli.py index b8cc9178..0967f6d9 100644 --- a/backend/snapstudio_core/passport_cli.py +++ b/backend/snapstudio_core/passport_cli.py @@ -13,24 +13,24 @@ Nothing here writes next to or over an input: `export -o` refuses an existing file and any path that is one of the inputs. -Known limit (accepted for the unmerged development branches): path validation and the filesystem -operations that follow it are separate steps. Another process or principal able to modify the output -directory, or any of its ancestors, after validation could redirect `export -o` (for example by -swapping the directory for a link to a network share). Use an output directory whose ancestors other -actors cannot modify. The UNC/device/link refusals and the no-overwrite rule are best-effort checks, -not a filesystem sandbox and not an absolute no-network guarantee. See docs/internal/PASSPORT.md. +Publication: `export -o` pins the output directory once (a held descriptor on POSIX; a handle that +forbids rename/delete on Windows) and writes through that pin (snapstudio_core.safe_publish), so swapping the +directory or an ancestor after the check cannot redirect the write. It is still not a filesystem +sandbox: someone who can already write inside the pinned directory can create or remove entries there, +and the UNC/device/link refusals are checks on the pinned path, not an absolute no-network guarantee. +See docs/internal/PASSPORT.md. """ from __future__ import annotations import json import os -import tempfile from functools import wraps from typing import Any import click from snapstudio_core import localpath +from snapstudio_core.safe_publish import UnsafeOutput, publish_new_file from snapstudio_core.passport import build_passport, import_passport, verify_passport from snapstudio_core.passport.model import decode_passport @@ -140,29 +140,13 @@ def export_cmd(original, prepared, sliced, recipes_file, mappings_file, out): if os.path.exists(target): _error("output_exists", "The output file already exists.") try: - fd, tmp = tempfile.mkstemp(dir=os.path.dirname(target) or ".", suffix=".tmp") - except OSError: - _error("write_failed", "The passport could not be written.") - try: - with os.fdopen(fd, "w", encoding="utf-8") as handle: - json.dump(document, handle, indent=2) - try: - os.link(tmp, target) # fails if the destination appeared meanwhile - except FileExistsError: - raise - except OSError: - if os.name != "nt": - raise # POSIX rename would replace; refuse rather than risk it - os.rename(tmp, target) # Windows rename is atomic and refuses an existing file + publish_new_file(target, json.dumps(document, indent=2).encode("utf-8")) except FileExistsError: _error("output_exists", "The output file already exists.") + except UnsafeOutput: + _error("bad_output", "The output directory could not be verified as a local folder.") except OSError: _error("write_failed", "The passport could not be written.") - finally: - try: - os.remove(tmp) # the passport is already published or refused - except OSError: - pass written = os.path.basename(target) _emit({"ok": True, "passport_id": document["passport_id"], "written": written, "passport": document, "diagnostics": [d.to_dict() for d in built.diagnostics], "losses": document["losses"]}, 0) diff --git a/backend/snapstudio_core/safe_publish.py b/backend/snapstudio_core/safe_publish.py new file mode 100644 index 00000000..d259863a --- /dev/null +++ b/backend/snapstudio_core/safe_publish.py @@ -0,0 +1,145 @@ +"""Publish a new local file without a validate-then-write race on the output directory. + +`publish_new_file(target, data)` writes `data` to `target` only if `target` does not exist, and +never replaces anything. The directory that will hold the file is opened ONCE ("pinned") and every +later operation goes through that pin, so a later swap of the directory, or of any ancestor, cannot +redirect the write: + +* POSIX: the directory is held as a file descriptor and the temporary file, the no-replace link and + the cleanup are all `dir_fd`-relative. The pinned directory's real path is checked for + network/device locations after the pin, from the descriptor (`/proc/self/fd`, or `F_GETPATH` on macOS). +* Windows: the directory is opened with a share mode that omits FILE_SHARE_DELETE, so the directory + and its ancestors cannot be renamed, replaced or removed while the handle is held. The final path + is read from the handle and checked for network/device locations; the file operations then use that + final path. + +Remaining limits (stated, not hidden): this is not a sandbox. Anyone who can already write inside the +pinned directory can still create or remove entries there, and a platform that can neither report the +pinned directory's path nor pin it is refused (`UnsafeOutput`) rather than written best-effort. +""" +from __future__ import annotations + +import os +import secrets +import sys + +from snapstudio_core import localpath + + +class UnsafeOutput(Exception): + """The output location could not be pinned and verified as a local directory.""" + + +def _after_pin() -> None: + """Seam for tests: runs after the directory is pinned and verified, before any file is created.""" + + +def _check_name(name: str) -> None: + if not name or name in (".", "..") or "\x00" in name or any(sep in name for sep in ("/", "\\")): + raise UnsafeOutput("the output must be a plain file name") + + +def _tmp_name(name: str) -> str: + return f".{name}.{secrets.token_hex(6)}.tmp" + + +def publish_new_file(target: str, data: bytes, mode: int = 0o600) -> None: + """Create `target` with `data`; FileExistsError if it exists; UnsafeOutput if not pinnable/local.""" + absolute = os.path.abspath(target) + parent, name = os.path.split(absolute) + _check_name(name) + if sys.platform == "win32": + _publish_windows(parent, name, data) + else: + _publish_posix(parent, name, data, mode) + + +# ---------------------------------------------------------------- POSIX + +def _pinned_path_posix(dfd: int) -> str: + if sys.platform.startswith("linux"): + return os.path.realpath(f"/proc/self/fd/{dfd}") + try: + import fcntl + raw = fcntl.fcntl(dfd, getattr(fcntl, "F_GETPATH"), b"\0" * 1024) + return os.fsdecode(raw.split(b"\0", 1)[0]) + except (ImportError, AttributeError, OSError): + raise UnsafeOutput("this platform cannot report the output directory's real path") from None + + +def _publish_posix(parent: str, name: str, data: bytes, mode: int) -> None: + flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_CLOEXEC", 0) + try: + dfd = os.open(parent, flags) + except OSError as error: + raise UnsafeOutput("the output directory could not be opened") from error + tmp = None + try: + real = _pinned_path_posix(dfd) + if not real or localpath._reaches_network(real): + raise UnsafeOutput("the output directory is not a local directory") + _after_pin() + tmp = _tmp_name(name) + fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), mode, dir_fd=dfd) + with os.fdopen(fd, "wb") as handle: + handle.write(data) + os.link(tmp, name, src_dir_fd=dfd, dst_dir_fd=dfd, follow_symlinks=False) # refuses an existing name + finally: + if tmp is not None: + try: + os.unlink(tmp, dir_fd=dfd) + except OSError: + pass + os.close(dfd) + + +# ---------------------------------------------------------------- Windows + +def _publish_windows(parent: str, name: str, data: bytes) -> None: + import ctypes + from ctypes import wintypes + + kernel32 = ctypes.WinDLL("kernel32", use_last_error=True) + kernel32.CreateFileW.argtypes = [wintypes.LPCWSTR, wintypes.DWORD, wintypes.DWORD, wintypes.LPVOID, + wintypes.DWORD, wintypes.DWORD, wintypes.HANDLE] + kernel32.CreateFileW.restype = wintypes.HANDLE + kernel32.GetFinalPathNameByHandleW.argtypes = [wintypes.HANDLE, wintypes.LPWSTR, wintypes.DWORD, wintypes.DWORD] + kernel32.GetFinalPathNameByHandleW.restype = wintypes.DWORD + kernel32.CloseHandle.argtypes = [wintypes.HANDLE] + + FILE_LIST_DIRECTORY = 0x0001 + SHARE_READ_WRITE = 0x1 | 0x2 # deliberately NOT FILE_SHARE_DELETE (0x4) + OPEN_EXISTING = 3 + FILE_FLAG_BACKUP_SEMANTICS = 0x02000000 + invalid = wintypes.HANDLE(-1).value + + handle = kernel32.CreateFileW(parent, FILE_LIST_DIRECTORY, SHARE_READ_WRITE, None, OPEN_EXISTING, + FILE_FLAG_BACKUP_SEMANTICS, None) + if handle in (None, invalid): + raise UnsafeOutput("the output directory could not be opened") + try: + buffer = ctypes.create_unicode_buffer(32768) + length = kernel32.GetFinalPathNameByHandleW(handle, buffer, len(buffer), 0) + if not length or length >= len(buffer): + raise UnsafeOutput("the output directory's real path could not be read") + real = buffer.value + if real.upper().startswith("\\\\?\\UNC\\"): + raise UnsafeOutput("the output directory is not a local directory") + if real.startswith("\\\\?\\") and len(real) > 6 and real[5] == ":": + real = real[4:] # \\?\C:\dir -> C:\dir (a plain local drive path) + if localpath._reaches_network(real): + raise UnsafeOutput("the output directory is not a local directory") + _after_pin() + destination = os.path.join(real, name) + tmp = os.path.join(real, _tmp_name(name)) + try: + with open(tmp, "xb") as out: + out.write(data) + os.rename(tmp, destination) # atomic and refuses an existing name on Windows + finally: + try: + os.remove(tmp) + except OSError: + pass + finally: + kernel32.CloseHandle(handle) diff --git a/backend/tests/passport/test_export_publication.py b/backend/tests/passport/test_export_publication.py new file mode 100644 index 00000000..535aaa74 --- /dev/null +++ b/backend/tests/passport/test_export_publication.py @@ -0,0 +1,129 @@ +"""R4-F1: `passport export -o` must publish into the directory it validated, even if that directory +(or an ancestor) is swapped between the check and the write. Evidence label: fixture-tested. + +The swap is simulated deterministically. Both the old write path (`tempfile.mkstemp` in the validated +directory) and the new one (`safe_publish._after_pin`, after the directory is pinned) trigger it exactly +once, immediately before the first file is created. The directory swap is a rename of the validated +directory plus a rename of a decoy into its place; on Windows the new code's pinned handle makes the +first rename fail, which is the protection under test. +""" +from __future__ import annotations + +import json +import os +import tempfile + +import pytest +from click.testing import CliRunner + +from snapstudio_core import passport_cli + +try: + from snapstudio_core import safe_publish +except ImportError: # the pre-fix tree: let the behavioural assertion fail instead + safe_publish = None + + +def _run(*args): + return CliRunner().invoke(passport_cli.passport, list(args)) + + +@pytest.fixture +def layout(tmp_path): + victim = tmp_path / "victim" + decoy = tmp_path / "decoy" + victim.mkdir() + decoy.mkdir() + (victim / "orig.marker").write_text("victim") + (decoy / "decoy.marker").write_text("decoy") + source = tmp_path / "part.3mf" + source.write_bytes(b"synthetic original") + return tmp_path, victim, decoy, source + + +def _install_swap(monkeypatch, victim, decoy): + moved = victim.with_name("victim_moved") + state = {"armed": True, "swapped": False} + + def swap(): + if not state["armed"]: + return + state["armed"] = False + try: + os.rename(victim, moved) + os.rename(decoy, victim) + state["swapped"] = True + except OSError: + pass # a pinned directory refuses to be renamed (Windows) + + real_mkstemp = tempfile.mkstemp + + def mkstemp(*args, **kwargs): + swap() + return real_mkstemp(*args, **kwargs) + + monkeypatch.setattr(tempfile, "mkstemp", mkstemp) + if safe_publish is not None: + monkeypatch.setattr(safe_publish, "_after_pin", swap) + return state, moved + + +def test_a_directory_swapped_after_validation_does_not_redirect_the_passport(layout, monkeypatch): + tmp_path, victim, decoy, source = layout + state, moved = _install_swap(monkeypatch, victim, decoy) + out = victim / "job.passport.json" + + result = _run("export", "--original", str(source), "-o", str(out)) + + assert result.exit_code == 0, result.output + assert json.loads(result.output)["written"] == "job.passport.json" + holders = [d for d in (victim, moved) if (d / "job.passport.json").exists()] + assert len(holders) == 1 + assert (holders[0] / "orig.marker").exists(), "the passport landed in the swapped-in directory" + assert not [p for p in (victim, moved) if (p / "decoy.marker").exists() and (p / "job.passport.json").exists()] + assert not list(holders[0].glob("*.tmp")) and not list(holders[0].glob(".*.tmp")) + + +def test_export_writes_a_new_file_and_refuses_an_existing_one(tmp_path): + source = tmp_path / "part.3mf" + source.write_bytes(b"x") + out = tmp_path / "p.json" + first = _run("export", "--original", str(source), "-o", str(out)) + assert first.exit_code == 0 and json.loads(out.read_text(encoding="utf-8"))["passport_id"] + before = out.read_bytes() + second = _run("export", "--original", str(source), "-o", str(out)) + assert second.exit_code == 1 and json.loads(second.output)["error"]["code"] == "output_exists" + assert out.read_bytes() == before + assert sorted(p.name for p in tmp_path.iterdir()) == ["p.json", "part.3mf"] + + +@pytest.mark.skipif(safe_publish is None, reason="needs safe_publish") +def test_publish_new_file_never_replaces_and_leaves_no_temporary(tmp_path): + target = tmp_path / "a.json" + safe_publish.publish_new_file(str(target), b"one") + with pytest.raises(FileExistsError): + safe_publish.publish_new_file(str(target), b"two") + assert target.read_bytes() == b"one" + assert [p.name for p in tmp_path.iterdir()] == ["a.json"] + + +@pytest.mark.skipif(safe_publish is None, reason="needs safe_publish") +@pytest.mark.parametrize("name", ["", "..", "a/b", "a\\b"]) +def test_publish_refuses_a_name_that_is_not_a_plain_file_name(tmp_path, name): + with pytest.raises(safe_publish.UnsafeOutput): + safe_publish._check_name(name) + + +@pytest.mark.skipif(safe_publish is None, reason="needs safe_publish") +def test_a_directory_that_resolves_to_a_network_location_is_refused(tmp_path, monkeypatch): + monkeypatch.setattr(safe_publish.localpath, "_reaches_network", lambda path, depth=0: True) + with pytest.raises(safe_publish.UnsafeOutput): + safe_publish.publish_new_file(str(tmp_path / "a.json"), b"x") + assert list(tmp_path.iterdir()) == [] + + +@pytest.mark.skipif(safe_publish is None, reason="needs safe_publish") +def test_a_missing_output_directory_is_refused_not_created(tmp_path): + with pytest.raises(safe_publish.UnsafeOutput): + safe_publish.publish_new_file(str(tmp_path / "nope" / "a.json"), b"x") + assert not (tmp_path / "nope").exists() diff --git a/backend/tests/test_review_fixes.py b/backend/tests/test_review_fixes.py index 47e10df4..83022b22 100644 --- a/backend/tests/test_review_fixes.py +++ b/backend/tests/test_review_fixes.py @@ -120,15 +120,23 @@ def test_export_refuses_a_destination_that_appears_before_publication(tmp_path, original = tmp_path / "a.3mf" original.write_bytes(b"synthetic") target = tmp_path / "out.passport.json" - real_link = os.link - - def racing_link(src, dst, *a, **k): - Path(dst).write_text("someone else's file", encoding="utf-8") # appears after validation - return real_link(src, dst, *a, **k) - - monkeypatch.setattr(os, "link", racing_link) + # the publishing primitive is a no-replace link on POSIX (dir_fd-relative) and a rename on Windows + name = "rename" if os.name == "nt" else "link" + real = getattr(os, name) + + def racing(src, dst, *a, **k): + dir_fd = k.get("dst_dir_fd") + if dir_fd is None: + Path(dst).write_text("someone else's file", encoding="utf-8") # appears after validation + else: + fd = os.open(dst, os.O_WRONLY | os.O_CREAT, 0o600, dir_fd=dir_fd) + os.write(fd, "someone else's file".encode("utf-8")) + os.close(fd) + return real(src, dst, *a, **k) + + monkeypatch.setattr(os, name, racing) result = CliRunner().invoke(passport_cli.passport, ["export", "--original", str(original), "-o", str(target)]) assert result.exit_code == 1 assert json.loads(result.output)["error"]["code"] == "output_exists" assert target.read_text(encoding="utf-8") == "someone else's file" - assert not list(tmp_path.glob("*.tmp")) + assert not list(tmp_path.glob("*.tmp")) and not list(tmp_path.glob(".*.tmp")) diff --git a/docs/internal/PASSPORT.md b/docs/internal/PASSPORT.md index 601b9d54..a0fdff13 100644 --- a/docs/internal/PASSPORT.md +++ b/docs/internal/PASSPORT.md @@ -4,8 +4,7 @@ Evidence label: **fixture-tested**. The passport model, import, verify and comma below are exercised by `backend/tests/passport/` with synthetic files and a synthetic command-line client. The path-refusal and output-file behaviour is exercised in `backend/tests/test_review_fixes*.py` and `backend/tests/test_localpath_links.py`; the refusal of a folder or trailing-separator `-o` has no -test yet. The directory-swap race described under "Path checks are not a sandbox" was not reproduced -or tested. No real third-party program, printer, slicer run or project file was used. +test yet. The `export -o` directory-swap race (R4-F1) is closed for the output side by pinning the directory (`snapstudio_core/safe_publish.py`); `backend/tests/passport/test_export_publication.py` reproduces the swap and fails on the previous write path. Only the Windows pin was exercised locally; the POSIX descriptor path is exercised by Linux CI. No real third-party program, printer, slicer run or project file was used. ## What a passport is @@ -86,12 +85,7 @@ through the real `u1convert` entry point. Studio refuses, up front, a UNC or dev style, a symlink or junction whose target is one of those, a folder given as the output, and an existing output file. It never overwrites an input or an existing file. -Those checks are separate from the file operations that follow them. Validation reads the path; the -open, `mkstemp`, link or rename happens afterwards. Another process or principal that can modify the -output directory, or any ancestor of it, between the two steps can redirect that operation, for -example by swapping the directory for a link to a network share. Studio does not guard against that. -Use an output directory whose ancestors other users and programs cannot modify. The checks reduce +For `export -o` the output directory is pinned once and the passport is created and published through that pin (a held directory descriptor on POSIX; a handle that forbids rename and delete of the directory and its ancestors on Windows), so swapping the directory or an ancestor after the check cannot redirect the write. A platform that cannot pin and report the real path is refused. Input paths are still checked and then opened separately (see below). The checks reduce accidents; they are not a filesystem sandbox and not a guarantee that no network location is ever -reached. The known case is a race on `export -o` (CLI only; the HTTP routes never write a passport). -Input paths are read-only opens of regular files and are checked the same way, with the same +reached. Input paths are read-only opens of regular files and are checked the same way, with the same validation-versus-use gap; no separate input-path exploit has been demonstrated. From c824bf0c8b8ba47fe3fb2bd1b96890856f333315 Mon Sep 17 00:00:00 2001 From: DeadlyVirusIn Date: Fri, 13 Nov 2026 17:48:49 -0500 Subject: [PATCH 2/5] fix(passport): close Windows in-place junction and Linux /proc gaps in export publication (R4-F1 review) Sol BLOCK on 082af75: (HIGH) an actor with write access to an empty pinned directory could install a junction in place; (MEDIUM) unresolved /proc/self/fd paths passed the network check; (MEDIUM) temp names grew with the destination name and backslashes were rejected on POSIX. Windows now creates the final name exclusively with sharing off, re-checks the pinned directory for a reparse point, verifies the file handle's own final path equals the verified directory plus name, and discards the empty file on a mismatch. Linux reads the descriptor path with readlink and fails closed. Temp names are bounded and independent of the destination; separator rejection is platform-aware. Tests: in-place junction and ancestor-swap regressions (fail on the old write path); obsolete no-hard-link rename test removed (path gone), covered by the retargeted destination-appears test. Verified: tests/passport + review-fix tests 82 passed on Windows; full backend 5242 passed before removing the obsolete test. Co-Authored-By: Claude Sonnet 5.5 --- backend/snapstudio_core/safe_publish.py | 132 ++++++++++++++---- .../tests/passport/test_export_publication.py | 104 ++++++++++++++ backend/tests/test_review_fixes.py | 29 ++-- backend/tests/test_review_fixes_r3.py | 32 ----- docs/internal/PASSPORT.md | 4 +- 5 files changed, 225 insertions(+), 76 deletions(-) diff --git a/backend/snapstudio_core/safe_publish.py b/backend/snapstudio_core/safe_publish.py index d259863a..41d7085f 100644 --- a/backend/snapstudio_core/safe_publish.py +++ b/backend/snapstudio_core/safe_publish.py @@ -10,8 +10,10 @@ network/device locations after the pin, from the descriptor (`/proc/self/fd`, or `F_GETPATH` on macOS). * Windows: the directory is opened with a share mode that omits FILE_SHARE_DELETE, so the directory and its ancestors cannot be renamed, replaced or removed while the handle is held. The final path - is read from the handle and checked for network/device locations; the file operations then use that - final path. + is read from the handle and checked for network/device locations. A junction cannot be renamed in, but + it can be set in place on an empty directory, so the final name is created exclusively with sharing + off, and the file HANDLE's own final path must equal the verified directory plus the name; a mismatch + discards the empty file before any content is written. Remaining limits (stated, not hidden): this is not a sandbox. Anyone who can already write inside the pinned directory can still create or remove entries there, and a platform that can neither report the @@ -35,12 +37,14 @@ def _after_pin() -> None: def _check_name(name: str) -> None: - if not name or name in (".", "..") or "\x00" in name or any(sep in name for sep in ("/", "\\")): + separators = ("/", "\\") if sys.platform == "win32" else ("/",) + if not name or name in (".", "..") or "\x00" in name or any(sep in name for sep in separators): raise UnsafeOutput("the output must be a plain file name") -def _tmp_name(name: str) -> str: - return f".{name}.{secrets.token_hex(6)}.tmp" +def _tmp_name() -> str: + """A bounded temporary name that does not depend on the destination name (NAME_MAX safe).""" + return f".snapstudio-{secrets.token_hex(8)}.tmp" def publish_new_file(target: str, data: bytes, mode: int = 0o600) -> None: @@ -58,7 +62,13 @@ def publish_new_file(target: str, data: bytes, mode: int = 0o600) -> None: def _pinned_path_posix(dfd: int) -> str: if sys.platform.startswith("linux"): - return os.path.realpath(f"/proc/self/fd/{dfd}") + try: + resolved = os.readlink(f"/proc/self/fd/{dfd}") # fails closed when /proc is unavailable + except OSError: + raise UnsafeOutput("this system cannot report the output directory's real path") from None + if not os.path.isabs(resolved) or resolved.endswith(" (deleted)"): + raise UnsafeOutput("the output directory's real path could not be verified") + return resolved try: import fcntl raw = fcntl.fcntl(dfd, getattr(fcntl, "F_GETPATH"), b"\0" * 1024) @@ -79,7 +89,7 @@ def _publish_posix(parent: str, name: str, data: bytes, mode: int) -> None: if not real or localpath._reaches_network(real): raise UnsafeOutput("the output directory is not a local directory") _after_pin() - tmp = _tmp_name(name) + tmp = _tmp_name() fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), mode, dir_fd=dfd) with os.fdopen(fd, "wb") as handle: handle.write(data) @@ -96,6 +106,15 @@ def _publish_posix(parent: str, name: str, data: bytes, mode: int) -> None: # ---------------------------------------------------------------- Windows def _publish_windows(parent: str, name: str, data: bytes) -> None: + """Pin the directory, then create the FINAL name exclusively and verify where it really landed. + + Holding the directory handle (no FILE_SHARE_DELETE) stops a rename or delete of the directory and its + ancestors, but an actor with write access to an EMPTY directory can still turn it into a junction in + place. So the file handle itself is checked: after the exclusive create (CREATE_NEW, share mode none, so + nobody can read a partial file) its final path must sit directly inside the pinned directory's path; + otherwise the just-created empty file is deleted through the handle and nothing is written. The residual + exposure is an empty, immediately removed file in the redirected location; no passport content is written. + """ import ctypes from ctypes import wintypes @@ -105,41 +124,94 @@ def _publish_windows(parent: str, name: str, data: bytes) -> None: kernel32.CreateFileW.restype = wintypes.HANDLE kernel32.GetFinalPathNameByHandleW.argtypes = [wintypes.HANDLE, wintypes.LPWSTR, wintypes.DWORD, wintypes.DWORD] kernel32.GetFinalPathNameByHandleW.restype = wintypes.DWORD + kernel32.GetFileInformationByHandle.argtypes = [wintypes.HANDLE, wintypes.LPVOID] + kernel32.GetFileInformationByHandle.restype = wintypes.BOOL + kernel32.SetFileInformationByHandle.argtypes = [wintypes.HANDLE, ctypes.c_int, wintypes.LPVOID, wintypes.DWORD] + kernel32.SetFileInformationByHandle.restype = wintypes.BOOL + kernel32.WriteFile.argtypes = [wintypes.HANDLE, wintypes.LPCVOID, wintypes.DWORD, ctypes.POINTER(wintypes.DWORD), + wintypes.LPVOID] + kernel32.WriteFile.restype = wintypes.BOOL kernel32.CloseHandle.argtypes = [wintypes.HANDLE] FILE_LIST_DIRECTORY = 0x0001 + GENERIC_WRITE = 0x40000000 + DELETE = 0x00010000 SHARE_READ_WRITE = 0x1 | 0x2 # deliberately NOT FILE_SHARE_DELETE (0x4) - OPEN_EXISTING = 3 + OPEN_EXISTING, CREATE_NEW = 3, 1 FILE_FLAG_BACKUP_SEMANTICS = 0x02000000 + FILE_ATTRIBUTE_NORMAL = 0x80 + FILE_ATTRIBUTE_REPARSE_POINT = 0x400 + FILE_DISPOSITION_INFO = 4 + ERROR_FILE_EXISTS, ERROR_ALREADY_EXISTS = 80, 183 invalid = wintypes.HANDLE(-1).value - handle = kernel32.CreateFileW(parent, FILE_LIST_DIRECTORY, SHARE_READ_WRITE, None, OPEN_EXISTING, - FILE_FLAG_BACKUP_SEMANTICS, None) - if handle in (None, invalid): - raise UnsafeOutput("the output directory could not be opened") - try: + class FILETIME(ctypes.Structure): + _fields_ = [("lo", wintypes.DWORD), ("hi", wintypes.DWORD)] + + class BY_HANDLE_FILE_INFORMATION(ctypes.Structure): + _fields_ = [("attributes", wintypes.DWORD), ("created", FILETIME), ("accessed", FILETIME), + ("written", FILETIME), ("volume", wintypes.DWORD), ("size_hi", wintypes.DWORD), + ("size_lo", wintypes.DWORD), ("links", wintypes.DWORD), ("index_hi", wintypes.DWORD), + ("index_lo", wintypes.DWORD)] + + def final_path(h) -> str: buffer = ctypes.create_unicode_buffer(32768) - length = kernel32.GetFinalPathNameByHandleW(handle, buffer, len(buffer), 0) + length = kernel32.GetFinalPathNameByHandleW(h, buffer, len(buffer), 0) if not length or length >= len(buffer): - raise UnsafeOutput("the output directory's real path could not be read") - real = buffer.value - if real.upper().startswith("\\\\?\\UNC\\"): - raise UnsafeOutput("the output directory is not a local directory") - if real.startswith("\\\\?\\") and len(real) > 6 and real[5] == ":": - real = real[4:] # \\?\C:\dir -> C:\dir (a plain local drive path) + raise UnsafeOutput("a real path could not be read") + text = buffer.value + if text.upper().startswith("\\\\?\\UNC\\"): + raise UnsafeOutput("the output location is not local") + if text.startswith("\\\\?\\") and len(text) > 6 and text[5] == ":": + text = text[4:] # strip the extended-length prefix from a local drive path + return text + + def is_reparse(h) -> bool: + info = BY_HANDLE_FILE_INFORMATION() + if not kernel32.GetFileInformationByHandle(h, ctypes.byref(info)): + raise UnsafeOutput("the output directory could not be inspected") + return bool(info.attributes & FILE_ATTRIBUTE_REPARSE_POINT) + + directory = kernel32.CreateFileW(parent, FILE_LIST_DIRECTORY, SHARE_READ_WRITE, None, OPEN_EXISTING, + FILE_FLAG_BACKUP_SEMANTICS, None) + if directory in (None, invalid): + raise UnsafeOutput("the output directory could not be opened") + out = None + try: + real = final_path(directory) if localpath._reaches_network(real): raise UnsafeOutput("the output directory is not a local directory") _after_pin() + if is_reparse(directory): # turned into a link in place after the pin + raise UnsafeOutput("the output directory was redirected") destination = os.path.join(real, name) - tmp = os.path.join(real, _tmp_name(name)) + out = kernel32.CreateFileW(destination, GENERIC_WRITE | DELETE, 0, None, CREATE_NEW, + FILE_ATTRIBUTE_NORMAL, None) + if out in (None, invalid): + if ctypes.get_last_error() in (ERROR_FILE_EXISTS, ERROR_ALREADY_EXISTS): + raise FileExistsError(destination) + raise OSError(ctypes.get_last_error(), "the passport could not be created") + + def discard(): + flag = wintypes.DWORD(1) + kernel32.SetFileInformationByHandle(out, FILE_DISPOSITION_INFO, ctypes.byref(flag), ctypes.sizeof(flag)) + try: - with open(tmp, "xb") as out: - out.write(data) - os.rename(tmp, destination) # atomic and refuses an existing name on Windows - finally: - try: - os.remove(tmp) - except OSError: - pass + landed = final_path(out) + expected = os.path.normcase(os.path.normpath(destination)) + if os.path.normcase(os.path.normpath(landed)) != expected or localpath._reaches_network(landed): + raise UnsafeOutput("the output was redirected away from the verified directory") + view = memoryview(data) + while len(view): + written = wintypes.DWORD(0) + chunk = bytes(view[: 1 << 20]) + if not kernel32.WriteFile(out, chunk, len(chunk), ctypes.byref(written), None): + raise OSError(ctypes.get_last_error(), "the passport could not be written") + view = view[written.value:] + except BaseException: + discard() + raise finally: - kernel32.CloseHandle(handle) + if out not in (None, invalid): + kernel32.CloseHandle(out) + kernel32.CloseHandle(directory) diff --git a/backend/tests/passport/test_export_publication.py b/backend/tests/passport/test_export_publication.py index 535aaa74..34de4092 100644 --- a/backend/tests/passport/test_export_publication.py +++ b/backend/tests/passport/test_export_publication.py @@ -127,3 +127,107 @@ def test_a_missing_output_directory_is_refused_not_created(tmp_path): with pytest.raises(safe_publish.UnsafeOutput): safe_publish.publish_new_file(str(tmp_path / "nope" / "a.json"), b"x") assert not (tmp_path / "nope").exists() + + +# ------------------------------------------------------------ in-place link on an empty directory + +def _make_junction_in_place(directory, target) -> bool: + """Turn the EMPTY `directory` into a junction to `target` without renaming it (Windows only).""" + import ctypes + import struct + from ctypes import wintypes + + kernel32 = ctypes.WinDLL("kernel32", use_last_error=True) + kernel32.CreateFileW.argtypes = [wintypes.LPCWSTR, wintypes.DWORD, wintypes.DWORD, wintypes.LPVOID, + wintypes.DWORD, wintypes.DWORD, wintypes.HANDLE] + kernel32.CreateFileW.restype = wintypes.HANDLE + kernel32.DeviceIoControl.argtypes = [wintypes.HANDLE, wintypes.DWORD, wintypes.LPVOID, wintypes.DWORD, + wintypes.LPVOID, wintypes.DWORD, ctypes.POINTER(wintypes.DWORD), + wintypes.LPVOID] + kernel32.DeviceIoControl.restype = wintypes.BOOL + h = kernel32.CreateFileW(str(directory), 0x40000000, 0x7, None, 3, 0x02000000 | 0x00200000, None) + if h in (None, wintypes.HANDLE(-1).value): + return False + try: + substitute = ("\\??\\" + str(target)).encode("utf-16-le") + printable = str(target).encode("utf-16-le") + path_buffer = substitute + b"\0\0" + printable + b"\0\0" + header = struct.pack(" Date: Fri, 13 Nov 2026 17:52:55 -0500 Subject: [PATCH 3/5] fix(passport): exact file-path check, platform-aware name test, report failed cleanup (R4-F1 review round 2) Sol BLOCK on c824bf0: case-folded final-path comparison could accept a junction to a differently-cased sibling on a case-sensitive volume (HIGH); POSIX name test still required a backslash to be rejected (MEDIUM); discard ignored a failed disposition (LOW). Compare exact canonical paths; make the separator test platform-aware (POSIX accepts a backslash); raise when the empty file cannot be removed. Verified: passport + review-fix tests 82 passed on Windows. Co-Authored-By: Claude Sonnet 5.5 --- backend/snapstudio_core/safe_publish.py | 16 ++++++++++------ .../tests/passport/test_export_publication.py | 11 ++++++++++- docs/internal/PASSPORT.md | 2 +- 3 files changed, 21 insertions(+), 8 deletions(-) diff --git a/backend/snapstudio_core/safe_publish.py b/backend/snapstudio_core/safe_publish.py index 41d7085f..1c8a7d94 100644 --- a/backend/snapstudio_core/safe_publish.py +++ b/backend/snapstudio_core/safe_publish.py @@ -192,14 +192,18 @@ def is_reparse(h) -> bool: raise FileExistsError(destination) raise OSError(ctypes.get_last_error(), "the passport could not be created") - def discard(): + def discard(reason): flag = wintypes.DWORD(1) - kernel32.SetFileInformationByHandle(out, FILE_DISPOSITION_INFO, ctypes.byref(flag), ctypes.sizeof(flag)) + if not kernel32.SetFileInformationByHandle(out, FILE_DISPOSITION_INFO, ctypes.byref(flag), + ctypes.sizeof(flag)): + raise UnsafeOutput("the output could not be verified and the file it created could not be " + "removed") from reason try: landed = final_path(out) - expected = os.path.normcase(os.path.normpath(destination)) - if os.path.normcase(os.path.normpath(landed)) != expected or localpath._reaches_network(landed): + # Both strings are canonical on-disk spellings (GetFinalPathNameByHandle), so compare them exactly: + # case-folding would accept a junction to a distinct directory on a case-sensitive volume. + if os.path.normpath(landed) != os.path.normpath(destination) or localpath._reaches_network(landed): raise UnsafeOutput("the output was redirected away from the verified directory") view = memoryview(data) while len(view): @@ -208,8 +212,8 @@ def discard(): if not kernel32.WriteFile(out, chunk, len(chunk), ctypes.byref(written), None): raise OSError(ctypes.get_last_error(), "the passport could not be written") view = view[written.value:] - except BaseException: - discard() + except BaseException as error: + discard(error) raise finally: if out not in (None, invalid): diff --git a/backend/tests/passport/test_export_publication.py b/backend/tests/passport/test_export_publication.py index 34de4092..e1b58927 100644 --- a/backend/tests/passport/test_export_publication.py +++ b/backend/tests/passport/test_export_publication.py @@ -108,12 +108,21 @@ def test_publish_new_file_never_replaces_and_leaves_no_temporary(tmp_path): @pytest.mark.skipif(safe_publish is None, reason="needs safe_publish") -@pytest.mark.parametrize("name", ["", "..", "a/b", "a\\b"]) +@pytest.mark.parametrize("name", ["", "..", "a/b"]) def test_publish_refuses_a_name_that_is_not_a_plain_file_name(tmp_path, name): with pytest.raises(safe_publish.UnsafeOutput): safe_publish._check_name(name) +@pytest.mark.skipif(safe_publish is None, reason="needs safe_publish") +def test_a_backslash_is_a_separator_only_on_windows(): + if os.name == "nt": + with pytest.raises(safe_publish.UnsafeOutput): + safe_publish._check_name("a\\b") + else: + safe_publish._check_name("a\\b") # an ordinary POSIX file name + + @pytest.mark.skipif(safe_publish is None, reason="needs safe_publish") def test_a_directory_that_resolves_to_a_network_location_is_refused(tmp_path, monkeypatch): monkeypatch.setattr(safe_publish.localpath, "_reaches_network", lambda path, depth=0: True) diff --git a/docs/internal/PASSPORT.md b/docs/internal/PASSPORT.md index 04da4c79..7ea77a76 100644 --- a/docs/internal/PASSPORT.md +++ b/docs/internal/PASSPORT.md @@ -85,7 +85,7 @@ through the real `u1convert` entry point. Studio refuses, up front, a UNC or dev style, a symlink or junction whose target is one of those, a folder given as the output, and an existing output file. It never overwrites an input or an existing file. -For `export -o` the output directory is pinned once and the passport is created and published through that pin (a held directory descriptor on POSIX; a handle that forbids rename and delete of the directory and its ancestors on Windows), so swapping the directory or an ancestor after the check cannot redirect the write. On Windows an in-place junction on an empty directory is caught by re-checking the pinned directory and by verifying the created file's own final path before any content is written; the residual exposure is an empty file created and immediately removed in the redirected location. A platform that cannot pin and report the real path is refused. Input paths are still checked and then opened separately (see below). The checks reduce +For `export -o` the output directory is pinned once and the passport is created and published through that pin (a held directory descriptor on POSIX; a handle that forbids rename and delete of the directory and its ancestors on Windows), so swapping the directory or an ancestor after the check cannot redirect the write. On Windows an in-place junction on an empty directory is caught by re-checking the pinned directory and by verifying the created file's own final path before any content is written; the residual exposure is an empty file created and immediately removed in the redirected location. The file-path comparison is exact (not case-folded), so a junction to a differently-cased sibling on a case-sensitive volume is refused; the window between the directory re-check and the exclusive create is covered by that file-path check rather than by a test, because it cannot be hit deterministically. If a cleanup after a refused write fails, the command reports that instead of the refusal alone. A platform that cannot pin and report the real path is refused. Input paths are still checked and then opened separately (see below). The checks reduce accidents; they are not a filesystem sandbox and not a guarantee that no network location is ever reached. Input paths are read-only opens of regular files and are checked the same way, with the same validation-versus-use gap; no separate input-path exploit has been demonstrated. From f84829a7f1456818d38e99f4d23382235640e533 Mon Sep 17 00:00:00 2001 From: DeadlyVirusIn Date: Fri, 13 Nov 2026 17:56:29 -0500 Subject: [PATCH 4/5] test(passport): drive the post-recheck window and the failed-cleanup path (R4-F1 review notes) Opus/Sol approved 3e89141 with notes: no test reached the file-handle final-path check, because the junction test fires before the directory re-check, and the docs wrongly called the window untestable. Add a no-op _before_create seam and two Windows tests (junction set exactly before the create is refused and leaves the decoy empty; a failed disposition is reported). Correct the docs. Verified: tests/passport 62 passed on Windows. Co-Authored-By: Claude Sonnet 5.5 --- backend/snapstudio_core/safe_publish.py | 5 +++ .../tests/passport/test_export_publication.py | 42 +++++++++++++++++++ docs/internal/PASSPORT.md | 2 +- 3 files changed, 48 insertions(+), 1 deletion(-) diff --git a/backend/snapstudio_core/safe_publish.py b/backend/snapstudio_core/safe_publish.py index 1c8a7d94..9b72d711 100644 --- a/backend/snapstudio_core/safe_publish.py +++ b/backend/snapstudio_core/safe_publish.py @@ -36,6 +36,10 @@ def _after_pin() -> None: """Seam for tests: runs after the directory is pinned and verified, before any file is created.""" +def _before_create() -> None: + """Seam for tests (Windows): runs after the pinned directory's reparse re-check, immediately before the create.""" + + def _check_name(name: str) -> None: separators = ("/", "\\") if sys.platform == "win32" else ("/",) if not name or name in (".", "..") or "\x00" in name or any(sep in name for sep in separators): @@ -185,6 +189,7 @@ def is_reparse(h) -> bool: if is_reparse(directory): # turned into a link in place after the pin raise UnsafeOutput("the output directory was redirected") destination = os.path.join(real, name) + _before_create() out = kernel32.CreateFileW(destination, GENERIC_WRITE | DELETE, 0, None, CREATE_NEW, FILE_ATTRIBUTE_NORMAL, None) if out in (None, invalid): diff --git a/backend/tests/passport/test_export_publication.py b/backend/tests/passport/test_export_publication.py index e1b58927..4d77acf6 100644 --- a/backend/tests/passport/test_export_publication.py +++ b/backend/tests/passport/test_export_publication.py @@ -240,3 +240,45 @@ def mkstemp(*args, **kwargs): holders = [d for d in (victim, moved / "b") if (d / "job.passport.json").exists()] assert len(holders) == 1 and (holders[0] / "orig.marker").exists() assert not (ancestor / "b" / "job.passport.json").exists() or (ancestor / "b" / "orig.marker").exists() + + +@pytest.mark.skipif(os.name != "nt", reason="the post-recheck window is the Windows file-handle check") +def test_a_junction_set_between_the_recheck_and_the_create_is_caught_by_the_file_handle_check(tmp_path, monkeypatch): + victim = tmp_path / "victim" + decoy = tmp_path / "decoy" + victim.mkdir() + decoy.mkdir() + state = {"linked": None} + + def link(): + state["linked"] = _make_junction_in_place(victim, decoy) + + monkeypatch.setattr(safe_publish, "_before_create", link) + with pytest.raises(safe_publish.UnsafeOutput): + safe_publish.publish_new_file(str(victim / "job.passport.json"), b"passport bytes") + + assert state["linked"], "the test could not create the in-place junction" + assert not list(decoy.iterdir()), "content or a leftover file was written through the junction" + + +@pytest.mark.skipif(os.name != "nt", reason="Windows discard path") +def test_a_failed_cleanup_after_a_refused_write_is_reported_not_hidden(tmp_path, monkeypatch): + import ctypes + + victim = tmp_path / "victim" + decoy = tmp_path / "decoy" + victim.mkdir() + decoy.mkdir() + monkeypatch.setattr(safe_publish, "_before_create", lambda: _make_junction_in_place(victim, decoy)) + real_kernel32 = ctypes.WinDLL("kernel32", use_last_error=True) + + class Wrapped: + def __getattr__(self, name): + return getattr(real_kernel32, name) + + wrapped = Wrapped() + wrapped.SetFileInformationByHandle = type("F", (), {"argtypes": None, "restype": None, + "__call__": lambda self, *a: 0})() + monkeypatch.setattr(ctypes, "WinDLL", lambda *a, **k: wrapped) + with pytest.raises(safe_publish.UnsafeOutput, match="could not be removed"): + safe_publish.publish_new_file(str(victim / "job.passport.json"), b"x") diff --git a/docs/internal/PASSPORT.md b/docs/internal/PASSPORT.md index 7ea77a76..d16ec6fe 100644 --- a/docs/internal/PASSPORT.md +++ b/docs/internal/PASSPORT.md @@ -85,7 +85,7 @@ through the real `u1convert` entry point. Studio refuses, up front, a UNC or dev style, a symlink or junction whose target is one of those, a folder given as the output, and an existing output file. It never overwrites an input or an existing file. -For `export -o` the output directory is pinned once and the passport is created and published through that pin (a held directory descriptor on POSIX; a handle that forbids rename and delete of the directory and its ancestors on Windows), so swapping the directory or an ancestor after the check cannot redirect the write. On Windows an in-place junction on an empty directory is caught by re-checking the pinned directory and by verifying the created file's own final path before any content is written; the residual exposure is an empty file created and immediately removed in the redirected location. The file-path comparison is exact (not case-folded), so a junction to a differently-cased sibling on a case-sensitive volume is refused; the window between the directory re-check and the exclusive create is covered by that file-path check rather than by a test, because it cannot be hit deterministically. If a cleanup after a refused write fails, the command reports that instead of the refusal alone. A platform that cannot pin and report the real path is refused. Input paths are still checked and then opened separately (see below). The checks reduce +For `export -o` the output directory is pinned once and the passport is created and published through that pin (a held directory descriptor on POSIX; a handle that forbids rename and delete of the directory and its ancestors on Windows), so swapping the directory or an ancestor after the check cannot redirect the write. On Windows an in-place junction on an empty directory is caught by re-checking the pinned directory and by verifying the created file's own final path before any content is written; the residual exposure is an empty file created and immediately removed in the redirected location. The file-path comparison is exact (not case-folded), so a junction to a differently-cased sibling on a case-sensitive volume is refused; the window between the directory re-check and the exclusive create is covered by that file-path check and by a regression test that sets the junction at that exact point. If the empty file cannot be removed after a refused write, the library raises a distinct error; the CLI reports it as the generic output-directory verification failure, not as a leftover-file notice. A platform that cannot pin and report the real path is refused. Input paths are still checked and then opened separately (see below). The checks reduce accidents; they are not a filesystem sandbox and not a guarantee that no network location is ever reached. Input paths are read-only opens of regular files and are checked the same way, with the same validation-versus-use gap; no separate input-path exploit has been demonstrated. From 4be90cb5f8e86aa4f08122c343a087443189fc03 Mon Sep 17 00:00:00 2001 From: DeadlyVirusIn Date: Sat, 14 Nov 2026 08:07:49 -0500 Subject: [PATCH 5/5] docs(passport): state the interrupted-write, filesystem and macOS limits of export publication Opus and Sol approved f84829a with this note. Doc-only; no code or test change. Co-Authored-By: Claude Sonnet 5.5 --- docs/internal/PASSPORT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/internal/PASSPORT.md b/docs/internal/PASSPORT.md index d16ec6fe..2f8565a2 100644 --- a/docs/internal/PASSPORT.md +++ b/docs/internal/PASSPORT.md @@ -4,7 +4,7 @@ Evidence label: **fixture-tested**. The passport model, import, verify and comma below are exercised by `backend/tests/passport/` with synthetic files and a synthetic command-line client. The path-refusal and output-file behaviour is exercised in `backend/tests/test_review_fixes*.py` and `backend/tests/test_localpath_links.py`; the refusal of a folder or trailing-separator `-o` has no -test yet. The `export -o` directory-swap race (R4-F1) is closed for the output side by pinning the directory (`snapstudio_core/safe_publish.py`); `backend/tests/passport/test_export_publication.py` reproduces the swap and fails on the previous write path. Only the Windows pin was exercised locally (directory swap, ancestor swap and in-place junction on an empty directory); the POSIX descriptor path has no local run and depends on the Linux CI job. On Windows the passport is now written with LF line endings. No real third-party program, printer, slicer run or project file was used. +test yet. The `export -o` directory-swap race (R4-F1) is closed for the output side by pinning the directory (`snapstudio_core/safe_publish.py`); `backend/tests/passport/test_export_publication.py` reproduces the swap and fails on the previous write path. Only the Windows pin was exercised locally (directory swap, ancestor swap and in-place junction on an empty directory); the POSIX descriptor path has no local run and depends on the Linux CI job. On Windows the passport is now written with LF line endings. Known limits: the Windows path writes the final file name directly, so a process killed or a power loss mid-write can leave a truncated passport at that name (a rerun then reports `output_exists`; delete it and export again); the POSIX path (temporary file plus no-replace link, no fsync) can likewise leave an empty or short file after power loss on some filesystems; FAT, exFAT and ReFS volumes and case-sensitive NTFS directories were not tested; the macOS `F_GETPATH` branch was assessed by reading only and never run; the POSIX branch has run only in the Linux CI job. A green CI run does not remove these limits. No real third-party program, printer, slicer run or project file was used. ## What a passport is