@openclaw/fs-safe 0.6.0 → 0.7.0

package/dist/archive-read.js

@@ -1,29 +1,32 @@
-import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import { Readable } from "node:stream";
 import { readFileHandleBounded } from "./bounded-read.js";
-import { ArchiveFormatError, ArchiveSecurityError, isArchiveFormatErrorMessage, } from "./archive-errors.js";
+import { ArchiveFormatError, ArchiveSecurityError, isArchiveFormatErrorMessage, isArchiveTarPathErrorMessage, } from "./archive-errors.js";
 import { formatErrorDetail } from "./error-detail.js";
-import { normalizeArchiveEntryPath, validateArchiveEntryPath, } from "./archive-entry.js";
+import { stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
 import { resolveArchiveKind } from "./archive-kind.js";
-import { DEFAULT_MAX_ARCHIVE_BYTES_ZIP, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_META_ENTRY_BYTES, ArchiveLimitError, ARCHIVE_LIMIT_ERROR_CODE, } from "./archive-limits.js";
+import { DEFAULT_MAX_ARCHIVE_BYTES_ZIP, DEFAULT_MAX_META_ENTRY_BYTES, ArchiveLimitError, ARCHIVE_LIMIT_ERROR_CODE, } from "./archive-limits.js";
 import { readTarEntryInfo } from "./archive-tar.js";
 import { preflightTarMetadata } from "./archive-tar-meta.js";
-import { importOptionalTar, normalizeTarParserError } from "./archive-tar-runtime.js";
+import { importOptionalTar, NODE_TAR_RATIO_DISABLED, normalizeTarParserError } from "./archive-tar-runtime.js";
 import { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
 import { createZipIntegrityTransform, normalizeZipIntegrityError, } from "./archive-zip-integrity.js";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { getNativeBinding } from "./native.js";
 import { admitZipBuffer } from "./archive-zip-admission.js";
-import { resolveExtractLimits } from "./archive-limits.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 normalizedRequestedEntry(entryPath) {
+function canonicalEntryPath(entryPath) {
     validateArchiveEntryPath(entryPath, { escapeLabel: "archive root" });
-    const normalized = normalizeArchiveEntryPath(entryPath).replace(/^\.\//, "");
-    if (!normalized || normalized.endsWith("/")) {
+    return stripArchivePath(entryPath, 0) ?? "";
+}
+function normalizedRequestedEntry(entryPath) {
+    const normalized = canonicalEntryPath(entryPath);
+    if (!normalized || /[/\\]$/.test(entryPath)) {
         throw new Error(`archive entry is not a file: ${formatErrorDetail(entryPath)}`);
     }
     return normalized;
@@ -62,30 +65,37 @@ async function readStreamBounded(stream, maxBytes) {
 }
 async function stageArchiveInput(archivePath) {
     const resolved = await fs.realpath(archivePath);
-    const before = await fs.lstat(archivePath);
-    if (before.isSymbolicLink() || !before.isFile()) {
-        throw new Error(`archive is not a regular file: ${archivePath}`);
-    }
-    const noFollow = process.platform !== "win32" && typeof fsSync.constants.O_NOFOLLOW === "number"
-        ? fsSync.constants.O_NOFOLLOW
-        : 0;
-    const handle = await fs.open(resolved, fsSync.constants.O_RDONLY | noFollow);
+    const before = await inspectFileIdentity(async () => {
+        const stat = await fs.lstat(archivePath, { bigint: true });
+        if (stat.isSymbolicLink() || !stat.isFile()) {
+            throw new Error(`archive is not a regular file: ${archivePath}`);
+        }
+        return stat;
+    });
+    const handle = await fs.open(resolved, resolveReadOpenFlags());
     const staged = await tempFile({ prefix: "fs-safe-archive-read", fileName: "archive.bin" });
     try {
-        const opened = await handle.stat();
-        const current = await fs.lstat(resolved);
-        if (!opened.isFile() ||
-            !current.isFile() ||
-            !sameFileIdentity(before, opened) ||
-            !sameFileIdentity(current, opened)) {
-            throw new Error("archive changed during validation");
-        }
+        const opened = await inspectFileIdentity(async () => {
+            const stat = await handle.stat({ bigint: true });
+            if (!stat.isFile())
+                throw new Error("archive changed during validation");
+            return stat;
+        }, before);
+        await inspectFileIdentity(async () => {
+            const stat = await fs.lstat(resolved, { bigint: true });
+            if (stat.isSymbolicLink() || !stat.isFile())
+                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 };
     }
     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 });
+        }
         throw error;
     }
     finally {
@@ -98,7 +108,17 @@ async function readZipEntry(buffer, entryPath, maxBytes) {
         maxEntryBytes: maxBytes,
         maxExtractedBytes: maxBytes,
     });
-    const entry = archive.files[entryPath];
+    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.
+    for (const candidate of Object.values(archive.files)) {
+        if (canonicalEntryPath(candidate.name) !== entryPath)
+            continue;
+        if (entry) {
+            throw new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(entryPath)}`);
+        }
+        entry = candidate;
+    }
     if (!entry || entry.dir) {
         throw new Error(`archive entry not found: ${formatErrorDetail(entryPath)}`);
     }
@@ -115,22 +135,34 @@ async function readZipEntry(buffer, entryPath, maxBytes) {
 }
 async function readTarEntry(archivePath, entryPath, maxBytes) {
     const tar = await importOptionalTar();
+    const seenPaths = new Set();
     await preflightTarMetadata({
         archivePath,
-        maxMetaEntryBytes: DEFAULT_MAX_META_ENTRY_BYTES,
+        limits: resolveTarMeterLimits(),
+        onMember(info) {
+            const normalized = canonicalEntryPath(info.path);
+            if (seenPaths.has(normalized)) {
+                throw new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(normalized)}`);
+            }
+            seenPaths.add(normalized);
+            if (normalized === entryPath && !["File", "OldFile", "ContiguousFile"].includes(info.type)) {
+                throw new Error(`archive entry is not a file: ${formatErrorDetail(entryPath)}`);
+            }
+        },
     });
     let matched;
     let entryError;
