@openclaw/fs-safe 0.2.6 → 0.2.7

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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

package/README.md

@@ -66,15 +66,18 @@ 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; writes that need it fail closed
+configureFsSafePython({ mode: "off" });     // never spawn Python; use best-effort Node fallbacks
 configureFsSafePython({ mode: "require" }); // fail closed if helper cannot start
 ```
 
 Equivalent env vars: `FS_SAFE_PYTHON_MODE=auto|off|require` and
-`FS_SAFE_PYTHON=/path/to/python3`. On POSIX, disabling or losing the helper now
-fails closed for root write paths that require fd-relative parent commits.
-Windows already uses the Node fallback path. See the
-[Python helper policy](docs/python-helper.md) for deployment guidance.
+`FS_SAFE_PYTHON=/path/to/python3`. Without Python, `fs-safe` keeps lexical and
+canonical root checks, no-follow opens, atomic temp+rename writes, and
+post-write identity verification. What you lose is the strongest POSIX
+fd-relative protection against a same-process-user racer swapping parent
+directories between validation and mutation. Windows already uses the Node
+fallback path. See the [Python helper policy](docs/python-helper.md) for
+deployment guidance.
 
 ## Quick start
 
@@ -432,7 +435,7 @@ Current `FsSafeErrorCode` values are `already-exists`, `hardlink`, `helper-faile
 - root-bounded APIs resolve paths against a configured root and reject canonical escapes
 - reads open with `O_NOFOLLOW` where available, then verify fd identity matches the path identity before returning the buffer or handle
 - writes use pinned parent-directory helpers and atomic replacement on POSIX, with verified post-write identity
