@openclaw/matrix 2026.9.6 → 2026.9.7

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

@@ -0,0 +1,56 @@
+import { Transform } from "node:stream";
+export type ArchiveExtractLimits = {
+    /**
+     * Max archive file bytes (compressed).
+     */
+    maxArchiveBytes?: number;
+    /** Max logical archive entries, including skipped/stripped members. */
+    maxEntries?: number;
+    /** Max extracted bytes across entries accepted after strip/filter policy. */
+    maxExtractedBytes?: number;
+    /** Max bytes in an entry accepted after strip/filter policy. */
+    maxEntryBytes?: number;
+    /** Max bytes in one PAX, GNU long-name, or related TAR metadata entry. */
+    maxMetaEntryBytes?: number;
+    /** Max path components in one extracted entry after stripComponents. */
+    maxEntryPathComponents?: number;
+};
+export declare const DEFAULT_MAX_ARCHIVE_BYTES_ZIP: number;
+export declare const DEFAULT_MAX_ENTRIES = 50000;
+export declare const DEFAULT_MAX_EXTRACTED_BYTES: number;
+export declare const DEFAULT_MAX_ENTRY_BYTES: number;
+export declare const DEFAULT_MAX_META_ENTRY_BYTES: number;
+export declare const DEFAULT_MAX_ENTRY_PATH_COMPONENTS = 256;
+export declare const ARCHIVE_LIMIT_ERROR_CODE: {
+    readonly ARCHIVE_SIZE_EXCEEDS_LIMIT: "archive-size-exceeds-limit";
+    readonly ENTRY_COUNT_EXCEEDS_LIMIT: "archive-entry-count-exceeds-limit";
+    readonly ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT: "archive-entry-extracted-size-exceeds-limit";
+    readonly EXTRACTED_SIZE_EXCEEDS_LIMIT: "archive-extracted-size-exceeds-limit";
+    readonly DECODED_SIZE_EXCEEDS_LIMIT: "archive-decoded-size-exceeds-limit";
+    readonly META_ENTRY_SIZE_EXCEEDS_LIMIT: "archive-meta-entry-size-exceeds-limit";
+    readonly MANIFEST_SIZE_EXCEEDS_LIMIT: "archive-manifest-size-exceeds-limit";
+    readonly ENTRY_PATH_COMPONENTS_EXCEEDS_LIMIT: "archive-entry-path-components-exceeds-limit";
+};
+export type ArchiveLimitErrorCode = (typeof ARCHIVE_LIMIT_ERROR_CODE)[keyof typeof ARCHIVE_LIMIT_ERROR_CODE];
+export declare class ArchiveLimitError extends Error {
+    readonly code: ArchiveLimitErrorCode;
+    constructor(code: ArchiveLimitErrorCode);
+}
+export type ResolvedArchiveExtractLimits = Required<ArchiveExtractLimits>;
+export type TarMeterLimits = Pick<ResolvedArchiveExtractLimits, "maxEntries" | "maxMetaEntryBytes"> & {
+    maxDecodedBytes: number;
+    maxManifestBytes: number;
+};
+export declare const MAX_TAR_MANIFEST_BYTES: number;
+export declare function resolveTarMeterLimits(options?: ArchiveExtractLimits): TarMeterLimits;
+export declare function resolveExtractLimits(limits?: ArchiveExtractLimits): ResolvedArchiveExtractLimits;
+export declare function assertArchiveEntryPathComponentsWithinLimit(entryPath: string, limits: ResolvedArchiveExtractLimits): void;
+export declare function assertArchiveEntryCountWithinLimit(entryCount: number, limits: ResolvedArchiveExtractLimits): void;
+export declare function createByteBudgetTracker(limits: ResolvedArchiveExtractLimits): {
+    startEntry: () => void;
+    addBytes: (bytes: number) => void;
+    addEntrySize: (size: number) => void;
+};
+export declare function createExtractBudgetTransform(params: {
+    onChunkBytes: (bytes: number) => void;
+}): Transform;

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

