@@ -59,21 +59,23 @@ export interface SafeWriteJsonOptions {
5959 * is DEFINED: a declared root that is empty or whitespace-only is rejected
6060 * rather than silently disabling the checks.
6161 *
62- * What it does NOT cover: an ancestor DIRECTORY of the target that is replaced
63- * by a link in the window between the last check and the commit rename. Both
64- * checks decide from the final component as it resolves at their own instant,
65- * and publication is path based - the parent-directory creation and the commit
66- * rename both take a path - so an ancestor swapped after the check redirects the
67- * publish. What happens then depends on what sits at the swapped-in path: if it
68- * already has a file at the target name the publish fails in the staging
69- * identity guard (StagingPathError) and nothing is written; if it does not, the
70- * write follows the swapped ancestor and lands OUTSIDE the declared scope. This
71- * option claims neither outcome: it confines the target it resolved, not the
72- * directory tree above it. Making the claim cover that window needs a publish
73- * that walks from an already-open directory handle with no-follow semantics
74- * (openat/renameat over a directory fd); this runtime exposes neither, so the
75- * claim is narrowed here instead of being made true. A caller that needs
76- * containment across that window cannot get it from this option.
62+ * Three checks run: before the advisory lock is taken, on the resolved publish
63+ * target inside the lock, and immediately before the commit rename. Each decides
64+ * the final component as it resolves at its own instant, and publication is path
65+ * based - the parent-directory creation and the commit rename both take a path -
66+ * so an ancestor DIRECTORY swapped for a link after a check redirects whatever
67+ * that check did not refuse. What remains uncovered is the sliver between the
68+ * re-check before the rename and the rename itself: a swap that lands there
69+ * publishes outside the declared scope, and because the rename takes a path it
70+ * replaces whatever file sits where it lands, including a file this write never
71+ * read. The re-check after the commit sees that escape and removes exactly the
72+ * bytes this write published there, but it cannot give back content the rename
73+ * already replaced. This option claims no containment across that sliver. Making
74+ * the claim cover it needs a publish that walks from an already-open directory
75+ * handle with no-follow semantics (openat/renameat over a directory fd); this
76+ * runtime exposes neither, so the claim is narrowed here instead of being made
77+ * true. A caller that needs containment across that sliver cannot get it from
78+ * this option.
7779 */
7880 confineTo ?: string
7981}
@@ -326,12 +328,12 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit
326328 // same way: the publish target is resolved through symlinks, and a target that
327329 // does not exist yet still carries the alias components of the path it was
328330 // given. This runs before the merge read and before anything is staged, so a
329- // rejected write leaves nothing behind. It is also the LAST confinement
330- // decision of this write: it decides the final component as it resolves here,
331- // and an ancestor directory replaced by a link between this point and the
332- // commit rename below is outside its reach, because the rename takes a path and
333- // re-resolves the tree at rename time. See the confineTo option doc for what the
334- // two outcomes of that window are and why neither is claimed by this option .
331+ // rejected write leaves nothing behind. It decides the final component as it
332+ // resolves here, so an ancestor directory replaced by a link after this point is
333+ // outside its reach. The re-check below the staging flush, taken immediately
334+ // before the commit rename, is what narrows that window, and the re-check after
335+ // the commit is the backstop for a swap that lands inside what is left of it.
336+ // See the confineTo option doc for what each of the three checks claims .
335337 if ( confinementRoot !== undefined ) {
336338 const scopeRoot = await _resolveScopeRoot ( confinementRoot )
337339 _assertWithinScope ( absoluteFilePath , await _resolveScopeRoot ( resolvedTargetPath ) , scopeRoot )
@@ -447,10 +449,12 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit
447449 // commit: if the bytes landed outside, undo by removing exactly the file
448450 // this write published at the escaped location (never a same-named file a peer
449451 // placed there after the commit) and report the escape. The peer's swap itself is
450- // left as the peer made it. (A swapped-in directory
451- // that already carried a target file is not stopped earlier here: the commit rename
452- // replaces the file it lands on, so the undo below is what keeps the escaped publish
453- // from leaving our bytes in place of somebody else's.)
452+ // left as the peer made it. The re-check above, taken before the commit rename,
453+ // refuses a swapped ancestor as soon as the write reaches it, so this one is the
454+ // backstop for the sliver that is left: a swap that lands between that check and
455+ // the rename still publishes outside the scope, the rename still replaces whatever
456+ // file sits where it lands, and the undo below removes our bytes without being
457+ // able to give back a peer's content the rename already consumed.
454458 if ( confinementRoot !== undefined ) {
455459 const publishedPath = await _resolveScopeRoot ( resolvedTargetPath )
456460 const scopeRoot = await _resolveScopeRoot ( confinementRoot )
0 commit comments