[mnriem]

Description

Use handle-based reads in FileHelper so path traversal, file-type checks, and reading operate on stable filesystem objects. Preserve supported contained symlinks, link chains, and trusted root aliases.

Extract the existing Windows handle primitive for reuse by FileHelper and catalog-cache I/O, add deterministic coverage for path replacement and handle cleanup, and update the FileHelper design contract. Narrow cleanup-fallback test fixtures to disable directory removal capabilities without disabling project reads.

Testing

Set up this checkout's .venv and editable install using the local development guide. Run commands from the checkout root.

• Tested locally with .venv/bin/specify --help (Windows PowerShell: .\.venv\Scripts\specify.exe --help)
• Ran relevant existing tests with .venv/bin/python -m pytest tests -q (Windows PowerShell: .\.venv\Scripts\python.exe -m pytest tests -q); use affected test paths for focused checks and LC_ALL=en_US.UTF-8 on macOS
• Tested with a sample project (if applicable)

Commands and results:

.venv/bin/specify --help
Passed.

LC_ALL=en_US.UTF-8 .venv/bin/python -m pytest tests/test_file_helper.py tests/specify_cli/test_file_policy.py tests/specify_cli/integrations/test_file_changes.py tests/specify_cli/workflows/test_catalog_cache.py tests/specify_cli/presets/test_command_remove.py tests/specify_cli/integrations/test_command_switch.py -q
555 passed, 82 skipped.

LC_ALL=en_US.UTF-8 .venv/bin/python -m pytest tests -q
14,841 passed, 136 skipped, 15 failed before narrowing the cleanup-fallback fixtures.
The subsequent focused run passes all 14 affected cleanup cases.
The remaining version-output formatting failure also reproduces with the original FileHelper implementation.

The remaining failure is tests/specify_cli/test_version_execution.py::TestWindowsUvToolEnvironment::test_non_windows_uv_tool_dry_run_still_previews_installer: terminal wrapping splits the long checkout interpreter path. No unrelated formatting change is included.

Native Windows execution was not available on the macOS host. Windows read-path wiring is covered with simulated handles; existing native Windows handle tests remain in the suite. A separate sample-project run is not applicable to this internal filesystem change.

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (fill in the disclosure below)

AI disclosure: Authored on behalf of @mnriem by GitHub Copilot using GPT-6.1 Sol (model ID: gpt-6.1-sol) in autonomous agent mode with runtime-default reasoning settings. AI assistance covered implementation, documentation, tests, automated checks, and this pull request description; no line-by-line human review is claimed.

[Copilot]

🟡 Changes recommended

The Windows branch reopens a pathname after validating its handle, allowing in-place reparse changes to redirect reads to an outside file.

4 open issues

• Read from the validated Windows handle, not a reopened path · New
• Use search-only directory handles for non-listable paths · New
• Close superseded parent descriptors during traversal · New
• Assert handles are pinned before the simulated Windows open · New

What changed in this PR

This PR moves FileHelper reads toward handle-based filesystem access while preserving the existing contained-symlink policy and trusted root aliases.

Changes:

• Add POSIX descriptor-relative traversal and Windows hierarchy pinning, with opened-file type checks.
• Extract the Windows handle primitive for reuse by FileHelper and catalog-cache I/O.
• Add replacement and cleanup coverage, narrow cleanup-fallback fixtures, and update the safety contract.

AI-generated review for the requester by GitHub Copilot (model/settings unavailable; autonomous analysis and suggested fixes).

File	Description
tests/​test_file_helper.py	Adds replacement, pinning, descriptor-cleanup, and unsupported-platform coverage.
tests/​specify_cli/​presets/​_skill_cleanup_helpers.py	Disables descriptor-relative removal without disabling safe reads.
src/​specify_cli/​workflows/​_catalog_cache.py	Reuses the extracted Windows handle helper.
src/​specify_cli/​file_helper.py	Introduces handle-based reads and descriptor type checks.
src/​specify_cli/​_file_handles.py	Provides the shared Windows handle primitive.
design/​file-helper.md	Documents read guarantees separately from mutation limitations.