-    const seenPaths = new Set();
     try {
         await tar.t({
             file: archivePath,
             strict: true,
             maxMetaEntrySize: DEFAULT_MAX_META_ENTRY_BYTES,
+            maxDecompressionRatio: NODE_TAR_RATIO_DISABLED,
             onReadEntry(entry) {
                 const info = readTarEntryInfo(entry);
+                let normalized;
                 try {
-                    validateArchiveEntryPath(info.path, { escapeLabel: "archive root" });
+                    normalized = canonicalEntryPath(info.path);
                 }
                 catch (error) {
                     // Throws escaping node-tar's callback do not reject its promise.
@@ -138,13 +170,6 @@ async function readTarEntry(archivePath, entryPath, maxBytes) {
                     entry.resume();
                     return;
                 }
-                const normalized = normalizeArchiveEntryPath(info.path).replace(/^\.\//, "");
-                if (seenPaths.has(normalized)) {
-                    entryError ??= new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(normalized)}`);
-                    entry.resume();
-                    return;
-                }
-                seenPaths.add(normalized);
                 if (normalized !== entryPath) {
                     entry.resume();
                     return;
@@ -192,15 +217,15 @@ export async function readArchiveEntry(archivePath, entryPath, options) {
         if (native) {
             try {
                 const signal = new AbortController().signal;
-                const manifest = await native.inspectArchiveNative(staged.path, kind, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_META_ENTRY_BYTES, DEFAULT_MAX_ARCHIVE_BYTES_ZIP, 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) {
-                    validateArchiveEntryPath(entry.path, { escapeLabel: "archive root" });
-                    const normalized = normalizeArchiveEntryPath(entry.path).replace(/^\.\//, "");
+                    const normalized = canonicalEntryPath(entry.path);
                     if (seenPaths.has(normalized)) {
                         throw new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(normalized)}`);
                     }
@@ -215,9 +240,12 @@ export async function readArchiveEntry(archivePath, entryPath, options) {
                 if (!rawEntryPath) {
                     throw new Error(`archive entry not found: ${formatErrorDetail(entryPath)}`);
                 }
-                return await native.readArchiveEntryNative(staged.path, kind, rawEntryPath, options.maxBytes, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_META_ENTRY_BYTES, signal);
+                return await native.readArchiveEntryNative(staged.path, kind, rawEntryPath, options.maxBytes, limits, signal);
             }
             catch (error) {
+                if (error instanceof Error && isArchiveTarPathErrorMessage(error.message)) {
+                    throw new ArchiveSecurityError("entry-path", error.message, { cause: error });
+                }
                 if (error instanceof Error) {
                     for (const code of Object.values(ARCHIVE_LIMIT_ERROR_CODE)) {
                         if (error.message.includes(code))

package/dist/archive-staging.d.ts

@@ -1,3 +1,4 @@
+import { type ExtractionDeadline } from "./archive-deadline.js";
 import { ArchiveSecurityError } from "./archive-errors.js";
 export { ArchiveSecurityError, type ArchiveSecurityErrorCode } from "./archive-errors.js";
 export declare function prepareArchiveDestinationDir(destDir: string): Promise<string>;
@@ -8,6 +9,7 @@ export declare function prepareArchiveOutputPath(params: {
     outPath: string;
     originalPath: string;
     isDirectory: boolean;
+    deadline?: ExtractionDeadline;
 }): Promise<void>;
 export declare function withStagedArchiveDestination<T>(params: {
     destinationRealDir: string;
@@ -18,6 +20,7 @@ export declare function mergeExtractedTreeIntoDestination(params: {
     sourceDir: string;
     destinationDir: string;
     destinationRealDir: string;
+    deadline?: ExtractionDeadline;
 }): Promise<void>;
 export declare function createArchiveSymlinkTraversalError(originalPath: string): ArchiveSecurityError;
 //# sourceMappingURL=archive-staging.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,oBAAoB,EAErB,MAAM,qBAAqB,CAAC;AAW7B,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAkC1F,wBAAsB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BnF;AA4DD,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuChB;AAyHD,wBAAsB,4BAA4B,CAAC,CAAC,EAAE,MAAM,EAAE;IAC5D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACzC,GAAG,OAAO,CAAC,CAAC,CAAC,CA6Bb;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;CAC5B,GAAG,OAAO,CAAC,IAAI,CAAC,CAkFhB;AAED,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,CAE7F"}
+{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AAOA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,oBAAoB,EAErB,MAAM,qBAAqB,CAAC;AAgB7B,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAkC1F,wBAAsB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BnF;AA4DD,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B,GAAG,OAAO,CAAC,IAAI,CAAC,CA6DhB;AAsID,wBAAsB,4BAA4B,CAAC,CAAC,EAAE,MAAM,EAAE;IAC5D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACzC,GAAG,OAAO,CAAC,CAAC,CAAC,CA6Bb;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B,GAAG,OAAO,CAAC,IAAI,CAAC,CA8FhB;AAED,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,CAE7F"}

package/dist/archive-staging.js

@@ -1,16 +1,20 @@
 import fs from "node:fs/promises";
-import fsSync from "node:fs";
 import path from "node:path";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, } from "./directory-guard.js";
+import { ownExtractionDestinationMutation, } from "./archive-deadline.js";
 import { ArchiveSecurityError, } from "./archive-errors.js";
 import { FsSafeError } from "./errors.js";
 import { formatErrorDetail } from "./error-detail.js";
 import { resolveOpenedFileRealPathForHandle, root } from "./root.js";
 import { isNotFoundPathError, isPathInside } from "./path.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 const ERROR_ARCHIVE_ENTRY_TRAVERSES_SYMLINK = "archive entry traverses symlink in destination";
 const ARCHIVE_STAGING_MODE = 0o700;
+function checkExtractionDeadline(deadline) {
+    deadline?.check();
+}
 export { ArchiveSecurityError } from "./archive-errors.js";
 function symlinkTraversalError(originalPath) {
     return new ArchiveSecurityError("destination-symlink-traversal", `${ERROR_ARCHIVE_ENTRY_TRAVERSES_SYMLINK}: ${formatErrorDetail(originalPath)}`);
@@ -105,55 +109,79 @@ async function mkdirArchiveOutput(params) {
     }
 }
 export async function prepareArchiveOutputPath(params) {
+    checkExtractionDeadline(params.deadline);
     const targetRoot = await root(params.destinationRealDir);
+    checkExtractionDeadline(params.deadline);
     const destinationGuard = await createDirectoryIdentityGuard(params.destinationRealDir);
+    checkExtractionDeadline(params.deadline);
     const relPath = params.relPath.split(path.sep).join(path.posix.sep);
     await assertNoSymlinkTraversal({
         rootDir: params.destinationDir,
         relPath,
         originalPath: params.originalPath,
     });
+    checkExtractionDeadline(params.deadline);
     if (params.isDirectory) {
         await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("mkdir", params.outPath);
-        await assertDirectoryIdentityGuard(destinationGuard);
-        await mkdirArchiveOutput({ targetRoot, relativePath: relPath, originalPath: params.originalPath });
-        await assertDirectoryIdentityGuard(destinationGuard);
-        await assertResolvedInsideDestination({
-            destinationRealDir: params.destinationRealDir,
-            targetPath: params.outPath,
-            originalPath: params.originalPath,
+        checkExtractionDeadline(params.deadline);
+        await ownExtractionDestinationMutation(params.deadline, async () => {
+            await assertDirectoryIdentityGuard(destinationGuard);
+            checkExtractionDeadline(params.deadline);
+            await mkdirArchiveOutput({
+                targetRoot,
+                relativePath: relPath,
+                originalPath: params.originalPath,
+            });
+            checkExtractionDeadline(params.deadline);
+            await assertDirectoryIdentityGuard(destinationGuard);
+            checkExtractionDeadline(params.deadline);
+            await assertResolvedInsideDestination({
+                destinationRealDir: params.destinationRealDir,
+                targetPath: params.outPath,
+                originalPath: params.originalPath,
+            });
+            checkExtractionDeadline(params.deadline);
         });
         return;
     }
     const parentRel = path.posix.dirname(relPath);
     if (parentRel !== ".") {
         await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("mkdir", path.dirname(params.outPath));
-        await assertDirectoryIdentityGuard(destinationGuard);
-        await mkdirArchiveOutput({
-            targetRoot,
-            relativePath: parentRel,
-            originalPath: params.originalPath,
+        checkExtractionDeadline(params.deadline);
+        await ownExtractionDestinationMutation(params.deadline, async () => {
+            await assertDirectoryIdentityGuard(destinationGuard);
+            checkExtractionDeadline(params.deadline);
+            await mkdirArchiveOutput({
+                targetRoot,
+                relativePath: parentRel,
+                originalPath: params.originalPath,
+            });
+            checkExtractionDeadline(params.deadline);
+            await assertDirectoryIdentityGuard(destinationGuard);
+            checkExtractionDeadline(params.deadline);
         });
-        await assertDirectoryIdentityGuard(destinationGuard);
     }
     await assertResolvedInsideDestination({
         destinationRealDir: params.destinationRealDir,
         targetPath: path.dirname(params.outPath),
         originalPath: params.originalPath,
     });
+    checkExtractionDeadline(params.deadline);
 }
 async function chmodInsideDestinationBestEffort(params) {
     await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("chmod", params.destinationPath);
+    checkExtractionDeadline(params.deadline);
     const destinationGuard = await createDirectoryIdentityGuard(params.destinationRealDir);
+    checkExtractionDeadline(params.deadline);
     await assertDirectoryIdentityGuard(destinationGuard);
-    const noFollowFlag = process.platform !== "win32" && "O_NOFOLLOW" in fsSync.constants
-        ? fsSync.constants.O_NOFOLLOW
-        : 0;
+    checkExtractionDeadline(params.deadline);
     const handle = await fs
-        .open(params.destinationPath, fsSync.constants.O_RDONLY | noFollowFlag)
+        .open(params.destinationPath, resolveReadOpenFlags())
         .catch(() => null);
+    checkExtractionDeadline(params.deadline);
     if (!handle) {
         const stat = await fs.lstat(params.destinationPath).catch(() => null);
+        checkExtractionDeadline(params.deadline);
         if (stat?.isSymbolicLink()) {
             throw symlinkTraversalError(params.originalPath);
         }
@@ -161,35 +189,45 @@ async function chmodInsideDestinationBestEffort(params) {
     }
     try {
         const stat = await handle.stat();
+        checkExtractionDeadline(params.deadline);
         if (!stat.isDirectory() && !stat.isFile()) {
             return;
         }
         const realPath = await resolveOpenedFileRealPathForHandle(handle, params.destinationPath);
+        checkExtractionDeadline(params.deadline);
         if (!isPathInside(params.destinationRealDir, realPath)) {
             throw symlinkTraversalError(params.originalPath);
         }
-        await handle.chmod(params.mode).catch(() => undefined);
-        await assertDirectoryIdentityGuard(destinationGuard);
+        await ownExtractionDestinationMutation(params.deadline, async () => {
+            await handle.chmod(params.mode).catch(() => undefined);
+            checkExtractionDeadline(params.deadline);
+            await assertDirectoryIdentityGuard(destinationGuard);
+            checkExtractionDeadline(params.deadline);
+        });
     }
     finally {
         await handle.close().catch(() => undefined);
     }
 }
 async function applyStagedEntryMode(params) {
+    checkExtractionDeadline(params.deadline);
     const destinationPath = path.join(params.destinationRealDir, params.relPath);
     await assertResolvedInsideDestination({
         destinationRealDir: params.destinationRealDir,
         targetPath: destinationPath,
         originalPath: params.originalPath,
     });
+    checkExtractionDeadline(params.deadline);
     if (params.mode !== 0) {
         await chmodInsideDestinationBestEffort({
             destinationRealDir: params.destinationRealDir,
             destinationPath,
             mode: params.mode,
             originalPath: params.originalPath,
+            deadline: params.deadline,
         });
     }
+    checkExtractionDeadline(params.deadline);
 }
 async function assertExtractedFileHasNoHardlinkAlias(params) {
     const destinationPath = path.join(params.destinationRealDir, params.relPath);
@@ -296,6 +334,7 @@ export async function mergeExtractedTreeIntoDestination(params) {
                     outPath: destinationPath,
                     originalPath,
                     isDirectory: true,
+                    deadline: params.deadline,
                 });
                 await walk(sourcePath);
                 await applyStagedEntryMode({
@@ -303,6 +342,7 @@ export async function mergeExtractedTreeIntoDestination(params) {
                     relPath,
                     mode: sourceStat.mode & 0o777,
                     originalPath,
+                    deadline: params.deadline,
                 });
                 continue;
             }
@@ -316,31 +356,39 @@ export async function mergeExtractedTreeIntoDestination(params) {
                 outPath: destinationPath,
                 originalPath,
                 isDirectory: false,
+                deadline: params.deadline,
             });
-            try {
-                await targetRoot.copyIn(relPath, sourcePath, { mkdir: true });
-                await assertExtractedFileHasNoHardlinkAlias({
-                    destinationRealDir: params.destinationRealDir,
-                    relPath,
-                    originalPath,
-                });
-                await applyStagedEntryMode({
-                    destinationRealDir: params.destinationRealDir,
-                    relPath,
-                    mode: sourceStat.mode & 0o777,
-                    originalPath,
-                });
-            }
-            catch (err) {
-                await removeExtractedDestinationFile({
-                    destinationRealDir: params.destinationRealDir,
-                    relPath,
-                });
-                if (err instanceof FsSafeError && (err.code === "hardlink" || err.code === "path-alias")) {
-                    throw symlinkTraversalError(originalPath);
+            await ownExtractionDestinationMutation(params.deadline, async () => {
+                try {
+                    await targetRoot.copyIn(relPath, sourcePath, { mkdir: true });
+                    checkExtractionDeadline(params.deadline);
+                    await assertExtractedFileHasNoHardlinkAlias({
+                        destinationRealDir: params.destinationRealDir,
+                        relPath,
+                        originalPath,
+                    });
+                    checkExtractionDeadline(params.deadline);
+                    await applyStagedEntryMode({
+                        destinationRealDir: params.destinationRealDir,
+                        relPath,
+                        mode: sourceStat.mode & 0o777,
+                        originalPath,
+                        deadline: params.deadline,
+                    });
+                    checkExtractionDeadline(params.deadline);
                 }
-                throw err;
-            }
+                catch (err) {
+                    await removeExtractedDestinationFile({
+                        destinationRealDir: params.destinationRealDir,
+                        relPath,
+                    });
+                    if (err instanceof FsSafeError &&
+                        (err.code === "hardlink" || err.code === "path-alias")) {
+                        throw symlinkTraversalError(originalPath);
+                    }
+                    throw err;
+                }
+            });
         }
     };
     await walk(params.sourceDir);

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

@@ -0,0 +1,7 @@
+import type { TarEntryInfo } from "./archive-tar.js";
+export declare function rawTarMember(header: Buffer, size: number, effectivePath?: string): TarEntryInfo;
+export declare function createTarAdmissionPlan(manifest: readonly TarEntryInfo[], check: (entry: TarEntryInfo) => boolean, strip: number): {
+    consume(entry: TarEntryInfo): string | null;
+    finish(): void;
+};
+//# sourceMappingURL=archive-tar-admission.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-tar-admission.d.ts","sourceRoot":"","sources":["../src/archive-tar-admission.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAYrD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,YAAY,CAS/F;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,KAAK,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,EACvC,KAAK,EAAE,MAAM,GACZ;IAAE,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,IAAI,IAAI,CAAA;CAAE,CAmBjE"}

package/dist/archive-tar-admission.js

@@ -0,0 +1,43 @@
+import { ArchiveFormatError } from "./archive-errors.js";
+import { stripArchivePath, validateArchiveEntryPath } from "./archive-entry.js";
+import { readTarHeaderPaths } from "./archive-tar-header.js";
+// node-tar's normalFsTypes/ReadEntry switch. All other non-metadata types
+// bypass both its filter and entry event; they still belong to our manifest.
+// Header.decode normalizes NUL to "0" before choosing the emitted File type.
+const visibleTypes = new Map([
+    [0, "File"], [0x30, "File"], [0x31, "Link"], [0x32, "SymbolicLink"],
+    [0x33, "CharacterDevice"], [0x34, "BlockDevice"], [0x35, "Directory"],
+    [0x36, "FIFO"], [0x37, "ContiguousFile"], [0x44, "GNUDumpDir"],
+]);
+export function rawTarMember(header, size, effectivePath) {
+    const { name, prefix } = readTarHeaderPaths(header);
+    validateArchiveEntryPath(name);
+    validateArchiveEntryPath(prefix);
+    const rawPath = prefix ? `${prefix}/${name}` : name;
+    validateArchiveEntryPath(rawPath);
+    const path = effectivePath ?? rawPath;
+    validateArchiveEntryPath(path);
+    return { path, size, type: visibleTypes.get(header[156]) ?? "Unsupported" };
+}
+export function createTarAdmissionPlan(manifest, check, strip) {
+    const visible = [];
+    for (const entry of manifest) {
+        const accepted = check(entry);
+        if (entry.type !== "Unsupported") {
+            visible.push({ entry, output: accepted ? stripArchivePath(entry.path, strip) : null });
+        }
+    }
+    let index = 0;
+    const mismatch = () => new ArchiveFormatError("invalid TAR header: parser disagrees with raw admission");
+    return {
+        consume(actual) {
+            const expected = visible[index++];
+            if (!expected || expected.entry.type !== actual.type || expected.entry.size !== actual.size ||
+                stripArchivePath(expected.entry.path, 0) !== stripArchivePath(actual.path, 0))
+                throw mismatch();
+            return expected.output;
+        },
+        finish() { if (index !== visible.length)
+            throw mismatch(); },
+    };
+}

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

@@ -0,0 +1,2 @@
+export declare function validateGnuMetadata(body: Buffer, type: "L" | "K"): string;
+//# sourceMappingURL=archive-tar-gnu.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-tar-gnu.d.ts","sourceRoot":"","sources":["../src/archive-tar-gnu.ts"],"names":[],"mappings":"AAKA,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,GAAG,GAAG,MAAM,CAazE"}

package/dist/archive-tar-gnu.js

@@ -0,0 +1,20 @@
+import { ArchiveFormatError } from "./archive-errors.js";
+import { validateArchiveEntryPath } from "./archive-entry.js";
+// Keep the byte grammar aligned with native/src/tar_meter.rs. Parsers differ
+// on embedded NULs and malformed UTF-8, so validate before either sees a name.
+export function validateGnuMetadata(body, type) {
+    const value = body.at(-1) === 0 ? body.subarray(0, -1) : body;
+    if (!value.length || value.includes(0)) {
+        throw new ArchiveFormatError("invalid GNU metadata: empty name or embedded NUL");
+    }
+    let name;
+    try {
+        name = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(value);
+    }
+    catch {
+        throw new ArchiveFormatError("invalid GNU metadata: name is not valid UTF-8");
+    }
+    if (type === "L")
+        validateArchiveEntryPath(name);
+    return name;
+}

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

@@ -0,0 +1,8 @@
+export declare function validateTarChecksum(header: Buffer): void;
+export declare function readTarHeaderPaths(header: Buffer): {
+    name: string;
+    prefix: string;
+    linkname: string;
+};
+export declare function validateTarHeader(header: Buffer): void;
+//# sourceMappingURL=archive-tar-header.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-tar-header.d.ts","sourceRoot":"","sources":["../src/archive-tar-header.ts"],"names":[],"mappings":"AAGA,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAWxD;AAcD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CASrG;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAUtD"}

package/dist/archive-tar-header.js

@@ -0,0 +1,47 @@
+import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
+const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+export function validateTarChecksum(header) {
+    const field = header.subarray(148, 156);
+    const end = field.indexOf(0);
+    const digits = field.subarray(0, end < 0 ? field.length : end).toString("latin1").replace(/^ +| +$/g, "");
+    const sum = header.reduce((total, byte, index) => total + (index >= 148 && index < 156 ? 32 : byte), 0);
+    // Require an in-field delimiter: node-tar otherwise reads into the typeflag.
+    if (!/^[0-7]+$/.test(digits) || ![0, 32].includes(field[7]) ||
+        (end >= 0 && field.subarray(end).some((byte) => byte !== 0 && byte !== 32)) ||
+        Number.parseInt(digits, 8) !== sum) {
+        throw new ArchiveFormatError("invalid TAR header: checksum failure");
+    }
+}
+function fixedField(field) {
+    const zero = field.indexOf(0);
+    if (zero >= 0 && field.subarray(zero).some((byte) => byte !== 0)) {
+        throw new ArchiveSecurityError("entry-path", "tar entry path contains bytes after NUL");
+    }
+    try {
+        return utf8.decode(field.subarray(0, zero < 0 ? field.length : zero));
+    }
+    catch {
+        throw new ArchiveSecurityError("entry-path", "tar entry path is not valid UTF-8");
+    }
+}
+export function readTarHeaderPaths(header) {
+    // node-tar's star layout uses a 130-byte prefix followed by atime/ctime.
+    const prefixEnd = header[475] === 0 ? 475 : 500;
+    return {
+        name: fixedField(header.subarray(0, 100)),
+        prefix: header.subarray(257, 265).equals(Buffer.from("ustar\0" + "00"))
+            ? fixedField(header.subarray(345, prefixEnd)) : "",
+        linkname: fixedField(header.subarray(157, 257)),
+    };
+}
+export function validateTarHeader(header) {
+    validateTarChecksum(header);
+    const { linkname } = readTarHeaderPaths(header);
+    const isLink = header[156] === 0x31 || header[156] === 0x32;
+    if (isLink && !linkname) {
+        throw new ArchiveFormatError("invalid TAR header: linkname required on a link header");
+    }
+    if (!isLink && linkname) {
+        throw new ArchiveFormatError("invalid TAR header: linkname forbidden on a non-link header");
+    }
+}