@openclaw/openshell-sandbox 2026.9.1 → 2026.9.3

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

@@ -0,0 +1,157 @@
+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 {} from "./directory-mode-owner.js";
+import { pinNodeDirectoryForMode } from "./directory-mode-node.js";
+import { FsSafeError } from "./errors.js";
+import { formatErrorDetail } from "./error-detail.js";
+import { isPathInside } from "./path.js";
+import { root } from "./root.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+export async function mergePlannedArchiveIntoDestination(params) {
+    await mergeTree(params, params.entries);
+}
+export async function mergeExtractedTreeIntoDestination(params) {
+    await mergeTree(params);
+}
+async function mergeTree(params, publication) {
+    const check = () => params.deadline?.check();
+    check();
+    const destinationGuard = await createDirectoryIdentityGuard(params.destinationRealDir);
+    check();
+    const targetRoot = await root(params.destinationRealDir);
+    check();
+    const sourceGuard = await createDirectoryIdentityGuard(params.sourceDir);
+    check();
+    const plan = publication ? new Map() : undefined;
+    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));
+        check();
+        if (!isPathInside(sourceGuard.realPath, stagedPath) || plan.has(stagedPath)) {
+            throw new FsSafeError("path-mismatch", "archive publication paths changed in staging");
+        }
+        plan.set(stagedPath, entry);
+    }
+    const ancestors = [];
+    const assertGuards = async () => {
+        await assertDirectoryIdentityGuard(destinationGuard);
+        check();
+        for (const ancestor of ancestors) {
+            await assertDirectoryIdentityGuard(ancestor.guard);
+            check();
+            await ancestor.owner.verify(check);
+            check();
+        }
+        await assertDirectoryIdentityGuard(sourceGuard);
+        check();
+    };
+    const walk = async (sourceDir) => {
+        await assertGuards();
+        const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+        check();
+        for (const entry of entries) {
+            await assertGuards();
+            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);
+            check();
+            if (sourceStat.isSymbolicLink())
+                throw createArchiveSymlinkTraversalError(originalPath);
+            const sourceReal = await fs.realpath(sourcePath);
+            check();
+            if (!isPathInside(sourceGuard.realPath, sourceReal))
+                throw createArchiveSymlinkTraversalError(originalPath);
+            if (!sourceStat.isFile() && !sourceStat.isDirectory()) {
+                throw new Error(`archive staging contains unsupported entry: ${formatErrorDetail(originalPath)}`);
+            }
+            const kind = sourceStat.isDirectory() ? "directory" : "file";
+            const planned = plan?.get(sourceReal);
+            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;
+            await preparePrivateArchiveOutputPath({
+                ...params, relPath, outPath: destinationPath, originalPath, isDirectory: kind === "directory",
+            }, assertGuards);
+            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 });
+                        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();
+                                } });
+                            check();
+                            await assertGuards();
+                        }
+                        finally {
+                            if (ancestors.at(-1)?.owner === owner)
+                                ancestors.pop();
+                        }
+                    }
+                    finally {
+                        await owner.close();
+                    }
+                });
+            }
+            else {
+                await ownExtractionDestinationMutation(params.deadline, async () => {
+                    await assertGuards();
+                    try {
+                        await targetRoot.copyIn(relPath, sourcePath, { mkdir: true, mode });
+                        check();
+                        await assertGuards();
+                        await assertResolvedInsideDestination({
+                            destinationRealDir: params.destinationRealDir, targetPath: destinationPath, originalPath,
+                        });
+                        check();
+                        const stat = await fs.lstat(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.
+                        if (error instanceof FsSafeError && (error.code === "hardlink" || error.code === "path-alias")) {
+                            throw createArchiveSymlinkTraversalError(originalPath);
+                        }
+                        throw error;
+                    }
+                });
+            }
+        }
+    };
+    await walk(params.sourceDir);
+}

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

@@ -0,0 +1,20 @@
+import type { ExtractionDeadline } from "./archive-deadline.js";
+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;
+    destDir: string;
+    kind: ArchiveKind;
+    stripComponents?: number;
+    limits: ResolvedArchiveExtractLimits;
+    tarLimits: TarMeterLimits;
+    deadline: ExtractionDeadline;
+    entryModes?: ExtractArchiveOptions["entryModes"];
+    entryFilter?: ExtractArchiveOptions["entryFilter"];
+    onFiltered?: ExtractArchiveOptions["onFiltered"];
+}): Promise<void>;
+//# sourceMappingURL=archive-native.d.ts.map

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