_{Review effort: Max (auto)}

[Copilot]

🟡 Changes recommended

The native Windows tests fail before exercising the intended behavior because of invalid CreateFile arguments, with an additional failure caused by the nonempty-file symlink fixture.

3 open issues

• Pass integer NULL values to CreateFile · New
• Use an empty file for the Windows symlink fixture · New
• Revoke search permission after validating the file · New

4 resolved since last review

• Read from the validated Windows handle, not a reopened path
• Close superseded parent descriptors during traversal
• Use search-only directory handles for non-listable paths
• Assert handles are pinned before the simulated Windows open

_{Review effort: Max (auto)}

[Copilot]

🔵 Needs a closer look

Attribute-only Windows opens can convert pinned directories into junctions and redirect subsequent reads outside the root, a critical safety gap not covered by the native regression test.

1 open issue

• Revoke search permission after validating the file

2 previously missed issues

In code that hasn't changed since last review

Prevent junction swaps via attribute-only directory opens

src/​specify_cli/​file_helper.py:176

An attribute-only FILE_WRITE_ATTRIBUTES open bypasses write-sharing checks, so converting an emptied, pinned directory into a junction can redirect the next full-path open outside the root. This conflicts with design/file-helper.md (“Safety limits and migration”); the native test only checks GENERIC_WRITE, not this attribute-only case. Open children relative to their pinned parent handles and add a native Windows regression for attribute-only junction conversion.

Avoid requiring directory-list permission for pinned reads

src/​specify_cli/​file_helper.py:172

These directory pins introduce an extra Windows permission requirement: windows_handle requests FILE_LIST_DIRECTORY (0x1), so a user with traversal permission and read access to a known file, but no folder-listing permission, can no longer read it. The previous pathname read did not require enumeration, and this also affects bootstrap reads of .specify/init-options.json. Please use a non-enumerating directory pin that retains rename/reparse protection, with a native Windows ACL regression test.

AI-generated review for the requester by GitHub Copilot (model: unknown; autonomous mode; code analysis).

2 resolved since last review

• Use an empty file for the Windows symlink fixture
• Pass integer NULL values to CreateFile

_{Review effort: Max (auto)}

[Copilot]

🟡 Changes recommended

The Windows exclusive-creation pathname-race warning is incomplete, and safe-read tests lack negative coverage for three required capabilities.

2 open issues

• Document Windows exclusive-create pathname race · New
• Test safe-read rejection for every required capability · New

1 resolved since last review

• Revoke search permission after validating the file

_{Review effort: Max (auto)}

[Copilot]

🔵 Needs a closer look

A critical risk of unbounded memory growth during repeated Windows reads requires human assessment before approval.

No open issues 🎉

2 resolved since last review

• Test safe-read rejection for every required capability
• Document Windows exclusive-create pathname race

_{Review effort: Max (auto)}

[Copilot]

🟡 Changes recommended

Eager Windows-only imports break CLI startup on POSIX Python builds without the optional _ctypes extension, even for specify --help.

1 open issue

• Defer Windows-only ctypes imports until Windows initialization · New

_{Review effort: Max (auto)}

[Copilot]

🔵 Needs a closer look

Human assessment is needed because the documentation states access requirements only for the root, while those rights are required for every resolved directory and can cause leaf reads to fail.

No open issues 🎉

1 resolved since last review

• Defer Windows-only ctypes imports until Windows initialization

_{Review effort: Max (auto)}

[Copilot]

🟡 Changes recommended

An active maintainability finding flags a third POSIX parent-descriptor walk with differing capability checks, requiring future traversal and cleanup fixes in three places.

1 open issue

• Share the POSIX parent-descriptor walk · New

_{Review effort: Max (auto)}

[Copilot]

🔵 Needs a closer look

The security-sensitive NtCreateFile/ctypes read-confinement path lacks native Windows validation of ABI, sharing, ACL, and reparse semantics that macOS simulations cannot establish.

No open issues 🎉

1 resolved since last review

• Share the POSIX parent-descriptor walk

_{Review effort: Max (auto)}