Skip to content

Commit 0b40d66

Browse files
file-safety: close the four pre-commit and post-commit gaps CodeRabbit raised
Four fixes on the safeWriteText commit path, each behind a test that fails without it: - validate the recorded ancestor identities BEFORE mkdir(recursive:true). mkdir follows whatever the name resolves to at the moment it runs, so a parent already swapped for a link outside the authorized chain was created through before the step 2b revalidation ever compared identities. Step 2b stays: it is what catches a swap in the window between the preflight and the commit. ENOENT is skipped, because an ancestor about to be created is not a containment violation. - compare both names after link(2). There was no post-commit identity check in the module at all: a third party that replaced the staging file before the link published bytes this write never staged. A mismatch now throws PublishedEntryMismatchError carrying targetPath and leaves BOTH names in place (stagingCommitted is set first), because after the link the staged name may belong to another process and an unlink by pathname could remove an entry this write does not own. The rename path cannot be verified this way; the comment says so and points at Zoo-Code-Org#2391 for what that follow-up must prove. - report an orphaned staged file instead of swallowing the failed unlink, and report a failed win32 DACL restore instead of swallowing the error. Both happen after the content is committed, so failing the write would report a failure for bytes the caller can read back; the new optional onPostCommitWarning callback names the residue and the cause while the write still resolves. PostCommitDurabilityError remains a throw: there the caller cannot rely on the write at all. No export is added for the warning value type (the kinds are spelled inline) because no production caller selects on them today, and an export whose only reader is a spec is dead API. safeWriteText still returns Promise<void>, so no caller changes. Tests: 4 added, 1 assertion updated (the ancestry refusal now happens before anything is created, so it asserts that nothing was created). Mutants: removing the preflight call fails 2 tests, neutering the post-link guard fails 1, and dropping either warning report fails 1; the unmutated pair is 2 files / 95 tests passing on the pinned node 22.23.4. No .changeset, no CHANGELOG edit, no suppression count change.
1 parent 970b3a4 commit 0b40d66

2 files changed

Lines changed: 255 additions & 9 deletions

File tree

‎src/services/file-safety/__tests__/safeWriteText.spec.ts‎

Lines changed: 140 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ import {
1818
OrphanedBackupAfterFailedWriteError,
1919
OrphanedBackupError,
2020
OrphanedPublishedBackupError,
21+
PublishedEntryMismatchError,
2122
} from "../safeWriteText"
2223

