@openclaw/fs-safe 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## Unreleased
+
+## 0.2.1 - 2026-05-08
+
+### Fixes
+
+- Align POSIX and Windows handling for literal `..`-prefixed write targets, preserve whitespace in direct home-relative path inputs, and run the check suite on Windows CI. (#14; thanks @sjf)
+- Keep source prepack builds isolated from parent monorepo ambient type packages such as Bun typings. (#13; thanks @Kaspre)
+- Let secret-file reads follow symlink paths through the pinned real target unless callers opt into `rejectSymlink: true`.
+
 ## 0.2.0 - 2026-05-07
 
 ### Features

package/dist/home-dir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"home-dir.d.ts","sourceRoot":"","sources":["../src/home-dir.ts"],"names":[],"mappings":"AAeA,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,GAAG,SAAS,CAGpB;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,GAAG,SAAS,CAGpB;AAsCD,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,CAER;AAED,wBAAgB,wBAAwB,CACtC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,CAER;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAWR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAcR;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EACN;IACE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACD,MAAM,CAAC,UAAU,EACrB,OAAO,CAAC,EAAE,MAAM,MAAM,GACrB,MAAM,CAMR;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAcR"}
+{"version":3,"file":"home-dir.d.ts","sourceRoot":"","sources":["../src/home-dir.ts"],"names":[],"mappings":"AAeA,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,GAAG,SAAS,CAGpB;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,GAAG,SAAS,CAGpB;AAyCD,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,CAER;AAED,wBAAgB,wBAAwB,CACtC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,CAER;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAYR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAcR;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EACN;IACE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACD,MAAM,CAAC,UAAU,EACrB,OAAO,CAAC,EAAE,MAAM,MAAM,GACrB,MAAM,CAMR;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAcR"}

package/dist/home-dir.js

@@ -21,17 +21,21 @@ export function resolveOsHomeDir(env = process.env, homedir = os.homedir) {
 }
 function resolveRawHomeDir(env, homedir) {
     const explicitHome = normalize(env.OPENCLAW_HOME);
-    if (explicitHome) {
-        if (explicitHome === "~" || explicitHome.startsWith("~/") || explicitHome.startsWith("~\\")) {
-            const fallbackHome = resolveRawOsHomeDir(env, homedir);
-            if (fallbackHome) {
-                return explicitHome.replace(/^~(?=$|[\\/])/, fallbackHome);
-            }
-            return undefined;
-        }
+    if (!explicitHome) {
+        return resolveRawOsHomeDir(env, homedir);
+    }
+    const segments = path.normalize(explicitHome).split(path.sep);
+    if (segments[0] !== "~") {
         return explicitHome;
     }
-    return resolveRawOsHomeDir(env, homedir);
+    // OPENCLAW_HOME starts with "~"; expand against the os home dir. Fall
+    // back to undefined when there is no os home to expand against rather
+    // than returning a raw "~"-prefixed path the caller cannot use.
+    const fallbackHome = resolveRawOsHomeDir(env, homedir);
+    if (!fallbackHome) {
+        return undefined;
+    }
+    return expandHomePrefix(explicitHome, { home: fallbackHome });
 }
 function resolveRawOsHomeDir(env, homedir) {
     const envHome = normalize(env.HOME);
@@ -59,7 +63,8 @@ export function resolveRequiredOsHomeDir(env = process.env, homedir = os.homedir
     return resolveOsHomeDir(env, homedir) ?? path.resolve(process.cwd());
 }
 export function expandHomePrefix(input, opts) {
-    if (!input.startsWith("~")) {
+    const segments = path.normalize(input).split(path.sep);
+    if (segments[0] !== "~") {
         return input;
     }
     const home = normalize(opts?.home) ??
@@ -67,22 +72,22 @@ export function expandHomePrefix(input, opts) {
     if (!home) {
         return input;
     }
-    return input.replace(/^~(?=$|[\\/])/, home);
+    return path.join(home, ...segments.slice(1));
 }
 export function resolveHomeRelativePath(input, opts) {
-    const trimmed = input.trim();
-    if (!trimmed) {
-        return trimmed;
+    if (!input) {
+        return input;
     }
-    if (trimmed.startsWith("~")) {
-        const expanded = expandHomePrefix(trimmed, {
-            home: resolveRequiredHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir),
-            env: opts?.env,
-            homedir: opts?.homedir,
-        });
-        return path.resolve(expanded);
+    const segments = path.normalize(input).split(path.sep);
+    if (segments[0] !== "~") {
+        return path.resolve(input);
     }
-    return path.resolve(trimmed);
+    const expanded = expandHomePrefix(input, {
+        home: resolveRequiredHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir),
+        env: opts?.env,
+        homedir: opts?.homedir,
+    });
+    return path.resolve(expanded);
 }
 export function resolveUserPath(input, optsOrEnv, homedir) {
     const opts = optsOrEnv && ("env" in optsOrEnv || "homedir" in optsOrEnv)
@@ -91,17 +96,17 @@ export function resolveUserPath(input, optsOrEnv, homedir) {
     return resolveHomeRelativePath(input, opts);
 }
 export function resolveOsHomeRelativePath(input, opts) {
-    const trimmed = input.trim();
-    if (!trimmed) {
-        return trimmed;
+    if (!input) {
+        return input;
     }
-    if (trimmed.startsWith("~")) {
-        const expanded = expandHomePrefix(trimmed, {
-            home: resolveRequiredOsHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir),
-            env: opts?.env,
-            homedir: opts?.homedir,
-        });
-        return path.resolve(expanded);
+    const segments = path.normalize(input).split(path.sep);
+    if (segments[0] !== "~") {
+        return path.resolve(input);
     }
-    return path.resolve(trimmed);
+    const expanded = expandHomePrefix(input, {
+        home: resolveRequiredOsHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir),
+        env: opts?.env,
+        homedir: opts?.homedir,
+    });
+    return path.resolve(expanded);
 }

package/dist/path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAWzB,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASvE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,cAAc,CAI1E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,SAA6B,GAAG,IAAI,CAIjG;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CA0BlE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAExE;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAa/F;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAChE,OAAO,CAUT;AAED,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,EAAE,CAAC,KAAK,GAAG,IAAI,CAMhE;AAED,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAuBpE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAOrF"}
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAUzB,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASvE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,cAAc,CAI1E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,SAA6B,GAAG,IAAI,CAIjG;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CA4BlE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAExE;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAa/F;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAChE,OAAO,CAUT;AAED,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,EAAE,CAAC,KAAK,GAAG,IAAI,CAMhE;AAED,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAuBpE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAOrF"}

package/dist/path.js

@@ -4,7 +4,6 @@ import { FsSafeError } from "./errors.js";
 import { normalizeLowercaseStringOrEmpty } from "./string-coerce.js";
 const NOT_FOUND_CODES = new Set(["ENOENT", "ENOTDIR"]);
 const SYMLINK_OPEN_CODES = new Set(["ELOOP", "EINVAL", "ENOTSUP"]);
-const PARENT_SEGMENT_PREFIX = /^\.\.(?:[\\/]|$)/u;
 const POSIX_SEPARATOR_CHAR_CODE = 0x2f;
 export function normalizeWindowsPathForComparison(input) {
     let normalized = path.win32.normalize(input);
@@ -38,7 +37,8 @@ export function isPathInside(root, target) {
         const rootForCompare = normalizeWindowsPathForComparison(path.win32.resolve(root));
         const targetForCompare = normalizeWindowsPathForComparison(path.win32.resolve(target));
         const relative = path.win32.relative(rootForCompare, targetForCompare);
-        return (relative === "" || (!PARENT_SEGMENT_PREFIX.test(relative) && !path.win32.isAbsolute(relative)));
+        const firstSegment = relative.split(path.win32.sep)[0];
+        return (relative === "" || (firstSegment !== ".." && !path.win32.isAbsolute(relative)));
     }
     if (root.length > 0 &&
         root.charCodeAt(0) === POSIX_SEPARATOR_CHAR_CODE &&
@@ -52,7 +52,8 @@ export function isPathInside(root, target) {
     const resolvedRoot = path.resolve(root);
     const resolvedTarget = path.resolve(target);
     const relative = path.relative(resolvedRoot, resolvedTarget);
-    return relative === "" || (!PARENT_SEGMENT_PREFIX.test(relative) && !path.isAbsolute(relative));
+    const firstSegment = relative.split(path.posix.sep)[0];
+    return relative === "" || (firstSegment !== ".." && !path.isAbsolute(relative));
 }
 export function resolveSafeBaseDir(rootDir) {
     const resolved = path.resolve(rootDir);

package/dist/root-impl.js

@@ -856,8 +856,10 @@ async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode)
     catch (err) {
         throw new FsSafeError("path-alias", "path alias escape blocked", { cause: err });
     }
+    // resolvePathInRoot already enforces isPathInside, so any actual escape
+    // is rejected upstream.
     const relativeResolved = path.relative(rootReal, resolved);
-    if (relativeResolved.startsWith("..") || path.isAbsolute(relativeResolved)) {
+    if (path.isAbsolute(relativeResolved)) {
         throw new FsSafeError("outside-workspace", "file is outside workspace root");
     }
     const relativePosix = relativeResolved
@@ -919,9 +921,10 @@ async function resolvePinnedOperationPathInRoot(root, params) {
     if ((relativeResolved === "" || relativeResolved === ".") && params.allowRoot === true) {
         return { rootReal: resolved.rootReal, resolved: resolved.canonicalPath, relativePosix: "" };
     }
+    const firstSegment = relativeResolved.split(path.sep)[0];
     if (relativeResolved === "" ||
         relativeResolved === "." ||
-        relativeResolved.startsWith("..") ||
+        firstSegment === ".." ||
         path.isAbsolute(relativeResolved)) {
         throw new FsSafeError("outside-workspace", "file is outside workspace root");
     }

package/dist/secret-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,6BAA6B,QAAY,CAAC;AACvD,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAuGF,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAQR;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAMpB;AAoFD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyDhB"}
+{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,6BAA6B,QAAY,CAAC;AACvD,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAqHF,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAQR;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAMpB;AAoFD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyDhB"}

package/dist/secret-file.js

@@ -36,12 +36,28 @@ function readSecretFileOutcomeSync(filePath, label, options = {}) {
             message: `Failed to inspect ${label} file at ${resolvedPath}: ${String(normalized)}`,
         };
     }
-    if (options.rejectSymlink && previewStat.isSymbolicLink()) {
-        return {
-            ok: false,
-            code: "symlink",
-            message: `${label} file at ${resolvedPath} must not be a symlink.`,
-        };
+    if (previewStat.isSymbolicLink()) {
+        if (!options.rejectSymlink) {
+            try {
+                previewStat = fs.statSync(resolvedPath);
+            }
+            catch (error) {
+                const normalized = normalizeSecretReadError(error);
+                return {
+                    ok: false,
+                    code: error.code === "ENOENT" ? "not-found" : "invalid-path",
+                    error: normalized,
+                    message: `Failed to inspect ${label} file at ${resolvedPath}: ${String(normalized)}`,
+                };
+            }
+        }
+        else {
+            return {
+                ok: false,
+                code: "symlink",
+                message: `${label} file at ${resolvedPath} must not be a symlink.`,
+            };
+        }
     }
     if (!previewStat.isFile()) {
         return {

package/package.json

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