@openclaw/feishu 2026.9.6 → 2026.9.8

package/node_modules/@openclaw/fs-safe/dist/directory-guard.js

@@ -0,0 +1,176 @@
+import fsSync from "node:fs";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { isNotFoundPathError } from "./path.js";
+import { directoryComponentNotDirectoryError } from "./root-errors.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+import { realpathSync } from "./realpath.js";
+import { directoryEntryPath } from "./directory-entry-path.js";
+import { assertStatObservationSync, inspectStatObservationSync, } from "./stat-observation.js";
+export async function readDirectoryIdentity(dir) {
+    const guard = await createAsyncDirectoryGuard(dir, { bigint: true });
+    return Object.freeze({ dev: guard.stat.dev, ino: guard.stat.ino, realPath: guard.realPath });
+}
+export function assertDirectoryIdentitySync(observedPath, expected) {
+    const operationPath = directoryOperationPath(observedPath);
+    const expectedDev = expected.dev;
+    const expectedIno = expected.ino;
+    const expectedRealPath = expected.realPath;
+    if (expectedRealPath !== undefined)
+        assertNoWindowsPathAlias(expectedRealPath, "filesystem");
+    inspectDirectoryIdentityAtPathSync(operationPath, { dev: expectedDev, ino: expectedIno });
+    if (expectedRealPath === undefined)
+        return;
+    const realPath = realpathSync.native(operationPath);
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    if (realPath !== expectedRealPath) {
+        throw new FsSafeError("path-mismatch", "directory changed during operation");
+    }
+}
+export async function createAsyncDirectoryGuard(dir, options) {
+    return captureDirectoryGuard(dir, "native", options);
+}
+export function createSyncDirectoryGuard(dir) {
+    return captureDirectoryGuard(dir, "normalized");
+}
+function captureDirectoryGuard(dir, mode, options) {
+    const operationPath = directoryOperationPath(dir);
+    const stat = options?.bigint
+        ? inspectDirectoryIdentityAtPathSync(operationPath, undefined, options.initial)
+        : fsSync.lstatSync(operationPath);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw directoryComponentNotDirectoryError();
+    }
+    const realPath = mode === "native" ? realpathSync.native(operationPath) : realpathSync(operationPath);
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    return { dir, realPath, stat };
+}
+export async function assertAsyncDirectoryGuard(guard) {
+    assertDirectoryGuard(guard, "native");
+}
+export function assertSyncDirectoryGuard(guard) {
+    assertDirectoryGuard(guard, "normalized");
+}
+function assertDirectoryGuard(guard, mode) {
+    const dir = guard.dir;
+    const operationPath = directoryOperationPath(dir);
+    const expectedRealPath = guard.realPath;
+    assertNoWindowsPathAlias(expectedRealPath, "filesystem");
+    const expectedStat = guard.stat;
+    const expectedIdentity = { dev: expectedStat.dev, ino: expectedStat.ino };
+    const stat = typeof expectedIdentity.dev === "bigint" && typeof expectedIdentity.ino === "bigint"
+        ? inspectDirectoryIdentityAtPathSync(operationPath, {
+            dev: expectedIdentity.dev,
+            ino: expectedIdentity.ino,
+        })
+        : fsSync.lstatSync(operationPath);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw directoryComponentNotDirectoryError();
+    }
+    // Native guards check identity first; normalized numeric guards preserve
+    // canonicalization errors before their final identity comparison.
+    if (mode === "native" && !sameFileIdentity(stat, expectedIdentity)) {
+        throw new FsSafeError("path-mismatch", "directory changed during operation");
+    }
+    const realPath = mode === "native" || typeof expectedIdentity.ino === "bigint"
+        ? realpathSync.native(operationPath) : realpathSync(operationPath);
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    if ((mode === "normalized" && !sameFileIdentity(stat, expectedIdentity)) || realPath !== expectedRealPath) {
+        throw new FsSafeError("path-mismatch", "directory changed during operation");
+    }
+}
+export async function createNearestExistingDirectoryGuard(rootReal, targetPath, options = { bigint: false }) {
+    return nearestExistingDirectoryGuard(rootReal, targetPath, "native", options);
+}
+function nearestExistingDirectoryGuard(rootReal, targetPath, mode, options) {
+    assertNoWindowsPathAlias(rootReal, "filesystem");
+    assertNoWindowsPathAlias(targetPath, "filesystem");
+    let current = resolvePathPreservingWindowsRoot(targetPath);
+    const root = resolvePathPreservingWindowsRoot(rootReal);
+    while (current !== root) {
+        try {
+            return captureDirectoryGuard(current, mode, options);
+        }
+        catch (error) {
+            if (!isNotFoundPathError(error)) {
+                throw error;
+            }
+            current = path.dirname(current);
+        }
+    }
+    return captureDirectoryGuard(root, mode, options);
+}
+// Recovery receipts must retain every identity bit, including on Windows.
+export async function inspectDirectoryIdentity(dir, expected) {
+    return inspectDirectoryIdentitySync(dir, expected);
+}
+function directoryOperationPath(dir) {
+    assertNoWindowsPathAlias(dir, "filesystem");
+    return pathForWindowsFilesystem(directoryEntryPath(dir));
+}
+export function observeDirectoryIdentitySync(dir, options) {
+    const entryPath = directoryOperationPath(dir);
+    const stat = options?.bigint
+        ? fsSync.lstatSync(entryPath, { bigint: true })
+        : fsSync.lstatSync(entryPath);
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+        throw directoryComponentNotDirectoryError();
+    return stat;
+}
+export function inspectDirectoryIdentitySync(dir, expected, initial, platform = process.platform) {
+    const operationPath = directoryOperationPath(dir);
+    const expectedIdentity = expected === undefined
+        ? undefined
+        : { dev: expected.dev, ino: expected.ino };
+    return inspectDirectoryIdentityAtPathSync(operationPath, expectedIdentity, initial, platform);
+}
+function inspectDirectoryIdentityAtPathSync(operationPath, expected, initial, platform = process.platform) {
+    return inspectFileIdentitySync(() => {
+        // Traversal can supply the first exact observation. A bounded retry still
+        // uses the admitted operation path and retains every known identity bit.
+        const stat = initial ?? fsSync.lstatSync(operationPath, { bigint: true });
+        initial = undefined;
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw directoryComponentNotDirectoryError();
+        return stat;
+    }, expected, platform);
+}
+export function extendDirectoryObservationGuard(observation, dir, realPath) {
+    const guard = observation;
+    guard.dir = dir;
+    guard.realPath = realPath;
+    return guard;
+}
+// Only stat/list receipts use this metadata fast path. Recovery and publication
+// callers retain the BigIntStats contract of inspectDirectoryIdentitySync.
+export function inspectDirectoryObservationSync(dir, expected) {
+    const entryPath = directoryOperationPath(dir);
+    return inspectStatObservationSync(bigint => {
+        const stat = bigint ? fsSync.lstatSync(entryPath, { bigint: true }) : fsSync.lstatSync(entryPath);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw directoryComponentNotDirectoryError();
+        return stat;
+    }, expected);
+}
+export function assertDirectoryObservationSync(dir, expected) {
+    const entryPath = directoryOperationPath(dir);
+    return assertStatObservationSync(bigint => {
+        const stat = bigint ? fsSync.lstatSync(entryPath, { bigint: true }) : fsSync.lstatSync(entryPath);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw directoryComponentNotDirectoryError();
+        return stat;
+    }, expected);
+}
+export function assertDirectoryObservationGuardSync(guard) {
+    const dir = guard.dir;
+    const expectedRealPath = guard.realPath;
+    assertNoWindowsPathAlias(expectedRealPath, "filesystem");
+    assertDirectoryObservationSync(dir, guard.identity);
+    const realPath = realpathSync.native(directoryOperationPath(dir));
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    if (realPath !== expectedRealPath) {
+        throw new FsSafeError("path-mismatch", "directory changed during operation");
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/directory-mode-node.d.ts

@@ -0,0 +1,39 @@
+import { type BigIntStats, type Stats } from "node:fs";
+export type DirectoryModeChecks = {
+    check?: () => void;
+    beforeChmod?: () => Promise<void>;
+};
+export type DirectoryModeOwner = {
+    verify(check?: () => void): Promise<void>;
+    apply(mode: number, checks?: DirectoryModeChecks): Promise<void>;
+    close(): Promise<void>;
+};
+export declare function assertOwnedDirectory(expected: Stats | BigIntStats, actual: Stats | BigIntStats): void;
+/** Serializes use and close: even a queued path-based fd operation retains its descriptor. */
+export declare function ownDirectoryMode(params: {
+    inspect: () => Promise<number>;
+    chmod: (mode: number) => Promise<void>;
+    prepareChmod?: () => Promise<void>;
+    verifyChmod?: () => Promise<void>;
+    close: () => Promise<void>;
+    ignoreChmodError?: boolean;
+}): DirectoryModeOwner;
+/** Darwin descriptor inspection avoids requesting directory-content reads. */
+export declare function nodeDarwinDirectoryMetadataFlags(): number;
+export declare function nodeDirectorySearchOnlyFlags(): {
+    flags: number;
+    proc: boolean;
+} | undefined;
+/** Real Node only: injected filesystem adapters must retain descriptor-chmod semantics. */
+export declare function pinNodeDirectoryForMode(dirPath: string, options?: {
+    expectedIdentity?: BigIntStats;
+    ownerUid?: number;
+}): Promise<DirectoryModeOwner>;
+/** Synchronous counterpart with the same no-follow, identity, and owner checks. */
+export declare function pinNodeDirectoryForModeSync(dirPath: string, options?: {
+    expectedIdentity?: BigIntStats;
+    ownerUid?: number;
+}): {
+    apply(mode: number, check?: () => void): void;
+    close(): void;
+};

package/node_modules/@openclaw/fs-safe/dist/directory-mode-node.js

@@ -0,0 +1,285 @@
+import fsSync, { constants } from "node:fs";
+import fs from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
+import { inspectDirectoryIdentity, inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+export function assertOwnedDirectory(expected, actual) {
+    if (actual.isSymbolicLink() || !actual.isDirectory()) {
+        throw new FsSafeError("not-file", "directory mode target must be a real directory");
+    }
+    if (!sameFileIdentityForCleanup(expected, actual)) {
+        throw new FsSafeError("path-mismatch", "directory changed before its mode could be applied");
+    }
+}
+/** Serializes use and close: even a queued path-based fd operation retains its descriptor. */
+export function ownDirectoryMode(params) {
+    let pending = Promise.resolve();
+    let closing;
+    const enqueue = (run) => {
+        if (closing)
+            return Promise.reject(new FsSafeError("path-mismatch", "directory mode owner is closed"));
+        const operation = pending.then(run);
+        pending = operation.catch(() => undefined);
+        return operation;
+    };
+    return {
+        verify: (check) => enqueue(async () => {
+            check?.();
+            await params.inspect();
+            check?.();
+        }),
+        apply: (mode, checks = {}) => enqueue(async () => {
+            // inspect() reports permission bits only; chmod ignores file-type bits,
+            // so tolerate raw stat modes (e.g. S_IFDIR | 0o755) by masking up front.
+            mode &= 0o7777;
+            checks.check?.();
+            const currentMode = await params.inspect();
+            checks.check?.();
+            if (currentMode === mode && !checks.beforeChmod && !checks.check)
+                return;
+            if (currentMode !== mode) {
+                await params.prepareChmod?.();
+                checks.check?.();
+            }
+            await checks.beforeChmod?.();
+            checks.check?.();
+            // Hooks/ancestor checks can yield; recheck the original named association.
+            await params.inspect();
+            checks.check?.();
+            let dispatchDeadlineFailure;
+            if (currentMode !== mode) {
+                checks.check?.();
+                try {
+                    await params.chmod(mode);
+                }
+                catch (error) {
+                    if (!params.ignoreChmodError)
+                        throw error;
+                }
+                // Expiry cannot release the fd while post-dispatch verification is pending.
+                try {
+                    checks.check?.();
+                }
+                catch (error) {
+                    dispatchDeadlineFailure = { error };
+                }
+                await params.verifyChmod?.();
+            }
+            const finalMode = await params.inspect();
+            if (dispatchDeadlineFailure)
+                throw dispatchDeadlineFailure.error;
+            checks.check?.();
+            if (!params.ignoreChmodError && finalMode !== mode) {
+                throw new FsSafeError("path-mismatch", "directory final mode could not be verified");
+            }
+        }),
+        close() {
+            closing ??= pending.then(params.close);
+            return closing;
+        },
+    };
+}
+/** Darwin descriptor inspection avoids requesting directory-content reads. */
+export function nodeDarwinDirectoryMetadataFlags() {
+    if (process.platform !== "darwin" || (process.arch !== "x64" && process.arch !== "arm64")) {
+        throw new FsSafeError("helper-unavailable", "Darwin directory metadata descriptors are unavailable");
+    }
+    // Darwin SDK O_EVTONLY; Node omits this flag from its exported constants.
+    return 0x8000 | constants.O_DIRECTORY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+}
+export function nodeDirectorySearchOnlyFlags() {
+    if (process.arch !== "x64" && process.arch !== "arm64")
+        return undefined;
+    // Darwin SDK O_SEARCH = O_EXEC (0x40000000) | O_DIRECTORY, on x64/arm64.
+    if (process.platform === "darwin")
+        return { flags: 0x40000000, proc: false };
+    // Linux x86-64/aarch64 UAPI O_PATH = 010000000. Not a usable fchmod fd.
+    if (process.platform === "linux")
+        return { flags: 0x200000, proc: true };
+    return undefined;
+}
+/** Real Node only: injected filesystem adapters must retain descriptor-chmod semantics. */
+export async function pinNodeDirectoryForMode(dirPath, options = {}) {
+    const { ownerUid } = options;
+    const assertOwner = (stat) => {
+        if (ownerUid !== undefined && stat.uid !== BigInt(ownerUid)) {
+            throw new FsSafeError("not-owned", "directory mode target must retain its expected owner");
+        }
+    };
+    const expected = await inspectDirectoryIdentity(dirPath, options.expectedIdentity);
+    assertOwner(expected);
+    if (process.platform === "win32") {
+        // POSIX mode enforcement is unsupported; retain strict path identity checks.
+        return ownDirectoryMode({
+            inspect: async () => { assertOwner(await inspectDirectoryIdentity(dirPath, expected)); return 0; },
+            chmod: async () => undefined, close: async () => undefined, ignoreChmodError: true,
+        });
+    }
+    if ([constants.O_DIRECTORY, constants.O_NOFOLLOW, constants.O_NONBLOCK, constants.O_RDONLY]
+        .some((flag) => typeof flag !== "number")) {
+        throw new FsSafeError("helper-unavailable", "no-follow directory mode descriptors are unavailable");
+    }
+    const flags = constants.O_DIRECTORY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+    let proc = false;
+    const handle = await fs.open(dirPath, constants.O_RDONLY | flags).catch(async (error) => {
+        if (error.code !== "EACCES")
+            throw error;
+        const route = nodeDirectorySearchOnlyFlags();
+        if (!route)
+            throw error;
+        proc = route.proc;
+        return await fs.open(dirPath, route.flags | flags);
+    });
+    try {
+        const inspect = async () => {
+            const opened = await inspectFileIdentity(() => fsSync.fstatSync(handle.fd, { bigint: true }), expected);
+            assertOwnedDirectory(expected, opened);
+            assertOwner(opened);
+            await inspectDirectoryIdentity(dirPath, expected);
+            return Number(opened.mode & 4095n);
+        };
+        const procPath = `/proc/self/fd/${handle.fd}`;
+        const assertProcAuthority = async () => {
+            // Authenticate the fd namespace, not the followed target's filesystem.
+            // This trusts host mount-namespace integrity, not privileged mount replacement.
+            const namespace = await fs.statfs("/proc/self/fd", { bigint: true });
+            if (namespace.type !== 0x9fa0n) {
+                throw new FsSafeError("path-mismatch", "directory mode requires a trusted procfs fd namespace");
+            }
+            const opened = await inspectFileIdentity(() => fsSync.fstatSync(handle.fd, { bigint: true }), expected);
+            const followed = await inspectFileIdentity(() => fsSync.statSync(procPath, { bigint: true }), expected);
+            assertOwnedDirectory(opened, followed);
+            assertOwner(opened);
+            assertOwner(followed);
+        };
+        const owner = ownDirectoryMode({
+            inspect,
+            prepareChmod: proc ? assertProcAuthority : undefined,
+            verifyChmod: proc ? assertProcAuthority : undefined,
+            async chmod(mode) {
+                if (proc) {
+                    await fs.chmod(procPath, mode);
+                }
+                else {
+                    await handle.chmod(mode);
+                }
+            },
+            close: () => handle.close(),
+        });
+        await owner.verify();
+        return owner;
+    }
+    catch (error) {
+        try {
+            await handle.close();
+        }
+        catch {
+            // Preserve the initial admission failure before ownership transfers.
+        }
+        throw error;
+    }
+}
+/** Synchronous counterpart with the same no-follow, identity, and owner checks. */
+export function pinNodeDirectoryForModeSync(dirPath, options = {}) {
+    const expected = inspectDirectoryIdentitySync(dirPath, options.expectedIdentity);
+    const assertOwner = (stat) => {
+        if (options.ownerUid !== undefined && stat.uid !== BigInt(options.ownerUid)) {
+            throw new FsSafeError("not-owned", "directory mode target must retain its expected owner");
+        }
+    };
+    assertOwner(expected);
+    if (process.platform === "win32") {
+        return {
+            apply: (_mode, check) => {
+                check?.();
+                assertOwner(inspectDirectoryIdentitySync(dirPath, expected));
+                check?.();
+            },
+            close: () => undefined,
+        };
+    }
+    if ([constants.O_DIRECTORY, constants.O_NOFOLLOW, constants.O_NONBLOCK, constants.O_RDONLY]
+        .some((flag) => typeof flag !== "number")) {
+        throw new FsSafeError("helper-unavailable", "no-follow directory mode descriptors are unavailable");
+    }
+    const flags = constants.O_DIRECTORY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+    let fd;
+    let proc = false;
+    try {
+        fd = fsSync.openSync(dirPath, constants.O_RDONLY | flags);
+    }
+    catch (error) {
+        if (error.code !== "EACCES")
+            throw error;
+        const route = nodeDirectorySearchOnlyFlags();
+        if (!route)
+            throw error;
+        proc = route.proc;
+        fd = fsSync.openSync(dirPath, route.flags | flags);
+    }
+    let closed = false;
+    const inspect = () => {
+        if (closed)
+            throw new FsSafeError("path-mismatch", "directory mode descriptor is closed");
+        const stat = inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }), expected);
+        assertOwnedDirectory(expected, stat);
+        assertOwner(stat);
+        inspectDirectoryIdentitySync(dirPath, expected);
+        return Number(stat.mode & 4095n);
+    };
+    const procPath = `/proc/self/fd/${fd}`;
+    const assertProcAuthority = () => {
+        if (fsSync.statfsSync("/proc/self/fd", { bigint: true }).type !== 0x9fa0n) {
+            throw new FsSafeError("path-mismatch", "directory mode requires a trusted procfs fd namespace");
+        }
+        const opened = inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }), expected);
+        const followed = inspectFileIdentitySync(() => fsSync.statSync(procPath, { bigint: true }), expected);
+        assertOwnedDirectory(opened, followed);
+        assertOwner(opened);
+        assertOwner(followed);
+    };
+    try {
+        inspect();
+        return {
+            apply: (mode, check) => {
+                mode &= 0o7777;
+                check?.();
+                const currentMode = inspect();
+                check?.();
+                if (currentMode !== mode) {
+                    if (proc)
+                        assertProcAuthority();
+                    check?.();
+                    inspect();
+                    if (proc)
+                        fsSync.chmodSync(procPath, mode);
+                    else
+                        fsSync.fchmodSync(fd, mode);
+                    if (proc)
+                        assertProcAuthority();
+                }
+                const finalMode = inspect();
+                check?.();
+                if (finalMode !== mode) {
+                    throw new FsSafeError("path-mismatch", "directory final mode could not be verified");
+                }
+            },
+            close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                fsSync.closeSync(fd);
+            },
+        };
+    }
+    catch (error) {
+        try {
+            fsSync.closeSync(fd);
+        }
+        catch {
+            // Preserve the initial admission failure before ownership transfers.
+        }
+        throw error;
+    }
+}

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

