@openclaw/matrix 2026.9.5 → 2026.9.7

package/node_modules/@openclaw/fs-safe/dist/root-write-complete-parent.js

@@ -0,0 +1,180 @@
+import fsSync from "node:fs";
+import path from "node:path";
+import { assertDirectoryIdentitySync, createAsyncDirectoryGuard, inspectDirectoryIdentitySync, } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { hasNodeErrorCode } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { admitPathInsideRoot, sameNormalizedPathSpelling } from "./root-boundary.js";
+import { ordinaryWindowsSegments } from "./pinned-mutation-shared-route.js";
+import { prepareRootWriteTarget } from "./root-directory-creation.js";
+import { errorCauseOptions } from "./root-errors.js";
+import { canReuseParentWithMutationAssertion } from "./root-write-lock-binding.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+export function writeSelectionChanged(cause) {
+    return new FsSafeError("path-mismatch", "write target changed during operation", errorCauseOptions(cause));
+}
+function ordinarySharedWriteRoute(root, relativePath, operationTargetPath) {
+    if (process.versions.bun || relativePath === "" || relativePath.startsWith("~") ||
+        relativePath.includes("\0") || path.isAbsolute(relativePath))
+        return false;
+    if (process.platform === "win32") {
+        if (!ordinaryWindowsSegments(relativePath))
+            return false;
+    }
+    else if (relativePath.includes("\\") || relativePath.split("/").some(segment => segment === "" || segment === "." || segment === ".."))
+        return false;
+    const routed = path.resolve(root.rootReal, relativePath);
+    const admitted = admitPathInsideRoot({
+        rootPath: root.rootReal,
+        candidatePath: routed,
+        rootIdentity: root.rootIdentity,
+    });
+    return admitted?.admission === "exact" &&
+        sameNormalizedPathSpelling(admitted.path, routed) &&
+        sameNormalizedPathSpelling(routed, operationTargetPath);
+}
+// Preparation is optional evidence. An exact identity mismatch is conclusive
+// and remains fail-closed; every other probe failure must let the established
+// ordered component admission classify the same filesystem state.
+function deoptPreparationFailure(error) {
+    if (error instanceof FsSafeError && error.code === "path-mismatch")
+        throw error;
+    return undefined;
+}
+function capturePreparedTargetObservation(targetPath) {
+    let stat;
+    try {
+        stat = inspectFileIdentitySync(() => fsSync.lstatSync(targetPath, { bigint: true }));
+    }
+    catch (error) {
+        if (hasNodeErrorCode(error, "ENOENT"))
+            return Object.freeze({ exists: false });
+        return deoptPreparationFailure(error);
+    }
+    // Final aliases retain the established full component walk and selected-path
+    // admission. The shortcut is intentionally limited to an ordinary spelling.
+    if (stat.isSymbolicLink())
+        return undefined;
+    let realPath;
+    try {
+        realPath = realpathSync.native(targetPath);
+    }
+    catch (error) {
+        return deoptPreparationFailure(error);
+    }
+    if (!sameNormalizedPathSpelling(realPath, targetPath))
+        return undefined;
+    return Object.freeze({ exists: true, stat });
+}
+function samePreparedTargetFacts(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode &&
+        left.nlink === right.nlink;
+}
+function assertPreparedTargetCurrent(prepared) {
+    if (!prepared.target.exists) {
+        try {
+            fsSync.lstatSync(prepared.selectedTargetPath, { bigint: true });
+        }
+        catch (error) {
+            if (hasNodeErrorCode(error, "ENOENT"))
+                return;
+            throw writeSelectionChanged(error);
+        }
+        throw writeSelectionChanged();
+    }
+    try {
+        const current = inspectFileIdentitySync(() => fsSync.lstatSync(prepared.selectedTargetPath, { bigint: true }), prepared.target.stat);
+        if (current.isSymbolicLink() || !samePreparedTargetFacts(prepared.target.stat, current)) {
+            throw writeSelectionChanged();
+        }
+    }
+    catch (error) {
+        if (error instanceof FsSafeError && error.code === "path-mismatch")
+            throw error;
+        throw writeSelectionChanged(error);
+    }
+}
+export function assertPreparedRootWriteParentCurrent(prepared, verifyTarget = false) {
+    try {
+        if (getFsSafeNativeConfig().mode !== prepared.nativeMode)
+            throw writeSelectionChanged();
+        if (!sameNormalizedPathSpelling(prepared.parentGuard.dir, prepared.rootPath)) {
+            assertDirectoryIdentitySync(prepared.rootPath, prepared.rootIdentity);
+        }
+        else if (prepared.parentGuard.stat.dev !== prepared.rootIdentity.dev ||
+            prepared.parentGuard.stat.ino !== prepared.rootIdentity.ino) {
+            throw writeSelectionChanged();
+        }
+        const parent = inspectDirectoryIdentitySync(prepared.parentGuard.dir, prepared.parentGuard.stat);
+        if (parent.mode !== prepared.parentGuard.stat.mode ||
+            parent.nlink !== prepared.parentGuard.stat.nlink ||
+            !sameNormalizedPathSpelling(realpathSync.native(prepared.parentGuard.dir), prepared.parentGuard.realPath))
+            throw writeSelectionChanged();
+        if (verifyTarget)
+            assertPreparedTargetCurrent(prepared);
+    }
+    catch (error) {
+        if (error instanceof FsSafeError && error.code === "path-mismatch")
+            throw error;
+        throw writeSelectionChanged(error);
+    }
+}
+async function prepareCompleteRootWriteParent(root, guarded, relativePath) {
+    if (!guarded.mutationAdmission || !guarded.selectedTargetAdmission ||
+        typeof root.rootIdentity.dev !== "bigint" || typeof root.rootIdentity.ino !== "bigint" ||
+        !ordinarySharedWriteRoute(root, relativePath, guarded.targetPath) ||
+        !sameNormalizedPathSpelling(guarded.resolvedPath.resolved, guarded.targetPath))
+        return undefined;
+    const parentPath = path.dirname(guarded.targetPath);
+    const admittedParent = admitPathInsideRoot({
+        rootPath: root.rootReal,
+        candidatePath: parentPath,
+        rootIdentity: root.rootIdentity,
+    });
+    if (admittedParent?.admission !== "exact" ||
+        !sameNormalizedPathSpelling(admittedParent.path, parentPath))
+        return undefined;
+    let parentGuard;
+    try {
+        parentGuard = await createAsyncDirectoryGuard(parentPath, { bigint: true });
+    }
+    catch (error) {
+        return deoptPreparationFailure(error);
+    }
+    if (!sameNormalizedPathSpelling(parentGuard.dir, parentPath) ||
+        !sameNormalizedPathSpelling(parentGuard.realPath, parentPath))
+        return undefined;
+    const target = capturePreparedTargetObservation(guarded.targetPath);
+    if (!target)
+        return undefined;
+    return Object.freeze({
+        operationTargetPath: guarded.targetPath,
+        selectedTargetPath: guarded.targetPath,
+        parentGuard,
+        rootPath: root.rootReal,
+        rootIdentity: Object.freeze({ dev: root.rootIdentity.dev, ino: root.rootIdentity.ino }),
+        nativeMode: getFsSafeNativeConfig().mode,
+        target,
+    });
+}
+export async function prepareSharedRootWriteTarget(root, params) {
+    const { guardedTarget } = params;
+    const resolvedPath = guardedTarget.resolvedPath.resolved;
+    const mutationAdmission = guardedTarget.mutationAdmission;
+    const beforeParentAdmission = mutationAdmission
+        ? getFsSafeTestHooks()?.beforePinnedWriteParentAdmission
+        : undefined;
+    if (mutationAdmission)
+        await beforeParentAdmission?.(resolvedPath);
+    const preparedParent = params.mkdir !== false &&
+        canReuseParentWithMutationAssertion(params.assertBeforeMutation, root.rootReal, guardedTarget.targetPath) &&
+        beforeParentAdmission === undefined
+        ? await prepareCompleteRootWriteParent(root, guardedTarget, params.relativePath)
+        : undefined;
+    const targetPath = params.mkdir === false
+        ? guardedTarget.targetPath
+        : preparedParent?.selectedTargetPath ?? await prepareRootWriteTarget(root, resolvedPath, params.assertBeforeMutation, mutationAdmission);
+    return { targetPath, mutationAdmission, preparedParent };
+}

