@openclaw/signal 2026.9.5 → 2026.9.6

package/node_modules/@openclaw/fs-safe/SECURITY.md

@@ -0,0 +1,45 @@
+# Security Policy
+
+If you believe you found a security issue in `@openclaw/fs-safe`, report it
+privately.
+
+## Reporting
+
+Open a private report through
+[GitHub Security Advisories](https://github.com/openclaw/fs-safe/security/advisories/new)
+or email `security@openclaw.ai`.
+
+Include:
+
+1. affected version or commit
+2. Node.js version, operating system, filesystem, and mount details
+3. minimal reproduction
+4. demonstrated impact
+5. suggested remediation, if known
+
+Do not open a public issue until maintainers have coordinated disclosure.
+
+## Scope
+
+Security issues in scope generally include:
+
+- traversal or root-confinement bypasses
+- symlink, hardlink, rename, or identity-swap races that cross a documented
+  filesystem boundary
+- archive extraction outside the intended destination
+- unsafe secret-file, permission, ownership, or temporary-file behavior
+- package or release-pipeline compromise affecting the published package
+
+Reports must demonstrate a concrete boundary bypass or impact. Applications
+remain responsible for operating-system isolation, authorization, and choosing
+trusted root directories unless this package documents and fails to enforce a
+specific invariant.
+
+## Operational Guidance
+
+- Keep `@openclaw/fs-safe`, Node.js, and optional archive dependencies current.
+- Treat pathnames and archive contents as untrusted.
+- Use OS-level sandboxing when the threat model includes a hostile process.
+- Pin and review dependency updates before publishing.
+
+There is currently no paid bug bounty program.

package/node_modules/@openclaw/fs-safe/dist/absolute-path.d.ts

@@ -0,0 +1,32 @@
+import { FsSafeError, type FsSafeErrorCode } from "./errors.js";
+export type AbsolutePathSymlinkPolicy = "reject" | "follow";
+export type ResolvedAbsolutePath = {
+    path: string;
+    canonicalPath: string;
+};
+export type ResolvedWritableAbsolutePath = ResolvedAbsolutePath & {
+    parentDir: string;
+    parentExists: boolean;
+};
+export type EnsureAbsoluteDirectoryOptions = {
+    scopeLabel?: string;
+    mode?: number;
+};
+export type EnsureAbsoluteDirectoryResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    code: FsSafeErrorCode;
+    error: FsSafeError;
+};
+export declare function assertAbsolutePathInput(filePath: string): string;
+export declare function findExistingAncestor(filePath: string): Promise<string | null>;
+export declare function ensureAbsoluteDirectory(dirPath: string, options?: EnsureAbsoluteDirectoryOptions): Promise<EnsureAbsoluteDirectoryResult>;
+export declare function canonicalPathFromExistingAncestor(filePath: string): Promise<string>;
+export declare function resolveAbsolutePathForRead(filePath: string, options?: {
+    symlinks?: AbsolutePathSymlinkPolicy;
+}): Promise<ResolvedAbsolutePath>;
+export declare function resolveAbsolutePathForWrite(filePath: string, options?: {
+    symlinks?: AbsolutePathSymlinkPolicy;
+}): Promise<ResolvedWritableAbsolutePath>;

package/node_modules/@openclaw/fs-safe/dist/absolute-path.js