@@ -0,0 +1,23 @@
+import { type BigIntStats, type Stats } from "node:fs";
+import type { DirectoryReceipt } from "./directory-durability.js";
+import type { FileIdentityStat } from "./file-identity.js";
+type ExactIdentity = Readonly<Pick<BigIntStats, "dev" | "ino">>;
+declare const numericFields: readonly ["dev", "mode", "nlink", "uid", "gid", "rdev", "blksize", "ino", "size", "blocks"];
+declare const timeFields: readonly ["atime", "mtime", "ctime", "birthtime"];
+type DirectoryMetadata = Pick<Stats, typeof numericFields[number] | `${typeof timeFields[number]}Ms`>;
+type DirectoryProvenance = Readonly<{
+    identity: ExactIdentity;
+    metadata: Readonly<DirectoryMetadata>;
+}>;
+type DirectoryAuthority = DirectoryProvenance & Readonly<{
+    path: string;
+    realPath: string;
+}>;
+export declare function directoryReceiptIdentity(identity: FileIdentityStat): ExactIdentity;
+export declare function directoryReceiptAuthority(receipt: DirectoryReceipt<Stats | BigIntStats>): DirectoryAuthority;
+export declare function ownDirectoryReceipt(receipt: DirectoryReceipt<Stats | BigIntStats>): DirectoryReceipt;
+export declare function copyRetainedDirectoryReceipt(receipt: DirectoryReceipt): DirectoryReceipt;
+export declare function createDirectoryReceiptFromIdentity(pathname: string, realPath: string, exactStat: BigIntStats): DirectoryReceipt;
+export declare function createDirectoryReceiptSync(directoryPath: string, label: string, canonicalize?: (pathname: string) => string): DirectoryReceipt;
+export declare function assertDirectoryReceiptCurrentSync(receipt: DirectoryReceipt, label: string, canonicalize?: (pathname: string) => string): void;
+export {};