@@ -0,0 +1,131 @@
+import { Transform } from "node:stream";
+export const DEFAULT_MAX_ARCHIVE_BYTES_ZIP = 256 * 1024 * 1024;
+export const DEFAULT_MAX_ENTRIES = 50_000;
+export const DEFAULT_MAX_EXTRACTED_BYTES = 512 * 1024 * 1024;
+export const DEFAULT_MAX_ENTRY_BYTES = 256 * 1024 * 1024;
+export const DEFAULT_MAX_META_ENTRY_BYTES = 1024 * 1024;
+export const DEFAULT_MAX_ENTRY_PATH_COMPONENTS = 256;
+export const ARCHIVE_LIMIT_ERROR_CODE = {
+    ARCHIVE_SIZE_EXCEEDS_LIMIT: "archive-size-exceeds-limit",
+    ENTRY_COUNT_EXCEEDS_LIMIT: "archive-entry-count-exceeds-limit",
+    ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT: "archive-entry-extracted-size-exceeds-limit",
+    EXTRACTED_SIZE_EXCEEDS_LIMIT: "archive-extracted-size-exceeds-limit",
+    DECODED_SIZE_EXCEEDS_LIMIT: "archive-decoded-size-exceeds-limit",
+    META_ENTRY_SIZE_EXCEEDS_LIMIT: "archive-meta-entry-size-exceeds-limit",
+    MANIFEST_SIZE_EXCEEDS_LIMIT: "archive-manifest-size-exceeds-limit",
+    ENTRY_PATH_COMPONENTS_EXCEEDS_LIMIT: "archive-entry-path-components-exceeds-limit",
+};
+const ARCHIVE_LIMIT_ERROR_MESSAGE = {
+    [ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT]: "archive size exceeds limit",
+    [ARCHIVE_LIMIT_ERROR_CODE.ENTRY_COUNT_EXCEEDS_LIMIT]: "archive entry count exceeds limit",
+    [ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT]: "archive entry extracted size exceeds limit",
+    [ARCHIVE_LIMIT_ERROR_CODE.EXTRACTED_SIZE_EXCEEDS_LIMIT]: "archive extracted size exceeds limit",
+    [ARCHIVE_LIMIT_ERROR_CODE.DECODED_SIZE_EXCEEDS_LIMIT]: "archive decoded size exceeds limit",
+    [ARCHIVE_LIMIT_ERROR_CODE.META_ENTRY_SIZE_EXCEEDS_LIMIT]: "archive metadata entry size exceeds limit",
+    [ARCHIVE_LIMIT_ERROR_CODE.MANIFEST_SIZE_EXCEEDS_LIMIT]: "archive manifest size exceeds limit",
+    [ARCHIVE_LIMIT_ERROR_CODE.ENTRY_PATH_COMPONENTS_EXCEEDS_LIMIT]: "archive entry path components exceed limit",
+};
+export class ArchiveLimitError extends Error {
+    code;
+    constructor(code) {
+        super(ARCHIVE_LIMIT_ERROR_MESSAGE[code]);
+        this.name = "ArchiveLimitError";
+        this.code = code;
+    }
+}
+export const MAX_TAR_MANIFEST_BYTES = 64 * 1024 * 1024;
+export function resolveTarMeterLimits(options) {
+    const limits = resolveExtractLimits(options);
+    const payload = Math.min(limits.maxExtractedBytes, Number.MAX_SAFE_INTEGER);
+    const overhead = Math.min(limits.maxArchiveBytes, Number.MAX_SAFE_INTEGER);
+    // Saturate before multiplying, including when public limits approach MAX_VALUE.
+    const pathBytes = Math.max(256, Math.min(limits.maxMetaEntryBytes, Math.min(Math.max(1, limits.maxEntryPathComponents), MAX_TAR_MANIFEST_BYTES / 256) * 256));
+    const perEntry = 64 + 2 * pathBytes;
+    const maxManifestBytes = limits.maxEntries > Math.floor(MAX_TAR_MANIFEST_BYTES / perEntry)
+        ? MAX_TAR_MANIFEST_BYTES : limits.maxEntries * perEntry;
+    // TAR sizes are safe integers; native logical entry counts use u32.
+    return {
+        maxEntries: Math.min(limits.maxEntries, 0xffff_ffff),
+        maxMetaEntryBytes: Math.min(limits.maxMetaEntryBytes, Number.MAX_SAFE_INTEGER),
+        maxManifestBytes,
+        maxDecodedBytes: payload > Number.MAX_SAFE_INTEGER - overhead
+            ? Number.MAX_SAFE_INTEGER : payload + overhead,
+    };
+}
+function clampLimit(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return undefined;
+    }
+    const v = Math.floor(value);
+    return v >= 0 ? v : undefined;
+}
+export function resolveExtractLimits(limits) {
+    // Defaults: defensive, but should not break normal installs.
+    return {
+        maxArchiveBytes: clampLimit(limits?.maxArchiveBytes) ?? DEFAULT_MAX_ARCHIVE_BYTES_ZIP,
+        maxEntries: clampLimit(limits?.maxEntries) ?? DEFAULT_MAX_ENTRIES,
+        maxExtractedBytes: clampLimit(limits?.maxExtractedBytes) ?? DEFAULT_MAX_EXTRACTED_BYTES,
+        maxEntryBytes: clampLimit(limits?.maxEntryBytes) ?? DEFAULT_MAX_ENTRY_BYTES,
+        maxMetaEntryBytes: clampLimit(limits?.maxMetaEntryBytes) ?? DEFAULT_MAX_META_ENTRY_BYTES,
+        maxEntryPathComponents: clampLimit(limits?.maxEntryPathComponents) ?? DEFAULT_MAX_ENTRY_PATH_COMPONENTS,
+    };
+}
+export function assertArchiveEntryPathComponentsWithinLimit(entryPath, limits) {
+    const components = entryPath
+        .split(/[\\/]+/u)
+        .filter((component) => component.length > 0 && component !== ".").length;
+    if (components > limits.maxEntryPathComponents) {
+        throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_PATH_COMPONENTS_EXCEEDS_LIMIT);
+    }
+}
+export function assertArchiveEntryCountWithinLimit(entryCount, limits) {
+    if (entryCount > limits.maxEntries) {
+        throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_COUNT_EXCEEDS_LIMIT);
+    }
+}
+export function createByteBudgetTracker(limits) {
+    let entryBytes = 0;
+    let extractedBytes = 0;
+    const addBytes = (bytes) => {
+        const b = Math.max(0, Math.floor(bytes));
+        if (b === 0) {
+            return;
+        }
+        entryBytes += b;
+        if (entryBytes > limits.maxEntryBytes) {
+            throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
+        }
+        extractedBytes += b;
+        if (extractedBytes > limits.maxExtractedBytes) {
+            throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.EXTRACTED_SIZE_EXCEEDS_LIMIT);
+        }
+    };
+    return {
+        startEntry() {
+            entryBytes = 0;
+        },
+        addBytes,
+        addEntrySize(size) {
+            const s = Math.max(0, Math.floor(size));
+            if (s > limits.maxEntryBytes) {
+                throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
+            }
+            // Tar budgets are based on the header-declared size.
+            addBytes(s);
+        },
+    };
+}
+export function createExtractBudgetTransform(params) {
+    return new Transform({
+        transform(chunk, _encoding, callback) {
+            try {
+                const buf = chunk instanceof Buffer ? chunk : Buffer.from(chunk);
+                params.onChunkBytes(buf.byteLength);
+                callback(null, buf);
+            }
+            catch (err) {
+                callback(err instanceof Error ? err : new Error(String(err)));
+            }
+        },
+    });
+}

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

