fix: recognize host-level UNC roots in path containment checks

[crowecawcaw]

Fixes #1321

Problem

os.path.commonpath cannot compare a Windows host-level UNC path (\\server) with a path under one of its shares. ntpath.splitdrive reports no drive for the former and \\server\share for the latter, so it raises. Three distinct pairs fail:

Pair	commonpath result
\\host vs \\host\share\f	ValueError: Paths don't have the same drive (the reported case)
\\host\s1\a vs \\host\s2\b	ValueError: Paths don't have the same drive
\\host\share vs \\host\share\f	ValueError: Can't mix absolute and relative paths

_is_known_path caught that ValueError as "not contained", so every asset path under a \\server known root was reported as unknown and submissions from a network share could not proceed without confirmation.

The audit found the same root cause at three more sites, where the exception was not caught at all and surfaced as a raw ValueError rather than a verdict — two of them latent crashes rather than merely wrong answers:

Site	Before
_submit_job_bundle.py:_is_known_path	caught ValueError → valid paths silently reported unknown
_submit_job_bundle.py:_filter_redundant_known_paths	Path.parts collapses \\server\share into one atom, so a host root never subsumed its shares
job_bundle/loader.py symlink containment	uncaught → crash for a bundle at a share root, or a symlink escaping onto a share
job_bundle/parameters.py PATH default	uncaught → same
cli/_groups/job_group.py download summary	stray trailing separator in user-visible text

Solution

New private deadline/client/_path_utils.py compares paths component by component, so a UNC host is an ordinary ancestor of its shares. Because the helper needs to work cross-OS and because Python stdlib handles paths differently for different versions, we need to implement some lower level path logic ourselves.

Testing

Lots of unit tests. Also testing on Windows runner with real SMB shares.

Appendix: Windows path spaces and the moving stdlib model

Background for reviewers who do not work on Windows day to day. "Path space" is the term the
code uses; Microsoft's docs call the \\?\ and \\.\ ones namespaces (Win32 file
namespace, Win32 device namespace) and call the broader categories path formats. Rows
marked ⓜ were measured on real interpreters rather than taken from documentation.

Windows has ~6 path spaces; POSIX has ~1

Spelling	Means	Fully qualified?
C:\foo	drive-absolute	yes
C:foo	foo under the working directory on drive C:	no
\foo	foo at the root of the current drive	no
foo	relative to the working directory	no
\\server\share\foo	UNC (network)	yes
\\?\..., \\.\...	extended-length / device	yes

• Windows keeps a working directory per drive (DOS legacy, carried in hidden =C:
  environment variables). That is why C:foo and \foo are ambiguous — they resolve against
  process state, which is exactly what a trusted root must not depend on.
• The POSIX habit that breaks here: string prefix implies directory containment. Across path
  spaces that is false in both directions.

Win32 normalization — what \\?\ turns off

Before a path reaches the filesystem, Win32 rewrites it: / to \; collapses . and ..;
strips trailing dots and spaces (foo. becomes foo); resolves drive-relative and rooted
forms against the working directory; intercepts reserved device names (CON, NUL, COM1);
and enforces MAX_PATH = 260.

\\?\ — the extended-length prefix

• Passes the rest through nearly verbatim to the NT namespace, raising the limit to ~32,767
  characters.
• Because normalization is off, the path must already be perfect: backslashes only (/
  fails), no . or .., fully qualified.
• Trailing dots and spaces are preserved, so it can name files Win32 cannot reach. This is why
  folding prefixed and plain spellings together is not automatically safe — it is safe here
  because component text is preserved, so C:\trusted \evil still fails closed.
• \\.\ is the device namespace (\\.\C: is the volume, not the filesystem root). It has
  no plain spelling, and neither does \\?\Volume{GUID}\. Both keep a path space of their own.

The \\?\UNC\ form is the trap. The prefix replaces the leading pair rather than stacking on
it:

\\server\share\f   ->   \\?\UNC\server\share\f      correct
\\server\share\f   ->   \\?\\\server\share\f        invalid -- what job-attachments#67 produced

Why \\server breaks everything

• On Windows, \\server is not a directory. server and share together form the mount
  point, the drive-equivalent. Explorer lists shares through a different API; there is no
  directory handle for \\server.
