@openclaw/fs-safe 0.12.0 → 0.13.0

package/dist/json-durable-queue.js

@@ -2,21 +2,27 @@ import fs, {} from "node:fs";
 import path from "node:path";
 import { syncDirectory } from "./directory-durability.js";
 import { syncQueueDirectoryCreation } from "./json-durable-queue-directory.js";
-import { getErrorCode, acknowledgeDurableQueueEntry, claimDurableQueueEntry, completeDeliveredQueueEntry, migrateDurableQueueEntry, moveDurableQueueEntryToFailed, } from "./json-durable-queue-ownership.js";
+import { queueValidationRoot, queueValidationRoots, resolveQueueFilesystemPath, } from "./json-durable-queue-paths.js";
+import { getErrorCode, acknowledgeDurableQueueEntry, claimDurableQueueEntry, completeDeliveredQueueEntry, migrateDurableQueueEntry, moveDurableQueueEntryToFailed, validateDurableQueueEntryPaths, } from "./json-durable-queue-ownership.js";
 import { withJsonDurableQueueEntry } from "./json-durable-queue-read.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
 import { realpathSync } from "./realpath.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { replaceFileAtomicWithDirectorySync } from "./replace-file.js";
 import { assertSafePathSegment } from "./safe-path-segment.js";
+import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
+import { assertNoWindowsPathAlias, hasWindowsPathAlias, } from "./windows-path-alias.js";
 export { DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES } from "./json-durable-queue-read.js";
 function assertSafeQueueEntryId(id) {
     assertSafePathSegment(id, { label: "queue entry id" });
 }
 export async function unlinkBestEffort(filePath) {
+    if (hasWindowsPathAlias(filePath, "filesystem"))
+        return;
     await fs.promises.unlink(filePath).catch(() => undefined);
 }
 export async function jsonDurableQueueEntryExists(filePath) {
+    assertNoWindowsPathAlias(filePath);
     try {
         const stat = fs.lstatSync(filePath);
         return stat.isFile();
@@ -43,6 +49,7 @@ async function unlinkStaleTmpBestEffort(filePath, now, maxAgeMs) {
 }
 export function resolveJsonDurableQueueEntryPaths(queueDir, id) {
     assertSafeQueueEntryId(id);
+    assertNoWindowsPathAlias(queueDir);
     return {
         jsonPath: path.join(queueDir, `${id}.json`),
         deliveredPath: path.join(queueDir, `${id}.delivered`),
@@ -50,9 +57,13 @@ export function resolveJsonDurableQueueEntryPaths(queueDir, id) {
     };
 }
 export async function ensureJsonDurableQueueDirs(params) {
-    const roots = await queueValidationRoots(params.queueDir, params.failedDir);
-    await ensureJsonDurableQueueDir(params.queueDir, roots.queueRoot);
-    await ensureJsonDurableQueueDir(params.failedDir, roots.failedRoot);
+    const queueDir = params.queueDir;
+    const failedDir = params.failedDir;
+    assertNoWindowsPathAlias(queueDir);
+    assertNoWindowsPathAlias(failedDir);
+    const roots = await queueValidationRoots(queueDir, failedDir);
+    await ensureJsonDurableQueueDir(queueDir, roots.queueRoot);
+    await ensureJsonDurableQueueDir(failedDir, roots.failedRoot);
 }
 async function ensureJsonDurableQueueDir(dir, validationRoot) {
     const root = validationRoot
@@ -70,41 +81,6 @@ async function assertJsonDurableQueueDir(dir, validationRoot) {
         : queueValidationRoot(dir);
     await assertNoSymlinkDirectorySegments(root, dir, false);
 }
-function commonPathAncestor(paths) {
-    const resolved = paths.map((entry) => path.resolve(entry));
-    const root = path.parse(resolved[0] ?? process.cwd()).root;
-    const parts = resolved.map((entry) => path.relative(root, entry).split(path.sep));
-    const common = [];
-    for (let index = 0; parts.every((part) => index < part.length); index++) {
-        const segment = parts[0]?.[index];
-        if (!segment || !parts.every((part) => part[index] === segment))
-            break;
-        common.push(segment);
-    }
-    return path.join(root, ...common);
-}
-function samePathRoot(paths) {
-    const roots = paths.map((entry) => path.parse(path.resolve(entry)).root);
-    const first = process.platform === "win32" ? roots[0]?.toLowerCase() : roots[0];
-    return roots.every((root) => (process.platform === "win32" ? root.toLowerCase() : root) === first);
-}
-async function queueValidationRoots(queueDir, failedDir) {
-    if (samePathRoot([queueDir, failedDir])) {
-        const common = commonPathAncestor([queueDir, failedDir]);
-        const root = queueValidationRoot(common);
-        return { failedRoot: root, queueRoot: root };
-    }
-    return {
-        failedRoot: queueValidationRoot(failedDir),
-        queueRoot: queueValidationRoot(queueDir),
-    };
-}
-function queueValidationRoot(dir) {
-    return {
-        path: path.parse(path.resolve(dir)).root,
-        allowSymlinkBase: process.platform === "darwin",
-    };
-}
 async function isDarwinSystemAlias(dir, stat) {
     if (process.platform !== "darwin" || !stat.isSymbolicLink()) {
         return false;
@@ -121,8 +97,8 @@ async function isDarwinSystemAlias(dir, stat) {
     }
 }
 async function assertNoSymlinkDirectorySegments(validationRoot, dir, allowMissing) {
-    let base = path.resolve(validationRoot.path);
-    let target = path.resolve(dir);
+    let base = resolveQueueFilesystemPath(validationRoot.path);
+    let target = resolveQueueFilesystemPath(dir);
     let current = base;
     let baseStat = fs.lstatSync(base);
     if (baseStat.isSymbolicLink() && validationRoot.allowSymlinkBase) {
@@ -213,11 +189,14 @@ export async function writeJsonDurableQueueEntry(params) {
     await writeQueueEntry(params);
 }
 async function writeQueueEntry(params, beforeRename) {
+    const filePath = admitStandalonePublicationPath(params.filePath);
+    const entry = params.entry;
+    const tempPrefix = params.tempPrefix;
     await replaceFileAtomicWithDirectorySync({
-        filePath: params.filePath,
-        content: stringifyJsonDocument(params.entry, null, 2),
+        filePath,
+        content: stringifyJsonDocument(entry, null, 2),
         mode: 0o600,
-        tempPrefix: params.tempPrefix,
+        tempPrefix,
         syncTempFile: true,
         beforeRename,
     }, syncDirectory);
@@ -235,16 +214,19 @@ export async function ackJsonDurableQueueEntry(paths) {
 }
 export async function loadJsonDurableQueueEntry(params) {
     try {
-        const claimedPath = await claimDurableQueueEntry(params.paths);
+        const pathsInput = params.paths;
+        const paths = validateDurableQueueEntryPaths(pathsInput);
+        const claimedPath = await claimDurableQueueEntry(paths);
         if (!claimedPath)
             return null;
         return await withJsonDurableQueueEntry(claimedPath, {
             maxBytes: params.maxBytes,
         }, async (raw, identity, releaseReadPin) => {
-            const result = params.read ? await params.read(raw, params.paths.jsonPath) : { entry: raw };
+            const read = params.read;
+            const result = read ? await Reflect.apply(read, params, [raw, paths.jsonPath]) : { entry: raw };
             if (result.migrated) {
                 await migrateClaimedQueueEntry({
-                    paths: params.paths, identity, releaseReadPin, entry: result.entry, tempPrefix: params.tempPrefix,
+                    paths, identity, releaseReadPin, entry: result.entry, tempPrefix: params.tempPrefix,
                 });
             }
             return result.entry;
@@ -258,9 +240,11 @@ export async function loadJsonDurableQueueEntry(params) {
     }
 }
 export async function loadPendingJsonDurableQueueEntries(options) {
+    const queueDir = options.queueDir;
+    assertNoWindowsPathAlias(queueDir);
     let files;
     try {
-        files = await fs.promises.readdir(options.queueDir);
+        files = await fs.promises.readdir(queueDir);
     }
     catch (error) {
         if (getErrorCode(error) === "ENOENT") {
@@ -278,10 +262,11 @@ export async function loadPendingJsonDurableQueueEntries(options) {
             catch {
                 continue;
             }
-            await completeDeliveredQueueEntry(resolveJsonDurableQueueEntryPaths(options.queueDir, id));
+            const paths = validateDurableQueueEntryPaths(resolveJsonDurableQueueEntryPaths(queueDir, id));
+            await completeDeliveredQueueEntry(paths);
         }
         else if (options.cleanupTmpMaxAgeMs !== undefined && file.endsWith(".tmp")) {
-            await unlinkStaleTmpBestEffort(path.join(options.queueDir, file), now, options.cleanupTmpMaxAgeMs);
+            await unlinkStaleTmpBestEffort(path.join(queueDir, file), now, options.cleanupTmpMaxAgeMs);
         }
     }
     const ids = [];
@@ -308,14 +293,15 @@ export async function loadPendingJsonDurableQueueEntries(options) {
     }
     const entries = [];
     for (const id of ids) {
-        const paths = resolveJsonDurableQueueEntryPaths(options.queueDir, id);
+        const paths = validateDurableQueueEntryPaths(resolveJsonDurableQueueEntryPaths(queueDir, id));
         const claimedPath = await claimDurableQueueEntry(paths, { skipUnowned: true });
         if (!claimedPath)
             continue;
         let migrationStarted = false;
         try {
             const entry = await withJsonDurableQueueEntry(claimedPath, { maxBytes: options.maxBytes }, async (raw, identity, releaseReadPin) => {
-                const result = options.read ? await options.read(raw, paths.jsonPath) : { entry: raw };
+                const read = options.read;
+                const result = read ? await Reflect.apply(read, options, [raw, paths.jsonPath]) : { entry: raw };
                 if (result.migrated) {
                     migrationStarted = true;
                     await migrateClaimedQueueEntry({
@@ -335,12 +321,18 @@ export async function loadPendingJsonDurableQueueEntries(options) {
     return entries;
 }
 export async function moveJsonDurableQueueEntryToFailed(params) {
-    assertSafeQueueEntryId(params.id);
-    const roots = await queueValidationRoots(params.queueDir, params.failedDir);
-    await assertJsonDurableQueueDir(params.queueDir, roots.queueRoot);
-    await ensureJsonDurableQueueDir(params.failedDir, roots.failedRoot);
+    const id = params.id;
+    const queueDir = params.queueDir;
+    const failedDir = params.failedDir;
+    assertSafeQueueEntryId(id);
+    assertNoWindowsPathAlias(queueDir);
+    assertNoWindowsPathAlias(failedDir);
+    const roots = await queueValidationRoots(queueDir, failedDir);
+    await assertJsonDurableQueueDir(queueDir, roots.queueRoot);
+    await ensureJsonDurableQueueDir(failedDir, roots.failedRoot);
+    const paths = validateDurableQueueEntryPaths(resolveJsonDurableQueueEntryPaths(queueDir, id));
     await moveDurableQueueEntryToFailed({
-        paths: resolveJsonDurableQueueEntryPaths(params.queueDir, params.id),
-        failedPath: path.join(params.failedDir, `${params.id}.json`),
+        paths,
+        failedPath: path.join(failedDir, `${id}.json`),
     });
 }

package/dist/json-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-store.d.ts","sourceRoot":"","sources":["../src/json-store.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,SAAS,EACd,KAAK,oBAAoB,EAC1B,MAAM,0BAA0B,CAAC;AAElC,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,oBAAoB,GAAG;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,YAAY,EAAE,oBAAoB,EAAE,SAAS,EAAE,oBAAoB,EAAE,CAAC;AAEtE,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAQvE"}
+{"version":3,"file":"json-store.d.ts","sourceRoot":"","sources":["../src/json-store.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,SAAS,EACd,KAAK,oBAAoB,EAC1B,MAAM,0BAA0B,CAAC;AAIlC,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,oBAAoB,GAAG;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,YAAY,EAAE,oBAAoB,EAAE,SAAS,EAAE,oBAAoB,EAAE,CAAC;AAEtE,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAUvE"}

package/dist/json-store.js

@@ -1,8 +1,12 @@
 import path from "node:path";
 import { fileStore } from "./file-store.js";
 import {} from "./json-document-store.js";
+import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export function jsonStore(options) {
-    const filePath = path.resolve(options.filePath);
+    const filePathInput = admitStandalonePublicationPath(options.filePath);
+    const filePath = path.resolve(filePathInput);
+    assertNoWindowsPathAlias(filePath);
     return fileStore({
         rootDir: path.dirname(filePath),
         private: true,

package/dist/json.d.ts.map

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

package/dist/json.js

@@ -9,8 +9,10 @@ import { readRegularFile, readRegularFileSync, statRegularFile } from "./regular
 import { openRootFileSync } from "./root-file.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
 import { writeTextAtomic } from "./text-atomic.js";
 import { sleep } from "./timing.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 const READ_RETRY_MAX_ATTEMPTS = 5;
 const READ_RETRY_BASE_DELAY_MS = 50;
 function isRetryableReadError(err, options) {
@@ -167,16 +169,17 @@ export function tryReadJsonSync(pathname, options = {}) {
     }
 }
 export function writeJsonSync(pathname, data) {
+    const filePath = admitStandalonePublicationPath(pathname);
     // Keep literal parent segments so staging follows the same symlinks as the target.
-    const tmpPath = path.format({ ...path.parse(pathname), base: `.fs-safe-${randomUUID()}.tmp` });
+    const tmpPath = path.format({ ...path.parse(filePath), base: `.fs-safe-${randomUUID()}.tmp` });
     const payload = `${stringifyJsonDocument(data, null, 2)}\n`;
-    fsSync.mkdirSync(recursiveMkdirPath(path.dirname(pathname)), { recursive: true, mode: JSON_DIR_MODE });
+    fsSync.mkdirSync(recursiveMkdirPath(path.dirname(filePath)), { recursive: true, mode: JSON_DIR_MODE });
     try {
         const tempIdentity = writeTempJsonFile(tmpPath, payload);
         trySetSecureMode(tmpPath, tempIdentity);
-        renameJsonFileWithFallback(tmpPath, pathname);
-        trySetSecureMode(pathname, tempIdentity);
-        trySyncDirectory(pathname);
+        renameJsonFileWithFallback(tmpPath, filePath);
+        trySetSecureMode(filePath, tempIdentity);
+        trySyncDirectory(filePath);
     }
     finally {
         try {
@@ -207,29 +210,59 @@ function resolveInvalidMessage(invalidMessage, relativePath) {
     return invalidMessage ?? `${relativePath} has an unexpected shape`;
 }
 export function readRootStructuredFileSync(options) {
-    const absolutePath = path.resolve(options.rootDir, options.relativePath);
+    return readRootStructuredFileSyncInternal(options, options);
+}
+function readRootStructuredFileSyncInternal(options, parser) {
+    let absolutePath;
+    let relativePath;
+    let rootDir;
+    let rootRealPath;
+    try {
+        rootDir = options.rootDir;
+        relativePath = options.relativePath;
+        rootRealPath = options.rootRealPath;
+        assertNoWindowsPathAlias(rootDir);
+        assertNoWindowsPathAlias(relativePath, "relative");
+        if (rootRealPath !== undefined) {
+            assertNoWindowsPathAlias(rootRealPath);
+        }
+        absolutePath = path.resolve(rootDir, relativePath);
+        assertNoWindowsPathAlias(absolutePath);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "open",
+            failure: { ok: false, reason: "validation", error },
+        };
+    }
+    const boundaryLabel = options.boundaryLabel;
+    const rejectHardlinks = options.rejectHardlinks;
+    const maxBytes = options.maxBytes;
     const opened = openRootFileSync({
         absolutePath,
-        rootPath: options.rootDir,
-        ...(options.rootRealPath !== undefined ? { rootRealPath: options.rootRealPath } : {}),
-        boundaryLabel: options.boundaryLabel,
-        rejectHardlinks: options.rejectHardlinks,
-        maxBytes: options.maxBytes,
+        rootPath: rootDir,
+        rootRealPath,
+        boundaryLabel,
+        rejectHardlinks,
+        maxBytes,
         allowedType: "file",
     });
     if (!opened.ok) {
         return { ok: false, reason: "open", failure: opened };
     }
     try {
-        const raw = options.maxBytes === undefined
+        const raw = maxBytes === undefined
             ? fsSync.readFileSync(opened.fd, "utf8")
-            : readFileDescriptorBoundedSync(opened.fd, options.maxBytes).toString("utf8");
-        const parsed = options.parse(raw);
-        if (options.validate && !options.validate(parsed)) {
+            : readFileDescriptorBoundedSync(opened.fd, maxBytes).toString("utf8");
+        const parse = parser.parse;
+        const parsed = Reflect.apply(parse, parser, [raw]);
+        const validate = parser.validate;
+        if (validate && !Reflect.apply(validate, parser, [parsed])) {
             return {
                 ok: false,
                 reason: "invalid",
-                error: resolveInvalidMessage(options.invalidMessage, options.relativePath),
+                error: resolveInvalidMessage(parser.invalidMessage, relativePath),
             };
         }
         return {
@@ -244,7 +277,7 @@ export function readRootStructuredFileSync(options) {
         return {
             ok: false,
             reason: "parse",
-            error: `failed to parse ${options.relativePath}: ${String(error)}`,
+            error: `failed to parse ${relativePath}: ${String(error)}`,
         };
     }
     finally {
@@ -252,14 +285,12 @@ export function readRootStructuredFileSync(options) {
     }
 }
 export function readRootJsonSync(options) {
-    return readRootStructuredFileSync({
-        ...options,
+    return readRootStructuredFileSyncInternal(options, {
         parse: (raw) => JSON.parse(raw),
     });
 }
 export function readRootJsonObjectSync(options) {
-    return readRootStructuredFileSync({
-        ...options,
+    return readRootStructuredFileSyncInternal(options, {
         parse: (raw) => JSON.parse(raw),
         validate: isRecord,
         invalidMessage: (relativePath) => `${relativePath} must contain a JSON object`,
@@ -334,8 +365,9 @@ export function readJsonSync(filePath, options = {}) {
     }
 }
 export async function writeJson(filePath, value, options) {
+    const admittedPath = admitStandalonePublicationPath(filePath);
     const text = stringifyJsonDocument(value, null, 2);
-    await writeTextAtomic(filePath, text, {
+    await writeTextAtomic(admittedPath, text, {
         mode: options?.mode,
         dirMode: options?.dirMode,
         trailingNewline: options?.trailingNewline,

package/dist/local-file-access.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-file-access.d.ts","sourceRoot":"","sources":["../src/local-file-access.ts"],"names":[],"mappings":"AAOA,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEhD;AAOD,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAeT;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAET;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,SAAS,GAAG,IAAI,CAIjF;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,MAAM,CAqBR;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,MAAM,GAAG,SAAS,CAMpB;AAED,wBAAgB,uBAAuB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgB3E"}
+{"version":3,"file":"local-file-access.d.ts","sourceRoot":"","sources":["../src/local-file-access.ts"],"names":[],"mappings":"AAQA,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEhD;AAOD,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAeT;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAET;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,SAAS,GAAG,IAAI,CAIjF;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,MAAM,CAwBR;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,MAAM,GAAG,SAAS,CAMpB;AAED,wBAAgB,uBAAuB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgB3E"}

package/dist/local-file-access.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { fileURLToPath, URL } from "node:url";
 import { normalizeLowercaseStringOrEmpty } from "./string-coerce.js";
+import { hasWindowsPathAlias } from "./windows-path-alias.js";
 const ENCODED_FILE_URL_SEPARATOR_RE = /%(?:2f|5c)/i;
 const FILE_URL_PREFIX_RE = /^file:\/\//i;
 export function isFileUrl(input) {
@@ -54,6 +55,9 @@ export function safeFileURLToPath(fileUrl, platform = process.platform) {
         throw new Error(`file:// URLs cannot encode path separators: ${fileUrl}`);
     }
     const filePath = fileURLToPath(parsed, { windows: platform === "win32" });
+    if (hasWindowsPathAlias(filePath, "filesystem", platform)) {
+        throw new Error(`Local file URL cannot use Windows filesystem namespace aliases: ${filePath}`);
+    }
     if (isWindowsNetworkPath(filePath, platform)) {
         throw new Error(`Local file URL cannot use Windows network paths: ${filePath}`);
     }

package/dist/local-file-descriptor.d.ts

@@ -0,0 +1,17 @@
+import type { BigIntStats, Stats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import type { HardlinkPolicy } from "./root-options.js";
+import type { SymlinkPolicy } from "./root-symlink-policy.js";
+type OwnedLocalFile = {
+    handle: FileHandle;
+    stat: Stats;
+    identity: BigIntStats;
+    preOpenStat: BigIntStats | undefined;
+};
+export declare function openLocalFileDescriptor(filePath: string, options?: {
+    hardlinks?: HardlinkPolicy;
+    symlinks?: SymlinkPolicy;
+    readWrite?: true;
+}): Promise<OwnedLocalFile>;
+export {};
+//# sourceMappingURL=local-file-descriptor.d.ts.map

package/dist/local-file-descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-file-descriptor.d.ts","sourceRoot":"","sources":["../src/local-file-descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAElD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAYnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAO9D,KAAK,cAAc,GAAG;IACpB,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,KAAK,CAAC;IACZ,QAAQ,EAAE,WAAW,CAAC;IACtB,WAAW,EAAE,WAAW,GAAG,SAAS,CAAC;CACtC,CAAC;AAIF,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB,GACA,OAAO,CAAC,cAAc,CAAC,CA0EzB"}

package/dist/local-file-descriptor.js

@@ -0,0 +1,84 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
+import { recordFileOpenFailure, recordPreOpenFileChange } from "./opened-file-failure.js";
+import { assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isSymlinkOpenError, } from "./path.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { fileNotFoundError, hardlinkedPathNotAllowedError } from "./root-errors.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+const OPEN_READ_FLAGS = resolveReadOpenFlags();
+const OPEN_READ_FOLLOW_FLAGS = resolveReadOpenFlags({ followSymlinks: true });
+// Ownership transfers only after descriptor verification. Each admission caller
+// must close on rejection and construct an OpenResult only after admission.
+export async function openLocalFileDescriptor(filePath, options) {
+    assertNoUnsafeDeviceReadPath(filePath);
+    const fsSafeTestHooks = getFsSafeTestHooks();
+    let preOpenStat;
+    let observedBeforeOpen = false;
+    // Reject directories before opening so we never surface EISDIR to callers (e.g. tool
+    // results that get sent to messaging channels). See openclaw/openclaw#31186.
+    try {
+        preOpenStat = await inspectFileIdentity(() => {
+            const stat = fsSync.lstatSync(filePath, { bigint: true });
+            observedBeforeOpen = true;
+            if (stat.isSymbolicLink() && options?.symlinks !== "follow-within-root") {
+                throw new FsSafeError("symlink", "symlink not allowed");
+            }
+            if (!stat.isFile() && !stat.isSymbolicLink()) {
+                throw new FsSafeError("not-file", "not a file");
+            }
+            return stat;
+        });
+    }
+    catch (err) {
+        if (err instanceof FsSafeError || observedBeforeOpen) {
+            throw err;
+        }
+        // Only an initial lookup failure falls through; a failed re-inspection aborts.
+    }
+    if (preOpenStat) {
+        await fsSafeTestHooks?.afterPreOpenLstat?.(filePath);
+    }
+    const openFlags = (options?.symlinks === "follow-within-root"
+        ? OPEN_READ_FOLLOW_FLAGS
+        : OPEN_READ_FLAGS) | (options?.readWrite ? fsSync.constants.O_RDWR : 0);
+    await fsSafeTestHooks?.beforeOpen?.(filePath, openFlags);
+    let handle;
+    try {
+        handle = await fs.open(filePath, openFlags).catch((error) => recordFileOpenFailure(isNotFoundPathError(error) ? fileNotFoundError() : error, filePath));
+    }
+    catch (err) {
+        if (isSymlinkOpenError(err)) {
+            throw new FsSafeError("symlink", "symlink open blocked", { cause: err });
+        }
+        // Defensive: if open still throws EISDIR (e.g. race), sanitize so it never leaks.
+        if (hasNodeErrorCode(err, "EISDIR")) {
+            throw new FsSafeError("not-file", "not a file");
+        }
+        throw err;
+    }
+    try {
+        await fsSafeTestHooks?.afterOpen?.(filePath, handle);
+        const stat = fsSync.fstatSync(handle.fd);
+        if (!stat.isFile()) {
+            throw new FsSafeError("not-file", "not a file");
+        }
+        // Keep numeric Stats for the public receipt, never for identity verification.
+        let openedIdentity;
+        const identity = await inspectFileIdentity(() => (openedIdentity = fsSync.fstatSync(handle.fd, { bigint: true })), preOpenStat && !preOpenStat.isSymbolicLink() ? preOpenStat : undefined).catch(async (error) => {
+            if ([0, 1].includes(stat.nlink)) {
+                await recordPreOpenFileChange(error, handle, filePath, preOpenStat, openedIdentity);
+            }
+            throw error;
+        });
+        if (options?.hardlinks === "reject" && stat.nlink > 1) {
+            throw hardlinkedPathNotAllowedError();
+        }
+        return { handle, stat, identity, preOpenStat };
+    }
+    catch (err) {
+        await handle.close().catch(() => { });
+        throw err;
+    }
+}

package/dist/local-roots.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-roots.d.ts","sourceRoot":"","sources":["../src/local-roots.ts"],"names":[],"mappings":"AAQA,OAAO,EAAQ,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAE3F,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oCAAoC,GAAG,sBAAsB,GAAG;IAC1E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG,sBAAsB,GAAG;IACnE,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B,CAAC;AAsDF,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,oCAAoC,GAC5C,oBAAoB,GAAG,IAAI,CAqC7B;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAiCtC"}
+{"version":3,"file":"local-roots.d.ts","sourceRoot":"","sources":["../src/local-roots.ts"],"names":[],"mappings":"AAQA,OAAO,EAAQ,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAQ3F,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oCAAoC,GAAG,sBAAsB,GAAG;IAC1E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG,sBAAsB,GAAG;IACnE,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B,CAAC;AAiEF,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,oCAAoC,GAC5C,oBAAoB,GAAG,IAAI,CA2C7B;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAuCtC"}

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";