@openclaw/fs-safe 0.4.7 → 0.5.0

package/dist/archive.js

@@ -1,22 +1,30 @@
-import { constants as fsConstants } from "node:fs";
+import fsSync, { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 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 { assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWithinLimit, 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 { isZipSymlinkEntry, zipEntryDeclaredSize, zipEntryMode, } from "./archive-zip-entry.js";
+import { FsSafeError } from "./errors.js";
+import { ArchiveSecurityError } from "./archive-errors.js";
+import { extractNativeArchive } from "./archive-native.js";
+import { stageArchiveFileForExtraction } from "./archive-input.js";
+import { getNativeBinding } from "./native.js";
+import { resolveArchiveEntryMode, shouldExtractArchiveEntry, } from "./archive-policy.js";
+import { importOptionalTar } from "./archive-tar-runtime.js";
+import { preflightTarMetadata } from "./archive-tar-meta.js";
 import { writeSiblingTempFile } from "./sibling-temp.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";
+export { readArchiveEntry } from "./archive-read.js";
+export { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, DEFAULT_MAX_ARCHIVE_BYTES_ZIP, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_EXTRACTED_BYTES, DEFAULT_MAX_ENTRY_BYTES, DEFAULT_MAX_META_ENTRY_BYTES, DEFAULT_MAX_ENTRY_PATH_COMPONENTS, } from "./archive-limits.js";
+export { ArchiveFormatError } from "./archive-errors.js";
 export { ArchiveSecurityError } from "./archive-staging.js";
 export { createArchiveSymlinkTraversalError, mergeExtractedTreeIntoDestination, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
 export { createTarEntryPreflightChecker } from "./archive-tar.js";
@@ -26,91 +34,6 @@ const OPEN_WRITE_CREATE_FLAGS = fsConstants.O_WRONLY |
     fsConstants.O_CREAT |
     fsConstants.O_EXCL |
     (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
-const ZIP_UNIX_FILE_TYPE_MASK = 0o170000;
-const ZIP_UNIX_SYMLINK_TYPE = 0o120000;
-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();
@@ -150,7 +73,7 @@ async function writeZipFileEntry(params) {
             dir: path.dirname(destinationPath),
             tempPrefix: `.${path.basename(destinationPath)}.fs-safe-archive`,
             chmodDir: false,
-            mode: zipEntryFileMode(params.entry),
+            mode: params.mode,
             writeTemp: async (tempPath) => {
                 tempHandle = await fs.open(tempPath, OPEN_WRITE_CREATE_FLAGS, 0o666);
                 const writable = tempHandle.createWriteStream();
@@ -218,6 +141,18 @@ async function extractZip(params) {
                     if (!output) {
                         continue;
                     }
+                    assertArchiveEntryPathComponentsWithinLimit(output.relPath, limits);
+                    const isSymlink = isZipSymlinkEntry(entry);
+                    const entryKind = isSymlink ? "symlink" : entry.dir ? "directory" : "file";
+                    const entrySize = zipEntryDeclaredSize(entry);
+                    if (!shouldExtractArchiveEntry({
+                        filter: params.entryFilter,
+                        onFiltered: params.onFiltered,
+                        entry: { path: entry.name, kind: entryKind, size: entrySize },
+                    })) {
+                        continue;
+                    }
+                    const mode = zipEntryMode(entry, params.entryModes);
                     await prepareZipOutputPath({
                         destinationDir: stagingRealDir,
                         destinationRealDir: stagingRealDir,
@@ -227,16 +162,18 @@ async function extractZip(params) {
                         isDirectory: entry.dir,
                     });
                     if (entry.dir) {
+                        await fs.chmod(output.outPath, mode);
                         continue;
                     }
-                    if (isZipSymlinkEntry(entry)) {
-                        throw new Error(`zip entry is a link: ${entry.name}`);
+                    if (isSymlink) {
+                        throw new ArchiveSecurityError("entry-link", `zip entry is a link: ${entry.name}`);
                     }
                     await writeZipFileEntry({
                         entry,
                         outPath: output.outPath,
                         budget,
                         deadline: params.deadline,
+                        mode,
                     });
                 }
                 params.deadline.check();
@@ -259,6 +196,25 @@ export async function extractArchive(params) {
         throw new Error(`unsupported archive: ${params.archivePath}`);
     }
     const label = kind === "zip" ? "extract zip" : "extract tar";
+    const native = getNativeBinding();
+    if (native) {
+        await withExtractionDeadline(params.timeoutMs, label, async (deadline) => extractNativeArchive({
+            binding: native,
+            archivePath: params.archivePath,
+            destDir: params.destDir,
+            kind,
+            stripComponents: params.stripComponents,
+            limits: params.limits,
+            deadline,
+            entryModes: params.entryModes,
+            entryFilter: params.entryFilter,
+            onFiltered: params.onFiltered,
+        }));
+        return;
+    }
+    if (kind === "tar-zstd" || kind === "tar-bzip2") {
+        throw new FsSafeError("helper-unavailable", `${kind} archives require a supported bundled native binding`);
+    }
     if (kind === "tar") {
         await withExtractionDeadline(params.timeoutMs, label, async (deadline) => {
             const tar = await importOptionalTar();
@@ -269,6 +225,12 @@ export async function extractArchive(params) {
                 deadline,
             });
             try {
+                await preflightTarMetadata({
+                    archivePath: stagedArchive.path,
+                    maxMetaEntryBytes: limits.maxMetaEntryBytes,
+                    signal: deadline.signal,
+                });
+                deadline.check();
                 const destinationRealDir = await prepareArchiveDestinationDir(params.destDir);
                 await withStagedArchiveDestination({
                     destinationRealDir,
@@ -278,23 +240,56 @@ export async function extractArchive(params) {
                             rootDir: destinationRealDir,
                             stripComponents: params.stripComponents,
                             limits,
+                            entryFilter: params.entryFilter,
+                            onFiltered: params.onFiltered,
                         });
+                        const acceptedEntries = [];
                         // 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,
+                        const extractor = tar.x({
                             cwd: stagingDir,
                             strip: Math.max(0, Math.floor(params.stripComponents ?? 0)),
                             gzip: params.tarGzip,
                             signal: deadline.signal,
                             preservePaths: false,
+                            noChmod: true,
+                            preserveOwner: false,
                             strict: true,
+                            maxMetaEntrySize: limits.maxMetaEntryBytes,
+                            filter(_entryPath, entry) {
+                                try {
+                                    const info = readTarEntryInfo(entry);
+                                    const accepted = checkTarEntrySafety(info);
+                                    if (accepted) {
+                                        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,
+                                                }),
+                                            });
+                                        }
+                                    }
+                                    return accepted;
+                                }
+                                catch (error) {
+                                    // Abort through the parser so pipeline tears down both the
+                                    // archive reader and unpacker instead of leaving a paused
+                                    // stream behind after a policy rejection.
+                                    this.abort(error instanceof Error ? error : new Error(String(error)));
+                                    return false;
+                                }
+                            },
                             onReadEntry(entry) {
                                 try {
                                     deadline.check();
-                                    checkTarEntrySafety(readTarEntryInfo(entry));
                                 }
                                 catch (err) {
                                     const error = err instanceof Error ? err : new Error(String(err));
@@ -305,6 +300,22 @@ export async function extractArchive(params) {
                                 }
                             },
                         });
+                        try {
+                            await pipeline(fsSync.createReadStream(stagedArchive.path), extractor, {
+                                signal: deadline.signal,
+                            });
+                        }
+                        catch (error) {
+                            throw createPipelineTimeoutError(error, deadline);
+                        }
+                        for (const accepted of acceptedEntries) {
+                            const outputPath = resolveArchiveOutputPath({
+                                rootDir: stagingDir,
+                                relPath: accepted.path,
+                                originalPath: accepted.path,
+                            });
+                            await fs.chmod(outputPath, accepted.mode);
+                        }
                         deadline.check();
                         await mergeExtractedTreeIntoDestination({
                             sourceDir: stagingDir,
@@ -327,16 +338,8 @@ export async function extractArchive(params) {
         stripComponents: params.stripComponents,
         limits: params.limits,
         deadline,
+        entryModes: params.entryModes,
+        entryFilter: params.entryFilter,
+        onFiltered: params.onFiltered,
     }));
 }
-async function importOptionalTar() {
-    try {
-        return await import("tar");
-    }
-    catch (err) {
-        throw missingOptionalArchiveDependencyError("tar", err);
-    }
-}
-function missingOptionalArchiveDependencyError(packageName, cause) {
-    return new Error(`Optional archive dependency "${packageName}" is not installed. Install it to use TAR archive helpers from @openclaw/fs-safe/archive.`, { cause });
-}

package/dist/atomic.d.ts

@@ -1,4 +1,4 @@
-export { replaceFileAtomic, replaceFileAtomicSync, type ReplaceFileAtomicFileSystem, type ReplaceFileAtomicOptions, type ReplaceFileAtomicResult, type ReplaceFileAtomicSyncFileSystem, type ReplaceFileAtomicSyncOptions, } from "./replace-file.js";
+export { replaceFileAtomic, replaceFileAtomicSync, type ReplaceFileAtomicFileSystem, type ReplaceFileAtomicOptions, type ReplaceFileAtomicRestoreCleanup, type ReplaceFileAtomicRestoreFailureDetails, type ReplaceFileAtomicResult, type ReplaceFileCopyFallbackRestorePolicy, type ReplaceFileDestinationHardlinkPolicy, type ReplaceFileAtomicSyncFileSystem, type ReplaceFileAtomicSyncOptions, } from "./replace-file.js";
 export { writeTextAtomic, type WriteTextAtomicOptions } from "./text-atomic.js";
 export { replaceDirectoryAtomic, type ReplaceDirectoryAtomicOptions } from "./replace-directory.js";
 export { movePathWithCopyFallback, type MovePathWithCopyFallbackOptions } from "./move-path.js";

package/dist/atomic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"atomic.d.ts","sourceRoot":"","sources":["../src/atomic.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,+BAA+B,EACpC,KAAK,4BAA4B,GAClC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,KAAK,6BAA6B,EAAE,MAAM,wBAAwB,CAAC;AACpG,OAAO,EAAE,wBAAwB,EAAE,KAAK,+BAA+B,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"atomic.d.ts","sourceRoot":"","sources":["../src/atomic.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC7B,KAAK,+BAA+B,EACpC,KAAK,sCAAsC,EAC3C,KAAK,uBAAuB,EAC5B,KAAK,oCAAoC,EACzC,KAAK,oCAAoC,EACzC,KAAK,+BAA+B,EACpC,KAAK,4BAA4B,GAClC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,KAAK,6BAA6B,EAAE,MAAM,wBAAwB,CAAC;AACpG,OAAO,EAAE,wBAAwB,EAAE,KAAK,+BAA+B,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/config.d.ts

@@ -1,3 +1,3 @@
-export { configureFsSafePython, getFsSafePythonConfig, type FsSafePythonConfig, type FsSafePythonMode, } from "./pinned-python-config.js";
+export { configureFsSafePython, configureFsSafeNative, getFsSafeNativeConfig, type FsSafePythonConfig, type FsSafeNativeConfig, type FsSafeNativeMode, } from "./native-config.js";
 export { configureFsSafeLocks, getFsSafeLockConfig, type FsSafeLockConfig, } from "./lock-config.js";
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC"}

package/dist/config.js

@@ -1,2 +1,2 @@
-export { configureFsSafePython, getFsSafePythonConfig, } from "./pinned-python-config.js";
+export { configureFsSafePython, configureFsSafeNative, getFsSafeNativeConfig, } from "./native-config.js";
 export { configureFsSafeLocks, getFsSafeLockConfig, } from "./lock-config.js";

package/dist/containment.d.ts

@@ -0,0 +1,2 @@
+export type ContainmentGuarantee = "kernel-atomic" | "best-effort";
+//# sourceMappingURL=containment.d.ts.map

package/dist/containment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"containment.d.ts","sourceRoot":"","sources":["../src/containment.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,oBAAoB,GAAG,eAAe,GAAG,aAAa,CAAC"}

package/dist/containment.js

@@ -0,0 +1 @@
+export {};

package/dist/durability.d.ts

@@ -1,2 +1,4 @@
 export { ensureDurableDirectory, pinDirectory, syncDirectory, syncDirectoryBestEffort, syncDirectoryBestEffortSync, syncDirectorySync, type DirectoryReceipt, type DirectorySyncOutcome, type DurableDirectoryReceipt, type EnsureDurableDirectoryOptions, type PinnedDirectory, } from "./directory-durability.js";
+export { isHardlinkFallbackError, publishFileExclusive, type PublishFileExclusiveResult, type PublishFileExclusiveStrategy, type PublishFileExclusiveCleanup, type PublishFileExclusiveDirectorySyncFailure, type PublishFileExclusiveFailureDetails, type PublishFileExclusiveFailurePhase, type PublishFileExclusiveSyncFailurePolicy, } from "./publish-file.js";
+export { sha256File, type Sha256FileInput, type Sha256FileResult, } from "./file-hash.js";
 //# sourceMappingURL=durability.d.ts.map

package/dist/durability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"durability.d.ts","sourceRoot":"","sources":["../src/durability.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,aAAa,EACb,uBAAuB,EACvB,2BAA2B,EAC3B,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,eAAe,GACrB,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"durability.d.ts","sourceRoot":"","sources":["../src/durability.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,aAAa,EACb,uBAAuB,EACvB,2BAA2B,EAC3B,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,eAAe,GACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,KAAK,0BAA0B,EAC/B,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EAChC,KAAK,wCAAwC,EAC7C,KAAK,kCAAkC,EACvC,KAAK,gCAAgC,EACrC,KAAK,qCAAqC,GAC3C,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC"}

package/dist/durability.js

@@ -1 +1,3 @@
 export { ensureDurableDirectory, pinDirectory, syncDirectory, syncDirectoryBestEffort, syncDirectoryBestEffortSync, syncDirectorySync, } from "./directory-durability.js";
+export { isHardlinkFallbackError, publishFileExclusive, } from "./publish-file.js";
+export { sha256File, } from "./file-hash.js";

package/dist/errors.d.ts

@@ -1,11 +1,14 @@
-export type FsSafeErrorCode = "already-exists" | "denied-path" | "device-path" | "hardlink" | "helper-failed" | "helper-unavailable" | "invalid-path" | "insecure-permissions" | "not-empty" | "not-file" | "not-found" | "not-owned" | "not-removable" | "outside-workspace" | "path-alias" | "path-mismatch" | "permission-unverified" | "symlink" | "timeout" | "too-large" | "unsupported-platform";
+export type FsSafeErrorCode = "already-exists" | "denied-path" | "device-path" | "hardlink" | "helper-failed" | "helper-unavailable" | "invalid-path" | "insecure-permissions" | "not-empty" | "not-file" | "not-found" | "not-owned" | "not-removable" | "outside-workspace" | "path-alias" | "path-mismatch" | "permission-unverified" | "secret-exists" | "store-reentrant-update" | "symlink" | "timeout" | "too-large" | "unsupported-platform";
 export type FsSafeErrorCategory = "policy" | "operational";
+export type FsSafeErrorDetails = Readonly<Record<string, unknown>>;
 export declare function categorizeFsSafeError(code: FsSafeErrorCode): FsSafeErrorCategory;
 export declare class FsSafeError extends Error {
     readonly code: FsSafeErrorCode;
     readonly category: FsSafeErrorCategory;
+    readonly details?: FsSafeErrorDetails;
     constructor(code: FsSafeErrorCode, message: string, options?: {
         cause?: unknown;
+        details?: FsSafeErrorDetails;
     });
 }
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GACvB,gBAAgB,GAChB,aAAa,GACb,aAAa,GACb,UAAU,GACV,eAAe,GACf,oBAAoB,GACpB,cAAc,GACd,sBAAsB,GACtB,WAAW,GACX,UAAU,GACV,WAAW,GACX,WAAW,GACX,eAAe,GACf,mBAAmB,GACnB,YAAY,GACZ,eAAe,GACf,uBAAuB,GACvB,SAAS,GACT,SAAS,GACT,WAAW,GACX,sBAAsB,CAAC;AAE3B,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,aAAa,CAAC;AAU3D,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,mBAAmB,CAEhF;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IAEvC,YAAY,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,EAKpF;CACF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GACvB,gBAAgB,GAChB,aAAa,GACb,aAAa,GACb,UAAU,GACV,eAAe,GACf,oBAAoB,GACpB,cAAc,GACd,sBAAsB,GACtB,WAAW,GACX,UAAU,GACV,WAAW,GACX,WAAW,GACX,eAAe,GACf,mBAAmB,GACnB,YAAY,GACZ,eAAe,GACf,uBAAuB,GACvB,eAAe,GACf,wBAAwB,GACxB,SAAS,GACT,SAAS,GACT,WAAW,GACX,sBAAsB,CAAC;AAE3B,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,aAAa,CAAC;AAC3D,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAUnE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,mBAAmB,CAEhF;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAEtC,YACE,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,kBAAkB,CAAA;KAAO,EAOhE;CACF"}

package/dist/errors.js

@@ -11,10 +11,12 @@ export function categorizeFsSafeError(code) {
 export class FsSafeError extends Error {
     code;
     category;
+    details;
     constructor(code, message, options = {}) {
         super(message, options);
         this.name = "FsSafeError";
         this.code = code;
         this.category = categorizeFsSafeError(code);
+        this.details = options.details;
     }
 }

package/dist/file-hash.d.ts

@@ -0,0 +1,10 @@
+import type { FileHandle } from "node:fs/promises";
+import { type NativeBinding } from "./native.js";
+export type Sha256FileInput = string | FileHandle;
+export type Sha256FileResult = {
+    bytes: number;
+    digest: string;
+};
+export declare function hashFileHandle(handle: FileHandle, native?: NativeBinding | undefined): Promise<Sha256FileResult>;
+export declare function sha256File(input: Sha256FileInput): Promise<Sha256FileResult>;
+//# sourceMappingURL=file-hash.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-hash.d.ts","sourceRoot":"","sources":["../src/file-hash.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEnE,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;AAcF,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,EAClB,MAAM,GAAE,aAAa,GAAG,SAA8B,GACrD,OAAO,CAAC,gBAAgB,CAAC,CAoB3B;AAsCD,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAElF"}

package/dist/file-hash.js

@@ -0,0 +1,73 @@
+import { createHash } from "node:crypto";
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { getNativeBinding } from "./native.js";
+function readFlags() {
+    return (fsSync.constants.O_RDONLY |
+        (process.platform !== "win32" && typeof fsSync.constants.O_NOFOLLOW === "number"
+            ? fsSync.constants.O_NOFOLLOW
+            : 0) |
+        (process.platform !== "win32" && typeof fsSync.constants.O_NONBLOCK === "number"
+            ? fsSync.constants.O_NONBLOCK
+            : 0));
+}
+export async function hashFileHandle(handle, native = getNativeBinding()) {
+    const stat = await handle.stat();
+    if (!stat.isFile()) {
+        throw new FsSafeError("not-file", "SHA-256 input is not a regular file");
+    }
+    if (native) {
+        return await native.sha256File(handle.fd);
+    }
+    const hash = createHash("sha256");
+    const buffer = Buffer.allocUnsafe(64 * 1024);
+    let position = 0;
+    while (true) {
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+        if (bytesRead === 0) {
+            return { bytes: position, digest: hash.digest("hex") };
+        }
+        hash.update(buffer.subarray(0, bytesRead));
+        position += bytesRead;
+    }
+}
+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");
+    }
+    let handle;
+    try {
+        handle = await fs.open(filePath, readFlags());
+    }
+    catch (error) {
+        if (error?.code === "ELOOP") {
+            throw new FsSafeError("symlink", "SHA-256 path must not be a symbolic link", {
+                cause: error,
+            });
+        }
+        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(opened, current)) {
+            throw new FsSafeError("path-mismatch", "SHA-256 path changed while opening");
+        }
+        return await hashFileHandle(handle);
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+export async function sha256File(input) {
+    return typeof input === "string" ? await hashPath(input) : await hashFileHandle(input);
+}

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

@@ -0,0 +1,35 @@
+import type { Root } from "./root-impl.js";
+import { type SidecarLockStaleSnapshot } from "./sidecar-lock-reclaim.js";
+import type { SidecarLockCompromisedInfo, SidecarLockRetryOptions, SidecarLockStaleRecovery } from "./sidecar-lock-types.js";
+export type FileLockSyncAcquireOptions<TPayload extends Record<string, unknown>> = {
+    lockPath?: string;
+    staleMs?: number;
+    timeoutMs?: number;
+    retry?: SidecarLockRetryOptions;
+    staleRecovery?: SidecarLockStaleRecovery;
+    reentrantOwner?: string;
+    payload: () => TPayload;
+    shouldReclaim?: (params: {
+        lockPath: string;
+        normalizedTargetPath: string;
+        payload: unknown;
+        staleMs: number;
+        nowMs: number;
+        heldByThisProcess: false;
+    }) => boolean;
+    shouldRemoveStaleLock?: (snapshot: SidecarLockStaleSnapshot) => boolean;
+    parsePayload?: (raw: string) => unknown;
+    lockRoot?: Root;
+    onCompromised?: (info: SidecarLockCompromisedInfo) => void;
+    compromiseCheckIntervalMs?: number;
+};
+export type FileLockSyncHandle = {
+    lockPath: string;
+    normalizedTargetPath: string;
+    verifyStillHeld(): boolean;
+    release(): void;
+    [Symbol.dispose](): void;
+};
+export declare function acquireFileLockSync<TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockSyncAcquireOptions<TPayload>): FileLockSyncHandle;
+export declare function withFileLockSync<T, TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockSyncAcquireOptions<TPayload>, fn: () => T): T;
+//# sourceMappingURL=file-lock-sync.d.ts.map

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

@@ -0,0 +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;AAEjC,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;AAiGF,wBAAgB,mBAAmB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,0BAA0B,CAAC,QAAQ,CAAC,GAC5C,kBAAkB,CA6IpB;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"}