@openclaw/fs-safe 0.8.3 → 0.8.5

package/CHANGELOG.md

@@ -1,13 +1,59 @@
 # Changelog
 
+## Unreleased
+
+## 0.8.5 - 2026-09-07
+
+### Highlights
+
+- **Strict moves stay strict:** a move started with hardlink rejection keeps that policy throughout asynchronous preparation and copying, even when the caller reuses or changes its options object.
+
+### Safe moves
+
+- Preserve the admitted `sourceHardlinks` policy through staged-copy fallback. A late hardlink is still rejected before destination publication, with the source and its alias preserved, instead of being accepted after an in-flight options change.
+- Document when move policy is captured and how it relates to the existing per-mutation authority checks and destination-publication receipts.
+
+## 0.8.4 - 2026-09-07
+
+### Highlights
+
+- **Faster reads and writes:** metadata checks avoid unnecessary event-loop round-trips while data I/O stays asynchronous; reconstructible data can explicitly opt out of fsync with `durable: false`.
+- **Inspect TARs without extracting:** the new bounded archive inspection API uses the same native/WASM admission and canonical planner as extraction.
+
+### Filesystem performance and durability
+
+- Run metadata checks inside async operations synchronously (microseconds each), cutting event-loop round-trips per read/write while data I/O remains asynchronous and native canonical path spelling is preserved, including Windows short paths.
+- Add `durable` to Root write/create/writeJson/createJson/append options and Root defaults; `durable: false` skips file and parent fsync for reconstructible data (default unchanged: durable).
+
+### Archive inspection and compatibility
+
+- Add bounded `inspectTarArchive` with complete native/WASM admission and the same canonical extraction planner, preserving effective member identities without materializing an output tree.
+- Preserve inherited and getter-backed extraction options on the WASM TAR path, matching native and ZIP handling for destinations, filters, stripping, and modes.
+
+### Validation
+
+- Apply the existing filesystem-test worker cap locally as well as in CI, and drain archive publication fixtures before resetting hooks or cleaning restricted directories after timeouts.
+
 ## 0.8.3 - 2026-09-06
 
+### Highlights
+
+- **Safer cancellable moves:** callers can guard every source removal and retain an exact destination-publication receipt for recovery after later failures, including Windows and cross-device fallbacks.
+- **Less filesystem overhead:** reads and writes make fewer calls while preserving their existing boundary and identity checks.
+
+### Move authority and recovery
+
 - Add optional synchronous move authority checks before renames and each copied-source removal, plus an exact bigint destination-publication receipt for caller-owned recovery after later failure; retain cross-device and Windows `EPERM` copy fallbacks and the existing `Promise<void>` contract.
 
-- Simplify internals without changing public behavior: remove unused string/home helpers, `resolveUserPath`, `createBoundedReadStream`, `sidecarLockPayloadIsStale`, and `tarManifestEntryCost`; share filesystem utilities and merge private modules.
+### Filesystem performance and durability
+
 - Reduce filesystem calls per read and write while retaining boundary, hardlink, hook, retry, and post-mutation identity checks.
 - Skip native publication's extra mode-only file fsync for modes that retain owner read/write when staging permissions have not widened; after a crash, a file may retain staged `0o600` instead of the wider requested mode, while restrictive modes retain the extra fsync.
+
+### Tooling and maintenance
+
 - Add 1 MiB read/write and existing-mode inheritance benchmarks, with native-mode metadata and per-case iteration counts.
+- Simplify internals without changing public behavior: remove unused string/home helpers, `resolveUserPath`, `createBoundedReadStream`, `sidecarLockPayloadIsStale`, and `tarManifestEntryCost`; share filesystem utilities and merge private modules.
 
 ## 0.8.2 - 2026-09-05
 