@@ -0,0 +1,22 @@
+import { type ExtractionDeadline } from "./archive-deadline.js";
+import { type ArchiveDirectoryGuard } from "./archive-staging.js";
+export type ArchivePublicationEntry = {
+    path: string;
+    kind: "file" | "directory";
+    mode: number;
+};
+type MergeParams = {
+    sourceDir: string;
+    destinationDir: string;
+    destinationRealDir: string;
+    deadline?: ExtractionDeadline;
+};
+type GuardedMergeParams = Pick<MergeParams, "sourceDir" | "deadline"> & {
+    destinationGuard: ArchiveDirectoryGuard;
+};
+export declare function withStagedArchivePublication(params: Omit<GuardedMergeParams, "sourceDir"> & {
+    durable?: boolean;
+    entryUmask?: number;
+}, extract: (stagingDir: string) => Promise<readonly ArchivePublicationEntry[]>): Promise<void>;
+export declare function mergeExtractedTreeIntoDestination(params: MergeParams): Promise<void>;
+export {};

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

@@ -0,0 +1,282 @@
+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, withStagedArchiveDestination, } from "./archive-staging.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 { 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";
+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) {
+    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 });
+}
+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 } = params;
+    const destinationDir = destinationGuard.dir;
+    const destinationRealDir = destinationGuard.realPath;
+    const targetRoot = rootFromDirectoryGuard(destinationGuard);
+    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 = 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");
+        }
+        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();
+        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();
+        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(destinationDir, relPath);
+            const sourceStat = inspectFileIdentitySync(() => fsSync.lstatSync(sourcePath, { bigint: true }));
+            check();
+            if (sourceStat.isSymbolicLink())
+                throw createArchiveSymlinkTraversalError(originalPath);
+            const sourceReal = realpathSync.native(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");
+            }
+            let mode = plan ? (planned?.mode ?? 0o755) & ~entryUmask : Number(sourceStat.mode & 511n);
+            await preparePrivateArchiveOutputPath({
+                destinationDir, destinationRealDir, deadline: params.deadline,
+                relPath, outPath: destinationPath, originalPath, isDirectory: kind === "directory",
+            }, assertGuards, destinationGuard);
+            check();
+            if (kind === "directory") {
+                // 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 {
+                            check();
+                            const guard = await createDirectoryIdentityGuard(destinationPath);
+                            check();
+                            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 {
+                            await owner.close();
+                        }
+                    });
+                }
+                finally {
+                    sourceAncestors.pop();
+                }
+            }
+            else {
+                await ownExtractionDestinationMutation(params.deadline, async () => {
+                    await assertGuards();
+                    try {
+                        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, targetPath: destinationPath, originalPath,
+                        });
+                        check();
+                        const stat = fsSync.lstatSync(destinationPath);
+                        check();
+                        if (stat.isSymbolicLink() || (stat.isFile() && stat.nlink > 1)) {
+                            throw createArchiveSymlinkTraversalError(originalPath);
+                        }
+                    }
+                    catch (error) {
+                        // copyIn cleans unpublished stages; merge never gains rollback authority.
+                        if (error instanceof FsSafeError && (error.code === "hardlink" || error.code === "path-alias")) {
+                            throw createArchiveSymlinkTraversalError(originalPath);
+                        }
+                        throw error;
+                    }
+                });
+            }
+        }
+    };
+    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

@@ -0,0 +1 @@
+export declare function classifyArchiveParserError(message: string, options?: ErrorOptions): Error | undefined;

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,85 @@
+import type { ArchiveKind } from "./archive-kind.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;
+    kind: "file" | "directory";
+    size: number;
+    mode: number;
+};
+export type ArchivePlanOptions = Pick<ExtractArchiveOptions, "stripComponents" | "limits" | "entryModes" | "entryFilter" | "onFiltered"> & {
+    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;
+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: Omit<ArchivePlanOptions & {
+    rootDir: string;
+}, "entryModes">): (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;
+};