@@ -0,0 +1,323 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { pathExists } from "./fs.js";
+import { realpathSync } from "./realpath.js";
+import { resolveRootPath } from "./root-path.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function resolveSymlinkPolicy(policy) {
+    if (policy === undefined)
+        return "reject";
+    if (policy !== "reject" && policy !== "follow") {
+        throw new TypeError(`invalid absolute path symlink policy: ${String(policy)}`);
+    }
+    return policy;
+}
+function ensureDirectoryFailure(code, message, cause) {
+    return {
+        ok: false,
+        code,
+        error: new FsSafeError(code, message, { cause }),
+    };
+}
+async function assertGuardResult(guard, scopeLabel) {
+    try {
+        await assertAsyncDirectoryGuard(guard);
+        return { ok: true };
+    }
+    catch (err) {
+        if (err instanceof FsSafeError) {
+            return await directoryGuardFailure(err, guard.dir, scopeLabel);
+        }
+        throw err;
+    }
+}
+async function createDirectoryGuardResult(dir, scopeLabel) {
+    try {
+        return { ok: true, guard: await createAsyncDirectoryGuard(dir) };
+    }
+    catch (err) {
+        if (err instanceof FsSafeError) {
+            return await directoryGuardFailure(err, dir, scopeLabel);
+        }
+        throw err;
+    }
+}
+function classifyDirectoryLookupError(err, scopeLabel) {
+    const code = err.code;
+    if (code === "ENOENT") {
+        return ensureDirectoryFailure("not-found", `directory path must have a real existing ancestor within ${scopeLabel}`, err);
+    }
+    if (code === "ENOTDIR") {
+        return ensureDirectoryFailure("not-file", `path must be a real directory within ${scopeLabel}`, err);
+    }
+    return null;
+}
+function classifyExistingDirectorySegment(stat, scopeLabel) {
+    if (stat.isSymbolicLink()) {
+        return ensureDirectoryFailure("symlink", `directory path traverses a symlink within ${scopeLabel}`);
+    }
+    if (!stat.isDirectory()) {
+        return ensureDirectoryFailure("not-file", `path must be a real directory within ${scopeLabel}`);
+    }
+    return null;
+}
+async function directoryGuardFailure(err, dir, scopeLabel) {
+    if (err.code !== "not-file") {
+        return { ok: false, code: err.code, error: err };
+    }
+    try {
+        const stat = fsSync.lstatSync(pathForWindowsFilesystem(dir));
+        const failure = classifyExistingDirectorySegment(stat, scopeLabel);
+        if (failure) {
+            return failure;
+        }
+    }
+    catch (lookupErr) {
+        const failure = classifyDirectoryLookupError(lookupErr, scopeLabel);
+        if (failure) {
+            return failure;
+        }
+        throw lookupErr;
+    }
+    return { ok: false, code: err.code, error: err };
+}
+async function resolveTrustedDirectoryPrefix(targetPath, scopeLabel) {
+    const root = path.parse(targetPath).root;
+    let current = root;
+    let currentStat;
+    try {
+        currentStat = fsSync.lstatSync(pathForWindowsFilesystem(current));
+    }
+    catch (err) {
+        const failure = classifyDirectoryLookupError(err, scopeLabel);
+        if (failure) {
+            return failure;
+        }
+        throw err;
+    }
+    const rootFailure = classifyExistingDirectorySegment(currentStat, scopeLabel);
+    if (rootFailure) {
+        return rootFailure;
+    }
+    // Walk forward with lstat. Looking backward for the "nearest existing
+    // ancestor" can cross an existing suffix through a symlinked parent before
+    // this helper gets a chance to reject that parent.
+    const segments = path.relative(root, targetPath).split(path.sep).filter(Boolean);
+    for (let index = 0; index < segments.length; index += 1) {
+        const segment = segments[index];
+        if (!segment) {
+            continue;
+        }
+        const next = path.join(current, segment);
+        try {
+            const nextStat = fsSync.lstatSync(pathForWindowsFilesystem(next));
+            const segmentFailure = classifyExistingDirectorySegment(nextStat, scopeLabel);
+            if (segmentFailure) {
+                return segmentFailure;
+            }
+            current = next;
+            currentStat = nextStat;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "ENOENT") {
+                return {
+                    ok: true,
+                    ancestorPath: current,
+                    missingSegments: segments.slice(index),
+                };
+            }
+            const failure = classifyDirectoryLookupError(err, scopeLabel);
+            if (failure) {
+                return failure;
+            }
+            throw err;
+        }
+    }
+    return { ok: true, ancestorPath: current, missingSegments: [] };
+}
+export function assertAbsolutePathInput(filePath) {
+    if (!filePath) {
+        throw new FsSafeError("invalid-path", "path is required");
+    }
+    if (filePath.includes("\0")) {
+        throw new FsSafeError("invalid-path", "path must not contain NUL bytes");
+    }
+    assertNoWindowsPathAlias(filePath);
+    if (!path.isAbsolute(filePath)) {
+        throw new FsSafeError("invalid-path", "path must be absolute");
+    }
+    const normalized = path.normalize(filePath);
+    assertNoWindowsPathAlias(normalized);
+    return normalized;
+}
+export async function findExistingAncestor(filePath) {
+    assertNoWindowsPathAlias(filePath);
+    let current = resolvePathPreservingWindowsRoot(filePath);
+    assertNoWindowsPathAlias(current);
+    while (true) {
+        try {
+            fsSync.lstatSync(pathForWindowsFilesystem(current));
+            return current;
+        }
+        catch (err) {
+            if (err.code !== "ENOENT") {
+                throw err;
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+export async function ensureAbsoluteDirectory(dirPath, options = {}) {
+    const scopeLabel = options.scopeLabel ?? "directory";
+    let targetPath;
+    try {
+        targetPath = assertAbsolutePathInput(dirPath);
+    }
+    catch (err) {
+        if (err instanceof FsSafeError) {
+            return { ok: false, code: err.code, error: err };
+        }
+        throw err;
+    }
+    const prefix = await resolveTrustedDirectoryPrefix(targetPath, scopeLabel);
+    if (!prefix.ok) {
+        return prefix;
+    }
+    let current = prefix.ancestorPath;
+    const initialGuard = await createDirectoryGuardResult(prefix.ancestorPath, scopeLabel);
+    if (!initialGuard.ok) {
+        return initialGuard;
+    }
+    let currentGuard = initialGuard.guard;
+    for (const segment of prefix.missingSegments) {
+        current = path.join(current, segment);
+        while (true) {
+            const guardResult = await assertGuardResult(currentGuard, scopeLabel);
+            if (!guardResult.ok) {
+                return guardResult;
+            }
+            try {
+                const stat = fsSync.lstatSync(current);
+                if (stat.isSymbolicLink()) {
+                    return ensureDirectoryFailure("symlink", `directory path traverses a symlink within ${scopeLabel}`);
+                }
+                if (!stat.isDirectory()) {
+                    return ensureDirectoryFailure("not-file", `path must be a real directory within ${scopeLabel}`);
+                }
+                break;
+            }
+            catch (err) {
+                if (err.code !== "ENOENT") {
+                    throw err;
+                }
+                const parentStillValid = await assertGuardResult(currentGuard, scopeLabel);
+                if (!parentStillValid.ok) {
+                    return parentStillValid;
+                }
+                try {
+                    await fs.mkdir(current, { mode: options.mode });
+                }
+                catch (mkdirErr) {
+                    if (mkdirErr.code === "EEXIST") {
+                        continue;
+                    }
+                    throw mkdirErr;
+                }
+            }
+        }
+        const nextGuard = await createDirectoryGuardResult(current, scopeLabel);
+        if (!nextGuard.ok) {
+            return nextGuard;
+        }
+        const previousGuardStillValid = await assertGuardResult(currentGuard, scopeLabel);
+        if (!previousGuardStillValid.ok) {
+            return previousGuardStillValid;
+        }
+        currentGuard = nextGuard.guard;
+    }
+    const finalGuardResult = await assertGuardResult(currentGuard, scopeLabel);
+    if (!finalGuardResult.ok) {
+        return finalGuardResult;
+    }
+    return { ok: true, path: targetPath };
+}
+export async function canonicalPathFromExistingAncestor(filePath) {
+    assertNoWindowsPathAlias(filePath);
+    const ancestor = await findExistingAncestor(filePath);
+    if (!ancestor) {
+        const resolved = resolvePathPreservingWindowsRoot(filePath);
+        assertNoWindowsPathAlias(resolved);
+        return resolved;
+    }
+    let canonicalAncestor = ancestor;
+    let resolvedAncestor;
+    try {
+        resolvedAncestor = realpathSync.native(pathForWindowsFilesystem(ancestor));
+    }
+    catch {
+        // Keep lexical path when the existing ancestor cannot be canonicalized.
+    }
+    if (resolvedAncestor !== undefined) {
+        assertNoWindowsPathAlias(resolvedAncestor);
+        canonicalAncestor = resolvedAncestor;
+    }
+    const relative = path.relative(ancestor, filePath);
+    const canonicalPath = relative ? path.join(canonicalAncestor, relative) : canonicalAncestor;
+    assertNoWindowsPathAlias(canonicalPath);
+    return canonicalPath;
+}
+export async function resolveAbsolutePathForRead(filePath, options = {}) {
+    const symlinks = resolveSymlinkPolicy(options.symlinks);
+    const normalized = assertAbsolutePathInput(filePath);
+    let canonicalPath;
+    try {
+        canonicalPath = realpathSync.native(pathForWindowsFilesystem(normalized));
+        assertNoWindowsPathAlias(canonicalPath);
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new FsSafeError("not-found", "path not found", { cause: err });
+        }
+        throw err;
+    }
+    if (symlinks === "reject" && canonicalPath !== normalized) {
+        throw new FsSafeError("symlink", "path traverses a symlink", { cause: { canonicalPath } });
+    }
+    return { path: normalized, canonicalPath };
+}
+export async function resolveAbsolutePathForWrite(filePath, options = {}) {
+    const symlinks = resolveSymlinkPolicy(options.symlinks);
+    const normalized = assertAbsolutePathInput(filePath);
+    const parentDir = path.dirname(normalized);
+    const parentExists = await pathExists(pathForWindowsFilesystem(parentDir));
+    if (symlinks === "reject") {
+        const filesystemRoot = path.parse(normalized).root;
+        await resolveRootPath({
+            absolutePath: normalized,
+            rootPath: filesystemRoot,
+            rootCanonicalPath: filesystemRoot,
+            boundaryLabel: "absolute path",
+            rejectSymlinks: true,
+        });
+    }
+    const canonicalPath = await canonicalPathFromExistingAncestor(normalized);
+    if (symlinks === "reject" && canonicalPath !== normalized) {
+        throw new FsSafeError("symlink", "path traverses a symlink", {
+            cause: { canonicalPath },
+        });
+    }
+    return {
+        path: normalized,
+        canonicalPath,
+        parentDir,
+        parentExists,
+    };
+}

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

@@ -0,0 +1,36 @@
+export { createAsyncLock } from "./async-lock.js";
+export { createDirectory, createDirectorySync, createFileSync, type CreateDirectoryOptions, type CreateFileOptions, type OwnedFileDescriptorSync, } from "./create.js";
+export { copyFileHandle, copyFileDescriptorSync, type CopyFileHandleOptions } from "./file-handle-transfer.js";
+export { sameFileContentsSync, type SameFileContentsOptions } from "./file-contents.js";
+export { overwriteFileHandle, type OverwriteFileHandleOptions } from "./overwrite-file-handle.js";
+export { probePathCaseInsensitiveSync, type ProbePathCaseOptions } from "./path-case.js";
+export { resolvePathPrefixSync, type ResolvedPathPrefix } from "./path-prefix.js";
+export { probePathSuffixAliasesSync, type ProbePathSuffixAliasesOptions } from "./path-suffix-aliases.js";
+export { readDirectoryIdentity, assertDirectoryIdentitySync, type DirectoryIdentity, } from "./directory-guard.js";
+export { stageFileInDirectory, } from "./native-staged-file.js";
+export type { StagedFile, StagedFileReceipt, PublishedFileReceipt, StagedFilePublication, StagedFileCleanupReceipt, StagedFileFailureDetails, } from "./staged-file-types.js";
+export { readFileDescriptorBounded, readFileDescriptorBoundedSync, readFileHandleBounded, } from "./bounded-read.js";
+export { readFileWindowFully, readFileWindowFullySync, type ReadFileWindowOptions, } from "./positional-read.js";
+export { writeFileWindowFully, type WriteFileWindowOptions } from "./write-file-handle.js";
+export { assertNoUnsafeDeviceReadPath, isUnsafeDeviceReadPath, matchUnsafeDeviceReadPath, type UnsafeDeviceReadPathMatch, type UnsafeDeviceReadPathOptions, type UnsafeDeviceReadPathReason, } from "./device-path.js";
+export { assertAbsolutePathInput, canonicalPathFromExistingAncestor, ensureAbsoluteDirectory, findExistingAncestor, resolveAbsolutePathForRead, resolveAbsolutePathForWrite, type AbsolutePathSymlinkPolicy, type EnsureAbsoluteDirectoryOptions, type EnsureAbsoluteDirectoryResult, type ResolvedAbsolutePath, type ResolvedWritableAbsolutePath, } from "./absolute-path.js";
+export { sameFileIdentity, type FileIdentityStat } from "./file-identity.js";
+export { sanitizeUntrustedFileName } from "./filename.js";
+export { pathExists, pathExistsSync } from "./fs.js";
+export { resolveLocalPathFromRootsSync, readLocalFileFromRoots, type LocalRootsInputOptions, type LocalRootsPathResult, type LocalRootsReadResult, type ReadLocalFileFromRootsOptions, type ResolveLocalPathFromRootsSyncOptions, } from "./local-roots.js";
+export { assertNoWindowsNetworkPath, basenameFromMediaSource, hasEncodedFileUrlSeparator, isWindowsDriveLetterPath, isWindowsNetworkPath, safeFileURLToPath, trySafeFileURLToPath, } from "./local-file-access.js";
+export { formatPosixMode } from "./permissions.js";
+export { configureFsSafeLocks, getFsSafeLockConfig, type FsSafeLockConfig, } from "./lock-config.js";
+export { assertNoHardlinkedFinalPath, assertNoPathAliasEscape, PATH_ALIAS_POLICIES, type PathAliasPolicy, } from "./path-policy.js";
+export { openRootFile, openRootFileSync, canUseRootFileOpen, matchRootFileOpenFailure, type OpenRootFileParams, type OpenRootFileSyncParams, type RootFileOpenFailure, type RootFileOpenFailureReason, type RootFileOpenResult, } from "./root-file.js";
+export { ROOT_PATH_ALIAS_POLICIES, resolvePathViaExistingAncestorSync, resolveRootPath, resolveRootPathSync, type ResolvedRootPath, type RootPathAliasPolicy, } from "./root-path.js";
+export { ensureDirectoryWithinRoot, pathScope, resolveExistingPathsWithinRoot, resolvePathWithinRoot, resolvePathsWithinRoot, resolveStrictExistingPathsWithinRoot, resolveWritablePathWithinRoot, type PathScope, type PathScopeOptions, type PathScopeResolveOptions, } from "./root-paths.js";
+export { safeDirName, safePathSegmentHashed, safePathSegmentHashedV2, resolveSafeInstallDir, assertCanonicalPathWithinBase, } from "./install-path.js";
+export { assertNoSymlinkParents, assertNoSymlinkParentsSync, type AssertNoSymlinkParentsOptions, } from "./symlink-parents.js";
+export { movePathToTrash, type MovePathToTrashOptions } from "./trash.js";
+export { withTimeout } from "./timing.js";
+export { resolveHomeRelativePath } from "./home-dir.js";
+export { appendRegularFile, appendRegularFileSync, readRegularFile, readRegularFileSync, resolveRegularFileAppendFlags, statRegularFile, statRegularFileSync, type AppendRegularFileOptions, type RegularFileStatResult, } from "./regular-file.js";
+export { buildRandomTempFilePath, sanitizeTempFileName, type TempFile, tempFile, withTempFile, } from "./temp-target.js";
+export { writeSiblingTempFile, writeViaSiblingTempPath, type WriteSiblingTempFileOptions, type WriteSiblingTempFileResult, } from "./sibling-temp.js";
+export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, type IcaclsResetCommandOptions, type PermissionCommandFailure, type PermissionExec, type WindowsAclEntry, type WindowsAclSummary, } from "./permissions.js";

package/node_modules/@openclaw/fs-safe/dist/advanced.js

@@ -0,0 +1,38 @@
+// Advanced composition surface. These exports are less stable than the focused
+// public subpaths; prefer root/json/store/temp/archive unless you are building a
+// higher-level primitive.
+export { createAsyncLock } from "./async-lock.js";
+export { createDirectory, createDirectorySync, createFileSync, } from "./create.js";
+export { copyFileHandle, copyFileDescriptorSync } from "./file-handle-transfer.js";
+export { sameFileContentsSync } from "./file-contents.js";
+export { overwriteFileHandle } from "./overwrite-file-handle.js";
+export { probePathCaseInsensitiveSync } from "./path-case.js";
+export { resolvePathPrefixSync } from "./path-prefix.js";
+export { probePathSuffixAliasesSync } from "./path-suffix-aliases.js";
+export { readDirectoryIdentity, assertDirectoryIdentitySync, } from "./directory-guard.js";
+export { stageFileInDirectory, } from "./native-staged-file.js";
+export { readFileDescriptorBounded, readFileDescriptorBoundedSync, readFileHandleBounded, } from "./bounded-read.js";
+export { readFileWindowFully, readFileWindowFullySync, } from "./positional-read.js";
+export { writeFileWindowFully } from "./write-file-handle.js";
+export { assertNoUnsafeDeviceReadPath, isUnsafeDeviceReadPath, matchUnsafeDeviceReadPath, } from "./device-path.js";
+export { assertAbsolutePathInput, canonicalPathFromExistingAncestor, ensureAbsoluteDirectory, findExistingAncestor, resolveAbsolutePathForRead, resolveAbsolutePathForWrite, } from "./absolute-path.js";
+export { sameFileIdentity } from "./file-identity.js";
+export { sanitizeUntrustedFileName } from "./filename.js";
+export { pathExists, pathExistsSync } from "./fs.js";
+export { resolveLocalPathFromRootsSync, readLocalFileFromRoots, } from "./local-roots.js";
+export { assertNoWindowsNetworkPath, basenameFromMediaSource, hasEncodedFileUrlSeparator, isWindowsDriveLetterPath, isWindowsNetworkPath, safeFileURLToPath, trySafeFileURLToPath, } from "./local-file-access.js";
+export { formatPosixMode } from "./permissions.js";
+export { configureFsSafeLocks, getFsSafeLockConfig, } from "./lock-config.js";
+export { assertNoHardlinkedFinalPath, assertNoPathAliasEscape, PATH_ALIAS_POLICIES, } from "./path-policy.js";
+export { openRootFile, openRootFileSync, canUseRootFileOpen, matchRootFileOpenFailure, } from "./root-file.js";
+export { ROOT_PATH_ALIAS_POLICIES, resolvePathViaExistingAncestorSync, resolveRootPath, resolveRootPathSync, } from "./root-path.js";
+export { ensureDirectoryWithinRoot, pathScope, resolveExistingPathsWithinRoot, resolvePathWithinRoot, resolvePathsWithinRoot, resolveStrictExistingPathsWithinRoot, resolveWritablePathWithinRoot, } from "./root-paths.js";
+export { safeDirName, safePathSegmentHashed, safePathSegmentHashedV2, resolveSafeInstallDir, assertCanonicalPathWithinBase, } from "./install-path.js";
+export { assertNoSymlinkParents, assertNoSymlinkParentsSync, } from "./symlink-parents.js";
+export { movePathToTrash } from "./trash.js";
+export { withTimeout } from "./timing.js";
+export { resolveHomeRelativePath } from "./home-dir.js";
+export { appendRegularFile, appendRegularFileSync, readRegularFile, readRegularFileSync, resolveRegularFileAppendFlags, statRegularFile, statRegularFileSync, } from "./regular-file.js";
+export { buildRandomTempFilePath, sanitizeTempFileName, tempFile, withTempFile, } from "./temp-target.js";
+export { writeSiblingTempFile, writeViaSiblingTempPath, } from "./sibling-temp.js";
+export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, } from "./permissions.js";

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

@@ -0,0 +1 @@
+export declare function updateCrc32(previous: number, buffer: Buffer): number;

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

@@ -0,0 +1,19 @@
+import zlib from "node:zlib";
+const nativeCrc32 = zlib.crc32;
+// Node 22.0–22.1 are supported but predate zlib.crc32.
+const CRC32_TABLE = nativeCrc32 ? undefined : Array.from({ length: 256 }, (_, index) => {
+    let value = index;
+    for (let bit = 0; bit < 8; bit += 1) {
+        value = (value & 1) !== 0 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+    }
+    return value >>> 0;
+});
+export function updateCrc32(previous, buffer) {
+    if (nativeCrc32)
+        return nativeCrc32(buffer, previous >>> 0);
+    let crc = previous ^ -1;
+    for (const byte of buffer) {
+        crc = (crc >>> 8) ^ (CRC32_TABLE[(crc ^ byte) & 0xff] ?? 0);
+    }
+    return (crc ^ -1) >>> 0;
+}

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

@@ -0,0 +1,11 @@
+export type ExtractionDeadline = {
+    signal: AbortSignal;
+    check: () => void;
+    ownDestinationMutation: <T>(run: () => Promise<T>) => Promise<T>;
+    waitForDestinationMutations: () => Promise<void>;
+    dispose: () => void;
+};
+export declare function ownExtractionDestinationMutation<T>(deadline: ExtractionDeadline | undefined, run: () => Promise<T>): Promise<T>;
+export declare function createPipelineTimeoutError(err: unknown, deadline: ExtractionDeadline): unknown;
+export declare function waitForDeadline<T>(promise: Promise<T>, deadline: ExtractionDeadline): Promise<T>;
+export declare function withExtractionDeadline<T>(timeoutMs: number, label: string, run: (deadline: ExtractionDeadline) => Promise<T>): Promise<T>;

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

@@ -0,0 +1,101 @@
+import { scheduleTimeout } from "./timing.js";
+export async function ownExtractionDestinationMutation(deadline, run) {
+    return deadline ? await deadline.ownDestinationMutation(run) : await run();
+}
+function signalReason(signal, fallback) {
+    const reason = signal.reason;
+    return reason instanceof Error ? reason : fallback ?? new Error(String(reason));
+}
+function deadlineReason(deadline) {
+    return signalReason(deadline.signal);
+}
+export function createPipelineTimeoutError(err, deadline) {
+    if (deadline.signal.aborted &&
+        err instanceof Error &&
+        (err.name === "AbortError" || err.message === "The operation was aborted")) {
+        return deadlineReason(deadline);
+    }
+    return err;
+}
+export async function waitForDeadline(promise, deadline) {
+    // An elapsed synchronous check must not orphan a later operation rejection.
+    void promise.catch(() => undefined);
+    deadline.check();
+    if (deadline.signal.aborted) {
+        throw deadlineReason(deadline);
+    }
+    const result = await Promise.race([
+        promise,
+        new Promise((_, reject) => {
+            const abort = () => reject(deadlineReason(deadline));
+            deadline.signal.addEventListener("abort", abort, { once: true });
+            const cleanup = () => {
+                deadline.signal.removeEventListener("abort", abort);
+            };
+            promise.then(cleanup, cleanup);
+        }),
+    ]);
+    deadline.check();
+    return result;
+}
+function createDestinationMutationOwner(check) {
+    const active = new Set();
+    return {
+        ownDestinationMutation: async (run) => {
+            check();
+            const operation = Promise.resolve().then(() => { check(); return run(); });
+            active.add(operation);
+            try {
+                return await operation;
+            }
+            finally {
+                active.delete(operation);
+            }
+        },
+        waitForDestinationMutations: async () => {
+            while (active.size > 0) {
+                await Promise.allSettled(active);
+            }
+        },
+    };
+}
+function createExtractionDeadline(timeoutMs, label) {
+    const controller = new AbortController();
+    const timeoutError = new Error(`${label} timed out after ${timeoutMs}ms`);
+    const enabled = Number.isFinite(timeoutMs) && timeoutMs > 0;
+    const startedAt = enabled ? performance.now() : 0;
+    const check = () => {
+        if (enabled && !controller.signal.aborted && performance.now() - startedAt >= timeoutMs) {
+            controller.abort(timeoutError);
+        }
+        if (controller.signal.aborted) {
+            throw signalReason(controller.signal, timeoutError);
+        }
+    };
+    return {
+        signal: controller.signal,
+        check,
+        ...createDestinationMutationOwner(check),
+        dispose: enabled ? scheduleTimeout(() => controller.abort(timeoutError), timeoutMs) : () => undefined,
+    };
+}
+export async function withExtractionDeadline(timeoutMs, label, run) {
+    const deadline = createExtractionDeadline(timeoutMs, label);
+    const operation = Promise.resolve().then(() => { deadline.check(); return run(deadline); });
+    try {
+        try {
+            return await waitForDeadline(operation, deadline);
+        }
+        catch (error) {
+            if (deadline.signal.aborted && error === deadlineReason(deadline)) {
+                // Preserve prompt timeout settlement for non-mutating work, but never
+                // return while live destination publication or rollback is still owned.
+                await deadline.waitForDestinationMutations();
+            }
+            throw error;
+        }
+    }
+    finally {
+        deadline.dispose();
+    }
+}

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

@@ -0,0 +1,23 @@
+import { type ExtractionDeadline } from "./archive-deadline.js";
+import { type ArchiveDirectoryGuard } from "./archive-staging.js";
+import type { PublishedWriteIdentity } from "./pinned-write-types.js";
+import type { Root } from "./root.js";
+export type ArchivePublishedFile = {
+    relativePath: string;
+    identity: PublishedWriteIdentity;
+    guards: readonly ArchiveDirectoryGuard[];
+};
+export type ArchivePublishedDirectory = {
+    guard: ArchiveDirectoryGuard;
+    parents: readonly ArchiveDirectoryGuard[];
+    mode: number;
+};
+export declare function finalizeArchivePublication(params: {
+    targetRoot: Root;
+    destinationGuard: ArchiveDirectoryGuard;
+    sourceGuard: ArchiveDirectoryGuard;
+    files: readonly ArchivePublishedFile[];
+    directories: readonly ArchivePublishedDirectory[];
+    durable: boolean;
+    deadline?: ExtractionDeadline;
+}): Promise<void>;