💫 Toolkit to help you get started with SDD or any other process!
Add scoped FileHelper foundation for filesystem policy (#4908)
Manfred Riem03de661789b7
diff --git a/design/file-helper.md b/design/file-helper.mdnew file mode 100644index 000000000..fa9d4dd0a--- /dev/null+++ b/design/file-helper.md@@ -0,0 +1,138 @@+# Scoped FileHelper foundation++`specify_cli.file_helper.FileHelper` owns filesystem operations under one+explicitly established root. This is the first migration stage: existing CLI+commands retain their current behavior and do not yet use this helper. There is+no global CLI flag or process-global policy.++The user-directed persistence requirement belongs to the dependent+project-policy wiring stage: save the setting in `.specify/init-options.json`,+then load and validate it for future invocations and pass the resulting policy+explicitly to helper instances. Only `specify init` exposes and persists the+setting. Every other CLI command reads the current project configuration on+each invocation, so manual edits take effect without a cached policy. There+is no root/global flag and no per-command override flag. The low-level helper+does not read configuration. Strict persisted-policy loading and configuration-+read bootstrap semantics must be coordinated before migration.++```python+from specify_cli.file_helper import FileHelper++files = FileHelper(project_root) # deny symlinks by default+files.mkdir("generated", exist_ok=True)+files.create_text("generated/config.txt", "initial\n")+files.write_text("generated/config.txt", "updated\n")+content = files.read_text("generated/config.txt")+files.delete("generated", recursive=True)+```++## Boundary and policy++Each helper has a frozen root and `allow_symlinks` setting. Relative operation+paths are root-relative. Absolute paths must be beneath the supplied root or+its canonical equivalent. User operation paths containing `..` are rejected+in their root-relative suffix rather than normalized before inspection. A+caller-established root spelling may itself contain `..`; absolute operation+paths derived from that exact supplied root prefix are supported. Only that+trusted prefix is removed before checking operation components, without+lexically collapsing the root or ignoring traversal in the remaining suffix.+Link targets may contain `..`, but+are walked component by component and may not leave the root, even temporarily.+Windows rooted-but-not-absolute paths (`/outside/file`, `\outside\file`) and+drive-relative paths (`C:outside/file`, `C:`) are rejected for both operation+paths and link targets. They are not root-relative: joining them can reset the+root or drive. Fully absolute paths still require scoped root matching.+For Windows containment comparisons, extended-length drive and UNC spellings+(`\\?\D:\project\file`, `\\?\UNC\server\share\project\file`) are compared with+their ordinary equivalents on both the target and root sides. This does not+resolve links or collapse `..`: accessed hierarchy evidence is retained for+the component walk. The UNC namespace marker is matched case-insensitively,+while the remaining path's original spelling is preserved. External targets,+ambiguous rooted-relative paths, and+unsupported device namespaces are still rejected. POSIX filenames are not+reinterpreted as Windows path spellings.++The caller must establish a trusted, existing directory root. Its alias is+resolved once, including OS and worktree aliases; the root itself and OS+ancestors above it are not subjected to the traversal policy. Thus explicitly+establishing a linked directory as a root trusts that alias even in deny mode.+Links *below* that boundary are checked in both the original accessed path and+any followed target hierarchy. An unrelated project symlink does not prevent+an operation. A helper cannot cross to another root; callers establish separate+helpers for independent project/source/managed boundaries.++| Operation | Default deny | Explicit allow |+|---|---|---|+| Read file | Reject accessed parent or leaf links | Follow only existing contained regular-file targets |+| Create directory | Reject accessed links before creating parents | Follow contained directory links; reject dangling targets |+| Exclusively create file | Reject accessed links | Follow contained parents; reject an existing leaf without opening its target |+| Atomic write/upsert | Reject accessed links | Replace the resolved regular-file target and preserve every link |+| Delete leaf link | Reject without mutation | Unlink the link, including dangling, cyclic, or external-target links |+| Delete through linked parent | Reject without mutation | Delete the contained target entry, leaving the parent link intact |+| Recursive delete | Preflight all descendants and reject any link before mutation | Preflight all descendants; unlink links without traversing their targets |+| Create symlink | Reject | Require an existing contained file/directory target |++## API and failures++- `mkdir(path, parents=False, exist_ok=False)` creates directories.+- `read_bytes(path)` / `read_text(path, encoding="utf-8")` read regular files.+- `create_bytes(path, content, mode=0o644)` / `create_text(...)` exclusively+ create files with existing parents. A no-follow `lstat` preflight rejects+ existing leaves, including dangling links, before opening the destination.+ This avoids target creation on backends that follow dangling links despite+ exclusive-open flags. `O_EXCL` and `O_NOFOLLOW` (where available) remain in use;+ the static preflight does not eliminate concurrent path-change races.+- `write_bytes(path, content, mode=0o644)` / `write_text(...)` atomically+ create or update files with existing parents. Text variants also accept+ `encoding="utf-8"`. Replacement files use the supplied mode; metadata and+ hard-link identity are not preserved. Atomic means same-directory+ `os.replace`, not crash durability.+- `delete(path, recursive=False)` unlinks files/links or removes directories.+ Nonrecursive directory deletion requires an empty directory. The established+ root cannot be deleted.+- `symlink(target, path)` creates a link exclusively. Relative targets are+ interpreted relative to the link parent, not the helper root.++`SymlinkDeniedError`, `PathEscapeError`, and `UnsupportedPathError` derive from+`FileHelperError` and describe policy failures. Missing paths (including+dangling read/update targets), permissions, existing exclusive-create+destinations, non-directory parents, and OS I/O failures retain native Python+exceptions. Nothing prints, warns-and-skips, or exits the CLI. Callers own+translation into their normal command error envelopes.++Only regular files, directories, and explicitly allowed symlinks are supported.+Below the established root, Windows directory junctions and other non-symlink+reparse entries are unsupported and rejected with `UnsupportedPathError` in+**both** policy modes. This includes contained junctions, leaf deletion, and+recursive deletion: preflight rejects them without traversing or removing+them. `allow_symlinks=True` does not authorize junction traversal or deletion.+The trusted root alias boundary may itself resolve through a junction just as+it may through a symlink; this does not authorize junctions below that root.+Read/update cycles and excessive link chains fail explicitly. A recursive+delete includes the entire selected tree; there is no exclusion filter in this+foundation. Future operations with exclusions must inspect only included+entries, not reject a whole project for excluded/unrelated links.++## Safety limits and migration++Preflight detects static policy failures before recursive deletion or parent+creation. Atomic writes recheck the original path before replacement, and+deletion rechecks each accessed entry. Portable path checks are **not** a+race-free sandbox: another process can exchange parents or entries between+checks and syscalls, and an I/O failure during mutation can leave partial+results. Protect against concurrent untrusted mutation separately; descriptor-+relative traversal or platform-specific mechanisms are future work, not a+claim of this API. The helper does not constrain subprocesses or third-party+code. Exclusive creation uses `O_EXCL` and `O_NOFOLLOW` where available.++Existing safe-write mechanisms informed this helper, but existing shared+infrastructure warning/skip behavior and development-mode link creation are+unchanged. Migrate one owned operation boundary at a time, carrying original+paths and an explicit root/policy into the helper before any early resolution.+CLI option wiring, linked command directories, and development-mode+registration remain dependent stages.++Windows path classification and directory-mode reparse rejection have portable+regression tests. Native Windows path and junction tests also exist and are+skipped on other hosts; running the portable cases on macOS does not validate+Windows filesystem syscalls or junction behavior.diff --git a/src/specify_cli/file_helper.py b/src/specify_cli/file_helper.pynew file mode 100644index 000000000..ba135135d--- /dev/null+++ b/src/specify_cli/file_helper.py@@ -0,0 +1,259 @@+"""Scoped filesystem operations; see design/file-helper.md for the contract."""++from dataclasses import dataclass, field+import errno+import os+from pathlib import Path, PurePath, PureWindowsPath+import stat+import tempfile+from typing import TypeVar+++_PathType = TypeVar("_PathType", bound=PurePath)+++def _strip_extended_length_prefix(path: _PathType) -> _PathType:+ """Normalize Windows extended drive/UNC spellings for comparison only."""+ raw = str(path)+ if raw.lower().startswith("\\\\?\\unc\\"):+ return type(path)("\\\\" + raw[len("\\\\?\\UNC\\"):])+ if raw.startswith("\\\\?\\"):+ return type(path)(raw[len("\\\\?\\"):])+ return path+++class FileHelperError(ValueError):+ """An operation violates the scoped filesystem contract."""+++class SymlinkDeniedError(FileHelperError):+ """An accessed symlink requires explicit traversal permission."""+++class PathEscapeError(FileHelperError):+ """An accessed path is outside the established root."""+++class UnsupportedPathError(FileHelperError):+ """An accessed object cannot be used by the requested operation."""+++@dataclass(frozen=True)+class FileHelper:+ """Own operations beneath one trusted root with an immutable link policy.++ Relative operation paths are relative to ``root``, not the process cwd.+ The root itself is a trusted alias boundary, resolved once on construction.+ """++ root: Path+ allow_symlinks: bool = False+ _canonical_root: Path = field(init=False, repr=False)++ def __post_init__(self) -> None:+ root = Path(self.root).absolute()+ canonical = root.resolve(strict=True)+ if not canonical.is_dir():+ raise NotADirectoryError(root)+ object.__setattr__(self, "root", root)+ object.__setattr__(self, "_canonical_root", canonical)++ def _parts(self, path: PurePath) -> tuple[str, ...]:+ original = path+ if isinstance(path, PureWindowsPath):+ path = _strip_extended_length_prefix(path)+ if not path.is_absolute():+ if original.anchor or path.anchor:+ raise PathEscapeError(f"Rooted-relative, drive-relative, or device path is not permitted: {original}")+ return path.parts+ for root in (self.root, self._canonical_root):+ if isinstance(root, PureWindowsPath):+ root = _strip_extended_length_prefix(root)+ try:+ return path.relative_to(root).parts+ except ValueError:+ continue+ raise PathEscapeError(f"Path is outside root {self.root}: {original}")++ @staticmethod+ def _entry_mode(path: Path) -> int:+ entry = path.lstat()+ if (+ getattr(entry, "st_file_attributes", 0) & stat.FILE_ATTRIBUTE_REPARSE_POINT+ and not stat.S_ISLNK(entry.st_mode)+ ):+ raise UnsupportedPathError(+ f"Unsupported Windows reparse point (including directory junctions): {path}"+ )+ return entry.st_mode++ def _walk(+ self,+ parts: tuple[str, ...],+ *,+ allow_missing: bool = False,+ follow_leaf: bool = True,+ links: tuple[Path, ...] = (),+ ) -> Path:+ current = self._canonical_root+ for index, part in enumerate(parts):+ if not current.is_dir():+ if not (allow_missing and not current.exists()):+ raise NotADirectoryError(current)+ if part == "..":+ if current == self._canonical_root:+ raise PathEscapeError(f"Symlink target escapes root {self.root}")+ current = current.parent+ continue+ candidate = current / part+ try:+ mode = self._entry_mode(candidate)+ except FileNotFoundError:+ if not allow_missing:+ raise+ current = candidate+ continue+ if stat.S_ISLNK(mode):+ if not self.allow_symlinks:+ raise SymlinkDeniedError(+ f"Refusing symlink {candidate}; explicitly allow symlinks "+ "on this FileHelper to use supported contained targets"+ )+ if not follow_leaf and index == len(parts) - 1:+ return candidate+ if candidate in links or len(links) >= 40:+ raise UnsupportedPathError(f"Symlink cycle or excessive chain: {candidate}")+ target = Path(os.readlink(candidate))+ target_parts = self._parts(target)+ if not target.is_absolute():+ target_parts = current.relative_to(self._canonical_root).parts + target_parts+ # Resolve the link target strictly, even when creating a new child.+ current = self._walk(target_parts, links=links + (candidate,))+ elif stat.S_ISDIR(mode) or stat.S_ISREG(mode):+ current = candidate+ else:+ raise UnsupportedPathError(f"Unsupported filesystem object: {candidate}")+ return current++ def _path(+ self, path: Path | str, *, allow_missing: bool = False, follow_leaf: bool = True+ ) -> Path:+ original = Path(path)+ parts = self._parts(original)+ if ".." in parts:+ raise PathEscapeError(f"Parent traversal is not an operation path: {original}")+ return self._walk(+ parts, allow_missing=allow_missing, follow_leaf=follow_leaf+ )++ @staticmethod+ def _require_file(path: Path) -> None:+ if not stat.S_ISREG(path.stat().st_mode):+ raise UnsupportedPathError(f"Expected a regular file: {path}")++ def mkdir(+ self, path: Path | str, *, parents: bool = False, exist_ok: bool = False+ ) -> None:+ """Create a directory, preflighting the entire requested hierarchy."""+ destination = self._path(path, allow_missing=True)+ destination.mkdir(parents=parents, exist_ok=exist_ok)++ def read_bytes(self, path: Path | str) -> bytes:+ destination = self._path(path)+ self._require_file(destination)+ return destination.read_bytes()++ def read_text(self, path: Path | str, *, encoding: str = "utf-8") -> str:+ return self.read_bytes(path).decode(encoding)++ def create_bytes(self, path: Path | str, content: bytes, *, mode: int = 0o644) -> None:+ """Exclusively create a file; never overwrite an existing entry."""+ destination = self._path(path, allow_missing=True, follow_leaf=False)+ try:+ self._entry_mode(destination)+ except FileNotFoundError:+ pass+ else:+ raise FileExistsError(errno.EEXIST, os.strerror(errno.EEXIST), str(destination))+ flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL+ flags |= getattr(os, "O_NOFOLLOW", 0)+ fd = os.open(destination, flags, mode)+ with os.fdopen(fd, "wb") as stream:+ stream.write(content)++ def create_text(+ self, path: Path | str, content: str, *, encoding: str = "utf-8", mode: int = 0o644+ ) -> None:+ self.create_bytes(path, content.encode(encoding), mode=mode)++ def write_bytes(self, path: Path | str, content: bytes, *, mode: int = 0o644) -> None:+ """Atomically create/replace a file, preserving any allowed leaf link."""+ destination = self._path(path, allow_missing=True)+ if destination.exists():+ self._require_file(destination)+ fd, temporary = tempfile.mkstemp(prefix=f".{destination.name}.", dir=destination.parent)+ temporary_path = Path(temporary)+ try:+ with os.fdopen(fd, "wb") as stream:+ stream.write(content)+ temporary_path.chmod(mode)+ if self._path(path, allow_missing=True) != destination:+ raise FileHelperError(f"Destination changed during write: {path}")+ os.replace(temporary_path, destination)+ finally:+ temporary_path.unlink(missing_ok=True)++ def write_text(+ self, path: Path | str, content: str, *, encoding: str = "utf-8", mode: int = 0o644+ ) -> None:+ self.write_bytes(path, content.encode(encoding), mode=mode)++ def symlink(self, target: Path | str, path: Path | str) -> None:+ """Create a link to an existing contained regular file or directory.++ Relative targets use the link's parent, matching ``Path.symlink_to``.+ """+ if not self.allow_symlinks:+ raise SymlinkDeniedError("Symlink creation requires explicit allow_symlinks=True")+ destination = self._path(path, allow_missing=True, follow_leaf=False)+ target = Path(target)+ target_parts = self._parts(target)+ if not target.is_absolute():+ target_parts = destination.parent.relative_to(self._canonical_root).parts + target_parts+ resolved = self._walk(target_parts)+ destination.symlink_to(target, target_is_directory=resolved.is_dir())++ def _deletion_plan(self, path: Path, *, recursive: bool) -> list[tuple[Path, bool]]:+ mode = self._entry_mode(path)+ if stat.S_ISLNK(mode):+ if not self.allow_symlinks:+ raise SymlinkDeniedError(f"Refusing to delete symlink: {path}")+ return [(path, False)]+ if stat.S_ISREG(mode):+ return [(path, False)]+ if not stat.S_ISDIR(mode):+ raise UnsupportedPathError(f"Unsupported filesystem object: {path}")+ plan: list[tuple[Path, bool]] = []+ if recursive:+ with os.scandir(path) as entries:+ children = sorted((Path(entry.path) for entry in entries))+ for child in children:+ plan.extend(self._deletion_plan(child, recursive=True))+ plan.append((path, True))+ return plan++ def delete(self, path: Path | str, *, recursive: bool = False) -> None:+ """Delete an entry; recursive deletion never follows descendant links."""+ destination = self._path(path, follow_leaf=False)+ if destination == self._canonical_root:+ raise FileHelperError(f"Refusing to delete the established root: {self.root}")+ plan = self._deletion_plan(destination, recursive=recursive)+ for entry, directory in plan:+ # Recheck accessed parents/leaf before each mutation, not just preflight.+ checked = self._path(entry, follow_leaf=False)+ if checked != entry:+ raise FileHelperError(f"Destination changed during deletion: {entry}")+ if directory:+ entry.rmdir()+ else:+ entry.unlink()diff --git a/src/specify_cli/integration_status.py b/src/specify_cli/integration_status.pyindex 99714c74a..7733b3750 100644--- a/src/specify_cli/integration_status.py+++ b/src/specify_cli/integration_status.py@@ -8,6 +8,7 @@ import statfrom pathlib import Pathfrom typing import Any+from .file_helper import _strip_extended_length_prefixfrom .integration_state import (INTEGRATION_JSON,INTEGRATION_STATE_SCHEMA,@@ -95,22 +96,6 @@ def _sha256_file(path: Path) -> str:return h.hexdigest()-def _strip_extended_length_prefix(path: Path) -> Path:- """Drop the Windows ``\\\\?\\`` extended-length prefix for path comparison.-- ``os.readlink`` and ``Path.resolve`` can return extended-length paths on- Windows (e.g. ``\\\\?\\C:\\proj``). Comparing such a path against a plain- ``C:\\proj`` root via :meth:`Path.relative_to` would spuriously fail, so we- normalise both sides through this helper before containment checks.- """- raw = str(path)- if raw.startswith("\\\\?\\UNC\\"):- return Path("\\\\" + raw[len("\\\\?\\UNC\\"):])- if raw.startswith("\\\\?\\"):- return Path(raw[len("\\\\?\\"):])- return path--def _is_within_project(project_root_resolved: Path, candidate: Path) -> bool:"""Return ``True`` when *candidate* stays within *project_root_resolved*.diff --git a/tests/test_file_helper.py b/tests/test_file_helper.pynew file mode 100644index 000000000..c7da7239b--- /dev/null+++ b/tests/test_file_helper.py@@ -0,0 +1,948 @@+"""Operation-level evidence for the scoped FileHelper foundation."""++from dataclasses import FrozenInstanceError+import errno+import os+from pathlib import Path, PureWindowsPath+import subprocess+from types import SimpleNamespace++import pytest++from specify_cli.file_helper import (+ FileHelper,+ FileHelperError,+ PathEscapeError,+ SymlinkDeniedError,+ UnsupportedPathError,+)+++def root(tmp_path):+ path = tmp_path / "project"+ path.mkdir()+ return path+++def link(root):+ """Skip link-specific tests only on hosts unable to create symlinks."""+ probe = root / "probe"+ try:+ probe.symlink_to(root, target_is_directory=True)+ except (NotImplementedError, OSError) as exc:+ pytest.skip(f"Symlink creation unavailable: {exc}")+ probe.unlink()++ def create(path, target):+ path.symlink_to(target, target_is_directory=Path(target).is_dir())+ return path++ return create++[email protected]("allow", [False, True])+def test_plain_operations(root, allow):+ files = FileHelper(root, allow_symlinks=allow)+ files.mkdir("nested/child", parents=True)+ files.mkdir("nested/child", exist_ok=True)+ files.create_text("nested/child/text", "caf\u00e9\n")+ assert files.read_text("nested/child/text") == "caf\u00e9\n"+ files.write_text("nested/child/text", "updated")+ assert files.read_bytes(root / "nested/child/text") == b"updated"+ files.write_bytes("nested/child/new", b"\x00\xff")+ assert files.read_bytes("nested/child/new") == b"\x00\xff"+ files.create_bytes("binary", b"\xff", mode=0o600)+ files.delete("binary")+ assert not (root / "binary").exists()+ files.delete("nested", recursive=True)+ assert list(root.iterdir()) == []++[email protected]("operation", ["read_bytes", "write_bytes", "create_bytes", "mkdir", "delete"])[email protected]("kind", ["leaf", "parent", "dangling"])+def test_deny_rejects_accessed_links_without_mutation(root, link, operation, kind):+ target = root / "target"+ target.mkdir()+ (target / "file").write_bytes(b"old")+ if kind == "parent":+ path = link(root / "alias", target) / "file"+ else:+ path = link(root / "alias", target / ("missing" if kind == "dangling" else "file"))+ files = FileHelper(root)+ args = (path, b"new") if operation in ("write_bytes", "create_bytes") else (path,)+ with pytest.raises(SymlinkDeniedError, match="symlink"):+ getattr(files, operation)(*args)+ assert (root / "alias").is_symlink()+ assert (target / "file").read_bytes() == b"old"+ assert not (target / "missing").exists()+++def test_allow_read_and_atomic_update_preserve_chain_and_target(root, link, monkeypatch):+ target = root / "target"+ target.write_bytes(b"old")+ first = link(root / "first", "target")+ second = link(root / "second", "first")+ files = FileHelper(root, allow_symlinks=True)+ assert files.read_text(second) == "old"+ replacements = []+ replace = os.replace++ def observe(source, destination):+ replacements.append((Path(source), destination))+ assert first.is_symlink() and second.is_symlink()+ assert target.read_bytes() == b"old"+ replace(source, destination)++ monkeypatch.setattr("specify_cli.file_helper.os.replace", observe)+ files.write_text(second, "new")+ assert len(replacements) == 1+ assert replacements[0][0].parent == target.parent+ assert replacements[0][1] == target+ assert os.readlink(first) == "target"+ assert os.readlink(second) == "first"+ assert target.read_bytes() == b"new"+ assert sorted(p.name for p in root.iterdir()) == ["first", "second", "target"]+++def test_allow_operations_through_linked_parent(root, link):+ target = root / "target"+ target.mkdir()+ alias = link(root / "alias", target)+ files = FileHelper(root, allow_symlinks=True)+ files.mkdir(alias / "created/child", parents=True)+ files.create_text(alias / "created/file", "old")+ assert files.read_text(alias / "created/file") == "old"+ files.write_text(alias / "created/file", "new")+ assert (target / "created/file").read_text() == "new"+ files.delete(alias / "created", recursive=True)+ assert alias.is_symlink() and target.is_dir()+ assert list(target.iterdir()) == []+++def test_delete_through_parent_link_removes_real_file_not_parent_link(root, link):+ target = root / "target"+ target.mkdir()+ (target / "file").write_text("delete")+ alias = link(root / "alias", target)+ FileHelper(root, allow_symlinks=True).delete(alias / "file")+ assert alias.is_symlink()+ assert target.is_dir()+ assert not (target / "file").exists()++[email protected]("allow", [False, True])+def test_empty_directory_nonrecursive_delete(root, allow):+ files = FileHelper(root, allow_symlinks=allow)+ files.mkdir("empty")+ files.delete("empty")+ assert not (root / "empty").exists()++[email protected]("operation", ["mkdir", "create_bytes", "write_bytes", "delete"])+def test_dangling_parent_cannot_be_used_for_mutation(root, link, operation):+ alias = link(root / "alias", root / "missing")+ files = FileHelper(root, allow_symlinks=True)+ path = alias / "child"+ args = (path, b"bad") if operation in ("create_bytes", "write_bytes") else (path,)+ with pytest.raises(FileNotFoundError):+ getattr(files, operation)(*args)+ assert alias.is_symlink()+ assert not (root / "missing").exists()+++def test_multi_link_cycle_and_excessive_chain_fail_explicitly(root, link):+ link(root / "first", "second")+ link(root / "second", "first")+ files = FileHelper(root, allow_symlinks=True)+ with pytest.raises(UnsupportedPathError, match="cycle"):+ files.read_bytes("first")+ (root / "target").write_text("ok")+ for index in reversed(range(41)):+ link(root / f"chain-{index}", "target" if index == 40 else f"chain-{index + 1}")+ with pytest.raises(UnsupportedPathError, match="excessive chain"):+ files.read_bytes("chain-0")++[email protected]("operation", ["read_bytes", "write_bytes", "mkdir", "create_bytes", "delete"])+def test_external_parent_is_never_traversed(root, link, operation):+ outside = root.parent / "outside"+ outside.mkdir()+ (outside / "file").write_bytes(b"old")+ alias = link(root / "alias", outside)+ files = FileHelper(root, allow_symlinks=True)+ path = alias / "file"+ args = (path, b"new") if operation in ("write_bytes", "create_bytes") else (path,)+ with pytest.raises(PathEscapeError):+ getattr(files, operation)(*args)+ assert (outside / "file").read_bytes() == b"old"+ assert alias.is_symlink()++[email protected]("kind", ["external", "dangling", "cycle"])[email protected]("operation", ["read_bytes", "write_bytes"])+def test_allow_reads_and_updates_reject_invalid_targets(root, link, kind, operation):+ if kind == "external":+ target = root.parent / "outside"+ target.write_bytes(b"old")+ error = PathEscapeError+ elif kind == "dangling":+ target = root / "missing"+ error = FileNotFoundError+ else:+ target = root / "alias"+ error = UnsupportedPathError+ alias = link(root / "alias", target)+ args = (alias, b"new") if operation == "write_bytes" else (alias,)+ with pytest.raises(error):+ getattr(FileHelper(root, allow_symlinks=True), operation)(*args)+ assert alias.is_symlink()+ if kind == "external":+ assert target.read_bytes() == b"old"+ if kind == "dangling":+ assert not target.exists()++[email protected]("kind", ["file", "directory", "external", "dangling", "cycle"])[email protected]("recursive", [False, True])+def test_allow_leaf_delete_unlinks_only_link(root, link, kind, recursive):+ target = root / "target"+ if kind == "file":+ target.write_bytes(b"keep")+ elif kind == "directory":+ target.mkdir()+ (target / "keep").write_bytes(b"keep")+ elif kind == "external":+ target = root.parent / "outside"+ target.write_bytes(b"keep")+ elif kind == "cycle":+ target = root / "alias"+ alias = link(root / "alias", target)+ FileHelper(root, allow_symlinks=True).delete(alias, recursive=recursive)+ assert not os.path.lexists(alias)+ if kind in ("file", "external"):+ assert target.read_bytes() == b"keep"+ elif kind == "directory":+ assert (target / "keep").read_bytes() == b"keep"+++def test_recursive_deny_preflight_leaves_entire_tree_untouched(root, link):+ tree = root / "tree"+ tree.mkdir()+ (tree / "a-file").write_bytes(b"keep")+ (tree / "b-dir").mkdir()+ (tree / "b-dir/keep").write_bytes(b"keep")+ alias = link(tree / "z-link", root / "missing")+ with pytest.raises(SymlinkDeniedError):+ FileHelper(root).delete(tree, recursive=True)+ assert (tree / "a-file").read_bytes() == b"keep"+ assert (tree / "b-dir/keep").read_bytes() == b"keep"+ assert alias.is_symlink()+++def test_recursive_allow_does_not_descend_through_links(root, link):+ tree = root / "tree"+ tree.mkdir()+ target = root / "retained"+ target.mkdir()+ (target / "keep").write_bytes(b"keep")+ outside = root.parent / "outside"+ outside.mkdir()+ (outside / "keep").write_bytes(b"keep")+ link(tree / "internal", target)+ link(tree / "external", outside)+ link(tree / "dangling", root / "missing")+ link(tree / "cycle", tree)+ (tree / "ordinary").write_bytes(b"delete")+ FileHelper(root, allow_symlinks=True).delete(tree, recursive=True)+ assert not tree.exists()+ assert (target / "keep").read_bytes() == b"keep"+ assert (outside / "keep").read_bytes() == b"keep"+++def test_deletion_rechecks_parents_after_preflight(root, link, monkeypatch):+ tree = root / "tree"+ (tree / "nested").mkdir(parents=True)+ (tree / "nested/file").write_text("keep")+ plan = FileHelper._deletion_plan++ def exchange(self, path, *, recursive):+ result = plan(self, path, recursive=recursive)+ if path == tree:+ (tree / "nested").rename(root / "retained")+ link(tree / "nested", root / "retained")+ return result++ monkeypatch.setattr(FileHelper, "_deletion_plan", exchange)+ with pytest.raises(FileHelperError, match="changed during deletion"):+ FileHelper(root, allow_symlinks=True).delete(tree, recursive=True)+ assert (root / "retained/file").read_text() == "keep"+ assert (tree / "nested").is_symlink()++[email protected]("allow", [False, True])+def test_unrelated_symlink_is_outside_operation_scope(root, link, allow):+ link(root / "unrelated", root.parent / "missing")+ files = FileHelper(root, allow_symlinks=allow)+ files.create_text("selected", "works")+ assert files.read_text("selected") == "works"+ files.delete("selected")+ assert (root / "unrelated").is_symlink()++[email protected]("allow", [False, True])+def test_trusted_root_alias_and_os_ancestors_are_not_rejected(root, link, allow):+ alias = link(root.parent / "root-alias", root)+ ancestor = link(root.parent / "ancestor-alias", root.parent)+ for supplied in (alias, ancestor / root.name):+ files = FileHelper(supplied, allow_symlinks=allow)+ files.write_text("file", "works")+ assert files.read_text(supplied / "file") == "works"+ assert files.read_text(root / "file") == "works"++[email protected]("allow", [False, True])[email protected]("relative_root", [False, True])+def test_operations_derived_from_trusted_parent_traversal_root(root, monkeypatch, allow, relative_root):+ anchor = root.parent / "anchor"+ anchor.mkdir()+ if relative_root:+ monkeypatch.chdir(anchor)+ supplied = Path("../project")+ else:+ supplied = anchor / ".." / root.name+ files = FileHelper(supplied, allow_symlinks=allow)+ assert ".." in files.root.parts+ directory = files.root / "created"+ files.mkdir(directory)+ files.create_text(directory / "file", "old")+ assert files.read_text(directory / "file") == "old"+ files.write_text(directory / "file", "new")+ assert (root / "created/file").read_text() == "new"+ assert files.read_text(root.resolve() / "created/file") == "new"+ files.delete(directory / "file")+ files.write_bytes(directory / "new", b"new")+ files.delete(directory, recursive=True)+ assert not (root / "created").exists()+ with pytest.raises(FileHelperError, match="established root"):+ files.delete(files.root, recursive=True)+ assert root.is_dir()++[email protected]("allow", [False, True])[email protected]("relative_root", [False, True])+def test_trusted_parent_traversal_root_does_not_permit_operation_suffix_traversal(+ root, monkeypatch, allow, relative_root+):+ anchor = root.parent / "anchor"+ anchor.mkdir()+ outside = root.parent / "outside"+ outside.mkdir()+ (outside / "keep").write_bytes(b"keep")+ if relative_root:+ monkeypatch.chdir(anchor)+ supplied = Path("../project")+ else:+ supplied = anchor / ".." / root.name+ files = FileHelper(supplied, allow_symlinks=allow)+ for path in (files.root / "../outside/keep", Path("../outside/keep"),+ files.root / "inside/../../outside/keep"):+ for operation in (+ lambda: files.read_bytes(path),+ lambda: files.write_bytes(path, b"bad"),+ lambda: files.create_bytes(path, b"bad"),+ lambda: files.mkdir(path, parents=True),+ lambda: files.delete(path),+ ):+ with pytest.raises(PathEscapeError, match="Parent traversal"):+ operation()+ assert (outside / "keep").read_bytes() == b"keep"+ assert list(root.iterdir()) == []++[email protected](os.name == "nt", reason="POSIX symlink/parent traversal semantics required")[email protected]("allow", [False, True])+def test_trusted_root_parent_traversal_is_not_lexically_collapsed(root, link, allow):+ container = root.parent / "different/container"+ container.mkdir(parents=True)+ selected = root.parent / "different/project"+ selected.mkdir()+ alias = link(root.parent / "root-entry", container)+ files = FileHelper(alias / "../project", allow_symlinks=allow)+ files.create_text(files.root / "file", "selected")+ assert (selected / "file").read_text() == "selected"+ assert list(root.iterdir()) == []+ assert alias.is_symlink()++[email protected]("path", ["../escape", "inside/../escape"])+def test_operation_parent_traversal_is_rejected(root, path):+ with pytest.raises(PathEscapeError):+ FileHelper(root).mkdir(path, parents=True)+ assert list(root.iterdir()) == []+++def test_absolute_escape_and_root_deletion_rejected(root):+ files = FileHelper(root)+ with pytest.raises(PathEscapeError):+ files.write_text(root.parent / "outside", "bad")+ with pytest.raises(FileHelperError, match="established root"):+ files.delete(".", recursive=True)+ assert root.is_dir()+++def test_relative_link_targets_are_walked_without_losing_evidence(root, link):+ directory = root / "directory"+ directory.mkdir()+ (root / "file").write_text("ok")+ link(directory / "valid", "../file")+ files = FileHelper(root, allow_symlinks=True)+ assert files.read_text("directory/valid") == "ok"+ link(directory / "escape", "../../outside")+ with pytest.raises(PathEscapeError):+ files.read_text("directory/escape")+ link(root / "inner", root.parent)+ link(root / "indirect", "inner/project/file")+ with pytest.raises(PathEscapeError):+ files.read_text("indirect")+ link(root / "invalid", "file/../file")+ with pytest.raises(NotADirectoryError):+ files.read_text("invalid")+++def test_intermediate_target_link_is_checked(root, link):+ outside = root.parent / "outside"+ outside.mkdir()+ (outside / "file").write_text("bad")+ link(root / "indirection", outside)+ link(root / "alias", root / "indirection/file")+ with pytest.raises(PathEscapeError):+ FileHelper(root, allow_symlinks=True).read_text("alias")++[email protected]("allow", [False, True])[email protected]("entry", ["file", "alias", "dangling"])+def test_exclusive_create_never_overwrites_file_or_link(root, link, allow, entry):+ (root / "file").write_bytes(b"keep")+ alias = link(root / "alias", root / "file")+ dangling = link(root / "dangling", root / "missing")+ files = FileHelper(root, allow_symlinks=allow)+ path = root / entry+ error = SymlinkDeniedError if path.is_symlink() and not allow else FileExistsError+ with pytest.raises(error):+ files.create_bytes(path, b"bad")+ assert (root / "file").read_bytes() == b"keep"+ assert alias.is_symlink() and dangling.is_symlink()+ assert not (root / "missing").exists()++[email protected]("operation", ["create_bytes", "create_text"])[email protected]("cyclic", [False, True])+def test_exclusive_create_rejects_existing_leaf_before_open(+ root, link, monkeypatch, operation, cyclic+):+ target = root / "target"+ target.write_bytes(b"keep")+ alias = link(root / "alias", root / "alias" if cyclic else target)+ original_target = os.readlink(alias)+ opened = []+ real_open = os.open++ def recording_open(path, flags, mode):+ opened.append(Path(path))+ return real_open(path, flags, mode)++ monkeypatch.setattr("specify_cli.file_helper.os.open", recording_open)+ content = b"bad" if operation == "create_bytes" else "bad"+ with pytest.raises(FileExistsError) as error:+ getattr(FileHelper(root, allow_symlinks=True), operation)(alias, content)+ assert error.value.errno == errno.EEXIST+ assert opened == []+ assert alias.is_symlink()+ assert os.readlink(alias) == original_target+ assert target.read_bytes() == b"keep"++[email protected]("operation", ["create_bytes", "create_text"])[email protected]("external", [False, True])+def test_exclusive_create_rejects_dangling_leaf_with_windows_backend(+ root, link, monkeypatch, operation, external+):+ target = root.parent / "external-missing" if external else root / "missing"+ alias = link(root / "alias", target)+ original_target = os.readlink(alias)+ opened = []+ real_open = os.open+ monkeypatch.delattr("specify_cli.file_helper.os.O_NOFOLLOW", raising=False)++ def windows_open(path, flags, mode):+ opened.append(Path(path))+ assert flags & os.O_CREAT and flags & os.O_EXCL+ return real_open(Path(os.readlink(path)), flags, mode)++ monkeypatch.setattr("specify_cli.file_helper.os.open", windows_open)+ content = b"bad" if operation == "create_bytes" else "bad"+ with pytest.raises(FileExistsError) as error:+ getattr(FileHelper(root, allow_symlinks=True), operation)(alias, content)+ assert error.value.errno == errno.EEXIST+ assert opened == []+ assert alias.is_symlink()+ assert os.readlink(alias) == original_target+ assert not os.path.lexists(target)+++def test_symlink_creation_requires_permission_and_contained_target(root, link):+ (root / "file").write_text("ok")+ with pytest.raises(SymlinkDeniedError):+ FileHelper(root).symlink("file", "denied")+ assert not os.path.lexists(root / "denied")+ files = FileHelper(root, allow_symlinks=True)+ files.symlink("file", "allowed")+ assert os.readlink(root / "allowed") == "file"+ assert files.read_text("allowed") == "ok"+ files.mkdir("directory")+ files.symlink("../file", "directory/relative")+ assert files.read_text("directory/relative") == "ok"+ files.symlink("directory", "directory-alias")+ assert (root / "directory-alias").is_dir()+ with pytest.raises(FileNotFoundError):+ files.symlink("missing", "dangling")+ with pytest.raises(PathEscapeError):+ files.symlink(root.parent / "outside", "escape")+ with pytest.raises(FileExistsError):+ files.symlink("file", "allowed")+ assert not os.path.lexists(root / "dangling")+ assert not os.path.lexists(root / "escape")+++def test_missing_wrong_type_and_nonempty_failures(root):+ files = FileHelper(root)+ with pytest.raises(FileNotFoundError):+ files.read_bytes("missing")+ with pytest.raises(FileNotFoundError):+ files.delete("missing")+ with pytest.raises(FileNotFoundError):+ files.create_text("missing/file", "bad")+ with pytest.raises(FileNotFoundError):+ files.write_text("missing/file", "bad")+ files.mkdir("directory")+ files.create_text("directory/file", "keep")+ for operation in (lambda: files.read_bytes("directory"),+ lambda: files.write_text("directory", "bad")):+ with pytest.raises(UnsupportedPathError):+ operation()+ with pytest.raises(NotADirectoryError):+ files.mkdir("directory/file/child", parents=True)+ with pytest.raises(OSError):+ files.delete("directory")+ assert files.read_text("directory/file") == "keep"++[email protected](not hasattr(os, "mkfifo"), reason="POSIX special files required")[email protected]("allow", [False, True])+def test_special_objects_fail_before_read_update_or_recursive_mutation(root, allow):+ files = FileHelper(root, allow_symlinks=allow)+ files.mkdir("tree")+ files.create_text("tree/a-file", "keep")+ os.mkfifo(root / "tree/z-fifo")+ for operation in (lambda: files.read_bytes("tree/z-fifo"),+ lambda: files.write_bytes("tree/z-fifo", b"bad"),+ lambda: files.delete("tree", recursive=True)):+ with pytest.raises(UnsupportedPathError):+ operation()+ assert files.read_text("tree/a-file") == "keep"+ assert (root / "tree/z-fifo").exists()+++def test_atomic_failure_cleans_temp_and_preserves_target(root, monkeypatch):+ files = FileHelper(root)+ files.create_text("file", "old")++ def fail(*args):+ raise PermissionError("replacement denied")++ monkeypatch.setattr("specify_cli.file_helper.os.replace", fail)+ with pytest.raises(PermissionError, match="replacement denied"):+ files.write_text("file", "new")+ assert files.read_text("file") == "old"+ assert list(root.iterdir()) == [root / "file"]+++def test_native_permission_failure_is_not_suppressed(root, monkeypatch):+ files = FileHelper(root)++ def fail(*args, **kwargs):+ raise PermissionError("creation denied")++ monkeypatch.setattr("specify_cli.file_helper.os.open", fail)+ with pytest.raises(PermissionError, match="creation denied"):+ files.create_bytes("file", b"bad")+ assert list(root.iterdir()) == []++[email protected](os.name == "nt", reason="POSIX permission bits required")+def test_atomic_target_replacement_uses_requested_mode(root, link):+ target = root / "target"+ target.write_text("old")+ alias = link(root / "alias", target)+ FileHelper(root, allow_symlinks=True).write_bytes(alias, b"new", mode=0o600)+ assert target.stat().st_mode & 0o777 == 0o600+ assert alias.is_symlink()+++def test_atomic_write_rechecks_original_link(root, link, monkeypatch):+ first = root / "first"+ first.write_text("first")+ second = root / "second"+ second.write_text("second")+ alias = link(root / "alias", first)+ chmod = Path.chmod++ def exchange(path, mode, **kwargs):+ chmod(path, mode, **kwargs)+ alias.unlink()+ alias.symlink_to(second)++ monkeypatch.setattr(Path, "chmod", exchange)+ with pytest.raises(FileHelperError, match="changed during write"):+ FileHelper(root, allow_symlinks=True).write_text(alias, "bad")+ assert first.read_text() == "first"+ assert second.read_text() == "second"+ assert sorted(p.name for p in root.iterdir()) == ["alias", "first", "second"]+++def test_policy_is_immutable_and_helpers_are_independent(root, link):+ (root / "file").write_text("ok")+ link(root / "alias", "file")+ deny = FileHelper(root)+ allow = FileHelper(root, allow_symlinks=True)+ with pytest.raises(FrozenInstanceError):+ deny.allow_symlinks = True+ assert allow.read_text("alias") == "ok"+ with pytest.raises(SymlinkDeniedError):+ deny.read_text("alias")+++def test_root_must_be_existing_directory(root):+ with pytest.raises(FileNotFoundError):+ FileHelper(root / "missing")+ (root / "file").write_text("file")+ with pytest.raises(NotADirectoryError):+ FileHelper(root / "file")++[email protected]("spelling", ["/outside/file", r"\outside\file", "C:outside/file", "C:"])+def test_windows_anchored_relative_forms_rejected_portably(root, spelling):+ path = PureWindowsPath(spelling)+ assert path.anchor and not path.is_absolute()+ with pytest.raises(PathEscapeError):+ FileHelper(root)._parts(path)++[email protected]("spelling", ["inside/file", r"inside\file", "."])+def test_windows_unanchored_relative_forms_are_root_relative(root, spelling):+ path = PureWindowsPath(spelling)+ assert FileHelper(root)._parts(path) == path.parts++[email protected]("spelling", ["C:/outside/file", r"\\server\share\outside"])+def test_windows_true_absolute_forms_do_not_bypass_scoped_matching(root, spelling):+ with pytest.raises(PathEscapeError):+ FileHelper(root)._parts(PureWindowsPath(spelling))+++ "spelling",+ ["D:/project/inside/file", "d:/PROJECT/inside/file", r"\\server\share\project\inside\file"],+)+def test_windows_contained_absolute_forms_match_roots_portably(spelling):+ boundary = SimpleNamespace(+ root=PureWindowsPath("D:/project"),+ _canonical_root=PureWindowsPath(r"\\server\share\project"),+ )+ assert FileHelper._parts(boundary, PureWindowsPath(spelling)) == ("inside", "file")+++ "spelling",+ ["D:/project2/file", "D:/outside/file", "C:/project/file", r"\\server\share\project2\file"],+)+def test_windows_absolute_forms_outside_declared_roots_rejected_portably(spelling):+ boundary = SimpleNamespace(+ root=PureWindowsPath("D:/project"),+ _canonical_root=PureWindowsPath(r"\\server\share\project"),+ )+ with pytest.raises(PathEscapeError):+ FileHelper._parts(boundary, PureWindowsPath(spelling))++[email protected]("unc", [False, True])[email protected]("root_extended", [False, True])[email protected]("target_extended", [False, True])+def test_windows_extended_contained_targets_match_roots_portably(+ unc, root_extended, target_extended+):+ plain = r"\\server\share\project" if unc else r"D:\project"+ extended = r"\\?\UNC\server\share\project" if unc else r"\\?\D:\project"+ root_path = PureWindowsPath(extended if root_extended else plain)+ target = PureWindowsPath(extended if target_extended else plain) / "inside/file"+ boundary = SimpleNamespace(root=root_path, _canonical_root=root_path)+ assert FileHelper._parts(boundary, target) == ("inside", "file")++[email protected]("marker", ["unc", "uNc", "UnC", "UNC"])[email protected]("prefixed_root", [False, True])+def test_windows_mixed_case_unc_prefixes_preserve_contained_targets(marker, prefixed_root):+ plain = r"\\Server\Share\Project"+ prefixed = "\\\\?\\" + marker + r"\Server\Share\Project"+ root_path = PureWindowsPath(prefixed if prefixed_root else plain)+ boundary = SimpleNamespace(root=root_path, _canonical_root=root_path)+ target = PureWindowsPath(prefixed + r"\ChIlD\FiLe")+ assert FileHelper._parts(boundary, target) == ("ChIlD", "FiLe")++[email protected]("marker", ["unc", "uNc", "UnC", "UNC"])+def test_windows_mixed_case_unc_prefixes_do_not_allow_external_targets(marker):+ root_path = PureWindowsPath(r"\\Server\Share\Project")+ boundary = SimpleNamespace(root=root_path, _canonical_root=root_path)+ target = PureWindowsPath("\\\\?\\" + marker + r"\Server\Share\ProjectSibling\file")+ with pytest.raises(PathEscapeError):+ FileHelper._parts(boundary, target)+++ "spelling",+ [+ r"\\?\D:\project2\file",+ r"\\?\D:\outside\file",+ r"\\?\C:\project\file",+ r"\\?\UNC\server\share\project2\file",+ r"\\?\UNC\other\share\project\file",+ r"\\?\GLOBALROOT\Device\HarddiskVolume1\file",+ r"\\?\C:relative\file",+ ],+)+def test_windows_extended_external_or_unsupported_targets_rejected_portably(spelling):+ boundary = SimpleNamespace(+ root=PureWindowsPath("D:/project"),+ _canonical_root=PureWindowsPath(r"\\server\share\project"),+ )+ with pytest.raises(PathEscapeError):+ FileHelper._parts(boundary, PureWindowsPath(spelling))+++def test_windows_extended_comparison_preserves_accessed_hierarchy_portably():+ boundary = SimpleNamespace(+ root=PureWindowsPath("D:/project"),+ _canonical_root=PureWindowsPath("D:/project"),+ )+ assert FileHelper._parts(+ boundary, PureWindowsPath(r"\\?\D:\project\linked\..\file")+ ) == ("linked", "..", "file")++[email protected](os.name == "nt", reason="POSIX literal backslash filename semantics required")+def test_posix_windows_like_filenames_are_not_reinterpreted(root, link):+ name = r"\\?\D:\literal"+ files = FileHelper(root, allow_symlinks=True)+ files.create_text(name, "old")+ files.symlink(name, "alias")+ assert files.read_text("alias") == "old"+ files.write_text("alias", "new")+ assert (root / name).read_text() == "new"+ assert (root / "alias").is_symlink()++[email protected](os.name != "nt", reason="Native Windows symlink semantics required")[email protected]("root_extended", [False, True])[email protected]("external", [False, True])+def test_native_windows_extended_symlink_read_update_and_creation(+ root, link, root_extended, external+):+ target = root.parent / "outside" if external else root / "target"+ target.write_text("old")++ def extended(path):+ raw = str(path)+ return "\\\\?\\UNC\\" + raw[2:] if raw.startswith("\\\\") else "\\\\?\\" + raw++ alias = link(root / "alias", extended(target))+ original_target = os.readlink(alias)+ files = FileHelper(Path(extended(root)) if root_extended else root, allow_symlinks=True)+ if external:+ with pytest.raises(PathEscapeError):+ files.read_text("alias")+ with pytest.raises(PathEscapeError):+ files.write_text("alias", "bad")+ with pytest.raises(PathEscapeError):+ files.symlink(extended(target), "new")+ assert target.read_text() == "old"+ assert not os.path.lexists(root / "new")+ else:+ assert files.read_text("alias") == "old"+ files.write_text("alias", "new")+ assert target.read_text() == "new"+ assert alias.is_symlink()+ assert os.readlink(alias) == original_target+ files.symlink(extended(target), "created")+ assert files.read_text("created") == "new"+ files.delete("alias")+ assert not os.path.lexists(alias)+ assert target.exists()++[email protected](os.name != "nt", reason="Native Windows path semantics required")[email protected]("spelling", ["/outside/file", r"\outside\file", "C:outside/file", "C:"])[email protected]("operation", ["read_bytes", "create_bytes", "write_bytes", "mkdir", "delete"])[email protected]("allow", [False, True])+def test_native_windows_anchored_relative_operations_rejected(root, spelling, operation, allow):+ args = (spelling, b"bad") if operation in ("create_bytes", "write_bytes") else (spelling,)+ with pytest.raises(PathEscapeError):+ getattr(FileHelper(root, allow_symlinks=allow), operation)(*args)+ assert list(root.iterdir()) == []++[email protected](os.name != "nt", reason="Native Windows path semantics required")[email protected]("spelling", ["/outside/file", r"\outside\file", "C:outside/file", "C:"])+def test_native_windows_invalid_link_targets_rejected(root, link, monkeypatch, spelling):+ (root / "file").write_text("keep")+ alias = link(root / "alias", root / "file")+ files = FileHelper(root, allow_symlinks=True)+ with pytest.raises(PathEscapeError):+ files.symlink(spelling, "new")+ monkeypatch.setattr("specify_cli.file_helper.os.readlink", lambda path: spelling)+ with pytest.raises(PathEscapeError):+ files.read_text(alias)+ with pytest.raises(PathEscapeError):+ files.write_text(alias, "bad")+ assert (root / "file").read_text() == "keep"+ assert not os.path.lexists(root / "new")++[email protected](os.name != "nt", reason="Native Windows path semantics required")+def test_native_windows_absolute_and_relative_scoping(root):+ files = FileHelper(root)+ files.write_text(root / "absolute", "ok")+ files.write_text("relative", "ok")+ assert files.read_text(root / "absolute") == "ok"+ assert files.read_text("relative") == "ok"+ with pytest.raises(PathEscapeError):+ files.write_text(root.parent / "outside", "bad")++[email protected]("allow", [False, True])[email protected]("recursive", [False, True])+def test_directory_reparse_entries_rejected_before_traversal_portably(+ root, monkeypatch, allow, recursive+):+ (root / "tree").mkdir()+ (root / "tree/a-file").write_text("keep")+ junction = root / "tree/z-junction"+ junction.mkdir()+ (junction / "keep").write_text("keep")+ lstat = Path.lstat++ def directory_reparse(path, **kwargs):+ result = lstat(path, **kwargs)+ if path == junction:+ return SimpleNamespace(+ st_mode=result.st_mode,+ st_file_attributes=0x400,+ st_reparse_tag=0xA0000003,+ )+ return result++ monkeypatch.setattr(Path, "lstat", directory_reparse)+ files = FileHelper(root, allow_symlinks=allow)+ for operation in (+ lambda: files.read_bytes(junction / "keep"),+ lambda: files.write_bytes(junction / "keep", b"bad"),+ lambda: files.create_bytes(junction / "new", b"bad"),+ lambda: files.mkdir(junction / "new-directory"),+ lambda: files.delete(junction, recursive=recursive),+ lambda: files.delete("tree", recursive=True),+ ):+ with pytest.raises(UnsupportedPathError, match="reparse"):+ operation()+ assert (root / "tree/a-file").read_text() == "keep"+ assert (junction / "keep").read_text() == "keep"+ assert not (junction / "new").exists()+ assert not (junction / "new-directory").exists()++[email protected]("allow", [False, True])+def test_symlink_reparse_entries_retain_normal_symlink_policy_portably(root, link, monkeypatch, allow):+ (root / "file").write_text("keep")+ alias = link(root / "alias", root / "file")+ lstat = Path.lstat++ def symlink_reparse(path, **kwargs):+ result = lstat(path, **kwargs)+ if path == alias:+ return SimpleNamespace(+ st_mode=result.st_mode, st_file_attributes=0x400, st_reparse_tag=0xA000000C,+ )+ return result++ monkeypatch.setattr(Path, "lstat", symlink_reparse)+ files = FileHelper(root, allow_symlinks=allow)+ if allow:+ assert files.read_text(alias) == "keep"+ files.write_text(alias, "updated")+ assert (root / "file").read_text() == "updated"+ files.delete(alias)+ assert not os.path.lexists(alias)+ else:+ with pytest.raises(SymlinkDeniedError):+ files.read_text(alias)+ with pytest.raises(SymlinkDeniedError):+ files.delete(alias)+ assert alias.is_symlink()+ assert (root / "file").read_text() == "keep"+++def junction(root):+ if os.name != "nt":+ pytest.skip("Native Windows junction creation required")++ def create(path, target):+ result = subprocess.run(+ ["cmd.exe", "/c", "mklink", "/J", str(path), str(target)],+ capture_output=True, text=True, check=False, timeout=30,+ )+ if result.returncode:+ pytest.skip(f"Windows junction creation unavailable: {result.stderr or result.stdout}")+ return path++ return create++[email protected]("allow", [False, True])[email protected]("external", [False, True])+def test_native_windows_junctions_never_traversed_or_deleted(root, junction, allow, external):+ target = root.parent / "outside" if external else root / "target"+ target.mkdir()+ (target / "keep").write_text("keep")+ tree = root / "tree"+ tree.mkdir()+ (tree / "a-file").write_text("keep")+ alias = junction(tree / "z-junction", target)+ files = FileHelper(root, allow_symlinks=allow)+ for operation in (+ lambda: files.read_text(alias / "keep"),+ lambda: files.write_text(alias / "keep", "bad"),+ lambda: files.create_text(alias / "new", "bad"),+ lambda: files.mkdir(alias / "new-directory"),+ lambda: files.delete(alias / "keep"),+ lambda: files.delete(alias),+ lambda: files.delete(alias, recursive=True),+ lambda: files.delete(tree, recursive=True),+ ):+ with pytest.raises(UnsupportedPathError, match="reparse"):+ operation()+ assert alias.exists()+ assert (target / "keep").read_text() == "keep"+ assert (tree / "a-file").read_text() == "keep"+ assert sorted(p.name for p in target.iterdir()) == ["keep"]