@@ -0,0 +1 @@
+{"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/node_modules/@openclaw/fs-safe/dist/archive-native.js

@@ -0,0 +1,107 @@
+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 { stripArchivePath, validateArchiveEntryPath } from "./archive-entry.js";
+import { createArchiveEntryPlanner } from "./archive-plan.js";
+import { stageArchiveFileForExtraction } from "./archive-input.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";
+export function throwMappedNativeArchiveError(error) {
+    if (error instanceof Error) {
+        const mapped = classifyArchiveParserError(error.message, { cause: error });
+        if (mapped)
+            throw mapped;
+        if (isArchiveFormatErrorMessage(error.message)) {
+            throw new ArchiveFormatError(error.message, { cause: error });
+        }
+        if (error.code === "InvalidArg") {
+            throw new ArchiveFormatError(`invalid archive: ${error.message}`, { cause: error });
+        }
+    }
+    throw error;
+}
+export async function extractNativeArchive(params) {
+    const { limits, tarLimits } = params;
+    const stagedArchive = await stageArchiveFileForExtraction({
+        archivePath: params.archivePath,
+        limits,
+        deadline: params.deadline,
+    });
+    try {
+        const zipEntries = [];
+        const physicalCount = params.kind === "zip"
+            ? await admitZipFile(stagedArchive.path, limits, params.deadline, (entry) => { zipEntries.push(entry); })
+            : undefined;
+        const destinationRealDir = await prepareArchiveDestinationDir(params.destDir);
+        await withStagedArchiveDestination({
+            destinationRealDir,
+            run: async (stagingDir) => {
+                params.deadline.check();
+                const manifest = await params.binding
+                    .inspectArchiveNative(stagedArchive.path, params.kind, tarLimits, params.deadline.signal)
+                    .catch(throwMappedNativeArchiveError);
+                params.deadline.check();
+                assertArchiveEntryCountWithinLimit(manifest.length, limits);
+                if (physicalCount !== undefined && manifest.length !== physicalCount) {
+                    throw new ArchiveSecurityError("entry-path", "zip decoder collapsed entry names");
+                }
+                if (params.kind === "zip") {
+                    for (const [ordinal, entry] of manifest.entries()) {
+                        const physical = zipEntries[ordinal];
+                        // Native ZIP indices are physical central-directory ordinals. Legacy
+                        // filename decoding remains native-selected; compare names when known.
+                        if (!physical || physical.index !== ordinal || entry.index !== ordinal ||
+                            entry.size !== physical.size ||
+                            (physical.path !== undefined && stripArchivePath(entry.path, 0) !== stripArchivePath(physical.path, 0)) ||
+                            (physical.creatorSystem === 3 && entry.mode !== physical.externalAttributes >>> 16)) {
+                            throw new ArchiveFormatError("ZIP decoder disagrees with admitted directory metadata");
+                        }
+                    }
+                }
+                // Recheck the native manifest at the shared policy boundary before
+                // any caller callback observes an entry.
+                if (params.kind !== "zip") {
+                    for (const entry of manifest)
+                        validateArchiveEntryPath(entry.path);
+                }
+                const planEntry = createArchiveEntryPlanner({ ...params, rootDir: stagingDir }, params.kind);
+                const plan = [];
+                for (const entry of manifest) {
+                    params.deadline.check();
+                    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(throwMappedNativeArchiveError);
+                }
+                finally {
+                    await directory.close().catch(() => undefined);
+                }
+                params.deadline.check();
+                await mergePlannedArchiveIntoDestination({
+                    entries: plan,
+                    sourceDir: stagingDir,
+                    destinationDir: params.destDir,
+                    destinationRealDir,
+                    deadline: params.deadline,
+                });
+                params.deadline.check();
+            },
+        });
+    }
+    finally {
+        await stagedArchive.cleanup();
+    }
+}

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

@@ -0,0 +1,21 @@
+import type { ArchiveKind } from "./archive-kind.js";
+import type { ArchiveExtractLimits } from "./archive-limits.js";
+import type { ArchiveEntryFilter, ArchiveEntryModePolicy, ArchiveFilteredEntryPolicy } from "./archive-policy.js";
+export type ArchiveLogger = {
+    info?: (message: string) => void;
+    warn?: (message: string) => void;
+};
+export type ExtractArchiveOptions = {
+    archivePath: string;
+    destDir: string;
+    timeoutMs: number;
+    kind?: ArchiveKind;
+    stripComponents?: number;
+    tarGzip?: boolean;
+    limits?: ArchiveExtractLimits;
+    logger?: ArchiveLogger;
+    entryModes?: ArchiveEntryModePolicy;
+    entryFilter?: ArchiveEntryFilter;
+    onFiltered?: ArchiveFilteredEntryPolicy;
+};
+//# sourceMappingURL=archive-options.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-options.d.ts","sourceRoot":"","sources":["../src/archive-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,EACV,kBAAkB,EAClB,sBAAsB,EACtB,0BAA0B,EAC3B,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,UAAU,CAAC,EAAE,sBAAsB,CAAC;IACpC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,UAAU,CAAC,EAAE,0BAA0B,CAAC;CACzC,CAAC"}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,2 @@
+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-parser-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-parser-errors.d.ts","sourceRoot":"","sources":["../src/archive-parser-errors.ts"],"names":[],"mappings":"AAGA,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,KAAK,GAAG,SAAS,CAQrG"}

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

@@ -0,0 +1,12 @@
+import { ArchiveSecurityError, isArchiveTarPathErrorMessage } from "./archive-errors.js";
+import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError } from "./archive-limits.js";
+export function classifyArchiveParserError(message, options) {
+    if (isArchiveTarPathErrorMessage(message)) {
+        return new ArchiveSecurityError("entry-path", message, options);
+    }
+    for (const code of Object.values(ARCHIVE_LIMIT_ERROR_CODE)) {
+        if (message.includes(code))
+            return new ArchiveLimitError(code);
+    }
+    return undefined;
+}

package/node_modules/@openclaw/fs-safe/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/node_modules/@openclaw/fs-safe/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/node_modules/@openclaw/fs-safe/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/node_modules/@openclaw/fs-safe/dist/archive-policy.d.ts

@@ -0,0 +1,22 @@
+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;
+//# sourceMappingURL=archive-policy.d.ts.map

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

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

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

@@ -0,0 +1,38 @@
+import { ArchiveSecurityError } from "./archive-errors.js";
+import { formatErrorDetail } from "./error-detail.js";
+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;
+}

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

@@ -0,0 +1,6 @@
+import { type ArchiveKind } from "./archive-kind.js";
+export declare function readArchiveEntry(archivePath: string, entryPath: string, options: {
+    maxBytes: number;
+    kind?: ArchiveKind;
+}): Promise<Buffer>;
+//# sourceMappingURL=archive-read.d.ts.map

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

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