• So ntpath.splitdrive(r"\\server\share") reports the whole thing as the drive, and no stdlib
  helper models "\\server contains its shares" — that is not a filesystem fact, it is a policy
  choice. It is the one piece of hand-written path logic in this PR, and deliberately so.
• commonpath raises rather than answering, because one side has a drive and the other does not.

The stdlib model shifted three times inside 3.9-3.14 ⓜ

	3.9 / 3.10	3.11 / 3.12	3.13 / 3.14
splitdrive(r"\\host")	("", r"\\host")	(r"\\host", "")	same
normpath(r"\\host")	\host — pair collapsed	\\host	same
isabs(r"\\host\share")	False	True	True
isabs(r"\x")	True	True	False
splitroot	absent	3.12+	present

• Before 3.11 the model demanded exactly \\server\share, and mishandled both neighbours in
  opposite directions:
  • less than that (\\host) read as "no drive", so normpath collapsed \\ to \ and
    silently moved a host-level root out of the UNC space;
  • exactly that (\\host\share) read as "all drive", leaving isabs an empty remainder to
    test, so it answered not absolute.
• 3.12 added splitroot, giving (drive, root, tail). Needed because splitdrive folds the
  root into rest and so cannot tell \foo from \\foo.
• 3.13 tightened isabs(r"\x") to False, correctly, since it needs the current drive. That is
  the answer this PR now matches on every version.
• Net effect: "just use the stdlib" returns different answers per interpreter. That is why
  these helpers derive the path space themselves instead of asking ntpath.

Long paths — three gates, not one

• MAX_PATH is enforced by normalization, so \\?\ bypasses it structurally.
• Windows 10 1607+ added the registry LongPathsEnabled, but it is not sufficient: the
  process also needs longPathAware in its executable manifest.
• RtlAreLongPathsEnabled() reports the process state, not the registry, despite the name.
  Measured in job-attachments#67: one machine, key set, stock python.exe reports True and a
  manifest-cleared copy reports False.
• python.exe has declared it since CPython 3.6. DCC executables and pythonservice.exe
  generally do not, which is why the prefix is still required.

Crossing between spellings — where the bugs live

• Apply the prefix at the filesystem call; strip it exactly once where a path is
  surfaced (terminal, JSON, manifests other tools parse).
• Retain it for internal filesystem consumers. That is job-attachments#67's invariant, and
  its items 1 to 5 came from stripping too early.
• Some APIs go through normalization and therefore reject the prefix —
  win32security.Get/SetFileSecurity is the live example.
• Path.resolve() preserves an existing \\?\ on 3.10+ but drops it on 3.8 and 3.9: a
  transition that silently varies by version.
• Prefixing one call in a chain moves the failure to the next unprefixed one. Both repositories
  hit this repeatedly — job-attachments#67 items 1 to 5 and 7 to 8, and four times here.
• Lexical versus symlink-aware is a real boundary. Collapsing .. lexically after a
  realpath-based check has already passed can write somewhere else, which is why .. is
  refused rather than collapsed in a prefixed path.

Why this class of bug recurs

• Six path spaces, and code written assuming one.
• The path space is encoded in a string prefix, so it is invisible unless you parse for it.
• The stdlib's own answer moved three times inside the supported range, so version-independence
  has to be built rather than inherited.
• Every failure mode here is a false negative — a valid path reported unknown, or a valid
  absolute path reported relative. Those surface as a warning or a dropped root rather than a
  crash, so they ship easily and are visible only to users on network shares.

[baxeaz]

Running this through some AI checks this is the main thing flagged and it seems somewhat unlikely, but here for consideration:

The SMB fixture calls pytest.skip() when the share cannot be created or reached (test_unc_path_containment.py:59,70).

Because pytest exits successfully when every test is skipped, the new regression workflow can go green while executing zero SMB tests. The “Report skips” step only prints the skips; it does not enforce coverage and unnecessarily reruns the entire suite.

I’d recommend running the suite once with -rs and making module-wide fixture skips fail in CI—for example, fail when the share cannot be created/reached or validate the JUnit report to ensure the required tests executed.

This matters because the workflow comments state that no other job runs these integration tests, so a green result could falsely indicate that issue #1321 remains covered.

[crowecawcaw]

Confirmed and fixed in cc26271. I checked the mechanism rather than reasoning about it:

module-scoped fixture pytest.skip  ->  2 skipped, exit 0
module-scoped fixture pytest.fail  ->  2 errors,  exit 1

So the green-with-zero-coverage path was real. The prerequisites step only closed the admin case, and on windows-latest the runner is already elevated — so that throw never fires, and the two skips that can actually happen were exactly the ones it did not cover.

Fixed the way you suggested — one run with -rs, environment skips failing in CI — via a _unavailable() helper gated on DEADLINE_SMB_TESTS_REQUIRED, which the workflow sets and a developer without administrator rights does not. Applied at all four skip sites rather than only the module fixture: share creation, reachability, the symlink privilege, and the drive letter. Each one means the environment cannot exercise the fix, and the workflow provisions for all four (it enables Developer Mode for the symlink), so a skip there is a broken runner rather than a benign one.

Two things surfaced while confirming it, both of which made it worse than described:

1. --numprocesses=auto is in addopts (pyproject.toml:172) and the run command did not override it, so every xdist worker built its own share and they raced for the one free drive letter — a spurious skip the workflow generated itself. Pinned to --numprocesses=0.
2. The platform gate was the same hole. skipif(sys.platform != "win32") is a skip like any other, so a runs-on change would have produced the identical false green. Under the flag it is now a collection error (exit 2, verified).

I skipped the JUnit-report validation you offered as the alternative: the flag covers "collected but skipped", and pytest already exits 5 on "collected nothing", so there is no gap left for XML parsing to close.

Report skips is gone — you are right that it re-ran the whole suite, a second net share create and delete cycle, to print counts it could not act on. -rs on the single run reports the same thing.

Also added test_unavailable_fails_where_the_share_is_required, which pins both branches of the helper and needs no share, so it is the one test here a broken runner cannot silence.

Worth stating because it sharpens your point: the workflow itself has never executed — workflow_dispatch requires the file on the default branch, so it could not have been dispatched from this branch. The post-merge push will be its first run, which is precisely when a false green would have gone unnoticed.

[crowecawcaw]

The review comment is correct, and the reason the Windows checks were green is that this test never ran in PR CI: windows_smb_test.yml triggers on workflow_dispatch / push: [mainline] / workflow_call only, and testpaths in pyproject.toml excludes test/integ, so nothing on a pull request reaches the file. Its first real run would have been the post-merge push to mainline.

Windows clamps .. at a share root — the root of \\server\share\... is \\server\share\, and ntpath.realpath starts with normpath, whose splitroot treats \\host\share as the drive with root \, so the leading .. is dropped rather than climbing to \\host:

os.path.realpath(os.path.join(r"\\host\share", "../escaped.txt"))  ->  \\host\share\escaped.txt

That is inside the destination, so _safe_zip_extract correctly does not raise and the pytest.raises failed. The lexical unit tests already say this (test/unit/deadline_client/test_path_utils.py:74-75); only this integ test contradicted them.

Verified on a real Windows runner against a real SMB share, both directions:

• pre-fix commit: test_archive_extracts_at_a_share_root_and_still_rejects_an_escape FAILED ... Failed: DID NOT RAISE ValueError (1 failed, 9 passed)
• post-fix: 12 passed

Fixed in baa5b9d, splitting the one test into three:

• test_archive_extracts_at_a_share_root — the actual [Bug] _is_known_path fails path validation for host-level UNC roots (e.g. \\<host> ) #1321 regression, unchanged.
• test_pardir_at_a_share_root_stays_on_the_share — pins the clamp against the real redirector, which is why a share-root destination needs no escape case.
• test_archive_escaping_a_directory_on_a_share_is_rejected — the escape case, now with a subdirectory destination as suggested, so ../escaped.txt genuinely leaves it.

Worth noting no escape was ever possible here regardless: zipfile.extractall strips .. from member names itself, so the guard is the second line of defense. This was a wrong assertion, not a hole.

[crowecawcaw]

Audited this PR's tests three ways — mutation testing (revert each fix, see if anything fails), CI wiring (does each test actually execute, and where), and assertion correctness (re-derive every Windows expectation against real interpreters). Six commits follow. Highlights:

Two guards had no effective coverage at all.

