sim 889c7efba0 test(#4653): failing-first coverage for the narrowed containment export ...

Phase 3 of epic #4636. Tests only; no implementation. These MUST fail.

A refactor changes what a good test looks like: the behavior under test must be
IDENTICAL before and after, so most of this phase's safety comes from
invariance rather than new assertions. That safety net already exists and is
untouched here — tests/security.test.cjs already pins the two engine behaviors
a re-derivation would silently lose:

  :177  a DANGLING symlink to a non-existent OUTSIDE target stays safe:false
        (the existence-oracle closure)
  :213  a not-yet-created file in a not-yet-created subdir under a
        non-canonical base stays safe:true (ancestor canonicalization)

plus traversal, absolute in/out, null bytes, empty, non-string, and
requireSafePath's throw. Those 0 deletions are the point: if any of them had to
change, the engine would have changed, and the engine is not supposed to.

What is new is the export surface Phase 3 introduces:

  assertWithinRoot(candidate, root, label?, opts?) -> ContainedPath  (throws)
  tryWithinRoot(candidate, root, opts?)            -> ContainedPath | null

Two shapes rather than one, because several call sites need a NON-throwing
check — findPhaseArtifact probes a direct path, then a .planning/ path, then
each readdir entry, and throwing on the first miss would break it outright.
ADR-4650 names only the throwing form; this is the gap between the ADR and the
call sites, recorded rather than papered over.

Rows that exist because they are the ones nobody enumerates:

- tryWithinRoot must return EXACTLY null on escape, and its return must not
  contain the escaping path's basename. The shape being replaced populates its
  "resolved" field with the escaping path precisely on the traversal branch, so
  a caller who ignores the boolean gets a usable attacker-controlled value.
  That is the defect the narrowing exists to remove, so it is asserted
  directly.
- A seeded parity property: tryWithinRoot returns non-null if and only if
  assertWithinRoot does not throw, and the values agree. Two exported shapes
  over one engine is a divergence pair by construction.
- The rejection text still contains the phrase "escapes allowed directory".
  Another suite surfaces it through a user-facing "reason" field, and a
  refactor is exactly where wording drifts unnoticed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-09-12 11:54:49 -04:00

60 KiB

Raw Blame History

View Raw