package/node_modules/@openclaw/fs-safe/dist/root-write-lock-binding.d.ts

@@ -0,0 +1,14 @@
+import { type RootBoundaryIdentity } from "./root-boundary.js";
+export declare function canReuseParentWithMutationAssertion(assertion: (() => void) | undefined, rootPath: string, targetPath: string): boolean;
+export declare function assertRootFallbackWritePath(expected: string | undefined, actual: string): void;
+export declare function createRootWriteLockBinding(params: Readonly<{
+    rootPath: string;
+    targetPath: string;
+    rootIdentity?: RootBoundaryIdentity;
+}>): Readonly<{
+    targetPath: string;
+    relativePath: string;
+    relativeLockPath: string;
+    assertCurrent: () => void;
+    dispose(): void;
+}>;

package/node_modules/@openclaw/fs-safe/dist/root-write-lock-binding.js

@@ -0,0 +1,162 @@
+import fs from "node:fs";
+import path from "node:path";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { hasNodeErrorCode, isNotFoundPathError } from "./path.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { realpathSync } from "./realpath.js";
+const lockObservations = new WeakMap();
+export function canReuseParentWithMutationAssertion(assertion, rootPath, targetPath) {
+    if (assertion === undefined)
+        return true;
+    const binding = lockObservations.get(assertion);
+    return binding?.rootPath === rootPath && binding.targetPath === targetPath;
+}
+function unsupportedSpelling() {
+    return new FsSafeError("path-alias", "Windows compatibility writes require lower-case ASCII destination components");
+}
+// Missing names have no portable case/Unicode lock key. Keep this admission
+// narrower than general Root paths and never change keys after acquisition.
+function effectiveDestination(rootPath, targetPath, rootIdentity) {
+    let effective;
+    let missingHint;
+    try {
+        effective = realpathSync.native(targetPath);
+    }
+    catch (error) {
+        if (!isNotFoundPathError(error))
+            throw error;
+        let cursor = targetPath;
+        const missing = [];
+        for (;;) {
+            try {
+                fs.lstatSync(cursor);
+                break;
+            }
+            catch (error) {
+                if (!isNotFoundPathError(error) || cursor === rootPath)
+                    throw error;
+                const parent = path.dirname(cursor);
+                if (parent === cursor)
+                    throw error;
+                missing.unshift(path.basename(cursor));
+                cursor = parent;
+            }
+        }
+        // Existing dangling links must fail resolution, not become missing names.
+        const canonicalParent = realpathSync.native(cursor);
+        effective = path.join(canonicalParent, ...missing);
+        // The hint must describe the selected route exactly. The full resolver can
+        // normalize a missing raw `..` component out of the eventual lock path.
+        if (missing.length > 1 && path.resolve(canonicalParent) === canonicalParent &&
+            missing.every(component => /^[a-z0-9._-]+$/.test(component) &&
+                component !== "." && component !== ".." && !component.endsWith("."))) {
+            missingHint = Object.freeze({ parentPath: canonicalParent, parts: Object.freeze(missing), nextIndex: 0 });
+        }
+    }
+    const admitted = admitPathInsideRoot({ rootPath, candidatePath: effective, rootIdentity });
+    if (!admitted)
+        throw unsupportedSpelling();
+    const relative = admitted.relativePath;
+    if (!relative || !relative.split(path.sep).every(component => /^[a-z0-9._-]+$/.test(component) && !component.endsWith(".")))
+        throw unsupportedSpelling();
+    return {
+        path: admitted.path,
+        // Case-folded or rebased root spellings keep the full resolver and its
+        // existing root-identity admission at every mutation.
+        missing: admitted.admission === "exact" && admitted.path === effective ? missingHint : undefined,
+    };
+}
+// The hint stores only a location. Each call freshly binds the nearest existing
+// prefix and its first absent child; no identity or authorization crosses calls.
+function observeMissingDestination(hint) {
+    // A complete parent needs only the ordinary leaf check, not a prefix fence.
+    if (hint.parts.length - hint.nextIndex < 2)
+        return undefined;
+    try {
+        let parentPath = hint.parentPath;
+        let parent = inspectDirectoryIdentitySync(parentPath);
+        for (let nextIndex = hint.nextIndex; nextIndex < hint.parts.length; nextIndex++) {
+            const childPath = path.join(parentPath, hint.parts[nextIndex]);
+            let child;
+            try {
+                child = fs.lstatSync(childPath, { bigint: true });
+            }
+            catch (error) {
+                if (!hasNodeErrorCode(error, "ENOENT"))
+                    return undefined;
+                if (realpathSync.native(parentPath) !== parentPath)
+                    return undefined;
+                inspectDirectoryIdentitySync(parentPath, parent);
+                try {
+                    fs.lstatSync(childPath);
+                }
+                catch (error) {
+                    if (!hasNodeErrorCode(error, "ENOENT"))
+                        return undefined;
+                    // Absence can follow a renamed ancestor through a new alias while
+                    // preserving the directory's identity. Finish at its current name.
+                    if (realpathSync.native(parentPath) !== parentPath)
+                        return undefined;
+                    return Object.freeze({ parentPath, parts: hint.parts, nextIndex });
+                }
+                return undefined;
+            }
+            // An existing leaf always receives the historical full resolution,
+            // including final links, collisions and unsupported canonical spellings.
+            if (nextIndex === hint.parts.length - 1)
+                return undefined;
+            parent = inspectDirectoryIdentitySync(childPath, undefined, child);
+            parentPath = childPath;
+        }
+    }
+    catch {
+        // Removal, redirection and uncertain observations only discard the hint.
+        // The full resolver below still determines the destination and error.
+    }
+    return undefined;
+}
+export function assertRootFallbackWritePath(expected, actual) {
+    if (expected !== undefined && actual !== expected) {
+        throw new FsSafeError("path-mismatch", "compatibility write destination changed after lock selection");
+    }
+}
+export function createRootWriteLockBinding(params) {
+    const { rootPath } = params;
+    const rootIdentity = params.rootIdentity && Object.freeze({
+        dev: params.rootIdentity.dev, ino: params.rootIdentity.ino,
+    });
+    const selected = effectiveDestination(rootPath, params.targetPath, rootIdentity);
+    const targetPath = selected.path;
+    let missingHint = selected.missing;
+    const relativePath = path.relative(rootPath, targetPath);
+    let active = true;
+    const assertCurrent = () => {
+        if (!active)
+            throw new FsSafeError("path-mismatch", "compatibility lock observation expired");
+        const observed = missingHint && observeMissingDestination(missingHint);
+        if (observed) {
+            missingHint = observed;
+            return;
+        }
+        missingHint = undefined;
+        const current = effectiveDestination(rootPath, targetPath, rootIdentity);
+        assertRootFallbackWritePath(targetPath, current.path);
+        missingHint = current.missing;
+    };
+    // Only this library-owned, observation-only closure permits parent reuse.
+    // Callers cannot obtain that status by setting properties on their callback.
+    lockObservations.set(assertCurrent, Object.freeze({ rootPath, targetPath }));
+    return Object.freeze({
+        targetPath,
+        relativePath,
+        // The existing lock protocol uses slashes; the writer needs native spelling.
+        relativeLockPath: relativePath.split(path.sep).join("/"),
+        assertCurrent,
+        dispose() {
+            active = false;
+            missingHint = undefined;
+            lockObservations.delete(assertCurrent);
+        },
+    });
+}

