@openclaw/fs-safe 0.8.1 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.8.2 - 2026-09-05
+
+**Highlights:** TAR/gzip extraction now shares one parser across native and fallback modes, improving compatibility with system-tar output while keeping admission and publication guarded.
+
+- Reject reserved archive device names and ignored-space aliases on Windows while preserving ordinary POSIX members, and guard secret reads with the documented `device-path` rejection. Thanks @SebTardif.
+- Unify native and guarded JavaScript TAR admission on one Rust core, bundle its WASM build, and accept strict UTF-8/newline PAX paths without a runtime `tar` dependency; retain bounded framing, raw-field validation, and guarded publication.
+- Accept bounded all-zero gzip container padding from system-tar stdout after validated member trailers, and reject nonzero data hidden after padding on both native and guarded JavaScript TAR routes.
+- Fix `replaceFileAtomic({ dirMode })` rejecting a raw `fs.stat` mode: directory modes are masked to permission bits (`0o7777`) before application and verification, matching chmod semantics; 0.8.0 regressed this input tolerance with `directory final mode could not be verified`.
+- Standardize malformed TAR mode fields on the native zero fallback while preserving ordinary octal, absent, zero, and safe GNU binary modes.
+- Refresh the native binding build tool to `@napi-rs/cli` 3.9.0 and the test/coverage toolchain to Vitest 5.0.0. Thanks @dependabot.
+
 ## 0.8.1 - 2026-09-04
 
 - Add `retainOnExit` to sidecar lock acquisition so deliberately retained ownership records (for example fail-closed build locks) survive natural process exit; default process-exit release behavior is unchanged.

package/README.md

