Skip to content

Commit f1090c1

Browse files
docs(utils): describe which confinement re-check refuses a swapped ancestor
1 parent d0bc9b7 commit f1090c1

2 files changed

Lines changed: 46 additions & 40 deletions

File tree

‎src/utils/__tests__/safeWriteJson.test.ts‎

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1233,11 +1233,12 @@ describe("safeWriteJson", () => {
12331233
})
12341234

12351235
// The confinement option decides from the resolved publish target and stops at its final
1236-
// component. An ancestor DIRECTORY replaced by a link in the window between that
1237-
// decision and the commit rename is caught fail-closed: publication takes a path and
1238-
// re-resolves the tree at rename time, so the confinement option re-resolves the
1239-
// published path after the commit and undoes an escaped write. These two tests are
1240-
// that contract as an executable pair - one per outcome of the window. The swap is driven from the merge
1236+
// component. An ancestor DIRECTORY replaced by a link is caught fail-closed by a re-check
1237+
// taken immediately before the commit rename, and a swap that lands inside the sliver between
1238+
// that check and the rename is caught by the re-check after the commit, which undoes an
1239+
// escaped write. These tests are that contract as an executable set - one for the
1240+
// swapped ancestor, one for the directory that already holds a file at the target name,
1241+
// one for the undo itself. The swap is driven from the merge
12411242
// callback, which safeWriteJson invokes after the in-lock confinement check and before
12421243
// anything is staged, so the ancestor moves inside the window rather than hopefully so.
12431244
// A directory link needs no privilege on win32 as a junction; "dir" is the POSIX
@@ -1255,15 +1256,15 @@ describe("safeWriteJson", () => {
12551256
await fs.mkdir(ancestor, { recursive: true })
12561257
const target = path.join(ancestor, "mcp.json")
12571258
await fs.writeFile(target, JSON.stringify({ inside: true }))
1258-
// The swapped-in directory has no file at the target name yet: this is the half of the
1259-
// window in which the commit itself succeeds and only the post-commit re-check sees
1260-
// the escape.
1259+
// The swapped-in directory has no file at the target name yet, so the shape under test is
1260+
// the swapped ancestor itself: the re-check before the commit rename sees the escape and
1261+
// the write never publishes.
12611262
const swappedIn = path.join(tempDir, "elsewhere", "settings")
12621263
await fs.mkdir(swappedIn, { recursive: true })
12631264

1264-
// The confinement option now fails closed on the swapped ancestor: the
1265-
// post-commit re-check re-resolves the published path, sees it outside the
1266-
// declared scope, removes the escaped file, and reports the escape.
1265+
// The confinement option fails closed on the swapped ancestor: the re-check taken
1266+
// before the commit rename re-resolves the publish target, sees it outside the
1267+
// declared scope, and reports the escape before any rename can land.
12671268
await expect(
12681269
safeWriteJson(
12691270
target,
@@ -1278,7 +1279,8 @@ describe("safeWriteJson", () => {
12781279
),
12791280
).rejects.toBeInstanceOf(ConfinedPathEscapeError)
12801281

1281-
// The escaped publication was undone: nothing remains outside the scope...
1282+
// Nothing was published outside the scope: the commit never ran, so the directory
1283+
// that was swapped in is still empty...
12821284
expect(fsSyncActual.existsSync(path.join(swappedIn, "mcp.json"))).toBe(false)
12831285
// ...and the file that was inside the scope keeps its pre-write bytes - the
12841286
// publish did not reach it under the moved-aside name either.
@@ -1362,10 +1364,10 @@ describe("safeWriteJson", () => {
13621364
await undoEscapedPublish(path.join(outside, "absent.json"), undefined)
13631365
})
13641366

1365-
// The confinement re-check inside the failure path at lines 481 to 490 of safeWriteJson.ts runs
1367+
// The confinement re-check inside the failure path at lines 492 to 517 of safeWriteJson.ts runs
13661368
// while the write is already failing, and the review says a rejection there must not decide
1367-
// what the teardown does: the backup rollback at lines 496 to 511 and the staged cleanup at
1368-
// lines 514 to 529 are what keep the committed copy and the staged bytes from being left
1369+
// what the teardown does: the backup rollback at lines 522 to 538 and the staged cleanup at
1370+
// lines 540 to 556 are what keep the committed copy and the staged bytes from being left
13691371
// behind. This row drives the same EPERM fallback the row at line 192 drives, so a backup
13701372
// exists and the canonical path is absent when the catch block runs, and it breaks fs.realpath
13711373
// only from the moment that backup rename lands, which is the state the catch block then reads.

‎src/utils/safeWriteJson.ts‎

Lines changed: 29 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -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

Comments
 (0)