@openclaw/fs-safe 0.9.0 → 0.11.0

package/dist/archive-merge.d.ts

@@ -1,4 +1,5 @@
 import { type ExtractionDeadline } from "./archive-deadline.js";
+import { type ArchiveDirectoryGuard } from "./archive-staging.js";
 export type ArchivePublicationEntry = {
     path: string;
     kind: "file" | "directory";
@@ -10,7 +11,10 @@ type MergeParams = {
     destinationRealDir: string;
     deadline?: ExtractionDeadline;
 };
-export declare function mergePlannedArchiveIntoDestination(params: MergeParams & {
+type GuardedMergeParams = Pick<MergeParams, "sourceDir" | "deadline"> & {
+    destinationGuard: ArchiveDirectoryGuard;
+};
+export declare function mergePlannedArchiveIntoDestination(params: GuardedMergeParams & {
     entries: readonly ArchivePublicationEntry[];
     durable?: boolean;
 }): Promise<void>;

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

@@ -1 +1 @@
-{"version":3,"file":"archive-merge.d.ts","sourceRoot":"","sources":["../src/archive-merge.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoC,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAkBlG,MAAM,MAAM,uBAAuB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AACjG,KAAK,WAAW,GAAG;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B,CAAC;AAEF,wBAAsB,kCAAkC,CACtD,MAAM,EAAE,WAAW,GAAG;IAAE,OAAO,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GACvF,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1F"}
+{"version":3,"file":"archive-merge.d.ts","sourceRoot":"","sources":["../src/archive-merge.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoC,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAClG,OAAO,EAIL,KAAK,qBAAqB,EAC3B,MAAM,sBAAsB,CAAC;AAa9B,MAAM,MAAM,uBAAuB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AACjG,KAAK,WAAW,GAAG;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B,CAAC;AACF,KAAK,kBAAkB,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,UAAU,CAAC,GAAG;IACtE,gBAAgB,EAAE,qBAAqB,CAAC;CACzC,CAAC;AAEF,wBAAsB,kCAAkC,CACtD,MAAM,EAAE,kBAAkB,GAAG;IAAE,OAAO,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9F,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1F"}

package/dist/archive-merge.js

@@ -3,13 +3,13 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { ownExtractionDestinationMutation } from "./archive-deadline.js";
 import { assertDirectoryIdentityGuard, assertResolvedInsideDestination, createDirectoryIdentityGuard, createArchiveSymlinkTraversalError, preparePrivateArchiveOutputPath, } from "./archive-staging.js";
-import {} from "./directory-guard.js";
 import {} from "./directory-mode-owner.js";
 import { pinNodeDirectoryForMode } from "./directory-mode-node.js";
 import { FsSafeError } from "./errors.js";
 import { formatErrorDetail } from "./error-detail.js";
 import { isPathInside } from "./path.js";
-import { root } from "./root.js";
+import { rootFromDirectoryGuard } from "./root-impl.js";
+import { realpathSync } from "./realpath.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 import { onCopyPublication } from "./copy-publication.js";
 import { syncFileBestEffortSync } from "./file-sync.js";
@@ -18,16 +18,18 @@ export async function mergePlannedArchiveIntoDestination(params) {
     await mergeTree(params, params.entries, params.durable === true);
 }
 export async function mergeExtractedTreeIntoDestination(params) {
-    await mergeTree(params);
+    const destinationGuard = await createDirectoryIdentityGuard(params.destinationRealDir);
+    await mergeTree({ sourceDir: params.sourceDir, deadline: params.deadline, destinationGuard });
 }
 async function mergeTree(params, publication, durable = true) {
     const publishedFiles = [];
     const publishedDirectories = [];
     const check = () => params.deadline?.check();
     check();
-    const destinationGuard = await createDirectoryIdentityGuard(params.destinationRealDir);
-    check();
-    const targetRoot = await root(params.destinationRealDir);
+    const { destinationGuard } = params;
+    const destinationDir = destinationGuard.dir;
+    const destinationRealDir = destinationGuard.realPath;
+    const targetRoot = rootFromDirectoryGuard(destinationGuard);
     check();
     const sourceGuard = await createDirectoryIdentityGuard(params.sourceDir);
     check();
@@ -35,7 +37,7 @@ async function mergeTree(params, publication, durable = true) {
     for (const entry of publication ?? []) {
         // Resolve admitted spelling in private staging, preserving the volume's case
         // and Unicode behavior without assigning explicit modes to distinct parents.
-        const stagedPath = fsSync.realpathSync.native(path.join(params.sourceDir, entry.path));
+        const stagedPath = realpathSync.native(path.join(params.sourceDir, entry.path));
         check();
         if (!isPathInside(sourceGuard.realPath, stagedPath) || plan.has(stagedPath)) {
             throw new FsSafeError("path-mismatch", "archive publication paths changed in staging");
@@ -64,12 +66,12 @@ async function mergeTree(params, publication, durable = true) {
             const sourcePath = path.join(sourceDir, entry.name);
             const relPath = path.relative(params.sourceDir, sourcePath);
             const originalPath = relPath.split(path.sep).join("/");
-            const destinationPath = path.join(params.destinationDir, relPath);
+            const destinationPath = path.join(destinationDir, relPath);
             const sourceStat = fsSync.lstatSync(sourcePath);
             check();
             if (sourceStat.isSymbolicLink())
                 throw createArchiveSymlinkTraversalError(originalPath);
-            const sourceReal = fsSync.realpathSync.native(sourcePath);
+            const sourceReal = realpathSync.native(sourcePath);
             check();
             if (!isPathInside(sourceGuard.realPath, sourceReal))
                 throw createArchiveSymlinkTraversalError(originalPath);
@@ -83,7 +85,8 @@ async function mergeTree(params, publication, durable = true) {
             }
             const mode = plan ? planned?.mode ?? 0o755 : sourceStat.mode & 0o777;
             await preparePrivateArchiveOutputPath({
-                ...params, relPath, outPath: destinationPath, originalPath, isDirectory: kind === "directory",
+                destinationDir, destinationRealDir, deadline: params.deadline,
+                relPath, outPath: destinationPath, originalPath, isDirectory: kind === "directory",
             }, assertGuards, destinationGuard);
             check();
             if (kind === "directory") {
@@ -119,7 +122,7 @@ async function mergeTree(params, publication, durable = true) {
                                     await assertDirectoryIdentityGuard(guard);
                                     check();
                                     await assertResolvedInsideDestination({
-                                        destinationRealDir: params.destinationRealDir, targetPath: destinationPath, originalPath,
+                                        destinationRealDir, targetPath: destinationPath, originalPath,
                                     });
                                     check();
                                 } });
@@ -162,7 +165,7 @@ async function mergeTree(params, publication, durable = true) {
                         check();
                         await assertGuards();
                         await assertResolvedInsideDestination({
-                            destinationRealDir: params.destinationRealDir, targetPath: destinationPath, originalPath,
+                            destinationRealDir, targetPath: destinationPath, originalPath,
                         });
                         check();
                         const stat = fsSync.lstatSync(destinationPath);
@@ -172,7 +175,7 @@ async function mergeTree(params, publication, durable = true) {
                         }
                     }
                     catch (error) {
-                        // copyIn alone owns cleanup; no receipt permits archive-layer unlink.
+                        // copyIn cleans unpublished stages; merge never gains rollback authority.
                         if (error instanceof FsSafeError && (error.code === "hardlink" || error.code === "path-alias")) {
                             throw createArchiveSymlinkTraversalError(originalPath);
                         }

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

@@ -1 +1 @@
-{"version":3,"file":"archive-native.d.ts","sourceRoot":"","sources":["../src/archive-native.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAEL,KAAK,4BAA4B,EACjC,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAOlE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAYnE;AAED,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,aAAa,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,4BAA4B,CAAC;IACrC,SAAS,EAAE,cAAc,CAAC;IAC1B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,UAAU,CAAC,EAAE,qBAAqB,CAAC,YAAY,CAAC,CAAC;IACjD,WAAW,CAAC,EAAE,qBAAqB,CAAC,aAAa,CAAC,CAAC;IACnD,UAAU,CAAC,EAAE,qBAAqB,CAAC,YAAY,CAAC,CAAC;CAClD,GAAG,OAAO,CAAC,IAAI,CAAC,CA8FhB"}
+{"version":3,"file":"archive-native.d.ts","sourceRoot":"","sources":["../src/archive-native.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAEL,KAAK,4BAA4B,EACjC,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAOlE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAYnE;AAED,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,aAAa,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,4BAA4B,CAAC;IACrC,SAAS,EAAE,cAAc,CAAC;IAC1B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,UAAU,CAAC,EAAE,qBAAqB,CAAC,YAAY,CAAC,CAAC;IACjD,WAAW,CAAC,EAAE,qBAAqB,CAAC,aAAa,CAAC,CAAC;IACnD,UAAU,CAAC,EAAE,qBAAqB,CAAC,YAAY,CAAC,CAAC;CAClD,GAAG,OAAO,CAAC,IAAI,CAAC,CA+FhB"}

package/dist/archive-native.js

@@ -6,7 +6,7 @@ import { stripArchivePath, validateArchiveEntryPath } from "./archive-entry.js";
 import { createArchiveEntryPlanner } from "./archive-plan.js";
 import { stageArchiveFileForExtraction } from "./archive-input.js";
 import { assertArchiveEntryCountWithinLimit, } from "./archive-limits.js";
-import { prepareArchiveDestinationDir, withStagedArchiveDestination, } from "./archive-staging.js";
+import { prepareArchiveDestinationGuard, withStagedArchiveDestination, } from "./archive-staging.js";
 import { mergePlannedArchiveIntoDestination } from "./archive-merge.js";
 import { admitZipFile } from "./archive-zip-admission.js";
 export function throwMappedNativeArchiveError(error) {
@@ -35,13 +35,15 @@ export async function extractNativeArchive(params) {
         const physicalCount = params.kind === "zip"
             ? await admitZipFile(stagedArchive.path, limits, params.deadline, (entry) => { zipEntries.push(entry); })
             : undefined;
-        const destinationRealDir = await prepareArchiveDestinationDir(params.destDir);
+        const destinationGuard = await prepareArchiveDestinationGuard(params.destDir);
+        const destinationRealDir = destinationGuard.realPath;
         await withStagedArchiveDestination({
             destinationRealDir,
             run: async (stagingDir) => {
                 params.deadline.check();
+                // N-API retains completed task state on its signal; each pass needs its own.
                 const manifest = await params.binding
-                    .inspectArchiveNative(stagedArchive.path, params.kind, tarLimits, params.deadline.signal)
+                    .inspectArchiveNative(stagedArchive.path, params.kind, tarLimits, AbortSignal.any([params.deadline.signal]))
                     .catch(throwMappedNativeArchiveError);
                 params.deadline.check();
                 assertArchiveEntryCountWithinLimit(manifest.length, limits);
@@ -84,7 +86,7 @@ export async function extractNativeArchive(params) {
                     (typeof fsConstants.O_DIRECTORY === "number" ? fsConstants.O_DIRECTORY : 0));
                 try {
                     params.deadline.check();
-                    await params.binding.extractArchiveNative(stagedArchive.path, params.kind, directory.fd, plan.map((entry) => ({ ...entry, mode: entry.kind === "directory" ? 0o700 : 0o600 })), tarLimits, params.deadline.signal).catch(throwMappedNativeArchiveError);
+                    await params.binding.extractArchiveNative(stagedArchive.path, params.kind, directory.fd, plan.map((entry) => ({ ...entry, mode: entry.kind === "directory" ? 0o700 : 0o600 })), tarLimits, AbortSignal.any([params.deadline.signal])).catch(throwMappedNativeArchiveError);
                 }
                 finally {
                     await directory.close().catch(() => undefined);
@@ -94,8 +96,7 @@ export async function extractNativeArchive(params) {
                     entries: plan,
                     durable: params.durable,
                     sourceDir: stagingDir,
-                    destinationDir: params.destDir,
-                    destinationRealDir,
+                    destinationGuard,
                     deadline: params.deadline,
                 });
                 params.deadline.check();

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

@@ -1 +1 @@
-{"version":3,"file":"archive-read.d.ts","sourceRoot":"","sources":["../src/archive-read.ts"],"names":[],"mappings":"AAeA,OAAO,EAAiD,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAkLpG,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,WAAW,CAAA;CAAE,GAChD,OAAO,CAAC,MAAM,CAAC,CA6EjB"}
+{"version":3,"file":"archive-read.d.ts","sourceRoot":"","sources":["../src/archive-read.ts"],"names":[],"mappings":"AAeA,OAAO,EAAiD,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAyOpG,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,WAAW,CAAA;CAAE,GAChD,OAAO,CAAC,MAAM,CAAC,CAkBjB"}

package/dist/archive-read.js

@@ -2,22 +2,23 @@ import { classifyArchiveParserError } from "./archive-parser-errors.js";
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import { Readable } from "node:stream";
-import { readFileHandleBounded } from "./bounded-read.js";
+import { readBoundedAsync } from "./bounded-read.js";
 import { ArchiveFormatError, ArchiveSecurityError, isArchiveFormatErrorMessage, } from "./archive-errors.js";
 import { formatErrorDetail } from "./error-detail.js";
 import { stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
 import { assertPortableArchiveKind, resolveArchiveKind } from "./archive-kind.js";
 import { DEFAULT_MAX_ARCHIVE_BYTES_ZIP, ArchiveLimitError, ARCHIVE_LIMIT_ERROR_CODE, } from "./archive-limits.js";
+import { isGzipBuffer } from "./archive-gzip-tail.js";
 import { inspectTar, replayTar } from "./archive-tar-stream.js";
-import { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
+import { loadAdmittedZipArchive } from "./archive-zip-loader.js";
 import { createZipIntegrityTransform, normalizeZipIntegrityError, } from "./archive-zip-integrity.js";
 import { FsSafeError } from "./errors.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { realpathSync } from "./realpath.js";
 import { getNativeBinding } from "./native.js";
 import { admitZipBuffer } from "./archive-zip-admission.js";
 import { resolveExtractLimits, resolveTarMeterLimits } from "./archive-limits.js";
-import { tempFile } from "./temp-target.js";
 const ZIP_UNIX_FILE_TYPE_MASK = 0o170000;
 const ZIP_UNIX_SYMLINK_TYPE = 0o120000;
 function canonicalEntryPath(entryPath) {
@@ -63,8 +64,8 @@ async function readStreamBounded(stream, maxBytes) {
     }
     return Buffer.concat(chunks, total);
 }
-async function stageArchiveInput(archivePath) {
-    const resolved = fsSync.realpathSync.native(archivePath);
+async function readArchiveInput(archivePath) {
+    const resolved = realpathSync.native(archivePath);
     const before = await inspectFileIdentity(async () => {
         const stat = fsSync.lstatSync(archivePath, { bigint: true });
         if (stat.isSymbolicLink() || !stat.isFile()) {
@@ -73,9 +74,7 @@ async function stageArchiveInput(archivePath) {
         return stat;
     });
     const handle = await fs.open(resolved, resolveReadOpenFlags());
-    let staged;
     try {
-        staged = await tempFile({ prefix: "fs-safe-archive-read", fileName: "archive.bin" });
         const opened = await inspectFileIdentity(async () => {
             const stat = fsSync.fstatSync(handle.fd, { bigint: true });
             if (!stat.isFile())
@@ -88,12 +87,14 @@ async function stageArchiveInput(archivePath) {
                 throw new Error("archive changed during validation");
             return stat;
         }, opened);
-        const buffer = await readFileHandleBounded(handle, DEFAULT_MAX_ARCHIVE_BYTES_ZIP);
-        await fs.writeFile(staged.path, buffer, { flag: "wx", mode: 0o600 });
-        return { path: staged.path, buffer, cleanup: staged.cleanup };
+        // Native archive workers borrow this private buffer. A pooled allocation could
+        // share its ArrayBuffer with unrelated JS buffers while the worker runs.
+        return await readBoundedAsync(DEFAULT_MAX_ARCHIVE_BYTES_ZIP, async (buffer, length) => (await handle.read(buffer, 0, length, null)).bytesRead, { unpooled: true, observeRegularFileSize: () => {
+                const size = fsSync.fstatSync(handle.fd).size;
+                return Number.isSafeInteger(size) && size >= 0 ? size : undefined;
+            } });
     }
     catch (error) {
-        await staged?.cleanup().catch(() => undefined);
         if (error instanceof FsSafeError && error.code === "path-mismatch") {
             throw new FsSafeError("path-mismatch", "archive changed during validation", { cause: error });
         }
@@ -103,12 +104,8 @@ async function stageArchiveInput(archivePath) {
         await handle.close().catch(() => undefined);
     }
 }
-async function readZipEntry(buffer, entryPath, maxBytes) {
-    const archive = await loadZipArchiveWithPreflight(buffer, {
-        maxArchiveBytes: DEFAULT_MAX_ARCHIVE_BYTES_ZIP,
-        maxEntryBytes: maxBytes,
-        maxExtractedBytes: maxBytes,
-    });
+async function readZipEntry(buffer, entryPath, maxBytes, physicalCount) {
+    const archive = await loadAdmittedZipArchive(buffer, physicalCount);
     let entry;
     // JSZip keys retain some aliases and may use Unicode Path metadata. Scan the
     // effective entries once, after raw ZIP admission has rejected collisions.
@@ -134,11 +131,11 @@ async function readZipEntry(buffer, entryPath, maxBytes) {
     stream.once("error", (error) => integrity.destroy(normalizeZipIntegrityError(error)));
     return await readStreamBounded(stream.pipe(integrity), maxBytes);
 }
-async function readTarEntry(archivePath, entryPath, maxBytes) {
+async function readTarEntry(archiveBuffer, entryPath, maxBytes) {
     const seenPaths = new Set();
     let selected;
     const limits = resolveTarMeterLimits();
-    await inspectTar({ archivePath, limits, onMember(info) {
+    await inspectTar({ archiveBuffer, limits, onMember(info) {
             const normalized = canonicalEntryPath(info.path);
             if (seenPaths.has(normalized)) {
                 throw new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(normalized)}`);
@@ -154,12 +151,68 @@ async function readTarEntry(archivePath, entryPath, maxBytes) {
     }
     if (selected.size > maxBytes)
         throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
+    if (!isGzipBuffer(archiveBuffer)) {
+        // Complete admission already validated this private snapshot through EOF.
+        // Copy the admitted payload so the result cannot expose or mutate its input.
+        const end = selected.offset + selected.size;
+        if (!Number.isSafeInteger(selected.offset) || selected.offset < 0 ||
+            !Number.isSafeInteger(end) || end < selected.offset || end > archiveBuffer.length) {
+            throw new ArchiveFormatError("invalid admitted TAR range");
+        }
+        return Buffer.from(archiveBuffer.subarray(selected.offset, end));
+    }
     let result;
-    await replayTar({ archivePath, limits, members: [selected], async consume(_member, payload) {
+    await replayTar({ archiveBuffer, limits, members: [selected], async consume(_member, payload) {
             result = await readStreamBounded(payload, maxBytes);
         } });
     return result;
 }
+function selectNativeEntry(manifest, requested, displayPath, physicalCount) {
+    if (physicalCount !== undefined && manifest.length !== physicalCount) {
+        throw new ArchiveSecurityError("entry-path", "zip decoder collapsed entry names");
+    }
+    const seen = new Set();
+    let selected;
+    for (const entry of manifest) {
+        const normalized = canonicalEntryPath(entry.path);
+        if (seen.has(normalized)) {
+            throw new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(normalized)}`);
+        }
+        seen.add(normalized);
+        if (normalized === requested) {
+            if (entry.kind !== "file")
+                throw new Error(`archive entry is not a file: ${formatErrorDetail(displayPath)}`);
+            selected = entry;
+        }
+    }
+    if (!selected)
+        throw new Error(`archive entry not found: ${formatErrorDetail(displayPath)}`);
+    return selected;
+}
+function throwNativeReadError(error) {
+    if (error instanceof Error) {
+        const mapped = classifyArchiveParserError(error.message, { cause: error });
+        if (mapped)
+            throw mapped;
+        if (isArchiveFormatErrorMessage(error.message))
+            throw new ArchiveFormatError(error.message, { cause: error });
+    }
+    throw error;
+}
+async function readNativeBufferEntry(native, buffer, kind, requested, displayPath, maxBytes, physicalCount) {
+    try {
+        const signal = new AbortController().signal;
+        const limits = resolveTarMeterLimits();
+        const reader = kind === "zip"
+            ? await native.openZipBufferNative(buffer, limits, AbortSignal.any([signal]))
+            : await native.openTarBufferNative(buffer, kind, limits, AbortSignal.any([signal]));
+        const selected = selectNativeEntry(reader.entries, requested, displayPath, physicalCount);
+        return await reader.readEntry(selected.index, maxBytes, AbortSignal.any([signal]));
+    }
+    catch (error) {
+        throwNativeReadError(error);
+    }
+}
 export async function readArchiveEntry(archivePath, entryPath, options) {
     if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0) {
         throw new RangeError("maxBytes must be a non-negative safe integer");
@@ -169,58 +222,14 @@ export async function readArchiveEntry(archivePath, entryPath, options) {
         throw new Error(`unsupported archive: ${archivePath}`);
     }
     const requestedEntry = normalizedRequestedEntry(entryPath);
-    const staged = await stageArchiveInput(archivePath);
-    try {
-        const physicalCount = kind === "zip"
-            ? admitZipBuffer(staged.buffer, resolveExtractLimits())
-            : undefined;
-        const native = getNativeBinding();
-        if (native) {
-            try {
-                const signal = new AbortController().signal;
-                const limits = resolveTarMeterLimits();
-                const manifest = await native.inspectArchiveNative(staged.path, kind, limits, signal);
-                let rawEntryPath;
-                if (physicalCount !== undefined && manifest.length !== physicalCount) {
-                    throw new ArchiveSecurityError("entry-path", "zip decoder collapsed entry names");
-                }
-                const seenPaths = new Set();
-                for (const entry of manifest) {
-                    const normalized = canonicalEntryPath(entry.path);
-                    if (seenPaths.has(normalized)) {
-                        throw new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(normalized)}`);
-                    }
-                    seenPaths.add(normalized);
-                    if (normalized === requestedEntry) {
-                        if (entry.kind !== "file") {
-                            throw new Error(`archive entry is not a file: ${formatErrorDetail(entryPath)}`);
-                        }
-                        rawEntryPath = entry.path;
-                    }
-                }
-                if (!rawEntryPath) {
-                    throw new Error(`archive entry not found: ${formatErrorDetail(entryPath)}`);
-                }
-                return await native.readArchiveEntryNative(staged.path, kind, rawEntryPath, options.maxBytes, limits, signal);
-            }
-            catch (error) {
-                if (error instanceof Error) {
-                    const mapped = classifyArchiveParserError(error.message, { cause: error });
-                    if (mapped)
-                        throw mapped;
-                }
-                if (error instanceof Error && isArchiveFormatErrorMessage(error.message)) {
-                    throw new ArchiveFormatError(error.message, { cause: error });
-                }
-                throw error;
-            }
-        }
-        assertPortableArchiveKind(kind);
-        return kind === "zip"
-            ? await readZipEntry(staged.buffer, requestedEntry, options.maxBytes)
-            : await readTarEntry(staged.path, requestedEntry, options.maxBytes);
-    }
-    finally {
-        await staged.cleanup();
-    }
+    const buffer = await readArchiveInput(archivePath);
+    const physicalCount = kind === "zip"
+        ? admitZipBuffer(buffer, resolveExtractLimits())
+        : undefined;
+    const native = getNativeBinding();
+    if (native)
+        return await readNativeBufferEntry(native, buffer, kind, requestedEntry, entryPath, options.maxBytes, physicalCount);
+    assertPortableArchiveKind(kind);
+    return kind === "zip" ? await readZipEntry(buffer, requestedEntry, options.maxBytes, physicalCount)
+        : await readTarEntry(buffer, requestedEntry, options.maxBytes);
 }

package/dist/archive-staging.d.ts

@@ -1,9 +1,12 @@
+import { type BigIntStats } from "node:fs";
 import { type AsyncDirectoryGuard } from "./directory-guard.js";
 import { type ExtractionDeadline } from "./archive-deadline.js";
 import { ArchiveSecurityError } from "./archive-errors.js";
+export type ArchiveDirectoryGuard = AsyncDirectoryGuard<BigIntStats>;
 export { ArchiveSecurityError, type ArchiveSecurityErrorCode } from "./archive-errors.js";
-export declare function createDirectoryIdentityGuard(dir: string): Promise<AsyncDirectoryGuard>;
-export declare function assertDirectoryIdentityGuard(guard: AsyncDirectoryGuard): Promise<void>;
+export declare function createDirectoryIdentityGuard(dir: string): Promise<ArchiveDirectoryGuard>;
+export declare function assertDirectoryIdentityGuard(guard: ArchiveDirectoryGuard): Promise<void>;
+export declare function prepareArchiveDestinationGuard(destDir: string): Promise<ArchiveDirectoryGuard>;
 export declare function prepareArchiveDestinationDir(destDir: string): Promise<string>;
 export declare function assertResolvedInsideDestination(params: {
     destinationRealDir: string;
@@ -20,7 +23,7 @@ type ArchiveOutputPathParams = {
     deadline?: ExtractionDeadline;
 };
 export declare function prepareArchiveOutputPath(params: ArchiveOutputPathParams): Promise<void>;
-export declare function preparePrivateArchiveOutputPath(params: ArchiveOutputPathParams, assertGuards?: () => Promise<void>, destinationGuard?: AsyncDirectoryGuard): Promise<void>;
+export declare function preparePrivateArchiveOutputPath(params: ArchiveOutputPathParams, assertGuards?: () => Promise<void>, destinationGuard?: ArchiveDirectoryGuard): Promise<void>;
 export declare function withStagedArchiveDestination<T>(params: {
     destinationRealDir: string;
     stagingDirPrefix?: string;

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

@@ -1 +1 @@
-{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,oBAAoB,EAErB,MAAM,qBAAqB,CAAC;AAkB7B,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAS1F,wBAAsB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAS5F;AAED,wBAAsB,4BAA4B,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAY5F;AAED,wBAAsB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BnF;AA0BD,wBAAsB,+BAA+B,CAAC,MAAM,EAAE;IAC5D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAahB;AAiBD,KAAK,uBAAuB,GAAG;IAC7B,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;IACrB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B,CAAC;AAEF,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7F;AAED,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,uBAAuB,EAAE,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EACnE,gBAAgB,CAAC,EAAE,mBAAmB,GACrC,OAAO,CAAC,IAAI,CAAC,CAEf;AAkHD,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,OAAO,EAAE,iCAAiC,EAAE,MAAM,oBAAoB,CAAC;AAEvE,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,CAE7F"}
+{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAGnD,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,oBAAoB,EAErB,MAAM,qBAAqB,CAAC;AAgB7B,MAAM,MAAM,qBAAqB,GAAG,mBAAmB,CAAC,WAAW,CAAC,CAAC;AAMrE,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAS1F,wBAAsB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAS9F;AAED,wBAAsB,4BAA4B,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAY9F;AAED,wBAAsB,8BAA8B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAyCpG;AAED,wBAAsB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEnF;AA0BD,wBAAsB,+BAA+B,CAAC,MAAM,EAAE;IAC5D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAahB;AAiBD,KAAK,uBAAuB,GAAG;IAC7B,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;IACrB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B,CAAC;AAEF,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7F;AAED,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,uBAAuB,EAAE,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EACnE,gBAAgB,CAAC,EAAE,qBAAqB,GACvC,OAAO,CAAC,IAAI,CAAC,CAEf;AAkHD,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,OAAO,EAAE,iCAAiC,EAAE,MAAM,oBAAoB,CAAC;AAEvE,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,CAE7F"}

package/dist/archive-staging.js

@@ -1,4 +1,4 @@
-import fsSync from "node:fs";
+import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, } from "./directory-guard.js";
@@ -13,6 +13,8 @@ import { getFsSafeTestHooks } from "./test-hooks.js";
 import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
 import { expandRelativePathWithHome } from "./root-context.js";
 import { resolveRootPath } from "./root-path.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { realpathSync } from "./realpath.js";
 const ERROR_ARCHIVE_ENTRY_TRAVERSES_SYMLINK = "archive entry traverses symlink in destination";
 const ARCHIVE_STAGING_MODE = 0o700;
 function checkExtractionDeadline(deadline) {
@@ -24,7 +26,7 @@ function symlinkTraversalError(originalPath) {
 }
 export async function createDirectoryIdentityGuard(dir) {
     try {
-        return await createAsyncDirectoryGuard(dir);
+        return await createAsyncDirectoryGuard(dir, { bigint: true });
     }
     catch (err) {
         if (err instanceof FsSafeError && err.code === "not-file") {
@@ -37,33 +39,51 @@ export async function assertDirectoryIdentityGuard(guard) {
     try {
         await assertAsyncDirectoryGuard(guard);
     }
+    catch (err) {
+        if (err instanceof FsSafeError || isNotFoundPathError(err)) {
+            throw new ArchiveSecurityError("destination-symlink-traversal", "archive destination changed during extraction");
+        }
+        throw err;
+    }
+}
+export async function prepareArchiveDestinationGuard(destDir) {
+    let stat;
+    try {
+        stat = inspectFileIdentitySync(() => {
+            const observed = fsSync.lstatSync(destDir, { bigint: true });
+            if (observed.isSymbolicLink()) {
+                throw new ArchiveSecurityError("destination-symlink", "archive destination is a symlink");
+            }
+            if (!observed.isDirectory()) {
+                throw new ArchiveSecurityError("destination-not-directory", "archive destination is not a directory");
+            }
+            return observed;
+        });
+    }
+    catch (err) {
+        if (err instanceof ArchiveSecurityError)
+            throw err;
+        if (err instanceof FsSafeError) {
+            throw new ArchiveSecurityError("destination-symlink-traversal", "archive destination changed during extraction");
+        }
+        throw err;
+    }
+    const realPath = realpathSync.native(destDir);
+    const guard = { dir: destDir, realPath, stat };
+    try {
+        inspectFileIdentitySync(() => fsSync.statSync(realPath, { bigint: true }), stat);
+        inspectFileIdentitySync(() => fsSync.lstatSync(destDir, { bigint: true }), stat);
+    }
     catch (err) {
         if (err instanceof FsSafeError) {
             throw new ArchiveSecurityError("destination-symlink-traversal", "archive destination changed during extraction");
         }
         throw err;
     }
+    return guard;
 }
 export async function prepareArchiveDestinationDir(destDir) {
-    const stat = fsSync.lstatSync(destDir);
-    if (stat.isSymbolicLink()) {
-        throw new ArchiveSecurityError("destination-symlink", "archive destination is a symlink");
-    }
-    if (!stat.isDirectory()) {
-        throw new ArchiveSecurityError("destination-not-directory", "archive destination is not a directory");
-    }
-    const realPath = fsSync.realpathSync.native(destDir);
-    const realStat = fsSync.statSync(realPath);
-    const postStat = fsSync.lstatSync(destDir);
-    if (realStat.dev !== stat.dev ||
-        realStat.ino !== stat.ino ||
-        postStat.isSymbolicLink() ||
-        !postStat.isDirectory() ||
-        postStat.dev !== stat.dev ||
-        postStat.ino !== stat.ino) {
-        throw new ArchiveSecurityError("destination-symlink-traversal", "archive destination changed during extraction");
-    }
-    return realPath;
+    return (await prepareArchiveDestinationGuard(destDir)).realPath;
 }
 async function assertNoSymlinkTraversal(params) {
     const parts = params.relPath.split(/[\\/]+/).filter(Boolean);
@@ -88,7 +108,7 @@ async function assertNoSymlinkTraversal(params) {
 export async function assertResolvedInsideDestination(params) {
     let resolved;
     try {
-        resolved = fsSync.realpathSync.native(params.targetPath);
+        resolved = realpathSync.native(params.targetPath);
     }
     catch (err) {
         if (isNotFoundPathError(err)) {

package/dist/archive-tar-stream.d.ts

@@ -1,18 +1,25 @@
 import type { TarMeterLimits } from "./archive-limits.js";
 import { type AdmittedTarMember } from "./archive-tar-wasm.js";
-export declare function inspectTar(params: {
+/** Buffers are private immutable snapshots, just like the staged file route. */
+type TarInput = {
     archivePath: string;
+    archiveBuffer?: never;
+} | {
+    archiveBuffer: Buffer;
+    archivePath?: never;
+};
+export declare function inspectTar(params: TarInput & {
     limits: TarMeterLimits;
     signal?: AbortSignal;
     onMember?: (entry: AdmittedTarMember) => void;
 }): Promise<void>;
 /** Replay in physical order, retaining at most one decoded chunk. Every range
- * comes from complete admission of the immutable staged input. */
-export declare function replayTar<T extends AdmittedTarMember>(params: {
-    archivePath: string;
+ * comes from complete admission of the immutable input. */
+export declare function replayTar<T extends AdmittedTarMember>(params: TarInput & {
     limits: TarMeterLimits;
     signal?: AbortSignal;
     members: readonly T[];
     consume(member: T, payload: AsyncIterable<Buffer>): Promise<void>;
 }): Promise<void>;
+export {};
 //# sourceMappingURL=archive-tar-stream.d.ts.map

package/dist/archive-tar-stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive-tar-stream.d.ts","sourceRoot":"","sources":["../src/archive-tar-stream.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AA4ChF,wBAAsB,UAAU,CAAC,MAAM,EAAE;IACvC,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAClE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC/C,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhB;AAED;kEACkE;AAClE,wBAAsB,SAAS,CAAC,CAAC,SAAS,iBAAiB,EAAE,MAAM,EAAE;IACnE,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAClE,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;IACtB,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BhB"}
+{"version":3,"file":"archive-tar-stream.d.ts","sourceRoot":"","sources":["../src/archive-tar-stream.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAGhF,gFAAgF;AAChF,KAAK,QAAQ,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAuDhH,wBAAsB,UAAU,CAAC,MAAM,EAAE,QAAQ,GAAG;IAClD,MAAM,EAAE,cAAc,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC7C,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC/C,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhB;AAED;2DAC2D;AAC3D,wBAAsB,SAAS,CAAC,CAAC,SAAS,iBAAiB,EAAE,MAAM,EAAE,QAAQ,GAAG;IAC9E,MAAM,EAAE,cAAc,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC7C,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;IACtB,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BhB"}