@@ -57,7 +57,7 @@ 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. 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).
+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`. TAR/gzip fallback uses the bundled WASM build of the same Rust parser as native and works with optional dependencies omitted. ZIP fallback still needs optional `jszip`. See the [0.6 migration guide](docs/migrating-to-0.6.md).
 
 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

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;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"}
+{"version":3,"file":"archive-entry.d.ts","sourceRoot":"","sources":["../src/archive-entry.ts"],"names":[],"mappings":"AAMA,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,CAoEN;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

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { ArchiveSecurityError } from "./archive-errors.js";
+import { isWindowsReservedDeviceName } from "./device-path.js";
 import { formatErrorDetail } from "./error-detail.js";
 import { resolveSafeBaseDir } from "./path.js";
 export function isWindowsDrivePath(value) {
@@ -25,6 +26,10 @@ export function validateArchiveEntryPath(entryPath, params) {
         slashNormalized.split("/").some((segment) => segment.includes(":"))) {
         throw new ArchiveSecurityError("entry-path", `archive entry uses a Windows alternate data stream path: ${formatErrorDetail(entryPath)}`);
     }
+    if (process.platform === "win32" &&
+        slashNormalized.split("/").some((segment) => isWindowsReservedDeviceName(segment))) {
+        throw new ArchiveSecurityError("entry-path", `archive entry uses a reserved device path: ${formatErrorDetail(entryPath)}`);
+    }
     const normalized = path.posix.normalize(slashNormalized);
     if (normalized.split("/").some((segment) => Math.max(Buffer.byteLength(segment.normalize("NFC")), Buffer.byteLength(segment.normalize("NFD"))) > 255)) {
         throw new ArchiveSecurityError("entry-path", `archive entry has an overlong path component: ${formatErrorDetail(entryPath)}`);

package/dist/archive-gzip-tail.d.ts

@@ -0,0 +1,18 @@
+import { Writable } from "node:stream";
+import type { Gunzip } from "node:zlib";
+/** Track physical input, not the sum of bytes consumed across separate writes:
+ * gunzip can resume on a later chunk after leaving an earlier padding gap. */
+export declare class GzipInput extends Writable {
+    private readonly decoder;
+    private position;
+    private firstUnused;
+    constructor(decoder: Gunzip);
+    get tailOffset(): number;
+    _write(chunk: Buffer, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
+    _final(callback: (error?: Error | null) => void): void;
+    _destroy(error: Error | null, callback: (error: Error | null) => void): void;
+}
+/** Check the immutable staged suffix from the first unused physical byte,
+ * including later chunks the decoder may have consumed, before returning. */
+export declare function validateGzipContainerTail(filePath: string, consumed: number, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=archive-gzip-tail.d.ts.map

package/dist/archive-gzip-tail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-gzip-tail.d.ts","sourceRoot":"","sources":["../src/archive-gzip-tail.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGxC;8EAC8E;AAC9E,qBAAa,SAAU,SAAQ,QAAQ;IAIzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,WAAW,CAAqB;IAExC,YAA6B,OAAO,EAAE,MAAM,EAE3C;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAEQ,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAcxG;IAEQ,MAAM,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAE9D;IAEQ,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAGpF;CACF;AAED;6EAC6E;AAC7E,wBAAsB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBvH"}

package/dist/archive-gzip-tail.js

@@ -0,0 +1,74 @@
+import fs from "node:fs/promises";
+import { Writable } from "node:stream";
+import { ArchiveFormatError } from "./archive-errors.js";
+/** Track physical input, not the sum of bytes consumed across separate writes:
+ * gunzip can resume on a later chunk after leaving an earlier padding gap. */
+export class GzipInput extends Writable {
+    decoder;
+    position = 0;
+    firstUnused;
+    constructor(decoder) {
+        super({ highWaterMark: 65536 });
+        this.decoder = decoder;
+    }
+    get tailOffset() {
+        return this.firstUnused ?? this.position;
+    }
+    _write(chunk, _encoding, callback) {
+        const before = this.decoder.bytesWritten;
+        this.decoder.write(chunk, (error) => {
+            if (error) {
+                callback(error);
+                return;
+            }
+            const used = this.decoder.bytesWritten - before;
+            if (!Number.isSafeInteger(used) || used < 0 || used > chunk.length ||
+                !Number.isSafeInteger(this.position + chunk.length)) {
+                callback(new ArchiveFormatError("invalid gzip consumed-input boundary"));
+                return;
+            }
+            if (used < chunk.length)
+                this.firstUnused ??= this.position + used;
+            this.position += chunk.length;
+            callback();
+        });
+    }
+    _final(callback) {
+        this.decoder.end(callback);
+    }
+    _destroy(error, callback) {
+        if (error || !this.writableFinished)
+            this.decoder.destroy(error ?? undefined);
+        callback(error);
+    }
+}
+/** Check the immutable staged suffix from the first unused physical byte,
+ * including later chunks the decoder may have consumed, before returning. */
+export async function validateGzipContainerTail(filePath, consumed, signal) {
+    signal?.throwIfAborted();
+    const handle = await fs.open(filePath, "r");
+    try {
+        const { size } = await handle.stat();
+        if (!Number.isSafeInteger(consumed) || consumed <= 0 || consumed > size) {
+            throw new ArchiveFormatError("invalid gzip consumed-input boundary");
+        }
+        if (consumed === size)
+            return;
+        const buffer = Buffer.allocUnsafe(65536);
+        let position = consumed;
+        while (position < size) {
+            signal?.throwIfAborted();
+            const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, size - position), position);
+            signal?.throwIfAborted();
+            if (bytesRead === 0)
+                throw new ArchiveFormatError("truncated gzip container padding");
+            if (buffer.subarray(0, bytesRead).some((byte) => byte !== 0)) {
+                throw new ArchiveFormatError("nonzero gzip container padding");
+            }
+            position += bytesRead;
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}

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;AAiOzE,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;AAkLzE,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

@@ -5,10 +5,8 @@ import { ArchiveFormatError, ArchiveSecurityError, isArchiveFormatErrorMessage,
 import { formatErrorDetail } from "./error-detail.js";
 import { stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
 import { resolveArchiveKind } from "./archive-kind.js";
-import { DEFAULT_MAX_ARCHIVE_BYTES_ZIP, DEFAULT_MAX_META_ENTRY_BYTES, ArchiveLimitError, ARCHIVE_LIMIT_ERROR_CODE, } from "./archive-limits.js";
-import { readTarEntryInfo } from "./archive-tar.js";
-import { preflightTarMetadata } from "./archive-tar-meta.js";
-import { importOptionalTar, NODE_TAR_RATIO_DISABLED, normalizeTarParserError } from "./archive-tar-runtime.js";
+import { DEFAULT_MAX_ARCHIVE_BYTES_ZIP, ArchiveLimitError, ARCHIVE_LIMIT_ERROR_CODE, } from "./archive-limits.js";
+import { inspectTar, replayTar } from "./archive-tar-stream.js";
 import { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
 import { createZipIntegrityTransform, normalizeZipIntegrityError, } from "./archive-zip-integrity.js";
 import { FsSafeError } from "./errors.js";
@@ -135,70 +133,30 @@ async function readZipEntry(buffer, entryPath, maxBytes) {
     return await readStreamBounded(stream.pipe(integrity), maxBytes);
 }
 async function readTarEntry(archivePath, entryPath, maxBytes) {
-    const tar = await importOptionalTar();
     const seenPaths = new Set();
-    await preflightTarMetadata({
-        archivePath,
-        limits: resolveTarMeterLimits(),
-        onMember(info) {
+    let selected;
+    const limits = resolveTarMeterLimits();
+    await inspectTar({ archivePath, limits, onMember(info) {
             const normalized = canonicalEntryPath(info.path);
             if (seenPaths.has(normalized)) {
                 throw new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(normalized)}`);
             }
             seenPaths.add(normalized);
