@openclaw/fs-safe 0.8.3 → 0.8.4

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

@@ -1 +1 @@
-{"version":3,"file":"root-path.d.ts","sourceRoot":"","sources":["../src/root-path.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,kCAAkC,EAAE,MAAM,yBAAyB,CAAC;AAE7E,KAAK,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtE,MAAM,MAAM,mBAAmB,GAAG;IAChC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC,CAAC;AAEF,eAAO,MAAM,wBAAwB;aACnC,MAAM;;;;aAIN,YAAY;;;;CAIJ,CAAC;AAEX,KAAK,qBAAqB,GAAG;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,KAAK,oBAAoB,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,oBAAoB,CAAC;CAC5B,CAAC;AAEF,wBAAsB,eAAe,CACnC,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CAM3B;AAsCD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,qBAAqB,GAAG,gBAAgB,CAMnF"}
+{"version":3,"file":"root-path.d.ts","sourceRoot":"","sources":["../src/root-path.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,kCAAkC,EAAE,MAAM,yBAAyB,CAAC;AAE7E,KAAK,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtE,MAAM,MAAM,mBAAmB,GAAG;IAChC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC,CAAC;AAEF,eAAO,MAAM,wBAAwB;aACnC,MAAM;;;;aAIN,YAAY;;;;CAIJ,CAAC;AAEX,KAAK,qBAAqB,GAAG;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,KAAK,oBAAoB,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,oBAAoB,CAAC;CAC5B,CAAC;AAEF,wBAAsB,eAAe,CACnC,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CAM3B;AAsCD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,qBAAqB,GAAG,gBAAgB,CAMnF"}

package/dist/root-path.js

@@ -1,5 +1,4 @@
 import fs from "node:fs";
-import fsp from "node:fs/promises";
 import path from "node:path";
 import { formatErrorDetail, shortPath } from "./error-detail.js";
 import { FsSafeError } from "./errors.js";
@@ -234,7 +233,7 @@ async function resolveRootPathLexicalAsync(params) {
         state.lexicalCursor = path.join(state.lexicalCursor, segment);
         let stat;
         try {
-            stat = await fsp.lstat(state.lexicalCursor);
+            stat = fs.lstatSync(state.lexicalCursor);
         }
         catch (error) {
             if (handleLexicalLstatFailure(context, error, idx))
@@ -423,8 +422,8 @@ function buildResolvedRootPath(params) {
 async function getPathKind(absolutePath, preserveFinalSymlink) {
     try {
         const stat = preserveFinalSymlink
-            ? await fsp.lstat(absolutePath)
-            : await fsp.stat(absolutePath);
+            ? fs.lstatSync(absolutePath)
+            : fs.statSync(absolutePath);
         return { exists: true, kind: toResolvedKind(stat) };
     }
     catch (error) {

package/dist/root-paths.d.ts.map

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

package/dist/root-paths.js

@@ -1,3 +1,4 @@
+import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { formatErrorDetail } from "./error-detail.js";
@@ -16,7 +17,7 @@ function pathStaysWithinRoot(rootDir, candidatePath) {
 }
 async function resolveRealPathIfExists(targetPath) {
     try {
-        return await fs.realpath(targetPath);
+        return fsSync.realpathSync.native(targetPath);
     }
     catch {
         return undefined;
@@ -24,11 +25,11 @@ async function resolveRealPathIfExists(targetPath) {
 }
 async function resolveTrustedRootRealPath(rootDir) {
     try {
-        const rootLstat = await fs.lstat(rootDir);
+        const rootLstat = fsSync.lstatSync(rootDir);
         if (!rootLstat.isDirectory() || rootLstat.isSymbolicLink()) {
             return undefined;
         }
-        return await fs.realpath(rootDir);
+        return fsSync.realpathSync.native(rootDir);
     }
     catch {
         return undefined;
@@ -36,7 +37,7 @@ async function resolveTrustedRootRealPath(rootDir) {
 }
 async function validateCanonicalPathWithinRoot(params) {
     try {
-        const candidateLstat = await fs.lstat(params.candidatePath);
+        const candidateLstat = fsSync.lstatSync(params.candidatePath);
         if (candidateLstat.isSymbolicLink()) {
             return "invalid";
         }
@@ -49,7 +50,7 @@ async function validateCanonicalPathWithinRoot(params) {
         if (params.expect === "file" && candidateLstat.nlink > 1) {
             return "invalid";
         }
-        const candidateRealPath = await fs.realpath(params.candidatePath);
+        const candidateRealPath = fsSync.realpathSync.native(params.candidatePath);
         return isPathInside(params.rootRealPath, candidateRealPath) ? "ok" : "invalid";
     }
     catch (err) {
@@ -109,7 +110,7 @@ async function resolveNearestExistingPath(targetPath) {
     let current = path.resolve(targetPath);
     while (true) {
         try {
-            await fs.lstat(current);
+            fsSync.lstatSync(current);
             return current;
         }
         catch (err) {
@@ -133,7 +134,7 @@ async function assertNoSymlinkSegments(params) {
     for (const segment of relative.split(path.sep).filter(Boolean)) {
         current = path.join(current, segment);
         try {
-            const stat = await fs.lstat(current);
+            const stat = fsSync.lstatSync(current);
             if (stat.isSymbolicLink()) {
                 throw new FsSafeError("symlink", `Invalid path: must not traverse symlinks within ${params.scopeLabel}`);
             }
@@ -163,14 +164,14 @@ export async function ensureDirectoryWithinRoot(params) {
             return lexical;
         const rootDir = path.resolve(params.rootDir);
         const targetPath = lexical.path;
-        const rootStat = await fs.lstat(rootDir);
+        const rootStat = fsSync.lstatSync(rootDir);
         if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
             return invalidPath(scopeLabel);
         }
         await assertNoSymlinkSegments({ rootDir, targetPath, scopeLabel });
-        const rootReal = await fs.realpath(rootDir);
+        const rootReal = fsSync.realpathSync.native(rootDir);
         const nearestExistingPath = await resolveNearestExistingPath(targetPath);
-        const nearestExistingReal = await fs.realpath(nearestExistingPath);
+        const nearestExistingReal = fsSync.realpathSync.native(nearestExistingPath);
         if (!isPathInside(rootReal, nearestExistingReal)) {
             return invalidPath(scopeLabel);
         }
@@ -180,7 +181,7 @@ export async function ensureDirectoryWithinRoot(params) {
             current = path.join(current, segment);
             while (true) {
                 try {
-                    const stat = await fs.lstat(current);
+                    const stat = fsSync.lstatSync(current);
                     if (stat.isSymbolicLink() || !stat.isDirectory()) {
                         return invalidPath(scopeLabel);
                     }
@@ -201,12 +202,12 @@ export async function ensureDirectoryWithinRoot(params) {
                     }
                 }
             }
-            const currentReal = await fs.realpath(current);
+            const currentReal = fsSync.realpathSync.native(current);
             if (!isPathInside(rootReal, currentReal)) {
                 return invalidPath(scopeLabel);
             }
         }
-        const targetReal = await fs.realpath(targetPath);
+        const targetReal = fsSync.realpathSync.native(targetPath);
         if (!isPathInside(rootReal, targetReal)) {
             return invalidPath(scopeLabel);
         }
@@ -308,7 +309,7 @@ async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
             return lexicalPathResult;
         }
         try {
-            const resolvedExistingPath = await fs.realpath(raw);
+            const resolvedExistingPath = fsSync.realpathSync.native(raw);
             const relativePath = path.relative(rootRealPath, resolvedExistingPath);
             if (!isInRoot(relativePath)) {
                 return lexicalPathResult;
@@ -350,7 +351,7 @@ async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
                         scopeLabel: params.scopeLabel,
                     });
                     const existingPath = await resolveNearestExistingPath(pathResult.fallbackPath);
-                    const existingRealPath = await fs.realpath(existingPath);
+                    const existingRealPath = fsSync.realpathSync.native(existingPath);
                     if (!isPathInside(rootRealPath, existingRealPath)) {
                         return invalidPath(params.scopeLabel);
                     }

package/dist/root-write-mode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root-write-mode.d.ts","sourceRoot":"","sources":["../src/root-write-mode.ts"],"names":[],"mappings":"AASA,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwClB"}
+{"version":3,"file":"root-write-mode.d.ts","sourceRoot":"","sources":["../src/root-write-mode.ts"],"names":[],"mappings":"AAUA,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwClB"}

package/dist/root-write-mode.js

@@ -1,3 +1,4 @@
+import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
@@ -8,7 +9,7 @@ import { inspectFileIdentity } from "./strict-file-identity.js";
 // The caller has already resolved and guarded this write target.
 export async function inheritWriteTargetMode(params) {
     try {
-        const existing = await inspectFileIdentity(() => fs.lstat(params.targetPath, { bigint: true }));
+        const existing = await inspectFileIdentity(() => fsSync.lstatSync(params.targetPath, { bigint: true }));
         if (existing.isSymbolicLink())
             throw new FsSafeError("path-alias", "path alias escape blocked");
         if (!existing.isFile())
@@ -22,7 +23,7 @@ export async function inheritWriteTargetMode(params) {
         const handle = await fs.open(params.targetPath, resolveReadOpenFlags());
         try {
             // Bind admission to the inode whose metadata is inherited.
-            if (!sameFileIdentity(await handle.stat({ bigint: true }), existing)) {
+            if (!sameFileIdentity(fsSync.fstatSync(handle.fd, { bigint: true }), existing)) {
                 throw new FsSafeError("path-mismatch", "write target changed during mode inheritance");
             }
         }
@@ -32,11 +33,11 @@ export async function inheritWriteTargetMode(params) {
         try {
             // A parent can change after guarded resolution. Do not inherit metadata
             // from an outside inode, even if the parent is restored before publication.
-            const realPath = await fs.realpath(params.targetPath);
+            const realPath = fsSync.realpathSync.native(params.targetPath);
             if (!isPathInside(params.rootWithSep, realPath))
                 throw outsideWorkspaceError();
             await inspectFileIdentity(async () => {
-                const current = await fs.stat(realPath, { bigint: true });
+                const current = fsSync.statSync(realPath, { bigint: true });
                 if (!current.isFile())
                     throw new FsSafeError("not-file", "not a file");
                 if (current.nlink > 1n)

package/dist/root-write-verification.js

@@ -46,16 +46,16 @@ export async function verifyAtomicWriteResult(params) {
     try {
         // This descriptor remains owned by the writer, even when final mode forbids opens.
         const stat = assertDescriptor();
-        assertPath(await fs.lstat(params.targetPath, { bigint: true }));
+        assertPath(fsSync.lstatSync(params.targetPath, { bigint: true }));
         const { realPath } = await resolveOpenedFileRealPathForFd(params.fd, stat, params.targetPath);
-        assertPath(await fs.stat(realPath, { bigint: true }));
+        assertPath(fsSync.statSync(realPath, { bigint: true }));
         if (!isPathInside(params.root.rootWithSep, realPath)) {
             throw outsideWorkspaceError();
         }
         await assertAsyncDirectoryGuard(params.parentGuard);
         await assertRootIdentityCurrent(params.root);
         // Recheck after canonical resolution and directory checks, including late links.
-        assertPath(await fs.lstat(params.targetPath, { bigint: true }));
+        assertPath(fsSync.lstatSync(params.targetPath, { bigint: true }));
         assertDescriptor();
         if (needsPathOpen) {
             // A retained fd cannot prove that an opaque Windows pathname still names it.
@@ -73,15 +73,15 @@ export async function verifyAtomicWriteResult(params) {
             });
             try {
                 const reopenedStat = assertDescriptor(opened.fd);
-                assertPath(await fs.lstat(params.targetPath, { bigint: true }));
+                assertPath(fsSync.lstatSync(params.targetPath, { bigint: true }));
                 const { realPath: reopenedPath } = await resolveOpenedFileRealPathForFd(opened.fd, reopenedStat, params.targetPath);
-                assertPath(await fs.stat(reopenedPath, { bigint: true }));
+                assertPath(fsSync.statSync(reopenedPath, { bigint: true }));
                 if (!isPathInside(params.root.rootWithSep, reopenedPath)) {
                     throw outsideWorkspaceError();
                 }
                 await assertAsyncDirectoryGuard(params.parentGuard);
                 await assertRootIdentityCurrent(params.root);
-                assertPath(await fs.lstat(params.targetPath, { bigint: true }));
+                assertPath(fsSync.lstatSync(params.targetPath, { bigint: true }));
                 assertDescriptor(opened.fd);
             }
             finally {

package/dist/secret-file.js

@@ -140,7 +140,7 @@ async function enforcePrivateDirectoryMode(params) {
 }
 async function inspectPrivateDirectory(directory, kind) {
     return await inspectFileIdentity(async () => {
-        const stat = await fsp.lstat(directory, { bigint: true });
+        const stat = fs.lstatSync(directory, { bigint: true });
         if (stat.isSymbolicLink()) {
             throw new Error(`Private secret ${kind} ${directory} must not be a symlink.`);
         }
@@ -260,7 +260,7 @@ export async function prepareSecretFileWrite(params) {
 async function materializeSecretFileAtomic(params, createOnly) {
     const { mode, rootGuard, parentGuard, fileName, finalFilePath } = await prepareSecretFileWrite(params);
     try {
-        const stat = await fsp.lstat(finalFilePath);
+        const stat = fs.lstatSync(finalFilePath);
         if (createOnly) {
             throw new FsSafeError("secret-exists", `Private secret file ${finalFilePath} already exists.`);
         }

package/dist/strict-file-identity.d.ts

@@ -1,6 +1,6 @@
 import type { BigIntStats } from "node:fs";
 type ExactFileIdentity = Pick<BigIntStats, "dev" | "ino">;
-export declare function inspectFileIdentity<T extends ExactFileIdentity>(inspect: () => Promise<T>, expected?: ExactFileIdentity, platform?: NodeJS.Platform): Promise<T>;
+export declare function inspectFileIdentity<T extends ExactFileIdentity>(inspect: () => T | Promise<T>, expected?: ExactFileIdentity, platform?: NodeJS.Platform): Promise<T>;
 export declare function inspectFileIdentitySync<T extends ExactFileIdentity>(inspect: () => T, expected?: ExactFileIdentity, platform?: NodeJS.Platform): T;
 export {};
 //# sourceMappingURL=strict-file-identity.d.ts.map

package/dist/strict-file-identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strict-file-identity.d.ts","sourceRoot":"","sources":["../src/strict-file-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAI3C,KAAK,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;AA+B1D,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,iBAAiB,EACnE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,iBAAiB,EACjE,OAAO,EAAE,MAAM,CAAC,EAChB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,CAAC,CAOH"}
+{"version":3,"file":"strict-file-identity.d.ts","sourceRoot":"","sources":["../src/strict-file-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAI3C,KAAK,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;AA+B1D,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,iBAAiB,EACnE,OAAO,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC7B,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,iBAAiB,EACjE,OAAO,EAAE,MAAM,CAAC,EAChB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,CAAC,CAOH"}

package/dist/symlink-parents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symlink-parents.d.ts","sourceRoot":"","sources":["../src/symlink-parents.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAyBF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,6BAA6B,GACpC,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,6BAA6B,GACpC,IAAI,CA6BN"}
+{"version":3,"file":"symlink-parents.d.ts","sourceRoot":"","sources":["../src/symlink-parents.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAyBF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,6BAA6B,GACpC,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,6BAA6B,GACpC,IAAI,CA6BN"}

package/dist/symlink-parents.js

@@ -1,5 +1,4 @@
 import fsSync from "node:fs";
-import fs from "node:fs/promises";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { hasNodeErrorCode, isPathRelativeEscape } from "./path.js";
@@ -30,7 +29,7 @@ export async function assertNoSymlinkParents(params) {
     for (const [index, segment] of walk.segments.entries()) {
         current = path.join(current, segment);
         try {
-            const stat = await fs.lstat(current);
+            const stat = fsSync.lstatSync(current);
             if (stat.isSymbolicLink()) {
                 if (params.allowRootChildSymlink && path.dirname(current) === walk.root) {
                     continue;

package/docs/archive.md

@@ -422,6 +422,63 @@ Normal link/filter policy still governs the described member. Canonical
 pre-strip filter paths, decoded-stream ceilings, and physical EOF checks apply
 to plain/gzip TAR and native zstd/bzip2 alike.
 
+## `inspectTarArchive`
+
+Inspect accepted TAR members without creating an extracted tree. This operation
+uses the same complete Rust/WASM admission and TypeScript extraction planner as
+`extractArchive`, with zero stripping. It detects plain TAR or gzip from the
+input bytes; ZIP, zstd, and bzip2 are not part of this inspection API.
+
+```ts
+import { inspectTarArchive } from "@openclaw/fs-safe/archive";
+
+const entries = await inspectTarArchive({
+  archivePath: "/srv/uploads/tree.tar.gz",
+  timeoutMs: 30_000,
+  limits: {
+    maxArchiveBytes: 16 * 1024 * 1024,
+    maxEntries: 5_000,
+    maxEntryBytes: 16 * 1024 * 1024,
+    maxExtractedBytes: 64 * 1024 * 1024,
+  },
+  entryFilter: ({ kind }) => kind === "file" || kind === "directory" ? "extract" : "skip",
+  onFiltered: "reject-archive",
+});
+```
+
+`InspectTarArchiveOptions` accepts `archivePath`, `timeoutMs`, `limits`,
+`entryFilter`, and `onFiltered`, with the same defaults and error classes as
+extraction. The result is a frozen array of frozen `InspectedTarEntry` records:
+`{ path: string; kind: "file" | "directory"; size: number }`, in archive order.
+`size` is the effective declared payload length. `path` is extraction's
+canonical pre-strip identity: case, Unicode spelling, BOM, and embedded LF are
+preserved, while separators and dot components follow the existing archive path
+contract. No human-readable tar listing or escape decoding is involved.
+
+Full framing, gzip integrity, EOF, metadata, decoded-byte, and manifest-budget
+validation finishes before the caller's filter runs. The shared planner then
+applies traversal, collision, depth, blocked-type, and accepted-payload limits.
+A failure returns no partial result. Filter callbacks are decisions, not admission
+receipts: later policy, collision, or budget checks can still reject the archive.
+Only the resolved Promise/result is authorization-worthy; do not perform
+irreversible actions from a filter callback.
+
+Root-only records count toward entry limits but produce no result; PAX/GNU metadata headers are not members. Only accepted
+file/directory members appear, not implicit parent directories. Unsupported
+records follow extraction's omission policy unless the filter rejects them, as
+in the example. AppleDouble records encoded as ordinary files are ordinary
+members, not hidden metadata.
+
+Inspection pins and privately stages its input, then cleans up that copy. It
+neither creates destination paths nor tests destination permissions or platform
+filename restrictions. Its result is evidence about those inspected bytes, not
+an extraction capability or a promise that a later file at `archivePath` is
+unchanged. Callers making authorization decisions must retain the same private
+immutable archive or verify byte identity before extracting with matching
+filter/limit settings. Extraction always performs its own admission and guarded
+publication. Native `off`, `auto`, and `require` retain their existing selection
+and availability semantics; inspection does not fall back after native failure.
+
 ## `resolveArchiveKind`
 
 ```ts

package/docs/reading.md

@@ -12,6 +12,8 @@ const opened = await fs.open("large.log");               // FileHandle for strea
 
 ## What every read does
 
+Identity and containment checks use brief synchronous metadata calls, like Node's module resolution, while file data is read asynchronously. Canonical paths retain Node's native realpath spelling, including expansion of Windows short paths.
+
 Regardless of shape, every read goes through the same boundary checks:
 
 1. Resolve the input lexically against the canonical real root.

package/docs/root.md

@@ -18,6 +18,7 @@ const fs = await root("/srv/workspace", {
 function root(rootDir: string, defaults?: RootDefaults): Promise<Root>;
 
 type RootDefaults = {
+  durable?: boolean;               // fsync write/create/writeJson/createJson/append; default true
   hardlinks?: "reject" | "allow";  // refuse files with nlink > 1 on read; defaults to "reject"
   denyMutations?: DenyMutationPolicy; // absolute paths/prefixes mutation methods may not change
   maxBytes?: number;               // refuse reads larger than this many bytes; defaults to 16 MiB
@@ -99,7 +100,7 @@ fs.write(rel, data, options?)            // overwrite-ok atomic write
 fs.create(rel, data, options?)           // throws "already-exists" if target exists
 fs.writeJson(rel, value, options?)       // JSON.stringify + atomic write
 fs.createJson(rel, value, options?)      // create() variant of writeJson
-fs.append(rel, data, options?)           // append text/buffer; syncs before close
+fs.append(rel, data, options?)           // append text/buffer; syncs before close by default
 fs.copyIn(rel, sourceAbsPath, options?)  // copy from outside the root, atomically, with size cap
 fs.openWritable(rel, options?)           // FileHandle for streaming writes; supports await using
 fs.move(from, to, options?)              // rename within the root; defaults to no clobber
@@ -110,6 +111,14 @@ fs.ensureRoot(options?)                  // accepts "" / "." as the root itself
 
 `write`, `create`, `append`, `writeJson`, and `createJson` accept `mode?: number`; use `0o600` for credentials and other private state. `writeJson` also accepts the same options as `JSON.stringify` plus `trailingNewline?: boolean` (defaults `true` so the file ends in `\n`).
 
+These five methods also accept `durable?: boolean`: the per-call value overrides
+`Root.defaults.durable`, which defaults to `true` when omitted. An explicitly
+`undefined` per-call value preserves the root default. `durable: false` keeps
+the existing publication behavior, modes, and identity checks but skips file
+and parent-directory fsync calls. Use it only for reconstructible data: a crash
+may lose the write or leave the previous file. See [Writing](writing.md#write-options)
+for platform details.
+
 `copyIn` is a one-shot ingest from a trusted absolute source path: it streams the source through the boundary, atomically renames into the root, and respects `maxBytes`.
 
 Root operations that choose a new destination reject a leading Windows

package/docs/types.md

@@ -100,6 +100,7 @@ type RenameIdentityPolicy = "strict" | "verify-content-with-lock";
 
 type RootDefaults = {
   denyMutations?: DenyMutationPolicy;
+  durable?: boolean; // default true for write/create/writeJson/createJson/append
   hardlinks?: "reject" | "allow";
   maxBytes?: number;
   mkdir?: boolean; // default true for mutation methods
@@ -126,7 +127,7 @@ type RootOptions = {
 
 ```ts
 type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "nonBlockingRead" | "symlinks">;
-type RootWriteOptions = Pick<RootDefaults, "denyMutations" | "mkdir" | "mode" | "renameIdentity"> & {
+type RootWriteOptions = Pick<RootDefaults, "denyMutations" | "durable" | "mkdir" | "mode" | "renameIdentity"> & {
   encoding?: BufferEncoding;
   overwrite?: boolean;
 };

package/docs/writing.md

@@ -77,14 +77,37 @@ await fs.write("state/last-run.json", JSON.stringify(run));
 await fs.write("notes/today.txt", "hello\n", { encoding: "utf8" });
 ```
 
-`data` accepts `string | Buffer`. `options` are `{ denyMutations?: DenyMutationPolicy; encoding?: BufferEncoding; mkdir?: boolean; mode?: number; overwrite?: boolean; renameIdentity?: RenameIdentityPolicy }`. `mode` sets the file's POSIX mode. If neither the call nor `RootDefaults` supplies it, a replacement preserves the existing file mode and a new file uses `0o600`. `mkdir` and `overwrite` both default to `true`; set `overwrite: false` for the same no-clobber behavior as `create()`.
+`data` accepts `string | Buffer`. `mode` sets the file's POSIX mode. If neither the call nor `RootDefaults` supplies it, a replacement preserves the existing file mode and a new file uses `0o600`. `mkdir` and `overwrite` both default to `true`; set `overwrite: false` for the same no-clobber behavior as `create()`.
+
+#### Write options
+
+| Option | Type | Default / behavior |
+|---|---|---|
+| `denyMutations` | `DenyMutationPolicy` | Merged with root-level denies. |
+| `durable` | `boolean` | `true`; use `false` to skip file and parent fsync. |
+| `encoding` | `BufferEncoding` | `"utf8"` for strings. |
+| `mkdir` | `boolean` | `true`; creates missing parents. |
+| `mode` | `number` | Inherited on replacement, otherwise `0o600`. |
+| `overwrite` | `boolean` | `true`; `false` is create-only. |
+| `renameIdentity` | `RenameIdentityPolicy` | `"strict"`. |
+
+`write`, `create`, `writeJson`, `createJson`, and `append` accept `durable`.
+Precedence is per-call option, then `Root.defaults.durable`, then `true`;
+an explicitly `undefined` call option preserves the root default.
+`durable: false` keeps the sibling-temp replace/rename behavior of replacement
+writes but skips file and parent-directory fsync calls. Create-only and append
+publication behavior, permissions, identity checks, and error codes are unchanged.
+Use it only for reconstructible data: a crash may lose the write or leave the
+previous file. `copyIn`, `move`, and streaming `openWritable` do not use this option.
+The existing pure-JavaScript Windows writer performs no fsync calls in either
+setting; native Windows writes honor the option. Directory sync remains best-effort.
 
 POSIX modes without read permission, including `0o000` and `0o200`, succeed:
 final verification uses a descriptor retained by the writer rather than reopening
 the published file. The requested mode is not relaxed for verification.
 Publication verification compares exact bigint descriptor and pathname identities,
 including large file indexes that cannot be represented by a JavaScript number.
-Native publication syncs content before rename and always syncs the parent directory.
+With durability enabled (the default), native publication syncs content before rename and syncs the parent directory.
 Modes that retain owner read/write skip the extra mode-only file sync: after a
 crash, the file may retain staged mode `0o600` instead of the wider requested mode.
 Modes that remove owner read or write, and corrections of observed wider staging
@@ -143,7 +166,7 @@ type RootWriteJsonOptions = RootWriteOptions & {
 
 ### `fs.append(rel, data, options?)`
 
-Open in append mode, write, sync the file handle, and close. Honors `mkdir` for the parent directory and syncs the parent directory when the append creates the file. Pass `prependNewlineIfNeeded: true` to insert a `\n` if the file does not already end in one.
+Open in append mode, write, sync the file handle, and close. Honors `mkdir` for the parent directory and syncs the parent directory when the append creates the file. `durable: false` skips both syncs. Pass `prependNewlineIfNeeded: true` to insert a `\n` if the file does not already end in one.
 
 ```ts
 await fs.append("logs/today.log", `[${ts}] ${line}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -156,13 +156,13 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.8.3",
-    "@openclaw/fs-safe-darwin-x64": "0.8.3",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.8.3",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.8.3",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.8.3",
-    "@openclaw/fs-safe-linux-x64-musl": "0.8.3",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.8.3",
+    "@openclaw/fs-safe-darwin-arm64": "0.8.4",
+    "@openclaw/fs-safe-darwin-x64": "0.8.4",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.8.4",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.8.4",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.8.4",
+    "@openclaw/fs-safe-linux-x64-musl": "0.8.4",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.8.4",
     "jszip": "^3.10.1"
   },
   "devDependencies": {