package/node_modules/@openclaw/fs-safe/dist/root-write-mode.d.ts

@@ -0,0 +1,7 @@
+import { type RootBoundaryIdentity } from "./root-boundary.js";
+export declare function inheritWriteTargetMode(params: {
+    targetPath: string;
+    rootWithSep: string;
+    rootIdentity?: RootBoundaryIdentity;
+    requestedMode?: number;
+}): Promise<number>;

package/node_modules/@openclaw/fs-safe/dist/root-write-mode.js

@@ -0,0 +1,72 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
+import { isNotFoundPathError } from "./path.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { realpathSync } from "./realpath.js";
+import { hardlinkedPathNotAllowedError, outsideWorkspaceError } from "./root-errors.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+// The caller has already resolved and guarded this write target.
+export async function inheritWriteTargetMode(params) {
+    try {
+        const admittedTarget = admitPathInsideRoot({
+            rootPath: params.rootWithSep,
+            candidatePath: params.targetPath,
+            rootIdentity: params.rootIdentity,
+        });
+        if (!admittedTarget)
+            throw outsideWorkspaceError();
+        const targetPath = admittedTarget.path;
+        const existing = await inspectFileIdentity(() => fsSync.lstatSync(targetPath, { bigint: true }));
+        if (existing.isSymbolicLink())
+            throw new FsSafeError("path-alias", "path alias escape blocked");
+        if (!existing.isFile())
+            throw new FsSafeError("not-file", "not a file");
+        if (existing.nlink > 1n)
+            throw hardlinkedPathNotAllowedError();
+        // Preserve read-open admission of the pre-existing destination. access(2)
+        // is not equivalent: it ignores ACLs on Windows and capabilities on Linux.
+        const handle = await fs.open(targetPath, resolveReadOpenFlags());
+        try {
+            // Bind admission to the inode whose metadata is inherited.
+            await inspectFileIdentity(() => fsSync.fstatSync(handle.fd, { bigint: true }), existing);
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+        }
+        try {
+            // A parent can change after guarded resolution. Do not inherit metadata
+            // from an outside inode, even if the parent is restored before publication.
+            const observedRealPath = realpathSync.native(targetPath);
+            const admittedRealPath = admitPathInsideRoot({
+                rootPath: params.rootWithSep,
+                candidatePath: observedRealPath,
+                rootIdentity: params.rootIdentity,
+            });
+            if (!admittedRealPath)
+                throw outsideWorkspaceError();
+            const realPath = admittedRealPath.path;
+            await inspectFileIdentity(async () => {
+                const current = fsSync.statSync(realPath, { bigint: true });
+                if (!current.isFile())
+                    throw new FsSafeError("not-file", "not a file");
+                if (current.nlink > 1n)
+                    throw hardlinkedPathNotAllowedError();
+                return current;
+            }, existing);
+        }
+        catch (error) {
+            if (isNotFoundPathError(error)) {
+                throw new FsSafeError("path-mismatch", "write target changed during mode inheritance", { cause: error });
+            }
+            throw error;
+        }
+        return params.requestedMode ?? Number(existing.mode & 511n);
+    }
+    catch (error) {
+        if (!isNotFoundPathError(error))
+            throw error;
+        return params.requestedMode ?? 0o600;
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/root-write-publication.d.ts

@@ -0,0 +1,23 @@
+import { type BigIntStats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import type { AnyAsyncDirectoryGuard } from "./directory-guard.js";
+import type { RootContext } from "./root-context.js";
+import type { RootWriteOptions } from "./root-options.js";
+export declare function finishRootFallbackWrite(params: {
+    root: RootContext;
+    targetPath: string;
+    handle: FileHandle;
+    identity: BigIntStats;
+    parentGuard: AnyAsyncDirectoryGuard;
+    mode: number;
+    options: RootWriteOptions & {
+        data: string | Buffer;
+    };
+    openForCompatibility: () => Promise<{
+        opened: {
+            handle: FileHandle;
+        };
+        identity: BigIntStats;
+    }>;
+    onVerificationFailure: (error: unknown) => void;
+}): Promise<void>;

package/node_modules/@openclaw/fs-safe/dist/root-write-publication.js

@@ -0,0 +1,85 @@
+import fsSync, {} from "node:fs";
+import path from "node:path";
+import { readFileHandleBounded } from "./bounded-read.js";
+import { syncDirectoryBestEffort } from "./directory-durability.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup, sha256Hex } from "./file-identity.js";
+import { cleanupPinnedFilePath } from "./file-cleanup.js";
+import { verifyAtomicWriteResult } from "./root-write-verification.js";
+// Compatibility callers hold the lock throughout this operation. The caller
+// owns the original write handle; this helper owns a content-verified reopen.
+export async function finishRootFallbackWrite(params) {
+    let handle = params.handle;
+    let identity = params.identity;
+    let accepted;
+    const compatibility = params.options.renameIdentity === "verify-content-with-lock";
+    const verify = async () => {
+        try {
+            await verifyAtomicWriteResult({
+                root: params.root, targetPath: params.targetPath, fd: handle.fd,
+                expectedIdentity: identity, parentGuard: params.parentGuard,
+            });
+        }
+        catch (error) {
+            params.onVerificationFailure(error);
+            throw error;
+        }
+    };
+    try {
+        if (compatibility) {
+            const current = fsSync.lstatSync(params.targetPath, { bigint: true });
+            if (current.isSymbolicLink() || !current.isFile()) {
+                throw new FsSafeError("path-mismatch", "fallback target changed during write");
+            }
+            if (process.platform === "win32" && (current.dev === 0n || current.ino === 0n)) {
+                // Opaque pathname stats are not evidence of rename identity drift. The
+                // strict verifier can reopen against the retained descriptor's exact
+                // identity without reading bytes; a different object must still fail.
+                await verify();
+            }
+            else if (!sameFileIdentityForCleanup(current, identity)) {
+                const opened = await params.openForCompatibility();
+                accepted = handle = opened.opened.handle;
+                identity = opened.identity;
+                // Admit the destination under the retained Root and parent before any
+                // read, chmod, or sync; the original temp no longer proves its identity.
+                await verify();
+                const data = params.options.data;
+                const expectedBytes = typeof data === "string"
+                    ? Buffer.byteLength(data, params.options.encoding ?? "utf8") : data.byteLength;
+                const content = await readFileHandleBounded(handle, expectedBytes).catch((error) => {
+                    if (error instanceof FsSafeError && error.code === "too-large") {
+                        throw new FsSafeError("path-mismatch", "fallback target changed during write", { cause: error });
+                    }
+                    throw error;
+                });
+                if (sha256Hex(content) !== sha256Hex(data, params.options.encoding)) {
+                    throw new FsSafeError("path-mismatch", "fallback target changed during write");
+                }
+                await verify();
+            }
+        }
+        // Final mode belongs to the accepted object, including on rename-unstable
+        // filesystems; never chmod the old temp and assume its mode was transferred.
+        try {
+            await handle.chmod(params.mode);
+        }
+        catch (error) {
+            await cleanupPinnedFilePath({
+                pathname: params.targetPath, handle, identity, parentGuard: params.parentGuard,
+            });
+            throw error;
+        }
+        if (params.options.durable !== false)
+            await handle.sync();
+        await verify();
+        if (params.options.durable !== false) {
+            await syncDirectoryBestEffort(path.dirname(params.targetPath));
+            if (compatibility)
+                await verify();
+        }
+    }
+    finally {
+        await accepted?.close().catch(() => undefined);
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/root-write-verification.d.ts

@@ -0,0 +1,11 @@
+import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
+import type { PublishedWriteIdentity } from "./pinned-write-types.js";
+import { type RootContext } from "./root-context.js";
+export declare function verifyAtomicWriteResult(params: {
+    root: RootContext;
+    targetPath: string;
+    fd: number;
+    expectedIdentity: PublishedWriteIdentity;
+    expectedMode?: number;
+    parentGuard: AnyAsyncDirectoryGuard;
+}): Promise<void>;

package/node_modules/@openclaw/fs-safe/dist/root-write-verification.js

@@ -0,0 +1,95 @@
+import fsSync, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import { assertAsyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { resolveOpenedFileRealPathForFd } from "./opened-realpath.js";
+import { assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isSymlinkOpenError } from "./path.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { assertRootIdentityCurrent } from "./root-context.js";
+import { fileNotFoundError, hardlinkedPathNotAllowedError, outsideWorkspaceError } from "./root-errors.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+export async function verifyAtomicWriteResult(params) {
+    let needsPathOpen = false;
+    const assertFile = (stat) => {
+        if (stat.isSymbolicLink()) {
+            throw new FsSafeError("symlink", "symlink not allowed");
+        }
+        if (!stat.isFile()) {
+            throw new FsSafeError("not-file", "not a file");
+        }
+        if (!sameFileIdentity(stat, params.expectedIdentity)) {
+            throw new FsSafeError("path-mismatch", "path changed during write");
+        }
+        if (stat.nlink > 1) {
+            throw hardlinkedPathNotAllowedError();
+        }
+    };
+    const assertPath = (stat) => {
+        assertFile(stat);
+        needsPathOpen ||= process.platform === "win32" && (stat.dev === 0n || stat.ino === 0n);
+    };
+    const assertDescriptor = (fd = params.fd) => {
+        const stat = fsSync.fstatSync(fd, { bigint: true });
+        // Only Windows pathname stats may have unknown identity; fd stats must match exactly.
+        if (params.expectedIdentity.dev !== stat.dev || params.expectedIdentity.ino !== stat.ino) {
+            throw new FsSafeError("path-mismatch", "descriptor changed during write");
+        }
+        assertFile(stat);
+        if (process.platform !== "win32" && params.expectedMode !== undefined) {
+            const actualMode = Number(stat.mode & 4095n);
+            if (actualMode !== params.expectedMode) {
+                throw new Error(`Private secret file ${params.targetPath} has insecure permissions ${actualMode.toString(8)}.`);
+            }
+        }
+        return stat;
+    };
+    try {
+        let opened;
+        try {
+            while (true) {
+                // The original descriptor remains borrowed; only a verification reopen is owned here.
+                const fd = opened?.fd ?? params.fd;
+                const stat = assertDescriptor(fd);
+                assertPath(fsSync.lstatSync(params.targetPath, { bigint: true }));
+                const { realPath, stat: resolvedStat } = await resolveOpenedFileRealPathForFd(fd, stat, params.targetPath);
+                // Consume the resolver's observation only in this pass; the checks after
+                // the directory guards must still sample the current path and descriptor.
+                assertPath(resolvedStat);
+                if (!admitPathInsideRoot({
+                    rootPath: params.root.rootReal,
+                    candidatePath: realPath,
+                    rootIdentity: params.root.rootIdentity,
+                })) {
+                    throw outsideWorkspaceError();
+                }
+                await assertAsyncDirectoryGuard(params.parentGuard);
+                await assertRootIdentityCurrent(params.root);
+                // Recheck after canonical resolution and directory checks, including late links.
+                assertPath(fsSync.lstatSync(params.targetPath, { bigint: true }));
+                assertDescriptor(fd);
+                if (opened || !needsPathOpen)
+                    break;
+                // Opaque Windows pathname identity needs one independent, read-free reopen.
+                assertNoUnsafeDeviceReadPath(params.targetPath);
+                opened = await fs.open(params.targetPath, resolveReadOpenFlags()).catch((error) => {
+                    if (isSymlinkOpenError(error)) {
+                        throw new FsSafeError("symlink", "symlink open blocked", { cause: error });
+                    }
+                    if (hasNodeErrorCode(error, "EISDIR"))
+                        throw new FsSafeError("not-file", "not a file");
+                    throw error;
+                });
+            }
+        }
+        finally {
+            if (opened)
+                await opened.close().catch(() => undefined);
+        }
+    }
+    catch (error) {
+        if (isNotFoundPathError(error))
+            throw fileNotFoundError();
+        throw error;
+    }
+}

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

@@ -0,0 +1,2 @@
+export { DEFAULT_ROOT_MAX_BYTES, openLocalFileSafely, readLocalFileSafely, resolveOpenedFileRealPathForHandle, root, type Root, } from "./root-impl.js";
+export type * from "./root-public-types.js";

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

@@ -0,0 +1 @@
+export { DEFAULT_ROOT_MAX_BYTES, openLocalFileSafely, readLocalFileSafely, resolveOpenedFileRealPathForHandle, root, } from "./root-impl.js";