-- `remove`, `mkdir`, `move`, `stat`, `list`, and parent-fd writes use one persistent fd-relative Python helper on POSIX; security-sensitive writes fail closed when that helper is disabled or unavailable
+- `remove`, `mkdir`, `move`, `stat`, `list`, and parent-fd writes use one persistent fd-relative Python helper on POSIX, with Node fallbacks when the helper is disabled or unavailable
 - archive extraction stages into a private directory and merges through the same boundary checks used by direct writes
 
 ## Limitations

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/json-durable-queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-durable-queue.d.ts","sourceRoot":"","sources":["../src/json-durable-queue.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAOF,eAAO,MAAM,0CAA0C,QAAmB,CAAC;AAY3E,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE;AAED,wBAAsB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpF;AAmBD,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,GACT,0BAA0B,CAM5B;AAED,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhB;AA+KD,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhB;AAiDD,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAW/F;AAED,wBAAsB,yBAAyB,CAAC,CAAC,EAAE,MAAM,EAAE;IACzD,KAAK,EAAE,0BAA0B,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAwBpB;AAED,wBAAsB,kCAAkC,CAAC,CAAC,EACxD,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,CAAC,EAAE,CAAC,CAkDd;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;CACZ,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB"}
+{"version":3,"file":"json-durable-queue.d.ts","sourceRoot":"","sources":["../src/json-durable-queue.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAOF,eAAO,MAAM,0CAA0C,QAAmB,CAAC;AAY3E,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE;AAED,wBAAsB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpF;AAmBD,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,GACT,0BAA0B,CAM5B;AAED,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhB;AA+KD,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhB;AAsDD,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAW/F;AAED,wBAAsB,yBAAyB,CAAC,CAAC,EAAE,MAAM,EAAE;IACzD,KAAK,EAAE,0BAA0B,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAwBpB;AAED,wBAAsB,kCAAkC,CAAC,CAAC,EACxD,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,CAAC,EAAE,CAAC,CAkDd;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;CACZ,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB"}

package/dist/json-durable-queue.js

@@ -215,6 +215,9 @@ async function readBoundedUtf8File(params) {
     if (initialStat.isSymbolicLink() || !initialStat.isFile()) {
         throw new Error("queue entry is not a regular file");
     }
+    if (initialStat.nlink > 1) {
+        throw new Error("queue entry hardlinks are not allowed");
+    }
     if (initialStat.size > params.maxBytes) {
         throw new Error(`queue entry exceeds ${params.maxBytes} bytes`);
     }
@@ -228,6 +231,8 @@ async function readBoundedUtf8File(params) {
         if (!openedStat.isFile() ||
             pathStat.isSymbolicLink() ||
             !pathStat.isFile() ||
+            openedStat.nlink > 1 ||
+            pathStat.nlink > 1 ||
             !sameFileIdentity(initialStat, openedStat) ||
             !sameFileIdentity(pathStat, openedStat)) {
             throw new Error("queue entry changed during read");

package/dist/output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,wBAAwB,CAAC,CAAC,GAAG,IAAI,IAAI;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,uBAAuB,CAAC,CAAC,GAAG,IAAI,IAAI;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AA6CF,wBAAsB,2BAA2B,CAAC,CAAC,GAAG,IAAI,EACxD,OAAO,EAAE,wBAAwB,CAAC,CAAC,CAAC,GACnC,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CA8BrC"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,wBAAwB,CAAC,CAAC,GAAG,IAAI,IAAI;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,uBAAuB,CAAC,CAAC,GAAG,IAAI,IAAI;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AA6CF,wBAAsB,2BAA2B,CAAC,CAAC,GAAG,IAAI,EACxD,OAAO,EAAE,wBAAwB,CAAC,CAAC,CAAC,GACnC,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CA+BrC"}

package/dist/output.js

@@ -42,6 +42,7 @@ export async function writeExternalFileWithinRoot(options) {
     if (requestedTargetPath.length === 0) {
         throw new FsSafeError("invalid-path", "target path is required");
     }
+    assertFileTargetPath(requestedTargetPath);
     const targetPath = toRootPathInput({
         rootDir: targetRoot.rootDir,
         rootReal: targetRoot.rootReal,

package/dist/pinned-write.js

@@ -67,7 +67,7 @@ export async function runPinnedWriteHelper(params) {
         relativeParentPath: params.relativeParentPath,
     });
     if (getFsSafePythonConfig().mode === "off") {
-        return await runPinnedWriteFallbackOrThrow(params);
+        return await runPinnedWriteFallback(params);
     }
     if (params.input.kind === "stream") {
         try {
@@ -75,7 +75,7 @@ export async function runPinnedWriteHelper(params) {
         }
         catch (error) {
             if (canFallbackFromPythonError(error)) {
-                return await runPinnedWriteFallbackOrThrow(params, error);
+                return await runPinnedWriteFallback(params);
             }
             throw error;
         }
@@ -99,7 +99,7 @@ export async function runPinnedWriteHelper(params) {
     }
     catch (error) {
         if (canFallbackFromPythonError(error)) {
-            return await runPinnedWriteFallbackOrThrow(params, error);
+            return await runPinnedWriteFallback(params);
         }
         throw error;
     }
@@ -126,12 +126,6 @@ export async function runPinnedCopyHelper(params) {
         },
     });
 }
-async function runPinnedWriteFallbackOrThrow(params, cause) {
-    if (process.platform !== "win32") {
-        throw new FsSafeError("helper-unavailable", "Python helper is required for pinned writes on this platform", { cause });
-    }
-    return await runPinnedWriteFallback(params);
-}
 async function runPinnedWriteFallback(params) {
     const parentPath = params.relativeParentPath
         ? path.join(params.rootPath, ...params.relativeParentPath.split("/"))

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,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
-import { isNotFoundPathError, isPathInside } from "./path.js";
+import { isNotFoundPathError, isPathInside, isPathRelativeEscape } from "./path.js";
 import { root as openRoot } from "./root.js";
 function invalidPath(scopeLabel) {
     return {
@@ -9,6 +9,10 @@ function invalidPath(scopeLabel) {
         error: `Invalid path: must stay within ${scopeLabel}`,
     };
 }
+function pathStaysWithinRoot(rootDir, candidatePath) {
+    const relative = path.relative(rootDir, candidatePath);
+    return Boolean(relative) && !isPathRelativeEscape(relative);
+}
 async function resolveRealPathIfExists(targetPath) {
     try {
         return await fs.realpath(targetPath);
@@ -58,11 +62,14 @@ export function resolvePathWithinRoot(params) {
         if (!params.defaultFileName) {
             return { ok: false, error: "path is required" };
         }
-        return { ok: true, path: path.join(root, params.defaultFileName) };
+        const defaultPath = path.resolve(root, params.defaultFileName);
+        if (!pathStaysWithinRoot(root, defaultPath)) {
+            return { ok: false, error: `Invalid path: must stay within ${params.scopeLabel}` };
+        }
+        return { ok: true, path: defaultPath };
     }
     const resolved = path.resolve(root, raw);
-    const rel = path.relative(root, resolved);
-    if (!rel || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+    if (!pathStaysWithinRoot(root, resolved)) {
         return { ok: false, error: `Invalid path: must stay within ${params.scopeLabel}` };
     }
     return { ok: true, path: resolved };
@@ -118,7 +125,7 @@ async function resolveNearestExistingPath(targetPath) {
 }
 async function assertNoSymlinkSegments(params) {
     const relative = path.relative(params.rootDir, params.targetPath);
-    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    if (isPathRelativeEscape(relative)) {
         throw new Error(`Invalid path: must stay within ${params.scopeLabel}`);
     }
     let current = params.rootDir;
@@ -195,6 +202,10 @@ export async function ensureDirectoryWithinRoot(params) {
                     }
                 }
             }
+            const currentReal = await fs.realpath(current);
+            if (!isPathInside(rootReal, currentReal)) {
+                return invalidPath(params.scopeLabel);
+            }
         }
         const targetReal = await fs.realpath(targetPath);
         if (!isPathInside(rootReal, targetReal)) {

package/dist/secret-file.d.ts

@@ -4,6 +4,7 @@ export declare const PRIVATE_SECRET_FILE_MODE = 384;
 export type SecretFileReadOptions = {
     maxBytes?: number;
     rejectSymlink?: boolean;
+    rejectHardlinks?: boolean;
 };
 export declare function readSecretFileSync(filePath: string, label: string, options?: SecretFileReadOptions): string;
 export declare function tryReadSecretFileSync(filePath: string | undefined, label: string, options?: SecretFileReadOptions): string | undefined;

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;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;AAoID,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,CA+ChB"}
+{"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;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAkIF,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,CAcpB;AAoID,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,CA+ChB"}

package/dist/secret-file.js

@@ -13,6 +13,10 @@ export const PRIVATE_SECRET_FILE_MODE = 0o600;
 function normalizeSecretReadError(error) {
     return error instanceof Error ? error : new Error(String(error));
 }
+function secretPathErrorCode(error) {
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR" ? "not-found" : "invalid-path";
+}
 function resolveUserPath(input) {
     return resolveHomeRelativePath(input);
 }
@@ -31,7 +35,7 @@ function readSecretFileOutcomeSync(filePath, label, options = {}) {
         const normalized = normalizeSecretReadError(error);
         return {
             ok: false,
-            code: error.code === "ENOENT" ? "not-found" : "invalid-path",
+            code: secretPathErrorCode(error),
             error: normalized,
             message: `Failed to inspect ${label} file at ${resolvedPath}: ${String(normalized)}`,
         };
@@ -45,7 +49,7 @@ function readSecretFileOutcomeSync(filePath, label, options = {}) {
                 const normalized = normalizeSecretReadError(error);
                 return {
                     ok: false,
-                    code: error.code === "ENOENT" ? "not-found" : "invalid-path",
+                    code: secretPathErrorCode(error),
                     error: normalized,
                     message: `Failed to inspect ${label} file at ${resolvedPath}: ${String(normalized)}`,
                 };
@@ -66,6 +70,13 @@ function readSecretFileOutcomeSync(filePath, label, options = {}) {
             message: `${label} file at ${resolvedPath} must be a regular file.`,
         };
     }
+    if (options.rejectHardlinks !== false && previewStat.nlink > 1) {
+        return {
+            ok: false,
+            code: "hardlink",
+            message: `${label} file at ${resolvedPath} must not be hardlinked.`,
+        };
+    }
     if (previewStat.size > maxBytes) {
         return {
             ok: false,
@@ -76,6 +87,7 @@ function readSecretFileOutcomeSync(filePath, label, options = {}) {
     const opened = openPinnedFileSync({
         filePath: resolvedPath,
         rejectPathSymlink: options.rejectSymlink,
+        rejectHardlinks: options.rejectHardlinks !== false,
         maxBytes,
     });
     if (!opened.ok) {
@@ -126,7 +138,15 @@ export function tryReadSecretFileSync(filePath, label, options = {}) {
         return undefined;
     }
     const result = readSecretFileOutcomeSync(filePath, label, options);
-    return result.ok ? result.secret : undefined;
+    if (result.ok) {
+        return result.secret;
+    }
+    if (result.code === "not-found") {
+        return undefined;
+    }
+    throw new FsSafeError(result.code, result.message, {
+        cause: result.error,
+    });
 }
 function isRelativeEscape(relativePath) {
     return relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath);

package/dist/sidecar-lock.d.ts.map

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

package/dist/sidecar-lock.js

@@ -34,8 +34,11 @@ async function readLockSnapshot(lockPath) {
             return { raw, payload: null, stat };
         }
     }
-    catch {
-        return null;
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return null;
+        }
+        throw err;
     }
 }
 function snapshotMatches(current, observed) {
@@ -86,7 +89,10 @@ async function removeStaleLockIfAllowed(params) {
     try {
         await fs.rm(params.lockPath, { force: true });
     }
-    catch {
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return "changed";
+        }
         return "not-approved";
     }
     return "removed";

package/dist/symlink-parents.js

@@ -1,12 +1,12 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { isNotFoundPathError } from "./path.js";
+import { isNotFoundPathError, isPathRelativeEscape } from "./path.js";
 function resolvePathWalk(params) {
     const root = path.resolve(params.rootDir);
     const target = path.resolve(params.targetPath);
     const relative = path.relative(root, target);
-    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    if (isPathRelativeEscape(relative)) {
         if (params.allowOutsideRoot) {
             return null;
         }

package/docs/python-helper.md

@@ -62,12 +62,12 @@ Node-only mode still keeps the important application-level guardrails:
 - root-relative path validation;
 - canonical root checks;
 - no-follow opens where Node/platform support exists;
-- file identity checks around reads and writes where a safe Node fallback exists;
-- atomic sibling-temp replacement on fallback platforms;
+- file identity checks around reads and writes;
+- atomic sibling-temp replacement;
 - hardlink/symlink policy checks where the API requests them;
 - byte limits and structured `FsSafeError` failures.
 
-What gets weaker is the POSIX defense against another same-UID process swapping a parent directory between validation and mutation. Write paths that need fd-relative parent commits now fail closed when the helper is disabled or unavailable; other operations such as `root().move()`, `root().remove()`, and `root().mkdir()` may still rely on Node path operations plus pre/post checks instead of parent-fd syscalls.
+What gets weaker is the POSIX defense against another same-UID process swapping a parent directory between validation and mutation. Without fd-relative mutation, `root().move()`, `root().remove()`, `root().mkdir()`, and some write paths rely on Node path operations plus pre/post checks instead of parent-fd syscalls.
 
 That is usually acceptable when the root directory is only writable by the trusted application user. It is not the right posture if untrusted local processes can race writes in the same tree and you are relying on `fs-safe` as part of the security boundary.
 

package/docs/root.md

@@ -102,14 +102,15 @@ operations that Node's `fs` API does not expose ergonomically.
 ```ts
 import { configureFsSafePython } from "@openclaw/fs-safe/config";
 
-configureFsSafePython({ mode: "off" });     // disable helper; some writes fail closed
+configureFsSafePython({ mode: "off" });     // Node-only fallback path
 configureFsSafePython({ mode: "require" }); // fail if fd-relative helper unavailable
 ```
 
-`auto` is the default. Configure the mode before creating roots. On POSIX,
-write methods that require fd-relative parent commits fail closed without the
-helper. Use `require` when any helper loss should be treated as a deployment
-failure. See [Python helper policy](python-helper.md) for deployment guidance.
+`auto` is the default. Configure the mode before creating roots. Without the
+helper, root methods still run, but same-UID races that swap parent directories
+between validation and mutation are harder to close completely. Use `require`
+when that downgrade should be treated as a deployment failure. See
+[Python helper policy](python-helper.md) for deployment guidance.
 
 ### Properties
 

package/docs/secret-file.md

@@ -36,7 +36,7 @@ The 16 KiB cap is intentionally aggressive — credentials should be small. If y
 
 ### `tryReadSecretFileSync(filePath, label, options?)`
 
-The lenient reader. Returns the trimmed secret string, or `undefined` when the path is missing, empty, unreadable, too large, or rejected by the validation checks.
+The lenient reader. Returns the trimmed secret string, or `undefined` when the path is missing or blank. Validation failures, unreadable files, oversized files, symlinks, and hardlinks throw `FsSafeError` so callers fail closed on suspicious credential state.
 
 ```ts
 import { tryReadSecretFileSync } from "@openclaw/fs-safe/secret";
@@ -63,10 +63,11 @@ const token = readSecretFileSync("/var/lib/app/auth.token");
 type SecretFileReadOptions = {
   maxBytes?: number;         // default DEFAULT_SECRET_FILE_MAX_BYTES (16 KiB)
   rejectSymlink?: boolean;
+  rejectHardlinks?: boolean; // default true
 };
 ```
 
-The reader trims the file content and rejects empty results. `rejectSymlink` blocks a symlink path before the pinned read.
+The reader trims the file content and rejects empty results. `rejectSymlink` blocks a symlink path before the pinned read. Hardlinks are rejected by default so another in-tree name cannot alias the credential; pass `rejectHardlinks: false` only when you explicitly trust that layout.
 
 ## Writing
 

package/docs/timing.md

@@ -102,7 +102,7 @@ await extractArchive({
 });
 ```
 
-`extractArchive` already takes `timeoutMs` and uses `withTimeout` internally — you don't need to wrap it. Reach for `withTimeout` for operations that don't carry their own timeout knob.
+`extractArchive` already takes `timeoutMs` and carries its own abort signal/deadline checks — you don't need to wrap it. Reach for `withTimeout` for operations that don't carry their own timeout knob.
 
 ### Disable in tests
 

package/package.json

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