@openclaw/fs-safe 0.5.6 → 0.6.0

package/dist/archive-zip-preflight.js

@@ -1,153 +1,14 @@
-import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, assertArchiveEntryCountWithinLimit, resolveExtractLimits, } from "./archive-limits.js";
+import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, resolveExtractLimits, } from "./archive-limits.js";
 import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
-const ZIP_EOCD_SIGNATURE = 0x06054b50;
-const ZIP64_EOCD_SIGNATURE = 0x06064b50;
-const ZIP64_EOCD_LOCATOR_SIGNATURE = 0x07064b50;
-const ZIP_EOCD_MIN_BYTES = 22;
-const ZIP_EOCD_MAX_COMMENT_BYTES = 0xffff;
-const ZIP64_ENTRY_COUNT_SENTINEL = 0xffff;
-const ZIP64_UINT32_SENTINEL = 0xffffffff;
-const ZIP_CENTRAL_FILE_HEADER_SIGNATURE = 0x02014b50;
-const ZIP_CENTRAL_FILE_HEADER_MIN_BYTES = 46;
-const ZIP_CENTRAL_FILE_HEADER_NAME_LENGTH_OFFSET = 28;
-const ZIP_CENTRAL_FILE_HEADER_EXTRA_LENGTH_OFFSET = 30;
-const ZIP_CENTRAL_FILE_HEADER_COMMENT_LENGTH_OFFSET = 32;
-const ZIP_EOCD_TOTAL_ENTRIES_OFFSET = 10;
-const ZIP_EOCD_CENTRAL_DIRECTORY_SIZE_OFFSET = 12;
-const ZIP_EOCD_CENTRAL_DIRECTORY_OFFSET_OFFSET = 16;
-const ZIP_EOCD_COMMENT_LENGTH_OFFSET = 20;
-const ZIP64_EOCD_LOCATOR_BYTES = 20;
-const ZIP64_EOCD_OFFSET_OFFSET = 8;
-const ZIP64_EOCD_TOTAL_ENTRIES_OFFSET = 32;
-const ZIP64_EOCD_CENTRAL_DIRECTORY_SIZE_OFFSET = 40;
-const ZIP64_EOCD_CENTRAL_DIRECTORY_OFFSET_OFFSET = 48;
-function asBufferView(buffer) {
-    if (Buffer.isBuffer(buffer)) {
-        return buffer;
-    }
-    return Buffer.from(buffer.buffer, buffer.byteOffset, buffer.byteLength);
-}
-function readSafeUInt64LE(buffer, offset) {
-    const value = buffer.readBigUInt64LE(offset);
-    if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
-        return Number.MAX_SAFE_INTEGER;
-    }
-    return Number(value);
-}
-function findZipEndOfCentralDirectory(buffer) {
-    if (buffer.byteLength < ZIP_EOCD_MIN_BYTES) {
-        return -1;
-    }
-    const minOffset = Math.max(0, buffer.byteLength - ZIP_EOCD_MIN_BYTES - ZIP_EOCD_MAX_COMMENT_BYTES);
-    for (let offset = buffer.byteLength - ZIP_EOCD_MIN_BYTES; offset >= minOffset; offset -= 1) {
-        if (buffer.readUInt32LE(offset) !== ZIP_EOCD_SIGNATURE) {
-            continue;
-        }
-        const commentLength = buffer.readUInt16LE(offset + ZIP_EOCD_COMMENT_LENGTH_OFFSET);
-        if (offset + ZIP_EOCD_MIN_BYTES + commentLength === buffer.byteLength) {
-            return offset;
-        }
-    }
-    return -1;
-}
-function readZip64CentralDirectoryInfo(buffer, eocdOffset) {
-    const locatorOffset = eocdOffset - ZIP64_EOCD_LOCATOR_BYTES;
-    if (locatorOffset < 0 || buffer.readUInt32LE(locatorOffset) !== ZIP64_EOCD_LOCATOR_SIGNATURE) {
-        return null;
-    }
-    const zip64EocdOffset = readSafeUInt64LE(buffer, locatorOffset + ZIP64_EOCD_OFFSET_OFFSET);
-    if (zip64EocdOffset < 0 ||
-        zip64EocdOffset + ZIP64_EOCD_CENTRAL_DIRECTORY_OFFSET_OFFSET + 8 > buffer.byteLength ||
-        buffer.readUInt32LE(zip64EocdOffset) !== ZIP64_EOCD_SIGNATURE) {
-        return null;
-    }
-    return {
-        declaredEntryCount: readSafeUInt64LE(buffer, zip64EocdOffset + ZIP64_EOCD_TOTAL_ENTRIES_OFFSET),
-        centralDirectorySize: readSafeUInt64LE(buffer, zip64EocdOffset + ZIP64_EOCD_CENTRAL_DIRECTORY_SIZE_OFFSET),
-        centralDirectoryOffset: readSafeUInt64LE(buffer, zip64EocdOffset + ZIP64_EOCD_CENTRAL_DIRECTORY_OFFSET_OFFSET),
-        endOfCentralDirectoryOffset: eocdOffset,
-    };
-}
-function readZipCentralDirectoryInfo(buffer) {
-    const eocdOffset = findZipEndOfCentralDirectory(buffer);
-    if (eocdOffset < 0) {
-        return null;
-    }
-    const declaredEntryCount = buffer.readUInt16LE(eocdOffset + ZIP_EOCD_TOTAL_ENTRIES_OFFSET);
-    const centralDirectorySize = buffer.readUInt32LE(eocdOffset + ZIP_EOCD_CENTRAL_DIRECTORY_SIZE_OFFSET);
-    const centralDirectoryOffset = buffer.readUInt32LE(eocdOffset + ZIP_EOCD_CENTRAL_DIRECTORY_OFFSET_OFFSET);
-    const usesZip64 = declaredEntryCount === ZIP64_ENTRY_COUNT_SENTINEL ||
-        centralDirectorySize === ZIP64_UINT32_SENTINEL ||
-        centralDirectoryOffset === ZIP64_UINT32_SENTINEL;
-    if (usesZip64) {
-        return (readZip64CentralDirectoryInfo(buffer, eocdOffset) ?? {
-            declaredEntryCount,
-            centralDirectoryOffset,
-            centralDirectorySize,
-            endOfCentralDirectoryOffset: eocdOffset,
-        });
-    }
-    return {
-        declaredEntryCount,
-        centralDirectoryOffset,
-        centralDirectorySize,
-        endOfCentralDirectoryOffset: eocdOffset,
-    };
-}
-function countZipCentralDirectoryHeaders(buffer, info) {
-    const start = info.centralDirectoryOffset;
-    const declaredEnd = start + info.centralDirectorySize;
-    const scanEnd = info.endOfCentralDirectoryOffset;
-    if (!Number.isSafeInteger(start) ||
-        !Number.isSafeInteger(declaredEnd) ||
-        !Number.isSafeInteger(scanEnd) ||
-        start < 0 ||
-        declaredEnd < start ||
-        scanEnd < start ||
-        scanEnd > buffer.byteLength) {
-        return null;
-    }
-    let offset = start;
-    let count = 0;
-    while (offset < scanEnd) {
-        if (scanEnd - offset < ZIP_CENTRAL_FILE_HEADER_MIN_BYTES) {
-            break;
-        }
-        if (buffer.readUInt32LE(offset) !== ZIP_CENTRAL_FILE_HEADER_SIGNATURE) {
-            break;
-        }
-        const nameLength = buffer.readUInt16LE(offset + ZIP_CENTRAL_FILE_HEADER_NAME_LENGTH_OFFSET);
-        const extraLength = buffer.readUInt16LE(offset + ZIP_CENTRAL_FILE_HEADER_EXTRA_LENGTH_OFFSET);
-        const commentLength = buffer.readUInt16LE(offset + ZIP_CENTRAL_FILE_HEADER_COMMENT_LENGTH_OFFSET);
-        const nextOffset = offset + ZIP_CENTRAL_FILE_HEADER_MIN_BYTES + nameLength + extraLength + commentLength;
-        if (nextOffset <= offset || nextOffset > scanEnd) {
-            return null;
-        }
-        count += 1;
-        offset = nextOffset;
-    }
-    return count > 0 || info.declaredEntryCount === 0 ? count : null;
-}
-export function readZipCentralDirectoryEntryCount(buffer) {
-    const view = asBufferView(buffer);
-    const info = readZipCentralDirectoryInfo(view);
-    if (!info) {
-        return null;
-    }
-    const countedEntryCount = countZipCentralDirectoryHeaders(view, info);
-    return countedEntryCount === null
-        ? info.declaredEntryCount
-        : Math.max(info.declaredEntryCount, countedEntryCount);
-}
+import { admitZipBuffer } from "./archive-zip-admission.js";
+import { validateArchiveEntryPath } from "./archive-entry.js";
+export { readZipCentralDirectoryEntryCount } from "./archive-zip-count.js";
 export async function loadZipArchiveWithPreflight(buffer, limits) {
     const resolvedLimits = resolveExtractLimits(limits);
     if (buffer.byteLength > resolvedLimits.maxArchiveBytes) {
         throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT);
     }