-            if (normalized === entryPath && !["File", "OldFile", "ContiguousFile"].includes(info.type)) {
-                throw new Error(`archive entry is not a file: ${formatErrorDetail(entryPath)}`);
-            }
-        },
-    });
-    let matched;
-    let entryError;
-    try {
-        await tar.t({
-            file: archivePath,
-            strict: true,
-            maxMetaEntrySize: DEFAULT_MAX_META_ENTRY_BYTES,
-            maxDecompressionRatio: NODE_TAR_RATIO_DISABLED,
-            onReadEntry(entry) {
-                const info = readTarEntryInfo(entry);
-                let normalized;
-                try {
-                    normalized = canonicalEntryPath(info.path);
-                }
-                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;
-                }
-                if (normalized !== entryPath) {
-                    entry.resume();
-                    return;
-                }
-                if (info.type !== "File" && info.type !== "OldFile" && info.type !== "ContiguousFile") {
-                    entryError ??= new Error(`archive entry is not a file: ${formatErrorDetail(entryPath)}`);
-                    entry.resume();
-                    return;
-                }
-                if (info.size > maxBytes) {
-                    entryError ??= new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
-                    entry.resume();
-                    return;
-                }
-                matched = readStreamBounded(entry, maxBytes);
-            },
-        });
-    }
-    catch (error) {
-        throw normalizeTarParserError(error);
-    }
-    if (entryError) {
-        throw entryError;
-    }
-    if (!matched) {
+            if (normalized === entryPath)
+                selected = info;
+        } });
+    if (!selected)
         throw new Error(`archive entry not found: ${formatErrorDetail(entryPath)}`);
+    if (!["File", "OldFile", "ContiguousFile"].includes(selected.type)) {
+        throw new Error(`archive entry is not a file: ${formatErrorDetail(entryPath)}`);
     }
