@openclaw/fs-safe 0.5.5 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 0.6.0 - 2026-08-29
+
+### Highlights
+
+- Install only the matching native platform package; deployments using native mode `require` or native-only features must keep optional dependencies enabled. See the [0.6 migration guide](https://fs-safe.io/migrating-to-0.6.html).
+- Strengthen root, secure, secret, and pathname-hash identity checks with lossless bigint comparisons and fail-closed handling of unknown Windows identities.
+- Add native-required Linux/macOS `stageFileInDirectory()` with retained-directory cleanup, private staging, identity-checked publication, and async disposal.
+- Validate physical ZIP metadata and names before decoder normalization or collapse, align bounded TAR/PAX and stripped-path handling, and reject ZIP symlinks disguised as directories.
+
+### Security and Correctness
+
+- Validate physical ZIP local/central and Unicode name metadata before decoding, rejecting traversal, hidden duplicates, and conflicting interpretations consistently in extraction and bounded reads.
+
+- Verify pathname SHA-256 hashing with lossless pre-open, descriptor, and current-path identities; fail closed on unknown Windows identities after one bounded retry without reopening the file.
+- Preserve underlying command diagnostics (command, timing, timeout flag, exit code/signal, and sanitized stderr) and cause on Windows ACL `permission-unverified` errors without changing verification semantics.
+- Verify secure and secret read identities with lossless bigint stats, reject replaced paths and retargeted aliases, and fail closed on unknown Windows identities after one bounded re-inspection; preserve the secure reader's numeric `Stats` receipt and permission options without letting them bypass identity checks.
+- Apply the same exact identity checks to guarded root reads, rejecting parent-directory replacements even when distinct Windows file IDs round to the same number; retain numeric read receipts and keep Windows write reopens anchored to the writer's exact retained identity.
+- Verify `Root.write()` and `create()` through retained descriptors and exact bigint identities for restrictive final modes, retaining guarded Windows path opens when pathname identity is unavailable; preserve explicit mode zero in `copyIn()`.
+- Preserve filesystem failures from `ensureDirectoryWithinRoot()` and `pathScope().ensureDir()` in an optional operational `FsSafeError` diagnostic with the original cause and bounded, escaped display text, instead of misreporting them as containment violations; keep nonthrowing string results and directory safety checks.
+- Accept bounded local PAX paths, sizes, and descriptive metadata, including inert binary macOS provenance xattrs, consistently in JavaScript and native TAR extraction/reads; reject ambiguous records, extension chains, and sparse semantics while retaining byte/count limits and guarded staging. Return TAR read traversal failures through the public promise instead of escaping the parser callback.
+- Add native-required Linux/macOS `stageFileInDirectory()` under `advanced` with retained-directory abort cleanup, private `0600` staging until publication is identity-checked, exact identity checks, explicit publication/cleanup receipts, and async disposal; share that ownership with POSIX native streaming writes so parent moves no longer strand their unpublished temps.
+- Share native writer admission and direct-child cleanup mechanisms; preserve combined POSIX coordinator operation/disposal failures with `SuppressedError` while keeping staged preparation/cleanup receipts and Windows close policy unchanged.
+- Fail closed when synchronous sidecar compromise checks hit I/O errors and invoke `onCompromised` once instead of throwing from the interval. Thanks @SebTardif.
+- Reject ZIP symlink-mode entries with a trailing slash or DOS directory bit before creating output, aligning JavaScript extraction with native link policy while preserving explicit filtering. Thanks @Yigtwxx.
+- Make the validated stripped path authoritative during JavaScript TAR extraction, fixing `ENOENT` and native path disagreement for dot or empty components, including local PAX paths, while preserving pre-strip filter inputs. Thanks @Yigtwxx.
+- Apply process-wide retry, timeout, and stale-policy defaults to synchronous file locks while preserving per-call overrides and caller-approved guarded recovery. Thanks @Yigtwxx.
+
+### Docs and Tooling
+
+- Publish native bindings as platform-filtered optional packages and load only the matching package, avoiding installation of binaries for six unrelated targets; verify root-only npm/pnpm resolution and document omitted-optionals limits and native-only recovery guidance. Thanks @RomneyDa.
+- Raise the Crabbox AWS root volume to 400 GiB to meet the runner image's snapshot minimum and avoid allocation failures before checks run.
+- Restore six missing documentation navigation entries, remove the dangling page, correct the lock-config link, and reject missing, nonexistent, or duplicate registrations before replacing site output. Thanks @Yigtwxx.
+- Fix the standalone native smoke script to use the numeric descriptor returned by `openBeneath()` for identity checks and cleanup.
+- Accept npm 11 array and npm 12 package-name-keyed pack results while validating the intended package and its file metadata.
+
+### Dependencies and maintenance
+
+- Refresh the Node and Rust dependency graphs, align development and CI on pnpm 11.24.0, and update the CodeQL, npm, and cargo-zigbuild pins while preserving the two-day dependency cooldown.
+
+## 0.5.6 - 2026-08-14
+
+### Security and Correctness
+
+- Treat asynchronous sidecar compromise-check I/O failures as a lost lock and invoke `onCompromised` once, instead of leaking an unhandled rejection from the interval.
+- Preserve replaced temporary paths during Windows cleanup when libuv reports a zero device or inode or a file index exceeds JavaScript's safe integer range, treating unknown or rounded identity as fail-closed instead of authorizing deletion.
+
+### Docs and Tooling
+
+- Set up Node before pnpm when hydrating Crabbox runners so minimal images without a preinstalled npm can prepare the workspace.
 ## 0.5.5 - 2026-08-12
 
 ### Security and Correctness

package/README.md

@@ -26,7 +26,7 @@ Full docs and reference at **[fs-safe.io](https://fs-safe.io)**.
 
 ## Contents
 
-[Why this exists](#why-this-exists) · [Not a sandbox](#not-a-sandbox) · [Install](#install) · [0.5 migration](docs/migrating-to-0.5.md) · [Python migration](#migrating-from-the-python-helper) · [Quick start](#quick-start) · [Reading](#reading) · [Subpaths](#subpaths) · [Failure semantics](#failure-semantics-in-the-name) · [Directory durability](#directory-durability) · [Atomic writes](#atomic-writes) · [External outputs](#external-outputs) · [Stores](#stores) · [Secure absolute reads](#secure-absolute-file-reads) · [Walking](#directory-walking) · [Archive extraction](#archive-extraction) · [Path scopes](#advanced-path-scopes) · [Errors](#errors) · [Safety model](#safety-model) · [Limitations](#limitations)
+[Why this exists](#why-this-exists) · [Not a sandbox](#not-a-sandbox) · [Install](#install) · [0.6 migration](docs/migrating-to-0.6.md) · [Python migration](#migrating-from-the-python-helper) · [Quick start](#quick-start) · [Reading](#reading) · [Subpaths](#subpaths) · [Failure semantics](#failure-semantics-in-the-name) · [Directory durability](#directory-durability) · [Atomic writes](#atomic-writes) · [External outputs](#external-outputs) · [Stores](#stores) · [Secure absolute reads](#secure-absolute-file-reads) · [Walking](#directory-walking) · [Archive extraction](#archive-extraction) · [Path scopes](#advanced-path-scopes) · [Errors](#errors) · [Safety model](#safety-model) · [Limitations](#limitations)
 
 ## Why this exists
 
@@ -57,10 +57,10 @@ This is a **library-level guardrail**, not OS-level isolation. It does not repla
 pnpm add @openclaw/fs-safe
 ```
 
-Node 22 or newer. Core root/path/json/temp helpers avoid framework dependencies. Archive helpers use optional `jszip` and `tar` dependencies for ZIP/TAR support; installs that omit optional dependencies can still use every non-archive subpath.
+Node 22 or newer. Core root/path/json/temp helpers avoid framework dependencies. With all optional dependencies omitted, public subpaths remain safe to import and non-archive fallback-capable operations work in `auto` or `off`. Native-only features remain unavailable, and operations needing the binding in `require` mode fail with `helper-unavailable`. JavaScript ZIP/TAR fallback also needs the optional `jszip`/`tar` codecs. See the [0.6 migration guide](docs/migrating-to-0.6.md).
 
-The package bundles prebuilt native bindings for seven supported targets. They
-supply fd-relative and atomic no-replace primitives that Node does not expose
+The package installs one prebuilt native binding for the current supported target. It
+supplies fd-relative and atomic no-replace primitives that Node does not expose
 directly. Configure the lazy loader before first use when you need a strict
 environment policy:
 
@@ -80,11 +80,11 @@ replace a writable parent between its identity check and Node's pathname
 mutation can redirect that mutation outside the root before the post-check
 reports the escape. Use `require` when hostile concurrent mutation is in scope.
 
-Equivalent env var: `FS_SAFE_NATIVE_MODE=auto|off|require`. All seven binaries
-ship inside `@openclaw/fs-safe`; there are no platform packages, postinstall
-steps, downloads, or consumer Rust builds. This makes the tarball larger than
-a per-platform package, but makes installation deterministic. On a platform
-without a bundled binary, `auto` silently retains lexical and canonical root
+Equivalent env var: `FS_SAFE_NATIVE_MODE=auto|off|require`. The seven bindings
+ship as exact-version optional packages filtered by OS, CPU, and Linux libc, so
+a normal install receives only its matching binary. There are no postinstall
+steps, runtime downloads, or consumer Rust builds. On a platform without a
+published binding, or when optional dependencies are omitted, `auto` silently retains lexical and canonical root
 checks, no-follow opens, guarded temp+rename writes, and post-write identity
 verification. See the [native
 helper policy](docs/native-helper.md) for the exact boundary and deployment
@@ -97,7 +97,7 @@ and guarded JavaScript results are best-effort. See the [security model](docs/se
 
 ## Migrating from the Python helper
 
-Version 0.5 replaces the persistent Python worker with bundled prebuilt native
+Version 0.5 replaces the persistent Python worker with prebuilt native
 bindings. The modes map directly: `configureFsSafePython({ mode: "auto" })`
 becomes `configureFsSafeNative({ mode: "auto" })`, and likewise for `off` and
 `require`. Replace `FS_SAFE_PYTHON_MODE` with `FS_SAFE_NATIVE_MODE`; remove
@@ -284,6 +284,12 @@ publication policy, creation callback, and platform contract.
 
 ## Atomic writes
 
+For preparation that must survive a parent rename until abort cleanup, use
+[`stageFileInDirectory()`](docs/staged-file.md) from `advanced`. It retains the
+original directory on Linux/macOS and requires native support for this operation.
+It offers atomic replace/no-replace publication, not expected-inode replacement
+or a crash-durability promise; application checks and coordination remain yours.
+
 `replaceFileAtomic()` writes a sibling temp file, applies its exact mode through the still-open descriptor, optionally fsyncs it, and renames it over the destination. It never follows the published destination path to set file permissions. Mode preservation, pinned-destination hardlink rejection, rename retry / copy fallback on `EPERM`, bounded original-content restoration after a torn fallback, parent-directory fsync, and a `beforeRename` hook for backup or observer flows are all opt-in. `movePathWithCopyFallback()` stages cross-device moves before commit and removes only the copied source entries, so concurrent source additions or replacements are preserved.
 
 ```ts

package/dist/advanced.d.ts

@@ -1,4 +1,5 @@
 export { createAsyncLock } from "./async-lock.js";
+export { stageFileInDirectory, type StagedFile, type StagedFileReceipt, type PublishedFileReceipt, type StagedFilePublication, type StagedFileCleanupReceipt, type StagedFileFailureDetails, } from "./staged-file.js";
 export { readFileDescriptorBounded, readFileDescriptorBoundedSync, readFileHandleBounded, } from "./bounded-read.js";
 export { assertNoUnsafeDeviceReadPath, isUnsafeDeviceReadPath, matchUnsafeDeviceReadPath, type UnsafeDeviceReadPathMatch, type UnsafeDeviceReadPathOptions, type UnsafeDeviceReadPathReason, } from "./device-path.js";
 export { assertAbsolutePathInput, canonicalPathFromExistingAncestor, ensureAbsoluteDirectory, findExistingAncestor, resolveAbsolutePathForRead, resolveAbsolutePathForWrite, type AbsolutePathSymlinkPolicy, type EnsureAbsoluteDirectoryOptions, type EnsureAbsoluteDirectoryResult, type ResolvedAbsolutePath, type ResolvedWritableAbsolutePath, } from "./absolute-path.js";
@@ -21,5 +22,5 @@ export { resolveHomeRelativePath } from "./home-dir.js";
 export { appendRegularFile, appendRegularFileSync, readRegularFile, readRegularFileSync, resolveRegularFileAppendFlags, statRegularFile, statRegularFileSync, type AppendRegularFileOptions, type RegularFileStatResult, } from "./regular-file.js";
 export { buildRandomTempFilePath, sanitizeTempFileName, type TempFile, tempFile, withTempFile, } from "./temp-target.js";
 export { writeSiblingTempFile, writeViaSiblingTempPath, type WriteSiblingTempFileOptions, type WriteSiblingTempFileResult, } from "./sibling-temp.js";
-export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, type IcaclsResetCommandOptions, type PermissionExec, type WindowsAclEntry, type WindowsAclSummary, } from "./permissions.js";
+export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, type IcaclsResetCommandOptions, type PermissionCommandFailure, type PermissionExec, type WindowsAclEntry, type WindowsAclSummary, } from "./permissions.js";
 //# sourceMappingURL=advanced.d.ts.map

package/dist/advanced.d.ts.map

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

package/dist/advanced.js

@@ -2,6 +2,7 @@
 // public subpaths; prefer root/json/store/temp/archive unless you are building a
 // higher-level primitive.
 export { createAsyncLock } from "./async-lock.js";
+export { stageFileInDirectory, } from "./staged-file.js";
 export { readFileDescriptorBounded, readFileDescriptorBoundedSync, readFileHandleBounded, } from "./bounded-read.js";
 export { assertNoUnsafeDeviceReadPath, isUnsafeDeviceReadPath, matchUnsafeDeviceReadPath, } from "./device-path.js";
 export { assertAbsolutePathInput, canonicalPathFromExistingAncestor, ensureAbsoluteDirectory, findExistingAncestor, resolveAbsolutePathForRead, resolveAbsolutePathForWrite, } from "./absolute-path.js";

package/dist/archive-crc32.d.ts

@@ -0,0 +1,2 @@
+export declare function updateCrc32(previous: number, buffer: Buffer): number;
+//# sourceMappingURL=archive-crc32.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-crc32.d.ts","sourceRoot":"","sources":["../src/archive-crc32.ts"],"names":[],"mappings":"AAQA,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAMpE"}

package/dist/archive-crc32.js

@@ -0,0 +1,14 @@
+const CRC32_TABLE = Array.from({ length: 256 }, (_, index) => {
+    let value = index;
+    for (let bit = 0; bit < 8; bit += 1) {
+        value = (value & 1) !== 0 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+    }
+    return value >>> 0;
+});
+export function updateCrc32(previous, buffer) {
+    let crc = previous ^ -1;
+    for (const byte of buffer) {
+        crc = (crc >>> 8) ^ (CRC32_TABLE[(crc ^ byte) & 0xff] ?? 0);
+    }
+    return (crc ^ -1) >>> 0;
+}

package/dist/archive-kind.js

@@ -10,8 +10,8 @@ const NATIVE_TAR_SUFFIXES = [
 ];
 function requireNativeArchiveKind(kind) {
     if (!getNativeBinding()) {
-        throw new FsSafeError("helper-unavailable", `${kind} archives require a supported bundled native binding; ` +
-            "use FS_SAFE_NATIVE_MODE=auto or require on a supported platform");
+        throw new FsSafeError("helper-unavailable", `${kind} archives require the matching optional native platform package; ` +
+            "install @openclaw/fs-safe with optional dependencies enabled on a supported platform and use FS_SAFE_NATIVE_MODE=auto or require");
     }
     return kind;
 }

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;AAuBjD,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,CAwHhB"}
+{"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"}

package/dist/archive-native.js

@@ -7,6 +7,7 @@ import { stageArchiveFileForExtraction } from "./archive-input.js";
 import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWithinLimit, createByteBudgetTracker, resolveExtractLimits, } 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";
 function policyKind(kind) {
     if (kind === "file" || kind === "directory")
         return kind;
@@ -37,6 +38,9 @@ export async function extractNativeArchive(params) {
         deadline: params.deadline,
     });
     try {
+        const physicalCount = params.kind === "zip"
+            ? await admitZipFile(stagedArchive.path, limits, params.deadline)
+            : undefined;
         const destinationRealDir = await prepareArchiveDestinationDir(params.destDir);
         await withStagedArchiveDestination({
             destinationRealDir,
@@ -47,6 +51,9 @@ export async function extractNativeArchive(params) {
                     .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");
+                }
                 const strip = Math.max(0, Math.floor(params.stripComponents ?? 0));
                 const budget = createByteBudgetTracker(limits);
                 const trackOutputPath = createArchiveOutputPathTracker();

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;AAqMzE,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,CAmFjB"}
+{"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"}

package/dist/archive-read.js

@@ -15,6 +15,8 @@ import { createZipIntegrityTransform, normalizeZipIntegrityError, } from "./arch
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { getNativeBinding } from "./native.js";
+import { admitZipBuffer } from "./archive-zip-admission.js";
+import { resolveExtractLimits } from "./archive-limits.js";
 import { tempFile } from "./temp-target.js";
 const ZIP_UNIX_FILE_TYPE_MASK = 0o170000;
 const ZIP_UNIX_SYMLINK_TYPE = 0o120000;
@@ -127,7 +129,15 @@ async function readTarEntry(archivePath, entryPath, maxBytes) {
             maxMetaEntrySize: DEFAULT_MAX_META_ENTRY_BYTES,
             onReadEntry(entry) {
                 const info = readTarEntryInfo(entry);
-                validateArchiveEntryPath(info.path, { escapeLabel: "archive root" });
+                try {
+                    validateArchiveEntryPath(info.path, { escapeLabel: "archive root" });
+                }
+                catch (error) {
+                    // Throws escaping node-tar's callback do not reject its promise.
+                    entryError ??= error instanceof Error ? error : new Error(String(error));
+                    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)}`);
@@ -175,12 +185,18 @@ export async function readArchiveEntry(archivePath, entryPath, options) {
     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 manifest = await native.inspectArchiveNative(staged.path, kind, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_META_ENTRY_BYTES, DEFAULT_MAX_ARCHIVE_BYTES_ZIP, 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" });
@@ -202,9 +218,11 @@ export async function readArchiveEntry(archivePath, entryPath, options) {
                 return await native.readArchiveEntryNative(staged.path, kind, rawEntryPath, options.maxBytes, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_META_ENTRY_BYTES, signal);
             }
             catch (error) {
-                if (error instanceof Error &&
-                    error.message.includes(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT)) {
-                    throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
+                if (error instanceof Error) {
+                    for (const code of Object.values(ARCHIVE_LIMIT_ERROR_CODE)) {
+                        if (error.message.includes(code))
+                            throw new ArchiveLimitError(code);
+                    }
                 }
                 if (error instanceof Error && isArchiveFormatErrorMessage(error.message)) {
                     throw new ArchiveFormatError(error.message, { cause: error });
@@ -213,7 +231,8 @@ export async function readArchiveEntry(archivePath, entryPath, options) {
             }
         }
         if (kind === "tar-zstd" || kind === "tar-bzip2") {
-            throw new FsSafeError("helper-unavailable", `${kind} archives require a supported bundled native binding`);
+            throw new FsSafeError("helper-unavailable", `${kind} archives require the matching optional native platform package; ` +
+                "install @openclaw/fs-safe with optional dependencies enabled on a supported platform and use FS_SAFE_NATIVE_MODE=auto or require");
         }
         return kind === "zip"
             ? await readZipEntry(staged.buffer, requestedEntry, options.maxBytes)

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

@@ -1 +1 @@
-{"version":3,"file":"archive-tar-meta.d.ts","sourceRoot":"","sources":["../src/archive-tar-meta.ts"],"names":[],"mappings":"AAqJA,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB"}
+{"version":3,"file":"archive-tar-meta.d.ts","sourceRoot":"","sources":["../src/archive-tar-meta.ts"],"names":[],"mappings":"AA8LA,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB"}

package/dist/archive-tar-meta.js

@@ -4,11 +4,14 @@ import { pipeline } from "node:stream/promises";
 import { createGunzip } from "node:zlib";
 import { ArchiveFormatError } from "./archive-errors.js";
 import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError } from "./archive-limits.js";
+import { parseLocalPax, paxMemberSize } from "./archive-tar-pax.js";
 class TarMetadataMeter extends Transform {
     maxMetaEntryBytes;
     block = Buffer.alloc(512);
     blockLength = 0;
     state = { kind: "header" };
+    pendingPax;
+    pendingGnu = false;
     constructor(maxMetaEntryBytes) {
         super();
         this.maxMetaEntryBytes = maxMetaEntryBytes;
@@ -32,7 +35,10 @@ class TarMetadataMeter extends Transform {
             return Number(value);
         }
         const zero = field.indexOf(0);
-        const text = field.subarray(0, zero < 0 ? field.length : zero).toString("ascii").trim();
+        const bytes = field.subarray(0, zero < 0 ? field.length : zero);
+        if (bytes.some((byte) => byte > 0x7f))
+            throw this.invalid("size is not ASCII octal");
+        const text = bytes.toString("ascii").trim();
         if (!text || !/^[0-7]+$/.test(text))
             throw this.invalid("size is not valid octal");
         const value = Number.parseInt(text, 8);
@@ -42,6 +48,9 @@ class TarMetadataMeter extends Transform {
     }
     finishHeader() {
         if (this.block.every((byte) => byte === 0)) {
+            if (this.pendingPax)
+                throw this.invalid("dangling PAX metadata");
+            this.pendingGnu = false;
             this.blockLength = 0;
             this.state = { kind: "header" };
             return;
@@ -54,13 +63,37 @@ class TarMetadataMeter extends Transform {
         if (this.block[156] !== 0x35 && name.at(-1) === 0x2f) {
             throw this.invalid("non-directory entry path ends with a separator");
         }
-        const size = this.parseSize();
+        let size = this.parseSize();
         const type = this.block[156];
-        if ([0x78, 0x67, 0x4c, 0x4b, 0x58].includes(type ?? -1) && size > this.maxMetaEntryBytes) {
+        if ([0x78, 0x67, 0x4c, 0x4b, 0x58, 0x4e].includes(type) && size > this.maxMetaEntryBytes) {
             throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.META_ENTRY_SIZE_EXCEEDS_LIMIT);
         }
-        if (type === 0x78 || type === 0x67 || type === 0x58) {
-            throw this.invalid("PAX metadata is unmeterable without interpreting content");
+        if (type === 0x67 || type === 0x58 || type === 0x4e) {
+            throw this.invalid("global/old PAX and old GNU metadata are not supported");
+        }
+        if (type === 0x78) {
+            if (this.pendingPax || this.pendingGnu || size === 0)
+                throw this.invalid("empty, repeated or mixed PAX metadata");
+            const magic = this.block.subarray(257, 265).toString("latin1");
+            if (magic !== "ustar\0" + "00" && magic !== "ustar  \0")
+                throw this.invalid("unrecognized PAX header format");
+            const padded = Math.ceil(size / 512) * 512;
+            if (!Number.isSafeInteger(padded))
+                throw this.invalid("entry padding exceeds the safe integer range");
+            this.state = { kind: "pax", body: Buffer.alloc(size), used: 0, padding: padded - size };
+            this.blockLength = 0;
+            return;
+        }
+        // Sparse headers retain their metadata-limit-before-format-error ordering.
+        if (this.pendingPax && type !== 0x53) {
+            size = paxMemberSize(this.pendingPax, type, size, this.block);
+            this.pendingPax = undefined;
+        }
+        if (type === 0x4c || type === 0x4b) {
+            this.pendingGnu = true;
+        }
+        else {
+            this.pendingGnu = false;
         }
         const padded = Math.ceil(size / 512) * 512;
         if (!Number.isSafeInteger(padded))
@@ -98,6 +131,18 @@ class TarMetadataMeter extends Transform {
     meter(chunk) {
         let offset = 0;
         while (offset < chunk.length) {
+            if (this.state.kind === "pax") {
+                const state = this.state;
+                const take = Math.min(state.body.length - state.used, chunk.length - offset);
+                chunk.copy(state.body, state.used, offset, offset + take);
+                state.used += take;
+                offset += take;
+                if (state.used === state.body.length) {
+                    this.pendingPax = parseLocalPax(state.body);
+                    this.state = state.padding === 0 ? { kind: "header" } : { kind: "data", remaining: state.padding };
+                }
+                continue;
+            }
             if (this.state.kind === "data") {
                 const take = Math.min(this.state.remaining, chunk.length - offset);
                 offset += take;
@@ -127,7 +172,9 @@ class TarMetadataMeter extends Transform {
         }
     }
     _flush(callback) {
-        if (this.state.kind === "header" && this.blockLength === 0)
+        if (this.pendingPax)
+            callback(this.invalid("dangling PAX metadata"));
+        else if (this.state.kind === "header" && this.blockLength === 0)
             callback();
         else
             callback(this.invalid(this.state.kind === "header" ? "truncated TAR header" : "truncated TAR entry"));

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

@@ -0,0 +1,8 @@
+export type LocalPax = {
+    path?: string;
+    linkpath?: string;
+    size?: number;
+};
+export declare function parseLocalPax(body: Buffer): LocalPax;
+export declare function paxMemberSize(pax: LocalPax, type: number, rawSize: number, header: Buffer): number;
+//# sourceMappingURL=archive-tar-pax.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-tar-pax.d.ts","sourceRoot":"","sources":["../src/archive-tar-pax.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,QAAQ,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAqB3E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAwCpD;AAQD,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAclG"}

package/dist/archive-tar-pax.js

@@ -0,0 +1,100 @@
+import { ArchiveFormatError } from "./archive-errors.js";
+function invalid() {
+    throw new ArchiveFormatError("invalid TAR header: unsupported or malformed PAX metadata");
+}
+function decimal(bytes) {
+    const text = bytes.toString("latin1");
+    if (!/^(0|[1-9][0-9]*)$/.test(text))
+        invalid();
+    const value = Number(text);
+    if (!Number.isSafeInteger(value))
+        invalid();
+    return value;
+}
+function ascii(bytes) {
+    if (bytes.length === 0 || bytes.some((byte) => byte < 0x20 || byte > 0x7e))
+        invalid();
+    return bytes.toString("ascii");
+}
+// Keep this grammar aligned with native/src/tar_pax.rs. Downstream parsers
+// disagree on duplicates, coercions and UTF-8 chunk boundaries.
+export function parseLocalPax(body) {
+    if (body.length === 0)
+        invalid();
+    const result = {};
+    const keys = new Set();
+    let offset = 0;
+    while (offset < body.length) {
+        const space = body.indexOf(0x20, offset);
+        if (space < 0)
+            invalid();
+        const length = decimal(body.subarray(offset, space));
+        if (length > body.length - offset || length <= space - offset + 3)
+            invalid();
+        const end = offset + length;
+        if (body[end - 1] !== 0x0a)
+            invalid();
+        const record = body.subarray(space + 1, end - 1);
+        if (record.includes(0x0a))
+            invalid();
+        const equals = record.indexOf(0x3d);
+        if (equals <= 0)
+            invalid();
+        const key = ascii(record.subarray(0, equals));
+        if (!/^[A-Za-z0-9_.-]+$/.test(key) || keys.has(key))
+            invalid();
+        keys.add(key);
+        const value = record.subarray(equals + 1);
+        if (/^(LIBARCHIVE|SCHILY)\.xattr\..+$/.test(key)) {
+            // Inert bytes, never restored. Newlines would corrupt Rust's subsequent
+            // record lookup; NUL and non-UTF8 bytes in these values are harmless.
+        }
+        else if (key === "path" || key === "linkpath") {
+            result[key] = ascii(value);
+        }
+        else if (key === "size") {
+            result.size = decimal(value);
+        }
+        else if (key === "uid" || key === "gid") {
+            decimal(value);
+        }
+        else if (key === "uname" || key === "gname") {
+            ascii(value);
+        }
+        else if (key === "mtime" || key === "atime" || key === "ctime") {
+            const text = ascii(value);
+            if (!/^-?(0|[1-9][0-9]*)(\.[0-9]+)?$/.test(text) || Math.abs(Number(text)) > 8_640_000_000_000)
+                invalid();
+        }
+        else {
+            invalid();
+        }
+        offset = end;
+    }
+    return result;
+}
+function rawText(field) {
+    const zero = field.indexOf(0);
+    const value = field.subarray(0, zero < 0 ? field.length : zero);
+    return value.length === 0 ? "" : ascii(value);
+}
+export function paxMemberSize(pax, type, rawSize, header) {
+    if (![0, 0x30, 0x31, 0x32, 0x35, 0x37].includes(type))
+        invalid();
+    const rawName = rawText(header.subarray(0, 100));
+    const rawLink = rawText(header.subarray(157, 257));
+    if (header.subarray(257, 265).equals(Buffer.from("ustar\0" + "00"))) {
+        rawText(header.subarray(345, 500));
+    }
+    const isLink = type === 0x31 || type === 0x32;
+    if (isLink !== (rawLink.length > 0))
+        invalid();
+    const size = pax.size ?? rawSize;
+    if ([0x31, 0x32, 0x35].includes(type) && (rawSize !== 0 || size !== 0))
+        invalid();
+    if (type !== 0x35 && (pax.path?.endsWith("/") || pax.path?.endsWith("\\") || rawName.endsWith("\\")))
+        invalid();
+    if (pax.linkpath !== undefined && !isLink)
+        invalid();
+    return size;
+}

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

@@ -25,6 +25,7 @@ export type TarModule = {
         preservePaths: false;
         noChmod: true;
         preserveOwner: false;
+        noMtime: true;
         strict: true;
         maxMetaEntrySize: number;
         filter?(this: TarParser, entryPath: string, entry: unknown): boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"archive-tar-runtime.d.ts","sourceRoot":"","sources":["../src/archive-tar-runtime.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,IAAI,IAAI,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,GAAG;IAC9C,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC1B,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,SAAS,CAAC;IAChF,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,SAAS,CAAC;IACzE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,SAAS,CAAC;IACnE,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,SAAS,CAAC;IAChE,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,SAAS,CAAC;CACnD,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,MAAM,EAAE,KAAK,OAAO,EAAE;QAAE,MAAM,EAAE,IAAI,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,KAAK,SAAS,CAAC;IAC/E,CAAC,CAAC,OAAO,EAAE;QACT,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,aAAa,EAAE,KAAK,CAAC;QACrB,OAAO,EAAE,IAAI,CAAC;QACd,aAAa,EAAE,KAAK,CAAC;QACrB,MAAM,EAAE,IAAI,CAAC;QACb,gBAAgB,EAAE,MAAM,CAAC;QACzB,MAAM,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;QACrE,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;KAClD,GAAG,SAAS,CAAC;IACd,CAAC,CAAC,OAAO,EAAE;QACT,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,IAAI,CAAC;QACb,gBAAgB,EAAE,MAAM,CAAC;QACzB,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG;YAAE,MAAM,IAAI,IAAI,CAAA;SAAE,GAAG,IAAI,CAAC;KACvE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtB,CAAC;AAEF,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,SAAS,CAAC,CAS5D;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAS/D"}
+{"version":3,"file":"archive-tar-runtime.d.ts","sourceRoot":"","sources":["../src/archive-tar-runtime.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,IAAI,IAAI,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,GAAG;IAC9C,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC1B,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,SAAS,CAAC;IAChF,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,SAAS,CAAC;IACzE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,SAAS,CAAC;IACnE,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,SAAS,CAAC;IAChE,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,SAAS,CAAC;CACnD,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,MAAM,EAAE,KAAK,OAAO,EAAE;QAAE,MAAM,EAAE,IAAI,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,KAAK,SAAS,CAAC;IAC/E,CAAC,CAAC,OAAO,EAAE;QACT,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,aAAa,EAAE,KAAK,CAAC;QACrB,OAAO,EAAE,IAAI,CAAC;QACd,aAAa,EAAE,KAAK,CAAC;QACrB,OAAO,EAAE,IAAI,CAAC;QACd,MAAM,EAAE,IAAI,CAAC;QACb,gBAAgB,EAAE,MAAM,CAAC;QACzB,MAAM,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;QACrE,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;KAClD,GAAG,SAAS,CAAC;IACd,CAAC,CAAC,OAAO,EAAE;QACT,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,IAAI,CAAC;QACb,gBAAgB,EAAE,MAAM,CAAC;QACzB,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG;YAAE,MAAM,IAAI,IAAI,CAAA;SAAE,GAAG,IAAI,CAAC;KACvE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtB,CAAC;AAEF,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,SAAS,CAAC,CAS5D;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAS/D"}

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

@@ -0,0 +1,7 @@
+import type { ExtractionDeadline } from "./archive-deadline.js";
+import { type ResolvedArchiveExtractLimits } from "./archive-limits.js";
+/** Admit physical records before a decoder can normalize or collapse names. */
+export declare function admitZipBuffer(input: Uint8Array, limits: ResolvedArchiveExtractLimits): number;
+/** The extraction input is already private and staged; read only bounded metadata. */
+export declare function admitZipFile(archivePath: string, limits: ResolvedArchiveExtractLimits, deadline: ExtractionDeadline): Promise<number>;
+//# sourceMappingURL=archive-zip-admission.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-zip-admission.d.ts","sourceRoot":"","sources":["../src/archive-zip-admission.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAA+C,KAAK,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAYrH,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,4BAA4B,GAAG,MAAM,CAU9F;AAED,sFAAsF;AACtF,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,4BAA4B,EAAE,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+B3I"}

package/dist/archive-zip-admission.js

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError } from "./archive-limits.js";
+import { openRootFile } from "./root-file.js";
+import { scanZipDirectory } from "./archive-zip-directory.js";
+import { zipFormat } from "./archive-zip-names.js";
+function checkSize(size, limits) {
+    if (size > limits.maxArchiveBytes) {
+        throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT);
+    }
+    if (!Number.isSafeInteger(size) || size < 0)
+        zipFormat("invalid archive size");
+}
+/** Admit physical records before a decoder can normalize or collapse names. */
+export function admitZipBuffer(input, limits) {
+    checkSize(input.byteLength, limits);
+    const buffer = Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+    const scan = scanZipDirectory(buffer.length, limits);
+    let step = scan.next();
+    while (!step.done) {
+        const { offset, length } = step.value;
+        step = scan.next(buffer.subarray(offset, offset + length));
+    }
+    return step.value;
+}
+/** The extraction input is already private and staged; read only bounded metadata. */
+export async function admitZipFile(archivePath, limits, deadline) {
+    deadline.check();
+    const opened = await openRootFile({
+        absolutePath: archivePath, rootPath: path.dirname(archivePath),
+        boundaryLabel: "staged ZIP archive", rejectSymlinks: true, rejectHardlinks: true,
+    });
+    if (!opened.ok)
+        throw opened.error ?? new Error("cannot open staged ZIP archive");
+    try {
+        checkSize(opened.stat.size, limits);
+        const scan = scanZipDirectory(opened.stat.size, limits);
+        let step = scan.next();
+        while (!step.done) {
+            const { offset, length } = step.value;
+            const bytes = Buffer.alloc(length);
+            let received = 0;
+            while (received < length) {
+                deadline.check();
+                const count = await new Promise((resolve, reject) => {
+                    fs.read(opened.fd, bytes, received, length - received, offset + received, (error, count) => error ? reject(error) : resolve(count));
+                });
+                deadline.check();
+                if (!count)
+                    zipFormat("truncated staged record");
+                received += count;
+            }
+            step = scan.next(bytes);
+        }
+        return step.value;
+    }
+    finally {
+        fs.closeSync(opened.fd);
+    }
+}