package/dist/absolute-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"absolute-path.d.ts","sourceRoot":"","sources":["../src/absolute-path.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAIhE,MAAM,MAAM,yBAAyB,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAU5D,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,GAAG;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,8BAA8B,GAAG;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,6BAA6B,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC;AAmL7D,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWhE;AAED,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAEnF;AAuBD,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,8BAAmC,GAC3C,OAAO,CAAC,6BAA6B,CAAC,CA+ExC;AAED,wBAAsB,iCAAiC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAazF;AAED,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,yBAAyB,CAAA;CAAO,GACrD,OAAO,CAAC,oBAAoB,CAAC,CAgB/B;AAED,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,yBAAyB,CAAA;CAAO,GACrD,OAAO,CAAC,4BAA4B,CAAC,CA2BvC"}
+{"version":3,"file":"absolute-path.d.ts","sourceRoot":"","sources":["../src/absolute-path.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAIhE,MAAM,MAAM,yBAAyB,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAU5D,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,GAAG;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,8BAA8B,GAAG;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,6BAA6B,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC;AAmL7D,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWhE;AAED,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAEnF;AAuBD,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,8BAAmC,GAC3C,OAAO,CAAC,6BAA6B,CAAC,CA+ExC;AAED,wBAAsB,iCAAiC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAazF;AAED,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,yBAAyB,CAAA;CAAO,GACrD,OAAO,CAAC,oBAAoB,CAAC,CAgB/B;AAED,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,yBAAyB,CAAA;CAAO,GACrD,OAAO,CAAC,4BAA4B,CAAC,CA2BvC"}

package/dist/absolute-path.js

@@ -1,3 +1,4 @@
+import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, } from "./directory-guard.js";
@@ -66,7 +67,7 @@ async function directoryGuardFailure(err, dir, scopeLabel) {
         return { ok: false, code: err.code, error: err };
     }
     try {
-        const stat = await fs.lstat(dir);
+        const stat = fsSync.lstatSync(dir);
         const failure = classifyExistingDirectorySegment(stat, scopeLabel);
         if (failure) {
             return failure;
@@ -86,7 +87,7 @@ async function resolveTrustedDirectoryPrefix(targetPath, scopeLabel) {
     let current = root;
     let currentStat;
     try {
-        currentStat = await fs.lstat(current);
+        currentStat = fsSync.lstatSync(current);
     }
     catch (err) {
         const failure = classifyDirectoryLookupError(err, scopeLabel);
@@ -110,7 +111,7 @@ async function resolveTrustedDirectoryPrefix(targetPath, scopeLabel) {
         }
         const next = path.join(current, segment);
         try {
-            const nextStat = await fs.lstat(next);
+            const nextStat = fsSync.lstatSync(next);
             const segmentFailure = classifyExistingDirectorySegment(nextStat, scopeLabel);
             if (segmentFailure) {
                 return segmentFailure;
@@ -155,7 +156,7 @@ async function findExistingAncestorWithStat(filePath) {
     let current = path.resolve(filePath);
     while (true) {
         try {
-            return { path: current, stat: await fs.lstat(current) };
+            return { path: current, stat: fsSync.lstatSync(current) };
         }
         catch (err) {
             if (err.code !== "ENOENT") {
@@ -199,7 +200,7 @@ export async function ensureAbsoluteDirectory(dirPath, options = {}) {
                 return guardResult;
             }
             try {
-                const stat = await fs.lstat(current);
+                const stat = fsSync.lstatSync(current);
                 if (stat.isSymbolicLink()) {
                     return ensureDirectoryFailure("symlink", `directory path traverses a symlink within ${scopeLabel}`);
                 }
@@ -250,7 +251,7 @@ export async function canonicalPathFromExistingAncestor(filePath) {
     }
     let canonicalAncestor = ancestor;
     try {
-        canonicalAncestor = await fs.realpath(ancestor);
+        canonicalAncestor = fsSync.realpathSync.native(ancestor);
     }
     catch {
         // Keep lexical path when the existing ancestor cannot be canonicalized.
@@ -263,7 +264,7 @@ export async function resolveAbsolutePathForRead(filePath, options = {}) {
     const normalized = assertAbsolutePathInput(filePath);
     let canonicalPath;
     try {
-        canonicalPath = await fs.realpath(normalized);
+        canonicalPath = fsSync.realpathSync.native(normalized);
     }
     catch (err) {
         if (err.code === "ENOENT") {

package/dist/archive-native.d.ts

@@ -3,6 +3,7 @@ import type { ArchiveKind } from "./archive-kind.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 throwMappedNativeArchiveError(error: unknown): never;
 export declare function extractNativeArchive(params: {
     binding: NativeBinding;
     archivePath: string;

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

@@ -1 +1 @@
-{"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;AAQlE,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,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,CAyJhB"}
+{"version":3,"file":"archive-native.d.ts","sourceRoot":"","sources":["../src/archive-native.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAEL,KAAK,4BAA4B,EACjC,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAOlE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAYnE;AAED,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,OAAO,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,CA6FhB"}

package/dist/archive-native.js

@@ -2,22 +2,14 @@ import { classifyArchiveParserError } from "./archive-parser-errors.js";
 import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import { ArchiveFormatError, ArchiveSecurityError, isArchiveFormatErrorMessage, } from "./archive-errors.js";
-import { formatErrorDetail } from "./error-detail.js";
-import { createArchiveOutputPathTracker, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
+import { stripArchivePath, validateArchiveEntryPath } from "./archive-entry.js";
+import { createArchiveEntryPlanner } from "./archive-plan.js";
 import { stageArchiveFileForExtraction } from "./archive-input.js";
-import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWithinLimit, createByteBudgetTracker, } from "./archive-limits.js";
-import { resolveArchiveEntryMode, shouldExtractArchiveEntry } from "./archive-policy.js";
+import { assertArchiveEntryCountWithinLimit, } from "./archive-limits.js";
 import { prepareArchiveDestinationDir, withStagedArchiveDestination, } from "./archive-staging.js";
 import { mergePlannedArchiveIntoDestination } from "./archive-merge.js";
 import { admitZipFile } from "./archive-zip-admission.js";
-function policyKind(kind) {
-    if (kind === "file" || kind === "directory")
-        return kind;
-    if (kind === "symlink" || kind === "hardlink")
-        return "symlink";
-    return "other";
-}
-function throwMappedNativeError(error) {
+export function throwMappedNativeArchiveError(error) {
     if (error instanceof Error) {
         const mapped = classifyArchiveParserError(error.message, { cause: error });
         if (mapped)
@@ -50,7 +42,7 @@ export async function extractNativeArchive(params) {
                 params.deadline.check();
                 const manifest = await params.binding
                     .inspectArchiveNative(stagedArchive.path, params.kind, tarLimits, params.deadline.signal)
-                    .catch(throwMappedNativeError);
+                    .catch(throwMappedNativeArchiveError);
                 params.deadline.check();
                 assertArchiveEntryCountWithinLimit(manifest.length, limits);
                 if (physicalCount !== undefined && manifest.length !== physicalCount) {
@@ -75,69 +67,24 @@ export async function extractNativeArchive(params) {
                     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();
+                const planEntry = createArchiveEntryPlanner({ ...params, rootDir: stagingDir }, params.kind);
                 const plan = [];
                 for (const entry of manifest) {
                     params.deadline.check();
-                    validateArchiveEntryPath(entry.path);
-                    const canonicalPath = stripArchivePath(entry.path, 0);
-                    if (!canonicalPath)
-                        continue;
-                    const relPath = stripArchivePath(canonicalPath, strip);
-                    if (!relPath)
-                        continue;
-                    validateArchiveEntryPath(relPath);
-                    assertArchiveEntryPathComponentsWithinLimit(relPath, limits);
-                    trackOutputPath(relPath, entry.path);
-                    resolveArchiveOutputPath({ rootDir: stagingDir, relPath, originalPath: entry.path });
-                    const kind = policyKind(entry.kind);
-                    if (!shouldExtractArchiveEntry({
-                        filter: params.entryFilter,
-                        onFiltered: params.onFiltered,
-                        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" || 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);
-                    }
-                    // 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);
-                    }
-                    if (kind === "file" || kind === "directory") {
-                        plan.push({
-                            index: entry.index,
-                            path: relPath,
-                            kind,
-                            size: entry.size,
-                            mode: resolveArchiveEntryMode({
-                                kind,
-                                archivedMode: params.kind === "zip"
-                                    ? zipEntries[entry.index].creatorSystem === 3
-                                        ? zipEntries[entry.index].externalAttributes >>> 16
-                                        : undefined
-                                    : entry.mode,
-                                policy: params.entryModes,
-                            }),
-                        });
-                    }
+                    const mode = params.kind === "zip"
+                        ? zipEntries[entry.index].creatorSystem === 3
+                            ? zipEntries[entry.index].externalAttributes >>> 16
+                            : undefined
+                        : entry.mode;
+                    const accepted = planEntry({ ...entry, mode });
+                    if (accepted)
+                        plan.push({ ...accepted, index: entry.index });
                 }
                 const directory = await fs.open(stagingDir, fsConstants.O_RDONLY |
                     (typeof fsConstants.O_DIRECTORY === "number" ? fsConstants.O_DIRECTORY : 0));
                 try {
                     params.deadline.check();
-                    await params.binding.extractArchiveNative(stagedArchive.path, params.kind, directory.fd, plan.map((entry) => ({ ...entry, mode: entry.kind === "directory" ? 0o700 : 0o600 })), tarLimits, params.deadline.signal).catch(throwMappedNativeError);
+                    await params.binding.extractArchiveNative(stagedArchive.path, params.kind, directory.fd, plan.map((entry) => ({ ...entry, mode: entry.kind === "directory" ? 0o700 : 0o600 })), tarLimits, params.deadline.signal).catch(throwMappedNativeArchiveError);
                 }
                 finally {
                     await directory.close().catch(() => undefined);

package/dist/archive-plan.d.ts

@@ -0,0 +1,20 @@
+import type { ArchiveKind } from "./archive-kind.js";
+import type { ExtractArchiveOptions } from "./archive-options.js";
+export type ArchiveMemberKind = "file" | "directory" | "symlink" | "hardlink" | "blocked" | "sparse" | "other";
+export type ArchivePlanEntry = {
+    path: string;
+    kind: "file" | "directory";
+    size: number;
+    mode: number;
+};
+export type ArchivePlanOptions = Pick<ExtractArchiveOptions, "stripComponents" | "limits" | "entryModes" | "entryFilter" | "onFiltered"> & {
+    rootDir?: string;
+    escapeLabel?: string;
+};
+export declare function createArchiveEntryPlanner(params: ArchivePlanOptions, archiveKind: ArchiveKind): (entry: {
+    path: string;
+    kind: ArchiveMemberKind;
+    size: number;
+    mode?: number;
+}) => ArchivePlanEntry | null;
+//# sourceMappingURL=archive-plan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-plan.d.ts","sourceRoot":"","sources":["../src/archive-plan.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AASrD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAIlE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC/G,MAAM,MAAM,gBAAgB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AACxG,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,qBAAqB,EACzD,iBAAiB,GAAG,QAAQ,GAAG,YAAY,GAAG,aAAa,GAAG,YAAY,CAAC,GAAG;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAIF,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,kBAAkB,EAAE,WAAW,EAAE,WAAW,GAAG,CAAC,KAAK,EAAE;IACvG,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACpE,KAAK,gBAAgB,GAAG,IAAI,CA2C5B"}

package/dist/archive-plan.js

@@ -0,0 +1,55 @@
+import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
+import { createArchiveOutputPathTracker, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
+import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWithinLimit, createByteBudgetTracker, resolveExtractLimits, } from "./archive-limits.js";
+import { resolveArchiveEntryMode, shouldExtractArchiveEntry } from "./archive-policy.js";
+import { formatErrorDetail } from "./error-detail.js";
+// Inspection and both executors decide over the same admitted identities.
+// A destination is optional only for inspection; writers still prove containment.
+export function createArchiveEntryPlanner(params, archiveKind) {
+    const strip = Math.max(0, Math.floor(params.stripComponents ?? 0));
+    const limits = resolveExtractLimits(params.limits);
+    const budget = createByteBudgetTracker(limits);
+    const trackOutputPath = createArchiveOutputPathTracker();
+    let entryCount = 0;
+    return (entry) => {
+        assertArchiveEntryCountWithinLimit(++entryCount, limits);
+        validateArchiveEntryPath(entry.path, { escapeLabel: params.escapeLabel });
+        const canonicalPath = stripArchivePath(entry.path, 0);
+        if (!canonicalPath)
+            return null;
+        const relPath = stripArchivePath(canonicalPath, strip);
+        if (!relPath)
+            return null;
+        validateArchiveEntryPath(relPath, { escapeLabel: params.escapeLabel });
+        assertArchiveEntryPathComponentsWithinLimit(relPath, limits);
+        trackOutputPath(relPath, entry.path);
+        if (params.rootDir !== undefined) {
+            resolveArchiveOutputPath({ rootDir: params.rootDir, relPath, originalPath: entry.path,
+                escapeLabel: params.escapeLabel });
+        }
+        const kind = entry.kind === "file" || entry.kind === "directory" ? entry.kind
+            : entry.kind === "symlink" || entry.kind === "hardlink" ? "symlink" : "other";
+        if (!shouldExtractArchiveEntry({ filter: params.entryFilter, onFiltered: params.onFiltered,
+            entry: { path: canonicalPath, kind, size: entry.size } }))
+            return null;
+        if (entry.kind === "sparse") {
+            throw new ArchiveFormatError(`GNU sparse archive entry is not supported: ${formatErrorDetail(entry.path)}`);
+        }
+        if (kind === "symlink" || entry.kind === "blocked") {
+            const label = archiveKind === "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);
+        }
+        // Unsupported records remain visible to policy but cannot create outputs.
+        if (kind === "other")
+            return null;
+        if (kind === "file" || archiveKind !== "zip") {
+            budget.startEntry();
+            budget.addEntrySize(entry.size);
+        }
+        return { path: relPath, kind, size: entry.size,
+            mode: resolveArchiveEntryMode({ kind, archivedMode: entry.mode, policy: params.entryModes }) };
+    };
+}

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

@@ -0,0 +1,7 @@
+import type { ExtractArchiveOptions } from "./archive-options.js";
+import { type ArchivePlanEntry } from "./archive-plan.js";
+export type InspectTarArchiveOptions = Pick<ExtractArchiveOptions, "archivePath" | "timeoutMs" | "limits" | "entryFilter" | "onFiltered">;
+export type InspectedTarEntry = Readonly<Pick<ArchivePlanEntry, "path" | "kind" | "size">>;
+/** Complete TAR/gzip admission and zero-strip extraction policy, without output writes. */
+export declare function inspectTarArchive(params: InspectTarArchiveOptions): Promise<readonly InspectedTarEntry[]>;
+//# sourceMappingURL=archive-tar-inspect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-tar-inspect.d.ts","sourceRoot":"","sources":["../src/archive-tar-inspect.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAOrF,MAAM,MAAM,wBAAwB,GAAG,IAAI,CAAC,qBAAqB,EAC/D,aAAa,GAAG,WAAW,GAAG,QAAQ,GAAG,aAAa,GAAG,YAAY,CAAC,CAAC;AACzE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;AAE3F,2FAA2F;AAC3F,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CA2C/G"}

package/dist/archive-tar-inspect.js

@@ -0,0 +1,59 @@
+import { withExtractionDeadline } from "./archive-deadline.js";
+import { validateArchiveEntryPath } from "./archive-entry.js";
+import { stageArchiveFileForExtraction } from "./archive-input.js";
+import { resolveExtractLimits, resolveTarMeterLimits } from "./archive-limits.js";
+import { throwMappedNativeArchiveError } from "./archive-native.js";
+import { createArchiveEntryPlanner } from "./archive-plan.js";
+import { resolveArchiveFilteredEntryPolicy } from "./archive-policy.js";
+import { createTarEntryPlanner } from "./archive-tar.js";
+import { inspectTar } from "./archive-tar-stream.js";
+import { getNativeBinding } from "./native.js";
+/** Complete TAR/gzip admission and zero-strip extraction policy, without output writes. */
+export async function inspectTarArchive(params) {
+    const onFiltered = resolveArchiveFilteredEntryPolicy(params.onFiltered);
+    const limits = resolveExtractLimits(params.limits);
+    const tarLimits = resolveTarMeterLimits(limits);
+    const native = getNativeBinding();
+    return await withExtractionDeadline(params.timeoutMs, "inspect tar", async (deadline) => {
+        const staged = await stageArchiveFileForExtraction({ archivePath: params.archivePath, limits, deadline });
+        try {
+            // Staging closes descriptors asynchronously; expiry there must not start a decoder.
+            deadline.check();
+            const entries = [];
+            const append = (entry) => {
+                if (entry)
+                    entries.push(Object.freeze({ path: entry.path, kind: entry.kind, size: entry.size }));
+            };
+            const policy = { limits, entryFilter: params.entryFilter, onFiltered };
+            if (native) {
+                const manifest = await native.inspectArchiveNative(staged.path, "tar", tarLimits, deadline.signal)
+                    .catch(throwMappedNativeArchiveError);
+                deadline.check();
+                // Match extraction's whole-manifest validation before caller policy runs.
+                for (const entry of manifest)
+                    validateArchiveEntryPath(entry.path);
+                const planEntry = createArchiveEntryPlanner(policy, "tar");
+                for (const entry of manifest) {
+                    deadline.check();
+                    append(planEntry(entry));
+                }
+            }
+            else {
+                const manifest = [];
+                await inspectTar({ archivePath: staged.path, limits: tarLimits, signal: deadline.signal,
+                    onMember: (entry) => { manifest.push(entry); } });
+                const planEntry = createTarEntryPlanner(policy);
+                for (const entry of manifest) {
+                    deadline.check();
+                    append(planEntry(entry));
+                }
+            }
+            deadline.check();
+            // This is bounded evidence about the staged bytes, not a reusable write plan.
+            return Object.freeze(entries);
+        }
+        finally {
+            await staged.cleanup();
+        }
+    });
+}

package/dist/archive-tar.d.ts

@@ -1,4 +1,5 @@
-import { type ArchiveExtractLimits } from "./archive-limits.js";
+import type { ArchiveExtractLimits } from "./archive-limits.js";
+import { type ArchivePlanEntry, type ArchivePlanOptions } from "./archive-plan.js";
 import { type ArchiveEntryFilter, type ArchiveFilteredEntryPolicy } from "./archive-policy.js";
 export type TarEntryInfo = {
     path: string;
@@ -6,6 +7,7 @@ export type TarEntryInfo = {
     size: number;
     mode?: number;
 };
+export declare function createTarEntryPlanner(params: ArchivePlanOptions): (entry: TarEntryInfo) => ArchivePlanEntry | null;
 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,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":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,0BAA0B,EAChC,MAAM,qBAAqB,CAAC;AAE7B,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;AASvF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,kBAAkB,GAC9D,CAAC,KAAK,EAAE,YAAY,KAAK,gBAAgB,GAAG,IAAI,CAQjD;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,CAGnC"}

package/dist/archive-tar.js

@@ -1,58 +1,21 @@
-import { createArchiveOutputPathTracker, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
-import { assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWithinLimit, createByteBudgetTracker, resolveExtractLimits, } from "./archive-limits.js";
-import { archiveEntryKindFromTarType, shouldExtractArchiveEntry, } from "./archive-policy.js";
-import { ArchiveSecurityError } from "./archive-errors.js";
-import { formatErrorDetail } from "./error-detail.js";
+import { createArchiveEntryPlanner, } from "./archive-plan.js";
+import { archiveEntryKindFromTarType, } from "./archive-policy.js";
 const BLOCKED_TAR_ENTRY_TYPES = new Set([
-    "SymbolicLink",
-    "Link",
     "BlockDevice",
     "CharacterDevice",
     "FIFO",
     "Socket",
 ]);
-export function createTarEntryPreflightChecker(params) {
-    const strip = Math.max(0, Math.floor(params.stripComponents ?? 0));
-    const limits = resolveExtractLimits(params.limits);
-    let entryCount = 0;
-    const budget = createByteBudgetTracker(limits);
-    const trackOutputPath = createArchiveOutputPathTracker();
+export function createTarEntryPlanner(params) {
+    // Preserve inherited/getter-backed public options and per-entry policy reads.
+    const plan = createArchiveEntryPlanner(params, "tar");
     return (entry) => {
-        entryCount += 1;
-        assertArchiveEntryCountWithinLimit(entryCount, limits);
-        validateArchiveEntryPath(entry.path, { escapeLabel: params.escapeLabel });
-        const canonicalPath = stripArchivePath(entry.path, 0);
-        if (!canonicalPath)
-            return false;
-        const relPath = stripArchivePath(canonicalPath, strip);
-        if (!relPath) {
-            return false;
-        }
-        validateArchiveEntryPath(relPath, { escapeLabel: params.escapeLabel });
-        assertArchiveEntryPathComponentsWithinLimit(relPath, limits);
-        trackOutputPath(relPath, entry.path);
-        resolveArchiveOutputPath({
-            rootDir: params.rootDir,
-            relPath,
-            originalPath: entry.path,
-            escapeLabel: params.escapeLabel,
-        });
-        const kind = archiveEntryKindFromTarType(entry.type);
-        if (!shouldExtractArchiveEntry({
-            filter: params.entryFilter,
-            onFiltered: params.onFiltered,
-            entry: { path: canonicalPath, kind, size: entry.size },
-        })) {
-            return false;
-        }
-        if (BLOCKED_TAR_ENTRY_TYPES.has(entry.type)) {
-            throw new ArchiveSecurityError("entry-link", `tar entry is a link: ${formatErrorDetail(entry.path)}`);
-        }
-        // Accepted unsupported records remain omitted, as in the native plan.
-        if (kind === "other")
-            return false;
-        budget.startEntry();
-        budget.addEntrySize(entry.size);
-        return true;
+        const kind = BLOCKED_TAR_ENTRY_TYPES.has(entry.type) ? "blocked" : archiveEntryKindFromTarType(entry.type);
+        // The public checker accepts structural entry objects, including class getters.
+        return plan({ path: entry.path, kind, size: entry.size, mode: entry.mode });
     };
 }
+export function createTarEntryPreflightChecker(params) {
+    const plan = createTarEntryPlanner(params);
+    return (entry) => plan(entry) !== null;
+}

package/dist/archive.d.ts

@@ -4,6 +4,7 @@ export type { ArchiveEntryFilter, ArchiveEntryKind, ArchiveEntryModePolicy, Arch
 export { isWindowsDrivePath, normalizeArchiveEntryPath, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
 export { resolveArchiveKind, resolvePackedRootDir, type ArchiveKind } from "./archive-kind.js";
 export { readArchiveEntry } from "./archive-read.js";
+export { inspectTarArchive, type InspectTarArchiveOptions, type InspectedTarEntry } from "./archive-tar-inspect.js";
 export { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, DEFAULT_MAX_ARCHIVE_BYTES_ZIP, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_EXTRACTED_BYTES, DEFAULT_MAX_ENTRY_BYTES, DEFAULT_MAX_META_ENTRY_BYTES, DEFAULT_MAX_ENTRY_PATH_COMPONENTS, type ArchiveExtractLimits, type ArchiveLimitErrorCode, } from "./archive-limits.js";
 export { ArchiveFormatError, type ArchiveFormatErrorCode } from "./archive-errors.js";
 export { ArchiveSecurityError, type ArchiveSecurityErrorCode } from "./archive-staging.js";

package/dist/archive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AA6DA,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,CA0DjF"}
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AA4DA,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,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACpH,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,CA4CjF"}