• _safe_zip_extract was the worse one, and it explains the original finding. is_path_contained's path_module default binds os.path at import time, so the one call site that relied on the default could not be pointed at ntpath the way every other call site can — each of those carries "read at call time, so tests can patch it". Reverting commit 0bcc8bf entirely failed zero tests in test/unit. Fixed by passing path_module explicitly, plus four cases: share-root destination, the .. clamp, an escape from a subdirectory, and D:evil (a drive-relative entry that survives the isabs check and discards the destination — ntpath.join(r"\\host\share", "D:evil") is "D:evil").
• The pre-submission hook PATH check had no seam and no test on any platform: restoring pre-3.11 isabs semantics there passed all 3580 unit tests, while the same mutation at its sibling call site kills 14. Extracted _reject_relative_hook_path_values with an injectable path_module; it now pins both directions (\\host\share accepted — pre-3.11 isabs called that relative; \scene.ma and C:scene.ma rejected — isabs accepted the first through 3.12).
• Related: the absolute-PATH-default check ran only on relative defaults, so it never evaluated under the injected ntpath. A share-root default is the spelling that diverges; match= matters because the containment check below raises the same type.

The tests-do-not-run problem was bigger than the one file. test/integ is locked out twice — pyproject.toml testpaths and hatch.toml:12, which hard-codes test/unit test/cli_e2e for the reusable build — so editing testpaths alone would change nothing. Meanwhile integ:test collected test/integ/windows_smb on both mainline CodeBuild legs and skipped all 12 silently, reading as coverage that did not exist. The SMB workflow now runs on pull_request for the paths it covers (verified: this push triggered it, event: pull_request, 12 passed), and the mainline integ script excludes the directory so one job owns it.

Two SMB tests were passing for the wrong reason. The mapped-drive test branched on realpath's output, so a containment regression in the drive-letter space would steer it into the branch that does not check that space — and the surviving assertion duplicated an earlier test. It now pins the UNC rewrite and asserts both spellings, including that a mapped-drive root does not cover files resolved to UNC form. The symlink escape targeted the local C: spelling of a file inside the share, so rejection came from comparing path spaces, not from leaving the bundle; it now targets a sibling through the share and pins that realpath resolves the link at all.

Smaller fixes: the anti-climb backstop had one covering case (added the prefixed/device spellings whose .. survives normalization before 3.11 — verified on real 3.9, where components are [..., "t", "..", "evil", "f"]); the known-root filter is now asserted through a pre-3.11 normpath; is_absolute_path is pinned against a deliberately-wrong isabs since 3.13+ stdlib agrees with it and cannot fail the delegating form; five pytest.raises gained match=; the common_ancestor property test gained an assertion floor (it skips empty answers, so returning nothing for everything passed it vacuously); dropped a patch of abspath the filter never calls and three dead ruff exemptions.

Also corrected two comments: the \\?\ normalization boundary is 3.11, not 3.10 (measured on 3.9/3.10/3.11), and the splitroot shim's triples are not comparable across that boundary — the shim reads the running splitdrive, so freezing 3.12 literals for the older legs would assert the wrong thing.

Verified: 3766 unit tests pass locally; SMB suite 12/12 on a real Windows runner with a real share; every mutation described above now fails at least one test (checked one at a time in an isolated worktree). Two things I did not change, for you to decide: the workflow_call trigger on the SMB workflow is dead — nothing in the repo calls it, so released tags get no SMB validation, and wiring it into release_publish.yml is a release-pipeline change; and AGENTS.md claims an 80% coverage gate while pyproject.toml sets fail_under = 69 (pre-existing).

[crowecawcaw]

Second audit round (code review for the same mistake classes + a read of the actual Actions logs). Six more commits.

Root cause of the archive-guard gap, fixed at the source. path_module=os.path in a signature binds at import, so any call site omitting it is unpatchable — that trap is what made the guard untestable. All seven helpers now take path_module=None and resolve in the body, so the omission is harmless and every call site is patchable whether or not it passes one.

Same #1321 bug found still live elsewhere. job_group._assert_valid_path validated a download root arriving over the JSON protocol with Path.is_absolute — PureWindowsPath(r"\\host").is_absolute() is False before 3.13 and True from 3.13 (measured on 3.9/3.10/3.11/3.14), so a host-level UNC download root was rejected outright on four of six supported versions. It had no tests: both references to it in the suite patch it out. Now uses the version-independent helper; the old implementation fails 5 of the new cases.

