diff --git a/src/services/file-safety/__tests__/safeWritePrimitives.errors.spec.ts b/src/services/file-safety/__tests__/safeWritePrimitives.errors.spec.ts new file mode 100644 index 0000000000..4937bcbcdf --- /dev/null +++ b/src/services/file-safety/__tests__/safeWritePrimitives.errors.spec.ts @@ -0,0 +1,67 @@ +// The three classes below are raised by the primitives commit path. The JSON layer imports +// them only to re-name a fault it did not raise (see the _publishFault doc comment in +// src/utils/safeWriteJson.ts), so no caller in this tree constructs them yet: their names, +// their messages and the fields they carry are observable only by building them. These tests +// build them, so the next caller that reads a name or a stage-specific sentence is reading +// something that was checked rather than something that was never run. + +import { PostCommitDurabilityError, StagingPathError, StagingReplacedError } from "../safeWritePrimitives" + +describe("StagingPathError", () => { + it("names itself and carries the rejected staging path", () => { + const error = new StagingPathError("staging path is outside the target directory", "/tmp/x/.zdt-stage-1") + expect(error).toBeInstanceOf(Error) + expect(error.name).toBe("StagingPathError") + expect(error.stagingPath).toBe("/tmp/x/.zdt-stage-1") + expect(error.message).toBe("staging path is outside the target directory") + }) +}) + +describe("PostCommitDurabilityError", () => { + it("names itself, carries both paths, keeps the fsync failure as its cause, and states the claim it makes", () => { + const cause = Object.assign(new Error("EIO: i/o error, fsync"), { code: "EIO" }) + const error = new PostCommitDurabilityError("/tmp/x/mcp.json", cause, "/tmp/x/.zdt-backup-1") + expect(error.name).toBe("PostCommitDurabilityError") + expect(error.targetPath).toBe("/tmp/x/mcp.json") + expect(error.backupPath).toBe("/tmp/x/.zdt-backup-1") + expect(error.cause).toBe(cause) + // The sentence is the contract: the rename landed, the directory entry is what failed. + // A caller that reports this as a lost write tells the user the opposite of what happened. + expect(error.message).toContain("The rename committed") + expect(error.message).toContain("parent directory could not be fsynced") + expect(error.message).toContain("directory entry may not be durable") + }) + it("reports no retained copy when backup mode left none", () => { + const error = new PostCommitDurabilityError("/tmp/x/mcp.json", new Error("EIO: i/o error, fsync")) + expect(error.backupPath).toBeNull() + }) +}) + +describe("StagingReplacedError", () => { + it("says the commit was skipped when the swap was noticed before the commit rename", () => { + const error = new StagingReplacedError("/tmp/x/.zdt-stage-1", "before-commit", "/tmp/x/mcp.json", null) + expect(error.name).toBe("StagingReplacedError") + expect(error.stage).toBe("before-commit") + expect(error.stagingPath).toBe("/tmp/x/.zdt-stage-1") + expect(error.targetPath).toBe("/tmp/x/mcp.json") + expect(error.backupPath).toBeNull() + expect(error.message).toContain("/tmp/x/.zdt-stage-1") + expect(error.message).toContain("no longer names the file this write staged") + expect(error.message).toContain("the target was left as it was") + // The after-commit sentence would claim a publish this write never made. + expect(error.message).not.toContain("did not stage") + }) + it("says the target holds a foreign file when the swap was noticed after the commit rename", () => { + const error = new StagingReplacedError( + "/tmp/x/.zdt-stage-1", + "after-commit", + "/tmp/x/mcp.json", + "/tmp/x/.zdt-backup-1", + ) + expect(error.stage).toBe("after-commit") + expect(error.message).toContain("was replaced before the commit rename landed") + expect(error.message).toContain("a file this write did not stage") + expect(error.message).not.toContain("left as it was") + expect(error.backupPath).toBe("/tmp/x/.zdt-backup-1") + }) +}) diff --git a/src/services/file-safety/safeWritePrimitives.ts b/src/services/file-safety/safeWritePrimitives.ts new file mode 100644 index 0000000000..00f055148b --- /dev/null +++ b/src/services/file-safety/safeWritePrimitives.ts @@ -0,0 +1,367 @@ +import * as fs from "fs/promises" +import * as path from "path" +import { execFile } from "child_process" + +export interface SafeWriteTextOptions { + /** + * When true, keep the old-file semantics without ever removing the target: the + * previous content is copied to a hidden backup path and flushed before the + * commit rename, the commit rename atomically replaces the target, and on success + * the backup copy is deleted. A failure before the commit leaves the target + * untouched (there is nothing to roll back) and removes the backup copy. When + * false (default) the atomic rename simply replaces the target. + */ + backup?: boolean + + /** + * Platform override for testing. When omitted the real process.platform + * value is used. Set to "win32" or "linux" / "darwin" from tests so that + * both branches are reachable without needing a real Windows runner. + */ + platform?: string + + /** + * Custom execFile runner for testing (e.g. vi.fn). When omitted the real + * child_process.execFile is used. + */ + execFileRunner?: typeof execFile + + /** + * Sink for non-fatal safety notices. A Windows DACL that could not be captured means the + * committed file may inherit different access rights: the write still proceeds (a missing or + * failing icacls must not block saving), but the caller is told instead of the change being + * silent. Defaults to console.warn. + */ + onWarning?: (message: string) => void + + /** + * Pre-written temp path to use for the commit phase. When provided, + * safeWriteText skips creating its own staging file and uses this path + * instead (it still fsyncs before rename). Useful when a caller has + * already written data to a temp file via a custom stream. + */ + tempPath?: string + + /** + * The publish target the caller already authorized. + * A caller that checks workspace containment and then calls this primitive resolves + * the path twice: once for its own decision and once here. If a link is swapped in + * between the two, the decision was about a different file than the one published. + * Passing the authorized value makes that drift fatal instead of silent. + */ + expectedResolvedPath?: string + + /** + * The directories the caller walked when it authorized this target, with the + * (dev, ino) identity each had at that moment. + * + * expectedResolvedPath pins the NAME this write publishes; it cannot see a parent + * directory being replaced by a link between the caller's containment check and the + * commit. Re-checking the ancestor identities immediately before the commit makes a + * swapped parent fatal too: the publish then aborts instead of writing through the new + * link. Node has no descriptor-relative rename, so a swap that lands after this check + * and before the rename is not eliminable here - it narrows the window to the commit + * itself rather than the whole guard. + * The identity check is paired with a realpath comparison: moving a directory + * preserves (dev, ino), and replacing its old name with a symlink to the moved + * location keeps stat() matching while sending the commit to the new location. + * The name must still resolve to the authorized location, not merely to the + * same inode. + */ + expectedAncestorIdentities?: AncestorIdentity[] +} + +/** One directory's on-disk identity, read with bigint stats so NTFS 64-bit values survive. */ +export type AncestorIdentity = { + dir: string + dev: bigint + ino: bigint +} + +/** + * A caller-supplied staging path that is not a file this write may publish: it + * sits outside the target's directory (so the commit rename would cross + * filesystems) or is not a regular file. Rejecting it before any write keeps the + * target from being replaced by whatever the path points at. + */ +export class StagingPathError extends Error { + readonly stagingPath: string + + constructor(message: string, stagingPath: string) { + super(message) + this.name = "StagingPathError" + this.stagingPath = stagingPath + } +} + +/** + * The commit rename succeeded but the parent-directory fsync did not, so the + * directory entry is not known to be durable. The content is at the target; the + * caller cannot assume it survives a crash. Reported as its own error so a + * successful return never claims durability the filesystem did not grant. + */ +export class PostCommitDurabilityError extends Error { + readonly targetPath: string + /** + * The old-content copy this path retains for recovery, or null when backup mode was off + * or no copy was taken. The name is a hidden random path, so without this field no caller + * could find the copy the failure cleanup deliberately keeps. + */ + readonly backupPath: string | null + + constructor(targetPath: string, cause: unknown, backupPath: string | null = null) { + super( + "The rename committed but the parent directory could not be fsynced -- the content is at the target path reported on this error, and the directory entry may not be durable.", + { cause }, + ) + this.name = "PostCommitDurabilityError" + this.targetPath = targetPath + this.backupPath = backupPath + } +} + +/** + * The staging entry this write validated, wrote and fsynced was found to name another + * file at the commit. The commit rename publishes whatever the staging name holds the + * moment it runs, so a peer that replaced the entry between validation and publication + * would otherwise have its own content committed onto the target while this write + * reported success. Reported as its own error so a failed write cannot claim a publish + * it did not make. + */ +export class StagingReplacedError extends Error { + readonly stagingPath: string + /** Where it was noticed: before anything was published, or after the commit rename landed. */ + readonly stage: "before-commit" | "after-commit" + /** The path the publish was aimed at. The staging name is a random path this module invented, so a caller that has to say which file it was saving cannot derive it from the staging path. */ + readonly targetPath: string + /** + * The copy of the previous content this failure leaves behind, or null when it leaves none: + * backup mode off, no target before the write, or a before-commit failure whose handler + * deletes the redundant copy. The name is a hidden random path, so without this field the + * retained copy sat where no caller could find it - the same reason PostCommitDurabilityError + * carries it. + */ + readonly backupPath: string | null + + constructor( + stagingPath: string, + stage: "before-commit" | "after-commit", + targetPath: string, + backupPath: string | null = null, + ) { + super( + stage === "before-commit" + ? `Staging entry ${stagingPath} no longer names the file this write staged; the commit rename was skipped and the target was left as it was.` + : `Staging entry ${stagingPath} was replaced before the commit rename landed; the target now holds a file this write did not stage.`, + ) + this.name = "StagingReplacedError" + this.stagingPath = stagingPath + this.stage = stage + this.targetPath = targetPath + this.backupPath = backupPath + } +} + +/** + * The backup copy could not be created AND the partial copy could not be removed. + * The write failed either way, but the leftover is a copy of the previous content that + * is still on disk: its path travels on the error so the caller can remove it, instead + * of the cleanup silently discarding the only reference to it. + */ +export class OrphanedBackupError extends Error { + readonly orphanedBackupPath: string + readonly originalError: unknown + readonly cleanupError: unknown + constructor(backupPath: string, targetPath: string, cause: unknown, cleanupError: unknown) { + super(_orphanedBackupMessage(targetPath, backupPath, cause, cleanupError), { cause }) + this.name = "OrphanedBackupError" + this.orphanedBackupPath = backupPath + this.originalError = cause + this.cleanupError = cleanupError + } +} + +function _orphanedBackupMessage(targetPath: string, backupPath: string, cause: unknown, cleanupError: unknown): string { + const reason = (error: unknown): string => (error instanceof Error ? error.message : String(error)) + return ( + `safeWriteText: could not create the backup of ${targetPath} (${reason(cause)}), and the ` + + `partial copy at ${backupPath} could not be removed (${reason(cleanupError)}). The copy is ` + + `still on disk and must be deleted.` + ) +} + +/** + * The path resolved to something other than the target the caller authorized. + * Nothing is staged or published: a link swapped in after the caller's containment + * check would otherwise send the write to a file that check never covered. + */ +export class TargetMovedError extends Error { + readonly authorizedPath: string + readonly resolvedPath: string + constructor(authorizedPath: string, resolvedPath: string) { + super( + `The write was authorized for ${authorizedPath}, but that path now resolves to ${resolvedPath} -- nothing was published.`, + ) + this.name = "TargetMovedError" + this.authorizedPath = authorizedPath + this.resolvedPath = resolvedPath + } +} + +/** + * A directory the caller walked on its way to the authorized target is no longer the + * directory it was: it was removed, replaced, or turned into a link to somewhere else. + * Publishing through it would act on a decision that was never made about the file now + * reachable there, so the commit is aborted. + */ +export class AncestorReplacedError extends Error { + readonly directory: string + constructor(directory: string, reason: string) { + super(`A directory on the authorized path (${directory}) ${reason} -- nothing was published.`) + this.name = "AncestorReplacedError" + this.directory = directory + } +} + +/** + * How far resolveLockKey follows a chain of links. 40 is where Node's own resolver gives up + * with ELOOP, so every chain the operating system is willing to resolve is a chain this walk + * resolves too; a smaller bound stops at an intermediate link of a long chain, and the writer + * that stopped there queues on a different lock from the writer standing at the referent - the + * two-locks-for-one-file case canonicalDirKey exists to prevent. + */ +const MAX_SYMLINK_HOPS = 40 + +export async function resolvePublishTarget(absoluteFilePath: string): Promise { + return fs.realpath(absoluteFilePath).catch(async (error: unknown) => { + if (errorCode(error) !== "ENOENT") throw error + // ENOENT also covers a dangling symlink, which must never be written through. + // Only a lstat that also reports the path as absent may fall back to the + // given path; a real lstat failure (EACCES, EIO) says nothing about whether + // the path is a link, so falling back would write through a link we were + // simply not allowed to inspect. + const linkStat = await fs.lstat(absoluteFilePath).catch((lstatError: unknown) => { + if (errorCode(lstatError) === "ENOENT") return undefined + throw lstatError + }) + if (linkStat?.isSymbolicLink()) throw error + return absoluteFilePath + }) +} +/** + * Distinguish "the target does not exist" from a real I/O failure (EACCES, + * EIO, ...). The mode-preservation path may only fall back to the fresh-file + * default on ENOENT; any other failure is propagated, otherwise a restrictive + * target (0o600) would be published with the default 0o644 through the rename. + */ +export function errorCode(error: unknown): string | undefined { + return typeof error === "object" && error !== null && "code" in error + ? String((error as { code: unknown }).code) + : undefined +} + +/** + * Canonicalize the parent directory and re-join the basename. fs.realpath + * canonicalizes every component, including a symlinked ancestor directory or a + * Windows 8.3 short name, so a lock key must be canonical even when the file + * itself is not there yet -- otherwise the key for one file depends on whether + * the file exists when the key is computed, and two writers take two locks. + * Components that are not there yet are walked over and re-joined onto the nearest + * ancestor that is: the writer that arrives before this file's parent directory is + * created has to take the lock of the writer that arrives after it. Only a missing + * component may be walked over. An ancestor that exists but cannot be canonicalized + * (ENOTDIR under a regular-file component, EACCES, EIO, ELOOP) means the canonical + * key is unknown, and handing back the literal spelling would key this writer apart + * from every writer that did canonicalize the same file. + */ + +async function canonicalDirKey(absoluteFilePath: string): Promise { + const basename = path.basename(absoluteFilePath) + const missing: string[] = [] + let cursor = path.dirname(absoluteFilePath) + for (;;) { + try { + const canonicalDir = await fs.realpath(cursor) + return path.join(canonicalDir, ...missing.reverse(), basename) + } catch (error: unknown) { + if (errorCode(error) !== "ENOENT") { + throw error + } + const parent = path.dirname(cursor) + if (parent === cursor) { + // The root of this path was reached with components still missing: no ancestor + // is left to canonicalize, so this spelling is the only answer available. + return path.join(cursor, ...missing.reverse(), basename) + } + missing.push(path.basename(cursor)) + cursor = parent + } + } +} + +/** + * Lock key for a publish target: the symlink referent when the path is an + * existing symlink, the path itself otherwise. Unlike resolvePublishTarget this + * tolerates a dangling link, because the lock key has to be computable while a + * peer writer is mid-commit (a publish renames the staged file onto the referent, + * and backup mode keeps a copy beside it). + * The walk is bounded, and a chain the bound cannot resolve rejects rather than naming + * an arbitrary intermediate link: two writers that enter the same chain from different + * ends would otherwise key one file with two different locks. Every key it does return + * is canonicalized through canonicalDirKey. + */ +export async function resolveLockKey(absoluteFilePath: string): Promise { + try { + return await canonicalDirKey(await resolvePublishTarget(absoluteFilePath)) + } catch (error: unknown) { + // Only a dangling link (ENOENT) may fall through to the walk: any other + // resolution error (EACCES, EIO) would key this writer to the alias path + // while a writer reaching the referent directly keys the referent, and + // the two writers would then take different locks for one file. + if (errorCode(error) !== "ENOENT") { + throw error + } + // A real readlink reports "this is not a link" by throwing: EINVAL on the + // platforms this file runs on (measured with node 22.23.4 on win32, and EINVAL + // on linux), and ENOENT when the path itself is gone. Those two answers end the + // walk. Any other failure - EACCES, EIO, ELOOP - says nothing about whether this + // path is a link, so it propagates: keying this writer to the alias while a + // writer that reached the referent keys the referent is the two-locks-for-one-file + // loss this function exists to prevent, and guessing it is how that loss arrives. + const linkWalkLimit = MAX_SYMLINK_HOPS + let key = absoluteFilePath + for (let depth = 0; depth < linkWalkLimit; depth++) { + const target = await fs.readlink(key).catch((linkError: unknown) => { + const code = errorCode(linkError) + if (code === "ENOENT" || code === "EINVAL") return undefined + throw linkError + }) + if (target === undefined) return await canonicalDirKey(key) + // A relative referent is relative to the link's REAL parent, not to the spelling the + // caller arrived with: under a symlinked directory `..` names the referent's parent, + // so a lexical join keys a different file and the writer through the alias stops + // excluding the writer through the referent. When the link's own parent cannot be + // canonicalized - a dangling chain - the lexical join is the only answer available. + const referentParent = path.isAbsolute(target) + ? undefined + : await fs.realpath(path.dirname(key)).catch(() => undefined) + key = await canonicalDirKey(path.resolve(referentParent ?? path.dirname(key), target)) + } + // The bound only exists to terminate a cycle. Past it the chain names no file, so + // the caller is told instead of handed whichever link the walk stopped on. + throw new Error( + `safeWriteText: could not resolve a lock key for ${absoluteFilePath}: the symlink chain is deeper than ${linkWalkLimit} links`, + ) + } +} + +/** + * The publish primitive itself. Tagged @internal because nothing in the shipped + * extension reaches it yet: this unit lands the primitive and its evidence, and the + * writer that is meant to call it arrives with the guardedWrite migration. Without the + * tag the production Knip view reports this export as unused, which states the wrong + * reason - the export is deliberate, its consumer is later in the merge order - and the + * alternative is blanking this whole module in knip.json. + * + * @internal + */ diff --git a/src/utils/__tests__/safeWriteJson.interruption.test.ts b/src/utils/__tests__/safeWriteJson.interruption.test.ts index c9c5993f84..4197eb1eba 100644 --- a/src/utils/__tests__/safeWriteJson.interruption.test.ts +++ b/src/utils/__tests__/safeWriteJson.interruption.test.ts @@ -28,16 +28,48 @@ const CHILD_SCRIPT = `"use strict" const fs = require("fs") const path = require("path") -const targetPath = path.resolve(process.env.INTERRUPTION_TARGET_PATH) +const targetSpec = path.resolve(process.env.INTERRUPTION_TARGET_PATH) const fsPromises = require("fs/promises") const actualRename = fsPromises.rename +// Identity, not spelling. The writer renames to the publish target it resolved through +// symlinks, and node's async fs.realpath expands an NTFS 8.3 alias, so on a runner whose +// temp path is reported as an alias (the normal windows-latest condition: the profile is +// RUNNER~1 there) the parent's authorized spelling and the writer's rename destination are +// different strings for one file. A text equality here never fires, every case prints +// WRITE_COMPLETED, and the injection silently stops being an injection. Decide what the +// destination IS: same name, and the same directory by dev+ino. The basenames under test +// are unique inside the storage directory, so the pair cannot land on another file. +const targetBase = path.basename(targetSpec) +function sameTargetAsAuthorized(candidate) { + if (path.basename(String(candidate)) !== targetBase) { + return false + } + const resolved = path.resolve(String(candidate)) + if (resolved === targetSpec) { + return true + } + let candidateDir = null + let authorizedDir = null + try { + candidateDir = fs.statSync(path.dirname(resolved), { bigint: true }) + } catch { + return false + } + try { + authorizedDir = fs.statSync(path.dirname(targetSpec), { bigint: true }) + } catch { + return false + } + return candidateDir.dev === authorizedDir.dev && candidateDir.ino === authorizedDir.ino +} + // Fault injection: hard-kill before the replacement lands. Any rename // whose destination is the canonical path is the commit step, whatever // replacement protocol the writer uses; exit before performing it. let commitAttempts = 0 fsPromises.rename = async function interruptionRename(oldPath, newPath) { - if (path.resolve(String(newPath)) === targetPath) { + if (sameTargetAsAuthorized(newPath)) { commitAttempts++ if (process.env.INTERRUPTION_MODE === "fallback" && commitAttempts === 1) { return Promise.reject(Object.assign(new Error("Injected EPERM"), { code: "EPERM" })) @@ -63,7 +95,7 @@ require(process.env.ESBUILD_PATH).buildSync({ const payload = JSON.parse(process.env.INTERRUPTION_PAYLOAD) require(process.env.INTERRUPTION_BUNDLE_PATH) - .safeWriteJson(targetPath, payload) + .safeWriteJson(targetSpec, payload) .then(() => { fs.writeSync(1, "WRITE_COMPLETED\\n") process.exit(0) diff --git a/src/utils/__tests__/safeWriteJson.lockKey.spec.ts b/src/utils/__tests__/safeWriteJson.lockKey.spec.ts new file mode 100644 index 0000000000..6cb23d3f7e --- /dev/null +++ b/src/utils/__tests__/safeWriteJson.lockKey.spec.ts @@ -0,0 +1,366 @@ +// npx vitest run utils/__tests__/safeWriteJson.lockKey.spec.ts + +import * as os from "os" +import path from "path" +import { existsSync } from "fs" +import type { BigIntStats } from "fs" +import * as fs from "fs/promises" +import { acquireFileLock } from "../fileLock" +import { safeWriteJson } from "../safeWriteJson" +import { resolveLockKey } from "../../services/file-safety/safeWritePrimitives" + +vi.mock("../fileLock", () => ({ + acquireFileLock: vi.fn(async () => async () => {}), +})) + +vi.mock("fs/promises", async () => { + const actual = await vi.importActual("fs/promises") + return { ...actual, realpath: vi.fn(), lstat: vi.fn(), readlink: vi.fn() } +}) + +const mockedRealpath = vi.mocked(fs.realpath) +const mockedLstat = vi.mocked(fs.lstat) +const mockedReadlink = vi.mocked(fs.readlink) +const mockedAcquireFileLock = vi.mocked(acquireFileLock) + +const enoent = Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" }) + +// Each test creates a real temp directory so the real fs calls still work. +// doubles between tests so an implementation from one test cannot carry over. +const createdDirs: string[] = [] +async function makeDir(prefix: string): Promise { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), prefix)) + createdDirs.push(dir) + return dir +} + +beforeEach(() => { + mockedRealpath.mockReset() + mockedLstat.mockReset() + mockedReadlink.mockReset() + mockedAcquireFileLock.mockReset() +}) + +afterEach(async () => { + for (const dir of createdDirs) { + await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined) + } + createdDirs.length = 0 +}) + +// Only isSymbolicLink() is consulted by the guard, so the double carries just +// that method. The mocks reject asynchronously: a synchronous throw would bypass +// resolvePublishTarget's catch and skip the ENOENT/symlink branch under test. +const symlinkStat = (target: unknown) => + ({ + isSymbolicLink: () => target === currentLink, + // The staging-path check in safeWriteText also asks whether the path is a + // regular file, so the double carries that predicate as well. + isFile: () => target !== currentLink, + }) as unknown as BigIntStats +let currentLink = "" + +describe("safeWriteJson lock key under a peer commit", () => { + it("waits for the peer instead of rejecting, and locks the referent", async () => { + const order: string[] = [] + const dir = await makeDir("lockkey-") + const referent = path.join(dir, "history_item.json") + currentLink = path.join(dir, "link.json") + + // The peer writer has renamed the referent away and has not committed yet, + // so the first resolution fails with ENOENT while lstat still reports a + // symbolic link. A strict resolve here rejects the caller before it can ever + // queue behind the peer, and the caller's delta write is lost. + mockedRealpath + .mockImplementationOnce(async () => { + order.push("resolve-failed") + throw enoent + }) + .mockImplementation(async (target) => { + order.push("resolve") + // The second call happens under the lock, where the peer has committed. + return target === currentLink ? referent : String(target) + }) + mockedLstat.mockImplementation(async (target) => { + order.push("lstat") + return symlinkStat(target) + }) + // A real readlink reports a non-link by rejecting with code EINVAL (measured with + // node 22.23.4 on win32; linux reports the same code), and the lock-key walk ends the + // walk on exactly that code, so the double carries it. + mockedReadlink.mockImplementation(async (target) => + target === currentLink + ? referent + : Promise.reject(Object.assign(new Error("not a link"), { code: "EINVAL" })), + ) + mockedAcquireFileLock.mockImplementation(async () => { + order.push("lock") + return async () => {} + }) + + await safeWriteJson(currentLink, { id: "task-1" }) + + // The lock key is the key every other writer to this file uses, so the caller + // queued behind the peer instead of failing before the lock. + expect(mockedAcquireFileLock).toHaveBeenCalledWith(referent) + // The lock key is the key every other writer to this file uses, so the caller + // queued behind the peer instead of failing before the lock. + expect(mockedAcquireFileLock).toHaveBeenCalledWith(referent) + // Choreography under the merged protocol: the pre-lock resolution is tolerant (a link the + // peer has not committed yet must not reject the caller), and the strict resolution runs + // after the recovery pass so an interrupted publish that recovery restores still resolves. + // That is one resolution more than a single strict resolve under the lock would cost, and + // staging plus every rename site then name the string that strict step returned, so + // nothing is left to diverge on afterwards. + expect(order).toEqual(["resolve-failed", "lstat", "resolve", "resolve", "lock", "resolve", "resolve"]) + expect(JSON.parse(await fs.readFile(referent, "utf8"))).toEqual({ id: "task-1" }) + }) + + it("releases the lock when the resolution under the lock rejects", async () => { + const order: string[] = [] + let released = false + const dir = await makeDir("lockkey-") + const referent = path.join(dir, "history_item.json") + currentLink = path.join(dir, "link.json") + + // A real dangling link: the walk tolerates it so the caller can queue behind + // the peer, but once the lock is held the strict rejection still applies. A + // rejection outside the protected block would leave the lock held until the + // stale timeout for every other writer to the same file. + mockedRealpath.mockImplementation(async () => { + throw enoent + }) + mockedLstat.mockImplementation(async (target) => { + order.push("lstat") + return symlinkStat(target) + }) + // Non-link answers carry EINVAL, the code a real readlink reports (see the row above). + mockedReadlink.mockImplementation(async (target) => + target === currentLink + ? referent + : Promise.reject(Object.assign(new Error("not a link"), { code: "EINVAL" })), + ) + mockedAcquireFileLock.mockImplementation(async () => { + order.push("lock") + return async () => { + order.push("release") + released = true + } + }) + + await expect(safeWriteJson(currentLink, { id: "task-1" })).rejects.toThrow(enoent) + expect(released).toBe(true) + // The strict rejection is reached through the ENOENT + symlink branch of the resolution + // that runs after the recovery pass, not through a synchronous throw that skips it, and the + // second lstat entry is that branch consulting lstat before refusing. + expect(order).toEqual(["lstat", "lock", "lstat", "lstat", "release"]) + }) + + it("canonicalizes the parent directory when the file itself is not there yet", async () => { + // fs.realpath canonicalizes every component, including a symlinked ancestor + // directory or a Windows 8.3 short name. If the fallback returns the alias + // directory, the key depends on whether the file exists at the moment the key + // is computed, and a writer that resolved the canonical directory takes a + // different lock for the same file. + const aliasDir = path.join(os.tmpdir(), "alias-dir") + const canonicalDir = path.join(os.tmpdir(), "canonical-dir") + const file = path.join(aliasDir, "history_item.json") + mockedRealpath.mockImplementation(async (target) => { + if (target === file) throw enoent + return canonicalDir + }) + mockedLstat.mockImplementation( + async () => ({ isSymbolicLink: () => false, isFile: () => true }) as unknown as BigIntStats, + ) + + expect(await resolveLockKey(file)).toBe(path.join(canonicalDir, "history_item.json")) + }) + + it("propagates a non-ENOENT resolution failure instead of keying on the alias", async () => { + // EACCES from realpath is not a dangling link: falling back to the walk + // would key this writer to the alias path while a writer reaching the + // referent directly keys the referent, and the two writers would take + // different locks for the same file. + const aliasDir = path.join(os.tmpdir(), "alias-dir") + const file = path.join(aliasDir, "history_item.json") + const eacces = Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" }) + mockedRealpath.mockImplementation(async () => { + throw eacces + }) + await expect(resolveLockKey(file)).rejects.toBe(eacces) + }) +}) + +it("recovers an interrupted write beside the referent the lock key names, not beside the spelling the caller arrived with", async () => { + // The interrupted writer staged its files beside the publish target it resolved. A writer + // that arrives through a differently named alias finds them only by looking beside the + // referent, which is where the lock key points; keyed to the caller's own spelling it scans + // a different directory, leaves the orphaned backup where it is, and stages beside the alias. + // A directory link cannot expose this on either platform - both spellings enumerate the same + // entries - so this is proved the way the rest of the key is proved here: a mocked resolution + // over a real filesystem, plus the path the recovery call was actually handed. + const realDir = await makeDir("recovery-real-") + const aliasDir = await makeDir("recovery-alias-") + const referent = path.join(realDir, "history_item.json") + const alias = path.join(aliasDir, "history_item.json") + const leftover = `.history_item.json.bak_${Date.now()}_fedcba.tmp` + await fs.writeFile(path.join(realDir, leftover), JSON.stringify({ previous: "content" }), "utf8") + + mockedRealpath.mockImplementation(async (target) => + path.resolve(String(target)) === path.resolve(alias) ? referent : String(target), + ) + const realLstat = (await vi.importActual("fs/promises")).lstat + mockedLstat.mockImplementation(async (target) => realLstat(String(target))) + mockedAcquireFileLock.mockImplementation(async () => async () => {}) + + const recoveryModule = await import("../jsonFileRecovery") + // Captured before the spy is installed: calling the namespace property from inside the + // implementation would recurse through the spy itself. + const realRecover = recoveryModule.recoverInterruptedReplacement + const recovered: string[] = [] + const recoverySpy = vi.spyOn(recoveryModule, "recoverInterruptedReplacement").mockImplementation(async (target) => { + recovered.push(path.resolve(String(target))) + return realRecover(target) + }) + + try { + await safeWriteJson(alias, { id: "task-1" }) + } finally { + recoverySpy.mockRestore() + } + + // Recovery ran against the key, so it scanned the directory beside the referent. + expect(recovered).toEqual([path.resolve(referent)]) + // The orphaned backup was found and restored, and the write then published the caller's + // content over it. (The write's own backup step leaves a fresh .bak_ file beside the + // target; the name asserted here is the one this fixture planted.) + expect((await fs.readdir(realDir)).filter((entry) => entry === leftover)).toEqual([]) + expect(JSON.parse(await fs.readFile(referent, "utf8"))).toEqual({ id: "task-1" }) + // Nothing was staged beside the alias. + expect(await fs.readdir(aliasDir)).toEqual([]) +}) + +it("does not log a cleanup error when the safety net finds the temp file already gone", async () => { + // safeWriteText removes its own temp file on failure, so the safety net in + // safeWriteJson normally finds it gone. That is the expected outcome, not a + // second failure, and it must not be logged as one. + const dir = await makeDir("cleanup-") + const target = path.join(dir, "history_item.json") + currentLink = "" + mockedRealpath.mockImplementation(async (t) => String(t)) + mockedLstat.mockImplementation(async (t) => symlinkStat(t)) + + const renameSpy = vi.spyOn(fs, "rename").mockRejectedValue(new Error("commit rename failed")) + const unlinkSpy = vi.spyOn(fs, "unlink").mockRejectedValue(enoent) + const consoleError = vi.spyOn(console, "error").mockImplementation(() => {}) + + try { + await expect(safeWriteJson(target, { id: "task-1" })).rejects.toThrow("commit rename failed") + + // Only the original failure is reported. + expect(consoleError).toHaveBeenCalledTimes(1) + } finally { + // Restore even when an assertion fails: the afterEach cleanup runs fs.rm + // with these spies still in place otherwise, and later tests inherit a + // rejecting rename. + renameSpy.mockRestore() + unlinkSpy.mockRestore() + consoleError.mockRestore() + } +}) + +// Blocks carried across the merge from the side that landed this module on the writers unit (pull +// 2452). The merged module keeps that side's guarantees, so its evidence travels with them. +// They are appended in their own describe so this file's own setup stays readable. +describe("guarantees carried from the writers unit (2452)", () => { + it("follows a chain of nine links to the file it ends at", async () => { + // Nine links, dangling at the far end. A walk that stops at eight leaves the key naming + // an intermediate link, so a writer that named the file through this chain queued on a + // different lock from a writer standing at the file itself - two locks for one file, + // reached by chain length instead of by spelling. + const chain = [ + "a0.json", + "a1.json", + "a2.json", + "a3.json", + "a4.json", + "a5.json", + "a6.json", + "a7.json", + "a8.json", + ] + const referent = path.resolve("/tmp/chain-dir", "history_item.json") + const targets = new Map() + chain.forEach((name, index) => { + targets.set( + path.resolve("/tmp/chain-dir", name), + index + 1 < chain.length ? path.resolve("/tmp/chain-dir", chain[index + 1]) : referent, + ) + }) + mockedRealpath.mockRejectedValue(enoent) + mockedLstat.mockImplementation( + async (target) => + ({ + isSymbolicLink: () => targets.has(String(target)), + isFile: () => !targets.has(String(target)), + }) as unknown as BigIntStats, + ) + mockedReadlink.mockImplementation(async (target) => { + const next = targets.get(String(target)) + return next === undefined + ? Promise.reject(Object.assign(new Error("not a link"), { code: "EINVAL" })) + : next + }) + + const viaChain = await resolveLockKey(path.resolve("/tmp/chain-dir", chain[0])) + + // One readlink per link, all nine, plus the probe that finds a non-link at the far end: + // the key names the file, not a link part-way down the chain. + expect(mockedReadlink).toHaveBeenCalledTimes(chain.length + 1) + expect(viaChain).toBe(referent) + }) + + it("heals the interrupted publish beside the referent while the alias dangles", async () => { + const linkDir = await makeDir("lockkey-link-") + const referentDir = await makeDir("lockkey-referent-") + const referent = path.join(referentDir, "history_item.json") + currentLink = path.join(linkDir, "link.json") + // An interrupted two-step replacement: the previous write renamed the committed file to + // its backup and never landed the replacement, so the committed content sits in a + // backup beside the referent while the referent itself is absent. The link was renamed + // away too, so the alias resolves nowhere. + const backupPath = path.join(referentDir, ".history_item.json.bak_previous.tmp") + await fs.writeFile(backupPath, JSON.stringify({ version: "committed" })) + // Neither spelling resolves while the referent is missing, which is what a dangling + // link looks like to realpath. Recovery restores the referent, and from then on both + // spellings resolve again. + // Only the two spellings of the missing file fail to resolve; directory components answer with + // their own path, which is what a real filesystem does while the referent is away, and the + // canonical key walk has to resolve them to find the nearest real ancestor. + mockedRealpath.mockImplementation(async (target) => { + const p = String(target) + if (!existsSync(referent) && (p === referent || p === currentLink)) { + throw enoent + } + return p === currentLink ? referent : p + }) + mockedLstat.mockImplementation(async (target) => symlinkStat(target)) + mockedReadlink.mockImplementation(async (target) => + target === currentLink + ? referent + : Promise.reject(Object.assign(new Error("not a link"), { code: "EINVAL" })), + ) + mockedAcquireFileLock.mockResolvedValue(async () => {}) + + await safeWriteJson(currentLink, { id: "task-1" }) + + // The lock key is the referent's key, and recovery looked beside the referent as well, + // so the interrupted publish's committed state was restored before this write decided + // what the file holds. Named at the dangling alias, this write queued on the referent's + // lock and healed the referent's leftovers instead of failing every retry. + expect(mockedAcquireFileLock).toHaveBeenCalledWith(referent) + expect(JSON.parse(await fs.readFile(referent, "utf8"))).toEqual({ id: "task-1" }) + expect(await fs.readdir(referentDir)).toEqual(["history_item.json"]) + expect(await fs.readdir(linkDir)).toEqual([]) + }) +}) diff --git a/src/utils/__tests__/safeWriteJson.postCommitDurability.spec.ts b/src/utils/__tests__/safeWriteJson.postCommitDurability.spec.ts new file mode 100644 index 0000000000..32cfb31eb2 --- /dev/null +++ b/src/utils/__tests__/safeWriteJson.postCommitDurability.spec.ts @@ -0,0 +1,186 @@ +// npx vitest run utils/__tests__/safeWriteJson.postCommitDurability.spec.ts + +import * as fsSync from "fs" +import type { WriteStream as FsWriteStream } from "fs" +import * as os from "os" +import path from "path" + +import * as fs from "fs/promises" + +import { safeWriteJson } from "../safeWriteJson" + +// Real filesystem throughout: what this spec has to prove is what the target's directory +// actually holds after a durability failure, and a fully mocked fs cannot show that. +// Only the sync primitives this module reaches for are wrapped - openSync for the +// post-commit directory fsync and createWriteStream for the staged write - and each +// wrapper delegates to the real implementation for every path except the one a test +// deliberately fails. The real implementations are captured inside the mock factory, +// before any vi.fn() wrapper exists, so a test's implementation callback can delegate +// without recursing into itself. +type OpenSyncRest = (...args: unknown[]) => number +// The options type carries the fs option as well: the staged write below fails at its own +// open by handing Node's WriteStream an fs whose open never succeeds. +// The hooks Node's WriteStream calls on a caller-supplied fs object, spelled out in the +// callback form Node itself uses. They are not named out of @types/node: this tree's +// TypeScript reports TS2694 for both CreateWriteStreamFSImplementation and the +// WriteStreamOptions type that carries it under the "fs" spelling, and the +// promise-flavoured typeof of an fs function carries a __promisify__ member a plain stand-in +// does not have (TS2741), so the bag is written from the call shapes instead. +type WriteStreamFsHooks = { + fs?: { + open?: ( + path: string | Buffer | URL, + flags: string, + mode: number | null | undefined, + callback: (err: Error | null, fd: number) => void, + ) => void + close?: (fd: number, callback: (err?: Error | null) => void) => void + write: ( + fd: number, + buffer: Uint8Array | string, + offset: number | null | undefined, + length: number, + position: number | null | undefined, + callback: (err: Error | null, bytesWritten: number) => void, + ) => void + } | null +} +type WriteStreamRest = (filePath: string, options: { encoding: string } & WriteStreamFsHooks) => FsWriteStream +const actuals = vi.hoisted( + (): { + openSync: OpenSyncRest | null + writeStream: WriteStreamRest | null + } => ({ openSync: null, writeStream: null }), +) + +vi.mock("fs", async () => { + const actual = await vi.importActual("fs") + // Node declares both functions as sets of overloads; capturing each as a rest-args or + // narrowed function is what lets this spec forward the arguments unchanged instead of + // re-declaring them. + actuals.openSync = actual.openSync as OpenSyncRest + actuals.writeStream = actual.createWriteStream as unknown as WriteStreamRest + return { + ...actual, + openSync: vi.fn(actual.openSync), + createWriteStream: vi.fn(actual.createWriteStream as unknown as WriteStreamRest), + } +}) + +// The advisory lock is not under test here; the real proper-lockfile would add a lock +// directory to the very directory this spec inspects for residue. +vi.mock("../fileLock", () => ({ + acquireFileLock: vi.fn(async () => async () => {}), +})) + +describe("safeWriteJson post-commit durability", () => { + let dir: string + // safeWriteJson derives the directory it fsyncs from the RESOLVED target, so the + // injected failure has to be keyed to the same spelling realpath reports. + let dirKey: string + let targetPath: string + let originalPlatform: NodeJS.Platform + + beforeEach(async () => { + originalPlatform = process.platform + // The parent-directory fsync (_flushDirectoryToDisk) is POSIX-only: Windows cannot + // open a directory for this purpose, so the branch is only reachable when the + // process reports a POSIX platform. + Object.defineProperty(process, "platform", { value: "linux", configurable: true }) + + dir = await fs.mkdtemp(path.join(os.tmpdir(), "safe-write-json-postcommit-")) + dirKey = await fs.realpath(dir) + targetPath = path.join(dirKey, "history_item.json") + await fs.writeFile(targetPath, JSON.stringify({ version: "old" })) + }) + + afterEach(async () => { + Object.defineProperty(process, "platform", { value: originalPlatform, configurable: true }) + vi.restoreAllMocks() + await fs.rm(dir, { recursive: true, force: true }) + }) + + it("releases every staging artifact when the post-commit directory fsync fails, and reports the write as committed", async () => { + // The commit rename already published the new JSON; only the durability of the + // directory entry that records the rename is in doubt. This module owns that fsync, + // and it swallows the failure rather than reporting a completed write as a failed + // one: the content is at the target either way, so a rejection would leave in-memory + // state diverging from disk. The staging file (and the backup copy, when the write + // took one) is still removed - leaving them behind would mean every affected write + // leaks another hidden copy next to the target. + let dirOpenAttempted = false + const openSyncActual = actuals.openSync + if (openSyncActual === null) { + throw new Error("fs mock did not capture the real openSync") + } + vi.mocked(fsSync.openSync).mockImplementation((...args: Parameters) => { + if (String(args[0]) === dirKey) { + // Pin the injection: without this flag the test would also pass on a run where + // the directory sync never fired at all, which proves nothing about the path + // that the failure handler takes. + dirOpenAttempted = true + throw Object.assign(new Error("EINVAL: invalid argument, open '" + dirKey + "'"), { code: "EINVAL" }) + } + return openSyncActual(...args) + }) + const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}) + const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + + await safeWriteJson(targetPath, { version: "new" }) + + expect(dirOpenAttempted).toBe(true) + expect(JSON.parse(await fs.readFile(targetPath, "utf8"))).toEqual({ version: "new" }) + // The swallowed error is still reported to the log: the directory entry is not known + // to be durable, and a caller that cannot see that would over-claim the write. + expect(warnSpy).toHaveBeenCalledTimes(1) + expect(errorSpy).not.toHaveBeenCalled() + // No backup copy, no staging temp, no staging directory: only the published file. + expect(await fs.readdir(dir)).toEqual(["history_item.json"]) + }) + + it("still rejects a failure before the commit rename, and leaves no residue", async () => { + // The post-commit leniency must stay narrow: a failure that happens before the commit + // has not published anything, and swallowing it would report a write that never ran. + // This module writes the staged file through a stream, so the pre-commit failure is + // injected on that stream. + let stagedOpenAttempted = false + const writeStreamActual = actuals.writeStream + if (writeStreamActual === null) { + throw new Error("fs mock did not capture the real createWriteStream") + } + // The open that never succeeds, in the callback form Node's WriteStream calls it in. + const failOpen = (...args: unknown[]): void => { + const callback = args.at(-1) + if (typeof callback === "function") { + process.nextTick(() => + callback(Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" })), + ) + } + } + vi.mocked(fsSync.createWriteStream).mockImplementation( + (...args: Parameters) => { + const stagedPath = String(args[0]) + if (stagedPath.includes(".new_")) { + // Pin the injection: without this flag the test would also pass on a run where + // the write never reached a staged file at all. + stagedOpenAttempted = true + // Fail the staged file at its open rather than emitting a synthetic error after a + // successful one. A real open creates the name before anything can fail, so the + // residue assertion below would then depend on when the cleanup happened to run; + // an open that never succeeds means the name is never created at all. + return writeStreamActual(stagedPath, { encoding: "utf8", fs: { ...fsSync, open: failOpen } }) + } + return writeStreamActual(stagedPath, { encoding: "utf8" }) + }, + ) + + await expect(safeWriteJson(targetPath, { version: "new" })).rejects.toThrow("EACCES: permission denied") + + expect(stagedOpenAttempted).toBe(true) + // Nothing was published and nothing was staged: the target still holds the previous + // content, and the staged file's name never came into existence because its open is + // what failed. + expect(JSON.parse(await fs.readFile(targetPath, "utf8"))).toEqual({ version: "old" }) + expect(await fs.readdir(dir)).toEqual(["history_item.json"]) + }) +}) diff --git a/src/utils/__tests__/safeWriteJson.scopeCanonicalization.spec.ts b/src/utils/__tests__/safeWriteJson.scopeCanonicalization.spec.ts new file mode 100644 index 0000000000..78653b39b8 --- /dev/null +++ b/src/utils/__tests__/safeWriteJson.scopeCanonicalization.spec.ts @@ -0,0 +1,106 @@ +// A scope that cannot be canonicalized has to fail the publish with the filesystem answer it +// got. The walk-up to the nearest existing ancestor exists for a scope that is MISSING; applying +// it to any other failure would build a partly lexical scope root and confine the write to a +// directory nobody named. The failure is chosen by an error code, and the codes that make a +// directory unreadable (EACCES on a locked volume, ELOOP on a link cycle) are not reproducible +// portably, so realpath is doubled here and the assertions name which failure the publish +// reports and which path it names. + +import * as os from "os" +import * as path from "path" +import * as fsSync from "fs" +import * as fs from "fs/promises" +import { ConfinedPathEscapeError, safeWriteJson } from "../safeWriteJson" + +vi.mock("fs/promises", async () => { + const actual = await vi.importActual("fs/promises") + return { ...actual, realpath: vi.fn() } +}) + +const mockedRealpath = vi.mocked(fs.realpath) + +const createdDirs: string[] = [] +async function makeDir(prefix: string): Promise { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), prefix)) + createdDirs.push(dir) + return dir +} + +function failureOf(error: unknown): { code: string; path: string } | undefined { + if (typeof error !== "object" || error === null) { + return undefined + } + const code = "code" in error ? error.code : undefined + const failedPath = "path" in error ? error.path : undefined + if (typeof code === "string" && typeof failedPath === "string") { + return { code, path: failedPath } + } + return undefined +} + +function fsFailure(code: string, failedPath: string): Error { + return Object.assign(new Error(`${code}: cannot canonicalize ${failedPath}`), { code, path: failedPath }) +} + +beforeEach(() => { + mockedRealpath.mockReset() +}) + +afterEach(async () => { + for (const dir of createdDirs) { + await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined) + } + createdDirs.length = 0 +}) + +describe("safeWriteJson confineTo scope canonicalization", () => { + it("surfaces an unreadable scope as itself instead of adopting the parent as the scope", async () => { + const scope = await makeDir("zdt-scope-eacces-") + const target = path.join(scope, "mcp.json") + mockedRealpath.mockImplementation(async (candidate) => { + const resolved = path.resolve(String(candidate)) + throw fsFailure("EACCES", resolved) + }) + + const outcome = await safeWriteJson(target, { mcpServers: {} }, { confineTo: scope }).then( + () => undefined, + (reason: unknown) => reason, + ) + + const failure = failureOf(outcome) + // The scope is measured first, and the measurement has to be the one reported: a walk-up on a + // permission failure would name the parent, and the caller would believe a different + // directory had been declared as the scope. + expect(failure?.code).toBe("EACCES") + expect(failure?.path).toBe(scope) + expect(mockedRealpath).toHaveBeenCalledTimes(1) + expect(mockedRealpath).toHaveBeenCalledWith(scope) + expect(outcome).not.toBeInstanceOf(ConfinedPathEscapeError) + // Nothing was written: the refusal happens before any filesystem side effect. + expect(await fs.readdir(scope)).toEqual([]) + }) + + it("still walks a missing scope up to its nearest existing ancestor and writes", async () => { + const parent = await makeDir("zdt-scope-missing-") + const scope = path.join(parent, "zz-not-created-yet") + const target = path.join(scope, "mcp.json") + // Doubled the way the real call behaves: a path that is not on disk rejects with ENOENT, + // a path that is on disk resolves to itself because this fixture uses no links. The scope is + // absent when the confinement check runs and present once the publish makes it, so the walk + // up and the after-the-fact re-verification see the same filesystem the real call would give. + mockedRealpath.mockImplementation(async (candidate) => { + const resolved = path.resolve(String(candidate)) + if (fsSync.existsSync(String(candidate))) { + return resolved + } + throw fsFailure("ENOENT", resolved) + }) + + await safeWriteJson(target, { mcpServers: { a: {} } }, { confineTo: scope }) + + // The ENOENT branch is the only one allowed to walk: the scope below an existing parent is + // re-joined onto the canonicalized parent and the write lands inside it. + expect(JSON.parse(String(await fs.readFile(target, "utf8")))).toEqual({ mcpServers: { a: {} } }) + expect(mockedRealpath).toHaveBeenCalledWith(scope) + }) +}) diff --git a/src/utils/__tests__/safeWriteJson.test.ts b/src/utils/__tests__/safeWriteJson.test.ts index 30ac500212..9fc3f49280 100644 --- a/src/utils/__tests__/safeWriteJson.test.ts +++ b/src/utils/__tests__/safeWriteJson.test.ts @@ -3,7 +3,9 @@ import { Writable } from "stream" import * as path from "path" import * as os from "os" -import { safeWriteJson } from "../safeWriteJson" +import { AncestorReplacedError, TargetMovedError } from "../../services/file-safety/safeWritePrimitives" +import { ConfinedPathEscapeError, safeWriteJson } from "../safeWriteJson" +import * as fileLockModule from "../fileLock" // Capture actual implementations before the vi.mock factory runs, // so they are never wrapped by vi.fn() — avoids infinite recursion when @@ -81,8 +83,17 @@ describe("safeWriteJson", () => { let currentTestFilePath: string beforeEach(async () => { - // Create a temporary directory for each test - tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "safeWriteJson-test-")) + // Create a temporary directory for each test, in the spelling the writer itself uses. + // safeWriteJson works on a path that fs.realpath returned (the lock key, and now the + // recovery scan keyed to it, are realpath results), and every path-keyed double in this + // file compares against strings derived from tempDir. On the windows CI runner os.tmpdir() + // reports the profile directory in its 8.3 form - C:\Users\RUNNER~1\AppData\Local\Temp - + // while fs.realpath reports C:\Users\runneradmin\AppData\Local\Temp for the same + // directory, and six rows here (three of them pre-existing) failed on that runner for + // nothing but the spelling: the doubles that inject a failure at a named path never saw + // that path, and the fsync row never saw the directory handle it opened. Canonicalising + // the fixture root makes the fixture's paths and the product's paths one string. + tempDir = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "safeWriteJson-test-"))) // Create a unique file path for each test currentTestFilePath = path.join(tempDir, "test-file.json") @@ -106,6 +117,37 @@ describe("safeWriteJson", () => { return JSON.parse(readContent) } + // The ancestor-swap tests below drive the swap from the merge callback, which + // safeWriteJson invokes after the in-lock confinement check and before anything is + // staged, so the ancestor moves inside the window rather than hopefully so. + // A directory link needs no privilege on win32 as a junction; "dir" is the POSIX + // spelling. Both make the ancestor itself the link, which is the shape under test. + const ancestorLinkKind = process.platform === "win32" ? ("junction" as const) : ("dir" as const) + + function swapAncestorAfterTheCheck(ancestor: string, pointsAt: string): void { + fsSyncActual.renameSync(ancestor, ancestor + "-moved-aside") + fsSyncActual.symlinkSync(pointsAt, ancestor, ancestorLinkKind) + } + + function removeAncestorLink(ancestor: string): void { + // The undo of the link above, and the two platforms remove it differently. Measured on + // this box (node 22.23.4, win32): lstatSync reports a junction as a symbolic link, and + // unlinkSync does remove the junction while leaving the target directory's contents + // alone - but while another handle is still open on that directory the unlink only marks + // the name for deletion, and the rename that puts the directory back then answers + // "EPERM: operation not permitted", which is what this row reported after switching to + // unlink. rmdir takes a junction cleanly. On POSIX the entry is a real directory symlink + // and rmdir will not take it: the ubuntu coverage lane answered + // "ENOTDIR: not a directory, rmdir '.../midwrite-swap-project/settings'" for this + // restoration, so unlink is the removal there. The branch follows the same platform fact + // the link was created with, rather than pretending one call serves both shapes. + if (process.platform === "win32") { + fsSyncActual.rmdirSync(ancestor) + } else { + fsSyncActual.unlinkSync(ancestor) + } + } + // Helper function to check if a file exists async function fileExists(filePath: string): Promise { try { @@ -818,4 +860,1078 @@ describe("safeWriteJson", () => { const content = await readFileContent(currentTestFilePath) expect(content).toEqual(newData) }) + + // Four variants the chain carried against its own write mechanism are not ported here, + // because the mechanism they describe is not the one this module ships: + // - "a failed commit keeps the previous content at the target and removes the backup + // copy" pinned a single-rename flow (renameCallCount === 1) and a + // "safeWriteText.bak_" backup name; this protocol backs up with a rename of the + // target and its own ".bak_" spelling, and main's + // "should keep the committed file when the commit rename fails with a non-EPERM + // error" already asserts the surviving behaviour - previous content at the target, + // staging artifacts removed - against that mechanism. + // - the chain's re-titling of main's rename-failure tests ("... backup copy taken", + // "the commit rename fails (filePath exists)") is a naming change over a different + // rename sequence; main's versions are kept verbatim. + // - the fsync variant below keeps the regression it guards (published content intact, + // consumed staging path untouched) but asserts the contract this protocol has: + // report and continue, not reject. + + test("stages the temp file beside the symlink referent and commits onto it", async () => { + const referentDir = path.join(tempDir, "referent") + const linkDir = path.join(tempDir, "link") + await fs.mkdir(referentDir, { recursive: true }) + await fs.mkdir(linkDir, { recursive: true }) + // caller-visible path (the link) vs the resolved referent path + const callerPath = path.join(linkDir, "test-file.json") + const referentPath = path.join(referentDir, "test-file.json") + // Seed the RESOLVED referent with real content (via the actual fs) so the + // write exercises replacement of an EXISTING referent: the lock, the + // backup, and the commit all target the resolved referent. + await fsPromisesActuals.writeFile!(referentPath, JSON.stringify({ seed: true })) + + // Only the file resolves through the link; the directory is already canonical, + // so the lock key is the referent rather than the alias directory + basename. + vi.spyOn(fs, "realpath").mockImplementation(async (target) => + target === callerPath ? referentPath : String(target), + ) + + await safeWriteJson(callerPath, { after: true }) + + // the temp file was created next to the resolved referent, NOT beside the link + const tempPaths = vi.mocked(fsSyncActual.createWriteStream).mock.calls.map((call) => String(call[0])) + expect(tempPaths.some((p) => p.startsWith(referentDir + path.sep) && p.includes(".new_"))).toBe(true) + expect(tempPaths.some((p) => p.startsWith(linkDir + path.sep))).toBe(false) + + // the content was committed onto the referent + expect(await readFileContent(referentPath)).toEqual({ after: true }) + }) + test("acquires the lock on the resolved referent, not the caller alias", async () => { + vi.resetModules() // fresh module instances so the doMock below is picked up + + const referentDir = path.join(tempDir, "lock-referent") + const linkDir = path.join(tempDir, "lock-link") + await fs.mkdir(referentDir, { recursive: true }) + await fs.mkdir(linkDir, { recursive: true }) + // caller-visible path (the link) vs the resolved referent path + const callerPath = path.join(linkDir, "locked.json") + const referentPath = path.join(referentDir, "locked.json") + await fsPromisesActuals.writeFile!(referentPath, JSON.stringify({ seed: 1 })) + + // Only the file resolves through the link; the directory is already canonical, + // so the lock key is the referent rather than the alias directory + basename. + const realpathSpy = vi + .spyOn(fs, "realpath") + .mockImplementation(async (target) => (target === callerPath ? referentPath : String(target))) + + // Wrap the real lock in a capturing mock, and drive the two rare error paths + // (the onCompromised callback and a failing release) so they stay covered + // without real lockfile staleness. The callback rethrows by design, so + // the mock swallows that throw and lets the real lock proceed. + const realLockfile = await vi.importActual("proper-lockfile") + const lockMockFn = vi.fn( + async ( + file: Parameters[0], + options?: Parameters[1], + ) => { + try { + options?.onCompromised?.(new Error("lock compromised (test)")) + } catch { + // onCompromised rethrows by design; swallow so the real lock proceeds. + } + const release = await realLockfile.lock(file, options) + return async () => { + await release() + throw new Error("release failed (test)") + } + }, + ) + const lockMock = lockMockFn as unknown as typeof realLockfile.lock + vi.doMock("proper-lockfile", () => ({ + ...realLockfile, + lock: lockMock, + })) + + // Re-import safeWriteJson so it picks up the mocked proper-lockfile. + const { safeWriteJson: mockedSafeWriteJson } = await import("../safeWriteJson") + + const mergeFn = vi.fn((existing: unknown, incoming: unknown) => ({ + ...(existing as Record), + ...(incoming as Record), + })) + + // Capture the compromise + release-failure logs. + const consoleErrorSpy = vi.spyOn(console, "error") + try { + await mockedSafeWriteJson(callerPath, { added: true }, { merge: mergeFn }) + + // The lock was keyed by the resolved referent — every alias shares it. + expect(lockMock).toHaveBeenCalledTimes(1) + expect(String(lockMockFn.mock.calls[0][0])).toBe(referentPath) + // The merge read the referent's content through that single lock. + expect(mergeFn).toHaveBeenCalledWith({ seed: 1 }, { added: true }) + expect(await readFileContent(referentPath)).toEqual({ seed: 1, added: true }) + // The compromise callback and the failed release were logged, not thrown. + expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining("was compromised"), expect.any(Error)) + expect(consoleErrorSpy).toHaveBeenCalledWith( + expect.stringContaining("Failed to release lock"), + expect.any(Error), + ) + } finally { + // Cleanup must run even when an assertion fails: a leaked mock + // registration or console spy changes later tests, and vi.unmock + // alone does not reset a module that already imported the mock. + realpathSpy.mockRestore() + vi.unmock("proper-lockfile") + vi.resetModules() + consoleErrorSpy.mockRestore() + } + }) + test("rejects a confined write whose target is outside the confined directory", async () => { + const scope = path.join(tempDir, "project") + await fs.mkdir(scope) + const outside = path.join(tempDir, "elsewhere.json") + + // No symlink needed: the check runs on the resolved publish target, so an + // out-of-scope path is rejected on every platform, and it is rejected before the + // lock is taken and before anything is staged. + await expect(safeWriteJson(outside, { mcpServers: {} }, { confineTo: scope })).rejects.toThrow( + ConfinedPathEscapeError, + ) + + const left = await fs.readdir(tempDir) + expect(left).not.toContain("elsewhere.json") + expect(left.filter((entry) => entry.includes(".new_") || entry.endsWith(".lock"))).toEqual([]) + }) + test("rejects an out-of-scope target before the advisory lock is taken", async () => { + vi.resetModules() + const projectDir = path.join(tempDir, "order-project-plain") + await fs.mkdir(projectDir) + const outside = path.join(tempDir, "order-outside-plain.json") + + const realLockfile = await vi.importActual("proper-lockfile") + const lockMockFn = vi.fn(async () => { + throw new Error("lock taken for an out-of-scope target (test)") + }) + vi.doMock("proper-lockfile", () => ({ ...realLockfile, lock: lockMockFn })) + const { safeWriteJson: lockedSafeWriteJson } = await import("../safeWriteJson") + + try { + await expect(lockedSafeWriteJson(outside, { mcpServers: {} }, { confineTo: projectDir })).rejects.toThrow( + /resolves outside the confined directory/, + ) + expect(lockMockFn).not.toHaveBeenCalled() + const entries = await fs.readdir(tempDir) + expect(entries.filter((entry) => entry.endsWith(".lock") || entry.includes(".new_"))).toEqual([]) + } finally { + vi.doUnmock("proper-lockfile") + vi.resetModules() + } + }) + test("fails closed when the confined scope cannot be canonicalized", async () => { + const scope = path.join(tempDir, "project") + await fs.mkdir(scope) + const target = path.join(scope, "mcp.json") + const merge = vi.fn() + // Only ENOENT means "walk up and re-join". EACCES means the scope root is unknown, + // and continuing with a partly lexical root would let the confinement check compare + // against a scope that may disagree with the canonical target. + const failure = Object.assign(new Error("EACCES"), { code: "EACCES" }) + const realpathSpy = vi.spyOn(fs, "realpath").mockImplementation(async () => { + throw failure + }) + try { + await expect(safeWriteJson(target, { mcpServers: {} }, { confineTo: scope, merge })).rejects.toThrow( + "EACCES", + ) + } finally { + realpathSpy.mockRestore() + } + + // Nothing was merged, staged, locked or published. + expect(merge).not.toHaveBeenCalled() + expect(await fs.readdir(scope)).toEqual([]) + const root = await fs.readdir(tempDir) + expect(root.filter((entry) => entry.includes(".new_") || entry.endsWith(".lock"))).toEqual([]) + }) + test("fails closed when a missing scope cannot be resolved through its ancestors", async () => { + const scope = path.join(tempDir, "missing", "nested") + const target = path.join(tempDir, "mcp.json") + const merge = vi.fn() + // The scope itself is missing, so the resolver walks up. The ancestor lookup then + // fails for a non-ENOENT reason (a symlink loop), which is not a "missing path" signal: + // the write has to fail rather than fall back to the lexical scope. + const realpathSpy = vi.spyOn(fs, "realpath").mockImplementation(async (candidate) => { + if (String(candidate).includes("missing")) { + throw Object.assign(new Error("ENOENT"), { code: "ENOENT" }) + } + throw Object.assign(new Error("ELOOP"), { code: "ELOOP" }) + }) + try { + await expect(safeWriteJson(target, { mcpServers: {} }, { confineTo: scope, merge })).rejects.toThrow( + "ELOOP", + ) + } finally { + realpathSpy.mockRestore() + } + + expect(merge).not.toHaveBeenCalled() + const root = await fs.readdir(tempDir) + expect(root.filter((entry) => entry.includes(".new_") || entry.endsWith(".lock"))).toEqual([]) + expect(root).not.toContain("mcp.json") + }) + test("does not create the parent directory of an out-of-scope confined target", async () => { + const projectDir = path.join(tempDir, "scope-dir-project") + await fs.mkdir(projectDir) + // The parent does not exist yet: the mkdir in safeWriteJson would create it - + // a filesystem change outside confineTo - before the confinement check rejected + // the write. + const outside = path.join(tempDir, "scope-missing-parent", "nested.json") + + await expect(safeWriteJson(outside, { mcpServers: {} }, { confineTo: projectDir })).rejects.toThrow( + /resolves outside the confined directory/, + ) + + const entries = await fs.readdir(tempDir) + expect(entries).not.toContain("scope-missing-parent") + expect(entries.filter((entry) => entry.endsWith(".lock") || entry.includes(".new_"))).toEqual([]) + }) + test("re-checks confinement after the lock when a peer moves the referent out of scope", async () => { + const projectDir = path.join(tempDir, "race-project") + await fs.mkdir(projectDir) + const target = path.join(projectDir, "mcp.json") + await fsPromisesActuals.writeFile!(target, JSON.stringify({ mcpServers: {} }), "utf8") + const outsideDir = path.join(tempDir, "race-outside") + await fs.mkdir(outsideDir) + const merge = vi.fn() + // The pre-lock check canonicalizes the lock key and sees the file inside the scope. + // A peer writer then moves it out, so every lookup made after the advisory lock is + // held - the publish-target resolution and the in-lock re-check - sees the referent + // elsewhere. A confinement check that ran only before the lock would publish onto the + // moved file outside the scope. + const movedTarget = path.join(outsideDir, "mcp.json") + // The move is tied to the lock rather than to a call count: everything the pre-lock + // canonicalization sees is still inside the scope, and everything resolved while the + // lock is held - the publish target and the in-lock re-check - sees it elsewhere. + let lockHeld = false + // Captured before the spy is installed: calling the namespace property from inside the + // implementation would recurse through the spy itself. + const realAcquire = fileLockModule.acquireFileLock + const lockSpy = vi.spyOn(fileLockModule, "acquireFileLock").mockImplementation(async (key: string) => { + const release = await realAcquire(key) + lockHeld = true + return release + }) + const realpathSpy = vi.spyOn(fs, "realpath").mockImplementation(async (candidate) => { + const p = String(candidate) + if (p === target) { + return lockHeld ? movedTarget : target + } + return p + }) + let captured: unknown = null + try { + await safeWriteJson(target, { mcpServers: {} }, { confineTo: projectDir, merge }) + } catch (error: unknown) { + captured = error + } finally { + realpathSpy.mockRestore() + lockSpy.mockRestore() + } + + expect(captured).toBeInstanceOf(ConfinedPathEscapeError) + // The rejection came from the check inside the protected block, not from the + // pre-lock one: the advisory lock had already been taken. (mockRestore in the + // finally clears the spy's call history, so the flag carries the evidence.) + expect(lockHeld).toBe(true) + // The rejection happens before the merge read and before anything is staged, and the + // advisory lock is released rather than left to the stale timeout. + expect(merge).not.toHaveBeenCalled() + expect(await fs.readdir(projectDir)).toEqual(["mcp.json"]) + expect(await fs.readdir(outsideDir)).toEqual([]) + const root = await fs.readdir(tempDir) + expect(root.filter((entry) => entry.includes(".new_") || entry.endsWith(".lock"))).toEqual([]) + }) + test("refuses the write when an ancestor is swapped for a link before staging, after the merge read", async () => { + const projectDir = path.join(tempDir, "swap-project") + const ancestor = path.join(projectDir, "settings") + await fs.mkdir(ancestor, { recursive: true }) + // The target does not exist yet, so the publish has to be stopped by the ancestor pin: + // nothing about the target NAME changes, and a create into the swapped-in directory + // would land outside the declared scope. + const target = path.join(ancestor, "mcp.json") + const swappedIn = path.join(tempDir, "elsewhere", "settings") + await fs.mkdir(swappedIn, { recursive: true }) + + const error = await safeWriteJson( + target, + { written: "payload" }, + { + confineTo: projectDir, + merge: () => { + swapAncestorAfterTheCheck(ancestor, swappedIn) + return { written: "payload" } + }, + }, + ).then( + () => undefined, + (reason: unknown) => reason, + ) + + // Fail closed on the swapped ancestor, not on the target path: the name still resolves + // to itself, only the directory it lives in was replaced. + expect(error).toBeInstanceOf(AncestorReplacedError) + expect(error).not.toBeInstanceOf(ConfinedPathEscapeError) + expect(path.basename((error as AncestorReplacedError).directory)).toBe("settings") + expect((error as AncestorReplacedError).message).toContain("nothing was published") + // Nothing landed outside the declared scope. The staged temp file is created through + // the swapped ancestor (staging is path based), and the failure cleanup removes it + // instead of leaving it beside the swapped-in directory. + expect(await fs.readdir(swappedIn)).toEqual([]) + // Nothing landed through the moved-aside name either. (The advisory lock directory is + // created under the pre-swap name by proper-lockfile; when the ancestor moves aside + // the release targets the path, which now resolves through the link, so that empty + // lock directory can be left in the moved-aside copy. It holds no published content.) + expect((await fs.readdir(ancestor + "-moved-aside")).filter((entry) => entry === "mcp.json")).toEqual([]) + // The scope was declared and active in this very fixture: with the ancestor left + // alone, the same option refuses an out-of-scope target. Without this contrast the + // rejection above would also be the outcome of a confinement check that never ran. + await expect( + safeWriteJson(path.join(tempDir, "elsewhere", "other.json"), { other: true }, { confineTo: projectDir }), + ).rejects.toThrow(ConfinedPathEscapeError) + }) + test("fails the publish when an existing target now resolves through a swapped ancestor", async () => { + const projectDir = path.join(tempDir, "swap-project-clash") + const ancestor = path.join(projectDir, "settings") + await fs.mkdir(ancestor, { recursive: true }) + const target = path.join(ancestor, "mcp.json") + await fs.writeFile(target, JSON.stringify({ inside: true })) + const swappedIn = path.join(tempDir, "elsewhere-clash", "settings") + await fs.mkdir(swappedIn, { recursive: true }) + await fs.writeFile(path.join(swappedIn, "mcp.json"), JSON.stringify({ outside: true })) + + const error = await safeWriteJson( + target, + { written: "payload" }, + { + confineTo: projectDir, + merge: () => { + swapAncestorAfterTheCheck(ancestor, swappedIn) + return { written: "payload" } + }, + }, + ).then( + () => undefined, + (reason: unknown) => reason, + ) + + // An existing target makes the swap visible in the resolved name itself, so the + // publish stops at the target pin before anything is staged. + expect(error).toBeInstanceOf(TargetMovedError) + expect(error).not.toBeInstanceOf(ConfinedPathEscapeError) + // Nothing was written on either side of the swap. + expect(JSON.parse(fsSyncActual.readFileSync(path.join(swappedIn, "mcp.json"), "utf8"))).toEqual({ + outside: true, + }) + expect(JSON.parse(fsSyncActual.readFileSync(path.join(ancestor + "-moved-aside", "mcp.json"), "utf8"))).toEqual( + { inside: true }, + ) + }) + test("publishes a confined write through a pinned ancestor chain and releases the lock", async () => { + const projectDir = path.join(tempDir, "pinned-project") + const nested = path.join(projectDir, "settings") + await fs.mkdir(nested, { recursive: true }) + const target = path.join(nested, "mcp.json") + + // The pins must not reject a directory chain that did not move: the write publishes + // and every artifact of it (lock, staged temp, staging directory) is gone afterwards. + await safeWriteJson(target, { mcpServers: {} }, { confineTo: projectDir }) + + expect(JSON.parse(fsSyncActual.readFileSync(target, "utf8"))).toEqual({ mcpServers: {} }) + expect(await fs.readdir(nested)).toEqual(["mcp.json"]) + expect(await fs.readdir(projectDir)).toEqual(["settings"]) + }) + + test("refuses the commit when an ancestor is swapped while the staged write is in flight", async () => { + const projectDir = path.join(tempDir, "midwrite-swap-project") + const ancestor = path.join(projectDir, "settings") + await fs.mkdir(ancestor, { recursive: true }) + const target = path.join(ancestor, "mcp.json") + const swappedIn = path.join(tempDir, "midwrite-elsewhere", "settings") + await fs.mkdir(swappedIn, { recursive: true }) + // The verification that runs before staging already passed by the time this hook + // fires: trace reports write-start at the point where the staged file is about to be + // written, so the ancestor moves inside the publish rather than hopefully so. The + // commit rename is the statement that acts on the confinement decision, and it names + // the path this write resolved before the swap. + let swapped = false + const error = await safeWriteJson( + target, + { written: "payload" }, + { + confineTo: projectDir, + trace: (event) => { + if (event.stage !== "write-start" || swapped) return + swapped = true + swapAncestorAfterTheCheck(ancestor, swappedIn) + }, + }, + ).then( + () => undefined, + (reason: unknown) => reason, + ) + + expect(error).toBeInstanceOf(AncestorReplacedError) + expect(path.basename((error as AncestorReplacedError).directory)).toBe("settings") + expect((error as AncestorReplacedError).message).toContain("nothing was published") + // Nothing published into the swapped-in directory - not the target, and not the staged + // file the swap had already redirected: the failure cleanup names the staged file + // through the same path, which now resolves into the swapped-in copy. + expect(await fs.readdir(swappedIn)).toEqual([]) + expect((await fs.readdir(ancestor + "-moved-aside")).filter((entry) => entry === "mcp.json")).toEqual([]) + + // Contrast in the same fixture: put the directory back and the same write publishes. + // Without this, the rejection above would also be the outcome of a publish that never + // reached the rename. The name currently holds the link swapAncestorAfterTheCheck put + // there - a junction on win32, a directory symlink on POSIX, where the helper calls the + // same kind "dir" - and removeAncestorLink undoes it the way this platform removes that + // shape. rmdirSync alone was wrong: the ubuntu coverage lane reported "ENOTDIR: not a + // directory, rmdir '.../midwrite-swap-project/settings'". + removeAncestorLink(ancestor) + fsSyncActual.renameSync(ancestor + "-moved-aside", ancestor) + // The failed write's lock release named the path, which at release time resolved through + // the link, so the empty lock directory stayed in the moved-aside copy and came back with + // the directory (the row above documents the same effect). Sweep it so the contrast write + // is not queued behind a lock nobody holds. + for (const entry of fsSyncActual.readdirSync(ancestor)) { + if (entry.includes(".lock")) { + fsSyncActual.rmSync(path.join(ancestor, entry), { recursive: true, force: true }) + } + } + await safeWriteJson(target, { written: "payload" }, { confineTo: projectDir }) + expect(JSON.parse(fsSyncActual.readFileSync(target, "utf8"))).toEqual({ written: "payload" }) + }) + test("refuses the commit when a moved ancestor's old name is replaced by a link back to it", async () => { + const projectDir = path.join(tempDir, "moved-back-project") + const ancestor = path.join(projectDir, "settings") + await fs.mkdir(ancestor, { recursive: true }) + const target = path.join(ancestor, "mcp.json") + // A directory rename preserves the inode, and a link placed at the old name points at + // the moved directory, so a stat through the old name reports the SAME dev+ino the pin + // recorded and the identity comparison passes. The publish takes path strings, so it + // follows that link to wherever the directory went: what has to stop it is the + // requirement that the authorized name still resolve to where it was walked. + let swapped = false + const error = await safeWriteJson( + target, + { written: "payload" }, + { + confineTo: projectDir, + trace: (event) => { + if (event.stage !== "write-start" || swapped) return + swapped = true + fsSyncActual.renameSync(ancestor, ancestor + "-moved-aside") + fsSyncActual.symlinkSync(ancestor + "-moved-aside", ancestor, ancestorLinkKind) + }, + }, + ).then( + () => undefined, + (reason: unknown) => reason, + ) + + expect(error).toBeInstanceOf(AncestorReplacedError) + expect(path.basename((error as AncestorReplacedError).directory)).toBe("settings") + // The reason names the resolution rather than the identity, because the identity + // comparison passed: this is the same directory, no longer at the location the + // confinement check walked. + expect((error as AncestorReplacedError).message).toContain("no longer resolves to the location") + expect((await fs.readdir(ancestor + "-moved-aside")).filter((entry) => entry === "mcp.json")).toEqual([]) + }) + test("propagates a transient ancestor lookup failure instead of reporting a replaced ancestor", async () => { + const projectDir = path.join(tempDir, "transient-project") + const ancestor = path.join(projectDir, "settings") + await fs.mkdir(ancestor, { recursive: true }) + const target = path.join(ancestor, "mcp.json") + const eacces = Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" }) + // Captured from the real module: the mocked namespace's stat is the property the spy + // replaces, so delegating to it would recurse. + const realStat = (await vi.importActual("fs/promises")).stat + let stagingStarted = false + const statSpy = vi.spyOn(fs, "stat").mockImplementation(async (candidate) => { + const lookedUp = String(candidate) + // Only the pinned directory, and only after the staged write began: the lookup + // that fails here is the re-verification that runs immediately before the commit + // rename. A permission error says nothing about whether the directory was + // replaced, so it must reach the caller unchanged. + if (stagingStarted && path.resolve(lookedUp) === path.resolve(ancestor)) { + throw eacces + } + return realStat(lookedUp) + }) + try { + await expect( + safeWriteJson( + target, + { written: "payload" }, + { + confineTo: projectDir, + trace: (event) => { + if (event.stage === "write-start") stagingStarted = true + }, + }, + ), + ).rejects.toBe(eacces) + } finally { + statSpy.mockRestore() + } + // Nothing published: the write stopped rather than guessing that a directory it could + // not look at had been replaced and reporting that as a containment failure. + expect(await fs.readdir(ancestor)).toEqual([]) + }) + test("reports what the target resolves to now when it no longer resolves to the pinned target", async () => { + const projectDir = path.join(tempDir, "moved-target-project") + const ancestor = path.join(projectDir, "settings") + await fs.mkdir(ancestor, { recursive: true }) + const target = path.join(ancestor, "mcp.json") + await fs.writeFile(target, JSON.stringify({ inside: true }), "utf8") + // The resolution the confinement decision was made against, captured while it is still + // the resolution on disk. + const pinnedResolution = fsSyncActual.realpathSync(target) + const swappedIn = path.join(tempDir, "moved-target-elsewhere", "settings") + await fs.mkdir(swappedIn, { recursive: true }) + await fs.writeFile(path.join(swappedIn, "mcp.json"), JSON.stringify({ outside: true }), "utf8") + + const error = await safeWriteJson( + target, + { written: "payload" }, + { + confineTo: projectDir, + merge: () => { + swapAncestorAfterTheCheck(ancestor, swappedIn) + return { written: "payload" } + }, + }, + ).then( + () => undefined, + (reason: unknown) => reason, + ) + + expect(error).toBeInstanceOf(TargetMovedError) + // The error carries the resolution the write was authorized against and the resolution + // the path has NOW, so the reader can tell which side of the swap each name means + // instead of being shown the authorized path twice. + expect((error as TargetMovedError).authorizedPath).toBe(pinnedResolution) + expect((error as TargetMovedError).resolvedPath).toBe( + fsSyncActual.realpathSync(path.join(swappedIn, "mcp.json")), + ) + expect((error as TargetMovedError).resolvedPath).not.toBe((error as TargetMovedError).authorizedPath) + expect(JSON.parse(fsSyncActual.readFileSync(path.join(swappedIn, "mcp.json"), "utf8"))).toEqual({ + outside: true, + }) + }) + test("holds the confined scope to the directory named before the lock when a peer replaces that name", async () => { + const projectDir = path.join(tempDir, "pinned-scope-project") + await fs.mkdir(projectDir) + const target = path.join(projectDir, "mcp.json") + const arrivedDir = path.join(tempDir, "pinned-scope-arrived") + await fs.mkdir(arrivedDir) + // Captured before the spy is installed: calling the namespace property from inside the + // implementation would recurse through the spy itself. + const realAcquire = fileLockModule.acquireFileLock + // Everything the pre-lock check sees is inside projectDir. While this writer waits for + // the advisory lock, projectDir is moved aside and a link to a different directory is + // left at its name, so every lookup made with the lock held finds the scope somewhere + // else. Re-resolving confineTo there would bless the directory that arrived: the write + // is confined to the directory the caller named. + const lockSpy = vi.spyOn(fileLockModule, "acquireFileLock").mockImplementation(async (key: string) => { + const release = await realAcquire(key) + fsSyncActual.renameSync(projectDir, projectDir + "-moved-aside") + fsSyncActual.symlinkSync(arrivedDir, projectDir, ancestorLinkKind) + return release + }) + let captured: unknown = null + try { + captured = await safeWriteJson(target, { written: "payload" }, { confineTo: projectDir }).then( + () => null, + (reason: unknown) => reason, + ) + } finally { + lockSpy.mockRestore() + } + + expect(captured).toBeInstanceOf(ConfinedPathEscapeError) + // Nothing was published into the directory that arrived at the scope's name. + expect(await fs.readdir(arrivedDir)).toEqual([]) + // Nor into the directory the caller named, which is now behind a link. (The advisory + // lock lives beside the key and moves with the directory; it holds no published content.) + expect((await fs.readdir(projectDir + "-moved-aside")).filter((entry) => !entry.endsWith(".lock"))).toEqual([]) + }) + test("does not recover an interrupted write through an ancestor that was replaced while the lock was waited for", async () => { + const projectDir = path.join(tempDir, "recovery-confined-project") + const ancestor = path.join(projectDir, "settings") + await fs.mkdir(ancestor, { recursive: true }) + const swappedIn = path.join(tempDir, "recovery-elsewhere", "settings") + await fs.mkdir(swappedIn, { recursive: true }) + // An orphaned backup from an interrupted write, belonging to whatever file lives in the + // directory behind the ancestor's name now. Recovery renames a backup like this into the + // target's directory, so it is the step that can publish outside the scope. + const leftover = `.mcp.json.bak_${Date.now()}_abcdef.tmp` + await fs.writeFile(path.join(swappedIn, leftover), JSON.stringify({ previous: true }), "utf8") + const target = path.join(ancestor, "mcp.json") + const realAcquire = fileLockModule.acquireFileLock + const lockSpy = vi.spyOn(fileLockModule, "acquireFileLock").mockImplementation(async (key: string) => { + const release = await realAcquire(key) + // The swap lands while this writer waits for the lock, so the recovery step is the + // first thing that touches the tree with the swapped directory already in place. + swapAncestorAfterTheCheck(ancestor, swappedIn) + return release + }) + let captured: unknown = null + try { + captured = await safeWriteJson(target, { written: "payload" }, { confineTo: projectDir }).then( + () => null, + (reason: unknown) => reason, + ) + } finally { + lockSpy.mockRestore() + } + + expect(captured).toBeInstanceOf(ConfinedPathEscapeError) + // The backup is still where it was found, and no file was published into the directory + // outside the scope. Running recovery before the confinement decision was re-verified + // would have renamed this backup onto the target name, moving a file the caller never + // authorized out of the scope and consuming it as if it were this file's own history. + expect(await fs.readdir(swappedIn)).toEqual([leftover]) + }) + test("refuses the publish when the file link is retargeted out of scope during recovery", async () => { + const projectDir = path.join(tempDir, "retarget-project") + await fs.mkdir(projectDir) + const target = path.join(projectDir, "mcp.json") + await fsPromisesActuals.writeFile!(target, JSON.stringify({ previous: true }), "utf8") + const outsideDir = path.join(tempDir, "retarget-outside") + await fs.mkdir(outsideDir) + const movedTarget = path.join(outsideDir, "mcp.json") + await fsPromisesActuals.writeFile!(movedTarget, JSON.stringify({ outside: true }), "utf8") + // An orphaned replacement file beside the target, so the recovery step really runs and really + // reports. Its trace event is where this row lands the retarget: after the heal has finished + // touching the tree, before the strict resolution decides what to publish onto. + const leftover = `.mcp.json.new_1_def.tmp` + await fsPromisesActuals.writeFile!(path.join(projectDir, leftover), "{}") + // The link is retargeted on command, on the recovery step, rather than after a number of + // resolutions: everything resolved before the heal sees the name pointing inside the scope - + // the pre-lock check, the lock key and the in-lock re-check - and everything resolved after it + // sees it pointing elsewhere. What this row proves is that a changed target is refused; what it + // does not prove is that a real peer retarget lands in that window, which no double here shows. + let retargetedDuringRecovery = false + const traceEvents: Array<{ stage: string; detail?: string }> = [] + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) + const realpathSpy = vi.spyOn(fs, "realpath").mockImplementation(async (candidate) => { + const resolved = String(candidate) + if (resolved === target) { + return retargetedDuringRecovery ? movedTarget : target + } + return resolved + }) + const merge = vi.fn() + let captured: unknown = null + try { + captured = await safeWriteJson( + target, + { written: "payload" }, + { + confineTo: projectDir, + merge, + trace: (event) => { + traceEvents.push(event) + if (event.stage === "recover") { + retargetedDuringRecovery = true + } + }, + }, + ).then( + () => null, + (reason: unknown) => reason, + ) + expect(captured).toBeInstanceOf(ConfinedPathEscapeError) + const escape = captured as ConfinedPathEscapeError + // The thrown value names both halves of the move, so an operator sees what happened to the + // write they asked for rather than only where it ended up. + expect(escape.requestedPath).toBe(target) + expect(escape.resolvedPath).toBe(movedTarget) + expect(escape.confineTo).toBe(projectDir) + // The name is what a caller logs and what a remote error reader shows; instanceof alone never + // checks it, so a class that renamed itself would still pass every assertion above. + expect(escape.name).toBe("ConfinedPathEscapeError") + expect(escape.message).toContain(movedTarget) + expect(escape.message).toContain(target) + // The refusal came from the authorization asked again after the heal, not from the pre-lock + // one: recovery had already reported, so the scope had to be measured against the value the + // strict resolution produced. + expect(traceEvents.map((event) => event.stage)).toContain("recover") + // Refused before the file under the lock was read for merging and before anything was staged, + // so the file the peer moved is exactly as the peer left it. + expect(merge).not.toHaveBeenCalled() + expect(await fs.readdir(outsideDir)).toEqual(["mcp.json"]) + expect(await readFileContent(movedTarget)).toEqual({ outside: true }) + // The in-scope file was not published over, and nothing was left beside it; the orphaned + // replacement was consumed by the recovery step that ran before this authorization. + expect(await readFileContent(target)).toEqual({ previous: true }) + expect((await fs.readdir(projectDir)).filter((entry) => !entry.endsWith(".lock"))).toEqual(["mcp.json"]) + // Contrast, same fixture, same double, same options, with the link left pointing where the + // caller put it: the write publishes inside the scope. Without this the refusal above would + // also be the outcome of a confinement check that never ran. + retargetedDuringRecovery = false + await safeWriteJson(target, { written: "payload" }, { confineTo: projectDir }) + expect(await readFileContent(target)).toEqual({ written: "payload" }) + expect(await fs.readdir(outsideDir)).toEqual(["mcp.json"]) + } finally { + realpathSpy.mockRestore() + consoleErrorSpy.mockRestore() + } + }) + test("creates the staged JSON private and puts the target's own mode on it before publishing", async () => { + const target = path.join(tempDir, "mode-target.json") + await fs.writeFile(target, JSON.stringify({ existing: true }), "utf8") + await fs.chmod(target, 0o600) + // The mode as this platform reports it: Windows synthesizes the mode from the read-only + // attribute, so a 0o600 file is reported as writable there. The mode the publish copies is + // whatever stat reports, and the assertions below read it back rather than assuming the + // spelling. + const targetMode = (await fs.stat(target)).mode & 0o777 + // Captured from the real module: createWriteStream on the mocked namespace is the + // property the spy replaces, and fs.stat is the mocked stat. + const realCreate = (await vi.importActual("fs")).createWriteStream + const staged: { path: string; creationMode: number | undefined; modeWhileStaged: number | undefined }[] = [] + const createSpy = vi.spyOn(fsSyncActual, "createWriteStream").mockImplementation((( + filePath: string, + options: { mode?: number } = {}, + ) => { + const stream = realCreate(filePath, options) + const record = { + path: filePath, + creationMode: options.mode, + modeWhileStaged: undefined as number | undefined, + } + // createWriteStream opens the file lazily, so the staged file's own mode is read + // when the open lands - before the content is streamed and long before the rename + // buries the name in the target. + stream.on("open", () => { + record.modeWhileStaged = fsSyncActual.statSync(filePath).mode & 0o777 + }) + staged.push(record) + return stream + }) as never) + const chmodSpy = vi.spyOn(fs, "chmod") + // Read from the spy before mockRestore: restoring clears the call history, and the + // assertions below run after the finally block. + let chmodCalls: { stagedPath: string; mode: number }[] = [] + let failure: unknown = null + try { + failure = await safeWriteJson(target, { written: "payload" }, { confineTo: tempDir }).then( + () => null, + (reason: unknown) => reason, + ) + chmodCalls = chmodSpy.mock.calls.map((call) => ({ stagedPath: String(call[0]), mode: call[1] as number })) + } finally { + createSpy.mockRestore() + chmodSpy.mockRestore() + } + + expect(failure).toBeNull() + expect(staged).toHaveLength(1) + // The staged file is created private. It holds the caller's content for the whole time + // it takes to stream, flush and copy the target's mode onto it, and a mode copy can only + // narrow a file that is already restricted - a file created with the process umask is + // group- and world-readable for that whole window. + expect(staged[0].creationMode).toBe(0o600) + // The target's own mode is still the mode that gets published. + // The target's own mode, whatever this platform reports it as, is copied onto the staged + // file, which is the file the rename publishes. + expect( + chmodCalls.some( + (call) => path.resolve(call.stagedPath) === path.resolve(staged[0].path) && call.mode === targetMode, + ), + ).toBe(true) + if (process.platform !== "win32") { + // Windows derives the mode from the read-only attribute, so the observed mode is + // only evidence on platforms that store one. + expect(staged[0].modeWhileStaged).toBe(0o600) + expect((await fs.stat(target)).mode & 0o777).toBe(targetMode) + } + expect(JSON.parse(fsSyncActual.readFileSync(target, "utf8"))).toEqual({ written: "payload" }) + }) + test("publishes over a target whose mode is wider than the staged file's", async () => { + const target = path.join(tempDir, "mode-wider-target.json") + await fs.writeFile(target, JSON.stringify({ existing: true }), "utf8") + await fs.chmod(target, 0o664) + // Both sides of the mode test above are 0o600, so an implementation that published the + // staged file's private mode onto the target - the copy running the wrong way round - still + // passed it. Here the target starts wider than the staged file, so only a copy in the right + // direction can leave a group-readable target behind: a hardcoded 0o600 would quietly take + // group read away from a file the caller had deliberately left group-readable. + const targetMode = (await fs.stat(target)).mode & 0o777 + const chmodSpy = vi.spyOn(fs, "chmod") + let chmodModes: number[] = [] + let failure: unknown = null + try { + failure = await safeWriteJson(target, { written: "payload" }, { confineTo: tempDir }).then( + () => null, + (reason: unknown) => reason, + ) + // Read from the spy before mockRestore: restoring clears the call history. + chmodModes = chmodSpy.mock.calls.map((call) => call[1] as number) + } finally { + chmodSpy.mockRestore() + } + expect(failure).toBeNull() + expect(JSON.parse(fsSyncActual.readFileSync(target, "utf8"))).toEqual({ written: "payload" }) + // The mode handed to chmod is the target's own mode, read back rather than assumed, so the + // copy is pinned to the right direction on every platform. Windows synthesizes the reported + // mode from the read-only attribute, so the number here is 0o666 for a 0o664 request; the + // point is that it is not the staged file's 0o600. + expect(chmodModes).toContain(targetMode) + if (process.platform !== "win32") { + // The end state, on a platform that actually stores a mode: the target is still + // group-readable after the publish, at the mode the caller put on it. + expect((await fs.stat(target)).mode & 0o777).toBe(0o664) + } + }) + test("refuses to publish when the target's mode cannot be read (carried from 2443)", async () => { + const target = path.join(tempDir, "mode-unreadable-target.json") + await fs.writeFile(target, JSON.stringify({ existing: "content" }), "utf8") + const actual = await vi.importActual("fs/promises") + // Not a missing target and not a missing directory above it: the target is there and this + // write cannot read who may access it. Publishing the staged file's own mode over it would + // be a guess about who can read the saved file. 2443 asked for console.error plus the + // rejection; this module reports the refusal in the rejection alone (2452's spelling, + // carried unchanged), so the row asserts the rejection and the untouched target. + const eio = Object.assign(new Error("Target stat failed"), { code: "EIO" }) + const statSpy = vi.spyOn(fs, "stat").mockImplementation(async (statPath) => { + if (statPath === target) { + throw eio + } + return actual.stat(statPath) + }) + let captured: unknown = null + try { + captured = await safeWriteJson(target, { written: "payload" }, { confineTo: tempDir }).then( + () => null, + (reason: unknown) => reason, + ) + } finally { + statSpy.mockRestore() + } + expect(captured).toBeInstanceOf(Error) + expect((captured as Error).message).toContain("could not read the mode of") + expect((captured as Error).message).toContain(target) + // The publish stopped before the rename, so the widening the mode copy exists to prevent + // never happened: the target still holds exactly what it held before this write. + expect(await readFileContent(target)).toEqual({ existing: "content" }) + // This file's fs.rename double is module-wide and not cleared between rows, so the + // untouched target above is the assertion that pins the publish having stopped. + }) + test("aborts the publish when the staged file cannot take the target's mode", async () => { + const target = path.join(tempDir, "chmod-fail-target.json") + await fs.writeFile(target, JSON.stringify({ existing: true }), "utf8") + await fs.chmod(target, 0o600) + const eacces = Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" }) + const realChmod = (await vi.importActual("fs/promises")).chmod + const chmodSpy = vi.spyOn(fs, "chmod").mockImplementation(async (candidate, mode) => { + const stagedPath = String(candidate) + if (stagedPath.includes(".new_")) { + // The staged file is what becomes the target. Publishing it with its own mode + // would replace a 0o600 file with a wider one, which is the failure this step + // exists to prevent. + throw eacces + } + return realChmod(stagedPath, mode as number) + }) + let captured: unknown = null + try { + captured = await safeWriteJson(target, { written: "payload" }, { confineTo: tempDir }).then( + () => null, + (reason: unknown) => reason, + ) + } finally { + chmodSpy.mockRestore() + } + + expect(captured).toBeInstanceOf(Error) + expect((captured as Error).message).toContain("could not copy mode") + // The committed target still holds the content it had, at the mode it had. + expect(JSON.parse(fsSyncActual.readFileSync(target, "utf8"))).toEqual({ existing: true }) + expect((await fs.readdir(tempDir)).filter((entry) => entry.includes(".new_"))).toEqual([]) + }) + test("aborts the publish when the target's mode cannot be read", async () => { + const target = path.join(tempDir, "stat-fail-target.json") + await fs.writeFile(target, JSON.stringify({ existing: true }), "utf8") + const eacces = Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" }) + const realStat = (await vi.importActual("fs/promises")).stat + const statSpy = vi.spyOn(fs, "stat").mockImplementation(async (candidate) => { + if (path.resolve(String(candidate)) === path.resolve(target)) { + // The target is there but unreadable-by-us: its mode is unknown, so the mode the + // publish would land cannot be checked, and proceeding with the staged file's own + // mode is the one answer that can widen a restrictive file. + throw eacces + } + return realStat(String(candidate)) + }) + let captured: unknown = null + try { + captured = await safeWriteJson(target, { written: "payload" }, { confineTo: tempDir }).then( + () => null, + (reason: unknown) => reason, + ) + } finally { + statSpy.mockRestore() + } + + expect(captured).toBeInstanceOf(Error) + expect((captured as Error).message).toContain("could not read the mode") + expect(JSON.parse(fsSyncActual.readFileSync(target, "utf8"))).toEqual({ existing: true }) + expect((await fs.readdir(tempDir)).filter((entry) => entry.includes(".new_"))).toEqual([]) + }) + it("keeps the published target with its new content when the post-commit directory fsync fails", async () => { + const fsSyncMod = await import("fs") + const realFsync = fsSyncMod.fsyncSync + // The parent-directory fsync is the only fsync that runs after the commit rename. + // Watching the rename itself - rather than fabricating a descriptor - keeps the SUT + // in charge of opening and closing its own real directory handle, so the injected + // fsync failure is the only error in flight on every platform. + const fsyncFailure = new Error("EIO fsync") + let committed = false + // One entry per fsyncSync call, recording which descriptor was flushed and whether the + // commit rename had already landed. Watching the calls rather than the log is what makes + // the assertion below able to tell a failed directory fsync from a directory that was + // never opened at all: both paths end in the same warning. + const fsyncCalls: { fd: number; afterCommit: boolean }[] = [] + const actualRename = fsPromisesActuals.rename! + vi.mocked(fs.rename).mockImplementation((async (from: string, to: string) => { + await actualRename(from, to) + committed = true + }) as typeof fs.rename) + vi.spyOn(process, "platform", "get").mockReturnValue("linux") + // Spied without replacing: the directory handle this write opens is the evidence that + // the descriptor the fsync below names belongs to the committed target's parent. + const openSpy = vi.spyOn(fsSyncMod, "openSync") + vi.spyOn(fsSyncMod, "fsyncSync").mockImplementation(((fd: number) => { + fsyncCalls.push({ fd, afterCommit: committed }) + if (committed) { + throw fsyncFailure + } + return (realFsync as (f: number) => unknown)(fd) + }) as never) + // Earlier tests in this file leave unlink history on the shared mock. + vi.mocked(fs.unlink).mockClear() + const consoleWarnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}) + const failure: unknown = await safeWriteJson(currentTestFilePath, { fresh: "content" }).then( + () => null, + (error: unknown) => error, + ) + // The protocol that ships here treats the post-commit parent-directory fsync as best + // effort: the publish already happened, so a failed directory fsync is reported and the + // write completes. (The chain's earlier mechanism wrapped it in PostCommitDurabilityError + // and rejected; that wrapper is not part of this protocol - see the merge note above.) + expect(failure).toBeNull() + const parentDir = path.dirname(path.resolve(currentTestFilePath)) + const directoryHandles = openSpy.mock.calls.flatMap((call, index) => + path.resolve(String(call[0])) === parentDir ? [openSpy.mock.results[index]?.value as number] : [], + ) + // The directory the published file now lives in was opened, ... + expect(directoryHandles.length).toBeGreaterThan(0) + // ... and a fsync actually ran on that handle after the commit rename. Without this, the + // warning below is satisfied by the same log line that reports "the directory could not + // be opened", in which case no fsync ever executed. + expect(fsyncCalls.some((call) => call.afterCommit && directoryHandles.includes(call.fd))).toBe(true) + // The warning names the directory that was not flushed. + expect(consoleWarnSpy.mock.calls.some((call) => /fsync/.test(String(call[0])))).toBe(true) + // The rename committed: the target must still hold the new JSON, not be unlinked away + // by the catch cleanup of the consumed staging path. + const content = await readFileContent(currentTestFilePath) + expect(content).toEqual({ fresh: "content" }) + // The cleanup must not unlink the consumed staging path: after the commit rename it is + // no longer this write's file to remove. + const stagingUnlinks = vi.mocked(fs.unlink).mock.calls.filter((call) => /\.new_.*\.tmp$/.test(String(call[0]))) + expect(stagingUnlinks).toHaveLength(0) + consoleWarnSpy.mockRestore() + }) +}) + +// Blocks carried across the merge from the side that landed this module on the writers unit (pull +// 2452). The merged module keeps that side's guarantees, so its evidence travels with them. +// They are appended in their own describe so this file's own setup stays readable. +describe("guarantees carried from the writers unit (2452)", () => { + let carriedTempDir: string + let carriedFilePath: string + + beforeEach(async () => { + carriedTempDir = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "safeWriteJson-carried-"))) + carriedFilePath = path.join(carriedTempDir, "test-file.json") + }) + + afterEach(async () => { + await fs.rm(carriedTempDir, { recursive: true, force: true }) + }) + + test("rejects an out-of-scope target before creating any directory", async () => { + const projectDir = path.join(carriedTempDir, "scope") + await fs.mkdir(projectDir) + // The target lives in a directory that does not exist. A confinement check that runs + // after the mkdir -p would create that directory OUTSIDE the declared scope first - + // the same side effect the pre-lock check exists to prevent, reached through a + // symlinked ancestor in the reported case - and an unwritable referent would surface + // the mkdir error instead of the confinement verdict. + const missingParent = path.join(carriedTempDir, "no-such-dir") + const outside = path.join(missingParent, "elsewhere.json") + + await expect(safeWriteJson(outside, { mcpServers: {} }, { confineTo: projectDir })).rejects.toThrow( + ConfinedPathEscapeError, + ) + + // Nothing was created outside the scope, and no lock was attempted there. + expect(fsSyncActual.existsSync(missingParent)).toBe(false) + expect( + (await fs.readdir(carriedTempDir)).filter(function (entry: string) { + return entry.endsWith(".lock") + }), + ).toEqual([]) + }) + + test("a failed commit keeps the previous content at the target and leaves no backup behind", async () => { + const initialData = { message: "Initial, must survive a failed commit" } + const newData = { message: "New content" } + + await fsPromisesActuals.writeFile!(carriedFilePath, JSON.stringify(initialData)) + + const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {}) // Suppress console.error + + // fs.rename is already vi.fn() — use vi.mocked to avoid double-wrapping via vi.spyOn + let renameCallCount = 0 + vi.mocked(fs.rename).mockImplementation(async (oldPath, newPath) => { + renameCallCount++ + if (renameCallCount === 1) { + // The commit rename fails with a non-EPERM error, so no fallback runs. + throw new Error("Primary rename failed") + } + return fsPromisesActuals.rename!(oldPath, newPath) + }) + + await expect(safeWriteJson(carriedFilePath, newData)).rejects.toThrow("Primary rename failed") + + // Exactly one rename was attempted, and it was the commit. + expect(renameCallCount).toBe(1) + + // The target never left its path, so the previous content is still what a + // reader sees, and no orphaned backup copy is left behind either. + // readFileContent lives inside the other describe's scope, so read through the real + // fs/promises the same way that helper did. + const content = JSON.parse(String(fsSyncActual.readFileSync(carriedFilePath, "utf8"))) + expect(content).toEqual(initialData) + const leftovers = (await fs.readdir(carriedTempDir)).filter( + (entry) => entry.includes(".bak_") || entry.includes(".new_") || entry.includes("safeWriteText.bak_"), + ) + expect(leftovers).toEqual([]) + + consoleErrorSpy.mockRestore() + }) }) diff --git a/src/utils/safeWriteJson.ts b/src/utils/safeWriteJson.ts index e54b8c51d3..3ec9586055 100644 --- a/src/utils/safeWriteJson.ts +++ b/src/utils/safeWriteJson.ts @@ -6,6 +6,18 @@ import { JsonStreamStringify } from "json-stream-stringify" import { getErrorCode } from "./errorCode" import { acquireFileLock } from "./fileLock" import { recoverInterruptedReplacement } from "./jsonFileRecovery" +import { + AncestorReplacedError, + OrphanedBackupError, + PostCommitDurabilityError, + resolveLockKey, + resolvePublishTarget, + StagingPathError, + StagingReplacedError, + TargetMovedError, + type AncestorIdentity, + type SafeWriteTextOptions, +} from "../services/file-safety/safeWritePrimitives" /** * Stages reported through the optional `trace` callback. They mark the @@ -46,6 +58,176 @@ export interface SafeWriteJsonOptions { * to emit diagnostic trace lines; it never influences the write itself. */ trace?: SafeWriteJsonTrace + + /** + * Restrict the write to a directory. The publish target is resolved through + * symlinks before this check runs, so a caller that picked the path from a + * known scope (a workspace, a project settings directory) can refuse a write + * that a planted symlink would land somewhere else. The check runs before the + * advisory lock is taken and before anything is staged. + */ + confineTo?: string +} + +/** + * Thrown when a write declared with `confineTo` resolves outside that directory. + */ +export class ConfinedPathEscapeError extends Error { + constructor( + readonly requestedPath: string, + readonly resolvedPath: string, + readonly confineTo: string, + ) { + super( + `Refusing to write ${resolvedPath}: it resolves outside the confined directory ${confineTo} (requested ${requestedPath}).`, + ) + this.name = "ConfinedPathEscapeError" + } +} + +/** + * Canonicalize the directory a write is confined to. The publish target is fully + * resolved through symlinks, so the scope has to be resolved the same way or a + * scope path that itself runs through a symlink (macOS /var -> /private/var is the + * common case) would compare lexically against a resolved target and reject every + * legitimate in-scope write. When the scope does not exist yet, the nearest + * existing ancestor is resolved and the remainder re-appended. + */ +async function _resolveScopeRoot(confineTo: string): Promise { + const lexical = path.resolve(confineTo) + try { + return await fs.realpath(lexical) + } catch (error: unknown) { + // Only a missing path means "walk up and re-join". EACCES or ELOOP means the + // scope cannot be canonicalized at all, and continuing would build a partly + // lexical root that can disagree with the canonical target - the failure has to + // surface rather than decide the scope from a guess. + if (getErrorCode(error) !== "ENOENT") { + throw error + } + const missing: string[] = [] + let ancestor = lexical + while (true) { + const parent = path.dirname(ancestor) + if (parent === ancestor) { + return lexical + } + missing.push(path.basename(ancestor)) + ancestor = parent + try { + const real = await fs.realpath(ancestor) + return path.join(real, ...missing.reverse()) + } catch (innerError: unknown) { + if (getErrorCode(innerError) !== "ENOENT") { + throw innerError + } + } + } + } +} + +/** + * Whether `candidate` sits outside `scopeRoot`. The scope root itself counts as + * outside: a file write cannot land on the directory that declares the scope. + */ +function _escapesScope(scopeRoot: string, candidate: string): boolean { + const relative = path.relative(scopeRoot, candidate) + return relative === "" || relative === ".." || relative.startsWith(".." + path.sep) || path.isAbsolute(relative) +} + +/** + * The directories between the canonical scope root and the target's parent, each with + * the identity it had when the write was authorized. `confineTo` decides from the + * resolved target; this is what lets the publish notice that a directory it walked was + * replaced afterwards, because safeWriteText re-reads every one of them right before the + * commit rename (see the confineTo option doc). + * + * A component that does not exist yet (a create into a directory the publish itself will + * make) has no identity to pin, so it is skipped: there is nothing to compare, and the + * pin exists to detect a directory that WAS walked being swapped, not to forbid creating + * one. + */ +/** + * Re-verify the pinned confinement decision against what is on disk now. + * + * The target name is checked first, because an existing target makes an ancestor swap visible in + * the resolved name itself: that is TargetMovedError, and the error carries what the path resolves + * to NOW rather than the resolution the write was authorized against, so a caller reading the + * failure sees the destination that exists instead of the one that stopped being true. A create + * into a swapped directory leaves the name resolving to itself, so the pinned directories are what + * catch it: AncestorReplacedError, naming the directory that moved. + * + * Each pinned directory is compared by identity and by resolution. A directory that was moved + * keeps its dev+ino and its old name can be replaced by a link that points at it, so the identity + * comparison passes while the name no longer means the location that was walked; the publish takes + * path strings and would follow that link out of the scope. A stat or realpath failure that is not + * "this path is gone" (EACCES, EIO) is propagated unchanged: reporting it as a replaced ancestor + * would point the user at a containment problem that is not there. + */ +async function _assertConfinementStillHolds( + absoluteFilePath: string, + expectedResolvedPath: string, + pinnedDirectories: AncestorIdentity[], +): Promise { + const currentResolvedPath = await resolvePublishTarget(absoluteFilePath) + if (currentResolvedPath !== expectedResolvedPath) { + throw new TargetMovedError(expectedResolvedPath, currentResolvedPath) + } + for (const pinnedDirectory of pinnedDirectories) { + const now = await fs.stat(pinnedDirectory.dir, { bigint: true }).catch((error: unknown) => { + const code = getErrorCode(error) + if (code === "ENOENT" || code === "ENOTDIR") { + return undefined + } + throw error + }) + // The error names the directory that moved; the reason is what this comparison actually + // observed, stated without the identity numbers it compared. + if (now === undefined || now.dev !== pinnedDirectory.dev || now.ino !== pinnedDirectory.ino) { + throw new AncestorReplacedError( + pinnedDirectory.dir, + "is no longer the directory the confinement check walked", + ) + } + const resolvedDir = await fs.realpath(pinnedDirectory.dir).catch((error: unknown) => { + const code = getErrorCode(error) + if (code === "ENOENT" || code === "ENOTDIR") { + return undefined + } + throw error + }) + if (resolvedDir === undefined || path.resolve(resolvedDir) !== path.resolve(pinnedDirectory.dir)) { + throw new AncestorReplacedError( + pinnedDirectory.dir, + "no longer resolves to the location the confinement check walked", + ) + } + } +} + +async function _ancestorIdentities(root: string, targetParent: string): Promise { + const relative = path.relative(root, targetParent) + const chain: string[] = [root] + if (relative && relative !== "." && !relative.startsWith(".." + path.sep) && !path.isAbsolute(relative)) { + let cursor = root + for (const segment of relative.split(path.sep)) { + cursor = path.join(cursor, segment) + chain.push(cursor) + } + } + const pinned: AncestorIdentity[] = [] + for (const dir of chain) { + // A missing ancestor has no identity to pin, but any other stat failure means the + // walk could not verify the chain: dropping it would let a swapped-in directory + // escape the confine check, so fail closed instead of skipping the pin. + // The publish creates the target's parent before it takes the lock and pins the ancestors + // after the lock is held, so a component that is missing here was removed during the publish. + // Skipping it would leave the chain unverified, and a symlink placed at that path before the + // staging write sends both the staged file and the commit rename outside the confine. + const stat = await fs.stat(dir, { bigint: true }) + pinned.push({ dir, dev: stat.dev, ino: stat.ino }) + } + return pinned } function createTempFilePath(absoluteFilePath: string, kind: "new" | "bak"): string { @@ -62,6 +244,9 @@ function createTempFilePath(absoluteFilePath: string, kind: "new" | "bak"): stri * - Recovers an interrupted previous write before touching the file: restores an orphaned backup when the canonical path is absent, and removes leftover temp files. * - Writes to a temporary file first, then commits it with a single atomic rename, so the committed target stays readable through an interrupted write. * - When a single rename over the target fails with EPERM (a reader holds the file open on Windows), falls back to backing the target up before replacing it. + * - Stages the replacement beside the resolved publish target, resolves the advisory + * lock key to the same referent, and refuses a write declared with confineTo when + * either the target or the lock key resolves outside that scope. * - Attempts to roll back and clean up in case of errors. * - Supports pretty-printing with indentation while maintaining streaming efficiency. * @@ -78,6 +263,31 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit // For directory creation const dirPath = path.dirname(absoluteFilePath) + // Pinned before the lock is taken: the canonical directory the write is confined to. Every + // confinement decision below is made against THIS root. Re-resolving confineTo after the lock + // would follow a link that someone placed at the scope's name while this writer waited, and the + // check would then bless whatever directory arrived there instead of the one the caller named. + let confinedScopeRoot: string | undefined + + // Declared outside the protected block so the catch and finally can still name + // the target when the resolution itself rejects. + let resolvedTargetPath: string | undefined + + // Confinement is checked before ANY filesystem side effect. mkdir -p through a + // planted symlinked ancestor (projectDir/.roo -> /elsewhere) would create + // directories outside the declared scope, and an unwritable referent would surface + // the mkdir error instead of the ConfinedPathEscapeError the caller is entitled to. + // _resolveScopeRoot resolves a not-yet-existing path through its nearest existing + // ancestor, so this works for the target's missing parents too. + if (options?.confineTo) { + const scopeRoot = await _resolveScopeRoot(options.confineTo) + const requested = await _resolveScopeRoot(absoluteFilePath) + if (_escapesScope(scopeRoot, requested)) { + throw new ConfinedPathEscapeError(absoluteFilePath, requested, scopeRoot) + } + confinedScopeRoot = scopeRoot + } + // Ensure directory structure exists with improved reliability try { // Create directory with recursive option @@ -90,24 +300,111 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit throw dirError } - // Acquire the lock before any file operations. `acquireFileLock` owns the - // shared advisory lock protocol, so callers that lock the same path with - // it (for example task-history deletion) serialize with this write. - // If lock acquisition fails, it throws immediately. The releaseLock - // remains a no-op, so the finally block in the main file operations - // try-catch-finally won't try to release an unacquired lock if this - // path is taken. - releaseLock = await acquireFileLock(absoluteFilePath) + // Lock key: the symlink referent when the path is an existing symlink, so a + // symlink alias and its referent share one lock. The key must stay computable while + // a peer writer is mid-commit - the commit rename briefly leaves the path without + // the referent it had when the walk started - so the walk tolerates a dangling link + // instead of rejecting it here. (The EPERM fallback below does rename the target onto a + // backup of its own, so a dangling link here can be that fallback mid-flight as well as + // a peer's commit or an external unlink; either way the next write finds its files beside + // the referent, because the key IS the referent.) + const lockKey = await resolveLockKey(absoluteFilePath) + + // Confinement is checked here as well as under the lock. The lock file lives NEXT + // TO the key, so a planted symlink that points outside the declared scope would + // first make this write create ".lock" outside that scope - a side effect + // the caller declared it would not have - and if that directory is not writable the + // caller would get a lock-acquisition error instead of the ConfinedPathEscapeError + // it is entitled to. The key is the symlink referent, so this check sees the same + // destination the lock would be taken on. The under-lock check stays: it covers the + // target re-resolved after a peer commits. + if (confinedScopeRoot !== undefined) { + if (_escapesScope(confinedScopeRoot, await _resolveScopeRoot(lockKey))) { + throw new ConfinedPathEscapeError(absoluteFilePath, lockKey, confinedScopeRoot) + } + } + + // Acquire the lock before any file operations. If acquisition fails it throws + // immediately, and releaseLock stays a no-op so the finally block does not try + // to release an unacquired lock. + releaseLock = await acquireFileLock(lockKey) // Variables to hold the actual paths of temp files if they are created. let actualTempNewFilePath: string | null = null let actualTempBackupFilePath: string | null = null try { + // First resolution, tolerant on purpose: resolvePublishTarget rejects a link with no + // referent, and while the link dangles the lock key still names the file an interrupted + // publish was renaming onto - the place the recovery below has to look, because the + // leftover names are derived from the publish target the interrupted write resolved. + // The strict resolution runs after that recovery, inside the protected block (a rejection + // here must not leave the advisory lock held until the stale timeout), so a link recovery + // healed resolves there and a link that is still dangling is refused rather than + // written through. + const initialTarget = await resolvePublishTarget(absoluteFilePath).catch((error: unknown) => { + if (getErrorCode(error) !== "ENOENT") { + throw error + } + return lockKey + }) + resolvedTargetPath = initialTarget + + // Confinement, if the caller declared a scope. Both sides are canonicalized the + // same way: the publish target is resolved through symlinks, and a target that + // does not exist yet still carries the alias components of the path it was + // given. The root is the one captured before the lock, so a link placed at the + // scope's own name while this writer waited cannot move the goalposts. This runs + // before the merge read and before anything is staged, so a rejected write leaves + // nothing behind. + if (confinedScopeRoot !== undefined) { + if (_escapesScope(confinedScopeRoot, await _resolveScopeRoot(resolvedTargetPath))) { + throw new ConfinedPathEscapeError(absoluteFilePath, resolvedTargetPath, confinedScopeRoot) + } + } + + // What the confinement decision was made ABOUT is pinned for the rest of the publish: the + // resolved publish target, and the identity (dev, ino) of every directory walked from the + // scope root down to the target's parent. The pins are re-verified three times - before + // recovery touches the tree, after the merge read and before anything is staged, and + // immediately before the commit rename - so an ancestor directory replaced by a link at any + // point in the publish aborts it instead of redirecting it outside the scope. Without the + // pins the publish would follow the swap at each of those steps. + let expectedResolvedPath: string | undefined + let expectedAncestorIdentities: SafeWriteTextOptions["expectedAncestorIdentities"] + if (confinedScopeRoot !== undefined) { + const canonicalTarget = await _resolveScopeRoot(resolvedTargetPath) + expectedResolvedPath = resolvedTargetPath + expectedAncestorIdentities = await _ancestorIdentities(confinedScopeRoot, path.dirname(canonicalTarget)) + // Verify before recovery touches anything. Recovery renames an orphaned backup into the + // target's directory and deletes leftover replacement files it matches by name; doing that + // before the walked directories are re-verified would let an ancestor that was already + // replaced move those changes outside confineTo, where the caller never authorized any write. + // An interrupted EPERM fallback can leave an in-scope alias dangling over a referent that is + // gone while its backup still sits beside the lock key. The strict resolution inside the + // check below rejects exactly that with ENOENT, which would stop this write before the + // recovery that heals the referent ever ran. Defer only that answer: recovery runs next, + // and the strict resolution after it, at the re-target block below and again before + // staging, still refuses a link that is dangling when there was nothing to heal. + try { + await _assertConfinementStillHolds(absoluteFilePath, expectedResolvedPath, expectedAncestorIdentities) + } catch (preRecoveryError: unknown) { + if (getErrorCode(preRecoveryError) !== "ENOENT") { + throw preRecoveryError + } + options?.trace?.({ stage: "recover", detail: "confinement-precheck-deferred:ENOENT" }) + } + } + // Heal any state an interrupted previous write left behind: an absent - // canonical path with an orphaned backup, or leftover replacement - // files. Runs first so a merge callback reads the restored content. - const recovery = await recoverInterruptedReplacement(absoluteFilePath).catch((error: unknown) => { + // canonical path with an orphaned backup, or leftover replacement files. Runs + // before the merge read so a merge callback reads the restored content, and after + // the checks above so it cannot act outside the declared scope. It scans the + // directory the LOCK KEY names rather than the directory of the path this caller + // spelled: the interrupted write staged its files beside the publish target it + // resolved, so a writer arriving through a differently named alias can only find + // them by looking beside the referent - which is where the key points. + const recovery = await recoverInterruptedReplacement(lockKey).catch((error: unknown) => { const code = getErrorCode(error) ?? "unknown" options?.trace?.({ stage: "recover", detail: `failed:${code}` }) throw error @@ -116,13 +413,47 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit options?.trace?.({ stage: "recover", detail: recovery.restoredFrom ?? "cleaned-leftovers" }) } + // Strict resolution after the heal: the target this write publishes to, decided once the + // leftovers beside the referent are gone. Where it differs from the path the confinement pins + // were computed against, the scope authorization is repeated against the canonical root that + // confineTo established before the new target is accepted, and only then do the pins move with + // it. The re-authorization is not covered by the re-verification below: the helper compares a + // fresh resolution of the requested path against the value this block stores into + // expectedResolvedPath, so once a changed target has been stored that comparison is the new + // resolution against itself, and all that is left in it is the loop over the ancestor + // directories pinned from the original target - a different attack, which is why the pins stay + // where they are. + + resolvedTargetPath = await resolvePublishTarget(absoluteFilePath) + if ( + expectedResolvedPath !== undefined && + expectedAncestorIdentities !== undefined && + resolvedTargetPath !== expectedResolvedPath + ) { + // A target that moved while this writer was inside recoverInterruptedReplacement above + // is a new authorization, not a detail of the old one: another process can repoint the + // file link during that step, and the strict resolution above then names a file outside + // the declared scope. Refuse with the error a confined write already carries for a target + // that escapes, naming the target that was authorized and the one that arrived so an + // operator can see what moved. confinedScopeRoot is the canonical directory pinned before + // the lock, so the fresh value is measured against the scope the caller named. + if (confinedScopeRoot !== undefined) { + const retargetedScopeCheck = await _resolveScopeRoot(resolvedTargetPath) + if (_escapesScope(confinedScopeRoot, retargetedScopeCheck)) { + throw new ConfinedPathEscapeError(expectedResolvedPath, resolvedTargetPath, confinedScopeRoot) + } + } + expectedResolvedPath = resolvedTargetPath + await _assertConfinementStillHolds(absoluteFilePath, expectedResolvedPath, expectedAncestorIdentities) + } + // If a merge callback was provided, read the current file under the lock // and let the caller merge before we write. Must be inside try/finally // so a throwing merge still releases the lock. if (options?.merge) { let existing: unknown = null try { - existing = JSON.parse(await fs.readFile(absoluteFilePath, "utf8")) + existing = JSON.parse(await fs.readFile(resolvedTargetPath, "utf8")) } catch (error: unknown) { const code = getErrorCode(error) if (!(error instanceof SyntaxError) && code !== "ENOENT") { @@ -132,21 +463,45 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit data = options.merge(existing, data) } + // Re-verify the pinned decision against what is on disk now, before anything is staged. + if (expectedResolvedPath !== undefined) { + await _assertConfinementStillHolds(absoluteFilePath, expectedResolvedPath, expectedAncestorIdentities ?? []) + } + // Step 1: Write data to a new temporary file and flush it to storage, // making a best-effort flush before committing the replacement. options?.trace?.({ stage: "write-start" }) - actualTempNewFilePath = createTempFilePath(absoluteFilePath, "new") + // Stage it beside the *resolved* publish target (the symlink referent when the + // path is a symlink): the commit rename below lands on that referent, and a rename + // across filesystems would fail with EXDEV. + actualTempNewFilePath = createTempFilePath(resolvedTargetPath, "new") await _streamDataToFile(actualTempNewFilePath, data, options?.prettyPrint) + + // CWE-732: the commit renames the staged file onto the target, so the file that + // lands carries the STAGED file's mode, not the target's. A 0o600 target would + // otherwise be published as 0o644 with the umask-derived default. Copy the target's + // mode onto the staged file before the rename; a target that is not there yet has no + // mode to copy, and POSIX modes are ignored on Windows. + await _copyTargetMode(resolvedTargetPath, actualTempNewFilePath) await _flushFileToDisk(actualTempNewFilePath) // Step 2: Commit the replacement with a single atomic rename. The // committed target stays in place until this rename lands, so a // process exit before or during the commit can no longer leave the // canonical path absent. + // + // The check above ran before the staged write; the staged write is the step that takes the + // time. Verify again here, against the statement that actually acts on the pinned decision, + // so an ancestor replaced while the JSON was streaming to disk cannot publish outside the + // scope: the rename below moves the staged file along the path this write resolved before the + // swap, and the staged file itself already followed the swap. + if (expectedResolvedPath !== undefined) { + await _assertConfinementStillHolds(absoluteFilePath, expectedResolvedPath, expectedAncestorIdentities ?? []) + } try { options?.trace?.({ stage: "replacement-rename" }) - await fs.rename(actualTempNewFilePath, absoluteFilePath) + await fs.rename(actualTempNewFilePath, resolvedTargetPath) } catch (renameError: unknown) { if (getErrorCode(renameError) !== "EPERM") { throw renameError @@ -159,15 +514,19 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit // second rename fails, and the recovery pass at the start of the // next write repairs a crash between the two renames. options?.trace?.({ stage: "backup-rename", detail: "eperm-fallback" }) - actualTempBackupFilePath = createTempFilePath(absoluteFilePath, "bak") - await fs.rename(absoluteFilePath, actualTempBackupFilePath) + actualTempBackupFilePath = createTempFilePath(resolvedTargetPath, "bak") + await fs.rename(resolvedTargetPath, actualTempBackupFilePath) options?.trace?.({ stage: "replacement-rename", detail: "eperm-fallback" }) - await fs.rename(actualTempNewFilePath, absoluteFilePath) + await fs.rename(actualTempNewFilePath, resolvedTargetPath) } // If we reach here, the new file is successfully in place. // The original actualTempNewFilePath is now the main file, so we shouldn't try to clean it up as "temp". // Mark as "used" or "committed" + + // The rename is durable only once the directory entry that records it reaches disk + // too. Best effort and POSIX-only - see _flushDirectoryToDisk. + _flushDirectoryToDisk(path.dirname(resolvedTargetPath)) actualTempNewFilePath = null options?.trace?.({ stage: "write-complete" }) @@ -181,13 +540,16 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit // Log this error, but do not re-throw. The main operation was successful. // actualTempBackupFilePath remains set, indicating an orphaned backup. console.error( - `Successfully wrote ${absoluteFilePath}, but failed to clean up backup ${actualTempBackupFilePath}:`, + `Successfully wrote ${resolvedTargetPath ?? absoluteFilePath}, but failed to clean up backup ${actualTempBackupFilePath}:`, unlinkBackupError, ) } } } catch (originalError) { - console.error(`Operation failed for ${absoluteFilePath}: [Original Error Caught]`, originalError) + console.error( + `Operation failed for ${resolvedTargetPath ?? absoluteFilePath}: [Original Error Caught]`, + originalError, + ) const newFileToCleanupWithinCatch = actualTempNewFilePath const backupFileToRollbackOrCleanupWithinCatch = actualTempBackupFilePath @@ -195,13 +557,15 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit // Attempt rollback if a backup was made if (backupFileToRollbackOrCleanupWithinCatch) { try { - await fs.rename(backupFileToRollbackOrCleanupWithinCatch, absoluteFilePath) + await fs.rename(backupFileToRollbackOrCleanupWithinCatch, resolvedTargetPath ?? absoluteFilePath) // Mark as handled, prevent later unlink of this path actualTempBackupFilePath = null } catch (rollbackError) { // actualTempBackupFilePath (outer scope) remains pointing to backupFileToRollbackOrCleanupWithinCatch console.error( - `[Catch] Failed to restore backup ${backupFileToRollbackOrCleanupWithinCatch} to ${absoluteFilePath}:`, + `[Catch] Failed to restore backup ${backupFileToRollbackOrCleanupWithinCatch} to ${ + resolvedTargetPath ?? absoluteFilePath + }:`, rollbackError, ) } @@ -211,11 +575,16 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit if (newFileToCleanupWithinCatch) { try { await fs.unlink(newFileToCleanupWithinCatch) - } catch (cleanupError) { - console.error( - `[Catch] Failed to clean up temporary new file ${newFileToCleanupWithinCatch}:`, - cleanupError, - ) + } catch (cleanupError: unknown) { + // An already-gone staging file is the normal outcome when the failure was the + // commit rename itself, so it is not a second failure and must not be logged as + // one; the caller would otherwise see two errors for one write. + if (getErrorCode(cleanupError) !== "ENOENT") { + console.error( + `[Catch] Failed to clean up temporary new file ${newFileToCleanupWithinCatch}:`, + cleanupError, + ) + } } } @@ -230,7 +599,7 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit await releaseLock() } catch (unlockError) { // Do not re-throw here, as the originalError from the try/catch (if any) is more important. - console.error(`Failed to release lock for ${absoluteFilePath}:`, unlockError) + console.error(`Failed to release lock for ${lockKey}:`, unlockError) } } } @@ -244,7 +613,12 @@ async function safeWriteJson(filePath: string, data: unknown, options?: SafeWrit */ async function _streamDataToFile(targetPath: string, data: unknown, prettyPrint = false): Promise { // Stream data to avoid high memory usage for large JSON objects. - const fileWriteStream = fsSync.createWriteStream(targetPath, { encoding: "utf8" }) + // mode 0o600 at creation: the staged file holds the caller's content - task history, MCP + // servers, settings - for as long as it takes to stream, flush, copy the target's mode onto it + // and rename it. Created with the process umask it would be group- and world-readable for that + // whole window, and the mode copy below can only narrow a staged file, not make an already-read + // copy unreadable again. A target with its own mode still gets that mode, applied below. + const fileWriteStream = fsSync.createWriteStream(targetPath, { encoding: "utf8", mode: 0o600 }) // JsonStreamStringify traverses the object and streams tokens directly // The 'spaces' parameter adds indentation during streaming, not via a separate pass @@ -263,6 +637,99 @@ async function _streamDataToFile(targetPath: string, data: unknown, prettyPrint }) } +/** + * Copies the existing target's permission mode onto the staged file so the publish + * does not silently widen it. A missing target has no mode to copy. Any other failure + * aborts the write rather than logging and proceeding: the commit renames the staged + * file onto the target, so a write that could not read the target's mode, or could not + * put it on the staged file, would publish a 0o600 file's content under 0o644 and tell + * nobody. That is the same rule safeWriteText states for its own mode handling (see its + * errorCode helper), and the staged file is created 0o600 so the content is never + * readable to others while this decision is being made. + */ +async function _copyTargetMode(targetPath: string, stagedPath: string): Promise { + let mode: number + try { + const stats = await fs.stat(targetPath) + mode = stats.mode & 0o777 + } catch (statError: unknown) { + const code = getErrorCode(statError) + if (code === "ENOENT" || code === "ENOTDIR") { + // Nothing is committed yet and no mode exists to preserve: the staged file's own + // private mode is the mode this write publishes. + return + } + // The target's mode is unknown, so the mode the publish would land cannot be checked. + // Failing here is the only answer that cannot widen a restrictive file's access. + throw _publishFault( + statError, + `safeWriteJson: could not read the mode of ${targetPath} before publishing onto it`, + ) + } + try { + await fs.chmod(stagedPath, mode) + } catch (chmodError: unknown) { + // The staged file is what becomes the target. Publishing it with its own mode would + // replace a restrictive file with a permissive one, which is the failure this step exists + // to prevent, so the write stops with the mode it could not honour named in the error. + throw _publishFault( + chmodError, + `safeWriteJson: could not copy mode ${mode.toString(8)} from ${targetPath} onto the staged file ${stagedPath}`, + ) + } +} + +/** + * Names a publish fault without re-describing one. The four classes named below come + * from the file-safety primitives. This module calls none of the code that raises them: + * it imports the two resolvers, the two identity errors and the primitives option shape + * from that module, and nothing else, so the chain below cannot fire through this module + * today. The fall-through builds the same Error, the same message text and the same + * cause as the two throw sites in _copyTargetMode built before this helper existed, so + * nothing a caller can read changes. It stands so that a fault arriving as one of those + * classes keeps its own name instead of being re-described as a generic write fault. + */ +function _publishFault(fault: unknown, message: string): Error { + if ( + fault instanceof StagingPathError || + fault instanceof StagingReplacedError || + fault instanceof OrphanedBackupError || + fault instanceof PostCommitDurabilityError + ) { + return fault + } + return new Error(message, { cause: fault }) +} + +/** + * Syncs the directory that holds a freshly committed file. A rename only survives a + * crash once the directory entry recording it is on disk as well. Best effort by + * design: the write already published, and a filesystem that refuses to open or fsync + * a directory must not turn a completed write into a reported failure - the content is + * at the target either way, so the caller is told through the log, not through a + * rejection. POSIX only: Windows cannot open a directory for this purpose. + */ +function _flushDirectoryToDisk(directoryPath: string): void { + if (process.platform === "win32") { + return + } + let fd: number | undefined + try { + fd = fsSync.openSync(directoryPath, "r") + fsSync.fsyncSync(fd) + } catch (dirSyncError: unknown) { + console.warn(`Could not fsync ${directoryPath} after publishing a file into it:`, dirSyncError) + } finally { + if (fd !== undefined) { + try { + fsSync.closeSync(fd) + } catch (closeError: unknown) { + void closeError + } + } + } +} + /** * Flushes a fully written temp file to storage before it is committed. * Best effort: durability against power loss is a bonus here, process-crash