-    const entryCount = readZipCentralDirectoryEntryCount(buffer);
-    if (entryCount !== null) {
-        assertArchiveEntryCountWithinLimit(entryCount, resolvedLimits);
-    }
+    const entryCount = admitZipBuffer(buffer, resolvedLimits);
     const JSZip = await importOptionalJsZip();
     let archive;
     try {
@@ -156,9 +17,11 @@ export async function loadZipArchiveWithPreflight(buffer, limits) {
     catch (error) {
         throw new ArchiveFormatError(`invalid ZIP archive: ${error instanceof Error ? error.message : String(error)}`, { cause: error instanceof Error ? error : undefined });
     }
-    if (entryCount !== null && Object.keys(archive.files).length !== entryCount) {
+    if (Object.keys(archive.files).length !== entryCount) {
         throw new ArchiveSecurityError("entry-path", "zip archive contains duplicate or colliding entry names");
     }
+    for (const name of Object.keys(archive.files))
+        validateArchiveEntryPath(name);
     return archive;
 }
 async function importOptionalJsZip() {

package/dist/archive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AA6DA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACjF,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,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,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,6BAA6B,EAC7B,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,iCAAiC,EACjC,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACtF,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;AAoNpC,wBAAsB,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkKjF"}
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AA4DA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACjF,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,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,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,6BAA6B,EAC7B,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,iCAAiC,EACjC,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACtF,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;AAoNpC,wBAAsB,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwKjF"}

package/dist/archive.js

@@ -3,7 +3,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
-import { createArchiveOutputPathTracker, normalizeArchiveEntryPath, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
+import { createArchiveOutputPathTracker, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
 import { createPipelineTimeoutError, waitForDeadline, withExtractionDeadline, } from "./archive-deadline.js";
 import { assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWithinLimit, createByteBudgetTracker, createExtractBudgetTransform, resolveExtractLimits, } from "./archive-limits.js";
 import { resolveArchiveKind } from "./archive-kind.js";
@@ -155,6 +155,9 @@ async function extractZip(params) {
                     })) {
                         continue;
                     }
+                    if (isSymlink) {
+                        throw new ArchiveSecurityError("entry-link", `zip entry is a link: ${entry.name}`);
+                    }
                     const mode = zipEntryMode(entry, params.entryModes);
                     await prepareZipOutputPath({
                         destinationDir: stagingRealDir,
@@ -168,9 +171,6 @@ async function extractZip(params) {
                         await fs.chmod(output.outPath, mode);
                         continue;
                     }
-                    if (isSymlink) {
-                        throw new ArchiveSecurityError("entry-link", `zip entry is a link: ${entry.name}`);
-                    }
                     await writeZipFileEntry({
                         entry,
                         outPath: output.outPath,
@@ -216,7 +216,8 @@ export async function extractArchive(params) {
         return;
     }
     if (kind === "tar-zstd" || kind === "tar-bzip2") {
-        throw new FsSafeError("helper-unavailable", `${kind} archives require a supported bundled native binding`);
+        throw new FsSafeError("helper-unavailable", `${kind} archives require the matching optional native platform package; ` +
+            "install @openclaw/fs-safe with optional dependencies enabled on a supported platform and use FS_SAFE_NATIVE_MODE=auto or require");
     }
     if (kind === "tar") {
         await withExtractionDeadline(params.timeoutMs, label, async (deadline) => {
@@ -239,6 +240,7 @@ export async function extractArchive(params) {
                     destinationRealDir,
                     run: async (stagingDir) => {
                         deadline.check();
+                        const strip = Math.max(0, Math.floor(params.stripComponents ?? 0));
                         const checkTarEntrySafety = createTarEntryPreflightChecker({
                             rootDir: destinationRealDir,
                             stripComponents: params.stripComponents,
@@ -253,35 +255,42 @@ export async function extractArchive(params) {
                         // the same safe-open boundary checks used by direct file writes.
                         const extractor = tar.x({
                             cwd: stagingDir,
-                            strip: Math.max(0, Math.floor(params.stripComponents ?? 0)),
+                            // fs-safe owns stripping: node-tar counts the `.` and empty path
+                            // components that stripArchivePath() drops, so the two disagree.
+                            strip: 0,
                             gzip: params.tarGzip,
                             signal: deadline.signal,
                             preservePaths: false,
                             noChmod: true,
                             preserveOwner: false,
+                            noMtime: true,
                             strict: true,
                             maxMetaEntrySize: limits.maxMetaEntryBytes,
                             filter(_entryPath, entry) {
                                 try {
                                     const info = readTarEntryInfo(entry);
-                                    const accepted = checkTarEntrySafety(info);
-                                    if (accepted) {
-                                        entry.path = normalizeArchiveEntryPath(info.path);
-                                        const relPath = stripArchivePath(info.path, Math.max(0, Math.floor(params.stripComponents ?? 0)));
-                                        if (relPath) {
-                                            acceptedEntries.push({
-                                                path: relPath,
-                                                mode: resolveArchiveEntryMode({
-                                                    kind: info.type === "Directory" || info.type === "GNUDumpDir"
-                                                        ? "directory"
-                                                        : "file",
-                                                    archivedMode: info.mode,
-                                                    policy: params.entryModes,
-                                                }),
-                                            });
-                                        }
+                                    if (!checkTarEntrySafety(info)) {
+                                        return false;
+                                    }
+                                    const relPath = stripArchivePath(info.path, strip);
+                                    if (!relPath) {
+                                        return false;
                                     }
-                                    return accepted;
+                                    // Hand node-tar the exact path this entry was validated,
+                                    // limited and collision-checked under, and that the mode
+                                    // pass below resolves after extraction.
+                                    entry.path = relPath;
+                                    acceptedEntries.push({
+                                        path: relPath,
+                                        mode: resolveArchiveEntryMode({
+                                            kind: info.type === "Directory" || info.type === "GNUDumpDir"
+                                                ? "directory"
+                                                : "file",
+                                            archivedMode: info.mode,
+                                            policy: params.entryModes,
+                                        }),
+                                    });
+                                    return true;
                                 }
                                 catch (error) {
                                     // Abort through the parser so pipeline tears down both the

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

@@ -1 +1 @@
-{"version":3,"file":"file-hash.d.ts","sourceRoot":"","sources":["../src/file-hash.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAGnE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,UAAU,CAAC;AAElD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,EAClB,MAAM,GAAE,aAAa,GAAG,SAA8B,GACrD,OAAO,CAAC,gBAAgB,CAAC,CAoB3B;AA2CD,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAElF"}
+{"version":3,"file":"file-hash.d.ts","sourceRoot":"","sources":["../src/file-hash.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAInE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,UAAU,CAAC;AAElD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,EAClB,MAAM,GAAE,aAAa,GAAG,SAA8B,GACrD,OAAO,CAAC,gBAAgB,CAAC,CAoB3B;AA+CD,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAElF"}

package/dist/file-hash.js

@@ -1,9 +1,9 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.js";
 import { getNativeBinding } from "./native.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
 export async function hashFileHandle(handle, native = getNativeBinding()) {
     const stat = await handle.stat();
     if (!stat.isFile()) {
@@ -25,13 +25,16 @@ export async function hashFileHandle(handle, native = getNativeBinding()) {
     }
 }
 async function hashPath(filePath) {
-    const before = await fs.lstat(filePath);
-    if (before.isSymbolicLink()) {
-        throw new FsSafeError("symlink", "SHA-256 path must not be a symbolic link");
-    }
-    if (!before.isFile()) {
-        throw new FsSafeError("not-file", "SHA-256 path is not a regular file");
-    }
+    const before = await inspectFileIdentity(async () => {
+        const stat = await fs.lstat(filePath, { bigint: true });
+        if (stat.isSymbolicLink()) {
+            throw new FsSafeError("symlink", "SHA-256 path must not be a symbolic link");
+        }
+        if (!stat.isFile()) {
+            throw new FsSafeError("not-file", "SHA-256 path is not a regular file");
+        }
+        return stat;
+    });
     let handle;
     try {
         handle = await fs.open(filePath, resolveReadOpenFlags());
@@ -45,17 +48,20 @@ async function hashPath(filePath) {
         throw error;
     }
     try {
-        const opened = await handle.stat();
-        const current = await fs.lstat(filePath);
-        if (!opened.isFile()) {
-            throw new FsSafeError("not-file", "SHA-256 path is not a regular file");
-        }
-        if (current.isSymbolicLink() ||
-            !current.isFile() ||
-            !sameFileIdentity(before, opened) ||
-            !sameFileIdentity(opened, current)) {
-            throw new FsSafeError("path-mismatch", "SHA-256 path changed while opening");
-        }
+        const opened = await inspectFileIdentity(async () => {
+            const stat = await handle.stat({ bigint: true });
+            if (!stat.isFile()) {
+                throw new FsSafeError("not-file", "SHA-256 path is not a regular file");
+            }
+            return stat;
+        }, before);
+        await inspectFileIdentity(async () => {
+            const stat = await fs.lstat(filePath, { bigint: true });
+            if (stat.isSymbolicLink() || !stat.isFile()) {
+                throw new FsSafeError("path-mismatch", "SHA-256 path changed while opening");
+            }
+            return stat;
+        }, opened);
         return await hashFileHandle(handle);
     }
     finally {

package/dist/file-lock-sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-lock-sync.d.ts","sourceRoot":"","sources":["../src/file-lock-sync.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAOL,KAAK,wBAAwB,EAC9B,MAAM,2BAA2B,CAAC;AAKnC,OAAO,KAAK,EACV,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,yBAAyB,CAAC;AAGjC,MAAM,MAAM,0BAA0B,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,QAAQ,CAAC;IACxB,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,iBAAiB,EAAE,KAAK,CAAC;KAC1B,KAAK,OAAO,CAAC;IACd,qBAAqB,CAAC,EAAE,CAAC,QAAQ,EAAE,wBAAwB,KAAK,OAAO,CAAC;IACxE,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,0BAA0B,KAAK,IAAI,CAAC;IAC3D,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,IAAI,OAAO,CAAC;IAC3B,OAAO,IAAI,IAAI,CAAC;IAChB,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B,CAAC;AA0IF,wBAAgB,mBAAmB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,0BAA0B,CAAC,QAAQ,CAAC,GAC5C,kBAAkB,CAuJpB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,0BAA0B,CAAC,QAAQ,CAAC,EAC7C,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAOH"}
+{"version":3,"file":"file-lock-sync.d.ts","sourceRoot":"","sources":["../src/file-lock-sync.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAOL,KAAK,wBAAwB,EAC9B,MAAM,2BAA2B,CAAC;AAKnC,OAAO,KAAK,EACV,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,yBAAyB,CAAC;AAIjC,MAAM,MAAM,0BAA0B,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,QAAQ,CAAC;IACxB,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,iBAAiB,EAAE,KAAK,CAAC;KAC1B,KAAK,OAAO,CAAC;IACd,qBAAqB,CAAC,EAAE,CAAC,QAAQ,EAAE,wBAAwB,KAAK,OAAO,CAAC;IACxE,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,0BAA0B,KAAK,IAAI,CAAC;IAC3D,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,IAAI,OAAO,CAAC;IAC3B,OAAO,IAAI,IAAI,CAAC;IAChB,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B,CAAC;AA0IF,wBAAgB,mBAAmB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,0BAA0B,CAAC,QAAQ,CAAC,GAC5C,kBAAkB,CAkKpB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,0BAA0B,CAAC,QAAQ,CAAC,EAC7C,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAOH"}

package/dist/file-lock-sync.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { readSidecarLockSnapshotSync, relativeSidecarLockPath, removeSidecarLockIfUnchangedSync, serializeSidecarLockPayload, sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
 import { computeSidecarLockDelayMs, sidecarLockPayloadCreatedAtMs, } from "./sidecar-lock-policy.js";
+import { getFsSafeLockConfig } from "./lock-config.js";
 import { sleepSync } from "./timing.js";
 const SYNC_HELD_LOCKS_KEY = Symbol.for("fsSafe.syncSidecarLocks");
 const SYNC_CLEANUP_REGISTERED_KEY = Symbol.for("fsSafe.syncSidecarLockCleanupRegistered");
@@ -137,14 +138,19 @@ export function acquireFileLockSync(targetPath, options) {
         held.refCount += 1;
         return createSyncHeldLockHandle(held);
     }
-    const staleMs = options.staleMs ?? 30_000;
-    const retry = options.retry ?? {};
+    // Process defaults fill the same fields here as withLockDefaults() fills for
+    // the asynchronous manager, so both acquirers honor configureFsSafeLocks().
+    const defaults = getFsSafeLockConfig();
+    const staleMs = options.staleMs ?? defaults.staleMs ?? 30_000;
+    const retry = options.retry ?? defaults.retry ?? {};
+    const timeoutMs = options.timeoutMs ?? defaults.timeoutMs;
+    const staleRecovery = options.staleRecovery ?? defaults.staleRecovery;
     const startedAt = Date.now();
     let attempt = 0;
     const reclaimGuardPath = `${lockPath}.reclaim`;
     const waitForRetry = () => {
         const elapsed = Date.now() - startedAt;
-        const timedOut = options.timeoutMs !== undefined && elapsed >= options.timeoutMs;
+        const timedOut = timeoutMs !== undefined && elapsed >= timeoutMs;
         if (timedOut || (retry.retries !== undefined && attempt >= retry.retries)) {
             throw Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
                 code: "file_lock_timeout",
@@ -190,9 +196,15 @@ export function acquireFileLockSync(targetPath, options) {
             const returnedHandle = createSyncHeldLockHandle(createdHeld);
             if (options.onCompromised && (options.compromiseCheckIntervalMs ?? 0) > 0) {
                 createdHeld.timer = setInterval(() => {
-                    if (!returnedHandle.verifyStillHeld()) {
-                        if (createdHeld.timer)
-                            clearInterval(createdHeld.timer);
+                    let stillHeld;
+                    try {
+                        stillHeld = returnedHandle.verifyStillHeld();
+                    }
+                    catch {
+                        stillHeld = false;
+                    }
+                    if (!stillHeld && createdHeld.timer) {
+                        clearInterval(createdHeld.timer);
                         createdHeld.timer = undefined;
                         options.onCompromised?.({ lockPath, normalizedTargetPath });
                     }
@@ -232,7 +244,7 @@ export function acquireFileLockSync(targetPath, options) {
                 })
                 : defaultShouldReclaim(snapshot.payload, lockPath, staleMs, nowMs);
             if (reclaim) {
-                if (options.staleRecovery === "remove-if-unchanged" &&
+                if (staleRecovery === "remove-if-unchanged" &&
                     snapshot.raw !== undefined &&
                     options.shouldRemoveStaleLock?.({
                         lockPath,

package/dist/native-binding.d.ts

@@ -62,6 +62,9 @@ export interface NativeWindowsSecurityFacts {
     aces: NativeWindowsAccessControlEntry[];
 }
 export interface NativeBinding {
+    createStagedFile?(parentFd: number, basename: string): number;
+    stagedFileMatches?(parentFd: number, basename: string, fileFd: number): boolean;
+    removeStagedFile?(parentFd: number, basename: string, fileFd: number): "removed" | "name-absent" | "preserved";
     cloneFileExclusive(sourceFd: number, targetRootFd: number, targetRelPath: string): number;
     copyFileRangeExclusive(sourceFd: number, targetRootFd: number, targetRelPath: string): Promise<NativeCopyResult>;
     createPrivateDirectory(path: string): void;

package/dist/native-binding.d.ts.map

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

package/dist/native-operations.d.ts

@@ -1,6 +1,7 @@
 import { type Stats } from "node:fs";
 import type { ContainmentGuarantee } from "./containment.js";
 import { type NativeBinding } from "./native.js";
+import type { PinnedWriteInput } from "./pinned-write.js";
 export type NativeFileHandle = {
     readonly fd: number;
     readonly containment: ContainmentGuarantee;
@@ -8,6 +9,9 @@ export type NativeFileHandle = {
     stat(): Promise<Stats>;
     writeFile(data: string | Buffer, encoding?: BufferEncoding): Promise<void>;
 };
+export declare function nativeOpenFlags(flags: number): number;
+export declare function writeNativeFd(fd: number, data: Buffer): void;
+export declare function writeNativeInput(fd: number, input: PinnedWriteInput, maxBytes?: number): Promise<void>;
 export declare function removeNativeCreatedFileIfStillPinned(params: {
     binding: NativeBinding;
     parentPath: string;
@@ -17,5 +21,4 @@ export declare function removeNativeCreatedFileIfStillPinned(params: {
 }): void;
 export declare function createNativeExclusiveFile(targetPath: string, mode: number): Promise<NativeFileHandle | undefined>;
 export declare function syncNativeFileBestEffort(fd: number): void;
-export declare function writeNativeFd(fd: number, data: Buffer): void;
 //# sourceMappingURL=native-operations.d.ts.map

package/dist/native-operations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-operations.d.ts","sourceRoot":"","sources":["../src/native-operations.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAG7C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE7D,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEnE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5E,CAAC;AA0CF,wBAAgB,oCAAoC,CAAC,MAAM,EAAE;IAC3D,OAAO,EAAE,aAAa,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,KAAK,CAAC;CACjB,GAAG,IAAI,CAsBP;AAED,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAyDvC;AAED,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAQzD;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE5D"}
+{"version":3,"file":"native-operations.d.ts","sourceRoot":"","sources":["../src/native-operations.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAG7C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAG7D,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5E,CAAC;AAEF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOrD;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAS5D;AAED,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,gBAAgB,EACvB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAgBf;AAsBD,wBAAgB,oCAAoC,CAAC,MAAM,EAAE;IAC3D,OAAO,EAAE,aAAa,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,KAAK,CAAC;CACjB,GAAG,IAAI,CAsBP;AAED,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAyDvC;AAED,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAQzD"}

package/dist/native-operations.js

@@ -1,15 +1,16 @@
 import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { FsSafeError } from "./errors.js";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
 import { getNativeBinding } from "./native.js";
-function nativeOpenFlags(flags) {
+export function nativeOpenFlags(flags) {
     const closeOnExec = fsSync.constants.O_CLOEXEC;
     return (flags |
         (closeOnExec ?? 0) |
         (typeof fsSync.constants.O_NOFOLLOW === "number" ? fsSync.constants.O_NOFOLLOW : 0));
 }
-function writeAll(fd, data) {
+export function writeNativeFd(fd, data) {
     let offset = 0;
     while (offset < data.byteLength) {
         const written = fsSync.writeSync(fd, data, offset, data.byteLength - offset);
@@ -19,6 +20,24 @@ function writeAll(fd, data) {
         offset += written;
     }
 }
+export async function writeNativeInput(fd, input, maxBytes) {
+    let bytes = 0;
+    const write = (data) => {
+        bytes += data.byteLength;
+        if (maxBytes !== undefined && bytes > maxBytes) {
+            throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got at least ${bytes})`);
+        }
+        writeNativeFd(fd, data);
+    };
+    if (input.kind === "buffer") {
+        write(typeof input.data === "string" ? Buffer.from(input.data, input.encoding ?? "utf8") : input.data);
+    }
+    else {
+        for await (const chunk of input.stream) {
+            write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+    }
+}
 function wrapNativeFd(fd, containment) {
     let open = true;
     return {
@@ -34,7 +53,7 @@ function wrapNativeFd(fd, containment) {
             return fsSync.fstatSync(fd);
         },
         async writeFile(data, encoding) {
-            writeAll(fd, Buffer.isBuffer(data) ? data : Buffer.from(data, encoding ?? "utf8"));
+            writeNativeFd(fd, Buffer.isBuffer(data) ? data : Buffer.from(data, encoding ?? "utf8"));
         },
     };
 }
@@ -123,6 +142,3 @@ export function syncNativeFileBestEffort(fd) {
         }
     }
 }
-export function writeNativeFd(fd, data) {
-    writeAll(fd, data);
-}

package/dist/native-pinned-write-windows.d.ts

@@ -0,0 +1,8 @@
+import type { FileHandle } from "node:fs/promises";
+import type { AsyncDirectoryGuard } from "./directory-guard.js";
+import type { FileIdentityStat } from "./file-identity.js";
+import type { NativeBinding } from "./native.js";
+import type { PinnedWriteParams } from "./pinned-write.js";
+export declare function sameNativeIdentity(left: Pick<FileIdentityStat, "dev" | "ino">, right: Pick<FileIdentityStat, "dev" | "ino">): boolean;
+export declare function runPinnedWriteWindows(binding: NativeBinding, params: PinnedWriteParams, root: FileHandle, parentFd: number, parentGuard: AsyncDirectoryGuard): Promise<FileIdentityStat>;
+//# sourceMappingURL=native-pinned-write-windows.d.ts.map

package/dist/native-pinned-write-windows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-pinned-write-windows.d.ts","sourceRoot":"","sources":["../src/native-pinned-write-windows.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAO3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,KAAK,CAAC,EAC3C,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,KAAK,CAAC,GAC3C,OAAO,CAET;AAWD,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,mBAAmB,GAC/B,OAAO,CAAC,gBAAgB,CAAC,CAgF3B"}