Skip to content

fix(papyrus): refuse a junctioned path in the Compile link scan - #8766

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/papyrus-latex-junction-link-guard
Sep 6, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/papyrus-latex-junction-link-guard

Conversation

@leonlaiyc

@leonlaiyc leonlaiyc commented Sep 5, 2026 •

Copy link
Copy Markdown
Contributor

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 by
name
, and the document chooses those names (\openout\ch=chapter1, a
redirected \jobname, .bbl/.idx toolchains), so compiling through a link
overwrites 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:

  1. The link is never reported. blocked comes back empty, compile_project
    proceeds, and pdflatex is free to write through the junction to whatever it
    points at. That is exactly the outcome this function exists to prevent.
  2. The walk descends into it. That contradicts the docstring's "does not
    descend INTO links, so a a -> .. cycle cannot spin it", and it spends the
    MAX_PROJECT_FILES budget on a tree outside the project — which can push
    complete to False and produce a "this project has more than N files" refusal
    the 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.py carries
@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_link already exists and its docstring
states the rule this violated:

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

Change — one line in _symlinked_artifacts: entry.is_symlink() becomes
store.is_reparse_link(entry). latex.py already imports store, so nothing
new is wired in.

This is the same move #7881 made for store.list_files, in the sibling module
that 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 the
editor 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.md carries 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_link detects junctions without depending on
os.path.isjunction (3.12+, and this project supports 3.10), so the guard is
present on every supported interpreter.

Tests

Added TestTheCompileLinkScanRefusesJunctionsToo to test/test_papyrus_latex.py,
following the pattern #7881 established in test_papyrus_store.py — stub the
shared helper, because os.path.isjunction is 3.12+ and always False off Windows:

  • test_a_junction_is_reported_as_a_link — the junction appears in the refusal
    list.
  • test_the_walk_does_not_descend_a_junction — asserts against what the walk
    looked 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 found would pass vacuously and prove
    nothing. (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 the
    scan asks the helper at all.
  • test_compile_refuses_when_a_junction_is_present — end-to-end: compile_project
    returns ok=False and the compiler never runs.
  • test_a_real_windows_junction_is_refused — no stub and no elevation. Creates
    an actual reparse point with _winapi.CreateJunction and asserts both halves:
    the junction is reported, and complete stays True under a budget of 2, which
    is 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 main production file
(Windows host, -p no:randomly): 5 failed. The real-junction test fails with
AssertionError: a real junction was not reported as a link — the bypass
demonstrated 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 against
store.is_reparse_link's stated contract after #7881 (fix(papyrus): papyrus walks refuse a Windows junction) merged, which fixed store.py and left this
sibling in latex.py.

Scope is deliberately this one call site. Other is_symlink() sites elsewhere in
the 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: semgrep

Pattern: is_symlink() / os.path.islink() used as a security refusal on a
path 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() reports
as 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 unverified
for the behaviour under test rather than as covered.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable) — the function's docstring now defines what "link" means here
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

🤖 Generated with Claude Code

`_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>
@leonlaiyc
leonlaiyc requested review from a team and chenmingwei23 September 5, 2026 15:00
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 5, 2026
@github-actions

github-actions Bot commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed 190c36fd0865b5567b77d7eb30997928fbec2586 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 190c36f

@github-actions

github-actions Bot commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of 190c36fd0865b5567b77d7eb30997928fbec2586 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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: store.is_reparse_link exists at store.py:166 with the contract quoted, list_files already honours it (store.py:503, 525), and latex.py:604 was the last divergent site. The tests assert the non-descent half against what the walk consulted rather than the vacuously-identical return value, and anchor the stubs with one real-junction Windows test — a sound shape for a bypass whose trigger cannot be created on the CI platforms that run the rest of the suite.

[DESIGN-REVIEWED] 190c36f

@github-actions

github-actions Bot commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of 190c36fd0865b5567b77d7eb30997928fbec2586 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

All verification complete. The base file at latex.py:604 indeed asks entry.is_symlink(); the shared helper store.is_reparse_link (store.py:166) exists with the exact documented invariant quoted, its other two walk sites in store.py and the gitops.py guard already honor it, and latex.py already imports store. The two remaining is_symlink() sites in papyrus are file-context, where a directory-only junction can't take the is_dir() descent path, so they aren't unfixed siblings. list_files skips links silently and can't report them, so the scan isn't a duplicate of it. Here is the review:

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 ships

Intent: stop Papyrus Compile from silently following a Windows junction that the same guard exists to refuse — a FIX.

  1. Compile now reports a junctioned directory as a link and refuses — justified
  2. The walk no longer descends a junction, so the file budget stays inside the project — justified (same one-line change)
  3. Function docstring now defines "link" as symlink-or-junction — declared, part of the fix
  4. Five new tests, one on a real Windows reparse point — justified

Every item is the fix or its evidence. The requirement is DERIVED twice over: store.is_reparse_link's own contract ("every place this module refuses a link at a name Kiro Crew owns has to refuse a junction too", store.py:173) and the cross-platform stance in AGENTS.md's shim table. The fix sits at cause level — it replaces the wrong predicate with the shared one rather than special-casing junctions at the call site. Sibling count: I grepped is_symlink|islink under papyrus/ — the 2 surviving production sites (tectonic.py:550, store.py:340) test file paths, where a directory-only junction cannot reach the is_dir() descent arm, so they are not instances of this root cause; the PR's per-site scoping claim holds. Zero new public surface, config, or flags.

[FIRST-PRINCIPLES-REVIEWED] 190c36f

@github-actions

github-actions Bot commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

Reviewed 190c36fd0865b5567b77d7eb30997928fbec2586 via the fork AI-review pipeline; updated in place on each push.

Review details

The diff is a clean, well-scoped security fix. store.is_reparse_link (store.py:166) returns True for symlinks OR junctions and handles its own errors; the changed line reports the link and continues without descending; the caller honors (blocked, scan_complete). The candidate pass found nothing, and I find nothing groundable to add.

No findings.

[OPUS-REVIEWED] 190c36f

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 5, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants