@openclaw/fs-safe 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.1 - 2026-05-06
+
+### Fixes
+
+- Preserve the caller's destination path spelling during staged archive merges so symlink-rebind checks catch alias races on macOS.
+- Reject archive writes that gain a hardlink alias during post-write verification and clean up the destination file.
+
 ## 0.1.0 - 2026-05-06
 
 ### Features

package/README.md

@@ -241,8 +241,9 @@ const opened = await media.open("inbound/photo.jpg");
 await media.pruneExpired({ ttlMs: 10 * 60 * 1000, recursive: true });
 ```
 
-`tempWorkspace()` also exposes `writeText()`, `writeJson()`, and `copyIn()` for
-single-file scratch workflows without hand-rolled path joins.
+`tempWorkspace()` exposes `write()`, `writeText()`, `writeJson()`, `copyIn()`, and `read()` for
+single-file scratch workflows without hand-rolled path joins, plus a `store: FileStore` view of
+the workspace dir for the richer cases (`writeStream`, `readJsonIfExists`, `store.json<T>(rel)`).
 
 `tempFile()` is the smaller one-file temp helper. It is intentionally an
 advanced primitive: use `tempWorkspace()` for the stable temp surface and reach

package/dist/archive-staging.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,wBAAwB,GAChC,2BAA2B,GAC3B,qBAAqB,GACrB,+BAA+B,CAAC;AAEpC,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,IAAI,EAAE,wBAAwB,CAAC;gBAEnB,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAKpF;AASD,wBAAsB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYnF;AA6CD,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBhB;AAmBD,wBAAsB,4BAA4B,CAAC,CAAC,EAAE,MAAM,EAAE;IAC5D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACzC,GAAG,OAAO,CAAC,CAAC,CAAC,CAkBb;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;CAC5B,GAAG,OAAO,CAAC,IAAI,CAAC,CAyDhB;AAED,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,CAE7F"}
+{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,wBAAwB,GAChC,2BAA2B,GAC3B,qBAAqB,GACrB,+BAA+B,CAAC;AAEpC,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,IAAI,EAAE,wBAAwB,CAAC;gBAEnB,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAKpF;AASD,wBAAsB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYnF;AA6CD,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBhB;AAqDD,wBAAsB,4BAA4B,CAAC,CAAC,EAAE,MAAM,EAAE;IAC5D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACzC,GAAG,OAAO,CAAC,CAAC,CAAC,CAkBb;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;CAC5B,GAAG,OAAO,CAAC,IAAI,CAAC,CAyEhB;AAED,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,CAE7F"}

package/dist/archive-staging.js

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { FsSafeError } from "./errors.js";
 import { root } from "./root.js";
 import { isNotFoundPathError, isPathInside } from "./path.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
@@ -95,6 +96,32 @@ async function applyStagedEntryMode(params) {
         await fs.chmod(destinationPath, params.mode).catch(() => undefined);
     }
 }
+async function assertExtractedFileHasNoHardlinkAlias(params) {
+    const destinationPath = path.join(params.destinationRealDir, params.relPath);
+    await assertResolvedInsideDestination({
+        destinationRealDir: params.destinationRealDir,
+        targetPath: destinationPath,
+        originalPath: params.originalPath,
+    });
+    const stat = await fs.lstat(destinationPath);
+    if (stat.isFile() && stat.nlink > 1) {
+        throw symlinkTraversalError(params.originalPath);
+    }
+}
+async function removeExtractedDestinationFile(params) {
+    const destinationPath = path.join(params.destinationRealDir, params.relPath);
+    let resolved;
+    try {
+        resolved = await fs.realpath(destinationPath);
+    }
+    catch {
+        return;
+    }
+    if (!isPathInside(params.destinationRealDir, resolved)) {
+        return;
+    }
+    await fs.rm(destinationPath, { force: true }).catch(() => undefined);
+}
 export async function withStagedArchiveDestination(params) {
     const stagingRoot = resolveSecureTempRoot({
         fallbackPrefix: "fs-safe-archive",
@@ -155,13 +182,30 @@ export async function mergeExtractedTreeIntoDestination(params) {
                 originalPath,
                 isDirectory: false,
             });
-            await targetRoot.copyIn(relPath, sourcePath, { mkdir: true });
-            await applyStagedEntryMode({
-                destinationRealDir: params.destinationRealDir,
-                relPath,
-                mode: sourceStat.mode & 0o777,
-                originalPath,
-            });
+            try {
+                await targetRoot.copyIn(relPath, sourcePath, { mkdir: true });
+                await assertExtractedFileHasNoHardlinkAlias({
+                    destinationRealDir: params.destinationRealDir,
+                    relPath,
+                    originalPath,
+                });
+                await applyStagedEntryMode({
+                    destinationRealDir: params.destinationRealDir,
+                    relPath,
+                    mode: sourceStat.mode & 0o777,
+                    originalPath,
+                });
+            }
+            catch (err) {
+                await removeExtractedDestinationFile({
+                    destinationRealDir: params.destinationRealDir,
+                    relPath,
+                });
+                if (err instanceof FsSafeError && (err.code === "hardlink" || err.code === "path-alias")) {
+                    throw symlinkTraversalError(originalPath);
+                }
+                throw err;
+            }
         }
     };
     await walk(params.sourceDir);

package/dist/archive.js

@@ -168,7 +168,7 @@ async function extractZip(params) {
             }
             await mergeExtractedTreeIntoDestination({
                 sourceDir: stagingRealDir,
-                destinationDir: destinationRealDir,
+                destinationDir: params.destDir,
                 destinationRealDir,
             });
         },
@@ -223,7 +223,7 @@ export async function extractArchive(params) {
                     });
                     await mergeExtractedTreeIntoDestination({
                         sourceDir: stagingDir,
-                        destinationDir: destinationRealDir,
+                        destinationDir: params.destDir,
                         destinationRealDir,
                     });
                 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "license": "MIT",
   "repository": {