@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/archive-merge.js

@@ -1,27 +1,61 @@
+import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { ownExtractionDestinationMutation } from "./archive-deadline.js";
-import { assertDirectoryIdentityGuard, assertResolvedInsideDestination, createDirectoryIdentityGuard, createArchiveSymlinkTraversalError, preparePrivateArchiveOutputPath, } from "./archive-staging.js";
-import {} from "./directory-guard.js";
+import { assertDirectoryIdentityGuard, assertResolvedInsideDestination, createDirectoryIdentityGuard, createArchiveSymlinkTraversalError, preparePrivateArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
 import {} from "./directory-mode-owner.js";
 import { pinNodeDirectoryForMode } from "./directory-mode-node.js";
+import { assertSyncDirectoryGuard, inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { formatErrorDetail } from "./error-detail.js";
-import { isPathInside } from "./path.js";
-import { root } from "./root.js";
+import { isNotFoundPathError, isPathInside } from "./path.js";
+import { rootFromDirectoryGuard } from "./root-impl.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { realpathSync } from "./realpath.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-export async function mergePlannedArchiveIntoDestination(params) {
-    await mergeTree(params, params.entries);
+import { onCopyPublication, onCopySourceAdmission } from "./copy-publication.js";
+import { syncFileBestEffortSync } from "./file-sync.js";
+import { finalizeArchivePublication } from "./archive-durability.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+export async function withStagedArchivePublication(params, extract) {
+    await withStagedArchiveDestination({
+        destinationRealDir: params.destinationGuard.realPath,
+        run: async (stagingPath) => {
+            const sourceDir = realpathSync.native(stagingPath);
+            const entries = await extract(sourceDir);
+            params.deadline?.check();
+            const mergeParams = { ...params, sourceDir };
+            assertMergePathInputs(mergeParams);
+            await mergeTree(mergeParams, entries, params.durable === true, params.entryUmask);
+            params.deadline?.check();
+        },
+    });
 }
 export async function mergeExtractedTreeIntoDestination(params) {
-    await mergeTree(params);
+    const sourceDir = params.sourceDir;
+    const destinationDir = params.destinationDir;
+    const destinationRealDir = params.destinationRealDir;
+    assertNoWindowsPathAlias(sourceDir);
+    assertNoWindowsPathAlias(destinationDir);
+    assertNoWindowsPathAlias(destinationRealDir);
+    const destinationGuard = await createDirectoryIdentityGuard(destinationRealDir);
+    await mergeTree({ sourceDir, deadline: params.deadline, destinationGuard });
 }
-async function mergeTree(params, publication) {
+function assertMergePathInputs(params) {
+    assertNoWindowsPathAlias(params.sourceDir);
+    assertNoWindowsPathAlias(params.destinationGuard.dir);
+    assertNoWindowsPathAlias(params.destinationGuard.realPath);
+}
+async function mergeTree(params, publication, durable = true, entryUmask = 0) {
+    const publishedFiles = [];
+    const publishedDirectories = [];
     const check = () => params.deadline?.check();
     check();
-    const destinationGuard = await createDirectoryIdentityGuard(params.destinationRealDir);
-    check();
-    const targetRoot = await root(params.destinationRealDir);
+    const { destinationGuard } = params;
+    const destinationDir = destinationGuard.dir;
+    const destinationRealDir = destinationGuard.realPath;
+    const targetRoot = rootFromDirectoryGuard(destinationGuard);
     check();
     const sourceGuard = await createDirectoryIdentityGuard(params.sourceDir);
     check();
@@ -29,7 +63,7 @@ async function mergeTree(params, publication) {
     for (const entry of publication ?? []) {
         // Resolve admitted spelling in private staging, preserving the volume's case
         // and Unicode behavior without assigning explicit modes to distinct parents.
-        const stagedPath = await fs.realpath(path.join(params.sourceDir, entry.path));
+        const stagedPath = realpathSync.native(path.join(params.sourceDir, entry.path));
         check();
         if (!isPathInside(sourceGuard.realPath, stagedPath) || plan.has(stagedPath)) {
             throw new FsSafeError("path-mismatch", "archive publication paths changed in staging");
@@ -37,6 +71,33 @@ async function mergeTree(params, publication) {
         plan.set(stagedPath, entry);
     }
     const ancestors = [];
+    const sourceAncestors = [];
+    const assertSourceDirectory = (guard, canonical = false) => {
+        try {
+            // Child receipts already retain canonical ancestry. An exact no-follow
+            // observation checks each named association without re-running realpath.
+            if (canonical)
+                assertSyncDirectoryGuard(guard);
+            else
+                inspectDirectoryIdentitySync(guard.dir, guard.stat);
+        }
+        catch (error) {
+            if (error instanceof FsSafeError || isNotFoundPathError(error)) {
+                throw createArchiveSymlinkTraversalError(path.relative(params.sourceDir, guard.dir));
+            }
+            throw error;
+        }
+        check();
+    };
+    const assertSourceFrontier = () => {
+        const current = sourceAncestors.at(-1);
+        if (current)
+            assertSourceDirectory(current);
+    };
+    const assertSourceAncestors = () => {
+        for (const ancestor of sourceAncestors)
+            assertSourceDirectory(ancestor);
+    };
     const assertGuards = async () => {
         await assertDirectoryIdentityGuard(destinationGuard);
         check();
@@ -51,19 +112,25 @@ async function mergeTree(params, publication) {
     };
     const walk = async (sourceDir) => {
         await assertGuards();
+        assertSourceFrontier();
         const entries = await fs.readdir(sourceDir, { withFileTypes: true });
         check();
+        if (entries.length === 0) {
+            await assertGuards();
+            assertSourceFrontier();
+        }
         for (const entry of entries) {
             await assertGuards();
+            assertSourceFrontier();
             const sourcePath = path.join(sourceDir, entry.name);
             const relPath = path.relative(params.sourceDir, sourcePath);
             const originalPath = relPath.split(path.sep).join("/");
-            const destinationPath = path.join(params.destinationDir, relPath);
-            const sourceStat = await fs.lstat(sourcePath);
+            const destinationPath = path.join(destinationDir, relPath);
+            const sourceStat = inspectFileIdentitySync(() => fsSync.lstatSync(sourcePath, { bigint: true }));
             check();
             if (sourceStat.isSymbolicLink())
                 throw createArchiveSymlinkTraversalError(originalPath);
-            const sourceReal = await fs.realpath(sourcePath);
+            const sourceReal = realpathSync.native(sourcePath);
             check();
             if (!isPathInside(sourceGuard.realPath, sourceReal))
                 throw createArchiveSymlinkTraversalError(originalPath);
@@ -75,75 +142,130 @@ async function mergeTree(params, publication) {
             if (plan && ((planned && planned.kind !== kind) || (!planned && kind === "file"))) {
                 throw new FsSafeError("path-mismatch", "archive staging disagrees with the admitted publication plan");
             }
-            const mode = plan ? planned?.mode ?? 0o755 : sourceStat.mode & 0o777;
+            let mode = plan ? (planned?.mode ?? 0o755) & ~entryUmask : Number(sourceStat.mode & 511n);
             await preparePrivateArchiveOutputPath({
-                ...params, relPath, outPath: destinationPath, originalPath, isDirectory: kind === "directory",
-            }, assertGuards);
+                destinationDir, destinationRealDir, deadline: params.deadline,
+                relPath, outPath: destinationPath, originalPath, isDirectory: kind === "directory",
+            }, assertGuards, destinationGuard);
             check();
             if (kind === "directory") {
-                // Ownership spans open, descendants, finalization and close, including timeout.
-                await ownExtractionDestinationMutation(params.deadline, async () => {
-                    await assertGuards();
-                    const owner = await pinNodeDirectoryForMode(destinationPath).catch((error) => {
-                        if (error instanceof FsSafeError && (error.code === "not-file" || error.code === "path-mismatch")) {
-                            throw createArchiveSymlinkTraversalError(originalPath);
-                        }
-                        throw error;
-                    });
-                    try {
-                        check();
-                        const guard = await createDirectoryIdentityGuard(destinationPath);
-                        check();
-                        await owner.verify(check);
-                        ancestors.push({ guard, owner });
+                // Retain the observation made before output preparation: recapturing
+                // here could silently authorize a replacement source directory.
+                sourceAncestors.push({ dir: sourcePath, realPath: sourceReal, stat: sourceStat });
+                try {
+                    // Ownership spans open, descendants, finalization and close, including timeout.
+                    await ownExtractionDestinationMutation(params.deadline, async () => {
+                        await assertGuards();
+                        assertSourceFrontier();
+                        const owner = await pinNodeDirectoryForMode(destinationPath).catch((error) => {
+                            if (error instanceof FsSafeError && (error.code === "not-file" || error.code === "path-mismatch")) {
+                                throw createArchiveSymlinkTraversalError(originalPath);
+                            }
+                            throw error;
+                        });
                         try {
-                            await walk(sourcePath);
-                            await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("chmod", destinationPath);
                             check();
-                            await assertGuards();
-                            // Do not recursively verify this owner from inside its serialized apply.
-                            ancestors.pop();
-                            await owner.apply(mode, { check, beforeChmod: async () => {
-                                    await assertGuards();
-                                    await assertDirectoryIdentityGuard(guard);
-                                    check();
-                                    await assertResolvedInsideDestination({
-                                        destinationRealDir: params.destinationRealDir, targetPath: destinationPath, originalPath,
-                                    });
-                                    check();
-                                } });
+                            const guard = await createDirectoryIdentityGuard(destinationPath);
                             check();
-                            await assertGuards();
+                            await owner.verify(check);
+                            ancestors.push({ guard, owner });
+                            try {
+                                await walk(sourcePath);
+                                if (publication) {
+                                    await assertGuards();
+                                    assertSourceAncestors();
+                                    publishedDirectories.push({ guard, mode, parents: ancestors.slice(0, -1).map((ancestor) => ancestor.guard) });
+                                    return;
+                                }
+                                await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("chmod", destinationPath);
+                                check();
+                                await assertGuards();
+                                // Do not recursively verify this owner from inside its serialized apply.
+                                ancestors.pop();
+                                await owner.apply(mode, { check, beforeChmod: async () => {
+                                        await assertGuards();
+                                        assertSourceAncestors();
+                                        await assertDirectoryIdentityGuard(guard);
+                                        check();
+                                        await assertResolvedInsideDestination({
+                                            destinationRealDir, targetPath: destinationPath, originalPath,
+                                        });
+                                        check();
+                                    } });
+                                check();
+                                await assertGuards();
+                                assertSourceAncestors();
+                            }
+                            finally {
+                                if (ancestors.at(-1)?.owner === owner)
+                                    ancestors.pop();
+                            }
                         }
                         finally {
-                            if (ancestors.at(-1)?.owner === owner)
-                                ancestors.pop();
+                            await owner.close();
                         }
-                    }
-                    finally {
-                        await owner.close();
-                    }
-                });
+                    });
+                }
+                finally {
+                    sourceAncestors.pop();
+                }
             }
             else {
                 await ownExtractionDestinationMutation(params.deadline, async () => {
                     await assertGuards();
                     try {
-                        await targetRoot.copyIn(relPath, sourcePath, { mkdir: true, mode });
+                        const options = {
+                            mkdir: false, mode, durable: publication ? false : true,
+                            [onCopySourceAdmission]: (identity, realPath) => {
+                                assertSourceDirectory(sourceGuard, true);
+                                assertSourceFrontier();
+                                inspectFileIdentitySync(() => identity, sourceStat);
+                                if (!admitPathInsideRoot({
+                                    rootPath: sourceGuard.realPath, candidatePath: realPath, rootIdentity: sourceGuard.stat,
+                                }))
+                                    throw createArchiveSymlinkTraversalError(originalPath);
+                                // Public merge permissions come from the admitted descriptor;
+                                // extraction keeps the separately admitted publication plan.
+                                if (!plan)
+                                    mode = Number(identity.mode & 511n);
+                                return { mode, verify() {
+                                        // Only copy publication boundaries scan the active chain.
+                                        // Destination mkdir callbacks must not multiply this work.
+                                        assertSourceDirectory(sourceGuard, true);
+                                        assertSourceAncestors();
+                                    } };
+                            },
+                        };
+                        if (publication && durable) {
+                            options[onCopyPublication] = async (fd, identity) => {
+                                check();
+                                if ((mode & 0o400) === 0) {
+                                    // Final mode may prohibit reopening. Sync the writer's still-owned
+                                    // descriptor without widening permissions or syncing its parent.
+                                    syncFileBestEffortSync(fd);
+                                    check();
+                                }
+                                else {
+                                    publishedFiles.push({ relativePath: relPath, identity,
+                                        guards: ancestors.map((ancestor) => ancestor.guard) });
+                                }
+                            };
+                        }
+                        await targetRoot.copyIn(relPath, sourcePath, options);
                         check();
                         await assertGuards();
                         await assertResolvedInsideDestination({
-                            destinationRealDir: params.destinationRealDir, targetPath: destinationPath, originalPath,
+                            destinationRealDir, targetPath: destinationPath, originalPath,
                         });
                         check();
-                        const stat = await fs.lstat(destinationPath);
+                        const stat = fsSync.lstatSync(destinationPath);
                         check();
                         if (stat.isSymbolicLink() || (stat.isFile() && stat.nlink > 1)) {
                             throw createArchiveSymlinkTraversalError(originalPath);
                         }
                     }
                     catch (error) {
-                        // copyIn alone owns cleanup; no receipt permits archive-layer unlink.
+                        // copyIn cleans unpublished stages; merge never gains rollback authority.
                         if (error instanceof FsSafeError && (error.code === "hardlink" || error.code === "path-alias")) {
                             throw createArchiveSymlinkTraversalError(originalPath);
                         }
@@ -154,4 +276,8 @@ async function mergeTree(params, publication) {
         }
     };
     await walk(params.sourceDir);
+    if (publication) {
+        await finalizeArchivePublication({ targetRoot, destinationGuard, sourceGuard,
+            files: publishedFiles, directories: publishedDirectories, durable, deadline: params.deadline });
+    }
 }

package/node_modules/@openclaw/fs-safe/dist/archive-parser-errors.d.ts

@@ -1,2 +1 @@
 export declare function classifyArchiveParserError(message: string, options?: ErrorOptions): Error | undefined;
-//# sourceMappingURL=archive-parser-errors.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/archive-plan.d.ts

@@ -1,5 +1,6 @@
 import type { ArchiveKind } from "./archive-kind.js";
-import type { ExtractArchiveOptions } from "./archive-options.js";
+import { type ResolvedArchiveExtractLimits, type ArchiveExtractLimits } from "./archive-limits.js";
+import type { ExtractionDeadline } from "./archive-deadline.js";
 export type ArchiveMemberKind = "file" | "directory" | "symlink" | "hardlink" | "blocked" | "sparse" | "other";
 export type ArchivePlanEntry = {
     path: string;
@@ -11,10 +12,79 @@ export type ArchivePlanOptions = Pick<ExtractArchiveOptions, "stripComponents" |
     rootDir?: string;
     escapeLabel?: string;
 };
+export declare function createArchiveEntrySelector(params: ArchivePlanOptions): {
+    limits: ResolvedArchiveExtractLimits;
+    select(entry: {
+        path: string;
+        kind: ArchiveEntryKind;
+        size: number;
+    }): string | null;
+};
 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
+export type ArchiveEntryKind = "file" | "directory" | "symlink" | "other";
+export type ArchiveEntryModePolicy = "clamp" | "preserve";
+export type ArchiveFilteredEntryPolicy = "reject-archive" | "skip-entry";
+export type ArchiveEntryFilter = (entry: {
+    /** Validated canonical archive path before stripping: / separators, no empty or . components. */
+    path: string;
+    kind: ArchiveEntryKind;
+    size: number;
+}) => "extract" | "skip";
+export declare function archiveEntryKindFromTarType(type: string): ArchiveEntryKind;
+export declare function resolveArchiveEntryMode(params: {
+    kind: "file" | "directory";
+    archivedMode?: number | null;
+    policy?: ArchiveEntryModePolicy;
+}): number;
+export declare function resolveArchiveFilteredEntryPolicy(value: unknown): ArchiveFilteredEntryPolicy;
+export declare function shouldExtractArchiveEntry(params: {
+    filter?: ArchiveEntryFilter;
+    onFiltered?: ArchiveFilteredEntryPolicy;
+    entry: Parameters<ArchiveEntryFilter>[0];
+}): boolean;
+export type TarEntryInfo = {
+    path: string;
+    type: string;
+    size: number;
+    mode?: number;
+};
+export declare function createTarEntryPlanner(params: ArchivePlanOptions): (entry: TarEntryInfo) => ArchivePlanEntry | null;
+export declare function createTarEntryPreflightChecker(params: {
+    rootDir: string;
+    stripComponents?: number;
+    limits?: ArchiveExtractLimits;
+    escapeLabel?: string;
+    entryFilter?: ArchiveEntryFilter;
+    onFiltered?: ArchiveFilteredEntryPolicy;
+}): (entry: TarEntryInfo) => boolean;
+export type ArchiveLogger = {
+    info?: (message: string) => void;
+    warn?: (message: string) => void;
+};
+export type ExtractArchiveOptions = {
+    archivePath: string;
+    destDir: string;
+    timeoutMs: number;
+    /** Sync published files and directories before returning. Defaults to false. */
+    durable?: boolean;
+    kind?: ArchiveKind;
+    stripComponents?: number;
+    tarGzip?: boolean;
+    limits?: ArchiveExtractLimits;
+    logger?: ArchiveLogger;
+    entryModes?: ArchiveEntryModePolicy;
+    /** Remove these rwx bits from final entry modes. Defaults to zero. */
+    entryUmask?: number;
+    entryFilter?: ArchiveEntryFilter;
+    onFiltered?: ArchiveFilteredEntryPolicy;
+};
+/** Private executors receive owned options and an already-staged archive path. */
+export type StagedArchiveExtractOptions = Pick<ExtractArchiveOptions, "archivePath" | "destDir" | "durable" | "stripComponents" | "entryModes" | "entryUmask" | "entryFilter" | "onFiltered"> & {
+    limits: ResolvedArchiveExtractLimits;
+    deadline: ExtractionDeadline;
+};

package/node_modules/@openclaw/fs-safe/dist/archive-plan.js

@@ -1,36 +1,45 @@
 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) {
+// Portable ZIP selects each entry immediately before streaming its payload;
+// manifest-backed routes add declared-byte admission through the planner below.
+export function createArchiveEntrySelector(params) {
     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 { limits, select(entry) {
+            assertArchiveEntryCountWithinLimit(++entryCount, limits);
+            validateArchiveEntryPath(entry.path, { escapeLabel: params.escapeLabel });
+            const canonicalPath = stripArchivePath(entry.path, 0);
+            if (!canonicalPath)
+                return null;
+            const relPath = strip === 0 ? canonicalPath : 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 });
+            }
+            if (!shouldExtractArchiveEntry({ filter: params.entryFilter, onFiltered: params.onFiltered,
+                entry: { path: canonicalPath, kind: entry.kind, size: entry.size } }))
+                return null;
+            return relPath;
+        } };
+}
+// A destination is optional only for inspection; writers still prove containment.
+export function createArchiveEntryPlanner(params, archiveKind) {
+    const { select, limits } = createArchiveEntrySelector(params);
+    const budget = createByteBudgetTracker(limits);
     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 } }))
+        const relPath = select({ path: entry.path, kind, size: entry.size });
+        if (relPath === null)
             return null;
         if (entry.kind === "sparse") {
             throw new ArchiveFormatError(`GNU sparse archive entry is not supported: ${formatErrorDetail(entry.path)}`);
@@ -53,3 +62,58 @@ export function createArchiveEntryPlanner(params, archiveKind) {
             mode: resolveArchiveEntryMode({ kind, archivedMode: entry.mode, policy: params.entryModes }) };
     };
 }
+export function archiveEntryKindFromTarType(type) {
+    if (type === "Directory" || type === "GNUDumpDir")
+        return "directory";
+    if (type === "File" || type === "OldFile" || type === "ContiguousFile")
+        return "file";
+    if (type === "SymbolicLink" || type === "Link")
+        return "symlink";
+    return "other";
+}
+export function resolveArchiveEntryMode(params) {
+    const archivedMode = (params.archivedMode ?? 0) & 0o777;
+    if (params.policy === "preserve") {
+        return params.archivedMode == null ? (params.kind === "directory" ? 0o755 : 0o644) : archivedMode;
+    }
+    if (params.kind === "directory") {
+        return 0o755;
+    }
+    return archivedMode & 0o100 ? 0o755 : 0o644;
+}
+export function resolveArchiveFilteredEntryPolicy(value) {
+    if (value === undefined || value === "reject-archive")
+        return "reject-archive";
+    if (value === "skip-entry")
+        return "skip-entry";
+    throw new RangeError('archive onFiltered must be "reject-archive" or "skip-entry"');
+}
+export function shouldExtractArchiveEntry(params) {
+    const onFiltered = resolveArchiveFilteredEntryPolicy(params.onFiltered);
+    if (!params.filter || params.filter(params.entry) === "extract") {
+        return true;
+    }
+    if (onFiltered === "reject-archive") {
+        throw new ArchiveSecurityError("entry-filtered", `archive entry rejected by filter: ${formatErrorDetail(params.entry.path)}`);
+    }
+    return false;
+}
+const BLOCKED_TAR_ENTRY_TYPES = new Set([
+    "BlockDevice",
+    "CharacterDevice",
+    "FIFO",
+    "Socket",
+]);
+export function createTarEntryPlanner(params) {
+    // Preserve inherited/getter-backed public options and per-entry policy reads.
+    const plan = createArchiveEntryPlanner(params, "tar");
+    return (entry) => {
+        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/node_modules/@openclaw/fs-safe/dist/archive-read.d.ts

@@ -3,4 +3,3 @@ export declare function readArchiveEntry(archivePath: string, entryPath: string,
     maxBytes: number;
     kind?: ArchiveKind;
 }): Promise<Buffer>;
-//# sourceMappingURL=archive-read.d.ts.map