Repository navigation
fix(papyrus): refuse a junctioned path in the Compile link scan - #8766
Conversation
`_symlinked_artifacts` is the guard that stops Compile running when anything
beneath a project is a link: pdflatex writes files by name, so compiling
through a link overwrites whatever it points at. It asked `is_symlink()`.
A Windows directory junction is a reparse point `is_symlink()` does NOT
report, and a junction is precisely a DIRECTORY link -- so it fell through to
the `is_dir()` arm of the same loop and broke the guard twice over:
* the junction never reached the refusal list, so Compile proceeded and the
compiler was free to write through it; and
* the walk DESCENDED it, contradicting the docstring's "does not descend
INTO links" and spending MAX_PROJECT_FILES budget on a tree outside the
project -- pushing `complete` toward False for reasons the project does
not contain, which is itself a refusal the user cannot act on.
Route it through `store.is_reparse_link`, whose own contract already states
the rule: "every place this module refuses a link at a name Kiro Crew owns
has to refuse a junction too, or the refusal is POSIX-only". `list_files`
was moved onto it in kirodotdev#7881; this leaves Compile agreeing with the file list
its docstring cites as the stance it matches, rather than following what the
editor already refuses to show.
Junctions need no elevation on Windows while symlinks do, so this was the
platform's cheapest bypass -- and every existing link test in this suite is
skipped on win32 for exactly that reason, which is how the gap survived.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Design Review (Fable 5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Root-cause fix: routes the compile guard through the module's shared link predicate, closing the one link type an unelevated Windows user can create. The diff matches the description exactly: [DESIGN-REVIEWED] 190c36f |
First Principles Review (Fable 5, fork) — ✅ PASSPremise-level review of All verification complete. The base file at First-Principles-Verdict: PASS A one-line fix that aligns the Compile link scan with the module's documented link predicate; nothing rides along. What this change shipsIntent: stop Papyrus Compile from silently following a Windows junction that the same guard exists to refuse — a FIX.
Every item is the fix or its evidence. The requirement is DERIVED twice over: [FIRST-PRINCIPLES-REVIEWED] 190c36f |
Opus 4.8 Review (fork) — ✅ no blocking findingsReviewed Review detailsThe diff is a clean, well-scoped security fix. No findings. [OPUS-REVIEWED] 190c36f |
bolichen97
left a comment
There was a problem hiding this comment.
Tech Lead review: APPROVE
Correct helper. The changed call site now asks store.is_reparse_link(entry) instead of entry.is_symlink(). That is the reparse-aware predicate AGENTS.md's cross-platform table mandates (is_link_or_junction in the Use column, path.is_symlink() explicitly in the NOT column, "misses a Windows junction"), implemented locally in store.py:166 as symlink-OR-junction with a st_reparse_tag == IO_REPARSE_TAG_MOUNT_POINT fallback so the guard is present on 3.10/3.11 where os.path.isjunction does not exist. It is the same predicate store.list_files and the gitops attributes guard already use, so this removes a Windows-only divergence rather than introducing a second convention.
Correct threat model. A junction is a DIRECTORY reparse point, so the old is_symlink() test did not merely skip the check: the entry fell through to the entry.is_dir() arm of the same loop and the walk descended it. Both halves of the guard failed at once (the link absent from found, so compile_project proceeded and pdflatex could write by name through it; and MAX_PROJECT_FILES spent outside the project, pushing complete toward False for reasons the project does not contain). Junctions need no elevation on Windows while symlinks do, so the old test covered the case a user mostly cannot create and missed the one they can.
Verified in context. entry comes from current.iterdir(), so it is a Path and is_reparse_link's str(path) / path.stat(follow_symlinks=False) both receive a real path (a DirEntry here would have silently broken the isjunction arm). The change is strictly a tightening: it can only add entries to the refusal list and only stop descent.
Tests. The non-descent assertion is made against what the walk consulted via a spy, not against the return value — correct, because this scan only ever appends links, so a walk that descended a junction of ordinary files returns an identical list and a found-based assertion would pass vacuously. test_a_real_windows_junction_is_refused anchors the stubs to a genuine _winapi.CreateJunction reparse point with no elevation, and proves non-descent through a budget of 2 against a padded outside directory rather than restating the mock.
Scope. Two files, one production line plus docstring/comment and one new test class. The per-site scoping is right: the two surviving is_symlink() sites under papyrus/ test file paths, where a directory-only junction cannot reach the is_dir() descent arm, so they are not unfixed instances of this root cause. No new surface, config, or flags.
CI: 69 success / 5 skipped, combined status success, including Backend Tests (Windows) 1-4 and Cross-Platform Portability. All four AI lanes clean (GPT 5.6 no findings, Opus 4.8 no findings, Design PASS, First Principles PASS). No unresolved review threads. Diff touches no website/src/** or website/electron/** path, so the ux-review-required ruleset does not apply.
Approving and squash-merging.
Problem / Motivation
Papyrus refuses to compile a project when anything beneath it is a link. The
reason is in
_symlinked_artifacts' own docstring: pdflatex writes files byname, and the document chooses those names (
\openout\ch=chapter1, aredirected
\jobname,.bbl/.idxtoolchains), so compiling through a linkoverwrites whatever it points at. The guard's stated stance is absolute —
"nothing beneath the project is a link at all".
The walk asked
entry.is_symlink().On Windows that misses a directory junction, and a junction is precisely a
DIRECTORY link — so it reached the
is_dir()arm of the very same loop.Why it matters
The guard fails in both directions at once for a junctioned path:
blockedcomes back empty,compile_projectproceeds, and pdflatex is free to write through the junction to whatever it
points at. That is exactly the outcome this function exists to prevent.
descend INTO links, so a
a -> ..cycle cannot spin it", and it spends theMAX_PROJECT_FILESbudget on a tree outside the project — which can pushcompleteto False and produce a "this project has more than N files" refusalthe user cannot act on, because the files are not in their project.
Junctions are the link type a Windows user can create without elevation,
while symlinks there require a privilege. So the symlink-only test covered the
case a Windows user mostly cannot create and missed the one they can.
That asymmetry is also why the gap survived review: every existing link test in
test_papyrus_latex.pycarries@pytest.mark.skipif(sys.platform == "win32", reason="symlink creation needs privilege on Windows").The suite could not have caught this.
What changed (motivation → approach → change)
Symptom — a junctioned directory inside a Papyrus project is neither
reported nor skipped by the Compile link scan.
Root cause — the scan tests for one link type instead of asking the module's
shared link predicate.
store.is_reparse_linkalready exists and its docstringstates the rule this violated:
Change — one line in
_symlinked_artifacts:entry.is_symlink()becomesstore.is_reparse_link(entry).latex.pyalready importsstore, so nothingnew is wired in.
This is the same move #7881 made for
store.list_files, in the sibling modulethat PR did not touch. It matters that they agree: this function's docstring
cites
list_files' stance as the one it is matching ("a link is not a file theeditor should follow"), and since #7881 they had silently diverged on Windows —
the editor refused to show a junctioned file while Compile followed it.
This is also a documented repository rule, not only a local inference: the
cross-platform table in
AGENTS.mdcarries the row| Detect/remove a dir link |
is_link_or_junction(path)/unlink_link_or_junction(path)|path.is_symlink()(misses a Windows junction) |so the changed call site was on the NOT column of that table.
store.is_reparse_linkdetects junctions without depending onos.path.isjunction(3.12+, and this project supports 3.10), so the guard ispresent on every supported interpreter.
Tests
Added
TestTheCompileLinkScanRefusesJunctionsToototest/test_papyrus_latex.py,following the pattern #7881 established in
test_papyrus_store.py— stub theshared helper, because
os.path.isjunctionis 3.12+ and always False off Windows:test_a_junction_is_reported_as_a_link— the junction appears in the refusallist.
test_the_walk_does_not_descend_a_junction— asserts against what the walklooked at, via a spy, not against the return value. This scan only ever
appends links, so a walk that descended a junction full of ordinary files
returns an identical list; checking
foundwould pass vacuously and provenothing. (It did: an earlier draft of this test passed on unpatched
main.)test_the_scan_consults_the_shared_helper— a junction is only refused if thescan asks the helper at all.
test_compile_refuses_when_a_junction_is_present— end-to-end:compile_projectreturns
ok=Falseand the compiler never runs.test_a_real_windows_junction_is_refused— no stub and no elevation. Createsan actual reparse point with
_winapi.CreateJunctionand asserts both halves:the junction is reported, and
completestays True under a budget of 2, whichis only possible if the walk stopped at the link instead of following it into a
padded outside directory. This anchors the stubbed tests to real platform
behaviour rather than to a mock of it.
Red-before, new tests against the unmodified
mainproduction file(Windows host,
-p no:randomly): 5 failed. The real-junction test fails withAssertionError: a real junction was not reported as a link— the bypassdemonstrated on a genuine reparse point, no mocking involved.
Green-after: whole file, 87 passed / 15 skipped.
Gates: repo black gate ✓ (nothing in scope unformatted outside the
baseline), isort ✓, flake8 ✓, mypy ✓ (no issues), brand gate ✓.
Manual verification
N/A — unit coverage sufficient, and stronger than a manual check would be: the
suite creates a real Windows junction and exercises the actual walk, so the
platform behaviour is executed rather than described.
Related Issues
No linked issue. Found by auditing the surviving
is_symlink()sites againststore.is_reparse_link's stated contract after #7881 (fix(papyrus): papyrus walks refuse a Windows junction) merged, which fixedstore.pyand left thissibling in
latex.py.Scope is deliberately this one call site. Other
is_symlink()sites elsewhere inthe tree each need their own threat analysis — as #8165's review put it, per-site
reasoning rather than a sweep — so they are not bundled here.
Pattern harvest
Rule candidate:
semgrepPattern:
is_symlink()/os.path.islink()used as a security refusal on apath the product owns. On Windows it silently misses a directory junction, which
is both the link type that needs no elevation and a link that
is_dir()reportsas a directory — so the miss does not merely skip the check, it routes the entry
into the "descend this directory" branch. A lint rule can flag the predicate
inside a refusal or walk and require the project's reparse-aware helper.
Secondary review prompt: when a test suite skips a whole class of tests on one
platform (
skipif(sys.platform == "win32")), treat that platform as unverifiedfor the behaviour under test rather than as covered.
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
🤖 Generated with Claude Code