@openclaw/fs-safe 0.11.0 → 0.13.0

package/dist/local-roots.js

@@ -7,6 +7,7 @@ import { isFileUrl, safeFileURLToPath } from "./local-file-access.js";
 import { realpathSync } from "./realpath.js";
 import { ROOT_PATH_ALIAS_POLICIES, resolveRootPathSync } from "./root-path.js";
 import { root } from "./root.js";
+import { assertNoWindowsPathAlias, isWindowsPathAliasError, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 function resolveLocalPathInput(input, label) {
     if (isFileUrl(input)) {
         try {
@@ -20,14 +21,18 @@ function resolveLocalPathInput(input, label) {
     if (input.includes("\0")) {
         throw new FsSafeError("invalid-path", `${label} must not contain NUL bytes`);
     }
+    assertNoWindowsPathAlias(input, "filesystem", `${label} uses a Windows filesystem namespace alias`);
     const homePrefix = input === "~" || input.startsWith("~/") ||
         (path.sep === "\\" && input.startsWith("~\\"));
     const expanded = homePrefix ? `${resolveRequiredHomeDir()}${path.sep}${input.slice(2)}` : input;
+    assertNoWindowsPathAlias(expanded, "filesystem", `${label} uses a Windows filesystem namespace alias`);
     if (path.isAbsolute(expanded))
         return expanded;
     const drive = path.parse(expanded).root;
     const base = drive ? path.resolve(drive) : process.cwd();
-    return `${base}${path.sep}${expanded.slice(drive.length)}`;
+    const resolved = `${base}${path.sep}${expanded.slice(drive.length)}`;
+    assertNoWindowsPathAlias(resolved, "filesystem", `${label} uses a Windows filesystem namespace alias`);
+    return resolved;
 }
 function resolveLocalRootInput(input, label) {
     const trimmed = input.trim();
@@ -40,29 +45,44 @@ function resolveLocalRootInput(input, label) {
     if (resolved.includes("\0")) {
         throw new FsSafeError("invalid-path", `${label} entry must not contain NUL bytes`);
     }
+    assertNoWindowsPathAlias(resolved, "filesystem", `${label} entry uses a Windows filesystem namespace alias`);
     if (!path.isAbsolute(resolved)) {
         throw new FsSafeError("invalid-path", `${label} entries must be absolute paths: ${input}`);
     }
-    return path.resolve(resolved);
+    const absolute = resolvePathPreservingWindowsRoot(resolved);
+    assertNoWindowsPathAlias(absolute, "filesystem", `${label} entry uses a Windows filesystem namespace alias`);
+    return absolute;
 }
 function resolveRootRealSync(rootDir) {
+    let realPath;
     try {
         // Configured roots may themselves be symlinks. Follow only this trusted
         // root entry, then use its canonical directory for containment checks.
-        const stat = fsSync.statSync(rootDir);
+        const operationPath = pathForWindowsFilesystem(rootDir);
+        const stat = fsSync.statSync(operationPath);
         if (!stat.isDirectory()) {
             return null;
         }
-        return realpathSync(rootDir);
+        realPath = realpathSync(operationPath);
     }
     catch {
         return null;
     }
+    assertNoWindowsPathAlias(realPath, "filesystem", "local root uses a Windows filesystem namespace alias");
+    return realPath;
 }
 export function resolveLocalPathFromRootsSync(options) {
     const label = options.label ?? "local roots";
-    const requestedPath = resolveLocalPathInput(options.filePath, "file path");
     const rootDirs = options.roots.map((rootEntry) => resolveLocalRootInput(rootEntry, label));
+    let requestedPath;
+    try {
+        requestedPath = resolveLocalPathInput(options.filePath, "file path");
+    }
+    catch (error) {
+        if (isWindowsPathAliasError(error))
+            return null;
+        throw error;
+    }
     for (const rootDir of rootDirs) {
         const rootReal = resolveRootRealSync(rootDir);
         if (!rootReal) {
@@ -89,7 +109,7 @@ export function resolveLocalPathFromRootsSync(options) {
             continue;
         if (candidate.exists && options.requireFile === true) {
             try {
-                if (!fsSync.lstatSync(requestedPath).isFile())
+                if (!fsSync.lstatSync(pathForWindowsFilesystem(requestedPath)).isFile())
                     continue;
             }
             catch {
@@ -103,8 +123,16 @@ export function resolveLocalPathFromRootsSync(options) {
 export async function readLocalFileFromRoots(options) {
     const maxBytes = normalizeMaxBytes(options.maxBytes);
     const label = options.label ?? "local roots";
-    const requestedPath = resolveLocalPathInput(options.filePath, "file path");
     const rootDirs = options.roots.map((rootEntry) => resolveLocalRootInput(rootEntry, label));
+    let requestedPath;
+    try {
+        requestedPath = resolveLocalPathInput(options.filePath, "file path");
+    }
+    catch (error) {
+        if (isWindowsPathAliasError(error))
+            return null;
+        throw error;
+    }
     for (const rootDir of rootDirs) {
         let scopedRoot;
         try {

package/dist/move-path-cleanup.d.ts

@@ -1,3 +1,4 @@
+import fsSync from "node:fs";
 export type EntryIdentity = {
     ctimeMs: number;
     dev: number;
@@ -12,6 +13,7 @@ export type CopiedEntryManifest = (EntryIdentity & {
         name: string;
         manifest: CopiedEntryManifest;
     }>;
+    directoryIdentity: Readonly<Pick<fsSync.BigIntStats, "dev" | "ino">>;
     kind: "directory";
 }) | (EntryIdentity & {
     kind: "leaf";

package/dist/move-path-cleanup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"move-path-cleanup.d.ts","sourceRoot":"","sources":["../src/move-path-cleanup.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAC3B,CAAC,aAAa,GAAG;IACf,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,mBAAmB,CAAA;KAAE,CAAC,CAAC;IACjE,IAAI,EAAE,WAAW,CAAC;CACnB,CAAC,GACF,CAAC,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEvC,KAAK,wBAAwB,GAAG,SAAS,GAAG,OAAO,CAAC;AAEpD,KAAK,iBAAiB,GAAG;IACvB,QAAQ,EAAE,aAAa,CAAC;IACxB,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC7C,CAAC;AAEF,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,aAAa,CAUhB;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAUxE;AAMD,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,KAAK,CAI5D;AAED,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC,CAIf;AA0BD,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,mBAAmB,GAC5B,uBAAuB,CAuBzB;AAsDD,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,uBAAuB,EAC9B,oBAAoB,EAAE,MAAM,IAAI,GAC/B,OAAO,CAAC,wBAAwB,CAAC,CAyDnC"}
+{"version":3,"file":"move-path-cleanup.d.ts","sourceRoot":"","sources":["../src/move-path-cleanup.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAM7B,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAC3B,CAAC,aAAa,GAAG;IACf,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,mBAAmB,CAAA;KAAE,CAAC,CAAC;IACjE,iBAAiB,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;IACrE,IAAI,EAAE,WAAW,CAAC;CACnB,CAAC,GACF,CAAC,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEvC,KAAK,wBAAwB,GAAG,SAAS,GAAG,OAAO,CAAC;AAEpD,KAAK,iBAAiB,GAAG;IACvB,QAAQ,EAAE,aAAa,CAAC;IACxB,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC7C,CAAC;AAEF,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,aAAa,CAUhB;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAUxE;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,KAAK,CAI5D;AAED,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC,CAIf;AA0BD,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,mBAAmB,GAC5B,uBAAuB,CAuBzB;AAsDD,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,uBAAuB,EAC9B,oBAAoB,EAAE,MAAM,IAAI,GAC/B,OAAO,CAAC,wBAAwB,CAAC,CAkFnC"}

package/dist/move-path-cleanup.js

@@ -1,6 +1,8 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
 export function entryIdentity(stat) {
     return {
         ctimeMs: stat.ctimeMs,
@@ -21,9 +23,6 @@ export function sameIdentity(a, b) {
         a.mtimeMs === b.mtimeMs &&
         a.ctimeMs === b.ctimeMs);
 }
-function sameDirectoryNode(a, b) {
-    return a.dev === b.dev && a.ino === b.ino;
-}
 export function sourceChangedError(sourcePath) {
     return Object.assign(new Error(`Source changed during move fallback: ${sourcePath}`), {
         code: "ESTALE",
@@ -113,22 +112,19 @@ function mergeCleanupResults(a, b) {
     return a === "stale" || b === "stale" ? "stale" : "removed";
 }
 export async function cleanupCopiedEntry(sourcePath, manifest, state, assertBeforeMutation) {
-    const aliasGroup = manifest.kind === "leaf" ? state.aliasGroups.get(identityKey(manifest)) : undefined;
-    if (aliasGroup?.stale) {
-        return "stale";
-    }
-    let currentStat;
-    try {
-        currentStat = fsSync.lstatSync(sourcePath);
-    }
-    catch (error) {
-        if (error?.code === "ENOENT") {
-            return aliasGroup ? poisonAliasGroup(aliasGroup) : "removed";
-        }
-        throw error;
-    }
     if (manifest.kind === "directory") {
-        if (!currentStat.isDirectory() || !sameDirectoryNode(manifest, entryIdentity(currentStat))) {
+        let currentStat;
+        try {
+            currentStat = inspectFileIdentitySync(() => fsSync.lstatSync(sourcePath, { bigint: true }), manifest.directoryIdentity);
+        }
+        catch (error) {
+            if (error?.code === "ENOENT")
+                return "removed";
+            if (error instanceof FsSafeError && error.code === "path-mismatch")
+                return "stale";
+            throw error;
+        }
+        if (!currentStat.isDirectory()) {
             return "stale";
         }
         // A same-inode directory can gain unrelated children after commit. Still
@@ -137,7 +133,23 @@ export async function cleanupCopiedEntry(sourcePath, manifest, state, assertBefo
         for (const child of manifest.children) {
             result = mergeCleanupResults(result, await cleanupCopiedEntry(path.join(sourcePath, child.name), child.manifest, state, assertBeforeMutation));
         }
+        // Child cleanup and the caller's authority check can replace the directory.
+        // Keep the final exact observation after both, immediately before removal.
         assertBeforeMutation();
+        try {
+            currentStat = inspectFileIdentitySync(() => fsSync.lstatSync(sourcePath, { bigint: true }), manifest.directoryIdentity);
+        }
+        catch (error) {
+            if (error?.code === "ENOENT") {
+                return "stale";
+            }
+            if (error instanceof FsSafeError && error.code === "path-mismatch")
+                return "stale";
+            throw error;
+        }
+        if (!currentStat.isDirectory()) {
+            return "stale";
+        }
         try {
             await fs.rmdir(sourcePath);
         }
@@ -150,6 +162,20 @@ export async function cleanupCopiedEntry(sourcePath, manifest, state, assertBefo
         }
         return result;
     }
+    const aliasGroup = state.aliasGroups.get(identityKey(manifest));
+    if (aliasGroup?.stale) {
+        return "stale";
+    }
+    let currentStat;
+    try {
+        currentStat = fsSync.lstatSync(sourcePath);
+    }
+    catch (error) {
+        if (error?.code === "ENOENT") {
+            return aliasGroup ? poisonAliasGroup(aliasGroup) : "removed";
+        }
+        throw error;
+    }
     const expected = aliasGroup?.expected ?? manifest;
     if (!sameIdentity(expected, entryIdentity(currentStat))) {
         return aliasGroup ? poisonAliasGroup(aliasGroup) : "stale";

package/dist/move-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"move-path.d.ts","sourceRoot":"","sources":["../src/move-path.ts"],"names":[],"mappings":"AAuBA,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb,CAAC,CAAC;AAEH,MAAM,MAAM,+BAA+B,GAAG;IAC5C,qFAAqF;IACrF,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,qFAAqF;IACrF,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE,0BAA0B,KAAK,IAAI,CAAC;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IACrC,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,KAAK,sBAAsB,GAAG,cAAc,GAAG,uBAAuB,CAAC;AAEvE,wBAAgB,oCAAoC,CAClD,KAAK,EAAE,OAAO,EACd,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,sBAAsB,GAAG,SAAS,CASpC;AAiRD,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAwGf"}
+{"version":3,"file":"move-path.d.ts","sourceRoot":"","sources":["../src/move-path.ts"],"names":[],"mappings":"AAyBA,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb,CAAC,CAAC;AAEH,MAAM,MAAM,+BAA+B,GAAG;IAC5C,qFAAqF;IACrF,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,qFAAqF;IACrF,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE,0BAA0B,KAAK,IAAI,CAAC;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IACrC,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,KAAK,sBAAsB,GAAG,cAAc,GAAG,uBAAuB,CAAC;AAEvE,wBAAgB,oCAAoC,CAClD,KAAK,EAAE,OAAO,EACd,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,sBAAsB,GAAG,SAAS,CASpC;AAoSD,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAoHf"}

package/dist/move-path.js

@@ -2,14 +2,16 @@ import { randomUUID } from "node:crypto";
 import fsSync, { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { createAsyncDirectoryGuard } from "./directory-guard.js";
+import { createAsyncDirectoryGuard, inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { guardedRename } from "./guarded-mutation.js";
 import { assertSourceStillMatches, cleanupCopiedEntry, createCleanupCopiedEntryState, entryIdentity, sameIdentity, sourceChangedError, } from "./move-path-cleanup.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { realpathSync } from "./realpath.js";
 import { cleanupPinnedFilePath } from "./replace-file-temp-owner.js";
 import { createMoveStageOwner } from "./move-path-stage.js";
-import { realpathSync } from "./realpath.js";
+import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export function moveCopyFallbackReasonForRenameError(error, platform = process.platform) {
     const code = error?.code;
     if (code === "EXDEV") {
@@ -176,6 +178,19 @@ async function copyRegularFilePinned(params) {
     }
     return openedIdentity;
 }
+function inspectSourceDirectory(sourcePath, expected) {
+    try {
+        return inspectDirectoryIdentitySync(sourcePath, expected);
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT" || code === "ENOTDIR" ||
+            (error instanceof FsSafeError && (error.code === "path-mismatch" || error.code === "not-file"))) {
+            throw sourceChangedError(sourcePath);
+        }
+        throw error;
+    }
+}
 async function copyEntryWithManifest(from, to, options, expectedIdentity) {
     const sourceStat = fsSync.lstatSync(from);
     const identity = entryIdentity(sourceStat);
@@ -193,6 +208,8 @@ async function copyEntryWithManifest(from, to, options, expectedIdentity) {
         return { ...identity, kind: "leaf" };
     }
     if (sourceStat.isDirectory()) {
+        const directoryStat = inspectSourceDirectory(from);
+        const directoryIdentity = Object.freeze({ dev: directoryStat.dev, ino: directoryStat.ino });
         await fs.mkdir(to, { mode: modeBits(sourceStat.mode) || 0o755 });
         options.onCreated?.(fsSync.lstatSync(to, { bigint: true }));
         const children = [];
@@ -215,10 +232,11 @@ async function copyEntryWithManifest(from, to, options, expectedIdentity) {
         // Directory traversal is path-based in Node. Treat a changed parent as a
         // stale move before committing so swapped-in outside trees are not imported.
         await assertSourceStillMatches(from, identity);
+        inspectSourceDirectory(from, directoryIdentity);
         // mkdir() honors process umask. Restore the source mode before commit so
         // EXDEV fallback preserves directory permissions like fs.cp did.
         await chmodDirectoryPinned(to, modeBits(sourceStat.mode));
-        return { ...identity, children, kind: "directory" };
+        return { ...identity, children, directoryIdentity, kind: "directory" };
     }
     if (!sourceStat.isFile()) {
         throw new Error(`Refusing to move non-file path with copy fallback: ${from}`);
@@ -244,6 +262,13 @@ function assertSynchronousResult(returned, name) {
     }
 }
 export async function movePathWithCopyFallback(options) {
+    const from = admitStandalonePublicationPath(options.from, "move source uses a Windows filesystem namespace alias");
+    const to = admitStandalonePublicationPath(options.to, "move destination uses a Windows filesystem namespace alias");
+    const sourcePath = path.resolve(from);
+    const targetPath = path.resolve(to);
+    assertNoWindowsPathAlias(sourcePath, "filesystem", "move source uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(targetPath, "filesystem", "move destination uses a Windows filesystem namespace alias");
+    const sourceHardlinks = options.sourceHardlinks;
     // Keep the initiating owner's callbacks across preparation and copy fallback.
     const callerRenameAssert = options.assertBeforeRename;
     const callerMutationAssert = options.assertBeforeMutation;
@@ -279,9 +304,7 @@ export async function movePathWithCopyFallback(options) {
             assertSynchronousResult(callerPublished?.(publicationReceipt), "onDestinationPublished");
         }
     };
-    const sourcePath = path.resolve(options.from);
-    const targetPath = path.resolve(options.to);
-    const rejectHardlinks = options.sourceHardlinks === "reject";
+    const rejectHardlinks = sourceHardlinks === "reject";
     if (rejectHardlinks) {
         await preflightSourceHardlinks(sourcePath);
     }
@@ -320,6 +343,8 @@ export async function movePathWithCopyFallback(options) {
         }, sourceIdentity);
         const cleanupState = createCleanupCopiedEntryState(sourcePath, manifest);
         await assertCopyDestinationOutsideSource(sourcePath, targetPath, manifest);
+        if (manifest.kind === "directory")
+            inspectSourceDirectory(sourcePath, manifest.directoryIdentity);
         await guardedRename({
             from: staged,
             to: targetPath,

package/dist/native-binding.d.ts

@@ -15,6 +15,11 @@ export interface NativeFileIdentity {
     isDirectory: boolean;
     isSymbolicLink: boolean;
 }
+export interface NativeDirectoryObservation {
+    dev: bigint;
+    ino: bigint;
+    realPath: string;
+}
 export interface NativeArchiveEntry {
     index: number;
     path: string;
@@ -75,12 +80,24 @@ export interface NativeWindowsSecurityFacts {
     unsupportedAceTypes: number[];
     aces: NativeWindowsAccessControlEntry[];
 }
+export interface NativeWindowsDescriptorSecurityFacts {
+    /** Canonical lowercase 32-bit volume serial and 64-bit file-index projection used by Node. */
+    identity: string;
+    security: NativeWindowsSecurityFacts;
+}
+export interface NativeDarwinAclFacts {
+    state: "absent" | "empty" | "present";
+}
 export interface NativeBinding {
+    /** Internal Darwin-only synchronous inspection; the caller retains its fd. */
+    inspectDarwinAcl?(fd: number): NativeDarwinAclFacts;
     /** POSIX system canonicalization; confinement and identity policy stay with callers. */
     canonicalizePath?(path: string, ordinary: boolean): {
         path?: string;
         errno?: number;
     };
+    /** Internal: exact directory identity and canonical path from one no-follow handle. */
+    observeDirectory?(path: string): NativeDirectoryObservation;
     /** Linux/Windows byte transfer; callers retain both admitted descriptors until settlement. */
     copyFileContents?(sourceFd: number, targetFd: number, signal?: AbortSignal): Promise<void>;
     /** Internal: same private, immutable input ownership as the ZIP buffer reader. */
@@ -107,10 +124,14 @@ export interface NativeBinding {
     fstatIdentity(fd: number): NativeFileIdentity;
     inspectArchiveNative(path: string, kind: string, limits: TarMeterLimits, signal: AbortSignal): Promise<NativeArchiveEntry[]>;
     linkBeneath(sourceRootFd: number, sourceRelPath: string, targetRootFd: number, targetRelPath: string): void;
+    /** Direct-child mkdir; true is receipt provenance only, never cleanup ownership. */
+    mkdirChildBeneath?(parentFd: number, basename: string, mode: number): boolean;
     mkdirBeneath(rootFd: number, relPath: string, mode: number): void;
     openBeneath(rootFd: number, relPath: string, flags: number): NativeOpenBeneathResult;
     readArchiveEntryNative(path: string, kind: string, requested: string, maxBytes: number, limits: TarMeterLimits, signal: AbortSignal): Promise<Buffer>;
     readOwnerAndDacl(path: string): NativeWindowsSecurityFacts;
+    /** Internal Windows-only inspection of the exact borrowed Node descriptor. */
+    inspectWindowsSecureFileHandle?(fd: number): NativeWindowsDescriptorSecurityFacts;
     ownedTreeRemovalAvailable?(parentFd: number): boolean;
     removeOwnedTree?(parentFd: number, basename: string, directoryFd: number): Promise<NativeOwnedTreeRemovalResult>;
     removeOwnedTreeSync?(parentFd: number, basename: string, directoryFd: number): NativeOwnedTreeRemovalResult;

package/dist/native-binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-binding.d.ts","sourceRoot":"","sources":["../src/native-binding.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"native-binding.d.ts","sourceRoot":"","sources":["../src/native-binding.ts"],"names":[],"mappings":"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"}

package/dist/native-directory-observation.d.ts

@@ -0,0 +1,17 @@
+import { type NativeBinding } from "./native.js";
+import type { NativeDirectoryObservation } from "./native-binding.js";
+import type { ExactStatIdentity } from "./stat-observation.js";
+export type NativeDirectoryObservationBackend = NativeBinding & {
+    observeDirectory(pathname: string): NativeDirectoryObservation;
+};
+export type NativeDirectoryObservationGuard = NativeDirectoryObservation & {
+    dir: string;
+    identity: ExactStatIdentity;
+    nativeDirectoryObservation: true;
+};
+export declare function getNativeDirectoryObservationBackend(enabled?: boolean): NativeDirectoryObservationBackend | undefined;
+/** Exact identity, type, and canonical path captured from one retained handle. */
+export declare function inspectNativeDirectoryObservation(backend: NativeDirectoryObservationBackend, pathname: string, expected?: ExactStatIdentity, platform?: NodeJS.Platform): NativeDirectoryObservation;
+export declare function extendNativeDirectoryObservationGuard(observation: NativeDirectoryObservation, dir: string): NativeDirectoryObservationGuard;
+export declare function isNativeDirectoryObservationGuard(guard: unknown): guard is NativeDirectoryObservationGuard;
+//# sourceMappingURL=native-directory-observation.d.ts.map

package/dist/native-directory-observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-directory-observation.d.ts","sourceRoot":"","sources":["../src/native-directory-observation.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAEtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,MAAM,MAAM,iCAAiC,GAAG,aAAa,GAAG;IAC9D,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,0BAA0B,CAAC;CAChE,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG,0BAA0B,GAAG;IACzE,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,0BAA0B,EAAE,IAAI,CAAC;CAClC,CAAC;AAEF,wBAAgB,oCAAoC,CAClD,OAAO,UAAO,GACb,iCAAiC,GAAG,SAAS,CAM/C;AAeD,kFAAkF;AAClF,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,iCAAiC,EAC1C,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,0BAA0B,CAM5B;AAED,wBAAgB,qCAAqC,CACnD,WAAW,EAAE,0BAA0B,EACvC,GAAG,EAAE,MAAM,GACV,+BAA+B,CAMjC;AAED,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,+BAA+B,CAG1C"}

package/dist/native-directory-observation.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+export function getNativeDirectoryObservationBackend(enabled = true) {
+    if (!enabled)
+        return undefined;
+    const binding = getNativeBinding();
+    return binding && typeof binding.observeDirectory === "function"
+        ? binding
+        : undefined;
+}
+function validateNativeDirectoryObservation(observation) {
+    if (!observation || typeof observation.dev !== "bigint" || observation.dev < 0n ||
+        typeof observation.ino !== "bigint" || observation.ino < 0n ||
+        typeof observation.realPath !== "string" ||
+        observation.realPath.includes("\0") ||
+        (!path.isAbsolute(observation.realPath) && !path.win32.isAbsolute(observation.realPath))) {
+        throw new FsSafeError("path-mismatch", "native directory observation is invalid");
+    }
+    return observation;
+}
+/** Exact identity, type, and canonical path captured from one retained handle. */
+export function inspectNativeDirectoryObservation(backend, pathname, expected, platform = process.platform) {
+    return inspectFileIdentitySync(() => validateNativeDirectoryObservation(backend.observeDirectory(pathname)), expected, platform);
+}
+export function extendNativeDirectoryObservationGuard(observation, dir) {
+    const guard = observation;
+    guard.dir = dir;
+    guard.identity = guard;
+    guard.nativeDirectoryObservation = true;
+    return guard;
+}
+export function isNativeDirectoryObservationGuard(guard) {
+    return typeof guard === "object" && guard !== null &&
+        guard.nativeDirectoryObservation === true;
+}

package/dist/native-parent-admission.d.ts

@@ -0,0 +1,31 @@
+import { type BigIntStats, type Stats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import type { FileIdentityStat } from "./file-identity.js";
+import type { NativeBinding } from "./native.js";
+import { describeStagedDirectory } from "./staged-directory.js";
+type RootIdentity = Pick<FileIdentityStat, "dev" | "ino">;
+export type NativeRootAdmission = {
+    exactRoot: boolean;
+    operation: string;
+    root: FileHandle;
+    rootPath: string;
+};
+export type NativeParentAdmission = {
+    fd: number;
+    guard: {
+        dir: string;
+        realPath: string;
+        stat: Stats | BigIntStats;
+    };
+    stagedDirectory?: ReturnType<typeof describeStagedDirectory>;
+};
+export declare function sameNativeIdentity(left: RootIdentity, right: RootIdentity): boolean;
+export declare function openNativeRootAdmission(binding: NativeBinding, params: {
+    rootPath: string;
+    rootIdentity?: RootIdentity;
+    operation?: string;
+}): Promise<NativeRootAdmission>;
+export declare function openNativeParentAdmission(binding: NativeBinding, rootAdmission: NativeRootAdmission, relativeParentPath: string): Promise<NativeParentAdmission>;
+export declare function closeNativeParentAdmission(admission: NativeParentAdmission | undefined): void;
+export {};
+//# sourceMappingURL=native-parent-admission.d.ts.map

package/dist/native-parent-admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-parent-admission.d.ts","sourceRoot":"","sources":["../src/native-parent-admission.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAwB,MAAM,uBAAuB,CAAC;AAKtF,KAAK,YAAY,GAAG,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;AAE1D,MAAM,MAAM,mBAAmB,GAAG;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,GAAG,WAAW,CAAA;KAAE,CAAC;IACpE,eAAe,CAAC,EAAE,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAC;CAC9D,CAAC;AAEF,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,YAAY,GAClB,OAAO,CAET;AAYD,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5E,OAAO,CAAC,mBAAmB,CAAC,CAgD9B;AAED,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,aAAa,EACtB,aAAa,EAAE,mBAAmB,EAClC,kBAAkB,EAAE,MAAM,GACzB,OAAO,CAAC,qBAAqB,CAAC,CA6DhC;AAED,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,qBAAqB,GAAG,SAAS,GAAG,IAAI,CAE7F"}

package/dist/native-parent-admission.js

@@ -0,0 +1,124 @@
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { inspectDirectoryIdentity } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { realpathSync } from "./realpath.js";
+import { describeStagedDirectory, exactIdentityMatches } from "./staged-directory.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem } from "./windows-path-alias.js";
+export function sameNativeIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function unavailable(message) {
+    return new FsSafeError("helper-unavailable", message);
+}
+function assertParentAdmissionAvailable(binding) {
+    if (typeof binding.openBeneath !== "function") {
+        throw unavailable("native parent directory admission is unavailable");
+    }
+}
+export async function openNativeRootAdmission(binding, params) {
+    assertParentAdmissionAvailable(binding);
+    const directoryFlags = fsSync.constants.O_RDONLY | (fsSync.constants.O_DIRECTORY ?? 0);
+    assertNoWindowsPathAlias(params.rootPath, "filesystem", "native root uses a Windows filesystem namespace alias");
+    const root = await fs.open(pathForWindowsFilesystem(params.rootPath), directoryFlags);
+    try {
+        const exactRoot = typeof params.rootIdentity?.dev === "bigint" &&
+            typeof params.rootIdentity.ino === "bigint";
+        let rootMatches;
+        if (exactRoot) {
+            inspectFileIdentitySync(() => fsSync.fstatSync(root.fd, { bigint: true }), params.rootIdentity);
+            rootMatches = true;
+        }
+        else if (process.platform === "win32") {
+            if (typeof binding.fstatIdentity !== "function") {
+                throw unavailable("native root directory identity checks are unavailable");
+            }
+            const identity = binding.fstatIdentity(root.fd);
+            rootMatches = !params.rootIdentity || sameNativeIdentity(params.rootIdentity, identity);
+        }
+        else {
+            const identity = fsSync.fstatSync(root.fd, { bigint: true });
+            rootMatches = !params.rootIdentity || exactIdentityMatches(params.rootIdentity, identity);
+        }
+        if (!rootMatches) {
+            throw new FsSafeError("path-mismatch", `root path changed during ${params.operation ?? "native admission"}`);
+        }
+        return {
+            exactRoot,
+            operation: params.operation ?? "native admission",
+            root,
+            rootPath: params.rootPath,
+        };
+    }
+    catch (error) {
+        try {
+            await root.close();
+        }
+        catch (closeError) {
+            // Windows admission keeps the typed boundary failure primary.
+            if (process.platform !== "win32") {
+                throw createSuppressedError(closeError, error, "native root admission and close failed");
+            }
+        }
+        throw error;
+    }
+}
+export async function openNativeParentAdmission(binding, rootAdmission, relativeParentPath) {
+    assertParentAdmissionAvailable(binding);
+    const directoryFlags = fsSync.constants.O_RDONLY | (fsSync.constants.O_DIRECTORY ?? 0);
+    assertNoWindowsPathAlias(relativeParentPath, "relative", "native parent uses a Windows filesystem namespace alias");
+    const opened = binding.openBeneath(rootAdmission.root.fd, relativeParentPath, directoryFlags);
+    if (!opened || !Number.isInteger(opened.fd) || opened.fd < 0) {
+        throw unavailable("native parent directory admission did not provide a descriptor");
+    }
+    const parentFd = opened.fd;
+    try {
+        const parentInput = relativeParentPath
+            ? path.join(rootAdmission.rootPath, ...relativeParentPath.split("/"))
+            : rootAdmission.rootPath;
+        const parentPath = realpathSync.native(pathForWindowsFilesystem(parentInput));
+        assertNoWindowsPathAlias(parentPath, "filesystem", "native parent uses a Windows filesystem namespace alias");
+        const stagedDirectory = process.platform === "win32"
+            ? undefined
+            : describeStagedDirectory(parentFd, parentPath);
+        const parentPathStat = rootAdmission.exactRoot
+            ? await inspectDirectoryIdentity(parentPath, inspectFileIdentitySync(() => fsSync.fstatSync(parentFd, { bigint: true })))
+            : fsSync.lstatSync(pathForWindowsFilesystem(parentPath));
+        if (process.platform === "win32" && !rootAdmission.exactRoot) {
+            if (typeof binding.fstatIdentity !== "function") {
+                throw unavailable("native parent directory identity checks are unavailable");
+            }
+            const parentIdentity = binding.fstatIdentity(parentFd);
+            if (parentPathStat.isSymbolicLink() || !sameNativeIdentity(parentPathStat, parentIdentity)) {
+                throw new FsSafeError("path-mismatch", `${rootAdmission.operation} parent changed during resolution`);
+            }
+        }
+        else if (process.platform !== "win32" &&
+            (parentPathStat.isSymbolicLink() || !exactIdentityMatches(parentPathStat, stagedDirectory.identity))) {
+            throw new FsSafeError("path-mismatch", `${rootAdmission.operation} parent changed during resolution`);
+        }
+        return {
+            fd: parentFd,
+            guard: { dir: parentPath, realPath: parentPath, stat: parentPathStat },
+            stagedDirectory,
+        };
+    }
+    catch (error) {
+        try {
+            fsSync.closeSync(parentFd);
+        }
+        catch (closeError) {
+            if (process.platform !== "win32") {
+                throw createSuppressedError(closeError, error, "native parent admission and close failed");
+            }
+        }
+        throw error;
+    }
+}
+export function closeNativeParentAdmission(admission) {
+    if (admission)
+        fsSync.closeSync(admission.fd);
+}

package/dist/native-pinned-write-windows.d.ts

@@ -3,6 +3,5 @@ import type { AnyAsyncDirectoryGuard } from "./directory-guard.js";
 import type { FileIdentityStat } from "./file-identity.js";
 import type { NativeBinding } from "./native.js";
 import type { PinnedWriteParams } from "./pinned-write.js";
-export declare function sameNativeIdentity(left: Pick<FileIdentityStat, "dev" | "ino">, right: Pick<FileIdentityStat, "dev" | "ino">): boolean;
 export declare function runPinnedWriteWindows(binding: NativeBinding, params: PinnedWriteParams, root: FileHandle, parentFd: number, parentGuard: AnyAsyncDirectoryGuard): Promise<FileIdentityStat>;
 //# sourceMappingURL=native-pinned-write-windows.d.ts.map

package/dist/native-pinned-write-windows.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-pinned-write-windows.d.ts","sourceRoot":"","sources":["../src/native-pinned-write-windows.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAEnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAM3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAI3D,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,KAAK,CAAC,EAC3C,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,KAAK,CAAC,GAC3C,OAAO,CAET;AAWD,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,sBAAsB,GAClC,OAAO,CAAC,gBAAgB,CAAC,CA0F3B"}
+{"version":3,"file":"native-pinned-write-windows.d.ts","sourceRoot":"","sources":["../src/native-pinned-write-windows.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAEnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAM3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAa3D,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,sBAAsB,GAClC,OAAO,CAAC,gBAAgB,CAAC,CA0F3B"}