-    return await matched;
+    if (selected.size > maxBytes)
+        throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
+    let result;
+    await replayTar({ archivePath, limits, members: [selected], async consume(_member, payload) {
+            result = await readStreamBounded(payload, maxBytes);
+        } });
+    return result;
 }
 export async function readArchiveEntry(archivePath, entryPath, options) {
     if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0) {

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

@@ -0,0 +1,11 @@
+import { type ExtractionDeadline } from "./archive-deadline.js";
+import type { ResolvedArchiveExtractLimits, TarMeterLimits } from "./archive-limits.js";
+import type { ExtractArchiveOptions } from "./archive-options.js";
+export declare function extractWasmTar(params: {
+    archivePath: string;
+    options: ExtractArchiveOptions;
+    limits: ResolvedArchiveExtractLimits;
+    tarLimits: TarMeterLimits;
+    deadline: ExtractionDeadline;
+}): Promise<void>;
+//# sourceMappingURL=archive-tar-extract.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-tar-extract.d.ts","sourceRoot":"","sources":["../src/archive-tar-extract.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,4BAA4B,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAExF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAQlE,wBAAsB,cAAc,CAAC,MAAM,EAAE;IAC3C,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,qBAAqB,CAAC;IAAC,MAAM,EAAE,4BAA4B,CAAC;IAC1F,SAAS,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,kBAAkB,CAAC;CACzD,GAAG,OAAO,CAAC,IAAI,CAAC,CAqChB"}

package/dist/archive-tar-extract.js

@@ -0,0 +1,49 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { stripArchivePath } from "./archive-entry.js";
+import {} from "./archive-deadline.js";
+import { mergePlannedArchiveIntoDestination } from "./archive-merge.js";
+import { resolveArchiveEntryMode } from "./archive-policy.js";
+import { prepareArchiveDestinationDir, preparePrivateArchiveOutputPath, withStagedArchiveDestination } from "./archive-staging.js";
+import { createTarEntryPreflightChecker } from "./archive-tar.js";
+import { inspectTar, replayTar } from "./archive-tar-stream.js";
+import { runPinnedWriteHelper } from "./pinned-write.js";
+export async function extractWasmTar(params) {
+    const { options, deadline, tarLimits } = params;
+    const manifest = [];
+    await inspectTar({ archivePath: params.archivePath, limits: tarLimits, signal: deadline.signal,
+        onMember: (entry) => { manifest.push(entry); } });
+    deadline.check();
+    const destinationRealDir = await prepareArchiveDestinationDir(options.destDir);
+    await withStagedArchiveDestination({ destinationRealDir, run: async (stagingPath) => {
+            const stagingDir = await fs.realpath(stagingPath);
+            const check = createTarEntryPreflightChecker({ rootDir: destinationRealDir,
+                stripComponents: options.stripComponents, limits: params.limits,
+                entryFilter: options.entryFilter, onFiltered: options.onFiltered });
+            const strip = Math.max(0, Math.floor(options.stripComponents ?? 0));
+            const accepted = manifest.filter((entry) => { deadline.check(); return check(entry); }).map((entry) => {
+                const kind = entry.type === "Directory" || entry.type === "GNUDumpDir" ? "directory" : "file";
+                return { ...entry, path: stripArchivePath(entry.path, strip), kind,
+                    mode: resolveArchiveEntryMode({ kind, archivedMode: entry.mode, policy: options.entryModes }) };
+            });
+            await replayTar({ archivePath: params.archivePath, limits: tarLimits, signal: deadline.signal, members: accepted,
+                async consume(member, payload) {
+                    deadline.check();
+                    await preparePrivateArchiveOutputPath({ destinationDir: stagingDir, destinationRealDir: stagingDir,
+                        relPath: member.path, outPath: path.join(stagingDir, member.path), originalPath: member.path,
+                        isDirectory: member.kind === "directory", deadline });
+                    if (member.kind === "file") {
+                        await runPinnedWriteHelper({ rootPath: stagingDir, relativeParentPath: path.posix.dirname(member.path),
+                            basename: path.posix.basename(member.path), mkdir: false, mode: 0o600, overwrite: false,
+                            maxBytes: member.size, input: { kind: "stream", stream: Readable.from(payload) } });
+                    }
+                    deadline.check();
+                },
+            });
+            deadline.check();
+            await mergePlannedArchiveIntoDestination({ entries: accepted, sourceDir: stagingDir,
+                destinationDir: options.destDir, destinationRealDir, deadline });
+            deadline.check();
+        } });
+}

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

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

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

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

package/dist/archive-tar-stream.js

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import { Writable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGunzip } from "node:zlib";
+import { GzipInput, validateGzipContainerTail } from "./archive-gzip-tail.js";
+import { ArchiveFormatError } from "./archive-errors.js";
+import { TarParserStream } from "./archive-tar-wasm.js";
+async function gzipFile(filePath) {
+    const handle = await fs.promises.open(filePath, "r");
+    try {
+        const magic = Buffer.alloc(2);
+        const { bytesRead } = await handle.read(magic, 0, 2, 0);
+        return bytesRead === 2 && magic[0] === 31 && magic[1] === 139;
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function withTarStream(params, consume) {
+    const gzip = await gzipFile(params.archivePath);
+    const parser = new TarParserStream(params.limits, params.onMember);
+    const input = fs.createReadStream(params.archivePath, { highWaterMark: 65536 });
+    const decoder = gzip ? createGunzip() : undefined;
+    const gzipInput = decoder ? new GzipInput(decoder) : undefined;
+    const destroy = (error) => {
+        input.destroy(error);
+        gzipInput?.destroy(error);
+        decoder?.destroy(error);
+        parser.destroy(error);
+    };
+    const pumps = decoder && gzipInput
+        ? [pipeline(decoder, parser, { signal: params.signal }), pipeline(input, gzipInput, { signal: params.signal })]
+        : [pipeline(input, parser, { signal: params.signal })];
+    // Either pump tears down both routes; join every pump even after the first failure.
+    const settled = Promise.all(pumps.map((pump) => pump.then(() => undefined, (cause) => {
+        const error = cause instanceof Error ? cause : new Error(String(cause));
+        destroy(error);
+        return error;
+    }))).then((errors) => errors.find((error) => error !== undefined));
+    try {
+        const result = await consume(parser);
+        const error = await settled;
+        if (error)
+            throw error;
+        if (gzipInput)
+            await validateGzipContainerTail(params.archivePath, gzipInput.tailOffset, params.signal);
+        return result;
+    }
+    finally {
+        destroy();
+        await settled;
+    }
+}
+export async function inspectTar(params) {
+    await withTarStream(params, async (parser) => {
+        await pipeline(parser, new Writable({ write(_chunk, _encoding, callback) { callback(); } }));
+    });
+}
+/** Replay in physical order, retaining at most one decoded chunk. Every range
+ * comes from complete admission of the immutable staged input. */
+export async function replayTar(params) {
+    await withTarStream(params, async (parser) => {
+        const iterator = parser[Symbol.asyncIterator]();
+        let chunk = Buffer.alloc(0);
+        let position = 0;
+        async function* take(length) {
+            while (length > 0) {
+                if (!chunk.length) {
+                    const next = await iterator.next();
+                    if (next.done)
+                        throw new ArchiveFormatError("truncated admitted TAR range");
+                    chunk = next.value;
+                }
+                const count = Math.min(length, chunk.length);
+                const bytes = chunk.subarray(0, count);
+                chunk = chunk.subarray(count);
+                position += count;
+                length -= count;
+                yield bytes;
+            }
+        }
+        for (const member of params.members) {
+            if (member.offset < position)
+                throw new ArchiveFormatError("invalid admitted TAR range order");
+            for await (const _ of take(member.offset - position)) { /* Skip admitted gaps. */ }
+            const payload = take(member.size);
+            await params.consume(member, payload);
+            for await (const _ of payload) { /* Directories may carry ignored dump data. */ }
+            if (position !== member.offset + member.size)
+                throw new ArchiveFormatError("incomplete TAR range consumption");
+        }
+        // Includes unrequested/skipped members, trailer checks, and physical EOF.
+        while (!(await iterator.next()).done) { /* Drain the bounded parser stream. */ }
+    });
+}

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

@@ -0,0 +1,18 @@
+import { Transform, type TransformCallback } from "node:stream";
+import { type TarMeterLimits } from "./archive-limits.js";
+import type { TarEntryInfo } from "./archive-tar.js";
+export type AdmittedTarMember = TarEntryInfo & {
+    offset: number;
+};
+/** Backpressure-aware transport only; all TAR semantics live in the Rust core. */
+export declare class TarParserStream extends Transform {
+    private readonly onMember?;
+    private abi;
+    constructor(limits: TarMeterLimits, onMember?: ((entry: AdmittedTarMember) => void) | undefined);
+    private bytes;
+    private text;
+    _transform(chunk: Buffer, _encoding: BufferEncoding, callback: TransformCallback): void;
+    _flush(callback: TransformCallback): void;
+    _destroy(error: Error | null, callback: (error: Error | null) => void): void;
+}
+//# sourceMappingURL=archive-tar-wasm.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-tar-wasm.d.ts","sourceRoot":"","sources":["../src/archive-tar-wasm.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,EAA+C,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACvG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAyClE,kFAAkF;AAClF,qBAAa,eAAgB,SAAQ,SAAS;IAER,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAD9D,OAAO,CAAC,GAAG,CAAkB;IAC7B,YAAY,MAAM,EAAE,cAAc,EAAmB,QAAQ,CAAC,GAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,aAAA,EAQjG;IACD,OAAO,CAAC,KAAK;IAQb,OAAO,CAAC,IAAI;IAIH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAkB/F;IACQ,MAAM,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAKjD;IACQ,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAKpF;CACF"}

package/dist/archive-tar-wasm.js

@@ -0,0 +1,102 @@
+import { readFileSync } from "node:fs";
+import { Transform } from "node:stream";
+import { ArchiveFormatError, ArchiveSecurityError, isArchiveTarPathErrorMessage } from "./archive-errors.js";
+import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError } from "./archive-limits.js";
+// Node exposes WebAssembly without DOM globals; keep the private ABI types local.
+const wasm = globalThis.WebAssembly;
+let compiled;
+function instance() {
+    // src tests and dist consumers resolve the same generated package artifact.
+    compiled ??= new wasm.Module(readFileSync(new URL("../dist/archive-parser.wasm", import.meta.url)));
+    if (wasm.Module.imports(compiled).length)
+        throw new Error("TAR WASM unexpectedly requires host imports");
+    return new wasm.Instance(compiled).exports;
+}
+const types = new Map([
+    [0, "File"], [48, "File"], [49, "Link"], [50, "SymbolicLink"],
+    [51, "CharacterDevice"], [52, "BlockDevice"], [53, "Directory"],
+    [54, "FIFO"], [55, "ContiguousFile"], [68, "GNUDumpDir"],
+]);
+function parserError(message) {
+    if (isArchiveTarPathErrorMessage(message))
+        return new ArchiveSecurityError("entry-path", message);
+    for (const code of Object.values(ARCHIVE_LIMIT_ERROR_CODE)) {
+        if (message.includes(code))
+            return new ArchiveLimitError(code);
+    }
+    return new ArchiveFormatError(message.replace(/^archive-header-invalid:/, "invalid TAR header:"));
+}
+/** Backpressure-aware transport only; all TAR semantics live in the Rust core. */
+export class TarParserStream extends Transform {
+    onMember;
+    abi;
+    constructor(limits, onMember) {
+        super();
+        this.onMember = onMember;
+        this.abi = instance();
+        if (this.abi.init(limits.maxEntries, limits.maxMetaEntryBytes, limits.maxDecodedBytes, limits.maxManifestBytes, Number(process.platform === "win32")) !== 0) {
+            this.abi.dispose();
+            this.abi = undefined;
+            throw new RangeError("invalid TAR parser limits");
+        }
+    }
+    bytes(pointer, length) {
+        const memory = this.abi.memory.buffer;
+        if (!Number.isInteger(pointer) || !Number.isInteger(length) || pointer < 0 || length < 0 ||
+            pointer > memory.byteLength || length > memory.byteLength - pointer) {
+            throw new ArchiveFormatError("invalid TAR WASM memory range");
+        }
+        return new Uint8Array(memory, pointer, length);
+    }
+    text() {
+        const abi = this.abi;
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(this.bytes(abi.text_ptr(), abi.text_len()));
+    }
+    _transform(chunk, _encoding, callback) {
+        try {
+            const abi = this.abi;
+            for (let offset = 0; offset < chunk.length;) {
+                const length = Math.min(65536, chunk.length - offset);
+                this.bytes(abi.input_ptr(), length).set(chunk.subarray(offset, offset + length));
+                const used = abi.push(length);
+                if (used < 0)
+                    throw parserError(this.text());
+                if (used === 0 || used > length)
+                    throw new ArchiveFormatError("TAR WASM made no progress");
+                offset += used;
+                const type = abi.member_type();
+                if (type >= 0)
+                    this.onMember?.({
+                        path: this.text(), type: types.get(type) ?? "Unsupported", size: abi.member_size(),
+                        mode: abi.member_mode(), offset: abi.member_offset(),
+                    });
+            }
+            callback(null, chunk);
+        }
+        catch (error) {
+            callback(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    _flush(callback) {
+        try {
+            if (this.abi.finish() !== 0)
+                throw parserError(this.text());
+            callback();
+        }
+        catch (error) {
+            callback(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    _destroy(error, callback) {
+        try {
+            this.abi?.dispose();
+        }
+        catch (cause) {
+            error ??= cause instanceof Error ? cause : new Error(String(cause));
+        }
+        finally {
+            this.abi = undefined;
+        }
+        callback(error);
+    }
+}

package/dist/archive-tar.d.ts

@@ -6,7 +6,6 @@ export type TarEntryInfo = {
     size: number;
     mode?: number;
 };
-export declare function readTarEntryInfo(entry: unknown): TarEntryInfo;
 export declare function createTarEntryPreflightChecker(params: {
     rootDir: string;
     stripComponents?: number;

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

@@ -1 +1 @@
-{"version":3,"file":"archive-tar.d.ts","sourceRoot":"","sources":["../src/archive-tar.ts"],"names":[],"mappings":"AAMA,OAAO,EAKL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,0BAA0B,EAChC,MAAM,qBAAqB,CAAC;AAI7B,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAWvF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,CAyB7D;AAED,wBAAgB,8BAA8B,CAAC,MAAM,EAAE;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,UAAU,CAAC,EAAE,0BAA0B,CAAC;CACzC,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAqDnC"}
+{"version":3,"file":"archive-tar.d.ts","sourceRoot":"","sources":["../src/archive-tar.ts"],"names":[],"mappings":"AAMA,OAAO,EAKL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,0BAA0B,EAChC,MAAM,qBAAqB,CAAC;AAI7B,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAWvF,wBAAgB,8BAA8B,CAAC,MAAM,EAAE;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,UAAU,CAAC,EAAE,0BAA0B,CAAC;CACzC,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAqDnC"}

package/dist/archive-tar.js

@@ -11,28 +11,6 @@ const BLOCKED_TAR_ENTRY_TYPES = new Set([
     "FIFO",
     "Socket",
 ]);
-export function readTarEntryInfo(entry) {
-    const p = typeof entry === "object" && entry !== null && "path" in entry
-        ? String(entry.path)
-        : "";
-    const t = typeof entry === "object" && entry !== null && "type" in entry
-        ? String(entry.type)
-        : "";
-    const s = typeof entry === "object" &&
-        entry !== null &&
-        "size" in entry &&
-        typeof entry.size === "number" &&
-        Number.isFinite(entry.size)
-        ? Math.max(0, Math.floor(entry.size))
-        : 0;
-    const mode = typeof entry === "object" &&
-        entry !== null &&
-        "mode" in entry &&
-        typeof entry.mode === "number"
-        ? entry.mode
-        : undefined;
-    return { path: p, type: t, size: s, mode };
-}
 export function createTarEntryPreflightChecker(params) {
     const strip = Math.max(0, Math.floor(params.stripComponents ?? 0));
     const limits = resolveExtractLimits(params.limits);

package/dist/archive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AA+DA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACjF,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,6BAA6B,EAC7B,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,iCAAiC,EACjC,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EACL,kCAAkC,EAClC,iCAAiC,EACjC,4BAA4B,EAC5B,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,8BAA8B,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,KAAK,mBAAmB,GACzB,MAAM,4BAA4B,CAAC;AA6MpC,wBAAsB,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqKjF"}
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AAwDA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACjF,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,6BAA6B,EAC7B,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,iCAAiC,EACjC,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EACL,kCAAkC,EAClC,iCAAiC,EACjC,4BAA4B,EAC5B,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,8BAA8B,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,KAAK,mBAAmB,GACzB,MAAM,4BAA4B,CAAC;AA6MpC,wBAAsB,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgEjF"}