@openclaw/fs-safe 0.6.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## 0.7.1 - 2026-09-01
+
+### Highlights
+
+- **Make lock handoffs reliable:** recover from disappearing ownership records within retry budgets, preserve callback errors, and safely retry failed synchronous release cleanup.
+- **Reject corrupt native ZIP reads:** verify decoded entry length against the declared size before returning bytes, while retaining byte caps and CRC checks.
+- **Preserve long destination filenames:** use independent private staging names for Root writes and copies, ZIP extraction, and synchronous JSON writes instead of lengthening the destination basename.
+
+### File locks
+
+- Recover Root-backed asynchronous handoffs from unlinked opened records with exact descriptor identity and unlink evidence, including Windows resolver `EPERM`/`EBADF` failures. Recheck canonical ancestors and charge discarded observations to retry/deadline budgets without granting release or reclaim authority. ([#189](https://github.com/openclaw/fs-safe/pull/189))
+- Retry Root lock contention when a holder changes between pre-open inspection and opening the file. Discard only the verified stale observation, recheck canonical ancestors, and require fresh exclusive creation; generic reads, creator admission, and release/reclaim authority remain unchanged.
+- Verify reopened Root-created sidecars against the creator's exact serialized bytes and ownership token before admission. Reject replacements and unlinked descriptors, and retain the original creator receipt for failed-acquisition cleanup. ([#189](https://github.com/openclaw/fs-safe/pull/189))
+- Align Windows synchronous lock-parent canonicalization with Root, including short-name expansion, and bound lock-file create/open denials and missing or changed snapshot retries. Preserve the original `EPERM` when a retry budget is exhausted. ([#189](https://github.com/openclaw/fs-safe/pull/189))
+- Determine synchronous lock staleness from the captured payload timestamp or snapshot mtime, avoiding false stale decisions after unlink or replacement. ([#189](https://github.com/openclaw/fs-safe/pull/189))
+- Retain failed synchronous release cleanup for safe retries without double-decrementing references, re-closing a consumed or reused descriptor, or deleting a replacement sidecar. ([#189](https://github.com/openclaw/fs-safe/pull/189))
+- Propagate payload, JSON serialization, and parsing failures unchanged without retrying the failing callback. Scope Root failure evidence to each observation so historical errors cannot trigger retries in later, nested, or concurrent acquisitions. ([#190](https://github.com/openclaw/fs-safe/pull/190))
+
+### File writes and archives
+
+- Keep private staging names independent of destination basenames across guarded Root writes and copies, native Windows writes, ZIP extraction, and `writeJsonSync()`. Preserve public producer filenames, custom `tempPrefix`, and literal JSON parent-path and drive-relative semantics. ([#191](https://github.com/openclaw/fs-safe/pull/191))
+- Avoid opening an existing target merely to inherit its mode during create-only Root writes, while preserving boundary, alias, hardlink, and type checks. ([#189](https://github.com/openclaw/fs-safe/pull/189))
+- Reject native `readArchiveEntry()` ZIP payloads whose decoded length differs from the declared uncompressed size with `ArchiveFormatError("archive-header-invalid")`, matching JavaScript behavior while preserving `maxBytes` and CRC checks. ([#189](https://github.com/openclaw/fs-safe/pull/189))
+
+### Docs and validation
+
+- Clarify that invalid UTF-8 or nonzero bytes after NUL terminators in fixed TAR name, linkname, and USTAR prefix fields reject with `ArchiveSecurityError("entry-path")`; this documents existing behavior. ([#189](https://github.com/openclaw/fs-safe/pull/189))
+- Add cross-process contention and release-retry proofs, plus focused lock-admission and ZIP-integrity coverage in JavaScript-fallback and required-native CI paths. Refresh the release checklist for eight-package trusted publishing.
+
+## 0.7.0 - 2026-08-31
+
+### Highlights
+
+- **Safer reads and writes:** extend exact identity checks and retained-descriptor publication to reject substituted inputs and detect publication mismatches, including rounded-equal Windows file IDs.
+- **Opt into bounded temp cleanup:** `cleanupSafety: "require-bounded"` prevents recursive traversal of substituted workspace trees, while the compatible default remains available without native support. See the [cleanup guarantees and POSIX limits](https://fs-safe.io/temp.html#private-temp-workspaces).
+- **Harden untrusted archive handling:** reject hidden path aliases, ambiguous TAR metadata, corrupt gzip streams, and excessive decoded data before publication; align filtering and entry reads across JavaScript and native backends.
+- **Preserve queued work and durability:** generation-bound claims protect newer same-ID entries from acknowledgement or quarantine, and queue transitions and synchronous store writes sync their filesystem changes.
+- **Make lock handoffs and timeouts reliable:** recover from ownership records unlinked during contention, surface release failures, and finish in-flight archive publication or rollback before returning a timeout.
+
+### Compatibility and upgrade notes
+
+- **Claim queued entries before processing.** Call `loadJsonDurableQueueEntry()` or the batch loader before acknowledgement, rather than pairing a direct read with `ackJsonDurableQueueEntry()`. A pending entry without a processing claim now rejects; missing entries remain idempotent no-ops. Queue and failed directories must share a filesystem with hardlink support for quarantine. See the [queue recovery contract](https://fs-safe.io/store.html).
+- **Handle the new cleanup result.** `TempWorkspaceCleanupResult` adds `"indeterminate"` for cleanup whose safe completion cannot be established. Exhaustive result handlers must accept it; do not treat it as successful removal or blindly delete retained artifacts.
+- **Archive filters receive canonical pre-strip paths.** `entryFilter` now sees normalized separators, dot components, and effective metadata names rather than alternate spellings of the same entry. Update filters that match raw aliases; invalid `onFiltered` values reject before extraction rather than enabling skipping.
+- **Validate limits and handle surfaced errors.** Root, FileStore, secure/secret/regular reads, durable queues, and external output require `maxBytes` to be a non-negative safe integer or positive `Infinity`; zero is enforced and `undefined` retains configured defaults. Lock retry/deadline numbers are validated. Handle propagated release, failed-acquire cleanup, and durability failures; exhaustive archive-limit handlers must accept `archive-decoded-size-exceeds-limit`.
+
+### File safety and temp cleanup
+
+- Verify regular-file reads, root-file adapters, archive staging, `Root.copyIn()` sources, and durable JSON queue reads with lossless bigint identities. Reject replacements whose IDs round to the same JavaScript number and unresolved Windows identities before reading bytes; public numeric `Stats` receipts remain unchanged.
+- Verify async and sync regular-file append targets against exact pre-open, descriptor, and current-path identities, rejecting rounded-equal replacements and persistent unknown Windows identities before chmod or append.
+- Retain async and sync atomic replacement descriptors across `beforeRename`, retries, copy fallback, and publication. Reject substituted, non-regular, or hardlinked stages and preserve unowned cleanup paths. `replaceFileAtomic()` and its sync variant add `renameIdentity: "verify-content-with-lock"` for rename-unstable FUSE mounts: an explicit weaker identity contract for cooperating writers, not protection against same-authority actors ignoring the lock.
+- Pin callback-produced sibling temps through mode application, optional fsync, rename, and publication checks. Preserve unverified paths and producer modes, retain disabled sync defaults and best-effort file/directory chmod, and admit read-only descriptors unless `writeSiblingTempFile` requests file sync.
+- Apply `writeJsonSync()` best-effort file-mode tightening only through a reopened, single-link regular descriptor matching the staged bigint identity, so a swap cannot chmod an unrelated file.
+- Add native handle-relative temp workspace removal with collision-safe quarantine, enumerated-child identity checks, mount-crossing rejection, and symlink/reparse leaf removal without target traversal. Windows deletes exact opened handles; POSIX retains a documented final name-based race bounded to one substituted leaf or empty directory entry, never recursive traversal of a substituted nonempty tree.
+- Require usable Linux `openat2` with `RESOLVE_NO_XDEV` at runtime for bounded cleanup. Compatible mode falls back when unavailable; `cleanupSafety: "require-bounded"` rejects before creating a child.
+- Open attacker-raceable secure, secret, archive, queue, publication, fallback, and lock-file read paths nonblocking on POSIX, so a FIFO substitution cannot stall admission, deadlines, or cleanup verification.
+
+### Archive extraction and reads
+
+- Prevent archive path aliases from bypassing excluded subtrees: pass canonical pre-strip paths to `entryFilter` across JavaScript/native ZIP, TAR, gzip, zstd, and bzip2, while retaining raw-path validation, stripping, collision checks, and filter rejection policy.
+- Reject ambiguous TAR EOF framing, unsafe numeric sizes, and bodies on raw directory/link entries before parsing. Enforce an absolute decoded-byte ceiling through physical EOF, including metadata and zero padding, before extraction publication or entry-read success; report `archive-decoded-size-exceeds-limit` on overflow.
+- Bound retained TAR manifests with a shared budget capped at 64 MiB, independent of compressed input size. Validate checksums, strict fixed-field UTF-8, NFC/NFD component lengths, GNU effective trailing separators, and linkname/type consistency before metadata processing or caller policy.
+- Validate GNU long-name/link bodies on both backends before parsing: reject malformed UTF-8/NUL structure, repeated or dangling metadata, mixed PAX/GNU chains, and unsafe effective names, while preserving original bytes and valid L+K pairs.
+- Apply ordered path, count, strip, depth, collision, and filter policy even to TAR records parsers would ignore (`V`, `A`, `I`, `M`, and unknown typeflags). Safely omit accepted unsupported records, validate raw names hidden by metadata or NUL terminators, and align native device/FIFO filtering and GNUDumpDir handling with JavaScript.
+- Stop starting archive destination mutations at the timeout boundary and wait for any already-running destination mutation and rollback before rejecting. Non-mutating work retains prompt deadlines; publication cannot continue after the timeout is reported.
+- Match `readArchiveEntry()` to extraction's validated canonical pre-strip paths and effective metadata names across all supported formats/backends. Preserve directory, link, collision, integrity, and byte-limit checks; read `maxBytes` remains a requested-entry budget, separate from archive-wide decoding and metadata limits.
+- Charge TAR `maxEntryBytes` and `maxExtractedBytes` only to entries accepted after strip/filter policy, not skipped or fully stripped members. Raw framing, logical entry counts, metadata, and absolute decoded-byte limits still apply to the whole archive.
+- Accept highly compressible gzip TARs within fs-safe's explicit limits consistently across backends by disabling node-tar's extra 1000x ratio threshold only after complete decoded-byte admission. Archive, decoded, entry, output, and deadline limits remain enforced.
+- Preserve large finite TAR limits such as `Number.MAX_VALUE` in native `auto`/`require` modes through shared internal metadata/decoded-byte and u32 entry-count clamping before backend selection; retain high-level payload budgets and reject malformed direct native limits.
+- Update native gzip/DEFLATE decoding to flate2 1.1.10 and miniz_oxide 0.9.1, including upstream incomplete-stream fixes. Truncated bodies, missing trailers, and checksum failures reject before extraction publishes files or an entry read returns bytes.
+
+### Durable queues, stores, and locks
+
+- Claim durable queue generations under a fail-closed cross-process lock using no-replace hardlinks and recoverable source retirement. Acknowledgement and quarantine preserve newer same-ID replacements, and quarantine collisions preserve existing failed-entry evidence.
+- Fsync affected directories for queue creation, claims, acknowledgement, quarantine, marker cleanup, and retirement; propagate durability failures. Synchronous file-store writes now fsync temps before rename and parent directories after publication.
+- Retry Root-backed sidecar acquisition when the owner unlinks its record after the waiter opens it, but only after the same Root capability proves absence. Replacements remain fail-closed; generic `Root.open()` behavior is unchanged.
+- Propagate asynchronous sidecar release and failed-acquire deletion failures, preserve paired errors, and retain failed release state for a safe retry through the same handle or manager drain.
+- Clamp synchronous lock backoff to the remaining finite deadline instead of overshooting the timeout or blocking forever.
+
 ## 0.6.0 - 2026-08-29
 
 ### Highlights

package/README.md

@@ -393,6 +393,13 @@ cleanup. Retry, dedupe, and transport semantics stay with the caller.
 `tempWorkspace()` exposes `write()`, `writeText()`, `writeJson()`, `copyIn()`, and `read()` for
 single-file scratch workflows without hand-rolled path joins, plus a `store: FileStore` view of
 the workspace dir for the richer cases (`writeStream`, `readJsonIfExists`, `store.json<T>(rel)`).
+Compatible creation and cleanup remain available without native support.
+Set `cleanupSafety: "require-bounded"` to require collision-safe quarantine and
+descriptor-bounded recursive cleanup before creating a child. See the
+[temp workspace contract](docs/temp.md).
+Linux bounded cleanup requires the exact `openat2`/`RESOLVE_NO_XDEV` capability
+at runtime; compatible mode falls back when unavailable, while `require-bounded`
+rejects before child creation.
 
 `tempFile()` is the smaller one-file temp helper. It is intentionally an
 advanced primitive: use `tempWorkspace()` for the stable temp surface and reach

package/dist/archive-deadline.d.ts

@@ -1,8 +1,11 @@
 export type ExtractionDeadline = {
     signal: AbortSignal;
     check: () => void;
+    ownDestinationMutation: <T>(run: () => Promise<T>) => Promise<T>;
+    waitForDestinationMutations: () => Promise<void>;
     dispose: () => void;
 };
+export declare function ownExtractionDestinationMutation<T>(deadline: ExtractionDeadline | undefined, run: () => Promise<T>): Promise<T>;
 export declare function createPipelineTimeoutError(err: unknown, deadline: ExtractionDeadline): unknown;
 export declare function waitForDeadline<T>(promise: Promise<T>, deadline: ExtractionDeadline): Promise<T>;
 export declare function withExtractionDeadline<T>(timeoutMs: number, label: string, run: (deadline: ExtractionDeadline) => Promise<T>): Promise<T>;

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

@@ -1 +1 @@
-{"version":3,"file":"archive-deadline.d.ts","sourceRoot":"","sources":["../src/archive-deadline.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAWF,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAST;AAED,wBAAsB,eAAe,CAAC,CAAC,EACrC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAAC,CAAC,CAAC,CAgBZ;AA4BD,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,CAAC,CAAC,CAAC,GAChD,OAAO,CAAC,CAAC,CAAC,CAQZ"}
+{"version":3,"file":"archive-deadline.d.ts","sourceRoot":"","sources":["../src/archive-deadline.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,sBAAsB,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACjE,2BAA2B,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF,wBAAsB,gCAAgC,CAAC,CAAC,EACtD,QAAQ,EAAE,kBAAkB,GAAG,SAAS,EACxC,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC,CAEZ;AAWD,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAST;AAED,wBAAsB,eAAe,CAAC,CAAC,EACrC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAAC,CAAC,CAAC,CAgBZ;AAyDD,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,CAAC,CAAC,CAAC,GAChD,OAAO,CAAC,CAAC,CAAC,CAkBZ"}

package/dist/archive-deadline.js

@@ -1,3 +1,6 @@
+export async function ownExtractionDestinationMutation(deadline, run) {
+    return deadline ? await deadline.ownDestinationMutation(run) : await run();
+}
 function signalReason(signal, fallback) {
     const reason = signal.reason;
     return reason instanceof Error ? reason : fallback ?? new Error(String(reason));
@@ -30,26 +33,48 @@ export async function waitForDeadline(promise, deadline) {
         }),
     ]);
 }
+function createDestinationMutationOwner(check) {
+    const active = new Set();
+    return {
+        ownDestinationMutation: async (run) => {
+            check();
+            const operation = Promise.resolve().then(run);
+            const tracked = operation.then(() => undefined, () => undefined);
+            active.add(tracked);
+            void tracked.finally(() => active.delete(tracked));
+            return await operation;
+        },
+        waitForDestinationMutations: async () => {
+            while (active.size > 0) {
+                await Promise.all(active);
+            }
+        },
+    };
+}
 function createExtractionDeadline(timeoutMs, label) {
     const controller = new AbortController();
+    const timeoutError = new Error(`${label} timed out after ${timeoutMs}ms`);
+    const check = () => {
+        if (controller.signal.aborted) {
+            throw signalReason(controller.signal, timeoutError);
+        }
+    };
+    const mutationOwner = createDestinationMutationOwner(check);
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
         return {
             signal: controller.signal,
-            check: () => undefined,
+            check,
+            ...mutationOwner,
             dispose: () => undefined,
         };
     }
-    const timeoutError = new Error(`${label} timed out after ${timeoutMs}ms`);
     const timeoutId = setTimeout(() => {
         controller.abort(timeoutError);
     }, timeoutMs);
     return {
         signal: controller.signal,
-        check: () => {
-            if (controller.signal.aborted) {
-                throw signalReason(controller.signal, timeoutError);
-            }
-        },
+        check,
+        ...mutationOwner,
         dispose: () => {
             clearTimeout(timeoutId);
         },
@@ -57,9 +82,20 @@ function createExtractionDeadline(timeoutMs, label) {
 }
 export async function withExtractionDeadline(timeoutMs, label, run) {
     const deadline = createExtractionDeadline(timeoutMs, label);
+    const operation = Promise.resolve().then(async () => await run(deadline));
     try {
         deadline.check();
-        return await waitForDeadline(run(deadline), deadline);
+        try {
+            return await waitForDeadline(operation, deadline);
+        }
+        catch (error) {
+            if (deadline.signal.aborted && error === deadlineReason(deadline)) {
+                // Preserve prompt timeout settlement for non-mutating work, but never
+                // return while live destination publication or rollback is still owned.
+                await deadline.waitForDestinationMutations();
+            }
+            throw error;
+        }
     }
     finally {
         deadline.dispose();

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

@@ -1 +1 @@
-{"version":3,"file":"archive-entry.d.ts","sourceRoot":"","sources":["../src/archive-entry.ts"],"names":[],"mappings":"AAKA,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAIzD;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAChC,IAAI,CA2DN;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc1F;AAED,wBAAgB,8BAA8B,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,IAAI,CAgBlG;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,MAAM,CAWT"}
+{"version":3,"file":"archive-entry.d.ts","sourceRoot":"","sources":["../src/archive-entry.ts"],"names":[],"mappings":"AAKA,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAIzD;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAChC,IAAI,CA2DN;AAGD,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc1F;AAED,wBAAgB,8BAA8B,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,IAAI,CAgBlG;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,MAAM,CAWT"}

package/dist/archive-entry.js

@@ -40,6 +40,7 @@ export function validateArchiveEntryPath(entryPath, params) {
         throw new ArchiveSecurityError("entry-path", `archive entry contains a parent segment: ${formatErrorDetail(entryPath)}`);
     }
 }
+// Validate raw paths first. Zero stripping gives the canonical policy identity.
 export function stripArchivePath(entryPath, stripComponents) {
     const raw = normalizeArchiveEntryPath(entryPath);
     if (!raw || raw === "." || raw === "./") {

package/dist/archive-errors.d.ts

@@ -9,4 +9,5 @@ export declare class ArchiveFormatError extends Error {
     constructor(message: string, options?: ErrorOptions);
 }
 export declare function isArchiveFormatErrorMessage(message: string): boolean;
+export declare function isArchiveTarPathErrorMessage(message: string): boolean;
 //# sourceMappingURL=archive-errors.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"archive-errors.d.ts","sourceRoot":"","sources":["../src/archive-errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AAE9D,MAAM,MAAM,wBAAwB,GAChC,2BAA2B,GAC3B,qBAAqB,GACrB,+BAA+B,GAC/B,gBAAgB,GAChB,YAAY,GACZ,YAAY,CAAC;AAEjB,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IAExC,YAAY,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAIlF;CACF;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IAEtC,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAIlD;CACF;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAKpE"}
+{"version":3,"file":"archive-errors.d.ts","sourceRoot":"","sources":["../src/archive-errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AAE9D,MAAM,MAAM,wBAAwB,GAChC,2BAA2B,GAC3B,qBAAqB,GACrB,+BAA+B,GAC/B,gBAAgB,GAChB,YAAY,GACZ,YAAY,CAAC;AAEjB,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IAExC,YAAY,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAIlF;CACF;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IAEtC,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAIlD;CACF;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAKpE;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAErE"}

package/dist/archive-errors.js

@@ -18,3 +18,6 @@ export function isArchiveFormatErrorMessage(message) {
     return (message.includes("archive-header-invalid") ||
         message.includes("archive entry size did not match its manifest"));
 }
+export function isArchiveTarPathErrorMessage(message) {
+    return message.includes("archive-gnu-path-invalid") || message.includes("archive-entry-path-invalid");
+}

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

@@ -1 +1 @@
-{"version":3,"file":"archive-input.d.ts","sourceRoot":"","sources":["../src/archive-input.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAGL,KAAK,4BAA4B,EAClC,MAAM,qBAAqB,CAAC;AAI7B,MAAM,MAAM,iBAAiB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC;AAM/E,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,kBAAkB,CAAC;CAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CAchB;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,4BAA4B,CAAC;IACrC,QAAQ,EAAE,kBAAkB,CAAC;CAC9B,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA8D7B"}
+{"version":3,"file":"archive-input.d.ts","sourceRoot":"","sources":["../src/archive-input.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAGL,KAAK,4BAA4B,EAClC,MAAM,qBAAqB,CAAC;AAM7B,MAAM,MAAM,iBAAiB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC;AAM/E,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,kBAAkB,CAAC;CAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CAchB;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,4BAA4B,CAAC;IACrC,QAAQ,EAAE,kBAAkB,CAAC;CAC9B,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAiE7B"}

package/dist/archive-input.js

@@ -2,7 +2,9 @@ import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, } from "./archive-limits.js";
-import { sameFileIdentity } from "./file-identity.js";
+import { FsSafeError } from "./errors.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { tempFile } from "./temp-target.js";
 async function closeFileHandle(handle) {
     if (handle)
@@ -22,15 +24,17 @@ export async function writeFileHandleFully(params) {
 export 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}`);
-    }
+    const initialStat = await inspectFileIdentity(async () => {
+        const stat = await fs.lstat(sourcePath, { bigint: true });
+        if (stat.isSymbolicLink() || !stat.isFile()) {
+            throw new Error(`archive is not a regular file: ${params.archivePath}`);
+        }
+        return stat;
+    });
     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);
+    const handle = await fs.open(sourcePath, resolveReadOpenFlags());
     let staged;
     let output;
     try {
@@ -38,15 +42,18 @@ export async function stageArchiveFileForExtraction(params) {
             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");
-        }
+        const opened = await inspectFileIdentity(async () => {
+            const stat = await handle.stat({ bigint: true });
+            if (!stat.isFile())
+                throw new Error("archive changed during validation");
+            return stat;
+        }, initialStat);
+        await inspectFileIdentity(async () => {
+            const stat = await fs.lstat(sourcePath, { bigint: true });
+            if (stat.isSymbolicLink() || !stat.isFile())
+                throw new Error("archive changed during validation");
+            return stat;
+        }, opened);
         const flags = fsConstants.O_WRONLY |
             fsConstants.O_CREAT |
             fsConstants.O_EXCL |
@@ -74,6 +81,9 @@ export async function stageArchiveFileForExtraction(params) {
     catch (error) {
         await closeFileHandle(output);
         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 {

package/dist/archive-limits.d.ts

@@ -4,11 +4,11 @@ export type ArchiveExtractLimits = {
      * Max archive file bytes (compressed).
      */
     maxArchiveBytes?: number;
-    /** Max number of extracted entries (files + dirs). */
+    /** Max logical archive entries, including skipped/stripped members. */
     maxEntries?: number;
-    /** Max extracted bytes (sum of all files). */
+    /** Max extracted bytes across entries accepted after strip/filter policy. */
     maxExtractedBytes?: number;
-    /** Max extracted bytes for a single file entry. */
+    /** Max bytes in an entry accepted after strip/filter policy. */
     maxEntryBytes?: number;
     /** Max bytes in one PAX, GNU long-name, or related TAR metadata entry. */
     maxMetaEntryBytes?: number;
@@ -26,6 +26,7 @@ export declare const ARCHIVE_LIMIT_ERROR_CODE: {
     readonly ENTRY_COUNT_EXCEEDS_LIMIT: "archive-entry-count-exceeds-limit";
     readonly ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT: "archive-entry-extracted-size-exceeds-limit";
     readonly EXTRACTED_SIZE_EXCEEDS_LIMIT: "archive-extracted-size-exceeds-limit";
+    readonly DECODED_SIZE_EXCEEDS_LIMIT: "archive-decoded-size-exceeds-limit";
     readonly META_ENTRY_SIZE_EXCEEDS_LIMIT: "archive-meta-entry-size-exceeds-limit";
     readonly MANIFEST_SIZE_EXCEEDS_LIMIT: "archive-manifest-size-exceeds-limit";
     readonly ENTRY_PATH_COMPONENTS_EXCEEDS_LIMIT: "archive-entry-path-components-exceeds-limit";
@@ -36,6 +37,13 @@ export declare class ArchiveLimitError extends Error {
     constructor(code: ArchiveLimitErrorCode);
 }
 export type ResolvedArchiveExtractLimits = Required<ArchiveExtractLimits>;
+export type TarMeterLimits = Pick<ResolvedArchiveExtractLimits, "maxEntries" | "maxMetaEntryBytes"> & {
+    maxDecodedBytes: number;
+    maxManifestBytes: number;
+};
+export declare const MAX_TAR_MANIFEST_BYTES: number;
+export declare function tarManifestEntryCost(path: string): number;
+export declare function resolveTarMeterLimits(options?: ArchiveExtractLimits): TarMeterLimits;
 export declare function resolveExtractLimits(limits?: ArchiveExtractLimits): ResolvedArchiveExtractLimits;
 export declare function assertArchiveEntryPathComponentsWithinLimit(entryPath: string, limits: ResolvedArchiveExtractLimits): void;
 export declare function assertArchiveEntryCountWithinLimit(entryCount: number, limits: ResolvedArchiveExtractLimits): void;

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

@@ -1 +1 @@
-{"version":3,"file":"archive-limits.d.ts","sourceRoot":"","sources":["../src/archive-limits.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,MAAM,oBAAoB,GAAG;IACjC;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF,eAAO,MAAM,6BAA6B,QAAoB,CAAC;AAC/D,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAC1C,eAAO,MAAM,2BAA2B,QAAoB,CAAC;AAC7D,eAAO,MAAM,uBAAuB,QAAoB,CAAC;AACzD,eAAO,MAAM,4BAA4B,QAAc,CAAC;AACxD,eAAO,MAAM,iCAAiC,MAAM,CAAC;AAErD,eAAO,MAAM,wBAAwB;aACnC,0BAA0B,EAAE,4BAA4B;aACxD,yBAAyB,EAAE,mCAAmC;aAC9D,kCAAkC,EAAE,4CAA4C;aAChF,4BAA4B,EAAE,sCAAsC;aACpE,6BAA6B,EAAE,uCAAuC;aACtE,2BAA2B,EAAE,qCAAqC;aAClE,mCAAmC,EAAE,6CAA6C;CAC1E,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAC/B,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,OAAO,wBAAwB,CAAC,CAAC;AAgB3E,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IAErC,YAAY,IAAI,EAAE,qBAAqB,EAItC;CACF;AAED,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC,oBAAoB,CAAC,CAAC;AAU1E,wBAAgB,oBAAoB,CAClC,MAAM,CAAC,EAAE,oBAAoB,GAC5B,4BAA4B,CAY9B;AAED,wBAAgB,2CAA2C,CACzD,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,4BAA4B,GACnC,IAAI,CASN;AAED,wBAAgB,kCAAkC,CAChD,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,4BAA4B,QAKrC;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,4BAA4B,GAAG;IAC7E,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC,CAiCA;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE;IACnD,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC,GAAG,SAAS,CAYZ"}
+{"version":3,"file":"archive-limits.d.ts","sourceRoot":"","sources":["../src/archive-limits.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,MAAM,oBAAoB,GAAG;IACjC;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF,eAAO,MAAM,6BAA6B,QAAoB,CAAC;AAC/D,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAC1C,eAAO,MAAM,2BAA2B,QAAoB,CAAC;AAC7D,eAAO,MAAM,uBAAuB,QAAoB,CAAC;AACzD,eAAO,MAAM,4BAA4B,QAAc,CAAC;AACxD,eAAO,MAAM,iCAAiC,MAAM,CAAC;AAErD,eAAO,MAAM,wBAAwB;aACnC,0BAA0B,EAAE,4BAA4B;aACxD,yBAAyB,EAAE,mCAAmC;aAC9D,kCAAkC,EAAE,4CAA4C;aAChF,4BAA4B,EAAE,sCAAsC;aACpE,0BAA0B,EAAE,oCAAoC;aAChE,6BAA6B,EAAE,uCAAuC;aACtE,2BAA2B,EAAE,qCAAqC;aAClE,mCAAmC,EAAE,6CAA6C;CAC1E,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAC/B,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,OAAO,wBAAwB,CAAC,CAAC;AAiB3E,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IAErC,YAAY,IAAI,EAAE,qBAAqB,EAItC;CACF;AAED,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC,oBAAoB,CAAC,CAAC;AAE1E,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,4BAA4B,EAC5D,YAAY,GAAG,mBAAmB,CAAC,GAAG;IAAE,eAAe,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9F,eAAO,MAAM,sBAAsB,QAAmB,CAAC;AAEvD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,cAAc,CAkBpF;AAUD,wBAAgB,oBAAoB,CAClC,MAAM,CAAC,EAAE,oBAAoB,GAC5B,4BAA4B,CAY9B;AAED,wBAAgB,2CAA2C,CACzD,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,4BAA4B,GACnC,IAAI,CASN;AAED,wBAAgB,kCAAkC,CAChD,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,4BAA4B,QAKrC;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,4BAA4B,GAAG;IAC7E,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC,CAiCA;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE;IACnD,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC,GAAG,SAAS,CAYZ"}

package/dist/archive-limits.js

@@ -10,6 +10,7 @@ export const ARCHIVE_LIMIT_ERROR_CODE = {
     ENTRY_COUNT_EXCEEDS_LIMIT: "archive-entry-count-exceeds-limit",
     ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT: "archive-entry-extracted-size-exceeds-limit",
     EXTRACTED_SIZE_EXCEEDS_LIMIT: "archive-extracted-size-exceeds-limit",
+    DECODED_SIZE_EXCEEDS_LIMIT: "archive-decoded-size-exceeds-limit",
     META_ENTRY_SIZE_EXCEEDS_LIMIT: "archive-meta-entry-size-exceeds-limit",
     MANIFEST_SIZE_EXCEEDS_LIMIT: "archive-manifest-size-exceeds-limit",
     ENTRY_PATH_COMPONENTS_EXCEEDS_LIMIT: "archive-entry-path-components-exceeds-limit",
@@ -19,6 +20,7 @@ const ARCHIVE_LIMIT_ERROR_MESSAGE = {
     [ARCHIVE_LIMIT_ERROR_CODE.ENTRY_COUNT_EXCEEDS_LIMIT]: "archive entry count exceeds limit",
     [ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT]: "archive entry extracted size exceeds limit",
     [ARCHIVE_LIMIT_ERROR_CODE.EXTRACTED_SIZE_EXCEEDS_LIMIT]: "archive extracted size exceeds limit",
+    [ARCHIVE_LIMIT_ERROR_CODE.DECODED_SIZE_EXCEEDS_LIMIT]: "archive decoded size exceeds limit",
     [ARCHIVE_LIMIT_ERROR_CODE.META_ENTRY_SIZE_EXCEEDS_LIMIT]: "archive metadata entry size exceeds limit",
     [ARCHIVE_LIMIT_ERROR_CODE.MANIFEST_SIZE_EXCEEDS_LIMIT]: "archive manifest size exceeds limit",
     [ARCHIVE_LIMIT_ERROR_CODE.ENTRY_PATH_COMPONENTS_EXCEEDS_LIMIT]: "archive entry path components exceed limit",
@@ -31,6 +33,28 @@ export class ArchiveLimitError extends Error {
         this.code = code;
     }
 }
+export const MAX_TAR_MANIFEST_BYTES = 64 * 1024 * 1024;
+export function tarManifestEntryCost(path) {
+    return 64 + 2 * Buffer.byteLength(path, "utf8");
+}
+export function resolveTarMeterLimits(options) {
+    const limits = resolveExtractLimits(options);
+    const payload = Math.min(limits.maxExtractedBytes, Number.MAX_SAFE_INTEGER);
+    const overhead = Math.min(limits.maxArchiveBytes, Number.MAX_SAFE_INTEGER);
+    // Saturate before multiplying, including when public limits approach MAX_VALUE.
+    const pathBytes = Math.max(256, Math.min(limits.maxMetaEntryBytes, Math.min(Math.max(1, limits.maxEntryPathComponents), MAX_TAR_MANIFEST_BYTES / 256) * 256));
+    const perEntry = 64 + 2 * pathBytes;
+    const maxManifestBytes = limits.maxEntries > Math.floor(MAX_TAR_MANIFEST_BYTES / perEntry)
+        ? MAX_TAR_MANIFEST_BYTES : limits.maxEntries * perEntry;
+    // TAR sizes are safe integers; native logical entry counts use u32.
+    return {
+        maxEntries: Math.min(limits.maxEntries, 0xffff_ffff),
+        maxMetaEntryBytes: Math.min(limits.maxMetaEntryBytes, Number.MAX_SAFE_INTEGER),
+        maxManifestBytes,
+        maxDecodedBytes: payload > Number.MAX_SAFE_INTEGER - overhead
+            ? Number.MAX_SAFE_INTEGER : payload + overhead,
+    };
+}
 function clampLimit(value) {
     if (typeof value !== "number" || !Number.isFinite(value)) {
         return undefined;

package/dist/archive-native.d.ts

@@ -1,6 +1,6 @@
 import type { ExtractionDeadline } from "./archive-deadline.js";
 import type { ArchiveKind } from "./archive-kind.js";
-import { type ArchiveExtractLimits } from "./archive-limits.js";
+import { type ResolvedArchiveExtractLimits, type TarMeterLimits } from "./archive-limits.js";
 import type { ExtractArchiveOptions } from "./archive-options.js";
 import type { NativeBinding } from "./native.js";
 export declare function extractNativeArchive(params: {
@@ -9,7 +9,8 @@ export declare function extractNativeArchive(params: {
     destDir: string;
     kind: ArchiveKind;
     stripComponents?: number;
-    limits?: ArchiveExtractLimits;
+    limits: ResolvedArchiveExtractLimits;
+    tarLimits: TarMeterLimits;
     deadline: ExtractionDeadline;
     entryModes?: ExtractArchiveOptions["entryModes"];
     entryFilter?: ExtractArchiveOptions["entryFilter"];

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

@@ -1 +1 @@
-{"version":3,"file":"archive-native.d.ts","sourceRoot":"","sources":["../src/archive-native.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAOL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAOlE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAwBjD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,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,CAAC,EAAE,oBAAoB,CAAC;IAC9B,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,CA8HhB"}
+{"version":3,"file":"archive-native.d.ts","sourceRoot":"","sources":["../src/archive-native.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAML,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;AA2BjD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,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,CAsIhB"}

package/dist/archive-native.js

@@ -1,10 +1,10 @@
 import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
-import { ArchiveFormatError, ArchiveSecurityError, isArchiveFormatErrorMessage, } from "./archive-errors.js";
+import { ArchiveFormatError, ArchiveSecurityError, isArchiveFormatErrorMessage, isArchiveTarPathErrorMessage, } from "./archive-errors.js";
 import { formatErrorDetail } from "./error-detail.js";
 import { createArchiveOutputPathTracker, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
 import { stageArchiveFileForExtraction } from "./archive-input.js";
-import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWithinLimit, createByteBudgetTracker, resolveExtractLimits, } from "./archive-limits.js";
+import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWithinLimit, createByteBudgetTracker, } from "./archive-limits.js";
 import { resolveArchiveEntryMode, shouldExtractArchiveEntry } from "./archive-policy.js";
 import { mergeExtractedTreeIntoDestination, prepareArchiveDestinationDir, withStagedArchiveDestination, } from "./archive-staging.js";
 import { admitZipFile } from "./archive-zip-admission.js";
@@ -17,6 +17,9 @@ function policyKind(kind) {
 }
 function throwMappedNativeError(error) {
     if (error instanceof Error) {
+        if (isArchiveTarPathErrorMessage(error.message)) {
+            throw new ArchiveSecurityError("entry-path", error.message, { cause: error });
+        }
         for (const code of Object.values(ARCHIVE_LIMIT_ERROR_CODE)) {
             if (error.message.includes(code))
                 throw new ArchiveLimitError(code);
@@ -31,7 +34,7 @@ function throwMappedNativeError(error) {
     throw error;
 }
 export async function extractNativeArchive(params) {
-    const limits = resolveExtractLimits(params.limits);
+    const { limits, tarLimits } = params;
     const stagedArchive = await stageArchiveFileForExtraction({
         archivePath: params.archivePath,
         limits,
@@ -47,13 +50,19 @@ export async function extractNativeArchive(params) {
             run: async (stagingDir) => {
                 params.deadline.check();
                 const manifest = await params.binding
-                    .inspectArchiveNative(stagedArchive.path, params.kind, limits.maxEntries, limits.maxMetaEntryBytes, limits.maxArchiveBytes, params.deadline.signal)
+                    .inspectArchiveNative(stagedArchive.path, params.kind, tarLimits, params.deadline.signal)
                     .catch(throwMappedNativeError);
                 params.deadline.check();
                 assertArchiveEntryCountWithinLimit(manifest.length, limits);
                 if (physicalCount !== undefined && manifest.length !== physicalCount) {
                     throw new ArchiveSecurityError("entry-path", "zip decoder collapsed entry names");
                 }
+                // Recheck the native manifest at the shared policy boundary before
+                // any caller callback observes an entry.
+                if (params.kind !== "zip") {
+                    for (const entry of manifest)
+                        validateArchiveEntryPath(entry.path);
+                }
                 const strip = Math.max(0, Math.floor(params.stripComponents ?? 0));
                 const budget = createByteBudgetTracker(limits);
                 const trackOutputPath = createArchiveOutputPathTracker();
@@ -61,7 +70,10 @@ export async function extractNativeArchive(params) {
                 for (const entry of manifest) {
                     params.deadline.check();
                     validateArchiveEntryPath(entry.path);
-                    const relPath = stripArchivePath(entry.path, strip);
+                    const canonicalPath = stripArchivePath(entry.path, 0);
+                    if (!canonicalPath)
+                        continue;
+                    const relPath = stripArchivePath(canonicalPath, strip);
                     if (!relPath)
                         continue;
                     validateArchiveEntryPath(relPath);
@@ -72,21 +84,22 @@ export async function extractNativeArchive(params) {
                     if (!shouldExtractArchiveEntry({
                         filter: params.entryFilter,
                         onFiltered: params.onFiltered,
-                        entry: { path: entry.path, kind, size: entry.size },
+                        entry: { path: canonicalPath, kind, size: entry.size },
                     })) {
                         continue;
                     }
                     if (entry.kind === "sparse") {
                         throw new ArchiveFormatError(`GNU sparse archive entry is not supported: ${formatErrorDetail(entry.path)}`);
                     }
-                    if (kind === "symlink") {
+                    if (kind === "symlink" || entry.kind === "blocked") {
                         const label = params.kind === "zip" ? "zip" : "tar";
                         throw new ArchiveSecurityError("entry-link", `${label} entry is a link: ${formatErrorDetail(entry.path)}`);
                     }
                     if (!Number.isSafeInteger(entry.size) || entry.size < 0) {
                         throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
                     }
-                    if (kind === "file") {
+                    // GNUDumpDir can carry a body; charge accepted TAR sizes as JS does.
+                    if (kind === "file" || (kind === "directory" && params.kind !== "zip")) {
                         budget.startEntry();
                         budget.addEntrySize(entry.size);
                     }
@@ -108,7 +121,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, limits.maxMetaEntryBytes, params.deadline.signal).catch(throwMappedNativeError);
+                    await params.binding.extractArchiveNative(stagedArchive.path, params.kind, directory.fd, plan, tarLimits, params.deadline.signal).catch(throwMappedNativeError);
                 }
                 finally {
                     await directory.close().catch(() => undefined);
@@ -118,7 +131,9 @@ export async function extractNativeArchive(params) {
                     sourceDir: stagingDir,
                     destinationDir: params.destDir,
                     destinationRealDir,
+                    deadline: params.deadline,
                 });
+                params.deadline.check();
             },
         });
     }

package/dist/archive-policy.d.ts

@@ -2,6 +2,7 @@ export type ArchiveEntryKind = "file" | "directory" | "symlink" | "other";
 export type ArchiveEntryModePolicy = "clamp" | "preserve";
 export type ArchiveFilteredEntryPolicy = "reject-archive" | "skip-entry";
 export type ArchiveEntryFilter = (entry: {
+    /** Validated canonical archive path before stripping: / separators, no empty or . components. */
     path: string;
     kind: ArchiveEntryKind;
     size: number;
@@ -12,6 +13,7 @@ export declare function resolveArchiveEntryMode(params: {
     archivedMode?: number;
     policy?: ArchiveEntryModePolicy;
 }): number;
+export declare function resolveArchiveFilteredEntryPolicy(value: unknown): ArchiveFilteredEntryPolicy;
 export declare function shouldExtractArchiveEntry(params: {
     filter?: ArchiveEntryFilter;
     onFiltered?: ArchiveFilteredEntryPolicy;

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

@@ -1 +1 @@
-{"version":3,"file":"archive-policy.d.ts","sourceRoot":"","sources":["../src/archive-policy.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAC1E,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,UAAU,CAAC;AAC1D,MAAM,MAAM,0BAA0B,GAAG,gBAAgB,GAAG,YAAY,CAAC;AACzE,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd,KAAK,SAAS,GAAG,MAAM,CAAC;AAEzB,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAK1E;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,sBAAsB,CAAC;CACjC,GAAG,MAAM,CAST;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAChD,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,UAAU,CAAC,EAAE,0BAA0B,CAAC;IACxC,KAAK,EAAE,UAAU,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;CAC1C,GAAG,OAAO,CAWV"}
+{"version":3,"file":"archive-policy.d.ts","sourceRoot":"","sources":["../src/archive-policy.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAC1E,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,UAAU,CAAC;AAC1D,MAAM,MAAM,0BAA0B,GAAG,gBAAgB,GAAG,YAAY,CAAC;AACzE,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE;IACvC,iGAAiG;IACjG,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd,KAAK,SAAS,GAAG,MAAM,CAAC;AAEzB,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAK1E;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,sBAAsB,CAAC;CACjC,GAAG,MAAM,CAST;AAED,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,OAAO,GACb,0BAA0B,CAM5B;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAChD,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,UAAU,CAAC,EAAE,0BAA0B,CAAC;IACxC,KAAK,EAAE,UAAU,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;CAC1C,GAAG,OAAO,CAYV"}

package/dist/archive-policy.js

@@ -19,11 +19,19 @@ export function resolveArchiveEntryMode(params) {
     }
     return archivedMode & 0o100 ? 0o755 : 0o644;
 }
+export function resolveArchiveFilteredEntryPolicy(value) {
+    if (value === undefined || value === "reject-archive")
+        return "reject-archive";
+    if (value === "skip-entry")
+        return "skip-entry";
+    throw new RangeError('archive onFiltered must be "reject-archive" or "skip-entry"');
+}
 export function shouldExtractArchiveEntry(params) {
+    const onFiltered = resolveArchiveFilteredEntryPolicy(params.onFiltered);
     if (!params.filter || params.filter(params.entry) === "extract") {
         return true;
     }
-    if ((params.onFiltered ?? "reject-archive") === "reject-archive") {
+    if (onFiltered === "reject-archive") {
         throw new ArchiveSecurityError("entry-filtered", `archive entry rejected by filter: ${formatErrorDetail(params.entry.path)}`);
     }
     return false;

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

@@ -1 +1 @@
-{"version":3,"file":"archive-read.d.ts","sourceRoot":"","sources":["../src/archive-read.ts"],"names":[],"mappings":"AAcA,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA8MzE,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,CAuFjB"}
+{"version":3,"file":"archive-read.d.ts","sourceRoot":"","sources":["../src/archive-read.ts"],"names":[],"mappings":"AAcA,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAgOzE,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,CAuFjB"}