Tests that asserted nothing. test_agrees_with_pathlib_except_for_unc_hosts — the PR's independent oracle — reached its assertions only for disagreeing pairs and continued otherwise, so it passed with zero assertions executed, including against an is_path_contained that just delegates to pathlib (i.e. this whole PR reverted). It now counts both sanctioned classes and asserts a floor; verified the delegating regression fails it. Separately, four TestSanitizeBundleName cases were written as if sys.platform == "win32": assert ... with no else, so half of that traversal guard's behavior went unverified on linux and macos; they now patch the sys.platform it reads at call time. Two pre-existing bare pytest.raises on the symlink guard gained match=.

Log audit — what actually ran. Every one of the 18 matrix legs collected exactly +304 items over the merge-base run; on 3.12/3.13/3.14 (all three OSes) +304 passed / +0 skipped, on 3.9/3.10/3.11 +300 passed / +4 skipped. Those 4 are test_splitroot_backport_matches_stdlib (no stdlib oracle before 3.12) and test_agrees_with_pathlib (skipif < 3.12), each with a version-independent counterpart that runs everywhere — no test added here skips on every leg. _path_summary.py is at 100% statement+branch coverage on all 18 legs; _path_utils.py 100% on 3.12+ and 98% below (the missing line is the 3.12-only splitroot delegation, correctly dead there). The SMB job: event = pull_request, DEADLINE_SMB_TESTS_REQUIRED=1, collected 12 items, 12 passed, 0 skipped, -rs produced no skip summary, SymlinkEvaluation reported ENABLED, 2m32s wall (~4s of it tests).

One correction to what I said earlier: running on pull_request makes this job visible, not blocking. Branch protection on mainline requires only the 18 Python legs plus DCO and Semantic PR, so a red SMB job cannot stop a merge today. That is inherent to the paths: filter — a filtered check sits permanently pending if made required — so making it required means dropping the filter and paying the Windows env install on every PR. Your call; also worth knowing Blender Submitter UI (Windows) carries continue-on-error: true and can never fail its workflow.

Unrelated flake, fixed here because it blocked this PR. test_deadline_login_dialog.py::test_monitor_login_keeps_its_own_message failed on macos 3.11 and reproduced locally under the full suite. The file is untouched by this branch (it came from #1323), but the race is in the test's own helper: it waited on an Event the background thread sets right after calling on_pending_authorization, then read dialog.text() — while the message crosses to the GUI thread on a queued signal, so that Event says nothing about whether the dialog applied it. It now waits for the text, bounded. Verified by injecting the delay a loaded runner produces: the old predicate fails with exactly the CI error, the new one passes.

Two things left alone, deliberately — both real, both outside this PR: ui/widgets/path_widgets.py:67,241 collapse $HOME with directory.startswith(home_dir) and then slice [len(home_dir) + 1:], so with a home of /Users/bob, picking /Users/bobby/projects/scene.ma displays ~/ar/projects/scene.ma and picking /Users/bob2/projects/x yields /projects/x — and deadline_config_dialog.py writes that text straight into job_history_dir / job_bundle_default_directory. That is the same string-prefix mistake, in the GUI. And cli/_groups/_batch_get.py:46 has an import-time-bound sleep=time.sleep default that both production call sites omit, so the retry/backoff path costs real wall-clock and is unpatchable. Happy to take either as a follow-up.

[crowecawcaw]

Correction to my last comment: the ~-collapse bug in ui/widgets/path_widgets.py is fixed here, not left for a follow-up. Both widgets carried the same copy-pasted block; it is now one helper using is_path_contained + relpath. With a home of /Users/bob: choosing /Users/bobby/projects/scene.ma previously displayed ~/ar/projects/scene.ma (the + 1 ate a character), and /Users/bob2/projects/x became /projects/x (join() drops the ~ when what follows is rooted) — both now come back untouched, and /Users/bob collapses to ~ rather than ~/. Covered in both path spaces including the sibling prefixes and Windows case-insensitivity; the previous implementation fails 8 of the new cases.

The _batch_get.py import-time-bound sleep=time.sleep default is the one still left for a follow-up.

Current state: 34 checks green, UNC Containment (real SMB) passing on pull_request at this head, and macos-latest 3.11 — the leg that failed earlier — green with the queued-signal race fixed. The branch is BEHIND mainline and will need an update before merge.