2324
// Full mock for fs/promises — all methods are vi.fn() stubs
@@ -109,6 +110,12 @@ function _dirIdentity(ino: bigint): BigIntStats {
109110
function _fileIdentity(dev: bigint, ino: bigint): BigIntStats {
110111
return { dev, ino, isSymbolicLink: () => false, isFile: () => true } as unknown as BigIntStats
111112
}
113+
// BigIntStats stand-in with a controllable device, for pinning the dev half of an identity test.
114+
// Same last-resort double assertion as _dirIdentity, test-local.
115+
function _crossIdentity(dev: bigint, ino: bigint): BigIntStats {
116+
return { dev, ino } as unknown as BigIntStats
117+
}
118+
112119
function _stats(mode: number): fsSync.Stats {
113120
const s = Object.create(fsSync.Stats.prototype) as fsSync.Stats
114121
Object.assign(s, { mode })
@@ -977,6 +984,39 @@ describe("safeWriteText", () => {
977984
expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.acl"))
978985
})
979986

987+
it("win32 DACL: a failed restore is reported on the warning channel and the write still resolves", async () => {
988+
const targetPath = "/tmp/test-dir/target.txt"
989+
vi.mocked(fs.realpath).mockResolvedValue(targetPath)
990+
vi.mocked(fsSync.openSync).mockReturnValue(1)
991+
992+
// icacls save succeeds, restore fails
993+
let callCount = 0
994+
vi.mocked(execFile).mockImplementation((_cmd, _args, _opts, cb) => {
995+
callCount++
996+
if (typeof cb === "function") {
997+
cb(callCount === 1 ? null : new Error("icacls restore error"), "", "")
998+
}
999+
return fakeChild
1000+
})
1001+
const warnings: { kind: string; path: string; cause: unknown }[] = []
1002+
1003+
await expect(
1004+
safeWriteText(targetPath, "data", {
1005+
platform: "win32",
1006+
onPostCommitWarning: (warning) => {
1007+
warnings.push({ kind: warning.kind, path: warning.path, cause: warning.cause })
1008+
},
1009+
}),
1010+
).resolves.toBeUndefined()
1011+
1012+
expect(warnings).toHaveLength(1)
1013+
expect(warnings[0]?.kind).toBe("dacl-restore-failed")
1014+
expect(warnings[0]?.path).toBe(path.dirname(targetPath))
1015+
expect((warnings[0]?.cause as Error | undefined)?.message).toBe("icacls restore error")
1016+
// still best-effort in every other respect: the dump is unlinked, as the test above pins
1017+
expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.acl"))
1018+
})
1019+
9801020
it("win32 DACL: when target does not exist, no save/restore/dump", async () => {
9811021
const targetPath = "/tmp/test-dir/target.txt"
9821022
vi.mocked(fs.realpath).mockResolvedValue(targetPath)
@@ -1596,6 +1636,73 @@ describe("safeWriteText", () => {
15961636
expect(fs.link).toHaveBeenCalledWith(expect.stringContaining("safeWriteText"), targetPath)
15971637
})
15981638

1639+
it("names the orphaned staged file on the warning channel when the unlink after the link fails", async () => {
1640+
// Same Windows antivirus case as the test above, now with the residue named instead of
1641+
// dropped: the write still resolves, and the caller learns the staged name is still there.
1642+
const targetPath = "/tmp/test-dir/target.txt"
1643+
vi.mocked(fs.realpath).mockResolvedValue(targetPath)
1644+
vi.mocked(fs.unlink).mockRejectedValue(Object.assign(new Error("EBUSY"), { code: "EBUSY" }))
1645+
const warnings: { kind: string; path: string; cause: unknown }[] = []
1646+
1647+
await expect(
1648+
safeWriteText(targetPath, "new data", {
1649+
failIfExist: true,
1650+
platform: "linux",
1651+
onPostCommitWarning: (warning) => {
1652+
warnings.push({ kind: warning.kind, path: warning.path, cause: warning.cause })
1653+
},
1654+
}),
1655+
).resolves.toBeUndefined()
1656+
1657+
expect(warnings).toHaveLength(1)
1658+
expect(warnings[0]?.kind).toBe("staging-link-orphan")
1659+
expect(String(warnings[0]?.path)).toContain("safeWriteText_")
1660+
expect((warnings[0]?.cause as { code?: string } | undefined)?.code).toBe("EBUSY")
1661+
})
1662+
1663+
it("refuses to report success when the published name is not the staged file", async () => {
1664+
// A third party replaced the staging file between the staging checks and link(2), so the
1665+
// name link(2) published holds bytes this write never staged. Comparing both names after the
1666+
// link is what catches it, and a mismatch is a refusal, not a success.
1667+
const targetPath = "/tmp/test-dir/target.txt"
1668+
vi.mocked(fs.realpath).mockResolvedValue(targetPath)
1669+
vi.mocked(fs.stat).mockImplementation(async (p) =>
1670+
String(p).includes("safeWriteText_") ? _dirIdentity(11n) : _dirIdentity(12n),
1671+
)
1672+
1673+
const error = await safeWriteText(targetPath, "new data", { failIfExist: true, platform: "linux" }).catch(
1674+
(caught: unknown) => caught,
1675+
)
1676+
1677+
expect(error).toBeInstanceOf(PublishedEntryMismatchError)
1678+
expect((error as PublishedEntryMismatchError).targetPath).toBe(targetPath)
1679+
expect((error as PublishedEntryMismatchError).message).toContain("both names were left in place")
1680+
// Neither name is removed: after a mismatch the staged name may be another process's file
1681+
// and the published name is content a reader can already see, so an unlink by pathname here
1682+
// could take away an entry this write does not own.
1683+
expect(fs.unlink).not.toHaveBeenCalled()
1684+
expect(fs.rename).not.toHaveBeenCalled()
1685+
})
1686+
1687+
it("refuses to report success when the published name holds a file from another device", async () => {
1688+
// The same refusal through the other half of the identity comparison: same inode number,
1689+
// different device. Pinning both halves is the only way to know that neither arm of the
1690+
// (dev, ino) test is dead code, which is why this case exists beside the inode case above.
1691+
const targetPath = "/tmp/test-dir/target.txt"
1692+
vi.mocked(fs.realpath).mockResolvedValue(targetPath)
1693+
vi.mocked(fs.stat).mockImplementation(async (p) =>
1694+
String(p).includes("safeWriteText_") ? _crossIdentity(1n, 11n) : _crossIdentity(2n, 11n),
1695+
)
1696+
1697+
const error = await safeWriteText(targetPath, "new data", { failIfExist: true, platform: "linux" }).catch(
1698+
(caught: unknown) => caught,
1699+
)
1700+
1701+
expect(error).toBeInstanceOf(PublishedEntryMismatchError)
1702+
expect((error as PublishedEntryMismatchError).message).toContain("both names were left in place")
1703+
expect(fs.unlink).not.toHaveBeenCalled()
1704+
})
1705+
15991706
it("refuses to publish when the path no longer resolves to the authorized target", async () => {
16001707
// Isolate the commit-phase counters from any async cleanup a previous test left
16011708
// in flight.
@@ -1646,8 +1753,39 @@ describe("safeWriteText", () => {
16461753
expect((error as AncestorReplacedError).message).toContain("no longer the directory that was authorized")
16471754
expect(fs.rename).not.toHaveBeenCalled()
16481755
expect(fs.link).not.toHaveBeenCalled()
1649-
// The staged copy is cleaned up rather than left beside the target.
1650-
expect(vi.mocked(fs.unlink).mock.calls.some((call) => String(call[0]).includes("safeWriteText"))).toBe(true)
1756+
// The pre-commit revalidation is no longer the first check to notice: the ancestor
1757+
// preflight runs before mkdir, so this write never created the parent, never made a staging
1758+
// directory beside the target, and has no staged copy to clean up.
1759+
expect(fs.mkdir).not.toHaveBeenCalled()
1760+
expect(
1761+
vi.mocked(fsSync.mkdirSync).mock.calls.some((call) => String(call[0]).includes(".file-safety-staging")),
1762+
).toBe(false)
1763+
expect(fs.unlink).not.toHaveBeenCalled()
1764+
})
1765+
1766+
it("refuses before creating anything when an authorized parent was already replaced", async () => {
1767+
const dir = path.resolve("/tmp/test-dir")
1768+
const targetPath = path.join(dir, "target.txt")
1769+
vi.mocked(fs.realpath).mockResolvedValue(targetPath)
1770+
vi.mocked(fs.stat).mockResolvedValue(_dirIdentity(999n)) // was 100n when authorized
1771+
1772+
const error = await safeWriteText(targetPath, "new data", {
1773+
expectedResolvedPath: targetPath,
1774+
expectedAncestorIdentities: [{ dir, dev: 1n, ino: 100n }],
1775+
platform: "linux",
1776+
}).catch((caught: unknown) => caught)
1777+
1778+
expect(error).toBeInstanceOf(AncestorReplacedError)
1779+
expect((error as AncestorReplacedError).directory).toBe(dir)
1780+
expect((error as AncestorReplacedError).message).toContain("no longer the directory that was authorized")
1781+
// The point of the preflight is the ORDER: mkdir(recursive:true) follows whatever the name
1782+
// resolves to at the moment it runs, so a parent that is already unauthorized gets created
1783+
// through before any identity comparison happens. Nothing was created and nothing was staged.
1784+
expect(fs.mkdir).not.toHaveBeenCalled()
1785+
expect(fsSync.mkdirSync).not.toHaveBeenCalled()
1786+
expect(fs.unlink).not.toHaveBeenCalled()
1787+
expect(fs.link).not.toHaveBeenCalled()
1788+
expect(fs.rename).not.toHaveBeenCalled()
16511789
})
16521790

16531791
it("refuses to publish when an authorized ancestor name was moved and replaced by a link", async () => {

‎src/services/file-safety/safeWriteText.ts‎

Lines changed: 115 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,19 @@ export interface SafeWriteTextOptions {
8383
* when it recorded a plain spelling - not merely to the same inode.
8484
*/
8585
expectedAncestorIdentities?: DirectoryIdentity[]
86+
/**
87+
* A post-commit step failed while the content this call published stayed readable: either the staged name
88+
* could not be removed after a no-replace commit, or the win32 DACL restore failed. The write
89+
* resolves in both cases - failing it would report a failure for bytes the caller can now read
90+
* back - and the residue is reported here instead of dropped. Kinds are spelled inline rather
91+
* than exported: no production caller selects on them today, and an export whose only reader
92+
* is a spec is dead API.
93+
*/
94+
onPostCommitWarning?: (warning: {
95+
kind: "staging-link-orphan" | "dacl-restore-failed"
96+
path: string
97+
cause: unknown
98+
}) => void
8699
}
87100

88101
/** One directory's on-disk identity, read with bigint stats so NTFS 64-bit values survive. */
@@ -319,8 +332,53 @@ export class AncestorReplacedError extends Error {
319332
this.directory = directory
320333
}
321334
}
335+
/**
336+
* The target name does not hold the file this write staged.
337+
*
338+
* A third party replaced the staging file between the staging checks and link(2), so the name now
339+
* published is bytes this write never staged. Nothing is removed: after the link both names may
340+
* belong to somebody else, and an unlink by pathname can take away an entry this write does not
341+
* own. The two identities travel on the error because the only useful next step is comparing them.
342+
*/
343+
export class PublishedEntryMismatchError extends Error {
344+
readonly targetPath: string
345+
constructor(targetPath: string, publishedIdentity: string, stagedIdentity: string) {
346+
super(
347+
`The published entry (${targetPath}) is not the staged file (published ${publishedIdentity}, staged ${stagedIdentity}); both names were left in place.`,
348+
)
349+
this.name = "PublishedEntryMismatchError"
350+
this.targetPath = targetPath
351+
}
352+
}
322353
// -- helpers ---------------------------------------------------------------
323354

355+
/**
356+
* Reject an unauthorized parent BEFORE mkdir walks through it.
357+
*
358+
* mkdir(recursive:true) follows whatever parent chain the name currently resolves to, and the
359+
* step 2b revalidation below runs after it, so a parent swapped for a link to outside the
360+
* authorized chain gets created through before anything compares identities. Only an ancestor that
361+
* is already present is compared: an ENOENT here is a directory this call is about to create, not a
362+
* containment violation, and the recorded identity for it cannot be checked against nothing. Step
363+
* 2b stays in place: it is what catches a swap in the window between this check and the commit.
364+
*/
365+
async function _preflightAncestors(identities: DirectoryIdentity[] | undefined): Promise<void> {
366+
if (!identities) {
367+
return
368+
}
369+
for (const expected of identities) {
370+
const current = await fs.stat(expected.dir, { bigint: true }).catch((error: unknown) => {
371+
if (getErrorCode(error) === "ENOENT") {
372+
return null
373+
}
374+
throw error
375+
})
376+
if (current !== null && (current.dev !== expected.dev || current.ino !== expected.ino)) {
377+
throw new AncestorReplacedError(expected.dir, "is no longer the directory that was authorized")
378+
}
379+
}
380+
}
381+
324382
/** fsync one directory so the entry it holds (a rename, or a newly created child) is durable. */
325383
function _syncDirectory(dir: string): void {
326384
const dirFd = fsSync.openSync(dir, "r")
@@ -406,17 +464,26 @@ async function _saveDaclWindows(srcPath: string, dumpPath: string, execFileRunne
406464
}
407465
}
408466
/** Restore a DACL dump onto *dirPath* on Windows.
409-
* Best-effort: content is already committed, so failure is non-fatal. */
410-
async function _restoreDaclWindows(dirPath: string, dumpPath: string, execFileRunner?: typeof execFile): Promise<void> {
467+
*
468+
* Best-effort: the content is already committed, so a failed restore does not fail the write. The
469+
* failure is RETURNED rather than swallowed, because the caller is the only party that can do
470+
* something about a directory whose ACL did not come back, and a swallowed error never reaches it. */
471+
async function _restoreDaclWindows(
472+
dirPath: string,
473+
dumpPath: string,
474+
execFileRunner?: typeof execFile,
475+
): Promise<unknown | null> {
411476
const runner = execFileRunner ?? execFile
412477
try {
413478
await new Promise<void>((resolve, reject) => {
414479
runner("icacls", [dirPath, "/restore", dumpPath], { windowsHide: true }, (err) =>
415480
err ? reject(err) : resolve(),
416481
)
417482
})
418-
} catch {
419-
// best-effort; content already committed
483+
return null
484+
} catch (error: unknown) {
485+
// best-effort: content already committed, so the caller is told rather than the write failed
486+
return error
420487
}
421488
}
422489

@@ -564,6 +631,7 @@ export async function safeWriteText(
564631
// Ensure parent directory exists (mirrors safeWriteJson behaviour). What mkdir reports it
565632
// created feeds step 4b's fsync of the ancestors this write introduced; see
566633
// _createdAncestorChain.
634+
await _preflightAncestors(options?.expectedAncestorIdentities)
567635
const createdAncestors = _createdAncestorChain(await fs.mkdir(dirPath, { recursive: true }), dirPath)
568636
await fs.access(dirPath)
569637

@@ -937,12 +1005,45 @@ export async function safeWriteText(
9371005
}
9381006

9391007
if (options?.failIfExist) {
1008+
// Both names should now be one inode. They are not when a third party replaced the
1009+
// staging file before the link, in which case the published name holds bytes this write
1010+
// never staged. Checked after the link because link(2) is the first point at which the
1011+
// target name exists; a check of either name before it cannot see what landed at the
1012+
// other. Neither name is removed on a mismatch and stagingCommitted is set first, so the
1013+
// cleanup below cannot unlink a name that may belong to another process. The ordinary
1014+
// rename path cannot be verified this way: rename(2) moves the staged inode itself and
1015+
// leaves no second name to compare, and a re-stat of the target proves only that the
1016+
// rename took effect, not that the staging file was still ours when it did. Issue
1017+
// #2391 is where that gap is carried; what it must prove is how a commit that leaves
1018+
// no second name detects a staging substitution before publication and how its cleanup
1019+
// avoids removing an entry it does not own. This unit does not claim that answer.
1020+
const [stagedNow, publishedNow] = await Promise.all([
1021+
fs.stat(tempPath, { bigint: true }),
1022+
fs.stat(targetPath, { bigint: true }),
1023+
])
1024+
if (stagedNow.dev !== publishedNow.dev || stagedNow.ino !== publishedNow.ino) {
1025+
stagingCommitted = true
1026+
throw new PublishedEntryMismatchError(
1027+
targetPath,
1028+
`${publishedNow.dev}:${publishedNow.ino}`,
1029+
`${stagedNow.dev}:${stagedNow.ino}`,
1030+
)
1031+
}
9401032
// The target name is published at this point; the staged name is only a second
9411033
// link to the same inode (or a copy of it). Removal is best-effort: on Windows
9421034
// an antivirus handle can make unlink fail with EBUSY/EPERM after the content
9431035
// is already visible, and the write must not be reported as failed for content
944-
// the caller can now read back.
945-
await fs.unlink(tempPath).catch(() => undefined)
1036+
// the caller can now read back. The residue is named on the warning channel rather
1037+
// than dropped, because a caller that keeps its own staging name needs to learn the
1038+
// orphan is still there.
1039+
const stagingResidue = await fs.unlink(tempPath).catch((error: unknown) => error)
1040+
if (stagingResidue !== undefined) {
1041+
options?.onPostCommitWarning?.({
1042+
kind: "staging-link-orphan",
1043+
path: tempPath,
1044+
cause: stagingResidue,
1045+
})
1046+
}
9461047
}
9471048

9481049
// Marked once the commit has consumed the staging name: on the rename path the
@@ -983,7 +1084,14 @@ export async function safeWriteText(
9831084
// and on every failed save.
9841085
if (daclDumpPath !== null) {
9851086
const restoredDir = path.dirname(targetPath)
986-
await _restoreDaclWindows(restoredDir, daclDumpPath, options?.execFileRunner)
1087+
const restoreFailure = await _restoreDaclWindows(restoredDir, daclDumpPath, options?.execFileRunner)
1088+
if (restoreFailure !== null) {
1089+
options?.onPostCommitWarning?.({
1090+
kind: "dacl-restore-failed",
1091+
path: restoredDir,
1092+
cause: restoreFailure,
1093+
})
1094+
}
9871095
}
9881096

9891097
// -- Step 6 (backup:true): delete backup on success -----------

0 commit comments

Comments
 (0)