@openclaw/fs-safe 0.2.5 → 0.2.7

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.2.7 - 2026-05-20
+
+### Security and Correctness
+
+- Restore best-effort Node write fallbacks when the Python helper is disabled or unavailable, preserving the `mode: "off"` contract while documenting the weaker POSIX same-UID race resistance compared with fd-relative helper commits.
+- Harden DeepSec-reported archive staging and input pinning, secret and queue hardlink rejection, absolute output file validation, sidecar lock read failures, ClawSweeper dispatch trust checks, and scoped path defaults.
+
+## 0.2.6 - 2026-05-17
+
+### Security and Correctness
+
+- Harden DeepSec-reported temp path handling, private secret writes, pinned helper commits, fallback mkdir writes, and dot-prefixed root relative paths against symlink, race, and relative-path edge cases.
+
 ## 0.2.5 - 2026-05-16
 
 ### Security and Correctness

package/README.md

@@ -66,7 +66,7 @@ before first use when you need a strict environment policy:
 import { configureFsSafePython } from "@openclaw/fs-safe";
 
 configureFsSafePython({ mode: "auto" });    // default: use helper, fall back if unavailable
-configureFsSafePython({ mode: "off" });     // never spawn Python; use Node fallbacks
+configureFsSafePython({ mode: "off" });     // never spawn Python; use best-effort Node fallbacks
 configureFsSafePython({ mode: "require" }); // fail closed if helper cannot start
 ```
 

package/dist/archive-deadline.d.ts

@@ -0,0 +1,9 @@
+export type ExtractionDeadline = {
+    signal: AbortSignal;
+    check: () => void;
+    dispose: () => void;
+};
+export declare function createPipelineTimeoutError(err: unknown, deadline: ExtractionDeadline): unknown;
+export declare function waitForDeadline<T>(promise: Promise<T>, deadline: ExtractionDeadline): Promise<T>;
+export declare function withExtractionDeadline<T>(timeoutMs: number, label: string, run: (deadline: ExtractionDeadline) => Promise<T>): Promise<T>;
+//# sourceMappingURL=archive-deadline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-deadline.d.ts","sourceRoot":"","sources":["../src/archive-deadline.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAWF,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAST;AAED,wBAAsB,eAAe,CAAC,CAAC,EACrC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAAC,CAAC,CAAC,CAgBZ;AA4BD,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,CAAC,CAAC,CAAC,GAChD,OAAO,CAAC,CAAC,CAAC,CAQZ"}

package/dist/archive-deadline.js

@@ -0,0 +1,67 @@
+function signalReason(signal, fallback) {
+    const reason = signal.reason;
+    return reason instanceof Error ? reason : fallback ?? new Error(String(reason));
+}
+function deadlineReason(deadline) {
+    return signalReason(deadline.signal);
+}
+export function createPipelineTimeoutError(err, deadline) {
+    if (deadline.signal.aborted &&
+        err instanceof Error &&
+        (err.name === "AbortError" || err.message === "The operation was aborted")) {
+        return deadlineReason(deadline);
+    }
+    return err;
+}
+export async function waitForDeadline(promise, deadline) {
+    deadline.check();
+    if (deadline.signal.aborted) {
+        throw deadlineReason(deadline);
+    }
+    return await Promise.race([
+        promise,
+        new Promise((_, reject) => {
+            const abort = () => reject(deadlineReason(deadline));
+            deadline.signal.addEventListener("abort", abort, { once: true });
+            const cleanup = () => {
+                deadline.signal.removeEventListener("abort", abort);
+            };
+            promise.then(cleanup, cleanup);
+        }),
+    ]);
+}
+function createExtractionDeadline(timeoutMs, label) {
+    const controller = new AbortController();
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        return {
+            signal: controller.signal,
+            check: () => undefined,
+            dispose: () => undefined,
+        };
+    }
+    const timeoutError = new Error(`${label} timed out after ${timeoutMs}ms`);
+    const timeoutId = setTimeout(() => {
+        controller.abort(timeoutError);
+    }, timeoutMs);
+    return {
+        signal: controller.signal,
+        check: () => {
+            if (controller.signal.aborted) {
+                throw signalReason(controller.signal, timeoutError);
+            }
+        },
+        dispose: () => {
+            clearTimeout(timeoutId);
+        },
+    };
+}
+export async function withExtractionDeadline(timeoutMs, label, run) {
+    const deadline = createExtractionDeadline(timeoutMs, label);
+    try {
+        deadline.check();
+        return await waitForDeadline(run(deadline), deadline);
+    }
+    finally {
+        deadline.dispose();
+    }
+}

package/dist/archive-file-io.d.ts

@@ -0,0 +1,9 @@
+import type { FileHandle } from "node:fs/promises";
+import type { ExtractionDeadline } from "./archive-deadline.js";
+export declare function writeFileHandleFully(params: {
+    handle: FileHandle;
+    buffer: Buffer;
+    bytes: number;
+    deadline: ExtractionDeadline;
+}): Promise<void>;
+//# sourceMappingURL=archive-file-io.d.ts.map

package/dist/archive-file-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-file-io.d.ts","sourceRoot":"","sources":["../src/archive-file-io.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,kBAAkB,CAAC;CAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CAchB"}

package/dist/archive-file-io.js

@@ -0,0 +1,11 @@
+export async function writeFileHandleFully(params) {
+    let offset = 0;
+    while (offset < params.bytes) {
+        params.deadline.check();
+        const { bytesWritten } = await params.handle.write(params.buffer, offset, params.bytes - offset);
+        if (bytesWritten <= 0) {
+            throw new Error("archive staging write made no progress");
+        }
+        offset += bytesWritten;
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AAiBA,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;AAkCD,wBAAsB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BnF;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,CAmChB;AAiGD,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"}
+{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AAiBA,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;AAkCD,wBAAsB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BnF;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,CAmChB;AAyHD,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,CA6Bb;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,CAgFhB;AAED,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,CAE7F"}

package/dist/archive-staging.js

@@ -195,6 +195,16 @@ async function assertExtractedFileHasNoHardlinkAlias(params) {
 }
 async function removeExtractedDestinationFile(params) {
     const destinationPath = path.join(params.destinationRealDir, params.relPath);
+    let stat;
+    try {
+        stat = await fs.lstat(destinationPath);
+    }
+    catch {
+        return;
+    }
+    if (!stat.isFile()) {
+        return;
+    }
     let resolved;
     try {
         resolved = await fs.realpath(destinationPath);
@@ -205,7 +215,19 @@ async function removeExtractedDestinationFile(params) {
     if (!isPathInside(params.destinationRealDir, resolved)) {
         return;
     }
-    await fs.rm(destinationPath, { force: true }).catch(() => undefined);
+    const targetRoot = await root(params.destinationRealDir);
+    await targetRoot.remove(params.relPath).catch(() => undefined);
+}
+function assertSafeArchiveStagingPrefix(prefix) {
+    if (!prefix ||
+        prefix === "." ||
+        prefix === ".." ||
+        prefix.includes("/") ||
+        prefix.includes("\\") ||
+        path.basename(prefix) !== prefix) {
+        throw new Error("archive staging prefix must be a single path segment");
+    }
+    return prefix;
 }
 export async function withStagedArchiveDestination(params) {
     const stagingRoot = resolveSecureTempRoot({
@@ -216,20 +238,34 @@ export async function withStagedArchiveDestination(params) {
     if (isPathInside(params.destinationRealDir, stagingRoot)) {
         throw new Error(`archive staging root must be outside destination: ${stagingRoot}`);
     }
-    const stagingDir = await fs.mkdtemp(path.join(stagingRoot, params.stagingDirPrefix ?? "fs-safe-archive-"));
+    const stagingPrefix = assertSafeArchiveStagingPrefix(params.stagingDirPrefix ?? "fs-safe-archive-");
+    const stagingDir = await fs.mkdtemp(path.join(stagingRoot, stagingPrefix));
+    const stagingGuard = await createDirectoryIdentityGuard(stagingDir);
     try {
         await fs.chmod(stagingDir, ARCHIVE_STAGING_MODE).catch(() => undefined);
+        await assertDirectoryIdentityGuard(stagingGuard);
         return await params.run(stagingDir);
     }
     finally {
-        await fs.rm(stagingDir, { recursive: true, force: true }).catch(() => undefined);
+        try {
+            await assertDirectoryIdentityGuard(stagingGuard);
+            await fs.rm(stagingDir, { recursive: true, force: true }).catch(() => undefined);
+        }
+        catch {
+            // The staging path identity changed; deleting by name could target data
+            // outside the private temp tree, so fail closed and leave it for OS cleanup.
+        }
     }
 }
 export async function mergeExtractedTreeIntoDestination(params) {
     const targetRoot = await root(params.destinationRealDir);
+    const sourceRootGuard = await createDirectoryIdentityGuard(params.sourceDir);
+    const sourceRootReal = sourceRootGuard.realPath;
     const walk = async (currentSourceDir) => {
+        await assertDirectoryIdentityGuard(sourceRootGuard);
         const entries = await fs.readdir(currentSourceDir, { withFileTypes: true });
         for (const entry of entries) {
+            await assertDirectoryIdentityGuard(sourceRootGuard);
             const sourcePath = path.join(currentSourceDir, entry.name);
             const relPath = path.relative(params.sourceDir, sourcePath);
             const originalPath = relPath.split(path.sep).join("/");
@@ -238,6 +274,10 @@ export async function mergeExtractedTreeIntoDestination(params) {
             if (sourceStat.isSymbolicLink()) {
                 throw symlinkTraversalError(originalPath);
             }
+            const sourceReal = await fs.realpath(sourcePath);
+            if (!isPathInside(sourceRootReal, sourceReal)) {
+                throw symlinkTraversalError(originalPath);
+            }
             if (sourceStat.isDirectory()) {
                 await prepareArchiveOutputPath({
                     destinationDir: params.destinationDir,

package/dist/archive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AAWA,OAAO,EAOL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAgBzE,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC,CAAC;AAEF,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,6BAA6B,EAC7B,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EACL,kCAAkC,EAClC,iCAAiC,EACjC,4BAA4B,EAC5B,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,8BAA8B,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,KAAK,mBAAmB,GACzB,MAAM,4BAA4B,CAAC;AA8MpC,wBAAsB,cAAc,CAAC,MAAM,EAAE;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyEhB"}
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AAkBA,OAAO,EAOL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAiBzE,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC,CAAC;AAEF,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,6BAA6B,EAC7B,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EACL,kCAAkC,EAClC,iCAAiC,EACjC,4BAA4B,EAC5B,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,8BAA8B,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,KAAK,mBAAmB,GACzB,MAAM,4BAA4B,CAAC;AAuTpC,wBAAsB,cAAc,CAAC,MAAM,EAAE;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6EhB"}

package/dist/archive.js

@@ -4,13 +4,16 @@ import path from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
+import { createPipelineTimeoutError, waitForDeadline, withExtractionDeadline, } from "./archive-deadline.js";
+import { writeFileHandleFully } from "./archive-file-io.js";
 import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, assertArchiveEntryCountWithinLimit, createByteBudgetTracker, createExtractBudgetTransform, resolveExtractLimits, } from "./archive-limits.js";
 import { resolveArchiveKind } from "./archive-kind.js";
 import { mergeExtractedTreeIntoDestination, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
 import { createTarEntryPreflightChecker, readTarEntryInfo, } from "./archive-tar.js";
 import { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
+import { sameFileIdentity } from "./file-identity.js";
 import { writeSiblingTempFile } from "./sibling-temp.js";
-import { withTimeout } from "./timing.js";
+import { tempFile } from "./temp-target.js";
 export { isWindowsDrivePath, normalizeArchiveEntryPath, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
 export { resolveArchiveKind, resolvePackedRootDir } from "./archive-kind.js";
 export { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, DEFAULT_MAX_ARCHIVE_BYTES_ZIP, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_EXTRACTED_BYTES, DEFAULT_MAX_ENTRY_BYTES, } from "./archive-limits.js";
@@ -29,6 +32,85 @@ function isZipSymlinkEntry(entry) {
     return (typeof entry.unixPermissions === "number" &&
         (entry.unixPermissions & ZIP_UNIX_FILE_TYPE_MASK) === ZIP_UNIX_SYMLINK_TYPE);
 }
+function zipEntryFileMode(entry) {
+    if (typeof entry.unixPermissions !== "number") {
+        return undefined;
+    }
+    const mode = entry.unixPermissions & 0o777;
+    return mode === 0 ? undefined : mode;
+}
+async function cleanupStagedArchiveFile(staged) {
+    if (staged) {
+        await staged.cleanup().catch(() => undefined);
+    }
+}
+async function closeFileHandle(handle) {
+    if (handle) {
+        await handle.close().catch(() => undefined);
+    }
+}
+async function stageArchiveFileForExtraction(params) {
+    params.deadline.check();
+    const sourcePath = path.resolve(params.archivePath);
+    const initialStat = await fs.lstat(sourcePath);
+    if (initialStat.isSymbolicLink() || !initialStat.isFile()) {
+        throw new Error(`archive is not a regular file: ${params.archivePath}`);
+    }
+    if (initialStat.size > params.limits.maxArchiveBytes) {
+        throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT);
+    }
+    const noFollow = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants ? fsConstants.O_NOFOLLOW : 0;
+    const handle = await fs.open(sourcePath, fsConstants.O_RDONLY | noFollow);
+    let staged;
+    let output;
+    try {
+        staged = await tempFile({
+            prefix: "fs-safe-archive-input",
+            fileName: path.basename(sourcePath),
+        });
+        const openedStat = await handle.stat();
+        const pathStat = await fs.lstat(sourcePath);
+        if (!openedStat.isFile() ||
+            pathStat.isSymbolicLink() ||
+            !pathStat.isFile() ||
+            !sameFileIdentity(initialStat, openedStat) ||
+            !sameFileIdentity(pathStat, openedStat)) {
+            throw new Error("archive changed during validation");
+        }
+        output = await fs.open(staged.path, OPEN_WRITE_CREATE_FLAGS, 0o600);
+        const buffer = Buffer.allocUnsafe(64 * 1024);
+        let written = 0;
+        while (true) {
+            params.deadline.check();
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
+            if (bytesRead === 0) {
+                break;
+            }
+            written += bytesRead;
+            if (written > params.limits.maxArchiveBytes) {
+                throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT);
+            }
+            await writeFileHandleFully({
+                handle: output,
+                buffer,
+                bytes: bytesRead,
+                deadline: params.deadline,
+            });
+            params.deadline.check();
+        }
+        await output.close();
+        output = undefined;
+        return staged;
+    }
+    catch (err) {
+        await closeFileHandle(output);
+        await cleanupStagedArchiveFile(staged);
+        throw err;
+    }
+    finally {
+        await closeFileHandle(handle);
+    }
+}
 async function readZipEntryStream(entry) {
     if (typeof entry.nodeStream === "function") {
         return entry.nodeStream();
@@ -57,6 +139,7 @@ async function prepareZipOutputPath(params) {
     await prepareArchiveOutputPath(params);
 }
 async function writeZipFileEntry(params) {
+    params.deadline.check();
     params.budget.startEntry();
     const readable = await readZipEntryStream(params.entry);
     const destinationPath = params.outPath;
@@ -67,13 +150,20 @@ async function writeZipFileEntry(params) {
             dir: path.dirname(destinationPath),
             tempPrefix: `.${path.basename(destinationPath)}.fs-safe-archive`,
             chmodDir: false,
+            mode: zipEntryFileMode(params.entry),
             writeTemp: async (tempPath) => {
                 tempHandle = await fs.open(tempPath, OPEN_WRITE_CREATE_FLAGS, 0o666);
                 const writable = tempHandle.createWriteStream();
                 writable.once("close", () => {
                     handleClosedByStream = true;
                 });
-                await pipeline(readable, createExtractBudgetTransform({ onChunkBytes: params.budget.addBytes }), writable);
+                try {
+                    await pipeline(readable, createExtractBudgetTransform({ onChunkBytes: params.budget.addBytes }), writable, { signal: params.deadline.signal });
+                }
+                catch (err) {
+                    throw createPipelineTimeoutError(err, params.deadline);
+                }
+                params.deadline.check();
                 if (!handleClosedByStream) {
                     await tempHandle.close().catch(() => undefined);
                     handleClosedByStream = true;
@@ -83,13 +173,6 @@ async function writeZipFileEntry(params) {
             },
             resolveFinalPath: (filePath) => filePath,
         });
-        // Best-effort permission restore for zip entries created on unix.
-        if (typeof params.entry.unixPermissions === "number") {
-            const mode = params.entry.unixPermissions & 0o777;
-            if (mode !== 0) {
-                await fs.chmod(destinationPath, mode).catch(() => undefined);
-            }
-        }
     }
     catch (err) {
         // Failures here happen before the temp has been committed. The destination
@@ -105,57 +188,70 @@ async function writeZipFileEntry(params) {
 }
 async function extractZip(params) {
     const limits = resolveExtractLimits(params.limits);
-    const destinationRealDir = await prepareArchiveDestinationDir(params.destDir);
-    const stat = await fs.stat(params.archivePath);
-    if (stat.size > limits.maxArchiveBytes) {
-        throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT);
-    }
-    const buffer = await fs.readFile(params.archivePath);
-    const zip = await loadZipArchiveWithPreflight(buffer, limits);
-    const entries = Object.values(zip.files);
-    const strip = Math.max(0, Math.floor(params.stripComponents ?? 0));
-    assertArchiveEntryCountWithinLimit(entries.length, limits);
-    const budget = createByteBudgetTracker(limits);
-    await withStagedArchiveDestination({
-        destinationRealDir,
-        run: async (stagingDir) => {
-            const stagingRealDir = await fs.realpath(stagingDir);
-            for (const entry of entries) {
-                const output = resolveZipOutputPath({
-                    entryPath: entry.name,
-                    strip,
-                    destinationDir: stagingRealDir,
-                });
-                if (!output) {
-                    continue;
-                }
-                await prepareZipOutputPath({
-                    destinationDir: stagingRealDir,
-                    destinationRealDir: stagingRealDir,
-                    relPath: output.relPath,
-                    outPath: output.outPath,
-                    originalPath: entry.name,
-                    isDirectory: entry.dir,
-                });
-                if (entry.dir) {
-                    continue;
-                }
-                if (isZipSymlinkEntry(entry)) {
-                    throw new Error(`zip entry is a link: ${entry.name}`);
+    const stagedArchive = await stageArchiveFileForExtraction({
+        archivePath: params.archivePath,
+        limits,
+        deadline: params.deadline,
+    });
+    try {
+        const destinationRealDir = await prepareArchiveDestinationDir(params.destDir);
+        params.deadline.check();
+        const buffer = await fs.readFile(stagedArchive.path, { signal: params.deadline.signal });
+        params.deadline.check();
+        const zip = await waitForDeadline(loadZipArchiveWithPreflight(buffer, limits), params.deadline);
+        params.deadline.check();
+        const entries = Object.values(zip.files);
+        const strip = Math.max(0, Math.floor(params.stripComponents ?? 0));
+        assertArchiveEntryCountWithinLimit(entries.length, limits);
+        const budget = createByteBudgetTracker(limits);
+        await withStagedArchiveDestination({
+            destinationRealDir,
+            run: async (stagingDir) => {
+                const stagingRealDir = await fs.realpath(stagingDir);
+                for (const entry of entries) {
+                    params.deadline.check();
+                    const output = resolveZipOutputPath({
+                        entryPath: entry.name,
+                        strip,
+                        destinationDir: stagingRealDir,
+                    });
+                    if (!output) {
+                        continue;
+                    }
+                    await prepareZipOutputPath({
+                        destinationDir: stagingRealDir,
+                        destinationRealDir: stagingRealDir,
+                        relPath: output.relPath,
+                        outPath: output.outPath,
+                        originalPath: entry.name,
+                        isDirectory: entry.dir,
+                    });
+                    if (entry.dir) {
+                        continue;
+                    }
+                    if (isZipSymlinkEntry(entry)) {
+                        throw new Error(`zip entry is a link: ${entry.name}`);
+                    }
+                    await writeZipFileEntry({
+                        entry,
+                        outPath: output.outPath,
+                        budget,
+                        deadline: params.deadline,
+                    });
                 }
-                await writeZipFileEntry({
-                    entry,
-                    outPath: output.outPath,
-                    budget,
+                params.deadline.check();
+                await mergeExtractedTreeIntoDestination({
+                    sourceDir: stagingRealDir,
+                    destinationDir: params.destDir,
+                    destinationRealDir,
                 });
-            }
-            await mergeExtractedTreeIntoDestination({
-                sourceDir: stagingRealDir,
-                destinationDir: params.destDir,
-                destinationRealDir,
-            });
-        },
-    });
+                params.deadline.check();
+            },
+        });
+    }
+    finally {
+        await stagedArchive.cleanup();
+    }
 }
 export async function extractArchive(params) {
     const kind = params.kind ?? resolveArchiveKind(params.archivePath);
@@ -164,62 +260,74 @@ export async function extractArchive(params) {
     }
     const label = kind === "zip" ? "extract zip" : "extract tar";
     if (kind === "tar") {
-        await withTimeout((async () => {
+        await withExtractionDeadline(params.timeoutMs, label, async (deadline) => {
             const tar = await importOptionalTar();
             const limits = resolveExtractLimits(params.limits);
-            const stat = await fs.stat(params.archivePath);
-            if (stat.size > limits.maxArchiveBytes) {
-                throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT);
-            }
-            const destinationRealDir = await prepareArchiveDestinationDir(params.destDir);
-            await withStagedArchiveDestination({
-                destinationRealDir,
-                run: async (stagingDir) => {
-                    const checkTarEntrySafety = createTarEntryPreflightChecker({
-                        rootDir: destinationRealDir,
-                        stripComponents: params.stripComponents,
-                        limits,
-                    });
-                    // A canonical cwd is not enough here: tar can still follow
-                    // pre-existing child symlinks in the live destination tree.
-                    // Extract into a private staging dir first, then merge through
-                    // the same safe-open boundary checks used by direct file writes.
-                    await tar.x({
-                        file: params.archivePath,
-                        cwd: stagingDir,
-                        strip: Math.max(0, Math.floor(params.stripComponents ?? 0)),
-                        gzip: params.tarGzip,
-                        preservePaths: false,
-                        strict: true,
-                        onReadEntry(entry) {
-                            try {
-                                checkTarEntrySafety(readTarEntryInfo(entry));
-                            }
-                            catch (err) {
-                                const error = err instanceof Error ? err : new Error(String(err));
-                                // Node's EventEmitter calls listeners with `this` bound to the
-                                // emitter (tar.Unpack), which exposes Parser.abort().
-                                const emitter = this;
-                                emitter.abort?.(error);
-                            }
-                        },
-                    });
-                    await mergeExtractedTreeIntoDestination({
-                        sourceDir: stagingDir,
-                        destinationDir: params.destDir,
-                        destinationRealDir,
-                    });
-                },
+            const stagedArchive = await stageArchiveFileForExtraction({
+                archivePath: params.archivePath,
+                limits,
+                deadline,
             });
-        })(), params.timeoutMs, label);
+            try {
+                const destinationRealDir = await prepareArchiveDestinationDir(params.destDir);
+                await withStagedArchiveDestination({
+                    destinationRealDir,
+                    run: async (stagingDir) => {
+                        deadline.check();
+                        const checkTarEntrySafety = createTarEntryPreflightChecker({
+                            rootDir: destinationRealDir,
+                            stripComponents: params.stripComponents,
+                            limits,
+                        });
+                        // A canonical cwd is not enough here: tar can still follow
+                        // pre-existing child symlinks in the live destination tree.
+                        // Extract into a private staging dir first, then merge through
+                        // the same safe-open boundary checks used by direct file writes.
+                        await tar.x({
+                            file: stagedArchive.path,
+                            cwd: stagingDir,
+                            strip: Math.max(0, Math.floor(params.stripComponents ?? 0)),
+                            gzip: params.tarGzip,
+                            signal: deadline.signal,
+                            preservePaths: false,
+                            strict: true,
+                            onReadEntry(entry) {
+                                try {
+                                    deadline.check();
+                                    checkTarEntrySafety(readTarEntryInfo(entry));
+                                }
+                                catch (err) {
+                                    const error = err instanceof Error ? err : new Error(String(err));
+                                    // Node's EventEmitter calls listeners with `this` bound to the
+                                    // emitter (tar.Unpack), which exposes Parser.abort().
+                                    const emitter = this;
+                                    emitter.abort?.(error);
+                                }
+                            },
+                        });
+                        deadline.check();
+                        await mergeExtractedTreeIntoDestination({
+                            sourceDir: stagingDir,
+                            destinationDir: params.destDir,
+                            destinationRealDir,
+                        });
+                        deadline.check();
+                    },
+                });
+            }
+            finally {
+                await stagedArchive.cleanup();
+            }
+        });
         return;
     }
-    await withTimeout(extractZip({
+    await withExtractionDeadline(params.timeoutMs, label, async (deadline) => extractZip({
         archivePath: params.archivePath,
         destDir: params.destDir,
         stripComponents: params.stripComponents,
         limits: params.limits,
-    }), params.timeoutMs, label);
+        deadline,
+    }));
 }
 async function importOptionalTar() {
     try {

package/dist/file-store-boundary.js

@@ -5,7 +5,7 @@ import { Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { assertSyncDirectoryGuard as assertDirectoryGuardSync, createSyncDirectoryGuard, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
-import { isPathInside } from "./path.js";
+import { isPathInside, isPathRelativeEscape } from "./path.js";
 import { resolveOpenedFileRealPathForHandle, root } from "./root.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
 function parentRelativePath(relativePath) {
@@ -131,7 +131,7 @@ export function ensureParentSync(params) {
     const rootDir = path.resolve(params.rootDir);
     const dir = path.dirname(path.resolve(params.filePath));
     const relative = path.relative(rootDir, dir);
-    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    if (isPathRelativeEscape(relative)) {
         throw new FsSafeError("outside-workspace", "file path escapes store root");
     }
     syncFs.mkdirSync(rootDir, { recursive: true, mode: params.mode });

package/dist/guarded-mkdir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guarded-mkdir.d.ts","sourceRoot":"","sources":["../src/guarded-mkdir.ts"],"names":[],"mappings":"AAaA,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACnE,GAAG,OAAO,CAAC,IAAI,CAAC,CAiChB"}
+{"version":3,"file":"guarded-mkdir.d.ts","sourceRoot":"","sources":["../src/guarded-mkdir.ts"],"names":[],"mappings":"AAWA,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACnE,GAAG,OAAO,CAAC,IAAI,CAAC,CAkChB"}