Skip to content

Commit 2e79e37

Browse files
file-safety: authorize by bigint file identity, not by a rounded number
The commit-time guard compared dev and ino as numbers. Both sides came from a plain stat, and a plain stat hands back a 64-bit NTFS file id rounded to a double: above 2**53 two different files can round to the same number, and the guard would then accept one for the other, which is exactly the swap it exists to catch. The lost bits cannot be recovered from the rounded value, so the fix is the capture spelling, not a smarter comparison: the option is now { dev: bigint; ino: bigint } and the guard reads the target with fs.stat(targetPath, { bigint: true }). The option has no production caller in this tree - the only seven mentions of authorizedTarget at 5559f1f are the option declaration, the three guard lines, and the three rows in safeWriteText.identity.spec.ts - so this is the moment the spelling is free to change, and it is the last moment it will be free once sibling units start handing identities in. Measured on this box's NTFS volume, three identities came back as 281474990289684, 4503599627490809 and 5629499534337367, all below 2**53: this volume cannot exhibit the collision, so no row here asserts the rounding, and the rows are updated to read bigint identities rather than being asked to prove something the filesystem will not do for them. Verification, pinned node v22.23.4 with stdio on file descriptors: services/file-safety with utils/__tests__/safeWriteJson.test.ts is 133 passed and 1 skipped (the mode row skipped on win32, as before) in 4 files; tsc --noEmit -p tsconfig.json in src reports 0 errors; eslint --prune-suppressions --max-warnings=0 exits 0 on both touched files and its suppressions rewrite was reverted; prettier --check is clean on both, and formatting was done before measuring. Gate: 496 of 500 counted executable lines at base 73931fe with base...head and --unified=0, against 496 at 5559f1f - a 0-line move, because the type line and the comments are not executable - measured with v22.23.4.
1 parent 5559f1f commit 2e79e37

2 files changed

Lines changed: 19 additions & 6 deletions

File tree

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

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,11 @@ import { safeWriteText } from "../safeWriteText"
1010
// in and the identity of the path about to be written - and it refuses rather than publishing
1111
// when they disagree or when the identity cannot be read at all. These rows run against the real
1212
// filesystem, with no stubbing of fs.stat, because the assertion that matters is about what the
13-
// path actually is at the moment of the commit.
13+
// path actually is at the moment of the commit. The identities below are read with
14+
// { bigint: true } because the guard compares bigints: a plain stat hands back a 64-bit NTFS file
15+
// id rounded to a double, so the guard would be comparing rounded numbers, and above 2**53 two
16+
// different files can round to the same one. This volume's measured ids are all below 2**53 (see
17+
// the option's comment), so these rows exercise the comparison and not the rounding.
1418
describe("safeWriteText authorized identity", () => {
1519
let dir: string
1620
beforeEach(async () => {
@@ -23,7 +27,7 @@ describe("safeWriteText authorized identity", () => {
2327
it("publishes when the target is still the file the caller authorized", async () => {
2428
const file = path.join(dir, "target.txt")
2529
await fs.promises.writeFile(file, "before")
26-
const authorized = await fs.promises.stat(file)
30+
const authorized = await fs.promises.stat(file, { bigint: true })
2731
await safeWriteText(file, "after", { authorizedTarget: { dev: authorized.dev, ino: authorized.ino } })
2832
expect(await fs.promises.readFile(file, "utf8")).toBe("after")
2933
})
@@ -40,7 +44,7 @@ describe("safeWriteText authorized identity", () => {
4044
const other = path.join(dir, "other.txt")
4145
await fs.promises.writeFile(file, "before")
4246
await fs.promises.writeFile(other, "someone else's")
43-
const otherIdentity = await fs.promises.stat(other)
47+
const otherIdentity = await fs.promises.stat(other, { bigint: true })
4448
await expect(
4549
safeWriteText(file, "after", { authorizedTarget: { dev: otherIdentity.dev, ino: otherIdentity.ino } }),
4650
).rejects.toThrow(/changed identity after it was authorized/)
@@ -53,7 +57,7 @@ describe("safeWriteText authorized identity", () => {
5357
it("refuses rather than reporting a raw stat failure when the authorized file is gone", async () => {
5458
const file = path.join(dir, "target.txt")
5559
await fs.promises.writeFile(file, "before")
56-
const authorized = await fs.promises.stat(file)
60+
const authorized = await fs.promises.stat(file, { bigint: true })
5761
await fs.promises.unlink(file)
5862
await expect(
5963
safeWriteText(file, "after", { authorizedTarget: { dev: authorized.dev, ino: authorized.ino } }),

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

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,17 @@ export interface SafeWriteTextOptions {
1919
* rename below refuses unless the target is still that same file, so an authorization made
2020
* outside this module cannot be spent on a link or a different file swapped in for the pathname
2121
* afterwards. A failure to read the identity counts as "not that file": the guard fails closed.
22+
*
23+
* Both halves are bigint because they are read from `stat(..., { bigint: true })`, on both sides
24+
* of the comparison. A plain stat returns a 64-bit NTFS file id rounded to a double, so above
25+
* 2**53 two different files can be reported with the same number and the guard would accept one
26+
* for the other; there is no way to recover the lost bits from the rounded value, so the capture
27+
* spelling has to be right rather than the comparison. Measured on this box's NTFS volume, three
28+
* identities came back as 281474990289684, 4503599627490809 and 5629499534337367 - all below
29+
* 2**53, so this volume cannot exhibit the collision, which is why the fix is the type and the
30+
* capture and not a test here.
2231
*/
23-
authorizedTarget?: { dev: number; ino: number }
32+
authorizedTarget?: { dev: bigint; ino: bigint }
2433

2534
/**
2635
* Platform override for testing. When omitted the real process.platform
@@ -749,7 +758,7 @@ export async function safeWriteText(
749758
// narrows the window to this stat-plus-rename pair - the most a rename-based writer can do.
750759
const authorizedTarget = options?.authorizedTarget
751760
if (authorizedTarget) {
752-
const identity = await fs.stat(targetPath).catch(() => undefined)
761+
const identity = await fs.stat(targetPath, { bigint: true }).catch(() => undefined)
753762
if (!identity || identity.dev !== authorizedTarget.dev || identity.ino !== authorizedTarget.ino) {
754763
throw new Error(`safeWriteText: ${absoluteFilePath} changed identity after it was authorized`)
755764
}

0 commit comments

Comments
 (0)