package/node_modules/@openclaw/fs-safe/dist/directory-receipt.js

@@ -0,0 +1,121 @@
+import fs, {} from "node:fs";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { realpathSync } from "./realpath.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+const numericFields = ["dev", "mode", "nlink", "uid", "gid", "rdev", "blksize", "ino", "size", "blocks"];
+const timeFields = ["atime", "mtime", "ctime", "birthtime"];
+// Live pins retain private authority. New admissions snapshot the supplied
+// fields and accept exact provenance only while its public identity is intact.
+const authorities = new WeakMap();
+const identities = new WeakMap();
+export function directoryReceiptIdentity(identity) {
+    if (!identity) {
+        throw new FsSafeError("path-mismatch", "directory receipt identity is missing");
+    }
+    const known = identities.get(identity);
+    const dev = identity.dev;
+    const ino = identity.ino;
+    if (known) {
+        const matches = (value, expected) => typeof value === "bigint" ? value === expected : value === Number(expected);
+        if (!matches(dev, known.identity.dev) || !matches(ino, known.identity.ino)) {
+            throw new FsSafeError("path-mismatch", "directory receipt identity changed");
+        }
+        return known.identity;
+    }
+    const exact = (value) => {
+        if ((typeof value !== "bigint" && !Number.isSafeInteger(value)) ||
+            (process.platform === "win32" && (value === 0 || value === 0n))) {
+            throw new FsSafeError("path-mismatch", "directory receipt identity could not be verified");
+        }
+        return BigInt(value);
+    };
+    return Object.freeze({ dev: exact(dev), ino: exact(ino) });
+}
+function snapshotDirectoryReceipt(receipt) {
+    const pathname = receipt?.path;
+    const realPath = receipt?.realPath;
+    const stat = receipt?.identity;
+    if (typeof pathname !== "string" || typeof realPath !== "string" || stat == null) {
+        throw new FsSafeError("path-mismatch", "directory receipt is incomplete");
+    }
+    assertNoWindowsPathAlias(pathname, "filesystem");
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    const identity = directoryReceiptIdentity(stat);
+    const known = authorities.get(receipt);
+    if (known && (pathname !== known.path || realPath !== known.realPath ||
+        identity.dev !== known.identity.dev || identity.ino !== known.identity.ino)) {
+        throw new FsSafeError("path-mismatch", "directory receipt changed before admission");
+    }
+    const metadata = known?.metadata ?? identities.get(stat)?.metadata ?? snapshotDirectoryMetadata(stat, identity);
+    return Object.freeze({ path: pathname, realPath, identity, metadata });
+}
+function snapshotDirectoryMetadata(stat, identity) {
+    const metadata = {};
+    for (const field of numericFields) {
+        metadata[field] = Number(field === "dev" || field === "ino" ? identity[field] : stat[field]);
+    }
+    for (const field of timeFields) {
+        if ("atimeNs" in stat) {
+            const nanoseconds = stat[`${field}Ns`];
+            const remainder = ((nanoseconds % 1000000000n) + 1000000000n) % 1000000000n;
+            metadata[`${field}Ms`] = Number((nanoseconds - remainder) / 1000000000n) * 1_000 + Number(remainder) / 1_000_000;
+        }
+        else {
+            metadata[`${field}Ms`] = stat[`${field}Ms`];
+        }
+    }
+    return Object.freeze(metadata);
+}
+export function directoryReceiptAuthority(receipt) {
+    return authorities.get(receipt) ?? snapshotDirectoryReceipt(receipt);
+}
+export function ownDirectoryReceipt(receipt) {
+    return receiptFromAuthority(snapshotDirectoryReceipt(receipt));
+}
+export function copyRetainedDirectoryReceipt(receipt) {
+    const authority = directoryReceiptAuthority(receipt);
+    return receiptFromAuthority(authority);
+}
+function receiptFromAuthority(authority) {
+    const receipt = {
+        path: authority.path,
+        realPath: authority.realPath,
+        identity: Object.assign(Object.create(fs.Stats.prototype), authority.metadata),
+    };
+    authorities.set(receipt, authority);
+    identities.set(receipt.identity, authority);
+    return receipt;
+}
+// The caller already admitted the exact observation and its paths.
+export function createDirectoryReceiptFromIdentity(pathname, realPath, exactStat) {
+    const identity = Object.freeze({ dev: exactStat.dev, ino: exactStat.ino });
+    return receiptFromAuthority(Object.freeze({
+        path: pathname,
+        realPath,
+        identity,
+        // Project metadata from the admitted observation, never a fresh pathname stat.
+        metadata: snapshotDirectoryMetadata(exactStat, identity),
+    }));
+}
+export function createDirectoryReceiptSync(directoryPath, label, canonicalize = realpathSync) {
+    assertNoWindowsPathAlias(directoryPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    const pathname = resolvePathPreservingWindowsRoot(directoryPath);
+    assertNoWindowsPathAlias(pathname, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    const exact = inspectDirectoryIdentitySync(pathname);
+    const operationPath = pathForWindowsFilesystem(pathname);
+    const realPath = canonicalize(operationPath);
+    assertNoWindowsPathAlias(realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
+    return createDirectoryReceiptFromIdentity(pathname, realPath, exact);
+}
+export function assertDirectoryReceiptCurrentSync(receipt, label, canonicalize = realpathSync) {
+    const authority = directoryReceiptAuthority(receipt);
+    assertNoWindowsPathAlias(authority.path, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    assertNoWindowsPathAlias(authority.realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
+    inspectDirectoryIdentitySync(authority.path, authority.identity);
+    const realPath = canonicalize(pathForWindowsFilesystem(authority.path));
+    assertNoWindowsPathAlias(realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
+    if (realPath !== authority.realPath) {
+        throw new FsSafeError("path-mismatch", `${label} changed during durable directory operation: ${authority.path}`);
+    }
+}

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

@@ -0,0 +1,4 @@
+export { ensureDurableDirectory, pinDirectory, syncDirectory, syncDirectoryBestEffort, syncDirectoryBestEffortSync, syncDirectorySync, type DirectoryReceipt, type DirectorySyncOutcome, type DurableDirectoryReceipt, type EnsureDurableDirectoryOptions, type PinnedDirectory, } from "./directory-durability.js";
+export { isHardlinkFallbackError, publishFileExclusive, type PublishFileExclusiveResult, type PublishFileExclusiveStrategy, } from "./publish-file.js";
+export type { PublishFileExclusiveCleanup, PublishFileExclusiveDirectorySyncFailure, PublishFileExclusiveFailureDetails, PublishFileExclusiveFailurePhase, PublishFileExclusiveSyncFailurePolicy, } from "./publish-file-failure.js";
+export { sha256File, sha256FileSync, type Sha256FileInput, type Sha256FileSyncInput, type Sha256FileOptions, type Sha256FileResult, } from "./file-hash.js";

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

@@ -0,0 +1,3 @@
+export { ensureDurableDirectory, pinDirectory, syncDirectory, syncDirectoryBestEffort, syncDirectoryBestEffortSync, syncDirectorySync, } from "./directory-durability.js";
+export { isHardlinkFallbackError, publishFileExclusive, } from "./publish-file.js";
+export { sha256File, sha256FileSync, } from "./file-hash.js";

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

@@ -0,0 +1 @@
+export declare function resolveEffectiveUid(): number;